VibeCode QA

Code health scanner for the AI coding era.

One command. Canonical checks. AI-powered fixes. Zero config.

npx @vibecodeqa/cli

What it does

vcqa scans your codebase and produces a scored health report with actionable findings. Auto-detects your stack (React, Vue, Svelte, Flutter, monorepos) and runs canonical checks across 7 categories.

Scan → See issues → AI fixes them → Score improves.

npx @vibecodeqa/cli                     # scan + full HTML report
npx @vibecodeqa/cli fix --ai            # AI-powered code fixes
npx @vibecodeqa/cli --skip-tests --top  # fast scan + top issues

Install everywhere

# CLI (one command, no install needed)
npx @vibecodeqa/cli

# GitHub Action (automatic PR scanning)
- uses: vibecodeqa/action@v1
  with:
    fail-under: "70"

# VS Code Extension
ext install vibecodeqa

# MCP Server (for AI coding agents)
claude mcp add vcqa -- npx @vibecodeqa/mcp

# Programmatic API
import { scan } from "@vibecodeqa/cli/core";
const report = await scan("./src");

AI-Powered Fix

Don't just find problems — fix them:

npx @vibecodeqa/cli fix --ai                      # fix all issues
npx @vibecodeqa/cli fix --ai --check security      # fix only security
npx @vibecodeqa/cli fix --ai --dry-run             # preview without applying

Uses Claude to read your code context, understand the issue, and generate a targeted fix. Requires ANTHROPIC_API_KEY.

Checks

Foundations (23%)

Check	Weight	What it measures
Structure	6%	Standard files, lockfile, test-to-source ratio
Lint	5%	Biome or ESLint errors/warnings
Types	6%	TypeScript compilation errors
Type Safety	3%	as any, @ts-ignore, non-null assertions, unsafe double/context casts
Standards	3%	File naming, large files, code smells

Quality (28%)

Check	Weight	What it measures
Complexity	5%	Cognitive complexity per function
Duplication	3%	Copy-pasted 6+ line blocks
Error Handling	3%	Empty catch, throw string, floating promises
React Patterns	3%	Conditional hooks, missing keys
Flutter Health	—	Flutter package health, widget/integration tests, generated Dart files
Accessibility	4%	img alt, click handlers, form labels
Docs	3%	README quality, JSDoc coverage
Best Practices	3%	CI/CD, supply chain, repo hygiene
HTML Quality	—	Static site: meta tags, broken links, heading hierarchy, render-blocking scripts
Frontend Health	2%	UI framework conflicts, mixed icons, unoptimized images, heavy imports
Styling	1%	Hardcoded colors, mixed approaches, !important, inconsistent spacing
Env Validation	1%	.env hygiene, .env.example drift
Git Hygiene	1%	Merge conflicts, commit quality, large/binary files
Resource Lifecycle (memory-safety)	1%	Interval/listener leaks, unclosed observers, global pollution

Testing (13%)

Deep assessment: pyramid presence, execution, coverage, file pairing, quality metrics, E2E detection.

Architecture (9%)

Check	Weight	What it measures
Architecture	5%	Import graph, circular deps, god modules, orphans
Performance	4%	Barrel imports, heavy deps, dynamic import opportunities
Container Health	—	Dockerfile best practices, .dockerignore, pinned images

Security (16%)

Check	Weight	What it measures
Secrets	6%	Hardcoded keys (AWS, GitHub, Stripe, OpenAI, Anthropic)
Security	5%	31 CWE patterns (XSS, injection, SSRF, CORS)
Dependencies	5%	npm audit CVEs, outdated packages

AI Readiness (9%)

Check	Weight	What it measures
Confusion Index	4%	Naming ambiguity that confuses LLMs
Context Locality	5%	Token density, import depth, circular deps

AI Analysis (PRO)

Check	What it measures
Doc Coherence	Contradictions between docs and code
Code Coherence	Internal inconsistencies across modules
Comment Staleness	Stale TODOs, numeric mismatches, commented-out code
Dead Patterns	Leftover code from incomplete refactors
Test Audit	Fake/shallow tests that inflate coverage
File Cohesion	Files mixing multiple responsibilities
Design Consistency	Visual inconsistency across components

GitHub Action

