@intentius/chant 0.124.46 → 0.124.48

package/src/cli/commands/import.ts

@@ -1,13 +1,14 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "fs";
 import { join, resolve, basename, dirname } from "path";
 import { formatSuccess, formatWarning, formatError } from "../format";
-import type { TemplateIR, ResourceIR, ParameterIR, ParseContext } from "../../import/parser";
+import type { TemplateIR, ResourceIR, ParameterIR, ParseContext, ImportDiagnostic } from "../../import/parser";
 import type { GeneratedFile, TypeScriptGenerator } from "../../import/generator";
 import { listInstalledLexicons, loadPlugin, loadPlugins, resolveProjectLexicons } from "../plugins";
 import type { ExportedTemplate, LexiconPlugin, ResourceSelector } from "../../lexicon";
 import { parseYAMLDocument, splitYAMLDocuments } from "../../yaml";
 import { importLexiconPackage } from "../../lexicon-module";
 import { resolveParserOptions } from "../../import/parser-options";
+import { summarizeImportDiagnostics } from "./import-report";
 import { EmbeddedImports, type EmbeddedContent, type RegisteredEmbeddedImporter } from "../../import/embedded";
 
 /**
@@ -31,6 +32,8 @@ export interface ImportOptions {
    * fails the import before anything is parsed.
    */
   parserOptions?: string[];
+  /** `--validate` (#4398): check the parsed template on the lexicon's emulator before writing. */
+  validate?: boolean;
 }
 
 /**
@@ -52,6 +55,12 @@ export interface ImportResult {
    * it was named (`--lexicon`, `--kustomize`) (#2965).
    */
   detected?: boolean;
+  /**
+   * What the parser flagged for review (#4398), then what `--validate`
+   * rejected. `--report` writes them as SARIF and `--strict` fails while a
+   * `warning` or `error` is open; see `./import-report.ts`.
+   */
+  diagnostics?: ImportDiagnostic[];
 }
 
 /**
@@ -353,6 +362,7 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
       output: options.output,
       force: options.force,
       parserOptions: options.parserOptions,
+      validate: options.validate,
     });
   }
 
@@ -391,7 +401,7 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
     );
   }
 
-  const result = await parseAndWrite(plugin, content, outputDir, options.force, warnings, generatedFiles, plugin.name, projectDir, options.parserOptions);
+  const result = await parseAndWrite(plugin, content, outputDir, options.force, warnings, generatedFiles, plugin.name, projectDir, options.parserOptions, options.validate);
   return { ...result, detected: true };
 }
 
@@ -412,6 +422,8 @@ export interface ContentImportOptions {
   force?: boolean;
   /** `--parser-option` entries for the lexicon's parser (#2994); see {@link ImportOptions.parserOptions}. */
   parserOptions?: string[];
+  /** `--validate`; see {@link ImportOptions.validate}. */
+  validate?: boolean;
 }
 
 export async function importFromContent(options: ContentImportOptions): Promise<ImportResult> {
@@ -432,7 +444,7 @@ export async function importFromContent(options: ContentImportOptions): Promise<
     return { success: false, generatedFiles: [], warnings: [], error: `Lexicon "${options.lexicon}" not available.` };
   }
   const projectDir = resolve(options.output ? dirname(options.output) : ".");
