pickier 0.1.13 → 0.1.14

package/README.md

@@ -2,7 +2,6 @@
 
 [![npm version][npm-version-src]][npm-version-href]
 [![GitHub Actions][github-actions-src]][github-actions-href]
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 <!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
 <!-- [![Codecov][codecov-src]][codecov-href] -->
 
@@ -13,80 +12,106 @@
 ## Features
 
 - Fast CLI with instant feedback
-- Lint and format in one tool
-- Zero-config defaults; simple, typed `pickier.config.ts`when you need it
+- Lint and format in one tool via `pickier run`
+- Zero-config defaults; simple, typed `pickier.config.ts` when you need it
 - Import organization: splits type/value imports, sorts modules/specifiers, removes unused named imports
-- JSON and config sorting for common files_(e.g.`package.json`, `tsconfig.json`)_-**Markdown linting with 53 rules**for documentation quality_(headings, lists, links, code blocks, tables, etc.)_- 27 rules support auto-fix for common formatting issues
-- Flexible formatting: `indent`, `indentStyle`_(tabs or spaces)_, `quotes`, `semi`, `trimTrailingWhitespace`, `maxConsecutiveBlankLines`, `finalNewline`- Smart whitespace cleanup
-- ESLint-style plugin system for lint rules_(load plugins, enable/disable rules, WIP labeling)_- CI-friendly reporters_(stylish, compact, JSON)_and strict`--max-warnings`control
+- JSON and config sorting for common files _(e.g. `package.json`, `tsconfig.json`)_
+- **Markdown linting with 53+ rules** for documentation quality _(headings, lists, links, code blocks, tables, etc.)_
+  - 27 rules support auto-fix for common formatting issues
+- Flexible formatting: `indent`, `indentStyle` _(tabs or spaces)_, `quotes`, `semi`, `trimTrailingWhitespace`, `maxConsecutiveBlankLines`, `finalNewline`
+- Smart whitespace cleanup
+- ESLint-style plugin system for lint rules _(load plugins, enable/disable rules, WIP labeling)_
+- CI-friendly reporters _(stylish, compact, JSON)_ and strict `--max-warnings` control
 - Programmatic API for custom tooling and editor integrations
 
-## Install```bash
+## Install
 
+```bash
 # as a dev dependency
-
 bun add -D pickier
 
 # or
-
 npm i -D pickier
 
 # or
-
 pnpm add -D pickier
 
 # or
-
 yarn add -D pickier
+```
 
-```You can also run it directly via npx without installing:```bash
+You can also run it directly via npx without installing:
+
+```bash
 npx pickier --help
 
 # or
-
 bunx pickier --help
-```## Quick start```bash
+```
 
-# Lint everything, pretty output
+## Quick Start
 
-pickier lint .
+The unified `pickier run` command handles both linting and formatting:
 
-# Auto-fix issues (safe fixes only)
+```bash
+# Auto-detect mode (lint + format)
+pickier run .
 
-pickier lint . --fix
+# Lint everything
+pickier run . --mode lint
 
-# Preview fixes without writing
+# Auto-fix lint issues (safe fixes only)
+pickier run . --mode lint --fix
 
-pickier lint . --fix --dry-run --verbose
+# Preview fixes without writing
+pickier run . --mode lint --fix --dry-run --verbose
 
 # Format and write changes
-
-pickier format . --write
+pickier run . --mode format --write
 
 # Check formatting without writing (CI-friendly)
+pickier run . --mode format --check
+```
+
+## CLI
 
-pickier format . --check
+### `pickier run [...globs]`
 
-```## CLI
+The primary command. Routes to lint or format based on `--mode`.
 
--`pickier lint [...globs]`-`--fix`: apply safe fixes (e.g. remove `debugger`statements)
-  -`--dry-run`: simulate fixes without writing
+**Options:**
 
-  - `--max-warnings <n>`: fail if warnings exceed n (default: -1)
-  - `--reporter <stylish|json|compact>`: output format (default: stylish)
-  - `--ext <.ts,.tsx,.js,...>`: comma-separated extensions (overrides config)
-  - `--ignore-path <file>`: optional ignore file (e.g. .gitignore)
-  - `--cache`: reserved (no-op currently)
-  - `--verbose`- Examples:
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mode <mode>` | `auto`, `lint`, or `format` | `auto` |
+| `--fix` | Apply safe fixes (lint mode) | `false` |
+| `--dry-run` | Simulate fixes without writing (lint mode) | `false` |
+| `--write` | Write changes to files (format mode) | `false` |
+| `--check` | Check without writing, non-zero exit on differences (format mode) | `false` |
+| `--max-warnings <n>` | Fail if warnings exceed _n_ | `-1` |
+| `--reporter <name>` | `stylish`, `json`, or `compact` | `stylish` |
+| `--ext <exts>` | Comma-separated extensions (overrides config) | — |
+| `--ignore-path <file>` | Optional ignore file (e.g. `.gitignore`) | — |
+| `--config <path>` | Path to pickier config file | — |
+| `--cache` | Enable cache (lint mode, reserved) | `false` |
+| `--verbose` | Verbose output | `false` |
 
-    -`pickier lint . --dry-run`-`pickier lint src --fix`-`pickier lint "src/**/*.{ts,tsx}" --reporter json`-`pickier format [...globs]`-`--write`: write formatted files
+**Examples:**
 
-  - `--check`: only check, non-zero exit on differences
-  - `--ext <.ts,.tsx,.js,.json,...>`-`--ignore-path <file>`-`--verbose`- Examples:
+```bash
+pickier run . --mode auto
+pickier run src --mode lint --fix
+pickier run "**/*.{ts,tsx,js}" --mode format --write
+pickier run . --mode lint --reporter json --max-warnings 0
+```
+
+> **Note:** The legacy `pickier lint` and `pickier format` commands are deprecated and will be removed in a future release. Use `pickier run --mode lint` and `pickier run --mode format` instead.
 
-    -`pickier format . --check`-`pickier format src --write`-`pickier format "**/*.{ts,tsx,js}" --write`## Configuration
+## Configuration
 
-Pickier works out-of-the-box. To customize, create`pickier.config.ts`in your project root. All fields are optional.```ts
+Pickier works out-of-the-box. To customize, create `pickier.config.ts` in your project root. All fields are optional.
+
+```ts
 // pickier.config.ts
 import type { PickierConfig } from 'pickier'
 
@@ -112,12 +137,14 @@ const config: PickierConfig = {
     maxConsecutiveBlankLines: 1,
     // one | two | none
     finalNewline: 'one',
-    // 2-space indentation (code files)
+    // indentation width (code files)
     indent: 2,
-    // preferred string quotes in code files: 'single' | 'double'
+    // 'spaces' | 'tabs'
+    indentStyle: 'spaces',
+    // preferred string quotes: 'single' | 'double'
     quotes: 'single',
     // when true, safely remove stylistic semicolons
-    // (never touches for(;;) headers; removes duplicate/empty semicolon statements)
+    // (never touches for(;;) headers; removes duplicate/empty semicolons)
     semi: false,
   },
 
@@ -129,8 +156,7 @@ const config: PickierConfig = {
 
   // Plugin rules for markdown, style, sorting, etc.
   pluginRules: {
-    // Markdown linting (53 rules available)
-    // See <https://pickier.dev/rules/markdown> for full list
+    // Markdown linting (53+ rules available)
     'markdown/heading-increment': 'error',
     'markdown/no-trailing-spaces': 'error',
     'markdown/fenced-code-language': 'error',
@@ -139,18 +165,36 @@ const config: PickierConfig = {
 }
 
 export default config
-```### Plugin system (rules)
-
-Pickier supports an ESLint-style plugin system for lint rules organized into focused categories:**Available Plugins:**-`eslint/`- Legacy compatibility layer for ESLint rule names
--`general/`- Error detection and possible problems (35+ rules)
--`quality/`- Best practices and code quality (40+ rules)
--`pickier/`- Sorting and import organization (17 rules)
--`style/`- Code style enforcement (7 rules)
--`ts/`- TypeScript-specific rules (9 rules)
--`regexp/`- Regular expression safety (3 rules)
--`markdown/`- Markdown documentation linting (53+ rules)
-
-Configure rules via`pluginRules: { 'pluginName/ruleId': 'off' | 'warn' | 'error' | ['warn', options] }`Define a plugin (example):```ts
+```
+
+### Plugin System
+
+Pickier supports an ESLint-style plugin system for lint rules organized into focused categories.
+
+**Available Plugins:**
+
+| Plugin | Description | Rules |
+|--------|-------------|-------|
+| `pickier/` | Sorting, import organization, and core checks | 17+ |
+| `general/` | Error detection and possible problems | 35+ |
+| `quality/` | Best practices and code quality | 40+ |
+| `style/` | Code style enforcement (spacing, punctuation, line breaks, etc.) | 50+ |
+| `ts/` | TypeScript-specific rules (type safety, formatting) | 13+ |
+| `regexp/` | Regular expression safety | 3+ |
+| `markdown/` | Markdown documentation linting | 53+ |
+| `lockfile/` | Lock file validation | 5+ |
+
+Configure rules via `pluginRules`:
+
+```ts
+pluginRules: {
+  'pluginName/ruleId': 'off' | 'warn' | 'error' | ['warn', options],
+}
+```
+
+**Custom Plugin Example:**
+
+```ts
 // sample-plugin.ts
 import type { PickierPlugin, RuleContext } from 'pickier'
 
@@ -181,157 +225,197 @@ export const samplePlugin: PickierPlugin = {
     'experimental-check': {
       meta: { wip: true },
       check() {
-        // not implemented yet
+        // not implemented yet — WIP rules surface errors with a :wip-error suffix
         throw new Error('WIP rule')
       },
     },
   },
 }
+```
+
+**Register the plugin in your config:**
 
-```Use the plugin in config:```ts
+```ts
 // pickier.config.ts
 import type { PickierConfig } from 'pickier'
 import { samplePlugin } from './sample-plugin'
 
 const config: PickierConfig = {
-  verbose: false,
-  ignores: ['**/node_modules/**'],
-  lint: { extensions: ['ts', 'js'], reporter: 'stylish', cache: false, maxWarnings: -1 },
-  format: { extensions: ['ts', 'js', 'json'], trimTrailingWhitespace: true, maxConsecutiveBlankLines: 1, finalNewline: 'one', indent: 2, quotes: 'single', semi: false },
-  rules: { noDebugger: 'error', noConsole: 'warn' },
-  // Register plugins (currently supports in-memory objects)
   plugins: [samplePlugin],
-  // Enable/disable rules and pass options
   pluginRules: {
     'sample/no-todo': 'warn',
-    // WIP rules that throw will surface as errors with a :wip-error suffix
     'sample/experimental-check': 'error',
   },
 }
 
 export default config
-```CLI example:```bash
+```
 
-pickier lint src --reporter json
+### Formatting Details
 
-# If a WIP rule throws, you will see an error like
+**Semicolons**
 
-# {
+Controlled by `format.semi` (default `false`). When `true`, Pickier safely removes only stylistic semicolons:
 
-# "ruleId": "sample/experimental-check:wip-error"
+- Preserves `for (init; test; update)` headers
+- Removes duplicate trailing semicolons (e.g. `foo();;` -> `foo();`)
+- Removes lines that are just empty statements (`;`)
+- Keeps normal end-of-line semicolons otherwise (non-destructive)
 
-# "message": "Rule sample/experimental-check is marked as WIP and threw: ..."
+**Imports (TypeScript/JavaScript)**
 
-#
+Groups and rewrites the top import block:
 
-# }
+- Splits type-only specifiers into `import type { ... } from 'x'`
+- Keeps default and namespace imports
+- Removes unused named specifiers (only when they have no alias)
+- Merges multiple imports from the same module
 
