@utoo/lint 0.2.1 → 0.2.3

package/README.md

@@ -18,15 +18,15 @@ Run the linter with:
 pnpm exec utoo-lint src
 ```
 
-If no target is provided, `utoo-lint` uses `files` from `utoo.json` or
-`utoo-lint.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`.
+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`.
 
 Use a config file:
 
 ```bash
-pnpm exec utoo-lint --config=utoo.json src
+pnpm exec utoo-lint --config=utlint.config.json src
 ```
 
 Run a focused rule set:
@@ -64,7 +64,23 @@ lists autofix coverage by rule.
 
 ## Configuration
 
-Create a `utoo.json` file:
+`utoo-lint` supports two canonical project config formats:
+
+| 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 npm CLI discovers either format automatically. It can also select one
+explicitly:
+
+```bash
+pnpm exec utoo-lint --config=utlint.config.ts src
+pnpm exec utoo-lint --config=utlint.config.json src
+```
+
+For a static config readable by both the npm CLI and raw native binary, create
+`utlint.config.json`:
 
 ```json
 {
@@ -78,10 +94,55 @@ Create a `utoo.json` file:
 }
 ```
 
+For a typed config executed by the npm/Node CLI, create `utlint.config.ts`:
+
+```ts
+import { defineConfig } from "@utoo/lint/config";
+
+export default defineConfig({
+  files: ["src/**/*.{js,jsx,ts,tsx}"],
+  ignores: ["dist", "node_modules"],
+  rules: {
+    "no-console": "off",
+    "no-debugger": "error"
+  }
+});
+```
+
+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:
 
 ```bash
-cp node_modules/@utoo/lint/configs/frontend.json utoo.json
+cp node_modules/@utoo/lint/configs/frontend.json utlint.config.json
 ```
 
 ## ESLint Migration
@@ -89,14 +150,14 @@ cp node_modules/@utoo/lint/configs/frontend.json utoo.json
 Convert an existing ESLint config into the native utoo format:
 
 ```bash
-pnpm exec utoo-lint migrate eslint --from eslint.config.js --output utoo.json
+pnpm exec utoo-lint migrate eslint --from eslint.config.js --output utlint.config.json
 ```
 
 The package also provides compatibility bins for common replacement flows:
 
 ```bash
-pnpm exec eslint --config utoo.json src
-pnpm exec fishlint eslint --disable-setup --config utoo.json --glob src
+pnpm exec eslint --config utlint.config.json src
+pnpm exec fishlint eslint --disable-setup --config utlint.config.json --glob src
 ```
 
 ## JavaScript API
@@ -105,7 +166,7 @@ pnpm exec fishlint eslint --disable-setup --config utoo.json --glob src
 import { lintFiles } from "@utoo/lint";
 
 const report = lintFiles(["src"], {
-  config: "utoo.json",
+  config: "utlint.config.json",
   rules: ["no-debugger"]
 });