Code Linting (Oxlint + Ruff)

architectureenforced by 1 rule

Context

Maintaining code quality and correctness is critical for long-term maintainability, especially in a hybrid workforce of human and AI/LLM developers, where AI-generated code must be held to the same high standard. Traditional linters like ESLint or Pylint are often slow, require complex configuration, and have a large dependency footprint.

The project is polyglot, using TypeScript as the primary language and Python for data tasks. We require a linting solution that is extremely fast (providing instant IDE feedback and quick CI runs), easy to configure with sensible defaults, comprehensive in its coverage of correctness rules, and well-integrated with Moonrepo and the standard IDE.

Decision

Linting will be mandatory and enforced in all projects.

For all TypeScript code, Oxlint is the exclusive linter.
For all Python code, Ruff is the exclusive linter.
An .oxlintrc.json configuration file must exist at the repository root.
Ruff lint settings should be configured in pyproject.toml for Python projects.
These tools will be integrated into the monorepo to run on every commit and pull request via Moonrepo tasks.
Builds must fail on linting errors.

Do's and Don'ts

Do

Integrate oxlint as the lint task in Moon task configurations for all TypeScript projects.
Integrate ruff check as the lint task for all Python projects.
Run oxlint and ruff check as part of moon ci. Builds must fail on linting errors.
Use the Oxlint and Ruff VSCode extensions for real-time feedback.
Keep a single .oxlintrc.json at the repository root.

Don't

Use ESLint or TSLint for TypeScript code. Oxlint is the standard linter.
Use Pylint, Flake8, or any other linter for Python code. Ruff is the standard linter.
Add configuration files for any forbidden linter (e.g., .eslintrc.js, tslint.json, .flake8, .pylintrc).
Disable or add "allow failure" exceptions for linting tasks in CI/CD.

Consequences

Positive

Both Oxlint and Ruff are written in Rust and provide 50-100x faster performance than their Node.js/Python counterparts (ESLint, Pylint), enabling near-instant developer feedback and faster CI/CD pipelines.
Ruff replaces a multitude of Python tools (Flake8, Pylint, isort, etc.) with a single binary.
Simplified configuration with one .oxlintrc.json for TypeScript and one pyproject.toml section for Python.
A single, enforced set of rules ensures all code, whether written by a human or an LLM, adheres to the same quality guidelines.
Both tools have mature VSCode extensions and integrate easily with Moonrepo.

Negative

Oxlint is newer than ESLint and does not yet have 1:1 parity with the entire ESLint plugin ecosystem. Some highly specific rules may be unavailable.
Developers familiar with ESLint's flexibility and ecosystem will need to adapt to Oxlint.

Enforcement rules

adrs/ARCH-007-linting-oxlint-ruff.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "oxlint-config-exists": {
      description: ".oxlintrc.json must exist at the repo root",
      async check(ctx) {
        try {
          await ctx.readFile(".oxlintrc.json");
        } catch {
          ctx.report.violation({
            message: ".oxlintrc.json is missing at repo root",
            file: ".oxlintrc.json",
            fix: "Create an .oxlintrc.json configuration file at the repository root",
          });
        }
      },
    },
    "no-wrong-linters": {
      description: "No ESLint, TSLint, Pylint, or Flake8 configs allowed — only Oxlint and Ruff",
      async check(ctx) {
        const forbiddenFiles = [
          ".eslintrc",
          ".eslintrc.js",
          ".eslintrc.cjs",
          ".eslintrc.json",
          ".eslintrc.yml",
          ".eslintrc.yaml",
          ".eslintignore",
          "eslint.config.js",
          "eslint.config.mjs",
          "eslint.config.cjs",
          "tslint.json",
          ".flake8",
          "pylintrc",
          ".pylintrc",
        ];

        // Check repo root
        await Promise.all(
          forbiddenFiles.map(async (file) => {
            try {
              await ctx.readFile(file);
              ctx.report.violation({
                message: `Forbidden linter config at root: ${file}`,
                file,
                fix: "Remove this file — use Oxlint for JS/TS and Ruff for Python",
              });
            } catch {
              // Doesn't exist — good
            }
          }),
        );

        // Check inside packages
        const packageDirs = [
          ...(await ctx.glob("packages/*/")),
          ...(await ctx.glob("packages/*/*/")),
        ];
        const packageChecks: Array<{ dir: string; file: string }> = [];
        for (const dir of packageDirs) {
          for (const file of forbiddenFiles) {
            packageChecks.push({ dir, file });
          }
        }
        await Promise.all(
          packageChecks.map(async ({ dir, file }) => {
            const fullPath = `${dir}${file}`;
            try {
              await ctx.readFile(fullPath);
              ctx.report.violation({
                message: `Forbidden linter config found: ${fullPath}`,
                file: fullPath,
                fix: "Remove this file — use Oxlint for JS/TS and Ruff for Python",
              });
            } catch {
              // Doesn't exist — good
            }
          }),
        );
      },
    },
  },
} satisfies RuleSet;