Skip to content

feat(formal): add where.mjs, the contract lookup command - #236

Merged
lan17 merged 3 commits into
mainfrom
claude/formal-where
Oct 15, 2026
Merged

lan17 merged 3 commits into
mainfrom
claude/formal-where

Conversation

@lan17

@lan17 lan17 commented Oct 15, 2026

Copy link
Copy Markdown
Owner

Phase 3 of #220, item N1. One commit, base main. Independent of the other open PRs.

What

node formal/tools/where.mjs C45
node formal/tools/where.mjs C45.maximum-age-exclusive --json

prints, for one contract or one semantic case, where it is:

  • Stated: its CONTRACTS row (with the evidence column) and every Quint comment that cites the ID, as file:line, plus the reviewed guides that name it.
  • Tested: the semantic cases that carry it, each with its scenarios, scoped Quint checks, required witnesses, replayed regressions and vectors; the documentation sections and tests disposed to it in the source audit; the feature families.
  • Challenged: the model-fault challenges that name it, with the invariant, the native mutant kind and ID, the reproducer run and the detecting and excluded profile counts.
  • Mapped: the native mutants whose case carries it, with the ports they edit, and the Go parity rows for its cases.

For C45 that is 96 lines assembled from eight files in one command; by hand it was the three-read navigation test #220 set for Phase 1, now one read. It adds no data and no gate: everything comes from the catalogs the audit already parses.

Tests

formal-where.test.ts: C45 resolves to its obligation, the kernel citation in recovery.qnt, the known case, challenge and mutant (M01 with TypeScript, Go and Rust edits), parity rows for exactly its cases and disposed sections; a case ID narrows the view and keeps only the challenges mapped through that case's mutant; the rendering has the four sections with file:line locations; an unknown contract, a malformed query and an unknown case are rejected with a one-line message.

Verification

vitest run test/formal-where passes; tsc --noEmit clean; make audit green; node scripts/check-docs.mjs green. The README and AUTHORING entries were re-keyed with --refresh; parity inputs re-pinned.

🤖 Generated with Claude Code

Comment thread formal/tools/where.mjs Fixed
@codecov-commenter

codecov-commenter commented Oct 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.73%. Comparing base (093c1c9) to head (d8b4d38).

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #236   +/-   ##
=======================================
  Coverage   93.73%   93.73%           
=======================================
  Files          78       78           
  Lines       11357    11357           
  Branches      656      656           
=======================================
+ Hits        10645    10646    +1     
+ Misses        642      641    -1     
  Partials       70       70           
Flag Coverage Δ
go 91.17% <ø> (+0.05%) ⬆️
python 92.08% <ø> (ø)
rust 94.29% <ø> (ø)
typescript 96.56% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

lan17 added 3 commits October 14, 2026 18:54
`node formal/tools/where.mjs C45` prints where one contract is stated
(its CONTRACTS row and every Quint comment that cites it, with
file:line), tested (the semantic cases that carry it with their
scenarios, scoped Quint checks, witnesses, replays and vectors, the
documentation sections and tests disposed to it, the feature families),
challenged (the model-fault challenges that name it, with their
invariant, native mutant, reproducer and profile partition counts) and
mapped (the native mutants whose case carries it, with the ports they
edit, and the Go parity rows). A semantic case ID narrows the view to
that case. `--json` prints the same structure for an agent.

It reads only the catalogs the audit already parses and adds no data and
no gate: it is the navigation a reviewer or an agent otherwise assembles
by hand, and the contract-level navigation test of #220 as
a command. The README task table, the tools index and AUTHORING's
reviewer-context section point at it.
…he argument

CodeQL flagged the regular expression where.mjs built from the validated
command-line ID. The scan now tests whole-token occurrences of the ID
directly, which also makes the intent (an ID is a letter and two digits,
not a prefix of a longer one) explicit.
Review follow-up. Mapped selected mutants by case-ID prefix while Tested
selected cases by contract, so a cross-listed case lost its mutant: C33
printed four challenges "mapped M06" above "Mapped (0 native mutants)".
Mutants are now the ones whose case the contract's cases include.

A case query dropped every challenge whose mutant sits on another case,
including the eight cross-contract mappings and the eight challenges
without a port line. Those stay with a tag ("cross-contract via M40 on
C40.future-rejected", "model-only, not narrowed to a case") and the
cross-contract note that execution.mjs requires is printed at both
levels.

Citations now include ranges ("C40 to C46", "C40-C45"), the house style
of the rewritten kernel headers; C42 showed no model citation although
six headers state it. The kernel fixtures are no longer scanned as
statements. The B-series contracts list their native cases from
feature-coverage.json with the port tests, and a native case ID is an
accepted query. Each semantic case shows its defining transitions and
source pointers. Challenge rows carry full paths and count profiles and
models separately; the CONTRACTS row must split into three cells; the
CLI rejects unknown flags and extra arguments; a case query's header is
the case rule. The near-constant "reviewed guides naming it" line is
gone.
@lan17
lan17 force-pushed the claude/formal-where branch from e4fc08c to d8b4d38 Compare October 15, 2026 01:54
@lan17
lan17 merged commit 0b386be into main Oct 15, 2026
21 checks passed
@lan17
lan17 deleted the claude/formal-where branch October 15, 2026 01:59
lan17 added a commit that referenced this pull request Oct 15, 2026
#236 added formal/tools/where.mjs, which prints where one contract is
stated, tested, challenged and mapped. That is the navigation the Bug
fix path and the formal convention in AGENTS.md asked agents to assemble
by hand, so both name the command, and DEVELOPMENT_PROCESS.md lists it
under Where to look.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants