@antelopejs/tooling-configs 0.4.1 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -29
- package/dist/bin/api-diff.mjs +235 -37
- package/dist/bin/body-check.mjs +14 -11
- package/dist/bin/capture.mjs +173 -54
- package/dist/bin/check-size.mjs +1 -1
- package/dist/bin/checks.mjs +166 -11
- package/dist/bin/comment-proof.mjs +29 -7
- package/dist/bin/garden.mjs +8 -58
- package/dist/bin/lease.mjs +48 -11
- package/dist/bin/ratchet.mjs +48 -14
- package/dist/bin/suppressions.mjs +3 -3
- package/dist/bin/sync.mjs +199 -80
- package/dist/bin/verify.mjs +1163 -474
- package/dist/capture/index.d.mts +6 -1
- package/dist/capture/index.mjs +1 -1
- package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
- package/dist/eslint.d.mts +16 -3
- package/dist/eslint.mjs +21 -6
- package/dist/formal/index.d.mts +20 -4
- package/dist/formal/index.mjs +71 -19
- package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
- package/dist/oxc/anti-slop/index.mjs +156 -421
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +789 -103
- package/dist/oxc/lint.d.mts +13 -15
- package/dist/oxc/lint.mjs +19 -29
- package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
- package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
- package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-ClfblHNJ.mjs} +18 -15
- package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
- package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
- package/dist/semver-BDxeEcP_.mjs +57 -0
- package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
- package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
- package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
- package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
- package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
- package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
- package/dist/verify/index.d.mts +60 -15
- package/package.json +3 -1
- package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
package/dist/bin/sync.mjs
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { a as formatCeilings, l as readCeilings, s as isRetired, t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
|
|
3
|
-
import { a as
|
|
4
|
-
import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-
|
|
3
|
+
import { a as parseManifest, c as toolingVersions, i as packageManager, o as repositoryTools, r as managedPackage, s as templatePackage, t as addedDevDependencies } from "../package-Dn7VTFUW.mjs";
|
|
4
|
+
import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-lJBZFskp.mjs";
|
|
5
5
|
import { a as VERIFY_KINDS, c as isVerifyKind, i as SYNCED_SKILL_FILES, l as skillFolder, o as claudeLink, s as claudeLinkTarget, u as planDocsSkills } from "../shared-igPpEDpS.mjs";
|
|
6
6
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
7
7
|
import { a as gitFiles, c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
|
|
8
|
-
import { i as recordedRelease, t as measureBaseline } from "../ratchet-
|
|
9
|
-
import { a as ciWorkflow, c as ciNodeCallers, l as ciRenovateSyncCallers, o as placeholderTestScript, p as renovateArtifacts, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW, u as hasChecksWorkflow } from "../ci-workflow-
|
|
10
|
-
import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-
|
|
11
|
-
import { t as DEFAULT_SHARED } from "../map-
|
|
8
|
+
import { i as recordedRelease, t as measureBaseline } from "../ratchet-ClfblHNJ.mjs";
|
|
9
|
+
import { a as ciWorkflow, c as ciNodeCallers, l as ciRenovateSyncCallers, o as placeholderTestScript, p as renovateArtifacts, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW, u as hasChecksWorkflow } from "../ci-workflow-COJUT12b.mjs";
|
|
10
|
+
import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Dvb_IqBo.mjs";
|
|
11
|
+
import { t as DEFAULT_SHARED } from "../map-DRyYz_Fw.mjs";
|
|
12
12
|
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
|
|
13
|
-
import { dirname, join, posix, resolve } from "node:path";
|
|
13
|
+
import { basename, dirname, join, posix, resolve } from "node:path";
|
|
14
14
|
import { execFileSync } from "node:child_process";
|
|
15
15
|
import { isMap, isScalar, isSeq, parseDocument } from "yaml";
|
|
16
16
|
import ts from "typescript";
|
|
@@ -67,6 +67,8 @@ const SHARED_RULES = [
|
|
|
67
67
|
["String-keyed object tables are read through own keys only", "`antelopejs/no-inherited-key-lookup`"],
|
|
68
68
|
["A type guard checks each member it narrows to; keys with `Object.hasOwn`", "`antelopejs/no-presence-only-type-guard`"],
|
|
69
69
|
["A type guard checks the nested elements and values it claims", "review; no tool"],
|
|
70
|
+
["A startup read does not decide an insert another replica can race", "`antelopejs/no-read-then-insert`"],
|
|
71
|
+
["`Object.assign` writes no `unknown`, `any` or mistyped value over a field", "`antelopejs/no-unsafe-object-assign`"],
|
|
70
72
|
["Every file type-aware lint reads is listed by a tsconfig", "`antelopejs/require-tsconfig-include`"],
|
|
71
73
|
["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
|
|
72
74
|
["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
|
|
@@ -95,9 +97,9 @@ const FULL_RULES = [
|
|
|
95
97
|
["A CI gate reads `needs.<id>` only of jobs in its `needs`", "`antelopejs-sync --check`"],
|
|
96
98
|
["Entry-only rules exempt no tracked outsider", "`antelopejs-sync --check`"],
|
|
97
99
|
["A DMS layer's `build/backend-boundary.ts` is the pack's plugin", "`antelopejs-sync --check`"],
|
|
98
|
-
["No `skipLibCheck` in the root tsconfig or one `typecheck` or `build` uses", "
|
|
99
|
-
["`build` skips the lib check only over what `typecheck` checks", "
|
|
100
|
-
["`release` runs `typecheck`", "
|
|
100
|
+
["No `skipLibCheck` in the root tsconfig or one `typecheck` or `build` uses", "`antelopejs-sync --check`"],
|
|
101
|
+
["`build` skips the lib check only over what `typecheck` checks", "`antelopejs-sync --check`"],
|
|
102
|
+
["`release` runs `typecheck`", "`antelopejs-sync --check`"],
|
|
101
103
|
["A test names the wrong implementation it catches", "review; no tool"]
|
|
102
104
|
];
|
|
103
105
|
/** Pads each column the way oxfmt does, so formatting AGENTS.md never reports sync drift. */
|
|
@@ -424,6 +426,91 @@ function checkEntryOnlyConfiguration(root) {
|
|
|
424
426
|
};
|
|
425
427
|
}
|
|
426
428
|
//#endregion
|
|
429
|
+
//#region src/guardrails/markdown-table.ts
|
|
430
|
+
/** The lines of a Markdown table whose first row is the header, columns padded as oxfmt leaves them. */
|
|
431
|
+
function tableLines(table) {
|
|
432
|
+
const widths = table[0].map((_, column) => Math.max(3, ...table.map((row) => row[column].length)));
|
|
433
|
+
const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
|
|
434
|
+
return [
|
|
435
|
+
line(table[0]),
|
|
436
|
+
line(widths.map((width) => "-".repeat(width))),
|
|
437
|
+
...table.slice(1).map(line)
|
|
438
|
+
];
|
|
439
|
+
}
|
|
440
|
+
//#endregion
|
|
441
|
+
//#region src/guardrails/docs-modules.ts
|
|
442
|
+
const DMS_MODULES_START = "<!-- antelopejs-dms-modules:start -->";
|
|
443
|
+
const DMS_MODULES_END = "<!-- antelopejs-dms-modules:end -->";
|
|
444
|
+
const ORGANIZATION = "https://github.com/AntelopeJS";
|
|
445
|
+
/** The AntelopeJS DMS modules in display order. Every README holding the markers lists exactly these. */
|
|
446
|
+
const DMS_MODULES = [
|
|
447
|
+
{
|
|
448
|
+
repo: "dms-builder",
|
|
449
|
+
row: "Edit pages, tables and data sources by clicking, as TypeScript that compiles"
|
|
450
|
+
},
|
|
451
|
+
{
|
|
452
|
+
repo: "dms-ai",
|
|
453
|
+
row: "An assistant chat in the dashboard, on your own Claude Code or Codex"
|
|
454
|
+
},
|
|
455
|
+
{
|
|
456
|
+
repo: "dms-database",
|
|
457
|
+
row: "Schemas, relation diagrams, a data browser and a query console"
|
|
458
|
+
},
|
|
459
|
+
{
|
|
460
|
+
repo: "dms-api",
|
|
461
|
+
row: "API health, request logs, per-route statistics and a request tester"
|
|
462
|
+
},
|
|
463
|
+
{
|
|
464
|
+
repo: "dms-automation",
|
|
465
|
+
row: "Node-graph automations on schedules, webhooks and DMS events, with a trace for every run"
|
|
466
|
+
},
|
|
467
|
+
{
|
|
468
|
+
repo: "dms-mailing",
|
|
469
|
+
row: "E-mail templates in a block editor, versions, a send log and delivery metrics"
|
|
470
|
+
},
|
|
471
|
+
{
|
|
472
|
+
repo: "dms-lang",
|
|
473
|
+
row: "Translation coverage, a translation matrix and a translation queue"
|
|
474
|
+
},
|
|
475
|
+
{
|
|
476
|
+
repo: "dms-media",
|
|
477
|
+
row: "A media library with folders, per-folder permissions, image sizes and light editing"
|
|
478
|
+
},
|
|
479
|
+
{
|
|
480
|
+
repo: "dms-saas",
|
|
481
|
+
row: "Self-service sign-up, plans that gate features, and Stripe billing"
|
|
482
|
+
},
|
|
483
|
+
{
|
|
484
|
+
repo: "dms-marketing",
|
|
485
|
+
row: "Traffic, conversion funnels with A/B splits and click heatmaps, without cookies"
|
|
486
|
+
},
|
|
487
|
+
{
|
|
488
|
+
repo: "dms-frontend",
|
|
489
|
+
row: "The `ajs dms` CLI, the Vue renderer and the SDK every frontend module builds on"
|
|
490
|
+
}
|
|
491
|
+
];
|
|
492
|
+
/** The generated block, formatted as oxfmt leaves it. */
|
|
493
|
+
function modulesBlock() {
|
|
494
|
+
return [
|
|
495
|
+
DMS_MODULES_START,
|
|
496
|
+
"",
|
|
497
|
+
...tableLines([["Module", "What it adds"], ...DMS_MODULES.map(({ repo, row }) => [`[\`${repo}\`](${ORGANIZATION}/${repo})`, row])]),
|
|
498
|
+
"",
|
|
499
|
+
DMS_MODULES_END,
|
|
500
|
+
""
|
|
501
|
+
].join("\n");
|
|
502
|
+
}
|
|
503
|
+
/** The README with the block between its markers rewritten. A README without markers comes back as it is. */
|
|
504
|
+
function placeModulesBlock(current) {
|
|
505
|
+
const start = current.indexOf(DMS_MODULES_START);
|
|
506
|
+
const end = current.indexOf(DMS_MODULES_END);
|
|
507
|
+
const starts = current.split(DMS_MODULES_START).length - 1;
|
|
508
|
+
const ends = current.split(DMS_MODULES_END).length - 1;
|
|
509
|
+
if (starts === 0 && ends === 0) return current;
|
|
510
|
+
if (starts !== 1 || ends !== 1 || end < start) throw new Error("invalid antelopejs-dms-modules markers: a README holds exactly one start marker followed by one end marker. Repair or delete them, then rerun antelopejs-sync.");
|
|
511
|
+
return `${current.slice(0, start)}${modulesBlock()}${current.slice(end + 35).replace(/^\r?\n/, "")}`;
|
|
512
|
+
}
|
|
513
|
+
//#endregion
|
|
427
514
|
//#region src/guardrails/docs-compat.ts
|
|
428
515
|
const DOCS_COMPAT_START = "<!-- antelopejs-docs-compat:start -->";
|
|
429
516
|
const DOCS_COMPAT_END = "<!-- antelopejs-docs-compat:end -->";
|
|
@@ -442,27 +529,19 @@ const RESOLVED_SECTIONS = [
|
|
|
442
529
|
];
|
|
443
530
|
/** The generated block, rows sorted by package name, formatted as oxfmt leaves it. */
|
|
444
531
|
function compatBlock(rows) {
|
|
445
|
-
const
|
|
446
|
-
"Package",
|
|
447
|
-
"Supported",
|
|
448
|
-
"Tested with"
|
|
449
|
-
], ...[...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map(({ name, supported, tested }) => [
|
|
450
|
-
`\`${name}\``,
|
|
451
|
-
`\`${supported.replaceAll("|", "\\|")}\``,
|
|
452
|
-
tested === void 0 ? UNRESOLVED : `\`${tested}\``
|
|
453
|
-
])];
|
|
454
|
-
const widths = [
|
|
455
|
-
0,
|
|
456
|
-
1,
|
|
457
|
-
2
|
|
458
|
-
].map((column) => Math.max(3, ...table.map((row) => row[column].length)));
|
|
459
|
-
const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
|
|
532
|
+
const sorted = [...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
|
|
460
533
|
return [
|
|
461
534
|
DOCS_COMPAT_START,
|
|
462
535
|
"",
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
536
|
+
...tableLines([[
|
|
537
|
+
"Package",
|
|
538
|
+
"Supported",
|
|
539
|
+
"Tested with"
|
|
540
|
+
], ...sorted.map(({ name, supported, tested }) => [
|
|
541
|
+
`\`${name}\``,
|
|
542
|
+
`\`${supported.replaceAll("|", "\\|")}\``,
|
|
543
|
+
tested === void 0 ? UNRESOLVED : `\`${tested}\``
|
|
544
|
+
])]),
|
|
466
545
|
"",
|
|
467
546
|
DOCS_COMPAT_END,
|
|
468
547
|
""
|
|
@@ -632,12 +711,14 @@ function sharesLockfile(root) {
|
|
|
632
711
|
function lockPath(shared, directory) {
|
|
633
712
|
return shared ? LOCKFILE : relative$1(directory, LOCKFILE);
|
|
634
713
|
}
|
|
635
|
-
function readLock(root, shared, directory) {
|
|
714
|
+
function readLock(root, shared, directory, documents) {
|
|
636
715
|
const path = join(root, lockPath(shared, directory));
|
|
637
|
-
|
|
638
|
-
|
|
716
|
+
if (!documents.has(path) && existsSync(path)) documents.set(path, parseDocument(readFileSync(path, "utf8")));
|
|
717
|
+
const document = documents.get(path);
|
|
718
|
+
return document && {
|
|
719
|
+
document,
|
|
639
720
|
importer: shared ? directory || "." : "."
|
|
640
|
-
}
|
|
721
|
+
};
|
|
641
722
|
}
|
|
642
723
|
/** Adds one package's `docs-files` lines and, when it needs one, its README with the generated blocks. */
|
|
643
724
|
function planPackage(root, plan, lock, standard, { directory, ranges, published, node }) {
|
|
@@ -648,7 +729,7 @@ function planPackage(root, plan, lock, standard, { directory, ranges, published,
|
|
|
648
729
|
if (isDirectory(root, docs)) plan.docsFiles.push(docs);
|
|
649
730
|
const current = existsSync(join(root, readme)) ? readFileSync(join(root, readme), "utf8") : void 0;
|
|
650
731
|
const nodeRange = standard && current !== void 0 ? node : void 0;
|
|
651
|
-
if (ranges.size === 0 &&
|
|
732
|
+
if (ranges.size === 0 && current === void 0) return;
|
|
652
733
|
const rows = [...ranges].map(([name, supported]) => ({
|
|
653
734
|
name,
|
|
654
735
|
supported,
|
|
@@ -659,7 +740,7 @@ function planPackage(root, plan, lock, standard, { directory, ranges, published,
|
|
|
659
740
|
plan.readmes.push({
|
|
660
741
|
path: readme,
|
|
661
742
|
current,
|
|
662
|
-
content: rows.length > 0 ? placeCompatBlock(withRequirements, compatBlock(rows)) : withRequirements ?? ""
|
|
743
|
+
content: placeModulesBlock(rows.length > 0 ? placeCompatBlock(withRequirements, compatBlock(rows)) : withRequirements ?? "")
|
|
663
744
|
});
|
|
664
745
|
} catch (error) {
|
|
665
746
|
plan.errors.push(`${readme}: ${error instanceof Error ? error.message : String(error)}`);
|
|
@@ -690,7 +771,8 @@ function planDocs(root, manager) {
|
|
|
690
771
|
exists: (path) => existsSync(join(root, path))
|
|
691
772
|
};
|
|
692
773
|
const shared = sharesLockfile(root);
|
|
693
|
-
const
|
|
774
|
+
const documents = /* @__PURE__ */ new Map();
|
|
775
|
+
const locks = new Map(qualifying.map(({ directory }) => [directory, manager === "pnpm" ? readLock(root, shared, directory, documents) : void 0]));
|
|
694
776
|
const missing = manager === "pnpm" ? qualifying.filter(({ directory }) => !locks.get(directory)) : [];
|
|
695
777
|
if (missing.length) {
|
|
696
778
|
for (const path of new Set(missing.map(({ directory }) => lockPath(shared, directory)))) plan.errors.push(`${path} is missing, and the docs-compat block reads Tested with from it: run pnpm install, then rerun antelopejs-sync.`);
|
|
@@ -1164,17 +1246,20 @@ function scriptsOf(files) {
|
|
|
1164
1246
|
return;
|
|
1165
1247
|
}
|
|
1166
1248
|
}
|
|
1167
|
-
/** The package.json and tsconfig facts that keep `typecheck` the lib check no other script skips: `build` skips the lib check only over a program `typecheck` checks in full, no tsconfig a script uses or the root one sets `skipLibCheck: true`, and `release` runs `typecheck`. A file that cannot be read yields a
|
|
1168
|
-
function checkTypecheckCoverage(root) {
|
|
1249
|
+
/** The package.json and tsconfig facts that keep `typecheck` the lib check no other script skips: `build` skips the lib check only over a program `typecheck` checks in full, no tsconfig a script uses or the root one sets `skipLibCheck: true`, and `release` runs `typecheck`. Under `check` a broken fact is an error; otherwise it is a `Note:` advisory. A file that cannot be read yields a `Note:` advisory and never an error. */
|
|
1250
|
+
function checkTypecheckCoverage(root, check) {
|
|
1169
1251
|
const files = coverageFiles(root);
|
|
1170
1252
|
const scripts = scriptsOf(files);
|
|
1171
|
-
|
|
1172
|
-
return [
|
|
1253
|
+
const findings = scripts === void 0 ? [] : [
|
|
1173
1254
|
...skipCoverageErrors(scripts),
|
|
1174
1255
|
...skipLibCheckErrors(files, scripts),
|
|
1175
|
-
...releaseErrors(files, scripts)
|
|
1176
|
-
...unreadableNotes(files)
|
|
1256
|
+
...releaseErrors(files, scripts)
|
|
1177
1257
|
];
|
|
1258
|
+
const notes = check ? unreadableNotes(files) : [...findings, ...unreadableNotes(files)];
|
|
1259
|
+
return {
|
|
1260
|
+
errors: check ? findings : [],
|
|
1261
|
+
advisories: notes.map((note) => `Note: ${note}`)
|
|
1262
|
+
};
|
|
1178
1263
|
}
|
|
1179
1264
|
/** The kind-specific text of each shared skill. */
|
|
1180
1265
|
const KIND_TEXT = {
|
|
@@ -1202,27 +1287,33 @@ const KIND_TEXT = {
|
|
|
1202
1287
|
title: "Verify module",
|
|
1203
1288
|
user: "The user of a module is an app developer: they add it to `antelope.config.ts`, configure it, and other modules call the interfaces it implements.",
|
|
1204
1289
|
launch: "`new` runs the setup (`pnpm run build` by default), then starts every `services` entry of `verify.config.ts` in its own Docker container on a free loopback port, named `<prefix>-<repo>-<service>-<run>` (`VERIFY_CONTAINER_PREFIX`, default `verify`), and waits for each readiness command. A provider with sandbox keys in `saas.env` records the missing ones.",
|
|
1205
|
-
builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
|
|
1290
|
+
builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus the `companions(services)` modules and a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
|
|
1206
1291
|
layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
|
|
1207
1292
|
- \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
|
|
1293
|
+
- \`companions(services)\`: other modules the fixture project loads, keyed by name, each a \`source\` and an optional \`config\` as in \`antelope.config.ts\`. Add the provider of every interface the module imports that it does not implement, such as \`@antelopejs/api\` for \`@antelopejs/interface-api\`, or the module never finishes starting.
|
|
1208
1294
|
- \`saas: { env, sandbox }\`: a SaaS module runs against the provider's sandbox with keys from these environment variables. Without every key, each journey is NOT VERIFIED and so is the verdict, never PASS or PASS+NOTES.
|
|
1209
1295
|
- \`journeys\`: the module's own journeys. Each writes through the module with \`context.call(...)\` and reads the result back with \`context.native(...)\` (\`redis-cli\`, \`mongosh\`, \`psql\`, the Mailpit API) inside the service container.`,
|
|
1210
1296
|
smoke: "`module-dev` and one write read back through the native client",
|
|
1211
1297
|
gotchas: ["Every container is the run's own. Never point a journey at a shared instance such as a developer's local database.", "A sandbox key missing from the environment is a NOT VERIFIED verdict."]
|
|
1212
1298
|
},
|
|
1213
1299
|
template: {
|
|
1214
|
-
description: "Drive this AntelopeJS template the way a new user does: scaffold a project with `ajs project init` from an offline interfaces manifest, install it, run its own `pnpm run checks`, run `ajs project dev --watch` and hit its welcome page, endpoint or ready line. Use to prove a change to the template works before merge, to verify a PR, or to run the release canary.",
|
|
1300
|
+
description: "Drive this AntelopeJS template the way a new user does: scaffold a project with `ajs project init`, or a module with `ajs module init`, from an offline interfaces manifest, install it, run its own `pnpm run checks`, run `ajs project dev --watch` and hit its welcome page, endpoint or ready line. Use to prove a change to the template works before merge, to verify a PR, or to run the release canary.",
|
|
1215
1301
|
title: "Verify template",
|
|
1216
|
-
user: "The user of a template is someone running `ajs project init --template
|
|
1217
|
-
launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. Journeys point `ajs config set git` at it, so no step reaches GitHub. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
|
|
1302
|
+
user: "The user of a template is someone running `ajs project init --template`, or `ajs module init --template` for a module template: they get a copy of the repository without `.agents/` and `.claude/skills/` and expect it to install, pass its checks and run.",
|
|
1303
|
+
launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. `context.scaffold` creates from it with `ajs project init`, or with `ajs module init` when `template.module` is set. Journeys point `ajs config set git` at it, so no step reaches GitHub. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
|
|
1218
1304
|
builtins: `- \`scaffold-dev\`: \`ajs project init <app> --template <name> --pm pnpm --git-init\`, \`pnpm install --frozen-lockfile\`, then \`ajs project dev --watch\` with \`PORT\` set until \`template.probe\` answers: a path and status on that port, or a \`log\` line followed by \`settleMs\` of still running. Ctrl+C must exit 130.
|
|
1219
|
-
- \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks
|
|
1305
|
+
- \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.
|
|
1306
|
+
- For a module template (\`template.module\`), both run \`ajs module init <app> --template <name> --pm pnpm --git-init\` in place of \`ajs project init\`, and \`scaffold-dev\` runs \`pnpm run build\` before \`ajs project dev --watch --project playground\`.
|
|
1307
|
+
|
|
1308
|
+
Both take their project from \`context.prepared("scaffolded", ...)\`, so the run scaffolds and installs it once. A repository journey that prepares \`scaffolded\` shares that build, so its build must be the same \`context.scaffold\` then \`pnpm install --frozen-lockfile --prefer-offline\`.`,
|
|
1220
1309
|
layer: `- \`template.name\`: the listing name users pass to \`--template\`.
|
|
1221
1310
|
- \`template.project\`: list it under \`projectTemplates\`.
|
|
1311
|
+
- \`template.module\`: a module template, listed under \`templates\` and created with \`ajs module init\`; it excludes \`template.project\`.
|
|
1222
1312
|
- \`services\`: image, port, readiness command and \`reset\`, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\` and passes their endpoints to the project it starts through the \`env\` of \`context.dev\`.
|
|
1313
|
+
- \`context.dev(name, project, { command })\`: a template that is not an \`ajs\` project starts with its own command, such as \`["node", "ace", "serve"]\`, in place of \`ajs project dev\`. The harness records its PID, so \`context.stop\` and \`clean\` stop it, and \`template.probe\` decides when it is ready. Leave \`scaffold-dev\` and \`scaffold-checks\` out of its features: both run \`ajs\`.
|
|
1223
1314
|
- \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
|
|
1224
|
-
smoke: "`scaffold-dev` and `scaffold-checks`",
|
|
1225
|
-
gotchas: ["`ajs project init`
|
|
1315
|
+
smoke: "`scaffold-dev` and `scaffold-checks`, or, for a template that is not an `ajs` project, its own journeys that start it with `context.dev(name, project, { command })`",
|
|
1316
|
+
gotchas: ["`ajs project init` and `ajs module init` leave out `.agents/` and `.claude/skills/`, so the scaffolded project or module carries neither this skill nor anything else under `.agents/`. Never expect either folder there.", "Every file a user gets is user-facing here, tests included; only `.github/` and `.claude/` outside `.claude/skills/` are not."]
|
|
1226
1317
|
}
|
|
1227
1318
|
};
|
|
1228
1319
|
//#endregion
|
|
@@ -1294,14 +1385,15 @@ Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`comman
|
|
|
1294
1385
|
${BIN} clean <run>
|
|
1295
1386
|
\`\`\`
|
|
1296
1387
|
|
|
1297
|
-
Each journey deletes its scratch folder and \`HOME\`, its install included, when it ends: passed, failed or interrupted. Only its evidence stays. \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`, the folders \`context.prepared\` kept included. Run it after every run, failed ones included.
|
|
1388
|
+
Each journey deletes its scratch folder and \`HOME\`, its install included, when it ends: passed, failed or interrupted. Only its evidence stays. \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`, the folders \`context.prepared\` kept included. Run it after every run, failed ones included. It cleans only a run this checkout created, the folder \`new\` printed: it refuses the shared runs folder, a repository's folder of runs and another checkout's run, which belong to other sessions. Never delete under the runs folder yourself, with \`rm\` or a glob over run names.
|
|
1298
1389
|
|
|
1299
1390
|
## The repository's own layer
|
|
1300
1391
|
|
|
1301
1392
|
- \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
|
|
1302
1393
|
- \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, why }\`.
|
|
1303
|
-
- \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports. A check states what the product must do; an environment that went away is never a failing check. When a journey fails, the harness reruns each service's readiness command, up to four times over about 3.5 s, and looks at every \`ajs project dev\` the journey started, its own readiness probe included. The journey ends NOT VERIFIED, not FAIL, when a service still fails every rerun, an app was killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the app the harness started failed to bind the port the harness gave it (\`EADDRINUSE\` naming that port). An app that exits on its own with an exit code, one that crashes by another signal such as SIGABRT or SIGSEGV, and one that logs \`EADDRINUSE\` for any other port are the product's failure. A change that takes its own service down still reads as an outage: the service stays down, so the journey is NOT VERIFIED. For anything else the journey depends on, such as a process it started with \`context.command\` or an outside endpoint, probe it when a check fails and call \`context.notVerified(reason)\` when it no longer answers.
|
|
1304
|
-
|
|
1394
|
+
- \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports. A check states what the product must do; an environment that went away is never a failing check. When a journey fails, the harness reruns each service's readiness command, up to four times over about 3.5 s, and looks at every \`ajs project dev\` the journey started, its own readiness probe included. The journey ends NOT VERIFIED, not FAIL, when a service still fails every rerun, an app was killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the app the harness started failed to bind the port the harness gave it (\`EADDRINUSE\` naming that port), or the first failing step is an install, image pull or image build whose failed requests went only to fixed public registry names that also fail a fresh DNS and TCP probe at verdict time. A registry that answers that probe makes the failure the product's, whatever the output says. An app that exits on its own with an exit code, one that crashes by another signal such as SIGABRT or SIGSEGV, and one that logs \`EADDRINUSE\` for any other port are the product's failure. A change that takes its own service down still reads as an outage: the service stays down, so the journey is NOT VERIFIED. For anything else the journey depends on, such as a process it started with \`context.command\` or an outside endpoint, probe it when a check fails and call \`context.notVerified(reason)\` when it no longer answers.
|
|
1395
|
+
|
|
1396
|
+
- \`context.prepared(key, build)\` does the preparation many journeys repeat once per run, such as scaffolding and installing a project, and returns the journey's own copy at \`<work>/<key>\`. The first journey that asks for \`key\` runs \`build(folder)\` on the empty folder with its usual steps, after a step \`prepared <key>\` that marks them as the build and says whether it was kept. A build is kept until \`clean\` only when it returns, records at least one check, passes every check, and leaves only files, directories and symlinks in the folder. Every later journey of the run, also in a later \`journey\` command, gets a fresh copy and one step, \`prepared <key>\`, that names the journey that built it and holds that build's evidence under \`build/\`. A build that is not kept is built again by the next journey, and rerunning the journey that built builds again. An absolute symlink into the folder points into each copy; other symlinks keep their target. A file with a hard link outside the folder, such as a package file pnpm links from its store, is linked into each copy rather than copied: \`context.edit\` gives it a new inode, and a journey that writes it another way replaces it instead of writing it in place. \`build\` writes only inside the folder it is given: a write elsewhere, such as a sibling under \`<work>\` or the repository, stays with the journey that built. Two concurrent \`journey\` commands that reach the same key at once both build, and the first to finish is kept. A project \`build\` creates with \`scaffold\` starts each copy as \`scaffold\` starts one: a copy with no installed module gets a module cache an earlier passing journey kept, and a passing journey keeps the registry modules installed into its copy. The commands \`build\` runs get a \`HOME\` of their own that is deleted when it ends: redo after \`prepared\` anything a later step needs in \`HOME\`, such as \`ajs config set git\`. Pass the same \`build\` for a key in every journey.
|
|
1305
1397
|
- \`env\`, \`setup\` (commands replacing the build), \`userFacing\` and \`shared\` (globs replacing the kind's default; \`shared\` lists the files whose change runs every feature), and \`formal\` (formal checks: \`name\`, \`covers\`, \`command\`, \`violation\` with an optional \`states\` group for the counterexample length, and optionally \`behaviour\` and \`baseCommand\`).
|
|
1306
1398
|
${text.layer}
|
|
1307
1399
|
- \`features/README.md\`: the index of the features; \`map\` does not read it as a feature.
|
|
@@ -1329,7 +1421,7 @@ ${BIN} map
|
|
|
1329
1421
|
6. **One-way doors.** The section comes right after the result line and is mandatory. \`${BIN} doors\` prints the \`One-way-door:\` line of the diff. Every file the path rules flag needs a door row or a false positive with its reason.
|
|
1330
1422
|
7. **Result.** FAIL if any rule fails. NOT VERIFIED when any journey of a required feature is NOT VERIFIED, for example a SaaS module run without its sandbox keys, however many other journeys passed. PASS+NOTES when everything required ran and passed but the judgement lists something no journey reached or something the owner should look at. PASS otherwise.
|
|
1331
1423
|
|
|
1332
|
-
Write your judgement to
|
|
1424
|
+
Write your judgement to a JSON file:
|
|
1333
1425
|
|
|
1334
1426
|
\`\`\`json
|
|
1335
1427
|
{
|
|
@@ -1345,13 +1437,13 @@ Write your judgement to \`<run>/evidence/judgement.json\`:
|
|
|
1345
1437
|
}
|
|
1346
1438
|
\`\`\`
|
|
1347
1439
|
|
|
1348
|
-
A door row is \`{ "kind", "location", "irreversible", "containment" }\`, where \`containment\` says what limits the damage.
|
|
1440
|
+
A door row is \`{ "kind", "location", "irreversible", "containment" }\`, where \`containment\` says what limits the damage. Pass it to \`verdict\` in the same step:
|
|
1349
1441
|
|
|
1350
1442
|
\`\`\`bash
|
|
1351
|
-
${BIN} verdict <run> --pr <n>
|
|
1443
|
+
${BIN} verdict <run> --pr <n> --judgement <file>
|
|
1352
1444
|
\`\`\`
|
|
1353
1445
|
|
|
1354
|
-
\`verdict\` writes \`evidence/verdict.md\` and exits 1
|
|
1446
|
+
\`verdict\` stores it as \`evidence/judgement.json\`, writes \`evidence/verdict.md\` and exits 1 when an input is missing or the result is not PASS or PASS+NOTES. Read \`verdict.md\` only after it exits. Report the verdict and what you saw in your own reply, from a thread that did not write the change.
|
|
1355
1447
|
|
|
1356
1448
|
## Trust
|
|
1357
1449
|
|
|
@@ -1472,24 +1564,47 @@ function planSharedKind(root, kind) {
|
|
|
1472
1564
|
path,
|
|
1473
1565
|
content
|
|
1474
1566
|
});
|
|
1475
|
-
const link = claudeLink(kind);
|
|
1476
|
-
|
|
1567
|
+
const link = planLink(root, claudeLink(kind), claudeLinkTarget(kind));
|
|
1568
|
+
return {
|
|
1569
|
+
actions: [...actions, ...link.actions],
|
|
1570
|
+
errors: [...errors, ...link.errors]
|
|
1571
|
+
};
|
|
1572
|
+
}
|
|
1573
|
+
function planLink(root, link, target) {
|
|
1477
1574
|
const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
|
|
1478
|
-
if (stat === void 0)
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1575
|
+
if (stat === void 0) return {
|
|
1576
|
+
actions: [{
|
|
1577
|
+
kind: "link",
|
|
1578
|
+
path: link,
|
|
1579
|
+
target
|
|
1580
|
+
}],
|
|
1581
|
+
errors: []
|
|
1582
|
+
};
|
|
1583
|
+
if (!stat.isSymbolicLink()) return {
|
|
1584
|
+
actions: [],
|
|
1585
|
+
errors: [`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`]
|
|
1586
|
+
};
|
|
1587
|
+
if (readlinkSync(join(root, link)) !== target) return {
|
|
1588
|
+
actions: [{
|
|
1589
|
+
kind: "link",
|
|
1590
|
+
path: link,
|
|
1591
|
+
target
|
|
1592
|
+
}],
|
|
1593
|
+
errors: []
|
|
1594
|
+
};
|
|
1489
1595
|
return {
|
|
1490
|
-
actions,
|
|
1491
|
-
errors
|
|
1596
|
+
actions: [],
|
|
1597
|
+
errors: []
|
|
1598
|
+
};
|
|
1599
|
+
}
|
|
1600
|
+
/** The `.claude/skills` link of an own skill under `.agents/skills`; one elsewhere is already where Claude Code reads it, or is not an agent skill. */
|
|
1601
|
+
function planOwnLink(root, skill) {
|
|
1602
|
+
const folder = skill === void 0 ? void 0 : dirname(skill);
|
|
1603
|
+
if (folder === void 0 || dirname(folder) !== ".agents/skills") return {
|
|
1604
|
+
actions: [],
|
|
1605
|
+
errors: []
|
|
1492
1606
|
};
|
|
1607
|
+
return planLink(root, `.claude/skills/${basename(folder)}`, `../../${folder}`);
|
|
1493
1608
|
}
|
|
1494
1609
|
function planStaleKinds(root, keep) {
|
|
1495
1610
|
const actions = [];
|
|
@@ -1525,7 +1640,8 @@ function planStaleKinds(root, keep) {
|
|
|
1525
1640
|
function planVerify(root, options) {
|
|
1526
1641
|
const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
|
|
1527
1642
|
const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
|
|
1528
|
-
const
|
|
1643
|
+
const own = shared ? void 0 : ownVerificationSkill(root);
|
|
1644
|
+
const wanted = shared ? planSharedKind(root, shared) : kind === "custom" ? planOwnLink(root, own) : {
|
|
1529
1645
|
actions: [],
|
|
1530
1646
|
errors: []
|
|
1531
1647
|
};
|
|
@@ -1535,7 +1651,7 @@ function planVerify(root, options) {
|
|
|
1535
1651
|
} : planStaleKinds(root, shared);
|
|
1536
1652
|
return {
|
|
1537
1653
|
kind,
|
|
1538
|
-
verificationSkill: shared ? skillPath(shared) :
|
|
1654
|
+
verificationSkill: shared ? skillPath(shared) : own,
|
|
1539
1655
|
actions: [...wanted.actions, ...stale.actions],
|
|
1540
1656
|
errors: [...errors, ...wanted.errors],
|
|
1541
1657
|
notes: stale.notes
|
|
@@ -1608,7 +1724,7 @@ const MANAGED_ARTIFACTS = [
|
|
|
1608
1724
|
path: "package.json",
|
|
1609
1725
|
profiles: ["full", "template"],
|
|
1610
1726
|
desired: (current, context) => ({
|
|
1611
|
-
content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context),
|
|
1727
|
+
content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context.versions, context),
|
|
1612
1728
|
notes: []
|
|
1613
1729
|
})
|
|
1614
1730
|
},
|
|
@@ -1652,7 +1768,7 @@ const MANAGED_ARTIFACTS = [
|
|
|
1652
1768
|
},
|
|
1653
1769
|
{
|
|
1654
1770
|
path: SUPPRESSIONS_FILE,
|
|
1655
|
-
profiles: ["full"],
|
|
1771
|
+
profiles: ["full", "template"],
|
|
1656
1772
|
desired: (_current, context) => ({
|
|
1657
1773
|
content: context.suppressionBudget,
|
|
1658
1774
|
notes: []
|
|
@@ -1757,12 +1873,13 @@ function repositoryContext(root, current, profile, verificationSkill) {
|
|
|
1757
1873
|
nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
|
|
1758
1874
|
claude: profile === "full" ? claudeProse(root, current) : "",
|
|
1759
1875
|
baseline: "",
|
|
1760
|
-
suppressionBudget:
|
|
1876
|
+
suppressionBudget: adoptedBudget(root, current.get(SUPPRESSIONS_FILE)),
|
|
1761
1877
|
managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
|
|
1762
1878
|
verificationSkill: profile === "template" && inScaffoldExcludedPath(verificationSkill) ? void 0 : verificationSkill,
|
|
1763
1879
|
glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file))),
|
|
1764
1880
|
docs: profile === "full" && current.has("package.json") ? planDocs(root, manager) : void 0,
|
|
1765
|
-
placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test)
|
|
1881
|
+
placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test),
|
|
1882
|
+
captures: existsSync(join(root, "docs/captures.ts"))
|
|
1766
1883
|
};
|
|
1767
1884
|
}
|
|
1768
1885
|
function writeArtifacts(root, artifacts) {
|
|
@@ -1802,7 +1919,9 @@ function syncRepository(root, options = {}) {
|
|
|
1802
1919
|
let plan = [...planSync(current, modes, context), ...standalone];
|
|
1803
1920
|
const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
|
|
1804
1921
|
const entryOnly = checkEntryOnlyConfiguration(root);
|
|
1922
|
+
const coverage = checkTypecheckCoverage(root, Boolean(options.check));
|
|
1805
1923
|
errors.push(...entryOnly.errors, ...verify.errors, ...writing.errors);
|
|
1924
|
+
errors.push(...coverage.errors);
|
|
1806
1925
|
const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
|
|
1807
1926
|
(options.check ? errors : notes).push(...repositoryNotices(root, context));
|
|
1808
1927
|
if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
|
|
@@ -1821,9 +1940,9 @@ function syncRepository(root, options = {}) {
|
|
|
1821
1940
|
writeArtifacts(root, writes);
|
|
1822
1941
|
applyVerifyActions(root, actions);
|
|
1823
1942
|
}
|
|
1824
|
-
const
|
|
1825
|
-
if (context.typeAware)
|
|
1826
|
-
const dependenciesAdded = profile === "full"
|
|
1943
|
+
const templateDependencies = ["knip"];
|
|
1944
|
+
if (context.typeAware) templateDependencies.push("oxlint-tsgolint");
|
|
1945
|
+
const dependenciesAdded = profile === "full" ? addedDevDependencies(manifest, context.versions, context).length > 0 : templateDependencies.some((name) => !manifest.devDependencies?.[name]);
|
|
1827
1946
|
return {
|
|
1828
1947
|
artifacts: plan,
|
|
1829
1948
|
paths: errors.length ? [] : [...writes, ...actions].map(({ path }) => path),
|
|
@@ -1831,7 +1950,7 @@ function syncRepository(root, options = {}) {
|
|
|
1831
1950
|
errors,
|
|
1832
1951
|
notes,
|
|
1833
1952
|
verifyNotes: options.check || errors.length ? [] : verify.notes,
|
|
1834
|
-
advisories: [...entryOnly.advisories, ...
|
|
1953
|
+
advisories: [...entryOnly.advisories, ...coverage.advisories],
|
|
1835
1954
|
dependenciesAdded
|
|
1836
1955
|
};
|
|
1837
1956
|
}
|