@intentius/chant 0.124.27 → 0.124.29

package/src/change-set-graph.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Mapping a change set's entries onto graph node ids (#4022). The real-estate
+ * tests read the graph from `chant graph --format ir`: the five tofu roots in
+ * `lexicons/terraform/src/components/pr-loop.tofu.test.ts` and the aws
+ * workspace member in `lifecycle/gate-change-set.e2e.test.ts`. This holds the
+ * address rules and the digest.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, lifecyclePlanPart, verifyChangeSetDigest, type ChangeSetEntry } from "./change-set";
+import { changeSetNodeCandidates, mapChangeSetToGraph, terraformBlockKey } from "./change-set-graph";
+import type { ChangeSet as LifecycleChangeSet } from "./lifecycle/change-set";
+
+const plan = JSON.parse(readFileSync(join(import.meta.dirname, "__fixtures__", "change-set", "lifecycle-plan.floci.json"), "utf8")) as LifecycleChangeSet;
+
+describe("terraformBlockKey", () => {
+  test("names the block the terraform lexicon keys, without the instance index", () => {
+    expect(terraformBlockKey("terraform_data.keep")).toBe("terraform_data.keep");
+    expect(terraformBlockKey("module.app.terraform_data.instance[0]")).toBe("module.app/terraform_data.instance");
+    expect(terraformBlockKey('module.cdn["eu"].module.bucket[1].aws_s3_bucket.this["a.b]"]')).toBe("module.cdn/module.bucket/aws_s3_bucket.this");
+    expect(terraformBlockKey("data.aws_iam_policy.boundary")).toBe("data.aws_iam_policy.boundary");
+    expect(terraformBlockKey("module.app.data.aws_ami.ubuntu")).toBe("module.app/data.aws_ami.ubuntu");
+  });
+
+  test("a terraform entry tries <root>/<block key>, then its address", () => {
+    expect(changeSetNodeCandidates({ member: "estate", planner: "tofu", address: "module.app.terraform_data.instance[1]" })).toEqual([
+      "estate/module.app/terraform_data.instance",
+      "module.app.terraform_data.instance[1]",
+    ]);
+    expect(changeSetNodeCandidates({ member: "delivery", planner: "chant", address: "jobs" })).toEqual(["jobs"]);
+    expect(changeSetNodeCandidates({ member: "org", planner: "warden", address: "team.platform" })).toEqual(["team.platform"]);
+  });
+});
+
+describe("mapChangeSetToGraph", () => {
+  const doc = composeChangeSet([lifecyclePlanPart({ member: "delivery", plan })]);
+
+  test("keeps the ids the graph holds, puts the member in front, and leaves the digest alone", () => {
+    const mapped = mapChangeSetToGraph(doc, { member: "delivery", at: "a".repeat(40), ids: ["jobs", "events", "dlq"] });
+    expect(mapped.entries.map((e) => [e.address, e.node])).toEqual([
+      ["alerts", null],
+      ["dlq", "delivery/dlq"],
+      ["events", "delivery/events"],
+      ["jobs", "delivery/jobs"],
+    ]);
+    expect(mapped.graph).toEqual({ member: "delivery", at: "a".repeat(40) });
+    expect(mapped.digest).toBe(doc.digest);
+    expect(verifyChangeSetDigest(mapped)).toBe(true);
+  });
+
+  test("outside a workspace the id is the member's own", () => {
+    const mapped = mapChangeSetToGraph(doc, { member: null, at: null, ids: ["jobs"] });
+    expect(mapped.entries.find((e) => e.address === "jobs")!.node).toBe("jobs");
+  });
+
+  test("no graph gives every entry a null node", () => {
+    const mapped = mapChangeSetToGraph(doc, null);
+    expect(mapped.graph).toBeNull();
+    expect(mapped.entries.every((e: ChangeSetEntry) => e.node === null)).toBe(true);
+    expect(verifyChangeSetDigest(mapped)).toBe(true);
+  });
+
+  test("a node is not hashed, and every other part of an entry still is", () => {
+    const mapped = mapChangeSetToGraph(doc, { member: null, at: null, ids: ["jobs"] });
+    const moved = { ...mapped, entries: mapped.entries.map((e) => ({ ...e, node: "elsewhere" })) };
+    expect(verifyChangeSetDigest(moved)).toBe(true);
+    const changed = { ...mapped, entries: mapped.entries.map((e, i) => (i === 0 ? { ...e, address: "other" } : e)) };
+    expect(verifyChangeSetDigest(changed)).toBe(false);
+  });
+});

package/src/change-set-graph.ts

@@ -0,0 +1,141 @@
+/**
+ * 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, with the node's source file as `source` when the graph gives one
+ * (#4025). 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>;
+  /**
+   * The source file of each node that has one (#4025), by the same ids, as a
+   * path from the repository root. An entry mapped onto such a node gets it
+   * as `source`.
+   */
+  sources?: ReadonlyMap<string, 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));
+      const source = id === undefined ? undefined : graph.sources?.get(id);
+      return { ...e, node: id === undefined ? null : `${prefix}${id}`, ...(source !== undefined ? { source } : {}) };
+    }),
+    graph: { member: graph.member, at: graph.at },
+  };
+}

package/src/change-set.ts

