@intentius/chant 0.44.13 → 0.45.0

package/src/audit/discover.ts

@@ -243,6 +243,63 @@ export function isCandidatePath(path: string): boolean {
   return /\.(ya?ml|json|template)$/i.test(name);
 }
 
+/**
+ * What a candidate file looks like it wants, judged cheaply by core alone
+ * (path, filename, a few content markers) with no lexicon plugin involved.
+ * Names the lexicon that would have claimed a file when that lexicon isn't
+ * installed (#1623). Deliberately coarse: precision comes from the plugin's
+ * `detectTemplate`, which is exactly what's missing in that case.
+ * `terraform` is not an audit lexicon; `*.tf` is surfaced so the user learns
+ * the audit never reads it (see `chant carve`).
+ */
+export type LexiconHint = AuditLexicon | "terraform";
+
+export function hintLexiconForFile(path: string, content: string): LexiconHint | undefined {
+  const name = basename(path);
+  const ci = ciLexiconForPath(path);
+  if (ci) return ci;
+  if (isDockerfileName(name)) return "docker";
+  if (name === "Chart.yaml") return "helm";
+  if (/\.tf$/i.test(name)) return "terraform";
+  const head = content.slice(0, 64 * 1024);
+  if (/cnrm\.cloud\.google\.com/.test(head)) return "gcp";
+  if (/AWSTemplateFormatVersion|["']?Type["']?\s*:\s*["']AWS::/.test(head)) return "aws";
+  if (/deploymentTemplate\.json/.test(head)) return "azure";
+  if (isYaml(name)) {
+    if (/^apiVersion:/m.test(head) && /^kind:/m.test(head)) return "k8s";
+    if (/^services:/m.test(head)) return "docker";
+  }
+  return undefined;
+}
+
+/** A candidate file that looked like it belonged to a lexicon the audit did not have. */
+export interface UnclaimedFile {
+  path: string;
+  lexicon: LexiconHint;
+}
+
+/**
+ * Files no loaded lexicon claimed, paired with the lexicon core guesses they
+ * wanted. Only files whose guessed lexicon is absent are reported; a file an
+ * installed lexicon declined is that plugin's call, not a coverage gap.
+ */
+export function unclaimedFiles(files: RepoFile[], inputs: AuditInput[], plugins: DetectPlugin[]): UnclaimedFile[] {
+  const loaded = new Set<string>(plugins.map((p) => p.name));
+  const claimed = new Set<string>();
+  for (const i of inputs) {
+    if (i.files) for (const rel of Object.keys(i.files)) claimed.add(i.path === "." ? rel : `${i.path}/${rel}`);
+    else claimed.add(i.path);
+  }
+  const out: UnclaimedFile[] = [];
+  for (const f of files) {
+    if (claimed.has(f.path)) continue;
+    const lexicon = hintLexiconForFile(f.path, f.content);
+    if (!lexicon || loaded.has(lexicon)) continue;
+    out.push({ path: f.path, lexicon });
+  }
+  return out;
+}
+
 /** Collect Helm charts as bundles from an in-memory file set; returns inputs + chart path-prefixes. */
 function classifyHelm(files: RepoFile[], plugin: DetectPlugin | undefined): { inputs: AuditInput[]; prefixes: string[] } {
   const inputs: AuditInput[] = [];
@@ -315,15 +372,26 @@ export function classifyFiles(files: RepoFile[], plugins: DetectPlugin[]): Audit
  * then handed to the shared `classifyFiles`. Detection is skipped for any
  * lexicon whose plugin isn't provided, so a caller can scope discovery.
  */
-export function discoverByDetection(root: string, plugins: LexiconPlugin[]): AuditInput[] {
+export function discoverByDetection(root: string, plugins: DetectPlugin[]): AuditInput[] {
+  return classifyFiles(collectCandidates(root), plugins);
+}
+
+/** The walk half of `discoverByDetection`: candidate files read into memory, paths relative to the root. */
+export function collectCandidates(root: string): RepoFile[] {
   const all: string[] = [];
   walkFiles(root, all);
   const files: RepoFile[] = [];
   for (const full of all) {
     const path = relative(root, full);
+    // Terraform is never audited; the path alone is enough to say so (#1623).
+    // Kept out of `isCandidatePath` so remote fetches never pull HCL.
+    if (/\.tf$/i.test(path)) {
+      files.push({ path, content: "" });
+      continue;
+    }
     if (!isCandidatePath(path)) continue;
     const content = readSafe(full);
     if (content !== undefined) files.push({ path, content });
   }
-  return classifyFiles(files, plugins);
+  return files;
 }

package/src/audit/edge-init-safety.test.ts

@@ -1,43 +1,174 @@
 import { describe, test, expect } from "vitest";
-import { readdirSync, readFileSync, existsSync } from "fs";
+import { readdirSync, readFileSync, existsSync, statSync } from "fs";
 import { fileURLToPath } from "url";
-import { join } from "path";
+import { join, dirname, resolve } from "path";
+import ts from "typescript";
 
 /**
- * #428: the lexicon modules the hosted service imports on the edge — post-synth
- * checks (+ their local helpers) and the `detect` modules — must not run Node-only
- * APIs at module load. `createRequire(import.meta.url)` at module scope throws on
- * Workers (import.meta.url is undefined), crashing the worker at startup. Anything
- * that genuinely needs it must do so lazily, inside a function, behind a try.
+ * #428 / #1621: the lexicon modules the hosted service imports on the edge —
+ * the post-synth barrel and the `detect` module, plus everything they reach
+ * through static imports — must not build filesystem paths at module load.
+ * On workerd `import.meta.url` is undefined and `__dirname`, `require` and
+ * `process.cwd()` do not exist, so a module-scope
+ * `dirname(fileURLToPath(import.meta.url))` crashes the worker at startup.
+ * Anything that genuinely needs a path must compute it lazily, inside a
+ * function, behind a try.
+ *
+ * The old guard only grepped the post-synth files themselves for
+ * `createRequire`. azure's `deploy-scopes.ts` (reached from azr030) used
+ * `fileURLToPath` and slipped through. This version walks the transitive
+ * relative-import graph of every barrel with the TypeScript parser and flags
+ * the whole family of constructions at module scope.
  */
 const lexiconsDir = fileURLToPath(new URL("../../../../lexicons", import.meta.url));
 
-function edgeImportedFiles(): string[] {
+function barrels(): string[] {
   const out: string[] = [];
   for (const lex of readdirSync(lexiconsDir)) {
     const detect = join(lexiconsDir, lex, "src", "detect.ts");
     if (existsSync(detect)) out.push(detect);
     const ps = join(lexiconsDir, lex, "src", "lint", "post-synth");
     if (existsSync(ps)) {
+      const index = join(ps, "index.ts");
+      if (existsSync(index)) out.push(index);
+      // Checks not re-exported from the barrel are still edge-imported
+      // individually by the hosted service, so keep them as roots too.
       for (const f of readdirSync(ps)) {
-        if (f.endsWith(".ts") && !f.endsWith(".test.ts")) out.push(join(ps, f));
+        if (f.endsWith(".ts") && !f.endsWith(".test.ts") && f !== "index.ts") out.push(join(ps, f));
       }
     }
   }
   return out;
 }
 
-describe("edge-imported lexicon modules are init-safe", () => {
-  test("no module-scope createRequire(import.meta.url)", () => {
-    const offenders: string[] = [];
-    for (const file of edgeImportedFiles()) {
-      for (const line of readFileSync(file, "utf-8").split("\n")) {
-        // Module scope = no leading whitespace. Inside a function it's indented.
-        if (/^(const|let|var|\s*)?\S.*createRequire\(import\.meta\.url\)/.test(line) && !/^\s/.test(line)) {
-          offenders.push(`${file.replace(lexiconsDir, "lexicons")}: ${line.trim()}`);
-        }
+function parse(file: string): ts.SourceFile {
+  return ts.createSourceFile(file, readFileSync(file, "utf-8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+
+/** Resolve a relative specifier to a .ts file the way the lexicon tsconfigs do. */
+function resolveRelative(from: string, spec: string): string | undefined {
+  const base = resolve(dirname(from), spec.replace(/\.js$/, ""));
+  for (const candidate of [`${base}.ts`, `${base}.tsx`, join(base, "index.ts")]) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return undefined;
+}
+
+/** Static (non-type-only) imports and re-exports of a file, resolved to paths. */
+function staticImports(sf: ts.SourceFile): string[] {
+  const out: string[] = [];
+  for (const stmt of sf.statements) {
+    let spec: string | undefined;
+    if (ts.isImportDeclaration(stmt)) {
+      if (stmt.importClause?.isTypeOnly) continue;
+      spec = (stmt.moduleSpecifier as ts.StringLiteral).text;
+    } else if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier) {
+      if (stmt.isTypeOnly) continue;
+      spec = (stmt.moduleSpecifier as ts.StringLiteral).text;
+    }
+    if (!spec || !spec.startsWith(".")) continue;
+    const resolved = resolveRelative(sf.fileName, spec);
+    if (resolved) out.push(resolved);
+  }
+  return out;
+}
+
+/** Every file reachable from the roots through static relative imports. */
+function transitiveClosure(roots: string[]): Map<string, ts.SourceFile> {
+  const seen = new Map<string, ts.SourceFile>();
+  const queue = [...roots];
+  while (queue.length) {
+    const file = queue.pop()!;
+    if (seen.has(file)) continue;
+    const sf = parse(file);
+    seen.set(file, sf);
+    for (const dep of staticImports(sf)) if (!seen.has(dep)) queue.push(dep);
+  }
+  return seen;
+}
+
+function isImportMetaUrl(node: ts.Node): boolean {
+  return (
+    ts.isPropertyAccessExpression(node) &&
+    node.name.text === "url" &&
+    ts.isMetaProperty(node.expression) &&
+    node.expression.keywordToken === ts.SyntaxKind.ImportKeyword
+  );
+}
+
+function containsImportMetaUrl(node: ts.Node): boolean {
+  if (isImportMetaUrl(node)) return true;
+  return ts.forEachChild(node, containsImportMetaUrl) ?? false;
+}
+
+/** Describe a module-scope path construction, or undefined if `node` is benign. */
+function offense(node: ts.Node): string | undefined {
+  if (ts.isIdentifier(node) && (node.text === "__dirname" || node.text === "__filename")) {
+    // `const __dirname_ = ...` is a declaration, not a use of the Node global.
+    if (ts.isVariableDeclaration(node.parent) && node.parent.name === node) return undefined;
+    return node.text;
+  }
+  if (ts.isCallExpression(node)) {
+    const callee = node.expression;
+    if (ts.isIdentifier(callee)) {
+      if (callee.text === "require") return "require(...)";
+      if ((callee.text === "fileURLToPath" || callee.text === "createRequire") && node.arguments.some(containsImportMetaUrl)) {
+        return `${callee.text}(import.meta.url)`;
       }
     }
+    if (
+      ts.isPropertyAccessExpression(callee) &&
+      ts.isIdentifier(callee.expression) &&
+      callee.expression.text === "process" &&
+      callee.name.text === "cwd"
+    ) {
+      return "process.cwd()";
+    }
+  }
+  if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "URL" && node.arguments?.some(containsImportMetaUrl)) {
+    return "new URL(..., import.meta.url)";
+  }
+  return undefined;
+}
+
+/** Bodies that run later than module evaluation. */
+function defersEvaluation(node: ts.Node): boolean {
+  return (
+    ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node) ||
+    ts.isPropertyDeclaration(node)
+  );
+}
+
+function moduleScopeOffenses(sf: ts.SourceFile): string[] {
+  const hits: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (defersEvaluation(node)) return;
+    const what = offense(node);
+    if (what) {
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+      hits.push(`${sf.fileName.replace(lexiconsDir, "lexicons")}:${line + 1}: ${what}`);
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  return hits;
+}
+
+describe("edge-imported lexicon modules are init-safe", () => {
+  test("reaches helpers through the barrel import graph", () => {
+    const files = [...transitiveClosure(barrels()).keys()];
+    expect(files).toContain(join(lexiconsDir, "azure", "src", "deploy-scopes.ts"));
+  });
+
+  test("no module-scope filesystem-path constructions in the transitive import graph", () => {
+    const offenders: string[] = [];
+    for (const sf of transitiveClosure(barrels()).values()) offenders.push(...moduleScopeOffenses(sf));
     expect(offenders, "move these into a function (lazy) — they crash edge bundles").toEqual([]);
   });
 });

package/src/audit/report-model.ts

@@ -6,6 +6,7 @@
  */
 
 import type { AuditFinding } from "./core";
+import type { UnclaimedFile } from "./discover";
 import { RULE_CATALOG, ruleDocUrl, type Authority, type Category, type FixKind, type RuleMeta, type Tier } from "./catalog";
 import { proveFix, unifiedDiff, type ProveOptions } from "./proof";
 import type { Severity } from "../lint/rule";
@@ -107,9 +108,17 @@ export interface SerializedFinding {
 export interface AuditReportJson {
   schemaVersion: string;
   tool: { name: string; version: string };
+  /**
+   * Whether the audit had lexicons to look with (#1623). `"ok"` when at least
+   * one audit lexicon resolved; `"no-lexicons"` means nothing was inspected and
+   * the report carries no findings by construction.
+   */
+  status: "ok" | "no-lexicons";
   snapshot?: AuditSnapshot;
   summary: ReportCounts;
   findings: SerializedFinding[];
+  /** Candidate files that looked like they wanted a lexicon that is not installed. */
+  unclaimed?: UnclaimedFile[];
 }
 
 export function metaFor(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): RuleMeta {
@@ -270,13 +279,14 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
 /** Build the versioned, machine-readable JSON report (stable contract). */
 export function buildReportJson(
   findings: AuditFinding[],
-  opts: { snapshot?: AuditSnapshot; toolVersion?: string; catalog?: Record<string, RuleMeta> } = {},
+  opts: { snapshot?: AuditSnapshot; toolVersion?: string; catalog?: Record<string, RuleMeta>; unclaimed?: UnclaimedFile[] } = {},
 ): AuditReportJson {
   const model = buildReportModel(findings, { catalog: opts.catalog });
   const version = opts.toolVersion ?? opts.snapshot?.toolVersion ?? "0.0.0";
   return {
     schemaVersion: REPORT_SCHEMA_VERSION,
     tool: { name: "chant-audit", version },
+    status: "ok",
     snapshot: opts.snapshot,
     summary: model.counts,
     findings: model.findings.map((f) => ({
@@ -294,5 +304,6 @@ export function buildReportJson(
       authority: f.meta.authority ?? [],
       docUrl: ruleDocUrl(f.checkId),
     })),
+    unclaimed: opts.unclaimed && opts.unclaimed.length > 0 ? opts.unclaimed : undefined,
   };
 }

package/src/audit/rules-doc.ts

@@ -49,6 +49,7 @@ export async function renderRulesReference(): Promise<string> {
   return `---
 title: Audit rules reference
 description: Every rule chant audit can report, with its tier, fix kind, and remediation.
+diataxis: reference
 ---
 
 This is the reference for every rule [\`chant audit\`](/chant/cli/audit/) can report. Each finding in a report links to its rule here.

package/src/build-params.test.ts

@@ -129,6 +129,58 @@ describe("resolveBuildParams — validation", () => {
   });
 });
 
+describe("resolveBuildParams — unset optional parameters (#1371)", () => {
+  // An unset optional parameter must read as `undefined` from `params.<name>`
+  // — never `null`. `null` is a value ("explicitly nothing"); leaving a
+  // parameter unset is not that statement, and a `null` that reaches a
+  // composite ships as `key: null` in the output.
+  test("unset optional with a declared default resolves to the default", () => {
+    const defs: BuildParamsConfig = {
+      baseImageArn: { type: "string", required: false, env: "KMV_BASE_IMAGE_ARN", default: "arn:base" },
+    };
+    const result = resolveBuildParams(defs, { env: {} });
+    expect(result.errors).toEqual([]);
+    expect(buildParamValues(result.provenance)).toEqual({ baseImageArn: "arn:base" });
+  });
+
+  test("unset optional without a default is absent — reads as undefined, never null", () => {
+    const defs: BuildParamsConfig = { baseImageArn: { type: "string", required: false, env: "KMV_BASE_IMAGE_ARN" } };
+    const result = resolveBuildParams(defs, { env: {} });
+    expect(result.errors).toEqual([]);
+    const values = buildParamValues(result.provenance);
+    expect("baseImageArn" in values).toBe(false);
+    expect(values.baseImageArn).toBeUndefined();
+    expect(values.baseImageArn ?? "fallback").toBe("fallback");
+  });
+
+  test("an env var declared but not exported is the same as unset", () => {
+    const defs: BuildParamsConfig = { baseImageArn: { type: "string", required: false, env: "KMV_BASE_IMAGE_ARN" } };
+    const result = resolveBuildParams(defs, { env: { KMV_BASE_IMAGE_ARN: undefined } });
+    expect(result.errors).toEqual([]);
+    expect(result.provenance).toEqual([]);
+  });
+
+  test("an explicit empty string is a supplied value, not unset", () => {
+    const defs: BuildParamsConfig = { baseImageArn: { type: "string", required: false, default: "arn:base" } };
+    const fromCli = resolveBuildParams(defs, { cli: { baseImageArn: "" } });
+    expect(fromCli.errors).toEqual([]);
+    expect(fromCli.provenance).toEqual([{ name: "baseImageArn", value: "", source: "cli" }]);
+
+    const fromEnv = resolveBuildParams({ baseImageArn: { type: "string", required: false, env: "X" } }, { env: { X: "" } });
+    expect(fromEnv.errors).toEqual([]);
+    expect(fromEnv.provenance).toEqual([{ name: "baseImageArn", value: "", source: "env" }]);
+  });
+
+  test("a null in --params-file is rejected, never passed through as a value", () => {
+    const defs: BuildParamsConfig = { baseImageArn: { type: "string", required: false } };
+    const result = resolveBuildParams(defs, { fromFile: { baseImageArn: null } });
+    expect(result.errors).toEqual([
+      'build parameter "baseImageArn" (from --params-file) must be a string, number, or boolean',
+    ]);
+    expect(result.provenance).toEqual([]);
+  });
+});
+
 describe("buildParamValues", () => {
   test("projects provenance records down to a plain value map", () => {
     const provenance = [

package/src/cli/build-params-cli.test.ts

@@ -56,16 +56,16 @@ describe("resolveCliBuildParams", () => {
     }
   });
 
-  test("a build with no overrides collapses to a single defaults count", () => {
+  test("a build with no overrides collapses to a single count line (#1424)", () => {
     // The provenance still records every value; the echo just stops naming
-    // what nobody set. One line, so silence still never means "no parameters
-    // reached us".
+    // them. One line, so silence still never means "no parameters reached us".
     const defs: BuildParamsConfig = { tier: { type: "string", default: "light" } };
     const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     try {
       const result = resolveCliBuildParams(defs, {});
       const logged = errorSpy.mock.calls.map((call) => String(call[0]));
-      expect(logged.some((line) => line.includes("1 parameters at their defaults"))).toBe(true);
+      expect(logged).toHaveLength(1);
+      expect(logged[0]).toContain("1 build parameter resolved (1 default); --verbose to list");
       expect(logged.some((line) => line.includes("[param] tier"))).toBe(false);
       expect(result.provenance).toEqual([{ name: "tier", value: "light", source: "default" }]);
     } finally {
@@ -73,7 +73,7 @@ describe("resolveCliBuildParams", () => {
     }
   });
 
-  test("names the overrides and collapses the defaults into a count", () => {
+  test("the count line breaks down by source, so an override's arrival is still visible", () => {
     const defs: BuildParamsConfig = {
       tier: { type: "string", default: "light" },
       target: { type: "string", default: "k3d" },
@@ -83,9 +83,26 @@ describe("resolveCliBuildParams", () => {
     try {
       resolveCliBuildParams(defs, { cli: { tier: "ha" } });
       const logged = errorSpy.mock.calls.map((call) => String(call[0]));
+      expect(logged).toHaveLength(1);
+      expect(logged[0]).toContain("3 build parameters resolved (1 from cli, 2 default); --verbose to list");
+      expect(logged.some((line) => line.includes("[param]"))).toBe(false);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("--verbose lists every parameter with its source", () => {
+    const defs: BuildParamsConfig = {
+      tier: { type: "string", default: "light" },
+      target: { type: "string", default: "k3d" },
+    };
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      resolveCliBuildParams(defs, { cli: { tier: "ha" }, verbose: true });
+      const logged = errorSpy.mock.calls.map((call) => String(call[0]));
       expect(logged.some((line) => line.includes("[param] tier") && line.includes("ha") && line.includes("cli"))).toBe(true);
-      expect(logged.some((line) => line.includes("2 more at their defaults"))).toBe(true);
-      expect(logged.some((line) => line.includes("[param] target"))).toBe(false);
+      expect(logged.some((line) => line.includes("[param] target") && line.includes("k3d") && line.includes("default"))).toBe(true);
+      expect(logged.some((line) => line.includes("--verbose to list"))).toBe(false);
     } finally {
       errorSpy.mockRestore();
     }
@@ -104,7 +121,7 @@ describe("resolveCliBuildParams", () => {
       const logged = errorSpy.mock.calls.map((call) => String(call[0]));
       expect(logged.some((line) => line.includes("[param] tier") && line.includes("ha"))).toBe(true);
       expect(logged.some((line) => line.includes("[param] target") && line.includes("k3d") && line.includes("default"))).toBe(true);
-      expect(logged.some((line) => line.includes("more at their defaults"))).toBe(false);
+      expect(logged.some((line) => line.includes("--verbose to list"))).toBe(false);
     } finally {
       if (prev === undefined) delete process.env.CHANT_PARAM_ECHO;
       else process.env.CHANT_PARAM_ECHO = prev;

package/src/cli/build-params-cli.ts

@@ -38,6 +38,8 @@ export interface CliBuildParamsArgs {
   cli?: Record<string, string>;
   /** `--params-file <path>` — a JSON file of `{ "name": value }` values, read and parsed here. */
   paramsFile?: string;
+  /** `--verbose` — list every resolved parameter one per line instead of the one-line count (#1424). */
+  verbose?: boolean;
 }
 
 export interface CliBuildParamsResolution {
@@ -62,13 +64,12 @@ export interface CliBuildParamsResolution {
  * chant #1064's acceptance criterion that this never surfaces as a thrown
  * error from inside user source.
  *
- * On success, every explicitly-set parameter is logged via `console.error` as
- * `[param] <name> = <value> (<source>)`, and the ones still at their declared
- * defaults collapse to a single count line (`CHANT_PARAM_ECHO=all` lists them
- * individually). Overrides stay unconditionally visible — not gated on
- * `--verbose` — so a build's environment-varying inputs are always in the log,
- * the same way #1022's fold decisions are; the defaults are the part that
- * never varies, which is exactly why they can be a count.
+ * On success, the resolution is summarized on one `console.error` line —
+ * `N build parameters resolved (a default, b from cli, ...); --verbose to
+ * list` — so silence never means "no parameters reached us", and the count
+ * by source says whether an override arrived. Under `--verbose` (or
+ * `CHANT_PARAM_ECHO=all`) every parameter is listed as
+ * `[param] <name> = <value> (<source>)` instead (#1424).
  */
 export function resolveCliBuildParams(
   buildParamsConfig: BuildParamsConfig | undefined,
@@ -102,27 +103,40 @@ export function resolveCliBuildParams(
     return { success: false, provenance: [], errors };
   }
 
-  // Echo what the operator SET, one line each; collapse what they did not.
-  // A project with two dozen declared parameters printed two dozen grey lines
-  // on every build, and the ones that matter — the overrides — drowned in the
-  // ones that never vary. Defaults still get named on request
-  // (CHANT_PARAM_ECHO=all), and a build with no overrides still says how many
-  // parameters resolved, so silence never means "no parameters reached us"
-  // (the failure mode warnIfParamsCannotReachProject exists for).
-  const explicit = resolution.provenance.filter((p) => p.source !== "default");
-  const defaulted = resolution.provenance.length - explicit.length;
-  const echoAll = process.env.CHANT_PARAM_ECHO === "all";
-  for (const p of echoAll ? resolution.provenance : explicit) {
-    console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
-  }
-  if (!echoAll && defaulted > 0) {
-    const more = explicit.length > 0 ? `${defaulted} more` : `${defaulted} parameters`;
-    console.error(formatInfo(`[param] ${more} at their defaults (CHANT_PARAM_ECHO=all lists them)`));
+  // #1424 — one line by default. A project with two dozen declared
+  // parameters printed two dozen grey lines on every build, ahead of the
+  // warnings the reader actually needed. The count by source still answers
+  // "did my override reach the build" (the failure mode
+  // warnIfParamsCannotReachProject exists for); --verbose names every value.
+  const verbose = args.verbose === true || process.env.CHANT_PARAM_ECHO === "all";
+  if (verbose) {
+    for (const p of resolution.provenance) {
+      console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
+    }
+  } else if (resolution.provenance.length > 0) {
+    console.error(formatInfo(summarizeBuildParams(resolution.provenance)));
   }
 
   return { success: true, provenance: resolution.provenance, errors: [] };
 }
 
+/**
+ * `N build parameters resolved (1 from cli, 3 default); --verbose to list` —
+ * the non-verbose echo of a successful resolution (#1424). Sources appear in
+ * precedence order; a source nobody used is left out.
+ */
+export function summarizeBuildParams(provenance: readonly { source: string }[]): string {
+  const counts = new Map<string, number>();
+  for (const p of provenance) counts.set(p.source, (counts.get(p.source) ?? 0) + 1);
+  const order = ["cli", "params-file", "env", "default"];
+  const rank = (s: string) => (order.includes(s) ? order.indexOf(s) : order.length);
+  const parts = [...counts.keys()]
+    .sort((a, b) => rank(a) - rank(b))
+    .map((source) => (source === "default" ? `${counts.get(source)} default` : `${counts.get(source)} from ${source}`));
+  const n = provenance.length;
+  return `${n} build parameter${n === 1 ? "" : "s"} resolved (${parts.join(", ")}); --verbose to list`;
+}
+
 /**
  * Resolve a command's declared build-time parameters, the same way `chant
  * build` does, so a `build()`/`discover()` on the declared side sees the values

package/src/cli/commands/__fixtures__/audit-coverage/.github/workflows/ci.yml

@@ -0,0 +1,5 @@
+on: push
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest

package/src/cli/commands/__fixtures__/audit-coverage/Dockerfile

@@ -0,0 +1,2 @@
+FROM ubuntu
+RUN apt-get update

package/src/cli/commands/__fixtures__/audit-coverage/infra/main.tf

@@ -0,0 +1,3 @@
+resource "aws_s3_bucket" "b" {
+  bucket = "x"
+}

package/src/cli/commands/__fixtures__/audit-coverage/infra/stack.json

@@ -0,0 +1,6 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Resources": {
+    "Bucket": { "Type": "AWS::S3::Bucket" }
+  }
+}

package/src/cli/commands/__fixtures__/audit-coverage/k8s/deploy.yaml

@@ -0,0 +1,12 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: x
+spec:
+  template:
+    spec:
+      containers:
+        - name: c
+          image: nginx:latest
+          securityContext:
+            privileged: true

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/pages/getting-started.mdx

@@ -0,0 +1,16 @@
+---
+title: Getting Started
+description: First project with the Fixture lexicon
+diataxis: tutorial
+---
+
+Install the lexicon, declare one resource, and build it.
+
+```bash
+npm install --save-dev @intentius/chant-lexicon-fixture
+chant build
+```
+
+Replace this with a walkthrough a new user can follow start to finish. Other
+pages go beside this file in `docs/pages/`, each with a `diataxis` field
+(`tutorial`, `how-to`, `reference` or `explanation`).

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/src/content.config.ts

@@ -1,7 +1,15 @@
-import { defineCollection } from 'astro:content';
+import { defineCollection, z } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
+        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+      }),
+    }),
+  }),
 };

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/generate-cli.ts

@@ -3,6 +3,8 @@ import { generate, writeGeneratedFiles } from "./generate";
 import { dirname } from "path";
 import { fileURLToPath } from "url";
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+// src/codegen/generate-cli.ts -> src/codegen -> src -> package root.
+// Two dirnames land in src/ and the first generate writes src/src/generated/ (#1614).
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const result = await generate({ verbose: true });
 writeGeneratedFiles(result, pkgDir);