@intentius/chant 0.66.0 → 0.67.0

package/src/behaviour-kinds.test.ts

@@ -0,0 +1,235 @@
+/**
+ * The coverage resolution, now that rows are contributed rather than held
+ * centrally (#2382).
+ *
+ * Two properties matter more than any individual row, and both are here
+ * because #2357's version could not have them: resolution is **total** (every
+ * type reaches exactly one verdict, so the request builder can promise every
+ * entity lands in `entities` or in `unpredicted`), and an absent contributor
+ * is **silence about an absent substrate**, never silence about entities that
+ * are present.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  ENGINE_KINDS,
+  coverageFor,
+  isEngineKind,
+  type BehaviourKinds,
+} from "./behaviour-kinds";
+
+const aws: BehaviourKinds = {
+  provider: "aws",
+  prefixes: ["AWS::"],
+  mapped: {
+    "AWS::EC2::Instance": { kind: "compute", sizeProp: "InstanceType", sizeType: "string" },
+    "AWS::S3::Bucket": { kind: "object-store" },
+  },
+  unmapped: {
+    "AWS::IAM::Role": "a grant is not a resource: it carries no rate of its own",
+  },
+  // CloudFormation property types — hundreds of nested blocks that became
+  // entities of their own, never separately priced.
+  unmappedWhen: (type) =>
+    type.includes(".")
+      ? "a CloudFormation property type: the resource above it carries the figures"
+      : undefined,
+};
+
+const cedar: BehaviourKinds = {
+  provider: "cedar",
+  prefixes: ["Cedar::"],
+  nothingPriced: "Cedar (a policy language, with nothing to saturate)",
+};
+
+const terraform: BehaviourKinds = {
+  provider: "aws",
+  prefixes: ["Terraform::"],
+  resolveType: (_entityType, props) => {
+    const address = props?.address;
+    if (typeof address !== "string") return undefined;
+    const dot = address.indexOf(".");
+    return dot > 0 ? address.slice(0, dot) : undefined;
+  },
+  mapped: {
+    aws_instance: { kind: "compute", sizeProp: "body.instance_type", sizeType: "string" },
+  },
+  unmapped: { aws_iam_role: "a grant is not a resource" },
+};
+
+/** A lexicon that models part of what it declares, which is terraform's shape. */
+const partial: BehaviourKinds = {
+  provider: "aws",
+  prefixes: ["Partial::"],
+  mapped: { "Partial::aws_instance": { kind: "compute" } },
+  unmapped: { "Partial::aws_iam_role": "a grant is not a resource" },
+  notModelledWhen: (type) =>
+    type.startsWith("Partial::aws_") ? undefined : `the ${type.split("::")[1]?.split("_")[0]} provider, which nothing here models`,
+};
+
+const ALL = [aws, cedar, terraform, partial];
+
+describe("the kind enum", () => {
+  test("is derived from a total witness, so a kind cannot be added and forgotten", () => {
+    expect(ENGINE_KINDS).toContain("control-plane");
+    expect(ENGINE_KINDS.length).toBe(new Set(ENGINE_KINDS).size);
+  });
+
+  test("isEngineKind rejects a plausible near-miss", () => {
+    expect(isEngineKind("compute")).toBe(true);
+    expect(isEngineKind("storage")).toBe(false);
+    expect(isEngineKind(undefined)).toBe(false);
+  });
+});
+
+describe("a lexicon's rows decide its own types", () => {
+  test("a mapped type carries the kind, the size property and the contributor's provider", () => {
+    const v = coverageFor(ALL, "AWS::EC2::Instance");
+    expect(v.status).toBe("mapped");
+    if (v.status !== "mapped") return;
+    expect(v.mapping.kind).toBe("compute");
+    expect(v.mapping.sizeProp).toBe("InstanceType");
+    // The row did not state a provider; it inherits the contributor's, which
+    // is what keeps `provider` off every row.
+    expect(v.mapping.provider).toBe("aws");
+  });
+
+  test("a declared-unmapped type keeps the sentence saying why", () => {
+    const v = coverageFor(ALL, "AWS::IAM::Role");
+    expect(v.status).toBe("declared-unmapped");
+    if (v.status !== "declared-unmapped") return;
+    expect(v.reason).toContain("a grant is not a resource");
+  });
+
+  test("a whole substrate can say nothing is priced, once, without rows", () => {
+    const v = coverageFor(ALL, "Cedar::Policy");
+    expect(v.status).toBe("provider-not-modelled");
+    if (v.status !== "provider-not-modelled") return;
+    expect(v.substrate).toContain("nothing to saturate");
+  });
+
+  test("a type its own lexicon claims and cannot classify is the one defect verdict", () => {
+    // Not `declared-unmapped`: nobody decided this, somebody forgot it.
+    expect(coverageFor(ALL, "AWS::Kinesis::Stream").status).toBe("unknown-type");
+  });
+
+  test("unmappedWhen is the last word, for a family too large to enumerate", () => {
+    const v = coverageFor(ALL, "AWS::S3::Bucket.VersioningConfiguration");
+    expect(v.status).toBe("declared-unmapped");
+    if (v.status !== "declared-unmapped") return;
+    expect(v.reason).toContain("carries the figures");
+  });
+});
+
+describe("a lexicon whose entities share one entity type", () => {
+  test("rows are looked up on the type its props carry, not on the entity type", () => {
+    const v = coverageFor(ALL, "Terraform::Resource", { address: "aws_instance.web" });
+    expect(v.status).toBe("mapped");
+    if (v.status !== "mapped") return;
+    expect(v.mapping.sizeProp).toBe("body.instance_type");
+  });
+
+  test("nothing to resolve is no opinion, not a defect claim about the wrong type", () => {
+    expect(coverageFor(ALL, "Terraform::Resource", {}).status).toBe("unknown-type");
+    expect(coverageFor(ALL, "Terraform::Resource").status).toBe("unknown-type");
+  });
+});
+
+describe("a contributor that redirects only some of its types", () => {
+  // terraform's shape: `Terraform::Resource` keys off its address, and the
+  // root's own blocks key by entity type like everyone else. The bug this
+  // pins: with `resolveType` blind to the entity type, every root block
+  // resolved through the address path and came back a defect.
+  const mixed: BehaviourKinds = {
+    provider: "aws",
+    prefixes: ["Tf::"],
+    resolveType: (entityType, props) =>
+      entityType === "Tf::Resource"
+        ? typeof props?.address === "string"
+          ? props.address.split(".")[0]
+          : undefined
+        : entityType,
+    mapped: { aws_instance: { kind: "compute" } },
+    unmapped: { "Tf::Variable": "a root module input; it shapes what is created and is never created itself" },
+  };
+
+  test("the redirected type reads its key out of the props", () => {
+    expect(coverageFor([mixed], "Tf::Resource", { address: "aws_instance.web" }).status).toBe("mapped");
+  });
+
+  test("an ordinary type of the same lexicon still keys by entity type", () => {
+    const v = coverageFor([mixed], "Tf::Variable");
+    expect(v.status).toBe("declared-unmapped");
+    if (v.status !== "declared-unmapped") return;
+    expect(v.reason).toContain("never created itself");
+  });
+});
+
+describe("what an absent contributor means", () => {
+  test("a type nobody claims is nobody's mistake", () => {
+    // The gcp lexicon is not installed, so no GCP:: entity was declared. The
+    // verdict exists for a type reached some other way, and it is silence.
+    expect(coverageFor(ALL, "GCP::Compute::Instance").status).toBe("unknown-type");
+  });
+
+  test("removing a contributor changes only its own types", () => {
+    const withoutAws = coverageFor([cedar, terraform], "AWS::EC2::Instance");
+    expect(withoutAws.status).toBe("unknown-type");
+    // Everyone else's verdicts are untouched — rows are additive, which is why
+    // they may be optional when the capability may not be.
+    expect(coverageFor([cedar, terraform], "Cedar::Policy").status).toBe("provider-not-modelled");
+  });
+});
+
+describe("a lexicon that models only part of what it declares", () => {
+  test("a family outside the modelled substrate is named, not called a defect", () => {
+    const v = coverageFor(ALL, "Partial::google_compute_instance");
+    expect(v.status).toBe("provider-not-modelled");
+    if (v.status !== "provider-not-modelled") return;
+    expect(v.substrate).toContain("google");
+  });
+
+  test("a type inside the modelled substrate with no row is still the defect", () => {
+    // The ordering that matters: a substrate boundary is a statement about
+    // types this lexicon never models, and it must not swallow a row somebody
+    // forgot to write for one it does.
+    expect(coverageFor(ALL, "Partial::aws_kinesis_stream").status).toBe("unknown-type");
+  });
+});
+
+describe("chant's own build-time entities", () => {
+  test("are declared-unmapped before any contributor is consulted", () => {
+    const v = coverageFor([], "chant:output:apiUrl");
+    expect(v.status).toBe("declared-unmapped");
+    if (v.status !== "declared-unmapped") return;
+    expect(v.reason).toContain("never billed");
+  });
+});
+
+describe("resolution is total", () => {
+  test("every shape of input reaches exactly one verdict, including hostile keys", () => {
+    const cases: Array<[string, Record<string, unknown> | undefined]> = [
+      ["AWS::EC2::Instance", undefined],
+      ["AWS::IAM::Role", undefined],
+      ["Cedar::Policy", undefined],
+      ["Terraform::Resource", { address: "aws_instance.web" }],
+      ["Terraform::Resource", undefined],
+      ["GCP::Compute::Instance", undefined],
+      ["chant:output:x", undefined],
+      // A prototype member as an entity type: `hasOwnProperty` rather than a
+      // truthiness check is what stops this resolving to a mapping that does
+      // not exist.
+      ["AWS::constructor", undefined],
+      ["AWS::__proto__", undefined],
+      ["", undefined],
+    ];
+    const seen = new Set<string>();
+    for (const [type, props] of cases) {
+      const v = coverageFor(ALL, type, props);
+      expect(["mapped", "declared-unmapped", "provider-not-modelled", "unknown-type"]).toContain(v.status);
+      seen.add(v.status);
+    }
+    // Not just legal: the cases above actually exercise all four arms.
+    expect(seen.size).toBe(4);
+  });
+});

