docs(oxfmt,formatter,formatter_json,formatter_core): add/update AGENTS.md (#22873)

- Update: apps/oxfmt
- Add: crates/oxc_formatter_core,oxc_formatter,oxc_formatter_json

Author: leaysgur

apps/oxfmt/AGENTS.md

@@ -6,12 +6,12 @@ The `oxfmt` implemented under this directory serves several purposes.
 
 - Pure Rust CLI
   - Minimum feature set, CLI usage only, no LSP, no Stdin support
-  - Formats JS/TS and TOML files, no xxx-in-js support
+  - Formats JS/TS, JSON and TOML files, no xxx-in-js support
   - Entry point: `main()` in `src/main.rs`
   - Build with `cargo build --no-default-features`
 - JS/Rust hybrid CLI using `napi-rs`
   - Full feature set like CLI, Stdin, LSP, and more
-  - Format many file types with embedded language formatting support
+  - Format many file types with embedded language formatting support like Prettier
   - Entry point: `src-js/cli.ts` which uses `run_cli()` from `src/main_napi.rs`
   - Build with `pnpm build`
 - Node.js API using napi-rs
@@ -20,7 +20,7 @@ The `oxfmt` implemented under this directory serves several purposes.
 
 When making changes, consider the impact on all paths.
 
-## Platform Considerations
+### Platform considerations
 
 Oxfmt is built for multiple platforms (Linux, macOS, Windows) and architectures.
 
@@ -31,6 +31,26 @@ When working with file paths in CLI code, be aware of Windows path differences:
   - Avoid hardcoding `/` as a path separator; prefer `Path::join()`
   - Windows uses `\` as a path separator and has drive letter prefixes (e.g., `C:\`)
 
+### Formatter implementations
+
+Oxfmt utilizes different implementations depending on the file extension and filename:
+
+- Tier 1: Rust implementations using `oxc_formatter` or `oxc_formatter_json` found in this repository
+- Tier 2: Rust implementations using external libraries like `oxc_toml`
+- Tier 3: Delegations to Prettier via NAPI-JS calls (e.g., for Vue or Markdown)
+- Tier 4: Delegations to Prettier that require additional plugins (e.g., for Svelte)
+
+Consequently, managing these various formatter implementations and handling their respective options are also part of Oxfmt's responsibilities.
+
+### CLI implementations
+
+Oxfmt shares code with Oxlint regarding its CLI implementation.
+
+- Rust implementation: `crates/oxc_config`
+- JS implementation: `apps/shared`
+
+Please exercise extra caution when making changes to these files.
+
 ## Verification
 
 ```sh
@@ -44,14 +64,15 @@ Also run `clippy` for the same configurations and resolve all warnings.
 Run tests with:
 
 ```sh
+# Run unit test in Rust
+cargo t
 # Run E2E test
-pnpm build-test && pnpm t
+pnpm build-dev && pnpm t
 # Update snapshots
 pnpm t -u
+
 # Run conformance test for xxx-in-js and js-in-xxx
 pnpm conformance
-# Run unit test in Rust
-cargo t
 ```
 
 To manually verify the CLI behavior after building:
@@ -67,18 +88,18 @@ cat <file> | node ./dist/cli.js --config=<cfg> --stdin-filepath=<file>
 OXC_LOG=debug node ./dist/cli.js --threads=1 <file>
 ```
 
-NOTE: `pnpm build-test` combines `pnpm build-js` and `pnpm build-napi`, so you don't need to run them separately.
+NOTE: `pnpm build-dev` combines `pnpm build-js` and `pnpm build-napi`, so you don't need to run them separately.
 
 To compare formatting output with Prettier:
 
 ```sh
-# Use a shared config file (e.g., fmt.json) because oxfmt and Prettier have different default printWidth
+# Use a shared config file (e.g., fmt.json) because Oxfmt and Prettier have different default printWidth.
 # Example fmt.json: { "printWidth": 80 }
 cat <file> | node ./dist/cli.js --config=fmt.json --stdin-filepath=<file>
 npx prettier --config=fmt.json <file>
 ```
 
-## Test Organization (`test/` directory)
+## Test organization (`test/` directory)
 
 Tests are organized into specific domains, each with its own structure.
 
@@ -114,7 +135,7 @@ Each test directory follows the 1:1:1 rule:
 
 Shared helpers are in `utils.ts` at the `test/lsp/` level.
 
-## After updating `Oxfmtrc` (Under `src/core/oxfmtrc`)
+## After updating `Oxfmtrc` (`src/core/oxfmtrc.rs`)
 
 When modifying the `Oxfmtrc` struct (and configuration options):
 

crates/oxc_formatter/AGENTS.md

@@ -0,0 +1,107 @@
+# Coding agent guides for `crates/oxc_formatter`
+
+## Overview
+
+Prettier compatible JS/TS formatter (`oxfmt`'s Tier 1 backend), ported from [Biome](https://github.com/biomejs/biome).
+It turns a parsed AST into an IR ("Document") of `FormatElement`s, then prints that IR via the shared `oxc_formatter_core` Printer.
+
+- Built on `oxc_formatter_core` for the language-agnostic IR + Printer + builders + macros
+  - See `crates/oxc_formatter_core/AGENTS.md` for the IR/pipeline details
+- This crate holds only the JS/TSX-specific layer
+- Parses with `oxc_parser`
+  - Comments and other JS-specific concerns live here, not in core
+
+### Public API
+
+Call-sites use text-in entry points;
+The AST-wrapping IR primitives (`AstNode`, `Format`, `Buffer`, …) are `pub(crate)` and not part of the contract.
+
+- `format`: Format a whole file (text-in)
+- `format_fragment`: Format a JS/TS fragment for js-in-xxx embedding, parameterized by `FragmentContext`
+  - Drives context-dependent decisions like forced parentheses / quote style
+  - The formatter knows nothing about Prettier/Vue vocabulary, callers pass wrapped source
+- `format_program`: Special-purpose AST-in entry point
+- `ExternalCallbacks` (in `external_formatter.rs`): Callbacks for embedded-doc / Tailwind formatting delegated back to the host
+
+### Generated code
+
+`ast_nodes/generated/` and the `Format` glue are generated by `tasks/ast_tools`.
+After changing AST shapes or the generators, regenerate with `just ast`, never hand-edit files under `generated/`.
+
+## JS formatter specific features
+
+### Sort imports (`ir_transform/sort_imports/`)
+
+- Inspired by `eslint-plugin-perfectionist`, but not a 1:1 match (default group definitions differ too)
+- Implemented purely as a Rust IR transform; requires no JS callback
+
+### Format JSDoc (`formatter/jsdoc/`)
+
+- Derived from `prettier-plugin-jsdoc`, but not fully compatible
+- See `prettier_conformance/jsdoc` for the covered behavior
+
+### Sort Tailwind CSS
+
+- Derived from `prettier-plugin-tailwindcss`
+- Classes are collected during IR construction and sorted in one batch when the IR is stringified
+- Requires `ExternalCallbacks` (the sort itself is delegated to the host via `TailwindCallback`)
+
+### Embedded language formatting
+
+- Two directions: xxx-in-js (e.g. css/graphql/html in template literals) and js-in-xxx (e.g. vue/svelte)
+- Both work by Oxfmt injecting Prettier calls through `ExternalCallbacks`
+  - This crate stays unaware of Prettier and only invokes the supplied callbacks
+
+## Fixing IR construction
+
+- Always keep the big picture in mind so a fix is not a one-off patch
+  - Comments and parentheses are especially prone to side effects, handle them with care
+- We aim for Prettier compatibility, but the implementation strategy differs:
+  - Prettier pre-classifies comments per context, whereas oxc_formatter decides on the spot
+  - Biome works on a CST rather than an AST, so its code and strategy differ in detail too
+
+Above all, prioritize consistency, and always consider whether the divergence is a Prettier bug.
+
+## Verification
+
+```sh
+cargo c -p oxc_formatter
+cargo c -p oxc_formatter --features detect_code_removal
+```
+
+Run `clippy` for the same configurations and resolve all warnings.
+
+### Fixtures tests
+
+Snapshot tests driven by fixture files under `tests/fixtures/{js,ts}/`.
+`build.rs` auto-discovers every `.{js,jsx,ts,tsx}` file and generates a test function per file; options are resolved from the nearest `options.json` up the directory tree. See `tests/README.md` for the full workflow.
+
+```sh
+# Run all fixtures tests
+cargo test -p oxc_formatter --test mod
+# Run a subset by module path (directory structure = module hierarchy)
+cargo test -p oxc_formatter fixtures::js::comments
+# Review / accept snapshots after intentional changes
+cargo insta test --accept -p oxc_formatter --test mod
+```
+
+Add a case by dropping a new file into `tests/fixtures/`, no manual registration needed.
+
+### Prettier conformance
+
+Compares output against Prettier's snapshots and tracks failures (not passes); results live in `tasks/prettier_conformance/snapshots/`.
+
+```sh
+cargo run -p oxc_prettier_conformance
+```
+
+### Embedded conformance (`apps/oxfmt`)
+
+The embedded-language features (xxx-in-js / js-in-xxx) are validated end-to-end through the Oxfmt.
+
+Requires a dev build first.
+
+```sh
+pnpm --dir apps/oxfmt build-dev
+pnpm --dir apps/oxfmt conformance
+```

crates/oxc_formatter/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

crates/oxc_formatter_core/AGENTS.md

@@ -0,0 +1,46 @@
+# Coding agent guides for `crates/oxc_formatter_core`
+
+## Overview
+
+Language-agnostic formatting infrastructure, ported from [Biome](https://github.com/biomejs/biome)'s `biome_formatter` crate.
+
+Every language-specific formatter in the oxc ecosystem (`oxc_formatter` for JS/TS, `oxc_formatter_json`, and future CSS/GraphQL/etc.) builds on this crate.
+It owns the IR and the printing pipeline; it knows nothing about any concrete language (no comments, no quote rules, those live in the consumer crates).
+
+### The IR ("Document") and pipeline
+
+Formatting is two stages:
+
+1. A consumer crate walks its AST and builds an IR, a tree of `FormatElement`s using the `builders` and the `write!` / `format_args!` macros
+2. The `Printer` consumes that IR plus `PrinterOptions` and produces the output string, deciding line breaks, indentation, and group expansion
+
+Key IR pieces are all exported from the crate root.
+
+### Generic context design
+
+The core is parameterized over a consumer-supplied context so it stays language-agnostic:
+
+- `FormatContext` trait: no lifetime parameter
+  - (avoids `oxc_allocator`'s `'ast` propagating through struct bounds and blocking anonymous lifetimes)
+  - The allocator lives on `FormatState`, not the context
+- `FormatOptions` trait: `indent_style()`, `indent_width()`, `line_width()`, `line_ending()`, `as_print_options() -> PrinterOptions`
+  - Core option types: `IndentStyle`, `IndentWidth`, `LineWidth`, `LineEnding`, `Expand`, `BracketSpacing`
+- `Format<'ast, C>` trait + `FormatState<'ast, C>`, `Formatted<'ast, C>`, `Formatter<'buf, 'ast, C>`, `Buffer<'ast, C>`
+  - All generic over the context `C`, consumers add a `C` bound only on `impl` blocks
+  - Not on struct definitions, and typically define a `type FooFormatter<…> = Formatter<…, FooContext<…>>` alias to keep lifetimes aligned
+
+## Cargo features
+
+`test_harness` exposes `test_support/` (fixture test generation) to downstream crates.
+Consumers still need their own `insta` dev-dep so the recorded `source:` header points to the consumer crate.
+
+## Verification
+
+```sh
+cargo c -p oxc_formatter_core
+cargo c -p oxc_formatter_core --features test_harness
+```
+
+Run `clippy` for both configurations and resolve all warnings.
+
+This crate has basic tests only of its own, it is exercised through the conformance/snapshot tests of its consumers.

crates/oxc_formatter_core/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

crates/oxc_formatter_json/AGENTS.md

@@ -0,0 +1,47 @@
+# Coding agent guides for `crates/oxc_formatter_json`
+
+## Overview
+
+Prettier compatible JSON/JSONC/JSON5 formatter (`oxfmt`'s Tier 1 backend), using the `oxc_formatter_core` APIs.
+
+- Built on `oxc_formatter_core` for the language-agnostic IR + Printer + builders + macros
+  - See `crates/oxc_formatter_core/AGENTS.md` for the IR/pipeline details
+- This crate holds only the JSON-specific layer
+- Parses with `oxc_parser`, not `serde_json`
+  - For Prettier, JSON is not spec compliant JSON
+  - They are subsets of JS expression syntax, so the comments, unquoted key, etc... are allowed as input
+
+### `JsonVariant`
+
+All variants share lenient parsing (comments, trailing commas, single quotes, unquoted keys all parse regardless of variant).
+
+What differs is the output formatting. See the doc comments on `JsonVariant` in `src/options.rs` for the per-variant rules.
+
+## Verification
+
+```sh
+cargo c -p oxc_formatter_json
+```
+
+Run `clippy` and resolve all warnings.
+
+### Fixtures tests
+
+Snapshot tests driven by fixture files under `tests/fixtures/json/`.
+`build.rs` auto-generates a test case from every `.{json,jsonc,json5}` file using the core `test_support` harness.
+
+```sh
+cargo test -p oxc_formatter_json
+# Review / accept snapshots after intentional changes
+cargo insta review -p oxc_formatter_json
+```
+
+Add a case by dropping a new file into `tests/fixtures/json/`, the build script picks it up.
+
+### Prettier conformance
+
+Compares output against Prettier's snapshots and tracks failures (not passes); results live in `tasks/prettier_conformance/snapshots/`. The `json` language is part of the shared conformance binary.
+
+```sh
+cargo run -p oxc_prettier_conformance
+```

crates/oxc_formatter_json/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md