@intentius/chant 0.80.0 → 0.81.0

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

@@ -0,0 +1,167 @@
+import { afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { auditCommand, printAuditResult, type AuditCommandOptions } from "./audit";
+import { loadAuditPlugins } from "../../audit/discover";
+
+/**
+ * #2528, one of the level-0 changes on #2525's exception list (warned in
+ * v0.80.0). A truncated local walk is stated in the report, with its limit and
+ * the flag that raises it, and TF023 honours every `.gitignore` between a path
+ * and the scan root.
+ */
+
+const NOW = "2026-09-23T00:00:00.000Z";
+const dirs: string[] = [];
+
+function tmpRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-2528-"));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+let plugins: Awaited<ReturnType<typeof loadAuditPlugins>>;
+
+// Loading every audit lexicon is the slow part; once, outside any one test's timeout.
+beforeAll(async () => {
+  plugins = await loadAuditPlugins();
+}, 120_000);
+
+function audit(path: string, extra: Partial<AuditCommandOptions> = {}) {
+  return auditCommand({ path, format: "json", now: NOW, toolVersion: "0.0.0", plugins, ...extra });
+}
+
+/** Print a result the way the CLI does, and split what reached each stream. */
+function printed(result: Awaited<ReturnType<typeof auditCommand>>): { stdout: string; stderr: string } {
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(s));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(s));
+  printAuditResult(result);
+  vi.restoreAllMocks();
+  return { stdout: out.join("\n"), stderr: err.join("\n") };
+}
+
+describe("a truncated walk is reported (#2528)", () => {
+  function treeWithTail(): string {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "a"), { recursive: true });
+    for (let i = 0; i < 5; i++) writeFileSync(join(dir, "a", `${i}.md`), "x");
+    writeFileSync(join(dir, "a", "terraform.tfstate"), "{}");
+    // Past the limit: a state file TF023 would report if the walk reached it.
+    mkdirSync(join(dir, "z"), { recursive: true });
+    writeFileSync(join(dir, "z", "terraform.tfstate"), "{}");
+    return dir;
+  }
+
+  test("JSON carries truncated with the limit and the flag, and nothing goes to stderr", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6 });
+    expect(JSON.parse(result.output).truncated).toEqual({ limit: 6, flag: "--max-files" });
+    expect(result.warnings).toBeUndefined();
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toBe("");
+    expect(result.findings.map((f) => f.file)).toEqual(["a/terraform.tfstate"]);
+  });
+
+  test("the text report leads with a note naming the limit and --max-files", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6, format: "stylish" });
+    const first = result.output.split("\n")[0];
+    expect(first).toBe(
+      `Note: The scan of ${dir} stopped at 6 files, so part of the tree was not audited. ` +
+        "The limit counts every file the walk reaches, not only the ones it audits. Raise it with --max-files <n>.",
+    );
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("markdown and HTML carry the note, and HTML's embedded JSON carries the field", async () => {
+    const dir = treeWithTail();
+    const md = await audit(dir, { maxFiles: 6, format: "markdown" });
+    expect(md.output).toContain("stopped at 6 files");
+    const html = await audit(dir, { maxFiles: 6, format: "html" });
+    expect(html.output).toContain("stopped at 6 files");
+    expect(html.output).toContain('"truncated":{"limit":6,"flag":"--max-files"}');
+  });
+
+  test("SARIF has no slot for it, so the truncation goes to stderr there", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6, format: "sarif" });
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toContain(`The scan of ${dir} stopped at 6 files`);
+    expect(stderr).toContain("--max-files <n>");
+  });
+
+  test("a whole scan reports nothing: no field, no note", async () => {
+    const dir = treeWithTail();
+    const raised = await audit(dir, { maxFiles: 7 });
+    expect(JSON.parse(raised.output)).not.toHaveProperty("truncated");
+    expect(raised.warnings).toBeUndefined();
+    expect(raised.findings.map((f) => f.file).sort()).toEqual(["a/terraform.tfstate", "z/terraform.tfstate"]);
+    const text = await audit(dir, { format: "stylish" });
+    expect(text.output).not.toContain("stopped at");
+  });
+
+  test("the no-lexicons report states it too", async () => {
+    const dir = treeWithTail();
+    const json = await audit(dir, { maxFiles: 6, plugins: [] });
+    expect(JSON.parse(json.output).truncated).toEqual({ limit: 6, flag: "--max-files" });
+    const text = await audit(dir, { maxFiles: 6, plugins: [], format: "stylish" });
+    expect(text.output).toContain("stopped at 6 files");
+  });
+
+  test("an audit with nothing auditable still says the scan was cut short", async () => {
+    const dir = tmpRepo();
+    for (let i = 0; i < 4; i++) writeFileSync(join(dir, `${i}.md`), "x");
+    const result = await audit(dir, { maxFiles: 2, format: "stylish" });
+    expect(result.output).toContain("No auditable files found");
+    expect(result.output).toContain("stopped at 2 files");
+  });
+});
+
+describe("TF023 honours every .gitignore between a path and the scan root (#2528)", () => {
+  function nestedTree(nested: string | undefined): string {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "infra", "prod"), { recursive: true });
+    writeFileSync(join(dir, ".gitignore"), "node_modules/\n");
+    writeFileSync(join(dir, "infra", "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "infra", "terraform.tfstate"), "{}");
+    writeFileSync(join(dir, "infra", "prod", "terraform.tfstate"), "{}");
+    if (nested !== undefined) writeFileSync(join(dir, "infra", ".gitignore"), nested);
+    return dir;
+  }
+  const tf023 = (r: Awaited<ReturnType<typeof audit>>) =>
+    r.findings.filter((f) => f.checkId === "TF023").map((f) => f.file).sort();
+
+  test("a nested .gitignore drops the paths it covers, at any depth below it", async () => {
+    const result = await audit(nestedTree("*.tfstate\n"));
+    expect(tf023(result)).toEqual([]);
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("a nested .gitignore that does not cover the file changes nothing", async () => {
+    expect(tf023(await audit(nestedTree("*.log\n")))).toEqual(["infra/prod/terraform.tfstate", "infra/terraform.tfstate"]);
+  });
+
+  test("a .gitignore deeper than the file does not apply to it", async () => {
+    const dir = nestedTree(undefined);
+    writeFileSync(join(dir, "infra", "prod", ".gitignore"), "*.tfstate\n");
+    expect(tf023(await audit(dir))).toEqual(["infra/terraform.tfstate"]);
+  });
+
+  test("auditing from the root and from the subdirectory agree", async () => {
+    const dir = nestedTree(undefined);
+    writeFileSync(join(dir, "infra", "prod", ".gitignore"), "*.tfstate\n");
+    const fromRoot = tf023(await audit(dir));
+    const fromInfra = tf023(await audit(join(dir, "infra"))).map((p) => `infra/${p}`);
+    expect(fromRoot).toEqual(fromInfra);
+  });
+});

package/src/cli/commands/audit.ts

@@ -6,15 +6,15 @@
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "fs";
-import { join, resolve } from "path";
+import { dirname, join, resolve } from "path";
 import { auditFiles, type AuditInput, type AuditFinding, type ChecksProvider, type SuppressionStats } from "../../audit/core";
 import { AUDIT_LEXICONS, classifyFiles, loadAuditPlugins, unclaimedFiles, walkCandidates, type CandidateWalk, 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 { auditNginxConfigs } from "../../audit/nginx";
-import { auditTerraformState, isTerraformStatePath } from "../../audit/terraform-state";
-import { warnDiscoveryChanges } from "../../discovery/convergence";
+import { auditTerraformState } from "../../audit/terraform-state";
+import { workspaceMemberDirs } from "../../discovery/walk";
 import { renderMarkdown } from "../../audit/report";
 import { renderHtml, type ReportTheme } from "../../audit/report-html";
 import { buildReportJson, REPORT_SCHEMA_VERSION, type AuditSnapshot } from "../../audit/report-model";
@@ -23,7 +23,8 @@ import { extractUnpinnedActions, extractUnpinnedImages } from "../../audit/proof
 import type { ProveOptions } from "../../audit/proof";
 import type { Severity } from "../../lint/rule";
 import { formatWarning } from "../format";
-import { lexiconModulePath, lexiconPackagesToInstall, lexiconSourceLabel } from "../../lexicon-module";
+import { lexiconPackagesToInstall, lexiconSourceLabel, pathLexiconMap, recordedLexiconModules } from "../../lexicon-module";
+import { readLexiconDeclarationsStatically, unknownPathLexiconsNotice } from "../../config-static";
 
 export type AuditFormat = "stylish" | "json" | "sarif" | "markdown" | "html";
 export type AuditTier = "merge-worthy" | "all";
@@ -116,7 +117,7 @@ export interface AuditCommandResult {
    * summary line.
    */
   suppressedCount?: number;
-  /** Run diagnostics for stderr (#2528). */
+  /** Run diagnostics for stderr: a truncated scan in a format that cannot carry it (#2528). */
   warnings?: AuditWarning[];
 }
 
@@ -129,16 +130,34 @@ export const NO_LEXICONS_EXIT_CODE = 2;
  * `chant.config.ts` names by path (#2520), which has no package to install
  * (chant#2578).
  */
-function missingLexiconRemedy(names: readonly string[]): string {
+function missingLexiconRemedy(names: readonly string[], paths: ReadonlyMap<string, string>): string {
   const parts: string[] = [];
-  const pkgs = lexiconPackagesToInstall(names);
+  const pkgs = lexiconPackagesToInstall(names, paths);
   if (pkgs.length > 0) parts.push(`npm i ${pkgs.join(" ")}`);
   for (const name of names) {
-    if (lexiconModulePath(name) !== undefined) parts.push(`${name} is declared by path: ${lexiconSourceLabel(name)}`);
+    if (paths.has(name)) parts.push(`${name} is declared by path: ${lexiconSourceLabel(name, process.cwd(), paths)}`);
   }
   return parts.join("; ");
 }
 
+/**
+ * chant#2589 — the lexicons a local target's chant.config declares by path,
+ * with any recorded earlier in this process. The config is read statically
+ * (../../config-static.ts) and never evaluated, and the paths are not
+ * recorded for the loaders: audit names them in its messages, but never
+ * imports a project's lexicon module. `notice` is set when the config's
+ * `lexicons` could not be read that way.
+ */
+export function auditPathLexicons(target: string, isUrl: boolean): { paths: Map<string, string>; notice?: string } {
+  const paths = recordedLexiconModules();
+  if (isUrl) return { paths };
+  const read = readLexiconDeclarationsStatically(resolve(target));
+  if (read.status === "read") {
+    for (const [name, path] of pathLexiconMap(read.entries, dirname(read.configPath))) paths.set(name, path);
+  }
+  return { paths, notice: unknownPathLexiconsNotice(read) };
+}
+
 /** Missing audit lexicons the unclaimed files pointed at, in first-seen order. */
 function wantedLexicons(unclaimed: UnclaimedFile[]): string[] {
   return [...new Set(unclaimed.map((u) => u.lexicon))];
@@ -149,26 +168,31 @@ function wantedLexicons(unclaimed: UnclaimedFile[]): string[] {
  * lexicons it needs. Every wanted lexicon is a `-p` package so npx puts all of
  * them on the same resolution path.
  */
-export function installLine(lexicons: string[], target: string): string {
+export function installLine(
+  lexicons: string[],
+  target: string,
+  paths: ReadonlyMap<string, string> = recordedLexiconModules(),
+): string {
   // chant#2578 — a lexicon declared by path has no package for npx to fetch.
-  const pkgs = ["@intentius/chant", ...lexiconPackagesToInstall(lexicons)];
+  const pkgs = ["@intentius/chant", ...lexiconPackagesToInstall(lexicons, paths)];
   return `npx ${pkgs.map((p) => `-p ${p}`).join(" ")} chant audit ${target}`;
 }
 
 /** One-line coverage hint for the partial case: some lexicons loaded, others wanted by files on disk. */
-function missingLexiconHint(unclaimed: UnclaimedFile[]): string | undefined {
+function missingLexiconHint(unclaimed: UnclaimedFile[], paths: ReadonlyMap<string, string>): string | undefined {
   const wanted = wantedLexicons(unclaimed);
   if (wanted.length === 0) return undefined;
   const n = unclaimed.length;
   return `${n} file${n === 1 ? " looks" : "s look"} like ${wanted.join("/")} but ${wanted.length === 1 ? "that lexicon is" : "those lexicons are"} not installed, so ${n === 1 ? "it was" : "they were"} skipped` +
-    ` (${missingLexiconRemedy(wanted)}).`;
+    ` (${missingLexiconRemedy(wanted, paths)}).`;
 }
 
 /** Human-readable diagnostic for the zero-lexicon case. */
-function renderNoLexicons(target: string, unclaimed: UnclaimedFile[]): string {
+function renderNoLexicons(target: string, unclaimed: UnclaimedFile[], paths: ReadonlyMap<string, string>, truncated?: AuditTruncation): string {
   const lines: string[] = [];
   lines.push(`chant audit had nothing to look with: no audit lexicon is installed, so nothing under ${target} was inspected.`);
   lines.push("This is not a clean result. Detection and checks live in the lexicon packages.");
+  if (truncated) lines.push("", `Note: ${truncationNote(truncated, target)}`);
   const wanted = wantedLexicons(unclaimed);
   if (unclaimed.length > 0) {
     lines.push("", "Files that wanted a lexicon:");
@@ -179,12 +203,17 @@ function renderNoLexicons(target: string, unclaimed: UnclaimedFile[]): string {
     lines.push("", "No file under the target looked like CI, Kubernetes, Helm, Docker, CloudFormation, ARM, Config Connector, fountain, or Terraform either.");
   }
   lines.push("", "Run it with the lexicons those files need:");
-  lines.push(`  ${installLine(wanted.length > 0 ? wanted : [...AUDIT_LEXICONS], target)}`);
+  const lexicons = wanted.length > 0 ? wanted : [...AUDIT_LEXICONS];
+  lines.push(`  ${installLine(lexicons, target, paths)}`);
+  // chant#2589 — a lexicon declared by path is left out of the line above.
+  for (const name of lexicons) {
+    if (paths.has(name)) lines.push(`  (${name} is declared by path: ${lexiconSourceLabel(name, process.cwd(), paths)})`);
+  }
   return lines.join("\n");
 }
 
 /** Machine-readable form of the zero-lexicon diagnostic (`status: "no-lexicons"`). */
-function renderNoLexiconsJson(target: string, unclaimed: UnclaimedFile[]): string {
+function renderNoLexiconsJson(target: string, unclaimed: UnclaimedFile[], paths: ReadonlyMap<string, string>, truncated?: AuditTruncation): string {
   const wanted = wantedLexicons(unclaimed);
   return JSON.stringify(
     {
@@ -196,7 +225,8 @@ function renderNoLexiconsJson(target: string, unclaimed: UnclaimedFile[]): strin
       findings: [],
       unclaimed,
       missingLexicons: wanted,
-      install: installLine(wanted.length > 0 ? wanted : [...AUDIT_LEXICONS], target),
+      install: installLine(wanted.length > 0 ? wanted : [...AUDIT_LEXICONS], target, paths),
+      truncated,
     },
     null,
     2,
@@ -406,32 +436,26 @@ async function buildSnapshot(options: AuditCommandOptions, files: string[], isUr
   };
 }
 
-/**
- * Warnings for the two level-0 changes #2528 makes in the next release, one
- * release ahead of it (#2525). Neither changes today's report: a truncated walk
- * is still reported as if it were whole, and TF023 still reads only the root
- * `.gitignore`.
- */
-export function walkWarnings(walk: CandidateWalk, target: string): AuditWarning[] {
-  const warnings: AuditWarning[] = [];
-  if (walk.truncated) {
-    warnings.push({
-      message:
-        `the scan of ${target} stopped at ${walk.maxFiles} files, so part of the tree was not audited. ` +
-        "The limit counts every file the walk reaches, not only the ones it audits.",
-      hint:
-        "Raise it with --max-files <n>. From the next release, text and JSON output will also report a truncated scan.",
-    });
-  }
-  for (const change of walk.nestedGitignore) {
-    warnings.push({
-      file: change.path,
-      message: `TF023 reports this path because chant audit reads only the root .gitignore, but ${change.gitignore} ignores it.`,
-      hint:
-        "From the next release chant audit reads every .gitignore between a file and the scan root, and TF023 will no longer report this path.",
-    });
-  }
-  return warnings;
+/** The flag that raises the local walk's file limit, named wherever a truncated scan is reported. */
+export const MAX_FILES_FLAG = "--max-files";
+
+/** How a report states that the local walk stopped at its limit (#2528). JSON carries it as `truncated`. */
+export interface AuditTruncation {
+  limit: number;
+  flag: typeof MAX_FILES_FLAG;
+}
+
+/** The truncation a walk reports, or undefined for a whole scan. */
+export function walkTruncation(walk: CandidateWalk): AuditTruncation | undefined {
+  return walk.truncated ? { limit: walk.maxFiles, flag: MAX_FILES_FLAG } : undefined;
+}
+
+/** The text-report note for a truncated scan. */
+export function truncationNote(t: AuditTruncation, target: string): string {
+  return (
+    `The scan of ${target} stopped at ${t.limit} files, so part of the tree was not audited. ` +
+    `The limit counts every file the walk reaches, not only the ones it audits. Raise it with ${t.flag} <n>.`
+  );
 }
 
 /** Run the audit and produce a rendered result. */
@@ -441,6 +465,8 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   const failOn = options.failOn ?? "none";
 
   const isUrl = /^https?:\/\//.test(options.path);
+  // chant#2589 — path lexicons the target declares, read without running its config.
+  const pathLexicons = auditPathLexicons(options.path, isUrl);
 
   // Detection lives in the lexicon plugins (each one's `detectTemplate`), so a
   // lexicon that isn't installed can't claim its files. Every branch below
@@ -449,7 +475,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   // render the same way (#1623).
   const plugins = options.plugins ?? (await loadAuditPlugins());
   let candidates: RepoFile[];
-  let warnings: AuditWarning[] = [];
+  let truncated: AuditTruncation | undefined;
   if (isUrl) {
     try {
       // Fetch the whole repo's candidate files (all lexicons, not just CI) and
@@ -469,20 +495,18 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
     // One walk, plugin-delegated detection. CI (path), Dockerfiles (name), and
     // Helm charts (bundle) are special-cased by the classifier since content
     // shape alone can't disambiguate them.
-    const walk = walkCandidates(options.path, { maxFiles: options.maxFiles });
+    // Workspace members leave the root's audit only when a declaration exists
+    // (#2525 rule 3); without one this is a few existsSync calls (#2527).
+    const excludeDirs = await workspaceMemberDirs(options.path);
+    const walk = walkCandidates(options.path, { maxFiles: options.maxFiles, excludeDirs });
     candidates = walk.files;
-    warnings = walkWarnings(walk, options.path);
-    // #2527's warning release: the converged walk skips git-ignored files and,
-    // inside a project, child projects. Terraform state paths are TF023's own
-    // question and stay out of it. `candidates` is unchanged.
-    await warnDiscoveryChanges({
-      walker: "audit",
-      root: options.path,
-      files: candidates.filter((f) => !isTerraformStatePath(f.path)).map((f) => resolve(options.path, f.path)),
-    });
+    truncated = walkTruncation(walk);
   }
-  // Only a non-empty list rides on the result, so a run with nothing to warn
-  // about returns exactly the object it did before #2528.
+  // Every format but SARIF states a truncated scan in the report itself
+  // (#2528). SARIF has no slot chant fills for it, so there it goes to stderr.
+  const warnings: AuditWarning[] =
+    truncated && format === "sarif" ? [{ message: truncationNote(truncated, options.path) }] : [];
+  if (pathLexicons.notice !== undefined) warnings.push({ message: pathLexicons.notice });
   const withWarnings = warnings.length > 0 ? { warnings } : {};
   // A local target hands its directory to the classifier, so an input whose
   // path names a directory carries the directory itself (#2217): terraform's
@@ -514,14 +538,18 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   const terraformStateFindings = auditTerraformState(candidates);
 
   if (plugins.length === 0) {
-    const output = format === "json" ? renderNoLexiconsJson(options.path, unclaimed) : renderNoLexicons(options.path, unclaimed);
+    const output =
+      format === "json"
+        ? renderNoLexiconsJson(options.path, unclaimed, pathLexicons.paths, truncated)
+        : renderNoLexicons(options.path, unclaimed, pathLexicons.paths, truncated);
     return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings, ...nginxFindings, ...terraformStateFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr", ...withWarnings };
   }
 
-  const missingLexiconNote = missingLexiconHint(unclaimed);
+  const missingLexiconNote = missingLexiconHint(unclaimed, pathLexicons.paths);
 
   if (inputs.length === 0 && secretsFindings.length === 0 && wranglerFindings.length === 0 && nginxFindings.length === 0 && terraformStateFindings.length === 0) {
-    const output = `No auditable files found under ${options.path}.${missingLexiconNote ? ` ${missingLexiconNote}` : ""}`;
+    let output = `No auditable files found under ${options.path}.${missingLexiconNote ? ` ${missingLexiconNote}` : ""}`;
+    if (truncated) output += `\n\nNote: ${truncationNote(truncated, options.path)}`;
     return { success: true, status: "ok", output, findings: [], scanned: [], unclaimed, exitCode: 0, ...withWarnings };
   }
 
@@ -548,6 +576,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
 
   if (tier === "merge-worthy") findings = findings.filter((f) => isMergeWorthy(f, catalog));
   const notes = coverageNotes(inputs);
+  if (truncated) notes.unshift(truncationNote(truncated, options.path));
   if (missingLexiconNote) notes.push(missingLexiconNote);
   if (suppressionStats.count > 0) {
     notes.push(
@@ -596,7 +625,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   switch (format) {
     case "json": {
       const snapshot = await buildSnapshot(options, scanned, isUrl);
-      output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion, catalog, unclaimed }), null, 2);
+      output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion, catalog, unclaimed, truncated }), null, 2);
       break;
     }
     case "sarif":
@@ -607,7 +636,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
       break;
     case "html": {
       const snapshot = await buildSnapshot(options, scanned, isUrl);
-      output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template, catalog });
+      output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template, catalog, truncated });
       break;
     }
     default:

package/src/cli/commands/check-lexicon.ts

@@ -106,6 +106,28 @@ export async function coverageReportCheck(plugin: LexiconPlugin | undefined): Pr
   };
 }
 
+/**
+ * #2535 — a lexicon that supplies member kinds publishes them as data at a
+ * `./workspace-kinds` subpath (ws-031). The file must be JSON, validate as
+ * kind data, and ship in the package. A lexicon without the subpath passes
+ * vacuously, like `coverageReport()` above. The workspace module loads only
+ * here, when the check runs.
+ */
+export async function workspaceKindsCheck(dir: string): Promise<CheckItem> {
+  const { readPackageKinds, kindsFileShips } = await import("../../workspace/kinds");
+  const read = readPackageKinds(dir);
+  const problems = [...read.problems];
+  if (read.file && problems.length === 0 && !kindsFileShips(dir, read.file)) {
+    problems.push(`${basename(read.file)} is not covered by package.json "files", so the published package would not carry it`);
+  }
+  return {
+    name: "Any ./workspace-kinds subpath holds valid kind data",
+    tier: 1,
+    pass: problems.length === 0,
+    detail: problems.length > 0 ? problems.join("; ") : read.file ? `${read.kinds.length} kind(s): ${read.kinds.map((k) => k.name).join(", ")}` : undefined,
+  };
+}
+
 // ── Check runner ─────────────────────────────────────────────────────
 
 /**
@@ -434,6 +456,8 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
   // now states the fact directly via `coverageReport()`.
   items.push(await coverageReportCheck(plugin));
 
+  items.push(await workspaceKindsCheck(dir));
+
   // ── Tier 2: Recommended ────────────────────────────────────────
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));

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

@@ -396,3 +396,33 @@ describe("package-type-module (#1421)", () => {
     });
   });
 });
+
+describe("doctorCommand in a declared workspace (#2535)", () => {
+  test("shows a member of kind other as a warning, and adds nothing outside a workspace", async () => {
+    await withTestDir(async (testDir) => {
+      mkdirSync(join(testDir, ".git"));
+      mkdirSync(join(testDir, "app"));
+      mkdirSync(join(testDir, "docs"));
+      writeFileSync(join(testDir, "app", "chant.config.json"), "{}");
+      const before = await doctorCommand(join(testDir, "app"));
+      expect(before.checks.filter((c) => c.name.startsWith("workspace-"))).toEqual([]);
+
+      writeFileSync(
+        join(testDir, "chant.workspace.json"),
+        JSON.stringify({
+          name: "acme",
+          schema: 1,
+          members: [
+            { name: "app", dir: "app", kind: "chant" },
+            { name: "docs", dir: "docs", kind: "other", because: "a static site" },
+          ],
+        }),
+      );
+      const report = await doctorCommand(join(testDir, "app"));
+      const workspace = report.checks.filter((c) => c.name.startsWith("workspace-"));
+      expect(workspace).toEqual([
+        { name: "workspace-WSP009", status: "warn", message: expect.stringMatching(/^member docs \(docs\) is kind other, which chant does not read: a static site \(.*chant\.workspace\.json:1\)$/) },
+      ]);
+    });
+  });
+});

package/src/cli/commands/doctor.ts

@@ -8,6 +8,7 @@ import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { MCP_CONFIG_FILENAME, MCP_SETUP_COMMAND, mcpConfigPath } from "../mcp-config";
 import { loadCapabilityPlugin } from "../../components/capability-plugin-loader";
 import { isCapabilityPlugin } from "../../components/capability-plugin";
+import { findWorkspaceRoot } from "../../project-root";
 
 export interface DoctorCheck {
   name: string;
@@ -322,6 +323,23 @@ export async function doctorCommand(path: string): Promise<DoctorReport> {
     }
   }
 
+  // #2535: in a declared workspace, doctor shows the declaration checks, so
+  // a member of kind other shows as a warning. The walk up only tests
+  // whether files exist; nothing under workspace/ loads without a
+  // declaration, so level 0 is unchanged (#2525).
+  const workspace = findWorkspaceRoot(projectPath);
+  if (workspace) {
+    const { runDeclarationChecks } = await import("../../workspace/checks");
+    // The declaration and kind checks only: `chant workspace check` runs the
+    // member checks, which read every member's files.
+    const report = await runDeclarationChecks(workspace.dir, (file) => join(workspace.dir, file), { gather: false });
+    const shown = report.diagnostics.filter((d) => d.severity !== "info");
+    for (const d of shown) {
+      checks.push({ name: `workspace-${d.ruleId}`, status: d.severity === "error" ? "fail" : "warn", message: `${d.message} (${d.file}:${d.line})` });
+    }
+    if (shown.length === 0) checks.push({ name: "workspace-declaration", status: "pass", message: report.file });
+  }
+
   return {
     checks,
     success: checks.every(c => c.status !== "fail"),

package/src/cli/commands/import-agents.ts

@@ -23,7 +23,7 @@ import { scanAgentConfigs } from "../../agents/discover";
 import type { AgentRuntime, AgentScope } from "../../agents/types";
 import type { AgentImportOutcome } from "../../agents/importer";
 import type { LexiconPlugin } from "../../lexicon";
-import { loadPlugin, recordProjectLexicons } from "../plugins";
+import { loadPlugin, recordProjectLexicons, unknownPathLexiconsNotice } from "../plugins";
 import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module";
 
 /** The lexicon used when `--lexicon` isn't given: the one that models agent workloads. */
@@ -94,7 +94,11 @@ export async function importAgentsCommand(opts: ImportAgentsOptions = {}): Promi
 
   // chant#2578 — a lexicon the project's chant.config declares by path loads
   // from that module, so read the declarations before loading the plugin.
-  if (!opts.pluginLoader) await recordProjectLexicons(process.cwd());
+  // chant#2591 — read without running chant.config.ts.
+  if (!opts.pluginLoader) {
+    const notice = unknownPathLexiconsNotice(recordProjectLexicons(process.cwd()));
+    if (notice !== undefined) warnings.push(notice);
+  }
 
   let plugin: LexiconPlugin;
   try {

package/src/cli/commands/init.ts

@@ -3,7 +3,7 @@ import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline";
 import { formatSuccess, formatWarning } from "../format";
-import { loadPlugin, recordProjectLexicons } from "../plugins";
+import { loadPlugin, recordProjectLexicons, unknownPathLexiconsNotice } from "../plugins";
 import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module";
 import { MCP_CONFIG_FILENAME, detectPackageManager, generateMcpConfig, mcpConfigPath } from "../mcp-config";
 
@@ -266,10 +266,13 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
 
   // chant#2578 — `--force` into an existing project keeps its chant.config.
   // When that config declares the lexicon by path, it loads from the module
-  // and there is no package to depend on or install.
+  // and there is no package to depend on or install. chant#2591 — the config
+  // is read without running it; when that fails, init says so and treats the
+  // lexicon as a package.
   let lexiconModule: string | undefined;
   if (existsSync(join(targetDir, "chant.config.ts")) || existsSync(join(targetDir, "chant.config.json"))) {
-    await recordProjectLexicons(targetDir);
+    const notice = unknownPathLexiconsNotice(recordProjectLexicons(targetDir));
+    if (notice !== undefined) warnings.push(notice);
     if (lexiconModulePath(options.lexicon) !== undefined) {
       lexiconModule = lexiconSourceLabel(options.lexicon, targetDir);
     }
@@ -447,6 +450,22 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
     // Skills are optional — don't fail init if plugin isn't installed yet
   }
 
+  // `--template` records where the files came from (#2540, ws-047). Plain
+  // init writes no lock and never loads the lineage module.
+  if (options.template && templateSet) {
+    const { writeTemplateLock } = await import("../../workspace/lineage-init");
+    const lock = writeTemplateLock({
+      targetDir,
+      lexicon: options.lexicon,
+      template: options.template,
+      createdFiles,
+      chantVersion: getChantVersion(),
+      lexiconModule,
+    });
+    if (lock) createdFiles.push(lock);
+    else warnings.push(".chant/workspace.lock.json already exists, skipping");
+  }
+
   return {
     success: true,
     createdFiles,