@intentius/chant 0.94.0 → 0.95.1

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

@@ -11,7 +11,7 @@
  * reference workspace runs a real one (`read-contract.test.ts`).
  */
 
-import { rmSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, declaration, declaration as declaration_, FAKE_GRAPH_CHANT, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
@@ -60,7 +60,7 @@ describe("graph output schema", () => {
   test("lists exactly the reason and error codes the code can return", () => {
     expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...GRAPH_ERROR_CODES]);
-    expect(GRAPH_ERROR_CODES).toEqual(WORKSPACE_ERROR_CODES);
+    expect(GRAPH_ERROR_CODES).toEqual([...WORKSPACE_ERROR_CODES, "live-at-revision"]);
   });
 });
 
@@ -89,7 +89,7 @@ describe("the links section (#2539)", () => {
       ]),
       "chant.workspace.json",
     );
-    const member = (name: string) => ({ name, dir: name, kind: "chant", status: "composed" as const, reason: null, chant: "0.81.0", irVersion: 1 });
+    const member = (name: string) => ({ name, dir: name, kind: "chant", status: "composed" as const, reason: null, chant: "0.81.0", irVersion: 1, live: false });
     const graph = composeWorkspaceGraph(
       { name: "acme", root: "." },
       [
@@ -107,8 +107,15 @@ describe("the links section (#2539)", () => {
 });
 
 describe("chant workspace graph on the chant repo (#2557)", () => {
-  test("validates, and lists every member as skipped: none is kind chant", async () => {
-    const { doc, failed } = await workspaceGraph({ cwd: join(REPO, "packages", "core") });
+  // The one terraform member runs through the terraform lexicon (#2874), a
+  // real chant per read; kind-readers.e2e.test.ts covers that. Here it is
+  // left out, so nothing runs.
+  const notRun = (JSON.parse(readFileSync(join(REPO, "chant.workspace.json"), "utf-8")) as { members: { name: string; kind: string }[] }).members
+    .filter((m) => m.kind !== "terraform" && m.kind !== "choudoufu")
+    .map((m) => m.name);
+
+  test("validates, and lists every member but the terraform one as skipped: none is kind chant", async () => {
+    const { doc, failed } = await workspaceGraph({ cwd: join(REPO, "packages", "core"), members: notRun });
     const g = result(doc);
     expectValid(g);
     expect(failed).toBe(false);
@@ -119,7 +126,7 @@ describe("chant workspace graph on the chant repo (#2557)", () => {
 
   test("--at HEAD reads from git objects and exports nothing when no member runs", async () => {
     const head = git(REPO, "rev-parse", "HEAD");
-    const { doc } = await workspaceGraph({ cwd: REPO, at: "HEAD" });
+    const { doc } = await workspaceGraph({ cwd: REPO, at: "HEAD", members: notRun });
     const g = result(doc);
     expectValid(g);
     expect(g.at).toBe(head);
@@ -203,3 +210,119 @@ describe("chant workspace graph on built workspaces", () => {
     ]);
   });
 });
+
+/**
+ * A chant older than member-run that records its command line in argv.txt
+ * beside the member, outside its directory so the member cache's stamp holds,
+ * and prints ir.json, or live.json when asked for --live (#2875).
+ */
+const FAKE_LIVE_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+printf '%s\\n' "$*" > ../argv.txt
+case " $* " in
+  *" --live "*) cat live.json ;;
+  *) cat ir.json ;;
+esac
+`;
+
+/** Every file under `dir` an hour old, past the member cache's freshness window. */
+function age(dir: string): void {
+  const then = new Date(Date.now() - 3_600_000);
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, e.name);
+    if (e.isDirectory()) age(path);
+    else if (e.isFile()) utimesSync(path, then, then);
+  }
+}
+
+describe("the live read (#2875)", () => {
+  const source = { version: 1, nodes: [{ id: "Queue", kind: "Thing", lexicon: "fake", attrs: {} }], edges: [], groups: {} };
+  const live = {
+    version: 1,
+    nodes: [
+      { id: "Queue", kind: "Thing", lexicon: "fake", attrs: { _status: "good", _drift: { fields: ["size"] }, _behaviour: { cost: { perHour: 1.5, currency: "USD" } } } },
+      { id: "Stray", kind: "Thing", lexicon: "fake", attrs: { _status: "warn", _overlay: "foreign", peer: { $ref: "Queue" } } },
+    ],
+    edges: [],
+    groups: {},
+    meta: { _behaviour: { engine: "fixture", traffic: "100 rps" } },
+  };
+  const liveWorkspace = () =>
+    repo({
+      "chant.workspace.json": declaration([
+        { name: "api", dir: "api", kind: "chant" },
+        { name: "docs", dir: "docs", kind: "other", because: "prose" },
+      ]),
+      "api/chant.config.ts": "export default {};\n",
+      "api/ir.json": JSON.stringify(source),
+      "api/live.json": JSON.stringify(live),
+      "docs/README.md": "",
+      ".gitignore": "node_modules\n",
+      "node_modules/.bin/chant": { text: FAKE_LIVE_CHANT, mode: 0o755 },
+    });
+
+  test("hands --live, --overlay and --traffic to every member, and marks each member read live", async () => {
+    const root = liveWorkspace();
+    const before = Date.now();
+    const { doc, failed } = await workspaceGraph({ cwd: root, args: { env: "prod", live: true, overlay: true, traffic: "100 rps" } });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    expect(readFileSync(join(root, "argv.txt"), "utf-8").trim()).toBe("graph . --format ir --env prod --live --overlay --traffic 100 rps");
+    const api = g.members.find((m) => m.name === "api")!;
+    expect(api).toMatchObject({ status: "composed", live: true });
+    expect(Date.parse(api.readAt!)).toBeGreaterThanOrEqual(before - 1000);
+    expect(g.members.find((m) => m.name === "docs")).toMatchObject({ status: "skipped", live: false });
+    expect(g.members.find((m) => m.name === "docs")!.readAt).toBeUndefined();
+  });
+
+  test("the drift, overlay and behaviour a member's chant wrote pass through composition untouched", async () => {
+    const { doc } = await workspaceGraph({ cwd: liveWorkspace(), args: { env: "prod", live: true, overlay: true } });
+    const g = result(doc);
+    expect(g.nodes.find((n) => n.id === "api/Queue")!.attrs).toEqual(live.nodes[0].attrs);
+    // Only $ref values are prefixed; every other attribute is as the member printed it.
+    expect(g.nodes.find((n) => n.id === "api/Stray")!.attrs).toEqual({ _status: "warn", _overlay: "foreign", peer: { $ref: "api/Queue" } });
+    expect(g.members.find((m) => m.name === "api")!.meta).toEqual(live.meta);
+  });
+
+  test("a source read marks every member not live, with no read time", async () => {
+    const { doc } = await workspaceGraph({ cwd: liveWorkspace() });
+    const g = result(doc);
+    expectValid(g);
+    expect(g.members.map((m) => [m.name, m.live, m.readAt ?? null])).toEqual([["api", false, null], ["docs", false, null]]);
+    expect(g.nodes.map((n) => n.id)).toEqual(["api/Queue"]);
+  });
+
+  test("a live read bypasses the member cache: it is never served from it and never stored (#2876)", async () => {
+    const root = liveWorkspace();
+    // Past the cache's freshness window, so a source read is stored.
+    age(root);
+    // A source read fills the cache; the live read after it still runs the member.
+    await workspaceGraph({ cwd: root });
+    const argv = join(root, "argv.txt");
+    rmSync(argv);
+    const live1 = result((await workspaceGraph({ cwd: root, args: { env: "prod", live: true, overlay: true } })).doc);
+    expect(existsSync(argv)).toBe(true);
+    expect(live1.members.find((m) => m.name === "api")).toMatchObject({ live: true, cached: false, stamp: null });
+    expect(live1.nodes.map((n) => n.id)).toEqual(["api/Queue", "api/Stray"]);
+    // A second live read runs again: nothing from the first was stored.
+    rmSync(argv);
+    const live2 = result((await workspaceGraph({ cwd: root, args: { env: "prod", live: true, overlay: true } })).doc);
+    expect(existsSync(argv)).toBe(true);
+    expect(live2.members.find((m) => m.name === "api")).toMatchObject({ live: true, cached: false });
+    // And the source read is still served as before, with no live attributes.
+    const again = result((await workspaceGraph({ cwd: root })).doc);
+    expect(again.members.find((m) => m.name === "api")).toMatchObject({ live: false, cached: true });
+    expect(again.nodes.map((n) => n.id)).toEqual(["api/Queue"]);
+  });
+
+  test("--live with --at is refused with live-at-revision, and runs no member", async () => {
+    const root = liveWorkspace();
+    commitAll(root);
+    const { doc, failed } = await workspaceGraph({ cwd: root, at: "HEAD", args: { env: "prod", live: true } });
+    expectValid(doc);
+    expect(failed).toBe(true);
+    expect("error" in doc && doc.error.code).toBe("live-at-revision");
+    expect(existsSync(join(root, "argv.txt"))).toBe(false);
+  });
+});

package/src/workspace/graph.schema.json

@@ -305,6 +305,25 @@
           ],
           "description": "The IR version the member printed, or null when it printed none and was read as version 1."
         },
+        "live": {
+          "type": "boolean",
+          "description": "Whether the member was read with --live (#2875): its graph is the account as it stands, and its nodes carry whatever _drift, _overlay and _behaviour attributes its chant wrote. false for a source read and for a member that did not run. A document from a chant before #2875 has no live field, and a reader may take that as false."
+        },
+        "readAt": {
+          "type": "string",
+          "description": "For a live read, as an ISO 8601 time: when the member's read finished. A live member of a toolchain whose member-run names no time gets the time its toolchain's process ended."
+        },
+        "cached": {
+          "type": "boolean",
+          "description": "Whether chant's per-member cache answered this read (#2876). Present on composed members. A cached read is the output the member's own chant printed for the same stamp, toolchain, command line and environment."
+        },
+        "stamp": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the per-member cache keys this read on (#2876): sha256 over the member's files and install state, or over the commit id with --at. Present on composed members; null for a live read or when no stamp could be taken. Two reads of a member with equal stamps read the same source."
+        },
         "meta": {
           "type": "object",
           "description": "The member IR's whole-read facts."
@@ -460,7 +479,8 @@
                 "reader-too-old",
                 "root-chant-required",
                 "not-a-git-repository",
-                "revision-unknown"
+                "revision-unknown",
+                "live-at-revision"
               ]
             },
             "message": {

package/src/workspace/kind-readers.e2e.test.ts

@@ -0,0 +1,68 @@
+/**
+ * `chant workspace graph` reads `terraform` and `choudoufu` members through
+ * the terraform lexicon (#2874), end to end: the lexicon's own kinds file,
+ * this checkout's chant as the members' toolchain, and a real HCL parse.
+ *
+ * The workspace links this checkout's `node_modules`, where the lexicon is
+ * installed, and pins it at its version. Its `net` root calls
+ * `../modules/subnets`, which lies outside the member but inside the
+ * workspace, so the module's resources are only read when the reader
+ * project's `moduleRoot` is the workspace root.
+ */
+
+import { readFileSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, declaration, REPO, repo } from "./__fixtures__/contract-repo";
+import { workspaceGraph, type GraphDocument } from "./graph-cli";
+import schema from "./graph.schema.json";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+const TIMEOUT = 240_000;
+const LEXICON = "@intentius/chant-lexicon-terraform";
+const VERSION = (JSON.parse(readFileSync(join(REPO, "lexicons", "terraform", "package.json"), "utf-8")) as { version: string }).version;
+
+function result(doc: GraphDocument): Extract<GraphDocument, { nodes: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("terraform and choudoufu members through the terraform lexicon (#2874)", () => {
+  test(
+    "compose with <member>/<root>/<address> ids, their local modules included",
+    async () => {
+      const root = repo({
+        "chant.workspace.json": declaration(
+          [
+            { name: "net", dir: "estates/net", kind: "terraform" },
+            { name: "shop", dir: "estates/shop", kind: "choudoufu" },
+          ],
+          { pins: [{ package: LEXICON, version: VERSION }] },
+        ),
+        "estates/net/main.tf": 'resource "aws_vpc" "main" {\n  cidr_block = "10.0.0.0/16"\n}\n\nmodule "subnets" {\n  source = "../modules/subnets"\n  vpc_id = aws_vpc.main.id\n}\n',
+        "estates/modules/subnets/main.tf": 'variable "vpc_id" {}\n\nresource "aws_subnet" "a" {\n  vpc_id     = var.vpc_id\n  cidr_block = "10.0.1.0/24"\n}\n',
+        "estates/shop/estate.chdf.hcl": 'estate = "shop"\n',
+        "estates/shop/main.tf": 'resource "aws_sns_topic" "orders" {\n  name = "orders"\n}\n',
+        ".gitignore": "node_modules\n",
+      });
+      symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir");
+
+      const { doc, failed } = await workspaceGraph({ cwd: root });
+      const g = result(doc);
+      expectValid(g);
+      expect(g.members.map((m) => [m.name, m.kind, m.status, m.reason?.message ?? null])).toEqual([
+        ["net", "terraform", "composed", null],
+        ["shop", "choudoufu", "composed", null],
+      ]);
+      expect(failed).toBe(false);
+      const ids = g.nodes.map((n) => n.id);
+      expect(ids).toContain("net/net/aws_vpc.main");
+      expect(ids).toContain("net/net/module.subnets/aws_subnet.a");
+      expect(ids).toContain("shop/shop/aws_sns_topic.orders");
+      expect(g.groups.byMember.net).toContain("net/net/module.subnets/aws_subnet.a");
+    },
+    TIMEOUT,
+  );
+});

package/src/workspace/kind-readers.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Members of a package's kind read through a reader project (#2874).
+ *
+ * The workspace pins a fake lexicon package whose kinds file carries a
+ * `graph` block, and its members run under a fake chant installed in the
+ * workspace's `node_modules/.bin`. That chant answers `chant graph` in the
+ * reader project with one node carrying what it found there: the config
+ * chant wrote, whether the lexicon resolves through `node_modules`, and its
+ * own directory, so a test can check the project is gone afterwards. The
+ * real terraform lexicon runs in `kind-readers.e2e.test.ts`.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, declaration, repo } from "./__fixtures__/contract-repo";
+import { workspaceGraph, type GraphDocument } from "./graph-cli";
+import { planMembers } from "./member-commands";
+import { loadKindRegistry } from "./kinds";
+import schema from "./graph.schema.json";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+function result(doc: GraphDocument): Extract<GraphDocument, { nodes: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+/** Prints one node whose attrs hold the reader project's config, whether the lexicon resolves, the argv, and the directory. */
+const READER_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+if [ -f node_modules/@intentius/chant-lexicon-fake/package.json ]; then found=true; else found=false; fi
+printf '{"version":1,"nodes":[{"id":"root/Thing","kind":"Thing","lexicon":"fake","attrs":{"found":%s,"pwd":"%s","argv":"%s","config":' "$found" "$(pwd -P)" "$*"
+cat chant.config.json
+printf '}}],"edges":[],"groups":{"byLexicon":{"fake":["root/Thing"]}}}\\n'
+`;
+
+const GRAPH = { lexicon: "fake", config: { moduleRoot: "{workspace}", roots: { "{member}": { dir: "{dir}" } } } };
+
+function lexiconPackage(name: string, kinds: unknown[]): Record<string, string> {
+  return {
+    [`node_modules/${name}/package.json`]: JSON.stringify({ name, version: "1.0.0", exports: { ".": "./index.js", "./workspace-kinds": "./workspace-kinds.json" } }),
+    [`node_modules/${name}/workspace-kinds.json`]: JSON.stringify({ schema: 1, kinds }),
+  };
+}
+
+const TF_KIND = { name: "tf", description: "a root", precedence: 400, probe: { anyFile: ["*.tf"] }, graph: GRAPH };
+
+function workspace(extra: Record<string, string | { text: string; mode: number }> = {}, pins = [{ package: "@intentius/chant-lexicon-fake", version: "1.0.0" }]): string {
+  return repo({
+    "chant.workspace.json": declaration(
+      [
+        { name: "net", dir: "estates/net", kind: "tf" },
+        { name: "docs", dir: "docs", kind: "other", because: "prose" },
+      ],
+      { pins },
+    ),
+    "estates/net/main.tf": 'module "vpc" { source = "../modules/vpc" }\n',
+    "estates/modules/vpc/main.tf": "",
+    "docs/README.md": "",
+    ".gitignore": "node_modules\n",
+    "node_modules/.bin/chant": { text: READER_CHANT, mode: 0o755 },
+    ...lexiconPackage("@intentius/chant-lexicon-fake", [TF_KIND]),
+    ...extra,
+  });
+}
+
+describe("workspace graph reads a package kind with a graph block (#2874)", () => {
+  test("in a reader project of its own, with the kind's config substituted and the pinned lexicon linked", async () => {
+    const root = workspace();
+    const { doc, failed } = await workspaceGraph({ cwd: root, args: { env: "prod" } });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    expect(g.members.map((m) => [m.name, m.kind, m.status, m.reason?.code ?? null])).toEqual([
+      ["net", "tf", "composed", null],
+      ["docs", "other", "skipped", "kind-not-run"],
+    ]);
+    expect(g.nodes.map((n) => n.id)).toEqual(["net/root/Thing"]);
+    const attrs = g.nodes[0].attrs as { found: boolean; pwd: string; argv: string; config: Record<string, unknown> };
+    expect(attrs.config).toEqual({ lexicons: ["fake"], fake: { moduleRoot: root, roots: { net: { dir: `${root}/estates/net` } } } });
+    expect(attrs.found).toBe(true);
+    // A reader project declares no environments, so --env stays with the chant members.
+    expect(attrs.argv).toBe("graph . --format ir");
+    expect(attrs.pwd.startsWith(root)).toBe(false);
+    expect(existsSync(attrs.pwd)).toBe(false);
+  });
+
+  test("--at points the reader at the revision's tree", async () => {
+    const root = workspace();
+    const sha = commitAll(root);
+    const g = result((await workspaceGraph({ cwd: root, at: sha })).doc);
+    expectValid(g);
+    const config = (g.nodes[0].attrs as { config: { fake: { moduleRoot: string; roots: { net: { dir: string } } } } }).config.fake;
+    expect(config.moduleRoot).not.toBe(root);
+    expect(config.roots.net.dir).toBe(`${config.moduleRoot}/estates/net`);
+  });
+
+  test("a lexicon found somewhere other than its pin fails the member with command-failed, and the rest still run", async () => {
+    const root = workspace(
+      { "plugins/fake/package.json": JSON.stringify({ name: "@intentius/chant-lexicon-fake", version: "1.0.0", exports: { "./workspace-kinds": "./workspace-kinds.json" } }), "plugins/fake/workspace-kinds.json": JSON.stringify({ schema: 1, kinds: [TF_KIND] }) },
+      [{ path: "plugins/fake" } as never],
+    );
+    const { doc, failed } = await workspaceGraph({ cwd: root });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(true);
+    const net = g.members.find((m) => m.name === "net")!;
+    expect(net).toMatchObject({ status: "failed", reason: { code: "command-failed" } });
+    expect(net.reason!.message).toMatch(/install the pinned package/);
+    expect(g.members.find((m) => m.name === "docs")).toMatchObject({ status: "skipped" });
+  });
+
+  test("a member whose directory the kind's probe doesn't claim is kind-probe-failed, and nothing runs", async () => {
+    const root = workspace();
+    rmSync(join(root, "estates", "net", "main.tf"));
+    const g = result((await workspaceGraph({ cwd: root })).doc);
+    expect(g.members.find((m) => m.name === "net")).toMatchObject({ status: "failed", reason: { code: "kind-probe-failed" } });
+    expect(g.nodes).toEqual([]);
+  });
+
+  test("build, lint and audit still skip the kind with kind-not-run", () => {
+    const root = workspace();
+    const { registry } = loadKindRegistry([{ package: "@intentius/chant-lexicon-fake", version: "1.0.0", path: null }], root);
+    for (const verb of ["build", "lint", "audit"] as const) {
+      const plan = planMembers(verb, root, { kinds: registry });
+      expect(plan.groups).toEqual([]);
+      expect(plan.skipped.find((s) => s.name === "net")?.reason.code).toBe("kind-not-run");
+    }
+    expect(planMembers("graph", root, { kinds: registry }).groups[0].units[0].reader).toMatchObject({ lexicon: "fake" });
+  });
+});

package/src/workspace/kind-readers.ts

@@ -0,0 +1,111 @@
+/**
+ * Reader projects for members of a package's kind (#2874).
+ *
+ * `chant workspace graph` runs `chant graph` in each member. A `terraform` or
+ * `choudoufu` member is a directory of `.tf` files with no chant config, so
+ * there is nothing for it to run. The kind's `graph` block in the package's
+ * kinds file says how to read one instead: a lexicon and that lexicon's
+ * config namespace. For each such member chant writes a reader project of its
+ * own, outside the workspace, and the member runs there:
+ *
+ * - `chant.config.json` declares the lexicon, and puts the kind's config under
+ *   the lexicon's key with `{member}`, `{dir}` and `{workspace}` substituted
+ *   (`substituteGraphConfig`). The terraform lexicon's config names one root
+ *   after the member, at the member's directory, with `moduleRoot` at the
+ *   workspace root, so a member that calls `../modules/x` keeps its modules.
+ * - `node_modules` links to the `node_modules` directory holding the lexicon
+ *   package, found from the workspace root as the kind's pin was. The lexicon
+ *   chant loads is then the one the declaration pins.
+ *
+ * Nothing is written under the workspace, and the projects are removed when
+ * the read ends. A lexicon that can't be found where its pin says fails the
+ * member with `command-failed` and says what to install; the other members
+ * still run.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findInstalledPackage, lexiconPackageName, substituteGraphConfig } from "./kinds";
+import type { MemberPlan, RunUnit, SkippedEntry } from "./member-commands";
+
+export interface PreparedReaders {
+  /** Members whose reader project couldn't be written, with the reason. They fail the run. */
+  failed: SkippedEntry[];
+  /** Remove every reader project. Safe to call more than once. */
+  cleanup(): void;
+}
+
+/** The `node_modules` directory an installed package sits in. */
+function nodeModulesOf(packageDir: string, name: string): string {
+  let dir = packageDir;
+  for (let i = 0; i < name.split("/").length; i++) dir = join(dir, "..");
+  return dir;
+}
+
+function real(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** Why a unit's lexicon can't be loaded from `root`, or the `node_modules` to link. */
+function lexiconModules(unit: RunUnit, root: string): { modules: string } | { message: string } {
+  const reader = unit.reader!;
+  const name = lexiconPackageName(reader.lexicon);
+  const installed = findInstalledPackage(name, root);
+  if (!installed) {
+    return {
+      message: `kind ${unit.kind} is read by the ${reader.lexicon} lexicon, and ${name} is not installed in a node_modules at or above ${root}; install it there to read this member`,
+    };
+  }
+  if (real(installed) !== real(reader.packageDir)) {
+    return {
+      message: `kind ${unit.kind} comes from ${reader.packageDir}, and the ${name} found from ${root} is ${real(installed)}; install the pinned package where the workspace resolves it`,
+    };
+  }
+  return { modules: nodeModulesOf(installed, name) };
+}
+
+/**
+ * Write a reader project for every unit of `plan` that has a `reader`, and
+ * point the unit's `abs` at it. Units that can't get one leave the plan and
+ * are returned in `failed`. `root` is the directory the plan was made from,
+ * the exported tree for `--at`.
+ */
+export function prepareKindReaders(plan: MemberPlan, root: string): PreparedReaders {
+  const failed: SkippedEntry[] = [];
+  let scratch: string | undefined;
+  const cleanup = () => {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+    scratch = undefined;
+  };
+  try {
+    for (const group of plan.groups) {
+      group.units = group.units.filter((unit) => {
+        if (!unit.reader) return true;
+        const found = lexiconModules(unit, root);
+        if ("message" in found) {
+          failed.push({ name: unit.member, dir: unit.dir, kind: unit.kind, reason: { code: "command-failed", message: found.message } });
+          return false;
+        }
+        scratch ??= mkdtempSync(join(tmpdir(), "chant-ws-reader-"));
+        const project = join(scratch, unit.id);
+        mkdirSync(project, { recursive: true });
+        const config = substituteGraphConfig(unit.reader.config, { member: unit.member, dir: unit.abs, workspace: root });
+        writeFileSync(join(project, "chant.config.json"), `${JSON.stringify({ lexicons: [unit.reader.lexicon], [unit.reader.lexicon]: config }, null, 2)}\n`);
+        symlinkSync(found.modules, join(project, "node_modules"), "dir");
+        unit.abs = project;
+        return true;
+      });
+    }
+    plan.groups = plan.groups.filter((g) => g.units.length > 0);
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+  plan.unreadable.push(...failed);
+  return { failed, cleanup };
+}

package/src/workspace/kinds.test.ts

@@ -17,6 +17,7 @@ import {
   probeKind,
   readPackageKinds,
   resolveKind,
+  substituteGraphConfig,
   type MemberKind,
 } from "./kinds";
 import schema from "./workspace-kinds.schema.json";
@@ -114,6 +115,54 @@ describe("parseKindData", () => {
   });
 });
 
+describe("a kind's graph block (#2874)", () => {
+  const graph = { lexicon: "tf", config: { moduleRoot: "{workspace}", roots: { "{member}": { dir: "{dir}" } } } };
+
+  test("is read as data, and refuses a field it doesn't know", () => {
+    const data = parseKindData(kindsFile([{ ...tf, graph }]), "p");
+    expect(data.problems).toEqual([]);
+    expect(data.kinds[0].graph).toEqual(graph);
+    expect(parseKindData(kindsFile([{ ...tf, graph: { ...graph, run: "x" } }]), "p").problems[0]).toMatch(/additional properties/);
+    expect(parseKindData(kindsFile([{ ...tf, graph: { lexicon: "Bad Name", config: {} } }]), "p").problems[0]).toMatch(/lexicon/);
+    expect(parseKindData(kindsFile([{ ...tf, graph: { lexicon: "tf" } }]), "p").problems[0]).toMatch(/config/);
+  });
+
+  test("substitutes {member}, {dir} and {workspace} in keys and values, and nothing else", () => {
+    const out = substituteGraphConfig(
+      { moduleRoot: "{workspace}", roots: { "{member}": { dir: "{dir}", note: "{other} at {dir}/x" } }, list: ["{member}", 3, true, null] },
+      { member: "net", dir: "/ws/estates/net", workspace: "/ws" },
+    );
+    expect(out).toEqual({ moduleRoot: "/ws", roots: { net: { dir: "/ws/estates/net", note: "{other} at /ws/estates/net/x" } }, list: ["net", 3, true, null] });
+  });
+
+  test("records the supplying package, and is dropped with a problem when the lexicon is not that package", () => {
+    const root = dir({
+      ...pkg("@intentius/chant-lexicon-tf", "1.0.0", [{ ...tf, graph }]),
+      ...pkg("@acme/other", "1.0.0", [{ ...tf, name: "other-tf", graph }]),
+    });
+    const good = loadKindRegistry([{ package: "@intentius/chant-lexicon-tf", version: "1.0.0", path: null }], root);
+    expect(good.problems).toEqual([]);
+    expect(good.registry.get("terraform")).toMatchObject({ graph, packageDir: join(root, "node_modules/@intentius/chant-lexicon-tf") });
+
+    const bad = loadKindRegistry([{ package: "@acme/other", version: "1.0.0", path: null }], root);
+    expect(bad.problems.map((p) => p.message)).toEqual([expect.stringMatching(/other-tf reads its members with lexicon tf, which is @intentius\/chant-lexicon-tf, and this package is @acme\/other/)]);
+    expect(bad.registry.get("other-tf")?.graph).toBeUndefined();
+    expect(bad.registry.get("other-tf")).toBeDefined();
+  });
+
+  test("the terraform lexicon's kinds read their members with it, named for the member at the workspace root", () => {
+    const lexicon = join(import.meta.dirname, "..", "..", "..", "..", "lexicons", "terraform");
+    const read = readPackageKinds(lexicon);
+    expect(read.problems).toEqual([]);
+    for (const name of ["terraform", "choudoufu"]) {
+      const k = read.kinds.find((x) => x.name === name)!;
+      expect(k.graph?.lexicon).toBe("terraform");
+      expect(substituteGraphConfig(k.graph!.config, { member: "net", dir: "/ws/net", workspace: "/ws" })).toMatchObject({ moduleRoot: "/ws", roots: { net: { dir: "/ws/net" } } });
+    }
+    expect(read.kinds.find((x) => x.name === "choudoufu")!.graph!.config.binary).toBe("choudoufu");
+  });
+});
+
 describe("reading a package's kinds", () => {
   test("follows only the literal ./workspace-kinds key, and only to a JSON file inside the package", () => {
     expect(kindsExportTarget({ exports: { "./*": "./src/*.ts" } })).toBeUndefined();