https://nick2bad4u.github.io/eslint-plugin-typedoc/blog/ eslint-plugin-typedoc Blog 2026-03-11T00:00:00.000Z https://github.com/jpmonette/feed Updates, architecture notes, and practical guidance for eslint-plugin-typedoc users. https://nick2bad4u.github.io/eslint-plugin-typedoc/img/favicon.ico © 2026 Nick2bad4u <![CDATA[Keeping Rule Docs and Presets in Sync]]> https://nick2bad4u.github.io/eslint-plugin-typedoc/blog/keeping-rule-docs-and-presets-in-sync/ 2026-03-11T00:00:00.000Z Documentation drift is one of the easiest ways to lose trust in a lint plugin.

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.

]]> Nick2bad4u https://github.com/Nick2bad4u <![CDATA[Type-Aware Linting Without Surprises]]> https://nick2bad4u.github.io/eslint-plugin-typedoc/blog/type-aware-linting-without-surprises/ 2026-03-11T00:00:00.000Z Type-aware rules are powerful, but they become noisy fast when parser-service assumptions are unclear.

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.

]]> Nick2bad4u https://github.com/Nick2bad4u <![CDATA[Designing Safe Autofixes for eslint-plugin-typefest]]> https://nick2bad4u.github.io/eslint-plugin-typedoc/blog/designing-safe-autofixes-for-eslint-plugin-typefest/ 2026-02-28T00:00:00.000Z Autofix is one of the biggest quality-of-life features in ESLint, but it is also one of the fastest ways to damage trust if a rule gets it wrong.

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.

]]> Nick2bad4u https://github.com/Nick2bad4u