@holmes-lab/holmes-kit 0.1.8 → 0.1.10

package/dist/holmes/rtm/test-scope.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_TEST_FRAMEWORKS = void 0;
+exports.architectureGoverningFiles = architectureGoverningFiles;
 exports.accountChangedFiles = accountChangedFiles;
 exports.countTestCases = countTestCases;
 exports.extractAnchors = extractAnchors;
@@ -42,8 +43,50 @@ exports.computeTestScope = computeTestScope;
 // @implements A-SPEC-121.2
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const spec_types_1 = require("../spec/spec-types");
 const rtm_check_1 = require("./rtm-check");
 const DEFAULTS = { partialBlast: 3, fullBlast: 12 };
+/**
+ * Architecture-governing documents, picked out of a change set.
+ *
+ * @implements A-SPEC-233
+ * WHY THIS EXISTS. `assessRisk`'s architecture axis already returns `hard-hitl` for exactly these
+ * changes — "supersedes accepted ADR(s)" and "C-SPEC Forbidden Edges / Layer Rules changed". Nothing
+ * on the test side consumed that verdict. Measured 2026-08-22 on the built dist: a change impacting
+ * A-SPEC-224 (the structural-constraint slice itself) got tier `unit`, ONE test file, while
+ * `assessRisk` returned `hard-hitl`. The most dangerous change received the narrowest test run.
+ *
+ * WHY THIS PREDICATE IS COARSER THAN THE RISK AXIS, AND WHY THAT IS RIGHT. The risk axis asks "did
+ * the CONSTRAINTS change?" and answers precisely, via `cspecConstraintChanged(current, proposed)`.
+ * That needs before-and-after content, which is not available here: the change source is not always
+ * git — `change-source.ts` also diffs against a baseline hash tree, where no "before" exists to
+ * read. So this asks the weaker question it can actually answer: "was an architecture-governing
+ * document touched?" The two are allowed to differ because their cost asymmetries are opposite. A
+ * false positive on the risk axis interrupts a human for nothing; a false positive here runs more
+ * tests. Widening is this module's standing answer to uncertainty everywhere else, and it is the
+ * answer here too.
+ *
+ * WHAT IT DOES NOT SEE. Whether the edit changed a rule or only its prose. Deletions (`changedFiles`
+ * carries added/modified/renamed; `.ax/specs`/`.ax/decisions` deletion is gated separately). Any
+ * architecture decision recorded somewhere other than these two locations.
+ */
+function architectureGoverningFiles(changedFiles) {
+    if (!Array.isArray(changedFiles))
+        return [];
+    // The C-SPEC folder is READ from the type table, never spelled here. A second spelling of a
+    // location is a second thing to keep in step, and this repository has already paid for that
+    // (`isTestFile` drifted into two copies; `parseSpec`'s section split was restated and returned an
+    // empty section while the check that used it went green).
+    const cspecDir = `.ax/specs/${spec_types_1.SPEC_TYPES['C-SPEC'].folder}/`;
+    const out = new Set();
+    for (const f of changedFiles) {
+        if (typeof f !== 'string' || !f.endsWith('.md'))
+            continue;
+        if (f.startsWith('.ax/decisions/') || f.startsWith(cspecDir))
+            out.add(f);
+    }
+    return [...out].sort();
+}
 const stripSpecPrefix = (id) => (id.startsWith('SPEC:') ? id.slice('SPEC:'.length) : id);
 // "Is this a test file?" must be ONE predicate. Two copies had already drifted: the scanner excluded
 // JVM/.NET/Rust/C++ conventions from the production graph while this side still only recognized
