@suss/terraform-gcp 0.33.0 → 0.34.0

package/README.md

@@ -1,12 +1,12 @@
 # @suss/terraform-gcp
 
-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.
 
-Says what Google Cloud's Terraform provider declares, for `@suss/contract-terraform` to read.
+This pack declares what the Google Cloud Terraform provider's resources are, for `@suss/contract-terraform` to read.
 
 ## What this package is
 
-A pack, and nothing but entries. Each one says what a resource is, and what its own words mean in the terms suss compares boundaries in.
+A pack made only of entries. Each entry declares what a resource is, and translates the resource's own terms into the ones suss compares boundaries in.
 
 ```ts
 import { terraformFileToSummaries } from "@suss/contract-terraform";
@@ -17,7 +17,7 @@ const summaries = terraformFileToSummaries("infra/terraform/monitoring", {
 });
 ```
 
-`suss contract --from terraform <path>` loads the entries for you. Nothing here runs at check time: the summaries contain what a metric measures and what a reading needs, and `checkMetric` in `@suss/checker` compares them, so `suss check --dir` over a folder of summaries reports the pair below with no pack loaded.
+`suss contract --from terraform <path>` loads the entries for you. Nothing here runs at check time. The summaries contain what a metric measures and what a reading needs, and `checkMetric` in `@suss/checker` compares them. So `suss check --dir` over a folder of summaries reports the pair described below without loading any pack.
 
 ## What it reads today
 
