@intentius/chant 0.124.31 → 0.124.33

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

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

@@ -148,6 +148,111 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--pr-loop asks for --require-review only under --require-review or the review-rules security group (#4168)", 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-review-rules-"));
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: root });
+      mkdirSync(join(root, "app"));
+      const declare = (extra: Record<string, unknown>) =>
+        writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, ...extra, 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");
+
+      declare({});
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[0][2].prLoop).toEqual({});
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true, requireReview: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[1][2].prLoop).toEqual({ requireReview: true });
+
+      declare({ security: ["review-rules"] });
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[2][2].prLoop).toEqual({ requireReview: true });
+
+      // #4168 step 7: a member's own group counts, and isolated-runners asks for --require-runner-start.
+      writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "chant", because: "the app", security: ["isolated-runners"] }] }));
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[3][2].prLoop).toEqual({ requireRunnerStart: true });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+      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,15 +16,23 @@ 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).
+ * `requireReview` is `--require-review`, or a workspace that opts into the
+ * `review-rules` security group (#4168); off otherwise. `requireRunnerStart`
+ * is `--require-runner-start`, or the `isolated-runners` group. `--apply-on-merge`
+ * (#4168) writes the apply job on merge in place of the record job.
  */
-function prLoopOption(args: CommandContext["args"]): PrLoopPipelineOptions {
+function prLoopOption(args: CommandContext["args"], reportUrl: string | undefined, requireReview = false, requireRunnerStart = false): 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 } : {}),
+    ...(args.requireReview === true || requireReview ? { requireReview: true } : {}),
+    ...(args.requireRunnerStart === true || requireRunnerStart ? { requireRunnerStart: true } : {}),
+    ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
   };
 }
 
@@ -90,6 +99,24 @@ 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;
+    }
+  }
+  // #4168: the review-rules group turns on --require-review in the generated apply. Read only inside a workspace.
+  let reviewRules = false;
+  let isolatedRunners = false;
+  if (found && args.prLoop) {
+    const groups = (await import("../../workspace/security")).securityGroupsAt(resolve(args.path));
+    reviewRules = groups.has("review-rules");
+    isolatedRunners = groups.has("isolated-runners");
+  }
   if (found) {
     memberPipeline = await import("../../workspace/member-pipeline");
     try {
@@ -104,7 +131,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, reviewRules, isolatedRunners) } : {}),
         ...(args.image ? { image: args.image } : {}),
         ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
       });
@@ -134,7 +161,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, reviewRules, isolatedRunners) } : {}),
       // #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 +311,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 +362,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 {