@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/flyway-layout.ts

@@ -0,0 +1,337 @@
+/**
+ * A Flyway project's layout, read from a workspace tree (#4400): its
+ * `flyway.toml` or `flyway.conf`, the locations it names, read recursively,
+ * and the placeholders it substitutes.
+ *
+ * This is the layout reading of sql-yodeler's `src/check/flyway.ts` (#250),
+ * moved here so the workspace kind and `yodel check` share one reader. It
+ * works on a {@link WorkspaceTree} and tree-relative paths instead of the
+ * file system, and it never runs Flyway or connects to a database.
+ *
+ * The configuration is the first `flyway.toml`, else `flyway.conf`, found in
+ * the directory checked or a directory above it, up to the tree's root. Its
+ * locations are read relative to the file's own directory:
+ *
+ *   filesystem:<path>   that directory
+ *   classpath:<path>    src/main/resources/<path> (and, for code
+ *   <path>              migrations, src/main/java/<path> and src/main/kotlin/<path>)
+ *
+ * With no configuration, or one that names no location, the directory
+ * checked is the one location. A location outside the tree is reported by
+ * {@link FlywayConfig.outside}, not read. A Java or Kotlin migration in a
+ * location is not SQL and is reported by {@link codeMigrations}.
+ *
+ * Placeholders are `${name}` (the prefix and suffix are configurable), from
+ * `flyway.placeholders.<name>` (conf) or `[flyway.placeholders]` (toml), plus
+ * Flyway's own: `flyway:defaultSchema`, `flyway:user`, `flyway:database`,
+ * `flyway:timestamp`, `flyway:filename`, `flyway:workingDirectory`,
+ * `flyway:table` and `flyway:environment`. {@link substitute} replaces them
+ * for a replay; the reader that lists migrations leaves the text as it is.
+ */
+
+import { posix } from "node:path";
+import { joinPath, type WorkspaceTree } from "./tree";
+
+export interface FlywayConfig {
+  /** The configuration file, tree-relative; undefined with none. */
+  file?: string;
+  /** Where file names are relative to: the configuration's directory, else the directory checked. Tree-relative. */
+  root: string;
+  /** The SQL locations, tree-relative directories. */
+  locations: string[];
+  /** Directories code migrations (Java, Kotlin) of a classpath location would be in. */
+  codeLocations: string[];
+  /** Locations the configuration names that lie outside the tree, as written. */
+  outside: string[];
+  placeholders: Record<string, string>;
+  placeholderPrefix: string;
+  placeholderSuffix: string;
+  placeholderReplacement: boolean;
+  sqlMigrationPrefix: string;
+  repeatableSqlMigrationPrefix: string;
+  baselineMigrationPrefix: string;
+  undoSqlMigrationPrefix: string;
+  sqlMigrationSeparator: string;
+  sqlMigrationSuffixes: string[];
+  defaultSchema?: string;
+  user?: string;
+  database?: string;
+  /** The JDBC URL, when the configuration has one. */
+  url?: string;
+  /** The dialect the URL names: `postgres` or `clickhouse`; undefined for another or none. */
+  dialect?: string;
+  table: string;
+  environment?: string;
+}
+
+/** The first `flyway.toml`, else `flyway.conf`, in `dir` or a directory above it, up to the tree's root. */
+export function findFlywayConfig(tree: WorkspaceTree, dir: string): string | undefined {
+  let at = dir;
+  for (;;) {
+    for (const name of ["flyway.toml", "flyway.conf"]) {
+      const f = joinPath(at, name);
+      if (tree.stat(f) === "file") return f;
+    }
+    if (at === "" || at === ".") return undefined;
+    at = posix.dirname(at) === "." ? "" : posix.dirname(at);
+  }
+}
+
+type Values = Record<string, string | string[] | boolean>;
+
+/** Java-properties `flyway.*` keys, without the `flyway.` prefix. */
+export function parseFlywayConf(text: string): Values {
+  const out: Values = {};
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i] ?? "";
+    while (/\\$/.test(line) && i + 1 < lines.length) line = line.slice(0, -1) + (lines[++i] ?? "").trimStart();
+    const t = line.trim();
+    if (t === "" || t.startsWith("#") || t.startsWith("!")) continue;
+    const m = /^([^=:\s]+)\s*[=:]\s*(.*)$/.exec(t);
+    if (!m) continue;
+    const key = m[1] ?? "";
+    if (!key.startsWith("flyway.")) continue;
+    out[key.slice("flyway.".length)] = (m[2] ?? "").trim();
+  }
+  return out;
+}
+
+/** A TOML document, as far as Flyway's configuration uses it: tables, strings, arrays of strings, booleans and numbers. */
+export function parseToml(text: string): Record<string, Values> {
+  const tables: Record<string, Values> = { "": {} };
+  let current = "";
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const t = stripComment(lines[i] ?? "").trim();
+    if (t === "") continue;
+    const table = /^\[\s*([^\]]+?)\s*\]$/.exec(t);
+    if (table) {
+      current = (table[1] ?? "").split(".").map((k) => unquote(k.trim())).join(".");
+      tables[current] ??= {};
+      continue;
+    }
+    const kv = /^("[^"]*"|'[^']*'|[A-Za-z0-9_.:-]+)\s*=\s*(.*)$/.exec(t);
+    if (!kv) continue;
+    let raw = kv[2] ?? "";
+    // A multi-line array runs to its closing bracket.
+    while (raw.trimStart().startsWith("[") && !balanced(raw) && i + 1 < lines.length) raw += ` ${stripComment(lines[++i] ?? "").trim()}`;
+    const path = unquote(kv[1] ?? "").split(".");
+    const key = path.pop() ?? "";
+    const where = [current, ...path].filter(Boolean).join(".");
+    tables[where] ??= {};
+    tables[where][key] = tomlValue(raw.trim());
+  }
+  return tables;
+}
+
+function stripComment(line: string): string {
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === "\\" && quote === '"') i++;
+      else if (c === quote) quote = undefined;
+    } else if (c === '"' || c === "'") quote = c;
+    else if (c === "#") return line.slice(0, i);
+  }
+  return line;
+}
+
+const balanced = (s: string) => (s.match(/\[/g) ?? []).length <= (s.match(/\]/g) ?? []).length;
+
+function unquote(s: string): string {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  return s;
+}
+
+function tomlValue(raw: string): string | string[] | boolean {
+  if (raw === "true" || raw === "false") return raw === "true";
+  if (raw.startsWith("[")) {
+    const inner = raw.replace(/^\[/, "").replace(/\]\s*$/, "");
+    return (inner.match(/"(?:[^"\\]|\\.)*"|'[^']*'|[^,\s]+/g) ?? []).map((v) => unquote(v.trim())).filter((v) => v !== "");
+  }
+  return unquote(raw);
+}
+
+const list = (v: string | string[] | boolean | undefined): string[] | undefined =>
+  v === undefined || typeof v === "boolean" ? undefined : Array.isArray(v) ? v : v.split(",").map((s) => s.trim()).filter(Boolean);
+const str = (v: string | string[] | boolean | undefined): string | undefined => (typeof v === "string" ? v : Array.isArray(v) ? v.join(",") : undefined);
+
+/** The database name a JDBC URL names: the path after the host. */
+function databaseOf(url: string | undefined): string | undefined {
+  const m = url === undefined ? null : /^jdbc:[a-z0-9]+:\/\/[^/]+\/([^?;]+)/i.exec(url);
+  return m?.[1] ?? undefined;
+}
+
+/** The dialect a JDBC URL names. */
+function dialectOf(url: string | undefined): string | undefined {
+  const m = url === undefined ? null : /^jdbc:([a-z0-9]+):/i.exec(url);
+  const driver = m?.[1]?.toLowerCase();
+  return driver === "postgresql" ? "postgres" : driver === "clickhouse" ? "clickhouse" : undefined;
+}
+
+/** The configuration `file` holds, or the defaults with `dir` as the one location when there is none. */
+export function readFlywayConfig(tree: WorkspaceTree, file: string | undefined, dir: string): FlywayConfig {
+  let values: Values = {};
+  let placeholders: Record<string, string> = {};
+  if (file !== undefined) {
+    const text = tree.read(file);
+    if (file.endsWith(".toml")) {
+      const t = parseToml(text);
+      const flyway = t.flyway ?? {};
+      const name = str(flyway.environment) ?? "default";
+      const env = t[`environments.${name}`] ?? {};
+      values = { ...flyway, ...(t[`environments.${name}.flyway`] ?? {}), ...(env.url !== undefined ? { url: env.url } : {}), ...(env.user !== undefined ? { user: env.user } : {}), ...(env.schemas !== undefined ? { schemas: env.schemas } : {}) };
+      if (str(flyway.environment) !== undefined) values.environment = name;
+      placeholders = Object.fromEntries(Object.entries({ ...(t["flyway.placeholders"] ?? {}), ...(t[`environments.${name}.flyway.placeholders`] ?? {}) }).map(([k, v]) => [k, str(v) ?? String(v)]));
+    } else {
+      values = parseFlywayConf(text);
+      placeholders = Object.fromEntries(Object.entries(values).flatMap(([k, v]) => (k.startsWith("placeholders.") ? [[k.slice("placeholders.".length), str(v) ?? ""]] : [])));
+    }
+  }
+  const root = file === undefined ? dir : posix.dirname(file) === "." ? "" : posix.dirname(file);
+  const named = list(values.locations) ?? [];
+  const locations: string[] = [];
+  const codeLocations: string[] = [];
+  const outside: string[] = [];
+  const inside = (...parts: string[]): string | undefined => {
+    const p = posix.normalize(joinPath(...parts)) || ".";
+    if (p === ".." || p.startsWith("../") || posix.isAbsolute(p)) return undefined;
+    return p === "." ? "" : p;
+  };
+  for (const l of named) {
+    const m = /^(filesystem|classpath):(.*)$/.exec(l);
+    const kind = m?.[1] ?? "classpath";
+    const raw = m?.[2] ?? l;
+    if (kind === "filesystem") {
+      const at = posix.isAbsolute(raw) ? undefined : inside(root, raw);
+      if (at === undefined) outside.push(l);
+      else locations.push(at);
+    } else {
+      const path = raw.replace(/^\/+/, "");
+      const res = inside(root, "src/main/resources", path);
+      if (res === undefined) outside.push(l);
+      else {
+        locations.push(res);
+        for (const lang of ["java", "kotlin"]) {
+          const c = inside(root, "src/main", lang, path);
+          if (c !== undefined) codeLocations.push(c);
+        }
+      }
+    }
+  }
+  if (named.length === 0) locations.push(dir);
+  const schemas = list(values.schemas);
+  const replacement = values.placeholderReplacement;
+  const defaultSchema = str(values.defaultSchema) ?? schemas?.[0];
+  const user = str(values.user);
+  const url = str(values.url);
+  const database = databaseOf(url);
+  const dialect = dialectOf(url);
+  const environment = str(values.environment);
+  return {
+    ...(file !== undefined ? { file } : {}),
+    root,
+    locations,
+    codeLocations,
+    outside,
+    placeholders,
+    placeholderPrefix: str(values.placeholderPrefix) ?? "${",
+    placeholderSuffix: str(values.placeholderSuffix) ?? "}",
+    placeholderReplacement: !(replacement === false || replacement === "false"),
+    sqlMigrationPrefix: str(values.sqlMigrationPrefix) ?? "V",
+    repeatableSqlMigrationPrefix: str(values.repeatableSqlMigrationPrefix) ?? "R",
+    baselineMigrationPrefix: str(values.baselineMigrationPrefix) ?? "B",
+    undoSqlMigrationPrefix: str(values.undoSqlMigrationPrefix) ?? "U",
+    sqlMigrationSeparator: str(values.sqlMigrationSeparator) ?? "__",
+    sqlMigrationSuffixes: list(values.sqlMigrationSuffixes) ?? [".sql"],
+    ...(defaultSchema !== undefined ? { defaultSchema } : {}),
+    ...(user !== undefined ? { user } : {}),
+    ...(database !== undefined ? { database } : {}),
+    ...(url !== undefined ? { url } : {}),
+    ...(dialect !== undefined ? { dialect } : {}),
+    table: str(values.table) ?? "flyway_schema_history",
+    ...(environment !== undefined ? { environment } : {}),
+  };
+}
+
+/** Every file under `dir`, recursively, tree-relative, sorted; none when it does not exist. */
+export function walk(tree: WorkspaceTree, dir: string): string[] {
+  const entries = tree.list(dir);
+  if (!entries) return [];
+  const out: string[] = [];
+  for (const e of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+    const p = joinPath(dir, e.name);
+    if (e.type === "dir") out.push(...walk(tree, p));
+    else out.push(p);
+  }
+  return out;
+}
+
+const base = (f: string): string => posix.basename(f);
+
+/** A Flyway SQL callback (`beforeMigrate.sql`, `afterEachMigrate__notify.sql`, ...): run around a migrate, not a migration. */
+export const isCallback = (file: string): boolean => /^(before|after)[A-Z][A-Za-z]*(__.*)?\.[A-Za-z]+$/.test(base(file));
+
+/** The code migrations (Java, Kotlin) in `config`'s locations, relative to the tree. */
+export function codeMigrations(tree: WorkspaceTree, config: FlywayConfig): string[] {
+  const code = /\.(java|kt|class)$/;
+  const prefixes = [config.sqlMigrationPrefix, config.repeatableSqlMigrationPrefix, config.baselineMigrationPrefix].filter(Boolean);
+  const migration = (f: string) => code.test(f) && prefixes.some((p) => base(f).startsWith(p)) && base(f).includes(config.sqlMigrationSeparator);
+  return [...new Set([...config.locations, ...config.codeLocations])].flatMap((d) => walk(tree, d)).filter(migration);
+}
+
+/** The values Flyway gives its own placeholders, for `file`. */
+function builtins(config: FlywayConfig, file: string, fallback: { defaultSchema?: string | undefined }): Record<string, string | undefined> {
+  return {
+    "flyway:defaultSchema": config.defaultSchema ?? fallback.defaultSchema,
+    "flyway:user": config.user,
+    "flyway:database": config.database,
+    "flyway:timestamp": new Date().toISOString().replace("T", " ").replace(/\..*$/, ""),
+    "flyway:filename": base(file),
+    "flyway:workingDirectory": process.cwd(),
+    "flyway:table": config.table,
+    "flyway:environment": config.environment,
+  };
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** A placeholder with no value; `file` is as the caller passed it, `line` is from 1. */
+export class FlywayPlaceholderError extends Error {
+  constructor(
+    readonly file: string,
+    readonly line: number,
+    readonly placeholder: string,
+    readonly name: string,
+    readonly where: string,
+  ) {
+    super(`${file}:${String(line)}: no value for the placeholder ${placeholder}; set it in ${where} (flyway.placeholders.${name} in flyway.conf, [flyway.placeholders] in flyway.toml)`);
+  }
+}
+
+/**
+ * `text` with its placeholders replaced, line by line so line numbers hold.
+ * A placeholder with no value throws a {@link FlywayPlaceholderError} naming
+ * `file` and the line, as Flyway's own run would fail.
+ */
+export function substitute(text: string, file: string, config: FlywayConfig, fallback: { defaultSchema?: string | undefined } = {}): string {
+  if (!config.placeholderReplacement) return text;
+  const values: Record<string, string | undefined> = { ...builtins(config, file, fallback), ...config.placeholders };
+  const lower = new Map(Object.entries(values).map(([k, v]) => [k.toLowerCase(), v]));
+  const pattern = new RegExp(`${escape(config.placeholderPrefix)}([A-Za-z0-9_.:-]+)${escape(config.placeholderSuffix)}`, "g");
+  return text
+    .split("\n")
+    .map((line, i) =>
+      line.replace(pattern, (whole, name: string) => {
+        const v = values[name] ?? lower.get(name.toLowerCase());
+        if (v === undefined) {
+          const where = config.file === undefined ? "a flyway.toml or flyway.conf beside the migrations" : config.file;
+          throw new FlywayPlaceholderError(file, i + 1, whole, name, where);
+        }
+        return v;
+      }),
+    )
+    .join("\n");
+}

package/src/workspace/graph-cache.ts

@@ -368,9 +368,7 @@ export function splitCached(plan: MemberPlan, args: ParsedArgs, cache: GraphCach
       // A member read through a generated reader project (#2874) is also keyed on
       // the kind's graph block and the version of the package that reads it.
       const reader = unit.reader ? readerStamp(unit.reader) : "";
-      const abs = unit.dir === "." ? plan.workspace.root : join(plan.workspace.root, ...unit.dir.split("/"));
-      const revision = at ? { commit: at, dir: unit.dir } : undefined;
-      const stamp = memberStamp(abs, unit.exclude, revision);
+      const { abs, revision, stamp } = unitStamp(plan, unit, at);
       if (!stamp) continue;
       stamps.set(unit.id, stamp.value);
       const key = cacheKey({ member: unit.member, dir: unit.dir, stamp: stamp.value, toolchain: `${tool}\0${reader}`, argv, env });
@@ -385,6 +383,32 @@ export function splitCached(plan: MemberPlan, args: ParsedArgs, cache: GraphCach
   return { hits, stamps, pending, started };
 }
 
+/** One unit's stamp, and what it was taken over: the member's directory on disk, and the commit for `--at`. */
+function unitStamp(plan: MemberPlan, unit: RunUnit, at: string | null): { abs: string; revision?: { commit: string; dir: string }; stamp: Stamp | undefined } {
+  const abs = unit.dir === "." ? plan.workspace.root : join(plan.workspace.root, ...unit.dir.split("/"));
+  const revision = at ? { commit: at, dir: unit.dir } : undefined;
+  return { abs, ...(revision ? { revision } : {}), stamp: memberStamp(abs, unit.exclude, revision) };
+}
+
+/**
+ * Every member unit's stamp, by unit id, by the rule {@link splitCached} keys
+ * the cache on (ws-059), with no cache read. A read that is never cached, such
+ * as `chant workspace search` (#4374), still stamps its members this way, so a
+ * reader compares stamps across documents with one meaning. A unit whose stamp
+ * can't be taken is left out.
+ */
+export function planStamps(plan: MemberPlan, at: string | null): Map<string, string> {
+  const stamps = new Map<string, string>();
+  for (const group of plan.groups) {
+    for (const unit of group.units) {
+      if (unit.group) continue;
+      const { stamp } = unitStamp(plan, unit, at);
+      if (stamp) stamps.set(unit.id, stamp.value);
+    }
+  }
+  return stamps;
+}
+
 /** The plan without the units in `ids`; a toolchain left with no units is dropped. */
 export function withoutUnits(plan: MemberPlan, ids: ReadonlySet<string>): MemberPlan {
   if (ids.size === 0) return plan;

package/src/workspace/graph-cli.ts

@@ -31,11 +31,14 @@ import { dirname, join, resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext, ParsedArgs } from "../cli/registry";
 import { graphBox, plantability, type Plantable } from "./box-factory";
-import { composeWorkspaceGraph, readMemberIr, type ComposedMember, type ComposeInput, type WorkspaceGraph } from "./compose-graph";
-import { openGraphCache, splitCached, storeReads, withoutUnits } from "./graph-cache";
-import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type ErrorLocation } from "./declaration";
-import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
-import { loadKindRegistry } from "./kinds";
+import { composedId, composeWorkspaceGraph, readMemberIr, type ComposedMember, type ComposeInput, type WorkspaceGraph } from "./compose-graph";
+import { isViewDocument, prefixView } from "../capabilities/view";
+import { refusedCapabilityView } from "./nested-graph";
+import { openGraphCache, planStamps, splitCached, storeReads, withoutUnits } from "./graph-cache";
+import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration, type ErrorLocation, type RepoRef } from "./declaration";
+import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberArgv, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
+import { loadKindRegistry, REPO_KIND, type KindRegistry } from "./kinds";
+import { repoIdentity } from "./repo-ref";
 import { readKindLinks } from "./kind-link-readers";
 import { prepareKindReaders, type PreparedReaders } from "./kind-readers";
 import { recordLinkRows } from "./record-assets";
@@ -168,6 +171,7 @@ function compose(
   only: string[] | undefined,
   declarationMembers: { name: string; dir: string; kind: string }[],
   live = false,
+  capabilityView = false,
 ): { inputs: ComposeInput[]; failed: boolean } {
   // A member that ran was read live when --live was given, and says when (#2875).
   const read = (member: ComposedMember, r: UnitResult): ComposedMember => {
@@ -203,6 +207,12 @@ function compose(
     }
     const member = read(memberStatus(m.name, m.dir, m.kind, "composed", null, r.chant), r);
     member.irVersion = ir.irVersion;
+    // The member's own capability view (#4378), with composed ids; null when its chant printed none.
+    if (capabilityView) {
+      const view = (ir.ir as { capabilityView?: unknown }).capabilityView;
+      member.capabilityView = isViewDocument(view) ? prefixView(view, composedId(m.name, "")) : null;
+    }
+    delete (ir.ir as { capabilityView?: unknown }).capabilityView;
     inputs.push({ member, ir: ir.ir });
   }
   return { inputs, failed };
@@ -212,58 +222,125 @@ function compose(
 export function planGraph(query: GraphQuery): MemberPlan {
   const located = locateWorkspace(query.cwd, query.at);
   const declaration = readDeclaration(located.tree, "", { rootChant: true });
-  const kinds = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
-  return planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds });
+  const { registry: kinds, problems } = loadKindRegistry(declaration.pins, located.rootOnDisk);
+  return planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds, kindProblems: problems.map((p) => p.message) });
 }
 
