@intentius/chant 0.124.45 → 0.124.48

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/declared-graph.ts

@@ -0,0 +1,99 @@
+import { dirname } from "node:path";
+import { mergeBuildRootEntities } from "../../build";
+import { loadChantConfigUpward, type ChantConfig } from "../../config";
+import type { Declarable } from "../../declarable";
+import { applyLexiconGraphEdges, type GraphIR, type LexiconGraphEdges } from "../../graph-ir";
+import type { BuildRootContributor, LexiconPlugin } from "../../lexicon";
+import { formatError, formatWarning } from "../format";
+import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } from "../plugins";
+import type { CommandContext } from "../registry";
+
+/**
+ * The pieces of the declared graph that `chant graph` and `chant search` both
+ * read (#1626, #4365, #4368). They live here, once, so the two commands answer
+ * over the same entity set and the same edges: search drifted from graph once
+ * already, answering `(no matches)` over a `terraform.roots` project graph drew
+ * in full, because it never ran the build-root contributors.
+ */
+
+/**
+ * The build-root contributors this invocation's project configures (#1626):
+ * a `terraform.roots` root's blocks, a `k8s.kustomize.roots` root's rendered
+ * objects. The same closures `chant build` and the lifecycle handlers hand to
+ * `BuildOptions.buildRoots`, bound here for the discover-based paths, which
+ * never run `build()` and so never ran the hook.
+ *
+ * Neither command is `requiresPlugins` (Op/source-graph modes must work
+ * without a lexicon), so plugins are loaded here when `ctx.plugins` is empty.
+ * Rooted at the config's own directory, like `cli/commands/build.ts`: a
+ * relative root resolves against where it was declared, not against a
+ * sourceDir-scoped path. A project that fails to load plugins degrades to no
+ * contributors with a warning rather than failing modes that never needed
+ * plugins at all.
+ */
+export async function declaredBuildRootContributors(
+  ctx: CommandContext,
+  projectPath: string,
+): Promise<BuildRootContributor[]> {
+  const { config, configPath } = await loadChantConfigUpward(projectPath).catch(
+    () => ({ config: {} as ChantConfig, configPath: undefined }),
+  );
+  let plugins = ctx.plugins;
+  if (plugins.length === 0) {
+    try {
+      plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
+    } catch (err) {
+      console.error(formatWarning({
+        message: `could not load the project's lexicons — build-root entities (terraform and kustomize roots) will be missing from the graph (${err instanceof Error ? err.message : String(err)})`,
+      }));
+      return [];
+    }
+  }
+  return collectBuildRootContributors(
+    plugins,
+    config as unknown as Record<string, unknown>,
+    configPath ? dirname(configPath) : projectPath,
+  );
+}
+
+/**
+ * Merge build-root contributions into a discovered entity set: the exact
+ * merge `build()` performs (one implementation: `mergeBuildRootEntities`,
+ * ../../build.ts), with its warnings and errors printed. Returns false when a
+ * contributor failed or a name collided; the caller stops, because a graph
+ * missing the entities the build would refuse over must not be answered from
+ * as if complete.
+ */
+export async function mergeDeclaredBuildRoots(
+  entities: Map<string, Declarable>,
+  contributors: BuildRootContributor[],
+): Promise<boolean> {
+  if (contributors.length === 0) return true;
+  const merged = await mergeBuildRootEntities(entities, contributors);
+  for (const w of merged.warnings) console.error(formatWarning({ message: w }));
+  if (merged.errors.length > 0) {
+    for (const message of merged.errors) console.error(formatError({ message }));
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Add the edges the lexicons' `graphEdges` hooks resolve (#3910): CI
+ * dependencies written as strings (`needs`, `uses:`, `trigger:`, `include:`,
+ * `extends`), which the AttrRef walk in `buildGraphIr` cannot see. A hook that
+ * throws costs its own edges and a warning, not the graph.
+ */
+export function withLexiconEdges(ir: GraphIR, plugins: readonly LexiconPlugin[], entities: Map<string, Declarable>): GraphIR {
+  const reports: LexiconGraphEdges[] = [];
+  for (const p of plugins) {
+    if (!p.graphEdges) continue;
+    try {
+      const report = p.graphEdges(entities);
+      if (report) reports.push(report);
+    } catch (err) {
+      console.error(formatWarning({ message: `the ${p.name} lexicon's graphEdges failed (${err instanceof Error ? err.message : String(err)}); its edges are left out` }));
+    }
+  }
+  return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
+}

package/src/cli/handlers/graph.test.ts

@@ -75,9 +75,10 @@ vi.mock("../../lifecycle/replay", () => ({
   hasSnapshot: (...a: unknown[]) => hasSnapshotMock(...a),
 }));
 
-vi.mock("../../lifecycle/observe", () => ({
-  observeResources: (...a: unknown[]) => observeMock(...a),
-}));
+vi.mock("../../lifecycle/observe", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/observe")>("../../lifecycle/observe");
+  return { carryAnnotations: actual.carryAnnotations, observeResources: (...a: unknown[]) => observeMock(...a) };
+});
 // `runGraphLive` resolves each component's `cfn-deploy` stack(s) (#57) so a
 // multi-stack, per-component project observes the right stacks; default to
 // "no components" (empty map, no errors) so the existing single-stack --live
@@ -544,6 +545,66 @@ describe("runGraph", () => {
       });
     });
 
