@composurecdk/eslint-plugin 0.10.0

package/dist/esm/rules/no-typescript-private-modifier.js

@@ -0,0 +1,88 @@
+/**
+ * The member's own name, for the message. A computed key has no name to give —
+ * `#[expr]` is not a thing — so the message falls back to a placeholder rather
+ * than naming whatever expression produced the key.
+ */
+function memberName(key, computed) {
+    if (computed)
+        return "field";
+    if (key.type === "Identifier")
+        return key.name;
+    if (key.type === "Literal" && typeof key.value === "string")
+        return key.value;
+    return "field";
+}
+/** The bound name of a parameter, seeing through a default value. */
+function parameterName(parameter) {
+    const bound = parameter.type === "AssignmentPattern" ? parameter.left : parameter;
+    return bound.type === "Identifier" ? bound.name : "field";
+}
+/**
+ * Bans the TypeScript `private` modifier in favour of ECMAScript private fields.
+ *
+ * The two are not interchangeable once a class is generic over its own members.
+ * A TypeScript `private` member is still part of the type, so it appears in
+ * `keyof T`, survives into a mapped type, and reaches the emitted `.d.ts` — where
+ * a consumer's compiler cannot name it and reports TS4094. A `#field` is not
+ * part of the type at all, so it never gets that far.
+ *
+ * A private constructor stays allowed: `#constructor` is not valid syntax, so
+ * there is nothing to prefer over it.
+ *
+ * See {@link https://github.com/laazyj/composureCDK/blob/main/packages/eslint-plugin/docs/rules/no-typescript-private-modifier.md | the rule documentation}.
+ */
+export const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Ban the TypeScript `private` modifier in favour of ECMAScript `#` fields",
+        },
+        schema: [],
+        messages: {
+            property: "Use an ECMAScript private field (`#{{name}}`) instead of the TypeScript `private` " +
+                "modifier. A `private` member still appears in `keyof T` and is carried through mapped " +
+                "types into the emitted .d.ts, where it produces TS4094 for consumers.",
+            method: "Use an ECMAScript private method (`#{{name}}()`) instead of the TypeScript `private` " +
+                "modifier. A private constructor is the only permitted use, since `#constructor` is not " +
+                "valid syntax.",
+            parameterProperty: "A parameter property cannot be ECMAScript private. Declare the field as " +
+                "`readonly #{{name}}` and assign it in the constructor body.",
+        },
+    },
+    create(ctx) {
+        // Each handler reports on the member's own name rather than the whole
+        // declaration: the fix replaces the modifier and renames the key, so a
+        // narrow squiggle points at both.
+        return {
+            "PropertyDefinition[accessibility='private']"(node) {
+                ctx.report({
+                    node: node.key,
+                    messageId: "property",
+                    data: { name: memberName(node.key, node.computed) },
+                });
+            },
+            "MethodDefinition[accessibility='private'][kind!='constructor']"(node) {
+                ctx.report({
+                    node: node.key,
+                    messageId: "method",
+                    data: { name: memberName(node.key, node.computed) },
+                });
+            },
+            // `accessor x` is a distinct node from a plain field, and its `private`
+            // reaches `keyof T` the same way.
+            "AccessorProperty[accessibility='private']"(node) {
+                const { key, computed } = node;
+                ctx.report({ node: key, messageId: "property", data: { name: memberName(key, computed) } });
+            },
+            "TSParameterProperty[accessibility='private']"(node) {
+                const { parameter } = node;
+                ctx.report({
+                    node: parameter,
+                    messageId: "parameterProperty",
+                    data: { name: parameterName(parameter) },
+                });
+            },
+        };
+    },
+};
+//# sourceMappingURL=no-typescript-private-modifier.js.map

