Strict Oxlint and Oxfmt Engineering Standard

v5.3 · Pinned (Latest)

Agent-ready linting, formatting, typechecking, and verification standard for JavaScript and TypeScript repositories using Oxlint, tsrs, and Oxfmt.

Agent access · Pure Markdown (no HTML)

Coding agents can fetch /standards/oxlint-oxfmt/v5.3.md directly (or pinned https://fitchhub.com/standards/oxlint-oxfmt/v5.3.md), or request this page URL with Accept: text/markdown to receive pure Markdown without HTML.

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.

  1. Quality, current-date grounding, and authority
  2. Quality exceptions
  3. Code design and behavioral contracts
  4. Source coverage and compiler requirements
  5. Toolchain and lint requirements
  6. Frameworks and test runners
  7. Formatting and generated artifacts
  8. Verification and enforcement integrity
  9. Adoption, upgrades, and escalation
  10. Acceptance and maintenance

1. Quality, current-date grounding, and authority

Link to 1. Quality, current-date grounding, and authority

1.1 Quality criteria

Link to 1.1 Quality criteria

Evaluate resulting code against all six criteria:

CriterionRequired outcome
CorrectnessSupported behavior, public contracts, security boundaries, and failure semantics remain sound.
MaintainabilityResponsibilities and state ownership are clear; changes have understandable, bounded effects.
ReadabilityNames, control flow, and interfaces support local reasoning without unnecessary indirection.
ConsistencyEquivalent operations follow established project conventions and use the same authoritative contracts.
ReuseShared domain knowledge, types, schemas, validation, and utilities have appropriate common ownership.
EfficiencyResource 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

Link to 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

Link to 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

Link to 2. Quality exceptions

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

Link to 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

Link to 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

Link to 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:

// 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

Link to 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

Link to 3. Code design and behavioral contracts

3.1 Shared contracts and reuse

Link to 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

Link to 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

Link to 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.

AreaContracts to preserve or explicitly change
ErrorsIdentity, subclass, code, cause, redaction, messages, thrown vs returned failures, and operator-visible output
DataAccepted inputs, defaults, validation location, serialization, absent vs explicit undefined, ordering, and reference identity
ObjectsObject vs collection APIs, property access, getters, prototypes, and consumer expectations
Async executionOrdering, concurrency, registration and hook timing, cancellation, retries, cleanup, and rejection ownership
ResourcesPublic signatures, receiver identity, lifecycle ownership, framework-required exports, and generated bindings
DistributionPackage 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

Link to 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

Link to 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:

PracticeRequired correction
Duplicate types, schemas, validators, or guards restating an established contractReuse the authoritative contract at the right boundary while preserving real ownership and distribution boundaries.
Harmful compliance shims (synthetic TypeErrors, 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 checksRestore 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 applyRestore cohesive responsibilities and readable scenarios while keeping genuinely useful abstractions.
Accidental changes to errors, accepted inputs, serialization, scheduling, cleanup, or assertions during compliance editsRestore 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 checksRemove 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

Link to 4. Source coverage and compiler requirements

4.1 Source profiles

Link to 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:

ProfileRequired treatment
Production, libraries, adapters, build/admin/quality toolingApplicable lint, compiler, and formatter checks; production structural limits
Tests and exclusively test-only supportFull applicable safety checks, assertion checks, and test structural limits
Handwritten declarations and augmentationsApplicable lint, real declaration checking, and relevant public-consumer checks; no implementation-size metrics
Static literal dataParsing, formatting, applicable typing/schema checks; no implementation-size metrics
Dedicated negative type testsCompiler-verified expected errors and passing counterparts; test structural limits
Generated or vendored outputIdentifiable 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

Link to 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:

{
  "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:

{
  "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

Link to 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

Link to 5. Toolchain and lint requirements

5.1 Published tools and tsrs type-aware backend

Link to 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:

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

Link to 5.2 Base configuration and composition

Use the complete Appendix A 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

Link to 5.3 Structural profiles
MetricProductionTests and test-only support
Modified cyclomatic complexity1015
Nesting depth34
Parameters (max-params)56
Statements per function (max-statements)40Off
Effective lines per function, including IIFEs (max-lines-per-function)80Off
Effective lines per file (max-lines)800Off

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

Link to 5.4 Deliberate baseline choices
SettingEngineering 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: falsePrevents 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: trueEnforces 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: offAccurate 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: offOrdinary synchronous callbacks may legitimately ignore return values. Floating Promises and async-callback misuse remain checked.
typescript/no-base-to-string with checkUnknown: falseUnknown diagnostic values may legitimately be formatted; known base-object stringification and unsafe any propagation remain checked.
typescript/prefer-promise-reject-errors with allowThrowingUnknown: truePreserves existing error identity when forwarding caught unknown rejections while still rejecting any, known non-Errors, and empty reject().
no-await-in-loop: offSequential await in loops is frequently required for pagination, rate limits, ordered side effects, and resource lifetimes.
no-control-regex: offControl-character validation and sanitization are legitimate; use legible escape sequences and tests.
Test statement/function/file-size limits offClear, 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

Link to 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:

RuleCommon trapIdiomatic resolution
preserve-caught-errorWrapping 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-listenerAssigning 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-propWhen 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-conditionTypeScript 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

Link to 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

Link to 6.1 React and DOM accessibility

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

{
  "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:

{
  "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.

Add "vitest" for Vitest test scopes and enable:

{
  "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"
}

Add "jest" for Jest test scopes and enable:

{
  "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)

Link to 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):

{
  "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

Link to 7. Formatting and generated artifacts

7.1 Formatter ownership

Link to 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"):

{
  "$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

Link to 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

Link to 8. Verification and enforcement integrity

8.1 Focused gate integrity — no stock-rule proof tests

Link to 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

Link to 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

Link to 9. Adoption, upgrades, and escalation

9.1 Inspect the target repository first

Link to 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

Link to 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)

Link to 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

Link to 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

Link to 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

Link to 10. Acceptance and maintenance

10.1 Required commands and CI

Link to 10.1 Required commands and CI

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

{
  "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

Link to 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

Link to 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

Link to 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.

{
  "$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

Link to 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.

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

Link to 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.

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:

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