@suss/contract-terraform 0.7.0

package/LICENSE

@@ -0,0 +1,205 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable by
+      such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor has
+      been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format please. Also add information on
+      how to contact you by electronic and paper mail.
+
+      If the program does not interact with users remotely through a computer
+      network, then your name and employer's name (e.g., your institution)
+      is sufficient to fill in the "name of copyright owner" field. Feel
+      free to omit the "name of employer" line if you are in no way affiliated
+      with any institution.
+
+      Copyright 2026 Nimbus Cloud AI LLC
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,57 @@
+# @suss/contract-terraform
+
+Reads the storage a Terraform configuration declares, so code can be checked against it.
+
+## What this package is
+
+A contract reader. It walks `.tf` files for `aws_dynamodb_table` resources and describes each one as a boundary, the same way `@suss/contract-cloudformation` describes a table a template declares.
+
+```bash
+suss contract --from terraform infra/terraform/dynamodb -o tables.json
+```
+
+The path may be one file or the directory a module lives in, since a module states its resources across several files.
+
+## What it reads
+
+```hcl
+resource "aws_dynamodb_table" "orders" {
+  name      = "${local.environment}-orders-v1"
+  hash_key  = "order_id"
+  range_key = "placed_at"
+
+  attribute {
+    name = "order_id"
+    type = "S"
+  }
+
+  global_secondary_index {
+    name     = "by-customer-v1"
+    hash_key = "customer_id"
+  }
+}
+```
+
+The resource label is the container, since that is what the rest of the configuration refers to. `name` is what the table is called once deployed, and it goes on the contract as the physical name.
+
+That name is usually built at deploy time, and Terraform interpolates the same way CloudFormation does, so `"${local.environment}-orders-v1"` is recorded as the pattern `{local.environment}-orders-v1`. Code that builds the same name from its own variable records `{stage}-orders-v1`, and the two pair on the fixed text. This is what lets a service written in TypeScript meet a table declared in HCL.
+
+Each secondary index becomes its own boundary, because a query through an index keys on that index's fields. `hash_key` and `range_key` say what identifies an item, partition key first, and the `attribute` blocks give each key its type.
+
+A table declares its keys and lets every other attribute vary, so the contract says `fieldSet: "partial"` and the checker never calls an ordinary attribute unknown.
+
+## What it will not tell you
+
+- **Only DynamoDB tables.** An RDS instance, an S3 bucket, or an SQS queue declared in the same configuration is skipped.
+- **A resource built with `for_each` or `count`** states one block for many tables, and this reads the block as written rather than working out what it expands to.
+- **A name a variable supplies whole**, `name = var.table_name`, has no fixed text to pair on, so it records nothing rather than guessing.
+
+## Where it fits in suss
+
+Depends on `@suss/behavioral-ir` for the summaries it produces and `hcl2-parser` for reading HCL. The storage pass in `@suss/checker` pairs what code touches against what this declares.
+
+## A way in that copies part of an item
+
+A DynamoDB index does not carry the whole item. `projection_type = "INCLUDE"` copies the attributes it lists, `KEYS_ONLY` copies none, and both copy the index's keys and the table's. A reader asking that index for anything else gets nothing back for it, and the store raises no error, so the caller sees an item with fields missing and nothing says why.
+
+So an index like that declares every field it will ever have, and its contract says `exhaustive` where the table's says `partial`. A pack states which attributes carry that, under `serves`, and a store without the idea leaves it out.

package/dist/index.cjs