package/dist/esm/rules/no-typescript-private-modifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-typescript-private-modifier.js","sourceRoot":"","sources":["../../../src/rules/no-typescript-private-modifier.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAS,EAAE,QAAiB;IAC9C,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAC/C,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC;IAC9E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qEAAqE;AACrE,SAAS,aAAa,CAAC,SAAe;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,KAAK,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,IAAI,GAAoB;IACnC,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS;QACf,IAAI,EAAE;YACJ,WAAW,EAAE,0EAA0E;SACxF;QACD,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE;YACR,QAAQ,EACN,oFAAoF;gBACpF,wFAAwF;gBACxF,uEAAuE;YACzE,MAAM,EACJ,uFAAuF;gBACvF,yFAAyF;gBACzF,eAAe;YACjB,iBAAiB,EACf,0EAA0E;gBAC1E,6DAA6D;SAChE;KACF;IACD,MAAM,CAAC,GAAG;QACR,sEAAsE;QACtE,uEAAuE;QACvE,kCAAkC;QAClC,OAAO;YACL,6CAA6C,CAAC,IAAwB;gBACpE,GAAG,CAAC,MAAM,CAAC;oBACT,IAAI,EAAE,IAAI,CAAC,GAAG;oBACd,SAAS,EAAE,UAAU;oBACrB,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;iBACpD,CAAC,CAAC;YACL,CAAC;YACD,gEAAgE,CAAC,IAAsB;gBACrF,GAAG,CAAC,MAAM,CAAC;oBACT,IAAI,EAAE,IAAI,CAAC,GAAG;oBACd,SAAS,EAAE,QAAQ;oBACnB,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;iBACpD,CAAC,CAAC;YACL,CAAC;YACD,wEAAwE;YACxE,kCAAkC;YAClC,2CAA2C,CAAC,IAAU;gBACpD,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAuC,CAAC;gBAClE,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9F,CAAC;YACD,8CAA8C,CAAC,IAAU;gBACvD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAwC,CAAC;gBAC/D,GAAG,CAAC,MAAM,CAAC;oBACT,IAAI,EAAE,SAAS;oBACf,SAAS,EAAE,mBAAmB;oBAC9B,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE;iBACzC,CAAC,CAAC;YACL,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/esm/rules/redeclared-prop-must-track-cdk-type.d.ts

@@ -0,0 +1,17 @@
+import type { Rule } from "eslint";
+/**
+ * Flags a re-declared CDK prop that pins a named CDK interface inside
+ * `Resolvable<…>` rather than reading the type from CDK's own prop.
+ *
+ * A builder's props type is CDK's props type with a few keys lifted out and
+ * re-declared. Everything left inside the `Omit` keeps tracking whichever
+ * `aws-cdk-lib` the consumer installed; a key re-spelled with a named interface
+ * stops tracking it, freezing at whatever that interface meant when it was
+ * written. When CDK later widens that prop, the builder goes on rejecting values
+ * the construct it wraps now accepts — and it surfaces in the consumer's own
+ * compile, not in this package's.
+ *
+ * See {@link https://github.com/laazyj/composureCDK/blob/main/packages/eslint-plugin/docs/rules/redeclared-prop-must-track-cdk-type.md | the rule documentation}.
+ */
+export declare const rule: Rule.RuleModule;
+//# sourceMappingURL=redeclared-prop-must-track-cdk-type.d.ts.map

package/dist/esm/rules/redeclared-prop-must-track-cdk-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redeclared-prop-must-track-cdk-type.d.ts","sourceRoot":"","sources":["../../../src/rules/redeclared-prop-must-track-cdk-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAqFnC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,UAiEvB,CAAC"}

package/dist/esm/rules/redeclared-prop-must-track-cdk-type.js

