@suss/contract-terraform 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -30,6 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  filterCalls: () => filterCalls,
+  filterTerms: () => filterTerms,
+  filterValuesFor: () => filterValuesFor,
+  parseFilterQuery: () => parseFilterQuery,
   terraformFileToSummaries: () => terraformFileToSummaries,
   terraformToSummaries: () => terraformToSummaries
 });
@@ -39,39 +43,394 @@ var import_node_path = __toESM(require("path"), 1);
 var import_hcl2_parser = __toESM(require("hcl2-parser"), 1);
 var import_semver = __toESM(require("semver"), 1);
 var import_behavioral_ir = require("@suss/behavioral-ir");
-function terraformToSummaries(source, sourceFile, options) {
-  let parsed;
-  try {
-    const [read] = import_hcl2_parser.default.parseToObject(source);
-    parsed = read;
-  } catch {
+
+// src/filterQuery.ts
+var OPERATORS = ["!=", ">=", "<=", "=", ">", "<", ":"];
+var KEYWORDS = /* @__PURE__ */ new Set(["AND", "OR", "NOT"]);
+function filterValuesFor(query, key) {
+  return filterTerms(query).filter((term) => term.key === key && term.operator === "=").map((term) => term.value);
+}
+function filterTerms(query) {
+  if (query.type === "term") {
+    return [query];
+  }
+  if (query.type === "call") {
     return [];
   }
-  const document = asRecord(parsed);
-  if (document === null) {
+  if (query.type === "negation") {
+    return filterTerms(query.operand);
+  }
+  return query.operands.flatMap(filterTerms);
+}
+function filterCalls(query) {
+  if (query.type === "call") {
+    return [query];
+  }
+  if (query.type === "term") {
     return [];
   }
-  const constraints = providerConstraints(document);
-  const summaries = [];
-  for (const [resourceType, label, body] of resourcesIn(document)) {
-    for (const pack of options.packs) {
-      const pattern = patternFor(pack, resourceType, constraints);
-      if (pattern === void 0) {
-        continue;
+  if (query.type === "negation") {
+    return filterCalls(query.operand);
+  }
+  return query.operands.flatMap(filterCalls);
+}
+function parseFilterQuery(source) {
+  const tokens = tokenize(source);
+  if (!tokens.ok) {
+    return { ok: false, reason: tokens.reason };
+  }
+  const reader = new TokenReader(tokens.tokens);
+  const query = reader.readExpression();
+  if (query === null) {
+    return { ok: false, reason: reader.reason };
+  }
+  if (!reader.atEnd()) {
+    return {
+      ok: false,
+      reason: `nothing joins the term at "${reader.rest()}"`
+    };
+  }
+  return { ok: true, query };
+}
+function tokenize(source) {
+  const tokens = [];
+  let at = 0;
+  while (at < source.length) {
+    const char = source[at];
+    if (/\s/.test(char) || char === ",") {
+      at += 1;
+      continue;
+    }
+    if (char === "(" || char === ")") {
+      tokens.push({ type: char === "(" ? "open" : "close", text: char });
+      at += 1;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      const quoted = readQuoted(source, at, char);
+      if (quoted === null) {
+        return { ok: false, reason: `a quote is never closed at ${at}` };
+      }
+      const previous = tokens[tokens.length - 1];
+      if (previous !== void 0 && isPartialKey(previous)) {
+        previous.text += quoted.value;
+      } else {
+        tokens.push({ type: "string", text: quoted.value });
       }
-      summaries.push(
-        ...summariesFor({ pattern, label, body, sourceFile, resourceType })
-      );
+      at = quoted.next;
+      continue;
+    }
+    const operator = OPERATORS.find(
+      (candidate) => source.startsWith(candidate, at)
+    );
+    if (operator !== void 0) {
+      tokens.push({ type: "operator", text: operator });
+      at += operator.length;
+      continue;
     }
+    const word = readWord(source, at);
+    if (word === null) {
+      return { ok: false, reason: `nothing readable at "${char}"` };
+    }
+    tokens.push({ type: "word", text: word.value });
+    at = word.next;
   }
-  return summaries;
+  return { ok: true, tokens };
+}
+function readQuoted(source, start, quote) {
+  let value = "";
+  let at = start + 1;
+  while (at < source.length) {
+    const char = source[at];
+    if (char === "\\" && at + 1 < source.length) {
+      value += source[at + 1];
+      at += 2;
+      continue;
+    }
+    if (char === quote) {
+      return { value, next: at + 1 };
+    }
+    value += char;
+    at += 1;
+  }
+  return null;
+}
+function isPartialKey(token) {
+  return token.type === "word" && token.text.endsWith(".");
+}
+function readWord(source, start) {
+  const match = /^[^\s(),="'!<>:]+/.exec(source.slice(start));
+  if (match === null) {
+    return null;
+  }
+  return { value: match[0], next: start + match[0].length };
+}
+var TokenReader = class {
+  constructor(tokens) {
+    this.tokens = tokens;
+  }
+  tokens;
+  at = 0;
+  /** What stopped the last read, for the caller to report. */
+  reason = "the filter states no comparison";
+  atEnd() {
+    return this.at >= this.tokens.length;
+  }
+  rest() {
+    return this.tokens.slice(this.at).map((token) => token.text).join(" ");
+  }
+  readExpression() {
+    return this.readJunction(
+      "or",
+      "OR",
+      () => this.readJunction("and", "AND", () => this.readUnary())
+    );
+  }
+  readJunction(operator, keyword, readOperand) {
+    const first = readOperand();
+    if (first === null) {
+      return null;
+    }
+    const operands = [first];
+    while (!this.atEnd()) {
+      const joined = this.keywordAhead(keyword);
+      if (!joined && !(operator === "and" && this.termAhead())) {
+        break;
+      }
+      if (joined) {
+        this.at += 1;
+      }
+      const next = readOperand();
+      if (next === null) {
+        return null;
+      }
+      operands.push(next);
+    }
+    return operands.length === 1 ? operands[0] : { type: "junction", operator, operands };
+  }
+  readUnary() {
+    if (this.keywordAhead("NOT")) {
+      this.at += 1;
+      const operand = this.readUnary();
+      return operand === null ? null : { type: "negation", operand };
+    }
+    return this.readPrimary();
+  }
+  readPrimary() {
+    const token = this.tokens[this.at];
+    if (token === void 0) {
+      this.reason = "the filter ends where a comparison should be";
+      return null;
+    }
+    if (token.type === "open") {
+      this.at += 1;
+      const inner = this.readExpression();
+      if (inner === null) {
+        return null;
+      }
+      if (this.tokens[this.at]?.type !== "close") {
+        this.reason = "a parenthesis is never closed";
+        return null;
+      }
+      this.at += 1;
+      return inner;
+    }
+    if (token.type === "word" && this.tokens[this.at + 1]?.type === "open") {
+      return this.readCall();
+    }
+    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.
+   */
+  readCall() {
+    const name = this.tokens[this.at];
+    this.at += 2;
+    const args = [];
+    while (!this.atEnd() && this.tokens[this.at]?.type !== "close") {
+      const argument = this.tokens[this.at];
+      if (argument.type === "word" || argument.type === "string") {
+        args.push(argument.text);
+      }
+      this.at += 1;
+    }
+    if (this.atEnd()) {
+      this.reason = `the call to "${name.text}" is never closed`;
+      return null;
+    }
+    this.at += 1;
+    return { type: "call", name: name.text, arguments: args };
+  }
+  readTerm() {
+    const key = this.tokens[this.at];
+    const operator = this.tokens[this.at + 1];
+    const value = this.tokens[this.at + 2];
+    if (key === void 0 || key.type !== "word") {
+      this.reason = `"${key?.text ?? ""}" is not a key`;
+      return null;
+    }
+    if (operator === void 0 || operator.type !== "operator") {
+      this.reason = `"${key.text}" is compared to nothing`;
+      return null;
+    }
+    if (value === void 0 || value.type !== "word" && value.type !== "string") {
+      this.reason = `"${key.text}" is compared to no value`;
+      return null;
+    }
+    this.at += 3;
+    return {
+      type: "term",
+      key: key.text,
+      operator: operator.text,
+      value: value.text
+    };
+  }
+  /** Whether the next token is this keyword rather than a key. */
+  keywordAhead(keyword) {
+    const token = this.tokens[this.at];
+    return token !== void 0 && token.type === "word" && token.text === keyword;
+  }
+  /** Whether a new comparison starts here, with no keyword joining it. */
+  termAhead() {
+    const token = this.tokens[this.at];
+    if (token === void 0) {
+      return false;
+    }
+    if (token.type === "open") {
+      return true;
+    }
+    return token.type === "word" && !KEYWORDS.has(token.text);
+  }
+};
+
+// src/references.ts
+var SUB_TOKEN = /\$\{([^}]*)\}/g;
+var RESOURCE_ATTRIBUTE = /^([A-Za-z][\w-]*)\.([A-Za-z_][\w-]*)\.([A-Za-z_][\w-]*)$/;
+var LOCAL_VALUE = /^local\.([A-Za-z_][\w-]*)$/;
+var LOCALS = "local";
+var CHAIN_LIMIT = 4;
+function referenceScope(resources, locals = []) {
+  const scope = /* @__PURE__ */ new Map();
+  for (const [resourceType, label, body] of resources) {
+    const address = `${resourceType}.${label}`;
+    if (!scope.has(address)) {
+      scope.set(address, body);
+    }
+  }
+  const stated = {};
+  for (const block of locals) {
+    for (const [name, value] of Object.entries(block)) {
+      if (!(name in stated)) {
+        stated[name] = value;
+      }
+    }
+  }
+  scope.set(LOCALS, stated);
+  return scope;
+}
+function resolveReferences(value, scope) {
+  return expand(value, scope, []) ?? value;
+}
+function expand(value, scope, resolving) {
+  let cycled = false;
+  const expanded = value.replace(SUB_TOKEN, (written, inner) => {
+    const reference = inner.trim();
+    if (resolving.includes(reference)) {
+      cycled = true;
+      return written;
+    }
+    const stated = statedValue(reference, scope);
+    if (stated === null || resolving.length >= CHAIN_LIMIT) {
+      return written;
+    }
+    const nested = expand(stated, scope, [...resolving, reference]);
+    if (nested === null) {
+      cycled = true;
+      return written;
+    }
+    return nested;
+  });
+  return cycled ? null : expanded;
+}
+function statedValue(reference, scope) {
+  const local = LOCAL_VALUE.exec(reference);
+  if (local !== null) {
+    const stated2 = scope.get(LOCALS)?.[local[1]];
+    return typeof stated2 === "string" ? stated2 : null;
+  }
+  const parsed = RESOURCE_ATTRIBUTE.exec(reference);
+  if (parsed === null) {
+    return null;
+  }
+  const [, resourceType, label, attribute] = parsed;
+  const stated = scope.get(`${resourceType}.${label}`)?.[attribute];
+  return typeof stated === "string" ? stated : null;
+}
+
+// src/index.ts
+function terraformToSummaries(source, sourceFile, options) {
+  return summariesForFiles([{ source, sourceFile }], options);
 }
 function terraformFileToSummaries(target, options) {
   const files = import_node_fs.default.statSync(target).isDirectory() ? import_node_fs.default.readdirSync(target).filter((name) => name.endsWith(".tf")).map((name) => import_node_path.default.join(target, name)) : [target];
-  return files.flatMap(
-    (file) => terraformToSummaries(import_node_fs.default.readFileSync(file, "utf8"), file, options)
+  return summariesForFiles(
+    files.map((file) => ({
+      source: import_node_fs.default.readFileSync(file, "utf8"),
+      sourceFile: file
+    })),
+    options
   );
 }
+function summariesForFiles(files, options) {
+  const parsed = files.map((file) => parseSource(file)).filter((file) => file !== null);
+  const scope = referenceScope(
+    parsed.flatMap((file) => file.resources),
+    parsed.flatMap((file) => file.locals)
+  );
+  const summaries = [];
+  for (const file of parsed) {
+    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) {
+          continue;
+        }
+        summaries.push(
+          ...summariesFor({
+            pattern,
+            label,
+            body,
+            sourceFile: file.sourceFile,
+            resourceType,
+            scope
+          })
+        );
+      }
+    }
+  }
+  return summaries;
+}
+function parseSource(file) {
+  let read;
+  try {
+    const [parsed] = import_hcl2_parser.default.parseToObject(file.source);
+    read = parsed;
+  } catch {
+    return null;
+  }
+  const document = asRecord(read);
+  if (document === null) {
+    return null;
+  }
+  return {
+    sourceFile: file.sourceFile,
+    constraints: providerConstraints(document),
+    resources: resourcesIn(document),
+    locals: localsIn(document)
+  };
+}
 function providerConstraints(document) {
   const constraints = /* @__PURE__ */ new Map();
   for (const block of arrayOf(document.terraform)) {
@@ -110,22 +469,26 @@ function patternFor(pack, resourceType, constraints) {
     }
   });
 }
+var READERS = {
+  storage: (site, boundary) => {
+    const types = fieldTypes(site.body, boundary);
+    return keyedShapes(site.body, boundary).map(
+      (shape) => storageSummary({ ...site, boundary, shape, types })
+    );
+  },
+  "message-bus": (site, boundary) => [busSummary({ ...site, boundary })],
+  metric: (site, boundary) => [metricSummary({ ...site, boundary })],
+  "metric-reading": (site, boundary) => readingSummaries({ ...site, boundary })
+};
 function summariesFor(opts) {
-  const { pattern } = opts;
-  if (pattern.boundary.kind === "message-bus") {
-    return [busSummary({ ...opts, boundary: pattern.boundary })];
-  }
-  const boundary = pattern.boundary;
-  const types = fieldTypes(opts.body, boundary);
-  return keyedShapes(opts.body, boundary).map(
-    (shape) => storageSummary({ ...opts, boundary, shape, types })
-  );
+  const { pattern, ...site } = opts;
+  const read = READERS[pattern.boundary.kind];
+  return read(site, pattern.boundary);
 }
 function storageSummary(opts) {
   const { boundary, label, shape, types } = opts;
   const address = `${opts.resourceType}.${label}`;
-  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
-  const physicalTable = declaredName === null ? null : (0, import_behavioral_ir.namePatternFromSub)(declaredName);
+  const physicalTable = boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
   return {
     kind: "library",
     location: {
@@ -169,8 +532,7 @@ function storageSummary(opts) {
 }
 function busSummary(opts) {
   const { boundary, label } = opts;
-  const declaredName = boundary.nameAttribute === void 0 ? null : stringOf(opts.body[boundary.nameAttribute]);
-  const physicalName = declaredName === null ? null : (0, import_behavioral_ir.namePatternFromSub)(declaredName);
+  const physicalName = boundary.nameAttribute === void 0 ? null : namePattern(opts.body[boundary.nameAttribute], opts.scope);
   return {
     kind: "library",
     location: {
@@ -200,6 +562,132 @@ function busSummary(opts) {
     }
   };
 }
+var NAME_HOLE = "{name}";
+function metricSummary(opts) {
+  const { boundary } = opts;
+  const declaredName = namePattern(
+    opts.body[boundary.nameAttribute],
+    opts.scope
+  );
+  const metricType = declaredName === null ? null : boundary.metricTypeTemplate.replace(NAME_HOLE, declaredName);
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: `${opts.resourceType}.${opts.label}`,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir.metricBinding)({
+        recognition: "terraform",
+        metricSystem: boundary.metricSystem,
+        metricType
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: { metricContract: metricContract(opts.body, boundary) }
+  };
+}
+function metricContract(body, boundary) {
+  const values = meaningOf(body, boundary.values);
+  const accumulates = meaningOf(body, boundary.accumulates);
+  return {
+    ...values !== void 0 ? { values } : {},
+    ...accumulates !== void 0 ? { accumulates } : {}
+  };
+}
+function readingSummaries(opts) {
+  const { boundary } = opts;
+  const summaries = [];
+  for (const reading of blocksAt(opts.body, boundary.readingBlocks)) {
+    const query = stringOf(valueAt(reading, boundary.queryAttribute));
+    for (const metricType of metricTypesIn(
+      query,
+      boundary.queryIdentityKey,
+      opts.scope
+    )) {
+      summaries.push({
+        kind: "consumer",
+        location: {
+          file: opts.sourceFile,
+          range: { start: 1, end: 1 },
+          exportName: null
+        },
+        identity: {
+          name: `${opts.resourceType}.${opts.label}#${summaries.length}`,
+          exportPath: null,
+          boundaryBinding: (0, import_behavioral_ir.metricBinding)({
+            recognition: "terraform",
+            metricSystem: boundary.metricSystem,
+            metricType
+          })
+        },
+        inputs: [],
+        transitions: [],
+        gaps: [],
+        confidence: { source: "declared", level: "high" },
+        metadata: { metricReading: metricReading(reading, boundary) }
+      });
+    }
+  }
+  return summaries;
+}
+function metricTypesIn(query, identityKey, scope) {
+  if (query === null) {
+    return [null];
+  }
+  const parsed = parseFilterQuery(query);
+  if (!parsed.ok) {
+    return [null];
+  }
+  const found = filterValuesFor(parsed.query, identityKey).map((value) => namePattern(value, scope)).filter((value) => value !== null);
+  return found.length === 0 ? [null] : found;
+}
+function metricReading(reading, boundary) {
+  const compares = boundary.comparesTo;
+  const comparesTo = compares !== void 0 && valueAt(reading, compares.attribute) !== void 0 ? compares.whenSet : void 0;
+  const reduces = boundary.reducesTo;
+  const reducesTo = meaningOf(reading, reduces);
+  return {
+    ...comparesTo !== void 0 ? { comparesTo } : {},
+    ...reducesTo !== void 0 ? { reducesTo } : {},
+    ...reduces === void 0 ? {} : { reduction: { setting: reduces.attribute, leaves: reduces.means } }
+  };
+}
+function meaningOf(body, spec) {
+  if (spec === void 0) {
+    return void 0;
+  }
+  const stated = stringOf(valueAt(body, spec.attribute));
+  return stated === null ? void 0 : spec.means[stated];
+}
+function valueAt(body, path2) {
+  const steps = path2.split(".");
+  const last = steps.pop();
+  let current = body;
+  for (const step of steps) {
+    const nested = arrayOf(current[step])[0];
+    current = asRecord(nested);
+    if (current === null) {
+      return void 0;
+    }
+  }
+  return current[last];
+}
+function blocksAt(body, blocks) {
+  let found = [body];
+  for (const block of blocks) {
+    found = found.flatMap(
+      (record) => arrayOf(record[block]).map(asRecord).filter((nested) => nested !== null)
+    );
+  }
+  return found;
+}
 function keyedShapes(body, boundary) {
   if (boundary.identifies === void 0) {
     return [{ accessPath: null, keyFields: [], serves: null }];
@@ -264,6 +752,16 @@ function fieldTypes(body, boundary) {
   }
   return types;
 }
+function localsIn(document) {
+  const found = [];
+  for (const block of arrayOf(document.locals)) {
+    const stated = asRecord(block);
+    if (stated !== null) {
+      found.push(stated);
+    }
+  }
+  return found;
+}
 function resourcesIn(document) {
   const found = [];
   for (const resource of arrayOf(document.resource)) {
@@ -290,6 +788,11 @@ function resourcesIn(document) {
   }
   return found;
 }
+function namePattern(value, scope) {
+  return (0, import_behavioral_ir.namePatternFromSub)(
+    typeof value === "string" ? resolveReferences(value, scope) : value
+  );
+}
 function arrayOf(value) {
   if (value === void 0 || value === null) {
     return [];
@@ -304,6 +807,10 @@ function stringOf(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  filterCalls,
+  filterTerms,
+  filterValuesFor,
+  parseFilterQuery,
   terraformFileToSummaries,
   terraformToSummaries
 });