@intentius/chant 0.44.13 → 0.45.0

package/src/codegen/docs-pages.test.ts

@@ -0,0 +1,194 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+
+import { readAuthoredPages } from "./docs-pages";
+import { docsPipeline, writeDocsSite, GENERATED_MARKER_TAG } from "./docs";
+import { buildSidebar, quadrantItems } from "./docs-sidebar";
+import type { DocsConfig, DocsResult, SidebarPage } from "./docs-types";
+
+let root: string;
+
+function config(overrides: Partial<DocsConfig> = {}): DocsConfig {
+  return {
+    name: "fixture",
+    displayName: "Fixture",
+    description: "fixture lexicon",
+    distDir: join(root, "dist"),
+    outDir: join(root, "docs"),
+    srcDir: join(root, "src"),
+    examplesDir: join(root, "examples"),
+    basePath: "/chant/lexicons/fixture/",
+    ...overrides,
+  };
+}
+
+function page(name: string, frontmatter: string, body = "Body.\n"): void {
+  mkdirSync(join(root, "docs", "pages"), { recursive: true });
+  writeFileSync(join(root, "docs", "pages", name), `---\n${frontmatter}\n---\n\n${body}`);
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "chant-docs-pages-"));
+  mkdirSync(join(root, "dist"), { recursive: true });
+  mkdirSync(join(root, "src"), { recursive: true });
+  mkdirSync(join(root, "examples"), { recursive: true });
+  writeFileSync(
+    join(root, "dist", "manifest.json"),
+    JSON.stringify({ name: "fixture", version: "0.0.0", intrinsics: [{ name: "ref", description: "a ref" }] }),
+  );
+  writeFileSync(join(root, "dist", "meta.json"), JSON.stringify({}));
+  writeFileSync(join(root, "examples", "snippet.ts"), "export const x = 1;\n");
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("readAuthoredPages", () => {
+  test("returns nothing when docs/pages/ does not exist", () => {
+    expect(readAuthoredPages(config())).toEqual([]);
+  });
+
+  test("reads frontmatter, expands file markers, strips sidebar-only keys", () => {
+    page(
+      "getting-started.mdx",
+      'title: "Getting Started"\ndescription: "Start here"\ndiataxis: tutorial\norder: 1\ngroup: "Intro"\nlabel: "Start"\nhidden: false',
+      "Before\n\n{{file:snippet.ts}}\n\nAfter\n",
+    );
+    const [p] = readAuthoredPages(config());
+    expect(p.slug).toBe("getting-started");
+    expect(p.quadrant).toBe("tutorial");
+    expect(p.order).toBe(1);
+    expect(p.group).toBe("Intro");
+    expect(p.label).toBe("Start");
+    expect(p.hidden).toBe(false);
+    expect(p.content).toContain('```typescript title="snippet.ts"\nexport const x = 1;\n```');
+    expect(p.content).toContain("diataxis: tutorial");
+    expect(p.content).not.toMatch(/^(order|group|label|hidden):/m);
+    expect(p.content).toContain('title: "Getting Started"');
+  });
+
+  test("label defaults to title", () => {
+    page("x.mdx", "title: Plain Title\ndiataxis: reference");
+    expect(readAuthoredPages(config())[0].label).toBe("Plain Title");
+  });
+
+  test("missing diataxis throws with the file path", () => {
+    page("untagged.mdx", "title: Untagged");
+    expect(() => readAuthoredPages(config())).toThrow(/untagged\.mdx.*diataxis/);
+  });
+
+  test("unknown diataxis value throws", () => {
+    page("bad.mdx", "title: Bad\ndiataxis: guide");
+    expect(() => readAuthoredPages(config())).toThrow(/"guide" is not one of/);
+  });
+});
+
+describe("docsPipeline with authored pages", () => {
+  test("authored page wins a slug collision with a generated page", () => {
+    page("intrinsics.mdx", "title: My Intrinsics\ndiataxis: reference", "Hand-written.\n");
+    const result = docsPipeline(config());
+    expect(result.pages.get("intrinsics.mdx")).toContain("Hand-written.");
+    expect(result.sidebarPages.filter((p) => p.slug === "intrinsics")).toHaveLength(1);
+  });
+
+  test("generated reference pages land in the reference quadrant after authored ones", () => {
+    page("howto.mdx", "title: Do It\ndiataxis: how-to");
+    const result = docsPipeline(config());
+    const ref = result.sidebarPages.filter((p) => p.quadrant === "reference").map((p) => p.slug);
+    expect(ref).toEqual(["intrinsics", "serialization"]);
+    expect(result.sidebarPages.find((p) => p.slug === "howto")?.quadrant).toBe("how-to");
+  });
+
+  test("hidden pages are written but kept out of the sidebar", () => {
+    page("secret.mdx", "title: Secret\ndiataxis: reference\nhidden: true");
+    const result = docsPipeline(config());
+    expect(result.pages.has("secret.mdx")).toBe(true);
+    expect(result.sidebarPages.some((p) => p.slug === "secret")).toBe(false);
+  });
+
+  test("authored pages carry a provenance marker naming the source file", () => {
+    page("howto.mdx", "title: Do It\ndiataxis: how-to");
+    const result = docsPipeline(config());
+    const out = result.pages.get("howto.mdx") as string;
+    expect(out).toContain(GENERATED_MARKER_TAG);
+    expect(out).toContain("docs/pages/howto.mdx");
+  });
+
+  test("writeDocsSite reaps the written copy once the source is removed", () => {
+    page("howto.mdx", "title: Do It\ndiataxis: how-to");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    const written = join(root, "docs", "src", "content", "docs", "howto.mdx");
+    expect(existsSync(written)).toBe(true);
+    rmSync(join(root, "docs", "pages", "howto.mdx"));
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(existsSync(written)).toBe(false);
+    const astro = readFileSync(join(root, "docs", "astro.config.mjs"), "utf-8");
+    expect(astro).not.toContain("howto");
+    const schema = readFileSync(join(root, "docs", "src", "content.config.ts"), "utf-8");
+    expect(schema).toContain("diataxis");
+  });
+});
+
+describe("buildSidebar", () => {
+  const sb = (pages: SidebarPage[]) =>
+    buildSidebar(config(), { pages: new Map(), sidebarPages: pages, stats: { resources: 0, properties: 0, services: 0, rules: 0, intrinsics: 0 } } satisfies DocsResult);
+
+  test("groups in fixed quadrant order and omits empty quadrants", () => {
+    const items = sb([
+      { slug: "why", label: "Why", quadrant: "explanation" },
+      { slug: "start", label: "Start", quadrant: "tutorial" },
+      { slug: "rules", label: "All Rules", quadrant: "reference", order: 1000 },
+    ]);
+    expect(items.map((i) => i.label)).toEqual(["← chant docs", "Overview", "Tutorials", "Reference", "Explanation"]);
+  });
+
+  test("orders by order then label and nests groups after loose pages", () => {
+    const items = quadrantItems([
+      { slug: "b", label: "Bravo", quadrant: "reference" },
+      { slug: "a", label: "Alpha", quadrant: "reference" },
+      { slug: "z", label: "Zulu", quadrant: "reference", order: 0 },
+      { slug: "eks", label: "EKS", quadrant: "reference", group: "Vendor" },
+      { slug: "aks", label: "AKS", quadrant: "reference", group: "Vendor" },
+    ]);
+    expect(items).toEqual([
+      { label: "Zulu", slug: "z" },
+      { label: "Alpha", slug: "a" },
+      { label: "Bravo", slug: "b" },
+      { label: "Vendor", items: [{ label: "AKS", slug: "aks" }, { label: "EKS", slug: "eks" }] },
+    ]);
+  });
+});
+
+/**
+ * chant #1377 — `dist/manifest.json` is written by `npm run bundle` (prepack
+ * only), so its version is whatever was last bundled on the machine; on one
+ * checkout it put the fountain docs two minor versions behind what was
+ * already committed. `package.json` is the source of truth, so the rendered
+ * version comes from there and the manifest is only a fallback.
+ */
+describe("lexicon version in generated docs comes from package.json (#1377)", () => {
+  test("package.json beside dist/ wins over a stale manifest", () => {
+    writeFileSync(join(root, "package.json"), JSON.stringify({ name: "fixture", version: "0.37.2" }));
+    const index = docsPipeline(config()).pages.get("index.mdx");
+    expect(index).toContain("**Lexicon version:** 0.37.2");
+    expect(index).not.toContain("0.0.0");
+  });
+
+  test("packageJsonPath overrides the default location", () => {
+    mkdirSync(join(root, "elsewhere"), { recursive: true });
+    writeFileSync(join(root, "elsewhere", "package.json"), JSON.stringify({ version: "1.2.3" }));
+    const index = docsPipeline(config({ packageJsonPath: join(root, "elsewhere", "package.json") })).pages.get(
+      "index.mdx",
+    );
+    expect(index).toContain("**Lexicon version:** 1.2.3");
+  });
+
+  test("falls back to the manifest when no package.json is present", () => {
+    const index = docsPipeline(config()).pages.get("index.mdx");
+    expect(index).toContain("**Lexicon version:** 0.0.0");
+  });
+});