@@ -0,0 +1,149 @@
+import { isCdkSource } from "./lib/imports.js";
+/** True for `@aws-cdk/aws-*-alpha` and friends, alongside `aws-cdk-lib`. */
+function isCdkModule(source) {
+    return isCdkSource(source) || source.startsWith("@aws-cdk/");
+}
+/** The first type argument of a type reference or interface heritage, either spelling. */
+function typeArgAt(node, index) {
+    const args = (node.typeArguments ?? node.typeParameters);
+    const params = args?.params ?? [];
+    return params.at(index);
+}
+/** The leftmost identifier of `Foo` or `ns.Foo`, or `undefined` for anything else. */
+function rootName(typeName) {
+    let current = typeName;
+    while (current.type === "TSQualifiedName")
+        current = current.left;
+    return current.type === "Identifier" ? current.name : undefined;
+}
+/** The string keys named by `Omit`'s second argument, ignoring non-literal ones. */
+function literalKeys(node) {
+    if (node === undefined)
+        return [];
+    if (node.type === "TSUnionType") {
+        return node.types.flatMap((t) => literalKeys(t));
+    }
+    if (node.type !== "TSLiteralType")
+        return [];
+    const literal = node.literal;
+    return typeof literal.value === "string" ? [literal.value] : [];
+}
+/** The keys an interface's `extends` clause omits from a base CDK props type. */
+function omittedKeys(heritage) {
+    const keys = new Set();
+    for (const entry of heritage) {
+        const expression = entry.expression;
+        if (expression?.type !== "Identifier" || expression.name !== "Omit")
+            continue;
+        for (const key of literalKeys(typeArgAt(entry, 1)))
+            keys.add(key);
+    }
+    return keys;
+}
+/** Every `Resolvable<…>` reference nested anywhere inside a type annotation. */
+function resolvableRefs(node, found = []) {
+    if (node === null || typeof node !== "object" || !("type" in node))
+        return found;
+    const typed = node;
+    if (typed.type === "TSTypeReference" && rootName(typed.typeName) === "Resolvable") {
+        found.push(typed);
+    }
+    for (const [key, value] of Object.entries(typed)) {
+        // `parent` points back up the tree — following it never terminates.
+        if (key === "parent")
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                resolvableRefs(item, found);
+        else
+            resolvableRefs(value, found);
+    }
+    return found;
+}
+/** The property name of a `key: T` signature, or `undefined` for a computed one. */
+function propertyName(member) {
+    if (member.type !== "TSPropertySignature" || member.computed === true)
+        return undefined;
+    const key = member.key;
+    if (key.type === "Identifier")
+        return key.name;
+    if (key.type === "Literal" && typeof key.value === "string")
+        return key.value;
+    return undefined;
+}
+/**
+ * Flags a re-declared CDK prop that pins a named CDK interface inside
+ * `Resolvable<…>` rather than reading the type from CDK's own prop.
+ *
+ * A builder's props type is CDK's props type with a few keys lifted out and
+ * re-declared. Everything left inside the `Omit` keeps tracking whichever
+ * `aws-cdk-lib` the consumer installed; a key re-spelled with a named interface
+ * stops tracking it, freezing at whatever that interface meant when it was
+ * written. When CDK later widens that prop, the builder goes on rejecting values
+ * the construct it wraps now accepts — and it surfaces in the consumer's own
+ * compile, not in this package's.
+ *
+ * See {@link https://github.com/laazyj/composureCDK/blob/main/packages/eslint-plugin/docs/rules/redeclared-prop-must-track-cdk-type.md | the rule documentation}.
+ */
+export const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "A re-declared CDK prop must read its type from CDK's own prop, not pin an interface",
+        },
+        schema: [],
+        messages: {
+            pinnedType: "`{{prop}}` re-declares a prop omitted from `{{base}}`, but pins `{{pinned}}` — the " +
+                "builder stops accepting what CDK accepts as soon as CDK widens the prop. Read the type " +
+                'from CDK\'s own prop instead: `Resolvable<NonNullable<{{base}}["{{prop}}"]>>`. ' +
+                "Keep the indexed access inline — extracting it to a named alias puts an unnameable " +
+                "type into the emitted declaration.",
+        },
+    },
+    create(ctx) {
+        const cdkTypeNames = new Set();
+        const listener = {
+            ImportDeclaration(node) {
+                if (typeof node.source.value !== "string" || !isCdkModule(node.source.value))
+                    return;
+                for (const spec of node.specifiers) {
+                    cdkTypeNames.add(spec.local.name);
+                }
+            },
+        };
+        listener.TSInterfaceDeclaration = (node) => {
+            const decl = node;
+            const heritage = decl.extends ?? [];
+            const omitted = omittedKeys(heritage);
+            if (omitted.size === 0)
+                return;
+            // Name the base the indexed access should read from — the first `Omit`'s
+            // own base, which is the CDK props type in every builder that has one.
+            const omit = heritage.find((entry) => entry.expression?.name === "Omit");
+            const omitBase = omit === undefined ? undefined : typeArgAt(omit, 0);
+            const base = (omitBase === undefined ? undefined : rootName(omitBase.typeName)) ??
+                "CdkProps";
+            const body = decl.body?.body ?? [];
+            for (const member of body) {
+                const prop = propertyName(member);
+                if (prop === undefined || !omitted.has(prop))
+                    continue;
+                for (const resolvable of resolvableRefs(member.typeAnnotation)) {
+                    const inner = typeArgAt(resolvable, 0);
+                    if (inner?.type !== "TSTypeReference")
+                        continue;
+                    const pinned = rootName(inner.typeName);
+                    if (pinned === undefined || !cdkTypeNames.has(pinned))
+                        continue;
+                    ctx.report({
+                        node: inner,
+                        messageId: "pinnedType",
+                        data: { prop, base, pinned },
+                    });
+                }
+            }
+        };
+        return listener;
+    },
+};
+//# sourceMappingURL=redeclared-prop-must-track-cdk-type.js.map

