@suss/contract-terraform 0.33.1 → 0.34.0

package/README.md

@@ -1,18 +1,18 @@
 # @suss/contract-terraform
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Reads the boundaries a Terraform configuration declares, so code and other resources can be checked against them.
+This package reads the boundaries a Terraform configuration declares, so code and other resources can be checked against them.
 
 ## What this package is
 
-A contract reader. It walks `.tf` files and describes what it finds as boundaries, the same way `@suss/contract-cloudformation` describes what a template declares. It knows no provider: a pack says that `aws_dynamodb_table` is a store and that `google_logging_metric` is a metric, and this matches on what the pack says.
+A contract reader. It walks `.tf` files and records what it finds as boundaries, the same way `@suss/contract-cloudformation` records what a template declares. It has no provider knowledge of its own. A pack declares that `aws_dynamodb_table` is a store and that `google_logging_metric` is a metric, and this reader matches on those declarations.
 
 ```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. A root module that only calls child modules is read too: see below.
+The path can be one file or the directory a module is in, since a module declares its resources across several files. A root module that only calls child modules is read too, as described below.
 
 ## What it reads
 
@@ -34,17 +34,17 @@ resource "aws_dynamodb_table" "orders" {
 }
 ```
 
-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.
+The resource label is the container, since the rest of the configuration refers to the resource by its label. `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.
+That name is usually built at deploy time. 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. That is how a service written in TypeScript pairs with 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.
+Each secondary index becomes its own boundary, because a query through an index keys on that index's fields. `hash_key` and `range_key` give 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.
+A table declares its keys and lets every other attribute vary, so the contract has `fieldSet: "partial"`, and the checker never reports an ordinary attribute as unknown.
 
 ## A structure written as JSON
 
-Several providers take a structure as a string rather than as blocks: a BigQuery table's schema, an ECS task's container definitions, an IAM policy document. Terraform gives an author two ways to write one, and both mean the same thing once deployed:
+Several providers take a structure as a string instead of as blocks. Examples are a BigQuery table's schema and an ECS task's container definitions. Terraform lets an author write one in two ways, and both mean the same thing once deployed:
 
 ```hcl
 schema = jsonencode([
@@ -56,23 +56,23 @@ schema = <<EOF
 EOF
 ```
 
-`jsonAttributeValue` reads both, and a pack asks for one through `fieldsFromJson` on a storage entry, saying which attribute the JSON is at and which keys of an entry give the field its name, its type, and whether it is always set. A schema written this way is every field the item has, so the contract comes out `exhaustive`. One a file or a variable supplies is not written down anywhere the reader can see, so nothing is recorded rather than guessed.
+`jsonAttributeValue` reads both. A pack asks for it through `fieldsFromJson` on a storage entry, giving the attribute the JSON is in, and the keys in each entry that give the field its name, its type, and whether it is always set. A schema written this way lists every field the item has, so the contract comes out `exhaustive`. A schema supplied by a file or a variable is not written anywhere the reader can see, so the reader records nothing and does not guess.
 
-A deployable steps into such an attribute rather than reading fields out of it. An ECS task writes its containers as `container_definitions = jsonencode([...])`, and a pack puts that attribute where it would put a block, so each container is read the same way a Cloud Run container written as blocks is.
+For a deployable, the reader goes into such an attribute and reads blocks from it, where a store would have fields read out of it. An ECS task writes its containers as `container_definitions = jsonencode([...])`, and a pack treats that attribute the way it would treat a block. So each container is read the same way as a Cloud Run container written as blocks.
 
 ## A block written once and deployed many times
 
-A module rarely writes a container's variables out one block at a time. It writes one `dynamic "env"` block over a map, or, in an ECS task's JSON, a `for` expression over the same thing. Both are expanded where the configuration already says what is in that map, so the container declares the variables the deployment will give it rather than none at all. [How a repeated block is expanded](./DESIGN.md#a-block-written-once-and-deployed-many-times) says which spellings settle and which stay holes.
+A module rarely writes a container's variables one block at a time. It writes one `dynamic "env"` block over a map, or, in an ECS task's JSON, a `for` expression over the same map. The reader expands both wherever the configuration already gives the contents of that map, so the container declares the variables the deployment will give it, instead of none. [How a repeated block is expanded](./DESIGN.md#a-block-written-once-and-deployed-many-times) covers which forms can be settled and which stay holes.
 
 ## A root module that calls child modules
 
-Plenty of configurations declare no resources at all at the root. They call a module per service, and every table and function is inside the child. A `source` that says which directory beside this one is followed and read as a module of its own, and everything the child declares gets `module.orders.` in front of its summary name and its deployable unit. [A module call this reader follows](./DESIGN.md#a-module-call-this-reader-follows) says what crosses between a call and the module it calls.
+Many configurations declare no resources at the root. They call one module per service, and every table and function is inside the child. When a `source` points at a directory next to this one, the reader follows it and reads that directory as a module of its own. Everything the child declares gets `module.orders.` in front of its summary name and its deployable unit. [A module call this reader follows](./DESIGN.md#a-module-call-this-reader-follows) covers what passes between a call and the module it calls.
 
 ## Several entries for one resource type
 
-A pack states more than one entry for a resource type when the provider spells it differently across versions. A resource that runs whichever engine one of its attributes picks needs no second entry: a storage entry's `storageSystem` is either a word or an attribute and a table of what each value there means, so `aws_db_instance` reads its `engine` and `google_sql_database_instance` reads its `database_version`. A table matches whole values by default, or the start of a value under `matches: "prefix"`, which is what Cloud SQL needs: `database_version` states an engine and a release together, `POSTGRES_15` and `MYSQL_8_0_31`, and the releases change every quarter.
+A pack declares more than one entry for a resource type when the provider spells it differently across versions. A resource whose engine is chosen by one of its attributes does not need a second entry. A storage entry's `storageSystem` is either a word, or an attribute plus a table of what each of its values means. So `aws_db_instance` reads its `engine`, and `google_sql_database_instance` reads its `database_version`. A table matches whole values by default, or the start of a value with `matches: "prefix"`. Cloud SQL needs the prefix form, because `database_version` gives an engine and a release together, as in `POSTGRES_15` and `MYSQL_8_0_31`, and the releases change every quarter.
 
-A value the pack does not list, and a value the configuration builds at deploy time, both leave the store with no engine on it. The resource is still read: the instance is deployed and it has a name, and the summary records a gap saying which attribute went unsettled. `appliesWhen` is for the other case, a resource that is not the thing the entry describes at all. A Firestore database in Datastore mode speaks a different API, so that entry gates on `type` and skips the resource outright.
+If the pack does not list a value, or the configuration builds the value at deploy time, the store gets no engine. The resource is still read, since the instance is deployed and has a name, and the summary records a gap saying which attribute was not settled. `appliesWhen` covers a different case: a resource that is not what the entry describes at all. A Firestore database in Datastore mode uses a different API, so that entry checks `type` and skips the resource entirely.
 
 ## What a deployable declares
 
@@ -92,27 +92,27 @@ resource "aws_lambda_function" "confirm" {
 }
 ```
 
-The contract lists every variable the process starts with, the ones the configuration sets and the ones the platform adds, and says which is which. `LOG_LEVEL` is recorded as the text it is set to. `ORDERS_TABLE` is set to another resource, so the contract records both what that resource states its name to be and which resource it was, and code that reads `process.env.ORDERS_TABLE` to address a table reaches the table through either.
+The contract lists every variable the process starts with, both the ones the configuration sets and the ones the platform adds, and marks which is which. `LOG_LEVEL` is recorded as the text it is set to. `ORDERS_TABLE` is set from another resource, so the contract records both the name that resource declares and which resource it was. Code that reads `process.env.ORDERS_TABLE` to address a table reaches the table through either.
 
-The unit is the resource label, `confirm`, rather than the name it deploys under. The label is what the rest of the configuration refers to it as, the way a logical id is in CloudFormation, so a variable pointing at the resource and the resource's own contract spell it the same way.
+The unit is the resource label, `confirm`, whatever name the function deploys under. The rest of the configuration refers to the resource by its label, the way CloudFormation uses a logical id, so a variable that points at the resource and the resource's own contract both use the same name.
 
-One resource deploys several processes where the provider says so. An ECS task definition is one contract per container, and each container gets only its own variables.
+One resource deploys several processes when the provider works that way. An ECS task definition produces one contract per container, and each container gets only its own variables.
 
-Every unsettled value in a contract is spelled the same way. An `image = var.image`, a `runtime` and a handler a variable supplies all come out as the pattern `{var.image}` rather than as the raw `${var.image}`, so nothing downstream has to know which field it is reading. A handler with a hole in it says nothing about which file the code is in, since splitting it at its last dot would pick a module nobody deploys.
+Every value that cannot be settled is written the same way in a contract. An `image = var.image`, a `runtime`, and a handler supplied by a variable all come out as a pattern such as `{var.image}`, without the `$` of the raw `${var.image}`, so nothing later has to know which field it is reading. A handler with a hole in it does not show which file the code is in, since splitting it at its last dot would pick a module nobody deploys.
 
-A configuration says which handler runs and never which directory the deployed artifact was built from, so the handler is all the checker has to go on. A container deployable states no handler at all, since its image was built somewhere else, and then the caller says where the code is with `--code-scope api/web=services/api`, or `codeScopes` on the read options. [Which code a deployable unit runs](./DESIGN.md#which-code-a-deployable-unit-runs) says what that writes, and what happens when two units are pointed at one directory.
+A configuration gives the handler that runs, but never the directory the deployed artifact was built from, so the handler is all the checker has to go on. A container deployable has no handler at all, since its image was built elsewhere. In that case the caller gives the location of the code with `--code-scope api/web=services/api`, or `codeScopes` in the read options. [Which code a deployable unit runs](./DESIGN.md#which-code-a-deployable-unit-runs) covers what that records, and what happens when two units point at one directory.
 
 ## What it will not tell you
 
-- **Only what a loaded pack describes.** A resource no entry covers, an IAM policy or a subnet, is skipped.
-- **A resource built with `for_each` or `count`** states one `resource` block for many tables, and this reads the block as written rather than working out what it expands to. A `dynamic` block inside a resource is expanded, since that one decides what a single deployed process is given.
-- **A name a variable supplies whole**, `name = var.table_name`, has no fixed text to pair on, so it records nothing rather than guessing.
-- **What a secret contains.** A variable a secret supplies records which resource supplies it and nothing else, since no configuration writes the contents down.
-- **Which source directory a deployable was built from.** Terraform builds the artifact outside the configuration, so a `filename` is a zip nothing in the run can open and a `source_dir` belongs to a data source this does not follow. `--code-scope` is how the caller supplies what the configuration never says.
+- **Anything no loaded pack describes.** A resource that no entry covers, such as an IAM policy or a subnet, is skipped.
+- **A resource built with `for_each` or `count`** has one `resource` block for many tables, and the reader reads the block as written without working out what it expands to. A `dynamic` block inside a resource is expanded, since it decides what a single deployed process is given.
+- **A name that comes entirely from a variable**, such as `name = var.table_name`, has no fixed text to pair on, so the reader records nothing instead of guessing.
+- **What a secret contains.** For a variable a secret supplies, the reader records which resource supplies it and nothing more, since no configuration writes the contents down.
+- **Which source directory a deployable was built from.** Terraform builds the artifact outside the configuration. A `filename` is a zip nothing in the run can open, and a `source_dir` belongs to a data source the reader does not follow. `--code-scope` is how the caller supplies what the configuration never states.
 
 ## 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.
+The package depends on `@suss/behavioral-ir` for the summaries it produces, and on `hcl2-parser` for reading HCL. The storage pass in `@suss/checker` pairs what code touches with what this reader declares.
 
 ## More
 

package/dist/index.cjs

@@ -592,9 +592,9 @@ var TokenReader = class {
     return this.readTerm();
   }
   /**
-   * A call where a comparison would be. Cloud Monitoring writes an SLO
-   * burn-rate condition that way, and the call says what the condition
-   * is about instead of any comparison.
+   * A call in place of a comparison. Cloud Monitoring writes an SLO
+   * burn-rate condition that way, and the call's arguments identify what
+   * the condition is about.
    */
   readCall() {
     const name = this.tokens[this.at];

package/dist/index.d.cts

@@ -1,28 +1,28 @@
 import { DeployableUnit, MessageBusTechnology, MetricValueShape, MetricAccumulation, BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
- * What a pack says about the resources one Terraform provider declares.
+ * The types a Terraform pack uses to describe the resources one 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.
+ * A provider defines its own resource types, and each version defines
+ * their attributes, so both belong in a pack and stay out of this
+ * reader. The reader walks HCL and matches resources. A pack describes
+ * what `aws_dynamodb_table` is and which provider versions that covers.
  *
- * 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.
+ * Every entry is data. When these types cannot describe a resource,
+ * widen them, so a pack never ships code the reader cannot inspect.
  */
 
 /**
- * An attribute whose value the pack translates into one of suss's own
- * words. The reader takes the value at `attribute` and looks it up in
- * `means`; a value the pack did not list says nothing, and so does one
- * the configuration builds at deploy time.
+ * An attribute whose value the pack translates into suss's own terms.
+ * The reader looks up the value at `attribute` in `means`. A value the
+ * pack did not list, or one the configuration builds at deploy time,
+ * maps to nothing.
  */
 interface AttributeMeaning<T extends string> {
-    /** The attribute path whose value says which one it is. */
+    /** The attribute path to read. */
     attribute: string;
-    /** What each value the provider can write there means. */
+    /** The suss term for each value the provider can write there. */
     means: Record<string, T>;
     /**
      * Whether a value has to equal a key of `means` or start with one.
@@ -30,45 +30,45 @@ interface AttributeMeaning<T extends string> {
      * and the releases change every quarter, so a pack lists the prefix.
      */
     matches?: "value" | "prefix";
-    /** What the resource means when it never set the attribute at all. */
+    /** The meaning to use when the resource does not set the attribute. */
     whenUnset?: T;
 }
 /** A store a caller addresses by container and key. */
 interface StorageResource {
     kind: "storage";
     /**
-     * Which store this is: dynamodb, s3. A resource that runs whichever
-     * engine one of its attributes picks says which attribute instead,
-     * and a value the pack does not list leaves the store with no engine
-     * on it rather than dropping the resource.
+     * The store, such as `aws.dynamodb` or `s3`. A resource whose engine
+     * depends on one of its attributes gives an AttributeMeaning instead.
+     * A value the pack does not list leaves the store with no engine, and
+     * the resource is still read.
      */
     storageSystem: string | AttributeMeaning<string>;
-    /** How a caller reaches it, when that is not the store's own name. */
+    /** How a caller reaches it, when that differs from the store's own name. */
     transport?: string;
     /**
-     * What the resource declares. The default, `"container"`, means the
-     * resource is the thing code addresses: code passes a bucket's name
-     * to `bucket()`, so the declared name and the accessed name meet.
-     * `"store"` means the resource only says the store exists. Code
-     * splits a Redis cluster into key namespaces, no attribute of the
-     * cluster lists them, so the summary gets no container name and
-     * claims no access. Any match on the cluster's own name would be a
-     * coincidence between a deployment name and a key prefix.
+     * What the resource declares. The default, `"container"`, means code
+     * addresses the resource directly: code passes a bucket's name to
+     * `bucket()`, so the declared name matches the accessed one. `"store"`
+     * means the resource only declares that the store exists. Code splits
+     * a Redis cluster into key namespaces that no attribute of the cluster
+     * lists, so the summary gets no container name and claims no access.
+     * A match on the cluster's own name would be a coincidence between a
+     * deployment name and a key prefix.
      */
     declares?: "container" | "store";
-    /** The attribute that says what the resource is called once deployed. */
+    /** The attribute that contains the resource's deployed name. */
     nameAttribute?: string;
     /**
-     * The attribute naming the namespace a container belongs to. A
+     * The attribute that contains the namespace a container belongs to. A
      * BigQuery table is always addressed through its dataset, so two
      * tables called `orders` in two datasets are two containers.
      */
     scopeAttribute?: 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. */
+    /** The attributes that list an item's key fields, in key order. */
     identifies?: string[];
-    /** Blocks that declare another way in, each keyed on its own fields. */
+    /** Blocks that declare another access path, each keyed on its own fields. */
     accessPathBlocks?: string[];
     /** The block that gives each field a type, and its two attributes. */
     fieldTypes?: {
@@ -77,35 +77,35 @@ interface StorageResource {
         typeAttribute: string;
     };
     /**
-     * An attribute stating every field as JSON, one object per field. A
-     * schema written this way is every field the item has, so reading one
-     * makes the contract exhaustive whatever `fieldSet` says.
+     * An attribute that lists every field as JSON, one object per field. A
+     * schema written this way lists every field the item has, so reading
+     * one makes the contract exhaustive regardless of `fieldSet`.
      */
     fieldsFromJson?: {
         /** The attribute whose value is a JSON list of field objects. */
         attribute: string;
-        /** The key of one entry that says what the field is called. */
+        /** The key in each entry that contains the field's name. */
         nameKey: string;
-        /** The key of one entry that gives the field its type. */
+        /** The key in each entry that contains the field's type. */
         typeKey?: string;
-        /** The key that says a field is always set, and the values that do. */
+        /** The key that marks a field as always set, and the values that do. */
         requires?: {
             key: string;
             values: 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.
+     * Which fields an access path can return. A DynamoDB index copies only
+     * part of an item, and a read of any other attribute returns nothing
+     * without an error, so the copied attributes are the index's complete
+     * field list.
      */
     serves?: {
-        /** The attribute that says which kind of copy it keeps. */
+        /** The attribute that contains the projection kind. */
         kindAttribute: string;
-        /** The attribute listing what it copies, for the kind that lists. */
+        /** The attribute listing the copied fields, for a kind that lists them. */
         fieldsAttribute: string;
-        /** The value of `kindAttribute` that means it copies the item. */
+        /** The `kindAttribute` value that means the whole item is copied. */
         everything: string;
     };
 }
@@ -116,46 +116,45 @@ interface MessageBusResource {
     nameAttribute?: string;
 }
 /**
- * How the deployed metric type is spelled, with each `{...}` standing
- * for the value at that attribute. A CloudWatch metric is identified by
- * its namespace and its name together, so a template says where both
- * come from: `"{metric_transformation.namespace}/{metric_transformation.name}"`.
- * A hole the resource leaves unset makes the whole identity unknown, so
- * the summary pairs with nothing rather than with a half-spelled name.
+ * The pattern of the deployed metric type, where each `{...}` is
+ * replaced by the value at that attribute path. A CloudWatch metric is
+ * identified by its namespace and its name together, so its template
+ * gives both: `"{metric_transformation.namespace}/{metric_transformation.name}"`.
+ * When the resource leaves one of those attributes unset, the whole
+ * identity is unknown, so the summary does not pair on a partial name.
  */
 type MetricTypeTemplate = string;
 /** A named series of measurements a resource declares. */
 interface MetricResource {
     kind: "metric";
-    /** Which system the series lives in: cloud-monitoring. */
+    /** The metrics system, such as `cloud-monitoring`. */
     metricSystem: string;
-    /** How the string both sides spell is built from the resource. */
+    /** How the identity both sides write is built from the resource. */
     metricTypeTemplate: MetricTypeTemplate;
-    /** Which attribute says whether one measurement is a number or a histogram. */
+    /** The attribute that decides whether a measurement is a number or a histogram. */
     values?: AttributeMeaning<MetricValueShape>;
-    /** Which attribute says what a measurement covers. */
+    /** The attribute that decides what one measurement covers. */
     accumulates?: AttributeMeaning<MetricAccumulation>;
 }
 /**
- * How a reading says which metric it is about. A CloudWatch alarm
- * writes the namespace and the name in attributes of its own; a Cloud
- * Monitoring condition states a query, and the metric is one value
- * inside it.
+ * Where a reading gives the metric it is about. A CloudWatch alarm
+ * writes the namespace and the name as attributes. A Cloud Monitoring
+ * condition writes a query, and the metric is one value inside it.
  */
 type MetricIdentity = {
     from: "attributes";
     template: MetricTypeTemplate;
 } | {
     from: "query";
-    /** The attribute whose query says which metric this is about. */
+    /** The attribute that contains the query. */
     attribute: string;
     /** The key inside that query whose value is the metric's type. */
     key: string;
 };
 /**
  * A resource that reads a metric another resource declares. One
- * resource usually states several readings, each in its own block and
- * each about its own metric, so each becomes a boundary of its own.
+ * resource often contains several readings, each in its own block and
+ * about its own metric, so each becomes its own boundary.
  */
 interface MetricReadingResource {
     kind: "metric-reading";
@@ -165,24 +164,24 @@ interface MetricReadingResource {
      * list means the resource is itself one reading.
      */
     readingBlocks: string[];
-    /** How the reading spells the metric it is about. */
+    /** Where the reading gives the metric it is about. */
     identifies: MetricIdentity;
     /**
-     * The attribute whose presence means the reading compares the series
-     * against a value of this shape. A condition states a threshold, so
-     * the number it compares against is the attribute being set at all.
+     * An attribute whose presence means the reading compares the series
+     * against a value of this shape. A condition that sets a threshold
+     * compares against a number, whatever the number is.
      */
     comparesTo?: {
         attribute: string;
         whenSet: MetricValueShape;
     };
-    /** Which attribute says what the reading reduces each window to first. */
+    /** The attribute that decides what the reading reduces each window to. */
     reducesTo?: AttributeMeaning<MetricValueShape>;
 }
 /**
- * Where a provider writes one process's environment. A map attribute
- * gives the names as its keys; repeated entries each say what one
- * variable is called and then what supplies it, a literal or a secret.
+ * Where a provider writes one process's environment: either a map
+ * attribute keyed by variable name, or repeated entries that each give
+ * one variable's name and its source, a literal or a secret.
  */
 type EnvDeclaration = {
     style: "map";
@@ -191,81 +190,80 @@ type EnvDeclaration = {
     style: "entries";
     /** The block one entry is written as, as a dotted path. */
     block: string;
-    /** The attribute stating what the variable is called. */
+    /** The attribute that contains the variable's name. */
     nameAttribute: string;
-    /** The attribute stating the value, for an entry that writes one. */
+    /** The attribute that contains the value, for an entry that writes one. */
     valueAttribute?: string;
-    /** The attribute stating which secret supplies the value. */
+    /** The attribute that contains the secret supplying the value. */
     secretAttribute?: string;
 };
 /**
- * How a platform spells the string that says which code it calls.
- * `"module.export"` is a module path and an exported name split at the
- * last dot, which is what Lambda takes. `"name"` is an exported name on
- * its own, which says nothing about which file it is in.
+ * How a platform writes the handler it calls. `"module.export"` is a
+ * module path and an exported name joined at the last dot, as Lambda
+ * takes it. `"name"` is an exported name alone, with no file.
  */
 type HandlerSpelling = "module.export" | "name";
-/** What the provider says one process runs. */
+/** Where the provider records the code one process runs. */
 interface DeployableCode {
-    /** The attribute that says which function the platform calls. */
+    /** The attribute that contains the function the platform calls. */
     handler?: {
         attribute: string;
         spelling: HandlerSpelling;
     };
-    /** The attribute that says which image a container runs. */
+    /** The attribute that contains the image a container runs. */
     imageAttribute?: string;
 }
 /** A resource that deploys several processes, each with its own environment. */
 interface DeployableContainers {
     /** The blocks one container is written inside, outermost first. */
     blocks: string[];
-    /** The attribute inside a container that says what it is called. */
+    /** The attribute inside a container that contains its name. */
     nameAttribute?: string;
 }
 /**
- * Something that gets deployed and runs: a function, a container, a
- * job. What it declares is the environment the process starts with, so
- * code reading a variable the deployment never sets is a defect either
- * side can be shown.
+ * Something that gets deployed and runs, such as a function, a
+ * container or a job. It declares the environment the process starts
+ * with, so suss can report code that reads a variable the deployment
+ * never sets.
  *
- * The unit is the resource's label rather than the name it deploys
- * under. The label is what the rest of the configuration refers to it
- * as, the way a logical id is in CloudFormation, and it is what a
- * variable pointing at the resource resolves to.
+ * The unit is keyed by the resource's label, and the deployed name is
+ * not used. The rest of the configuration refers to the resource by its
+ * label, as CloudFormation does with a logical id, and a variable that
+ * points at the resource resolves to it.
  */
 interface DeployableResource {
     kind: "deployable";
-    /** Which medium runs it, in the words a deployable unit is keyed by. */
+    /** What runs it, as a deployable unit's `deploymentTarget`. */
     deploymentTarget: DeployableUnit["deploymentTarget"];
     /** Where each process is written, for a resource that deploys several. */
     containers?: DeployableContainers;
     /** Where the environment is written, inside the process. */
     env?: EnvDeclaration[];
-    /** What the provider says the process runs. */
+    /** Where the provider records the code the process runs. */
     code?: DeployableCode;
-    /** The attribute stating the language runtime, verbatim. */
+    /** The attribute that contains the language runtime, copied as written. */
     runtimeAttribute?: string;
     /**
-     * Names the platform sets whatever the configuration says. An entry
-     * that states none takes the list for its deployment target, which
-     * is the one every other reader of that target uses. A product with
-     * a list of its own, Cloud Run against a bare container, states it.
+     * Variables the platform sets regardless of the configuration. An
+     * entry that leaves this out gets the list for its deployment target,
+     * which every other reader of that target uses. A product with its own
+     * list, such as Cloud Run, sets it here.
      */
     platformEnvVars?: readonly string[];
 }
 type TerraformResource = StorageResource | MessageBusResource | MetricResource | MetricReadingResource | DeployableResource;
 /** One resource type, as one version range of one provider declares it. */
 interface TerraformResourcePattern {
-    /** The resource type, spelled the way the provider spells it. */
+    /** The resource type, as the provider writes it. */
     resource: string;
     /**
      * An attribute that decides whether the entry describes the resource
-     * at all. A Firestore database in Datastore mode speaks a different
-     * API, so it is not the store the Firestore entry describes. A value
-     * outside `equals`, or one built at deploy time, means the resource
-     * is not read, rather than read as something it may not be.
-     * `whenUnset` says what an absent attribute means; the default is not
-     * to read the resource.
+     * at all. A Firestore database in Datastore mode uses a different
+     * API, so the Firestore entry does not describe it. A value outside
+     * `equals`, or one built at deploy time, means the resource is
+     * skipped, so it is never read as something it may not be.
+     * `whenUnset` gives what an absent attribute means; by default the
+     * resource is skipped.
      */
     appliesWhen?: {
         attribute: string;
@@ -277,7 +275,7 @@ interface TerraformResourcePattern {
      * 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.
+     * constraint is read by every entry, since nothing rules any out.
      */
     providerVersions: string;
     /** What the resource is, once read. */
@@ -297,16 +295,15 @@ interface TerraformPack {
 /**
  * A filter written as comparisons joined by AND and OR.
  *
- * Several cloud APIs take a selector as one string in this shape:
+ * Several cloud APIs take a selector as one string such as
  * `metric.type = "x" AND resource.type = "y"`, with quoted or bare
  * values, parentheses, NOT, and terms written next to each other for
  * AND. A resource that reads what another resource declares usually
- * says which one inside such a string, so reading the string is how
- * this reader finds out what a resource refers to.
+ * identifies it inside such a string, so the reader parses the string.
  *
- * A pack says which key it wants. This file knows the grammar and no
- * provider's key names. What comes back is a tree, since OR and NOT
- * change what a term claims and only the caller can judge that.
+ * The pack gives the key to look for, and this file contains only the
+ * grammar. It returns a tree, because OR and NOT change what a term
+ * means and only the caller can decide how to treat that.
  */
 /** One comparison, as the filter writes it. */
 interface FilterTerm {
@@ -322,7 +319,7 @@ interface FilterTerm {
     /** The right side, with the quotes taken off a quoted value. */
     value: string;
 }
-/** A call standing where a comparison would, with its arguments. */
+/** A function call in place of a comparison, with its arguments. */
 interface FilterCall {
     type: "call";
     name: string;
@@ -336,7 +333,7 @@ type FilterQuery = FilterTerm | FilterCall | {
     type: "negation";
     operand: FilterQuery;
 };
-/** A filter nobody could read says why, rather than reading as empty. */
+/** A parse failure includes the reason, so it is never mistaken for an empty filter. */
 type FilterParse = {
     ok: true;
     query: FilterQuery;
@@ -348,63 +345,61 @@ type FilterParse = {
 declare function filterValuesFor(query: FilterQuery, key: string): string[];
 /** Every comparison in the tree, in the order the filter writes them. */
 declare function filterTerms(query: FilterQuery): FilterTerm[];
-/** Every call in the tree, for a caller that reads one of them. */
+/** Every call in the tree, in the order the filter writes them. */
 declare function filterCalls(query: FilterQuery): FilterCall[];
-/** Read one filter string, or say what stopped the reading. */
+/** Parses one filter string, or returns what stopped the parse. */
 declare function parseFilterQuery(source: string): FilterParse;
 
 /**
  * An attribute whose value is JSON.
  *
- * Several providers take a structure as a string rather than as blocks:
- * a BigQuery table's schema, an ECS task's container definitions, an
- * IAM policy document. Terraform gives an author two ways to write one,
- * a literal string (usually a heredoc) and `jsonencode` over an HCL
- * value, and the two arrive at this reader looking nothing alike. This
- * turns both into the value the provider will see.
+ * Several providers take a structure as a JSON string instead of as
+ * blocks, such as a BigQuery table's schema or an ECS task's container
+ * definitions. An author can write one as a literal string, usually a
+ * heredoc, or as `jsonencode` over an HCL value, and the parser returns
+ * the two very differently. This module turns both into the value the
+ * provider receives.
  *
- * A schema a file or a variable supplies is not written down anywhere
- * this can read, so it comes back as null and the caller records
- * nothing rather than guessing.
+ * A value that a file or a variable supplies is not written in the
+ * configuration, so it comes back as null and the caller records nothing.
  */
 /**
- * The value an attribute states as JSON, or null when the attribute is
- * missing or states something only a deploy can settle.
+ * The value an attribute writes as JSON, or null when the attribute is
+ * missing or its value is known only at deploy time.
  */
 declare function jsonAttributeValue(value: unknown): unknown;
 
 /**
  * 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
+ * This module reads HCL and matches it against the packs a run loads. A
+ * pack describes what `aws_dynamodb_table` is, and 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. An interpolation
- * that refers to another resource in the same configuration resolves
- * instead, since that resource states the value. The README says how a
- * block that HCL states once or many times is read.
+ * 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. A reference to another resource in the
+ * same configuration resolves instead, since that resource writes the
+ * value. DESIGN.md covers references, module calls and repeated blocks.
  */
 
 interface TerraformReadOptions {
-    /** The packs that say what this configuration's resources are. */
+    /** The packs that describe this configuration's resources. */
     packs: TerraformPack[];
     /**
-     * The directory each deployable unit's code is in, by the instance
-     * name the unit is keyed by. A configuration says which handler runs
-     * and never which directory the artifact was built from, so a
-     * container whose image is built elsewhere has no code at all until
-     * somebody says where it is.
+     * The directory each deployable unit's code is in, by the unit's
+     * instance name. A configuration gives the handler that runs but never
+     * the directory the artifact was built from, so a container whose
+     * image is built elsewhere has no code until the caller gives its
+     * location.
      */
     codeScopes?: Record<string, string>;
 }
 /** 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, and
+ * Reads one `.tf` file, or every one directly inside a directory, and
  * every local module the configuration calls.
  */
 declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];

package/dist/index.d.ts

@@ -1,28 +1,28 @@
 import { DeployableUnit, MessageBusTechnology, MetricValueShape, MetricAccumulation, BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
- * What a pack says about the resources one Terraform provider declares.
+ * The types a Terraform pack uses to describe the resources one 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.
+ * A provider defines its own resource types, and each version defines
+ * their attributes, so both belong in a pack and stay out of this
+ * reader. The reader walks HCL and matches resources. A pack describes
+ * what `aws_dynamodb_table` is and which provider versions that covers.
  *
- * 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.
+ * Every entry is data. When these types cannot describe a resource,
+ * widen them, so a pack never ships code the reader cannot inspect.
  */
 
 /**
- * An attribute whose value the pack translates into one of suss's own
- * words. The reader takes the value at `attribute` and looks it up in
- * `means`; a value the pack did not list says nothing, and so does one
- * the configuration builds at deploy time.
+ * An attribute whose value the pack translates into suss's own terms.
+ * The reader looks up the value at `attribute` in `means`. A value the
+ * pack did not list, or one the configuration builds at deploy time,
+ * maps to nothing.
  */
 interface AttributeMeaning<T extends string> {
-    /** The attribute path whose value says which one it is. */
+    /** The attribute path to read. */
     attribute: string;
-    /** What each value the provider can write there means. */
+    /** The suss term for each value the provider can write there. */
     means: Record<string, T>;
     /**
      * Whether a value has to equal a key of `means` or start with one.
@@ -30,45 +30,45 @@ interface AttributeMeaning<T extends string> {
      * and the releases change every quarter, so a pack lists the prefix.
      */
     matches?: "value" | "prefix";
-    /** What the resource means when it never set the attribute at all. */
+    /** The meaning to use when the resource does not set the attribute. */
     whenUnset?: T;
 }
 /** A store a caller addresses by container and key. */
 interface StorageResource {
     kind: "storage";
     /**
-     * Which store this is: dynamodb, s3. A resource that runs whichever
-     * engine one of its attributes picks says which attribute instead,
-     * and a value the pack does not list leaves the store with no engine
-     * on it rather than dropping the resource.
+     * The store, such as `aws.dynamodb` or `s3`. A resource whose engine
+     * depends on one of its attributes gives an AttributeMeaning instead.
+     * A value the pack does not list leaves the store with no engine, and
+     * the resource is still read.
      */
     storageSystem: string | AttributeMeaning<string>;
-    /** How a caller reaches it, when that is not the store's own name. */
+    /** How a caller reaches it, when that differs from the store's own name. */
     transport?: string;
     /**
-     * What the resource declares. The default, `"container"`, means the
-     * resource is the thing code addresses: code passes a bucket's name
-     * to `bucket()`, so the declared name and the accessed name meet.
-     * `"store"` means the resource only says the store exists. Code
-     * splits a Redis cluster into key namespaces, no attribute of the
-     * cluster lists them, so the summary gets no container name and
-     * claims no access. Any match on the cluster's own name would be a
-     * coincidence between a deployment name and a key prefix.
+     * What the resource declares. The default, `"container"`, means code
+     * addresses the resource directly: code passes a bucket's name to
+     * `bucket()`, so the declared name matches the accessed one. `"store"`
+     * means the resource only declares that the store exists. Code splits
+     * a Redis cluster into key namespaces that no attribute of the cluster
+     * lists, so the summary gets no container name and claims no access.
+     * A match on the cluster's own name would be a coincidence between a
+     * deployment name and a key prefix.
      */
     declares?: "container" | "store";
-    /** The attribute that says what the resource is called once deployed. */
+    /** The attribute that contains the resource's deployed name. */
     nameAttribute?: string;
     /**
-     * The attribute naming the namespace a container belongs to. A
+     * The attribute that contains the namespace a container belongs to. A
      * BigQuery table is always addressed through its dataset, so two
      * tables called `orders` in two datasets are two containers.
      */
     scopeAttribute?: 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. */
+    /** The attributes that list an item's key fields, in key order. */
     identifies?: string[];
-    /** Blocks that declare another way in, each keyed on its own fields. */
+    /** Blocks that declare another access path, each keyed on its own fields. */
     accessPathBlocks?: string[];
     /** The block that gives each field a type, and its two attributes. */
     fieldTypes?: {
@@ -77,35 +77,35 @@ interface StorageResource {
         typeAttribute: string;
     };
     /**
-     * An attribute stating every field as JSON, one object per field. A
-     * schema written this way is every field the item has, so reading one
-     * makes the contract exhaustive whatever `fieldSet` says.
+     * An attribute that lists every field as JSON, one object per field. A
+     * schema written this way lists every field the item has, so reading
+     * one makes the contract exhaustive regardless of `fieldSet`.
      */
     fieldsFromJson?: {
         /** The attribute whose value is a JSON list of field objects. */
         attribute: string;
-        /** The key of one entry that says what the field is called. */
+        /** The key in each entry that contains the field's name. */
         nameKey: string;
-        /** The key of one entry that gives the field its type. */
+        /** The key in each entry that contains the field's type. */
         typeKey?: string;
-        /** The key that says a field is always set, and the values that do. */
+        /** The key that marks a field as always set, and the values that do. */
         requires?: {
             key: string;
             values: 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.
+     * Which fields an access path can return. A DynamoDB index copies only
+     * part of an item, and a read of any other attribute returns nothing
+     * without an error, so the copied attributes are the index's complete
+     * field list.
      */
     serves?: {
-        /** The attribute that says which kind of copy it keeps. */
+        /** The attribute that contains the projection kind. */
         kindAttribute: string;
-        /** The attribute listing what it copies, for the kind that lists. */
+        /** The attribute listing the copied fields, for a kind that lists them. */
         fieldsAttribute: string;
-        /** The value of `kindAttribute` that means it copies the item. */
+        /** The `kindAttribute` value that means the whole item is copied. */
         everything: string;
     };
 }
@@ -116,46 +116,45 @@ interface MessageBusResource {
     nameAttribute?: string;
 }
 /**
- * How the deployed metric type is spelled, with each `{...}` standing
- * for the value at that attribute. A CloudWatch metric is identified by
- * its namespace and its name together, so a template says where both
- * come from: `"{metric_transformation.namespace}/{metric_transformation.name}"`.
- * A hole the resource leaves unset makes the whole identity unknown, so
- * the summary pairs with nothing rather than with a half-spelled name.
+ * The pattern of the deployed metric type, where each `{...}` is
+ * replaced by the value at that attribute path. A CloudWatch metric is
+ * identified by its namespace and its name together, so its template
+ * gives both: `"{metric_transformation.namespace}/{metric_transformation.name}"`.
+ * When the resource leaves one of those attributes unset, the whole
+ * identity is unknown, so the summary does not pair on a partial name.
  */
 type MetricTypeTemplate = string;
 /** A named series of measurements a resource declares. */
 interface MetricResource {
     kind: "metric";
-    /** Which system the series lives in: cloud-monitoring. */
+    /** The metrics system, such as `cloud-monitoring`. */
     metricSystem: string;
-    /** How the string both sides spell is built from the resource. */
+    /** How the identity both sides write is built from the resource. */
     metricTypeTemplate: MetricTypeTemplate;
-    /** Which attribute says whether one measurement is a number or a histogram. */
+    /** The attribute that decides whether a measurement is a number or a histogram. */
     values?: AttributeMeaning<MetricValueShape>;
-    /** Which attribute says what a measurement covers. */
+    /** The attribute that decides what one measurement covers. */
     accumulates?: AttributeMeaning<MetricAccumulation>;
 }
 /**
- * How a reading says which metric it is about. A CloudWatch alarm
- * writes the namespace and the name in attributes of its own; a Cloud
- * Monitoring condition states a query, and the metric is one value
- * inside it.
+ * Where a reading gives the metric it is about. A CloudWatch alarm
+ * writes the namespace and the name as attributes. A Cloud Monitoring
+ * condition writes a query, and the metric is one value inside it.
  */
 type MetricIdentity = {
     from: "attributes";
     template: MetricTypeTemplate;
 } | {
     from: "query";
-    /** The attribute whose query says which metric this is about. */
+    /** The attribute that contains the query. */
     attribute: string;
     /** The key inside that query whose value is the metric's type. */
     key: string;
 };
 /**
  * A resource that reads a metric another resource declares. One
- * resource usually states several readings, each in its own block and
- * each about its own metric, so each becomes a boundary of its own.
+ * resource often contains several readings, each in its own block and
+ * about its own metric, so each becomes its own boundary.
  */
 interface MetricReadingResource {
     kind: "metric-reading";
@@ -165,24 +164,24 @@ interface MetricReadingResource {
      * list means the resource is itself one reading.
      */
     readingBlocks: string[];
-    /** How the reading spells the metric it is about. */
+    /** Where the reading gives the metric it is about. */
     identifies: MetricIdentity;
     /**
-     * The attribute whose presence means the reading compares the series
-     * against a value of this shape. A condition states a threshold, so
-     * the number it compares against is the attribute being set at all.
+     * An attribute whose presence means the reading compares the series
+     * against a value of this shape. A condition that sets a threshold
+     * compares against a number, whatever the number is.
      */
     comparesTo?: {
         attribute: string;
         whenSet: MetricValueShape;
     };
-    /** Which attribute says what the reading reduces each window to first. */
+    /** The attribute that decides what the reading reduces each window to. */
     reducesTo?: AttributeMeaning<MetricValueShape>;
 }
 /**
- * Where a provider writes one process's environment. A map attribute
- * gives the names as its keys; repeated entries each say what one
- * variable is called and then what supplies it, a literal or a secret.
+ * Where a provider writes one process's environment: either a map
+ * attribute keyed by variable name, or repeated entries that each give
+ * one variable's name and its source, a literal or a secret.
  */
 type EnvDeclaration = {
     style: "map";
@@ -191,81 +190,80 @@ type EnvDeclaration = {
     style: "entries";
     /** The block one entry is written as, as a dotted path. */
     block: string;
-    /** The attribute stating what the variable is called. */
+    /** The attribute that contains the variable's name. */
     nameAttribute: string;
-    /** The attribute stating the value, for an entry that writes one. */
+    /** The attribute that contains the value, for an entry that writes one. */
     valueAttribute?: string;
-    /** The attribute stating which secret supplies the value. */
+    /** The attribute that contains the secret supplying the value. */
     secretAttribute?: string;
 };
 /**
- * How a platform spells the string that says which code it calls.
- * `"module.export"` is a module path and an exported name split at the
- * last dot, which is what Lambda takes. `"name"` is an exported name on
- * its own, which says nothing about which file it is in.
+ * How a platform writes the handler it calls. `"module.export"` is a
+ * module path and an exported name joined at the last dot, as Lambda
+ * takes it. `"name"` is an exported name alone, with no file.
  */
 type HandlerSpelling = "module.export" | "name";
-/** What the provider says one process runs. */
+/** Where the provider records the code one process runs. */
 interface DeployableCode {
-    /** The attribute that says which function the platform calls. */
+    /** The attribute that contains the function the platform calls. */
     handler?: {
         attribute: string;
         spelling: HandlerSpelling;
     };
-    /** The attribute that says which image a container runs. */
+    /** The attribute that contains the image a container runs. */
     imageAttribute?: string;
 }
 /** A resource that deploys several processes, each with its own environment. */
 interface DeployableContainers {
     /** The blocks one container is written inside, outermost first. */
     blocks: string[];
-    /** The attribute inside a container that says what it is called. */
+    /** The attribute inside a container that contains its name. */
     nameAttribute?: string;
 }
 /**
- * Something that gets deployed and runs: a function, a container, a
- * job. What it declares is the environment the process starts with, so
- * code reading a variable the deployment never sets is a defect either
- * side can be shown.
+ * Something that gets deployed and runs, such as a function, a
+ * container or a job. It declares the environment the process starts
+ * with, so suss can report code that reads a variable the deployment
+ * never sets.
  *
- * The unit is the resource's label rather than the name it deploys
- * under. The label is what the rest of the configuration refers to it
- * as, the way a logical id is in CloudFormation, and it is what a
- * variable pointing at the resource resolves to.
+ * The unit is keyed by the resource's label, and the deployed name is
+ * not used. The rest of the configuration refers to the resource by its
+ * label, as CloudFormation does with a logical id, and a variable that
+ * points at the resource resolves to it.
  */
 interface DeployableResource {
     kind: "deployable";
-    /** Which medium runs it, in the words a deployable unit is keyed by. */
+    /** What runs it, as a deployable unit's `deploymentTarget`. */
     deploymentTarget: DeployableUnit["deploymentTarget"];
     /** Where each process is written, for a resource that deploys several. */
     containers?: DeployableContainers;
     /** Where the environment is written, inside the process. */
     env?: EnvDeclaration[];
-    /** What the provider says the process runs. */
+    /** Where the provider records the code the process runs. */
     code?: DeployableCode;
-    /** The attribute stating the language runtime, verbatim. */
+    /** The attribute that contains the language runtime, copied as written. */
     runtimeAttribute?: string;
     /**
-     * Names the platform sets whatever the configuration says. An entry
-     * that states none takes the list for its deployment target, which
-     * is the one every other reader of that target uses. A product with
-     * a list of its own, Cloud Run against a bare container, states it.
+     * Variables the platform sets regardless of the configuration. An
+     * entry that leaves this out gets the list for its deployment target,
+     * which every other reader of that target uses. A product with its own
+     * list, such as Cloud Run, sets it here.
      */
     platformEnvVars?: readonly string[];
 }
 type TerraformResource = StorageResource | MessageBusResource | MetricResource | MetricReadingResource | DeployableResource;
 /** One resource type, as one version range of one provider declares it. */
 interface TerraformResourcePattern {
-    /** The resource type, spelled the way the provider spells it. */
+    /** The resource type, as the provider writes it. */
     resource: string;
     /**
      * An attribute that decides whether the entry describes the resource
-     * at all. A Firestore database in Datastore mode speaks a different
-     * API, so it is not the store the Firestore entry describes. A value
-     * outside `equals`, or one built at deploy time, means the resource
-     * is not read, rather than read as something it may not be.
-     * `whenUnset` says what an absent attribute means; the default is not
-     * to read the resource.
+     * at all. A Firestore database in Datastore mode uses a different
+     * API, so the Firestore entry does not describe it. A value outside
+     * `equals`, or one built at deploy time, means the resource is
+     * skipped, so it is never read as something it may not be.
+     * `whenUnset` gives what an absent attribute means; by default the
+     * resource is skipped.
      */
     appliesWhen?: {
         attribute: string;
@@ -277,7 +275,7 @@ interface TerraformResourcePattern {
      * 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.
+     * constraint is read by every entry, since nothing rules any out.
      */
     providerVersions: string;
     /** What the resource is, once read. */
@@ -297,16 +295,15 @@ interface TerraformPack {
 /**
  * A filter written as comparisons joined by AND and OR.
  *
- * Several cloud APIs take a selector as one string in this shape:
+ * Several cloud APIs take a selector as one string such as
  * `metric.type = "x" AND resource.type = "y"`, with quoted or bare
  * values, parentheses, NOT, and terms written next to each other for
  * AND. A resource that reads what another resource declares usually
- * says which one inside such a string, so reading the string is how
- * this reader finds out what a resource refers to.
+ * identifies it inside such a string, so the reader parses the string.
  *
- * A pack says which key it wants. This file knows the grammar and no
- * provider's key names. What comes back is a tree, since OR and NOT
- * change what a term claims and only the caller can judge that.
+ * The pack gives the key to look for, and this file contains only the
+ * grammar. It returns a tree, because OR and NOT change what a term
+ * means and only the caller can decide how to treat that.
  */
 /** One comparison, as the filter writes it. */
 interface FilterTerm {
@@ -322,7 +319,7 @@ interface FilterTerm {
     /** The right side, with the quotes taken off a quoted value. */
     value: string;
 }
-/** A call standing where a comparison would, with its arguments. */
+/** A function call in place of a comparison, with its arguments. */
 interface FilterCall {
     type: "call";
     name: string;
@@ -336,7 +333,7 @@ type FilterQuery = FilterTerm | FilterCall | {
     type: "negation";
     operand: FilterQuery;
 };
-/** A filter nobody could read says why, rather than reading as empty. */
+/** A parse failure includes the reason, so it is never mistaken for an empty filter. */
 type FilterParse = {
     ok: true;
     query: FilterQuery;
@@ -348,63 +345,61 @@ type FilterParse = {
 declare function filterValuesFor(query: FilterQuery, key: string): string[];
 /** Every comparison in the tree, in the order the filter writes them. */
 declare function filterTerms(query: FilterQuery): FilterTerm[];
-/** Every call in the tree, for a caller that reads one of them. */
+/** Every call in the tree, in the order the filter writes them. */
 declare function filterCalls(query: FilterQuery): FilterCall[];
-/** Read one filter string, or say what stopped the reading. */
+/** Parses one filter string, or returns what stopped the parse. */
 declare function parseFilterQuery(source: string): FilterParse;
 
 /**
  * An attribute whose value is JSON.
  *
- * Several providers take a structure as a string rather than as blocks:
- * a BigQuery table's schema, an ECS task's container definitions, an
- * IAM policy document. Terraform gives an author two ways to write one,
- * a literal string (usually a heredoc) and `jsonencode` over an HCL
- * value, and the two arrive at this reader looking nothing alike. This
- * turns both into the value the provider will see.
+ * Several providers take a structure as a JSON string instead of as
+ * blocks, such as a BigQuery table's schema or an ECS task's container
+ * definitions. An author can write one as a literal string, usually a
+ * heredoc, or as `jsonencode` over an HCL value, and the parser returns
+ * the two very differently. This module turns both into the value the
+ * provider receives.
  *
- * A schema a file or a variable supplies is not written down anywhere
- * this can read, so it comes back as null and the caller records
- * nothing rather than guessing.
+ * A value that a file or a variable supplies is not written in the
+ * configuration, so it comes back as null and the caller records nothing.
  */
 /**
- * The value an attribute states as JSON, or null when the attribute is
- * missing or states something only a deploy can settle.
+ * The value an attribute writes as JSON, or null when the attribute is
+ * missing or its value is known only at deploy time.
  */
 declare function jsonAttributeValue(value: unknown): unknown;
 
 /**
  * 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
+ * This module reads HCL and matches it against the packs a run loads. A
+ * pack describes what `aws_dynamodb_table` is, and 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. An interpolation
- * that refers to another resource in the same configuration resolves
- * instead, since that resource states the value. The README says how a
- * block that HCL states once or many times is read.
+ * 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. A reference to another resource in the
+ * same configuration resolves instead, since that resource writes the
+ * value. DESIGN.md covers references, module calls and repeated blocks.
  */
 
 interface TerraformReadOptions {
-    /** The packs that say what this configuration's resources are. */
+    /** The packs that describe this configuration's resources. */
     packs: TerraformPack[];
     /**
-     * The directory each deployable unit's code is in, by the instance
-     * name the unit is keyed by. A configuration says which handler runs
-     * and never which directory the artifact was built from, so a
-     * container whose image is built elsewhere has no code at all until
-     * somebody says where it is.
+     * The directory each deployable unit's code is in, by the unit's
+     * instance name. A configuration gives the handler that runs but never
+     * the directory the artifact was built from, so a container whose
+     * image is built elsewhere has no code until the caller gives its
+     * location.
      */
     codeScopes?: Record<string, string>;
 }
 /** 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, and
+ * Reads one `.tf` file, or every one directly inside a directory, and
  * every local module the configuration calls.
  */
 declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];

package/dist/index.js

@@ -563,9 +563,9 @@ var TokenReader = class {
     return this.readTerm();
   }
   /**
-   * A call where a comparison would be. Cloud Monitoring writes an SLO
-   * burn-rate condition that way, and the call says what the condition
-   * is about instead of any comparison.
+   * A call in place of a comparison. Cloud Monitoring writes an SLO
+   * burn-rate condition that way, and the call's arguments identify what
+   * the condition is about.
    */
   readCall() {
     const name = this.tokens[this.at];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-terraform",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "type": "module",
   "description": "Read the storage a Terraform configuration declares and check it against the code that reads and writes those tables.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/terraform#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,7 +47,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.1",
+    "@suss/behavioral-ir": "0.34.0",
     "hcl2-parser": "^1.0.3",
     "semver": "^7.6.0"
   },