scip-query 0.19.1 → 0.19.4

package/docs/COMMAND_REFERENCE.md

@@ -177,7 +177,7 @@ enforce (see `docs/plans/2026-07-02-followups.md` items 6 and 9).
 Followup #6 closed the one confirmed gap in an otherwise-wired battery command: `co-change`
 (`src/runtime/query-commands/impact.ts`) used the plain `dbCommand` and never disclosed a budget,
 even though its per-pair classification loop in `queries.coChange`
-(`src/queries/impact/co-change.ts`) does real filesystem/graph work whose cost scales with
+(`src/queries/cleanup/co-change.ts`) does real filesystem/graph work whose cost scales with
 candidate-pair count on a large repository. It now flows through `budgetedDbCommand` and
 `coChange` accepts a `scanLimit` option that truncates the (already priority-sorted) candidate
 pairs before classification, so the disclosed budget is truthful rather than cosmetic.

package/docs/DETECTOR_GUIDE.md

@@ -92,7 +92,7 @@ coverage, reciprocity, and connected-group signals.
 | `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
 | `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
 | `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
-| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, or requireAcyclic are configured and a baseline exists. |
+| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, requireAcyclic, requireResolvedBoundaries, requireMinimalPolicy, maxBoundaryFanOut, global maxBoundaryFiles, per-boundary maxFiles, or testPaths are configured and a baseline exists. |
 | `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
 | `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
 | `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |

package/docs/analyzer-inventory.md

@@ -94,7 +94,7 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 | `hotspots`           | Most referenced symbols                                                                                                            | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                         |
 | `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                      | Support analysis          | Raw graph metrics.                                                                                                                                                  |
 | `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                               |
