vibeclean 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithon
+
+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,245 @@
+# 🧹 vibeclean
+
+Audit your codebase for the mess vibe coding left behind.
+
+AI assistants write great code. They just write it differently every time. `vibeclean` finds the inconsistencies.
+
+Terminal screenshot/GIF:
+- Add `assets/vibeclean-demo.gif` (recommended for Vibeathon voting)
+- Keep it short (3-8s) and show `npx vibeclean` + score + `--rules` output
+
+## Quick Start
+
+```bash
+npx vibeclean
+```
+
+One command. Zero config.
+
+PR-focused mode:
+
+```bash
+npx vibeclean --changed --base main
+```
+
+## What It Detects
+
+- 🔀 Pattern inconsistencies (multiple HTTP clients, mixed async styles, mixed imports)
+- 📝 Naming chaos (camelCase + snake_case + mixed file naming)
+- 🗑️ AI leftovers (TODO/FIXME, console logs, placeholders, localhost URLs)
+- 📦 Dependency bloat (unused packages, duplicate functionality, deprecated libs)
+- 💀 Dead code (orphan files, unused exports, stubs)
+- ⚠️ Error handling gaps (empty catches, unhandled async, mixed error patterns)
+
+## Example Output
+
+```text
+  🧹 vibeclean v1.0.0 — Cleaning up the vibe
+
+  Scanning project... ✓ Found 124 source files in 0.8s
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ⚠️  NAMING INCONSISTENCY                         Score: 6/10
+     ├─ camelCase: 72%, snake_case: 28%
+     ├─ Mixed directories: 4
+     └─ Component filename mismatches: 3
+
+  ⚠️  PATTERN INCONSISTENCY                        Score: 8/10
+     ├─ HTTP clients: fetch (12), axios (5), got (1)
+     ├─ Mixed async: async/await (78%), .then() (22%)
+     └─ Module style: import files 25, require files 6
+
+  🚨 AI LEFTOVERS                                  Score: 7/10
+     ├─ console.* statements: 23
+     ├─ TODO/FIXME markers: 12 (8 AI-like)
+     └─ Placeholders/localhost: 9
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  📊 VIBE CLEANLINESS SCORE: 38/100
+     Your codebase has significant vibe coding debt.
+
+  🧹 Found 67 issues across 6 categories
+  📋 Run vibeclean --rules to generate AI rules file
+```
+
+## Vibe Cleanliness Score
+
+Each category gets a score from `0-10` (higher = more inconsistency). `vibeclean` converts this into an overall score out of `100` (higher = cleaner).
+
+- `80-100`: consistent and clean
+- `60-79`: manageable debt
+- `40-59`: visible inconsistency debt
+- `<40`: significant vibe debt
+
+## Generate Rules for AI Assistants
+
+```bash
+vibeclean --rules
+vibeclean --rules --cursor --claude
+```
+
+Generated files:
+
+- `.vibeclean-rules.md`
+- `.cursorrules` (optional)
+- `CLAUDE.md` (optional)
+
+These encode your dominant project conventions so future AI-assisted code stays consistent.
+
+## CLI Usage
+
+```text
+Usage: vibeclean [options] [directory]
+
+Arguments:
+  directory                Project directory to scan (default: current directory)
+
+Options:
+  -f, --fix               Apply safe autofixes before scoring (TODO/commented code/noisy console)
+  --json                  Output results as JSON
+  --report <format>       Output format: text, json, markdown (default: text)
+  --report-file <path>    Write report output to file
+  --profile <name>        Preset profile: app, library, cli (default: app)
+  --changed               Scan only changed files in the current git working tree
+  --base <ref>            Git base ref to diff against when using --changed (default: HEAD)
+  --baseline              Compare against baseline file and detect regressions
+  --baseline-file <path>  Baseline file path for compare/write (default: .vibeclean-baseline.json)
+  --write-baseline        Write current report to baseline file
+  --rules                 Generate .vibeclean-rules.md file
+  --cursor                Also generate .cursorrules file
+  --claude                Also generate CLAUDE.md file
+  --min-severity <level>  Minimum severity: low, medium, high (default: low)
+  --fail-on <level>       Fail if findings hit this severity: low, medium, high
+  --max-issues <n>        Fail if total issues exceed this number
+  --min-score <n>         Fail if overall score is below this threshold (0-100)
+  --ignore <patterns>     Additional ignore patterns (comma-separated)
+  --max-files <n>         Maximum files to scan (default: 500)
+  -q, --quiet             Summary output only
+  -v, --version           Show version
+  -h, --help              Show help
+```
+
+## CI / PR Quality Gates
+
+```bash
+# Fail CI on high-severity findings in changed files only
+vibeclean --changed --base main --fail-on high
+
+# Fail if quality drifts too far
+vibeclean --min-score 75 --max-issues 20
+```
+
+When a gate fails, vibeclean exits with status code `1`.
+
+## Profiles
+
+```bash
+# Default
+vibeclean --profile app
+
+# Libraries: ignores common example/benchmark folders
+vibeclean --profile library
+
+# CLI projects: reduces test/bin leftovers noise
+vibeclean --profile cli
+```
+
+Profiles apply sensible defaults, but you can still override with `.vibecleanrc` and `--ignore`.
+
+## Baseline Compare
+
+```bash
+# Create baseline snapshot
+vibeclean --write-baseline --baseline-file .vibeclean-baseline.json
+
+# Compare current branch against baseline (fails on regressions by default)
+vibeclean --baseline --baseline-file .vibeclean-baseline.json
+```
+
+Baseline compare tracks:
+- overall score drift
+- issue count drift
+- high-severity finding drift
+- category-level score regressions
+
+## Markdown PR Report
+
+```bash
+# Print markdown to stdout
+vibeclean --report markdown
+
+# Write markdown report to file for PR comments/artifacts
+vibeclean --report markdown --report-file vibeclean-report.md
+```
+
+## Autofix Mode
+
+```bash
+vibeclean --fix
+```
+
+Safe autofix currently removes:
+- TODO/FIXME/HACK/XXX comment lines
+- obvious commented-out code blocks
+- standalone `console.log/debug/trace` lines
+
+After fixes are applied, vibeclean re-scores the project and reports what changed.
+
+## Configuration
+
+Create `.vibecleanrc` or `.vibecleanrc.json` in project root:
+
+```json
+{
+  "maxFiles": 500,
+  "changedOnly": false,
+  "changedBase": "main",
+  "profile": "app",
+  "baseline": false,
+  "baselineFile": ".vibeclean-baseline.json",
+  "failOnRegression": true,
+  "reportFormat": "text",
+  "ignore": ["scripts/", "*.test.js", "*.spec.js"],
+  "severity": "medium",
+  "failOn": "high",
+  "maxIssues": 30,
+  "minScore": 70,
+  "rules": {
+    "naming": true,
+    "patterns": true,
+    "leftovers": true,
+    "dependencies": true,
+    "deadcode": true,
+    "errorhandling": true
+  },
+  "allowedPatterns": {
+    "httpClient": "fetch",
+    "asyncStyle": "async-await",
+    "stateManagement": "zustand"
+  }
+}
+```
+
+## Why vibeclean?
+
+ESLint checks syntax and style. SonarQube checks quality and vulnerabilities.
+
+`vibeclean` checks the specific mess that AI coding creates: pattern inconsistency across sessions.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Development
+
+```bash
+npm install
+npm test
+node bin/vibeclean.js .
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/bin/vibeclean.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { runAudit } from "../src/index.js";
+import { writeBaselineSnapshot } from "../src/baseline.js";
+import { renderMarkdownReport } from "../src/markdown-report.js";
+import { renderReport } from "../src/reporter.js";
+
+async function readToolVersion() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const rootDir = path.resolve(path.dirname(currentFile), "..");
+  try {
+    const raw = await fs.readFile(path.join(rootDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version || "1.0.0";
+  } catch {
+    return "1.0.0";
+  }
+}
+
+async function main() {
+  const version = await readToolVersion();
+
+  const program = new Command();
+  program
+    .name("vibeclean")
+    .description("Audit your codebase for the mess vibe coding left behind.")
+    .version(version, "-v, --version", "Show version")
+    .argument("[directory]", "Project directory to scan", process.cwd())
+    .option("-f, --fix", "Apply safe autofixes before scoring (TODO/commented code/noisy console)")
+    .option("--json", "Output results as JSON")
+    .option("--report <format>", "Output format: text, json, markdown", "text")
+    .option("--report-file <path>", "Write report output to file")
+    .option("--profile <name>", "Preset profile: app, library, cli", "app")
+    .option("--changed", "Scan only changed files in the current git working tree")
+    .option("--base <ref>", "Git base ref to diff against when using --changed", "HEAD")
+    .option("--baseline", "Compare current report against a baseline snapshot file")
+    .option("--baseline-file <path>", "Baseline file path for compare/write", ".vibeclean-baseline.json")
+    .option("--write-baseline", "Write current report to the baseline snapshot file")
+    .option("--rules", "Generate .vibeclean-rules.md file")
+    .option("--cursor", "Also generate .cursorrules file")
+    .option("--claude", "Also generate CLAUDE.md file")
+    .option("--min-severity <level>", "Minimum severity to report: low, medium, high", "low")
+    .option("--fail-on <level>", "Fail with exit code 1 if findings reach this severity: low, medium, high")
+    .option("--max-issues <n>", "Fail with exit code 1 if total issues exceed this number")
+    .option("--min-score <n>", "Fail with exit code 1 if overall score falls below this threshold (0-100)")
+    .option("--ignore <patterns>", "Additional patterns to ignore (comma-separated)")
+    .option("--max-files <n>", "Maximum files to scan", "500")
+    .option("-q, --quiet", "Only show summary, not individual issues")
+    .action(async (directory, options) => {
+      const spinner = ora("Running vibeclean diagnostics...").start();
+
+      try {
+        const result = await runAudit(directory, {
+          ...options,
+          maxFiles: Number.parseInt(options.maxFiles, 10),
+          maxIssues: Number.parseInt(options.maxIssues, 10),
+          minScore: Number.parseInt(options.minScore, 10),
+          profile: options.profile,
+          baseline: Boolean(options.baseline),
+          baselineFile: options.baselineFile,
+          reportFormat: options.report,
+          reportFile: options.reportFile || null,
+          changedOnly: Boolean(options.changed),
+          changedBase: options.base,
+          minSeverity: options.minSeverity,
+          failOn: options.failOn,
+          version
+        });
+
+        spinner.stop();
+
+        let baselineWriteResult = null;
+        if (options.writeBaseline) {
+          baselineWriteResult = await writeBaselineSnapshot(
+            result.rootDir,
+            options.baselineFile,
+            result.report
+          );
+        }
+
+        const reportFormat = options.json
+          ? "json"
+          : String(result.config?.reportFormat || options.report || "text").toLowerCase();
+        const payload = {
+          report: result.report,
+          generatedRules: result.generatedRules
+        };
+
+        if (reportFormat === "json") {
+          const jsonOutput = JSON.stringify(payload, null, 2);
+          if (options.reportFile) {
+            await fs.writeFile(options.reportFile, `${jsonOutput}\n`, "utf8");
+            console.log(chalk.green(`Saved JSON report to ${options.reportFile}`));
+          } else {
+            console.log(jsonOutput);
+          }
+        } else if (reportFormat === "markdown") {
+          const markdownOutput = renderMarkdownReport(result.report);
+          if (options.reportFile) {
+            await fs.writeFile(options.reportFile, markdownOutput, "utf8");
+            console.log(chalk.green(`Saved Markdown report to ${options.reportFile}`));
+          } else {
+            console.log(markdownOutput);
+          }
+        } else {
+          console.log(renderReport(result.report, { quiet: Boolean(options.quiet) }));
+
+          if (result.generatedRules?.length) {
+            console.log("");
+            console.log(chalk.green.bold("  📋 Generated rule files"));
+            for (const item of result.generatedRules) {
+              console.log(`  ${chalk.green("✓")} ${item.path}`);
+            }
+          }
+
+          if (baselineWriteResult) {
+            console.log("");
+            console.log(chalk.green.bold("  📌 Baseline updated"));
+            console.log(`  ${chalk.green("✓")} ${baselineWriteResult.path}`);
+          }
+
+          if (result.report.gateFailures?.length) {
+            console.log("");
+            console.log(chalk.red.bold("  ⛔ Quality gates failed"));
+            for (const failure of result.report.gateFailures) {
+              console.log(`  ${chalk.red("•")} ${failure}`);
+            }
+          }
+        }
+
+        if (baselineWriteResult && reportFormat !== "text") {
+          console.log(chalk.green(`Baseline updated: ${baselineWriteResult.path}`));
+        }
+
+        if (result.report.gateFailures?.length) {
+          process.exitCode = 1;
+        }
+      } catch (error) {
+        spinner.fail("vibeclean failed");
+        console.error(chalk.red(error?.message || "Unknown error"));
+        process.exitCode = 1;
+      }
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+main();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "vibeclean",
+  "version": "1.0.0",
+  "description": "Audit your codebase for vibe coding mess. Detect inconsistencies, AI leftovers, and pattern chaos with one command.",
+  "type": "module",
+  "bin": {
+    "vibeclean": "bin/vibeclean.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/vibeclean.js",
+    "check": "node ./bin/vibeclean.js --quiet",
+    "test": "node --test"
+  },
+  "keywords": [
+    "vibe-coding",
+    "code-quality",
+    "consistency",
+    "audit",
+    "cli",
+    "linter",
+    "developer-tools",
+    "ai-code",
+    "technical-debt",
+    "code-review",
+    "cleanup",
+    "dead-code",
+    "unused-dependencies",
+    "cursor",
+    "copilot",
+    "claude",
+    "chatgpt"
+  ],
+  "author": "Pithon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/piths/vibeclean.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "acorn": "^8.11.0",
+    "acorn-jsx": "^5.3.0",
+    "acorn-walk": "^8.3.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "glob": "^10.0.0",
+    "ignore": "^5.3.0",
+    "ora": "^8.0.0"
+  }
+}