+    // behold#919: a project that reads source it did not author (a workspace
+    // reader project, behold's scratch project for a bare Terraform folder)
+    // sets `graph.lint: "report"`, and a lint error is a finding about the
+    // estate, carried on meta.lint, not a reason to draw nothing.
+    describe('graph.lint: "report" (behold#919)', () => {
+      const finding = { file: "/abs/estate/db.tf", line: 4, column: 3, ruleId: "TF033", severity: "error", message: "[estate/aws_db_instance.orders] storage_encrypted is false", entity: "estate/aws_db_instance.orders" };
+      const warning = { file: "/abs/estate/net.tf", line: 9, column: 1, ruleId: "TF010", severity: "warning", message: "a warning" };
+      const reportMode = (): void => {
+        loadChantConfigUpwardMock.mockResolvedValue({ config: { graph: { lint: "report" } } });
+      };
+
+      test("emits the graph with lint errors, every finding on meta.lint", async () => {
+        reportMode(); discovered();
+        lintMock.mockResolvedValue({ success: false, diagnostics: [finding, warning] });
+        const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        const ir = JSON.parse(stdoutBuf.join("\n"));
+        expect(ir.nodes.map((n: { id: string }) => n.id).sort()).toEqual(["pod", "subnet", "vpc"]);
+        expect(ir.meta.lint).toEqual({
+          errors: 1,
+          warnings: 1,
+          findings: [
+            { ruleId: "TF033", severity: "error", message: "[estate/aws_db_instance.orders] storage_encrypted is false", file: "/abs/estate/db.tf", line: 4, column: 3, entity: "estate/aws_db_instance.orders" },
+            { ruleId: "TF010", severity: "warning", message: "a warning", file: "/abs/estate/net.tf", line: 9, column: 1 },
+          ],
+        });
+        expect(stderrBuf.join("\n")).toMatch(/with 1 lint error: graph\.lint is "report"/);
+      });
+
+      test("a clean read still carries meta.lint, so a reader can tell clean from not looked", async () => {
+        reportMode(); lintClean(); discovered();
+        const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        expect(JSON.parse(stdoutBuf.join("\n")).meta.lint).toEqual({ errors: 0, warnings: 0, findings: [] });
+      });
+
+      test("the default gate is unchanged, and adds no meta.lint", async () => {
+        lintClean(); discovered();
+        await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        expect(JSON.parse(stdoutBuf.join("\n")).meta?.lint).toBeUndefined();
+      });
+
+      test("an uninstalled dependency still refuses: there is no source to read", async () => {
+        const project = realpathSync(mkdtempSync(join(tmpdir(), "chant-919-graph-")));
+        try {
+          reportMode(); discovered();
+          lintMock.mockResolvedValue({
+            success: false,
+            diagnostics: [{ file: join(project, "a.ts"), line: 1, column: 1, ruleId: "LEX002", severity: "error", message: `Cannot find package '@intentius/chant-lexicon-aws' imported from ${join(project, "a.ts")}` }],
+          });
+          const exit = await runGraph({ args: makeArgs({ format: "ir", path: project }), plugins: [], serializers: [] });
+          expect(exit).toBe(1);
+          expect(stdoutBuf.join("\n")).toBe("");
+          expect(stderrBuf.join("\n")).toContain("dependencies not installed");
+        } finally {
+          rmSync(project, { recursive: true, force: true });
+        }
+      });
+    });
+
     test("--format mermaid emits a flowchart", async () => {
       lintClean(); discovered();
       const exit = await runGraph({ args: makeArgs({ format: "mermaid" }), plugins: [], serializers: [] });
@@ -872,6 +933,36 @@ describe("runGraph", () => {
       expect(out).toContain("web-vpc");
     });
 
+    // #4372 — a planned create is absent, and its plan attributes ride beside
+    // the verdict as annotations. `--overlay` puts them on the declared node,
+    // which keeps its pending paint: behold's plan cards read this IR.
+    test("--overlay carries an absent entity's annotations onto its declared node, still pending", async () => {
+      resolveLexMock.mockResolvedValue(["terraform"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "terraform", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverMock.mockResolvedValue({
+        entities: new Map([
+          ["app/terraform_data.created", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })],
+        ]),
+        errors: [],
+        sourceFiles: [],
+      });
+      observeMock.mockResolvedValue({
+        observations: [],
+        errors: [],
+        warnings: [],
+        annotations: { "app/terraform_data.created": { planAction: "create", planAfterUnknown: ["id"] } },
+      });
+      // `--detail 3`, as behold asks: lower tiers thin list attributes.
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", detail: 3 }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n")) as { nodes: Array<{ id: string; physicalId?: string; attrs: Record<string, unknown> }> };
+      const node = ir.nodes.find((n) => n.id === "app/terraform_data.created");
+      expect(node?.attrs).toMatchObject({ _status: "accent", planAction: "create", planAfterUnknown: ["id"] });
+      expect(node?.physicalId).toBeUndefined();
+    });
+
     // #2377 — the overlay carries the prediction. behold's reader takes
     // `attrs._behaviour` per node and `meta._behaviour` on the graph, and
     // reads the absence of both as "not looked" rather than as a refusal, so