@@ -113,6 +113,25 @@ 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;
+  /**
+   * The source file that declares the entry's node, from the repository
+   * root (#4025): the node's `sourceLoc.file` in the member's graph IR, with
+   * the member's directory in front. Set beside `node` when a stored change
+   * set is mapped onto a graph whose node has a source location, absent
+   * otherwise. Like `node`, never part of the digest. The overlap report
+   * attributes the entry to a work item through the commits that changed
+   * this file.
+   */
+  source?: string;
 }
 
 /** Something a planner could not read, so the plan says nothing about it. */
@@ -201,6 +220,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 +278,40 @@ 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) and its source file (#4025) say where on
+  // the graph the change is, not what the plan does, so they stay 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, source: _source, ...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 +357,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 +380,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 +400,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 +410,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/build-params-cli.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "fs";
 import { resolve } from "path";
-import { resolveBuildParams, type BuildParamsConfig } from "../build-params";
+import { resolveBuildParams, type BuildParamFlags, type BuildParamsConfig } from "../build-params";
 import type { BuildParamProvenance } from "../provenance";
 import { formatError, formatInfo } from "./format";
 
@@ -40,6 +40,10 @@ export interface CliBuildParamsArgs {
   paramsFile?: string;
   /** `--verbose` — list every resolved parameter one per line instead of the one-line count (#1424). */
   verbose?: boolean;
+  /** The workspace flags backing parameters in this build's environment (#4024), from `../flag-params.ts`. */
+  flags?: BuildParamFlags;
+  /** `false` to resolve without printing the summary line, for a caller that checks more before it prints ({@link echoBuildParams}). */
+  echo?: boolean;
 }
 
 export interface CliBuildParamsResolution {
@@ -94,6 +98,7 @@ export function resolveCliBuildParams(
     cli: args.cli,
     fromFile,
     env: process.env,
+    ...(args.flags ? { flags: args.flags } : {}),
   });
   for (const message of resolution.errors) {
     errors.push(formatError({ message }));
@@ -103,21 +108,25 @@ export function resolveCliBuildParams(
     return { success: false, provenance: [], errors };
   }
 
+  if (args.echo !== false) echoBuildParams(resolution.provenance, args.verbose);
+  return { success: true, provenance: resolution.provenance, errors: [] };
+}
+
+/** Print a successful resolution: the one-line summary, or every value under `--verbose` or `CHANT_PARAM_ECHO=all` (#1424). */
+export function echoBuildParams(provenance: readonly BuildParamProvenance[], verboseFlag?: boolean): void {
   // #1424 — one line by default. A project with two dozen declared
   // parameters printed two dozen grey lines on every build, ahead of the
   // warnings the reader actually needed. The count by source still answers
   // "did my override reach the build" (the failure mode
   // warnIfParamsCannotReachProject exists for); --verbose names every value.
-  const verbose = args.verbose === true || process.env.CHANT_PARAM_ECHO === "all";
+  const verbose = verboseFlag === true || process.env.CHANT_PARAM_ECHO === "all";
   if (verbose) {
-    for (const p of resolution.provenance) {
+    for (const p of provenance) {
       console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
     }
-  } else if (resolution.provenance.length > 0) {
-    console.error(formatInfo(summarizeBuildParams(resolution.provenance)));
+  } else if (provenance.length > 0) {
+    console.error(formatInfo(summarizeBuildParams(provenance)));
   }
-
-  return { success: true, provenance: resolution.provenance, errors: [] };
 }
 
 /**
@@ -127,8 +136,12 @@ export function resolveCliBuildParams(
  */
 export function summarizeBuildParams(provenance: readonly { source: string }[]): string {
   const counts = new Map<string, number>();
-  for (const p of provenance) counts.set(p.source, (counts.get(p.source) ?? 0) + 1);
-  const order = ["cli", "params-file", "env", "default"];
+  // Every flag source (`flag:<name>`, #4024) counts as one, "from flags".
+  for (const p of provenance) {
+    const source = p.source.startsWith("flag:") ? "flags" : p.source;
+    counts.set(source, (counts.get(source) ?? 0) + 1);
+  }
+  const order = ["cli", "params-file", "env", "flags", "default"];
   const rank = (s: string) => (order.includes(s) ? order.indexOf(s) : order.length);
   const parts = [...counts.keys()]
     .sort((a, b) => rank(a) - rank(b))

package/src/cli/commands/build.ts

@@ -12,7 +12,7 @@ import { resolveTelemetryAttribution } from "../../telemetry-attribution";
 import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
-import { resolveCliBuildParams } from "../build-params-cli";
+import { resolveFlaggedBuildParams } from "../../flag-params";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks, type PostSynthDiagnostic } from "../../lint/post-synth";
@@ -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);
 }
 
 /**
@@ -283,11 +297,14 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // project's own `params.ts` does before migrating to this mechanism). Also
   // logs a one-line count on success, or every resolved value (`[param] name =
   // value (source)`) under --verbose (#1424).
-  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+  // #4024: in a workspace member, a build for an environment also reads the
+  // flag records that back its parameters, and refuses an override of one
+  // where the environment has a gate (../../flag-params.ts).
+  const paramsResolution = await resolveFlaggedBuildParams(configDir, config.buildParams, {
     cli: options.params,
     paramsFile: options.paramsFile,
     verbose: options.verbose,
-  });
+  }, options.env);
   if (!paramsResolution.success) {
     errors.push(...paramsResolution.errors);
     return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
@@ -735,6 +752,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 +884,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 +910,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 +929,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 +950,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 };
+}