-/** Read and compose the graph, and build the document. Never throws a {@link WorkspaceReadError}. */
-export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
-  const head: Head = { $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: GRAPH_CONTRACT_VERSION, chant: readerVersion() };
+/** The members of a workspace read, each read under its own toolchain: what graph and search compose (#4374). */
+export interface MemberReads {
+  located: LocatedWorkspace;
+  declaration: Declaration;
+  kinds: KindRegistry;
+  /** The plan the members ran from. */
+  plan: MemberPlan;
+  /** Each member's answer, the cache's included, in no particular order. */
+  results: UnitResult[];
+  /** The members the cache answered. */
+  served: ReadonlySet<string>;
+  /** Each member's stamp, by unit id (ws-059). */
+  stamps: ReadonlyMap<string, string>;
+  /** With {@link GraphQuery.components}: each member's component graph run. */
+  components?: UnitResult[];
+}
+
+export interface MemberReadOptions {
+  /** The command line each member runs; `chant graph --format ir` and the verb's flags by default. */
+  argvFor?: MemberArgv;
+  /**
+   * Answer members from the per-member cache and store what they print
+   * (ws-059). Only a read whose output is a graph IR may be cached. When
+   * off, every member is still stamped by the same rule.
+   */
+  cache: boolean;
+}
+
+/**
+ * Plan the members a workspace read covers, run each under its own toolchain
+ * (ws-021) at the revision asked for, and return what they printed. One
+ * fan-out, shared by `chant workspace graph` and `chant workspace search`
+ * (#4374): `--at` exports the tree once, a member of a package's kind runs in
+ * its reader project, and every member is stamped by the rule of ws-059. The
+ * exported tree and the reader projects are removed before this returns.
+ * Throws a {@link WorkspaceReadError} when the declaration can't be read.
+ */
+export async function readMembers(query: GraphQuery, options: MemberReadOptions): Promise<MemberReads> {
   let exported: string | undefined;
   let readers: PreparedReaders | undefined;
-  if (query.args?.live && query.at !== undefined) {
-    return { doc: { ...head, error: { code: "live-at-revision", message: LIVE_AT_REVISION, location: null } }, failed: true };
-  }
   try {
     const located = locateWorkspace(query.cwd, query.at);
     const declaration = readDeclaration(located.tree, "", { rootChant: true });
     // Kinds are read before planning: a package kind with a graph block runs (#2874).
-    const kinds = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
-    let plan = planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds });
+    const { registry: kinds, problems } = loadKindRegistry(declaration.pins, located.rootOnDisk);
+    const kindProblems = problems.map((p) => p.message);
+    let plan = planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds, kindProblems });
     const args = (query.args ?? {}) as ParsedArgs;
     // Members whose last source read still stands are answered from the cache (#2876).
     // A composites read runs every member's component graph as well, so it reads everything.
