@intentius/chant 0.124.26 → 0.124.28

package/src/codegen/docs.ts

@@ -8,10 +8,19 @@
  */
 
 import { copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
 import { expandFileMarkers } from "./docs-file-markers";
+import {
+  DOCS_SITE_DEPENDENCIES,
+  buildSectionGroup,
+  hiddenSectionSlugs,
+  rebaseImports,
+  resolveDocsMode,
+  sectionContentDir,
+  withQuadrant,
+} from "./docs-in-site";
 import { readAuthoredPages } from "./docs-pages";
 import { scanRules, generateRules } from "./docs-rule-scanning";
 import { buildSidebar } from "./docs-sidebar";
@@ -22,6 +31,14 @@ import type { DocsConfig, DocsResult, ManifestJSON, MetaEntry, SidebarPage } fro
 export { expandFileMarkers } from "./docs-file-markers";
 export type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
 export { QUADRANTS, QUADRANT_LABELS, readAuthoredPages } from "./docs-pages";
+export {
+  DOCS_SITE_DEPENDENCIES,
+  buildSectionGroup,
+  findChantDocsSite,
+  resolveDocsMode,
+  sectionContentDir,
+  type DocsSiteMode,
+} from "./docs-in-site";
 
 // ── Pipeline ───────────────────────────────────────────────────────
 
@@ -279,6 +296,46 @@ export function writeDocsPages(result: DocsResult, outDir: string): void {
   }
 }
 
+/**
+ * Write a lexicon's docs from pipeline results, in the mode
+ * {@link resolveDocsMode} picks: inside the chant repository, a section of the
+ * main site ({@link writeDocsSection}); anywhere else, a standalone Starlight
+ * app ({@link writeStandaloneDocsSite}). Every lexicon's `docs.ts` calls this,
+ * so neither they nor the `chant init-lexicon` scaffold choose a mode.
+ */
+export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
+  const { mode, siteDir } = resolveDocsMode(config);
+  if (mode === "in-site" && siteDir) writeDocsSection(config, result, siteDir);
+  else writeStandaloneDocsSite(config, result);
+}
+
+/**
+ * Write a lexicon's pages into the main docs site (chant #3993): every page
+ * under `docs/src/content/docs/lexicons/<name>/`, and `_sidebar.json` beside
+ * them with the lexicon's sidebar group and its hidden pages. The section is
+ * build output, so the directory is replaced whole on every run; a page the
+ * pipeline stopped emitting cannot linger. No app files are written.
+ */
+export function writeDocsSection(config: DocsConfig, result: DocsResult, siteDir: string): void {
+  const sectionDir = sectionContentDir(siteDir, config.name);
+  rmSync(sectionDir, { recursive: true, force: true });
+  mkdirSync(sectionDir, { recursive: true });
+
+  const quadrantOf = new Map(result.sidebarPages.map((p) => [`${p.slug}.mdx`, p.quadrant]));
+  for (const [filename, content] of result.pages) {
+    const filePath = join(sectionDir, filename);
+    const pageDir = dirname(filePath);
+    mkdirSync(pageDir, { recursive: true });
+    const page = rebaseImports(withQuadrant(content, quadrantOf.get(filename)), { outDir: config.outDir, siteDir, pageDir });
+    writeFileSync(filePath, page);
+  }
+
+  writeFileSync(
+    join(sectionDir, "_sidebar.json"),
+    JSON.stringify({ group: buildSectionGroup(config, result), hidden: hiddenSectionSlugs(config, result) }, null, 2) + "\n",
+  );
+}
+
 /**
  * Scaffold a standalone Starlight docs site from pipeline results.
  *
@@ -286,7 +343,7 @@ export function writeDocsPages(result: DocsResult, outDir: string): void {
  * pages under src/content/docs/. The resulting directory can be built with
  * `npm install && npm run build`.
  */
