@intentius/chant 0.124.31 → 0.124.32

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

@@ -148,6 +148,75 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--pr-loop without --report-url bakes the workspace's ci.reportUrl into the jobs, and the flag wins (#4160)", async () => {
+    const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { execFileSync } = await import("node:child_process");
+    const root = mkdtempSync(join(tmpdir(), "chant-build-report-url-"));
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: root });
+      mkdirSync(join(root, "app"));
+      writeFileSync(
+        join(root, "chant.workspace.json"),
+        JSON.stringify({ name: "acme", schema: 1, ci: { reportUrl: "s3://acme-reports/prod/" }, members: [{ name: "app", dir: "app", kind: "chant", because: "the app" }] }),
+      );
+      generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "jobs: {}", stages: [], jobs: [] });
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      const path = join(root, "app");
+      const output = join(root, "out.yml");
+
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[0][2].prLoop).toEqual({ reportUrl: "s3://acme-reports/prod" });
+
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true, reportUrl: "file:///srv/reports" }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[1][2].prLoop).toEqual({ reportUrl: "file:///srv/reports" });
+
+      // Without --pr-loop the declaration's URL is not read and nothing changes.
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github" }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[2][2]).not.toHaveProperty("prLoop");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+      vi.restoreAllMocks();
+    }
+  });
+
+  test("--pr-loop outside any workspace has no report URL unless the flag gives one (#4160)", async () => {
+    const { mkdtempSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const plain = mkdtempSync(join(tmpdir(), "chant-build-plain-"));
+    try {
+      generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "jobs: {}", stages: [], jobs: [] });
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      expect(await runBuild({ args: makeArgs({ path: plain, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock).toHaveBeenCalledWith(plain, "github", { env: undefined, prLoop: {} }, undefined, []);
+    } finally {
+      rmSync(plain, { recursive: true, force: true });
+      vi.restoreAllMocks();
+    }
+  });
+
+  test("an invalid ci.reportUrl stops --pr-loop with its reason code, and generates nothing (#4160)", async () => {
+    const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { execFileSync } = await import("node:child_process");
+    const root = mkdtempSync(join(tmpdir(), "chant-build-report-url-bad-"));
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: root });
+      mkdirSync(join(root, "app"));
+      writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, ci: { reportUrl: "https://reports.example" }, members: [{ name: "app", dir: "app", kind: "chant", because: "the app" }] }));
+      const stderr = makeStderrSpy();
+      expect(await runBuild({ args: makeArgs({ path: join(root, "app"), generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(1);
+      expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
+      expect(stderr.join("\n")).toMatch(/ci\.reportUrl https:\/\/reports\.example: .*\[declaration-invalid\]/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+      vi.restoreAllMocks();
+    }
+  });
+
   test("--pr-build and --pr-build-command become the prLoop build options (#4088)", async () => {
     generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "jobs: {}", stages: [], jobs: [] });
     vi.spyOn(console, "log").mockImplementation(() => {});

package/src/cli/handlers/build.ts

@@ -2,6 +2,7 @@ import { writeFileSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { buildCommand, buildCommandWatch, printErrors, printWarnings, resolveBuildFormat } from "../commands/build";
 import { formatError, formatInfo, formatSuccess, formatBold } from "../format";
+import { reportUninstalledDependencies } from "../dependencies";
 import type { CommandContext } from "../registry";
 import { generateComponentsPipeline } from "../../components/cli-support";
 import { loadChantConfigUpward, type ChantConfig } from "../../config";
@@ -15,13 +16,14 @@ import type { PrLoopPipelineOptions } from "../../components/pr-pipeline";
  * and the branch, and with `--events-json` and `--report-url` (#4007) the
  * flags the generated jobs pass to pr-plan and pr-apply. `--pr-build` and
  * `--pr-build-command` (#4088) add the build and lint steps before both.
+ * `reportUrl` is `--report-url`, else the workspace's `ci.reportUrl` (#4160).
  */
-function prLoopOption(args: CommandContext["args"]): PrLoopPipelineOptions {
+function prLoopOption(args: CommandContext["args"], reportUrl: string | undefined): PrLoopPipelineOptions {
   return {
     ...(args.gate ? { gate: args.gate } : {}),
     ...(args.branch ? { branch: args.branch } : {}),
     ...(args.eventsJson ? { events: true } : {}),
-    ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
+    ...(reportUrl ? { reportUrl } : {}),
     ...(args.prBuild ? { build: true } : {}),
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
   };
@@ -90,6 +92,16 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   const found = findWorkspaceRoot(resolve(args.path));
   let plan: import("../../workspace/member-pipeline").MemberComponentPlan | undefined;
   let memberPipeline: typeof import("../../workspace/member-pipeline") | undefined;
+  // #4160: without --report-url, the declaration's ci.reportUrl. Read only inside a workspace.
+  let reportUrl = args.reportUrl;
+  if (found && args.prLoop && !reportUrl) {
+    try {
+      reportUrl = await (await import("../../workspace/ci-report-url")).declaredReportUrl(resolve(args.path));
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
   if (found) {
     memberPipeline = await import("../../workspace/member-pipeline");
     try {
@@ -104,7 +116,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         params: args.param,
         paramsFile: args.paramsFile,
         ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
-        ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+        ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl) } : {}),
         ...(args.image ? { image: args.image } : {}),
         ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
       });
@@ -134,7 +146,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
         : {}),
       // #3183: a plan job per pull request and an apply job per merge.
-      ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+      ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl) } : {}),
       // #4002: the job image and the lines that install what it lacks, chant itself included.
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
@@ -284,6 +296,8 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
       const own = result.warnings.filter((w) => !w.includes("No serializer found for lexicon") && !seenWarnings.has(w));
       for (const w of own) seenWarnings.add(w);
       printWarnings(own);
+      // #4116: once, before the first failing group's errors.
+      if (!result.success && !failed) reportUninstalledDependencies(result.errors, resolve(args.path));
       printErrors(result.errors);
       if (!result.success) failed = true;
     }
@@ -333,6 +347,8 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     warnings = warnings.filter((w) => !w.includes('No serializer found for lexicon'));
   }
   printWarnings(warnings);
+  // #4116: errors that are imports of uninstalled packages are led by the dependencies message.
+  if (!result.success) reportUninstalledDependencies(result.errors, resolve(args.path));
   printErrors(result.errors);
 
   return result.success ? 0 : 1;

package/src/cli/handlers/fan-out.test.ts

@@ -78,6 +78,18 @@ const ESTATE = [
 
 let ran: string[] = [];
 let failing: string[] = [];
+/** The error a component's step throws, in place of applying (#3997). */
+let refusal: Record<string, Error> = {};
+
+/** A step's refusal of a plan that moved since it was approved, marked `planMoved` as cfn-deploy marks it. */
+function planMovedError(component: string): Error {
+  return Object.assign(new Error(`${component}: refusing to apply, the plan moved`), { planMoved: true });
+}
+
+/** A step error carrying an `exitCode`, as kubectl-apply's carried one before #3997's follow-up. */
+function exitCodeError(component: string, exitCode: number): Error {
+  return Object.assign(new Error(`${component}: refused`), { exitCode });
+}
 /** What each component's step was handed, after wiring resolved. */
 let inputs: Record<string, Record<string, unknown>> = {};
 /** Stack outputs a component's step returns, as cfn-deploy's `outputs` does. */
@@ -118,6 +130,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   ran = [];
   failing = [];
+  refusal = {};
   inputs = {};
   stepOutputs = {};
   onStart = () => {};
@@ -155,6 +168,7 @@ beforeEach(() => {
         onStart(runCtx.component);
         ran.push(runCtx.component);
         inputs[runCtx.component] = input;
+        if (refusal[runCtx.component]) throw refusal[runCtx.component];
         if (failing.includes(runCtx.component)) throw new Error(`${runCtx.component} failed`);
         return { ok: true, ...(stepOutputs[runCtx.component] ? { outputs: stepOutputs[runCtx.component] } : {}) };
       },
@@ -310,6 +324,31 @@ describe("proof: a mid-run failure blocks its subtree and leaves the independent
   });
 });
 
