Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
Executor instructions: Read 086-rewrite-programme.md and AGENTS.md first. Five phases, each one PR. Phases 0 and 1 touch no bake module and can go at once; phases 2 to 4 edit bake modules and wait for the maintainer's word on when (see "The cost nobody sees"). Run every Verify before the next phase; on a STOP condition, stop and report. Update this plan's row in
docs/plans/README.mdafter each phase.Drift check (run first):
git diff --stat 5dfa300d..HEAD -- pipeline/pyproject.toml pipeline/uv.lock pipeline/bake/common.py pipeline/bake/step_cache.py .github/workflows/ci.yml package.json— and run the checker again (below): the counts in Current state are of5dfa300d.
Status
- Priority: P2 — cheap to start, and what plan 092 stands on
- Effort: M (phases 0–1: S)
- Risk: LOW for the gate; MED for the fixes, each of which re-runs bake steps on the maintainer's machine
- Depends on: none. Needed by 092.
- Category: rewrite — less complexity (contracts that are checked, not remembered); beside the aims: a re-bake that fails before it runs, not hours in
- Series: 086-rewrite-programme.md
- Planned at: commit
5dfa300d, 2026-11-16 - Status: TODO
Why this matters
pipeline/bake/ is 41 757 lines of Python in 83 files, and nothing
checks its types. 1 696 of its 2 031 functions state a return type, so
the intent is written down — and unread: CI's pipeline job runs pytest
and ruff. A bake step runs for minutes to hours on raw data only the
maintainer's machine holds, so a None that arrives where a geometry
was expected is found late and far from its cause. Plan 092 will rewrite
the input and output of every step (site-wide typed tables in place of a
file per tile); doing that to unchecked code would trade one drift for
another.
Current state
Measured on 2026-11-16 at 5dfa300d with pyright 1.1.414 in its default
mode, Python 3.13 (cd pipeline && uv sync --locked && pyright --pythonpath .venv/bin/python --outputjson bake): 593 errors in 56 of
83 files, 27 files clean. By what they are:
| Class | Findings | What it is |
|---|---|---|
| The bakes' own annotation | 184 | 229 uses of shapely.Geometry in 35 modules (def carriageways(tile: Tile) -> list[shapely.Geometry], ways.py). In the stubs the checker has for shapely that is the bare base class without area, buffer, is_empty, geom_type; the class meant is shapely.geometry.base.BaseGeometry. Most asked: geom_type 29, area 25, is_empty 14, length 14, buffer 12, interpolate 12, exterior 9 |
None not handled | 67 | reportOptionalMemberAccess 29, reportOptionalSubscript 13, reportOptionalOperand 7, "None is not iterable" 18 — p.text.split() on an XML element (citygml.py), tile.tree_cadastre.credit (cadastre.py), bridge.py, rail.py, cultivated.py |
| Possibly unbound | 15 | a name bound in one branch and read after it: roofs.py (lab, faces, surface, drawn), facades.py (ws), lsc.py, facade_measure.py |
| A library without types | 93 | labels, n = ndi.label(mask) 60 (scipy's partial stubs); rasterio.transform, pyogrio.raw "not a known attribute of module" 16; laspy's array views 12; from scipy.spatial import cKDTree 5 |
| Calls | 52 | "no overloads match" 32 (numpy), a wrong count of positional arguments 20 (_moved(mask, *moves[k], 0, res) in dormers.py: a star over a tuple of unknown length; Window(c0, r0, …) of rasterio) |
| What follows from the rows above | 182 | reportArgumentType 119, reportOperatorIssue 29, the rest of reportAttributeAccessIssue 16, reportReturnType 9, reportIndexIssue 5, reportAssignmentType 4 — mostly numpy unions grown from an untyped call upstream |
Most findings: roofs.py 56, furniture.py 43, water.py 36,
roof_planes.py 34, dormers.py 33, lowveg.py 32. The modules plan
092 rewrites are nearly clean already: common.py 4, osm.py 1,
osm_index.py 6, spec.py 1, citygml.py 6, and none in
step_cache.py, rasters.py, fetch.py, net.py, __main__.py.
Which libraries ship types (looked up in pipeline/.venv, 2026-11-16):
numpy, pyproj, Pillow and scikit-image do (py.typed); shapely,
rasterio, pyogrio, networkx and onnxruntime do not; scipy and laspy
ship a few .pyi files. For shapely the checker brings stubs of its
own, so a new version of the checker can move the counts.
The files that matter:
pipeline/pyproject.toml— the dependencies, pinned exactly; the dev group is["pytest==9.2.0", "ruff==0.17.3"]; ruff's rules areE,F,I,B,UP,SIM. No checker's section yet..github/workflows/ci.yml, jobpipeline:uv sync --locked,uv run pytest -q tests,uv run ruff check .,uv run ruff format --check ..package.json'stest:pipelineruns the same three.pipeline/bake/common.py— what every step reads and writes with:Tile,read_layer(returnstuple[np.ndarray, dict[str, np.ndarray]]),feature(geometry: dict, properties: dict | None) -> dict,write_geojson(path, features: list[dict], epsg, …),geometry_json,table_json,save_grey_png. A handed-over file's shape is a dict literal here and a zod schema inlib/city/<name>-file.ts(ADR 0059).pipeline/bake/step_cache.py—code_hash(module)hashes the bytes of the step's module and of every bake module it reaches, andlocked_runtime(uv.lock): the lockfile's lines for the project's dependencies and what they depend on, "not the dev group — a new ruff or pytest bakes nothing differently" (tests/test_step_cache.py,test_the_locked_runtime_is_what_a_bake_runs_with).- Today's escapes in
bake/: 5type: ignore, 2cast(.
The cost nobody sees
Because code_hash hashes a module's bytes, an annotation is a code
change to the step cache. Replacing shapely.Geometry in common.py
re-keys every step of every tile of every site: the next bun run bake
runs them all again, on the maintainer's machine, from raw downloads
some of which were not reachable at the last re-bake (plan 022's row:
GeoSN's laser scan). A checker in the dev group, its settings in
pyproject.toml, a script outside bake/ and stub files re-key
nothing.
Commands you will need
| Purpose | Command | Expected |
|---|---|---|
| Environment | cd pipeline && uv sync --locked | .venv/ (git-ignored) |
| Python tests | bun run test:pipeline | pytest and ruff pass |
| The checker, as measured | cd pipeline && pyright --pythonpath .venv/bin/python --outputjson bake | JSON, summary.errorCount |
| A re-bake of one tile | bun run bake dresden 33412_5656_2_sn | needs the raw data: the maintainer's machine |
| TypeScript gate | bun run verify | passes (only package.json and docs change on that side) |
Scope
In scope: pipeline/pyproject.toml, pipeline/uv.lock,
pipeline/typecheck.py and pipeline/typecheck-baseline.json (new),
pipeline/typings/ (new, stubs), pipeline/tests/test_typecheck.py
(new), pipeline/bake/**/*.py (phases 2–4 only),
.github/workflows/ci.yml (the pipeline job), package.json
(test:pipeline), AGENTS.md (the Commands block),
docs/data-pipeline.md (the paragraph on pipeline/tests/).
Out of scope
pipeline/tests/under the checker — the bakes first; say so in the settings (include = ["bake"]).- What a step computes. A fix that changes a written file is a STOP.
pipeline/bake/step_cache.py's key (see decision B below).- A typed record for each handed-over file: 40 hand-written
TypedDicts would be a fourth copy of each shape. Plan 092 derives them from the one schema. - Stricter modes (
strict, unknown-type reports): after the baseline is empty, not before.
Phases
Phase 0 — choose the checker, pin it, prove it re-keys nothing
- Decision A (executor, with a note to the maintainer). The
baseline above was measured with pyright. Before pinning it, try
what is current: a checker must run under
uv runfrom an exact pin in the dev group, on CI's runner as it is (pyright's Python package fetches a Node program when first run — check that thepipelinejob needs no new set-up step and no download at run time, or name the alternative that does not), print machine-readable findings, and know shapely. Run each candidate once overbake/and put its count, its time and what it needs into Findings. Without a reason against it, take the one measured here. - Add it to
[dependency-groups] devwith an exact pin, its settings topyproject.toml(include = ["bake"], the Python version the lower bound ofrequires-python, the environment.venv, the stub pathtypings). - Prove the claim of "The cost nobody sees": with the new
uv.lock,step_cache.locked_runtimereturns what it returned before.
Verify: cd pipeline && uv run pytest -q tests/test_step_cache.py
passes; with the lockfile of before saved to a scratch file (git show HEAD:pipeline/uv.lock > "$TMPDIR/uv.lock.before"), uv run python -c "import os; from bake import step_cache as s; print(s.locked_runtime(open(os.environ['TMPDIR'] + '/uv.lock.before').read()) == s.locked_runtime(s.LOCK.read_text()))" prints True; git diff --stat -- pipeline/bake is empty.
Phase 1 — the baseline and the gate
pipeline/typecheck.py(outsidebake/, so no step's closure reaches it): runs the checker with JSON output, folds the findings to{file: {rule: count}}— no line numbers, so an edit above a finding moves nothing — and compares withpipeline/typecheck-baseline.json:- a count above the baseline, or a file or rule the baseline lacks: exit 1, listing the new findings with their lines;
- a count below it: exit 1 too, "the baseline is stale — run
uv run python typecheck.py --update";--updatewrites the file and refuses to raise any count; - it also counts
type: ignoreandcast(inbake/and holds them at today's 5 and 2. The checker has no baseline of its own that can be trusted to stay; this file is ours, and the comparison is a pure function with a test.
- CI: one more line in the
pipelinejob,uv run python typecheck.py; the same inpackage.json'stest:pipeline. AGENTS.md's Commands block sayspytest + ruff + types. docs/data-pipeline.mdsays in itspipeline/tests/paragraph that the bakes are type-checked against a baseline and how to lower it.
Verify: bun run test:pipeline passes; a scratch edit that adds
x: int = None to bake/classes.py fails it with that line; the
baseline's counts sum to what the checker reports; git diff --stat -- pipeline/bake is empty.
Phase 2 — stubs for what the libraries lack (still no bake edit)
Stub files change no module's bytes, so do them first.
pipeline/typings/scipy/ndimage.pyi(or the narrowest file the checker accepts):labelreturnstuple[NDArray[np.int32], int]for the call the bakes make — 60 findings.rasterio: the surface the bakes use and no more (open,transform.xy,windows.Window,features.rasterize, …: list it fromgrep -rhoE "rasterio\.[a-z_.A-Z]+" pipeline/bake | sort -u);pyogrio.raw.read; laspy's views as the arrays they behave as.- Run phase 1's
--updateand commit the lower baseline.
Verify: uv run python typecheck.py passes; the baseline no longer
has an entry for "is not iterable" on Literal[…] nor for an unknown
attribute of a module; git diff --stat -- pipeline/bake is empty.
Decision B (maintainer) — when the bake modules may be edited
Phases 3 and 4 re-key the step cache. Three ways; pick one and write it into Findings:
- With plan 092's re-bake (recommended in the series). 092 re-bakes every site anyway. Phases 3 and 4 are prepared as a stack of PRs and merged in the days before that re-bake; nothing is baked twice.
- Now, and pay. Merge, re-bake the affected steps, and take the
proof that comes with it: a re-bake after an edit that changed no
behaviour writes no file anew (
git status data/is clean; under plan 088, the source set's hash is the old one). - Teach the cache. Make
code_hashhash what a module does (its syntax tree without annotations, comments and docstrings) and bumpVERSION. It changes what the cache trusts, costs one full re-key itself, and belongs in a PR and a test of its own. Not without the maintainer's word.
Phase 3 — the bakes' own annotations
- One name for "a geometry" in
bake/common.py(an alias ofshapely.geometry.base.BaseGeometry), and the 229 uses ofshapely.Geometryin annotations take it (every use is an annotation: none constructs or tests one). Where a function needs what only one kind has (exterior9 findings,geoms7), say the real class in the signature, or narrow once at the top where another kind really can arrive (if not isinstance(g, Polygon): return …; the bakes already writeif g is not None and not g.is_empty). --updatethe baseline.
Verify: uv run python typecheck.py passes; grep -rc "shapely\.Geometry" pipeline/bake | awk -F: '{s+=$2} END {print s}'
prints 0; uv run pytest -q tests and ruff pass; per decision B, one
tile re-baked shows no changed file.
Phase 4 — the findings that are real
In this order, a module a PR where it helps review (roofs.py,
furniture.py, water.py are the largest):
None(67). For each: can it beNonehere? If the code above rules it out, say so where it is ruled out (return early, or raise with the file and the tile in the message — the bakes fail loudly, plan 063). If it can, that is a defect: write the pytest that reaches it first, then the fix.- Possibly unbound (15): bind before the branch or return in it.
- Calls (20 wrong counts, 32 overloads) and the 182 that follow: re-run after steps 1–2 and the stubs; fix what is ours (a star over a tuple: give the tuple its length in its type); a numpy overload that is right at run time and wrong in numpy's types stays in the baseline with one line in Findings per kind.
- Never silence: no new
type: ignore, nocast(phase 1 counts them).
Verify: uv run python typecheck.py passes; the baseline has no
entry for reportOptionalMemberAccess, reportOptionalSubscript,
reportOptionalOperand or reportPossiblyUnboundVariable;
common.py, osm.py, osm_index.py, spec.py, citygml.py,
rasters.py, fetch.py, net.py, step_cache.py and __main__.py
have no entry at all; every defect found has its test.
Test plan
pipeline/tests/test_typecheck.py(new): the comparison alone — a raised count fails and names the file and rule; a lowered one fails as stale;--updatelowers and never raises; an unknown rule in the findings is a failure, not a pass. Pattern:pipeline/tests/test_step_cache.py(pure functions on literal inputs, no bake run).- Every defect of phase 4 step 1: a test in the module's existing test
file that reaches the
None. - No test runs the checker itself; CI does.
Done criteria
-
bun run test:pipelineruns the checker and passes -
pipeline/typecheck-baseline.jsonhas noreportOptional*and noreportPossiblyUnboundVariableentry, and none for the ten modules named in phase 4's Verify -
grep -rc "type: ignore" pipeline/bake | awk -F: '{s+=$2} END {print s}'prints at most 5 -
locked_runtimeis unchanged by the checker's pin (test_step_cache.pypasses) - decision B is recorded, and what was re-baked after phases 3–4 wrote no changed file
-
docs/plans/README.md: this plan's row updated, with the baseline's total before and after
STOP conditions
- The checker cannot run in CI's
pipelinejob without a new set-up step or a download at run time, and no candidate can. - Adding it changes
locked_runtime's text (every step would re-run). - A fix changes a file a step writes. The plan is types, not behaviour: report the difference and the tile.
- More than a handful of the 67
Nonefindings turn out to be real defects in files already published: stop and list them — that is a finding about the data, and the maintainer decides what to re-bake. - A phase can only pass by raising a count in the baseline.
Maintenance notes
- A bump of the checker can move counts in either direction (its
shapely stubs travel with it): bump it in a PR of its own and
--updatethere, saying which rule moved. - A bump of shapely, rasterio or pyogrio: check
typings/against the calls the bakes make. - New bake modules start clean: a file the baseline does not name may have no finding.
- When the baseline is empty, delete it and the comparison, and let the checker's exit code be the gate.
What the series changes about this plan
Built alone, this plan would finish its fixes whenever they are ready and pay a re-bake for each batch. In the series:
- Plan 092 rewrites every step's input and output. It needs phase 4's
ten modules clean first (they are the readers and writers), and it
— not this plan — gives each handed-over file its Python type, from
the one schema both languages read. So this plan stops at the
writers' signatures and writes no
TypedDictby hand. - 092's full re-bake is the window for phases 3 and 4 (decision B): 086 puts this plan beside 088, early; only phases 0–2 go then.
- Plan 088 moves the bakes' outputs out of git. After it, "wrote no
changed file" is read from the source set's hash, not from
git status.
Findings
(empty — phase 0 writes the checker's choice here, decision B after it)