-    const cache = query.noCache || query.components ? undefined : openGraphCache(located.rootOnDisk);
+    const cache = !options.cache || query.noCache || query.components ? undefined : openGraphCache(located.rootOnDisk);
     const split = cache ? splitCached(plan, args, cache, located.at) : undefined;
+    const stamps = split?.stamps ?? (options.cache ? new Map<string, string>() : planStamps(plan, located.at));
     const served = new Set(split?.hits.map((h) => h.id));
     if (located.at !== null && withoutUnits(plan, served).groups.length > 0) {
       exported = exportRevision(located, withoutUnits(plan, served).groups.flatMap((g) => g.units.map((u) => u.dir)));
-      plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: workingTree(exported), kinds });
+      plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: workingTree(exported), kinds, kindProblems });
     }
     // Only the members that run get a reader project; a served member needs none.
     const toRun = withoutUnits(plan, served);
     readers = prepareKindReaders(toRun, exported ?? located.rootOnDisk);
-    const [ran, components] = await Promise.all([
-      executePlan(toRun, args),
+    const [first, components] = await Promise.all([
+      executePlan(toRun, args, options.argvFor),
       query.components ? executePlan(plan, args, () => componentGraphArgv(args)) : Promise.resolve(undefined),
     ]);
+    const ran = args.capabilityView && !options.argvFor ? await withoutViewWhereRefused(toRun, args, first) : first;
     if (cache && split) storeReads(split, ran, cache);
     const results = [...(split?.hits ?? []), ...ran];
     if (query.inTree) await query.inTree(exported ?? located.rootOnDisk, declaration.members.filter((m) => !query.members?.length || query.members.includes(m.name)));
     for (const r of components ?? []) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     for (const r of results) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
-    const { inputs, failed } = compose(plan, results, query.members, declaration.members, !!args.live);
+    return { located, declaration, kinds, plan, results, served, stamps, ...(components ? { components } : {}) };
+  } finally {
+    readers?.cleanup();
+    if (exported) rmSync(dirname(exported), { recursive: true, force: true });
+  }
+}
+
+/**
+ * A member's chant from before #4378 refuses `--capability-view` as a flag
+ * it doesn't know. Read those members again without it, so the graph still
+ * composes them; they carry `capabilityView: null`, which a capability search
+ * reports as `member-chant-too-old`.
+ */
+async function withoutViewWhereRefused(plan: MemberPlan, args: ParsedArgs, results: UnitResult[]): Promise<UnitResult[]> {
+  const refused = new Set(results.filter((r) => r.exitCode !== 0 && refusedCapabilityView(r.stderr)).map((r) => r.id));
+  if (refused.size === 0) return results;
+  const others = new Set(results.filter((r) => !refused.has(r.id)).map((r) => r.id));
+  const again = await executePlan(withoutUnits(plan, others), { ...args, capabilityView: false });
+  const byId = new Map(again.map((r) => [r.id, r]));
+  return results.map((r) => byId.get(r.id) ?? r);
+}
+
+/** Read and compose the graph, and build the document. Never throws a {@link WorkspaceReadError}. */
+export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
+  const head: Head = { $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: GRAPH_CONTRACT_VERSION, chant: readerVersion() };
+  if (query.args?.live && query.at !== undefined) {
+    return { doc: { ...head, error: { code: "live-at-revision", message: LIVE_AT_REVISION, location: null } }, failed: true };
+  }
+  try {
+    const { located, declaration, kinds, plan, results, served, stamps, components } = await readMembers(query, { cache: true });
+    const args = (query.args ?? {}) as ParsedArgs;
+    const { inputs, failed } = compose(plan, results, query.members, declaration.members, !!args.live, !!args.capabilityView);
     for (const { member } of inputs) {
       if (member.status !== "composed") continue;
       member.cached = served.has(member.name);
-      member.stamp = split?.stamps.get(member.name) ?? null;
+      member.stamp = stamps.get(member.name) ?? null;
     }
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
     // A kind's link reader (#3932) reads the member's files in the tree read, as check does.
-    const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds, read: readKindLinks(declaration, located.tree, kinds) });
+    const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root, repo: repoIdentity(located.rootOnDisk) }, inputs, { declaration, kinds, read: readKindLinks(declaration, located.tree, kinds) });
     // The box's factory and listing (#3146), from the declaration read, so --at gives them at that revision.
     for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree, declaration.members);
     // Nested workspaces (#2551, ws-071): read-only, through their own chant workspace graph.