package/src/behaviour-kinds.ts

@@ -0,0 +1,324 @@
+/**
+ * What an engine is asked to price, and who gets to say so (#2382).
+ *
+ * `./behaviour.ts` says what a prediction may mean and `./behaviour-http.ts`
+ * carries one to an engine. Between them sits a question neither answers: for
+ * a given entity in a project's graph, what *kind* of thing is it, and is it
+ * something an engine prices at all? #2357 answered it with one table in one
+ * lexicon, keyed by every other lexicon's entity types. That table described
+ * 117 types it did not own, and the capability rode on whether an optional
+ * package happened to be installed — which gave a consumer a fourth
+ * outcome this contract never named: no overlay, no refusal, and no reason.
+ *
+ * So the resolution lives here, where every other part of the feature already
+ * does, and the *rows* are contributed by the lexicon that owns the substrate.
+ * Core learns that an entity has an engine kind. It never learns which.
+ *
+ * ## Why rows are safe to make optional when the capability is not
+ *
+ * A lexicon that is not installed declared no entities of its types, so it has
+ * no rows to contribute and nothing goes missing: the estate simply contains
+ * nothing of that substrate. That is the opposite of the capability itself
+ * being optional, where an uninstalled package means an estate full of
+ * entities nobody will say anything about.
+ *
+ * ## The three things a lexicon can say about its own types
+ *
+ *   - **mapped** — this type is a `compute`/`database`/`queue`, and its size
+ *     is read from this declared property, in the provider's own vocabulary.
+ *   - **declared unmapped** — this type is real and carries no rate an engine
+ *     can quote, with the sentence saying why. A grant is not a resource; a
+ *     boundary is not a node; a meter chant cannot read is not a figure.
+ *   - **nothing priced** — nothing this lexicon declares is an estate an
+ *     engine prices, once, for the whole substrate. A CI workflow is not an
+ *     estate, and a policy language has nothing to saturate.
+ *
+ * A type a contributor claims and has no row for is `unknown-type`: the one
+ * verdict that is a defect rather than a decision, and the reason the three
+ * above are distinct states instead of one absent row.
+ */
+
+/**
+ * The categories a cost-and-saturation model actually distinguishes, not a
+ * taxonomy of every product a cloud sells.
+ *
+ * A kind is here when an engine would price it differently or when its
+ * saturation axis differs. `cache` is separate from `database` because a cache
+ * saturates on memory and a database on IO; `serverless` is separate from
+ * `compute` because one is priced per invocation and the other per hour of
+ * existence, and this contract's output shape is per hour. `control-plane` is
+ * separate from everything because a managed control plane is a flat hourly
+ * fee that does not move with the estate's traffic at all — pricing one as
+ * `compute` would make it look like something a right-size suggestion could
+ * shrink.
+ */
+export type EngineKind =
+  | "compute"
+  | "serverless"
+  | "control-plane"
+  | "database"
+  | "cache"
+  | "queue"
+  | "object-store"
+  | "block-store"
+  | "load-balancer"
+  | "cdn";
+
+const ENGINE_KIND_WITNESS: Record<EngineKind, true> = {
+  compute: true,
+  serverless: true,
+  "control-plane": true,
+  database: true,
+  cache: true,
+  queue: true,
+  "object-store": true,
+  "block-store": true,
+  "load-balancer": true,
+  cdn: true,
+};
+
+/**
+ * Every legal {@link EngineKind}, derived from a total witness rather than
+ * written out by hand — the construction `behaviour.ts` uses for
+ * `BEHAVIOUR_BASES`, for the same reason: a hand-written array is checked for
+ * having legal members and never for having all of them.
+ */
+export const ENGINE_KINDS: readonly EngineKind[] = Object.keys(ENGINE_KIND_WITNESS) as EngineKind[];
+
+/** True when `value` is a legal {@link EngineKind}. */
+export function isEngineKind(value: unknown): value is EngineKind {
+  return typeof value === "string" && (ENGINE_KINDS as readonly string[]).includes(value);
+}
+
+/** One row of a lexicon's coverage: what one of its entity types becomes on the wire. */
+export interface EngineKindMapping {
+  /** The engine-side kind. */
+  kind: EngineKind;
+  /**
+   * The substrate, as the engine names it — `aws`, `kubernetes`. A plain
+   * string rather than a closed union: the contributing lexicon names its own
+   * substrate, and core adding a member here for every lexicon that ships
+   * would be core holding the list it exists to stop holding.
+   */
+  provider: string;
+  /**
+   * The declared property whose value is the entity's size, in the provider's
+   * own vocabulary — `InstanceType`, not a parsed vCPU count. Absent where the
+   * type has no size a single `size` string can carry.
+   */
+  sizeProp?: string;
+  /**
+   * Which type {@link sizeProp} holds. A value of the other type is absent
+   * rather than coerced: a number rendered into a size field an engine matches
+   * against a price table of strings is worse than no size at all.
+   */
+  sizeType?: "string" | "number";
+  /**
+   * The declared property naming the region or zone this entity sits in, where
+   * the type states one of its own. Most do not, and inherit the caller's.
+   */
+  regionProp?: string;
+}
+
+/**
+ * One lexicon's answer for its own entity types, contributed through the
+ * plugin's `behaviourKinds` field.
+ *
+ * Every field except {@link prefixes} is optional, and a lexicon that supplies
+ * only {@link nothingPriced} has said something complete: that none of what it
+ * declares is an estate an engine prices.
+ */
+export interface BehaviourKinds {
+  /** The substrate, as the engine names it. Every mapped row inherits it. */
+  provider: string;
+  /**
+   * The entity-type prefixes this lexicon owns — `["AWS::"]`, `["K8s::"]`.
+   * Ownership is what makes a missing row a defect rather than silence: a type
+   * nobody claims is nobody's mistake, and a type its own lexicon claims and
+   * cannot classify is a row somebody forgot to write.
+   */
+  prefixes: readonly string[];
+  /** Types this lexicon prices, keyed by entity type — or by resolved type where {@link resolveType} is given. */
+  mapped?: Readonly<Record<string, Omit<EngineKindMapping, "provider"> & { provider?: string }>>;
+  /** Types that are real and carry no rate, keyed the same way, with the sentence saying why. */
+  unmapped?: Readonly<Record<string, string>>;
+  /**
+   * Nothing this lexicon declares is priced, and this says why — checked
+   * before the tables, so a lexicon that states it needs no rows at all.
+   */
+  nothingPriced?: string;
+  /**
+   * For a lexicon whose entities do not key rows by their entity type, the
+   * key to look rows up on instead. terraform's every `resource` block arrives
+   * as `Terraform::Resource`, and what an engine would price is the type its
+   * address carries.
+   *
+   * It is handed the entity type as well as the props, because a lexicon
+   * usually redirects only *some* of its types: terraform's root blocks
+   * (`Terraform::Variable`, `Terraform::Output`) key by entity type like
+   * everyone else, and only `Terraform::Resource` reads its key out of the
+   * props. Returning the entity type unchanged is how a contributor says "this
+   * one is ordinary". Returning `undefined` is "nothing to look up", the same
+   * no-opinion an unseen type gets.
+   */
+  resolveType?: (entityType: string, props: Record<string, unknown> | undefined) => string | undefined;
+  /**
+   * A family of this lexicon's types that belongs to a substrate nothing here
+   * models, named as the substrate — or `undefined` to let the type carry on
+   * to {@link unmappedWhen}. terraform is the case this exists for: one
+   * lexicon's `resource` blocks span every provider there is, so `google_`
+   * and `azurerm_` and `null_` are each a boundary of their own, while an
+   * `aws_` type with no row stays the defect it is. A contributor whose whole
+   * substrate is unpriced uses {@link nothingPriced} instead; this is for the
+   * lexicon that models part of what it declares.
+   */
+  notModelledWhen?: (type: string) => string | undefined;
+  /**
+   * A last word on a type this lexicon claims and has no row for: the reason
+   * it is unmapped, or `undefined` to leave it a defect. CloudFormation's
+   * property types are the case this exists for — hundreds of nested blocks
+   * that became entities of their own, never separately priced, and
+   * enumerating them one row at a time would bury the table's real decisions.
+   */
+  unmappedWhen?: (type: string) => string | undefined;
+}
+
+/** What one entity type resolves to. Total: every type reaches exactly one of these. */
+export type CoverageVerdict =
+  | { status: "mapped"; mapping: EngineKindMapping }
+  | { status: "declared-unmapped"; reason: string }
+  | { status: "provider-not-modelled"; substrate: string }
+  | { status: "unknown-type" };
+
+/** chant's own build-time entities, which no lexicon owns and nothing bills. */
+const CHANT_PSEUDO_PREFIX = "chant:";
+
+/**
+ * Resolve one entity type against the contributed rows.
+ *
+ * Total by construction: every type reaches one of the four states and there
+ * is no fifth arm for "dropped". That is the property the request builder
+ * relies on to guarantee every entity it was asked about lands in `entities`
+ * or in `unpredicted`.
+ *
+ * `hasOwnProperty` rather than a truthiness check, because these are plain
+ * object literals and an entity named after a prototype member would otherwise
+ * resolve to a mapping that does not exist.
+ */
+export function coverageFor(
+  contributors: readonly BehaviourKinds[],
+  entityType: string,
+  props?: Record<string, unknown>,
+): CoverageVerdict {
+  if (entityType.startsWith(CHANT_PSEUDO_PREFIX)) {
+    return {
+      status: "declared-unmapped",
+      reason:
+        "one of chant's own build-time entities rather than something an account holds — a declared " +
+        "output, or a default that rides onto the resources beside it. It is never created and never " +
+        "billed",
+    };
+  }
+
+  const owner = contributors.find((c) => c.prefixes.some((p) => entityType.startsWith(p)));
+  if (!owner) return { status: "unknown-type" };
+  if (owner.nothingPriced) return { status: "provider-not-modelled", substrate: owner.nothingPriced };
+
+  const type = owner.resolveType ? owner.resolveType(entityType, props) : entityType;
+  if (type === undefined) return { status: "unknown-type" };
+
+  if (owner.mapped && Object.prototype.hasOwnProperty.call(owner.mapped, type)) {
+    const row = owner.mapped[type];
+    return { status: "mapped", mapping: { ...row, provider: row.provider ?? owner.provider } };
+  }
+  if (owner.unmapped && Object.prototype.hasOwnProperty.call(owner.unmapped, type)) {
+    return { status: "declared-unmapped", reason: owner.unmapped[type] };
+  }
+  // Before `unmappedWhen`, and after both tables: a row is this lexicon's
+  // decision about a type it models, and a substrate boundary is a statement
+  // about types it never will. A type inside the modelled substrate with no
+  // row falls past both and stays the defect it is.
+  const elsewhere = owner.notModelledWhen?.(type);
+  if (elsewhere !== undefined) return { status: "provider-not-modelled", substrate: elsewhere };
+  const late = owner.unmappedWhen?.(type);
+  if (late !== undefined) return { status: "declared-unmapped", reason: late };
+  return { status: "unknown-type" };
+}
+
+/**
+ * The contributor that owns an entity type, or `undefined` when nobody claims
+ * it. Exported because a caller that has already resolved a verdict often
+ * needs the owner too — to name it in a detail, or to label the entity the way
+ * its own lexicon would.
+ */
+export function ownerOf(
+  contributors: readonly BehaviourKinds[],
+  entityType: string,
+): BehaviourKinds | undefined {
+  return contributors.find((c) => c.prefixes.some((p) => entityType.startsWith(p)));
+}
+
+/**
+ * How a detail names an entity's kind. The chant entity type, except where the
+ * owning lexicon keys its rows on something else: `Terraform::Resource` names
+ * nothing a reader can act on, and the provider type is the kind, so the label
+ * is `aws_vpc (Terraform::Resource)`.
+ */
+export function coverageLabel(
+  contributors: readonly BehaviourKinds[],
+  entityType: string,
+  props?: Record<string, unknown>,
+): string {
+  const owner = ownerOf(contributors, entityType);
+  if (!owner?.resolveType) return entityType;
+  const type = owner.resolveType(entityType, props);
+  return type === undefined || type === entityType ? entityType : `${type} (${entityType})`;
+}
+
+/**
+ * The `detail` an `unpredicted` entry carries, naming the kind in every case.
+ *
+ * The kind is named here, in the per-entity decline, because that is the only
+ * place in this contract with a per-entity axis: a `BehaviourRefusalReport` is
+ * a statement about the whole run and has no `entities` key by design, so a
+ * report-level refusal for one unmapped bucket would take the other nineteen
+ * entities' figures down with it.
+ *
+ * The `unknown-type` arm names the lexicon that owns the type rather than a
+ * file path, because since #2382 the row belongs to whichever lexicon defines
+ * the type, and that is the thing a reader needs to be told.
+ */
+export function unmappedDetail(
+  label: string,
+  verdict: CoverageVerdict,
+  owner?: BehaviourKinds,
+): string {
+  if (verdict.status === "declared-unmapped") {
+    return `${label} is declared unmapped by the ${owner?.provider ?? "declaring"} coverage rows: ${verdict.reason}.`;
+  }
+  if (verdict.status === "provider-not-modelled") {
+    return (
+      `${label} belongs to ${verdict.substrate}, which nothing here models. A substrate is added by ` +
+      "the lexicon that owns its types contributing rows for them, not by adding a row elsewhere. " +
+      "This is a stated boundary rather than a gap — nothing needs filing."
+    );
+  }
+  const where = owner
+    ? `the lexicon that owns ${owner.prefixes.join(", ")}`
+    : "the lexicon that owns this entity type";
+  return (
+    `${label} has no row in any contributed coverage table — it is a type from a substrate that is ` +
+    "modelled, and is neither mapped to an engine kind nor declared unmapped, so nothing has an " +
+    `opinion about it rather than a stated one. Add a row in ${where}.`
+  );
+}
+
+/**
+ * Compare two strings by UTF-16 code unit.
+ *
+ * Not `localeCompare`, which reads the ambient locale: under `sv-SE` and
+ * `et-EE` it orders these type names differently from `en-US`, which would
+ * make the request's bytes — and therefore any golden fixture, and therefore
+ * any declared-versus-live delta — a function of the machine that built them.
+ */
+export const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);