package/dist/esm/rules/redeclared-prop-must-track-cdk-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redeclared-prop-must-track-cdk-type.js","sourceRoot":"","sources":["../../../src/rules/redeclared-prop-must-track-cdk-type.ts"],"names":[],"mappings":"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"}

package/docs/rules/builder-must-be-tagged.md

@@ -0,0 +1,46 @@
+# composurecdk/builder-must-be-tagged
+
+Flags `Builder()` or `IBuilder<…>` imported from `@composurecdk/core` in a library builder, where the tagged equivalents belong.
+
+- **Preset:** `internal` (`error`)
+
+## Why
+
+Tagging is a cross-cutting concern every deployable resource needs, and it is not something each builder should re-invent. `taggedBuilder` / `ITaggedBuilder` from `@composurecdk/cloudformation` wrap the core builder with the shared tagging surface, so a consumer gets the same `.tags(…)` API on every builder in the library rather than on whichever ones remembered.
+
+`@composurecdk/core` stays CDK-agnostic and cannot provide this itself — tagging is a CloudFormation concern, so the tagged wrapper lives one layer up.
+
+## ❌ Incorrect
+
+```ts
+import { Builder, type IBuilder } from "@composurecdk/core";
+
+export function createBucketBuilder(): IBuilder<BucketBuilderProps, Bucket> {
+  return Builder(BucketBuilderImpl);
+}
+```
+
+## ✅ Correct
+
+```ts
+import { taggedBuilder, type ITaggedBuilder } from "@composurecdk/cloudformation";
+
+export function createBucketBuilder(): ITaggedBuilder<BucketBuilderProps, Bucket> {
+  return taggedBuilder(BucketBuilderImpl);
+}
+```
+
+## Escape hatch
+
+Some CloudFormation resources have no `Tags` property at all — Route53 records, IAM `ManagedPolicy`, SNS `Subscription`, AWS Budgets. A builder wrapping one of those cannot be tagged, so disable the rule on the line and name the resource, keeping the exception visible in review:
+
+```ts
+// eslint-disable-next-line composurecdk/builder-must-be-tagged -- AWS::Route53::RecordSet has no Tags property
+return Builder(RecordSetBuilderImpl);
+```
+
+The implementation of the tagged wrapper itself is exempt in this repo's root config — `packages/cloudformation/src/tagged-builder.ts` _is_ the tagged surface, so by definition it reaches for the core builder.
+
+## How it works
+
+Syntactic. The rule looks for `Builder` / `IBuilder` bindings imported from `@composurecdk/core` and reports their use.

package/docs/rules/builder-must-implement-copy-state.md

