@intentius/chant 0.79.0 → 0.81.0

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

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { lintCommand, isLintRule, loadPluginRules, LEXICON_RESOLUTION_RULE_ID, type LintOptions } from "./lint";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { mkdir, rm, writeFile } from "node:fs/promises";
@@ -641,6 +641,57 @@ describe("lintCommand — git-ignored files are not linted", () => {
   });
 });
 
+/**
+ * chant#2527: lint walks through the one discovery walk. A child project
+ * inside a project is a boundary, `include` re-admits it, and a scan root
+ * that is itself git-ignored is linted.
+ */
+describe("lintCommand — the converged discovery walk (#2527)", () => {
+  let testDir: string;
+  const EVL003 = `const t = { a: 1 };\nexport function g(k: string) { return t[k]; }\n`;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-lint-2527-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+    process.env.NO_COLOR = "1";
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    delete process.env.NO_COLOR;
+  });
+
+  async function childProject(config: Record<string, unknown>): Promise<void> {
+    await writeFile(join(testDir, "chant.config.json"), JSON.stringify({ knowledge: { dir: "knowledge" }, ...config }));
+    await writeFile(join(testDir, "index.ts"), `export const x = 1;\n`);
+    await mkdir(join(testDir, "stacks", "east"), { recursive: true });
+    await writeFile(join(testDir, "stacks", "east", "chant.config.ts"), `export default {};\n`);
+    await writeFile(join(testDir, "stacks", "east", "east.ts"), EVL003);
+  }
+
+  test("a nested child project is not linted from the parent", async () => {
+    await childProject({});
+    const result = await lintCommand({ path: testDir, format: "stylish" });
+    expect(result.diagnostics.some((d) => d.file.includes("east.ts"))).toBe(false);
+  });
+
+  test("include re-admits the child project", async () => {
+    await childProject({ include: ["stacks/east"] });
+    const result = await lintCommand({ path: testDir, format: "stylish" });
+    expect(result.diagnostics.some((d) => d.file.includes("east.ts") && d.ruleId === "EVL003")).toBe(true);
+  });
+
+  test("an ignored scan root is linted: ignore rules apply below the root only", async () => {
+    execFileSync("git", ["init", "-q"], { cwd: testDir });
+    await writeFile(join(testDir, ".gitignore"), "/carveout/\n");
+    await mkdir(join(testDir, "carveout", "src"), { recursive: true });
+    await writeFile(join(testDir, "carveout", "src", "main.ts"), EVL003);
+
+    const result = await lintCommand({ path: join(testDir, "carveout", "src"), format: "stylish" });
+    expect(result.diagnostics.some((d) => d.file.includes("main.ts") && d.ruleId === "EVL003")).toBe(true);
+  });
+});
+
 /**
  * chant #2222 (epic #2215 sub-issue 7) — `chant lint` used to print "No
  * problems found" and exit 0 on a project whose declared lexicon could not be

package/src/cli/commands/lint.ts

@@ -1,7 +1,6 @@
 import { resolve, join, relative } from "path";
 import type { BuildParamProvenance } from "../../provenance";
-import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
-import { execFileSync } from "child_process";
+import { readFileSync, writeFileSync, readdirSync } from "fs";
 import { runLint, parseDisableComments } from "../../lint/engine";
 import type { LintRule, LintDiagnostic, LintFix } from "../../lint/rule";
 import type { IntrinsicDef, LexiconPlugin } from "../../lexicon";
@@ -19,14 +18,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 { hasDiscoveryMarkerSync, isSourceFileName } from "../../discovery/files";
+import { walkDiscovery, workspaceMemberDirs } from "../../discovery/walk";
 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 +141,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 +219,7 @@ async function loadAllPluginRules(
     rules.set(r.id, r);
   }
 
-  return { rules, intrinsics, ...(lexiconError ? { lexiconError } : {}) };
+  return { rules, intrinsics, plugins, ...(lexiconError ? { lexiconError } : {}) };
 }
 
 /**
@@ -269,64 +269,26 @@ export interface LintResult {
 }
 
 /**
- * Drop paths git ignores. Vendored trees (`vendor/`), build output (`dist/`),
- * and anything else in `.gitignore` are not authored chant source — linting
- * them surfaces EVL/COR errors in code the project never wrote, which then
- * gates `chant graph --format ir` on files outside the graph. Delegates to
- * `git check-ignore` for exact gitignore semantics (nesting, negation) in one
- * batched call; a non-git tree (or absent git) filters nothing.
+ * Every TypeScript file `chant lint` reads under `dir`, through the one
+ * discovery walk (`../../discovery/walk.ts`, #2527): git-ignored paths
+ * (vendored trees and the like, which the project never wrote), dot-directories,
+ * `dist` and, inside a project, child projects are skipped, and so is what the
+ * project's `exclude` globs (#2519) name, unless `include` re-admits it. Test
+ * and spec files, chant-generated files and skip-marked files are left out.
+ * Symlinks are followed, as lint always did.
  */
