@antelopejs/tooling-configs 0.7.3 → 0.7.5-next.356.g0d472b3
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 +63 -80
- package/dist/bin/api-diff.mjs +29 -49
- package/dist/bin/capture.mjs +4 -4
- package/dist/bin/check-size.mjs +12 -3
- package/dist/bin/checks.mjs +2 -2
- package/dist/bin/comment-proof.mjs +3 -4
- package/dist/bin/garden.mjs +45 -170
- package/dist/bin/readme-strip.mjs +2 -2
- package/dist/bin/suppressions.mjs +212 -9
- package/dist/bin/sync.mjs +318 -210
- package/dist/bin/tsc.mjs +24 -0
- package/dist/bin/verify.mjs +91 -671
- package/dist/{checks-CSlWvky1.mjs → checks-C60vMFin.mjs} +155 -310
- package/dist/{docs-compat-BAZiPLZt.mjs → docs-compat-CdgBviGf.mjs} +2 -2
- package/dist/eslint.mjs +1 -1
- package/dist/{files-C-JJhExM.mjs → files-BbzJEk-L.mjs} +5 -4
- package/dist/formal/index.mjs +1 -1
- package/dist/{guardrails-nj7NTglr.mjs → guardrails-Dron1AbR.mjs} +67 -673
- package/dist/{installed-typescript-6MtIWlE4.mjs → installed-typescript-CF_FR9DV.mjs} +17 -17
- package/dist/{map-BYkmnvNw.mjs → map-CbNbypUa.mjs} +2 -2
- package/dist/oxc/anti-slop/index.mjs +22 -964
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +1 -1
- package/dist/oxc/lint.d.mts +2 -14
- package/dist/oxc/lint.mjs +3 -20
- package/dist/{package-DDG3YH7W.mjs → package-7oylgBeT.mjs} +6 -19
- package/dist/{workflow-C-oBwL2H.mjs → renovate-D0su_v9p.mjs} +191 -91
- package/dist/{suppression-budget-CPDSFg4X.mjs → suppression-budget-De9nUzlD.mjs} +33 -13
- package/dist/{suppressions-CxPnh4sC.mjs → suppressions-CfJwL0fN.mjs} +6 -2
- package/dist/{templates-HG0fel2S.mjs → templates-DLW0Ubfk.mjs} +26 -29
- package/dist/typescript-C7eU-cig.mjs +581 -0
- package/dist/typescript-version-CptQKjGz.mjs +18 -0
- package/dist/typescript6-BWqCcXGY.mjs +2 -0
- package/dist/typescript6-HdyOMBv3.mjs +8 -0
- package/dist/verify/index.d.mts +5 -24
- package/package.json +27 -7
- package/dist/bin/body-check.mjs +0 -350
- package/dist/bin/ratchet.d.mts +0 -1
- package/dist/bin/ratchet.mjs +0 -375
- package/dist/ceilings-B7KayYIG.mjs +0 -76
- package/dist/oxlint-CIeonWMB.mjs +0 -133
- package/dist/proof-stamp-BFV7JTZT.mjs +0 -342
- package/dist/ratchet-DLCfeaPY.mjs +0 -453
- package/dist/renames-L2owF5GD.mjs +0 -59
- package/dist/size-CCGLY4Ke.mjs +0 -18
- package/dist/suppression-base-CYaLZAq7.mjs +0 -120
- package/dist/typescript-QfxkJYzd.mjs +0 -292
- /package/dist/bin/{body-check.d.mts → tsc.d.mts} +0 -0
package/dist/bin/sync.mjs
CHANGED
|
@@ -1,25 +1,23 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { a as
|
|
3
|
-
import { a as managedPackage, c as repositoryTools, f as toolingVersions, l as serializeManifest, m as usesNuxt, n as bootstrapDependencies, o as packageManager, p as usesCaptures, r as bootstrappedManifest, s as parseManifest, t as addedDevDependencies, u as templatePackage } from "../package-DDG3YH7W.mjs";
|
|
2
|
+
import { a as managedPackage, c as repositoryTools, f as toolingVersions, l as serializeManifest, m as usesNuxt, n as bootstrapDependencies, o as packageManager, p as usesCaptures, r as bootstrappedManifest, s as parseManifest, t as addedDevDependencies, u as templatePackage } from "../package-7oylgBeT.mjs";
|
|
4
3
|
import { t as admits } from "../semver-BDxeEcP_.mjs";
|
|
5
|
-
import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-
|
|
4
|
+
import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-DLW0Ubfk.mjs";
|
|
6
5
|
import { a as VERIFY_KINDS, c as isVerifyKind, d as linkPointsAt, i as SYNCED_SKILL_FILES, l as skillFolder, o as claudeLink, s as claudeLinkTarget, u as planDocsSkills } from "../shared-BCFFyp3l.mjs";
|
|
6
|
+
import { t as typescript6_default } from "../typescript6-HdyOMBv3.mjs";
|
|
7
7
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
8
|
-
import { _ as
|
|
9
|
-
import {
|
|
10
|
-
import { n as workspaceDirectories, r as workspacePatterns, t as planDocs } from "../docs-compat-
|
|
8
|
+
import { _ as ciRenovateSyncCallers, a as GITATTRIBUTES_ARTIFACT, b as sharedWorkflow, c as CI_CONTEXT, f as callerPlan, g as ciNodeCallers, h as MISSING_CHECKS_WORKFLOW, m as ciWorkflow, p as ciProfile, r as renovateArtifacts, u as CI_PATH, v as hasChecksWorkflow, y as sharedRefArtifacts } from "../renovate-D0su_v9p.mjs";
|
|
9
|
+
import { i as gitFiles, s as repositoryRoot } from "../files-BbzJEk-L.mjs";
|
|
10
|
+
import { n as workspaceDirectories, r as workspacePatterns, t as planDocs } from "../docs-compat-CdgBviGf.mjs";
|
|
11
11
|
import { n as shimInvocation } from "../run-command-BlFRPORx.mjs";
|
|
12
|
-
import { a as
|
|
13
|
-
import {
|
|
14
|
-
import {
|
|
15
|
-
import {
|
|
16
|
-
import { t as DEFAULT_SHARED } from "../map-BYkmnvNw.mjs";
|
|
12
|
+
import { a as matchingScripts, c as inWorkspace, d as runPnpm, i as verifyLayers, l as installsWithPnpm, n as droppedChecksSteps, o as stepsOf, s as pnpmLockfiles, u as moveDependencyRanges } from "../checks-C60vMFin.mjs";
|
|
13
|
+
import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-De9nUzlD.mjs";
|
|
14
|
+
import { u as typescript } from "../suppressions-CfJwL0fN.mjs";
|
|
15
|
+
import { t as DEFAULT_SHARED } from "../map-CbNbypUa.mjs";
|
|
17
16
|
import { createRequire } from "node:module";
|
|
17
|
+
import { isAlias, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
|
|
18
18
|
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
|
|
19
19
|
import { basename, dirname, join, posix, resolve } from "node:path";
|
|
20
20
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
21
|
-
import { isAlias, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
|
|
22
|
-
import ts from "@typescript/typescript6";
|
|
23
21
|
import { parseArgs } from "node:util";
|
|
24
22
|
//#region src/guardrails/docs-typescript.ts
|
|
25
23
|
const MARKDOWN = /\.(?:md|mdc)$/i;
|
|
@@ -92,158 +90,41 @@ function untypedDocsFiles(root) {
|
|
|
92
90
|
//#region src/guardrails/agents-block.ts
|
|
93
91
|
const AGENTS_BLOCK_START = "<!-- antelopejs-guardrails:start -->";
|
|
94
92
|
const AGENTS_BLOCK_END = "<!-- antelopejs-guardrails:end -->";
|
|
95
|
-
const ITERATION =
|
|
96
|
-
|
|
97
|
-
\`pnpm run checks\` runs every step, so run it once, at the end. While you iterate, run only the check that covers what you changed:
|
|
93
|
+
const ITERATION = `CI runs \`pnpm run checks\` in full on every pull request and reports what failed. The commit hook formats and lints the staged files. Locally, run only the fast check for what you touched:
|
|
98
94
|
|
|
99
95
|
- \`pnpm run typecheck\` after you change types or signatures.
|
|
100
96
|
- \`pnpm exec oxlint <files>\` and \`pnpm exec oxfmt <files>\` on the files you changed.
|
|
101
|
-
-
|
|
97
|
+
- One test file, not the suite. In a module that tests with \`ajs module test\`: \`pnpm run build\`, then \`pnpm exec ajs module test . -f dist/<path>.test.js\`.`;
|
|
102
98
|
const COMMENTS = `### Comments
|
|
103
99
|
|
|
104
|
-
Say it in code
|
|
105
|
-
|
|
106
|
-
Before suppressing a type rule, try inference or a type derived from its owner with \`Parameters\`, \`ReturnType\`, or indexed access. A private alias can still appear in a published declaration. Keep a suppression only after checking the published contract and the unchecked boundary it protects.
|
|
107
|
-
|
|
108
|
-
Check each directive reason against the current line and its callers. Returning a value is not the same as awaiting and discarding it. A reason must describe what the code does now.`;
|
|
100
|
+
Say it in code: a constraint in a type, a lint rule or a test, a public item's contract in TSDoc. Other comments are lint directives naming their rules, \`@ts-expect-error <reason>\`, \`SAFETY: <reason>\` above a type assertion, and license or tool directives. A reason states what the code does now.`;
|
|
109
101
|
const TESTS = `### Tests
|
|
110
102
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
- Name the wrong implementation this test fails on. A test with no answer is deleted, not kept.
|
|
114
|
-
- No test reads the file it tests. Drive the behaviour through the public interface.
|
|
115
|
-
- An invariant over many files is a lint rule, not a test.`;
|
|
116
|
-
const CLEANUP_PROOF = `### Cleanup proof
|
|
103
|
+
Each test names the wrong implementation it fails on, or is deleted. Drive behaviour through the public interface. An invariant over many files is a lint rule.`;
|
|
104
|
+
const REVIEW = `### Review
|
|
117
105
|
|
|
118
|
-
|
|
106
|
+
No tool checks these:
|
|
119
107
|
|
|
120
|
-
|
|
108
|
+
- A type guard checks the nested elements and values it claims.
|
|
109
|
+
- A no-upward import rule rejects same-tier peers; probe it with an import.
|
|
110
|
+
- A finding only an evasion or a patched internal can trigger goes under Attention and never blocks.`;
|
|
111
|
+
const SUPPRESSIONS = `### Suppressions
|
|
121
112
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
An entry-only rule exempts only its own module. Add a second module entry rather than exempting another importer. A no-upward rule must reject peers in the same tier as well as higher tiers. Probe the rank decision with an import, not just a reading of the configuration.
|
|
125
|
-
|
|
126
|
-
Moving a method body into a function keeps how it is called: the same receiver, argument count, read order and laziness.
|
|
127
|
-
|
|
128
|
-
Verify a boundary against the imports a developer or agent would plausibly write: static and dynamic imports, re-exports, Vue \`src\`, CSS \`@import\`, and worker or child-process entries in normally named files. A construction only an evasion would write, an edit to resolution configuration (\`package.json\` \`browser\`, \`exports\`, \`main\` or \`imports\`, bundler aliases, tsconfig \`paths\`), and a difference observable only by patching private fields or internal methods go under Attention and never block. Public API and ordinary subclass behaviour stay part of the contract.`;
|
|
129
|
-
const SUPPRESSION_BUDGET = `### Suppression budget
|
|
130
|
-
|
|
131
|
-
\`guardrails.suppressions.json\` caps the suppressions in authored code, the repository's own files under \`.agents/\`, \`.claude/\` and the other agent directories included (\`agentFiles\`; only what \`antelopejs-sync\` writes there is skipped): lint directives per rule they name (\`*\` for none), \`@ts-expect-error\`, \`@ts-ignore\` and \`SAFETY:\` comments, and under \`config\` each rule a lint config (\`oxlint.config.*\`, \`.oxlintrc.json\`, \`eslint.config.*\`) switches off or to a warning, keyed by rule and \`files\` glob anchored at the config's directory, so widening or moving a scope is a new ceiling of 0, while narrowing one takes over the room it gives up. Switching a rule off in a config is a suppression too: fix the code its rule reports instead. A suppression over its ceiling fails: fix the code, or remove another suppression of the same kind. A rule that keeps needing suppressions should be changed in the preset. Never raise or remove a number in that file: the check fails a ceiling higher than on the pull request base, and only the operator approves a raise. A directive disabling \`anti-slop/require-safety-comment-for-type-assertion\` is burn-down debt: remove the assertion, or, where it holds, replace the directive with \`SAFETY: <why it holds>\`, which takes over its room without a raise. After you remove suppressions, run \`pnpm run suppressions:update\` and commit the lowered file.`;
|
|
132
|
-
const SHARED_RULES = [
|
|
133
|
-
["Formatting", "oxfmt"],
|
|
134
|
-
["Lint findings are errors; no rule warns", "oxlint preset"],
|
|
135
|
-
["Comments are TSDoc, directives, or `SAFETY:` only", "`antelopejs/no-comments`"],
|
|
136
|
-
["Every test asserts", "`antelopejs/require-assertion`"],
|
|
137
|
-
["Tests read no files outside fixtures, helpers, locales", "`antelopejs/no-fs-read-in-tests`"],
|
|
138
|
-
["Tests import the code under test from local source, not their own package name", "`antelopejs/no-self-import-in-tests`"],
|
|
139
|
-
["No assertion that restates a constant", "`antelopejs/no-constant-value-assertion`"],
|
|
140
|
-
["No test whose only check is \"is a function\"", "`antelopejs/no-typeof-function-only-test`"],
|
|
141
|
-
["String-keyed object tables are read through own keys only", "`antelopejs/no-inherited-key-lookup`"],
|
|
142
|
-
["A type guard checks each member it narrows to; keys with `Object.hasOwn`", "`antelopejs/no-presence-only-type-guard`"],
|
|
143
|
-
["A type guard checks the nested elements and values it claims", "review; no tool"],
|
|
144
|
-
["A startup read does not decide an insert another replica can race", "`antelopejs/no-read-then-insert`"],
|
|
145
|
-
["An awaited function or a promise resolves to no unrun database query", "`antelopejs/no-unrun-query`"],
|
|
146
|
-
["`Object.assign` writes no `unknown`, `any` or mistyped value over a field", "`antelopejs/no-unsafe-object-assign`"],
|
|
147
|
-
["Every file type-aware lint reads is listed by a tsconfig that resolves its imports", "`antelopejs/require-tsconfig-include`"],
|
|
148
|
-
["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
|
|
149
|
-
["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
|
|
150
|
-
["Comment-only changes preserve JavaScript emit", "`antelopejs-comment-proof <base-ref>`"],
|
|
151
|
-
["PR-body proof tables are copied unedited from the current head", "`antelopejs-body-check <body.md>`"],
|
|
152
|
-
["PR-body findings-left lines are live diagnostics at HEAD", "`antelopejs-body-check <body.md>`"],
|
|
153
|
-
["Receiver, positional and unpublished-module behaviour", "`antelopejs-api-diff <base-ref> --probe <file.cjs>`"],
|
|
154
|
-
["Directive and `SAFETY:` reasons are true of the code", "review; no tool"],
|
|
155
|
-
["Evasion-only and patched-internal findings go under Attention", "review; no tool"],
|
|
156
|
-
["No-upward rules reject same-tier peers", "review and import probes"],
|
|
157
|
-
["No `@ts-ignore`", "`typescript/ban-ts-comment`"],
|
|
158
|
-
["No once-used type parameter standing in for `unknown`", "`typescript/no-unnecessary-type-parameters`"],
|
|
159
|
-
["No `any` passed, assigned or returned where a type is declared", "`typescript/no-unsafe-{argument,assignment,return}`"]
|
|
160
|
-
];
|
|
161
|
-
const FULL_RULES = [
|
|
162
|
-
["Files ≤ 20,000 bytes, tests and agent files included", "`antelopejs-check-size` (pre-commit)"],
|
|
163
|
-
["Suppressions stay within `guardrails.suppressions.json`", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
164
|
-
["No lint config switches off a rule to stay under the budget", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
165
|
-
["No added directive disables the `SAFETY:`, comment or test rules", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
166
|
-
["An added suppression gives a specific reason", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
167
|
-
["A directive in a file a change touches suppresses something and gives a reason", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
168
|
-
["A block disable is closed in its file", "`antelopejs-suppressions` (pre-commit, checks)"],
|
|
169
|
-
["Types check", "`tsc` (pre-push)"],
|
|
170
|
-
["No dead files, exports, or dependencies", "knip"],
|
|
171
|
-
["Managed files match the pack", "`antelopejs-sync --check`"],
|
|
172
|
-
["A CI gate reads `needs.<id>` only of jobs in its `needs`", "`antelopejs-sync --check`"],
|
|
173
|
-
["Entry-only rules exempt no tracked outsider", "`antelopejs-sync --check`"],
|
|
174
|
-
["A DMS layer's `build/backend-boundary.ts` is the pack's plugin", "`antelopejs-sync --check`"],
|
|
175
|
-
["No `skipLibCheck` in the root tsconfig or one `typecheck` or `build` uses", "`antelopejs-sync --check`"],
|
|
176
|
-
["`build` skips the lib check only over what `typecheck` checks", "`antelopejs-sync --check`"],
|
|
177
|
-
["`release` runs `typecheck`", "`antelopejs-sync --check`"],
|
|
178
|
-
["A test names the wrong implementation it catches", "review; no tool"]
|
|
179
|
-
];
|
|
180
|
-
/** Pads each column the way oxfmt does, so formatting AGENTS.md never reports sync drift. */
|
|
181
|
-
function ruleTable(rows) {
|
|
182
|
-
const table = [["Rule", "Enforced by"], ...rows];
|
|
183
|
-
const widths = [0, 1].map((column) => Math.max(...table.map((row) => row[column].length)));
|
|
184
|
-
const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
|
|
185
|
-
const [header, ...body] = table.map(line);
|
|
186
|
-
return [
|
|
187
|
-
"### What enforces what",
|
|
188
|
-
"",
|
|
189
|
-
header,
|
|
190
|
-
line(widths.map((width) => "-".repeat(width))),
|
|
191
|
-
...body
|
|
192
|
-
].join("\n");
|
|
193
|
-
}
|
|
113
|
+
\`guardrails.suppressions.json\` caps lint directives, \`@ts-expect-error\`, \`SAFETY:\` comments and rules a lint config turns off. Over a cap, fix the code or remove another suppression of that kind; only the operator raises a number. After removing suppressions, run \`pnpm run suppressions:update\` and commit the file.`;
|
|
194
114
|
function pointers(context) {
|
|
195
115
|
const lines = [];
|
|
196
116
|
if (context.verificationSkill !== void 0) lines.push(`Prove a change works with the verification skill in [\`${context.verificationSkill}\`](${context.verificationSkill}) before you call it done.`);
|
|
197
117
|
if (context.glossary !== void 0) lines.push(`Name things with the terms in [\`${context.glossary}\`](${context.glossary}).`);
|
|
198
118
|
return lines;
|
|
199
119
|
}
|
|
120
|
+
function sections(...parts) {
|
|
121
|
+
return parts.flatMap((part, index) => index === 0 ? [part] : ["", part]);
|
|
122
|
+
}
|
|
200
123
|
function fullBody(context) {
|
|
201
|
-
return
|
|
202
|
-
"## Guardrails",
|
|
203
|
-
"",
|
|
204
|
-
`Finish every change with \`pnpm run checks\`. It runs typecheck, lint, format, knip, tests, size, ${context.ratchet ? "ratchet, " : ""}suppressions, and sync, and prints only what failed. The change is done when it prints no failure.`,
|
|
205
|
-
"",
|
|
206
|
-
ITERATION,
|
|
207
|
-
"",
|
|
208
|
-
...pointers(context).flatMap((line) => [line, ""]),
|
|
209
|
-
"The tools enforce most rules, listed in the table at the end. The sections below hold the rules no tool checks.",
|
|
210
|
-
"",
|
|
211
|
-
COMMENTS,
|
|
212
|
-
"",
|
|
213
|
-
TESTS,
|
|
214
|
-
"",
|
|
215
|
-
CLEANUP_PROOF,
|
|
216
|
-
"",
|
|
217
|
-
SUPPRESSION_BUDGET,
|
|
218
|
-
"",
|
|
219
|
-
...context.ratchet ? [
|
|
220
|
-
"### Debt",
|
|
221
|
-
"",
|
|
222
|
-
"`guardrails.ratchet.json` records the lint findings and oversize files this repository already had. Its numbers only go down. After you remove debt, or after a pack upgrade, run `pnpm run ratchet:update` and commit the file: it lowers the numbers and adds only the rules the new pack release enabled, at today's count. Never edit the numbers by hand; CI fails one added or raised against the base. A rule listed there is off for `oxlint`. The ratchet counts it instead, and the pre-commit hook rejects it on every line you add.",
|
|
223
|
-
""
|
|
224
|
-
] : [],
|
|
225
|
-
ruleTable([
|
|
226
|
-
...SHARED_RULES,
|
|
227
|
-
...FULL_RULES,
|
|
228
|
-
...context.ratchet ? [["Existing debt only shrinks", "`antelopejs-ratchet`"]] : []
|
|
229
|
-
])
|
|
230
|
-
];
|
|
124
|
+
return sections("## Guardrails", ITERATION, ...pointers(context), COMMENTS, TESTS, REVIEW, SUPPRESSIONS);
|
|
231
125
|
}
|
|
232
126
|
function templateBody(context) {
|
|
233
|
-
return
|
|
234
|
-
"## Guardrails",
|
|
235
|
-
"",
|
|
236
|
-
"Lint with `oxlint` and format with `oxfmt`; both read the configs at the repository root. Fix every finding: no rule warns.",
|
|
237
|
-
"",
|
|
238
|
-
...pointers(context).flatMap((line) => [line, ""]),
|
|
239
|
-
COMMENTS,
|
|
240
|
-
"",
|
|
241
|
-
TESTS,
|
|
242
|
-
"",
|
|
243
|
-
CLEANUP_PROOF,
|
|
244
|
-
"",
|
|
245
|
-
ruleTable(SHARED_RULES)
|
|
246
|
-
];
|
|
127
|
+
return sections("## Guardrails", "Lint with `oxlint` and format with `oxfmt`; both read the configs at the repository root. Fix every finding: no rule warns.", ...pointers(context), COMMENTS, TESTS, REVIEW);
|
|
247
128
|
}
|
|
248
129
|
/** The managed block, markers included, ending with a newline. */
|
|
249
130
|
function agentsBlock(context) {
|
|
@@ -464,6 +345,233 @@ function pnpmWorkspaceArtifacts(root, manifest, profile) {
|
|
|
464
345
|
return installRoots(root, manifest, profile).flatMap((installRoot) => installRootArtifact(root, manifest, installRoot));
|
|
465
346
|
}
|
|
466
347
|
//#endregion
|
|
348
|
+
//#region src/guardrails/release-workflow.ts
|
|
349
|
+
const WORKFLOWS = ".github/workflows";
|
|
350
|
+
const RELEASE_PATH = `${WORKFLOWS}/release.yml`;
|
|
351
|
+
const NEXT_SYNC_PATH = `${WORKFLOWS}/next-sync.yml`;
|
|
352
|
+
const RELEASE_CALLER = /^AntelopeJS\/\.github\/\.github\/workflows\/release-npm-(public|private)\.yml@\S+$/;
|
|
353
|
+
/** The caller of next-sync.yml, which merges `main` into `branch` after each push to `main`; next-sync.yml needs `issues: write`. */
|
|
354
|
+
function nextSyncCaller(branch) {
|
|
355
|
+
const inputs = branch === "next" ? "" : ` with:\n branch: ${branch}\n`;
|
|
356
|
+
return `name: Next sync
|
|
357
|
+
|
|
358
|
+
on:
|
|
359
|
+
push:
|
|
360
|
+
branches: [main]
|
|
361
|
+
|
|
362
|
+
permissions: {}
|
|
363
|
+
|
|
364
|
+
jobs:
|
|
365
|
+
next-sync:
|
|
366
|
+
permissions:
|
|
367
|
+
issues: write
|
|
368
|
+
uses: ${sharedWorkflow("next-sync.yml")}
|
|
369
|
+
${inputs} secrets:
|
|
370
|
+
RELEASE_GITHUB_TOKEN: \${{ secrets.RELEASE_GITHUB_TOKEN }}
|
|
371
|
+
NOTION_TOKEN: \${{ secrets.NOTION_TOKEN }}
|
|
372
|
+
`;
|
|
373
|
+
}
|
|
374
|
+
function normalizeDirectory(path) {
|
|
375
|
+
return path.replace(/^(?:\.\/)+/, "").replace(/\/+$/, "") || ".";
|
|
376
|
+
}
|
|
377
|
+
function choiceOptions(document, input) {
|
|
378
|
+
const on = document.get("on", true);
|
|
379
|
+
const options = isMap(on) ? on.getIn([
|
|
380
|
+
"workflow_dispatch",
|
|
381
|
+
"inputs",
|
|
382
|
+
input,
|
|
383
|
+
"options"
|
|
384
|
+
], true) : void 0;
|
|
385
|
+
return isSeq(options) ? options.items.flatMap((item) => isScalar(item) ? [String(item.value)] : []) : [];
|
|
386
|
+
}
|
|
387
|
+
/** The directories a caller's `package-directory` names: a path, a release-train input with a fallback path, or a dispatch input whose choices, between an optional prefix and suffix, are paths. */
|
|
388
|
+
function directoriesOf(root, text) {
|
|
389
|
+
if (text === void 0) return ["."];
|
|
390
|
+
if (!text.includes("${{")) return [normalizeDirectory(text)];
|
|
391
|
+
const fallback = /^\$\{\{\s*inputs\.[\w-]+\s*\|\|\s*'([^']+)'\s*\}\}$/.exec(text);
|
|
392
|
+
if (fallback) return [normalizeDirectory(fallback[1])];
|
|
393
|
+
const input = /^([^$]*)\$\{\{\s*inputs\.([\w-]+)\s*\}\}([^$]*)$/.exec(text);
|
|
394
|
+
if (!input) return [];
|
|
395
|
+
const [, prefix, name, suffix] = input;
|
|
396
|
+
return choiceOptions(root, name).map((option) => normalizeDirectory(`${prefix}${option}${suffix}`));
|
|
397
|
+
}
|
|
398
|
+
function droppedInputs(job) {
|
|
399
|
+
const inputs = job.get("with", true);
|
|
400
|
+
if (!isMap(inputs)) return [];
|
|
401
|
+
return inputs.items.flatMap(({ key }) => isScalar(key) && ![
|
|
402
|
+
"release-version",
|
|
403
|
+
"release-commit",
|
|
404
|
+
"dependency-ranges",
|
|
405
|
+
"install-core",
|
|
406
|
+
"package-directory"
|
|
407
|
+
].includes(String(key.value)) ? [String(key.value)] : []);
|
|
408
|
+
}
|
|
409
|
+
function needsOf(job) {
|
|
410
|
+
const needs = job.get("needs", true);
|
|
411
|
+
if (isScalar(needs)) return [String(needs.value)];
|
|
412
|
+
return isSeq(needs) ? needs.items.flatMap((item) => isScalar(item) ? [String(item.value)] : []) : [];
|
|
413
|
+
}
|
|
414
|
+
function addPackage(found, release, where) {
|
|
415
|
+
const known = found.packages.find(({ directory }) => directory === release.directory);
|
|
416
|
+
if (!known) found.packages.push(release);
|
|
417
|
+
else if (known.registry !== release.registry) found.errors.push(`${where}: ${release.directory} is released to both the public and the private registry. Keep one caller, then rerun antelopejs-sync.`);
|
|
418
|
+
}
|
|
419
|
+
function readCallers(file, text, found) {
|
|
420
|
+
const document = parseDocument(text);
|
|
421
|
+
const root = document.contents;
|
|
422
|
+
const jobs = document.errors.length ? void 0 : document.get("jobs", true);
|
|
423
|
+
if (!isMap(root) || !isMap(jobs)) return;
|
|
424
|
+
const callers = jobs.items.filter(({ value }) => isMap(value) && RELEASE_CALLER.test(String(value.get("uses"))));
|
|
425
|
+
if (!callers.length) return;
|
|
426
|
+
found.files.set(file, text);
|
|
427
|
+
const needed = new Set(callers.flatMap(({ value }) => isMap(value) ? needsOf(value) : []));
|
|
428
|
+
for (const { key, value } of jobs.items) {
|
|
429
|
+
if (!isMap(value)) continue;
|
|
430
|
+
const id = String(isScalar(key) ? key.value : key);
|
|
431
|
+
const registry = RELEASE_CALLER.exec(String(value.get("uses")))?.[1];
|
|
432
|
+
if (registry !== "public" && registry !== "private") {
|
|
433
|
+
if (needed.has(id)) found.dropped.push(`job ${id} of ${file}`);
|
|
434
|
+
else found.errors.push(`${file}: the job ${id} is not part of the release, and sync moves the release callers of this file into ${RELEASE_PATH}. Move ${id} to a workflow file of its own, then rerun antelopejs-sync.`);
|
|
435
|
+
continue;
|
|
436
|
+
}
|
|
437
|
+
found.dropped.push(...droppedInputs(value).map((input) => `input ${input} of ${file}`));
|
|
438
|
+
const inputs = value.get("with", true);
|
|
439
|
+
const directoryNode = isMap(inputs) ? inputs.get("package-directory", true) : void 0;
|
|
440
|
+
const directory = isScalar(directoryNode) ? String(directoryNode.value) : void 0;
|
|
441
|
+
const installCore = isMap(inputs) ? inputs.get("install-core") : void 0;
|
|
442
|
+
const directories = directoriesOf(root, directory);
|
|
443
|
+
if (!directories.length) found.errors.push(`${file}: the job ${id} sets package-directory to ${directory}, which names no package directory. Set it to the package's directory, then rerun antelopejs-sync.`);
|
|
444
|
+
for (const path of directories) {
|
|
445
|
+
const release = {
|
|
446
|
+
directory: path,
|
|
447
|
+
registry
|
|
448
|
+
};
|
|
449
|
+
if (installCore === true || installCore === false) release.installCore = installCore;
|
|
450
|
+
addPackage(found, release, file);
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
}
|
|
454
|
+
/** Every job of `.github/workflows` that calls release-npm-public.yml or release-npm-private.yml, at any ref. */
|
|
455
|
+
function releaseCallers(root) {
|
|
456
|
+
const found = {
|
|
457
|
+
packages: [],
|
|
458
|
+
files: /* @__PURE__ */ new Map(),
|
|
459
|
+
dropped: [],
|
|
460
|
+
errors: []
|
|
461
|
+
};
|
|
462
|
+
const directory = join(root, WORKFLOWS);
|
|
463
|
+
if (!existsSync(directory)) return found;
|
|
464
|
+
for (const name of readdirSync(directory).filter((file) => /\.ya?ml$/.test(file)).sort()) {
|
|
465
|
+
const file = `${WORKFLOWS}/${name}`;
|
|
466
|
+
readCallers(file, readFileSync(join(root, file), "utf8"), found);
|
|
467
|
+
}
|
|
468
|
+
found.packages.sort((a, b) => a.directory.localeCompare(b.directory));
|
|
469
|
+
return found;
|
|
470
|
+
}
|
|
471
|
+
function jobId(release, several) {
|
|
472
|
+
if (!several) return "release";
|
|
473
|
+
return release.directory === "." ? "release-root" : `release-${release.directory.replaceAll("/", "-")}`;
|
|
474
|
+
}
|
|
475
|
+
/** The condition under which a release-train dispatch is for `directory`; the train leaves `package-directory` out for the root package. */
|
|
476
|
+
function dispatched(directory) {
|
|
477
|
+
return directory === "." ? "inputs.package-directory == '' || inputs.package-directory == '.'" : `inputs.package-directory == '${directory}'`;
|
|
478
|
+
}
|
|
479
|
+
function releaseJob(release, several) {
|
|
480
|
+
const nested = release.directory !== ".";
|
|
481
|
+
return [
|
|
482
|
+
` ${jobId(release, several)}:`,
|
|
483
|
+
...several ? [` if: github.event_name == 'push' || ${dispatched(release.directory)}`] : [],
|
|
484
|
+
` uses: ${sharedWorkflow(`release-npm-${release.registry}.yml`)}`,
|
|
485
|
+
" with:",
|
|
486
|
+
" release-version: ${{ inputs.release-version }}",
|
|
487
|
+
" release-commit: ${{ inputs.release-commit }}",
|
|
488
|
+
" dependency-ranges: ${{ inputs.dependency-ranges }}",
|
|
489
|
+
...release.installCore === void 0 ? [] : [` install-core: ${release.installCore}`],
|
|
490
|
+
...!nested ? [] : several ? [` package-directory: ${release.directory}`] : [` package-directory: \${{ inputs.package-directory || '${release.directory}' }}`],
|
|
491
|
+
" secrets:",
|
|
492
|
+
" RELEASE_GITHUB_TOKEN: ${{ secrets.RELEASE_GITHUB_TOKEN }}",
|
|
493
|
+
...release.registry === "private" ? [" NPM_ANTELOPE_TOKEN: ${{ secrets.NPM_ANTELOPE_TOKEN }}"] : []
|
|
494
|
+
].map((line) => `${line}\n`).join("");
|
|
495
|
+
}
|
|
496
|
+
/**
|
|
497
|
+
* The release.yml that publishes `packages`: a preview of each on every push to `branch`, and the stable version the
|
|
498
|
+
* release train dispatches on the default branch with `release-version`, `release-commit`, `dependency-ranges` and, when a package is
|
|
499
|
+
* not at the root, `package-directory`. With several packages, each has its own job, which a dispatch runs only for
|
|
500
|
+
* the `package-directory` it names.
|
|
501
|
+
*/
|
|
502
|
+
function releaseCaller(packages, branch) {
|
|
503
|
+
const several = packages.length > 1;
|
|
504
|
+
return `name: Release
|
|
505
|
+
|
|
506
|
+
on:
|
|
507
|
+
push:
|
|
508
|
+
branches: [${branch}]
|
|
509
|
+
workflow_dispatch:
|
|
510
|
+
inputs:
|
|
511
|
+
release-version:
|
|
512
|
+
description: Stable version to release, set by the release train
|
|
513
|
+
required: false
|
|
514
|
+
type: string
|
|
515
|
+
release-commit:
|
|
516
|
+
description: Commit SHA to release, set by the release train
|
|
517
|
+
required: false
|
|
518
|
+
type: string
|
|
519
|
+
dependency-ranges:
|
|
520
|
+
description: JSON object of stable ranges that replace preview pins, set by the release train
|
|
521
|
+
required: false
|
|
522
|
+
default: "{}"
|
|
523
|
+
type: string
|
|
524
|
+
${packages.some(({ directory }) => directory !== ".") ? ` package-directory:
|
|
525
|
+
description: Directory of the package to release, set by the release train
|
|
526
|
+
required: false
|
|
527
|
+
type: string
|
|
528
|
+
` : ""}
|
|
529
|
+
permissions:
|
|
530
|
+
contents: write
|
|
531
|
+
${packages.some(({ registry }) => registry === "public") ? " id-token: write\n" : ""}
|
|
532
|
+
jobs:
|
|
533
|
+
${packages.map((release) => releaseJob(release, several)).join("\n")}`;
|
|
534
|
+
}
|
|
535
|
+
/**
|
|
536
|
+
* Brings every release caller of the repository into one release.yml at the shared tag, so the release train, which
|
|
537
|
+
* dispatches release.yml only, reaches each package, and npm trusted publishing sees one calling workflow file. Each
|
|
538
|
+
* other workflow file that held a release caller is removed. Inputs the shared workflows no longer take (`channel`,
|
|
539
|
+
* `services-compose-file`) and jobs besides the callers, such as a metadata `validate` job, are dropped and named in
|
|
540
|
+
* a note. A repository with no release caller publishes nothing, and nothing is written.
|
|
541
|
+
*/
|
|
542
|
+
function releaseArtifacts(root, branch) {
|
|
543
|
+
const found = releaseCallers(root);
|
|
544
|
+
if (found.errors.length) return found.errors.map((message) => ({
|
|
545
|
+
kind: "error",
|
|
546
|
+
path: RELEASE_PATH,
|
|
547
|
+
message
|
|
548
|
+
}));
|
|
549
|
+
if (!found.packages.length) return [];
|
|
550
|
+
const content = releaseCaller(found.packages, branch);
|
|
551
|
+
const removed = [...found.files.keys()].filter((file) => file !== RELEASE_PATH);
|
|
552
|
+
const artifacts = removed.map((path) => ({
|
|
553
|
+
kind: "remove",
|
|
554
|
+
path
|
|
555
|
+
}));
|
|
556
|
+
if (found.files.get(RELEASE_PATH) === content) return [...artifacts, {
|
|
557
|
+
kind: "unchanged",
|
|
558
|
+
path: RELEASE_PATH
|
|
559
|
+
}];
|
|
560
|
+
const notes = [...found.dropped.map((item) => `Dropped ${item}: release-npm-*.yml@v2 validates the package metadata, takes no channel and runs no tests.`), ...removed.map((file) => `Moved the release caller of ${file} into ${RELEASE_PATH}, the only workflow the release train dispatches. Point the package's npm trusted publisher at release.yml.`)];
|
|
561
|
+
return [...artifacts, notes.length ? {
|
|
562
|
+
kind: "migrated",
|
|
563
|
+
path: RELEASE_PATH,
|
|
564
|
+
content,
|
|
565
|
+
mode: void 0,
|
|
566
|
+
notes
|
|
567
|
+
} : {
|
|
568
|
+
kind: "write",
|
|
569
|
+
path: RELEASE_PATH,
|
|
570
|
+
content,
|
|
571
|
+
mode: void 0
|
|
572
|
+
}];
|
|
573
|
+
}
|
|
574
|
+
//#endregion
|
|
467
575
|
//#region src/guardrails/backend-boundary.ts
|
|
468
576
|
/** Where a DMS frontend layer keeps its backend boundary plugin, relative to the layer. */
|
|
469
577
|
const BACKEND_BOUNDARY_FILE = "build/backend-boundary.ts";
|
|
@@ -602,12 +710,12 @@ function boundaryCheck(): VitePlugin {
|
|
|
602
710
|
function formatFreeProgram(text) {
|
|
603
711
|
const parts = [];
|
|
604
712
|
const visit = (node) => {
|
|
605
|
-
if (
|
|
606
|
-
parts.push(
|
|
607
|
-
if (
|
|
608
|
-
|
|
713
|
+
if (typescript6_default.isParenthesizedExpression(node) || typescript6_default.isParenthesizedTypeNode(node)) return void typescript6_default.forEachChild(node, visit);
|
|
714
|
+
parts.push(typescript6_default.SyntaxKind[node.kind]);
|
|
715
|
+
if (typescript6_default.isIdentifier(node) || typescript6_default.isPrivateIdentifier(node) || typescript6_default.isLiteralExpression(node) || typescript6_default.isTemplateHead(node) || typescript6_default.isTemplateMiddle(node) || typescript6_default.isTemplateTail(node)) parts.push(JSON.stringify(node.text));
|
|
716
|
+
typescript6_default.forEachChild(node, visit);
|
|
609
717
|
};
|
|
610
|
-
visit(
|
|
718
|
+
visit(typescript6_default.createSourceFile("backend-boundary.ts", text, typescript6_default.ScriptTarget.Latest, false, typescript6_default.ScriptKind.TS));
|
|
611
719
|
return parts.join(" ");
|
|
612
720
|
}
|
|
613
721
|
/** The sync plan for every tracked backend boundary plugin under `root`: each one is the pack's plugin for the package that holds its layer, in any formatting. */
|
|
@@ -766,17 +874,17 @@ function unreadableNotes(files) {
|
|
|
766
874
|
}
|
|
767
875
|
/** The property `name` of a JSON object literal; when the key is repeated the last one wins, as when tsc reads it. */
|
|
768
876
|
function propertyNamed(object, name) {
|
|
769
|
-
if (object === void 0 || !
|
|
770
|
-
return object.properties.findLast((item) =>
|
|
877
|
+
if (object === void 0 || !typescript6_default.isObjectLiteralExpression(object)) return void 0;
|
|
878
|
+
return object.properties.findLast((item) => typescript6_default.isPropertyAssignment(item) && (typescript6_default.isIdentifier(item.name) || typescript6_default.isStringLiteral(item.name)) && item.name.text === name)?.initializer;
|
|
771
879
|
}
|
|
772
880
|
/** The root value of a JSON text, comments and trailing commas allowed. */
|
|
773
881
|
function jsonRoot(file, text) {
|
|
774
|
-
return
|
|
882
|
+
return typescript6_default.parseJsonText(file, text).statements[0]?.expression;
|
|
775
883
|
}
|
|
776
884
|
/** The strings of a JSON string or array of strings. */
|
|
777
885
|
function stringValues(value) {
|
|
778
886
|
if (value === void 0) return [];
|
|
779
|
-
return (
|
|
887
|
+
return (typescript6_default.isArrayLiteralExpression(value) ? value.elements : [value]).filter(typescript6_default.isStringLiteral).map((item) => item.text);
|
|
780
888
|
}
|
|
781
889
|
//#endregion
|
|
782
890
|
//#region src/guardrails/release-hooks.ts
|
|
@@ -787,8 +895,8 @@ function hooksIn(files, file, path) {
|
|
|
787
895
|
if (text === void 0) return [];
|
|
788
896
|
let node = jsonRoot(file, text);
|
|
789
897
|
for (const key of path) node = propertyNamed(node, key);
|
|
790
|
-
if (node === void 0 || !
|
|
791
|
-
return node.properties.flatMap((property) =>
|
|
898
|
+
if (node === void 0 || !typescript6_default.isObjectLiteralExpression(node)) return [];
|
|
899
|
+
return node.properties.flatMap((property) => typescript6_default.isPropertyAssignment(property) && (typescript6_default.isStringLiteral(property.name) || typescript6_default.isIdentifier(property.name)) && BEFORE_PUBLISH.test(property.name.text) && propertyNamed(node, property.name.text) === property.initializer ? stringValues(property.initializer) : []);
|
|
792
900
|
}
|
|
793
901
|
/** The commands of the release-it hooks that run before publishing, from `.release-it.json` and from the `release-it` key of `package.json`. Other config formats are not read. */
|
|
794
902
|
function releaseHooks(files) {
|
|
@@ -805,7 +913,18 @@ function normalizeProgram(project) {
|
|
|
805
913
|
function optionName(word) {
|
|
806
914
|
return word.startsWith("-") ? word.replace(/^--?/u, "").toLowerCase() : void 0;
|
|
807
915
|
}
|
|
808
|
-
|
|
916
|
+
/** The options `tsc -b` accepts that take a string as the next word, which would otherwise read as a project; TypeScript 7 adds `builders`, `checkers` and `pprofdir`. */
|
|
917
|
+
const VALUED = /* @__PURE__ */ new Set([
|
|
918
|
+
"builders",
|
|
919
|
+
"checkers",
|
|
920
|
+
"pprofdir",
|
|
921
|
+
"locale",
|
|
922
|
+
"generatetrace",
|
|
923
|
+
"generatecpuprofile"
|
|
924
|
+
]);
|
|
925
|
+
/** The explicit values a boolean option such as `--pretty false` takes, which are not projects. */
|
|
926
|
+
const BOOLEAN_VALUES = /* @__PURE__ */ new Set(["true", "false"]);
|
|
927
|
+
function tscRun(command, args) {
|
|
809
928
|
const build = ["b", "build"].includes(optionName(args[0] ?? "") ?? "");
|
|
810
929
|
const positional = [];
|
|
811
930
|
let project;
|
|
@@ -813,11 +932,13 @@ function tscRun(args) {
|
|
|
813
932
|
for (let index = build ? 1 : 0; index < args.length; index++) {
|
|
814
933
|
const option = optionName(args[index]);
|
|
815
934
|
if (option === "p" || option === "project") project = args[++index];
|
|
935
|
+
else if (option !== void 0 && VALUED.has(option)) index++;
|
|
816
936
|
else if (option === "skiplibcheck") skipsLibCheck = args[index + 1] !== "false";
|
|
817
|
-
else if (option === void 0) positional.push(args[index]);
|
|
937
|
+
else if (option === void 0 && !BOOLEAN_VALUES.has(args[index])) positional.push(args[index]);
|
|
818
938
|
}
|
|
819
939
|
const named = build ? positional : project === void 0 ? [] : [project];
|
|
820
940
|
return {
|
|
941
|
+
command,
|
|
821
942
|
programs: (named.length === 0 ? ["."] : named).map(normalizeProgram),
|
|
822
943
|
build,
|
|
823
944
|
skipsLibCheck
|
|
@@ -844,7 +965,7 @@ function referencedFile(files, from, path) {
|
|
|
844
965
|
}
|
|
845
966
|
function referencePaths(object) {
|
|
846
967
|
const references = propertyNamed(object, "references");
|
|
847
|
-
if (references === void 0 || !
|
|
968
|
+
if (references === void 0 || !typescript6_default.isArrayLiteralExpression(references)) return [];
|
|
848
969
|
return references.elements.flatMap((element) => stringValues(propertyNamed(element, "path")));
|
|
849
970
|
}
|
|
850
971
|
function readFacts(files, file) {
|
|
@@ -854,7 +975,7 @@ function readFacts(files, file) {
|
|
|
854
975
|
const flag = propertyNamed(propertyNamed(object, "compilerOptions"), "skipLibCheck");
|
|
855
976
|
const resolve = (found) => found ? [found] : [];
|
|
856
977
|
return {
|
|
857
|
-
skipLibCheck: flag === void 0 ? void 0 : flag.kind ===
|
|
978
|
+
skipLibCheck: flag === void 0 ? void 0 : flag.kind === typescript6_default.SyntaxKind.TrueKeyword,
|
|
858
979
|
parents: stringValues(propertyNamed(object, "extends")).flatMap((entry) => resolve(extendedFile(files, file, entry))),
|
|
859
980
|
references: referencePaths(object).flatMap((path) => resolve(referencedFile(files, file, path)))
|
|
860
981
|
};
|
|
@@ -939,18 +1060,18 @@ function reach(scripts, name, extra = []) {
|
|
|
939
1060
|
return reached;
|
|
940
1061
|
}
|
|
941
1062
|
function ownRuns(script) {
|
|
942
|
-
return stepsOf(script).flatMap((step) => step.kind === "tsc" ? [tscRun(step.args)] : []);
|
|
1063
|
+
return stepsOf(script).flatMap((step) => step.kind === "tsc" ? [tscRun(step.command, step.args)] : []);
|
|
943
1064
|
}
|
|
944
1065
|
function runsOf(scripts, name) {
|
|
945
1066
|
return [...reach(scripts, name).local].flatMap((script) => ownRuns(scripts.get(script) ?? ""));
|
|
946
1067
|
}
|
|
947
1068
|
function skipCoverageErrors(scripts) {
|
|
948
|
-
const skipped =
|
|
1069
|
+
const skipped = new Map(runsOf(scripts, "build").filter((run) => run.skipsLibCheck).flatMap((run) => run.programs.map((program) => [program, run.command])));
|
|
949
1070
|
const typecheck = runsOf(scripts, "typecheck");
|
|
950
1071
|
const covered = typecheck.filter((run) => !run.skipsLibCheck).flatMap((run) => run.programs);
|
|
951
|
-
return skipped.filter((program) => !covered.includes(program)).map((program) => {
|
|
952
|
-
const lead = `package.json: script "build" passes --skipLibCheck to
|
|
953
|
-
const fix = `Make "typecheck" run
|
|
1072
|
+
return [...skipped].filter(([program]) => !covered.includes(program)).map(([program, command]) => {
|
|
1073
|
+
const lead = `package.json: script "build" passes --skipLibCheck to ${command} for ${program}, but`;
|
|
1074
|
+
const fix = `Make "typecheck" run \`${command} --noEmit${program === "tsconfig.json" ? "" : ` -p ${program}`}\` without --skipLibCheck, or drop --skipLibCheck from "build".`;
|
|
954
1075
|
if (!scripts.has("typecheck")) return `${lead} there is no "typecheck" script. ${fix}`;
|
|
955
1076
|
if (typecheck.some((run) => run.programs.includes(program))) return `${lead} script "typecheck" also passes --skipLibCheck for it. ${fix}`;
|
|
956
1077
|
return `${lead} script "typecheck" runs no full tsc over it. ${fix}`;
|
|
@@ -1146,7 +1267,7 @@ Each journey deletes its scratch folder and \`HOME\`, its install included, when
|
|
|
1146
1267
|
- \`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.
|
|
1147
1268
|
|
|
1148
1269
|
- \`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.
|
|
1149
|
-
- \`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
|
|
1270
|
+
- \`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\`, and optionally \`files\`).
|
|
1150
1271
|
${text.layer}
|
|
1151
1272
|
- \`features/README.md\`: the index of the features; \`map\` does not read it as a feature.
|
|
1152
1273
|
- \`features/<feature>.md\`: frontmatter lists \`covers:\` (source globs), \`docs:\` (pages a verdict judges) and \`journeys:\`, then the sections Sub-features, How to get to it (user POV), Driving it with antelopejs-verify, and Gotchas. \`features/smoke.md\` covers nothing and runs on every verdict; here it runs ${text.smoke}.
|
|
@@ -1163,13 +1284,7 @@ ${BIN} map
|
|
|
1163
1284
|
2. **An unmapped surface fails the verdict.** A changed user-facing file no feature covers needs a feature entry and its journeys in the same PR.
|
|
1164
1285
|
3. **Every registered journey of a feature in \`run\` must have run and passed.** Run whole features. A journey that could not reach the product, or whose environment went away during it, is NOT VERIFIED, and so is the verdict, whatever else passed: never PASS and never PASS+NOTES. Every journey result in the run's evidence counts, also for a feature outside \`run\`: a failed one fails the verdict, because it shows a \`covers:\` glob that misses what the diff broke. A NOT VERIFIED one outside \`run\` is listed under Not verified and caps the result at PASS+NOTES. A journey outside \`run\` that never ran is not required.
|
|
1165
1286
|
4. **Docs.** Judge every page \`plan\` lists as \`docs\` against what the journeys showed: the \`docs:\` pages of the touched features, or of every feature when the full set runs. A stale page fails the verdict.
|
|
1166
|
-
5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff, or whose own \`files\` the diff changes,
|
|
1167
|
-
- a covered check that did not run, or exits non-zero (a tool error, or a check that no longer matches its record), fails the verdict;
|
|
1168
|
-
- when the covered behaviour did not change, the verdict reports recorded findings as known findings, except a rule HEAD breaks that the base run did not, which fails the verdict whatever the diff touched, the check's own \`files\` included; when the base run itself exited non-zero, HEAD's findings cannot be compared and fail the verdict, and so does a result whose check's own \`files\` changed with no base run recorded. A check the diff adds is the exception: when the base could not run it, the base's \`verify.config.ts\` never names it, none of its files is a git rename of a base file, and the covered behaviour is unchanged, its recorded findings pass as the record it brings. List those findings in the PR body so a reviewer sees what the record accepts. A new check on a diff that also changes the covered code fails with \`new check with a covered-code change: land the check in its own PR first\`: land the check alone, then the code change. A moved or renamed check is a changed check;
|
|
1169
|
-
- when the covered behaviour changed, or the diff changed the check's own \`files\`, \`formal\` also runs the check on the base (\`baseCommand\` when set). A rule the base broke counts as fixed only when HEAD reports it passing (\`passing\`); a rule the base broke that HEAD does not report at all fails the verdict. A change that leaves no violated rule passes;
|
|
1170
|
-
- when the covered behaviour changed, recorded findings fail the verdict unless the base run exited 0 and broke each of them with the same counterexample length (the \`states\` named group of \`violation\`, after the rule's group, in decimal digits; a \`states\` group that is the first group or captures anything else gives no length), and HEAD fixed every other rule the base broke; then the verdict reports them as the same known findings as the base, with the fixed ones. A new rule, a changed length, or a length either run did not print fails.
|
|
1171
|
-
|
|
1172
|
-
Whether the behaviour changed never reads the check's output, so a model whose rule names stay the same still fails on a changed behaviour unless the rule above keeps its findings known. It is conservative: a local rename or an extracted helper counts as changed, and code outside \`covers\` is invisible to it. \`--all\` also runs the checks that do not cover the diff, without gating.
|
|
1287
|
+
5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff, or whose own \`files\` the diff changes, records it under \`evidence/formal/<name>/\` and prints HOLDS, VIOLATED or ERROR for each. A covered check fails the verdict when it did not run, when its output names a rule its \`violation\` pattern matches (VIOLATED, whatever the exit code), or when it exits non-zero without naming one (ERROR; a check without a \`violation\` pattern names the rule \`property\` instead, so it is VIOLATED). \`--all\` also runs the checks that do not cover the diff, without gating.
|
|
1173
1288
|
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.
|
|
1174
1289
|
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.
|
|
1175
1290
|
|
|
@@ -1197,10 +1312,6 @@ ${BIN} verdict <run> --pr <n> --judgement <file>
|
|
|
1197
1312
|
|
|
1198
1313
|
\`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.
|
|
1199
1314
|
|
|
1200
|
-
## Trust
|
|
1201
|
-
|
|
1202
|
-
The skill is not Trusted yet. It becomes Trusted when it passes a shadow run of 10 consecutive agent PRs and its last maintain pass is newer than the last change to the repository or its \`@antelopejs\` dependencies and at most 30 days old.
|
|
1203
|
-
|
|
1204
1315
|
## Gotchas
|
|
1205
1316
|
|
|
1206
1317
|
${bullets(text.gotchas)}
|
|
@@ -1427,7 +1538,6 @@ function applyVerifyActions(root, actions) {
|
|
|
1427
1538
|
//#endregion
|
|
1428
1539
|
//#region src/guardrails/sync.ts
|
|
1429
1540
|
const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
|
|
1430
|
-
const RETIRED_RATCHET = `${CEILINGS_FILE} has no debt left. Run ratchet:update to delete it, then run antelopejs-sync.`;
|
|
1431
1541
|
function managedAgents(current = "", context) {
|
|
1432
1542
|
const start = current.indexOf(AGENTS_BLOCK_START);
|
|
1433
1543
|
const end = current.indexOf(AGENTS_BLOCK_END);
|
|
@@ -1460,7 +1570,7 @@ const MANAGED_ARTIFACTS = [
|
|
|
1460
1570
|
path: "lefthook.yml",
|
|
1461
1571
|
profiles: ["full"],
|
|
1462
1572
|
desired: (current, context) => ({
|
|
1463
|
-
content: lefthook(current, context.manager
|
|
1573
|
+
content: lefthook(current, context.manager),
|
|
1464
1574
|
notes: []
|
|
1465
1575
|
})
|
|
1466
1576
|
},
|
|
@@ -1468,7 +1578,10 @@ const MANAGED_ARTIFACTS = [
|
|
|
1468
1578
|
path: CI_PATH,
|
|
1469
1579
|
profiles: ["full", "template"],
|
|
1470
1580
|
desired: (current, context) => ({
|
|
1471
|
-
content: ciWorkflow(current, current === void 0 ? [] : ciNodeCallers(current), current === void 0 ? [] : ciRenovateSyncCallers(current),
|
|
1581
|
+
content: ciWorkflow(current, current === void 0 ? [] : ciNodeCallers(current), current === void 0 ? [] : ciRenovateSyncCallers(current), {
|
|
1582
|
+
...context.ci,
|
|
1583
|
+
docsFiles: context.docs
|
|
1584
|
+
}),
|
|
1472
1585
|
notes: []
|
|
1473
1586
|
})
|
|
1474
1587
|
},
|
|
@@ -1483,6 +1596,14 @@ const MANAGED_ARTIFACTS = [
|
|
|
1483
1596
|
};
|
|
1484
1597
|
}
|
|
1485
1598
|
},
|
|
1599
|
+
{
|
|
1600
|
+
path: NEXT_SYNC_PATH,
|
|
1601
|
+
profiles: ["full"],
|
|
1602
|
+
desired: (_current, context) => ({
|
|
1603
|
+
content: nextSyncCaller((context.ci.profile ?? ciProfile(void 0)).integrationBranch),
|
|
1604
|
+
notes: []
|
|
1605
|
+
})
|
|
1606
|
+
},
|
|
1486
1607
|
GITATTRIBUTES_ARTIFACT,
|
|
1487
1608
|
{
|
|
1488
1609
|
path: ".nvmrc",
|
|
@@ -1514,14 +1635,6 @@ const MANAGED_ARTIFACTS = [
|
|
|
1514
1635
|
notes: context.claude ? ["Moved CLAUDE.md content into AGENTS.md's hand-written part before the managed block."] : []
|
|
1515
1636
|
})
|
|
1516
1637
|
},
|
|
1517
|
-
{
|
|
1518
|
-
path: CEILINGS_FILE,
|
|
1519
|
-
profiles: ["full"],
|
|
1520
|
-
desired: (current, context) => ({
|
|
1521
|
-
content: current ?? context.baseline,
|
|
1522
|
-
notes: []
|
|
1523
|
-
})
|
|
1524
|
-
},
|
|
1525
1638
|
{
|
|
1526
1639
|
path: SUPPRESSIONS_FILE,
|
|
1527
1640
|
profiles: ["full", "template"],
|
|
@@ -1540,7 +1653,6 @@ function planSync(current, executables, context) {
|
|
|
1540
1653
|
});
|
|
1541
1654
|
for (const artifact of MANAGED_ARTIFACTS) {
|
|
1542
1655
|
if (!artifact.profiles.includes(context.profile)) continue;
|
|
1543
|
-
if (artifact.path === "guardrails.ratchet.json" && !context.ratchet) continue;
|
|
1544
1656
|
if (artifact.path === ".github/workflows/ci.yml" && !context.managesCi) continue;
|
|
1545
1657
|
try {
|
|
1546
1658
|
const { content, notes } = artifact.desired(current.get(artifact.path), context);
|
|
@@ -1621,20 +1733,18 @@ function repositoryContext(root, current, profile, verificationSkill) {
|
|
|
1621
1733
|
const manager = packageManager(manifest);
|
|
1622
1734
|
return {
|
|
1623
1735
|
profile,
|
|
1624
|
-
ratchet: current.has(CEILINGS_FILE),
|
|
1625
1736
|
manager,
|
|
1626
1737
|
versions: toolingVersions(),
|
|
1627
1738
|
tools: repositoryTools(manifest),
|
|
1628
1739
|
typeAware: /\btypeAware["']?\s*:\s*true\b/.test(desiredLint),
|
|
1629
1740
|
nuxt: usesNuxt(root, manifest),
|
|
1630
1741
|
claude: profile === "full" ? claudeProse(root, current) : "",
|
|
1631
|
-
baseline: "",
|
|
1632
1742
|
suppressionBudget: adoptedBudget(root, current.get(SUPPRESSIONS_FILE)),
|
|
1633
1743
|
managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
|
|
1634
1744
|
verificationSkill: profile === "template" && inScaffoldExcludedPath(verificationSkill) ? void 0 : verificationSkill,
|
|
1635
1745
|
glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file))),
|
|
1636
1746
|
docs: profile === "full" && current.has("package.json") ? planDocs(root, manager) : void 0,
|
|
1637
|
-
|
|
1747
|
+
ci: callerPlan(manifest),
|
|
1638
1748
|
captures: usesCaptures(root)
|
|
1639
1749
|
};
|
|
1640
1750
|
}
|
|
@@ -1647,14 +1757,15 @@ function writeArtifacts(root, artifacts) {
|
|
|
1647
1757
|
if (artifact.mode !== void 0) makeExecutable(root, artifact.path, artifact.mode);
|
|
1648
1758
|
}
|
|
1649
1759
|
}
|
|
1760
|
+
function removeArtifacts(root, paths) {
|
|
1761
|
+
for (const path of paths) unlinkSync(join(root, path));
|
|
1762
|
+
}
|
|
1650
1763
|
function repositoryNotices(root, context) {
|
|
1651
1764
|
const notices = [];
|
|
1652
1765
|
if (context.profile === "full" && !hasChecksWorkflow(root) && existsSync(join(root, ".github/workflows/ci.yml"))) notices.push(MISSING_CHECKS_WORKFLOW);
|
|
1653
|
-
if (context.ratchet && isRetired(readCeilings(root))) notices.push(RETIRED_RATCHET);
|
|
1654
1766
|
return notices;
|
|
1655
1767
|
}
|
|
1656
1768
|
/**
|
|
1657
|
-
* Measures debt only on first adoption, before sync has written the sync:check script; retired repositories stay retired.
|
|
1658
1769
|
* Under the template profile the agent layer, `verify-template` and the writing skills, is synced only in the template source,
|
|
1659
1770
|
* marked by its `.agents/skills/verify-template` folder or chosen with `--verify template`, because a scaffold ships without it,
|
|
1660
1771
|
* and the AGENTS.md block, which a scaffold keeps, links no skill under it.
|
|
@@ -1674,9 +1785,11 @@ function syncRepository(root, options = {}) {
|
|
|
1674
1785
|
const standalone = [
|
|
1675
1786
|
...backendBoundaryArtifacts(root),
|
|
1676
1787
|
...renovateArtifacts(root, manifest, profile === "full" || verify.kind === "template"),
|
|
1677
|
-
...pnpmWorkspaceArtifacts(root, manifest, profile)
|
|
1788
|
+
...pnpmWorkspaceArtifacts(root, manifest, profile),
|
|
1789
|
+
...releaseArtifacts(root, (context.ci.profile ?? ciProfile(void 0)).integrationBranch)
|
|
1678
1790
|
];
|
|
1679
|
-
|
|
1791
|
+
const synced = [...planSync(current, executables, context), ...standalone];
|
|
1792
|
+
const plan = [...synced, ...sharedRefArtifacts(root, new Set(synced.map(({ path }) => path)))];
|
|
1680
1793
|
const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
|
|
1681
1794
|
const entryOnly = checkEntryOnlyConfiguration(root);
|
|
1682
1795
|
const coverage = checkTypecheckCoverage(root, Boolean(options.check));
|
|
@@ -1684,20 +1797,11 @@ function syncRepository(root, options = {}) {
|
|
|
1684
1797
|
errors.push(...coverage.errors);
|
|
1685
1798
|
const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
|
|
1686
1799
|
(options.check ? errors : notes).push(...repositoryNotices(root, context));
|
|
1687
|
-
if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
|
|
1688
|
-
const lint = PRESET_CONFIGS[0];
|
|
1689
|
-
const desired = presetConfig(current.get(lint.path), lint, context.tools);
|
|
1690
|
-
const baseline = measureBaseline(root, desired === current.get(lint.path) ? void 0 : desired);
|
|
1691
|
-
context.ratchet = !isRetired(baseline);
|
|
1692
|
-
context.baseline = formatCeilings({
|
|
1693
|
-
...baseline,
|
|
1694
|
-
pack: recordedRelease(void 0)
|
|
1695
|
-
});
|
|
1696
|
-
plan = [...planSync(current, executables, context), ...standalone];
|
|
1697
|
-
}
|
|
1698
1800
|
const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
|
|
1801
|
+
const removals = plan.flatMap((artifact) => artifact.kind === "remove" ? [artifact.path] : []);
|
|
1699
1802
|
if (!options.check && !errors.length) {
|
|
1700
1803
|
writeArtifacts(root, writes);
|
|
1804
|
+
removeArtifacts(root, removals);
|
|
1701
1805
|
applyVerifyActions(root, actions);
|
|
1702
1806
|
}
|
|
1703
1807
|
const templateDependencies = ["knip"];
|
|
@@ -1705,8 +1809,12 @@ function syncRepository(root, options = {}) {
|
|
|
1705
1809
|
const dependenciesAdded = profile === "full" ? addedDevDependencies(manifest, context.versions, context).length > 0 : templateDependencies.some((name) => !manifest.devDependencies?.[name]);
|
|
1706
1810
|
return {
|
|
1707
1811
|
artifacts: plan,
|
|
1708
|
-
paths: errors.length ? [] : [
|
|
1709
|
-
|
|
1812
|
+
paths: errors.length ? [] : [
|
|
1813
|
+
...writes.map(({ path }) => path),
|
|
1814
|
+
...removals,
|
|
1815
|
+
...actions.map(({ path }) => path)
|
|
1816
|
+
],
|
|
1817
|
+
removed: [...removals, ...actions.filter((action) => action.kind === "remove").map(({ path }) => path)],
|
|
1710
1818
|
errors,
|
|
1711
1819
|
notes,
|
|
1712
1820
|
verifyNotes: options.check || errors.length ? [] : verify.notes,
|