@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,3000 @@
1
+ #!/usr/bin/env node
2
+ import { a as isString, f as parseJson, i as isObject, u as optStr } from "../json-BqvuCkqr.mjs";
3
+ import { a as exitIs, c as interrupted, i as exists, r as equal, u as refused } from "../checks-BlWDFYio.mjs";
4
+ import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
5
+ import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
6
+ import { a as skillFolder, i as isVerifyKind, t as VERIFY_KINDS } from "../kinds-Bzyyi9yk.mjs";
7
+ import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
8
+ import { basename, dirname, join, matchesGlob, relative, resolve, sep } from "node:path";
9
+ import { execFileSync, spawn, spawnSync } from "node:child_process";
10
+ import { parseArgs } from "node:util";
11
+ import { pathToFileURL } from "node:url";
12
+ import { homedir, tmpdir } from "node:os";
13
+ import { randomBytes } from "node:crypto";
14
+ import ts from "typescript";
15
+ import { createServer } from "node:net";
16
+ //#region src/verify/doors.ts
17
+ const RELEASE_FILES = [
18
+ "package.json",
19
+ ".release-it.json",
20
+ "changelogen.config.json",
21
+ ".github/workflows/release.yml"
22
+ ];
23
+ const DEFAULT_DOOR_GLOBS = {
24
+ interface: {
25
+ contract: ["src/**", "package.json"],
26
+ publish: RELEASE_FILES
27
+ },
28
+ module: {
29
+ contract: ["package.json"],
30
+ publish: RELEASE_FILES
31
+ },
32
+ template: {}
33
+ };
34
+ /** Every path rule of a door kind: the kind's defaults, the repo's globs and its declared funnels. */
35
+ function doorGlobs(workspace, kind) {
36
+ const rule = workspace.config.doors[kind];
37
+ if (!rule) return [];
38
+ return [.../* @__PURE__ */ new Set([
39
+ ...DEFAULT_DOOR_GLOBS[workspace.kind][kind] ?? [],
40
+ ...rule.globs,
41
+ ...rule.funnels
42
+ ])];
43
+ }
44
+ /** The door kinds whose path rules `files` hit. */
45
+ function flaggedDoors(workspace, files) {
46
+ return [
47
+ "data",
48
+ "format",
49
+ "contract",
50
+ "outbound",
51
+ "exposure",
52
+ "publish"
53
+ ].flatMap((kind) => {
54
+ const globs = doorGlobs(workspace, kind);
55
+ const hits = files.filter((file) => globs.some((glob) => matchesGlob(file, glob)));
56
+ return hits.length > 0 ? [{
57
+ kind,
58
+ files: hits
59
+ }] : [];
60
+ });
61
+ }
62
+ /** The files a unified diff changes, read from its `+++ b/` headers. */
63
+ function patchFiles(patch) {
64
+ return [...readFileSync(patch, "utf8").matchAll(/^\+\+\+ b\/(.+)$/gm)].map((match) => match[1]);
65
+ }
66
+ /** The `One-way-door:` line for flagged kinds, or nothing when none is flagged. */
67
+ function doorLine(doors) {
68
+ return doors.length > 0 ? `One-way-door: ${doors.map((door) => door.kind).join(", ")}` : "";
69
+ }
70
+ //#endregion
71
+ //#region src/verify/formal.ts
72
+ /** The formal checks of verify.config.ts whose covered files the change touches. */
73
+ function touchedFormalChecks(workspace, changed) {
74
+ return (workspace.config.formal ?? []).filter((check) => changed.some((file) => check.covers.includes(file)));
75
+ }
76
+ function violatedRules(check, exitCode, output) {
77
+ if (check.violation) return [...new Set([...output.matchAll(check.violation)].map((match) => match[1]))];
78
+ return exitCode === 0 ? [] : ["property"];
79
+ }
80
+ /** Runs one formal check from the repository root and records it under evidence/formal/<name>/. */
81
+ function runFormalCheck(workspace, state, check) {
82
+ const folder = join(state.evidence, "formal", check.name);
83
+ mkdirSync(folder, { recursive: true });
84
+ const [program, ...args] = check.command;
85
+ const run = spawnSync(program, args, {
86
+ cwd: workspace.root,
87
+ encoding: "utf8"
88
+ });
89
+ writeFileSync(join(folder, "command.txt"), `${check.command.join(" ")}\n`);
90
+ writeFileSync(join(folder, "stdout.txt"), run.stdout ?? "");
91
+ writeFileSync(join(folder, "stderr.txt"), `${run.stderr ?? ""}${run.error ? `\n${run.error.message}\n` : ""}`);
92
+ writeFileSync(join(folder, "exit-code.txt"), `${run.status}\n`);
93
+ const result = {
94
+ name: check.name,
95
+ exitCode: run.status,
96
+ violated: violatedRules(check, run.status, run.stdout ?? ""),
97
+ folder: relative(state.evidence, folder)
98
+ };
99
+ writeFileSync(join(folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
100
+ return result;
101
+ }
102
+ /** The recorded result of a formal check in a run, if it ran. */
103
+ function readFormalResult(state, name) {
104
+ const file = join(state.evidence, "formal", name, "result.json");
105
+ if (!existsSync(file)) return void 0;
106
+ return JSON.parse(readFileSync(file, "utf8"));
107
+ }
108
+ //#endregion
109
+ //#region src/verify/judgement.ts
110
+ const DOOR_KINDS = [
111
+ "data",
112
+ "format",
113
+ "contract",
114
+ "outbound",
115
+ "exposure",
116
+ "publish"
117
+ ];
118
+ function isDoorKind(value) {
119
+ return DOOR_KINDS.some((kind) => kind === value);
120
+ }
121
+ function text(source, key) {
122
+ const value = source[key];
123
+ return value !== void 0 && isString(value) ? value.trim() : "";
124
+ }
125
+ function texts(source, key) {
126
+ const value = source[key];
127
+ return Array.isArray(value) ? value.filter(isString) : [];
128
+ }
129
+ function objects(value) {
130
+ return Array.isArray(value) ? value.filter(isObject) : [];
131
+ }
132
+ function doorKind(value, label) {
133
+ if (!isDoorKind(value)) throw new Error(`judgement.json: ${label} is "${value}", not one of ${DOOR_KINDS.join(", ")}`);
134
+ return value;
135
+ }
136
+ function parseRows(doors) {
137
+ return objects(doors.rows).map((row, index) => {
138
+ const parsed = {
139
+ location: text(row, "location"),
140
+ irreversible: text(row, "irreversible"),
141
+ containment: text(row, "containment")
142
+ };
143
+ if (!parsed.location || !parsed.irreversible || !parsed.containment) throw new Error(`judgement.json: doors.rows[${index}] needs kind, location, irreversible and containment`);
144
+ return {
145
+ ...parsed,
146
+ kind: doorKind(text(row, "kind"), `doors.rows[${index}].kind`),
147
+ containmentJourney: text(row, "containmentJourney")
148
+ };
149
+ });
150
+ }
151
+ function parseFalsePositives(doors) {
152
+ return objects(doors.falsePositives).map((entry, index) => {
153
+ const location = text(entry, "location");
154
+ const reason = text(entry, "reason");
155
+ if (!location || !reason) throw new Error(`judgement.json: doors.falsePositives[${index}] needs location and reason`);
156
+ return {
157
+ kind: doorKind(text(entry, "kind"), `doors.falsePositives[${index}].kind`),
158
+ location,
159
+ reason
160
+ };
161
+ });
162
+ }
163
+ /** Parses evidence/judgement.json. A verdict without a One-way doors section is void, so a missing one throws. */
164
+ function readJudgement(file) {
165
+ if (!existsSync(file)) throw new Error(`${file} is missing: write the verifier's judgement before rendering the verdict`);
166
+ const raw = parseJson(readFileSync(file, "utf8"));
167
+ if (!isObject(raw)) throw new Error(`${file} must hold a JSON object`);
168
+ const doors = raw.doors !== void 0 && isObject(raw.doors) ? raw.doors : {};
169
+ const rows = parseRows(doors);
170
+ const none = text(doors, "none") || null;
171
+ if (!none && rows.length === 0) throw new Error("judgement.json: doors needs `none` with a reason or at least one row; a verdict without it is void");
172
+ const verifier = text(raw, "verifier");
173
+ if (!verifier) throw new Error("judgement.json: verifier must say who judged this run, for example the verifier thread's URL");
174
+ return {
175
+ notVerified: texts(raw, "notVerified"),
176
+ attention: texts(raw, "attention"),
177
+ docs: objects(raw.docs).map((entry) => ({
178
+ page: text(entry, "page"),
179
+ matches: entry.matches === true,
180
+ note: text(entry, "note")
181
+ })),
182
+ doorsNone: none,
183
+ doors: rows,
184
+ falsePositives: parseFalsePositives(doors),
185
+ verifier
186
+ };
187
+ }
188
+ //#endregion
189
+ //#region src/verify/workspace.ts
190
+ /**
191
+ * Caches shared by every run: the warm pnpm store, the npm cache and the
192
+ * published packages. Nothing a journey asserts on lives here.
193
+ */
194
+ const CACHE_DIR = join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "antelopejs-verify");
195
+ /** Runs git in `cwd` and returns its trimmed output. */
196
+ function git(cwd, args) {
197
+ return execFileSync("git", args, {
198
+ cwd,
199
+ encoding: "utf8",
200
+ stdio: [
201
+ "ignore",
202
+ "pipe",
203
+ "pipe"
204
+ ]
205
+ }).trim();
206
+ }
207
+ function readManifest$1(root) {
208
+ const file = join(root, "package.json");
209
+ const value = existsSync(file) ? parseJson(readFileSync(file, "utf8")) : {};
210
+ return isObject(value) ? value : {};
211
+ }
212
+ /** Opens the repository at `root` for `kind`, loading the repo-owned verify.config.ts. */
213
+ async function openWorkspace(root, kind) {
214
+ const skill = join(root, skillFolder(kind));
215
+ const file = join(skill, "verify.config.ts");
216
+ if (!existsSync(file)) throw new Error(`${file} is missing. Write the repo-owned layer (verify.config.ts and features/) described in ${skillFolder(kind)}/SKILL.md.`);
217
+ const config = (await import(pathToFileURL(file).href)).default;
218
+ if (config?.doors === void 0) throw new Error(`${file} must export default a VerifyConfig with a doors block.`);
219
+ const manifest = readManifest$1(root);
220
+ return {
221
+ root,
222
+ kind,
223
+ skill,
224
+ config,
225
+ manifest,
226
+ name: String(manifest.name ?? basename(root)).replace(/^@[^/]+\//, "").replace(/[^a-z0-9-]+/gi, "-")
227
+ };
228
+ }
229
+ function stateFile(dir) {
230
+ return join(dir, "run.json");
231
+ }
232
+ /** Reads a run created by `new`, failing with the reason when it is missing. */
233
+ function loadRun(dir) {
234
+ const file = stateFile(resolve(dir));
235
+ if (!existsSync(file)) throw new Error(`No run at ${dir}: run.json is missing. Create one with \`new\`.`);
236
+ return JSON.parse(readFileSync(file, "utf8"));
237
+ }
238
+ /** Persists the run state. */
239
+ function saveRun(state) {
240
+ writeFileSync(stateFile(state.dir), `${JSON.stringify(state, null, 2)}\n`);
241
+ }
242
+ /** Allocates the folders of a new run under the system temp folder. */
243
+ function allocateRun(workspace, baseRef, title) {
244
+ const id = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").slice(0, 15)}-${randomBytes(3).toString("hex")}`;
245
+ const dir = join(tmpdir(), "antelopejs-verify", workspace.name, id);
246
+ const evidence = join(dir, "evidence");
247
+ mkdirSync(evidence, { recursive: true });
248
+ return {
249
+ id,
250
+ kind: workspace.kind,
251
+ repo: workspace.root,
252
+ dir,
253
+ evidence,
254
+ createdAt: (/* @__PURE__ */ new Date()).toISOString(),
255
+ headSha: git(workspace.root, ["rev-parse", "HEAD"]),
256
+ baseRef,
257
+ title,
258
+ processes: [],
259
+ containers: [],
260
+ pack: "",
261
+ manifestUrl: "",
262
+ templateName: "",
263
+ missingKeys: (workspace.config.saas?.env ?? []).filter((key) => !process.env[key])
264
+ };
265
+ }
266
+ const INHERITED_PREFIXES = [
267
+ "ANTELOPEJS_",
268
+ "npm_",
269
+ "PNPM_",
270
+ "XDG_"
271
+ ];
272
+ /**
273
+ * The environment every driven command gets: the journey's HOME, CI=1, no
274
+ * update check, no colors and the shared caches. Variables that could leak
275
+ * the operator's own settings into the run are dropped.
276
+ */
277
+ function isolatedEnv(workspace, home, extra = {}) {
278
+ const kept = Object.entries(process.env).filter(([key]) => !INHERITED_PREFIXES.some((prefix) => key.startsWith(prefix)));
279
+ return {
280
+ ...Object.fromEntries(kept),
281
+ HOME: home,
282
+ USERPROFILE: home,
283
+ CI: "1",
284
+ AJS_NO_UPDATE_CHECK: "1",
285
+ NO_COLOR: "1",
286
+ COREPACK_HOME: process.env.COREPACK_HOME ?? join(homedir(), ".cache", "node", "corepack"),
287
+ COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
288
+ XDG_DATA_HOME: join(CACHE_DIR, "xdg-data"),
289
+ XDG_CACHE_HOME: join(home, ".cache"),
290
+ XDG_CONFIG_HOME: join(home, ".config"),
291
+ npm_config_cache: join(CACHE_DIR, "npm"),
292
+ npm_config_prefer_offline: "true",
293
+ GIT_CONFIG_NOSYSTEM: "1",
294
+ ...workspace.config.env,
295
+ ...extra
296
+ };
297
+ }
298
+ //#endregion
299
+ //#region src/verify/docker.ts
300
+ const READY_TIMEOUT_MS$1 = 9e4;
301
+ function docker(args) {
302
+ const run = spawnSync("docker", args, { encoding: "utf8" });
303
+ return {
304
+ status: run.status,
305
+ stdout: run.stdout ?? "",
306
+ stderr: `${run.stderr ?? ""}${run.error ? `${run.error.message}\n` : ""}`
307
+ };
308
+ }
309
+ function record(folder, args, result) {
310
+ mkdirSync(folder, { recursive: true });
311
+ writeFileSync(join(folder, "command.txt"), `docker ${args.join(" ")}\n`);
312
+ writeFileSync(join(folder, "stdout.txt"), result.stdout);
313
+ writeFileSync(join(folder, "stderr.txt"), result.stderr);
314
+ writeFileSync(join(folder, "exit-code.txt"), `${result.status}\n`);
315
+ }
316
+ function publishedPort(container, port) {
317
+ const mapping = docker([
318
+ "port",
319
+ container,
320
+ `${port}/tcp`
321
+ ]).stdout;
322
+ const match = /127\.0\.0\.1:(\d+)/.exec(mapping);
323
+ if (!match) throw new Error(`${container} does not publish ${port}: ${mapping}`);
324
+ return Number(match[1]);
325
+ }
326
+ function waitReady(container, ready, folder) {
327
+ const deadline = Date.now() + READY_TIMEOUT_MS$1;
328
+ let last = docker([
329
+ "exec",
330
+ container,
331
+ ...ready
332
+ ]);
333
+ while (last.status !== 0 && Date.now() < deadline) {
334
+ spawnSync("sleep", ["0.5"]);
335
+ last = docker([
336
+ "exec",
337
+ container,
338
+ ...ready
339
+ ]);
340
+ }
341
+ record(folder, [
342
+ "exec",
343
+ container,
344
+ ...ready
345
+ ], last);
346
+ if (last.status !== 0) throw new Error(`${container} was not ready within ${READY_TIMEOUT_MS$1} ms: ${last.stderr}`);
347
+ }
348
+ /**
349
+ * Starts every service of verify.config.ts in its own container, named
350
+ * `<prefix>-<repo>-<service>-<run id>`, publishes its port on a free
351
+ * loopback port chosen by Docker, and waits for its readiness command. Each
352
+ * container is recorded before it is probed, so `clean` removes it even when
353
+ * it never became ready.
354
+ */
355
+ function startServices(workspace, state, prefix) {
356
+ for (const [service, definition] of Object.entries(workspace.config.services ?? {})) {
357
+ const name = `${prefix}-${workspace.name}-${service}-${state.id}`.toLowerCase();
358
+ const env = Object.entries(definition.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
359
+ const args = [
360
+ "run",
361
+ "-d",
362
+ "--name",
363
+ name,
364
+ "-p",
365
+ `127.0.0.1::${definition.port}`,
366
+ ...env,
367
+ definition.image
368
+ ];
369
+ const folder = join(state.evidence, "services", service);
370
+ const started = docker(args);
371
+ record(join(folder, "01-run"), args, started);
372
+ if (started.status !== 0) throw new Error(`docker ${args.join(" ")} failed: ${started.stderr}`);
373
+ const container = {
374
+ service,
375
+ name,
376
+ host: "127.0.0.1",
377
+ port: 0
378
+ };
379
+ state.containers.push(container);
380
+ saveRun(state);
381
+ container.port = publishedPort(name, definition.port);
382
+ saveRun(state);
383
+ waitReady(name, definition.ready, join(folder, "02-ready"));
384
+ }
385
+ }
386
+ /** Whether a recorded container is running. */
387
+ function containerRunning(name) {
388
+ return docker([
389
+ "inspect",
390
+ "-f",
391
+ "{{.State.Running}}",
392
+ name
393
+ ]).stdout.trim() === "true";
394
+ }
395
+ /** Removes a container this run started, by its recorded name. */
396
+ function removeContainer(name) {
397
+ return docker([
398
+ "rm",
399
+ "-f",
400
+ "-v",
401
+ name
402
+ ]).status === 0;
403
+ }
404
+ //#endregion
405
+ //#region src/verify/fixture-modules.ts
406
+ const WALK = String.raw`
407
+ const fs = require("node:fs");
408
+ const { pathToFileURL } = require("node:url");
409
+
410
+ const entries = JSON.parse(process.env.VERIFY_ENTRIES || "{}");
411
+
412
+ function load(name, entry) {
413
+ return require(entry === "." ? name : name + "/" + entry.replace(/^\.\//, ""));
414
+ }
415
+
416
+ function isClass(value) {
417
+ return /^class[\s{]/.test(Function.prototype.toString.call(value));
418
+ }
419
+
420
+ function kindOf(value) {
421
+ if (typeof value === "function") {
422
+ if (value.proxy && typeof value.proxy.onCall === "function") return "async";
423
+ return isClass(value) ? "class" : "function";
424
+ }
425
+ if (!value || typeof value !== "object") return "value";
426
+ if (typeof value.onCall === "function" && typeof value.call === "function") return "async";
427
+ if (typeof value.onHandlers === "function" || typeof value.onRegister === "function") return "registering";
428
+ if (typeof value.emit === "function" && typeof value.register === "function") return "event";
429
+ const prototype = Object.getPrototypeOf(value);
430
+ return prototype === Object.prototype || prototype === null ? "namespace" : "value";
431
+ }
432
+
433
+ function walk(value, keys, visit) {
434
+ for (const key of Object.keys(value)) {
435
+ if (key === "__esModule") continue;
436
+ const member = value[key];
437
+ const kind = kindOf(member);
438
+ if (kind === "namespace") {
439
+ if (keys.length < 4) walk(member, [...keys, key], visit);
440
+ continue;
441
+ }
442
+ visit([...keys, key], kind, member);
443
+ }
444
+ }
445
+
446
+ async function loadHooks() {
447
+ if (!process.env.VERIFY_CONFIG) return {};
448
+ const config = (await import(pathToFileURL(process.env.VERIFY_CONFIG).href)).default;
449
+ return (config && config.interface) || {};
450
+ }
451
+ `;
452
+ /** The driver module: the consumer every fixture project loads, answering HTTP calls by calling interfaces through core. */
453
+ const DRIVER_SOURCE = String.raw`"use strict";
454
+ const http = require("node:http");
455
+ ${WALK}
456
+ const TIMEOUT_MS = 15000;
457
+ const interfaces = Object.keys(entries);
458
+ let server;
459
+ let hooks = {};
460
+
461
+ function settle(value) {
462
+ return Promise.race([
463
+ Promise.resolve(value),
464
+ new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error("did not settle within " + TIMEOUT_MS + " ms"), { name: "Timeout" })), TIMEOUT_MS).unref()),
465
+ ]);
466
+ }
467
+
468
+ function serializable(value) {
469
+ try {
470
+ return JSON.parse(JSON.stringify(value === undefined ? null : value));
471
+ } catch {
472
+ return { unserializable: String(value) };
473
+ }
474
+ }
475
+
476
+ function target(body) {
477
+ const name = body.interface || interfaces[0];
478
+ let owner;
479
+ let value = load(name, body.entry || ".");
480
+ for (const key of body.path) {
481
+ owner = value;
482
+ value = value[key];
483
+ }
484
+ return { owner, value };
485
+ }
486
+
487
+ function surface() {
488
+ const found = [];
489
+ for (const name of interfaces) {
490
+ for (const entry of entries[name]) {
491
+ walk(load(name, entry), [], (keys, kind) => found.push({ interface: name, entry, path: entry + ":" + keys.join("."), kind }));
492
+ }
493
+ }
494
+ return found;
495
+ }
496
+
497
+ async function call(body) {
498
+ const { owner, value: member } = target(body);
499
+ const args = body.args || [];
500
+ let value = await settle(kindOf(member) === "async" && typeof member !== "function" ? member.call(...args) : member.apply(owner, args));
501
+ for (const [method, ...rest] of body.chain || []) value = await settle(value[method](...rest));
502
+ return value;
503
+ }
504
+
505
+ async function registering(body) {
506
+ const { value: proxy } = target(body);
507
+ await settle(proxy.register("verify-registration", () => "verify-handler"));
508
+ await settle(proxy.unregister("verify-registration"));
509
+ return "registered and unregistered";
510
+ }
511
+
512
+ async function event(body) {
513
+ const { value: proxy } = target(body);
514
+ let received = null;
515
+ const handler = (...args) => {
516
+ received = args;
517
+ };
518
+ proxy.register(handler);
519
+ proxy.emit(...(body.args || []));
520
+ proxy.unregister(handler);
521
+ return received;
522
+ }
523
+
524
+ async function hook(body) {
525
+ const entry = body.path.slice(0, body.path.indexOf(":"));
526
+ const found = (hooks.calls || {})[body.path];
527
+ if (!found) throw new Error("verify.config.ts has no interface.calls hook for " + body.path);
528
+ return found.call(load(body.interface || interfaces[0], entry));
529
+ }
530
+
531
+ const ROUTES = { "/surface": async () => surface(), "/call": call, "/registering": registering, "/event": event, "/hook": hook };
532
+
533
+ async function answer(request) {
534
+ if (request.url === "/health") return { ok: true };
535
+ const route = ROUTES[request.url];
536
+ if (!route) return { ok: false, error: { name: "NotFound", message: request.url } };
537
+ let text = "";
538
+ for await (const chunk of request) text += chunk;
539
+ try {
540
+ return { ok: true, value: serializable(await route(text ? JSON.parse(text) : {})) };
541
+ } catch (error) {
542
+ return { ok: false, error: { name: (error && error.name) || "Error", message: String((error && error.message) || error) } };
543
+ }
544
+ }
545
+
546
+ exports.construct = function construct() {};
547
+ exports.start = async function start() {
548
+ hooks = await loadHooks();
549
+ server = http.createServer((request, response) => {
550
+ answer(request).then((result) => {
551
+ response.setHeader("content-type", "application/json");
552
+ response.end(JSON.stringify(result));
553
+ });
554
+ });
555
+ await new Promise((resolve) => server.listen(Number(process.env.VERIFY_DRIVER_PORT), "127.0.0.1", resolve));
556
+ };
557
+ exports.stop = function stop() {
558
+ if (server) server.close();
559
+ };
560
+ exports.destroy = function destroy() {};
561
+ `;
562
+ /** The stub provider module of the interface kind: implements every proxy of the interface through ImplementInterface and logs each call. */
563
+ const STUB_SOURCE = String.raw`"use strict";
564
+ const { ImplementInterface } = require("@antelopejs/interface-core");
565
+ ${WALK}
566
+ function note(path, args) {
567
+ fs.appendFileSync(process.env.VERIFY_CALL_LOG, JSON.stringify({ path, args }) + "\n");
568
+ }
569
+
570
+ function place(tree, keys, leaf) {
571
+ let node = tree;
572
+ for (const key of keys.slice(0, -1)) node = node[key] = node[key] || {};
573
+ node[keys[keys.length - 1]] = leaf;
574
+ }
575
+
576
+ function stubs(entry, api) {
577
+ const tree = {};
578
+ walk(api, [], (keys, kind) => {
579
+ const path = entry + ":" + keys.join(".");
580
+ if (kind === "async") place(tree, keys, (...args) => (note(path, args), { stub: path, args }));
581
+ if (kind === "registering")
582
+ place(tree, keys, { register: (id) => note(path + ".register", [id]), unregister: (id) => note(path + ".unregister", [id]) });
583
+ });
584
+ return tree;
585
+ }
586
+
587
+ exports.construct = async function construct() {
588
+ for (const [name, list] of Object.entries(entries)) {
589
+ for (const entry of list) {
590
+ const api = load(name, entry);
591
+ ImplementInterface(api, stubs(entry, api));
592
+ }
593
+ }
594
+ const hooks = await loadHooks();
595
+ if (hooks.provide) await hooks.provide(load(Object.keys(entries)[0], "."));
596
+ };
597
+ exports.start = function start() {};
598
+ exports.stop = function stop() {};
599
+ exports.destroy = function destroy() {};
600
+ `;
601
+ //#endregion
602
+ //#region src/verify/fixture.ts
603
+ function readPackage(folder) {
604
+ const value = parseJson(readFileSync(join(folder, "package.json"), "utf8"));
605
+ return isObject(value) ? value : {};
606
+ }
607
+ /** The runtime export subpaths of a package: every `exports` key but `./package.json` and patterns, or `.` alone. */
608
+ function runtimeEntries(manifest) {
609
+ const exported = manifest.exports;
610
+ if (exported === void 0 || exported === null || isString(exported) || !isObject(exported)) return ["."];
611
+ const keys = Object.keys(exported).filter((key) => key.startsWith("."));
612
+ if (keys.length === 0) return ["."];
613
+ return keys.filter((key) => key !== "./package.json" && !key.includes("*"));
614
+ }
615
+ /** The interfaces a module declares in `antelopeJs.implements`. */
616
+ function implementedInterfaces(manifest) {
617
+ const antelope = manifest.antelopeJs;
618
+ if (antelope === void 0 || !isObject(antelope)) return [];
619
+ const list = antelope.implements;
620
+ return Array.isArray(list) ? list.filter(isString) : [];
621
+ }
622
+ /** The real folder of a dependency installed in the repository, or a clear error naming what to install. */
623
+ function installedPackage(root, name) {
624
+ const folder = join(root, "node_modules", name);
625
+ if (!existsSync(folder)) throw new Error(`${name} is not installed in ${root}. Run the package manager's install first.`);
626
+ return realpathSync(folder);
627
+ }
628
+ function link(target, path) {
629
+ mkdirSync(dirname(path), { recursive: true });
630
+ symlinkSync(target, path, "dir");
631
+ }
632
+ function writeModule(folder, manifest, source, links) {
633
+ mkdirSync(folder, { recursive: true });
634
+ writeFileSync(join(folder, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
635
+ writeFileSync(join(folder, "index.js"), source);
636
+ for (const [name, target] of links) link(target, join(folder, "node_modules", name));
637
+ }
638
+ function interfaceLinks(workspace, state) {
639
+ const core = installedPackage(workspace.root, "@antelopejs/interface-core");
640
+ if (workspace.kind === "interface") {
641
+ const name = String(workspace.manifest.name);
642
+ return {
643
+ links: /* @__PURE__ */ new Map([[name, state.pack], ["@antelopejs/interface-core", core]]),
644
+ entries: { [name]: runtimeEntries(readPackage(state.pack)) }
645
+ };
646
+ }
647
+ const links = /* @__PURE__ */ new Map([["@antelopejs/interface-core", core]]);
648
+ const entries = {};
649
+ for (const name of implementedInterfaces(workspace.manifest)) {
650
+ const folder = installedPackage(workspace.root, name);
651
+ links.set(name, folder);
652
+ entries[name] = runtimeEntries(readPackage(folder));
653
+ }
654
+ return {
655
+ links,
656
+ entries
657
+ };
658
+ }
659
+ /**
660
+ * Writes the fixture project of a journey: an `antelope.config.ts` loading
661
+ * the driver module and, for the interface kind, the stub provider, or, for
662
+ * the module kind, the module under verification as a `local` source. Every
663
+ * interface the driver calls is linked to the copy the repository resolves,
664
+ * so the project shares one copy per interface as core requires.
665
+ */
666
+ function writeFixture(workspace, state, folder, moduleConfig) {
667
+ const project = join(folder, "project");
668
+ const { links, entries } = interfaceLinks(workspace, state);
669
+ const modules = {};
670
+ if (workspace.kind === "interface") {
671
+ writeModule(join(project, "stub"), {
672
+ name: "verify-stub",
673
+ version: "1.0.0",
674
+ main: "index.js",
675
+ antelopeJs: { implements: Object.keys(entries) }
676
+ }, STUB_SOURCE, links);
677
+ modules["verify-stub"] = { source: {
678
+ type: "local",
679
+ path: "./stub"
680
+ } };
681
+ } else modules[workspace.name] = {
682
+ source: {
683
+ type: "local",
684
+ path: workspace.root
685
+ },
686
+ config: moduleConfig
687
+ };
688
+ writeModule(join(project, "driver"), {
689
+ name: "verify-driver",
690
+ version: "1.0.0",
691
+ main: "index.js"
692
+ }, DRIVER_SOURCE, links);
693
+ modules["verify-driver"] = { source: {
694
+ type: "local",
695
+ path: "./driver"
696
+ } };
697
+ writeFileSync(join(project, "antelope.config.ts"), `export default ${JSON.stringify({
698
+ name: `verify-${workspace.name}`,
699
+ modules
700
+ }, null, 2)};\n`);
701
+ const config = join(workspace.skill, "verify.config.ts");
702
+ return {
703
+ project,
704
+ env: {
705
+ VERIFY_ENTRIES: JSON.stringify(entries),
706
+ VERIFY_CALL_LOG: join(folder, "calls.jsonl"),
707
+ VERIFY_CONFIG: config
708
+ }
709
+ };
710
+ }
711
+ /** The `ajs` entry of the `@antelopejs/core` the repository installs. */
712
+ function ajsEntry(root) {
713
+ const folder = installedPackage(root, "@antelopejs/core");
714
+ const manifest = parseJson(readFileSync(join(folder, "package.json"), "utf8"));
715
+ const bin = isObject(manifest) && manifest.bin !== void 0 && isObject(manifest.bin) ? manifest.bin.ajs : void 0;
716
+ if (bin === void 0 || !isString(bin)) throw new Error(`${folder} has no ajs bin`);
717
+ return join(folder, bin);
718
+ }
719
+ //#endregion
720
+ //#region src/verify/surface.ts
721
+ const MAX_DEPTH = 4;
722
+ const SIGNATURE_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.WriteArrowStyleSignature;
723
+ const DECLARATION_FILE = /\.d\.[cm]?ts$/;
724
+ function exportedDeclaration(value) {
725
+ if (Array.isArray(value)) return value.map(exportedDeclaration).find((found) => found !== void 0);
726
+ if (isString(value)) return DECLARATION_FILE.test(value) ? value : void 0;
727
+ if (!isObject(value)) return void 0;
728
+ const types = optStr(value, "types");
729
+ if (types !== void 0) return types;
730
+ return Object.values(value).map(exportedDeclaration).find((found) => found !== void 0);
731
+ }
732
+ function declarationEntries(manifest) {
733
+ const entries = /* @__PURE__ */ new Map();
734
+ const exported = manifest.exports;
735
+ if (exported === void 0) {
736
+ const types = optStr(manifest, "types") ?? optStr(manifest, "typings");
737
+ if (types !== void 0) entries.set(".", types);
738
+ return entries;
739
+ }
740
+ const subpaths = isObject(exported) && Object.keys(exported).some((key) => key[0] === ".") ? Object.entries(exported) : [[".", exported]];
741
+ for (const [subpath, target] of subpaths) {
742
+ if (subpath === "./package.json" || subpath.includes("*")) continue;
743
+ const declaration = exportedDeclaration(target);
744
+ if (declaration !== void 0) entries.set(subpath, declaration);
745
+ }
746
+ return entries;
747
+ }
748
+ function inPackage(walk, file) {
749
+ const path = relative(walk.folder, file);
750
+ return path !== "" && !path.startsWith("..") && !path.split(sep).includes("node_modules");
751
+ }
752
+ function declaredHere(walk, symbol) {
753
+ return (symbol.declarations ?? []).some((declaration) => inPackage(walk, declaration.getSourceFile().fileName));
754
+ }
755
+ function resolveAlias(walk, symbol) {
756
+ return symbol.flags & ts.SymbolFlags.Alias ? walk.checker.getAliasedSymbol(symbol) : symbol;
757
+ }
758
+ function signatureTexts(walk, signatures, kind) {
759
+ return signatures.map((signature) => walk.checker.signatureToString(signature, void 0, SIGNATURE_FLAGS, kind).replace(/\s+/g, " "));
760
+ }
761
+ function callableText(walk, type) {
762
+ const callable = walk.checker.getNonNullableType(type);
763
+ const texts = [...signatureTexts(walk, callable.getCallSignatures(), ts.SignatureKind.Call), ...signatureTexts(walk, callable.getConstructSignatures(), ts.SignatureKind.Construct)];
764
+ return texts.length === 0 ? void 0 : texts.join(" | ");
765
+ }
766
+ function typeOf(walk, symbol) {
767
+ return walk.checker.getTypeOfSymbol(symbol);
768
+ }
769
+ function isPublic(property) {
770
+ const hidden = ts.ModifierFlags.Private | ts.ModifierFlags.Protected;
771
+ return (property.declarations ?? []).every((declaration) => (ts.getCombinedModifierFlags(declaration) & hidden) === 0);
772
+ }
773
+ function recordMembers(walk, type, prefix, skip) {
774
+ for (const property of walk.checker.getPropertiesOfType(type)) {
775
+ if (property.name === skip || !isPublic(property)) continue;
776
+ if (!declaredHere(walk, property)) continue;
777
+ const text = callableText(walk, typeOf(walk, property));
778
+ if (text !== void 0) walk.surface.set(`${prefix}${property.name}`, text);
779
+ }
780
+ }
781
+ function recordClass(walk, symbol, path) {
782
+ recordMembers(walk, typeOf(walk, symbol), `${path}.`, "prototype");
783
+ recordMembers(walk, walk.checker.getDeclaredTypeOfSymbol(symbol), `${path}.prototype.`, "");
784
+ }
785
+ function isObjectType(type) {
786
+ return (type.flags & ts.TypeFlags.Object) !== 0;
787
+ }
788
+ function isObjectLiteralType(walk, type) {
789
+ const owner = type.symbol;
790
+ return isObjectType(type) && (type.objectFlags & ts.ObjectFlags.Anonymous) !== 0 && owner !== void 0 && (owner.flags & ts.SymbolFlags.TypeLiteral) !== 0 && declaredHere(walk, owner);
791
+ }
792
+ function visit(walk, exported, path, trail) {
793
+ const symbol = resolveAlias(walk, exported);
794
+ if (trail.includes(symbol)) return;
795
+ const depth = path.split(":")[1]?.split(".").length ?? MAX_DEPTH;
796
+ const type = symbol.flags & ts.SymbolFlags.Value ? typeOf(walk, symbol) : void 0;
797
+ const text = type && callableText(walk, type);
798
+ if (text !== void 0) walk.surface.set(path, text);
799
+ if (symbol.flags & ts.SymbolFlags.Class && declaredHere(walk, symbol)) {
800
+ recordClass(walk, symbol, path);
801
+ return;
802
+ }
803
+ if (depth >= MAX_DEPTH || !declaredHere(walk, symbol)) return;
804
+ const next = [...trail, symbol];
805
+ if (symbol.flags & ts.SymbolFlags.Module) for (const member of walk.checker.getExportsOfModule(symbol)) visit(walk, member, `${path}.${member.name}`, next);
806
+ else if (type && text === void 0 && isObjectLiteralType(walk, type)) for (const member of walk.checker.getPropertiesOfType(type)) visit(walk, member, `${path}.${member.name}`, next);
807
+ }
808
+ function unresolvedImports(walk, program) {
809
+ const missing = [];
810
+ for (const file of program.getSourceFiles()) {
811
+ if (!inPackage(walk, file.fileName)) continue;
812
+ for (const statement of file.statements) {
813
+ const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier : void 0;
814
+ if (specifier && !walk.checker.getSymbolAtLocation(specifier)) missing.push(`${relative(walk.folder, file.fileName)} -> ${specifier.text}`);
815
+ }
816
+ }
817
+ return missing;
818
+ }
819
+ function readManifest(folder) {
820
+ const manifest = parseJson(readFileSync(join(folder, "package.json"), "utf8"));
821
+ if (!isObject(manifest)) throw new Error(`${folder}: package.json is not an object`);
822
+ return manifest;
823
+ }
824
+ /**
825
+ * The function surface an extracted npm package declares, read from its `.d.ts` files.
826
+ * Throws when an export's declaration file is missing or an import in the package's
827
+ * own declarations cannot be resolved, because the surface would silently be partial.
828
+ */
829
+ function declaredSurface(packageFolder) {
830
+ const folder = realpathSync(resolve(packageFolder));
831
+ const entries = declarationEntries(readManifest(folder));
832
+ const files = /* @__PURE__ */ new Map();
833
+ for (const [subpath, declaration] of entries) {
834
+ const file = resolve(folder, declaration);
835
+ if (!existsSync(file)) throw new Error(`${subpath}: ${declaration} is missing`);
836
+ files.set(subpath, file);
837
+ }
838
+ const program = ts.createProgram([...files.values()], {
839
+ noEmit: true,
840
+ skipLibCheck: true,
841
+ strict: true,
842
+ target: ts.ScriptTarget.ESNext,
843
+ module: ts.ModuleKind.ESNext,
844
+ moduleResolution: ts.ModuleResolutionKind.Bundler,
845
+ types: []
846
+ });
847
+ const walk = {
848
+ checker: program.getTypeChecker(),
849
+ folder,
850
+ surface: /* @__PURE__ */ new Map()
851
+ };
852
+ const missing = unresolvedImports(walk, program);
853
+ if (missing.length > 0) throw new Error(`unresolved imports in declarations: ${missing.join(", ")}`);
854
+ for (const [subpath, file] of files) {
855
+ const source = program.getSourceFile(file);
856
+ const module = source && walk.checker.getSymbolAtLocation(source);
857
+ if (!module) continue;
858
+ for (const member of walk.checker.getExportsOfModule(module)) visit(walk, member, `${subpath}:${member.name}`, []);
859
+ }
860
+ return walk.surface;
861
+ }
862
+ /** The paths added, removed and changed from `published` to `head`, each sorted. */
863
+ function diffSurface(published, head) {
864
+ const added = [...head.keys()].filter((path) => !published.has(path));
865
+ const removed = [...published.keys()].filter((path) => !head.has(path));
866
+ const changed = [...head].flatMap(([path, after]) => {
867
+ const before = published.get(path);
868
+ return before !== void 0 && before !== after ? [{
869
+ path,
870
+ before,
871
+ after
872
+ }] : [];
873
+ });
874
+ return {
875
+ added: added.sort(),
876
+ removed: removed.sort(),
877
+ changed: changed.sort((a, b) => a.path.localeCompare(b.path))
878
+ };
879
+ }
880
+ function parseVersion(text) {
881
+ const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(text.trim());
882
+ if (!match) throw new Error(`not a semver version: ${text}`);
883
+ return {
884
+ core: [
885
+ Number(match[1]),
886
+ Number(match[2]),
887
+ Number(match[3])
888
+ ],
889
+ pre: match[4] ? match[4].split(".") : []
890
+ };
891
+ }
892
+ function comparePre(a, b) {
893
+ if (a.length === 0 || b.length === 0) return b.length - a.length;
894
+ const numeric = /^\d+$/;
895
+ for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
896
+ const [left, right] = [a[index] ?? "", b[index] ?? ""];
897
+ const order = numeric.test(left) && numeric.test(right) ? Number(left) - Number(right) : numeric.test(left) === numeric.test(right) ? left.localeCompare(right) : numeric.test(left) ? -1 : 1;
898
+ if (order !== 0) return order;
899
+ }
900
+ return a.length - b.length;
901
+ }
902
+ function compareVersions(a, b) {
903
+ return a.core[0] - b.core[0] || a.core[1] - b.core[1] || a.core[2] - b.core[2] || comparePre(a.pre, b.pre);
904
+ }
905
+ function increment(version, bump) {
906
+ const [major, minor, patch] = version.core;
907
+ if (bump === "major") return {
908
+ core: [
909
+ major + 1,
910
+ 0,
911
+ 0
912
+ ],
913
+ pre: []
914
+ };
915
+ if (bump === "minor") return {
916
+ core: [
917
+ major,
918
+ minor + 1,
919
+ 0
920
+ ],
921
+ pre: []
922
+ };
923
+ return {
924
+ core: version.pre.length > 0 ? [
925
+ major,
926
+ minor,
927
+ patch
928
+ ] : [
929
+ major,
930
+ minor,
931
+ patch + 1
932
+ ],
933
+ pre: []
934
+ };
935
+ }
936
+ function format(version) {
937
+ const core = version.core.join(".");
938
+ return version.pre.length > 0 ? `${core}-${version.pre.join(".")}` : core;
939
+ }
940
+ function titleBump(title) {
941
+ const match = /^(\w+)(?:\([^)]*\))?(!)?:/.exec(title.trim());
942
+ if (match?.[2] === "!" || title.includes("BREAKING CHANGE")) return "major";
943
+ return match?.[1] === "feat" ? "minor" : "patch";
944
+ }
945
+ /**
946
+ * The bump changelogen 0.5.7 applies to `currentVersion` for these commit titles:
947
+ * `!` or a `BREAKING CHANGE` footer is major, `feat` minor, anything else patch,
948
+ * and on a `0.x` version major becomes minor and minor becomes patch.
949
+ */
950
+ function releaseType(currentVersion, titles) {
951
+ const order = [
952
+ "patch",
953
+ "minor",
954
+ "major"
955
+ ];
956
+ const highest = titles.map(titleBump).reduce((top, bump) => order.indexOf(bump) > order.indexOf(top) ? bump : top, "patch");
957
+ if (!currentVersion.startsWith("0.")) return highest;
958
+ return highest === "major" ? "minor" : "patch";
959
+ }
960
+ function listPaths(diff) {
961
+ return [
962
+ diff.added.length > 0 ? `added ${diff.added.join(", ")}` : "",
963
+ diff.changed.length > 0 ? `changed ${diff.changed.map((entry) => entry.path).join(", ")}` : "",
964
+ diff.removed.length > 0 ? `removed ${diff.removed.join(", ")}` : ""
965
+ ].filter((part) => part !== "").join("; ");
966
+ }
967
+ /**
968
+ * Judges the interface minor-bump rule: an added, changed or removed function needs a
969
+ * release of at least the next minor of the published version.
970
+ */
971
+ function minorRule(input) {
972
+ const { published, headVersion, titles, diff } = input;
973
+ if (published === null) return {
974
+ required: "none",
975
+ releases: headVersion,
976
+ ok: true,
977
+ reason: "never published: the first release has no surface to compare against"
978
+ };
979
+ const base = parseVersion(published);
980
+ const releases = compareVersions(parseVersion(headVersion), base) > 0 ? headVersion : format(increment(base, releaseType(published, titles)));
981
+ const required = diff.added.length + diff.changed.length + diff.removed.length > 0 ? "minor" : "none";
982
+ if (required === "none") return {
983
+ required,
984
+ releases,
985
+ ok: true,
986
+ reason: `no function added, changed or removed against ${published}: no minor required`
987
+ };
988
+ const floor = format(increment(base, "minor"));
989
+ const ok = compareVersions(parseVersion(releases), parseVersion(floor)) >= 0;
990
+ const facts = `${listPaths(diff)}: needs at least ${floor} against ${published}, this change releases as ${releases}`;
991
+ const title = base.core[0] === 0 ? "a `feat!:` commit title (changelogen turns a breaking change into a minor on 0.x)" : "a `feat:` commit title";
992
+ return {
993
+ required,
994
+ releases,
995
+ ok,
996
+ reason: ok ? facts : `${facts}. Fix: use ${title}, or run the release workflow with release-version ${floor}`
997
+ };
998
+ }
999
+ //#endregion
1000
+ //#region src/verify/interface.ts
1001
+ const CALL_ARGS = ["verify-argument", 7];
1002
+ function runtimeMembers(value) {
1003
+ if (!Array.isArray(value)) return [];
1004
+ return value.filter(isObject).map((member) => ({
1005
+ path: String(member.path),
1006
+ kind: String(member.kind)
1007
+ }));
1008
+ }
1009
+ function splitPath(path) {
1010
+ const colon = path.indexOf(":");
1011
+ return {
1012
+ entry: path.slice(0, colon),
1013
+ keys: path.slice(colon + 1).split(".")
1014
+ };
1015
+ }
1016
+ function writeJson(folder, file, value) {
1017
+ writeFileSync(join(folder, file), `${JSON.stringify(value, null, 2)}\n`);
1018
+ }
1019
+ /** Links the repository's node_modules under an extracted package, so its declarations resolve their imports. */
1020
+ function linkDependencies(packageFolder, repo) {
1021
+ symlinkSync(join(repo, "node_modules"), join(packageFolder, "node_modules"), "dir");
1022
+ }
1023
+ function readSurface(context, folder, label) {
1024
+ const step = context.step(`${label} declared surface`);
1025
+ try {
1026
+ const surface = declaredSurface(folder);
1027
+ writeJson(step, "surface.json", Object.fromEntries(surface));
1028
+ context.expect(step, [{
1029
+ name: `${label} declarations read`,
1030
+ pass: true,
1031
+ detail: `${surface.size} functions`
1032
+ }]);
1033
+ return surface;
1034
+ } catch (error) {
1035
+ const detail = error instanceof Error ? error.message : String(error);
1036
+ context.expect(step, [{
1037
+ name: `${label} declarations read`,
1038
+ pass: false,
1039
+ detail
1040
+ }], { critical: true });
1041
+ return;
1042
+ }
1043
+ }
1044
+ function logged(context, project, path, args) {
1045
+ const calls = context.stubCalls(project);
1046
+ const seen = calls.some((call) => call.path === path && JSON.stringify(call.args) === JSON.stringify(args));
1047
+ return {
1048
+ name: `the stub provider received ${path}(${JSON.stringify(args).slice(1, -1)})`,
1049
+ pass: seen,
1050
+ detail: JSON.stringify(calls.filter((call) => call.path.startsWith(path)))
1051
+ };
1052
+ }
1053
+ async function callProxy(context, app, path) {
1054
+ const { entry, keys } = splitPath(path);
1055
+ const result = await context.call(`call ${path}`, app, {
1056
+ entry,
1057
+ path: keys,
1058
+ args: CALL_ARGS
1059
+ });
1060
+ context.expect(result.folder, [
1061
+ {
1062
+ name: `${path} resolved through core`,
1063
+ pass: result.ok,
1064
+ detail: JSON.stringify(result.value ?? result.error)
1065
+ },
1066
+ equal(`${path} returned the stub provider's answer`, result.value, {
1067
+ stub: path,
1068
+ args: CALL_ARGS
1069
+ }),
1070
+ logged(context, app.project, path, CALL_ARGS)
1071
+ ]);
1072
+ }
1073
+ async function callRegistering(context, app, path) {
1074
+ const { entry, keys } = splitPath(path);
1075
+ const result = await context.driver(`register ${path}`, app, "/registering", {
1076
+ entry,
1077
+ path: keys
1078
+ });
1079
+ context.expect(result.folder, [
1080
+ {
1081
+ name: `${path} register and unregister resolved through core`,
1082
+ pass: result.ok,
1083
+ detail: JSON.stringify(result.value ?? result.error)
1084
+ },
1085
+ logged(context, app.project, `${path}.register`, ["verify-registration"]),
1086
+ logged(context, app.project, `${path}.unregister`, ["verify-registration"])
1087
+ ]);
1088
+ }
1089
+ async function callEvent(context, app, path) {
1090
+ const { entry, keys } = splitPath(path);
1091
+ const result = await context.driver(`emit ${path}`, app, "/event", {
1092
+ entry,
1093
+ path: keys,
1094
+ args: CALL_ARGS
1095
+ });
1096
+ context.expect(result.folder, [equal(`a handler registered on ${path} received the emitted arguments`, result.value, CALL_ARGS)]);
1097
+ }
1098
+ async function callHook(context, app, path, expected) {
1099
+ const result = await context.driver(`call ${path}`, app, "/hook", { path });
1100
+ context.expect(result.folder, [{
1101
+ name: `${path} resolved through core`,
1102
+ pass: result.ok,
1103
+ detail: JSON.stringify(result.value ?? result.error)
1104
+ }, equal(`${path} returned the value verify.config.ts expects`, result.value, expected)]);
1105
+ }
1106
+ function unreachable(context, path, detail) {
1107
+ context.expect(context.step(`no call for ${path}`), [{
1108
+ name: `${path} is called through core`,
1109
+ pass: false,
1110
+ detail
1111
+ }]);
1112
+ }
1113
+ async function callMember(context, app, path, members) {
1114
+ const hooks = context.workspace.config.interface ?? {};
1115
+ const providerSide = hooks.providerSide?.[path];
1116
+ const hook = hooks.calls?.[path];
1117
+ const kind = members.find((member) => member.path === path)?.kind;
1118
+ if (providerSide !== void 0) {
1119
+ const step = context.step(`provider side ${path}`);
1120
+ context.expect(step, [{
1121
+ name: `${path} is called by providers only`,
1122
+ pass: providerSide.trim() !== "",
1123
+ detail: providerSide
1124
+ }]);
1125
+ } else if (hook !== void 0) await callHook(context, app, path, hook.expect);
1126
+ else if (kind === void 0) unreachable(context, path, "declared in the .d.ts files but the loaded package does not export it");
1127
+ else if (kind === "async") await callProxy(context, app, path);
1128
+ else if (kind === "registering") await callRegistering(context, app, path);
1129
+ else if (kind === "event") await callEvent(context, app, path);
1130
+ else unreachable(context, path, `a plain ${kind}: add interface.calls["${path}"] to verify.config.ts, or interface.providerSide["${path}"] with why consumers never call it`);
1131
+ }
1132
+ /** Loads the packed interface with a stub provider and a consumer, and calls every declared function through core. */
1133
+ const everyFunction = {
1134
+ title: "every declared function answers through core from a stub provider",
1135
+ entryPoint: "a consumer module calling the packed interface in `ajs project dev`",
1136
+ async run(context) {
1137
+ const declared = readSurface(context, context.state.pack, "head");
1138
+ const project = context.fixture();
1139
+ const app = await context.dev("ajs project dev", project);
1140
+ const surface = await context.driver("runtime surface", app, "/surface", {});
1141
+ const members = runtimeMembers(surface.value);
1142
+ context.expect(surface.folder, [{
1143
+ name: "the consumer walked the loaded interface",
1144
+ pass: surface.ok && members.length > 0,
1145
+ detail: `${members.length} members`
1146
+ }]);
1147
+ for (const path of declared?.keys() ?? []) await callMember(context, app, path, members);
1148
+ const stopped = await context.stop("SIGINT", app);
1149
+ context.expect(stopped.folder, [interrupted(stopped)]);
1150
+ }
1151
+ };
1152
+ function publishedVersion(output) {
1153
+ const text = output.trim();
1154
+ return text === "" ? null : text.replace(/^"|"$/g, "");
1155
+ }
1156
+ async function fetchPublished(context, name, version) {
1157
+ const folder = join(CACHE_DIR, "published", name.replace("/", "+"), version);
1158
+ mkdirSync(folder, { recursive: true });
1159
+ const packed = await context.command(`npm pack ${name}@${version}`, "npm", [
1160
+ "pack",
1161
+ `${name}@${version}`,
1162
+ "--pack-destination",
1163
+ folder
1164
+ ], { env: {
1165
+ npm_config_offline: "false",
1166
+ npm_config_prefer_offline: "false"
1167
+ } });
1168
+ const tarball = readdirSync(folder).find((file) => file.endsWith(".tgz"));
1169
+ if (packed.exitCode !== 0 || tarball === void 0) {
1170
+ context.expect(packed.folder, [exitIs(packed, 0)], { critical: true });
1171
+ return;
1172
+ }
1173
+ const extracted = join(context.work, "published");
1174
+ mkdirSync(extracted, { recursive: true });
1175
+ const untar = await context.command("extract published", "tar", [
1176
+ "-xzf",
1177
+ join(folder, tarball),
1178
+ "-C",
1179
+ extracted
1180
+ ]);
1181
+ context.expect(untar.folder, [exitIs(untar, 0)], { critical: true });
1182
+ const root = join(extracted, "package");
1183
+ linkDependencies(root, context.repo);
1184
+ return root;
1185
+ }
1186
+ function changeTitles(context) {
1187
+ if (context.state.title !== "") return [context.state.title];
1188
+ const base = git(context.repo, [
1189
+ "merge-base",
1190
+ context.state.baseRef,
1191
+ "HEAD"
1192
+ ]);
1193
+ return git(context.repo, [
1194
+ "log",
1195
+ "--format=%s",
1196
+ `${base}..HEAD`
1197
+ ]).split("\n").filter(Boolean);
1198
+ }
1199
+ /** The journeys the interface kind ships, by id. */
1200
+ const INTERFACE_JOURNEYS = {
1201
+ "every-function": everyFunction,
1202
+ "minor-bump": {
1203
+ title: "an added, changed or removed function releases as a new minor",
1204
+ entryPoint: "the published package against the packed head, as a module author upgrading sees it",
1205
+ async run(context) {
1206
+ const name = String(context.workspace.manifest.name);
1207
+ const headVersion = String(context.workspace.manifest.version);
1208
+ const view = await context.command(`npm view ${name}`, "npm", [
1209
+ "view",
1210
+ name,
1211
+ "version",
1212
+ "--json"
1213
+ ], { env: {
1214
+ npm_config_offline: "false",
1215
+ npm_config_prefer_offline: "false"
1216
+ } });
1217
+ const missing = view.exitCode !== 0 && /E404/.test(view.stderr);
1218
+ if (view.exitCode !== 0 && !missing) context.notVerified(`npm view ${name} failed: ${view.stderr.trim().slice(-200)}`);
1219
+ const published = missing ? null : publishedVersion(view.stdout);
1220
+ const head = readSurface(context, context.state.pack, "head");
1221
+ const root = published === null ? void 0 : await fetchPublished(context, name, published);
1222
+ const diff = diffSurface((root === void 0 ? void 0 : readSurface(context, root, `published ${published}`)) ?? /* @__PURE__ */ new Map(), head ?? /* @__PURE__ */ new Map());
1223
+ const titles = changeTitles(context);
1224
+ const verdict = minorRule({
1225
+ published,
1226
+ headVersion,
1227
+ titles,
1228
+ diff
1229
+ });
1230
+ const step = context.step("minor rule");
1231
+ writeJson(step, "minor-rule.json", {
1232
+ published,
1233
+ headVersion,
1234
+ titles,
1235
+ ...diff,
1236
+ ...verdict
1237
+ });
1238
+ context.expect(step, [{
1239
+ name: verdict.required === "minor" ? `releases at least the next minor of ${published}` : "no function changed against the published version",
1240
+ pass: verdict.ok,
1241
+ detail: verdict.reason
1242
+ }]);
1243
+ }
1244
+ }
1245
+ };
1246
+ //#endregion
1247
+ //#region src/verify/record.ts
1248
+ const DEFAULT_TIMEOUT_MS = 6e5;
1249
+ /** Quotes an argument the way a shell user would type it. */
1250
+ function shellQuote(value) {
1251
+ return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
1252
+ }
1253
+ function describe(spec) {
1254
+ return [spec.program, ...spec.args].map(shellQuote).join(" ");
1255
+ }
1256
+ function writeCommand(folder, spec) {
1257
+ mkdirSync(folder, { recursive: true });
1258
+ writeFileSync(join(folder, "command.txt"), `cd ${shellQuote(spec.cwd)}\n${describe(spec)}\n`);
1259
+ }
1260
+ /** Runs a command to completion and writes command.txt, stdout.txt, stderr.txt and exit-code.txt into `folder`. */
1261
+ function runRecorded(folder, spec) {
1262
+ writeCommand(folder, spec);
1263
+ return new Promise((resolve) => {
1264
+ const child = spawn(spec.program, spec.args, {
1265
+ cwd: spec.cwd,
1266
+ env: spec.env,
1267
+ stdio: [
1268
+ "ignore",
1269
+ "pipe",
1270
+ "pipe"
1271
+ ]
1272
+ });
1273
+ const out = [];
1274
+ const err = [];
1275
+ child.stdout.on("data", (chunk) => out.push(chunk));
1276
+ child.stderr.on("data", (chunk) => err.push(chunk));
1277
+ const timer = setTimeout(() => child.kill("SIGKILL"), spec.timeoutMs ?? DEFAULT_TIMEOUT_MS);
1278
+ const finish = (code, signal, failure = "") => {
1279
+ clearTimeout(timer);
1280
+ const result = {
1281
+ folder,
1282
+ command: describe(spec),
1283
+ exitCode: code,
1284
+ signal,
1285
+ stdout: Buffer.concat(out).toString("utf8"),
1286
+ stderr: `${Buffer.concat(err).toString("utf8")}${failure}`
1287
+ };
1288
+ writeFileSync(join(folder, "stdout.txt"), result.stdout);
1289
+ writeFileSync(join(folder, "stderr.txt"), result.stderr);
1290
+ writeFileSync(join(folder, "exit-code.txt"), `${code ?? `signal ${signal}`}\n`);
1291
+ resolve(result);
1292
+ };
1293
+ child.on("error", (error) => finish(null, null, `${error.message}\n`));
1294
+ child.on("close", (code, signal) => finish(code, signal));
1295
+ });
1296
+ }
1297
+ /** Starts a long-running command in its own process group, writing stdout and stderr straight to files. */
1298
+ function startRecorded(folder, spec) {
1299
+ writeCommand(folder, spec);
1300
+ const stdout = openSync(join(folder, "stdout.txt"), "w");
1301
+ const stderr = openSync(join(folder, "stderr.txt"), "w");
1302
+ const child = spawn(spec.program, spec.args, {
1303
+ cwd: spec.cwd,
1304
+ env: spec.env,
1305
+ detached: true,
1306
+ stdio: [
1307
+ "ignore",
1308
+ stdout,
1309
+ stderr
1310
+ ]
1311
+ });
1312
+ closeSync(stdout);
1313
+ closeSync(stderr);
1314
+ const exited = new Promise((resolve) => {
1315
+ child.on("exit", (exitCode, signal) => {
1316
+ writeFileSync(join(folder, "exit-code.txt"), `${exitCode ?? `signal ${signal}`}\n`);
1317
+ resolve({
1318
+ exitCode,
1319
+ signal
1320
+ });
1321
+ });
1322
+ });
1323
+ if (child.pid === void 0) throw new Error(`Could not start ${describe(spec)}`);
1324
+ writeFileSync(join(folder, "pid.txt"), `${child.pid}\n`);
1325
+ return {
1326
+ folder,
1327
+ child,
1328
+ pid: child.pid,
1329
+ exited
1330
+ };
1331
+ }
1332
+ /** Kills the process group of `pid`, or `pid` alone, ignoring a process already gone. */
1333
+ function killGroup(pid) {
1334
+ try {
1335
+ process.kill(-pid, "SIGKILL");
1336
+ } catch {
1337
+ try {
1338
+ process.kill(pid, "SIGKILL");
1339
+ } catch {
1340
+ return;
1341
+ }
1342
+ }
1343
+ }
1344
+ /** Reads what a background command has written so far. */
1345
+ function readOutput(folder) {
1346
+ return {
1347
+ stdout: readFileSync(join(folder, "stdout.txt"), "utf8"),
1348
+ stderr: readFileSync(join(folder, "stderr.txt"), "utf8")
1349
+ };
1350
+ }
1351
+ /** Asks the kernel for a free TCP port on the loopback interface. */
1352
+ function freePort() {
1353
+ return new Promise((resolve, reject) => {
1354
+ const server = createServer();
1355
+ server.once("error", reject);
1356
+ server.listen(0, "127.0.0.1", () => {
1357
+ const address = server.address();
1358
+ const port = address !== null && address instanceof Object ? address.port : 0;
1359
+ server.close(() => resolve(port));
1360
+ });
1361
+ });
1362
+ }
1363
+ function reason(error) {
1364
+ return error.cause instanceof Error ? error.cause.message : error.message;
1365
+ }
1366
+ /** Sends one request and writes http.json with the status and body. */
1367
+ async function httpRecorded(folder, url, init = {}) {
1368
+ mkdirSync(folder, { recursive: true });
1369
+ let result;
1370
+ try {
1371
+ const response = await fetch(url, {
1372
+ method: init.method ?? "GET",
1373
+ body: init.body,
1374
+ headers: init.body ? { "content-type": "application/json" } : void 0,
1375
+ signal: AbortSignal.timeout(init.timeoutMs ?? 5e3)
1376
+ });
1377
+ const body = await response.text();
1378
+ let json;
1379
+ try {
1380
+ json = parseJson(body);
1381
+ } catch {
1382
+ json = void 0;
1383
+ }
1384
+ result = {
1385
+ folder,
1386
+ url,
1387
+ status: response.status,
1388
+ body,
1389
+ json,
1390
+ error: null
1391
+ };
1392
+ } catch (error) {
1393
+ result = {
1394
+ folder,
1395
+ url,
1396
+ status: null,
1397
+ body: "",
1398
+ json: void 0,
1399
+ error: error instanceof Error ? reason(error) : String(error)
1400
+ };
1401
+ }
1402
+ writeFileSync(join(folder, "http.json"), `${JSON.stringify({
1403
+ request: {
1404
+ url,
1405
+ ...init
1406
+ },
1407
+ response: result
1408
+ }, null, 2)}\n`);
1409
+ return result;
1410
+ }
1411
+ const TREE_SKIP = /* @__PURE__ */ new Set([
1412
+ "node_modules",
1413
+ ".git",
1414
+ ".pnpm-store"
1415
+ ]);
1416
+ function listTree(root, folder = root) {
1417
+ return readdirSync(folder, { withFileTypes: true }).filter((entry) => !TREE_SKIP.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name)).flatMap((entry) => {
1418
+ const path = join(folder, entry.name);
1419
+ const name = relative(root, path);
1420
+ if (entry.isDirectory()) return [`${name}/`, ...listTree(root, path)];
1421
+ return [`${name} ${statSync(path).size}`];
1422
+ });
1423
+ }
1424
+ /** Writes `tree.txt`: every path under `root` with its size, node_modules and .git left out. */
1425
+ function recordTree(folder, root) {
1426
+ mkdirSync(folder, { recursive: true });
1427
+ let lines;
1428
+ try {
1429
+ lines = listTree(root);
1430
+ } catch {
1431
+ lines = [];
1432
+ }
1433
+ writeFileSync(join(folder, "tree.txt"), `${root}\n${lines.join("\n")}\n`);
1434
+ return lines;
1435
+ }
1436
+ //#endregion
1437
+ //#region src/verify/sources.ts
1438
+ const IDENTITY = [
1439
+ "-c",
1440
+ "user.name=antelopejs-verify",
1441
+ "-c",
1442
+ "user.email=verify@antelopejs.invalid",
1443
+ "-c",
1444
+ "init.defaultBranch=main",
1445
+ "-c",
1446
+ "commit.gpgsign=false"
1447
+ ];
1448
+ function commitFolder(folder) {
1449
+ for (const args of [
1450
+ ["init", "-q"],
1451
+ [
1452
+ "add",
1453
+ "-A",
1454
+ "--force"
1455
+ ],
1456
+ [
1457
+ "commit",
1458
+ "-q",
1459
+ "-m",
1460
+ "verify source"
1461
+ ]
1462
+ ]) execFileSync("git", [...IDENTITY, ...args], {
1463
+ cwd: folder,
1464
+ stdio: "ignore"
1465
+ });
1466
+ }
1467
+ function bare(source, target) {
1468
+ execFileSync("git", [
1469
+ "clone",
1470
+ "-q",
1471
+ "--bare",
1472
+ source,
1473
+ target
1474
+ ], { stdio: "ignore" });
1475
+ return pathToFileURL(target).href;
1476
+ }
1477
+ function copyWorkingTree(root, target) {
1478
+ const files = git(root, [
1479
+ "ls-files",
1480
+ "-z",
1481
+ "--cached",
1482
+ "--others",
1483
+ "--exclude-standard"
1484
+ ]).split("\0").filter(Boolean);
1485
+ for (const file of new Set(files)) {
1486
+ const source = join(root, file);
1487
+ const stat = lstatSync(source, { throwIfNoEntry: false });
1488
+ if (stat === void 0 || existsSync(join(target, file))) continue;
1489
+ mkdirSync(dirname(join(target, file)), { recursive: true });
1490
+ if (stat.isSymbolicLink()) symlinkSync(readlinkSync(source), join(target, file));
1491
+ else copyFileSync(source, join(target, file));
1492
+ }
1493
+ }
1494
+ /** The template name the offline manifest lists, the repository's own unless verify.config.ts names one. */
1495
+ function templateName(workspace) {
1496
+ return workspace.config.template?.name ?? `Verify ${workspace.name}`;
1497
+ }
1498
+ /**
1499
+ * Builds the offline template source of a run: the template's working tree,
1500
+ * uncommitted changes included, as a local git repository, and an interfaces
1501
+ * repository whose manifest.json lists it through a `file://` URL. Returns
1502
+ * the manifest repository URL `ajs config set git` points at.
1503
+ */
1504
+ function seedSources(workspace, state) {
1505
+ const sources = join(state.dir, "sources");
1506
+ const template = join(sources, "template");
1507
+ mkdirSync(template, { recursive: true });
1508
+ copyWorkingTree(workspace.root, template);
1509
+ commitFolder(template);
1510
+ const templateUrl = bare(template, join(sources, "template.git"));
1511
+ const manifest = join(sources, "interfaces");
1512
+ mkdirSync(manifest, { recursive: true });
1513
+ const listing = workspace.config.template?.project ? "projectTemplates" : "templates";
1514
+ const entry = {
1515
+ name: templateName(workspace),
1516
+ repository: templateUrl,
1517
+ branch: "main",
1518
+ packageManager: "pnpm"
1519
+ };
1520
+ const content = {
1521
+ interfaces: {},
1522
+ starredInterfaces: [],
1523
+ templates: [],
1524
+ projectTemplates: [],
1525
+ [listing]: [entry]
1526
+ };
1527
+ writeFileSync(join(manifest, "manifest.json"), `${JSON.stringify(content, null, 2)}\n`);
1528
+ commitFolder(manifest);
1529
+ return bare(manifest, join(sources, "interfaces.git"));
1530
+ }
1531
+ //#endregion
1532
+ //#region src/verify/lifecycle.ts
1533
+ /** The prefix of every container a run starts; `VERIFY_CONTAINER_PREFIX` overrides it. */
1534
+ function containerPrefix() {
1535
+ return process.env.VERIFY_CONTAINER_PREFIX ?? "verify";
1536
+ }
1537
+ function setupCommands(workspace) {
1538
+ if (workspace.config.setup) return workspace.config.setup;
1539
+ const scripts = workspace.manifest.scripts;
1540
+ return scripts !== void 0 && isObject(scripts) && scripts.build !== void 0 && workspace.kind !== "template" ? [[
1541
+ "pnpm",
1542
+ "run",
1543
+ "build"
1544
+ ]] : [];
1545
+ }
1546
+ async function runSetup(workspace, state) {
1547
+ const commands = setupCommands(workspace);
1548
+ for (const [index, [program, ...args]] of commands.entries()) {
1549
+ const folder = join(state.evidence, "setup", `${String(index + 1).padStart(2, "0")}-${program}`);
1550
+ const result = await runRecorded(folder, {
1551
+ program,
1552
+ args,
1553
+ cwd: workspace.root,
1554
+ env: {
1555
+ ...process.env,
1556
+ ...workspace.config.env
1557
+ }
1558
+ });
1559
+ if (result.exitCode !== 0) throw new Error(`setup \`${result.command}\` exited ${result.exitCode}; see ${folder}`);
1560
+ }
1561
+ }
1562
+ async function packInterface(workspace, state) {
1563
+ const folder = join(state.dir, "pack");
1564
+ mkdirSync(folder, { recursive: true });
1565
+ const env = isolatedEnv(workspace, join(state.dir, "home"));
1566
+ const packed = await runRecorded(join(state.evidence, "setup", "pack"), {
1567
+ program: "pnpm",
1568
+ args: [
1569
+ "pack",
1570
+ "--pack-destination",
1571
+ folder
1572
+ ],
1573
+ cwd: workspace.root,
1574
+ env
1575
+ });
1576
+ const tarball = readdirSync(folder).find((file) => file.endsWith(".tgz"));
1577
+ if (packed.exitCode !== 0 || tarball === void 0) throw new Error(`pnpm pack failed: ${packed.stderr.slice(-300)}`);
1578
+ const extract = await runRecorded(join(state.evidence, "setup", "extract"), {
1579
+ program: "tar",
1580
+ args: [
1581
+ "-xzf",
1582
+ join(folder, tarball),
1583
+ "-C",
1584
+ folder
1585
+ ],
1586
+ cwd: folder,
1587
+ env
1588
+ });
1589
+ if (extract.exitCode !== 0) throw new Error(`tar failed: ${extract.stderr.slice(-300)}`);
1590
+ const root = join(folder, "package");
1591
+ linkDependencies(root, workspace.root);
1592
+ return root;
1593
+ }
1594
+ /**
1595
+ * Creates an isolated run: runs the setup (the build by default), then
1596
+ * prepares what the kind drives. An interface is packed as npm would publish
1597
+ * it, a module's backing services start in Docker on free ports, and a
1598
+ * template is served from an offline manifest repository.
1599
+ */
1600
+ async function createRun(workspace, baseRef, title) {
1601
+ const state = allocateRun(workspace, baseRef, title);
1602
+ saveRun(state);
1603
+ await runSetup(workspace, state);
1604
+ if (workspace.kind === "interface") state.pack = await packInterface(workspace, state);
1605
+ if (workspace.kind === "module") startServices(workspace, state, containerPrefix());
1606
+ if (workspace.kind === "template") {
1607
+ state.manifestUrl = seedSources(workspace, state);
1608
+ state.templateName = templateName(workspace);
1609
+ }
1610
+ saveRun(state);
1611
+ return state;
1612
+ }
1613
+ function alive(pid) {
1614
+ try {
1615
+ process.kill(pid, 0);
1616
+ return true;
1617
+ } catch {
1618
+ return false;
1619
+ }
1620
+ }
1621
+ function newestUnder(folder) {
1622
+ if (!existsSync(folder)) return 0;
1623
+ return readdirSync(folder, {
1624
+ recursive: true,
1625
+ withFileTypes: true
1626
+ }).filter((entry) => entry.isFile()).reduce((newest, entry) => Math.max(newest, statSync(join(entry.parentPath, entry.name)).mtimeMs), 0);
1627
+ }
1628
+ function buildLine(workspace) {
1629
+ const built = newestUnder(join(workspace.root, "dist"));
1630
+ const source = newestUnder(join(workspace.root, "src"));
1631
+ if (workspace.kind === "template" || source === 0) return {
1632
+ check: "build",
1633
+ ok: true,
1634
+ detail: "nothing to build"
1635
+ };
1636
+ return {
1637
+ check: "build is newer than src",
1638
+ ok: built >= source,
1639
+ detail: built >= source ? "dist is current" : "src changed after the build; create a new run"
1640
+ };
1641
+ }
1642
+ function kindLines(workspace, state) {
1643
+ if (workspace.kind === "interface") return [{
1644
+ check: "packed interface",
1645
+ ok: existsSync(join(state.pack, "package.json")),
1646
+ detail: state.pack
1647
+ }];
1648
+ if (workspace.kind === "template") return [{
1649
+ check: "offline manifest",
1650
+ ok: existsSync(join(state.dir, "sources", "interfaces.git")),
1651
+ detail: `${state.templateName} at ${state.manifestUrl}`
1652
+ }];
1653
+ return [{
1654
+ check: "provider sandbox keys",
1655
+ ok: state.missingKeys.length === 0,
1656
+ detail: state.missingKeys.length === 0 ? "present or not needed" : `missing ${state.missingKeys.join(", ")}: every journey is not verified`
1657
+ }, ...state.containers.map((container) => ({
1658
+ check: `service ${container.service}`,
1659
+ ok: containerRunning(container.name),
1660
+ detail: `${container.name} on ${container.host}:${container.port}`
1661
+ }))];
1662
+ }
1663
+ /** Read-only checks that answer whether a run is worth driving. */
1664
+ function doctor(workspace, state) {
1665
+ const head = git(workspace.root, ["rev-parse", "HEAD"]);
1666
+ let core = "";
1667
+ try {
1668
+ core = relative(workspace.root, installedPackage(workspace.root, "@antelopejs/core"));
1669
+ } catch (error) {
1670
+ core = error instanceof Error ? error.message : String(error);
1671
+ }
1672
+ return [
1673
+ {
1674
+ check: "HEAD unchanged since new",
1675
+ ok: head === state.headSha,
1676
+ detail: head === state.headSha ? head.slice(0, 7) : `new at ${state.headSha.slice(0, 7)}, HEAD is ${head.slice(0, 7)}`
1677
+ },
1678
+ {
1679
+ check: "ajs from the repository's @antelopejs/core",
1680
+ ok: !core.includes(" "),
1681
+ detail: core
1682
+ },
1683
+ buildLine(workspace),
1684
+ ...kindLines(workspace, state),
1685
+ ...state.processes.map((record) => ({
1686
+ check: `no leftover process ${record.name}`,
1687
+ ok: !alive(record.pid),
1688
+ detail: `pid ${record.pid}`
1689
+ }))
1690
+ ];
1691
+ }
1692
+ /** Stops what the run started, by recorded PID and container name, and removes everything but the evidence and run.json. Returns what it could not remove. */
1693
+ function clean(state) {
1694
+ const lines = [];
1695
+ for (const record of state.processes) killGroup(record.pid);
1696
+ for (const container of state.containers) if (!removeContainer(container.name)) lines.push(`could not remove container ${container.name}`);
1697
+ state.processes = [];
1698
+ state.containers = [];
1699
+ saveRun(state);
1700
+ for (const entry of readdirSync(state.dir)) {
1701
+ if (entry === "evidence" || entry === "run.json") continue;
1702
+ rmSync(join(state.dir, entry), {
1703
+ recursive: true,
1704
+ force: true
1705
+ });
1706
+ }
1707
+ return lines;
1708
+ }
1709
+ //#endregion
1710
+ //#region src/verify/map.ts
1711
+ /** The feature that always runs, whatever the diff touches. */
1712
+ const SMOKE_FEATURE = "smoke";
1713
+ const DEFAULT_USER_FACING = {
1714
+ interface: ["src/**"],
1715
+ module: ["src/**"],
1716
+ template: ["**"]
1717
+ };
1718
+ const VERIFICATION_LAYER = [
1719
+ ".agents/**",
1720
+ ".claude/**",
1721
+ ".github/**"
1722
+ ];
1723
+ /** Tests are user-facing in a template, whose whole tree is what `ajs` copies. */
1724
+ const NOT_USER_FACING = {
1725
+ interface: [
1726
+ "**/*.test.ts",
1727
+ "**/test/**",
1728
+ "**/tests/**",
1729
+ ...VERIFICATION_LAYER
1730
+ ],
1731
+ module: [
1732
+ "**/*.test.ts",
1733
+ "**/test/**",
1734
+ "**/tests/**",
1735
+ ...VERIFICATION_LAYER
1736
+ ],
1737
+ template: VERIFICATION_LAYER
1738
+ };
1739
+ function frontmatterLists(text) {
1740
+ const lists = /* @__PURE__ */ new Map();
1741
+ const match = /^---\n([\s\S]*?)\n---\n/.exec(text);
1742
+ let current;
1743
+ for (const line of (match?.[1] ?? "").split("\n")) {
1744
+ const key = /^(\w+):\s*$/.exec(line);
1745
+ const item = /^\s+-\s+(.+)$/.exec(line);
1746
+ if (key) {
1747
+ current = [];
1748
+ lists.set(key[1], current);
1749
+ } else if (item && current) current.push(item[1].replace(/^"|"$/g, ""));
1750
+ }
1751
+ return lists;
1752
+ }
1753
+ /** Reads every feature file under features/, README.md excluded. */
1754
+ function readFeatures(workspace) {
1755
+ const folder = join(workspace.skill, "features");
1756
+ if (!existsSync(folder)) return [];
1757
+ return readdirSync(folder).filter((file) => file.endsWith(".md") && file !== "README.md").sort().map((file) => {
1758
+ const body = readFileSync(join(folder, file), "utf8");
1759
+ const lists = frontmatterLists(body);
1760
+ return {
1761
+ name: file.replace(/\.md$/, ""),
1762
+ file: relative(workspace.root, join(folder, file)),
1763
+ covers: lists.get("covers") ?? [],
1764
+ docs: lists.get("docs") ?? [],
1765
+ journeys: lists.get("journeys") ?? [],
1766
+ body
1767
+ };
1768
+ });
1769
+ }
1770
+ function matches(file, globs) {
1771
+ return globs.some((glob) => matchesGlob(file, glob));
1772
+ }
1773
+ /** Whether a user can observe a change to `file`. */
1774
+ function userFacing(workspace, file) {
1775
+ return matches(file, workspace.config.userFacing ?? DEFAULT_USER_FACING[workspace.kind]) && !matches(file, NOT_USER_FACING[workspace.kind]);
1776
+ }
1777
+ function trackedFiles(workspace) {
1778
+ return git(workspace.root, ["ls-files"]).split("\n").filter(Boolean);
1779
+ }
1780
+ /** The features whose globs cover `file`. */
1781
+ function featuresOf(file, features) {
1782
+ return features.filter((feature) => matches(file, feature.covers)).map((feature) => feature.name);
1783
+ }
1784
+ function featureProblems(workspace, feature, known, tracked) {
1785
+ const problems = [];
1786
+ if (feature.journeys.length === 0) problems.push(`${feature.file}: lists no journeys`);
1787
+ for (const journey of feature.journeys) {
1788
+ if (!known.has(journey)) problems.push(`${feature.file}: journey ${journey} is neither built in nor in verify.config.ts journeys`);
1789
+ if (!feature.body.includes(`\`${journey}\``)) problems.push(`${feature.file}: journey \`${journey}\` is not described`);
1790
+ }
1791
+ if (feature.name !== "smoke" && feature.covers.length === 0) problems.push(`${feature.file}: lists no covers globs`);
1792
+ for (const glob of feature.covers) if (!tracked.some((file) => matchesGlob(file, glob))) problems.push(`${feature.file}: glob ${glob} matches no tracked file`);
1793
+ if (feature.docs.length === 0) problems.push(`${feature.file}: lists no docs pages`);
1794
+ for (const doc of feature.docs) if (!existsSync(join(workspace.root, doc))) problems.push(`${feature.file}: docs path ${doc} does not exist`);
1795
+ if (!existsSync(join(workspace.skill, "seeded-breaks", `${feature.name}.patch`))) problems.push(`${feature.file}: seeded-breaks/${feature.name}.patch is missing`);
1796
+ return problems;
1797
+ }
1798
+ /**
1799
+ * Checks the repo-owned layer against the repository: a smoke feature
1800
+ * exists, every user-facing file is covered, every feature names known
1801
+ * journeys, docs pages that exist and a seeded break, every config journey is
1802
+ * used, and every applicable door kind has a seeded door. One line per problem.
1803
+ */
1804
+ function checkMap(workspace, builtins) {
1805
+ const features = readFeatures(workspace);
1806
+ const tracked = trackedFiles(workspace);
1807
+ const configJourneys = Object.keys(workspace.config.journeys ?? {});
1808
+ const known = /* @__PURE__ */ new Set([...builtins, ...configJourneys]);
1809
+ const problems = [];
1810
+ if (!features.some((feature) => feature.name === "smoke")) problems.push(`${skillFolder(workspace.kind)}/features/${SMOKE_FEATURE}.md is missing: every verdict runs the smoke feature`);
1811
+ for (const file of tracked.filter((path) => userFacing(workspace, path))) if (featuresOf(file, features).length === 0) problems.push(`unmapped: ${file} matches no feature glob`);
1812
+ for (const feature of features) problems.push(...featureProblems(workspace, feature, known, tracked));
1813
+ for (const journey of configJourneys) if (!features.some((feature) => feature.journeys.includes(journey))) problems.push(`verify.config.ts journey ${journey} is in no feature file`);
1814
+ for (const [kind, rule] of Object.entries(workspace.config.doors)) if (rule && !existsSync(join(workspace.skill, "seeded-doors", `${kind}.patch`))) problems.push(`seeded-doors/${kind}.patch is missing: the ${kind} door applies to this repository`);
1815
+ problems.push(...containmentProblems(workspace, features));
1816
+ return problems;
1817
+ }
1818
+ /** A Data or Format door is contained only by a journey, so each rule names at least one, as a registered `feature/journey`. */
1819
+ function containmentProblems(workspace, features) {
1820
+ const problems = [];
1821
+ for (const kind of ["data", "format"]) {
1822
+ const rule = workspace.config.doors[kind];
1823
+ if (!rule) continue;
1824
+ if (rule.containments.length === 0) problems.push(`doors.${kind} names no containments journey: a ${kind} door row could never pass`);
1825
+ for (const containment of rule.containments) {
1826
+ const [name, journey] = containment.split("/");
1827
+ if (!features.some((entry) => entry.name === name && entry.journeys.includes(journey))) problems.push(`doors.${kind} containment ${containment} is not a journey a feature registers`);
1828
+ }
1829
+ }
1830
+ return problems;
1831
+ }
1832
+ /** The files a change touches: committed since the merge base, staged, unstaged and untracked. */
1833
+ function changedFiles(workspace, baseSha) {
1834
+ const committed = git(workspace.root, [
1835
+ "diff",
1836
+ "--name-only",
1837
+ baseSha
1838
+ ]).split("\n");
1839
+ const untracked = git(workspace.root, [
1840
+ "ls-files",
1841
+ "--others",
1842
+ "--exclude-standard"
1843
+ ]).split("\n");
1844
+ return [...new Set([...committed, ...untracked].filter(Boolean))].sort();
1845
+ }
1846
+ /**
1847
+ * Maps the change from the merge base of `baseRef` onto features: every
1848
+ * touched feature plus the smoke feature runs, and a user-facing file outside
1849
+ * every glob is an unmapped surface.
1850
+ */
1851
+ function planFor(workspace, baseRef) {
1852
+ const features = readFeatures(workspace);
1853
+ const baseSha = git(workspace.root, [
1854
+ "merge-base",
1855
+ baseRef,
1856
+ "HEAD"
1857
+ ]);
1858
+ const changed = changedFiles(workspace, baseSha);
1859
+ const touched = features.map((feature) => ({
1860
+ feature: feature.name,
1861
+ files: changed.filter((file) => matches(file, feature.covers))
1862
+ })).filter((entry) => entry.files.length > 0);
1863
+ const unmapped = changed.filter((file) => userFacing(workspace, file) && featuresOf(file, features).length === 0);
1864
+ const touchedNames = new Set(touched.map((entry) => entry.feature));
1865
+ const docs = [...new Set(features.filter((feature) => touchedNames.has(feature.name)).flatMap((feature) => feature.docs))];
1866
+ const run = [SMOKE_FEATURE, ...[...touchedNames].filter((name) => name !== SMOKE_FEATURE)];
1867
+ const dirty = git(workspace.root, [
1868
+ "status",
1869
+ "--porcelain",
1870
+ "--untracked-files=no"
1871
+ ]).split("\n").filter(Boolean);
1872
+ return {
1873
+ baseRef,
1874
+ baseSha,
1875
+ headSha: git(workspace.root, ["rev-parse", "HEAD"]),
1876
+ changed,
1877
+ touched,
1878
+ unmapped,
1879
+ docs,
1880
+ run,
1881
+ dirty
1882
+ };
1883
+ }
1884
+ //#endregion
1885
+ //#region src/verify/publish.ts
1886
+ const EVIDENCE_BRANCH = "verify-evidence";
1887
+ const SCRATCH_BRANCH = "verify-evidence-scratch";
1888
+ const STATUS = {
1889
+ PASS: "success",
1890
+ "PASS+NOTES": "success",
1891
+ "NOT VERIFIED": "error",
1892
+ FAIL: "failure"
1893
+ };
1894
+ /**
1895
+ * Commits the run's evidence under pr-<n>/<sha>/ of the orphan evidence
1896
+ * branch and pushes it. Works in a temporary worktree so the checkout under
1897
+ * review is never touched. Returns the pushed evidence commit.
1898
+ */
1899
+ function pushEvidence(root, state, verdict) {
1900
+ const worktree = mkdtempSync(join(tmpdir(), "verify-evidence-"));
1901
+ try {
1902
+ if (git(root, [
1903
+ "ls-remote",
1904
+ "--heads",
1905
+ "origin",
1906
+ EVIDENCE_BRANCH
1907
+ ]) !== "") {
1908
+ git(root, [
1909
+ "fetch",
1910
+ "--quiet",
1911
+ "origin",
1912
+ `${EVIDENCE_BRANCH}:refs/remotes/origin/${EVIDENCE_BRANCH}`
1913
+ ]);
1914
+ git(root, [
1915
+ "worktree",
1916
+ "add",
1917
+ "--quiet",
1918
+ "--detach",
1919
+ worktree,
1920
+ `origin/${EVIDENCE_BRANCH}`
1921
+ ]);
1922
+ } else git(root, [
1923
+ "worktree",
1924
+ "add",
1925
+ "--quiet",
1926
+ "--orphan",
1927
+ "-B",
1928
+ SCRATCH_BRANCH,
1929
+ worktree
1930
+ ]);
1931
+ const target = join(worktree, `pr-${verdict.pr}`, verdict.headSha);
1932
+ rmSync(target, {
1933
+ recursive: true,
1934
+ force: true
1935
+ });
1936
+ mkdirSync(target, { recursive: true });
1937
+ cpSync(state.evidence, target, { recursive: true });
1938
+ git(worktree, [
1939
+ "add",
1940
+ "--all",
1941
+ "."
1942
+ ]);
1943
+ git(worktree, [
1944
+ "-c",
1945
+ "commit.gpgsign=false",
1946
+ "commit",
1947
+ "--quiet",
1948
+ "--allow-empty",
1949
+ "-m",
1950
+ `verify: evidence for #${verdict.pr} at ${verdict.headSha.slice(0, 7)} (${verdict.result})`
1951
+ ]);
1952
+ git(worktree, [
1953
+ "push",
1954
+ "--quiet",
1955
+ "origin",
1956
+ `HEAD:refs/heads/${EVIDENCE_BRANCH}`
1957
+ ]);
1958
+ return git(worktree, ["rev-parse", "HEAD"]);
1959
+ } finally {
1960
+ git(root, [
1961
+ "worktree",
1962
+ "remove",
1963
+ "--force",
1964
+ worktree
1965
+ ]);
1966
+ if (git(root, [
1967
+ "branch",
1968
+ "--list",
1969
+ SCRATCH_BRANCH
1970
+ ]) !== "") git(root, [
1971
+ "branch",
1972
+ "--quiet",
1973
+ "-D",
1974
+ SCRATCH_BRANCH
1975
+ ]);
1976
+ }
1977
+ }
1978
+ /** Posts the verdict as a PR comment and returns the comment URL printed by gh. */
1979
+ function postComment(root, verdict) {
1980
+ return execFileSync("gh", [
1981
+ "pr",
1982
+ "comment",
1983
+ String(verdict.pr),
1984
+ "--repo",
1985
+ verdict.repository,
1986
+ "--body",
1987
+ verdict.markdown
1988
+ ], {
1989
+ cwd: root,
1990
+ encoding: "utf8"
1991
+ }).trim();
1992
+ }
1993
+ /**
1994
+ * Sets the `verify` commit status on the head SHA the verdict judged and
1995
+ * reads it back from GitHub. Returns what GitHub holds, or the error GitHub
1996
+ * answered, so a token without `statuses: write` is reported, never hidden.
1997
+ */
1998
+ function setStatus(root, verdict, targetUrl) {
1999
+ const write = spawnSync("gh", [
2000
+ "api",
2001
+ "--silent",
2002
+ `repos/${verdict.repository}/statuses/${verdict.headSha}`,
2003
+ "-f",
2004
+ `state=${STATUS[verdict.result]}`,
2005
+ "-f",
2006
+ "context=verify",
2007
+ "-f",
2008
+ `description=verify: ${verdict.result}`,
2009
+ "-f",
2010
+ `target_url=${targetUrl}`
2011
+ ], {
2012
+ cwd: root,
2013
+ encoding: "utf8"
2014
+ });
2015
+ if (write.status !== 0) return {
2016
+ ok: false,
2017
+ detail: `setting status verify failed: ${(write.stderr || write.stdout).trim()}`
2018
+ };
2019
+ const state = spawnSync("gh", [
2020
+ "api",
2021
+ `repos/${verdict.repository}/commits/${verdict.headSha}/statuses`,
2022
+ "--jq",
2023
+ "[.[] | select(.context == \"verify\")][0].state"
2024
+ ], {
2025
+ cwd: root,
2026
+ encoding: "utf8"
2027
+ }).stdout.trim();
2028
+ return {
2029
+ ok: state === STATUS[verdict.result],
2030
+ detail: `status verify on ${verdict.headSha}: ${state || "absent"}`
2031
+ };
2032
+ }
2033
+ //#endregion
2034
+ //#region src/verify/builtins.ts
2035
+ /** Loads the module from its local source next to its backing services, then stops it. */
2036
+ const moduleDev = {
2037
+ title: "the module loads from its local source against its backing services and stops on Ctrl+C",
2038
+ entryPoint: "`ajs project dev` on a project that installs the module as `local`",
2039
+ async run(context) {
2040
+ const project = context.fixture();
2041
+ const app = await context.dev("ajs project dev", project);
2042
+ const surface = await context.driver("implemented interfaces", app, "/surface", {});
2043
+ context.expect(surface.folder, [{
2044
+ name: "the consumer loaded every implemented interface",
2045
+ pass: surface.ok,
2046
+ detail: JSON.stringify(surface.value).slice(0, 300)
2047
+ }]);
2048
+ const stopped = await context.stop("SIGINT", app);
2049
+ context.expect(stopped.folder, [interrupted(stopped)]);
2050
+ const after = await context.http("port after stop", `http://127.0.0.1:${app.port}/health`);
2051
+ context.expect(after.folder, [refused(after)]);
2052
+ }
2053
+ };
2054
+ /** Scaffolds a project from the template with `ajs project init` and installs it; returns its folder. */
2055
+ async function scaffoldProject(context) {
2056
+ const project = join(context.work, "app");
2057
+ const init = await context.scaffold("ajs project init", project);
2058
+ context.expect(init.folder, [exitIs(init, 0), exists(join(project, "antelope.config.ts"))], { critical: true });
2059
+ context.tree("scaffolded tree", project);
2060
+ const install = await context.command("pnpm install", "pnpm", [
2061
+ "install",
2062
+ "--frozen-lockfile",
2063
+ "--prefer-offline"
2064
+ ], { cwd: project });
2065
+ context.expect(install.folder, [exitIs(install, 0)], { critical: true });
2066
+ return project;
2067
+ }
2068
+ /** The journeys each kind ships, by id; a feature file names them next to its repo-owned journeys. */
2069
+ const BUILTIN_JOURNEYS = {
2070
+ interface: INTERFACE_JOURNEYS,
2071
+ module: { "module-dev": moduleDev },
2072
+ template: {
2073
+ "scaffold-dev": {
2074
+ title: "a project scaffolded from the template installs, starts and answers",
2075
+ entryPoint: "`ajs project init --template` from the interfaces manifest, then `ajs project dev --watch`, as the template's `pnpm dev` runs it",
2076
+ async run(context) {
2077
+ const app = await context.dev("ajs project dev --watch", await scaffoldProject(context), { args: ["--watch"] });
2078
+ const stopped = await context.stop("SIGINT", app);
2079
+ context.expect(stopped.folder, [interrupted(stopped)]);
2080
+ }
2081
+ },
2082
+ "scaffold-checks": {
2083
+ title: "a project scaffolded from the template passes its own checks",
2084
+ entryPoint: "`ajs project init --template` from the interfaces manifest, then `pnpm run checks`",
2085
+ async run(context) {
2086
+ const project = await scaffoldProject(context);
2087
+ const checks = await context.command("pnpm run checks", "pnpm", ["run", "checks"], { cwd: project });
2088
+ context.expect(checks.folder, [exitIs(checks, 0)]);
2089
+ }
2090
+ }
2091
+ }
2092
+ };
2093
+ //#endregion
2094
+ //#region src/verify/context.ts
2095
+ var JourneyAbort = class extends Error {};
2096
+ var NotVerified = class extends Error {};
2097
+ const READY_TIMEOUT_MS = 12e4;
2098
+ const STOP_TIMEOUT_MS = 3e4;
2099
+ const POLL_MS = 250;
2100
+ const SETTLE_MS = 3e3;
2101
+ function slug(text) {
2102
+ return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
2103
+ }
2104
+ function sleep(ms) {
2105
+ return new Promise((resolve) => setTimeout(resolve, ms));
2106
+ }
2107
+ /** The harness side of a journey: every driving call writes its evidence into a new numbered step folder. */
2108
+ var VerifyContext = class {
2109
+ repo;
2110
+ folder;
2111
+ work;
2112
+ home;
2113
+ steps = [];
2114
+ running = [];
2115
+ fixtures = /* @__PURE__ */ new Map();
2116
+ index = 0;
2117
+ workspace;
2118
+ state;
2119
+ constructor(workspace, state, feature, journey) {
2120
+ this.workspace = workspace;
2121
+ this.state = state;
2122
+ this.repo = workspace.root;
2123
+ this.folder = join(state.evidence, feature, journey);
2124
+ this.work = join(state.dir, "work", feature, journey);
2125
+ this.home = join(state.dir, "homes", feature, journey);
2126
+ for (const folder of [
2127
+ this.folder,
2128
+ this.work,
2129
+ this.home
2130
+ ]) {
2131
+ rmSync(folder, {
2132
+ recursive: true,
2133
+ force: true
2134
+ });
2135
+ mkdirSync(folder, { recursive: true });
2136
+ }
2137
+ }
2138
+ /** A fresh numbered step folder. */
2139
+ step(name) {
2140
+ this.index += 1;
2141
+ const folder = join(this.folder, `${String(this.index).padStart(2, "0")}-${slug(name)}`);
2142
+ mkdirSync(folder, { recursive: true });
2143
+ return folder;
2144
+ }
2145
+ env(extra = {}) {
2146
+ return isolatedEnv(this.workspace, this.home, extra);
2147
+ }
2148
+ command(name, program, args, options = {}) {
2149
+ return runRecorded(this.step(name), {
2150
+ program,
2151
+ args,
2152
+ cwd: options.cwd ?? this.work,
2153
+ env: this.env(options.env),
2154
+ timeoutMs: options.timeoutMs
2155
+ });
2156
+ }
2157
+ /** Runs `ajs <args>` of the repository's `@antelopejs/core`. */
2158
+ ajs(name, args, options = {}) {
2159
+ return this.command(name, process.execPath, [ajsEntry(this.repo), ...args], options);
2160
+ }
2161
+ edit(name, file, content) {
2162
+ const folder = this.step(name);
2163
+ mkdirSync(join(file, ".."), { recursive: true });
2164
+ writeFileSync(file, content);
2165
+ writeFileSync(join(folder, "edit.txt"), `${file}\n---\n${content}`);
2166
+ return folder;
2167
+ }
2168
+ tree(name, root) {
2169
+ const folder = this.step(name);
2170
+ return {
2171
+ folder,
2172
+ lines: recordTree(folder, root)
2173
+ };
2174
+ }
2175
+ http(name, url, init = {}) {
2176
+ return httpRecorded(this.step(name), url, init);
2177
+ }
2178
+ expect(folder, checks, options = {}) {
2179
+ const name = relative(this.folder, folder) || "journey";
2180
+ this.steps.push({
2181
+ name,
2182
+ folder: relative(this.state.evidence, folder),
2183
+ checks
2184
+ });
2185
+ appendFileSync(join(folder, "checks.json"), `${JSON.stringify(checks, null, 2)}\n`);
2186
+ const passed = checks.every((check) => check.pass);
2187
+ if (!passed && options.critical) throw new JourneyAbort(`critical step ${name} failed`);
2188
+ return passed;
2189
+ }
2190
+ notVerified(reason) {
2191
+ throw new NotVerified(reason);
2192
+ }
2193
+ service(name) {
2194
+ const found = this.state.containers.find((container) => container.service === name);
2195
+ if (!found) throw new Error(`No service ${name} in this run; declare it under services in verify.config.ts.`);
2196
+ return {
2197
+ name,
2198
+ container: found.name,
2199
+ host: found.host,
2200
+ port: found.port
2201
+ };
2202
+ }
2203
+ services() {
2204
+ return this.state.containers.map((container) => this.service(container.service));
2205
+ }
2206
+ native(name, service, args) {
2207
+ return this.command(name, "docker", [
2208
+ "exec",
2209
+ this.service(service).container,
2210
+ ...args
2211
+ ]);
2212
+ }
2213
+ fixture(options = {}) {
2214
+ const config = options.moduleConfig ?? this.workspace.config.moduleConfig?.(this.services()) ?? {};
2215
+ const fixture = writeFixture(this.workspace, this.state, this.work, config);
2216
+ this.fixtures.set(fixture.project, fixture);
2217
+ this.tree("fixture project", fixture.project);
2218
+ return fixture.project;
2219
+ }
2220
+ /** The log the stub provider wrote, one call per line: the provider's view of what core delivered. */
2221
+ stubCalls(project) {
2222
+ const file = this.fixtures.get(project)?.env.VERIFY_CALL_LOG;
2223
+ if (!file) return [];
2224
+ let text = "";
2225
+ try {
2226
+ text = readFileSync(file, "utf8");
2227
+ } catch {
2228
+ return [];
2229
+ }
2230
+ return text.split("\n").filter(Boolean).map((line) => parseJson(line)).filter(isObject).map((entry) => ({
2231
+ path: String(entry.path),
2232
+ args: entry.args ?? null
2233
+ }));
2234
+ }
2235
+ async dev(name, project, options = {}) {
2236
+ const port = await freePort();
2237
+ const fixture = this.fixtures.get(project);
2238
+ const env = {
2239
+ ...fixture?.env,
2240
+ VERIFY_DRIVER_PORT: String(port),
2241
+ PORT: String(port),
2242
+ ...options.env
2243
+ };
2244
+ const folder = this.step(name);
2245
+ const handle = startRecorded(folder, {
2246
+ program: process.execPath,
2247
+ args: [
2248
+ ajsEntry(this.repo),
2249
+ "project",
2250
+ "dev",
2251
+ ...options.args ?? []
2252
+ ],
2253
+ cwd: project,
2254
+ env: this.env(env)
2255
+ });
2256
+ writeFileSync(join(folder, "port.txt"), `${port}\n`);
2257
+ const app = {
2258
+ name,
2259
+ pid: handle.pid,
2260
+ folder,
2261
+ project,
2262
+ port
2263
+ };
2264
+ this.running.push({
2265
+ app,
2266
+ handle
2267
+ });
2268
+ this.state.processes.push({
2269
+ name: `${name} (${project})`,
2270
+ pid: handle.pid
2271
+ });
2272
+ saveRun(this.state);
2273
+ await this.waitReady(app, handle, fixture !== void 0);
2274
+ return app;
2275
+ }
2276
+ async probe(app, fixture, folder) {
2277
+ const probe = this.workspace.config.template?.probe;
2278
+ if (!fixture && probe?.log) {
2279
+ const output = readOutput(app.folder);
2280
+ return {
2281
+ name: `dev output matches ${probe.log}`,
2282
+ pass: probe.log.test(`${output.stdout}${output.stderr}`),
2283
+ detail: output.stderr.slice(-300)
2284
+ };
2285
+ }
2286
+ const path = fixture ? "/health" : probe?.path ?? "/";
2287
+ const answer = await httpRecorded(folder, `http://127.0.0.1:${app.port}${path}`);
2288
+ const status = fixture ? 200 : probe?.status ?? 200;
2289
+ const body = !fixture && probe?.body ? probe.body : /./s;
2290
+ return {
2291
+ name: `GET ${path} answers ${status} with ${body}`,
2292
+ pass: answer.status === status && body.test(answer.body),
2293
+ detail: answer.error ?? `status ${answer.status}, body ${answer.body.slice(0, 300)}`
2294
+ };
2295
+ }
2296
+ async waitReady(app, handle, fixture) {
2297
+ const folder = this.step("ready");
2298
+ const deadline = Date.now() + READY_TIMEOUT_MS;
2299
+ let exited = false;
2300
+ handle.exited.then(() => {
2301
+ exited = true;
2302
+ });
2303
+ let check = await this.probe(app, fixture, folder);
2304
+ while (!check.pass && !exited && Date.now() < deadline) {
2305
+ await sleep(POLL_MS);
2306
+ check = await this.probe(app, fixture, folder);
2307
+ }
2308
+ const settle = this.workspace.config.template?.probe.log ? this.workspace.config.template.probe.settleMs ?? SETTLE_MS : 0;
2309
+ if (check.pass && settle > 0) await sleep(settle);
2310
+ const alive = {
2311
+ name: "still running after readiness",
2312
+ pass: !exited,
2313
+ detail: `waited ${settle} ms`
2314
+ };
2315
+ writeFileSync(join(folder, "ready.txt"), `${check.pass && !exited ? "ready" : exited ? "exited before ready" : "timed out"}\n`);
2316
+ this.expect(folder, check.pass ? [check, alive] : [check], { critical: true });
2317
+ this.expect(folder, [check], { critical: true });
2318
+ }
2319
+ /** Posts a JSON body to a route of the driver module. */
2320
+ async driver(name, app, route, body) {
2321
+ const result = await httpRecorded(this.step(name), `http://127.0.0.1:${app.port}${route}`, {
2322
+ method: "POST",
2323
+ body: JSON.stringify(body),
2324
+ timeoutMs: 3e4
2325
+ });
2326
+ const json = result.json !== void 0 && isObject(result.json) ? result.json : {};
2327
+ return {
2328
+ ...result,
2329
+ ok: json.ok === true,
2330
+ value: json.ok === true ? json.value : json.error
2331
+ };
2332
+ }
2333
+ call(name, app, request) {
2334
+ const body = {
2335
+ path: request.path,
2336
+ args: request.args ?? [],
2337
+ chain: request.chain ?? [],
2338
+ entry: request.entry ?? "."
2339
+ };
2340
+ if (request.interface) body.interface = request.interface;
2341
+ return this.driver(name, app, "/call", body);
2342
+ }
2343
+ async stop(name, app) {
2344
+ const folder = this.step(name);
2345
+ writeFileSync(join(folder, "command.txt"), `kill -INT ${app.pid}\n`);
2346
+ const running = this.running.find((entry) => entry.app.pid === app.pid);
2347
+ try {
2348
+ process.kill(app.pid, "SIGINT");
2349
+ } catch {
2350
+ writeFileSync(join(folder, "note.txt"), "process was already gone\n");
2351
+ }
2352
+ let timer;
2353
+ const timeout = new Promise((resolve) => {
2354
+ timer = setTimeout(() => resolve(void 0), STOP_TIMEOUT_MS);
2355
+ });
2356
+ const outcome = running ? await Promise.race([running.handle.exited, timeout]) : {
2357
+ exitCode: null,
2358
+ signal: null
2359
+ };
2360
+ clearTimeout(timer);
2361
+ if (!outcome) {
2362
+ killGroup(app.pid);
2363
+ writeFileSync(join(folder, "note.txt"), `no exit within ${STOP_TIMEOUT_MS} ms of SIGINT; killed the process group\n`);
2364
+ }
2365
+ const exit = outcome ?? {
2366
+ exitCode: null,
2367
+ signal: "SIGKILL"
2368
+ };
2369
+ writeFileSync(join(folder, "exit-code.txt"), `${exit.exitCode ?? `signal ${exit.signal}`}\n`);
2370
+ this.untrack(app.pid);
2371
+ return {
2372
+ ...exit,
2373
+ ...readOutput(app.folder),
2374
+ folder
2375
+ };
2376
+ }
2377
+ untrack(pid) {
2378
+ const index = this.running.findIndex((entry) => entry.app.pid === pid);
2379
+ if (index !== -1) this.running.splice(index, 1);
2380
+ this.state.processes = this.state.processes.filter((record) => record.pid !== pid);
2381
+ saveRun(this.state);
2382
+ }
2383
+ async scaffold(name, project, flags = [
2384
+ "--pm",
2385
+ "pnpm",
2386
+ "--git-init"
2387
+ ]) {
2388
+ const set = await this.ajs("config set git", [
2389
+ "config",
2390
+ "set",
2391
+ "git",
2392
+ this.state.manifestUrl
2393
+ ]);
2394
+ this.expect(set.folder, [{
2395
+ name: "git setting points at the offline manifest",
2396
+ pass: set.exitCode === 0,
2397
+ detail: set.stderr.slice(-300)
2398
+ }], { critical: true });
2399
+ return this.ajs(name, [
2400
+ "project",
2401
+ "init",
2402
+ relative(this.work, project),
2403
+ "--template",
2404
+ this.state.templateName,
2405
+ ...flags
2406
+ ]);
2407
+ }
2408
+ /** Stops every app the journey left running. */
2409
+ async cleanup() {
2410
+ for (const entry of this.running.slice()) await this.stop(`cleanup ${entry.app.name}`, entry.app);
2411
+ }
2412
+ /** Records why the journey ended without a verdict on the product. */
2413
+ static reasonOf(failure) {
2414
+ if (failure instanceof NotVerified) return {
2415
+ error: null,
2416
+ notVerified: failure.message
2417
+ };
2418
+ if (failure instanceof JourneyAbort) return {
2419
+ error: failure.message,
2420
+ notVerified: null
2421
+ };
2422
+ return {
2423
+ error: failure.stack ?? failure.message,
2424
+ notVerified: null
2425
+ };
2426
+ }
2427
+ };
2428
+ //#endregion
2429
+ //#region src/verify/runner.ts
2430
+ /** Every journey id a feature file may name: the kind's built-in journeys and the repo's own. */
2431
+ function knownJourneys(workspace) {
2432
+ return new Map([...Object.entries(BUILTIN_JOURNEYS[workspace.kind]), ...Object.entries(workspace.config.journeys ?? {})]);
2433
+ }
2434
+ /** The journeys a feature file registers, in order. */
2435
+ function featureJourneys(workspace, feature) {
2436
+ return readFeatures(workspace).find((entry) => entry.name === feature)?.journeys;
2437
+ }
2438
+ function resetServices(context) {
2439
+ for (const [name, service] of Object.entries(context.workspace.config.services ?? {})) {
2440
+ if (!service.reset) continue;
2441
+ const container = context.service(name).container;
2442
+ const run = spawnSync("docker", [
2443
+ "exec",
2444
+ container,
2445
+ ...service.reset
2446
+ ], { encoding: "utf8" });
2447
+ const folder = context.step(`reset ${name}`);
2448
+ writeFileSync(join(folder, "command.txt"), `docker exec ${container} ${service.reset.join(" ")}\n`);
2449
+ writeFileSync(join(folder, "stdout.txt"), run.stdout ?? "");
2450
+ writeFileSync(join(folder, "stderr.txt"), run.stderr ?? "");
2451
+ context.expect(folder, [{
2452
+ name: `${name} reset to a clean state`,
2453
+ pass: run.status === 0,
2454
+ detail: `exit ${run.status}`
2455
+ }], { critical: true });
2456
+ }
2457
+ }
2458
+ function statusOf(context, failure) {
2459
+ if (failure.notVerified !== null) return "NOT VERIFIED";
2460
+ return failure.error !== null || context.steps.some((step) => step.checks.some((check) => !check.pass)) || context.steps.length === 0 ? "FAIL" : "PASS";
2461
+ }
2462
+ async function runOne(workspace, state, feature, id, journey) {
2463
+ const context = new VerifyContext(workspace, state, feature, id);
2464
+ let failure = {
2465
+ error: null,
2466
+ notVerified: null
2467
+ };
2468
+ try {
2469
+ if (state.missingKeys.length > 0) context.notVerified(`provider sandbox keys missing from the environment: ${state.missingKeys.join(", ")}`);
2470
+ resetServices(context);
2471
+ await journey.run(context);
2472
+ } catch (error) {
2473
+ failure = VerifyContext.reasonOf(error instanceof Error ? error : new Error(String(error)));
2474
+ }
2475
+ await context.cleanup();
2476
+ const result = {
2477
+ feature,
2478
+ journey: id,
2479
+ title: journey.title,
2480
+ entryPoint: journey.entryPoint,
2481
+ status: statusOf(context, failure),
2482
+ steps: context.steps,
2483
+ ...failure,
2484
+ folder: relative(state.evidence, context.folder)
2485
+ };
2486
+ writeFileSync(join(context.folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
2487
+ return result;
2488
+ }
2489
+ /** Reads the merged results of a feature in a run, if any journey of it ran. */
2490
+ function readResults(state, feature) {
2491
+ const file = join(state.evidence, feature, "feature.json");
2492
+ if (!existsSync(file)) return void 0;
2493
+ return JSON.parse(readFileSync(file, "utf8"));
2494
+ }
2495
+ /**
2496
+ * Runs the named journeys of a feature, or all of them, and merges their
2497
+ * results into feature.json so partial runs add up instead of overwriting.
2498
+ */
2499
+ async function runFeature(workspace, state, feature, ids) {
2500
+ const registered = featureJourneys(workspace, feature);
2501
+ if (registered === void 0) throw new Error(`Unknown feature ${feature}: no features/${feature}.md`);
2502
+ const unknown = ids.filter((id) => !registered.includes(id));
2503
+ if (unknown.length > 0) throw new Error(`${feature} registers no journey ${unknown.join(", ")}; it registers ${registered.join(", ")}`);
2504
+ const known = knownJourneys(workspace);
2505
+ const results = [];
2506
+ for (const id of ids.length > 0 ? ids : registered) {
2507
+ const journey = known.get(id);
2508
+ if (journey === void 0) throw new Error(`${feature} names journey ${id}, which is neither built in nor in verify.config.ts journeys`);
2509
+ results.push(await runOne(workspace, state, feature, id, journey));
2510
+ }
2511
+ const earlier = readResults(state, feature) ?? [];
2512
+ const merged = registered.flatMap((id) => results.filter((result) => result.journey === id).concat(results.some((result) => result.journey === id) ? [] : earlier.filter((result) => result.journey === id)));
2513
+ writeFileSync(join(state.evidence, feature, "feature.json"), `${JSON.stringify(merged, null, 2)}\n`);
2514
+ return results;
2515
+ }
2516
+ //#endregion
2517
+ //#region src/verify/seeded.ts
2518
+ function inTree(worktree, program, args) {
2519
+ return execFileSync(program, args, {
2520
+ cwd: worktree,
2521
+ encoding: "utf8",
2522
+ env: {
2523
+ ...process.env,
2524
+ CI: "1"
2525
+ },
2526
+ stdio: [
2527
+ "ignore",
2528
+ "pipe",
2529
+ "pipe"
2530
+ ]
2531
+ }).trim();
2532
+ }
2533
+ function prepareWorktree(workspace, label, feature) {
2534
+ const worktree = mkdtempSync(join(tmpdir(), `antelopejs-verify-seeded-${label}-`));
2535
+ execFileSync("git", [
2536
+ "worktree",
2537
+ "add",
2538
+ "--detach",
2539
+ "--force",
2540
+ worktree,
2541
+ "HEAD"
2542
+ ], {
2543
+ cwd: workspace.root,
2544
+ stdio: "ignore"
2545
+ });
2546
+ try {
2547
+ const skill = join(worktree, relative(workspace.root, workspace.skill));
2548
+ rmSync(skill, {
2549
+ recursive: true,
2550
+ force: true
2551
+ });
2552
+ cpSync(workspace.skill, skill, {
2553
+ recursive: true,
2554
+ verbatimSymlinks: true
2555
+ });
2556
+ if (feature !== null) inTree(worktree, "git", ["apply", join(skill, "seeded-breaks", `${feature}.patch`)]);
2557
+ inTree(worktree, "pnpm", [
2558
+ "install",
2559
+ "--frozen-lockfile",
2560
+ "--prefer-offline",
2561
+ "--ignore-scripts"
2562
+ ]);
2563
+ } catch (error) {
2564
+ removeWorktree(workspace, worktree);
2565
+ throw error;
2566
+ }
2567
+ return worktree;
2568
+ }
2569
+ function removeWorktree(workspace, worktree) {
2570
+ execFileSync("git", [
2571
+ "worktree",
2572
+ "remove",
2573
+ "--force",
2574
+ worktree
2575
+ ], {
2576
+ cwd: workspace.root,
2577
+ stdio: "ignore"
2578
+ });
2579
+ }
2580
+ function runFeatureIn(bin, worktree, feature, baseRef) {
2581
+ const created = spawnSync(process.execPath, [
2582
+ bin,
2583
+ "new",
2584
+ "--base",
2585
+ baseRef
2586
+ ], {
2587
+ cwd: worktree,
2588
+ encoding: "utf8"
2589
+ });
2590
+ const run = created.stdout.trim().split("\n").at(-1) ?? "";
2591
+ if (created.status !== 0 || !existsSync(join(run, "run.json"))) return {
2592
+ run,
2593
+ results: [],
2594
+ output: `${created.stdout}${created.stderr}`
2595
+ };
2596
+ const journeys = spawnSync(process.execPath, [
2597
+ bin,
2598
+ "journey",
2599
+ run,
2600
+ feature
2601
+ ], {
2602
+ cwd: worktree,
2603
+ encoding: "utf8"
2604
+ });
2605
+ const cleaned = spawnSync(process.execPath, [
2606
+ bin,
2607
+ "clean",
2608
+ run
2609
+ ], {
2610
+ cwd: worktree,
2611
+ encoding: "utf8"
2612
+ });
2613
+ return {
2614
+ run,
2615
+ results: readResults(loadRun(run), feature) ?? [],
2616
+ output: `${journeys.stdout}${journeys.stderr}${cleaned.stderr}`
2617
+ };
2618
+ }
2619
+ function failsACheck(result) {
2620
+ return result.steps.some((step) => step.checks.some((check) => !check.pass));
2621
+ }
2622
+ /** A break is caught only by a journey that passes in the control and fails one of its checks with the patch. */
2623
+ function judgeSeeded(feature, control, seeded) {
2624
+ const passedInControl = new Set(control.results.filter((result) => result.status === "PASS").map((result) => result.journey));
2625
+ const failed = seeded.results.filter((result) => result.status === "FAIL");
2626
+ return {
2627
+ feature,
2628
+ caught: failed.some((result) => passedInControl.has(result.journey) && failsACheck(result)),
2629
+ run: seeded.run,
2630
+ controlRun: control.run,
2631
+ caughtBy: failed.filter((result) => passedInControl.has(result.journey) && failsACheck(result)).map((result) => result.journey),
2632
+ failingInControl: control.results.filter((result) => result.status !== "PASS").map((result) => result.journey),
2633
+ harnessErrors: failed.filter((result) => !failsACheck(result)).map((result) => result.journey),
2634
+ output: seeded.output
2635
+ };
2636
+ }
2637
+ /**
2638
+ * Runs each feature's journeys twice from scratch worktrees of HEAD, with the
2639
+ * skill folder as it is in the checkout: once unpatched as the control, once
2640
+ * with seeded-breaks/<feature>.patch applied. Each run is cleaned afterwards;
2641
+ * both runs' evidence stays.
2642
+ */
2643
+ function runSeededBreaks(workspace, bin, features, baseRef) {
2644
+ const controlTree = prepareWorktree(workspace, "control", null);
2645
+ try {
2646
+ return features.map((feature) => {
2647
+ const control = runFeatureIn(bin, controlTree, feature, baseRef);
2648
+ const seededTree = prepareWorktree(workspace, feature, feature);
2649
+ try {
2650
+ return judgeSeeded(feature, control, runFeatureIn(bin, seededTree, feature, baseRef));
2651
+ } finally {
2652
+ removeWorktree(workspace, seededTree);
2653
+ }
2654
+ });
2655
+ } finally {
2656
+ removeWorktree(workspace, controlTree);
2657
+ }
2658
+ }
2659
+ /** Checks every seeded-doors/<kind>.patch: the path rules must flag its own kind. */
2660
+ function checkSeededDoors(workspace) {
2661
+ const folder = join(workspace.skill, "seeded-doors");
2662
+ if (!existsSync(folder)) return [];
2663
+ return readdirSync(folder).filter((file) => file.endsWith(".patch")).sort().map((file) => {
2664
+ const kind = file.replace(/\.patch$/, "");
2665
+ const kinds = flaggedDoors(workspace, patchFiles(join(folder, file))).map((door) => door.kind);
2666
+ return {
2667
+ kind,
2668
+ flagged: kinds.some((found) => found === kind),
2669
+ kinds
2670
+ };
2671
+ });
2672
+ }
2673
+ //#endregion
2674
+ //#region src/verify/verdict.ts
2675
+ const CONTAINED_KINDS = /* @__PURE__ */ new Set(["data", "format"]);
2676
+ /** The GitHub `owner/repo` of the origin remote. */
2677
+ function originRepository(root) {
2678
+ const url = git(root, [
2679
+ "remote",
2680
+ "get-url",
2681
+ "origin"
2682
+ ]);
2683
+ const match = /github\.com[:/](.+?)(?:\.git)?$/.exec(url);
2684
+ if (!match) throw new Error(`origin ${url} is not a GitHub repository`);
2685
+ return match[1];
2686
+ }
2687
+ function short(sha) {
2688
+ return sha.slice(0, 7);
2689
+ }
2690
+ function bullets(entries, empty) {
2691
+ return (entries.length > 0 ? entries : [empty]).map((entry) => `- ${entry}`);
2692
+ }
2693
+ function journeyRows(workspace, state, plan, link) {
2694
+ const rows = [];
2695
+ const reasons = [];
2696
+ const notVerified = [];
2697
+ const byJourney = /* @__PURE__ */ new Map();
2698
+ for (const feature of plan.run) {
2699
+ const results = readResults(state, feature) ?? [];
2700
+ const registered = featureJourneys(workspace, feature) ?? [];
2701
+ for (const id of registered.filter((journey) => !results.some((result) => result.journey === journey))) reasons.push(`${feature}/${id} was not run`);
2702
+ for (const result of results) {
2703
+ if (!registered.includes(result.journey)) reasons.push(`${feature}/${result.journey} is not a registered journey`);
2704
+ byJourney.set(`${feature}/${result.journey}`, result);
2705
+ if (result.status === "FAIL") reasons.push(`${feature}/${result.journey} failed`);
2706
+ if (result.status === "NOT VERIFIED") notVerified.push(`${feature}/${result.journey}: ${result.notVerified}`);
2707
+ const outcome = result.status === "PASS" ? "pass" : result.status === "FAIL" ? "**fail**" : "**not verified**";
2708
+ rows.push(`| ${feature} | \`${result.journey}\`: ${result.entryPoint} | ${outcome}: ${result.title} | [${result.folder}](${link(result.folder)}) |`);
2709
+ }
2710
+ }
2711
+ return {
2712
+ rows,
2713
+ reasons,
2714
+ notVerified,
2715
+ byJourney
2716
+ };
2717
+ }
2718
+ function doorReasons(workspace, judgement, results, plan) {
2719
+ const reasons = [];
2720
+ for (const row of judgement.doors.filter((door) => CONTAINED_KINDS.has(door.kind))) {
2721
+ const allowed = workspace.config.doors[row.kind]?.containments ?? [];
2722
+ const journey = results.get(row.containmentJourney);
2723
+ if (!allowed.includes(row.containmentJourney)) reasons.push(`${row.kind} door at ${row.location} names ${row.containmentJourney || "no journey"}; its containment must be one of ${allowed.join(", ") || "the kind's containments in verify.config.ts, which lists none"}`);
2724
+ else if (journey?.status !== "PASS") reasons.push(`${row.kind} door at ${row.location}: containment journey ${row.containmentJourney} did not pass in this run`);
2725
+ }
2726
+ for (const door of flaggedDoors(workspace, plan.changed)) for (const file of door.files) {
2727
+ const listed = judgement.doors.some((row) => row.kind === door.kind && row.location.includes(file));
2728
+ const dismissed = judgement.falsePositives.some((entry) => entry.kind === door.kind && entry.location === file);
2729
+ if (!listed && !dismissed) reasons.push(`path rules flag a ${door.kind} door at ${file} that the One-way doors section neither lists nor dismisses`);
2730
+ }
2731
+ return reasons;
2732
+ }
2733
+ function doorsSection(judgement) {
2734
+ const dismissed = judgement.falsePositives.map((entry) => `- Not a door: \`${entry.location}\` matches the ${entry.kind} path rules. ${entry.reason}`);
2735
+ if (judgement.doors.length === 0) return [`None: ${judgement.doorsNone}`, ...dismissed];
2736
+ return [
2737
+ ...dismissed,
2738
+ "| Kind | Location | What cannot be undone | Containment |",
2739
+ "|---|---|---|---|",
2740
+ ...judgement.doors.map((door) => `| ${door.kind} | \`${door.location}\` | ${door.irreversible} | ${door.containment}${door.containmentJourney ? ` (journey \`${door.containmentJourney}\`)` : ""} |`)
2741
+ ];
2742
+ }
2743
+ function formalSection(workspace, state, plan, link) {
2744
+ const reasons = [];
2745
+ const lines = [];
2746
+ const touched = touchedFormalChecks(workspace, plan.changed).map((check) => check.name);
2747
+ for (const check of workspace.config.formal ?? []) {
2748
+ const result = readFormalResult(state, check.name);
2749
+ const gate = touched.includes(check.name);
2750
+ if (!result) {
2751
+ if (gate) reasons.push(`formal check ${check.name} covers the diff but was not run`);
2752
+ continue;
2753
+ }
2754
+ if (gate && (result.violated.length > 0 || result.exitCode !== 0)) reasons.push(`formal check ${check.name}: ${result.violated.length > 0 ? `violated ${result.violated.join(", ")}` : `exit ${result.exitCode}`}`);
2755
+ const summary = result.violated.length > 0 ? `violated: ${result.violated.join(", ")}` : `exit ${result.exitCode}, no violated rule`;
2756
+ lines.push(`\`${check.name}\` (${gate ? "covers the diff, gates the verdict" : "does not cover the diff, informational"}): ${summary}. [evidence](${link(result.folder)})`);
2757
+ }
2758
+ return {
2759
+ reasons,
2760
+ lines
2761
+ };
2762
+ }
2763
+ function docsReasons(judgement, plan) {
2764
+ return plan.docs.flatMap((page) => {
2765
+ const docs = judgement.docs.find((entry) => entry.page === page);
2766
+ if (!docs) return [`docs page ${page} of a touched feature has no judgement`];
2767
+ return docs.matches ? [] : [`${page} no longer matches the behaviour`];
2768
+ });
2769
+ }
2770
+ function resultOf(reasons, notVerified, notes) {
2771
+ if (reasons.length > 0) return "FAIL";
2772
+ if (notVerified.length > 0) return "NOT VERIFIED";
2773
+ return notes > 0 ? "PASS+NOTES" : "PASS";
2774
+ }
2775
+ /**
2776
+ * Computes the verdict of a run from its journey results, the diff plan and
2777
+ * the verifier's judgement, and writes verdict.md, verdict.json and plan.json
2778
+ * into the evidence folder.
2779
+ */
2780
+ function renderVerdict(workspace, state, pr, judgement) {
2781
+ const plan = planFor(workspace, state.baseRef);
2782
+ const repository = originRepository(workspace.root);
2783
+ const skillSha = git(workspace.root, [
2784
+ "log",
2785
+ "-1",
2786
+ "--format=%H",
2787
+ "--",
2788
+ relative(workspace.root, workspace.skill)
2789
+ ]) || plan.headSha;
2790
+ const link = (path) => `https://github.com/${repository}/tree/verify-evidence/pr-${pr}/${plan.headSha}/${path}`;
2791
+ const reasons = [];
2792
+ if (plan.headSha !== state.headSha) reasons.push(`the run was created at ${short(state.headSha)} but HEAD is ${short(plan.headSha)}`);
2793
+ const journeys = journeyRows(workspace, state, plan, link);
2794
+ const formal = formalSection(workspace, state, plan, link);
2795
+ reasons.push(...journeys.reasons, ...plan.unmapped.map((file) => `unmapped surface ${file}`), ...docsReasons(judgement, plan), ...doorReasons(workspace, judgement, journeys.byJourney, plan), ...formal.reasons);
2796
+ const notVerified = [...journeys.notVerified, ...judgement.notVerified];
2797
+ const result = resultOf(reasons, journeys.notVerified, notVerified.length + judgement.attention.length);
2798
+ const touched = plan.touched.map((entry) => `\`${entry.feature}\` (diff: ${entry.files.map((file) => `\`${file}\``).join(", ")})`);
2799
+ const markdown = [
2800
+ `## Verify: ${result}`,
2801
+ "",
2802
+ "### One-way doors",
2803
+ ...doorsSection(judgement),
2804
+ "",
2805
+ `**Head** \`${short(plan.headSha)}\` · **Skill** \`verify-${workspace.kind}\` @ \`${short(skillSha)}\` (not trusted yet) · **Verifier** ${judgement.verifier}`,
2806
+ "",
2807
+ "### Touched features",
2808
+ ...bullets(touched, "none"),
2809
+ `- ${SMOKE_FEATURE}: runs on every verdict`,
2810
+ "",
2811
+ ...plan.unmapped.length > 0 ? [
2812
+ "### Unmapped surfaces",
2813
+ ...plan.unmapped.map((file) => `- \`${file}\` matches no feature glob; add it to a feature file.`),
2814
+ ""
2815
+ ] : [],
2816
+ ...reasons.length > 0 ? [
2817
+ "### Why it fails",
2818
+ ...reasons.map((reason) => `- ${reason}`),
2819
+ ""
2820
+ ] : [],
2821
+ "### Journeys",
2822
+ "| Feature | Entry point | Result | Evidence |",
2823
+ "|---|---|---|---|",
2824
+ ...journeys.rows,
2825
+ "",
2826
+ "### Formal checks",
2827
+ ...bullets(formal.lines, "None configured."),
2828
+ "",
2829
+ "### Docs",
2830
+ ...bullets(judgement.docs.map((docs) => `\`${docs.page}\`: ${docs.matches ? "matches" : "**stale**"}${docs.note ? `. ${docs.note}` : ""}`), "No touched feature links a page."),
2831
+ "",
2832
+ "### Not verified",
2833
+ ...bullets(notVerified, "Nothing."),
2834
+ "",
2835
+ "### Attention",
2836
+ ...bullets(judgement.attention, "Nothing."),
2837
+ "",
2838
+ `Evidence: \`verify-evidence\` branch, [\`pr-${pr}/${plan.headSha}/\`](${link("")})`,
2839
+ ""
2840
+ ].join("\n");
2841
+ writeFileSync(join(state.evidence, "verdict.md"), markdown);
2842
+ writeFileSync(join(state.evidence, "plan.json"), `${JSON.stringify(plan, null, 2)}\n`);
2843
+ writeFileSync(join(state.evidence, "verdict.json"), `${JSON.stringify({
2844
+ result,
2845
+ headSha: plan.headSha,
2846
+ skillSha,
2847
+ pr,
2848
+ reasons
2849
+ }, null, 2)}\n`);
2850
+ return {
2851
+ result,
2852
+ headSha: plan.headSha,
2853
+ skillSha,
2854
+ pr,
2855
+ repository,
2856
+ markdown,
2857
+ reasons
2858
+ };
2859
+ }
2860
+ //#endregion
2861
+ //#region src/bin/verify.ts
2862
+ const USAGE = `Usage: antelopejs-verify <command>
2863
+
2864
+ map check every user-facing file is covered and every feature is complete
2865
+ plan [--base <ref>] map the diff to features; list unmapped surfaces
2866
+ new [--base <ref>] [--title <t>] build, prepare an isolated run, print its folder
2867
+ doctor <run> check the run is worth driving
2868
+ journey <run> <feature> [ids...] run a feature's journeys and record evidence
2869
+ formal <run> [--all] run the formal checks that cover the diff, or every one
2870
+ doors [patch] [--base <ref>] print the One-way-door line for a patch, or for the diff
2871
+ seeded <feature...> [--base <ref>] run each feature unpatched and with its seeded break
2872
+ seeded-doors check every seeded door is flagged with its kind
2873
+ clean <run> stop what the run started, keep only the evidence
2874
+ verdict <run> --pr <n> render evidence/verdict.md from the results and evidence/judgement.json
2875
+ publish <run> --pr <n> push the evidence to verify-evidence, comment the verdict, set status verify
2876
+ `;
2877
+ function print(text) {
2878
+ process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
2879
+ }
2880
+ function detectKind(root, flag) {
2881
+ if (flag !== void 0) {
2882
+ if (!isVerifyKind(flag)) throw new Error(`--kind must be one of ${VERIFY_KINDS.join(", ")}`);
2883
+ return flag;
2884
+ }
2885
+ const found = VERIFY_KINDS.filter((kind) => existsSync(join(root, skillFolder(kind), "SKILL.md")));
2886
+ if (found.length !== 1) throw new Error(found.length === 0 ? "No shared verification skill in this repository: run antelopejs-sync --verify <kind>." : `Several shared verification skills: ${found.join(", ")}. Pass --kind.`);
2887
+ return found[0];
2888
+ }
2889
+ function printMap(workspace) {
2890
+ const problems = checkMap(workspace, [...knownJourneys(workspace).keys()]);
2891
+ for (const problem of problems) print(problem);
2892
+ return problems.length === 0 ? 0 : 1;
2893
+ }
2894
+ async function runJourneys(workspace, dir, feature, ids) {
2895
+ const results = await runFeature(workspace, loadRun(dir), feature, ids);
2896
+ for (const result of results) {
2897
+ print(`${result.status} ${feature}/${result.journey}`);
2898
+ for (const step of result.steps) for (const check of step.checks.filter((entry) => !entry.pass)) print(` ${step.name}: ${check.name} (${check.detail})`);
2899
+ if (result.error) print(` ${result.error.split("\n")[0]}`);
2900
+ if (result.notVerified) print(` ${result.notVerified}`);
2901
+ }
2902
+ return results.every((result) => result.status === "PASS") ? 0 : 1;
2903
+ }
2904
+ function runFormal(workspace, dir, all) {
2905
+ const state = loadRun(dir);
2906
+ const checks = all ? workspace.config.formal ?? [] : touchedFormalChecks(workspace, planFor(workspace, state.baseRef).changed);
2907
+ for (const check of checks) {
2908
+ const result = runFormalCheck(workspace, state, check);
2909
+ print(`${result.violated.length > 0 ? "VIOLATED" : result.exitCode === 0 ? "HOLDS" : "ERROR"} ${check.name}${result.violated.length > 0 ? `: ${result.violated.join(", ")}` : ""} (exit ${result.exitCode})`);
2910
+ }
2911
+ if (checks.length === 0) print("no formal check covers the diff");
2912
+ return checks.every((check) => readFormalResult(state, check.name)?.exitCode === 0) ? 0 : 1;
2913
+ }
2914
+ function printDoors(workspace, files) {
2915
+ const doors = flaggedDoors(workspace, files);
2916
+ print(doorLine(doors) || "One-way-door: none flagged by path rules");
2917
+ for (const door of doors) print(` ${door.kind}: ${door.files.join(", ")}`);
2918
+ return 0;
2919
+ }
2920
+ function runSeeded(workspace, features, baseRef) {
2921
+ const results = runSeededBreaks(workspace, process.argv[1], features, baseRef);
2922
+ for (const result of results) {
2923
+ print(`${result.caught ? "CAUGHT" : "MISSED"} ${result.feature} by ${result.caughtBy.join(", ") || "no journey"} (evidence ${result.run}/evidence/${result.feature}, control ${result.controlRun}/evidence/${result.feature})`);
2924
+ if (result.failingInControl.length > 0) print(` not passing without the patch, not counted: ${result.failingInControl.join(", ")}`);
2925
+ if (result.harnessErrors.length > 0) print(` failed without a failing check (harness error), not counted: ${result.harnessErrors.join(", ")}`);
2926
+ print(result.output.replace(/^/gm, " "));
2927
+ }
2928
+ return results.every((result) => result.caught) ? 0 : 1;
2929
+ }
2930
+ function runSeededDoors(workspace) {
2931
+ const doors = checkSeededDoors(workspace);
2932
+ for (const door of doors) print(`${door.flagged ? "FLAGGED" : "MISSED"} ${door.kind} (path rules flag: ${door.kinds.join(", ") || "nothing"})`);
2933
+ return doors.every((door) => door.flagged) ? 0 : 1;
2934
+ }
2935
+ function judge(workspace, command, dir, pr) {
2936
+ if (!Number.isInteger(pr) || pr <= 0) throw new Error(`${command} needs --pr <number>`);
2937
+ const state = loadRun(dir);
2938
+ const verdict = renderVerdict(workspace, state, pr, readJudgement(join(state.evidence, "judgement.json")));
2939
+ print(verdict.markdown);
2940
+ if (command === "publish") {
2941
+ print(`evidence commit ${pushEvidence(workspace.root, state, verdict)}`);
2942
+ const comment = postComment(workspace.root, verdict);
2943
+ print(`comment ${comment}`);
2944
+ const status = setStatus(workspace.root, verdict, comment);
2945
+ print(status.detail);
2946
+ if (!status.ok) return 1;
2947
+ }
2948
+ return verdict.result === "PASS" || verdict.result === "PASS+NOTES" ? 0 : 1;
2949
+ }
2950
+ async function main(argv) {
2951
+ const { positionals, values } = parseArgs({
2952
+ args: argv,
2953
+ allowPositionals: true,
2954
+ options: {
2955
+ base: {
2956
+ type: "string",
2957
+ default: "origin/main"
2958
+ },
2959
+ title: {
2960
+ type: "string",
2961
+ default: ""
2962
+ },
2963
+ pr: { type: "string" },
2964
+ all: { type: "boolean" },
2965
+ kind: { type: "string" }
2966
+ }
2967
+ });
2968
+ const [command, ...rest] = positionals;
2969
+ if (command === void 0) {
2970
+ print(USAGE);
2971
+ return 0;
2972
+ }
2973
+ const root = repositoryRoot();
2974
+ const workspace = await openWorkspace(root, detectKind(root, values.kind));
2975
+ if (command === "new") print((await createRun(workspace, values.base, values.title)).dir);
2976
+ else if (command === "map") return printMap(workspace);
2977
+ else if (command === "plan") {
2978
+ const plan = planFor(workspace, values.base);
2979
+ print(JSON.stringify(plan, null, 2));
2980
+ return plan.unmapped.length === 0 ? 0 : 1;
2981
+ } else if (command === "doctor") {
2982
+ const lines = doctor(workspace, loadRun(rest[0]));
2983
+ for (const line of lines) print(`${line.ok ? "ok " : "FAIL"} ${line.check}: ${line.detail}`);
2984
+ return lines.every((line) => line.ok) ? 0 : 1;
2985
+ } else if (command === "journey") return runJourneys(workspace, rest[0], rest[1], rest.slice(2));
2986
+ else if (command === "formal") return runFormal(workspace, rest[0], values.all === true);
2987
+ else if (command === "doors") return printDoors(workspace, rest[0] ? patchFiles(rest[0]) : planFor(workspace, values.base).changed);
2988
+ else if (command === "seeded") return runSeeded(workspace, rest, values.base);
2989
+ else if (command === "seeded-doors") return runSeededDoors(workspace);
2990
+ else if (command === "clean") for (const line of clean(loadRun(rest[0]))) print(line);
2991
+ else if (command === "verdict" || command === "publish") return judge(workspace, command, rest[0], Number(values.pr));
2992
+ else {
2993
+ print(USAGE);
2994
+ return 2;
2995
+ }
2996
+ return 0;
2997
+ }
2998
+ runCliAsync(() => main(process.argv.slice(2)));
2999
+ //#endregion
3000
+ export {};