@intentius/chant 0.124.51 → 0.124.54

package/src/__fixtures__/drift-record/live-diff.json

@@ -0,0 +1,125 @@
+{
+  "missing": [
+    "cacheTopic"
+  ],
+  "orphan": [],
+  "runtimeChildren": [],
+  "disappeared": [
+    "strayTopic"
+  ],
+  "newlyObserved": [
+    "alertsTopic",
+    "quietSg",
+    "webSg"
+  ],
+  "driftedSinceSnapshot": [
+    {
+      "name": "appRole",
+      "type": "AWS::IAM::Role",
+      "changes": [
+        {
+          "path": "status",
+          "oldValue": "CREATE_COMPLETE",
+          "newValue": "EXTERNAL"
+        },
+        {
+          "path": "lastUpdated",
+          "oldValue": "2026-10-26T06:31:45.132045382Z"
+        },
+        {
+          "path": "attributes.region",
+          "oldValue": "us-east-1"
+        },
+        {
+          "path": "attributes.Arn",
+          "newValue": "arn:aws:iam::000000000000:role/ry-app-role"
+        },
+        {
+          "path": "attributes.RoleName",
+          "newValue": "ry-app-role"
+        },
+        {
+          "path": "attributes.Path",
+          "newValue": "/"
+        }
+      ]
+    },
+    {
+      "name": "dataBucket",
+      "type": "AWS::S3::Bucket",
+      "changes": [
+        {
+          "path": "status",
+          "oldValue": "CREATE_COMPLETE",
+          "newValue": "UPDATE_COMPLETE"
+        },
+        {
+          "path": "lastUpdated",
+          "oldValue": "2026-10-26T06:31:45.132492549Z",
+          "newValue": "2026-10-26T06:32:00.156983792Z"
+        }
+      ]
+    },
+    {
+      "name": "dataBucketPolicy",
+      "type": "AWS::S3::BucketPolicy",
+      "changes": [
+        {
+          "path": "status",
+          "oldValue": "CREATE_COMPLETE",
+          "newValue": "UPDATE_COMPLETE"
+        },
+        {
+          "path": "physicalId",
+          "oldValue": "bucket-policy-4516bdd6",
+          "newValue": "bucket-policy-993b2ead"
+        },
+        {
+          "path": "lastUpdated",
+          "oldValue": "2026-10-26T06:31:45.133049215Z",
+          "newValue": "2026-10-26T06:32:00.157473792Z"
+        }
+      ]
+    },
+    {
+      "name": "eventsTopic",
+      "type": "AWS::SNS::Topic",
+      "changes": [
+        {
+          "path": "status",
+          "oldValue": "CREATE_COMPLETE",
+          "newValue": "UPDATE_COMPLETE"
+        },
+        {
+          "path": "lastUpdated",
+          "oldValue": "2026-10-26T06:31:45.132664465Z",
+          "newValue": "2026-10-26T06:32:00.157185292Z"
+        }
+      ]
+    },
+    {
+      "name": "taskQueue",
+      "type": "AWS::SQS::Queue",
+      "changes": [
+        {
+          "path": "status",
+          "oldValue": "CREATE_COMPLETE",
+          "newValue": "UPDATE_COMPLETE"
+        },
+        {
+          "path": "lastUpdated",
+          "oldValue": "2026-10-26T06:31:45.132903549Z",
+          "newValue": "2026-10-26T06:32:00.157365833Z"
+        }
+      ]
+    }
+  ],
+  "unchanged": [],
+  "unobserved": [],
+  "queried": {
+    "appRole": "cloudcontrol:GetResource:AWS::IAM::Role:ry-app-role"
+  },
+  "definitions": {
+    "cacheTopic": "cfbb459653feffdc748e920ae9f0eb9a0c78d8efcd82cc21b74371be533e2e66"
+  }
+}

package/src/audit/discover.e2e.test.ts

@@ -137,6 +137,20 @@ describe("discoverByDetection (unified, detectTemplate-driven)", () => {
       expect(found.find((i) => i.path === "live/app")!.content).toContain("# file: terragrunt.hcl");
     });
 
