@crewhaus/tool-changeset 0.7.0 → 0.8.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 CHANGED
@@ -19,11 +19,12 @@
19
19
  import { readFileSync, readdirSync, statSync } from "node:fs";
20
20
  import { join, relative } from "node:path";
21
21
  import { buildTool } from "@crewhaus/tool-builder";
22
+ import { describeRegexOutcome, openRegexSession, screenUserRegex, } from "@crewhaus/tool-safety/regex";
22
23
  import { parseUnifiedDiff } from "@crewhaus/tool-text";
23
24
  import { z } from "zod";
24
25
  import { MAX_DIFF_CHARS, MAX_TIMEOUT_MS, collectDiff } from "./git";
25
26
  import { buildTokenIndex, checkRefs, extractDocRefs, } from "./lib/docs";
26
- import { RULE_IDS, lintParsedDiff } from "./lib/rules";
27
+ import { RULE_IDS, callerPatternSubjects, lintParsedDiff, } from "./lib/rules";
27
28
  import { ToolPermissionError, resolveSafe, toPosix, workspaceRoot } from "./paths";
28
29
  /** Compact JSON — the reader is a model, not a person, so no indentation. */
29
30
  const json = (value) => JSON.stringify(value);
@@ -52,9 +53,118 @@ const SKIP_DIRS = new Set([
52
53
  ]);
53
54
  // ---------------------------------------------------------------------------
54
55
  // DiffLint
56
+ /** A zod refine that refuses a caller regex the screen refuses, with its reason. */
57
+ function refusePattern(pattern, ctx) {
58
+ const verdict = screenUserRegex(pattern);
59
+ if (!verdict.ok)
60
+ ctx.addIssue({ code: z.ZodIssueCode.custom, message: verdict.reason });
61
+ }
62
+ /** Total subject text the caller's patterns may run over in one call. */
63
+ const MAX_PATTERN_SUBJECT_CHARS = MAX_DIFF_CHARS * 2;
64
+ /**
65
+ * Run the caller's ticket and machine-path patterns over every subject the
66
+ * lint will ask about, in @crewhaus/tool-safety's regex worker under a
67
+ * deadline (C073), and hand back synchronous lookups. A subject the worker
68
+ * could not answer — the engine gave up on it, or the deadline passed — is
69
+ * undefined, which the lint reports as undetermined, never as "no ticket"
70
+ * or "no machine path".
71
+ */
72
+ async function answerCallerPatterns(parsed, ruleEdits, ticketPattern, machinePatterns, ctx) {
73
+ const warnings = [];
74
+ if (ticketPattern === undefined && machinePatterns.length === 0) {
75
+ return { machinePathTests: [], warnings };
76
+ }
77
+ const { todoBodies, lines } = callerPatternSubjects(parsed, ruleEdits);
78
+ const common = {
79
+ onGiveUp: "skip",
80
+ deadlineMs: 5_000,
81
+ maxInputChars: MAX_PATTERN_SUBJECT_CHARS,
82
+ ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
83
+ ...(ctx?.runContext !== undefined ? { runawayKey: ctx.runContext.sessionId } : {}),
84
+ };
85
+ /** Answers for `subjects` from the matched and undetermined index lists. */
86
+ const lookup = (subjects, matched, undetermined) => {
87
+ if (matched === undefined)
88
+ return () => undefined;
89
+ const answers = new Map();
90
+ const hit = new Set(matched);
91
+ const unknown = new Set(undetermined ?? []);
92
+ // `subjects` is deduplicated, so each one has exactly one answer.
93
+ for (const [i, subject] of subjects.entries()) {
94
+ answers.set(subject, unknown.has(i) ? undefined : hit.has(i));
95
+ }
96
+ return (subject) => answers.get(subject);
97
+ };
98
+ const session = openRegexSession();
99
+ try {
100
+ let ticketTest;
101
+ if (ticketPattern !== undefined) {
102
+ const subjects = [...new Set(todoBodies)];
103
+ const outcome = subjects.length === 0
104
+ ? undefined
105
+ : await session.run({
106
+ op: "testEach",
107
+ pattern: ticketPattern,
108
+ inputs: subjects,
109
+ maxMatches: subjects.length,
110
+ ...common,
111
+ });
112
+ if (outcome !== undefined && outcome.status !== "ok") {
113
+ warnings.push(`ticketPattern /${ticketPattern}/: ${describeRegexOutcome(outcome)}`);
114
+ }
115
+ ticketTest = {
116
+ source: ticketPattern,
117
+ test: outcome === undefined
118
+ ? () => undefined
119
+ : outcome.status === "ok" && !outcome.result.truncated
120
+ ? lookup(subjects, outcome.result.matched, outcome.result.undetermined)
121
+ : () => undefined,
122
+ };
123
+ }
124
+ const machinePathTests = [];
125
+ if (machinePatterns.length > 0) {
126
+ const subjects = [...new Set(lines)];
127
+ const outcome = subjects.length === 0
128
+ ? undefined
129
+ : await session.run({
130
+ op: "testMatrix",
131
+ patterns: machinePatterns.map((pattern) => ({ pattern })),
132
+ inputs: subjects,
133
+ ...common,
134
+ });
135
+ if (outcome !== undefined && outcome.status !== "ok") {
136
+ warnings.push(`machinePathPatterns: ${describeRegexOutcome(outcome)}`);
137
+ }
138
+ for (const [i, source] of machinePatterns.entries()) {
139
+ machinePathTests.push({
140
+ source,
141
+ test: outcome === undefined
142
+ ? () => undefined
143
+ : outcome.status === "ok"
144
+ ? lookup(subjects, outcome.result.matched[i], outcome.result.undetermined[i])
145
+ : () => undefined,
146
+ });
147
+ }
148
+ }
149
+ return { ...(ticketTest !== undefined ? { ticketTest } : {}), machinePathTests, warnings };
150
+ }
151
+ finally {
152
+ session.close();
153
+ }
154
+ }
55
155
  const ruleIdField = z.enum(RULE_IDS);
