@antelopejs/tooling-configs 0.2.11 → 0.2.13
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 +8 -0
- package/dist/bin/garden.mjs +13 -71
- package/dist/bin/suppressions.mjs +32 -20
- package/dist/bin/sync.mjs +373 -23
- package/dist/bin/verify.d.mts +1 -0
- package/dist/bin/verify.mjs +3487 -0
- package/dist/checks-BlWDFYio.mjs +94 -0
- package/dist/json-BqvuCkqr.mjs +67 -0
- package/dist/kinds-Bzyyi9yk.mjs +25 -0
- package/dist/verify/index.d.mts +284 -0
- package/dist/verify/index.mjs +2 -0
- package/package.json +5 -3
package/dist/bin/sync.mjs
CHANGED
|
@@ -6,7 +6,8 @@ import { a as repositoryTools, i as parseManifest, n as managedPackage, o as too
|
|
|
6
6
|
import { t as measureBaseline } from "../ratchet-DRdIYwmv.mjs";
|
|
7
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, rmdirSync, 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";
|
|
@@ -340,6 +341,354 @@ function checkEntryOnlyConfiguration(root) {
|
|
|
340
341
|
advisories
|
|
341
342
|
};
|
|
342
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: \`name\`, \`covers\`, \`command\`, \`violation\`, and optionally \`behaviour\` and \`baseCommand\`).
|
|
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 and records it under \`evidence/formal/<name>/\`. For each one it decides, without judgement, whether the diff changed what the covered code does. \`emit\` (the default) compares the structure of the covered files' JavaScript on the base and on HEAD: node kinds, names and literal values, leaving out types, comments, formatting, parentheses and \`export\` keywords. Each use of an imported binding stands for its origin (the resolved module and the imported name), so an import retargeted to another module or alias counts as changed; side-effect imports are compared by resolved module, and re-exports of uncovered modules by origin and exported name. Each file must keep its top-level statements in order; function declarations, which are hoisted, may move between covered files with their imports. So a type-only edit, a reformat or a moved function declaration counts as unchanged, while reordering statements or moving any other statement counts as changed. \`emit\` judges behaviour, not the public surface: exports are the api-diff's job. \`probe\` runs the check's \`behaviour.command\` with a worktree of each commit and compares what it prints. Then:
|
|
475
|
+
- 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;
|
|
476
|
+
- recorded findings fail the verdict only when the covered behaviour changed; when it did not, the verdict reports them as known findings;
|
|
477
|
+
- 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.
|
|
478
|
+
|
|
479
|
+
The decision never reads the check's output, so a model whose rule names stay the same still fails on a changed behaviour. 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.
|
|
480
|
+
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.
|
|
481
|
+
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.
|
|
482
|
+
|
|
483
|
+
Write your judgement to \`<run>/evidence/judgement.json\`:
|
|
484
|
+
|
|
485
|
+
\`\`\`json
|
|
486
|
+
{
|
|
487
|
+
"doors": {
|
|
488
|
+
"none": "why the diff opens no door",
|
|
489
|
+
"rows": [],
|
|
490
|
+
"falsePositives": [{ "kind": "publish", "location": "package.json", "reason": "only devDependencies changed" }]
|
|
491
|
+
},
|
|
492
|
+
"docs": [{ "page": "README.md", "matches": true, "note": "" }],
|
|
493
|
+
"notVerified": ["What no journey reached, and why"],
|
|
494
|
+
"attention": ["What the owner should look at that the journeys cannot judge"],
|
|
495
|
+
"verifier": "the fresh thread that judged this run, not the author"
|
|
496
|
+
}
|
|
497
|
+
\`\`\`
|
|
498
|
+
|
|
499
|
+
A door row is \`{ "kind", "location", "irreversible", "containment", "containmentJourney" }\`. Then render and publish:
|
|
500
|
+
|
|
501
|
+
\`\`\`bash
|
|
502
|
+
${BIN} verdict <run> --pr <n>
|
|
503
|
+
${BIN} publish <run> --pr <n>
|
|
504
|
+
\`\`\`
|
|
505
|
+
|
|
506
|
+
\`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.
|
|
507
|
+
|
|
508
|
+
## Trust
|
|
509
|
+
|
|
510
|
+
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.
|
|
511
|
+
|
|
512
|
+
## Seeded breaks and doors
|
|
513
|
+
|
|
514
|
+
\`\`\`bash
|
|
515
|
+
${BIN} seeded <feature...>
|
|
516
|
+
${BIN} seeded-doors
|
|
517
|
+
\`\`\`
|
|
518
|
+
|
|
519
|
+
\`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.
|
|
520
|
+
|
|
521
|
+
## Gotchas
|
|
522
|
+
|
|
523
|
+
${bullets(text.gotchas)}
|
|
524
|
+
- Runs live under the system temp folder (\`TMPDIR\`), and the shared caches under \`~/.cache/antelopejs-verify\`.
|
|
525
|
+
- A repository that outgrows this skill runs \`antelopejs-sync --verify custom\` and keeps its own \`.agents/skills/verify-<repo>/\`.
|
|
526
|
+
`;
|
|
527
|
+
}
|
|
528
|
+
/** The skill folder's package.json: it makes verify.config.ts an ES module and keeps the folder out of published packages. */
|
|
529
|
+
const SKILL_PACKAGE = `${JSON.stringify({
|
|
530
|
+
private: true,
|
|
531
|
+
type: "module"
|
|
532
|
+
}, null, 2)}\n`;
|
|
533
|
+
/** Every file of a kind's synced layer, by path relative to the repository root. */
|
|
534
|
+
function syncedFiles(kind) {
|
|
535
|
+
return [{
|
|
536
|
+
path: `${skillFolder(kind)}/SKILL.md`,
|
|
537
|
+
content: skillText(kind)
|
|
538
|
+
}, {
|
|
539
|
+
path: `${skillFolder(kind)}/package.json`,
|
|
540
|
+
content: SKILL_PACKAGE
|
|
541
|
+
}];
|
|
542
|
+
}
|
|
543
|
+
//#endregion
|
|
544
|
+
//#region src/guardrails/verify-skill.ts
|
|
545
|
+
/** Whether `value` is a valid `--verify` argument. */
|
|
546
|
+
function isVerifyChoice(value) {
|
|
547
|
+
return value === "custom" || isVerifyKind(value);
|
|
548
|
+
}
|
|
549
|
+
const SKILL_DIRECTORIES = [
|
|
550
|
+
".agents/skills",
|
|
551
|
+
".claude/skills",
|
|
552
|
+
"skills"
|
|
553
|
+
];
|
|
554
|
+
function skillPath(kind) {
|
|
555
|
+
return `${skillFolder(kind)}/SKILL.md`;
|
|
556
|
+
}
|
|
557
|
+
/** The repository's own verification skill: a folder named like `verif` with a SKILL.md, other than the shared kind folders. */
|
|
558
|
+
function ownVerificationSkill(root) {
|
|
559
|
+
const shared = VERIFY_KINDS.map(skillFolder);
|
|
560
|
+
for (const directory of SKILL_DIRECTORIES) {
|
|
561
|
+
if (!existsSync(join(root, directory))) continue;
|
|
562
|
+
for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
|
|
563
|
+
const folder = `${directory}/${entry.name}`;
|
|
564
|
+
if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && !shared.includes(folder) && existsSync(join(root, folder, "SKILL.md"))) return `${folder}/SKILL.md`;
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
function inferKind(manifest, profile) {
|
|
569
|
+
if (profile === "template") return "template";
|
|
570
|
+
const declared = manifest.antelopeJs;
|
|
571
|
+
if (declared?.kind === "interface" || declared?.kind === "module") return declared.kind;
|
|
572
|
+
if (Array.isArray(declared?.implements) && declared.implements.length > 0) return "module";
|
|
573
|
+
}
|
|
574
|
+
function resolveKind(root, flag, manifest, profile) {
|
|
575
|
+
const errors = [];
|
|
576
|
+
if (flag === "custom" && ownVerificationSkill(root) === void 0) errors.push("--verify custom needs your own verification skill: write it under .agents/skills/verify-<repo>/ first.");
|
|
577
|
+
if (flag !== void 0) return {
|
|
578
|
+
kind: flag,
|
|
579
|
+
errors
|
|
580
|
+
};
|
|
581
|
+
const synced = VERIFY_KINDS.filter((kind) => existsSync(join(root, skillPath(kind))));
|
|
582
|
+
if (synced.length > 1) return {
|
|
583
|
+
kind: void 0,
|
|
584
|
+
errors: [`Several shared verification skills exist: ${synced.map(skillPath).join(", ")}. Keep one: run antelopejs-sync --verify <kind>.`]
|
|
585
|
+
};
|
|
586
|
+
if (synced.length === 1) return {
|
|
587
|
+
kind: synced[0],
|
|
588
|
+
errors
|
|
589
|
+
};
|
|
590
|
+
if (ownVerificationSkill(root) !== void 0) return {
|
|
591
|
+
kind: "custom",
|
|
592
|
+
errors
|
|
593
|
+
};
|
|
594
|
+
return {
|
|
595
|
+
kind: inferKind(manifest, profile),
|
|
596
|
+
errors
|
|
597
|
+
};
|
|
598
|
+
}
|
|
599
|
+
function readIfPresent(root, path) {
|
|
600
|
+
const file = join(root, path);
|
|
601
|
+
return existsSync(file) ? readFileSync(file, "utf8") : void 0;
|
|
602
|
+
}
|
|
603
|
+
function planSharedKind(root, kind) {
|
|
604
|
+
const actions = [];
|
|
605
|
+
const errors = [];
|
|
606
|
+
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.`);
|
|
607
|
+
else if (readIfPresent(root, path) !== content) actions.push({
|
|
608
|
+
kind: "write",
|
|
609
|
+
path,
|
|
610
|
+
content
|
|
611
|
+
});
|
|
612
|
+
const link = claudeLink(kind);
|
|
613
|
+
const target = claudeLinkTarget(kind);
|
|
614
|
+
const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
|
|
615
|
+
if (stat === void 0) actions.push({
|
|
616
|
+
kind: "link",
|
|
617
|
+
path: link,
|
|
618
|
+
target
|
|
619
|
+
});
|
|
620
|
+
else if (!stat.isSymbolicLink()) errors.push(`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`);
|
|
621
|
+
else if (readlinkSync(join(root, link)) !== target) actions.push({
|
|
622
|
+
kind: "link",
|
|
623
|
+
path: link,
|
|
624
|
+
target
|
|
625
|
+
});
|
|
626
|
+
return {
|
|
627
|
+
actions,
|
|
628
|
+
errors
|
|
629
|
+
};
|
|
630
|
+
}
|
|
631
|
+
function planStaleKinds(root, keep) {
|
|
632
|
+
const actions = [];
|
|
633
|
+
const notes = [];
|
|
634
|
+
for (const kind of VERIFY_KINDS) {
|
|
635
|
+
if (kind === keep) continue;
|
|
636
|
+
const before = actions.length;
|
|
637
|
+
for (const { path } of syncedFiles(kind)) {
|
|
638
|
+
const synced = lstatSync(join(root, path), { throwIfNoEntry: false });
|
|
639
|
+
if (synced?.isFile() || synced?.isSymbolicLink()) actions.push({
|
|
640
|
+
kind: "remove",
|
|
641
|
+
path
|
|
642
|
+
});
|
|
643
|
+
}
|
|
644
|
+
if (lstatSync(join(root, claudeLink(kind)), { throwIfNoEntry: false })?.isSymbolicLink()) actions.push({
|
|
645
|
+
kind: "remove",
|
|
646
|
+
path: claudeLink(kind)
|
|
647
|
+
});
|
|
648
|
+
if (actions.length === before) continue;
|
|
649
|
+
const folder = skillFolder(kind);
|
|
650
|
+
if (existsSync(join(root, folder)) && readdirSync(join(root, folder)).some((name) => !syncedFiles(kind).some(({ path }) => path === `${folder}/${name}`))) notes.push(`Removed the synced files of verify-${kind} and kept its repo-owned files in ${folder}.`);
|
|
651
|
+
}
|
|
652
|
+
return {
|
|
653
|
+
actions,
|
|
654
|
+
notes
|
|
655
|
+
};
|
|
656
|
+
}
|
|
657
|
+
/** Resolves the repository's verification kind and plans the synced layer; the repo-owned files are never touched. */
|
|
658
|
+
function planVerify(root, options) {
|
|
659
|
+
const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
|
|
660
|
+
const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
|
|
661
|
+
const wanted = shared ? planSharedKind(root, shared) : {
|
|
662
|
+
actions: [],
|
|
663
|
+
errors: []
|
|
664
|
+
};
|
|
665
|
+
const stale = kind === void 0 ? {
|
|
666
|
+
actions: [],
|
|
667
|
+
notes: []
|
|
668
|
+
} : planStaleKinds(root, shared);
|
|
669
|
+
return {
|
|
670
|
+
kind,
|
|
671
|
+
verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
|
|
672
|
+
actions: [...wanted.actions, ...stale.actions],
|
|
673
|
+
errors: [...errors, ...wanted.errors],
|
|
674
|
+
notes: stale.notes
|
|
675
|
+
};
|
|
676
|
+
}
|
|
677
|
+
/** Applies planned changes; a replaced symlink is unlinked first so a write never goes through it. */
|
|
678
|
+
function applyVerifyActions(root, actions) {
|
|
679
|
+
for (const action of actions) {
|
|
680
|
+
const path = join(root, action.path);
|
|
681
|
+
if (action.kind === "remove") {
|
|
682
|
+
unlinkSync(path);
|
|
683
|
+
if (readdirSync(dirname(path)).length === 0) rmdirSync(dirname(path));
|
|
684
|
+
continue;
|
|
685
|
+
}
|
|
686
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
687
|
+
if (lstatSync(path, { throwIfNoEntry: false }) !== void 0) unlinkSync(path);
|
|
688
|
+
if (action.kind === "write") writeFileSync(path, action.content);
|
|
689
|
+
else symlinkSync(action.target, path);
|
|
690
|
+
}
|
|
691
|
+
}
|
|
343
692
|
//#endregion
|
|
344
693
|
//#region src/guardrails/sync.ts
|
|
345
694
|
const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
|
|
@@ -492,19 +841,6 @@ function planSync(current, modes, context) {
|
|
|
492
841
|
}
|
|
493
842
|
return plan;
|
|
494
843
|
}
|
|
495
|
-
function verificationSkill(root) {
|
|
496
|
-
for (const directory of [
|
|
497
|
-
".agents/skills",
|
|
498
|
-
".claude/skills",
|
|
499
|
-
"skills"
|
|
500
|
-
]) {
|
|
501
|
-
if (!existsSync(join(root, directory))) continue;
|
|
502
|
-
for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
|
|
503
|
-
const path = `${directory}/${entry.name}/SKILL.md`;
|
|
504
|
-
if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && existsSync(join(root, path))) return path;
|
|
505
|
-
}
|
|
506
|
-
}
|
|
507
|
-
}
|
|
508
844
|
function repositorySnapshot(root) {
|
|
509
845
|
const current = /* @__PURE__ */ new Map();
|
|
510
846
|
const modes = /* @__PURE__ */ new Map();
|
|
@@ -530,7 +866,7 @@ function claudeProse(root, current) {
|
|
|
530
866
|
if (!claude.includes("\n") && /^(?:@?(?:\.\/)?AGENTS\.md|(?:See |Refer to )?\[AGENTS\.md\]\((?:\.\/)?AGENTS\.md\)(?: for .*)?\.?)$/i.test(claude)) return "";
|
|
531
867
|
return claude;
|
|
532
868
|
}
|
|
533
|
-
function repositoryContext(root, current, profile) {
|
|
869
|
+
function repositoryContext(root, current, profile, verificationSkill) {
|
|
534
870
|
const manifest = parseManifest(current.get("package.json") ?? "{}");
|
|
535
871
|
const lint = PRESET_CONFIGS[0];
|
|
536
872
|
const desiredLint = current.get(lint.path) ?? lint.content;
|
|
@@ -547,7 +883,7 @@ function repositoryContext(root, current, profile) {
|
|
|
547
883
|
suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
|
|
548
884
|
packageName: manifest.name ?? "",
|
|
549
885
|
managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
|
|
550
|
-
verificationSkill
|
|
886
|
+
verificationSkill,
|
|
551
887
|
glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
|
|
552
888
|
};
|
|
553
889
|
}
|
|
@@ -571,11 +907,16 @@ function syncRepository(root, options = {}) {
|
|
|
571
907
|
const profile = options.profile ?? "full";
|
|
572
908
|
const { current, modes } = repositorySnapshot(root);
|
|
573
909
|
const manifest = parseManifest(current.get("package.json") ?? "{}");
|
|
574
|
-
const
|
|
910
|
+
const verify = planVerify(root, {
|
|
911
|
+
flag: options.verify,
|
|
912
|
+
manifest,
|
|
913
|
+
profile
|
|
914
|
+
});
|
|
915
|
+
const context = repositoryContext(root, current, profile, verify.verificationSkill);
|
|
575
916
|
let plan = planSync(current, modes, context);
|
|
576
917
|
const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
|
|
577
918
|
const entryOnly = checkEntryOnlyConfiguration(root);
|
|
578
|
-
errors.push(...entryOnly.errors);
|
|
919
|
+
errors.push(...entryOnly.errors, ...verify.errors);
|
|
579
920
|
const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
|
|
580
921
|
(options.check ? errors : notes).push(...repositoryNotices(root, context));
|
|
581
922
|
if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
|
|
@@ -587,15 +928,20 @@ function syncRepository(root, options = {}) {
|
|
|
587
928
|
plan = planSync(current, modes, context);
|
|
588
929
|
}
|
|
589
930
|
const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
|
|
590
|
-
if (!options.check && !errors.length)
|
|
931
|
+
if (!options.check && !errors.length) {
|
|
932
|
+
writeArtifacts(root, writes);
|
|
933
|
+
applyVerifyActions(root, verify.actions);
|
|
934
|
+
}
|
|
591
935
|
const requiredDependencies = ["lefthook", "knip"];
|
|
592
936
|
if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
|
|
593
937
|
const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
|
|
594
938
|
return {
|
|
595
939
|
artifacts: plan,
|
|
596
|
-
paths: errors.length ? [] : writes.map(({ path }) => path),
|
|
940
|
+
paths: errors.length ? [] : [...writes, ...verify.actions].map(({ path }) => path),
|
|
941
|
+
removed: verify.actions.filter((action) => action.kind === "remove").map(({ path }) => path),
|
|
597
942
|
errors,
|
|
598
943
|
notes,
|
|
944
|
+
verifyNotes: options.check || errors.length ? [] : verify.notes,
|
|
599
945
|
advisories: entryOnly.advisories,
|
|
600
946
|
dependenciesAdded
|
|
601
947
|
};
|
|
@@ -608,18 +954,22 @@ runCli(() => {
|
|
|
608
954
|
profile: {
|
|
609
955
|
type: "string",
|
|
610
956
|
default: "full"
|
|
611
|
-
}
|
|
957
|
+
},
|
|
958
|
+
verify: { type: "string" }
|
|
612
959
|
} });
|
|
613
960
|
if (values.profile !== "full" && values.profile !== "template") throw new Error("--profile must be full or template.");
|
|
961
|
+
if (values.verify !== void 0 && !isVerifyChoice(values.verify)) throw new Error("--verify must be interface, module, template, or custom.");
|
|
614
962
|
const result = syncRepository(repositoryRoot(), {
|
|
615
963
|
check: values.check,
|
|
616
|
-
profile: values.profile
|
|
964
|
+
profile: values.profile,
|
|
965
|
+
verify: values.verify
|
|
617
966
|
});
|
|
618
967
|
for (const note of result.notes) process.stdout.write(`Note: ${values.check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
|
|
968
|
+
for (const note of result.verifyNotes) process.stdout.write(`Note: ${note}\n`);
|
|
619
969
|
for (const advisory of result.advisories) process.stdout.write(`${advisory}\n`);
|
|
620
970
|
for (const error of result.errors) process.stderr.write(`${error}\n`);
|
|
621
971
|
if (result.errors.length) return 1;
|
|
622
|
-
for (const path of result.paths) process.stdout.write(
|
|
972
|
+
for (const path of result.paths) process.stdout.write(values.check ? `Drift: ${path}; run antelopejs-sync\n` : `${result.removed.includes(path) ? "Removed" : "Updated"}: ${path}\n`);
|
|
623
973
|
if (!result.paths.length) process.stdout.write("Guardrails are in sync.\n");
|
|
624
974
|
if (!values.check && result.dependenciesAdded) process.stdout.write("Added devDependencies. Run install with your package manager before using the hooks or checks.\n");
|
|
625
975
|
return values.check && result.paths.length ? 1 : 0;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|