@intentius/chant 0.124.45 → 0.124.48

package/dist/capabilities/language.js

@@ -0,0 +1,335 @@
+/**
+ * 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.
+ */
+/** A rule file the parser cannot read, with the line it failed on. */
+export class RuleSyntaxError extends Error {
+    constructor(message, line) {
+        super(`line ${line}: ${message}`);
+        this.line = line;
+    }
+}
+// An identifier may hold `-` (`can-assume`), but not one that starts an arrow.
+const TOKEN = /\s*(!->|!<-|->|<-|:=|<=|>=|!=|\{\d*(?:,\d*)?\}|"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?![\w-])|[$]?[A-Za-z_](?:\w|-(?!>))*|[()[\],|?*+@:=~<>!;])/y;
+function tokenize(text, line) {
+    const out = [];
+    TOKEN.lastIndex = 0;
+    const end = text.trimEnd().length;
+    while (TOKEN.lastIndex < end) {
+        const at = TOKEN.lastIndex;
+        const m = TOKEN.exec(text);
+        if (!m)
+            throw new RuleSyntaxError(`cannot read "${text.slice(at).trim()}"`, line);
+        out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * 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 function parseRules(text) {
+    const rules = [];
+    let meta = {};
+    let pending;
+    const lines = text.split("\n");
+    const flush = () => {
+        if (!pending)
+            return;
+        const { text: body, line } = pending;
+        const toks = tokenize(body, line);
+        const p = new Parser(toks, line);
+        if (pending.rule) {
+            p.eat("|");
+            pending.rule.alts.push(p.alternative());
+            pending.rule.text += `\n${body.trim()}`;
+        }
+        else {
+            const rule = p.header(meta, body.trim());
+            meta = {};
+            rule.alts.push(p.alternative());
+            rules.push(rule);
+        }
+        p.done();
+        pending = undefined;
+    };
+    lines.forEach((raw, i) => {
+        const line = i + 1;
+        const docMatch = /^\s*##\s*([\w-]+)\s*:\s*(.*)$/.exec(raw);
+        if (docMatch) {
+            flush();
+            const [, key, value] = docMatch;
+            meta[key] = meta[key] ? `${meta[key]}\n${value.trim()}` : value.trim();
+            return;
+        }
+        const code = raw.replace(/(^|\s)#.*$/, "");
+        if (!code.trim())
+            return;
+        if (/^\s*\|/.test(code)) {
+            flush();
+            const rule = rules.at(-1);
+            if (!rule)
+                throw new RuleSyntaxError("an alternative needs a rule above it", line);
+            pending = { text: code, line, rule };
+            return;
+        }
+        if (/^\s/.test(code) && pending) {
+            pending.text += ` ${code.trim()}`;
+            return;
+        }
+        flush();
+        pending = { text: code, line };
+    });
+    flush();
+    const seen = new Set();
+    for (const r of rules) {
+        if (seen.has(r.name))
+            throw new RuleSyntaxError(`"${r.name}" is defined twice`, r.line);
+        seen.add(r.name);
+    }
+    return rules;
+}
+const LIT = (tok) => {
+    if (tok === "null")
+        return null;
+    if (tok === "true")
+        return true;
+    if (tok === "false")
+        return false;
+    if (tok.startsWith('"'))
+        return JSON.parse(tok);
+    if (/^-?\d/.test(tok))
+        return Number(tok);
+    return tok;
+};
+const NAME = /^[A-Za-z_][\w-]*$/;
+class Parser {
+    constructor(t, line) {
+        this.t = t;
+        this.line = line;
+        this.i = 0;
+    }
+    peek(k = 0) {
+        return this.t[this.i + k];
+    }
+    next() {
+        const tok = this.t[this.i++];
+        if (tok === undefined)
+            throw new RuleSyntaxError("the rule ends too early", this.line);
+        return tok;
+    }
+    eat(x) {
+        if (this.t[this.i] !== x) {
+            throw new RuleSyntaxError(`expected "${x}" at "${this.t.slice(this.i).join(" ") || "end of rule"}"`, this.line);
+        }
+        this.i++;
+    }
+    done() {
+        if (this.i !== this.t.length)
+            throw new RuleSyntaxError(`cannot read "${this.t.slice(this.i).join(" ")}"`, this.line);
+    }
+    name(what) {
+        const tok = this.next();
+        if (!NAME.test(tok))
+            throw new RuleSyntaxError(`expected ${what}, found "${tok}"`, this.line);
+        return tok;
+    }
+    header(meta, text) {
+        const name = this.name("a capability name");
+        this.eat("(");
+        const vars = [this.name("a variable")];
+        if (this.peek() === ",") {
+            this.next();
+            vars.push(this.name("a variable"));
+        }
+        const params = [];
+        if (this.peek() === ";") {
+            this.next();
+            for (;;) {
+                const p = this.name("a parameter");
+                const optional = this.peek() === "?";
+                if (optional)
+                    this.next();
+                params.push({ name: p, optional });
+                if (this.peek() !== ",")
+                    break;
+                this.next();
+            }
+        }
+        this.eat(")");
+        this.eat(":=");
+        return { name, vars, params, alts: [], meta, line: this.line, text };
+    }
+    alternative() {
+        const head = this.node();
+        const steps = [];
+        while (this.peek() && /^!?(->|<-)$/.test(this.peek()))
+            steps.push(this.step());
+        return { head, steps, line: this.line };
+    }
+    step() {
+        const arrow = this.next();
+        const negated = arrow.startsWith("!");
+        const dir = arrow.endsWith("->") ? "out" : "in";
+        let min = 1;
+        let max = 1;
+        const q = this.peek();
+        if (q === "?") {
+            this.next();
+            min = 0;
+        }
+        else if (q === "*") {
+            this.next();
+            max = Infinity;
+        }
+        else if (q === "+") {
+            this.next();
+            max = Infinity;
+        }
+        else if (q && q.startsWith("{")) {
+            this.next();
+            const m = /^\{(\d*)(,(\d*))?\}$/.exec(q);
+            min = m[1] === "" ? 0 : Number(m[1]);
+            max = m[2] === undefined ? min : m[3] === "" ? Infinity : Number(m[3]);
+            if (max < min)
+                throw new RuleSyntaxError(`depth ${q} has its maximum below its minimum`, this.line);
+        }
+        if (negated && (min !== 1 || max !== 1))
+            throw new RuleSyntaxError("a negated step takes no depth", this.line);
+        const names = [];
+        if (this.peek() === "(") {
+            this.next();
+            for (;;) {
+                names.push(this.edgeName());
+                if (this.peek() !== "|")
+                    break;
+                this.next();
+            }
+            this.eat(")");
+        }
+        else
+            names.push(this.edgeName());
+        return { dir, negated, names, min, max, node: this.node() };
+    }
+    edgeName() {
+        const name = this.name("an edge name");
+        // `->grants($action)`: arguments must touch the name, so a following
+        // `(a|b)` step is not read as arguments.
+        return { name, args: this.peek() === "(" ? this.args() : [] };
+    }
+    args() {
+        this.eat("(");
+        const out = [];
+        while (this.peek() !== ")") {
+            out.push(this.value());
+            if (this.peek() === ",")
+                this.next();
+        }
+        this.eat(")");
+        return out;
+    }
+    value() {
+        const tok = this.next();
+        if (tok.startsWith("$"))
+            return { param: tok.slice(1) };
+        return { lit: LIT(tok) };
+    }
+    node() {
+        const spec = { tests: [] };
+        const p = this.peek();
+        if (p && NAME.test(p) && /^[a-z_]/.test(p) && this.peek(1) !== "(") {
+            spec.v = this.next();
+        }
+        if (this.peek() === ":") {
+            this.next();
+            spec.labels = [this.name("a label")];
+            while (this.peek() === "|" && /^[A-Z]/.test(this.peek(1) ?? "")) {
+                this.next();
+                spec.labels.push(this.name("a label"));
+            }
+        }
+        if (this.peek() === "[") {
+            this.next();
+            while (this.peek() !== "]") {
+                spec.tests.push(this.test());
+                if (this.peek() === ",")
+                    this.next();
+                else if (this.peek() !== "]")
+                    throw new RuleSyntaxError(`expected "," or "]" at "${this.peek() ?? "end of rule"}"`, this.line);
+            }
+            this.eat("]");
+        }
+        return spec;
+    }
+    test() {
+        let negated = false;
+        if (this.peek() === "!") {
+            this.next();
+            negated = true;
+        }
+        if (this.peek() === "@") {
+            this.next();
+            const cap = this.name("a capability name");
+            return { kind: "cap", negated, cap, args: this.peek() === "(" ? this.args() : [] };
+        }
+        const attr = this.name("an attribute");
+        const op = this.peek();
+        if (op === "," || op === "]")
+            return { kind: "attr", negated, attr, op: "present", values: [] };
+        this.next();
+        if (op === "in") {
+            return { kind: "attr", negated, attr, op: "in", values: this.args() };
+        }
+        if (op === "=" || op === "!=" || op === "~" || op === "<" || op === "<=" || op === ">" || op === ">=") {
+            return { kind: "attr", negated, attr, op, values: [this.value()] };
+        }
+        throw new RuleSyntaxError(`"${op}" is not a test operator`, this.line);
+    }
+}
+/** The capabilities a rule refers to, by name: in `[@cap]` tests and in steps. */
+export function ruleDependencies(rule) {
+    const out = new Set();
+    const node = (n) => {
+        for (const t of n.tests)
+            if (t.kind === "cap")
+                out.add(t.cap);
+    };
+    for (const a of rule.alts) {
+        node(a.head);
+        for (const s of a.steps) {
+            for (const n of s.names)
+                out.add(n.name);
+            node(s.node);
+        }
+    }
+    return out;
+}

package/dist/capabilities/matcher.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The matcher for capability rules (#4375): evaluates `./language.ts` rules
+ * over a `./view.ts` view, lazily, keeping the path that proved each fact.
+ *
+ * A capability is computed the first time something asks for it, over the
+ * whole view, and kept. One that refers to another asks for it first, so
+ * negation is stratified by construction: `[!@cap]` reads a set that is
+ * already complete. Two capabilities that need each other are refused.
+ */
+import type { Literal, Rule } from "./language.js";
+import type { View, ViewHop } from "./view.js";
+/** Why a node is in a set, or a pair in an edge: the hops walked, and the sets it relied on. */
+export interface Evidence {
+    /** IR hops in walk order. Each keeps the edge's own direction. */
+    hops: ViewHop[];
+    /** The `[@cap]` tests the match relied on, each with its own evidence. */
+    because: {
+        capability: string;
+        id: string;
+        evidence: Evidence;
+    }[];
+}
+export type Args = Record<string, Literal | undefined>;
+/** An edge capability: each source's targets, with evidence. */
+export interface Relation {
+    out: Map<string, Map<string, Evidence>>;
+    in: Map<string, Map<string, Evidence>>;
+}
+export declare class CapabilityError extends Error {
+}
+export declare class CapabilityEngine {
+    readonly view: View;
+    private readonly rules;
+    private readonly sets;
+    private readonly relations;
+    private readonly busy;
+    private readonly out;
+    private readonly in;
+    private readonly byLabel;
+    constructor(view: View, rules: Rule[]);
+    private index;
+    /** Refuse a rule that names a capability that doesn't exist, or uses one in the wrong shape. */
+    private check;
+    has(name: string): boolean;
+    /** The capabilities the catalog lists: rules that carry a `## meaning`. */
+    publicNames(): string[];
+    rule(name: string): Rule | undefined;
+    /** Bind positional arguments to a rule's parameters. */
+    bind(name: string, positional: (Literal | undefined)[]): Args;
+    private key;
+    /** The nodes in a set capability, with evidence. */
+    set(name: string, args?: Args): Map<string, Evidence>;
+    /** The pairs in an edge capability, with evidence. */
+    relation(name: string, args?: Args): Relation;
+    private enter;
+    private starts;
+    private resolve;
+    private test;
+    private ok;
+    private hop;
+    /** Every node within the step's depth range, by its shortest walk. */
+    private walk;
+    private match;
+}
+//# sourceMappingURL=matcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/capabilities/matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAe,OAAO,EAAY,IAAI,EAAqB,MAAM,YAAY,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE5C,gGAAgG;AAChG,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,EAAE,CAAC;CACnE;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;AAEvD,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxC,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CACxC;AAED,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAkB7C,qBAAa,gBAAgB;IAUzB,QAAQ,CAAC,IAAI,EAAE,IAAI;IATrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4C;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqE;IACzF,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqE;IACxF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,YACW,IAAI,EAAE,IAAI,EACnB,KAAK,EAAE,IAAI,EAAE,EAYd;IAED,OAAO,CAAC,KAAK;IAQb,gGAAgG;IAChG,OAAO,CAAC,KAAK;IAuBb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,2EAA2E;IAC3E,WAAW,IAAI,MAAM,EAAE,CAEtB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAEnC;IAED,wDAAwD;IACxD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,OAAO,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAa5D;IAED,OAAO,CAAC,GAAG;IAIX,oDAAoD;IACpD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAS,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAoBxD;IAED,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAS,GAAG,QAAQ,CA4BhD;IAED,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,IAAI;IAqCZ,OAAO,CAAC,EAAE;IAQV,OAAO,CAAC,GAAG;IAcX,sEAAsE;IACtE,OAAO,CAAC,IAAI;IAuBZ,OAAO,CAAC,KAAK;CAyBd"}