@intentius/chant 0.27.0 → 0.28.0

package/src/kubectl-context.ts

@@ -0,0 +1,126 @@
+/**
+ * K8s environment→cluster binding — chant #1100.
+ *
+ * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group,
+ * Temporal looks up `temporal.profiles.<env>` in `chant.config.ts`. K8s (and
+ * GCP-via-Config-Connector, which observes through the same kubectl path)
+ * bound nothing — `describeResources` shelled out to `kubectl get` with no
+ * `--context`, so it read whatever cluster `kubectl config current-context`
+ * happened to point at. Point `prod` at a dev cluster and every declared
+ * resource reads as missing — a wrong-cluster diff that looks like a
+ * confident list of deletions.
+ *
+ * This module is the shared resolver both the k8s and gcp lexicons'
+ * `describeResources` call, so they resolve a cluster identity the same way
+ * (see `lexicons/k8s/src/config.ts`'s `K8sChantConfig` for the declared
+ * shape). It is intentionally provider-agnostic and lives in core (like
+ * `./ownership.ts`) rather than in the k8s lexicon package, since gcp's
+ * Config Connector observation needs it too without taking a dependency on
+ * the k8s lexicon.
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** A single environment's cluster binding — see `K8sChantConfig` in the k8s lexicon. */
+export interface K8sClusterProfile {
+  /** kubectl context name this environment is bound to. */
+  context: string;
+}
+
+/** Shape of the `k8s` passthrough key in `chant.config.ts` that this resolver reads. */
+export interface K8sConfigShape {
+  profiles?: Record<string, K8sClusterProfile>;
+}
+
+/**
+ * Thrown when an environment declares a cluster binding but the ambient
+ * kubectl context disagrees with it. Refusing here — instead of silently
+ * observing whichever cluster is ambient — is the fix for #1100: a
+ * wrong-cluster read reports every declared resource as missing, which #1089
+ * then classifies as a confident (and wrong) list of `create` actions.
+ */
+export class ClusterBindingMismatchError extends Error {
+  constructor(
+    public readonly environment: string,
+    public readonly expectedContext: string,
+    public readonly ambientContext: string,
+  ) {
+    super(
+      `k8s: environment "${environment}" is bound to cluster context "${expectedContext}" ` +
+        `(k8s.profiles.${environment}.context), but the ambient kubectl context is ` +
+        `"${ambientContext}". Refusing to observe — reading the wrong cluster would misreport ` +
+        `every declared resource as missing. Run \`kubectl config use-context ${expectedContext}\` ` +
+        `to switch, or update the binding in chant.config.ts if "${ambientContext}" is actually correct.`,
+    );
+    this.name = "ClusterBindingMismatchError";
+  }
+}
+
+export interface ResolvedClusterTarget {
+  /**
+   * Explicit `--context` value to pass to every kubectl invocation. Present
+   * only when the environment has a declared binding — undefined means
+   * "no binding, keep today's ambient-context behavior".
+   */
+  context?: string;
+  /** Where the target came from. */
+  source: "bound" | "ambient";
+}
+
+/** Reads `kubectl config current-context`. Returns undefined if unset or kubectl fails. */
+async function currentAmbientContext(): Promise<string | undefined> {
+  try {
+    const { stdout } = await execAsync("kubectl config current-context");
+    const trimmed = stdout.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the kubectl context an environment should be observed/applied
+ * against, reading `k8s.profiles.<environment>.context` from `chant.config.ts`
+ * (the `config` passed in is the passthrough `ChantConfig`, cast loosely since
+ * the `k8s` key isn't declared on the core schema — same pattern as
+ * `temporal.profiles`).
+ *
+ * - No binding declared: returns `{ source: "ambient" }` — unchanged
+ *   behavior — but logs a visible warning identifying the caller and
+ *   environment, so the fallback is never silent (#1100 acceptance).
+ * - Binding declared and the ambient context agrees (or ambient can't be
+ *   determined): returns `{ context: bound, source: "bound" }`. Callers
+ *   should pass this context explicitly on every kubectl invocation rather
+ *   than relying on it also being ambient.
+ * - Binding declared and the ambient context disagrees: throws
+ *   {@link ClusterBindingMismatchError} — a loud refusal instead of quietly
+ *   reading the wrong cluster.
+ */
+export async function resolveClusterTarget(
+  config: Record<string, unknown>,
+  environment: string,
+  lexiconName: string,
+): Promise<ResolvedClusterTarget> {
+  const k8sConfig = config.k8s as K8sConfigShape | undefined;
+  const bound = k8sConfig?.profiles?.[environment]?.context;
+
+  if (!bound) {
+    console.warn(
+      `[${lexiconName}] no cluster binding for environment "${environment}" ` +
+        `(k8s.profiles.${environment}.context in chant.config.ts) — observing whatever kubectl ` +
+        `context is ambient. Add a binding to pin this environment to a specific cluster (chant #1100).`,
+    );
+    return { source: "ambient" };
+  }
+
+  const ambient = await currentAmbientContext();
+  if (ambient && ambient !== bound) {
+    throw new ClusterBindingMismatchError(environment, bound, ambient);
+  }
+
+  return { context: bound, source: "bound" };
+}

package/src/lint/config.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { loadConfig, DEFAULT_CONFIG, findProjectRoot } from "./config";
+import { loadConfig, DEFAULT_CONFIG, findProjectRoot, resolveConfiguredSeverity, applyConfiguredSeverity } from "./config";
+import type { PostSynthDiagnostic } from "./post-synth";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join, resolve } from "path";
 
@@ -717,3 +718,94 @@ describe("findProjectRoot", () => {
     expect(findProjectRoot(sub)).toBe(packageRoot);
   });
 });
+
+/**
+ * chant #1138 — the one severity-resolution path AST lint rules
+ * (`../cli/commands/lint.ts`'s `getDefaultRules`), COMP* checks
+ * (`runComponentCheckDiagnostics`), and post-synth checks/policies
+ * (`applyConfiguredSeverity`, below) all now call, keyed by whichever id the
+ * caller has (a `LintRule.id`, a `ComponentCheck.id`, or a
+ * `PostSynthDiagnostic.checkId`) — a rule id behaves the same regardless of
+ * which phase produced it.
+ */
+describe("resolveConfiguredSeverity", () => {
+  test("an id with no config entry falls back to the caller's default severity, with no options", () => {
+    expect(resolveConfiguredSeverity(undefined, "COR001", "error")).toEqual({ severity: "error" });
+    expect(resolveConfiguredSeverity({}, "COR001", "warning")).toEqual({ severity: "warning" });
+    expect(resolveConfiguredSeverity({ OTHER: "off" }, "COR001", "error")).toEqual({ severity: "error" });
+  });
+
+  test("a bare severity string overrides the default", () => {
+    expect(resolveConfiguredSeverity({ COR001: "warning" }, "COR001", "error")).toEqual({ severity: "warning" });
+  });
+
+  test('"off" suppresses regardless of the default severity', () => {
+    expect(resolveConfiguredSeverity({ WAW019: "off" }, "WAW019", "error")).toEqual({ severity: "off" });
+  });
+
+  test("a [severity, options] tuple carries options through", () => {
+    expect(resolveConfiguredSeverity({ COR009: ["warning", { max: 12 }] }, "COR009", "error")).toEqual({
+      severity: "warning",
+      options: { max: 12 },
+    });
+  });
+
+  test("an invalid severity in a [severity, options] tuple throws, naming the bad value", () => {
+    expect(() =>
+      resolveConfiguredSeverity({ COR009: ["fatal" as never, { max: 12 }] }, "COR009", "error"),
+    ).toThrow(/severity "fatal"/);
+  });
+});
+
+/**
+ * chant #1138 — `lint.rules` severity overrides apply to a post-synth check
+ * id (`diag.checkId`) through the identical `resolveConfiguredSeverity` an
+ * AST rule id or a COMP* check id goes through, so
+ * `lint.rules: { WAW019: "off" }` suppresses a post-synth finding just like a
+ * pre-synth one — the bug this issue reports.
+ */
+describe("applyConfiguredSeverity", () => {
+  function diag(overrides: Partial<PostSynthDiagnostic> = {}): PostSynthDiagnostic {
+    return { checkId: "WAW019", severity: "error", message: "open ingress", ...overrides };
+  }
+
+  test("an unconfigured check id passes through unchanged — no drift for the common case", () => {
+    const result = applyConfiguredSeverity([diag()], undefined);
+    expect(result.diagnostics).toEqual([diag()]);
+    expect(result.suppressed).toEqual([]);
+  });
+
+  test('"off" suppresses the finding — moved to `suppressed`, not dropped, so it stays countable', () => {
+    const result = applyConfiguredSeverity([diag()], { WAW019: "off" });
+    expect(result.diagnostics).toEqual([]);
+    expect(result.suppressed).toEqual([diag()]);
+  });
+
+  test('"warning" downgrades an error-severity finding', () => {
+    const result = applyConfiguredSeverity([diag({ severity: "error" })], { WAW019: "warning" });
+    expect(result.diagnostics).toEqual([diag({ severity: "warning" })]);
+    expect(result.suppressed).toEqual([]);
+  });
+
+  test('"error" upgrades a warning-severity finding', () => {
+    const result = applyConfiguredSeverity([diag({ severity: "warning" })], { WAW019: "error" });
+    expect(result.diagnostics).toEqual([diag({ severity: "error" })]);
+  });
+
+  test("resolves each diagnostic by its own checkId — one config, independent ids", () => {
+    const diags = [
+      diag({ checkId: "WAW019" }),
+      diag({ checkId: "WAW049", message: "no logging" }),
+      diag({ checkId: "WAW099", message: "untouched" }),
+    ];
+    const result = applyConfiguredSeverity(diags, { WAW019: "off", WAW049: "warning" });
+    expect(result.suppressed.map((d) => d.checkId)).toEqual(["WAW019"]);
+    expect(result.diagnostics.map((d) => d.checkId)).toEqual(["WAW049", "WAW099"]);
+    expect(result.diagnostics.find((d) => d.checkId === "WAW049")?.severity).toBe("warning");
+    expect(result.diagnostics.find((d) => d.checkId === "WAW099")?.severity).toBe("error");
+  });
+
+  test("an empty diagnostics list is a no-op", () => {
+    expect(applyConfiguredSeverity([], { WAW019: "off" })).toEqual({ diagnostics: [], suppressed: [] });
+  });
+});

package/src/lint/config.ts

@@ -3,6 +3,7 @@ import { join, dirname, resolve } from "path";
 import { z } from "zod";
 import { evaluateProjectConfigSync } from "../config-sandbox";
 import type { Severity, RuleConfig } from "./rule";
+import type { PostSynthDiagnostic } from "./post-synth";
 import { moduleDir, getRuntime } from "../runtime-adapter";
 import strictPreset from "./presets/strict.json";
 
@@ -202,6 +203,40 @@ export function parseRuleConfig(value: RuleConfig): ParsedRuleConfig {
   return { severity, options };
 }
 
+/**
+ * Resolve one check/rule id's effective severity (and options) against an
+ * already-resolved `lint.rules` map — the ONE place `"off"`/severity-override
+ * resolution happens, so a rule id behaves identically regardless of which
+ * phase produced it.
+ *
+ * chant #1138 — before this, the same `lint.rules: { ID: "off" }` config was
+ * resolved by two independent call sites that had grown their own copy of
+ * this logic (`../cli/commands/lint.ts`'s `getDefaultRules` for AST COR/EVL
+ * rules, and its `runComponentCheckDiagnostics` for whole-component COMP*
+ * checks) — identical in effect, but a rule id's suppression having two
+ * places to (potentially, eventually) diverge is itself the bug class #1138
+ * is about. Both were converted to call this instead, and post-synth checks/
+ * policies (`./post-synth.ts`'s `applyConfiguredSeverity`) now go through it
+ * too, closing the gap the issue reports: a post-synth check id honors
+ * `lint.rules` exactly like an AST rule id does.
+ *
+ * `rules` takes the already-resolved map (`config.rules`, or
+ * `resolveRulesForFile`'s per-file merge) rather than a whole `LintConfig` —
+ * callers that need per-file `overrides` resolve that first; post-synth
+ * checks have no per-file scope to begin with (see {@link
+ * ./post-synth.ts!PostSynthDiagnostic}'s doc for why), so they always pass
+ * `config.rules` directly.
+ */
+export function resolveConfiguredSeverity(
+  rules: Record<string, RuleConfig> | undefined,
+  id: string,
+  defaultSeverity: Severity,
+): ParsedRuleConfig {
+  const configValue = rules?.[id];
+  if (configValue === undefined) return { severity: defaultSeverity };
+  return parseRuleConfig(configValue);
+}
+
 /**
  * Default configuration with all rules enabled at strict preset severities
  */
@@ -411,3 +446,76 @@ export function resolveRulesForFile(config: LintConfig, filePath: string): Recor
 
   return rules;
 }
