@intentius/chant 0.124.13 → 0.124.15

package/dist/governance.js

@@ -0,0 +1,43 @@
+/**
+ * Governance verb vocabulary .
+ *
+ * `resourceType` on a change-set entry is a free provider-specific string
+ * ("team", "branch-protection", "protected-tag", …) chosen per cycle. That is
+ * right for display but useless for reading two providers' plans as one
+ * grammar. The verb is the cross-provider category a cycle reconciles;
+ * provider-specific cycle names stay for display.
+ *
+ * SCM and cloud cycles stamp the same verbs, so a GitHub plan and an AWS plan
+ * group the same way:
+ *
+ * - `org-unit` — the containers and their settings: GitHub org/repo settings,
+ *   GitLab group/project/instance settings, cloud OUs/folders/accounts.
+ * - `policy-guardrail` — rules constraining what may happen: branch
+ *   protections, rulesets, push rules, MR approvals, security features,
+ *   dependency hygiene, SCPs, Org Policies.
+ * - `membership` — who belongs, directly or via teams: org members, team
+ *   membership, group members.
+ * - `identity-assignment` — non-person and delegated access: tokens, deploy
+ *   keys, service credentials, SSO/IAM assignments. `membership` is people
+ *   in containers; this is everything else that can act.
+ * - `audit-sink` — where events and evidence flow: webhooks, integrations,
+ *   CloudTrail/audit-log sinks.
+ * - `secret-material` — secrets and CI variables the platform stores.
+ *
+ * A cycle has exactly one verb. When a cycle plausibly spans two (GitHub
+ * `environments` carries both reviewer gates and secrets), stamp the verb of
+ * the cycle's primary object — the thing whose create/delete the cycle owns —
+ * not of fields it also happens to write.
+ */
+/** Every verb, for exhaustiveness checks ("does each cycle stamp one?"). */
+export const GOVERNANCE_VERBS = [
+    "org-unit",
+    "policy-guardrail",
+    "membership",
+    "identity-assignment",
+    "audit-sink",
+    "secret-material",
+];
+export function isGovernanceVerb(v) {
+    return typeof v === "string" && GOVERNANCE_VERBS.includes(v);
+}

package/dist/graph-declared.js

@@ -0,0 +1,45 @@
+import { resolve } from "node:path";
+import { discover } from "./discovery/index.js";
+import { buildGraphIr } from "./graph-ir.js";
+/**
+ * Build the DECLARED graph for a multi-stack project, scoped per stack (#1162).
+ *
+ * A whole-project discovery disambiguates colliding logical names by module path
+ * (two `server`s become `UsEast1Srcserver` / `UsWest1Srcserver`) — names that
+ * never appear in any deployed template, because each stack deploys its OWN
+ * scoped source with BARE LogicalResourceIds. Observation therefore keys live
+ * nodes by `${stack}::${logicalId}` (bare id). To make the declared side join
+ * that live side, build each stack's `src` in isolation and qualify its node ids
+ * and edge endpoints the same way. Stacks are merged into one graph.
+ *
+ * A stack without `src` contributes nothing here — it has no declared source to
+ * scope to (its live nodes still show as foreign in the overlay).
+ */
+export async function buildDeclaredPerStack(stacks, projectPath) {
+    var _a;
+    const nodes = [];
+    const edges = [];
+    // Which nodes belong to which stack (#1433). This is not derived or guessed:
+    // the stack is declared in config and every node here is being renamed with
+    // its name on the line below. The membership was always known and thrown
+    // away, which left `byStack` — the axis consumers draw boundary boxes from —
+    // empty for the one project shape that genuinely has side-by-side stacks.
+    const byStack = {};
+    for (const st of stacks) {
+        if (!st.src)
+            continue;
+        const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
+        const q = (id) => `${st.name}::${id}`;
+        for (const n of g.nodes) {
+            const id = q(n.id);
+            nodes.push({ ...n, id });
+            (byStack[_a = st.name] ?? (byStack[_a] = [])).push(id);
+        }
+        for (const e of g.edges)
+            edges.push({ ...e, from: q(e.from), to: q(e.to) });
+    }
+    for (const ids of Object.values(byStack))
+        ids.sort();
+    const groups = Object.keys(byStack).length ? { byStack } : {};
+    return { nodes, edges, groups };
+}

