aboutsummaryrefslogtreecommitdiff
path: root/languages/python/CLAUDE.md
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-07-23 20:48:44 -0500
committerCraig Jennings <c@cjennings.net>2026-07-23 20:48:44 -0500
commitc238afbd4150ef53737f16e7dd84a565d2838ecc (patch)
tree588a25dc318cb854c57d8146639d400674baed18 /languages/python/CLAUDE.md
parent10ea44b6de3be1872f7f0bd4501ccf3878105bc4 (diff)
downloadrulesets-c238afbd4150ef53737f16e7dd84a565d2838ecc.tar.gz
rulesets-c238afbd4150ef53737f16e7dd84a565d2838ecc.zip
feat(languages): ship the missing python and typescript hooks
The python and typescript bundles carried rules and a coverage script but no pre-commit hook, so any project installing one got no credential scan on commit. Both now ship all four components the README documents: the shared secret scan, a validate-on-edit hook, settings wiring, and a seed CLAUDE.md. Verified against a real repo: a commit carrying an AWS key is refused. install-lang now warns when a bundle is missing a documented component. That's the half that keeps this from recurring. Whoever adds the sixth bundle will forget something too, and today the installer prints success either way. Two things fell out of the build. node --check is unusable on TypeScript: it ignores --experimental-strip-types, so it rejects valid TS and accepts broken TS. The hook uses tsc filtered to syntactic diagnostics instead. And completing the bundles means every pair now collides on settings.json and pre-commit, so no two compose without FORCE=1. The earlier "bundles already compose" reading rested on these two being incomplete. Filed for a real decision; clock-panel is the project that wants it. Also stamps :LAST_REVIEWED: at task creation, with a lint checker to catch misses. Writing a task is reviewing it, so leaving the stamp off pushed every fresh task to the top of the next review batch to be re-derived by someone with less context than its author had. Tonight's sweep sent the staleness count from 13 to 22 while the list got more accurate.
Diffstat (limited to 'languages/python/CLAUDE.md')
-rw-r--r--languages/python/CLAUDE.md80
1 files changed, 80 insertions, 0 deletions
diff --git a/languages/python/CLAUDE.md b/languages/python/CLAUDE.md
new file mode 100644
index 0000000..a2d0a82
--- /dev/null
+++ b/languages/python/CLAUDE.md
@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+## Project
+
+Python project. Customize this section with your own description, layout,
+and conventions.
+
+**Typical layout:**
+- `src/<package>/` or a top-level package directory — importable code
+- `tests/` — pytest tests mirroring the package layout
+- `pyproject.toml` — dependencies, tool config (ruff, pytest, coverage)
+
+## Build & Test Commands
+
+If the project has a Makefile, document targets here. Common pattern:
+
+```bash
+make test # run the pytest suite
+make test FILE=tests/x.py # one file
+make coverage # suite + coverage report
+make lint # ruff across the tree
+make typecheck # mypy (if the project adopts it)
+make fmt # ruff format / black
+```
+
+Direct equivalents: `python3 -m pytest`, `pytest tests/test_x.py::test_name`,
+`ruff check .`, `ruff format --diff .`, `mypy src/`.
+
+## Language Rules
+
+See rule files in `.claude/rules/`:
+- `python-testing.md` — pytest conventions and fixture discipline
+- `verification.md` — verify-before-claim-done discipline
+
+## Git Workflow
+
+Commit conventions: see `.claude/rules/commits.md` (author identity,
+no AI attribution, message format).
+
+Pre-commit hook in `githooks/` scans for secrets, syntax-checks staged Python,
+and runs `ruff` when it's installed. Activate on a fresh clone with
+`git config core.hooksPath githooks`.
+
+## Problem-Solving Approach
+
+Investigate before fixing. When diagnosing a bug:
+1. Read the relevant module and trace what actually happens
+2. Identify the root cause, not a surface symptom
+3. Write a failing test that captures the correct behavior
+4. Fix, then re-run tests
+
+## Testing Discipline
+
+TDD is the default: write a failing test before any implementation. If you can't
+write the test, you don't yet understand the change. Details in
+`.claude/rules/python-testing.md`.
+
+## Editing Discipline
+
+A PostToolUse hook syntax-checks every Python file after Edit/Write/MultiEdit
+and blocks on a parse error, then runs `ruff` when it's installed. The hook
+covers `.py`, `.pyi`, and extensionless files with a python shebang.
+
+Type checking is not enforced by the hook — it needs the whole package and its
+dependencies resolved, which is a build-scale operation rather than a
+per-keystroke one. Run it via `make typecheck`.
+
+Formatting is likewise not enforced: a project picks its own line length and
+quote style, so blocking on an unconfigured default would impose a contested
+choice. Adopt one per project in `pyproject.toml`.
+
+## What Not to Do
+
+- Don't add features beyond what was asked
+- Don't refactor surrounding code when fixing a bug
+- Don't use a bare `except:` or swallow an exception without handling it
+- Don't use a mutable default argument (`def f(xs=[])`)
+- Don't add comments to code you didn't change
+- Don't commit `.env` files, credentials, or API keys — the pre-commit hook
+ catches common patterns but isn't a substitute for care