@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/lib/rules.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { onlyCommentOpener } from "./scan-text";
1
2
  /**
2
3
  * Every rule, in the order findings are reported within one line.
3
4
  *
@@ -42,6 +43,7 @@ const DEFAULT_SEVERITY = {
42
43
  oversizedFile: "warning",
43
44
  commentedCode: "warning",
44
45
  };
46
+ const MAX_UNDETERMINED = 50;
45
47
  const DEFAULT_TICKET = /(?:\b[A-Z][A-Z0-9]{1,9}-\d+\b|#\d+|https?:\/\/\S+)/;
46
48
  const DEFAULT_MAX_LINE_CHARS = 1_000;
47
49
  const DEFAULT_MAX_ADDED_LINES = 800;
@@ -208,6 +210,55 @@ const CONSOLE_LOG = /\bconsole\s*\.\s*(?:log|debug|dir|trace)\s*\(/;
208
210
  const CONFLICT_STRONG = /^(?:<{7}|>{7}|\|{7})(?:\s|$)/;
209
211
  const CONFLICT_WEAK = /^={7}\s*$/;
210
212
  const TODO_MARKER = /\b(TODO|FIXME|HACK|XXX)\b/;
213
+ /**
214
+ * The text a ticket pattern is tested against, for an added line that is a
215
+ * TODO note, or undefined for any other line.
216
+ *
217
+ * The marker must OPEN the comment: `// TODO: x` is a note to a maintainer,
218
+ * and "a TODO with no ticket" in the middle of a sentence is prose about
219
+ * todos. With the whole file a mask would decide this; with one line, where
220
+ * the marker sits is the signal there is.
221
+ */
222
+ export function todoBody(text, lang) {
223
+ const comment = commentStart(text, lang);
224
+ const marker = TODO_MARKER.exec(text);
225
+ if (marker === null || !inComment(comment, marker.index))
226
+ return undefined;
227
+ const between = text.slice(comment ?? 0, marker.index);
228
+ if (!onlyCommentOpener(between))
229
+ return undefined;
230
+ return text.slice(marker.index).replace(/\*\/\s*$/, "");
231
+ }
232
+ /**
233
+ * Every subject the caller's patterns will be asked about, in the order the
234
+ * lint visits them: the TODO bodies (for a ticket pattern) and the added
235
+ * lines (for machine-path patterns) of every file the lint scans. DiffLint
236
+ * answers these in the regex worker, then lints with the answers.
237
+ */
238
+ export function callerPatternSubjects(parsed, options = {}) {
239
+ const active = activeRules(options);
240
+ const todoBodies = [];
241
+ const lines = [];
242
+ for (const file of parsed.files) {
243
+ if (skipReason(file) !== undefined || file.hunks.length === 0)
244
+ continue;
245
+ const lang = languageOf(file.newPath ?? file.oldPath ?? "(unknown path)");
246
+ for (const hunk of file.hunks) {
247
+ for (const parsedLine of hunk.lines) {
248
+ if (parsedLine.kind !== "added" || parsedLine.newLine === null)
249
+ continue;
250
+ if (active.has("machinePath"))
251
+ lines.push(parsedLine.text);
252
+ if (active.has("ticketlessTodo")) {
253
+ const body = todoBody(parsedLine.text, lang);
254
+ if (body !== undefined)
255
+ todoBodies.push(body);
256
+ }
257
+ }
258
+ }
259
+ }
260
+ return { todoBodies, lines };
261
+ }
211
262
  /**
212
263
  * Suppressions worth reporting when they are NEW.
213
264
  *
@@ -344,7 +395,7 @@ const snippet = (text) => {
344
395
  function skipReason(file) {
345
396
  return file.binary ? "binary file — no text to lint" : undefined;
346
397
  }
347
- function lineHits(text, lang, active, opts, fileHasStrongConflict) {
398
+ function lineHits(text, lang, active, opts, fileHasStrongConflict, onUndetermined = () => undefined) {
348
399
  const hits = [];
349
400
  const comment = commentStart(text, lang);
350
401
  const maxLineChars = opts.maxLineChars ?? DEFAULT_MAX_LINE_CHARS;
@@ -402,22 +453,19 @@ function lineHits(text, lang, active, opts, fileHasStrongConflict) {
402
453
  }
403
454
  }
404
455
  if (active.has("ticketlessTodo")) {
405
- const marker = TODO_MARKER.exec(text);
406
- // The marker must OPEN the comment: `// TODO: x` is a note to a
407
- // maintainer, and "a TODO with no ticket" in the middle of a sentence is
408
- // prose about todos. With the whole file a mask would decide this; with
409
- // one line, where the marker sits is the signal there is.
410
- if (marker !== null && inComment(comment, marker.index)) {
411
- const between = text.slice(comment ?? 0, marker.index);
412
- if (/^(?:\/\/+|\/\*+|#+|\*+|--|<!--)?[\s\-*>]*$/.test(between)) {
413
- const body = text.slice(marker.index).replace(/\*\/\s*$/, "");
414
- const ticket = opts.ticketPattern ?? DEFAULT_TICKET;
415
- if (!ticket.test(body)) {
416
- hits.push({
417
- rule: "ticketlessTodo",
418
- message: "a TODO/FIXME/HACK with no ticket or issue reference — nobody will ever find it",
419
- });
420
- }
456
+ const body = todoBody(text, lang);
457
+ if (body !== undefined) {
458
+ const hasTicket = opts.ticketTest !== undefined
459
+ ? opts.ticketTest.test(body)
460
+ : (opts.ticketPattern ?? DEFAULT_TICKET).test(body);
461
+ if (hasTicket === undefined) {
462
+ onUndetermined("ticketlessTodo", opts.ticketTest?.source ?? "");
463
+ }
464
+ else if (!hasTicket) {
465
+ hits.push({
466
+ rule: "ticketlessTodo",
467
+ message: "a TODO/FIXME/HACK with no ticket or issue reference — nobody will ever find it",
468
+ });
421
469
  }
422
470
  }
423
471
  }
@@ -432,8 +480,18 @@ function lineHits(text, lang, active, opts, fileHasStrongConflict) {
432
480
  });
433
481
  break; // one path finding per line is enough to act on
434
482
  }
435
- for (const extra of opts.machinePathPatterns ?? []) {
436
- if (!extra.test(text))
483
+ const extras = opts.machinePathTests ??
484
+ (opts.machinePathPatterns ?? []).map((re) => ({
485
+ source: re.source,
486
+ test: (t) => re.test(t),
487
+ }));
488
+ for (const extra of extras) {
489
+ const hit = extra.test(text);
490
+ if (hit === undefined) {
491
+ onUndetermined("machinePath", extra.source);
492
+ continue;
493
+ }
494
+ if (!hit)
437
495
  continue;
438
496
  hits.push({
439
497
  rule: "machinePath",
@@ -474,6 +532,8 @@ export function lintParsedDiff(parsed, options = {}) {
474
532
  const byRule = {};
475
533
  const bySeverity = { error: 0, warning: 0 };
476
534
  const skipped = [];
535
+ const undetermined = [];
536
+ let undeterminedCount = 0;
477
537
  let filesScanned = 0;
478
538
  let addedLinesScanned = 0;
479
539
  let total = 0;
@@ -527,7 +587,13 @@ export function lintParsedDiff(parsed, options = {}) {
527
587
  if (crlfSeen === 1)
528
588
  crlfFirst = line.line;
529
589
  }
530
- for (const hit of lineHits(line.text, lang, active, options, strongConflict)) {
590
+ const onUndetermined = (rule, pattern) => {
591
+ undeterminedCount++;
592
+ if (undetermined.length < MAX_UNDETERMINED) {
593
+ undetermined.push({ rule, file: path, line: line.line, pattern });
594
+ }
595
+ };
596
+ for (const hit of lineHits(line.text, lang, active, options, strongConflict, onUndetermined)) {
531
597
  record({
532
598
  rule: hit.rule,
533
599
  severity: hit.severity ?? DEFAULT_SEVERITY[hit.rule],
@@ -556,5 +622,7 @@ export function lintParsedDiff(parsed, options = {}) {
556
622
  counts: { byRule, bySeverity },
557
623
  skipped,
558
624
  truncated: total > findings.length,
625
+ undetermined,
626
+ undeterminedCount,
559
627
  };
560
628
  }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Line reads that used to be regular expressions, and rescanned a run.
3
+ *
4
+ * Each pattern below tried every start inside a run of whitespace (or of
5
+ * fence or comment characters) and, when what follows the run was not what
6
+ * it needed, rescanned the rest of the run from each before giving the start
7
+ * up: quadratic in the run's length. A diff and a document are whatever the
8
+ * workspace or the model hands over, so each is a scan that gives the same
9
+ * answer.
10
+ */
11
+ /** A code unit `\s` matches: WhiteSpace or LineTerminator. */
12
+ export declare function isRegExpSpace(c: number): boolean;
13
+ /** `text` before its first ` as `: what `text.split(/\s+as\s+/)[0]` returned. */
14
+ export declare function beforeAs(text: string): string;
15
+ /**
16
+ * A fence line's marker and info string: what
17
+ * `/^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(line)` captured, or `null`. Up to three
18
+ * whitespace characters, a run of three or more of one fence character, and a
19
+ * rest holding no line break.
20
+ */
21
+ export declare function fenceOpening(line: string): {
22
+ marker: string;
23
+ info: string;
24
+ } | null;
25
+ /**
26
+ * Whether `text` is only a comment opener and filler: what
27
+ * `/^(?:\/\/+|\/\*+|#+|\*+|--|<!--)?[\s\-*>]*$/.test(text)` answered. An
28
+ * opener of `*`, `--` or `/*` needs no case of its own past its first
29
+ * character, because `*` and `-` are filler too.
30
+ */
31
+ export declare function onlyCommentOpener(text: string): boolean;
@@ -0,0 +1,106 @@
1
+ /**
2
+ * Line reads that used to be regular expressions, and rescanned a run.
3
+ *
4
+ * Each pattern below tried every start inside a run of whitespace (or of
5
+ * fence or comment characters) and, when what follows the run was not what
6
+ * it needed, rescanned the rest of the run from each before giving the start
7
+ * up: quadratic in the run's length. A diff and a document are whatever the
8
+ * workspace or the model hands over, so each is a scan that gives the same
9
+ * answer.
10
+ */
11
+ /** A code unit `\s` matches: WhiteSpace or LineTerminator. */
12
+ export function isRegExpSpace(c) {
13
+ return ((c >= 0x09 && c <= 0x0d) ||
14
+ c === 0x20 ||
15
+ c === 0xa0 ||
16
+ c === 0x1680 ||
17
+ (c >= 0x2000 && c <= 0x200a) ||
18
+ c === 0x2028 ||
19
+ c === 0x2029 ||
20
+ c === 0x202f ||
21
+ c === 0x205f ||
22
+ c === 0x3000 ||
23
+ c === 0xfeff);
24
+ }
25
+ /** A code unit `.` does not match without the `s` flag. */
26
+ function isLineBreak(c) {
27
+ return c === 0x0a || c === 0x0d || c === 0x2028 || c === 0x2029;
28
+ }
29
+ /** `text` before its first ` as `: what `text.split(/\s+as\s+/)[0]` returned. */
30
+ export function beforeAs(text) {
31
+ let i = 0;
32
+ while (i < text.length) {
33
+ if (!isRegExpSpace(text.charCodeAt(i))) {
34
+ i++;
35
+ continue;
36
+ }
37
+ const runStart = i;
38
+ while (i < text.length && isRegExpSpace(text.charCodeAt(i)))
39
+ i++;
40
+ if (text.charCodeAt(i) === 0x61 &&
41
+ text.charCodeAt(i + 1) === 0x73 &&
42
+ i + 2 < text.length &&
43
+ isRegExpSpace(text.charCodeAt(i + 2))) {
44
+ return text.slice(0, runStart);
45
+ }
46
+ }
47
+ return text;
48
+ }
49
+ /**
50
+ * A fence line's marker and info string: what
51
+ * `/^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(line)` captured, or `null`. Up to three
52
+ * whitespace characters, a run of three or more of one fence character, and a
53
+ * rest holding no line break.
54
+ */
55
+ export function fenceOpening(line) {
56
+ let start = 0;
57
+ while (start < 3 && start < line.length && isRegExpSpace(line.charCodeAt(start)))
58
+ start++;
59
+ const ch = line.charCodeAt(start);
60
+ if (ch !== 0x60 && ch !== 0x7e)
61
+ return null;
62
+ let end = start;
63
+ while (end < line.length && line.charCodeAt(end) === ch)
64
+ end++;
65
+ if (end - start < 3)
66
+ return null;
67
+ for (let i = end; i < line.length; i++)
68
+ if (isLineBreak(line.charCodeAt(i)))
69
+ return null;
70
+ return { marker: line.slice(start, end), info: line.slice(end) };
71
+ }
72
+ /** A code unit `[\s\-*>]` matches. */
73
+ const isCommentFill = (c) => isRegExpSpace(c) || c === 0x2d || c === 0x2a || c === 0x3e;
74
+ function allCommentFill(text, from) {
75
+ for (let i = from; i < text.length; i++)
76
+ if (!isCommentFill(text.charCodeAt(i)))
77
+ return false;
78
+ return true;
79
+ }
80
+ /**
81
+ * Whether `text` is only a comment opener and filler: what
82
+ * `/^(?:\/\/+|\/\*+|#+|\*+|--|<!--)?[\s\-*>]*$/.test(text)` answered. An
83
+ * opener of `*`, `--` or `/*` needs no case of its own past its first
84
+ * character, because `*` and `-` are filler too.
85
+ */
86
+ export function onlyCommentOpener(text) {
87
+ if (allCommentFill(text, 0))
88
+ return true;
89
+ if (text.startsWith("//")) {
90
+ let i = 2;
91
+ while (text.charCodeAt(i) === 0x2f)
92
+ i++;
93
+ return allCommentFill(text, i);
94
+ }
95
+ if (text.startsWith("/*"))
96
+ return allCommentFill(text, 1);
97
+ if (text.startsWith("#")) {
98
+ let i = 1;
99
+ while (text.charCodeAt(i) === 0x23)
100
+ i++;
101
+ return allCommentFill(text, i);
102
+ }
103
+ if (text.startsWith("<!--"))
104
+ return allCommentFill(text, 4);
105
+ return false;
106
+ }
package/dist/paths.d.ts CHANGED
@@ -1,10 +1,29 @@
1
1
  import { CrewhausError } from "@crewhaus/errors";
