@intentius/chant 0.124.44 → 0.124.46

package/src/workspace/declaration.ts

@@ -335,6 +335,12 @@ export interface CiPrEnvironment {
   template: string;
   /** How long the environment lives after its last apply: `72h` when absent. */
   ttl: string;
+  /**
+   * A command that tears down what no lexicon does (#4330), such as a
+   * Terraform root's copy: run by `pr-env down` and `pr-env sweep` after the
+   * ownership check (../components/pr-env-run.ts, `commandTeardownAdapter`).
+   */
+  teardown?: { name?: string; command: string[]; lexicons?: string[] };
 }
 
 /** The default `ci.prEnvironment.ttl`. */
@@ -1260,7 +1266,7 @@ function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, ke
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
   const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
   const policy = ciPolicyOf(block.policy, at);
   const workflow = {
@@ -1271,7 +1277,23 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
     ...(block.locks !== undefined ? { locks: block.locks } : {}),
     ...(policy ? { policy } : {}),
     ...(block.identity?.cloud !== undefined ? { identity: { cloud: cloudIdentityOf(block.identity.cloud, at) } } : {}),
-    ...(block.prEnvironment !== undefined ? { prEnvironment: { template: block.prEnvironment.template, ttl: block.prEnvironment.ttl ?? DEFAULT_PR_ENVIRONMENT_TTL } } : {}),
+    ...(block.prEnvironment !== undefined
+      ? {
+          prEnvironment: {
+            template: block.prEnvironment.template,
+            ttl: block.prEnvironment.ttl ?? DEFAULT_PR_ENVIRONMENT_TTL,
+            ...(block.prEnvironment.teardown !== undefined
+              ? {
+                  teardown: {
+                    ...(block.prEnvironment.teardown.name !== undefined ? { name: block.prEnvironment.teardown.name } : {}),
+                    command: [...block.prEnvironment.teardown.command],
+                    ...(block.prEnvironment.teardown.lexicons !== undefined ? { lexicons: [...block.prEnvironment.teardown.lexicons] } : {}),
+                  },
+                }
+              : {}),
+          },
+        }
+      : {}),
   };
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {

package/src/workspace/graph-cache.ts

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

package/src/workspace/graph-cli.ts

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

package/src/workspace/graph.schema.json

@@ -437,6 +437,17 @@
               }
             }
           ]
+        },
+        "capabilityView": {
+          "description": "Added in contract 1 by #4378. Only with `--capability-view`, which `chant workspace search` asks for when a query has a capability term. The lexicon-neutral view capability rules read, built by the member's own chant through the mappings and adapters of the lexicons the member loads (its `chant graph --format ir --capability-view`), with `<member>/<id>` ids. null on a composed member whose chant printed no view (one from before #4378); a capability search reports that member as `member-chant-too-old`. Absent without the flag, and on a member that was not composed.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/capabilityView"
+            }
+          ]
         }
       },
       "if": {
@@ -1438,6 +1449,143 @@
           ]
         }
       }
