@intentius/chant 0.39.0 → 0.41.0

package/src/apply.ts

@@ -0,0 +1,249 @@
+/**
+ * The apply contract (#1446) — what a lexicon's applier is allowed to mean.
+ *
+ * The peer of `./observation.ts`, and it exists for the same reason on the other
+ * side of the lifecycle.
+ *
+ * The read path had two ways to return nothing for a declared entity and no way
+ * to tell them apart — "the provider says it is absent" versus "I never looked"
+ * — and the second was classifying as `create`. #1089 made that a tri-state and
+ * #1201 built a conformance suite so a lexicon could not pass by returning a
+ * well-shaped result that still proposed a create.
+ *
+ * The write path had the identical hole. An applier could skip a resource and
+ * report nothing:
+ *
+ *     const mapper = MAPPERS[r.kind];
+ *     if (!mapper) {
+ *       console.log(`skip: no mapper for kind ${r.kind}`);
+ *       continue;                    // never appears in `applied`, or anywhere
+ *     }
+ *
+ * A caller receiving `{ applied: [...] }` could not distinguish a complete apply
+ * from one that dropped half the manifest, and `ApplyOp` had nothing to gate on.
+ * A `console.log` on stdout is not a signal in a result, the same way a warn on
+ * stderr was not a signal in a change set (#1447 was the concrete bug; #1457
+ * found the same shape in two more appliers).
+ *
+ * The contract is a tri-state, per resource in the plan:
+ *
+ *   - **APPLIED** — the provider was called and converged. Carries the action
+ *     (`created` / `updated` / `unchanged`) and the physical id when resolved.
+ *   - **PRUNED** — owned, no longer declared, deleted.
+ *   - **NOT-ATTEMPTED** — carrying a total {@link NotAttemptedReason}. Never
+ *     silent, never inferred from absence.
+ *
+ * The three are **disjoint and total**: every resource the applier was given
+ * appears in exactly one. That is the assertion the conformance suite exists to
+ * make, and the one the gcp skip failed.
+ *
+ * Compatibility: an applier may keep returning its own shape. The envelope is
+ * discriminated by its literal `apply: "v1"` field, the same mechanism
+ * `observation: "v1"` uses, so an un-migrated applier normalizes to "everything
+ * I was handed, I attempted" and nothing breaks. Reporting NOT-ATTEMPTED
+ * requires the envelope — which is the point: you cannot claim the guarantee
+ * without adopting the shape that can express its absence.
+ */
+
+/**
+ * Why a resource in the plan was not attempted. Total: an applier that skips a
+ * resource must pick one of these, and consumers may switch exhaustively.
+ *
+ * - `unsupported-kind` — the lexicon has no mapper/writer for this type. The
+ *   resource is declared and simply was not written.
+ * - `no-credentials` — no usable credentials/authorization for the target.
+ * - `no-binding` — the environment resolves to no concrete target (no cluster
+ *   context, no subscription, no resource group, no endpoint).
+ * - `dependency-failed` — an upstream resource in the same run failed, so this
+ *   one was never reached. Distinct from a failure of its own.
+ * - `filtered` — reached but deliberately withheld by a caller-requested scope.
+ * - `not-prunable` — an owned orphan of a kind the applier cannot enumerate or
+ *   delete. The prune-side shape: not "there was nothing to prune" but "I could
+ *   not look for anything to prune here".
+ */
+export type NotAttemptedReason =
+  | "unsupported-kind"
+  | "no-credentials"
+  | "no-binding"
+  | "dependency-failed"
+  | "filtered"
+  | "not-prunable";
+
+/** Every legal {@link NotAttemptedReason}, for validation and conformance checks. */
+export const NOT_ATTEMPTED_REASONS: readonly NotAttemptedReason[] = [
+  "unsupported-kind",
+  "no-credentials",
+  "no-binding",
+  "dependency-failed",
+  "filtered",
+  "not-prunable",
+];
+
+/** True when `value` is a legal {@link NotAttemptedReason}. */
+export function isNotAttemptedReason(value: unknown): value is NotAttemptedReason {
+  return typeof value === "string" && (NOT_ATTEMPTED_REASONS as readonly string[]).includes(value);
+}
+
+/** What an apply did to a resource that it did reach. */
+export type AppliedAction = "created" | "updated" | "unchanged";
+
+/** Every legal {@link AppliedAction}. */
+export const APPLIED_ACTIONS: readonly AppliedAction[] = ["created", "updated", "unchanged"];
+
+/** How a resource is named across appliers whose native vocabularies differ. */
+export interface ApplyRef {
+  /**
+   * The provider's own type name — a CNRM `kind`, an ARM `type`, a
+   * CloudFormation resource type, a Fly entity class. Kept verbatim rather than
+   * normalized into a chant vocabulary, so an applier stays true to its target.
+   */
+  kind: string;
+  /** The resource's name within its scope. */
+  name: string;
+}
+
+/** APPLIED — the provider was called and the resource converged. */
+export interface AppliedResource extends ApplyRef {
+  action: AppliedAction;
+  /** Provider-assigned identifier, when the response carried one. */
+  physicalId?: string;
+}
+
+/** PRUNED — owned, no longer declared, deleted. */
+export interface PrunedResource extends ApplyRef {
+  /**
+   * False when the delete was a no-op because the resource was already gone.
+   * Still PRUNED: the applier looked, decided, and acted.
+   */
+  deleted: boolean;
+}
+
+/** NOT-ATTEMPTED — no provider call was made, and why. */
+export interface NotAttemptedResource extends ApplyRef {
+  reason: NotAttemptedReason;
+  /** Detail for the operator: the status and body, the missing binding, the unsupported kind. */
+  detail?: string;
+}
+
+/**
+ * The apply envelope. Explicitly versioned: `apply: "v1"`, which discriminates
+ * it from an applier's own return shape.
+ */
+export interface ApplyResult {
+  /** Discriminant + wire version. */
+  readonly apply: "v1";
+  applied: AppliedResource[];
+  pruned?: PrunedResource[];
+  /** Omit or leave empty when everything in the plan was attempted. */
+  notAttempted?: NotAttemptedResource[];
+}
+
+/** Normalized form every consumer works with. All three arrays always present. */
+export interface NormalizedApply {
+  applied: AppliedResource[];
+  pruned: PrunedResource[];
+  notAttempted: NotAttemptedResource[];
+}
+
+/** True when `value` is the versioned {@link ApplyResult} envelope. */
+export function isApplyResult(value: unknown): value is ApplyResult {
+  return typeof value === "object" && value !== null && (value as { apply?: unknown }).apply === "v1";
+}
+
+/**
+ * Build an {@link ApplyResult}. Appliers use this rather than writing the
+ * discriminant by hand.
+ */
+export function applyResult(
+  applied: AppliedResource[],
+  pruned?: PrunedResource[],
+  notAttempted?: NotAttemptedResource[],
+): ApplyResult {
+  return {
+    apply: "v1",
+    applied,
+    ...(pruned && pruned.length > 0 ? { pruned } : {}),
+    ...(notAttempted && notAttempted.length > 0 ? { notAttempted } : {}),
+  };
+}
+
+/**
+ * Normalize an applier's return value.
+ *
+ * A non-envelope value normalizes to "everything I was handed, I attempted" —
+ * an empty `notAttempted`. That is the compatibility path, and it is also
+ * exactly the claim an un-migrated applier is implicitly making, so nothing is
+ * invented on its behalf.
+ *
+ * `undefined` normalizes to three empty arrays. An applier that means "I applied
+ * nothing because I could not" must say so with {@link notAttemptedAll} rather
+ * than returning nothing, for the same reason `unobservedAll` exists on the read
+ * side.
+ */
+export function normalizeApply(value: ApplyResult | Partial<NormalizedApply> | undefined): NormalizedApply {
+  if (!value) return { applied: [], pruned: [], notAttempted: [] };
+  return {
+    applied: value.applied ?? [],
+    pruned: value.pruned ?? [],
+    notAttempted: value.notAttempted ?? [],
+  };
+}
+
+/**
+ * Mark every named resource NOT-ATTEMPTED with one reason — the whole-run
+ * failure case (no credentials, no binding, the transport never came up). Core
+ * applies this when an applier throws, so a thrown apply degrades to an honest
+ * "did not attempt" per resource instead of an empty result that reads as a
+ * successful no-op.
+ */
+export function notAttemptedAll(
+  refs: Iterable<ApplyRef>,
+  reason: NotAttemptedReason,
+  detail?: string,
+): NotAttemptedResource[] {
+  return [...refs].map((ref) => ({ ...ref, reason, ...(detail ? { detail } : {}) }));
+}
+
+/** A resource's identity within one apply, for disjointness checks. */
+export function applyRefKey(ref: ApplyRef): string {
+  return `${ref.kind}/${ref.name}`;
+}
+
+/**
+ * Every resource that appears in more than one bucket. Empty is the contract;
+ * a non-empty result means the applier both wrote and skipped the same
+ * resource, which is not a state that can be true.
+ *
+ * Pruned is checked against the other two but not against itself: an applier
+ * may legitimately apply a resource and prune a different, same-named one only
+ * if their kinds differ, and {@link applyRefKey} already separates those.
+ */
+export function overlappingRefs(result: NormalizedApply): string[] {
+  const seen = new Map<string, Set<string>>();
+  const note = (bucket: string, refs: ApplyRef[]): void => {
+    for (const ref of refs) {
+      const key = applyRefKey(ref);
+      (seen.get(key) ?? seen.set(key, new Set()).get(key)!).add(bucket);
+    }
+  };
+  note("applied", result.applied);
+  note("pruned", result.pruned);
+  note("notAttempted", result.notAttempted);
+  return [...seen.entries()].filter(([, buckets]) => buckets.size > 1).map(([key]) => key);
+}
+
+/**
+ * Resources in `plan` that the result accounts for in no bucket — the silent
+ * drop this contract exists to make impossible.
+ *
+ * The conformance suite's central assertion. Before #1447, gcp's applier failed
+ * exactly this: an unmapped kind was in the plan, in no bucket, and the result
+ * looked complete.
+ */
+export function unaccountedRefs(plan: Iterable<ApplyRef>, result: NormalizedApply): string[] {
+  const accounted = new Set<string>();
+  for (const bucket of [result.applied, result.pruned, result.notAttempted]) {
+    for (const ref of bucket) accounted.add(applyRefKey(ref));
+  }
+  return [...plan].map(applyRefKey).filter((key) => !accounted.has(key));
+}

