pickier 0.1.20 → 0.1.22

package/README.md

@@ -1,488 +1,109 @@
-<p align="center"><img src=".github/art/cover.jpg" alt="Social Card of this repo"></p>
+# pickier
 
-[![npm version][npm-version-src]][npm-version-href]
-[![GitHub Actions][github-actions-src]][github-actions-href]
-<!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
-<!-- [![Codecov][codecov-src]][codecov-href] -->
+Format, lint, and more in a fraction of a second.
 
-# Pickier
-
-> Fast linting and formatting. Minimal defaults. Extensible. Built for speed.
-
-## Features
-
-- Fast CLI with instant feedback
-- Lint and format in one tool
-- 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
-- **Package.json validation with 20 publint rules** for correct npm publishing _(exports ordering, file format, module system, etc.)_
-- 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
+## Installation
 
 ```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
-npx pickier --help
-
-# or
-bunx pickier --help
-```
-
-## Quick Start
-
-```bash
-# Lint your project
-pickier .
-
-# Auto-fix lint issues
-pickier . --fix
-
-# Format files
-pickier . --format
-
-# Check formatting without writing (CI-friendly)
-pickier . --format --check
-
-# Preview fixes without writing
-pickier . --fix --dry-run
+npm install -D pickier
 ```
 
-By default, `pickier` lints. Use `--fix` to auto-fix problems or `--format` to format files.
-
-## CLI
-
-### `pickier [...globs]`
-
-Lints by default. Add `--fix` to auto-fix or `--format` to format files.
+## Usage
 
 ```bash
-# These are equivalent:
-pickier .
-pickier lint .
-
-# These are equivalent:
-pickier . --fix
+# Lint files
 pickier lint . --fix
 
-# These are equivalent:
-pickier . --format
+# Format files
 pickier format . --write
-```
-
-### `pickier lint [...globs]`
-
-Lint files.
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--fix` | Auto-fix problems | `false` |
-| `--dry-run` | Simulate fixes without writing | `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 (reserved) | `false` |
-| `--verbose` | Verbose output | `false` |
-
-### `pickier format [...globs]`
-
-Format files.
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--write` | Write changes to files | `false` |
-| `--check` | Check without writing, non-zero exit on differences (CI-friendly) | `false` |
-| `--ext <exts>` | Comma-separated extensions (overrides config) | — |
-| `--ignore-path <file>` | Optional ignore file (e.g. `.gitignore`) | — |
-| `--config <path>` | Path to pickier config file | — |
-| `--verbose` | Verbose output | `false` |
-
-### `pickier run [...globs]`
-
-Unified command that routes to lint or format based on `--mode`.
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--mode <mode>` | `auto`, `lint`, or `format` | `auto` |
-
-Accepts all flags from both `lint` and `format`. Useful for scripts that need explicit mode control.
-
-## Configuration
-
-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'
-
-const config: PickierConfig = {
-  verbose: false,
-  ignores: ['**/node_modules/**', '**/dist/**', '**/build/**'],
-
-  lint: {
-    // which extensions to lint ('.ts' or 'ts' both supported)
-    extensions: ['ts', 'js'],
-    // stylish | json | compact
-    reporter: 'stylish',
-    // reserved (not used yet)
-    cache: false,
-    // -1 disables, otherwise fail when warnings > maxWarnings
-    maxWarnings: -1,
-  },
-
-  format: {
-    // which extensions to format
-    extensions: ['ts', 'js', 'json', 'md', 'yaml', 'yml'],
-    trimTrailingWhitespace: true,
-    maxConsecutiveBlankLines: 1,
-    // one | two | none
-    finalNewline: 'one',
-    // indentation width (code files)
-    indent: 2,
-    // 'spaces' | 'tabs'
-    indentStyle: 'spaces',
-    // preferred string quotes: 'single' | 'double'
-    quotes: 'single',
-    // when true, safely remove stylistic semicolons
-    // (never touches for(;;) headers; removes duplicate/empty semicolons)
-    semi: false,
-  },
-
-  rules: {
-    // 'off' | 'warn' | 'error'
-    noDebugger: 'error',
-    noConsole: 'warn',
-  },
-
-  // Plugin rules for markdown, style, sorting, etc.
-  pluginRules: {
-    // Markdown linting (53+ rules available)
-    'markdown/heading-increment': 'error',
-    'markdown/no-trailing-spaces': 'error',
-    'markdown/fenced-code-language': 'error',
-    'markdown/no-duplicate-heading': 'warn',
-  },
-}
-
-export default config
-```
-
-### 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+ |
-| `publint/` | Package.json validation for npm publishing ([publint](https://publint.dev) rules) | 20 |
-| `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'
-
-export const samplePlugin: PickierPlugin = {
-  name: 'sample',
-  rules: {
-    'no-todo': {
-      meta: { docs: 'disallow TODO comments', recommended: true },
-      check(content: string, ctx: RuleContext) {
-        const issues = []
-        const lines = content.split(/\r?\n/)
-        for (let i = 0; i < lines.length; i++) {
-          const col = lines[i].indexOf('TODO')
-          if (col !== -1) {
-            issues.push({
-              filePath: ctx.filePath,
-              line: i + 1,
-              column: col + 1,
-              ruleId: 'sample/no-todo',
-              message: 'Unexpected TODO comment.',
-              severity: 'warning',
-            })
-          }
-        }
-        return issues
-      },
-    },
-    'experimental-check': {
-      meta: { wip: true },
-      check() {
-        // not implemented yet — WIP rules surface errors with a :wip-error suffix
-        throw new Error('WIP rule')
-      },
-    },
-  },
-}
-```
-
-**Register the plugin in your config:**
-
-```ts
-// pickier.config.ts
-import type { PickierConfig } from 'pickier'
-import { samplePlugin } from './sample-plugin'
-
-const config: PickierConfig = {
-  plugins: [samplePlugin],
-  pluginRules: {
-    'sample/no-todo': 'warn',
-    'sample/experimental-check': 'error',
-  },
-}
-
-export default config
-```
-
-### Formatting Details
-
-**Semicolons**
-
-Controlled by `format.semi` (default `false`). When `true`, Pickier safely removes only stylistic semicolons:
-
-- 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)
-
-**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
-
-Spacing:
-
-- Ensures a single blank line between the import block and the rest of the file
-- Respects `format.finalNewline` at EOF
-
-**Built-in Rules**
-
-- `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)
-
-All four tools spawn a process and read the file from disk.
-
-| 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
+# Unified command
+pickier run . --mode lint --fix
+pickier run . --mode format --write
 ```
 
-## Programmatic Usage
+### Programmatic API
 
-Call Pickier from code (Bun/Node) for custom tooling, editors, or pipelines.
+```typescript
+import { lintText, runLintProgrammatic } from 'pickier'
 
