@intentius/chant 0.26.0 → 0.28.0

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;