-  return parseAndWrite(plugin, options.content, outputDir, options.force, [], [], plugin.name, projectDir, options.parserOptions);
+  return parseAndWrite(plugin, options.content, outputDir, options.force, [], [], plugin.name, projectDir, options.parserOptions, options.validate);
 }
 
 /**
@@ -568,6 +580,7 @@ async function parseAndWrite(
   lexicon: string,
   projectDir: string,
   parserOptionEntries?: readonly string[],
+  validate?: boolean,
 ): Promise<ImportResult> {
   // A lexicon can recognize a template (detectTemplate) without being able to
   // import it (grafana had no parser until #2945). Every path funnels through here, so
@@ -609,6 +622,18 @@ async function parseAndWrite(
   if (ir.warnings) {
     warnings.push(...ir.warnings);
   }
+  // Findings for review (#4398), and what the lexicon's emulator rejects.
+  const diagnostics: ImportDiagnostic[] = [...(ir.diagnostics ?? [])];
+  if (validate) {
+    if (!plugin.validateImport) {
+      return { success: false, generatedFiles: [], warnings: [], error: `lexicon "${plugin.name}" has no emulator to validate an import against`, lexicon: plugin.name };
+    }
+    try {
+      diagnostics.push(...(await plugin.validateImport(ir, resolved.options)));
+    } catch (err) {
+      return { success: false, generatedFiles: [], warnings: [], error: `--validate failed to run: ${err instanceof Error ? err.message : String(err)}`, lexicon: plugin.name };
+    }
+  }
   // Embedded content the owner could not carry, or that no installed lexicon imports.
   if (embedded) warnings.push(...embedded.warnings);
 
@@ -660,6 +685,7 @@ async function parseAndWrite(
     generatedFiles,
     warnings,
     lexicon,
+    ...(diagnostics.length > 0 ? { diagnostics } : {}),
   };
 }
 
@@ -894,6 +920,10 @@ export function printImportResult(result: ImportResult): void {
     console.log(`${result.detected ? "Detected lexicon" : "Lexicon"}: ${result.lexicon}`);
   }
 
+  if (result.diagnostics && result.diagnostics.length > 0) {
+    console.error(summarizeImportDiagnostics(result.diagnostics));
+  }
+
   if (result.generatedFiles.length > 0) {
     console.log(formatSuccess("Generated files:"));
     for (const file of result.generatedFiles) {

package/src/cli/commands/migrate-dialect.test.ts

@@ -0,0 +1,145 @@
+/**
+ * `chant migrate` naming and the target-server `--validate` (#4399): a side is
+ * `lexicon` or `lexicon/dialect`, a directory is a source only when the
+ * lexicon says so, and a result's own `validate` replaces the external linter.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { lexiconOfSide, migrateCommand } from "./migrate";
+import type { LexiconPlugin, MigrationResult, MigrationSource } from "../../lexicon";
+
+const seen: Array<{ from: string; to: string | undefined }> = [];
+
+function sqlPlugin(over: { directory?: boolean; result?: Partial<MigrationResult>; transform?: MigrationSource["transform"] } = {}): LexiconPlugin {
+  return {
+    name: "sql",
+    serializer: { name: "sql", rulePrefix: "SQL", serialize: () => "" },
+    async generate() {},
+    async validate() {},
+    async coverage() {},
+    async package() {},
+    migrationSource(from: string, to?: string) {
+      seen.push({ from, to });
+      if (from !== "sql/postgres" || (to !== undefined && to !== "sql/clickhouse")) return undefined;
+      return {
+        detect: (content: string) => content.includes("CREATE TABLE"),
+        ...(over.directory ? { directory: true } : {}),
+        transform: over.transform ?? (async () => ({ output: "-- ddl\n", provenance: [], diagnostics: [], ...over.result })),
+      };
+    },
+  };
+}
+
+const base = { emit: "sql" as const, strict: false, validate: false, useComposites: false };
+
+describe("lexiconOfSide", () => {
+  test("is the part before the slash", () => {
+    expect(lexiconOfSide("sql/clickhouse")).toBe("sql");
+    expect(lexiconOfSide("gitlab")).toBe("gitlab");
+  });
+});
+
+describe("migrateCommand with lexicon/dialect sides", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-migrate-dialect-"));
+    seen.length = 0;
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+  const file = () => {
+    const f = join(dir, "schema.sql");
+    writeFileSync(f, "CREATE TABLE t (id int);");
+    return f;
+  };
+
+  test("finds the plugin by the lexicon part, and hands the source both sides as written", async () => {
+    const r = await migrateCommand({ ...base, sourceFile: file(), from: "sql/postgres", to: "sql/clickhouse", output: join(dir, "out.sql"), plugins: [sqlPlugin()] });
+    expect(r.exitCode).toBe(0);
+    expect(seen).toEqual([{ from: "sql/postgres", to: "sql/clickhouse" }]);
+    expect(readFileSync(join(dir, "out.sql"), "utf8")).toBe("-- ddl\n");
+  });
+
+  test("a dialect the lexicon does not know is refused by name", async () => {
+    const r = await migrateCommand({ ...base, sourceFile: file(), from: "sql/postgres", to: "sql/mysql", plugins: [sqlPlugin()] });
+    expect(r.exitCode).toBe(1);
+    expect(r.error).toContain('Lexicon "sql/mysql" does not support migration from "sql/postgres"');
+  });
+
+  test("creates the output's directory", async () => {
+    const out = join(dir, "a/b/out.sql");
+    const r = await migrateCommand({ ...base, sourceFile: file(), from: "sql/postgres", to: "sql/clickhouse", output: out, plugins: [sqlPlugin()] });
+    expect(r.exitCode).toBe(0);
+    expect(readFileSync(out, "utf8")).toBe("-- ddl\n");
+  });
+
+  test("a directory is refused unless the source reads directories; then detect is skipped and content is empty", async () => {
+    const member = join(dir, "db");
+    mkdirSync(member);
+    const refused = await migrateCommand({ ...base, sourceFile: member, from: "sql/postgres", to: "sql/clickhouse", plugins: [sqlPlugin()] });
+    expect(refused.exitCode).toBe(1);
+    expect(refused.error).toContain("is a directory");
+    let got: { content: string; sourceFile?: string } | undefined;
+    const ok = await migrateCommand({
+      ...base,
+      sourceFile: member,
+      from: "sql/postgres",
+      to: "sql/clickhouse",
+      output: join(dir, "o.sql"),
+      plugins: [sqlPlugin({ directory: true, transform: async (content, opts) => ((got = { content, sourceFile: opts.sourceFile }), { output: "x", provenance: [], diagnostics: [] }) })],
+    });
+    expect(ok.exitCode).toBe(0);
+    expect(got).toEqual({ content: "", sourceFile: member });
+  });
+});
+
+describe("--validate with a result that checks itself", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-migrate-validate-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+  const run = (result: Partial<MigrationResult>, extra: { strict?: boolean } = {}) => {
+    const f = join(dir, "schema.sql");
+    writeFileSync(f, "CREATE TABLE t (id int);");
+    return migrateCommand({ ...base, ...extra, validate: true, sourceFile: f, from: "sql/postgres", to: "sql/clickhouse", output: join(dir, "o.sql"), plugins: [sqlPlugin({ result })] });
+  };
+
+  test("a clean check passes and its diagnostics join the result", async () => {
+    const r = await run({ validate: async () => [] });
+    expect(r.exitCode).toBe(0);
+  });
+
+  test("a refused statement fails the run without --strict, and is in the diagnostics", async () => {
+    const r = await run({ validate: async () => [{ ruleId: "SQLRV012", severity: "error", message: "t: the emulator rejected the statement." }] });
+    expect(r.exitCode).toBe(1);
+    expect(r.diagnostics.map((d) => d.ruleId)).toEqual(["SQLRV012"]);
+  });
+
+  test("a server that cannot start is a validation that did not run, which fails", async () => {
+    const r = await run({
+      validate: async () => {
+        throw new Error("Docker is not available, so the ClickHouse emulator cannot start");
+      },
+    });
+    expect(r.exitCode).toBe(1);
+    expect(r.error).toContain("--validate did not run: Docker is not available");
+  });
+
+  test("without --validate the check is not run", async () => {
+    let ran = false;
+    const f = join(dir, "schema.sql");
+    writeFileSync(f, "CREATE TABLE t (id int);");
+    const r = await migrateCommand({
+      ...base,
+      sourceFile: f,
+      from: "sql/postgres",
+      to: "sql/clickhouse",
+      output: join(dir, "o.sql"),
+      plugins: [sqlPlugin({ result: { validate: async () => ((ran = true), []) } })],
+    });
+    expect(r.exitCode).toBe(0);
+    expect(ran).toBe(false);
+  });
+});

package/src/cli/commands/migrate.ts

@@ -6,19 +6,30 @@
  * stdout/stderr surfaces, and exit codes.
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { spawnSync } from "node:child_process";
 import { formatError, formatInfo } from "../format";
 import { formatSarif } from "../reporters/stylish";
 import type { LexiconPlugin } from "../../lexicon";
 import type { LintRule, LintDiagnostic } from "../../lint/rule";
 import { ensureTypeScriptLoader } from "../../ts-loader";
+import { planMigrateLinks } from "../../workspace/migrate-links";
+
+/**
+ * A side of `--from` or `--to`: a lexicon, or a lexicon and one of its
+ * dialects, `sql/clickhouse` (#4399). The plugin is the part before the slash.
+ */
+export function lexiconOfSide(side: string): string {
+  const slash = side.indexOf("/");
+  return slash === -1 ? side : side.slice(0, slash);
+}
 
 export interface MigrateCliOpts {
   sourceFile: string;
   from: string;
   to: string;
-  emit: "yaml" | "ts";
+  emit: "yaml" | "ts" | "sql";
   strict: boolean;
   validate: boolean;
   useComposites: boolean;
@@ -39,10 +50,13 @@ export interface MigrateCliResult {
   error?: string;
   /** Markdown summary lines printed to stderr */
   markdownSummary?: string;
+  /** What was done about workspace links, or why nothing was (#4399) */
+  linkNote?: string;
 }
 
 export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliResult> {
-  const targetPlugin = opts.plugins.find((p) => p.name === opts.to);
+  const targetLexicon = lexiconOfSide(opts.to);
+  const targetPlugin = opts.plugins.find((p) => p.name === targetLexicon);
   if (!targetPlugin) {
     return {
       exitCode: 1,
@@ -59,7 +73,7 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
       error: `Lexicon "${opts.to}" does not support migration`,
     };
   }
-  const source = targetPlugin.migrationSource(opts.from);
+  const source = targetPlugin.migrationSource(opts.from, opts.to);
   if (!source) {
     return {
       exitCode: 1,
@@ -70,8 +84,23 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
   }
 
   let content: string;
+  // A directory is a workspace member: the source reads it itself (#4399).
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(opts.sourceFile).isDirectory();
+  } catch {
+    // The read below names the problem.
+  }
+  if (isDirectory && !source.directory) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `${opts.sourceFile} is a directory, and migrating from "${opts.from}" reads a file`,
+    };
+  }
   try {
-    content = readFileSync(opts.sourceFile, "utf-8");
+    content = isDirectory ? "" : readFileSync(opts.sourceFile, "utf-8");
   } catch (err) {
     return {
       exitCode: 1,
@@ -81,7 +110,7 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
     };
   }
 
