@intentius/chant 0.124.13 → 0.124.15

package/dist/lint/rules/__fixtures__/comp/comp007/pass/search-service.component.js

@@ -0,0 +1,16 @@
+import { phase } from "../../../../../../components/component.js";
+/** COMP007 pass case: structurally distinct from orders-table.component.ts (service: build+publish+apply+verify vs. infra: apply+verify only) — no sprawl hint expected. */
+export const searchService = {
+    name: "search-service",
+    archetype: "service",
+    dependsOn: [],
+    build: { kind: "docker-build", context: ".", into: "archive" },
+    deploy: [
+        phase("Publish", [{ kind: "publish-image", from: "archive", to: "$env.registry" }]),
+        phase("Apply", [
+            { kind: "cfn-deploy", template: "archive:search.template.json", imageRef: "@Publish.digest" },
+            { kind: "ecs-update-service", cluster: "$env.cluster", service: "search" },
+        ]),
+        phase("Verify", [{ kind: "wait-steady-state", service: "search" }]),
+    ],
+};

package/dist/lint/rules/comp/comp001-publishes-never-applies.js

@@ -0,0 +1,69 @@
+/**
+ * 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 { collectWiringRefs, walkComponent } from "./support.js";
+const PUBLISH_KIND = /^(publish-image|publish-artifact|load-image-on-host)$/;
+export const comp001PublishesNeverAppliesRule = {
+    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) {
+        const diagnostics = [];
+        // 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();
+        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/dist/lint/rules/comp/comp002-dangling-wiring-ref.js

@@ -0,0 +1,84 @@
+/**
+ * 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 { collectWiringRefs, topLevelPhaseNames, walkComponent } from "./support.js";
+export const comp002DanglingWiringRefRule = {
+    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) {
+        const diagnostics = [];
+        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/dist/lint/rules/comp/comp003-mutating-no-rollback.js

@@ -0,0 +1,103 @@
+/**
+ * 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 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 { walkComponent } from "./support.js";
+/**
+ * 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, kind) {
+    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 = {
+    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) {
+        const diagnostics = [];
+        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();
+            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.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;
+    },
+};

package/dist/lint/rules/comp/comp004-gate-needs-durable-runtime.js

@@ -0,0 +1,70 @@
+/**
+ * COMP004: gate-needs-durable-runtime (the file is renamed in #2116; the
+ * behaviour changed in #2119)
+ *
+ * The file name and the exported symbol keep the old wording on purpose
+ * (#2195): the id is what an author writes in a `chant-disable` comment and
+ * what every import names, and churning both buys nothing. `description`
+ * below is the accurate sentence, and it is what the docs page uses as its
+ * heading — since #2119 the rule has nothing to do with which runtime hosts
+ * the run.
+ *
+ * Flags a `gate` step anywhere in a component's composition — the point where
+ * a run stops and waits for a person. Since #2119 that is not a refusal: the
+ * driver decides the gate against the gate ledger (`../../../op/gate.ts`), and
+ * one nobody has approved ends the run pending `chant approve <component>
+ * <gate>`, to be re-decided next run.
+ *
+ * The rule survives the change because what it flags survives it. The
+ * component contract has no per-component runtime field (the runtime is chosen
+ * per *run*, via `chant run --on`, intentionally not part of the declaration),
+ * so lint cannot tell from the declaration alone that a `gate` is deliberate;
+ * every one is a standing "this component stops for a human" fact worth
+ * surfacing, not a mistake to silently allow. Acknowledge it explicitly with a
+ * **file-level**
+ * disable directive once the human wait is genuinely intended (see
+ * lint-rules/disable-directives.mdx) — a COMP* diagnostic carries no real
+ * line/column (it is reported for the whole component; see
+ * ../../component-checks.ts), so only the file-level `chant-disable` form is
+ * honored for these rules — `-line`/`-next-line` do not suppress a COMP*
+ * diagnostic (see ../../../cli/commands/lint.ts's
+ * `runComponentCheckDiagnostics`):
+ *
+ * ```ts
+ * // chant-disable COMP004 -- the rollout waits on a release manager's approval
+ * ```
+ *
+ * Triggers on: any `gate` step in `deploy`/`rollback` with no matching
+ * file-level disable directive.
+ * OK: a component with no `gate` steps at all, or a `gate` whose file-level
+ * disable directive says who is expected to approve it and why.
+ */
+import { gateName } from "../../../op/gate-name.js";
+import { walkComponent } from "./support.js";
+export const comp004GateNeedsDurableRuntimeRule = {
+    id: "COMP004",
+    severity: "error",
+    category: "correctness",
+    description: "A gate step ends the run pending approval — acknowledge the human wait explicitly",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [name, { component, filePath }] of ctx.components) {
+            const { gates } = walkComponent(component);
+            for (const { gate, phaseName } of gates) {
+                const label = gateName(gate);
+                diagnostics.push({
+                    checkId: "COMP004",
+                    severity: "error",
+                    component: name,
+                    file: filePath,
+                    message: `Component "${name}": gate "${label}" (phase "${phaseName}") ends the run pending approval — ` +
+                        `a run that reaches it records the gate as a fact and stops there until someone runs ` +
+                        `"chant approve ${name} ${label}", and no later phase runs. If that wait is intended, ` +
+                        `suppress with a file-level "// chant-disable COMP004 -- <reason>" comment anywhere in this file to ` +
+                        `document who approves it and why.`,
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/comp/comp005-capability-kind-is-noun.js

@@ -0,0 +1,109 @@
+/**
+ * COMP005: capability-kind-is-noun
+ *
+ * Flags a step `kind` that names a component rather than an operation — the
+ * "capability-per-component (renamed sprawl)" failure mode from epic #551
+ * §"Failure modes ... + guardrails": "Tell: capabilities named after nouns."
+ * Every starter-set verb is a verb-phrase describing an operation
+ * (`cfn-deploy`, `publish-image`, `wait-steady-state`, ...); a capability
+ * named after *this* component (or any other discovered component) is
+ * exactly the sprawl the capability model exists to remove — see
+ * docs/components/capabilities.mdx#the-discipline ("A capability describes
+ * an operation, never a component").
+ *
+ * Detection is structural, not NLP: a step `kind` is flagged when it equals,
+ * or is built from, a discovered component's own kebab-case `name` (e.g. a
+ * `search-service` component composing a `{ kind: "deploy-search-service" }`
+ * or `{ kind: "search-service" }` step) — the concrete, checkable form of
+ * "named after a component" the issue asks for, mirroring how
+ * ../../../components/capability.ts's own docstring defines the discipline
+ * ("never named after the component that happens to use it").
+ *
+ * Every registered `kind` is excluded from this check unconditionally,
+ * regardless of whether its dash-separated segments happen to overlap a
+ * component's name. The allowlist comes from `ctx.knownKinds` — the kinds the
+ * project's capability registry actually resolves, which `chant lint` builds
+ * from the project's config (core's starter set plus the active lexicons'
+ * leaves, e.g. `cfn-deploy`/`wait-for-stack` when `lexicons: ["aws"]`). Without
+ * this exclusion, a component literally named "stack", "job", "image", or
+ * "host" would falsely flag `wait-for-stack`/`emr-start-job-run`/`publish-image`/
+ * `load-image-on-host` — a real capability's verb-ness is an established fact of
+ * the registry, not something to re-adjudicate by substring match. When no
+ * registry was resolved (a direct unit test), it falls back to core's starter
+ * set (`CORE_STARTER_KINDS`).
+ *
+ * Triggers on: `{ kind: "search-service" }` or `{ kind: "deploy-search-service" }`
+ * in any component, when "search-service" is a discovered component's name and
+ * neither form is a registered verb.
+ * OK: `{ kind: "cfn-deploy" }`, `{ kind: "ecs-update-service" }`,
+ * `{ kind: "wait-for-stack" }` — verb-named, and/or a registered verb.
+ */
+import { STARTER_VERB_FAMILIES } from "../../../components/starter-plugin.js";
+import { walkComponent } from "./support.js";
+/**
+ * Fallback allowlist when the check runs without a resolved registry (e.g. a
+ * direct unit test): core's own starter verbs. The real `chant lint` run passes
+ * `ctx.knownKinds` — every kind the project's registry actually resolves,
+ * including the active lexicons' leaves (`cfn-deploy`, `wait-for-stack`, …) —
+ * so a real project never depends on this fallback for its cloud verbs.
+ */
+const CORE_STARTER_KINDS = new Set(Object.values(STARTER_VERB_FAMILIES).flat());
+/** True if `kind` is exactly a component name, or that name embedded with `-`-joined affixes (e.g. "deploy-search-service", "search-service-apply"). */
+function kindNamesComponent(kind, componentName) {
+    if (kind === componentName)
+        return true;
+    const parts = kind.split("-");
+    const nameParts = componentName.split("-");
+    if (nameParts.length === 0)
+        return false;
+    for (let i = 0; i + nameParts.length <= parts.length; i++) {
+        if (nameParts.every((p, j) => parts[i + j] === p))
+            return true;
+    }
+    return false;
+}
+export const comp005CapabilityKindIsNounRule = {
+    id: "COMP005",
+    severity: "error",
+    category: "style",
+    description: "A capability kind is named after a component (a noun) rather than an operation (a verb)",
+    check(ctx) {
+        const diagnostics = [];
+        const componentNames = [...ctx.components.keys()];
+        if (componentNames.length === 0)
+            return diagnostics;
+        // Every known verb — the project's registered kinds when `chant lint`
+        // resolved a registry (includes active lexicons' leaves), else core's
+        // starter set. A known verb is never a "noun named after the component",
+        // regardless of any substring overlap with a component's name.
+        const knownKinds = ctx.knownKinds ?? CORE_STARTER_KINDS;
+        for (const [name, { component, filePath }] of ctx.components) {
+            const { steps } = walkComponent(component);
+            const reported = new Set();
+            for (const { step, phaseName } of steps) {
+                if (step.kind === "gate")
+                    continue;
+                if (knownKinds.has(step.kind))
+                    continue;
+                const matchedComponent = componentNames.find((cn) => kindNamesComponent(step.kind, cn));
+                if (!matchedComponent)
+                    continue;
+                const dedupeKey = `${step.kind}:${phaseName}`;
+                if (reported.has(dedupeKey))
+                    continue;
+                reported.add(dedupeKey);
+                diagnostics.push({
+                    checkId: "COMP005",
+                    severity: "error",
+                    component: name,
+                    file: filePath,
+                    message: `Component "${name}": step kind "${step.kind}" (phase "${phaseName}") is named after component ` +
+                        `"${matchedComponent}" rather than an operation. A capability kind must be a verb ("cfn-deploy", ` +
+                        `"publish-image", "wait-steady-state", ...), never a noun naming the component that uses it — see ` +
+                        `docs/components/capabilities.mdx#the-discipline.`,
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/comp/comp006-shell-needs-reason.js

@@ -0,0 +1,49 @@
+/**
+ * COMP006: shell-needs-reason
+ *
+ * Flags a `shell` step with no (or empty/blank) `reason` — the escape-hatch
+ * discipline from epic #551 §7 and §"What chant adds": "raw `shell` without a
+ * declared reason" gets flagged. `shell` is the deliberate escape hatch
+ * (../../../components/verbs/shell.ts) for reaching past the capability set;
+ * `ShellInput.reason` is already a required field on the typed
+ * `createShellCapability` input, but a hand-authored/JSON-only component (the
+ * contract's whole point — see component-contract.mdx's "portable, not
+ * chant-only" framing) is not type-checked against that interface, so the raw
+ * JSON contract's `Step` (open `additionalProperties`) does not itself
+ * enforce it. This rule enforces the same discipline at the composition
+ * level, for every authoring form.
+ *
+ * Triggers on: `{ kind: "shell", cmd: "..." }` with no `reason`, or
+ * `reason: ""` / `reason: "   "`.
+ * OK: `{ kind: "shell", cmd: "...", reason: "no capability covers <x> yet" }`.
+ */
+import { walkComponent } from "./support.js";
+export const comp006ShellNeedsReasonRule = {
+    id: "COMP006",
+    severity: "error",
+    category: "correctness",
+    description: 'A raw "shell" escape-hatch step has no declared reason',
+    check(ctx) {
+        const diagnostics = [];
+        for (const [name, { component, filePath }] of ctx.components) {
+            const { steps } = walkComponent(component);
+            for (const { step, phaseName } of steps) {
+                if (step.kind !== "shell")
+                    continue;
+                const reason = step.reason;
+                const hasReason = typeof reason === "string" && reason.trim().length > 0;
+                if (hasReason)
+                    continue;
+                diagnostics.push({
+                    checkId: "COMP006",
+                    severity: "error",
+                    component: name,
+                    file: filePath,
+                    message: `Component "${name}": "shell" step (phase "${phaseName}") is the escape hatch and must declare why no ` +
+                        `capability covers this case — add a non-empty "reason" property (e.g. "reason: \\"no capability for X yet\\"").`,
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/comp/comp007-composition-sprawl.js

@@ -0,0 +1,64 @@
+/**
+ * COMP007: composition-sprawl
+ *
+ * Flags two or more components whose `deploy` composition is structurally
+ * identical (same phases, same `parallel`/nesting shape, same step kinds in
+ * the same order) — the "composition copy-paste (declaration sprawl)"
+ * failure mode from epic #551 §"Failure modes ... + guardrails": "Guard:
+ * presets (Level 2) + a lint hint when an identical composition repeats
+ * across components." This is a *hint*, not a hard error (severity:
+ * "warning") — the epic frames it as "reach for a preset"
+ * (docs/components/capabilities.mdx#presets--reuse-without-a-closed-set),
+ * not a correctness defect.
+ *
+ * The fingerprint (../comp/support.ts's `compositionFingerprint`) compares
+ * phase names, `parallel` flags, nesting, and step *kinds* only — never
+ * `name`/`dependsOn`/literal wiring values/params, so two components that
+ * both do "build -> publish -> apply -> verify" with the same capability
+ * kinds but different templates/clusters/images still match (that is exactly
+ * the "own destiny is in the params, not the shape" case a preset should
+ * absorb).
+ *
+ * Triggers on: three components (arbitrary example) that all compose
+ * `docker-build` -> `publish-image` -> `cfn-deploy` + `ecs-update-service` ->
+ * `wait-steady-state` + `health-gate` with no meaningful structural
+ * difference.
+ * OK: components whose phase/step-kind shape differs (a different archetype,
+ * a different apply family, fan-out vs. no fan-out, etc.) — like the four
+ * real pilots, which were deliberately chosen to be structurally distinct
+ * (see ../../../components/SPRAWL-VALIDATION.md).
+ */
+import { compositionFingerprint } from "./support.js";
+export const comp007CompositionSprawlRule = {
+    id: "COMP007",
+    severity: "warning",
+    category: "style",
+    description: "An identical composition shape is repeated across components — a declaration-sprawl hint to reach for a preset",
+    check(ctx) {
+        const diagnostics = [];
+        const byFingerprint = new Map();
+        for (const [name, { component }] of ctx.components) {
+            const fp = compositionFingerprint(component);
+            byFingerprint.set(fp, [...(byFingerprint.get(fp) ?? []), name]);
+        }
+        for (const names of byFingerprint.values()) {
+            if (names.length < 2)
+                continue;
+            const sorted = [...names].sort();
+            for (const name of sorted) {
+                const others = sorted.filter((n) => n !== name);
+                const { filePath } = ctx.components.get(name);
+                diagnostics.push({
+                    checkId: "COMP007",
+                    severity: "warning",
+                    component: name,
+                    file: filePath,
+                    message: `Component "${name}" composes an identical phase/step shape to ${others.map((n) => `"${n}"`).join(", ")} ` +
+                        `— consider extracting a shared preset (docs/components/capabilities.mdx#presets) instead of repeating ` +
+                        `the composition per component.`,
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/comp/index.js

@@ -0,0 +1,33 @@
+/**
+ * COMP* composition lint rules (#562, epic #551) — the long-term entropy
+ * guards over the discovered `Component` graph. See ../../component-checks.ts
+ * for why these are `ComponentCheck`s (whole-project, post-discovery) rather
+ * than `LintRule`s (single-file AST), and docs/lint-rules/composition.mdx for
+ * the user-facing reference.
+ */
+import { comp001PublishesNeverAppliesRule } from "./comp001-publishes-never-applies.js";
+import { comp002DanglingWiringRefRule } from "./comp002-dangling-wiring-ref.js";
+import { comp003MutatingNoRollbackRule } from "./comp003-mutating-no-rollback.js";
+import { comp004GateNeedsDurableRuntimeRule } from "./comp004-gate-needs-durable-runtime.js";
+import { comp005CapabilityKindIsNounRule } from "./comp005-capability-kind-is-noun.js";
+import { comp006ShellNeedsReasonRule } from "./comp006-shell-needs-reason.js";
+import { comp007CompositionSprawlRule } from "./comp007-composition-sprawl.js";
+export { comp001PublishesNeverAppliesRule } from "./comp001-publishes-never-applies.js";
+export { comp002DanglingWiringRefRule } from "./comp002-dangling-wiring-ref.js";
+export { comp003MutatingNoRollbackRule } from "./comp003-mutating-no-rollback.js";
+export { comp004GateNeedsDurableRuntimeRule } from "./comp004-gate-needs-durable-runtime.js";
+export { comp005CapabilityKindIsNounRule } from "./comp005-capability-kind-is-noun.js";
+export { comp006ShellNeedsReasonRule } from "./comp006-shell-needs-reason.js";
+export { comp007CompositionSprawlRule } from "./comp007-composition-sprawl.js";
+/** All seven COMP* checks, sorted by id. */
+export function loadComponentChecks() {
+    return [
+        comp001PublishesNeverAppliesRule,
+        comp002DanglingWiringRefRule,
+        comp003MutatingNoRollbackRule,
+        comp004GateNeedsDurableRuntimeRule,
+        comp005CapabilityKindIsNounRule,
+        comp006ShellNeedsReasonRule,
+        comp007CompositionSprawlRule,
+    ];
+}