aislop 0.10.2 → 0.11.0

package/README.md

@@ -2,30 +2,37 @@
 
 **Catch the slop AI coding agents leave in your code.**
 
-[![npm version](https://img.shields.io/npm/v/aislop.svg)](https://www.npmjs.com/package/aislop)
-[![npm downloads](https://img.shields.io/npm/dm/aislop.svg)](https://www.npmjs.com/package/aislop)
-[![CI](https://github.com/scanaislop/aislop/actions/workflows/ci.yml/badge.svg)](https://github.com/scanaislop/aislop/actions/workflows/ci.yml)
-[![aislop score](https://badges.scanaislop.com/score/scanaislop/aislop.svg)](https://scanaislop.com/scanaislop/aislop)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/aislop.svg)](https://www.npmjs.com/package/aislop) [![npm downloads](https://img.shields.io/npm/dm/aislop.svg)](https://www.npmjs.com/package/aislop) [![PyPI downloads](https://img.shields.io/pepy/dt/aislop.svg?label=PyPI%20downloads)](https://pypi.org/project/aislop/) [![Homebrew tap](https://img.shields.io/badge/Homebrew-scanaislop%2Ftap-2f855a.svg)](https://github.com/scanaislop/homebrew-tap) [![CI](https://github.com/scanaislop/aislop/actions/workflows/ci.yml/badge.svg)](https://github.com/scanaislop/aislop/actions/workflows/ci.yml) [![aislop score](https://badges.scanaislop.com/score/scanaislop/aislop.svg)](https://scanaislop.com/scanaislop/aislop) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 
 The patterns Claude Code, Cursor, Codex, and OpenCode leave behind: narrative comments above self-explanatory code, swallowed exceptions, `as any` casts, hallucinated imports, duplicated helpers, dead code, todo stubs, oversized functions. Tests pass. Lint passes. The code rots anyway.
 
-aislop catches them. 50+ rules across 7 languages (TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP). Scores every change 0–100. Sub-second. Deterministic — no LLM in the runtime path, same code in, same score out. MIT-licensed, free CLI.
+aislop catches them. 50+ rules across 8 language targets (TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP). Scores every change 0–100. Sub-second. Deterministic — no LLM in the runtime path, same code in, same score out. MIT-licensed, free CLI.
 
 ## Quick start
 
 ```bash
-npx aislop scan
+npx aislop@latest scan
 ```
 
 No install needed. Works on any project. Get your score in seconds.
 
+Also available on npm, Yarn, Bun, Homebrew, and PyPI:
+
+```bash
+npm install -g aislop                # npm
+yarn dlx aislop scan                 # Yarn (no install)
+bun add -g aislop                    # Bun
+brew install scanaislop/tap/aislop   # Homebrew
+pipx install aislop                  # Python
+```
+
+See [Installation](#installation) for every option.
+
 ```bash
-npx aislop fix                   # auto-fix issues
-npx aislop fix -f                # aggressive fixes (deps, unused files)
-npx aislop ci                    # CI mode (JSON + gate)
-npx aislop hook install --claude # per-edit hook
+aislop fix                   # auto-fix issues after installing
+aislop fix -f                # aggressive fixes (deps, unused files)
+aislop ci                    # CI mode (JSON + gate)
+aislop hook install --claude # per-edit hook
 ```
 
 **Public badge**: Show your score on your README
@@ -34,7 +41,7 @@ npx aislop hook install --claude # per-edit hook
 [![aislop](https://badges.scanaislop.com/score/<owner>/<repo>.svg)](https://scanaislop.com)
 ```
 
-Run `npx aislop badge` to auto-generate. Free at [scanaislop.com](https://scanaislop.com).
+Run `npx aislop@latest badge` to auto-generate. Free at [scanaislop.com](https://scanaislop.com).
 
 ## See it in action
 
@@ -46,9 +53,13 @@ Run `npx aislop badge` to auto-generate. Free at [scanaislop.com](https://scanai
 
 ## Installation
 
+The same CLI is published to npm, Homebrew, and PyPI. Pick whichever fits your stack.
+
+**Node / npm**
+
 ```bash
 # Run without installing
-npx aislop scan
+npx aislop@latest scan
 
 # npm
 npm install --save-dev aislop
@@ -59,25 +70,64 @@ yarn add --dev aislop
 # pnpm
 pnpm add -D aislop
 
+# bun
+bun add -d aislop
+
 # Global
 npm install -g aislop
 ```
 
 Also available as [`@scanaislop/aislop`](docs/installation.md) on GitHub Packages.
 
+**Homebrew** (macOS / Linux)
+
+```bash
+brew install scanaislop/tap/aislop
+```
+
+Homebrew installs Node.js as a dependency if it isn't already present. Details: [homebrew-tap](https://github.com/scanaislop/homebrew-tap).
+
+**Python / pipx**
+
+```bash
+pipx install aislop
+```
+
+`pipx` keeps `aislop` in its own isolated environment. Needs Node.js on `PATH`. Details: [PyPI package](https://pypi.org/project/aislop/).
+
+Full reference for every channel, bundled tooling, and external tools: [docs/installation.md](docs/installation.md).
+
 ---
 
 ## Usage
 
+Examples below use the installed `aislop` binary. For a one-off latest run, prefix the command with `npx aislop@latest`, for example `npx aislop@latest scan`.
+
+### Command reference
+
+```bash
+aislop --help              # clean overview
+aislop commands            # every public command and major flag
+aislop <command> --help    # detailed help for one command
+aislop version             # installed version
+aislop -V                  # installed version
+aislop update              # current and latest npm versions
+```
+
 ### Scan
 
 ```bash
-npx aislop scan           # current directory
-npx aislop scan ./src     # specific directory
-npx aislop scan --changes # changed files from HEAD
-npx aislop scan --staged  # staged files only
-npx aislop scan --json    # JSON output
-npx aislop scan --sarif   # SARIF 2.1.0 output (GitHub code scanning)
+aislop scan                       # current directory
+aislop scan ./src                 # specific directory
+aislop scan --changes             # changed files from HEAD
+aislop scan --changes --base origin/main  # changed vs a base branch (PRs)
+aislop scan --staged              # staged files only
+aislop scan -d                    # verbose file/rule detail
+aislop scan --json                # JSON output
+aislop scan --sarif               # SARIF 2.1.0 output (GitHub code scanning)
+aislop scan --format json         # alternate JSON form
+aislop scan --include "src/**"    # only matching paths
+aislop scan --exclude "dist,gen"  # skip extra paths
 ```
 
 **Exclude files**: `node_modules`, `.git`, `dist`, `build`, `coverage` excluded by default. Add more in `.aislop/config.yml`:
@@ -88,9 +138,9 @@ exclude:
   - src/generated
 ```
 
-Or via CLI: `npx aislop scan --exclude "**/*.test.ts,dist"`
+Or via CLI: `aislop scan --exclude "**/*.test.ts,dist"`
 
-**Unsupported languages**: aislop only analyses the 8 languages above. If a repo is mostly something else (C, C++, C#, Swift, Kotlin, …), scoring a handful of incidental files would misrepresent it, so aislop **withholds the score** and says so rather than printing a number off code it never read. `--json` returns `score: null`, `scoreable: false`, and a `coverage` breakdown.
+**Unsupported languages**: aislop only analyses the 8 language targets above. If a repo is mostly something else (C, C++, C#, Swift, Kotlin, …), scoring a handful of incidental files would misrepresent it, so aislop **withholds the score** and says so rather than printing a number off code it never read. `--json` returns `score: null`, `scoreable: false`, and a `coverage` breakdown.
 
 **Per-rule severity**: Override the severity of any rule by id, or turn it off:
 
@@ -139,9 +189,11 @@ ci:
 Auto-fix what's mechanical (formatters, unused imports, dead code). For issues that need context, hand off to your agent with full diagnostic info.
 
 ```bash
-npx aislop fix                 # auto-fixes
-npx aislop fix --safe          # only reversible fixes (imports, comment removal, formatting)
-npx aislop fix -f              # aggressive: deps, unused files
+aislop fix                 # auto-fixes
+aislop fix -d              # detailed fix progress
+aislop fix --safe          # only reversible fixes (imports, comment removal, formatting)
+aislop fix -f              # aggressive: deps, unused files
+aislop fix -p              # print an agent handoff prompt
 ```
 
 `--safe` restricts the run to fixes that cannot change behaviour — unused-import removal, import merging, narrative-comment removal, and formatting. Anything that deletes code or rewrites behaviour/attributes (console/dead-code removal, lint autofixes, unused-declaration and dependency pruning) is skipped, so a `--safe` run is genuinely "apply and commit".
@@ -151,37 +203,45 @@ npx aislop fix -f              # aggressive: deps, unused files
 When auto-fix can't solve it, pass the remaining issues to your coding agent with full context:
 
 ```bash
-npx aislop fix --claude        # Claude Code
-npx aislop fix --cursor        # Cursor (copies to clipboard)
-npx aislop fix --gemini        # Gemini CLI
-npx aislop fix --codex         # Codex CLI
-# Also: --windsurf, --amp, --aider, --goose, --pi, --crush, --opencode, --warp, --kimi, --antigravity, --deep-agents, --vscode
-npx aislop fix --prompt        # print prompt (agent-agnostic)
+aislop fix --claude        # Claude Code
+aislop fix --codex         # Codex CLI
+aislop fix --cursor        # Cursor (copies to clipboard)
+aislop fix --gemini        # Gemini CLI
+aislop fix --prompt        # print prompt (agent-agnostic)
 ```
 
+Other fix handoff flags: `--windsurf`, `--vscode`, `--amp`, `--antigravity`, `--deep-agents`, `--kimi`, `--opencode`, `--warp`, `--aider`, `--goose`, `--pi`, `--crush`.
+
 ### Install hook
 
 Runs after every agent edit. Feedback flows back immediately.
 
 ```bash
-npx aislop hook install --claude           # Claude Code
-npx aislop hook install --cursor           # Cursor
-npx aislop hook install --gemini           # Gemini CLI
-npx aislop hook install --pi               # pi
-npx aislop hook install                    # all supported agents
-npx aislop hook install claude cursor      # specific agents
+aislop hook install --claude           # Claude Code
+aislop hook install --cursor           # Cursor
+aislop hook install --gemini           # Gemini CLI
+aislop hook install --pi               # pi
+aislop hook install                    # pick agents interactively
+aislop hook install claude cursor      # specific agents
+aislop hook install --agent claude,pi  # comma-separated agents
+aislop install claude cursor           # alias for hook install
+aislop install hooks --claude          # natural alias for hook install
 ```
 
 **Runtime adapters** (scan + feedback): `claude`, `cursor`, `gemini`, `pi`.  
 **Rules-only** (agent reads rules): `codex`, `windsurf`, `cline`, `kilocode`, `antigravity`, `copilot`.
 
+Hook install flags: `--agent <names>`, `-g, --global`, `--project`, `--dry-run`, `--yes`, `--quality-gate`, plus per-agent shortcuts `--claude`, `--cursor`, `--gemini`, `--pi`, `--codex`, `--windsurf`, `--cline`, `--kilocode`, `--antigravity`, `--copilot`.
+
 **Quality-gate mode**: Blocks if score regresses below baseline.
 
 ```bash
-npx aislop hook install --claude --quality-gate
-npx aislop hook baseline                    # re-capture baseline
-npx aislop hook status                      # list installed
-npx aislop hook uninstall --claude          # remove
+aislop hook install --claude --quality-gate
+aislop hook baseline                    # re-capture baseline
+aislop hook status                      # list installed
+aislop hook uninstall --claude          # remove
+aislop uninstall claude                  # alias for hook uninstall
+aislop uninstall hooks --claude          # natural alias for hook uninstall
 ```
 
 Docs: [`/docs/hooks`](https://scanaislop.com/docs/hooks)
@@ -207,18 +267,30 @@ Expose aislop as MCP tools for Claude Desktop, Cursor, Codex:
 ### CI
 
 ```bash
-npx aislop ci                  # JSON output, exits 1 if score < threshold
+aislop ci                  # JSON output, exits 1 if score < threshold
+aislop ci --changes --base origin/main  # gate only the files a PR changes
+aislop ci --human          # human-friendly CI output
+aislop ci --sarif          # SARIF output for code scanning
 ```
 
+`ci` accepts the same `--changes` / `--staged` / `--base <ref>` scoping as `scan`. Use `--changes --base origin/<target>` to gate a pull request on only the files it touches; the score gate and exit code still apply.
+
 ### Other commands
 
 ```bash
-npx aislop init                # create .aislop/config.yml
-npx aislop init --strict       # enterprise-grade gate: all engines, typecheck, failBelow 85
-npx aislop rules               # list rules
-npx aislop badge               # print badge URL
-npx aislop trend               # show score history over time
-npx aislop                     # interactive menu
+aislop                         # interactive menu
+aislop init                    # create .aislop/config.yml
+aislop init --strict           # enterprise-grade gate: all engines, typecheck, failBelow 85
+aislop doctor                  # check which engines can run here
+aislop rules                   # list rules
+aislop rules --search          # searchable rule explorer
+aislop badge                   # print badge URL
+aislop badge --owner o --repo r --json
+aislop trend                   # show score history over time
+aislop trend --limit 20
+aislop update                  # show current and latest npm versions
+aislop upgrade                 # alias for update
+aislop commands                # full command list
 ```
 
 **Score history**: a normal (full-project, interactive) `scan` appends a compact record to `.aislop/history.jsonl` (timestamp, score, error/warning counts, file count, CLI version). `aislop trend` reads it and prints a table plus an ASCII sparkline of recent scores. History is a local side effect only: it is never written for `--json`/`--sarif` output, in CI, or when `AISLOP_NO_HISTORY=1` is set, so machine output stays clean.
@@ -234,7 +306,7 @@ Docs: [commands](docs/commands.md)
 Run directly on staged files:
 
 ```bash
-npx aislop scan --staged
+aislop scan --staged
 ```
 
 Or wire it into the [pre-commit](https://pre-commit.com) framework via the bundled hook:
@@ -243,14 +315,14 @@ Or wire it into the [pre-commit](https://pre-commit.com) framework via the bundl
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/scanaislop/aislop
-    rev: v0.10.2
+    rev: v1
     hooks:
       - id: aislop
 ```
 
 ### GitHub Actions
 
-Run `npx aislop init` and accept the workflow prompt, or add manually:
+Run `aislop init` and accept the workflow prompt, or add manually. The self-contained form always runs the latest CLI, so there's nothing to bump:
 
 ```yaml
 name: aislop
@@ -265,30 +337,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
-      - uses: scanaislop/aislop@v0.10.2
+      - uses: actions/setup-node@v4
         with:
-          version: latest
-```
-
-`uses: scanaislop/aislop@v0.10.2` pins the GitHub Action wrapper. `version: latest` follows the latest npm CLI. For fully deterministic CI, set both to the same release:
-
-```yaml
-- uses: actions/checkout@v4
-
-- uses: scanaislop/aislop@v0.10.2
-  with:
-    version: "0.10.2"
+          node-version: 24
+      - run: npx --yes aislop@latest ci
 ```
 
-Manual workflow without the Marketplace Action:
+Prefer the Marketplace Action? `@v1` tracks the latest release and `version: latest` keeps the CLI current. Pin `@v0.10.2` and a `version` for reproducible builds:
 
 ```yaml
 - uses: actions/checkout@v4
-- uses: actions/setup-node@v4
+- uses: scanaislop/aislop@v1
   with:
-    node-version: 20
-- run: npx --yes aislop@latest ci .
+    version: latest
 ```
 
 **GitHub code scanning (SARIF)**: emit a SARIF 2.1.0 report and upload it so findings appear in the Security tab:
@@ -300,6 +361,27 @@ Manual workflow without the Marketplace Action:
     sarif_file: aislop.sarif
 ```
 
+### Bitbucket Pipelines
+
+Bitbucket clones shallow by default, so fetch the PR target branch and gate on only the changed files with `ci --changes --base`:
+
+```yaml
+# bitbucket-pipelines.yml
+pipelines:
+  pull-requests:
+    "**":
+      - step:
+          name: aislop gate
+          image: node:24
+          clone:
+            depth: full   # branch diffs need history
+          script:
+            - git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
+            - npx --yes aislop@latest ci --changes --base FETCH_HEAD
+```
+
+`ci` applies the score gate and exit code, so no JSON parsing or hand-rolled threshold is needed. More providers: [CI/CD](docs/ci.md).
+
 ### Quality gate
 
 Set minimum score in `.aislop/config.yml`:
@@ -333,7 +415,7 @@ AI coding tools generate code that compiles and passes tests but ships with patt
 - **One score**: 0-100, enforced in CI. Weighted so sloppy patterns hit harder than style noise.
 - **Auto-fix first**: Clears formatters, unused imports, dead code mechanically. Hands off the rest to your agent with full context.
 - **Deterministic**: Regex + AST + standard tooling. No LLMs, no API calls. Same code in, same score out.
-- **Zero-config start**: `npx aislop scan` works on any repo. Add `.aislop/config.yml` to tune.
+- **Zero-config start**: `npx aislop@latest scan` works on any repo. Add `.aislop/config.yml` to tune.
 
 ## What it catches