+    test(".tf.json, .tofu and .tofu.json files join the terraform bundle beside .tf (chant#4457)", () => {
+      const files = [
+        { path: "app/main.tf", content: 'resource "x" "a" {}\n' },
+        { path: "app/extra.tf.json", content: '{"resource": {"x": {"b": {}}}}\n' },
+        { path: "app/tofu.tofu", content: 'resource "x" "c" {}\n' },
+        { path: "app/tofu.tofu.json", content: '{"resource": {"x": {"d": {}}}}\n' },
+      ];
+      const found = classifyFiles(files, [terraform]);
+      expect(targets(found)).toEqual(["terraform:app"]);
+      expect(Object.keys(found[0]!.files!).sort()).toEqual(["extra.tf.json", "main.tf", "tofu.tofu", "tofu.tofu.json"]);
+      expect(hintLexiconForFile("app/extra.tf.json", "{}")).toBe("terraform");
+      expect(hintLexiconForFile("app/tofu.tofu", "")).toBe("terraform");
+    });
+
     test("without the terraform plugin, .tf files are classified into nothing (skipped, same as an unloaded helm)", () => {
       const found = discoverByDetection(fixture("audit-terraform"), []);
       expect(found).toEqual([]);

package/src/audit/discover.ts

@@ -153,7 +153,9 @@ function isDockerfileName(name: string): boolean {
 function isTerraformFileName(name: string): boolean {
   // `terragrunt.hcl` and `root.hcl` ride in the terraform bundle (#3417): the
   // terraform lexicon reads them into Terragrunt entities, apart from modules.
-  return /\.tf$/i.test(name) || name === "terragrunt.hcl" || name === "root.hcl";
+  // `.tf.json`, `.tofu` and `.tofu.json` are configuration too (chant#4457);
+  // which of them a root reads is the lexicon's call, by its binary.
+  return /\.(tf|tofu)(\.json)?$/i.test(name) || name === "terragrunt.hcl" || name === "root.hcl";
 }
 
 /**

package/src/behaviour.ts

@@ -411,7 +411,7 @@ export interface PredictedBehaviour {
  * at an address that is answering perfectly well.
  */
 export type BehaviourUnpredictedReason =
-  | Exclude<UnobservedReason, "no-credentials">
+  | Exclude<UnobservedReason, "no-credentials" | "not-reached">
   | "no-engine"
   | "engine-unreachable"
   | "engine-out-of-credit"

package/src/capabilities/templates.json

@@ -0,0 +1,145 @@
+{
+  "version": 1,
+  "templates": [
+    {
+      "id": "dependents",
+      "title": "What depends on it",
+      "question": "what reads this resource, directly or through others, in its own project",
+      "sources": ["chant"],
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "source",
+      "query": { "kind": "path", "text": "->*{{node}}" }
+    },
+    {
+      "id": "dependencies",
+      "title": "What it depends on",
+      "question": "what this resource reads, directly or through others, in its own project",
+      "sources": ["chant"],
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "source",
+      "query": { "kind": "path", "text": "<-*{{node}}" }
+    },
+    {
+      "id": "paths-to-kind",
+      "title": "Paths from it to a kind",
+      "question": "does this resource reach anything of a given kind, and by which path",
+      "sources": ["chant"],
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." },
+        { "name": "kind", "kind": "term", "description": "A kind or type, as kind: takes it (aws_internet_gateway, EC2::InternetGateway)." }
+      ],
+      "reads": "source",
+      "query": { "kind": "path", "text": "{{node}} ->*kind:{{kind}}" }
+    },
+    {
+      "id": "capability",
+      "title": "Whether a capability holds for it",
+      "question": "does a capability from the catalog hold for this resource",
+      "sources": ["chant"],
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." },
+        { "name": "capability", "kind": "term", "description": "A capability from chant's catalog, with its arguments: internet-reachable(22)." }
+      ],
+      "reads": "source",
+      "query": { "kind": "path", "text": "{{node}} cap:{{capability}}" }
+    },
+    {
+      "id": "drift",
+      "title": "Drift",
+      "question": "has this resource drifted from its declaration in an environment",
+      "sources": ["chant"],
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." },
+        { "name": "env", "kind": "scope", "description": "The environment to read live." }
+      ],
+      "reads": "live",
+      "query": { "kind": "path", "text": "{{node}}" },
+      "note": "Draws the node in the environment's live read, coloured by drift."
+    },
+    {
+      "id": "dependents-all",
+      "title": "What depends on it, across every source",
+      "question": "what reads this resource, in any project, root or stack loaded into the session",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "session",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (o:Resource)-[:REF*1..6]->(r:Resource {key: $key}) RETURN DISTINCT o.key AS key, o.kind AS kind, o.scopeKey AS scope"
+      }
+    },
+    {
+      "id": "dependencies-all",
+      "title": "What it depends on, across every source",
+      "question": "what this resource reads, in any project, root or stack loaded into the session",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "session",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (r:Resource {key: $key})-[:REF*1..6]->(o:Resource) RETURN DISTINCT o.key AS key, o.kind AS kind, o.scopeKey AS scope"
+      }
+    },
+    {
+      "id": "ownership",
+      "title": "Ownership",
+      "question": "who owns this cloud ID, and which other sources know the same object",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "session",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (r:Resource {key: $key}) OPTIONAL MATCH (r)-[:KNOWN_AS]->(:CloudId)<-[:KNOWN_AS]-(o:Resource) WHERE o.key <> r.key RETURN r.key AS key, r.ownership AS ownership, r.engineOwnership AS engineOwnership, r.facts AS facts, r.observedAt AS observedAt, collect(DISTINCT o.key) AS sameObject"
+      },
+      "note": "ownership is chant's marker verdict, owned or foreign. engineOwnership is an engine's, bound, unowned, pending or foreign. Absent is unknown, never guessed. A cloud listing reads markers only."
+    },
+    {
+      "id": "same-object",
+      "title": "The same object in other sources",
+      "question": "where else is the object behind this resource declared or recorded",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "session",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (r:Resource {key: $key})-[:KNOWN_AS]->(c:CloudId)<-[:KNOWN_AS]-(o:Resource) WHERE o.scopeKey <> r.scopeKey RETURN DISTINCT o.key AS key, o.scopeKey AS scope, c.value AS cloudId, c.kind AS cloudIdKind"
+      }
+    },
+    {
+      "id": "readers",
+      "title": "Who reads it from another estate or root",
+      "question": "which other estate or root reads this resource",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "session",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (o:Resource)-[e:REF]->(r:Resource {key: $key}) WHERE o.scopeKey <> r.scopeKey RETURN o.key AS key, o.scopeKey AS scope, e.viaAttr AS via, e.origin AS origin, e.rule AS rule UNION MATCH (r:Resource {key: $key})-[:KNOWN_AS]->(:CloudId)<-[:KNOWN_AS]-(t:Resource)<-[e:REF]-(o:Resource) WHERE o.scopeKey <> r.scopeKey RETURN o.key AS key, o.scopeKey AS scope, e.viaAttr AS via, e.origin AS origin, e.rule AS rule"
+      },
+      "note": "A derived edge (origin derived, rule identity:<kind>) is an identity match, not a declared reference."
+    },
+    {
+      "id": "history",
+      "title": "History",
+      "question": "how has this resource's record changed over time",
+      "inputs": [
+        { "name": "node", "kind": "resource", "description": "The resource: a name, an IR id, a block address or a cloud ID." }
+      ],
+      "reads": "snapshots",
+      "query": {
+        "kind": "cypher",
+        "text": "MATCH (r:Resource {key: $key}) RETURN r.key AS key, r.facts AS facts, r.version AS version, r.observedAt AS observedAt"
+      },
+      "note": "The record's versions come from facts.recordVersions, when the engine ran with -history or --versions. Snapshot history (chant#4519's store) is not loaded into the session yet."
+    }
+  ]
+}

