@intentius/chant 0.124.46 → 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-cli.ts

@@ -35,9 +35,10 @@ import { composedId, composeWorkspaceGraph, readMemberIr, type ComposedMember, t
 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 } from "./declaration";
+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, type KindRegistry } from "./kinds";
+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";
@@ -335,10 +336,11 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
     }
     // 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) {
@@ -365,33 +367,46 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
 
 /**
  * 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"]);
     }
   });

package/src/workspace/graph.schema.json

@@ -67,6 +67,13 @@
               "type": "string",
               "description": "The declared name. With `at`, it identifies the workspace."
             },
+            "repo": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Added in contract 1 by #3168. The repository the document came from: the URL of the remote origin of the git repository that holds the workspace, with any user name or password removed, or null when there is no origin or the workspace is outside git. With name, root and the revision, it says which repository's workspace a document describes, so a reader that gathers several repositories' documents, such as an org workspace's repo members, tells them apart."
+            },
             "root": {
               "type": "string",
               "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
@@ -287,6 +294,33 @@
           "type": "string",
           "description": "Relative to the workspace root, with / separators; \".\" is the root member."
         },
+        "repo": {
+          "type": "object",
+          "description": "Added in contract 1 by #3168. For a member of kind repo, the other repository's workspace it names: url, the pinned rev and the workspace root inside that repository. Absent for every other kind. A repo member's dir is @repo/<name>, a marker that names no directory of this repository.",
+          "required": [
+            "url",
+            "rev",
+            "workspace"
+          ],
+          "properties": {
+            "url": {
+              "type": "string"
+            },
+            "rev": {
+              "type": "string"
+            },
+            "workspace": {
+              "type": "string"
+            },
+            "read": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The repo identity the other repository's own graph document gave (its workspace.repo), or null when it gave none or the read failed."
+            }
+          }
+        },
         "kind": {
           "type": "string"
         },

package/src/workspace/identity.test.ts

@@ -71,14 +71,26 @@ describe("identity.attribution", () => {
     expect(decl({ attribution: "identified", gates: { ship: { class: "operator" }, rollback: {} } }).identity).toEqual({
       attribution: "identified",
       gates: {
-        ship: { gate: "ship", class: "operator", pointer: "/identity/gates/ship" },
-        rollback: { gate: "rollback", class: null, pointer: "/identity/gates/rollback" },
+        ship: { gate: "ship", class: "operator", quorum: null, pointer: "/identity/gates/ship" },
+        rollback: { gate: "rollback", class: null, quorum: null, pointer: "/identity/gates/rollback" },
       },
     });
     expect(() => decl({ attribution: "verified" })).toThrow();
     expect(() => decl({ gates: { ship: { by: "x" } } })).toThrow();
   });
 
+  test("a gate entry takes a quorum beside its class (#4324)", () => {
+    const rules = [{ targets: ["prod-*"], count: 2, roles: ["platform"] }, { count: 1 }];
+    const gates = decl({ gates: { ship: { class: "operator", quorum: { count: 2 } }, deploy: { quorum: rules } } }).identity!.gates;
+    expect(gates.ship).toEqual({ gate: "ship", class: "operator", quorum: { count: 2 }, pointer: "/identity/gates/ship" });
+    expect(gates.deploy!.quorum).toEqual(rules);
+    // The schema refuses a malformed rule, and the reader refuses notAuthor, which an Op gate can't judge.
+    expect(() => decl({ gates: { ship: { quorum: { count: 0 } } } })).toThrow();
+    expect(() => decl({ gates: { ship: { quorum: [] } } })).toThrow();
+    expect(() => decl({ gates: { ship: { quorum: { count: 1, by: "x" } } } })).toThrow();
+    expect(() => decl({ gates: { ship: { quorum: { count: 1, notAuthor: true } } } })).toThrow(/identity\.gates\.ship\.quorum\.notAuthor is not read here/);
+  });
+
   test("identified refuses a bare name and takes a forge identity or a signer", () => {
     const source = { declaration: decl({ attribution: "identified" }), policy: policyWith([{ principal: "dana@example.test", key: "ssh-ed25519 AAAA" }]) };
     expect(() => refuseUnidentified(source, ["github:alice", "dana@example.test"], "--by")).not.toThrow();

package/src/workspace/intent.ts

@@ -66,6 +66,7 @@ import { isGeneratedPath } from "./generated-files";
 import { entityDecisions, hasTrailer, readCommitJoins, runCommitJoins, type CommitJoins, type IntentCommit, type JoinedEntity, type PluginFinding } from "./intent-joins";
 import { loadKindRegistry } from "./kinds";
 import { resolveLinks, type LinkTableRow } from "./links";
+import { readKindLinks } from "./kind-link-readers";
 import { sourceMemberHandles } from "./member-handles";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
 import type { DecidedIn } from "./record-decided";
@@ -78,6 +79,7 @@ import { memberDirOnDisk, memberSymbolResolvers, type SymbolPluginLoader } from
 import { resolveSymbol, symbolResolverFor, type SymbolResolver } from "./symbols";
 import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { buildTrace, type IntentTrace } from "./intent-trace";
+import { compareDecisionRank, type WhyRelevance } from "./decision-rank";
 import { joinPath, skippedDir, workingTree, type WorkspaceTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
@@ -524,8 +526,7 @@ export interface WhySpan {
   via?: string[];
 }
 
-/** Why a decision is in `why`, most relevant first (#3034). */
-export type WhyRelevance = "carried" | "path" | "contract" | "issue" | "member" | "related";
+export type { WhyRelevance };
 
 export interface WhyDecision {
   decision: string;
@@ -1854,7 +1855,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
         atRevision: located.at !== null,
         ...(query.loadLexicon ? { load: query.loadLexicon as unknown as import("./lexicon-outputs").OutputsPluginLoader } : {}),
       });