package/src/cli/commands/doctor.test.ts

@@ -351,3 +351,48 @@ describe("doctorCommand", () => {
     });
   });
 });
+
+/**
+ * #1421 — the sibling of the `tsconfig-paths` check. Both are project settings
+ * that silently break runtime module resolution; this one makes build
+ * parameters read as empty in project source on the run path, so declarations
+ * conditioned on them take their default branch while chant reports success.
+ */
+describe("package-type-module (#1421)", () => {
+  const withPkg = async (pkg: object | undefined, assert: (check: { status: string; message?: string } | undefined) => void): Promise<void> => {
+    await withTestDir(async (testDir) => {
+      if (pkg) writeFileSync(join(testDir, "package.json"), JSON.stringify(pkg));
+      const report = await doctorCommand(testDir);
+      assert(report.checks.find((c) => c.name === "package-type-module"));
+    });
+  };
+
+  test('passes for "type": "module"', async () => {
+    await withPkg({ name: "p", type: "module" }, (check) => {
+      expect(check?.status).toBe("pass");
+    });
+  });
+
+  test('warns for "type": "commonjs", saying what breaks', async () => {
+    await withPkg({ name: "p", type: "commonjs" }, (check) => {
+      expect(check?.status).toBe("warn");
+      expect(check?.message).toContain('"type": "commonjs"');
+      expect(check?.message).toContain("build parameters");
+      expect(check?.message).toContain('Set "type": "module"');
+    });
+  });
+
+  // The easier one to miss: no `type` field is CommonJS too.
+  test("warns when no type field is declared at all", async () => {
+    await withPkg({ name: "p" }, (check) => {
+      expect(check?.status).toBe("warn");
+      expect(check?.message).toContain("no `type` field");
+    });
+  });
+
+  test("says nothing when there is no package.json to judge", async () => {
+    await withPkg(undefined, (check) => {
+      expect(check).toBeUndefined();
+    });
+  });
+});

package/src/cli/commands/doctor.ts

@@ -169,6 +169,46 @@ export async function doctorCommand(path: string): Promise<DoctorReport> {
     }
   }
 
+  // Check 8b: package.json declares "type": "module" (#1421)
+  //
+  // Sibling of the tsconfig-paths check above, and filed for the same reason:
+  // both are project settings that silently break runtime module resolution.
+  //
+  // chant's core is ESM. When the project is CJS — `"type": "commonjs"`, or no
+  // `type` field at all — 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. `setBuildParams` mutates one object
+  // in place; project source reads the other, and sees `{}`.
+  //
+  // The result is a silent wrong answer, not a failure: chant prints
+  // `[param] tier = "prod" (cli)` and then emits the graph for the default. It
+  // hits `chant graph` (always the run path) and `chant build --no-fold`; plain
+  // `chant build` escapes only because folding substitutes parameters
+  // statically and never reads the shared object.
+  const projectPkgPath = join(projectPath, "package.json");
+  if (existsSync(projectPkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(projectPkgPath, "utf-8")) as { type?: string };
+      if (pkg.type === "module") {
+        checks.push({ name: "package-type-module", status: "pass" });
+      } else {
+        const found = pkg.type ? `"type": "${pkg.type}"` : "no `type` field";
+        checks.push({
+          name: "package-type-module",
+          status: "warn",
+          message:
+            `package.json has ${found} — chant is ESM, and a CommonJS project reads build ` +
+            `parameters as empty on the run path (\`chant graph\`, \`chant build --no-fold\`). ` +
+            `Declarations conditioned on \`params.<name>\` silently take their default branch. ` +
+            `Set "type": "module".`,
+        });
+      }
+    } catch (e) {
+      debug("project package.json parse failed:", e);
+      checks.push({ name: "package-type-module", status: "warn", message: "Could not parse package.json" });
+    }
+  }
+
   // Check 9: .mcp.json exists and has chant entry
   const mcpPath = join(projectPath, ".mcp.json");
   if (!existsSync(mcpPath)) {

package/src/codegen/naming.test.ts

@@ -0,0 +1,129 @@
+import { describe, test, expect } from "vitest";
+import { NamingStrategy, reservedNamesFromSnapshot, type NamingConfig, type NamingInput } from "./naming";
+
+/**
+ * chant #1459 — a published TypeScript name belongs to the type that published
+ * it, so an unrelated upstream addition or removal cannot rename a resource
+ * whose own schema never moved.
+ */
+
+const config: NamingConfig = {
+  priorityNames: {},
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+  shortName: (t) => t.split("::").pop() ?? t,
+  serviceName: (t) => t.split("::")[1] ?? "",
+};
+
+function name(types: string[], over: Partial<NamingConfig> = {}): Map<string, string | undefined> {
+  const inputs: NamingInput[] = types.map((typeName) => ({ typeName, propertyTypes: [] }));
+  const strategy = new NamingStrategy(inputs, { ...config, ...over });
+  return new Map(types.map((t) => [t, strategy.resolve(t)]));
+}
+
+describe("reservedNamesFromSnapshot", () => {
+  test("inverts the snapshot into spec type → published name", () => {
+    expect(
+      reservedNamesFromSnapshot({
+        entries: { MacieSession: { kind: "resource", resourceType: "AWS::Macie::Session" } },
+      }),
+    ).toEqual({ "AWS::Macie::Session": "MacieSession" });
+  });
+
+  test("reserves resources only, not property types", () => {
+    // Property names derive from their owning resource (phase 5), so pinning
+    // the resource pins them; reserving them separately would freeze aliases
+    // that are meant to follow their parent.
+    const reserved = reservedNamesFromSnapshot({
+      entries: {
+        Bucket: { kind: "resource", resourceType: "AWS::S3::Bucket" },
+        Bucket_Rule: { kind: "property", resourceType: "AWS::S3::Bucket.Rule" },
+      },
+    });
+    expect(reserved).toEqual({ "AWS::S3::Bucket": "Bucket" });
+  });
+
+  test("ignores entries with no resourceType, and a missing snapshot", () => {
+    expect(reservedNamesFromSnapshot({ entries: { Broken: { kind: "resource" } } })).toEqual({});
+    expect(reservedNamesFromSnapshot(undefined)).toEqual({});
+    expect(reservedNamesFromSnapshot({})).toEqual({});
+  });
+
+  test("first writer wins when one spec type is listed under two names", () => {
+    const reserved = reservedNamesFromSnapshot({
+      entries: {
+        Alpha: { kind: "resource", resourceType: "AWS::X::Y" },
+        Beta: { kind: "resource", resourceType: "AWS::X::Y" },
+      },
+    });
+    expect(reserved).toEqual({ "AWS::X::Y": "Alpha" });
+  });
+});
+
+describe("reserved names survive their neighbours changing", () => {
+  test("a competitor disappearing does not hand its short name over", () => {
+    // The real case: AWS::Athena::Session and AWS::SSM::Session were removed
+    // upstream, which silently renamed AWS::Macie::Session from MacieSession
+    // to Session — breaking a resource AWS had not touched.
+    const withCompetitor = name(["AWS::Macie::Session", "AWS::Athena::Session"]);
+    expect(withCompetitor.get("AWS::Macie::Session")).toBe("MacieSession");
+
+    const afterRemoval = name(["AWS::Macie::Session"], {
+      reservedNames: { "AWS::Macie::Session": "MacieSession" },
+    });
+    expect(afterRemoval.get("AWS::Macie::Session")).toBe("MacieSession");
+  });
+
+  test("without reservation, the same removal renames it — the bug", () => {
+    const afterRemoval = name(["AWS::Macie::Session"]);
+    expect(afterRemoval.get("AWS::Macie::Session")).toBe("Session");
+  });
+
+  test("a newcomer colliding gets qualified instead of displacing the incumbent", () => {
+    // AWS::QuickSight::Space appearing renamed AWS::SageMaker::Space from
+    // Space to SageMakerSpace. The newcomer should absorb the qualification.
+    const names = name(["AWS::SageMaker::Space", "AWS::QuickSight::Space"], {
+      reservedNames: { "AWS::SageMaker::Space": "Space" },
+    });
+    expect(names.get("AWS::SageMaker::Space")).toBe("Space");
+    expect(names.get("AWS::QuickSight::Space")).toBe("QuickSightSpace");
+  });
+
+  test("order of the input does not decide the outcome", () => {
+    const reservedNames = { "AWS::SageMaker::Space": "Space" };
+    const forward = name(["AWS::SageMaker::Space", "AWS::QuickSight::Space"], { reservedNames });
+    const reverse = name(["AWS::QuickSight::Space", "AWS::SageMaker::Space"], { reservedNames });
+    expect(forward.get("AWS::SageMaker::Space")).toBe(reverse.get("AWS::SageMaker::Space"));
+    expect(forward.get("AWS::QuickSight::Space")).toBe(reverse.get("AWS::QuickSight::Space"));
+  });
+});
+
+describe("reservation boundaries", () => {
+  test("an explicit priority name still outranks history", () => {
+    const names = name(["AWS::Macie::Session"], {
+      priorityNames: { "AWS::Macie::Session": "PinnedName" },
+      reservedNames: { "AWS::Macie::Session": "MacieSession" },
+    });
+    expect(names.get("AWS::Macie::Session")).toBe("PinnedName");
+  });
+
+  test("a reservation for a type no longer in the input releases the name", () => {
+    // AWS::CodeArtifact::Package was genuinely removed, so Package is free for
+    // whoever legitimately claims it next.
+    const names = name(["AWS::Panorama::Package"], {
+      reservedNames: { "AWS::CodeArtifact::Package": "Package" },
+    });
+    expect(names.get("AWS::Panorama::Package")).toBe("Package");
+  });
+
+  test("a brand-new resource with no reservation is unaffected", () => {
+    const names = name(["AWS::MSK::Channel"], { reservedNames: { "AWS::Macie::Session": "MacieSession" } });
+    expect(names.get("AWS::MSK::Channel")).toBe("Channel");
+  });
+
+  test("no reservations at all reproduces the previous behaviour exactly", () => {
+    const types = ["AWS::Macie::Session", "AWS::Athena::Session", "AWS::MSK::Channel"];
+    expect(name(types, { reservedNames: {} })).toEqual(name(types));
+  });
+});

package/src/codegen/naming.ts

@@ -1,12 +1,32 @@
 /**
  * Collision-free naming strategy for TypeScript class names.
  *
- * 5-phase algorithm:
+ * 6-phase algorithm:
  * 1. Priority names (backward compatibility)
+ * 1a. Reserved names — names this lexicon has already published (chant #1459)
  * 2. Priority aliases (additional short names)
  * 3. Short names (last segment of type)
  * 4. Collision resolution (service-prefixed)
  * 5. Property type aliases (globally unique defs)
+ *
+ * ## Why phase 1a exists
+ *
+ * Phases 3 and 4 assign a short name to whoever asks first and service-qualify
+ * everyone after. Membership of that contest is the whole input set, so a
+ * resource's name was a function of its NEIGHBOURS: removing
+ * `AWS::Athena::Session` upstream freed `Session`, and `AWS::Macie::Session`
+ * silently changed from `MacieSession` to `Session` — a breaking rename for a
+ * resource whose schema had not moved. Adding a resource does the same in
+ * reverse: `AWS::QuickSight::Space` appearing renamed `AWS::SageMaker::Space`
+ * from `Space` to `SageMakerSpace`.
+ *
+ * Worse, it is reversible. These are read-only registry types that come and go,
+ * so a name could flip back on the next upgrade and break consumers again.
+ *
+ * Reserved names invert the bias: a name that has already shipped belongs to
+ * the type that shipped it, and a newcomer colliding with it gets qualified
+ * instead. A published name then changes only when its own type disappears,
+ * which is a genuine breaking change rather than an incidental one.
  */
 
 /**
@@ -35,6 +55,40 @@ export interface NamingConfig {
   shortName: (typeName: string) => string;
   /** Extract the service name from a type name (e.g. "Vendor::Service::Resource" → "Service"). */
   serviceName: (typeName: string) => string;
+  /**
+   * chant #1459 — spec type name → the TypeScript name this lexicon has
+   * already published for it, normally read from the committed
+   * `surface.snapshot.json` via {@link reservedNamesFromSnapshot}.
+   *
+   * Claimed before short names are contested, so a shipped name is not taken
+   * away from its owner by an unrelated upstream change. Omit for a lexicon
+   * with no published surface yet; an entry for a type that is no longer in
+   * the input is ignored, so a removed type frees its name for reuse.
+   */
+  reservedNames?: Record<string, string>;
+}
+
+/**
+ * The names a lexicon has already published, read from a committed surface
+ * snapshot (chant #1459).
+ *
+ * The snapshot is keyed by TypeScript name with the spec type inside, which is
+ * exactly the mapping phase 1a needs, inverted. Only `resource` entries are
+ * reserved: property-type names are derived from their owning resource's name
+ * (phase 5), so pinning the resource pins them, and reserving them separately
+ * would freeze aliases that are meant to follow their parent.
+ */
+export function reservedNamesFromSnapshot(
+  snapshot: { entries?: Record<string, { kind?: string; resourceType?: string }> } | undefined,
+): Record<string, string> {
+  const reserved: Record<string, string> = {};
+  for (const [tsName, entry] of Object.entries(snapshot?.entries ?? {})) {
+    if (entry.kind !== "resource" || !entry.resourceType) continue;
+    // First writer wins: a snapshot that somehow lists one spec type under two
+    // names keeps the earlier, rather than silently preferring iteration order.
+    reserved[entry.resourceType] ??= tsName;
+  }
+  return reserved;
 }
 
 export class NamingStrategy {
@@ -58,6 +112,23 @@ export class NamingStrategy {
       }
     }
 
+    // Phase 1a: claim previously-published names (chant #1459).
+    //
+    // After priority names, which are explicit hand-pinned decisions and still
+    // win, and before any short name is contested. A reserved name whose type
+    // is gone from the input is simply never reached, so its name is released
+    // for whoever legitimately claims it next.
+    for (const t of typeNames) {
+      if (this.assigned.has(t)) continue;
+      const published = config.reservedNames?.[t];
+      // `usedNames` guards the case where a priority name already took it —
+      // an explicit pin outranks history.
+      if (published && !this.usedNames.has(published)) {
+        this.assigned.set(t, published);
+        this.usedNames.add(published);
+      }
+    }
+
     // Phase 1b: assign priority aliases
     for (const t of typeNames) {
       const extras = config.priorityAliases[t];

package/src/codegen/validate.test.ts

@@ -84,3 +84,89 @@ describe("validateLexiconArtifacts", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 });
+
+/**
+ * chant #1473 — the release gate. `prepack` regenerates from an upstream that
+ * moves, so what must match the reviewed baseline is the API that comes out,
+ * not the archive that went in.
+ */
+describe("surface snapshot gate (#1473)", () => {
+  const LEXICON = JSON.stringify({
+    Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource", lexicon: "aws" },
+  });
+  const DTS = "export declare class Bucket {}\n";
+
+  function fixture(opts: { snapshot?: string } = {}): string {
+    const dir = makeTempDir();
+    const genDir = join(dir, "src", "generated");
+    mkdirSync(genDir, { recursive: true });
+    writeFileSync(join(genDir, "lexicon-test.json"), LEXICON);
+    writeFileSync(join(genDir, "index.d.ts"), DTS);
+    if (opts.snapshot !== undefined) writeFileSync(join(dir, "surface.snapshot.json"), opts.snapshot);
+    return dir;
+  }
+
+  const run = (basePath: string, checkSurfaceSnapshot: boolean, armed = true) =>
+    validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath,
+      checkSurfaceSnapshot,
+      env: armed ? { CHANT_RELEASE_GATE: "1" } : {},
+    });
+
+  /** The snapshot a matching build would have produced. */
+  async function matchingSnapshot(): Promise<string> {
+    const { extractSurface, serializeSnapshot } = await import("./surface-snapshot");
+    return serializeSnapshot(extractSurface(LEXICON, DTS));
+  }
+
+  test("passes when the generated API matches the snapshot", async () => {
+    const result = await run(fixture({ snapshot: await matchingSnapshot() }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(true);
+  });
+
+  test("fails when the generated API differs, and says how to accept it", async () => {
+    const stale = JSON.stringify({
+      schemaVersion: 1,
+      generatedAt: "2026-01-01T00:00:00.000Z",
+      entries: { Queue: { kind: "resource", resourceType: "AWS::SQS::Queue", attrs: [], props: [] } },
+    });
+    const result = await run(fixture({ snapshot: stale }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+    expect(check?.error).toContain("--update-snapshot");
+    expect(result.success).toBe(false);
+  });
+
+  test("is off unless the lexicon opts in", async () => {
+    // k8s and azure are adrift from their own baselines (#1475); switching
+    // this on globally would block their releases.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), false);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+  });
+
+  test("does not run outside a release, even for a lexicon that opted in", async () => {
+    // `validate` runs on every PR. Upstream can move the surface at any time,
+    // so a hard check here would turn unrelated PRs red — the same trap the
+    // spec pin fell into. Drift between releases is the upgrade job's business.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), true, false);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).toBe(true);
+  });
+
+  test("is skipped for a lexicon with no committed snapshot", async () => {
+    // A new lexicon before its first baseline must still be able to build.
+    const result = await run(fixture(), true);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+  });
+
+  test("an unreadable snapshot fails rather than passing silently", async () => {
+    const result = await run(fixture({ snapshot: "{ not json" }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+  });
+});