+describe("a step that refuses its plan because the plan moved exits 3 (#3997)", () => {
+  test("marked planMoved: exit 3, and its subtree is blocked as for any failure", async () => {
+    refusal = { "cluster-a": planMovedError("cluster-a") };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(3);
+    expect(ran).not.toContain("app-one");
+    expect(ran).toContain("app-three");
+  });
+
+  test("an exitCode of 3 on the step's error is the same mark", async () => {
+    refusal = { "cluster-a": exitCodeError("cluster-a", 3) };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(3);
+  });
+
+  test("any other exitCode is ignored, and the failure exits 1", async () => {
+    refusal = { "cluster-a": exitCodeError("cluster-a", 7) };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(1);
+  });
+
+  test("one moved plan beside another failure still exits 3", async () => {
+    refusal = { "cluster-a": planMovedError("cluster-a") };
+    failing = ["cluster-b"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(3);
+  });
+});
+
 describe("proof: the re-run prints already-applied for what it skips, and finishes", () => {
   test("repeating the identical command finishes the fan-out, and the approval is not re-asked", async () => {
     const dir = await mkdtemp(join(tmpdir(), "fan-out-"));
@@ -523,6 +562,7 @@ describe("gated waves (#3049): one gate per wave, bound to the wave's set digest
         },
         async run(runCtx: { component: string }) {
           ran.push(runCtx.component);
+          if (refusal[runCtx.component]) throw refusal[runCtx.component];
           return { ok: true };
         },
       } as never);
@@ -530,6 +570,39 @@ describe("gated waves (#3049): one gate per wave, bound to the wave's set digest
     });
   });
 