-      rows = resolveLinks(declaration, sourceMemberHandles(declaration, located.tree, groups, kindsRegistry, lexiconOutputs)).filter((r) => r.origin === "declared");
+      rows = resolveLinks(declaration, sourceMemberHandles(declaration, located.tree, groups, kindsRegistry, lexiconOutputs), undefined, readKindLinks(declaration, located.tree, kindsRegistry)).filter((r) => r.origin === "declared");
     } catch (err) {
       if (!(err instanceof WorkspaceReadError)) throw err;
     }
@@ -2080,7 +2081,6 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     // The decisions, most relevant first.
     const decisionNodes = [...nodes.values()].filter((n): n is DecisionNode => n.kind === "decision");
     const ownLines = (d: DecisionNode) => who.filter((w) => w.sha !== null && ownWork(joined.get(w.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)).length;
-    const ORDER: WhyRelevance[] = ["carried", "path", "contract", "issue", "member", "related"];
     const ranked = decisionNodes.map((d) => {
       const lines = ownLines(d);
       const carried = lines > 0 || (fileLines === null && touched.some((t) => ownWork(joined.get(t.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)));
@@ -2090,16 +2090,8 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       const specificity = Math.max(0, ...d.constrains.filter((c) => c.granularity === "path").map((c) => c.entry.length));
       return { d, entry: { decision: d.id, relevance, current: d.supersededBy === null, closed: d.closed, lines } satisfies WhyDecision, specificity };
     });
-    ranked.sort(
-      (a, b) =>
-        Number(b.entry.current) - Number(a.entry.current) ||
-        ORDER.indexOf(a.entry.relevance) - ORDER.indexOf(b.entry.relevance) ||
-        b.entry.lines - a.entry.lines ||
-        Number(b.entry.closed) - Number(a.entry.closed) ||
-        b.specificity - a.specificity ||
-        (b.d.decidedIn?.date ?? "").localeCompare(a.d.decidedIn?.date ?? "") ||
-        a.d.id.localeCompare(b.d.id),
-    );
+    const key = (r: (typeof ranked)[number]) => ({ ...r.entry, id: r.d.id, specificity: r.specificity, decidedOn: r.d.decidedIn?.date ?? null });
+    ranked.sort((a, b) => compareDecisionRank(key(a), key(b)));
     const decisions = ranked.map((r) => r.entry);
 
     // The runs that wrote the current lines, most lines first; for a directory, every run in the walk.