@intentius/chant 0.124.51 → 0.124.54

package/dist/graph-refs.js

@@ -84,8 +84,13 @@ export function reconstructEdges(nodes, catalog) {
                 continue;
             for (const value of readPath(node.attrs, rule.path)) {
                 const candidates = index.get(value) ?? [];
+                // `chant graph --live` keeps its first-candidate pick: its values are
+                // logical ids and physical ids, which name one node. An index refuses
+                // the pick instead (reconstructIndexedEdges, #4522).
                 const match = rule.targetKind ? candidates.find((c) => c.kind === rule.targetKind) : candidates[0];
                 if (!match) {
+                    if (rule.optional)
+                        continue;
                     dangling.push({ from: node.id, path: rule.path, value, ...(rule.targetKind ? { targetKind: rule.targetKind } : {}) });
                     continue;
                 }
@@ -154,3 +159,303 @@ export function containmentGroups(pairs) {
         out[parent] = [...byParent.get(parent)].sort();
     return out;
 }
+/** Values a masking or normalization pass wrote: never an identifier. */
+const PLACEHOLDER_VALUES = new Set(["[REDACTED]", "<chant:unresolved>", "<masked>"]);
+/** The attribute a rule reads through, as a declared graph's `viaAttr` names it: `SecurityGroupIds[]` is `SecurityGroupIds`. */
+function topAttr(path) {
+    const first = path.split(".")[0];
+    return first.endsWith("[]") ? first.slice(0, -2) : first;
+}
+/** `<lexicon>:<from kind>:<path>`, the id a derived edge carries. */
+export function refRuleId(lexicon, from, path) {
+    return `${lexicon}:${from}:${path}`;
+}
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Derive edges over indexed nodes (#4522) with each lexicon's catalog, under
+ * the rules ruled on INTENTIUS/behold#1023:
+ *
+ * - the join key is the scoped value: a reference on a node in region R
+ *   matches nodes of the same account in R, and global nodes of the same
+ *   account; a reference on a global node matches global nodes only;
+ * - a rule's target kind is `targetKind`, else `indexedTargetKind`;
+ * - a value that matches more than one node draws no edge and is returned in
+ *   `ambiguous` with every candidate, in place of {@link reconstructEdges}'
+ *   first-candidate pick, so two reads of one account in another node order
+ *   give the same edges;
+ * - tags make edges only through a catalog's typed `tagRefs`.
+ *
+ * A node is matched by its id, physical id, native id, cloud ids, and the
+ * catalog's identity paths. Rules apply to nodes of their own lexicon. Pure.
+ */
+export function reconstructIndexedEdges(nodes, catalogs, scopeOf) {
+    const sorted = [...nodes].sort((a, b) => byString(a.id, b.id));
+    const keyOf = (scope, value) => `${scope.account}\u0000${scope.region ?? ""}\u0000${value}`;
+    const index = new Map();
+    const add = (scope, value, node) => {
+        if (value === undefined || value === "" || PLACEHOLDER_VALUES.has(value))
+            return;
+        const k = keyOf(scope, value);
+        (index.get(k) ?? index.set(k, new Map()).get(k)).set(node.id, node.kind);
+    };
+    const identities = catalogs.flatMap((c) => c.catalog.identities);
+    for (const node of sorted) {
+        const scope = scopeOf(node);
+        add(scope, node.id, node);
+        add(scope, node.physicalId, node);
+        add(scope, node.nativeId, node);
+        for (const c of node.facts?.cloudIds ?? [])
+            add(scope, c.value, node);
+        for (const rule of identities) {
+            if (rule.kind !== node.kind)
+                continue;
+            for (const p of rule.ids)
+                for (const v of readPath(node.attrs, p))
+                    add(scope, v, node);
+        }
+    }
+    const lookup = (holder, value) => {
+        const scope = scopeOf(holder);
+        const out = new Map();
+        const keys = scope.region !== undefined ? [keyOf(scope, value), keyOf({ account: scope.account }, value)] : [keyOf(scope, value)];
+        for (const k of keys)
+            for (const [id, kind] of index.get(k) ?? [])
+                out.set(id, kind);
+        return out;
+    };
+    const edges = new Map();
+    const containment = new Map();
+    // Keyed by holder, rule and value: two rules with one id (the describe-shape
+    // and template-shape rules for the same path) report a reference once.
+    const dangling = new Map();
+    const ambiguous = new Map();
+    const resolve = (holder, value, rule) => {
+        if (PLACEHOLDER_VALUES.has(value))
+            return;
+        const found = lookup(holder, value);
+        let candidates = [...found.entries()].filter(([, kind]) => rule.targetKind === undefined || kind === rule.targetKind).map(([id]) => id);
+        if (candidates.includes(holder.id)) {
+            if (candidates.length === 1)
+                return; // a self-reference (an SG rule to its own group)
+            candidates = candidates.filter((id) => id !== holder.id);
+        }
+        candidates.sort(byString);
+        if (candidates.length === 0) {
+            if (rule.optional)
+                return;
+            dangling.set(`${holder.id}|${rule.id}|${value}`, { from: holder.id, path: rule.path, value, rule: rule.id, ...(rule.targetKind ? { targetKind: rule.targetKind } : {}) });
+            return;
+        }
+        if (candidates.length > 1) {
+            ambiguous.set(`${holder.id}|${rule.id}|${value}`, { from: holder.id, rule: rule.id, path: rule.path, value, candidates });
+            return;
+        }
+        const to = candidates[0];
+        const key = `${holder.id}|${to}|${rule.via}|${rule.relation}`;
+        const prev = edges.get(key);
+        // Two rules can draw one edge (the describe-shape and template-shape rules
+        // read the same attribute); the smaller rule id is kept, so the result
+        // does not depend on catalog order.
+        if (!prev || byString(rule.id, prev.rule) < 0) {
+            edges.set(key, {
+                from: holder.id,
+                to,
+                kind: "ref",
+                viaAttr: rule.via,
+                grain: "property",
+                origin: "derived",
+                rule: rule.id,
+                relation: rule.relation,
+            });
+        }
+        if (rule.relation === "containment") {
+            const ck = `${holder.id}|${to}`;
+            const prevPair = containment.get(ck);
+            if (!prevPair || (rule.label !== undefined && (prevPair.label === undefined || byString(rule.label, prevPair.label) < 0))) {
+                containment.set(ck, { child: holder.id, parent: to, ...(rule.label ? { label: rule.label } : {}) });
+            }
+        }
+    };
+    for (const node of sorted) {
+        for (const { lexicon, catalog } of catalogs) {
+            if (node.lexicon !== lexicon)
+                continue;
+            for (const rule of catalog.refs) {
+                if (rule.from !== node.kind)
+                    continue;
+                const spec = {
+                    id: refRuleId(lexicon, rule.from, rule.path),
+                    path: rule.path,
+                    targetKind: rule.targetKind ?? rule.indexedTargetKind,
+                    relation: rule.relation,
+                    via: rule.viaAttr ?? topAttr(rule.path),
+                    ...(rule.label ? { label: rule.label } : {}),
+                    ...(rule.optional ? { optional: true } : {}),
+                };
+                for (const value of new Set(readPath(node.attrs, rule.path)))
+                    resolve(node, value, spec);
+            }
+            for (const rule of catalog.tagRefs ?? []) {
+                if (rule.from !== undefined && rule.from !== node.kind)
+                    continue;
+                const tags = node.tags ?? {};
+                const spec = {
+                    id: refRuleId(lexicon, rule.from ?? node.kind, `tag:${rule.key}`),
+                    path: `tag:${rule.key}`,
+                    targetKind: rule.targetKind,
+                    relation: "reference",
+                    via: "Tags",
+                    ...(rule.label ? { label: rule.label } : {}),
+                };
+                if (rule.read === "value") {
+                    const v = tags[rule.key];
+                    if (typeof v === "string" && v !== "")
+                        resolve(node, v, spec);
+                }
+                else {
+                    for (const k of Object.keys(tags).sort()) {
+                        if (k.startsWith(rule.key) && k.length > rule.key.length)
+                            resolve(node, k.slice(rule.key.length), spec);
+                    }
+                }
+            }
+        }
+    }
+    const edgeKey = (e) => `${e.from}|${e.to}|${e.viaAttr ?? ""}|${e.relation ?? ""}`;
+    return {
+        edges: [...edges.values()].sort((a, b) => byString(edgeKey(a), edgeKey(b))),
+        containment: [...containment.values()].sort((a, b) => byString(`${a.child}|${a.parent}`, `${b.child}|${b.parent}`)),
+        dangling: [...dangling.values()].sort((a, b) => byString(`${a.from}|${a.rule}|${a.value}`, `${b.from}|${b.rule}|${b.value}`)),
+        ambiguous: [...ambiguous.values()].sort((a, b) => byString(`${a.from}|${a.rule}|${a.value}`, `${b.from}|${b.rule}|${b.value}`)),
+    };
+}
+/** The label every edge of the identity pass carries, as the prefix of its `rule`. */
+export const IDENTITY_MATCH_RULE = "identity-match";
+/** `identity-match:<owner lexicon>:<owner kind>:<identity kind>`. */
+export function identityMatchRuleId(lexicon, kind, identityKind) {
+    return `${IDENTITY_MATCH_RULE}:${lexicon}:${kind}:${identityKind}`;
+}
+/** The default identities of an indexed node: the native id, and any ARN among its cloud ids. */
+export function defaultNodeIdentities(node) {
+    const out = [];
+    if (node.nativeId)
+        out.push({ kind: "native-id", value: node.nativeId });
+    for (const c of node.facts?.cloudIds ?? [])
+        if (c.kind === "arn")
+            out.push({ kind: "arn", value: c.value });
+    return out;
+}
+/** Top-level keys whose values the identity pass never reads: tags make edges only through typed rules (behold#1023 Q5). */
+const IDENTITY_SKIPPED_KEYS = new Set(["Tags", "tags", "TagSet", "labels", "Labels"]);
+/** Short values are names anything can carry (`default`, `app`); whitespace means prose, not an identifier. */
+const MIN_IDENTITY_VALUE = 6;
+const MAX_IDENTITY_VALUE = 2048;
+function identityCandidateValue(v) {
+    return v.length >= MIN_IDENTITY_VALUE && v.length <= MAX_IDENTITY_VALUE && !/\s/.test(v) && !PLACEHOLDER_VALUES.has(v);
+}
+/** Every string leaf under `attrs` with its path (`a.b`, `arr[].c`), skipping tag subtrees. */
+function stringLeaves(attrs) {
+    const out = [];
+    const walk = (v, path) => {
+        if (typeof v === "string") {
+            out.push({ path, value: v });
+        }
+        else if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, `${path}[]`);
+        }
+        else if (v && typeof v === "object") {
+            for (const k of Object.keys(v).sort())
+                walk(v[k], path ? `${path}.${k}` : k);
+        }
+    };
+    for (const k of Object.keys(attrs).sort()) {
+        if (IDENTITY_SKIPPED_KEYS.has(k))
+            continue;
+        walk(attrs[k], k);
+    }
+    return out;
+}
+/**
+ * The identity-match pass (#4523, ruled on INTENTIUS/behold#1023 Q1-Q3): the
+ * second pass over indexed nodes, after {@link reconstructIndexedEdges}. A
+ * string attribute on one node equal to a value that names another node (its
+ * native id, which for aws is the CloudFormation `primaryIdentifier`, or its
+ * ARN) draws an edge labelled `identity-match`:
+ *
+ * - only nodes of a lexicon in `owners` are named; holders are any node;
+ * - the join key is the scoped value, as in the catalog pass: a holder in
+ *   region R reaches nodes of its account in R and global nodes of its
+ *   account; a global holder reaches global nodes only;
+ * - a value naming more than one node draws no edge and is returned in
+ *   `ambiguous` with every candidate;
+ * - tag subtrees are never read, values under {@link MIN_IDENTITY_VALUE}
+ *   characters or with whitespace are skipped, and a value naming the holder
+ *   itself is not a reference;
+ * - a pair the catalog pass already joined (`existing`) gets no second edge.
+ *
+ * Pure, and independent of node order.
+ */
+export function reconstructIdentityEdges(nodes, owners, scopeOf, existing = []) {
+    const sorted = [...nodes].sort((a, b) => byString(a.id, b.id));
+    const ownerBy = new Map(owners.map((o) => [o.lexicon, o]));
+    const keyOf = (scope, value) => `${scope.account}\u0000${scope.region ?? ""}\u0000${value}`;
+    // key -> node id -> the rule that names it
+    const index = new Map();
+    const own = new Map();
+    for (const node of sorted) {
+        const owner = ownerBy.get(node.lexicon);
+        if (!owner || node.unmappedKind)
+            continue;
+        const scope = scopeOf(node);
+        const values = (owner.identities ?? defaultNodeIdentities)(node);
+        own.set(node.id, new Set(values.map((v) => v.value)));
+        for (const { kind, value } of values) {
+            if (!identityCandidateValue(value))
+                continue;
+            const k = keyOf(scope, value);
+            const m = index.get(k) ?? index.set(k, new Map()).get(k);
+            const rule = identityMatchRuleId(owner.lexicon, node.kind, kind);
+            const prev = m.get(node.id);
+            if (prev === undefined || byString(rule, prev) < 0)
+                m.set(node.id, rule);
+        }
+    }
+    const joined = new Set(existing.map((e) => `${e.from}|${e.to}`));
+    const edges = new Map();
+    const ambiguous = new Map();
+    for (const holder of sorted) {
+        const scope = scopeOf(holder);
+        const keys = scope.region !== undefined ? (v) => [keyOf(scope, v), keyOf({ account: scope.account }, v)] : (v) => [keyOf(scope, v)];
+        const mine = own.get(holder.id) ?? new Set([holder.nativeId ?? "", holder.physicalId ?? ""]);
+        for (const { path, value } of stringLeaves(holder.attrs ?? {})) {
+            if (!identityCandidateValue(value) || mine.has(value))
+                continue;
+            const found = new Map();
+            for (const k of keys(value))
+                for (const [id, rule] of index.get(k) ?? [])
+                    if (id !== holder.id)
+                        found.set(id, rule);
+            if (found.size === 0)
+                continue;
+            if (found.size > 1) {
+                ambiguous.set(`${holder.id}|${path}|${value}`, { from: holder.id, path, value, candidates: [...found.keys()].sort(byString) });
+                continue;
+            }
+            const [[to, rule]] = [...found.entries()];
+            if (joined.has(`${holder.id}|${to}`))
+                continue;
+            const via = topAttr(path);
+            const key = `${holder.id}|${to}|${via}`;
+            const prev = edges.get(key);
+            if (!prev || byString(rule, prev.rule) < 0) {
+                edges.set(key, { from: holder.id, to, kind: "ref", viaAttr: via, grain: "property", origin: "derived", rule, relation: "reference" });
+            }
+        }
+    }
+    const edgeKey = (e) => `${e.from}|${e.to}|${e.viaAttr ?? ""}`;
+    return {
+        edges: [...edges.values()].sort((a, b) => byString(edgeKey(a), edgeKey(b))),
+        ambiguous: [...ambiguous.values()].sort((a, b) => byString(`${a.from}|${a.path}|${a.value}`, `${b.from}|${b.path}|${b.value}`)),
+    };
+}

package/dist/graph-schema/fixtures/adopt.json

@@ -0,0 +1,15 @@
+{
+  "adopt": "v1",
+  "index": {
+    "scopeKey": "cloud/aws/000000000000/9bd41033bb42",
+    "version": "20261026T120000Z-e2f92b265a4d.json",
+    "digest": "e2f92b265a4dd604e013b3f55eafe5cf317ea1f5b7c54b4c5187120d0dcfe10d"
+  },
+  "select": [
+    {
+      "node": "aws/000000000000/us-east-1/AWS::S3::Bucket/web-logs",
+      "as": "aws_s3_bucket.web_logs",
+      "type": "aws_s3_bucket"
+    }
+  ]
+}

package/dist/graph-schema/fixtures/choudoufu.engine-graph.json

@@ -0,0 +1,169 @@
+{
+  "version": 1,
+  "meta": {
+    "engineGraph": {
+      "format": 1,
+      "engine": {
+        "name": "choudoufu",
+        "version": "0.33.0"
+      },
+      "scope": {
+        "kind": "estate",
+        "estate": "web"
+      },
+      "observedAt": "2026-10-26T12:00:00Z",
+      "markerScheme": {
+        "ownerKey": "tofu-estate",
+        "addressKey": "tofu-address",
+        "continuationKeys": [
+          "tofu-slot"
+        ],
+        "encoding": {
+          "tags": "escaped",
+          "labels": "escaped"
+        }
+      },
+      "gaps": [
+        {
+          "address": "aws_iam_role.legacy",
+          "reason": "unsupported-kind",
+          "detail": "no lister for this type on this provider"
+        }
+      ]
+    }
+  },
+  "nodes": [
+    {
+      "id": "aws_s3_bucket.logs",
+      "kind": "aws_s3_bucket",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "aws_s3_bucket.logs"
+      },
+      "physicalId": "web-logs",
+      "facts": {
+        "ownership": "bound",
+        "ownedBy": "record",
+        "cloudIds": [
+          {
+            "kind": "import-id",
+            "value": "web-logs"
+          },
+          {
+            "kind": "arn",
+            "value": "arn:aws:s3:::web-logs"
+          }
+        ],
+        "recordVersions": {
+          "kept": true,
+          "versions": [
+            {
+              "id": "3sL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY",
+              "writtenAt": "2026-10-26T11:58:02Z",
+              "current": true,
+              "deleted": false
+            },
+            {
+              "id": "2bE8x0l1BqzDmoPTmD7M7bGqFrsTFTQS",
+              "writtenAt": "2026-10-20T09:14:40Z",
+              "current": false,
+              "deleted": false
+            }
+          ]
+        },
+        "observedAt": "2026-10-26T12:00:00Z"
+      }
+    },
+    {
+      "id": "module.app.aws_eip.pool",
+      "kind": "aws_eip",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "module.app.aws_eip.pool"
+      }
+    },
+    {
+      "id": "module.app.aws_instance.web",
+      "kind": "aws_instance",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "module.app.aws_instance.web"
+      }
+    },
+    {
+      "id": "module.app[0].aws_eip.pool[1]",
+      "kind": "aws_eip",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "module.app[0].aws_eip.pool[1]"
+      },
+      "physicalId": "eipalloc-0abc",
+      "instanceOf": "module.app.aws_eip.pool",
+      "instanceKey": "[1]",
+      "instanceScope": "module.app[0]",
+      "facts": {
+        "ownership": "bound",
+        "ownedBy": "marker",
+        "markers": {
+          "owner": "web",
+          "address": "module.app:0.aws_eip.pool:1",
+          "encoding": "escaped",
+          "source": "live"
+        },
+        "cloudIds": [
+          {
+            "kind": "import-id",
+            "value": "eipalloc-0abc"
+          }
+        ],
+        "observedAt": "2026-10-26T12:00:00Z"
+      }
+    },
+    {
+      "id": "aws_sqs_queue.jobs",
+      "kind": "aws_sqs_queue",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "aws_sqs_queue.jobs"
+      },
+      "facts": {
+        "ownership": "foreign",
+        "markers": {
+          "owner": "billing",
+          "encoding": "escaped",
+          "source": "live"
+        },
+        "observedAt": "2026-10-26T12:00:00Z"
+      }
+    },
+    {
+      "id": "aws_sns_topic.alerts",
+      "kind": "aws_sns_topic",
+      "lexicon": "terraform",
+      "attrs": {
+        "address": "aws_sns_topic.alerts"
+      },
+      "facts": {
+        "ownership": "pending",
+        "observedAt": "2026-10-26T12:00:00Z"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "from": "module.app[0].aws_eip.pool[1]",
+      "to": "module.app.aws_instance.web",
+      "kind": "ref",
+      "viaAttr": "dependencies",
+      "grain": "block"
+    },
+    {
+      "from": "module.app.aws_instance.web",
+      "to": "aws_s3_bucket.logs",
+      "kind": "ref",
+      "viaAttr": "dependencies",
+      "grain": "block"
+    }
+  ],
+  "groups": {}
+}