@@ -0,0 +1,50 @@
+# composurecdk/builder-must-implement-copy-state
+
+Flags a builder class holding private state with no `[COPY_STATE]` hook.
+
+- **Preset:** `recommended` (`error`)
+- **Decision:** [ADR-0005](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0005-builder-copy.md)
+
+## Why
+
+`.copy()` shallow-clones `props`. Anything a builder keeps _outside_ `props` — private fields — is not carried across unless `[COPY_STATE]` says so. Without the hook, `.copy()` silently drops that state, breaking both variant authoring and strategy hand-off, and it fails quietly: the copy looks fine and behaves differently.
+
+[ADR-0005](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0005-builder-copy.md) has the design.
+
+## ❌ Incorrect
+
+```ts
+class BucketBuilderImpl {
+  #alarms: AlarmDefinition[] = [];
+  // no [COPY_STATE] — `.copy()` returns a builder with no alarms
+}
+```
+
+## ✅ Correct
+
+```ts
+class BucketBuilderImpl {
+  #alarms: AlarmDefinition[] = [];
+
+  [COPY_STATE](target: this): void {
+    target.#alarms = [...this.#alarms];
+  }
+}
+```
+
+## Existence, not correctness
+
+The rule checks only that the hook is **present**. A hook copying three of five fields passes. The companion test helper `assertCopyPreservesState` from `@composurecdk/core/testing` closes that gap on the test side — the two are meant to be used together.
+
+## Per-field opt-out
+
+Annotate a field to exempt it, e.g. for cache-shaped state regenerated on each build. The justification after `--` is required:
+
+```ts
+// @copy-state: ignore -- memoised per build, regenerated on the clone
+#resolvedArn?: string;
+```
+
+## How it works
+
+Syntactic. The rule identifies builder classes as those passed as the first argument to `Builder()` or `taggedBuilder()`, then checks for private fields against the presence of a `[COPY_STATE]` member.

package/docs/rules/constraint-metadata-required.md

@@ -0,0 +1,44 @@
+# composurecdk/constraint-metadata-required
+
+Requires every `stringConstraint({ … })` call to set a non-empty `name`, `allowed`, and `source`.
+
+- **Preset:** `internal` (`error`)
+- **Decision:** [ADR-0010](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0010-aws-property-constraints.md)
+
+## Why
+
+Those three fields are the whole value of a synth-time validation error. They name the property, list the allowed character set, and link the AWS documentation — turning "deployment failed" into something the author can act on at the call site.
+
+The factory's type already makes the keys required, so the rule's real job is what the type checker cannot see: a present-but-empty literal such as `allowed: ""` compiles fine while silently degrading every message the constraint produces.
+
+## ❌ Incorrect
+
+```ts
+const GROUP_DESCRIPTION = stringConstraint({
+  name: "EC2 SecurityGroup GroupDescription",
+  charClass: "a-zA-Z0-9 ._\\-:/()#,@\\[\\]+=&;{}!$*",
+  allowed: "",
+  source: "",
+});
+```
+
+## ✅ Correct
+
+```ts
+const GROUP_DESCRIPTION = stringConstraint({
+  name: "EC2 SecurityGroup GroupDescription",
+  charClass: "a-zA-Z0-9 ._\\-:/()#,@\\[\\]+=&;{}!$*",
+  allowed: "letters, digits, spaces and ._-:/()#,@[]+=&;{}!$*",
+  source:
+    "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-security-group.html",
+});
+```
+
+## Not flagged
+
+- **Non-literal values** — `allowed: SG_ALLOWED`. The contents are not statically knowable, so the rule leaves them alone.
+- **Calls that spread another object** — skipped, to avoid false positives where the required field arrives via the spread.
+
+## How it works
+
+Syntactic. The rule keys on the `stringConstraint` callee name, which is unique to the constraint-catalogue mechanism.

package/docs/rules/lifecycle-build-context-required.md

@@ -0,0 +1,39 @@
+# composurecdk/lifecycle-build-context-required
+
+Flags a `Lifecycle` class that uses `Resolvable<…>` but whose `build` method takes no `context` parameter.
+
+- **Preset:** `recommended` (`error`)
+
+## Why
+
+A builder holding a `Resolvable<…>` accepts refs at configuration time. Resolving one at build time needs the context — `resolve(value, context)`. With no `context` parameter the call receives `undefined`, and the ref throws "cannot be resolved" at synth.
+
+This rule checks the **declaration**. Its call-site counterpart, [`lifecycle-build-must-forward-context`](lifecycle-build-must-forward-context.md), checks that a builder which delegates actually passes its context on — having the parameter is not enough.
+
+## ❌ Incorrect
+
+```ts
+class TopicBuilderImpl implements Lifecycle<Topic> {
+  #props: { masterKey?: Resolvable<IKey> } = {};
+
+  build(scope: IConstruct, id: string): Topic {
+    // no `context` — resolving `masterKey` here cannot work
+  }
+}
+```
+
+## ✅ Correct
+
+```ts
+class TopicBuilderImpl implements Lifecycle<Topic> {
+  #props: { masterKey?: Resolvable<IKey> } = {};
+
+  build(scope: IConstruct, id: string, context?: BuildContext): Topic {
+    const masterKey = resolve(this.#props.masterKey, context);
+  }
+}
+```
+
+## How it works
+
+Syntactic. The rule keys on the identifier `Resolvable` appearing in the class body — a name unique to this codebase. Keying on `resolve(` instead would produce false positives on `Promise.resolve` and friends.

package/docs/rules/lifecycle-build-must-forward-context.md

@@ -0,0 +1,50 @@
+# composurecdk/lifecycle-build-must-forward-context
+
+Flags a two-argument `builder.build(scope, id)` call in library source, which gives the sub-builder no context to resolve refs against.
+
+- **Preset:** `libraryAuthor` (`error`)
+
+## Why
+
+This is the call-site counterpart to [`lifecycle-build-context-required`](lifecycle-build-context-required.md), which checks the declaration. Accepting a `context` parameter is not enough: a builder that delegates to a sub-builder must pass its context on. When it does not, the sub-builder resolves refs against `{}`, and any `ref()` the caller supplied through a `configure` callback dies with "component not found in context".
+
+The declaration rule cannot see this. It keys on `Resolvable<` in the builder's own class body, but in every real occurrence the resolvable lived one delegation away — in the _sub-builder's_ props — while the offending call sat in a free helper function (`resolveAccessLogs`, `resolveFlowLogs`, …), often in another file.
+
+Checking the call site catches both failure modes at once: to satisfy the rule at the leaf you must thread `context` into the helper, which in turn forces the parameter onto the parent's `build`.
+
+## ❌ Incorrect
+
+```ts
+function resolveAccessLogs(scope: IConstruct, props: Props): Bucket {
+  return props.logBucket.build(scope, "LogBucket");
+}
+```
+
+## ✅ Correct
+
+```ts
+function resolveAccessLogs(scope: IConstruct, props: Props, context?: BuildContext): Bucket {
+  return props.logBucket.build(scope, "LogBucket", context);
+}
+```
+
+## Why exactly two arguments
+
+`Lifecycle.build(scope, id, context?)` is always called with at least `scope` and `id`, so a two-argument call is the precise signature of the bug. Matching exactly two — rather than "fewer than three" — keeps the rule off unrelated `build()` methods that share the name, notably `StatementBuilder.build()` in `@composurecdk/iam`, which takes none.
+
+A spread call such as `target.build(...args)` is one argument and is likewise skipped: that is the generic forwarding wrapper in `tagged-builder.ts`, which passes context through by construction.
+
+## Escape hatch
+
+A root-level build genuinely has no context to forward — nothing composed it. Silence those explicitly, so the exception stays visible in review:
+
+```ts
+// eslint-disable-next-line composurecdk/lifecycle-build-must-forward-context -- root build: the strategy callback receives only (scope, id)
+stackBuilder.build(scope, id);
+```
+
+Application entry points build at the root as a matter of course, so this repo's root config switches the rule off for `packages/examples/src`.
+
+## How it works
+
+Deliberately syntactic, like every rule in this plugin. Type information would let it assert the receiver really is a `Lifecycle`, but the residual false-positive set is small and specific — root-level standalone builds, above — so the added cost is not yet worth paying.

package/docs/rules/no-cdk-api-above-floor.md

