@intentius/chant 0.124.31 → 0.124.32

package/src/cli/commands/init-lexicon.test.ts

@@ -274,13 +274,16 @@ describe("scaffold content validation", () => {
   });
 
   // #2090, the scaffolded package.json failed tier 1 as generated: a bare
-  // string exports["."], a build script that never deletes emitted .js, and
-  // a prepack that never bundled, so dist/manifest.json never existed.
-  test("package.json exports[\".\"].default is ./src/index.ts, build deletes emitted JS, prepack bundles (#2090)", () => {
+  // string exports["."] and a prepack that never bundled, so
+  // dist/manifest.json never existed. #3981 — the package ships compiled JS.
+  test("package.json exports[\".\"] is development src, default dist JS, build keeps JS, prepack bundles (#2090, #3981)", () => {
     const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
-    expect(pkg.exports["."].default).toBe("./src/index.ts");
-    expect(pkg.scripts.build).toContain("-delete");
+    expect(pkg.exports["."].development).toBe("./src/index.ts");
+    expect(pkg.exports["."].default).toBe("./dist/index.js");
+    expect(pkg.exports["./*"].default).toBe("./dist/*.js");
+    expect(pkg.scripts.build).not.toContain("-delete");
     expect(pkg.scripts.prepack).toContain("bundle");
+    expect(pkg.scripts.prepack).toContain("npm run build");
   });
 
   test("tsconfig.build.json uses bundler resolution + the development condition (#749)", () => {

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

@@ -305,6 +305,51 @@ describe("onboardCommand", () => {
   });
 });
 
+describe("chant.yml validate step for a lexicon it already has (#2877)", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = makeTempDir();
+    writeFixtureRepo(root);
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const withGithubStep = (run: string) =>
+    ciContent.replace(
+      "      - name: Generate and validate K8s lexicon",
+      `      - name: Generate and validate GitHub lexicon\n        ${run}\n\n      - name: Generate and validate K8s lexicon`,
+    );
+
+  const githubSteps = (ci: string) => ci.match(/Generate and validate github lexicon/gi)?.length;
+
+  test("a named step's bare run: line counts as the lexicon's prepack line", () => {
+    const before = withGithubStep("run: npm run --prefix lexicons/github prepack");
+    expect(before).not.toBe(ciContent);
+    writeFileSync(join(root, ".github/workflows/chant.yml"), before);
+
+    const result = onboardCommand({ name: "github", root });
+    expect(result.patched).not.toContain("chant.yml (prepack + validate)");
+    expect(result.skipped).toContain("chant.yml: github already in chant.yml");
+    expect(readFileSync(join(root, ".github/workflows/chant.yml"), "utf-8")).toBe(before);
+  });
+
+  test("the step-name check ignores case (Github vs GitHub)", () => {
+    // A step whose run line is not a plain prepack call, so only the name can
+    // tell onboard the validate step already exists.
+    writeFileSync(
+      join(root, ".github/workflows/chant.yml"),
+      withGithubStep("run: npm run --prefix lexicons/github prepack -- --strict"),
+    );
+
+    onboardCommand({ name: "github", root });
+    const ci = readFileSync(join(root, ".github/workflows/chant.yml"), "utf-8");
+    expect(githubSteps(ci)).toBe(1);
+  });
+});
+
 describe("root tsconfig.json paths (#1614)", () => {
   let root: string;
 

package/src/cli/commands/onboard.ts

@@ -32,13 +32,14 @@ function findRepoRoot(): string {
 }
 
 /**
- * A real prepack invocation line: a Dockerfile `RUN`, a workflow `- run:`,
- * or a bare line inside a `run: |` block. Comments, `echo` messages and
+ * A real prepack invocation line: a Dockerfile `RUN`, a workflow `- run:` or
+ * `run:` step key (a named step puts `run:` on its own line, #2877), or a bare
+ * line inside a `run: |` block. Comments, `echo` messages and
  * `$lex` / `<lex>` placeholders do not match. Matching those placeholder
  * substrings was how onboard appended duplicates to Dockerfile.smoke on
  * every run (#1678).
  */
-const PREPACK_LINE = /^\s*(?:RUN\s+|-\s*run:\s*)?npm run --prefix lexicons\/[a-z0-9-]+ prepack\s*$/i;
+const PREPACK_LINE = /^\s*(?:RUN\s+|(?:-\s*)?run:\s*)?npm run --prefix lexicons\/[a-z0-9-]+ prepack\s*$/i;
 
 function isPrepackLine(line: string): boolean {
   return PREPACK_LINE.test(line);
@@ -256,7 +257,10 @@ function patchCiWorkflow(root: string, name: string): PatchResult {
   const displayName = name.charAt(0).toUpperCase() + name.slice(1);
   const validateStepName = `Generate and validate ${displayName} lexicon`;
 
-  if (!lines.some((l) => l.includes(validateStepName))) {
+  // Case-insensitive: the name is built from the directory ("Github"), and an
+  // existing step may spell the product its own way ("GitHub", #2877).
+  const stepNameLower = validateStepName.toLowerCase();
+  if (!lines.some((l) => l.toLowerCase().includes(stepNameLower))) {
     let lastValidateRunIdx = -1;
     for (let i = 0; i < lines.length; i++) {
       if (lines[i].includes("Generate and validate")) {

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

@@ -25,6 +25,12 @@ describe("updateCommand", () => {
       const result = await updateCommand({ path: testDir });
       expect(result.success).toBe(true);
       expect(result.warnings.some((w) => w.includes("not found"))).toBe(true);
+      // chant #3988 — the warning names the install command for the package.
+      expect(
+        result.warnings.some((w) =>
+          w.includes('npm install --save-dev @intentius/chant-lexicon-nonexistent'),
+        ),
+      ).toBe(true);
     });
   });
 

package/src/cli/commands/update.ts

@@ -154,7 +154,10 @@ export async function updateCommand(options: UpdateOptions): Promise<UpdateResul
     const pkgPath = resolvePackagePath(pkgName, projectDir);
 
     if (!pkgPath) {
-      warnings.push(`${pkgName} not found in node_modules. Run "npm install" first.`);
+      // chant #3988 — update copies from node_modules and never installs.
+      warnings.push(
+        `${pkgName} not found in node_modules. chant update does not install lexicons: run "npm install --save-dev ${pkgName}" first.`,
+      );
       continue;
     }
 

package/src/cli/compiled-cli.e2e.test.ts

@@ -7,14 +7,19 @@
  * Each run is traced through a load hook that NODE_OPTIONS hands to the CLI's
  * node, so the test can say what loaded: none of chant's TypeScript source,
  * ever, and tsx only for a command that imports TypeScript (here the
- * lexicon and the project source). tsx's ESM hooks run on a thread of their
- * own, about 200 MB of the process (#3276), so a workspace read must not
- * register it either.
+ * project source). tsx's ESM hooks run on a thread of their own, about 200 MB
+ * of the process (#3276), so a workspace read must not register it either.
+ *
+ * The lexicon ships compiled JS (#3981): its exports' `default` is
+ * `dist/*.js`. No command loads a module of the lexicon's TypeScript, and
+ * `serve mcp` on a project whose config is JSON loads no tsx at all, with the
+ * same lint rules and post-synth checks as the lexicon loaded from source.
  *
  * End to end because it packs, installs from the registry and spawns the CLI.
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
+import { loadPlugin } from "./plugins";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -33,14 +38,20 @@ let waves: string;
 let workspace: string;
 let chant: string;
 let tracer: string;
+let mcpProject: string;
 
 const TRACER = `
 import { registerHooks } from "node:module";
 import { appendFileSync } from "node:fs";
 const out = process.env.CHANT_TRACE_OUT;
-const seen = { chantSrc: 0, chantDist: 0, tsx: 0, typescript: 0, dist: [] };
+const seen = { chantSrc: 0, chantDist: 0, tsx: 0, typescript: 0, dist: [], lexiconTs: 0, lexiconJs: 0 };
 registerHooks({
   load(url, context, next) {
+    if (url.includes("/@intentius/chant-lexicon-")) {
+      const path = url.replace(/[?#].*$/, "");
+      if (/\\.[cm]?tsx?$/.test(path) && !/\\.d\\.[cm]?ts$/.test(path)) seen.lexiconTs++;
+      else if (path.includes("/dist/") && path.endsWith(".js")) seen.lexiconJs++;
+    }
     if (url.includes("/@intentius/chant/src/")) seen.chantSrc++;
     else if (url.includes("/@intentius/chant/dist/")) { seen.chantDist++; seen.dist.push(url.slice(url.indexOf("/@intentius/chant/dist/") + 23)); }
     else if (url.includes("/node_modules/tsx/")) seen.tsx++;
@@ -61,15 +72,15 @@ interface Run {
   status: number | null;
   stdout: string;
   stderr: string;
-  /** Counts of what loaded, plus each compiled module's path under `dist/`. */
-  loaded: { chantSrc: number; chantDist: number; tsx: number; typescript: number; dist: string[] };
+  /** Counts of what loaded, plus each compiled module's path under `dist/`. `lexiconTs` and `lexiconJs` count the lexicon's TypeScript and compiled modules. */
+  loaded: { chantSrc: number; chantDist: number; tsx: number; typescript: number; dist: string[]; lexiconTs: number; lexiconJs: number };
 }
 
-function run(cwd: string, args: string[], extraEnv: NodeJS.ProcessEnv = {}, command = chant): Run {
+function run(cwd: string, args: string[], extraEnv: NodeJS.ProcessEnv = {}, command = chant, input?: string): Run {
   const traceOut = join(scratch, `trace-${Math.random().toString(36).slice(2)}.jsonl`);
   const env: NodeJS.ProcessEnv = { ...process.env, ...extraEnv, NODE_OPTIONS: `--import ${tracer}`, CHANT_TRACE_OUT: traceOut };
   delete env.CHANT_ENV;
-  const result = spawnSync(command, args, { cwd, env, encoding: "utf-8" });
+  const result = spawnSync(command, args, { cwd, env, encoding: "utf-8", input, timeout: 120_000 });
   const lines = readFileSync(traceOut, "utf-8").trim().split("\n");
   return { status: result.status, stdout: result.stdout, stderr: result.stderr, loaded: JSON.parse(lines[0]!) as Run["loaded"] };
 }
@@ -80,7 +91,9 @@ beforeAll(() => {
   writeFileSync(tracer, TRACER);
   const core = pack(coreRoot);
   // The lexicon's prepack regenerates it from upstream specs; the checkout's
-  // generated source and dist are what this test needs, so pack them as they are.
+  // generated source and bundle are what this test needs, so pack them as they
+  // are, after the prepack's last step, the build that writes dist/*.js.
+  execFileSync("npm", ["run", "build"], { cwd: renderRoot, stdio: ["ignore", "pipe", "pipe"] });
   const render = pack(renderRoot, true);
 
   project = join(scratch, "project");
@@ -95,6 +108,13 @@ beforeAll(() => {
   );
   chant = join(project, "node_modules", ".bin", "chant");
 
+  // The same lexicon, from a config that is JSON, with no source: nothing for tsx to load.
+  mcpProject = join(scratch, "mcp-project");
+  mkdirSync(mcpProject);
+  writeFileSync(join(mcpProject, "package.json"), JSON.stringify({ name: "compiled-cli-mcp-e2e", private: true, type: "module" }));
+  writeFileSync(join(mcpProject, "chant.config.json"), JSON.stringify({ lexicons: ["render"] }));
+  symlinkSync(join(project, "node_modules"), join(mcpProject, "node_modules"), "dir");
+
   // The same project with no package.json at all, so nothing above the config
   // says "type": "module" and tsx compiles chant.config.ts as CommonJS (#3897).
   cjsProject = join(scratch, "cjs-project");
@@ -217,19 +237,64 @@ describe("the installed chant CLI (#3878)", () => {
     expect(heavy).toEqual([]);
   });
 
-  test("build loads the TypeScript lexicon and project through tsx, against the one compiled core", () => {
+  test("build loads the project through tsx and the lexicon as compiled JS, against the one compiled core", () => {
     const r = run(project, ["build", "src", "-o", "out/render.json"]);
     expect(r.status, r.stderr).toBe(0);
     const built = JSON.parse(readFileSync(join(project, "out", "render.json"), "utf-8")) as Record<string, { body?: { name?: string } }>;
     expect(built.db?.body?.name).toBe("e2e-db");
     expect(r.loaded.tsx).toBeGreaterThan(0);
     expect(r.loaded.chantSrc).toBe(0);
+    expect(r.loaded.lexiconJs).toBeGreaterThan(0);
+    expect(r.loaded.lexiconTs).toBe(0);
   });
 
-  test("lint passes on the project", () => {
+  test("lint passes on the project and loads none of the lexicon's TypeScript", () => {
     const r = run(project, ["lint", "src"]);
     expect(r.status, r.stdout + r.stderr).toBe(0);
     expect(r.loaded.chantSrc).toBe(0);
+    expect(r.loaded.lexiconTs).toBe(0);
+  });
+
+  test("serve mcp loads the packed lexicon's plugin with no tsx (#3981)", () => {
+    const input =
+      [
+        { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", clientInfo: { name: "e2e" } } },
+        { jsonrpc: "2.0", method: "notifications/initialized" },
+        { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
+        { jsonrpc: "2.0", id: 3, method: "resources/list", params: {} },
+      ]
+        .map((m) => JSON.stringify(m))
+        .join("\n") + "\n";
+    const r = run(mcpProject, ["serve", "mcp"], {}, chant, input);
+    expect(r.status, r.stderr).toBe(0);
+    const responses = r.stdout.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line) as { id?: number; result?: Record<string, unknown> });
+    const result = (id: number) => responses.find((m) => m.id === id)?.result;
+    expect((result(1)?.serverInfo as { name?: string } | undefined)?.name).toBe("chant");
+    const tools = ((result(2)?.tools ?? []) as Array<{ name: string }>).map((t) => t.name);
+    for (const name of ["build", "lint", "explain"]) expect(tools).toContain(name);
+    expect(r.loaded.lexiconJs).toBeGreaterThan(0);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0, lexiconTs: 0 });
+  });
+
+  test("the packed lexicon's plugin has the lint rules and post-synth checks of its source (#3981)", async () => {
+    // The plugin as the installed CLI loads it: compiled core, plain node, the lexicon's dist/*.js.
+    const script =
+      `const core = ${JSON.stringify(pathToFileURL(join(project, "node_modules", "@intentius", "chant", "dist")).href)};\n` +
+      `const { installCompiledCli } = await import(core + "/ts-loader.js");\n` +
+      `installCompiledCli();\n` +
+      `const { loadPlugin } = await import(core + "/cli/plugins.js");\n` +
+      `const plugin = await loadPlugin("render");\n` +
+      `process.stdout.write(JSON.stringify({ lintRules: plugin.lintRules().map((r) => r.id).sort(), postSynthChecks: (plugin.postSynthChecks?.() ?? []).map((c) => c.id).sort() }));\n`;
+    const r = run(mcpProject, ["--input-type=module", "-e", script], {}, process.execPath);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0, lexiconTs: 0 });
+    const packed = JSON.parse(r.stdout) as { lintRules: string[]; postSynthChecks: string[] };
+
+    // The same plugin from the repository's source, in this (vitest) process.
+    const source = await loadPlugin("render");
+    expect(packed.lintRules).toEqual((source.lintRules?.() ?? []).map((rule) => rule.id).sort());
+    expect(packed.postSynthChecks).toEqual((source.postSynthChecks?.() ?? []).map((check) => check.id).sort());
+    expect(packed.lintRules.length).toBeGreaterThan(0);
   });
 
   test("build --sandbox bundles chant's source for the sandboxed child", () => {

package/src/cli/dependencies.e2e.test.ts

@@ -0,0 +1,101 @@
+/**
+ * chant #4116, end to end through the real CLI: a project whose dependencies
+ * are not installed is told so, and a project without node_modules that builds
+ * today still builds.
+ *
+ * Both fixtures are temporary git repositories with no package.json install,
+ * run with this checkout's chant from source the way
+ * ../workspace/member-commands.e2e.test.ts runs it:
+ *
+ * - `bare` is a clone of a project like examples/fan-out-estate: its source
+ *   imports `@intentius/chant-lexicon-k8s` and nothing installs it;
+ * - `linked` is member-commands' setup: a node_modules holding only the
+ *   lexicon, linked to this checkout, and no `@intentius/chant`. chant loads
+ *   the lexicon, and the lexicon resolves `@intentius/chant` from its own
+ *   location, so it builds. The first attempt at #4116 (#4118) refused it.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+
+const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", ".."));
+const LOADER = join(REPO, "node_modules", "tsx", "dist", "loader.mjs");
+const MAIN = join(REPO, "packages", "core", "src", "cli", "main.ts");
+const TIMEOUT = 240_000;
+
+let root: string;
+
+function chant(args: string[], cwd: string): { status: number | null; stdout: string; stderr: string } {
+  const r = spawnSync(process.execPath, ["--import", `file://${LOADER}`, MAIN, ...args], {
+    cwd,
+    encoding: "utf-8",
+    timeout: TIMEOUT,
+    env: { ...process.env, TSX_DISABLE_CACHE: "1", NO_COLOR: "1" },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function project(name: string): string {
+  const dir = join(root, name);
+  const write = (path: string, text: string) => {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  };
+  write("chant.config.ts", 'export default { lexicons: ["k8s"] };\n');
+  write(
+    "src/infra.ts",
+    'import { Namespace } from "@intentius/chant-lexicon-k8s";\nexport const appNs = new Namespace({ metadata: { name: "app" } });\n',
+  );
+  write(".gitignore", "node_modules\nout\n");
+  const git = (...args: string[]) =>
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: dir, stdio: "ignore" });
+  git("init", "-q");
+  git("add", "-A");
+  git("commit", "-qm", "fixture");
+  return dir;
+}
+
+let bare: string;
+let linked: string;
+
+beforeAll(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-4116-e2e-")));
+  bare = project("bare");
+  linked = project("linked");
+  mkdirSync(join(linked, "node_modules", "@intentius"), { recursive: true });
+  symlinkSync(join(REPO, "lexicons", "k8s"), join(linked, "node_modules", "@intentius", "chant-lexicon-k8s"), "dir");
+}, TIMEOUT);
+
+afterAll(() => {
+  if (root) rmSync(root, { recursive: true, force: true });
+});
+
+describe("dependencies not installed (#4116)", () => {
+  test("graph says the dependencies are not installed, not that the source has lint errors", () => {
+    const r = chant(["graph", "--format", "ir"], bare);
+    expect(r.status, r.stderr).toBe(1);
+    expect(r.stderr).toContain(`dependencies not installed: @intentius/chant-lexicon-k8s does not resolve from ${bare}`);
+    expect(r.stderr).toContain("run npm install (or the project's package manager)");
+    expect(r.stderr).not.toMatch(/lint errors/i);
+    expect(r.stdout).toBe("");
+  }, TIMEOUT);
+
+  test("build and lint lead with the dependencies message and exit 1", () => {
+    for (const verb of ["build", "lint"]) {
+      const r = chant([verb], bare);
+      expect(r.status, `${verb}: ${r.stderr}`).toBe(1);
+      expect(r.stderr, verb).toContain("dependencies not installed: @intentius/chant-lexicon-k8s does not resolve from");
+    }
+  }, TIMEOUT);
+
+  test("a project without @intentius/chant in node_modules that builds today still builds", () => {
+    for (const args of [["build"], ["lint"], ["graph", "--format", "ir"]]) {
+      const r = chant(args, linked);
+      expect(r.status, `${args.join(" ")}: ${r.stderr}`).toBe(0);
+      expect(r.stderr, args.join(" ")).not.toContain("dependencies not installed");
+    }
+  }, TIMEOUT);
+});

package/src/cli/dependencies.test.ts

@@ -0,0 +1,93 @@
+/**
+ * chant #4116: which failure messages are imports of packages the project has
+ * not installed. The command paths that print the message have their own tests
+ * (handlers/graph.test.ts, handlers/lint.test.ts, dependencies.e2e.test.ts).
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { reportUninstalledDependencies, uninstalledDependencyIn } from "./dependencies";
+
+let root: string;
+let project: string;
+
+const notFound = (pkg: string, file = "src/a.ts") => `Cannot find package '${pkg}' imported from ${join(project, file)}`;
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-4116-")));
+  project = join(root, "proj");
+  mkdirSync(join(project, "src"), { recursive: true });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("uninstalledDependencyIn", () => {
+  test("an @intentius package no node_modules holds, as lint and build report it", () => {
+    expect(uninstalledDependencyIn(notFound("@intentius/chant-lexicon-aws"), project)).toEqual({
+      package: "@intentius/chant-lexicon-aws",
+      dir: project,
+    });
+    expect(uninstalledDependencyIn(`Component discovery error: ${notFound("@intentius/chant", "a.component.ts")}`, project)).toEqual({
+      package: "@intentius/chant",
+      dir: project,
+    });
+  });
+
+  test("a subpath import names its package", () => {
+    expect(uninstalledDependencyIn("Cannot find module '@intentius/chant/params' imported from /x/a.ts", project)?.package).toBe("@intentius/chant");
+  });
+
+  test("a package found in a parent node_modules is installed", () => {
+    mkdirSync(join(root, "node_modules", "@intentius", "chant-lexicon-aws"), { recursive: true });
+    expect(uninstalledDependencyIn(notFound("@intentius/chant-lexicon-aws"), project)).toBeUndefined();
+  });
+
+  test("a package found from the importing file's directory is installed", () => {
+    const lexicon = join(root, "elsewhere", "lexicon");
+    mkdirSync(join(root, "elsewhere", "node_modules", "@intentius", "chant"), { recursive: true });
+    mkdirSync(lexicon, { recursive: true });
+    expect(uninstalledDependencyIn(`Cannot find package '@intentius/chant' imported from ${join(lexicon, "index.ts")}`, project)).toBeUndefined();
+  });
+
+  test("another package counts only when the project's package.json declares it", () => {
+    expect(uninstalledDependencyIn(notFound("lodahs"), project)).toBeUndefined();
+    writeFileSync(join(project, "package.json"), JSON.stringify({ dependencies: { yaml: "*" } }));
+    expect(uninstalledDependencyIn(notFound("yaml"), project)).toEqual({ package: "yaml", dir: project });
+    expect(uninstalledDependencyIn(notFound("lodahs"), project)).toBeUndefined();
+  });
+
+  test("relative imports and other messages are not dependencies", () => {
+    expect(uninstalledDependencyIn("Cannot find module './missing' imported from /x/a.ts", project)).toBeUndefined();
+    expect(uninstalledDependencyIn("Exported declarable 'x' is never referenced", project)).toBeUndefined();
+  });
+});
+
+describe("reportUninstalledDependencies", () => {
+  let stderr: string[];
+  beforeEach(() => {
+    stderr = [];
+    vi.spyOn(console, "error").mockImplementation((s: string) => void stderr.push(s));
+  });
+
+  test("names the first uninstalled package with the install hint; all when every message is one", () => {
+    expect(reportUninstalledDependencies([notFound("@intentius/chant-lexicon-aws"), notFound("@intentius/chant")], project)).toBe("all");
+    expect(stderr).toHaveLength(1);
+    expect(stderr[0]).toContain(`dependencies not installed: @intentius/chant-lexicon-aws does not resolve from ${project}`);
+    expect(stderr[0]).toContain("run npm install (or the project's package manager)");
+  });
+
+  test("some when other errors are beside them", () => {
+    expect(reportUninstalledDependencies([notFound("@intentius/chant"), "a real problem"], project)).toBe("some");
+    expect(stderr).toHaveLength(1);
+  });
+
+  test("prints nothing when no message is one", () => {
+    expect(reportUninstalledDependencies(["a real problem"], project)).toBeUndefined();
+    expect(reportUninstalledDependencies([], project)).toBeUndefined();
+    expect(stderr).toEqual([]);
+  });
+});

package/src/cli/dependencies.ts

@@ -0,0 +1,122 @@
+/**
+ * chant #4116: a failure caused by a project whose dependencies are not installed.
+ *
+ * In a clone with no node_modules, every project file that imports
+ * `@intentius/chant` or a lexicon package fails to load. Lint reports each one
+ * (LEX002, COMP000), the graph's lint gate then says the source has lint
+ * errors, and build prints node's own "Cannot find package" per file. The
+ * source is fine; the install is missing.
+ *
+ * This runs only after something has already failed, on that failure's
+ * messages. A project chant builds today never reaches it, whatever its
+ * node_modules looks like: chant resolves a lexicon from its own install first,
+ * and a project that imports only what it has installed loads fine. That is why
+ * the check is not made up front (#4118, reverted in #4125).
+ *
+ * A message counts when it is node's "Cannot find package|module '<spec>'",
+ * `<spec>` names a package that is `@intentius/*` or declared in the project's
+ * package.json, and no node_modules from the project directory up holds it. A
+ * typo in an import of an undeclared package keeps its message as it is.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageNameOf } from "../lexicon-module";
+import { formatError } from "./format";
+
+/** A package that a failure could not import and that is not installed for the project. */
+export interface UninstalledDependency {
+  package: string;
+  /** The project directory it does not resolve from. */
+  dir: string;
+}
+
+const NOT_FOUND = /Cannot find (?:package|module) '([^']+)'(?: imported from (\S+))?/g;
+
+/** True when a node_modules at `dir` or above holds `pkg`. */
+function installedFrom(pkg: string, dir: string): boolean {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    if (existsSync(join(d, "node_modules", ...pkg.split("/")))) return true;
+    if (dirname(d) === d) return false;
+  }
+}
+
+/** The packages the nearest package.json at `dir` or above declares, in any dependency field. */
+function declaredPackages(dir: string): Set<string> {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    const file = join(d, "package.json");
+    if (existsSync(file)) {
+      try {
+        const json = JSON.parse(readFileSync(file, "utf-8")) as Record<string, unknown>;
+        const names = new Set<string>();
+        for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+          const deps = json[field];
+          if (deps && typeof deps === "object") for (const name of Object.keys(deps)) names.add(name);
+        }
+        return names;
+      } catch {
+        return new Set();
+      }
+    }
+    if (dirname(d) === d) return new Set();
+  }
+}
+
+function importerDir(importer: string | undefined): string | undefined {
+  if (!importer) return undefined;
+  try {
+    const path = importer.startsWith("file:") ? fileURLToPath(importer) : importer;
+    return isAbsolute(path) ? dirname(path) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The uninstalled package `message` reports, or `undefined` when it reports none. */
+export function uninstalledDependencyIn(message: string, projectDir: string): UninstalledDependency | undefined {
+  const dir = resolve(projectDir);
+  let declared: Set<string> | undefined;
+  for (const match of message.matchAll(NOT_FOUND)) {
+    const pkg = packageNameOf(match[1]);
+    if (pkg === undefined) continue;
+    if (!pkg.startsWith("@intentius/")) {
+      declared ??= declaredPackages(dir);
+      if (!declared.has(pkg)) continue;
+    }
+    if (installedFrom(pkg, dir)) continue;
+    const from = importerDir(match[2]);
+    if (from !== undefined && installedFrom(pkg, from)) continue;
+    return { package: pkg, dir };
+  }
+  return undefined;
+}
+
+/** The dependencies message, formatted as an error with the install hint. */
+export function formatDependenciesNotInstalled(dep: UninstalledDependency): string {
+  return formatError({
+    message: `dependencies not installed: ${dep.package} does not resolve from ${dep.dir}`,
+    hint: "run npm install (or the project's package manager)",
+  });
+}
+
+/**
+ * Print the dependencies message, naming the first uninstalled package, when
+ * any of a failure's `messages` reports one. Prints nothing and returns
+ * `undefined` when none does. Returns `"all"` when every message reports one,
+ * so a caller can drop its own wording when that wording blames the source.
+ */
+export function reportUninstalledDependencies(
+  messages: readonly string[],
+  projectDir: string,
+): "all" | "some" | undefined {
+  let first: UninstalledDependency | undefined;
+  let all = messages.length > 0;
+  for (const message of messages) {
+    const dep = uninstalledDependencyIn(message, projectDir);
+    if (dep) first ??= dep;
+    else all = false;
+  }
+  if (!first) return undefined;
+  console.error(formatDependenciesNotInstalled(first));
+  return all ? "all" : "some";
+}