@intentius/chant 0.39.0 → 0.41.0

package/src/codegen/validate.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { computeCoverage, checkThresholds, type CoverageThresholds } from "./coverage";
+import { extractSurface, diffSurface, parseSnapshot, formatDelta } from "./surface-snapshot";
 
 export interface ValidateCheck {
   name: string;
@@ -20,6 +21,12 @@ export interface ValidateResult {
   checks: ValidateCheck[];
 }
 
+/**
+ * Set by the publish workflow to arm the release-time surface gate
+ * (chant #1473). Absent in ordinary CI, where upstream drift is expected.
+ */
+export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -35,6 +42,32 @@ export interface LexiconValidationConfig {
   requiredNamesMatchSubstring?: boolean;
   /** Base path of the lexicon package */
   basePath: string;
+  /**
+   * chant #1473 — this lexicon's release is gated on the generated API
+   * matching the committed `surface.snapshot.json`.
+   *
+   * Two conditions, both required. The lexicon opts in here, AND
+   * {@link RELEASE_GATE_ENV} is set — which the publish workflow does and
+   * ordinary CI does not.
+   *
+   * The env half is not caution, it is correctness. `validate` runs on every
+   * PR, and the upstream a lexicon generates from can move at any time: the
+   * CloudFormation archive republishes schemas several times a day, and some
+   * of those edits do change the surface. A hard surface check on every PR
+   * would turn any unrelated change red the moment upstream moved, which is
+   * the same trap the spec pin fell into one level down. Drift between
+   * releases is expected and is what the scheduled lexicon-upgrade job exists
+   * to report (#1423).
+   *
+   * What must never happen is *publishing* a surface nobody reviewed. That is
+   * a release-time property, so it is checked at release time.
+   *
+   * Opt-in per lexicon because k8s and azure are currently adrift from their
+   * own baselines (393 and 483 entries, #1475).
+   */
+  checkSurfaceSnapshot?: boolean;
+  /** Environment to read {@link RELEASE_GATE_ENV} from. Defaults to `process.env`; overridden in tests. */
+  env?: NodeJS.ProcessEnv;
   /** Path to the generated directory (defaults to basePath/src/generated) */
   generatedDir?: string;
   /** Coverage thresholds (optional) */
@@ -148,6 +181,47 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
     }
   }
 
