@intentius/chant 0.44.14 → 0.46.0

package/src/codegen/docs-sidebar.ts

@@ -1,13 +1,50 @@
 /**
  * Sidebar generation for Starlight docs sites.
+ *
+ * Grouped by Diátaxis quadrant (https://diataxis.fr), chant #1731. Every page
+ * the pipeline knows about — authored under docs/pages/ and generated reference
+ * tables — arrives as a {@link SidebarPage} with a quadrant; this module only sorts and nests. Empty quadrants are omitted.
  */
 
-import type { DocsConfig, DocsResult } from "./docs-types";
+import { QUADRANTS, QUADRANT_LABELS } from "./docs-pages";
+import type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
+
+type Entry = Record<string, unknown>;
+
+function byOrderThenLabel(a: SidebarPage, b: SidebarPage): number {
+  const ao = a.order ?? Number.POSITIVE_INFINITY;
+  const bo = b.order ?? Number.POSITIVE_INFINITY;
+  if (ao !== bo) return ao - bo;
+  return a.label.localeCompare(b.label);
+}
+
+/**
+ * One quadrant's entries: ungrouped pages first (by order, then label), then
+ * each nested `group` in order of its lowest-ordered member.
+ */
+export function quadrantItems(pages: SidebarPage[]): Entry[] {
+  const loose = pages.filter((p) => !p.group).sort(byOrderThenLabel);
+  const groups = new Map<string, SidebarPage[]>();
+  for (const p of pages) {
+    if (!p.group) continue;
+    const list = groups.get(p.group) ?? [];
+    list.push(p);
+    groups.set(p.group, list);
+  }
+  const items: Entry[] = loose.map((p) => ({ label: p.label, slug: p.slug }));
+  const grouped = [...groups.entries()]
+    .map(([label, members]) => ({ label, members: members.sort(byOrderThenLabel) }))
+    .sort((a, b) => byOrderThenLabel(a.members[0], b.members[0]));
+  for (const g of grouped) {
+    items.push({ label: g.label, items: g.members.map((p) => ({ label: p.label, slug: p.slug })) });
+  }
+  return items;
+}
 
 export function buildSidebar(
   config: DocsConfig,
   result: DocsResult,
-): Array<Record<string, unknown>> {
+): Entry[] {
   // Starlight prepends basePath to every sidebar `link`, so a site-root-relative
   // path like "/chant/" becomes "/chant/lexicons/aws/chant/" — a 404.  Instead
   // we use relative traversal: "../../" is prepended to become
@@ -15,47 +52,23 @@ export function buildSidebar(
   const segments = (config.basePath ?? "/").replace(/^\/|\/$/g, "").split("/");
   const backLink = segments.length > 1 ? "../".repeat(segments.length - 1) : "/";
 
-  const items: Array<Record<string, unknown>> = [
+  const items: Entry[] = [
     { label: "← chant docs", link: backLink },
     { label: "Overview", slug: "index" },
   ];
 
-  const suppress = new Set(config.suppressPages ?? []);
-  const extraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
-
-  // Extra pages from lexicon config (appear after Overview)
-  if (config.extraPages) {
-    for (const page of config.extraPages) {
-      if (page.sidebar === false) continue;
-      items.push({ label: page.title, slug: page.slug });
-    }
-  }
-
-  if (!suppress.has("intrinsics") && !extraSlugs.has("intrinsics") && result.pages.has("intrinsics.mdx")) {
-    items.push({ label: "Intrinsics", slug: "intrinsics" });
-  }
-
-  if (!suppress.has("pseudo-parameters") && !extraSlugs.has("pseudo-parameters") && result.pages.has("pseudo-parameters.mdx")) {
-    items.push({ label: "Pseudo-Parameters", slug: "pseudo-parameters" });
-  }
-
-  // Every lexicon links its generated rules table, whether or not it also
-  // ships a prose `lint-rules` page. Skipping it when one existed was how gcp
-  // ended up emitting a page nothing pointed at (#1312), and it left readers
-  // with no complete list on the lexicons whose prose covers only part of the
-  // set — aws documented 26 of 50 that way. The label distinguishes the
-  // generated table from a prose page rather than competing with it.
-  if (!suppress.has("rules") && !extraSlugs.has("rules") && result.pages.has("rules.mdx")) {
-    items.push({ label: "All Rules", slug: "rules" });
-  }
-
-  if (!suppress.has("serialization") && !extraSlugs.has("serialization") && result.pages.has("serialization.mdx")) {
-    items.push({ label: "Serialization", slug: "serialization" });
+  const byQuadrant = new Map<Quadrant, SidebarPage[]>();
+  for (const page of result.sidebarPages) {
+    if (page.hidden) continue;
+    const list = byQuadrant.get(page.quadrant) ?? [];
+    list.push(page);
+    byQuadrant.set(page.quadrant, list);
   }
 
-  // Append raw sidebar entries (supports groups and nested items)
-  if (config.sidebarExtra) {
-    items.push(...config.sidebarExtra);
+  for (const q of QUADRANTS) {
+    const pages = byQuadrant.get(q);
+    if (!pages || pages.length === 0) continue;
+    items.push({ label: QUADRANT_LABELS[q], items: quadrantItems(pages) });
   }
 
   return items;

package/src/codegen/docs-types.ts

@@ -13,6 +13,12 @@ export interface DocsConfig {
   distDir: string;
   /** Output directory for generated .mdx files */
   outDir: string;
+  /**
+   * The lexicon's package.json, read for the version rendered into the docs
+   * (chant #1377). Defaults to `<distDir>/../package.json`. The manifest's
+   * version is only a fallback; it goes stale between bundles.
+   */
+  packageJsonPath?: string;
   /** Lexicon-specific overview content (markdown) */
   overview?: string;
   /** Output format description (e.g. "CloudFormation JSON template") */
@@ -21,8 +27,6 @@ export interface DocsConfig {
   serviceFromType?: (resourceType: string) => string;
   /** Custom sections to append to overview page */
   extraSections?: Array<{ title: string; content: string }>;
-  /** Standalone pages added to the sidebar after Overview */
-  extraPages?: Array<{ slug: string; title: string; description?: string; content: string; sidebar?: boolean }>;
   /** Slugs of auto-generated pages to suppress (e.g. "pseudo-parameters") */
   suppressPages?: string[];
   /** Source directory for scanning rule files (defaults to srcDir sibling of distDir) */
@@ -31,12 +35,36 @@ export interface DocsConfig {
   basePath?: string;
   /** Root directory for resolving {{file:...}} markers in extra page content */
   examplesDir?: string;
-  /** Extra sidebar entries appended after extraPages (supports Starlight groups) */
-  sidebarExtra?: Array<Record<string, unknown>>;
+  /**
+   * Directory of authored `.mdx` pages, each tagged with a Diátaxis quadrant
+   * (chant #1733). Defaults to `<outDir>/pages`. See docs-pages.ts. This is
+   * the only way a lexicon adds prose pages; `extraPages` (prose in docs.ts
+   * template literals) and `sidebarExtra` (hand-listed content files) were
+   * removed in chant #1757.
+   */
+  pagesDir?: string;
+}
+
+/** Diátaxis quadrant (https://diataxis.fr). */
+export type Quadrant = "tutorial" | "how-to" | "reference" | "explanation";
+
+/** One sidebar entry, as the quadrant-grouped sidebar builder sees it. */
+export interface SidebarPage {
+  slug: string;
+  label: string;
+  quadrant: Quadrant;
+  /** Nested subgroup label inside the quadrant. */
+  group?: string;
+  /** Lower sorts first within its group; unordered pages follow, by label. */
+  order?: number;
+  /** Keep out of the sidebar. */
+  hidden?: boolean;
 }
 
 export interface DocsResult {
   pages: Map<string, string>;
+  /** Every page the sidebar should list, authored and generated, by quadrant. */
+  sidebarPages: SidebarPage[];
   stats: {
     resources: number;
     properties: number;

package/src/codegen/docs.ts

@@ -12,17 +12,38 @@ import { join } from "path";
 import { fileURLToPath } from "url";
 
 import { expandFileMarkers } from "./docs-file-markers";
+import { readAuthoredPages } from "./docs-pages";
 import { scanRules, generateRules } from "./docs-rule-scanning";
 import { buildSidebar } from "./docs-sidebar";
 import { generateOverview, generateIntrinsics, generatePseudoParameters, generateSerialization } from "./docs-sections";
-import type { DocsConfig, DocsResult, ManifestJSON, MetaEntry } from "./docs-types";
+import type { DocsConfig, DocsResult, ManifestJSON, MetaEntry, SidebarPage } from "./docs-types";
 
 // Re-export all public types and functions so existing importers continue to work.
 export { expandFileMarkers } from "./docs-file-markers";
-export type { DocsConfig, DocsResult } from "./docs-types";
+export type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
+export { QUADRANTS, QUADRANT_LABELS, readAuthoredPages } from "./docs-pages";
 
 // ── Pipeline ───────────────────────────────────────────────────────
 
+/**
+ * The version rendered into the docs (chant #1377).
+ *
+ * `dist/manifest.json` is written by `npm run bundle`, which runs only under
+ * `prepack`, so its `version` is whatever was last bundled on this machine
+ * and can trail `package.json` by several releases. `package.json` is the
+ * source of truth and is never stale, so it wins whenever it is present.
+ * The manifest's own version is the fallback for a dist with no package
+ * beside it (test fixtures, relocated dist directories).
+ */
+export function lexiconVersion(config: DocsConfig, manifest: ManifestJSON): string {
+  const pkgPath = config.packageJsonPath ?? join(config.distDir, "..", "package.json");
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: unknown };
+    if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+  }
+  return manifest.version;
+}
+
 /**
  * Run the documentation pipeline with the supplied config.
  */
@@ -30,6 +51,7 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   const manifest = JSON.parse(
     readFileSync(join(config.distDir, "manifest.json"), "utf-8"),
   ) as ManifestJSON;
+  manifest.version = lexiconVersion(config, manifest);
 
   const meta = JSON.parse(
     readFileSync(join(config.distDir, "meta.json"), "utf-8"),
@@ -71,50 +93,47 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   }
   pages.set("index.mdx", overviewContent);
   const suppress = new Set(config.suppressPages ?? []);
-  const extraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
-
-  // Extra pages from lexicon config
-  if (config.extraPages) {
-    for (const page of config.extraPages) {
-      let content = page.content;
-      if (config.examplesDir) {
-        content = expandFileMarkers(content, config.examplesDir);
-      }
-      pages.set(
-        `${page.slug}.mdx`,
-        [
-          "---",
-          `title: "${page.title}"`,
-          page.description ? `description: "${page.description}"` : "",
-          "---",
-          "",
-          content,
-          "",
-        ]
-          .filter(Boolean)
-          .join("\n"),
-      );
-    }
+  const sidebarPages: SidebarPage[] = [];
+
+  // Authored pages under docs/pages/ (#1733). Each names its Diátaxis
+  // quadrant; the sidebar is grouped from that. Written with a provenance
+  // marker that points back at the source file.
+  const authored = readAuthoredPages(config);
+  const authoredSources = new Map<string, string>();
+  for (const page of authored) {
+    pages.set(`${page.slug}.mdx`, page.content);
+    authoredSources.set(`${page.slug}.mdx`, page.file);
+    if (!page.hidden) sidebarPages.push(page);
   }
 
-  // A generated page must not overwrite one the lexicon explicitly declared.
-  // The extraPages above are written into `pages` first, so an unguarded
-  // `pages.set` below silently discards them: helm declared its own
-  // "Intrinsics Reference" and pre-synth rules pages and shipped neither for
-  // as long as both slugs collided (#1312). Explicit authorship wins, and the
-  // collision is reported rather than resolved in silence.
+  const extraSlugs = new Set(authored.map((p) => p.slug));
+
+  // A generated page must not overwrite one the lexicon authored. Authored
+  // pages are written into `pages` first, so an unguarded `pages.set` below
+  // would silently discard them: helm once declared its own "Intrinsics
+  // Reference" and pre-synth rules pages and shipped neither for as long as
+  // both slugs collided (#1312). Authorship wins, and the collision is
+  // reported rather than resolved in silence.
   const claimed = (slug: string): boolean => {
     if (suppress.has(slug)) return true;
     if (!extraSlugs.has(slug)) return false;
     console.warn(
-      `[docs:${config.name}] extraPages declares "${slug}", which is also a generated page — keeping the declared one.\n` +
-        `  Add "${slug}" to suppressPages to make that explicit, or rename the extraPage if both are wanted.`,
+      `[docs:${config.name}] docs/pages/${slug}.mdx has the slug of a generated page — keeping the authored one.\n` +
+        `  Add "${slug}" to suppressPages to make that explicit, or rename the authored page if both are wanted.`,
     );
     return true;
   };
 
+  // Generated reference tables sort after authored reference pages, in the
+  // order the old flat sidebar listed them.
+  let generatedOrder = 1000;
+  const generated = (slug: string, label: string): void => {
+    sidebarPages.push({ slug, label, quadrant: "reference", order: generatedOrder++ });
+  };
+
   if (!claimed("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
     pages.set("intrinsics.mdx", generateIntrinsics(config, manifest));
+    generated("intrinsics", "Intrinsics");
   }
 
   if (
@@ -126,14 +145,21 @@ export function docsPipeline(config: DocsConfig): DocsResult {
       "pseudo-parameters.mdx",
       generatePseudoParameters(config, manifest),
     );
+    generated("pseudo-parameters", "Pseudo-Parameters");
   }
 
+  // Every lexicon links its generated rules table, whether or not it also
+  // ships a prose `lint-rules` page. Skipping it when one existed was how gcp
+  // ended up emitting a page nothing pointed at (#1312). The label
+  // distinguishes the generated table from a prose page.
   if (!claimed("rules") && rules.length > 0) {
     pages.set("rules.mdx", generateRules(config, rules));
+    generated("rules", "All Rules");
   }
 
   if (!claimed("serialization")) {
     pages.set("serialization.mdx", generateSerialization(config));
+    generated("serialization", "Serialization");
   }
 
   // Stamp every emitted page with its provenance. These files look exactly
@@ -142,11 +168,12 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   // intrinsics guide's #1044 claim were both fixed in the emitted `.mdx` and
   // silently reverted by the next regen (#1312).
   for (const [filename, content] of pages) {
-    pages.set(filename, withGeneratedMarker(config, content));
+    pages.set(filename, withGeneratedMarker(config, content, authoredSources.get(filename)));
   }
 
   return {
     pages,
+    sidebarPages,
     stats: {
       resources: resources.size,
       properties: properties.size,
@@ -163,8 +190,11 @@ export function docsPipeline(config: DocsConfig): DocsResult {
  * MDX parses `<!-- -->` as JSX rather than a comment, so this uses the
  * `{/* … *\/}` form the rest of the docs already use for generated markers.
  */
-function withGeneratedMarker(config: DocsConfig, content: string): string {
-  const marker = `{/* ${GENERATED_MARKER_TAG} by \`npm run docs -w @intentius/chant-lexicon-${config.name}\` — DO NOT EDIT.\n    Edit lexicons/${config.name}/src/codegen/docs.ts instead; changes here are overwritten. */}`;
+function withGeneratedMarker(config: DocsConfig, content: string, source?: string): string {
+  const edit = source
+    ? `Edit lexicons/${config.name}/docs/pages/${source} instead`
+    : `Edit lexicons/${config.name}/src/codegen/docs.ts instead`;
+  const marker = `{/* ${GENERATED_MARKER_TAG} by \`npm run docs -w @intentius/chant-lexicon-${config.name}\` — DO NOT EDIT.\n    ${edit}; changes here are overwritten. */}`;
   const lines = content.split("\n");
   // Frontmatter is the leading `---` … `---` block; the marker goes after it.
   if (lines[0] === "---") {
@@ -302,7 +332,7 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   if (unreachable.length > 0) {
     console.warn(
       `[docs:${config.name}] ${unreachable.length} page(s) in no sidebar entry — reachable only by direct URL: ${unreachable.join(", ")}.\n` +
-        `  Declare them in this lexicon's DocsConfig \`sidebarExtra\` (or \`extraPages\`) to surface them.`,
+        `  Move them to docs/pages/ with a \`diataxis\` field to surface them (chant #1731).`,
     );
   }
 
@@ -349,12 +379,20 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   mkdirSync(join(outDir, "src"), { recursive: true });
   writeFileSync(
     join(outDir, "src", "content.config.ts"),
-    `import { defineCollection } from 'astro:content';
+    `import { defineCollection, z } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
+        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+      }),
+    }),
+  }),
 };
 `,
   );

package/src/codegen/lexicon-regen.ts

@@ -25,6 +25,7 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync, type Dirent } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
+import { SNAPSHOT_UPDATE_ENV } from "./validate";
 import {
   extractSurface,
   diffSurface,
@@ -114,6 +115,17 @@ export interface RegenOptions {
    *   sha256:<64-hex-chars>  <relative-path-to-spec-file>
    */
   pinnedDigestPath?: string;
+  /**
+   * This run is about to rewrite the baseline snapshot (#1825).
+   *
+   * The `validate` step runs with {@link SNAPSHOT_UPDATE_ENV} set so its
+   * `surface-matches-snapshot` check is skipped. A lexicon whose snapshot gate
+   * runs in `"always"` mode (#1475) fails validate on a stale baseline, and a
+   * stale baseline is exactly what a re-baseline starts from — without this
+   * exemption the documented update flow deadlocks. Every other validate check
+   * still gates the run, so a broken generate cannot be baselined.
+   */
+  updatingSnapshot?: boolean;
 }
 
 // ── Pipeline ──────────────────────────────────────────────────────────
@@ -132,6 +144,7 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
     skipBuild = false,
     skipLint = false,
     skipExamples = true,
+    updatingSnapshot = false,
   } = opts;
 
   const failures: RegenFailure[] = [];
@@ -177,7 +190,12 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
   }
 
   // Step 4: validate
-  const validateFail = runScript(lexiconDir, "validate", process.env, verbose);
+  // A re-baseline run is exempt from the surface-matches-snapshot check only
+  // (#1825) — see RegenOptions.updatingSnapshot.
+  const validateEnv: NodeJS.ProcessEnv = updatingSnapshot
+    ? { ...process.env, [SNAPSHOT_UPDATE_ENV]: "1" }
+    : process.env;
+  const validateFail = runScript(lexiconDir, "validate", validateEnv, verbose);
   if (validateFail) {
     failures.push(validateFail);
   }
@@ -524,13 +542,15 @@ function makeResult(
     added: [],
     changed: [],
     removed: [],
+    renamed: [],
     severity: "none",
   };
   const effectiveDelta = delta ?? emptyDelta;
   const changed =
     effectiveDelta.added.length > 0 ||
     effectiveDelta.changed.length > 0 ||
-    effectiveDelta.removed.length > 0;
+    effectiveDelta.removed.length > 0 ||
+    effectiveDelta.renamed.length > 0;
   const deltaText = changed ? formatDelta(effectiveDelta) : "";
 
   return {

package/src/codegen/rolling-upgrade.test.ts

@@ -93,7 +93,7 @@ function makeRegen(
   return async () => {
     const delta = fresh
       ? diffSurface(baseline, fresh)
-      : { added: [], changed: [], removed: [], severity: "none" as const };
+      : { added: [], changed: [], removed: [], renamed: [], severity: "none" as const };
     const changed =
       delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0;
     return {

package/src/codegen/rolling-upgrade.ts

@@ -293,7 +293,7 @@ export function classifyDelta(delta: SurfaceDelta): {
   severity: ChangeSeverity;
 } {
   const hasUpgrade =
-    delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0;
+    delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0 || delta.renamed.length > 0;
   return { hasUpgrade, severity: hasUpgrade ? delta.severity : "none" };
 }
 

package/src/codegen/surface-snapshot.test.ts

@@ -428,6 +428,133 @@ describe("serializeSnapshot / parseSnapshot", () => {
 
 // ── formatDelta ───────────────────────────────────────────────────────
 
+describe("diffSurface — renames (#1460)", () => {
+  test("a removal and an addition with the same resourceType pair as one rename", () => {
+    const baseline = makeSnapshot({
+      MacieSession: { kind: "resource", resourceType: "AWS::Macie::Session", props: ["Status:false"] },
+    });
+    const fresh = makeSnapshot({
+      Session: { kind: "resource", resourceType: "AWS::Macie::Session", props: ["Status:false"] },
+    });
+    const delta = diffSurface(baseline, fresh);
+    expect(delta.added).toEqual([]);
+    expect(delta.removed).toEqual([]);
+    expect(delta.renamed).toEqual([
+      { from: "MacieSession", to: "Session", entry: fresh.entries.Session },
+    ]);
+    // The old import still breaks, so a rename stays breaking for 1.x.
+    expect(delta.severity).toBe("breaking");
+  });
+
+  test("property types rename the same way, and a same-kind match is required", () => {
+    const baseline = makeSnapshot({
+      BCMDataExportsExport_DataQuery: { kind: "property", resourceType: "AWS::BCMDataExports::Export.DataQuery" },
+      Thing: { kind: "resource", resourceType: "X::Thing" },
+    });
+    const fresh = makeSnapshot({
+      Export_DataQuery: { kind: "property", resourceType: "AWS::BCMDataExports::Export.DataQuery" },
+      Thing_Prop: { kind: "property", resourceType: "X::Thing" },
+    });
+    const delta = diffSurface(baseline, fresh);
+    expect(delta.renamed.map((r) => `${r.from} -> ${r.to}`)).toEqual([
+      "BCMDataExportsExport_DataQuery -> Export_DataQuery",
+    ]);
+    // A resource and a property under the same type string are not a rename.
+    expect(delta.removed.map((r) => r.name)).toEqual(["Thing"]);
+    expect(delta.added.map((a) => a.name)).toEqual(["Thing_Prop"]);
+    expect(delta.severity).toBe("breaking");
+  });
+
+  test("a rename that also changed shape carries the structural diff", () => {
+    const baseline = makeSnapshot({
+      PanoramaPackage: { kind: "resource", resourceType: "AWS::Panorama::Package", props: ["PackageName:true", "Tags:false"] },
+    });
+    const fresh = makeSnapshot({
+      Package: { kind: "resource", resourceType: "AWS::Panorama::Package", props: ["PackageName:true"], attrs: ["Arn"] },
+    });
+    const delta = diffSurface(baseline, fresh);
+    expect(delta.renamed).toHaveLength(1);
+    expect(delta.renamed[0].changes).toEqual({ removedProps: ["Tags"], addedAttrs: ["Arn"] });
+    expect(delta.changed).toEqual([]);
+  });
+
+  test("several old and new names under one resourceType pair by similarity; the rest stay add/remove", () => {
+    const rt = "AWS::SageMaker::Space";
+    const baseline = makeSnapshot({
+      Space_OwnershipSettings: { kind: "property", resourceType: rt },
+      Space_SpaceSettings: { kind: "property", resourceType: rt },
+      Space_Gone: { kind: "property", resourceType: rt },
+    });
+    const fresh = makeSnapshot({
+      SageMakerSpace_SpaceSettings: { kind: "property", resourceType: rt },
+      SageMakerSpace_OwnershipSettings: { kind: "property", resourceType: rt },
+    });
+    const delta = diffSurface(baseline, fresh);
+    expect(delta.renamed.map((r) => `${r.from} -> ${r.to}`)).toEqual([
+      "Space_OwnershipSettings -> SageMakerSpace_OwnershipSettings",
+      "Space_SpaceSettings -> SageMakerSpace_SpaceSettings",
+    ]);
+    expect(delta.removed.map((r) => r.name)).toEqual(["Space_Gone"]);
+    expect(delta.added).toEqual([]);
+  });
+
+  test("entries with an empty resourceType never pair", () => {
+    const baseline = makeSnapshot({ A: { kind: "property", resourceType: "" } });
+    const fresh = makeSnapshot({ B: { kind: "property", resourceType: "" } });
+    const delta = diffSurface(baseline, fresh);
+    expect(delta.renamed).toEqual([]);
+    expect(delta.removed).toHaveLength(1);
+    expect(delta.added).toHaveLength(1);
+  });
+
+  test("the #1423 shape: 28 renames among 148 removals and 83 additions", () => {
+    // 3 resources renamed, each dragging 25/3-ish property types with them —
+    // 28 renames in total, 120 plain removals, 55 plain additions.
+    const baseEntries: SurfaceSnapshot["entries"] = {};
+    const freshEntries: SurfaceSnapshot["entries"] = {};
+
+    const renamedResources: Array<[string, string, string]> = [
+      ["MacieSession", "Session", "AWS::Macie::Session"],
+      ["PanoramaPackage", "Package", "AWS::Panorama::Package"],
+      ["Space", "SageMakerSpace", "AWS::SageMaker::Space"],
+    ];
+    let renames = 0;
+    for (const [oldName, newName, rt] of renamedResources) {
+      baseEntries[oldName] = { kind: "resource", resourceType: rt };
+      freshEntries[newName] = { kind: "resource", resourceType: rt };
+      renames++;
+    }
+    // 25 property renames spread across the three parents
+    for (let i = 0; i < 25; i++) {
+      const [oldName, newName, rt] = renamedResources[i % 3];
+      baseEntries[`${oldName}_Prop${i}`] = { kind: "property", resourceType: `${rt}.Prop${i}` };
+      freshEntries[`${newName}_Prop${i}`] = { kind: "property", resourceType: `${rt}.Prop${i}` };
+      renames++;
+    }
+    expect(renames).toBe(28);
+
+    for (let i = 0; i < 120; i++) {
+      baseEntries[`Gone${i}`] = { kind: "resource", resourceType: `AWS::Gone::Type${i}` };
+    }
+    for (let i = 0; i < 55; i++) {
+      freshEntries[`Fresh${i}`] = { kind: "resource", resourceType: `AWS::Fresh::Type${i}` };
+    }
+
+    const delta = diffSurface(makeSnapshot(baseEntries), makeSnapshot(freshEntries));
+    expect(delta.renamed).toHaveLength(28);
+    expect(delta.removed).toHaveLength(120);
+    expect(delta.added).toHaveLength(55);
+    expect(delta.severity).toBe("breaking");
+
+    const text = formatDelta(delta);
+    expect(text).toContain("Renamed (28):");
+    expect(text).toContain("Removed (120):");
+    expect(text).toContain("Added (55):");
+    expect(text).toContain("  ~ MacieSession -> Session [resource] (AWS::Macie::Session)");
+    expect(text).toContain("Severity: breaking");
+  });
+});
+
 describe("formatDelta", () => {
   test("includes severity in output", () => {
     const delta = diffSurface(
@@ -457,5 +584,17 @@ describe("formatDelta", () => {
     expect(text).toContain("Added (1):");
     expect(text).toContain("Removed (1):");
     expect(text).toContain("Changed (1):");
+    expect(text).not.toContain("Renamed");
+  });
+
+  test("renames print as Old -> New with the shared resourceType", () => {
+    const baseline = makeSnapshot({ Old: { kind: "resource", resourceType: "X" } });
+    const fresh = makeSnapshot({ New: { kind: "resource", resourceType: "X" } });
+    const text = formatDelta(diffSurface(baseline, fresh));
+    expect(text).toContain("Renamed (1):");
+    expect(text).toContain("  ~ Old -> New [resource] (X)");
+    expect(text).not.toContain("Added (");
+    expect(text).not.toContain("Removed (");
+    expect(text).toContain("Severity: breaking");
   });
 });