@isentinel/eslint-config 6.0.1 → 6.2.0

package/README.md

@@ -253,6 +253,22 @@ Other behaviours:
   re-lint (its own dirty count), rather than eagerly spinning up a worker per
   CPU. The fast pass is cheap per file, so it packs far more files per worker
   (see `FAST_FILES_PER_WORKER`) than the type-aware pass.
+- Sizes the heap of every ESLint child that builds a TypeScript program (the
+  type-aware pass, the full pass and the fix child). Each worker holds its own
+  program, so the limit that matters is workers × heap. By default the runner
+  splits half the machine's memory (or its cgroup limit, when lower) across
+  those workers, and raises Node's heap limit when the share is larger. When the
+  budget cannot give each worker twice Node's default heap, it runs fewer
+  workers: every worker loads the program of nearly every project, so fewer,
+  larger workers need far less memory in total than more, smaller ones. The flag
+  goes in the child's `NODE_OPTIONS`, which every ESLint worker inherits; oxlint
+  and the fast pass never get it. `--print` shows the chosen workers, files per
+  worker and heap on stderr. If a child still runs out of memory, the runner
+  prints a hint that names `LINT_TYPED_HEAP_MB`. A size set in
+  `LINT_TYPED_HEAP_MB` also caps the workers at budget ÷ size. An explicit
+  `LINT_MAX_WORKERS` or `--concurrency` is never reduced. A
+  `--max-old-space-size` already in `NODE_OPTIONS` wins over all of this: the
+  runner adds nothing and keeps the worker count.
 - Keeps a separate ESLint cache per pass so they never invalidate one another:
   `.eslintcache-fast-<key>` (fast pass), `.eslintcache-typeaware-<key>`
   (type-aware pass), and `.eslintcache-<key>` (the full config, used by CI,
@@ -383,6 +399,7 @@ or `--`.
 | `--oxlint-args "<args>"`       | Extra arguments forwarded verbatim to oxlint.                                                                                      |
 | `--files0-from <file\|->`      | Read the paths to lint from a NUL-delimited UTF-8 list (`-` for stdin); an empty list exits 0.                                     |
 | `--print`                      | Print the composed commands without running them.                                                                                  |
+| `--no-oxfmt`                   | Skip the oxfmt pass that runs when the project has an `oxfmt.config.*` file (see [Standalone oxfmt](#standalone-oxfmt)).           |
 | `-- <args>`                    | Forward args to the single selected tool (needs `--eslint`/`--oxlint`).                                                            |
 | `-h`, `--help`                 | Show help.                                                                                                                         |
 | `-v`, `--version`              | Show the version.                                                                                                                  |
@@ -394,6 +411,7 @@ or `--`.
 | `FILES_PER_WORKER`      | Target files a single type-aware ESLint worker handles before adding another (default `350`).                        |
 | `FAST_FILES_PER_WORKER` | Same, for the fast (syntactic) pass, which packs far more files per worker (default `800`).                          |
 | `LINT_MAX_WORKERS`      | Upper bound on ESLint workers (default a quarter of available CPUs).                                                 |
+| `LINT_TYPED_HEAP_MB`    | Heap per worker for the program-building ESLint children: `auto` (default), a size in MB, or `off` (Node's default). |
 | `ESLINT_TYPE_AWARE`     | `off` or `only`; the type-aware mode `--type-aware` sets for the ESLint child (`false` is a legacy alias for `off`). |
 | `CI`                    | When set, the runner uses the single full pass with `--cache-strategy content` (see below).                          |
 
@@ -932,6 +950,103 @@ pnpm i -D oxlint oxlint-tsgolint
 See [docs/oxlint.md](./docs/oxlint.md) for the per-rule mapping, what stays in
 ESLint and why, and migration notes.
 
+#### Standalone oxfmt
+
+By default, oxfmt runs inside the linter as the `oxfmt/oxfmt` rule. To run it as
+its own tool (`oxfmt`, editor format-on-save through the oxc extension), set
+`formatter: "standalone"` in both factories and add an `oxfmt.config.ts` built
+from the preset:
+
+```ts
+// oxfmt.config.ts
+import { isentinelOxfmt } from "@isentinel/eslint-config/oxfmt";
+
+export default isentinelOxfmt({ cwd: import.meta.dirname, printWidth: 100 });
+```
+
+```ts
+// eslint.config.ts
+import isentinel from "@isentinel/eslint-config";
+
+export default isentinel({
+	formatter: "standalone",
+});
+```
+
+`isentinelOxfmt` starts from the same options the linter uses (preset defaults,
+then `.editorconfig`, then `.prettierrc`). Each key you pass replaces its base
+value, except `ignorePatterns` and `overrides`, which are appended to the
+preset's. The override order is the one the `oxfmt/oxfmt` rule uses: the
+preset's Markdown, YAML and JSON5 overrides, then the `.editorconfig` sections
+(without keys you set at the root), then yours, then the `.prettierrc`
+`overrides`. Override globs without a slash are anchored to the config directory
+(`*.json` becomes `./*.json`), because the rule matches them only there. `cwd`
+is the directory to read `.prettierrc` and `.editorconfig` from (default
+`process.cwd()`). Pass `import.meta.dirname`, as the wizard does, so the result
+does not depend on where oxfmt runs.
+
+`isentinelOxfmt` takes `formatters` and `componentExts`, with the same meaning
+as in the factories, so oxfmt formats the same files the linter would. TOML,
+`.mdx` and other files the linter does not format are ignored.
+
+In standalone mode, oxfmt never sees the linter's options. The factories warn
+once per lint run when you set any of these, because they do not change
+formatting: `formatters` (any value except `true`), `componentExts`, `ignores`,
+or `gitignore` (`false` or custom files). Set the equivalent in `isentinelOxfmt`
+instead (`formatters`, `componentExts`, `ignorePatterns`, and format options).
+`stylistic: false` turns off the stylistic lint rules but not oxfmt. The rule
+widths also come from the oxfmt config only, not from
+`formatters.prettierOptions` or `formatters.oxfmtOptions`. The setup wizard
+copies migrated `.eslintignore` patterns to both configs.
+
+With `formatter: "standalone"`, the linter enables `oxfmt/oxfmt` nowhere but
+keeps the rules that turn off formatting conflicts. Lua formatting (Stylua)
+stays in ESLint, because oxfmt does not format Lua. The setup wizard can write
+all of this for you.
+
+`isentinel-lint` runs `oxfmt --check` next to the linters whenever it finds an
+`oxfmt.config.ts` or `oxfmt.config.mts`, and `oxfmt --write` last with `--fix`.
+It does this whatever the `formatter` option is, so set
+`formatter: "standalone"` with such a file, or the files are formatted twice.
+Pass `--no-oxfmt` to skip the pass.
+
+Both factories read the oxfmt config that oxfmt itself uses: `.oxfmtrc.json`,
+`.oxfmtrc.jsonc`, `oxfmt.config.ts` or `oxfmt.config.mts`, in the nearest
+directory from the working directory up to the filesystem root. More than one of
+them in one directory is an error, as in oxfmt. Its root options (without
+`ignorePatterns` and `overrides`) override `formatters.prettierOptions`, and
+`formatters.oxfmtOptions` overrides them.
+
+Nested oxfmt configs (a config file in a subdirectory) are not used, in either
+mode. One root config formats the whole project: the `oxfmt/oxfmt` rule sets
+`disableNestedConfig`, `isentinel-lint` passes `--config`, the wizard's format
+scripts pass `--disable-nested-config`, and its VS Code settings set
+`oxc.fmt.disableNestedConfig`. Use `overrides` for per-folder options. The same
+holds for `.editorconfig`: only the nearest one at or above the root config is
+read, so a `.editorconfig` in a subdirectory does not change formatting.
+
+`flawless/arrow-return-style` uses two widths. `maxLen` is your limit: an arrow
+becomes implicit only if it fits. It comes from `stylistic.maxLen`, else
+`printWidth`, and it can be shorter than the formatter width on purpose.
+`useOxfmt.printWidth` is the width the rule gives oxfmt to predict its output.
+It always comes from the root `printWidth` of the oxfmt config, so that `--fix`
+agrees with oxfmt. An override that changes `printWidth` or `tabWidth` for JS or
+TS files gets a warning, because the linter uses the root values. In Markdown
+code blocks, `useOxfmt` uses the Markdown widths instead, because oxfmt formats
+embedded code with the Markdown options. Each oxfmt, `.editorconfig` or
+`.prettierrc` override that changes the Markdown widths reaches only the code
+blocks of the files it matches. The comment length rules take their `tabSize`
+from the same oxfmt widths.
+
+The stylistic `indent` and `quotes`, and the JSON bracket spacing, follow the
+oxfmt options (`useTabs`, `tabWidth`, `singleQuote`, `bracketSpacing`) unless
+you set them in `stylistic`.
+
+Both modes write the same output, with one known difference: when one import
+merges into another (`import/no-duplicates`), eslint mode sorts the imports
+before the merge and standalone mode after it, so comments above the merged
+import can end in a different order.
+
 #### Type-Aware Split
 
 On large projects the type-aware rules dominate ESLint wall time; an explicit

package/dist/cli.mjs

@@ -1,15 +1,89 @@
-import { cancel, confirm, group, intro, log, multiselect, note, outro } from "@clack/prompts";
+import { createRequire } from "node:module";
+import { cancel, confirm, group, intro, log, multiselect, note, outro, select } from "@clack/prompts";
 import ansis from "ansis";
 import process from "node:process";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import "find-up-simple";
+import "jsonc-eslint-parser";
+import "local-pkg";
 import fs from "node:fs";
-import fsp from "node:fs/promises";
 import path from "node:path";
+import "semver";
+import fsp from "node:fs/promises";
 import { existsSync, readFileSync } from "fs";
 import { execSync } from "node:child_process";
+//#region src/guards.ts
+/**
+* Internal runtime type guards. Prefer these over `as` assertions so values
+* crossing untyped boundaries (`JSON.parse`, dynamic `import`, plugin objects)
+* are validated at runtime rather than asserted away.
+*/
+/**
+* Whether a value is a non-null, non-array object usable as a string-keyed
+* record. Narrows `unknown` without an assertion.
+*
+* @param value - The value to test.
+* @returns Whether the value is a plain object.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Whether a value is an array whose every element is a string.
+*
+* @param value - The value to test.
+* @returns Whether the value is a `string` array.
+*/
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+createRequire(import.meta.url);
+environmentMatcher("PATH", /\.pi[/\\]agent/), environmentMatcher("EDITOR", /devin/), environmentMatcher("TERM_PROGRAM", /kiro/, { noTty: true });
+/**
+* Build a probe that regex-tests one environment variable, for the agents that
+* announce themselves inside a variable a human also sets.
+*
+* `noTty` marks a variable an interactive user shares with the agent (kiro's
+* `TERM_PROGRAM` is set in its terminal too): an attached stdout TTY means a
+* person is watching, so the probe declines.
+*
+* @param name - The environment variable to test.
+* @param pattern - The pattern the value must match.
+* @param options - Probe options.
+* @param options.noTty - Whether an attached stdout TTY disqualifies the match.
+* @returns The probe.
+*/
+function environmentMatcher(name, pattern, { noTty = false } = {}) {
+	return (environment) => {
+		if (noTty && process.stdout.isTTY) return false;
+		const value = environment[name];
+		return value !== void 0 && pattern.test(value);
+	};
+}
+/** JSON oxfmt config files oxfmt discovers. */
+const OXFMT_RC_FILES = [".oxfmtrc.json", ".oxfmtrc.jsonc"];
+/**
+* Oxfmt config modules oxfmt discovers. It loads other module extensions only
+* through `--config`, never by search.
+*/
+const OXFMT_CONFIG_MODULES = ["oxfmt.config.ts", "oxfmt.config.mts"];
+/** The config module the standalone setup writes. */
+const OXFMT_CONFIG_MODULE = OXFMT_CONFIG_MODULES[0];
+/** Every file name oxfmt discovers. One directory may hold only one of them. */
+const OXFMT_CONFIG_NAMES = [...OXFMT_RC_FILES, ...OXFMT_CONFIG_MODULES];
+/**
+* List the oxfmt config files in one directory, without walking up.
+*
+* @param directory - Directory to check.
+* @returns The file names found, sorted.
+*/
+function oxfmtConfigNamesIn(directory) {
+	return OXFMT_CONFIG_NAMES.filter((name) => fs.existsSync(path.join(directory, name))).sort();
+}
+//#endregion
 //#region package.json
-var version = "6.0.1";
+var version = "6.2.0";
 var package_default = {
 	name: "@isentinel/eslint-config",
 	version,
@@ -43,6 +117,10 @@ var package_default = {
 			"default": "./dist/index.mjs"
 		},
 		"./formatter-agents": "./dist/formatter-agents.mjs",
+		"./oxfmt": {
+			"types": "./dist/oxfmt.d.mts",
+			"default": "./dist/oxfmt.mjs"
+		},
 		"./oxlint": {
 			"types": "./dist/oxlint.d.mts",
 			"default": "./dist/oxlint.mjs"
@@ -73,6 +151,7 @@ var package_default = {
 		"release": "bumpp -r",
 		"stub": "tsdown",
 		"test": "nr gen && vitest run",
+		"test:parity": "vitest run --config vitest.parity.config.ts",
 		"test:watch": "vitest",
 		"typecheck": "tsc --noEmit",
 		"validate:oxlint": "node scripts/validate-oxlint.ts",
@@ -122,6 +201,7 @@ var package_default = {
 		"file-entry-cache": "catalog:prod",
 		"find-up-simple": "catalog:prod",
 		"globals": "catalog:prod",
+		"jiti": "catalog:prod",
 		"jsonc-eslint-parser": "catalog:prod",
 		"local-pkg": "catalog:prod",
 		"oxfmt": "catalog:prod",
@@ -161,7 +241,6 @@ var package_default = {
 		"eslint-plugin-react-x": "catalog:peer",
 		"eslint-plugin-testing-library": "catalog:peer",
 		"eslint-typegen": "catalog:dev",
-		"jiti": "catalog:dev",
 		"oxlint": "catalog:peer",
 		"oxlint-tsgolint": "catalog:peer",
 		"parse-gitignore-ts": "catalog:dev",
@@ -208,11 +287,43 @@ var package_default = {
 };
 //#endregion
 //#region src/cli/constants.ts
-const vscodeSettingsString = `
+/** The VS Code extension that runs oxfmt. */
+const OXC_VSCODE_EXTENSION = "oxc.oxc-vscode";
+/** Languages oxfmt formats on save in the standalone setup. */
+const OXFMT_LANGUAGES = [
+	"css",
+	"graphql",
+	"html",
+	"javascript",
+	"javascriptreact",
+	"json",
+	"jsonc",
+	"less",
+	"markdown",
+	"scss",
+	"typescript",
+	"typescriptreact",
+	"yaml"
+];
+const eslintFormatterSettings = `
   // Disable the default formatter, use eslint instead
   "prettier.enable": false,
   "editor.formatOnSave": false,
-
+`;
+const standaloneFormatterSettings = `
+  // Format with oxfmt; eslint only lints
+  "prettier.enable": false,
+  "eslint.format.enable": false,
+  // One root oxfmt config, as the CLI and lint runs use
+  "oxc.fmt.disableNestedConfig": true,
+${OXFMT_LANGUAGES.map((language) => {
+	return `  "[${language}]": {
+    "editor.defaultFormatter": "${OXC_VSCODE_EXTENSION}",
+    "editor.formatOnSave": true
+  },`;
+}).join("\n")}
+`;
+const lintSettings = `
   // Auto fix
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "explicit",
@@ -246,6 +357,36 @@ const vscodeSettingsString = `
 	  "luau"
   ]
 `;
+/**
+* The VS Code settings the wizard adds, as the body of a JSON object.
+*
+* @param formatter - Where formatting runs.
+* @returns The settings text.
+*/
+function vscodeSettingsString(formatter = "eslint") {
+	return `${formatter === "standalone" ? standaloneFormatterSettings : eslintFormatterSettings}${lintSettings}`;
+}
+const formatterOptions = [{
+	hint: "oxfmt runs as an ESLint rule",
+	label: "ESLint",
+	value: "eslint"
+}, {
+	hint: `oxfmt runs as its own tool, with ${OXFMT_CONFIG_MODULE}`,
+	label: "Standalone oxfmt",
+	value: "standalone"
+}];
+/**
+* The {@link OXFMT_CONFIG_MODULE} the standalone setup writes.
+*
+* @param ignorePatterns - Patterns oxfmt should skip, as in ESLint `ignores`.
+* @returns The module source.
+*/
+function oxfmtConfigContent(ignorePatterns = []) {
+	return `import { isentinelOxfmt } from "@isentinel/eslint-config/oxfmt";
+
+export default isentinelOxfmt({ cwd: import.meta.dirname${ignorePatterns.length > 0 ? `, ignorePatterns: ${JSON.stringify(ignorePatterns)}` : ""} });
+`;
+}
 const frameworkOptions = [{
 	label: ansis.red("Test"),
 	value: "test"
@@ -263,17 +404,6 @@ const dependenciesMap = {
 	test: ["eslint-plugin-jest"]
 };
 //#endregion
-//#region src/guards.ts
-/**
-* Whether a value is an array whose every element is a string.
-*
-* @param value - The value to test.
-* @returns Whether the value is a `string` array.
-*/
-function isStringArray(value) {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-//#endregion
 //#region ../../../setup-pnpm/node_modules/.bin/store/v11/links/@/parse-gitignore-ts/1.0.0/0cdd402c09c3520e4b8d62a0e9eaf59ef70b71773d70a71b070a2cf3609765b8/node_modules/parse-gitignore-ts/dist/index.mjs
 var isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 var INVALID_PATH_CHARS_REGEX = /[<>:"|?*\n\r\t\f\x00-\x1F]/;
@@ -523,9 +653,18 @@ async function updateEslintFiles(result) {
 	const configLines = [];
 	if (eslintIgnores.length) configLines.push(`ignores: ${JSON.stringify(eslintIgnores)},`);
 	for (const framework of result.frameworks) configLines.push(`${framework}: true,`);
+	if (result.formatter === "standalone") configLines.push("formatter: \"standalone\",");
 	const eslintConfigContent = getEslintConfigContent(configLines.map((index) => `  ${index}`).join("\n"), []);
 	await fsp.writeFile(pathFlatConfig, eslintConfigContent);
 	log.success(ansis.green(`Created ${configFileName}`));
+	if (result.formatter === "standalone") {
+		const [existing] = oxfmtConfigNamesIn(cwd);
+		if (existing !== void 0) log.warn(ansis.yellow(`${existing} already exists, left unchanged.`));
+		else {
+			await fsp.writeFile(path.join(cwd, OXFMT_CONFIG_MODULE), oxfmtConfigContent(eslintIgnores));
+			log.success(ansis.green(`Created ${OXFMT_CONFIG_MODULE}`));
+		}
+	}
 	const files = fs.readdirSync(cwd);
 	const legacyConfig = [];
 	for (const file of files) if (LEGACY_CONFIG_REGEX.test(file) && !file.includes("eslint.config.")) legacyConfig.push(file);
@@ -538,7 +677,8 @@ const versionsMap = {
 	"eslint-plugin-jest": "29.16.0",
 	"eslint-plugin-react-jsx": "5.17.3",
 	"eslint-plugin-react-naming-convention": "5.17.3",
-	"eslint-plugin-react-x": "5.17.3"
+	"eslint-plugin-react-x": "5.17.3",
+	"oxfmt": "0.72.0"
 };
 //#endregion
 //#region src/cli/stages/update-package-json.ts
@@ -547,20 +687,28 @@ const LINT_SCRIPTS = {
 	"lint": "isentinel-lint",
 	"lint:fix": "isentinel-lint --fix"
 };
+/** Scripts the standalone formatter setup adds, so oxfmt runs on its own. */
+const FORMAT_SCRIPTS = {
+	"format": "oxfmt --disable-nested-config",
+	"format:check": "oxfmt --check --disable-nested-config"
+};
 /**
-* Merge the lint scripts into a `scripts` block in place. Missing scripts are
-* always added. An existing script with identical content is left untouched. An
-* existing script with different content is preserved in skip-prompt mode, and
-* otherwise only overwritten when {@link ConfirmOverwrite} resolves true.
+* Merge the lint scripts (or `options.desired`) into a `scripts` block in
+* place. Missing scripts are always added. An existing script with identical
+* content is left untouched. An existing script with different content is
+* preserved in skip-prompt mode, and otherwise only overwritten when
+* {@link ConfirmOverwrite} resolves true.
 *
 * @param scripts - The consumer's `scripts` block, mutated in place.
-* @param options - Skip-prompt flag and the overwrite confirmation callback.
+* @param options - Skip-prompt flag, the overwrite confirmation callback and
+*   the scripts to merge (default {@link LINT_SCRIPTS}).
 * @returns Which scripts were added and which were overwritten.
 */
-async function mergeLintScripts(scripts, options) {
+async function mergeScripts(scripts, options) {
 	const added = [];
 	const overwritten = [];
-	for (const [name, desired] of Object.entries(LINT_SCRIPTS)) {
+	const entries = Object.entries(options.desired ?? LINT_SCRIPTS);
+	for (const [name, desired] of entries) {
 		const existing = scripts[name];
 		if (existing === void 0) {
 			scripts[name] = desired;
@@ -587,6 +735,7 @@ async function updatePackageJson(result, skipPrompt = false) {
 	parsedPackage.devDependencies ??= {};
 	parsedPackage.devDependencies["@isentinel/eslint-config"] = `^${version}`;
 	parsedPackage.devDependencies["eslint"] ??= versionsMap.eslint;
+	if (result.formatter === "standalone") parsedPackage.devDependencies["oxfmt"] ??= versionsMap.oxfmt;
 	const addedPackages = [];
 	for (const framework of result.frameworks) {
 		if (!(framework in dependenciesMap)) continue;
@@ -599,17 +748,21 @@ async function updatePackageJson(result, skipPrompt = false) {
 	if (addedPackages.length) note(ansis.dim(addedPackages.join(", ")), "Added packages");
 	parsedPackage.scripts ??= {};
 	const { scripts = {} } = parsedPackage;
-	const { added, overwritten } = await mergeLintScripts(scripts, {
+	const { added, overwritten } = await mergeScripts(scripts, {
 		confirmOverwrite: async (name, existing, desired) => {
 			return await confirm({
 				initialValue: false,
 				message: `A "${name}" script already exists ("${existing}"). Overwrite it with "${desired}"?`
 			}) === true;
 		},
+		desired: result.formatter === "standalone" ? {
+			...LINT_SCRIPTS,
+			...FORMAT_SCRIPTS
+		} : LINT_SCRIPTS,
 		skipPrompt
 	});
 	const touched = [...added, ...overwritten];
-	if (touched.length) note(ansis.dim(touched.map((name) => `${name}: ${scripts[name]}`).join("\n")), "Lint scripts");
+	if (touched.length) note(ansis.dim(touched.map((name) => `${name}: ${scripts[name]}`).join("\n")), "Scripts");
 	await fsp.writeFile(pathPackageJSON, JSON.stringify(parsedPackage, null, 2));
 	log.success(ansis.green("Changes wrote to package.json"));
 }
@@ -617,22 +770,55 @@ async function updatePackageJson(result, skipPrompt = false) {
 //#region src/cli/stages/update-vscode-settings.ts
 async function updateVscodeSettings(result) {
 	if (!result.updateVscodeSettings) return;
+	const settings = vscodeSettingsString(result.formatter);
 	const cwd = process.cwd();
 	const dotVscodePath = path.join(cwd, ".vscode");
 	const settingsPath = path.join(dotVscodePath, "settings.json");
 	if (!fs.existsSync(dotVscodePath)) await fsp.mkdir(dotVscodePath, { recursive: true });
 	if (!fs.existsSync(settingsPath)) {
-		await fsp.writeFile(settingsPath, `{${vscodeSettingsString}}\n`, "utf-8");
+		await fsp.writeFile(settingsPath, `{${settings}}\n`, "utf-8");
 		log.success(ansis.green("Created .vscode/settings.json"));
+		await recommendExtensions(dotVscodePath, result);
 		return;
 	}
 	let settingsContent = await fsp.readFile(settingsPath, "utf8");
 	settingsContent = settingsContent.trim();
 	if (settingsContent.endsWith("}")) settingsContent = settingsContent.slice(0, -1).trimEnd();
 	settingsContent += settingsContent.endsWith(",") || settingsContent.endsWith("{") ? "" : ",";
-	settingsContent += `${vscodeSettingsString}}\n`;
+	settingsContent += `${settings}}\n`;
 	await fsp.writeFile(settingsPath, settingsContent, "utf-8");
 	log.success(ansis.green("Updated .vscode/settings.json"));
+	await recommendExtensions(dotVscodePath, result);
+}
+/**
+* Add the oxc extension to `.vscode/extensions.json` for the standalone
+* formatter setup. A file that is not plain JSON is left alone with a warning.
+*
+* @param dotVscodePath - The `.vscode` directory.
+* @param result - The prompt result.
+*/
+async function recommendExtensions(dotVscodePath, result) {
+	if (result.formatter !== "standalone") return;
+	const extensionsPath = path.join(dotVscodePath, "extensions.json");
+	let extensions = {};
+	if (fs.existsSync(extensionsPath)) {
+		let parsed;
+		try {
+			parsed = JSON.parse(await fsp.readFile(extensionsPath, "utf8"));
+		} catch {
+			parsed = void 0;
+		}
+		if (!isRecord(parsed)) {
+			log.warn(ansis.yellow(`Could not read .vscode/extensions.json; add "${OXC_VSCODE_EXTENSION}" to its recommendations manually.`));
+			return;
+		}
+		extensions = parsed;
+	}
+	const recommendations = isStringArray(extensions["recommendations"]) ? extensions["recommendations"] : [];
+	if (recommendations.includes("oxc.oxc-vscode")) return;
+	extensions["recommendations"] = [...recommendations, OXC_VSCODE_EXTENSION];
+	await fsp.writeFile(extensionsPath, `${JSON.stringify(extensions, null, 2)}\n`, "utf-8");
+	log.success(ansis.green("Recommended the oxc extension in .vscode/extensions.json"));
 }
 //#endregion
 //#region src/cli/run.ts
@@ -646,13 +832,15 @@ async function run(options = {}) {
 		log.warn(ansis.yellow(`${eslintConfigFiles[0]} already exists, migration wizard exited.`));
 		return process.exit(1);
 	}
+	const argumentFormatter = formatterOptions.find(({ value }) => value === options.formatter)?.value;
 	let result = {
+		formatter: argumentFormatter ?? "eslint",
 		frameworks: argumentTemplate ?? [],
 		uncommittedConfirmed: false,
 		updateVscodeSettings: true
 	};
 	if (argumentSkipPrompt !== true) {
-		const { frameworks: groupedFrameworks, uncommittedConfirmed, updateVscodeSettings: shouldUpdateVscode } = await group({
+		const { formatter: groupedFormatter, frameworks: groupedFrameworks, uncommittedConfirmed, updateVscodeSettings: shouldUpdateVscode } = await group({
 			uncommittedConfirmed: async () => {
 				if (isGitClean()) return true;
 				return confirm({
@@ -660,6 +848,14 @@ async function run(options = {}) {
 					message: "There are uncommitted changes in the current repository, are you sure to continue?"
 				});
 			},
+			formatter: async ({ results }) => {
+				if (argumentFormatter !== void 0 || results.uncommittedConfirmed !== true) return;
+				return select({
+					initialValue: "eslint",
+					message: "Where should formatting run?",
+					options: formatterOptions
+				});
+			},
 			frameworks: async ({ results }) => {
 				if ((argumentTemplate && argumentTemplate.length > 0 && argumentTemplate.every((template) => frameworks.includes(template))) === true || results.uncommittedConfirmed !== true) return;
 				const message = argumentTemplate && argumentTemplate.length > 0 ? `"${argumentTemplate.join(", ")}" isn't a valid template. Please choose from below: ` : "Select a framework:";
@@ -681,6 +877,7 @@ async function run(options = {}) {
 			process.exit(0);
 		} });
 		result = {
+			formatter: argumentFormatter ?? (groupedFormatter === "standalone" ? "standalone" : "eslint"),
 			frameworks: isStringArray(groupedFrameworks) ? groupedFrameworks.filter((value) => {
 				return frameworks.some((option) => option === value);
 			}) : [],
@@ -708,6 +905,10 @@ yargs(hideBin(process.argv)).scriptName("@isentinel/eslint-config").usage("").co
 		alias: "y",
 		description: "Skip prompts and use default values",
 		type: "boolean"
+	}).option("formatter", {
+		choices: ["eslint", "standalone"],
+		description: "Where formatting runs: in ESLint, or oxfmt on its own",
+		type: "string"
 	}).option("template", {
 		alias: "t",
 		description: "Use the framework template for optimal customization: react, jest",