-function filterGitIgnored(files: string[], cwd: string): string[] {
-  if (files.length === 0) return files;
-  try {
-    const out = execFileSync("git", ["check-ignore", "--stdin"], {
-      cwd,
-      input: files.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.
-      stdio: ["pipe", "pipe", "ignore"],
-      // Exit 1 means "nothing ignored" — execFileSync throws on non-zero, so the
-      // catch handles it; exit 128 (not a repo) lands there too and filters none.
-    });
-    const ignored = new Set(out.split(/\r?\n/).filter(Boolean));
-    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.
-    return files;
-  }
-}
-
-/**
- * Get all TypeScript files recursively, skipping git-ignored paths.
- */
-function getTypeScriptFiles(dir: string): string[] {
-  const files: string[] = [];
-
-  function scan(currentDir: string): void {
-    const entries = readdirSync(currentDir);
-
-    for (const entry of entries) {
-      const fullPath = join(currentDir, entry);
-      const stat = statSync(fullPath);
-
-      if (stat.isDirectory()) {
-        if (entry !== "node_modules" && !entry.startsWith(".")) {
-          scan(fullPath);
-        }
-      } else if (entry.endsWith(".ts") && !entry.endsWith(".test.ts") && !entry.endsWith(".spec.ts")) {
-        // 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)) {
-          continue;
-        }
-        files.push(fullPath);
-      }
-    }
-  }
-
-  scan(dir);
-  return filterGitIgnored(files, dir);
+async function getTypeScriptFiles(dir: string): Promise<string[]> {
+  // A missing or non-directory path fails here, as lint's own walk always did;
+  // the shared walk skips an unreadable directory in silence.
+  readdirSync(dir);
+  return walkDiscovery({
+    walker: "lint",
+    root: dir,
+    globs: await resolveDiscoveryGlobs(dir),
+    excludeDirs: await workspaceMemberDirs(dir),
+    followSymlinks: true,
+    accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
+  });
 }
 
 /**
@@ -522,8 +484,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 +502,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 +538,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 +668,8 @@ 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, through the one discovery walk (#2527)
+  const files = await getTypeScriptFiles(infraPath);
 
   // Run lint — use per-file rules when overrides are present
   let diagnostics: LintDiagnostic[];
@@ -736,7 +706,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 +760,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,5 +1,6 @@
+import { lexiconModulePath, lexiconNames } from "../../lexicon-module";
 import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync, readFileSync } from "fs";
-import { join, resolve } from "path";
+import { dirname, join, resolve } from "path";
 import { createRequire } from "module";
 import { formatSuccess, formatWarning, formatError } from "../format";
 import { loadChantConfig } from "../../config";
@@ -28,6 +29,15 @@ export interface UpdateResult {
   error?: string;
 }
 
+/**
+ * Where `chant update` writes a lexicon skill, relative to the project. The
+ * workspace drift check (#2541) compares these files with what the skills
+ * render to, so both read the path from here.
+ */
+export function skillFilePath(skillName: string): string {
+  return `skills/${skillName}/SKILL.md`;
+}
+
 /**
  * Copy directory contents recursively, filtering to .ts and .d.ts files
  */