+
+/** Result of applying `lint.rules` to a set of post-synth diagnostics. */
+export interface PostSynthSeverityResult {
+  /** Diagnostics after config resolution — `"off"`-suppressed ones removed, everything else at its resolved severity. */
+  diagnostics: PostSynthDiagnostic[];
+  /**
+   * Diagnostics `lint.rules` turned `"off"`, unaltered — present so a caller
+   * can report a count (chant #1138) rather than the finding simply
+   * vanishing, mirroring `../lint/engine.ts`'s `LintRunResult.suppressed` for
+   * AST rules.
+   */
+  suppressed: PostSynthDiagnostic[];
+}
+
+/**
+ * Apply `lint.rules` severity overrides to already-produced post-synth
+ * diagnostics — one lexicon-shipped check's findings, or one project's
+ * `lint.policies` findings, it doesn't matter which: both are plain
+ * `PostSynthDiagnostic[]` by the time they reach this function, so both go
+ * through the identical resolution an AST rule id or a COMP* check id gets
+ * (`resolveConfiguredSeverity`, above), keyed by `diag.checkId` instead of
+ * `LintRule.id`/`ComponentCheck.id`. `"off"` suppresses (moved to
+ * `suppressed`); any other configured severity replaces `diag.severity`,
+ * exactly as a config override changes an AST diagnostic's reported level.
+ *
+ * Lives here rather than in `./post-synth.ts` (where `PostSynthDiagnostic` is
+ * declared) on purpose: `post-synth.ts` is a leaf every lexicon's checks
+ * import as a real runtime module, and this file resolves built-in preset
+ * paths via the runtime adapter at module scope — pulling that into every
+ * lexicon's check barrel merely to share one filter function would be the
+ * wrong trade. Only this file's TYPE (`PostSynthDiagnostic`) crosses back,
+ * which costs nothing at runtime.
+ *
+ * chant #1138 — deliberately does NOT also honor `chant-disable` source
+ * comments. `PostSynthDiagnostic` has no source anchor to disable AT — see
+ * its doc comment (`./post-synth.ts`) for why `entity` doesn't supply one —
+ * so there is no coherent site to check for a directive. Even in the one case
+ * a real anchor sometimes exists (a live, in-process `ctx.entities` value
+ * stamped with build provenance, `../provenance.ts`'s `getProvenance`), it
+ * would not generalize: not every check sets `entity`, `entity` isn't
+ * guaranteed to be an entities-map key (it's a name in the synthesized
+ * OUTPUT — a CFN logical id, a k8s `metadata.name` — which a serializer is
+ * free to have derived, prefixed, or renamed from the source-level entity
+ * name), and that provenance never crosses the `--sandbox` policy child's
+ * JSON wire (`../discovery/entity-wire-codec.ts` doesn't carry it, and
+ * re-deriving it on the far side would mean sending source file paths into a
+ * channel that's supposed to carry only the resolved build). Building
+ * directive suppression on a sometimes-present, sometimes-not anchor would
+ * make `chant build` and `chant build --sandbox` disagree about the
+ * identical finding depending on which path happened to still have the
+ * entity object around — precisely the kind of inconsistency #1138 exists to
+ * remove. Config severity (`"off"`) is the one suppression surface this can
+ * offer uniformly; a check that wants a per-instance escape hatch can read
+ * `ctx.env`/its own options to decide not to emit a diagnostic at all.
+ */
+export function applyConfiguredSeverity(
+  diagnostics: readonly PostSynthDiagnostic[],
+  rules: Record<string, RuleConfig> | undefined,
+): PostSynthSeverityResult {
+  const kept: PostSynthDiagnostic[] = [];
+  const suppressed: PostSynthDiagnostic[] = [];
+
+  for (const diag of diagnostics) {
+    const resolved = resolveConfiguredSeverity(rules, diag.checkId, diag.severity);
+    if (resolved.severity === "off") {
+      suppressed.push(diag);
+      continue;
+    }
+    kept.push(resolved.severity === diag.severity ? diag : { ...diag, severity: resolved.severity });
+  }
+
+  return { diagnostics: kept, suppressed };
+}

package/src/lint/policy.test.ts

