lint-suite 1.6.3 → 2.0.0

package/README.md

@@ -106,6 +106,18 @@ export default [
 | changes, do not use ESLint `--cache` for correctness gates; run a full non-cached lint (for example,          |
 | `eslint --no-cache`).                                                                                         |
 
+## Disk cache
+
+`no-unstyled-classes`, `no-unused-classes`, and `no-unused-instance-fields`
+parse component metadata, stylesheets, and templates once per file and keep
+the result in memory for the life of the process, keyed by the file's mtime
+and size. The same entries are mirrored to
+`node_modules/.cache/lint-suite/*.json` under the current working directory
+at process exit, so the next ESLint or stylelint process (a CI run, or an
+editor's first lint) skips every parse of a file that did not change. Set
+`LINT_SUITE_CACHE_DIR` to move the directory, or `LINT_SUITE_CACHE=0` to
+keep everything in memory only.
+
 ## Customization
 
 You can override any rules by adding a `rules` section to your ESLint config:
@@ -152,6 +164,13 @@ templates can read a component or directive member:
 }
 ```
 
+- In an editor session the index is updated incrementally: a save re-indexes
+  only the saved file and the files whose resolutions depended on it. The
+  saved file's own templates, and the templates of every component in its
+  folder, are re-read on every lint; edits to templates in other folders are
+  picked up on a throttled schedule (at most every 100× the duration of the
+  last check), so a cross-folder template edit can take a moment to show up
+  in another file's diagnostics.
 - `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
@@ -193,7 +212,11 @@ reported. `[ngClass]` is deliberately not analysed.
 Stylesheets come from the component beside the template: `styleUrl`,
 `styleUrls`, and inline `styles` read as string or template literals from the
 `@Component` metadata, falling back to a sibling `.scss` or `.css` file when
-the metadata declares none. Each stylesheet is parsed with `postcss-scss`, so
+the metadata declares none. A `<link rel="stylesheet" href="...">` in the
+template itself is read too, resolved against the template's directory, so a
+plain HTML page without a component is judged against the stylesheets it
+links; root-relative (`/x.css`) and absolute (`https://...`) links are
+skipped. Each stylesheet is parsed with `postcss-scss`, so
 `&__element`, `&--modifier`, `&.other`, `& > .child`, `.wrapper &`, and rules
 nested inside `@media` all resolve against their parent selector, and a
 selector list such as `.a, .b { &__x {} }` yields both `.a__x` and `.b__x`.
@@ -243,9 +266,13 @@ file; each matching component contributes its `templateUrl` file or its inline
 `template` literal, and their classes are merged, so a stylesheet shared by two
 components is judged against both templates. When no component declares the
 stylesheet, a sibling template of the same name (`card.component.scss` →
-`card.component.html`) is used instead. A partial (`_tokens.scss`) or a global
-`styles.scss` that no component declares has no template, and the rule stays
-silent.
+`card.component.html`) and every `.html` file in the same directory whose
+`<link rel="stylesheet" href="...">` resolves to it are used instead, plus
+every template anywhere under the working directory whose link resolves to
+it (`node_modules`, `dist`, `coverage`, and dot-folders are skipped), so a
+plain `styles.css` beside an `index.html` and a shared stylesheet linked from
+other folders are both checked. A partial (`_tokens.scss`) or a global
+`styles.scss` that nothing links has no template, and the rule stays silent.
 
 Selectors resolve through the same parser as the ESLint rule, so `&__element`,
 `&--modifier`, `&.other`, `& > .child`, `.wrapper &`, `@media` blocks, and
@@ -339,6 +366,9 @@ 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.
+- The same rule reports and fixes `readonly T[]` and `ReadonlyArray<T>` to
+  `T[]`: the property reference is readonly, the array contents stay
+  mutable.
 - 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.
@@ -346,29 +376,25 @@ type User = { readonly name: string; roles: string[]; profile: Profile };
 ### 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.
+reports every object type literal that is not the direct body of a
+`type NAME = ...` alias: nested properties, array element types, union and
+intersection members, generic arguments such as `Readonly<{...}>`, function
+parameter and return types, `satisfies` targets, interface and class
+members, and members of a `declare module` block. 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 } };
+const describe = (field: { readonly name: string }): { readonly label: string } => ...
 
 // After
-type Item = { readonly id: string };
-type LineItem = { readonly name: string; readonly item: Item };
+type Field = { readonly name: string };
+type FieldSummary = { readonly label: string };
+const describe = (field: Field): FieldSummary => ...
 ```
 
-- 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.
+- The direct body of a `type X = {...}` alias is the only allowed position.
+- Mapped types (`{ [K in Keys]: T }`) are a different node and stay valid.
 
 ### One-line guard
 
@@ -402,6 +428,77 @@ if (!user) return null;
   single-line guard once it exists, while `local/one-line-guard` is what
   collapses a braced guard down to one line in the first place.
 
+### Statement shape rules
+
+The `typescript` preset enables a family of small syntactic rules that make
+control flow and data shape visible by reading the code's outline. None of
+them reads type information or the filesystem; each listens to one node
+type and reports in microseconds per file. Where a fix needs a name the rule
+offers an IDE suggestion with a placeholder name instead of an auto-fix.
+
+| Rule | Reports | Fix |
+|---|---|---|
+| `local/no-call-in-condition` | A function call inside an `if` condition, or inside a boolean `const` that an `if` tests. Zero-argument `this.x()` calls (Angular signal reads) and type-predicate calls are exempt; predicates are found through scope in the same file, or through the type checker when a program is available. Option `allowPredicates` (regex sources, default `['^(is\|has)[A-Z]']`) applies when there is no program. | Suggestion: hoist to a `const` |
+| `local/max-condition-operands` | An `if` condition with more than `max` (default 3) operands joined by `&&` / `\|\|`. | none |
+| `local/no-grouped-condition` | A parenthesised group with a different operator inside an `if` condition or a boolean `const` (`a && (b \|\| c)`). | Suggestion: hoist the group |
+| `local/ternary-branch-shape` | A ternary branch that is not a name, literal, template literal, or plain member access. | none |
+| `local/chain-receiver-is-name` | A member chain starting on an inline expression: `(a ?? b).x`, `{...}.x`, `[...].x`, `(await p).x`. | Suggestion: name the receiver |
+| `local/chain-fits-line` | A chain of two or more calls whose `.method(` parts sit on different lines. A multi-line callback argument does not count. | none |
+| `local/arrow-body-fits-line` | An expression-bodied arrow whose body wraps onto more lines. | Fix: block body with `return` |
+| `local/no-nested-object-value` | A property value that is a non-empty object literal, an array holding object literals, a ternary, or a call chain. Decorator arguments (`@Component({...})`) and files matching `configFiles` (default `**/*.config.*`, `**/eslint.config.*`, `**/*.schema.ts`) are exempt. | Suggestion: hoist to a `const` |
+| `local/no-spread-expression` | `...(expr)` where the argument is not a name or member access. | Suggestion: hoist to a `const` |
+| `local/no-inline-return-object` | `return {...}` and `=> ({...})`. | Suggestion: `const result = {...}; return result;` |
+
+### Project layout rules
+
+Also in the `typescript` preset. These read only the file's own path and
+return no listeners for files they do not cover, so they cost one regex
+per file.
+
+| Rule | Reports | Options |
+|---|---|---|
+| `local/type-placement` | An exported `type` outside a `common/*.type.ts` or `test/common/*.type.ts` file; a value exported from a `*.type.ts` file; a non-`const` export from a `*.const.ts` file; an `import type` from a relative or internal path that is neither a `*.type.ts` file nor a `common` barrel (`../common`, `./common/index.ts`, `@shared/common`). `.spec.ts`, `.stub.ts`, `.d.ts`, `state.type.ts` (any prefix), and fixtures are exempt; a `.spec.util.ts` file is not, so an exported type in one is reported. Never resolves imports. | `internalPatterns`: regex sources for alias prefixes that must resolve to a `*.type.ts` file. Default empty: a workspace alias (`@shared/common`) resolves to a library entry point, and module boundaries forbid deep imports, so alias type imports pass. |
+| `local/util-purity` | Inside `utils/*.util.ts` (excluding paths under `test/` or `testing/`): imports of `node:fs`, `child_process`, `os`, `process`, `http`, `net`, `worker_threads`; a module-level `let`; a module-level `new Map/Set/WeakMap/WeakSet`; `process.*`, `globalThis`, `window`, `document`, `localStorage`, `console`; `Date.now`, `Math.random`, `performance.now`, `crypto.randomUUID`; `setTimeout`, `setInterval`, `fetch`, `inject`, `require`. | `bannedModules` |
+| `local/test-file-shape` | A file named `*.spec-support.ts`, `*.spec-helper.ts`, `*.test-utils.ts`, `*-fixture.ts`, or under `__mocks__/` / `helpers/` / `common/stubs/`; a `.stub.ts` outside `test/stubs/`, a `.mock.ts` outside `test/mocks/`, a `.spec.util.ts` outside `test/utils/`, or any `fixtures/` directory outside `test/fixtures/` (a dedicated `testing/` library is exempt from all of these); a `test/stubs/*.stub.ts` export not named `UPPER_SNAKE_STUB` or without a type annotation; a `test/mocks/*.mock.ts` export that is not a camelCase `...Mock` function with an explicit return type. | none |
+
+### No unused exports
+
+The `typescript` preset enables `local/no-unused-exports`, which reports an
+export (values and types) that no other file in the TypeScript program
+imports, and a module that exports names but is never imported at all.
+
+- Source of truth is the program typescript-eslint already built for the
+  type-aware rules: no extra parse, no file enumeration, no filesystem.
+- Per file the rule walks top-level statements, plus every node of a file
+  whose text contains `import(`, and caches the result
+  on the `ts.SourceFile` object; the project-wide usage map is cached per
+  `ts.Program`, and an edit that only touches a few files patches that map
+  in place instead of rebuilding it. The patch is scoped per project
+  (`tsconfig`): programs from different projects never share an aggregate,
+  even when ESLint alternates between them in the same process. Editing one
+  file re-walks that file and rebuilds the map once. At 10k files the warm
+  cost is map lookups.
+- Re-exports are followed: `export { x } from`, `export * from`, and
+  `export * as ns from` count usage at the file that declares `x`, so a
+  barrel does not hide a dead export. `import * as ns`, default imports,
+  and dynamic `import('./x')` anywhere in the file (a lazy route's
+  `loadComponent: () => import('./x')` included) count every export of the
+  target as used.
+- Files matching `entryPoints` are never reported (default `**/main.ts`,
+  `**/main.*.ts`, `**/public-api.ts`, `**/index.ts`, `**/*.config.ts`,
+  `**/*.config.mts`, `**/*.config.cts`, `**/*.spec.ts`, `**/*.spec.util.ts`,
+  `**/*.stub.ts`, `**/*.mock.ts`, `**/*.d.ts`, `**/*.stories.ts`,
+  `**/environment*.ts`).
+  Files with `export =` or a `declare module` block are skipped.
+- Names an entry point re-exports (`export { x } from`, `export * from`)
+  are public API and never reported: an Nx library's `index.ts` protects
+  the exports other projects consume, even though those projects sit
+  outside the library's own TypeScript program.
+- The project is the linted file's tsconfig program. An export used only
+  from a file outside that program (for example a spec excluded by
+  `tsconfig.lib.json`) reports as unused; that is the same boundary `tsc`
+  draws.
+
 ## Stylelint and Prettier presets
 
 These are standalone configs exported as subpaths — they are not part of the `recommended` ESLint array.