package/dist/graph-detail.js

@@ -0,0 +1,207 @@
+export const DETAIL = {
+    STACKS: 0,
+    COMPOSITES: 1,
+    DECLARABLES: 2,
+    ATTRIBUTES: 3,
+};
+/** Apply a detail tier to the base (declarable-level) IR. */
+export function applyDetail(ir, level) {
+    switch (level) {
+        case 0:
+            return toStacks(ir);
+        case 1:
+            return toComposites(ir);
+        case 3:
+            return toAttributes(ir);
+        case 2:
+        default:
+            return toDeclarables(ir);
+    }
+}
+/** Overlay paint (`_status`, `_unobserved`, …) is a verdict about the node,
+ * not a property of the resource — it survives every tier above STACKS so a
+ * zoomed-out drift view keeps its colours. */
+function paintAttrs(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs))
+        if (k.startsWith("_"))
+            out[k] = v;
+    return out;
+}
+/** A `{ $ref: "producer.attribute" }` envelope — a reference, not a property tree. */
+function isRefEnvelope(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        typeof v.$ref === "string");
+}
+/** T2's resource view of a node's attrs: overlay paint, scalar fields
+ * (identity, status-relevant values), and top-level reference envelopes.
+ * Nested property trees — a k8s `spec`/`metadata`, a Tags list — wait for T3. */
+function resourceAttrs(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (k.startsWith("_") || v === null || typeof v !== "object" || isRefEnvelope(v)) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function edgeSortKey(e) {
+    return `${e.from}\0${e.to}\0${e.viaAttr ?? ""}`;
+}
+function sortEdges(edges) {
+    return edges.sort((a, b) => edgeSortKey(a).localeCompare(edgeSortKey(b)));
+}
+function byLexiconOf(nodes) {
+    var _a;
+    const out = {};
+    for (const n of nodes)
+        (out[_a = n.lexicon] ?? (out[_a] = [])).push(n.id);
+    const sorted = {};
+    for (const k of Object.keys(out).sort())
+        sorted[k] = out[k].sort();
+    return sorted;
+}
+/** T0 — collapse every resource to its lexicon; edges become cross-lexicon deps. */
+function toStacks(ir) {
+    const lexOf = new Map(ir.nodes.map((n) => [n.id, n.lexicon]));
+    const lexicons = [...new Set(ir.nodes.map((n) => n.lexicon))].sort();
+    const nodes = lexicons.map((l) => ({ id: l, kind: "stack", lexicon: l, attrs: {} }));
+    const seen = new Map();
+    for (const e of ir.edges) {
+        const from = lexOf.get(e.from);
+        const to = lexOf.get(e.to);
+        if (!from || !to || from === to)
+            continue;
+        const key = `${from}\0${to}`;
+        if (!seen.has(key))
+            seen.set(key, { from, to, kind: "ref" });
+    }
+    return { nodes, edges: sortEdges([...seen.values()]), groups: {} };
+}
+/** T2 — every resource, each carrying the resource view of its attrs (the
+ * scalar/reference projection; the full property tree is T3's addition). */
+function toDeclarables(ir) {
+    return { ...ir, nodes: ir.nodes.map((n) => ({ ...n, attrs: resourceAttrs(n.attrs) })) };
+}
+/** T1 — collapse each composite instance to one node; internal edges disappear.
+ * Topology view: surviving plain nodes keep only overlay paint, not properties. */
+function toComposites(ir) {
+    const idMap = new Map();
+    for (const n of ir.nodes)
+        idMap.set(n.id, n.compositeInstance ?? n.id);
+    const instances = new Map();
+    const plain = [];
+    for (const n of ir.nodes) {
+        if (n.compositeInstance) {
+            const arr = instances.get(n.compositeInstance) ?? [];
+            arr.push(n);
+            instances.set(n.compositeInstance, arr);
+        }
+        else {
+            plain.push({ ...n, attrs: paintAttrs(n.attrs) });
+        }
+    }
+    const nodes = [...plain];
+    for (const [inst, members] of instances) {
+        const types = new Set(members.map((m) => m.compositeParent).filter(Boolean));
+        const lexicons = new Set(members.map((m) => m.lexicon));
+        nodes.push({
+            id: inst,
+            kind: types.size === 1 ? [...types][0] : "Composite",
+            lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
+            attrs: { members: members.length },
+        });
+    }
+    const seen = new Map();
+    for (const e of ir.edges) {
+        const from = idMap.get(e.from) ?? e.from;
+        const to = idMap.get(e.to) ?? e.to;
+        if (from === to)
+            continue; // edge internal to a composite
+        // A property label only makes sense when neither endpoint was collapsed.
+        const collapsed = from !== e.from || to !== e.to;
+        const edge = collapsed
+            ? { from, to, kind: "ref" }
+            : { from, to, kind: "ref", viaAttr: e.viaAttr };
+        const key = `${from}\0${to}\0${edge.viaAttr ?? ""}`;
+        if (!seen.has(key))
+            seen.set(key, edge);
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    // Carry the cross-stack import list forward: parameter/import nodes aren't
+    // composites, so they survive the collapse as plain nodes — a viewer that
+    // hides imports (or matches them across stacks) needs `imports` at every tier,
+    // not just the base + ATTRIBUTES. Filter to handles whose node survived.
+    const surviving = new Set(nodes.map((n) => n.id));
+    const imports = ir.imports?.filter((i) => surviving.has(i.node));
+    return {
+        nodes,
+        edges: sortEdges([...seen.values()]),
+        groups: { byLexicon: byLexiconOf(nodes) },
+        ...(imports && imports.length ? { imports } : {}),
+    };
+}
+/** T3 — annotate each edge with the producer attribute it references. */
+function toAttributes(ir) {
+    const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
+    const edges = ir.edges.map((e) => {
+        const node = nodeById.get(e.from);
+        const toAttr = node ? findRefAttr(node.attrs, e.to) : undefined;
+        return toAttr ? { ...e, toAttr } : { ...e };
+    });
+    return { ...ir, edges };
+}
+/** Find the attribute in a `{ $ref: "producer.attribute" }` envelope under attrs. */
+function findRefAttr(attrs, producer) {
+    let found;
+    const visit = (v) => {
+        if (found !== undefined || v === null || typeof v !== "object")
+            return;
+        if (Array.isArray(v)) {
+            for (const item of v)
+                visit(item);
+            return;
+        }
+        const ref = v.$ref;
+        if (typeof ref === "string") {
+            const dot = ref.indexOf(".");
+            if (dot > 0 && ref.slice(0, dot) === producer) {
+                found = ref.slice(dot + 1);
+                return;
+            }
+        }
+        for (const val of Object.values(v))
+            visit(val);
+    };
+    visit(attrs);
+    return found;
+}
+/**
+ * chant #1489 — the message to print when `--detail 3` changed nothing.
+ *
+ * T3 adds two things over T2: the full property tree on each node and the
+ * producer attribute on `$ref`-derived edges. A graph whose nodes carry no
+ * properties beyond the resource view AND whose edges reference nothing (they
+ * link by name or label convention) gains neither, so levels 2 and 3 come out
+ * byte-identical — which reads as a broken dial from any consumer stepping
+ * through the levels (behold#131 was filed over exactly this). Accepting a
+ * value that changes nothing without saying so is the bug; this names it.
+ *
+ * Returns the warning text, or undefined when detail 3 did add something.
+ * `base` is the pre-detail IR the caller already holds (the same one it fed
+ * `applyDetail`); the T2 view to compare against is derived here, so callers
+ * don't run the projection twice for a message. Pure — no I/O.
+ */
+export function detailInertNotice(base, detailed) {
+    if (JSON.stringify(detailed) !== JSON.stringify(toDeclarables(base)))
+        return undefined;
+    const edges = base.edges.length;
+    const why = edges === 0
+        ? "this graph has no edges at all"
+        : `none of this graph's ${edges} edge(s) reference a producer attribute — they link by name or label convention`;
+    return (`--detail 3 adds each node's full property tree and the producer attribute on reference edges, ` +
+        `but every node's properties already fit the resource view and ${why}, ` +
+        `so the output is identical to --detail 2.`);
+}

package/dist/graph-dot.js

@@ -0,0 +1,54 @@
+/**
+ * Render the graph IR as Graphviz DOT. Pure text — no `dot` needed to produce
+ * it. Two consumers: render directly with `dot -Tsvg` (mingrammer-style), or
+ * feed it to a layout engine for node positions that a custom painter draws
+ * (the rackattack pattern; see {@link toLayout}). See issue #497 / epic #492.
+ *
+ * Consumes whatever IR it is given, so `--detail` (and future `--lens`) flow
+ * through for free.
+ */
+export function toDot(ir) {
+    const lines = ["digraph chant {", "  rankdir=TB;", '  node [shape=box];'];
+    // Cluster by wave (component graph) when present, else by lexicon (entity graph).
+    const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
+    const grouped = new Set();
+    if (clusters) {
+        for (const [name, members] of Object.entries(clusters)) {
+            lines.push(`  subgraph ${q(`cluster_${name}`)} {`);
+            lines.push(`    label=${q(name)};`);
+            for (const id of members) {
+                const node = ir.nodes.find((n) => n.id === id);
+                if (!node)
+                    continue;
+                grouped.add(id);
+                lines.push(`    ${nodeLine(node)}`);
+            }
+            lines.push("  }");
+        }
+    }
+    for (const node of ir.nodes) {
+        if (grouped.has(node.id))
+            continue;
+        lines.push(`  ${nodeLine(node)}`);
+    }
+    for (const e of ir.edges)
+        lines.push(`  ${edgeLine(e)}`);
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+function nodeLine(node) {
+    const label = node.kind && node.kind !== node.id ? `${node.id}\n${node.kind}` : node.id;
+    return `${q(node.id)} [label=${q(label)}];`;
+}
+function edgeLine(e) {
+    const from = q(e.from);
+    const to = q(e.to);
+    const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
+    return label ? `${from} -> ${to} [label=${q(label)}];` : `${from} -> ${to};`;
+}
+/** Quote a DOT identifier/label. Graphviz accepts any string in double quotes;
+ * a real newline becomes the DOT line-break escape. */
+function q(s) {
+    const esc = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+    return `"${esc}"`;
+}

package/dist/graph-effective.js

@@ -0,0 +1,107 @@
+/**
+ * Fold DERIVED reachability facts onto EC2 instance nodes so a single-node query
+ * can answer questions that are otherwise a multi-hop join with a union (#1139).
+ *
+ * Two facts, both things a live AWS-CLI sweep gets wrong because it can't cheaply
+ * resolve the topology:
+ *
+ *  - `effectiveIngress` — the union of security-group ingress rules reachable
+ *    from the instance, BOTH directly (`SecurityGroupIds`) AND through its launch
+ *    template (`LaunchTemplate → LaunchTemplateData → SecurityGroupIds`). The
+ *    launch-template hop is exactly what a CLI agent misses (it under-counts
+ *    SSH-reachable instances). Each rule is normalized to `proto:port:cidr`
+ *    (e.g. `tcp:22:0.0.0.0/0`) so it is precisely queryable.
+ *  - `internetFacing` — whether the instance's subnet routes to an Internet
+ *    Gateway (`subnet ← SubnetRouteTableAssociation → RouteTable ← Route →
+ *    InternetGateway`). "Public subnet" means an IGW route, not
+ *    `MapPublicIpOnLaunch`.
+ *
+ * With these, "instances SSH-reachable from the internet" is one predicate:
+ *   `kind:EC2::Instance attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0`
+ * — no hand-joined CLI sweep, no over/under-counting.
+ */
+export function enrichEffectiveTopology(ir) {
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    const edges = ir.edges ?? [];
+    const kind = (n) => n?.kind ?? "";
+    const isKind = (n, suffix) => !!n && (kind(n) === suffix || kind(n).endsWith("::" + suffix));
+    const via = (...names) => (v) => names.includes(v);
+    /** Out-neighbours of `id` (edges from → to), optionally filtered by viaAttr. */
+    const out = (id, pred) => edges
+        .filter((e) => e.from === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+        .map((e) => byId.get(e.to))
+        .filter((x) => !!x);
+    /** In-neighbours of `id` (edges to ← from), optionally filtered by viaAttr. */
+    const incoming = (id, pred) => edges
+        .filter((e) => e.to === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+        .map((e) => byId.get(e.from))
+        .filter((x) => !!x);
+    const normalizeIngress = (sg) => {
+        const rules = sg.attrs?.["SecurityGroupIngress"];
+        if (!Array.isArray(rules))
+            return [];
+        return rules.map((r) => {
+            const rule = r;
+            const proto = String(rule.IpProtocol ?? "-1");
+            const from = rule.FromPort;
+            const to = rule.ToPort;
+            const port = from == null ? "all" : from === to ? `${from}` : `${from}-${to}`;
+            const cidr = rule.CidrIp ??
+                rule.CidrIpv6 ??
+                (rule.SourceSecurityGroupId ? `sg:${String(rule.SourceSecurityGroupId)}` : "?");
+            return `${proto}:${port}:${cidr}`;
+        });
+    };
+    /** Security groups reachable from an instance — direct and via launch template. */
+    const effectiveSgs = (inst) => {
+        const direct = out(inst.id, via("SecurityGroupIds", "SecurityGroupId"));
+        const templates = out(inst.id, via("LaunchTemplate", "LaunchTemplateId"));
+        const viaTemplate = templates
+            .flatMap((lt) => out(lt.id, via("LaunchTemplateData", "SecurityGroupIds", "SecurityGroupId")))
+            .filter((n) => isKind(n, "SecurityGroup"));
+        const all = [...direct.filter((n) => isKind(n, "SecurityGroup")), ...viaTemplate];
+        return [...new Map(all.map((s) => [s.id, s])).values()];
+    };
+    /** The IGW an instance's subnet routes to (evidence), or undefined. */
+    const internetFacingVia = (inst) => {
+        for (const subnet of out(inst.id, via("SubnetId")).filter((n) => isKind(n, "Subnet"))) {
+            const assocs = incoming(subnet.id, via("SubnetId")).filter((a) => isKind(a, "SubnetRouteTableAssociation"));
+            const routeTables = assocs.flatMap((a) => out(a.id, via("RouteTableId")).filter((n) => isKind(n, "RouteTable")));
+            for (const rt of routeTables) {
+                const routes = incoming(rt.id, via("RouteTableId")).filter((n) => isKind(n, "Route"));
+                for (const route of routes) {
+                    const dest = route.attrs?.["DestinationCidrBlock"];
+                    const igw = out(route.id, via("GatewayId")).find((g) => isKind(g, "InternetGateway"));
+                    if (igw && (dest == null || dest === "0.0.0.0/0")) {
+                        const id = igw.id.includes("::") ? igw.id.slice(igw.id.lastIndexOf("::") + 2) : igw.id;
+                        return `${rt.id.includes("::") ? rt.id.slice(rt.id.lastIndexOf("::") + 2) : rt.id} → ${id}`;
+                    }
+                }
+            }
+        }
+        return undefined;
+    };
+    const nodes = ir.nodes.map((n) => {
+        if (!isKind(n, "Instance"))
+            return n;
+        const effectiveIngress = effectiveSgs(n).flatMap(normalizeIngress);
+        // A live enrichment may already have set internetFacing (+ its evidence) for
+        // a subnet chant doesn't model declaratively (e.g. the account's default
+        // VPC). Keep that truth; otherwise derive it from the declared route topology.
+        const attrs = (n.attrs ?? {});
+        const liveFacing = attrs["internetFacing"] === true;
+        const declaredVia = internetFacingVia(n);
+        const via = attrs["internetFacingVia"] ?? declaredVia;
+        return {
+            ...n,
+            attrs: { ...attrs, effectiveIngress, internetFacing: liveFacing || !!declaredVia, ...(via ? { internetFacingVia: via } : {}) },
+        };
+    });
+    // Record what this pass computed, so a caller can report the graph's derived surface
+    // without hardcoding attribute names. Only kinds actually enriched are listed.
+    const enriched = nodes.some((n) => isKind(n, "Instance"));
+    const derivedAttrs = enriched
+        ? { ...(ir.derivedAttrs ?? {}), Instance: ["internetFacing", "effectiveIngress"] }
+        : ir.derivedAttrs;
+    return { ...ir, nodes, ...(derivedAttrs ? { derivedAttrs } : {}) };
+}