@@ -0,0 +1,309 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  terraformFileToSummaries: () => terraformFileToSummaries,
+  terraformToSummaries: () => terraformToSummaries
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_hcl2_parser = __toESM(require("hcl2-parser"), 1);
+var import_semver = __toESM(require("semver"), 1);
+var import_behavioral_ir = require("@suss/behavioral-ir");
+function terraformToSummaries(source, sourceFile, options) {
+  let parsed;
+  try {
+    const [read] = import_hcl2_parser.default.parseToObject(source);
+    parsed = read;
+  } catch {
+    return [];
+  }
+  const document = asRecord(parsed);
+  if (document === null) {
+    return [];
+  }
+  const constraints = providerConstraints(document);
+  const summaries = [];
+  for (const [resourceType, label, body] of resourcesIn(document)) {
+    for (const pack of options.packs) {
+      const pattern = patternFor(pack, resourceType, constraints);
+      if (pattern === void 0) {
+        continue;
+      }
+      summaries.push(
+        ...summariesFor({ pattern, label, body, sourceFile, resourceType })
+      );
+    }
+  }
+  return summaries;
+}
+function terraformFileToSummaries(target, options) {
+  const files = import_node_fs.default.statSync(target).isDirectory() ? import_node_fs.default.readdirSync(target).filter((name) => name.endsWith(".tf")).map((name) => import_node_path.default.join(target, name)) : [target];
+  return files.flatMap(
+    (file) => terraformToSummaries(import_node_fs.default.readFileSync(file, "utf8"), file, options)
+  );
+}
+function providerConstraints(document) {
+  const constraints = /* @__PURE__ */ new Map();
+  for (const block of arrayOf(document.terraform)) {
+    for (const required of arrayOf(asRecord(block)?.required_providers)) {
+      const declared = asRecord(required);
+      if (declared === null) {
+        continue;
+      }
+      for (const [provider, spec] of Object.entries(declared)) {
+        for (const entry of arrayOf(spec)) {
+          const version = stringOf(asRecord(entry)?.version);
+          if (version !== null) {
+            constraints.set(provider, version);
+          }
+        }
+      }
+    }
+  }
+  return constraints;
+}
+function patternFor(pack, resourceType, constraints) {
+  const pinned = constraints.get(pack.provider);
+  return pack.resources.find((pattern) => {
+    if (pattern.resource !== resourceType) {
+      return false;
+    }
+    if (pinned === void 0) {
+      return true;
+    }
+    try {
+      return import_semver.default.intersects(pinned, pattern.providerVersions, {
+        loose: true
+      });
+    } catch {
+      return true;
+    }
+  });
+}
+function summariesFor(opts) {
+  const { pattern } = opts;
+  if (pattern.boundary.kind === "message-bus") {
+    return [busSummary({ ...opts, boundary: pattern.boundary })];
+  }
+  const boundary = pattern.boundary;
+  const types = fieldTypes(opts.body, boundary);
+  return keyedShapes(opts.body, boundary).map(
+    (shape) => storageSummary({ ...opts, boundary, shape, types })
+  );
+}
+function storageSummary(opts) {
+  const { boundary, label, shape, types } = opts;
+  const address = `${opts.resourceType}.${label}`;
+  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
+  const physicalTable = declaredName === null ? null : (0, import_behavioral_ir.namePatternFromSub)(declaredName);
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: shape.accessPath === null ? address : `${address}#${shape.accessPath}`,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir.storageBinding)({
+        recognition: "terraform",
+        storageSystem: boundary.storageSystem,
+        ...boundary.transport !== void 0 ? { transport: boundary.transport } : {},
+        scope: "default",
+        container: label,
+        accessPath: shape.accessPath
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      storageContract: {
+        // A way in that copies part of an item has every field it will
+        // ever have, whatever the container itself stores.
+        fieldSet: shape.serves === null ? boundary.fieldSet : "exhaustive",
+        ...boundary.identifies === void 0 ? {} : {
+          identifies: { kind: "keyFields", fields: shape.keyFields },
+          fields: (shape.serves ?? shape.keyFields).map((field) => ({
+            name: field,
+            ...types.has(field) ? { type: types.get(field) } : {},
+            ...shape.keyFields.includes(field) ? { primary: true } : {}
+          }))
+        },
+        ...physicalTable !== null ? { physicalTable } : {}
+      }
+    }
+  };
+}
+function busSummary(opts) {
+  const { boundary, label } = opts;
+  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
+  const physicalName = declaredName === null ? null : (0, import_behavioral_ir.namePatternFromSub)(declaredName);
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: `${opts.resourceType}.${label}`,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir.messageBusBinding)({
+        recognition: "terraform",
+        messageBus: boundary.messageBus,
+        channel: label
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      messageBus: {
+        ...physicalName !== null ? { physicalName } : {},
+        ...opts.body.fifo_queue === true ? { fifoQueue: true } : {},
+        ...opts.body.fifo_topic === true ? { fifoTopic: true } : {}
+      }
+    }
+  };
+}
+function keyedShapes(body, boundary) {
+  if (boundary.identifies === void 0) {
+    return [{ accessPath: null, keyFields: [], serves: null }];
+  }
+  const ownKeys = keyFields(body, boundary.identifies);
+  const shapes = [
+    { accessPath: null, keyFields: ownKeys, serves: null }
+  ];
+  for (const block of boundary.accessPathBlocks ?? []) {
+    for (const declared of arrayOf(body[block])) {
+      const index = asRecord(declared);
+      const indexName = index === null ? null : stringOf(index.name);
+      if (index === null || indexName === null) {
+        continue;
+      }
+      const indexKeys = keyFields(index, boundary.identifies);
+      shapes.push({
+        accessPath: indexName,
+        keyFields: indexKeys,
+        serves: servedFields(index, boundary, [...indexKeys, ...ownKeys])
+      });
+    }
+  }
+  return shapes;
+}
+function servedFields(block, boundary, keys) {
+  const spec = boundary.serves;
+  if (spec === void 0) {
+    return null;
+  }
+  const kind = stringOf(block[spec.kindAttribute]);
+  if (kind === null || kind === spec.everything) {
+    return null;
+  }
+  const listed = arrayOf(block[spec.fieldsAttribute]).flatMap(
+    (entry) => Array.isArray(entry) ? entry : [entry]
+  );
+  const named = listed.filter(
+    (entry) => typeof entry === "string"
+  );
+  return [.../* @__PURE__ */ new Set([...keys, ...named])];
+}
+function keyFields(block, attributes) {
+  return attributes.map((attribute) => stringOf(block[attribute])).filter((field) => field !== null);
+}
+function fieldTypes(body, boundary) {
+  const types = /* @__PURE__ */ new Map();
+  const spec = boundary.fieldTypes;
+  if (spec === void 0) {
+    return types;
+  }
+  for (const declared of arrayOf(body[spec.block])) {
+    const field = asRecord(declared);
+    if (field === null) {
+      continue;
+    }
+    const name = stringOf(field[spec.nameAttribute]);
+    const type = stringOf(field[spec.typeAttribute]);
+    if (name !== null && type !== null) {
+      types.set(name, type);
+    }
+  }
+  return types;
+}
+function resourcesIn(document) {
+  const found = [];
+  for (const resource of arrayOf(document.resource)) {
+    const byType = asRecord(resource);
+    if (byType === null) {
+      continue;
+    }
+    for (const [resourceType, labelled] of Object.entries(byType)) {
+      for (const group of arrayOf(labelled)) {
+        const byLabel = asRecord(group);
+        if (byLabel === null) {
+          continue;
+        }
+        for (const [label, bodies] of Object.entries(byLabel)) {
+          for (const body of arrayOf(bodies)) {
+            const read = asRecord(body);
+            if (read !== null) {
+              found.push([resourceType, label, read]);
+            }
+          }
+        }
+      }
+    }
+  }
+  return found;
+}
+function arrayOf(value) {
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function stringOf(value) {
+  return typeof value === "string" ? value : null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  terraformFileToSummaries,
+  terraformToSummaries
+});

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { MessageBusTechnology, BehavioralSummary } from '@suss/behavioral-ir';
+
+/**
+ * What a pack says about the resources one Terraform provider declares.
+ *
+ * A provider states its own resource types, and a version of it states
+ * their shape, so both belong to a pack rather than to this reader. The
+ * reader walks HCL and matches; a pack says what `aws_dynamodb_table`
+ * is and which provider versions it is describing.
+ *
+ * Every entry is data rather than a function. A resource this shape
+ * cannot describe is a reason to widen it, rather than a reason for a
+ * pack to ship code the reader cannot see into.
+ */
+
+/** A store a caller addresses by container and key. */
+interface StorageResource {
+    kind: "storage";
+    /** Which store this is: dynamodb, s3. */
+    storageSystem: string;
+    /** How a caller reaches it, when that is not the store's own name. */
+    transport?: string;
+    /** The attribute that says what the resource is called once deployed. */
+    nameAttribute?: string;
+    /** Whether the fields it declares are every field an item has. */
+    fieldSet: "exhaustive" | "partial" | "none";
+    /** The attributes that state what identifies an item, in key order. */
+    identifies?: string[];
+    /** Blocks that declare another way in, each keyed on its own fields. */
+    accessPathBlocks?: string[];
+    /** The block that gives each field a type, and its two attributes. */
+    fieldTypes?: {
+        block: string;
+        nameAttribute: string;
+        typeAttribute: string;
+    };
+    /**
+     * How another way in says what it can serve. A DynamoDB index copies
+     * some of an item rather than all of it, and a reader asking for
+     * anything else gets nothing back and no error, so what it copies is
+     * every field it has rather than the ones somebody wrote down.
+     */
+    serves?: {
+        /** The attribute that says which kind of copy it keeps. */
+        kindAttribute: string;
+        /** The attribute listing what it copies, for the kind that lists. */
+        fieldsAttribute: string;
+        /** The value of `kindAttribute` that means it copies the item. */
+        everything: string;
+    };
+}
+/** A channel messages cross. */
+interface MessageBusResource {
+    kind: "message-bus";
+    messageBus: MessageBusTechnology;
+    nameAttribute?: string;
+}
+type TerraformResource = StorageResource | MessageBusResource;
+/** One resource type, as one version range of one provider declares it. */
+interface TerraformResourcePattern {
+    /** The resource type, spelled the way the provider spells it. */
+    resource: string;
+    /**
+     * Which provider versions this describes, as a semver range. A
+     * configuration states its own constraint under `required_providers`,
+     * and an entry outside it is not read. A configuration that states no
+     * constraint is read by every entry, since nothing said otherwise.
+     */
+    providerVersions: string;
+    /** What the resource is, once read. */
+    boundary: TerraformResource;
+}
+interface TerraformPack {
+    /** The pack's own name, for messages. */
+    name: string;
+    /**
+     * The provider these resources come from, as `required_providers`
+     * keys it: `aws`, `google`, `cloudflare`.
+     */
+    provider: string;
+    resources: TerraformResourcePattern[];
+}
+
+/**
+ * The boundaries a Terraform configuration declares.
+ *
+ * This reads HCL and matches what it finds against the packs a run
+ * loads. A pack says what `aws_dynamodb_table` is; nothing about any
+ * provider is written here.
+ *
+ * A name is usually built at deploy time, and Terraform interpolates
+ * the same way CloudFormation does, so `"${local.environment}-orders"`
+ * becomes the pattern `{local.environment}-orders` and pairs with code
+ * that builds the same name from its own variable. The README says how
+ * a block that HCL states once or many times is read.
+ */
+
+interface TerraformReadOptions {
+    /** The packs that say what this configuration's resources are. */
+    packs: TerraformPack[];
+}
+/** Every boundary one Terraform configuration declares. */
+declare function terraformToSummaries(source: string, sourceFile: string, options: TerraformReadOptions): BehavioralSummary[];
+/** Read one `.tf` file, or every one directly inside a directory. */
+declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];
+
+export { type MessageBusResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, terraformFileToSummaries, terraformToSummaries };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { MessageBusTechnology, BehavioralSummary } from '@suss/behavioral-ir';
+
+/**
+ * What a pack says about the resources one Terraform provider declares.
+ *
+ * A provider states its own resource types, and a version of it states
+ * their shape, so both belong to a pack rather than to this reader. The
+ * reader walks HCL and matches; a pack says what `aws_dynamodb_table`
+ * is and which provider versions it is describing.
+ *
+ * Every entry is data rather than a function. A resource this shape
+ * cannot describe is a reason to widen it, rather than a reason for a
+ * pack to ship code the reader cannot see into.
+ */
+
+/** A store a caller addresses by container and key. */
+interface StorageResource {
+    kind: "storage";
+    /** Which store this is: dynamodb, s3. */
+    storageSystem: string;
+    /** How a caller reaches it, when that is not the store's own name. */
+    transport?: string;
+    /** The attribute that says what the resource is called once deployed. */
+    nameAttribute?: string;
+    /** Whether the fields it declares are every field an item has. */
+    fieldSet: "exhaustive" | "partial" | "none";
+    /** The attributes that state what identifies an item, in key order. */
+    identifies?: string[];
+    /** Blocks that declare another way in, each keyed on its own fields. */
+    accessPathBlocks?: string[];
+    /** The block that gives each field a type, and its two attributes. */
+    fieldTypes?: {
+        block: string;
+        nameAttribute: string;
+        typeAttribute: string;
+    };
+    /**
+     * How another way in says what it can serve. A DynamoDB index copies
+     * some of an item rather than all of it, and a reader asking for
+     * anything else gets nothing back and no error, so what it copies is
+     * every field it has rather than the ones somebody wrote down.
+     */
+    serves?: {
+        /** The attribute that says which kind of copy it keeps. */
+        kindAttribute: string;
+        /** The attribute listing what it copies, for the kind that lists. */
+        fieldsAttribute: string;
+        /** The value of `kindAttribute` that means it copies the item. */
+        everything: string;
+    };
+}
+/** A channel messages cross. */
+interface MessageBusResource {
+    kind: "message-bus";
+    messageBus: MessageBusTechnology;
+    nameAttribute?: string;
+}
+type TerraformResource = StorageResource | MessageBusResource;
+/** One resource type, as one version range of one provider declares it. */
+interface TerraformResourcePattern {
+    /** The resource type, spelled the way the provider spells it. */
+    resource: string;
+    /**
+     * Which provider versions this describes, as a semver range. A
+     * configuration states its own constraint under `required_providers`,
+     * and an entry outside it is not read. A configuration that states no
+     * constraint is read by every entry, since nothing said otherwise.
+     */
+    providerVersions: string;
+    /** What the resource is, once read. */
+    boundary: TerraformResource;
+}
+interface TerraformPack {
+    /** The pack's own name, for messages. */
+    name: string;
+    /**
+     * The provider these resources come from, as `required_providers`
+     * keys it: `aws`, `google`, `cloudflare`.
+     */
+    provider: string;
+    resources: TerraformResourcePattern[];
+}
+
+/**
+ * The boundaries a Terraform configuration declares.
+ *
+ * This reads HCL and matches what it finds against the packs a run
+ * loads. A pack says what `aws_dynamodb_table` is; nothing about any
+ * provider is written here.
+ *
+ * A name is usually built at deploy time, and Terraform interpolates
+ * the same way CloudFormation does, so `"${local.environment}-orders"`
+ * becomes the pattern `{local.environment}-orders` and pairs with code
+ * that builds the same name from its own variable. The README says how
+ * a block that HCL states once or many times is read.
+ */
+
+interface TerraformReadOptions {
+    /** The packs that say what this configuration's resources are. */
+    packs: TerraformPack[];
+}
+/** Every boundary one Terraform configuration declares. */
+declare function terraformToSummaries(source: string, sourceFile: string, options: TerraformReadOptions): BehavioralSummary[];
+/** Read one `.tf` file, or every one directly inside a directory. */
+declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];
+
+export { type MessageBusResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, terraformFileToSummaries, terraformToSummaries };

