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.
- package/README.md +34 -2
- package/dist/args.js +168 -0
- package/dist/bin.cjs +20 -0
- package/dist/check.js +472 -0
- package/dist/cli.js +182 -0
- package/dist/config.js +278 -0
- package/dist/docs.js +41 -0
- package/dist/doctor.js +273 -0
- package/dist/environment.js +73 -0
- package/dist/explain.js +446 -0
- package/dist/files.js +388 -0
- package/dist/glob.js +268 -0
- package/dist/grammars/LICENSES.txt +353 -0
- package/dist/grammars/tree-sitter-c.wasm +0 -0
- package/dist/grammars/tree-sitter-c_sharp.wasm +0 -0
- package/dist/grammars/tree-sitter-cpp.wasm +0 -0
- package/dist/grammars/tree-sitter-go.wasm +0 -0
- package/dist/grammars/tree-sitter-java.wasm +0 -0
- package/dist/grammars/tree-sitter-javascript.wasm +0 -0
- package/dist/grammars/tree-sitter-kotlin.wasm +0 -0
- package/dist/grammars/tree-sitter-php.wasm +0 -0
- package/dist/grammars/tree-sitter-python.wasm +0 -0
- package/dist/grammars/tree-sitter-ruby.wasm +0 -0
- package/dist/grammars/tree-sitter-rust.wasm +0 -0
- package/dist/grammars/tree-sitter-tsx.wasm +0 -0
- package/dist/grammars/tree-sitter-typescript.wasm +0 -0
- package/dist/guard.js +179 -0
- package/dist/init.js +131 -0
- package/dist/keys.js +55 -0
- package/dist/law.js +416 -0
- package/dist/lawchange.js +208 -0
- package/dist/limits.js +207 -0
- package/dist/main.js +77 -0
- package/dist/names.js +117 -0
- package/dist/output.js +325 -0
- package/dist/prime.js +211 -0
- package/dist/programs.js +177 -0
- package/dist/progress.js +42 -0
- package/dist/prompt.js +317 -0
- package/dist/providers/anthropic.js +33 -0
- package/dist/providers/claude-code.js +41 -0
- package/dist/providers/codex.js +75 -0
- package/dist/providers/copilot-cli.js +56 -0
- package/dist/providers/gemini-cli.js +30 -0
- package/dist/providers/google.js +31 -0
- package/dist/providers/http.js +138 -0
- package/dist/providers/index.js +96 -0
- package/dist/providers/ollama.js +39 -0
- package/dist/providers/openai-compatible.js +41 -0
- package/dist/providers/openai.js +17 -0
- package/dist/providers/program.js +282 -0
- package/dist/readers.js +286 -0
- package/dist/review.js +116 -0
- package/dist/rules.js +418 -0
- package/dist/runner.js +177 -0
- package/dist/setup.js +388 -0
- package/dist/try.js +346 -0
- package/dist/types.js +99 -0
- package/dist/uses.js +78 -0
- package/dist/verdicts.js +337 -0
- package/dist/waivers.js +70 -0
- package/dist/work.js +21 -0
- package/docs/change.md +62 -0
- package/docs/ci.md +133 -0
- package/docs/codes.md +60 -0
- package/docs/config.md +117 -0
- package/docs/first-law.md +189 -0
- package/docs/json.md +72 -0
- package/docs/languages.md +87 -0
- package/docs/law.md +95 -0
- package/docs/providers.md +105 -0
- package/docs/reviewer-rules.md +96 -0
- package/docs/script-rules.md +90 -0
- package/docs/waivers.md +56 -0
- package/package.json +59 -3
package/dist/explain.js
ADDED
|
@@ -0,0 +1,446 @@
|
|
|
1
|
+
import { lstatSync } from 'node:fs';
|
|
2
|
+
import { bytesOfName, onDisk } from './names.js';
|
|
3
|
+
import { documentOf, errorResult, text as flagText, usageError } from './args.js';
|
|
4
|
+
import { ignoresPath, nestedReason, repositoryHolding } from './files.js';
|
|
5
|
+
import { compilePattern } from './glob.js';
|
|
6
|
+
import { takesWaivers } from './law.js';
|
|
7
|
+
import { plural, shown } from './output.js';
|
|
8
|
+
import { readError } from './limits.js';
|
|
9
|
+
import { step } from './progress.js';
|
|
10
|
+
import { mayUsePart, ruleKind, walk } from './prime.js';
|
|
11
|
+
import { buildPrompt, FRAME, size } from './prompt.js';
|
|
12
|
+
import { readerOf, siblingsOf } from './readers.js';
|
|
13
|
+
import { loadConfig, loadLaw, loadRuleFiles, locate, fromCwd, nearPart, requireGit, RULES_DIR, stopped, typeAll, typingErrors, Stop, usage, WRITTEN } from './setup.js';
|
|
14
|
+
import { decode, filesOfTypes, isBinary, splitLines } from './types.js';
|
|
15
|
+
import { listInForce } from './uses.js';
|
|
16
|
+
import { readFailure, readVerdicts, reviewKey } from './verdicts.js';
|
|
17
|
+
import { parseWaivers, waivedLines } from './waivers.js';
|
|
18
|
+
const REVIEW_TEXT = {
|
|
19
|
+
reviewed: 'reviewed',
|
|
20
|
+
failed: 'failed earlier',
|
|
21
|
+
'too-large': 'too large to review',
|
|
22
|
+
'not-reviewed': 'not reviewed',
|
|
23
|
+
};
|
|
24
|
+
const NO_LIST = 'any file; no type on the way up has may_use';
|
|
25
|
+
const LIMIT = 50;
|
|
26
|
+
export function names(ids) {
|
|
27
|
+
return ids.length <= 1 ? (ids[0] ?? '') : `${ids.slice(0, -1).join(', ')} and ${ids[ids.length - 1]}`;
|
|
28
|
+
}
|
|
29
|
+
function untyped(path, exists, none, then = null) {
|
|
30
|
+
return { path, exists, type: null, chain: [], none, matched: [], notMatched: [], then, uses: null, rules: [], waivers: [] };
|
|
31
|
+
}
|
|
32
|
+
function firstPlain(type, path) {
|
|
33
|
+
return type.paths.find((pattern) => !pattern.startsWith('!') && compilePattern(pattern).test(path)) ?? type.paths[0];
|
|
34
|
+
}
|
|
35
|
+
function chainOf(type) {
|
|
36
|
+
const chain = [];
|
|
37
|
+
for (let at = type; at !== null; at = at.parent)
|
|
38
|
+
chain.unshift(at);
|
|
39
|
+
return chain;
|
|
40
|
+
}
|
|
41
|
+
function rulesOf(ctx, chain, review) {
|
|
42
|
+
const out = [];
|
|
43
|
+
for (const type of chain) {
|
|
44
|
+
for (const id of type.rules) {
|
|
45
|
+
if (out.some((item) => item.id === id))
|
|
46
|
+
continue;
|
|
47
|
+
const rule = ctx.law.rules.get(id);
|
|
48
|
+
const kind = ruleKind(ctx.kinds, id);
|
|
49
|
+
out.push({ id, kind, status: rule.status, why: rule.why, from: type.id, review: kind === 'reviewer' && review !== null ? review(id) : null });
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
return out;
|
|
53
|
+
}
|
|
54
|
+
function usesOf(ctx, type, path, text) {
|
|
55
|
+
if (listInForce(type) === null)
|
|
56
|
+
return null;
|
|
57
|
+
const reader = readerOf(path, text, siblingsOf(ctx.files));
|
|
58
|
+
if (!reader.reader)
|
|
59
|
+
return { read: false, language: null };
|
|
60
|
+
const dot = path.lastIndexOf('.');
|
|
61
|
+
return { read: true, language: reader.view?.language ?? path.slice(dot + 1) };
|
|
62
|
+
}
|
|
63
|
+
function reviewState(ctx, path, text, waivers) {
|
|
64
|
+
const verdicts = readVerdicts(ctx.root);
|
|
65
|
+
const lineCount = splitLines(text).length;
|
|
66
|
+
return (id) => {
|
|
67
|
+
const reviewer = ctx.kinds.reviewers.get(id);
|
|
68
|
+
const why = ctx.law.rules.get(id).why;
|
|
69
|
+
const waived = waivedLines(waivers, id);
|
|
70
|
+
const key = reviewKey({ frame: FRAME, ruleId: id, why, ruleText: reviewer.text, context: reviewer.context, filePath: path, fileText: text, waived });
|
|
71
|
+
if (verdicts.has(`${key} ${id}`))
|
|
72
|
+
return 'reviewed';
|
|
73
|
+
if (readFailure(ctx.root, key, id, lineCount) !== null)
|
|
74
|
+
return 'failed';
|
|
75
|
+
const prompt = buildPrompt({ why, ruleText: reviewer.text, context: reviewer.context, filePath: path, fileText: text, waived });
|
|
76
|
+
return size(prompt) > ctx.config.maxChars ? 'too-large' : 'not-reviewed';
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
const BEHIND = 'it lies behind a symbolic link, which has no type';
|
|
80
|
+
function behindLink(root, path) {
|
|
81
|
+
const parts = path.split('/');
|
|
82
|
+
for (let i = 1; i < parts.length; i++) {
|
|
83
|
+
try {
|
|
84
|
+
if (lstatSync(onDisk(root, parts.slice(0, i).join('/'))).isSymbolicLink())
|
|
85
|
+
return true;
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
function existing(ctx, path, symlink) {
|
|
94
|
+
if (behindLink(ctx.root, path))
|
|
95
|
+
return untyped(path, true, BEHIND);
|
|
96
|
+
const nested = repositoryHolding(ctx.root, path, ctx.listed);
|
|
97
|
+
if (nested !== null)
|
|
98
|
+
return untyped(path, true, nestedReason(nested));
|
|
99
|
+
if (!ctx.listed.has(path))
|
|
100
|
+
return untyped(path, true, 'git ignores it, so Lawcheck never sees it');
|
|
101
|
+
if (symlink)
|
|
102
|
+
return untyped(path, true, 'it is a symbolic link, which has no type');
|
|
103
|
+
if (WRITTEN.has(path))
|
|
104
|
+
return untyped(path, true, 'Lawcheck writes this file, and it has no type');
|
|
105
|
+
if (!ctx.law.types.some((type) => type.matches(path)))
|
|
106
|
+
return untyped(path, true, "no type's paths match it, so no rule judges it");
|
|
107
|
+
step(`typing ${path}`);
|
|
108
|
+
let bytes;
|
|
109
|
+
try {
|
|
110
|
+
bytes = ctx.read(path);
|
|
111
|
+
}
|
|
112
|
+
catch (error) {
|
|
113
|
+
throw new Stop([readError(path, error)]);
|
|
114
|
+
}
|
|
115
|
+
if (isBinary(bytes))
|
|
116
|
+
return untyped(path, true, 'it is binary, which has no type');
|
|
117
|
+
const text = decode(bytes);
|
|
118
|
+
const chain = [];
|
|
119
|
+
let notMatched = [];
|
|
120
|
+
let level = ctx.law.types;
|
|
121
|
+
for (;;) {
|
|
122
|
+
const byPath = level.filter((type) => type.matches(path));
|
|
123
|
+
const hits = byPath.filter((type) => type.content === null || type.content.test(text));
|
|
124
|
+
if (hits.length > 1) {
|
|
125
|
+
return untyped(path, true, `it matches ${names(hits.map((t) => t.id))} at one level (type-overlap); check stops with exit 2 until a ! pattern in one of them leaves it out`);
|
|
126
|
+
}
|
|
127
|
+
if (hits.length === 0) {
|
|
128
|
+
if (chain.length === 0)
|
|
129
|
+
return untyped(path, true, `it matches the paths of ${names(byPath.map((t) => t.id))} but not their content, so no rule judges it`);
|
|
130
|
+
notMatched = byPath;
|
|
131
|
+
break;
|
|
132
|
+
}
|
|
133
|
+
chain.push(hits[0]);
|
|
134
|
+
level = hits[0].types;
|
|
135
|
+
}
|
|
136
|
+
const type = chain[chain.length - 1];
|
|
137
|
+
const ruleIds = new Set([...ctx.law.rules.keys(), 'forbidden-use']);
|
|
138
|
+
const { waivers } = takesWaivers(type) ? parseWaivers(splitLines(text), ruleIds) : { waivers: [] };
|
|
139
|
+
return {
|
|
140
|
+
path,
|
|
141
|
+
exists: true,
|
|
142
|
+
type,
|
|
143
|
+
chain,
|
|
144
|
+
none: null,
|
|
145
|
+
matched: chain.map((t) => ({ type: t.id, pattern: firstPlain(t, path), content: t.expression })),
|
|
146
|
+
notMatched: notMatched.map((t) => ({ type: t.id, content: t.expression })),
|
|
147
|
+
then: null,
|
|
148
|
+
uses: usesOf(ctx, type, path, text),
|
|
149
|
+
rules: rulesOf(ctx, chain, reviewState(ctx, path, text, waivers)),
|
|
150
|
+
waivers: waivers.map((w) => ({ line: w.line, rule: w.rule, reason: w.reason })),
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
export function alternatives(hits, deepest) {
|
|
154
|
+
const plain = hits.filter((type) => type.content === null);
|
|
155
|
+
const withContent = hits.filter((type) => type.content !== null);
|
|
156
|
+
if (plain.length >= 2)
|
|
157
|
+
return { then: `any file here matches ${names(plain.map((t) => t.id))} at one level (type-overlap)`, overlap: true };
|
|
158
|
+
if (plain.length === 1) {
|
|
159
|
+
const only = plain[0].id;
|
|
160
|
+
const parts = withContent.map((t) => `a type-overlap of ${only} and ${t.id} if its text matches "${t.expression}"`);
|
|
161
|
+
return { then: `${parts.join('; ')}; otherwise ${only}`, overlap: false };
|
|
162
|
+
}
|
|
163
|
+
const parts = withContent.map((t) => `${t.id} if its text matches "${t.expression}"`);
|
|
164
|
+
return { then: `${parts.join('; ')}; otherwise ${deepest?.id ?? 'none'}`, overlap: false };
|
|
165
|
+
}
|
|
166
|
+
export function walkPath(types, path) {
|
|
167
|
+
const chain = [];
|
|
168
|
+
let level = types;
|
|
169
|
+
for (;;) {
|
|
170
|
+
const hits = level.filter((type) => type.matches(path));
|
|
171
|
+
if (hits.length === 1 && hits[0].content === null) {
|
|
172
|
+
chain.push(hits[0]);
|
|
173
|
+
level = hits[0].types;
|
|
174
|
+
continue;
|
|
175
|
+
}
|
|
176
|
+
return { chain, stop: hits };
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
function absent(ctx, path) {
|
|
180
|
+
if (behindLink(ctx.root, path))
|
|
181
|
+
return untyped(path, false, BEHIND);
|
|
182
|
+
const nested = repositoryHolding(ctx.root, path, ctx.listed);
|
|
183
|
+
if (nested !== null)
|
|
184
|
+
return untyped(path, false, nestedReason(nested));
|
|
185
|
+
if (ignoresPath(ctx.root, path))
|
|
186
|
+
return untyped(path, false, 'git ignores this path, so Lawcheck would never see it');
|
|
187
|
+
const { chain, stop } = walkPath(ctx.law.types, path);
|
|
188
|
+
const deepest = chain[chain.length - 1] ?? null;
|
|
189
|
+
if (deepest === null) {
|
|
190
|
+
if (stop.length === 0)
|
|
191
|
+
return untyped(path, false, "no type's paths match it, so no rule judges it");
|
|
192
|
+
const { then, overlap } = alternatives(stop, null);
|
|
193
|
+
return overlap ? untyped(path, false, then) : untyped(path, false, null, then);
|
|
194
|
+
}
|
|
195
|
+
return {
|
|
196
|
+
path,
|
|
197
|
+
exists: false,
|
|
198
|
+
type: deepest,
|
|
199
|
+
chain,
|
|
200
|
+
none: null,
|
|
201
|
+
matched: chain.map((t) => ({ type: t.id, pattern: firstPlain(t, path), content: t.expression })),
|
|
202
|
+
notMatched: [],
|
|
203
|
+
then: stop.length === 0 ? null : alternatives(stop, deepest).then,
|
|
204
|
+
uses: usesOf(ctx, deepest, path, ''),
|
|
205
|
+
rules: rulesOf(ctx, chain, null),
|
|
206
|
+
waivers: [],
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
function mayUseLine(type) {
|
|
210
|
+
return ` may use: ${mayUsePart(type, ' ') ?? NO_LIST}`;
|
|
211
|
+
}
|
|
212
|
+
function mayUseJson(type) {
|
|
213
|
+
if (type === null)
|
|
214
|
+
return null;
|
|
215
|
+
const inForce = listInForce(type);
|
|
216
|
+
if (inForce === null)
|
|
217
|
+
return null;
|
|
218
|
+
return { types: inForce.list, from: inForce.from === type ? null : inForce.from.id };
|
|
219
|
+
}
|
|
220
|
+
function ruleLines(rules) {
|
|
221
|
+
if (rules.length === 0)
|
|
222
|
+
return [' rules: none'];
|
|
223
|
+
return [' rules:', ...rules.map((r) => ` ${r.id} ${r.kind} ${r.status} from ${r.from}${r.review === null ? '' : ` ${REVIEW_TEXT[r.review]}`} ${r.why}`)];
|
|
224
|
+
}
|
|
225
|
+
export function fileText(answer) {
|
|
226
|
+
const lines = [answer.exists ? shown(answer.path) : `${shown(answer.path)} (does not exist yet)`];
|
|
227
|
+
const type = answer.type;
|
|
228
|
+
if (type === null) {
|
|
229
|
+
lines.push(answer.none !== null ? ` type: none: ${answer.none}` : ` type: depends on its text: ${answer.then}`);
|
|
230
|
+
return lines.join('\n') + '\n';
|
|
231
|
+
}
|
|
232
|
+
lines.push(` type: ${type.id} (${answer.chain.map((t) => t.id).join(' > ')})${type.about === null ? '' : ` ${shown(type.about)}`}`);
|
|
233
|
+
const matched = answer.matched.map((m) => `${m.type} by "${shown(m.pattern)}"${m.content === null ? '' : ` and content "${shown(m.content)}"`}`);
|
|
234
|
+
const not = answer.notMatched.map((n) => `not ${n.type}: content "${shown(n.content)}" does not match`);
|
|
235
|
+
lines.push(` matched: ${[...matched, ...not].join(', ')}`);
|
|
236
|
+
if (answer.then !== null)
|
|
237
|
+
lines.push(` then: ${answer.then}`);
|
|
238
|
+
lines.push(mayUseLine(type));
|
|
239
|
+
if (answer.uses !== null)
|
|
240
|
+
lines.push(` uses: ${answer.uses.read ? `read as ${answer.uses.language}` : 'not read: Lawcheck has no reader for this file'}`);
|
|
241
|
+
lines.push(...ruleLines(answer.rules));
|
|
242
|
+
if (answer.exists) {
|
|
243
|
+
if (answer.waivers.length === 0)
|
|
244
|
+
lines.push(' waivers: none');
|
|
245
|
+
else
|
|
246
|
+
lines.push(' waivers:', ...answer.waivers.map((w) => ` ${shown(answer.path)}:${w.line} ${w.rule} ${shown(w.reason)}`));
|
|
247
|
+
}
|
|
248
|
+
return lines.join('\n') + '\n';
|
|
249
|
+
}
|
|
250
|
+
function fileJson(answer) {
|
|
251
|
+
return {
|
|
252
|
+
schema: 'lawcheck-explain/0',
|
|
253
|
+
subject: 'file',
|
|
254
|
+
path: answer.path,
|
|
255
|
+
exists: answer.exists,
|
|
256
|
+
type: answer.type?.id ?? null,
|
|
257
|
+
chain: answer.chain.map((t) => t.id),
|
|
258
|
+
about: answer.type?.about ?? null,
|
|
259
|
+
none: answer.none,
|
|
260
|
+
matched: answer.matched,
|
|
261
|
+
not_matched: answer.notMatched,
|
|
262
|
+
then: answer.then,
|
|
263
|
+
may_use: mayUseJson(answer.type),
|
|
264
|
+
uses: answer.uses,
|
|
265
|
+
rules: answer.rules,
|
|
266
|
+
waivers: answer.waivers,
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
function list(lines, files) {
|
|
270
|
+
for (const file of files.slice(0, LIMIT))
|
|
271
|
+
lines.push(` ${file}`);
|
|
272
|
+
if (files.length > LIMIT)
|
|
273
|
+
lines.push(` ... ${files.length - LIMIT} more (--json lists all)`);
|
|
274
|
+
}
|
|
275
|
+
function directory(ctx, path, json) {
|
|
276
|
+
const below = path === '.' ? ctx.files : ctx.files.filter((file) => file.startsWith(`${path}/`));
|
|
277
|
+
const { typed, errors } = typingErrors(ctx.root, ctx.law, below, ctx.read);
|
|
278
|
+
if (errors.length > 0)
|
|
279
|
+
throw new Stop(errors);
|
|
280
|
+
const counts = new Map();
|
|
281
|
+
for (const file of typed)
|
|
282
|
+
counts.set(file.type.id, (counts.get(file.type.id) ?? 0) + 1);
|
|
283
|
+
const types = [];
|
|
284
|
+
walk(ctx.law.types, (type) => {
|
|
285
|
+
const count = counts.get(type.id);
|
|
286
|
+
if (count !== undefined)
|
|
287
|
+
types.push({ type: type.id, files: count });
|
|
288
|
+
});
|
|
289
|
+
if (below.length > typed.length)
|
|
290
|
+
types.push({ type: null, files: below.length - typed.length });
|
|
291
|
+
const label = path === '.' ? './' : `${path}/`;
|
|
292
|
+
if (json)
|
|
293
|
+
return documentOf({ schema: 'lawcheck-explain/0', subject: 'directory', path: label, files: below.length, types });
|
|
294
|
+
const lines = [`${shown(label)} ${plural(below.length, 'file')}`, ...types.map((t) => ` ${t.type ?? 'no type'} ${plural(t.files, 'file')}`)];
|
|
295
|
+
return lines.join('\n') + '\n';
|
|
296
|
+
}
|
|
297
|
+
function typeAnswer(ctx, id, json) {
|
|
298
|
+
const type = ctx.law.byId.get(id);
|
|
299
|
+
const typed = typeAll(ctx.root, ctx.law, ctx.files, ctx.read);
|
|
300
|
+
const files = filesOfTypes(typed, ctx.law).get(id) ?? [];
|
|
301
|
+
const chain = chainOf(type);
|
|
302
|
+
const rules = rulesOf(ctx, chain, null);
|
|
303
|
+
if (json) {
|
|
304
|
+
return documentOf({
|
|
305
|
+
schema: 'lawcheck-explain/0',
|
|
306
|
+
subject: 'type',
|
|
307
|
+
id,
|
|
308
|
+
chain: chain.map((t) => t.id),
|
|
309
|
+
about: type.about,
|
|
310
|
+
paths: type.paths,
|
|
311
|
+
content: type.expression,
|
|
312
|
+
may_use: mayUseJson(type),
|
|
313
|
+
rules: rules.map(({ review: _review, ...rest }) => rest),
|
|
314
|
+
subtypes: type.types.map((t) => t.id),
|
|
315
|
+
waivers: takesWaivers(type),
|
|
316
|
+
files,
|
|
317
|
+
});
|
|
318
|
+
}
|
|
319
|
+
const lines = [`type ${id} (${chain.map((t) => t.id).join(' > ')})${type.about === null ? '' : ` ${shown(type.about)}`}`, ` paths: ${shown(type.paths.join(', '))}`];
|
|
320
|
+
if (type.expression !== null)
|
|
321
|
+
lines.push(` content: ${shown(type.expression)}`);
|
|
322
|
+
lines.push(mayUseLine(type), ...ruleLines(rules));
|
|
323
|
+
if (!takesWaivers(type))
|
|
324
|
+
lines.push(' waivers: not read; a waiver marker in its files is text');
|
|
325
|
+
lines.push(` subtypes: ${type.types.length === 0 ? 'none' : type.types.map((t) => t.id).join(', ')}`);
|
|
326
|
+
lines.push(` files: ${files.length}`);
|
|
327
|
+
list(lines, files);
|
|
328
|
+
return lines.join('\n') + '\n';
|
|
329
|
+
}
|
|
330
|
+
function ruleAnswer(ctx, id, json) {
|
|
331
|
+
const rule = ctx.law.rules.get(id);
|
|
332
|
+
const kind = ruleKind(ctx.kinds, id);
|
|
333
|
+
const typed = typeAll(ctx.root, ctx.law, ctx.files, ctx.read);
|
|
334
|
+
const onTypes = [];
|
|
335
|
+
walk(ctx.law.types, (type) => {
|
|
336
|
+
if (type.rules.includes(id))
|
|
337
|
+
onTypes.push(type.id);
|
|
338
|
+
});
|
|
339
|
+
const bound = typed.filter((file) => file.rules.includes(id));
|
|
340
|
+
const files = bound.map((file) => file.path);
|
|
341
|
+
let reviewed = null;
|
|
342
|
+
if (kind === 'reviewer') {
|
|
343
|
+
const verdicts = readVerdicts(ctx.root);
|
|
344
|
+
const reviewer = ctx.kinds.reviewers.get(id);
|
|
345
|
+
const ruleIds = new Set([...ctx.law.rules.keys(), 'forbidden-use']);
|
|
346
|
+
reviewed = bound.filter((file) => {
|
|
347
|
+
const waived = waivedLines(takesWaivers(file.type) ? parseWaivers(file.lines, ruleIds).waivers : [], id);
|
|
348
|
+
return verdicts.has(`${reviewKey({ frame: FRAME, ruleId: id, why: rule.why, ruleText: reviewer.text, context: reviewer.context, filePath: file.path, fileText: file.text, waived })} ${id}`);
|
|
349
|
+
}).length;
|
|
350
|
+
}
|
|
351
|
+
const file = `${RULES_DIR}${id}.${kind === 'script' ? 'mjs' : 'md'}`;
|
|
352
|
+
const context = rule.context === null ? null : rule.context.map((item) => item.path);
|
|
353
|
+
if (json) {
|
|
354
|
+
return documentOf({ schema: 'lawcheck-explain/0', subject: 'rule', id, kind, status: rule.status, why: rule.why, file, context, types: onTypes, files, reviewed });
|
|
355
|
+
}
|
|
356
|
+
const lines = [`rule ${id} ${kind} ${rule.status}`, ` why: ${rule.why}`, ` file: ${file}`];
|
|
357
|
+
if (context !== null)
|
|
358
|
+
lines.push(` context: ${context.join(', ')}`);
|
|
359
|
+
if (onTypes.length === 0) {
|
|
360
|
+
lines.push(' on types: none; it judges no file until a type lists it', ' binds: 0 files');
|
|
361
|
+
return lines.join('\n') + '\n';
|
|
362
|
+
}
|
|
363
|
+
lines.push(` on types: ${onTypes.join(', ')}`);
|
|
364
|
+
const verdictPart = reviewed === null ? '' : `; ${reviewed} ${reviewed === 1 ? 'has' : 'have'} a verdict for their content`;
|
|
365
|
+
lines.push(` binds: ${plural(files.length, 'file')}${verdictPart}`);
|
|
366
|
+
list(lines, files);
|
|
367
|
+
return lines.join('\n') + '\n';
|
|
368
|
+
}
|
|
369
|
+
// A file system that ignores case finds SRC/core/price.ts at src/core/price.ts, which git lists under that spelling alone; the answer is about the file git lists.
|
|
370
|
+
function spelledAsListed(root, path, listed) {
|
|
371
|
+
if (listed.has(path))
|
|
372
|
+
return path;
|
|
373
|
+
let named;
|
|
374
|
+
try {
|
|
375
|
+
named = lstatSync(onDisk(root, path), { bigint: true });
|
|
376
|
+
}
|
|
377
|
+
catch {
|
|
378
|
+
return path;
|
|
379
|
+
}
|
|
380
|
+
const lower = path.toLowerCase();
|
|
381
|
+
const same = [...listed].filter((other) => {
|
|
382
|
+
if (other.toLowerCase() !== lower)
|
|
383
|
+
return false;
|
|
384
|
+
try {
|
|
385
|
+
const stat = lstatSync(onDisk(root, other), { bigint: true });
|
|
386
|
+
return stat.dev === named.dev && stat.ino === named.ino;
|
|
387
|
+
}
|
|
388
|
+
catch {
|
|
389
|
+
return false;
|
|
390
|
+
}
|
|
391
|
+
});
|
|
392
|
+
return same.length === 1 ? same[0] : path;
|
|
393
|
+
}
|
|
394
|
+
export async function explain(args, context, json) {
|
|
395
|
+
const typeId = flagText(args, '--type');
|
|
396
|
+
const ruleId = flagText(args, '--rule');
|
|
397
|
+
const given = args.words.length + (typeId === null ? 0 : 1) + (ruleId === null ? 0 : 1);
|
|
398
|
+
if (given !== 1)
|
|
399
|
+
return usageError('explain takes exactly one of a path, --type <id> and --rule <id>', json, 'explain');
|
|
400
|
+
const outcome = await stopped(() => {
|
|
401
|
+
const root = locate(context.cwd);
|
|
402
|
+
requireGit(root);
|
|
403
|
+
const law = loadLaw(root);
|
|
404
|
+
if (typeId !== null && !law.byId.has(typeId))
|
|
405
|
+
throw usage(`the law has no type '${typeId}'${nearPart(typeId, [...law.byId.keys()])}`);
|
|
406
|
+
if (ruleId !== null && !law.rules.has(ruleId))
|
|
407
|
+
throw usage(`the law has no rule '${ruleId}'${nearPart(ruleId, [...law.rules.keys()])}`);
|
|
408
|
+
const config = loadConfig(root);
|
|
409
|
+
const { listed, files, read, kinds } = loadRuleFiles(root, law);
|
|
410
|
+
const ctx = { root, law, config, listed, files, read, kinds };
|
|
411
|
+
if (typeId !== null)
|
|
412
|
+
return typeAnswer(ctx, typeId, json);
|
|
413
|
+
if (ruleId !== null)
|
|
414
|
+
return ruleAnswer(ctx, ruleId, json);
|
|
415
|
+
const given = fromCwd(root, context.cwd, args.words[0]);
|
|
416
|
+
// A name over 255 bytes or a path over 4,095 can exist on no system Lawcheck runs on, though Windows answers that such a file is missing. An escaped name is measured by the bytes it stands for.
|
|
417
|
+
if (given.split('/').some((part) => bytesOfName(part).length > 255) || Buffer.byteLength(onDisk(root, given)) > 4095) {
|
|
418
|
+
throw usage(`the path '${args.words[0]}' cannot exist here: it is longer than this system allows for a name or a path`);
|
|
419
|
+
}
|
|
420
|
+
const path = spelledAsListed(root, given, listed);
|
|
421
|
+
if (path === '.')
|
|
422
|
+
return directory(ctx, path, json);
|
|
423
|
+
let stat = null;
|
|
424
|
+
try {
|
|
425
|
+
stat = lstatSync(onDisk(root, path));
|
|
426
|
+
}
|
|
427
|
+
catch (error) {
|
|
428
|
+
const code = error.code;
|
|
429
|
+
if (code === 'ENAMETOOLONG')
|
|
430
|
+
throw usage(`the path '${args.words[0]}' cannot exist here: it is longer than this system allows for a name or a path`);
|
|
431
|
+
if (code !== 'ENOENT' && code !== 'ENOTDIR')
|
|
432
|
+
throw error;
|
|
433
|
+
}
|
|
434
|
+
if (stat !== null && stat.isDirectory())
|
|
435
|
+
return directory(ctx, path, json);
|
|
436
|
+
if (stat !== null && !stat.isFile() && !stat.isSymbolicLink()) {
|
|
437
|
+
const answer = untyped(path, true, 'it is no regular file, which has no type');
|
|
438
|
+
return json ? documentOf(fileJson(answer)) : fileText(answer);
|
|
439
|
+
}
|
|
440
|
+
const answer = stat === null ? absent(ctx, path) : existing(ctx, path, stat.isSymbolicLink());
|
|
441
|
+
return json ? documentOf(fileJson(answer)) : fileText(answer);
|
|
442
|
+
});
|
|
443
|
+
if (typeof outcome !== 'string')
|
|
444
|
+
return errorResult(outcome.errors, json, 'explain');
|
|
445
|
+
return { code: 0, stdout: outcome };
|
|
446
|
+
}
|