# Strict Oxlint and Oxfmt Engineering Standard

**Version 5.3 · 19 November 2026**

- **Canonical agent-readable Markdown:** `https://fitchhub.com/standards/oxlint-oxfmt.md`
- **Pinned release Markdown:** `https://fitchhub.com/standards/oxlint-oxfmt/v5.3.md`

This standard defines linting, formatting, typechecking, and verification requirements for JavaScript and TypeScript repositories. It is written primarily for coding agents implementing or updating quality enforcement in a target repository, and for engineers and reviewers governing that work.

**Apply strict checks by default. Relax an applicable rule only when the best reasonable compliant implementation demonstrably harms a supported contract or introduces disproportionate complexity without a meaningful safety or correctness benefit.**

**Treat this standard as a baseline floor, not a ceiling. Do not weaken stricter rules, tighter thresholds, or extra checks that are already working well and delivering real value in the target repository; keep them and raise them to the user driving the work so they can be considered for upstream adoption in this standard.**

**If any mandated rule, option, threshold, or requirement in this standard causes regressions in the target repository, raise those concerns directly to the user driving the work with concrete evidence before weakening enforcement or introducing workarounds.**

The objective is software that is correct, maintainable, readable, consistent, appropriately reusable, and efficient. Automated checks support that objective; passing them is necessary for acceptance but does not by itself establish engineering quality.

This document is self-contained. Each adopting repository supplies its own configurations, source mappings, verification commands, and local exception records. Previous releases and external conversations are not required to interpret or apply it.

Adoption covers both first-time implementations and upgrades from earlier versions of this standard, including correcting existing nonconformance and harmful compliance patterns within the declared scope.

## Contents

