@intentius/chant 0.124.27 → 0.124.28

package/src/change-set-graph.ts

@@ -0,0 +1,133 @@
+/**
+ * Place a change set's entries on the graph (#4022).
+ *
+ * A reader such as behold draws the graph `chant graph --format ir` and
+ * `chant workspace graph` print, and wants each change of a change set on the
+ * node it changes. The planner's address is not that node's id: a terraform
+ * plan names an instance, `module.app.terraform_data.instance[0]`, where the
+ * graph has one node per block, `<root>/module.app/terraform_data.instance`
+ * (the terraform lexicon's entity key, `hcl/parse.ts`). So chant maps the
+ * address itself, against the node ids of the graph it read, and a reader
+ * never derives an id.
+ *
+ * {@link changeSetNodeCandidates} lists the ids an entry's address can have,
+ * by planner. {@link mapChangeSetToGraph} keeps the first that the graph
+ * holds and puts the member's name in front, as `chant workspace graph`
+ * does. An entry whose address the graph does not hold gets `node: null`:
+ * a delete of a block the source no longer declares, or a warden or sql
+ * change outside the graph.
+ *
+ * Like `./change-set.ts`, this imports nothing at run time, so it bundles
+ * into one file with the change-set code.
+ */
+
+import type { ChangeSetDocument, ChangeSetEntry } from "./change-set";
+
+/** The graph a document is mapped onto: the node ids of one member's own IR. */
+export interface ChangeSetGraphNodes {
+  /** The workspace member whose graph it is, its path of names joined with `/` when nested, or null outside a workspace. */
+  member: string | null;
+  /** The commit the graph was read at, or null when unknown. */
+  at: string | null;
+  /** Every node id of the member's `chant graph --format ir`, without the member in front. */
+  ids: Iterable<string>;
+}
+
+/**
+ * Split a terraform address into its dot-separated parts, dropping every
+ * `[...]` index. A quoted key may hold `.` or `]`, so quotes are honoured.
+ */
+function terraformParts(address: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quoted = false;
+  for (let i = 0; i < address.length; i++) {
+    const c = address[i];
+    if (depth > 0) {
+      if (quoted) {
+        if (c === "\\") i++;
+        else if (c === '"') quoted = false;
+      } else if (c === '"') quoted = true;
+      else if (c === "]") depth--;
+      continue;
+    }
+    if (c === "[") depth++;
+    else if (c === ".") {
+      parts.push(current);
+      current = "";
+    } else current += c;
+  }
+  parts.push(current);
+  return parts.filter((p) => p.length > 0);
+}
+
+/**
+ * The block key the terraform lexicon gives an address in its root:
+ * `module.<call>/` for each module call, then the block's own address with
+ * no index. `module.app.terraform_data.instance[0]` is
+ * `module.app/terraform_data.instance`.
+ */
+export function terraformBlockKey(address: string): string | undefined {
+  const parts = terraformParts(address);
+  const scope: string[] = [];
+  let i = 0;
+  while (parts[i] === "module" && i + 1 < parts.length) {
+    scope.push(`module.${parts[i + 1]}`);
+    i += 2;
+  }
+  const rest = parts.slice(i);
+  let block: string | undefined;
+  if (rest[0] === "data" && rest.length >= 3) block = `data.${rest[1]}.${rest[2]}`;
+  else if (rest.length >= 2) block = `${rest[0]}.${rest[1]}`;
+  else if (rest.length === 0 && scope.length > 0) {
+    // The module call itself is a block of its caller.
+    const call = scope.pop()!;
+    block = call;
+  }
+  if (block === undefined) return undefined;
+  return [...scope, block].join("/");
+}
+
+/**
+ * The ids, in the order tried, that an entry's address can have in its
+ * member's graph IR:
+ *
+ * - `chant`: the address, which is the entity name the IR uses as its id.
+ * - `terraform`, `tofu`, `choudoufu`: `<root>/<block key>`, the root being
+ *   the change-set member (`terraformBlockKey`), then the address.
+ * - `warden`, `sql`: the address.
+ */
+export function changeSetNodeCandidates(entry: Pick<ChangeSetEntry, "member" | "planner" | "address">): string[] {
+  switch (entry.planner) {
+    case "terraform":
+    case "tofu":
+    case "choudoufu": {
+      const key = terraformBlockKey(entry.address);
+      return key === undefined ? [entry.address] : [`${entry.member}/${key}`, entry.address];
+    }
+    default:
+      return [entry.address];
+  }
+}
+
+/**
+ * The document with each entry's `node` set from `graph`, and `graph`
+ * recording which graph it was. A null `graph` (none could be read) gives
+ * every entry `node: null`. The digest is unchanged: `node` is not hashed.
+ */
+export function mapChangeSetToGraph(doc: ChangeSetDocument, graph: ChangeSetGraphNodes | null): ChangeSetDocument {
+  if (graph === null) {
+    return { ...doc, entries: doc.entries.map((e) => ({ ...e, node: null })), graph: null };
+  }
+  const ids = new Set(graph.ids);
+  const prefix = graph.member ? `${graph.member}/` : "";
+  return {
+    ...doc,
+    entries: doc.entries.map((e) => {
+      const id = changeSetNodeCandidates(e).find((c) => ids.has(c));
+      return { ...e, node: id === undefined ? null : `${prefix}${id}` };
+    }),
+    graph: { member: graph.member, at: graph.at },
+  };
+}