@@ -0,0 +1,90 @@
+/**
+ * chant #1138 — `evaluateProjectPolicies` (the `policyGate` Op step's entry
+ * point, ../../lexicons/temporal/src/op/activities/policy.ts) applies
+ * `lint.rules` severity overrides to policy diagnostics the same way `chant
+ * build` does (`../cli/commands/build.ts`), so a check `lint.rules` turns
+ * "off" no longer gates an apply either — before this fix, only `chant
+ * build`'s own error list was affected (and, before #1138, not even that).
+ *
+ * No lexicon is declared: the fixture project has no source files, so
+ * `resolveProjectLexicons` detects none and `build()` succeeds trivially with
+ * zero entities — the policy pack is the only thing under test.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { evaluateProjectPolicies } from "./policy";
+
+describe("evaluateProjectPolicies honors lint.rules (chant #1138)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-policy-eval-test-${Date.now()}-${Math.random()}`);
+    await mkdir(join(testDir, "policies"), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  async function writePolicyProject(checkId: string, severity: "error" | "warning", rules: Record<string, string>): Promise<void> {
+    await writeFile(
+      join(testDir, "policies", "org.ts"),
+      `export const check = {\n` +
+        `  id: ${JSON.stringify(checkId)},\n` +
+        `  description: "test policy",\n` +
+        `  check: () => [{ checkId: ${JSON.stringify(checkId)}, severity: ${JSON.stringify(severity)}, message: ${JSON.stringify(`${checkId} triggered`)} }],\n` +
+        `};\n`,
+    );
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      // `lexicons: ["k8s"]` avoids `resolveProjectLexicons`'s source-import
+      // auto-detection, which throws on a project with no lexicon-importing
+      // source file at all (this fixture has none — the policy pack is the
+      // only thing under test).
+      `export default { lexicons: ["k8s"], lint: { policies: ["policies/org.ts"], rules: ${JSON.stringify(rules)} } };\n`,
+    );
+  }
+
+  test('lint.rules "off" removes a check from violations and reports it as suppressed', async () => {
+    await writePolicyProject("ORG-OFF", "error", { "ORG-OFF": "off" });
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.violations).toEqual([]);
+    expect(evaluation.diagnostics).toEqual([]);
+    expect(evaluation.suppressed).toHaveLength(1);
+    expect(evaluation.suppressed[0].checkId).toBe("ORG-OFF");
+  });
+
+  test('lint.rules "warning" downgrades an error-severity check out of violations', async () => {
+    await writePolicyProject("ORG-DOWN", "error", { "ORG-DOWN": "warning" });
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.violations).toEqual([]);
+    expect(evaluation.diagnostics).toHaveLength(1);
+    expect(evaluation.diagnostics[0].severity).toBe("warning");
+    expect(evaluation.suppressed).toEqual([]);
+  });
+
+  test('lint.rules "error" upgrades a warning-severity check INTO violations', async () => {
+    await writePolicyProject("ORG-UP", "warning", { "ORG-UP": "error" });
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.violations).toHaveLength(1);
+    expect(evaluation.violations[0].checkId).toBe("ORG-UP");
+    expect(evaluation.violations[0].severity).toBe("error");
+  });
+
+  test("an unconfigured check id is unaffected — no drift for the common case", async () => {
+    await writePolicyProject("ORG-PLAIN", "error", {});
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.violations).toHaveLength(1);
+    expect(evaluation.suppressed).toEqual([]);
+  });
+});

package/src/lint/policy.ts

@@ -9,6 +9,7 @@ import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
 import { build } from "../build";
 import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
 import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import { applyConfiguredSeverity } from "./config";
 import { importPolicyModule, isSandboxPolicyExecutionArmed } from "./policy-import";
 
 /**
@@ -49,12 +50,18 @@ export async function loadPolicyChecks(paths: string[], configDir: string): Prom
 }
 
 export interface PolicyEvaluation {
-  /** All policy diagnostics (errors + warnings). */
+  /** All policy diagnostics (errors + warnings), after `lint.rules` severity overrides. */
   diagnostics: PostSynthDiagnostic[];
-  /** The error-severity subset — these are policy *violations* that gate. */
+  /** The error-severity subset (post-override) — these are policy *violations* that gate. */
   violations: PostSynthDiagnostic[];
   /** The environment policies were evaluated against (if any). */
   env?: string;
