@antelopejs/tooling-configs 0.2.10 → 0.2.12

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.
@@ -0,0 +1,262 @@
1
+ //#region src/garden/json.d.ts
2
+ type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
3
+ interface JsonObject {
4
+ [key: string]: JsonValue;
5
+ }
6
+ //#endregion
7
+ //#region src/verify/types.d.ts
8
+ /** A kind of one-way door, the closed list of Upd4ting/outer-loop#42. */
9
+ type DoorKind = "data" | "format" | "contract" | "outbound" | "exposure" | "publish";
10
+ /** Path rules for one door kind: the globs, the declared funnel modules and the journeys that contain it. */
11
+ interface DoorRule {
12
+ /** Repository paths whose change opens a door of this kind, on top of the pack's defaults for the repo kind. */
13
+ globs: string[];
14
+ /** The only modules allowed to make this kind's calls (outbound clients, raw deletes); also path rules. */
15
+ funnels: string[];
16
+ /** Journeys, as `feature/journey`, whose pass contains a Data or Format door of this kind. */
17
+ containments: string[];
18
+ /** Why these paths are doors in this repository. */
19
+ why: string;
20
+ }
21
+ /** Every door kind with its rule, or `null` when the kind cannot apply to the repository. */
22
+ type DoorRules = { [Kind in DoorKind]: DoorRule | null; };
23
+ /** A formal check, the source files it covers, the command that runs it and how its output names a violated rule. */
24
+ interface FormalCheck {
25
+ name: string;
26
+ covers: string[];
27
+ command: string[];
28
+ violation: RegExp | null;
29
+ }
30
+ /** A backing service the harness runs in Docker for every run, published on a free loopback port. */
31
+ interface ServiceDefinition {
32
+ image: string;
33
+ /** The port the service listens on inside its container. */
34
+ port: number;
35
+ env?: {
36
+ [name: string]: string;
37
+ };
38
+ /** Runs inside the container until it exits 0: the readiness probe. */
39
+ ready: string[];
40
+ /** Runs inside the container before each journey, so every journey starts from a clean state. */
41
+ reset?: string[];
42
+ }
43
+ /** Where a running service answers from the host. */
44
+ interface ServiceEndpoint {
45
+ name: string;
46
+ container: string;
47
+ host: string;
48
+ port: number;
49
+ }
50
+ /** One expectation a step met or missed, with what was observed. */
51
+ interface Check {
52
+ name: string;
53
+ pass: boolean;
54
+ detail: string;
55
+ }
56
+ /** What one driven command produced, read back from its evidence folder. */
57
+ interface CommandResult {
58
+ folder: string;
59
+ command: string;
60
+ exitCode: number | null;
61
+ signal: string | null;
62
+ stdout: string;
63
+ stderr: string;
64
+ }
65
+ /** The answer of an HTTP request, or the network error when nothing answered. */
66
+ interface HttpResult {
67
+ folder: string;
68
+ url: string;
69
+ status: number | null;
70
+ body: string;
71
+ json: JsonValue | undefined;
72
+ error: string | null;
73
+ }
74
+ /** The tree a step recorded: its folder and every path with its size. */
75
+ interface TreeRecord {
76
+ folder: string;
77
+ lines: string[];
78
+ }
79
+ /** Options of `ajs project dev`: extra environment and extra flags such as `--watch`. */
80
+ interface DevOptions {
81
+ env?: {
82
+ [name: string]: string;
83
+ };
84
+ args?: string[];
85
+ }
86
+ /** Options of a driven command. */
87
+ interface DriveOptions {
88
+ cwd?: string;
89
+ env?: {
90
+ [name: string]: string;
91
+ };
92
+ timeoutMs?: number;
93
+ }
94
+ /** A request to the driver module: call an interface member through core, then chain methods on the awaited result. */
95
+ interface CallRequest {
96
+ /** The interface package; defaults to the interface under verification, or the module's only implemented interface. */
97
+ interface?: string;
98
+ /** The export subpath, `.` by default. */
99
+ entry?: string;
100
+ /** The member path inside the entry, for example `["GetClient"]`. */
101
+ path: string[];
102
+ args?: JsonValue[];
103
+ /** Methods called in turn on the awaited result, each `[method, ...args]`. */
104
+ chain?: JsonValue[][];
105
+ }
106
+ /** What the driver answered: the awaited value, or the error the call threw. */
107
+ interface CallResult extends HttpResult {
108
+ ok: boolean;
109
+ value: JsonValue | undefined;
110
+ }
111
+ /** A running `ajs project dev` and the ports it answers on. */
112
+ interface App {
113
+ name: string;
114
+ pid: number;
115
+ folder: string;
116
+ project: string;
117
+ /** The driver module's port in a fixture project, or the port given to a scaffolded project. */
118
+ port: number;
119
+ }
120
+ /** How a stopped app ended, with its output. */
121
+ interface StopResult {
122
+ folder: string;
123
+ exitCode: number | null;
124
+ signal: string | null;
125
+ stdout: string;
126
+ stderr: string;
127
+ }
128
+ /** The API a journey drives the product through. Every call records its evidence in a numbered step folder. */
129
+ interface JourneyContext {
130
+ /** The repository under verification. */
131
+ readonly repo: string;
132
+ /** The journey's scratch folder, removed by `clean`. */
133
+ readonly work: string;
134
+ /** The journey's own HOME. */
135
+ readonly home: string;
136
+ command(name: string, program: string, args: string[], options?: DriveOptions): Promise<CommandResult>;
137
+ edit(name: string, file: string, content: string): string;
138
+ tree(name: string, root: string): TreeRecord;
139
+ http(name: string, url: string, init?: {
140
+ method?: string;
141
+ body?: string;
142
+ }): Promise<HttpResult>;
143
+ /** Records the checks of a step. A failing `critical` step ends the journey. */
144
+ expect(folder: string, checks: Check[], options?: {
145
+ critical?: boolean;
146
+ }): boolean;
147
+ /** Ends the journey as not verified, for example when provider sandbox keys are missing. */
148
+ notVerified(reason: string): never;
149
+ service(name: string): ServiceEndpoint;
150
+ /** Runs a command inside a service's container: the read-back through the native client. */
151
+ native(name: string, service: string, args: string[]): Promise<CommandResult>;
152
+ /** Writes the fixture project of the interface or module kind and returns its folder. */
153
+ fixture(options?: {
154
+ moduleConfig?: JsonObject;
155
+ }): string;
156
+ /** Starts `ajs project dev` in a project and waits until it is ready. */
157
+ dev(name: string, project: string, options?: DevOptions): Promise<App>;
158
+ call(name: string, app: App, request: CallRequest): Promise<CallResult>;
159
+ /** Stops an app with SIGINT by recorded PID. */
160
+ stop(name: string, app: App): Promise<StopResult>;
161
+ /** Creates a project from the template under verification with `ajs project init`. */
162
+ scaffold(name: string, project: string, flags?: string[]): Promise<CommandResult>;
163
+ }
164
+ /** A repo-owned journey of `verify.config.ts`, named by id in a feature file. */
165
+ interface Journey {
166
+ title: string;
167
+ entryPoint: string;
168
+ run(context: JourneyContext): Promise<void>;
169
+ }
170
+ /** An exported function of an interface that is not a proxy, called through core by the driver module. */
171
+ interface InterfaceCall<Api> {
172
+ call(api: Api): Promise<JsonValue>;
173
+ /** The value the call must resolve to. */
174
+ expect: JsonValue;
175
+ }
176
+ /** Repo-owned hooks of the interface kind for contracts that are not interface proxies. */
177
+ interface InterfaceHooks<Api> {
178
+ /** Runs in the stub provider module after the generic stubs attach, for example to call `internal.SetClient`. */
179
+ provide?(api: Api): void | Promise<void>;
180
+ /** Plain exported functions, by path such as `.:GetClient`, called by the driver module. */
181
+ calls?: {
182
+ [path: string]: InterfaceCall<Api>;
183
+ };
184
+ /** Exported functions only a provider calls, by path, with why the consumer never calls them. */
185
+ providerSide?: {
186
+ [path: string]: string;
187
+ };
188
+ }
189
+ /** How the template kind knows the scaffolded project is up. */
190
+ interface TemplateProbe {
191
+ /** A path on the port the harness passes as `PORT`; the welcome page or endpoint. */
192
+ path?: string;
193
+ status?: number;
194
+ body?: RegExp;
195
+ /** A line of `ajs project dev` output that means ready, for a template with no HTTP endpoint. */
196
+ log?: RegExp;
197
+ /** How long the process must keep running after `log` matches, 3000 ms by default: core prints nothing once modules start. */
198
+ settleMs?: number;
199
+ }
200
+ /** The repo-owned layer of a shared verification skill: `.agents/skills/verify-<kind>/verify.config.ts`. */
201
+ interface VerifyConfig<Api = never> {
202
+ doors: DoorRules;
203
+ formal?: FormalCheck[];
204
+ /** Files whose change a user can observe; replaces the kind's default. */
205
+ userFacing?: string[];
206
+ services?: {
207
+ [name: string]: ServiceDefinition;
208
+ };
209
+ /** Extra environment for every driven command. */
210
+ env?: {
211
+ [name: string]: string;
212
+ };
213
+ /** Commands run in the repository by `new`, replacing the default build. */
214
+ setup?: string[][];
215
+ journeys?: {
216
+ [id: string]: Journey;
217
+ };
218
+ /** Provider sandbox keys read from the environment; without every one the run is not verified, never PASS. */
219
+ saas?: {
220
+ env: string[];
221
+ sandbox: string;
222
+ };
223
+ /** The module kind's configuration of the module under verification. */
224
+ moduleConfig?(services: ServiceEndpoint[]): JsonObject;
225
+ interface?: InterfaceHooks<Api>;
226
+ /** The template kind: its name in the offline manifest, whether it is a project template, and its readiness probe. */
227
+ template?: {
228
+ name?: string;
229
+ project?: boolean;
230
+ probe: TemplateProbe;
231
+ };
232
+ }
233
+ //#endregion
234
+ //#region src/verify/checks.d.ts
235
+ interface Exited {
236
+ exitCode: number | null;
237
+ }
238
+ /** The process exited with `code`. */
239
+ declare function exitIs(result: Exited, code: number): Check;
240
+ /** The process ended on SIGINT, by exit code 130 or by the signal itself. */
241
+ declare function interrupted(result: {
242
+ exitCode: number | null;
243
+ signal: string | null;
244
+ }): Check;
245
+ /** `text` matches `pattern`; `label` names the stream. */
246
+ declare function has(label: string, text: string, pattern: RegExp): Check;
247
+ /** `text` does not match `pattern`. */
248
+ declare function lacks(label: string, text: string, pattern: RegExp): Check;
249
+ /** A file or folder exists at `file`. */
250
+ declare function exists(file: string): Check;
251
+ /** The file at `file` matches `pattern`. */
252
+ declare function fileHas(file: string, pattern: RegExp): Check;
253
+ /** Two values are deeply equal once serialized. */
254
+ declare function equal(name: string, actual: JsonValue | undefined, expected: JsonValue): Check;
255
+ /** The request answered `status` (200 by default). */
256
+ declare function answered(result: HttpResult, status?: number): Check;
257
+ /** The request answered 200 with JSON whose `key` is `expected`. */
258
+ declare function answers(result: HttpResult, key: string, expected: JsonValue): Check;
259
+ /** Nothing answered the request. */
260
+ declare function refused(result: HttpResult): Check;
261
+ //#endregion
262
+ export { type App, type CallRequest, type CallResult, type Check, type CommandResult, type DevOptions, type DoorKind, type DoorRule, type DoorRules, type DriveOptions, type FormalCheck, type HttpResult, type InterfaceCall, type InterfaceHooks, type Journey, type JourneyContext, type ServiceDefinition, type ServiceEndpoint, type StopResult, type TemplateProbe, type VerifyConfig, answered, answers, equal, exists, exitIs, fileHas, has, interrupted, lacks, refused };
@@ -0,0 +1,2 @@
1
+ import { a as exitIs, c as interrupted, i as exists, l as lacks, n as answers, o as fileHas, r as equal, s as has, t as answered, u as refused } from "../checks-BlWDFYio.mjs";
2
+ export { answered, answers, equal, exists, exitIs, fileHas, has, interrupted, lacks, refused };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/tooling-configs",
3
- "version": "0.2.10",
3
+ "version": "0.2.12",
4
4
  "description": "Shared tooling presets for AntelopeJS repositories: oxlint (with the vendored anti-slop rules), oxfmt, ESLint for Nuxt layers, Knip, and an interface range check",
