ai-diff-check 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prashant Parmar
+
+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,127 @@
+# ai-diff-check
+
+> Your AI wrote the code. This runs the vibe check.
+
+[![CI](https://github.com/prashant1234568/ai-diff-check/actions/workflows/ci.yml/badge.svg)](https://github.com/prashant1234568/ai-diff-check/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
+
+An open-source CLI that reviews **only your git diff** before you commit — catching what AI coding agents leave behind. Offline, deterministic, no account, no LLM required.
+
+![ai-diff-check reviewing a diff: hallucinated import, duplicated function, deleted try/catch, leftover console.log, untested change — trust score 34/100](docs/demo.svg)
+
+**Status: v0.2 code-complete — all 8 checks live. npm release coming with the v1.0 launch.**
+
+## Why
+
+- 66% of developers say their #1 frustration is AI code that's *"almost right, but not quite"* (Stack Overflow 2025)
+- 96% don't fully trust AI-generated code — yet only 48% verify it before committing (Sonar 2025)
+- The existing tools in this space (Sonar, CodeRabbit, Qodo) are paid and cloud-based
+
+`ai-diff-check` is the free, local, diff-scoped alternative: it never scans your whole repo, only what just changed — so legacy code stays grandfathered and adoption costs nothing.
+
+## vs. the paid tools
+
+|  | ai-diff-check | CodeRabbit | SonarQube Cloud | Qodo |
+|---|---|---|---|---|
+| Price | **Free, MIT** | per-seat | per-LoC tiers | per-seat |
+| Runs | **Local + CI, offline** | cloud | cloud/server | cloud |
+| Your code leaves your machine | **Never** | yes | yes | yes |
+| LLM required | **No — deterministic** | yes | no | yes |
+| Scope | **Only the diff** (legacy grandfathered) | PR | whole project | PR |
+| Custom house rules | **One JSON line** | prompt config | quality profiles | prompt config |
+| Setup | **`npx ai-diff-check init`** | GitHub app | server + scanner | app |
+
+Not a replacement for deep static analysis or a human reviewer — it's the fast, free gate that catches AI-agent mess *before* the commit, deterministically, with zero noise on a clean diff.
+
+## What it checks
+
+| Check | Catches | Status |
+|-------|---------|--------|
+| `STUB` | Empty catch blocks, TODOs, "not implemented" throws, leftover console.log | ✅ built |
+| `OVERSIZE` | Monolith files / 200+ line components, with a proposed split | ✅ built |
+| `PHANTOM-DEP` | Imports of packages that don't exist or aren't installed (AI hallucinations / slopsquat risk) | ✅ built |
+| `DUPLICATE` | New functions that repeat code already in your codebase | ✅ built |
+| `DELETION` | Removed validation, error handling, or tests the task didn't ask to remove | ✅ built |
+| `UNREFERENCED` | New exports with zero references — generated "just in case" | ✅ built |
+| `NO-TEST` | Source logic changed but the matching test file didn't | ✅ built |
+| `STANDARD` | Your house rules from `aidiff.config.json` — each pointing at the approved alternative | ✅ built |
+| `REUSE` | New components whose markup forks an existing component — same JSX skeleton, different wiring | ✅ built |
+
+## Usage (npm release pending — run from a clone until then)
+
+```bash
+npx ai-diff-check                  # review working tree vs main (or --base <ref>)
+npx ai-diff-check init             # starter config + pre-commit hook (husky-aware)
+npx ai-diff-check ignore DUP-104   # permanently silence a false positive by id
+npx ai-diff-check --ci             # GitHub annotations + JSON for CI
+```
+
+Exit code `1` on any error-severity finding (and on warnings too with `"strict": true`) — wire it into husky/pre-commit or CI to gate merges.
+
+## Pre-commit gate
+
+`init` wires the hook for you: `.husky/pre-commit` if your repo uses husky, plain `.git/hooks/pre-commit` otherwise — never overwriting what's already there. Every commit then gets the vibe check; findings with error severity block it.
+
+## CI
+
+One step in any workflow — findings land as inline annotations on the PR diff:
+
+```yaml
+jobs:
+  vibe-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so the diff base resolves
+      - uses: prashant1234568/ai-diff-check@main
+```
+
+Under the hood that's `--ci` mode: `::error file=…,line=…::message → fix` workflow commands plus a JSON report for anything else to consume. This repo runs it on its own PRs — the reviewer reviews itself.
+
+## For coding agents
+
+**MCP server mode** — let the agent vibe-check its own diffs before declaring a task done:
+
+```json
+{ "mcpServers": { "ai-diff-check": { "command": "npx", "args": ["ai-diff-check", "mcp"] } } }
+```
+
+The `vibe_check` tool reviews the current diff and returns the trust score plus a scoped fix list. Zero extra dependencies — the MCP server is ~150 lines of the same lean codebase.
+
+**`--fix-prompt`** — the same fix list as a copy-pasteable prompt for any agent:
+
+```bash
+ai-diff-check --fix-prompt | pbcopy   # paste into your agent, let it clean up after itself
+```
+
+## Configuration
+
+Optional `aidiff.config.json` in the repo root (defaults shown):
+
+```jsonc
+{
+  "maxFileLines": 400,       // OVERSIZE: file line limit
+  "maxComponentLines": 200,  // OVERSIZE: component line limit (.tsx/.jsx)
+  "strict": false,           // true → warnings also fail the run (exit 1)
+  "ignore": [],              // finding ids to silence, e.g. ["STUB-441"]
+  "standards": [             // your house rules — diff-scoped, so legacy is grandfathered
+    {
+      "ban": "fetch(",                        // substring to ban ("pattern" takes a regex instead)
+      "in": "src/**",                         // optional glob scope
+      "use": "apiClient from @/lib/api",      // the approved alternative, shown as the fix
+      "docs": "docs/api-standards.md",        // optional pointer to your standards doc
+      "severity": "error"                     // error | warn | info (default warn)
+    }
+  ]
+}
+```
+
+New code that breaks a rule gets flagged with your own alternative as the fix; old violations stay quiet until touched — a ratchet, not a rewrite mandate.
+
+Every finding prints a stable id like `[OVERSIZE-377]` — add it to `ignore` to permanently silence a false positive. A malformed config never falls back silently: the run stops with exit code `2` and the reason.
+
+## License
+
+MIT © Prashant Parmar