@intentius/chant 0.124.31 → 0.124.32

package/src/lexicon-dist.e2e.test.ts

@@ -0,0 +1,254 @@
+/**
+ * #3981 — lexicons loaded from compiled JS, with plain node.
+ *
+ * Lexicon packages publish compiled `dist/*.js` as each export's `default`.
+ * This compiles core and a set of real lexicons (aws and helm, which find
+ * their lint rules by directory scan, and the lexicons they import) with tsc
+ * into a scratch `node_modules`, with each lexicon's own package.json. A
+ * plain node process with no
+ * loader then loads each plugin through the compiled core, and must find the
+ * same lint rules, post-synth checks, skills and generated data as the same
+ * plugins loaded from source, without loading tsx or any TypeScript module.
+ * A `chant build` and `chant lint` of a project against the compiled aws
+ * lexicon must work and load none of the lexicon's TypeScript.
+ *
+ * End to end because it runs tsc and spawns node.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+
+const coreRoot = resolve(import.meta.dirname, "..");
+const repo = resolve(coreRoot, "..", "..");
+const repoModules = join(repo, "node_modules");
+
+/** Compiled and counted. aws and helm discover their lint rules from a directory; the rest are what they import. */
+const LEXICONS = ["aws", "helm", "k8s", "grafana", "otel", "prometheus"];
+
+let scratch: string;
+let modules: string;
+let coreDist: string;
+let project: string;
+
+/**
+ * Loads each named plugin through core and prints what it found. argv[2] is a
+ * JSON object: `core` (the URL of core's ts-loader and cli/plugins modules,
+ * without extension), `ext` (`.js` or `.ts`), `names`, and `taggable` (the
+ * URL of the aws lexicon's taggable module).
+ */
+const COUNT = `
+import { registerHooks } from "node:module";
+const seen = { tsx: 0, typeScript: [] };
+registerHooks({
+  load(url, context, next) {
+    const path = url.replace(/[?#].*$/, "");
+    if (path.includes("/node_modules/tsx/")) seen.tsx++;
+    else if (/\\.[cm]?tsx?$/.test(path)) seen.typeScript.push(path);
+    return next(url, context);
+  },
+});
+const args = JSON.parse(process.argv[2]);
+const { installCompiledCli } = await import(args.core + "/ts-loader" + args.ext);
+installCompiledCli();
+const { loadPlugin } = await import(args.core + "/cli/plugins" + args.ext);
+const plugins = {};
+for (const name of args.names) {
+  const plugin = await loadPlugin(name);
+  const catalogs = {};
+  for (const resource of plugin.mcpResources?.() ?? []) {
+    if (!resource.uri.endsWith(":resource-catalog")) continue;
+    try { catalogs[resource.uri] = JSON.parse(await resource.handler()).length ?? 0; } catch (err) { catalogs[resource.uri] = String(err); }
+  }
+  plugins[name] = {
+    catalogs,
+    lintRules: (plugin.lintRules?.() ?? []).map((r) => r.id).sort(),
+    postSynthChecks: (plugin.postSynthChecks?.() ?? []).map((c) => c.id).sort(),
+    skills: (plugin.skills?.() ?? []).filter((s) => s.content.length > 0).map((s) => s.name).sort(),
+  };
+}
+const { loadTaggableResources } = await import(args.taggable);
+const compiled = globalThis[Symbol.for("chant.compiledCli")];
+process.stdout.write(JSON.stringify({
+  plugins,
+  taggable: loadTaggableResources().size,
+  tsxRegistered: compiled ? compiled.tsx : null,
+  seen,
+}));
+`;
+
+interface Counted {
+  plugins: Record<string, { catalogs: Record<string, number | string>; lintRules: string[]; postSynthChecks: string[]; skills: string[] }>;
+  taggable: number;
+  tsxRegistered: boolean | null;
+  seen: { tsx: number; typeScript: string[] };
+}
+
+function tsc(project: string, outDir: string): void {
+  execFileSync(join(repo, "scripts", "tsc7.sh"), ["-p", project, "--outDir", outDir, "--sourceMap", "false", "--declaration", "false", "--declarationMap", "false"], {
+    cwd: repo,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  execFileSync(process.execPath, [join(repoModules, "tsc-alias", "dist", "bin", "index.js"), "-p", project, "--outDir", outDir], {
+    cwd: repo,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function count(script: string, args: object, nodeArgs: string[] = []): Counted {
+  const r = spawnSync(process.execPath, [...nodeArgs, script, JSON.stringify(args)], { cwd: scratch, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`count script failed (${r.status}):\n${r.stderr}`);
+  return JSON.parse(r.stdout) as Counted;
+}
+
+beforeAll(() => {
+  scratch = mkdtempSync(join(tmpdir(), "chant-lexicon-dist-"));
+  modules = join(scratch, "node_modules");
+  mkdirSync(join(modules, "@intentius"), { recursive: true });
+  for (const name of readdirSync(repoModules)) {
+    if (name === "@intentius" || name === ".bin") continue;
+    symlinkSync(join(repoModules, name), join(modules, name));
+  }
+
+  // Core as an install has it: its source (the package exports name it, and
+  // the compiled CLI redirects each import of it to dist), and dist.
+  const core = join(modules, "@intentius", "chant");
+  mkdirSync(core);
+  cpSync(join(coreRoot, "package.json"), join(core, "package.json"));
+  cpSync(join(coreRoot, "src"), join(core, "src"), { recursive: true, filter: (p) => !/\.test\.ts$/.test(p) });
+  coreDist = join(core, "dist");
+  tsc(join(coreRoot, "tsconfig.build.json"), coreDist);
+  mkdirSync(join(core, "scripts"));
+  cpSync(join(coreRoot, "scripts", "copy-assets.mjs"), join(core, "scripts", "copy-assets.mjs"));
+  execFileSync(process.execPath, [join(core, "scripts", "copy-assets.mjs")], { stdio: "ignore" });
+
+  for (const name of LEXICONS) {
+    const root = join(repo, "lexicons", name);
+    const pkg = join(modules, "@intentius", `chant-lexicon-${name}`);
+    mkdirSync(pkg);
+    cpSync(join(root, "package.json"), join(pkg, "package.json"));
+    // src/ is published beside dist/, and holds what a module reads beside itself.
+    symlinkSync(join(root, "src"), join(pkg, "src"));
+    if (existsSync(join(root, "node_modules"))) symlinkSync(join(root, "node_modules"), join(pkg, "node_modules"));
+    // The bundle's dist/ (meta.json, manifest.json), then the compiled modules.
+    if (existsSync(join(root, "dist"))) cpSync(join(root, "dist"), join(pkg, "dist"), { recursive: true });
+    tsc(join(root, "tsconfig.build.json"), join(pkg, "dist"));
+  }
+
+  writeFileSync(join(scratch, "count.mjs"), COUNT);
+
+  project = join(scratch, "project");
+  mkdirSync(join(project, "src"), { recursive: true });
+  writeFileSync(join(project, "package.json"), JSON.stringify({ name: "lexicon-dist-e2e", private: true, type: "module" }));
+  writeFileSync(join(project, "chant.config.ts"), `export default { lexicons: ["aws"] };\n`);
+  writeFileSync(
+    join(project, "src", "infra.ts"),
+    `import { Queue } from "@intentius/chant-lexicon-aws";\n` +
+      `export const taskQueue = new Queue({ QueueName: "lexicon-dist-e2e", Tags: [{ Key: "suite", Value: "lexicon-dist" }], SqsManagedSseEnabled: true });\n`,
+  );
+}, 600_000);
+
+afterAll(() => {
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("lexicons loaded from compiled JS (#3981)", () => {
+  let fromSource: Counted;
+  let fromDist: Counted;
+
+  beforeAll(() => {
+    const tsxLoader = pathToFileURL(join(repoModules, "tsx", "dist", "loader.mjs")).href;
+    fromSource = count(
+      join(scratch, "count.mjs"),
+      {
+        core: pathToFileURL(join(coreRoot, "src")).href,
+        ext: ".ts",
+        names: LEXICONS,
+        taggable: pathToFileURL(join(repo, "lexicons", "aws", "src", "taggable.ts")).href,
+      },
+      // The repository's lexicons through their `development` export, src/*.ts, as bin/chant runs from source.
+      ["--conditions=development", "--import", tsxLoader],
+    );
+    fromDist = count(join(scratch, "count.mjs"), {
+      core: pathToFileURL(coreDist).href,
+      ext: ".js",
+      names: LEXICONS,
+      taggable: "@intentius/chant-lexicon-aws/taggable",
+    });
+  }, 300_000);
+
+  test("plain node loads every plugin with no tsx and no TypeScript module", () => {
+    expect(fromDist.tsxRegistered).toBe(false);
+    expect(fromDist.seen.tsx).toBe(0);
+    expect(fromDist.seen.typeScript).toEqual([]);
+    // The comparison run really loads the lexicons' source.
+    expect(fromSource.seen.typeScript.some((path) => path.includes("/lexicons/aws/src/"))).toBe(true);
+  });
+
+  test("the compiled plugins find the same lint rules as the source", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.lintRules, name).toEqual(fromSource.plugins[name]!.lintRules);
+    }
+    // The two that scan a directory for their rules found some.
+    expect(fromDist.plugins.aws!.lintRules.length).toBeGreaterThan(0);
+    expect(fromDist.plugins.helm!.lintRules.length).toBeGreaterThan(0);
+  });
+
+  test("the compiled plugins find the same post-synth checks as the source", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.postSynthChecks, name).toEqual(fromSource.plugins[name]!.postSynthChecks);
+    }
+    expect(fromDist.plugins.aws!.postSynthChecks.length).toBeGreaterThan(0);
+  });
+
+  test("the compiled plugins read their skills from src/", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.skills, name).toEqual(fromSource.plugins[name]!.skills);
+    }
+    expect(fromDist.plugins.aws!.skills.length).toBeGreaterThan(0);
+  });
+
+  test("a compiled module reads the generated JSON under src/", () => {
+    expect(fromSource.taggable).toBeGreaterThan(0);
+    expect(fromDist.taggable).toBe(fromSource.taggable);
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.catalogs, name).toEqual(fromSource.plugins[name]!.catalogs);
+      for (const size of Object.values(fromDist.plugins[name]!.catalogs)) expect(typeof size, `${name}: ${size}`).toBe("number");
+    }
+    expect(fromDist.plugins.aws!.catalogs["aws:resource-catalog"]).toBeGreaterThan(0);
+  });
+
+  test("build and lint run against the compiled aws lexicon and load none of its TypeScript", () => {
+    const tracer = join(scratch, "trace.mjs");
+    writeFileSync(
+      tracer,
+      `import { registerHooks } from "node:module";\nimport { appendFileSync } from "node:fs";\n` +
+        `const seen = [];\n` +
+        `registerHooks({ load(url, context, next) { if (/\\/(lexicons|chant-lexicon-[a-z0-9]+)\\/src\\/.*\\.ts$/.test(url)) seen.push(url); return next(url, context); } });\n` +
+        `process.on("exit", () => appendFileSync(process.env.TRACE_OUT, JSON.stringify(seen) + "\\n"));\n`,
+    );
+    const main = join(coreDist, "cli", "main.js");
+    const run = (args: string[]) => {
+      const out = join(scratch, `trace-${args[0]}.jsonl`);
+      const env: NodeJS.ProcessEnv = { ...process.env, TRACE_OUT: out };
+      delete env.CHANT_ENV;
+      const r = spawnSync(process.execPath, ["--import", pathToFileURL(tracer).href, main, ...args], { cwd: project, encoding: "utf-8", env });
+      return { ...r, lexiconTypeScript: JSON.parse(readFileSync(out, "utf-8").trim().split("\n")[0]!) as string[] };
+    };
+
+    const built = run(["build", "src", "-o", "out/template.json"]);
+    expect(built.status, built.stderr).toBe(0);
+    const template = JSON.parse(readFileSync(join(project, "out", "template.json"), "utf-8")) as {
+      Resources: Record<string, { Type: string; Properties: { QueueName?: string } }>;
+    };
+    expect(Object.values(template.Resources).map((r) => [r.Type, r.Properties.QueueName])).toEqual([["AWS::SQS::Queue", "lexicon-dist-e2e"]]);
+    expect(built.lexiconTypeScript).toEqual([]);
+
+    const linted = run(["lint", "src"]);
+    expect(linted.status, linted.stdout + linted.stderr).toBe(0);
+    expect(linted.lexiconTypeScript).toEqual([]);
+  });
+});

package/src/lexicon-module.test.ts

@@ -201,3 +201,50 @@ describe("lexicons declared by module path (#2520)", () => {
     expect(typeof evaluator.evaluateGatePolicy).toBe("function");
   });
 });
+
+describe("tsx only for a lexicon that resolves to TypeScript (#3981)", () => {
+  const STATE = Symbol.for("chant.compiledCli");
+  const global = globalThis as { [STATE]?: { tsx: boolean } };
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "chant-lexicon-js-"));
+    // Stand in for the compiled CLI before it has registered tsx.
+    global[STATE] = { tsx: false };
+  });
+
+  afterEach(async () => {
+    delete global[STATE];
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function jsPackage(root: string, name: string): Promise<void> {
+    const pkg = join(root, "node_modules", "@intentius", `chant-lexicon-${name}`);
+    await mkdir(join(pkg, "dist"), { recursive: true });
+    await writeFile(join(pkg, "package.json"), JSON.stringify({ name: `@intentius/chant-lexicon-${name}`, type: "module", exports: { ".": "./dist/index.js" } }));
+    await writeFile(join(pkg, "dist", "index.js"), `export const marker = ${JSON.stringify(name)};\n`);
+  }
+
+  test("a compiled package the project installs imports with plain node", async () => {
+    await jsPackage(dir, "jsonly");
+    const { importLexiconPackage } = await import("./lexicon-module");
+    const mod = await importLexiconPackage("@intentius/chant-lexicon-jsonly", dir);
+    expect(mod.marker).toBe("jsonly");
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+
+  test("a compiled module named by absolute path imports with plain node", async () => {
+    const path = join(dir, "lexicon.mjs");
+    await writeFile(path, `export const marker = "by-path";\n`);
+    const { importLexiconPackage } = await import("./lexicon-module");
+    const mod = await importLexiconPackage(path, dir);
+    expect(mod.marker).toBe("by-path");
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+
+  test("a package missing from the project too rethrows the first error and registers nothing", async () => {
+    const { importLexiconPackage } = await import("./lexicon-module");
+    await expect(importLexiconPackage("@intentius/chant-lexicon-not-installed-3981", dir)).rejects.toThrow(/chant-lexicon-not-installed-3981/);
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+});

package/src/lexicon-module.ts

@@ -27,8 +27,9 @@
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { ensureTypeScriptLoader } from "./ts-loader";
+import { ensureTypeScriptLoader, ensureTypeScriptLoaderFor, typeScriptLoaderPending } from "./ts-loader";
 import { esModuleNamespace } from "./module-interop";
+import { isJavaScriptModule } from "./module-source";
 
 /**
  * One `lexicons` entry: a package-backed name, or a name plus the module that
@@ -180,6 +181,9 @@ export function resetLexiconModules(): void {
  * `typeScript: false` imports it with plain node, without registering tsx
  * (#3276): tsx's ESM hooks run on a thread of their own, which costs the
  * compiled CLI about 200 MB, so a caller whose module is JavaScript says so.
+ * Left out, the module's extension decides (#3981): a `.js` or `.mjs` module
+ * imports with plain node, and anything else (`.ts`, or no extension, which
+ * only tsx's resolver completes) registers tsx first.
  */
 export async function importLexiconModule(
   name: string,
@@ -188,7 +192,8 @@ export async function importLexiconModule(
   const path = modulePaths.get(name);
   if (path === undefined) return undefined;
   try {
-    if (options.typeScript !== false) ensureTypeScriptLoader();
+    const typeScript = options.typeScript ?? !isJavaScriptModule(path);
+    if (typeScript) ensureTypeScriptLoader();
     return esModuleNamespace((await import(path)) as Record<string, unknown>);
   } catch (err) {
     throw new Error(
@@ -258,6 +263,18 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
   }
 }
 
+/**
+ * #3981 — where `spec` resolves from this module, as `import(spec)` here
+ * would resolve it. Throws as the import would when it cannot be resolved.
+ * An absolute path is its own file URL.
+ */
+function resolveImport(spec: string): string {
+  if (isAbsolute(spec)) return pathToFileURL(spec).href;
+  const resolveMeta = (import.meta as { resolve?: (specifier: string) => string }).resolve;
+  if (typeof resolveMeta === "function") return resolveMeta(spec);
+  return pathToFileURL(createRequire(import.meta.url).resolve(spec)).href;
+}
+
 /**
  * chant#2845 — import a lexicon package, or one of its subpaths, by its bare
  * specifier. chant's own install is tried first, as a bare `import()` always
@@ -266,16 +283,41 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
  * that installs its lexicons in its own node_modules, it is resolved from
  * `fromDir` (the project) and imported from there. Any other failure, and a
  * package the project doesn't have either, rethrows the first error.
+ *
+ * #3981 — tsx is registered only when the module resolves to TypeScript. A
+ * lexicon that ships compiled JS imports with plain node. The module is
+ * resolved before it is imported, because a failed import is cached: one
+ * tried without tsx cannot be tried again with it. A resolution that fails
+ * for any reason but a missing package registers tsx, whose resolver may
+ * still complete it.
  */
 export async function importLexiconPackage(spec: string, fromDir: string = process.cwd()): Promise<Record<string, unknown>> {
+  const pkg = packageNameOf(spec);
+  if (typeScriptLoaderPending()) {
+    let resolved: string | undefined;
+    try {
+      resolved = resolveImport(spec);
+    } catch (err) {
+      if (pkg === undefined || !isPackageNotFound(err, pkg)) {
+        ensureTypeScriptLoader();
+      } else {
+        return importFromProject(spec, fromDir, err);
+      }
+    }
+    if (resolved !== undefined) ensureTypeScriptLoaderFor(resolved);
+  }
   try {
-    ensureTypeScriptLoader();
     return esModuleNamespace((await import(spec)) as Record<string, unknown>);
   } catch (err) {
-    const pkg = packageNameOf(spec);
     if (pkg === undefined || !isPackageNotFound(err, pkg)) throw err;
-    const resolved = resolveFromProject(spec, fromDir);
-    if (resolved === undefined) throw err;
-    return esModuleNamespace((await import(pathToFileURL(resolved).href)) as Record<string, unknown>);
+    return importFromProject(spec, fromDir, err);
   }
 }
+
+/** The project's copy of `spec`, for {@link importLexiconPackage}. Rethrows `err` when the project has none. */
+async function importFromProject(spec: string, fromDir: string, err: unknown): Promise<Record<string, unknown>> {
+  const resolved = resolveFromProject(spec, fromDir);
+  if (resolved === undefined) throw err;
+  ensureTypeScriptLoaderFor(resolved);
+  return esModuleNamespace((await import(pathToFileURL(resolved).href)) as Record<string, unknown>);
+}

package/src/lexicon-plugin-helpers.ts

@@ -7,8 +7,8 @@
  */
 
 import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
+import { moduleSourceDir } from "./module-source";
 import type { SkillDefinition } from "./lexicon";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { Serializer } from "./serializer";
@@ -44,7 +44,8 @@ export function createSkillsLoader(
   specs: SkillFileSpec[],
 ): () => SkillDefinition[] {
   return () => {
-    const skillsDir = join(dirname(fileURLToPath(importMetaUrl)), "skills");
+    // Skills are markdown beside the source; a compiled plugin finds them under src/ (#3981).
+    const skillsDir = join(moduleSourceDir(importMetaUrl), "skills");
     return specs.map(({ file, ...meta }) => {
       try {
         const content = readFileSync(join(skillsDir, file), "utf-8");
@@ -123,7 +124,8 @@ export function createCatalogResource(
     description,
     mimeType: "application/json",
     async handler(): Promise<string> {
-      const dir = dirname(fileURLToPath(importMetaUrl));
+      // Generated JSON sits beside the source; a compiled plugin finds it under src/ (#3981).
+      const dir = moduleSourceDir(importMetaUrl);
       const lexicon = JSON.parse(
         readFileSync(join(dir, "generated", lexiconJsonFile), "utf-8"),
       ) as Record<string, { resourceType: string; kind: string }>;

package/src/lexicon.ts

@@ -554,6 +554,8 @@ export interface ComponentPipelineOptions {
    * `wave-<k>` runs `chant components fan-out --wave-gate <gate> --wave <k>`
    * and hands the attempt record to the next job. See
    * `components/gated-wave-pipeline.ts`. Unset, the pipeline is unchanged.
+   * Beside `prLoop` (#4003) it gives the pull request's apply a gate per
+   * wave instead: one apply job per wave (`prLoopWithWaves`).
    */
   gatedWaves?: GatedWavePipelineOptions;
   /**

package/src/lifecycle/affected.test.ts

@@ -14,6 +14,7 @@ import {
 import type { StackGraph } from "../build";
 import type { Serializer } from "../serializer";
 import type { Declarable } from "../declarable";
+import { EMPTY_TREE_SHA } from "../components/changed-files";
 
 const execFileAsync = promisify(execFile);
 
@@ -136,6 +137,12 @@ describe("affectedStacks — baseDir (caller-supplied)", () => {
     const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer] });
     expect(r.changed).toEqual([]);
   });
+
+  test("the empty tree as the base (a root commit, #4004) builds nothing: every head stack is changed", async () => {
+    const head = srcDir("head", widget("Widget"));
+    const r = await affectedStacks({ projectPath: head, baseRef: EMPTY_TREE_SHA, serializers: [fakeSerializer] });
+    expect(r.changed).toEqual(["fake"]);
+  });
 });
 
 // A second lexicon, so a stack that serializes through two of them can be shown

package/src/lifecycle/affected.ts

@@ -37,6 +37,7 @@ import { tmpdir } from "node:os";
 import { build, type StackGraph } from "../build";
 import { getPrimaryOutput } from "../lint/post-synth";
 import type { Serializer } from "../serializer";
+import { EMPTY_TREE_SHA } from "../components/changed-files";
 import type { Declarable } from "../declarable";
 
 const execFileAsync = promisify(execFile);
@@ -258,7 +259,9 @@ export interface AffectedStacksOptions {
  */
 export async function affectedStacks(opts: AffectedStacksOptions): Promise<AffectedResult> {
   const projectPath = resolve(opts.projectPath);
-  const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir);
+  // The empty tree (#4004) builds nothing, so it needs no worktree.
+  const emptyBase = !opts.baseDir && opts.baseRef === EMPTY_TREE_SHA;
+  const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir && !emptyBase);
   const repoRoot = needsWorktree ? await gitTopLevel(projectPath) : projectPath;
   // Canonicalize via realpath so the worktree-relative path is correct even when
   // the temp dir is a symlink (macOS /var → /private/var) and `git
@@ -293,6 +296,8 @@ export async function affectedStacks(opts: AffectedStacksOptions): Promise<Affec
   let baseMap: Map<string, string>;
   if (opts.baseDir) {
     baseMap = (await readArtifacts(resolve(opts.baseDir), false)).artifacts;
+  } else if (emptyBase) {
+    baseMap = new Map();
   } else if (opts.baseRef) {
     baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => (await readArtifacts(join(dir, relProject), false)).artifacts);
   } else {

package/src/lifecycle/release-ledger.ts

@@ -58,11 +58,23 @@ export interface RunOrigin {
   repo?: string;
   /** Resolved link to the run, when the environment provided enough to build one. */
   url?: string;
+  /**
+   * The forge's id for the job within the run (#4156): `GITHUB_JOB` on GitHub
+   * and Forgejo, the job's key in the workflow, and `CI_JOB_ID` on GitLab.
+   * Only `chant ci run` in a forge job writes it ({@link resolveCiJob}),
+   * from {@link RUN_ORIGIN_JOB_FLOOR}.
+   */
+  jobId?: string;
+  /** The run's attempt, `GITHUB_RUN_ATTEMPT` on GitHub and Forgejo (#4156). GitLab gives a retried job a new `jobId` instead. */
+  attempt?: number;
 }
 
 /** The first chant that writes `runOrigin.forge: "chant"`, for a job `chant ci run` ran (#4094). */
 export const RUN_ORIGIN_CHANT_FLOOR = "0.124.30";
 
+/** The first chant that writes `runOrigin.jobId` and `runOrigin.attempt`, for a forge job that ran `chant ci run` (#4156). */
+export const RUN_ORIGIN_JOB_FLOOR = "0.124.32";
+
 /**
  * The gate resolution that admitted a deploy (#4020): the gate's address in the
  * gate ledger (`_gates/<op>.jsonl`, `op` and `gate`) and when the resolution
@@ -310,6 +322,28 @@ export function resolveCiRun(env: NodeJS.ProcessEnv = process.env): { runId: str
   return undefined;
 }
 
+/**
+ * The CI run the environment names, as {@link resolveCiRun} has it, with the
+ * job within the run and the run's attempt when the forge gives them
+ * (#4156). `chant ci run` in a forge job records this as its run's origin;
+ * a release record keeps {@link resolveCiRun}'s shape.
+ */
+export function resolveCiJob(env: NodeJS.ProcessEnv = process.env): { runId: string; runOrigin: RunOrigin } | undefined {
+  const ci = resolveCiRun(env);
+  if (!ci) return undefined;
+  const github = ci.runOrigin.forge === "github";
+  const jobId = github ? env.GITHUB_JOB : env.CI_JOB_ID;
+  const attempt = github ? Number(env.GITHUB_RUN_ATTEMPT) : NaN;
+  return {
+    runId: ci.runId,
+    runOrigin: {
+      ...ci.runOrigin,
+      ...(jobId ? { jobId } : {}),
+      ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+    },
+  };
+}
+
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

package/src/lifecycle/work-dir.test.ts

@@ -0,0 +1,77 @@
+/**
+ * #2893: work worktrees live at `.chant/work/[<member>/]<item>` in the
+ * checkout, excluded through `<git-common-dir>/info/exclude`, and the
+ * hand-written walkers skip them.
+ */
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { excludeWorkDir, isWorkDir, removeEmptyWorkDirs, workWorktreePath, legacyWorkWorktreePath, WORK_DIR_EXCLUDE } from "./work-dir";
+import { listFiles } from "../workspace/export";
+
+describe("the work directory", () => {
+  test("a worktree is .chant/work/[<member>/]<item> in the checkout; older versions made it under the git directory", () => {
+    expect(workWorktreePath("/repo", [], "W-1")).toBe(join("/repo", ".chant", "work", "W-1"));
+    expect(workWorktreePath("/repo", ["app"], "W-1")).toBe(join("/repo", ".chant", "work", "app", "W-1"));
+    expect(legacyWorkWorktreePath("/repo/.git", ["app"], "W-1")).toBe(join("/repo/.git", "chant-work", "app", "W-1"));
+  });
+
+  test("isWorkDir is .chant/work at the walk's root or below it, and nothing else in .chant", () => {
+    expect(isWorkDir(".chant/work")).toBe(true);
+    expect(isWorkDir("members/app/.chant/work")).toBe(true);
+    expect(isWorkDir(".chant")).toBe(false);
+    expect(isWorkDir(".chant/factory")).toBe(false);
+    expect(isWorkDir("x.chant/work")).toBe(false);
+  });
+
+  test("the exclude line is written once, after any last line without a newline, and not when git already ignores the directory", async () => {
+    await withTestDir(async (dir) => {
+      const common = join(dir, "git");
+      expect(excludeWorkDir(common, false)).toBe(true);
+      expect(readFileSync(join(common, "info", "exclude"), "utf-8")).toBe(`${WORK_DIR_EXCLUDE}\n`);
+      expect(excludeWorkDir(common, false)).toBe(false);
+      expect(readFileSync(join(common, "info", "exclude"), "utf-8")).toBe(`${WORK_DIR_EXCLUDE}\n`);
+
+      const other = join(dir, "other");
+      mkdirSync(join(other, "info"), { recursive: true });
+      writeFileSync(join(other, "info", "exclude"), "*.log");
+      expect(excludeWorkDir(other, false)).toBe(true);
+      expect(readFileSync(join(other, "info", "exclude"), "utf-8")).toBe(`*.log\n${WORK_DIR_EXCLUDE}\n`);
+
+      const ignored = join(dir, "ignored");
+      expect(excludeWorkDir(ignored, true)).toBe(false);
+      expect(existsSync(join(ignored, "info", "exclude"))).toBe(false);
+    });
+  });
+
+  test("removing a worktree takes the empty directories above it up to .chant, and stops at one that holds anything", async () => {
+    await withTestDir(async (dir) => {
+      // The worktree itself is gone already: removed, its parent left empty.
+      const tree = workWorktreePath(dir, ["app"], "W-1");
+      mkdirSync(dirname(tree), { recursive: true });
+      mkdirSync(workWorktreePath(dir, [], "W-2"), { recursive: true });
+      removeEmptyWorkDirs(tree);
+      expect(existsSync(dirname(tree))).toBe(false);
+      expect(existsSync(join(dir, ".chant", "work", "W-2"))).toBe(true);
+
+      const only = join(dir, "only");
+      mkdirSync(join(only, ".chant", "work"), { recursive: true });
+      removeEmptyWorkDirs(workWorktreePath(only, [], "W-3"));
+      expect(existsSync(join(only, ".chant"))).toBe(false);
+      expect(existsSync(only)).toBe(true);
+    });
+  });
+});
+
+describe("walkers skip .chant/work", () => {
+  test("export's file list outside git leaves out a work worktree and keeps the rest of .chant", async () => {
+    await withTestDir(async (dir) => {
+      for (const p of ["a.ts", ".chant/workspace.lock.json", ".chant/work/W-1/a.ts", "m/.chant/work/W-2/a.ts"]) {
+        mkdirSync(dirname(join(dir, p)), { recursive: true });
+        writeFileSync(join(dir, p), "x");
+      }
+      expect(listFiles(dir)).toEqual([".chant/workspace.lock.json", "a.ts"]);
+    });
+  });
+});