5
5
  "keywords": [
6
6
  "antelopejs",
@@ -29,7 +29,8 @@
29
29
  "antelopejs-garden": "./dist/bin/garden.mjs",
30
30
  "antelopejs-ratchet": "./dist/bin/ratchet.mjs",
31
31
  "antelopejs-suppressions": "./dist/bin/suppressions.mjs",
32
- "antelopejs-sync": "./dist/bin/sync.mjs"
32
+ "antelopejs-sync": "./dist/bin/sync.mjs",
33
+ "antelopejs-verify": "./dist/bin/verify.mjs"
33
34
  },
34
35
  "files": [
35
36
  "dist"
@@ -41,7 +42,8 @@
41
42
  "./oxc/anti-slop": "./dist/oxc/anti-slop/index.mjs",
42
43
  "./oxc/guardrails": "./dist/oxc/guardrails/index.mjs",
43
44
  "./knip": "./dist/knip.mjs",
44
- "./eslint": "./dist/eslint.mjs"
45
+ "./eslint": "./dist/eslint.mjs",
46
+ "./verify": "./dist/verify/index.mjs"
45
47
  },
46
48
  "publishConfig": {
47
49
  "access": "public",
@@ -1,119 +0,0 @@
1
- import { r as MEASURE_ENV, s as readCeilings } from "./ceilings-BSw9p4YB.mjs";
2
- import { n as renamedPaths } from "./renames-BGO4dWJ8.mjs";
3
- import { a as repositoryPath } from "./files-2FikHZ9F.mjs";
4
- import { createRequire } from "node:module";
5
- import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
6
- import { basename, dirname, join } from "node:path";
7
- import { execFileSync, spawnSync } from "node:child_process";
8
- //#region src/guardrails/oxlint.ts
9
- function resolveOxlint(root) {
10
- try {
11
- const require = createRequire(join(root, "package.json"));
12
- return join(dirname(require.resolve("oxlint/package.json")), "bin/oxlint");
13
- } catch {
14
- throw new Error("oxlint is not installed in this repository. Install dependencies first.");
15
- }
16
- }
17
- function ruleId(code) {
18
- const match = /^([^()]+)\(([^()]+)\)$/.exec(code);
19
- if (!match) throw new Error(`Cannot measure oxlint diagnostic code ${JSON.stringify(code)}. Fix parser or configuration errors before recording a baseline.`);
20
- const [, plugin, rule] = match;
21
- return `${plugin === "typescript-eslint" ? "typescript" : plugin}/${rule}`;
22
- }
23
- function parseDiagnostics(text, root) {
24
- const report = JSON.parse(text);
25
- if (!Array.isArray(report?.diagnostics)) throw new Error("oxlint did not return a JSON diagnostics array.");
26
- return report.diagnostics.map((item) => {
27
- const file = repositoryPath(root, item.filename);
28
- const span = item.labels?.[0]?.span;
29
- return {
30
- rule: ruleId(item.code),
31
- file,
32
- location: span ? `${file}:${span.line}:${span.column}` : file,
33
- message: item.message,
34
- line: span?.line,
35
- help: item.help
36
- };
37
- });
38
- }
39
- function lintDiagnostics(root, config, files) {
40
- const binary = resolveOxlint(root);
41
- const temporary = config === void 0 ? void 0 : mkdtempSync(join(root, ".antelopejs-measure.generated."));
42
- try {
43
- const args = [
44
- binary,
45
- "-f",
46
- "json"
47
- ];
48
- if (temporary) {
49
- const path = join(temporary, "oxlint.config.ts");
50
- writeFileSync(path, config ?? "");
51
- args.push("--config", path, "--ignore-pattern", `${basename(temporary)}/**`);
52
- }
53
- if (files) args.push("--no-error-on-unmatched-pattern", "--", ...files);
54
- const result = spawnSync(process.execPath, args, {
55
- cwd: root,
56
- encoding: "utf8",
57
- env: {
58
- ...process.env,
59
- [MEASURE_ENV]: "1"
60
- },
61
- maxBuffer: 67108864
62
- });
63
- if (result.error) throw result.error;
64
- if (result.status !== 0 && result.status !== 1) throw new Error(`oxlint failed (${result.status ?? result.signal}): ${result.stderr || result.stdout}`);
65
- const diagnostics = parseDiagnostics(result.stdout, root);
66
- if (result.status !== 0 && diagnostics.length === 0) throw new Error(`oxlint failed without diagnostics: ${result.stderr || result.stdout}`);
67
- return diagnostics;
68
- } finally {
69
- if (temporary) rmSync(temporary, {
70
- recursive: true,
71
- force: true
72
- });
73
- }
74
- }
75
- //#endregion
76
- //#region src/guardrails/staged-ratchet.ts
77
- /** The line ranges each staged file adds against HEAD, following renames. */
78
- function stagedAdditions(root, targets) {
79
- const renames = renamedPaths(root, true);
80
- const additions = /* @__PURE__ */ new Map();
81
- for (const file of targets) {
82
- const diff = execFileSync("git", [
83
- "diff",
84
- "--cached",
85
- "--no-ext-diff",
86
- "--no-color",
87
- "--unified=0",
88
- "--find-renames",
89
- "--",
90
- ...[renames.get(file), file].filter((path) => path !== void 0)
91
- ], {
92
- cwd: root,
93
- encoding: "utf8"
94
- });
95
- additions.set(file, Array.from(diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm), ([, line, count]) => ({
96
- start: Number(line),
97
- end: Number(line) + Number(count ?? 1) - 1
98
- })));
99
- }
100
- return additions;
101
- }
102
- function stagedRatchet(root, files) {
103
- const targets = files ?? execFileSync("git", [
104
- "diff",
105
- "--cached",
106
- "--name-only",
107
- "--diff-filter=ACMR",
108
- "-z"
109
- ], {
110
- cwd: root,
111
- encoding: "utf8"
112
- }).split("\0").filter(Boolean);
113
- if (!targets.length) return [];
114
- const additions = stagedAdditions(root, targets);
115
- const ceilings = readCeilings(root);
116
- return lintDiagnostics(root, void 0, targets).filter(({ rule, file, line }) => Object.hasOwn(ceilings.rules, rule) && line !== void 0 && additions.get(file)?.some(({ start, end }) => line >= start && line <= end)).map((diagnostic) => `${diagnostic.location}: ${diagnostic.message} [${diagnostic.rule}]\n Fix: ${diagnostic.help ?? "Resolve this finding on the added line; the ceiling covers only legacy findings on untouched lines."}`);
117
- }
118
- //#endregion
119
- export { stagedRatchet as n, lintDiagnostics as r, stagedAdditions as t };