-```### Formatting details
+Sorting order:
 
-- Semicolons
-  - Controlled by`format.semi`(default`false`). When `true`, Pickier removes only stylistic semicolons safely:
-    - preserves `for (init; test; update)`headers
-    - removes duplicate trailing semicolons (e.g.`foo();;`→`foo();`)
-    - removes lines that are just empty statements (`;`)
-    - keeps normal end-of-line semicolons otherwise (non-destructive)
+- By kind: type imports, side-effect imports, value imports
+- For modules: external before relative
+- For specifiers: A-Z by identifier
 
-- Imports (TypeScript/JavaScript)
-  - Groups and rewrites the top import block:
-    - Splits type-only specifiers into `import type { ... } from 'x'`- Keeps default and namespace imports
-    - Removes unused named specifiers only when they have no alias
-    - Merges multiple imports from the same module
-  - Sorting
-    - Order by kind: type imports, side-effect imports, value imports
-    - For modules: external before relative
-    - For specifiers: A→Z by identifier; minor normalization for consistent ordering
-  - Spacing/newlines
-    - Ensures a single blank line between the import block and the rest of the file
-    - Respects`format.finalNewline`at EOF
+Spacing:
 
-Notes:
+- Ensures a single blank line between the import block and the rest of the file
+- Respects `format.finalNewline` at EOF
 
--`noDebugger`removes lines that are debugger statements when`--fix`is used.
--`noConsole`controls severity (turn off for libraries that allow console logs).
+**Built-in Rules**
 
-## Development
+- `noDebugger` — removes `debugger` statements when `--fix` is used
+- `noConsole` — controls severity (turn off for libraries that allow console logs)
+
+## Benchmarks
+
+Measured on an Apple M3 Pro with Bun 1.3.9. Each tool uses equivalent settings (single quotes, no semicolons, 2-space indent). Pickier and Prettier use their in-memory APIs; oxfmt and Biome have no JS formatting API, so they are called via stdin pipe. Full benchmark source is in `bechmarks/benchmarks/format-comparison.bench.ts`.
+
+### In-memory / Programmatic API
+
+Pickier `formatCode()` and Prettier `format()` run in-process. oxfmt and Biome are piped via stdin (no JS formatting API).
+
+| File | Pickier | Biome (stdin) | oxfmt (stdin) | Prettier |
+|------|--------:|--------------:|--------------:|---------:|
+| Small (52 lines, 1 KB) | **41 us** | 40 ms | 51 ms | 1.59 ms |
+| Medium (419 lines, 10 KB) | **417 us** | 42 ms | 50 ms | 10.2 ms |
+| Large (1,279 lines, 31 KB) | **1.25 ms** | 46 ms | 50 ms | 28.1 ms |
+
+### CLI (single file)
 
-This repository contains Pickier’s source under`packages/pickier`.
+All four tools spawn a process and read the file from disk.
 
-Common tasks:
+| File | Pickier | Biome | oxfmt | Prettier |
+|------|--------:|------:|------:|---------:|
+| Small (52 lines) | **37 ms** | 43 ms | 68 ms | 105 ms |
+| Medium (419 lines) | **38 ms** | 53 ms | 71 ms | 143 ms |
+| Large (1,279 lines) | **40 ms** | 90 ms | 73 ms | 187 ms |
+
+### CLI Batch (all files, sequential)
+
+| Tool | Time |
+|------|-----:|
+| Pickier | **121 ms** |
+| Biome | 187 ms |
+| oxfmt | 216 ms |
+| Prettier | 423 ms |
+
+### Throughput (large file x 20)
+
+| Tool | Time |
+|------|-----:|
+| Pickier | **26 ms** |
+| Prettier | 524 ms |
+| Biome (stdin) | 957 ms |
+| oxfmt (stdin) | 1,040 ms |
+
+> Pickier's in-memory API is **22-39x faster than Prettier** and orders of magnitude faster than tools that must spawn a process. On CLI, Pickier's compiled binary beats Biome's native Rust binary across all file sizes — **37ms vs 43ms on small files**, and pulling further ahead on larger files. At throughput scale (20x large file), Pickier is **20x faster** than Prettier and **37x faster** than Biome/oxfmt.
 
 ```bash
+# reproduce locally
+bun bechmarks/benchmarks/format-comparison.bench.ts
+```
 
-# install deps
+## Programmatic Usage
+
+Call Pickier from code (Bun/Node) for custom tooling, editors, or pipelines.
 
+```ts
+import type { RunOptions } from 'pickier'
+import { config, defaultConfig, run, runLint, runFormat, lintText } from 'pickier'
+
+// Unified run (recommended)
+const exitCode = await run(['.'], {
+  mode: 'auto',
+  fix: true,
+  verbose: false,
+})
+
+// Lint specific directories
+const lintCode = await runLint(['src', 'tests'], {
+  fix: true,
+  dryRun: false,
+  reporter: 'json',
+  maxWarnings: 0,
+})
+
+// Format specific globs
+const fmtCode = await runFormat(['src/**/*.ts'], {
+  write: true,
+})
+
+// Lint a single string
+const result = await lintText('const x = 1;;', {
+  filePath: 'virtual.ts',
+})
+
+// Access loaded config (from pickier.config.ts or defaults)
+console.log('loaded config:', config)
+```
+
+## Development
+
+This repository contains Pickier's source under `packages/pickier`.
+
+```bash
+# install deps
 bun i
 
 # run tests (with coverage)
-
 bun test --coverage
 
 # build JS and type declarations
-
 bun run -C packages/pickier build
 
 # compile native binary for your platform
-
 bun run -C packages/pickier compile
 
 # compile all platform binaries
-
 bun run -C packages/pickier compile:all
+```
 
-```Try the CLI locally without publishing:```bash
+Try the CLI locally without publishing:
 
+```bash
 # run the TS entry directly
-
 bun packages/pickier/bin/cli.ts --help
 
 # run the built dist CLI
-
-bun packages/pickier/dist/bin/cli.js lint .
+bun packages/pickier/dist/bin/cli.js run . --mode lint
 
 # or the compiled native binary (after compile)
-
 ./packages/pickier/bin/pickier-<your-platform> --help
-```## Programmatic usage
-
-You can also call Pickier from code (Bun/Node). Useful for custom tooling, editors, or pipelines.```ts
-import type { FormatOptions, LintOptions } from 'pickier'
-// example.ts
-import { pickierConfig, runFormat, runLint } from 'pickier'
-
-// Lint some directories
-const lintOptions: LintOptions = {
-  fix: true, // apply safe fixes
-  dryRun: false, // set true to simulate fixes
-  reporter: 'json', // 'stylish' | 'json' | 'compact'
-  maxWarnings: 0, // fail on any warning
-}
-
-const lintCode = await runLint(['src', 'tests'], lintOptions)
-console.log('lint exit code:', lintCode)
-
-// Format some globs
-const formatOptions: FormatOptions = {
-  write: true, // write changes
-}
+```
 
-const fmtCode = await runFormat(['src/**/*.ts'], formatOptions)
-console.log('format exit code:', fmtCode)
-
-// Access loaded config (from pickier.config.ts or defaults)
-console.log('loaded config:', pickierConfig)
-
-```Run it with Bun:```bash
-bun example.ts
-```## Testing```bash
+## Testing
 
+```bash
 bun test
+```
 
-```## Changelog
+## Changelog
 
-Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
+Please see our [releases](https://github.com/pickier/pickier/releases) page for more information on what has changed recently.
 
 ## Contributing
 
@@ -341,7 +425,7 @@ Please review the [Contributing Guide](https://github.com/stacksjs/contributing)
 
 For help, discussion about best practices, or any other conversation that would benefit from being searchable:
 
-[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+[Discussions on GitHub](https://github.com/pickier/pickier/discussions)
 
 For casual chit-chat with others using this package:
 
@@ -367,15 +451,15 @@ We would like to extend our thanks to the following sponsors for funding Stacks
 
 ## License
 
-The MIT License (MIT). Please see [LICENSE](https://github.com/pickier/pickier/tree/main/LICENSE.md) for more information.
+The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
 
 Made with 💙
 
 <!-- Badges -->
-[npm-version-src]: <https://img.shields.io/npm/v/pickier?style=flat-square>
-[npm-version-href]: <https://npmjs.com/package/pickier>
-[github-actions-src]: <https://img.shields.io/github/actions/workflow/status/pickier/pickier/ci.yml?style=flat-square&branch=main>
-[github-actions-href]: <https://github.com/pickier/pickier/actions?query=workflow%3Aci>
+[npm-version-src]: https://img.shields.io/npm/v/pickier?style=flat-square
+[npm-version-href]: https://npmjs.com/package/pickier
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/pickier/pickier/ci.yml?style=flat-square&branch=main
+[github-actions-href]: https://github.com/pickier/pickier/actions?query=workflow%3Aci
 
-<!-- [codecov-src]: <https://img.shields.io/codecov/c/gh/pickier/pickier/main?style=flat-square>
-[codecov-href]: <https://codecov.io/gh/pickier/pickier> -->
+<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/pickier/pickier/main?style=flat-square -->
+<!-- [codecov-href]: https://codecov.io/gh/pickier/pickier -->