@intentius/chant 0.27.0 → 0.28.0

package/src/cli/commands/build.ts

@@ -4,6 +4,7 @@ import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
+import { applyConfiguredSeverity } from "../../lint/config";
 import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
 import { sortedJsonReplacer } from "../../utils";
@@ -282,6 +283,16 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   }
 
   // Run post-synth checks from plugins — each plugin only sees its own lexicon's output
+  //
+  // chant #1138 — every diagnostic collected below (a lexicon-shipped check's
+  // AND a project's `lint.policies`') is resolved against `lint.rules` before
+  // it becomes an error/warning line, through the exact same
+  // `applyConfiguredSeverity` (../../lint/post-synth.ts) that keys off
+  // `diag.checkId` the way `lintCommand` keys an AST/COMP* diagnostic off its
+  // rule id — so `lint.rules: { WAW019: "off" }` suppresses a post-synth
+  // finding just as it suppresses a pre-synth one. A finding it suppresses is
+  // counted, not dropped silently — see `suppressedPostSynthCount` below.
+  let suppressedPostSynthCount = 0;
   if (result.errors.length === 0 && options.plugins) {
     for (const plugin of options.plugins) {
       if (!plugin.postSynthChecks) continue;
@@ -301,7 +312,9 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
 
       const scopedResult = { ...result, outputs: scopedOutputs };
       const postDiags = runPostSynthChecks(checks, scopedResult, env);
-      for (const diag of postDiags) {
+      const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(postDiags, config.lint?.rules);
+      suppressedPostSynthCount += suppressed.length;
+      for (const diag of activeDiags) {
         const prefix = diag.entity ? `[${diag.entity}] ` : "";
         const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
         if (diag.severity === "error") {
@@ -321,6 +334,15 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     // result to a post-merge sandboxed child, which imports the policy modules
     // and runs their checks there, and only plain `PostSynthDiagnostic`s come
     // back. Unsandboxed, it is the same in-process load-and-run as before.
+    //
+    // #1138 — `applyConfiguredSeverity` runs HERE, in the parent, after the
+    // sandboxed child (when armed) has already returned — never inside it.
+    // The child only knows the policy paths and the encoded build result, not
+    // this project's resolved `lint.rules`, and by design nothing about the
+    // suppression surface needs to cross that boundary: both the plain and
+    // the `--sandbox` path funnel through this identical call with the
+    // identical `config.lint?.rules`, so a sandboxed and an unsandboxed build
+    // of the same project apply the same config to the same diagnostics.
     if (policies.length > 0) {
       const policyDiags = await runProjectPolicies({
         policies,
@@ -329,7 +351,9 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
         env,
         preloaded: preloadedPolicyChecks,
       });
-      for (const diag of policyDiags) {
+      const { diagnostics: activePolicyDiags, suppressed } = applyConfiguredSeverity(policyDiags, config.lint?.rules);
+      suppressedPostSynthCount += suppressed.length;
+      for (const diag of activePolicyDiags) {
         const prefix = diag.entity ? `[${diag.entity}] ` : "";
         const where = diag.lexicon ? ` (${diag.lexicon})` : "";
         const msg = `[policy:${diag.checkId}] ${prefix}${diag.message}${where}`;
@@ -337,6 +361,14 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
         else warnings.push(formatWarning({ message: msg }));
       }
     }
+
+    if (suppressedPostSynthCount > 0) {
+      warnings.push(
+        formatWarning({
+          message: `${suppressedPostSynthCount} post-synth finding(s) suppressed via lint.rules (severity "off")`,
+        }),
+      );
+    }
   }
 
   // Empty-output guard: source files were discovered but no lexicon produced

package/src/cli/commands/lint.ts

@@ -18,8 +18,7 @@ import { formatError, formatInfo } from "../format";
 import { GENERATED_MARKER } from "../../discovery/files";
 
 // Import config loader
-import { loadConfig, resolveRulesForFile, parseRuleConfig, findProjectRoot } from "../../lint/config";
-import type { RuleConfig } from "../../lint/rule";
+import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -263,28 +262,22 @@ function getDefaultRules(
   const ruleOptions = new Map<string, Record<string, unknown>>();
 
   for (const [ruleId, rule] of allRules) {
-    const configValue: RuleConfig | undefined = effectiveRules?.[ruleId];
-
-    if (configValue === undefined) {
-      // Rule not mentioned in config — include with default severity
-      rules.push(rule);
-      continue;
-    }
-
-    const parsed = parseRuleConfig(configValue);
+    // chant #1138 — the same resolution post-synth checks and COMP* checks
+    // now go through too (`resolveConfiguredSeverity`, ../../lint/config.ts),
+    // so `lint.rules: { ID: "off" }` suppresses a rule id identically no
+    // matter which phase produced it.
+    const { severity, options } = resolveConfiguredSeverity(effectiveRules, ruleId, rule.severity);
 
     // Skip rules that are explicitly turned off
-    if (parsed.severity === "off") continue;
+    if (severity === "off") continue;
 
-    // Override severity from config
-    rules.push({
-      ...rule,
-      severity: parsed.severity as "error" | "warning" | "info",
-    });
+    // Override severity from config (a no-op when the rule wasn't mentioned —
+    // `severity` is then just `rule.severity` again)
+    rules.push({ ...rule, severity });
 
     // Store options if present
-    if (parsed.options) {
-      ruleOptions.set(ruleId, parsed.options);
+    if (options) {
+      ruleOptions.set(ruleId, options);
     }
   }
 
@@ -394,12 +387,11 @@ async function runComponentCheckDiagnostics(
     // Discovery errors (COMP000) always surface at error severity — not user-configurable.
     let severity = d.severity;
     if (d.checkId !== "COMP000") {
-      const configValue = config.rules?.[d.checkId];
-      if (configValue !== undefined) {
-        const parsed = parseRuleConfig(configValue);
-        if (parsed.severity === "off") continue;
-        severity = parsed.severity;
-      }
+      // chant #1138 — same resolution function AST rules and post-synth
+      // checks use (`resolveConfiguredSeverity`, ../../lint/config.ts).
+      const resolved = resolveConfiguredSeverity(config.rules, d.checkId, d.severity);
+      if (resolved.severity === "off") continue;
+      severity = resolved.severity;
     }
 
     const disable = fileLevelDisable(d.file, d.checkId);

package/src/discovery/sandbox/config-boundary.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -236,4 +236,58 @@ describe("chant.config.ts evaluation under --sandbox (chant #1113)", () => {
     );
     expect(marker()).toBeUndefined();
   });
+
+  /**
+   * chant #1148 — `chant.config.ts`'s own `console.log`/`console.error` used
+   * to go nowhere under `--sandbox`. Same relay as the run-fallback child
+   * (`./run.test.ts`), just this child's own prefix.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // See ./run.test.ts's identical helper doc: the IPC "message" the awaited
+    // call resolves on and the child's stdout/stderr pipe data are
+    // independent channels, so polling briefly avoids a flaky assertion.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("the config's own console.log/console.error are forwarded, prefixed with [sandbox:config]", async () => {
+      const stderr = captureStderr();
+      await writeFile(
+        join(testDir, "chant.config.ts"),
+        `console.log("hello from config stdout");\n` +
+          `console.error("hello from config stderr");\n` +
+          `export default { lexicons: ["aws"] };\n`,
+      );
+      armSandboxConfigEvaluation();
+
+      const { config } = await loadChantConfig(testDir);
+
+      expect(config.lexicons).toEqual(["aws"]);
+      await waitFor(stderr, /^\[sandbox:config\] hello from config stdout$/m);
+      await waitFor(stderr, /^\[sandbox:config\] hello from config stderr$/m);
+    });
+  });
 });

package/src/discovery/sandbox/config-run.ts

@@ -108,6 +108,9 @@ export async function evaluateConfigSandboxed(
         env,
         timeoutMs: CONFIG_CHILD_TIMEOUT_MS,
         label: `sandboxed evaluation of ${configPath}`,
+        // chant #1148 — the config's own console.log/error no longer goes
+        // nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: "[sandbox:config]",
       },
       isConfigChildResponse,
     );

package/src/discovery/sandbox/fork.ts

@@ -11,6 +11,11 @@ import { fork } from "node:child_process";
  * one function is the cheapest way to make "same profile" a fact rather than
  * a claim.
  *
+ * chant #1148 — this is also the one place chant forwards a sandboxed
+ * child's own stdout/stderr, so `./run.ts`, `./config-run.ts` and
+ * `./policy-run.ts` cannot drift on whether project output vanishes. See
+ * {@link SandboxForkOptions.outputPrefix}.
+ *
  * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
  * description for the full write-up):
  *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
@@ -45,6 +50,26 @@ export interface SandboxForkOptions {
   timeoutMs: number;
   /** What timed out / exited early, for the error message (e.g. `"sandboxed run"`). */
   label: string;
+  /**
+   * chant #1148 — prepended to every line the child writes on EITHER stdout
+   * or stderr before it is relayed, line-buffered, to this process's own
+   * stderr (e.g. `"[sandbox:run]"`, `"[sandbox:config]"`,
+   * `"[policy:org.ts]"`).
+   *
+   * A sandboxed child's `console.log`/`console.error` used to go nowhere: its
+   * stdout was piped but never read, and its stderr was captured only into
+   * {@link stderrBuf}'s error-message use, never surfaced on a successful
+   * run. Diagnostics crossing as data (the whole point of the boundary) is
+   * not the same thing as incidental output being silently dropped — chant's
+   * stance is that nothing the project prints vanishes, sandboxed or not.
+   *
+   * This is forwarding, not a second capture: {@link stderrBuf} still
+   * accumulates the child's raw stderr for `classifyChildError`/the
+   * exited-before-reporting message exactly as before. Both read the same
+   * `data` events; one buffers for classification, this one relays for a
+   * human to see.
+   */
+  outputPrefix: string;
   /**
    * chant #1131 — an optional payload sent to the child over the SAME IPC
    * channel its response comes back on, immediately after the fork.
@@ -65,6 +90,36 @@ export interface SandboxForkOptions {
   send?: Record<string, unknown>;
 }
 
+/**
+ * chant #1148 — buffers arbitrary chunks and calls `emit` once per complete
+ * line, never on a chunk boundary that happens to split a line in two (a
+ * pipe makes no promise that one `write()` on the child's side arrives as one
+ * `data` event on ours). `flush()` emits whatever partial line never got a
+ * trailing newline, so the last unterminated write doesn't silently vanish
+ * when the stream ends — the same no-dropping stance this whole feature
+ * exists for.
+ */
+function lineBuffered(emit: (line: string) => void) {
+  let pending = "";
+  return {
+    push(chunk: Buffer | string): void {
+      pending += chunk.toString();
+      let newlineAt = pending.indexOf("\n");
+      while (newlineAt !== -1) {
+        emit(pending.slice(0, newlineAt));
+        pending = pending.slice(newlineAt + 1);
+        newlineAt = pending.indexOf("\n");
+      }
+    },
+    flush(): void {
+      if (pending.length > 0) {
+        emit(pending);
+        pending = "";
+      }
+    },
+  };
+}
+
 /**
  * Fork `bundlePath` under `--permission` with a scrubbed environment, and
  * resolve with the first IPC message that satisfies `isResponse` (or reject
@@ -74,7 +129,8 @@ export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
 ): Promise<T> {
-  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send } = options;
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send, outputPrefix } =
+    options;
 
   return new Promise((resolvePromise, reject) => {
     const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
@@ -106,9 +162,27 @@ export function forkSandboxed<T>(
       });
     }
 
+    // chant #1148 — forward, don't just capture. Both streams write to THIS
+    // process's stderr, prefixed and line-buffered, independent of
+    // `stderrBuf` below (which keeps accumulating raw stderr for
+    // `classifyChildError`'s use — forwarded and captured are not mutually
+    // exclusive, the same bytes feed both).
+    const forwardLine = (line: string): void => {
+      process.stderr.write(`${outputPrefix} ${line}\n`);
+    };
+    const stdoutForwarder = lineBuffered(forwardLine);
+    const stderrForwarder = lineBuffered(forwardLine);
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutForwarder.push(chunk);
+    });
+    child.stdout?.on("end", () => stdoutForwarder.flush());
+
     child.stderr?.on("data", (chunk: Buffer) => {
       stderrBuf += chunk.toString();
+      stderrForwarder.push(chunk);
     });
+    child.stderr?.on("end", () => stderrForwarder.flush());
 
     child.on("message", (msg: unknown) => {
       if (settled || !isResponse(msg)) return;

package/src/discovery/sandbox/policy-boundary.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -281,6 +281,61 @@ describe("lint.policies execution under --sandbox (chant #1131)", () => {
     expect(await run([])).toEqual([]);
   });
 
+  /**
+   * chant #1148 — a policy's own `console.log`/`console.error` used to go
+   * nowhere under `--sandbox` (noted as a residual when #1131 shipped). Same
+   * relay as the run-fallback and config children, keyed to the policy
+   * module's own basename rather than a generic tag.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // See ./run.test.ts's identical helper doc: the IPC "message" the
+    // awaited call resolves on and the child's stdout/stderr pipe data are
+    // independent channels, so polling briefly avoids a flaky assertion.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("a policy's console.log/console.error are forwarded, prefixed with [policy:<module-basename>]", async () => {
+      const stderr = captureStderr();
+      await writeMarkerPolicy(
+        "org.ts",
+        `console.log("hello from policy stdout");\n` +
+          `console.error("hello from policy stderr");\n` +
+          `export const c = { id: "X", description: "d", check: () => [] };\n`,
+      );
+      armSandboxPolicyExecution();
+
+      const diags = await run(["org.ts"]);
+
+      expect(diags).toEqual([]);
+      await waitFor(stderr, /^\[policy:org\.ts\] hello from policy stdout$/m);
+      await waitFor(stderr, /^\[policy:org\.ts\] hello from policy stderr$/m);
+    });
+  });
+
   test("a program that runs a policy child EXITS — the child is not left holding the event loop", async () => {
     // Found the hard way while measuring #1131's cost: unlike the run and
     // config drivers, the policy driver keeps a `message` listener registered

package/src/discovery/sandbox/policy-run.ts

@@ -1,5 +1,5 @@
 import { realpathSync, rmSync } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import type { PostSynthDiagnostic } from "../../lint/post-synth";
 import { bundleDriver } from "./bundle";
 import { generatePolicyDriverSource } from "./driver";
@@ -79,6 +79,17 @@ interface PolicyChildResponse {
   error?: { name: string; file: string; message: string; type: string };
 }
 
+/**
+ * chant #1148 — `[policy:<module-basename>]`, joined when a project declares
+ * more than one policy module (all of them share the one child — see the
+ * module doc above). One policy module is the only shape this repo's own
+ * corpus exercises (`lexicons/k8s/examples/org-policy`), so this is the
+ * common case, not a hypothetical.
+ */
+function policyOutputPrefix(policyPaths: readonly string[]): string {
+  return `[policy:${policyPaths.map((p) => basename(p)).join(",")}]`;
+}
+
 function isPolicyChildResponse(value: unknown): value is PolicyChildResponse {
   return (
     typeof value === "object" &&
@@ -158,6 +169,9 @@ export async function runPoliciesSandboxed(options: SandboxPolicyOptions): Promi
         timeoutMs: POLICY_CHILD_TIMEOUT_MS,
         label: `sandboxed evaluation of lint.policies (${policyPaths.length} module(s))`,
         send: payload,
+        // chant #1148 — a policy's own console.log/error no longer goes
+        // nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: policyOutputPrefix(policyPaths),
       },
       isPolicyChildResponse,
     );

package/src/discovery/sandbox/run.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -176,4 +176,88 @@ describe("runFallbackFilesSandboxed — isolation", () => {
     expect(ref.getLogicalName?.()).toBe("dataBucket");
     expect(ref.attribute).toBe("Arn");
   });
+
+  /**
+   * chant #1148 — a run-fallback file's own `console.log`/`console.error`
+   * used to go nowhere: the child's stdout was piped but never read, and its
+   * stderr was captured only for `classifyChildError`'s use, never surfaced
+   * on a successful run. `./fork.ts` now relays both, line-buffered and
+   * prefixed, to THIS process's stderr — diagnostics crossing as data was
+   * never meant to mean incidental output vanishes.
+   */
+  describe("console output forwarding (chant #1148)", () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    /** Spies on `process.stderr.write` and returns the lines captured so far — same shape as `../../cli/handlers/emulator.test.ts`'s `stdout()`/`stderr()` helpers. */
+    function captureStderr(): string[] {
+      const lines: string[] = [];
+      vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+        lines.push(String(chunk));
+        return true;
+      });
+      return lines;
+    }
+
+    // The child's IPC "message" (what the awaited call resolves on) and its
+    // stdout/stderr pipe data are two independent channels — nothing orders
+    // one ahead of the other, and #1147 deliberately keeps it that way (see
+    // the hang-regression test in policy-boundary.test.ts). Polling briefly
+    // rather than asserting immediately avoids a flaky test without giving
+    // the production path anything to wait for.
+    async function waitFor(lines: string[], matcher: RegExp, timeoutMs = 5000): Promise<void> {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (matcher.test(lines.join(""))) return;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`stderr never matched ${matcher}. Captured so far:\n${lines.join("")}`);
+    }
+
+    test("both console.log and console.error are forwarded, prefixed with [sandbox:run]", async () => {
+      const stderr = captureStderr();
+      const file = join(testDir, "noisy.ts");
+      await writeFile(
+        file,
+        `
+          console.log("hello from run-fallback stdout");
+          console.error("hello from run-fallback stderr");
+          export const value = "ok";
+        `,
+      );
+
+      const result = await runFallbackFilesSandboxed([file], testDir);
+
+      expect(result.errors).toEqual([]);
+      await waitFor(stderr, /^\[sandbox:run\] hello from run-fallback stdout$/m);
+      await waitFor(stderr, /^\[sandbox:run\] hello from run-fallback stderr$/m);
+    });
+
+    test("a file that exits hard still has its stderr in the classified error (forwarding doesn't replace capture)", async () => {
+      const stderr = captureStderr();
+      const file = join(testDir, "crashes.ts");
+      await writeFile(
+        file,
+        `
+          console.error("about to exit hard");
+          process.exit(1);
+        `,
+      );
+
+      const result = await runFallbackFilesSandboxed([file], testDir);
+
+      // A hard process.exit() takes the whole bundled child with it — this is
+      // fork.ts's pre-existing "child exited before reporting results" path,
+      // fed by the SAME stderrBuf that now also feeds forwarding.
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].message).toMatch(/about to exit hard/);
+
+      await waitFor(stderr, /^\[sandbox:run\] about to exit hard$/m);
+    });
+  });
 });