package/dist/graph-schema/fixtures/index.json

@@ -0,0 +1,68 @@
+{
+  "index": "v1",
+  "stamp": {
+    "source": {
+      "kind": "cloud",
+      "name": "behold-lister",
+      "version": "0.0.0"
+    },
+    "scope": {
+      "kind": "cloud",
+      "substrate": "aws",
+      "scopeId": "000000000000",
+      "locations": [
+        "us-east-1"
+      ],
+      "types": [
+        "AWS::S3::Bucket",
+        "AWS::SQS::Queue"
+      ]
+    },
+    "scopeKey": "cloud/aws/000000000000/9bd41033bb42",
+    "observedAt": "2026-10-26T12:00:00Z",
+    "completedAt": "2026-10-26T12:00:04Z",
+    "digest": "e2f92b265a4dd604e013b3f55eafe5cf317ea1f5b7c54b4c5187120d0dcfe10d"
+  },
+  "coverage": [
+    {
+      "listedType": "AWS::S3::Bucket",
+      "location": "us-east-1",
+      "verdict": "listed"
+    },
+    {
+      "listedType": "AWS::SQS::Queue",
+      "location": "us-east-1",
+      "verdict": "read-failed",
+      "detail": "ListResources returned UnsupportedOperation"
+    }
+  ],
+  "graph": {
+    "version": 1,
+    "nodes": [
+      {
+        "id": "aws/000000000000/us-east-1/AWS::S3::Bucket/web-logs",
+        "kind": "AWS::S3::Bucket",
+        "lexicon": "aws",
+        "attrs": {
+          "BucketName": "web-logs"
+        },
+        "physicalId": "web-logs"
+      }
+    ],
+    "edges": [],
+    "groups": {
+      "byLexicon": {
+        "aws": [
+          "aws/000000000000/us-east-1/AWS::S3::Bucket/web-logs"
+        ]
+      }
+    }
+  },
+  "notes": [
+    {
+      "kind": "no-catalog",
+      "message": "no reference catalog for AWS::SQS::Queue",
+      "listedType": "AWS::SQS::Queue"
+    }
+  ]
+}