@@ -105,7 +115,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 +147,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);
 
@@ -166,9 +179,9 @@ export async function updateCommand(options: UpdateOptions): Promise<UpdateResul
         const skills = plugin.skills();
         if (skills.length > 0) {
           for (const skill of skills) {
-            const skillDir = join(projectDir, "skills", skill.name);
-            mkdirSync(skillDir, { recursive: true });
-            writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+            const file = join(projectDir, skillFilePath(skill.name));
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, skill.content);
           }
           synced.push(`${plugin.name} skills (${skills.length})`);
         }

package/src/cli/commands/vendor.ts

@@ -76,7 +76,7 @@ export function contentHash(files: Map<string, Buffer>): string {
 // ── Source resolution → a { relpath → bytes } file set ──────────────────────
 
 /** Walk a local directory into a relpath→bytes map (or a single file). */
-function readLocal(absPath: string): Map<string, Buffer> {
+export function readLocal(absPath: string): Map<string, Buffer> {
   const files = new Map<string, Buffer>();
   const stat = statSync(absPath);
   if (stat.isFile()) {
@@ -135,12 +135,17 @@ export function scopeArchiveFiles(
 }
 
 async function resolveSource(entry: VendorEntry, manifestDir: string): Promise<Map<string, Buffer>> {
-  if (entry.source.type === "local") {
-    const abs = resolve(manifestDir, entry.source.path);
-    if (!existsSync(abs)) throw new Error(`local source not found: ${entry.source.path}`);
+  return resolveVendorSource(entry.source, manifestDir);
+}
+
+/** Resolve a vendor source (a local path, or an archive URL) to its file set. */
+export async function resolveVendorSource(source: VendorEntry["source"], manifestDir: string): Promise<Map<string, Buffer>> {
+  if (source.type === "local") {
+    const abs = resolve(manifestDir, source.path);
+    if (!existsSync(abs)) throw new Error(`local source not found: ${source.path}`);
     return readLocal(abs);
   }
-  return readArchive(entry.source.url, entry.source.subpath);
+  return readArchive(source.url, source.subpath);
 }
 
 // ── File I/O ────────────────────────────────────────────────────────────────
@@ -154,7 +159,7 @@ function writeFiles(targetDir: string, files: Map<string, Buffer>): void {
   }
 }
 
-function readTarget(targetDir: string): Map<string, Buffer> {
+export function readTarget(targetDir: string): Map<string, Buffer> {
   if (!existsSync(targetDir)) return new Map();
   return readLocal(targetDir);
 }

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/__snapshots__/build-member.test.ts.snap

@@ -0,0 +1,38 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`a project outside any workspace (level 0) > the pipeline is the generator's output, unchanged 1`] = `
+"name: chant-components-staging
+
+on:
+  workflow_dispatch: {}
+
+env:
+  CHANT_ENV: staging
+
+jobs:
+  shared-alb:
+    runs-on: ubuntu-latest
+    container: node:22-slim
+    steps:
+      - uses: actions/checkout@v4
+      - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
+      - name: Upload shared-alb outputs
+        uses: actions/upload-artifact@v4
+        with:
+          name: shared-alb-outputs
+          path: shared-alb.outputs.json
+  api:
+    runs-on: ubuntu-latest
+    needs:
+      - shared-alb
+    container: node:22-slim
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download shared-alb outputs
+        uses: actions/download-artifact@v4
+        with:
+          name: shared-alb-outputs
+          path: .
+      - run: chant run --components api --env staging --seed-outputs shared-alb.outputs.json
+"
+`;