@intentius/chant 0.49.0 → 0.51.0

package/src/cli/commands/build.ts

@@ -17,7 +17,6 @@ import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
-import { collectSecretDeclarations } from "../../secret-provenance";
 import { coreReceiptChecks } from "../../lint/receipt-checks";
 import { coreOutputChecks } from "../../lint/output-checks";
 import { coreKnowledgeChecks } from "../../lint/knowledge-checks";
@@ -25,6 +24,7 @@ import { applyConfiguredSeverity } from "../../lint/config";
 import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
 import { sortedJsonReplacer } from "../../utils";
+import { rankFoldBlockers, toCollapsedFormat, type FoldRankResult } from "../../discovery/fold-rank";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync, mkdirSync } from "fs";
 import { resolve, dirname, join, relative } from "path";
@@ -85,6 +85,23 @@ export interface BuildOptions {
    * after {@link params}.
    */
   paramsFile?: string;
+
+  /**
+   * chant #1083 — `chant build --fold --fold-rank`: after the build, rank
+   * `"run"`-mode files by dominator retained-count over the forward
+   * import-failure graph (see `../../discovery/fold-rank.ts`), and report
+   * the reverse-taint bucket (#1044) separately. Printed to stderr,
+   * independent of `--verbose`'s per-file listing. No-op without `fold`.
+   */
+  foldRank?: boolean;
+
+  /**
+   * chant #1083 — `chant build --fold --fold-rank <path>`: as {@link
+   * foldRank}, and ALSO writes the ranking as a Brendan Gregg collapsed
+   * stack export (weighted by retained count) to this path, so it opens in
+   * any flame/icicle viewer with no chant-specific tooling.
+   */
+  foldRankCollapsedFile?: string;
 }
 
 /**
@@ -347,6 +364,23 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     }
   }
 
+  // chant #1083 — rank fold blockers by dominator retained-count over the
+  // forward import-failure graph, and report the reverse-taint bucket
+  // (#1044) separately. Opt-in (`--fold-rank`) and independent of
+  // `--verbose`: the per-file listing above says WHAT ran; this says WHICH
+  // of those files is worth fixing first.
+  if (fold && (options.foldRank || options.foldRankCollapsedFile) && result.foldDecisions.length > 0) {
+    const ranking = await rankFoldBlockers(result.foldDecisions);
+    console.error(formatInfo(formatFoldRanking(ranking, infraPath)));
+    if (options.foldRankCollapsedFile) {
+      const collapsedPath = resolve(options.foldRankCollapsedFile);
+      mkdirSync(dirname(collapsedPath), { recursive: true });
+      const lines = toCollapsedFormat(ranking, { relativeTo: infraPath });
+      writeFileSync(collapsedPath, lines.length > 0 ? `${lines.join("\n")}\n` : "");
+      console.error(formatInfo(`[fold-rank] collapsed-format export: ${collapsedPath} (${lines.length} line(s))`));
+    }
+  }
+
   // Format errors — grouped by message, because one refusal can surface once
   // per resource file. A project whose params module throws (a guard like
   // "this seam cannot back that tier") throws in EVERY file that imports it,
@@ -545,28 +579,55 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
 
   // Handle output
   if (result.errors.length === 0 && errors.length === 0) {
-    // Extract primary content and collect additional files from SerializerResult
-    const additionalFiles = new Map<string, string>();
+    // Extract primary content and collect additional files from SerializerResult.
+    // Each entry remembers which lexicon produced it, so a same-basename
+    // collision between two sources (below) can name both.
+    const additionalFiles = new Map<string, { content: string; source: string }>();
 
-    // Sidecar files that must reach disk BYTE-FOR-BYTE: committed ciphertext
+    // Basenames (from some SerializerResult.files) that must reach disk
+    // BYTE-FOR-BYTE — e.g. committed ciphertext
     // (`declareSecret({ provenance: "committed-encrypted", file })`). The
     // additional-file writer below round-trips anything JSON.parse accepts,
-    // key-sorting it and possibly re-emitting it as YAML — which would break
-    // the `sops` MAC. `file` is restricted to .yaml/.yml, so that parse fails
-    // in practice, but naming the files here makes byte identity structural
-    // rather than a lucky accident.
+    // key-sorting it and possibly re-emitting it as YAML, which would break
+    // e.g. the `sops` MAC on committed ciphertext. A serializer opts a file
+    // out of that round trip structurally, via `SerializerResult.verbatimFiles`
+    // (chant#1937) — "the parse happens to fail" is not a safety guarantee.
     const verbatimFiles = new Set<string>();
-    for (const decl of collectSecretDeclarations(result.entities).values()) {
-      if (decl.provenance === "committed-encrypted") {
-        verbatimFiles.add(decl.file.split(/[\\/]/).pop()!);
+
+    // A same basename emitted by two sources with different content would
+    // otherwise silently overwrite (last-writer-wins, since `additionalFiles`
+    // is keyed by basename alone). Identical content from two sources is
+    // fine — dedup — but differing content is refused, naming both sources,
+    // the same way the committed-encrypted resolution stage refuses a
+    // basename collision among its own declarations.
+    function addAdditionalFile(filename: string, content: string, source: string): void {
+      const existing = additionalFiles.get(filename);
+      if (existing === undefined) {
+        additionalFiles.set(filename, { content, source });
+        return;
       }
+      if (existing.content === content) return;
+      errors.push(
+        formatError({
+          message:
+            `Additional file "${filename}" collides: "${existing.source}" and "${source}" ` +
+            `both emit it with different content — additional files share one flat ` +
+            `namespace, so two sources whose filenames match would otherwise silently ` +
+            `overwrite each other.`,
+        }),
+      );
     }
 
-    function getPrimaryContent(raw: string | SerializerResult): string {
+    function getPrimaryContent(raw: string | SerializerResult, source: string): string {
       if (typeof raw === "string") return raw;
       if (raw.files) {
         for (const [filename, content] of Object.entries(raw.files)) {
-          additionalFiles.set(filename, content);
+          addAdditionalFile(filename, content, source);
+        }
+      }
+      if (raw.verbatimFiles) {
+        for (const filename of raw.verbatimFiles) {
+          verbatimFiles.add(filename);
         }
       }
       return raw.primary;
@@ -585,8 +646,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     // Multiple lexicons: wrap in lexicon keys
     let output: string = "{}";
     if (result.outputs.size === 1) {
-      const [, raw] = [...result.outputs.entries()][0];
-      const content = getPrimaryContent(raw);
+      const [lexiconName, raw] = [...result.outputs.entries()][0];
+      const content = getPrimaryContent(raw, lexiconName);
       const parsed = tryParseJson(content);
       if ("json" in parsed) {
         output = JSON.stringify(parsed.json, sortedJsonReplacer, 2);
@@ -603,7 +664,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       const nonJsonSections: string[] = [];
       const sortedLexiconNames = [...result.outputs.keys()].sort();
       for (const lexiconName of sortedLexiconNames) {
-        const content = getPrimaryContent(result.outputs.get(lexiconName)!);
+        const content = getPrimaryContent(result.outputs.get(lexiconName)!, lexiconName);
         const parsed = tryParseJson(content);
         if ("json" in parsed) {
           combined[lexiconName] = parsed.json;
@@ -634,13 +695,13 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     // `foo.yaml`, so the durable-run worker was never where `run --temporal` looks.
     const projectDist = resolve(options.path ?? ".", "dist");
     let opsWritten = 0;
-    for (const [filename, content] of [...additionalFiles]) {
+    for (const [filename, entry] of [...additionalFiles]) {
       if (!filename.startsWith("ops/")) continue;
       additionalFiles.delete(filename);
       try {
         const targetPath = join(projectDist, filename);
         mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, content);
+        writeFileSync(targetPath, entry.content);
         opsWritten += 1;
       } catch (err) {
         errors.push(
@@ -665,13 +726,13 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
         // Write additional files (e.g. nested stack templates) alongside the primary output
         if (additionalFiles.size > 0) {
           const outputDir = dirname(outputPath);
-          for (const [filename, content] of additionalFiles) {
-            let fileContent = content;
+          for (const [filename, entry] of additionalFiles) {
+            let fileContent = entry.content;
             // Format additional files consistently — except the ones declared
             // verbatim, which are copied exactly as they were committed.
             if (!verbatimFiles.has(filename)) {
               try {
-                const fileParsed = JSON.parse(content);
+                const fileParsed = JSON.parse(entry.content);
                 fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
                 if (options.format === "yaml") {
                   fileContent = jsonToYaml(JSON.parse(fileContent));
@@ -711,9 +772,9 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       // Print to stdout
       console.log(output);
       // Log additional files to stderr if any
-      for (const [filename, content] of additionalFiles) {
+      for (const [filename, entry] of additionalFiles) {
         console.error(`\n--- ${filename} ---`);
-        console.error(content);
+        console.error(entry.content);
       }
     }
   }
@@ -757,6 +818,36 @@ export function summarizeFoldDecisions(decisions: readonly { mode: string }[]):
   return `fold: ${files(folded)} folded, ${ran} ran${hint}`;
 }
 
+/**
+ * `chant build --fold --fold-rank`'s text report (chant #1083): blockers
+ * ranked by dominator retained-count, highest first, then the reverse-taint
+ * bucket (#1044) called out separately since the tree can't express that
+ * edge (see `../../discovery/fold-rank.ts`'s module doc).
+ */
+export function formatFoldRanking(ranking: FoldRankResult, infraPath: string): string {
+  const rel = (file: string): string => relative(infraPath, file) || file;
+  const lines: string[] = [];
+  if (ranking.blockers.length === 0) {
+    lines.push("fold-rank: no run-mode files to rank");
+  } else {
+    lines.push(`fold-rank: ${ranking.blockers.length} blocker(s), ${ranking.totalBlocked} file(s) blocked`);
+    for (const b of ranking.blockers) {
+      const via = b.topLevel ? "" : ` (behind ${rel(b.dominatedBy!)})`;
+      const reason = b.reason ? ` — ${b.reason}` : "";
+      lines.push(`  retained ${b.retained}: ${rel(b.file)}${via}${reason}`);
+    }
+  }
+  if (ranking.reverseTainted.length > 0) {
+    lines.push(
+      `fold-rank: ${ranking.reverseTainted.length} file(s) held back only by the reverse rule (#1044) — would fold in isolation, blocked by a run-mode importer, not modeled in the tree above:`,
+    );
+    for (const t of ranking.reverseTainted) {
+      lines.push(`  ${rel(t.file)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Simple JSON to YAML converter
  */

package/src/cli/handlers/build.ts

@@ -148,6 +148,8 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     env: args.env,
     fold: args.fold,
     sandbox: args.sandbox,
+    foldRank: args.foldRank,
+    foldRankCollapsedFile: args.foldRankCollapsedFile,
     params,
     paramsFile: args.paramsFile,
   });

package/src/cli/handlers/components.test.ts

@@ -1,7 +1,11 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { createMockPlugin, staticDescribeResources } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
+import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import type { ParsedArgs } from "../registry";
 
 /**
@@ -28,6 +32,7 @@ const loadChantConfigMock = vi.fn();
 const buildMock = vi.fn();
 const discoverComponentsMock = vi.fn();
 const findBuildManifestByArtifactDigestMock = vi.fn();
+const readBuildManifestMock = vi.fn();
 
 vi.mock("../../lifecycle/git", () => ({
   getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
@@ -38,6 +43,7 @@ vi.mock("../../lifecycle/git", () => ({
 
 vi.mock("../../lifecycle/build-ledger-store", () => ({
   findBuildManifestByArtifactDigest: (...args: unknown[]) => findBuildManifestByArtifactDigestMock(...args),
+  readBuildManifest: (...args: unknown[]) => readBuildManifestMock(...args),
 }));
 
 vi.mock("../../lifecycle/release-ledger", async () => {
@@ -66,7 +72,7 @@ vi.mock("../../components/discover", () => ({
   discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
 }));
 
-const { runComponentsReleaseRecord, runComponentsStatus, runComponentsUnknown } = await import("./components");
+const { runComponentsReleaseRecord, runComponentsStatus, runComponentsExport, runComponentsUnknown } = await import("./components");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -126,6 +132,7 @@ describe("components handlers", () => {
     buildMock.mockReset().mockResolvedValue(makeBuildResult({}));
     discoverComponentsMock.mockReset().mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
     findBuildManifestByArtifactDigestMock.mockReset().mockResolvedValue(undefined);
+    readBuildManifestMock.mockReset().mockResolvedValue(null);
 
     delete process.env.GITHUB_RUN_ID;
     delete process.env.CI_PIPELINE_ID;
@@ -569,6 +576,197 @@ describe("components handlers", () => {
     });
   });
 
+  describe("runComponentsExport", () => {
+    const originalCwd = process.cwd();
+    let srcDir: string;
+    let outDir: string;
+
+    function makeManifest(overrides: Partial<BuildArchiveManifest> = {}): BuildArchiveManifest {
+      return {
+        version: 1,
+        component: "search-service",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        manifestDigest: "sha256:manifest1",
+        contents: [
+          { kind: "template", path: "search.template.json", digest: "sha256:tmpl1", mediaType: "application/json" },
+          { kind: "asset", path: "dist/search.zip", digest: "sha256:asset1", mediaType: "application/octet-stream" },
+        ],
+        ...overrides,
+      };
+    }
+
+    beforeEach(async () => {
+      srcDir = await mkdtemp(join(tmpdir(), "chant-export-src-"));
+      outDir = await mkdtemp(join(tmpdir(), "chant-export-out-"));
+      process.chdir(srcDir);
+    });
+
+    afterEach(async () => {
+      process.chdir(originalCwd);
+      await rm(srcDir, { recursive: true, force: true });
+      await rm(outDir, { recursive: true, force: true });
+    });
+
+    test("-o/--output is required", async () => {
+      const ctx = { args: makeArgs({ path: "export", digest: "sha256:manifest1" }), plugins: [], serializers: [] };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("-o/--output <dir> is required");
+    });
+
+    test("without --digest, requires environment and --component", async () => {
+      const ctx = { args: makeArgs({ path: "export", output: outDir }), plugins: [], serializers: [] };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("Environment and --component are required");
+    });
+
+    test("--digest resolves the manifest directly and materializes every entry plus manifest.json", async () => {
+      await writeFile(join(srcDir, "search.template.json"), '{"Resources":{}}');
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", component: "search-service", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(readBuildManifestMock).toHaveBeenCalledWith("sha256:manifest1");
+      expect(await readFile(join(outDir, "search.template.json"), "utf-8")).toBe('{"Resources":{}}');
+      expect(await readFile(join(outDir, "dist", "search.zip"), "utf-8")).toBe("zip-bytes");
+      const manifestOut = JSON.parse(await readFile(join(outDir, "manifest.json"), "utf-8"));
+      expect(manifestOut.manifestDigest).toBe("sha256:manifest1");
+      expect(manifestOut.contents).toHaveLength(2);
+    });
+
+    test("resolves via the release ledger's latest record when --digest is omitted (manifestDigest present)", async () => {
+      readReleaseLedgerMock.mockResolvedValue({
+        records: [
+          {
+            version: 1, component: "search-service", env: "prod", digest: "sha256:artifact1",
+            gitSha: "abc", runId: "1", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice",
+            manifestDigest: "sha256:manifest1",
+          },
+        ],
+        malformed: 0,
+      });
+      readBuildManifestMock.mockResolvedValue(makeManifest({ contents: [] }));
+
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(readBuildManifestMock).toHaveBeenCalledWith("sha256:manifest1");
+      expect(findBuildManifestByArtifactDigestMock).not.toHaveBeenCalled();
+    });
+
+    test("falls back to findBuildManifestByArtifactDigest when the release record carries no manifestDigest", async () => {
+      readReleaseLedgerMock.mockResolvedValue({
+        records: [
+          {
+            version: 1, component: "search-service", env: "prod", digest: "sha256:artifact1",
+            gitSha: "abc", runId: "1", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice",
+          },
+        ],
+        malformed: 0,
+      });
+      findBuildManifestByArtifactDigestMock.mockResolvedValue(makeManifest({ contents: [] }));
+
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(findBuildManifestByArtifactDigestMock).toHaveBeenCalledWith("sha256:artifact1");
+    });
+
+    test("no release record for the component/env -> error", async () => {
+      readReleaseLedgerMock.mockResolvedValue({ records: [], malformed: 0 });
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("No release record for component");
+    });
+
+    test("--digest with no persisted manifest -> error", async () => {
+      readBuildManifestMock.mockResolvedValue(null);
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:missing", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("No persisted build manifest found");
+    });
+
+    test("a source file missing on disk is reported per entry and fails the command", async () => {
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+      // Neither entry's source file exists in srcDir.
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("not found on disk");
+    });
+
+    test("--json emits a structured per-entry summary", async () => {
+      await writeFile(join(srcDir, "search.template.json"), "{}");
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:manifest1", output: outDir, json: true }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(0);
+
+      const parsed = JSON.parse(stdoutBuf.join(""));
+      expect(parsed.component).toBe("search-service");
+      expect(parsed.manifestDigest).toBe("sha256:manifest1");
+      expect(parsed.entries).toHaveLength(2);
+      expect(parsed.entries.every((e: { status: string }) => e.status === "materialized")).toBe(true);
+    });
+
+    test("a --component that mismatches the resolved --digest manifest warns but still exports", async () => {
+      await writeFile(join(srcDir, "search.template.json"), "{}");
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", component: "other-service", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(0);
+      expect(stderrBuf.join("\n")).toContain("does not match the resolved manifest's component");
+    });
+  });
+
   describe("runComponentsUnknown", () => {
     test("reports the unknown subcommand", async () => {
       const ctx = { args: makeArgs({ path: "bogus" }), plugins: [], serializers: [] };