@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/checks/ci-branch.test.ts

@@ -0,0 +1,128 @@
+/**
+ * WSP152 (#4325): a member's generated pipeline targets the branch
+ * `ci.branches` routes the member to.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { pipelineTargets, routeDifferences } from "./ci-branch";
+import { REASONS } from "../reason-codes";
+import { servedBranches } from "../ci-branches";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ci-branch-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+/** A generated pull-request pipeline, as chant writes it for a target `branch` (`--branch` is on the record and apply commands only). */
+const pipeline = (branch: string | null, triggers: string[] = branch === null ? [] : [branch]): string =>
+  [
+    "on:",
+    "  pull_request:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "  push:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "jobs:",
+    "  plan:",
+    "    steps:",
+    "      - run: chant ci run plan --in-place --no-push --env prod --gate pr-apply --forge github",
+    "  record:",
+    "    steps:",
+    `      - run: chant ci run record --in-place --env prod --gate pr-apply --forge github${branch === null ? "" : ` --branch "${branch}"`}`,
+    "",
+  ].join("\n");
+
+const PIPELINE_PATH = ".github/workflows/chant-pr.app.prod.yml";
+const record = JSON.stringify({ schema: 1, files: [{ path: PIPELINE_PATH, command: "chant build" }] });
+const workspace = (branches: Record<string, string[]> | undefined, text: string, members = ["app"]): Record<string, string> => ({
+  "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: members.map((name) => ({ name, dir: name, kind: "other", because: name })), ...(branches ? { ci: { branches } } : {}) }),
+  ...Object.fromEntries(members.map((m) => [`${m}/.chant/generated.json`, record])),
+  [PIPELINE_PATH]: text,
+});
+
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP152").map((d) => [d.code, d.entity ?? null, d.severity]);
+
+describe("what a pipeline targets", () => {
+  test("reads the --branch of each record and apply command, and the trigger branch lists", () => {
+    expect(pipelineTargets(pipeline("release"))).toEqual({
+      jobs: [{ line: 12, branch: "release" }],
+      triggers: [
+        { trigger: "push", branches: ["release"] },
+        { trigger: "pull_request", branches: ["release"] },
+      ],
+    });
+    expect(pipelineTargets(pipeline(null)).jobs).toEqual([{ line: 10, branch: null }]);
+    expect(pipelineTargets("not: [valid").triggers).toEqual([]);
+  });
+
+  test("a routed member's pipeline names its route in both places; an unrouted one does not name a reserved branch", () => {
+    const listed = ["release"];
+    expect(routeDifferences(pipelineTargets(pipeline("release")), "release", listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), "release", listed, "app")).toHaveLength(3);
+    expect(routeDifferences(pipelineTargets(pipeline(null)), "release", listed, "app")).toEqual([expect.stringContaining("the default branch")]);
+    expect(routeDifferences(pipelineTargets(pipeline("release", ["release", "main"])), "release", listed, "app")).toHaveLength(2);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), null, listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("release")), null, listed, "app")).toHaveLength(3);
+  });
+});
+
+describe("WSP152 over a workspace", () => {
+  test("a pipeline on the route passes, and a workspace with no ci.branches is not read", async () => {
+    expect(await found(repo(workspace({ release: ["app"] }, pipeline("release"))))).toEqual([]);
+    expect(await found(repo(workspace(undefined, pipeline("anything"))))).toEqual([]);
+  });
+
+  test("a pipeline generated before the route changed fails", async () => {
+    const root = repo(workspace({ release: ["app"] }, pipeline("main")));
+    expect(await found(root)).toEqual([
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+    ]);
+  });
+
+  test("an unrouted member's pipeline may not target a branch ci.branches reserves", async () => {
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("release"))))).toHaveLength(3);
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("main"))))).toEqual([]);
+  });
+
+  test("the code is a documented reason code", () => {
+    expect(REASONS["ci-branch-route-differs"]).toMatch(/targets a branch other than/);
+  });
+});
+
+describe("the branches ci serve polls (#4325)", () => {
+  const branches = { release: ["prod-*"], staging: ["stg-*"] };
+
+  test("a routed member polls its route alone, and a branch that disagrees is refused", () => {
+    expect(servedBranches(branches, "prod-eu", "main", false)).toEqual({ served: ["release"], routed: ["release"] });
+    expect(servedBranches(branches, "prod-eu", "release", true).served).toEqual(["release"]);
+    expect(() => servedBranches(branches, "prod-eu", "main", true)).toThrow(/routes member prod-eu to release/);
+  });
+
+  test("an unrouted member polls the default branch, and not one reserved for other members", () => {
+    expect(servedBranches(branches, "docs", "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(() => servedBranches(branches, "docs", "release", true)).toThrow(/member docs is not one/);
+  });
+
+  test("with no member, the default branch and then each routed branch", () => {
+    expect(servedBranches(branches, undefined, "main", false)).toEqual({ served: ["main", "release", "staging"], routed: ["release", "staging"] });
+    expect(servedBranches(undefined, undefined, "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(servedBranches(branches, undefined, "release", true).served).toEqual(["release", "staging"]);
+  });
+});

package/src/workspace/checks/ci-branch.ts

@@ -0,0 +1,141 @@
+/**
+ * WSP152 (#4325): a member's generated pull-request pipeline targets the
+ * branch `ci.branches` routes the member to.
+ *
+ * `chant build --pr-loop` refuses a branch that disagrees with the route
+ * (../member-pipeline.ts), but only when it writes the file. A route changed
+ * after the pipeline was generated, or a pipeline edited by hand, goes
+ * unnoticed until a push to the wrong branch applies nothing. This check
+ * reads the files each member's generated-file record lists and compares what
+ * they target with the route. It reads files and never runs them.
+ *
+ * A pipeline names its target in two places: the `--branch` its record and
+ * apply commands carry, and the `branches` of its `push` and `pull_request`
+ * triggers. A routed member's pipeline names the route in both. A member with
+ * no route may name a branch `ci.branches` does not list, and not one it
+ * lists, since that branch applies only the members its globs match.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import { routedBranch } from "../ci-branches";
+import { GENERATED_RECORD_FILE } from "../member-pipeline";
+import { joinPath } from "../tree";
+import { parseYAMLDocument } from "../../yaml";
+import { read } from "./security";
+
+export const WSP_CI_BRANCH_ROUTE = "WSP152";
+
+/** The finding code WSP152 reports. */
+export const CI_BRANCH_FINDING_CODES = ["ci-branch-route-differs"] as const;
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+/** A record or apply command of the pull-request loop: `ci run record|apply`, or `components pr-record|pr-apply`. */
+const JOB = /\bci\s+run\s+(?:record|apply)\b|\bcomponents\s+pr-(?:record|apply)\b/;
+const BRANCH_FLAG = /--branch(?:\s+|=)(?:"([^"]+)"|'([^']+)'|(\S+))/;
+
+/** What a pipeline file says it targets. */
+export interface PipelineTargets {
+  /** The `--branch` of each record or apply command, by line; null for a command with none. */
+  jobs: { line: number; branch: string | null }[];
+  /** The branches its `push` and `pull_request` triggers list, by trigger. Absent for a trigger with no list. */
+  triggers: { trigger: "push" | "pull_request"; branches: string[] }[];
+}
+
+/** The branches a pipeline file targets, read from its text. */
+export function pipelineTargets(text: string): PipelineTargets {
+  const jobs: PipelineTargets["jobs"] = [];
+  text.split("\n").forEach((line, i) => {
+    if (!JOB.test(line)) return;
+    const m = BRANCH_FLAG.exec(line);
+    jobs.push({ line: i + 1, branch: m ? (m[1] ?? m[2] ?? m[3] ?? null) : null });
+  });
+  const triggers: PipelineTargets["triggers"] = [];
+  try {
+    const doc = parseYAMLDocument(text) as { on?: unknown; true?: unknown } | null;
+    // YAML 1.1 reads a bare `on` key as true.
+    const on = doc && typeof doc === "object" ? (doc.on ?? doc.true) : undefined;
+    if (on && typeof on === "object" && !Array.isArray(on)) {
+      for (const trigger of ["push", "pull_request"] as const) {
+        const t = (on as Record<string, unknown>)[trigger];
+        const branches = t && typeof t === "object" ? (t as { branches?: unknown }).branches : undefined;
+        if (Array.isArray(branches)) triggers.push({ trigger, branches: branches.filter((b): b is string => typeof b === "string") });
+      }
+    }
+  } catch {
+    // A file that is not YAML has no triggers to compare; its commands still are.
+  }
+  return { jobs, triggers };
+}
+
+/**
+ * What differs between `targets` and the branch `own` the member is routed to
+ * (null when it has no route), as sentences. `listed` is every branch
+ * `ci.branches` names.
+ */
+export function routeDifferences(targets: PipelineTargets, own: string | null, listed: readonly string[], member: string): string[] {
+  const out: string[] = [];
+  const said = (b: string | null): string => (b === null ? "the default branch (it passes no --branch)" : b);
+  for (const j of targets.jobs) {
+    if (own !== null && j.branch !== own) out.push(`line ${j.line} targets ${said(j.branch)}, and ci.branches routes member ${member} to ${own}`);
+    else if (own === null && j.branch !== null && listed.includes(j.branch)) out.push(`line ${j.line} targets ${j.branch}, which ci.branches reserves for the members its globs match, and member ${member} is not one`);
+  }
+  for (const t of targets.triggers) {
+    if (own !== null && !(t.branches.length === 1 && t.branches[0] === own)) out.push(`its ${t.trigger} trigger lists ${t.branches.join(", ") || "no branch"}, and ci.branches routes member ${member} to ${own}`);
+    else if (own === null) {
+      const reserved = t.branches.filter((b) => listed.includes(b));
+      if (reserved.length > 0) out.push(`its ${t.trigger} trigger lists ${reserved.join(", ")}, which ci.branches reserves for the members its globs match, and member ${member} is not one`);
+    }
+  }
+  return out;
+}
+
+/** The files a member's generated-file record lists, which are pipelines the check can read. */
+function recordedFiles(ctx: Parameters<WorkspaceCheck["check"]>[0], member: Member): string[] {
+  const text = read(ctx.tree, joinPath(memberDir(member.dir), GENERATED_RECORD_FILE));
+  if (text === null) return [];
+  try {
+    const parsed = JSON.parse(text) as { files?: { path?: unknown }[] };
+    return (parsed.files ?? []).flatMap((f) => (typeof f.path === "string" && /\.ya?ml$/.test(f.path) ? [f.path] : []));
+  } catch {
+    return [];
+  }
+}
+
+export const CI_BRANCH_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_CI_BRANCH_ROUTE,
+    name: "ci-branch-route",
+    description: "A member's generated pull-request pipeline targets the branch ci.branches routes the member to, in its record and apply commands and its push and pull_request triggers.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const branches = ctx.declaration.ci?.branches;
+      if (!branches || Object.keys(branches).length === 0) return [];
+      const listed = Object.keys(branches);
+      const out: WorkspaceDiagnostic[] = [];
+      for (const member of ctx.declaration.members) {
+        const own = routedBranch(branches, member.name);
+        for (const path of recordedFiles(ctx, member)) {
+          const text = read(ctx.tree, path);
+          if (text === null) continue;
+          for (const why of routeDifferences(pipelineTargets(text), own, listed, member.name)) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: CI_BRANCH_FINDING_CODES[0],
+              message: `WSP152: ${path}: ${why}; regenerate it with chant build --components --generate <forge> --pr-loop`,
+              pointer: "/ci/branches",
+              entity: member.name,
+              treeFile: path,
+              line: 1,
+              column: 1,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+];

package/src/workspace/checks/links.ts

@@ -22,6 +22,9 @@
  * Links a kind's reader finds in a member's own files (#3932), such as a dbt
  * project's sources, are checked by WSP093 to WSP095 like declared ones, and
  * their findings name the member's file and line instead of the declaration.
+ * Links a member's lexicon reads from its declarations (#4397), such as the
+ * tables an otel `clickhouse` exporter writes, are checked the same way, with
+ * the reader named `lexicon <name>`.
  */
 
 import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
@@ -33,11 +36,19 @@ import { DEFAULT_LINK_KIND, LINK_KINDS, TELEMETRY_LINK_KIND, linkTargetProblem,
 const tables = new WeakMap<WorkspaceCheckContext, LinkTableRow[]>();
 const reads = new WeakMap<WorkspaceCheckContext, Map<string, KindLinkRead>>();
 
-/** What each member's kind reader found (#3932), read once per check run. */
+/**
+ * What each member's kind reader found (#3932), and the links its lexicons
+ * read from its declarations (#4397), read once per check run.
+ */
 function kindReads(ctx: WorkspaceCheckContext): Map<string, KindLinkRead> {
   let read = reads.get(ctx);
   if (!read) {
     read = readKindLinks(ctx.declaration, ctx.tree, ctx.kinds);
+    for (const [member, lexicon] of ctx.facts?.lexiconLinks ?? []) {
+      const prev = read.get(member);
+      // resolveLinks names one reader per member; the lexicon's links keep their file and line.
+      read.set(member, prev ? { ...prev, links: [...prev.links, ...lexicon.links], gaps: [...prev.gaps, ...lexicon.gaps] } : lexicon);
+    }
     reads.set(ctx, read);
   }
   return read;

package/src/workspace/checks/org.ts

@@ -0,0 +1,169 @@
+/**
+ * Org scope (#3168): members of kind `repo`, which name another repository's
+ * workspace by URL and pinned revision, and the org-level workspace that
+ * holds only such members.
+ *
+ * | Id | Check |
+ * |---|---|
+ * | WSP013 | an org workspace holds only repo members |
+ * | WSP014 | every repository the forge lists is declared (with `--forge-repos`) |
+ * | WSP015 | every declared repository is one the forge lists (with `--forge-repos`) |
+ * | WSP016 | no repo member's URL carries a password or token |
+ *
+ * The forge's list is input, never fetched here: a warden enumerates the
+ * org's repositories from its own API and hands the list to
+ * `chant workspace check --forge-repos <file>`, so the check stays offline.
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { REPO_KIND } from "../kinds";
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+
+/** One repository the forge lists. */
+export interface ForgeRepo {
+  url: string;
+  /** An archived repository need not be declared, and declaring one is not a drop. */
+  archived: boolean;
+}
+
+/** The forge's repository list for `--forge-repos` (#3168), as a warden writes it. */
+export interface ForgeRepoList {
+  /** The file it was read from, for messages. */
+  source: string;
+  repos: ForgeRepo[];
+}
+
+/**
+ * Parse a forge repository list. Three shapes are read: `{ "repos": [...] }`
+ * (a warden may add `forge` and `org` beside it), a bare array, and, for each
+ * repository, a URL string or `{ "url", "archived"? }`. Throws an Error that
+ * says what is wrong.
+ */
+export function parseForgeRepos(text: string, source: string): ForgeRepoList {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${source} is not JSON (${(err as Error).message})`);
+  }
+  const list = Array.isArray(raw) ? raw : raw !== null && typeof raw === "object" && Array.isArray((raw as { repos?: unknown }).repos) ? (raw as { repos: unknown[] }).repos : undefined;
+  if (!list) throw new Error(`${source} is neither an array of repositories nor an object with a repos array`);
+  const repos = list.map((r, i): ForgeRepo => {
+    if (typeof r === "string" && r.length > 0) return { url: r, archived: false };
+    if (r !== null && typeof r === "object" && typeof (r as { url?: unknown }).url === "string") {
+      return { url: (r as { url: string }).url, archived: (r as { archived?: unknown }).archived === true };
+    }
+    throw new Error(`${source}: repos[${i}] is neither a URL nor an object with a url`);
+  });
+  return { source, repos };
+}
+
+/**
+ * A repository URL reduced to what names the repository, so the forge's
+ * https URL and a declaration's ssh or scp-style URL compare equal:
+ * `host/owner/repo`, lowercased, with no scheme, user, port, `.git` or
+ * trailing slash. A local path or file URL becomes its absolute path,
+ * resolved from `base`.
+ */
+export function repoKey(url: string, base: string = process.cwd()): string {
+  const trimmed = url.trim();
+  const scp = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/\/)(.+)$/.exec(trimmed);
+  let hostPath: string | undefined;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    let u: URL;
+    try {
+      u = new URL(trimmed);
+    } catch {
+      return trimmed.toLowerCase();
+    }
+    if (u.protocol === "file:") return stripGit(decodeURIComponent(u.pathname));
+    hostPath = `${u.hostname}${u.pathname}`;
+  } else if (scp && !isAbsolute(trimmed) && !/^[a-z]:[\\/]/i.test(trimmed)) {
+    hostPath = `${scp[1]}/${scp[2]}`;
+  } else {
+    return stripGit(resolve(base, trimmed));
+  }
+  return stripGit(hostPath.replace(/\/+/g, "/")).toLowerCase();
+}
+
+function stripGit(path: string): string {
+  return path.replace(/\/+$/, "").replace(/\.git$/, "");
+}
+
+/** Whether a URL carries a password or token, which a declaration must never hold. */
+export function urlCredential(url: string): boolean {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return false;
+  try {
+    const u = new URL(url);
+    // ssh://git@host is a user name, not a secret; a password, or any user on http(s), is one.
+    return u.password !== "" || (u.username !== "" && /^https?:$/.test(u.protocol));
+  } catch {
+    return false;
+  }
+}
+
+const repoMembers = (ctx: Parameters<WorkspaceCheck["check"]>[0]) => ctx.declaration.members.filter((m) => m.kind === REPO_KIND && m.repo !== null);
+
+function finding(check: WorkspaceCheck, message: string, pointer: string, entity?: string): WorkspaceDiagnostic {
+  return { checkId: check.id, severity: check.severity, message, pointer, ...(entity !== undefined ? { entity } : {}) };
+}
+
+export const ORG_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP013",
+    name: "org-member-local",
+    description: "An org workspace (scope org) holds only members of kind repo, each a reference to another repository's workspace (#3168).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      if (ctx.declaration.scope !== "org") return [];
+      return ctx.declaration.entries
+        .filter((e) => e.kind !== REPO_KIND)
+        .map((e) =>
+          finding(this, `${e.type === "group" ? "example group" : "member"} ${e.name} is kind ${e.kind}, and an org workspace holds only repo members; move it into a repository's own workspace and reference that`, `${e.pointer}/kind`, e.name),
+        );
+    },
+  },
+  {
+    id: "WSP014",
+    name: "org-repo-undeclared",
+    description: "With --forge-repos, every repository the forge lists, archived ones aside, is named by a repo member (#3168).",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const forge = ctx.facts?.forgeRepos;
+      if (!forge) return [];
+      const declared = new Set(repoMembers(ctx).map((m) => repoKey(m.repo!.url)));
+      return forge.repos
+        .filter((r) => !r.archived && !declared.has(repoKey(r.url)))
+        .map((r) => finding(this, `the forge lists ${r.url} (${forge.source}), and no repo member names it; add a member of kind repo with its url and pinned rev`, "/members"));
+    },
+  },
+  {
+    id: "WSP015",
+    name: "org-repo-dropped",
+    description: "With --forge-repos, every repository a repo member names is one the forge still lists (#3168).",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const forge = ctx.facts?.forgeRepos;
+      if (!forge) return [];
+      const listed = new Set(forge.repos.map((r) => repoKey(r.url)));
+      return repoMembers(ctx)
+        .filter((m) => !listed.has(repoKey(m.repo!.url)))
+        .map((m) => finding(this, `member ${m.name} names ${m.repo!.url}, which the forge no longer lists (${forge.source}); remove the member or say why it stays`, `${m.pointer}/repo/url`, m.name));
+    },
+  },
+  {
+    id: "WSP016",
+    name: "repo-url-credential",
+    description: "No repo member's URL carries a password or token: the declaration is committed, and git's own credential helpers supply access (#3168).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return repoMembers(ctx)
+        .filter((m) => urlCredential(m.repo!.url))
+        .map((m) => finding(this, `member ${m.name}'s repo url carries a credential; name the repository without one and let git's credential helper supply access`, `${m.pointer}/repo/url`, m.name));
+    },
+  },
+];

package/src/workspace/checks.ts

@@ -21,7 +21,8 @@
  *
  * | Ids | Checks |
  * |---|---|
- * | WSP001 to WSP011 | the declaration and member kinds (this file) |
+ * | WSP001 to WSP012 | the declaration and member kinds (this file), and a member's file against its kind's schema (#3672) |
+ * | WSP013 to WSP016 | org scope: repo members and the org workspace, checked against the forge's list with `--forge-repos` (#3168) |
  * | WSP071, WSP072 | member ledgers |
  * | WSP081 to WSP083 | recorded pipelines |
  * | WSP091 to WSP099 | member links (#2539, #2558), and those a kind's reader finds in a member's files (#3932) |
@@ -38,6 +39,7 @@
  * | WSP141, WSP142 | member links resolved against a live read, with `--live` (#2549) |
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
  * | WSP151 | what a member under `ci.workflow` still lacks (#4168 step 6) |
+ * | WSP152 | a member's generated pipeline targets the branch `ci.branches` routes it to (#4325) |
  * | WSP161 to WSP165 | the security groups the declaration opts into: what each still lacks (#4168 step 7) |
  */
 
@@ -48,7 +50,7 @@ import type { PostSynthDiagnostic } from "../lint/post-synth";
 import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, type Entry, type ErrorLocation, type ResolvedGroup } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
-import { loadKindRegistry, probeKind, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { checkMemberFile, loadKindRegistry, probeKind, REPO_KIND, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
 import { coreClassRegistry, loadClassRegistry, unknownScopeClasses, type ClassRegistry } from "./principal-classes";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
@@ -62,9 +64,12 @@ import { BOX_CHECKS } from "./checks/boxes";
 import { DIAGRAM_CHECKS } from "./checks/diagrams";
 import { SECURITY_CHECKS } from "./checks/security";
 import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
+import { CI_BRANCH_CHECKS } from "./checks/ci-branch";
+import { ORG_CHECKS, type ForgeRepoList } from "./checks/org";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 import { resolveBoxIntents, type ResolvedBoxIntent } from "./box-intent";
-import { gatherLexiconOutputs, type MemberLexiconOutputs } from "./lexicon-outputs";
+import { gatherLexiconLinks, gatherLexiconOutputs, type MemberLexiconOutputs } from "./lexicon-outputs";
+import type { KindLinkRead } from "./kind-link-readers";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -88,6 +93,10 @@ export interface WorkspaceFacts {
   boxIntents?: readonly ResolvedBoxIntent[];
   /** The outputs linked members' lexicons report about their declarations, read by folding their source (#3931). */
   lexiconOutputs?: ReadonlyMap<string, MemberLexiconOutputs>;
+  /** The links members' lexicons read from their declarations, such as an otel clickhouse exporter's tables (#4397). */
+  lexiconLinks?: ReadonlyMap<string, KindLinkRead>;
+  /** The forge's repository list, from `--forge-repos` (#3168). */
+  forgeRepos?: ForgeRepoList;
 }
 
 /** What every declaration check reads. */
@@ -174,9 +183,9 @@ function entryFinding(check: WorkspaceCheck, entry: Entry, field: string | null,
   };
 }
 
-/** The dir exists and the kind is known: the members every probe check reads. */
+/** The dir exists and the kind is known: the members every probe check reads. A repo member has no directory here (#3168). */
 function readableMembers(ctx: WorkspaceCheckContext) {
-  return ctx.declaration.members.filter((m) => ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
+  return ctx.declaration.members.filter((m) => m.kind !== REPO_KIND && ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
 }
 
 /** The first id of the read failure, used by {@link runDeclarationChecks} when the declaration can't be read. */
@@ -240,7 +249,7 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
     configurable: true,
     check(ctx) {
       return ctx.declaration.members
-        .filter((m) => ctx.tree.stat(memberDir(m.dir)) !== "dir")
+        .filter((m) => m.kind !== REPO_KIND && ctx.tree.stat(memberDir(m.dir)) !== "dir")
         .map((m) => entryFinding(this, m, "dir", `member ${m.name}'s directory ${m.dir} does not exist${ctx.tree.label}`));
     },
   },
@@ -359,6 +368,43 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
       return out;
     },
   },
+  {
+    id: "WSP012",
+    name: "member-file-invalid",
+    description: "Every member of a kind that names a member file has that file, and it passes the kind's JSON Schema (#3672).",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of readableMembers(ctx)) {
+        const kind = ctx.kinds.get(m.kind)!;
+        const mf = kind.memberFile;
+        if (!mf) continue;
+        const file = memberDir(m.dir) === "" ? mf.path : `${memberDir(m.dir)}/${mf.path}`;
+        if (!mf.validate) {
+          out.push(entryFinding(this, m, "kind", `member ${m.name}'s ${mf.path} can't be checked: kind ${m.kind}'s schema ${mf.schema} did not load (see WSP002)`));
+          continue;
+        }
+        if (ctx.tree.stat(file) !== "file") {
+          out.push(entryFinding(this, m, "dir", `member ${m.name} (${m.dir}) has no ${mf.path}, which kind ${m.kind} requires${ctx.tree.label}`));
+          continue;
+        }
+        let text: string;
+        try {
+          text = ctx.tree.read(file);
+        } catch (err) {
+          out.push(entryFinding(this, m, "dir", `member ${m.name}'s ${mf.path} can't be read: ${(err as Error).message}`));
+          continue;
+        }
+        for (const p of checkMemberFile(mf, mf.path, text)) {
+          out.push({ ...entryFinding(this, m, null, `member ${m.name}'s ${mf.path} fails kind ${m.kind}'s schema ${mf.schema}: ${p.message}`), treeFile: file, line: 1, column: 1 });
+        }
+      }
+      return out;
+    },
+  },
+  // Org scope (#3168), WSP013 to WSP016.
+  ...ORG_CHECKS,
   // Member ledgers (#2538).
   ...LEDGER_CHECKS,
   // Recorded pipelines (#2542).
@@ -377,6 +423,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...LIVE_CHECKS,
   // What a member under ci.workflow still lacks (#4168 step 6), WSP151.
   ...CI_WORKFLOW_CHECKS,
+  // A member's pipeline targets the branch ci.branches routes it to (#4325), WSP152.
+  ...CI_BRANCH_CHECKS,
   // The security groups the declaration opts into (#4168 step 7), WSP161 to WSP165.
   ...SECURITY_CHECKS,
 ];
@@ -463,6 +511,8 @@ export interface DeclarationCheckOptions {
    * account now. `onStderr` gets each member's stderr.
    */
   live?: { env: string; onStderr?: (text: string) => void };
+  /** The forge's repository list, from `--forge-repos` (#3168), for WSP014 and WSP015. Read under `--at` too: it is input, not the tree. */
+  forgeRepos?: ForgeRepoList;
 }
 
 /**
@@ -534,12 +584,19 @@ export async function runDeclarationChecks(
   // A box's intent is read from the working tree's records, so not under --at (#2850).
   const boxIntents = declaredKinds && !options.tree ? await resolveBoxIntents(declaration, root, declaredKinds) : undefined;
   // A linked member's lexicons name its tables and columns as outputs (#3931); reading them folds its source, never runs it.
+  // A member's lexicons may also read other members' outputs from its declarations (#4397); their targets are read too.
+  const outputsTree = options.tree ? workingTree(root) : tree;
+  const lexiconLinks = options.gather === false ? undefined : await gatherLexiconLinks(root, declaration, outputsTree, groups, registry, { atRevision: options.tree !== undefined });
   const lexiconOutputs =
-    options.gather === false ? undefined : await gatherLexiconOutputs(root, declaration, options.tree ? workingTree(root) : tree, groups, registry, { atRevision: options.tree !== undefined });
+    options.gather === false
+      ? undefined
+      : await gatherLexiconOutputs(root, declaration, outputsTree, groups, registry, { atRevision: options.tree !== undefined, ...(lexiconLinks ? { lexiconLinks } : {}) });
   const facts: WorkspaceFacts = {
     ...(lexiconOutputs && lexiconOutputs.size > 0 ? { lexiconOutputs } : {}),
+    ...(lexiconLinks && lexiconLinks.size > 0 ? { lexiconLinks } : {}),
     ...gathered,
     ...(options.records ? { records: options.records } : {}),
+    ...(options.forgeRepos ? { forgeRepos: options.forgeRepos } : {}),
     ...(declaredKinds ? { declaredKinds } : {}),
     ...(boxIntents ? { boxIntents } : {}),
     ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),

package/src/workspace/ci-branches.ts

@@ -40,6 +40,37 @@ export function routeConflicts(branches: MemberGlobs | undefined, members: reado
   return members.map((member) => ({ member, branches: keysMatching(branches, member) })).filter((c) => c.branches.length > 1);
 }
 
+/**
+ * The branches `chant ci serve` polls (#4325), and the ones among them a job
+ * is told with `--branch`.
+ *
+ * - A routed member polls its route alone. A `named` branch that differs
+ *   from the route is refused, as `chant build --pr-loop` refuses it.
+ * - An unrouted member polls `fallback`, which may not be a routed branch.
+ * - Where no member is in play (the workspace root), `fallback` and then each
+ *   routed branch, so every branch a member applies from is watched.
+ *
+ * `fallback` is the branch `--branch` names, else the default branch.
+ */
+export function servedBranches(
+  branches: MemberGlobs | undefined,
+  member: string | undefined,
+  fallback: string,
+  named: boolean,
+): { served: string[]; routed: string[] } {
+  const keys = Object.keys(branches ?? {});
+  if (member === undefined) return { served: [fallback, ...keys.filter((k) => k !== fallback)], routed: keys };
+  const own = routedBranch(branches, member);
+  if (own !== null) {
+    if (named && fallback !== own) throw new Error(`--branch ${fallback}: ci.branches routes member ${member} to ${own}, so ci serve polls ${own}`);
+    return { served: [own], routed: [own] };
+  }
+  if (keys.includes(fallback)) {
+    throw new Error(`--branch ${fallback}: ci.branches applies only the members its globs match from ${fallback}, and member ${member} is not one`);
+  }
+  return { served: [fallback], routed: [] };
+}
+
 /**
  * Whether a push to `pushed` applies `member`, with a line that says why.
  * A routed member applies only from its branch. Any other member applies