@intentius/chant 0.46.0 → 0.50.0

package/src/cli/commands/build.test.ts

@@ -184,6 +184,71 @@ export const testEntity = {
     }
   });
 
+  test("#1083 — --fold-rank ranks blockers and, given a path, writes a collapsed-format export", async () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+
+    // A pair of files that fold fine (same shape as the #1022 test above),
+    // so the build produces output and the "no output" guard doesn't fire —
+    // unrelated to the ranking below.
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `,
+    );
+    // a.ts fails directly (process.env); b.ts fails because it imports a.ts.
+    await writeFile(join(testDir, "a.ts"), `export const a = process.env.SOMETHING;`);
+    await writeFile(
+      join(testDir, "b.ts"),
+      `
+        import { a } from "./a";
+        export const b = a;
+      `,
+    );
+
+    const awsSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.keys()]),
+    };
+
+    const collapsedPath = join(testDir, "out", "fold.collapsed");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [awsSerializer],
+        fold: true,
+        foldRank: true,
+        foldRankCollapsedFile: collapsedPath,
+      });
+
+      expect(result.success).toBe(true);
+
+      const lines = errorSpy.mock.calls.map((call) => String(call[0]));
+      const rankingLine = lines.find((l) => l.includes("fold-rank:") && l.includes("blocker(s)"));
+      expect(rankingLine).toBeDefined();
+      const aLine = lines.find((l) => l.includes("retained 2") && l.includes("a.ts"));
+      expect(aLine).toBeDefined();
+
+      expect(existsSync(collapsedPath)).toBe(true);
+      const collapsed = readFileSync(collapsedPath, "utf-8").trim().split("\n");
+      expect(collapsed.sort()).toEqual(["fold;a.ts 1", "fold;a.ts;b.ts 1"].sort());
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
   describe("#1396 — ownership.env resolves from the env build parameter", () => {
     const thisDir = dirname(fileURLToPath(import.meta.url));
     const runtimePath = resolvePath(thisDir, "../../runtime");
@@ -705,6 +770,186 @@ export const testEntity = {
     expect(existsSync(join(testDir, "dist", "ops", "alb-deploy", "worker.ts"))).toBe(true);
   });
 
+  describe("committed-encrypted secret sidecars", () => {
+    const CIPHERTEXT = 'apiVersion: v1\nkind: Secret\nstringData:\n  T: ENC[AES256_GCM,data:xx]\nsops:\n  version: 3.9.4\n';
+
+    /** A serializer standing in for the k8s one: a sidecar plus a primary doc. */
+    const sidecarSerializer: Serializer = {
+      name: "multi",
+      rulePrefix: "MULTI",
+      serialize: () => ({
+        primary: "kind: Deployment\n",
+        files: { "db.sops.yaml": CIPHERTEXT },
+        verbatimFiles: ["db.sops.yaml"],
+      }),
+    };
+
+    async function writeProject(fileValue: string): Promise<void> {
+      const modulePath = resolvePath(
+        dirname(fileURLToPath(import.meta.url)),
+        "..",
+        "..",
+        "secret-provenance",
+      );
+      await writeFile(
+        join(testDir, "infra.ts"),
+        `import { declareSecret } from ${JSON.stringify(modulePath)};
+export const dbCredentials = declareSecret({ name: "db-credentials", provenance: "committed-encrypted", file: ${JSON.stringify(fileValue)} });
+export const x = { [Symbol.for("chant.declarable")]: true, entityType: "X", lexicon: "multi", kind: "resource", props: {}, attributes: {} };`,
+      );
+    }
+
+    test("a build with no --output refuses, naming the flag", async () => {
+      await writeProject("secrets/db.sops.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        format: "yaml",
+        serializers: [sidecarSerializer],
+        // no `output` — the sidecar would be echoed to stderr and lost
+      } as BuildOptions);
+
+      expect(result.success).toBe(false);
+      expect(result.errors.join("\n")).toContain("--output");
+      expect(result.errors.join("\n")).toContain("db.sops.yaml");
+    });
+
+    test("with --output the sidecar lands beside the primary, byte for byte", async () => {
+      await writeProject("secrets/db.sops.yaml");
+      const outputPath = join(testDir, "dist", "manifests.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "yaml",
+        serializers: [sidecarSerializer],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "db.sops.yaml"), "utf-8")).toBe(CIPHERTEXT);
+    });
+
+    test("a declared sidecar is never round-tripped through JSON.parse", async () => {
+      // YAML is a JSON superset, so a ciphertext file that happens to parse as
+      // JSON would otherwise be rewritten key-sorted (or re-emitted as YAML),
+      // breaking the `sops` MAC. Declared files skip that path entirely.
+      const jsonish = '{"b": 1, "a": 2}\n';
+      const jsonSidecar: Serializer = {
+        name: "multi",
+        rulePrefix: "MULTI",
+        serialize: () => ({
+          primary: "kind: Deployment\n",
+          files: { "db.sops.yaml": jsonish },
+          verbatimFiles: ["db.sops.yaml"],
+        }),
+      };
+      await writeProject("secrets/db.sops.yaml");
+      const outputPath = join(testDir, "dist", "manifests.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "yaml",
+        serializers: [jsonSidecar],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "db.sops.yaml"), "utf-8")).toBe(jsonish);
+    });
+  });
+
+  describe("SerializerResult.verbatimFiles — general channel (#1937)", () => {
+    test("a verbatim file whose content happens to be valid JSON survives byte-identical", async () => {
+      // Deliberately not key-sorted or 2-space indented — content the JSON
+      // round trip below would reformat. The old workaround (skip the round
+      // trip only because a file happens to fail JSON.parse, true for the
+      // committed-encrypted `.sops.yaml` case but never a real guarantee)
+      // could not protect this case. `verbatimFiles` can, structurally.
+      const raw = '{"b":1,"a":2,   "nested":{"z":true}}';
+      const verbatimSerializer: Serializer = {
+        name: "multi",
+        rulePrefix: "MULTI",
+        serialize: () => ({
+          primary: "{}",
+          files: { "raw.json": raw },
+          verbatimFiles: ["raw.json"],
+        }),
+      };
+      await writeFile(
+        join(testDir, "infra.ts"),
+        `export const x = { [Symbol.for("chant.declarable")]: true, entityType: "X", lexicon: "multi", kind: "resource", props: {}, attributes: {} };`,
+      );
+      const outputPath = join(testDir, "dist", "manifest.json");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "json",
+        serializers: [verbatimSerializer],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "raw.json"), "utf-8")).toBe(raw);
+    });
+  });
+
+  describe("additional-file basename collisions across lexicons (#1937)", () => {
+    const lexASerializer = (content: string): Serializer => ({
+      name: "lexa",
+      rulePrefix: "LEXA",
+      serialize: () => ({ primary: "{}", files: { "shared.yaml": content } }),
+    });
+    const lexBSerializer = (content: string): Serializer => ({
+      name: "lexb",
+      rulePrefix: "LEXB",
+      serialize: () => ({ primary: "{}", files: { "shared.yaml": content } }),
+    });
+
+    async function writeTwoLexiconProject(): Promise<void> {
+      await writeFile(
+        join(testDir, "infra.ts"),
+        [
+          `export const a = { [Symbol.for("chant.declarable")]: true, entityType: "A", lexicon: "lexa", kind: "resource", props: {}, attributes: {} };`,
+          `export const b = { [Symbol.for("chant.declarable")]: true, entityType: "B", lexicon: "lexb", kind: "resource", props: {}, attributes: {} };`,
+        ].join("\n"),
+      );
+    }
+
+    test("differing content at the same basename fails the build, naming the basename and both sources", async () => {
+      await writeTwoLexiconProject();
+      const outputPath = join(testDir, "dist", "manifest.json");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "json",
+        serializers: [lexASerializer("from lexa\n"), lexBSerializer("from lexb\n")],
+      });
+
+      expect(result.success).toBe(false);
+      const message = result.errors.join("\n");
+      expect(message).toContain("shared.yaml");
+      expect(message).toContain("lexa");
+      expect(message).toContain("lexb");
+    });
+
+    test("identical content at the same basename passes", async () => {
+      await writeTwoLexiconProject();
+      const outputPath = join(testDir, "dist", "manifest.json");
+      const shared = "same content for both\n";
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "json",
+        serializers: [lexASerializer(shared), lexBSerializer(shared)],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "shared.yaml"), "utf-8")).toBe(shared);
+    });
+  });
+
   test("op worker files go to <project>/dist/ops even with no --output (#878)", async () => {
     // The generated Op worker must land where `chant run <op> --temporal` reads it
     // (`<project>/dist/ops/<name>/worker.ts`) even when the build has no --output

package/src/cli/commands/build.ts

@@ -7,7 +7,9 @@ import {
   isOwnershipParamRef,
   resolveFoldEnabled,
   resolveSandboxEnabled,
+  resolveKnowledgeDir,
 } from "../../config";
+import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
@@ -15,10 +17,14 @@ import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
+import { coreReceiptChecks } from "../../lint/receipt-checks";
+import { coreOutputChecks } from "../../lint/output-checks";
+import { coreKnowledgeChecks } from "../../lint/knowledge-checks";
 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";
@@ -79,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;
 }
 
 /**
@@ -341,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,
@@ -382,6 +422,66 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // finding just as it suppresses a pre-synth one. A finding it suppresses is
   // counted, not dropped silently — see `suppressedPostSynthCount` below.
   let suppressedPostSynthCount = 0;
+
+  // Core-owned post-synth checks over effect receipts (#1833). Receipts are
+  // recognized by marker, lexicon-independently, so this set runs over the
+  // FULL build result — unscoped, and regardless of which plugins loaded.
+  // Same severity-resolution funnel as every other post-synth finding.
+  if (result.errors.length === 0) {
+    const receiptDiags = runPostSynthChecks(coreReceiptChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(receiptDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over serialized output text (#1526). The
+  // "[object Object]" marker means a reference got stringified instead of
+  // resolved; it can appear in any lexicon's emitted text, so this runs over
+  // the FULL build result the same way the receipt checks above do.
+  if (result.errors.length === 0) {
+    const outputDiags = runPostSynthChecks(coreOutputChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(outputDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over the project's OKF knowledge bundle
+  // (#1865, design #1059): a concept's `binds` naming no discovered entity is
+  // a stale binding, surfaced as a COR026 warning. `resolveKnowledgeDir` +
+  // `loadOkfBundle` never fail — a missing/absent `knowledge/` directory
+  // loads an empty bundle, so this is a no-op for a project that has none.
+  if (result.errors.length === 0) {
+    const bundle = await loadOkfBundle(resolveKnowledgeDir(config, configDir));
+    const knowledgeDiags = runPostSynthChecks(coreKnowledgeChecks(bundle), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(knowledgeDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
   if (result.errors.length === 0 && options.plugins) {
     for (const plugin of options.plugins) {
       if (!plugin.postSynthChecks) continue;
@@ -479,14 +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 }>();
+
+    // 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
+    // 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>();
+
+    // 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;
@@ -505,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);
@@ -523,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;
@@ -554,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(
@@ -585,17 +726,20 @@ 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;
-            // Format additional files consistently
-            try {
-              const fileParsed = JSON.parse(content);
-              fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
-              if (options.format === "yaml") {
-                fileContent = jsonToYaml(JSON.parse(fileContent));
+          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(entry.content);
+                fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
+                if (options.format === "yaml") {
+                  fileContent = jsonToYaml(JSON.parse(fileContent));
+                }
+              } catch {
+                // If not JSON, write as-is
               }
-            } catch {
-              // If not JSON, write as-is
             }
             const targetPath = join(outputDir, filename);
             mkdirSync(dirname(targetPath), { recursive: true });
@@ -609,13 +753,28 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
           })
         );
       }
+    } else if (verbatimFiles.size > 0) {
+      // A build carrying committed ciphertext and no --output has nowhere to
+      // put the sidecar. Echoing it to a terminal is not useful and dropping
+      // it silently is worse: the primary output would reference a Secret
+      // whose file never got written, and the miss would surface as a pod
+      // failing to start, far from its cause. Refuse, naming the flag.
+      const names = [...verbatimFiles].sort().join(", ");
+      errors.push(
+        formatError({
+          message:
+            `This build emits committed-encrypted secret file(s) (${names}) as sidecars, ` +
+            `which need a directory to be written into. Re-run with --output <path> ` +
+            `(the sidecars land beside it).`,
+        }),
+      );
     } else {
       // 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);
       }
     }
   }
@@ -659,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/commands/lint.ts

@@ -20,8 +20,9 @@ import { GENERATED_MARKER } from "../../discovery/files";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
-import { loadChantConfig } from "../../config";
+import { loadChantConfig, resolveKnowledgeDir } from "../../config";
 import type { LintProjectConfig } from "../../lint/rule";
+import { loadOkfBundle, type OkfBundle } from "../../okf-read";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -454,10 +455,21 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // runLint() call below via LintContext.projectConfig. Best-effort: a
   // directory with no project config lints with those rules silent.
   let projectConfig: LintProjectConfig | undefined;
+  // chant #1866 — the loaded OKF knowledge bundle, threaded into
+  // `formatStylish` below so its suppressed section can resolve `okf:`
+  // citations. Best-effort like `projectConfig` above (same
+  // `loadChantConfig` call): a directory with no chant config, or no
+  // `knowledge/` bundle, lints with citations rendering unresolved rather
+  // than a failure — `loadOkfBundle` already treats a missing directory as
+  // an empty bundle.
+  let knowledgeBundle: OkfBundle | undefined;
   try {
-    projectConfig = (await loadChantConfig(projectRoot)).config as LintProjectConfig;
+    const chantConfig = (await loadChantConfig(projectRoot)).config;
+    projectConfig = chantConfig as LintProjectConfig;
+    knowledgeBundle = await loadOkfBundle(resolveKnowledgeDir(chantConfig, projectRoot));
   } catch {
     projectConfig = undefined;
+    knowledgeBundle = undefined;
   }
 
   // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
@@ -588,7 +600,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       break;
     case "stylish":
     default:
-      output = formatStylish(diagnostics);
+      output = formatStylish(diagnostics, suppressed, knowledgeBundle);
       break;
   }
 

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,
   });