@intentius/chant 0.45.0 → 0.46.0

package/src/codegen/validate.ts

@@ -27,6 +27,17 @@ export interface ValidateResult {
  */
 export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
 
+/**
+ * Set by `chant dev surface-diff --update-snapshot` for the validate run it
+ * performs before rewriting the baseline (chant #1825). When set to "1", the
+ * `surface-matches-snapshot` check is skipped. That check fails on exactly the
+ * staleness the update run exists to fix, and with an `"always"` gate (#1475)
+ * the two would deadlock: validate cannot pass until the snapshot is updated,
+ * and the snapshot cannot be updated until validate passes. Every other check
+ * still runs, so a broken generate cannot be baselined.
+ */
+export const SNAPSHOT_UPDATE_ENV = "CHANT_SNAPSHOT_UPDATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -201,10 +212,18 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
   // Runs on the artifacts already on disk — no second generation — and is
   // skipped for a lexicon with no committed snapshot, which is the case for a
   // new lexicon before its first baseline.
+  //
+  // A re-baseline run (`chant dev surface-diff --update-snapshot`) sets
+  // {@link SNAPSHOT_UPDATE_ENV} and is exempt: the check would fail on the
+  // stale snapshot that run is about to rewrite, deadlocking the documented
+  // update flow against an `"always"` gate (#1825). Only this check is exempt —
+  // every other check above still gates the run.
   const snapshotPath = join(config.basePath, "surface.snapshot.json");
+  const env = config.env ?? process.env;
   const surfaceGate =
-    config.checkSurfaceSnapshot === "always" ||
-    (config.checkSurfaceSnapshot === true && (config.env ?? process.env)[RELEASE_GATE_ENV] === "1");
+    (config.checkSurfaceSnapshot === "always" ||
+      (config.checkSurfaceSnapshot === true && env[RELEASE_GATE_ENV] === "1")) &&
+    env[SNAPSHOT_UPDATE_ENV] !== "1";
   if (surfaceGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
     try {
       const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));

package/src/config.test.ts

@@ -9,6 +9,8 @@ import {
   environmentName,
   environmentNames,
   environmentEndpoint,
+  matchesEnvironmentPattern,
+  matchesDeclaredEnvironment,
 } from "./config";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
@@ -336,6 +338,44 @@ describe("environmentName / environmentNames / environmentEndpoint (#1166)", ()
     expect(environmentEndpoint(environments, "unknown")).toBeUndefined(); // not declared at all
     expect(environmentEndpoint(undefined, "floci")).toBeUndefined();
   });
