@intentius/chant 0.79.0 → 0.81.0

package/src/cli/commands/audit.ts

@@ -6,14 +6,15 @@
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "fs";
-import { join } 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, collectCandidates, loadAuditPlugins, unclaimedFiles, type DetectPlugin, type RepoFile, type UnclaimedFile } from "../../audit/discover";
+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 } 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";
@@ -21,6 +22,9 @@ import { fetchRepoFiles, resolveActionSha, resolveImageDigest, resolveRepoCommit
 import { extractUnpinnedActions, extractUnpinnedImages } from "../../audit/proof";
 import type { ProveOptions } from "../../audit/proof";
 import type { Severity } from "../../lint/rule";
+import { formatWarning } from "../format";
+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";
@@ -68,6 +72,23 @@ export interface AuditCommandOptions {
    * present (URL targets have no local config file to read).
    */
   secretsScan?: SecretsScanOptions;
+  /**
+   * Files the local walk takes before it stops, counting every file
+   * (`--max-files`, #2528). Defaults to 1000. Local paths only.
+   */
+  maxFiles?: number;
+}
+
+/**
+ * A diagnostic about the run rather than the repository. Printed on stderr by
+ * `printAuditResult`, never part of `output`, so the report on stdout is the
+ * same with or without one.
+ */
+export interface AuditWarning {
+  /** The path the warning is about, when there is one. */
+  file?: string;
+  message: string;
+  hint?: string;
 }
 
 export interface AuditCommandResult {
@@ -96,14 +117,45 @@ export interface AuditCommandResult {
    * summary line.
    */
   suppressedCount?: number;
+  /** Run diagnostics for stderr: a truncated scan in a format that cannot carry it (#2528). */
+  warnings?: AuditWarning[];
 }
 
 /** Exit code when the audit had no lexicons to look with. Distinct from 1 (findings / failure). */
 export const NO_LEXICONS_EXIT_CODE = 2;
 
-/** The npm package that provides an audit lexicon's detection and checks. */
-function lexiconPackage(name: string): string {
-  return `@intentius/chant-lexicon-${name}`;
+/**
+ * What to tell the user about lexicons that did not load: an `npm i` line for
+ * the package-backed ones, and the declared path for any lexicon
+ * `chant.config.ts` names by path (#2520), which has no package to install
+ * (chant#2578).
+ */
+function missingLexiconRemedy(names: readonly string[], paths: ReadonlyMap<string, string>): string {
+  const parts: string[] = [];
+  const pkgs = lexiconPackagesToInstall(names, paths);
+  if (pkgs.length > 0) parts.push(`npm i ${pkgs.join(" ")}`);
+  for (const name of names) {
+    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. */
@@ -116,25 +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 {
-  const pkgs = ["@intentius/chant", ...lexicons.map(lexiconPackage)];
+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, 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` +
-    ` (npm i ${wanted.map(lexiconPackage).join(" ")}).`;
+    ` (${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:");
@@ -145,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(
     {
@@ -162,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,
@@ -372,6 +436,28 @@ async function buildSnapshot(options: AuditCommandOptions, files: string[], isUr
   };
 }
 
+/** 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. */
 export async function auditCommand(options: AuditCommandOptions): Promise<AuditCommandResult> {
   const format = options.format ?? "stylish";
@@ -379,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
@@ -387,6 +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 truncated: AuditTruncation | undefined;
   if (isUrl) {
     try {
       // Fetch the whole repo's candidate files (all lexicons, not just CI) and
@@ -406,8 +495,19 @@ 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.
-    candidates = collectCandidates(options.path);
+    // 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;
+    truncated = walkTruncation(walk);
   }
+  // 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
   // parse-to-graph follows a root module's local `module` calls from there. A
@@ -438,15 +538,19 @@ 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);
-    return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings, ...nginxFindings, ...terraformStateFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr" };
+    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}` : ""}`;
-    return { success: true, status: "ok", output, findings: [], scanned: [], unclaimed, exitCode: 0 };
+    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 };
   }
 
   let findings: AuditFinding[] = [];
@@ -472,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(
@@ -520,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":
@@ -531,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:
@@ -545,22 +650,20 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
     } catch (err) {
       return { success: false, output, findings, scanned, exitCode: 1, error: `Failed to write ${options.output}: ${err instanceof Error ? err.message : String(err)}` };
     }
-    return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, wroteTo: options.output, suppressedCount: suppressionStats.count };
+    return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, wroteTo: options.output, suppressedCount: suppressionStats.count, ...withWarnings };
   }
 
-  return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, suppressedCount: suppressionStats.count };
+  return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, suppressedCount: suppressionStats.count, ...withWarnings };
 }
 
-/** Print an audit result to stdout. */
+/** Print an audit result to stdout, and its warnings to stderr. */
 export function printAuditResult(result: AuditCommandResult): void {
   if (!result.success) {
     console.error(result.error ?? "Audit failed");
     return;
   }
-  if (result.wroteTo) {
-    console.error(`Wrote report to ${result.wroteTo}`);
-    return;
-  }
-  if (result.stream === "stderr") console.error(result.output);
+  if (result.wroteTo) console.error(`Wrote report to ${result.wroteTo}`);
+  else if (result.stream === "stderr") console.error(result.output);
   else console.log(result.output);
+  for (const w of result.warnings ?? []) console.error(formatWarning(w));
 }

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

@@ -33,6 +33,7 @@
  * validates against its own schemas.
  */
 
+import { lexiconNames as declaredLexiconNames } from "../../lexicon-module";
 import { existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { build, type BuildResult } from "../../build";
@@ -141,7 +142,7 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
       const { config: exampleConfig } = await loadChantConfig(join(examplesDir, entry.name));
       const lexiconNames =
         exampleConfig.lexicons && exampleConfig.lexicons.length > 0
-          ? exampleConfig.lexicons
+          ? declaredLexiconNames(exampleConfig.lexicons)
           : await detectLexicons(files);
       if (lexiconNames.length === 0) {
         results.push({

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;
@@ -95,6 +96,9 @@ export async function doctorCommand(path: string): Promise<DoctorReport> {
   const lexicons = config?.lexicons as string[] | undefined;
   if (lexicons && Array.isArray(lexicons)) {
     for (const lex of lexicons) {
+      // chant #2520 — a lexicon declared by module path is project source,
+      // not a package `chant update` copies types from.
+      if (typeof lex !== "string") continue;
       const lexDir = join(projectPath, ".chant", "types", `lexicon-${lex}`);
       if (!existsSync(lexDir)) {
         checks.push({ name: `lexicon-${lex}-types`, status: "fail", message: `.chant/types/lexicon-${lex}/ not found — run chant update` });
@@ -319,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,8 @@ 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 } 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. */
 export const DEFAULT_AGENT_LEXICON = "fountain";
@@ -91,18 +92,28 @@ 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.
+  // 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 {
     plugin = await (opts.pluginLoader ?? loadPlugin)(lexiconName);
   } catch (err) {
+    const remedy =
+      lexiconModulePath(lexiconName) !== undefined
+        ? `The ${lexiconName} lexicon is declared by path in chant.config.ts: ${lexiconSourceLabel(lexiconName)}`
+        : `Install it with: npm i @intentius/chant-lexicon-${lexiconName}`;
     return {
       success: false,
       generatedFiles: [],
       summary: { discovered: scan.sites.length, mapped: 0 },
       warnings,
-      error:
-        `Could not load the ${lexiconName} lexicon: ${err instanceof Error ? err.message : String(err)}\n` +
-        `Install it with: npm i @intentius/chant-lexicon-${lexiconName}`,
+      error: `Could not load the ${lexiconName} lexicon: ${err instanceof Error ? err.message : String(err)}\n${remedy}`,
     };
   }
 

package/src/cli/commands/init.ts

@@ -3,7 +3,8 @@ import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline";
 import { formatSuccess, formatWarning } from "../format";
-import { loadPlugin } from "../plugins";
+import { loadPlugin, recordProjectLexicons, unknownPathLexiconsNotice } from "../plugins";
+import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module";
 import { MCP_CONFIG_FILENAME, detectPackageManager, generateMcpConfig, mcpConfigPath } from "../mcp-config";
 
 /** Read the current chant package version from our own package.json. */
@@ -53,16 +54,27 @@ export interface InitResult {
   warnings: string[];
   /** Error message if failed */
   error?: string;
+  /**
+   * chant#2578 — where the lexicon loads from when the directory's existing
+   * chant.config declares it by path. There is no package to depend on or
+   * install for it.
+   */
+  lexiconModule?: string;
 }
 
 /**
  * Generate package.json content
  */
-function generatePackageJson(lexicon: string, extraScripts?: Record<string, string>): string {
+function generatePackageJson(
+  lexicon: string,
+  extraScripts?: Record<string, string>,
+  lexiconIsPackage = true,
+): string {
   const ver = getChantVersion();
   const dependencies: Record<string, string> = {
     "@intentius/chant": `^${ver}`,
-    [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}`,
+    // chant#2578 — a lexicon declared by path is not a package to depend on.
+    ...(lexiconIsPackage ? { [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}` } : {}),
   };
 
   const pkg = {
@@ -252,6 +264,20 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
     mkdirSync(targetDir, { recursive: true });
   }
 
+  // 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. 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"))) {
+    const notice = unknownPathLexiconsNotice(recordProjectLexicons(targetDir));
+    if (notice !== undefined) warnings.push(notice);
+    if (lexiconModulePath(options.lexicon) !== undefined) {
+      lexiconModule = lexiconSourceLabel(options.lexicon, targetDir);
+    }
+  }
+
   // Load plugin early to get template set (used for scripts + source files)
   let templateSet: import("../../lexicon").InitTemplateSet | undefined;
   try {
@@ -272,7 +298,7 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
   // Generate package.json
   writeIfNotExists(
     join(targetDir, "package.json"),
-    generatePackageJson(options.lexicon, templateSet?.scripts),
+    generatePackageJson(options.lexicon, templateSet?.scripts, lexiconModule === undefined),
     "package.json",
     createdFiles,
     warnings,
@@ -361,29 +387,32 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
     warnings,
   );
 
-  // Scaffold .chant/types/lexicon-{lexicon}/ stub
-  const lexiconTypesDir = join(targetDir, ".chant", "types", `lexicon-${options.lexicon}`);
-  mkdirSync(lexiconTypesDir, { recursive: true });
+  // Scaffold .chant/types/lexicon-{lexicon}/ stub. A lexicon declared by path
+  // is imported by its path, so it has no package name to stub (chant#2578).
+  if (lexiconModule === undefined) {
+    const lexiconTypesDir = join(targetDir, ".chant", "types", `lexicon-${options.lexicon}`);
+    mkdirSync(lexiconTypesDir, { recursive: true });
 
-  writeIfNotExists(
-    join(lexiconTypesDir, "package.json"),
-    JSON.stringify(
-      { name: `@intentius/chant-lexicon-${options.lexicon}`, version: "0.0.0", types: "./index.d.ts" },
-      null,
-      2,
-    ),
-    `.chant/types/lexicon-${options.lexicon}/package.json`,
-    createdFiles,
-    warnings,
-  );
+    writeIfNotExists(
+      join(lexiconTypesDir, "package.json"),
+      JSON.stringify(
+        { name: `@intentius/chant-lexicon-${options.lexicon}`, version: "0.0.0", types: "./index.d.ts" },
+        null,
+        2,
+      ),
+      `.chant/types/lexicon-${options.lexicon}/package.json`,
+      createdFiles,
+      warnings,
+    );
 
-  writeIfNotExists(
-    join(lexiconTypesDir, "index.d.ts"),
-    `// Lexicon type stubs — run "chant update" to sync full types\nexport {};\n`,
-    `.chant/types/lexicon-${options.lexicon}/index.d.ts`,
-    createdFiles,
-    warnings,
-  );
+    writeIfNotExists(
+      join(lexiconTypesDir, "index.d.ts"),
+      `// Lexicon type stubs — run "chant update" to sync full types\nexport {};\n`,
+      `.chant/types/lexicon-${options.lexicon}/index.d.ts`,
+      createdFiles,
+      warnings,
+    );
+  }
 
   // Generate the project's MCP config. It lands in the directory init was
   // pointed at, like everything else init produces, and at the path
@@ -421,10 +450,27 @@ 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,
     warnings,
+    ...(lexiconModule !== undefined ? { lexiconModule } : {}),
   };
 }
 
@@ -453,6 +499,11 @@ export async function printInitResult(
 
   console.log("");
 
+  if (result.lexiconModule !== undefined) {
+    console.log(`The lexicon loads from ${result.lexiconModule}, as chant.config.ts declares. It has no package to install.`);
+    console.log("");
+  }
+
   const pm = detectPackageManager(options?.cwd);
 
   // Interactive install prompt