millionco__react-doctor/TODOS.md at v0.4.2

mirror of https://github.com/millionco/react-doctor.git synced 2026-09-14 20:00:24 +08:00

Files

T

Aiden Bai dafe231e24 feat: add category-level rule controls (severity overrides + family tags) (#285 )

* feat(core): add severityOverrides config with per-rule / per-category / per-tag channels

Introduces a unified severity-override resolver that lets users
promote, demote, or fully disable rules across every diagnostic
surface (CLI, PR comment, score, --fail-on) without editing source.

- New `severityOverrides` field on `ReactDoctorConfig` with `rules`,
`categories`, and `tags` channels. Values: `error` | `warn` | `off`.
Precedence: `rules` > `categories` > `tags`; within the tag channel
the most permissive override wins (`off` > `warn` > `error`).
- `resolveRuleSeverityOverride` is a pure resolver shared between the
oxlint config builder (next commit) and the post-lint diagnostic
filter, so external-plugin rules (`react/*`, `jsx-a11y/*`) honor
`off` too even though their severities live outside our control.
- `applySeverityOverrides` drops `off` diagnostics, re-stamps
`warn` / `error` severities, and short-circuits to the input
array when no overrides are configured so the common path stays
allocation-free.
- `validateConfigTypes` coerces stringy mistakes and warns on
invalid severities / channel shapes; `mergeAndFilterDiagnostics`
runs the override before the existing ignore pipeline.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* feat(core): apply severityOverrides at oxlint config time

Threads `severityOverrides` from the user config through `runOxlint`
into `createOxlintConfig`, where it short-circuits `off` rules
before registration (so they never run, never emit, and never reach
any surface) and re-stamps the registered severity for `warn` /
`error` overrides. The retry-without-extends fallback honors the
same overrides so a crashed adopt-extends path doesn't quietly
reactivate a silenced rule family.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* feat(plugin): bucket-derived auto-tags and migration-hint family

Cross-cutting controls (`severityOverrides.tags`,
`surfaces.*.excludeTags`, `config.ignore.tags`) need a way to target
whole rule families without each rule file repeating the same tag.
The codegen now merges bucket-derived tags into every entry:

- `react-native/` bucket rules get `"react-native"`
- `server/` bucket rules get `"server-action"`

Tags authored on the rule (e.g. `test-noise` on
`no-react19-deprecated-apis`) are preserved and deduped at registry
build time. The four migration-prompt rules now carry an explicit
`migration-hint` tag too:

- `no-react19-deprecated-apis`
- `no-react-dom-deprecated-apis`
- `no-legacy-class-lifecycles`
- `no-legacy-context-api`

`formatAutoTagsLine` mirrors prettier's wrap-at-100-cols decision at
codegen time so the regen-equals-formatted contract enforced by
`gen:check` stays stable.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* test: cover severityOverrides resolution, post-lint apply, and tag registration

- `resolve-rule-severity-override.test.ts` checks precedence,
empty-overrides short-circuit, the multi-tag most-permissive-wins
rule, and category / tag fallback.
- `apply-severity-overrides.test.ts` verifies `off` drops both
react-doctor and external-plugin diagnostics; `warn` / `error`
re-stamps the severity; and the no-overrides path returns the
input array by identity.
- `rule-tag-registration.test.ts` guards the bucket-derived auto-tags
(`react-native` on every RN rule, `server-action` on every server
rule) and the explicit `migration-hint` tags on the four migration
rules, plus that authored tags survive the bucket merge.
- `validate-config-types.test.ts` extends the existing surfaces
coverage with severityOverrides happy / invalid / partial-channel
paths.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* docs: document severityOverrides and the five rule-family tags

Adds a README section right after the surface controls explaining
when to use `severityOverrides` (single value applied across every
channel) vs `surfaces` (visibility-only, per channel), with a
copy-pasteable JSON example covering the five tag families called
out in the original TODO — `design`, `test-noise`, `react-native`,
`server-action`, `migration-hint`. Updates the TODOs entry to
landed status and adds a minor-bump changeset.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* refactor: tighten severity-override surface for elegance

Net -58 lines while making each path read more directly:

- New `get-diagnostic-rule-identity.ts` projects a diagnostic onto
the three axes every rule-targeted control reasons about
(`ruleKey`, `category`, `tags`). `filter-for-surface` and
`apply-severity-overrides` both consume it instead of repeating
the plugin-aware tag lookup inline.
- `resolve-rule-severity-override` drops the two-level
`pickMostPermissive` / `collectTagOverride` helpers in favor of a
single linear scan with a small `isMorePermissive` predicate;
reads top-to-bottom in rule > category > tags precedence order.
- `apply-severity-overrides` factors a `restampSeverity` helper
driven by a `SEVERITY_FOR_OVERRIDE` map, keeping the main loop to
three lines of decision logic.
- `createOxlintConfig` collapses the override-then-fallback into one
`?? rule.severity` expression so the "\"off\" skips registration"
check is the only branch left.
- Codegen drops the manual prettier-width math entirely — the
shorter `[...new Set(...)]` form always fits under 100 cols, so
`gen:check` stays idempotent without the wrap-aware fork.
- `validate-config-types` extracts `applyFieldValidator`,
`isPlainObject`, and `formatType` so the four "if undefined skip;
validate; store or delete" blocks at the bottom collapse into one
expression each, and the three "must be plain object" guards stop
duplicating their type check.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* test: dogfood js-combine-iterations in rule-tag-registration test

React Review flagged two .filter().map() chains in the test file as
`js-combine-iterations` warnings (we eat our own dogfood). Replaces
both chains with a shared `collectRuleIdsMatching` helper that walks
`Object.entries(plugin.rules)` once and pushes ids into a single
result array — same behavior, single pass.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* fix(core): warn on unknown severityOverrides channel keys

Bugbot caught an asymmetry: `validateSurfacesField` iterates the
user-provided keys via `Object.entries` and warns on unknown surface
names, but `validateSeverityOverridesField` only iterated the
allowlist — so a typo like `"rule"` instead of `"rules"` or
`"category"` instead of `"categories"` silently dropped the
override with no signal to the user.

Switches the iteration to walk the user's keys (matching surfaces)
and emits `config field "severityOverrides.<key>" is not a known
channel (expected one of: rules, categories, tags); ignoring.` when
the key isn't recognized. Adds a regression test for the typo path.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* refactor: rename severityOverrides config to severity for ESLint/oxlint idiomacy

The wrapper key `severityOverrides` was the only non-idiomatic part of
the design — ESLint exposes severity under top-level `rules`, oxlint
exposes it under top-level `rules` + `categories`, and Biome under
`linter.rules`. None wrap it in a multi-word `*Overrides` namespace,
and our own project's existing wrapper namespaces (`ignore`,
`surfaces`) are single-word.