+
+  test("environmentEndpoint resolves through a pattern entry, literal entry winning (#1221)", () => {
+    const environments = [
+      { name: "pr-special", endpoint: "http://special:1111" },
+      { name: "pr-*", endpoint: "http://preview:4566" },
+    ];
+    expect(environmentEndpoint(environments, "pr-42")).toBe("http://preview:4566");
+    expect(environmentEndpoint(environments, "pr-special")).toBe("http://special:1111"); // literal wins over the pattern
+    expect(environmentEndpoint(environments, "prod")).toBeUndefined();
+  });
+});
+
+describe("environment glob patterns (#1221)", () => {
+  test("matchesEnvironmentPattern: a * matches any run of characters, anchored", () => {
+    expect(matchesEnvironmentPattern("pr-*", "pr-42")).toBe(true);
+    expect(matchesEnvironmentPattern("pr-*", "pr-")).toBe(true); // empty run is a run
+    expect(matchesEnvironmentPattern("pr-*", "pr")).toBe(false);
+    expect(matchesEnvironmentPattern("pr-*", "xpr-42")).toBe(false); // anchored at the start
+    expect(matchesEnvironmentPattern("*-preview", "42-preview")).toBe(true);
+    expect(matchesEnvironmentPattern("*-preview", "42-preview-old")).toBe(false); // anchored at the end
+    expect(matchesEnvironmentPattern("test-*-eu", "test-a-eu")).toBe(true);
+    expect(matchesEnvironmentPattern("test-*-eu", "test-a-us")).toBe(false);
+  });
+
+  test("matchesEnvironmentPattern without a * is plain equality", () => {
+    expect(matchesEnvironmentPattern("prod", "prod")).toBe(true);
+    expect(matchesEnvironmentPattern("prod", "prod2")).toBe(false);
+  });
+
+  test("matchesDeclaredEnvironment: literal first, then pattern, across entry forms", () => {
+    const environments = ["dev", "prod", "pr-*", { name: "test-*", endpoint: "http://localhost:4566" }];
+    expect(matchesDeclaredEnvironment(environments, "prod")).toBe(true);
+    expect(matchesDeclaredEnvironment(environments, "pr-42")).toBe(true);
+    expect(matchesDeclaredEnvironment(environments, "test-suite-a")).toBe(true); // object-form pattern entry
+    expect(matchesDeclaredEnvironment(environments, "stage")).toBe(false);
+    expect(matchesDeclaredEnvironment(undefined, "prod")).toBe(false);
+    expect(matchesDeclaredEnvironment([], "prod")).toBe(false);
+  });
 });
 
 describe("resolveFoldEnabled (#1134 — fold is the default build path)", () => {

package/src/config.ts

@@ -44,6 +44,56 @@ export function environmentNames(environments: EnvironmentDeclaration[] | undefi
   return environments?.map(environmentName);
 }
 
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export function isEnvironmentPattern(declaredName: string): boolean {
+  return declaredName.includes("*");
+}
+
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export function matchesEnvironmentPattern(pattern: string, name: string): boolean {
+  const parts = pattern.split("*");
+  if (parts.length === 1) return pattern === name;
+  const first = parts[0];
+  const last = parts[parts.length - 1];
+  if (!name.startsWith(first)) return false;
+  let cursor = first.length;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    const at = name.indexOf(part, cursor);
+    if (at === -1) return false;
+    cursor = at + part.length;
+  }
+  return name.length - cursor >= last.length && name.endsWith(last);
+}
+
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export function matchesDeclaredEnvironment(
+  environments: EnvironmentDeclaration[] | undefined,
+  name: string,
+): boolean {
+  const names = environmentNames(environments) ?? [];
+  if (names.includes(name)) return true;
+  return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
+}
+
 /**
  * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
  * entry, an entry with no `endpoint` set, or a name this project doesn't
@@ -51,9 +101,16 @@ export function environmentNames(environments: EnvironmentDeclaration[] | undefi
  * it injects this into the ambient env var each observing lexicon's CLI
  * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
  * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
  */
 export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
-  const found = environments?.find((e) => environmentName(e) === name);
+  const found =
+    environments?.find((e) => environmentName(e) === name) ??
+    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
   return found && typeof found !== "string" ? found.endpoint : undefined;
 }
 

package/src/env.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect } from "vitest";
 import { mkdir, writeFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { env, unknownEnvError, ENV_VAR } from "./env";
+import { env, unknownEnvError, isProdLikeEnvironment, ENV_VAR } from "./env";
 import { discover } from "./discovery/index";
 
 const withEnv = async (value: string | undefined, fn: () => void | Promise<void>): Promise<void> => {
@@ -52,6 +52,25 @@ describe("unknownEnvError", () => {
       unknownEnvError("stage", ["prod", { name: "floci", endpoint: "http://localhost:4566" }]),
     ).toMatch(/Unknown environment "stage".*prod, floci/);
   });
+
+  // #1221 — an entry containing `*` is a glob pattern, so an unbounded family
+  // (per-PR environments, per-suite test environments) is declarable without
+  // listing each name.
+  test("accepts an env covered by a declared glob pattern (#1221)", () => {
+    expect(unknownEnvError("pr-42", ["dev", "prod", "pr-*"])).toBeUndefined();
+    expect(unknownEnvError("test-suite-a", ["prod", { name: "test-*", endpoint: "http://localhost:4566" }])).toBeUndefined();
+  });
+
+  test("rejects an env no pattern covers, listing the patterns among the declared entries (#1221)", () => {
+    expect(unknownEnvError("stage", ["dev", "prod", "pr-*"])).toMatch(/Unknown environment "stage".*dev, prod, pr-\*/);
+    expect(unknownEnvError("pr", ["pr-*"])).toMatch(/Unknown environment "pr"/); // prefix alone is not covered
+  });
+
+  test("a literal entry still matches by equality, never as a pattern (#1221)", () => {
+    // `prod` contains no `*`: nothing about pattern support changes it.
+    expect(unknownEnvError("prod", ["prod", "pr-*"])).toBeUndefined();
+    expect(unknownEnvError("production", ["prod"])).toMatch(/Unknown environment "production"/);
+  });
 });
 
 describe("env-aware discovery (#505)", () => {
@@ -87,3 +106,18 @@ describe("env-aware discovery (#505)", () => {
     }
   });
 });
