@suss/contract-terraform 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { MessageBusTechnology, BehavioralSummary } from '@suss/behavioral-ir';
+import { MessageBusTechnology, MetricValueShape, MetricAccumulation, BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
  * What a pack says about the resources one Terraform provider declares.
@@ -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. */
@@ -55,11 +66,81 @@ interface MessageBusResource {
     messageBus: MessageBusTechnology;
     nameAttribute?: string;
 }
-type TerraformResource = StorageResource | MessageBusResource;
+/**
+ * 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, the same as an
+ * attribute the configuration never set.
+ */
+interface AttributeMeaning<T extends string> {
+    /** The attribute path whose value says which one it is. */
+    attribute: string;
+    /** What each value the provider can write there means. */
+    means: Record<string, T>;
+}
+/** A named series of measurements a resource declares. */
+interface MetricResource {
+    kind: "metric";
+    /** Which system the series lives in: cloud-monitoring. */
+    metricSystem: string;
+    /** The attribute that says what the metric is called. */
+    nameAttribute: string;
+    /**
+     * How the deployed metric type is spelled, with `{name}` standing
+     * for the declared name. That string is what a resource reading the
+     * metric spells, so it is the identity the two sides share.
+     */
+    metricTypeTemplate: string;
+    /** 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>;
+}
+/**
+ * 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.
+ */
+interface MetricReadingResource {
+    kind: "metric-reading";
+    metricSystem: string;
+    /** The blocks one reading is written inside, outermost first. */
+    readingBlocks: string[];
+    /** The attribute whose query says which metric the reading is about. */
+    queryAttribute: string;
+    /** The key inside that query whose value is the metric's type. */
+    queryIdentityKey: string;
+    /**
+     * 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.
+     */
+    comparesTo?: {
+        attribute: string;
+        whenSet: MetricValueShape;
+    };
+    /** Which attribute says what the reading reduces each window to first. */
+    reducesTo?: AttributeMeaning<MetricValueShape>;
+}
+type TerraformResource = StorageResource | MessageBusResource | MetricResource | MetricReadingResource;
 /** One resource type, as one version range of one provider declares it. */
 interface TerraformResourcePattern {
     /** The resource type, spelled the way the provider spells it. */
     resource: string;
+    /**
+     * 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`,
@@ -81,6 +162,65 @@ interface TerraformPack {
     resources: TerraformResourcePattern[];
 }
 
+/**
+ * A filter written as comparisons joined by AND and OR.
+ *
+ * Several cloud APIs take a selector as one string in this shape:
+ * `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.
+ *
+ * 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.
+ */
+/** One comparison, as the filter writes it. */
+interface FilterTerm {
+    type: "term";
+    /**
+     * The left side, a dotted path such as `metric.type`. A segment the
+     * filter quotes, `metric.label."response_code"`, comes back without
+     * the quotes, so one key has one spelling.
+     */
+    key: string;
+    /** `=`, `!=`, `>`, `>=`, `<`, `<=`, or `:` for "has". */
+    operator: string;
+    /** The right side, with the quotes taken off a quoted value. */
+    value: string;
+}
+/** A call standing where a comparison would, with its arguments. */
+interface FilterCall {
+    type: "call";
+    name: string;
+    arguments: string[];
+}
+type FilterQuery = FilterTerm | FilterCall | {
+    type: "junction";
+    operator: "and" | "or";
+    operands: FilterQuery[];
+} | {
+    type: "negation";
+    operand: FilterQuery;
+};
+/** A filter nobody could read says why, rather than reading as empty. */
+type FilterParse = {
+    ok: true;
+    query: FilterQuery;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every value a key is compared to with `=`, anywhere in the tree. */
+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. */
+declare function filterCalls(query: FilterQuery): FilterCall[];
+/** Read one filter string, or say what stopped the reading. */
+declare function parseFilterQuery(source: string): FilterParse;
+
 /**
  * The boundaries a Terraform configuration declares.
  *
@@ -91,8 +231,10 @@ interface TerraformPack {
  * A name is usually built at deploy time, and Terraform interpolates
  * the same way CloudFormation does, so `"${local.environment}-orders"`
  * becomes the pattern `{local.environment}-orders` and pairs with code
- * that builds the same name from its own variable. The README says how
- * a block that HCL states once or many times is read.
+ * 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.
  */
 
 interface TerraformReadOptions {
@@ -104,4 +246,4 @@ declare function terraformToSummaries(source: string, sourceFile: string, option
 /** Read one `.tf` file, or every one directly inside a directory. */
 declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];
 
-export { type MessageBusResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, terraformFileToSummaries, terraformToSummaries };
+export { type AttributeMeaning, type FilterCall, type FilterParse, type FilterQuery, type FilterTerm, type MessageBusResource, type MetricReadingResource, type MetricResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, filterCalls, filterTerms, filterValuesFor, parseFilterQuery, terraformFileToSummaries, terraformToSummaries };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MessageBusTechnology, BehavioralSummary } from '@suss/behavioral-ir';
+import { MessageBusTechnology, MetricValueShape, MetricAccumulation, BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
  * What a pack says about the resources one Terraform provider declares.
@@ -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. */
@@ -55,11 +66,81 @@ interface MessageBusResource {
     messageBus: MessageBusTechnology;
     nameAttribute?: string;
 }
-type TerraformResource = StorageResource | MessageBusResource;
+/**
+ * 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, the same as an
+ * attribute the configuration never set.
+ */
+interface AttributeMeaning<T extends string> {
+    /** The attribute path whose value says which one it is. */
+    attribute: string;
+    /** What each value the provider can write there means. */
+    means: Record<string, T>;
+}
+/** A named series of measurements a resource declares. */
+interface MetricResource {
+    kind: "metric";
+    /** Which system the series lives in: cloud-monitoring. */
+    metricSystem: string;
+    /** The attribute that says what the metric is called. */
+    nameAttribute: string;
+    /**
+     * How the deployed metric type is spelled, with `{name}` standing
+     * for the declared name. That string is what a resource reading the
+     * metric spells, so it is the identity the two sides share.
+     */
+    metricTypeTemplate: string;
+    /** 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>;
+}
+/**
+ * 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.
+ */
+interface MetricReadingResource {
+    kind: "metric-reading";
+    metricSystem: string;
+    /** The blocks one reading is written inside, outermost first. */
+    readingBlocks: string[];
+    /** The attribute whose query says which metric the reading is about. */
+    queryAttribute: string;
+    /** The key inside that query whose value is the metric's type. */
+    queryIdentityKey: string;
+    /**
+     * 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.
+     */
+    comparesTo?: {
+        attribute: string;
+        whenSet: MetricValueShape;
+    };
+    /** Which attribute says what the reading reduces each window to first. */
+    reducesTo?: AttributeMeaning<MetricValueShape>;
+}
+type TerraformResource = StorageResource | MessageBusResource | MetricResource | MetricReadingResource;
 /** One resource type, as one version range of one provider declares it. */
 interface TerraformResourcePattern {
     /** The resource type, spelled the way the provider spells it. */
     resource: string;
+    /**
+     * 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`,
@@ -81,6 +162,65 @@ interface TerraformPack {
     resources: TerraformResourcePattern[];
 }
 
+/**
+ * A filter written as comparisons joined by AND and OR.
+ *
+ * Several cloud APIs take a selector as one string in this shape:
+ * `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.
+ *
+ * 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.
+ */
+/** One comparison, as the filter writes it. */
+interface FilterTerm {
+    type: "term";
+    /**
+     * The left side, a dotted path such as `metric.type`. A segment the
+     * filter quotes, `metric.label."response_code"`, comes back without
+     * the quotes, so one key has one spelling.
+     */
+    key: string;
+    /** `=`, `!=`, `>`, `>=`, `<`, `<=`, or `:` for "has". */
+    operator: string;
+    /** The right side, with the quotes taken off a quoted value. */
+    value: string;
+}
+/** A call standing where a comparison would, with its arguments. */
+interface FilterCall {
+    type: "call";
+    name: string;
+    arguments: string[];
+}
+type FilterQuery = FilterTerm | FilterCall | {
+    type: "junction";
+    operator: "and" | "or";
+    operands: FilterQuery[];
+} | {
+    type: "negation";
+    operand: FilterQuery;
+};
+/** A filter nobody could read says why, rather than reading as empty. */
+type FilterParse = {
+    ok: true;
+    query: FilterQuery;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every value a key is compared to with `=`, anywhere in the tree. */
+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. */
+declare function filterCalls(query: FilterQuery): FilterCall[];
+/** Read one filter string, or say what stopped the reading. */
+declare function parseFilterQuery(source: string): FilterParse;
+
 /**
  * The boundaries a Terraform configuration declares.
  *
@@ -91,8 +231,10 @@ interface TerraformPack {
  * A name is usually built at deploy time, and Terraform interpolates
  * the same way CloudFormation does, so `"${local.environment}-orders"`
  * becomes the pattern `{local.environment}-orders` and pairs with code
- * that builds the same name from its own variable. The README says how
- * a block that HCL states once or many times is read.
+ * 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.
  */
 
 interface TerraformReadOptions {
@@ -104,4 +246,4 @@ declare function terraformToSummaries(source: string, sourceFile: string, option
 /** Read one `.tf` file, or every one directly inside a directory. */
 declare function terraformFileToSummaries(target: string, options: TerraformReadOptions): BehavioralSummary[];
 
-export { type MessageBusResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, terraformFileToSummaries, terraformToSummaries };
+export { type AttributeMeaning, type FilterCall, type FilterParse, type FilterQuery, type FilterTerm, type MessageBusResource, type MetricReadingResource, type MetricResource, type StorageResource, type TerraformPack, type TerraformReadOptions, type TerraformResource, type TerraformResourcePattern, filterCalls, filterTerms, filterValuesFor, parseFilterQuery, terraformFileToSummaries, terraformToSummaries };