@intentius/chant 0.124.44 → 0.124.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.44",
+  "version": "0.124.46",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/__snapshots__/okf.test.ts.snap

@@ -16,6 +16,10 @@ composite_instance: app
 ---
 Declared in \`main.ts\`.
 
+## Depends on
+
+- [environment](/aws/environment.md)
+
 ## Referenced by
 
 - [appBucketPolicy](/aws/appBucketPolicy.md)
@@ -60,6 +64,7 @@ Declared in \`main.ts\`.
 
 - [appBucket](/aws/appBucket.md)
 - [appRole](/aws/appRole.md)
+- [environment](/aws/environment.md)
 ",
     "path": "aws/appFunc.md",
   },
@@ -112,6 +117,11 @@ kind: resource
 source: params.ts
 ---
 Declared in \`params.ts\`.
+
+## Referenced by
+
+- [appBucket](/aws/appBucket.md)
+- [appFunc](/aws/appFunc.md)
 ",
     "path": "aws/environment.md",
   },

package/src/capabilities/aws.paths

@@ -0,0 +1,148 @@
+# Capabilities over AWS resources (#4375, ruled on #4361).
+#
+# Rules read the lexicon-neutral view, not the IR. Labels (Instance, Role,
+# SecurityGroup) and edge names (subnet, sg, statement) come from each
+# lexicon's mapping, so this one file serves CloudFormation (the aws lexicon)
+# and Terraform's AWS provider (the terraform lexicon) alike.
+#
+# name(x) is a node set, tested with [@name]. name(a, b) is an edge, followed
+# with ->name. Parameters follow `;`. The language is in language.ts.
+#
+# `## key: value` lines describe the capability that follows them, for the
+# `capabilities` document: meaning, answers (one per line), depth, search,
+# not-evaluated, and a line per parameter (param-<name>). A rule with no
+# `## meaning` is a helper: other rules use it, the catalog doesn't list it.
+
+# ------------------------------------------------------------------ helpers
+
+in-sg(x, g)          := x ->{0,1}template ->sg g:SecurityGroup
+ingress-of(x, r)     := x ->in-sg ->ingress r:IngressRule
+world-open(r)        := r:IngressRule[cidrs in ("0.0.0.0/0", "::/0")]
+allows(r, x; action?) := r:Role <-{0,1}attachedTo ->statement :Statement[doc = "permission", effect = "Allow", actions ~ $action] ->resource x
+                      | r:Role <-principal :Statement[doc = "resource", effect = "Allow", actions ~ $action] ->resource x
+denies(r, x; action?) := r:Role <-{0,1}attachedTo ->statement :Statement[doc = "permission", effect = "Deny", actions ~ $action] ->resource x
+                      | r:Role <-principal :Statement[doc = "resource", effect = "Deny", actions ~ $action] ->resource x
+pivot(a, b)          := a ->(runs-as|can-assume|network) b
+
+# ------------------------------------------------------------------ network
+
+## meaning: its subnet routes 0.0.0.0/0 to an internet gateway
+## answers: which instances are in a public subnet
+## answers: what sits in a subnet that routes to the internet
+## depth: either
+## not-evaluated: a subnet on its VPC's main route table (no explicit association) is not followed
+internet-facing(c)   := c:Instance ->subnet :Subnet <-subnet :RouteTableAssociation ->table :RouteTable <-table :Route[dest in ("0.0.0.0/0", "::/0", null)] ->gateway :InternetGateway
+                      | c:Instance[internetFacing = true]
+
+## meaning: a security group reaching it, directly or through a launch template, admits 0.0.0.0/0 or ::/0
+## param-port: a port the open rule must cover, such as 22
+## param-proto: a protocol the open rule must allow, such as tcp; a rule for every protocol (-1) always does
+## answers: what admits SSH from anywhere
+## answers: which instances have a security group open to the world
+## depth: declared
+## not-evaluated: network ACLs; prefix lists
+open-ingress(c; port?, proto?) := c:Instance|Database|Function|Service ->ingress-of r:IngressRule[@world-open, from <= $port, to >= $port, proto in ($proto, "-1")]
+
+## meaning: internet-facing and open-ingress, or a Lambda function URL with no auth. Load balancers and API gateways come later
+## param-port: a port the open rule must cover, such as 22
+## answers: what in prod can be reached on SSH from the internet
+## answers: which instances are SSH-reachable from the internet
+## depth: either
+## not-evaluated: load balancers; API gateways; network ACLs
+internet-reachable(c; port?) := c[@internet-facing, @open-ingress($port)]
+                      | c:Function <-function :FunctionUrl[authType = "NONE"]
+
+## meaning: no member, attachment or route references it
+## answers: which security groups are unused
+## answers: which subnets have no instances or network interfaces
+## answers: which policies are attached to nothing
+## depth: either
+attached-to-nothing(x) := x:SecurityGroup !<-sg
+                      | x:Subnet !<-subnet
+                      | x:Policy !->attachedTo
+                      | x:InternetGateway !<-gateway
+
+## meaning: in the account's default VPC
+## answers: which instances run in the default VPC
+## answers: which instances are not in the default VPC (negate it: !cap:in-default-vpc)
+## depth: either
+in-default-vpc(x)    := x ->{1,2}(subnet|vpc) :Vpc[isDefault = true]
+
+## meaning: host to host through security-group-to-group ingress
+## answers: what can this instance reach on the network
+## depth: declared
+## not-evaluated: CIDR-to-CIDR reachability inside the VPC; network ACLs
+network(a, y)        := a:Instance|Database|Function|Service ->in-sg <-source :IngressRule <-ingress :SecurityGroup <-in-sg y:Instance|Database|Function|Service
+
+# ------------------------------------------------------------------ data
+
+## meaning: a bucket, table, database, queue, file system or secret
+## answers: where is our data
+## depth: declared
+stores-data(x)       := x:Bucket|Table|Database|Queue|FileSystem|Secret|Parameter
+
+## meaning: a secret, an SSM SecureString, or a data store tagged as restricted (the tag keys are the lexicon mapping's classificationTags)
+## answers: which stores hold secrets or restricted data
+## depth: declared
+holds-secret(x)      := x:Secret
+                      | x:Parameter[paramType = "SecureString"]
+                      | x:Bucket|Table|Database|Queue|FileSystem[classification in ("restricted", "secret", "confidential")]
+
+## meaning: encrypted at rest: a database, file system or volume whose encryption attribute is set; S3 buckets, DynamoDB tables, SQS queues and secrets always are
+## answers: which data stores are not encrypted at rest (negate it: !cap:encrypted-at-rest)
+## depth: declared
+## not-evaluated: account-level EBS encryption by default; which key (AWS-owned, AWS-managed or customer-managed)
+encrypted-at-rest(x) := x:Database|FileSystem|Volume[encrypted = true]
+                      | x:Bucket|Table|Queue|Secret
+
+## meaning: a bucket whose policy allows principal * and no public-access block stops it, or a public ACL
+## answers: what is public
+## answers: which buckets can anyone read
+## depth: declared
+## not-evaluated: IAM Condition keys; account-level public-access blocks
+publicly-readable(x) := x:Bucket[!blockPublicPolicy = true] !<-blocks :PublicAccessBlock[blockPublicPolicy = true] <-policyOf :ResourcePolicy ->statement :Statement[doc = "resource", effect = "Allow", principals in ("*")]
+                      | x:Bucket[acl in ("public-read", "public-read-write")]
+
+# ------------------------------------------------------------------ identity
+
+## meaning: compute to the role it runs as (instance profile, also through a launch template; Lambda role; ECS task role)
+## answers: what identity does this instance run as
+## depth: declared
+runs-as(c, r)        := c:Instance|Function|Service|TaskDefinition ->{0,1}template ->{0,1}(profile|task) ->role r:Role
+
+## meaning: role to role, where both the caller's permission and the target's trust allow sts:AssumeRole
+## answers: which roles can this role become
+## depth: declared
+## not-evaluated: IAM Condition keys; Resource "*"; a trust policy that names the account root
+can-assume(a, b)     := a:Role <-{0,1}attachedTo ->statement :Statement[doc = "permission", effect = "Allow", actions ~ "sts:AssumeRole"] ->resource b:Role ->statement :Statement[doc = "trust", actions ~ "sts:AssumeRole"] ->principal a
+
+## meaning: role to resource, by an identity policy or a resource policy, with no explicit Deny on the same pair
+## param-action: an IAM action the grant must cover, such as dynamodb:GetItem
+## answers: what can this role touch
+## answers: what can reach the customer database (read it in reverse: <-[cap=grants])
+## depth: declared
+## not-evaluated: IAM Condition keys; Resource "*"; NotAction and NotResource; permission boundaries and SCPs; AWS-managed policies, named by ARN only; resources the graph holds but can't resolve, such as an expression naming nothing declared
+grants(r, x; action?) := r:Role ->allows($action) x !<-denies($action) r
+
+## meaning: can-assume any number of times, then grants
+## param-action: an IAM action the grant must cover, such as s3:GetObject
+## answers: if this role is compromised, what data can it reach
+## answers: what can reach the customer database (read it in reverse: <-[cap=reaches])
+## depth: declared
+## not-evaluated: IAM Condition keys; Resource "*"; NotAction and NotResource; permission boundaries and SCPs; AWS-managed policies, named by ARN only; resources the graph holds but can't resolve, such as an expression naming nothing declared
+reaches(r, x; action?) := r:Role ->{0,}can-assume ->grants($action) x
+
+# ------------------------------------------------------------------ paths
+
+## meaning: internet-reachable compute that runs as a role that reaches a store holding a secret
+## answers: is there an exfiltration path from the internet to our data
+## answers: which internet-facing hosts can read restricted data
+## depth: declared
+## not-evaluated: IAM Condition keys; Resource "*"; load balancers and API gateways; resources the graph holds but can't resolve, such as an expression naming nothing declared
+exfiltrates(c, x)    := c[@internet-reachable] ->runs-as ->reaches x[@holds-secret]
+
+## meaning: what a compromise of it reaches: runs-as, can-assume and network any number of times, then what each identity is granted
+## answers: what is the blast radius if this host is compromised
+## depth: declared
+## not-evaluated: IAM Condition keys; Resource "*"; CIDR-to-CIDR reachability; resources the graph holds but can't resolve, such as an expression naming nothing declared
+blast(s, x)          := s ->{0,}pivot ->{0,1}grants x

