The rulebook
Every check, explained
Will It Vibe runs the same 115 checks on every repo. Each check either fires or it doesn't, and each one deducts a fixed number of points from its category based on severity. No AI reads your code and no model touches the score, so the same repo gets the same result every time. This catalog documents what every check looks for, why it matters, and how to fix it.
Critical-25 ptsHigh-15 ptsMedium-8 ptsLow-4 ptsInfo-2 pts
Security
30% of the score25 checks- SEC-001CriticalHardcoded secret or API keyDetects string patterns matching common cloud/API secret formats (AWS, Stripe, GitHub, Slack) or generic api_key/secret assignments.
- SEC-002Critical.env file committed to the repoA .env file (which typically holds secrets) was found tracked in the project directory.
- SEC-004CriticalPrivate key file committedCertificate or private key files (.pem, .key, id_rsa, etc.) should never be committed to source control.
- SEC-005CriticalHardcoded credentials in connection stringA database/service connection string embeds a username and password directly in code.
- SEC-009CriticalSQL built via string concatenationBuilding SQL with string concatenation/interpolation instead of parameterized queries risks SQL injection.
- SEC-010CriticalShell command built from variable inputos.system/subprocess with shell=True, or child_process.exec, risk command injection when fed unsanitized input.
- SEC-014CriticalHardcoded JWT secretSigning/verifying JWTs with a literal string secret instead of an environment variable.
- SEC-016CriticalTLS certificate verification disabledDisabling certificate verification (rejectUnauthorized: false, verify=False) exposes traffic to MITM attacks.
- SEC-024CriticalPath traversal riskBuilding a filesystem path directly from user-controlled input without sanitization risks path traversal.
- SEC-025CriticalInsecure deserializationpickle.loads on untrusted input, and yaml.load without SafeLoader, can lead to arbitrary code execution.
- SEC-003High.env missing from .gitignoreA .env file is present but .gitignore doesn't exclude it, risking an accidental commit of secrets.
- SEC-006HighUse of eval() / Function constructoreval() and `new Function(...)` execute arbitrary strings as code and are a common injection vector.
- SEC-007HighUse of exec()/eval() in Pythonexec()/eval() run arbitrary code and are rarely required outside of very specific tooling.
- SEC-008HighUnsanitized innerHTML / dangerouslySetInnerHTMLWriting variable content into innerHTML or dangerouslySetInnerHTML without sanitizing is a common XSS vector.
- SEC-012HighPermissive CORS wildcardAccess-Control-Allow-Origin: * (or cors({origin: '*'})) allows any site to call the API.
- SEC-015HighDebug mode enabledFramework debug mode left on can leak stack traces, source, and environment details in production.
- SEC-017HighWeak hash algorithm near password handlingMD5/SHA1 are not suitable for password hashing; use bcrypt/argon2/scrypt instead.
- SEC-020HighHistorically compromised packageChecks dependency names against a small curated list of packages with documented supply-chain compromise incidents.
- SEC-021HighSensitive token stored in localStoragelocalStorage is readable by any script on the page (XSS-exposed); tokens/passwords stored there are easily stolen.
- SEC-023HighOpen redirect via unsanitized query paramRedirecting to a URL taken directly from request input lets attackers craft phishing redirect links.
- SEC-011MediumWeak randomness for a security-sensitive valueMath.random() used near token/password/secret naming is not cryptographically secure.
- SEC-013MediumMissing HTTP security headers middlewareAn Express app was detected with no helmet (or equivalent) dependency for setting standard security headers.
- SEC-019MediumUnpinned dependency versionpackage.json declares a dependency with '*' or 'latest' as its version, which can silently pull in breaking or malicious updates.
- SEC-018LowNo input validation libraryAn API server dependency (Express/Fastify) was found with no schema-validation library for incoming request data.
- SEC-022LowNo rate limitingAn Express-based API has no rate-limiting middleware dependency, leaving it open to brute-force/abuse.
Code Quality & Syntax
20% of the score25 checks- CQ-009HighEmpty catch blockAn empty catch/except block silently swallows errors, making failures invisible.
- CQ-002Mediumdebugger statement left in codeA `debugger;` breakpoint statement was left in source.
- CQ-004MediumVery large fileSource files over 500 lines are hard to review and often mix unrelated responsibilities.
- CQ-005MediumLong function (JS/TS)Functions longer than ~80 lines are a strong readability and testability smell.
- CQ-019MediumGod fileA single file defining 15+ top-level functions/classes usually needs to be split by responsibility.
- CQ-023MediumPromise chain possibly missing .catch()A .then() chain with no trailing .catch() on the same statement means rejected promises may fail silently.
- CQ-001Lowconsole.log left in sourceLeftover console.log/console.debug statements in shipped source are a common vibe-coding leftover and can leak data.
- CQ-006LowDeep nestingCode nested 6+ levels deep is a readability/complexity smell (indentation-based heuristic).
- CQ-007LowCommented-out code blockThree or more consecutive comment lines that look like real code -- usually dead code left behind.
- CQ-010LowOverly broad exception handlingCatching the base Exception type hides bugs that should surface, and should generally be narrowed or re-raised.
- CQ-014LowDuplicate code blockIdentical 5+ line chunks repeated across the codebase -- a copy-paste smell that should usually be extracted into a shared function.
- CQ-018LowToo many function parametersFunctions with more than 5 parameters are hard to call correctly; consider an options object/dataclass.
- CQ-021LowUnreachable code after returnCode found at the same indentation level immediately after a return statement will never execute.
- CQ-024LowAsync/await without error handlingA file uses async/await but has no try/catch anywhere, so rejected awaits will throw unhandled.
- CQ-003Infoprint() left in Python sourceprint() debugging statements left outside of scripts/CLI entrypoints; prefer a logger.
- CQ-008InfoHigh TODO/FIXME densityMore than 1 TODO/FIXME/HACK marker per 100 lines suggests unfinished work shipped as-is.
- CQ-011InfoMagic number in conditionUnexplained numeric literals in conditionals hurt readability; prefer a named constant.
- CQ-012InfoUse of var instead of let/const`var` has function-scoping footguns; modern JS/TS should use let/const.
- CQ-013InfoLoose equality operator`==`/`!=` perform type coercion and are a common source of subtle bugs; prefer `===`/`!==`.
- CQ-015InfoMixed tabs/spacesA file uses both tabs and spaces for indentation, which renders inconsistently across editors.
- CQ-016InfoTrailing whitespaceMore than 10 lines with trailing whitespace in a single file, usually a missing editor/formatter config.
- CQ-017InfoInconsistent semicolon usageA JS/TS file mixes semicolon-terminated and non-terminated statements, suggesting no formatter is enforced.
- CQ-020InfoUnused import (Python)An imported name is never referenced elsewhere in the file (AST-based check).
- CQ-022Infoalert()/confirm() used for UXNative alert()/confirm() dialogs are jarring and block the main thread; use in-app UI for errors and confirmations.
- CQ-025InfoInconsistent variable naming conventionA single file mixes camelCase and snake_case for variable names.
Architecture & Best Practices
15% of the score20 checks- ARCH-003CriticalSecret referenced in frontend codeA frontend component/file references what looks like a secret key directly, which ships it to every browser.
- ARCH-010HighDependency directory committednode_modules/ or a Python virtualenv was found tracked in the repo, bloating history and risking leaked local paths/secrets.
- ARCH-002MediumNo environment-based configurationA backend-looking project never reads from environment variables, suggesting config/secrets are hardcoded.
- ARCH-004MediumNo centralized error handlingNo Express error-handling middleware was found, so unhandled errors likely crash requests inconsistently.
- ARCH-007MediumMonolithic entry pointThe app's root entry file is very large, suggesting routes/logic/config were never split into modules.
- ARCH-009MediumMissing .gitignoreEvery project with source control should exclude build artifacts, dependencies, and secrets via .gitignore.
- ARCH-011MediumMissing lockfileNo package-lock.json/yarn.lock/pnpm-lock.yaml was found alongside package.json.
- ARCH-018MediumBlocking synchronous I/O in request handlerfs.readFileSync/writeFileSync inside request-handling code blocks the Node event loop for all concurrent requests.
- ARCH-001LowHardcoded localhost/port URLHardcoding localhost or a fixed port instead of reading from environment/config breaks non-local deploys.
- ARCH-005LowMissing loading stateA component performs data fetching with no visible loading-state variable, usually a bare/blank UI while data loads.
- ARCH-006LowMissing error stateA component performs data fetching with no visible error handling, so failed requests likely fail silently in the UI.
- ARCH-008LowNo service-layer separationA large route/controller file makes direct data-access calls inline, mixing HTTP concerns with business logic.
- ARCH-012LowConflicting lockfilesMore than one package-manager lockfile was found, usually meaning the team/tooling drifted between npm/yarn/pnpm.
- ARCH-013LowNo environment-specific configurationNo per-environment config/env files were found, suggesting dev and production share identical configuration.
- ARCH-017LowNo health-check endpointNo conventional health-check route was found, which most hosting/orchestration platforms rely on for liveness checks.
- ARCH-019LowUnbounded list queryA find/select query with no limit/pagination can return unbounded result sets as data grows.
- ARCH-014InfoExcessive inline stylesHeavy use of inline style objects in JSX makes styling hard to reuse and theme consistently.
- ARCH-015InfoNo state management strategyA sizeable React app has no state-management library or Context API usage, often meaning state is drilled through many prop layers.
- ARCH-016InfoUnversioned API routesAPI routes with no version prefix (/api/v1/...) make future breaking changes harder to roll out safely.
- ARCH-020InfoGlobal mutable stateA module exports mutable top-level state (let/var), a common source of subtle cross-request bugs in server code.
Documentation, UX & Accessibility
15% of the score20 checks- DOCS-001MediumNo READMENo README file was found at the project root.
- DOCS-007MediumMissing viewport meta tagNo <meta name="viewport"> tag found, so the page won't scale correctly on mobile.
- DOCS-010MediumImages missing alt textImages without an alt attribute are invisible to screen readers.
- DOCS-011MediumForm inputs missing labelsForm inputs with no associated label or aria-label are hard or impossible to use with assistive technology.
- DOCS-012MediumButtons with no accessible textIcon-only or empty buttons with no aria-label are unusable for screen-reader users.
- DOCS-015MediumFocus outline removedRemoving the default focus outline without a visible replacement breaks keyboard navigation.
- DOCS-002LowREADME missing setup instructionsThe README doesn't appear to include an install/setup/getting-started section.
- DOCS-003LowREADME missing usage instructionsThe README doesn't appear to include a usage/example section.
- DOCS-006LowMissing html lang attributeThe <html> tag has no lang attribute, which hurts screen readers and SEO.
- DOCS-008LowMissing <title>No <title> tag found in the HTML document.
- DOCS-014LowNo semantic HTMLThe page is built entirely from generic <div> elements with no semantic HTML5 structure, hurting accessibility and SEO.
- DOCS-016LowNo responsive design signalsNo media queries or a utility framework with responsive prefixes were found in a non-trivial stylesheet.
- DOCS-004InfoNo LICENSE fileNo LICENSE file was found, which leaves the legal terms of reuse undefined.
- DOCS-005InfoMissing package.json descriptionpackage.json has no description field, which shows up blank on npm/registry listings.
- DOCS-009InfoMissing meta descriptionNo <meta name="description"> tag found, which hurts SEO/link-preview quality.
- DOCS-013InfoNo faviconNo favicon file or link tag was found; the browser tab will show a generic icon.
- DOCS-017InfoNo 404 pageNo not-found page or catch-all route was found, so unmatched URLs likely show a raw error instead of a friendly page.
- DOCS-018InfoNo CONTRIBUTING guideA licensed/open-source-looking project has no CONTRIBUTING.md to guide external contributors.
- DOCS-019InfoNo changelogThe package version suggests multiple releases have happened, but there's no CHANGELOG.md tracking what changed.
- DOCS-020InfoNo design tokens / theme variablesColors are hardcoded as raw hex values throughout the stylesheet instead of using CSS custom properties, making theming and consistency harder.
Testing & CI
10% of the score10 checks- TEST-001HighNo tests foundNo files matching common test naming conventions (*.test.*, *.spec.*, tests/, test_*.py) were found anywhere in the project.
- TEST-002MediumNo CI configurationNo continuous-integration config (GitHub Actions, GitLab CI, CircleCI, Travis) was found, so nothing runs checks automatically on push/PR.
- TEST-006MediumTrivial/placeholder testsTest files exist but contain very few assertions relative to file count, suggesting scaffolded but unwritten tests.
- TEST-003LowNo linter configurationNo ESLint/Ruff/Flake8/Pylint configuration was found, so style and common bugs aren't checked automatically.
- TEST-010LowNo structured loggingNo logging library (winston/pino, or Python's logging module) was detected -- production issues will be hard to diagnose with only console.log/print.
- TEST-004InfoNo formatter configurationNo Prettier/Black configuration was found, so code style likely drifts across contributors and AI-assisted edits.
- TEST-005InfoNo pre-commit hooksNo pre-commit/husky configuration was found, so lint/test checks aren't enforced before code is committed.
- TEST-007InfoNo coverage toolingNo coverage tool (jest/nyc/c8/coverage.py) was detected, so there's no visibility into how much of the code is actually tested.
- TEST-008InfoNo .editorconfigNo .editorconfig file was found to keep indentation/charset/line-ending conventions consistent across editors.
- TEST-009InfoNo type-checking configurationNo TypeScript config or mypy configuration was found for a project that would benefit from static type checking.
Dependencies & Hygiene
10% of the score15 checks- DEP-001MediumNo dependency manifestSource code exists but there's no package manifest declaring what it depends on.
- DEP-006MediumUnpinned Python requirementsrequirements.txt declares packages with no version pins, so installs can silently drift between environments.
- DEP-009MediumMissing .dockerignoreA Dockerfile exists but there's no .dockerignore, risking secrets/bloat being copied into the image build context.
- DEP-010MediumDocker container runs as rootNo USER instruction was found in the Dockerfile, so the container runs as root by default.
- DEP-002LowDependency listed twiceThe same package appears in both dependencies and devDependencies in package.json.
- DEP-005LowNode engines mismatchThe declared Node engine version is older than what the syntax used in the code actually requires.
- DEP-007LowLarge binary file committedFiles over 5MB were found committed directly, which bloats repo size; consider Git LFS or external storage.
- DEP-011LowUnpinned Docker base imageThe Dockerfile's FROM line has no version tag (or uses :latest), so the base image can change under you between builds.
- DEP-012LowIncomplete .gitignore.gitignore exists but is missing some standard entries for this project's stack.
- DEP-015LowPossible circular importTwo local modules appear to import from each other -- a heuristic signal of a circular dependency.
- DEP-003InfoDependency bloatA very high dependency count relative to the size of the codebase, worth auditing for unused packages.
- DEP-004InfoDeprecated/abandoned packageA dependency with well-known deprecation/abandonment status was found (curated list).
- DEP-008InfoConflicting Python manifestsMore than one of requirements.txt/Pipfile/pyproject.toml was found declaring dependencies.
- DEP-013InfoMixed line endingsA file mixes Windows (CRLF) and Unix (LF) line endings, which shows up as noisy diffs.
- DEP-014InfoNo Node version pinNeither .nvmrc nor package.json engines.node specifies a target Node version.
See which checks your repo trips
Paste a GitHub URL or drop a project folder. The scan runs in your browser and takes seconds.
Scan your repo