2
- /** Raised when a caller-supplied path resolves outside the workspace root. */
2
+ /**
3
+ * The longest path this resolves, in UTF-16 code units; a longer one is
4
+ * refused before it is walked. Nothing that long can be opened or created:
5
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
6
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
7
+ * UTF-16 one. The limit is twice that because the part of a path that exists
8
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
9
+ * own: no spelling of the place reaches it, not even one through a symlink
10
+ * that shortens the part that exists.
11
+ */
12
+ export declare const MAX_PATH_CHARS: number;
13
+ /**
14
+ * Raised when a caller-supplied path resolves outside the workspace root, or
15
+ * is longer than any path can be.
16
+ */
3
17
  export declare class ToolPermissionError extends CrewhausError {
4
18
  readonly name = "ToolPermissionError";
5
19
  readonly toolName: string;
6
20
  readonly path: string;
7
- constructor(toolName: string, attemptedPath: string);
21
+ /**
22
+ * Why, when it is not that the location escapes the workspace root: a path
23
+ * longer than any path can be. A caller that rewords the refusal says this.
24
+ */
25
+ readonly reason: string | undefined;
26
+ constructor(toolName: string, attemptedPath: string, reason?: string);
8
27
  }
9
28
  /**
10
29
  * A validated path, in both forms the tools need.
package/dist/paths.js CHANGED
@@ -11,15 +11,45 @@
11
11
  import { lstatSync, readlinkSync, realpathSync } from "node:fs";
12
12
  import * as path from "node:path";
13
13
  import { CrewhausError } from "@crewhaus/errors";
14
- /** Raised when a caller-supplied path resolves outside the workspace root. */
14
+ /**
15
+ * The longest path this resolves, in UTF-16 code units; a longer one is
16
+ * refused before it is walked. Nothing that long can be opened or created:
17
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
18
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
19
+ * UTF-16 one. The limit is twice that because the part of a path that exists
20
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
21
+ * own: no spelling of the place reaches it, not even one through a symlink
22
+ * that shortens the part that exists.
23
+ */
24
+ export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
25
+ /** A path as a refusal quotes it: whole, unless it is past {@link MAX_PATH_CHARS}. */
26
+ function shownPath(given) {
27
+ return given.length > MAX_PATH_CHARS ? `${given.slice(0, 64)}…` : given;
28
+ }
29
+ /** Why a path past {@link MAX_PATH_CHARS} is refused: its length and the limit. */
30
+ function tooLong(abs) {
31
+ return `it is ${abs.length} characters once resolved, over the ${MAX_PATH_CHARS}-character limit: no path that long can be opened or created`;
32
+ }
33
+ /**
34
+ * Raised when a caller-supplied path resolves outside the workspace root, or
35
+ * is longer than any path can be.
36
+ */
15
37
  export class ToolPermissionError extends CrewhausError {
16
38
  name = "ToolPermissionError";
17
39
  toolName;
18
40
  path;
19
- constructor(toolName, attemptedPath) {
20
- super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
41
+ /**
42
+ * Why, when it is not that the location escapes the workspace root: a path
43
+ * longer than any path can be. A caller that rewords the refusal says this.
44
+ */
45
+ reason;
46
+ constructor(toolName, attemptedPath, reason) {
47
+ super("tool", reason === undefined
48
+ ? `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`
49
+ : `tool "${toolName}" rejected path "${shownPath(attemptedPath)}": ${reason}`);
21
50
  this.toolName = toolName;
22
51
  this.path = attemptedPath;
52
+ this.reason = reason;
23
53
  }
24
54
  }
25
55
  /** The workspace root, resolved. Every path is contained within it. */
@@ -67,15 +97,7 @@ function nameExists(p) {
67
97
  function resolveLocation(target, depth = 0) {
68
98
  if (depth > 40)
69
99
  throw new Error(`symlink chain at "${target}" is too long to resolve`);
70
- let probe = target;
71
- const tail = [];
72
- while (!nameExists(probe)) {
73
- tail.unshift(path.basename(probe));
74
- const parent = path.dirname(probe);
75
- if (parent === probe)
76
- break; // reached the filesystem root
77
- probe = parent;
78
- }
100
+ const { probe, tail } = deepestName(target);
79
101
  let probeReal;
80
102
  try {
81
103
  probeReal = realpathSync(probe);
@@ -97,7 +119,41 @@ function resolveLocation(target, depth = 0) {
97
119
  const base = realpathSync(path.dirname(probe));
98
120
  probeReal = resolveLocation(path.resolve(base, link), depth + 1);
99
121
  }
100
- return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
122
+ // One string, not one argument per name: Bun's `path.join` keeps only
123
+ // (argument count mod 65,536) of its arguments.
124
+ return tail.length > 0 ? path.join(probeReal, tail) : probeReal;
125
+ }
126
+ /**
127
+ * `target`, an absolute path, split where its deepest prefix that exists as
128
+ * a NAME ends: that prefix, and the names below it, which do not exist, as
129
+ * one string ("" when `target` itself exists). This is `path.dirname` and
130
+ * `path.basename` worked by index on `target` itself: handing them each
131
+ * shorter prefix in turn copied the rest of the path once per missing name,
132
+ * the square of a count the caller picks.
133
+ */
134
+ function deepestName(target) {
135
+ const top = path.parse(target).root.length;
136
+ const isSep = (i) => target[i] === "/" || target[i] === path.sep;
137
+ let probe = target;
138
+ let start = target.length;
139
+ let stop = -1;
140
+ while (!nameExists(probe)) {
141
+ // `path.basename(probe)` is `target.slice(start, end)`, and
142
+ // `path.dirname(probe)` is `target.slice(0, up)`.
143
+ let end = probe.length;
144
+ while (end > top && isSep(end - 1))
145
+ end--;
146
+ if (stop < 0)
147
+ stop = end;
148
+ start = end;
149
+ while (start > top && !isSep(start - 1))
150
+ start--;
151
+ const up = start > top ? start - 1 : top;
152
+ if (up === probe.length)
153
+ break; // reached the filesystem root
154
+ probe = target.slice(0, up);
155
+ }
156
+ return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
101
157
  }
102
158
  export function resolveSafe(toolName, rel, root = workspaceRoot()) {
103
159
  const rootResolved = path.resolve(root);
@@ -107,6 +163,9 @@ export function resolveSafe(toolName, rel, root = workspaceRoot()) {
107
163
  if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
108
164
  throw new ToolPermissionError(toolName, rel);
109
165
  }
166
+ // Longer than any path can be: refused before the walk below reads it.
167
+ if (abs.length > MAX_PATH_CHARS)
168
+ throw new ToolPermissionError(toolName, rel, tooLong(abs));
110
169
  let real;
111
170
  try {
112
171
  const rootReal = realpathSync(rootResolved);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/tool-changeset",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "type": "module",
5
5
  "description": "Deterministic change-set review: lint only the added lines of a diff, and check that documented symbols still exist",
6
6
  "main": "dist/index.js",
@@ -8,18 +8,21 @@
8
8
  "exports": {
9
9
  ".": {
10
10
  "types": "./dist/index.d.ts",
11
- "import": "./dist/index.js"
11
+ "import": "./dist/index.js",
12
+ "default": "./dist/index.js"
12
13
  }
13
14
  },
14
15
  "scripts": {
15
16
  "test": "bun test src"
16
17
  },
17
18
  "dependencies": {
18
- "@crewhaus/errors": "0.7.0",
19
- "@crewhaus/tool-builder": "0.7.0",
20
- "@crewhaus/tool-catalog": "0.7.0",
21
- "@crewhaus/tool-code": "0.7.0",
22
- "@crewhaus/tool-text": "0.7.0",
19
+ "@crewhaus/errors": "0.8.0",
20
+ "@crewhaus/tool-builder": "0.8.0",
21
+ "@crewhaus/tool-catalog": "0.8.0",
22
+ "@crewhaus/tool-code": "0.8.0",
23
+ "@crewhaus/tool-git": "0.8.0",
24
+ "@crewhaus/tool-safety": "0.8.0",
25
+ "@crewhaus/tool-text": "0.8.0",
23
26
  "zod": "^3.23.8"
24
27
  },
25
28
  "devDependencies": {
@@ -43,5 +46,8 @@
43
46
  "publishConfig": {
44
47
  "access": "public"
45
48
  },
46
- "files": ["dist", "README.md", "LICENSE", "NOTICE"]
49
+ "files": ["dist", "README.md", "LICENSE", "NOTICE"],
50
+ "engines": {
51
+ "bun": ">=1.3.14"
52
+ }
47
53
  }