codebase-auditor 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude-flow__swarm_init",
+      "Bash(npm install:*)",
+      "Bash(node audit.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\toddler-activities\")",
+      "Bash(notepad .env)",
+      "Bash(node audit.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\village\")",
+      "Bash(node audit.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\audit-test-repo\")",
+      "Bash(node audit.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\dotenv-test\")",
+      "Bash(node src/index.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\dotenv-test\")",
+      "Bash(node index.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\dotenv-test\")",
+      "Bash(ls *.js *.mjs *.ts)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('main:', d.get\\('main'\\)\\); print\\('scripts:', d.get\\('scripts'\\)\\)\")",
+      "Bash(node audit.js \"C:\\\\Users\\\\Still Pending\\\\Projects\\\\chalk-test\")"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "claude-flow"
+  ]
+}

package/.claude-flow/swarm/swarm-state.json

@@ -0,0 +1,23 @@
+{
+  "swarms": {
+    "swarm-1775182478458-20duxg": {
+      "swarmId": "swarm-1775182478458-20duxg",
+      "topology": "hierarchical",
+      "maxAgents": 8,
+      "status": "running",
+      "agents": [],
+      "tasks": [],
+      "config": {
+        "topology": "hierarchical",
+        "maxAgents": 8,
+        "strategy": "balanced",
+        "communicationProtocol": "message-bus",
+        "autoScaling": true,
+        "consensusMechanism": "majority"
+      },
+      "createdAt": "2026-04-03T02:14:38.458Z",
+      "updatedAt": "2026-04-03T02:14:38.458Z"
+    }
+  },
+  "version": "3.0.0"
+}

package/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=your_key_here

package/README.md

