@suss/contract-terraform 0.9.0 → 0.10.0

package/README.md

@@ -83,7 +83,7 @@ An entry with `kind: "metric"` says which attribute is the name and how the depl
 
 The selector is a small query language rather than a name, so `parseFilterQuery` reads it: comparisons joined by `AND` and `OR`, with parentheses, `NOT`, quoted or bare values, and terms written next to each other for AND. A key may quote one of its own segments, `metric.label."response_code_class"`, and that comes back as one key with the quotes off. A call may stand where a comparison would, which is how Cloud Monitoring writes an SLO burn-rate condition, and `filterCalls` gives those back. The parser is exported, so a pack that has to read the same string for something else does not write a second one. A selector it cannot read leaves the reading with no metric on it, which pairs with nothing.
 
-Both kinds also say what the resource's own words mean in suss's terms, so the checker never learns a provider's vocabulary. A pack writes `values: { attribute: "shape.value_type", means: { SPREAD: "spread", SCALAR: "number" } }`, the reader takes the value at that attribute, dotted paths stepping into nested blocks, looks it up in the table, and writes the answer to `metricContract` on the summary. `accumulates` works the same way. A value the table does not list says nothing, the same as an attribute the configuration never set.
+Both kinds also say what the resource's own words mean in suss's terms, so the checker never learns a provider's vocabulary. A pack writes `values: { attribute: "shape.value_type", means: { SPREAD: "histogram", SCALAR: "number" } }`, the reader takes the value at that attribute, dotted paths stepping into nested blocks, looks it up in the table, and writes the answer to `metricContract` on the summary. `accumulates` works the same way. A value the table does not list says nothing, the same as an attribute the configuration never set.
 
 A reading translates two things the same way. `comparesTo: { attribute: "limit", whenSet: "number" }` says the reading compares the series against a single number when it states a limit at all, since a threshold is a number by being written down. `reducesTo` maps an aligner or reducer to what it leaves behind. Both land on the summary under `metricReading`, along with the setting and the values that would reduce the series, so a finding can name the fix without the checker knowing which provider it came from.
 

package/dist/index.cjs

