@intentius/chant 0.124.31 → 0.124.33

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/lifecycle-health.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createMockPlugin } from "@intentius/chant-test-utils";
+import type { BuildResult } from "../../build";
+import type { LexiconPlugin } from "../../lexicon";
+import type { ParsedArgs } from "../registry";
+import { HEALTH_SCHEMA_ID } from "../../health";
+import { UNOBSERVED_REASONS } from "../../observation";
+import { contract, validSchema } from "../../workspace/__fixtures__/contract-repo";
+import schema from "../../health.schema.json";
+
+const { expectValid, validate } = contract(schema);
+
+const buildMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+
+const { runLifecycleHealth } = await import("./lifecycle-health");
+
+function args(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return { command: "lifecycle", path: "health", format: "", fix: false, watch: false, verbose: false, help: false, extraPositional: "prod", ...overrides } as ParsedArgs;
+}
+
+function buildResult(entities: Array<[string, string, string]>): BuildResult {
+  return {
+    outputs: new Map([["aws", "{}"]]),
+    entities: new Map(entities.map(([name, lexicon, entityType]) => [name, { lexicon, entityType, kind: "resource", props: {} }])),
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: { lexicons: ["aws"], outputs: {}, deployOrder: ["aws"] },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("chant lifecycle health (#4177)", () => {
+  let out: string[];
+  let err: string[];
+  beforeEach(() => {
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { err.push(s); });
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"] } });
+    buildMock.mockReset();
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  test("asks only about the types the lexicon names, and prints chant-health/v1", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"], ["bucket", "aws", "AWS::S3::Bucket"]]));
+    const asked: string[][] = [];
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async (o) => {
+        asked.push([...o.entities.keys()]);
+        return { entities: { web: { type: "AWS::ECS::Service", state: "unhealthy", detail: "0/2 running", observedAt: "t" } }, unobserved: {}, absent: [] };
+      },
+    };
+    const exit = await runLifecycleHealth({ args: args({ json: true }), plugins: [plugin], serializers: [plugin.serializer] });
+    expect(exit).toBe(0);
+    expect(asked).toEqual([["web"]]);
+    const json = JSON.parse(out[0]!);
+    expect(json.schema).toBe("chant-health/v1");
+    expect(typeof json.chantVersion).toBe("string");
+    expect(json.lexicons.aws.entities.web.state).toBe("unhealthy");
+    expect(json.summary).toEqual({ healthy: 0, unhealthy: 1, unknown: 0, unobserved: 0, absent: 0 });
+    expectValid(json);
+  });
+
+  test("a reader that throws is not read, never unhealthy", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"]]));
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async () => {
+        throw new Error("no route to host");
+      },
+    };
+    await runLifecycleHealth({ args: args(), plugins: [plugin], serializers: [plugin.serializer] });
+    expect(out.join("\n")).toContain("not read  web (AWS::ECS::Service): read-failed, no route to host");
+    expect(err.join("\n")).toContain("0 healthy, 0 unhealthy, 0 unknown, 1 not observed");
+  });
+
+  test("refuses with no environment, and with no lexicon that reads health", async () => {
+    const plain = createMockPlugin({ name: "aws" });
+    expect(await runLifecycleHealth({ args: args({ extraPositional: undefined }), plugins: [plain], serializers: [] })).toBe(1);
+    expect(await runLifecycleHealth({ args: args(), plugins: [plain], serializers: [] })).toBe(1);
+    expect(err.join("\n")).toContain("No configured lexicon has a health read");
+  });
+
+  test("the JSON of a read that failed follows the schema", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"], ["gone", "aws", "AWS::ECS::Service"]]));
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async () => ({ entities: {}, unobserved: { web: { type: "AWS::ECS::Service", reason: "no-credentials", detail: "no AWS credentials" } }, absent: ["gone"] }),
+    };
+    await runLifecycleHealth({ args: args({ json: true }), plugins: [plugin], serializers: [plugin.serializer] });
+    const json = JSON.parse(out[0]!);
+    expect(json.summary).toEqual({ healthy: 0, unhealthy: 0, unknown: 0, unobserved: 1, absent: 1 });
+    expectValid(json);
+  });
+});
+
+describe("the chant-health/v1 schema (#4177)", () => {
+  test("is a valid schema with the exported id, and names every unobserved reason", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(HEALTH_SCHEMA_ID);
+    expect([...schema.$defs.hole.properties.reason.enum].sort()).toEqual([...UNOBSERVED_REASONS].sort());
+  });
+
+  test("a document with neither lexicons nor stacks, or a state outside the three, does not validate", () => {
+    const base = { schema: "chant-health/v1", chantVersion: "0.124.33", environment: "prod", observedAt: "t", summary: { healthy: 0, unhealthy: 0, unknown: 0, unobserved: 0, absent: 0 } };
+    expect(validate(base)).toBe(false);
+    expectValid({ ...base, stacks: { east: {} } });
+    const bad = { ...base, lexicons: { aws: { entities: { web: { type: "AWS::ECS::Service", state: "down", detail: "", observedAt: "t" } }, unobserved: {}, absent: [] } } };
+    expect(validate(bad)).toBe(false);
+  });
+});

package/src/cli/handlers/lifecycle-health.ts

@@ -0,0 +1,157 @@
+/**
+ * `chant lifecycle health <env> [lexicon] [--json]` (#4177): whether each
+ * declared resource that has a health read is up, separate from drift.
+ *
+ * It builds the project as `lifecycle diff` does, so the entity names are the
+ * graph's node ids, then asks each lexicon with a health read about the
+ * entities whose types it names. An environment's declared endpoint is applied
+ * for the read, as on the other live reads (#1166).
+ *
+ * The JSON is the {@link HEALTH_SCHEMA} shape. A single-stack project prints
+ * `lexicons` at the top level; a multi-stack one nests them under `stacks`,
+ * the same split `lifecycle diff --live --json` makes.
+ */
+
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { loadChantConfig } from "../../config";
+import { isObservableDeclarable } from "../../declarable";
+import { HEALTH_SCHEMA, healthApplicable, observeHealthFor, summarizeHealth, type HealthLexicon, type HealthReadResult } from "../../health";
+import { applyLiveEndpoint } from "../../live-endpoint";
+import type { SerializerResult } from "../../serializer";
+import { CHANT_VERSION } from "../version";
+import { commandBuildParams } from "../build-params-cli";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
+import { formatBold, formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { resolveStackTargets } from "./lifecycle";
+
+type ByLexicon = Record<string, HealthReadResult>;
+
+export async function runLifecycleHealth(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle health <environment> [lexicon]" }));
+    return 1;
+  }
+
+  const readers = plugins.filter(
+    (p) => p.observeHealth && (p.healthTypes?.length ?? 0) > 0 && (!lexiconFilter || p.name === lexiconFilter),
+  );
+  if (readers.length === 0) {
+    console.error(formatWarning({
+      message: lexiconFilter
+        ? `${lexiconFilter}: no health read in this lexicon`
+        : "No configured lexicon has a health read (aws, azure and gcp do)",
+    }));
+    return 1;
+  }
+
+  const projectRoot = resolve(".");
+  const { config } = await loadChantConfig(projectRoot);
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
+  const targets = resolveStackTargets(args, config);
+  const buildOptions = resolveProjectBuildOptions({
+    config,
+    configDir: projectRoot,
+    plugins,
+    modes: resolveBuildModes(config, { fold: args.fold, sandbox: args.sandbox }),
+    buildParams: declaredParams,
+  });
+  const serializers = readers.map((p) => p.serializer);
+
+  const endpoint = applyLiveEndpoint(config.environments, environment, readers);
+  if (endpoint.notice) console.error(formatWarning({ message: endpoint.notice }));
+
+  const perStack: Record<string, ByLexicon> = {};
+  let single: ByLexicon | undefined;
+  let anyBuildError = false;
+  const observedAt = new Date().toISOString();
+
+  try {
+    for (const target of targets) {
+      const buildResult = await build(target.root, serializers, undefined, buildOptions);
+      if (buildResult.errors.length > 0) {
+        console.error(formatError({
+          message: `Build failed for ${target.stack ? `stack "${target.stack}"` : "project"}; fix errors before reading health`,
+        }));
+        anyBuildError = true;
+        continue;
+      }
+      const byLexicon: ByLexicon = {};
+      for (const plugin of readers) {
+        const declared = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+        for (const [name, entity] of buildResult.entities) {
+          if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
+            declared.set(name, {
+              entityType: entity.entityType,
+              props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            });
+          }
+        }
+        const entities = healthApplicable(plugin as HealthLexicon, declared);
+        if (entities.size === 0) continue;
+        const raw = buildResult.outputs.get(plugin.name);
+        const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
+        byLexicon[plugin.name] = await observeHealthFor(plugin as HealthLexicon, {
+          environment,
+          buildOutput,
+          entities,
+          ...(target.stack ? { stack: target.stack } : {}),
+          ...(target.region ? { region: target.region } : {}),
+        });
+      }
+      if (target.stack) perStack[target.stack] = byLexicon;
+      else single = byLexicon;
+    }
+  } finally {
+    endpoint.restore();
+  }
+
+  const all = single ? [single] : Object.values(perStack);
+  const summary = summarizeHealth(all.flatMap((b) => Object.values(b)));
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      schema: HEALTH_SCHEMA,
+      chantVersion: CHANT_VERSION,
+      environment,
+      observedAt,
+      ...(single ? { lexicons: single } : { stacks: perStack }),
+      summary,
+    }));
+  } else {
+    if (single) renderHealth(single);
+    else for (const [stack, byLexicon] of Object.entries(perStack)) {
+      console.log(`\n${formatBold(`■ stack ${stack}`)}`);
+      renderHealth(byLexicon);
+    }
+    const total = summary.healthy + summary.unhealthy + summary.unknown + summary.unobserved + summary.absent;
+    if (total === 0) {
+      console.error(formatWarning({ message: "No declared resource has a health read" }));
+    } else {
+      console.error(
+        `${summary.healthy} healthy, ${summary.unhealthy} unhealthy, ${summary.unknown} unknown` +
+          (summary.unobserved > 0 ? `, ${summary.unobserved} not observed` : "") +
+          (summary.absent > 0 ? `, ${summary.absent} not deployed` : ""),
+      );
+    }
+  }
+  return anyBuildError ? 1 : 0;
+}
+
+function renderHealth(byLexicon: ByLexicon): void {
+  for (const [lexicon, result] of Object.entries(byLexicon)) {
+    console.log(formatBold(lexicon));
+    for (const [name, entry] of Object.entries(result.entities)) {
+      console.log(`  ${entry.state.padEnd(9)} ${name} (${entry.type}): ${entry.detail}`);
+    }
+    for (const [name, hole] of Object.entries(result.unobserved)) {
+      console.log(`  ${"not read".padEnd(9)} ${name}${hole.type ? ` (${hole.type})` : ""}: ${hole.reason}${hole.detail ? `, ${hole.detail}` : ""}`);
+    }
+    for (const name of result.absent) console.log(`  ${"absent".padEnd(9)} ${name}: not deployed`);
+  }
+}

package/src/cli/handlers/lifecycle.ts

@@ -90,7 +90,7 @@ interface StackTarget {
  * observed as the stack named after the environment (unchanged behavior). An
  * explicit `--src` always wins and forces a single scoped target.
  */
-function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
+export function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
   if (args.src) return [{ root: resolve(args.src) }];
   if (config.stacks && config.stacks.length > 0) {
     return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));

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;
   }