Code Quality Audit
Run a comprehensive audit on your app's code. Checks structural patterns, code organization, consistency, test coverage, and technical debt. Produces actionable findings ranked by severity so you know exactly what to fix first.
Skill prompt
Engineering Audit Skill
Perform a deep engineering audit of a TypeScript/Node.js codebase. This skill is for TypeScript + Bash environments only. Execute each section below, collect findings, and produce a final structured report.
Audit Execution Order
Run the sections in this order. For each finding, record the severity, file path, line number, and a concise description.
Severity Levels
| Severity | Meaning |
|---|---|
| critical | Actively causing bugs, data loss, or security holes. Fix immediately. |
| high | Will cause problems soon or blocks maintainability. Fix this sprint. |
| medium | Code smell or suboptimal pattern. Plan to address. |
| low | Minor style or convention issue. Address opportunistically. |
| info | Observation or positive finding worth noting. No action required. |
1. Architecture Review
Examine module boundaries, layering, and structural patterns.
Circular Dependencies
# Use madge to detect circular dependencies
npx madge --circular --extensions ts src/
# If madge is not available, check for obvious circular imports manually
npx madge --circular --extensions ts --no-spinner src/ 2>/dev/null || echo "madge not available - perform manual inspection"
Barrel Export Analysis
# Find barrel files (index.ts that only re-export)
find src/ -name "index.ts" -exec grep -l "export \* from\|export {" {} \;
# Check for barrel files that re-export everything (can cause large bundle sizes and circular deps)
grep -rn "export \* from" src/index.ts src/**/index.ts 2>/dev/null
Layering Violations
Check that dependencies flow in one direction. In a Hercules app the rule is: React components import from convex/_generated/api, and Convex functions never import from src/ (the frontend). Flag any backend file that reaches into the frontend.
# Find Convex functions that import from the frontend
grep -rn "from ['\"]\.\./src\|from ['\"]@/" convex/ 2>/dev/null
# Find React components that bypass the Convex hooks layer
grep -rn "ConvexHttpClient\|new ConvexClient" src/ --include="*.tsx" 2>/dev/null
Module Size Analysis
# Find god files (files over 500 lines)
find src/ -name "*.ts" -exec wc -l {} \; | sort -rn | head -20
# Find god directories (directories with too many files)
find src/ -type d -exec sh -c 'echo "$(find "$1" -maxdepth 1 -name "*.ts" | wc -l) $1"' _ {} \; | sort -rn | head -15
Separation of Concerns
# Find React components doing database work directly instead of going through Convex hooks
grep -rln "ConvexHttpClient\|fetch(" src/ --include="*.tsx" 2>/dev/null
# Find Convex queries/mutations that mix data access with rendering or business rules
grep -rn "ctx\.db\." convex/ --include="*.ts" -A2 2>/dev/null | grep -B1 "JSX\|React\|return <" | head -20
2. Type Safety
Identify patterns that weaken TypeScript's type system.
any Usage
# Count and locate all uses of 'any'
grep -rn "\bany\b" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "\.d\.ts"
# Specifically dangerous: function parameters and return types typed as any
grep -rn ":\s*any\b\|<any>" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Type Assertions
# Find 'as' type assertions (especially 'as any' and 'as unknown')
grep -rn "\bas any\b\|\bas unknown\b" src/ --include="*.ts" --include="*.tsx"
# Find angle-bracket assertions (older style)
grep -rn "<any>\|<unknown>" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Non-Null Assertions
# Find non-null assertion operator usage (!)
grep -rn "[a-zA-Z0-9_)\]]!\." src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "\.d\.ts"
grep -rn "[a-zA-Z0-9_)\]]!;" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Missing Return Types on Exported Functions
# Exported functions without explicit return types
grep -rn "export\s\+\(async\s\+\)\?function\s\+[a-zA-Z]" src/ --include="*.ts" | grep -v "):" | grep -v "): " | head -30
Generic Abuse
# Find overly complex generic signatures (4+ type parameters)
grep -rn "<[A-Z][a-zA-Z]*,\s*[A-Z][a-zA-Z]*,\s*[A-Z][a-zA-Z]*,\s*[A-Z]" src/ --include="*.ts" | grep -v "node_modules"
3. Code Quality
Dead Code Detection
# Use knip to find unused exports, files, and dependencies
npx knip 2>/dev/null || echo "knip not available - perform manual inspection"
# Find unused exports manually: exported functions not imported elsewhere
grep -rn "export function\|export const\|export class\|export interface\|export type\|export enum" src/ --include="*.ts" | head -50
Duplicated Logic
# Find suspiciously similar function names across files (potential duplication)
grep -rn "export\s\+\(async\s\+\)\?function" src/ --include="*.ts" | sed 's/.*function\s\+//' | sed 's/(.*//' | sort | uniq -d
# Find copy-paste patterns: identical multi-line blocks
# Look for identical catch blocks, similar validation logic, etc.
grep -rn "catch\s*(.*)\s*{" src/ --include="*.ts" -A3 | head -40
Overly Complex Functions
# Find functions with deep nesting (proxy for high cyclomatic complexity)
# Files with many levels of indentation
grep -rn "^\s\{16,\}" src/ --include="*.ts" | grep -v "node_modules" | head -20
# Find long functions: blocks with more than 50 lines between braces
awk '/^\s*(export\s+)?(async\s+)?function|=>\s*\{/{start=NR} /^\}/{if(start && NR-start>50) print FILENAME":"start" ("NR-start" lines)"; start=0}' src/**/*.ts 2>/dev/null | head -20
Inconsistent Naming
# Find snake_case in TypeScript (should be camelCase)
grep -rn "const [a-z]\+_[a-z]\|let [a-z]\+_[a-z]\|function [a-z]\+_[a-z]" src/ --include="*.ts" | grep -v "node_modules" | head -20
# Find inconsistent boolean naming (should start with is/has/should/can/will)
grep -rn "const\s\+\(is\|has\|should\|can\|will\)" src/ --include="*.ts" | wc -l
grep -rn ":\s*boolean" src/ --include="*.ts" | grep -v "is\|has\|should\|can\|will\|enable\|disable\|allow\|visible\|active\|valid\|loading\|open\|closed\|done\|ready" | head -20
4. Error Handling
Swallowed Errors
# Empty catch blocks
grep -rn "catch" src/ --include="*.ts" -A2 | grep -B1 "{\s*}" | grep "catch"
# Catch blocks that only log (no rethrow or return)
grep -rn "catch" src/ --include="*.ts" -A5 | grep -A4 "console\.\(log\|warn\)" | grep -v "throw\|return\|reject" | head -20
Missing Error Boundaries
# Find top-level async functions without try/catch
grep -rn "export\s\+async\s\+function" src/ --include="*.ts" -A15 | grep -B1 "await" | grep -v "try" | head -20
# Find Convex actions making external calls without try/catch
grep -rn "await fetch\|await axios" convex/ --include="*.ts" -B3 | grep -v "try" | head -20
Unhandled Promise Rejections
# Promises without .catch() and not in try/catch
grep -rn "\.then(" src/ --include="*.ts" | grep -v "\.catch(" | grep -v "await" | head -20
# Fire-and-forget async calls (no await, no .catch)
grep -rn "[^await]\s\+[a-zA-Z]\+(" src/ --include="*.ts" | grep -v "\.catch\|await\|void\|\/\/" | head -20
Inconsistent Error Patterns
# Check for mixed error creation patterns
grep -rn "new Error(\|throw new\|throw '" src/ --include="*.ts" | sed 's/.*\(new Error\|throw new [A-Z][a-zA-Z]*\|throw '\''.*'\''\).*/\1/' | sort | uniq -c | sort -rn
# Find error classes to check for consistency
grep -rn "class.*extends.*Error" src/ --include="*.ts"
5. Dependency Health
Outdated and Vulnerable Packages
# Check for outdated packages
npm outdated 2>/dev/null || pnpm outdated 2>/dev/null || yarn outdated 2>/dev/null
# Security audit
npm audit 2>/dev/null || pnpm audit 2>/dev/null
Unused Dependencies
# Use depcheck or knip to find unused dependencies
npx depcheck 2>/dev/null || npx knip --dependencies 2>/dev/null || echo "depcheck/knip not available"
Duplicate Dependencies
# Check for duplicate packages in lockfile
npm ls --all 2>/dev/null | grep -i "deduped" | wc -l
npm ls --all 2>/dev/null | grep "invalid" | head -10
# Check for multiple versions of the same package
cat package-lock.json 2>/dev/null | grep -o '"node_modules/[^"]*"' | sed 's/.*\///' | sed 's/"//' | sort | uniq -d | head -20
Heavy Imports
# Find imports that pull in large packages where lighter alternatives exist
grep -rn "from ['\"]lodash['\"]" src/ --include="*.ts" | head -10
grep -rn "from ['\"]moment['\"]" src/ --include="*.ts" | head -10
grep -rn "from ['\"]axios['\"]" src/ --include="*.ts" | head -10
# Check for deep imports vs barrel imports (barrel = heavier)
grep -rn "from ['\"]lodash['\"]" src/ --include="*.ts" | wc -l
grep -rn "from ['\"]lodash/" src/ --include="*.ts" | wc -l
6. Testing Gaps
Missing Test Files
# Find source files without corresponding test files
for file in $(find src/ -name "*.ts" -not -name "*.test.ts" -not -name "*.spec.ts" -not -name "*.d.ts" -not -name "index.ts" -not -path "*/test/*" -not -path "*/__tests__/*"); do
base="${file%.ts}"
if [ ! -f "${base}.test.ts" ] && [ ! -f "${base}.spec.ts" ]; then
dir=$(dirname "$file")
fname=$(basename "$base")
if [ ! -f "${dir}/__tests__/${fname}.test.ts" ] && [ ! -f "${dir}/__tests__/${fname}.spec.ts" ]; then
echo "MISSING TEST: $file"
fi
fi
done | head -30
Low Assertion Density
# Find test files with low assertion counts
for testfile in $(find src/ -name "*.test.ts" -o -name "*.spec.ts"); do
tests=$(grep -c "it(\|test(" "$testfile" 2>/dev/null || echo 0)
asserts=$(grep -c "expect\|assert" "$testfile" 2>/dev/null || echo 0)
if [ "$tests" -gt 0 ] && [ "$asserts" -lt "$tests" ]; then
echo "LOW ASSERTIONS ($asserts asserts / $tests tests): $testfile"
fi
done
Test Anti-Patterns
# Tests checking implementation details (mocking internals excessively)
grep -rn "jest\.mock\|vi\.mock\|sinon\.stub" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l
# Disabled/skipped tests
grep -rn "\.skip\|xdescribe\|xit\|test\.skip\|it\.skip" src/ --include="*.test.ts" --include="*.spec.ts"
# Tests without cleanup
grep -rn "beforeEach\|afterEach\|beforeAll\|afterAll" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l
# Snapshot overuse
grep -rn "toMatchSnapshot\|toMatchInlineSnapshot" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l
7. Performance Patterns
N+1 Queries
# Database calls inside loops (the classic N+1 — fetch parents, then loop and fetch children one by one)
grep -rn "for\s*(.*of\|forEach\|\.map(" convex/ --include="*.ts" -A8 | grep -B3 "ctx\.db\.\(get\|query\)" | head -30
Missing Memoization
# Expensive computations that could be memoized: repeated function calls with same patterns
grep -rn "\.filter(.*\.filter\|\.map(.*\.map\|\.reduce(.*\.reduce" src/ --include="*.ts" | head -10
# React components: missing useMemo/useCallback for expensive operations
grep -rn "\.filter(\|\.map(\|\.sort(\|\.reduce(" src/ --include="*.tsx" | grep -v "useMemo\|useCallback" | head -20
Sync Operations That Should Be Async
# Synchronous file system operations in non-script files
grep -rn "readFileSync\|writeFileSync\|existsSync\|mkdirSync\|readdirSync\|statSync\|unlinkSync\|appendFileSync" src/ --include="*.ts" | grep -v "node_modules\|\.test\.\|\.spec\.\|scripts/" | head -20
# Synchronous crypto operations
grep -rn "crypto\..*Sync\|pbkdf2Sync\|scryptSync\|randomBytes\b" src/ --include="*.ts" | grep -v "node_modules" | head -10
Large Bundle Contributions
# Check for dynamic imports that should be lazy-loaded
grep -rn "^import.*from" src/ --include="*.ts" --include="*.tsx" | grep -i "chart\|editor\|markdown\|highlight\|pdf\|xlsx\|csv\|moment\|lodash\|aws-sdk" | head -20
8. Security Quick-Check
Hardcoded Secrets
# Potential hardcoded secrets, tokens, and keys
grep -rn "password\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock\|example\|placeholder\|changeme\|xxx"
grep -rn "apiKey\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock"
grep -rn "secret\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock\|process\.env"
grep -rn "Bearer\s\+[A-Za-z0-9._-]\{20,\}" src/ --include="*.ts" | head -10
Unsafe Regex
# Find complex regex patterns that may be vulnerable to ReDoS
grep -rn "new RegExp(\|/.*[*+]\{.*[*+]" src/ --include="*.ts" | grep -v "node_modules" | head -15
Prototype Pollution Vectors
# Object.assign or spread with user input
grep -rn "Object\.assign\|_.merge\|_.defaultsDeep\|_.set(" src/ --include="*.ts" | grep -v "node_modules" | head -10
# Missing __proto__ / constructor checks in merge utilities
grep -rn "function.*merge\|function.*extend\|function.*deepCopy" src/ --include="*.ts" | head -10
Unsanitized User Input
# User input flowing into dangerous sinks
grep -rn "innerHTML\|outerHTML\|document\.write\|eval(\|new Function(" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | head -10
# exec with string interpolation (command injection)
grep -rn "exec(\`\|exec(\".*\$\|execSync(\`" src/ --include="*.ts" | grep -v "node_modules" | head -10
9. Technical Debt Markers
TODO/FIXME/HACK Comments
# Inventory all debt markers with context
echo "=== TODOs ==="
grep -rn "// TODO\|// @todo\|/\* TODO" src/ --include="*.ts" --include="*.tsx"
echo ""
echo "=== FIXMEs ==="
grep -rn "// FIXME\|// @fixme\|/\* FIXME" src/ --include="*.ts" --include="*.tsx"
echo ""
echo "=== HACKs ==="
grep -rn "// HACK\|// @hack\|/\* HACK\|// XXX\|// WORKAROUND" src/ --include="*.ts" --include="*.tsx"
Deprecated API Usage
# Find @deprecated usage or calls to deprecated Node.js APIs
grep -rn "@deprecated" src/ --include="*.ts" | head -15
grep -rn "url\.parse(\|new Buffer(\|fs\.exists(\|path\.extname" src/ --include="*.ts" | grep -v "node_modules" | head -10
# Deprecated TypeScript patterns
grep -rn "/// <reference\|namespace " src/ --include="*.ts" | grep -v "node_modules\|\.d\.ts" | head -10
Temporary Workarounds
# Patterns that suggest temporary code
grep -rn "// temporary\|// temp fix\|// remove after\|// revert this\|// quick fix\|// hotfix\|@ts-ignore\|@ts-expect-error\|eslint-disable" src/ --include="*.ts" --include="*.tsx" | head -30
10. Automated Tool Checks
Run available tooling for deeper analysis. Skip tools that are not installed.
# Use the run_lint and run_build tools to check for type errors and lint
# violations. They run the project's configured linter and build pipeline
# without needing to know which tools the project uses.
# Circular dependency check
npx madge --circular --extensions ts src/ 2>&1
# Unused exports and dependencies
npx knip 2>&1 | head -50
Output: Final Report Format
After completing all sections, compile findings into this structured report. Every finding MUST include a file path and line number where possible.
# Engineering Audit Report
**Project:** [project name]
**Date:** [audit date]
**Scope:** [directories audited]
## Executive Summary
- **Critical:** X findings
- **High:** X findings
- **Medium:** X findings
- **Low:** X findings
- **Info:** X findings
## Critical Findings
1. **[CRITICAL]** `src/path/file.ts:42` - Description of the issue
- **Impact:** What goes wrong if this is not fixed
- **Recommendation:** Specific fix with code example if applicable
## High Findings
1. **[HIGH]** `src/path/file.ts:100` - Description of the issue
- **Impact:** Why this matters
- **Recommendation:** How to fix it
## Medium Findings
1. **[MEDIUM]** `src/path/file.ts:200` - Description of the issue
- **Recommendation:** Suggested improvement
## Low Findings
1. **[LOW]** `src/path/file.ts:300` - Description of the issue
## Info / Positive Observations
1. **[INFO]** Good pattern observed: description
## Technical Debt Summary
| Category | Count | Top Priority Item |
| ----------------------- | ----- | ----------------------- |
| TODO/FIXME comments | X | file.ts:N - description |
| `any` type usage | X | file.ts:N - description |
| Skipped tests | X | file.test.ts:N |
| @ts-ignore/expect-error | X | file.ts:N |
| Deprecated API calls | X | file.ts:N |
## Recommended Next Steps
1. [Prioritized action item 1]
2. [Prioritized action item 2]
3. [Prioritized action item 3]
When to Use This Skill
Use /engineering-audit when:
- Onboarding onto an unfamiliar TypeScript codebase
- Preparing for a major refactor or migration
- Conducting a quarterly or periodic health check
- Evaluating a codebase for acquisition or integration
- Establishing a baseline before adding new team members
- Identifying and prioritizing technical debt reduction work
- Preparing architecture decision records (ADRs) backed by evidence