@@ -279,15 +322,62 @@ function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [
     // incomplete graph is not evidence of no impact — same epistemic state as C3 below, same answer.
     // Checked FIRST so a contradictory input (empty impact + unresolved present) resolves toward
     // full, never toward "nothing to re-test".
+    const architectureTouched = [...new Set(extras?.architectureTouched ?? [])].sort();
+    const obligationGaps = [...new Set(extras?.obligationGaps ?? [])].sort();
     if (unresolvedFiles.length > 0) {
         const shown = unresolvedFiles.slice(0, 5).join(', ');
         const suffix = unresolvedFiles.length > 5 ? ` (${unresolvedFiles.length} unresolved total)` : '';
         return {
             tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
-            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles, architectureTouched, obligationGaps,
             reason: `${unresolvedFiles.length} changed source file(s) resolved to no spec — cannot narrow safely, full regression: ${shown}${suffix}`,
         };
     }
+    // @implements A-SPEC-233
+    // This branch RETURNS. That, not its position, is what makes it beat the branches below, which
+    // only assign `tier`/`reason` and fall through to the shared return.
+    //
+    // The first cut of this comment claimed the placement was the contract, and gave a reason that is
+    // false: that below `impactedSpecs.length === 0` the signal would vanish. Measured — moving this
+    // block to just above the final return left all twelve cases green, because that branch does not
+    // return either. A comment asserting a guarantee the code does not make is the exact state this
+    // slice's own REQ exists to remove, so it is written as it actually is.
+    //
+    // The one real ordering relation is with the OTHER early return, `unresolvedFiles`. Both answer
+    // `full`, so the tier is never in question between them; what the order decides is which reason
+    // is reported, and `unresolvedFiles` wins because it names the files to anchor — an operator can
+    // act on that.
+    //
+    // What carries the weight instead of placement: an architecture document having changed is true
+    // regardless of blast, and true even when `impactedSpecs` is empty — the shape of a change that
+    // edits ONLY a C-SPEC, which resolves to no impacted spec at all.
+    if (architectureTouched.length > 0) {
+        const shown = architectureTouched.slice(0, 5).join(', ');
+        const suffix = architectureTouched.length > 5 ? ` (${architectureTouched.length} total)` : '';
+        return {
+            tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles: [], architectureTouched, obligationGaps,
+            reason: `architecture-governing document(s) changed — full regression: ${shown}${suffix}`,
+        };
+    }
+    // @implements A-SPEC-235
+    // Another early return, so it wins over the assigning branches below for the same reason the last
+    // one does. Its position among the OTHER early returns decides only which reason is reported —
+    // all three answer `full`. It comes last of the three because the two above signal larger
+    // uncertainty: a graph that cannot see a changed file, and an architecture document that moved.
+    //
+    // The reason names the TAG, not just the spec id. "coverage gap in A-SPEC-235" sends the reader
+    // to grep; "A-SPEC-235 [purity]" tells them the case to write.
+    if (obligationGaps.length > 0) {
+        const shown = obligationGaps.slice(0, 5).join(', ');
+        const suffix = obligationGaps.length > 5 ? ` (${obligationGaps.length} total)` : '';
+        return {
+            tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles: [],
+            architectureTouched, obligationGaps,
+            reason: `declared obligation(s) with no test — full regression: ${shown}${suffix}`,
+        };
+    }
     // Tier on the DIRECTLY-impacted A-SPECs (what the changed code implements), NOT the whole impacted
     // set — impactedBy always returns the ancestor chain up to the REQ root, so keying on it made every
     // change "reach a foundational REQ" → always full (verification H4). Downstream blast of the direct
@@ -332,5 +422,5 @@ function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [
         tier = 'unit';
         reason = `localized impact (blast=${blastRadius}) — run the ${impactedTestFiles.length} impacted test file(s)`;
     }
-    return { tier, impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius, hitsFoundational, coverageGaps: [...coverageGaps], reason, unresolvedFiles: [] };
+    return { tier, impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius, hitsFoundational, coverageGaps: [...coverageGaps], reason, unresolvedFiles: [], architectureTouched, obligationGaps };
 }

package/dist/holmes/server/dashboard.d.ts