Renames:

- Config field `severityOverrides` → `severity`. The triple
`ignore` / `surfaces` / `severity` reads as a coherent set of
single-word namespaces parallel to the rest of the project.
- Type `SeverityOverrideControls` → `RuleSeverityControls`. The value
type stays `RuleSeverityOverride` so it doesn't collide with the
plugin's existing `RuleSeverity = "error" | "warn"` (the
registrable subset).
- File `apply-severity-overrides.ts` → `apply-severity-controls.ts`,
function `applySeverityOverrides` → `applySeverityControls`. Matches
the config field's noun form.
- Validation error messages updated from
`config field "severityOverrides.<x>"` to
`config field "severity.<x>"`.
- README, changeset, and TODOs.md updated to draw the explicit
parallel to ESLint's `rules: { ... }` and oxlint's
`rules: { ... } + categories: { ... }`, plus the extra `tags`
channel for behavioral families.

All 1158 tests pass.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* refactor: promote severity controls to top-level rules / categories / tags (ESLint shape)

The wrapper namespace was the last non-idiomatic piece. ESLint exposes
severity under top-level `rules` (its hallmark field name and shape).
oxlint exposes `rules` + `categories` at the top level. Promoting our
three channels to the config root gives users the exact field they
already know from ESLint, plus oxlint-shaped `categories` and a
`tags` extension with the same Record-of-severity shape.

Before:

{
"severity": {
"rules": { "react-doctor/no-array-index-as-key": "error" },
"categories": { "React Native": "warn" },
"tags": { "design": "off" }
}
}

