npm - aislop - Versions diffs - 0.1.3 → 0.2.1 - Mend

aislop 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +136 -260
package/dist/cli.js +254 -126
package/dist/{engine-info-Bi8pE12U.js → engine-info-DFze-2GQ.js} +1 -1
package/dist/index.js +464 -362
package/dist/{json-66-1kHeg.js → json-Ci_gvHLS.js} +1 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -3,355 +3,231 @@
 **Stop AI slop from shipping.**
 [![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/heavykenny/aislop/actions/workflows/ci.yml/badge.svg)](https://github.com/heavykenny/aislop/actions/workflows/ci.yml)
 [![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)
-AI coding assistants are fast, but they leave behind a trail of sloppy code: swallowed exceptions, trivial comments that restate the obvious, unused imports, `as any` casts, empty catch blocks, leftover `console.log` calls, and copy-paste duplication. **aislop** catches all of it in one command.
+`aislop` is a unified code-quality CLI that catches the lazy patterns AI coding tools leave behind. One command, one score out of 100.
-`aislop` is a unified code-quality CLI for multi-language repositories. It runs formatting, linting, code-quality, AI-pattern, architecture, and security checks behind a single command and summarizes everything as one score out of 100.
+`aislop` helps teams review AI-assisted code faster by combining formatting, linting, maintainability, AI-pattern detection, architecture checks, and security checks into a single report.
-```
-$ npx aislop scan
-aislop Scan v0.1.0
-  ✓ Project my-app (typescript)
-  Source files: 142
-  ✓ Formatting:     done (0 issues)
-  ✓ Linting:        done (2 warnings)
-  ✓ Code Quality:   done (1 warning)
-  ! Maintainability: done (4 warnings)
-  ✓ Security:       done (0 issues)
-  Score: 80/100 (Healthy)
-```
----
+## See it in action
-## Why aislop?
+### Scan
-Code generated by AI assistants often looks correct at first glance but is full of quality issues that pass review because they are spread across dozens of files. No single existing linter catches all of them. `aislop` was built to be the one tool that does:
+![aislop scan demo](assets/scan.gif)
-- **Catches AI-specific patterns** that ESLint and Prettier ignore: trivial comments (`// Import React`), thin wrappers, generic names (`data2`, `helper_1`), swallowed exceptions
-- **Multi-language** -- TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP in one CLI
-- **Single score** -- one number to gate PRs, track in CI, and trend over time
-- **Zero config to start** -- run `npx aislop scan` and get results immediately
-- **Batteries included** -- ships with oxlint, biome, and knip; downloads ruff and golangci-lint automatically on install
+### Fix
----
+![aislop fix demo](assets/fix.gif)
-## Installation
-### Run without installing
+## Quick start
 ```bash
+# scan your project
 npx aislop scan
-```
-### Install as a dev dependency
-```bash
-# npm
-npm install --save-dev aislop
-# yarn
-yarn add --dev aislop
+# auto-fix what can be fixed safely
+npx aislop fix
-# pnpm
-pnpm add -D aislop
+# CI mode (JSON output + quality gate)
+npx aislop ci
 ```
-### Global install
+Sample output:
-```bash
-npm install -g aislop
-aislop scan
-```
+```text
+aislop scan v0.2.0
-`aislop` ships with Node-based tooling (oxlint, biome, knip) as package dependencies. On install it also downloads bundled binaries for **ruff** and **golangci-lint**. To skip those downloads:
+  ✓ Project my-app (typescript)
+  Source files: 142
-```bash
-AISLOP_SKIP_TOOL_DOWNLOAD=1 npm install
+  ✓ Formatting: done (0 issues)
+  ! Linting: done (2 warnings)
+  ! Code Quality: done (1 warning)
+  ✓ Maintainability: done (0 issues)
+  ✓ Security: done (0 issues)
+------------------------------------------------------------
+Summary
+  Score: 89/100 (Healthy)
+  Issues: 0 errors, 3 warnings
+  Auto-fixable: 2
+  Files: 142
+  Time: 2.3s
+------------------------------------------------------------
 ```
-Some checks depend on tools already present on your machine: `gofmt`, `govulncheck`, `cargo`, `rubocop`, `phpcs`, `php-cs-fixer`. Run `aislop doctor` to see what is available.
 ---
-## Quick start
+## Why aislop
-```bash
-# Scan the current directory
-npx aislop scan
+AI-generated changes often pass review because problems are spread across many files and many categories.
+`aislop` gives you one view and one score.
-# Auto-fix formatting and lint issues
-npx aislop fix
+- **One command, full picture**: formatting + lint + maintainability + AI slop + security (+ architecture)
+- **Score-based quality gate**: use a single 0-100 score in CI and PR checks
+- **Auto-fix support**: remove unused imports, apply lint suggestions, and format in one pass
+- **Duplication visibility**: flag repeated blocks and encourage extraction into shared modules
+- **Software engineering best practices**: enforce function/file size limits, nesting limits, dead code cleanup, and safer patterns
+- **Works across stacks**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Expo/React Native
+- **Zero-config start**: run `npx aislop scan` and get useful output immediately
-# Scan only changed files (great for pre-commit)
-npx aislop scan --changes
+## What it catches
-# Scan only staged files
-npx aislop scan --staged
+Six engines run in parallel: **Formatting**, **Linting**, **Code Quality**, **AI Slop Detection**, **Security**, and **Architecture** (opt-in).
-# CI-friendly JSON output
-npx aislop ci
-# Initialize config files
-npx aislop init
+| Engine | Examples |
+|---|---|
+| Formatting | Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer |
+| Linting | oxlint, ruff, golangci-lint, clippy, expo-doctor |
+| Code Quality | Function/file size limits, deep nesting, duplication, dead code, unused dependencies (knip) |
+| AI Slop | Trivial comments, swallowed exceptions, unused imports, console leftovers, type assertion abuse, TODO stubs |
+| Security | Hardcoded secrets, eval, innerHTML, SQL/shell injection, dependency audits |
+| Architecture | Custom import bans, layering rules, required patterns |
-# Interactive menu
-npx aislop
-```
+See the full [rules reference](docs/rules.md).
 ---
-## Commands
-| Command | What it does |
-|---|---|
-| `aislop` | Interactive TTY menu (falls back to `scan` in non-TTY) |
-| `aislop scan [dir]` | Run all enabled engines and print a scored report |
-| `aislop fix [dir]` | Apply safe auto-fixes (formatting + lint) |
-| `aislop ci [dir]` | Output JSON for CI pipelines |
-| `aislop init [dir]` | Create `.aislop/config.yml` and `.aislop/rules.yml` |
-| `aislop doctor [dir]` | Report which tools are installed and available |
-| `aislop rules [dir]` | List all built-in and configured rules |
-### Flags
+## Installation
-| Flag | Description |
-|---|---|
-| `--changes` | Only scan files changed from `HEAD` |
-| `--staged` | Only scan staged files |
-| `-d, --verbose` | Show detailed per-file output |
-| `--json` | Output JSON instead of terminal UI |
-| `-v, --version` | Print version |
+```bash
+# Run without installing
+npx aislop scan
----
+# npm
+npm install --save-dev aislop
-## What it catches
+# yarn
+yarn add --dev aislop
-`aislop` groups checks into six engines. Each engine runs in parallel for speed.
+# pnpm
+pnpm add -D aislop
-### Formatting
+# Global
+npm install -g aislop
+```
-Enforces consistent formatting using the best tool for each language.
+Also available as [`@heavykenny/aislop`](docs/installation.md) on GitHub Packages.
-| Language | Tool |
-|---|---|
-| TypeScript / JavaScript | Biome |
-| Python | ruff format |
-| Go | gofmt |
-| Rust | cargo fmt |
-| Ruby | rubocop |
-| PHP | php-cs-fixer |
+---
-### Linting
+## Usage
-Catches bugs and bad practices.
+### Scan your project
-| Language | Tool |
-|---|---|
-| TypeScript / JavaScript | oxlint (bundled, with React/Next.js awareness) |
-| Python | ruff |
-| Go | golangci-lint |
-| Rust | clippy |
-| Ruby | rubocop |
+```bash
+aislop scan                # scan current directory
+aislop scan ./src          # scan a specific directory
+aislop scan --changes      # only files changed from HEAD
+aislop scan --staged       # only staged files (pre-commit)
+aislop scan --json         # output JSON
+```
-### Code quality
+### Fix issues automatically
-Measures structural complexity and finds dead code.
+```bash
+aislop fix                 # auto-fix unused imports, formatting, and lint fixes
+```
-| Rule | What it checks |
-|---|---|
-| `complexity/function-too-long` | Functions exceeding configurable line limit (default: 80) |
-| `complexity/file-too-large` | Files exceeding configurable line limit (default: 400) |
-| `complexity/deep-nesting` | Control-flow nesting beyond threshold (default: 5) |
-| `complexity/too-many-params` | Functions with too many parameters (default: 6) |
-| `duplication/block` | Cross-file duplicate code blocks (12+ lines) |
-| `knip/files`, `knip/exports`, `knip/types` | Dead code via knip (JS/TS) |
-### AI slop detection (Maintainability)
-The rules that make aislop unique. These catch the patterns AI assistants leave behind.
-| Rule | Severity | What it catches |
-|---|---|---|
-| `ai-slop/trivial-comment` | warning | Comments restating the code (`// Import React`, `// Return the value`) |
-| `ai-slop/swallowed-exception` | error | Empty catch blocks, catch blocks that only log (JS/TS/Python/Go/Ruby/Java) |
-| `ai-slop/thin-wrapper` | warning | Functions that only delegate to another function |
-| `ai-slop/generic-naming` | info | AI-generated names: `helper_1`, `data2`, `temp1` |
-| `ai-slop/unused-import` | warning | Unused imports (JS/TS and Python) |
-| `ai-slop/console-leftover` | warning | `console.log`/`debug`/`info` left in production code |
-| `ai-slop/todo-stub` | info | Unresolved TODO/FIXME/HACK comments |
-| `ai-slop/unreachable-code` | warning | Code after `return`/`throw` statements |
-| `ai-slop/constant-condition` | warning | `if (true)`, `if (false)`, `if (0)` |
-| `ai-slop/empty-function` | info | Empty function bodies |
-| `ai-slop/unsafe-type-assertion` | warning | `as any` in TypeScript |
-| `ai-slop/double-type-assertion` | warning | `as unknown as X` pattern |
-| `ai-slop/ts-directive` | info | `@ts-ignore` / `@ts-expect-error` usage |
-### Security
-Finds secrets, risky constructs, and vulnerable dependencies.
-| Rule | What it catches |
-|---|---|
-| `security/hardcoded-secret` | API keys, AWS credentials, JWT tokens, database URLs, passwords |
-| `security/eval` | `eval()` usage (JS/TS/Python/Ruby/PHP) |
-| `security/innerhtml` | `.innerHTML` and `dangerouslySetInnerHTML` |
-| `security/sql-injection` | String concatenation in SQL queries |
-| `security/shell-injection` | User input in command execution |
-| `security/vulnerable-dependency` | npm/pip/cargo/go dependency audit |
+### Use in CI pipelines
-### Architecture (opt-in)
+```bash
+aislop ci                  # JSON output, exits 1 if score < threshold
+```
-Custom import and path rules defined in `.aislop/rules.yml`.
+### Common workflow
-| Rule type | Example |
-|---|---|
-| `forbid_import` | Ban `axios` project-wide |
-| `forbid_import_from_path` | Controllers cannot import database modules |
-| `require_pattern` | Require error handling in API routes |
+```bash
+# before commit
+aislop scan --staged
----
+# during local cleanup
+aislop fix
-Every diagnostic contributes a weighted penalty:
+# full project check
+aislop scan
+```
-| Severity | Penalty |
-|---|---|
-| Error | 3.0 |
-| Warning | 1.0 |
-| Info | 0.25 |
+### Other commands
-Penalties are multiplied by engine weight (configurable, security defaults to 2x). The final score uses logarithmic scaling with issue-density normalization (relative to source file count), so a few issues still matter but a single finding in an otherwise clean project remains proportional.
+```bash
+aislop init                # create .aislop/config.yml
+aislop doctor              # check which tools are available
+aislop rules               # list all built-in rules
+aislop                     # interactive menu
+```
-| Score | Label |
-|---|---|
-| 75 -- 100 | Healthy |
-| 50 -- 74 | Needs Work |
-| 0 -- 49 | Critical |
+See [all commands and flags](docs/commands.md).
 ---
-## Configuration
+## Use in your project
-Run `aislop init` to generate `.aislop/config.yml`:
-```yaml
-version: 1
-engines:
-  format: true
-  lint: true
-  code-quality: true
-  ai-slop: true
-  architecture: false    # opt-in, needs rules.yml
-  security: true
-quality:
-  maxFunctionLoc: 80
-  maxFileLoc: 400
-  maxNesting: 5
-  maxParams: 6
-security:
-  audit: true
-  auditTimeout: 25000
-scoring:
-  weights:
-    format: 0.5
-    lint: 1.0
-    code-quality: 1.5
-    ai-slop: 1.0
-    architecture: 1.0
-    security: 2.0
-  thresholds:
-    good: 75
-    ok: 50
+### Pre-commit hook
-ci:
-  failBelow: 0           # set to e.g. 70 to fail CI below that score
-  format: json
+```bash
+npx aislop scan --staged
 ```
----
-## CI / CD
 ### GitHub Actions
 ```yaml
-- uses: actions/setup-node@v4
+- uses: actions/setup-node@v6
   with:
     node-version: 20
+- run: npm ci
 - run: npx aislop ci
 ```
-### Fail below a score threshold
+### Quality gate
-Set `ci.failBelow` in `.aislop/config.yml`:
+Set a minimum score in `.aislop/config.yml`:
 ```yaml
 ci:
   failBelow: 70
 ```
-`aislop ci` exits with code 1 when the score is below the threshold.
-### Pre-commit hook
-```bash
-npx aislop scan --staged
-```
+`aislop ci` exits with code 1 when the score drops below the threshold. See [CI/CD docs](docs/ci.md) for more.
 ---
-## Supported languages
+## Documentation
-| Language | Format | Lint | Code quality | AI slop | Security |
-|---|---|---|---|---|---|
-| TypeScript | Biome | oxlint | knip, complexity | All rules | All rules |
-| JavaScript | Biome | oxlint | knip, complexity | All rules | All rules |
-| Python | ruff | ruff | complexity | Imports, exceptions, comments | Secrets, audit |
-| Go | gofmt | golangci-lint | complexity | Exceptions, comments | Secrets, audit |
-| Rust | cargo fmt | clippy | complexity | Comments | Secrets, audit |
-| Ruby | rubocop | rubocop | complexity | Exceptions, comments | Secrets |
-| PHP | php-cs-fixer | -- | complexity | Comments | Secrets |
+| Topic | Link |
+|---|---|
+| Installation | [docs/installation.md](docs/installation.md) |
+| Commands & flags | [docs/commands.md](docs/commands.md) |
+| Rules reference | [docs/rules.md](docs/rules.md) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Scoring | [docs/scoring.md](docs/scoring.md) |
+| CI / CD | [docs/ci.md](docs/ci.md) |
+| Telemetry | [docs/telemetry.md](docs/telemetry.md) |
 ---
-## Telemetry
-`aislop` collects anonymous usage analytics to help us understand how the tool is used and prioritize improvements. **No code, file paths, project names, or secrets are ever collected.**
-What we collect: command run (scan/fix/ci), languages detected, score bucket, issue counts per engine, engine timing, OS, Node version, and aislop version.
-Telemetry is **off in CI** by default. To opt out anywhere:
-```bash
-# Environment variable (any of these)
-AISLOP_NO_TELEMETRY=1 aislop scan
-DO_NOT_TRACK=1 aislop scan
+## Contributing
-# Or in .aislop/config.yml
-telemetry:
-  enabled: false
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add new rules. AI coding assistants can find project context in [AGENTS.md](AGENTS.md).
----
+## Acknowledgments
-## Contributing
+`aislop` is built on top of excellent open-source projects:
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project architecture, and how to add new rules or engines.
+- [Biome](https://biomejs.dev/) — formatting and linting for JS/TS
+- [oxlint](https://oxc.rs/) — fast JavaScript/TypeScript linter
+- [knip](https://knip.dev/) — unused files, exports, and dependencies
+- [ruff](https://docs.astral.sh/ruff/) — Python linting and formatting
+- [golangci-lint](https://golangci-lint.run/) — Go linting
+- [expo-doctor](https://docs.expo.dev/) — Expo/React Native project health
-## Security
+## Contributors
-See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+[![Contributors](https://contrib.rocks/image?repo=heavykenny/aislop)](https://github.com/heavykenny/aislop/graphs/contributors)
 ## License
-[MIT](LICENSE) -- see the [LICENSE](LICENSE) file.
+[MIT](LICENSE)