- uses: vibecodeqa/action@v1
  with:
    fail-under: "70"          # quality gate
    auto-fix: "true"          # AI fixes pushed to PR
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Features: PR comments, SARIF upload, quality gates, AI autofix.

Programmatic API

import { scan, CHECK_META } from "@vibecodeqa/cli/core";

const report = await scan("./src", {
  skipTests: true,
  checks: ["security", "testing"],
  onProgress: (check, result, i, total) => {
    console.log(`${i + 1}/${total} ${check}: ${result.grade}`);
  },
});

console.log(`${report.grade} ${report.score}/100`);

MCP Server

Give AI coding agents real-time code health context:

claude mcp add vcqa -- npx @vibecodeqa/mcp

7 tools: vcqa_score, vcqa_scan, vcqa_file_health, vcqa_check, vcqa_explain, vcqa_fix, vcqa_delta.

Delta Reports

Every scan compares against the previous one. The --markdown and --pr-comment outputs show what changed:

📈 +6 vs previous · 15 fixed · 2 new

- ✅ lint: 45 → 100 (+55)
- ✅ confusion: 20 → 93 (+73)
- ⚠️ standards: 50 → 48 (-2)

The vcqa fix command runs a baseline scan before fixing and a final scan after, producing a delta report saved to .vibe-check/delta.md.

Programmatic delta

import { scan, computeDelta, formatDeltaMarkdown } from "@vibecodeqa/cli/core";

const before = await scan("./src");
// ... make changes ...
const after = await scan("./src");
const delta = computeDelta(before, after);
console.log(formatDeltaMarkdown(delta));

Configuration

Create .vcqa.json (or add a "vcqa" key to package.json):

{
  "checks": {
    "react": { "enabled": false },
    "container-health": { "ignore": ["Dockerfile.dev"] },
    "complexity": { "ignore": ["src/legacy/**"] },
    "security": { "ignore": ["src/test-helpers/**"] }
  },
  "ignore": ["generated/**", "vendor/**", "*.min.js"],
  "failUnder": 70
}

Configuration options

Key	Type	Description
checks.<name>.enabled	boolean	Disable a check entirely
checks.<name>.ignore	string[]	Glob patterns to skip for this check
ignore	string[]	Global glob patterns to skip everywhere
failUnder	number	Exit code 1 if score is below this (CI quality gate)

Alternative: package.json

{
  "vcqa": {
    "checks": { "react": { "enabled": false } },
    "failUnder": 70
  }
}

Monorepo support

Auto-detects workspace tools: pnpm, npm, yarn, bun, lerna, turborepo, nx, melos.

When a monorepo is detected, vcqa:

• Resolves all workspace packages from pnpm-workspace.yaml, package.json workspaces, lerna.json, etc.
• Scans packages/*/src/ (or wherever each package's source lives)
• Runs supported tools from the cwd where their config lives and normalizes findings back to repo-root paths
• Checks tsconfig.json in each workspace package for strict mode
• Detects lockfiles in root or packages (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, bun.lock)
• Scopes confusion checks per-package (no false positives from cross-package names)

npx @vibecodeqa/cli ~/my-monorepo    # auto-detects workspace, scans all packages

Repo and folder discovery is deterministic core functionality. AI/Pro features may explain the detected architecture or suggest config, but they are not required for scanning.

Stack detection

Auto-detects: TypeScript/JavaScript/Dart, React/Vue/Svelte/Flutter, Vite/Webpack/esbuild, vitest/jest, Biome/ESLint, pnpm/npm/yarn/bun.

CLI options

Flag	Description
--skip-tests	Skip test execution (fast mode)
--ci	CI mode (exit 1 if score < 60)
--fail-under N	Exit 1 if score < N
--json	JSON output
--badge	Generate SVG badge
--sarif	SARIF for GitHub Code Scanning
--upload	Upload to dashboard
--top [N]	Show top N issues
--diff [base]	Issues in changed files only
--markdown	Markdown summary
--pr-comment	PR comment (needs GITHUB_TOKEN)
--annotations	GitHub Actions annotations
--watch	Re-scan on file changes

Links

• Website: https://vibecodeqa.online
• Dashboard: https://app.vibecodeqa.online
• GitHub Action: https://github.com/vibecodeqa/action
• VS Code: https://github.com/vibecodeqa/vscode
• MCP: https://github.com/vibecodeqa/mcp

MIT — Free forever as a CLI tool.