Skip to main content

Type-aware linting readiness

Use this guide when you want the full checker-backed behavior of the plugin's typed branches.

When this guide appliesโ€‹

Use this checklist when adopting:

  • immutable.configs.recommended with projectService enabled for immutable-data
  • immutable.configs.immutable or any stricter preset when you want the implicit-array inference branch of readonly-array
  • a custom flat-config block that enables immutable-data or readonly-array and relies on parser services

Readiness checklistโ€‹

1) Parser-service availabilityโ€‹

Confirm the lint runtime can provide full type services:

  • ESLint uses @typescript-eslint/parser
  • your lint config resolves the intended tsconfig(s)
  • the targeted files are included in those tsconfig(s)

2) Know which rules gain precisionโ€‹

Today the most relevant checker-backed paths are:

  • immutable-data when it distinguishes mutable array/object operations from freshly-created values
  • readonly-array when it infers implicit mutable array types from initializers

Without parser services, these rules fall back conservatively instead of crashing, but they may report less precisely.

3) Project graph stabilityโ€‹

Before enabling stricter checks:

  • npm run typecheck is green
  • baseline linting is green (or has a controlled known backlog)
  • generated types/artifacts are not stale

4) Performance baselineโ€‹

Capture a baseline to detect regressions:

npx eslint "src/**/*.{ts,tsx}" --stats

Track:

  • total runtime
  • expensive files
  • hot rules that call type-checker operations frequently

5) CI gate orderingโ€‹

Prefer this order:

  1. typecheck
  2. lint (typed parser services enabled where needed)
  3. tests

This keeps typed-service failures easy to classify.

  1. Start with one package/folder.
  2. Enable type-aware rules as warn first.
  3. Fix baseline findings in small batches.
  4. Promote to error once the scope stays green.
  5. Expand scope incrementally.

Fast validation commandsโ€‹

npm run typecheck
npm run lint
npm run test

For focused typed checks during migration:

npx eslint "src/**/*.{ts,tsx}" --stats

Common failure modesโ€‹

Typed behavior is missing or less precise than expectedโ€‹

Likely causes:

  • file not included in the active tsconfig
  • parser-service wiring mismatch for the current workspace
  • incorrect project root assumptions in local/CI lint execution
  • projectService not enabled in the config block that spreads the preset

Typical symptoms:

  • immutable-data falling back to its conservative assumeTypes behavior
  • readonly-array still reporting explicit T[] syntax but skipping implicit array inference for unannotated declarations

Large runtime regressionsโ€‹

Likely causes:

  • expensive semantic checks on broad selectors
  • repeated checker calls without syntax prefilters
  • too-large rollout scope for first pass