+  /**
+   * chant #1138 — diagnostics `lint.rules` turned `"off"`, present here rather
+   * than dropped so a caller (`policyGate`, below) can report a count instead
+   * of the finding just vanishing.
+   */
+  suppressed: PostSynthDiagnostic[];
 }
 
 /**
@@ -90,10 +97,15 @@ export async function evaluateProjectPolicies(opts: {
     ? await loadPolicyChecks(config.lint.policies, configDir)
     : [];
   if (checks.length === 0) {
-    return { diagnostics: [], violations: [], env };
+    return { diagnostics: [], violations: [], env, suppressed: [] };
   }
 
-  const diagnostics = runPostSynthChecks(checks, result, env);
+  const raw = runPostSynthChecks(checks, result, env);
+  // chant #1138 — same `lint.rules` resolution `chant build` applies
+  // (`../cli/commands/build.ts`), so a check `lint.rules` turned "off"/
+  // "warning" doesn't gate an apply here even though `chant build` no longer
+  // fails on it either, and vice versa for a check turned UP to "error".
+  const { diagnostics, suppressed } = applyConfiguredSeverity(raw, config.lint?.rules);
   const violations = diagnostics.filter((d) => d.severity === "error");
-  return { diagnostics, violations, env };
+  return { diagnostics, violations, env, suppressed };
 }

package/src/lint/post-synth.test.ts

@@ -141,3 +141,7 @@ describe("isPostSynthCheck", () => {
     expect(isPostSynthCheck("nope")).toBe(false);
   });
 });
+
+// chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
+// pass over `PostSynthDiagnostic`s) is tested in `./config.test.ts`, where the
+// function itself now lives — see `./config.ts`'s doc comment for why.

package/src/lint/post-synth.ts

@@ -35,6 +35,19 @@ export function getPrimaryOutput(output: string | SerializerResult): string {
 
 /**
  * A diagnostic from a post-synthesis check.
+ *
+ * chant #1138 — deliberately carries no `file`/`line` the way `LintDiagnostic`
+ * (`./rule.ts`) does. A post-synth check runs over `ctx.outputs` — the
+ * SYNTHESIZED output text (a CloudFormation template, a Kubernetes manifest) —
+ * not a `ts.SourceFile`, so there is no AST position to report in the first
+ * place. `entity` (below) is the closest thing to a locator and is NOT a
+ * substitute: it names a resource in that synthesized output (a CFN logical
+ * id, a k8s `metadata.name`), which several checks in this repo never even
+ * set (a cross-cutting check with no single implicated resource), and which
+ * is not guaranteed to match a `ctx.entities` map key. This is why source-
+ * comment (`chant-disable`) suppression is out of scope for post-synth
+ * findings — see `./config.ts`'s `applyConfiguredSeverity` doc for the full
+ * reasoning and what suppression surface post-synth findings get instead.
  */
 export interface PostSynthDiagnostic {
   /** ID of the check that produced this diagnostic */
@@ -43,7 +56,11 @@ export interface PostSynthDiagnostic {
   severity: Severity;
   /** Human-readable message */
   message: string;
-  /** Optional entity name related to this diagnostic */
+  /**
+   * Optional resource name related to this diagnostic — a name from the
+   * SYNTHESIZED OUTPUT (a CFN logical id, a k8s `metadata.name`), not a
+   * source file/line. See this interface's doc comment.
+   */
   entity?: string;
   /** Optional lexicon related to this diagnostic */
   lexicon?: string;
@@ -96,3 +113,15 @@ export function runPostSynthChecks(
   }
   return diagnostics;
 }
+
+// chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
+// pass over a set of `PostSynthDiagnostic`s) lives in `./config.ts`, not here,
+// even though it operates on this module's own type. This file is a leaf:
+// every lexicon's post-synth checks import it as a real runtime module (not
+// just for types — `getPrimaryOutput` above is a plain function several
+// checks call directly), so it has to stay cheap to load. `./config.ts` is
+// not cheap — it resolves built-in preset paths via the runtime adapter at
+// module scope — and pulling that into every lexicon's check barrel merely to
+// share one filter function is the wrong trade. `applyConfiguredSeverity`
+// only needs this module's TYPE (`PostSynthDiagnostic`), which costs nothing
+// at runtime, so the dependency runs the other way instead.

package/src/stack-output.test.ts

@@ -41,9 +41,9 @@ describe("stackOutput", () => {
     expect(out.description).toBe("Primary VPC id");
   });
 
-  test("throws for a value that is neither AttrRef-like nor an Intrinsic", () => {
-    expect(() => stackOutput("not-a-ref" as unknown as AttrRef)).toThrow(
-      "stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one",
+  test("throws for a value that is neither AttrRef-like, Intrinsic, nor a string literal", () => {
+    expect(() => stackOutput(42 as unknown as AttrRef)).toThrow(
+      "stackOutput(ref): ref must be an attribute reference, an intrinsic wrapping one, or a literal string",
     );
   });
 
@@ -116,3 +116,21 @@ describe("isStackOutput", () => {
     expect(isStackOutput(42)).toBe(false);
   });
 });
+
+describe("stackOutput export names and literals", () => {
+  test("carries exportName through to the declaration", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    const out = stackOutput(ref, { exportName: "my-stack-VpcId" });
+    expect(out.exportName).toBe("my-stack-VpcId");
+  });
+
+  test("accepts a literal string with an explicit lexicon", () => {
+    const out = stackOutput("22", { lexicon: "aws", exportName: "my-stack-OpenSSHPort" });
+    expect(out.sourceRef).toBe("22");
+    expect(out.lexicon).toBe("aws");
+  });
+
+  test("rejects a literal without a lexicon", () => {
+    expect(() => stackOutput("22")).toThrow(/options\.lexicon/);
+  });
+});

package/src/stack-output.ts

@@ -26,10 +26,13 @@ export interface StackOutput extends Declarable {
   readonly lexicon: string;
   readonly entityType: string;
   readonly kind: "output";
-  /** The exported value: a bare attribute reference, or an intrinsic wrapping
-   * one (e.g. `Join(",", zone.NameServers)`). */
-  readonly sourceRef: AttrRef | Intrinsic;
+  /** The exported value: a bare attribute reference, an intrinsic wrapping
+   * one (e.g. `Join(",", zone.NameServers)`), or a literal string. */
+  readonly sourceRef: AttrRef | Intrinsic | string;
   readonly description?: string;
+  /** When set, the serializer emits a cross-stack export under this name
+   * (CloudFormation `Output.Export.Name`) in addition to the plain output. */
+  readonly exportName?: string;
 }
 
 /** Find the first AttrRef anywhere inside a value (walking intrinsics/objects/
@@ -82,8 +85,8 @@ export function isStackOutput(value: unknown): value is StackOutput {
  * ```
  */
 export function stackOutput(
-  ref: AttrRef | Intrinsic,
-  options?: { description?: string },
+  ref: AttrRef | Intrinsic | string,
+  options?: { description?: string; exportName?: string; lexicon?: string },
 ): StackOutput {
   // Duck-type, not `instanceof` (chant #1137): AttrRef also implements
   // Intrinsic (a global-symbol marker), so `isIntrinsic(ref)` alone already
@@ -92,19 +95,27 @@ export function stackOutput(
   // so the guard's own logic states the invariant explicitly ("ref must be
   // AttrRef-like or Intrinsic") rather than relying on that coincidence,
   // matching the anchor selection right below it, which does misbehave.
-  if (!isAttrRefLike(ref) && !isIntrinsic(ref)) {
-    throw new Error("stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one");
+  if (typeof ref !== "string" && !isAttrRefLike(ref) && !isIntrinsic(ref)) {
+    throw new Error(
+      "stackOutput(ref): ref must be an attribute reference, an intrinsic wrapping one, or a literal string",
+    );
+  }
+  if (typeof ref === "string" && !options?.lexicon) {
+    throw new Error(
+      "stackOutput(literal): a literal output has no entity to derive its lexicon from — pass options.lexicon",
+    );
   }
   // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
   // for an intrinsic (Join etc.), the first AttrRef nested inside it. A
   // foreign-copy AttrRef failing raw `instanceof` here would fall to
   // `firstAttrRef`, which (before its own #1137 fix) would also miss it —
   // silently anchoring on nothing and recording `lexicon: "unknown"`.
-  const anchor = isAttrRefLike(ref) ? ref : firstAttrRef(ref);
+  const anchor = typeof ref === "string" ? undefined : isAttrRefLike(ref) ? ref : firstAttrRef(ref);
   const parent = anchor?.parent.deref();
-  const lexicon = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
+  const derived = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
     ? (parent as Record<string, unknown>).lexicon as string
     : "unknown";
+  const lexicon = options?.lexicon ?? derived;
 
   const output: StackOutput = {
     [STACK_OUTPUT_MARKER]: true,
@@ -114,6 +125,7 @@ export function stackOutput(
     kind: "output",
     sourceRef: ref,
     description: options?.description,
+    exportName: options?.exportName,
   };
 
   return output;