package/src/capabilities/base-mappings.json

@@ -0,0 +1,122 @@
+{
+  "$comment": "The kinds core's effective-topology folds read (#1139, #4362), as data. These were constants in graph-effective.ts; they stay in core so the folds work on a graph read without its lexicon's plugin. Each lexicon's own mapping (src/capabilities/mapping.json) extends its entry here.",
+  "mappings": [
+    {
+      "lexicon": "aws",
+      "types": "kind",
+      "refs": "cloudformation",
+      "labels": {
+        "AWS::EC2::Instance": "Instance",
+        "AWS::EC2::LaunchTemplate": "LaunchTemplate",
+        "AWS::EC2::SecurityGroup": "SecurityGroup",
+        "AWS::EC2::SecurityGroupIngress": { "label": "IngressRule", "style": "cfn" },
+        "AWS::EC2::Subnet": "Subnet",
+        "AWS::EC2::SubnetRouteTableAssociation": "RouteTableAssociation",
+        "AWS::EC2::RouteTable": "RouteTable",
+        "AWS::EC2::Route": "Route",
+        "AWS::EC2::InternetGateway": "InternetGateway"
+      },
+      "edges": {
+        "Instance": {
+          "SecurityGroupIds": "sg",
+          "SecurityGroupId": "sg",
+          "LaunchTemplate": "template",
+          "LaunchTemplateId": "template",
+          "SubnetId": "subnet"
+        },
+        "LaunchTemplate": {
+          "LaunchTemplateData": { "SecurityGroup": "sg" },
+          "SecurityGroupIds": "sg",
+          "SecurityGroupId": "sg"
+        },
+        "IngressRule": { "GroupId": "-ingress", "SourceSecurityGroupId": "source" },
+        "RouteTableAssociation": { "SubnetId": "subnet", "RouteTableId": "table" },
+        "Route": { "RouteTableId": "table", "GatewayId": "gateway" }
+      },
+      "attrs": {
+        "Route": { "dest": "DestinationCidrBlock" },
+        "IngressRule": { "proto": "IpProtocol", "from": "FromPort", "to": "ToPort", "cidrs": { "all": ["CidrIp", "CidrIpv6"] } }
+      },
+      "blocks": {
+        "SecurityGroup": [
+          {
+            "attr": "SecurityGroupIngress",
+            "label": "IngressRule",
+            "edge": "ingress",
+            "style": "cfn",
+            "attrs": { "proto": "IpProtocol", "from": "FromPort", "to": "ToPort", "cidrs": { "all": ["CidrIp", "CidrIpv6"] } },
+            "refs": { "SourceSecurityGroupId": "source" }
+          }
+        ]
+      }
+    },
+    {
+      "lexicon": "terraform",
+      "types": "terraform",
+      "body": "body",
+      "refs": "terraform",
+      "labels": {
+        "aws_instance": "Instance",
+        "aws_launch_template": "LaunchTemplate",
+        "aws_security_group": "SecurityGroup",
+        "aws_security_group_rule": { "label": "IngressRule", "when": { "type": "ingress" }, "style": "tf-sg-rule" },
+        "aws_vpc_security_group_ingress_rule": { "label": "IngressRule", "style": "tf-vpc-rule" },
+        "aws_subnet": "Subnet",
+        "aws_route_table_association": "RouteTableAssociation",
+        "aws_route_table": "RouteTable",
+        "aws_route": "Route",
+        "aws_internet_gateway": "InternetGateway"
+      },
+      "edges": {
+        "Instance": {
+          "vpc_security_group_ids": "sg",
+          "security_groups": "sg",
+          "launch_template": "template",
+          "subnet_id": "subnet"
+        },
+        "LaunchTemplate": {
+          "vpc_security_group_ids": "sg",
+          "security_group_names": "sg",
+          "network_interfaces": { "SecurityGroup": "sg" }
+        },
+        "IngressRule": {
+          "security_group_id": "-ingress",
+          "source_security_group_id": "source",
+          "referenced_security_group_id": "source"
+        },
+        "RouteTableAssociation": { "subnet_id": "subnet", "route_table_id": "table" },
+        "Route": { "route_table_id": "table", "gateway_id": "gateway" }
+      },
+      "attrs": {
+        "Route": { "dest": ["destination_cidr_block", "destination_ipv6_cidr_block"] },
+        "IngressRule": {
+          "proto": ["ip_protocol", "protocol"],
+          "from": "from_port",
+          "to": "to_port",
+          "cidrs": { "all": ["cidr_blocks", "ipv6_cidr_blocks", "cidr_ipv4", "cidr_ipv6"] }
+        }
+      },
+      "blocks": {
+        "SecurityGroup": [
+          {
+            "attr": "ingress",
+            "label": "IngressRule",
+            "edge": "ingress",
+            "style": "tf-inline",
+            "attrs": { "proto": "protocol", "from": "from_port", "to": "to_port", "cidrs": { "all": ["cidr_blocks", "ipv6_cidr_blocks"] } },
+            "refs": { "security_groups": "source" }
+          }
+        ],
+        "RouteTable": [
+          {
+            "attr": "route",
+            "label": "Route",
+            "edge": "-table",
+            "attrs": { "dest": ["cidr_block", "ipv6_cidr_block"] },
+            "refs": { "gateway_id": "gateway" }
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/capabilities/catalog.ts

@@ -0,0 +1,230 @@
+/**
+ * The capability catalog (#4375): the rule files core ships, the packs
+ * lexicons contribute, and the engine that evaluates one over a graph.
+ *
+ * Rules are data: `aws.paths` beside this module, read at run time. It serves
+ * every lexicon that maps AWS resources onto the view (the aws lexicon's
+ * CloudFormation kinds and the terraform lexicon's AWS provider types), so it
+ * lives here rather than in either lexicon. Each lexicon ships its mapping
+ * (data) and, where it needs one, an adapter (code), as a `CapabilityPack` on
+ * its plugin.
+ */
+import { readFileSync } from "node:fs";
+import type { GraphIR } from "../graph-ir";
+import { parseRules, ruleDependencies, type Literal, type Rule } from "./language";
+import { CapabilityEngine } from "./matcher";
+import { buildView, mergeMappings, type CapabilityMapping, type CapabilityPack, type View } from "./view";
+import base from "./base-mappings.json" with { type: "json" };
+
+/** The rule files core ships, by name. */
+const RULE_FILES = ["aws.paths"] as const;
+
+let rulesCache: { rules: Rule[]; sources: Map<string, string> } | undefined;
+
+/** Every rule core ships, parsed, with the file each came from. */
+export function shippedRules(): { rules: Rule[]; sources: Map<string, string> } {
+  if (rulesCache) return rulesCache;
+  const rules: Rule[] = [];
+  const sources = new Map<string, string>();
+  for (const file of RULE_FILES) {
+    const text = readFileSync(new URL(`./${file}`, import.meta.url), "utf-8");
+    for (const r of parseRules(text)) {
+      rules.push(r);
+      sources.set(r.name, file);
+    }
+  }
+  rulesCache = { rules, sources };
+  return rulesCache;
+}
+
+/** The mappings core's folds need, for a graph read without its lexicon's plugin. */
+export function basePacks(): CapabilityPack[] {
+  return (base as unknown as { mappings: CapabilityMapping[] }).mappings.map((mapping) => ({ mapping }));
+}
+
+const registered: CapabilityPack[] = [];
+
+/**
+ * Register a lexicon's pack for callers that hold no plugin list (the folds,
+ * a test). A plugin's `capabilityPack` reaches search without this.
+ */
+export function registerCapabilityPack(pack: CapabilityPack): void {
+  if (!registered.includes(pack)) registered.push(pack);
+}
+
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export function resolvePacks(packs: CapabilityPack[] = []): CapabilityPack[] {
+  return [...basePacks(), ...registered, ...packs.filter((p) => !registered.includes(p))];
+}
+
+const engines = new WeakMap<GraphIR, CapabilityEngine>();
+
+/**
+ * The capability engine for a graph, built once per graph object. Packs
+ * passed on the first call for a graph are the ones it uses.
+ */
+export function capabilityEngine(ir: GraphIR, packs: CapabilityPack[] = []): CapabilityEngine {
+  let e = engines.get(ir);
+  if (!e) {
+    e = new CapabilityEngine(buildView(ir, resolvePacks(packs)), shippedRules().rules);
+    engines.set(ir, e);
+  }
+  return e;
+}
+
+/** Bind a graph to the packs its search was given, before anything asks for a capability. */
+export function attachCapabilities(ir: GraphIR, packs: CapabilityPack[]): CapabilityEngine {
+  engines.delete(ir);
+  return capabilityEngine(ir, packs);
+}
+
+/**
+ * Bind a graph to a view built elsewhere (#4378): a workspace's composed
+ * view, which each member's own chant mapped. The rules are this chant's.
+ */
+export function attachView(ir: GraphIR, view: View): CapabilityEngine {
+  const e = new CapabilityEngine(view, shippedRules().rules);
+  engines.set(ir, e);
+  return e;
+}
+
+/**
+ * Read `name` or `name(arg, ...)`, as a search term or an edge qualifier
+ * spells a capability. An argument is a number, `true`/`false`, or text,
+ * quoted or not.
+ */
+export function parseCapabilityCall(text: string): { name: string; args: (Literal | undefined)[] } | undefined {
+  const m = /^([A-Za-z_][\w-]*)(?:\((.*)\))?$/.exec(text.trim());
+  if (!m) return undefined;
+  const args = m[2] === undefined || m[2].trim() === ""
+    ? []
+    : m[2].split(",").map((a) => {
+        const s = a.trim();
+        if (s === "" || s === "_") return undefined;
+        if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+        if (s === "true" || s === "false") return s === "true";
+        return s.replace(/^"(.*)"$/, "$1");
+      });
+  return { name: m[1], args };
+}
+
+/** Public capabilities: those whose rule carries a `## meaning`. Helpers carry none. */
+export function isPublic(rule: Rule): boolean {
+  return rule.meta.meaning !== undefined;
+}
+
+/** Every label a rule needs, through the capabilities it uses, per alternative: any one alternative suffices. */
+function labelsNeeded(rule: Rule, byName: Map<string, Rule>, seen = new Set<string>()): string[][] {
+  if (seen.has(rule.name)) return [[]];
+  seen.add(rule.name);
+  const out: string[][] = [];
+  for (const alt of rule.alts) {
+    // A node of any one of its labels will do, so each label is an option.
+    let options: string[][] = alt.head.labels ? alt.head.labels.map((l) => [l]) : [[]];
+    const add = (more: string[][]): void => {
+      options = options.flatMap((o) => more.map((m) => [...o, ...m]));
+    };
+    for (const t of alt.head.tests) if (t.kind === "cap" && !t.negated) add(labelsNeeded(byName.get(t.cap)!, byName, new Set(seen)));
+    for (const s of alt.steps) {
+      if (s.negated) continue;
+      if (s.node.labels && s.min > 0) add(s.node.labels.map((l) => [l]));
+      for (const t of s.node.tests) if (t.kind === "cap" && !t.negated) add(labelsNeeded(byName.get(t.cap)!, byName, new Set(seen)));
+      if (s.min > 0) {
+        const edgeRules = s.names.map((n) => byName.get(n.name)).filter((r): r is Rule => !!r);
+        if (edgeRules.length === s.names.length) add(edgeRules.flatMap((r) => labelsNeeded(r, byName, new Set(seen))));
+      }
+    }
+    out.push(...options);
+  }
+  return out;
+}
+
+/**
+ * Whether a lexicon can supply a capability: its own statement when its
+ * mapping makes one, otherwise whether every label one alternative needs
+ * is one the mapping labels.
+ */
+export function lexiconSupport(
+  rule: Rule,
+  mapping: CapabilityMapping | undefined,
+  lexicon: string,
+): "supported" | { code: string; message: string } {
+  if (!mapping) {
+    return { code: "lexicon-has-no-mapping", message: `the ${lexicon} lexicon ships no capability mapping` };
+  }
+  const stated = mapping.unsupported?.[rule.name];
+  if (stated) return stated;
+  // A lexicon's mapping extends core's base mapping for it (the folds' kinds).
+  const own = mapping;
+  const baseFor = basePacks().find((p) => p.mapping.lexicon === own.lexicon)?.mapping;
+  if (baseFor) mapping = mergeMappings(baseFor, own);
+  const { rules } = shippedRules();
+  const byName = new Map(rules.map((r) => [r.name, r]));
+  const labels = new Set(
+    Object.values(mapping.labels ?? {}).map((s) => (typeof s === "string" ? s : s.label)),
+  );
+  // Statements and inline blocks are the adapter's own nodes.
+  labels.add("Statement");
+  for (const specs of Object.values(mapping.blocks ?? {})) for (const b of specs) labels.add(b.label);
+  const options = labelsNeeded(rule, byName);
+  if (options.some((o) => o.every((l) => labels.has(l)))) return "supported";
+  const missing = [...new Set(options.flatMap((o) => o.filter((l) => !labels.has(l))))];
+  return {
+    code: "capability-not-derivable",
+    message: `the ${lexicon} mapping labels no ${missing.join(" or ")}`,
+  };
+}
+
+/** The capabilities a rule uses, directly. */
+export function usesOf(rule: Rule): string[] {
+  const { rules } = shippedRules();
+  const names = new Set(rules.map((r) => r.name));
+  return [...ruleDependencies(rule)].filter((n) => names.has(n));
+}
+
+/** One capability as the `capabilities` document lists it (#4375). */
+export interface CapabilityEntry {
+  name: string;
+  meaning: string;
+  shape: "set" | "edge";
+  params: { name: string; optional: boolean; meaning: string }[];
+  /** The search term that asks for it: `cap:<name>` for a set, `->[cap=<name>]` for an edge. */
+  search: string;
+  answers: string[];
+  depth: "declared" | "live" | "either";
+  lexicons: Record<string, "supported" | { code: string; message: string }>;
+  notEvaluated: string[];
+  /** The capabilities and helpers its rule uses. */
+  uses: string[];
+  rule: string;
+}
+
+/**
+ * The catalog as the `capabilities` document carries it: every public
+ * capability, with whether each lexicon given can supply it, and the helper
+ * rules they use. `lexicons` maps each lexicon to its mapping, or to
+ * undefined when it ships none.
+ */
+export function capabilityCatalog(lexicons: Record<string, CapabilityMapping | undefined>): {
+  capabilities: CapabilityEntry[];
+  helpers: { name: string; rule: string }[];
+} {
+  const { rules } = shippedRules();
+  const list = (s: string | undefined): string[] =>
+    (s ?? "").split(/\n|;/).map((x) => x.trim()).filter(Boolean);
+  const capabilities = rules.filter(isPublic).map((r): CapabilityEntry => ({
+    name: r.name,
+    meaning: r.meta.meaning,
+    shape: r.vars.length === 1 ? "set" : "edge",
+    params: r.params.map((p) => ({ name: p.name, optional: p.optional, meaning: r.meta[`param-${p.name}`] ?? "" })),
+    search: r.vars.length === 1 ? `cap:${r.name}` : `->[cap=${r.name}]`,
+    answers: (r.meta.answers ?? "").split("\n").map((x) => x.trim()).filter(Boolean),
+    depth: (r.meta.depth ?? "declared") as CapabilityEntry["depth"],
+    lexicons: Object.fromEntries(Object.entries(lexicons).map(([lex, m]) => [lex, lexiconSupport(r, m, lex)])),
+    notEvaluated: list(r.meta["not-evaluated"]),
+    uses: usesOf(r),
+    rule: r.text,
+  }));
+  const helpers = rules.filter((r) => !isPublic(r)).map((r) => ({ name: r.name, rule: r.text }));
+  return { capabilities, helpers };
+}