oxc-project/oxc
github.com/oxc-project/oxc ↗ · 4000 files · 12.6 MB · scan capped
[![MIT licensed][license-badge]][license-url] [![Build Status][ci-badge]][ci-url] [![Code Coverage][code-coverage-badge]][code-coverage-url] [![Discord chat][discord-badge]][discord-url] [![Playground][playground-badge]][playground-url] [![Website][website-bad
Overview
Oxc is a modular Rust toolchain for JavaScript and TypeScript, serving developers through Oxlint and Oxfmt and tooling authors through compiler crates and Node.js bindings. Its implementations share arena-backed ASTs, semantic analysis, diagnostics, and code generation, while application layers add file discovery, configuration, parallel processing, and editor integration. This brief examines commit 7f65b757df7c3225320d8f7e051e64873f80f988 through bounded source inspection; it does not establish runtime correctness or measured performance.
System map
The repository combines reusable compiler components with native applications and Node.js bindings. Runtime boundaries differ between Rust-only CLIs, NAPI callbacks, the stdio language server, and the optional tsgolint subprocess. Application persistence is visible as source-file rewrites and a JSON suppression baseline. Build and verification definitions span Cargo, pnpm, Just, and GitHub Actions.
- Cargo groups apps, crates, napi, and tasks into one workspace using resolver 3 and Rust edition 2024; the declared MSRV is 1.97.0.
- The shared dependency table connects allocator, AST, parser, semantic, transformer, minifier, codegen, diagnostics, and traversal crates; formatter and application crates are separately marked unpublished.
- Oxlint's native entrypoint uses a synchronous Rayon CLI path and constructs a Tokio runtime only when --lsp is selected.
- Oxfmt exports both a Rust executable and lib/cdylib artifacts; its Rust main supports basic CLI processing, while run_cli supplies Node-backed LSP, stdin, initialization, and migration dispatch.
- The language-server transport is stdin/stdout through tower_lsp_server; its service registers document lifecycle, diagnostics, formatting, code actions, and workspace commands.
- LintRunner owns regular LintService, optional TsGoLintState, and a shared disable-directive store; tsgolint is launched as a separate process with piped JSON input.
- Persistent outputs include formatter source rewrites, lint-fix source rewrites, and pretty-printed JSON suppression tracking saved through fs::write.
- Root pnpm scripts build and test selected application, NAPI, and package workspaces sequentially; Cargo aliases provide checks, Clippy, conformance, benchmarking, and code generation, while just test invokes cargo test --all-features.
Feature catalog
The inspected public surfaces cover linting, formatting, parsing, transformation, minification, and editor integration. Application features depend on the execution boundary: Node callbacks enable capabilities unavailable in the Rust-only formatter CLI. Framework and ecosystem names generally describe supported inputs or lint plugins, rather than a product frontend. This catalog covers the investigated interfaces and does not claim exhaustive enumeration of every rule or option.
- Oxlint exposes initialization, resolved-config printing, rule listing, and debug file listing as early branches within CliRunner::run.
- Type-aware linting and type checking are configurable; --type-check requires type-aware mode, and --type-check-only rejects fix flags and suppression-update flags.
- Oxlint supports bulk suppression and pruning through oxlint-suppressions.json, reports stale baseline entries, and returns success after a successful --suppress-all update.
- Oxfmt's Node CLI dispatches initialization, Prettier migration, Biome migration, stdin formatting, filesystem formatting, and LSP operation.
- Oxfmt classifies JS/TS, TOML, package.json, JSON/JSONC/JSON5, GraphQL, CSS variants, and YAML into native strategies; Prettier file delegation is gated by the napi feature.
- Embedded formatting routes GraphQL, CSS/SCSS/Less, YAML, and JSON variants natively; HTML, Angular, and Markdown use an available Prettier fallback, and unsupported languages remain unchanged.
- The parser binding offers synchronous and task-based parsing, optional semantic diagnostics, selectable JavaScript/TypeScript AST fields, comments, and module metadata.
- Transformation options include TypeScript declarations, decorators, third-party plugin options, JSX, target environments, inject/define replacements, and source maps; minification separately returns code, maps, legal comments, diagnostics, and an optional property-mangle cache.
Data flow
Source text enters through filesystem reads or explicit binding arguments and becomes arena-owned compiler data. Configuration resolution selects rule state or a typed formatting strategy before processing. Node parser output crosses an additional coordinate and serialization boundary. Filesystem outputs and suppression baselines are distinct from temporary allocator, module-graph, and directive state.
- Parser binding input consists of filename, source text, and ParserOptions; parse_with_return creates an allocator, derives SourceType and AST flavor, then calls parse_impl.
- Node parser results optionally accumulate semantic diagnostics, convert AST/module/error offsets from UTF-8 to UTF-16, serialize ESTree fields, and return comments plus module metadata.
- Oxlint normalizes explicit paths, filters ignore sources, walks candidates, loads root/nested configuration, and combines resolved rule state and external-plugin metadata into ConfigStore.
- Lint Runtime stores source and section semantics under an AllocatorGuard-backed self_cell; a concurrent module graph retains Arc-owned records, with other cyclic references required to use Weak.
- PartialLoader separates framework source sections; each section is parsed and semantically analyzed, and failed-section diagnostic spans are shifted back to original file coordinates.
- Oxfmt streams FormatStrategy entries over an mpsc channel; FormatService bridges them into Rayon processing, reads source, formats it, and sends success or wrapped diagnostics over separate channels.
- JS formatting acquires a pooled allocator and a FormatSession carrying resolved host services, calls format_with_session, and prints its result; embedded children inherit the host's resolved config rather than resolving a virtual path.
- Suppression state maps filenames to rule diagnostic counts; serialization sorts filenames and rules, while finalization compares runtime counts with the baseline before saving updates or reporting differences.
Behavior traces
The following traces were reconstructed by reading callers and callees, without execution. They follow parser API use, lint startup and fixes, suppression persistence, formatter startup and writes, and minification. Branch conditions matter: parser recovery differs from lint rejection, configuration can fail during streaming, and type-check-only alters the lint pipeline.
- Parser flow: parse_sync → parse_with_return → get_source_type/get_ast_type → parse_impl → Parser::new.with_options.parse; showSemanticErrors then conditionally invokes SemanticBuilder before UTF-16 conversion and ESTree serialization.
- Lint startup: main → lint_command().run → init_tracing → handle_threads → CliRunner::new.run; --lsp instead constructs Tokio and awaits run_lsp.
- Lint orchestration: CliRunner::run → Walk::paths → ConfigLoader::load_root_and_nested → ConfigStoreBuilder::build → LintRunner::builder.build → lint_files; regular LintService runs before optional tsgolint, while type-check-only collects parse diagnostics instead of regular rules.
- Per-file lint/fix flow: Runtime::run_impl resolves modules → process_path_to_module reads source → process_source splits sections → process_source_section parses and builds semantics → run_with_disable_directives → optional Fixer::fix → write_file for modified source.
- Suppression persistence: CliRunner loads SuppressionManager → build_diff → lint_files accumulates counts → finalize computes suppression/pruning updates → write → SuppressionTracking::save serializes and writes JSON; type-check-only skips finalization.
- Node formatter startup: cli.ts gathers argv and supplies callbacks → run_cli parses modes → initialization/migration returns to JavaScript; CLI mode initializes Rayon, constructs WalkRunner with external services and a config loader, then calls run.
- Formatter write flow: WalkRunner::run loads ConfigScopes → starts FormatService::run_streaming → ScopedWalker::run sends targets → SourceFormatter::format dispatches a strategy → format_with_session.print for JS → fs::write only when Write mode and is_changed are both true.
- Minification flow: minify_sync → minify_impl validates options → Parser::parse → disables property mangling if parsing reported diagnostics → Minifier::minify → Codegen with returned scoping/private mappings → result containing code, map, comments, errors, and eligible cache.
Testing signals
Tests and CI were inspected, not executed; test existence is not a passing result. Rust tests, Insta snapshots, Vitest bindings tests, formatter fixture harnesses, and external conformance tasks cover different boundaries. The inspected definitions expose important limits, including recorded idempotency failures and platform jobs that run only on main. This bounded inspection does not establish complete coverage or identify every untested path.
- The inspected NoDebugger rule uses a Rust #[test], Tester pass/fail inputs, explicit expected fixes, and test_and_snapshot; cases preserve valid control-flow bodies by replacing debugger with an empty block.
- Parser Vitest cases exercise language selection, async output/comments, opt-in semantic errors, script/module/commonjs interpretation, and declaration-file parsing; these definitions were read without running them.
- Minifier Vitest cases assert emitted code and source-map contents and test disabling compression, mangling, and whitespace removal.
- The shared formatter harness generates option/width variants, asserts input/output fingerprints, and feeds Insta snapshots; idempotency mismatches are recorded as snapshot sections rather than asserted independently.
- SourceFormatter Rust tests cover native CSS-in-JS, native JSDoc fences, embedded formatting disabled, and preservation of non-native HTML embeds when napi is disabled.
- The conformance CLI selects parser, lexer, semantic, codegen, formatter, transformer, minifier, runtime, ESTree, token, and types tasks; it loads fixture data lazily and supports --filter.
- CI defines Linux all-feature tests, conditionally built NAPI/Vitest and e2e suites, and app-specific tests; ARM64, macOS, Windows, big-endian, and 32-bit jobs are main-only, with explicit cross-target exclusions.
- Separate inspected workflows define strict-provenance Miri checks, Windows allocator Miri, LLVM coverage, CodSpeed component benchmarks, and label-triggered ecosystem CI; their presence supplies no execution or performance result in this investigation.
Risk map
These are source-observed trust boundaries and correctness hazards, not confirmed vulnerabilities. The most consequential inspected paths execute JavaScript configuration, select an external executable, transfer raw memory, or rewrite user files. Compiler-stage ordering and streaming configuration introduce additional coupling. Testing and documentation limits should be accounted for before making broader safety or correctness claims.
- JavaScript/TypeScript configuration is executable input: importJsConfig dynamically imports a cache-busted file URL before validating its default export; Oxfmt invokes it through the Node config callback.
- Type-aware linting trusts executable selection from OXLINT_TSGOLINT_PATH, ancestor node_modules/.bin locations, then PATH; spawn_tsgolint executes that path with headless and piped input.
- Raw parser transfer exposes unsafe functions with caller requirements for source offset, length, and valid UTF-8; get_buffer_offset explicitly does not verify bounds, and the representation relies on large aligned buffers and platform gating.
- Formatter writes can partially complete before a lazy nested-config failure: WalkRunner explicitly warns that unaffected scopes may already have been written.
- Selected formatting paths are rewritten with fs::write, and cwd is used to shorten displayed paths with an outside-cwd fallback; this write site itself does not enforce repository-root containment.
- Transformations can leave scoping out of sync with the AST; CompilerInterface::compile tracks scoping_dirty and rebuilds before inject/define consumers, making stage order a correctness-sensitive edit boundary.
- Formatter fixture snapshots can contain accepted idempotency mismatches, so a matching snapshot alone does not establish formatter idempotence.
- Architecture documentation contains version drift: ARCHITECTURE.md states MSRV 1.86.0+, whereas Cargo.toml declares 1.97.0 and rust-toolchain.toml selects 1.99.0.
Extension points
Extensions attach to explicit Rust traits, generated registries, callback interfaces, and dispatch tables. Native lint rules and JavaScript lint plugins enter through different mechanisms. Formatter integration owns language routing and host services, while language crates implement formatting. Compiler hooks and filesystem abstractions provide composition points without requiring changes to application startup.
- Native lint rules implement Rule hooks for configuration, AST nodes, whole-file analysis, Jest/Vitest nodes, and per-file should_run selection.
- Rule metadata is declared with declare_oxc_lint, as demonstrated by NoDebugger; the generated rule enum identifies cargo lintgen as its regeneration command.
- External lint plugins supply workspace create/destroy, plugin loading, rule configuration, and per-file lint callbacks carrying rule IDs, options IDs, settings, globals, and allocator access.
- RuntimeFileSystem is an injection boundary for reading and writing linted files; LintService accepts it for filesystem linting, source linting, and parse-diagnostic collection.
- Whole-file formatter support plugs into classify_file_kind and FormatStrategy::from_format_config; classification returns None for excluded or unsupported targets and gates Prettier strategies on napi.
- Embedded language support plugs into route and dispatcher assembly; aliases resolve centrally, with typed Native, Prettier, and Unsupported outcomes.
- Language-server tools implement ToolBuilder::build and Tool methods for configuration, watchers, commands, code actions, formatting, and diagnostic lifecycle behavior.
- CompilerInterface exposes stage options and after_parse/after_semantic/after_transform hooks with early termination; formatter test consumers separately implement FixtureFormatter with language-owned options and fingerprints.
Contributor handoff
Use the pinned implementation and nearest package guidance to choose a narrow edit boundary. Tests and CI were inspected, not executed, and the inventory remains bounded rather than exhaustive. Future verification should target the changed runtime surface before broad workspace checks. Generated outputs, formatter policy, and Rust-versus-Node feature differences are recurring traps.
- Start with the root and nearest package AGENTS.md; Oxfmt's guide identifies separate CLI, stdin, LSP, direct API, and textToDoc paths and warns against assuming shared behavior.
- Use manifests for version decisions: development Rust is 1.99.0, MSRV is 1.97.0, and the root package manager is pnpm 12.7.0.
- Edit generator inputs rather than generated artifacts: AST builder output names its generator, and linter registry output requires cargo lintgen; root guidance also requires lint-timings for linter codegen changes.
- For formatter changes, read the shared FORMATTER_POLICY through the crate guide, preserve text-in API boundaries, and keep comments, parentheses, and embedding responsibilities in their owning layer.
- Account for Oxfmt execution differences: the pure Rust CLI has no stdin/LSP support, the Node API uses caller-supplied options without config discovery, and native formatters do not fall back to Prettier.
- For later authorized checks, use focused Rust tests, filtered cargo coverage tasks, or package-specific pnpm build-test/test commands; this investigation inspected their definitions and CI wiring without executing them.
- Do not treat just fmt or just ready as harmless read-only checks: fmt invokes cargo shear --fix, while ready installs dependencies, regenerates code, formats files, and runs broad checks.
- Submission guidance requires AI-use disclosure and human responsibility for reviewed, understood, tested contributions; preserve this requirement when preparing an issue or PR.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 4150 | 47% |
| Rust | 2463 | 28% |
| TypeScript | 2042 | 23% |
| JSON | 980 | docs/config |
| Markdown | 620 | docs/config |
| YAML | 83 | docs/config |
| TOML | 81 | 1% |
| Sass | 57 | 1% |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
crates/ (1925 files) packages/ (7 files)
Repository structure
| Top-level path | Files |
|---|---|
crates/ | 1925 |
apps/ | 1470 |
tasks/ | 380 |
napi/ | 102 |
.github/ | 54 |
npm/ | 23 |
packages/ | 7 |
.agents/ | 4 |
Docs found: AGENTS.mdARCHITECTURE.mdCONTRIBUTING.mdREADME.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/autofix.yml— GitHub Actions workflow.github/workflows/benchmark.yml— GitHub Actions workflow.github/workflows/bloat.yml— GitHub Actions workflow.github/workflows/cargo_llvm_lines.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/codecov.yml— GitHub Actions workflow.github/workflows/deny.yml— GitHub Actions workflow.github/workflows/ecosystem-ci.yml— GitHub Actions workflow
Structural health signals
Average score 6.2/10 across 96 analyzed source files; 55 hotspots surfaced.
apps/oxlint/src/lint.rs— 1362 lines, score 4 (Large file, Deep nesting)apps/oxlint/src/config_loader.rs— 1254 lines, score 4 (Large file, Deep nesting)apps/oxfmt/src/cli/walk.rs— 986 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
7f65b757df7c2026-10-02 — fix(formatter): format assignment target property as assignment-like (#27289)6c08f2aaf1082026-10-02 — fix(formatter_css): apply the `url()` import exception to a lone comma group (#27288)565d75dce1ca2026-10-02 — fix(minifier): correct indopedency when processing nested sequences (#27273)f9a056b8a4552026-10-02 — test(oxlint): use plain text for stylish CLI snapshots (#27287)3f86ed558ad92026-10-02 — test(lexer): improve test for `kw_verify_batch` (#27286)