@antelopejs/tooling-configs 0.2.14 → 0.2.15

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.
@@ -145,13 +145,24 @@ function sortMembers(compiler, visited, original, source) {
145
145
  keyed.sort((a, b) => compareKeys(a.key, b.key));
146
146
  return compiler.factory.createNodeArray(keyed.map(({ member }) => member));
147
147
  }
148
- /** Rewrites every object type literal, interface and class in `file`, whose nodes were parsed from `source`, so its members appear in a canonical order. Member order does not change a type, so two declaration texts that differ only in it print identically. Tuple elements, parameters, overloads of one name, enum members, union and intersection constituents and statement bodies of namespaces keep the order they were written in. */
148
+ /** Orders the constituents of a union by their printed text. Union order does not change a type, but the checker prints constituents in the order it created them, which varies with the files around the declaration. Intersections keep their order, because the order of intersected function types is the order of their overloads. */
149
+ function sortUnionTypes(compiler, visited, file) {
150
+ const printer = compiler.createPrinter({ removeComments: true });
151
+ const keyed = visited.map((type) => ({
152
+ type,
153
+ text: printer.printNode(compiler.EmitHint.Unspecified, type, file)
154
+ }));
155
+ keyed.sort((a, b) => a.text === b.text ? 0 : a.text < b.text ? -1 : 1);
156
+ return compiler.factory.createNodeArray(keyed.map(({ type }) => type));
157
+ }
158
+ /** Rewrites every object type literal, interface and class in `file`, whose nodes were parsed from `source`, so its members appear in a canonical order. Member order does not change a type, so two declaration texts that differ only in it print identically. Union constituents are ordered by their printed text. Tuple elements, parameters, overloads of one name, enum members, intersection constituents and statement bodies of namespaces keep the order they were written in. */
149
159
  function sortDeclarationMembers(compiler, file, source) {
150
160
  const { factory } = compiler;
151
161
  const result = compiler.transform(file, [(context) => {
152
162
  const visit = (node) => {
153
163
  const visited = compiler.visitEachChild(node, visit, context);
154
164
  if (compiler.isTypeLiteralNode(node) && compiler.isTypeLiteralNode(visited)) return factory.updateTypeLiteralNode(visited, sortMembers(compiler, visited.members, node.members, source));
165
+ if (compiler.isUnionTypeNode(node) && compiler.isUnionTypeNode(visited)) return factory.updateUnionTypeNode(visited, sortUnionTypes(compiler, visited.types, file));
155
166
  if (compiler.isInterfaceDeclaration(node) && compiler.isInterfaceDeclaration(visited)) return factory.updateInterfaceDeclaration(visited, visited.modifiers, visited.name, visited.typeParameters, visited.heritageClauses, sortMembers(compiler, visited.members, node.members, source));
156
167
  if (compiler.isClassDeclaration(node) && compiler.isClassDeclaration(visited)) return factory.updateClassDeclaration(visited, visited.modifiers, visited.name, visited.typeParameters, visited.heritageClauses, sortMembers(compiler, visited.members, node.members, source));
157
168
  return visited;
package/dist/bin/sync.mjs CHANGED
@@ -347,7 +347,7 @@ const KIND_TEXT = {
347
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
348
  title: "Verify interface",
349
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.",
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. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
351
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
352
  - an async proxy answers the stub's echo, and the stub's call log shows the same arguments (the second view);
353
353
  - a registering proxy registers and unregisters, and the stub logs both;
@@ -355,11 +355,16 @@ const KIND_TEXT = {
355
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
356
  A declared function with none of these fails the journey.
357
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\`.
358
+ layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\`.
359
+ - \`interface.provide(api, services)\` runs in the stub provider after the generic stubs attach, for example to hand a client pointed at \`services\` to \`internal.SetClient\`.
359
360
  - \`interface.calls["<entry>:<path>"]\` calls a plain exported function from the consumer and states the value it must return.
360
361
  - \`interface.providerSide["<entry>:<path>"]\` names a function only providers call, with the reason.`,
361
362
  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
+ gotchas: [
364
+ "A function the consumer awaits forever, such as a getter no provider resolved, fails after 15 seconds with a `Timeout` value.",
365
+ "`minor-bump` needs the npm registry. Without it the journey is not verified, never passed.",
366
+ "A containment journey of a Data or Format door must check what that door's seeded patch changes, for example the arguments the stub provider logged. `containments` reports one that still passes with its door as `MISSED`."
367
+ ]
363
368
  },
364
369
  module: {
365
370
  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.",
@@ -369,23 +374,32 @@ const KIND_TEXT = {
369
374
  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
375
  layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
371
376
  - \`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.
377
+ - \`saas: { env, sandbox }\`: a SaaS module runs against the provider's sandbox with keys from these environment variables. Without every key, each journey is NOT VERIFIED and so is the verdict, never PASS or PASS+NOTES.
373
378
  - \`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
379
  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`."]
380
+ gotchas: [
381
+ "Every container is the run's own. Never point a journey at a shared instance such as a developer's local database.",
382
+ "A sandbox key missing from the environment is a NOT VERIFIED verdict, which sets status `verify` to `error`.",
383
+ "A containment journey of a Data or Format door must read back, through the native client, the state that door's seeded patch corrupts. `containments` reports one that still passes with its door as `MISSED`."
384
+ ]
376
385
  },
377
386
  template: {
378
387
  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
388
  title: "Verify template",
380
389
  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.",
390
+ launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. Journeys point `ajs config set git` at it, so no step reaches GitHub. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
382
391
  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
392
  - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.`,
384
393
  layer: `- \`template.name\`: the listing name users pass to \`--template\`.
385
394
  - \`template.project\`: list it under \`projectTemplates\`.
395
+ - \`services\`: image, port, readiness command and \`reset\`, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\` and passes their endpoints to the project it starts through the \`env\` of \`context.dev\`.
386
396
  - \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
387
397
  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."]
398
+ gotchas: [
399
+ "`ajs` copies the whole repository, `.agents/` and `.claude/` included, so the scaffolded project carries this skill too.",
400
+ "Every file a user gets is user-facing here, tests included; only `.agents/`, `.claude/` and `.github/` are not.",
401
+ "A containment journey of a Data or Format door must check the scaffolded files or endpoint that door's seeded patch changes. `containments` reports one that still passes with its door as `MISSED`."
402
+ ]
389
403
  }
390
404
  };
391
405
  //#endregion
@@ -451,34 +465,34 @@ ${BIN} clean <run>
451
465
  ## The repository's own layer
452
466
 
453
467
  - \`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.
468
+ - \`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\` journeys that contain a Data or Format door. Each must fail with that kind's seeded door applied and pass without it: write the journey so one of its checks reads the state the door corrupts.
455
469
  - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports.
456
470
  - \`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
471
  ${text.layer}
458
472
  - \`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
473
  - \`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.
474
+ - \`seeded-doors/<kind>.patch\`: one change per door kind that applies. A Data or Format door's patch must break what its containment journeys check.
461
475
 
462
476
  \`\`\`bash
463
477
  ${BIN} map
464
478
  \`\`\`
465
479
 
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.
480
+ \`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. \`containments\` (below) then runs those journeys against the seeded doors.
467
481
 
468
482
  ## Verdict rules
469
483
 
470
484
  1. **Run every feature whose \`covers:\` globs the diff touches, plus \`smoke\`.** \`plan\` prints that list as \`run\`.
471
485
  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.
486
+ 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, whatever else passed: never PASS and never PASS+NOTES.
473
487
  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:
488
+ 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, 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; a function declaration refers to the top-level variables and classes of its own file by file and name, so moving it next to a different variable of the same name counts as changed. Exports are keyed by the origin they export, so a re-export or an \`export { f as run }\` retargeted to another binding counts as changed. Each file must keep its top-level statements and its side-effect imports 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
489
  - 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
490
  - recorded findings fail the verdict only when the covered behaviour changed; when it did not, the verdict reports them as known findings;
477
491
  - 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
492
 
479
493
  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.
494
+ 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, and that journey is proven by \`${BIN} containments\`: it fails with the kind's seeded door applied. A containment that passes with its door contains nothing, so a Data or Format door without one that fails with its door is not contained.
495
+ 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.
482
496
 
483
497
  Write your judgement to \`<run>/evidence/judgement.json\`:
484
498
 
@@ -507,16 +521,17 @@ ${BIN} publish <run> --pr <n>
507
521
 
508
522
  ## Trust
509
523
 
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.
524
+ The skill is not Trusted yet. It becomes Trusted when it catches every seeded break, flags every seeded door, fails every Data and Format containment with its 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
525
 
512
526
  ## Seeded breaks and doors
513
527
 
514
528
  \`\`\`bash
515
529
  ${BIN} seeded <feature...>
516
530
  ${BIN} seeded-doors
531
+ ${BIN} containments
517
532
  \`\`\`
518
533
 
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.
534
+ \`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. \`containments\` runs every Data and Format containment journey in a scratch worktree of HEAD without the door, as the control, and with \`seeded-doors/<kind>.patch\` applied. It prints \`CONTAINED\` only when the journey passes in the control and fails one of its checks with the door. \`MISSED\` means it passes with its door, \`UNPROVEN\` that it fails in the control or ends without a failing check, and \`NO-DOOR\` that the kind has no seeded door; the command exits 1 on anything but \`CONTAINED\`.
520
535
 
521
536
  ## Gotchas
522
537