@holmes-lab/holmes-kit 0.35.14 → 0.35.15

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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.15] - 2026-10-08
9
+
10
+ ### Added
11
+
12
+ - **`maintenance_analyze` names the file a change still has to create** (A-SPEC-759, A-SPEC-759.1). When
13
+ `changedFiles` is given, a relative import that a changed TypeScript/JavaScript file newly introduces and that
14
+ resolves to nothing — no scanned file, no file on disk in any resolvable form, declaration files included, and
15
+ not a path inside a build or vendor directory — is reported under `impacts.missingNewFiles` as
16
+ `{ from, specifier, candidates }`. No ranking over existing files can name a file that is not there, and of the
17
+ files an incomplete change set is missing 6–12% do not exist yet. Measured through the product function on two
18
+ windows of a public TypeScript monorepo that no earlier measurement had used (140 and 143 changes of three or
19
+ more files, a third of each hidden): every naming was a file the change did create (precision 1.000 on both) and
20
+ 78–86% of the not-yet-existing missing files were named — 7–8% of all missing files, at no cost in precision.
21
+ On a second public TypeScript repository seen for the first time (229 changes) the first build scored 0.908
22
+ (79/87): five of the eight were files the commit did create that the scoring does not count, one was a
23
+ declaration file that had always existed, two were imports of build output — the last two kinds are what
24
+ A-SPEC-759.1 removes, leaving no namings of a file that was not created.
25
+ "Newly introduced" is the rule that makes it exact: reading every unresolved import instead had precision
26
+ 0.46–0.83, all of the wrong namings being imports already unresolved before the change (build-generated modules,
27
+ import text inside strings). The earlier text is HEAD's, read with one `git show` per changed file that has a
28
+ surviving import (at most 50); the list is cut to 20 rows. **What this does not do:** a change already committed
29
+ shows nothing (HEAD holds it); outside version control nothing is named; Python, Go, Rust and Java import forms,
30
+ bare package names and path aliases are not read; a type checker reports the same gap once it is run. Rankings,
31
+ classification and every gate are unchanged.
32
+
8
33
  ## [0.35.14] - 2026-10-08
9
34
 
