vigiles 41.0.0 → 41.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/core/rule-proof/kits/eslint.d.ts +30 -0
- package/dist/core/rule-proof/kits/eslint.js +130 -0
- package/dist/core/rule-proof/kits/index.d.ts +7 -0
- package/dist/core/rule-proof/kits/index.js +12 -0
- package/dist/core/rule-proof/kits/ruff.d.ts +28 -0
- package/dist/core/rule-proof/kits/ruff.js +178 -0
- package/dist/core/rule-proof/node-install.d.ts +32 -0
- package/dist/core/rule-proof/node-install.js +117 -0
- package/dist/core/rule-proof/pair.d.ts +11 -0
- package/dist/core/rule-proof/pair.js +61 -0
- package/dist/core/rule-proof/port.d.ts +77 -0
- package/dist/core/rule-proof/port.js +3 -0
- package/dist/core/rule-proof/report.d.ts +11 -0
- package/dist/core/rule-proof/report.js +36 -0
- package/dist/core/rule-proof/run.d.ts +58 -0
- package/dist/core/rule-proof/run.js +260 -0
- package/dist/core/rule-proof/types.d.ts +119 -0
- package/dist/core/rule-proof/types.js +13 -0
- package/dist/entries/rule-proof.d.ts +18 -0
- package/dist/entries/rule-proof.js +23 -0
- package/dist/host/rule-proof.io.d.ts +4 -0
- package/dist/host/rule-proof.io.js +64 -0
- package/package.json +2 -1
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The two ports of `experimental_ruleProof`.
|
|
3
|
+
*
|
|
4
|
+
* {@link RuleProofHost} is every effect the steps need from the machine; the
|
|
5
|
+
* host adapter (`src/host/rule-proof.io.ts`) implements it. {@link ProofKit} is
|
|
6
|
+
* everything the steps need to know about ONE linter; each kit is a module in
|
|
7
|
+
* `./kits/`, and the set is assembled there and handed in by the entry root. The
|
|
8
|
+
* steps (`./run.ts`) know neither a machine nor a linter by name.
|
|
9
|
+
*/
|
|
10
|
+
import type { BaseReading, ExecOptions, ExecResult, LintParse } from "./types.js";
|
|
11
|
+
/** Every effect rule-proof needs. Paths are absolute unless a member says otherwise. */
|
|
12
|
+
export interface RuleProofHost {
|
|
13
|
+
readonly exec: (command: string, args: readonly string[], options: ExecOptions) => ExecResult;
|
|
14
|
+
/** A file's text, or null when it is absent or unreadable. */
|
|
15
|
+
readonly read: (path: string) => string | null;
|
|
16
|
+
readonly exists: (path: string) => boolean;
|
|
17
|
+
/** Entry names directly in `dir`. */
|
|
18
|
+
readonly list: (dir: string) => readonly string[];
|
|
19
|
+
/** Write a file, making its parent directories. */
|
|
20
|
+
readonly write: (path: string, text: string) => void;
|
|
21
|
+
/** Remove a file or a directory tree; absent is fine. */
|
|
22
|
+
readonly remove: (path: string) => void;
|
|
23
|
+
/**
|
|
24
|
+
* Files under `dir` matching `patterns`: relative, `/`-separated, never
|
|
25
|
+
* inside node_modules or .git.
|
|
26
|
+
*/
|
|
27
|
+
readonly files: (dir: string, patterns: readonly string[]) => readonly string[];
|
|
28
|
+
}
|
|
29
|
+
/** What a kit may look at in a repository's root before installing. */
|
|
30
|
+
export interface RootView {
|
|
31
|
+
/** Entry names at the root. */
|
|
32
|
+
readonly names: readonly string[];
|
|
33
|
+
/** A root file's text by name, or null. */
|
|
34
|
+
readonly read: (name: string) => string | null;
|
|
35
|
+
}
|
|
36
|
+
/** How to install a linter at the repository's pinned version, or why that is impossible. */
|
|
37
|
+
export type KitPlan = {
|
|
38
|
+
readonly kind: "plan";
|
|
39
|
+
/** The install command and its arguments, run in the repository. */
|
|
40
|
+
readonly install: readonly [string, ...string[]];
|
|
41
|
+
/** The argv prefix that runs the linter once installed. */
|
|
42
|
+
readonly command: (dir: string) => readonly string[];
|
|
43
|
+
/** The installed version, given a reader of repository-relative files; null when absent. */
|
|
44
|
+
readonly version: (read: (path: string) => string | null) => string | null;
|
|
45
|
+
/** What to say when `version` finds nothing after the install. */
|
|
46
|
+
readonly missing: string;
|
|
47
|
+
} | {
|
|
48
|
+
readonly kind: "none";
|
|
49
|
+
readonly stage: "no-lockfile" | "no-pin";
|
|
50
|
+
readonly reason: string;
|
|
51
|
+
};
|
|
52
|
+
/** One lint call: the config file to write, and the arguments after the command. */
|
|
53
|
+
export interface Invocation {
|
|
54
|
+
readonly configPath: string;
|
|
55
|
+
readonly configText: string;
|
|
56
|
+
readonly args: readonly string[];
|
|
57
|
+
}
|
|
58
|
+
/** Where a lint call runs and where its scratch files go. */
|
|
59
|
+
export interface Places {
|
|
60
|
+
readonly dir: string;
|
|
61
|
+
readonly cacheDir: string;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Everything the steps need to know about one linter. Methods, not function
|
|
65
|
+
* properties: a kit of a narrower reading is still a kit.
|
|
66
|
+
*/
|
|
67
|
+
export interface ProofKit<R extends BaseReading> {
|
|
68
|
+
readonly linter: R["linter"];
|
|
69
|
+
plan(root: RootView): KitPlan;
|
|
70
|
+
/** Environment that keeps this linter's tools' caches under `cacheDir`. */
|
|
71
|
+
env(cacheDir: string): Readonly<Record<string, string>>;
|
|
72
|
+
invocation(reading: R, files: readonly string[], places: Places): Invocation;
|
|
73
|
+
/** Exit codes after which stdout holds a report. Any other is `config-load`. */
|
|
74
|
+
readonly reportCodes: readonly number[];
|
|
75
|
+
parse(stdout: string, files: readonly string[], reading: R, dir: string): LintParse;
|
|
76
|
+
}
|
|
77
|
+
//# sourceMappingURL=port.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { LintParse } from "./types.js";
|
|
2
|
+
/** `file` relative to `dir`, `/`-separated. */
|
|
3
|
+
export declare const toRelative: (dir: string, file: string) => string;
|
|
4
|
+
/**
|
|
5
|
+
* The JSON array in a linter's stdout. A plugin may print banner lines first,
|
|
6
|
+
* so the array starts at the first line that opens one.
|
|
7
|
+
*/
|
|
8
|
+
export declare function jsonArray(stdout: string): unknown;
|
|
9
|
+
/** Output that is not the report: never an empty list. */
|
|
10
|
+
export declare const unreadable: (stdout: string) => LintParse;
|
|
11
|
+
//# sourceMappingURL=report.d.ts.map
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.unreadable = exports.toRelative = void 0;
|
|
4
|
+
exports.jsonArray = jsonArray;
|
|
5
|
+
/**
|
|
6
|
+
* Helpers every kit uses to read its linter's JSON report: the array after any
|
|
7
|
+
* banner lines, paths made repository-relative, and the one shape an unreadable
|
|
8
|
+
* report takes.
|
|
9
|
+
*/
|
|
10
|
+
const node_path_1 = require("node:path");
|
|
11
|
+
/** `file` relative to `dir`, `/`-separated. */
|
|
12
|
+
const toRelative = (dir, file) => (0, node_path_1.relative)(dir, file).split(node_path_1.sep).join(node_path_1.posix.sep);
|
|
13
|
+
exports.toRelative = toRelative;
|
|
14
|
+
/**
|
|
15
|
+
* The JSON array in a linter's stdout. A plugin may print banner lines first,
|
|
16
|
+
* so the array starts at the first line that opens one.
|
|
17
|
+
*/
|
|
18
|
+
function jsonArray(stdout) {
|
|
19
|
+
const start = stdout.search(/^\[/m);
|
|
20
|
+
if (start === -1)
|
|
21
|
+
return undefined;
|
|
22
|
+
try {
|
|
23
|
+
const value = JSON.parse(stdout.slice(start));
|
|
24
|
+
return value;
|
|
25
|
+
}
|
|
26
|
+
catch {
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/** Output that is not the report: never an empty list. */
|
|
31
|
+
const unreadable = (stdout) => ({
|
|
32
|
+
kind: "unreadable",
|
|
33
|
+
reason: `no JSON report in the linter's output: ${stdout.slice(0, 200)}`,
|
|
34
|
+
});
|
|
35
|
+
exports.unreadable = unreadable;
|
|
36
|
+
//# sourceMappingURL=report.js.map
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { ProofKit, RuleProofHost } from "./port.js";
|
|
2
|
+
import type { BaseReading, FlaggedRun, InstallOptions, NotInstalled, NotRun, PlantedPair } from "./types.js";
|
|
3
|
+
type Settled = Required<InstallOptions>;
|
|
4
|
+
/** A repository's own linter at its pinned version. Only `install` makes one. */
|
|
5
|
+
export declare class PinnedLinter<R extends BaseReading> {
|
|
6
|
+
readonly linter: R["linter"];
|
|
7
|
+
readonly version: string;
|
|
8
|
+
readonly dir: string;
|
|
9
|
+
/** @internal the kit, the argv prefix that runs the linter, the settled options */
|
|
10
|
+
readonly run: {
|
|
11
|
+
readonly kit: ProofKit<R>;
|
|
12
|
+
readonly command: readonly string[];
|
|
13
|
+
readonly options: Settled;
|
|
14
|
+
};
|
|
15
|
+
private readonly brand;
|
|
16
|
+
/** @internal */
|
|
17
|
+
constructor(linter: R["linter"], version: string, dir: string,
|
|
18
|
+
/** @internal the kit, the argv prefix that runs the linter, the settled options */
|
|
19
|
+
run: {
|
|
20
|
+
readonly kit: ProofKit<R>;
|
|
21
|
+
readonly command: readonly string[];
|
|
22
|
+
readonly options: Settled;
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
/** A reading that passed its planted pair on one PinnedLinter. Only `prove` makes one. */
|
|
26
|
+
export declare class ProvedReading<R extends BaseReading> {
|
|
27
|
+
readonly pinned: PinnedLinter<R>;
|
|
28
|
+
readonly reading: R;
|
|
29
|
+
private readonly brand;
|
|
30
|
+
/** @internal */
|
|
31
|
+
constructor(pinned: PinnedLinter<R>, reading: R);
|
|
32
|
+
}
|
|
33
|
+
/** The install's outcome. */
|
|
34
|
+
export type Installed<R extends BaseReading> = {
|
|
35
|
+
readonly kind: "installed";
|
|
36
|
+
readonly linter: PinnedLinter<R>;
|
|
37
|
+
} | NotInstalled;
|
|
38
|
+
/** The verdict on one reading's planted pair. */
|
|
39
|
+
export type Proof<R extends BaseReading> = {
|
|
40
|
+
readonly kind: "proved";
|
|
41
|
+
readonly reading: ProvedReading<R>;
|
|
42
|
+
} | {
|
|
43
|
+
readonly kind: "not-proved";
|
|
44
|
+
readonly badHits: number;
|
|
45
|
+
readonly goodHits: number;
|
|
46
|
+
} | NotRun;
|
|
47
|
+
/** A kit set keyed by linter name, each kit typed by its own reading. */
|
|
48
|
+
export type KitSet<M extends Record<string, BaseReading>> = {
|
|
49
|
+
readonly [N in keyof M]: ProofKit<M[N]>;
|
|
50
|
+
};
|
|
51
|
+
/** The three steps over one host and one kit set. */
|
|
52
|
+
export declare function ruleProofWith<M extends Record<string, BaseReading>>(host: RuleProofHost, kits: KitSet<M>): {
|
|
53
|
+
install: <N extends keyof M>(linter: N, dir: string, options: InstallOptions) => Installed<M[N]>;
|
|
54
|
+
prove: <R extends BaseReading>(pinned: PinnedLinter<R>, reading: NoInfer<R>, pair: PlantedPair) => Proof<R>;
|
|
55
|
+
flagged: <R extends BaseReading>(proved: ProvedReading<R>) => FlaggedRun;
|
|
56
|
+
};
|
|
57
|
+
export {};
|
|
58
|
+
//# sourceMappingURL=run.d.ts.map
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.ProvedReading = exports.PinnedLinter = void 0;
|
|
4
|
+
exports.ruleProofWith = ruleProofWith;
|
|
5
|
+
/**
|
|
6
|
+
* `experimental_ruleProof`'s three steps, over the {@link RuleProofHost} port
|
|
7
|
+
* and a set of {@link ProofKit}s. This file names no machine and no linter: the
|
|
8
|
+
* host adapter does every effect, a kit knows its linter, and the entry root
|
|
9
|
+
* hands both in.
|
|
10
|
+
*
|
|
11
|
+
* install(linter, dir) → a PinnedLinter: the repository's own linter version
|
|
12
|
+
* prove(pinned, reading, { bad, good })
|
|
13
|
+
* → a ProvedReading only when the planted violation is
|
|
14
|
+
* flagged AND its twin is not
|
|
15
|
+
* flagged(proved) → the repository files that reading flags
|
|
16
|
+
*
|
|
17
|
+
* Each step takes a value only the step before can make. So a reading cannot be
|
|
18
|
+
* run over a repository before it passed its pair, the pair cannot be half a
|
|
19
|
+
* pair, and the pair cannot be checked at one linter version and the
|
|
20
|
+
* repository run at another: `flagged` takes the ProvedReading alone, and it
|
|
21
|
+
* carries the PinnedLinter it was proved on. The classes are nominal (a
|
|
22
|
+
* `private` member), so an object of the same shape is not one.
|
|
23
|
+
*/
|
|
24
|
+
const node_path_1 = require("node:path");
|
|
25
|
+
const pair_js_1 = require("./pair.js");
|
|
26
|
+
/** A repository's own linter at its pinned version. Only `install` makes one. */
|
|
27
|
+
class PinnedLinter {
|
|
28
|
+
linter;
|
|
29
|
+
version;
|
|
30
|
+
dir;
|
|
31
|
+
run;
|
|
32
|
+
/** @internal */
|
|
33
|
+
constructor(linter, version, dir,
|
|
34
|
+
/** @internal the kit, the argv prefix that runs the linter, the settled options */
|
|
35
|
+
run) {
|
|
36
|
+
this.linter = linter;
|
|
37
|
+
this.version = version;
|
|
38
|
+
this.dir = dir;
|
|
39
|
+
this.run = run;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
exports.PinnedLinter = PinnedLinter;
|
|
43
|
+
/** A reading that passed its planted pair on one PinnedLinter. Only `prove` makes one. */
|
|
44
|
+
class ProvedReading {
|
|
45
|
+
pinned;
|
|
46
|
+
reading;
|
|
47
|
+
/** @internal */
|
|
48
|
+
constructor(pinned, reading) {
|
|
49
|
+
this.pinned = pinned;
|
|
50
|
+
this.reading = reading;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
exports.ProvedReading = ProvedReading;
|
|
54
|
+
const CONFIG_LOAD = "config-load";
|
|
55
|
+
const tail = (text) => text.trim().split("\n").slice(-5).join("\n");
|
|
56
|
+
const notInstalled = (stage, reason) => ({ kind: "not-installed", stage, reason });
|
|
57
|
+
const notRun = (stage, reason) => ({
|
|
58
|
+
kind: "not-run",
|
|
59
|
+
stage,
|
|
60
|
+
reason,
|
|
61
|
+
});
|
|
62
|
+
/** An ExecResult that is not a clean exit, as why nothing was installed. */
|
|
63
|
+
function installFailure(command, r) {
|
|
64
|
+
if (r.kind === "timeout")
|
|
65
|
+
return notInstalled("timeout", `${command} ran past its time limit`);
|
|
66
|
+
if (r.kind === "spawn-error")
|
|
67
|
+
return notInstalled("install", `${command} could not start: ${r.message}`);
|
|
68
|
+
if (r.kind === "killed")
|
|
69
|
+
return notInstalled("install", `${command} was killed by ${r.signal}`);
|
|
70
|
+
return r.code === 0
|
|
71
|
+
? null
|
|
72
|
+
: notInstalled("install", `${command} exited ${String(r.code)}: ${tail(r.stderr)}`);
|
|
73
|
+
}
|
|
74
|
+
/** A lint call's stdout, or why there is no report to read. */
|
|
75
|
+
function outputOf(r, reportCodes) {
|
|
76
|
+
if (r.kind === "timeout")
|
|
77
|
+
return notRun("timeout", "the linter ran past its time limit");
|
|
78
|
+
if (r.kind === "spawn-error")
|
|
79
|
+
return notRun(CONFIG_LOAD, `the linter could not start: ${r.message}`);
|
|
80
|
+
if (r.kind === "killed")
|
|
81
|
+
return notRun(CONFIG_LOAD, `the linter was killed by ${r.signal}`);
|
|
82
|
+
if (!reportCodes.includes(r.code))
|
|
83
|
+
return notRun(CONFIG_LOAD, tail(`${r.stderr}\n${r.stdout}`));
|
|
84
|
+
return { kind: "output", stdout: r.stdout };
|
|
85
|
+
}
|
|
86
|
+
const fromParse = (parse) => parse.kind === "unreadable"
|
|
87
|
+
? notRun(CONFIG_LOAD, parse.reason)
|
|
88
|
+
: { kind: "files", files: parse.files };
|
|
89
|
+
/** Files per lint call, so a large repository never meets the argv limit. */
|
|
90
|
+
const CHUNK = 200;
|
|
91
|
+
/** `a/b/c.js` → `["a", "a/b"]`. */
|
|
92
|
+
const ancestorsOf = (path) => path
|
|
93
|
+
.split("/")
|
|
94
|
+
.slice(0, -1)
|
|
95
|
+
.map((_, i, parts) => parts.slice(0, i + 1).join("/"));
|
|
96
|
+
const settle = (o) => ({
|
|
97
|
+
installTimeoutMs: 600_000,
|
|
98
|
+
lintTimeoutMs: 150_000,
|
|
99
|
+
...o,
|
|
100
|
+
});
|
|
101
|
+
/** HOME and the shared caches under `cacheDir`, plus the kit's own tools' caches. */
|
|
102
|
+
function envFor(kit, cacheDir) {
|
|
103
|
+
return {
|
|
104
|
+
HOME: node_path_1.posix.join(cacheDir, "home"),
|
|
105
|
+
XDG_CACHE_HOME: node_path_1.posix.join(cacheDir, "xdg"),
|
|
106
|
+
CI: "1",
|
|
107
|
+
...kit.env(cacheDir),
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
function install(host, kit, dir, o) {
|
|
111
|
+
const plan = kit.plan({
|
|
112
|
+
names: host.list(dir),
|
|
113
|
+
read: (name) => host.read((0, node_path_1.join)(dir, name)),
|
|
114
|
+
});
|
|
115
|
+
if (plan.kind === "none")
|
|
116
|
+
return notInstalled(plan.stage, plan.reason);
|
|
117
|
+
const [command, ...args] = plan.install;
|
|
118
|
+
const env = envFor(kit, o.cacheDir);
|
|
119
|
+
const failed = installFailure(command, host.exec(command, args, { cwd: dir, env, timeoutMs: o.installTimeoutMs }));
|
|
120
|
+
if (failed !== null)
|
|
121
|
+
return failed;
|
|
122
|
+
const version = plan.version((path) => host.read((0, node_path_1.join)(dir, path)));
|
|
123
|
+
if (version === null)
|
|
124
|
+
return notInstalled("no-linter", plan.missing);
|
|
125
|
+
const run = { kit, command: plan.command(dir), options: o };
|
|
126
|
+
return {
|
|
127
|
+
kind: "installed",
|
|
128
|
+
linter: new PinnedLinter(kit.linter, version, dir, run),
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
/** Lint `files` (relative paths) with one reading on its pinned linter. */
|
|
132
|
+
function lint(host, pinned, reading, files) {
|
|
133
|
+
const { kit, command, options } = pinned.run;
|
|
134
|
+
const places = { dir: pinned.dir, cacheDir: options.cacheDir };
|
|
135
|
+
const call = kit.invocation(reading, files, places);
|
|
136
|
+
// A repository file at the scratch path is never overwritten, nor deleted.
|
|
137
|
+
if (host.exists(call.configPath))
|
|
138
|
+
return notRun("scratch-path-taken", `${(0, node_path_1.relative)(pinned.dir, call.configPath)} already exists in the repository`);
|
|
139
|
+
host.write(call.configPath, call.configText);
|
|
140
|
+
try {
|
|
141
|
+
const [bin = "", ...prefix] = command;
|
|
142
|
+
const result = host.exec(bin, [...prefix, ...call.args], {
|
|
143
|
+
cwd: pinned.dir,
|
|
144
|
+
env: envFor(kit, options.cacheDir),
|
|
145
|
+
timeoutMs: options.lintTimeoutMs,
|
|
146
|
+
});
|
|
147
|
+
const out = outputOf(result, kit.reportCodes);
|
|
148
|
+
if (out.kind === "not-run")
|
|
149
|
+
return out;
|
|
150
|
+
return fromParse(kit.parse(out.stdout, files, reading, pinned.dir));
|
|
151
|
+
}
|
|
152
|
+
finally {
|
|
153
|
+
host.remove(call.configPath);
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
/** Write a planted file; return what to remove: the topmost directory it created, or itself. */
|
|
157
|
+
function plant(host, dir, file) {
|
|
158
|
+
const missing = ancestorsOf(file.path)
|
|
159
|
+
.map((a) => (0, node_path_1.join)(dir, a))
|
|
160
|
+
.find((a) => !host.exists(a));
|
|
161
|
+
host.write((0, node_path_1.join)(dir, file.path), file.text);
|
|
162
|
+
return missing ?? (0, node_path_1.join)(dir, file.path);
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Plant the files one by one, recording each write that happened, so a write
|
|
166
|
+
* that fails part-way (a path component is a file) still leaves a list of what
|
|
167
|
+
* to remove.
|
|
168
|
+
*/
|
|
169
|
+
function plantAll(host, dir, files) {
|
|
170
|
+
return files.reduce((done, file) => {
|
|
171
|
+
if (done.failed !== null)
|
|
172
|
+
return done;
|
|
173
|
+
try {
|
|
174
|
+
return {
|
|
175
|
+
created: [...done.created, plant(host, dir, file)],
|
|
176
|
+
failed: null,
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
catch (error) {
|
|
180
|
+
return {
|
|
181
|
+
created: done.created,
|
|
182
|
+
failed: notRun("pair-path-taken", `${file.path} cannot be written: ${String(error)}`),
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
}, { created: [], failed: null });
|
|
186
|
+
}
|
|
187
|
+
/** Why a pair may not be planted at all. */
|
|
188
|
+
function blocked(host, dir, reading, pair) {
|
|
189
|
+
const planted = [pair.bad, pair.good];
|
|
190
|
+
const outside = planted.find((f) => !(0, pair_js_1.inScope)(f.path, reading.scope));
|
|
191
|
+
if (outside !== undefined)
|
|
192
|
+
return notRun("pair-outside-scope", `${outside.path} is not in the reading's scope`);
|
|
193
|
+
const taken = planted.find((f) => host.exists((0, node_path_1.join)(dir, f.path)));
|
|
194
|
+
return taken === undefined
|
|
195
|
+
? null
|
|
196
|
+
: notRun("pair-path-taken", `${taken.path} already exists in the repository`);
|
|
197
|
+
}
|
|
198
|
+
/** The pair's two reports, or which planted file the linter said nothing about. */
|
|
199
|
+
function pairReports(run, pair) {
|
|
200
|
+
if (run.kind === "not-run")
|
|
201
|
+
return run;
|
|
202
|
+
const reportOf = (f) => run.files.find((r) => r.path === f.path);
|
|
203
|
+
const nothingFor = (f) => notRun(CONFIG_LOAD, `the linter reported nothing for ${f.path}`);
|
|
204
|
+
const bad = reportOf(pair.bad);
|
|
205
|
+
if (bad === undefined)
|
|
206
|
+
return nothingFor(pair.bad);
|
|
207
|
+
const good = reportOf(pair.good);
|
|
208
|
+
return good === undefined ? nothingFor(pair.good) : [bad, good];
|
|
209
|
+
}
|
|
210
|
+
const isPair = (r) => Array.isArray(r);
|
|
211
|
+
function prove(host, pinned, reading, pair) {
|
|
212
|
+
const stop = blocked(host, pinned.dir, reading, pair);
|
|
213
|
+
if (stop !== null)
|
|
214
|
+
return stop;
|
|
215
|
+
// The proof runs on a snapshot: a caller's object changed after this call
|
|
216
|
+
// cannot change the reading that passed.
|
|
217
|
+
const frozen = structuredClone(reading);
|
|
218
|
+
const planted = plantAll(host, pinned.dir, [pair.bad, pair.good]);
|
|
219
|
+
try {
|
|
220
|
+
if (planted.failed !== null)
|
|
221
|
+
return planted.failed;
|
|
222
|
+
const paths = [pair.bad.path, pair.good.path];
|
|
223
|
+
const reports = pairReports(lint(host, pinned, frozen, paths), pair);
|
|
224
|
+
if (!isPair(reports))
|
|
225
|
+
return reports;
|
|
226
|
+
const judged = (0, pair_js_1.judgePair)(...reports);
|
|
227
|
+
return judged.kind === "proved"
|
|
228
|
+
? { kind: "proved", reading: new ProvedReading(pinned, frozen) }
|
|
229
|
+
: judged;
|
|
230
|
+
}
|
|
231
|
+
finally {
|
|
232
|
+
planted.created.forEach((p) => {
|
|
233
|
+
host.remove(p);
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
function flagged(host, proved) {
|
|
238
|
+
const { pinned, reading } = proved;
|
|
239
|
+
const files = host
|
|
240
|
+
.files(pinned.dir, reading.scope.files)
|
|
241
|
+
.filter((p) => (0, pair_js_1.inScope)(p, reading.scope))
|
|
242
|
+
.sort((a, b) => a.localeCompare(b));
|
|
243
|
+
const chunks = Array.from({ length: Math.ceil(files.length / CHUNK) }, (_, i) => files.slice(i * CHUNK, (i + 1) * CHUNK));
|
|
244
|
+
const results = chunks.map((chunk) => lint(host, pinned, reading, chunk));
|
|
245
|
+
const stopped = results.find((r) => r.kind === "not-run");
|
|
246
|
+
const reports = results.flatMap((r) => (r.kind === "files" ? r.files : []));
|
|
247
|
+
return stopped ?? { kind: "ran", ...(0, pair_js_1.summarize)(reports) };
|
|
248
|
+
}
|
|
249
|
+
/** The three steps over one host and one kit set. */
|
|
250
|
+
function ruleProofWith(host, kits) {
|
|
251
|
+
return {
|
|
252
|
+
install: (linter, dir, options) => install(host, kits[linter], dir, settle(options)),
|
|
253
|
+
prove: (pinned,
|
|
254
|
+
// The reading's type comes from the pinned linter, never the other way:
|
|
255
|
+
// a reading of another linter is a type error here.
|
|
256
|
+
reading, pair) => prove(host, pinned, reading, pair),
|
|
257
|
+
flagged: (proved) => flagged(host, proved),
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
//# sourceMappingURL=run.js.map
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The vocabulary of `experimental_ruleProof`, shared by the steps, the port and
|
|
3
|
+
* every linter kit. It names no linter: a kit adds its own reading fields on top
|
|
4
|
+
* of {@link BaseReading}.
|
|
5
|
+
*
|
|
6
|
+
* Two lessons from hand-written copies of this, kept as types rather than notes:
|
|
7
|
+
* a config that did not load printed nothing and was scored "no diagnostic", so
|
|
8
|
+
* an unreadable report is its own case and never an empty list; and a file that
|
|
9
|
+
* did not parse is not a clean file, so a per-file report has three kinds.
|
|
10
|
+
*/
|
|
11
|
+
/** Where a reading applies, as patterns relative to the repository root. */
|
|
12
|
+
export interface ReadingScope {
|
|
13
|
+
readonly files: readonly string[];
|
|
14
|
+
readonly ignores: readonly string[];
|
|
15
|
+
}
|
|
16
|
+
/** What every reading has. A kit's reading adds the linter's own options. */
|
|
17
|
+
export interface BaseReading {
|
|
18
|
+
/** The kit's name, as the kit set is keyed. */
|
|
19
|
+
readonly linter: string;
|
|
20
|
+
/** The rule as the linter spells it. */
|
|
21
|
+
readonly rule: string;
|
|
22
|
+
readonly scope: ReadingScope;
|
|
23
|
+
}
|
|
24
|
+
/** What one lint run said about one file. */
|
|
25
|
+
export type FileReport = {
|
|
26
|
+
readonly path: string;
|
|
27
|
+
readonly kind: "linted";
|
|
28
|
+
readonly hits: number;
|
|
29
|
+
} | {
|
|
30
|
+
readonly path: string;
|
|
31
|
+
readonly kind: "parse-error";
|
|
32
|
+
readonly message: string;
|
|
33
|
+
} | {
|
|
34
|
+
readonly path: string;
|
|
35
|
+
readonly kind: "ignored";
|
|
36
|
+
};
|
|
37
|
+
/** A linter's output read as per-file facts, or why it could not be. */
|
|
38
|
+
export type LintParse = {
|
|
39
|
+
readonly kind: "parsed";
|
|
40
|
+
readonly files: readonly FileReport[];
|
|
41
|
+
} | {
|
|
42
|
+
readonly kind: "unreadable";
|
|
43
|
+
readonly reason: string;
|
|
44
|
+
};
|
|
45
|
+
/** Why a reading or a run produced no verdict. */
|
|
46
|
+
export type NotRunStage = "pair-outside-scope" | "pair-path-taken" | "scratch-path-taken" | "pair-ignored" | "parse" | "config-load" | "timeout";
|
|
47
|
+
/** No verdict, and why. */
|
|
48
|
+
export interface NotRun {
|
|
49
|
+
readonly kind: "not-run";
|
|
50
|
+
readonly stage: NotRunStage;
|
|
51
|
+
readonly reason: string;
|
|
52
|
+
}
|
|
53
|
+
/** The verdict on a planted pair, before the proved reading is bound to its linter. */
|
|
54
|
+
export type PairVerdict = {
|
|
55
|
+
readonly kind: "proved";
|
|
56
|
+
} | {
|
|
57
|
+
readonly kind: "not-proved";
|
|
58
|
+
readonly badHits: number;
|
|
59
|
+
readonly goodHits: number;
|
|
60
|
+
} | NotRun;
|
|
61
|
+
/** Why there is no pinned linter. */
|
|
62
|
+
export interface NotInstalled {
|
|
63
|
+
readonly kind: "not-installed";
|
|
64
|
+
readonly stage: "no-lockfile" | "no-pin" | "install" | "timeout" | "no-linter";
|
|
65
|
+
readonly reason: string;
|
|
66
|
+
}
|
|
67
|
+
/** A file planted for the proof: a path relative to the repository and its text. */
|
|
68
|
+
export interface PlantedFile {
|
|
69
|
+
readonly path: string;
|
|
70
|
+
readonly text: string;
|
|
71
|
+
}
|
|
72
|
+
/** The violation and its twin. Both are required: one direction proves nothing. */
|
|
73
|
+
export interface PlantedPair {
|
|
74
|
+
readonly bad: PlantedFile;
|
|
75
|
+
readonly good: PlantedFile;
|
|
76
|
+
}
|
|
77
|
+
/** The repository files a proved reading flags, and the ones it could not judge. */
|
|
78
|
+
export interface Flagged {
|
|
79
|
+
/** Files the linter parsed, flagged or not. */
|
|
80
|
+
readonly linted: number;
|
|
81
|
+
readonly flagged: readonly string[];
|
|
82
|
+
readonly parseErrors: readonly string[];
|
|
83
|
+
readonly ignored: readonly string[];
|
|
84
|
+
}
|
|
85
|
+
/** What a proved reading flags in the repository. */
|
|
86
|
+
export type FlaggedRun = ({
|
|
87
|
+
readonly kind: "ran";
|
|
88
|
+
} & Flagged) | NotRun;
|
|
89
|
+
/** Where install keeps every cache, and how long each step may take. */
|
|
90
|
+
export interface InstallOptions {
|
|
91
|
+
/** A directory the caller owns; HOME and every package-manager cache go here. */
|
|
92
|
+
readonly cacheDir: string;
|
|
93
|
+
/** Default 600 s. */
|
|
94
|
+
readonly installTimeoutMs?: number;
|
|
95
|
+
/** Per lint call, default 150 s. */
|
|
96
|
+
readonly lintTimeoutMs?: number;
|
|
97
|
+
}
|
|
98
|
+
/** What a command did. A timeout and a binary that never started are not exit codes. */
|
|
99
|
+
export type ExecResult = {
|
|
100
|
+
readonly kind: "exited";
|
|
101
|
+
readonly code: number;
|
|
102
|
+
readonly stdout: string;
|
|
103
|
+
readonly stderr: string;
|
|
104
|
+
} | {
|
|
105
|
+
readonly kind: "timeout";
|
|
106
|
+
} | {
|
|
107
|
+
readonly kind: "killed";
|
|
108
|
+
readonly signal: string;
|
|
109
|
+
} | {
|
|
110
|
+
readonly kind: "spawn-error";
|
|
111
|
+
readonly message: string;
|
|
112
|
+
};
|
|
113
|
+
/** Options for one command. `env` is added to the inherited environment. */
|
|
114
|
+
export interface ExecOptions {
|
|
115
|
+
readonly cwd: string;
|
|
116
|
+
readonly env: Readonly<Record<string, string>>;
|
|
117
|
+
readonly timeoutMs: number;
|
|
118
|
+
}
|
|
119
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The vocabulary of `experimental_ruleProof`, shared by the steps, the port and
|
|
4
|
+
* every linter kit. It names no linter: a kit adds its own reading fields on top
|
|
5
|
+
* of {@link BaseReading}.
|
|
6
|
+
*
|
|
7
|
+
* Two lessons from hand-written copies of this, kept as types rather than notes:
|
|
8
|
+
* a config that did not load printed nothing and was scored "no diagnostic", so
|
|
9
|
+
* an unreadable report is its own case and never an empty list; and a file that
|
|
10
|
+
* did not parse is not a clean file, so a per-file report has three kinds.
|
|
11
|
+
*/
|
|
12
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
13
|
+
//# sourceMappingURL=types.js.map
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @experimental Prove a linter configuration fires on a planted pair, then list
|
|
3
|
+
* the repository files it flags — ESLint and Ruff. `install` → `prove` →
|
|
4
|
+
* `flagged`, each taking only what the step before returns. See
|
|
5
|
+
* `docs/rule-proof.md`.
|
|
6
|
+
*/
|
|
7
|
+
export declare const experimental_ruleProof: {
|
|
8
|
+
install: <N extends "eslint" | "ruff">(linter: N, dir: string, options: import("../core/rule-proof/types.js").InstallOptions) => import("../core/rule-proof/run.js").Installed<{
|
|
9
|
+
eslint: import("../core/rule-proof/kits/eslint.js").EslintReading;
|
|
10
|
+
ruff: import("../core/rule-proof/kits/ruff.js").RuffReading;
|
|
11
|
+
}[N]>;
|
|
12
|
+
prove: <R extends import("../core/rule-proof/types.js").BaseReading>(pinned: import("../core/rule-proof/run.js").PinnedLinter<R>, reading: NoInfer<R>, pair: import("../core/rule-proof/types.js").PlantedPair) => import("../core/rule-proof/run.js").Proof<R>;
|
|
13
|
+
flagged: <R extends import("../core/rule-proof/types.js").BaseReading>(proved: import("../core/rule-proof/run.js").ProvedReading<R>) => import("../core/rule-proof/types.js").FlaggedRun;
|
|
14
|
+
};
|
|
15
|
+
export type { EslintReading, RuffReading, } from "../core/rule-proof/kits/index.js";
|
|
16
|
+
export type { KitSet, Installed, PinnedLinter, Proof, ProvedReading, } from "../core/rule-proof/run.js";
|
|
17
|
+
export type { BaseReading, FlaggedRun, Flagged, InstallOptions, NotInstalled, NotRun, NotRunStage, PlantedFile, PlantedPair, ReadingScope, } from "../core/rule-proof/types.js";
|
|
18
|
+
//# sourceMappingURL=rule-proof.d.ts.map
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.experimental_ruleProof = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* `vigiles/rule-proof` — a package entry, and so a COMPOSITION ROOT: the one
|
|
6
|
+
* file that puts the steps (core), the kit set (core) and the machine (host
|
|
7
|
+
* adapter) together. Nothing else in rule-proof imports both sides.
|
|
8
|
+
*
|
|
9
|
+
* It installs and runs ANOTHER repository's linter and plugins. Install scripts
|
|
10
|
+
* are off, but linting loads plugin code, so this is an explicit call meant for
|
|
11
|
+
* a throwaway runner (CI), and nothing in `audit` or `lint` reaches it.
|
|
12
|
+
*/
|
|
13
|
+
const index_js_1 = require("../core/rule-proof/kits/index.js");
|
|
14
|
+
const run_js_1 = require("../core/rule-proof/run.js");
|
|
15
|
+
const rule_proof_io_js_1 = require("../host/rule-proof.io.js");
|
|
16
|
+
/**
|
|
17
|
+
* @experimental Prove a linter configuration fires on a planted pair, then list
|
|
18
|
+
* the repository files it flags — ESLint and Ruff. `install` → `prove` →
|
|
19
|
+
* `flagged`, each taking only what the step before returns. See
|
|
20
|
+
* `docs/rule-proof.md`.
|
|
21
|
+
*/
|
|
22
|
+
exports.experimental_ruleProof = (0, run_js_1.ruleProofWith)(rule_proof_io_js_1.nodeHost, index_js_1.PROOF_KITS);
|
|
23
|
+
//# sourceMappingURL=rule-proof.js.map
|