chore(lint): static guards for the five recurring review-reject classes

[lmeyerov]

What

Five defect classes that reviewers keep rejecting by hand are now checked statically, in the existing lint lane. No new workflow, no new job, no production code changed.

• bin/ci_type_hygiene_guard.py — stdlib-only AST pass over graphistry/ (tests excluded, matching mypy.ini), invoked from bin/lint.sh, so it runs in python-lint-types on py3.8–3.14. ~1.4 s, byte-identical counts on all seven interpreters (verified).
• bin/ci_type_hygiene_baseline.json — the per-file ratchet.
• pyproject.toml — ruff B009/B010 promoted to errors, today's offenders seeded into per-file-ignores.
• DEVELOP.md — conventions + escape hatch. CHANGELOG.md — entry.

Measured first

Counts on master b6181d35, graphistry/ excluding graphistry/tests (same exclusion mypy.ini already uses; including tests would add ~5,000 missing-annotation findings from throwaway fixtures):

Class	Check	Findings	Files	Enforcement
1 missing contracts	missing-annotations	1704	79	ratchet
3a Any	explicit-any	1605	117	ratchet
3b cast()	explicit-cast	959	81	ratchet
4 bare generics	bare-generic	209	48	ratchet
2 dynamic attr write	plottable-setattr	3	3	effectively a hard rule
2 direct attr write	plottable-attr-write	39	5	effectively a hard rule
5 str vs Literal	vocab-str-param	42	21	narrow ratchet
2 constant-name attr	ruff B009/B010	31	14	error today, seeded per-file-ignores

Ratchet

Per-file count baseline: a file may not gain findings, and a file absent from the baseline must have zero. So new files are fully enforced, and new untyped functions inside existing files are caught too — which per-file-ignores alone would not do.

changed-files-only was considered and rejected: python-lint-types checks out at fetch-depth: 1, so no merge-base is available in that job, and I cannot author workflows to change it.

Escape hatch is # hygiene-ok: <check> -- <reason> on the line, not raising a cap via --update-baseline.

Class 2 targets the hazard, not the syntax

A blanket getattr/setattr ban was measured and rejected: 300 non-test getattr sites, overwhelmingly legitimate optional-attribute reads. The #1825 leak (setattr cache onto the caller's Plottable keyed by id(), returning a stale answer after in-place mutation) requires a write, so only writes onto a parameter annotated as a Plottable are flagged:

• plottable-setattr — 3 sites. One is gfql_fast_paths.py:514, i.e. GFQL: two-hop count returns a STALE answer after in-place frame mutation (degree-count memo setattrs onto the caller's Plottable, keyed by id() — the BLOCKER-1 pattern the same file forbids) #1825 itself; one is gfql_unified.py:1571; one is cluster.py:190 (legitimate, dynamic name on a fresh copy).
• plottable-attr-write — 39 sites, the param.attr = ... form the same hazard takes when nobody writes setattr. Without this the setattr rule is one keystroke from being bypassed.

Ruff B009/B010 additionally reject the constant-name forms outright; 31 offenders across 14 files are seeded and retire with ruff check --fix --select B009,B010 <file>.

Class 5 is deliberately narrow

There is no honest general rule for "this str should be a Literal". I prototyped the obvious one — a str parameter compared against a small closed set of literals in its own body — and measured it: 44 hits at roughly 80% precision. The false positives are exactly the owner's carve-out (_alias_key(column: str), __getattr__(name: str), _is_bool_literal(text: str), _coerce_value(attr_type: str) reading arbitrary GEXF). Not shipped.

What ships instead is a hard-coded registry of six parameter names whose vocabularies this repo has already committed to as Literal aliases (table, kind, direction, how, mode, engine) — 42 sites, ratcheted. It is a floor, not a full check; reviewers still own the general case.

What this will NOT catch

• Wrong annotations. Every check is presence/shape only — def f(x: str) -> str where x is really a DataFrame is invisible.
• Annotation churn inside a baselined file: delete one untyped function, add another, count unchanged.
• Any reached through a type alias or an unparameterized import; only the literal Any token in an annotation is seen.
• Plottable writes through a local alias (h = g; h._x = 1) or a non-Plottable-annotated / unannotated parameter. The rule keys on the annotation, which is why it is precise; that precision is also its blind spot.
• Class 5 at large — see above.
• The baseline can rot: shrinkage only warns by default. --strict lists files that improved so caps can be retightened deliberately.

Not done, on purpose

No mypy.ini strictness flags. disallow_untyped_defs / disallow_any_explicit / disallow_any_generics are per-module all-or-nothing, and with 79–117 dirty modules the exemption list would be ~the whole package, with no way to express "no worse than today". The AST guard gives per-file granularity in the same lane at ~1.4 s.

Verification

• ./bin/lint.sh green end to end (ruff + guard + relative-import check), exit 0.
• Guard verified to fire on a synthetic file for all 7 checks, and # hygiene-ok verified to suppress.
• B009/B010 verified to fire on new code despite the seeded ignores.
• Counts confirmed identical on py3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14.

Please do not merge without owner review — the baseline encodes a policy decision about what is grandfathered.