@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/review/review-targets.js

@@ -0,0 +1,92 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readReviewNeeded = readReviewNeeded;
+exports.anchoredForReview = anchoredForReview;
+const path = __importStar(require("node:path"));
+/**
+ * Read the outstanding `review-needed` signals off the provenance chain. P4 does not auto-clear, so
+ * every recorded signal is currently "outstanding" — the surface lists them so a reviewer knows what
+ * moved and which files to examine. A missing/unreadable chain → [] (nothing to route), never a throw.
+ */
+function readReviewNeeded(ledgerFile) {
+    // @implements A-SPEC-148
+    // Reads EVERY replica chain. Bound to the legacy filename this returned nothing once writes moved
+    // to the per-replica chain — a routing signal that silently stops arriving is worse than one that
+    // never existed, because the absence looks like "no review needed".
+    let events;
+    try {
+        const { FileLedgerStore } = require('../governance/ledger-store');
+        events = new FileLedgerStore(path.dirname(ledgerFile)).loadAll();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const evt of events) {
+        if (evt.kind === 'review-needed' && Array.isArray(evt.inputs) && evt.inputs.length >= 3) {
+            const [spec, from, to, ...files] = evt.inputs;
+            out.push({ spec, from, to, files });
+        }
+    }
+    return out;
+}
+/**
+ * The deterministic set of source files a targeted adversarial review must re-examine when a spec's
+ * approved content MOVES (P4). This is a ROUTING computation, not a verdict: it names WHERE to look,
+ * never whether the code is right — that judgment stays with the review layer / a human, which is the
+ * whole point of P4 (the decision layer checks form/existence/execution, never meaning).
+ *
+ * - An A-SPEC's targets are the source files whose scanned `@implements` names it (its direct anchors).
+ * - A REQ's or H-SPEC's targets are the union of its APPROVED direct A-SPEC children's anchors (one
+ *   hop): a moved parent implicates the code under the approved slices beneath it.
+ *
+ * Pure, deduped, path-sorted — same (spec, anchor graph) → same set.
+ */
+function anchoredForReview(specId, scanned, specs) {
+    const self = specs.find((s) => s.id === specId);
+    const collectDirect = (aspecId) => scanned.filter((f) => f.implementsSpecs.includes(aspecId)).map((f) => f.sourcePath);
+    let files;
+    if (self && (self.type === 'REQ' || self.type === 'H-SPEC')) {
+        // one hop: approved direct A-SPEC children
+        const children = specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved' && s.dependsOn.includes(specId));
+        files = children.flatMap((c) => collectDirect(c.id));
+    }
+    else {
+        // A-SPEC (or an unknown id): its own direct anchors
+        files = collectDirect(specId);
+    }
+    return [...new Set(files)].sort();
+}

package/dist/holmes/review/scope.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeReviewScope = computeReviewScope;
+const rtm_builder_1 = require("../rtm/rtm-builder");
+const ACCEPTANCE_SECTION_BY_TYPE = {
+    'A-SPEC': 'Done When',
+    'H-SPEC': 'Acceptance Criteria',
+    REQ: 'Success Criteria',
+};
+function stripSpecPrefix(specNodeId) {
+    return specNodeId.startsWith('SPEC:') ? specNodeId.slice('SPEC:'.length) : specNodeId;
+}
+// @implements A-SPEC-102.1
+function computeReviewScope(graph, specs, changedSymbols) {
+    const specById = new Map();
+    for (const s of specs) {
+        specById.set(s.id, s);
+    }
+    const dedupedChangedSymbols = [...new Set(changedSymbols)].sort();
+    const impactedSpecs = [...new Set((0, rtm_builder_1.impactedBy)(graph, dedupedChangedSymbols))].sort();
+    const acceptanceCriteria = [];
+    for (const specNodeId of impactedSpecs) {
+        const specId = stripSpecPrefix(specNodeId);
+        const spec = specById.get(specId);
+        if (!spec)
+            continue;
+        const sectionName = ACCEPTANCE_SECTION_BY_TYPE[spec.type];
+        if (!sectionName)
+            continue;
+        const criteria = spec.sections[sectionName];
+        if (!criteria)
+            continue;
+        acceptanceCriteria.push({ specId, criteria });
+    }
+    acceptanceCriteria.sort((a, b) => (a.specId < b.specId ? -1 : a.specId > b.specId ? 1 : 0));
+    const unrequestedSymbols = dedupedChangedSymbols
+        .filter((qn) => !(0, rtm_builder_1.impactedBy)(graph, [qn]).some((id) => id.startsWith('SPEC:')))
+        .sort();
+    const coverageGaps = [];
+    for (const specNodeId of impactedSpecs) {
+        if (!specNodeId.startsWith('SPEC:A-SPEC-'))
+            continue;
+        const aSpecId = stripSpecPrefix(specNodeId);
+        const hasTSpecChild = specs.some((s) => s.type === 'T-SPEC' && s.dependsOn.includes(aSpecId));
+        if (!hasTSpecChild) {
+            coverageGaps.push(aSpecId);
+        }
+    }
+    coverageGaps.sort();
+    return {
+        changedSymbols: dedupedChangedSymbols,
+        impactedSpecs,
+        acceptanceCriteria,
+        unrequestedSymbols,
+        coverageGaps,
+    };
+}

package/dist/holmes/review/test-evidence.js

@@ -0,0 +1,77 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVIDENCE_FILE = void 0;
+exports.computeExecutedByAspec = computeExecutedByAspec;
+exports.isFresh = isFresh;
+exports.writeTestEvidence = writeTestEvidence;
+exports.readTestEvidence = readTestEvidence;
+// @implements A-SPEC-102.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Map per-test-file executed counts onto the A-SPECs those files @implement (pure). */
+function computeExecutedByAspec(executedByFile, testAnchors) {
+    const out = {};
+    for (const [file, n] of Object.entries(executedByFile)) {
+        for (const id of testAnchors[file] ?? [])
+            out[id] = (out[id] ?? 0) + n;
+    }
+    return out;
+}
+/** Evidence is usable only for the exact commit it was produced at (pure). */
+function isFresh(ev, currentHead) {
+    return !!ev && !!ev.head && ev.head === currentHead;
+}
+exports.EVIDENCE_FILE = path.join('.ax', 'ledger', 'test-evidence.json');
+function writeTestEvidence(root, ev) {
+    try {
+        const file = path.join(root, exports.EVIDENCE_FILE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(ev, null, 2), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    } // evidence recording must never break a run
+}
+function readTestEvidence(root) {
+    try {
+        const ev = JSON.parse(fs.readFileSync(path.join(root, exports.EVIDENCE_FILE), 'utf8'));
+        return ev && typeof ev.head === 'string' && ev.executedByAspec && typeof ev.executedByAspec === 'object' ? ev : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}