@intentius/chant 0.13.1 → 0.15.0

package/src/lexicon.ts

@@ -7,6 +7,8 @@ import type { TypeScriptGenerator } from "./import/generator";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
+import type { DriverComponent } from "./components/driver";
+import type { RuleMeta } from "./audit/catalog";
 
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
@@ -161,6 +163,68 @@ export interface InitTemplateSet {
  * Required lifecycle methods enforce consistency: every lexicon must support
  * generate, validate, coverage, and package operations.
  */
+/**
+ * Where a lexicon pins an upstream schema/spec version, and where to look for a
+ * newer one — the lexicon's own declaration for the self-upgrade tooling
+ * (`chant dev pinned-upgrade`), so core never hard-codes per-lexicon upstream
+ * repos or version-constant locations. See ./codegen/pinned-upgrade.ts.
+ */
+export interface UpstreamPin {
+  /** Source file (relative to the lexicon package root) holding the pinned version constant. */
+  readonly file: string;
+  /** Regex whose first capture group is the current pinned version in `file`. */
+  readonly pattern: RegExp;
+  /** Rebuild a line that matched `pattern`, substituting the new version. */
+  replace(newVersion: string, line: string): string;
+  /** Where to query for the latest stable upstream tag. */
+  readonly upstream: {
+    readonly owner: string;
+    readonly repo: string;
+    /** `releases` = published releases; `tags` = every git tag. */
+    readonly kind: "releases" | "tags";
+    /** Only consider tags ending with this suffix (e.g. "-ee" for GitLab). */
+    readonly tagSuffix?: string;
+  };
+}
+
+/** One CI job in a generated pipeline (generate mode) — a thin trigger for one component in one wave. */
+export interface ComponentPipelineJob {
+  /** CI job name (safe as a YAML key). */
+  jobName: string;
+  /** The component this job triggers. */
+  component: string;
+  /** The stage/wave this job runs in. */
+  stage: string;
+  /** Direct dependency job names this job waits on (mirrors the component's `dependsOn`). */
+  needs: string[];
+}
+
+/** Generic knobs for generate mode, applied once across every generated job (never per component). */
+export interface ComponentPipelineOptions {
+  /** Target environment threaded into the trigger command. */
+  env?: string;
+  /** The trigger command per component, argv with `{name}` substituted. */
+  runCommand?: string[];
+  /** Extra script lines appended to every job. */
+  extraScript?: string[];
+  /** Script lines run before the trigger command in every job. */
+  beforeScript?: string[];
+  /** Container image every job runs in. */
+  image?: string;
+  /** Top-level CI `variables:` block. */
+  variables?: Record<string, string>;
+}
+
+/** The synthesized CI pipeline for a component graph (generate mode). */
+export interface ComponentPipelineResult {
+  /** The synthesized CI YAML (e.g. `.gitlab-ci.yml` content). */
+  yaml: string;
+  /** Wave-ordered stage names (matches the driver's graph waves 1:1). */
+  stages: string[];
+  /** Every generated job, in emit order. */
+  jobs: ComponentPipelineJob[];
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -191,6 +255,15 @@ export interface LexiconPlugin {
   /** Return post-synthesis checks for build validation */
   postSynthChecks?(): PostSynthCheck[];
 
+  /**
+   * Audit catalog metadata (title/tier/fix/authority/category) for this
+   * lexicon's `postSynthChecks`, keyed by check id — the per-provider half of
+   * `chant audit`'s rule catalog (#687, epic #350). Core aggregates these over
+   * its static catalog via `resolveAuditCatalog` (./audit/catalog.ts). Omit
+   * for lexicons whose rule metadata still lives in core's static catalog.
+   */
+  auditCatalog?(): Record<string, RuleMeta>;
+
   /** Return intrinsic function definitions */
   intrinsics?(): IntrinsicDef[];
 
@@ -219,6 +292,21 @@ export interface LexiconPlugin {
   /** Optional initialization hook */
   init?(): void | Promise<void>;
 
+  /** How this lexicon pins its upstream schema version + where to check for a newer one (self-upgrade tooling — see ./codegen/pinned-upgrade.ts). Omit for lexicons with no pinned upstream. */
+  readonly upstreamPin?: UpstreamPin;
+
+  /**
+   * Generate a CI pipeline from the discovered component graph — the
+   * `chant build --components --generate <name>` seam. Only CI-provider
+   * lexicons (gitlab, github, forgejo) implement this; core owns the generic
+   * driver (discovery + graph waves) and dispatches here. Omit for lexicons
+   * that are not CI providers.
+   */
+  generateComponentPipeline?(
+    components: DriverComponent[],
+    options?: ComponentPipelineOptions,
+  ): ComponentPipelineResult;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];

package/src/lifecycle/build-ledger-store.test.ts

@@ -0,0 +1,217 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  persistBuildManifest,
+  readBuildManifest,
+  listBuildManifestDigests,
+  readAllBuildManifests,
+  findBuildManifestByArtifactDigest,
+} from "./build-ledger-store";
+import {
+  createBuildArchiveManifest,
+  addArchiveEntry,
+  type BuildArchiveManifest,
+} from "../components/verbs/build-archive";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makeManifest(component: string, imageDigest: string): BuildArchiveManifest {
+  let manifest = createBuildArchiveManifest(component, { now: () => new Date("2026-01-01T00:00:00.000Z") });
+  manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: imageDigest });
+  manifest = addArchiveEntry(manifest, {
+    kind: "sbom",
+    path: "image.tar.sbom.json",
+    digest: "sha256:sbomdoc",
+    mediaType: "application/spdx+json",
+    subjectDigest: imageDigest,
+    packageCount: 12,
+    generator: "syft",
+  });
+  return manifest;
+}
+
+describe("lifecycle/build-ledger-store", () => {
+  describe("persistBuildManifest / readBuildManifest", () => {
+    test("round-trips a manifest by its own manifestDigest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const manifest = makeManifest("search-service", "sha256:image1");
+
+        const { commit } = await persistBuildManifest(manifest, { cwd: dir });
+        expect(commit).toMatch(/^[0-9a-f]{40}$/);
+
+        const readBack = await readBuildManifest(manifest.manifestDigest, { cwd: dir });
+        expect(readBack).not.toBeNull();
+        expect(readBack).toEqual(manifest);
+      });
+    });
+
+    test("preserves BOM entries and reproducibility/provenance across the round-trip", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        let manifest = createBuildArchiveManifest("svc");
+        manifest = addArchiveEntry(manifest, {
+          kind: "image",
+          path: "image.tar",
+          digest: "sha256:image1",
+          provenance: { sourceRef: "deadbeef", artifactDigest: "sha256:image1" },
+        });
+        manifest = addArchiveEntry(manifest, {
+          kind: "sbom",
+          path: "image.tar.sbom.json",
+          digest: "sha256:sbomdoc",
+          mediaType: "application/spdx+json",
+          subjectDigest: "sha256:image1",
+          bomKind: "software",
+          packageCount: 42,
+          generator: "syft",
+        });
+
+        await persistBuildManifest(manifest, { cwd: dir });
+        const readBack = await readBuildManifest(manifest.manifestDigest, { cwd: dir });
+
+        expect(readBack?.contents.find((e) => e.kind === "image")?.reproducibility).toEqual({ basis: "best-effort" });
+        expect(readBack?.contents.find((e) => e.kind === "image")?.provenance).toEqual({
+          sourceRef: "deadbeef",
+          artifactDigest: "sha256:image1",
+        });
+        const sbomEntry = readBack?.contents.find((e) => e.kind === "sbom");
+        expect(sbomEntry?.packageCount).toBe(42);
+        expect(sbomEntry?.generator).toBe("syft");
+        expect(sbomEntry?.bomKind).toBe("software");
+      });
+    });
+
+    test("readBuildManifest returns null for an unknown digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readBuildManifest("sha256:doesnotexist", { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("persisting the same manifest twice overwrites rather than duplicating", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const manifest = makeManifest("svc", "sha256:image1");
+        await persistBuildManifest(manifest, { cwd: dir });
+        await persistBuildManifest(manifest, { cwd: dir });
+
+        const digests = await listBuildManifestDigests({ cwd: dir });
+        expect(digests).toHaveLength(1);
+      });
+    });
+
+    test("release ledger and build manifest store coexist on the same orphan branch", async () => {
+      const { appendReleaseRecord, readReleaseLedger } = await import("./release-ledger");
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const manifest = makeManifest("svc", "sha256:image1");
+        await persistBuildManifest(manifest, { cwd: dir });
+        await appendReleaseRecord(
+          {
+            component: "svc",
+            env: "prod",
+            digest: "sha256:image1",
+            gitSha: "deadbeef",
+            runId: "run-1",
+            timestamp: "2026-01-01T00:00:00.000Z",
+            actor: "ci-bot",
+          },
+          { cwd: dir },
+        );
+
+        expect(await readBuildManifest(manifest.manifestDigest, { cwd: dir })).not.toBeNull();
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+      });
+    });
+  });
+
+  describe("listBuildManifestDigests / readAllBuildManifests", () => {
+    test("returns empty when no manifest has ever been persisted", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await listBuildManifestDigests({ cwd: dir })).toEqual([]);
+        expect(await readAllBuildManifests({ cwd: dir })).toEqual([]);
+      });
+    });
+
+    test("lists every persisted manifest's own digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const a = makeManifest("svc-a", "sha256:a1");
+        const b = makeManifest("svc-b", "sha256:b1");
+        await persistBuildManifest(a, { cwd: dir });
+        await persistBuildManifest(b, { cwd: dir });
+
+        const digests = await listBuildManifestDigests({ cwd: dir });
+        expect(digests.sort()).toEqual([a.manifestDigest, b.manifestDigest].sort());
+      });
+    });
+
+    test("readAllBuildManifests reads every persisted manifest back", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const a = makeManifest("svc-a", "sha256:a1");
+        const b = makeManifest("svc-b", "sha256:b1");
+        await persistBuildManifest(a, { cwd: dir });
+        await persistBuildManifest(b, { cwd: dir });
+
+        const manifests = await readAllBuildManifests({ cwd: dir });
+        expect(manifests.map((m) => m.component).sort()).toEqual(["svc-a", "svc-b"]);
+      });
+    });
+  });
+
+  describe("findBuildManifestByArtifactDigest", () => {
+    test("finds the manifest carrying a matching image-entry digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const manifest = makeManifest("search-service", "sha256:image1");
+        await persistBuildManifest(manifest, { cwd: dir });
+
+        const found = await findBuildManifestByArtifactDigest("sha256:image1", { cwd: dir });
+        expect(found?.manifestDigest).toBe(manifest.manifestDigest);
+        expect(found?.component).toBe("search-service");
+      });
+    });
+
+    test("returns undefined when no persisted manifest carries the digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const manifest = makeManifest("svc", "sha256:image1");
+        await persistBuildManifest(manifest, { cwd: dir });
+
+        expect(await findBuildManifestByArtifactDigest("sha256:unknown", { cwd: dir })).toBeUndefined();
+      });
+    });
+
+    test("distinguishes between multiple persisted manifests by digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const a = makeManifest("svc-a", "sha256:a1");
+        const b = makeManifest("svc-b", "sha256:b1");
+        await persistBuildManifest(a, { cwd: dir });
+        await persistBuildManifest(b, { cwd: dir });
+
+        expect((await findBuildManifestByArtifactDigest("sha256:a1", { cwd: dir }))?.component).toBe("svc-a");
+        expect((await findBuildManifestByArtifactDigest("sha256:b1", { cwd: dir }))?.component).toBe("svc-b");
+      });
+    });
+  });
+});

