@intentius/chant 0.45.0 → 0.46.0

package/src/lifecycle/teardown.ts

@@ -0,0 +1,357 @@
+/**
+ * Teardown planning (#1222) — the enumeration half of
+ * `chant lifecycle teardown <env>`.
+ *
+ * Answers one question: which live resources carry THIS project's ownership
+ * marker for THIS environment? Selection is marker-scoped by construction —
+ * managed-by present, stack equal to the project's `ownership.stack`, env
+ * equal to the argument — so a foreign stack's resources, another env's
+ * resources, and unmarked resources are out of scope by shape, not by
+ * filtering discipline someone has to remember.
+ *
+ * Stateless: live markers only. No build, no snapshot, no ledger — the
+ * ownership record lives on the cloud resource (see ../ownership.ts), and this
+ * module reads it back from there.
+ *
+ * Two paths per lexicon:
+ * - the `teardownOwned` capability, where the lexicon enumerates its own
+ *   would-delete set (and can use a read shaped for deletion — aws's
+ *   stack-level path, k8s's prune selector);
+ * - a fallback over `describeResources` + the {@link ResourceMetadata.marker}
+ *   field (#1222 PR 1), for lexicons that have not implemented the capability
+ *   yet. Best-effort: a lexicon whose thin read only resolves declared names
+ *   returns nothing here, which the plan reports as a skip, not as clean.
+ *
+ * Whichever path ran, core re-checks every candidate's marker and drops
+ * mismatches — an implementation bug can narrow the set, never widen it.
+ *
+ * The execution half is {@link executeTeardown}: it drives each lexicon's
+ * `executeTeardown` capability over the planned set, then runs one bounded
+ * retry pass over the failures. Both halves are exported as functions —
+ * #1224's test-env harness calls them in-process, not only through the verb.
+ */
+
+import { normalizeObservation, unobservedAll } from "../observation";
+import type { ObservationLexicon, TeardownCandidate, TeardownHole, TeardownOutcome } from "../lexicon";
+import type { OwnershipMarker } from "../ownership";
+
+/** One would-delete row in a teardown plan, attributed to its lexicon. */
+export interface TeardownPlanEntry extends TeardownCandidate {
+  lexicon: string;
+}
+
+/** One hole in a teardown plan (#1089), attributed to its lexicon. */
+export interface TeardownPlanHole extends TeardownHole {
+  lexicon: string;
+}
+
+/** The plan `chant lifecycle teardown <env>` prints and #1224 consumes. */
+export interface TeardownPlan {
+  environment: string;
+  /** The project's ownership stack — the identity everything was selected on. */
+  stack: string;
+  /** The would-delete set. Every entry's marker equals `{ stack, env: environment }`. */
+  entries: TeardownPlanEntry[];
+  /** What could not be read (#1089). A plan with holes is incomplete, not clean. */
+  holes: TeardownPlanHole[];
+  /**
+   * Lexicons that took part in neither path — no `teardownOwned`, no
+   * `describeResources`. Reported so "nothing to delete" can never quietly
+   * mean "nobody looked".
+   */
+  skipped: string[];
+}
+
+export interface PlanTeardownOptions {
+  /** The environment being torn down — the marker env to select on. */
+  environment: string;
+  /** This project's ownership stack (`ownership.stack` in chant.config). */
+  stack: string;
+  plugins: ObservationLexicon[];
+  /** Deployed stack name, for a multi-stack project. */
+  deployedStack?: string;
+  /** Region that stack is deployed in. */
+  region?: string;
+  /**
+   * Every deployed stack a multi-stack project declares (`stacks` in
+   * chant.config), for a lexicon whose teardown is stack-shaped (aws
+   * enumerates and deletes whole stacks). Forwarded to `teardownOwned` /
+   * `executeTeardown` as `stacks`.
+   */
+  deployedStacks?: Array<{ name: string; region?: string }>;
+}
+
+/** True when `marker` is exactly the identity this plan selects on. */
+function markerMatches(marker: OwnershipMarker | undefined, stack: string, env: string): boolean {
+  return marker !== undefined && marker.stack === stack && marker.env === env;
+}
+
+/**
+ * Enumerate what `chant lifecycle teardown <env>` would delete. Read-only —
+ * this function never deletes and never will; execution composes on top of the
+ * plan it returns.
+ */
+export async function planTeardown(opts: PlanTeardownOptions): Promise<TeardownPlan> {
+  const marker: OwnershipMarker = { stack: opts.stack, env: opts.environment };
+  const entries: TeardownPlanEntry[] = [];
+  const holes: TeardownPlanHole[] = [];
+  const skipped: string[] = [];
+
+  for (const plugin of opts.plugins) {
+    if (plugin.teardownOwned) {
+      let enumeration;
+      try {
+        enumeration = await plugin.teardownOwned({
+          environment: opts.environment,
+          marker,
+          ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+          ...(opts.region ? { region: opts.region } : {}),
+          ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+        });
+      } catch (err) {
+        // A failed enumeration is a hole over the whole lexicon, not a clean
+        // lexicon (#1089): nothing was read, so nothing is known.
+        holes.push({
+          lexicon: plugin.name,
+          name: "*",
+          reason: "read-failed",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+        continue;
+      }
+      for (const candidate of enumeration.candidates) {
+        // Defense in depth: the contract says every candidate carries the
+        // requested identity; a candidate that does not is dropped here so an
+        // implementation bug cannot widen the delete set.
+        if (!markerMatches(candidate.marker, opts.stack, opts.environment)) continue;
+        entries.push({ lexicon: plugin.name, ...candidate });
+      }
+      for (const hole of enumeration.holes ?? []) {
+        holes.push({ lexicon: plugin.name, ...hole });
+      }
+      continue;
+    }
+
+    if (plugin.describeResources) {
+      let observed;
+      try {
+        observed = normalizeObservation(
+          await plugin.describeResources({
+            environment: opts.environment,
+            buildOutput: "",
+            entityNames: [],
+            entities: new Map(),
+            owned: true,
+            ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+            ...(opts.region ? { region: opts.region } : {}),
+          }),
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        observed = {
+          resources: {},
+          unobserved: unobservedAll(["*"], "read-failed", message),
+          queried: {},
+          notes: [],
+        };
+      }
+      for (const [name, meta] of Object.entries(observed.resources)) {
+        // Marker-scoped by construction: no marker, foreign stack, or foreign
+        // env means not a candidate — a resource with no readable identity is
+        // never promoted to a delete.
+        if (!markerMatches(meta.marker, opts.stack, opts.environment)) continue;
+        entries.push({
+          lexicon: plugin.name,
+          name,
+          type: meta.type,
+          ...(meta.physicalId ? { physicalId: meta.physicalId } : {}),
+          marker: meta.marker!,
+        });
+      }
+      for (const [name, u] of Object.entries(observed.unobserved)) {
+        holes.push({
+          lexicon: plugin.name,
+          name,
+          ...(u.type ? { type: u.type } : {}),
+          reason: u.reason,
+          ...(u.detail ? { detail: u.detail } : {}),
+        });
+      }
+      continue;
+    }
+
+    skipped.push(plugin.name);
+  }
+
+  entries.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+  return { environment: opts.environment, stack: opts.stack, entries, holes, skipped };
+}
+
+/** One planned entry's fate after execution, attributed to its lexicon. */
+export interface TeardownOutcomeEntry extends TeardownPlanEntry {
+  /**
+   * `skipped` is core's verdict for a candidate whose lexicon implements no
+   * `executeTeardown` yet; the other three come from the lexicon (see
+   * {@link TeardownOutcome}).
+   */
+  outcome: "deleted" | "failed" | "not-prunable" | "skipped";
+  /** The error for `failed`, the reason for `not-prunable`/`skipped`. */
+  detail?: string;
+  /** True when this final outcome came from the bounded retry pass. */
+  retried?: boolean;
+}
+
+/** What `chant lifecycle teardown <env> --yes` prints and #1224 consumes. */
+export interface TeardownReport {
+  environment: string;
+  stack: string;
+  /** The plan that was executed — holes and skipped lexicons included. */
+  plan: TeardownPlan;
+  /** One row per planned entry. Never fewer: silence is never success. */
+  outcomes: TeardownOutcomeEntry[];
+  /** Lexicons whose candidates were skipped for lack of an `executeTeardown`. */
+  unimplemented: string[];
+}
+
+export interface ExecuteTeardownOptions extends PlanTeardownOptions {
+  /**
+   * A plan already computed (the one just shown to the user). Recomputed from
+   * a fresh live read when omitted.
+   */
+  plan?: TeardownPlan;
+}
+
+/**
+ * Run one execution pass over a lexicon's candidates and return exactly one
+ * outcome per candidate: what the lexicon reported, `failed` for anything it
+ * stayed silent about, and `failed` across the board when the call threw.
+ * Outcomes the lexicon volunteers for names core never asked about are
+ * dropped — an implementation cannot widen the set by reporting on it.
+ */
+async function executePass(
+  plugin: ObservationLexicon,
+  candidates: TeardownCandidate[],
+  opts: ExecuteTeardownOptions,
+  marker: OwnershipMarker,
+): Promise<Map<string, TeardownOutcome>> {
+  const byName = new Map<string, TeardownOutcome>();
+  let reported: TeardownOutcome[];
+  try {
+    const execution = await plugin.executeTeardown!({
+      environment: opts.environment,
+      marker,
+      candidates,
+      ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+      ...(opts.region ? { region: opts.region } : {}),
+      ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+    });
+    reported = execution.outcomes;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    for (const candidate of candidates) {
+      byName.set(candidate.name, { name: candidate.name, outcome: "failed", detail });
+    }
+    return byName;
+  }
+  const asked = new Set(candidates.map((c) => c.name));
+  for (const outcome of reported) {
+    if (!asked.has(outcome.name)) continue;
+    byName.set(outcome.name, outcome);
+  }
+  for (const candidate of candidates) {
+    if (byName.has(candidate.name)) continue;
+    byName.set(candidate.name, {
+      name: candidate.name,
+      outcome: "failed",
+      detail: "the lexicon reported no outcome for this candidate",
+    });
+  }
+  return byName;
+}
+
+/**
+ * Execute a teardown: delete every planned candidate through its lexicon's
+ * `executeTeardown`, then retry the failures once. Per-lexicon ordering only —
+ * each lexicon deletes its own set in the order its target requires (k8s
+ * deletes namespaces last, fly deletes apps last); there is no global
+ * reverse-dependency ordering in v1, the bounded retry pass covers the
+ * cross-lexicon cases it would.
+ *
+ * Every planned entry comes back with an outcome. A lexicon that enumerates
+ * but implements no execution reports its candidates as `skipped` — loudly,
+ * never as clean. Failures that survive the retry stay `failed` in the
+ * report; nothing here ever swallows one.
+ */
+export async function executeTeardown(opts: ExecuteTeardownOptions): Promise<TeardownReport> {
+  const marker: OwnershipMarker = { stack: opts.stack, env: opts.environment };
+  const plan = opts.plan ?? (await planTeardown(opts));
+
+  const byLexicon = new Map<string, TeardownPlanEntry[]>();
+  for (const entry of plan.entries) {
+    const list = byLexicon.get(entry.lexicon) ?? [];
+    list.push(entry);
+    byLexicon.set(entry.lexicon, list);
+  }
+
+  const outcomes: TeardownOutcomeEntry[] = [];
+  const unimplemented: string[] = [];
+
+  // Plugin registration order, so a project's lexicon ordering is stable.
+  for (const plugin of opts.plugins) {
+    const entries = byLexicon.get(plugin.name);
+    if (!entries) continue;
+    byLexicon.delete(plugin.name);
+
+    if (!plugin.executeTeardown) {
+      unimplemented.push(plugin.name);
+      for (const entry of entries) {
+        outcomes.push({
+          ...entry,
+          outcome: "skipped",
+          detail: `the ${plugin.name} lexicon does not implement teardown execution yet`,
+        });
+      }
+      continue;
+    }
+
+    const candidates: TeardownCandidate[] = entries.map(({ lexicon: _lexicon, ...candidate }) => candidate);
+    const first = await executePass(plugin, candidates, opts, marker);
+
+    // One bounded retry pass over this lexicon's failures — transient errors
+    // and ordering hiccups get a second chance, nothing gets an infinite one.
+    const failedNames = new Set(
+      [...first.values()].filter((o) => o.outcome === "failed").map((o) => o.name),
+    );
+    const retried =
+      failedNames.size > 0
+        ? await executePass(plugin, candidates.filter((c) => failedNames.has(c.name)), opts, marker)
+        : new Map<string, TeardownOutcome>();
+
+    for (const entry of entries) {
+      const second = retried.get(entry.name);
+      const outcome = second ?? first.get(entry.name)!;
+      outcomes.push({
+        ...entry,
+        outcome: outcome.outcome,
+        ...(outcome.detail !== undefined ? { detail: outcome.detail } : {}),
+        ...(second !== undefined ? { retried: true } : {}),
+      });
+    }
+  }
+
+  // A planned entry attributed to a lexicon that is not in `plugins` at
+  // execution time (a plan handed in from elsewhere). Nobody can delete it,
+  // and silence is never success.
+  for (const entries of byLexicon.values()) {
+    for (const entry of entries) {
+      outcomes.push({
+        ...entry,
+        outcome: "skipped",
+        detail: `no loaded lexicon named "${entry.lexicon}" to execute this candidate`,
+      });
+    }
+  }
+
+  outcomes.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+  return { environment: opts.environment, stack: opts.stack, plan, outcomes, unimplemented };
+}

package/src/lint/engine.ts

@@ -1,4 +1,4 @@
-import type { LintRule, LintDiagnostic, LintContext } from "./rule";
+import type { LintRule, LintDiagnostic, LintContext, LintProjectConfig } from "./rule";
 import type { IntrinsicDef } from "../lexicon";
 import { parseFile } from "./parser";
 import { readFileSync } from "fs";
@@ -203,6 +203,10 @@ function isDiagnosticDisabled(
  *   `IntrinsicDef[]` into the fold path since #1039/#1105. Optional and
  *   defaulting to none, so a caller that hasn't resolved a project's
  *   lexicons (a unit test, `bench.test.ts`) is unaffected.
+ * @param projectConfig - chant #1221 — the project's config slice for
+ *   config-aware rules (COR021 reads `environments` + `ownership`), put on
+ *   every file's `LintContext.projectConfig`. Optional; without it those
+ *   rules stay silent.
  * @returns LintRunResult with diagnostics and suppressed items
  */
 export async function runLint(
@@ -210,6 +214,7 @@ export async function runLint(
   rules: LintRule[],
   ruleOptions?: Map<string, Record<string, unknown>>,
   intrinsics?: readonly IntrinsicDef[],
+  projectConfig?: LintProjectConfig,
 ): Promise<LintRunResult> {
   const allDiagnostics: LintDiagnostic[] = [];
   const allSuppressed: Array<LintDiagnostic & { reason?: string }> = [];
@@ -231,6 +236,7 @@ export async function runLint(
         filePath,
         lexicon: undefined,
         intrinsics,
+        projectConfig,
       };
 
       // Execute each rule

package/src/lint/rule.ts

@@ -49,6 +49,21 @@ export interface LintDiagnostic {
   fix?: LintFix;
 }
 
+/**
+ * The slice of the project's `chant.config` a config-aware rule reads
+ * (#1221) — threaded into {@link LintContext} by `runLint` when the caller
+ * resolved the project's config (`chant lint` does; a bare unit test or the
+ * LSP's single-file lint may not). Structurally mirrors the corresponding
+ * `ChantConfig` fields (../config.ts) without importing them, so `rule.ts`
+ * stays dependency-light for lexicon rule authors.
+ */
+export interface LintProjectConfig {
+  /** Declared environments — a bare name or `{ name, endpoint }` (#1166). */
+  environments?: Array<string | { name: string; endpoint?: string }>;
+  /** Ownership marking config — `env` is a literal or a build-parameter reference (#1396). */
+  ownership?: { stack?: string; env?: string | { param: string }; enabled?: boolean };
+}
+
 /**
  * Context provided to lint rules during checking
  */
@@ -74,6 +89,14 @@ export interface LintContext {
    * call is a violation.
    */
   intrinsics?: readonly IntrinsicDef[];
+  /**
+   * chant #1221 — the project's resolved config slice for config-aware rules
+   * (COR021 reads `environments` + `ownership`). Threaded from `runLint`;
+   * undefined when the caller never loaded a project config (a unit test
+   * constructing a context directly, the LSP's single-file path), in which
+   * case config-aware rules stay silent.
+   */
+  projectConfig?: LintProjectConfig;
 }
 
 /**

package/src/lint/rules/cor021-env-literal-name.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
+import type { LintContext, LintProjectConfig } from "../rule";
+
+const MULTI_ENV_PARAM_BOUND: LintProjectConfig = {
+  environments: ["dev", "prod"],
+  ownership: { stack: "billing", env: { param: "env" } },
+};
+
+function createContext(code: string, projectConfig?: LintProjectConfig, filePath = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath, lexicon: undefined, projectConfig };
+}
+
+describe("COR021: literal name in a multi-environment project (#1221)", () => {
+  test("rule metadata", () => {
+    expect(cor021EnvLiteralNameRule.id).toBe("COR021");
+    expect(cor021EnvLiteralNameRule.severity).toBe("warning");
+    expect(cor021EnvLiteralNameRule.category).toBe("correctness");
+  });
+
+  test("flags a bare string literal in a *Name property", () => {
+    const ctx = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      MULTI_ENV_PARAM_BOUND,
+    );
+    const diags = cor021EnvLiteralNameRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR021");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain('"billing-uploads"');
+    expect(diags[0].message).toContain("params.env");
+  });
+
+  test("flags a bare `name` property, nested objects included", () => {
+    const ctx = createContext(
+      `export const svc = new Service({ metadata: { name: "web" } });`,
+      MULTI_ENV_PARAM_BOUND,
+    );
+    const diags = cor021EnvLiteralNameRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('name: "web"');
+  });
+
+  test("flags a no-substitution template literal the same as a string literal", () => {
+    const ctx = createContext(
+      "export const uploads = new Bucket({ bucketName: `billing-uploads` });",
+      MULTI_ENV_PARAM_BOUND,
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(1);
+  });
+
+  test("passes a template literal interpolating the env parameter", () => {
+    const ctx = createContext(
+      "export const uploads = new Bucket({ bucketName: `billing-${params.env}-uploads` });",
+      MULTI_ENV_PARAM_BOUND,
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("passes non-name properties and non-literal name values", () => {
+    const ctx = createContext(
+      `
+        const shared = { prefix: "billing" };
+        export const uploads = new Bucket({ bucketName: shared.prefix, region: "us-east-1" });
+      `,
+      MULTI_ENV_PARAM_BOUND,
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("silent when ownership.env is a literal", () => {
+    const ctx = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      { environments: ["dev", "prod"], ownership: { stack: "billing", env: "prod" } },
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("silent when ownership.env is absent", () => {
+    const ctx = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      { environments: ["dev", "prod"], ownership: { stack: "billing" } },
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("silent with fewer than two declared environments", () => {
+    const oneEnv = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      { environments: ["prod"], ownership: { stack: "billing", env: { param: "env" } } },
+    );
+    expect(cor021EnvLiteralNameRule.check(oneEnv)).toHaveLength(0);
+
+    const noEnvs = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      { ownership: { stack: "billing", env: { param: "env" } } },
+    );
+    expect(cor021EnvLiteralNameRule.check(noEnvs)).toHaveLength(0);
+  });
+
+  test("silent without a project config on the context", () => {
+    const ctx = createContext(`export const uploads = new Bucket({ bucketName: "billing-uploads" });`);
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("names the bound parameter, whatever it is called", () => {
+    const ctx = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      { environments: ["dev", "prod"], ownership: { stack: "billing", env: { param: "stage" } } },
+    );
+    const diags = cor021EnvLiteralNameRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("params.stage");
+  });
+
+  test("object-form environments entries count toward the threshold", () => {
+    const ctx = createContext(
+      `export const uploads = new Bucket({ bucketName: "billing-uploads" });`,
+      {
+        environments: ["prod", { name: "floci", endpoint: "http://localhost:4566" }],
+        ownership: { stack: "billing", env: { param: "env" } },
+      },
+    );
+    expect(cor021EnvLiteralNameRule.check(ctx)).toHaveLength(1);
+  });
+});

package/src/lint/rules/cor021-env-literal-name.ts

@@ -0,0 +1,114 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic, LintProjectConfig } from "../rule";
+
+/**
+ * COR021: Literal Name in a Multi-Environment Project (#1221)
+ *
+ * A project that declares two or more `environments` and binds its ownership
+ * marker to a build parameter (`ownership.env: { param: "env" }`) is built
+ * once per environment — and every physical name that does not vary with
+ * that parameter is the SAME name in every build. The collision is silent at
+ * build time and only surfaces at apply time, when the second environment's
+ * deploy walks over the first's resources.
+ *
+ * This rule warns on the declaration: a name-bearing property (`name`, or a
+ * `*Name` property like `bucketName`) whose value is a bare string literal,
+ * in a project shaped for per-environment builds. The fix is interpolation —
+ * `` `billing-${params.env}-uploads` `` — which folds to a per-environment
+ * literal because build parameters resolve before any file is imported
+ * (#1064). See the resource-naming guide's multi-environment section.
+ *
+ * Deliberately silent when:
+ * - no project config was threaded (a bare unit test, the LSP single-file path),
+ * - the project declares fewer than two environments (nothing to collide),
+ * - `ownership.env` is not param-bound — a literal `ownership.env` (or none)
+ *   means the project is not doing per-environment builds from one source
+ *   tree, so per-instance names are presumably managed another way (the
+ *   layered-config all-in-one pattern hand-names each instance),
+ * - the value is anything other than a bare string literal — a template
+ *   interpolating `params.<name>` is the fixed shape, and other non-literal
+ *   values are EVL territory, not this rule's.
+ */
+
+/** Does this property name carry a physical resource name — `name` or a camelCase `*Name`? */
+function isNameBearingProperty(propName: string): boolean {
+  return propName === "name" || /^[a-z][A-Za-z0-9]*Name$/.test(propName);
+}
+
+/** The property's declared name, for Identifier and string-literal keys; undefined for computed keys. */
+function propertyName(prop: ts.PropertyAssignment): string | undefined {
+  if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) return prop.name.text;
+  return undefined;
+}
+
+/** Whether the rule's preconditions hold: 2+ declared environments and a param-bound ownership.env. */
+function projectIsMultiEnvParamBound(config: LintProjectConfig | undefined): string | undefined {
+  const env = config?.ownership?.env;
+  const paramBound = typeof env === "object" && env !== null && typeof env.param === "string";
+  if (!paramBound) return undefined;
+  if ((config?.environments?.length ?? 0) < 2) return undefined;
+  return env.param;
+}
+
+/** Walk an object literal (nested included, e.g. k8s `metadata: { name }`), flagging literal name-bearing values. */
+function checkObjectLiteral(
+  obj: ts.ObjectLiteralExpression,
+  paramName: string,
+  context: LintContext,
+  diagnostics: LintDiagnostic[],
+): void {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const name = propertyName(prop);
+    const value = prop.initializer;
+    if (
+      name !== undefined &&
+      isNameBearingProperty(name) &&
+      (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))
+    ) {
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        value.getStart(context.sourceFile),
+      );
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR021",
+        severity: "warning",
+        message:
+          `Literal ${name}: "${value.text}" in a multi-environment project — every environment's build ` +
+          `produces this same physical name, so two deployed environments collide. Interpolate the env ` +
+          `parameter: \`${value.text}-\${params.${paramName}}\` (see the resource-naming guide's ` +
+          `multi-environment section).`,
+      });
+    }
+    if (ts.isObjectLiteralExpression(value)) {
+      checkObjectLiteral(value, paramName, context, diagnostics);
+    }
+  }
+}
+
+function checkNode(node: ts.Node, paramName: string, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isNewExpression(node) && node.arguments && node.arguments.length > 0) {
+    const firstArg = node.arguments[0];
+    if (ts.isObjectLiteralExpression(firstArg)) {
+      checkObjectLiteral(firstArg, paramName, context, diagnostics);
+    }
+  }
+  ts.forEachChild(node, (child) => checkNode(child, paramName, context, diagnostics));
+}
+
+export const cor021EnvLiteralNameRule: LintRule = {
+  id: "COR021",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "In a multi-environment project with a param-bound ownership.env, name-bearing properties should interpolate the env parameter, not hold a bare literal",
+  check(context: LintContext): LintDiagnostic[] {
+    const paramName = projectIsMultiEnvParamBound(context.projectConfig);
+    if (paramName === undefined) return [];
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, paramName, context, diagnostics);
+    return diagnostics;
+  },
+};