@holmes-lab/holmes-kit 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +19 -17
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/doctor.js +25 -1
  5. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  6. package/dist/holmes/cpg/ast-mutation.js +4 -2
  7. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  8. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  9. package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
  10. package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
  11. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
  12. package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
  13. package/dist/holmes/mcp/handlers.d.ts +107 -0
  14. package/dist/holmes/mcp/handlers.js +11 -1
  15. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
  16. package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
  17. package/dist/holmes/mcp/tool-schemas.js +14 -1
  18. package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
  19. package/dist/holmes/review/condition-hunk-replay.js +112 -0
  20. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  21. package/dist/holmes/review/condition-hunk-resolution.js +207 -0
  22. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  23. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  24. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  25. package/dist/holmes/review/requirement-triage.js +143 -0
  26. package/dist/holmes/semantic/local-model.d.ts +3 -3
  27. package/dist/holmes/semantic/local-model.js +10 -12
  28. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  29. package/dist/holmes/semantic/model-cache.js +77 -21
  30. package/dist/holmes/semantic/tier.d.ts +5 -1
  31. package/dist/holmes/semantic/tier.js +7 -6
  32. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  33. package/dist/holmes/semantic/vector-coverage.js +37 -0
  34. package/docs/install-guide.md +19 -24
  35. package/package.json +1 -1
@@ -383,6 +383,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
383
383
  head?: string;
384
384
  since?: string;
385
385
  }) => Promise<{
386
+ requirementSemanticWarm?: {
387
+ tier: string;
388
+ computed: number;
389
+ cached: number;
390
+ } | undefined;
386
391
  semanticWarm?: {
387
392
  tier: string;
388
393
  computed: number;
@@ -591,6 +596,108 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
591
596
  root: string;
592
597
  harness?: import("../cli/agents").Agent;
593
598
  }): Promise<import("../project/workspace-preflight").WorkspacePreflight>;