+    // Repo members (#3168): another repository's workspace at its pinned revision, read the same way.
     const nestedFailed = await expandNested(graph, declaration.members, query, located.rootOnDisk, located.at);
     let recordsFailed = false;
     if (query.kind !== undefined) {
@@ -285,41 +362,51 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
-  } finally {
-    readers?.cleanup();
-    if (exported) rmSync(dirname(exported), { recursive: true, force: true });
   }
 }
 
 /**
  * Expand every member of kind `workspace` the query covers, read-only (#2551,
- * ws-071). Returns whether one could not be read.
+ * ws-071), and every member of kind `repo` the same way, at its pinned
+ * revision, fetched into the user's cache (#3168). Returns whether one could
+ * not be read.
  */
 async function expandNested(
   graph: WorkspaceGraph,
-  members: readonly { name: string; dir: string; kind: string }[],
+  members: readonly { name: string; dir: string; kind: string; repo: RepoRef | null }[],
   query: GraphQuery,
   rootOnDisk: string,
   at: string | null,
 ): Promise<boolean> {
-  const nested = members.filter((m) => m.kind === "workspace" && (!query.members?.length || query.members.includes(m.name)));
+  const covered = (m: { name: string }) => !query.members?.length || query.members.includes(m.name);
+  const nested = members.filter((m) => (m.kind === "workspace" || (m.kind === REPO_KIND && m.repo !== null)) && covered(m));
   if (nested.length === 0) return false;
   const { foldNested, readNested } = await import("./nested-graph");
+  const { fetchRepoAt } = await import("./repo-ref");
   const reads = await Promise.all(
     nested.map(async (m) => {
+      if (m.repo) {
+        // The other repository at its pinned revision, whatever revision the outer read is at.
+        const fetched = fetchRepoAt(m.repo, rootOnDisk);
+        if (!fetched.ok) return { m, read: null, missing: fetched.message };
+        if (!existsSync(fetched.dir)) return { m, read: null, missing: `${m.repo.url} at ${m.repo.rev} has no directory ${m.repo.workspace}` };
+        return { m, read: await readNested(fetched.dir, query.args ?? {}, m.repo.rev, GRAPH_OUTPUT_SCHEMA_ID, GRAPH_CONTRACT_VERSION, query.reader), missing: null };
+      }
       const abs = join(rootOnDisk, ...m.dir.split("/"));
-      if (!existsSync(abs)) return { m, read: null };
-      return { m, read: await readNested(abs, query.args ?? {}, at, GRAPH_OUTPUT_SCHEMA_ID, GRAPH_CONTRACT_VERSION, query.reader) };
+      if (!existsSync(abs)) return { m, read: null, missing: null };
+      return { m, read: await readNested(abs, query.args ?? {}, at, GRAPH_OUTPUT_SCHEMA_ID, GRAPH_CONTRACT_VERSION, query.reader), missing: null };
     }),
   );
   let failed = false;
-  for (const { m, read } of reads) {
+  for (const { m, read, missing } of reads) {
     const member = graph.members.find((x) => x.name === m.name);
     if (!member) continue;
+    if (m.repo) member.repo = { ...m.repo, read: read?.ok ? (read.doc.workspace.repo ?? null) : null };
     if (!read) {
       failed = true;
       member.status = "failed";
-      member.reason = { code: "dir-missing", message: `the nested workspace's directory ${m.dir} does not exist` };
+      // A repo that can't be fetched is a read that failed; the contract's codes stay as they are.
+      member.reason = missing !== null ? { code: "command-failed", message: missing } : { code: "dir-missing", message: `the nested workspace's directory ${m.dir} does not exist` };
       continue;
     }
     if (read.stderr.trim() && query.onStderr) query.onStderr(read.stderr.endsWith("\n") ? read.stderr : `${read.stderr}\n`);

package/src/workspace/graph-contract.test.ts

@@ -230,7 +230,9 @@ describe("chant workspace graph on the chant repo (#2557)", () => {
     const g = result(doc);
     expectValid(g);
     expect(failed).toBe(false);
-    expect(g.workspace).toEqual({ name: "chant", root: "." });
+    expect(g.workspace).toMatchObject({ name: "chant", root: "." });
+    // The repo identity (#3168) is this checkout's origin, whatever it is here.
+    expect(g.workspace.repo === null || typeof g.workspace.repo === "string").toBe(true);
     expect(g.at).toBeNull();
     expect(g.members.every((m) => m.status === "skipped" && m.reason?.code === "kind-not-run")).toBe(true);
   });
@@ -294,7 +296,7 @@ describe("chant workspace graph on built workspaces", () => {
     for (const at of [undefined, sha]) {
       const g = result((await workspaceGraph({ cwd: join(top, "infra", "api"), at })).doc);
       expectValid(g);
-      expect(g.workspace).toEqual({ name: "acme", root: "infra" });
+      expect(g.workspace).toEqual({ name: "acme", root: "infra", repo: null });
       expect(g.nodes.map((n) => n.id)).toEqual(["api/Queue"]);
     }
   });