package/src/lifecycle/build-ledger-store.ts

@@ -0,0 +1,165 @@
+/**
+ * Build-archive manifest store (#609, epic #551 follow-up to #564/#568/#606/
+ * #613/#614): persists a `BuildArchiveManifest`
+ * (../components/verbs/build-archive.ts) to a durable, content-addressed
+ * location so it survives past the in-process build/run that assembled it.
+ *
+ * **The gap this closes.** `docker-build` (../components/verbs/build.ts) and
+ * friends assemble a real `BuildArchiveManifest` in memory — complete with
+ * `sbom`/config-BOM entries (#606/#613) and per-artifact
+ * `reproducibility`/`provenance` (#614) — but nothing ever wrote it anywhere
+ * durable. `build-ledger.ts`'s `buildLedgerEntries`/`componentBomSummary` are
+ * unit-tested against a manifest handed to them directly, but
+ * `chant components status` (../cli/handlers/components.ts) had no manifest
+ * to hand them at all: `componentBom` and `build.reproducibility` were always
+ * `null` in that CLI path. This module is the missing durable layer — write
+ * once at build time, read back by digest at status time.
+ *
+ * **Storage choice: the `chant/lifecycle` orphan branch, a sibling namespace
+ * to the release ledger.** Reuses the exact git-plumbing
+ * `writeBlobToPath`/`readBlobFromPath`/`listFilesInDir` (./git.ts) that
+ * `writeSnapshot`/`appendReleaseRecordLine` already use — same hash-object →
+ * mktree → commit-tree → update-ref pipeline, same `--force-with-lease` push
+ * discipline (`pushLifecycle`), same "no checkout, no working tree changes"
+ * property. Rejected alternatives:
+ *  - **A new on-disk directory in the working tree** — would need its own
+ *    persistence/sync story (commit it? gitignore it? sync across CI
+ *    runners?) that the orphan branch already solves for the release ledger;
+ *    introducing a second mechanism for a manifest that is conceptually the
+ *    same kind of durable, git-native record would be needless divergence.
+ *  - **A path under `<env>/`** — a build archive is *not* env-scoped. The
+ *    whole point of promote-by-digest (epic #551 "4. Build archive +
+ *    deferred publish") is that one build's manifest is referenced from
+ *    every environment it gets promoted to; writing it under a single env
+ *    directory would either duplicate it per env (defeating "byte-identical
+ *    across envs") or arbitrarily pick one env as "the" owner. Manifests
+ *    instead live under a fixed top-level `_builds/` directory on the same
+ *    orphan branch, keyed by `manifestDigest` — a peer of the per-env
+ *    directories `writeSnapshot`/the release ledger already create there,
+ *    never nested inside one.
+ *
+ * **Content-addressed, keyed by `manifestDigest`.** One file per manifest,
+ * `_builds/<manifestDigest-with-":"->"_">.json`, so a rebuild of
+ * byte-identical inputs (same `manifestDigest`, per
+ * ../components/verbs/build-archive.ts's module doc) overwrites its own
+ * entry with identical content rather than accumulating duplicates —
+ * `writeBlobToPath` already replaces-by-path, so this falls out for free.
+ * `findBuildManifestByArtifactDigest` additionally resolves "the manifest
+ * that produced artifact digest X" (the join key `chant components status`
+ * actually has on hand — a `ReleaseRecord.digest` is an *artifact* digest,
+ * not a manifest digest) by scanning every stored manifest's `contents` for
+ * a matching entry. This is a linear scan over however many manifests have
+ * been persisted; fine for the ledger's expected scale (one manifest per
+ * build), and avoids maintaining a second reverse-index file that could get
+ * out of sync with the manifests themselves.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { writeBlobToPath, readBlobFromPath, listFilesInDir } from "./git";
+import type { BuildArchiveManifest } from "../components/verbs/build-archive";
+
+/** Fixed top-level directory on the `chant/lifecycle` orphan branch that holds every persisted build manifest — a peer of the per-env directories, never nested inside one (see module doc for why). */
+const BUILDS_DIR = "_builds";
+
+/** Turn a `sha256:...`-style digest into a filesystem/git-tree-safe filename stem (`:` is not usable in a git tree entry name the way this plumbing constructs it). */
+function digestToFilenameStem(digest: string): string {
+  return digest.replace(/:/g, "_");
+}
+
+function manifestFilename(manifestDigest: string): string {
+  return `${digestToFilenameStem(manifestDigest)}.json`;
+}
+
+/**
+ * Persist a `BuildArchiveManifest` to the orphan branch, keyed by its own
+ * `manifestDigest`. Does not push to the remote — call `pushLifecycle`
+ * (./git.ts) afterward, the same two-step (`write` then `push`) shape
+ * `appendReleaseRecord`/`takeSnapshot` use, so a caller persisting several
+ * manifests (or a manifest plus a release record) in one run can batch the
+ * push into one network round-trip.
+ *
+ * Idempotent: persisting the same manifest twice (identical `manifestDigest`)
+ * overwrites the same path with identical bytes — safe to call more than
+ * once for the same build.
+ */
+export async function persistBuildManifest(
+  manifest: BuildArchiveManifest,
+  opts?: { cwd?: string },
+): Promise<{ commit: string }> {
+  const json = JSON.stringify(manifest, sortedJsonReplacer);
+  const commit = await writeBlobToPath(BUILDS_DIR, manifestFilename(manifest.manifestDigest), json, "Build manifest", opts);
+  return { commit };
+}
+
+/**
+ * Read a persisted `BuildArchiveManifest` back by its own `manifestDigest`.
+ * Returns `null` when no manifest was ever persisted under that digest
+ * (never throws — a status query for a digest with no recorded build is a
+ * normal, expected state, matching `readSnapshot`'s null-on-missing
+ * convention).
+ */
+export async function readBuildManifest(
+  manifestDigest: string,
+  opts?: { cwd?: string },
+): Promise<BuildArchiveManifest | null> {
+  const content = await readBlobFromPath(BUILDS_DIR, manifestFilename(manifestDigest), opts);
+  if (!content) return null;
+  try {
+    return JSON.parse(content) as BuildArchiveManifest;
+  } catch {
+    return null;
+  }
+}
+
+/** List the `manifestDigest` of every build manifest persisted on the orphan branch. */
+export async function listBuildManifestDigests(opts?: { cwd?: string }): Promise<string[]> {
+  const files = await listFilesInDir(BUILDS_DIR, opts);
+  return files
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => f.replace(/\.json$/, "").replace(/_/g, ":"));
+}
+
+/**
+ * Read every persisted build manifest. Best-effort: a manifest file that
+ * fails to parse is skipped rather than failing the whole read (mirrors
+ * `readReleaseLedger`'s "skip malformed lines" degrade-gracefully
+ * convention) — the caller only gets the count implicitly via array length,
+ * since a corrupted manifest blob is a much rarer/more surprising event than
+ * a hand-edited ledger line and not expected to need the same "surfaced
+ * count" treatment.
+ */
+export async function readAllBuildManifests(opts?: { cwd?: string }): Promise<BuildArchiveManifest[]> {
+  const digests = await listBuildManifestDigests(opts);
+  const manifests: BuildArchiveManifest[] = [];
+  for (const digest of digests) {
+    const manifest = await readBuildManifest(digest, opts);
+    if (manifest) manifests.push(manifest);
+  }
+  return manifests;
+}
+
+/**
+ * Find the persisted manifest that carries an entry (any kind — image,
+ * template, asset, or sbom) whose `digest` equals `artifactDigest`. This is
+ * the lookup `chant components status` actually needs: a `ReleaseRecord`
+ * (../lifecycle/release-ledger.ts) records the *artifact* digest that was
+ * promoted/deployed, not the manifest's own aggregate `manifestDigest` — so
+ * resolving "the build behind this deployed digest" means searching
+ * manifest contents, not a direct keyed lookup. Returns `undefined` when no
+ * persisted manifest contains a matching entry (no build was ever persisted
+ * for that artifact digest — e.g. it predates #609, or was recorded via the
+ * standalone `chant components release` command with no corresponding
+ * `chant build`/`run` in this checkout).
+ *
+ * A `ReleaseRecord.manifestDigest`, when present (an optional field a caller
+ * may have supplied at record time), lets a caller skip this scan entirely
+ * via `readBuildManifest` directly — this function is the fallback for the
+ * common case where only the artifact digest is known.
+ */
+export async function findBuildManifestByArtifactDigest(
+  artifactDigest: string,
+  opts?: { cwd?: string },
+): Promise<BuildArchiveManifest | undefined> {
+  const manifests = await readAllBuildManifests(opts);
+  return manifests.find((m) => m.contents.some((entry) => entry.digest === artifactDigest));
+}