package/src/change-set.ts

@@ -113,6 +113,15 @@ export interface ChangeSetEntry {
   /** The estate, environment or org the change lands in. */
   scope?: string;
   attributes: ChangeSetAttribute[];
+  /**
+   * The graph node the entry changes, as `chant graph --format ir` and
+   * `chant workspace graph` name it (#4022): `<member>/<id>` inside a
+   * workspace. Null when the graph holds no node for the address, such as
+   * a delete of a block the source no longer declares. Absent until the
+   * document is mapped onto a graph (`./change-set-graph.ts`), and never
+   * part of the digest.
+   */
+  node?: string | null;
 }
 
 /** Something a planner could not read, so the plan says nothing about it. */
@@ -201,6 +210,30 @@ export interface ChangeSetDocument {
   /** Triggered actions, sorted by member and address. Absent when no member runs one. */
   sideEffects?: ChangeSetSideEffect[];
   summary: ChangeSetSummary;
+  /**
+   * The graph the entries' `node` ids come from (#4022): the workspace member
+   * whose graph it is, or null outside a workspace, and the commit it was
+   * read at, or null when that is unknown. Null when no graph could be read,
+   * so every `node` is null. Absent on a document never mapped. Not hashed.
+   */
+  graph?: ChangeSetGraph | null;
+  /**
+   * The release this change set was planned for (#4045): the `releaseDigest`
+   * of the release a `components promote --release` deploys. Set with
+   * `environment` on a release gate's document, absent on every other. Part
+   * of the digest when present, so a stored document names the one release
+   * and environment its gate bound, and two releases whose plans read the
+   * same never share a document or an approval.
+   */
+  releaseDigest?: string;
+  /** The environment this change set was planned for (#4045), set with `releaseDigest`. Part of the digest when present. */
+  environment?: string;
+}
+
+/** Where a document's node ids come from. */
+export interface ChangeSetGraph {
+  member: string | null;
+  at: string | null;
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -235,22 +268,39 @@ export function changeSetDigest(members: ReadonlyArray<Pick<ChangeSetMember, "me
 /**
  * The document's digest: `computePlanDigest("change-set-document", …)` over
  * the set digest ({@link changeSetDigest}), each member's name, status and
- * holes, the entries and the side effects. Members are sorted by name and
+ * holes, the entries (without their graph `node`) and the side effects.
+ * Members are sorted by name and
  * entries and side effects by the keys {@link composeChangeSet} sorts them by,
  * so order makes no difference.
  *
  * A provisional member is left out, with its entries and side effects, as
  * the set digest leaves it out: no approval of the document covers it.
+ *
+ * A release gate's document (#4045) also hashes the `releaseDigest` and
+ * `environment` it was planned for. A document without them hashes as it
+ * always has, so no earlier digest moves.
  */
-export function changeSetDocumentDigest(doc: Pick<ChangeSetDocument, "members" | "entries" | "sideEffects">): string {
+export function changeSetDocumentDigest(
+  doc: Pick<ChangeSetDocument, "members" | "entries" | "sideEffects" | "releaseDigest" | "environment">,
+): string {
   const provisional = new Set(doc.members.filter((m) => m.provisional === true).map((m) => m.member));
   const members = doc.members
     .filter((m) => !provisional.has(m.member))
     .map((m) => ({ member: m.member, status: m.status, holes: m.holes }))
     .sort((a, b) => byString(a.member, b.member));
-  const entries = doc.entries.filter((e) => !provisional.has(e.member)).sort((a, b) => byString(entryKey(a), entryKey(b)));
+  // An entry's graph node (#4022) says where on the graph the change is,
+  // not what the plan does, so it stays outside the digest: mapping a stored
+  // document onto a graph never moves the value its gate bound.
+  const entries = doc.entries
+    .filter((e) => !provisional.has(e.member))
+    .map(({ node: _node, ...e }) => e)
+    .sort((a, b) => byString(entryKey(a), entryKey(b)));
   const sideEffects = (doc.sideEffects ?? []).filter((s) => !provisional.has(s.member)).sort(bySideEffect);
-  return computePlanDigest("change-set-document", { set: changeSetDigest(doc.members), members, entries, sideEffects });
+  const planned =
+    doc.releaseDigest !== undefined || doc.environment !== undefined
+      ? { planned: { releaseDigest: doc.releaseDigest ?? null, environment: doc.environment ?? null } }
+      : {};
+  return computePlanDigest("change-set-document", { set: changeSetDigest(doc.members), members, entries, sideEffects, ...planned });
 }
 
 /** The summary of a set of members and entries. */
@@ -296,6 +346,8 @@ function sortKeys<T>(o: Record<string, T>): Record<string, T> {
 export interface ComposeChangeSetOptions {
   /** The chant version to record in `chant`. */
   chant?: string;
+  /** The release and environment a release gate's change set was planned for (#4045), recorded and hashed. */
+  planned?: { releaseDigest: string; environment: string };
 }
 
 /**
@@ -317,12 +369,14 @@ export function composeChangeSet(parts: ReadonlyArray<ChangeSetPart>, options: C
   const sideEffects: ChangeSetSideEffect[] = parts
     .flatMap((p) => (p.sideEffects ?? []).map((s) => ({ member: p.member.member, ...s })))
     .sort(bySideEffect);
-  const digest = changeSetDocumentDigest({ members, entries, sideEffects });
+  const planned = options.planned ? { releaseDigest: options.planned.releaseDigest, environment: options.planned.environment } : {};
+  const digest = changeSetDocumentDigest({ members, entries, sideEffects, ...planned });
   return {
     $schema: CHANGE_SET_SCHEMA_ID,
     contract: CHANGE_SET_CONTRACT,
     ...(options.chant !== undefined ? { chant: options.chant } : {}),
     digest,
+    ...planned,
     members,
     entries,
     ...(sideEffects.length > 0 ? { sideEffects } : {}),
@@ -335,7 +389,9 @@ export function composeChangeSet(parts: ReadonlyArray<ChangeSetPart>, options: C
  * effects give ({@link changeSetDocumentDigest}). A document that names a
  * member twice has no digest and is not verified.
  */
-export function verifyChangeSetDigest(doc: Pick<ChangeSetDocument, "digest" | "members" | "entries" | "sideEffects">): boolean {
+export function verifyChangeSetDigest(
+  doc: Pick<ChangeSetDocument, "digest" | "members" | "entries" | "sideEffects" | "releaseDigest" | "environment">,
+): boolean {
   try {
     return changeSetDocumentDigest(doc) === doc.digest;
   } catch {
@@ -343,6 +399,20 @@ export function verifyChangeSetDigest(doc: Pick<ChangeSetDocument, "digest" | "m
   }
 }
 
+/**
+ * Whether a change set changes nothing (ws-104 question 6, #4045): it has at
+ * least one member, every member planned, none failed or provisional, no
+ * member has a hole, and every entry is a `no-op` or a `read`. A release
+ * gate over such a document passes without an approval.
+ */
+export function isEmptyChangeSet(doc: Pick<ChangeSetDocument, "members" | "entries">): boolean {
+  if (doc.members.length === 0) return false;
+  for (const m of doc.members) {
+    if (m.status !== "planned" || m.provisional === true || m.holes.length > 0) return false;
+  }
+  return doc.entries.every((e) => e.action === "no-op" || e.action === "read");
+}
+
 // ── chant lifecycle plan ───────────────────────────────────────────────────────
 
 export interface LifecyclePlanPartInput {

package/src/chant-version.ts

@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+
+/**
+ * The installed chant's version, read from `@intentius/chant`'s own
+ * package.json, or "0.0.0" when it can't be read. The path is the same from
+ * `src/` and `dist/`, so it holds whether chant runs from source or from its
+ * build. Kept outside `cli/` so that a module the Op entry loads, such as the
+ * run-event writer (#4041), can name the version without loading the CLI.
+ */
+export const CHANT_VERSION: string = (() => {
+  try {
+    return (createRequire(import.meta.url)("../package.json") as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();

package/src/cli/commands/build.ts

@@ -118,6 +118,20 @@ export interface BuildOptions {
    * outputs of its own `serializers`, so the sources are evaluated once.
    */
   sharedBuild?: { serializers: Serializer[]; result?: ReturnType<typeof build> };
+
+  /**
+   * Where each output file goes: called with its absolute path and its
+   * content in place of creating the directory and writing the file. A
+   * release cut (#4046) passes one that keeps the files in memory, so it
+   * records exactly what this build writes and nothing left on disk by an
+   * earlier one.
+   */
+  writeFile?: (path: string, content: string) => void;
+}
+
+function writeFileCreatingDir(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
 }
 
 /**
@@ -735,6 +749,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   }
 
   // Handle output
+  const writeOutput = options.writeFile ?? writeFileCreatingDir;
   if (result.errors.length === 0 && errors.length === 0) {
     // Extract primary content and collect additional files from SerializerResult.
     // Each entry remembers which lexicon produced it, so a same-basename
@@ -866,8 +881,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       additionalFiles.delete(filename);
       try {
         const targetPath = join(projectDist, filename);
-        mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, entry.content);
+        writeOutput(targetPath, entry.content);
         opsWritten += 1;
       } catch (err) {
         errors.push(
@@ -893,8 +907,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       if (!config?.name) continue;
       try {
         const targetPath = join(projectDist, "ops", config.name, "op.json");
-        mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, serializeOpIR(config));
+        writeOutput(targetPath, serializeOpIR(config));
         irWritten += 1;
       } catch (err) {
         errors.push(
@@ -913,8 +926,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       // output path and any nested additional-file paths (e.g. ops/<name>/...).
       try {
         const outputPath = resolve(options.output);
-        mkdirSync(dirname(outputPath), { recursive: true });
-        writeFileSync(outputPath, output);
+        writeOutput(outputPath, output);
 
         // Write additional files (e.g. nested stack templates) alongside the primary output
         if (additionalFiles.size > 0) {
@@ -935,8 +947,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
               }
             }
             const targetPath = join(outputDir, filename);
-            mkdirSync(dirname(targetPath), { recursive: true });
-            writeFileSync(targetPath, fileContent);
+            writeOutput(targetPath, fileContent);
           }
         }
       } catch (err) {

package/src/cli/commands/check-lexicon-docs.test.ts

@@ -88,3 +88,54 @@ describe("auditDocsReachability", () => {
     expect(auditDocsReachability(d).unreachable).toEqual(["a", "c"]);
   });
 });
+
+/**
+ * chant #3993: inside the chant repository a lexicon's pages are generated
+ * into the main docs site with a _sidebar.json beside them, and the audit
+ * reads those instead of a docs app the lexicon no longer has.
+ */
+describe("auditDocsReachability for a section of the main site", () => {
+  function mainSite(): void {
+    mkdirSync(join(dir, "docs"), { recursive: true });
+    writeFileSync(join(dir, "docs", "package.json"), JSON.stringify({ name: "@intentius/chant-docs" }));
+    writeFileSync(join(dir, "docs", "astro.config.mjs"), "export default {};\n");
+  }
+
+  function repoWithSection(pages: string[], group: unknown, hidden: string[] = []): string {
+    mainSite();
+    const section = join(dir, "docs", "src", "content", "docs", "lexicons", "fixture");
+    mkdirSync(section, { recursive: true });
+    for (const page of pages) writeFileSync(join(section, `${page}.mdx`), "body\n");
+    writeFileSync(join(section, "_sidebar.json"), JSON.stringify({ group, hidden }));
+    const lex = join(dir, "lexicons", "fixture");
+    mkdirSync(join(lex, "docs", "pages"), { recursive: true });
+    return lex;
+  }
+
+  test("every page in the fragment, or hidden by it, is reachable", () => {
+    const lex = repoWithSection(
+      ["index", "start", "secret"],
+      {
+        label: "Fixture",
+        items: [
+          { label: "Overview", slug: "lexicons/fixture" },
+          { label: "Tutorials", items: [{ label: "Start", slug: "lexicons/fixture/start" }] },
+        ],
+      },
+      ["lexicons/fixture/secret"],
+    );
+    expect(auditDocsReachability(lex)).toEqual({ hasSite: true, pages: ["index", "secret", "start"], unreachable: [] });
+  });
+
+  test("a page the fragment does not name is unreachable", () => {
+    const lex = repoWithSection(["index", "orphan"], { label: "Fixture", items: [{ label: "Overview", slug: "lexicons/fixture" }] });
+    expect(auditDocsReachability(lex).unreachable).toEqual(["orphan"]);
+  });
+
+  test("before the section is generated there is nothing to audit", () => {
+    mainSite();
+    const lex = join(dir, "lexicons", "fixture");
+    mkdirSync(lex, { recursive: true });
+    expect(auditDocsReachability(lex).hasSite).toBe(false);
+  });
+});

package/src/cli/commands/check-lexicon-docs.ts

@@ -15,7 +15,10 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import { basename, join, resolve } from "path";
+
+import { collectSidebarSlugs } from "../../codegen/docs";
+import { findChantDocsSite, sectionContentDir } from "../../codegen/docs-in-site";
 
 export interface DocsReachability {
   /** Whether this lexicon ships a Starlight site at all. */
@@ -55,7 +58,7 @@ export function auditDocsReachability(lexiconDir: string): DocsReachability {
   const configPath = join(lexiconDir, "docs", "astro.config.mjs");
 
   if (!existsSync(contentDir) || !existsSync(configPath)) {
-    return { hasSite: false, pages: [], unreachable: [] };
+    return auditSectionReachability(lexiconDir);
   }
 
   const slugs = sidebarSlugs(readFileSync(configPath, "utf-8"));
@@ -99,3 +102,37 @@ export function auditDocsClassification(lexiconDir: string): DocsClassification
   }
   return { hasPages: true, unclassified };
 }
+
+/**
+ * Reachability for a lexicon whose docs are a section of the chant main site
+ * (chant #3993): its generated pages under
+ * `docs/src/content/docs/lexicons/<name>/` against the `_sidebar.json` the
+ * pipeline wrote beside them. A page the fragment lists as hidden is
+ * deliberately URL-only and does not count. Before the section has been
+ * generated there is nothing to audit, which reads as no site, like a
+ * lexicon with no docs.
+ */
+function auditSectionReachability(lexiconDir: string): DocsReachability {
+  const site = findChantDocsSite(lexiconDir);
+  const name = basename(resolve(lexiconDir));
+  const dir = site ? sectionContentDir(site, name) : undefined;
+  const fragmentPath = dir ? join(dir, "_sidebar.json") : undefined;
+  if (!dir || !fragmentPath || !existsSync(fragmentPath)) return { hasSite: false, pages: [], unreachable: [] };
+
+  const fragment = JSON.parse(readFileSync(fragmentPath, "utf-8")) as {
+    group: Record<string, unknown>;
+    hidden?: string[];
+  };
+  const prefix = `lexicons/${name}/`;
+  const reached = new Set(
+    [...collectSidebarSlugs([fragment.group]), ...(fragment.hidden ?? [])].map((slug) =>
+      slug.startsWith(prefix) ? slug.slice(prefix.length) : slug,
+    ),
+  );
+  const pages = readdirSync(dir)
+    .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+    .map((f) => f.replace(/\.mdx?$/, ""))
+    .sort();
+  const unreachable = pages.filter((slug) => slug !== "index" && !reached.has(slug));
+  return { hasSite: true, pages, unreachable };
+}

package/src/cli/commands/check-lexicon.ts

@@ -457,12 +457,24 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
     pass: hasSerializerTest,
   });
 
+  // A lexicon whose src/codegen/docs.ts runs docsPipeline always has a page:
+  // the pipeline writes the overview (index.mdx) from the manifest. Inside the
+  // chant repository that page is generated into the main docs site rather
+  // than committed under docs/ (chant #3993), so k3d, whose docs are all
+  // generated, has no .mdx of its own to count.
   const mdxFiles = findFiles(join(dir, "docs"), (n) => n.endsWith(".mdx"));
+  const docsTs = join(dir, "src", "codegen", "docs.ts");
+  const pipelineOverview = existsSync(docsTs) && readFileSync(docsTs, "utf-8").includes("docsPipeline(");
   items.push({
     name: "At least 1 .mdx doc page",
     tier: 1,
-    pass: mdxFiles.length > 0,
-    detail: mdxFiles.length > 0 ? `${mdxFiles.length} page(s)` : undefined,
+    pass: mdxFiles.length > 0 || pipelineOverview,
+    detail:
+      mdxFiles.length > 0
+        ? `${mdxFiles.length} page(s)`
+        : pipelineOverview
+          ? "the docs pipeline's generated overview"
+          : undefined,
   });
 
   // Counting pages says nothing about whether a reader can find them.

package/src/cli/commands/init-lexicon/templates/docs.ts

@@ -1,7 +1,12 @@
 /**
- * Docs site template generators for init-lexicon scaffold.
+ * Docs site template generators for init-lexicon scaffold. The app files
+ * (package.json, tsconfig, Astro config, content config) are written only for a
+ * lexicon outside the chant repository; inside it, the lexicon's docs are a
+ * section of the main site (chant #3993).
  */
 
+import { DOCS_SITE_DEPENDENCIES } from "../../../../codegen/docs-in-site";
+
 export function generateDocsPackageJson(name: string): string {
   return JSON.stringify(
     {
@@ -14,11 +19,7 @@ export function generateDocsPackageJson(name: string): string {
         build: "astro build",
         preview: "astro preview",
       },
-      dependencies: {
-        "@astrojs/starlight": "^0.37.6",
-        astro: "^5.6.1",
-        sharp: "^0.34.2",
-      },
+      dependencies: { ...DOCS_SITE_DEPENDENCIES },
     },
     null,
     2,

package/src/cli/commands/init-lexicon.test.ts

@@ -78,6 +78,31 @@ describe("initLexiconCommand", () => {
     }
   });
 
+  // chant #3993: inside the chant repository the lexicon's docs are a section
+  // of the main site, so only docs/pages/ is scaffolded.
+  test("inside the chant repository it scaffolds docs/pages/ and no docs app", async () => {
+    mkdirSync(join(tmpDir, "docs"), { recursive: true });
+    writeFileSync(join(tmpDir, "docs", "package.json"), JSON.stringify({ name: "@intentius/chant-docs" }));
+    writeFileSync(join(tmpDir, "docs", "astro.config.mjs"), "export default {};\n");
+    const targetDir = join(tmpDir, "lexicons", "in-repo");
+    const result = await initLexiconCommand({ name: "in-repo", path: targetDir });
+
+    expect(result.success).toBe(true);
+    expect(existsSync(join(targetDir, "docs/pages/getting-started.mdx"))).toBe(true);
+    for (const file of ["docs/package.json", "docs/tsconfig.json", "docs/astro.config.mjs", "docs/src"]) {
+      expect(existsSync(join(targetDir, file)), file).toBe(false);
+    }
+  });
+
+  test("a standalone docs app pins the main site's Starlight and Astro", async () => {
+    const targetDir = join(tmpDir, "pins");
+    await initLexiconCommand({ name: "pins", path: targetDir });
+    const docsPkg = JSON.parse(readFileSync(join(targetDir, "docs/package.json"), "utf-8"));
+    const mainPkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "..", "..", "..", "docs", "package.json"), "utf-8"));
+    expect(docsPkg.dependencies["@astrojs/starlight"]).toBe(mainPkg.dependencies["@astrojs/starlight"]);
+    expect(docsPkg.dependencies.astro).toBe(mainPkg.dependencies.astro);
+  });
+
   test("plugin.ts contains all 5 required lifecycle methods", async () => {
     const targetDir = join(tmpDir, "lifecycle");
     await initLexiconCommand({ name: "k8s", path: targetDir });

package/src/cli/commands/init-lexicon.ts

@@ -12,6 +12,7 @@ import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJ
 import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests";
 import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs";
 import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples";
+import { findChantDocsSite } from "../../codegen/docs-in-site";
 
 /**
  * Init-lexicon command options
@@ -101,6 +102,13 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     }
   }
 
+  // Inside the chant repository a lexicon's docs are a section of the main
+  // site (chant #3993): the pipeline writes its pages into docs/, so the
+  // lexicon gets only docs/pages/. Anywhere else it gets a standalone
+  // Starlight app of its own, as before.
+  const standaloneDocs = findChantDocsSite(targetDir) === undefined;
+  const standaloneDocsDirs = ["docs/src", "docs/src/content", "docs/src/content/docs"];
+
   // Create directory structure
   const dirs = [
     "",
@@ -112,9 +120,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "src/lsp",
     "src/generated",
     "docs",
-    "docs/src",
-    "docs/src/content",
-    "docs/src/content/docs",
+    ...(standaloneDocs ? standaloneDocsDirs : []),
     "docs/pages",
     "examples/getting-started",
     "examples/getting-started/src",
@@ -157,11 +163,15 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "justfile": generateJustfile(name),
     ".gitignore": generateGitignore(),
     "README.md": generateReadme(name, names),
-    "docs/package.json": generateDocsPackageJson(name),
-    "docs/tsconfig.json": generateDocsTsConfig(),
-    "docs/astro.config.mjs": generateDocsAstroConfig(name),
-    "docs/src/content.config.ts": generateDocsContentConfig(),
-    "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+    ...(standaloneDocs
+      ? {
+          "docs/package.json": generateDocsPackageJson(name),
+          "docs/tsconfig.json": generateDocsTsConfig(),
+          "docs/astro.config.mjs": generateDocsAstroConfig(name),
+          "docs/src/content.config.ts": generateDocsContentConfig(),
+          "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+        }
+      : {}),
     "docs/pages/getting-started.mdx": generateDocsGettingStartedMdx(name),
     "examples/getting-started/package.json": generateExamplePackageJson(name),
     "examples/getting-started/src/infra.ts": generateExampleInfraTs(name, names),