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
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { CONFIG } from './config.js';
|
|
4
|
+
import { git, mergeBase, resolveCommit, splitZ } from './files.js';
|
|
5
|
+
import { parseLaw } from './law.js';
|
|
6
|
+
import { LAW, RULES_DIR } from './setup.js';
|
|
7
|
+
import { decode, isBinary, splitLines } from './types.js';
|
|
8
|
+
import { MARKER, parseWaivers } from './waivers.js';
|
|
9
|
+
export const LINE_ITEMS = 5;
|
|
10
|
+
function parseEntries(output) {
|
|
11
|
+
const found = new Map();
|
|
12
|
+
let start = 0;
|
|
13
|
+
for (let i = 0; i < output.length; i++) {
|
|
14
|
+
if (output[i] !== 0)
|
|
15
|
+
continue;
|
|
16
|
+
const entry = output.subarray(start, i);
|
|
17
|
+
start = i + 1;
|
|
18
|
+
const tab = entry.indexOf(9);
|
|
19
|
+
if (tab < 0)
|
|
20
|
+
continue;
|
|
21
|
+
const [, , id] = entry.subarray(0, tab).toString('latin1').split(' ');
|
|
22
|
+
const paths = splitZ(Buffer.concat([entry.subarray(tab + 1), Buffer.from([0])]));
|
|
23
|
+
if (id !== undefined && paths[0] !== undefined)
|
|
24
|
+
found.set(paths[0], id);
|
|
25
|
+
}
|
|
26
|
+
return found;
|
|
27
|
+
}
|
|
28
|
+
function blobAt(root, commit, path) {
|
|
29
|
+
const listed = git(root, ['--literal-pathspecs', 'ls-tree', '-z', commit, '--', path]);
|
|
30
|
+
const id = listed.status === 0 ? parseEntries(listed.stdout).get(path) : undefined;
|
|
31
|
+
return id === undefined ? null : blobById(root, id);
|
|
32
|
+
}
|
|
33
|
+
function treeAt(root, commit) {
|
|
34
|
+
const result = git(root, ['ls-tree', '-r', '-z', commit, '--', RULES_DIR.slice(0, -1)]);
|
|
35
|
+
return result.status === 0 ? parseEntries(result.stdout) : new Map();
|
|
36
|
+
}
|
|
37
|
+
function blobById(root, id) {
|
|
38
|
+
const result = git(root, ['cat-file', 'blob', id]);
|
|
39
|
+
return result.status === 0 ? result.stdout : null;
|
|
40
|
+
}
|
|
41
|
+
const UNSAFE = /[\\\p{Cc}\p{Cf}\u2028\u2029]/gu;
|
|
42
|
+
export function named(path) {
|
|
43
|
+
return path.replace(UNSAFE, (c) => {
|
|
44
|
+
if (c === '\\')
|
|
45
|
+
return '\\\\';
|
|
46
|
+
const code = c.codePointAt(0);
|
|
47
|
+
if (code === 0x200c || code === 0x200d)
|
|
48
|
+
return c;
|
|
49
|
+
return code > 0xffff ? `\\u{${code.toString(16)}}` : `\\u${code.toString(16).padStart(4, '0')}`;
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
function fileNow(root, path) {
|
|
53
|
+
try {
|
|
54
|
+
return readFileSync(join(root, path));
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
return null;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
function lawOf(bytes) {
|
|
61
|
+
return parseLaw(bytes.toString('utf8')).law;
|
|
62
|
+
}
|
|
63
|
+
function flat(law) {
|
|
64
|
+
return new Map(law.byId);
|
|
65
|
+
}
|
|
66
|
+
function same(a, b) {
|
|
67
|
+
return JSON.stringify(a) === JSON.stringify(b);
|
|
68
|
+
}
|
|
69
|
+
function ofLaw(before, after) {
|
|
70
|
+
const items = [];
|
|
71
|
+
const was = flat(before);
|
|
72
|
+
const is = flat(after);
|
|
73
|
+
const sorted = (ids) => [...ids].sort();
|
|
74
|
+
for (const id of sorted(was.keys()))
|
|
75
|
+
if (!is.has(id))
|
|
76
|
+
items.push(`removes the type ${id}`);
|
|
77
|
+
for (const id of sorted(is.keys()))
|
|
78
|
+
if (!was.has(id))
|
|
79
|
+
items.push(`adds the type ${id}`);
|
|
80
|
+
for (const id of sorted(before.rules.keys()))
|
|
81
|
+
if (!after.rules.has(id))
|
|
82
|
+
items.push(`removes the rule ${id}`);
|
|
83
|
+
for (const id of sorted(after.rules.keys()))
|
|
84
|
+
if (!before.rules.has(id))
|
|
85
|
+
items.push(`adds the rule ${id}`);
|
|
86
|
+
for (const id of sorted(after.rules.keys())) {
|
|
87
|
+
const old = before.rules.get(id);
|
|
88
|
+
const now = after.rules.get(id);
|
|
89
|
+
if (old !== undefined && old.status !== now.status)
|
|
90
|
+
items.push(`makes the rule ${id} ${now.status}`);
|
|
91
|
+
}
|
|
92
|
+
for (const id of sorted(after.rules.keys())) {
|
|
93
|
+
const old = before.rules.get(id);
|
|
94
|
+
const now = after.rules.get(id);
|
|
95
|
+
if (old === undefined)
|
|
96
|
+
continue;
|
|
97
|
+
if (old.why !== now.why)
|
|
98
|
+
items.push(`changes the why of the rule ${id}`);
|
|
99
|
+
if (!same(old.context?.map((c) => c.path), now.context?.map((c) => c.path)))
|
|
100
|
+
items.push(`changes the context of the rule ${id}`);
|
|
101
|
+
}
|
|
102
|
+
for (const id of sorted(is.keys())) {
|
|
103
|
+
const old = was.get(id);
|
|
104
|
+
const now = is.get(id);
|
|
105
|
+
if (old === undefined)
|
|
106
|
+
continue;
|
|
107
|
+
for (const rule of old.rules)
|
|
108
|
+
if (!now.rules.includes(rule) && after.rules.has(rule))
|
|
109
|
+
items.push(`takes the rule ${rule} off the type ${id}`);
|
|
110
|
+
for (const rule of now.rules)
|
|
111
|
+
if (!old.rules.includes(rule) && before.rules.has(rule))
|
|
112
|
+
items.push(`puts the rule ${rule} on the type ${id}`);
|
|
113
|
+
if (!same(old.paths, now.paths))
|
|
114
|
+
items.push(`changes the paths of the type ${id}`);
|
|
115
|
+
if (old.content?.source !== now.content?.source)
|
|
116
|
+
items.push(`changes the content of the type ${id}`);
|
|
117
|
+
if (!same(old.mayUse, now.mayUse))
|
|
118
|
+
items.push(`changes may_use of the type ${id}`);
|
|
119
|
+
if (old.about !== now.about)
|
|
120
|
+
items.push(`changes the about of the type ${id}`);
|
|
121
|
+
if (old.waivers !== now.waivers)
|
|
122
|
+
items.push(`changes the waivers of the type ${id}`);
|
|
123
|
+
}
|
|
124
|
+
return items;
|
|
125
|
+
}
|
|
126
|
+
function ofFile(path, before, after) {
|
|
127
|
+
if (before === null && after === null)
|
|
128
|
+
return null;
|
|
129
|
+
const shown = named(path);
|
|
130
|
+
if (before === null)
|
|
131
|
+
return `adds ${shown}`;
|
|
132
|
+
if (after === null)
|
|
133
|
+
return `removes ${shown}`;
|
|
134
|
+
return before.equals(after) ? null : `changes ${shown}`;
|
|
135
|
+
}
|
|
136
|
+
// What the change does to the law that judges it, read against the merge base of HEAD and the base. A file that cannot be told apart in words is named, so the list is never empty when the law changed.
|
|
137
|
+
export function lawChanges(root, base, files, changed, plain) {
|
|
138
|
+
const commit = resolveCommit(root, base);
|
|
139
|
+
const fork = commit === null ? null : mergeBase(root, commit);
|
|
140
|
+
if (fork === null)
|
|
141
|
+
return [];
|
|
142
|
+
const items = [];
|
|
143
|
+
const lawBefore = blobAt(root, fork, LAW);
|
|
144
|
+
const lawAfter = fileNow(root, LAW);
|
|
145
|
+
const lawsBefore = lawBefore === null ? null : lawOf(lawBefore);
|
|
146
|
+
const lawsAfter = lawAfter === null ? null : lawOf(lawAfter);
|
|
147
|
+
if (lawBefore !== null && lawAfter !== null && !lawBefore.equals(lawAfter)) {
|
|
148
|
+
const told = lawsBefore !== null && lawsAfter !== null ? ofLaw(lawsBefore, lawsAfter) : [];
|
|
149
|
+
items.push(...(told.length > 0 ? told : [lawsBefore !== null && lawsAfter !== null ? `edits ${LAW} without changing a rule or a type` : `changes ${LAW}`]));
|
|
150
|
+
}
|
|
151
|
+
else {
|
|
152
|
+
const item = ofFile(LAW, lawBefore, lawAfter);
|
|
153
|
+
if (item !== null)
|
|
154
|
+
items.push(item);
|
|
155
|
+
}
|
|
156
|
+
const here = new Set(files);
|
|
157
|
+
const before = treeAt(root, fork);
|
|
158
|
+
const names = new Set([...before.keys()].filter((path) => !here.has(path)));
|
|
159
|
+
for (const path of changed)
|
|
160
|
+
if (path.startsWith(RULES_DIR))
|
|
161
|
+
names.add(path);
|
|
162
|
+
for (const path of [...names].sort()) {
|
|
163
|
+
const id = before.get(path);
|
|
164
|
+
const item = ofFile(path, id === undefined ? null : blobById(root, id), fileNow(root, path));
|
|
165
|
+
if (item !== null)
|
|
166
|
+
items.push(item);
|
|
167
|
+
}
|
|
168
|
+
const config = ofFile(CONFIG, blobAt(root, fork, CONFIG), fileNow(root, CONFIG));
|
|
169
|
+
if (config !== null)
|
|
170
|
+
items.push(config);
|
|
171
|
+
items.push(...waiversAdded(root, fork, changed, new Set([...(lawsBefore?.rules.keys() ?? []), ...(lawsAfter?.rules.keys() ?? []), 'forbidden-use']), plain));
|
|
172
|
+
return items;
|
|
173
|
+
}
|
|
174
|
+
function waiversOf(bytes, rules) {
|
|
175
|
+
const counts = new Map();
|
|
176
|
+
if (bytes === null || isBinary(bytes))
|
|
177
|
+
return counts;
|
|
178
|
+
for (const waiver of parseWaivers(splitLines(decode(bytes)), rules).waivers) {
|
|
179
|
+
const key = `${waiver.rule}\u0000${waiver.reason}`;
|
|
180
|
+
counts.set(key, (counts.get(key) ?? 0) + 1);
|
|
181
|
+
}
|
|
182
|
+
return counts;
|
|
183
|
+
}
|
|
184
|
+
function waiversAdded(root, fork, changed, rules, plain) {
|
|
185
|
+
const items = [];
|
|
186
|
+
for (const path of [...changed].sort()) {
|
|
187
|
+
if (path.startsWith(RULES_DIR) || plain.has(path))
|
|
188
|
+
continue;
|
|
189
|
+
const now = fileNow(root, path);
|
|
190
|
+
if (now === null || !now.includes(MARKER))
|
|
191
|
+
continue;
|
|
192
|
+
const before = waiversOf(blobAt(root, fork, path), rules);
|
|
193
|
+
const seen = new Map();
|
|
194
|
+
for (const [key, count] of waiversOf(now, rules)) {
|
|
195
|
+
const added = count - (before.get(key) ?? 0);
|
|
196
|
+
if (added > 0)
|
|
197
|
+
seen.set(key.split('\u0000')[0], (seen.get(key.split('\u0000')[0]) ?? 0) + added);
|
|
198
|
+
}
|
|
199
|
+
for (const rule of [...seen.keys()].sort())
|
|
200
|
+
items.push(`adds a waiver of ${rule} in ${named(path)}`);
|
|
201
|
+
}
|
|
202
|
+
return items;
|
|
203
|
+
}
|
|
204
|
+
export function lawChangeLine(items) {
|
|
205
|
+
const shown = items.slice(0, LINE_ITEMS).join('; ');
|
|
206
|
+
const rest = items.length - LINE_ITEMS;
|
|
207
|
+
return `note: this change edits the law that judges it: ${shown}${rest > 0 ? `; and ${rest} more` : ''}`;
|
|
208
|
+
}
|
package/dist/limits.js
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
import { closeSync, constants, fstatSync, openSync, readFileSync, readSync } from 'node:fs';
|
|
2
|
+
import { freemem } from 'node:os';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
const MiB = 1024 * 1024;
|
|
5
|
+
// The numbers of the table of limits in spec/check-slice.md, section 10, each measured as that section says.
|
|
6
|
+
export const HEAD_BYTES = 8000;
|
|
7
|
+
export const FILE_TEXT_BYTES = 16 * MiB;
|
|
8
|
+
export const FILE_LINES = 1_048_576;
|
|
9
|
+
export const RUN_TEXT_BYTES = 128 * MiB;
|
|
10
|
+
export const RUN_FINDINGS = 200_000;
|
|
11
|
+
export const RUN_MESSAGE_CHARS = 16 * MiB;
|
|
12
|
+
export const MESSAGE_CHARS = 4096;
|
|
13
|
+
export const RULES_RUN_MS = 600_000;
|
|
14
|
+
export const LAW_BYTES = 1 * MiB;
|
|
15
|
+
export const CONFIG_BYTES = 1 * MiB;
|
|
16
|
+
export const USES_FILE_BYTES = 512 * 1024;
|
|
17
|
+
export const LAW_RULES = 10_000;
|
|
18
|
+
export const LAW_TYPES = 1_000;
|
|
19
|
+
export const STEP_MS = 30_000;
|
|
20
|
+
export const MEMORY_BYTES = 1536 * MiB;
|
|
21
|
+
export const MEMORY_SHARE = 0.85;
|
|
22
|
+
export const STEP_MEMORY_BYTES = 384 * MiB;
|
|
23
|
+
export const MEMORY_RESERVE_BYTES = 128 * MiB;
|
|
24
|
+
export const MEMORY_CHECK_MS = 5;
|
|
25
|
+
// The most memory a run may hold: MEMORY_BYTES, or less on a smaller machine.
|
|
26
|
+
export function runBound(total) {
|
|
27
|
+
return Math.min(MEMORY_BYTES, Math.floor((total * MEMORY_SHARE) / MiB) * MiB);
|
|
28
|
+
}
|
|
29
|
+
// The memory the system can still give: on Linux the kernel's estimate, or a container's limit less what its processes use; on Windows the physical memory that is free or on standby. macOS counts only the pages free this moment, which it keeps few, so there it gives no number.
|
|
30
|
+
export function availableNow(platform = process.platform) {
|
|
31
|
+
if (platform === 'darwin')
|
|
32
|
+
return null;
|
|
33
|
+
const left = process.availableMemory();
|
|
34
|
+
if (platform !== 'linux' || left >= MEMORY_RESERVE_BYTES)
|
|
35
|
+
return left;
|
|
36
|
+
return withCache(left, cgroupStat(), freemem());
|
|
37
|
+
}
|
|
38
|
+
// A cgroup v2 counts its page cache as used, so right after a large write its limit less its use reads near nothing; where the kernel charges its own memory to the cgroup (most kernels; not one booted with cgroup.memory=nokmem), the dentries and inodes of every file the cgroup touched count as used too. The kernel takes both back before it kills a process of the cgroup, so they count as left, as the kernel's own estimate of available memory counts the page cache and the reclaimable slab, and never as more than that estimate. Shared memory and tmpfs are not on these lists.
|
|
39
|
+
export function withCache(left, stat, free) {
|
|
40
|
+
if (stat === null)
|
|
41
|
+
return left;
|
|
42
|
+
let cache = 0;
|
|
43
|
+
for (const line of stat.split('\n')) {
|
|
44
|
+
const [key, value] = line.split(' ');
|
|
45
|
+
if (key === 'active_file' || key === 'inactive_file' || key === 'slab_reclaimable')
|
|
46
|
+
cache += Number(value) || 0;
|
|
47
|
+
}
|
|
48
|
+
return cache === 0 ? left : Math.min(free, left + cache);
|
|
49
|
+
}
|
|
50
|
+
function cgroupStat() {
|
|
51
|
+
try {
|
|
52
|
+
const own = /^0::(\/.*)$/m.exec(readFileSync('/proc/self/cgroup', 'utf8'));
|
|
53
|
+
return own === null ? null : readFileSync(join('/sys/fs/cgroup', own[1], 'memory.stat'), 'utf8');
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
export function memoryCase(read) {
|
|
60
|
+
if (read.stepGrowth !== null && read.stepGrowth > STEP_MEMORY_BYTES)
|
|
61
|
+
return 'file';
|
|
62
|
+
if (read.rss > runBound(read.total))
|
|
63
|
+
return 'run';
|
|
64
|
+
if (read.available !== null && read.available < MEMORY_RESERVE_BYTES)
|
|
65
|
+
return 'system';
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
// A character is a code point, as a reader counts one, so a pair of UTF-16 code units counts once.
|
|
69
|
+
export function points(text) {
|
|
70
|
+
let count = text.length;
|
|
71
|
+
for (let i = 1; i < text.length; i++) {
|
|
72
|
+
const low = text.charCodeAt(i);
|
|
73
|
+
if (low >= 0xdc00 && low <= 0xdfff) {
|
|
74
|
+
const high = text.charCodeAt(i - 1);
|
|
75
|
+
if (high >= 0xd800 && high <= 0xdbff)
|
|
76
|
+
count--;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
return count;
|
|
80
|
+
}
|
|
81
|
+
export function mib(bytes) {
|
|
82
|
+
return bytes < MiB ? `${bytes / 1024} KiB` : `${bytes / MiB} MiB`;
|
|
83
|
+
}
|
|
84
|
+
export function count(value) {
|
|
85
|
+
return value.toLocaleString('en-US');
|
|
86
|
+
}
|
|
87
|
+
export class FileTooLarge extends Error {
|
|
88
|
+
path;
|
|
89
|
+
bytes;
|
|
90
|
+
lines;
|
|
91
|
+
constructor(path, bytes, lines = null) {
|
|
92
|
+
super(lines === null ? `${path} holds ${count(bytes)} bytes, more than the ${mib(FILE_TEXT_BYTES)} a file read as text may hold` : `${path} holds ${count(lines)} lines, more than the ${count(FILE_LINES)} a file read as text may hold`);
|
|
93
|
+
this.path = path;
|
|
94
|
+
this.bytes = bytes;
|
|
95
|
+
this.lines = lines;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
export class TextTooLarge extends Error {
|
|
99
|
+
path;
|
|
100
|
+
bytes;
|
|
101
|
+
constructor(path, bytes) {
|
|
102
|
+
super(`the text read in this run reaches ${count(bytes)} bytes at ${path}, more than the ${mib(RUN_TEXT_BYTES)} one run may read`);
|
|
103
|
+
this.path = path;
|
|
104
|
+
this.bytes = bytes;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
export function tooLargeError(error) {
|
|
108
|
+
if (error instanceof FileTooLarge) {
|
|
109
|
+
const what = error.lines === null ? `${count(error.bytes)} bytes, more than the ${mib(FILE_TEXT_BYTES)}` : `${count(error.lines)} lines, more than the ${count(FILE_LINES)}`;
|
|
110
|
+
return { code: 'file-too-large', file: error.path, line: null, message: `the file holds ${what} a file read as text may hold` };
|
|
111
|
+
}
|
|
112
|
+
return {
|
|
113
|
+
code: 'text-too-large',
|
|
114
|
+
file: error.path,
|
|
115
|
+
line: null,
|
|
116
|
+
message: `the text of the files read in this run reaches ${count(error.bytes)} bytes with this file, more than the ${mib(RUN_TEXT_BYTES)} one run may read`,
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
export class NotRegular extends Error {
|
|
120
|
+
path;
|
|
121
|
+
constructor(path) {
|
|
122
|
+
super(`${path} is no regular file`);
|
|
123
|
+
this.path = path;
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
export function readError(path, error) {
|
|
127
|
+
if (error instanceof NotRegular)
|
|
128
|
+
return { code: 'file-unreadable', file: path, line: null, message: 'the file cannot be read (it is no regular file)' };
|
|
129
|
+
if (error instanceof FileTooLarge || error instanceof TextTooLarge)
|
|
130
|
+
return tooLargeError(error);
|
|
131
|
+
const code = error.code ?? 'an error';
|
|
132
|
+
return { code: 'file-unreadable', file: path, line: null, message: `the file cannot be read (${code})` };
|
|
133
|
+
}
|
|
134
|
+
const head = Buffer.allocUnsafe(HEAD_BYTES);
|
|
135
|
+
// A named pipe or a device opened for reading waits for a writer, and the thread waiting in that call cannot be ended; opened without waiting, it is refused by its kind.
|
|
136
|
+
const OPEN = process.platform === 'win32' ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NONBLOCK;
|
|
137
|
+
// A binary file is known by its first 8,000 bytes, so only they are read, and only up to the NUL is kept; a text file is read whole, up to its limit.
|
|
138
|
+
export function readBounded(full, path, headOnly = true) {
|
|
139
|
+
const limit = FILE_TEXT_BYTES;
|
|
140
|
+
const fd = openSync(full, OPEN);
|
|
141
|
+
try {
|
|
142
|
+
const stat = fstatSync(fd);
|
|
143
|
+
if (stat.isDirectory())
|
|
144
|
+
throw Object.assign(new Error('EISDIR: illegal operation on a directory, read'), { code: 'EISDIR' });
|
|
145
|
+
if (!stat.isFile())
|
|
146
|
+
throw new NotRegular(path);
|
|
147
|
+
const size = stat.size;
|
|
148
|
+
let got = 0;
|
|
149
|
+
while (got < HEAD_BYTES) {
|
|
150
|
+
const n = readSync(fd, head, got, HEAD_BYTES - got, null);
|
|
151
|
+
if (n === 0)
|
|
152
|
+
break;
|
|
153
|
+
got += n;
|
|
154
|
+
}
|
|
155
|
+
const nul = head.subarray(0, got).indexOf(0);
|
|
156
|
+
if (headOnly && nul >= 0)
|
|
157
|
+
return { bytes: Buffer.from(head.subarray(0, nul + 1)), binary: true };
|
|
158
|
+
if (got < HEAD_BYTES)
|
|
159
|
+
return { bytes: Buffer.from(head.subarray(0, got)), binary: false };
|
|
160
|
+
if (size > limit)
|
|
161
|
+
throw new FileTooLarge(path, size);
|
|
162
|
+
let buffer = Buffer.allocUnsafe(Math.min(Math.max(size, HEAD_BYTES), limit) + 1);
|
|
163
|
+
head.copy(buffer, 0, 0, got);
|
|
164
|
+
for (;;) {
|
|
165
|
+
if (got === buffer.length) {
|
|
166
|
+
if (got > limit)
|
|
167
|
+
throw new FileTooLarge(path, got);
|
|
168
|
+
const grown = Buffer.allocUnsafe(Math.min(buffer.length * 2, limit + 1));
|
|
169
|
+
buffer.copy(grown, 0, 0, got);
|
|
170
|
+
buffer = grown;
|
|
171
|
+
}
|
|
172
|
+
const n = readSync(fd, buffer, got, buffer.length - got, null);
|
|
173
|
+
if (n === 0)
|
|
174
|
+
break;
|
|
175
|
+
got += n;
|
|
176
|
+
if (got > limit)
|
|
177
|
+
throw new FileTooLarge(path, got);
|
|
178
|
+
}
|
|
179
|
+
const bytes = buffer.subarray(0, got);
|
|
180
|
+
// A run holds a line in memory at a cost of its own, so a file of short lines is bounded by their count as well as by its bytes.
|
|
181
|
+
if (headOnly) {
|
|
182
|
+
const lines = lineEnds(bytes);
|
|
183
|
+
if (lines > FILE_LINES)
|
|
184
|
+
throw new FileTooLarge(path, got, lines);
|
|
185
|
+
}
|
|
186
|
+
return { bytes, binary: false };
|
|
187
|
+
}
|
|
188
|
+
finally {
|
|
189
|
+
closeSync(fd);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
function lineEnds(bytes) {
|
|
193
|
+
let lines = 0;
|
|
194
|
+
for (let at = bytes.indexOf(10); at >= 0; at = bytes.indexOf(10, at + 1))
|
|
195
|
+
lines++;
|
|
196
|
+
return bytes.length > 0 && bytes[bytes.length - 1] !== 10 ? lines + 1 : lines;
|
|
197
|
+
}
|
|
198
|
+
export function readWhole(full, path) {
|
|
199
|
+
return readBounded(full, path, false).bytes;
|
|
200
|
+
}
|
|
201
|
+
export function readFailure(error) {
|
|
202
|
+
if (error instanceof FileTooLarge)
|
|
203
|
+
return `it holds more than ${mib(FILE_TEXT_BYTES)}`;
|
|
204
|
+
if (error instanceof NotRegular)
|
|
205
|
+
return 'it is no regular file';
|
|
206
|
+
return error.code ?? 'an error';
|
|
207
|
+
}
|
package/dist/main.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { step } from './progress.js';
|
|
2
|
+
import { check } from './check.js';
|
|
3
|
+
import { firstLine } from './law.js';
|
|
4
|
+
import { renderErrors, renderReport, safeJson, safeText } from './output.js';
|
|
5
|
+
import { hiddenJson, useKeys } from './keys.js';
|
|
6
|
+
import { COMMANDS, number, PROGRAM_USAGE, readArguments, text, usageError, USAGE, version } from './args.js';
|
|
7
|
+
export { version };
|
|
8
|
+
import { init } from './init.js';
|
|
9
|
+
import { prime } from './prime.js';
|
|
10
|
+
import { explain } from './explain.js';
|
|
11
|
+
import { tryRule } from './try.js';
|
|
12
|
+
import { docs } from './docs.js';
|
|
13
|
+
import { doctor } from './doctor.js';
|
|
14
|
+
import { environmentRefusal, gitNow, runtimeNow } from './environment.js';
|
|
15
|
+
export function parseArguments(argv) {
|
|
16
|
+
const read = readArguments(argv);
|
|
17
|
+
if ('problem' in read)
|
|
18
|
+
return { problem: read.problem };
|
|
19
|
+
if (read.arguments.command !== 'check')
|
|
20
|
+
return { problem: `the command '${read.arguments.command}' is not check` };
|
|
21
|
+
return checkOptions(read.arguments);
|
|
22
|
+
}
|
|
23
|
+
function checkOptions(args) {
|
|
24
|
+
const review = args.flags.has('--review');
|
|
25
|
+
if (args.words.length > 0 && ['--full', '--base', '--review', '--again', '--max-calls'].some((flag) => args.flags.has(flag))) {
|
|
26
|
+
return { problem: 'paths go with --json alone' };
|
|
27
|
+
}
|
|
28
|
+
if (!review && args.flags.has('--again'))
|
|
29
|
+
return { problem: 'the flag --again works only with --review' };
|
|
30
|
+
if (!review && args.flags.has('--max-calls'))
|
|
31
|
+
return { problem: 'the flag --max-calls works only with --review' };
|
|
32
|
+
return { options: { full: args.flags.has('--full'), base: text(args, '--base'), review, again: args.flags.has('--again'), maxCalls: number(args, '--max-calls'), paths: args.words } };
|
|
33
|
+
}
|
|
34
|
+
function internal(error) {
|
|
35
|
+
return { code: 'internal', file: null, line: null, message: firstLine(error) || 'an unknown failure' };
|
|
36
|
+
}
|
|
37
|
+
const HANDLERS = { init, prime, explain, try: tryRule, docs, doctor };
|
|
38
|
+
export async function main(argv, context, command = check) {
|
|
39
|
+
useKeys(context.env);
|
|
40
|
+
const result = await run(argv, context, command);
|
|
41
|
+
return { ...result, stdout: argv.includes('--json') ? safeJson(hiddenJson(result.stdout)) : safeText(result.stdout) };
|
|
42
|
+
}
|
|
43
|
+
async function run(argv, context, command) {
|
|
44
|
+
const json = argv.includes('--json');
|
|
45
|
+
const named = COMMANDS.includes(argv[0] ?? '') ? argv[0] : null;
|
|
46
|
+
try {
|
|
47
|
+
if (argv.length === 1 && argv[0] === '--version')
|
|
48
|
+
return { code: 0, stdout: version() + '\n' };
|
|
49
|
+
if (argv.length === 1 && argv[0] === '--help')
|
|
50
|
+
return { code: 0, stdout: PROGRAM_USAGE };
|
|
51
|
+
if (argv.length === 2 && named !== null && argv[1] === '--help')
|
|
52
|
+
return { code: 0, stdout: USAGE[named] };
|
|
53
|
+
const read = readArguments(argv);
|
|
54
|
+
if ('problem' in read)
|
|
55
|
+
return usageError(read.problem, json, read.command);
|
|
56
|
+
const args = read.arguments;
|
|
57
|
+
if (args.command !== 'docs' && args.command !== 'doctor') {
|
|
58
|
+
const refused = environmentRefusal(context.runtime ?? runtimeNow(), () => gitNow(context.cwd));
|
|
59
|
+
if (refused !== null)
|
|
60
|
+
return { code: 2, stdout: renderErrors([refused], json, args.command) };
|
|
61
|
+
}
|
|
62
|
+
if (args.command !== 'check')
|
|
63
|
+
return await HANDLERS[args.command](args, context, json);
|
|
64
|
+
const parsed = checkOptions(args);
|
|
65
|
+
if ('problem' in parsed)
|
|
66
|
+
return usageError(parsed.problem, json, 'check');
|
|
67
|
+
const outcome = await command(parsed.options, context);
|
|
68
|
+
if ('errors' in outcome)
|
|
69
|
+
return { code: 2, stdout: renderErrors(outcome.errors, json) };
|
|
70
|
+
step('writing the report');
|
|
71
|
+
const text = renderReport(outcome.report, json);
|
|
72
|
+
return { code: outcome.report.findings.some((f) => f.severity === 'error') ? 1 : 0, stdout: text };
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
return { code: 2, stdout: renderErrors([internal(error)], json, named) };
|
|
76
|
+
}
|
|
77
|
+
}
|
package/dist/names.js
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { join, sep } from 'node:path';
|
|
2
|
+
const strict = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
|
|
3
|
+
const PLAIN = /^[^\\\n\r]*$/;
|
|
4
|
+
const HEX = '0123456789abcdef';
|
|
5
|
+
function hex(byte) {
|
|
6
|
+
return `\\x${HEX[byte >> 4]}${HEX[byte & 15]}`;
|
|
7
|
+
}
|
|
8
|
+
function sequence(bytes, at) {
|
|
9
|
+
const lead = bytes[at];
|
|
10
|
+
if (lead < 0x80)
|
|
11
|
+
return 1;
|
|
12
|
+
const continued = (i, low = 0x80, high = 0xbf) => at + i < bytes.length && bytes[at + i] >= low && bytes[at + i] <= high;
|
|
13
|
+
if (lead >= 0xc2 && lead <= 0xdf)
|
|
14
|
+
return continued(1) ? 2 : 0;
|
|
15
|
+
if (lead === 0xe0)
|
|
16
|
+
return continued(1, 0xa0) && continued(2) ? 3 : 0;
|
|
17
|
+
if (lead === 0xed)
|
|
18
|
+
return continued(1, 0x80, 0x9f) && continued(2) ? 3 : 0;
|
|
19
|
+
if (lead >= 0xe1 && lead <= 0xef)
|
|
20
|
+
return continued(1) && continued(2) ? 3 : 0;
|
|
21
|
+
if (lead === 0xf0)
|
|
22
|
+
return continued(1, 0x90) && continued(2) && continued(3) ? 4 : 0;
|
|
23
|
+
if (lead === 0xf4)
|
|
24
|
+
return continued(1, 0x80, 0x8f) && continued(2) && continued(3) ? 4 : 0;
|
|
25
|
+
if (lead >= 0xf1 && lead <= 0xf3)
|
|
26
|
+
return continued(1) && continued(2) && continued(3) ? 4 : 0;
|
|
27
|
+
return 0;
|
|
28
|
+
}
|
|
29
|
+
// spec/check-slice.md, section 2: a path's bytes read as UTF-8, with a backslash, a line feed, a carriage return and every byte outside valid UTF-8 written as an escape, so the name holds no line break and maps back to the bytes on disk.
|
|
30
|
+
export function nameOf(bytes) {
|
|
31
|
+
try {
|
|
32
|
+
const text = strict.decode(bytes);
|
|
33
|
+
if (PLAIN.test(text))
|
|
34
|
+
return text;
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
// Not valid UTF-8: the bytes are escaped one sequence at a time below.
|
|
38
|
+
}
|
|
39
|
+
let out = '';
|
|
40
|
+
for (let at = 0; at < bytes.length;) {
|
|
41
|
+
const length = sequence(bytes, at);
|
|
42
|
+
if (length === 0) {
|
|
43
|
+
out += hex(bytes[at]);
|
|
44
|
+
at++;
|
|
45
|
+
continue;
|
|
46
|
+
}
|
|
47
|
+
const ch = strict.decode(bytes.subarray(at, at + length));
|
|
48
|
+
out += ch === '\\' ? '\\\\' : ch === '\n' ? '\\n' : ch === '\r' ? '\\r' : ch;
|
|
49
|
+
at += length;
|
|
50
|
+
}
|
|
51
|
+
return out;
|
|
52
|
+
}
|
|
53
|
+
const NAMED = { '\\': 0x5c, n: 0x0a, r: 0x0d, t: 0x09 };
|
|
54
|
+
// The bytes a name stands for. Besides the escapes nameOf writes, \t, \x with two hexadecimal digits and \u with four are read, which the text output writes for other characters; a backslash that starts none of these stands for itself.
|
|
55
|
+
export function bytesOfName(name) {
|
|
56
|
+
if (!name.includes('\\'))
|
|
57
|
+
return Buffer.from(name, 'utf8');
|
|
58
|
+
const parts = [];
|
|
59
|
+
let plain = '';
|
|
60
|
+
const flush = () => {
|
|
61
|
+
if (plain !== '')
|
|
62
|
+
parts.push(Buffer.from(plain, 'utf8'));
|
|
63
|
+
plain = '';
|
|
64
|
+
};
|
|
65
|
+
for (let i = 0; i < name.length; i++) {
|
|
66
|
+
const ch = name[i];
|
|
67
|
+
if (ch !== '\\') {
|
|
68
|
+
plain += ch;
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
const next = name[i + 1];
|
|
72
|
+
if (next !== undefined && Object.hasOwn(NAMED, next)) {
|
|
73
|
+
flush();
|
|
74
|
+
parts.push(Buffer.from([NAMED[next]]));
|
|
75
|
+
i++;
|
|
76
|
+
}
|
|
77
|
+
else if (next === 'x' && /^[0-9a-fA-F]{2}$/.test(name.slice(i + 2, i + 4))) {
|
|
78
|
+
flush();
|
|
79
|
+
parts.push(Buffer.from([parseInt(name.slice(i + 2, i + 4), 16)]));
|
|
80
|
+
i += 3;
|
|
81
|
+
}
|
|
82
|
+
else if (next === 'u' && /^[0-9a-fA-F]{4}$/.test(name.slice(i + 2, i + 6))) {
|
|
83
|
+
plain += String.fromCharCode(parseInt(name.slice(i + 2, i + 6), 16));
|
|
84
|
+
i += 5;
|
|
85
|
+
}
|
|
86
|
+
else {
|
|
87
|
+
plain += ch;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
flush();
|
|
91
|
+
return Buffer.concat(parts);
|
|
92
|
+
}
|
|
93
|
+
// The one spelling of a name a user typed, so a raw backslash and its escape select the same file; Windows reads a backslash as a separator, and its file names hold none of the escaped bytes.
|
|
94
|
+
export function canonicalName(word) {
|
|
95
|
+
if (sep === '\\' || !word.includes('\\'))
|
|
96
|
+
return word;
|
|
97
|
+
return nameOf(bytesOfName(word));
|
|
98
|
+
}
|
|
99
|
+
export function onDisk(root, name) {
|
|
100
|
+
if (sep === '\\' || !name.includes('\\'))
|
|
101
|
+
return join(root, name);
|
|
102
|
+
return Buffer.concat([Buffer.from(join(root, '/'), 'utf8'), bytesOfName(name)]);
|
|
103
|
+
}
|
|
104
|
+
// git reads a path of --stdin-paths in C quotes when the line starts with a double quote, from the top of the work tree; quoting every path the same way carries any byte and needs no other rule.
|
|
105
|
+
export function quotedLine(prefix, bytes) {
|
|
106
|
+
const out = [0x22];
|
|
107
|
+
for (const byte of [...Buffer.from(prefix, 'utf8'), ...bytes]) {
|
|
108
|
+
if (byte === 0x22 || byte === 0x5c)
|
|
109
|
+
out.push(0x5c, byte);
|
|
110
|
+
else if (byte < 0x20 || byte >= 0x7f)
|
|
111
|
+
out.push(0x5c, ...Buffer.from(byte.toString(8).padStart(3, '0')));
|
|
112
|
+
else
|
|
113
|
+
out.push(byte);
|
|
114
|
+
}
|
|
115
|
+
out.push(0x22, 0x0a);
|
|
116
|
+
return Buffer.from(out);
|
|
117
|
+
}
|