@intentius/chant 0.79.0 → 0.81.0

package/src/op/activity-registry.ts

@@ -12,6 +12,7 @@
 
 import * as baseActivities from "./activities";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+import { importLexiconModule } from "../lexicon-module";
 
 export type { ActivityProfile } from "./activity-profiles";
 
@@ -52,6 +53,16 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
 
   for (const name of lexicons) {
     try {
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import; its plugin's `activities()` member stands in for it.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        const plugin = Object.values(local).find((v) => isActivityContributor(v) && v.name === name) as
+          | ActivityContributor
+          | undefined;
+        if (plugin) collectActivities(await plugin.activities(), activities);
+        continue;
+      }
       const spec = `@intentius/chant-lexicon-${name}/op/activities`;
       collectActivities((await import(spec)) as Record<string, unknown>, activities);
     } catch {
@@ -62,6 +73,21 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
   return activities;
 }
 
+/** A plugin-shaped export with an `activities()` member (`LexiconPlugin.activities`). Structural, so this layer does not import `../lexicon.ts`. */
+interface ActivityContributor {
+  name: string;
+  activities(): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+function isActivityContributor(value: unknown): value is ActivityContributor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === "string" &&
+    typeof (value as { activities?: unknown }).activities === "function"
+  );
+}
+
 /**
  * The built-in profile table. Kept async because it is awaited on the CLI's
  * run path alongside {@link loadActivities}, and because a hosted runtime may

package/src/op/discover.test.ts

@@ -1,6 +1,11 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { discoverOps } from "./discover";
 
+/** The example project that holds `ops/alb-deploy.op.ts`. */
+const ALB_INFRA = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../examples/gitlab-aws-alb-infra");
+
 // Mock getRuntime to return git root pointing at the repo root. Partial, via
 // `importOriginal`: the modules a discovered Op file pulls in reach the rest of
 // this module (`moduleDir`, for the lint presets), and a wholesale replacement
