@intentius/chant 0.49.0 → 0.51.0

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

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { fileURLToPath } from "url";
+import Ajv from "ajv";
 import { auditCommand, tokenForHost, coverageNotes, installLine, NO_LEXICONS_EXIT_CODE } from "./audit";
 import { discoverByDetection, loadAuditPlugins } from "../../audit/discover";
 import { MissingLexiconError, type AuditInput, type AuditLexicon } from "../../audit/core";
@@ -8,12 +9,19 @@ import { MissingLexiconError, type AuditInput, type AuditLexicon } from "../../a
 async function discoverLexicon(repo: string, lexicon: AuditLexicon): Promise<AuditInput[]> {
   return discoverByDetection(repo, await loadAuditPlugins()).filter((i) => i.lexicon === lexicon);
 }
-import { readFileSync, existsSync, rmSync } from "fs";
+import { readFileSync, existsSync, rmSync, mkdirSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import { fingerprintSecret } from "../../audit/secrets";
 
 const REPO = fileURLToPath(new URL("./__fixtures__/audit-repo", import.meta.url));
 
+/** The real, vendored SARIF 2.1.0 JSON Schema — same structural-validation convention as component-bom.test.ts. */
+function loadSarifSchema(): unknown {
+  const path = fileURLToPath(new URL("./__fixtures__/schemas/sarif-2.1.0.schema.json", import.meta.url));
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
 describe("auditCommand", () => {
   test("selects a host-specific token (no cross-host leakage)", () => {
     const env = { GITHUB_TOKEN: "gh", GITLAB_TOKEN: "gl", CODEBERG_TOKEN: "cb" } as unknown as NodeJS.ProcessEnv;
@@ -399,4 +407,210 @@ describe("auditCommand", () => {
     expect(sarif.version).toBe("2.1.0");
     expect(sarif.runs[0].results.length).toBeGreaterThan(0);
   });
+
+  test("sarif carries tier on results and dimension/category + remediation help on rules (#442)", async () => {
+    const result = await auditCommand({ path: REPO, format: "sarif" });
+    const sarif = JSON.parse(result.output) as {
+      runs: Array<{
+        tool: { driver: { rules: Array<{ id: string; helpUri?: string; help?: { text: string }; properties?: { category?: string; dimension?: string } }> } };
+        results: Array<{ ruleId: string; properties?: { tier?: string } }>;
+      }>;
+    };
+    const run = sarif.runs[0];
+    // Every result carries the finding's tier so a consumer can triage merge-worthy vs. report-only without a second lookup.
+    expect(run.results.length).toBeGreaterThan(0);
+    for (const r of run.results) {
+      expect(r.properties?.tier).toMatch(/^(merge-worthy|report-only)$/);
+    }
+    // Every rule carries its dimension/category and remediation text (mapped from the catalog, #351) as help.
+    expect(run.tool.driver.rules.length).toBeGreaterThan(0);
+    for (const rule of run.tool.driver.rules) {
+      expect(rule.properties?.category).toMatch(/^(security|correctness|best-practice)$/);
+      expect(rule.properties?.dimension).toBe(rule.properties?.category);
+      expect(rule.help?.text.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("sarif output validates against the real, vendored SARIF 2.1.0 JSON Schema", async () => {
+    const result = await auditCommand({ path: REPO, format: "sarif" });
+    const doc = JSON.parse(result.output);
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    const validate = ajv.compile(loadSarifSchema() as object);
+    const valid = validate(doc);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+
+  test("sarif schema validation also holds for the empty-result case (no findings)", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-fountain-clean", import.meta.url));
+    const result = await auditCommand({ path: repo, format: "sarif" });
+    const doc = JSON.parse(result.output);
+    expect(doc.runs[0].results).toEqual([]);
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    const validate = ajv.compile(loadSarifSchema() as object);
+    const valid = validate(doc);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+});
+
+describe("secrets detection (#443)", () => {
+  // A deliberately fake, non-functional AWS-access-key-ID-shaped value, built
+  // via concatenation (never a contiguous literal in this file's raw bytes)
+  // so pushing this file doesn't trip GitHub's own secret-scanning push
+  // protection on what is just a test fixture.
+  const FAKE_AWS_KEY = "AKIA" + "ABCDEFGHIJKLMNOP";
+  const FAKE_STRIPE_LIVE = "sk_live_" + "4eC39HqLyjWDarjtT1zdp7dc";
+
+  function tmpRepo(): string {
+    const dir = join(tmpdir(), `chant-audit-secrets-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  test("flags a hardcoded credential even when no lexicon is installed", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, ".env"), `AWS_ACCESS_KEY_ID=${FAKE_AWS_KEY}\n`);
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.status).toBe("no-lexicons"); // no lexicon installed — still not a clean miss
+    expect(result.findings.map((f) => f.checkId)).toContain("SEC001");
+    expect(JSON.stringify(result.findings)).not.toContain(FAKE_AWS_KEY); // redaction
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("sarif output never carries the raw secret value for a planted fake credential (#442)", async () => {
+    // `plugins: []` takes the "no-lexicons" diagnostic branch regardless of
+    // format, so a real lexicon (github) has to be installed for `format:
+    // "sarif"` to actually render SARIF here — same setup as the JSON
+    // round-trip test below.
+    const dir = tmpRepo();
+    mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+    writeFileSync(
+      join(dir, ".github", "workflows", "ci.yml"),
+      "name: CI\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n",
+    );
+    writeFileSync(join(dir, ".env"), `AWS_ACCESS_KEY_ID=${FAKE_AWS_KEY}\nSTRIPE_KEY=${FAKE_STRIPE_LIVE}\n`);
+    const all = await loadAuditPlugins();
+    const result = await auditCommand({ path: dir, plugins: all.filter((p) => p.name === "github"), format: "sarif" });
+    expect(result.status).toBe("ok");
+    expect(result.output).not.toContain(FAKE_AWS_KEY);
+    expect(result.output).not.toContain(FAKE_STRIPE_LIVE);
+    const sarif = JSON.parse(result.output) as { runs: Array<{ results: Array<{ ruleId: string; message: { text: string } }> }> };
+    const ruleIds = sarif.runs[0].results.map((r) => r.ruleId);
+    expect(ruleIds).toContain("SEC001");
+    expect(ruleIds).toContain("SEC006");
+    for (const r of sarif.runs[0].results) {
+      expect(r.message.text).not.toContain(FAKE_AWS_KEY);
+      expect(r.message.text).not.toContain(FAKE_STRIPE_LIVE);
+    }
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a secret rides alongside lexicon findings, tiered and cataloged like any other finding", async () => {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+    writeFileSync(
+      join(dir, ".github", "workflows", "ci.yml"),
+      "name: CI\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n",
+    );
+    writeFileSync(join(dir, ".env"), `STRIPE_KEY=${FAKE_STRIPE_LIVE}\n`);
+    const all = await loadAuditPlugins();
+    const result = await auditCommand({ path: dir, plugins: all.filter((p) => p.name === "github"), format: "json" });
+    expect(result.status).toBe("ok");
+    const json = JSON.parse(result.output);
+    const sec = json.findings.find((f: { checkId: string }) => f.checkId === "SEC006");
+    expect(sec).toBeDefined();
+    expect(sec.tier).toBe("merge-worthy");
+    expect(sec.category).toBe("security");
+    expect(sec.file).toBe(".env");
+    expect(JSON.stringify(json)).not.toContain(FAKE_STRIPE_LIVE); // redaction, incl. the JSON report
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("an inline `chant-audit-ignore` marker suppresses the finding", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, ".env"), `AWS_ACCESS_KEY_ID=${FAKE_AWS_KEY} # chant-audit-ignore: SEC001\n`);
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.findings.map((f) => f.checkId)).not.toContain("SEC001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test(".chant-audit.json's allowlist suppresses a finding by fingerprint, without storing the secret", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, ".env"), `AWS_ACCESS_KEY_ID=${FAKE_AWS_KEY}\n`);
+    const fingerprint = fingerprintSecret(FAKE_AWS_KEY);
+    writeFileSync(join(dir, ".chant-audit.json"), JSON.stringify({ secrets: { allow: [{ ruleId: "SEC001", fingerprint }] } }));
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.findings.map((f) => f.checkId)).not.toContain("SEC001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("an explicit secretsScan option overrides (and wins over) the local config", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "config.yaml"), "token: kQ7mZ9pL2xR8vT4nW1sD6uJ3\n");
+    writeFileSync(join(dir, ".chant-audit.json"), JSON.stringify({ secrets: { entropyThreshold: 1 } }));
+    const result = await auditCommand({ path: dir, plugins: [], secretsScan: { entropyThreshold: 6.5 } });
+    expect(result.findings.map((f) => f.checkId)).not.toContain("SEC010");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("Wrangler config audit (#446)", () => {
+  function tmpRepo(): string {
+    const dir = join(tmpdir(), `chant-audit-wrangler-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  test("audits wrangler.toml end to end, even when no lexicon is installed", async () => {
+    const dir = tmpRepo();
+    writeFileSync(
+      join(dir, "wrangler.toml"),
+      [
+        'name = "my-worker"',
+        "",
+        "[observability]",
+        "enabled = false",
+        "",
+        "[env.production]",
+        "workers_dev = true",
+      ].join("\n"),
+    );
+    const result = await auditCommand({ path: dir, plugins: [], format: "json" });
+    expect(result.status).toBe("no-lexicons"); // no lexicon installed — still not a clean miss
+    const ids = result.findings.map((f) => f.checkId);
+    expect(ids).toContain("WRG001");
+    expect(ids).toContain("WRG003");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a wrangler finding is tiered and cataloged like any other finding, alongside lexicon findings", async () => {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+    writeFileSync(
+      join(dir, ".github", "workflows", "ci.yml"),
+      "name: CI\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n",
+    );
+    writeFileSync(join(dir, "wrangler.toml"), 'routes = ["*/*"]\n');
+    const all = await loadAuditPlugins();
+    const result = await auditCommand({ path: dir, plugins: all.filter((p) => p.name === "github"), format: "json" });
+    expect(result.status).toBe("ok");
+    const json = JSON.parse(result.output);
+    const wrg = json.findings.find((f: { checkId: string }) => f.checkId === "WRG004");
+    expect(wrg).toBeDefined();
+    expect(wrg.tier).toBe("merge-worthy");
+    expect(wrg.category).toBe("security");
+    expect(wrg.file).toBe("wrangler.toml");
+    expect(wrg.docUrl).toBe("https://intentius.io/chant/lint-rules/audit-rules/#wrg004");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a malformed wrangler.toml contributes no findings, never fails the audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "wrangler.toml"), "not = valid = toml = [\n");
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.success).toBe(true);
+    expect(result.findings.map((f) => f.checkId)).not.toEqual(expect.arrayContaining([expect.stringMatching(/^WRG/)]));
+    rmSync(dir, { recursive: true, force: true });
+  });
 });

package/src/cli/commands/audit.ts

@@ -5,10 +5,13 @@
  * directly and runs the real post-synth checks via the audit core.
  */
 
-import { existsSync, statSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "fs";
+import { join } from "path";
 import { auditFiles, type AuditInput, type AuditFinding, type ChecksProvider } from "../../audit/core";
 import { AUDIT_LEXICONS, classifyFiles, collectCandidates, loadAuditPlugins, unclaimedFiles, type DetectPlugin, type RepoFile, type UnclaimedFile } from "../../audit/discover";
 import { RULE_CATALOG, resolveAuditCatalog, type RuleMeta } from "../../audit/catalog";
+import { scanForSecrets, parseSecretsConfig, type SecretsScanOptions } from "../../audit/secrets";
+import { auditWranglerConfigs } from "../../audit/wrangler";
 import { renderMarkdown } from "../../audit/report";
 import { renderHtml, type ReportTheme } from "../../audit/report-html";
 import { buildReportJson, REPORT_SCHEMA_VERSION, type AuditSnapshot } from "../../audit/report-model";
@@ -47,6 +50,12 @@ export interface AuditCommandOptions {
   toolVersion?: string;
   /** Injectable detection plugins (testing); defaults to every installed audit lexicon. */
   plugins?: DetectPlugin[];
+  /**
+   * Secrets-detection options (#443) — entropy threshold/min-length and an
+   * allowlist. Merged over a `.chant-audit.json` at the local target root, if
+   * present (URL targets have no local config file to read).
+   */
+  secretsScan?: SecretsScanOptions;
 }
 
 export interface AuditCommandResult {
@@ -194,6 +203,26 @@ function sarifLevel(sev: Severity): string {
   return sev === "error" ? "error" : sev === "warning" ? "warning" : "note";
 }
 
+/** `.chant-audit.json`'s `secrets` section at the local target root, if present (tolerant of a missing/malformed file). */
+function readLocalSecretsConfig(root: string): SecretsScanOptions {
+  const file = join(root, ".chant-audit.json");
+  if (!existsSync(file)) return {};
+  try {
+    return parseSecretsConfig(readFileSync(file, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Merge the local `.chant-audit.json` config under any explicitly-passed options (options win). */
+function resolveSecretsOptions(fileConfig: SecretsScanOptions, explicit?: SecretsScanOptions): SecretsScanOptions {
+  return {
+    entropyThreshold: explicit?.entropyThreshold ?? fileConfig.entropyThreshold,
+    entropyMinLength: explicit?.entropyMinLength ?? fileConfig.entropyMinLength,
+    allow: [...(fileConfig.allow ?? []), ...(explicit?.allow ?? [])],
+  };
+}
+
 /** Coverage caveats about what the audit could and couldn't see. */
 export function coverageNotes(inputs: AuditInput[]): string[] {
   const notes: string[] = [];
@@ -221,7 +250,8 @@ function renderStylish(findings: AuditFinding[], scanned: string[], notes: strin
     if (list.length === 0) return;
     lines.push("", title);
     for (const f of list) {
-      const where = f.entity ? `${f.file} (${f.entity})` : f.file;
+      const loc = f.line ? `${f.file}:${f.line}` : f.file;
+      const where = f.entity ? `${loc} (${f.entity})` : loc;
       const title = catalog[f.checkId]?.title ?? f.checkId;
       lines.push(`  [${f.checkId}] ${f.severity}  ${where}  — ${title}`);
     }
@@ -231,6 +261,14 @@ function renderStylish(findings: AuditFinding[], scanned: string[], notes: strin
   return lines.join("\n");
 }
 
+/**
+ * SARIF (2.1.0) export (#442). Rule-level metadata — category (the finding
+ * "dimension": security/correctness/best-practice) and remediation — is
+ * carried in the property bag / `help` block since SARIF's core schema has no
+ * dedicated slot for either; `tier` is per-result (a `RuleMeta` fact looked up
+ * per finding) so consumers can triage merge-worthy vs. report-only without a
+ * second catalog lookup.
+ */
 function renderSarif(findings: AuditFinding[], catalog: Record<string, RuleMeta> = RULE_CATALOG): string {
   const ruleIds = [...new Set(findings.map((f) => f.checkId))].sort();
   const rules = ruleIds.map((id) => {
@@ -239,15 +277,28 @@ function renderSarif(findings: AuditFinding[], catalog: Record<string, RuleMeta>
       id,
       name: m?.title ?? id,
       shortDescription: { text: m?.title ?? id },
+      ...(m?.remediation ? { help: { text: m.remediation } } : {}),
       helpUri: m?.authority?.[0]?.url,
+      ...(m?.category ? { properties: { category: m.category, dimension: m.category } } : {}),
+    };
+  });
+  const results = findings.map((f) => {
+    const tier = catalog[f.checkId]?.tier;
+    return {
+      ruleId: f.checkId,
+      level: sarifLevel(f.severity),
+      message: { text: f.message },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: f.file },
+            ...(f.line ? { region: { startLine: f.line } } : {}),
+          },
+        },
+      ],
+      ...(tier ? { properties: { tier } } : {}),
     };
   });
-  const results = findings.map((f) => ({
-    ruleId: f.checkId,
-    level: sarifLevel(f.severity),
-    message: { text: f.message },
-    locations: [{ physicalLocation: { artifactLocation: { uri: f.file } } }],
-  }));
   return JSON.stringify(
     {
       $schema: "https://json.schemastore.org/sarif-2.1.0.json",
@@ -327,28 +378,46 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   const unclaimed = unclaimedFiles(candidates, inputs, plugins);
   const scanned = inputs.map((i) => i.path);
 
+  // Secrets detection (#443) is independent of lexicon: it scans every
+  // candidate file's raw text, not just the ones a lexicon claimed, and runs
+  // even when no lexicon is installed at all. `.chant-audit.json` at a local
+  // target's root supplies the entropy threshold / allowlist; a URL target
+  // has no local config file to read.
+  const secretsConfig = isUrl ? {} : readLocalSecretsConfig(options.path);
+  const secretsFindings = scanForSecrets(candidates, resolveSecretsOptions(secretsConfig, options.secretsScan));
+  // Wrangler config audit (#446) is likewise lexicon-independent: it scans
+  // every candidate file for `wrangler.toml` by its own detector, not through
+  // `classifyFiles`/an installed lexicon package (no such package exists —
+  // this format ships only a detector and checks, per the issue's scope).
+  const wranglerFindings = auditWranglerConfigs(candidates);
+
   if (plugins.length === 0) {
     const output = format === "json" ? renderNoLexiconsJson(options.path, unclaimed) : renderNoLexicons(options.path, unclaimed);
-    return { success: true, status: "no-lexicons", output, findings: [], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr" };
+    return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr" };
   }
 
   const missingLexiconNote = missingLexiconHint(unclaimed);
 
-  if (inputs.length === 0) {
+  if (inputs.length === 0 && secretsFindings.length === 0 && wranglerFindings.length === 0) {
     const output = `No auditable files found under ${options.path}.${missingLexiconNote ? ` ${missingLexiconNote}` : ""}`;
     return { success: true, status: "ok", output, findings: [], scanned: [], unclaimed, exitCode: 0 };
   }
 
-  let findings: AuditFinding[];
-  try {
-    findings = await auditFiles(inputs, { checksProvider: options.checksProvider });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
+  let findings: AuditFinding[] = [];
+  if (inputs.length > 0) {
+    try {
+      findings = await auditFiles(inputs, { checksProvider: options.checksProvider });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
+    }
   }
+  findings = [...findings, ...secretsFindings, ...wranglerFindings];
   // Resolve the audit catalog once, aggregating the audited lexicons' own
   // metadata over core's static catalog (#687). The lexicons are already loaded
-  // by `auditFiles` above, so this is cheap.
+  // by `auditFiles` above, so this is cheap. Core's static catalog (always
+  // included) carries the SEC* secrets rules, so they resolve even when
+  // `inputs` claimed nothing.
   const catalog = await resolveAuditCatalog([...new Set(inputs.map((i) => i.lexicon))]);
 
   if (tier === "merge-worthy") findings = findings.filter((f) => isMergeWorthy(f, catalog));

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");
@@ -712,7 +777,11 @@ export const testEntity = {
     const sidecarSerializer: Serializer = {
       name: "multi",
       rulePrefix: "MULTI",
-      serialize: () => ({ primary: "kind: Deployment\n", files: { "db.sops.yaml": CIPHERTEXT } }),
+      serialize: () => ({
+        primary: "kind: Deployment\n",
+        files: { "db.sops.yaml": CIPHERTEXT },
+        verbatimFiles: ["db.sops.yaml"],
+      }),
     };
 
     async function writeProject(fileValue: string): Promise<void> {
@@ -768,7 +837,11 @@ export const x = { [Symbol.for("chant.declarable")]: true, entityType: "X", lexi
       const jsonSidecar: Serializer = {
         name: "multi",
         rulePrefix: "MULTI",
-        serialize: () => ({ primary: "kind: Deployment\n", files: { "db.sops.yaml": jsonish } }),
+        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");
@@ -785,6 +858,98 @@ export const x = { [Symbol.for("chant.declarable")]: true, entityType: "X", lexi
     });
   });
 
+  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