@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/chant-migrations.js

@@ -0,0 +1,113 @@
+/**
+ * Migrations chant ships (#2737).
+ *
+ * A template's own migrations (./lineage-migrations.ts) move a scope between
+ * two versions of that template. Some moves are chant's instead: a part a
+ * template used goes away, and chant knows where each piece of it went. The
+ * first is `chud-lexicon-exit`, which takes a repo made from chud's template
+ * (or the studio kit's copy of it) off `@intentius/chant-lexicon-chud` and
+ * `@intentius/chud-runtime` (ws-056).
+ *
+ * `chant workspace upgrade` asks each one for a plan after the template's own
+ * chain has run in the staging worktree, and before the per-file merge. A
+ * migration plans from what the scope holds, not from a version range, so it
+ * works whatever ref the scope is pinned at. Its plan lists every file it
+ * writes or deletes and why, what it cannot move and where that went, and any
+ * conflict. A plan with a conflict is not applied at all, and the upgrade's
+ * checks fail with it, so the dry run shows the whole plan and the tree is
+ * never left half moved.
+ *
+ * An applied migration's id is added to the lineage's `migrations`, so the
+ * lock records it and a second upgrade does not plan it again. A migration's
+ * plan is also empty once nothing it moves is left, so running it twice
+ * changes nothing either way.
+ *
+ * Files the migration rewrites keep their lineage entry: the lock's hash is
+ * still the template's, so to a later upgrade they are the project's own
+ * edits, merged per file like any other (ws-005). A deleted file keeps its
+ * entry too, so a template version that still has it leaves it deleted.
+ *
+ * chant itself carries no chud lexicon or chud-shaped code (#2830, once
+ * #2715's proof passed): `chud-lexicon-exit` and its follow-ons are the
+ * retirement tool, not a remaining dependency. They stay until no known repo
+ * still depends on chud, and are removed only in a major version.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { chudLexiconExit } from "./chant-migrations/chud-lexicon-exit.js";
+import { chudLexiconExitRollback } from "./chant-migrations/chud-lexicon-exit-rollback.js";
+import { chudLexiconExitShipInputs } from "./chant-migrations/chud-lexicon-exit-ship-inputs.js";
+import { chudLexiconExitShipPolicy } from "./chant-migrations/chud-lexicon-exit-ship-policy.js";
+import { chudLexiconExitFlySite } from "./chant-migrations/chud-lexicon-exit-fly-site.js";
+import { chudLexiconExitLiveNames } from "./chant-migrations/chud-lexicon-exit-live-names.js";
+/** Every migration chant ships, in the order they are planned. */
+export const CHANT_MIGRATIONS = [
+    chudLexiconExit,
+    chudLexiconExitRollback,
+    chudLexiconExitShipInputs,
+    chudLexiconExitShipPolicy,
+    chudLexiconExitFlySite,
+    chudLexiconExitLiveNames,
+];
+/** The plans for a scope: each migration not yet in the lineage that finds something to move. */
+export function planChantMigrations(ctx, migrations = CHANT_MIGRATIONS) {
+    const applied = new Set(ctx.lineage.migrations);
+    const plans = [];
+    for (const m of migrations) {
+        if (applied.has(m.id))
+            continue;
+        const plan = m.plan(ctx);
+        if (plan && (plan.changes.length > 0 || plan.conflicts.length > 0))
+            plans.push(plan);
+    }
+    return plans;
+}
+/**
+ * Plan each migration in order and apply each plan with no conflict before
+ * the next is planned, so a migration planned after another sees the tree
+ * the earlier one left (#2800: `chud-lexicon-exit-rollback` after
+ * `chud-lexicon-exit`). A plan with a conflict is not applied, and the ones
+ * after it plan from the tree as it is.
+ */
+export function runChantMigrations(ctx, migrations = CHANT_MIGRATIONS) {
+    const out = [];
+    for (const m of migrations) {
+        if (ctx.lineage.migrations.includes(m.id))
+            continue;
+        const plan = m.plan(ctx);
+        if (!plan || (plan.changes.length === 0 && plan.conflicts.length === 0))
+            continue;
+        const applied = plan.conflicts.length === 0;
+        if (applied)
+            applyChantMigration(plan, ctx.dir, ctx.lineage);
+        out.push({ plan, applied });
+    }
+    return out;
+}
+/** Apply a plan with no conflicts, and record its id in the lineage. */
+export function applyChantMigration(plan, dir, lineage) {
+    if (plan.conflicts.length > 0)
+        throw new Error(`${plan.id} has conflicts and cannot be applied`);
+    for (const c of plan.changes) {
+        const abs = join(dir, c.path);
+        if (c.action === "delete") {
+            rmSync(abs, { force: true });
+        }
+        else {
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, c.data);
+        }
+    }
+    if (!lineage.migrations.includes(plan.id))
+        lineage.migrations.push(plan.id);
+}
+export function reportPlan(plan, applied) {
+    return {
+        id: plan.id,
+        description: plan.description,
+        applied,
+        changes: plan.changes.map(({ data: _d, ...rest }) => rest),
+        notMoved: plan.notMoved,
+        conflicts: plan.conflicts,
+    };
+}

