badvibes

badvibes

Lint for AI slop. Audits a repo and prints a Vibe Score from 0 to 100.

badvibes is a zero-config CLI that scans a repository for the things AI-assisted codebases tend to accumulate: missing .env.example, committed secrets, giant files, TODO/FIXME drifts, duplicated blocks, placeholder stubs, missing tests, missing CI, thin READMEs, unresolved imports.

It's deterministic. No LLMs. Just rules, file scans, and a little bit of judgment.

Quick start

npx badvibes .

That's it. No config file, no setup.

Example output

💀 BadVibes Report for ./my-app

Vibe Score: 63/100 (Neutral)

CRITICAL
- Missing .env.example despite env usage  (src/api/server.ts)
- Potential committed secret (AWS access key id)  (src/config.ts)

WARNINGS
- File exceeds 600 LOC (712 lines)  (src/routes/handler.ts:712)
- 17 TODO/FIXME/HACK/TEMP/XXX markers found. Top: src/utils/helpers.ts (9), src/api/server.ts (5), src/lib/parser.ts (3)
- Duplicate 6-line block found in 3 files  (src/a.ts:42, src/b.ts:17)

INFO
- Possibly unused dependency: lodash  (package.json)
- Mixed filename conventions in src/components/: kebab(4), pascal(3)

Verdict:
Functional, but worth cleaning up before shipping.

Why

AI pair-programming produces code faster than anyone can review it. That code tends to ship with the same handful of problems:

• secrets hard-coded during "let me just test this"
• mock for now / sample data / // TODO: real implementation
• giant files that were refactored by "just extend this one"
• three copies of the same function in different folders
• no .env.example to onboard the next human

badvibes puts a number on it.

Install

# one-off
npx badvibes .

# as a dev dependency
npm install --save-dev badvibes

Requires Node.js 18+.

Usage

badvibes            # audit cwd
badvibes .          # same
badvibes ./my-app   # audit another path

badvibes --json .                        # machine-readable output
badvibes --strict .                      # harsher scoring + non-zero exit if score < 70
badvibes --roast .                       # roast issue descriptions
badvibes --no-funny .                    # dry verdict
badvibes --max-file-lines 800 .          # override large-file threshold
badvibes --help
badvibes --version

Flags

GitHub Action

Use the GitHub Action to run badvibes on every pull request and post a clean PR comment with the score, verdict, and issue table.

name: badvibes

on:
  pull_request:

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  badvibes:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run badvibes
        uses: marco-trotta1/badvibes@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          strict: true

With strict: true, the action runs badvibes --strict and fails the check only when the resulting score is below 70. Set strict: false to keep it informational.

JSON shape

{
  "target": "/abs/path/to/repo",
  "score": 63,
  "band": "Neutral",
  "strict": false,
  "summary": { "critical": 1, "warnings": 3, "info": 2 },
  "issues": [
    {
      "severity": "critical",
      "code": "missing-env-example",
      "message": "Missing .env.example despite env usage",
      "file": ".env.example",
      "line": null
    }
  ],
  "verdict": "Functional, but worth cleaning up before shipping."
}

Score bands

Scores start at 100 and subtract per issue. Representative weights:

--strict multiplies these by 1.5.

What it checks

1. Env example — detects process.env / import.meta.env usage and warns if .env.example is missing.
2. Secrets — pattern + high-entropy heuristics for AWS, Google, GitHub, Slack, Stripe, OpenAI, Anthropic, JWTs, private keys, and bearer tokens. Skips fixtures and placeholders.
3. Tests — looks for __tests__/, *.test.*, *.spec.*. Flags critical if src/api, src/server, src/routes, or src/lib exist without tests.
4. Large files — configurable warn / severe thresholds. Skips node_modules, dist, build, coverage, .git, lockfiles, binaries.
5. Markers — counts TODO, FIXME, HACK, TEMP, XXX. Reports top offenders.
6. Placeholders / stubs — flags sample data, mock for now, temporary, fake data, placeholder, etc. in source (not docs).
7. Duplicate logic — hashes normalized 6-line windows across source files.
8. Unused dependencies — compares package.json deps to imports/requires/scripts. Conservative; only reports info.
9. Naming consistency — flags directories that mix kebab / pascal / snake / camel filename conventions.
10. CI — looks for GitHub Actions, GitLab CI, CircleCI, Travis, Azure Pipelines, Bitbucket, Drone.
11. README — checks for description, install section, usage section.
12. Broken imports — resolves relative imports and flags unresolved ones.

Programmatic API

import { analyze } from 'badvibes';

const report = await analyze({
  target: './my-app',
  strict: false,
  funny: true,
  maxFileLines: 600,
});

console.log(report.score, report.band);

Roadmap

• --fix suggestions for common issues
• pluggable checks via badvibes.config.ts
• per-project ignore rules
• HTML report mode
• severity thresholds (e.g. --min-score 75)
• more language-specific heuristics (Python, Go)

Contributing

Small, focused PRs welcome. See CONTRIBUTING.md.

Each check lives in src/checks/ and is a pure function over a RepoContext. Add yours, wire it into src/index.ts, and drop a test in tests/checks.test.ts.

npm install
npm test
npm run dev .      # run against cwd
npm run build      # emit dist/

License

MIT — see LICENSE.