@intentius/chant 0.124.45 → 0.124.48

package/dist/terraform/cuts.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Cuts and reference-closed sets over the carve graph (#3909).
+ *
+ * `carve advise` scores one block at a time. A consumer splitting one root into
+ * several (terragucci's estate carving) needs the same question for a set:
+ * which edges cross its boundary and which way, and the smallest set around a
+ * seed whose crossings all run a way the caller allows. These are pure
+ * functions over `TfGraph`, on the index and walk in `reach.ts`, so the rules
+ * there hold here too: folds contract first, outputs are terminal and counted
+ * apart, modules and unresolved `count` are named as hiding their contents, a
+ * `depends_on` cycle terminates, and `crossStack` edges are counted apart.
+ *
+ * Nothing here ranks sets, reads state or plan times, writes HCL, or knows
+ * about roots or backends; that stays with the consumer.
+ */
+import type { TfEdge, TfGraph } from "./types.js";
+/** Cut edges of one direction, counted. */
+export interface CutCount {
+    /** Edges whose reading side is a resource or module block. */
+    resources: number;
+    /** Edges whose reading side is an `output` block. */
+    outputs: number;
+    /** Of all of them, the `crossStack` edges (a CDK `Fn::ImportValue`). */
+    crossStack: number;
+}
+/** A set of blocks, as the walks see it. */
+export interface BlockSet {
+    /** Resource and module addresses, each fold parent with the blocks folded into it. Sorted. */
+    resources: string[];
+    /** `output.<name>` pseudo-addresses in the set. Sorted. */
+    outputs: string[];
+}
+export interface Cuts extends BlockSet {
+    /** Edges where something outside reads something inside, as the graph holds them. */
+    inbound: TfEdge[];
+    /** Edges where something inside reads something outside. */
+    outbound: TfEdge[];
+    counts: {
+        inbound: CutCount;
+        outbound: CutCount;
+    };
+    /** Cuts run in both directions: the set can move only with wiring both ways. */
+    bothWays: boolean;
+}
+/** The cut directions a closure may leave: `inbound` (outside may read in), `outbound` (inside may read out), or `none`. */
+export type CutAllowance = "inbound" | "outbound" | "none";
+export interface Closure extends Cuts {
+    /** The seeds as the walk saw them, folds contracted. */
+    seeds: string[];
+    allow: CutAllowance;
+    /**
+     * How many resource instances the set stands for: each block once, or its
+     * instance count once `--state` resolved it. `"unknown"` where a module or an
+     * unresolved `count`/`for_each` hides how much it holds; `hiddenBy` names them.
+     */
+    instances: number | "unknown";
+    hiddenBy?: string[];
+}
+export interface Component extends BlockSet {
+    /** As {@link Closure.instances}. */
+    instances: number | "unknown";
+    hiddenBy?: string[];
+}
+/**
+ * The graph's weakly connected components (#3909): blocks joined by a
+ * reference either way, fold-contracted, each module one node. An output never
+ * joins two components, since outputs are terminal; it is listed in every
+ * component it reads into. Components are sorted by their first address.
+ */
+export declare function components(graph: TfGraph): Component[];
+/**
+ * Every edge crossing the boundary of `addresses` (#3909). A folded block in
+ * the set brings its parent and siblings, and a fold parent its folded blocks,
+ * before anything is counted, so an edge inside one fold is never a cut. An
+ * `output.<name>` in the set is inside it like any block.
+ *
+ * Throws when an address is not a block of the graph.
+ */
+export declare function cuts(graph: TfGraph, addresses: Iterable<string>): Cuts;
+/**
+ * The smallest superset of `seeds` whose remaining cuts all run in the
+ * direction `allow` permits, plus those cuts (#3909).
+ *
+ *  - `outbound`: nothing outside may read in, so the set takes every
+ *    dependent of the seeds, outputs included.
+ *  - `inbound`: nothing inside may read out, so the set takes everything the
+ *    seeds depend on.
+ *  - `none`: the seeds' whole components, with each output that reads only
+ *    into them.
+ *
+ * Outputs are terminal, so none of these walks passes through one. An output
+ * that reads both the set and something outside it is therefore a cut no
+ * closure removes: under `none` it stays outside and its read into the set is
+ * left as an inbound cut, for the caller to wire.
+ */
+export declare function closure(graph: TfGraph, seeds: Iterable<string>, allow: CutAllowance): Closure;
+//# sourceMappingURL=cuts.d.ts.map

package/dist/terraform/cuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cuts.d.ts","sourceRoot":"","sources":["../../src/terraform/cuts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE/C,2CAA2C;AAC3C,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,IAAK,SAAQ,QAAQ;IACpC,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAClD,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,4HAA4H;AAC5H,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,OAAQ,SAAQ,IAAI;IACnC,wDAAwD;IACxD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,oCAAoC;IACpC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,EAAE,CAatD;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAmB7F"}

package/dist/terraform/cuts.js

@@ -0,0 +1,138 @@
+/**
+ * Cuts and reference-closed sets over the carve graph (#3909).
+ *
+ * `carve advise` scores one block at a time. A consumer splitting one root into
+ * several (terragucci's estate carving) needs the same question for a set:
+ * which edges cross its boundary and which way, and the smallest set around a
+ * seed whose crossings all run a way the caller allows. These are pure
+ * functions over `TfGraph`, on the index and walk in `reach.ts`, so the rules
+ * there hold here too: folds contract first, outputs are terminal and counted
+ * apart, modules and unresolved `count` are named as hiding their contents, a
+ * `depends_on` cycle terminates, and `crossStack` edges are counted apart.
+ *
+ * Nothing here ranks sets, reads state or plan times, writes HCL, or knows
+ * about roots or backends; that stays with the consumer.
+ */
+import { carveIndex, cmp, hidesContents, isOutputAddress, walkFrom, weigh } from "./reach.js";
+/**
+ * The graph's weakly connected components (#3909): blocks joined by a
+ * reference either way, fold-contracted, each module one node. An output never
+ * joins two components, since outputs are terminal; it is listed in every
+ * component it reads into. Components are sorted by their first address.
+ */
+export function components(graph) {
+    const index = carveIndex(graph);
+    const assigned = new Set();
+    const found = [];
+    for (const address of [...index.nodes.keys()].sort(cmp)) {
+        const start = index.rep(address);
+        if (assigned.has(start))
+            continue;
+        const reached = walkFrom(index, [start], "both");
+        const reps = [start, ...[...reached.keys()].filter((a) => !isOutputAddress(a))];
+        for (const rep of reps)
+            assigned.add(rep);
+        found.push({ ...blockSet(index, reps, [...reached.keys()].filter(isOutputAddress)), ...holdings(index, reps) });
+    }
+    return found;
+}
+/**
+ * Every edge crossing the boundary of `addresses` (#3909). A folded block in
+ * the set brings its parent and siblings, and a fold parent its folded blocks,
+ * before anything is counted, so an edge inside one fold is never a cut. An
+ * `output.<name>` in the set is inside it like any block.
+ *
+ * Throws when an address is not a block of the graph.
+ */
+export function cuts(graph, addresses) {
+    const index = carveIndex(graph);
+    return cutsOf(index, contract(index, addresses));
+}
+/**
+ * The smallest superset of `seeds` whose remaining cuts all run in the
+ * direction `allow` permits, plus those cuts (#3909).
+ *
+ *  - `outbound`: nothing outside may read in, so the set takes every
+ *    dependent of the seeds, outputs included.
+ *  - `inbound`: nothing inside may read out, so the set takes everything the
+ *    seeds depend on.
+ *  - `none`: the seeds' whole components, with each output that reads only
+ *    into them.
+ *
+ * Outputs are terminal, so none of these walks passes through one. An output
+ * that reads both the set and something outside it is therefore a cut no
+ * closure removes: under `none` it stays outside and its read into the set is
+ * left as an inbound cut, for the caller to wire.
+ */
+export function closure(graph, seeds, allow) {
+    const index = carveIndex(graph);
+    const start = contract(index, seeds);
+    const direction = allow === "outbound" ? "in" : allow === "inbound" ? "out" : "both";
+    const members = new Set([...start, ...walkFrom(index, start, direction).keys()]);
+    if (allow === "none") {
+        for (const address of [...members]) {
+            if (!isOutputAddress(address) || start.has(address))
+                continue;
+            const reads = (index.adj.out.get(address) ?? []).map((e) => e.to);
+            if (!reads.every((to) => members.has(to)))
+                members.delete(address);
+        }
+    }
+    const found = cutsOf(index, members);
+    return {
+        ...found,
+        seeds: [...start].sort(cmp),
+        allow,
+        ...holdings(index, [...members].filter((a) => !isOutputAddress(a))),
+    };
+}
+/** The addresses as the walks see them: each fold child replaced by its parent. Throws on an unknown address. */
+function contract(index, addresses) {
+    const out = new Set();
+    for (const address of addresses) {
+        const known = index.nodes.has(address) || (isOutputAddress(address) && index.adj.out.has(address));
+        if (!known)
+            throw new Error(`carve: ${address} is not a resource, module or output in this graph`);
+        out.add(index.rep(address));
+    }
+    return out;
+}
+function cutsOf(index, members) {
+    const inbound = [];
+    const outbound = [];
+    for (const address of members) {
+        for (const e of index.adj.in.get(address) ?? [])
+            if (!members.has(e.from))
+                inbound.push(e.edge);
+        for (const e of index.adj.out.get(address) ?? [])
+            if (!members.has(e.to))
+                outbound.push(e.edge);
+    }
+    const byEnds = (a, b) => cmp(a.from, b.from) || cmp(a.to, b.to);
+    inbound.sort(byEnds);
+    outbound.sort(byEnds);
+    const reps = [...members];
+    return {
+        ...blockSet(index, reps.filter((a) => !isOutputAddress(a)), reps.filter(isOutputAddress)),
+        inbound,
+        outbound,
+        counts: { inbound: countOf(inbound), outbound: countOf(outbound) },
+        bothWays: inbound.length > 0 && outbound.length > 0,
+    };
+}
+function countOf(edges) {
+    const outputs = edges.filter((e) => e.fromKind === "output").length;
+    return { resources: edges.length - outputs, outputs, crossStack: edges.filter((e) => e.crossStack).length };
+}
+function blockSet(index, reps, outputs) {
+    return {
+        resources: reps.flatMap((rep) => index.membersOf(rep)).sort(cmp),
+        outputs: [...outputs].sort(cmp),
+    };
+}
+function holdings(index, reps) {
+    const instances = weigh(index, reps);
+    if (instances !== "unknown")
+        return { instances };
+    return { instances, hiddenBy: reps.filter((a) => hidesContents(index.nodes.get(a))).sort(cmp) };
+}

package/dist/terraform/folds.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fold detection for the carve graph, shared by the scorer and the walks.
+ *
+ * A sub-resource whose type inlines into a parent (`foldParentOf`) carves with
+ * that parent when the parent is in the estate under the same name:
+ * `aws_s3_bucket_versioning.assets` goes with `aws_s3_bucket.assets`. The
+ * scorer drops it from the ranking and discounts its edge to the parent; the
+ * walks in `reach.ts` contract it into the parent before stepping, since an
+ * uncontracted walk counts the child as a separate dependent (#2325 measured a
+ * 100% overstatement on the sample estate). It lived privately in `score.ts`
+ * until the walks needed it.
+ */
+import type { TfGraph } from "./types.js";
+export interface Folds {
+    /** Every address that folds into a parent present in the estate. */
+    folded: Set<string>;
+    /** Parent address → the addresses folded into it. */
+    childrenOf: Map<string, Set<string>>;
+}
+/**
+ * Build the set of addresses that fold into a parent present in the estate, plus
+ * the reverse lookup (parent → its folded children), so a parent can discount
+ * inbound edges coming from its own folded sub-resources.
+ */
+export declare function computeFolds(graph: TfGraph): Folds;
+//# sourceMappingURL=folds.d.ts.map

package/dist/terraform/folds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folds.d.ts","sourceRoot":"","sources":["../../src/terraform/folds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,oEAAoE;IACpE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,qDAAqD;IACrD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAelD"}

package/dist/terraform/folds.js

@@ -0,0 +1,38 @@
+/**
+ * Fold detection for the carve graph, shared by the scorer and the walks.
+ *
+ * A sub-resource whose type inlines into a parent (`foldParentOf`) carves with
+ * that parent when the parent is in the estate under the same name:
+ * `aws_s3_bucket_versioning.assets` goes with `aws_s3_bucket.assets`. The
+ * scorer drops it from the ranking and discounts its edge to the parent; the
+ * walks in `reach.ts` contract it into the parent before stepping, since an
+ * uncontracted walk counts the child as a separate dependent (#2325 measured a
+ * 100% overstatement on the sample estate). It lived privately in `score.ts`
+ * until the walks needed it.
+ */
+import { foldParentOf } from "./tier-map.js";
+/**
+ * Build the set of addresses that fold into a parent present in the estate, plus
+ * the reverse lookup (parent → its folded children), so a parent can discount
+ * inbound edges coming from its own folded sub-resources.
+ */
+export function computeFolds(graph) {
+    const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+    const folded = new Set();
+    const childrenOf = new Map();
+    for (const node of graph.nodes) {
+        if (node.kind !== "resource" || !node.type)
+            continue;
+        const parentType = foldParentOf(node.type);
+        if (!parentType)
+            continue;
+        const parentAddress = `${parentType}.${node.name}`;
+        if (!byAddress.has(parentAddress))
+            continue; // sub-resource without its parent → score it on its own
+        folded.add(node.address);
+        if (!childrenOf.has(parentAddress))
+            childrenOf.set(parentAddress, new Set());
+        childrenOf.get(parentAddress).add(node.address);
+    }
+    return { folded, childrenOf };
+}

package/dist/terraform/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/terraform/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAU,MAAM,SAAS,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAKpE,UAAU,MAAM;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4BD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe/D;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAiB/D;AA8LD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAsFhF;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtE;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/terraform/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAU,MAAM,SAAS,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAKpE,UAAU,MAAM;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4BD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe/D;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAiB/D;AAqMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAwFhF;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtE;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvE"}

package/dist/terraform/graph.js

@@ -266,6 +266,14 @@ function throughReferrers(refs, resolved) {
 function blockHasMeta(block, key) {
     return !!block && typeof block === "object" && key in block;
 }
+/** Which expansion meta-argument a block carries, as a spreadable `TfNode` field (#2325). */
+function expansionOf(block) {
+    if (blockHasMeta(block, "count"))
+        return { expansion: "count" };
+    if (blockHasMeta(block, "for_each"))
+        return { expansion: "for_each" };
+    return {};
+}
 /**
  * The literal string at a dotted path into a block, or undefined when the path
  * misses or lands on an interpolation. A dotted path walks nested blocks —
@@ -365,6 +373,7 @@ export function buildGraph(tree, exprRefs) {
                 name,
                 instances: 1,
                 hasDynamic: dynamic || touchesData,
+                ...expansionOf(block),
                 identity: literalIdentity(block, type),
                 dataSourceValues: dataSourceValues(block, type),
             });
@@ -384,6 +393,7 @@ export function buildGraph(tree, exprRefs) {
             name,
             instances: 1,
             hasDynamic: dynamic || touchesData,
+            ...expansionOf(block),
         });
     }
     // Output blocks: referrers without being nodes (#1638). Their pseudo-address

package/dist/terraform/reach.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Transitive reachability over the carve graph (#2325).
+ *
+ * `inboundEdges`/`outboundEdges` in `graph.ts` answer one hop with a linear
+ * scan, which is right for the scorer's depth-1 counts and wrong as the step of
+ * a walk: calling it per node per step is O(V²E). This module builds one
+ * index per graph instead, and walks it with the same breadth-first walk
+ * `chant search` uses (`graph-walk.ts`).
+ *
+ * Four rules from the spike (docs/design/carve-dependency-blast-radius-spike.md)
+ * hold for every walk here and for the set functions in `cuts.ts` built on it:
+ *
+ *  - Folds contract first. A folded sub-resource is its parent for the walk, so
+ *    `aws_s3_bucket_versioning.assets` is never a dependent of
+ *    `aws_s3_bucket.assets`, and a node reading the child depends on the
+ *    parent.
+ *  - Outputs are terminal and counted apart. An `output.<name>` pseudo-address
+ *    has no inbound edges, so it never extends a path; it is reported in its
+ *    own list.
+ *  - Modules and unresolved `count`/`for_each` hide how much a node holds. A
+ *    `module.x` node is one node whatever it contains, and `count = 20` is one
+ *    node until `--state` resolves it. They are walked through and named, so a
+ *    caller can say `unknown` instead of a number.
+ *  - Cross-stack hops are told apart. On the CDK path an `Fn::ImportValue` edge
+ *    carries `crossStack: true`; what is reachable only through one is listed
+ *    separately.
+ *
+ * Pure, like the rest of the carve analysis. `src/cdk/graph.ts` emits the same
+ * `TfGraph`, so one implementation covers both sources.
+ */
+import { type Adjacency } from "../graph-walk.js";
+import type { TfEdge, TfGraph, TfNode } from "./types.js";
+/** An edge with both ends contracted to their fold parents. `edge` is the edge as the graph holds it. */
+export interface ContractedEdge extends TfEdge {
+    edge: TfEdge;
+}
+/** The index every walk over one graph shares. Built once per graph; see {@link carveIndex}. */
+export interface CarveIndex {
+    graph: TfGraph;
+    /** Every node by address, folded sub-resources included. */
+    nodes: Map<string, TfNode>;
+    /** The address a walk sees for `address`: its fold parent, or itself. */
+    rep(address: string): string;
+    /** A walked node's own blocks: itself first, then what folds into it, sorted. */
+    membersOf(address: string): string[];
+    /** Contracted edges by both ends. An edge internal to one fold is dropped. */
+    adj: Adjacency<ContractedEdge>;
+    /** The graph has at least one `crossStack` edge (a CDK assembly of several stacks). */
+    crossStack: boolean;
+}
+/**
+ * The fold-contracted adjacency index for a graph, built on first use and
+ * cached against the graph object. O(V+E) to build; every walk after that is
+ * O(V+E). A caller that mutates `graph.edges` after the first walk must pass a
+ * new graph object (`applyStateCounts` only touches node instance counts, which
+ * the index reads live).
+ */
+export declare function carveIndex(graph: TfGraph): CarveIndex;
+/** `output.<name>`: a pseudo-address `buildGraph` gives an output block's edges (#1638). */
+export declare function isOutputAddress(address: string): boolean;
+/**
+ * Whether a node stands for an amount of infrastructure the graph cannot see:
+ * a Terraform `module` block (one node, whatever it holds; state is not read
+ * inside modules), or a `count`/`for_each` block whose instance count no
+ * `.tfstate` resolved. A CDK L3 construct is also `kind: "module"`, but its
+ * members are listed and its address is a construct path, so it hides nothing.
+ */
+export declare function hidesContents(node: TfNode): boolean;
+/**
+ * Which way a walk steps: `in` follows who reads a node (its dependents), `out`
+ * what it reads, `both` either (weak connectivity, #3909). An output is
+ * terminal every way: it is reached, never stepped from.
+ */
+export type WalkDirection = "in" | "out" | "both";
+/**
+ * Walk from `seeds` (already contracted) and return every node reached with its
+ * shortest depth, seeds excluded. `sameStack` refuses `crossStack` edges.
+ */
+export declare function walkFrom(index: CarveIndex, seeds: Iterable<string>, direction: WalkDirection, opts?: {
+    sameStack?: boolean;
+}): Map<string, number>;
+/** What a walk from one node reached. Every list is sorted and holds contracted addresses. */
+export interface Reach {
+    /** The node the walk started from: the requested address, or its fold parent. */
+    address: string;
+    /** Resource and module nodes reached, the start excluded. */
+    resources: string[];
+    /** `output.<name>` pseudo-addresses reached; terminal, never in `resources`. */
+    outputs: string[];
+    /** The longest shortest path to anything reached, outputs included; 0 when nothing was. */
+    depth: number;
+    /** Of `resources`, those reached only through a `crossStack` edge. Empty off the CDK path. */
+    crossStack: string[];
+    /** Of `resources`, those that hide how much they hold (see {@link hidesContents}). */
+    hidden: string[];
+}
+/**
+ * Everything reachable from `address` (#2325). Direction `in` (the default)
+ * walks dependents: what a change to `address` reaches, its blast radius.
+ * Direction `out` walks dependencies: what `address` needs.
+ *
+ * Throws when `address` is not a node of the graph.
+ */
+export declare function reach(graph: TfGraph, address: string, opts?: {
+    direction?: WalkDirection;
+}): Reach;
+/** Code-point order, as `buildGraph` sorts: locale-independent. */
+export declare function cmp(a: string, b: string): number;
+/**
+ * How far a change to one node reaches, as `carve advise` reports it (#2326):
+ * its own axis beside the peelability score, never a penalty term. Every score
+ * term is a unit of work (an inbound edge is one data-source patch); a
+ * transitive dependent is not work, nobody patches it, and its count can run
+ * far past what a 0-100 score carries.
+ */
+export interface BlastRadius {
+    /**
+     * Resources and modules that depend on the node, directly or not, weighted by
+     * instance count when `--state` resolved it. `"unknown"` when one of them is
+     * a module or a `count`/`for_each` no state resolved: see `hiddenBy`.
+     */
+    resources: number | "unknown";
+    /** `output` blocks that read the node or one of its dependents. */
+    outputs: number;
+    /** Hops to the farthest dependent, outputs included; 0 when nothing depends on it. */
+    depth: number;
+    /**
+     * Of `resources`, those reachable only through a `crossStack` edge (a CDK
+     * `Fn::ImportValue`), weighted the same way. Present only when the graph has
+     * such an edge.
+     */
+    crossStack?: number | "unknown";
+    /** The dependents that make a count `"unknown"`. Present only when one does. */
+    hiddenBy?: string[];
+}
+/** The instances `addresses` stand for, or `"unknown"` when one of them hides its contents. */
+export declare function weigh(index: CarveIndex, addresses: readonly string[]): number | "unknown";
+/** The {@link BlastRadius} of `address`: its {@link reach} through dependents, counted. */
+export declare function blastRadius(graph: TfGraph, address: string): BlastRadius;
+//# sourceMappingURL=reach.d.ts.map

package/dist/terraform/reach.d.ts.map

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

package/dist/terraform/reach.js

@@ -0,0 +1,170 @@
+/**
+ * Transitive reachability over the carve graph (#2325).
+ *
+ * `inboundEdges`/`outboundEdges` in `graph.ts` answer one hop with a linear
+ * scan, which is right for the scorer's depth-1 counts and wrong as the step of
+ * a walk: calling it per node per step is O(V²E). This module builds one
+ * index per graph instead, and walks it with the same breadth-first walk
+ * `chant search` uses (`graph-walk.ts`).
+ *
+ * Four rules from the spike (docs/design/carve-dependency-blast-radius-spike.md)
+ * hold for every walk here and for the set functions in `cuts.ts` built on it:
+ *
+ *  - Folds contract first. A folded sub-resource is its parent for the walk, so
+ *    `aws_s3_bucket_versioning.assets` is never a dependent of
+ *    `aws_s3_bucket.assets`, and a node reading the child depends on the
+ *    parent.
+ *  - Outputs are terminal and counted apart. An `output.<name>` pseudo-address
+ *    has no inbound edges, so it never extends a path; it is reported in its
+ *    own list.
+ *  - Modules and unresolved `count`/`for_each` hide how much a node holds. A
+ *    `module.x` node is one node whatever it contains, and `count = 20` is one
+ *    node until `--state` resolves it. They are walked through and named, so a
+ *    caller can say `unknown` instead of a number.
+ *  - Cross-stack hops are told apart. On the CDK path an `Fn::ImportValue` edge
+ *    carries `crossStack: true`; what is reachable only through one is listed
+ *    separately.
+ *
+ * Pure, like the rest of the carve analysis. `src/cdk/graph.ts` emits the same
+ * `TfGraph`, so one implementation covers both sources.
+ */
+import { adjacencyOf, walkBreadthFirst } from "../graph-walk.js";
+import { computeFolds } from "./folds.js";
+const indexes = new WeakMap();
+/**
+ * The fold-contracted adjacency index for a graph, built on first use and
+ * cached against the graph object. O(V+E) to build; every walk after that is
+ * O(V+E). A caller that mutates `graph.edges` after the first walk must pass a
+ * new graph object (`applyStateCounts` only touches node instance counts, which
+ * the index reads live).
+ */
+export function carveIndex(graph) {
+    const cached = indexes.get(graph);
+    if (cached)
+        return cached;
+    const nodes = new Map(graph.nodes.map((n) => [n.address, n]));
+    const parentOf = new Map();
+    const { childrenOf } = computeFolds(graph);
+    for (const [parent, children] of childrenOf)
+        for (const child of children)
+            parentOf.set(child, parent);
+    const rep = (address) => parentOf.get(address) ?? address;
+    const contracted = [];
+    for (const e of graph.edges) {
+        const from = rep(e.from);
+        const to = rep(e.to);
+        if (from === to)
+            continue; // a folded child reading its own parent is not an edge of the fold
+        contracted.push({ ...e, from, to, edge: e });
+    }
+    const index = {
+        graph,
+        nodes,
+        rep,
+        membersOf: (address) => [address, ...[...(childrenOf.get(address) ?? [])].sort()],
+        adj: adjacencyOf(contracted),
+        crossStack: graph.edges.some((e) => e.crossStack),
+    };
+    indexes.set(graph, index);
+    return index;
+}
+/** `output.<name>`: a pseudo-address `buildGraph` gives an output block's edges (#1638). */
+export function isOutputAddress(address) {
+    return address.startsWith("output.");
+}
+/**
+ * Whether a node stands for an amount of infrastructure the graph cannot see:
+ * a Terraform `module` block (one node, whatever it holds; state is not read
+ * inside modules), or a `count`/`for_each` block whose instance count no
+ * `.tfstate` resolved. A CDK L3 construct is also `kind: "module"`, but its
+ * members are listed and its address is a construct path, so it hides nothing.
+ */
+export function hidesContents(node) {
+    if (node.kind === "module" && node.address.startsWith("module."))
+        return true;
+    return node.expansion !== undefined && node.instancesFrom !== "state";
+}
+/**
+ * Walk from `seeds` (already contracted) and return every node reached with its
+ * shortest depth, seeds excluded. `sameStack` refuses `crossStack` edges.
+ */
+export function walkFrom(index, seeds, direction, opts = {}) {
+    const start = new Set(seeds);
+    const reached = new Map();
+    const stepsAlong = (edges, far) => (edges ?? []).filter((e) => !(opts.sameStack && e.crossStack)).map((e) => ({ far: e[far], hops: [] }));
+    walkBreadthFirst(start, {
+        steps: (id) => {
+            if (isOutputAddress(id) && !start.has(id))
+                return [];
+            const steps = [];
+            if (direction !== "out")
+                steps.push(...stepsAlong(index.adj.in.get(id), "from"));
+            if (direction !== "in")
+                steps.push(...stepsAlong(index.adj.out.get(id), "to"));
+            return steps;
+        },
+        arrive: ({ id, depth }) => {
+            if (!start.has(id) && !reached.has(id))
+                reached.set(id, depth);
+            return false;
+        },
+    });
+    return reached;
+}
+/**
+ * Everything reachable from `address` (#2325). Direction `in` (the default)
+ * walks dependents: what a change to `address` reaches, its blast radius.
+ * Direction `out` walks dependencies: what `address` needs.
+ *
+ * Throws when `address` is not a node of the graph.
+ */
+export function reach(graph, address, opts = {}) {
+    const index = carveIndex(graph);
+    if (!index.nodes.has(address))
+        throw new Error(`reach: ${address} is not a resource or module in this graph`);
+    const start = index.rep(address);
+    const direction = opts.direction ?? "in";
+    const reached = walkFrom(index, [start], direction);
+    const sorted = [...reached.keys()].sort(cmp);
+    const resources = sorted.filter((a) => !isOutputAddress(a));
+    let crossStack = [];
+    if (index.crossStack) {
+        const inStack = walkFrom(index, [start], direction, { sameStack: true });
+        crossStack = resources.filter((a) => !inStack.has(a));
+    }
+    return {
+        address: start,
+        resources,
+        outputs: sorted.filter(isOutputAddress),
+        depth: Math.max(0, ...reached.values()),
+        crossStack,
+        hidden: resources.filter((a) => hidesContents(index.nodes.get(a))),
+    };
+}
+/** Code-point order, as `buildGraph` sorts: locale-independent. */
+export function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** The instances `addresses` stand for, or `"unknown"` when one of them hides its contents. */
+export function weigh(index, addresses) {
+    let total = 0;
+    for (const address of addresses) {
+        const node = index.nodes.get(address);
+        if (hidesContents(node))
+            return "unknown";
+        total += node.instances;
+    }
+    return total;
+}
+/** The {@link BlastRadius} of `address`: its {@link reach} through dependents, counted. */
+export function blastRadius(graph, address) {
+    const index = carveIndex(graph);
+    const r = reach(graph, address);
+    return {
+        resources: weigh(index, r.resources),
+        outputs: r.outputs.length,
+        depth: r.depth,
+        ...(index.crossStack ? { crossStack: weigh(index, r.crossStack) } : {}),
+        ...(r.hidden.length ? { hiddenBy: r.hidden } : {}),
+    };
+}