lawcheck 0.0.0 → 0.1.0-alpha.1

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.
Files changed (75) hide show
  1. package/README.md +34 -2
  2. package/dist/args.js +168 -0
  3. package/dist/bin.cjs +20 -0
  4. package/dist/check.js +472 -0
  5. package/dist/cli.js +182 -0
  6. package/dist/config.js +278 -0
  7. package/dist/docs.js +41 -0
  8. package/dist/doctor.js +273 -0
  9. package/dist/environment.js +73 -0
  10. package/dist/explain.js +446 -0
  11. package/dist/files.js +388 -0
  12. package/dist/glob.js +268 -0
  13. package/dist/grammars/LICENSES.txt +353 -0
  14. package/dist/grammars/tree-sitter-c.wasm +0 -0
  15. package/dist/grammars/tree-sitter-c_sharp.wasm +0 -0
  16. package/dist/grammars/tree-sitter-cpp.wasm +0 -0
  17. package/dist/grammars/tree-sitter-go.wasm +0 -0
  18. package/dist/grammars/tree-sitter-java.wasm +0 -0
  19. package/dist/grammars/tree-sitter-javascript.wasm +0 -0
  20. package/dist/grammars/tree-sitter-kotlin.wasm +0 -0
  21. package/dist/grammars/tree-sitter-php.wasm +0 -0
  22. package/dist/grammars/tree-sitter-python.wasm +0 -0
  23. package/dist/grammars/tree-sitter-ruby.wasm +0 -0
  24. package/dist/grammars/tree-sitter-rust.wasm +0 -0
  25. package/dist/grammars/tree-sitter-tsx.wasm +0 -0
  26. package/dist/grammars/tree-sitter-typescript.wasm +0 -0
  27. package/dist/guard.js +179 -0
  28. package/dist/init.js +131 -0
  29. package/dist/keys.js +55 -0
  30. package/dist/law.js +416 -0
  31. package/dist/lawchange.js +208 -0
  32. package/dist/limits.js +207 -0
  33. package/dist/main.js +77 -0
  34. package/dist/names.js +117 -0
  35. package/dist/output.js +325 -0
  36. package/dist/prime.js +211 -0
  37. package/dist/programs.js +177 -0
  38. package/dist/progress.js +42 -0
  39. package/dist/prompt.js +317 -0
  40. package/dist/providers/anthropic.js +33 -0
  41. package/dist/providers/claude-code.js +41 -0
  42. package/dist/providers/codex.js +75 -0
  43. package/dist/providers/copilot-cli.js +56 -0
  44. package/dist/providers/gemini-cli.js +30 -0
  45. package/dist/providers/google.js +31 -0
  46. package/dist/providers/http.js +138 -0
  47. package/dist/providers/index.js +96 -0
  48. package/dist/providers/ollama.js +39 -0
  49. package/dist/providers/openai-compatible.js +41 -0
  50. package/dist/providers/openai.js +17 -0
  51. package/dist/providers/program.js +282 -0
  52. package/dist/readers.js +286 -0
  53. package/dist/review.js +116 -0
  54. package/dist/rules.js +418 -0
  55. package/dist/runner.js +177 -0
  56. package/dist/setup.js +388 -0
  57. package/dist/try.js +346 -0
  58. package/dist/types.js +99 -0
  59. package/dist/uses.js +78 -0
  60. package/dist/verdicts.js +337 -0
  61. package/dist/waivers.js +70 -0
  62. package/dist/work.js +21 -0
  63. package/docs/change.md +62 -0
  64. package/docs/ci.md +133 -0
  65. package/docs/codes.md +60 -0
  66. package/docs/config.md +117 -0
  67. package/docs/first-law.md +189 -0
  68. package/docs/json.md +72 -0
  69. package/docs/languages.md +87 -0
  70. package/docs/law.md +95 -0
  71. package/docs/providers.md +105 -0
  72. package/docs/reviewer-rules.md +96 -0
  73. package/docs/script-rules.md +90 -0
  74. package/docs/waivers.md +56 -0
  75. package/package.json +59 -3