package/dist/workspace/check.schema.json

@@ -0,0 +1,433 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json",
+  "title": "chant workspace check output",
+  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, WSP001, a declaration that can't be read, also carries the declaration's reason code, and the box checks WSP121 to WSP127 carry theirs. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The checks ran. Exit code 0 when ok is true, 1 otherwise.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "workspace",
+        "ok",
+        "lock",
+        "findings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The version of the chant that ran the checks."
+        },
+        "at": {
+          "description": "The full commit id the checks read (--at), or null for the working tree.",
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "workspace": {
+          "description": "The workspace whose declaration was checked, or null when no declaration sits between the directory and the git root.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name",
+                "root"
+              ],
+              "properties": {
+                "name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The declared name, or null when the declaration can't be read."
+                },
+                "root": {
+                  "type": "string",
+                  "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
+                }
+              }
+            }
+          ]
+        },
+        "ok": {
+          "type": "boolean",
+          "description": "No lock finding, and no declaration finding of error severity."
+        },
+        "lock": {
+          "description": "The lineage lock's path, or null when the directory has none.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "const": ".chant/workspace.lock.json"
+            }
+          ]
+        },
+        "findings": {
+          "description": "The lineage lock findings.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/lockFinding"
+          }
+        },
+        "declaration": {
+          "$ref": "#/$defs/declaration"
+        }
+      }
+    },
+    "lockFinding": {
+      "type": "object",
+      "required": [
+        "code",
+        "scope",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "lock-invalid",
+            "manual-step-open"
+          ]
+        },
+        "scope": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The lock scope, or null for the lock as a whole."
+        },
+        "path": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "declaration": {
+      "description": "Present when a declaration sits between the directory and the git root.",
+      "type": "object",
+      "required": [
+        "file",
+        "diagnostics",
+        "suppressed",
+        "ok"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "The declaration, relative to the directory the command ran in."
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "live": {
+          "description": "Present with --live --env (#2549, ws-062): the declared output links resolved against the live graph of the environment. Each member of kind chant ran chant graph --live. Added by chant 0.101.0.",
+          "type": "object",
+          "required": [
+            "env",
+            "links"
+          ],
+          "properties": {
+            "env": {
+              "type": "string"
+            },
+            "links": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "consumer",
+                  "producer",
+                  "output",
+                  "resolves",
+                  "status",
+                  "reason"
+                ],
+                "properties": {
+                  "consumer": {
+                    "type": "string"
+                  },
+                  "producer": {
+                    "type": "string"
+                  },
+                  "output": {
+                    "type": "string"
+                  },
+                  "kind": {
+                    "type": "string"
+                  },
+                  "origin": {
+                    "const": "declared"
+                  },
+                  "resolves": {
+                    "const": "live"
+                  },
+                  "status": {
+                    "enum": [
+                      "resolved",
+                      "missing",
+                      "unresolved",
+                      "invalid"
+                    ]
+                  },
+                  "reason": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "pointer": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "diagnostics": {
+          "description": "Active findings, in the shape `chant lint --format json` prints, sorted by position.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/diagnostic"
+          }
+        },
+        "suppressed": {
+          "description": "Findings an entry's suppress turned off, with its reason. They never fail the command.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/suppressed"
+          }
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": [
+        "file",
+        "line",
+        "column",
+        "ruleId",
+        "severity",
+        "message"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Relative to the directory the command ran in."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endColumn": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ruleId": {
+          "type": "string",
+          "pattern": "^WSP[0-9]{3}$",
+          "description": "The declaration check's id, from the catalog on the workspace check page."
+        },
+        "severity": {
+          "enum": [
+            "error",
+            "warning",
+            "info"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "entity": {
+          "type": "string",
+          "description": "The member or group the finding is about. For a box check, the box member."
+        },
+        "code": {
+          "enum": [
+            "declaration-missing",
+            "declaration-ambiguous",
+            "declaration-unparseable",
+            "declaration-invalid",
+            "placement-invalid",
+            "reader-too-old",
+            "root-chant-required",
+            "not-a-git-repository",
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "box-isolation-literal",
+            "box-fountain-callback-undeclared",
+            "box-intent-unknown",
+            "box-intent-unconstrained",
+            "work-acceptance-unmet",
+            "diagram-source-missing",
+            "diagram-render-missing",
+            "diagram-render-drift"
+          ],
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
+        }
+      }
+    },
+    "suppressed": {
+      "type": "object",
+      "required": [
+        "file",
+        "line",
+        "column",
+        "ruleId",
+        "severity",
+        "message",
+        "reason"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Relative to the directory the command ran in."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endColumn": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ruleId": {
+          "type": "string",
+          "pattern": "^WSP[0-9]{3}$",
+          "description": "The declaration check's id, from the catalog on the workspace check page."
+        },
+        "severity": {
+          "enum": [
+            "error",
+            "warning",
+            "info"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "entity": {
+          "type": "string",
+          "description": "The member or group the finding is about. For a box check, the box member."
+        },
+        "code": {
+          "enum": [
+            "declaration-missing",
+            "declaration-ambiguous",
+            "declaration-unparseable",
+            "declaration-invalid",
+            "placement-invalid",
+            "reader-too-old",
+            "root-chant-required",
+            "not-a-git-repository",
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "box-isolation-literal",
+            "box-fountain-callback-undeclared",
+            "box-intent-unknown",
+            "box-intent-unconstrained",
+            "work-acceptance-unmet",
+            "diagram-source-missing",
+            "diagram-render-missing",
+            "diagram-render-drift"
+          ],
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "The checks could not run: --at outside a git repository or at an unknown revision. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message",
+            "location"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "location": {
+              "type": "null"
+            }
+          }
+        },
+        "findings": false,
+        "declaration": false
+      }
+    }
+  }
+}

package/dist/workspace/checks/box-isolation.js

@@ -0,0 +1,62 @@
+/**
+ * The box isolation checks, WSP123 and WSP124 (#2727).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP123 | `box-isolation-collision` | two boxes on one host, or two ports in one box, resolve to the same port, state path or cookie name |
+ * | WSP124 | `box-isolation-literal` | a host's state root or a box's state entry is a literal machine path |
+ *
+ * Both are fixed errors. A collision means one box signs another's people out
+ * or reads another's identity (arugula-salad/studio#39), and a literal path
+ * means the declaration only holds on one machine. Neither has a case where
+ * turning the check down is the fix.
+ */
+import { boxCollisions, boxLiterals } from "../box-isolation.js";
+export const WSP_BOX_COLLISION = "WSP123";
+export const WSP_BOX_LITERAL = "WSP124";
+const WHAT = { port: "port", state: "state path", cookie: "cookie name" };
+export const BOX_ISOLATION_CHECKS = [
+    {
+        id: WSP_BOX_COLLISION,
+        name: "box-isolation-collision",
+        description: "No two boxes on one host resolve to the same port, state path or cookie name, and no two ports in one box share an offset.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            return boxCollisions(ctx.declaration).map((c) => {
+                const [first, ...rest] = c.holders;
+                const names = c.holders.map((h) => `${h.box}.${h.name}`).join(" and ");
+                const hint = c.what === "port"
+                    ? new Set(c.holders.map((h) => h.box)).size > 1
+                        ? "; give each box on a host its own slot"
+                        : "; give each port in a box its own offset"
+                    : "";
+                return {
+                    checkId: this.id,
+                    severity: this.severity,
+                    code: "box-isolation-collision",
+                    message: `box-isolation-collision: ${names} on host ${c.host} resolve to the same ${WHAT[c.what]} ${c.value}${hint}`,
+                    entity: rest.find((h) => h.box !== first.box)?.box ?? first.box,
+                    pointer: (rest[0] ?? first).pointer,
+                };
+            });
+        },
+    },
+    {
+        id: WSP_BOX_LITERAL,
+        name: "box-isolation-literal",
+        description: "No host's state root and no box's state entry is a literal machine path: state paths derive from an environment reference and the member's name.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            return boxLiterals(ctx.declaration).map((l) => ({
+                checkId: this.id,
+                severity: this.severity,
+                code: "box-isolation-literal",
+                message: `box-isolation-literal: ${l.message}`,
+                ...(l.box !== null ? { entity: l.box } : {}),
+                pointer: l.pointer,
+            }));
+        },
+    },
+];