@@ -394,7 +394,7 @@ function summariesForFiles(files, options) {
     for (const [resourceType, label, body] of file.resources) {
       for (const pack of options.packs) {
         const pattern = patternFor(pack, resourceType, file.constraints);
-        if (pattern === void 0) {
+        if (pattern === void 0 || !entryApplies(pattern, body)) {
           continue;
         }
         summaries.push(
@@ -469,6 +469,18 @@ function patternFor(pack, resourceType, constraints) {
     }
   });
 }
+function entryApplies(pattern, body) {
+  const gate = pattern.appliesWhen;
+  if (gate === void 0) {
+    return true;
+  }
+  const value = body[gate.attribute];
+  if (value === void 0) {
+    return gate.whenUnset === "read";
+  }
+  const text = stringOf(value);
+  return text !== null && gate.equals.includes(text);
+}
 var READERS = {
   storage: (site, boundary) => {
     const types = fieldTypes(site.body, boundary);
@@ -488,7 +500,8 @@ function summariesFor(opts) {
 function storageSummary(opts) {
   const { boundary, label, shape, types } = opts;
   const address = `${opts.resourceType}.${label}`;
-  const physicalTable = boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
+  const declaresContainer = boundary.declares !== "store";
+  const physicalTable = !declaresContainer || boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
   return {
     kind: "library",
     location: {
@@ -504,7 +517,7 @@ function storageSummary(opts) {
         storageSystem: boundary.storageSystem,
         ...boundary.transport !== void 0 ? { transport: boundary.transport } : {},
         scope: "default",
-        container: label,
+        container: declaresContainer ? label : null,
         accessPath: shape.accessPath
       })
     },

package/dist/index.d.cts

@@ -20,6 +20,17 @@ interface StorageResource {
     storageSystem: string;
     /** How a caller reaches it, when that is not 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.
+     */
+    declares?: "container" | "store";
     /** The attribute that says what the resource is called once deployed. */
     nameAttribute?: string;
     /** Whether the fields it declares are every field an item has. */
@@ -80,7 +91,7 @@ interface MetricResource {
      * metric spells, so it is the identity the two sides share.
      */
     metricTypeTemplate: string;
-    /** Which attribute says whether one measurement is a number or a spread. */
+    /** Which attribute says whether one measurement is a number or a histogram. */
     values?: AttributeMeaning<MetricValueShape>;
     /** Which attribute says what a measurement covers. */
     accumulates?: AttributeMeaning<MetricAccumulation>;
@@ -116,6 +127,20 @@ type TerraformResource = StorageResource | MessageBusResource | MetricResource |
 interface TerraformResourcePattern {
     /** The resource type, spelled the way the provider spells it. */
     resource: string;
+    /**
+     * An attribute that decides whether the entry describes the resource
+     * at all. `aws_elasticache_cluster` deploys whichever engine its
+     * `engine` attribute picks, and only some engines are the store the
+     * 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.
+     */
+    appliesWhen?: {
+        attribute: string;
+        equals: string[];
+        whenUnset?: "read" | "skip";
+    };
     /**
      * Which provider versions this describes, as a semver range. A
      * configuration states its own constraint under `required_providers`,

package/dist/index.d.ts

@@ -20,6 +20,17 @@ interface StorageResource {
     storageSystem: string;
     /** How a caller reaches it, when that is not 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.
+     */
+    declares?: "container" | "store";
     /** The attribute that says what the resource is called once deployed. */
     nameAttribute?: string;
     /** Whether the fields it declares are every field an item has. */
@@ -80,7 +91,7 @@ interface MetricResource {
      * metric spells, so it is the identity the two sides share.
      */
     metricTypeTemplate: string;
-    /** Which attribute says whether one measurement is a number or a spread. */
+    /** Which attribute says whether one measurement is a number or a histogram. */
     values?: AttributeMeaning<MetricValueShape>;
     /** Which attribute says what a measurement covers. */
     accumulates?: AttributeMeaning<MetricAccumulation>;
@@ -116,6 +127,20 @@ type TerraformResource = StorageResource | MessageBusResource | MetricResource |
 interface TerraformResourcePattern {
     /** The resource type, spelled the way the provider spells it. */
     resource: string;
+    /**
+     * An attribute that decides whether the entry describes the resource
+     * at all. `aws_elasticache_cluster` deploys whichever engine its
+     * `engine` attribute picks, and only some engines are the store the
+     * 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.
+     */
+    appliesWhen?: {
+        attribute: string;
+        equals: string[];
+        whenUnset?: "read" | "skip";
+    };
     /**
      * Which provider versions this describes, as a semver range. A
      * configuration states its own constraint under `required_providers`,

package/dist/index.js

@@ -360,7 +360,7 @@ function summariesForFiles(files, options) {
     for (const [resourceType, label, body] of file.resources) {
       for (const pack of options.packs) {
         const pattern = patternFor(pack, resourceType, file.constraints);
-        if (pattern === void 0) {
+        if (pattern === void 0 || !entryApplies(pattern, body)) {
           continue;
         }
         summaries.push(
@@ -435,6 +435,18 @@ function patternFor(pack, resourceType, constraints) {
     }
   });
 }
+function entryApplies(pattern, body) {
+  const gate = pattern.appliesWhen;
+  if (gate === void 0) {
+    return true;
+  }
+  const value = body[gate.attribute];
+  if (value === void 0) {
+    return gate.whenUnset === "read";
+  }
+  const text = stringOf(value);
+  return text !== null && gate.equals.includes(text);
+}
 var READERS = {
   storage: (site, boundary) => {
     const types = fieldTypes(site.body, boundary);
@@ -454,7 +466,8 @@ function summariesFor(opts) {
 function storageSummary(opts) {
   const { boundary, label, shape, types } = opts;
   const address = `${opts.resourceType}.${label}`;
-  const physicalTable = boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
+  const declaresContainer = boundary.declares !== "store";
+  const physicalTable = !declaresContainer || boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
   return {
     kind: "library",
     location: {
@@ -470,7 +483,7 @@ function storageSummary(opts) {
         storageSystem: boundary.storageSystem,
         ...boundary.transport !== void 0 ? { transport: boundary.transport } : {},
         scope: "default",
-        container: label,
+        container: declaresContainer ? label : null,
         accessPath: shape.accessPath
       })
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-terraform",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Read the storage a Terraform configuration declares, for checking code against it.",
   "keywords": [
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.9.0",
+    "@suss/behavioral-ir": "0.10.0",
     "hcl2-parser": "^1.0.3",
     "semver": "^7.6.0"
   },