-  if (!source.detect(content)) {
+  if (!isDirectory && !source.detect(content)) {
     return {
       exitCode: 1,
       diagnostics: [],
@@ -113,6 +142,7 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
   // Write output (--output file or stdout)
   if (opts.output && opts.output !== "-") {
     try {
+      mkdirSync(dirname(opts.output), { recursive: true });
       writeFileSync(opts.output, result.output);
     } catch (err) {
       return {
@@ -126,9 +156,34 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
     process.stdout.write(result.output);
   }
 
+  // The target's own server (--validate), when the source has one (#4399).
+  // A refusal always fails the run; so does a server that could not start,
+  // since a validation that did not run is not a pass.
+  let validationFailed = false;
+  if (opts.validate && result.validate) {
+    try {
+      const found = await result.validate();
+      result.diagnostics.push(...found);
+      if (found.some((d) => d.severity === "error")) {
+        validationFailed = true;
+        console.error(`Validator found ${found.filter((d) => d.severity === "error").length} refused statement(s):\n${found.map((d) => `  ${String(d.message)}`).join("\n")}`);
+      } else {
+        console.error("Validator (target server) OK");
+      }
+    } catch (err) {
+      return {
+        exitCode: 1,
+        output: result.output,
+        diagnostics: result.diagnostics,
+        provenance: result.provenance,
+        error: `--validate did not run: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
   // External validator (--validate) — glci preferred, glab fallback.
   let validatorWarning: string | undefined;
-  if (opts.validate && opts.emit === "yaml") {
+  if (opts.validate && !result.validate && opts.emit === "yaml") {
     const v = tryValidateExternal(result.output);
     if (!v.ran) {
       validatorWarning = "neither glci nor glab is on PATH; skipping --validate";
@@ -157,11 +212,35 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
     }
   }
 
+  // Links from the output's workspace member to the outputs it reads (#4399).
+  let linkNote: string | undefined;
+  if (result.links && result.links.length > 0) {
+    const outcome = planMigrateLinks({
+      sourcePath: opts.sourceFile,
+      outputPath: opts.output && opts.output !== "-" ? opts.output : undefined,
+      outputs: result.links,
+    });
+    if (outcome && "skipped" in outcome) linkNote = outcome.skipped;
+    else if (outcome) {
+      const { plan } = outcome;
+      if (plan.added.length === 0) {
+        linkNote = `member ${plan.consumer} already links every output it reads from ${plan.producer}`;
+      } else {
+        try {
+          writeFileSync(plan.file, plan.text);
+          linkNote = `added ${plan.added.length} link${plan.added.length === 1 ? "" : "s"} from member ${plan.consumer} to ${plan.producer} in ${plan.file}`;
+        } catch (err) {
+          linkNote = `could not write the links to ${plan.file}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+      }
+    }
+  }
+
   // SARIF report (--report <path>) — reuse the lint-side formatSarif so any
   // CI SARIF ingest path treats migration findings uniformly.
   if (opts.reportFile) {
     try {
-      const rules = await loadMigrationRules(opts.to);
+      const rules = await loadMigrationRules(targetLexicon);
       const lintShape = result.diagnostics as unknown as LintDiagnostic[];
       const sarif = formatSarif(lintShape, rules);
       writeFileSync(opts.reportFile, sarif);
@@ -172,7 +251,8 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
   }
 
   // Markdown summary (always to stderr — leaves stdout clean for piping)
-  let markdownSummary = formatMarkdownSummary(result.provenance, result.diagnostics, content);
+  let markdownSummary =
+    targetLexicon === "gitlab" ? formatMarkdownSummary(result.provenance, result.diagnostics, content) : formatDiagnosticSummary(result.provenance, result.diagnostics);
   // Append the security posture section when security analysis ran (#306).
   if (result.securityPosture) {
     markdownSummary += `\n\n${result.securityPosture}`;
@@ -182,7 +262,7 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
   // The transformer already escalates needs-review → error when opts.strict
   // is passed via MigrationSource.transform(); we double-check here.
   const errorDiagnostics = result.diagnostics.filter((d) => d.severity === "error");
-  const exitCode = opts.strict && errorDiagnostics.length > 0 ? 1 : 0;
+  const exitCode = validationFailed || (opts.strict && errorDiagnostics.length > 0) ? 1 : 0;
 
   return {
     exitCode,
@@ -190,6 +270,7 @@ export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliRe
     diagnostics: result.diagnostics,
     provenance: result.provenance,
     markdownSummary,
+    ...(linkNote ? { linkNote } : {}),
   };
 }
 
@@ -231,7 +312,7 @@ export function tryValidateExternal(yamlText: string): ValidatorResult {
  * Returns an empty array if the lexicon doesn't expose them.
  */
 async function loadMigrationRules(targetLexicon: string): Promise<LintRule[]> {
-  // For now only gitlab exposes migration rules. Hard-coded import keeps
+  // gitlab and sql expose migration rules. Hard-coded imports keep
   // the dependency direction explicit; widen the switch when more
   // lexicons ship their own migrate paths.
   if (targetLexicon === "gitlab") {
@@ -243,9 +324,46 @@ async function loadMigrationRules(targetLexicon: string): Promise<LintRule[]> {
       return [];
     }
   }
+  // The sql lexicon's needs-review catalog (#4399), one rule per finding id.
+  if (targetLexicon === "sql") {
+    try {
+      ensureTypeScriptLoader();
+      const mod = await import("@intentius/chant-lexicon-sql/clickhouse/review-catalog");
+      const rules = (mod as { REVIEW_RULES: Record<string, { id: string; name: string; summary: string; docs: readonly string[] }> }).REVIEW_RULES;
+      return Object.values(rules).map((r): LintRule => ({
+        id: r.id,
+        severity: "warning",
+        category: "correctness",
+        description: `${r.name}: ${r.summary}`,
+        helpUri: r.docs[0] ?? "https://intentius.io/chant/lexicons/sql/migrate-postgres-to-clickhouse/",
+        check: () => [],
+      }));
+    } catch {
+      return [];
+    }
+  }
   return [];
 }
 
+/**
+ * The report for a pair that is not GitHub to GitLab: the counts and the
+ * diagnostics, with none of that pair's workflow advice (#4399).
+ */
+export function formatDiagnosticSummary(provenance: Array<Record<string, unknown>>, diagnostics: Array<Record<string, unknown>>): string {
+  const totals = { error: 0, warning: 0, info: 0 };
+  for (const d of diagnostics) {
+    const sev = d.severity as string;
+    if (sev === "error" || sev === "warning" || sev === "info") totals[sev]++;
+  }
+  const lines = ["", "## Migration report", "", `- Translated: ${provenance.length}`, `- Diagnostics: ${totals.error} error, ${totals.warning} warning, ${totals.info} info`];
+  if (diagnostics.length > 0) {
+    lines.push("", "### Diagnostics", "", "| Severity | Rule | Message |", "|---|---|---|");
+    for (const d of diagnostics.slice(0, 50)) lines.push(`| ${String(d.severity)} | ${String(d.ruleId)} | ${String(d.message).replace(/\|/g, "\\|").slice(0, 160)} |`);
+    if (diagnostics.length > 50) lines.push(`| ... | ... | ${diagnostics.length - 50} more diagnostics omitted |`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Format the migration report as Markdown, mirroring the output format
  * prescribed by the upstream gitlab-org/ci-cd/github-actions-to-gitlab-ci
@@ -471,6 +589,9 @@ export function printMigrateResult(result: MigrateCliResult): void {
   if (result.markdownSummary) {
     console.error(result.markdownSummary);
   }
+  if (result.linkNote) {
+    console.error(`\nWorkspace links: ${result.linkNote}`);
+  }
   if (result.exitCode === 0) {
     console.error(formatInfo("\nMigration complete."));
   } else {

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

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
     container: node:22
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
       - name: Upload shared-alb outputs
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: shared-alb-outputs
           path: shared-alb.outputs.json
@@ -27,9 +27,9 @@ jobs:
       - shared-alb
     container: node:22
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Download shared-alb outputs
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: shared-alb-outputs
           path: .

package/src/cli/handlers/approve.ts

@@ -599,6 +599,21 @@ export async function recordGateApproval(
   // decision is written next to the approval, so a pass can be traced to the
   // rule that allowed it.
   const approval = standingForOrigin?.approval;
+  // #4290, #4324: roles come from .chant/trust.json at base, for an approver
+  // a seal proves. The quorum and the policy both read these, never --role.
+  const judge = trustQuorumJudge({ signers: scope.policy, roles: scope.policy.roles });
+  const trusted = judge({
+    version: 1,
+    op: opName,
+    gate,
+    ...(environment !== undefined ? { environment } : {}),
+    ...(planDigest !== undefined ? { planDigest } : {}),
+    resolvedBy,
+    ...(relayedBy ? { relayedBy } : {}),
+    timestamp,
+    ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
+    ...(seal ? { seal } : {}),
+  }).roles;
   let policyDecision: GatePolicyDecision | undefined;
   if (approval?.policy) {
     try {
@@ -610,6 +625,7 @@ export async function recordGateApproval(
           gate,
           resolvedBy,
           approver,
+          roles: trusted,
           ...(planDigest !== undefined ? { planDigest } : {}),
           ...(approval.context ? { context: approval.context } : {}),
         }),
@@ -680,9 +696,14 @@ export async function recordGateApproval(
         "after it plans again. A moved plan or another commit starts it at the first phase.",
     ));
   }
+  const untrusted = (approver.roles ?? []).filter((r) => !trusted.includes(r));
+  if (untrusted.length > 0) {
+    console.error(formatInfo(
+      `--role ${untrusted.join(", ")} is recorded on the approval and trusted by nothing: a gate's quorum and policy read ` +
+        `${record.resolvedBy}'s roles from .chant/trust.json at base, and only for an approval sealed by a signer listed at base (chant approve --sign).`,
+    ));
+  }
   if (approval) {
-    // #4290: the rules count roles from .chant/trust.json at base, for a proven approver.
-    const judge = trustQuorumJudge({ signers: scope.policy, roles: scope.policy.roles });
     for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending, judge)) {
       console.error(formatInfo(line));
     }

package/src/cli/handlers/build.ts

@@ -171,6 +171,12 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     }
   }
 
+  // #4327: ci.locks: plan adds the lock and unlock jobs. Read from the declaration, as the security groups are; GitLab keeps its own jobs.
+  let locks: "plan" | undefined;
+  if (found && args.prLoop && lexicon !== "gitlab") {
+    locks = (await import("../../workspace/ci-locks")).ciLocksAt(resolve(args.path)) === "plan" ? "plan" : undefined;
+  }
+
   // Which lexicons support generate mode is a property of the loaded lexicon
   // plugins (those implementing `generateComponentPipeline`, #688), not a
   // hard-coded core list — `generateComponentsPipeline` returns a descriptive
@@ -192,7 +198,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         : {}),
       // #3183: a plan job per pull request and an apply job per merge.
       // #4292: on the branch ci.branches routes the member to, when it routes it.
-      ...(args.prLoop ? { prLoop: { ...prLoopOption(args, reportUrl, reviewRules, isolatedRunners), ...(plan?.branch ? { branch: plan.branch } : {}), ...(identity ? { identity } : {}), ...(prEnvIdentity ? { prEnvIdentity } : {}) } } : {}),
+      ...(args.prLoop ? { prLoop: { ...prLoopOption(args, reportUrl, reviewRules, isolatedRunners), ...(plan?.branch ? { branch: plan.branch } : {}), ...(identity ? { identity } : {}), ...(prEnvIdentity ? { prEnvIdentity } : {}), ...(locks ? { locks } : {}) } } : {}),
       // #4002: the job image and the lines that install what it lacks, chant itself included.
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),

package/src/cli/handlers/ledger.ts

@@ -0,0 +1,54 @@
+/**
+ * `chant ledger <table> [dir] [--member <name>] [--where <field><op><value>]...
+ * [--since <time>] [--at <rev>] [--json]` (#4363): one ledger's rows from the
+ * local `chant/lifecycle` branch, filtered with typed filters. The read and
+ * its contract live in `../../lifecycle/ledger-read.ts`; the ledgers are read
+ * as `chant query` reads them (`./query.ts` {@link queryLedgers}).
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { queryLedgers } from "./query";
+
+const USAGE = "chant ledger <resources|snapshots|runs|gates|deploys|releases|cuts> [dir] [--member <name>] [--where <field><op><value>]... [--since <time>] [--at <rev>] [--json]";
+
+const cell = (v: unknown): string => (v === null || v === undefined ? "" : typeof v === "object" ? JSON.stringify(v) : String(v));
+
+export async function runLedgerCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const table = args.positionals?.[0];
+  if (table === undefined || table.trim() === "") {
+    console.error(formatError({ message: "chant ledger needs a table", hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(args.positionals?.[1] ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  const { readLedgerTable, ledgerReadFailure, LedgerRevisionError } = await import("../../lifecycle/ledger-read");
+  const { QueryError } = await import("../../lifecycle/query");
+  let doc;
+  try {
+    doc = await readLedgerTable(table, () => queryLedgers(cwd, args.members, args.at), { where: args.where, since: args.since, at: args.at ?? null });
+  } catch (err) {
+    if (err instanceof LedgerRevisionError) doc = ledgerReadFailure("revision-unknown", err.message);
+    else if (err instanceof QueryError) doc = ledgerReadFailure("ledger-unreadable", err.message);
+    else throw err;
+  }
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  const widths = doc.columns.map((c) => Math.max(c.length, ...doc.rows.map((r) => cell(r[c]).length)));
+  const line = (vals: string[]): string => vals.map((v, i) => v.padEnd(widths[i])).join("  ").trimEnd();
+  console.log([line(doc.columns), line(widths.map((w) => "-".repeat(w))), ...doc.rows.map((r) => line(doc.columns.map((c) => cell(r[c]))))].join("\n"));
+  console.log(`(${doc.rows.length} of ${doc.total} ${doc.total === 1 ? "row" : "rows"})`);
+  if (doc.malformed > 0) console.error(formatWarning({ message: `left out ${doc.malformed} in ${doc.table} that could not be read` }));
+  return 0;
+}