package/src/codegen/docs-pages.ts

@@ -0,0 +1,138 @@
+/**
+ * Authored lexicon doc pages (chant #1731 / #1733).
+ *
+ * A lexicon's prose lives as `.mdx` files under `lexicons/<name>/docs/pages/`.
+ * Each carries a `diataxis` frontmatter field naming its Diátaxis quadrant
+ * (https://diataxis.fr). The pipeline expands `{{file:...}}` markers, stamps a
+ * provenance marker and writes the result into `src/content/docs/`, and the
+ * sidebar is grouped from the field. This replaced two older modes — prose
+ * inside `docs.ts` template literals (`extraPages`) and hand-written content
+ * pages wired through `sidebarExtra` — removed in chant #1757.
+ *
+ * Frontmatter recognised here, on top of Starlight's `title` / `description`:
+ *
+ * - `diataxis`: `tutorial | how-to | reference | explanation`. Required.
+ * - `label`: sidebar label; defaults to `title`.
+ * - `group`: a nested subgroup label inside the quadrant (e.g. "Vendor Composites").
+ * - `order`: number; lower sorts first within its group. Unordered pages follow, by label.
+ * - `hidden`: `true` keeps the page out of the sidebar (reachable by URL only).
+ *
+ * `group` / `order` / `hidden` / `label` are stripped from the written copy so
+ * Starlight's schema never sees them; `diataxis` stays, and the generated
+ * `content.config.ts` declares it.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+
+import { expandFileMarkers } from "./docs-file-markers";
+import type { DocsConfig, Quadrant, SidebarPage } from "./docs-types";
+
+export const QUADRANTS: readonly Quadrant[] = ["tutorial", "how-to", "reference", "explanation"];
+
+/** Sidebar group label for each quadrant, in display order. */
+export const QUADRANT_LABELS: Record<Quadrant, string> = {
+  tutorial: "Tutorials",
+  "how-to": "How-to guides",
+  reference: "Reference",
+  explanation: "Explanation",
+};
+
+export interface AuthoredPage extends SidebarPage {
+  /** Source file name under `pagesDir`, e.g. `getting-started.mdx`. */
+  file: string;
+  /** Page body with the rewritten frontmatter, markers expanded. */
+  content: string;
+}
+
+interface Frontmatter {
+  fields: Map<string, string>;
+  /** Raw frontmatter lines, in order, so unknown keys survive the rewrite. */
+  lines: string[];
+  body: string;
+}
+
+function parseFrontmatter(text: string, file: string): Frontmatter {
+  if (!text.startsWith("---\n")) {
+    throw new Error(`${file}: authored doc page must start with a frontmatter block`);
+  }
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) throw new Error(`${file}: unterminated frontmatter`);
+  const lines = text.slice(4, end).split("\n");
+  const fields = new Map<string, string>();
+  for (const line of lines) {
+    const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (m) fields.set(m[1], m[2].trim());
+  }
+  // Skip the closing `---` and the newline after it.
+  const afterClose = text.indexOf("\n", end + 1);
+  const body = afterClose === -1 ? "" : text.slice(afterClose + 1);
+  return { fields, lines, body };
+}
+
+function unquote(v: string): string {
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    try {
+      return v.startsWith('"') ? (JSON.parse(v) as string) : v.slice(1, -1);
+    } catch {
+      return v.slice(1, -1);
+    }
+  }
+  return v;
+}
+
+/** Keys this module consumes and removes from the written page. */
+const SIDEBAR_KEYS = new Set(["label", "group", "order", "hidden"]);
+
+/**
+ * Read every authored page under `pagesDir`. Returns an empty list when the
+ * directory does not exist, which is every lexicon before it migrates.
+ */
+export function readAuthoredPages(config: DocsConfig): AuthoredPage[] {
+  const pagesDir = config.pagesDir ?? join(config.outDir, "pages");
+  if (!existsSync(pagesDir)) return [];
+
+  const pages: AuthoredPage[] = [];
+  for (const file of readdirSync(pagesDir).sort()) {
+    if (!file.endsWith(".mdx") && !file.endsWith(".md")) continue;
+    const path = join(pagesDir, file);
+    const { fields, lines, body } = parseFrontmatter(readFileSync(path, "utf-8"), path);
+
+    const title = fields.get("title");
+    if (!title) throw new Error(`${path}: frontmatter needs a title`);
+    const quadrant = fields.get("diataxis");
+    if (!quadrant) {
+      throw new Error(
+        `${path}: frontmatter needs \`diataxis: ${QUADRANTS.join(" | ")}\` (https://diataxis.fr)`,
+      );
+    }
+    if (!QUADRANTS.includes(quadrant as Quadrant)) {
+      throw new Error(`${path}: diataxis "${quadrant}" is not one of ${QUADRANTS.join(", ")}`);
+    }
+
+    const orderRaw = fields.get("order");
+    const order = orderRaw === undefined ? undefined : Number(orderRaw);
+    if (order !== undefined && Number.isNaN(order)) {
+      throw new Error(`${path}: order must be a number, got "${orderRaw}"`);
+    }
+
+    const kept = lines.filter((line) => {
+      const key = line.match(/^([A-Za-z_][\w-]*):/)?.[1];
+      return !(key && SIDEBAR_KEYS.has(key));
+    });
+    let content = body;
+    if (config.examplesDir) content = expandFileMarkers(content, config.examplesDir);
+
+    pages.push({
+      file,
+      slug: file.replace(/\.mdx?$/, ""),
+      label: unquote(fields.get("label") ?? title),
+      quadrant: quadrant as Quadrant,
+      group: fields.has("group") ? unquote(fields.get("group") as string) : undefined,
+      order,
+      hidden: fields.get("hidden") === "true",
+      content: ["---", ...kept, "---", "", content].join("\n"),
+    });
+  }
+  return pages;
+}

package/src/codegen/docs-sections.ts

@@ -42,14 +42,6 @@ export function generateOverview(
 
   const suppress = new Set(config.suppressPages ?? []);
 
-  // Extra pages listed first in reference links
-  if (config.extraPages && config.extraPages.length > 0) {
-    for (const page of config.extraPages) {
-      if (page.sidebar === false) continue;
-      lines.push(`- [${page.title}](./${page.slug})`);
-    }
-  }
-
   if (!suppress.has("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
     lines.push(
       `- [Intrinsic Functions](./intrinsics) — ${manifest.intrinsics.length} built-in functions`,

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;