@holmes-lab/holmes-kit 0.35.15 → 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,26 @@ 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
+
8
28
  ## [0.35.15] - 2026-10-08
9
29
 
10
30
  ### Added
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
- **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`.
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,7 @@ Measured at `843876d688fe` (specs `sha256:5f2dfff7ced0`) — 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.
26
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.
27
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.
28
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.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- f167b18a-muypcwqp
1
+ 68181d77-muyuet0q
@@ -49,6 +49,7 @@ 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
51
  const missing_imports_1 = require("../../review/missing-imports");
52
+ const removed_names_1 = require("../../review/removed-names");
52
53
  const test_files_1 = require("../../cpg/test-files");
53
54
  const commit_text_1 = require("../../review/commit-text");
54
55
  const bundler_1 = require("../../context/bundler");
@@ -238,29 +239,49 @@ function createMaintenanceAnalysisHandlers(context) {
238
239
  // @implements A-SPEC-759 — the file the change still has to create: a relative import a changed
239
240
  // file newly introduces that resolves nowhere. The earlier text is HEAD's; a path absent at
240
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.
241
245
  let missing = [];
246
+ let broken = [];
242
247
  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 */ }
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
256
261
  try {
257
- return git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
262
+ text = git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
258
263
  }
259
264
  catch {
260
- return undefined;
265
+ text = undefined;
261
266
  }
262
- },
263
- exists: (repoPath) => fs.existsSync(path.join(root, repoPath)),
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
+ } },
264
285
  });
265
286
  }
266
287
  catch { /* no finding */ }
@@ -271,6 +292,7 @@ function createMaintenanceAnalysisHandlers(context) {
271
292
  ...(coChange !== undefined ? { coChange } : {}),
272
293
  ...(changeFrequency !== undefined ? { changeFrequency } : {}),
273
294
  ...(missing.length > 0 ? { missingNewFiles: missing } : {}),
295
+ ...(broken.length > 0 ? { removedNameUsers: broken } : {}),
274
296
  coverage: { ...common.coverage, historyStatus },
275
297
  history,
276
298
  changePrior,
@@ -127,6 +127,16 @@ export interface MaintenanceAnalysisInput {
127
127
  specifier: string;
128
128
  candidates: string[];
129
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
+ }>;
130
140
  /**
131
141
  * @implements A-SPEC-388
132
142
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -366,6 +376,17 @@ export interface MaintenanceAnalysis {
366
376
  specifier: string;
367
377
  candidates: string[];
368
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
+ }>;
369
390
  /**
370
391
  * @implements A-SPEC-290
371
392
  * Which impacted contracts were actually OBSERVED executing, and whether that observation can
@@ -1231,6 +1231,7 @@ function analyzeMaintenance(input) {
1231
1231
  rankedImpact,
1232
1232
  importedByFiles,
1233
1233
  ...((input.missingNewFiles?.length ?? 0) > 0 ? { missingNewFiles: input.missingNewFiles } : {}),
1234
+ ...((input.removedNameUsers?.length ?? 0) > 0 ? { removedNameUsers: input.removedNameUsers } : {}),
1234
1235
  unresolvedRelations: input.resolution ?? null,
1235
1236
  runtimeObserved: {
1236
1237
  status: runtimeStatus,
@@ -14,4 +14,6 @@ export interface MissingNewFilesInput {
14
14
  }
15
15
  export declare const MISSING_NEW_FILES_MAX = 20;
16
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;
17
19
  export declare function missingNewFiles(input: MissingNewFilesInput): MissingNewFile[];
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.MISSING_NEW_FILE_CANDIDATES = exports.MISSING_NEW_FILES_MAX = void 0;
37
+ exports.candidatesOf = candidatesOf;
37
38
  exports.missingNewFiles = missingNewFiles;
38
39
  // @implements A-SPEC-759
39
40
  /**
@@ -64,6 +65,7 @@ const DECLARATIONS = ['.d.ts', '.d.mts', '.d.cts'];
64
65
  const DECLARATION_OF_EMITTED = [
65
66
  ['.js', '.d.ts'], ['.jsx', '.d.ts'], ['.mjs', '.d.mts'], ['.cjs', '.d.cts'],
66
67
  ];
68
+ /** Exported for A-SPEC-759.2, which asks the inverse question: which import pointed at a file that is gone. */
67
69
  function candidatesOf(fromFile, specifier) {
68
70
  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
69
71
  if (base === '..' || base.startsWith('../') || base === '.' || base === '')
@@ -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.15",
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",