@antelopejs/tooling-configs 0.2.10 → 0.2.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -9
- package/dist/bin/api-diff.mjs +74 -41
- package/dist/bin/garden.mjs +13 -71
- package/dist/bin/ratchet.mjs +2 -2
- package/dist/bin/suppressions.mjs +33 -21
- package/dist/bin/sync.mjs +369 -24
- package/dist/bin/verify.d.mts +1 -0
- package/dist/bin/verify.mjs +3000 -0
- package/dist/checks-BlWDFYio.mjs +94 -0
- package/dist/json-BqvuCkqr.mjs +67 -0
- package/dist/kinds-Bzyyi9yk.mjs +25 -0
- package/dist/oxc/guardrails/index.mjs +119 -0
- package/dist/oxc/lint.d.mts +4 -0
- package/dist/oxc/lint.mjs +1 -0
- package/dist/{ratchet-B2qYUs51.mjs → ratchet-DRdIYwmv.mjs} +1 -1
- package/dist/staged-ratchet-CjoRfZaM.mjs +236 -0
- package/dist/{suppression-budget-Bq30tJDS.mjs → suppression-budget-Yyf5_J5l.mjs} +2 -1
- package/dist/verify/index.d.mts +262 -0
- package/dist/verify/index.mjs +2 -0
- package/package.json +5 -3
- package/dist/staged-ratchet-BNfjcbih.mjs +0 -119
package/dist/bin/sync.mjs
CHANGED
|
@@ -3,10 +3,11 @@ import { a as formatCeilings, o as isRetired, s as readCeilings, t as CEILINGS_F
|
|
|
3
3
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
4
4
|
import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
|
|
5
5
|
import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-Dtjt_lSa.mjs";
|
|
6
|
-
import { t as measureBaseline } from "../ratchet-
|
|
7
|
-
import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-
|
|
6
|
+
import { t as measureBaseline } from "../ratchet-DRdIYwmv.mjs";
|
|
7
|
+
import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Yyf5_J5l.mjs";
|
|
8
8
|
import { a as ciWorkflow, c as ciNodeCallers, i as MUTATION_PATH, l as hasChecksWorkflow, o as mutationCaller, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW } from "../ci-workflow-BDy6hQJ6.mjs";
|
|
9
|
-
import {
|
|
9
|
+
import { a as skillFolder, i as isVerifyKind, n as claudeLink, r as claudeLinkTarget, t as VERIFY_KINDS } from "../kinds-Bzyyi9yk.mjs";
|
|
10
|
+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
|
|
10
11
|
import { dirname, join, resolve } from "node:path";
|
|
11
12
|
import { execFileSync } from "node:child_process";
|
|
12
13
|
import { parseArgs } from "node:util";
|
|
@@ -50,6 +51,7 @@ const SHARED_RULES = [
|
|
|
50
51
|
["Comments are TSDoc, directives, or `SAFETY:` only", "`antelopejs/no-comments`"],
|
|
51
52
|
["Every test asserts", "`antelopejs/require-assertion`"],
|
|
52
53
|
["Tests read no files outside fixtures, helpers, locales", "`antelopejs/no-fs-read-in-tests`"],
|
|
54
|
+
["Tests import the code under test from local source, not their own package name", "`antelopejs/no-self-import-in-tests`"],
|
|
53
55
|
["No assertion that restates a constant", "`antelopejs/no-constant-value-assertion`"],
|
|
54
56
|
["No test whose only check is \"is a function\"", "`antelopejs/no-typeof-function-only-test`"],
|
|
55
57
|
["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
|
|
@@ -339,6 +341,349 @@ function checkEntryOnlyConfiguration(root) {
|
|
|
339
341
|
advisories
|
|
340
342
|
};
|
|
341
343
|
}
|
|
344
|
+
/** The kind-specific text of each shared skill. */
|
|
345
|
+
const KIND_TEXT = {
|
|
346
|
+
interface: {
|
|
347
|
+
description: "Drive this AntelopeJS interface the way a module author does: pack it, load it in `ajs project dev` next to a stub provider wired through ImplementInterface and a consumer, call every declared function through core, and check the minor-bump rule against the published version. Use to prove a change to the interface works before merge, to verify a PR, or to check that a seeded break is caught.",
|
|
348
|
+
title: "Verify interface",
|
|
349
|
+
user: "The user of an interface is a module author: one module implements it, others import it and call its functions through core.",
|
|
350
|
+
launch: "`new` runs the setup (`pnpm run build` by default), then packs the interface with `pnpm pack` and extracts it, so journeys load what npm would publish, `files` and `exports` included.",
|
|
351
|
+
builtins: `- \`every-function\`: a fixture project loads the packed interface with a stub provider and a consumer module. The consumer walks the loaded interface, and every function the \`.d.ts\` files declare is called through core:
|
|
352
|
+
- an async proxy answers the stub's echo, and the stub's call log shows the same arguments (the second view);
|
|
353
|
+
- a registering proxy registers and unregisters, and the stub logs both;
|
|
354
|
+
- an event proxy delivers the emitted arguments to a registered handler;
|
|
355
|
+
- a plain function runs the \`interface.calls\` hook of \`verify.config.ts\` and must return its \`expect\`; one only providers call is listed in \`interface.providerSide\` with why.
|
|
356
|
+
A declared function with none of these fails the journey.
|
|
357
|
+
- \`minor-bump\`: reads the declared functions of the packed head and of the published version (\`npm pack <name>@<latest>\`). An added, changed or removed function needs a release of at least the next minor. The release is the head version when it is already bumped, otherwise what changelogen makes of the change title (\`new --title\`) or the commit subjects since the base.`,
|
|
358
|
+
layer: `- \`interface.provide(api)\` runs in the stub provider after the generic stubs attach, for example to hand a stub client to \`internal.SetClient\`.
|
|
359
|
+
- \`interface.calls["<entry>:<path>"]\` calls a plain exported function from the consumer and states the value it must return.
|
|
360
|
+
- \`interface.providerSide["<entry>:<path>"]\` names a function only providers call, with the reason.`,
|
|
361
|
+
smoke: "`every-function`",
|
|
362
|
+
gotchas: ["A function the consumer awaits forever, such as a getter no provider resolved, fails after 15 seconds with a `Timeout` value.", "`minor-bump` needs the npm registry. Without it the journey is not verified, never passed."]
|
|
363
|
+
},
|
|
364
|
+
module: {
|
|
365
|
+
description: "Drive this AntelopeJS implementation module the way an app developer does: install it as `local` in a fixture project, run its backing services in Docker on free ports, call its interfaces from a consumer module and read stored state back with the service's native client. Use to prove a change to the module works before merge, to verify a PR, or to check that a seeded break is caught.",
|
|
366
|
+
title: "Verify module",
|
|
367
|
+
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.",
|
|
368
|
+
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.",
|
|
369
|
+
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.",
|
|
370
|
+
layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
|
|
371
|
+
- \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
|
|
372
|
+
- \`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.
|
|
373
|
+
- \`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.`,
|
|
374
|
+
smoke: "`module-dev` and one write read back through the native client",
|
|
375
|
+
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, which sets status `verify` to `error`."]
|
|
376
|
+
},
|
|
377
|
+
template: {
|
|
378
|
+
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, to run the release canary, or to check that a seeded break is caught.",
|
|
379
|
+
title: "Verify template",
|
|
380
|
+
user: "The user of a template is someone running `ajs project init --template`: they get a copy of the whole repository and expect it to install, pass its checks and run.",
|
|
381
|
+
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.",
|
|
382
|
+
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.
|
|
383
|
+
- \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.`,
|
|
384
|
+
layer: `- \`template.name\`: the listing name users pass to \`--template\`.
|
|
385
|
+
- \`template.project\`: list it under \`projectTemplates\`.
|
|
386
|
+
- \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
|
|
387
|
+
smoke: "`scaffold-dev` and `scaffold-checks`",
|
|
388
|
+
gotchas: ["`ajs` copies the whole repository, `.agents/` and `.claude/` included, so the scaffolded project carries this skill too.", "Every file a user gets is user-facing here, tests included; only `.agents/`, `.claude/` and `.github/` are not."]
|
|
389
|
+
}
|
|
390
|
+
};
|
|
391
|
+
//#endregion
|
|
392
|
+
//#region src/verify/skills.ts
|
|
393
|
+
const BIN = "pnpm exec antelopejs-verify";
|
|
394
|
+
function bullets(lines) {
|
|
395
|
+
return lines.map((line) => `- ${line}`).join("\n");
|
|
396
|
+
}
|
|
397
|
+
/** The synced SKILL.md of a kind, the part of the skill `antelopejs-sync` owns. */
|
|
398
|
+
function skillText(kind) {
|
|
399
|
+
const text = KIND_TEXT[kind];
|
|
400
|
+
const folder = skillFolder(kind);
|
|
401
|
+
return `---
|
|
402
|
+
name: verify-${kind}
|
|
403
|
+
description: ${JSON.stringify(text.description)}
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
# ${text.title}
|
|
407
|
+
|
|
408
|
+
${text.user} Every deterministic step is an \`antelopejs-verify\` command: you choose which journeys to run and judge what they show. Never replace a command with a shell recipe. When a journey you need does not exist, add it to \`verify.config.ts\`, name it in its feature file, then run it.
|
|
409
|
+
|
|
410
|
+
\`antelopejs-sync\` writes this file and \`package.json\` here, and keeps them in sync. Everything else in \`${folder}/\` is the repository's own layer, which sync never touches.
|
|
411
|
+
|
|
412
|
+
## Launch
|
|
413
|
+
|
|
414
|
+
\`\`\`bash
|
|
415
|
+
${BIN} new --base origin/main --title "<PR title>"
|
|
416
|
+
\`\`\`
|
|
417
|
+
|
|
418
|
+
\`new\` prints the run folder; pass it as \`<run>\` below. ${text.launch} Every journey gets its own \`HOME\` and scratch folder, \`CI=1\`, \`AJS_NO_UPDATE_CHECK=1\`, \`NO_COLOR=1\` and a free port from the kernel, so two runs never share an instance. Run it from the repository root after installing dependencies.
|
|
419
|
+
|
|
420
|
+
## Doctor
|
|
421
|
+
|
|
422
|
+
\`\`\`bash
|
|
423
|
+
${BIN} doctor <run>
|
|
424
|
+
\`\`\`
|
|
425
|
+
|
|
426
|
+
Doctor checks that HEAD has not moved since \`new\`, \`ajs\` comes from the repository's \`@antelopejs/core\`, the build is newer than \`src/\`, what \`new\` prepared is there, and no process the run recorded is still alive. Do not drive a run that fails doctor.
|
|
427
|
+
|
|
428
|
+
## Drive
|
|
429
|
+
|
|
430
|
+
\`\`\`bash
|
|
431
|
+
${BIN} plan --base origin/main
|
|
432
|
+
${BIN} journey <run> <feature> [journey...]
|
|
433
|
+
\`\`\`
|
|
434
|
+
|
|
435
|
+
\`plan\` maps the diff to features and lists unmapped surfaces. \`journey\` runs a feature's journeys, or the ones named. The pack ships these journeys for this kind; a feature file names them next to the repository's own:
|
|
436
|
+
|
|
437
|
+
${text.builtins}
|
|
438
|
+
|
|
439
|
+
## Evidence
|
|
440
|
+
|
|
441
|
+
Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`command.txt\`, \`stdout.txt\`, \`stderr.txt\`, \`exit-code.txt\`, \`pid.txt\` for background processes, \`tree.txt\`, \`http.json\` for every request, and \`checks.json\`. \`result.json\` holds a journey's result and \`feature.json\` the merged results of the feature. Read the evidence before you judge a PASS: a check proves only what it asserts.
|
|
442
|
+
|
|
443
|
+
## Cleanup
|
|
444
|
+
|
|
445
|
+
\`\`\`bash
|
|
446
|
+
${BIN} clean <run>
|
|
447
|
+
\`\`\`
|
|
448
|
+
|
|
449
|
+
\`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`. Run it after every run, failed ones included.
|
|
450
|
+
|
|
451
|
+
## The repository's own layer
|
|
452
|
+
|
|
453
|
+
- \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
|
|
454
|
+
- \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, containments, why }\`. \`containments\` names the \`feature/journey\` that contains a Data or Format door.
|
|
455
|
+
- \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports.
|
|
456
|
+
- \`env\`, \`setup\` (commands replacing the build), \`userFacing\` (globs replacing the kind's default) and \`formal\` (formal checks with the files they cover).
|
|
457
|
+
${text.layer}
|
|
458
|
+
- \`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}.
|
|
459
|
+
- \`seeded-breaks/<feature>.patch\`: one minimal product bug per feature that its journeys must catch.
|
|
460
|
+
- \`seeded-doors/<kind>.patch\`: one change per door kind that applies.
|
|
461
|
+
|
|
462
|
+
\`\`\`bash
|
|
463
|
+
${BIN} map
|
|
464
|
+
\`\`\`
|
|
465
|
+
|
|
466
|
+
\`map\` fails on a user-facing file no feature covers, a feature without journeys, docs or seeded break, an unknown journey, an applicable door kind without its seeded door, and a Data or Format door whose \`containments\` name no journey a feature registers.
|
|
467
|
+
|
|
468
|
+
## Verdict rules
|
|
469
|
+
|
|
470
|
+
1. **Run every feature whose \`covers:\` globs the diff touches, plus \`smoke\`.** \`plan\` prints that list as \`run\`.
|
|
471
|
+
2. **An unmapped surface fails the verdict.** A changed user-facing file no feature covers needs a feature entry, its journeys and its seeded break in the same PR.
|
|
472
|
+
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 is not verified, and so is the verdict, never PASS.
|
|
473
|
+
4. **Docs.** Judge every \`docs:\` page of a touched feature against what the journeys showed. A stale page fails the verdict.
|
|
474
|
+
5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff. One that did not run, violates a rule or errors fails the verdict.
|
|
475
|
+
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. A Data or Format row names a \`containments\` journey that passed in this run.
|
|
476
|
+
7. **Result.** FAIL if any rule fails. NOT VERIFIED when a journey could not reach the product. PASS+NOTES when something is not verified or needs the owner's attention. PASS otherwise.
|
|
477
|
+
|
|
478
|
+
Write your judgement to \`<run>/evidence/judgement.json\`:
|
|
479
|
+
|
|
480
|
+
\`\`\`json
|
|
481
|
+
{
|
|
482
|
+
"doors": {
|
|
483
|
+
"none": "why the diff opens no door",
|
|
484
|
+
"rows": [],
|
|
485
|
+
"falsePositives": [{ "kind": "publish", "location": "package.json", "reason": "only devDependencies changed" }]
|
|
486
|
+
},
|
|
487
|
+
"docs": [{ "page": "README.md", "matches": true, "note": "" }],
|
|
488
|
+
"notVerified": ["What no journey reached, and why"],
|
|
489
|
+
"attention": ["What the owner should look at that the journeys cannot judge"],
|
|
490
|
+
"verifier": "the fresh thread that judged this run, not the author"
|
|
491
|
+
}
|
|
492
|
+
\`\`\`
|
|
493
|
+
|
|
494
|
+
A door row is \`{ "kind", "location", "irreversible", "containment", "containmentJourney" }\`. Then render and publish:
|
|
495
|
+
|
|
496
|
+
\`\`\`bash
|
|
497
|
+
${BIN} verdict <run> --pr <n>
|
|
498
|
+
${BIN} publish <run> --pr <n>
|
|
499
|
+
\`\`\`
|
|
500
|
+
|
|
501
|
+
\`verdict\` writes \`evidence/verdict.md\` and exits 1 unless the result is PASS or PASS+NOTES. \`publish\` commits the evidence to the orphan branch \`verify-evidence\` under \`pr-<n>/<sha>/\` from a temporary worktree, posts the verdict as a PR comment, sets commit status \`verify\` on the head SHA (\`success\` for PASS and PASS+NOTES, \`error\` for NOT VERIFIED, \`failure\` for FAIL) and reads it back. It prints the error GitHub answers when the token cannot write statuses. A new push voids the status. Post a verdict only from a thread that did not write the change.
|
|
502
|
+
|
|
503
|
+
## Trust
|
|
504
|
+
|
|
505
|
+
The skill is not Trusted yet. It becomes Trusted when it catches every seeded break and flags every seeded door, 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.
|
|
506
|
+
|
|
507
|
+
## Seeded breaks and doors
|
|
508
|
+
|
|
509
|
+
\`\`\`bash
|
|
510
|
+
${BIN} seeded <feature...>
|
|
511
|
+
${BIN} seeded-doors
|
|
512
|
+
\`\`\`
|
|
513
|
+
|
|
514
|
+
\`seeded\` runs each feature's journeys in a scratch worktree of HEAD without the patch, as the control, and with \`seeded-breaks/<feature>.patch\` applied. It prints \`CAUGHT\` only when a journey that passes in the control fails one of its checks with the patch. Journeys failing in the control and failures without a failing check do not count. \`seeded-doors\` prints \`FLAGGED\` when the path rules flag each patch with its own kind.
|
|
515
|
+
|
|
516
|
+
## Gotchas
|
|
517
|
+
|
|
518
|
+
${bullets(text.gotchas)}
|
|
519
|
+
- Runs live under the system temp folder (\`TMPDIR\`), and the shared caches under \`~/.cache/antelopejs-verify\`.
|
|
520
|
+
- A repository that outgrows this skill runs \`antelopejs-sync --verify custom\` and keeps its own \`.agents/skills/verify-<repo>/\`.
|
|
521
|
+
`;
|
|
522
|
+
}
|
|
523
|
+
/** The skill folder's package.json: it makes verify.config.ts an ES module and keeps the folder out of published packages. */
|
|
524
|
+
const SKILL_PACKAGE = `${JSON.stringify({
|
|
525
|
+
private: true,
|
|
526
|
+
type: "module"
|
|
527
|
+
}, null, 2)}\n`;
|
|
528
|
+
/** Every file of a kind's synced layer, by path relative to the repository root. */
|
|
529
|
+
function syncedFiles(kind) {
|
|
530
|
+
return [{
|
|
531
|
+
path: `${skillFolder(kind)}/SKILL.md`,
|
|
532
|
+
content: skillText(kind)
|
|
533
|
+
}, {
|
|
534
|
+
path: `${skillFolder(kind)}/package.json`,
|
|
535
|
+
content: SKILL_PACKAGE
|
|
536
|
+
}];
|
|
537
|
+
}
|
|
538
|
+
//#endregion
|
|
539
|
+
//#region src/guardrails/verify-skill.ts
|
|
540
|
+
/** Whether `value` is a valid `--verify` argument. */
|
|
541
|
+
function isVerifyChoice(value) {
|
|
542
|
+
return value === "custom" || isVerifyKind(value);
|
|
543
|
+
}
|
|
544
|
+
const SKILL_DIRECTORIES = [
|
|
545
|
+
".agents/skills",
|
|
546
|
+
".claude/skills",
|
|
547
|
+
"skills"
|
|
548
|
+
];
|
|
549
|
+
function skillPath(kind) {
|
|
550
|
+
return `${skillFolder(kind)}/SKILL.md`;
|
|
551
|
+
}
|
|
552
|
+
/** The repository's own verification skill: a folder named like `verif` with a SKILL.md, other than the shared kind folders. */
|
|
553
|
+
function ownVerificationSkill(root) {
|
|
554
|
+
const shared = VERIFY_KINDS.map(skillFolder);
|
|
555
|
+
for (const directory of SKILL_DIRECTORIES) {
|
|
556
|
+
if (!existsSync(join(root, directory))) continue;
|
|
557
|
+
for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
|
|
558
|
+
const folder = `${directory}/${entry.name}`;
|
|
559
|
+
if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && !shared.includes(folder) && existsSync(join(root, folder, "SKILL.md"))) return `${folder}/SKILL.md`;
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
function inferKind(manifest, profile) {
|
|
564
|
+
if (profile === "template") return "template";
|
|
565
|
+
const declared = manifest.antelopeJs;
|
|
566
|
+
if (declared?.kind === "interface" || declared?.kind === "module") return declared.kind;
|
|
567
|
+
if (Array.isArray(declared?.implements) && declared.implements.length > 0) return "module";
|
|
568
|
+
}
|
|
569
|
+
function resolveKind(root, flag, manifest, profile) {
|
|
570
|
+
const errors = [];
|
|
571
|
+
if (flag === "custom" && ownVerificationSkill(root) === void 0) errors.push("--verify custom needs your own verification skill: write it under .agents/skills/verify-<repo>/ first.");
|
|
572
|
+
if (flag !== void 0) return {
|
|
573
|
+
kind: flag,
|
|
574
|
+
errors
|
|
575
|
+
};
|
|
576
|
+
const synced = VERIFY_KINDS.filter((kind) => existsSync(join(root, skillPath(kind))));
|
|
577
|
+
if (synced.length > 1) return {
|
|
578
|
+
kind: void 0,
|
|
579
|
+
errors: [`Several shared verification skills exist: ${synced.map(skillPath).join(", ")}. Keep one: run antelopejs-sync --verify <kind>.`]
|
|
580
|
+
};
|
|
581
|
+
if (synced.length === 1) return {
|
|
582
|
+
kind: synced[0],
|
|
583
|
+
errors
|
|
584
|
+
};
|
|
585
|
+
if (ownVerificationSkill(root) !== void 0) return {
|
|
586
|
+
kind: "custom",
|
|
587
|
+
errors
|
|
588
|
+
};
|
|
589
|
+
return {
|
|
590
|
+
kind: inferKind(manifest, profile),
|
|
591
|
+
errors
|
|
592
|
+
};
|
|
593
|
+
}
|
|
594
|
+
function readIfPresent(root, path) {
|
|
595
|
+
const file = join(root, path);
|
|
596
|
+
return existsSync(file) ? readFileSync(file, "utf8") : void 0;
|
|
597
|
+
}
|
|
598
|
+
function planSharedKind(root, kind) {
|
|
599
|
+
const actions = [];
|
|
600
|
+
const errors = [];
|
|
601
|
+
for (const { path, content } of syncedFiles(kind)) if (lstatSync(join(root, path), { throwIfNoEntry: false })?.isDirectory()) errors.push(`${path} is a folder. Move it away, then rerun antelopejs-sync.`);
|
|
602
|
+
else if (readIfPresent(root, path) !== content) actions.push({
|
|
603
|
+
kind: "write",
|
|
604
|
+
path,
|
|
605
|
+
content
|
|
606
|
+
});
|
|
607
|
+
const link = claudeLink(kind);
|
|
608
|
+
const target = claudeLinkTarget(kind);
|
|
609
|
+
const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
|
|
610
|
+
if (stat === void 0) actions.push({
|
|
611
|
+
kind: "link",
|
|
612
|
+
path: link,
|
|
613
|
+
target
|
|
614
|
+
});
|
|
615
|
+
else if (!stat.isSymbolicLink()) errors.push(`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`);
|
|
616
|
+
else if (readlinkSync(join(root, link)) !== target) actions.push({
|
|
617
|
+
kind: "link",
|
|
618
|
+
path: link,
|
|
619
|
+
target
|
|
620
|
+
});
|
|
621
|
+
return {
|
|
622
|
+
actions,
|
|
623
|
+
errors
|
|
624
|
+
};
|
|
625
|
+
}
|
|
626
|
+
function planStaleKinds(root, keep) {
|
|
627
|
+
const actions = [];
|
|
628
|
+
const notes = [];
|
|
629
|
+
for (const kind of VERIFY_KINDS) {
|
|
630
|
+
if (kind === keep) continue;
|
|
631
|
+
const before = actions.length;
|
|
632
|
+
for (const { path } of syncedFiles(kind)) {
|
|
633
|
+
const synced = lstatSync(join(root, path), { throwIfNoEntry: false });
|
|
634
|
+
if (synced?.isFile() || synced?.isSymbolicLink()) actions.push({
|
|
635
|
+
kind: "remove",
|
|
636
|
+
path
|
|
637
|
+
});
|
|
638
|
+
}
|
|
639
|
+
if (lstatSync(join(root, claudeLink(kind)), { throwIfNoEntry: false })?.isSymbolicLink()) actions.push({
|
|
640
|
+
kind: "remove",
|
|
641
|
+
path: claudeLink(kind)
|
|
642
|
+
});
|
|
643
|
+
if (actions.length === before) continue;
|
|
644
|
+
const folder = skillFolder(kind);
|
|
645
|
+
const kept = existsSync(join(root, folder)) && readdirSync(join(root, folder)).some((name) => !syncedFiles(kind).some(({ path }) => path === `${folder}/${name}`));
|
|
646
|
+
notes.push(`Removed the synced files of verify-${kind}.${kept ? ` Kept its repo-owned files in ${folder}.` : ""}`);
|
|
647
|
+
}
|
|
648
|
+
return {
|
|
649
|
+
actions,
|
|
650
|
+
notes
|
|
651
|
+
};
|
|
652
|
+
}
|
|
653
|
+
/** Resolves the repository's verification kind and plans the synced layer; the repo-owned files are never touched. */
|
|
654
|
+
function planVerify(root, options) {
|
|
655
|
+
const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
|
|
656
|
+
const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
|
|
657
|
+
const wanted = shared ? planSharedKind(root, shared) : {
|
|
658
|
+
actions: [],
|
|
659
|
+
errors: []
|
|
660
|
+
};
|
|
661
|
+
const stale = kind === void 0 ? {
|
|
662
|
+
actions: [],
|
|
663
|
+
notes: []
|
|
664
|
+
} : planStaleKinds(root, shared);
|
|
665
|
+
return {
|
|
666
|
+
kind,
|
|
667
|
+
verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
|
|
668
|
+
actions: [...wanted.actions, ...stale.actions],
|
|
669
|
+
errors: [...errors, ...wanted.errors],
|
|
670
|
+
notes: stale.notes
|
|
671
|
+
};
|
|
672
|
+
}
|
|
673
|
+
/** Applies planned changes; a replaced symlink is unlinked first so a write never goes through it. */
|
|
674
|
+
function applyVerifyActions(root, actions) {
|
|
675
|
+
for (const action of actions) {
|
|
676
|
+
const path = join(root, action.path);
|
|
677
|
+
if (action.kind === "remove") {
|
|
678
|
+
unlinkSync(path);
|
|
679
|
+
continue;
|
|
680
|
+
}
|
|
681
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
682
|
+
if (lstatSync(path, { throwIfNoEntry: false }) !== void 0) unlinkSync(path);
|
|
683
|
+
if (action.kind === "write") writeFileSync(path, action.content);
|
|
684
|
+
else symlinkSync(action.target, path);
|
|
685
|
+
}
|
|
686
|
+
}
|
|
342
687
|
//#endregion
|
|
343
688
|
//#region src/guardrails/sync.ts
|
|
344
689
|
const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
|
|
@@ -491,19 +836,6 @@ function planSync(current, modes, context) {
|
|
|
491
836
|
}
|
|
492
837
|
return plan;
|
|
493
838
|
}
|
|
494
|
-
function verificationSkill(root) {
|
|
495
|
-
for (const directory of [
|
|
496
|
-
".agents/skills",
|
|
497
|
-
".claude/skills",
|
|
498
|
-
"skills"
|
|
499
|
-
]) {
|
|
500
|
-
if (!existsSync(join(root, directory))) continue;
|
|
501
|
-
for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
|
|
502
|
-
const path = `${directory}/${entry.name}/SKILL.md`;
|
|
503
|
-
if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && existsSync(join(root, path))) return path;
|
|
504
|
-
}
|
|
505
|
-
}
|
|
506
|
-
}
|
|
507
839
|
function repositorySnapshot(root) {
|
|
508
840
|
const current = /* @__PURE__ */ new Map();
|
|
509
841
|
const modes = /* @__PURE__ */ new Map();
|
|
@@ -529,7 +861,7 @@ function claudeProse(root, current) {
|
|
|
529
861
|
if (!claude.includes("\n") && /^(?:@?(?:\.\/)?AGENTS\.md|(?:See |Refer to )?\[AGENTS\.md\]\((?:\.\/)?AGENTS\.md\)(?: for .*)?\.?)$/i.test(claude)) return "";
|
|
530
862
|
return claude;
|
|
531
863
|
}
|
|
532
|
-
function repositoryContext(root, current, profile) {
|
|
864
|
+
function repositoryContext(root, current, profile, verificationSkill) {
|
|
533
865
|
const manifest = parseManifest(current.get("package.json") ?? "{}");
|
|
534
866
|
const lint = PRESET_CONFIGS[0];
|
|
535
867
|
const desiredLint = current.get(lint.path) ?? lint.content;
|
|
@@ -546,7 +878,7 @@ function repositoryContext(root, current, profile) {
|
|
|
546
878
|
suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
|
|
547
879
|
packageName: manifest.name ?? "",
|
|
548
880
|
managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
|
|
549
|
-
verificationSkill
|
|
881
|
+
verificationSkill,
|
|
550
882
|
glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
|
|
551
883
|
};
|
|
552
884
|
}
|
|
@@ -570,11 +902,16 @@ function syncRepository(root, options = {}) {
|
|
|
570
902
|
const profile = options.profile ?? "full";
|
|
571
903
|
const { current, modes } = repositorySnapshot(root);
|
|
572
904
|
const manifest = parseManifest(current.get("package.json") ?? "{}");
|
|
573
|
-
const
|
|
905
|
+
const verify = planVerify(root, {
|
|
906
|
+
flag: options.verify,
|
|
907
|
+
manifest,
|
|
908
|
+
profile
|
|
909
|
+
});
|
|
910
|
+
const context = repositoryContext(root, current, profile, verify.verificationSkill);
|
|
574
911
|
let plan = planSync(current, modes, context);
|
|
575
912
|
const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
|
|
576
913
|
const entryOnly = checkEntryOnlyConfiguration(root);
|
|
577
|
-
errors.push(...entryOnly.errors);
|
|
914
|
+
errors.push(...entryOnly.errors, ...verify.errors);
|
|
578
915
|
const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
|
|
579
916
|
(options.check ? errors : notes).push(...repositoryNotices(root, context));
|
|
580
917
|
if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
|
|
@@ -586,15 +923,19 @@ function syncRepository(root, options = {}) {
|
|
|
586
923
|
plan = planSync(current, modes, context);
|
|
587
924
|
}
|
|
588
925
|
const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
|
|
589
|
-
if (!options.check && !errors.length)
|
|
926
|
+
if (!options.check && !errors.length) {
|
|
927
|
+
writeArtifacts(root, writes);
|
|
928
|
+
applyVerifyActions(root, verify.actions);
|
|
929
|
+
}
|
|
590
930
|
const requiredDependencies = ["lefthook", "knip"];
|
|
591
931
|
if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
|
|
592
932
|
const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
|
|
593
933
|
return {
|
|
594
934
|
artifacts: plan,
|
|
595
|
-
paths: errors.length ? [] : writes.map(({ path }) => path),
|
|
935
|
+
paths: errors.length ? [] : [...writes, ...verify.actions].map(({ path }) => path),
|
|
596
936
|
errors,
|
|
597
937
|
notes,
|
|
938
|
+
verifyNotes: verify.notes,
|
|
598
939
|
advisories: entryOnly.advisories,
|
|
599
940
|
dependenciesAdded
|
|
600
941
|
};
|
|
@@ -607,14 +948,18 @@ runCli(() => {
|
|
|
607
948
|
profile: {
|
|
608
949
|
type: "string",
|
|
609
950
|
default: "full"
|
|
610
|
-
}
|
|
951
|
+
},
|
|
952
|
+
verify: { type: "string" }
|
|
611
953
|
} });
|
|
612
954
|
if (values.profile !== "full" && values.profile !== "template") throw new Error("--profile must be full or template.");
|
|
955
|
+
if (values.verify !== void 0 && !isVerifyChoice(values.verify)) throw new Error("--verify must be interface, module, template, or custom.");
|
|
613
956
|
const result = syncRepository(repositoryRoot(), {
|
|
614
957
|
check: values.check,
|
|
615
|
-
profile: values.profile
|
|
958
|
+
profile: values.profile,
|
|
959
|
+
verify: values.verify
|
|
616
960
|
});
|
|
617
961
|
for (const note of result.notes) process.stdout.write(`Note: ${values.check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
|
|
962
|
+
for (const note of result.verifyNotes) process.stdout.write(`Note: ${note}\n`);
|
|
618
963
|
for (const advisory of result.advisories) process.stdout.write(`${advisory}\n`);
|
|
619
964
|
for (const error of result.errors) process.stderr.write(`${error}\n`);
|
|
620
965
|
if (result.errors.length) return 1;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|