-| `architecture`       | Project-owned boundary paths and dependency rules applied to resolved import and re-export edges, with mapping coverage, policy-row coverage, edge breadth, reciprocity, and SCCs | Split by evidence         | Forbidden edges, required-but-missing policy rows, and cycles under `requireAcyclic` are direct policy findings. Unmapped files, reciprocity, and advisory cycles remain report-only signals.                       |
+| `architecture`       | Project-owned boundary paths and dependency rules applied to resolved import and re-export edges, with mapping coverage, policy-row coverage, edge breadth, reciprocity, and SCCs | Split by evidence         | Forbidden edges, required-but-missing policy rows, cycles under `requireAcyclic`, and boundaries hiding an internal sub-directory cycle under `requireResolvedBoundaries` are direct policy findings. Unmapped files, reciprocity, and advisory cycles remain report-only signals.                       |
 | `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                          |
 | `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                    | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds. |
 | `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                    | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                    |

package/docs/analyzer-validation-ledger.md

@@ -368,10 +368,140 @@ full evidence is in
 ## 2026-07-23 Architecture Coherence Follow-Up
 
 `src/runtime/commands/query-command-specs.ts` remains the canonical public
-query order after adding `architecture` to the graph family. The enforcement
+query order after adding `architecture` to the graph family. (The file moved to
+`src/runtime/query-commands/` in the 2026-07-24 boundary-resolution pass; the
+public query order itself is unchanged.) The enforcement
 follow-up replaced drift's repository-specific policy with project-owned
 configuration and added stable boundary-pair identities to the shared health
 baseline. The default diff gate now blocks only new configured forbidden edges
 or explicitly forbidden cycles; accepted existing identities remain ratcheted.
 Reciprocal pairs, unmapped files, undeclared edges, and undeclared cycles remain
 contextual signals until external calibration.
+
+## 2026-07-24 Boundary Resolution and Coarse-Boundary Detection
+
+`architecture` gained a second enforceable rule, `requireResolvedBoundaries`,
+and a corresponding finding class `architecture:coarse-boundary:<boundary>`
+carried through the same health-baseline ratchet as forbidden edges and cycles.
+
+The rule exists because `requireAcyclic` had a structural blind spot rather than
+a precision problem. `analyzeArchitectureGraph` discards every dependency whose
+endpoints share a boundary before running SCC, so a boundary coarse enough to
+contain both sides of a cycle passes while asserting nothing about the code it
+holds. This repository was the demonstrating case: 14 declared boundaries with
+`requireAcyclic: true` reported zero cycles while six of them — holding 295 of
+348 files — each contained an internal cycle.
+
+**Validation.** The detector was run against the pre-change tree in an isolated
+worktree, using the original 14-boundary configuration. `requireAcyclic`
+reported 0 cycles; `detectCoarseBoundaries` reported exactly the 6 boundaries
+identified by manual analysis (`queries`, `runtime`, `semantic`, `source`,
+`reindex`, `symbols`), and its `narrowestEdges` named the precise imports the
+repair pass then removed. On the repaired tree it reports 0. Both directions are
+covered, so the result is not an artifact of a permanently-firing check.
+
+**Precision decision.** Module-hierarchy suppression is content-aware, not
+path-based. `classifyFile` decides "barrel" from the filename, which labels
+every `index.ts` bookkeeping — including `src/language-parsers/index.ts`, a
+130-line cache module that was the *target* of the narrowest real back edge in
+the repository. A path-based rule therefore produced a false negative on the
+single most important finding. A barrel is now excluded only when the index
+records no definitions of its own inside it.
+
+Directory nesting alone is deliberately not a suppression signal. An earlier
+draft suppressed any component whose sub-units shared an ancestor directory,
+which silently hid the `queries` and `semantic` findings — a boundary's root
+files depending on one of its own sub-directories is the most common real
+intra-boundary cycle, not module bookkeeping.
+
+**Known limits, not yet calibrated.** Sub-units are one directory level, so a
+layer inversion *inside* a single directory is invisible; the `src/source`
+primitives/facts/products tangle had to be derived by hand and was fixed by
+splitting the directory. Test files are not SCIP-indexed and are therefore
+outside boundary enforcement entirely. `requireCompletePolicy` checks that a
+dependency row exists, not that it is minimal, so an allowance can outlive the
+edge that justified it.
+
+## 2026-07-24 Boundary Enforcement Gap Closure
+
+Five rules were added to `architecture` after auditing what boundary
+enforcement still could not see. Each is opt-in and defaults to off, so
+upgrading tightens no existing project's gate.
+
+| Rule | Closes | Finding identity |
+| --- | --- | --- |
+| `requireMinimalPolicy` | A declared allowance outliving the edge that justified it. `requireCompletePolicy` checks a row *exists*, never that it is *minimal*, so policy widens silently. | `architecture:stale-allowance:<from>:<to>` |
+| `maxBoundaryFanOut` / global `maxBoundaryFiles` / per-boundary `maxFiles` | A boundary growing until it is coupled to most of the system. A local file ceiling overrides the global default only for its reviewed boundary. Coarseness was previously caught only when it *hid a cycle*, never when it merely got large. | `architecture:boundary-limit:<kind>:<boundary>` |
+| `testPaths` | Test files are excluded from the compiler project and therefore from the index, leaving them outside every boundary rule. | `architecture:test-boundary:<test>:<boundary>` |
+| `subUnits: 'file'` | A layer inversion *inside* one directory, invisible when sub-units are directories. | (reuses `coarse-boundary`) |
+| `fragileEdges` (report-only) | No signal distinguishing a load-bearing dependency from one resting on a single import. 60 of 251 edges here are single-import. | none — advisory |
+
+**Test-boundary calibration.** The first rule shape — "a test may import only what
+its subject's boundary may import" — produced 91 findings, nearly all
+legitimate: a test for `analysis/git-history` drives it *through*
+`queries/cleanup/co-change`, which is composition, not coupling. The shipped
+rule allows the subject's **transitive** reach plus any boundary that reaches
+the subject (a consumer is the natural driver). That yields 0 findings here,
+and a planted violation (`source-vue` test importing `reindex-vue`, which is
+unrelated in both directions) is caught. Subject resolution requires the
+mirrored path to be a **real file**: boundary globs match paths that do not
+exist, so trusting them attributed cross-cutting tests to whichever directory
+they sat in and produced 4 false positives.
+
+**One audited gap was not real.** "Dynamic `import()` counts as a static edge"
+was measured with `scip-query deps`, which builds its graph with
+`scipEdges: 'all-references'`. `architecture` builds with
+`scipEdges: 'imports-only'`, which never includes dynamic import edges — zero
+boundary edges in this repository are backed by the file whose only
+`query-commands` reference is an `await import()`. The dynamic-import detector
+written against that premise was removed rather than shipped, since it guarded
+a case the code path cannot produce and cost a source scan per file. Recorded
+here because the two graph configurations are easy to conflate when reasoning
+about architecture from `deps` output.
+
+## 2026-07-24 Review Remediation (boundary resolution)
+
+Seven review findings against the boundary work were resolved. Recorded because
+three changed a decision rather than a line.
+
+**The `source` / `language-parsers` split was reverted.** The target
+architecture forbids re-splitting them "merely to force a layer direction," and
+that is exactly what the split did once the underlying cycle was repaired. The
+merged `source` boundary is now internally acyclic and is verified as such by
+`requireResolvedBoundaries`, so the enforcement goal is met without
+contradicting the normative decision. This is the better outcome: the rule and
+the enforcement now agree instead of competing. `docs/architecture/scip-query-target-architecture.md`
+records the 14-boundary configuration as superseded, with current counts.
+
+**`subUnits` was unvalidated — the highest-risk defect.** Detection treats every
+value other than `'file'` as directory granularity, so `subUnits: "files"`
+passed validation and silently disabled the same-directory enforcement the
+option exists to turn on. A config option whose typo mode is "quietly do
+nothing" is worse than no option. Now validated as a closed set, with a
+regression test, alongside tests for the growth limits and `testPaths`.
+
+**The coarse-boundary identity encoded its members.** The identity is the
+persistent baseline comparison key, so including the current SCC membership
+meant adding one file to a tangle read as the old finding being fixed plus a
+new one appearing — ratchet churn on a problem that never went away. Now keyed
+by boundary alone.
+
+**Plan step B1.6 was completed rather than abandoned.** The plan called for
+moving the baseline checks into `queries/internal`; the literal move is
+impossible, because `checkHealthBaseline` runs every health detector and would
+create `internal -> cleanup` against the existing `cleanup -> internal`. The
+shared parts — file format, path resolution, identity normalization, and the
+new-versus-fixed comparison — moved to `queries/internal/baseline-file.ts`, and
+`checkArchitectureBaseline` moved to `queries/graph/architecture-baseline.ts`
+beside the report it reads. `checkHealthBaseline` stays in health because
+collecting findings is intrinsically a detector-layer concern. The relocation
+immediately produced the `requireMinimalPolicy` rule's first real finding: a
+`queries-health -> symbols-core` allowance left stale by the moved import.
+
+**Two smaller corrections.** `detectCoarseBoundaries` defaulted its classifier
+to `() => false`, so a direct caller reported barrel and entry bookkeeping; it
+now defaults to the path-based `classifyFile` test, with `architecture(db)`
+still overriding it with the content-aware version. And the report described a
+single-import edge as "incidental rather than load-bearing" — the graph
+establishes edge breadth, not importance, so it now reports the measurement and
+says explicitly that breadth alone settles nothing.

package/docs/architecture-coherence-vision.md

@@ -87,6 +87,35 @@ row for a boundary that may depend on nothing. `requireAcyclic` independently
 forbids multi-boundary strongly connected components. A project should enable
 both only after the observed graph has been classified and repaired.
 
+`requireResolvedBoundaries` closes the gap those two leave open. Same-boundary
+dependencies are always allowed, so every edge inside a boundary is discarded
+before `requireAcyclic` runs — which means a boundary coarse enough to contain
+both sides of a cycle passes the check while saying nothing about the code
+inside it. The rule quotients each boundary by its sub-directories and requires
+that quotient to be acyclic too, so "no cycles" keeps its meaning as boundaries
+grow. It reports the narrowest internal edge as the inspection point, because a
+hidden cycle is usually one import against a dominant direction rather than a
+tangle.
+
+Four narrower rules close the remaining holes. `requireMinimalPolicy` rejects a
+declared allowance no edge uses, because `requireCompletePolicy` checks only
+that a row exists and a stale row widens the policy silently.
+`maxBoundaryFanOut` and global `maxBoundaryFiles` bound growth, since coarseness
+was otherwise caught only when it hid a cycle. A boundary-specific `maxFiles`
+overrides the global file ceiling only for that reviewed responsibility.
+`testPaths` brings test files back
+under enforcement — they are excluded from the compiler project and so from the
+index, which put them outside every rule — judging each test against the
+boundary of the code it covers, while still allowing it to reach anything that
+subject transitively reaches or that reaches the subject. And a boundary may set
+`subUnits: "file"` when its members form layers inside one directory.
+
+The failure it prevents is specific: this repository's own configuration
+declared 14 boundaries with `requireAcyclic: true` and reported zero cycles,
+while six of those boundaries — holding 85% of all files — each contained an
+internal cycle. The clean result was an artifact of granularity, not a property
+of the code.
+
 ## What the Analyzer Should Report
 
 The report should preserve both policy truth and graph evidence:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.19.1",
+  "version": "0.19.4",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -324,7 +324,7 @@
     "bench:native-symbol-leaf": "node scripts/bench-native-symbol-leaf.mjs",
     "calibrate": "node scripts/accuracy-calibration.mjs",
     "docs:commands": "vite-node scripts/render-command-reference.ts --write",
-    "prepublishOnly": "npm run publish:scip-windows && npm run build",
+    "prepublishOnly": "vite-node scripts/publish-scip-windows.ts && npm run build",
     "postinstall": "node dist/postinstall.js || true",
     "publish:scip-windows": "vite-node scripts/publish-scip-windows.ts"
   },