@crewhaus/tool-changeset 0.7.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.
package/dist/index.js ADDED
@@ -0,0 +1,528 @@
1
+ /**
2
+ * @crewhaus/tool-changeset — everything you can decide about a change set
3
+ * before it becomes a pull request.
4
+ *
5
+ * Two questions, both of which a model answers plausibly and incompletely:
6
+ *
7
+ * - `DiffLint`: does this change add anything the team already decided it
8
+ * does not want — a focused test, a `debugger`, a merge marker, a TODO
9
+ * nobody will find, a path that only exists on one laptop.
10
+ * - `DocsSymbolCheck`: does the documentation still name things the code
11
+ * still has.
12
+ *
13
+ * Both are review passes, and a review pass earns its place only by being
14
+ * boring: same change set, same findings, every time, with no judgement about
15
+ * whether the code is any good. Where a rule has to guess it says so, ships
16
+ * at warning severity, and can be turned off by name — a check that cries
17
+ * wolf is turned off wholesale, and then it catches nothing at all.
18
+ */
19
+ import { readFileSync, readdirSync, statSync } from "node:fs";
20
+ import { join, relative } from "node:path";
21
+ import { buildTool } from "@crewhaus/tool-builder";
22
+ import { parseUnifiedDiff } from "@crewhaus/tool-text";
23
+ import { z } from "zod";
24
+ import { MAX_DIFF_CHARS, MAX_TIMEOUT_MS, collectDiff } from "./git";
25
+ import { buildTokenIndex, checkRefs, extractDocRefs, } from "./lib/docs";
26
+ import { RULE_IDS, lintParsedDiff } from "./lib/rules";
27
+ import { ToolPermissionError, resolveSafe, toPosix, workspaceRoot } from "./paths";
28
+ /** Compact JSON — the reader is a model, not a person, so no indentation. */
29
+ const json = (value) => JSON.stringify(value);
30
+ const LIMITS = {
31
+ /** Documents read in one call. */
32
+ docs: 500,
33
+ /** Source files read in one call, before the scan is refused as incomplete. */
34
+ sourceFiles: 5_000,
35
+ /** A single file this big is not documentation or source. */
36
+ fileBytes: 4 * 1024 * 1024,
37
+ docChars: 4_000_000,
38
+ };
39
+ const SKIP_DIRS = new Set([
40
+ ".git",
41
+ "node_modules",
42
+ "dist",
43
+ "build",
44
+ "out",
45
+ "coverage",
46
+ "vendor",
47
+ "target",
48
+ ".next",
49
+ ".turbo",
50
+ ".venv",
51
+ "__pycache__",
52
+ ]);
53
+ // ---------------------------------------------------------------------------
54
+ // DiffLint
55
+ const ruleIdField = z.enum(RULE_IDS);
56
+ export const diffLint = buildTool({
57
+ name: "DiffLint",
58
+ description: "Run a policy pass over ONLY the added lines of a change set: focused tests, debugger statements, console.log, committed merge-conflict markers, new @ts-ignore, TODOs with no ticket, machine-specific absolute paths, CRLF, and files that added more than they should. Use it before committing or opening a pull request, in place of reading a diff and hoping to notice. Every finding carries the line number in the NEW file, so it can be fixed without re-reading anything. Give it `diff` text if you already have the patch; otherwise it runs `git diff` for you. The commented-out-code rule is a heuristic and is off unless you enable it.",
59
+ inputSchema: z.object({
60
+ diff: z
61
+ .string()
62
+ .max(MAX_DIFF_CHARS)
63
+ .optional()
64
+ .describe("unified diff text; pass this when you already have the patch"),
65
+ cwd: z.string().optional().describe("directory inside the workspace to run git in"),
66
+ ref: z.string().min(1).optional().describe("diff against this single ref"),
67
+ range: z.string().min(1).optional().describe("a commit range such as 'main...HEAD'"),
68
+ staged: z.boolean().optional().describe("diff the index against HEAD instead of the worktree"),
69
+ paths: z.array(z.string().min(1)).max(256).optional().describe("limit to these paths"),
70
+ timeout: z.number().int().positive().max(MAX_TIMEOUT_MS).optional(),
71
+ enable: z.array(ruleIdField).max(RULE_IDS.length).optional().describe("turn opt-in rules on"),
72
+ disable: z.array(ruleIdField).max(RULE_IDS.length).optional(),
73
+ ticketPattern: z
74
+ .string()
75
+ .max(400)
76
+ .optional()
77
+ .describe("regex a TODO must match to count as ticketed; default 'ABC-123', '#123' or a URL"),
78
+ machinePathPatterns: z
79
+ .array(z.string().max(400))
80
+ .max(32)
81
+ .optional()
82
+ .describe("extra machine-specific path shapes, as regex sources"),
83
+ maxLineChars: z.number().int().positive().max(100_000).optional().describe("default 1000"),
84
+ maxAddedLinesPerFile: z.number().int().positive().max(1_000_000).optional(),
85
+ maxFindings: z.number().int().positive().max(5_000).optional().describe("default 500"),
86
+ }),
87
+ readOnly: true,
88
+ concurrencySafe: true,
89
+ // Static flags describe the worst case: given `diff` text this tool spawns
90
+ // nothing, but the same tool can spawn git, and a capability that is
91
+ // sometimes true is true.
92
+ scope: "external",
93
+ ioCapability: "process",
94
+ execute: async (input, ctx) => {
95
+ const usesGit = input.cwd !== undefined ||
96
+ input.ref !== undefined ||
97
+ input.range !== undefined ||
98
+ input.staged !== undefined ||
99
+ input.paths !== undefined;
100
+ if (input.diff !== undefined && usesGit) {
101
+ return "DiffLint takes either `diff` text or a git selector (cwd/ref/range/staged/paths), not both — with the text in hand there is nothing for git to do.";
102
+ }
103
+ // Compiling the caller's patterns before anything else: a bad regex is a
104
+ // caller mistake, and it should be reported as one rather than as an
105
+ // empty result that looks like a clean change set.
106
+ let ticket;
107
+ if (input.ticketPattern !== undefined) {
108
+ try {
109
+ ticket = new RegExp(input.ticketPattern);
110
+ }
111
+ catch (err) {
112
+ return `DiffLint could not use ticketPattern /${input.ticketPattern}/: ${err.message}`;
113
+ }
114
+ }
115
+ const machinePatterns = [];
116
+ for (const source of input.machinePathPatterns ?? []) {
117
+ try {
118
+ machinePatterns.push(new RegExp(source));
119
+ }
120
+ catch (err) {
121
+ return `DiffLint could not use the machine-path pattern /${source}/: ${err.message}`;
122
+ }
123
+ }
124
+ let diffText;
125
+ let source;
126
+ let spawnTruncated = false;
127
+ if (input.diff !== undefined) {
128
+ diffText = input.diff;
129
+ source = "caller-supplied diff";
130
+ }
131
+ else {
132
+ const collected = await collectDiff("DiffLint", {
133
+ ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
134
+ ...(input.ref !== undefined ? { ref: input.ref } : {}),
135
+ ...(input.range !== undefined ? { range: input.range } : {}),
136
+ ...(input.staged !== undefined ? { staged: input.staged } : {}),
137
+ ...(input.paths !== undefined ? { paths: input.paths } : {}),
138
+ ...(input.timeout !== undefined ? { timeout: input.timeout } : {}),
139
+ }, ctx?.signal);
140
+ if (!collected.ok)
141
+ return collected.message;
142
+ diffText = collected.value.diff;
143
+ source = collected.value.command;
144
+ spawnTruncated = collected.value.truncated;
145
+ }
146
+ if (diffText.length > MAX_DIFF_CHARS) {
147
+ return `DiffLint refused a ${diffText.length}-character diff, over the ${MAX_DIFF_CHARS} limit — lint it a directory at a time with \`paths\`.`;
148
+ }
149
+ const parsed = parseUnifiedDiff(diffText);
150
+ const result = lintParsedDiff(parsed, {
151
+ ...(input.enable !== undefined ? { enable: input.enable } : {}),
152
+ ...(input.disable !== undefined ? { disable: input.disable } : {}),
153
+ ...(ticket !== undefined ? { ticketPattern: ticket } : {}),
154
+ ...(machinePatterns.length > 0 ? { machinePathPatterns: machinePatterns } : {}),
155
+ ...(input.maxLineChars !== undefined ? { maxLineChars: input.maxLineChars } : {}),
156
+ ...(input.maxAddedLinesPerFile !== undefined
157
+ ? { maxAddedLinesPerFile: input.maxAddedLinesPerFile }
158
+ : {}),
159
+ ...(input.maxFindings !== undefined ? { maxFindings: input.maxFindings } : {}),
160
+ });
161
+ // A patch that could not be parsed whole is reported as such rather than
162
+ // as a clean bill of health: the parser's warnings are the only thing
163
+ // standing between "no findings" and "no findings in the part I read".
164
+ const warnings = [...parsed.warnings];
165
+ if (spawnTruncated) {
166
+ warnings.push(`git's output hit the ${MAX_DIFF_CHARS}-character cap and the tail of the change set was not linted — narrow it with \`paths\``);
167
+ }
168
+ return json({
169
+ source,
170
+ filesScanned: result.filesScanned,
171
+ addedLinesScanned: result.addedLinesScanned,
172
+ findings: result.findings,
173
+ counts: result.counts,
174
+ ...(result.skipped.length > 0 ? { skipped: result.skipped } : {}),
175
+ ...(result.truncated ? { findingsTruncated: true } : {}),
176
+ ...(warnings.length > 0 ? { warnings } : {}),
177
+ ...(result.findings.length === 0 && warnings.length === 0 ? { clean: true } : {}),
178
+ });
179
+ },
180
+ });
181
+ const newCollected = () => ({
182
+ files: [],
183
+ oversized: [],
184
+ unreadableDirs: [],
185
+ escaped: [],
186
+ hitFileCap: false,
187
+ });
188
+ /** Read one file, or report it as oversized rather than pulling it into memory. */
189
+ function readIfSmall(abs, rel, into) {
190
+ let stat;
191
+ try {
192
+ stat = statSync(abs);
193
+ }
194
+ catch {
195
+ return; // vanished between the listing and the read, or a dangling link
196
+ }
197
+ // A link to a directory, a fifo, a device: `readFileSync` either fails or
198
+ // blocks, and calling that "too large to read" would refuse the whole scan
199
+ // with a reason that is not true.
200
+ if (!stat.isFile())
201
+ return;
202
+ if (stat.size > LIMITS.fileBytes) {
203
+ into.oversized.push(rel);
204
+ return;
205
+ }
206
+ try {
207
+ into.files.push({ path: rel, text: readFileSync(abs, "utf-8") });
208
+ }
209
+ catch {
210
+ into.oversized.push(rel);
211
+ }
212
+ }
213
+ /**
214
+ * Every file under `root` with one of `extensions`, workspace-relative and in
215
+ * a stable order.
216
+ *
217
+ * `readdirSync` order is filesystem order, not an order anything should
218
+ * depend on, so each directory is sorted before it is walked: the same tree
219
+ * produces the same listing on macOS and on a Linux runner.
220
+ *
221
+ * Containment does not stop at the root the caller named. `resolveSafe` gates
222
+ * that path, but a walk of it opens files the caller never named, and
223
+ * `readFileSync` FOLLOWS a symlink (CWE-59): a `docs/notes.md -> ~/.ssh/known_hosts`
224
+ * inside the workspace reads a file outside it, and this tool quotes a
225
+ * document's line back in `context`. So every symlinked entry is resolved
226
+ * before it is opened, and one that lands outside the workspace is recorded
227
+ * and skipped. A symlinked DIRECTORY is not walked at all — `isDirectory()`
228
+ * is false for a link — which is also what keeps a link cycle from recursing.
229
+ */
230
+ function collectFiles(toolName, root, extensions, cap, into = newCollected(), rel = "") {
231
+ let entries;
232
+ try {
233
+ entries = readdirSync(join(root, rel), { withFileTypes: true });
234
+ }
235
+ catch {
236
+ into.unreadableDirs.push(rel === "" ? "." : toPosix(rel));
237
+ return into;
238
+ }
239
+ for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : 1))) {
240
+ if (into.hitFileCap)
241
+ return into;
242
+ if (entry.isDirectory()) {
243
+ if (SKIP_DIRS.has(entry.name))
244
+ continue;
245
+ collectFiles(toolName, root, extensions, cap, into, join(rel, entry.name));
246
+ continue;
247
+ }
248
+ if (!entry.isFile() && !entry.isSymbolicLink())
249
+ continue;
250
+ const dot = entry.name.lastIndexOf(".");
251
+ if (dot <= 0 || !extensions.has(entry.name.slice(dot).toLowerCase()))
252
+ continue;
253
+ // The cap is checked at the file that would actually be read, not once
254
+ // per directory entry: a tree holding exactly `cap` sources and one image
255
+ // sorted after them had nothing left unread, and used to refuse anyway.
256
+ if (into.files.length >= cap) {
257
+ into.hitFileCap = true;
258
+ return into;
259
+ }
260
+ const abs = join(root, rel, entry.name);
261
+ const relPath = toPosix(join(rel, entry.name));
262
+ if (entry.isSymbolicLink()) {
263
+ try {
264
+ resolveSafe(toolName, abs);
265
+ }
266
+ catch {
267
+ into.escaped.push(relPath);
268
+ continue;
269
+ }
270
+ }
271
+ readIfSmall(abs, relPath, into);
272
+ }
273
+ return into;
274
+ }
275
+ /** Extensions scanned for "does this identifier still exist anywhere". */
276
+ const DEFAULT_SOURCE_EXTENSIONS = [
277
+ ".ts",
278
+ ".tsx",
279
+ ".mts",
280
+ ".cts",
281
+ ".js",
282
+ ".jsx",
283
+ ".mjs",
284
+ ".cjs",
285
+ ".py",
286
+ ".go",
287
+ ".rs",
288
+ ".java",
289
+ ".kt",
290
+ ".rb",
291
+ ".php",
292
+ ".swift",
293
+ ".c",
294
+ ".h",
295
+ ".cc",
296
+ ".cpp",
297
+ ".hpp",
298
+ ".cs",
299
+ ".json",
300
+ ".yaml",
301
+ ".yml",
302
+ ".toml",
303
+ ];
304
+ const DOC_EXTENSIONS = new Set([".md", ".mdx", ".markdown"]);
305
+ export const docsSymbolCheck = buildTool({
306
+ name: "DocsSymbolCheck",
307
+ description: "Find documentation that names symbols the code no longer has. Point it at markdown and at the source tree the markdown is about; it reports each documented symbol whose identifier appears NOWHERE in the scanned sources, with the document and line. It is built to under-report: only backticked identifiers and named imports inside fenced blocks count as references, a name shaped like an English word is skipped unless written as a call, and a document whose references mostly do not resolve is reported as probably describing a different tree rather than as a page full of dead symbols. A scan that could not read the whole source tree is refused rather than answered, because an incomplete index invents missing symbols.",
308
+ inputSchema: z.object({
309
+ docs: z
310
+ .array(z.string().min(1))
311
+ .max(LIMITS.docs)
312
+ .optional()
313
+ .describe("markdown files or directories, relative to the workspace root"),
314
+ docsText: z.string().max(LIMITS.docChars).optional().describe("or the document text itself"),
315
+ docsLabel: z.string().max(200).optional().describe("what to call `docsText` in findings"),
316
+ source: z
317
+ .string()
318
+ .min(1)
319
+ .optional()
320
+ .describe("the source tree the docs describe; defaults to the working directory"),
321
+ extensions: z
322
+ .array(z.string().min(2).max(16))
323
+ .max(64)
324
+ .optional()
325
+ .describe("source extensions to index, each with its dot"),
326
+ localPrefixes: z
327
+ .array(z.string().min(1).max(200))
328
+ .max(64)
329
+ .optional()
330
+ .describe("module specifier prefixes that mean 'this project', e.g. '@acme/'"),
331
+ include: z.enum(["imports", "backticks", "both"]).optional().describe("default 'both'"),
332
+ minLength: z.number().int().min(1).max(64).optional().describe("default 4"),
333
+ requireDistinctive: z
334
+ .boolean()
335
+ .optional()
336
+ .describe("skip plain lowercase words like `build`; default true"),
337
+ ignore: z.array(z.string().min(1).max(200)).max(500).optional(),
338
+ minResolvedRatio: z
339
+ .number()
340
+ .min(0)
341
+ .max(1)
342
+ .optional()
343
+ .describe("share of a document's references that must resolve before misses count; default 0.25"),
344
+ reportUnmatchedDocs: z
345
+ .boolean()
346
+ .optional()
347
+ .describe("report misses even from a document that mostly does not resolve"),
348
+ allowUnreadableSources: z
349
+ .boolean()
350
+ .optional()
351
+ .describe("continue when a source file was too large to read; default false, which refuses"),
352
+ maxFiles: z.number().int().positive().max(LIMITS.sourceFiles).optional(),
353
+ maxFindings: z.number().int().positive().max(2_000).optional().describe("default 200"),
354
+ }),
355
+ readOnly: true,
356
+ concurrencySafe: true,
357
+ execute: async (input) => {
358
+ if (input.docs === undefined && input.docsText === undefined) {
359
+ return "DocsSymbolCheck needs something to read: pass `docs` (files or directories) or `docsText`.";
360
+ }
361
+ const root = workspaceRoot();
362
+ const extensions = new Set((input.extensions ?? DEFAULT_SOURCE_EXTENSIONS).map((e) => (e.startsWith(".") ? e : `.${e}`).toLowerCase()));
363
+ let sourceDir;
364
+ try {
365
+ sourceDir = resolveSafe("DocsSymbolCheck", input.source ?? ".").real;
366
+ }
367
+ catch (err) {
368
+ if (err instanceof ToolPermissionError) {
369
+ return `DocsSymbolCheck refused the source path "${input.source ?? "."}": it resolves outside the workspace root.`;
370
+ }
371
+ throw err;
372
+ }
373
+ try {
374
+ if (!statSync(sourceDir).isDirectory()) {
375
+ return `DocsSymbolCheck refused "${input.source ?? "."}": \`source\` must be a directory containing the code the docs describe.`;
376
+ }
377
+ }
378
+ catch {
379
+ return `DocsSymbolCheck could not read "${input.source ?? "."}": no such directory.`;
380
+ }
381
+ const sources = collectFiles("DocsSymbolCheck", sourceDir, extensions, input.maxFiles ?? LIMITS.sourceFiles);
382
+ // All three of these make the index incomplete, and an incomplete index
383
+ // turns "I did not look there" into "this symbol is gone". Refusing is
384
+ // the only honest answer; the alternative is a confident lie in the
385
+ // direction that costs this tool its credibility.
386
+ if (sources.hitFileCap) {
387
+ return `DocsSymbolCheck stopped after ${input.maxFiles ?? LIMITS.sourceFiles} source files, so the symbol index is incomplete and a missing symbol could simply be one it never read. Point \`source\` at a narrower tree, or raise \`maxFiles\`.`;
388
+ }
389
+ if (sources.unreadableDirs.length > 0 && input.allowUnreadableSources !== true) {
390
+ return `DocsSymbolCheck could not list ${sources.unreadableDirs.length} directory(ies) under "${input.source ?? "."}" (${sources.unreadableDirs.slice(0, 5).join(", ")}), so the symbol index is missing everything inside them and a symbol that lives only there would be reported as deleted. Fix the permissions, narrow \`source\`, or pass allowUnreadableSources to accept the gap.`;
391
+ }
392
+ if (sources.oversized.length > 0 && input.allowUnreadableSources !== true) {
393
+ return `DocsSymbolCheck could not read ${sources.oversized.length} source file(s) over ${LIMITS.fileBytes} bytes (${sources.oversized.slice(0, 5).join(", ")}), so the symbol index is incomplete. Exclude them with \`extensions\`, or pass allowUnreadableSources to accept the gap.`;
394
+ }
395
+ if (sources.files.length === 0) {
396
+ return `DocsSymbolCheck found no source files under "${input.source ?? "."}" with the extensions it was given, so every documented symbol would look deleted. Check the path, or pass \`extensions\`.`;
397
+ }
398
+ const index = new Set();
399
+ for (const file of sources.files)
400
+ buildTokenIndex(file.text, index);
401
+ const extractOptions = {
402
+ ...(input.include !== undefined ? { include: input.include } : {}),
403
+ ...(input.localPrefixes !== undefined ? { localPrefixes: input.localPrefixes } : {}),
404
+ ...(input.minLength !== undefined ? { minLength: input.minLength } : {}),
405
+ ...(input.requireDistinctive !== undefined
406
+ ? { requireDistinctive: input.requireDistinctive }
407
+ : {}),
408
+ ...(input.ignore !== undefined ? { ignore: input.ignore } : {}),
409
+ };
410
+ const refs = [];
411
+ const docNames = [];
412
+ const unreadable = [];
413
+ const docDirsUnreadable = [];
414
+ const docsEscaped = [];
415
+ let docsHitCap = false;
416
+ if (input.docsText !== undefined) {
417
+ const label = input.docsLabel ?? "(docsText)";
418
+ docNames.push(label);
419
+ refs.push(...extractDocRefs(input.docsText, label, extractOptions));
420
+ }
421
+ for (const given of input.docs ?? []) {
422
+ let target;
423
+ try {
424
+ target = resolveSafe("DocsSymbolCheck", given).real;
425
+ }
426
+ catch (err) {
427
+ if (err instanceof ToolPermissionError) {
428
+ return `DocsSymbolCheck refused the document path "${given}": it resolves outside the workspace root.`;
429
+ }
430
+ throw err;
431
+ }
432
+ let isDir = false;
433
+ try {
434
+ isDir = statSync(target).isDirectory();
435
+ }
436
+ catch {
437
+ return `DocsSymbolCheck could not read "${given}": no such file or directory.`;
438
+ }
439
+ const found = isDir
440
+ ? collectFiles("DocsSymbolCheck", target, DOC_EXTENSIONS, LIMITS.docs)
441
+ : (() => {
442
+ const one = newCollected();
443
+ readIfSmall(target, toPosix(relative(root, target)), one);
444
+ return one;
445
+ })();
446
+ unreadable.push(...found.oversized);
447
+ docDirsUnreadable.push(...found.unreadableDirs);
448
+ docsEscaped.push(...found.escaped);
449
+ docsHitCap ||= found.hitFileCap;
450
+ for (const file of found.files) {
451
+ // A directory walk yields paths relative to that directory; a
452
+ // workspace-relative name is what a reader can act on.
453
+ const name = isDir ? toPosix(join(toPosix(relative(root, target)), file.path)) : file.path;
454
+ docNames.push(name);
455
+ refs.push(...extractDocRefs(file.text, name, extractOptions));
456
+ }
457
+ }
458
+ if (docNames.length === 0) {
459
+ return `DocsSymbolCheck found no markdown to read in ${JSON.stringify(input.docs ?? [])}. Pass a .md file, a directory containing one, or \`docsText\`.`;
460
+ }
461
+ const checkOptions = {
462
+ ...(input.minResolvedRatio !== undefined ? { minResolvedRatio: input.minResolvedRatio } : {}),
463
+ ...(input.reportUnmatchedDocs !== undefined
464
+ ? { reportUnmatchedDocs: input.reportUnmatchedDocs }
465
+ : {}),
466
+ ...(input.maxFindings !== undefined ? { maxFindings: input.maxFindings } : {}),
467
+ };
468
+ const verdict = checkRefs(refs, index, checkOptions);
469
+ const warnings = [];
470
+ if (unreadable.length > 0) {
471
+ warnings.push(`${unreadable.length} document(s) were too large to read: ${unreadable.slice(0, 5).join(", ")}`);
472
+ }
473
+ // A document walk that stopped early reads FEWER docs, which under-reports
474
+ // rather than inventing — so it warns instead of refusing. Saying nothing
475
+ // would still be wrong: "no findings" and "no findings in the 500 pages I
476
+ // got to" are different answers.
477
+ if (docsHitCap) {
478
+ warnings.push(`the document walk stopped after ${LIMITS.docs} files, so any document past that was not checked — pass a narrower \`docs\` list`);
479
+ }
480
+ if (docDirsUnreadable.length > 0) {
481
+ warnings.push(`${docDirsUnreadable.length} documentation directory(ies) could not be listed and were not checked: ${docDirsUnreadable.slice(0, 5).join(", ")}`);
482
+ }
483
+ for (const [kind, escaped] of [
484
+ ["document", docsEscaped],
485
+ ["source", sources.escaped],
486
+ ]) {
487
+ if (escaped.length === 0)
488
+ continue;
489
+ warnings.push(`${escaped.length} ${kind} symlink(s) point outside the workspace root and were not read: ${escaped.slice(0, 5).join(", ")}${kind === "source" ? " — a symbol that lives only behind one of them reads as missing" : ""}`);
490
+ }
491
+ if (sources.oversized.length > 0) {
492
+ warnings.push(`${sources.oversized.length} source file(s) were too large to index, so a symbol that lives only in one of them reads as missing`);
493
+ }
494
+ if (sources.unreadableDirs.length > 0) {
495
+ warnings.push(`${sources.unreadableDirs.length} source directory(ies) could not be listed, so a symbol that lives only inside one of them reads as missing: ${sources.unreadableDirs.slice(0, 5).join(", ")}`);
496
+ }
497
+ return json({
498
+ docsScanned: docNames.length,
499
+ sourceFilesScanned: sources.files.length,
500
+ identifiersIndexed: index.size,
501
+ references: verdict.references,
502
+ resolved: verdict.resolved,
503
+ missing: verdict.missing.map((ref) => ({
504
+ symbol: ref.symbol,
505
+ doc: ref.doc,
506
+ line: ref.line,
507
+ evidence: ref.evidence,
508
+ context: ref.context,
509
+ })),
510
+ ...(verdict.withheld > 0 ? { withheld: verdict.withheld } : {}),
511
+ ...(verdict.truncated ? { findingsTruncated: true } : {}),
512
+ coverage: verdict.coverage,
513
+ ...(warnings.length > 0 ? { warnings } : {}),
514
+ method: "a documented symbol is reported only when its identifier appears nowhere in the scanned sources — code, comments, strings and config alike",
515
+ });
516
+ },
517
+ });
518
+ /** Every tool this package registers, in the order a catalog should list them. */
519
+ export const CHANGESET_TOOLS = Object.freeze([
520
+ diffLint,
521
+ docsSymbolCheck,
522
+ ]);
523
+ /**
524
+ * The rule vocabulary, for a caller that builds its own `enable`/`disable`
525
+ * list and wants to validate it before the call rather than read a schema
526
+ * rejection afterwards.
527
+ */
528
+ export { RULE_IDS, unknownRuleIds } from "./lib/rules";