@intentius/chant 0.124.51 → 0.124.54

package/src/lifecycle/__fixtures__/index-diff/20261026T130000Z-bbbbbbbbbbbb.json

@@ -0,0 +1,127 @@
+{
+  "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::IAM::Role",
+        "AWS::S3::Bucket",
+        "AWS::SQS::Queue"
+      ]
+    },
+    "scopeKey": "cloud/aws/000000000000/5c1f0e2a9b7d",
+    "observedAt": "2026-10-26T13:00:00Z",
+    "completedAt": "2026-10-26T13:00:04Z",
+    "digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+  },
+  "coverage": [
+    {
+      "listedType": "AWS::IAM::Role",
+      "location": "us-east-1",
+      "verdict": "listed"
+    },
+    {
+      "listedType": "AWS::S3::Bucket",
+      "location": "us-east-1",
+      "verdict": "listed"
+    },
+    {
+      "listedType": "AWS::SQS::Queue",
+      "location": "us-east-1",
+      "verdict": "read-failed",
+      "detail": "ListResources returned ThrottlingException"
+    }
+  ],
+  "graph": {
+    "version": 1,
+    "nodes": [
+      {
+        "id": "aws/000000000000/us-east-1/AWS::IAM::Role/app-role",
+        "kind": "AWS::IAM::Role",
+        "lexicon": "aws",
+        "attrs": {
+          "RoleName": "app-role",
+          "Path": "/"
+        },
+        "physicalId": "app-role",
+        "listedType": "AWS::IAM::Role",
+        "location": "us-east-1",
+        "nativeId": "app-role",
+        "facts": {
+          "observedAt": "2026-10-26T13:00:00Z"
+        }
+      },
+      {
+        "id": "aws/000000000000/us-east-1/AWS::S3::Bucket/new-bucket",
+        "kind": "AWS::S3::Bucket",
+        "lexicon": "aws",
+        "attrs": {
+          "BucketName": "new-bucket"
+        },
+        "physicalId": "new-bucket",
+        "listedType": "AWS::S3::Bucket",
+        "location": "us-east-1",
+        "nativeId": "new-bucket",
+        "facts": {
+          "observedAt": "2026-10-26T13:00:00Z"
+        }
+      },
+      {
+        "id": "aws/000000000000/us-east-1/AWS::S3::Bucket/web-logs",
+        "kind": "AWS::S3::Bucket",
+        "lexicon": "aws",
+        "attrs": {
+          "BucketName": "web-logs",
+          "VersioningConfiguration": {
+            "Status": "Enabled"
+          },
+          "Tags": [
+            {
+              "Key": "env",
+              "Value": "dev"
+            }
+          ]
+        },
+        "physicalId": "web-logs",
+        "listedType": "AWS::S3::Bucket",
+        "location": "us-east-1",
+        "nativeId": "web-logs",
+        "facts": {
+          "observedAt": "2026-10-26T13:00:00Z"
+        },
+        "tags": {
+          "env": "dev"
+        }
+      }
+    ],
+    "edges": [
+      {
+        "from": "aws/000000000000/us-east-1/AWS::IAM::Role/app-role",
+        "to": "aws/000000000000/us-east-1/AWS::S3::Bucket/web-logs",
+        "kind": "ref",
+        "viaAttr": "Policies",
+        "origin": "derived",
+        "rule": "aws:AWS::IAM::Role:Policies"
+      },
+      {
+        "from": "aws/000000000000/us-east-1/AWS::IAM::Role/app-role",
+        "to": "aws/000000000000/us-east-1/AWS::S3::Bucket/new-bucket",
+        "kind": "ref",
+        "viaAttr": "Policies",
+        "origin": "derived",
+        "rule": "aws:AWS::IAM::Role:Policies"
+      }
+    ],
+    "groups": {}
+  }
+}

package/src/lifecycle/adoption-file.test.ts

@@ -0,0 +1,100 @@
+/**
+ * #4536: the adoption file (`adopt: v1`). Refusals on its own and against
+ * the index version it is read with, and the file an index import report
+ * gives. Pure; nothing reaches a cloud.
+ */
+import { describe, expect, test } from "vitest";
+import {
+  adoptionFileFromImportReport,
+  adoptionFileProblems,
+  adoptionFileProblemsAgainst,
+  validateAdoptionFile,
+  type AdoptionFile,
+} from "./adoption-file";
+import { indexDocumentDigest, indexScopeKey, indexVersionName, type CloudIndexScope, type IndexDocument } from "./index-document";
+import type { IndexImportReport } from "./index-import";
+
+const SCOPE: CloudIndexScope = { kind: "cloud", substrate: "aws", scopeId: "111", locations: ["us-east-1"], types: "*" };
+const BUCKET = "aws/111/us-east-1/AWS::S3::Bucket/logs";
+const QUEUE = "aws/111/us-east-1/AWS::SQS::Queue/jobs";
+const graph = {
+  version: 1 as const,
+  nodes: [
+    { id: BUCKET, kind: "AWS::S3::Bucket", lexicon: "aws", attrs: {}, listedType: "AWS::S3::Bucket", location: "us-east-1", nativeId: "logs" },
+    { id: QUEUE, kind: "AWS::SQS::Queue", lexicon: "aws", attrs: {}, listedType: "AWS::SQS::Queue", location: "us-east-1", nativeId: "jobs" },
+  ],
+  edges: [],
+  groups: {},
+};
+const DOC: IndexDocument = {
+  index: "v1",
+  stamp: { source: { kind: "cloud", name: "behold-lister" }, scope: SCOPE, scopeKey: indexScopeKey(SCOPE), observedAt: "2026-10-26T09:00:00Z", digest: indexDocumentDigest({ graph, coverage: [] }) },
+  coverage: [],
+  graph,
+};
+const file = (over: Partial<AdoptionFile> = {}): AdoptionFile => ({
+  adopt: "v1",
+  index: { scopeKey: DOC.stamp.scopeKey, version: indexVersionName(DOC.stamp.observedAt, DOC.stamp.digest), digest: DOC.stamp.digest },
+  select: [{ node: BUCKET, as: "aws_s3_bucket.logs", type: "aws_s3_bucket" }],
+  ...over,
+});
+
+describe("adoption file (#4536)", () => {
+  test("a file naming the version it is read with is accepted, with or without a sha256: prefix", () => {
+    expect(adoptionFileProblemsAgainst(file(), DOC)).toEqual([]);
+    const prefixed = file();
+    prefixed.index = { ...prefixed.index, digest: `sha256:${prefixed.index.digest}` };
+    expect(adoptionFileProblemsAgainst(prefixed, DOC)).toEqual([]);
+  });
+
+  test("a digest, version or scope key that is not the version's is refused", () => {
+    const other = "0".repeat(64);
+    const wrongDigest = file();
+    wrongDigest.index = { ...wrongDigest.index, digest: other, version: indexVersionName(DOC.stamp.observedAt, other) };
+    expect(adoptionFileProblemsAgainst(wrongDigest, DOC).join("\n")).toMatch(/digest does not match/);
+    const wrongScope = file();
+    wrongScope.index = { ...wrongScope.index, scopeKey: "cloud/aws/222/abcdefabcdef" };
+    expect(adoptionFileProblemsAgainst(wrongScope, DOC).join("\n")).toMatch(/scopeKey/);
+    const wrongVersion = file();
+    wrongVersion.index = { ...wrongVersion.index, version: indexVersionName("2026-10-25T09:00:00Z", DOC.stamp.digest) };
+    expect(adoptionFileProblemsAgainst(wrongVersion, DOC).join("\n")).toMatch(/is not the version read/);
+  });
+
+  test("a version name that does not carry the digest is refused on its own", () => {
+    const f = file();
+    f.index = { ...f.index, version: "20261026T090000Z-000000000000.json" };
+    expect(adoptionFileProblems(f).join("\n")).toMatch(/does not name the digest/);
+  });
+
+  test("a node the version does not hold is refused by name", () => {
+    const f = file({ select: [{ node: "aws/111/us-east-1/AWS::S3::Bucket/gone", as: "aws_s3_bucket.gone" }] });
+    expect(() => validateAdoptionFile(f, DOC)).toThrow(/AWS::S3::Bucket\/gone is not in index version/);
+  });
+
+  test("no select, a node selected twice and two nodes at one address are refused", () => {
+    expect(adoptionFileProblems(file({ select: [] }))).toContain("select names no node");
+    const twice = adoptionFileProblems(file({ select: [{ node: BUCKET, as: "a" }, { node: BUCKET, as: "b" }] }));
+    expect(twice.join("\n")).toMatch(/selected twice/);
+    const oneAddress = adoptionFileProblems(file({ select: [{ node: BUCKET, as: "a" }, { node: QUEUE, as: "a" }] }));
+    expect(oneAddress.join("\n")).toMatch(/two nodes are adopted as a/);
+  });
+
+  test("an import report gives a file with each imported resource as its logical id; declared and unsupported ones are left out", () => {
+    const report: IndexImportReport = {
+      report: "chant-index-import/v1",
+      index: [{ scopeKey: DOC.stamp.scopeKey, observedAt: DOC.stamp.observedAt, digest: DOC.stamp.digest, source: "behold-lister" }],
+      selection: { all: true },
+      resources: [
+        { node: QUEUE, identity: { substrate: "aws", scopeId: "111", listedType: "AWS::SQS::Queue", location: "us-east-1", nativeId: "jobs" }, cloudIds: [], lexicon: "aws", kind: "AWS::SQS::Queue", status: "imported", logicalId: "QueueJobs", group: "" },
+        { node: BUCKET, identity: { substrate: "aws", scopeId: "111", listedType: "AWS::S3::Bucket", location: "us-east-1", nativeId: "logs" }, cloudIds: [], lexicon: "aws", kind: "AWS::S3::Bucket", status: "declared", entity: "logs" },
+      ],
+      parameters: [],
+      groups: [],
+    };
+    const f = adoptionFileFromImportReport(report);
+    expect(f.select).toEqual([{ node: QUEUE, as: "QueueJobs", type: "AWS::SQS::Queue" }]);
+    expect(adoptionFileProblemsAgainst(f, DOC)).toEqual([]);
+    expect(() => adoptionFileFromImportReport({ ...report, index: [...report.index, { ...report.index[0], scopeKey: "cloud/aws/111/x" }] })).toThrow(/names one index version/);
+    expect(() => adoptionFileFromImportReport({ ...report, resources: [report.resources[1]] })).toThrow(/nothing to adopt/);
+  });
+});