+
+
+describe("isProdLikeEnvironment (#1222)", () => {
+  test("matches prod, production, and separator-delimited variants", () => {
+    for (const name of ["prod", "production", "Prod", "PRODUCTION", "prod-eu", "us-prod", "prod2", "production-east", "eu_prod"]) {
+      expect(isProdLikeEnvironment(name)).toBe(true);
+    }
+  });
+
+  test("does not match names that merely contain the letters", () => {
+    for (const name of ["dev", "staging", "preprod", "product-demo", "reproduction", "pr-123"]) {
+      expect(isProdLikeEnvironment(name)).toBe(false);
+    }
+  });
+});

package/src/env.ts

@@ -18,7 +18,7 @@
  * pinhole renders/diffs them to show environment drift (INTENTIUS/pinhole#3).
  */
 
-import { environmentNames, type EnvironmentDeclaration } from "./config";
+import { environmentNames, matchesDeclaredEnvironment, type EnvironmentDeclaration } from "./config";
 
 /** The environment variable the CLI sets from `--env`. */
 export const ENV_VAR = "CHANT_ENV";
@@ -34,14 +34,28 @@ export function env(fallback?: string): string | undefined {
  * when it's valid (or when the project declares no environments, in which case
  * any name is accepted). `declared` entries may be a bare name or `{ name,
  * endpoint }` (#1166) — {@link environmentNames} reduces either to the names
- * this checks against.
+ * this checks against. An entry containing `*` is a glob pattern (#1221):
+ * `"pr-*"` legalizes every `pr-<n>` environment. Literal entries are checked
+ * first, then patterns — see {@link matchesDeclaredEnvironment}.
  */
 export function unknownEnvError(
   requested: string | undefined,
   declared: EnvironmentDeclaration[] | undefined,
 ): string | undefined {
   if (!requested || !declared || declared.length === 0) return undefined;
+  if (matchesDeclaredEnvironment(declared, requested)) return undefined;
   const names = environmentNames(declared) ?? [];
-  if (names.includes(requested)) return undefined;
   return `Unknown environment "${requested}". Declared environments: ${names.join(", ")}.`;
 }
+
+/**
+ * True when an environment name looks like production — `prod`, `production`,
+ * and separator-delimited variants (`prod-eu`, `us-prod`, `production2`).
+ * `chant lifecycle teardown <env> --yes` demands an extra confirmation for
+ * these (#1222): a typo that survives the declared-environments check should
+ * still not delete production on one flag. Name-shaped, deliberately — chant
+ * has no other signal for which environment is the one that pays the bills.
+ */
+export function isProdLikeEnvironment(name: string): boolean {
+  return /(^|[-_./])prod(uction)?([-_./0-9]|$)/i.test(name);
+}

package/src/lexicon.ts

@@ -11,12 +11,12 @@ import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeAc
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
 import type { EmulatorDeclaration } from "./op/emulator-lifecycle";
-import type { OwnershipChannel } from "./ownership";
+import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
-import type { DescribeResourcesResult } from "./observation";
+import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -540,6 +540,23 @@ export interface LexiconPlugin {
    */
   auditCatalog?(): Record<string, RuleMeta>;
 
+  /**
+   * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
+   *
+   * `coverage()` prints a report for humans; this returns the one fact the
+   * completeness gate cares about: which upstream spec kinds are neither
+   * modeled as declarables nor on the lexicon's exclusion list. fountain held
+   * this line in a lexicon-local vitest assertion (`coverage.test.ts`), which
+   * is a convention rather than a contract — the same class of gap #1342
+   * closed for LSP providers.
+   *
+   * Implementations must work offline from committed snapshots (fountain
+   * reads `spec/fountain-openapi.snapshot.json` plus its surface baseline):
+   * `check-lexicon` runs on every PR, so no network I/O. Omit when the
+   * lexicon has no kind-level spec accounting; the check passes vacuously.
+   */
+  coverageReport?(): Promise<{ unaccountedKinds?: string[] }>;
+
   /** Return intrinsic function definitions */
   intrinsics?(): IntrinsicDef[];
 
@@ -862,6 +879,86 @@ export interface LexiconPlugin {
    */
   describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
 
+  /**
+   * Enumerate the resources this lexicon would delete for one marker identity
+   * (#1222). Opt-in, and read-only here: this method names the would-delete
+   * set, it never deletes. `chant lifecycle teardown <env>` calls it to plan;
+   * the execution half ({@link executeTeardown}) deletes from the same
+   * enumeration.
+   *
+   * Selection is marker-scoped by construction. `marker` carries this
+   * project's ownership stack plus the requested environment, and every
+   * returned candidate must have been read carrying exactly that identity on
+   * this lexicon's marker channel — managed-by present, stack equal, env
+   * equal. A resource whose marker is absent, foreign-stack, or foreign-env is
+   * not a candidate, ever. Core re-checks each candidate's `marker` and drops
+   * mismatches, so a buggy implementation cannot widen the set.
+   *
+   * The #1089 discipline applies: a kind this lexicon stamps but cannot read
+   * back (no reader for the kind, the read errored, no credentials) is a
+   * `hole`, named with a total {@link UnobservedReason} — never silently
+   * absent, because "absent from the plan" reads as "safe", and an unreadable
+   * kind is unknown, not safe.
+   *
+   * A lexicon without this capability still takes part in teardown planning:
+   * core falls back to {@link describeResources} and filters on
+   * {@link ResourceMetadata.marker}. Implement this when that read is the
+   * wrong shape for deletion — aws, whose thin read carries no tags and whose
+   * teardown is stack-level, is the motivating case.
+   */
+  teardownOwned?(options: {
+    environment: string;
+    /** The identity to select on: this project's ownership stack + the env being torn down. */
+    marker: OwnershipMarker;
+    /** Deployed stack name, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Region that stack is deployed in (#1261's contract). */
+    region?: string;
+    /**
+     * Every deployed stack a multi-stack project declares (see `stacks` in
+     * {@link ChantConfig}), for a lexicon whose enumeration is stack-shaped
+     * (aws). When absent or empty, the single-stack convention applies:
+     * `stack`, else the stack named after the environment.
+     */
+    stacks?: Array<{ name: string; region?: string }>;
+  }): Promise<TeardownEnumeration>;
+
+  /**
+   * Delete the teardown candidates core hands over — the execution half of
+   * `chant lifecycle teardown <env> --yes` (#1222). Opt-in, and the sibling of
+   * {@link teardownOwned}: that method names the would-delete set, this one
+   * deletes it. A lexicon that enumerates but does not implement this reports
+   * its candidates as skipped rather than pretending.
+   *
+   * `candidates` is the marker-verified set core computed from the plan — an
+   * implementation deletes those and only those, in whatever order its target
+   * requires (k8s deletes namespaces last; fly deletes apps last). It never
+   * re-widens the set: a live resource not in `candidates` is not this call's
+   * business, whatever its labels say.
+   *
+   * Every candidate gets exactly one outcome per call, keyed by `name`:
+   * `deleted` (including already-gone — deletion is idempotent), `failed`
+   * (the delete errored; core runs one bounded retry pass over these), or
+   * `not-prunable` with a reason (the live object no longer carries the
+   * requested identity, the kind cannot be addressed, the target refuses).
+   * A candidate the implementation says nothing about is reported as failed
+   * by core — silence is never success.
+   */
+  executeTeardown?(options: {
+    environment: string;
+    /** The identity everything was selected on: ownership stack + env. */
+    marker: OwnershipMarker;
+    /** The marker-verified candidates to delete — from {@link teardownOwned} / the plan. */
+    candidates: TeardownCandidate[];
+    /** Deployed stack name, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Region that stack is deployed in (#1261's contract). */
+    region?: string;
+    /** Every declared deployed stack, mirroring {@link teardownOwned} — how a
+     * stack-shaped execution (aws) finds each candidate's region. */
+    stacks?: Array<{ name: string; region?: string }>;
+  }): Promise<TeardownExecution>;
+
   /**
    * Where this lexicon can stamp and read chant's ownership marker (#1348).
    * Data, not a method.
@@ -962,6 +1059,74 @@ export interface LexiconPlugin {
   }): Promise<ExportedTemplate>;
 }
 
+/**
+ * One resource {@link LexiconPlugin.teardownOwned} would delete (#1222).
+ * Identity only — no delete happens on this path.
+ */
+export interface TeardownCandidate {
+  /** chant entity name where a declared mapping exists, else the provider-side name. */
+  name: string;
+  /** Resource type (e.g. "AWS::S3::Bucket", "K8s::Apps::Deployment"). */
+  type: string;
+  /** Provider-side identifier, when the read surfaces one. */
+  physicalId?: string;
+  /**
+   * The stack/env identity read off the resource's own marker — read back,
+   * never inferred. Core verifies it equals the requested identity and drops
+   * the candidate otherwise.
+   */
+  marker: OwnershipMarker;
+}
+
+/**
+ * One kind or entity a teardown enumeration could not read (#1089). A hole is
+ * a claim of ignorance, not of absence: the plan must print it loudly, and the
+ * execution half must refuse to call the env clean while holes exist.
+ */
+export interface TeardownHole {
+  /** The unreadable kind or entity name. */
+  name: string;
+  /** Resource type, when known. */
+  type?: string;
+  /** Total verdict — the same vocabulary the observation envelope uses. */
+  reason: UnobservedReason;
+  /** Human-readable detail: the failing command, the unsupported kind. */
+  detail?: string;
+}
+
+/** What {@link LexiconPlugin.teardownOwned} returns: the would-delete set plus its holes. */
+export interface TeardownEnumeration {
+  candidates: TeardownCandidate[];
+  /** Omit or leave empty when every stamped kind was readable. */
+  holes?: TeardownHole[];
+}
+
+/**
+ * One candidate's fate after {@link LexiconPlugin.executeTeardown} (#1222).
+ * `name` keys it back to the candidate it answers for.
+ */
+export interface TeardownOutcome {
+  /** The candidate's `name`, verbatim. */
+  name: string;
+  /** Resource type, when the implementation carries it through. */
+  type?: string;
+  /** Provider-side identifier, when known. */
+  physicalId?: string;
+  /**
+   * - `deleted` — gone, including already-gone (deletion is idempotent);
+   * - `failed` — the delete errored (core retries these once);
+   * - `not-prunable` — deliberately not deleted; `detail` says why.
+   */
+  outcome: "deleted" | "failed" | "not-prunable";
+  /** The error for `failed`, the reason for `not-prunable`. */
+  detail?: string;
+}
+
+/** What {@link LexiconPlugin.executeTeardown} returns: one outcome per candidate. */
+export interface TeardownExecution {
+  outcomes: TeardownOutcome[];
+}
+
 /**
  * The observation view of a lexicon — every capability except live export.
  *
@@ -1047,6 +1212,21 @@ export interface ResourceMetadata {
    * a delete, and never escalates `unknown` to one.
    */
   ownership?: "owned" | "foreign" | "unknown";
+  /**
+   * The stack/env identity read off the resource's own ownership marker
+   * (#1222) — the tags/labels/metadata chant stamped at synthesis, read back
+   * verbatim on the same channel. This is what marker-scoped selection keys
+   * on: {@link ownership} says "chant's", `marker` says *which* stack and env.
+   *
+   * Set only when the live model actually carries the channel and the
+   * managed-by marker is present — an absent channel means an absent field,
+   * never a guess. In particular aws's thin read is sourced from
+   * `describe-stack-resources`, which returns no tags at all, so aws never
+   * populates this here; aws teardown is stack-level and reads the stack's own
+   * tags instead (later PR). A populated `marker` does not by itself imply an
+   * {@link ownership} verdict on paths that do not declare a marker channel.
+   */
+  marker?: OwnershipMarker;
   /**
    * Where this resource's owner-reference chain leads, for a live resource
    * that is not itself declared (#1077). A lexicon that maintains an

package/src/lifecycle/index.ts

@@ -13,3 +13,4 @@ export * from "./build-ledger";
 export * from "./build-ledger-store";
 export * from "./oras-referrer-lookup";
 export * from "./status";
+export * from "./teardown";