@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/README.md +231 -0
- package/dist/git.d.ts +73 -0
- package/dist/git.js +295 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +528 -0
- package/dist/lib/docs.d.ts +166 -0
- package/dist/lib/docs.js +338 -0
- package/dist/lib/rules.d.ts +117 -0
- package/dist/lib/rules.js +560 -0
- package/dist/paths.d.ts +42 -0
- package/dist/paths.js +158 -0
- package/package.json +47 -0
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";
|