package/src/lifecycle/adoption-file.ts

@@ -0,0 +1,154 @@
+/**
+ * The adoption file, `adopt: "v1"` (chant#4536; ruled on
+ * INTENTIUS/choudoufu#2284 Q1, 2026-10-26).
+ *
+ * One input for the three engines that adopt an indexed resource: choudoufu
+ * `live-import`, plunge `stack adopt` and chant's CloudFormation import. It
+ * names one index version (scope key, version name and digest) and the nodes
+ * to adopt from it. Each selected node carries the engine's address for it
+ * and, where the inventory type joins to more than one engine type, the
+ * engine type.
+ *
+ * The index proposes and the live read decides: an engine reads each object
+ * again before it writes anything. The file only says which object and
+ * where. An engine refuses a file whose index digest does not match the
+ * version it loads, and a node that version does not hold
+ * ({@link validateAdoptionFile}).
+ *
+ * Its JSON Schema is `#/$defs/AdoptionFile` in ../graph-schema/graph.schema.json,
+ * generated from these types; the Go engines read the JSON and test against
+ * ../graph-schema/fixtures/adopt.json.
+ *
+ * `chant import --index ... --adopt-out <file>` writes one from the import
+ * report ({@link adoptionFileFromImportReport}).
+ */
+import { NEXT_RELEASE } from "../release-floors";
+import { indexVersionName, type IndexDocument } from "./index-document";
+import type { IndexImportReport } from "./index-import";
+
+/** The first chant that writes or reads an adoption file. */
+export const ADOPTION_FILE_FLOOR = NEXT_RELEASE;
+
+/** The index version an adoption file reads from. */
+export interface AdoptionIndexRef {
+  /** The version's `stamp.scopeKey`: `cloud/<substrate>/<scopeId>/<scope digest>`. */
+  scopeKey: string;
+  /** The version's file name under the scope key: `<observedAt>-<digest12>.json`. */
+  version: string;
+  /** The version's `stamp.digest`, sha256 hex. A `sha256:` prefix is accepted and ignored. */
+  digest: string;
+}
+
+/** One node to adopt. */
+export interface AdoptionSelection {
+  /** The index node id: `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`. */
+  node: string;
+  /**
+   * The engine's address for the object: a Terraform address for choudoufu,
+   * a URN name and parent for plunge, an entity (logical) name for chant.
+   */
+  as: string;
+  /**
+   * The engine's type (`aws_lb`, `aws:s3/bucket:Bucket`, `AWS::S3::Bucket`).
+   * Left out only when the node's listed type joins to exactly one engine
+   * type; an engine refuses an ambiguous join without it, naming every
+   * candidate.
+   */
+  type?: string;
+}
+
+/** An adoption file (`adopt: "v1"`): one index version and the nodes to adopt from it. */
+export interface AdoptionFile {
+  adopt: "v1";
+  index: AdoptionIndexRef;
+  select: AdoptionSelection[];
+}
+
+const bareDigest = (d: string): string => d.replace(/^sha256:/, "");
+
+/** Refusals of an adoption file on its own: shape, version name, duplicate nodes and addresses. */
+export function adoptionFileProblems(file: AdoptionFile): string[] {
+  const problems: string[] = [];
+  if (file.adopt !== "v1") problems.push(`adoption file version "${String(file.adopt)}" is not v1`);
+  const ix = file.index;
+  if (!ix || typeof ix.scopeKey !== "string" || ix.scopeKey === "") problems.push("index.scopeKey is missing");
+  if (!ix || typeof ix.digest !== "string" || !/^[0-9a-f]{12,}$/.test(bareDigest(ix.digest))) {
+    problems.push(`index.digest "${String(ix?.digest)}" is not sha256 hex`);
+  } else if (typeof ix.version !== "string" || !/^\d{8}T\d{6}Z-[0-9a-f]{12}\.json$/.test(ix.version)) {
+    problems.push(`index.version "${String(ix?.version)}" is not an index version name (<observedAt>-<digest12>.json)`);
+  } else if (!ix.version.endsWith(`-${bareDigest(ix.digest).slice(0, 12)}.json`)) {
+    problems.push(`index.version ${ix.version} does not name the digest ${bareDigest(ix.digest).slice(0, 12)}`);
+  }
+  if (!Array.isArray(file.select) || file.select.length === 0) {
+    problems.push("select names no node");
+    return problems;
+  }
+  const nodes = new Set<string>();
+  const addresses = new Set<string>();
+  for (const s of file.select) {
+    if (!s.node) problems.push("a selection has no node");
+    if (!s.as) problems.push(`${s.node}: no engine address (as)`);
+    if (s.node && nodes.has(s.node)) problems.push(`${s.node} is selected twice`);
+    if (s.as && addresses.has(s.as)) problems.push(`two nodes are adopted as ${s.as}`);
+    nodes.add(s.node);
+    addresses.add(s.as);
+  }
+  return problems;
+}
+
+/**
+ * Refusals of an adoption file against the index version it is read with:
+ * a scope key, version or digest that is not that version's, and a selected
+ * node the version does not hold. Empty when the file can be used.
+ */
+export function adoptionFileProblemsAgainst(file: AdoptionFile, doc: IndexDocument): string[] {
+  const problems = adoptionFileProblems(file);
+  const { stamp } = doc;
+  if (file.index.scopeKey !== stamp.scopeKey) problems.push(`index.scopeKey ${file.index.scopeKey} is not the version's ${stamp.scopeKey}`);
+  if (bareDigest(file.index.digest) !== bareDigest(stamp.digest)) problems.push(`index.digest does not match the version's digest ${bareDigest(stamp.digest).slice(0, 12)}`);
+  const version = indexVersionName(stamp.observedAt, stamp.digest);
+  if (file.index.version !== version) problems.push(`index.version ${file.index.version} is not the version read (${version})`);
+  const held = new Set(doc.graph.nodes.map((n) => n.id));
+  for (const s of file.select ?? []) {
+    if (s.node && !held.has(s.node)) problems.push(`${s.node} is not in index version ${version}`);
+  }
+  return problems;
+}
+
+/** Throw on the first refusal of {@link adoptionFileProblemsAgainst}, or of {@link adoptionFileProblems} with no document. */
+export function validateAdoptionFile(file: AdoptionFile, doc?: IndexDocument): void {
+  const problems = doc ? adoptionFileProblemsAgainst(file, doc) : adoptionFileProblems(file);
+  if (problems.length > 0) throw new Error(`adoption file refused: ${problems.join("; ")}`);
+}
+
+/**
+ * The adoption file for what an index import wrote: every `imported`
+ * resource, adopted as its logical id, with its lexicon kind as the type
+ * (`AWS::S3::Bucket`). Declared and unsupported resources are left out. Refuses a report
+ * read from more than one index version, since an adoption file names one.
+ */
+export function adoptionFileFromImportReport(report: IndexImportReport): AdoptionFile {
+  if (report.index.length !== 1) {
+    throw new Error(
+      `an adoption file names one index version; this import read ${report.index.length} (${report.index.map((i) => i.scopeKey).join(", ")})`,
+    );
+  }
+  const [ix] = report.index;
+  const select: AdoptionSelection[] = report.resources
+    .filter((r) => r.status === "imported" && r.logicalId !== undefined)
+    .map((r) => ({ node: r.node, as: r.logicalId!, ...(r.kind ? { type: r.kind } : {}) }))
+    .sort((a, b) => (a.node < b.node ? -1 : a.node > b.node ? 1 : 0));
+  if (select.length === 0) throw new Error("the import wrote no resource, so there is nothing to adopt");
+  const file: AdoptionFile = {
+    adopt: "v1",
+    index: { scopeKey: ix.scopeKey, version: indexVersionName(ix.observedAt, ix.digest), digest: bareDigest(ix.digest) },
+    select,
+  };
+  validateAdoptionFile(file);
+  return file;
+}
+
+/** An adoption file as written: two-space JSON and a final newline. */
+export function adoptionFileJson(file: AdoptionFile): string {
+  return JSON.stringify(file, null, 2) + "\n";
+}