aislop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 heavykenny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# aislop
+
+**Stop AI slop from shipping.**
+
+[![npm version](https://img.shields.io/npm/v/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)
+
+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 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.
+
+```
+$ 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)
+```
+
+---
+
+## Why aislop?
+
+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:
+
+- **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
+
+---
+
+## Installation
+
+### Run without installing
+
+```bash
+npx aislop scan
+```
+
+### Install as a dev dependency
+
+```bash
+# npm
+npm install --save-dev aislop
+
+# yarn
+yarn add --dev aislop
+
+# pnpm
+pnpm add -D aislop
+```
+
+### Global install
+
+```bash
+npm install -g aislop
+aislop scan
+```
+
+`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:
+
+```bash
+AISLOP_SKIP_TOOL_DOWNLOAD=1 npm install
+```
+
+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
+
+```bash
+# Scan the current directory
+npx aislop scan
+
+# Auto-fix formatting and lint issues
+npx aislop fix
+
+# Scan only changed files (great for pre-commit)
+npx aislop scan --changes
+
+# Scan only staged files
+npx aislop scan --staged
+
+# CI-friendly JSON output
+npx aislop ci
+
+# Initialize config files
+npx aislop init
+
+# Interactive menu
+npx aislop
+```
+
+---
+
+## 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
+
+| 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 |
+
+---
+
+## What it catches
+
+`aislop` groups checks into six engines. Each engine runs in parallel for speed.
+
+### Formatting
+
+Enforces consistent formatting using the best tool for each language.
+
+| Language | Tool |
+|---|---|
+| TypeScript / JavaScript | Biome |
+| Python | ruff format |
+| Go | gofmt |
+| Rust | cargo fmt |
+| Ruby | rubocop |
+| PHP | php-cs-fixer |
+
+### Linting
+
+Catches bugs and bad practices.
+
+| Language | Tool |
+|---|---|
+| TypeScript / JavaScript | oxlint (bundled, with React/Next.js awareness) |
+| Python | ruff |
+| Go | golangci-lint |
+| Rust | clippy |
+| Ruby | rubocop |
+
+### Code quality
+
+Measures structural complexity and finds dead code.
+
+| 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 |
+
+### Architecture (opt-in)
+
+Custom import and path rules defined in `.aislop/rules.yml`.
+
+| 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 |
+
+---
+
+## Scoring
+
+Every diagnostic contributes a weighted penalty:
+
+| Severity | Penalty |
+|---|---|
+| Error | 3.0 |
+| Warning | 1.0 |
+| Info | 0.25 |
+
+Penalties are multiplied by engine weight (configurable, security defaults to 2x). The final score uses logarithmic scaling so a few issues cause a noticeable drop, but the score does not collapse to zero from minor findings.
+
+| Score | Label |
+|---|---|
+| 75 -- 100 | Healthy |
+| 50 -- 74 | Needs Work |
+| 0 -- 49 | Critical |
+
+---
+
+## Configuration
+
+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
+
+ci:
+  failBelow: 0           # set to e.g. 70 to fail CI below that score
+  format: json
+```
+
+---
+
+## CI / CD
+
+### GitHub Actions
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+
+- run: npx aislop ci
+```
+
+### Fail below a score threshold
+
+Set `ci.failBelow` 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
+```
+
+---
+
+## Supported languages
+
+| 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 |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project architecture, and how to add new rules or engines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+
+## License
+
+[MIT](LICENSE) -- see the [LICENSE](LICENSE) file.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { };