@intentius/chant 0.57.0 → 0.58.0

package/src/lint/suppressions.test.ts

@@ -0,0 +1,163 @@
+import { describe, test, expect } from "vitest";
+import {
+  applyInlineSuppressions,
+  entitySuppressions,
+  SUPPRESSION_EXPIRED_ID,
+  SUPPRESSION_MISPLACED_FILE_ID,
+  SUPPRESSION_UNIGNORABLE_ID,
+  type SuppressionDirective,
+} from "./suppressions";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+import type { PostSynthDiagnostic } from "./post-synth";
+import type { RuleConfig } from "./rule";
+
+/** A minimal `Declarable` carrying the duck-typed `suppressions` field this module reads. */
+function entityWith(directives?: SuppressionDirective[]): Declarable {
+  return {
+    [DECLARABLE_MARKER]: true,
+    lexicon: "fake",
+    entityType: "Fake::Thing",
+    suppressions: directives,
+  } as unknown as Declarable;
+}
+
+let seq = 0;
+function directive(partial: Partial<SuppressionDirective> & Pick<SuppressionDirective, "form">): SuppressionDirective {
+  seq += 1;
+  return { ids: "all", file: "main.tf", line: 1, key: `key-${seq}`, ...partial };
+}
+
+function diag(checkId: string, entityKey?: string): PostSynthDiagnostic {
+  return { checkId, severity: "warning", message: `${checkId} fired`, entity: entityKey, lexicon: "fake" };
+}
+
+describe("entitySuppressions", () => {
+  test("returns [] for an entity with no suppressions field", () => {
+    expect(entitySuppressions(entityWith(undefined))).toEqual([]);
+  });
+
+  test("returns [] for undefined", () => {
+    expect(entitySuppressions(undefined)).toEqual([]);
+  });
+
+  test("returns the directives array when present", () => {
+    const d = directive({ form: "chant-ignore" });
+    expect(entitySuppressions(entityWith([d]))).toEqual([d]);
+  });
+});
+
+describe("applyInlineSuppressions", () => {
+  test("a directive naming the checkId explicitly suppresses it", () => {
+    const d = directive({ form: "chant-ignore", ids: new Set(["TF010"]) });
+    const entities = new Map([["e1", entityWith([d])]]);
+    const { diagnostics, suppressed } = applyInlineSuppressions([diag("TF010", "e1")], entities);
+    expect(diagnostics).toHaveLength(0);
+    expect(suppressed).toHaveLength(1);
+  });
+
+  test("a directive naming a different id does not suppress", () => {
+    const d = directive({ form: "chant-ignore", ids: new Set(["TF010"]) });
+    const entities = new Map([["e1", entityWith([d])]]);
+    const { diagnostics, suppressed } = applyInlineSuppressions([diag("TF011", "e1")], entities);
+    expect(diagnostics).toHaveLength(1);
+    expect(suppressed).toHaveLength(0);
+  });
+
+  test('"all" suppresses every rule id on the entity it anchors to', () => {
+    const d = directive({ form: "chant-ignore-block", ids: "all" });
+    const entities = new Map([["e1", entityWith([d])]]);
+    const { diagnostics, suppressed } = applyInlineSuppressions([diag("TF001", "e1"), diag("TF999", "e1")], entities);
+    expect(diagnostics).toHaveLength(0);
+    expect(suppressed).toHaveLength(2);
+  });
+
+  test("a diagnostic with no entity is never suppressed (nothing to look up)", () => {
+    const d = directive({ form: "chant-ignore", ids: "all" });
+    const entities = new Map([["e1", entityWith([d])]]);
+    const { diagnostics } = applyInlineSuppressions([diag("TF001", undefined)], entities);
+    expect(diagnostics).toHaveLength(1);
+  });
+
+  test("a diagnostic whose entity carries no directives is unaffected", () => {
+    const entities = new Map([["e1", entityWith(undefined)]]);
+    const { diagnostics, suppressed } = applyInlineSuppressions([diag("TF001", "e1")], entities);
+    expect(diagnostics).toHaveLength(1);
+    expect(suppressed).toHaveLength(0);
+  });
+
+  describe("expiry", () => {
+    test("an expired directive no longer suppresses, and is reported once as its own finding", () => {
+      const d = directive({ form: "chant-ignore", ids: "all", expires: "2020-01-01", file: "main.tf", line: 4 });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed, meta } = applyInlineSuppressions([diag("TF001", "e1")], entities, undefined, new Date("2026-01-01"));
+      expect(diagnostics).toHaveLength(1); // not suppressed: the finding still fires
+      expect(suppressed).toHaveLength(0);
+      expect(meta).toHaveLength(1);
+      expect(meta[0].checkId).toBe(SUPPRESSION_EXPIRED_ID);
+      expect(meta[0].file).toBe("main.tf");
+      expect(meta[0].line).toBe(4);
+    });
+
+    test("a not-yet-expired directive still suppresses normally", () => {
+      const d = directive({ form: "chant-ignore", ids: "all", expires: "2099-01-01" });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed, meta } = applyInlineSuppressions([diag("TF001", "e1")], entities, undefined, new Date("2026-01-01"));
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+      expect(meta).toHaveLength(0);
+    });
+
+    test("an expired directive attached to several entities is reported once, not once per entity", () => {
+      const d = directive({ form: "chant-ignore-file", ids: "all", expires: "2020-01-01", file: "main.tf", line: 1 });
+      const entities = new Map([
+        ["e1", entityWith([d])],
+        ["e2", entityWith([d])],
+      ]);
+      const { meta } = applyInlineSuppressions([diag("TF001", "e1"), diag("TF002", "e2")], entities, undefined, new Date("2026-01-01"));
+      expect(meta).toHaveLength(1);
+    });
+  });
+
+  describe("a misplaced chant-ignore-file directive", () => {
+    test("has no suppressing effect and is reported once as its own finding", () => {
+      const d = directive({ form: "chant-ignore-file", ids: "all", misplaced: true, file: "main.tf", line: 3 });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed, meta } = applyInlineSuppressions([diag("TF001", "e1")], entities);
+      expect(diagnostics).toHaveLength(1);
+      expect(suppressed).toHaveLength(0);
+      expect(meta).toHaveLength(1);
+      expect(meta[0].checkId).toBe(SUPPRESSION_MISPLACED_FILE_ID);
+      expect(meta[0].line).toBe(3);
+    });
+  });
+
+  describe("ignorable: false", () => {
+    const rules: Record<string, RuleConfig> = { TF008: ["error", { ignorable: false }] };
+
+    test("a directive explicitly naming an unignorable id does not suppress it, and is itself reported", () => {
+      const d = directive({ form: "chant-ignore", ids: new Set(["TF008"]) });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed, meta } = applyInlineSuppressions([diag("TF008", "e1")], entities, rules);
+      expect(diagnostics).toHaveLength(1);
+      expect(suppressed).toHaveLength(0);
+      expect(meta.map((m) => m.checkId)).toEqual([SUPPRESSION_UNIGNORABLE_ID]);
+    });
+
+    test("an unconfigured id is ignorable by default", () => {
+      const d = directive({ form: "chant-ignore", ids: new Set(["TF001"]) });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed, meta } = applyInlineSuppressions([diag("TF001", "e1")], entities, rules);
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+      expect(meta).toHaveLength(0);
+    });
+
+    test("a directive covering a different, ignorable id in the same set still suppresses that one", () => {
+      const d = directive({ form: "chant-ignore", ids: new Set(["TF008", "TF010"]) });
+      const entities = new Map([["e1", entityWith([d])]]);
+      const { diagnostics, suppressed } = applyInlineSuppressions([diag("TF010", "e1")], entities, rules);
+      expect(diagnostics).toHaveLength(0);
+      expect(suppressed).toHaveLength(1);
+    });
+  });
+});

package/src/lint/suppressions.ts

@@ -0,0 +1,204 @@
+/**
+ * Inline HCL-comment suppression (chant #2111). This file is core's small,
+ * generic half of the mechanism. It filters already-produced
+ * `PostSynthDiagnostic`s against suppression directives an entity carries,
+ * with no knowledge of which lexicon produced that entity. The other half,
+ * reading `# chant-ignore` / `# chant-ignore-file` / `# chant-ignore-block`
+ * comments out of raw `.tf` text and attaching the result to each parsed
+ * entity, is terraform-specific and lives in
+ * `lexicons/terraform/src/hcl/suppressions.ts`.
+ *
+ * Placement. The issue that asked for this weighed two options: a wrapper
+ * over `runPostSynthChecks` private to the terraform lexicon, or a
+ * `PostSynthContext` field every lexicon could share. Neither is quite what
+ * this file does. `ctx.entities` is already the one thing every
+ * `PostSynthContext` carries regardless of lexicon, and a suppression
+ * directive is inherently a fact ABOUT one entity, namely which block it
+ * anchors to, not a fact about the run as a whole. That is the same reasoning
+ * that already lets each lexicon's `Declarable` carry its own `props` shape
+ * (`TerraformEntity.props`, `K8sEntity.props`, and so on), so the hook here
+ * is a plain, duck-typed optional field, `suppressions`, that any entity MAY
+ * carry beside its `props`, read generically through `entitySuppressions()`
+ * below. Choosing this over a `PostSynthContext.suppressions` field needed no
+ * change to `PostSynthContext`, `Declarable`, or any of the places that
+ * construct a context (`./post-synth.ts`'s `runPostSynthChecks`, `chant
+ * audit`'s `../audit/core.ts`, and the two test-utils builders). Every one
+ * of them already hands `applyInlineSuppressions` below `ctx.entities`, so a
+ * lexicon that wants this (k8s manifests are the epic's other named
+ * candidate) adopts the convention on its own entities, with zero further
+ * core changes.
+ *
+ * `rules` (a project's `lint.rules`) is optional here on purpose. `chant
+ * build` has one to pass, so `ignorable: false` works there; `chant audit`'s
+ * audit-core path does not thread a project config through at all today, see
+ * `../audit/core.ts`, so it calls this with `rules` omitted. Every rule
+ * reads as ignorable in that path, the same default this module
+ * gives an unconfigured rule id everywhere else.
+ */
+
+import type { RuleConfig } from "./rule";
+import type { PostSynthDiagnostic } from "./post-synth";
+import type { Declarable } from "../declarable";
+
+/** What a directive's id list names. `"all"` is the wildcard every form accepts. */
+export type SuppressionIds = "all" | ReadonlySet<string>;
+
+/** One `# chant-ignore*` comment, already parsed from raw source text. */
+export interface SuppressionDirective {
+  /** Which of the three comment forms produced this directive. */
+  form: "chant-ignore" | "chant-ignore-file" | "chant-ignore-block";
+  /** Rule ids this directive names, or `"all"`. */
+  ids: SuppressionIds;
+  /** The `exp:YYYY-MM-DD` term, if present. */
+  expires?: string;
+  /** Source file the comment lives in. */
+  file: string;
+  /** 1-based line the comment ITSELF sits on (not the block it anchors to). */
+  line: number;
+  /**
+   * `chant-ignore-file` is only valid as the file's first non-blank line
+   * (tflint's own constraint on `tflint-ignore-file`, kept here so the form
+   * stays findable). A directive found elsewhere sets this instead of being
+   * applied; see `SUPPRESSION_MISPLACED_FILE_ID` below.
+   */
+  misplaced?: boolean;
+  /**
+   * Stable identity, for dedup across the several entities one directive can
+   * attach to. A file-level directive attaches to every entity parsed from
+   * its file, but an expired-or-misplaced report about it should appear once.
+   */
+  key: string;
+}
+
+/** An expired suppression is reported once as its own finding, not dropped. */
+export const SUPPRESSION_EXPIRED_ID = "SUPP001";
+/** A `chant-ignore-file` found anywhere but the first non-blank line. */
+export const SUPPRESSION_MISPLACED_FILE_ID = "SUPP002";
+/** A directive explicitly names a rule id configured `ignorable: false`. */
+export const SUPPRESSION_UNIGNORABLE_ID = "SUPP003";
+
+export type SuppressionMetaCheckId =
+  | typeof SUPPRESSION_EXPIRED_ID
+  | typeof SUPPRESSION_MISPLACED_FILE_ID
+  | typeof SUPPRESSION_UNIGNORABLE_ID;
+
+/**
+ * A finding about the suppression mechanism itself, not about a rule id a
+ * check would normally report, so it deliberately does not go through the
+ * audit catalog: nothing here is registered as a `PostSynthCheck`, so it
+ * never needs a `RuleMeta` entry, a lineage entry, or a full page.
+ */
+export interface SuppressionMetaFinding {
+  checkId: SuppressionMetaCheckId;
+  severity: "warning";
+  message: string;
+  file: string;
+  line: number;
+}
+
+export interface InlineSuppressionResult {
+  /** Diagnostics after inline suppression, matched ones removed. */
+  diagnostics: PostSynthDiagnostic[];
+  /** Diagnostics an inline directive suppressed, unaltered (counted, never dropped silently). */
+  suppressed: PostSynthDiagnostic[];
+  /** Findings about the suppression mechanism itself: expired, misplaced, or denied by `ignorable: false`. */
+  meta: SuppressionMetaFinding[];
+}
+
+/** Read an entity's directives, if it carries any (duck-typed; see module doc). */
+export function entitySuppressions(entity: Declarable | undefined): readonly SuppressionDirective[] {
+  if (!entity) return [];
+  const s = (entity as { suppressions?: unknown }).suppressions;
+  return Array.isArray(s) ? (s as SuppressionDirective[]) : [];
+}
+
+/** Default is ignorable (per the issue); only an explicit `{ ignorable: false }` option denies it. */
+function isIgnorable(rules: Record<string, RuleConfig> | undefined, id: string): boolean {
+  const cfg = rules?.[id];
+  if (!Array.isArray(cfg)) return true;
+  const options = cfg[1] as { ignorable?: boolean } | undefined;
+  return options?.ignorable !== false;
+}
+
+function namesId(ids: SuppressionIds, checkId: string): boolean {
+  return ids === "all" || ids.has(checkId);
+}
+
+function isExpired(expires: string | undefined, today: Date): boolean {
+  if (!expires) return false;
+  const parsed = new Date(`${expires}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime())) return false;
+  return parsed.getTime() < today.getTime();
+}
+
+/**
+ * Apply inline (`# chant-ignore*`) suppression to a set of post-synth
+ * diagnostics. `entities` is `ctx.entities`, the same map every
+ * `PostSynthContext` already carries. `rules` is the project's `lint.rules`,
+ * for `ignorable: false`; see this module's doc comment for why it is
+ * optional. `today` is injectable so an expiry test doesn't depend on the
+ * clock.
+ */
+export function applyInlineSuppressions(
+  diagnostics: readonly PostSynthDiagnostic[],
+  entities: Map<string, Declarable>,
+  rules?: Record<string, RuleConfig>,
+  today: Date = new Date(),
+): InlineSuppressionResult {
+  const kept: PostSynthDiagnostic[] = [];
+  const suppressed: PostSynthDiagnostic[] = [];
+  const meta: SuppressionMetaFinding[] = [];
+  const reported = new Set<string>();
+
+  const reportMeta = (d: SuppressionDirective, checkId: SuppressionMetaCheckId, message: string): void => {
+    const dedupeKey = `${checkId}:${d.key}`;
+    if (reported.has(dedupeKey)) return;
+    reported.add(dedupeKey);
+    meta.push({ checkId, severity: "warning", file: d.file, line: d.line, message });
+  };
+
+  // Expired and misplaced directives are findings on their own. They don't
+  // need a matching diagnostic to be worth reporting, so every directive
+  // attached to any entity is checked once here, deduplicated by its own
+  // identity (a directive attached to several entities, as a file-level one
+  // is, would otherwise be reported once per entity).
+  for (const entity of entities.values()) {
+    for (const d of entitySuppressions(entity)) {
+      if (d.misplaced) {
+        reportMeta(
+          d,
+          SUPPRESSION_MISPLACED_FILE_ID,
+          `chant-ignore-file at ${d.file}:${d.line} is not the first non-blank line of the file, so it has no effect. Move it to the top.`,
+        );
+        continue;
+      }
+      if (isExpired(d.expires, today)) {
+        reportMeta(d, SUPPRESSION_EXPIRED_ID, `Suppression at ${d.file}:${d.line} expired ${d.expires} and no longer applies.`);
+      }
+    }
+  }
+
+  for (const diag of diagnostics) {
+    const entity = diag.entity ? entities.get(diag.entity) : undefined;
+    let matched: SuppressionDirective | undefined;
+    for (const d of entitySuppressions(entity)) {
+      if (d.misplaced) continue;
+      if (isExpired(d.expires, today)) continue;
+      if (!namesId(d.ids, diag.checkId)) continue;
+      if (d.ids !== "all" && !isIgnorable(rules, diag.checkId)) {
+        reportMeta(
+          d,
+          SUPPRESSION_UNIGNORABLE_ID,
+          `${diag.checkId} is configured \`ignorable: false\`; the ${d.form} at ${d.file}:${d.line} naming it has no effect.`,
+        );
+        continue;
+      }
+      matched = d;
+      break;
+    }
+    if (matched) suppressed.push(diag);
+    else kept.push(diag);
+  }
+
+  return { diagnostics: kept, suppressed, meta };
+}

package/src/live-endpoint.ts

@@ -42,7 +42,7 @@ import { emulatorsOf, endpointEnvVars, type EmulatorDeclaration } from "./op/emu
  * The ambient endpoint vars a lexicon honors, from its emulator capability.
  *
  * A lexicon with no emulator contributes nothing, which is the same answer the
- * hand-maintained map gave for k8s, gcp and temporal — they resolve their live
+ * hand-maintained map gave for k8s and gcp — they resolve their live
  * target from `chant.config` itself, so there is nothing to inject.
  */
 export function endpointEnvVarsFor(lexicon: EndpointLexicon): string[] {

package/src/op/activities/activity-contracts.ts

@@ -0,0 +1,66 @@
+/**
+ * Activity contracts for core's own `op/activities` (chant #1288
+ * Stage 1). Each contract's `args` schema mirrors the corresponding
+ * `*Args` interface in `./activities/*.ts` — kept alongside the
+ * implementation, the way the issue asked for, and validated by
+ * `chant build` via `tmp012` (the OPS012 activity-contract rule).
+ *
+ * Author `args` with `z.strictObject(...)`, never `z.object(...)`: the
+ * default form silently drops a key it doesn't recognize instead of
+ * rejecting it, which reproduces the exact bug this issue is about
+ * (`helmInstall("api", "./chart", { nameSpace: "prod" })` — the misspelled
+ * key vanishes rather than failing the build).
+ *
+ * Deliberately partial. Only activities with args simple enough for a zod
+ * mirror to earn its keep are covered here — `kubectlApply`/`helmInstall`/
+ * the cloud appliers carry a dozen-plus fields each with real cross-field
+ * logic (see `KubectlApplyArgs`, `HelmInstallArgs`), and forcing those
+ * through a duplicate schema is exactly the maintenance burden Stage 2
+ * (regenerating the step builders as fully typed wrappers) is meant to
+ * avoid by deriving types instead of restating them. A step calling an
+ * activity with no registered contract here is skipped by `tmp012`, not
+ * flagged — see `activityContract`'s doc in `../activity-contract` for why
+ * that's the intended, non-breaking default.
+ */
+
+import { z } from "zod";
+import { activityContract } from "../activity-contract";
+
+export const lifecycleSnapshotContract = activityContract(
+  "lifecycleSnapshot",
+  z.strictObject({ env: z.string() }),
+);
+
+export const lifecycleDiffContract = activityContract(
+  "lifecycleDiff",
+  z.strictObject({ env: z.string(), live: z.boolean().optional() }),
+  z.object({ output: z.string(), exitCode: z.number(), drifted: z.boolean() }),
+);
+
+export const shellCmdContract = activityContract(
+  "shellCmd",
+  z.strictObject({ cmd: z.string(), env: z.record(z.string(), z.string()).optional(), cwd: z.string().optional() }),
+);
+
+export const httpCheckContract = activityContract(
+  "httpCheck",
+  z.strictObject({
+    url: z.string(),
+    method: z.string().optional(),
+    status: z.number().optional(),
+    contains: z.string().optional(),
+    retries: z.number().optional(),
+    intervalMs: z.number().optional(),
+  }),
+  z.object({ status: z.number() }),
+  // The check's effect is entity-scoped (#2022): `url` names the service the
+  // step probes, so op.json resolves it into the step's `entities` — the join
+  // a renderer draws to the estate node it targets. The scope-ish args
+  // (retries, interval) stay mechanics.
+  { entities: ["url"] },
+);
+
+export const chantTeardownContract = activityContract(
+  "chantTeardown",
+  z.strictObject({ path: z.string() }),
+);