@@ -0,0 +1,88 @@
+# Codebase Auditor
+
+An AI-powered CLI tool that audits your codebase across six dimensions using the Anthropic API. Point it at any project and get a structured Markdown report with prioritized findings and fix suggestions.
+
+## What It Does
+
+Codebase Auditor runs six parallel AI agents against your source files, each focused on a specific dimension:
+
+- **Security** — Hardcoded secrets, SQL injection, unsafe `eval()`, insecure patterns
+- **Performance** — Blocking sync operations, N+1 queries, memory leaks, inefficient loops
+- **Test Coverage** — Untested exports, missing error-path tests, weak assertions
+- **Documentation** — Missing JSDoc, undocumented parameters, README gaps
+- **Dependencies** — Vulnerable packages, abandoned libraries, license conflicts
+- **Code Quality** — Long functions, deep nesting, duplicate code, dead code
+
+All six agents run simultaneously via `Promise.all()` and their results are merged into a single `audit-report.md` file.
+
+## Requirements
+
+- Node.js 18 or higher
+- An [Anthropic API key](https://console.anthropic.com/)
+
+## Installation
+
+```bash
+git clone https://github.com/your-username/codebase-auditor.git
+cd codebase-auditor
+npm install
+cp .env.example .env
+# Edit .env and add your Anthropic API key
+```
+
+## Usage
+
+```bash
+node audit.js ./your-project
+```
+
+Replace `./your-project` with the path to the directory you want to audit. Defaults to `./` if no path is given.
+
+## What Gets Checked
+
+| Dimension | What the Agent Looks For |
+|-----------|--------------------------|
+| Security | Hardcoded credentials, API keys, SQL injection, `eval()` misuse, path traversal |
+| Performance | `readFileSync` in async functions, nested loops on large data, N+1 DB calls, memory leaks |
+| Tests | Exported functions with no tests, missing edge-case coverage, trivial test files |
+| Docs | Public functions without JSDoc, missing `@param`/`@returns`, README without usage section |
+| Dependencies | CVE-prone packages, unmaintained libraries (2+ years), `devDependencies` in wrong section |
+| Quality | Functions >50 lines, 4+ nesting levels, duplicated blocks, `console.log` in production code |
+
+## Example Output
+
+```
+Codebase Auditor — scanning: /home/user/my-app
+
+Scanning files...
+Found 42 files to audit.
+
+Starting Security agent...
+Starting Performance agent...
+Starting Tests agent...
+Starting Docs agent...
+Starting Dependencies agent...
+Starting Quality agent...
+
+Security agent complete.
+Performance agent complete.
+...
+
+Audit complete. 17 total findings:
+
+  🔴 Critical: 2
+  🟠 High:     5
+  🟡 Medium:   7
+  🟢 Low:      3
+
+Report saved to: /home/user/my-app/audit-report.md
+```
+
+The generated `audit-report.md` contains an executive summary table and a dedicated section for each audit dimension with severity labels, affected files, descriptions, and fix suggestions.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes and run `npm test`
+4. Submit a pull request with a clear description of the change

package/audit.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { resolve, basename } from 'path';
+import { scanDirectory } from './src/scanner.js';
+import { runSecurityAudit } from './src/agents/security.js';
+import { runPerformanceAudit } from './src/agents/performance.js';
+import { runTestAudit } from './src/agents/tests.js';
+import { runDocsAudit } from './src/agents/docs.js';
+import { runDependencyAudit } from './src/agents/dependencies.js';
+import { runQualityAudit } from './src/agents/quality.js';
+import { generateReport } from './src/reporter.js';
+
+async function main() {
+  const targetPath = process.argv[2] || './';
+  const absTarget = resolve(targetPath);
+  const projectName = basename(absTarget);
+
+  console.log(`\nCodebase Auditor — scanning: ${absTarget}\n`);
+
+  console.log('Scanning files...');
+  const { files, packageJson } = await scanDirectory(absTarget);
+  console.log(`Found ${files.length} files to audit.\n`);
+
+  if (files.length === 0) {
+    console.log('No auditable files found. Exiting.');
+    process.exit(0);
+  }
+
+  const agentNames = ['Security', 'Performance', 'Tests', 'Docs', 'Dependencies', 'Quality'];
+  agentNames.forEach(name => console.log(`Starting ${name} agent...`));
+  console.log('');
+
+  console.log('Running Security agent...');
+  const security = await runSecurityAudit(files);
+  console.log('Security agent complete.');
+
+  console.log('Running Performance agent...');
+  const performance = await runPerformanceAudit(files);
+  console.log('Performance agent complete.');
+
+  console.log('Running Tests agent...');
+  const tests = await runTestAudit(files);
+  console.log('Tests agent complete.');
+
+  console.log('Running Docs agent...');
+  const docs = await runDocsAudit(files);
+  console.log('Docs agent complete.');
+
+  console.log('Running Dependencies agent...');
+  const dependencies = await runDependencyAudit(packageJson);
+  console.log('Dependencies agent complete.');
+
+  console.log('Running Quality agent...');
+  const quality = await runQualityAudit(files);
+  console.log('Quality agent complete.');
+
+  console.log('\nGenerating report...');
+
+  const { outputPath, totals, totalFindings } = await generateReport(
+    { security, performance, tests, docs, dependencies, quality },
+    projectName,
+    absTarget
+  );
+
+  console.log(`\nAudit complete. ${totalFindings} total findings:\n`);
+  console.log(`  🔴 Critical: ${totals.critical}`);
+  console.log(`  🟠 High:     ${totals.high}`);
+  console.log(`  🟡 Medium:   ${totals.medium}`);
+  console.log(`  🟢 Low:      ${totals.low}`);
+  console.log(`\nReport saved to: ${outputPath}\n`);
+}
+
+main().catch(err => {
+  console.error('Audit failed:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "codebase-auditor",
+  "version": "1.0.0",
+  "description": "AI-powered codebase auditor. Scans your project with 6 specialized agents and generates a structured report with Risk and Quality scores.",
+  "main": "audit.js",
+  "bin": {
+    "codebase-auditor": "./audit.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["audit", "code-quality", "security", "static-analysis", "ai", "claude", "codebase"],
+  "author": "skynetendofhumanraise-beep",
+  "license": "MIT",
+  "homepage": "https://github.com/skynetendofhumanraise-beep/codebase-auditor",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skynetendofhumanraise-beep/codebase-auditor.git"
+  },
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.82.0",
+    "dotenv": "^17.4.0"
+  }
+}

package/src/agents/dependencies.js

@@ -0,0 +1,79 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runDependencyAudit(packageJson) {
+  if (packageJson == null) {
+    return {
+      findings: [{
+        severity: 'low',
+        title: 'No package.json found',
+        file: 'package.json',
+        description: 'No package.json was detected in this project. Dependency audit was skipped.',
+        fix: 'If this project uses npm packages, ensure a package.json exists in the root directory.',
+      }],
+    };
+  }
+
+  const hasDeps = packageJson.dependencies && Object.keys(packageJson.dependencies).length > 0;
+  const hasDevDeps = packageJson.devDependencies && Object.keys(packageJson.devDependencies).length > 0;
+
+  if (!hasDeps && !hasDevDeps) {
+    return {
+      findings: [{
+        severity: 'low',
+        title: 'No dependencies declared',
+        file: 'package.json',
+        description: 'The package.json exists but declares no dependencies or devDependencies.',
+        fix: 'If this project relies on external packages, add them to the appropriate section in package.json.',
+      }],
+    };
+  }
+
+  const packageSummary = JSON.stringify(packageJson, null, 2);
+
+  const prompt = `You are a dependency security and maintenance auditor. Analyze the following package.json for genuine dependency risks.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- Packages with known CVEs or confirmed security vulnerabilities at the version range declared
+- Packages explicitly deprecated by their maintainers with a stated recommended replacement
+- Packages with no releases in 3+ years that are not intentionally in maintenance-only mode
+- devDependencies that are actually imported or required in production source code
+- Dependencies with licenses that are restrictive or incompatible with this project's license
+
+DO NOT flag:
+- Packages that are stable and intentionally not updated frequently (e.g., dotenv — stability is a feature, not a defect)
+- Minor patch or minor version differences from the absolute latest release
+- TypeScript type packages (@types/*) being slightly behind the runtime package version
+- Packages explicitly in maintenance mode that still receive security patches
+
+SEVERITY for dependencies:
+- Packages with known CVEs = CRITICAL if the vulnerability is critical/high severity, or HIGH if the CVE is moderate
+- Packages explicitly deprecated with no security coverage = MEDIUM
+- Packages outdated but still actively maintained and receiving security fixes = LOW
+
+package.json to audit:
+${packageSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"package.json","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/agents/docs.js

@@ -0,0 +1,54 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runDocsAudit(files) {
+  const filesSummary = files.map(f => `// File: ${f.path}\n${f.content}`).join('\n\n---\n\n');
+
+  const prompt = `You are a technical writer and documentation auditor. Analyze the following source files for meaningful documentation gaps that would hurt a developer trying to use this code.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- Exported public functions with no JSDoc comment at all
+- README files that have no usage instructions or examples
+- Complex algorithms (cryptographic operations, custom parsers, non-obvious bitwise operations) with no inline explanation of what they do or why
+
+DO NOT flag:
+- Internal private functions prefixed with an underscore (_)
+- Simple one-liner functions where the function name makes the behavior completely obvious
+- Missing @param or @returns tags when the function signature and types are self-evident
+- Getters and setters
+
+CONSOLIDATION RULE — STRICTLY ENFORCED: If a function is missing its JSDoc entirely, file EXACTLY ONE finding that covers the missing description, @param tags, and @returns tags all together. Never file separate findings for different missing JSDoc elements on the same function. Only file separate @param or @returns findings if the function already has a JSDoc description but is specifically missing those tags.
+
+SEVERITY for documentation:
+- NEVER use CRITICAL for any documentation finding — documentation gaps are never critical
+- Missing JSDoc on primary public API functions = MEDIUM
+- Missing README usage section = MEDIUM
+- Missing inline explanation for complex algorithms = LOW
+- Missing @param or @returns on functions that already have a JSDoc description = LOW
+
+Files to audit:
+${filesSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"string","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/agents/performance.js

@@ -0,0 +1,54 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runPerformanceAudit(files) {
+  const filesSummary = files.map(f => `// File: ${f.path}\n${f.content}`).join('\n\n---\n\n');
+
+  const prompt = `You are a performance engineer. Analyze the following source files for genuine performance problems that would affect real users.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- fs.readFileSync inside async functions, inside request handlers, or inside loops that execute repeatedly at runtime
+- Inefficient O(n²) patterns — nested loops iterating the same dataset
+- Repeated DOM queries (e.g., document.querySelector) inside loops or render functions that run frequently
+- N+1 patterns — database or API calls made inside loops instead of batched
+- Event listeners added in components that mount/unmount but never removed, causing accumulation
+
+DO NOT flag:
+- fs.readFileSync in functions named config, load, init, setup, parse, or configDotenv — these are intentional one-time initialization patterns
+- Math.random() calls
+- Simple Object.keys() iterations on small, bounded objects
+- Memory retention in small constant arrays or static data structures like tips arrays
+- One-time startup I/O that does not repeat during the application lifecycle
+
+SEVERITY for performance:
+- Blocking synchronous I/O inside request handlers or repeated runtime paths = HIGH
+- O(n²) patterns in loops = MEDIUM
+- Repeated DOM queries inside render or loop functions = MEDIUM
+- Minor inefficiencies with limited real-world impact = LOW
+
+Files to audit:
+${filesSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"string","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/agents/quality.js

@@ -0,0 +1,53 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runQualityAudit(files) {
+  const filesSummary = files.map(f => `// File: ${f.path}\n${f.content}`).join('\n\n---\n\n');
+
+  const prompt = `You are a code quality reviewer. Analyze the following source files for genuine code quality issues that affect maintainability.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- Functions genuinely over 60 lines of executable code (60 lines is the real threshold where complexity becomes a problem — not 50)
+- Nesting depth of 5 or more levels (deeply nested conditionals or loops within loops)
+- Large blocks of commented-out code — 10 or more consecutive lines of code that has been commented out
+- console.log statements that are clearly leftover debug output: inside business logic, loops, or event handlers where there is no logging purpose
+
+DO NOT flag:
+- console.log inside functions whose sole purpose is logging — functions named log, warn, debug, error, _log, _warn, _debug, logger, print, output, or any similar logging-purpose name
+- Duplicate data structures that are intentionally separate (e.g., two activity arrays maintained independently for different purposes)
+- Functions that are long because they contain data definitions or configuration, not executable logic
+- Nesting at 4 levels or fewer
+
+SEVERITY for quality:
+- Functions over 100 lines of executable logic = HIGH
+- Functions between 60 and 100 lines of executable logic = MEDIUM
+- Nesting depth of 5+ levels = MEDIUM
+- Commented-out code blocks (10+ lines) = LOW
+- Leftover console.log debug statements = LOW
+
+Files to audit:
+${filesSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"string","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/agents/security.js

@@ -0,0 +1,54 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runSecurityAudit(files) {
+  const filesSummary = files.map(f => `// File: ${f.path}\n${f.content}`).join('\n\n---\n\n');
+
+  const prompt = `You are a security auditor. Analyze the following source files for genuine security vulnerabilities only. Do not flag theoretical or unlikely risks.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- Hardcoded secrets, API keys, or passwords embedded in source code
+- eval() or Function() called with user-controlled input
+- SQL injection via string concatenation with unsanitized user input
+- Path traversal vulnerabilities where user input reaches file paths without validation
+- XSS via unsanitized user input assigned to innerHTML or similar DOM sinks
+- Insecure use of crypto (weak algorithms, hardcoded IVs, broken key derivation)
+
+DO NOT flag:
+- console.log or debug logging output
+- Synchronous file operations used in initialization or configuration loading
+- Regex complexity unless there is a proven ReDoS pattern with a specific exploit string demonstrating catastrophic backtracking
+- Domain names or URLs appearing in strings
+- Debug logging functions or structured loggers
+
+SEVERITY for security:
+- Hardcoded secrets and eval() with user input = CRITICAL
+- SQL injection = HIGH
+- Path traversal and XSS = MEDIUM unless the code is directly and trivially exploitable with no mitigating factors, then HIGH
+
+Files to audit:
+${filesSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"string","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/agents/tests.js

@@ -0,0 +1,53 @@
+import Anthropic from '@anthropic-ai/sdk';
+import 'dotenv/config';
+import { parseJsonResponse } from '../parseJson.js';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function runTestAudit(files) {
+  const filesSummary = files.map(f => `// File: ${f.path}\n${f.content}`).join('\n\n---\n\n');
+
+  const prompt = `You are a QA engineer. Analyze the following source files for genuine gaps in test coverage.
+
+SHARED SEVERITY RULES (apply to all findings):
+- CRITICAL: Only for issues that directly enable data breach, code execution, or system compromise. Examples: hardcoded credentials, eval() with user input, SQL injection. Never use Critical for code quality, documentation, or test coverage issues.
+- HIGH: Significant issues that meaningfully increase risk or maintenance burden. One HIGH per distinct problem, never multiple HIGHs for sub-parts of the same issue.
+- MEDIUM: Real issues worth fixing but not urgent. Missing documentation, weak test coverage, performance patterns that could cause problems at scale.
+- LOW: Suggestions and minor improvements. Style issues, optional optimizations, nice-to-have documentation.
+- Never file more than one finding per function per issue type. If a function has multiple related problems, combine them into one finding.
+
+FLAG these issues:
+- Exported functions or classes with zero test coverage anywhere in the entire test suite
+- Test files that contain only trivial assertions such as expect(true).toBe(true) and test nothing real
+- Missing tests for critical error paths in security-sensitive functions (e.g., auth, input validation, crypto)
+
+DO NOT flag:
+- Functions that are tested indirectly through integration tests — indirect coverage counts
+- Internal helper functions that are not exported from the module
+- Missing tests for simple getter functions or plain constants
+- Missing edge case tests unless the function handles user input or security-sensitive data
+
+CRITICAL ANALYSIS INSTRUCTION: Before flagging any function as untested, carefully read ALL test files in the project. Test files do not need to import functions directly to provide coverage — integration tests, end-to-end tests, and indirect calls all count as coverage. Only flag a function as untested if you are confident it is not exercised by any test in any test file.
+
+SEVERITY for test coverage:
+- No tests at all for an exported function = HIGH
+- Test file exists but contains only trivial or meaningless assertions = LOW
+- Missing error path tests for security-sensitive functions = MEDIUM
+- Missing edge case tests for non-sensitive functions = LOW
+
+Files to audit:
+${filesSummary}
+
+Respond with ONLY valid JSON in this exact shape, no markdown, no explanation:
+{"findings":[{"severity":"critical|high|medium|low","title":"string","file":"string","description":"string","fix":"string"}]}
+
+If no issues found, return: {"findings":[]}`;
+
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return parseJsonResponse(message.content[0].text);
+}

package/src/parseJson.js

@@ -0,0 +1,24 @@
+/**
+ * Extract and parse the first JSON object from an LLM response.
+ * Handles: raw JSON, ```json fences, prose before/after JSON.
+ */
+export function parseJsonResponse(text) {
+  const trimmed = text.trim();
+
+  // Strip markdown fences first
+  const defenced = trimmed.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '').trim();
+
+  // Try direct parse
+  try {
+    return JSON.parse(defenced);
+  } catch (_) {}
+
+  // Extract the first {...} block from anywhere in the text
+  const start = defenced.indexOf('{');
+  const end = defenced.lastIndexOf('}');
+  if (start !== -1 && end > start) {
+    return JSON.parse(defenced.slice(start, end + 1));
+  }
+
+  throw new SyntaxError(`No JSON object found in response: ${trimmed.slice(0, 120)}`);
+}

package/src/reporter.js

@@ -0,0 +1,240 @@
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+
+const SEVERITY_EMOJI = { critical: '🔴', high: '🟠', medium: '🟡', low: '🟢' };
+const SEVERITY_LABEL = { critical: 'CRITICAL', high: 'HIGH', medium: 'MEDIUM', low: 'LOW' };
+const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
+const STOP_WORDS = new Set(['the','a','an','in','for','of','and','or','with','without','no','missing','is','are','not','to','on','at','by','be','as','it','its']);
+const SECURITY_KEYWORDS = ['eval','sql injection','hardcoded','credentials','api key','password','injection','xss','sanitize','sanitization'];
+
+function significantWords(title) {
+  return title.toLowerCase().replace(/[^a-z0-9 ]/g, ' ').split(/\s+/).filter(w => w.length > 1 && !STOP_WORDS.has(w));
+}
+
+function titlesSimilar(a, b) {
+  const wordsA = new Set(significantWords(a));
+  const wordsB = significantWords(b);
+  let shared = 0;
+  for (const w of wordsB) if (wordsA.has(w)) shared++;
+  return shared >= 3;
+}
+
+function mentionsSecurityKeyword(finding) {
+  const haystack = `${finding.title} ${finding.description}`.toLowerCase();
+  return SECURITY_KEYWORDS.some(kw => haystack.includes(kw));
+}
+
+function suppressedByAuthority(candidate, allFindings) {
+  // Docs/Quality findings that mention security keywords are suppressed when Security owns that file
+  if (candidate.agentName === 'docs' || candidate.agentName === 'quality') {
+    if (mentionsSecurityKeyword(candidate)) {
+      const fileKey = (candidate.file || '').toLowerCase();
+      const securityOwnsFile = allFindings.some(
+        f => f.agentName === 'security' && (f.file || '').toLowerCase() === fileKey
+      );
+      if (securityOwnsFile) return true;
+    }
+  }
+
+  // Quality findings about a package are suppressed when Dependencies owns that package
+  if (candidate.agentName === 'quality') {
+    const candidateFile = (candidate.file || '').toLowerCase();
+    const depOwnsPackage = allFindings.some(f => {
+      if (f.agentName !== 'dependencies') return false;
+      const depFile = (f.file || '').toLowerCase();
+      // Match if they reference the same package name (same file token, e.g. "lodash")
+      return depFile && candidateFile && (depFile === candidateFile || candidateFile.includes(depFile) || depFile.includes(candidateFile));
+    });
+    if (depOwnsPackage) return true;
+  }
+
+  return false;
+}
+
+export function deduplicateFindings(allFindings) {
+  // Authority suppression pass — run before similarity grouping
+  const afterSuppression = allFindings.filter(f => !suppressedByAuthority(f, allFindings));
+
+  const byFile = new Map();
+  for (const f of afterSuppression) {
+    const key = (f.file || '').toLowerCase();
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(f);
+  }
+
+  const kept = [];
+  for (const group of byFile.values()) {
+    const merged = [];
+    for (const candidate of group) {
+      const dupIdx = merged.findIndex(m => titlesSimilar(m.title, candidate.title));
+      if (dupIdx === -1) {
+        merged.push(candidate);
+      } else {
+        const existing = merged[dupIdx];
+        const rankCand = SEVERITY_RANK[(candidate.severity || 'low').toLowerCase()] || 1;
+        const rankExist = SEVERITY_RANK[(existing.severity || 'low').toLowerCase()] || 1;
+        if (rankCand > rankExist || (rankCand === rankExist && (candidate.description || '').length > (existing.description || '').length)) {
+          merged[dupIdx] = candidate;
+        }
+      }
+    }
+    kept.push(...merged);
+  }
+  return kept;
+}
+
+function countBySeverity(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) {
+    const sev = (f.severity || 'low').toLowerCase();
+    if (sev in counts) counts[sev]++;
+  }
+  return counts;
+}
+
+function calcRiskScore(findings) {
+  const score = Math.max(0,
+    100
+    - countBySeverity(findings).critical * 25
+    - countBySeverity(findings).high * 15
+    - countBySeverity(findings).medium * 8
+    - countBySeverity(findings).low * 3
+  );
+  if (score >= 90) return { score, emoji: '🟢', label: 'Low Risk' };
+  if (score >= 70) return { score, emoji: '🟡', label: 'Moderate Risk' };
+  if (score >= 40) return { score, emoji: '🟠', label: 'Elevated Risk' };
+  return { score, emoji: '🔴', label: 'High Risk' };
+}
+
+function calcQualityScore(findings) {
+  const score = Math.max(0,
+    100
+    - countBySeverity(findings).critical * 20
+    - countBySeverity(findings).high * 10
+    - countBySeverity(findings).medium * 5
+    - countBySeverity(findings).low * 2
+  );
+  if (score >= 90) return { score, emoji: '🟢', label: 'Excellent' };
+  if (score >= 75) return { score, emoji: '🟡', label: 'Good' };
+  if (score >= 50) return { score, emoji: '🟠', label: 'Needs Work' };
+  return { score, emoji: '🔴', label: 'Needs Significant Work' };
+}
+
+function renderFindings(findings) {
+  if (!findings || findings.length === 0) return '_No issues found._\n';
+  return findings.map(f => {
+    const sev = (f.severity || 'low').toLowerCase();
+    const emoji = SEVERITY_EMOJI[sev] || '⚪';
+    const label = SEVERITY_LABEL[sev] || sev.toUpperCase();
+    return [
+      `#### ${emoji} [${label}] ${f.title}`,
+      `- **File:** \`${f.file}\``,
+      `- **Issue:** ${f.description}`,
+      `- **Fix:** ${f.fix}`,
+    ].join('\n');
+  }).join('\n\n');
+}
+
+export async function generateReport(allResults, projectName, outputDir = '.') {
+  const sections = {
+    security:     { label: 'Security',      findings: (allResults.security     || { findings: [] }).findings },
+    performance:  { label: 'Performance',   findings: (allResults.performance  || { findings: [] }).findings },
+    tests:        { label: 'Test Coverage', findings: (allResults.tests        || { findings: [] }).findings },
+    docs:         { label: 'Documentation', findings: (allResults.docs         || { findings: [] }).findings },
+    dependencies: { label: 'Dependencies',  findings: (allResults.dependencies || { findings: [] }).findings },
+    quality:      { label: 'Code Quality',  findings: (allResults.quality      || { findings: [] }).findings },
+  };
+
+  // Tag every finding with its agent source
+  for (const [agentName, { findings }] of Object.entries(sections)) {
+    for (const f of findings) f.agentName = agentName;
+  }
+
+  const combined = Object.values(sections).flatMap(s => s.findings);
+  const deduped = deduplicateFindings(combined);
+  const duplicatesRemoved = combined.length - deduped.length;
+
+  // Re-partition deduplicated findings back into their sections
+  for (const s of Object.values(sections)) s.findings = [];
+  for (const f of deduped) {
+    if (sections[f.agentName]) sections[f.agentName].findings.push(f);
+  }
+
+  const riskFindings = [...sections.security.findings, ...sections.dependencies.findings];
+  const qualityFindings = [...sections.tests.findings, ...sections.docs.findings, ...sections.performance.findings, ...sections.quality.findings];
+
+  const totals = countBySeverity(deduped);
+  const risk = calcRiskScore(riskFindings);
+  const qual = calcQualityScore(qualityFindings);
+  const date = new Date().toISOString().split('T')[0];
+
+  const report = `# Codebase Audit Report: ${projectName}
+
+**Date:** ${date}
+**Total Findings:** ${deduped.length}
+**Duplicates Removed:** ${duplicatesRemoved} findings merged
+
+---
+
+## Executive Summary
+
+| Severity | Count |
+|----------|-------|
+| ${SEVERITY_EMOJI.critical} Critical | ${totals.critical} |
+| ${SEVERITY_EMOJI.high} High | ${totals.high} |
+| ${SEVERITY_EMOJI.medium} Medium | ${totals.medium} |
+| ${SEVERITY_EMOJI.low} Low | ${totals.low} |
+
+---
+
+## Scores
+
+| | Score | Grade |
+|---|---|---|
+| 🛡️ Risk | ${risk.score}/100 | ${risk.emoji} ${risk.label} |
+| 🔧 Quality | ${qual.score}/100 | ${qual.emoji} ${qual.label} |
+
+**Risk** measures security vulnerabilities and dependency exposure.
+**Quality** measures test coverage, documentation, and code maintainability.
+
+---
+
+## Security
+
+${renderFindings(sections.security.findings)}
+
+---
+
+## Performance
+
+${renderFindings(sections.performance.findings)}
+
+---
+
+## Test Coverage
+
+${renderFindings(sections.tests.findings)}
+
+---
+
+## Documentation
+
+${renderFindings(sections.docs.findings)}
+
+---
+
+## Dependencies
+
+${renderFindings(sections.dependencies.findings)}
+
+---
+
+## Code Quality
+
+${renderFindings(sections.quality.findings)}
+`;
+
+  const outputPath = join(outputDir, 'audit-report.md');
+  await writeFile(outputPath, report, 'utf-8');
+  return { outputPath, totals, totalFindings: deduped.length };
+}

package/src/scanner.js

@@ -0,0 +1,46 @@
+import { readdir, readFile } from 'fs/promises';
+import { join, extname, resolve } from 'path';
+
+const ALLOWED_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.py', '.css', '.html']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '__pycache__']);
+
+async function collectFiles(dir, results = []) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        await collectFiles(fullPath, results);
+      }
+    } else if (entry.isFile() && ALLOWED_EXTENSIONS.has(extname(entry.name))) {
+      try {
+        const content = await readFile(fullPath, 'utf-8');
+        results.push({ path: fullPath, content });
+      } catch {
+        // skip unreadable files
+      }
+    }
+  }
+  return results;
+}
+
+export async function scanDirectory(targetPath) {
+  const absPath = resolve(targetPath);
+  const files = await collectFiles(absPath);
+
+  let packageJson = null;
+  try {
+    const pkgContent = await readFile(join(absPath, 'package.json'), 'utf-8');
+    packageJson = JSON.parse(pkgContent);
+  } catch {
+    // no package.json found
+  }
+
+  return { files, packageJson };
+}