@@ -41,11 +41,11 @@ const summaries = terraformFileToSummaries("infra/terraform/monitoring", {
 
 Everything else a configuration declares is skipped.
 
-A bucket pairs by name: `@suss/framework-gcs` records the bucket an access reaches, and the `name` attribute is the same string, so `suss check` compares the two sides. A Memorystore instance does not: code addresses Redis by key namespace, no attribute of the instance declares one, and a match on the instance's own name would be a coincidence, so the summary declares the store with no container name and the storage check claims no access for it. The `@suss/terraform-aws` DESIGN walks through the same decision for ElastiCache. Spanner, Firestore and Cloud SQL are the same case: the tables or collections are inside the database, and nothing on the resource lists them.
+A bucket pairs by name. `@suss/framework-gcs` records the bucket an access reaches, and the `name` attribute is the same string, so `suss check` compares the two sides. A Memorystore instance does not pair. Code addresses Redis by key namespace, no attribute of the instance declares one, and a match on the instance's own name would be a coincidence. So the summary declares the store with no container name, and the storage check claims no access for it. The DESIGN notes in `@suss/terraform-aws` go through the same decision for ElastiCache. Spanner, Firestore and Cloud SQL are the same case: the tables or collections are inside the database, and nothing on the resource lists them.
 
-A BigQuery table is the one resource here with a field contract, since a query against it reads named columns. A Cloud Run service, a job and a function each declare the environment their containers start with. A Pub/Sub topic and subscription pair with nothing yet, because no code pack records a publish or a subscribe. [What each entry decided](./DESIGN.md) says how each of those is read.
+A BigQuery table is the only resource here with a field contract, since a query against it reads named columns. A Cloud Run service, a job and a function each declare the environment their containers start with. A Pub/Sub topic and subscription do not pair with anything yet, because no code pack records a publish or a subscribe. [Why each entry reads what it reads](./DESIGN.md) explains how each of those is read.
 
-## The pair the provider refuses
+## A pair the provider rejects at apply time
 
 A log-based metric can declare that each measurement is a histogram of buckets:
 
@@ -70,32 +70,32 @@ condition_threshold {
 }
 ```
 
-Both blocks are well formed, `terraform validate` and `terraform plan` both pass, and the apply fails minutes in: a distribution has no single value to compare, and Cloud Monitoring wants an aligner such as `ALIGN_PERCENTILE_95` to reduce each window to one number first.
+Both blocks are well formed, and `terraform validate` and `terraform plan` both pass. Then the apply fails several minutes in. A distribution has no single value to compare, and Cloud Monitoring needs an aligner such as `ALIGN_PERCENTILE_95` to reduce each window to one number first.
 
-The entries say that `value_type = "DISTRIBUTION"` means the measurements are a histogram, that a `threshold_value` means the condition compares against a single number, and that the four percentile aligners are the ones that reduce a window to a number. `checkMetric` puts those together and reports the pair as a `boundaryShapeMismatch` at error severity, naming `aggregations.per_series_aligner` and the four values that would fix it.
+The entries declare three things: `value_type = "DISTRIBUTION"` means the measurements are a histogram, a `threshold_value` means the condition compares against a single number, and the four percentile aligners are the ones that reduce a window to a number. `checkMetric` combines those and reports the pair as a `boundaryShapeMismatch` at error severity. The finding points at `aggregations.per_series_aligner` and lists the four values that would fix it.
 
-A condition that states one of the percentile aligners is left alone, as is a condition on a metric declared as `INT64` or `DOUBLE`.
+A condition that sets one of the percentile aligners is left alone, and so is a condition on a metric declared as `INT64` or `DOUBLE`.
 
 ## What it will not tell you
 
-- **A condition about a metric nothing in the run declares** says nothing. Most alerts watch metrics the platform publishes, and a metric declared in a module this run did not read looks the same from here. The pairing pass reports a boundary with one side missing.
-- **A condition that states no `metric.type`** leaves the condition with no metric type on it, so it pairs with nothing rather than pairing with the wrong thing. An SLO burn-rate condition is written as a call rather than a comparison, and it is about an objective rather than a metric, so it lands here.
-- **A metric the platform publishes**, `run.googleapis.com/request_latencies` and everything like it, states its value type in Google's documentation rather than in any configuration. Judging a condition on one of those needs a catalog this does not ship.
-- **A `BOOL`, `STRING`, or `MONEY` metric** is left out of the value-type table, because none of suss's words describe one, and a metric this pack says nothing about is compared against nothing.
-- **`for_each` and `count`** state one block for many resources, and the reader takes the block as written.
-- **`google_sql_database`**, the named database inside a Cloud SQL instance, states no engine of its own. Which store it is lives on the instance its `instance` attribute points at, and an entry has no way to read an attribute through a reference to another resource, so the database goes unread and the instance is what declares the store.
-- **`google_monitoring_uptime_check_config`** is a probe rather than a reading: it makes its own requests on a schedule and publishes a result, so it never reads a metric type back and `checkMetric` has nothing to compare. It would fit a kind for a synthetic check, which suss does not have.
-- **A Spanner database's `ddl`** statements state the tables, and reading SQL out of a Terraform attribute is a job for the SQL readers rather than for this pack.
-- **A Firestore database in Datastore mode** speaks a different API from the Firestore one, so the entry's gate turns it down rather than reading it as something it may not be.
+- **A condition about a metric that nothing in the run declares** produces nothing. Most alerts watch metrics the platform publishes, and from here a metric declared in a module this run did not read looks the same. The pairing pass reports a boundary with one side missing.
+- **A condition that does not give a `metric.type`** has no metric type on it, so it does not pair with anything and cannot pair with the wrong thing. An SLO burn-rate condition is written as a call instead of a comparison, and is about an objective instead of a metric, so it ends up in this case.
+- **A metric the platform publishes**, such as `run.googleapis.com/request_latencies`, has its value type in Google's documentation and not in any configuration. Judging a condition on one of those needs a catalog that this pack does not include.
+- **A `BOOL`, `STRING` or `MONEY` metric** is left out of the value-type table, because suss has no term that describes one, and a metric this pack does not describe is not compared against anything.
+- **`for_each` and `count`** use one block for many resources, and the reader takes the block as written.
+- **`google_sql_database`**, the named database inside a Cloud SQL instance, has no engine of its own. The engine is on the instance its `instance` attribute points at, and an entry cannot read an attribute through a reference to another resource. So the database is not read, and the instance is what declares the store.
+- **`google_monitoring_uptime_check_config`** is a probe, and does not read a metric. It makes its own requests on a schedule and publishes a result, so it never reads a metric type back and `checkMetric` has nothing to compare. It would fit a kind for synthetic checks, which suss does not have.
+- **A Spanner database's `ddl`** statements declare the tables, and reading SQL out of a Terraform attribute is a job for the SQL readers, outside this pack.
+- **A Firestore database in Datastore mode** uses a different API from Firestore's, so the entry's check turns it away instead of reading it as something it may not be.
 
 ## How the identity is built
 
-Cloud Monitoring puts every metric a project defines for itself under `logging.googleapis.com/user/`, and the alert spells that whole string, so the whole string is the identity the two sides share. A name built at deploy time keeps its hole: `name = "${var.environment}-refusals"` becomes `logging.googleapis.com/user/{var.environment}-refusals`, and a filter that interpolates the same variable is spelled the same way.
+Cloud Monitoring puts every metric a project defines for itself under `logging.googleapis.com/user/`, and the alert writes out that whole string. So the whole string is the identity both sides share. A name built at deploy time keeps its hole: `name = "${var.environment}-refusals"` becomes `logging.googleapis.com/user/{var.environment}-refusals`, and a filter that interpolates the same variable comes out the same way.
 
 ## Where it fits in suss
 
-Depends on `@suss/contract-terraform` for the shape of an entry and on `@suss/behavioral-ir` for the words a translation table is allowed to use. The reader knows nothing about Google, and neither does the checker: Google's vocabulary starts and stops in the entries here.
+The pack depends on `@suss/contract-terraform` for the type of an entry, and on `@suss/behavioral-ir` for the terms a translation table may use. Neither the reader nor the checker knows anything about Google. Google's vocabulary appears only in the entries here.
 
 ## More
 
-- [What each entry decided](./DESIGN.md), the provider versions it was written against, and the pages it came from
+- [Why each entry reads what it reads](./DESIGN.md), the provider versions it was written against, and the pages it came from

package/dist/index.cjs

@@ -90,8 +90,8 @@ function googleTerraform() {
         boundary: {
           kind: "storage",
           storageSystem: "gcs",
-          // The name is what code passes to `bucket()`, so it is the
-          // identity both sides spell.
+          // Code passes the same name to `bucket()`, so both sides use
+          // it as the identity.
           nameAttribute: "name",
           // An object has no fields to compare a read against.
           fieldSet: "none"
@@ -117,8 +117,9 @@ function googleTerraform() {
           storageSystem: BIGQUERY,
           nameAttribute: "table_id",
           scopeAttribute: "dataset_id",
-          // A schema written in the configuration is every column the
-          // table has; one a file or a variable supplies says nothing.
+          // A schema written in the configuration lists every column. A
+          // schema from a file or a variable is out of sight, so `none` is
+          // the fallback when fieldsFromJson finds nothing.
           fieldSet: "none",
           fieldsFromJson: {
             attribute: "schema",
@@ -143,8 +144,8 @@ function googleTerraform() {
       {
         resource: "google_firestore_database",
         providerVersions: CURRENT,
-        // A database in Datastore mode speaks a different API, so it is
-        // not the store this entry describes.
+        // A database in Datastore mode uses a different API, so this
+        // entry does not describe it.
         appliesWhen: { attribute: "type", equals: ["FIRESTORE_NATIVE"] },
         boundary: {
           kind: "storage",
@@ -161,8 +162,8 @@ function googleTerraform() {
         boundary: {
           kind: "storage",
           storageSystem: "gcp.bigtable",
-          // A table id is what code passes to `instance.table()`, so
-          // the declared name and the accessed name meet.
+          // Code passes the table id to `instance.table()`, so the
+          // declared name matches the accessed one.
           nameAttribute: "name",
           // Column families are not the fields of a row.
           fieldSet: "none"
@@ -209,7 +210,7 @@ function googleTerraform() {
           storageSystem: "redis",
           // Code addresses key namespaces, which no attribute of the
           // instance lists, so it declares the store and claims no
-          // access. The README says how the sides meet.
+          // access. The README explains why.
           declares: "store",
           fieldSet: "none"
         }
@@ -221,8 +222,8 @@ function googleTerraform() {
           kind: "metric",
           metricSystem: METRIC_SYSTEM,
           // Cloud Monitoring puts every metric a project defines for
-          // itself under this prefix, and an alert policy spells the
-          // whole string, so the whole string is the shared identity.
+          // itself under this prefix, and an alert policy writes the
+          // whole string, so the identity is the whole string.
           metricTypeTemplate: "logging.googleapis.com/user/{name}",
           values: {
             attribute: "metric_descriptor.value_type",
@@ -266,7 +267,7 @@ function googleTerraform() {
         boundary: {
           kind: "deployable",
           // A second-generation function is deployed as a Cloud Run
-          // service, so it runs on the same medium as one.
+          // service, so it uses the same deployment target as one.
           deploymentTarget: "container",
           runtimeAttribute: "build_config.runtime",
           env: [
@@ -278,8 +279,8 @@ function googleTerraform() {
               secretAttribute: "secret"
             }
           ],
-          // The entry point is an exported name and says nothing about
-          // which file it is in.
+          // The entry point is an exported name and does not give the
+          // file it is in.
           code: {
             handler: {
               attribute: "build_config.entry_point",

package/dist/index.d.cts

@@ -4,16 +4,15 @@ import { TerraformPack } from '@suss/contract-terraform';
  * What Google Cloud's Terraform provider declares, as far as suss reads
  * it.
  *
- * A log-based metric is a boundary: the resource declares a series of
- * measurements, and an alert policy elsewhere reads it back by the type
- * string Cloud Monitoring gives it. That string is what the two share,
- * whether the policy writes it out or builds it from a reference to the
- * metric resource.
+ * A log-based metric is a boundary. The resource declares a series of
+ * measurements, and an alert policy reads it back by the type string
+ * Cloud Monitoring gives it, whether the policy writes that string out
+ * or builds it from a reference to the metric resource.
  *
- * Google's vocabulary starts and stops in this file. Each entry says
- * which attribute a resource writes which of Google's words in, and
- * what they mean in the terms suss compares boundaries in, so
- * `checkMetric` in `@suss/checker` judges a pair with no pack loaded.
+ * Google's own terms appear only in this file. Each entry gives the
+ * attribute that contains a Google value and what that value means in
+ * suss's terms, so `checkMetric` in `@suss/checker` can judge a pair
+ * without loading a pack.
  */
 
 declare function googleTerraform(): TerraformPack;

package/dist/index.d.ts

@@ -4,16 +4,15 @@ import { TerraformPack } from '@suss/contract-terraform';
  * What Google Cloud's Terraform provider declares, as far as suss reads
  * it.
  *
- * A log-based metric is a boundary: the resource declares a series of
- * measurements, and an alert policy elsewhere reads it back by the type
- * string Cloud Monitoring gives it. That string is what the two share,
- * whether the policy writes it out or builds it from a reference to the
- * metric resource.
+ * A log-based metric is a boundary. The resource declares a series of
+ * measurements, and an alert policy reads it back by the type string
+ * Cloud Monitoring gives it, whether the policy writes that string out
+ * or builds it from a reference to the metric resource.
  *
- * Google's vocabulary starts and stops in this file. Each entry says
- * which attribute a resource writes which of Google's words in, and
- * what they mean in the terms suss compares boundaries in, so
- * `checkMetric` in `@suss/checker` judges a pair with no pack loaded.
+ * Google's own terms appear only in this file. Each entry gives the
+ * attribute that contains a Google value and what that value means in
+ * suss's terms, so `checkMetric` in `@suss/checker` can judge a pair
+ * without loading a pack.
  */
 
 declare function googleTerraform(): TerraformPack;

package/dist/index.js

@@ -65,8 +65,8 @@ function googleTerraform() {
         boundary: {
           kind: "storage",
           storageSystem: "gcs",
-          // The name is what code passes to `bucket()`, so it is the
-          // identity both sides spell.
+          // Code passes the same name to `bucket()`, so both sides use
+          // it as the identity.
           nameAttribute: "name",
           // An object has no fields to compare a read against.
           fieldSet: "none"
@@ -92,8 +92,9 @@ function googleTerraform() {
           storageSystem: BIGQUERY,
           nameAttribute: "table_id",
           scopeAttribute: "dataset_id",
-          // A schema written in the configuration is every column the
-          // table has; one a file or a variable supplies says nothing.
+          // A schema written in the configuration lists every column. A
+          // schema from a file or a variable is out of sight, so `none` is
+          // the fallback when fieldsFromJson finds nothing.
           fieldSet: "none",
           fieldsFromJson: {
             attribute: "schema",
@@ -118,8 +119,8 @@ function googleTerraform() {
       {
         resource: "google_firestore_database",
         providerVersions: CURRENT,
-        // A database in Datastore mode speaks a different API, so it is
-        // not the store this entry describes.
+        // A database in Datastore mode uses a different API, so this
+        // entry does not describe it.
         appliesWhen: { attribute: "type", equals: ["FIRESTORE_NATIVE"] },
         boundary: {
           kind: "storage",
@@ -136,8 +137,8 @@ function googleTerraform() {
         boundary: {
           kind: "storage",
           storageSystem: "gcp.bigtable",
-          // A table id is what code passes to `instance.table()`, so
-          // the declared name and the accessed name meet.
+          // Code passes the table id to `instance.table()`, so the
+          // declared name matches the accessed one.
           nameAttribute: "name",
           // Column families are not the fields of a row.
           fieldSet: "none"
@@ -184,7 +185,7 @@ function googleTerraform() {
           storageSystem: "redis",
           // Code addresses key namespaces, which no attribute of the
           // instance lists, so it declares the store and claims no
-          // access. The README says how the sides meet.
+          // access. The README explains why.
           declares: "store",
           fieldSet: "none"
         }
@@ -196,8 +197,8 @@ function googleTerraform() {
           kind: "metric",
           metricSystem: METRIC_SYSTEM,
           // Cloud Monitoring puts every metric a project defines for
-          // itself under this prefix, and an alert policy spells the
-          // whole string, so the whole string is the shared identity.
+          // itself under this prefix, and an alert policy writes the
+          // whole string, so the identity is the whole string.
           metricTypeTemplate: "logging.googleapis.com/user/{name}",
           values: {
             attribute: "metric_descriptor.value_type",
@@ -241,7 +242,7 @@ function googleTerraform() {
         boundary: {
           kind: "deployable",
           // A second-generation function is deployed as a Cloud Run
-          // service, so it runs on the same medium as one.
+          // service, so it uses the same deployment target as one.
           deploymentTarget: "container",
           runtimeAttribute: "build_config.runtime",
           env: [
@@ -253,8 +254,8 @@ function googleTerraform() {
               secretAttribute: "secret"
             }
           ],
-          // The entry point is an exported name and says nothing about
-          // which file it is in.
+          // The entry point is an exported name and does not give the
+          // file it is in.
           code: {
             handler: {
               attribute: "build_config.entry_point",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/terraform-gcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "What the Google Cloud Terraform provider declares, so suss can check your code against the infrastructure you deploy.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/terraform/gcp#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,8 +47,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.0",
-    "@suss/contract-terraform": "0.33.0"
+    "@suss/behavioral-ir": "0.34.0",
+    "@suss/contract-terraform": "0.34.0"
   },
   "devDependencies": {
     "@suss/checker": "*",