The checks¶

A scan runs 38 checks across 7 weighted categories. Each check is scored 0–100 and weighted into a single composite score. The weights of the 37 checks that carry category metadata sum to 100; Pro/AI Analysis and platform-specific zero-weight checks are informational unless promoted into the scoring model. The CHECK_META table in the @vibecodeqa/schema package is the source of truth for the exact current check list and weights.

Full check inventory¶

Every check a scan runs, in run order, with the category and weight it contributes.

dead-code is a synthetic check: it is derived from the performance runner's findings, has no CHECK_META row, and is marked scoreImpact: false, so it appears in report.json and the HTML report but never moves the score.

Foundations (23% of score)¶

Project Structure¶

weight 6% · high priority

What it checks. Checks for standard project files: package.json, tsconfig.json, LICENSE, README, .gitignore, lockfile. Verifies test-to-source file ratio and that essential scripts (test, build) exist.

Lint¶

weight 5% · high priority

What it checks. Runs the project's linter (Biome or ESLint, auto-detected) and counts errors and warnings. Lint rules catch bugs, enforce consistency, and prevent common mistakes before they reach production.

Type Check¶

weight 6% · critical priority

What it checks. Runs tsc --noEmit to find TypeScript compilation errors. Type errors mean the code may crash at runtime in ways the compiler could have prevented.

Type Safety¶

weight 3% · medium priority

What it checks. Counts unsafe type patterns: 'as any' casts, explicit ': any' annotations, @ts-ignore directives, @ts-nocheck, and non-null assertions (!.). Each weakens the type system's protection.

Code Standards¶

weight 3% · high priority

What it checks. Checks coding conventions: file naming (PascalCase for components, kebab-case for modules), file size limits (>300 lines flagged), code smells (console.log, var, ==, eval, innerHTML, TODO/FIXME), config hygiene (strict mode), and framework best practices (Tailwind vs inline styles).

Quality (30% of score)¶

Error Handling¶

weight 3% · high priority

What it checks. Detects poor error handling: empty catch blocks, throw string literals, swallowed .catch(), floating promises, JSON.parse without try-catch, infinite loops, process.exit() in library code, and missing unhandledRejection handlers.

Complexity¶

weight 5% · high priority

What it checks. Measures cognitive complexity of each function: how many branches (if/else/switch/for/while/ternary/&&/||) and how many lines. Functions over 60 lines or with complexity over 15 are flagged.

Duplication¶

weight 3% · medium priority

What it checks. Detects copy-pasted code blocks of 6+ lines across source files. Duplication is measured as a percentage of total source lines involved in duplicate blocks.

Documentation¶

weight 3% · low priority

What it checks. Checks README quality (existence, length, sections) and JSDoc coverage (what percentage of exported functions/classes have documentation comments).

React Patterns¶

weight 3% · high priority

What it checks. Checks React-specific patterns. Configured React ESLint plugins are the primary source for React diagnostics: eslint-plugin-react-hooks, eslint-plugin-react, eslint-plugin-react-refresh, eslint-plugin-jsx-a11y, and the newer React ESLint plugin families. VCQA heuristics fill gaps when those tools are absent or do not cover a visualized metric, including conditional hook calls, missing key props in .map(), index keys, prop spreading on DOM elements, useEffect dependency hazards, direct DOM queries, inline style pressure when Tailwind is present, and missing Error Boundaries. Monitor reports group findings into React Health categories: hooks, effects, rendering, component structure, error boundaries, compiler readiness, Fast Refresh, and accessibility.

Flutter Health¶

advisory · high priority

What it checks. Checks Flutter-specific project health across single-package and multi-package roots: package discovery, analysis_options.yaml coverage, flutter_lints, flutter_test, widget tests, integration_test, generated Dart files, and pubspec hygiene.

Accessibility¶

weight 4% · high priority

What it checks. Runs standard static accessibility tools first, then applies VibeCode QA fallback heuristics for gaps.

• JSX/TSX is checked with eslint-plugin-jsx-a11y through ESLint's programmatic Linter API.
• Static HTML is checked with html-validate:standard and html-validate:a11y.
• Built-in heuristics cover Vue/Svelte templates, missing accessible names, heading-order skips, missing landmarks, static color contrast, hidden focus indicators, click-only controls, autoFocus usage, positive tabIndex, dialog focus basics, and missing html lang.
• Issues include file, line, rule, selector, WCAG category, severity, and a suggested fix when known.

Best Practices¶

weight 3% · medium priority

