@intentius/chant 0.44.14 → 0.45.0

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

@@ -524,13 +524,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");
   });
 });