@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.
@@ -0,0 +1,166 @@
1
+ /**
2
+ * Stale-documentation detection, as pure functions over text.
3
+ *
4
+ * The whole design follows from one asymmetry: a MISSED stale symbol costs a
5
+ * reader one confusing minute, and a WRONG "this symbol is gone" costs the
6
+ * tool its reputation — people stop reading its output, and then it catches
7
+ * nothing at all. So every decision here is taken in the direction of saying
8
+ * less.
9
+ *
10
+ * Three consequences, each load-bearing:
11
+ *
12
+ * 1. What counts as a symbol reference is narrow (see `extractDocRefs`).
13
+ * Prose is not searched for identifiers; a reference has to be marked up
14
+ * as code by the person who wrote the document.
15
+ * 2. What counts as "still exists" is wide (see `buildTokenIndex`). The
16
+ * question asked of the source tree is "does this identifier appear
17
+ * anywhere at all" — in code, in a comment, in a string, in a config
18
+ * file. A symbol that survives only as a string key is not reported.
19
+ * This is why the module does not parse the source: a parser answers a
20
+ * narrower question ("is it declared") and every narrowing is a new way
21
+ * to be wrong out loud. `SymbolOutline` and `AstQuery` in
22
+ * `@crewhaus/tool-code` are the tools for the declaration question.
23
+ * 3. A document whose references mostly do not resolve is treated as the
24
+ * wrong document, not as thirty findings (see `checkRefs`).
25
+ */
26
+ /** How a reference was written, which is how much it is trusted. */
27
+ export type Evidence = "import" | "backtick";
28
+ export type DocRef = {
29
+ /** The reference exactly as the document wrote it, e.g. `Foo.bar` or `run()`. */
30
+ readonly symbol: string;
31
+ /** The identifier actually looked up: the head of a member path, call parens stripped. */
32
+ readonly base: string;
33
+ readonly doc: string;
34
+ /** 1-based line in the document. */
35
+ readonly line: number;
36
+ readonly evidence: Evidence;
37
+ readonly context: string;
38
+ };
39
+ export type ExtractOptions = {
40
+ /** Which reference kinds to collect; default both. */
41
+ readonly include?: "imports" | "backticks" | "both";
42
+ /**
43
+ * Module specifier prefixes that mean "this project". A fenced import from
44
+ * anywhere else is ignored: `react`'s exports are not this tree's problem.
45
+ * Relative specifiers always count.
46
+ */
47
+ readonly localPrefixes?: ReadonlyArray<string>;
48
+ /** Shortest identifier considered; default 4. `id` and `fn` are noise. */
49
+ readonly minLength?: number;
50
+ /**
51
+ * Require a backticked identifier to LOOK like an API name — an interior
52
+ * capital, an underscore, a `$`, a member path or call parens. Default on;
53
+ * without it `build`, `run` and `format` flood the output.
54
+ */
55
+ readonly requireDistinctive?: boolean;
56
+ /** Symbols to never report, on top of `DEFAULT_IGNORED`. */
57
+ readonly ignore?: ReadonlyArray<string>;
58
+ };
59
+ /**
60
+ * Words that are shaped like identifiers and are not this tree's symbols.
61
+ *
62
+ * Every one of these has been seen inside backticks in ordinary
63
+ * documentation. The list is short on purpose: the distinctive-shape rule
64
+ * does most of the filtering, and a stoplist that tries to enumerate the
65
+ * world's vocabulary is a maintenance burden that still misses.
66
+ */
67
+ export declare const DEFAULT_IGNORED: ReadonlySet<string>;
68
+ /**
69
+ * Reduce a backticked span to the identifier to look up, or nothing.
70
+ *
71
+ * Nothing is the common case and that is intended: a span holding a command,
72
+ * a path, a flag, a type expression or a sentence is not a symbol reference
73
+ * this tool can check, and guessing at one is how false findings are born.
74
+ */
75
+ export declare function referenceOf(span: string): {
76
+ symbol: string;
77
+ base: string;
78
+ } | undefined;
79
+ /** An identifier shaped like an API name rather than like an English word. */
80
+ export declare function isDistinctive(name: string): boolean;
81
+ /**
82
+ * The inline code spans on one line, scanned by hand rather than by regex.
83
+ *
84
+ * The obvious pattern is `/(`+)([^`]+?)\1/g`, and it is quadratic: on a run of
85
+ * backticks that nothing closes, the engine re-walks the whole run from every
86
+ * offset inside it. A document is allowed to be four megabytes, and four
87
+ * megabytes of backticks never comes back — the tool hangs rather than
88
+ * answers, which is the one failure a deterministic tool cannot recover from.
89
+ * One pass over the line costs O(n) and reads the same spans the regex did,
90
+ * closing run included: an opening run of three closed by a run of one
91
+ * consumes one backtick and leaves the rest to open the next span.
92
+ */
93
+ export declare function codeSpans(line: string): string[];
94
+ /**
95
+ * Every symbol reference in one markdown document.
96
+ *
97
+ * Two forms are recognised, and deliberately only two:
98
+ *
99
+ * - A NAMED IMPORT inside a fenced code block, from a project-local module.
100
+ * This is the strongest evidence a document can carry: the writer named
101
+ * the module and the export together, so there is nothing to infer.
102
+ * - A BACKTICKED IDENTIFIER in prose, when it survives the shape filters.
103
+ * `parseUnifiedDiff` is a symbol reference; `npm install`, `--force`,
104
+ * `src/index.ts` and `the plan` are not, and never become one.
105
+ *
106
+ * Everything else inside a fence is ignored. A fence usually holds shell
107
+ * commands, sample output or JSON, and mining it for identifiers produces
108
+ * exactly the noise this tool exists not to produce.
109
+ */
110
+ export declare function extractDocRefs(text: string, doc: string, options?: ExtractOptions): DocRef[];
111
+ /**
112
+ * Every identifier-shaped token in a source file, added to `into`.
113
+ *
114
+ * Comments and string literals are NOT masked, and that is the point: the
115
+ * question is "could this name still mean something here", and a name that
116
+ * survives only in a doc comment or as a string key is not a name that has
117
+ * been removed. Masking would make the index smaller and the findings
118
+ * bolder, which is the wrong direction for this tool.
119
+ */
120
+ export declare function buildTokenIndex(text: string, into: Set<string>): Set<string>;
121
+ export type DocCoverage = {
122
+ readonly doc: string;
123
+ readonly references: number;
124
+ readonly resolved: number;
125
+ /** Set when this document's unresolved references were withheld. */
126
+ readonly suppressed?: string;
127
+ };
128
+ export type CheckResult = {
129
+ readonly missing: ReadonlyArray<DocRef>;
130
+ readonly coverage: ReadonlyArray<DocCoverage>;
131
+ readonly references: number;
132
+ readonly resolved: number;
133
+ /** Findings withheld by the unmatched-document guard. */
134
+ readonly withheld: number;
135
+ /**
136
+ * True when `maxFindings` cut the list.
137
+ *
138
+ * Without it the cap is indistinguishable from a clean tail: `missing` is
139
+ * the only place a dropped finding would have shown, `coverage` counts the
140
+ * whole document either way, and a reader who fixes all 200 has no way to
141
+ * learn there were 900.
142
+ */
143
+ readonly truncated: boolean;
144
+ };
145
+ export type CheckOptions = {
146
+ /**
147
+ * A document must resolve at least this share of its references before any
148
+ * of its misses are reported; default 0.25.
149
+ *
150
+ * This is the guard against the most expensive failure this tool has: being
151
+ * pointed at the wrong source tree, or at a document about a different
152
+ * project, and confidently reporting every symbol in it as deleted. A
153
+ * document that really documents this tree resolves most of what it names.
154
+ */
155
+ readonly minResolvedRatio?: number;
156
+ /** Turn the guard off and report every miss; default false. */
157
+ readonly reportUnmatchedDocs?: boolean;
158
+ readonly maxFindings?: number;
159
+ };
160
+ /**
161
+ * Compare references against the token index, per document.
162
+ *
163
+ * Ordering is document order then line order, so two runs over the same
164
+ * inputs return the same bytes.
165
+ */
166
+ export declare function checkRefs(refs: ReadonlyArray<DocRef>, index: ReadonlySet<string>, options?: CheckOptions): CheckResult;
@@ -0,0 +1,338 @@
1
+ /**
2
+ * Stale-documentation detection, as pure functions over text.
3
+ *
4
+ * The whole design follows from one asymmetry: a MISSED stale symbol costs a
5
+ * reader one confusing minute, and a WRONG "this symbol is gone" costs the
6
+ * tool its reputation — people stop reading its output, and then it catches
7
+ * nothing at all. So every decision here is taken in the direction of saying
8
+ * less.
9
+ *
10
+ * Three consequences, each load-bearing:
11
+ *
12
+ * 1. What counts as a symbol reference is narrow (see `extractDocRefs`).
13
+ * Prose is not searched for identifiers; a reference has to be marked up
14
+ * as code by the person who wrote the document.
15
+ * 2. What counts as "still exists" is wide (see `buildTokenIndex`). The
16
+ * question asked of the source tree is "does this identifier appear
17
+ * anywhere at all" — in code, in a comment, in a string, in a config
18
+ * file. A symbol that survives only as a string key is not reported.
19
+ * This is why the module does not parse the source: a parser answers a
20
+ * narrower question ("is it declared") and every narrowing is a new way
21
+ * to be wrong out loud. `SymbolOutline` and `AstQuery` in
22
+ * `@crewhaus/tool-code` are the tools for the declaration question.
23
+ * 3. A document whose references mostly do not resolve is treated as the
24
+ * wrong document, not as thirty findings (see `checkRefs`).
25
+ */
26
+ const MAX_CONTEXT_CHARS = 160;
27
+ /**
28
+ * Words that are shaped like identifiers and are not this tree's symbols.
29
+ *
30
+ * Every one of these has been seen inside backticks in ordinary
31
+ * documentation. The list is short on purpose: the distinctive-shape rule
32
+ * does most of the filtering, and a stoplist that tries to enumerate the
33
+ * world's vocabulary is a maintenance burden that still misses.
34
+ */
35
+ export const DEFAULT_IGNORED = new Set([
36
+ "JavaScript",
37
+ "TypeScript",
38
+ "JSON",
39
+ "YAML",
40
+ "TOML",
41
+ "HTML",
42
+ "HTTP",
43
+ "HTTPS",
44
+ "GitHub",
45
+ "GitLab",
46
+ "README",
47
+ "CHANGELOG",
48
+ "LICENSE",
49
+ "NOTICE",
50
+ "MacOS",
51
+ "macOS",
52
+ "iOS",
53
+ "npm",
54
+ "npx",
55
+ "bun",
56
+ "bunx",
57
+ "pnpm",
58
+ "yarn",
59
+ "git",
60
+ "curl",
61
+ "sudo",
62
+ "true",
63
+ "false",
64
+ "null",
65
+ "undefined",
66
+ "string",
67
+ "number",
68
+ "boolean",
69
+ "object",
70
+ "array",
71
+ "void",
72
+ "async",
73
+ "await",
74
+ "const",
75
+ "class",
76
+ "function",
77
+ "import",
78
+ "export",
79
+ "return",
80
+ "default",
81
+ "package.json",
82
+ "tsconfig.json",
83
+ ]);
84
+ /** A bare identifier: what a symbol reference has to reduce to. */
85
+ const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
86
+ /** `Foo.bar.baz` — a member path whose head is what we can actually check. */
87
+ const MEMBER_PATH = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)+$/;
88
+ /**
89
+ * Reduce a backticked span to the identifier to look up, or nothing.
90
+ *
91
+ * Nothing is the common case and that is intended: a span holding a command,
92
+ * a path, a flag, a type expression or a sentence is not a symbol reference
93
+ * this tool can check, and guessing at one is how false findings are born.
94
+ */
95
+ export function referenceOf(span) {
96
+ const trimmed = span.trim();
97
+ if (trimmed === "" || /\s/.test(trimmed))
98
+ return undefined;
99
+ // `run()` and `run(...)` are unambiguous symbol references; the arguments
100
+ // are not part of the name.
101
+ const call = /^([A-Za-z_$][A-Za-z0-9_$.]*)\((?:\.{3}|)\)$/.exec(trimmed);
102
+ const bare = call === null ? trimmed : call[1];
103
+ if (IDENT.test(bare))
104
+ return { symbol: trimmed, base: bare };
105
+ if (MEMBER_PATH.test(bare)) {
106
+ // Only the HEAD is checked. If `Foo` exists but `Foo.bar` does not, this
107
+ // module cannot tell a removed method from a method it cannot see
108
+ // lexically, so it says nothing rather than guessing.
109
+ return { symbol: trimmed, base: bare.slice(0, bare.indexOf(".")) };
110
+ }
111
+ return undefined;
112
+ }
113
+ /** An identifier shaped like an API name rather than like an English word. */
114
+ export function isDistinctive(name) {
115
+ if (/[_$]/.test(name))
116
+ return true;
117
+ if (/^[a-z]+[A-Z]/.test(name))
118
+ return true; // camelCase
119
+ if (/^[A-Z]/.test(name) && /[a-z]/.test(name) && /[A-Z]/.test(name.slice(1)))
120
+ return true; // PascalCase
121
+ return /^[A-Z][A-Z0-9]+$/.test(name) && name.length > 2; // SCREAMING_CASE without the underscore
122
+ }
123
+ const BACKTICK = 96;
124
+ /**
125
+ * The inline code spans on one line, scanned by hand rather than by regex.
126
+ *
127
+ * The obvious pattern is `/(`+)([^`]+?)\1/g`, and it is quadratic: on a run of
128
+ * backticks that nothing closes, the engine re-walks the whole run from every
129
+ * offset inside it. A document is allowed to be four megabytes, and four
130
+ * megabytes of backticks never comes back — the tool hangs rather than
131
+ * answers, which is the one failure a deterministic tool cannot recover from.
132
+ * One pass over the line costs O(n) and reads the same spans the regex did,
133
+ * closing run included: an opening run of three closed by a run of one
134
+ * consumes one backtick and leaves the rest to open the next span.
135
+ */
136
+ export function codeSpans(line) {
137
+ const spans = [];
138
+ let i = 0;
139
+ while (i < line.length) {
140
+ if (line.charCodeAt(i) !== BACKTICK) {
141
+ i++;
142
+ continue;
143
+ }
144
+ const openStart = i;
145
+ while (i < line.length && line.charCodeAt(i) === BACKTICK)
146
+ i++;
147
+ const openLength = i - openStart;
148
+ let close = i;
149
+ while (close < line.length && line.charCodeAt(close) !== BACKTICK)
150
+ close++;
151
+ if (close === line.length)
152
+ break; // nothing on this line closes the run
153
+ let closeLength = 0;
154
+ while (close + closeLength < line.length && line.charCodeAt(close + closeLength) === BACKTICK) {
155
+ closeLength++;
156
+ }
157
+ spans.push(line.slice(i, close));
158
+ i = close + Math.min(openLength, closeLength);
159
+ }
160
+ return spans;
161
+ }
162
+ /** Named imports from a project-local module inside a fenced block. */
163
+ function importedNames(line, localPrefixes) {
164
+ const out = [];
165
+ const isLocal = (spec) => spec.startsWith(".") ||
166
+ spec.startsWith("/") ||
167
+ localPrefixes.some((prefix) => spec === prefix || spec.startsWith(prefix));
168
+ for (const m of line.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"]+)\2|(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*(['"])([^'"]+)\5\s*\)/g)) {
169
+ const body = m[1] ?? m[4] ?? "";
170
+ const spec = m[3] ?? m[6] ?? "";
171
+ if (!isLocal(spec))
172
+ continue;
173
+ for (const piece of body.split(",")) {
174
+ const cleaned = piece.replace(/\btype\s+/g, "").trim();
175
+ if (cleaned === "")
176
+ continue;
177
+ // `a as b`: `a` is the name that has to exist in the source; `b` is a
178
+ // local alias the document invented and nothing can check.
179
+ const name = cleaned.split(/\s+as\s+/)[0].trim();
180
+ if (IDENT.test(name))
181
+ out.push(name);
182
+ }
183
+ }
184
+ return out;
185
+ }
186
+ /**
187
+ * Every symbol reference in one markdown document.
188
+ *
189
+ * Two forms are recognised, and deliberately only two:
190
+ *
191
+ * - A NAMED IMPORT inside a fenced code block, from a project-local module.
192
+ * This is the strongest evidence a document can carry: the writer named
193
+ * the module and the export together, so there is nothing to infer.
194
+ * - A BACKTICKED IDENTIFIER in prose, when it survives the shape filters.
195
+ * `parseUnifiedDiff` is a symbol reference; `npm install`, `--force`,
196
+ * `src/index.ts` and `the plan` are not, and never become one.
197
+ *
198
+ * Everything else inside a fence is ignored. A fence usually holds shell
199
+ * commands, sample output or JSON, and mining it for identifiers produces
200
+ * exactly the noise this tool exists not to produce.
201
+ */
202
+ export function extractDocRefs(text, doc, options = {}) {
203
+ const include = options.include ?? "both";
204
+ const minLength = options.minLength ?? 4;
205
+ const requireDistinctive = options.requireDistinctive ?? true;
206
+ const ignore = new Set([...DEFAULT_IGNORED, ...(options.ignore ?? [])]);
207
+ const localPrefixes = options.localPrefixes ?? [];
208
+ const refs = [];
209
+ const fence = { open: false, marker: "", info: "" };
210
+ const seen = new Set();
211
+ const lines = text.split("\n");
212
+ for (let i = 0; i < lines.length; i++) {
213
+ const raw = lines[i].replace(/\r$/, "");
214
+ const context = raw.trim().slice(0, MAX_CONTEXT_CHARS);
215
+ const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(raw);
216
+ if (fenceMatch !== null) {
217
+ const marker = fenceMatch[1];
218
+ if (!fence.open) {
219
+ fence.open = true;
220
+ fence.marker = marker[0];
221
+ fence.info = (fenceMatch[2] ?? "").trim();
222
+ }
223
+ else if (marker.startsWith(fence.marker)) {
224
+ // A closing fence must use the same character; a ``` inside a ~~~
225
+ // block is content, not the end of the block.
226
+ fence.open = false;
227
+ fence.info = "";
228
+ }
229
+ continue;
230
+ }
231
+ if (fence.open) {
232
+ if (include === "backticks")
233
+ continue;
234
+ for (const name of importedNames(raw, localPrefixes)) {
235
+ if (ignore.has(name))
236
+ continue;
237
+ const key = `import:${name}`;
238
+ if (seen.has(key))
239
+ continue;
240
+ seen.add(key);
241
+ refs.push({ symbol: name, base: name, doc, line: i + 1, evidence: "import", context });
242
+ }
243
+ continue;
244
+ }
245
+ if (include === "imports")
246
+ continue;
247
+ for (const span of codeSpans(raw)) {
248
+ const reference = referenceOf(span);
249
+ if (reference === undefined)
250
+ continue;
251
+ if (reference.base.length < minLength)
252
+ continue;
253
+ if (ignore.has(reference.base) || ignore.has(reference.symbol))
254
+ continue;
255
+ if (requireDistinctive && !isDistinctive(reference.base) && !reference.symbol.endsWith(")")) {
256
+ continue;
257
+ }
258
+ const key = `backtick:${reference.symbol}`;
259
+ if (seen.has(key))
260
+ continue;
261
+ seen.add(key);
262
+ refs.push({
263
+ symbol: reference.symbol,
264
+ base: reference.base,
265
+ doc,
266
+ line: i + 1,
267
+ evidence: "backtick",
268
+ context,
269
+ });
270
+ }
271
+ }
272
+ return refs;
273
+ }
274
+ /**
275
+ * Every identifier-shaped token in a source file, added to `into`.
276
+ *
277
+ * Comments and string literals are NOT masked, and that is the point: the
278
+ * question is "could this name still mean something here", and a name that
279
+ * survives only in a doc comment or as a string key is not a name that has
280
+ * been removed. Masking would make the index smaller and the findings
281
+ * bolder, which is the wrong direction for this tool.
282
+ */
283
+ export function buildTokenIndex(text, into) {
284
+ for (const m of text.matchAll(/[A-Za-z_$][A-Za-z0-9_$]*/g))
285
+ into.add(m[0]);
286
+ return into;
287
+ }
288
+ /**
289
+ * Compare references against the token index, per document.
290
+ *
291
+ * Ordering is document order then line order, so two runs over the same
292
+ * inputs return the same bytes.
293
+ */
294
+ export function checkRefs(refs, index, options = {}) {
295
+ const minRatio = options.minResolvedRatio ?? 0.25;
296
+ const maxFindings = options.maxFindings ?? 200;
297
+ const byDoc = new Map();
298
+ for (const ref of refs) {
299
+ const list = byDoc.get(ref.doc);
300
+ if (list === undefined)
301
+ byDoc.set(ref.doc, [ref]);
302
+ else
303
+ list.push(ref);
304
+ }
305
+ const missing = [];
306
+ const coverage = [];
307
+ let references = 0;
308
+ let resolved = 0;
309
+ let withheld = 0;
310
+ let dropped = 0;
311
+ for (const [doc, list] of byDoc) {
312
+ const gone = list.filter((ref) => !index.has(ref.base));
313
+ const docResolved = list.length - gone.length;
314
+ references += list.length;
315
+ resolved += docResolved;
316
+ const ratio = list.length === 0 ? 1 : docResolved / list.length;
317
+ const unmatched = gone.length > 0 && ratio < minRatio;
318
+ if (unmatched && options.reportUnmatchedDocs !== true) {
319
+ withheld += gone.length;
320
+ coverage.push({
321
+ doc,
322
+ references: list.length,
323
+ resolved: docResolved,
324
+ suppressed: `only ${docResolved} of ${list.length} references resolve against the scanned sources — this document probably does not describe this tree, so its ${gone.length} unresolved reference${gone.length === 1 ? "" : "s"} are withheld. Point \`source\` at the right tree, or pass reportUnmatchedDocs.`,
325
+ });
326
+ continue;
327
+ }
328
+ coverage.push({ doc, references: list.length, resolved: docResolved });
329
+ for (const ref of gone) {
330
+ if (missing.length >= maxFindings) {
331
+ dropped++;
332
+ continue;
333
+ }
334
+ missing.push(ref);
335
+ }
336
+ }
337
+ return { missing, coverage, references, resolved, withheld, truncated: dropped > 0 };
338
+ }
@@ -0,0 +1,117 @@
1
+ /**
2
+ * The change-set policy rules, as pure functions over an already-parsed diff.
3
+ *
4
+ * Two decisions shape everything here.
5
+ *
6
+ * The first is that a rule only ever sees an ADDED line. A change set is not
7
+ * a codebase: nobody wants a review that reports the `console.log` somebody
8
+ * else left behind three years ago, and a linter that does it once gets
9
+ * turned off. The rules run on `kind === "added"` and on nothing else.
10
+ *
11
+ * The second is that every finding carries `line`, the line number in the NEW
12
+ * file, straight from `parseUnifiedDiff`. That number is the product: it is
13
+ * what lets a caller fix a finding without re-reading the file. Nothing in
14
+ * this module counts lines itself — the parser already did, and a second
15
+ * counter would be a second chance to be off by one.
16
+ *
17
+ * A rule sees one line, without the file around it. That is a real limit and
18
+ * it is the reason the rules here are anchored tightly and lean toward
19
+ * silence: `console.log` inside a multi-line string literal reads exactly
20
+ * like a call, and no amount of regex fixes that without the whole file.
21
+ */
22
+ import type { ParsedDiff } from "@crewhaus/tool-text";
23
+ export type Severity = "error" | "warning";
24
+ /**
25
+ * Every rule, in the order findings are reported within one line.
26
+ *
27
+ * The ids are the caller's vocabulary — `enable`, `disable` and every finding
28
+ * name one — so they are a closed set, and an id that is not in it is refused
29
+ * rather than ignored. A typo that silently disables nothing is how a team
30
+ * ends up believing a rule is off for a year.
31
+ */
32
+ export declare const RULE_IDS: readonly ["conflictMarker", "debugger", "focusedTest", "consoleLog", "suppression", "ticketlessTodo", "machinePath", "crlf", "longLine", "oversizedFile", "commentedCode"];
33
+ export type RuleId = (typeof RULE_IDS)[number];
34
+ /**
35
+ * Rules that are OFF unless the caller asks for them.
36
+ *
37
+ * `commentedCode` is a heuristic with a genuine false-positive rate (see
38
+ * `looksLikeCommentedCode`), and a heuristic that fires on prose is how the
39
+ * whole tool gets disabled. It ships opt-in and at warning severity.
40
+ */
41
+ export declare const OPT_IN_RULES: ReadonlyArray<RuleId>;
42
+ export type Finding = {
43
+ readonly rule: RuleId;
44
+ readonly severity: Severity;
45
+ /** Path in the new tree, as the diff spells it. */
46
+ readonly file: string;
47
+ /** 1-based line in the NEW file; null only on a whole-file finding. */
48
+ readonly line: number | null;
49
+ readonly message: string;
50
+ /** The offending line, trimmed and capped — enough to recognise, not to quote. */
51
+ readonly snippet: string;
52
+ };
53
+ export type SkippedFile = {
54
+ readonly file: string;
55
+ readonly why: string;
56
+ };
57
+ export type LintResult = {
58
+ readonly findings: ReadonlyArray<Finding>;
59
+ readonly filesScanned: number;
60
+ readonly addedLinesScanned: number;
61
+ /** Counts over EVERY finding, including any dropped by `maxFindings`. */
62
+ readonly counts: {
63
+ readonly byRule: Readonly<Record<string, number>>;
64
+ readonly bySeverity: Readonly<Record<Severity, number>>;
65
+ };
66
+ readonly skipped: ReadonlyArray<SkippedFile>;
67
+ /** True when `maxFindings` cut the list; the counts above are still whole. */
68
+ readonly truncated: boolean;
69
+ };
70
+ export type LintOptions = {
71
+ /** Turn opt-in rules on. */
72
+ readonly enable?: ReadonlyArray<RuleId>;
73
+ /** Turn default rules off. */
74
+ readonly disable?: ReadonlyArray<RuleId>;
75
+ /** What counts as a ticket reference on a TODO. */
76
+ readonly ticketPattern?: RegExp;
77
+ /** Extra machine-specific path shapes, on top of the built-in ones. */
78
+ readonly machinePathPatterns?: ReadonlyArray<RegExp>;
79
+ /** An added line longer than this is reported once; default 500. */
80
+ readonly maxLineChars?: number;
81
+ /** A file adding more lines than this is reported once; default 800. */
82
+ readonly maxAddedLinesPerFile?: number;
83
+ /** Hard cap on returned findings; default 500. */
84
+ readonly maxFindings?: number;
85
+ };
86
+ /** Ids in `ids` that are not rules — returned so a caller can refuse by name. */
87
+ export declare function unknownRuleIds(ids: ReadonlyArray<string>): string[];
88
+ /** The rules that will actually run, after the opt-in list and the caller's edits. */
89
+ export declare function activeRules(options?: LintOptions): ReadonlySet<RuleId>;
90
+ export type Lang = "js" | "python" | "go" | "rust" | "jvm" | "c" | "ruby" | "php" | "shell" | "sql" | "config" | "markdown" | "other";
91
+ export declare function languageOf(path: string): Lang;
92
+ /** True when the whole line is a comment — not merely when one trails the code. */
93
+ export declare function isCommentLine(text: string, lang: Lang): boolean;
94
+ /**
95
+ * Does this comment look like code somebody commented out rather than a note
96
+ * somebody wrote?
97
+ *
98
+ * This is the one rule here that guesses, so it guesses toward silence. A
99
+ * body qualifies only on a positive code signal — a statement keyword, an
100
+ * assignment, a bare call, or a line ending in `;`/`{`/`}` — and a body that
101
+ * reads like a sentence vetoes all of them. The prose veto is a word count
102
+ * rather than a word list because a comment in German is still prose:
103
+ * five or more plain alphabetic words in a row is writing, not code.
104
+ *
105
+ * What still gets through: a short imperative comment that ends in a brace or
106
+ * names a function, `// see runTests()` most of all. That is why the rule is
107
+ * opt-in and warns rather than errors.
108
+ */
109
+ export declare function looksLikeCommentedCode(body: string): boolean;
110
+ /**
111
+ * Run the policy over a parsed diff.
112
+ *
113
+ * Findings come back in diff order and then line order, which is stable for a
114
+ * stable diff — this is a deterministic tool and two runs over the same patch
115
+ * return the same bytes.
116
+ */
117
+ export declare function lintParsedDiff(parsed: ParsedDiff, options?: LintOptions): LintResult;