package/dist/index.js

@@ -0,0 +1,277 @@
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import hcl2 from "hcl2-parser";
+import semver from "semver";
+import {
+  messageBusBinding,
+  namePatternFromSub,
+  storageBinding
+} from "@suss/behavioral-ir";
+function terraformToSummaries(source, sourceFile, options) {
+  let parsed;
+  try {
+    const [read] = hcl2.parseToObject(source);
+    parsed = read;
+  } catch {
+    return [];
+  }
+  const document = asRecord(parsed);
+  if (document === null) {
+    return [];
+  }
+  const constraints = providerConstraints(document);
+  const summaries = [];
+  for (const [resourceType, label, body] of resourcesIn(document)) {
+    for (const pack of options.packs) {
+      const pattern = patternFor(pack, resourceType, constraints);
+      if (pattern === void 0) {
+        continue;
+      }
+      summaries.push(
+        ...summariesFor({ pattern, label, body, sourceFile, resourceType })
+      );
+    }
+  }
+  return summaries;
+}
+function terraformFileToSummaries(target, options) {
+  const files = fs.statSync(target).isDirectory() ? fs.readdirSync(target).filter((name) => name.endsWith(".tf")).map((name) => path.join(target, name)) : [target];
+  return files.flatMap(
+    (file) => terraformToSummaries(fs.readFileSync(file, "utf8"), file, options)
+  );
+}
+function providerConstraints(document) {
+  const constraints = /* @__PURE__ */ new Map();
+  for (const block of arrayOf(document.terraform)) {
+    for (const required of arrayOf(asRecord(block)?.required_providers)) {
+      const declared = asRecord(required);
+      if (declared === null) {
+        continue;
+      }
+      for (const [provider, spec] of Object.entries(declared)) {
+        for (const entry of arrayOf(spec)) {
+          const version = stringOf(asRecord(entry)?.version);
+          if (version !== null) {
+            constraints.set(provider, version);
+          }
+        }
+      }
+    }
+  }
+  return constraints;
+}
+function patternFor(pack, resourceType, constraints) {
+  const pinned = constraints.get(pack.provider);
+  return pack.resources.find((pattern) => {
+    if (pattern.resource !== resourceType) {
+      return false;
+    }
+    if (pinned === void 0) {
+      return true;
+    }
+    try {
+      return semver.intersects(pinned, pattern.providerVersions, {
+        loose: true
+      });
+    } catch {
+      return true;
+    }
+  });
+}
+function summariesFor(opts) {
+  const { pattern } = opts;
+  if (pattern.boundary.kind === "message-bus") {
+    return [busSummary({ ...opts, boundary: pattern.boundary })];
+  }
+  const boundary = pattern.boundary;
+  const types = fieldTypes(opts.body, boundary);
+  return keyedShapes(opts.body, boundary).map(
+    (shape) => storageSummary({ ...opts, boundary, shape, types })
+  );
+}
+function storageSummary(opts) {
+  const { boundary, label, shape, types } = opts;
+  const address = `${opts.resourceType}.${label}`;
+  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
+  const physicalTable = declaredName === null ? null : namePatternFromSub(declaredName);
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: shape.accessPath === null ? address : `${address}#${shape.accessPath}`,
+      exportPath: null,
+      boundaryBinding: storageBinding({
+        recognition: "terraform",
+        storageSystem: boundary.storageSystem,
+        ...boundary.transport !== void 0 ? { transport: boundary.transport } : {},
+        scope: "default",
+        container: label,
+        accessPath: shape.accessPath
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      storageContract: {
+        // A way in that copies part of an item has every field it will
+        // ever have, whatever the container itself stores.
+        fieldSet: shape.serves === null ? boundary.fieldSet : "exhaustive",
+        ...boundary.identifies === void 0 ? {} : {
+          identifies: { kind: "keyFields", fields: shape.keyFields },
+          fields: (shape.serves ?? shape.keyFields).map((field) => ({
+            name: field,
+            ...types.has(field) ? { type: types.get(field) } : {},
+            ...shape.keyFields.includes(field) ? { primary: true } : {}
+          }))
+        },
+        ...physicalTable !== null ? { physicalTable } : {}
+      }
+    }
+  };
+}
+function busSummary(opts) {
+  const { boundary, label } = opts;
+  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
+  const physicalName = declaredName === null ? null : namePatternFromSub(declaredName);
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: `${opts.resourceType}.${label}`,
+      exportPath: null,
+      boundaryBinding: messageBusBinding({
+        recognition: "terraform",
+        messageBus: boundary.messageBus,
+        channel: label
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      messageBus: {
+        ...physicalName !== null ? { physicalName } : {},
+        ...opts.body.fifo_queue === true ? { fifoQueue: true } : {},
+        ...opts.body.fifo_topic === true ? { fifoTopic: true } : {}
+      }
+    }
+  };
+}
+function keyedShapes(body, boundary) {
+  if (boundary.identifies === void 0) {
+    return [{ accessPath: null, keyFields: [], serves: null }];
+  }
+  const ownKeys = keyFields(body, boundary.identifies);
+  const shapes = [
+    { accessPath: null, keyFields: ownKeys, serves: null }
+  ];
+  for (const block of boundary.accessPathBlocks ?? []) {
+    for (const declared of arrayOf(body[block])) {
+      const index = asRecord(declared);
+      const indexName = index === null ? null : stringOf(index.name);
+      if (index === null || indexName === null) {
+        continue;
+      }
+      const indexKeys = keyFields(index, boundary.identifies);
+      shapes.push({
+        accessPath: indexName,
+        keyFields: indexKeys,
+        serves: servedFields(index, boundary, [...indexKeys, ...ownKeys])
+      });
+    }
+  }
+  return shapes;
+}
+function servedFields(block, boundary, keys) {
+  const spec = boundary.serves;
+  if (spec === void 0) {
+    return null;
+  }
+  const kind = stringOf(block[spec.kindAttribute]);
+  if (kind === null || kind === spec.everything) {
+    return null;
+  }
+  const listed = arrayOf(block[spec.fieldsAttribute]).flatMap(
+    (entry) => Array.isArray(entry) ? entry : [entry]
+  );
+  const named = listed.filter(
+    (entry) => typeof entry === "string"
+  );
+  return [.../* @__PURE__ */ new Set([...keys, ...named])];
+}
+function keyFields(block, attributes) {
+  return attributes.map((attribute) => stringOf(block[attribute])).filter((field) => field !== null);
+}
+function fieldTypes(body, boundary) {
+  const types = /* @__PURE__ */ new Map();
+  const spec = boundary.fieldTypes;
+  if (spec === void 0) {
+    return types;
+  }
+  for (const declared of arrayOf(body[spec.block])) {
+    const field = asRecord(declared);
+    if (field === null) {
+      continue;
+    }
+    const name = stringOf(field[spec.nameAttribute]);
+    const type = stringOf(field[spec.typeAttribute]);
+    if (name !== null && type !== null) {
+      types.set(name, type);
+    }
+  }
+  return types;
+}
+function resourcesIn(document) {
+  const found = [];
+  for (const resource of arrayOf(document.resource)) {
+    const byType = asRecord(resource);
+    if (byType === null) {
+      continue;
+    }
+    for (const [resourceType, labelled] of Object.entries(byType)) {
+      for (const group of arrayOf(labelled)) {
+        const byLabel = asRecord(group);
+        if (byLabel === null) {
+          continue;
+        }
+        for (const [label, bodies] of Object.entries(byLabel)) {
+          for (const body of arrayOf(bodies)) {
+            const read = asRecord(body);
+            if (read !== null) {
+              found.push([resourceType, label, read]);
+            }
+          }
+        }
+      }
+    }
+  }
+  return found;
+}
+function arrayOf(value) {
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function stringOf(value) {
+  return typeof value === "string" ? value : null;
+}
+export {
+  terraformFileToSummaries,
+  terraformToSummaries
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@suss/contract-terraform",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Read the storage a Terraform configuration declares, for checking code against it.",
+  "keywords": [
+    "suss",
+    "behavioral-summary",
+    "terraform",
+    "dynamodb",
+    "storage"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/terraform#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/contract/terraform"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@suss/behavioral-ir": "0.7.0",
+    "hcl2-parser": "^1.0.3",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/semver": "*",
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}