Skip to content

Unify Oxlint gate and review sensor policy #395

Description

@taras

Problem

The repository has two independently maintained Oxlint policies:

  • the root .oxlintrc.json, used as the repository lint gate; and
  • .reviews/.oxlintrc.json, used as the automated review sensor.

They have drifted. The root configuration disables the broad pedantic and style categories, while the review sensor enables both at "warn". PR #375 consequently reported 424 diagnostics, including many rules that conflict with established project and function-component conventions.

The specifications also contradict each other: the Oxlint sensor configuration says pedantic and style are off, while a later section says they are enabled.

Evidence: #375 (comment)

Contract

The policy hierarchy is:

  1. AGENTS.md and merged specifications define project conventions.
  2. The root Oxlint configuration enforces the machine-checkable subset.
  3. The review sensor provides advisory signals and must not silently introduce contradictory project rules.
  4. Generic category expansion is not a policy decision. A new rule is adopted explicitly, with rationale and coverage.

The review sensor must not recommend changes that violate established contracts, including:

  • PascalCase filenames required by Markdown function-component resolution;
  • named props and returns exports required by function components;
  • named exports used by published package APIs;
  • Effection function* generators and operation shape.

Rules such as filename-case, no-named-export, group-exports, exports-last, func-style, and require-yield must therefore not appear as review findings.

Potentially useful rules such as no-unsafe-assignment, no-unsafe-return, no-unsafe-member-access, preserve-caught-error, no-duplicate-imports, and complexity limits require individual adoption decisions. They must not arrive accidentally through an entire category.

Proposed implementation

  • Introduce one shared native Oxlint configuration containing:
    • shared plugins;
    • correctness and suspicious category settings;
    • pedantic: "off" and style: "off";
    • the explicit review-sensor rule catalog;
    • common test overrides.
  • Make the root gate and review sensor extend the shared configuration.
  • Keep project-specific blocking JavaScript-plugin rules in the root configuration.
  • Keep the sensor advisory and limited to explicitly selected signals.
  • Keep the sensor rule catalog, Doctor capability catalog, diagnostic categorization, and specification synchronized.
  • Remove contradictory and historical configuration descriptions from the specifications.

Oxlint supports JSON configuration inheritance through extends and exposes --print-config for inspecting the effective policy.

Drift prevention

Add a conformance test using representative production, test, and .reviews/components/*.ts files. It must prove that:

  • the review profile does not enable a built-in rule disabled by the project profile;
  • every explicitly supported sensor rule is enabled;
  • every sensor rule is represented in the Doctor capability and diagnostic-category catalogs;
  • known component-protocol conflicts remain disabled;
  • project-specific blocking rules remain enabled in the root gate;
  • both configurations inherit the canonical shared policy.

Use oxlint --print-config so the test verifies effective merged configuration rather than only comparing JSON source text.

Acceptance criteria

  • Root and review Oxlint configurations inherit one canonical shared policy.
  • Broad pedantic and style categories are disabled.
  • The review sensor enables only project-compatible, explicitly selected advisory rules.
  • Rules that conflict with function-component or Effection contracts do not appear in review output.
  • A conformance test fails when the root and review policies drift.
  • Sensor configuration, Doctor rule availability, diagnostic categorization, and specifications agree.
  • The contradictory specification language is removed.
  • A representative review produces focused diagnostics rather than generic style noise.
  • Deno, Node, and Bun run the portable policy tests.
  • deno task lint, deno task check, deno task test, and deno task check:jsr pass.

Out of scope

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions