@composurecdk/eslint-plugin 0.10.0

package/docs/rules/no-realm-bound-instanceof.md

@@ -0,0 +1,87 @@
+# composurecdk/no-realm-bound-instanceof
+
+Bans `instanceof` against a class reached through an `import`, in library `src/`.
+
+- **Preset:** `recommended` (`error`)
+- **Decision:** [ADR-0007](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0007-dual-esm-cjs-publishing.md), [ADR-0011](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0011-cross-component-relationship-guards.md), [ADR-0019](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0019-lint-rules-as-public-contract.md)
+
+## Why
+
+`instanceof` is realm-bound, and library source is published dual ESM/CJS. When both copies of a package load in one process — the dual-package hazard — each copy has its own class objects. An instance minted by one copy fails `instanceof` against the other copy's class, so the check returns `false` for a value that is plainly of that type.
+
+That has already shipped as two bugs: **#384**, where a stack-singleton dedup was silently skipped and collided on a construct id, and **#385**, where a `StatementBuilder` went unrecognised and skipped the wildcard-resource security guard. Both failed silently, which is the characteristic danger here.
+
+## ❌ Incorrect
+
+```ts
+import { StatementBuilder } from "./statement-builder.js";
+
+if (value instanceof StatementBuilder) {
+  // false across the dual-package boundary
+}
+```
+
+## ✅ Correct
+
+```ts
+const STATEMENT_BUILDER = Symbol.for("composurecdk.statement-builder");
+
+if (typeof value === "object" && value !== null && STATEMENT_BUILDER in value) {
+  // a Symbol.for brand is realm-agnostic
+}
+```
+
+That is the fix when the class is **yours**. The report tells you which case you are in, because the import says so:
+
+| Import                     | Message           | Fix                                                                                                                                                                                             |
+| -------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Relative — your own module | `ownClass`        | Brand it with `Symbol.for(…)`.                                                                                                                                                                  |
+| `aws-cdk-lib`              | `cdkClass`        | Read the L1 — `CfnResource.isCfnResource(x) && x.cfnResourceType === …`, per [ADR-0011](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0011-cross-component-relationship-guards.md). |
+| Any other package          | `dependencyClass` | You cannot brand a class you do not own. Prefer a type guard the package exports, or test a distinguishing property rather than identity.                                                       |
+
+## Every import is in scope by default, relative ones included
+
+A relative import is **not** a same-realm guarantee by default. `./statement-builder.js` resolves separately in each copy of the package, which is exactly how #385 happened.
+
+## Options
+
+### `assumeNeverInstalledAsADependency`
+
+```js
+"composurecdk/no-realm-bound-instanceof": ["error", { assumeNeverInstalledAsADependency: true }]
+```
+
+Asserts that **this package cannot load twice in one process**, so its own modules resolve to one set of class objects. Relative imports are then treated as same-realm; everything else is still flagged, because whether a _dependency_ loads twice is a property of the consumer's install, not of your source.
+
+**An application is the archetype** — nothing installs one as a dependency, so it genuinely loads once. Being `private` is not the test: a private package can still be a dependency, and one in this repo is depended on by seventeen others.
+
+**A library must not set it**, even a single-format one. A consumer can install two versions of your library side by side, and then your relative imports duplicate exactly as a dual-published package's do — the hazard returns with the option silencing it. Shipping one module format is not sufficient; the condition is that nothing can install you twice.
+
+Default `false`, which flags every import.
+
+Only relative specifiers are exempted. A `#` subpath is **not**: Node's `imports` field can map one to an external package, so `#dep` may resolve into `node_modules` like any dependency.
+
+### Why this is an option rather than a preset
+
+Only one of the rule's two halves is a property of your own package, so a tier cannot express it — moving the whole rule into `dualPublishing` would silence the bare-specifier half, which is the half that caused both shipped bugs. See [ADR-0019](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0019-lint-rules-as-public-contract.md) and [#450](https://github.com/laazyj/composureCDK/issues/450).
+
+## Not flagged
+
+Neither can be duplicated by the hazard:
+
+- **Globals and intrinsics** — `x instanceof RegExp`, `x instanceof Error`. They resolve to no import binding, so the scope walk skips them.
+- **Classes declared in the same module** — the class and every `new` of it come from one evaluation of that module.
+
+## Known gaps
+
+Both uncommon in this ESM source:
+
+- `import = require()` bindings.
+- An intermediate call that breaks the chain — `getClasses().Bucket` reads a runtime value rather than the import.
+- A **relative path that leaves the package** (`../../other/src/x.js`, possible in a workspace) is exempted by the option although it reaches a different package. This repo bans that import shape outright; a consumer's may not.
+- A **tsconfig path alias** (`@app/thing`, `~/thing`) resolves in-package but looks bare, so it is still flagged under the option — an over-report, not a miss.
+- A package importing **itself by name** (`@scope/pkg` from inside `@scope/pkg`) is treated as a dependency, so `assumeNeverInstalledAsADependency` does not exempt it. Conservative rather than wrong — it over-reports, never under-reports — and self-reference needs an `exports` field, which an application, the only legitimate setter of that option, does not have.
+
+## How it works
+
+Resolution is scope-aware, so a local shadowing an import name is correctly treated as a non-import binding. TS-only wrappers (`as`, `!`, `satisfies`, angle-bracket assertion) are unwrapped rather than trusted.

package/docs/rules/no-typescript-private-modifier.md

@@ -0,0 +1,72 @@
+# composurecdk/no-typescript-private-modifier
+
+Flags the TypeScript `private` modifier on a class member, in favour of an ECMAScript `#` private field.
+
+- **Preset:** `libraryAuthor` (`error`)
+- **Decision:** [ADR-0001](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0001-builder-type-emission.md)
+
+## Why
+
+The two kinds of privacy look interchangeable and are not, once a class is generic over its own members.
+
+A TypeScript `private` member is still **part of the type**. It appears in `keyof T`, so it survives into any mapped type built from the class — and from there into the emitted `.d.ts`, where a consumer's compiler meets a name it cannot refer to and reports **TS4094**. The error surfaces in the consumer's build, not in the one that produced the declaration.
+
+An ECMAScript `#field` is not part of the type at all, so nothing downstream can trip over it.
+
+Builders are the case that forces this, since a builder's public type is derived from its class by a mapped type — but the hazard belongs to any class whose type is transformed rather than written out by hand.
+
+## ❌ Incorrect
+
+```ts
+class BucketBuilderImpl {
+  private props: BucketProps = {};
+
+  private clone(): this {
+    return this;
+  }
+}
+
+class Component {
+  constructor(private readonly scope: IConstruct) {}
+}
+```
+
+## ✅ Correct
+
+```ts
+class BucketBuilderImpl {
+  #props: BucketProps = {};
+
+  #clone(): this {
+    return this;
+  }
+}
+
+class Component {
+  readonly #scope: IConstruct;
+
+  constructor(scope: IConstruct) {
+    this.#scope = scope;
+  }
+}
+```
+
+A parameter property cannot be `#private` — there is no syntax for it — so the field is declared on the class and assigned in the constructor body.
+
+## Not flagged
+
+| Shape                            | Why it is allowed                                                                                                                |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `private constructor() {}`       | `#constructor` is not valid syntax, so there is nothing to prefer. Private constructors stay available for factory-only classes. |
+| `protected` and `public` members | Deliberately part of the type; this rule is only about privacy that leaks.                                                       |
+| `constructor(readonly scope: T)` | A parameter property with no accessibility modifier. It is public by design.                                                     |
+
+## How it works
+
+Three syntactic selectors — a `private` property, a `private` method that is not a constructor, and a `private` parameter property. No type information, so it runs in a flat config and reports as you type.
+
+## History
+
+`private accessor x` was not caught while this was a config: `accessor` fields parse as a distinct node that none of the three selectors matched, though the `private` on one reaches `keyof T` exactly as a plain field's does. The rule closes that hole, so it flags slightly more than the selectors did.
+
+This shipped as three `no-restricted-syntax` selectors before becoming a rule. That was fine while the preset was private to one repo and fatal once published: flat config **replaces** rule options rather than merging them, so a consumer configuring `no-restricted-syntax` for their own purposes would silently drop all three selectors — no error, no warning. A named rule composes instead of colliding.

package/docs/rules/redeclared-prop-must-track-cdk-type.md

@@ -0,0 +1,60 @@
+# composurecdk/redeclared-prop-must-track-cdk-type
+
+Flags a re-declared CDK prop that pins a named CDK interface inside `Resolvable<…>` instead of reading the type from CDK's own prop.
+
+- **Preset:** `libraryAuthor` (`error`)
+- **Decision:** [ADR-0018](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0018-re-declared-props-track-cdk-prop-types.md)
+
+## Why
+
+A builder's props interface is `Omit<CdkProps, K>` plus a re-declaration of each lifted key. Everything inside the `Omit` tracks the consumer's installed `aws-cdk-lib` — that is the point of extending CDK's own type. A re-declared key spelled `Resolvable<IKey>` does not: it freezes at whatever interface was current when it was written, so when CDK widens that prop the builder silently starts **rejecting values the wrapped construct accepts**.
+
+Nothing else catches it. The suites do not typecheck, and `build` runs against the latest CDK, where a narrowed prop still compiles — it is narrower, not wrong. The failure surfaces in a consumer's own `tsc`.
+
+[ADR-0018](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0018-re-declared-props-track-cdk-prop-types.md) has the full case, including the two instances that shipped unnoticed for seven months and why raising the version floors was rejected instead.
+
+## ❌ Incorrect
+
+```ts
+import { type IKey } from "aws-cdk-lib/aws-kms";
+import { type TopicProps } from "aws-cdk-lib/aws-sns";
+
+export interface TopicBuilderProps extends Omit<TopicProps, "masterKey"> {
+  masterKey?: Resolvable<IKey>;
+}
+```
+
+## ✅ Correct
+
+```ts
+import { type TopicProps } from "aws-cdk-lib/aws-sns";
+
+export interface TopicBuilderProps extends Omit<TopicProps, "masterKey"> {
+  masterKey?: Resolvable<NonNullable<TopicProps["masterKey"]>>;
+}
+```
+
+The prop now accepts exactly what the consumer's `aws-cdk-lib` accepts, at every floor, because it _is_ that type.
+
+**Keep the indexed access inline.** Extracting it to a named alias puts an unnameable type into the emitted builder type and reintroduces [ADR-0001](https://github.com/laazyj/composureCDK/blob/main/docs/adr/0001-builder-type-emission.md)'s TS2883.
+
+## Not flagged
+
+Each is a deliberate exclusion in ADR-0018:
+
+| Shape                                                         | Why it is allowed                                                                                               |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Resolvable<string[]>`, `Resolvable<Record<string, unknown>>` | Primitives and `any`-shaped types resolve to no CDK import.                                                     |
+| `Resolvable<string \| Foo["bar"]>`                            | A widened union — the arm the builder adds has no CDK prop to read from. Only a bare type reference is flagged. |
+| A shape-replacing re-declaration                              | The builder's own type is the point; it is not a `Resolvable` of a CDK interface.                               |
+
+## Known gaps
+
+Both are covered by ADR-0018 and by review rather than by this rule:
+
+- A prop re-declared in a **separate interface** that the props interface mixes in (`@composurecdk/sqs`'s `QueueBuilderExtensionProps`) has no `Omit` of its own to key on.
+- A **hand-written setter** standing in for a lifted prop is a class method, not a property signature.
+
+## How it works
+
+Purely syntactic — no type resolution, so it runs in the flat config and fires at authoring time. The rule looks for a property whose name appears in the `Omit<…>` of its own interface's `extends` clause, and whose `Resolvable<…>` argument is a bare type reference imported from `aws-cdk-lib` or `@aws-cdk/*`.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@composurecdk/eslint-plugin",
+  "version": "0.10.0",
+  "description": "Internal ESLint plugin encoding ComposureCDK architectural invariants (tagged builders, lifecycle context, builder copy state).",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laazyj/composureCDK.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "clean": "rm -rf dist .tshy .tshy-build",
+    "build": "tshy",
+    "typecheck": "tsc --noEmit",
+    "check:exports": "attw --pack . --profile node16 && publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "aws-cdk",
+    "composurecdk",
+    "static-analysis",
+    "architecture"
+  ],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/estree": "^1.0.9",
+    "@types/node": "^26.5.1",
+    "@typescript-eslint/parser": "^8.70.0",
+    "eslint": "^10.10.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:tooling"
+    ]
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js"
+}