Codebase Audit

Audit the codebase like you're inheriting someone else's mess - be thorough and honest. No diplomacy, no softening. Focus on what actually matters: security holes, bugs, maintainability problems, and tech debt. If something is broken or badly done, say it.

Audit Process

1. Check Available Tools

Start by checking what tools you have available:

command -v trufflehog
command -v npm # or pnpm, yarn, pip, cargo, etc.

If any expected tools are missing, list them in your output and ask the user if they want to continue without them. Don't let missing tools block the entire audit.

2. Detect Project Type and Run Audits

Figure out the package manager and run the right audit:

• package-lock.json → npm audit --json
• pnpm-lock.yaml → pnpm audit --json
• yarn.lock → yarn audit --json
• requirements.txt / poetry.lock → pip-audit --format json or safety check --json
• Cargo.toml → cargo audit --json
• go.mod → go list -json -m all | nancy sleuth

Secret scanning: Need help with TruffleHog? Check references/secret-scanning.md for scanning both current files and git history.

Parse the JSON output from these tools and integrate what you find into the audit report.

TypeScript projects (if tsconfig.json exists):

• Check if strict mode is enabled (critical issue if it's false or missing)
• Count how many times any is used explicitly (this defeats type safety)
• Count type assertions using as or <Type> (suggest using type narrowing instead)

OWASP Top 10 checks: See references/owasp-top-10.md for vulnerability patterns and detection commands. Report findings as critical with file:line, what the risk is, and how to fix it.

Accessibility checks: Check references/accessibility-checklist.md for a11y detection commands and testing procedures. Report these as important because they exclude real users from using the app.

Monitoring/Observability: Look for error tracking tools (Sentry, DataDog, NewRelic), structured logging libraries (winston, pino), health check endpoints, and watch out for console.logs making it to production. Report missing observability as important for production systems.

3. Detect Tech Stack and Understand Project

Figure out the tech stack: Need help identifying package managers, frameworks, cloud platforms, or IaC tools? See references/tech-stack-detection.md for the complete detection guide.

Build a summary that covers: language(s), framework, build tools, testing framework, cloud platform, IaC tools, and CI/CD platform.

Framework best practices:

Once you know what framework they're using, check the relevant patterns guide:

• Next.js/React → references/framework-patterns-nextjs.md
• Nuxt/Vue → references/framework-patterns-nuxt.md
• Other frameworks → Use WebSearch to look up current best practices and common mistakes

Performance testing (if Chrome MCP is available):

If this is a web app and you have access to chrome-devtools MCP:

• Ask the user: "Want me to run performance tests? Provide a URL or say skip."
• If they give you a URL, use Chrome MCP to run a Lighthouse-style audit
• Report Core Web Vitals (LCP, FID, CLS), bundle size, unoptimized images, and render-blocking resources

Don't forget to also check the project structure, documentation quality, and CI/CD setup.

4. Critical Issues (Show Details Immediately)

Surface these issues with full context right away - don't bury them:

Security (from tools + manual review)

• Secrets found by trufflehog - show file:line, what type of secret, and severity
• Vulnerable dependencies from npm/pip/cargo audit - package name, CVE, severity
• Hardcoded credentials or API keys sitting in the code
• Missing authentication or authorization checks
• Unsafe ways of handling data
• Sensitive endpoints that are exposed

TypeScript Configuration (if it's a TypeScript project)

• strict mode is disabled or missing from tsconfig.json
• explicit any types being used (this defeats the whole point of TypeScript)
• type casting/assertions (suggest type narrowing instead)

Breaking Problems

• Build failures or broken configuration
• Missing dependencies that are critical
• Incompatible version requirements
• Database migrations that can't be rolled back

Data Loss Risks

• Operations running without validation
• Missing error handling in paths that matter
• Race conditions in how data is handled

5. High-Level Findings (Summary Only)

Organize what you found into categories with counts and brief summaries. Need help with the full category breakdown? Check references/report-template.md.

Categories to cover:

• Architecture & Structure
• Tech Debt

...