+  // Check: the generated API matches the reviewed one (chant #1473).
+  //
+  // This is the gate that makes a release trustworthy. `prepack` regenerates
+  // from upstream, and for aws that upstream republishes schemas several times
+  // a day, so the input can differ from the one whose delta a human accepted.
+  // What must not differ is the API that ships. Comparing the just-generated
+  // artifacts against the committed `surface.snapshot.json` says exactly that,
+  // and says nothing about byte churn that changed no declaration.
+  //
+  // Runs on the artifacts already on disk — no second generation — and is
+  // skipped for a lexicon with no committed snapshot, which is the case for a
+  // new lexicon before its first baseline.
+  const snapshotPath = join(config.basePath, "surface.snapshot.json");
+  const releaseGate = config.checkSurfaceSnapshot && (config.env ?? process.env)[RELEASE_GATE_ENV] === "1";
+  if (releaseGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
+    try {
+      const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));
+      const delta = diffSurface(parseSnapshot(readFileSync(snapshotPath, "utf-8")), fresh);
+      const moved = delta.added.length + delta.removed.length + delta.changed.length;
+      checks.push(
+        moved === 0
+          ? { name: "surface-matches-snapshot", ok: true }
+          : {
+              name: "surface-matches-snapshot",
+              ok: false,
+              error:
+                `The generated API differs from the reviewed surface.snapshot.json ` +
+                `(${delta.added.length} added, ${delta.removed.length} removed, ${delta.changed.length} changed). ` +
+                `Accept it deliberately with \`chant dev surface-diff <lexicon> --update-snapshot --bump\`, ` +
+                `never as a side effect of a release.\n${formatDelta(delta)}`,
+            },
+      );
+    } catch (err) {
+      checks.push({
+        name: "surface-matches-snapshot",
+        ok: false,
+        error: `Failed to compare against surface.snapshot.json: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
   return {
     success: checks.every((c) => c.ok),
     checks,

package/src/discovery/index.ts

@@ -11,6 +11,64 @@ import { getProvenance } from "../provenance";
 import type { BuildParamProvenance } from "../provenance";
 import { buildParamValues } from "../build-params";
 import { setBuildParams } from "../params";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+
+/**
+ * Warn when resolved build parameters cannot reach project source (#1421).
+ *
+ * chant's core is ESM. When the project is CommonJS — `"type": "commonjs"`, or
+ * no `type` field — tsx loads project source through the CommonJS transform, so
+ * the project's `require` of `params.ts` and core's `import` of it produce two
+ * separate module records. {@link setBuildParams} mutates one object in place;
+ * project source reads the other, and sees `{}`.
+ *
+ * The failure is silence. chant prints `[param] tier = "prod" (cli)` and then
+ * emits the graph for the default branch. `chant graph` is always affected
+ * because it always takes the run path; `chant build --no-fold` likewise. Plain
+ * `chant build` usually escapes because folding substitutes parameters
+ * statically — but a file that falls back to run inside a folded build is wrong
+ * the same way, which is why this warns regardless of `fold`.
+ *
+ * Only fires when parameters were actually resolved, so a CJS project that uses
+ * none is never nagged. `chant doctor`'s `package-type-module` check is the
+ * ambient version of the same advice.
+ *
+ * Best-effort and never throws: a project whose `package.json` cannot be found
+ * or parsed gets no warning rather than a failed build.
+ */
+function warnIfParamsCannotReachProject(path: string, values: Record<string, unknown>): void {
+  if (Object.keys(values).length === 0) return;
+  try {
+    const pkgPath = findPackageJsonUpward(path);
+    if (!pkgPath) return;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { type?: string };
+    if (pkg.type === "module") return;
+    const found = pkg.type ? `"type": "${pkg.type}"` : "no `type` field";
+    const names = Object.keys(values).sort().join(", ");
+    console.error(
+      `warning: ${pkgPath} has ${found}, but chant is ESM — build parameters (${names}) ` +
+        `will read as empty in project source on the run path, so declarations conditioned ` +
+        `on them take their default branch. Set "type": "module". (chant #1421)`,
+    );
+  } catch {
+    // Unreadable or unparseable package.json — say nothing rather than fail.
+  }
+}
+
+/** Nearest `package.json` at or above `startDir`, or undefined. */
+function findPackageJsonUpward(startDir: string): string | undefined {
+  let dir = startDir;
+  const { root } = parse(dir);
+  for (;;) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) return candidate;
+    if (dir === root) return undefined;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
 
 /**
  * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
@@ -150,6 +208,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
   // `--watch`) never leaks into a build that supplied none.
   const buildParamValuesMap = buildParamValues(options?.buildParams ?? []);
   setBuildParams(buildParamValuesMap);
+  warnIfParamsCannotReachProject(path, buildParamValuesMap);
 
   // Step 1: Scan for TypeScript files
   const files = await findInfraFiles(path);

package/src/discovery/params-cjs-warning.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discover } from "./index";
+
+/**
+ * #1421 — chant's core is ESM. A CommonJS project's `require` of `params.ts`
+ * and core's `import` of it are two module records, so `setBuildParams`'s
+ * in-place mutation never reaches project source: it reads `{}` and every
+ * declaration conditioned on a parameter takes its default branch, silently.
+ *
+ * The fix is to stop it being silent. These assert the warning fires exactly
+ * when the hazard exists and stays quiet otherwise.
+ */
+describe("build params that cannot reach a CommonJS project (#1421)", () => {
+  const dirs: string[] = [];
+  const project = (type: string | undefined): string => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-1421-"));
+    dirs.push(dir);
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify(type === undefined ? { name: "p" } : { name: "p", type }),
+    );
+    mkdirSync(join(dir, "src"));
+    writeFileSync(join(dir, "src", "main.ts"), "export const x = 1;\n");
+    return dir;
+  };
+
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  const warnings = async (dir: string, params: Array<{ name: string; value: unknown }>): Promise<string[]> => {
+    const seen: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => void seen.push(a.join(" ")));
+    await discover(join(dir, "src"), {
+      buildParams: params as never,
+    });
+    return seen.filter((s) => s.includes("#1421"));
+  };
+
+  test('warns for "type": "commonjs" when parameters were resolved', async () => {
+    const out = await warnings(project("commonjs"), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/"type": "commonjs"/);
+    expect(out[0]).toMatch(/tier/);
+    expect(out[0]).toMatch(/Set "type": "module"/);
+  });
+
+  // The sneakier half: no `type` field at all is also CommonJS.
+  test("warns when package.json declares no type at all", async () => {
+    const out = await warnings(project(undefined), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/no `type` field/);
+  });
+
+  test('stays quiet for "type": "module"', async () => {
+    expect(await warnings(project("module"), [{ name: "tier", value: "prod" }])).toEqual([]);
+  });
+
+  // A CJS project using no parameters is not at risk, and must not be nagged.
+  test("stays quiet when no parameters were resolved", async () => {
+    expect(await warnings(project("commonjs"), [])).toEqual([]);
+  });
+
+  test("names every resolved parameter, sorted", async () => {
+    const out = await warnings(project("commonjs"), [
+      { name: "zone", value: "b" },
+      { name: "tier", value: "prod" },
+    ]);
+    expect(out[0]).toMatch(/\(tier, zone\)/);
+  });
+});

package/src/index.ts

@@ -49,6 +49,7 @@ export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
+export * from "./apply";
 export * from "./deep-observation";
 export * from "./owner-chain";
 export * from "./lexicon-integrity";