+    },
+    "capabilityView": {
+      "type": "object",
+      "description": "One member's capability view (#4378), as `capabilities/view.ts` serializes it. Rules read labels, attributes and edges; a node's attributes are the neutral ones its lexicon's mapping names.",
+      "required": [
+        "version",
+        "lexicons",
+        "nodes",
+        "edges",
+        "unresolved"
+      ],
+      "properties": {
+        "version": {
+          "const": 1,
+          "description": "The view's own format version. A reader treats a view of a version it doesn't know as no view."
+        },
+        "lexicons": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The lexicons whose nodes a mapping labelled."
+        },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "label",
+              "irId",
+              "lexicon",
+              "attrs"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "A node id of the composed graph, or, for a policy statement or an inline block, that id with `#<attribute path>`."
+              },
+              "label": {
+                "type": "string",
+                "description": "The neutral label (`Role`, `Bucket`, `Statement`, `IngressRule`)."
+              },
+              "irId": {
+                "type": "string",
+                "description": "The composed graph node this view node is, or sits inside."
+              },
+              "lexicon": {
+                "type": "string"
+              },
+              "attrs": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "from",
+              "to",
+              "name",
+              "hops"
+            ],
+            "properties": {
+              "from": {
+                "type": "string"
+              },
+              "to": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string",
+                "description": "The view edge's name (`subnet`, `statement`, `resource`, `attachedTo`)."
+              },
+              "hops": {
+                "type": "array",
+                "description": "The graph references the edge stands for, in walk order from `from`, each in the reference's own direction.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "from",
+                    "to",
+                    "edge"
+                  ],
+                  "properties": {
+                    "from": {
+                      "type": "string"
+                    },
+                    "fromAttr": {
+                      "type": "string"
+                    },
+                    "to": {
+                      "type": "string"
+                    },
+                    "toAttr": {
+                      "type": "string"
+                    },
+                    "edge": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "unresolved": {
+          "type": "array",
+          "description": "ARN strings naming a role, bucket or table that the member declares nothing of. `chant workspace search` resolves them by name over every member's view, so a policy in one member reaches a bucket in another.",
+          "items": {
+            "type": "object",
+            "required": [
+              "from",
+              "fromAttr",
+              "edge",
+              "value"
+            ],
+            "properties": {
+              "from": {
+                "type": "string"
+              },
+              "fromAttr": {
+                "type": "string"
+              },
+              "edge": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -65,4 +65,32 @@ describe("terraform and choudoufu members through the terraform lexicon (#2874)"
     },
     TIMEOUT,
   );
+
+  // behold#919: the reader project sets `graph.lint: "report"`, so a member
+  // whose HCL fails one of the lexicon's error rules is composed, with the
+  // finding on its meta.lint. Before, it failed with command-failed.
+  test(
+    "a member with a lint error is composed, the finding on its meta.lint",
+    async () => {
+      const root = repo({
+        "chant.workspace.json": declaration([{ name: "db", dir: "estates/db", kind: "terraform" }], { pins: [{ package: LEXICON, version: VERSION }] }),
+        "estates/db/main.tf":
+          'resource "aws_db_instance" "orders" {\n  identifier        = "orders"\n  engine            = "postgres"\n  instance_class    = "db.t3.micro"\n  allocated_storage = 20\n  storage_encrypted = false\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.status, m.reason?.code ?? null])).toEqual([["db", "composed", null]]);
+      expect(failed).toBe(false);
+      expect(g.nodes.map((n) => n.id)).toContain("db/db/aws_db_instance.orders");
+      const lint = (g.members[0] as { meta?: { lint?: { errors: number; findings: { ruleId: string; severity: string; entity?: string }[] } } }).meta?.lint;
+      expect(lint?.errors).toBeGreaterThanOrEqual(1);
+      // The finding names its entity, the id the member IR gives the node (before composition prefixes it).
+      expect(lint?.findings).toContainEqual(expect.objectContaining({ ruleId: "TF033", severity: "error", entity: "db/aws_db_instance.orders" }));
+    },
+    TIMEOUT,
+  );
 });

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

@@ -80,7 +80,7 @@ describe("workspace graph reads a package kind with a graph block (#2874)", () =
     ]);
     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.config).toEqual({ lexicons: ["fake"], fake: { moduleRoot: root, roots: { net: { dir: `${root}/estates/net` } } }, graph: { lint: "report" } });
     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");

package/src/workspace/kind-readers.ts

@@ -13,6 +13,9 @@
  *   (`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.
+ * - It also sets `graph.lint: "report"` (behold#919), so a member whose
+ *   source fails the lexicon's lint is still composed, with the findings on
+ *   its `meta.lint`, instead of failing with `command-failed`.
  * - `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.
@@ -95,7 +98,10 @@ export function prepareKindReaders(plan: MemberPlan, root: string): PreparedRead
         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`);
+        // `graph.lint: "report"` (behold#919): chant did not author a reader
+        // member's source, so a lint error there is a finding about it, carried
+        // on the member's `meta.lint`, not a reason to leave it out of the graph.
+        writeFileSync(join(project, "chant.config.json"), `${JSON.stringify({ lexicons: [unit.reader.lexicon], [unit.reader.lexicon]: config, graph: { lint: "report" } }, null, 2)}\n`);
         symlinkSync(found.modules, join(project, "node_modules"), "dir");
         unit.abs = project;
         return true;

package/src/workspace/member-commands.ts

@@ -12,7 +12,10 @@
  * - For `graph` only, members of a pinned package's kind whose kinds file
  *   says how to read them (#2874, a `graph` block): each runs `chant graph`
  *   in a reader project chant writes for it (`kind-readers.ts`). Other
- *   package kinds are `kind-not-run`, as before.
+ *   package kinds are `kind-not-run`, as before. A kind no built-in or
+ *   pinned package supplies, such as `terraform` when the pinned lexicon is
+ *   missing or at another version, is `unknown-kind` and fails the read,
+ *   with the pin's problem in the message (#4380).
  * - For `build` and `lint` only, every project an example group matches
  *   (ws-051): groups are built and linted, and have no ledger, audit or place
  *   in the graph. On a large repository this is most of the run, so
@@ -155,6 +158,12 @@ export interface PlanOptions {
   reader?: Toolchain;
   /** The files to plan from, such as a revision's (`--at`); the working tree under `root` by default. */
   tree?: WorkspaceTree;
+  /**
+   * Why a pinned package's kinds couldn't be loaded (`loadKindRegistry`'s
+   * problems), such as a pin at one version with another installed. A graph
+   * read names them on a member whose kind is unknown (#4380).
+   */
+  kindProblems?: readonly string[];
 }
 
 /** Work out which projects run and under which chant. Throws a {@link WorkspaceReadError} for an unreadable declaration or an unknown `--member` name. */
@@ -218,6 +227,16 @@ export function planMembers(verb: WorkspaceVerb, root: string, options: PlanOpti
       });
       continue;
     }
+    // A kind no built-in or pinned package supplies is unknown, not a kind
+    // the read leaves out (#4380): a terraform member whose pinned lexicon is
+    // missing or at another version said kind-not-run before, as if the graph
+    // never read its kind. Say why, the pin's problem included.
+    if (verb === "graph" && !kinds.get(entry.kind)) {
+      const reason = memberReason(entry, tree, kinds) ?? { code: "unknown-kind", message: `no built-in kind or pinned package supplies kind ${entry.kind}` };
+      const problems = reason.code === "unknown-kind" ? (options.kindProblems ?? []) : [];
+      unreadable.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason: problems.length ? { ...reason, message: `${reason.message}; ${problems.join("; ")}` } : reason });
+      continue;
+    }
     if (entry.kind !== "chant") {
       const why =
         entry.kind === "workspace"
@@ -308,6 +327,8 @@ export function memberArgv(verb: WorkspaceVerb, unit: RunUnit, args: ParsedArgs)
     // The detail tier too, so `workspace graph --detail 1` composes collapsed
     // composites with their rolled-up status (#4228).
     if (args.detail !== undefined) argv.push("--detail", String(args.detail));
+    // Each member's chant maps its own capability view (#4378).
+    if (args.capabilityView) argv.push("--capability-view");
   }
   return argv;
 }

package/src/workspace/nested-graph.ts

@@ -22,6 +22,7 @@
 
 import { spawn } from "node:child_process";
 import type { ParsedArgs } from "../cli/registry";
+import { isViewDocument, prefixView, VIEW_DOCUMENT_VERSION } from "../capabilities/view";
 import { danglingKey, SCOPED_GROUPS, type ComposedMember, type ComposedNode, type WorkspaceGraph } from "./compose-graph";
 
 export type { NestedWorkspace } from "./compose-graph";
@@ -45,6 +46,7 @@ export function nestedArgv(dir: string, args: Partial<ParsedArgs>, at: string |
     ...(args.traffic !== undefined ? ["--traffic", String(args.traffic)] : []),
     ...(args.detail !== undefined ? ["--detail", String(args.detail)] : []),
     ...(args.noCache ? ["--no-cache"] : []),
+    ...(args.capabilityView ? ["--capability-view"] : []),
   ];
 }
 
@@ -97,10 +99,21 @@ export async function readNested(
   contract: number,
   toolchain: Toolchain | undefined = undefined,
 ): Promise<NestedRead & { stderr: string }> {
-  const r = await spawnRead((toolchain ?? readerToolchain()).command, nestedArgv(abs, args, at), abs);
+  const command = (toolchain ?? readerToolchain()).command;
+  let r = await spawnRead(command, nestedArgv(abs, args, at), abs);
+  // A nested chant from before #4378 has no --capability-view: read it
+  // without, and its members carry no view.
+  if (args.capabilityView && r.exitCode !== 0 && refusedCapabilityView(r.stderr)) {
+    r = await spawnRead(command, nestedArgv(abs, { ...args, capabilityView: false }, at), abs);
+  }
   return { ...readNestedDocument(r.stdout, r.exitCode, r.stderr, schemaId, contract), stderr: r.stderr };
 }
 
+/** Whether a chant refused `--capability-view` as a flag it doesn't know (#4378): one from before it. */
+export function refusedCapabilityView(stderr: string): boolean {
+  return /Unknown flag:?\s*--capability-view/i.test(stderr);
+}
+
 const prefixed = (outer: string, id: string): string => `${outer}/${id}`;
 
 function prefixRefs(value: unknown, outer: string): unknown {
@@ -141,6 +154,24 @@ export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner:
   for (const e of inner.exports ?? []) graph.exports.push({ ...e, ...(e.node ? { node: prefixed(outer, e.node) } : {}), member: outer });
   for (const i of inner.imports ?? []) graph.imports.push({ ...i, node: prefixed(outer, i.node), member: outer });
   graph.groups.byMember[outer] = ids.sort();
+  // The capability view (#4378): each nested member's, under the outer id. A
+  // nested member that read without one leaves the outer member without one.
+  const composedInner = inner.members.filter((m) => m.status === "composed");
+  if (composedInner.some((m) => m.capabilityView !== undefined)) {
+    const views = composedInner.map((m) => m.capabilityView);
+    if (views.every(isViewDocument)) {
+      const ps = views.map((v) => prefixView(v, `${outer}/`));
+      member.capabilityView = {
+        version: VIEW_DOCUMENT_VERSION,
+        lexicons: [...new Set(ps.flatMap((v) => v.lexicons))].sort(),
+        nodes: ps.flatMap((v) => v.nodes),
+        edges: ps.flatMap((v) => v.edges),
+        unresolved: ps.flatMap((v) => v.unresolved),
+      };
+    } else {
+      member.capabilityView = null;
+    }
+  }
   const groups = graph.groups as unknown as Record<string, Record<string, string[]> | undefined>;
   const innerGroups = inner.groups as unknown as Record<string, Record<string, string[]> | undefined>;
   for (const key of ["byLexicon", "byComposite"] as const) {

package/src/workspace/reason-codes.test.ts

@@ -55,6 +55,8 @@ import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
 import { METRICS_ERROR_CODES, METRICS_REASON_CODES } from "./delivery-metrics";
+import { SEARCH_ERROR_CODES, SEARCH_MEMBER_REASON_CODES, WORKSPACE_SEARCH_ERROR_CODES } from "./search-contract";
+import { CAPABILITIES_ERROR_CODES, CAPABILITY_SUPPORT_CODES } from "./capabilities-contract";
 
 const HERE = import.meta.dirname;
 
@@ -132,6 +134,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   EVIDENCE_ERROR_CODES,
   METRICS_ERROR_CODES,
   METRICS_REASON_CODES,
+  SEARCH_ERROR_CODES,
+  WORKSPACE_SEARCH_ERROR_CODES,
+  SEARCH_MEMBER_REASON_CODES,
+  CAPABILITIES_ERROR_CODES,
+  CAPABILITY_SUPPORT_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */