@intentius/chant 0.124.45 → 0.124.48

package/dist/workspace/capabilities-contract.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The `capabilities` document of the read contract (#4375, ws-017): the
+ * capability catalog `chant search` answers `cap:` terms with, described by
+ * `capabilities.schema.json` beside this file.
+ *
+ * `chant search --capabilities --json` prints it for one project, with a
+ * support statement for each lexicon the project loads. `chant workspace
+ * search --capabilities --json` prints it from the workspace root's chant,
+ * for every lexicon a member loads (a terraform member's reader lexicon
+ * included, #4380): capability rules run once, under
+ * the workspace's chant, so the catalog is that chant's. chant's MCP
+ * `capabilities` tool returns whichever of the two applies where the server
+ * runs, unchanged.
+ */
+import type { CapabilityEntry } from "../capabilities/catalog.js";
+/** The version of the `capabilities` document this chant writes. */
+export declare const CAPABILITIES_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export declare const CAPABILITIES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json";
+/** Why no catalog was printed. */
+export declare const CAPABILITIES_ERROR_CODES: readonly ["usage-invalid"];
+export type CapabilitiesErrorCode = (typeof CAPABILITIES_ERROR_CODES)[number];
+/** Why a lexicon can't supply a capability. */
+export declare const CAPABILITY_SUPPORT_CODES: readonly ["lexicon-has-no-mapping", "capability-not-derivable", "lexicon-not-loaded"];
+interface CapabilitiesHead {
+    $schema: typeof CAPABILITIES_OUTPUT_SCHEMA_ID;
+    contract: typeof CAPABILITIES_CONTRACT_VERSION;
+    /** The chant that wrote the document. */
+    chant: string;
+}
+export interface CapabilitiesResult extends CapabilitiesHead {
+    capabilities: CapabilityEntry[];
+    helpers: {
+        name: string;
+        rule: string;
+    }[];
+}
+export interface CapabilitiesFailure extends CapabilitiesHead {
+    error: {
+        code: CapabilitiesErrorCode;
+        message: string;
+        hint?: string;
+    };
+}
+export type CapabilitiesDocument = CapabilitiesResult | CapabilitiesFailure;
+/**
+ * The catalog, with a support statement for each lexicon named. Each is
+ * loaded on its own, so one that isn't installed is said to be, and the rest
+ * still read.
+ */
+export declare function capabilitiesDocument(lexicons: string[], load?: (name: string) => Promise<{
+    capabilityPack?: {
+        mapping: unknown;
+    };
+}>): Promise<CapabilitiesResult>;
+export declare function capabilitiesFailure(error: CapabilitiesFailure["error"]): Promise<CapabilitiesFailure>;
+/**
+ * The lexicons the members of the workspace at `cwd` load, for its catalog:
+ * each chant member's own, and for a member of a package's kind, such as
+ * `terraform`, the lexicon its reader project declares (#4380).
+ */
+export declare function workspaceLexicons(cwd: string): Promise<string[]>;
+/** The catalog as text: one capability per line, its search term and meaning, then its parameters. */
+export declare function formatCapabilities(doc: CapabilitiesResult): string[];
+export {};
+//# sourceMappingURL=capabilities-contract.d.ts.map

package/dist/workspace/capabilities-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-contract.d.ts","sourceRoot":"","sources":["../../src/workspace/capabilities-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,oEAAoE;AACpE,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,0FAA0F,CAAC;AAErI,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,4BAA6D,CAAC;AACnG,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,+CAA+C;AAC/C,eAAO,MAAM,wBAAwB,uFAAwH,CAAC;AAE9J,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,6BAA6B,CAAC;IAC9C,QAAQ,EAAE,OAAO,6BAA6B,CAAC;IAC/C,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,KAAK,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAO5E;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,cAAc,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC,GAC1E,OAAO,CAAC,kBAAkB,CAAC,CAoB7B;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAE3G;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBtE;AAED,sGAAsG;AACtG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAYpE"}

package/dist/workspace/capabilities-contract.js

@@ -0,0 +1,107 @@
+/**
+ * The `capabilities` document of the read contract (#4375, ws-017): the
+ * capability catalog `chant search` answers `cap:` terms with, described by
+ * `capabilities.schema.json` beside this file.
+ *
+ * `chant search --capabilities --json` prints it for one project, with a
+ * support statement for each lexicon the project loads. `chant workspace
+ * search --capabilities --json` prints it from the workspace root's chant,
+ * for every lexicon a member loads (a terraform member's reader lexicon
+ * included, #4380): capability rules run once, under
+ * the workspace's chant, so the catalog is that chant's. chant's MCP
+ * `capabilities` tool returns whichever of the two applies where the server
+ * runs, unchanged.
+ */
+import { resolve } from "node:path";
+/** The version of the `capabilities` document this chant writes. */
+export const CAPABILITIES_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const CAPABILITIES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json";
+/** Why no catalog was printed. */
+export const CAPABILITIES_ERROR_CODES = ["usage-invalid"];
+/** Why a lexicon can't supply a capability. */
+export const CAPABILITY_SUPPORT_CODES = ["lexicon-has-no-mapping", "capability-not-derivable", "lexicon-not-loaded"];
+async function head() {
+    const { readChantPackageVersion } = await import("../package-version.js");
+    return { $schema: CAPABILITIES_OUTPUT_SCHEMA_ID, contract: CAPABILITIES_CONTRACT_VERSION, chant: readChantPackageVersion() };
+}
+/**
+ * The catalog, with a support statement for each lexicon named. Each is
+ * loaded on its own, so one that isn't installed is said to be, and the rest
+ * still read.
+ */
+export async function capabilitiesDocument(lexicons, load) {
+    const loadPlugin = load ?? (await import("../cli/plugins.js")).loadPlugin;
+    const { capabilityCatalog } = await import("../capabilities/catalog.js");
+    const mappings = {};
+    const notLoaded = [];
+    for (const name of [...new Set(lexicons)].sort()) {
+        try {
+            mappings[name] = (await loadPlugin(name)).capabilityPack?.mapping;
+        }
+        catch {
+            notLoaded.push(name);
+            mappings[name] = undefined;
+        }
+    }
+    const catalog = capabilityCatalog(mappings);
+    for (const c of catalog.capabilities) {
+        for (const name of notLoaded) {
+            c.lexicons[name] = { code: "lexicon-not-loaded", message: `the ${name} lexicon isn't installed where this chant runs, so its mapping wasn't read` };
+        }
+    }
+    return { ...(await head()), ...catalog };
+}
+export async function capabilitiesFailure(error) {
+    return { ...(await head()), error };
+}
+/**
+ * The lexicons the members of the workspace at `cwd` load, for its catalog:
+ * each chant member's own, and for a member of a package's kind, such as
+ * `terraform`, the lexicon its reader project declares (#4380).
+ */
+export async function workspaceLexicons(cwd) {
+    const { listWorkspace } = await import("./ls.js");
+    const { findWorkspaceRoot } = await import("../project-root.js");
+    const { resolveProjectLexicons } = await import("../cli/plugins.js");
+    const { loadKindRegistry } = await import("./kinds.js");
+    const located = findWorkspaceRoot(cwd);
+    const doc = listWorkspace({ cwd });
+    if (!located || "error" in doc)
+        return [];
+    const out = new Set();
+    const kinds = doc.members.some((m) => m.kind !== "chant" && m.readable) ? loadKindRegistry(doc.workspace.pins, located.dir).registry : undefined;
+    for (const m of doc.members) {
+        if (!m.readable)
+            continue;
+        const reader = m.kind === "chant" ? undefined : kinds?.get(m.kind)?.graph?.lexicon;
+        if (reader)
+            out.add(reader);
+        if (m.kind !== "chant")
+            continue;
+        try {
+            for (const l of await resolveProjectLexicons(resolve(located.dir, m.dir)))
+                out.add(l);
+        }
+        catch {
+            // A member whose lexicons can't be resolved adds none; its own search says why.
+        }
+    }
+    return [...out];
+}
+/** The catalog as text: one capability per line, its search term and meaning, then its parameters. */
+export function formatCapabilities(doc) {
+    const width = Math.max(...doc.capabilities.map((c) => c.search.length));
+    const lines = [];
+    for (const c of doc.capabilities) {
+        lines.push(`${c.search.padEnd(width)}  ${c.shape.padEnd(4)}  ${c.meaning}`);
+        for (const p of c.params)
+            lines.push(`${"".padEnd(width)}        ${p.name}${p.optional ? "?" : ""}: ${p.meaning}`);
+        const unsupported = Object.entries(c.lexicons).filter(([, s]) => s !== "supported");
+        for (const [lex, s] of unsupported)
+            lines.push(`${"".padEnd(width)}        not in ${lex}: ${s.message}`);
+    }
+    const lexicons = Object.keys(doc.capabilities[0]?.lexicons ?? {});
+    lines.push(`— ${doc.capabilities.length} capabilities${lexicons.length ? ` · lexicons ${lexicons.join(", ")}` : ""} · --json prints each rule`);
+    return lines;
+}

package/dist/workspace/capabilities.schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json",
+  "title": "chant capabilities catalog",
+  "description": "What `chant search --capabilities --json` prints (#4375): the capability catalog `chant search` answers `cap:` terms and `->[cap=...]` edges with, each capability's rule, and whether each lexicon the project loads can supply it. chant's MCP `capabilities` tool returns the same document. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.46 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "capabilities",
+        "helpers"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "capabilities": {
+          "type": "array",
+          "description": "Every capability the catalog lists, in the order the rule file defines them.",
+          "items": {
+            "$ref": "#/$defs/capability"
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "description": "Rules the capabilities use that the catalog does not list as capabilities of their own.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "rule"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "rule": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "name",
+        "meaning",
+        "shape",
+        "params",
+        "search",
+        "answers",
+        "depth",
+        "lexicons",
+        "notEvaluated",
+        "uses",
+        "rule"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "meaning": {
+          "type": "string",
+          "description": "What the capability says, in one line."
+        },
+        "shape": {
+          "enum": [
+            "set",
+            "edge"
+          ],
+          "description": "set: a set of nodes, tested with cap:<name>. edge: pairs of nodes, walked with ->[cap=<name>] or <-[cap=<name>]."
+        },
+        "params": {
+          "type": "array",
+          "description": "Arguments, in order: cap:<name>(<a>, <b>). An optional one left out drops the test that reads it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "optional",
+              "meaning"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "optional": {
+                "type": "boolean"
+              },
+              "meaning": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "search": {
+          "type": "string",
+          "description": "The search term that asks for it: cap:<name> for a set, ->[cap=<name>] for an edge."
+        },
+        "answers": {
+          "type": "array",
+          "description": "Questions it serves, in people's words.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depth": {
+          "enum": [
+            "declared",
+            "live",
+            "either"
+          ],
+          "description": "Which observation can supply its facts: declared source, a live read or snapshot, or either."
+        },
+        "lexicons": {
+          "type": "object",
+          "description": "Each lexicon the project loads: supported, or why it can't supply the capability.",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "const": "supported"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "properties": {
+                  "code": {
+                    "enum": [
+                      "lexicon-has-no-mapping",
+                      "capability-not-derivable",
+                      "lexicon-not-loaded"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "notEvaluated": {
+          "type": "array",
+          "description": "What the rule leaves out. chant search prints this under every answer that uses the capability.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "uses": {
+          "type": "array",
+          "description": "The capabilities and helpers its rule refers to.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rule": {
+          "type": "string",
+          "description": "The rule as written, one alternative per line."
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "usage-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "hint": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/workspace/check.schema.json

@@ -65,6 +65,13 @@
                   ],
                   "description": "The declared name, or null when the declaration can't be read."
                 },
+                "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."
@@ -341,7 +348,8 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "ci-branch-route-differs"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         }
@@ -463,7 +471,8 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "ci-branch-route-differs"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         },

package/dist/workspace/checks/ci-branch.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 } from "../checks.js";
+export declare const WSP_CI_BRANCH_ROUTE = "WSP152";
+/** The finding code WSP152 reports. */
+export declare const CI_BRANCH_FINDING_CODES: readonly ["ci-branch-route-differs"];
+/** 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 declare function pipelineTargets(text: string): PipelineTargets;
+/**
+ * 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 declare function routeDifferences(targets: PipelineTargets, own: string | null, listed: readonly string[], member: string): string[];
+export declare const CI_BRANCH_CHECKS: readonly WorkspaceCheck[];
+//# sourceMappingURL=ci-branch.d.ts.map

package/dist/workspace/checks/ci-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-branch.d.ts","sourceRoot":"","sources":["../../../src/workspace/checks/ci-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,WAAW,CAAC;AAQrE,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,YAAI,yBAAyB,CAAU,CAAC;AAQ5E,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,6FAA6F;IAC7F,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IAChD,+GAA+G;IAC/G,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACtE;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAuB7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAelI;AAcD,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAmCrD,CAAC"}

package/dist/workspace/checks/ci-branch.js

@@ -0,0 +1,133 @@
+/**
+ * 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 { routedBranch } from "../ci-branches.js";
+import { GENERATED_RECORD_FILE } from "../member-pipeline.js";
+import { joinPath } from "../tree.js";
+import { parseYAMLDocument } from "../../yaml.js";
+import { read } from "./security.js";
+export const WSP_CI_BRANCH_ROUTE = "WSP152";
+/** The finding code WSP152 reports. */
+export const CI_BRANCH_FINDING_CODES = ["ci-branch-route-differs"];
+const memberDir = (dir) => (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+))/;
+/** The branches a pipeline file targets, read from its text. */
+export function pipelineTargets(text) {
+    const 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 = [];
+    try {
+        const doc = parseYAMLDocument(text);
+        // 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"]) {
+                const t = on[trigger];
+                const branches = t && typeof t === "object" ? t.branches : undefined;
+                if (Array.isArray(branches))
+                    triggers.push({ trigger, branches: branches.filter((b) => 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, own, listed, member) {
+    const out = [];
+    const said = (b) => (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, member) {
+    const text = read(ctx.tree, joinPath(memberDir(member.dir), GENERATED_RECORD_FILE));
+    if (text === null)
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        return (parsed.files ?? []).flatMap((f) => (typeof f.path === "string" && /\.ya?ml$/.test(f.path) ? [f.path] : []));
+    }
+    catch {
+        return [];
+    }
+}
+export const CI_BRANCH_CHECKS = [
+    {
+        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 = [];
+            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/dist/workspace/checks/links.d.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 } from "../checks.js";
 import { type LinkTableRow } from "../links.js";

package/dist/workspace/checks/links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../../src/workspace/checks/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAuB,MAAM,WAAW,CAAC;AAI5F,OAAO,EAAwH,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAenK,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,GAAG,EAAE,qBAAqB,GAAG,YAAY,EAAE,CAOpE;AAoBD,eAAO,MAAM,WAAW,EAAE,SAAS,cAAc,EAmLhD,CAAC"}
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../../src/workspace/checks/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAuB,MAAM,WAAW,CAAC;AAI5F,OAAO,EAAwH,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAuBnK,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,GAAG,EAAE,qBAAqB,GAAG,YAAY,EAAE,CAOpE;AAoBD,eAAO,MAAM,WAAW,EAAE,SAAS,cAAc,EAmLhD,CAAC"}

package/dist/workspace/checks/links.js

@@ -22,17 +22,28 @@
  * 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 { sourceMemberHandles } from "../member-handles.js";
 import { readKindLinks } from "../kind-link-readers.js";
 import { DEFAULT_LINK_KIND, LINK_KINDS, TELEMETRY_LINK_KIND, linkTargetProblem, resolveLinks } from "../links.js";
 const tables = new WeakMap();
 const reads = new WeakMap();
-/** 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) {
     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;