After (matches ESLint's flat-config / .eslintrc shape exactly, plus
oxlint's `categories`):

{
"rules": { "react-doctor/no-array-index-as-key": "error" },
"categories": { "React Native": "warn" },
"tags": { "design": "off" }
}

Changes:

- `ReactDoctorConfig` drops `severity` and gains three top-level
fields `rules`, `categories`, `tags`. Each is a
`Record<string, RuleSeverityOverride>`.
- New `buildRuleSeverityControls(config)` adapter assembles the
internal `RuleSeverityControls` shape from the three top-level
fields so the resolver and the oxlint config builder don't need
to know about the public API shape.
- `applySeverityControls` and `runOxlint` switch to the adapter;
`resolveRuleSeverityOverride` is unchanged (still takes
`RuleSeverityControls` directly).
- Validation: drops the `severity` wrapper validator; adds a
shared `validateSeverityMap(fieldName, value)` invoked once per
top-level field. Error messages now read `config field "rules"` /
`config field "tags.design"` — matching what the user typed.
- Tests, README, changeset, and TODOs.md updated. README now opens
the section with "The exact ESLint / oxlint shape" so the parity
is the first thing a reader sees.

All 1161 tests pass (gained 3 from build-rule-severity-controls.test.ts).

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* ci: retrigger workflow after path filter miss

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* ci: nudge actions queue

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* chore: drop changeset for category-level rule controls

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* docs(readme): tighten severity-controls section

Previous version was 32 lines of intro + 5-bullet behavior reference
+ full tag/category enumeration. Cuts to one intro sentence, a
compact JSON example, and a single paragraph covering precedence and
where the value applies. The full tag/category list is implicit from
the example; the precedence and most-permissive-wins rule are now
one sentence each.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

* refactor: drop user-facing severity-by-tag (tags are internal metadata)

Per-tag severity at the top level exposed an internal grouping
concept that doesn't exist in ESLint or oxlint. Tags are
behavioral labels rule authors invent; surfacing them as a
first-class user config field made `react-doctor.config.json`
depend on internal labeling decisions.

Drops the top-level `tags` field. The severity surface is now
strictly ESLint + oxlint shaped:

- `rules` — ESLint's exact field
- `categories` — oxlint's exact field

Recovers the dropped functionality via existing fields:

- whole-family suppression: `ignore.tags: ["design", ...]`
(existing field, unchanged)
- per-channel visibility: `surfaces.*.{include,exclude}Tags`
(existing field, unchanged)
- per-rule severity: list rules explicitly in `rules`

Code falls out:

- `RuleSeverityControls.tags` removed
- `resolveRuleSeverityOverride` collapses to a two-line lookup
(`rules` -> `categories`); drops the most-permissive-wins
machinery and the `SEVERITY_RANK` map entirely
- `buildRuleSeverityControls` drops the tag merge
- `validate-config-types` SEVERITY_FIELD_NAMES = ["rules", "categories"]
- `applySeverityControls` destructures only the two channels it
needs from `getDiagnosticRuleIdentity` (which keeps returning
tags for surface filters / ignore.tags consumers)

Tests, README, and TODOs updated to reflect the smaller surface.
1169 tests still passing.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

2026-05-16 22:55:28 -07:00

16 KiB Raw Permalink Blame History

React Doctor / React Review TODOs

P0 - Trust-Breaking False Positives

[ ] Separate PR regressions from baseline health in React Review

[ ] Fix ReDoS risk in glob pattern compilation

P1 - CI, Docs, Config, Product Semantics

[ ] Reconcile offline scoring behavior

[ ] Stop recommending millionco/react-doctor@main

[ ] Expose --annotations through action.yml

[x] Add category-level rule controls

[ ] Support mature-codebase adoption workflows natively

[ ] Make test-noise suppression consistent

[ ] Improve suppression ergonomics

[ ] Finish Husky/lint-staged docs

[ ] Decide custom package.json path support

[ ] Keep React dependency detection robust in non-standard workspaces

[ ] Track large-codebase crash and resource failure modes

[ ] Clarify React Doctor vs React Review

[ ] Fix hosted private-repo / repo-not-found failures

[ ] Add non-GitHub / self-hosted GitLab integration path

[ ] Improve install flow and post-install empty states

[ ] Keep local and hosted privacy/data behavior explicit

[ ] Improve score-change communication

[ ] Add clear release/version mapping

[ ] Verify local report/export support and docs

P2 - Platform and Product Expansion

[ ] Decide dangerous CI/security config detection

[ ] Reframe positioning away from generic "React review bot"

[ ] Improve hosted React Review PR comment and dashboard polish

[ ] Add Preact support position

[ ] Clarify React Native coverage

[ ] Decide HIR precision work priority

[ ] Decide TUI priority

[ ] Decide broader ecosystem "Doctor" variants

Open PR Triage

Open Issue Triage

Historical Regression Ledger

Monorepo and discovery

GitHub Action and CI

CLI and agent workflow

Rule quality

Product and docs

Shipped enhancements

Immediate Order

16 KiB

Raw Permalink Blame History

[ ] Stop recommending `millionco/react-doctor@main`

[ ] Expose `--annotations` through `action.yml`

[ ] Decide custom `package.json` path support