package/src/capabilities/templates.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Investigation templates (#4531): the catalog's second kind of entry. Every
+ * shipped template holds to the entry kind, every path template parses as a
+ * chant search query and runs against a fixture graph, and the data file is
+ * exported for behold and choudoufu.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { GraphIR } from "../graph-ir";
+import { __searchInternals, resolveKindTerms } from "../cli/handlers/search";
+import { NEXT_RELEASE } from "../release-floors";
+import {
+  CAPABILITY_TEMPLATES_FLOOR,
+  TemplateCatalogError,
+  expandTemplate,
+  investigationTemplates,
+  parseTemplates,
+  type TemplateEntry,
+} from "./templates";
+import data from "./templates.json" with { type: "json" };
+
+const { parseQuery, matchTerm } = __searchInternals;
+
+/**
+ * A CloudFormation project's graph: an instance in a subnet in a VPC, and a
+ * security group nothing uses. Edges point from the consumer to what it
+ * references. The ids share no substring, since a bare word matches by
+ * substring.
+ */
+const node = (id: string, kind: string) => ({ id, kind, lexicon: "aws", attrs: {} });
+const fixture = (): GraphIR =>
+  ({
+    nodes: [
+      node("AppVpc", "AWS::EC2::VPC"),
+      node("AppSubnet", "AWS::EC2::Subnet"),
+      node("WebHost", "AWS::EC2::Instance"),
+      node("SpareGroup", "AWS::EC2::SecurityGroup"),
+    ],
+    edges: [
+      { from: "AppSubnet", to: "AppVpc", kind: "ref", viaAttr: "VpcId", toAttr: "id" },
+      { from: "WebHost", to: "AppSubnet", kind: "ref", viaAttr: "SubnetId", toAttr: "id" },
+    ],
+    groups: {},
+  }) as unknown as GraphIR;
+
+/** Run a chant search query over a graph as runSearch matches it, returning the matched ids. */
+function search(ir: GraphIR, query: string): string[] {
+  const terms = parseQuery(query);
+  resolveKindTerms(terms, ir.nodes);
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  return ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId))).map((n) => n.id).sort();
+}
+
+/**
+ * Each path template's run against the fixture: the inputs, and the ids the
+ * query must match. A path template missing here fails the test below.
+ */
+const PATH_CASES: Record<string, { inputs: Record<string, string>; matches: string[] }[]> = {
+  dependents: [
+    { inputs: { node: "AppVpc" }, matches: ["AppSubnet", "WebHost"] },
+    { inputs: { node: "WebHost" }, matches: [] },
+  ],
+  dependencies: [
+    { inputs: { node: "WebHost" }, matches: ["AppSubnet", "AppVpc"] },
+    { inputs: { node: "AppVpc" }, matches: [] },
+  ],
+  "paths-to-kind": [
+    { inputs: { node: "WebHost", kind: "AWS::EC2::VPC" }, matches: ["WebHost"] },
+    { inputs: { node: "SpareGroup", kind: "AWS::EC2::VPC" }, matches: [] },
+  ],
+  capability: [
+    { inputs: { node: "SpareGroup", capability: "attached-to-nothing" }, matches: ["SpareGroup"] },
+    { inputs: { node: "WebHost", capability: "attached-to-nothing" }, matches: [] },
+  ],
+  drift: [{ inputs: { node: "WebHost", env: "prod" }, matches: ["WebHost"] }],
+};
+
+/** The set behold#1027 stubbed in behold's src/graph-db/templates.ts. */
+const BEHOLD_STUB = [
+  "dependents",
+  "dependencies",
+  "paths-to-kind",
+  "capability",
+  "drift",
+  "dependents-all",
+  "dependencies-all",
+  "ownership",
+  "same-object",
+  "readers",
+  "history",
+];
+
+describe("the shipped templates", () => {
+  it("parse, and are behold's stubbed set", () => {
+    const templates = investigationTemplates();
+    expect(templates.map((t) => t.id)).toEqual(BEHOLD_STUB);
+    for (const t of templates) {
+      expect(t.inputs[0], t.id).toMatchObject({ name: "node", kind: "resource" });
+      expect(t.question.length, t.id).toBeGreaterThan(0);
+    }
+  });
+
+  it("say which language each expands to: the in-project questions are path patterns, the cross-source ones Cypher", () => {
+    const byKind = (k: string) => investigationTemplates().filter((t) => t.query.kind === k).map((t) => t.id);
+    expect(byKind("path")).toEqual(["dependents", "dependencies", "paths-to-kind", "capability", "drift"]);
+    expect(byKind("cypher")).toEqual(["dependents-all", "dependencies-all", "ownership", "same-object", "readers", "history"]);
+  });
+
+  it("every path template parses as a chant search query and runs against the fixture", () => {
+    const paths = investigationTemplates().filter((t) => t.query.kind === "path");
+    expect(Object.keys(PATH_CASES).sort()).toEqual(paths.map((t) => t.id).sort());
+    for (const t of paths) {
+      for (const c of PATH_CASES[t.id]!) {
+        const expanded = expandTemplate(t, c.inputs);
+        expect(() => parseQuery(expanded.text), `${t.id}: ${expanded.text}`).not.toThrow();
+        expect(search(fixture(), expanded.text), `${t.id}: ${expanded.text}`).toEqual(c.matches);
+      }
+    }
+  });
+
+  it("a scope input says where the query is read and stays out of its text", () => {
+    const drift = investigationTemplates().find((t) => t.id === "drift")!;
+    expect(expandTemplate(drift, { node: "WebHost", env: "prod" })).toEqual({
+      template: "drift",
+      kind: "path",
+      reads: "live",
+      text: "WebHost",
+      scope: { env: "prod" },
+    });
+  });
+
+  it("a Cypher template binds the node as $key and splices nothing into its text", () => {
+    for (const t of investigationTemplates().filter((x) => x.query.kind === "cypher")) {
+      const e = expandTemplate(t, { node: "chant:app/AppVpc" });
+      expect(e.text, t.id).toBe(t.query.text);
+      expect(e.params, t.id).toEqual({ key: "chant:app/AppVpc" });
+      expect(e.text, t.id).not.toContain("chant:app/AppVpc");
+    }
+  });
+
+  it("ownership returns chant's verdict and the engine's as two columns, as behold's stub does (behold#906 Q4, behold#1031)", () => {
+    const t = investigationTemplates().find((x) => x.id === "ownership")!;
+    expect(t.query.text).toContain("r.ownership AS ownership");
+    expect(t.query.text).toContain("r.engineOwnership AS engineOwnership");
+    expect(t.query.text).not.toMatch(/coalesce\(/i);
+  });
+
+  it("refuses a value that would add a second search term, a missing input and an unknown one", () => {
+    const t = investigationTemplates().find((x) => x.id === "paths-to-kind")!;
+    expect(() => expandTemplate(t, { node: "WebHost", kind: "aws_vpc cap:blast" })).toThrow(/not one search term/);
+    expect(() => expandTemplate(t, { node: "WebHost" })).toThrow(/needs kind/);
+    expect(() => expandTemplate(t, { node: "WebHost", kind: "aws_vpc", env: "prod" })).toThrow(/takes no input env/);
+  });
+});
+
+describe("the entry kind", () => {
+  const valid = (): TemplateEntry => ({
+    id: "t",
+    title: "T",
+    question: "what is it",
+    inputs: [{ name: "node", kind: "resource", description: "the resource" }],
+    reads: "source",
+    query: { kind: "path", text: "->*{{node}}" },
+  });
+  const parse = (...templates: unknown[]) => parseTemplates({ version: 1, templates });
+  const refuses = (patch: Record<string, unknown>, message: RegExp) =>
+    expect(() => parse({ ...valid(), ...patch })).toThrow(message);
+
+  it("reads a valid entry", () => {
+    expect(parse(valid())).toEqual([valid()]);
+  });
+
+  it("refuses an entry that does not hold to it, naming the template", () => {
+    expect(() => parseTemplates({ version: 2, templates: [] })).toThrow(TemplateCatalogError);
+    expect(() => parse(valid(), valid())).toThrow(/template t: is defined twice/);
+    refuses({ id: "Bad Id" }, /needs an id/);
+    refuses({ question: "" }, /needs the question/);
+    refuses({ reads: "everything" }, /reads is one of/);
+    refuses({ query: { kind: "sql", text: "SELECT 1" } }, /query is/);
+    refuses({ inputs: [] }, /one resource input, first/);
+    refuses({ inputs: [{ name: "env", kind: "scope", description: "e" }, ...valid().inputs] }, /one resource input, first/);
+    refuses({ inputs: [...valid().inputs, { name: "kind", kind: "term", description: "k" }] }, /never uses kind/);
+    refuses({ query: { kind: "path", text: "->*{{other}}" } }, /names no input/);
+    refuses({ query: { kind: "path", text: "->*$key" } }, /not \$parameters/);
+  });
+
+  it("holds a Cypher query to reading, with the node as $key and its inputs as parameters", () => {
+    const cypher = (text: string) => ({ query: { kind: "cypher", text } });
+    expect(() => parse({ ...valid(), ...cypher("MATCH (r:Resource {key: $key}) RETURN r") })).not.toThrow();
+    refuses(cypher("MATCH (r:Resource {key: '{{node}}'}) RETURN r"), /never spliced/);
+    refuses(cypher("MATCH (r:Resource {key: $key}) DETACH DELETE r"), /only reads/);
+    refuses(cypher("RETURN 1"), /reading clause/);
+    refuses(cypher("MATCH (r:Resource {key: $key} RETURN r"), /do not balance/);
+    refuses(cypher("MATCH (r:Resource {key: $id}) RETURN r"), /binds the resource as \$key/);
+    refuses(cypher("MATCH (r:Resource {key: $key, kind: $kind}) RETURN r"), /\$kind names no input/);
+  });
+});
+
+describe("the export", () => {
+  it("ships templates.json as @intentius/chant/capabilities/templates.json, the data the catalog reads", () => {
+    const pkg = JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "package.json"), "utf-8")) as { exports: Record<string, unknown> };
+    expect(pkg.exports["./capabilities/templates.json"]).toBe("./src/capabilities/templates.json");
+    const onDisk = JSON.parse(readFileSync(join(import.meta.dirname, "templates.json"), "utf-8")) as unknown;
+    expect(onDisk).toEqual(data);
+    expect(parseTemplates(onDisk)).toEqual(investigationTemplates());
+  });
+
+  it("carries its floor at the next release", () => {
+    expect(CAPABILITY_TEMPLATES_FLOOR).toBe(NEXT_RELEASE);
+  });
+});