@utoo/lint 0.2.8 → 0.3.4

package/README.md

@@ -2,252 +2,239 @@
 
 ![utoo-lint logo](assets/utoo-lint-logo.svg)
 
-High performance linter for JavaScript and TypeScript written by Zig.
+[![npm version](https://img.shields.io/npm/v/%40utoo%2Flint?logo=npm)](https://www.npmjs.com/package/@utoo/lint)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![CI](https://github.com/utooland/utoo-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/utooland/utoo-lint/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/utooland/utoo-lint)](https://github.com/utooland/utoo-lint/blob/main/LICENSE)
 
-## Install
+A high-performance linter for JavaScript and TypeScript, written in Zig and
+powered by [Yuku](https://github.com/yuku-toolchain/yuku).
 
-```bash
-pnpm add -D @utoo/lint
-```
+`@utoo/lint` combines a native lint engine with familiar configuration, CLI,
+and JavaScript APIs.
 
-## CLI
+[Installation](#installation) · [Quick start](#quick-start) ·
+[Rules](https://github.com/utooland/utoo-lint/blob/main/docs/rule-status.md) ·
+[Configuration](https://github.com/utooland/utoo-lint/blob/main/docs/configuration.md) ·
+[GitHub](https://github.com/utooland/utoo-lint)
 
-Run the linter with:
+## Why utoo-lint?
 
-```bash
-pnpm exec utoo-lint src
-```
+- **Native performance** — Zig and Yuku power parsing, semantic analysis, and
+  parallel file linting.
+- **Broad rule coverage** — More than 300 rules cover JavaScript, TypeScript,
+  React, JSX accessibility, and imports.
+- **Familiar configuration** — Use typed `utlint.config.ts` or static
+  `utlint.config.json`, with ESLint-style rule names and severities.
+- **Practical workflows** — Safe autofix, suppression comments, JSON output,
+  and ESM/CommonJS APIs are included.
+- **Portable installation** — Prebuilt binaries are available for macOS,
+  Linux, and Windows on supported architectures.
 
-If no target is provided, `utoo-lint` uses `files` from the selected
-`utlint.config.ts` or `utlint.config.json`. When no config file or `files` entry
-exists, it scans the current directory. It skips `.git`, `.zig-cache`,
-`node_modules`, `vendor`, and `zig-out`.
+## Installation
 
-Use a config file:
+`@utoo/lint` requires Node.js 20 or later.
 
-```bash
-pnpm exec utoo-lint --config=utlint.config.json src
-```
+### utoo
 
-Run a focused rule set:
+[utoo](https://utoo.land/en/docs/utoo) is a fast, npm-compatible package
+manager written in Rust. Install it once if it is not already available:
 
 ```bash
-pnpm exec utoo-lint --rules=no-debugger,no-console src
+npm install -g utoo
 ```
 
-Use machine-readable output:
+Add `@utoo/lint` as a development dependency:
 
 ```bash
-pnpm exec utoo-lint --format=json src
+ut install @utoo/lint -D
 ```
 
-The default terminal output groups diagnostics by file, aligns their location
-and severity, and summarizes errors and warnings separately. Color is detected
-automatically; pass `--color` to force it or `--no-color` to disable it. JSON
-output remains stable for editor and CI integrations.
-
-## Autofix
+In an existing project, run `ut install` without a package name to install all
+dependencies declared in `package.json`.
 
-Apply safe fixes from all enabled rules that support autofix:
+### Other package managers
 
 ```bash
-pnpm exec utoo-lint --fix src
+pnpm add -D @utoo/lint
+npm install --save-dev @utoo/lint
 ```
 
-Preview the result without changing files:
+The package selects the native binary for the current platform. No Zig
+toolchain is required.
+
+## Quick start
+
+### Run with the default rules
 
 ```bash
-pnpm exec utoo-lint --fix-dry-run --format=json src
+utx @utoo/lint src
 ```
 
-`--fix` writes fixed source back to disk. `--fix-dry-run` never writes files;
-with JSON output, changed sources are returned in the `outputs` array. Fixes run
-until the source is stable, subject to a safety pass limit. Diagnostics remain
-when a rule or a particular code shape cannot be fixed safely. The current
-[rule status](https://github.com/fireairforce/utoo-lint/blob/main/docs/rule-status.md)
-lists autofix coverage by rule.
+Without a config file, `utoo-lint` uses its built-in default rules. It supports
+`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, and `.cts` files.
 
-## Suppression comments
+### Add a typed config
 
-Suppress a rule for the next line of code with `utlint-ignore`:
+Create `utlint.config.ts`:
 
-```js
-// utlint-ignore no-debugger: generated breakpoint
-debugger;
-```
+```ts
+import { defineConfig } from "@utoo/lint/config";
+import frontend from "@utoo/lint/configs/frontend";
 
-Omit the rule ID to suppress all lint rules for the next line of code. Use
-`utlint-ignore-all` before any code for a file-level suppression, or matching
-`utlint-ignore-start` and `utlint-ignore-end` comments for a range. Line and
-block comments are supported. Parse errors remain visible, and fixes from
-suppressed diagnostics are not applied.
+export default defineConfig({
+  ...frontend,
+  ignores: [...frontend.ignores, ".next", "storybook-static"],
+  rules: {
+    ...frontend.rules,
+    "no-console": "off",
+    "react/no-forward-ref": "off"
+  }
+});
+```
 
-Native reports expose suppressed items in `suppressedDiagnostics`; the ESLint
-compatibility API exposes them in `suppressedMessages`.
+The frontend preset uses `error` for correctness and safety checks that should
+fail CI, and `warn` for migration or maintainability checks that should remain
+visible without blocking adoption:
 
-## Configuration
+| Severity | Added frontend guardrails |
+| --- | --- |
+| `error` | `react-hooks/rules-of-hooks`, `react/jsx-key`, `react/no-children-prop`, `react/no-danger-with-children`, `react/void-dom-elements-no-children`, `no-script-url`, `promise/no-nesting` |
+| `warn` | `react-hooks/exhaustive-deps`, `react/no-array-index-key`, `react/no-unstable-nested-components`, `react/no-forward-ref`, `unused-imports/no-unused-imports`, `@typescript-eslint/no-unused-vars`, `@typescript-eslint/ban-types` |
 
-`utoo-lint` supports two canonical project config formats:
+Override project-specific rules after spreading `frontend.rules`, and append
+framework-generated directories to `frontend.ignores`, as shown above.
 
-| Config | Use it when | Raw native binary |
-| --- | --- | --- |
-| `utlint.config.ts` | You want typed authoring, imports, or computed values. | No |
-| `utlint.config.json` | You want a static, runtime-independent config. | Yes |
+The preset intentionally enables no formatter or type-checker integration.
+Keep Prettier (or another formatter) and `tsc` as independent project steps.
 
-The npm CLI discovers either format automatically. It can also select one
-explicitly:
+The CLI discovers the config and uses its `files` patterns:
 
 ```bash
-pnpm exec utoo-lint --config=utlint.config.ts src
-pnpm exec utoo-lint --config=utlint.config.json src
+utx @utoo/lint
 ```
 
-For a static config readable by both the npm CLI and raw native binary, create
-`utlint.config.json`:
+See the
+[configuration guide](https://github.com/utooland/utoo-lint/blob/main/docs/configuration.md)
+for flat config arrays, global ignores, rule options, and config precedence.
+
+### Add package scripts
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/fireairforce/utoo-lint/main/npm/utoo-lint/schema.json",
-  "files": ["src/**/*.{js,jsx,ts,tsx}"],
-  "ignores": ["dist", "node_modules"],
-  "rules": {
-    "no-console": "off",
-    "no-debugger": "error"
+  "scripts": {
+    "lint": "utoo-lint src",
+    "lint:fix": "utoo-lint --fix src"
   }
 }
 ```
 
-For a typed config executed by the npm/Node CLI, create `utlint.config.ts`:
+With utoo, run these scripts as `ut lint` and `ut lint:fix`.
 
-```ts
-import { defineConfig } from "@utoo/lint/config";
+## Common commands
 
-export default defineConfig({
-  files: ["src/**/*.{js,jsx,ts,tsx}"],
-  ignores: ["dist", "node_modules"],
-  rules: {
-    "no-console": "off",
-    "no-debugger": "error"
-  }
-});
-```
+| Task | Command |
+| --- | --- |
+| Lint files | `utx @utoo/lint src` |
+| Apply safe fixes | `utx @utoo/lint --fix src` |
+| Preview fixes as JSON | `utx @utoo/lint --fix-dry-run --format=json src` |
+| Select rules for one run | `utx @utoo/lint --rules=no-debugger,no-unused-vars src` |
+| Use an explicit config | `utx @utoo/lint --config=utlint.config.json src` |
 
-The packaged frontend preset is also available as a typed config import:
+Run `utx @utoo/lint --help` for all CLI options.
 
-```ts
-import { defineConfig } from "@utoo/lint/config";
-import frontend from "@utoo/lint/configs/frontend";
+## Configuration
 
-export default defineConfig({
-  ...frontend,
-  rules: {
-    ...frontend.rules,
-    "no-console": "off",
-  },
-});
-```
+`utoo-lint` supports two canonical config formats. They are alternative
+representations of one active config and are not merged together.
 
-Use `globalIgnores()` as a separate config entry when files or directories
-must be excluded from every entry:
+| Config | Best for | Raw native binary |
+| --- | --- | --- |
+| `utlint.config.ts` | Typed authoring, imports, presets, and computed values | No |
+| `utlint.config.json` | Static configuration and JSON Schema validation | Yes |
 
-```ts
-import { defineConfig, globalIgnores } from "@utoo/lint/config";
-
-export default defineConfig(
-  globalIgnores(["dist/", ".next/", "**/generated/"]),
-  {
-    files: ["**/*.{js,jsx,ts,tsx}"],
-    rules: {
-      "no-debugger": "error"
-    }
-  }
-);
+Rule severities follow ESLint conventions: `off`, `warn`, `error`, `0`, `1`,
+and `2`. A selected config enables only the rules present in its resolved
+`rules` map.
+
+The npm CLI and JavaScript API load both formats. The raw native binary loads
+JSON only. See the
+[configuration guide](https://github.com/utooland/utoo-lint/blob/main/docs/configuration.md)
+for the complete behavior.
+
+## Autofix
+
+Apply safe fixes in place:
+
+```bash
+utx @utoo/lint --fix src
 ```
 
-`globalIgnores()` returns an ignore-only object containing `ignores` and a
-generated `name`. Only such global entries prune directories during target
-discovery. By contrast, `ignores` beside `files`, `rules`, or another config
-key is entry-scoped: it prevents that entry from applying to matching files,
-but does not exclude them from other entries. With no CLI targets, global
-ignores filter the config's `files` patterns, or the current-directory scan
-when no `files` are configured. Directory patterns such as `dist/` and
-`.next/` are relative to the config; use `**/generated/` to match at any depth.
-This intentionally follows [ESLint flat config ignore semantics](https://eslint.org/docs/latest/use/configure/ignore).
-
-The two canonical names represent one active config and are not implicitly
-merged. For the npm/Node entry point, discovery is nearest-directory-first.
-Within the same directory, `utlint.config.ts` takes precedence over
-`utlint.config.json`; deprecated `utoo.json` and `utoo-lint.json` files are
-checked afterward for temporary backward compatibility. Rule-related CLI
-options such as `--rules`, individual rule toggles, and fishlint's `--rule` are
-applied after the selected config.
-
-Project-config `files` and `ignores` patterns are relative to the selected
-config file's directory. In a flat config array, they select the entries that
-apply to each file; matching entries are combined in order and later rule
-values override earlier values. The npm CLI, JavaScript API, and fishlint
-compatibility command perform this rule resolution per file.
-
-TypeScript config is trusted executable code. Its default export must be a
-JSON-serializable object or flat config array. The npm wrapper executes it and
-materializes the result as JSON before invoking the native binary. The raw
-binary does not execute or discover TypeScript; it searches for
-`utlint.config.json` and then the legacy JSON names. Direct native use therefore
-requires a JSON config. The raw binary applies only its `rules`;
-config-driven `files` and `ignores` filtering and default target selection are
-npm/Node wrapper features. Pass lint targets explicitly when invoking the raw
-binary. As in ESLint, selecting a config disables rules not present in its
-resolved `rules` map. When no config is selected, utoo-lint uses its built-in
-default rules.
-
-Rule severities use ESLint's exit behavior: warnings are reported with exit
-status 0, while errors return exit status 1. Use fishlint's `--max-warnings`
-option when warnings should fail CI.
-
-Start from the packaged frontend template:
+Preview fixes without writing files:
 
 ```bash
-cp node_modules/@utoo/lint/configs/frontend.json utlint.config.json
+utx @utoo/lint --fix-dry-run --format=json src
 ```
 
-## ESLint Migration
+Fixes run until the source is stable, subject to a safety pass limit. The
+[rule status](https://github.com/utooland/utoo-lint/blob/main/docs/rule-status.md)
+documents autofix support for each rule.
 
-Convert an existing ESLint config into the native utoo format:
+## Suppression comments
 
-```bash
-pnpm exec utoo-lint migrate eslint --from eslint.config.js --output utlint.config.json
+Use suppression comments for intentional exceptions without disabling a rule
+in project configuration:
+
+```js
+// utlint-ignore no-debugger: generated breakpoint
+debugger;
 ```
 
-The package also provides compatibility bins for common replacement flows:
+| Directive | Scope |
+| --- | --- |
+| `utlint-ignore [rule]` | The next line of code |
+| `utlint-ignore-all [rule]` | The entire file when placed before any code |
+| `utlint-ignore-start [rule]` | The start of a suppressed range |
+| `utlint-ignore-end [rule]` | The end of a suppressed range |
+
+A directive may target one rule ID. Omitting it creates or closes an all-rules
+suppression. Parse errors are never suppressed, and suppressed fixes are not
+applied.
+
+See the
+[suppression comments guide](https://github.com/utooland/utoo-lint/blob/main/docs/suppressions.md)
+for range examples and API behavior.
+
+## Migrating from ESLint
+
+Convert an existing ESLint config into a native utoo-lint config:
 
 ```bash
-pnpm exec eslint --config utlint.config.json src
-pnpm exec fishlint eslint --disable-setup --config utlint.config.json --glob src
+utx @utoo/lint migrate eslint \
+  --from eslint.config.js \
+  --output utlint.config.json
 ```
 
+The package also exposes `eslint` and `fishlint` compatibility commands for
+incremental replacement workflows. See the
+[migration guide](https://github.com/utooland/utoo-lint/blob/main/docs/eslint-migration.md)
+for supported mappings and known differences.
+
 ## JavaScript API
 
+The package provides ESM and CommonJS entry points:
+
 ```js
 import { lintFiles } from "@utoo/lint";
 
 const report = lintFiles(["src"], {
-  config: "utlint.config.json",
-  rules: ["no-debugger"]
+  config: "utlint.config.ts"
 });
 
 console.log(report.diagnostics);
 ```
 
-Calling `lintFiles()` without patterns follows the same default target behavior
-as the CLI, so migration scripts usually do not need to expand config `files`
-manually.
-
-CommonJS is supported through `require("@utoo/lint")`.
-
-Set `fix: true` to compute fixed output through the JavaScript API. Raw
-`lintFiles()` and `lintText()` reports expose changed sources in `outputs`
-without writing them. The ESLint-compatible API follows the usual two-step
-flow:
+An ESLint-style API is also available:
 
 ```js
 import { ESLint } from "@utoo/lint";
@@ -257,8 +244,50 @@ const results = await eslint.lintFiles(["src"]);
 await ESLint.outputFixes(results);
 ```
 
-## Binary Resolution
+Raw reports include active diagnostics, suppressed diagnostics, fixed outputs,
+and an exit code. The compatibility layer also exports `Linter`, `CLIEngine`,
+`RuleTester`, and `SourceCode` APIs.
+
+The Node wrapper captures up to 64 MiB from each native stdout and stderr
+stream by default. Programmatic `run`, `runCli`, and `runFishlint` calls can set
+`maxBuffer` to another positive byte count. Set `UTOO_LINT_MAX_BUFFER` to apply
+the same limit to CLI invocations; output beyond the configured bound reports
+`ENOBUFS` instead of being truncated.
+
+## WebAssembly
+
+For browser playgrounds and in-memory Node ESM usage, install the independent
+`@utoo/lint-wasm` package. It ships a freestanding WebAssembly module rather
+than selecting one of the native platform packages used by `@utoo/lint`.
+
+See the
+[WebAssembly guide](https://github.com/utooland/utoo-lint/blob/main/docs/wasm.md)
+for its API, runtime boundaries, and Web Worker recommendation.
+
+## Supported platforms
+
+The package installs a platform-specific optional dependency containing the
+native binary.
+
+| Operating system | Architectures |
+| --- | --- |
+| macOS | arm64, x64 |
+| Linux | arm64, x64 |
+| Windows | x64 |
+
+Set `UTOO_LINT_BIN=/path/to/utoo-lint` to use a custom binary during local
+development.
+
+## Documentation
+
+- [Rule status](https://github.com/utooland/utoo-lint/blob/main/docs/rule-status.md)
+- [Configuration](https://github.com/utooland/utoo-lint/blob/main/docs/configuration.md)
+- [Suppression comments](https://github.com/utooland/utoo-lint/blob/main/docs/suppressions.md)
+- [WebAssembly](https://github.com/utooland/utoo-lint/blob/main/docs/wasm.md)
+- [Migrating from ESLint](https://github.com/utooland/utoo-lint/blob/main/docs/eslint-migration.md)
+- [Benchmarks](https://github.com/utooland/utoo-lint/tree/main/benchmarks)
+- [Security policy](https://github.com/utooland/utoo-lint/blob/main/SECURITY.md)
+
+## License
 
-`@utoo/lint` installs a platform-specific optional dependency containing the
-native `utoo-lint` binary. Set `UTOO_LINT_BIN=/path/to/utoo-lint` to force a
-specific binary during local development.
+[MIT](https://github.com/utooland/utoo-lint/blob/main/LICENSE)

package/bin/fishlint.js

@@ -61,6 +61,8 @@ const STYLELINT_VALUE_FLAGS = new Set([
   "-f",
   "-o"
 ]);
+const DEFAULT_NATIVE_MAX_BUFFER = 64 * 1024 * 1024;
+const nativeOutputMaxBuffer = readNativeMaxBuffer();
 
 if (isVersionRequest(values)) {
   printVersion();
@@ -182,7 +184,10 @@ const needsReportOutput =
   ignoredFiltered.diagnostics.length > 0 ||
   usesJsonWithMetadataFormat(nativeValues) ||
   ruleResolution.configuredRules.size > 0;
-const result = spawnSync(binary, needsReportOutput ? withJsonFormat(ruleConfig.args) : ruleConfig.args, { encoding: "utf8" });
+const result = spawnSync(binary, needsReportOutput ? withJsonFormat(ruleConfig.args) : ruleConfig.args, {
+  encoding: "utf8",
+  maxBuffer: nativeOutputMaxBuffer
+});
 
 if (result.error) {
   console.error(`utoo-lint: failed to run native binary: ${result.error.message}`);
@@ -1102,7 +1107,7 @@ function runFlatConfigGroups(binary, translatedArgs, selectedConfig, ruleOverrid
       ...withoutConfigAndTargets(translatedArgs),
       `--config=${runtimeConfig.file}`,
       ...group.files
-    ]), { encoding: "utf8" });
+    ]), { encoding: "utf8", maxBuffer: nativeOutputMaxBuffer });
     cleanupRuleConfig(runtimeConfig);
     if (result.error) {
       return { error: result.error };
@@ -1500,13 +1505,28 @@ function parseJsonReport(stdout) {
 }
 
 function jsonDiagnosticCounts(binary, args) {
-  const result = spawnSync(binary, withJsonFormat(args), { encoding: "utf8" });
+  const result = spawnSync(binary, withJsonFormat(args), {
+    encoding: "utf8",
+    maxBuffer: nativeOutputMaxBuffer
+  });
   if (result.error) {
     return null;
   }
   return diagnosticCounts(result.stdout ?? "");
 }
 
+function readNativeMaxBuffer() {
+  const configured = process.env.UTOO_LINT_MAX_BUFFER;
+  if (configured === undefined || configured === "") {
+    return DEFAULT_NATIVE_MAX_BUFFER;
+  }
+  const value = Number(configured);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError("UTOO_LINT_MAX_BUFFER must be a positive integer byte count");
+  }
+  return value;
+}
+
 function withJsonFormat(args) {
   const values = [];
   let foundFormat = false;