-export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
+export function writeStandaloneDocsSite(config: DocsConfig, result: DocsResult): void {
   const outDir = config.outDir;
   const contentDir = join(outDir, "src", "content", "docs");
 
@@ -350,11 +407,7 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
           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/codegen/rehype-base-url.d.mts

@@ -3,6 +3,8 @@ export interface RehypeBaseUrlOptions {
   base: string;
   /** Project-wide base used to detect already-correctly-prefixed cross-site links. */
   projectBase?: string;
+  /** Per-page base, by the page's source path; undefined falls back to `base`. */
+  baseFor?: (path: string) => string | undefined;
 }
 
 type HastNode = {
@@ -14,4 +16,4 @@ type HastNode = {
 
 export default function rehypeBaseUrl(
   opts: RehypeBaseUrlOptions,
-): (tree: HastNode) => void;
+): (tree: HastNode, file?: { path?: string }) => void;

package/src/codegen/rehype-base-url.mjs

@@ -11,9 +11,16 @@
  * idempotently skips hrefs that already start with the site's own base or the
  * project-wide base.
  *
+ * `baseFor` lets one site hold sections with their own root (chant #3993): the
+ * main docs site builds every lexicon's pages under /chant/lexicons/<name>/,
+ * and a lexicon page's `/foo/` has always meant its own lexicon's root, as it
+ * did when each lexicon was a separate site. `baseFor(file.path)` returns the
+ * base for that page, or undefined to use `base`.
+ *
  * @typedef {Object} RehypeBaseUrlOptions
  * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
  * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ * @property {(path: string) => string | undefined} [baseFor] - Per-page base, by the page's source path.
  */
 
 const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
@@ -26,16 +33,12 @@ function normalizeBase(value) {
  * @param {RehypeBaseUrlOptions} opts
  */
 export default function rehypeBaseUrl(opts) {
-  const base = normalizeBase(opts.base);
-  if (base === "/") {
-    return () => {};
-  }
-  const ownPrefix = base + "/";
+  const siteBase = normalizeBase(opts.base);
   const projectPrefix = opts.projectBase
     ? normalizeBase(opts.projectBase) + "/"
     : null;
 
-  function rewrite(node) {
+  function rewrite(node, base, ownPrefix) {
     if (
       node &&
       node.type === "element" &&
@@ -58,11 +61,14 @@ export default function rehypeBaseUrl(opts) {
       }
     }
     if (node && node.children) {
-      for (const child of node.children) rewrite(child);
+      for (const child of node.children) rewrite(child, base, ownPrefix);
     }
   }
 
-  return (tree) => {
-    rewrite(tree);
+  return (tree, file) => {
+    const own = opts.baseFor && file && typeof file.path === "string" ? opts.baseFor(file.path) : undefined;
+    const base = own ? normalizeBase(own) : siteBase;
+    if (base === "/") return;
+    rewrite(tree, base, base + "/");
   };
 }

package/src/codegen/rehype-base-url.test.ts

@@ -159,3 +159,37 @@ describe("rehypeBaseUrl — tree traversal", () => {
     expect(root.children[0].properties.src).toBe("/foo.png");
   });
 });
+
+// chant #3993: the main site builds every lexicon's pages under
+// /chant/lexicons/<name>/, and a lexicon page's root-relative link keeps
+// meaning its own lexicon's root, as it did on the lexicon's own site.
+describe("rehypeBaseUrl — per-page base (baseFor)", () => {
+  const baseFor = (path: string): string | undefined => {
+    const name = path.match(/\/content\/docs\/lexicons\/([^/]+)\//)?.[1];
+    return name ? `/chant/lexicons/${name}` : undefined;
+  };
+  const opts = { base: "/chant", projectBase: "/chant", baseFor };
+
+  function runAt(path: string | undefined, href: string): string {
+    const plugin = rehypeBaseUrl(opts);
+    const root = tree(a(href));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (plugin as any)(root, path === undefined ? undefined : { path });
+    return root.children[0].properties.href as string;
+  }
+
+  it("prefixes a lexicon page's root-relative link with its lexicon's base", () => {
+    expect(runAt("/repo/docs/src/content/docs/lexicons/aws/composites.mdx", "/intrinsics/")).toBe(
+      "/chant/lexicons/aws/intrinsics/",
+    );
+  });
+
+  it("leaves a lexicon page's /chant/ link alone", () => {
+    expect(runAt("/repo/docs/src/content/docs/lexicons/aws/composites.mdx", "/chant/guide/ops/")).toBe("/chant/guide/ops/");
+  });
+
+  it("uses the site base for every other page", () => {
+    expect(runAt("/repo/docs/src/content/docs/guide/ops.mdx", "/lexicons/aws/")).toBe("/chant/lexicons/aws/");
+    expect(runAt(undefined, "/lexicons/aws/")).toBe("/chant/lexicons/aws/");
+  });
+});

package/src/components/auto-release.test.ts

@@ -95,6 +95,27 @@ describe("maybeRecordAutoRelease", () => {
     expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
   });
 
+  test("a deploy that passed a gate records the approver and the admission (#4020)", async () => {
+    appendReleaseRecordMock.mockResolvedValue({ commit: "c".repeat(40), record: { version: 1 } });
+    const admission = { op: "svc", gate: "approve-prod", resolvedAt: "2026-01-01T00:05:00.000Z" };
+
+    await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "9001", runOrigin: { forge: "github", repo: "acme/app" }, approver: "alice", admission },
+      { actor: "alice" },
+    );
+
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input).toMatchObject({ runId: "9001", runOrigin: { forge: "github", repo: "acme/app" }, approver: "alice", admission });
+  });
+
+  test("an ungated deploy records neither", async () => {
+    appendReleaseRecordMock.mockResolvedValue({ commit: "c".repeat(40), record: { version: 1 } });
+    await maybeRecordAutoRelease({ component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "r" }, { actor: "alice" });
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input).not.toHaveProperty("approver");
+    expect(input).not.toHaveProperty("admission");
+  });
+
   test("a pre-resolved digest takes precedence and is used directly", async () => {
     appendReleaseRecordMock.mockResolvedValue({
       commit: "b".repeat(40),

package/src/components/auto-release.ts

@@ -26,7 +26,7 @@
  * env vars, timestamp is a real `new Date()` taken at record time).
  */
 import { getHeadCommit, pushLifecycle, StaleLifecycleBranchError } from "../lifecycle/git";
-import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
+import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseAdmission, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
 import type { DriverStepRecord } from "./driver";
 
 /**
@@ -94,6 +94,9 @@ export interface AutoReleaseRunInfo {
   runId: string;
   /** The id space `runId` lives in (#2045) — `{ forge: "op" }` for a hosted run, `{ forge: "local" }` for a local-executor mint. Recorded verbatim as the release record's `runOrigin`. */
   runOrigin?: RunOrigin;
+  /** Who approved the deploy at its gate (#1035) and the gate resolution that admitted it (#4020), when it passed one. `recordAutoReleasesForRun` reads both off the component's gate step records. */
+  approver?: string;
+  admission?: ReleaseAdmission;
   /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
   profileOverride?: string;
   /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
@@ -184,6 +187,8 @@ export async function maybeRecordAutoRelease(
         ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}),
         timestamp,
         actor,
+        ...(run.approver ? { approver: run.approver } : {}),
+        ...(run.admission ? { admission: run.admission } : {}),
         ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
         ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
       },

package/src/components/cli-support.test.ts

@@ -27,6 +27,8 @@ import {
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { memoryGateLedgerPort } from "../op/gate";
 import type { DriverComponent, RunProgressEvent } from "./driver";
+import { openRunEventStream } from "../run-event-stream";
+import { checkRunEventLines, stepTrail } from "../workspace/__fixtures__/run-event-check";
 
 // A minimal stand-in for the real gitlab lexicon plugin, satisfying
 // `isLexiconPlugin` (../lexicon.ts) — used only by the `generateComponentsPipeline`
@@ -1106,3 +1108,83 @@ describe("runComponents — onProgress (--progress-json wiring, M3)", () => {
     expect(result.run?.ok).toBe(true);
   });
 });
+
+describe("runComponents — onRunEvent (`chant run --components --events-json`, #4041)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-run-components-events-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /** The run's stream, as `--events-json` opens it. */
+  function stream() {
+    const lines: string[] = [];
+    const s = openRunEventStream(
+      { runId: "local-1", kind: "component", name: "all", gitSha: null, runtime: "local", runOrigin: { forge: "local" } },
+      (l) => lines.push(l),
+    );
+    return { s, lines };
+  }
+
+  test("a two-wave run: schema-valid, waves and components framed, each step started before it settles", async () => {
+    await writeFile(
+      join(testDir, "alb.component.ts"),
+      `export const alb = { name: "shared-alb", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "search-service", dependsOn: ["shared-alb"], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+    const { s, lines } = stream();
+    const result = await runComponents(testDir, "all", { registry: fakeRegistry(), onRunEvent: s.emit });
+
+    expect(result.success).toBe(true);
+    const events = checkRunEventLines(lines);
+    expect(events[0]).toMatchObject({ type: "run-start", waves: [["shared-alb"], ["search-service"]] });
+    expect(events.filter((e) => e.type === "step-start")).toEqual([
+      expect.objectContaining({ component: "shared-alb", phase: "Apply", step: "deploy-thing", index: 0 }),
+      expect.objectContaining({ component: "search-service", phase: "Apply", step: "deploy-thing", index: 0 }),
+    ]);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+  });
+
+  test("a gate nobody approved: gate-waiting and a gated settle, the step after it not-run, the run gated", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-ok" }, { kind: "deploy-thing" }] }] };`,
+    );
+    const { s, lines } = stream();
+    const result = await runComponents(testDir, "svc", { registry: fakeRegistry(), gates: memoryGateLedgerPort(), onRunEvent: s.emit });
+
+    expect(result.gated).toBeDefined();
+    const events = checkRunEventLines(lines);
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "gate:prod-ok"],
+      ["gate-waiting", "gate:prod-ok"],
+      ["step-settle", "gate:prod-ok", "gated"],
+      ["step-settle", "deploy-thing", "skipped:not-run"],
+    ]);
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ component: "svc", op: "svc", gate: "prod-ok", point: null });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "gated" });
+  });
+
+  test("onProgress beside onRunEvent prints what it printed alone: the older stream is unchanged", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-ok" }, { kind: "deploy-thing" }] }] };`,
+    );
+    const alone: RunProgressEvent[] = [];
+    await runComponents(testDir, "svc", { registry: fakeRegistry({ failRun: true }), gates: memoryGateLedgerPort(), onProgress: (e) => alone.push(e) });
+    const beside: RunProgressEvent[] = [];
+    const { s } = stream();
+    await runComponents(testDir, "svc", { registry: fakeRegistry({ failRun: true }), gates: memoryGateLedgerPort(), onProgress: (e) => beside.push(e), onRunEvent: s.emit });
+    expect(beside).toEqual(alone);
+    // The gate step, its decision and the not-run step after it are not in the older stream.
+    expect(alone.map((e) => e.type)).toEqual(["run-start", "wave-start", "component-start", "phase-start", "phase-done", "component-done", "wave-done", "run-done"]);
+  });
+});

