This repository treats metadata-to-doc synchronization as a first-class quality gate, not a best-effort cleanup task.

The core principle​

Human-written explanation should stay human.

Mechanically derivable data should be generated and tested.

For us, that includes:

• README rules matrix
• presets rules matrix
• rule metadata snapshots and integrity contracts

What this prevents​

Without canonical generation, drift appears quickly:

• rule added to a preset but matrix unchanged
• fix/suggestion capability changes but docs lag
• links and IDs diverge between source and docs

That leads to wrong migration guidance and unnecessary issue churn.

How we enforce it​

• sync scripts produce canonical matrix sections
• CI checks fail when docs and generated sections diverge
• docs integrity tests enforce stable heading/catalog conventions

The result is less manual bookkeeping and fewer review-time surprises.

Practical maintenance advice​

When changing rules or preset composition:

1. update rule source and metadata
2. run matrix sync scripts
3. run docs integrity and snapshot suites
4. only then review prose-level docs edits

This ordering keeps intent and generated truth aligned.

Related docs​

• Rule catalog and docs synchronization chart
• Preset composition and rule matrix chart
• Presets page

The goal is not “run typed rules everywhere immediately.” The goal is predictable behavior under real project conditions.

The contract we want​

A healthy typed-rule setup has three explicit outcomes:

1. Typed path available: semantic checks run with parser services + checker.
2. Optional typed path unavailable: semantic branch is skipped safely.
3. Required typed path unavailable: fail fast with a clear configuration signal.

That split keeps failures actionable and prevents silent drift.

Why guard-first design matters​

In large codebases, parser-service availability is not uniform:

• different tsconfig scopes
• mixed package boundaries
• generated or excluded files

Guard-first execution avoids brittle behavior by making typed entry conditions explicit.

Rollout pattern that works​

• Start in one folder/package.
• Measure with --stats before and after enabling typed checks.
• Promote from warn to error once baseline noise is gone.
• Expand scope only when performance and diagnostics stay stable.

What to track​

• typed-rule error rate tied to config gaps
• lint runtime deltas after enabling typed presets
• rule-level hotspots that call checker APIs most often

If those stay stable, typed linting remains a quality upgrade instead of a workflow tax.

Related docs​

• Typed service path inventory
• Typed rule semantic analysis flow
• Type-aware linting readiness guide

In this plugin, a fix is not accepted just because it is convenient. A fix must be safe.

The safety bar​

Before a fixer is enabled, the rule needs confidence in three areas:

1. Semantic stability: The rewritten code must keep the same runtime meaning.
2. Syntactic stability: The output must stay valid TypeScript in real files.
3. Formatting stability: The change should cooperate with normal formatter and linter workflows.

If any of those checks are uncertain, we downgrade to a suggestion.

Fix versus suggestion​

Use fix when​

• the transformation is deterministic,
• there are no ambiguous symbols or scope collisions,
• and the replacement can be generated from source text without structural guesswork.

Use suggest when​

• there is a meaningful chance of behavior change,
• user intent cannot be derived from syntax alone,
• or code style constraints vary across teams.

This keeps automation helpful without becoming risky.

Why this matters in TypeScript-heavy codebases​

TypeScript projects frequently rely on utility types, narrowings, and overloaded APIs. Small rewrites can accidentally change constraints or type inference behavior.

A conservative strategy means developers still get guidance and one-click migrations, but only in places where the rule can prove safety.

Practical rollout advice​

If your team is adopting this plugin:

1. Start with a baseline preset.
2. Enable autofix in CI only after reviewing suggestion quality.
3. Move stricter rules from suggestion-first to fix-first once confidence is high.

That progression gives teams predictable upgrades instead of disruptive churn.

The core motivation​

Most teams using TypeScript still carry legacy utility patterns that were reasonable at the time but are now harder to maintain than modern type-fest and ts-extras alternatives.

This plugin tries to close that gap by doing three things:

1. Detect outdated or unsafe patterns reliably.
2. Offer clear, actionable diagnostics instead of vague “bad style” warnings.
3. Autofix only when semantics are preserved.

Design constraints we intentionally accepted​

1) Performance over cleverness​

Rules run on every save. If a rule needs expensive type-checker calls in hot paths, it can become a drag on the whole developer workflow.

So we bias toward:

• syntax-first detection where possible,
• narrow AST selectors,
• type-aware fallbacks only where they materially improve correctness.

2) Correctness over aggressive autofixes​

A fast autofix that changes runtime behavior is a bug.

When we can guarantee safety, we emit fix. When a transformation is likely correct but not universally safe, we emit suggest.

This keeps trust high: developers know auto-applied changes are meant to be safe-by-default.

3) Documentation as part of the rule contract​

A rule without clear documentation creates churn.

Every rule is expected to explain:

• the specific anti-pattern it flags,
• the safer alternative,
• concrete incorrect/correct examples,
• whether type information is required.

Long-term direction​

The roadmap is to keep tightening alignment with modern TypeScript utility ecosystems while preserving practical adoption paths:

• low-friction presets for gradual rollout,
• stricter presets for mature codebases,
• focused migration guidance in docs and examples.

If a rule cannot be explained explicitly, implemented performantly, and fixed safely, it does not belong in this plugin.