package/dist/check.js ADDED
@@ -0,0 +1,472 @@
1
+ import { join } from 'node:path';
2
+ import { comparePaths, nestedReason, nestedRepositories, repositoryHolding, trackedLinks, workTreeTop } from './files.js';
3
+ import { compilePattern } from './glob.js';
4
+ import { hide } from './keys.js';
5
+ import { takesWaivers } from './law.js';
6
+ import { fixNext, plural, sortFindings, WHY } from './output.js';
7
+ import { buildPrompt, cleanMessage, FRAME, size } from './prompt.js';
8
+ import { createProvider } from './providers/index.js';
9
+ import { readerOf, readUses, siblingsOf, Unreadable } from './readers.js';
10
+ import { lawChangeLine, lawChanges } from './lawchange.js';
11
+ import { call, preflight } from './review.js';
12
+ import { crashNext, FindingBudget, linksOut, rulesDeadline, runAll, runnerProblem, runRule, slowMessage } from './rules.js';
13
+ import { filesOfTypes, isBinary } from './types.js';
14
+ import { bytesOf, selectTargets } from './try.js';
15
+ import { fromCwd, loadConfig, loadLaw, loadRuleFiles, locate, requireGit, RULES_DIR, LAW, stopped, theChange, touchesLaw, typeAll } from './setup.js';
16
+ import { judgeUses, listInForce, notRead } from './uses.js';
17
+ import { countPasses, FULL_NEXT, readFailure, readVerdicts, reviewKey, Unwritable, VERDICTS, VerdictsFull, VerdictsUnreadable, VerdictWriter } from './verdicts.js';
18
+ import { parseWaivers, waive, waivedLines } from './waivers.js';
19
+ import { count, mib, points, readError, RUN_FINDINGS, RUN_MESSAGE_CHARS, USES_FILE_BYTES } from './limits.js';
20
+ import { step } from './progress.js';
21
+ export { findRoot } from './setup.js';
22
+ export async function check(options, context) {
23
+ return stopped(async () => {
24
+ const root = locate(context.cwd);
25
+ requireGit(root);
26
+ const law = loadLaw(root);
27
+ const config = loadConfig(root);
28
+ const { listed, files, read, kinds } = loadRuleFiles(root, law, false);
29
+ const named = options.paths !== undefined && options.paths.length > 0;
30
+ const chosen = named ? selectTargets(root, context.cwd, options.paths, files, (path) => isBinary(bytesOf(read, path)), true) : null;
31
+ const typed = typeAll(root, law, files, read, kinds.unreadable);
32
+ const elsewhere = named ? inOtherRepositories(root, context.cwd, options.paths, chosen, listed) : [];
33
+ return checkAt(root, options, context, { law, config, listed, files, read, kinds, typed, chosen, elsewhere });
34
+ });
35
+ }
36
+ function linkError(link) {
37
+ return { code: 'link-outside-root', file: link.path, line: null, message: `the link leads to ${link.target}, outside the git work tree and Lawcheck's folder, and a script rule could read through it` };
38
+ }
39
+ async function checkAt(root, options, context, front) {
40
+ const { law, config, files, read, kinds, typed, chosen } = front;
41
+ const named = chosen !== null;
42
+ const { base, changed } = named ? { base: null, changed: new Set(chosen) } : theChange(root, files, options.base, context.env, options.full);
43
+ const lawChanged = base !== null && [...changed].some(touchesLaw);
44
+ const run = options.full ? typed : typed.filter((file) => changed.has(file.path));
45
+ run.sort((a, b) => comparePaths(a.path, b.path));
46
+ const filesOf = filesOfTypes(typed, law);
47
+ const budget = new FindingBudget();
48
+ const deadline = rulesDeadline();
49
+ const tasks = [...kinds.scripts]
50
+ .map((rule) => ({ rule, files: run.filter((file) => file.rules.includes(rule)) }))
51
+ .filter(({ files: bound }) => bound.length > 0)
52
+ .map(({ rule, files: bound }) => async () => ({
53
+ rule,
54
+ outcome: deadline.signal.aborted
55
+ ? { slow: slowMessage('not started') }
56
+ : await runRule({ root, rule, ruleFile: join(root, `${RULES_DIR}${rule}.mjs`), files: bound, filesOf, budget, signal: deadline.signal }),
57
+ }));
58
+ const unsupported = tasks.length === 0 ? null : runnerProblem(root);
59
+ if (unsupported !== null)
60
+ return { errors: [{ code: 'path-unsupported', file: null, line: null, message: unsupported }] };
61
+ const out = tasks.length === 0 ? [] : linksOut(root, workTreeTop(root), trackedLinks(root));
62
+ if (out.length > 0)
63
+ return { errors: out.map(linkError) };
64
+ const outcomes = await runAll(tasks);
65
+ deadline.clear();
66
+ const crashes = [];
67
+ const raw = [];
68
+ for (const { rule, outcome } of outcomes) {
69
+ if ('broken' in outcome)
70
+ return { errors: [{ code: 'runner-failed', file: null, line: null, message: outcome.broken }] };
71
+ if ('crash' in outcome) {
72
+ const next = crashNext(outcome.crash);
73
+ crashes.push({ code: 'rule-crashed', file: `${RULES_DIR}${rule}.mjs`, line: null, message: outcome.crash, ...(next === undefined ? {} : { next }) });
74
+ }
75
+ else if ('slow' in outcome)
76
+ crashes.push({ code: 'rules-too-slow', file: `${RULES_DIR}${rule}.mjs`, line: null, message: outcome.slow });
77
+ else
78
+ for (const finding of outcome.findings)
79
+ raw.push(finding);
80
+ }
81
+ if (crashes.length > 0)
82
+ return { errors: crashes };
83
+ if (budget.passed())
84
+ return { errors: tooManyFindings(budget) };
85
+ const uses = await readTheUses(root, files, read, typed, run, changed);
86
+ if ('errors' in uses)
87
+ return { errors: uses.errors };
88
+ const byFile = new Map();
89
+ const tally = (path, text) => {
90
+ const own = byFile.get(path) ?? { count: 0, chars: 0 };
91
+ byFile.set(path, { count: own.count + 1, chars: own.chars + points(text) });
92
+ };
93
+ for (const item of uses.forbidden)
94
+ tally(item.file, item.message);
95
+ for (const item of uses.unresolved)
96
+ tally(item.file, item.what);
97
+ for (const item of uses.notRead)
98
+ tally(LAW, item.message);
99
+ for (const item of uses.tooLarge)
100
+ tally(item.file, item.message);
101
+ for (const path of [...byFile.keys()].sort(comparePaths)) {
102
+ const own = byFile.get(path);
103
+ if (budget.addAt(own.count, own.chars))
104
+ return { errors: [tooManyAt(path, budget)] };
105
+ }
106
+ const ruleIds = new Set([...law.rules.keys(), 'forbidden-use']);
107
+ const waiversOf = new Map();
108
+ for (const file of run) {
109
+ const parsed = takesWaivers(file.type) ? parseWaivers(file.lines, ruleIds) : { waivers: [], problems: [] };
110
+ waiversOf.set(file.path, parsed);
111
+ let chars = 0;
112
+ for (const problem of parsed.problems)
113
+ chars += points(problem.message);
114
+ for (const waiver of parsed.waivers)
115
+ chars += points(waiver.reason);
116
+ if (budget.addAt(parsed.problems.length + parsed.waivers.length, chars))
117
+ return { errors: [tooManyAt(file.path, budget)] };
118
+ }
119
+ const review = `lawcheck check --review${options.base === null ? '' : ` --base ${hide(options.base)}`}`;
120
+ const cap = options.maxCalls ?? config.maxCalls;
121
+ const roomOf = () => verdictRoom(root, law, typed, kinds);
122
+ let verdicts;
123
+ try {
124
+ verdicts = readVerdicts(root);
125
+ }
126
+ catch (error) {
127
+ if (!(error instanceof VerdictsUnreadable) || !error.cause.startsWith('it holds more'))
128
+ throw error;
129
+ return { errors: [{ code: 'file-unreadable', file: VERDICTS, line: null, message: `the file cannot be read (${error.cause}); ${roomOf()}`, next: FULL_NEXT }] };
130
+ }
131
+ const asks = [];
132
+ const builtIn = [];
133
+ const reviewerRaw = (file, rule, findings) => {
134
+ for (const finding of findings) {
135
+ const item = { rule, file, message: cleanMessage(finding.message) };
136
+ if (finding.line !== null)
137
+ item.line = finding.line;
138
+ raw.push(item);
139
+ }
140
+ };
141
+ for (const file of run) {
142
+ const bound = file.rules.filter((rule) => kinds.reviewers.has(rule)).sort(comparePaths);
143
+ for (const rule of bound) {
144
+ const reviewer = kinds.reviewers.get(rule);
145
+ const why = law.rules.get(rule).why;
146
+ const waived = waivedLines(waiversOf.get(file.path).waivers, rule);
147
+ const key = reviewKey({ frame: FRAME, ruleId: rule, why, ruleText: reviewer.text, context: reviewer.context, filePath: file.path, fileText: file.text, waived });
148
+ if (verdicts.has(`${key} ${rule}`))
149
+ continue;
150
+ const lineCount = file.lines.length;
151
+ if (!options.again) {
152
+ const cached = readFailure(root, key, rule, lineCount);
153
+ if (cached !== null) {
154
+ let chars = 0;
155
+ for (const finding of cached)
156
+ chars += points(finding.message);
157
+ if (budget.addAt(cached.length, chars))
158
+ return { errors: [tooManyAt(file.path, budget)] };
159
+ reviewerRaw(file.path, rule, cached);
160
+ continue;
161
+ }
162
+ }
163
+ const prompt = buildPrompt({ why, ruleText: reviewer.text, context: reviewer.context, filePath: file.path, fileText: file.text, waived });
164
+ const characters = size(prompt);
165
+ if (characters > config.maxChars) {
166
+ builtIn.push({
167
+ code: 'too-large-to-review',
168
+ rule,
169
+ file: file.path,
170
+ message: `the prompt for ${rule} holds ${characters} characters; reviewer.max_chars is ${config.maxChars}`,
171
+ });
172
+ continue;
173
+ }
174
+ asks.push({ file: file.path, rule, key, prompt, lineCount, waived: new Set(waived) });
175
+ }
176
+ }
177
+ let callsMade = 0;
178
+ let passesRecorded = 0;
179
+ let missing = asks;
180
+ if (options.review && asks.length > 0) {
181
+ const provider = createProvider(config, context.env);
182
+ const blocked = preflight(provider, config, cap, asks.length, review);
183
+ if (blocked.length > 0)
184
+ return { errors: blocked };
185
+ const writer = new VerdictWriter(root);
186
+ try {
187
+ writer.ready(asks.map((ask) => ask.rule));
188
+ }
189
+ catch (error) {
190
+ if (!(error instanceof VerdictsFull))
191
+ throw error;
192
+ return { errors: [{ code: 'file-unwritable', file: VERDICTS, line: null, message: `cannot be written (${error.cause}); ${roomOf()}`, next: FULL_NEXT }] };
193
+ }
194
+ context.warn?.(`lawcheck: ${plural(asks.length, 'reviewer call')} to ${config.provider}`);
195
+ let result;
196
+ try {
197
+ result = await call(asks, provider, writer, { cap, parallel: config.parallel, timeoutSeconds: config.timeout });
198
+ }
199
+ catch (error) {
200
+ if (!(error instanceof Unwritable))
201
+ throw error;
202
+ const room = error instanceof VerdictsFull ? `; ${roomOf()}` : '';
203
+ return { errors: [{ code: 'file-unwritable', file: error.path, line: null, message: `cannot be written (${error.cause}), so the answers of the reviewer calls this run made are lost${room}`, ...(error.next === null ? {} : { next: error.next }) }] };
204
+ }
205
+ if (result.failed.length > 0) {
206
+ const again = 'run the same command again; what was answered is kept, so it asks only the rest';
207
+ return {
208
+ errors: result.failed.map((f) => ({ code: f.code, file: f.ask.file, line: null, message: f.message, ...(f.fix === undefined ? {} : { next: `${f.fix}, then ${again}` }) })),
209
+ };
210
+ }
211
+ for (const answered of result.answered) {
212
+ let chars = 0;
213
+ for (const finding of answered.findings)
214
+ chars += points(finding.message);
215
+ if (budget.addAt(answered.findings.length, chars))
216
+ return { errors: [tooManyAt(answered.ask.file, budget)] };
217
+ reviewerRaw(answered.ask.file, answered.ask.rule, answered.findings);
218
+ }
219
+ callsMade = result.sent;
220
+ passesRecorded = writer.added;
221
+ missing = [];
222
+ }
223
+ for (const ask of missing) {
224
+ const message = `${ask.rule} has no verdict for this content`;
225
+ if (budget.addAt(1, points(message)))
226
+ return { errors: [tooManyAt(ask.file, budget)] };
227
+ builtIn.push({ code: 'not-reviewed', rule: ask.rule, file: ask.file, message });
228
+ }
229
+ step('judging the findings');
230
+ const report = judge(law, run, raw, builtIn, uses, waiversOf, kinds.reviewers, changed, base, named ? 'paths' : options.full ? 'full' : 'change');
231
+ report.reviews = {
232
+ missing: [...report.findings, ...report.debt].filter((f) => f.code === 'not-reviewed').length,
233
+ calls_made: callsMade,
234
+ passes_recorded: passesRecorded,
235
+ };
236
+ report.next = nextOf(report, config, cap, review);
237
+ report.lawChanged = lawChanged;
238
+ const notes = [];
239
+ if (lawChanged) {
240
+ const told = lawChanges(root, base, files, changed, new Set(run.filter((file) => !takesWaivers(file.type)).map((file) => file.path)));
241
+ if (!options.full)
242
+ notes.push(`note: the law changed in this change; lawcheck check --full${options.base === null ? '' : ` --base ${options.base}`} shows what it finds in the rest of the code`);
243
+ if (told.length > 0) {
244
+ report.lawChanges = told;
245
+ notes.push(lawChangeLine(told));
246
+ }
247
+ }
248
+ if (!named) {
249
+ const unseen = unseenRepositories(root, front.listed, law);
250
+ if (unseen !== null)
251
+ notes.push(unseen);
252
+ }
253
+ notes.push(...front.elsewhere);
254
+ report.note = notes.length === 0 ? null : notes.join('\n');
255
+ return { report };
256
+ }
257
+ // A named path below a submodule or a repository of its own selects nothing, and the note says why rather than a bare count of 0.
258
+ function inOtherRepositories(root, cwd, words, chosen, listed) {
259
+ const notes = [];
260
+ for (const word of words) {
261
+ let path;
262
+ try {
263
+ path = fromCwd(root, cwd, word);
264
+ }
265
+ catch {
266
+ continue;
267
+ }
268
+ const nested = repositoryHolding(root, path, listed);
269
+ if (nested !== null && !chosen.includes(path))
270
+ notes.push(`note: ${path} ${nestedReason(nested).replace(/^it /, '')}`);
271
+ }
272
+ return notes;
273
+ }
274
+ // A type whose paths reach into a submodule or a repository of its own judges none of its files, and saying so is the one sign of it (stress finding S1-9).
275
+ function unseenRepositories(root, listed, law) {
276
+ const plain = law.types.flatMap((type) => type.paths.filter((pattern) => !pattern.startsWith('!'))).map(compilePattern);
277
+ const reached = nestedRepositories(root, listed).filter(({ dir }) => plain.some((pattern) => pattern.reaches(`${dir}/`)));
278
+ if (reached.length === 0)
279
+ return null;
280
+ const named = reached.slice(0, 3).map(({ dir, submodule }) => `${dir} (${submodule ? 'a submodule' : 'a repository of its own'})`);
281
+ const more = reached.length > 3 ? ` and ${reached.length - 3} more` : '';
282
+ return `note: the paths of a type reach into ${named.join(', ')}${more}; Lawcheck does not look into another repository, so no file there is judged`;
283
+ }
284
+ // What the reviews of this tree need of a full verdicts file, worked out with no call: its passes, those the files of the tree need, and the calls a review of every file of the law would take.
285
+ function verdictRoom(root, law, typed, kinds) {
286
+ const needed = new Set();
287
+ const ruleIds = new Set([...law.rules.keys(), 'forbidden-use']);
288
+ for (const file of typed) {
289
+ let waivers = null;
290
+ for (const rule of file.rules) {
291
+ const reviewer = kinds.reviewers.get(rule);
292
+ if (reviewer === undefined)
293
+ continue;
294
+ waivers ??= takesWaivers(file.type) ? parseWaivers(file.lines, ruleIds).waivers : [];
295
+ const why = law.rules.get(rule).why;
296
+ const waived = waivedLines(waivers, rule);
297
+ needed.add(`${reviewKey({ frame: FRAME, ruleId: rule, why, ruleText: reviewer.text, context: reviewer.context, filePath: file.path, fileText: file.text, waived })} ${rule}`);
298
+ }
299
+ }
300
+ const counted = countPasses(root, needed);
301
+ return `of its ${count(counted.held)} ${counted.held === 1 ? 'pass' : 'passes'} the files of this tree need ${count(counted.needed)}, and a review of every file of this law would take ${plural(needed.size, 'reviewer call')}`;
302
+ }
303
+ export function tooManyFindings(budget) {
304
+ const all = `the rules of a run may return ${count(RUN_FINDINGS)} findings with ${count(RUN_MESSAGE_CHARS)} characters of message in all, and they returned ${count(budget.total)} with ${count(budget.chars)}`;
305
+ const items = [];
306
+ for (const [rule, own] of budget.byRule) {
307
+ if (own.count === 0)
308
+ continue;
309
+ items.push({ code: 'too-many-findings', file: `${RULES_DIR}${rule}.mjs`, line: null, message: `returns ${count(own.count)} findings with ${count(own.chars)} characters of message in this run; ${all}` });
310
+ }
311
+ return items;
312
+ }
313
+ function tooManyAt(path, budget) {
314
+ return {
315
+ code: 'too-many-findings',
316
+ file: path,
317
+ line: null,
318
+ message: `brings the findings of this run to ${count(budget.total)} with ${count(budget.chars)} characters of message, more than the ${count(RUN_FINDINGS)} findings with ${count(RUN_MESSAGE_CHARS)} characters one run may hold`,
319
+ next: `narrow the types whose files bring so many findings, then run lawcheck check`,
320
+ };
321
+ }
322
+ async function readTheUses(root, files, read, typed, run, changed) {
323
+ const out = { forbidden: [], notRead: [], unresolved: [], tooLarge: [] };
324
+ const siblings = siblingsOf(files);
325
+ const toRead = [];
326
+ const unread = [];
327
+ for (const file of run) {
328
+ if (listInForce(file.type) === null)
329
+ continue;
330
+ const reader = readerOf(file.path, file.text, siblings);
331
+ if (reader.reader)
332
+ toRead.push({ path: file.path, view: reader.view });
333
+ else
334
+ unread.push({ path: file.path, type: file.type, debt: !changed.has(file.path) });
335
+ }
336
+ out.notRead = notRead(unread);
337
+ if (toRead.length === 0)
338
+ return out;
339
+ const known = new Set(files);
340
+ const typedByPath = new Map(typed.map((file) => [file.path, file]));
341
+ const bytes = (path) => {
342
+ try {
343
+ return read(path);
344
+ }
345
+ catch (error) {
346
+ throw new Unreadable(path, readError(path, error));
347
+ }
348
+ };
349
+ const ownerOf = (path) => {
350
+ const file = typedByPath.get(path);
351
+ if (file !== undefined)
352
+ return file.type.id;
353
+ if (!known.has(path))
354
+ return undefined;
355
+ return isBinary(bytes(path)) ? '#binary' : '#untyped';
356
+ };
357
+ const outcome = await readUses({ root, files, bytes, ownerOf, read: toRead });
358
+ if ('error' in outcome)
359
+ return { errors: [outcome.error] };
360
+ for (const { path, bytes, uses } of outcome.skipped) {
361
+ const size = `the file holds ${count(bytes)} bytes, more than the ${mib(USES_FILE_BYTES)} a file whose uses are read may hold`;
362
+ const message = uses ? `its uses are not read: ${size}` : `the uses of it are not judged: it is read for what it declares, and ${size}`;
363
+ out.tooLarge.push({ file: path, message, type: typedByPath.get(path)?.type.id ?? '' });
364
+ }
365
+ const targetOf = (path) => {
366
+ const file = typedByPath.get(path);
367
+ if (file !== undefined)
368
+ return { kind: 'typed', type: file.type };
369
+ return ownerOf(path) === '#binary' ? { kind: 'binary' } : { kind: 'untyped' };
370
+ };
371
+ for (const file of run) {
372
+ const found = outcome.uses.get(file.path);
373
+ if (found === undefined)
374
+ continue;
375
+ const judged = judgeUses(file.path, file.type, found, targetOf);
376
+ for (const item of judged.forbidden)
377
+ out.forbidden.push(item);
378
+ const debt = !changed.has(file.path);
379
+ for (const item of judged.unresolved)
380
+ out.unresolved.push({ ...item, debt });
381
+ }
382
+ out.unresolved.sort((a, b) => comparePaths(a.file, b.file) || a.line - b.line || comparePaths(a.what, b.what));
383
+ return out;
384
+ }
385
+ function nextOf(report, config, cap, review) {
386
+ const blocking = report.findings.filter((f) => f.severity === 'error');
387
+ if (blocking.length === 0)
388
+ return null;
389
+ const other = blocking.find((f) => f.code !== 'not-reviewed');
390
+ if (other !== undefined)
391
+ return { command: null, text: fixNext(other) };
392
+ const count = report.findings.filter((f) => f.code === 'not-reviewed').length;
393
+ if (config.provider === null) {
394
+ return { command: null, text: `ask the user to set reviewer.provider and reviewer.model in .lawcheck/config.yaml, then run ${review}` };
395
+ }
396
+ if (count > cap) {
397
+ return { command: null, text: `${count} reviewer calls are needed and reviewer.max_calls is ${cap}; raising the limit is the user's decision` };
398
+ }
399
+ return { command: review, text: `${review} (${plural(count, 'reviewer call')})` };
400
+ }
401
+ function judge(law, run, raw, builtIn, uses, waiversOf, reviewers, changed, base, mode) {
402
+ const byPath = new Map(run.map((file) => [file.path, file]));
403
+ const change = [];
404
+ const debt = [];
405
+ const place = (finding) => (finding.debt ? debt : change).push(finding);
406
+ for (const item of raw) {
407
+ const file = byPath.get(item.file);
408
+ if (item.line !== undefined && waive(waiversOf.get(item.file).waivers, item.rule, item.line))
409
+ continue;
410
+ const rule = law.rules.get(item.rule);
411
+ const isDebt = !changed.has(item.file);
412
+ const severity = !isDebt && rule.status === 'enforced' ? 'error' : 'warning';
413
+ const finding = { code: rule.id, rule: rule.id, severity, debt: isDebt, file: item.file, type: file.type.id, message: item.message, why: rule.why };
414
+ if (item.line !== undefined)
415
+ finding.line = item.line;
416
+ place(finding);
417
+ }
418
+ for (const item of builtIn) {
419
+ const rule = law.rules.get(item.rule);
420
+ const isDebt = !changed.has(item.file);
421
+ const severity = !isDebt && rule.status === 'enforced' && mode !== 'paths' ? 'error' : 'warning';
422
+ place({ code: item.code, rule: rule.id, severity, debt: isDebt, file: item.file, type: byPath.get(item.file).type.id, message: item.message, why: WHY[item.code] });
423
+ }
424
+ for (const item of uses.forbidden) {
425
+ if (waive(waiversOf.get(item.file).waivers, 'forbidden-use', item.line))
426
+ continue;
427
+ const isDebt = !changed.has(item.file);
428
+ place({
429
+ code: 'forbidden-use',
430
+ rule: null,
431
+ severity: isDebt ? 'warning' : 'error',
432
+ debt: isDebt,
433
+ file: item.file,
434
+ line: item.line,
435
+ type: byPath.get(item.file).type.id,
436
+ message: item.message,
437
+ why: WHY['forbidden-use'],
438
+ });
439
+ }
440
+ for (const item of uses.tooLarge) {
441
+ const isDebt = !changed.has(item.file);
442
+ if (isDebt && mode !== 'full')
443
+ continue;
444
+ place({ code: 'uses-not-read', rule: null, severity: isDebt ? 'warning' : 'error', debt: isDebt, file: item.file, type: item.type, message: item.message, why: WHY['uses-not-read'] });
445
+ }
446
+ for (const item of uses.notRead) {
447
+ place({ code: 'uses-not-read', rule: null, severity: 'warning', debt: item.debt, file: LAW, line: item.type.line, type: item.type.id, message: item.message, why: WHY['uses-not-read'] });
448
+ }
449
+ const waivers = [];
450
+ for (const file of run) {
451
+ const isDebt = !changed.has(file.path);
452
+ const { waivers: valid, problems } = waiversOf.get(file.path);
453
+ for (const problem of problems) {
454
+ place({ code: problem.code, rule: null, severity: isDebt ? 'warning' : 'error', debt: isDebt, file: file.path, line: problem.line, type: file.type.id, message: problem.message, why: WHY[problem.code] });
455
+ }
456
+ for (const waiver of valid) {
457
+ waivers.push({ file: file.path, line: waiver.line, rule: waiver.rule, debt: isDebt, waived: waiver.waived, reason: waiver.reason });
458
+ if (waiver.waived === 0 && !reviewers.has(waiver.rule)) {
459
+ place({ code: 'waiver-unused', rule: null, severity: 'warning', debt: isDebt, file: file.path, line: waiver.line, type: file.type.id, message: `the waiver of '${waiver.rule}' drops no finding`, why: WHY['waiver-unused'] });
460
+ }
461
+ }
462
+ }
463
+ return {
464
+ mode,
465
+ base,
466
+ changed: changed.size,
467
+ findings: sortFindings(change),
468
+ debt: sortFindings(debt),
469
+ waivers,
470
+ unresolved: uses.unresolved,
471
+ };
472
+ }
package/dist/cli.js ADDED
@@ -0,0 +1,182 @@
1
+ #!/usr/bin/env node
2
+ import { realpathSync } from 'node:fs';
3
+ import { spawn } from 'node:child_process';
4
+ import { dirname, join } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { isMainThread, MessageChannel, Worker } from 'node:worker_threads';
7
+ const GIT_OUTPUT_BYTES = 1 << 30;
8
+ import { COMMANDS } from './args.js';
9
+ import { hiddenJson, hide, useKeys } from './keys.js';
10
+ import { totalmem } from 'node:os';
11
+ import { availableNow, MEMORY_CHECK_MS, MEMORY_RESERVE_BYTES, memoryCase, mib, runBound, STEP_MEMORY_BYTES, STEP_MS } from './limits.js';
12
+ import { renderErrors, safeJson, safeText } from './output.js';
13
+ import { lastStep, progressBuffer } from './progress.js';
14
+ import { absolutePath, NO_CURRENT_FOLDER } from './programs.js';
15
+ // Each case names a step the user can take: a file whose uses are read leaves the types with may_use; a file read only for what it declares leaves the files git lists; a run or a machine short of memory gets more of it.
16
+ function memoryError(found, what, file, command) {
17
+ const again = `then run lawcheck ${command} again`;
18
+ if (found === 'file' && file !== null && what.startsWith('reading what')) {
19
+ return { code: 'memory-too-large', file, line: null, message: `the run grew by more than the ${mib(STEP_MEMORY_BYTES)} of memory one file may add while ${what}`, next: `keep ${file} out of the files git lists here (git rm --cached, and a line in .gitignore), since Lawcheck reads it for what it declares, ${again}` };
20
+ }
21
+ if (found === 'file' && file !== null) {
22
+ return { code: 'memory-too-large', file, line: null, message: `the run grew by more than the ${mib(STEP_MEMORY_BYTES)} of memory one file may add while ${what}`, next: `leave ${file} out of the types whose may_use is in force, ${again}` };
23
+ }
24
+ if (found === 'run') {
25
+ return { code: 'memory-too-large', file: null, line: null, message: `the run passed the ${mib(runBound(totalmem()))} of memory it may hold while ${what}`, next: `narrow the types whose may_use is in force in .lawcheck/law.yaml, or run Lawcheck where it may hold more memory, ${again}` };
26
+ }
27
+ return { code: 'memory-too-large', file: null, line: null, message: `the system had less than ${mib(MEMORY_RESERVE_BYTES)} of memory left while ${what}`, next: `free memory on this machine, or run Lawcheck where it has more, ${again}` };
28
+ }
29
+ function internal(error) {
30
+ const text = error instanceof Error ? error.message : String(error);
31
+ return { code: 'internal', file: null, line: null, message: text.split(/\r?\n/)[0] || 'an unknown failure' };
32
+ }
33
+ // macOS reports a write to a pipe whose reader closed as ENOTCONN, as well as EPIPE.
34
+ export function readerGone(error) {
35
+ const code = error?.code;
36
+ return code === 'EPIPE' || code === 'ENOTCONN';
37
+ }
38
+ // The command runs in a worker, so a signal is answered while the command is busy in code that never yields, such as a regular expression.
39
+ export function start() {
40
+ absolutePath(process.env);
41
+ if (process.platform === 'win32')
42
+ process.env[NO_CURRENT_FOLDER] = '1';
43
+ useKeys(process.env);
44
+ const argv = process.argv.slice(2);
45
+ const json = argv.includes('--json');
46
+ const named = COMMANDS.includes(argv[0] ?? '') ? argv[0] : null;
47
+ let writing = false;
48
+ const gits = new Set();
49
+ const gitFlag = new Int32Array(new SharedArrayBuffer(4));
50
+ const exit = (code) => {
51
+ for (const child of gits)
52
+ child.kill('SIGKILL');
53
+ process.exit(code);
54
+ };
55
+ const writeOut = (bytes, code) => {
56
+ writing = true;
57
+ process.stdout.on('error', () => undefined);
58
+ process.stdout.write(bytes, (error) => {
59
+ if (!error || readerGone(error))
60
+ return exit(code);
61
+ const cause = error.code ?? 'an error';
62
+ process.stderr.write(`error[file-unwritable] standard output cannot be written (${cause}), so the result is lost\n`, () => exit(2));
63
+ });
64
+ };
65
+ const fail = (item) => {
66
+ if (writing) {
67
+ process.stderr.write(safeText(`error[${item.code}] ${hide(item.message)}\n`), () => exit(2));
68
+ return;
69
+ }
70
+ const text = renderErrors([item], json, named);
71
+ writeOut(json ? safeJson(hiddenJson(text)) : safeText(text), 2);
72
+ };
73
+ for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
74
+ process.on(signal, () => fail({ code: 'stopped', file: null, line: null, message: `stopped by ${signal}` }));
75
+ }
76
+ const progress = progressBuffer();
77
+ const { port1, port2 } = new MessageChannel();
78
+ port1.on('message', (request) => {
79
+ const reply = (message, transfer = []) => {
80
+ port1.postMessage(message, transfer);
81
+ Atomics.store(gitFlag, 0, 1);
82
+ Atomics.notify(gitFlag, 0);
83
+ };
84
+ const child = spawn(request.program, request.args, { cwd: request.root, env: request.env, stdio: [request.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
85
+ gits.add(child);
86
+ if (request.input !== undefined) {
87
+ // A git that ends before it reads all its input closes the pipe; its status says why.
88
+ child.stdin.on('error', () => { });
89
+ child.stdin.end(request.input);
90
+ }
91
+ const out = [];
92
+ const err = [];
93
+ let size = 0;
94
+ let failed = null;
95
+ const collect = (into) => (chunk) => {
96
+ size += chunk.length;
97
+ if (size > GIT_OUTPUT_BYTES && failed === null) {
98
+ failed = { code: 'ENOBUFS', message: 'git printed more than 1 GiB' };
99
+ child.kill('SIGKILL');
100
+ }
101
+ if (failed === null)
102
+ into.push(chunk);
103
+ };
104
+ child.stdout.on('data', collect(out));
105
+ child.stderr.on('data', collect(err));
106
+ child.on('error', (error) => {
107
+ failed ??= { code: error.code ?? null, message: error.message };
108
+ });
109
+ child.on('close', (status, signal) => {
110
+ gits.delete(child);
111
+ const stdout = new Uint8Array(Buffer.concat(out));
112
+ const stderr = new Uint8Array(Buffer.concat(err));
113
+ reply({ error: failed, status, signal, stdout, stderr }, [stdout.buffer, stderr.buffer]);
114
+ });
115
+ });
116
+ port1.unref();
117
+ const worker = new Worker(new URL('./work.js', import.meta.url), {
118
+ workerData: { argv, cwd: process.cwd(), progress, git: port2, gitFlag: gitFlag.buffer },
119
+ transferList: [port2],
120
+ stdout: false,
121
+ stderr: false,
122
+ });
123
+ const watch = setInterval(() => {
124
+ const last = lastStep(progress);
125
+ if (writing || Date.now() - last.at <= STEP_MS)
126
+ return;
127
+ clearInterval(watch);
128
+ fail({ code: 'step-too-slow', file: null, line: null, message: `one step of the run took more than ${STEP_MS / 1000} seconds without an end: ${last.what}` });
129
+ }, 1000);
130
+ watch.unref();
131
+ // A reader of uses can grow by megabytes a millisecond and cannot be stopped from within, so the memory of the whole process is read from here, often, and the run ends before the system ends it.
132
+ const total = totalmem();
133
+ let stepAt = -1;
134
+ let stepRss = 0;
135
+ const memory = setInterval(() => {
136
+ if (writing)
137
+ return;
138
+ const rss = process.memoryUsage.rss();
139
+ const last = lastStep(progress);
140
+ if (last.at !== stepAt) {
141
+ stepAt = last.at;
142
+ stepRss = rss;
143
+ }
144
+ const found = memoryCase({ rss, stepGrowth: last.file === null ? null : rss - stepRss, available: availableNow(), total });
145
+ if (found === null)
146
+ return;
147
+ clearInterval(memory);
148
+ fail(memoryError(found, last.what, last.file, named ?? 'check'));
149
+ }, MEMORY_CHECK_MS);
150
+ memory.unref();
151
+ worker.on('message', (message) => {
152
+ if (message.kind === 'warn')
153
+ process.stderr.write(safeText(message.line) + '\n');
154
+ else if (message.kind === 'stderr')
155
+ process.stderr.write(message.text);
156
+ else
157
+ writeOut(message.stdout, message.code);
158
+ });
159
+ worker.on('error', (error) => fail(internal(error)));
160
+ worker.on('exit', () => {
161
+ if (!writing)
162
+ fail(internal(new Error('the command ended without a result')));
163
+ });
164
+ }
165
+ function started() {
166
+ try {
167
+ return process.argv[1] === undefined ? null : realpathSync(process.argv[1]);
168
+ }
169
+ catch {
170
+ return null;
171
+ }
172
+ }
173
+ // The command and its modules load in the worker alone, so the handlers of the signals are in place before them; started as dist/cli.js or through dist/bin.cjs, this module loads no more, and a test that imports the command loads it here.
174
+ const here = fileURLToPath(import.meta.url);
175
+ const first = started();
176
+ const launched = isMainThread && (first === here || first === join(dirname(here), 'bin.cjs'));
177
+ if (launched && first === here)
178
+ start();
179
+ const command = launched ? null : await import('./main.js');
180
+ export const main = command?.main;
181
+ export const parseArguments = command?.parseArguments;
182
+ export const version = command?.version;