diff --git a/CLAUDE.md b/CLAUDE.md index cbb1e00..d00371d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,8 +61,9 @@ npm run assistant:streaming # src/assistant-streaming.ts — Part 10.3/1 npm run models # src/models.ts — lists model IDs available to the API key ``` -The Python half runs the same lessons through `uv`, from the **repo root**, not -from inside `pyweather/`: +The Python half runs the same lessons through `uv`, and — unlike the npm +scripts above — from any directory inside the repo: `pyweather/` resolves +both the ledger and `.env` from its own location on disk, not from cwd. ```bash npm run typecheck:py # pyright, strict — run this after any pyweather/ edit @@ -200,12 +201,29 @@ with `404 not_found_error`, or pricing looks off, run `npm run models` to check what the live API actually returns rather than trusting this repo or the tutorial document. -**`verify:docs` covers both documents.** `scripts/check-docs.ts` holds a -`LANGUAGES` table: everything language-specific (fence names, marker comment -syntax, comment stripping, how to typecheck, which directory) lives there, and -the four gates — compile, ordering, diff, coverage — are shared. Adding a third -language means adding a row, not a branch. Note the Python comment stripper +**`verify:docs` covers both documents.** `scripts/check-docs.ts` runs six +gates: two repo-wide ones first — structure (every Markdown file's fences +balance and its links resolve) and command parity (every `package.json` +script has a matching `uv run` entry point in `pyproject.toml`, and vice +versa) — then, per document, the four code-coupling gates: compile, ordering, +diff, coverage. A `LANGUAGES` table holds everything language-specific (fence +names, marker comment syntax, comment stripping, how to typecheck, which +directory); the six gates themselves are shared, so adding a third language +means adding a row, not a branch. The command parity gate is why adding an +npm script without a matching `[project.scripts]` entry in `pyproject.toml` +fails `verify:docs` — three scripts are deliberately exempt from that check +(`NPM_ONLY` in `check-docs.ts`): `typecheck`, `typecheck:py`, and +`verify:docs` itself, since they're infrastructure, not lessons, and have no +Python counterpart to pair with. Note the Python comment stripper also drops **docstrings** that sit alone on their own lines, because Python puts its teaching headers in docstrings where TypeScript puts them in `//` comments; without that the document would have to reproduce every docstring verbatim. + +**The stripping is also a blind spot, and it is the one to remember.** Because +comments are removed from *both* sides before the diff gate compares them, a +teaching comment can drift out of step with its listing in the document — or +say something flatly untrue — while all six gates stay green. The comments are +the teaching in this repo, so that is not a small hole: when you edit a comment +in `src/` or `pyweather/`, sync the document's copy by hand, because nothing +else will. diff --git a/docs/setup-mac.md b/docs/setup-mac.md index 5c1ed0b..99f5771 100644 --- a/docs/setup-mac.md +++ b/docs/setup-mac.md @@ -89,7 +89,7 @@ git --version `npm` came with Node. It installs code libraries other people wrote. Git is already on your Mac. -> **Why 20.6 specifically.** That's the release where Node learned to read a `.env` file by itself, via the `--env-file` flag every script in this project uses. On an older Node the scripts start and then fail to find your API key, which looks like a key problem and isn't. +> **Why 20.6 specifically.** That's the release where Node learned to read a `.env` file by itself, via the `--env-file` flag every script that needs a key uses. On an older Node the scripts start and then fail to find your API key, which looks like a key problem and isn't. ## 0.5 Git and GitHub diff --git a/pyproject.toml b/pyproject.toml index da20fb4..297a937 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,10 +2,14 @@ # for one specific reason: usage.csv. # # src/usage.ts writes 'usage.csv' as a RELATIVE path, resolved against the -# process's working directory. npm runs its scripts from the project root, so -# that is where the ledger lands. If the Python lessons ran from inside -# pyweather/, they would quietly create a SECOND usage.csv in there, and the -# whole point of this document — one artifact, two languages — would evaporate. +# process's working directory. That's safe for npm, which always runs its +# scripts from the project root — but `uv run` makes no such promise, so +# pyweather/usage.py can't get away with the same trick. It resolves the +# ledger from `__file__` instead — two directories up from usage.py, which +# lands here, at the repo root, no matter where `uv run` was invoked from. +# Without that, the Python lessons could quietly create a SECOND usage.csv +# wherever you happened to be standing, and the whole point of this document +# — one artifact, two languages — would evaporate. # # Same directory, same file. `uv run agent` and `npm run agent` append to it.