-```ts
-import type { RunOptions } from 'pickier'
-import { config, defaultConfig, run, runLint, runFormat, lintText } from 'pickier'
-
-// Unified run
-const exitCode = await run(['.'], {
-  mode: 'lint',
-  fix: true,
-})
+// Lint a single string
+const issues = await lintText('const x = "hello";')
 
-// Lint specific directories
-const lintCode = await runLint(['src', 'tests'], {
+// Programmatic lint run
+const results = await runLintProgrammatic({
+  files: ['src/**/*.ts'],
   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
-# run the TS entry directly
-bun packages/pickier/bin/cli.ts --help
-
-# lint the current directory
-bun packages/pickier/bin/cli.ts .
-
-# or the compiled native binary (after compile)
-./packages/pickier/bin/pickier-<your-platform> .
-```
-
-## Testing
-
-```bash
-bun test
-```
-
-## Changelog
-
-Please see our [releases](https://github.com/pickier/pickier/releases) page for more information on what has changed recently.
-
-## Contributing
-
-Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
-
-## Community
-
-For help, discussion about best practices, or any other conversation that would benefit from being searchable:
-
-[Discussions on GitHub](https://github.com/pickier/pickier/discussions)
-
-For casual chit-chat with others using this package:
-
-[Join the Stacks Discord Server](https://discord.gg/stacksjs)
-
-## Postcardware
-
-“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where`pickier` is being used! We showcase them on our website too.
-
-Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
-
-## Sponsors
-
-We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
-
-- [JetBrains](https://www.jetbrains.com/)
-- [The Solana Foundation](https://solana.com/)
-
-## Credits
+## Features
 
-- [Chris Breuer](https://github.com/chrisbbreuer)
-- [All Contributors](../../contributors)
+- **Fast CLI** - Instant feedback powered by Bun
+- **Lint and Format** - One tool for both linting and formatting
+- **Zero-config Defaults** - Works out of the box, or customize with `pickier.config.ts`
+- **Import Organization** - Splits type/value imports, sorts modules and specifiers, removes unused imports
+- **JSON Sorting** - Sorts `package.json`, `tsconfig.json`, and other config files
+- **Tailwind CSS Class Ordering** - Enforces canonical class order across HTML/JSX/TSX/Vue/Svelte/STX
+- **Markdown Linting** - Documentation quality checks with auto-fix support
+- **Shell Script Linting & Formatting** - 21 rules for `.sh`, `.bash`, and `.zsh` files with auto-fix support and indentation normalization
+- **Spell Checking** - Optional spell-check rules powered by [ts-spell-check](https://github.com/stacksjs/ts-spell-check) (234K dictionary, 150+ common misspelling corrections)
+- **Flexible Formatting** - Configurable indent, quotes, semicolons, whitespace, and more
+- **Package.json Validation** - Validates exports ordering, file format, and module system
+- **ESLint-style Plugin System** - Load plugins, enable/disable rules
+- **CI-friendly Reporters** - Stylish, compact, and JSON output formats
+- **Programmatic API** - Use in custom tooling and editor integrations
+
+## Shell Script Support
+
+Pickier includes a full `shell/` plugin with 21 rules for linting and formatting shell scripts (`.sh`, `.bash`, `.zsh`). Files are also detected by shebang (`#!/bin/bash`, `#!/usr/bin/env zsh`, etc.).
+
+### Formatting
+
+Shell formatting normalizes indentation for control structures (`if/then/fi`, `case/esac`, `while/for/do/done`, function bodies), trims trailing whitespace, collapses blank lines, and ensures final newlines — all while preserving heredoc content verbatim.
+
+### Rules
+
+**Error Prevention:**
+
+| Rule | Fixable | Description |
+|------|---------|-------------|
+| `shell/command-substitution` | Yes | Use `$()` instead of backticks |
+| `shell/quote-variables` | - | Quote `$var` to prevent word splitting |
+| `shell/no-cd-without-check` | - | Require fallback exit after `cd` |
+| `shell/no-eval` | - | Disallow `eval` |
+| `shell/no-useless-cat` | - | Detect useless use of cat |
+| `shell/no-ls-parsing` | - | Don't parse `ls` output |
+| `shell/no-variable-in-single-quotes` | - | Flag `$var` inside single quotes |
+| `shell/no-exit-in-subshell` | - | Flag `exit` inside subshells |
+
+**Style:**
+
+| Rule | Fixable | Description |
+|------|---------|-------------|
+| `shell/shebang` | - | Ensure proper shebang line |
+| `shell/indent` | Yes | Consistent indentation (2 spaces default) |
+| `shell/function-style` | Yes | Prefer `name() {` over `function name` |
+| `shell/operator-spacing` | Yes | Spaces inside `[[ ]]` and `[ ]` |
+| `shell/keyword-spacing` | - | Spacing around shell keywords |
+| `shell/no-trailing-semicolons` | Yes | Remove unnecessary trailing `;` |
+| `shell/no-trailing-whitespace` | Yes | Trim trailing whitespace |
+
+**Best Practices:**
+
+| Rule | Fixable | Description |
+|------|---------|-------------|
+| `shell/prefer-double-brackets` | Yes | `[[ ]]` over `[ ]` for bash/zsh |
+| `shell/set-options` | - | Recommend `set -euo pipefail` |
+| `shell/prefer-printf` | - | `printf` over `echo -e`/`echo -n` |
+| `shell/consistent-case-terminators` | - | Consistent `;;` in case statements |
+| `shell/no-broken-redirect` | - | Correct `2>&1` ordering |
+| `shell/heredoc-indent` | - | Recommend `<<-` for indented heredocs |
 
 ## License
 
-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
-
-<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/pickier/pickier/main?style=flat-square -->
-<!-- [codecov-href]: https://codecov.io/gh/pickier/pickier -->
+MIT

package/dist/ast.d.ts

@@ -4,21 +4,10 @@ export declare function tokenize(text: string): Token[];
 export declare function findMatching(text: string, start: number, open: string, close: string): number;
 // Lightweight parsing utilities (no deps). Intentionally minimal for Pickier rules.
 // Provides tokenization, simple bracket matching, and loc <-> index mapping.
-export declare interface Loc {
-  line: number
-  column: number
-}
-export declare interface Range {
-  start: number
-  end: number
-}
-export declare interface Token {
-  type: string
-  value: string
-  start: number
-  end: number
-}
+export declare interface Loc { line: number, column: number }
+export declare interface Range { start: number, end: number }
+export declare interface Token { type: string, value: string, start: number, end: number }
 export declare interface SourceMap {
   lineStarts: number[]
   indexToLoc: (idx: number) => Loc
-}
+}