@intentius/chant 0.78.0 → 0.80.0

package/src/cli/commands/lint.ts

@@ -19,14 +19,15 @@ import { runPostSynthChecks } from "../../lint/post-synth";
 import { rule } from "../../lint/declarative";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 import { formatError, formatInfo } from "../format";
-import { GENERATED_MARKER } from "../../discovery/files";
+import { GENERATED_MARKER, hasSkipMarker, compileDiscoveryFilter } from "../../discovery/files";
+import { dirProbe, warnDiscoveryChanges } from "../../discovery/convergence";
 import { buildParamValues, resolveBuildParams } from "../../build-params";
 import { setBuildParams } from "../../params";
 import { isNoLexiconDetected } from "../../detectLexicon";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
-import { loadChantConfig, resolveKnowledgeDir } from "../../config";
+import { loadChantConfig, resolveKnowledgeDir, resolveDiscoveryGlobs } from "../../config";
 import { findProjectConfig } from "../../project-root";
 import type { LintProjectConfig } from "../../lint/rule";
 import { loadOkfBundle, type OkfBundle } from "../../okf-read";
@@ -141,7 +142,7 @@ function lexiconResolutionDiagnostic(projectRoot: string, error: Error): LintDia
  */
 async function loadAllPluginRules(
   projectPath: string,
-): Promise<{ rules: Map<string, LintRule>; intrinsics: IntrinsicDef[]; lexiconError?: Error }> {
+): Promise<{ rules: Map<string, LintRule>; intrinsics: IntrinsicDef[]; plugins: LexiconPlugin[]; lexiconError?: Error }> {
   const rules = new Map<string, LintRule>();
 
   // Load core COR/EVL rules directly
@@ -219,7 +220,7 @@ async function loadAllPluginRules(
     rules.set(r.id, r);
   }
 
-  return { rules, intrinsics, ...(lexiconError ? { lexiconError } : {}) };
+  return { rules, intrinsics, plugins, ...(lexiconError ? { lexiconError } : {}) };
 }
 
 /**
@@ -276,12 +277,14 @@ export interface LintResult {
  * `git check-ignore` for exact gitignore semantics (nesting, negation) in one
  * batched call; a non-git tree (or absent git) filters nothing.
  */
-function filterGitIgnored(files: string[], cwd: string): string[] {
+function filterGitIgnored(files: string[], cwd: string, ignoredOut?: Set<string>): string[] {
   if (files.length === 0) return files;
   try {
     const out = execFileSync("git", ["check-ignore", "--stdin"], {
       cwd,
-      input: files.join("\n"),
+      // The scan root rides along as one extra probe for #2527's warning
+      // release: whether it is itself ignored. It is never a file in `files`.
+      input: [...files, dirProbe(cwd)].join("\n"),
       encoding: "utf-8",
       // stdin piped (input), stdout captured, stderr silenced so a non-git tree's
       // "fatal: not a git repository" never leaks to the lint output.
@@ -290,6 +293,7 @@ function filterGitIgnored(files: string[], cwd: string): string[] {
       // catch handles it; exit 128 (not a repo) lands there too and filters none.
     });
     const ignored = new Set(out.split(/\r?\n/).filter(Boolean));
+    for (const p of ignored) ignoredOut?.add(p);
     return ignored.size === 0 ? files : files.filter((f) => !ignored.has(f));
   } catch {
     // No git, not a repo, or nothing ignored (exit 1) — keep every file.
@@ -297,10 +301,19 @@ function filterGitIgnored(files: string[], cwd: string): string[] {
   }
 }
 
+/** What {@link getTypeScriptFiles} saw before its git-ignore filter, for #2527's warning. */
+interface TypeScriptScan {
+  raw: string[];
+  ignored: Set<string>;
+}
+
 /**
- * Get all TypeScript files recursively, skipping git-ignored paths.
+ * Get all TypeScript files recursively, skipping git-ignored paths and the
+ * files `skip` (the project's `exclude` globs, #2519) names. `scanOut`, when
+ * given, receives the files found before the ignore filter and the paths git
+ * reported ignored.
  */
-function getTypeScriptFiles(dir: string): string[] {
+function getTypeScriptFiles(dir: string, skip?: (file: string) => boolean, scanOut?: TypeScriptScan): string[] {
   const files: string[] = [];
 
   function scan(currentDir: string): void {
@@ -315,9 +328,12 @@ function getTypeScriptFiles(dir: string): string[] {
           scan(fullPath);
         }
       } else if (entry.endsWith(".ts") && !entry.endsWith(".test.ts") && !entry.endsWith(".spec.ts")) {
+        if (skip?.(fullPath)) continue;
         // Skip chant-generated files (worker/workflow/activities bootstrap): they
         // hold no authored source and use runtime patterns the EVL* rules forbid.
-        if (readFileSync(fullPath, "utf-8").slice(0, 256).includes(GENERATED_MARKER)) {
+        // A hand-written file opts out with the skip marker (#2519).
+        const head = readFileSync(fullPath, "utf-8").slice(0, 1024);
+        if (head.slice(0, 256).includes(GENERATED_MARKER) || hasSkipMarker(head)) {
           continue;
         }
         files.push(fullPath);
@@ -326,7 +342,8 @@ function getTypeScriptFiles(dir: string): string[] {
   }
 
   scan(dir);
-  return filterGitIgnored(files, dir);
+  scanOut?.raw.push(...files);
+  return filterGitIgnored(files, dir, scanOut?.ignored);
 }
 
 /**
@@ -522,8 +539,10 @@ async function runComponentCheckDiagnostics(
  *
  * The project's configured lexicon NAMES are read, though (chant #2101), to
  * resolve the activity contracts each one declares at
- * `@intentius/chant-lexicon-<name>/op/activity-contracts` — one dynamic
- * import per lexicon, no plugin load. Without them a step calling a
+ * `@intentius/chant-lexicon-<name>/op/activity-contracts`. The plugins
+ * `lintCommand` already loaded are passed in (chant #2520), so a plugin's
+ * `activityContracts()` member counts here as it does in `chant build`, and
+ * a lexicon declared by module path is covered. Without them a step calling a
  * lexicon's activity is flagged for the absence of a contract that lexicon
  * does declare, which is the whole point of OPS013 firing outside a build.
  *
@@ -538,6 +557,7 @@ async function runOpCheckDiagnostics(
   infraPath: string,
   files: string[],
   buildParams?: BuildParamProvenance[],
+  plugins: readonly LexiconPlugin[] = [],
 ): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
   const config = loadConfig(findProjectRoot(infraPath));
   const opFiles = files.filter((f) => f.endsWith(".op.ts"));
@@ -573,8 +593,13 @@ async function runOpCheckDiagnostics(
 
   if (entities.size === 0) return { diagnostics: [], suppressed: [] };
 
-  const lexiconNames = await resolveProjectLexicons(infraPath).catch(() => [] as string[]);
-  const activityContracts = await loadActivityContracts(lexiconNames);
+  // chant #2520 — hand over the loaded plugin objects when there are any, as
+  // `chant build` does, so a plugin's `activityContracts()` member is read
+  // here too. Names alone are the fallback when no plugin loaded.
+  const activityContracts =
+    plugins.length > 0
+      ? await loadActivityContracts(plugins)
+      : await loadActivityContracts(await resolveProjectLexicons(infraPath).catch(() => [] as string[]));
 
   const raw = runPostSynthChecks(
     coreOpChecks(),
@@ -698,8 +723,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     allRules = new Map([...allRules, ...pluginRules]);
   }
 
-  // Get all TypeScript files (scan scoped to the lint arg, git-ignored trees dropped)
-  const files = getTypeScriptFiles(infraPath);
+  // Get all TypeScript files (scan scoped to the lint arg, git-ignored trees
+  // and the project's `exclude` globs dropped)
+  const scanned: TypeScriptScan = { raw: [], ignored: new Set() };
+  const files = getTypeScriptFiles(infraPath, compileDiscoveryFilter(await resolveDiscoveryGlobs(infraPath)), scanned);
+  // #2527's warning release: which of these the converged walker reads
+  // differently. `files` is today's list, unchanged.
+  await warnDiscoveryChanges({ walker: "lint", root: infraPath, files, lintIgnored: scanned });
 
   // Run lint — use per-file rules when overrides are present
   let diagnostics: LintDiagnostic[];
@@ -736,7 +766,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // Run the OPS* Op-model post-synth checks (#2122) over every `*.op.ts`
   // file under the lint target — see runOpCheckDiagnostics's doc for why
   // this needs no lexicon or build to fire.
-  const opResult = await runOpCheckDiagnostics(infraPath, files, buildParams);
+  const opResult = await runOpCheckDiagnostics(infraPath, files, buildParams, loaded.plugins);
   diagnostics.push(...opResult.diagnostics);
   suppressed.push(...opResult.suppressed);
 
@@ -790,7 +820,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
 
     // OPS* checks have no `.fix` either; re-run for the same consistency
     // reason as the COMP* re-run just above.
-    const postOpResult = await runOpCheckDiagnostics(infraPath, files, buildParams);
+    const postOpResult = await runOpCheckDiagnostics(infraPath, files, buildParams, loaded.plugins);
     diagnostics.push(...postOpResult.diagnostics);
     suppressed.push(...postOpResult.suppressed);
   }

package/src/cli/commands/onboard.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { formatSuccess, formatError, formatWarning } from "../format";
+import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module";
 
 export interface OnboardOptions {
   name: string;
@@ -331,6 +332,20 @@ export function patchDockerfile(filePath: string, name: string): PatchResult {
  * Execute the onboard command — patches monorepo infrastructure for a new lexicon.
  */
 export function onboardCommand(options: OnboardOptions): OnboardResult {
+  // chant#2578 — onboard wires a lexicon package into the chant monorepo. A
+  // lexicon declared by path has no package, so there is nothing to wire and
+  // no install step to print; say where it loads from instead.
+  if (lexiconModulePath(options.name) !== undefined) {
+    return {
+      success: false,
+      patched: [],
+      skipped: [],
+      error:
+        `lexicon "${options.name}" is declared by path in chant.config.ts and loads from ${lexiconSourceLabel(options.name)}. ` +
+        "onboard adds a lexicon package to the chant monorepo, and a lexicon loaded by path has no package to add.",
+    };
+  }
+
   const root = options.root ?? findRepoRoot();
   const patched: string[] = [];
   const skipped: string[] = [];

package/src/cli/commands/update.ts

@@ -1,3 +1,4 @@
+import { lexiconModulePath, lexiconNames } from "../../lexicon-module";
 import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync, readFileSync } from "fs";
 import { join, resolve } from "path";
 import { createRequire } from "module";
@@ -105,7 +106,7 @@ export async function updateCommand(options: UpdateOptions): Promise<UpdateResul
 
   // Load config to get lexicons
   const { config } = await loadChantConfig(projectDir);
-  const lexicons = config.lexicons ?? [];
+  const lexicons = lexiconNames(config.lexicons ?? []);
 
   if (lexicons.length === 0) {
     return {
@@ -137,6 +138,9 @@ export async function updateCommand(options: UpdateOptions): Promise<UpdateResul
 
   // Sync each lexicon
   for (const lexicon of lexicons) {
+    // chant #2520 — a lexicon declared by module path is project source, with
+    // no package to copy types from.
+    if (lexiconModulePath(lexicon) !== undefined) continue;
     const pkgName = `@intentius/chant-lexicon-${lexicon}`;
     const pkgPath = resolvePackagePath(pkgName, projectDir);
 

package/src/cli/conflict-check.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { checkConflicts } from "./conflict-check";
+import { checkConflicts, describeConflict } from "./conflict-check";
 import type { LexiconPlugin, CommandGroup } from "../lexicon";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -228,6 +228,23 @@ describe("checkConflicts", () => {
     expect(report.conflicts).toEqual([{ type: "command-group-name", key: "build", plugins: ["rogue"] }]);
   });
 
+  // #2529 — `workspace` is reserved ahead of core's own command, and the
+  // error says it is reserved rather than naming a second lexicon.
+  test("a command group named workspace is a hard conflict with a clear message", () => {
+    const plugins = [makePlugin("rogue", { commandGroup: { name: "workspace", description: "d", commands: [] } })];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts).toEqual([{ type: "command-group-name", key: "workspace", plugins: ["rogue"] }]);
+    expect(describeConflict(report.conflicts[0])).toMatch(
+      /"workspace" is a reserved chant command name, so no lexicon can register a command group with it/,
+    );
+  });
+
+  test("a conflict between two lexicons is described without the reserved-name note", () => {
+    expect(describeConflict({ type: "command-group-name", key: "kube", plugins: ["k8s", "fly"] })).toBe(
+      '  command-group-name "kube" from: k8s, fly',
+    );
+  });
+
   test("no conflict for a single lexicon's own, non-reserved command-group name", () => {
     const plugins = [
       makePlugin("k8s", { commandGroup: { name: "kube", description: "d", commands: [] } }),

package/src/cli/conflict-check.ts

@@ -108,3 +108,16 @@ export function checkConflicts(plugins: LexiconPlugin[]): ConflictReport {
 
   return { conflicts, warnings };
 }
+
+/**
+ * One line of the load-time error for a conflict. A command-group name that
+ * core reserves says so and says what to do, since the lexicon author reading
+ * it may not know the word is core's (#2529).
+ */
+export function describeConflict(c: ConflictEntry): string {
+  const line = `  ${c.type} "${c.key}" from: ${c.plugins.join(", ")}`;
+  if (c.type === "command-group-name" && RESERVED_COMMAND_NAMES.has(c.key)) {
+    return `${line} — "${c.key}" is a reserved chant command name, so no lexicon can register a command group with it. Rename the group.`;
+  }
+  return line;
+}

package/src/cli/discovery-skip.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdir, writeFile, rm, symlink, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { SKIP_MARKER } from "../discovery/files";
+
+/**
+ * chant #2519 — a project keeps a runnable `.ts` script with top-level side
+ * effects next to its declarations, and whole-project commands neither import
+ * nor lint it once the project says so, with an `exclude` glob or the skip
+ * marker.
+ *
+ * The script is the one from the issue: it reads `process.argv` as an Op name
+ * and exits the process with code 2. Imported by discovery, it reads chant's
+ * own argv and ends the command, which is what the first test shows. It also
+ * writes a file, so "imported" is visible apart from the exit code, and it
+ * indexes `process.env` dynamically, which EVL003 flags, so "linted" is
+ * visible in lint output.
+ *
+ * End-to-end through the real CLI (`main.ts`, spawned as `bin/chant` spawns
+ * it): an in-process `build()` would be killed by the script's `process.exit`,
+ * and the point is that every command's own path honours the setting.
+ */
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const mainTsPath = resolve(thisDir, "main.ts");
+const repoRoot = resolve(thisDir, "../../../..");
+/** One CLI run can take a minute on a loaded CI runner, and a test makes up to three. */
+const SPAWN_TIMEOUT = 150_000;
+const TIMEOUT = 3 * SPAWN_TIMEOUT + 30_000;
+
+describe("CLI end-to-end — discovery skips a side-effecting script (#2519)", () => {
+  let testDir: string;
+  let ranPath: string;
+
+  /** Write the project config; `extra` is spliced into the default export. */
+  async function writeConfig(extra: string): Promise<void> {
+    await writeFile(join(testDir, "chant.config.ts"), `export default { lexicons: ["k8s"]${extra} };\n`);
+  }
+
+  /** The runner from the issue, optionally headed by `header`. */
+  async function writeRunner(header = ""): Promise<void> {
+    await writeFile(
+      join(testDir, "ops", "run.ts"),
+      [
+        header,
+        'import { writeFileSync } from "node:fs";',
+        "const op = process.argv[2];",
+        "const target = process.env[`OP_${op}`];",
+        `writeFileSync(${JSON.stringify(ranPath)}, String(op));`,
+        'console.error(`no op named "${op}"`, target ?? "");',
+        "process.exit(2);",
+        "",
+      ].join("\n"),
+    );
+  }
+
+  beforeEach(async () => {
+    testDir = await realpath(
+      await (async () => {
+        const dir = join(tmpdir(), `chant-discovery-skip-test-${Date.now()}-${Math.random()}`);
+        await mkdir(join(dir, "src"), { recursive: true });
+        await mkdir(join(dir, "ops"), { recursive: true });
+        return dir;
+      })(),
+    );
+    ranPath = join(testDir, "runner-ran.txt");
+
+    await mkdir(join(testDir, "node_modules", "@intentius"), { recursive: true });
+    await symlink(
+      join(repoRoot, "lexicons", "k8s"),
+      join(testDir, "node_modules", "@intentius", "chant-lexicon-k8s"),
+      "dir",
+    );
+    await writeFile(
+      join(testDir, "src", "infra.ts"),
+      [
+        'import { Namespace } from "@intentius/chant-lexicon-k8s";',
+        'export const ns = new Namespace({ metadata: { name: "discovery-skip" } });',
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  function runCli(args: string[]): { status: number | null; stdout: string; stderr: string } {
+    const result = spawnSync("npx", ["tsx", mainTsPath, ...args], {
+      cwd: repoRoot,
+      encoding: "utf-8",
+      timeout: SPAWN_TIMEOUT,
+    });
+    return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  }
+
+  test("without exclude or the marker, the script runs under `chant build` and ends it", async () => {
+    await writeConfig("");
+    await writeRunner();
+
+    const { status, stderr } = runCli(["build", testDir]);
+
+    expect(status).toBe(2);
+    expect(stderr).toContain('no op named "build"');
+    expect(existsSync(ranPath)).toBe(true);
+  }, TIMEOUT);
+
+  test("an `exclude` glob keeps build and lint out of the script", async () => {
+    await writeConfig(', exclude: ["ops/**"]');
+    await writeRunner();
+
+    const build = runCli(["build", testDir]);
+    expect(build.stderr).not.toContain("no op named");
+    expect(build.status).toBe(0);
+    expect(build.stdout).toContain("name: discovery-skip");
+
+    const lint = runCli(["lint", testDir, "--format", "json"]);
+    expect(lint.status).toBe(0);
+    const diagnostics = JSON.parse(lint.stdout) as Array<{ file: string }>;
+    expect(diagnostics.some((d) => d.file.endsWith("infra.ts"))).toBe(true);
+    expect(diagnostics.filter((d) => d.file.includes("ops"))).toEqual([]);
+
+    expect(existsSync(ranPath), "the script was imported").toBe(false);
+  }, TIMEOUT);
+
+  test("an `exclude` glob keeps list and explain out of the script", async () => {
+    await writeConfig(', exclude: ["ops/**"]');
+    await writeRunner();
+
+    for (const command of ["list", "explain"]) {
+      const { status, stdout, stderr } = runCli([command, testDir]);
+      expect(stderr, command).not.toContain("no op named");
+      expect(status, command).toBe(0);
+      expect(stdout, command).toContain("ns");
+    }
+
+    expect(existsSync(ranPath), "the script was imported").toBe(false);
+  }, TIMEOUT);
+
+  test("the skip marker keeps build and lint out of the script with no config change", async () => {
+    await writeConfig("");
+    await writeRunner(`// ${SKIP_MARKER}: a runner, not a declaration`);
+
+    const build = runCli(["build", testDir]);
+    expect(build.stderr).not.toContain("no op named");
+    expect(build.status).toBe(0);
+
+    const lint = runCli(["lint", testDir, "--format", "json"]);
+    expect(lint.status).toBe(0);
+    const diagnostics = JSON.parse(lint.stdout) as Array<{ file: string }>;
+    expect(diagnostics.filter((d) => d.file.includes("ops"))).toEqual([]);
+
+    expect(existsSync(ranPath), "the script was imported").toBe(false);
+  }, TIMEOUT);
+
+  test("the control: without exclude, `chant lint` lints the script", async () => {
+    await writeConfig("");
+    await writeRunner();
+
+    const lint = runCli(["lint", testDir, "--format", "json"]);
+    const diagnostics = JSON.parse(lint.stdout) as Array<{ file: string; ruleId: string }>;
+    expect(diagnostics.some((d) => d.file.endsWith(join("ops", "run.ts")) && d.ruleId === "EVL003")).toBe(true);
+  }, TIMEOUT);
+});

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

@@ -70,6 +70,17 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--promote-to is forwarded to the generator as promoteTo (#2575)", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({ args: makeArgs({ env: "staging", promoteTo: "prod" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(".", "gitlab", { env: "staging", promoteTo: "prod" }, undefined, []);
+    vi.restoreAllMocks();
+  });
+
   test("chant.config.ts's declared buildParams resolve, log, and are forwarded to generateComponentsPipeline", async () => {
     loadChantConfigUpwardMock.mockResolvedValue({
       config: { buildParams: { tier: { type: "string", default: "light" } } },

package/src/cli/handlers/build.ts

@@ -51,7 +51,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   const result = await generateComponentsPipeline(
     args.path,
     lexicon,
-    { env: args.env },
+    { env: args.env, ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}) },
     args.sandbox,
     paramsResolution.provenance,
   );

package/src/cli/handlers/dev.ts

@@ -33,6 +33,9 @@ export async function runDevOnboard(ctx: CommandContext): Promise<number> {
   }
 
   const { onboardCommand, printOnboardResult } = await import("../commands/onboard");
+  // chant#2578 — so a lexicon the project declares by path is recognised.
+  const { recordProjectLexicons } = await import("../plugins");
+  await recordProjectLexicons(process.cwd());
   const result = onboardCommand({ name, verbose: ctx.args.verbose });
   await printOnboardResult(result, name);
   return result.success ? 0 : 1;

package/src/cli/handlers/graph.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
+import { GRAPH_IR_VERSION } from "../../graph-ir";
 
 /**
  * The aws emulator capability, as the real plugin declares it. `--live`
@@ -226,6 +227,25 @@ describe("runGraph", () => {
       expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
     });
 
+    // #2529 — the IR carries its version, as the first key, so a reader can
+    // decide how to read the rest before it reads anything else.
+    test("--format ir leads with the IR version", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.version).toBe(GRAPH_IR_VERSION);
+      expect(GRAPH_IR_VERSION).toBe(1);
+      expect(Object.keys(ir)[0]).toBe("version");
+    });
+
+    test("the other view formats carry no version field", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "mermaid" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).not.toContain("version");
+    });
+
     // #1675 — discovery scans sourceDir, but ops live beside it (project root,
     // `ops/`) and are found by discoverOps from the git root. The IR joins them.
     describe("ops outside sourceDir reach the IR (#1675)", () => {

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
+import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -886,7 +886,9 @@ async function emitIr(
       }
     case "ir":
     default:
-      console.log(JSON.stringify(ir, null, 2));
+      // The version leads the document (#2529), so a reader sees it before
+      // anything it might not understand.
+      console.log(JSON.stringify({ version: GRAPH_IR_VERSION, ...ir }, null, 2));
       return 0;
   }
 }

package/src/cli/handlers/lifecycle.ts

@@ -1,3 +1,4 @@
+import { lexiconNames } from "../../lexicon-module";
 import { resolve } from "node:path";
 import { commandBuildParams } from "../build-params-cli";
 import { build } from "../../build";
@@ -559,7 +560,7 @@ interface BetweenDiffArgs {
 async function runLifecycleDiffBetween(args: BetweenDiffArgs): Promise<number> {
   await fetchLifecycle();
   const { config } = await loadChantConfig(resolve("."));
-  const lexicons = args.lexiconFilter ? [args.lexiconFilter] : config.lexicons ?? [];
+  const lexicons = args.lexiconFilter ? [args.lexiconFilter] : lexiconNames(config.lexicons ?? []);
   if (lexicons.length === 0) {
     console.error(formatError({ message: "No lexicons to diff — pass a lexicon or declare `lexicons` in chant.config." }));
     return 1;

package/src/cli/handlers/misc.ts

@@ -114,6 +114,21 @@ export async function runAudit(ctx: CommandContext): Promise<number> {
     return result.exitCode;
   }
 
+  // `--max-files` (#2528) only means something to the local walk. A URL audit
+  // fetches through the host's tree API with its own caps, so the flag is
+  // refused there rather than silently ignored.
+  const maxFiles = args.maxFiles;
+  if (maxFiles !== undefined) {
+    if (!Number.isInteger(maxFiles) || maxFiles < 1) {
+      console.error(formatError({ message: `--max-files must be a positive integer (got "${maxFiles}")` }));
+      return 1;
+    }
+    if (/^https?:\/\//.test(args.path)) {
+      console.error(formatError({ message: "--max-files applies to a local path; a repository URL is fetched with its own limits." }));
+      return 1;
+    }
+  }
+
   // HTML report customization: --template <file> (full override) + --theme <file> (JSON knobs).
   let template: string | undefined;
   let theme: ReportTheme | undefined;
@@ -146,6 +161,7 @@ export async function runAudit(ctx: CommandContext): Promise<number> {
     template,
     theme,
     toolVersion: CHANT_VERSION,
+    maxFiles,
   });
   printAuditResult(result);
   return result.exitCode;