aislop 0.6.2 → 0.8.0

package/README.md

@@ -1,14 +1,27 @@
 # aislop
 
-**The quality gate for agentic coding.**
+**The engineering standards layer and quality gate for AI-written 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)
 
-`aislop` scans the code your agent wrote and gives you one score, 0–100. It rolls formatters, linters, complexity limits, dependency audits, and an AI-slop detector into a single command. It auto-fixes what's safely fixable and hands the rest to your coding agent with full context.
+Define your standard once in `.aislop/config.yml` + `.aislop/rules.yml`. Every change your agent makes is held to it automatically. `aislop` catches the slop they leave behind (narrative comments, `as any`, swallowed errors, hallucinated imports, todo stubs), enforces the rules your team sets, and scores every change 0–100. 8+ languages. Deterministic — no LLM at runtime.
+
+### The killer feature: the per-edit hook
+
+Install once into your coding agent:
+
+```bash
+npx aislop hook install --claude    # also: --cursor, --codex, --gemini, --windsurf, --cline, --kilo, --antigravity, --copilot
+```
+
+After every `Edit` / `Write` your agent makes, `aislop` runs and feeds the diagnostics back into the agent's next turn as structured `additionalContext` (envelope: `aislop.hook.v1` — score, counts, findings, regression flag, suggested next steps). **The agent sees the score regression on the same turn it wrote the code, before you prompt again.** No more PR-time surprises; the slop never leaves the keystroke that produced it.
+
+CI is the second gate: `aislop ci` exits non-zero when score drops below your threshold, so the same standard is enforced on every PR.
 
 Every check is deterministic. Regex patterns, AST analysis, and standard tooling (Biome, oxlint, knip, ruff). Same code in, same score out. No API calls, no LLMs, no network dependency (except optional dependency audits). The name refers to what it *catches*.
 
@@ -34,7 +47,7 @@ npx aislop fix
 # CI mode (JSON output + quality gate)
 npx aislop ci
 
-# wire aislop into your agent so it runs on every edit (new in 0.6.0)
+# wire aislop into your agent so it runs on every edit
 npx aislop hook install --claude
 ```
 
@@ -46,7 +59,7 @@ Sample output:
  [!]  Code Quality: done (2 warnings, 812ms)
  [!]  AI Slop: done (4 warnings, 455ms)
  [ok] Security: done (0 issues, 1.3s)
- aislop 0.6.2  ·  the quality gate for agentic coding
+ aislop 0.8.0  ·  the quality gate for agentic coding
 
  scan  ·  my-app  ·  typescript  ·  142 files
 
@@ -78,7 +91,7 @@ AI coding tools generate code that compiles and passes tests but ships with patt
 
 - **One score, one gate**: a 0-100 number you can enforce in CI with `aislop ci`. Weighted so sloppy patterns (dead code, `as any`, swallowed errors) hit harder than style noise.
 - **Auto-fix first, agent second**: `aislop fix` clears what's mechanically safe (formatters, unused imports, trivial comments, dead patterns). For the rest, one flag hands off to Claude Code, Codex, Cursor, Gemini, Windsurf, Amp, Aider, Goose, and 7 more, with full diagnostic context pre-filled.
-- **Wire it into your agent (new in 0.6.0)**: `aislop hook install` plugs aislop into Claude Code, Cursor, Gemini CLI (runtime), plus Codex, Windsurf, Cline, Kilo Code, Antigravity, and Copilot (rules-only). The agent gets score + findings on the turn it wrote the code, not after.
+- **Wire it into your agent**: `aislop hook install` plugs aislop into Claude Code, Cursor, Gemini CLI (runtime), plus Codex, Windsurf, Cline, Kilo Code, Antigravity, and Copilot (rules-only). The agent gets score + findings on the turn it wrote the code, not after.
 - **Deterministic**: regex, AST, and standard tooling. No LLMs, no API keys, no network dependency. Same repo in, same score out.
 - **Zero-config start**: `npx aislop scan` works on any repo. Add `.aislop/config.yml` when you want to tune thresholds or enable the architecture engine.
 - **Works across stacks**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Expo / React Native.
@@ -154,6 +167,18 @@ aislop scan --exclude "src/generated" --exclude "**/*.spec.*"
 
 CLI flags beat config; config beats defaults.
 
+**Extend a shared config.** A project config can extend a parent and override specific keys. Useful for org-wide baselines: ship one strict config, let each repo soften or tighten as needed.
+
+```yaml
+# .aislop/config.yml
+extends: ../../.aislop/base.yml   # relative path to a parent config
+
+ci:
+  failBelow: 80                   # override just this key, inherit the rest
+```
+
+`extends:` accepts a single path or an array of paths. Later entries win. Deep-merged: nested objects (`scoring.weights`, `engines`) are merged key-by-key; arrays are replaced. Circular references and depths beyond 5 are rejected with a clear error.
+
 ### Fix issues automatically
 
 ```bash
