@holmes-lab/holmes-kit 0.35.14 → 0.35.16

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,51 @@ 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.16] - 2026-10-08
9
+
10
+ ### Added
11
+
12
+ - **`maintenance_analyze` names the unchanged files a change has broken** (A-SPEC-759.2). When `changedFiles` is
13
+ given and a changed TypeScript/JavaScript or Python file no longer defines a top-level name it defined at HEAD —
14
+ removed or renamed, and not written anywhere in the file any more — every unchanged file that imports the changed
15
+ file and still has that name as a word is reported under `impacts.removedNameUsers` as `{ file, imports, name }`.
16
+ A changed TypeScript/JavaScript file that was deleted names the files whose relative imports pointed at it.
17
+ Measured through the product function against every path each commit touched: 22 files named on a public
18
+ TypeScript repository and 21 on a public Python repository, all of them files the commit did change (precision
19
+ 1.000 on both), 8 of 8 on a third window. It fires rarely and unevenly: it recovers 7.4% of the files an
20
+ incomplete change set was missing on the Python repository and 2–2.5% on the TypeScript ones. The evidence is
21
+ deliberately coarse — imports the file, has the name as a word. In the same measurement following resolved call
22
+ edges from the removed symbol scored 0.46–1.00, removed member names 0.26–0.86 and any changed declaration head
23
+ 0.19–0.62; none of those is built. **What this does not do:** member names and changed signatures are not read;
24
+ a deleted Python module is not followed; a change already committed shows nothing; outside version control
25
+ nothing is named; a type checker reports the same breakage in TypeScript once it is run (Python has none).
26
+ Rankings, classification and every gate are unchanged.
27
+
28
+ ## [0.35.15] - 2026-10-08
29
+
30
+ ### Added
31
+
32
+ - **`maintenance_analyze` names the file a change still has to create** (A-SPEC-759, A-SPEC-759.1). When
33
+ `changedFiles` is given, a relative import that a changed TypeScript/JavaScript file newly introduces and that
34
+ resolves to nothing — no scanned file, no file on disk in any resolvable form, declaration files included, and
35
+ not a path inside a build or vendor directory — is reported under `impacts.missingNewFiles` as
36
+ `{ from, specifier, candidates }`. No ranking over existing files can name a file that is not there, and of the
37
+ files an incomplete change set is missing 6–12% do not exist yet. Measured through the product function on two
38
+ windows of a public TypeScript monorepo that no earlier measurement had used (140 and 143 changes of three or
39
+ more files, a third of each hidden): every naming was a file the change did create (precision 1.000 on both) and
40
+ 78–86% of the not-yet-existing missing files were named — 7–8% of all missing files, at no cost in precision.
41
+ On a second public TypeScript repository seen for the first time (229 changes) the first build scored 0.908
42
+ (79/87): five of the eight were files the commit did create that the scoring does not count, one was a
43
+ declaration file that had always existed, two were imports of build output — the last two kinds are what
44
+ A-SPEC-759.1 removes, leaving no namings of a file that was not created.
45
+ "Newly introduced" is the rule that makes it exact: reading every unresolved import instead had precision
46
+ 0.46–0.83, all of the wrong namings being imports already unresolved before the change (build-generated modules,
47
+ import text inside strings). The earlier text is HEAD's, read with one `git show` per changed file that has a
48
+ surviving import (at most 50); the list is cut to 20 rows. **What this does not do:** a change already committed
49
+ shows nothing (HEAD holds it); outside version control nothing is named; Python, Go, Rust and Java import forms,
50
+ bare package names and path aliases are not read; a type checker reports the same gap once it is run. Rankings,
51
+ classification and every gate are unchanged.
52
+
8
53
  ## [0.35.14] - 2026-10-08
9
54
 
10
55
  ### 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
+ **448/454** source files (98.6%) trace to an approved spec · **756/819** approved A-SPECs (92.3%) are anchored from code.
13
+ Measured at `13ef32c36276` (specs `sha256:613dcd17da1a`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,8 @@ 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 unchanged files a change has broken** *(new in 0.35.16)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.removedNameUsers` every unchanged file that imports a changed file and still uses a top-level name that file no longer defines (removed or renamed), and the files still importing a deleted TypeScript/JavaScript file. Deterministic and read-only; TypeScript/JavaScript and Python. Measured on public repositories: every file named was one the commit did change (22 of 22, 21 of 21). It fires rarely — 2–7% of the files an incomplete change set was missing. Member names and changed signatures are not read.
27
+ - **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
28
  - **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
29
  - **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
30
  - **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
+ 68181d77-muyuet0q
@@ -48,6 +48,8 @@ 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");
52
+ const removed_names_1 = require("../../review/removed-names");
51
53
  const test_files_1 = require("../../cpg/test-files");
52
54
  const commit_text_1 = require("../../review/commit-text");
53
55
  const bundler_1 = require("../../context/bundler");
@@ -58,6 +60,8 @@ const maintenance_analyze_1 = require("../maintenance-analyze");
58
60
  const maintenance_evidence_1 = require("../maintenance-evidence");
59
61
  const defuse_bound_1 = require("../defuse-bound");
60
62
  const bounded_io_1 = require("../../project/bounded-io");
63
+ /** @implements A-SPEC-759 — at most this many changed files have their HEAD text read for the missing-new-file finding. */
64
+ const MISSING_NEW_FILES_PRIOR_READS = 50;
61
65
  function createMaintenanceAnalysisHandlers(context) {
62
66
  return {
63
67
  async maintenance_analyze(a) {
@@ -232,11 +236,63 @@ function createMaintenanceAnalysisHandlers(context) {
232
236
  }
233
237
  catch { /* the graph ranking alone */ }
234
238
  }
239
+ // @implements A-SPEC-759 — the file the change still has to create: a relative import a changed
240
+ // file newly introduces that resolves nowhere. The earlier text is HEAD's; a path absent at
241
+ // HEAD is a new file (null), any other failure is unknown (undefined) and names nothing.
242
+ // @implements A-SPEC-759.2 — and the unchanged files the change has broken: they import a
243
+ // changed file and still use a top-level name it no longer defines. Both findings read each
244
+ // changed file's HEAD text at most once, through one memo and one bound.
245
+ let missing = [];
246
+ let broken = [];
247
+ if (head !== '' && (a.changedFiles?.length ?? 0) > 0) {
248
+ const changed = a.changedFiles.filter((file) => typeof file === 'string');
249
+ 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'] });
250
+ const priorMemo = new Map();
251
+ const priorText = (file) => {
252
+ if (priorMemo.has(file))
253
+ return priorMemo.get(file);
254
+ let text;
255
+ if (priorMemo.size < MISSING_NEW_FILES_PRIOR_READS) {
256
+ try {
257
+ text = git(['show', `HEAD:${file}`]);
258
+ }
259
+ catch {
260
+ // absent at HEAD (a new file), or unreadable — told apart here
261
+ try {
262
+ text = git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
263
+ }
264
+ catch {
265
+ text = undefined;
266
+ }
267
+ }
268
+ }
269
+ priorMemo.set(file, text);
270
+ return text;
271
+ };
272
+ try {
273
+ missing = (0, missing_imports_1.missingNewFiles)({ scanned, changedFiles: changed, priorText, exists: (repoPath) => fs.existsSync(path.join(root, repoPath)) });
274
+ }
275
+ catch { /* no finding */ }
276
+ try {
277
+ broken = (0, removed_names_1.removedNameUsers)({
278
+ scanned, changedFiles: changed, priorText,
279
+ currentText: (file) => { try {
280
+ return fs.readFileSync(path.join(root, file), 'utf8');
281
+ }
282
+ catch {
283
+ return null;
284
+ } },
285
+ });
286
+ }
287
+ catch { /* no finding */ }
288
+ }
235
289
  const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
236
290
  semantic,
237
291
  ...common,
238
292
  ...(coChange !== undefined ? { coChange } : {}),
239
293
  ...(changeFrequency !== undefined ? { changeFrequency } : {}),
294
+ ...(missing.length > 0 ? { missingNewFiles: missing } : {}),
295
+ ...(broken.length > 0 ? { removedNameUsers: broken } : {}),
240
296
  coverage: { ...common.coverage, historyStatus },
241
297
  history,
242
298
  changePrior,
@@ -116,6 +116,27 @@ 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
+ }>;
130
+ /**
131
+ * @implements A-SPEC-759.2
132
+ * Unchanged files that still use a top-level name a changed file no longer defines
133
+ * (`review/removed-names.ts`), computed by the caller. Carried into `impacts.removedNameUsers`.
134
+ */
135
+ removedNameUsers?: Array<{
136
+ file: string;
137
+ imports: string;
138
+ name: string;
139
+ }>;
119
140
  /**
120
141
  * @implements A-SPEC-388
121
142
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -344,6 +365,28 @@ export interface MaintenanceAnalysis {
344
365
  * reporting — and, by A-SPEC-274's rule, being affected is still not being a candidate.
345
366
  */
346
367
  importedByFiles: string[];
368
+ /**
369
+ * @implements A-SPEC-759
370
+ * Files the change still has to CREATE: a changed file newly imports each `specifier` and none
371
+ * of the `candidates` exists. Deterministic, and present only when there is one — no ranking
372
+ * over existing files can name a file that is not there.
373
+ */
374
+ missingNewFiles?: Array<{
375
+ from: string;
376
+ specifier: string;
377
+ candidates: string[];
378
+ }>;
379
+ /**
380
+ * @implements A-SPEC-759.2
381
+ * Files the change has BROKEN and not touched: `file` imports the changed file `imports` and
382
+ * still uses `name`, a top-level name that file no longer defines. Deterministic; present only
383
+ * when there is one.
384
+ */
385
+ removedNameUsers?: Array<{
386
+ file: string;
387
+ imports: string;
388
+ name: string;
389
+ }>;
347
390
  /**
348
391
  * @implements A-SPEC-290
349
392
  * Which impacted contracts were actually OBSERVED executing, and whether that observation can
@@ -1230,6 +1230,8 @@ function analyzeMaintenance(input) {
1230
1230
  impactedFiles: reachableTier,
1231
1231
  rankedImpact,
1232
1232
  importedByFiles,
1233
+ ...((input.missingNewFiles?.length ?? 0) > 0 ? { missingNewFiles: input.missingNewFiles } : {}),
1234
+ ...((input.removedNameUsers?.length ?? 0) > 0 ? { removedNameUsers: input.removedNameUsers } : {}),
1233
1235
  unresolvedRelations: input.resolution ?? null,
1234
1236
  runtimeObserved: {
1235
1237
  status: runtimeStatus,
@@ -0,0 +1,19 @@
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
+ /** Exported for A-SPEC-759.2, which asks the inverse question: which import pointed at a file that is gone. */
18
+ export declare function candidatesOf(fromFile: string, specifier: string): string[] | null;
19
+ export declare function missingNewFiles(input: MissingNewFilesInput): MissingNewFile[];
@@ -0,0 +1,142 @@
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.candidatesOf = candidatesOf;
38
+ exports.missingNewFiles = missingNewFiles;
39
+ // @implements A-SPEC-759
40
+ /**
41
+ * The file a change still has to create.
42
+ *
43
+ * Of the files an incomplete change set is missing, 6–12% do not exist yet, and no ranking over
44
+ * existing files can name them. The change often states the gap itself: it imports a module that
45
+ * resolves nowhere. Measured before this was built (north-star goal document, H12/H12b): reading
46
+ * EVERY unresolved import of a changed file had precision 0.46–0.83, and every wrong naming was an
47
+ * import already unresolved before the change — build-generated modules, import text inside
48
+ * strings. Restricting to what the change INTRODUCED gave 1.000 on two unseen windows (24/24,
49
+ * 36/36). Hence the two rules below that look redundant and are not: the scanner's imports rather
50
+ * than a text match, and the earlier text as a veto.
51
+ */
52
+ const path = __importStar(require("node:path"));
53
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
54
+ const import_resolver_1 = require("../cpg/import-resolver");
55
+ exports.MISSING_NEW_FILES_MAX = 20;
56
+ exports.MISSING_NEW_FILE_CANDIDATES = 4;
57
+ const SCRIPT_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
58
+ const SOURCE_OF_EMITTED = [
59
+ ['.js', ['.ts', '.tsx']], ['.jsx', ['.tsx']], ['.mjs', ['.mts']], ['.cjs', ['.cts']],
60
+ ];
61
+ const APPENDED = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
62
+ // @implements A-SPEC-759.1 — a declaration file answers an import. Replayed on a second public
63
+ // corpus, `../types/anymatch` was named although `anymatch.d.ts` had always been there.
64
+ const DECLARATIONS = ['.d.ts', '.d.mts', '.d.cts'];
65
+ const DECLARATION_OF_EMITTED = [
66
+ ['.js', '.d.ts'], ['.jsx', '.d.ts'], ['.mjs', '.d.mts'], ['.cjs', '.d.cts'],
67
+ ];
68
+ /** Exported for A-SPEC-759.2, which asks the inverse question: which import pointed at a file that is gone. */
69
+ function candidatesOf(fromFile, specifier) {
70
+ const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
71
+ if (base === '..' || base.startsWith('../') || base === '.' || base === '')
72
+ return null; // leaves the repository
73
+ // @implements A-SPEC-759.1 — build and vendor output (`../dist/lib/x`) is never part of a change
74
+ // set; the scanner's own skip set says what counts, so there is one definition of it.
75
+ if ((0, cpg_scanner_1.isUnderSkippedDir)(`${base}/x`))
76
+ return null;
77
+ const out = [base];
78
+ for (const [emitted, sources] of SOURCE_OF_EMITTED) {
79
+ if (base.endsWith(emitted))
80
+ for (const ext of sources)
81
+ out.push(`${base.slice(0, -emitted.length)}${ext}`);
82
+ }
83
+ for (const ext of APPENDED)
84
+ out.push(`${base}${ext}`);
85
+ for (const ext of APPENDED)
86
+ out.push(`${base}/index${ext}`);
87
+ return [...new Set(out)];
88
+ }
89
+ /** Paths consulted for existence only — never handed back as a candidate to create. */
90
+ function declarationsOf(base) {
91
+ const out = [];
92
+ for (const [emitted, declaration] of DECLARATION_OF_EMITTED) {
93
+ if (base.endsWith(emitted))
94
+ out.push(`${base.slice(0, -emitted.length)}${declaration}`);
95
+ }
96
+ for (const ext of DECLARATIONS)
97
+ out.push(`${base}${ext}`);
98
+ out.push(`${base}/index.d.ts`);
99
+ return out;
100
+ }
101
+ function missingNewFiles(input) {
102
+ if (input.changedFiles.length === 0)
103
+ return [];
104
+ const changed = new Set(input.changedFiles);
105
+ const { resolve } = (0, import_resolver_1.createImportResolver)(input.scanned);
106
+ const rows = [];
107
+ for (const file of input.scanned) {
108
+ if (!changed.has(file.sourcePath) || !SCRIPT_FILE.test(file.sourcePath))
109
+ continue;
110
+ let prior;
111
+ let priorRead = false;
112
+ const seen = new Set();
113
+ for (const edge of file.edges ?? []) {
114
+ if (edge.rel !== 'imports')
115
+ continue;
116
+ const specifier = edge.to;
117
+ if (!(specifier.startsWith('./') || specifier.startsWith('../')) || seen.has(specifier))
118
+ continue;
119
+ seen.add(specifier);
120
+ if (resolve(file.sourcePath, specifier) !== null)
121
+ continue;
122
+ const candidates = candidatesOf(file.sourcePath, specifier);
123
+ if (candidates === null || candidates.some((candidate) => input.exists(candidate)))
124
+ continue;
125
+ if (declarationsOf(candidates[0]).some((declaration) => input.exists(declaration)))
126
+ continue;
127
+ // Read once per file, and only when something survived this far — most changed files never ask.
128
+ if (!priorRead) {
129
+ prior = input.priorText(file.sourcePath);
130
+ priorRead = true;
131
+ }
132
+ if (prior === undefined)
133
+ break;
134
+ if (prior !== null && (prior.includes(`'${specifier}'`) || prior.includes(`"${specifier}"`) || prior.includes(`\`${specifier}\``)))
135
+ continue;
136
+ rows.push({ from: file.sourcePath, specifier, candidates: candidates.slice(0, exports.MISSING_NEW_FILE_CANDIDATES) });
137
+ }
138
+ }
139
+ return rows
140
+ .sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : a.specifier < b.specifier ? -1 : a.specifier > b.specifier ? 1 : 0))
141
+ .slice(0, exports.MISSING_NEW_FILES_MAX);
142
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The unchanged files a change has just broken.
3
+ *
4
+ * `missing-imports` names the file a change still has to create. The same necessity runs the other
5
+ * way: a change that removes or renames a top-level name leaves every file that imports the changed
6
+ * file and still uses that name in need of a change too. Measured before this was built (north-star
7
+ * goal document, H11), against every path each commit touched: 22 namings on a public TypeScript
8
+ * repository and 30 on a public Python repository, all correct, and 13 more on four smaller windows.
9
+ *
10
+ * The evidence is deliberately coarse — "imports the file" and "has the name as a word" — and the
11
+ * precise alternative lost: following resolved call edges from the removed symbol scored 0.46–1.00
12
+ * in the same measurement, because a member call is resolved by name. Hence top-level names only,
13
+ * and no call graph.
14
+ */
15
+ import { type ScannedFile } from '../cpg/cpg-scanner';
16
+ export interface RemovedNameUser {
17
+ file: string;
18
+ imports: string;
19
+ name: string;
20
+ }
21
+ export interface RemovedNameUsersInput {
22
+ scanned: readonly ScannedFile[];
23
+ changedFiles: readonly string[];
24
+ /** The file's text before the change; `null` when it did not exist; `undefined` when unknown. Both name nothing. */
25
+ priorText: (file: string) => string | null | undefined;
26
+ /** The file's text in the working tree; `null` when it is not there. */
27
+ currentText: (file: string) => string | null;
28
+ /** Top-level names a text defines. Defaults to the product parser; injected by tests. */
29
+ topLevelNames?: (code: string, file: string) => string[];
30
+ }
31
+ export declare const REMOVED_NAME_USERS_MAX = 20;
32
+ export declare function removedNameUsers(input: RemovedNameUsersInput): RemovedNameUser[];
@@ -0,0 +1,110 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REMOVED_NAME_USERS_MAX = void 0;
4
+ exports.removedNameUsers = removedNameUsers;
5
+ // @implements A-SPEC-759.2
6
+ /**
7
+ * The unchanged files a change has just broken.
8
+ *
9
+ * `missing-imports` names the file a change still has to create. The same necessity runs the other
10
+ * way: a change that removes or renames a top-level name leaves every file that imports the changed
11
+ * file and still uses that name in need of a change too. Measured before this was built (north-star
12
+ * goal document, H11), against every path each commit touched: 22 namings on a public TypeScript
13
+ * repository and 30 on a public Python repository, all correct, and 13 more on four smaller windows.
14
+ *
15
+ * The evidence is deliberately coarse — "imports the file" and "has the name as a word" — and the
16
+ * precise alternative lost: following resolved call edges from the removed symbol scored 0.46–1.00
17
+ * in the same measurement, because a member call is resolved by name. Hence top-level names only,
18
+ * and no call graph.
19
+ */
20
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
21
+ const import_resolver_1 = require("../cpg/import-resolver");
22
+ const language_parser_1 = require("../cpg/language-parser");
23
+ const missing_imports_1 = require("./missing-imports");
24
+ exports.REMOVED_NAME_USERS_MAX = 20;
25
+ const MIN_NAME_LENGTH = 3;
26
+ const SCRIPT_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
27
+ const READ_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py)$/;
28
+ function parsedTopLevelNames(code, file) {
29
+ return new language_parser_1.TreeSitterTsParser().extractSymbols(code, (0, cpg_scanner_1.langForPath)(file))
30
+ .map((symbol) => symbol.qualifiedName).filter((name) => !name.includes('.'));
31
+ }
32
+ const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
33
+ const wordOf = (name) => new RegExp(`(?<![\\w$])${escaped(name)}(?![\\w$])`);
34
+ function removedNameUsers(input) {
35
+ if (input.changedFiles.length === 0)
36
+ return [];
37
+ const changed = new Set(input.changedFiles);
38
+ const byPath = new Map(input.scanned.map((file) => [file.sourcePath, file]));
39
+ const namesIn = input.topLevelNames ?? parsedTopLevelNames;
40
+ // What each changed file no longer defines.
41
+ const removedBy = new Map();
42
+ const deletedScripts = new Set();
43
+ for (const file of changed) {
44
+ if (!READ_FILE.test(file))
45
+ continue;
46
+ const prior = input.priorText(file);
47
+ if (typeof prior !== 'string')
48
+ continue;
49
+ let earlier;
50
+ try {
51
+ earlier = namesIn(prior, file);
52
+ }
53
+ catch {
54
+ continue;
55
+ }
56
+ const scannedNow = byPath.get(file);
57
+ const current = input.currentText(file);
58
+ const still = new Set((scannedNow?.symbols ?? []).map((symbol) => symbol.qualifiedName));
59
+ const removed = [...new Set(earlier)]
60
+ .filter((name) => !name.includes('.') && name.length >= MIN_NAME_LENGTH && !still.has(name))
61
+ // A name still written in the file — re-exported, or turned into an alias the scanner does not list — is not gone.
62
+ .filter((name) => current === null || !wordOf(name).test(current))
63
+ .sort();
64
+ if (removed.length === 0)
65
+ continue;
66
+ removedBy.set(file, removed);
67
+ if (current === null && scannedNow === undefined && SCRIPT_FILE.test(file))
68
+ deletedScripts.add(file);
69
+ }
70
+ if (removedBy.size === 0)
71
+ return [];
72
+ const { resolve } = (0, import_resolver_1.createImportResolver)(input.scanned);
73
+ const rows = [];
74
+ for (const user of input.scanned) {
75
+ if (changed.has(user.sourcePath))
76
+ continue;
77
+ const targets = new Set();
78
+ for (const edge of user.edges ?? []) {
79
+ if (edge.rel !== 'imports')
80
+ continue;
81
+ const target = resolve(user.sourcePath, edge.to);
82
+ if (target !== null) {
83
+ if (removedBy.has(target))
84
+ targets.add(target);
85
+ continue;
86
+ }
87
+ // The import resolves to nothing: it may have pointed at a file this change deleted.
88
+ if (deletedScripts.size === 0 || !(edge.to.startsWith('./') || edge.to.startsWith('../')))
89
+ continue;
90
+ for (const candidate of (0, missing_imports_1.candidatesOf)(user.sourcePath, edge.to) ?? [])
91
+ if (deletedScripts.has(candidate))
92
+ targets.add(candidate);
93
+ }
94
+ if (targets.size === 0)
95
+ continue;
96
+ let text;
97
+ for (const target of [...targets].sort()) {
98
+ if (text === undefined)
99
+ text = input.currentText(user.sourcePath);
100
+ if (text === null)
101
+ break;
102
+ const name = removedBy.get(target).find((candidate) => wordOf(candidate).test(text));
103
+ if (name !== undefined)
104
+ rows.push({ file: user.sourcePath, imports: target, name });
105
+ }
106
+ }
107
+ return rows
108
+ .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.imports < b.imports ? -1 : a.imports > b.imports ? 1 : 0))
109
+ .slice(0, exports.REMOVED_NAME_USERS_MAX);
110
+ }
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.16",
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",