@intentius/chant 0.13.0 → 0.15.0

package/src/lint/rules/comp/comp.test.ts

@@ -0,0 +1,378 @@
+/**
+ * COMP* composition lint rule tests (#562, epic #551).
+ *
+ * Each rule gets one passing and one failing fixture directory under
+ * ../__fixtures__/comp/<ruleId>/{pass,fail}/ — real `*.component.ts` files
+ * discovered the same way `chant lint` discovers them (via
+ * ../../component-checks.ts's `runComponentChecks`, itself
+ * `../../../components/discover.ts`'s `discoverComponents` plus every
+ * `ComponentCheck`). Each fixture directory is its own tiny "project" so
+ * cross-component rules (COMP002, COMP007) only see the components meant for
+ * that specific case.
+ */
+
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runComponentChecks } from "../../component-checks";
+import type { RollbackPolicy } from "../../../components/capability";
+import { loadComponentChecks } from "./index";
+
+const FIXTURES_DIR = join(import.meta.dirname, "..", "__fixtures__", "comp");
+const checks = loadComponentChecks();
+
+/**
+ * Rollback dispositions the COMP003 fixtures reference, standing in for what
+ * `chant lint` derives from the project's registry (`cfn-deploy` has a native
+ * `rollback`; `run-migration` declares `needs-opt-out` in the aws lexicon).
+ */
+const FIXTURE_ROLLBACK_POLICIES = new Map<string, RollbackPolicy>([
+  ["cfn-deploy", "native"],
+  ["run-migration", "needs-opt-out"],
+]);
+
+async function lintFixture(
+  ruleId: string,
+  kind: "pass" | "fail",
+  registryContext?: { knownKinds?: ReadonlySet<string>; rollbackPolicies?: ReadonlyMap<string, RollbackPolicy> },
+) {
+  const dir = join(FIXTURES_DIR, ruleId.toLowerCase(), kind);
+  return runComponentChecks(dir, checks, registryContext);
+}
+
+describe("COMP000: component discovery errors", () => {
+  it("surfaces a duplicate component name as a COMP000 diagnostic instead of silently dropping it", async () => {
+    const dir = join(FIXTURES_DIR, "comp000-discovery-error");
+    const diagnostics = await runComponentChecks(dir, checks);
+    const hits = diagnostics.filter((d) => d.checkId === "COMP000");
+    expect(hits.length).toBeGreaterThan(0);
+    expect(hits[0].severity).toBe("error");
+    expect(hits[0].message).toContain("Duplicate component name");
+  });
+});
+
+describe("loadComponentChecks()", () => {
+  it("returns all seven COMP* checks, sorted by id, each error or warning severity", () => {
+    expect(checks.map((c) => c.id)).toEqual([
+      "COMP001",
+      "COMP002",
+      "COMP003",
+      "COMP004",
+      "COMP005",
+      "COMP006",
+      "COMP007",
+    ]);
+    for (const check of checks) {
+      expect(["error", "warning"]).toContain(check.severity);
+      expect(typeof check.description).toBe("string");
+      expect(check.description.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("COMP001: publishes-but-never-applies", () => {
+  it("flags a publish step whose output nothing ever consumes", async () => {
+    const diagnostics = await lintFixture("comp001", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP001");
+    expect(hits).toHaveLength(1);
+    expect(hits[0].component).toBe("orphan-lib");
+    expect(hits[0].message).toContain("never consumed");
+  });
+
+  it("does not flag a publish step consumed by a downstream component", async () => {
+    const diagnostics = await lintFixture("comp001", "pass");
+    expect(diagnostics.filter((d) => d.checkId === "COMP001")).toHaveLength(0);
+  });
+});
+
+describe("COMP002: dangling-wiring-ref", () => {
+  it("flags a @Phase.field reference to a nonexistent phase and a @component.publish.* reference to an undiscovered component", async () => {
+    const diagnostics = await lintFixture("comp002", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP002");
+    expect(hits.length).toBeGreaterThanOrEqual(2);
+    expect(hits.some((d) => d.message.includes('"@Build.digest"'))).toBe(true);
+    expect(hits.some((d) => d.message.includes('"@missing-lib.publish.uri"'))).toBe(true);
+  });
+
+  it("does not flag references that resolve to a real phase/dependency", async () => {
+    const diagnostics = await lintFixture("comp002", "pass");
+    expect(diagnostics.filter((d) => d.checkId === "COMP002")).toHaveLength(0);
+  });
+
+  it("flags a cross-component reference to a component missing from dependsOn", async () => {
+    // Reuses the pass fixture's components but confirms the dependsOn check
+    // specifically by asserting the pass fixture's searchService (which DOES
+    // list jar-lib in dependsOn) produces no COMP002 hit for that reference.
+    const diagnostics = await lintFixture("comp002", "pass");
+    const jarRefHits = diagnostics.filter(
+      (d) => d.checkId === "COMP002" && d.message.includes("jar-lib"),
+    );
+    expect(jarRefHits).toHaveLength(0);
+  });
+});
+
+describe("COMP003: mutating-no-rollback", () => {
+  it("flags a mutating step (run-migration) with no native rollback and no opt-out", async () => {
+    const diagnostics = await lintFixture("comp003", "fail", { rollbackPolicies: FIXTURE_ROLLBACK_POLICIES });
+    const hits = diagnostics.filter((d) => d.checkId === "COMP003");
+    expect(hits).toHaveLength(1);
+    expect(hits[0].component).toBe("migrator");
+    expect(hits[0].message).toContain("run-migration");
+  });
+
+  it("does not flag a step with a native rollback (cfn-deploy) or an explicit noRollback opt-out", async () => {
+    const diagnostics = await lintFixture("comp003", "pass", { rollbackPolicies: FIXTURE_ROLLBACK_POLICIES });
+    expect(diagnostics.filter((d) => d.checkId === "COMP003")).toHaveLength(0);
+  });
+
+  it("flags a needs-opt-out step nested inside a fan-out phase, not just top-level phases", () => {
+    // Regression test: the rule used to iterate component.deploy directly and
+    // never recursed into nested Phase entries (a fan-out unit, e.g. the
+    // Neo4j pilot's per-instance phases), so a mutating step buried inside one
+    // was silently skipped. It must now use the same walkComponent traversal
+    // every other COMP rule uses.
+    const [comp003] = checks.filter((c) => c.id === "COMP003");
+    const ctx = {
+      rollbackPolicies: FIXTURE_ROLLBACK_POLICIES,
+      components: new Map([
+        [
+          "fanout-cluster",
+          {
+            component: {
+              name: "fanout-cluster",
+              dependsOn: [],
+              deploy: [
+                {
+                  phase: "Rolling",
+                  steps: [
+                    {
+                      phase: "Node 1",
+                      steps: [{ kind: "run-migration", tool: "flyway", target: "node-1" }],
+                    },
+                  ],
+                },
+              ],
+            },
+            filePath: "fanout-cluster.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp003.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].component).toBe("fanout-cluster");
+    expect(diagnostics[0].message).toContain("run-migration");
+  });
+
+  it("a compensation sibling only counts within the same nested phase, not a same-named sibling phase elsewhere in the component", () => {
+    // Two different "Node" phases both contain a run-migration step; only the
+    // second one has a rollback-previous sibling. The first must still be
+    // flagged — object identity, not phase-name string, decides "same phase".
+    const [comp003] = checks.filter((c) => c.id === "COMP003");
+    const ctx = {
+      rollbackPolicies: FIXTURE_ROLLBACK_POLICIES,
+      components: new Map([
+        [
+          "fanout-cluster",
+          {
+            component: {
+              name: "fanout-cluster",
+              dependsOn: [],
+              deploy: [
+                { phase: "Node A", steps: [{ kind: "run-migration", tool: "flyway", target: "a" }] },
+                {
+                  phase: "Node B",
+                  steps: [
+                    { kind: "run-migration", tool: "flyway", target: "b" },
+                    { kind: "rollback-previous", resource: "b" },
+                  ],
+                },
+              ],
+            },
+            filePath: "fanout-cluster.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp003.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain('phase "Node A"');
+  });
+});
+
+describe("COMP004: gate-needs-temporal", () => {
+  it("flags a gate step with no disable directive", async () => {
+    const diagnostics = await lintFixture("comp004", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP004");
+    expect(hits).toHaveLength(1);
+    expect(hits[0].component).toBe("neo4j-cluster");
+    expect(hits[0].message).toContain("gate");
+  });
+
+  it("does not flag a component with no gate steps", async () => {
+    const diagnostics = await lintFixture("comp004", "pass");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP004" && d.component !== "neo4j-cluster");
+    expect(hits).toHaveLength(0);
+  });
+
+  it("still raises the raw diagnostic for a gate with a file-level disable directive — runComponentChecks does not itself apply disable-directive filtering (that is the chant lint CLI layer's job, see ../../../cli/commands/component-lint.test.ts)", async () => {
+    const diagnostics = await lintFixture("comp004", "pass");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP004" && d.component === "neo4j-cluster");
+    expect(hits).toHaveLength(1);
+  });
+});
+
+describe("COMP005: capability-kind-is-noun", () => {
+  it("flags a step kind named after the component itself", async () => {
+    const diagnostics = await lintFixture("comp005", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP005");
+    expect(hits).toHaveLength(1);
+    expect(hits[0].message).toContain("deploy-search-service");
+  });
+
+  it("does not flag verb-named capability kinds", async () => {
+    const diagnostics = await lintFixture("comp005", "pass");
+    expect(diagnostics.filter((d) => d.checkId === "COMP005")).toHaveLength(0);
+  });
+
+  it("regression: never flags a registered verb, even when a component's name is a substring of it (e.g. a component named \"stack\")", () => {
+    // A component literally named "stack", "job", "image", or "host" must not
+    // falsely flag wait-for-stack / emr-start-job-run / publish-image /
+    // load-image-on-host by dash-segment substring collision. `ctx.knownKinds`
+    // is what `chant lint` passes for an aws-active project — the registry's
+    // resolved kinds, which include these lexicon leaves.
+    const [comp005] = checks.filter((c) => c.id === "COMP005");
+    const knownKinds = new Set([
+      "docker-build",
+      "wait-for-stack",
+      "emr-start-job-run",
+      "publish-image",
+      "load-image-on-host",
+    ]);
+    const ctx = {
+      knownKinds,
+      components: new Map([
+        [
+          "stack",
+          {
+            component: {
+              name: "stack",
+              dependsOn: [],
+              deploy: [{ phase: "Verify", steps: [{ kind: "wait-for-stack", stack: "stack" }] }],
+            },
+            filePath: "stack.component.ts",
+          },
+        ],
+        [
+          "job",
+          {
+            component: {
+              name: "job",
+              dependsOn: [],
+              deploy: [{ phase: "Submit", steps: [{ kind: "emr-start-job-run", jar: "x" }] }],
+            },
+            filePath: "job.component.ts",
+          },
+        ],
+        [
+          "image",
+          {
+            component: {
+              name: "image",
+              dependsOn: [],
+              build: { kind: "docker-build" },
+              deploy: [{ phase: "Publish", steps: [{ kind: "publish-image", from: "a", to: "b" }] }],
+            },
+            filePath: "image.component.ts",
+          },
+        ],
+        [
+          "host",
+          {
+            component: {
+              name: "host",
+              dependsOn: [],
+              deploy: [{ phase: "Publish", steps: [{ kind: "load-image-on-host", from: "a", host: "b" }] }],
+            },
+            filePath: "host.component.ts",
+          },
+        ],
+      ]),
+    };
+    expect(comp005.check(ctx as never)).toEqual([]);
+  });
+
+  it("falls back to the core starter set when no registry (knownKinds) was resolved — a core verb whose name overlaps a component is still not flagged", () => {
+    const [comp005] = checks.filter((c) => c.id === "COMP005");
+    const ctx = {
+      // no knownKinds -> fall back to core starter (includes wait-cluster-healthy)
+      components: new Map([
+        [
+          "cluster",
+          {
+            component: {
+              name: "cluster",
+              dependsOn: [],
+              deploy: [{ phase: "Verify", steps: [{ kind: "wait-cluster-healthy", size: 1 }] }],
+            },
+            filePath: "cluster.component.ts",
+          },
+        ],
+      ]),
+    };
+    expect(comp005.check(ctx as never)).toEqual([]);
+  });
+
+  it("without a resolved registry, an active-lexicon verb it can't know about IS flagged when it collides with a component name (registry-driven, not hard-coded)", () => {
+    const [comp005] = checks.filter((c) => c.id === "COMP005");
+    const ctx = {
+      // no knownKinds -> `wait-for-stack` is not a core verb, so for a component
+      // literally named "stack" it reads as a noun-collision. A real `chant lint`
+      // run passes knownKinds and avoids this; this documents the fallback edge.
+      components: new Map([
+        [
+          "stack",
+          {
+            component: {
+              name: "stack",
+              dependsOn: [],
+              deploy: [{ phase: "Verify", steps: [{ kind: "wait-for-stack", stack: "stack" }] }],
+            },
+            filePath: "stack.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp005.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].checkId).toBe("COMP005");
+  });
+});
+
+describe("COMP006: shell-needs-reason", () => {
+  it('flags a "shell" step with no reason', async () => {
+    const diagnostics = await lintFixture("comp006", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP006");
+    expect(hits).toHaveLength(1);
+    expect(hits[0].component).toBe("legacy-tool");
+  });
+
+  it('does not flag a "shell" step with a declared reason', async () => {
+    const diagnostics = await lintFixture("comp006", "pass");
+    expect(diagnostics.filter((d) => d.checkId === "COMP006")).toHaveLength(0);
+  });
+});
+
+describe("COMP007: composition-sprawl", () => {
+  it("flags two components with an identical phase/step-kind composition shape", async () => {
+    const diagnostics = await lintFixture("comp007", "fail");
+    const hits = diagnostics.filter((d) => d.checkId === "COMP007");
+    expect(hits).toHaveLength(2);
+    expect(hits.map((d) => d.component).sort()).toEqual(["inventory-table", "orders-table"]);
+    expect(hits[0].severity).toBe("warning");
+  });
+
+  it("does not flag structurally distinct components", async () => {
+    const diagnostics = await lintFixture("comp007", "pass");
+    expect(diagnostics.filter((d) => d.checkId === "COMP007")).toHaveLength(0);
+  });
+});

package/src/lint/rules/comp/comp001-publishes-never-applies.ts

@@ -0,0 +1,78 @@
+/**
+ * COMP001: publishes-but-never-applies
+ *
+ * Flags a component that publishes an image/artifact (a `publish-image`,
+ * `publish-artifact`, or `load-image-on-host` step) that nothing ever
+ * consumes: neither an apply/submit step later in the same component (via a
+ * `@Phase.field` prior-step reference into the publish phase) nor any other
+ * component (via `@<this-component>.publish.uri|digest|key`). A publish step
+ * with no consumer either belongs to a producer/library component another
+ * component should depend on, or is dead composition — see epic #551 §7
+ * ("What chant adds") and §"Failure modes" (renamed/orphaned sprawl).
+ *
+ * Triggers on: a `service`-shaped component whose `publish-image` output is
+ * never referenced by its own Apply phase or by any sibling component.
+ * OK: the publish output is referenced via `@Publish.digest` (same
+ * component) or `@<name>.publish.uri` (a consumer component).
+ */
+
+import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
+import { collectWiringRefs, walkComponent } from "./support";
+
+const PUBLISH_KIND = /^(publish-image|publish-artifact|load-image-on-host)$/;
+
+export const comp001PublishesNeverAppliesRule: ComponentCheck = {
+  id: "COMP001",
+  severity: "error",
+  category: "correctness",
+  description: "A publish step's output is never consumed by an apply/submit step, in this component or any other",
+  check(ctx: ComponentCheckContext): ComponentCheckDiagnostic[] {
+    const diagnostics: ComponentCheckDiagnostic[] = [];
+
+    // Every `@<name>.publish.*` reference anywhere across every discovered
+    // component — a publish step in component X is "consumed" if some
+    // component (including X itself, via `@Phase.field`) references it.
+    const referencedComponentPublishes = new Set<string>();
+    for (const { component } of ctx.components.values()) {
+      const { steps } = walkComponent(component);
+      for (const { step } of steps) {
+        for (const ref of collectWiringRefs(step)) {
+          if (ref.kind === "component-artifact") referencedComponentPublishes.add(ref.componentName);
+        }
+      }
+    }
+
+    for (const [name, { component, filePath }] of ctx.components) {
+      const { steps } = walkComponent(component);
+      const publishSteps = steps.filter(({ step }) => PUBLISH_KIND.test(step.kind));
+      if (publishSteps.length === 0) continue;
+
+      // Consumed if: (a) some other/same component references
+      // `@<name>.publish.*`, or (b) a same-component prior-step reference
+      // points at the publish step's own phase (e.g. `@Publish.digest` used
+      // by a later Apply step in the same component).
+      if (referencedComponentPublishes.has(name)) continue;
+
+      const publishPhaseNames = new Set(publishSteps.map(({ phaseName }) => phaseName));
+      const consumedByPriorStepRef = steps.some(({ step }) =>
+        collectWiringRefs(step).some((ref) => ref.kind === "prior-step" && publishPhaseNames.has(ref.phaseName)),
+      );
+      if (consumedByPriorStepRef) continue;
+
+      diagnostics.push({
+        checkId: "COMP001",
+        severity: "error",
+        component: name,
+        file: filePath,
+        message:
+          `Component "${name}" publishes an artifact (${[...publishPhaseNames].join(", ")} phase) that is never ` +
+          `consumed — no apply/submit step in this component references it via "@${[...publishPhaseNames][0]}.<field>", ` +
+          `and no other component references "@${name}.publish.<field>". If this is a producer/library ` +
+          `component, a consumer should depend on it and reference its publish output; otherwise this publish step ` +
+          `is dead composition.`,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/comp/comp002-dangling-wiring-ref.ts

@@ -0,0 +1,94 @@
+/**
+ * COMP002: dangling-wiring-ref
+ *
+ * Flags a wiring reference (`@Phase.field` or `@<component>.publish.*`,
+ * carried in a step's `imageRef`/`jar`/`revision`/`inputs`/any other
+ * capability-specific field — see ../../../components/component.ts's
+ * `Wiring`) that points at a phase or component that does not exist:
+ *
+ *  - `@Phase.field` naming a phase not declared anywhere in this component's
+ *    own `deploy` (top-level phase names only — a nested fan-out phase's
+ *    name is addressed by its own name, never a parent's, matching how
+ *    ../../../components/driver.ts's `resolveWiring` keys `phaseOutputs` by
+ *    the phase the step ran directly under).
+ *  - `@<component>.publish.<field>` naming a component that either is not
+ *    discovered at all, or is discovered but not listed in this component's
+ *    `dependsOn` — the graph only resolves an artifact reference for a
+ *    declared dependency (composition-and-wiring.mdx#cross-component-outputs).
+ *
+ * Triggers on: `imageRef: "@Build.digest"` when no phase named "Build"
+ * exists, or `jar: "@some-lib.publish.uri"` when "some-lib" is undiscovered
+ * or missing from `dependsOn`.
+ * OK: `imageRef: "@Publish.digest"` when a "Publish" phase exists in the same
+ * component, or `jar: "@jar-lib.publish.uri"` when "jar-lib" is discovered
+ * and listed in `dependsOn`.
+ */
+
+import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
+import { collectWiringRefs, topLevelPhaseNames, walkComponent } from "./support";
+
+export const comp002DanglingWiringRefRule: ComponentCheck = {
+  id: "COMP002",
+  severity: "error",
+  category: "correctness",
+  description: "A wiring reference (@Phase.field or @component.publish.*) points at a phase or component that does not exist",
+  check(ctx: ComponentCheckContext): ComponentCheckDiagnostic[] {
+    const diagnostics: ComponentCheckDiagnostic[] = [];
+
+    for (const [name, { component, filePath }] of ctx.components) {
+      const phaseNames = topLevelPhaseNames(component);
+      const dependsOn = new Set(component.dependsOn ?? []);
+      const { steps } = walkComponent(component);
+
+      for (const { step, phaseName } of steps) {
+        for (const ref of collectWiringRefs(step)) {
+          if (ref.kind === "prior-step") {
+            if (phaseNames.has(ref.phaseName)) continue;
+            diagnostics.push({
+              checkId: "COMP002",
+              severity: "error",
+              component: name,
+              file: filePath,
+              message:
+                `Component "${name}": step "${step.kind}" (in phase "${phaseName}") references "@${ref.phaseName}.${ref.field}", ` +
+                `but no phase named "${ref.phaseName}" exists in this component's "deploy". Known phases: ` +
+                `${[...phaseNames].join(", ") || "(none)"}.`,
+            });
+            continue;
+          }
+
+          // ref.kind === "component-artifact"
+          const target = ctx.components.get(ref.componentName);
+          if (!target) {
+            diagnostics.push({
+              checkId: "COMP002",
+              severity: "error",
+              component: name,
+              file: filePath,
+              message:
+                `Component "${name}": step "${step.kind}" (in phase "${phaseName}") references ` +
+                `"@${ref.componentName}.publish.${ref.field}", but no component named "${ref.componentName}" was discovered.`,
+            });
+            continue;
+          }
+
+          if (!dependsOn.has(ref.componentName)) {
+            diagnostics.push({
+              checkId: "COMP002",
+              severity: "error",
+              component: name,
+              file: filePath,
+              message:
+                `Component "${name}": step "${step.kind}" (in phase "${phaseName}") references ` +
+                `"@${ref.componentName}.publish.${ref.field}", but "${ref.componentName}" is not listed in this ` +
+                `component's "dependsOn" — the graph only resolves an artifact reference for a declared dependency. ` +
+                `Add "${ref.componentName}" to dependsOn.`,
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/comp/comp003-mutating-no-rollback.ts

@@ -0,0 +1,115 @@
+/**
+ * COMP003: mutating-no-rollback
+ *
+ * Flags a mutating capability step whose family has no known native/starter
+ * rollback and no explicit opt-out — the "mutating capability with no
+ * rollback and no explicit opt-out reason" guardrail from epic #551 §7 and
+ * §"Failure modes".
+ *
+ * Each capability declares its rollback disposition via `rollbackPolicy`
+ * (../../../components/capability.ts): `"native"` (a paired `rollback`, e.g.
+ * `cfn-deploy`/`ecs-update-service`/`lambda-deploy`/`code-deploy`),
+ * `"none-by-design"` (nothing to compensate — the build/publish and wait/verify
+ * families, whose outputs are immutable/content-addressed or read-only), or
+ * `"needs-opt-out"` (a mutating verb with no native rollback and no safe undo,
+ * e.g. `s3-sync`/`run-migration`). This rule flags only `"needs-opt-out"` steps
+ * lacking an explicit opt-out. It reads the disposition from the project's
+ * capability registry (`ctx.rollbackPolicies`, built by `chant lint` from the
+ * active lexicons + core starter — the same seam COMP005 uses for
+ * `ctx.knownKinds`), never a hard-coded verb list, so the aws leaves'
+ * dispositions come from the aws lexicon that owns them.
+ *
+ * The opt-out: since the capability interface and schema are out of scope for
+ * this issue (`Step` already has `additionalProperties: true` — see
+ * component.schema.json), a component may attach a `noRollback: "<reason>"`
+ * string property directly on the step to declare the compensation gap is
+ * intentional and understood, or supply its own explicit compensation via a
+ * component-level `rollback` field (as the ALB/ECS pilot does with
+ * `rollback-previous`) or a sibling `rollback-previous`/`snapshot-before` step
+ * in the same phase.
+ *
+ * Triggers on: a bare `{ kind: "run-migration", ... }` step with no
+ * `noRollback` reason, no component-level `rollback`, and no sibling
+ * `rollback-previous`/`snapshot-before` step.
+ * OK: `{ kind: "run-migration", ..., noRollback: "forward-only migration, ..." }`,
+ * or a component `rollback` field, or a sibling compensation step.
+ */
+
+import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
+import { walkComponent } from "./support";
+
+/**
+ * A step is flagged only when its verb's rollback disposition is
+ * `"needs-opt-out"` — a mutating capability with no native rollback and no safe
+ * undo. That disposition is the capability's own declaration (`rollbackPolicy`,
+ * ../../../components/capability.ts), surfaced to this rule via
+ * `ctx.rollbackPolicies` (built from the project's registry by `chant lint`,
+ * exactly like `ctx.knownKinds` for COMP005). Verbs with a native rollback
+ * (`cfn-deploy`, …) or nothing to compensate (build/publish/wait) are
+ * `"native"`/`"none-by-design"` and never flagged. When no registry was
+ * resolved (a direct unit test), an unknown verb defaults to
+ * `"none-by-design"` — the rule stays silent rather than guessing.
+ */
+function policyFor(ctx: ComponentCheckContext, kind: string): string {
+  return ctx.rollbackPolicies?.get(kind) ?? "none-by-design";
+}
+
+/** A sibling step kind that itself is (or supplies) compensation — its presence in the same phase is treated as the component handling rollback explicitly, not silence. */
+const COMPENSATION_SIBLING_KINDS = new Set(["rollback-previous", "snapshot-before"]);
+
+export const comp003MutatingNoRollbackRule: ComponentCheck = {
+  id: "COMP003",
+  severity: "error",
+  category: "correctness",
+  description: "A mutating capability step has no known rollback and no explicit opt-out (noRollback reason, component rollback, or a compensation sibling step)",
+  check(ctx: ComponentCheckContext): ComponentCheckDiagnostic[] {
+    const diagnostics: ComponentCheckDiagnostic[] = [];
+
+    for (const [name, { component, filePath }] of ctx.components) {
+      const hasComponentRollback = Array.isArray(component.rollback) && component.rollback.length > 0;
+
+      // Walk every step (including inside nested fan-out phases and
+      // onFailure compensation phases — see support.ts's walkComponent) so a
+      // mutating step nested inside a fan-out unit (e.g. a Neo4j-style
+      // per-instance phase) is inspected the same as a top-level one.
+      const { steps } = walkComponent(component);
+
+      // Group steps by the exact Phase object they live under (identity, not
+      // name — two different nested phases can share a display name) so the
+      // "sibling in the same phase" compensation check only looks at true
+      // siblings, never steps from an unrelated phase of the same name.
+      const stepsByPhase = new Map<object, typeof steps>();
+      for (const walked of steps) {
+        const group = stepsByPhase.get(walked.phase) ?? [];
+        group.push(walked);
+        stepsByPhase.set(walked.phase, group);
+      }
+
+      for (const walked of steps) {
+        const { step, phaseName, phase } = walked;
+        if (policyFor(ctx, step.kind) !== "needs-opt-out") continue;
+
+        const noRollback = (step as { noRollback?: unknown }).noRollback;
+        const hasStepOptOut = typeof noRollback === "string" && noRollback.trim().length > 0;
+        if (hasStepOptOut || hasComponentRollback) continue;
+
+        const siblings = stepsByPhase.get(phase) ?? [];
+        const hasCompensationSibling = siblings.some((s) => COMPENSATION_SIBLING_KINDS.has(s.step.kind));
+        if (hasCompensationSibling) continue;
+
+        diagnostics.push({
+          checkId: "COMP003",
+          severity: "error",
+          component: name,
+          file: filePath,
+          message:
+            `Component "${name}": step "${step.kind}" (phase "${phaseName}") is a mutating capability with no ` +
+            `known native rollback and no explicit opt-out. Add a "noRollback: \\"<reason>\\"" property to the step, ` +
+            `a component-level "rollback" phase, or a sibling "rollback-previous"/"snapshot-before" step in the same phase.`,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};