599
+ requirement_triage: (a: {
600
+ root: string;
601
+ prompt: string;
602
+ topK?: number;
603
+ persist?: boolean;
604
+ }) => Promise<{
605
+ promptDigest: string;
606
+ semantic: {
607
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
608
+ recovery?: string | undefined;
609
+ tier: "local" | "none" | "cloud";
610
+ covered: number;
611
+ total: number;
612
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
613
+ availability: string;
614
+ };
615
+ provenance: {
616
+ reqId: string;
617
+ documents: {
618
+ id: string;
619
+ type: import("../review/requirement-triage").RequirementDocumentKind;
620
+ status: string;
621
+ dependsOn: readonly string[];
622
+ }[];
623
+ implementationAnchors: string[];
624
+ graphProvenance: {
625
+ [k: string]: {} | null;
626
+ };
627
+ executionEvidence: {
628
+ state: string;
629
+ recordedHead: string | null;
630
+ currentHead: string;
631
+ };
632
+ }[];
633
+ graph: {
634
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
635
+ sourceCommit: string | null;
636
+ graphAsOf: string | null;
637
+ resolutionLimits: string[];
638
+ };
639
+ graphBasis: {
640
+ head: string;
641
+ governedDocumentCount: number;
642
+ scannedSourceCount: number;
643
+ };
644
+ verdict: import("../review/requirement-triage").RequirementVerdict;
645
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
646
+ reasons: string[];
647
+ uncertainty: string[];
648
+ schema: "requirement-triage/1";
649
+ } | {
650
+ evidenceDigest: string;
651
+ persistedTo: string;
652
+ artifact: {
653
+ digest: string;
654
+ path: string;
655
+ };
656
+ promptDigest: string;
657
+ semantic: {
658
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
659
+ recovery?: string | undefined;
660
+ tier: "local" | "none" | "cloud";
661
+ covered: number;
662
+ total: number;
663
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
664
+ availability: string;
665
+ };
666
+ provenance: {
667
+ reqId: string;
668
+ documents: {
669
+ id: string;
670
+ type: import("../review/requirement-triage").RequirementDocumentKind;
671
+ status: string;
672
+ dependsOn: readonly string[];
673
+ }[];
674
+ implementationAnchors: string[];
675
+ graphProvenance: {
676
+ [k: string]: {} | null;
677
+ };
678
+ executionEvidence: {
679
+ state: string;
680
+ recordedHead: string | null;
681
+ currentHead: string;
682
+ };
683
+ }[];
684
+ graph: {
685
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
686
+ sourceCommit: string | null;
687
+ graphAsOf: string | null;
688
+ resolutionLimits: string[];
689
+ };
690
+ graphBasis: {
691
+ head: string;
692
+ governedDocumentCount: number;
693
+ scannedSourceCount: number;
694
+ };
695
+ verdict: import("../review/requirement-triage").RequirementVerdict;
696
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
697
+ reasons: string[];
698
+ uncertainty: string[];
699
+ schema: "requirement-triage/1";
700
+ }>;
594
701
  ledger_reconcile: (a: {
595
702
  root?: string;
596
703
  nonce: string;
@@ -38,7 +38,7 @@ exports.isHandlerRefusal = isHandlerRefusal;
38
38
  exports.unreadableAmong = unreadableAmong;
39
39
  exports.makeHandlers = makeHandlers;
40
40
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627
41
+ // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713
42
42
  // @implements A-SPEC-643
43
43
  // @implements A-SPEC-642
44
44
  // @implements A-SPEC-642
@@ -82,6 +82,7 @@ const graph_operations_1 = require("./handlers/graph-operations");
82
82
  // @implements A-SPEC-632 — the rebuild paths discharge shares with reindex.
83
83
  const graph_operations_2 = require("./handlers/graph-operations");
84
84
  const maintenance_analysis_1 = require("./handlers/maintenance-analysis");
85
+ const requirement_triage_1 = require("./handlers/requirement-triage");
85
86
  const taint_screening_1 = require("./handlers/taint-screening");
86
87
  const cpg_scanner_1 = require("../cpg/cpg-scanner");
87
88
  const scan_cache_1 = require("../cpg/scan-cache");
@@ -716,6 +717,14 @@ function makeRawHandlers(store, opts) {
716
717
  specStoreBlindReason: (root, count) => specStoreBlindReason(store, root, count),
717
718
  fileDigestOf,
718
719
  });
720
+ const requirementTriage = (0, requirement_triage_1.createRequirementTriageHandlers)({
721
+ listSpecs: () => store.list(),
722
+ foreignRootReason: root => foreignRootReason(store, root),
723
+ projectRootOf,
724
+ cachedScan,
725
+ assertStoreReachable: (tool, root) => assertSpecStoreReachable(tool, store, root),
726
+ refusal: reason => new HandlerRefusal(reason),
727
+ });
719
728
  const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
720
729
  // @implements A-SPEC-100.2, A-SPEC-128, A-SPEC-138, A-SPEC-140.2, A-SPEC-189, A-SPEC-461, A-SPEC-512.2, A-SPEC-513.1, A-SPEC-524.1
721
730
  const taintScreening = (0, taint_screening_1.createTaintScreeningHandlers)({
@@ -927,6 +936,7 @@ function makeRawHandlers(store, opts) {
927
936
  listSpecs: () => store.list(),
928
937
  cachedScan,
929
938
  }),
939
+ requirement_triage: requirementTriage.requirement_triage,
930
940
  // @implements A-SPEC-642 — placed in the one slot no public-key-order pin covers (the handler suites pin
931
941
  // spec_create..spec_upgrade, spec_retire..spec_unseal, spec_unseal+5, spec_approve+4, spec_next+3,
932
942
  // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
@@ -0,0 +1,11 @@
1
+ export declare const REQUIREMENT_TRIAGE_EVIDENCE_DIR: string;
2
+ export interface RequirementTriageArtifact {
3
+ schema: 'requirement-triage-evidence/1';
4
+ promptDigest: string;
5
+ result: unknown;
6
+ }
7
+ /** Writes an atomically published artifact addressed by its content digest. */
8
+ export declare function writeRequirementTriageEvidence(root: string, artifact: RequirementTriageArtifact): {
9
+ digest: string;
10
+ path: string;
11
+ };
@@ -0,0 +1,79 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = void 0;
37
+ exports.writeRequirementTriageEvidence = writeRequirementTriageEvidence;
38
+ // @implements A-SPEC-713
39
+ /** Content-addressed, isolated persistence for advisory requirement triage results. */
40
+ const crypto = __importStar(require("node:crypto"));
41
+ const fs = __importStar(require("node:fs"));
42
+ const path = __importStar(require("node:path"));
43
+ exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = path.join('.ax', 'evidence', 'requirement-triage');
44
+ const sha256 = (text) => `sha256:${crypto.createHash('sha256').update(text).digest('hex')}`;
45
+ const DIGEST = /^sha256:[a-f0-9]{64}$/;
46
+ /** Canonical JSON keeps equivalent object construction from creating different evidence addresses. */
47
+ function stable(value) {
48
+ if (value === null || typeof value === 'boolean' || typeof value === 'string')
49
+ return JSON.stringify(value);
50
+ if (typeof value === 'number') {
51
+ if (!Number.isFinite(value))
52
+ throw new Error('requirement triage artifact contains a non-finite number');
53
+ return JSON.stringify(value);
54
+ }
55
+ if (Array.isArray(value))
56
+ return `[${value.map(stable).join(',')}]`;
57
+ if (typeof value === 'object') {
58
+ const row = value;
59
+ return `{${Object.keys(row).sort().map((key) => `${JSON.stringify(key)}:${stable(row[key])}`).join(',')}}`;
60
+ }
61
+ throw new Error('requirement triage artifact is not JSON-serializable');
62
+ }
63
+ /** Writes an atomically published artifact addressed by its content digest. */
64
+ function writeRequirementTriageEvidence(root, artifact) {
65
+ if (artifact.schema !== 'requirement-triage-evidence/1' || !DIGEST.test(artifact.promptDigest)) {
66
+ throw new Error('requirement triage artifact requires a sha256 prompt digest');
67
+ }
68
+ const body = `${stable(artifact)}\n`;
69
+ const digest = sha256(body);
70
+ const dir = path.join(root, exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR);
71
+ const target = path.join(dir, `${digest.slice('sha256:'.length)}.json`);
72
+ fs.mkdirSync(dir, { recursive: true });
73
+ if (!fs.existsSync(target)) {
74
+ const temp = `${target}.${process.pid}.tmp`;
75
+ fs.writeFileSync(temp, body, 'utf8');
76
+ fs.renameSync(temp, target);
77
+ }
78
+ return { digest, path: target };
79
+ }
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627
4
+ // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713
5
5
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
6
6
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
7
7
  // @implements A-SPEC-642
@@ -366,6 +366,19 @@ exports.TOOL_SCHEMAS = {
366
366
  required: ['root', 'request'],
367
367
  },
368
368
  },
369
+ requirement_triage: {
370
+ description: 'Read-only requirement lifecycle advisory. BM25 always ranks governed REQ/H-SPEC/A-SPEC/T-SPEC lineages; cached local BGE-M3 or explicit Gemini candidates are additive. Content, approval, implementation-anchor, and fresh execution evidence determine fulfilled, existing-change, new, or ambiguous. It never creates, edits, approves, unseals, retires, or opens a source-edit gate.',
371
+ inputSchema: {
372
+ type: 'object',
373
+ properties: {
374
+ root: ROOT_ANY,
375
+ prompt: str('User requirement or requested behavior to compare with governed requirement lineages.'),
376
+ topK: num('Maximum displayed candidate lineages (default 10, clamped to 1..20).'),
377
+ persist: bool('Write only a content-addressed requirement-triage evidence artifact. Default false.'),
378
+ },
379
+ required: ['root', 'prompt'],
380
+ },
381
+ },
369
382
  maintenance_outcome: {
370
383
  description: 'Record what a change actually touched against a previously persisted maintenance analysis, so the prediction can later be scored. The digest must name an analysis this project already stored.',
371
384
  inputSchema: {
@@ -0,0 +1,33 @@
1
+ import type { ReplayCase } from './replay-corpus';
2
+ export interface ConditionHunkReplayReport {
3
+ schema: 'condition-hunk-replay/1';
4
+ commits: string[];
5
+ caseCount: number;
6
+ raw: {
7
+ files: number;
8
+ symbols: number;
9
+ candidateSymbols: number;
10
+ hunks: number;
11
+ resolved: number;
12
+ ambiguous: number;
13
+ unavailable: number;
14
+ relaxed: number;
15
+ narrowed: number;
16
+ unknown: number;
17
+ };
18
+ candidateReduction: {
19
+ hunkToResolved: number | null;
20
+ };
21
+ timingMs: {
22
+ baseline: number;
23
+ conditionResolution: number;
24
+ overheadPct: number | null;
25
+ };
26
+ elapsedMs: number;
27
+ limitations: string[];
28
+ }
29
+ /** Replays caller-selected commits only; it never checks out, writes a cache, or inspects another repository. */
30
+ export declare function replayConditionHunks(input: {
31
+ root: string;
32
+ cases: readonly ReplayCase[];
33
+ }): Promise<ConditionHunkReplayReport>;
@@ -0,0 +1,112 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.replayConditionHunks = replayConditionHunks;
37
+ // @implements A-SPEC-661
38
+ /** Historical, read-only measurement for the condition-hunk advisory. */
39
+ const node_child_process_1 = require("node:child_process");
40
+ const path = __importStar(require("node:path"));
41
+ const language_parser_1 = require("../cpg/language-parser");
42
+ const condition_hunk_resolution_1 = require("./condition-hunk-resolution");
43
+ const SAFE_COMMIT = /^[0-9a-f]{7,64}$/;
44
+ const sourceLanguage = (file) => {
45
+ if (/\.(ts|mts|cts)$/.test(file))
46
+ return 'typescript';
47
+ if (/\.(tsx|js|jsx|mjs|cjs)$/.test(file))
48
+ return 'tsx';
49
+ return null;
50
+ };
51
+ const safePath = (file) => file !== '' && !path.isAbsolute(file) && !file.split(/[\\/]/).includes('..');
52
+ const git = (root, args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], {
53
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024,
54
+ });
55
+ /** Replays caller-selected commits only; it never checks out, writes a cache, or inspects another repository. */
56
+ async function replayConditionHunks(input) {
57
+ const started = Date.now();
58
+ const parser = new language_parser_1.TreeSitterTsParser();
59
+ const resolutions = [];
60
+ let files = 0, symbols = 0, candidateSymbols = 0, baselineMs = 0, conditionResolutionMs = 0;
61
+ const commits = [];
62
+ for (const replayCase of input.cases) {
63
+ if (!SAFE_COMMIT.test(replayCase.commit))
64
+ throw new Error('condition replay requires a hexadecimal commit id');
65
+ commits.push(replayCase.commit);
66
+ for (const file of replayCase.files) {
67
+ const language = sourceLanguage(file);
68
+ if (language === null || !safePath(file))
69
+ continue;
70
+ let source, diff;
71
+ const baselineStart = Date.now();
72
+ try {
73
+ source = git(input.root, ['show', `${replayCase.commit}:${file}`]);
74
+ diff = git(input.root, ['diff', '--unified=0', `${replayCase.commit}^`, replayCase.commit, '--', file]);
75
+ }
76
+ catch {
77
+ continue;
78
+ }
79
+ const hunks = (0, condition_hunk_resolution_1.parseUnifiedZeroDiff)(diff);
80
+ if (hunks.length === 0)
81
+ continue;
82
+ const rows = parser.extractSymbols(source, language).map((symbol) => ({ file, name: symbol.qualifiedName, startLine: symbol.startLine, endLine: symbol.endLine }));
83
+ baselineMs += Date.now() - baselineStart;
84
+ files++;
85
+ symbols += rows.length;
86
+ candidateSymbols += hunks.reduce((total, hunk) => total + rows.filter((symbol) => symbol.startLine <= hunk.startLine && symbol.endLine >= hunk.endLine).length, 0);
87
+ const conditionStart = Date.now();
88
+ resolutions.push(...await (0, condition_hunk_resolution_1.resolveConditionHunksFromSources)({ diff, sources: [{ file, source }], symbols: rows }));
89
+ conditionResolutionMs += Date.now() - conditionStart;
90
+ }
91
+ }
92
+ const resolved = resolutions.filter((row) => row.state === 'resolved').length;
93
+ const ambiguous = resolutions.filter((row) => row.state === 'ambiguous').length;
94
+ const unavailable = resolutions.filter((row) => row.state === 'unavailable').length;
95
+ const relaxed = resolutions.filter((row) => row.direction === 'relaxed').length;
96
+ const narrowed = resolutions.filter((row) => row.direction === 'narrowed').length;
97
+ const unknown = resolutions.filter((row) => row.direction === 'unknown').length;
98
+ return {
99
+ schema: 'condition-hunk-replay/1', commits, caseCount: input.cases.length,
100
+ raw: { files, symbols, candidateSymbols, hunks: resolutions.length, resolved, ambiguous, unavailable, relaxed, narrowed, unknown },
101
+ candidateReduction: { hunkToResolved: candidateSymbols === 0 ? null : 1 - resolved / candidateSymbols },
102
+ timingMs: { baseline: baselineMs, conditionResolution: conditionResolutionMs,
103
+ overheadPct: baselineMs === 0 ? null : conditionResolutionMs / baselineMs * 100 },
104
+ elapsedMs: Date.now() - started,
105
+ limitations: [
106
+ 'This measures only caller-selected TypeScript/JavaScript files with readable commit blobs.',
107
+ 'A resolved span is provenance coverage, not a precision or correctness claim.',
108
+ 'Direction is reported only for a same-position changed control-flow predicate with a locally monotonic syntax rule; every other hunk remains unknown.',
109
+ 'The replay is read-only and does not evaluate a gate, mutate changedFiles, or run tests.',
110
+ ],
111
+ };
112
+ }
@@ -0,0 +1,65 @@
1
+ export type ConditionDirection = 'relaxed' | 'narrowed' | 'unknown';
2
+ export type HunkResolutionState = 'resolved' | 'ambiguous' | 'unavailable';
3
+ export interface UnifiedZeroHunk {
4
+ file: string;
5
+ startLine: number;
6
+ endLine: number;
7
+ deletionOnly?: boolean;
8
+ /** Exact changed lines are evidence only; resolution never expands the changed line range. */
9
+ removedLines?: string[];
10
+ addedLines?: string[];
11
+ }
12
+ export interface HunkSymbol {
13
+ file: string;
14
+ name: string;
15
+ startLine: number;
16
+ endLine: number;
17
+ }
18
+ export interface ConditionBranch {
19
+ file: string;
20
+ startLine: number;
21
+ endLine: number;
22
+ conditionText?: string;
23
+ beforeConditionText?: string;
24
+ branchLabel: 'true' | 'false' | 'case' | 'default' | string;
25
+ astKind?: string;
26
+ }
27
+ export interface HunkResolution {
28
+ file: string;
29
+ hunk: UnifiedZeroHunk;
30
+ symbol?: string;
31
+ branch?: ConditionBranch;
32
+ conditionText?: string;
33
+ direction: ConditionDirection;
34
+ state: HunkResolutionState;
35
+ reason?: string;
36
+ candidates?: ConditionBranch[];
37
+ }
38
+ /** Parse file headers, @@ ranges, and exact changed lines; body text never widens the changed region. */
39
+ export declare function parseUnifiedZeroDiff(diff: string): UnifiedZeroHunk[];
40
+ /** Classifies only syntactic changes with a local, monotonic meaning; all other changes are unknown. */
41
+ export declare function classifyConditionDirection(before: string | undefined, after: string | undefined): ConditionDirection;
42
+ export interface ResolveConditionHunksInput {
43
+ hunks: readonly UnifiedZeroHunk[];
44
+ symbols: readonly HunkSymbol[];
45
+ branches: readonly ConditionBranch[];
46
+ /** This first advisory implementation preserves TS/JS branch source spans only. */
47
+ language?: string;
48
+ }
49
+ /** Intersects hunk → narrowest symbol → branch span, retaining ties instead of inventing a winner. */
50
+ export declare function resolveConditionHunks(input: ResolveConditionHunksInput): HunkResolution[];
51
+ export interface ConditionHunkSource {
52
+ file: string;
53
+ source: string;
54
+ }
55
+ export interface ResolveConditionHunksFromSourcesInput {
56
+ diff: string;
57
+ sources: readonly ConditionHunkSource[];
58
+ symbols: readonly HunkSymbol[];
59
+ }
60
+ /**
61
+ * The explicit heavy advisory path: parse only caller-supplied TS/JS source, derive CFG predicate
62
+ * spans, and feed the same conservative resolver. It is intentionally separate from CpgScanner's
63
+ * synchronous hot path and cannot alter changedFiles, a graph, a gate, or a cache.
64
+ */
65
+ export declare function resolveConditionHunksFromSources(input: ResolveConditionHunksFromSourcesInput): Promise<HunkResolution[]>;