+  /** Run the gated fan-out once to record wave 1's pending fact, then approve that digest. */
+  async function approveWave1(run: () => Promise<number>): Promise<void> {
+    await run();
+    const first = gateLedger.appended[0];
+    gateLedger = memoryGateLedgerPort({
+      pending: [first],
+      resolutions: [
+        {
+          version: 1,
+          kind: "resolution",
+          op: "fan-out",
+          gate: "release-wave-1",
+          resolvedBy: "operator",
+          timestamp: new Date(Date.parse(first.timestamp) + 1000).toISOString(),
+          planDigest: first.planDigest,
+        },
+      ],
+    });
+  }
+
+  test.each([
+    ["marked planMoved", 3, () => planMovedError("net")],
+    ["with exitCode 3", 3, () => exitCodeError("net", 3)],
+    ["with exitCode 7", 1, () => exitCodeError("net", 7)],
+    ["unmarked", 1, () => new Error("net failed")],
+  ])("an approved wave whose step fails with an error %s exits %i (#3997)", async (_label, code, error) => {
+    const run = () => runComponentsFanOut(ctx({ base: "main", env: "test", waveGate: "release" }));
+    await approveWave1(run);
+    refusal = { net: error() };
+    expect(await run()).toBe(code);
+    expect(ran).toEqual(["net"]);
+  });
+
   test("wave 1 stops at its own gate, and the record names its digest", async () => {
     const dir = await mkdtemp(join(tmpdir(), "fan-out-waves-"));
     try {

package/src/cli/handlers/fan-out.ts

@@ -68,9 +68,10 @@ import { approveCommand, gateIsSealed } from "../../op/gate";
 import { getHeadCommit } from "../../lifecycle/git";
 import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
 import { readDeployedOutputs } from "../../components/wave-plan";
-import { deployContext } from "../../components/driver";
+import { deployContext, failedRunExitCode } from "../../components/driver";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
+import { reportUninstalledDependencies } from "../dependencies";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { resolveBuildRoot } from "./lifecycle";
 import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run";
@@ -237,10 +238,14 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   } catch (err) {
     // A cycle or an unknown `dependsOn` refuses here, over the whole graph and
     // before anything is selected (#2417). The message names the members.
-    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    const message = err instanceof Error ? err.message : String(err);
+    reportUninstalledDependencies([message], projectPath); // #4116
+    console.error(formatError({ message }));
     return 1;
   }
   if (!derived.success) {
+    // #4116: component files that import packages the project has not installed.
+    if (derived.error) reportUninstalledDependencies([derived.error], projectPath);
     console.error(formatError({ message: derived.error ?? "Could not discover components" }));
     return 1;
   }
@@ -522,8 +527,10 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       ...(await summaryLedgerPrefix()),
       ...(pending.environment ? { environment: pending.environment } : {}),
     });
-    return result.status === "gated" ? GATED_EXIT_CODE : 1;
+    return result.status === "gated" ? GATED_EXIT_CODE : failedRunExitCode(result.results);
   }
 
-  return result.status === "ok" ? 0 : 1;
+  // A step that refused the wave's plan because its target moved since the
+  // approval exits 3, the code of a wave whose plan changed (#3997).
+  return result.status === "ok" ? 0 : failedRunExitCode(result.results);
 }

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

@@ -1,4 +1,7 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
@@ -468,6 +471,79 @@ describe("runGraph", () => {
       expect(discoverMock).not.toHaveBeenCalled();
     });
 
+    // #4116: a clone of examples/fan-out-estate with no node_modules. Every
+    // source file fails to import its lexicon, and lint reports each import.
+    describe("lint gate: dependencies not installed (#4116)", () => {
+      let project: string;
+      beforeEach(() => {
+        project = realpathSync(mkdtempSync(join(tmpdir(), "chant-4116-graph-")));
+      });
+      afterEach(() => {
+        rmSync(project, { recursive: true, force: true });
+      });
+      const missing = (pkg: string, file: string) => ({
+        file: join(project, file), line: 1, column: 1, ruleId: "LEX002", severity: "error",
+        message: `Cannot find package '${pkg}' imported from ${join(project, file)}`,
+      });
+
+      test("every lint error an uninstalled import: the dependencies message, not lint errors", async () => {
+        lintMock.mockResolvedValue({
+          success: false,
+          diagnostics: [
+            missing("@intentius/chant-lexicon-aws", "src/network/outputs.ts"),
+            { ...missing("@intentius/chant", "network.component.ts"), ruleId: "COMP000", message: `Component discovery error: ${missing("@intentius/chant", "network.component.ts").message}` },
+            { ...missing("@intentius/chant", "x.ts"), ruleId: "COR004", severity: "warning", message: "a warning" },
+          ],
+        });
+        for (const components of [false, true]) {
+          stderrBuf.length = 0;
+          const exit = await runGraph({ args: makeArgs({ format: "ir", path: project, components }), plugins: [], serializers: [] });
+          expect(exit).toBe(1);
+          const err = stderrBuf.join("\n");
+          expect(err).toContain(`dependencies not installed: @intentius/chant-lexicon-aws does not resolve from ${project}`);
+          expect(err).toContain("run npm install (or the project's package manager)");
+          expect(err).not.toMatch(/lint errors/i);
+        }
+      });
+
+      test("an uninstalled import beside a real lint error: both are said", async () => {
+        lintMock.mockResolvedValue({
+          success: false,
+          diagnostics: [
+            missing("@intentius/chant-lexicon-aws", "src/a.ts"),
+            { file: join(project, "src/b.ts"), line: 3, column: 1, ruleId: "COR001", severity: "error", message: "a real problem" },
+          ],
+        });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", path: project }), plugins: [], serializers: [] });
+        expect(exit).toBe(1);
+        const err = stderrBuf.join("\n");
+        expect(err).toContain("dependencies not installed: @intentius/chant-lexicon-aws");
+        expect(err).toMatch(/source has lint errors/);
+      });
+
+      test("real lint errors still say lint errors, with no dependencies message", async () => {
+        lintMock.mockResolvedValue({
+          success: false,
+          diagnostics: [{ file: join(project, "src/b.ts"), line: 3, column: 1, ruleId: "COR001", severity: "error", message: "a real problem" }],
+        });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", path: project }), plugins: [], serializers: [] });
+        expect(exit).toBe(1);
+        const err = stderrBuf.join("\n");
+        expect(err).toMatch(/source has lint errors/);
+        expect(err).not.toContain("dependencies not installed");
+      });
+
+      test("an import the project has installed is a lint error, not a missing dependency", async () => {
+        mkdirSync(join(project, "node_modules", "@intentius", "chant-lexicon-aws"), { recursive: true });
+        lintMock.mockResolvedValue({ success: false, diagnostics: [missing("@intentius/chant-lexicon-aws", "src/a.ts")] });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", path: project }), plugins: [], serializers: [] });
+        expect(exit).toBe(1);
+        const err = stderrBuf.join("\n");
+        expect(err).toMatch(/source has lint errors/);
+        expect(err).not.toContain("dependencies not installed");
+      });
+    });
+
     test("--format mermaid emits a flowchart", async () => {
       lintClean(); discovered();
       const exit = await runGraph({ args: makeArgs({ format: "mermaid" }), plugins: [], serializers: [] });

package/src/cli/handlers/graph.ts

@@ -19,7 +19,8 @@ import { applyLens, parseLens } from "../../graph-lens";
 import { toMermaid } from "../../graph-mermaid";
 import { toDot } from "../../graph-dot";
 import { getLayoutEngine, toLayoutInput, type NodeSize } from "../../graph-layout";
-import { lintCommand } from "../commands/lint";
+import { lintCommand, type LintResult } from "../commands/lint";
+import { reportUninstalledDependencies } from "../dependencies";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins";
 import { isNoLexiconDetected } from "../../detectLexicon";
 import { readFileSync } from "node:fs";
@@ -555,6 +556,21 @@ async function runComponentGraph(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * The lint gate's refusal. When the lint errors are imports of packages the
+ * project has not installed (#4116), the dependencies message leads, and it
+ * stands alone when every error is one: the source is not what is wrong.
+ */
+function refuseLintGate(lint: LintResult, projectPath: string): void {
+  const errors = (lint.diagnostics ?? []).filter((d) => d.severity === "error").map((d) => d.message);
+  if (reportUninstalledDependencies(errors, projectPath) === "all") return;
+  console.error(
+    formatError({
+      message: "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
+    }),
+  );
+}
+
 /**
  * `chant graph --components --format ir|mermaid|dot|layout` — the component DAG
  * projected into the renderable IR (nodes = components, `groups.byWave` = the
@@ -596,11 +612,7 @@ async function runComponentGraphView(
     buildParams: componentParams,
   });
   if (!lint.success) {
-    console.error(
-      formatError({
-        message: "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
-      }),
-    );
+    refuseLintGate(lint, projectPath);
     return 1;
   }
 
@@ -869,12 +881,7 @@ async function runGraphView(
     buildParams,
   });
   if (!lint.success) {
-    console.error(
-      formatError({
-        message:
-          "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
-      }),
-    );
+    refuseLintGate(lint, projectPath);
     return 1;
   }
 

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

@@ -16,6 +16,9 @@
  * #1108 gap in generate mode.
  */
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ParsedArgs } from "../registry";
 
 const lintCommandMock = vi.fn();
@@ -105,3 +108,42 @@ describe("runLint build-time parameters (#2251)", () => {
     expect(lintCommandMock).not.toHaveBeenCalled();
   });
 });
+
+describe("runLint on a project whose dependencies are not installed (#4116)", () => {
+  let project: string;
+  let stderr: string[];
+
+  beforeEach(() => {
+    project = realpathSync(mkdtempSync(join(tmpdir(), "chant-4116-lint-")));
+    stderr = [];
+    loadChantConfigUpwardMock.mockReset().mockResolvedValue({ config: {} });
+    vi.spyOn(console, "error").mockImplementation((s: string) => void stderr.push(s));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(project, { recursive: true, force: true });
+  });
+
+  const failing = (message: string) =>
+    lintCommandMock.mockReset().mockResolvedValue({
+      success: false,
+      errorCount: 1,
+      warningCount: 0,
+      diagnostics: [{ file: join(project, "src/a.ts"), line: 1, column: 1, ruleId: "LEX002", severity: "error", message }],
+    });
+
+  test("an uninstalled import leads with the dependencies message", async () => {
+    failing(`Cannot find package '@intentius/chant-lexicon-aws' imported from ${join(project, "src/a.ts")}`);
+    const exit = await runLint({ args: makeArgs({ path: project }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain(`dependencies not installed: @intentius/chant-lexicon-aws does not resolve from ${project}`);
+  });
+
+  test("a real lint error prints no dependencies message", async () => {
+    failing("Exported declarable 'x' is broken");
+    const exit = await runLint({ args: makeArgs({ path: project }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).not.toContain("dependencies not installed");
+  });
+});

package/src/cli/handlers/lint.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { lintCommand, lintCommandWatch, printLintResult } from "../commands/lint";
 import { formatError, formatInfo } from "../format";
+import { reportUninstalledDependencies } from "../dependencies";
 import type { CommandContext } from "../registry";
 import { commandBuildParams } from "../build-params-cli";
 import { loadChantConfigUpward, type ChantConfig } from "../../config";
@@ -63,6 +64,11 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     buildParams,
   });
 
+  // #4116: errors that are imports of uninstalled packages are led by the dependencies message.
+  if (!result.success) {
+    const errors = result.diagnostics.filter((d) => d.severity === "error").map((d) => d.message);
+    reportUninstalledDependencies(errors, resolve(args.path));
+  }
   printLintResult(result);
   return result.success ? 0 : 1;
 }

package/src/cli/handlers/operator.ts

@@ -221,8 +221,8 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
  *
  * Refuses, before ticking anything:
  * - an environment whose form is `fountain`, because there the composite's
- *   Agent and Teammate are the steward and this process would be a second
- *   writer beside them;
+ *   Agent and its conversation are the steward and this process would be a
+ *   second writer beside them;
  * - a steward whose lease another live process holds (a second local
  *   operator for it).
  */
@@ -242,7 +242,7 @@ export async function runStewardOperator(ctx: CommandContext): Promise<number> {
   if (form !== "local") {
     console.error(formatError({
       message: `steward "${steward.name}" runs on ${form} in environment "${env}", so a local operator for it would be a second writer`,
-      hint: `Its turns run on the fountain teammate "${steward.name}". Run this in an environment the declaration's form makes local, or change the form.`,
+      hint: `Its turns run in the fountain steward "${steward.name}"'s conversation. Run this in an environment the declaration's form makes local, or change the form.`,
     }));
     return 1;
   }