@@ -212,6 +237,30 @@ aislop hook uninstall                   # remove every aislop entry, sentinel-ve
 
 Every install is sentinel-guarded (SHA-256 hash fence) for idempotent re-runs and exact uninstall. Full guide: [`/docs/hooks`](https://scanaislop.com/docs/hooks).
 
+### Use as an MCP server
+
+aislop ships an MCP (Model Context Protocol) server so any agent that speaks MCP — Claude Desktop, Claude Code, Cursor, Codex — can call it as a tool.
+
+```jsonc
+// ~/.cursor/mcp.json  /  Claude Desktop config  /  ~/.codex/config.toml equivalent
+{
+  "mcpServers": {
+    "aislop": {
+      "command": "npx",
+      "args": ["-y", "aislop-mcp"]
+    }
+  }
+}
+```
+
+Tools exposed:
+- `aislop_scan({ path? })` — score + counts + top findings
+- `aislop_fix({ path?, force? })` — apply mechanical fixes; returns before/after delta
+- `aislop_why({ rule_id })` — engine + docs link for a rule
+- `aislop_baseline({ path? })` — read the per-edit-hook baseline (score, lastScanAt, fileCount)
+
+Same engines as the CLI; calling these from inside an agent session lets the model self-check before claiming work is done.
+
 ### Use in CI pipelines
 
 ```bash
@@ -237,6 +286,7 @@ aislop scan
 aislop init                # create .aislop/config.yml
 aislop doctor              # check which tools are available
 aislop rules               # list all built-in rules
+aislop badge               # print the public score badge URL + README snippet
 aislop hook install        # wire aislop into your coding agent
 aislop                     # interactive menu
 ```
@@ -313,6 +363,18 @@ ci:
 
 The CLI is MIT-licensed and always will be. [Learn more about the platform →](https://scanaislop.com)
 
+## Public score badge
+
+Show your aislop score on a README. Free for any project that opts in on [scanaislop.com](https://scanaislop.com).
+
+```markdown
+[![aislop](https://badges.scanaislop.com/score/<owner>/<repo>.svg)](https://scanaislop.com)
+```
+
+Shields-compatible SVG, edge-cached on Cloudflare. Colour-coded: green ≥ 85, amber 70-84, red < 70, grey if no scans yet.
+
+Run `aislop badge` to print the snippet pre-filled with your repo's owner/name, auto-detected from `git remote get-url origin`.
+
 ## Contributing
 
 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).
@@ -330,7 +392,15 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add new
 
 ## Contributors
 
-[![Contributors](https://contrib.rocks/image?repo=scanaislop/aislop)](https://github.com/scanaislop/aislop/graphs/contributors)
+Thanks to everyone who has shipped code, ideas, docs, or bug reports.
+
+<!-- CONTRIBUTORS-START -->
+- [@heavykenny](https://github.com/heavykenny)
+- [@myke-awoniran](https://github.com/myke-awoniran)
+- [@yashrajoria](https://github.com/yashrajoria)
+<!-- CONTRIBUTORS-END -->
+
+This list is regenerated by `.github/workflows/contributors.yml` after every push to `develop` or `main`. The workflow reads git log, resolves each author's GitHub login, and opens a PR with any diff. If your commits aren't being credited, either link your commit email under [GitHub Settings → Emails](https://github.com/settings/emails) or add a mapping to [`.github/contributors-overrides.json`](.github/contributors-overrides.json).
 
 ## License