@@ -23,14 +28,19 @@ vi.mock("../runtime-adapter", async (importOriginal) => ({
 }));
 
 describe("discoverOps", () => {
-  test("discovers alb-deploy.op.ts from examples/", async () => {
-    const { ops, errors } = await discoverOps();
+  test("discovers alb-deploy.op.ts from its own project", async () => {
+    const { ops, errors } = await discoverOps({ cwd: ALB_INFRA });
     expect(errors).toHaveLength(0);
     expect(ops.has("alb-deploy")).toBe(true);
   });
 
-  test("discovered Op has correct config shape", async () => {
+  test("from the git root, a child project's Ops are not discovered (#2527)", async () => {
     const { ops } = await discoverOps();
+    expect(ops.has("alb-deploy")).toBe(false);
+  });
+
+  test("discovered Op has correct config shape", async () => {
+    const { ops } = await discoverOps({ cwd: ALB_INFRA });
     const op = ops.get("alb-deploy");
     expect(op).toBeDefined();
     expect(op!.config.name).toBe("alb-deploy");
@@ -40,7 +50,7 @@ describe("discoverOps", () => {
   });
 
   test("filePath points to the .op.ts source file", async () => {
-    const { ops } = await discoverOps();
+    const { ops } = await discoverOps({ cwd: ALB_INFRA });
     const op = ops.get("alb-deploy");
     expect(op!.filePath).toMatch(/alb-deploy\.op\.ts$/);
   });

package/src/op/discover.ts

@@ -1,8 +1,10 @@
 import { getRuntime } from "../runtime-adapter";
-import { readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import type { OpConfig } from "./types";
+import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
+import { hasDiscoveryMarkerSync } from "../discovery/files";
+import { resolveDiscoveryGlobs } from "../config";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -52,28 +54,22 @@ async function findDiscoveryRoot(cwd?: string): Promise<string> {
   return gitRoot;
 }
 
-async function collectOpFiles(dir: string): Promise<string[]> {
-  const files: string[] = [];
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return files;
-  }
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "dist") {
-      files.push(...await collectOpFiles(fullPath));
-    } else if (
-      entry.isFile() &&
-      entry.name.endsWith(".op.ts") &&
-      !entry.name.endsWith(".test.ts") &&
-      !entry.name.endsWith(".spec.ts")
-    ) {
-      files.push(fullPath);
-    }
-  }
-  return files;
+/**
+ * Every `*.op.ts` file below the Op root, through the one discovery walk
+ * (`../discovery/walk.ts`, #2527). The walk down stops at child projects
+ * whatever the root is, so a configless layout whose Op root is the git root
+ * no longer collects its sibling projects' Ops. The project's
+ * `exclude`/`include` globs and the skip marker apply.
+ */
+async function collectOpFiles(root: string): Promise<string[]> {
+  return walkDiscovery({
+    walker: "ops",
+    root,
+    globs: await resolveDiscoveryGlobs(root),
+    excludeDirs: await workspaceMemberDirs(root),
+    accept: (name, full) =>
+      name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full),
+  });
 }
 
 /** The `OpConfig` behind an exported value, or `undefined` when the value is not an Op. An Op entity carries its config on `.props` (`./resource.ts`); `name` and `phases` are what every consumer of a discovered Op reads. */

package/src/op/gate-approval.ts

@@ -32,6 +32,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { lexiconModulePath } from "../lexicon-module";
 import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
 
 /** What a policy's decision does to the gate. */
@@ -221,7 +222,8 @@ function isContextValue(value: unknown): boolean {
 
 /** Import `lexicon`'s evaluator. Throws a message that names the package when it is not installed or exports none. */
 export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePolicyEvaluator> {
-  const spec = `@intentius/chant-lexicon-${lexicon}/gate-policy`;
+  // chant #2520 — a lexicon declared by module path exports its evaluator from that module.
+  const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
   let mod: Partial<GatePolicyEvaluator>;
   try {
     mod = (await import(spec)) as Partial<GatePolicyEvaluator>;

package/src/op/gate-name.ts

@@ -29,6 +29,14 @@ import type { OpConfig, PhaseDefinition, StepDefinition } from "./types";
  */
 export const FAN_OUT_GATE_OP = "fan-out";
 
+/**
+ * The op name a `chant workspace upgrade` gate is recorded under (#2550). The
+ * gate is the scope (`.` for a plain project), and it binds the digest of the
+ * upgrade's patch. Like a fan-out, the upgrade is a command with no `*.op.ts`
+ * behind it, so `chant approve` must not warn that it found none.
+ */
+export const WORKSPACE_UPGRADE_GATE_OP = "workspace-upgrade";
+
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
 export interface GateNamed {
   gate?: string;

package/src/op/gate-summary.test.ts

@@ -58,6 +58,20 @@ describe("gatedRunSummaryMarkdown (#2243)", () => {
     expect(md).toContain("and not the next run");
   });
 
+  // #2574 with #2538: a component gate in a workspace member names both its
+  // environment in the approve line and the member's gate ledger path.
+  test("a member's component gate names its environment and its member ledger path", () => {
+    const md = gatedRunSummaryMarkdown({
+      op: "search-service",
+      gate: "release",
+      expiresAt: "2026-09-08T00:00:00Z",
+      environment: "prod",
+      ledgerPrefix: "_members/services/search/",
+    });
+    expect(md).toContain("chant approve search-service release --env prod --approver <you>");
+    expect(md).toContain("`_members/services/search/_gates/search-service.jsonl`");
+  });
+
   test("a gate that binds no plan says nothing about one", () => {
     expect(gatedRunSummaryMarkdown(summary)).not.toContain("and not the next run");
   });

package/src/op/gate-summary.ts

@@ -20,6 +20,7 @@
 
 import { appendFileSync } from "node:fs";
 import { gateLedgerPath } from "../lifecycle/gate-ledger";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { approveCommand } from "./gate";
 
 /** What a gated run knows about the gate it stopped on. */
@@ -50,6 +51,28 @@ export interface GatedRunSummary {
    * to see that the digest has moved on.
    */
   planDigest?: string;
+  /**
+   * The project's ledger prefix, `_members/<member>/` for a workspace member
+   * (#2538), so the ledger path shown is the one the fact was written to.
+   * Absent at level 0 and for the root member.
+   */
+  ledgerPrefix?: string;
+  /** The environment a component gate's pending fact was recorded in (#2574). The `chant approve` line names it. */
+  environment?: string;
+}
+
+/**
+ * `{ ledgerPrefix }` for the project at `cwd` when it is a workspace member,
+ * else `{}`. A summary is a report, so a declaration that cannot be read
+ * leaves the path as it is rather than failing the report.
+ */
+export async function summaryLedgerPrefix(cwd: string = process.cwd()): Promise<{ ledgerPrefix?: string }> {
+  try {
+    const { prefix } = await resolveMemberLedger(cwd);
+    return prefix ? { ledgerPrefix: prefix } : {};
+  } catch {
+    return {};
+  }
 }
 
 /**
@@ -78,10 +101,10 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
     "Approve it, then re-run this workflow:",
     "",
     "```",
-    `${approveCommand(summary.op, summary.gate)} --approver <you>`,
+    `${approveCommand(summary.op, summary.gate, summary.environment)} --approver <you>`,
     "```",
     "",
-    `Ledger: \`${gateLedgerPath(summary.op)}\` on the \`chant/lifecycle\` branch.`,
+    `Ledger: \`${gateLedgerPath(summary.op, summary.ledgerPrefix)}\` on the \`chant/lifecycle\` branch.`,
   );
   if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
   if (summary.url) lines.push(`Approve at: ${summary.url}`);

package/src/op/gate.ts

@@ -170,6 +170,14 @@ export interface GateCheckInput {
    * the standing pending fact satisfies the gate whatever has changed since.
    */
   planDigest?: string;
+  /**
+   * The environment this run deploys to (#2574). The component driver sets it,
+   * because a component's gate ledger is keyed by component and holds every
+   * environment's facts. Set, the gate reads only this environment's pending
+   * facts and resolutions (plus resolutions that record no environment, which
+   * come back as a mismatch), and the pending fact it records carries it.
+   */
+  environment?: string;
   /**
    * The gate's quorum and policy (#2508), context already resolved. Absent,
    * one approval passes the gate, which is the rule every gate had before.
@@ -194,6 +202,8 @@ export interface GateDigestMismatch {
   resolvedBy: string;
   /** When they recorded it. */
   timestamp: string;
+  /** The environment this run deploys to, on a component gate (#2574). The approve command a refusal prints names it. */
+  environment?: string;
 }
 
 /**
@@ -210,15 +220,18 @@ export interface GateDigestMismatch {
 export function describeGateMismatch(op: string, gate: string, mismatch: GateDigestMismatch): string {
   const why =
     mismatch.approved === undefined
-      ? "That resolution predates plan-bound gates (#2300) and records no plan at all, so it cannot " +
-        "answer for this one. Approving again binds it:"
+      ? mismatch.environment !== undefined
+        ? "That approval predates environment- and plan-bound component gates (#2574) and records neither, " +
+          "so it cannot answer for this one. Approving again binds it:"
+        : "That resolution predates plan-bound gates (#2300) and records no plan at all, so it cannot " +
+          "answer for this one. Approving again binds it:"
       : "The configuration or the live system changed between that approval and this plan, so it needs " +
         "a fresh one:";
   return (
     `Gate "${gate}" is approved, but not for this plan. ` +
     `approved: ${describePlanDigest(mismatch.approved)} (by ${mismatch.resolvedBy} at ${mismatch.timestamp}); ` +
     `planned: ${mismatch.planned}. ` +
-    `${why} ${approveCommand(op, gate)}`
+    `${why} ${approveCommand(op, gate, mismatch.environment)}`
   );
 }
 
@@ -374,7 +387,17 @@ const EPOCH = new Date(0).toISOString();
  */
 export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
   const now = input.now ?? new Date().toISOString();
-  const { resolutions, pending } = await port.read(input.op);
+  const ledger = await port.read(input.op);
+  // #2574: a component's ledger holds every environment's facts. This run
+  // answers only to its own environment's pending facts and approvals. An
+  // approval that records no environment at all is kept, so it comes back as
+  // a mismatch with a message instead of silently not counting.
+  const env = input.environment;
+  const pending = env === undefined ? ledger.pending : ledger.pending.filter((p) => p.environment === env);
+  const resolutions =
+    env === undefined
+      ? ledger.resolutions
+      : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env);
 
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
@@ -410,6 +433,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
         planned: input.planDigest!,
         resolvedBy: mismatched.resolvedBy,
         timestamp: mismatched.timestamp,
+        ...(env !== undefined ? { environment: env } : {}),
       }
     : undefined;
   const asMismatch = { ...(mismatch ? { mismatch } : {}), ...(quorum ? { quorum } : {}) };
@@ -441,6 +465,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    ...(env !== undefined ? { environment: env } : {}),
     ...(input.approval ? { approval: input.approval } : {}),
   });
   return {
@@ -453,7 +478,11 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   };
 }
 
-/** The line every renderer prints to say how a pending gate is cleared. */
-export function approveCommand(op: string, gate: string): string {
-  return `chant approve ${op} ${gate}`;
+/**
+ * The line every renderer prints to say how a pending gate is cleared. A
+ * component gate names its environment (#2574), so the approval picks that
+ * environment's pending fact when others stand beside it.
+ */
+export function approveCommand(op: string, gate: string, environment?: string): string {
+  return environment === undefined ? `chant approve ${op} ${gate}` : `chant approve ${op} ${gate} --env ${environment}`;
 }

package/src/op/generate-pipeline.test.ts

@@ -3,12 +3,16 @@
  * `../components/cli-support.ts`'s `generateComponentsPipeline`. Mirrors that
  * module's own test style (`cli-support.test.ts`): a minimal mocked lexicon
  * plugin satisfying `isLexiconPlugin`, real `discoverOps()` resolution
- * against this repo's actual `*.op.ts` fixtures (`examples/alb-deploy.op.ts`
- * — see `./discover.test.ts`) so Op-name validation exercises the real
- * discovery path rather than a stub.
+ * against this repo's actual `*.op.ts` fixtures
+ * (`examples/gitlab-aws-alb-infra/ops/alb-deploy.op.ts`, see
+ * `./discover.test.ts`) so Op-name validation exercises the real discovery
+ * path rather than a stub. Discovery starts in that example: since #2527 the
+ * walk from the git root stops at child projects, so the repo root finds none.
  */
 
 import { describe, test, expect, vi } from "vitest";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
 import type { DiscoveredOp } from "./discover";
 import type { OpConfig } from "./types";
@@ -34,6 +38,9 @@ vi.mock("@intentius/chant-lexicon-gitlab", () => ({
   },
 }));
 
+/** The example project that holds `alb-deploy.op.ts`. */
+const ALB_INFRA = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../examples/gitlab-aws-alb-infra");
+
 describe("generateOpsPipeline", () => {
   test("errors when the target lexicon has no generateOpPipeline", async () => {
     const result = await generateOpsPipeline([{ name: "alb-deploy", schedule: "0 6 * * *" }], "aws");
@@ -45,6 +52,8 @@ describe("generateOpsPipeline", () => {
     const result = await generateOpsPipeline(
       [{ name: "definitely-not-a-real-op", schedule: "0 6 * * *" }],
       "gitlab",
+      undefined,
+      ALB_INFRA,
     );
     expect(result.success).toBe(false);
     expect(result.error).toMatch(/Unknown Op\(s\): definitely-not-a-real-op/);
@@ -52,7 +61,7 @@ describe("generateOpsPipeline", () => {
 
   test("validates every named Op and delegates to the lexicon plugin", async () => {
     const specs: ScheduledOpSpec[] = [{ name: "alb-deploy", schedule: "0 6 * * *", findingMode: "issue" }];
-    const result = await generateOpsPipeline(specs, "gitlab");
+    const result = await generateOpsPipeline(specs, "gitlab", undefined, ALB_INFRA);
     expect(result.success).toBe(true);
     expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
     expect(result.jobs).toEqual([
@@ -66,7 +75,7 @@ describe("generateOpsPipeline", () => {
   // `PipelineAuditOp`, `ReconcileOp`) only ever sets `schedule`.
   test("a legacy `{ schedule }` spec with no `trigger` round-trips unchanged", async () => {
     const specs: ScheduledOpSpec[] = [{ name: "alb-deploy", schedule: "0 6 * * *" }];
-    const result = await generateOpsPipeline(specs, "gitlab");
+    const result = await generateOpsPipeline(specs, "gitlab", undefined, ALB_INFRA);
     expect(result.success).toBe(true);
     expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
     expect(result.jobs).toEqual([

package/src/op/generate-pipeline.ts

@@ -17,6 +17,7 @@
  */
 
 import { discoverOps, type DiscoveredOp } from "./discover";
+import { lexiconModulePath } from "../lexicon-module";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -36,7 +37,7 @@ import {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

package/src/op/runtimes/local.ts

@@ -18,6 +18,7 @@
  * answers.
  */
 
+import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { loadActivities, loadProfiles } from "../activity-registry";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
@@ -129,7 +130,7 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
       // unreadable config just yields the base activities.
       let lexicons: string[] = [];
       try {
-        lexicons = (await loadChantConfig(projectPath)).config.lexicons ?? [];
+        lexicons = lexiconNames((await loadChantConfig(projectPath)).config.lexicons ?? []);
       } catch {
         // No/invalid chant.config — base activities only.
       }

package/src/project-root.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import { findProjectConfig, findProjectRoot } from "./project-root";
+import { findProjectConfig, findProjectRoot, findWorkspaceRoot } from "./project-root";
 
 // Every test builds its own isolated directory tree under a fresh tmpdir —
 // never reused across tests, and never anywhere near the real repo's own
@@ -103,3 +103,68 @@ describe("findProjectConfig / findProjectRoot (chant #1117)", () => {
     expect(result.configPath).toBe(join(projectRoot, "chant.config.ts"));
   });
 });
+
+describe("findWorkspaceRoot (chant #2534)", () => {
+  const declare = (dir: string, name = "chant.workspace.json") => {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, name), "{}");
+  };
+
+  test("walks up to the nearest declaration, and never looks at chant.config", () => {
+    mkdirSync(join(root, ".git"));
+    declare(root);
+    const deep = join(root, "lexicons", "aws", "examples", "one");
+    mkdirSync(deep, { recursive: true });
+    writeFileSync(join(root, "lexicons", "aws", "package.json"), "{}");
+    writeFileSync(join(deep, "chant.config.ts"), "export default {};");
+    expect(findWorkspaceRoot(deep)).toEqual({ dir: root, file: join(root, "chant.workspace.json") });
+    // findProjectConfig is unchanged: it still stops at the project's own config.
+    expect(findProjectConfig(deep).dir).toBe(deep);
+  });
+
+  test("the nearest declaration wins, so a nested workspace finds itself", () => {
+    mkdirSync(join(root, ".git"));
+    declare(root);
+    const inner = join(root, "vendor", "kit");
+    declare(inner, "chant.workspace.jsonc");
+    mkdirSync(join(inner, "src"));
+    expect(findWorkspaceRoot(join(inner, "src"))).toEqual({ dir: inner, file: join(inner, "chant.workspace.jsonc") });
+  });
+
+  test("stops at the git root after checking it", () => {
+    declare(root);
+    const repo = join(root, "repo");
+    mkdirSync(join(repo, ".git"), { recursive: true });
+    mkdirSync(join(repo, "src"));
+    expect(findWorkspaceRoot(join(repo, "src"))).toBeUndefined();
+    declare(repo);
+    expect(findWorkspaceRoot(join(repo, "src"))?.dir).toBe(repo);
+  });
+
+  test("a .git file (a worktree or submodule) is a git root too", () => {
+    declare(root);
+    const repo = join(root, "wt");
+    mkdirSync(repo);
+    writeFileSync(join(repo, ".git"), "gitdir: /elsewhere\n");
+    expect(findWorkspaceRoot(repo)).toBeUndefined();
+  });
+
+  test("outside a git repository only the start directory is checked", () => {
+    declare(root);
+    const sub = join(root, "sub");
+    mkdirSync(sub);
+    expect(findWorkspaceRoot(sub)).toBeUndefined();
+    expect(findWorkspaceRoot(root)?.dir).toBe(root);
+  });
+
+  test("both names present is reported, not thrown", () => {
+    mkdirSync(join(root, ".git"));
+    declare(root);
+    declare(root, "chant.workspace.jsonc");
+    expect(findWorkspaceRoot(root)).toEqual({
+      dir: root,
+      file: join(root, "chant.workspace.json"),
+      conflicting: join(root, "chant.workspace.jsonc"),
+    });
+  });
+});

package/src/project-root.ts

@@ -76,3 +76,51 @@ export function findProjectConfig(startDir: string): ProjectConfigSearch {
 export function findProjectRoot(startDir: string): string {
   return findProjectConfig(startDir).dir;
 }
+
+/** The two names a workspace declaration may have (#2524 D1). */
+export const WORKSPACE_DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"] as const;
+
+/** Where {@link findWorkspaceRoot} found a declaration. */
+export interface WorkspaceRootSearch {
+  /** The directory holding the declaration. */
+  dir: string;
+  /** Absolute path of the declaration file. When both names are present this is the `.json` one. */
+  file: string;
+  /**
+   * Absolute path of the `.jsonc` file when `.json` is also there. Having both
+   * is an error, which the reader reports; the walk itself never throws.
+   */
+  conflicting?: string;
+}
+
+/**
+ * Walk up from `startDir` (inclusive) to the nearest `chant.workspace.json` or
+ * `chant.workspace.jsonc` (#2524 D1). The walk stops at the git root, the first
+ * directory holding `.git`, after checking it. Outside a git repository only
+ * `startDir` itself is checked, so a stray declaration in an unrelated
+ * ancestor is never picked up.
+ *
+ * It only tests whether files exist and loads nothing else, so a level-0
+ * command can afford to call it. {@link findProjectConfig} is unchanged and
+ * never looks at a declaration.
+ */
+export function findWorkspaceRoot(startDir: string): WorkspaceRootSearch | undefined {
+  const start = resolve(startDir);
+  let top: string | undefined;
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) {
+      top = dir;
+      break;
+    }
+    if (dirname(dir) === dir) break;
+  }
+  for (let dir = start; ; dir = dirname(dir)) {
+    const [json, jsonc] = WORKSPACE_DECLARATION_FILES.map((name) => join(dir, name));
+    const hasJson = existsSync(json);
+    const hasJsonc = existsSync(jsonc);
+    if (hasJson && hasJsonc) return { dir, file: json, conflicting: jsonc };
+    if (hasJson) return { dir, file: json };
+    if (hasJsonc) return { dir, file: jsonc };
+    if (top === undefined || dir === top || dirname(dir) === dir) return undefined;
+  }
+}