package/src/discovery/sandbox/run.ts

@@ -112,6 +112,9 @@ export async function runFallbackFilesSandboxed(
         env: { PATH: process.env.PATH ?? "" },
         timeoutMs: CHILD_TIMEOUT_MS,
         label: "sandboxed run",
+        // chant #1148 — a run-fallback file's own console.log/error no
+        // longer goes nowhere; see `./fork.ts`'s `outputPrefix` doc.
+        outputPrefix: "[sandbox:run]",
       },
       isChildResponse,
     );

package/src/kubectl-context.test.ts

@@ -0,0 +1,94 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
+      Promise.resolve(execMock(cmd)).then(
+        (out) => cb(null, out as { stdout: string; stderr: string }),
+        (err) => cb(err as Error, { stdout: "", stderr: "" }),
+      );
+    },
+  };
+});
+
+const { resolveClusterTarget, ClusterBindingMismatchError } = await import("./kubectl-context");
+
+describe("resolveClusterTarget (chant #1100)", () => {
+  beforeEach(() => {
+    execMock.mockReset();
+  });
+
+  test("no binding declared: returns ambient source, warns visibly, never probes kubectl", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const target = await resolveClusterTarget({}, "prod", "k8s");
+
+    expect(target).toEqual({ source: "ambient" });
+    expect(execMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringMatching(/\[k8s\].*environment "prod".*k8s\.profiles\.prod\.context/s),
+    );
+    warnSpy.mockRestore();
+  });
+
+  test("bound and ambient context matches: returns the bound context", async () => {
+    execMock.mockResolvedValue({ stdout: "prod-eks\n", stderr: "" });
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ context: "prod-eks", source: "bound" });
+    expect(execMock).toHaveBeenCalledWith(expect.stringContaining("current-context"));
+  });
+
+  test("bound and ambient context cannot be determined: proceeds with the bound context anyway", async () => {
+    execMock.mockRejectedValue(new Error("no kubeconfig"));
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ context: "prod-eks", source: "bound" });
+  });
+
+  test("bound and ambient context mismatches: refuses loudly, naming env/expected/ambient", async () => {
+    execMock.mockResolvedValue({ stdout: "staging-eks\n", stderr: "" });
+
+    const err: unknown = await resolveClusterTarget(
+      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
+      "prod",
+      "k8s",
+    ).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(ClusterBindingMismatchError);
+    const mismatch = err as InstanceType<typeof ClusterBindingMismatchError>;
+    expect(mismatch.environment).toBe("prod");
+    expect(mismatch.expectedContext).toBe("prod-eks");
+    expect(mismatch.ambientContext).toBe("staging-eks");
+    expect(mismatch.message).toContain('environment "prod"');
+    expect(mismatch.message).toContain('"prod-eks"');
+    expect(mismatch.message).toContain('"staging-eks"');
+  });
+
+  test("bound for a different environment than the one requested: treated as unbound for this environment", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const target = await resolveClusterTarget(
+      { k8s: { profiles: { staging: { context: "staging-eks" } } } },
+      "prod",
+      "k8s",
+    );
+
+    expect(target).toEqual({ source: "ambient" });
+    expect(execMock).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});