@@ -28,3 +28,80 @@ export interface GraphEdge {
  * @implements A-SPEC-219
  */
 export declare function startDashboardServer(options: DashboardOptions): Promise<DashboardServerHandle>;
+/**
+ * One end-to-end 6-stage trace row: REQ -> H-SPEC -> A-SPEC -> T-SPEC -> File -> AST Symbol.
+ *
+ * Every stage is nullable ON PURPOSE. A stage that does not exist in the repository is reported as
+ * `null` and named in `missingStages`; it is never back-filled with a synthesized spec id or with a
+ * placeholder file/symbol, because a traceability matrix that invents its own evidence cannot be
+ * audited against the repository it claims to describe.
+ *
+ * @implements A-SPEC-219
+ */
+export interface PipelineRow {
+    reqId: string;
+    reqTitle: string;
+    hspecId: string | null;
+    aspecId: string | null;
+    tspecId: string | null;
+    fileId: string | null;
+    symbolId: string | null;
+    symbolLine: number | null;
+    /** How many of the 6 stages are backed by a real artifact (1..6; REQ itself always counts). */
+    stagesComplete: number;
+    /** Human-readable names of the stages with no artifact, in pipeline order. */
+    missingStages: string[];
+    /** COVERED only when all 6 stages resolve to a real artifact. */
+    status: 'COVERED' | 'UNCOVERED';
+    findingsCount: number;
+    criticalCount: number;
+    /**
+     * false when no findings ledger exists. `findingsCount: 0` then means "not scanned", never
+     * "scanned and clean", and the audit lens must render the two differently.
+     */
+    findingsScanned: boolean;
+    mutantCount: number;
+    /**
+     * `null` — never a number. A mutation SCORE requires executing the test suite once per mutant;
+     * this endpoint only generates mutants statically, so it has no basis for a score and says so
+     * rather than reporting a constant that reads as a measurement.
+     */
+    mutationScore: null;
+    mutationScoreMeasured: false;
+}
+export declare function isCanonicalStatus(status: unknown): boolean;
+/**
+ * The kinds that are governed specs at all.
+ *
+ * @implements A-SPEC-219.1
+ * Held here rather than imported from SPEC_TYPES because REQ is a spec kind that SPEC_TYPES does
+ * list — the distinction this set draws is "document in the spec store that the pipeline governs"
+ * versus "document that lives there but never will", and JOB is the whole of the second group.
+ */
+export declare const SPEC_KINDS: Set<string>;
+/**
+ * Drop retired documents before anything reads the corpus.
+ *
+ * @implements A-SPEC-222.2
+ * A-SPEC-222.1 excluded `outdated` from `isGoverned` and claimed every other check would follow.
+ * `tspec-mirror.test.ts` refuted that, and the spec was corrected to name one known site. Measured
+ * 2026-08-22 it was three: /api/rtm exposed 132 retired ids, the heatmap 108, the graph 132 — a
+ * screen still pointing at documents retired the day before. Stated once here so the three sites
+ * cannot drift, with the suite enumerating the endpoints so a fourth cannot be added silently.
+ */
+export declare function activeSpecs<T extends {
+    status?: unknown;
+}>(specs: T[]): T[];
+/** `A-SPEC-219.1` -> `A-SPEC`, `REQ-021` -> `REQ`. */
+export declare function specKindOf(id: string): string;
+/**
+ * Build the 6-stage pipeline matrix from the repository's real specs, scanned files and findings.
+ *
+ * Pure and exported so the truthfulness invariants can be asserted directly, without an HTTP round
+ * trip: no row may name an artifact that the inputs do not contain, and no symbol may be dropped.
+ *
+ * @implements A-SPEC-219
+ */
+export declare function buildPipelineRows(specs: any[], files: any[], allFindings: any[], options?: {
+    findingsScanned?: boolean;
+}): PipelineRow[];