gate: cf-import-contract — layering direction under contract

[Antawari]

cf-import-contract — layering direction under contract

New gate in the battery: every consumer repo commits ONE exhaustive import contract (import-linter form, [tool.importlinter] in pyproject.toml) plus an ignore-count baseline, and the gate holds it in three passes — contract-file lint, lint-imports at the kit-pinned version (import-linter==2.11, exact pin so the parsed oracle cannot drift), and a companion AST scan for module-level dynamic imports the static contract cannot see.

Budget

• Enumerated ignores only, ratchet shrink-only. ignore_imports entries are named edges, never wildcards (CONTRACT_LINT_WILDCARD); their count ratchets against the committed import-contract-baseline.json ({"ignored_imports": N}) and an absent baseline means zero, never a free pass (CONTRACT_LINT_RATCHET).
• Stale ignores self-clean. unmatched_ignore_imports_alerting is pinned to "error" — an ignore entry matching no real edge fails (CONTRACT_STALE_IGNORE), so the baseline can only shrink.
• Pinned settings may not be loosened. exclude_type_checking_imports = true fails the contract file itself (CONTRACT_LINT_PINNED_CONFIG).
• Exhaustiveness. Every top-level package under the resolved source root must be named in some contract clause (CONTRACT_LINT_EXHAUSTIVENESS) — kills rename-evasion and vacuity.
• Exit codes: 0 clean · 1 violation · 2 the gate itself could not run (typed GateError on stderr — environment trouble is never a violation verdict).
• Honest scope is disclosed in the gate docstring: this is a layering-direction proxy; abstraction quality stays review-tier, contract content is review-gated at mount.

Control rods (eleven, through the CLI's parsed-output surface)

R1 module-level upward edge → CONTRACT_BROKEN with the named edge + line · R2 enumerated ignore entry passes with the entry printed · R3 packages with no contract → CONTRACT_MISSING · R4 function-body deferred upward import still fails · R5 TYPE_CHECKING-guarded upward import still fails · R6 wildcard ignore fails · R7 unnamed top-level package fails exhaustiveness · R8 module-level dynamic import fails · R9 stale ignore entry fails · R10 exclude_type_checking_imports = true fails · R11 uninstalled src-layout package is a typed config error (exit 2), never a violation verdict.

Self-run (the gauge submits to its own gate)

Pre-registered prediction: the kit would fail its own new gate. Confirmed verbatim:

CONTRACT_MISSING: top-level package(s) cf_quality carry no committed import contract ([tool.importlinter] in pyproject.toml)

Resolution: fixed, not baselined (the gate's only baseline surface is the ignore-count ratchet; a missing contract has no baseline path). The kit now commits its own contract — the six gate modules sit above repo_config above errors — and self-ci runs cf-import-contract --root .. The contract was refuted live: an injected errors -> repo_config edge draws CONTRACT_BROKEN: cf_quality.errors -> cf_quality.repo_config (l.86); reverting restores green.

Verification

• Suite: 296 passed (295 from the gate build + 1 new clean-wheel regression test).
• Full battery green, no-cache: ruff check · ruff format · sticky · file-budget · recursion · exemptions · import-contract · mypy (0 errors).
• Clean-wheel harsh oracle (non-editable install, no source tree): CONTRACT_MISSING fixture exits 1 with the verdict; a contracted clean fixture exits 0; an injected upward edge exits 1 with the named edge — and the new packaging test pins the verdict path.
• Also caught and fixed in review: ruff I001/format drift in the gate's test battery, present at the previous commit but masked by a stale ruff cache.

Open fork for the maintainer

cf-import-contract is wired into self-ci only. Mounting it into the reusable quality-gate.yml would immediately fail every consumer repo that has not yet committed a contract — that rollout (and the per-repo contract content review) is a maintainer decision, deliberately not taken here.

Do not merge — pending maintainer review.