@intentius/chant 0.124.44 → 0.124.46

package/dist/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/dist/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/dist/capabilities/catalog.d.ts

@@ -0,0 +1,89 @@
+import type { GraphIR } from "../graph-ir.js";
+import { type Literal, type Rule } from "./language.js";
+import { CapabilityEngine } from "./matcher.js";
+import { type CapabilityMapping, type CapabilityPack, type View } from "./view.js";
+/** Every rule core ships, parsed, with the file each came from. */
+export declare function shippedRules(): {
+    rules: Rule[];
+    sources: Map<string, string>;
+};
+/** The mappings core's folds need, for a graph read without its lexicon's plugin. */
+export declare function basePacks(): 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 declare function registerCapabilityPack(pack: CapabilityPack): void;
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export declare function resolvePacks(packs?: CapabilityPack[]): CapabilityPack[];
+/**
+ * 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 declare function capabilityEngine(ir: GraphIR, packs?: CapabilityPack[]): CapabilityEngine;
+/** Bind a graph to the packs its search was given, before anything asks for a capability. */
+export declare function attachCapabilities(ir: GraphIR, packs: CapabilityPack[]): CapabilityEngine;
+/**
+ * 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 declare function attachView(ir: GraphIR, view: View): CapabilityEngine;
+/**
+ * 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 declare function parseCapabilityCall(text: string): {
+    name: string;
+    args: (Literal | undefined)[];
+} | undefined;
+/** Public capabilities: those whose rule carries a `## meaning`. Helpers carry none. */
+export declare function isPublic(rule: Rule): boolean;
+/**
+ * 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 declare function lexiconSupport(rule: Rule, mapping: CapabilityMapping | undefined, lexicon: string): "supported" | {
+    code: string;
+    message: string;
+};
+/** The capabilities a rule uses, directly. */
+export declare function usesOf(rule: Rule): string[];
+/** 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 declare function capabilityCatalog(lexicons: Record<string, CapabilityMapping | undefined>): {
+    capabilities: CapabilityEntry[];
+    helpers: {
+        name: string;
+        rule: string;
+    }[];
+};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/capabilities/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/capabilities/catalog.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/catalog.js

@@ -0,0 +1,204 @@
+/**
+ * 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 { parseRules, ruleDependencies } from "./language.js";
+import { CapabilityEngine } from "./matcher.js";
+import { buildView, mergeMappings } from "./view.js";
+import base from "./base-mappings.json" with { type: "json" };
+/** The rule files core ships, by name. */
+const RULE_FILES = ["aws.paths"];
+let rulesCache;
+/** Every rule core ships, parsed, with the file each came from. */
+export function shippedRules() {
+    if (rulesCache)
+        return rulesCache;
+    const rules = [];
+    const sources = new Map();
+    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() {
+    return base.mappings.map((mapping) => ({ mapping }));
+}
+const registered = [];
+/**
+ * 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) {
+    if (!registered.includes(pack))
+        registered.push(pack);
+}
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export function resolvePacks(packs = []) {
+    return [...basePacks(), ...registered, ...packs.filter((p) => !registered.includes(p))];
+}
+const engines = new WeakMap();
+/**
+ * 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, packs = []) {
+    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, packs) {
+    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, view) {
+    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) {
+    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) {
+    return rule.meta.meaning !== undefined;
+}
+/** Every label a rule needs, through the capabilities it uses, per alternative: any one alternative suffices. */
+function labelsNeeded(rule, byName, seen = new Set()) {
+    if (seen.has(rule.name))
+        return [[]];
+    seen.add(rule.name);
+    const out = [];
+    for (const alt of rule.alts) {
+        // A node of any one of its labels will do, so each label is an option.
+        let options = alt.head.labels ? alt.head.labels.map((l) => [l]) : [[]];
+        const add = (more) => {
+            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);
+                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, mapping, lexicon) {
+    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) {
+    const { rules } = shippedRules();
+    const names = new Set(rules.map((r) => r.name));
+    return [...ruleDependencies(rule)].filter((n) => names.has(n));
+}
+/**
+ * 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) {
+    const { rules } = shippedRules();
+    const list = (s) => (s ?? "").split(/\n|;/).map((x) => x.trim()).filter(Boolean);
+    const capabilities = rules.filter(isPublic).map((r) => ({
+        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"),
+        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 };
+}

package/dist/capabilities/language.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The capability rule language (#4375, ruled on #4361).
+ *
+ * A capability is a named path pattern over the lexicon-neutral view
+ * (`./view.ts`). Its steps are #4359's edge terms: an arrow, an optional
+ * depth, then what the edge is. A rule file is data, read at run time:
+ *
+ *   # a comment
+ *   ## meaning: what the capability says, in one line      (catalog metadata)
+ *   in-sg(x, g)          := x ->{0,1}template ->sg g:SecurityGroup
+ *   open-ingress(c; port?, proto?)
+ *                        := c ->in-sg ->ingress :IngressRule[cidrs in ("0.0.0.0/0"), from <= $port]
+ *   internet-reachable(c; port?)
+ *                        := c[@internet-facing, @open-ingress($port)]
+ *                         | c:Function <-function :FunctionUrl[authType = "NONE"]
+ *
+ * One variable makes a node set, used as `[@name]`. Two make a named edge,
+ * followed as `->name` or `<-name`, which carries the hops that proved it.
+ * Parameters come after `;`; a `?` makes one optional, and a test that names
+ * an absent parameter is left out. Lines starting `|` add an alternative.
+ *
+ * A step is `->` or `<-`, an optional depth (`?`, `*`, `+`, `{n}`, `{m,n}`,
+ * `{m,}`; a rule may start at 0, which #4359's query grammar refuses), an
+ * edge name or `(a|b)`, and an optional node: `var:Label|Label[tests]`.
+ * `!->name node` and `!<-name node` are negated steps: the walk stays where
+ * it is and goes on only when no such edge leads to such a node.
+ *
+ * A node test is `attr = v`, `attr != v`, `attr in (v, ...)`, `attr ~ "glob"`,
+ * `attr < n` (and `<=`, `>`, `>=`), a bare `attr` (present and not false),
+ * or `@cap` / `@cap(args)`. Any test takes a leading `!`. Against a list
+ * attribute, a test holds when it holds for any element.
+ */
+export type Literal = string | number | boolean | null;
+/** A value in a test or an argument: a literal, or a reference to a parameter. */
+export type Value = {
+    lit: Literal;
+} | {
+    param: string;
+};
+export type Test = {
+    kind: "attr";
+    negated: boolean;
+    attr: string;
+    op: "=" | "!=" | "in" | "~" | "<" | "<=" | ">" | ">=" | "present";
+    values: Value[];
+} | {
+    kind: "cap";
+    negated: boolean;
+    cap: string;
+    args: Value[];
+};
+export interface NodeSpec {
+    v?: string;
+    labels?: string[];
+    tests: Test[];
+}
+export interface Step {
+    dir: "out" | "in";
+    negated: boolean;
+    /** Edge names: view edges or two-variable capabilities. */
+    names: {
+        name: string;
+        args: Value[];
+    }[];
+    min: number;
+    max: number;
+    node: NodeSpec;
+}
+export interface Alternative {
+    head: NodeSpec;
+    steps: Step[];
+    /** 1-based line in the rule file, for messages. */
+    line: number;
+}
+export interface Param {
+    name: string;
+    optional: boolean;
+}
+export interface Rule {
+    name: string;
+    vars: string[];
+    params: Param[];
+    alts: Alternative[];
+    /** `## key: value` lines above the rule. */
+    meta: Record<string, string>;
+    line: number;
+    /** The rule as written, one alternative per line, comments dropped. */
+    text: string;
+}
+/** A rule file the parser cannot read, with the line it failed on. */
+export declare class RuleSyntaxError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+/**
+ * Parse a rule file. Rules may span lines: a line that starts with `|`
+ * continues the rule above it, and so does an indented line when the rule's
+ * `:=` has nothing after it yet.
+ */
+export declare function parseRules(text: string): Rule[];
+/** The capabilities a rule refers to, by name: in `[@cap]` tests and in steps. */
+export declare function ruleDependencies(rule: Rule): Set<string>;
+//# sourceMappingURL=language.d.ts.map