@intentius/chant 0.101.0 → 0.104.0

package/src/cli/commands/onboard.ts

@@ -117,6 +117,10 @@ function patchRootPackageJson(root: string, name: string): PatchResult {
  * The whole-repo typecheck runs with `moduleResolution: node`, which never
  * reads package exports maps, so every lexicon needs a bare + subpath
  * mapping here or an example importing the package fails to resolve.
+ *
+ * Entries are `./`-prefixed like every other entry (#3227): with no `baseUrl`
+ * (removed in #3205) a bare `lexicons/...` path is invalid and tsx's tsconfig
+ * loader throws on it for every run in the repo.
  */
 export function patchRootTsconfigPaths(root: string, name: string): PatchResult {
   const tsconfigPath = join(root, "tsconfig.json");
@@ -128,8 +132,8 @@ export function patchRootTsconfigPaths(root: string, name: string): PatchResult
 
   const bare = `@intentius/chant-lexicon-${name}`;
   const wanted: Record<string, string[]> = {
-    [bare]: [`lexicons/${name}/src/index.ts`],
-    [`${bare}/*`]: [`lexicons/${name}/src/*`],
+    [bare]: [`./lexicons/${name}/src/index.ts`],
+    [`${bare}/*`]: [`./lexicons/${name}/src/*`],
   };
 
   let changed = false;
@@ -297,7 +301,15 @@ function patchPublishWorkflow(root: string, name: string): PatchResult {
   }
 
   if (!insertPrepackAfterEach(lines, name)) {
-    return { patched: false, reason: "no prepack line found to anchor on" };
+    // #3227 — not a failure and not "covered by a prepack line": publish.yml
+    // carries no per-lexicon lines. The run builds every lexicon through
+    // scripts/ci-lexicon-artifacts.sh and publishes through
+    // scripts/publish-packages.sh, both of which enumerate the workspace.
+    return {
+      patched: false,
+      reason:
+        "nothing to patch: it has no per-lexicon prepack lines; scripts/ci-lexicon-artifacts.sh and scripts/publish-packages.sh enumerate the workspace",
+    };
   }
   writeFileSync(filePath, lines.join("\n"));
   return { patched: true };
@@ -321,6 +333,12 @@ export function patchDockerfile(filePath: string, name: string): PatchResult {
 
   const changed = addToLexiconLoops(lines, name) || insertPrepackAfterEach(lines, name);
   if (!changed) {
+    // #3227 — the smoke-npm and smoke-e2e images read their lexicon list from
+    // a file. Point at it instead of reporting a missing anchor.
+    const listFile = lines.join("\n").match(/test\/(smoke-[\w-]+-lexicons\.txt)/)?.[1];
+    if (listFile) {
+      return { patched: false, reason: `reads its lexicon list from test/${listFile}, not from the Dockerfile` };
+    }
     return { patched: false, reason: "no lexicon loop or prepack line found to anchor on" };
   }
 
@@ -328,6 +346,22 @@ export function patchDockerfile(filePath: string, name: string): PatchResult {
   return { patched: true };
 }
 
+/**
+ * Append a lexicon to a one-name-per-line list file (test/smoke-npm-lexicons.txt).
+ * Idempotent; keeps the file's trailing newline.
+ */
+export function patchLexiconList(filePath: string, name: string): PatchResult {
+  const rel = filePath.split("/").slice(-2).join("/");
+  if (!existsSync(filePath)) return { patched: false, reason: `${rel} not found` };
+  const content = readFileSync(filePath, "utf-8");
+  if (content.split("\n").some((l) => l.trim() === name)) {
+    return { patched: false, reason: `${name} already in ${rel}` };
+  }
+  const sep = content === "" || content.endsWith("\n") ? "" : "\n";
+  writeFileSync(filePath, `${content}${sep}${name}\n`);
+  return { patched: true };
+}
+
 /**
  * Execute the onboard command — patches monorepo infrastructure for a new lexicon.
  */
@@ -375,6 +409,20 @@ export function onboardCommand(options: OnboardOptions): OnboardResult {
     patchDockerfile(join(root, "test/Dockerfile.smoke-npm"), options.name),
   );
 
+  // 6. Smoke image lexicon lists (#3227). The npm smoke packs every lexicon.
+  //    The e2e list is opt-in: it names the lexicons an example uses plus
+  //    their dependencies, so onboard leaves it alone and says so.
+  record(
+    "smoke-npm-lexicons.txt",
+    "lexicon list",
+    patchLexiconList(join(root, "test/smoke-npm-lexicons.txt"), options.name),
+  );
+  if (existsSync(join(root, "test/smoke-e2e-lexicons.txt"))) {
+    skipped.push(
+      `smoke-e2e-lexicons.txt: not patched; it lists only lexicons an e2e example uses (and their dependencies). Add ${options.name} to test/smoke-e2e-lexicons.txt when an example needs it`,
+    );
+  }
+
   return { success: true, patched, skipped, verbose: options.verbose };
 }
 
@@ -396,7 +444,7 @@ export async function printOnboardResult(result: OnboardResult, name: string): P
 
   if (result.skipped.length > 0) {
     console.log("");
-    console.log("Skipped (already covered):");
+    console.log("Not patched (already covered, or nothing to patch):");
     for (const s of result.skipped) {
       console.log(`  ${s}`);
     }

package/src/cli/commands/pinned-upgrade.ts

@@ -1,7 +1,7 @@
 /**
  * `chant dev pinned-upgrade <lexicon-dir>` command implementation.
  *
- * Detects whether a pinned-version lexicon (k8s, gcp, docker, gitlab) has a
+ * Detects whether a lexicon that declares `upstreamPin` has a
  * newer stable upstream release. When it does, it dry-run bumps the pinned
  * version constant, regenerates + surface-diffs (via #524's regenLexicon), then
  * reverts the bump — leaving the working tree unchanged.
@@ -10,20 +10,21 @@
  */
 
 import { existsSync } from "fs";
-import { basename, resolve } from "path";
+import { resolve } from "path";
 import {
-  checkPinnedUpgrade,
+  checkPinnedUpgrades,
+  lexiconNameOf,
   type LexiconId,
   type UpgradeCheckResult,
 } from "../../codegen/pinned-upgrade";
 
-const PINNED_LEXICONS: readonly LexiconId[] = ["k8s", "gcp", "docker", "gitlab"];
-
 export interface PinnedUpgradeOptions {
   /** Resolved path to the lexicon directory. */
   lexiconDir: string;
   /** Explicit lexicon id; inferred from the directory name when omitted. */
   lexicon?: LexiconId;
+  /** Label of one pin to check, for a lexicon that declares several. Omitted: all of them. */
+  pin?: string;
   /** Force re-fetch of the upstream spec during regen. */
   force?: boolean;
   /** Print subprocess output while running. */
@@ -31,12 +32,13 @@ export interface PinnedUpgradeOptions {
 }
 
 /**
- * Infer the lexicon id from a directory name. Returns null when the directory
- * basename is not one of the pinned lexicons.
+ * Infer the lexicon id from a directory: its package name
+ * (`@intentius/chant-lexicon-<name>`), else the directory name. Whether the
+ * lexicon is pinned is the plugin's `upstreamPin`, checked by
+ * `checkPinnedUpgrade`, not a list here.
  */
-export function inferLexicon(lexiconDir: string): LexiconId | null {
-  const name = basename(lexiconDir);
-  return (PINNED_LEXICONS as readonly string[]).includes(name) ? (name as LexiconId) : null;
+export function inferLexicon(lexiconDir: string): LexiconId {
+  return lexiconNameOf(lexiconDir);
 }
 
 /**
@@ -52,37 +54,38 @@ export function semverLabel(result: UpgradeCheckResult): "minor" | "major" | "no
 
 /**
  * Run the pinned-upgrade check and return the structured result.
- * Never throws — a missing dir or an unrecognised lexicon becomes a fetchError.
+ * Never throws — a missing dir or a lexicon with no `upstreamPin` becomes a fetchError.
  */
 export async function runPinnedUpgrade(opts: PinnedUpgradeOptions): Promise<UpgradeCheckResult> {
+  return (await runPinnedUpgrades(opts))[0]!;
+}
+
+/**
+ * Run the check for every pin the plugin declares (or the one in `opts.pin`),
+ * one result each. A lexicon with one pin gives one result.
+ */
+export async function runPinnedUpgrades(opts: PinnedUpgradeOptions): Promise<UpgradeCheckResult[]> {
   const dir = resolve(opts.lexiconDir);
 
   const lexicon = opts.lexicon ?? inferLexicon(dir);
-  if (!lexicon) {
-    return {
-      lexicon: "k8s",
-      hasUpgrade: false,
-      from: "(unknown)",
-      to: null,
-      validation: null,
-      fetchError: `Not a pinned lexicon directory: ${dir}. Expected one of: ${PINNED_LEXICONS.join(", ")}.`,
-    };
-  }
 
   if (!existsSync(dir)) {
-    return {
-      lexicon,
-      hasUpgrade: false,
-      from: "(unknown)",
-      to: null,
-      validation: null,
-      fetchError: `Lexicon directory not found: ${dir}`,
-    };
+    return [
+      {
+        lexicon,
+        hasUpgrade: false,
+        from: "(unknown)",
+        to: null,
+        validation: null,
+        fetchError: `Lexicon directory not found: ${dir}`,
+      },
+    ];
   }
 
-  return checkPinnedUpgrade({
+  return checkPinnedUpgrades({
     lexiconDir: dir,
     lexicon,
+    pin: opts.pin,
     force: opts.force,
     verbose: opts.verbose,
   });
@@ -112,12 +115,14 @@ function c(text: string, code: string): string {
  */
 export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boolean): void {
   const label = semverLabel(result);
+  const name = result.pin ? `${result.lexicon}/${result.pin}` : result.lexicon;
 
   if (json) {
     console.log(
       JSON.stringify(
         {
           lexicon: result.lexicon,
+          ...(result.pin ? { pin: result.pin } : {}),
           hasUpgrade: result.hasUpgrade,
           from: result.from,
           to: result.to,
@@ -128,6 +133,7 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
           validationOk: result.validation?.ok ?? null,
           failures: result.validation?.failures ?? [],
           fetchError: result.fetchError,
+          manualPin: result.manualPin ?? null,
         },
         null,
         2,
@@ -137,22 +143,31 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
   }
 
   if (result.fetchError) {
-    console.log(c(`[${result.lexicon}] error: ${result.fetchError}`, COLORS.red));
+    console.log(c(`[${name}] error: ${result.fetchError}`, COLORS.red));
     return;
   }
 
   if (!result.hasUpgrade) {
     console.log(
-      c(`[${result.lexicon}] up to date`, COLORS.green) +
+      c(`[${name}] up to date`, COLORS.green) +
         `  pinned=${result.from}` +
         (result.to ? ` latest=${result.to}` : ""),
     );
     return;
   }
 
+  if (result.manualPin) {
+    console.log(
+      c(`[${name}] upgrade available`, COLORS.bold) + `  ${result.from} -> ${result.to}`,
+    );
+    console.log(`  The pin in ${result.manualPin.file} cannot be rewritten generically, so nothing was edited or regenerated.`);
+    console.log(`  ${result.manualPin.instructions}`);
+    return;
+  }
+
   // Upgrade available
   console.log(
-    c(`[${result.lexicon}] upgrade available`, COLORS.bold) +
+    c(`[${name}] upgrade available`, COLORS.bold) +
       `  ${result.from} -> ${result.to}`,
   );
 
@@ -202,3 +217,28 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
     `Validation: ${validationLabel}  Semver: ${c(label, labelColor)}  ${result.from} -> ${result.to}`,
   );
 }
+
+/**
+ * Print one result per pin. One result prints exactly as `printPinnedUpgradeResult`;
+ * several print in turn, and `json` emits an array of the same objects.
+ */
+export function printPinnedUpgradeResults(results: UpgradeCheckResult[], json: boolean): void {
+  if (results.length === 1) {
+    printPinnedUpgradeResult(results[0]!, json);
+    return;
+  }
+  if (json) {
+    // Each result prints as its own JSON object; collect them into one array.
+    const lines: string[] = [];
+    const log = console.log;
+    console.log = (...a: unknown[]) => void lines.push(a.join(" "));
+    try {
+      for (const r of results) printPinnedUpgradeResult(r, true);
+    } finally {
+      console.log = log;
+    }
+    console.log(`[${lines.join(",\n")}]`);
+    return;
+  }
+  for (const r of results) printPinnedUpgradeResult(r, false);
+}

package/src/cli/handlers/__snapshots__/build-member.test.ts.snap

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     container: node:22-slim
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
       - name: Upload shared-alb outputs
         uses: actions/upload-artifact@v4
@@ -27,7 +27,7 @@ jobs:
       - shared-alb
     container: node:22-slim
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Download shared-alb outputs
         uses: actions/download-artifact@v4
         with:

package/src/cli/handlers/build.ts

@@ -79,7 +79,19 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   const result = await generateComponentsPipeline(
     args.path,
     lexicon,
-    { env: args.env, ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}), ...(plan ? { member: plan.member } : {}) },
+    {
+      env: args.env,
+      ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}),
+      ...(plan ? { member: plan.member } : {}),
+      // #3049: one job per wave of a gated-wave fan-out instead of one per component.
+      ...(args.waveGate
+        ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
+        : {}),
+      // #3183: a plan job per pull request and an apply job per merge.
+      ...(args.prLoop
+        ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } }
+        : {}),
+    },
     args.sandbox,
     paramsResolution.provenance,
   );

package/src/cli/handlers/change-set.test.ts

@@ -0,0 +1,56 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { composeChangeSet } from "../../change-set";
+import { commandRegistry, parseArgs } from "../main";
+import { resolveCommand } from "../registry";
+import { runChangeSetSummary } from "./change-set";
+
+const dir = mkdtempSync(join(tmpdir(), "chant-change-set-summary-"));
+const file = join(dir, "change-set.json");
+writeFileSync(
+  file,
+  JSON.stringify(
+    composeChangeSet(
+      ["a", "b"].map((m, i) => ({
+        member: { member: m, lexicon: "terraform", planner: "terraform" as const, status: "planned" as const, planDigest: `jcs1-sha256:${String(i).padStart(64, "0")}`, holes: [] },
+        entries: [{ member: m, lexicon: "terraform", planner: "terraform" as const, address: "aws_db_instance.main", type: "aws_db_instance", action: "delete" as const, attributes: [] }],
+      })),
+    ),
+  ),
+);
+
+async function run(argv: string[]): Promise<{ code: number; out: string; err: string }> {
+  let out = "";
+  let err = "";
+  vi.spyOn(process.stdout, "write").mockImplementation((s) => ((out += String(s)), true));
+  vi.spyOn(console, "log").mockImplementation((s) => void (out += String(s) + "\n"));
+  vi.spyOn(console, "error").mockImplementation((s) => void (err += String(s) + "\n"));
+  const args = parseArgs(argv);
+  expect(resolveCommand(args, commandRegistry)?.def.name).toBe("change-set summary");
+  const code = await runChangeSetSummary({ args, plugins: [], serializers: [] });
+  return { code, out, err };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("chant change-set summary", () => {
+  test("prints text, json and markdown, naming each destroy", async () => {
+    const text = await run(["change-set", "summary", file]);
+    expect(text.code).toBe(0);
+    expect(text.out).toContain("2 members: 1 group, 2 destroys or replacements.");
+    expect(text.out).toContain("a: aws_db_instance.main (delete)");
+    const json = await run(["change-set", "summary", file, "--format", "json"]);
+    expect(JSON.parse(json.out).destroys).toHaveLength(2);
+    const md = await run(["change-set", "summary", file, "--format", "markdown", "--limit", "500"]);
+    expect(md.out).toContain("- `b: aws_db_instance.main (delete)`");
+  });
+
+  test("refuses a file that is not a change-set document, and an unknown format", async () => {
+    const other = join(dir, "other.json");
+    writeFileSync(other, "{}");
+    expect((await run(["change-set", "summary", other])).err).toContain("is not a change-set document");
+    expect((await run(["change-set", "summary", file, "--format", "html"])).code).toBe(1);
+  });
+});

package/src/cli/handlers/change-set.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, type ChangeSetDocument } from "../../change-set";
+import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "../../plan-summary";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+const USAGE = "chant change-set summary <change-set.json> [--format text|json|markdown] [--limit <chars>]";
+
+/**
+ * `chant change-set summary <file>` (#3188): the grouped plan summary of a
+ * change-set document (`../../change-set.ts`), such as the `document` a
+ * `composeChangeSet` step returns. `--format` picks text (default), json
+ * (the plan-summary schema) or markdown, an MR or PR note of at most
+ * `--limit` characters (default GitHub's comment limit, 65536). Reads one
+ * file; no project, no plugins, no network.
+ */
+export async function runChangeSetSummary(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const file = args.extraPositional;
+  const format = args.json ? "json" : args.format || "text";
+  const fail = (message: string): number => {
+    console.error(formatError({ message, hint: USAGE }));
+    return 1;
+  };
+  if (!file) return fail("change-set summary needs the change-set document to read");
+  if (format !== "text" && format !== "json" && format !== "markdown") return fail(`--format ${format} is not one of text, json or markdown`);
+  if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 200)) return fail("--limit needs a whole number of characters, at least 200");
+
+  let doc: ChangeSetDocument;
+  try {
+    doc = JSON.parse(readFileSync(file, "utf-8")) as ChangeSetDocument;
+  } catch (err) {
+    return fail(`cannot read ${file} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (doc?.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT) {
+    return fail(`${file} is not a change-set document: its $schema is not ${CHANGE_SET_SCHEMA_ID} with contract ${CHANGE_SET_CONTRACT}`);
+  }
+
+  const summary = groupChangeSet(doc);
+  if (format === "json") console.log(JSON.stringify(summary, null, 2));
+  else if (format === "markdown") process.stdout.write(renderPlanSummaryMarkdown(summary, { limit: args.limit ?? GITHUB_COMMENT_LIMIT }));
+  else process.stdout.write(renderPlanSummaryText(summary));
+  return 0;
+}

package/src/cli/handlers/components.ts

@@ -48,7 +48,7 @@ import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
 import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -643,7 +643,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
           const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
           for (const [name, entity] of buildResult.entities) {
             // Resource declarables only (see lifecycle/observe.ts).
-            if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
+            if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
               declared.add(name);
               entities.set(name, {
                 entityType: entity.entityType,

package/src/cli/handlers/dev.ts

@@ -85,16 +85,18 @@ export async function runDevSurfaceDiff(ctx: CommandContext): Promise<number> {
 
 export async function runDevPinnedUpgrade(ctx: CommandContext): Promise<number> {
   const dir = ctx.args.extraPositional ?? ".";
-  const { runPinnedUpgrade, printPinnedUpgradeResult } = await import("../commands/pinned-upgrade");
-  const result = await runPinnedUpgrade({
+  const { runPinnedUpgrades, printPinnedUpgradeResults } = await import("../commands/pinned-upgrade");
+  // The optional second positional is a pin label, for a lexicon that declares several pins.
+  const results = await runPinnedUpgrades({
     lexiconDir: resolve(dir),
+    pin: ctx.args.extraPositional2,
     force: ctx.args.force,
     verbose: ctx.args.verbose,
   });
-  printPinnedUpgradeResult(result, ctx.args.format === "json");
-  // Exit non-zero when the upstream query failed or the regen validation broke.
-  if (result.fetchError) return 1;
-  if (result.validation && !result.validation.ok) return 1;
+  printPinnedUpgradeResults(results, ctx.args.format === "json");
+  // Exit non-zero when an upstream query failed or a regen validation broke.
+  if (results.some((r) => r.fetchError)) return 1;
+  if (results.some((r) => r.validation && !r.validation.ok)) return 1;
   return 0;
 }