1. [Quality, current-date grounding, and authority](#1-quality-current-date-grounding-and-authority)
2. [Quality exceptions](#2-quality-exceptions)
3. [Code design and behavioral contracts](#3-code-design-and-behavioral-contracts)
4. [Source coverage and compiler requirements](#4-source-coverage-and-compiler-requirements)
5. [Toolchain and lint requirements](#5-toolchain-and-lint-requirements)
6. [Frameworks and test runners](#6-frameworks-and-test-runners)
7. [Formatting and generated artifacts](#7-formatting-and-generated-artifacts)
8. [Verification and enforcement integrity](#8-verification-and-enforcement-integrity)
9. [Adoption, upgrades, and escalation](#9-adoption-upgrades-and-escalation)
10. [Acceptance and maintenance](#10-acceptance-and-maintenance)

- [Appendix A: Base Oxlint configuration](#appendix-a-base-oxlint-configuration)
- [Appendix B: Repository records](#appendix-b-repository-records)
- [References](#references)

## 1. Quality, current-date grounding, and authority

### 1.1 Quality criteria

Evaluate resulting code against all six criteria:

| Criterion       | Required outcome                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| Correctness     | Supported behavior, public contracts, security boundaries, and failure semantics remain sound.         |
| Maintainability | Responsibilities and state ownership are clear; changes have understandable, bounded effects.          |
| Readability     | Names, control flow, and interfaces support local reasoning without unnecessary indirection.           |
| Consistency     | Equivalent operations follow established project conventions and use the same authoritative contracts. |
| Reuse           | Shared domain knowledge, types, schemas, validation, and utilities have appropriate common ownership.  |
| Efficiency      | Resource use, execution order, concurrency, and runtime cost fit the actual workload and contracts.    |

A reduction in line count or diagnostic count is not by itself evidence of improvement. A gain in one criterion cannot justify incorrect behavior or unsafe data flow.

### 1.2 Current-date, native-first engineering

Agents and engineers often operate on incomplete or outdated assumptions about what a language, runtime, compiler, linter, formatter, or package actually provides. Treat memory as a lead, never as proof:

- **Use current releases.** Keep languages, runtimes, compilers, linters, formatters, and project dependencies up to date through the repository's normal update workflow rather than anchoring to legacy patterns.
- **Inspect installed code and current documentation.** Before designing a workaround, custom wrapper, rule override, exception, or test, inspect the actual installed package source, type declarations (`node_modules/**/*.d.ts`), tool schemas (`configuration_schema.json`), CLI help, and current-date official documentation for the exact versions in use.
- **Lean on native capabilities.** Prefer built-in language syntax, runtime APIs, compiler guarantees, native linter rules/options, formatter capabilities, and first-class package primitives over custom shims, hand-rolled wrappers, or bespoke enforcement code.
- **Verify against the real toolchain.** Check rule behavior, declaration origins, and config composition directly against the installed binaries instead of inferring behavior from older tools such as ESLint or Prettier.

### 1.3 Requirements, discretion, and escalation

**Must** identifies a requirement. **Should** identifies a recommendation whose applicability depends on the stated context. **May** identifies a permitted choice. Configuration blocks and limits are normative where their stated profile applies.

Implementers must apply the baseline and defined profiles. An **implementation mapping** selects actual repository files, runtimes, framework settings, test-runner profiles, or commands without reducing required enforcement. Applying a defined profile (such as the test profile or `node:test` runner mapping) to genuine matching files is a mapping, not an exception.

A **relaxation** disables an applicable rule, weakens an option, raises a limit, broadens an allowance, or reduces the source operations a required check examines. It remains a relaxation whether expressed through an override, directive, nested config, CLI flag, plugin list, wrapper, or custom rule. Every repository-specific relaxation beyond the defined profiles requires a quality exception under Section 2.

An instruction to adopt or update this standard authorizes implementation work and evidence-backed Section 2 quality exceptions. Existing review requirements, branch protections, ownership constraints, and repository permissions remain in force. Adoption alone does not authorize merging, deploying, altering product contracts, or overwriting unrelated work.

**Mandatory regression escalation:** If you determine that a mandated rule, option, threshold, or requirement in this standard is actually causing regressions in the target repository — breaking supported behavior, degrading runtime or type safety, conflicting with current upstream tool or runtime contracts, or forcing harmful workarounds — you must raise those concerns directly to the user driving the work with concrete evidence (see Section 9.4).

**Baseline floor, not a ceiling:** This standard defines minimum required quality enforcement, not a strictness cap. If the target repository already enforces stricter lint rules, tighter structural thresholds, additional compiler checks, or stronger domain guardrails that work cleanly without inducing over-engineered workarounds, keep them intact and surface them to the user driving the work for potential upstream adoption in this standard (see Section 9.5).

Additional architectural rules must come from repository instructions or a demonstrated engineering need. This standard does not impose universal bans on barrels, mutable resource types, single-consumer helpers, or checked JavaScript.

## 2. Quality exceptions

### 2.1 Eligibility

Use a straightforward compliant implementation whenever one is reasonably available. A quality exception is permitted only when a concrete comparison demonstrates that the best reasonable compliant implementation would:

1. Harm supported functionality, sound typing, correctness, or safety, including an established ownership, lifecycle, accessibility, compatibility, or performance contract; or
2. Introduce disproportionate verbosity, indirection, or complexity without a meaningful safety or correctness benefit.

The resulting implementation must still satisfy Section 1.1 and every boundary in Section 2.5. Exceptions may address lint rules, structural thresholds, or formatting requirements. A checker limitation must be demonstrated on the installed toolchain; calling a finding a false positive does not establish eligibility.

Modest explicit typing, boundary validation, or meaningful decomposition is normal compliance work. Fewer lines, stylistic preference, migration effort, deadlines, historical practice, and the desire for green checks are not grounds for an exception. Compare realistic alternatives; do not fabricate awkward rewrites to justify an exemption.

### 2.2 Decision process

Each exception must establish:

1. **The finding.** Identify the installed tool versions, rule and options, affected operation, and reproducible diagnostic. Inspect project membership, `.d.ts` declarations, and effective configuration (`oxlint --print-config`) before attributing the problem to the rule.
2. **The contract.** Explain the behavior, type relationship, ownership, or design responsibility that must remain correct. Cite the relevant code, consumers, or API contract.
3. **The comparison.** Present the best reasonable compliant alternative and demonstrate one of the two grounds in Section 2.1. For complexity claims, show the concrete code and explain why its extra machinery adds no meaningful safety or correctness benefit.
4. **The adjustment.** Select the narrowest scope and least reduction in checking that resolves the demonstrated problem: a native rule option, declaration-qualified allowance, operation-bound directive, or file-scoped override. Preserve all unaffected protections. A global change requires evidence of a mismatch across the rule's entire relevant scope that a narrower adjustment cannot address.
5. **The remaining protection.** Verify that the intended code passes and state clearly what detection is lost and what other checks protect the affected contract.
6. **The review record.** Record the decision in Appendix B and include the code, configuration, and verification in the same reviewable change.

If an exception cannot resolve a mandated requirement cleanly because the requirement itself induces regressions across the repository, escalate to the user under Section 9.4 instead of normalizing a workaround.

### 2.3 Structural and unsafe-type evidence

For a structural exception, compare the proposed implementation with the best compliant alternative, including any helpers or signature changes it introduces. Record the metric before and after and explain the concrete effect on responsibilities, contracts, or readability.

For `no-explicit-any` or any `no-unsafe-*` exception, brevity or stylistic preference is never sufficient. Trace the exact value and type flow, explain why the operation is sound despite the diagnostic, show how untrusted data is validated or constrained before trusted use, and record every safety assumption that remains unverified by the type system.

### 2.4 Scope and directives

Use native configuration when it expresses the intended scope cleanly. When a single site is more precise, use a next-line directive for one rule with a stable exception identifier and concise reason:

```ts
// oxlint-disable-next-line unicorn/prefer-add-event-listener -- QX-001: SDK exposes only an onMessage callback property.
```

Blanket, file-wide, and range lint disables, ESLint disable directives (`eslint-disable*`), and undocumented inline disables are prohibited. If one operation legitimately requires more than one exception, identify each rule explicitly and verify attachment against the installed Oxlint version.

Keep site directives tied to specific authorized operations rather than vague prose. Remove unused directives immediately (enforced by `reportUnusedDisableDirectives: "error"`) and prune stale exception records when dependencies, rules, or contracts change. No arbitrary exception quota or expiration date is required.

### 2.5 Non-negotiable boundaries

An exception must not:

- Conceal diagnostics through output filtering, finding-count budgets, skipped checks, or swallowed exit statuses.
- Remove maintained source from required lint, compiler, or formatter coverage.
- Disable compiler strictness, checked-JavaScript coverage, or required declaration checking.
- Replace sound types or validation with unjustified `any`, unsound predicates, misleading generics, or unsafe assertion chains.
- Hide the same operation behind aliases, reflection, wrappers, proxies, or removed annotations while claiming the original check still protects it.
- Reclassify production code as tests, static data, generated output, or fixtures to gain an exemption.
- Weaken test assertions or silently alter supported behavior.

## 3. Code design and behavioral contracts

### 3.1 Shared contracts and reuse

Before adding a type, schema, validator, decoder, or utility, locate the repository's existing authoritative definition and consumers. Reuse it when semantic contract, ownership, dependency direction, and distribution requirements match. Equivalent domain concepts must not gain competing definitions solely to clear local lint or compiler errors.

When a runtime schema owns a contract, derive its static types using the schema library's native facilities where appropriate. When an external API or independently owned type is authoritative, use explicit adapters or checked mappings rather than maintaining parallel declarations that drift.

Consolidate shared knowledge at the appropriate boundary without merging genuinely distinct domain models, transport formats, persistence records, or independently versioned APIs. Respect package layering and standalone distribution boundaries.

### 3.2 Types, validation, and ownership

Use accurate types, `unknown` at untrusted boundaries, explicit validation, and type narrowing. Validate external data where it enters the trusted model and avoid repeating redundant guards for invariants already established at that boundary.

Carry established contracts through accurate shared types instead of propagating `unknown` into trusted code and reconstructing ordinary property access or calls via reflection helpers.

Apply these idiomatic native boundary patterns rather than suppressions:

- **JSON parsing:** `const value: unknown = JSON.parse(text);` preserves native `SyntaxError` behavior and satisfies `typescript/no-unsafe-assignment` cleanly before validation. Use schema decoders when their error and fallback contract matches.
- **Dynamic `import(specifier)`:** TypeScript types non-literal dynamic `import(url)` as `Promise<any>`. Annotate the binding explicitly as `const mod: unknown = await import(specifier);` and narrow or validate `mod` before accessing exports. This passes `typescript/no-unsafe-assignment` cleanly on Oxlint with `tsrs` with zero directives.
- **Test doubles:** Build typed fakes and stubs using accurate interfaces, `satisfies`, or focused typed test helpers. Do not weaken production `no-unsafe-*` rules for test convenience. When mocking a genuinely untyped external boundary in tests, keep any required type boundary minimal and local to the test helper.
- **Parameter mutation (`no-param-reassign`):** Keep `{ "props": true }` by default. For files that legitimately mutate named parameters in place — such as Immer `draft` callbacks, reducer accumulators (`acc`), HTTP/RPC middleware (`ctx`, `req`, `res`), DOM builders, or SDK hooks whose contract observes mutation on a shared options object — use a file-scoped `ignorePropertyModificationsFor` override targeting the exact parameter names (keeping `props: true` everywhere else) rather than disabling `no-param-reassign` globally or adding lint-only copies or wrappers.

Use `readonly` views for borrowed data when they accurately express the contract, while preserving accurate mutable ownership and lifecycle types where mutation belongs.

### 3.3 Behavioral preservation and banned compliance shims

Typing, formatting, lint compliance, and decomposition must preserve supported behavior. Treat intentional behavioral improvements as separate behavioral work with appropriate tests.

| Area            | Contracts to preserve or explicitly change                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Errors          | Identity, subclass, code, `cause`, redaction, messages, thrown vs returned failures, and operator-visible output                |
| Data            | Accepted inputs, defaults, validation location, serialization, absent vs explicit `undefined`, ordering, and reference identity |
| Objects         | Object vs collection APIs, property access, getters, prototypes, and consumer expectations                                      |
| Async execution | Ordering, concurrency, registration and hook timing, cancellation, retries, cleanup, and rejection ownership                    |
| Resources       | Public signatures, receiver identity, lifecycle ownership, framework-required exports, and generated bindings                   |
| Distribution    | Package entrypoints, standalone execution, emitted artifacts, and deployment contracts                                          |

**Harmful compliance shims are prohibited.** Never distort runtime behavior or add artificial machinery solely to satisfy a lint or compiler diagnostic. Specifically, do not introduce:

- **Synthetic runtime guards on typed parameters** (such as throwing a fabricated `TypeError` on values already constrained by the TypeScript signature) when the contract does not call for runtime validation.
- **Artificial async yields** (such as `await Promise.resolve()` or dummy microtasks) added solely to satisfy async rules.
- **Reflection, descriptor, or double-cast dodges** (`Reflect.get`, `Object.getOwnPropertyDescriptor`, `as unknown as`, proxy indirection, or unused aliases) added to hide an operation from type or mutation rules.
- **Lint-only forwarding wrappers, dummy state, no-op assignments, or empty error handlers** whose only purpose is clearing a finding.
- **Custom shims reimplementing native language, runtime, or dependency features** that already exist in the installed toolchain.

Own asynchronous work through the appropriate `await`, `return`, or lifecycle/error handler. Preserve required sequential loops and resource limits. Use concise explanatory comments for intentional no-ops instead of dummy state or fake returns.

If satisfying a mandated rule appears to require any of the shims above or risks regressing supported behavior, inspect the installed API and rule documentation first; if a conflict remains, use a narrow Section 2 exception or escalate to the user under Section 9.4.

### 3.4 Decomposition

Extract meaningful responsibilities and clear interfaces. Keep control flow and assertions easy to follow locally. Evaluate cohesion and clarity, not raw file or helper count.

Avoid numbered-stage functions (`step1`, `step2`), compressed statements, dummy closures, or moving production logic into exempt profiles to beat a threshold. Use options objects when they express a coherent API, not as a mechanical workaround for every multi-parameter signature. Public APIs, constructors, and SDK callbacks retain their supported contracts.

### 3.5 Practices to correct

Review existing code as well as new changes within the declared adoption scope. Correct the following patterns wherever found; prior passing checks do not justify keeping them:

| Practice                                                                                                                                                  | Required correction                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Duplicate types, schemas, validators, or guards restating an established contract                                                                         | Reuse the authoritative contract at the right boundary while preserving real ownership and distribution boundaries.    |
| Harmful compliance shims (synthetic `TypeError`s, fake `await Promise.resolve()`, reflection/cast dodges, lint-only wrappers/copies/aliases)              | Remove the shim and express the actual API and ownership directly using native idioms or a narrow Section 2 exception. |
| Misleading generics, unjustified casts or predicates, or annotation removal evading safety checks                                                         | Restore accurate types and checked value flow; document a narrow exception only if Section 2 is met.                   |
| Fragmentation or helper extraction done solely to satisfy a metric that does not apply                                                                    | Restore cohesive responsibilities and readable scenarios while keeping genuinely useful abstractions.                  |
| Accidental changes to errors, accepted inputs, serialization, scheduling, cleanup, or assertions during compliance edits                                  | Restore the supported contract, or handle the change as explicitly authorized and verified behavioral work.            |
| Obsolete stock-rule proof tests, legacy `oxlint-tsgolint` plumbing, finding-count baselines, or hand-rolled policy engines duplicating native tool checks | Remove obsolete scaffolding and rely on the native published toolchain and focused repo-owned checks.                  |

Verify consumers and responsibilities before deleting existing helpers or safeguards. Retain independently necessary launcher, resource, compatibility, and custom domain checks.

## 4. Source coverage and compiler requirements

### 4.1 Source profiles

Every maintained handwritten JavaScript and TypeScript file — implementation, tests, scripts, tooling, and executable templates — receives its applicable checks across `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts` where used.

Classify files by actual contents and consumers:

| Profile                                                      | Required treatment                                                                                                        |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Production, libraries, adapters, build/admin/quality tooling | Applicable lint, compiler, and formatter checks; production structural limits                                             |
| Tests and exclusively test-only support                      | Full applicable safety checks, assertion checks, and test structural limits                                               |
| Handwritten declarations and augmentations                   | Applicable lint, real declaration checking, and relevant public-consumer checks; no implementation-size metrics           |
| Static literal data                                          | Parsing, formatting, applicable typing/schema checks; no implementation-size metrics                                      |
| Dedicated negative type tests                                | Compiler-verified expected errors and passing counterparts; test structural limits                                        |
| Generated or vendored output                                 | Identifiable generator or upstream source, freshness/provenance check, and build/compatibility verification as applicable |

Helpers imported by both production and tests are production. A data module containing executable factories, calls, or orchestration is implementation. Maintained generators and executable templates carry full implementation requirements.

Verify that every maintained file is covered by the actual acceptance commands — not merely matched by an unused `tsconfig` or ignored by a stale ignore pattern. Missing ownership is a coverage bug, not a reason to add an exemption.

### 4.2 Compiler settings

Apply these options effectively to every maintained implementation project, including tests and scripts, while preserving appropriate runtime targets, module resolution, JSX mode, libraries, references, and asset handling:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedSideEffectImports": true,
    "forceConsistentCasingInFileNames": true,
    "noCheck": false
  }
}
```

Projects containing maintained JavaScript also require:

```json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  }
}
```

Every declared maintained project must actually execute through the canonical compiler or framework checker in acceptance. Individual strict-family options must not be disabled. `@ts-check` on selected files does not replace project-wide `checkJs: true`. Ordinary implementation must not use `@ts-ignore`, `@ts-nocheck`, or `@ts-expect-error` to hide errors.

Handwritten declarations and augmentations must receive real checking with `skipLibCheck: false` (either directly or through a dedicated declarations `tsconfig` covering the handwritten declarations and their real dependency closure, without permissive stubs).

Dedicated negative type tests (`*.test-d.ts`) may use `@ts-expect-error` with a description of at least ten characters explaining the expected contract failure; the compiler must reject unused `@ts-expect-error` directives.

### 4.3 JavaScript and TypeScript

Both checked JavaScript and TypeScript are supported. Choose the form that produces the clearest maintainable implementation within the repository's runtime and distribution constraints. Native runtime type stripping (for example, Node running `.ts` directly) executes code without typechecking; always keep the full compiler gate active. Do not switch languages or abuse JSDoc inference gaps to bypass safety checks.

## 5. Toolchain and lint requirements

### 5.1 Published tools and `tsrs` type-aware backend

Use the latest published releases of **`oxlint`**, **`tsrs`**, **`oxfmt`**, and any additional quality packages required by the repository. Resolve current releases when adopting or upgrading; this standard does not pin stale version numbers or impose an artificial waiting period.

**Use `tsrs` as Oxlint's type-aware linting backend.** Do not install or retain `oxlint-tsgolint`. When `tsrs` is installed as a devDependency alongside `oxlint`, Oxlint automatically detects and uses `tsrs` for `--type-aware` (and `--type-check` when enabled) without changing CLI flags or rule configuration:

```bash
pnpm add -D oxlint@latest tsrs@latest oxfmt@latest
```

Use the repository's own package manager (`npm`, `pnpm`, `yarn`, or `bun`) and commit updated manifests and lockfiles so local development, coding agents, CI, and editors share one resolved dependency tree.

Keep the canonical compiler or framework typechecker (`tsc --noEmit`, framework `typegen && tsc --noEmit`, etc.) as a required gate with Oxlint `options.typeCheck: false` by default, because `tsrs` tracks upstream TypeScript 7.1 while a repository's compiler or framework toolchain may pin a different TypeScript release. A repository may opt into `options.typeCheck: true` when it has verified full compatibility with its TypeScript version, tsconfig graph, and ignored-file coverage (note that `oxlint --type-check` only reports type errors in files Oxlint lints, so ignored files still require `tsc --noEmit` if maintained).

Lean on Oxlint's native diagnostic and inspection flags instead of building wrapper scripts:

- `oxlint --format=agent` — compact, single-line diagnostics designed for coding agents.
- `oxlint --debug=timings` — per-rule timing profile to diagnose slow lint runs.
- `oxlint --debug=files` — exact file list linted under current ignore patterns.
- `oxlint --print-config` — inspect effective resolved configuration and overrides.

Do not maintain a forked linter or hand-patched `node_modules` installation. If an upgrade introduces a real regression or breaks required checks, retain the last passing toolchain, inspect upstream release notes/issues, and escalate if a mandated requirement is affected.

### 5.2 Base configuration and composition

Use the complete [Appendix A configuration](#appendix-a-base-oxlint-configuration). Adapt `$schema` paths and profile globs to the repository layout without weakening enforcement. Add applicable framework and test-runner mappings from Section 6. Keep local Section 2 exceptions clearly distinguishable from the baseline.

Configuration format:

- **Default:** `.oxlintrc.json` (or `.oxlintrc.jsonc`), which requires no JS runtime evaluation and works with standalone binaries as well as the Node package.
- **TypeScript config:** `oxlint.config.ts` (or `oxlint.config.mts`) using `defineConfig` from `"oxlint"` is first-class and recommended when composing shared config packages via `extends` (`.oxlintrc.json` does not support package imports in `extends`). Note that TypeScript configs require Node 22.18+ / 24+ and the Node-based `oxlint` package, and JSON and TS config files cannot coexist in the same directory.

Active categories (`correctness`, `suspicious`, `perf`) enable rules beyond the explicit `rules` map; preserve their effective coverage. Applicable required rules run at `"error"`; `"off"` is limited to defined profiles or documented Section 2 exceptions. Keep `denyWarnings: true`, `typeAware: true`, `reportUnusedDisableDirectives: "error"`, and `respectEslintDisableDirectives: false`.

An explicit root `plugins` array replaces Oxlint's default plugin set. Preserve all six base entries (`eslint`, `typescript`, `unicorn`, `oxc`, `import`, `promise`) when adding framework plugins.

When using `extends`, nested configs, or overlapping `overrides`, verify effective composition using `oxlint --print-config` and actual lint runs across affected scopes rather than assuming array order alone. Note that passing `--config` / `-c` explicitly disables nested config lookup.

### 5.3 Structural profiles

| Metric                                                                   | Production | Tests and test-only support |
| ------------------------------------------------------------------------ | ---------: | --------------------------: |
| Modified cyclomatic complexity                                           |         10 |                          15 |
| Nesting depth                                                            |          3 |                           4 |
| Parameters (`max-params`)                                                |          5 |                           6 |
| Statements per function (`max-statements`)                               |         40 |                         Off |
| Effective lines per function, including IIFEs (`max-lines-per-function`) |         80 |                         Off |
| Effective lines per file (`max-lines`)                                   |        800 |                         Off |

Effective line limits exclude blank lines and comments (`skipBlankLines: true`, `skipComments: true`). Handwritten declarations and static literal data do not carry implementation-size limits; all other applicable checks remain active. Map test-only support files by actual role rather than relying solely on filename conventions.

### 5.4 Deliberate baseline choices

| Setting                                                                                      | Engineering rationale and remaining protection                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max-lines: 800` and `max-params: 5` (production)                                            | Accommodates cohesive modules and real 5-argument SDK/framework callbacks without forcing artificial splitting or parameter-bag wrappers, while still flagging genuinely bloated files and 6+ argument signatures that warrant options objects.                                                                 |
| `unicorn/no-useless-undefined` with `checkArguments: false`, `checkArrowFunctionBody: false` | Prevents breakage on required `T \| undefined` positional arguments (`fn(undefined)`) and typed `() => T \| undefined` callbacks, while retaining checks on useless `let x = undefined` initializers and `= undefined` parameter defaults. Oxlint already permits `return undefined` in return-typed functions. |
| `import/no-cycle` with `ignoreExternal: true`                                                | Enforces cycle-free imports across all repository-owned modules (including type imports and dynamic imports) without failing on third-party cycles inside `node_modules` that the repository does not own.                                                                                                      |
| `typescript/prefer-readonly-parameter-types: off`                                            | Accurate domain and resource types take priority over universal deep-readonly annotations. Direct parameter-mutation checks (`no-param-reassign`), readonly views, and `prefer-readonly` remain active.                                                                                                         |
| `typescript/strict-void-return: off`                                                         | Ordinary synchronous callbacks may legitimately ignore return values. Floating Promises and async-callback misuse remain checked.                                                                                                                                                                               |
| `typescript/no-base-to-string` with `checkUnknown: false`                                    | Unknown diagnostic values may legitimately be formatted; known base-object stringification and unsafe `any` propagation remain checked.                                                                                                                                                                         |
| `typescript/prefer-promise-reject-errors` with `allowThrowingUnknown: true`                  | Preserves existing error identity when forwarding caught `unknown` rejections while still rejecting `any`, known non-Errors, and empty `reject()`.                                                                                                                                                              |
| `no-await-in-loop: off`                                                                      | Sequential `await` in loops is frequently required for pagination, rate limits, ordered side effects, and resource lifetimes.                                                                                                                                                                                   |
| `no-control-regex: off`                                                                      | Control-character validation and sanitization are legitimate; use legible escape sequences and tests.                                                                                                                                                                                                           |
| Test statement/function/file-size limits off                                                 | Clear, linear test scenarios and thorough assertions should not be fragmented purely for line count; complexity, nesting, and parameter limits remain active.                                                                                                                                                   |

### 5.5 Common native-rule traps and idiomatic resolutions

Before writing a suppression or workaround for these recurring native rules, apply the idiomatic native pattern:

| Rule                                                                                                | Common trap                                                                                                                                                                                        | Idiomatic resolution                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preserve-caught-error`                                                                             | Wrapping a caught error in a new `Error` drops the original cause.                                                                                                                                 | Use ES2022 `new Error("...", { cause: error })`. Use a narrow Section 2 directive only when security/redaction contracts prohibit attaching raw underlying errors.                                      |
| `unicorn/prefer-add-event-listener`                                                                 | Assigning `target.onmessage = ...` or `window.onresize = ...`.                                                                                                                                     | Use `addEventListener` with `{ once: true }` or `{ signal }` (`AbortController`). Document a narrow Section 2 directive only when an SDK exposes an `on*` callback property without `addEventListener`. |
| `react-perf/jsx-no-new-object-as-prop` / `jsx-no-new-function-as-prop` / `jsx-no-new-array-as-prop` | When a React repo opts into `react-perf`, flagging inline `style={{ ... }}` or `onClick={() => ...}` on native HTML elements triggers pointless `useMemo`/`useCallback` churn.                     | Configure `["error", { "nativeAllowList": "all" }]` so intrinsic DOM elements stay ergonomic while custom/memoized React components remain checked.                                                     |
| `typescript/no-unnecessary-condition`                                                               | TypeScript control-flow narrowing assumes values do not mutate externally, flagging real checks on live getters (`AbortSignal.aborted`, reactive refs, or shared state mutated across an `await`). | Never delete a real post-`await` or live-getter guard to satisfy the rule. Read through a clean helper/method or record a targeted Section 2 exception citing the live mutation boundary.               |
| Upstream checker bugs (for example, narrowed-control-flow edge cases such as `oxc#20331`)           | A specific tool version emits a demonstrable false diagnostic on valid code.                                                                                                                       | Confirm the minimal repro on the installed `oxlint`/`tsrs` version, record a targeted Section 2 exception linking the upstream issue and revisit trigger, and remove it once fixed upstream.            |

## 6. Frameworks and test runners

Enable native framework plugins in their applicable scope while keeping base protections active. Inspect the actual installed plugin rules, runtime globals, and test-runner `.d.ts` declarations rather than assuming plugin defaults cover every helper or convention.

### 6.1 React and DOM accessibility

For React code, add `"react"` to `plugins` and enable these explicit rules alongside category coverage:

```json
{
  "react/rules-of-hooks": "error",
  "react/exhaustive-deps": "error",
  "react/jsx-key": "error",
  "react/jsx-no-duplicate-props": "error",
  "react/jsx-no-undef": "error"
}
```

For JSX targeting DOM interfaces, add `"jsx-a11y"`, keep category coverage, and explicitly enable:

```json
{
  "jsx-a11y/no-noninteractive-element-interactions": "error",
  "jsx-a11y/no-noninteractive-tabindex": "error",
  "jsx-a11y/prefer-tag-over-role": "error"
}
```

If the repository additionally opts into `"react-perf"`, configure `{ "nativeAllowList": "all" }` on its JSX allocation rules (see Section 5.5). Prefer native HTML controls where they fit the contract; interactive widget changes still require keyboard, focus, and accessible-name/role verification beyond static linting.

### 6.2 Vitest

Add `"vitest"` for Vitest test scopes and enable:

```json
{
  "vitest/no-focused-tests": "error",
  "vitest/valid-expect": [
    "error",
    {
      "minArgs": 1,
      "maxArgs": 2
    }
  ],
  "vitest/expect-expect": [
    "error",
    {
      "assertFunctionNames": ["expect", "expectTypeOf", "assert", "assertType"]
    }
  ],
  "vitest/no-conditional-expect": "error"
}
```

### 6.3 Jest

Add `"jest"` for Jest test scopes and enable:

```json
{
  "jest/no-focused-tests": "error",
  "jest/valid-expect": "error",
  "jest/valid-expect-in-promise": "error",
  "jest/expect-expect": [
    "error",
    {
      "assertFunctionNames": ["expect"]
    }
  ],
  "jest/no-conditional-expect": "error"
}
```

Add only verified repository assertion helpers to `assertFunctionNames`; never use broad wildcards that allow assertion-free tests to pass.

### 6.4 Node test runner (`node:test`)

In `@types/node/test.d.ts`:

- Lifecycle hooks (`before`, `after`, `beforeEach`, `afterEach`) return `void` and do not trigger `typescript/no-floating-promises`.
- Test and suite registrations (`test`, `it`, `describe`, `suite`) return `Promise<void>`. Because `@types/node` re-exports `describe` as an alias for `suite` (`export { suite as describe, test as it }`), declaration matching requires including `"suite"` alongside `"describe"` so aliased imports (such as `import { describe as nodeDescribe } from "node:test"`) also match.

Repositories using `node:test` may apply this standard test-profile runner mapping inside their test override (no separate Section 2 exception is required for this defined profile):

```json
{
  "typescript/no-floating-promises": [
    "error",
    {
      "checkThenables": true,
      "ignoreIIFE": false,
      "ignoreVoid": false,
      "allowForKnownSafeCalls": [
        {
          "from": "package",
          "package": "node:test",
          "name": ["test", "it", "describe", "suite"]
        }
      ],
      "allowForKnownSafePromises": []
    }
  ]
}
```

Keep these two rules in mind when using `node:test`:

1. **Always `await` (or return) nested subtests (`await t.test(...)`).** Because `TestContext.test` shares the name `"test"` inside `@types/node`, `allowForKnownSafeCalls` cannot distinguish unawaited `t.test(...)` from top-level `test(...)`, and Node's runner requires subtests inside an async test to be awaited.
2. **Intentional `await test(...)` is also permitted.** Repositories whose test files intentionally await top-level or suite registrations (without altering required hook timing) may omit `allowForKnownSafeCalls` entirely. Never mass-rewrite existing unawaited registrations into `await` if doing so changes module-evaluation or hook-ordering semantics.

Do not allowlist `test.only` / `describe.only` or disable `no-floating-promises` in tests; real floating promises inside test bodies must still fail lint.

## 7. Formatting and generated artifacts

### 7.1 Formatter ownership

Oxfmt owns formatting for supported maintained files. Preserve intentional, established repository style conventions; otherwise use this baseline `.oxfmtrc.json` (or equivalent `oxfmt.config.ts` using `defineConfig` from `"oxfmt"`):

```json
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "endOfLine": "lf",
  "insertFinalNewline": true,
  "sortImports": false,
  "sortPackageJson": false,
  "sortTailwindcss": false,
  "jsdoc": false
}
```

Oxfmt natively supports `sortImports`, `sortPackageJson`, `sortTailwindcss`, `overrides`, `associations`, and `.editorconfig`. Keep automatic sorting disabled unless the repository deliberately opts into it and verifies that import reordering does not alter side effects or runtime initialization order.

Assign each file type one clear formatting owner and avoid overlapping formatters. Generated, vendored, and byte-sensitive fixtures may designate an explicit generator or separate owner; handwritten maintained source remains formatted and checked by `oxfmt --check .`.

### 7.2 Generated freshness

Verify committed generated artifacts (such as Cloudflare Worker types, schema outputs, or generated content indexes) in acceptance using each generator's native non-writing check where available (for example, Wrangler `types --check` when supported), or by regenerating into an isolated temporary directory and diffing without mutating tracked files. A successful generator run alone does not prove committed output is current.

## 8. Verification and enforcement integrity

### 8.1 Focused gate integrity — no stock-rule proof tests

Verification must prove that **this repository's own configuration, coverage, acceptance commands, and custom code work** — not that upstream tools still implement their built-in rules.

**Do not write or retain tests whose only purpose is re-verifying stock Oxlint, Oxfmt, or TypeScript compiler rules** (such as synthetic fixtures asserting that Oxlint still reports `typescript/no-floating-promises`, `eqeqeq`, or `max-lines`, or that `tsc` still rejects a type error). Upstream projects own and test their native rules; duplicating those checks in adopting repositories adds maintenance drag without improving code quality.

Focus verification strictly on what the repository owns:

1. **Real acceptance gates pass on the actual repository tree:**
   - Formatting check (`oxfmt --check .`)
   - Full type-aware lint with zero warnings and zero unused disables (`oxlint --deny-warnings .`, backed by `tsrs`)
   - Every declared compiler, framework-typegen, and handwritten-declaration check (`tsc --noEmit`, etc.)
   - Generated-artifact freshness checks where applicable
   - Real unit, integration, and end-to-end tests covering repository behavior
2. **Effective configuration and source coverage are verified natively:**
   - Inspect effective config (`oxlint --print-config`) and matched files (`oxlint --debug=files`) during adoption and config changes to verify that all maintained source files, overrides, and plugins are actually active and that no maintained source is silently ignored.
   - Verify compiler project membership so every maintained TS and checked-JS file is actually compiled by the acceptance workflow.
   - Ensure aggregate scripts and CI workflows propagate failures accurately without diagnostic filtering, finding budgets, or `continue-on-error`.
3. **Custom repository-owned quality code is tested directly:**
   - Write and retain targeted tests **only** for quality tooling this repository itself owns — such as custom JS lint plugins, custom architecture/boundary scripts, config generators, or custom directive-inventory validators.

### 8.2 Evidence quality

Record exact revisions, installed tool versions, commands run, selection scope, and exit statuses when reporting verification. Report each check plainly as passed, failed, blocked, or unrun. Selected suites are not full suites; a script existing in `package.json` does not prove it ran; local verification does not prove hosted CI passed. Investigate flaky checks rather than rerunning until a single pass hides the issue.

## 9. Adoption, upgrades, and escalation

### 9.1 Inspect the target repository first

Before editing files:

1. Record the starting Git revision and preserve any unrelated uncommitted work.
2. Inventory runtimes, package manager, installed toolchain versions, `tsconfig` projects, test runners, frameworks, generators, existing lint/format configs, and CI workflows.
3. Inspect the actual installed `node_modules` declarations, tool schemas, and current docs where any framework or API contract is in doubt.
4. Check whether the repository is a **first-time adoption** or an **upgrade from an earlier version** of this standard.

### 9.2 First-time adoption

When a repository has never implemented this standard:

1. Install current `oxlint`, `tsrs`, and `oxfmt` (and required framework plugins) using the repository's package manager.
2. Create the root Oxlint config from Appendix A, add applicable Section 6 framework/runner mappings, configure Oxfmt from Section 7, and align compiler settings with Section 4.2.
3. Group findings by underlying contract and fix them cleanly using idiomatic native code (no harmful compliance shims). Separate intentional behavioral improvements from mechanical compliance edits.
4. Record any genuinely eligible relaxations under Section 2 in Appendix B.
5. Wire the required scripts and CI acceptance workflow (Section 10.1), verify coverage natively (`--print-config` / `--debug=files`), and run the full acceptance suite.

### 9.3 Upgrading from an earlier version (delta workflow)

When a repository already adopted an earlier version of this standard:

1. **Compute the delta** between the repository's existing adopted guide, lint/format/compiler configs, scripts, exception records, and quality tests against this version.
2. **Upgrade the toolchain and backend:** Replace `oxlint-tsgolint` with `tsrs`, update `oxlint`, `tsrs`, and `oxfmt` to current published releases, and remove any legacy `tsgolint` plumbing or temporary backend-swap exceptions that are now baseline.
3. **Reconcile changed baseline settings:** Apply updated defaults (`max-lines: 800`, `max-params: 5`, `unicorn/no-useless-undefined` options, `import/no-cycle` `ignoreExternal: true`, `node:test` profile) and remove any old site directives or overrides made unnecessary by the updated baseline.
   - Preserve stricter existing rules, tighter thresholds, or additional checks that are already working well and delivering real value in the target repository, and surface them to the user under Section 9.5 instead of downgrading them to the baseline.
4. **Clean up obsolete machinery and shims:** Remove stock-rule proof tests (Section 8.1), lint-only wrappers/scaffolding, and harmful compliance shims (Section 3.3 and Section 3.5) while keeping tests for custom repo-owned tooling and real behavior.
5. **Re-verify the integrated repository** through its canonical acceptance workflow and update Appendix B records to reflect the new revision and versions.

Do not leave behind mixed old/new standard copies, dead config keys, or obsolete verifier scripts that contradict this version.

### 9.4 Raising regressions to the driving user

If while tailoring or implementing this standard you identify that a **mandated rule, option, threshold, or guidance in this standard is actually causing regressions** in the target repository — for example, breaking supported runtime behavior, forcing broken types, triggering incompatibilities with the current runtime/framework/compiler, or pushing code toward harmful shims — **stop and raise the concern directly to the user driving the work**.

Include:

1. **The exact requirement:** Section, rule/option/threshold, and installed tool versions (`oxlint`, `tsrs`, `oxfmt`, `typescript`, runtime).
2. **Concrete evidence:** Reproducible diagnostic, failing test, or exact behavioral/type contract harmed.
3. **Options and recommendation:** Whether a narrow Section 2 quality exception resolves the repository issue cleanly, or whether the standard's mandated rule itself should be reconsidered.

Never hide a regression behind a silent disable, a compliance shim, or weakened test assertions.

### 9.5 Preserving and surfacing stronger repository conventions

This standard is a floor, not a ceiling. Target repositories often carry stricter rules, tighter thresholds, additional compiler flags, or custom domain checks tailored to their workload.

When you encounter existing enforcement that is stricter than this standard:

1. **Evaluate real value vs. compliance friction:** Confirm whether the stricter check is genuinely paying for itself — catching real defects, enforcing meaningful invariants, and passing cleanly without forcing synthetic splits, wrapper boilerplate, or harmful compliance shims.
2. **Preserve what works well:** Do not weaken, relax, or delete a stricter rule or threshold merely to normalize the repository down to this standard's baseline.
3. **Surface it for upstream consideration:** Highlight each high-value stricter rule or convention directly to the user driving the work — naming the exact rule, option, or check, why it fits cleanly without slop, and the class of bugs or maintainability issues it prevents — so it can be considered for adoption in a future revision of this standard.
4. **Reconcile only what actively harms quality:** If an existing stricter rule is demonstrably inducing compliance slop or harmful shims, present the concrete evidence to the user before relaxing it.

## 10. Acceptance and maintenance

### 10.1 Required commands and CI

Preserve established repository script names and package managers where appropriate. Standard script shape:

```json
{
  "scripts": {
    "lint": "oxlint --deny-warnings .",
    "lint:agent": "oxlint --deny-warnings --format=agent .",
    "lint:fix": "oxlint --fix .",
    "format": "oxfmt --write .",
    "format:check": "oxfmt --check ."
  }
}
```

The canonical acceptance workflow must require:

- Formatting check (`format:check`) and full type-aware lint (`lint`) backed by `tsrs` with zero warnings and zero unused disable directives.
- Every applicable compiler, framework typegen, and handwritten declaration check.
- Generated-artifact freshness and relevant build/package checks.
- The repository's real unit, integration, and behavioral tests (plus tests for any custom repo-owned lint plugins or policy scripts).

`lint:agent` is a compact diagnostic output format for coding agents, not a second full lint run in CI. Run independent gates so one failure does not mask others, and ensure the aggregate acceptance command exits non-zero whenever any required gate fails.

### 10.2 Completion criteria

Adoption or upgrade is complete when:

1. Every maintained source file is covered by active lint, compiler, and formatter checks.
2. Effective configuration meets or exceeds the baseline, applicable defined profiles, and justified Appendix B exceptions (preserving high-value stricter local rules under Section 9.5).
3. Migration finding budgets, diagnostic filtering, legacy `oxlint-tsgolint` dependencies, and incomplete-source exemptions are removed.
4. All required acceptance checks pass on the exact integrated revision.
5. Intentional behavioral changes, Section 2 exceptions, escalated regression concerns (Section 9.4), and high-value stricter local rules worth considering upstream (Section 9.5) have been reviewed with the driving user.
6. Required hosted CI passes on the relevant revision (or local-only acceptance is explicitly recorded if the repo has no hosted CI).

### 10.3 Ongoing maintenance

Keep `oxlint`, `tsrs`, `oxfmt`, and compiler dependencies current. Reassess exceptions whenever their underlying dependency, rule, or API contract changes.

In repository `AGENTS.md` / `CLAUDE.md` instructions, point coding agents directly to the agent-readable Markdown URL (`https://fitchhub.com/standards/oxlint-oxfmt.md` or a pinned release URL such as `https://fitchhub.com/standards/oxlint-oxfmt/v5.3.md`), name the repository's canonical acceptance command, and note where local Appendix B records live. Keep those pointers short so this standard remains the single authoritative specification.

## Appendix A: Base Oxlint configuration

This is the normative starting `.oxlintrc.json` (or equivalent `oxlint.config.ts` via `defineConfig`). Adapt `$schema` paths and profile globs per Sections 4 and 5, and add applicable Section 6 framework/runner mappings. Every weakening of an applicable requirement follows Section 2.

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["eslint", "typescript", "unicorn", "oxc", "import", "promise"],
  "categories": {
    "correctness": "error",
    "suspicious": "error",
    "perf": "error",
    "pedantic": "off",
    "style": "off",
    "restriction": "off",
    "nursery": "off"
  },
  "options": {
    "typeAware": true,
    "typeCheck": false,
    "denyWarnings": true,
    "reportUnusedDisableDirectives": "error",
    "respectEslintDisableDirectives": false
  },
  "rules": {
    "typescript/no-explicit-any": [
      "error",
      {
        "fixToUnknown": false,
        "ignoreRestArgs": false
      }
    ],
    "typescript/no-non-null-assertion": "error",
    "typescript/no-unsafe-type-assertion": "error",
    "typescript/no-unnecessary-type-assertion": [
      "error",
      {
        "checkLiteralConstAssertions": true
      }
    ],
    "typescript/consistent-type-assertions": [
      "error",
      {
        "assertionStyle": "as",
        "objectLiteralTypeAssertions": "never",
        "arrayLiteralTypeAssertions": "never"
      }
    ],
    "typescript/no-unsafe-argument": "error",
    "typescript/no-unsafe-assignment": "error",
    "typescript/no-unsafe-call": "error",
    "typescript/no-unsafe-member-access": "error",
    "typescript/no-unsafe-return": "error",
    "typescript/no-empty-object-type": "error",
    "typescript/no-unsafe-function-type": "error",
    "typescript/no-wrapper-object-types": "error",
    "typescript/no-invalid-void-type": [
      "error",
      {
        "allowAsThisParameter": true,
        "allowInGenericTypeArguments": true
      }
    ],
    "typescript/no-unnecessary-type-parameters": "error",
    "typescript/no-deprecated": "error",
    "typescript/no-duplicate-type-constituents": "error",
    "typescript/no-redundant-type-constituents": "error",
    "typescript/unbound-method": "error",
    "typescript/no-misused-spread": "error",
    "typescript/no-for-in-array": "error",
    "typescript/require-array-sort-compare": "error",
    "typescript/ban-ts-comment": [
      "error",
      {
        "ts-check": false,
        "ts-expect-error": true,
        "ts-ignore": true,
        "ts-nocheck": true
      }
    ],
    "typescript/strict-boolean-expressions": [
      "error",
      {
        "allowAny": false,
        "allowNullableBoolean": false,
        "allowNullableEnum": false,
        "allowNullableNumber": false,
        "allowNullableObject": true,
        "allowNullableString": false,
        "allowNumber": false,
        "allowString": false
      }
    ],
    "typescript/no-unnecessary-condition": [
      "error",
      {
        "checkTypePredicates": false,
        "allowConstantLoopConditions": "only-allowed-literals"
      }
    ],
    "typescript/switch-exhaustiveness-check": [
      "error",
      {
        "considerDefaultExhaustiveForUnions": false
      }
    ],
    "eqeqeq": ["error", "always"],
    "no-implicit-coercion": "error",
    "typescript/restrict-plus-operands": [
      "error",
      {
        "allowAny": false,
        "allowBoolean": false,
        "allowNullish": false,
        "allowNumberAndString": false,
        "allowRegExp": false,
        "skipCompoundAssignments": false
      }
    ],
    "typescript/restrict-template-expressions": [
      "error",
      {
        "allowAny": false,
        "allowArray": false,
        "allowBoolean": true,
        "allowNever": false,
        "allowNullish": false,
        "allowNumber": true,
        "allowRegExp": false
      }
    ],
    "typescript/no-base-to-string": [
      "error",
      {
        "checkUnknown": false
      }
    ],
    "typescript/no-floating-promises": [
      "error",
      {
        "checkThenables": true,
        "ignoreIIFE": false,
        "ignoreVoid": false,
        "allowForKnownSafeCalls": [],
        "allowForKnownSafePromises": []
      }
    ],
    "typescript/no-misused-promises": "error",
    "typescript/await-thenable": "error",
    "typescript/return-await": ["error", "error-handling-correctness-only"],
    "typescript/strict-void-return": "off",
    "typescript/no-confusing-void-expression": [
      "error",
      {
        "ignoreArrowShorthand": true,
        "ignoreVoidOperator": false,
        "ignoreVoidReturningFunctions": false
      }
    ],
    "typescript/no-meaningless-void-operator": "error",
    "promise/always-return": [
      "error",
      {
        "ignoreLastCallback": true,
        "ignoreAssignmentVariable": []
      }
    ],
    "promise/catch-or-return": "error",
    "no-async-promise-executor": "error",
    "no-promise-executor-return": "error",
    "typescript/only-throw-error": [
      "error",
      {
        "allowThrowingAny": false,
        "allowThrowingUnknown": false,
        "allowRethrowing": true
      }
    ],
    "typescript/use-unknown-in-catch-callback-variable": "error",
    "typescript/prefer-promise-reject-errors": [
      "error",
      {
        "allowEmptyReject": false,
        "allowThrowingAny": false,
        "allowThrowingUnknown": true
      }
    ],
    "no-useless-catch": "error",
    "no-param-reassign": [
      "error",
      {
        "props": true,
        "ignorePropertyModificationsFor": [],
        "ignorePropertyModificationsForRegex": []
      }
    ],
    "typescript/prefer-readonly": "error",
    "typescript/explicit-module-boundary-types": "error",
    "typescript/method-signature-style": ["error", "property"],
    "typescript/consistent-type-imports": [
      "error",
      {
        "prefer": "type-imports",
        "fixStyle": "inline-type-imports",
        "disallowTypeAnnotations": true
      }
    ],
    "typescript/consistent-type-exports": "error",
    "typescript/no-import-type-side-effects": "error",
    "import/no-cycle": [
      "error",
      {
        "ignoreTypes": false,
        "ignoreExternal": true,
        "allowUnsafeDynamicCyclicDependency": false
      }
    ],
    "import/no-self-import": "error",
    "import/no-duplicates": [
      "error",
      {
        "preferInline": true
      }
    ],
    "import/no-mutable-exports": "error",
    "complexity": [
      "error",
      {
        "max": 10,
        "variant": "modified"
      }
    ],
    "max-depth": [
      "error",
      {
        "max": 3
      }
    ],
    "max-params": [
      "error",
      {
        "max": 5
      }
    ],
    "max-statements": [
      "error",
      {
        "max": 40
      }
    ],
    "max-lines-per-function": [
      "error",
      {
        "max": 80,
        "skipBlankLines": true,
        "skipComments": true,
        "IIFEs": true
      }
    ],
    "max-lines": [
      "error",
      {
        "max": 800,
        "skipBlankLines": true,
        "skipComments": true
      }
    ],
    "curly": ["error", "all"],
    "no-var": "error",
    "prefer-const": "error",
    "no-nested-ternary": "error",
    "no-return-assign": ["error", "always"],
    "no-sequences": "error",
    "no-multi-assign": "error",
    "no-else-return": "error",
    "no-eval": "error",
    "no-implied-eval": "error",
    "no-new-func": "error",
    "no-with": "error",
    "no-debugger": "error",
    "no-control-regex": "off",
    "no-empty": [
      "error",
      {
        "allowEmptyCatch": false
      }
    ],
    "no-empty-function": "error",
    "unicorn/no-useless-undefined": [
      "error",
      {
        "checkArguments": false,
        "checkArrowFunctionBody": false
      }
    ],
    "unicorn/no-abusive-eslint-disable": "error",
    "typescript/prefer-readonly-parameter-types": "off",
    "no-await-in-loop": "off",
    "require-await": "off",
    "typescript/require-await": "off",
    "typescript/consistent-return": "off",
    "no-underscore-dangle": "off",
    "unicorn/consistent-function-scoping": "off",
    "unicorn/no-array-sort": "off",
    "unicorn/no-array-reverse": "off"
  },
  "overrides": [
    {
      "files": [
        "**/*.test.{js,jsx,ts,tsx,mjs,cjs,mts,cts}",
        "**/*.spec.{js,jsx,ts,tsx,mjs,cjs,mts,cts}",
        "**/__tests__/**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}"
      ],
      "rules": {
        "complexity": [
          "error",
          {
            "max": 15,
            "variant": "modified"
          }
        ],
        "max-depth": [
          "error",
          {
            "max": 4
          }
        ],
        "max-params": [
          "error",
          {
            "max": 6
          }
        ],
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    },
    {
      "files": ["**/*.d.ts", "**/*.d.mts", "**/*.d.cts"],
      "rules": {
        "complexity": "off",
        "max-depth": "off",
        "max-params": "off",
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    },
    {
      "files": ["**/*.test-d.{ts,mts,cts}"],
      "rules": {
        "typescript/ban-ts-comment": [
          "error",
          {
            "ts-check": false,
            "ts-expect-error": "allow-with-description",
            "ts-ignore": true,
            "ts-nocheck": true,
            "minimumDescriptionLength": 10
          }
        ],
        "complexity": [
          "error",
          {
            "max": 15,
            "variant": "modified"
          }
        ],
        "max-depth": [
          "error",
          {
            "max": 4
          }
        ],
        "max-params": [
          "error",
          {
            "max": 6
          }
        ],
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    }
  ]
}
```

## Appendix B: Repository records

Maintain these records in each adopting repository (for example, in `docs/code-quality.md` or alongside the repository's quality config). Supporting tests and review artifacts live in their normal locations, and the record must explain each decision without relying on an external conversation.

### Adoption record

Record:

- Repository name and adopted standard version (`v5.3`)
- Supported runtimes and package manager
- Installed toolchain versions (`oxlint`, `tsrs`, `oxfmt`, compiler/framework checker)
- Configuration files, compiler projects, source profiles, and acceptance commands
- Formatter and generator ownership
- Exact integrated verification revision and command outcomes

### Quality-exception record

Use stable identifiers such as `QX-001`. One rationale may cover a bounded repeated pattern. Record concrete evidence rather than restating eligibility criteria.

```text
ID and title:
Rule, option, or threshold; installed tool versions:
Scope: files, authorized operations, origins, or bounded pattern:
Diagnostic and required contract:
Best reasonable compliant alternative and demonstrated quality cost:
Eligibility ground: supported-contract harm or disproportionate complexity without meaningful safety/correctness benefit:
Chosen adjustment and why its scope is appropriate:
Structural comparison or unsafe-type evidence (where applicable):
Verification commands, relevant tests, and results:
Retained protection, lost detection, and remaining assumptions:
Review and revisit trigger:
```

## References

Primary upstream references for current tool behavior (this standard defines repository enforcement and exception authority):

- [Oxlint configuration](https://oxc.rs/docs/guide/usage/linter/config), [configuration reference](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html), and [type-aware linting](https://oxc.rs/docs/guide/usage/linter/type-aware).
- [Faster type-aware linting with `tsrs`](https://oxc.rs/blog/2026-11-17-faster-type-aware-linting-with-tsrs).
- [Oxlint ignore comments](https://oxc.rs/docs/guide/usage/linter/ignore-comments.html).
- [Floating-Promise checks](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-floating-promises), [readonly parameter types](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-readonly-parameter-types), [strict void returns](https://oxc.rs/docs/guide/usage/linter/rules/typescript/strict-void-return), and [`unicorn/no-useless-undefined`](https://oxc.rs/docs/guide/usage/linter/rules/unicorn/no-useless-undefined).
- [Promise rejection options](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-promise-reject-errors).
- [Node test runner (`node:test`)](https://nodejs.org/api/test.html).
- [Oxfmt configuration](https://oxc.rs/docs/guide/usage/formatter/config), [configuration reference](https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html), [CLI](https://oxc.rs/docs/guide/usage/formatter/cli.html), and [language support](https://oxc.rs/docs/guide/usage/formatter/language-support).
