lint-suite 1.6.0 → 1.6.2

package/README.md

@@ -62,7 +62,13 @@ export default [
 `recommended` is intentionally framework-agnostic — it ships only the language + architecture + format baseline (`base`, `javascript`, `typescript`, `json`, `boundaries`, `prettier`). Add the framework/tooling configs your project actually uses:
 
 ```js
-import { recommended, angular, angularTemplate, rxjs, vitest } from 'lint-suite/eslint';
+import {
+  recommended,
+  angular,
+  angularTemplate,
+  rxjs,
+  vitest
+} from 'lint-suite/eslint';
 
 export default [
   ...recommended,
@@ -77,21 +83,28 @@ export default [
 
 ## Available Configurations
 
-| Configuration       | Description                                              |
-| ------------------- | -------------------------------------------------------- |
-| `base`              | Core JavaScript rules, formatting, and complexity limits |
-| `javascript`        | JavaScript-specific rules via `@nx/eslint-plugin`        |
-| `typescript`        | TypeScript strict typing, imports, and naming conventions |
-| `angular`           | Angular component best practices with Signal support     |
-| `angularTemplate`   | HTML template rules with accessibility and performance   |
-| `rxjs`              | Observable patterns, operator safety, and subscriptions  |
-| `vitest`            | Vitest testing rules and matcher improvements            |
-| `playwright`        | Playwright e2e locator and matcher best practices        |
-| `json`              | JSON linting with comment support for tsconfig/vscode    |
-| `storybook`         | Storybook CSF enforcement                                |
-| `boundaries`        | Module boundary rules (feature, data-access, ui, etc.)   |
-| `prettier`          | Disables rules that conflict with Prettier (use last)    |
-| **`recommended`**   | **Baseline only: `base` + `javascript` + `typescript` + `json` + `boundaries` + `prettier` — compose the rest on top** |
+| Configuration                                                                                                 | Description                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `base`                                                                                                        | Core JavaScript rules, formatting, and complexity limits                                                               |
+| `javascript`                                                                                                  | JavaScript-specific rules via `@nx/eslint-plugin`                                                                      |
+| `typescript`                                                                                                  | TypeScript strict typing, imports, and naming conventions                                                              |
+| `angular`                                                                                                     | Angular component best practices with Signal support                                                                   |
+| `angularTemplate`                                                                                             | HTML template rules with accessibility and performance                                                                 |
+| `rxjs`                                                                                                        | Observable patterns, operator safety, and subscriptions                                                                |
+| `vitest`                                                                                                      | Vitest testing rules and matcher improvements                                                                          |
+| `playwright`                                                                                                  | Playwright e2e locator and matcher best practices                                                                      |
+| `json`                                                                                                        | JSON linting with comment support for tsconfig/vscode                                                                  |
+| `storybook`                                                                                                   | Storybook CSF enforcement                                                                                              |
+| `boundaries`                                                                                                  | Module boundary rules (feature, data-access, ui, etc.)                                                                 |
+| `prettier`                                                                                                    | Disables rules that conflict with Prettier (use last)                                                                  |
+| **`recommended`**                                                                                             | **Baseline only: `base` + `javascript` + `typescript` + `json` + `boundaries` + `prettier` — compose the rest on top** |
+| **Angular project analysis:** The `angular` preset enables `projectService: true` and project analysis for    |
+| `lint-suite-angular/no-unused-instance-fields`. It counts exact reads in the configured TypeScript/Angular    |
+| Program, including external parent templates/TypeScript, subclasses, and Angular interface implementations;   |
+| code outside that Program is unknowable. Project mode also reports unused public/protected directive members. |
+| Direct rule usage remains local by default, and `allowEffectFields` is opt-in. After cross-file or template   |
+| changes, do not use ESLint `--cache` for correctness gates; run a full non-cached lint (for example,          |
+| `eslint --no-cache`).                                                                                         |
 
 ## Customization
 
@@ -111,6 +124,138 @@ export default [
 ];
 ```
 
+### Unused Angular instance fields
+
+The `angular` config enables `lint-suite-angular/no-unused-instance-fields`.
+Local analysis recognizes reads from the class, component template, and host
+expressions. Use project analysis when other TypeScript files or Angular
+templates can read a component or directive member:
+
+```js
+{
+  files: ['**/*.ts'],
+  languageOptions: {
+    parserOptions: {
+      projectService: true,
+      tsconfigRootDir: import.meta.dirname
+    }
+  },
+  rules: {
+    'lint-suite-angular/no-unused-instance-fields': [
+      'error',
+      {
+        analysis: 'project',
+        allowEffectFields: true
+      }
+    ]
+  }
+}
+```
+
+- `analysis` defaults to `'local'`. Project mode excludes spec-file reads. A
+  file it cannot index exactly (a template that does not parse, metadata it
+  cannot evaluate, a read it cannot type) falls back to name matching for
+  that file only: every member whose name that file mentions counts as read.
+  Set `LINT_SUITE_DEBUG=1` to print which files fell back and why, for
+  example `LINT_SUITE_DEBUG=1 eslint --no-cache src/app/some.component.ts`.
+- `allowEffectFields` defaults to `false`. When enabled, fields holding
+  auto-cleaned Angular `effect()` calls are allowed; effects configured with
+  `manualCleanup: true` must still be read.
+- Angular signal inputs, models, outputs, and query fields are always treated
+  as framework-managed.
+- Fields typed with `ComponentRef` imported from `@angular/core` are excluded
+  from unused-field reports.
+- In local mode, non-private members of `abstract` components and directives
+  are exempt: subclasses that read them live in other files. Project mode
+  resolves those subclass reads and reports the members normally.
+- Project analysis is incremental. The index is kept per tsconfig; when an
+  editor hands the rule a changed Program after a save, only the saved file and
+  the files whose reads depended on it are re-indexed, so feedback stays fast
+  in large workspaces. Template references (`#ref`, `#ref="exportAs"`) resolve
+  within a standalone component's `imports`; when that scope cannot be
+  determined statically (NgModule declarations, `hostDirectives`, spreads),
+  every matching component or directive in the Program is a candidate. Extra
+  candidates can only add reads. Metadata strings may be constants.
+
+### Explicit accessibility
+
+The `typescript` preset enables `local/explicit-accessibility`, which reports
+class members (fields, methods, accessors, abstract members, and constructor
+parameter properties) without an explicit `public`, `private`, or `protected`
+modifier. `#private` members are ignored: TypeScript forbids a modifier there.
+
+```js
+{
+  rules: {
+    'local/explicit-accessibility': [
+      'error',
+      { defaultAccessibility: 'private' }
+    ]
+  }
+}
+```
+
+- `defaultAccessibility` defaults to `public` and drives `eslint --fix`; the
+  IDE offers the other two levels as suggestions.
+- `defaultAccessibility: 'none'` reports without an auto-fix and offers all
+  three levels as suggestions.
+- Constructors are always fixed to `public`. A private constructor breaks
+  `new` and dependency injection.
+- The fix does not default to `private` because members implementing an
+  interface or read by an Angular template must stay non-private, and the
+  rule cannot see either.
+
+### Readonly type properties
+
+The `typescript` preset enables `local/readonly-type-properties`, which
+reports primitive-typed properties in `type` aliases, interfaces, and
+inline object types that are not marked `readonly`, and auto-fixes them
+with `eslint --fix`. A property is primitive-typed when its annotation is
+`string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `undefined`, a
+literal or template-literal type, or a union/intersection of those.
+
+```ts
+// Before
+type User = { name: string; roles: string[]; profile: Profile };
+
+// After --fix
+type User = { readonly name: string; roles: string[]; profile: Profile };
+```
+
+- Arrays, object types, type references (including string-union aliases
+  like `Status`), functions, and tuples are left untouched because the
+  rule is syntactic and does not resolve types.
+- Index signatures, mapped types, and method signatures are out of scope.
+- Use `// eslint-disable-next-line local/readonly-type-properties` when a
+  property genuinely needs to stay mutable.
+
+### No inline object types
+
+The `typescript` preset enables `local/no-inline-object-types`, which
+reports object type literals nested inside a `type NAME = ...` alias
+declaration (nested properties, array element types, union members,
+intersection members, and generic arguments such as `Readonly<{...}>`).
+It is not auto-fixable: extracting an inline object type requires
+choosing a name.
+
+```ts
+// Before
+type LineItem = { readonly name: string; readonly item: { readonly id: string } };
+
+// After
+type Item = { readonly id: string };
+type LineItem = { readonly name: string; readonly item: Item };
+```
+
+- The direct body of a `type X = {...}` alias is allowed to be an object
+  literal; any object type literal nested inside that alias must reference
+  a named type instead.
+- Positions outside a type alias — function parameters and return types,
+  `as`/`satisfies` expressions, generic call arguments, interface members,
+  and class members — are not checked by this rule.
+- Declare the shape as `type Item = {...}` and reference it instead of
+  inlining the object type.
+
 ## Stylelint and Prettier presets
 
 These are standalone configs exported as subpaths — they are not part of the `recommended` ESLint array.