10
35
  ### Fixed
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **436/436** source files (100%) trace to an approved spec · **752/815** approved A-SPECs (92.2%) are anchored from code.
13
- Measured at `d2852f9a42c2` (specs `sha256:2730ac4791a0`) — reproduce with `holmes-kit attest --exclude dist-tools/,docs/goals/probes/,reference/`.
12
+ **447/453** source files (98.6%) trace to an approved spec · **754/817** approved A-SPECs (92.2%) are anchored from code.
13
+ Measured at `843876d688fe` (specs `sha256:5f2dfff7ced0`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,7 @@ Measured at `d2852f9a42c2` (specs `sha256:2730ac4791a0`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **The analysis names the file a change still has to create** *(new in 0.35.15)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.missingNewFiles` every relative import a changed TypeScript/JavaScript file newly introduces that resolves to nothing — the importing file, the specifier and the candidate paths. Deterministic and read-only. On two unseen windows of a public TypeScript monorepo every naming was a file the change did create (precision 1.000), covering 78–86% of the not-yet-existing files an incomplete change set was missing. Only uncommitted changes in a git repository; other languages, bare package names and path aliases are not read.
26
27
  - **ES-module TypeScript projects get their import graph** *(new in 0.35.14 — fix)*: a specifier written `./x.js` for a `x.ts` source (the ESM convention) now resolves, where it used to emit no edge at all — on a public TypeScript monorepo the graph went from 3 import edges to 4,628 of 6,854 import relations. Extensionless projects are unchanged. The cycle ratchet sees the same edges. Workspace package names are still unresolved, and the graded impact list does not yet use import edges.
27
28
  - **The impact list also knows where work is concentrating, and a release cannot ship a stale badge** *(new in 0.35.13)*: for a named change, `impacts.rankedImpact` is fused once more with each file's recency-weighted change frequency (same single `git log`; rows may carry `changeFrequency`). On 703 replayed changes neither corpus had been measured on before, recall among the ten rose 0.485 → 0.545 and 0.378 → 0.540 on a second, Python repository (both above the minimum detectable effect) and 0.521 → 0.551 / 0.419 → 0.477 here; precision rose detectably on all four windows. Stated plainly: against the modelled human engineer this project aims at (`docs/NORTH-STAR.md` — recall 0.67–0.78, precision ≈ 0.9) recall is still below the band and precision about a sixth. Separately, `npm publish` now refuses when the README shows the attest badge and `.ax/badges/traced.svg` was not re-measured since the previous release.
28
29
  - **What else moves when you change this file — ranked by history too** *(new in 0.35.12)*: when `maintenance_analyze` is given `changedFiles`, its graded impact list (`impacts.rankedImpact`) fuses the call-graph ranking with recency-weighted co-change from git history (files committed together with the changed ones, recent commits counting more). On replayed changes of a second, Python repository a file that really changed with the named one is among the ten shown with recall 0.44 instead of 0.34 (beyond the minimum detectable difference, and replicated on further changes); on this repository the difference is positive and not detectable. Walking the call graph deeper was measured at the same time and not adopted: it reaches more and ranks worse.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 7bc430d2-muyiyuem
1
+ f167b18a-muypcwqp
@@ -48,6 +48,7 @@ const root_1 = require("../../project/root");
48
48
  const test_evidence_1 = require("../../review/test-evidence");
49
49
  const temporal_prior_1 = require("../../review/temporal-prior");
50
50
  const co_change_1 = require("../../review/co-change");
51
+ const missing_imports_1 = require("../../review/missing-imports");
51
52
  const test_files_1 = require("../../cpg/test-files");
52
53
  const commit_text_1 = require("../../review/commit-text");
53
54
  const bundler_1 = require("../../context/bundler");
@@ -58,6 +59,8 @@ const maintenance_analyze_1 = require("../maintenance-analyze");
58
59
  const maintenance_evidence_1 = require("../maintenance-evidence");
59
60
  const defuse_bound_1 = require("../defuse-bound");
60
61
  const bounded_io_1 = require("../../project/bounded-io");
62
+ /** @implements A-SPEC-759 — at most this many changed files have their HEAD text read for the missing-new-file finding. */
63
+ const MISSING_NEW_FILES_PRIOR_READS = 50;
61
64
  function createMaintenanceAnalysisHandlers(context) {
62
65
  return {
63
66
  async maintenance_analyze(a) {
@@ -232,11 +235,42 @@ function createMaintenanceAnalysisHandlers(context) {
232
235
  }
233
236
  catch { /* the graph ranking alone */ }
234
237
  }
238
+ // @implements A-SPEC-759 — the file the change still has to create: a relative import a changed
239
+ // file newly introduces that resolves nowhere. The earlier text is HEAD's; a path absent at
240
+ // HEAD is a new file (null), any other failure is unknown (undefined) and names nothing.
241
+ let missing = [];
242
+ if (head !== '' && (a.changedFiles?.length ?? 0) > 0) {
243
+ try {
244
+ const git = (args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] });
245
+ let reads = 0;
246
+ missing = (0, missing_imports_1.missingNewFiles)({
247
+ scanned,
248
+ changedFiles: a.changedFiles.filter((file) => typeof file === 'string'),
249
+ priorText: (file) => {
250
+ if (reads++ >= MISSING_NEW_FILES_PRIOR_READS)
251
+ return undefined;
252
+ try {
253
+ return git(['show', `HEAD:${file}`]);
254
+ }
255
+ catch { /* absent at HEAD, or unreadable — told apart below */ }
256
+ try {
257
+ return git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
258
+ }
259
+ catch {
260
+ return undefined;
261
+ }
262
+ },
263
+ exists: (repoPath) => fs.existsSync(path.join(root, repoPath)),
264
+ });
265
+ }
266
+ catch { /* no finding */ }
267
+ }
235
268
  const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
236
269
  semantic,
237
270
  ...common,
238
271
  ...(coChange !== undefined ? { coChange } : {}),
239
272
  ...(changeFrequency !== undefined ? { changeFrequency } : {}),
273
+ ...(missing.length > 0 ? { missingNewFiles: missing } : {}),
240
274
  coverage: { ...common.coverage, historyStatus },
241
275
  history,
242
276
  changePrior,
@@ -116,6 +116,17 @@ export interface MaintenanceAnalysisInput {
116
116
  * to rank `impacts.rankedImpact`, after co-change.
117
117
  */
118
118
  changeFrequency?: Record<string, number>;
119
+ /**
120
+ * @implements A-SPEC-759
121
+ * Relative imports the change newly introduces that resolve nowhere (`review/missing-imports.ts`),
122
+ * computed by the caller, which alone can read the earlier text and the working tree. Carried into
123
+ * `impacts.missingNewFiles`; it touches no ranking.
124
+ */
125
+ missingNewFiles?: Array<{
126
+ from: string;
127
+ specifier: string;
128
+ candidates: string[];
129
+ }>;
119
130
  /**
120
131
  * @implements A-SPEC-388
121
132
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -344,6 +355,17 @@ export interface MaintenanceAnalysis {
344
355
  * reporting — and, by A-SPEC-274's rule, being affected is still not being a candidate.
345
356
  */
346
357
  importedByFiles: string[];
358
+ /**
359
+ * @implements A-SPEC-759
360
+ * Files the change still has to CREATE: a changed file newly imports each `specifier` and none
361
+ * of the `candidates` exists. Deterministic, and present only when there is one — no ranking
362
+ * over existing files can name a file that is not there.
363
+ */
364
+ missingNewFiles?: Array<{
365
+ from: string;
366
+ specifier: string;
367
+ candidates: string[];
368
+ }>;
347
369
  /**
348
370
  * @implements A-SPEC-290
349
371
  * Which impacted contracts were actually OBSERVED executing, and whether that observation can
@@ -1230,6 +1230,7 @@ function analyzeMaintenance(input) {
1230
1230
  impactedFiles: reachableTier,
1231
1231
  rankedImpact,
1232
1232
  importedByFiles,
1233
+ ...((input.missingNewFiles?.length ?? 0) > 0 ? { missingNewFiles: input.missingNewFiles } : {}),
1233
1234
  unresolvedRelations: input.resolution ?? null,
1234
1235
  runtimeObserved: {
1235
1236
  status: runtimeStatus,
@@ -0,0 +1,17 @@
1
+ import { type ScannedFile } from '../cpg/cpg-scanner';
2
+ export interface MissingNewFile {
3
+ from: string;
4
+ specifier: string;
5
+ candidates: string[];
6
+ }
7
+ export interface MissingNewFilesInput {
8
+ scanned: readonly ScannedFile[];
9
+ changedFiles: readonly string[];
10
+ /** The file's text before the change; `null` when it did not exist; `undefined` when unknown — unknown names nothing. */
11
+ priorText: (file: string) => string | null | undefined;
12
+ /** Does this repo-relative POSIX path exist in the working tree (scanned or not)? */
13
+ exists: (repoPath: string) => boolean;
14
+ }
15
+ export declare const MISSING_NEW_FILES_MAX = 20;
16
+ export declare const MISSING_NEW_FILE_CANDIDATES = 4;
17
+ export declare function missingNewFiles(input: MissingNewFilesInput): MissingNewFile[];
@@ -0,0 +1,140 @@
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.MISSING_NEW_FILE_CANDIDATES = exports.MISSING_NEW_FILES_MAX = void 0;
37
+ exports.missingNewFiles = missingNewFiles;
38
+ // @implements A-SPEC-759
39
+ /**
40
+ * The file a change still has to create.
41
+ *
42
+ * Of the files an incomplete change set is missing, 6–12% do not exist yet, and no ranking over
43
+ * existing files can name them. The change often states the gap itself: it imports a module that
44
+ * resolves nowhere. Measured before this was built (north-star goal document, H12/H12b): reading
45
+ * EVERY unresolved import of a changed file had precision 0.46–0.83, and every wrong naming was an
46
+ * import already unresolved before the change — build-generated modules, import text inside
47
+ * strings. Restricting to what the change INTRODUCED gave 1.000 on two unseen windows (24/24,
48
+ * 36/36). Hence the two rules below that look redundant and are not: the scanner's imports rather
49
+ * than a text match, and the earlier text as a veto.
50
+ */
51
+ const path = __importStar(require("node:path"));
52
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
53
+ const import_resolver_1 = require("../cpg/import-resolver");
54
+ exports.MISSING_NEW_FILES_MAX = 20;
55
+ exports.MISSING_NEW_FILE_CANDIDATES = 4;
56
+ const SCRIPT_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
57
+ const SOURCE_OF_EMITTED = [
58
+ ['.js', ['.ts', '.tsx']], ['.jsx', ['.tsx']], ['.mjs', ['.mts']], ['.cjs', ['.cts']],
59
+ ];
60
+ const APPENDED = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
61
+ // @implements A-SPEC-759.1 — a declaration file answers an import. Replayed on a second public
62
+ // corpus, `../types/anymatch` was named although `anymatch.d.ts` had always been there.
63
+ const DECLARATIONS = ['.d.ts', '.d.mts', '.d.cts'];
64
+ const DECLARATION_OF_EMITTED = [
65
+ ['.js', '.d.ts'], ['.jsx', '.d.ts'], ['.mjs', '.d.mts'], ['.cjs', '.d.cts'],
66
+ ];
67
+ function candidatesOf(fromFile, specifier) {
68
+ const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
69
+ if (base === '..' || base.startsWith('../') || base === '.' || base === '')
70
+ return null; // leaves the repository
71
+ // @implements A-SPEC-759.1 — build and vendor output (`../dist/lib/x`) is never part of a change
72
+ // set; the scanner's own skip set says what counts, so there is one definition of it.
73
+ if ((0, cpg_scanner_1.isUnderSkippedDir)(`${base}/x`))
74
+ return null;
75
+ const out = [base];
76
+ for (const [emitted, sources] of SOURCE_OF_EMITTED) {
77
+ if (base.endsWith(emitted))
78
+ for (const ext of sources)
79
+ out.push(`${base.slice(0, -emitted.length)}${ext}`);
80
+ }
81
+ for (const ext of APPENDED)
82
+ out.push(`${base}${ext}`);
83
+ for (const ext of APPENDED)
84
+ out.push(`${base}/index${ext}`);
85
+ return [...new Set(out)];
86
+ }
87
+ /** Paths consulted for existence only — never handed back as a candidate to create. */
88
+ function declarationsOf(base) {
89
+ const out = [];
90
+ for (const [emitted, declaration] of DECLARATION_OF_EMITTED) {
91
+ if (base.endsWith(emitted))
92
+ out.push(`${base.slice(0, -emitted.length)}${declaration}`);
93
+ }
94
+ for (const ext of DECLARATIONS)
95
+ out.push(`${base}${ext}`);
96
+ out.push(`${base}/index.d.ts`);
97
+ return out;
98
+ }
99
+ function missingNewFiles(input) {
100
+ if (input.changedFiles.length === 0)
101
+ return [];
102
+ const changed = new Set(input.changedFiles);
103
+ const { resolve } = (0, import_resolver_1.createImportResolver)(input.scanned);
104
+ const rows = [];
105
+ for (const file of input.scanned) {
106
+ if (!changed.has(file.sourcePath) || !SCRIPT_FILE.test(file.sourcePath))
107
+ continue;
108
+ let prior;
109
+ let priorRead = false;
110
+ const seen = new Set();
111
+ for (const edge of file.edges ?? []) {
112
+ if (edge.rel !== 'imports')
113
+ continue;
114
+ const specifier = edge.to;
115
+ if (!(specifier.startsWith('./') || specifier.startsWith('../')) || seen.has(specifier))
116
+ continue;
117
+ seen.add(specifier);
118
+ if (resolve(file.sourcePath, specifier) !== null)
119
+ continue;
120
+ const candidates = candidatesOf(file.sourcePath, specifier);
121
+ if (candidates === null || candidates.some((candidate) => input.exists(candidate)))
122
+ continue;
123
+ if (declarationsOf(candidates[0]).some((declaration) => input.exists(declaration)))
124
+ continue;
125
+ // Read once per file, and only when something survived this far — most changed files never ask.
126
+ if (!priorRead) {
127
+ prior = input.priorText(file.sourcePath);
128
+ priorRead = true;
129
+ }
130
+ if (prior === undefined)
131
+ break;
132
+ if (prior !== null && (prior.includes(`'${specifier}'`) || prior.includes(`"${specifier}"`) || prior.includes(`\`${specifier}\``)))
133
+ continue;
134
+ rows.push({ from: file.sourcePath, specifier, candidates: candidates.slice(0, exports.MISSING_NEW_FILE_CANDIDATES) });
135
+ }
136
+ }
137
+ return rows
138
+ .sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : a.specifier < b.specifier ? -1 : a.specifier > b.specifier ? 1 : 0))
139
+ .slice(0, exports.MISSING_NEW_FILES_MAX);
140
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.14",
4
+ "version": "0.35.15",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",