What it checks. Advisory check for industry-standard CI/CD, supply chain, and repo hygiene practices. Checks: GitHub Actions with explicit permissions, OIDC instead of long-lived tokens, pinned action SHAs, frozen lockfile in CI, committed lockfile, engine constraints, SECURITY.md, CODEOWNERS, CONTRIBUTING.md, .env.example, pre-commit hooks, automated dependency updates (Dependabot/Renovate).

Testing (13% of score)¶

Testing¶

weight 13% · critical priority

What it checks. Deep assessment of test quality across 6 dimensions: pyramid presence (unit/integration/component/E2E layers), test execution (pass/fail), coverage (statement/branch/line/function), file pairing (test file per source file), test quality (assertion density, mock ratio, snapshot ratio), and E2E tool detection (Playwright/Cypress).

Architecture (9% of score)¶

Architecture¶

weight 5% · high priority

What it checks. Analyzes the import graph to detect structural problems: circular dependencies, god modules (imported by >50% of files), orphan modules (dead code), high fan-out (importing too many modules), and connector modules (high coupling). Generates an SVG architecture diagram.

Performance¶

weight 4% · medium priority

What it checks. Detects barrel imports that defeat tree-shaking, heavy dependencies with lighter alternatives, static imports of large libraries that could be lazy-loaded, and runtime CSS-in-JS overhead.

Security (16% of score)¶

Secrets¶

weight 6% · critical priority

What it checks. Scans source files for hardcoded secrets: AWS keys, GitHub tokens, Stripe keys, OpenAI/Anthropic API keys, Google API keys, private keys, and generic secret patterns. Checks 14 regex patterns against every non-test source file. Delegates to gitleaks when installed.

Security Patterns¶

weight 5% · critical priority

What it checks. Static analysis for 31 vulnerability patterns mapped to CWE IDs. Covers: XSS, injection, weak crypto, prototype pollution, path traversal, SSRF, credential storage (localStorage/sessionStorage/cookies/connection strings/hardcoded passwords), and missing security headers. Delegates to eslint-plugin-security when installed (adds ReDoS, timing attacks, non-literal require/fs).

Dependencies¶

weight 5% · high priority

What it checks. Runs npm/pnpm audit to find known vulnerabilities (CVEs) in dependencies. Also checks for outdated packages — major version gaps indicate potential security debt and breaking API changes.

LLM Readiness (9% of score)¶

Confusion Index¶

weight 4% · high priority

What it checks. Measures naming ambiguity that causes LLMs to misunderstand or edit the wrong code. Checks: file name confusability (Levenshtein distance + synonym detection), generic function/variable names, export name collisions across files, and ambiguous abbreviations.

Context Locality¶

weight 5% · high priority

What it checks. Measures how self-contained code is for LLM consumption. Checks: token density per file, import count, circular dependencies, and context sinks (files that import many modules but export little). Based on the finding that LLMs lose 30%+ accuracy for information in the middle of long contexts.

AI Analysis (Pro · informational)¶

These checks need a VCQA_PRO_KEY in the environment. Without it they report status unavailable and are excluded from the score. There are seven of them; file-cohesion and design-consistency do not yet have a detailed section below.

Doc Coherence¶

weight Pro · high priority

What it checks. LLM-powered analysis that detects contradictions between documentation and code. Finds stale README claims, incorrect JSDoc parameters, outdated CHANGELOG references, and comments that no longer match the implementation.

Code Coherence¶

weight Pro · high priority

What it checks. LLM-powered analysis that detects internal contradictions within the codebase itself. Finds inconsistent validation logic, conflicting defaults across modules, naming convention drift, dead config flags, and behavioral mismatches.

Comment Staleness¶

weight Pro · medium priority

What it checks. Detects stale comments: TODOs older than 6 months, numeric claims that don't match code ("handles 3 cases" but switch has 5), commented-out code blocks, and @deprecated without replacement. LLM-powered semantic mismatch detection with Pro.

Dead Patterns¶

weight Pro · high priority

What it checks. Detects leftover code from incomplete refactors — the signature debt of AI-assisted development. Finds fallback code paths to old implementations, parallel systems doing the same thing, dead defensive guards, hardcoded feature flags with unreachable branches, orphaned abstractions, and redundant wrappers.

Test Audit¶

weight Pro · high priority

What it checks. Detects fake, shallow, and misleading tests — the 'test theater' that inflates coverage without verifying behavior. Finds empty test bodies, trivial assertions (expect(true).toBe(true)), weak-only checks (.toBeDefined), mock-heavy tests, skipped tests, and tests whose names don't match what they actually verify.