package/src/components/cli-support.ts

@@ -45,6 +45,7 @@ import type { GateDigestMismatch, GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
 import { isLexiconPlugin, type LexiconPlugin, type ComponentPipelineOptions } from "../lexicon";
 import type { RunProgressEvent } from "./run-progress";
+import { joinRunEventSinks, progressSinkOf, type RunEventSink } from "../run-event-stream";
 import { dirname, relative } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { getHeadCommit } from "../lifecycle/git";
@@ -437,6 +438,11 @@ export interface RunComponentsOptions {
    * `--progress-json`, in which case nothing changes.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * Where the run's events go (#4041, `--events-json`): run-event bodies,
+   * with the same single-wave framing for a single component as `onProgress`.
+   */
+  onRunEvent?: RunEventSink;
   /**
    * chant #1108 — this run's resolved build-time parameter values, resolved
    * the exact same way `chant build` resolves them
@@ -681,7 +687,7 @@ export async function runComponents(
   // from a caller (a downstream CI job passing an upstream job's dumped
   // outputs via `--seed-outputs`); grows as this run's components complete.
   const seedOutputs = options.componentOutputs ?? {};
-  const { onProgress } = options;
+  const emit = joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
 
   const gates = options.gates;
   // #3061: the commit this run deploys, for the workloads' vcs.ref.head.revision. The digest comes
@@ -705,7 +711,7 @@ export async function runComponents(
         env,
         releaseIdentity,
         componentOutputs: seedOutputs,
-        onProgress,
+        ...(emit ? { onRunEvent: emit } : {}),
         ...(gates ? { gates } : {}),
       });
       return {
@@ -741,21 +747,22 @@ export async function runComponents(
     // `run.waves`/`run.order` below already give it.
     const componentOutputs = { ...seedOutputs };
     const componentName = resolvedTargets[0].name;
-    onProgress?.({ type: "run-start", waves: [selected] });
-    onProgress?.({ type: "wave-start", wave: 1, components: selected });
-    onProgress?.({ type: "component-start", wave: 1, component: componentName });
+    emit?.({ type: "run-start", waves: [selected] });
+    emit?.({ type: "wave-start", wave: 1, components: selected });
+    emit?.({ type: "component-start", wave: 1, component: componentName });
     const componentResult = await runComponentDeploy(
       resolvedTargets[0],
       deployContext({ env, releaseIdentity }, componentName),
       registry,
       componentOutputs,
-      onProgress,
+      undefined,
       gates ? { port: gates } : undefined,
+      emit,
     );
     const status = componentResult.status === "fail" ? "failed" : componentResult.status;
-    onProgress?.({ type: "component-done", wave: 1, component: componentName, status });
-    onProgress?.({ type: "wave-done", wave: 1, status });
-    onProgress?.({ type: "run-done", status });
+    emit?.({ type: "component-settle", wave: 1, component: componentName, status });
+    emit?.({ type: "wave-settle", wave: 1, status });
+    emit?.({ type: "run-settle", status, durationMs: null });
     const run: DriverRunResult = {
       order: selected,
       waves: [selected],