56
156
  export const diffLint = buildTool({
57
157
  name: "DiffLint",
158
+ operativeArgs: [
159
+ {
160
+ field: "paths",
161
+ kind: "path",
162
+ within: "cwd",
163
+ default: ".",
164
+ beneath: "all",
165
+ defaultAtRoot: true,
166
+ },
167
+ ],
58
168
  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
169
  inputSchema: z.object({
60
170
  diff: z
@@ -66,17 +176,22 @@ export const diffLint = buildTool({
66
176
  ref: z.string().min(1).optional().describe("diff against this single ref"),
67
177
  range: z.string().min(1).optional().describe("a commit range such as 'main...HEAD'"),
68
178
  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"),
179
+ paths: z
180
+ .array(z.string().min(1))
181
+ .max(256)
182
+ .optional()
183
+ .describe("limit to these paths: files, or directories with everything under them; literal, never wildcards"),
70
184
  timeout: z.number().int().positive().max(MAX_TIMEOUT_MS).optional(),
71
185
  enable: z.array(ruleIdField).max(RULE_IDS.length).optional().describe("turn opt-in rules on"),
72
186
  disable: z.array(ruleIdField).max(RULE_IDS.length).optional(),
73
187
  ticketPattern: z
74
188
  .string()
75
189
  .max(400)
190
+ .superRefine(refusePattern)
76
191
  .optional()
77
192
  .describe("regex a TODO must match to count as ticketed; default 'ABC-123', '#123' or a URL"),
78
193
  machinePathPatterns: z
79
- .array(z.string().max(400))
194
+ .array(z.string().max(400).superRefine(refusePattern))
80
195
  .max(32)
81
196
  .optional()
82
197
  .describe("extra machine-specific path shapes, as regex sources"),
@@ -100,30 +215,26 @@ export const diffLint = buildTool({
100
215
  if (input.diff !== undefined && usesGit) {
101
216
  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
217
  }
103
- // Compiling the caller's patterns before anything else: a bad regex is a
218
+ // Screening the caller's patterns before anything else: a bad regex is a
104
219
  // 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;
220
+ // empty result that looks like a clean change set. The screen also
221
+ // refuses the shapes that backtrack catastrophically (C073).
107
222
  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}`;
223
+ const verdict = screenUserRegex(input.ticketPattern);
224
+ if (!verdict.ok) {
225
+ return `DiffLint could not use ticketPattern /${input.ticketPattern}/: ${verdict.reason}`;
113
226
  }
114
227
  }
115
- const machinePatterns = [];
116
228
  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}`;
229
+ const verdict = screenUserRegex(source);
230
+ if (!verdict.ok) {
231
+ return `DiffLint could not use the machine-path pattern /${source}/: ${verdict.reason}`;
122
232
  }
123
233
  }
124
234
  let diffText;
125
235
  let source;
126
236
  let spawnTruncated = false;
237
+ let repoConfigNote;
127
238
  if (input.diff !== undefined) {
128
239
  diffText = input.diff;
129
240
  source = "caller-supplied diff";
@@ -142,16 +253,23 @@ export const diffLint = buildTool({
142
253
  diffText = collected.value.diff;
143
254
  source = collected.value.command;
144
255
  spawnTruncated = collected.value.truncated;
256
+ repoConfigNote = collected.value.repoConfigNote;
145
257
  }
146
258
  if (diffText.length > MAX_DIFF_CHARS) {
147
259
  return `DiffLint refused a ${diffText.length}-character diff, over the ${MAX_DIFF_CHARS} limit — lint it a directory at a time with \`paths\`.`;
148
260
  }
149
261
  const parsed = parseUnifiedDiff(diffText);
150
- const result = lintParsedDiff(parsed, {
262
+ const ruleEdits = {
151
263
  ...(input.enable !== undefined ? { enable: input.enable } : {}),
152
264
  ...(input.disable !== undefined ? { disable: input.disable } : {}),
153
- ...(ticket !== undefined ? { ticketPattern: ticket } : {}),
154
- ...(machinePatterns.length > 0 ? { machinePathPatterns: machinePatterns } : {}),
265
+ };
266
+ const answered = await answerCallerPatterns(parsed, ruleEdits, input.ticketPattern, input.machinePathPatterns ?? [], ctx);
267
+ const result = lintParsedDiff(parsed, {
268
+ ...ruleEdits,
269
+ ...(answered.ticketTest !== undefined ? { ticketTest: answered.ticketTest } : {}),
270
+ ...(answered.machinePathTests.length > 0
271
+ ? { machinePathTests: answered.machinePathTests }
272
+ : {}),
155
273
  ...(input.maxLineChars !== undefined ? { maxLineChars: input.maxLineChars } : {}),
156
274
  ...(input.maxAddedLinesPerFile !== undefined
157
275
  ? { maxAddedLinesPerFile: input.maxAddedLinesPerFile }
@@ -161,7 +279,10 @@ export const diffLint = buildTool({
161
279
  // A patch that could not be parsed whole is reported as such rather than
162
280
  // as a clean bill of health: the parser's warnings are the only thing
163
281
  // standing between "no findings" and "no findings in the part I read".
164
- const warnings = [...parsed.warnings];
282
+ const warnings = [...parsed.warnings, ...answered.warnings];
283
+ if (result.undeterminedCount > 0) {
284
+ warnings.push(`${result.undeterminedCount} added line(s) could not be checked against your ticketPattern or machinePathPatterns (listed in \`undetermined\`); they are neither findings nor clean`);
285
+ }
165
286
  if (spawnTruncated) {
166
287
  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
288
  }
@@ -173,7 +294,11 @@ export const diffLint = buildTool({
173
294
  counts: result.counts,
174
295
  ...(result.skipped.length > 0 ? { skipped: result.skipped } : {}),
175
296
  ...(result.truncated ? { findingsTruncated: true } : {}),
297
+ ...(result.undeterminedCount > 0
298
+ ? { undetermined: result.undetermined, undeterminedCount: result.undeterminedCount }
299
+ : {}),
176
300
  ...(warnings.length > 0 ? { warnings } : {}),
301
+ ...(repoConfigNote !== undefined ? { repoConfigNote } : {}),
177
302
  ...(result.findings.length === 0 && warnings.length === 0 ? { clean: true } : {}),
178
303
  });
179
304
  },
@@ -304,6 +429,11 @@ const DEFAULT_SOURCE_EXTENSIONS = [
304
429
  const DOC_EXTENSIONS = new Set([".md", ".mdx", ".markdown"]);
305
430
  export const docsSymbolCheck = buildTool({
306
431
  name: "DocsSymbolCheck",
432
+ // The documents and the source tree it reads, hidden names included.
433
+ operativeArgs: [
434
+ { field: "docs", kind: "path", beneath: "all" },
435
+ { field: "source", kind: "path", default: ".", beneath: "all" },
436
+ ],
307
437
  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
438
  inputSchema: z.object({
309
439
  docs: z
@@ -366,6 +496,8 @@ export const docsSymbolCheck = buildTool({
366
496
  }
367
497
  catch (err) {
368
498
  if (err instanceof ToolPermissionError) {
499
+ if (err.reason !== undefined)
500
+ return err.message;
369
501
  return `DocsSymbolCheck refused the source path "${input.source ?? "."}": it resolves outside the workspace root.`;
370
502
  }
371
503
  throw err;
@@ -425,6 +557,8 @@ export const docsSymbolCheck = buildTool({
425
557
  }
426
558
  catch (err) {
427
559
  if (err instanceof ToolPermissionError) {
560
+ if (err.reason !== undefined)
561
+ return err.message;
428
562
  return `DocsSymbolCheck refused the document path "${given}": it resolves outside the workspace root.`;
429
563
  }
430
564
  throw err;
package/dist/lib/docs.js CHANGED
@@ -23,6 +23,8 @@
23
23
  * 3. A document whose references mostly do not resolve is treated as the
24
24
  * wrong document, not as thirty findings (see `checkRefs`).
25
25
  */
26
+ import { namedImports } from "./import-scan";
27
+ import { beforeAs, fenceOpening } from "./scan-text";
26
28
  const MAX_CONTEXT_CHARS = 160;
27
29
  /**
28
30
  * Words that are shaped like identifiers and are not this tree's symbols.
@@ -165,9 +167,7 @@ function importedNames(line, localPrefixes) {
165
167
  const isLocal = (spec) => spec.startsWith(".") ||
166
168
  spec.startsWith("/") ||
167
169
  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] ?? "";
170
+ for (const { body, spec } of namedImports(line)) {
171
171
  if (!isLocal(spec))
172
172
  continue;
173
173
  for (const piece of body.split(",")) {
@@ -176,7 +176,7 @@ function importedNames(line, localPrefixes) {
176
176
  continue;
177
177
  // `a as b`: `a` is the name that has to exist in the source; `b` is a
178
178
  // local alias the document invented and nothing can check.
179
- const name = cleaned.split(/\s+as\s+/)[0].trim();
179
+ const name = beforeAs(cleaned).trim();
180
180
  if (IDENT.test(name))
181
181
  out.push(name);
182
182
  }
@@ -212,13 +212,13 @@ export function extractDocRefs(text, doc, options = {}) {
212
212
  for (let i = 0; i < lines.length; i++) {
213
213
  const raw = lines[i].replace(/\r$/, "");
214
214
  const context = raw.trim().slice(0, MAX_CONTEXT_CHARS);
215
- const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(raw);
215
+ const fenceMatch = fenceOpening(raw);
216
216
  if (fenceMatch !== null) {
217
- const marker = fenceMatch[1];
217
+ const marker = fenceMatch.marker;
218
218
  if (!fence.open) {
219
219
  fence.open = true;
220
220
  fence.marker = marker[0];
221
- fence.info = (fenceMatch[2] ?? "").trim();
221
+ fence.info = fenceMatch.info.trim();
222
222
  }
223
223
  else if (marker.startsWith(fence.marker)) {
224
224
  // A closing fence must use the same character; a ``` inside a ~~~
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The braced names and the module of each named import or destructured
3
+ * require on `line`, in order: what
4
+ * `/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"]+)\2|(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*(['"])([^'"]+)\5\s*\)/g`
5
+ * matched, its `{…}` and its module.
6
+ *
7
+ * As a global search, each `import {` or `let {` read on to the first `}`,
8
+ * so a line of them with none, or with the `}` far away and no `from`
9
+ * after it, was read again from every one: quadratic in the line, on
10
+ * documents of up to 4 MiB from the workspace. Every part of the pattern is
11
+ * fixed by the one before it (the blanks are taken whole, `[^}]*` runs to
12
+ * the first `}`, `[^'"]+` to the first quote), so it is read here by hand,
13
+ * in one pass: every opener with a `{` after it shares the first `}` after
14
+ * that `{` with the openers before it, and every opener sharing that `}`
15
+ * shares what follows it, so the `}` is searched for once and what follows
16
+ * it read once.
17
+ */
18
+ export declare function namedImports(line: string): Array<{
19
+ body: string;
20
+ spec: string;
21
+ }>;
@@ -0,0 +1,142 @@
1
+ import { isRegExpSpace } from "./scan-text";
2
+ /** Where the run of `\s` starting at `at` ends. */
3
+ function blanksEnd(line, at) {
4
+ let i = at;
5
+ while (i < line.length && isRegExpSpace(line.charCodeAt(i)))
6
+ i++;
7
+ return i;
8
+ }
9
+ const isQuote = (c) => c === 0x22 || c === 0x27;
10
+ /**
11
+ * `(['"])([^'"]+)\N` at `at`: a quote, one or more characters that are not
12
+ * quotes, and the same quote again. The module and the index after it, or
13
+ * null.
14
+ */
15
+ function quotedAt(line, at) {
16
+ const open = line.charCodeAt(at);
17
+ if (!isQuote(open))
18
+ return null;
19
+ let i = at + 1;
20
+ while (i < line.length && !isQuote(line.charCodeAt(i)))
21
+ i++;
22
+ if (i === at + 1 || line.charCodeAt(i) !== open)
23
+ return null;
24
+ return { spec: line.slice(at + 1, i), end: i + 1 };
25
+ }
26
+ /** `import\s+(?:type\s+)?\{` at `at`: the index of its `{`, or -1. */
27
+ function importOpen(line, at) {
28
+ if (!line.startsWith("import", at))
29
+ return -1;
30
+ let i = blanksEnd(line, at + 6);
31
+ if (i === at + 6)
32
+ return -1;
33
+ if (line.charCodeAt(i) === 0x7b)
34
+ return i;
35
+ if (!line.startsWith("type", i))
36
+ return -1;
37
+ const afterType = blanksEnd(line, i + 4);
38
+ if (afterType === i + 4)
39
+ return -1;
40
+ i = afterType;
41
+ return line.charCodeAt(i) === 0x7b ? i : -1;
42
+ }
43
+ /** `(?:const|let|var)\s*\{` at `at`: the index of its `{`, or -1. */
44
+ function requireOpen(line, at) {
45
+ const word = line.startsWith("const", at)
46
+ ? 5
47
+ : line.startsWith("let", at) || line.startsWith("var", at)
48
+ ? 3
49
+ : 0;
50
+ if (word === 0)
51
+ return -1;
52
+ const i = blanksEnd(line, at + word);
53
+ return line.charCodeAt(i) === 0x7b ? i : -1;
54
+ }
55
+ /** `\s*from\s*(['"])([^'"]+)\2` at `at`. */
56
+ function fromTail(line, at) {
57
+ const i = blanksEnd(line, at);
58
+ if (!line.startsWith("from", i))
59
+ return null;
60
+ return quotedAt(line, blanksEnd(line, i + 4));
61
+ }
62
+ /** `\s*=\s*require\(\s*(['"])([^'"]+)\5\s*\)` at `at`. */
63
+ function requireTail(line, at) {
64
+ let i = blanksEnd(line, at);
65
+ if (line.charCodeAt(i) !== 0x3d)
66
+ return null;
67
+ i = blanksEnd(line, i + 1);
68
+ if (!line.startsWith("require(", i))
69
+ return null;
70
+ const quoted = quotedAt(line, blanksEnd(line, i + 8));
71
+ if (quoted === null)
72
+ return null;
73
+ const close = blanksEnd(line, quoted.end);
74
+ return line.charCodeAt(close) === 0x29 ? { spec: quoted.spec, end: close + 1 } : null;
75
+ }
76
+ /**
77
+ * The braced names and the module of each named import or destructured
78
+ * require on `line`, in order: what
79
+ * `/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"]+)\2|(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*(['"])([^'"]+)\5\s*\)/g`
80
+ * matched, its `{…}` and its module.
81
+ *
82
+ * As a global search, each `import {` or `let {` read on to the first `}`,
83
+ * so a line of them with none, or with the `}` far away and no `from`
84
+ * after it, was read again from every one: quadratic in the line, on
85
+ * documents of up to 4 MiB from the workspace. Every part of the pattern is
86
+ * fixed by the one before it (the blanks are taken whole, `[^}]*` runs to
87
+ * the first `}`, `[^'"]+` to the first quote), so it is read here by hand,
88
+ * in one pass: every opener with a `{` after it shares the first `}` after
89
+ * that `{` with the openers before it, and every opener sharing that `}`
90
+ * shares what follows it, so the `}` is searched for once and what follows
91
+ * it read once.
92
+ */
93
+ export function namedImports(line) {
94
+ const out = [];
95
+ let close = -2;
96
+ let fromAt = -1;
97
+ let fromFound = null;
98
+ let requireAt = -1;
99
+ let requireFound = null;
100
+ let at = 0;
101
+ while (at < line.length) {
102
+ const c = line.charCodeAt(at);
103
+ const isImport = c === 0x69;
104
+ const open = isImport
105
+ ? importOpen(line, at)
106
+ : c === 0x63 || c === 0x6c || c === 0x76
107
+ ? requireOpen(line, at)
108
+ : -1;
109
+ if (open === -1) {
110
+ at++;
111
+ continue;
112
+ }
113
+ if (close !== -1 && close <= open)
114
+ close = line.indexOf("}", open + 1);
115
+ if (close === -1) {
116
+ at++;
117
+ continue;
118
+ }
119
+ let tail;
120
+ if (isImport) {
121
+ if (fromAt !== close) {
122
+ fromAt = close;
123
+ fromFound = fromTail(line, close + 1);
124
+ }
125
+ tail = fromFound;
126
+ }
127
+ else {
128
+ if (requireAt !== close) {
129
+ requireAt = close;
130
+ requireFound = requireTail(line, close + 1);
131
+ }
132
+ tail = requireFound;
133
+ }
134
+ if (tail === null) {
135
+ at++;
136
+ continue;
137
+ }
138
+ out.push({ body: line.slice(open + 1, close), spec: tail.spec });
139
+ at = tail.end;
140
+ }
141
+ return out;
142
+ }
@@ -66,16 +66,50 @@ export type LintResult = {
66
66
  readonly skipped: ReadonlyArray<SkippedFile>;
67
67
  /** True when `maxFindings` cut the list; the counts above are still whole. */
68
68
  readonly truncated: boolean;
69
+ /**
70
+ * Lines a caller-pattern check could not be answered for (the pattern
71
+ * engine gave up, or the deadline passed): neither a finding nor clean.
72
+ * Capped at `MAX_UNDETERMINED`; `undeterminedCount` is whole.
73
+ */
74
+ readonly undetermined: ReadonlyArray<UndeterminedCheck>;
75
+ readonly undeterminedCount: number;
69
76
  };
77
+ /** A caller-pattern check on one added line whose answer is unknown. */
78
+ export type UndeterminedCheck = {
79
+ readonly rule: RuleId;
80
+ readonly file: string;
81
+ readonly line: number;
82
+ /** The caller's pattern source. */
83
+ readonly pattern: string;
84
+ };
85
+ /**
86
+ * A caller-pattern answer computed off this thread: true or false, or
87
+ * undefined when it could not be determined. DiffLint runs the caller's
88
+ * patterns in @crewhaus/tool-safety's regex worker before linting (C073),
89
+ * because this loop is synchronous and a pattern run here could hold the
90
+ * process for seconds per line, or be abandoned by the engine and read as
91
+ * "no match".
92
+ */
93
+ export type PatternAnswer = (subject: string) => boolean | undefined;
70
94
  export type LintOptions = {
71
95
  /** Turn opt-in rules on. */
72
96
  readonly enable?: ReadonlyArray<RuleId>;
73
97
  /** Turn default rules off. */
74
98
  readonly disable?: ReadonlyArray<RuleId>;
75
- /** What counts as a ticket reference on a TODO. */
99
+ /** What counts as a ticket reference on a TODO (a trusted, in-process pattern). */
76
100
  readonly ticketPattern?: RegExp;
77
- /** Extra machine-specific path shapes, on top of the built-in ones. */
101
+ /** Extra machine-specific path shapes, on top of the built-in ones (trusted, in-process). */
78
102
  readonly machinePathPatterns?: ReadonlyArray<RegExp>;
103
+ /** The caller's ticket pattern, answered off-thread; wins over `ticketPattern`. */
104
+ readonly ticketTest?: {
105
+ readonly source: string;
106
+ readonly test: PatternAnswer;
107
+ };
108
+ /** The caller's machine-path patterns, answered off-thread; used instead of `machinePathPatterns`. */
109
+ readonly machinePathTests?: ReadonlyArray<{
110
+ readonly source: string;
111
+ readonly test: PatternAnswer;
112
+ }>;
79
113
  /** An added line longer than this is reported once; default 500. */
80
114
  readonly maxLineChars?: number;
81
115
  /** A file adding more lines than this is reported once; default 800. */
@@ -91,6 +125,26 @@ export type Lang = "js" | "python" | "go" | "rust" | "jvm" | "c" | "ruby" | "php
91
125
  export declare function languageOf(path: string): Lang;
92
126
  /** True when the whole line is a comment — not merely when one trails the code. */
93
127
  export declare function isCommentLine(text: string, lang: Lang): boolean;
128
+ /**
129
+ * The text a ticket pattern is tested against, for an added line that is a
130
+ * TODO note, or undefined for any other line.
131
+ *
132
+ * The marker must OPEN the comment: `// TODO: x` is a note to a maintainer,
133
+ * and "a TODO with no ticket" in the middle of a sentence is prose about
134
+ * todos. With the whole file a mask would decide this; with one line, where
135
+ * the marker sits is the signal there is.
136
+ */
137
+ export declare function todoBody(text: string, lang: Lang): string | undefined;
138
+ /**
139
+ * Every subject the caller's patterns will be asked about, in the order the
140
+ * lint visits them: the TODO bodies (for a ticket pattern) and the added
141
+ * lines (for machine-path patterns) of every file the lint scans. DiffLint
142
+ * answers these in the regex worker, then lints with the answers.
143
+ */
144
+ export declare function callerPatternSubjects(parsed: ParsedDiff, options?: LintOptions): {
145
+ readonly todoBodies: string[];
146
+ readonly lines: string[];
147
+ };
94
148
  /**
95
149
  * Does this comment look like code somebody commented out rather than a note
96
150
  * somebody wrote?