@@ -0,0 +1,56 @@
+# composurecdk/no-cdk-api-above-floor
+
+Flags use of an `aws-cdk-lib` API newer than the package's supported peer-dependency floor.
+
+- **Preset:** `internal` (`error`)
+- **Decision:** [ADR-0008](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0008-aws-cdk-lib-version-floors.md)
+
+## Why
+
+Such calls compile fine — devDependencies track the latest CDK — but **throw at runtime** for a consumer on an older, still-supported version inside the declared `^2` peer range. Nothing else catches it: the type checker sees the newest CDK, and the unit suites run against it too.
+
+[ADR-0008](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0008-aws-cdk-lib-version-floors.md) covers how the floors are chosen and enforced.
+
+## ❌ Incorrect
+
+```ts
+import { CfnAlarm } from "aws-cdk-lib/aws-cloudwatch";
+
+if (CfnAlarm.isCfnAlarm(node)) {
+  // TypeError on aws-cdk-lib < 2.231.0
+}
+```
+
+## ✅ Correct
+
+```ts
+import { CfnResource } from "aws-cdk-lib";
+import { CfnAlarm } from "aws-cdk-lib/aws-cloudwatch";
+
+if (CfnResource.isCfnResource(node) && node.cfnResourceType === CfnAlarm.CFN_RESOURCE_TYPE_NAME) {
+  // what the static does internally, valid across the whole peer range
+}
+```
+
+`@composurecdk/cloudwatch` exposes this as an `isCfnAlarm` helper; see [ADR-0011](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0011-cross-component-relationship-guards.md) for the pattern.
+
+## The ban list
+
+Currently one entry: the per-resource `Cfn<Resource>.isCfn<Resource>` L1 static type guards, which `aws-cdk-lib` first shipped on every generated L1 in **2.231.0** (verified by installing real versions — 2.230.0 lacks them). See issue #146.
+
+`isCfnResource` and `isCfnElement` are explicitly allowed: they are core, predate the floor, and `isCfnResource` is the portable replacement.
+
+The list is expected to grow as floors are pinned and lowered ahead of 1.0.0. Add an entry whenever an API turns out to postdate the floor.
+
+## Known gaps
+
+Both uncommon in this ESM source:
+
+- Computed bracket access — `CfnAlarm["isCfnAlarm"](x)`.
+- `import = require()` bindings.
+
+## How it works
+
+Matched by the accessed **member name** rather than the owning class identifier, so it holds regardless of how the class is imported or aliased — `CfnAlarm.isCfnAlarm`, `cw.CfnAlarm.isCfnAlarm`, `cdk.aws_cloudwatch.CfnAlarm.isCfnAlarm` all match.
+
+Resolution runs through ESLint's scope manager, so a local shadowing the import name (a parameter called `CfnAlarm`, say) is correctly treated as a non-CDK binding. TS-only wrappers (`as`, `satisfies`, `!`, angle-bracket assertion) are unwrapped so they cannot smuggle a call past the rule. A call in the chain — `Stack.of(x).isCfnY()` — breaks the root link, since that reads a runtime value rather than the import.

package/docs/rules/no-cjs-incompatible-syntax.md

@@ -0,0 +1,48 @@
+# composurecdk/no-cjs-incompatible-syntax
+
+Flags syntax in library `src/` that has no CommonJS emit: `import.meta`, top-level `await`, and top-level `for await…of`.
+
+- **Preset:** `dualPublishing` (`error`)
+- **Decision:** [ADR-0007](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0007-dual-esm-cjs-publishing.md)
+
+## Why
+
+Every `@composurecdk/*` package is dual-published, ESM and CommonJS. All three constructs are valid ESM with no CJS equivalent, so `tsc` — and `tshy`'s CommonJS dialect — errors on them.
+
+Catching them at lint time gives an in-editor error immediately, rather than waiting for the per-dialect compile to fail.
+
+## ❌ Incorrect
+
+```ts
+const here = import.meta.url;
+
+const config = await loadConfig();
+
+for await (const chunk of stream) {
+  // …
+}
+```
+
+## ✅ Correct
+
+```ts
+import { fileURLToPath } from "node:url";
+
+async function init(): Promise<Config> {
+  const config = await loadConfig();
+  for await (const chunk of stream) {
+    // …
+  }
+  return config;
+}
+```
+
+Move the `await` inside an async function. Where a module genuinely needs its own location, take it from a parameter or a caller-supplied value rather than `import.meta`.
+
+## Scope
+
+Library `src/` only. Test files are never published, so they may use all three freely — this repo's root config applies the preset to `packages/*/src/**/*.ts`.
+
+## How it works
+
+Syntactic. `import.meta` is matched as a `MetaProperty`; `await` and `for await…of` are reported only when no enclosing function declaration, function expression or arrow function is found in the ancestor chain — that is, only at the top level.