forgedev 1.0.0

package/src/doctor-checks.js

@@ -0,0 +1,743 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function runAllChecks(projectDir, scan) {
+  const issues = [];
+
+  issues.push(...checkClaudeMdLength(projectDir, scan));
+  issues.push(...checkUnauthEndpoints(projectDir, scan));
+  issues.push(...checkFlakyTestPatterns(projectDir));
+  issues.push(...checkCrossDomainImports(projectDir, scan));
+  issues.push(...checkBareExcepts(projectDir));
+  issues.push(...checkMissingHealthEndpoint(projectDir, scan));
+  issues.push(...checkMissingGracefulShutdown(projectDir, scan));
+  issues.push(...checkMissingUAT(scan));
+  issues.push(...checkScatteredAPICalls(projectDir, scan));
+  issues.push(...checkLargeFiles(projectDir));
+  issues.push(...checkMissingScopedClaudeMd(projectDir, scan));
+  issues.push(...checkUnusedDependencies(projectDir, scan));
+  issues.push(...checkHardcodedValues(projectDir));
+  issues.push(...checkUnusedExports(projectDir, scan));
+  issues.push(...checkDuplicateCode(projectDir));
+  issues.push(...checkDeadFeatures(projectDir, scan));
+  issues.push(...checkAIPrompts(projectDir));
+
+  return issues.sort((a, b) => {
+    const order = { critical: 0, warning: 1, info: 2 };
+    return (order[a.severity] ?? 3) - (order[b.severity] ?? 3);
+  });
+}
+
+function checkClaudeMdLength(projectDir, scan) {
+  if (!scan.infrastructure.hasClaudeMd) return [];
+  const lines = scan.infrastructure.claudeMdLines;
+  if (lines <= 150) return [];
+
+  return [{
+    severity: lines > 500 ? 'critical' : 'warning',
+    title: `CLAUDE.md is ${lines} lines (recommended limit: 150)`,
+    impact: 'Instructions are being dropped — Claude Code ignores rules randomly when context is too large',
+    files: ['CLAUDE.md'],
+    autoFixable: false,
+    promptId: 'CLAUDE_MD_TOO_LONG',
+    effort: 'medium',
+  }];
+}
+
+function checkUnauthEndpoints(projectDir, scan) {
+  const issues = [];
+
+  // FastAPI: check for routes missing Depends(get_current_user)
+  if (scan.backend.detected && scan.backend.framework === 'fastapi') {
+    const apiDir = path.join(projectDir, scan.backend.directory || 'backend', 'app', 'api');
+    if (!fs.existsSync(apiDir)) return [];
+
+    const pyFiles = findFiles(apiDir, '.py');
+    for (const file of pyFiles) {
+      if (path.basename(file) === '__init__.py' || path.basename(file) === 'auth.py') continue;
+      const content = fs.readFileSync(file, 'utf-8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/@router\.(get|post|put|delete|patch)\s*\(/.test(line)) {
+          // Look ahead for the function definition and check for auth dependency
+          const fnBlock = lines.slice(i, Math.min(i + 10, lines.length)).join('\n');
+          if (!fnBlock.includes('get_current_user') && !fnBlock.includes('current_user') && !fnBlock.includes('Depends(')) {
+            const relPath = path.relative(projectDir, file);
+            issues.push({
+              severity: 'critical',
+              title: `Unauthenticated endpoint: ${relPath}:${i + 1}`,
+              impact: 'Security vulnerability — data accessible without login',
+              files: [`${relPath}:${i + 1}`],
+              autoFixable: false,
+              promptId: 'UNAUTH_ENDPOINT',
+              effort: 'quick',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Next.js API routes: check for missing auth
+  if (scan.frontend.detected && scan.frontend.framework === 'nextjs') {
+    const srcDir = scan.frontend.directory || 'src';
+    const apiDir = path.join(projectDir, srcDir, 'app', 'api');
+    if (!fs.existsSync(apiDir)) return issues;
+
+    const routeFiles = findFiles(apiDir, '.ts').concat(findFiles(apiDir, '.tsx'));
+    for (const file of routeFiles) {
+      if (path.basename(file) === 'route.ts' || path.basename(file) === 'route.tsx') {
+        // Skip health endpoints
+        if (file.includes('/health/')) continue;
+
+        const content = fs.readFileSync(file, 'utf-8');
+        if (!content.includes('getServerSession') && !content.includes('auth(') &&
+            !content.includes('getToken') && !content.includes('currentUser') &&
+            !content.includes('session')) {
+          const relPath = path.relative(projectDir, file);
+          issues.push({
+            severity: 'warning',
+            title: `API route may lack auth: ${relPath}`,
+            impact: 'Endpoint may be accessible without authentication',
+            files: [relPath],
+            autoFixable: false,
+            promptId: 'UNAUTH_ENDPOINT',
+            effort: 'quick',
+          });
+        }
+      }
+    }
+  }
+
+  // Consolidate multiple unauth endpoints into one issue
+  if (issues.length > 1) {
+    const allFiles = issues.flatMap(i => i.files);
+    const severity = issues.some(i => i.severity === 'critical') ? 'critical' : 'warning';
+    return [{
+      severity,
+      title: `${issues.length} endpoints have no authentication`,
+      impact: 'Security vulnerability — data accessible without login',
+      files: allFiles,
+      autoFixable: false,
+      promptId: 'UNAUTH_ENDPOINT',
+      effort: 'quick',
+    }];
+  }
+
+  return issues;
+}
+
+function checkFlakyTestPatterns(projectDir) {
+  const issues = [];
+  const testDirs = ['tests', 'e2e', '__tests__', 'test', 'frontend/e2e', 'frontend/tests'];
+  const testFiles = [];
+
+  for (const dir of testDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (fs.existsSync(fullDir)) {
+      testFiles.push(...findFiles(fullDir, '.ts'), ...findFiles(fullDir, '.js'), ...findFiles(fullDir, '.py'));
+    }
+  }
+
+  // Also find test files in src
+  const srcDir = path.join(projectDir, 'src');
+  if (fs.existsSync(srcDir)) {
+    const allSrc = findFiles(srcDir, '.ts').concat(findFiles(srcDir, '.js'));
+    testFiles.push(...allSrc.filter(f => f.includes('.test.') || f.includes('.spec.')));
+  }
+
+  const flakyFiles = [];
+  for (const file of testFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes('waitForTimeout') || content.includes('page.waitForTimeout') ||
+        /cy\.wait\(\d+\)/.test(content) || /setTimeout.*\d{3,}/.test(content)) {
+      flakyFiles.push(path.relative(projectDir, file));
+    }
+  }
+
+  if (flakyFiles.length > 0) {
+    issues.push({
+      severity: 'critical',
+      title: `${flakyFiles.length} tests use waitForTimeout() or hardcoded delays`,
+      impact: 'Tests fail randomly — unreliable CI',
+      files: flakyFiles,
+      autoFixable: false,
+      promptId: 'FLAKY_TESTS',
+      effort: 'medium',
+    });
+  }
+
+  return issues;
+}
+
+function checkCrossDomainImports(projectDir, scan) {
+  if (!scan.frontend.detected || !scan.backend.detected) return [];
+  if (scan.stackId !== 'polyglot-fullstack') return [];
+
+  const issues = [];
+  const frontendDir = scan.frontend.directory || 'frontend';
+  const backendDir = scan.backend.directory || 'backend';
+
+  // Check frontend files importing from backend
+  const frontendPath = path.join(projectDir, frontendDir);
+  if (fs.existsSync(frontendPath)) {
+    const frontFiles = findFiles(frontendPath, '.ts').concat(findFiles(frontendPath, '.tsx'), findFiles(frontendPath, '.js'));
+    for (const file of frontFiles) {
+      const content = fs.readFileSync(file, 'utf-8');
+      if (content.includes(`from '../../${backendDir}`) || content.includes(`from '../${backendDir}`) ||
+          content.includes(`import '../../${backendDir}`) || content.includes(`require('../../${backendDir}`)) {
+        issues.push({
+          severity: 'critical',
+          title: `Cross-domain import: ${path.relative(projectDir, file)} imports from ${backendDir}`,
+          impact: 'Build will break or bundle server code into client — security risk',
+          files: [path.relative(projectDir, file)],
+          autoFixable: false,
+          promptId: 'CROSS_DOMAIN_IMPORT',
+          effort: 'medium',
+        });
+      }
+    }
+  }
+
+  if (issues.length > 1) {
+    const allFiles = issues.flatMap(i => i.files);
+    return [{
+      severity: 'critical',
+      title: `${issues.length} cross-domain imports (frontend importing backend or vice versa)`,
+      impact: 'Build will break or bundle server code into client — security risk',
+      files: allFiles,
+      autoFixable: false,
+      promptId: 'CROSS_DOMAIN_IMPORT',
+      effort: 'medium',
+    }];
+  }
+
+  return issues;
+}
+
+function checkBareExcepts(projectDir) {
+  const pyFiles = [];
+  const dirs = ['backend', 'app', 'src', '.'];
+  for (const dir of dirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (fs.existsSync(fullDir) && fs.statSync(fullDir).isDirectory()) {
+      pyFiles.push(...findFiles(fullDir, '.py'));
+    }
+  }
+
+  const bareExceptFiles = [];
+  for (const file of pyFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim();
+      if (trimmed === 'except:' || trimmed === 'except :') {
+        bareExceptFiles.push(`${path.relative(projectDir, file)}:${i + 1}`);
+      }
+    }
+  }
+
+  if (bareExceptFiles.length === 0) return [];
+
+  return [{
+    severity: 'warning',
+    title: `${bareExceptFiles.length} bare except: blocks`,
+    impact: 'Silently swallows real errors, makes debugging impossible',
+    files: bareExceptFiles,
+    autoFixable: false,
+    promptId: 'BARE_EXCEPT',
+    effort: 'quick',
+  }];
+}
+
+function checkMissingHealthEndpoint(projectDir, scan) {
+  // Search for health endpoints by file path or content
+  const patterns = ['/health', '/healthz', '/api/health'];
+  const searchDirs = ['src', 'backend', 'app', 'frontend/src'];
+
+  for (const dir of searchDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.js'), findFiles(fullDir, '.py'));
+    for (const file of files) {
+      // Check file path (e.g., src/app/api/health/route.ts)
+      const relPath = path.relative(projectDir, file).replace(/\\/g, '/');
+      if (relPath.includes('/health/') || relPath.includes('/healthz/')) {
+        return [];
+      }
+      // Check file content
+      const content = fs.readFileSync(file, 'utf-8');
+      if (patterns.some(p => content.includes(p))) {
+        return [];
+      }
+    }
+  }
+
+  return [{
+    severity: 'warning',
+    title: 'No health check endpoint',
+    impact: 'Load balancers and monitoring can\'t verify app is running',
+    files: [],
+    autoFixable: false,
+    promptId: 'MISSING_HEALTH',
+    effort: 'quick',
+  }];
+}
+
+function checkMissingGracefulShutdown(projectDir, scan) {
+  const searchDirs = ['src', 'backend', 'app', 'frontend/src'];
+  const signals = ['SIGTERM', 'SIGINT', 'process.on', 'signal.signal', 'lifespan'];
+
+  for (const dir of searchDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.js'), findFiles(fullDir, '.py'));
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf-8');
+      if (signals.some(s => content.includes(s))) {
+        return [];
+      }
+    }
+  }
+
+  return [{
+    severity: 'warning',
+    title: 'No graceful shutdown handler',
+    impact: 'Deployments may drop in-flight requests',
+    files: [],
+    autoFixable: false,
+    promptId: 'MISSING_SHUTDOWN',
+    effort: 'quick',
+  }];
+}
+
+function checkMissingUAT(scan) {
+  if (scan.infrastructure.hasUAT) return [];
+  return [{
+    severity: 'warning',
+    title: 'No UAT scenarios',
+    impact: 'No formal acceptance criteria — features may not work as intended',
+    files: [],
+    autoFixable: false,
+    promptId: 'MISSING_UAT',
+    effort: 'medium',
+  }];
+}
+
+function checkScatteredAPICalls(projectDir, scan) {
+  if (!scan.frontend.detected) return [];
+
+  const srcDir = path.join(projectDir, scan.frontend.directory || 'src');
+  if (!fs.existsSync(srcDir)) return [];
+
+  const files = findFiles(srcDir, '.tsx').concat(findFiles(srcDir, '.jsx'));
+  const scattered = [];
+
+  for (const file of files) {
+    const basename = path.basename(file);
+    // Skip files that ARE the API client
+    if (['api.ts', 'api.js', 'apiClient.ts', 'apiClient.js', 'fetcher.ts', 'fetcher.js'].includes(basename)) continue;
+    // Skip non-component files
+    if (file.includes('/lib/') || file.includes('/services/') || file.includes('/utils/')) continue;
+
+    const content = fs.readFileSync(file, 'utf-8');
+    if (/fetch\s*\(\s*['"`]\/api\//.test(content) || /fetch\s*\(\s*['"`]http/.test(content) ||
+        /axios\.(get|post|put|delete|patch)\s*\(/.test(content)) {
+      scattered.push(path.relative(projectDir, file));
+    }
+  }
+
+  if (scattered.length <= 3) return [];
+
+  return [{
+    severity: 'warning',
+    title: `${scattered.length} components make direct API calls instead of using a centralized client`,
+    impact: 'API changes require updating every component instead of one file',
+    files: scattered,
+    autoFixable: false,
+    promptId: 'SCATTERED_API_CALLS',
+    effort: 'medium',
+  }];
+}
+
+function checkLargeFiles(projectDir) {
+  const sourceDirs = ['src', 'backend', 'app', 'frontend/src', 'frontend'];
+  const largeFiles = [];
+
+  for (const dir of sourceDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts')
+      .concat(findFiles(fullDir, '.tsx'), findFiles(fullDir, '.js'), findFiles(fullDir, '.jsx'), findFiles(fullDir, '.py'));
+
+    for (const file of files) {
+      // Skip generated/vendor files
+      if (file.includes('node_modules') || file.includes('.next') || file.includes('__pycache__')) continue;
+      const content = fs.readFileSync(file, 'utf-8');
+      const lineCount = content.split('\n').length;
+      if (lineCount > 500) {
+        largeFiles.push({ file: path.relative(projectDir, file), lines: lineCount });
+      }
+    }
+  }
+
+  if (largeFiles.length === 0) return [];
+
+  return [{
+    severity: 'info',
+    title: `${largeFiles.length} files over 500 lines — candidates for splitting`,
+    impact: 'Large files are hard to navigate, review, and test',
+    files: largeFiles.map(f => `${f.file} (${f.lines} lines)`),
+    autoFixable: false,
+    promptId: 'LARGE_FILES',
+    effort: 'large',
+  }];
+}
+
+function checkMissingScopedClaudeMd(projectDir, scan) {
+  if (!scan.frontend.detected || !scan.backend.detected) return [];
+
+  const issues = [];
+  const frontendDir = scan.frontend.directory || 'src';
+  const backendDir = scan.backend.directory || 'backend';
+
+  if (!fs.existsSync(path.join(projectDir, frontendDir, 'CLAUDE.md'))) {
+    issues.push({
+      severity: 'info',
+      title: `No ${frontendDir}/CLAUDE.md — frontend rules not scoped`,
+      impact: 'Claude Code loads all rules even when working only on frontend',
+      files: [],
+      autoFixable: false,
+      promptId: 'MISSING_SCOPED_CLAUDE_MD',
+      effort: 'quick',
+    });
+  }
+
+  if (!fs.existsSync(path.join(projectDir, backendDir, 'CLAUDE.md'))) {
+    issues.push({
+      severity: 'info',
+      title: `No ${backendDir}/CLAUDE.md — backend rules not scoped`,
+      impact: 'Claude Code loads all rules even when working only on backend',
+      files: [],
+      autoFixable: false,
+      promptId: 'MISSING_SCOPED_CLAUDE_MD',
+      effort: 'quick',
+    });
+  }
+
+  return issues;
+}
+
+function checkUnusedDependencies(projectDir, scan) {
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return [];
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  const deps = Object.keys(pkg.dependencies || {});
+  if (deps.length === 0) return [];
+
+  // Gather all source file contents
+  const srcDirs = ['src', 'app', 'frontend/src', 'pages', 'components', 'lib'];
+  let allContent = '';
+  for (const dir of srcDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.tsx'), findFiles(fullDir, '.js'), findFiles(fullDir, '.jsx'));
+    for (const file of files) {
+      allContent += fs.readFileSync(file, 'utf-8') + '\n';
+    }
+  }
+
+  // Also check config files at root
+  const configFiles = ['next.config.ts', 'next.config.js', 'next.config.mjs', 'tailwind.config.ts', 'tailwind.config.js', 'postcss.config.js', 'postcss.config.mjs'];
+  for (const cf of configFiles) {
+    const cfPath = path.join(projectDir, cf);
+    if (fs.existsSync(cfPath)) {
+      allContent += fs.readFileSync(cfPath, 'utf-8') + '\n';
+    }
+  }
+
+  // Skip framework deps that are used implicitly
+  const implicitDeps = ['react', 'react-dom', 'next', '@prisma/client', 'typescript'];
+  const unused = deps.filter(dep => {
+    if (implicitDeps.includes(dep)) return false;
+    // Check if the package name appears in imports
+    const shortName = dep.startsWith('@') ? dep : dep.split('/')[0];
+    return !allContent.includes(shortName);
+  });
+
+  if (unused.length === 0) return [];
+
+  return [{
+    severity: 'info',
+    title: `${unused.length} potentially unused dependencies`,
+    impact: 'Bloats install size and increases supply chain risk',
+    files: unused.map(d => `package.json → ${d}`),
+    autoFixable: false,
+    promptId: 'UNUSED_DEPENDENCIES',
+    effort: 'quick',
+  }];
+}
+
+function checkHardcodedValues(projectDir) {
+  const sourceDirs = ['src', 'backend', 'app', 'frontend/src'];
+  const hardcoded = [];
+
+  const patterns = [
+    { regex: /['"]http:\/\/localhost:\d+/, label: 'hardcoded localhost URL' },
+    { regex: /['"]postgresql:\/\//, label: 'hardcoded database URL' },
+    { regex: /['"]mongodb:\/\//, label: 'hardcoded database URL' },
+    { regex: /['"]redis:\/\//, label: 'hardcoded redis URL' },
+    { regex: /['"]sk-[a-zA-Z0-9]{20,}['"]/, label: 'possible API key' },
+    { regex: /port\s*[:=]\s*\d{4,5}\b/i, label: 'hardcoded port number' },
+  ];
+
+  for (const dir of sourceDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.tsx'), findFiles(fullDir, '.js'), findFiles(fullDir, '.jsx'), findFiles(fullDir, '.py'));
+
+    for (const file of files) {
+      // Skip config and env files
+      const basename = path.basename(file);
+      if (basename.includes('.config.') || basename.includes('.env') || basename.includes('.test.') || basename.includes('.spec.')) continue;
+
+      const content = fs.readFileSync(file, 'utf-8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Skip comments
+        if (line.trim().startsWith('//') || line.trim().startsWith('#')) continue;
+        for (const pat of patterns) {
+          if (pat.regex.test(line)) {
+            hardcoded.push(`${path.relative(projectDir, file)}:${i + 1} (${pat.label})`);
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  if (hardcoded.length === 0) return [];
+
+  return [{
+    severity: 'warning',
+    title: `${hardcoded.length} hardcoded values that should be in environment variables`,
+    impact: 'Cannot change config without code changes — breaks deployment',
+    files: hardcoded,
+    autoFixable: false,
+    promptId: 'HARDCODED_VALUES',
+    effort: 'medium',
+  }];
+}
+
+function checkUnusedExports(projectDir, scan) {
+  const srcDir = path.join(projectDir, scan.frontend?.directory || 'src');
+  if (!fs.existsSync(srcDir)) return [];
+
+  const files = findFiles(srcDir, '.ts').concat(findFiles(srcDir, '.tsx'), findFiles(srcDir, '.js'), findFiles(srcDir, '.jsx'));
+  if (files.length === 0) return [];
+
+  // Collect all exports and imports
+  const exportMap = new Map(); // name -> file
+  const importedNames = new Set();
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const relPath = path.relative(projectDir, file);
+
+    // Skip barrel files and index files
+    if (path.basename(file).startsWith('index.')) continue;
+
+    // Find named exports
+    const exportMatches = content.matchAll(/export\s+(?:function|const|class|type|interface|enum)\s+(\w+)/g);
+    for (const m of exportMatches) {
+      // Skip default page/layout/route exports (Next.js convention)
+      if (['default', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'generateMetadata', 'generateStaticParams'].includes(m[1])) continue;
+      exportMap.set(`${relPath}:${m[1]}`, relPath);
+    }
+
+    // Find imports
+    const importMatches = content.matchAll(/import\s+\{([^}]+)\}/g);
+    for (const m of importMatches) {
+      const names = m[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim());
+      names.forEach(n => importedNames.add(n));
+    }
+  }
+
+  const unused = [];
+  for (const [key] of exportMap) {
+    const name = key.substring(key.lastIndexOf(':') + 1);
+    if (!importedNames.has(name)) {
+      unused.push(key);
+    }
+  }
+
+  // Only report if there's a meaningful number
+  if (unused.length < 5) return [];
+
+  return [{
+    severity: 'info',
+    title: `${unused.length} exported symbols may be unused`,
+    impact: 'Dead exports add confusion and increase bundle size',
+    files: unused.slice(0, 20),
+    autoFixable: false,
+    promptId: 'UNUSED_EXPORTS',
+    effort: 'medium',
+  }];
+}
+
+function checkDuplicateCode(projectDir) {
+  const sourceDirs = ['src', 'backend', 'app', 'frontend/src'];
+  const functionBodies = new Map(); // hash -> [{file, line, name}]
+
+  for (const dir of sourceDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.tsx'), findFiles(fullDir, '.js'), findFiles(fullDir, '.jsx'), findFiles(fullDir, '.py'));
+
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf-8');
+      const lines = content.split('\n');
+
+      // Look for consecutive blocks of 6+ identical lines
+      for (let i = 0; i <= lines.length - 6; i++) {
+        const block = lines.slice(i, i + 6).map(l => l.trim()).filter(l => l.length > 0);
+        if (block.length < 4) continue;
+        const key = block.join('|');
+        if (key.length < 50) continue; // Skip trivial blocks
+
+        if (!functionBodies.has(key)) {
+          functionBodies.set(key, []);
+        }
+        functionBodies.get(key).push({ file: path.relative(projectDir, file), line: i + 1 });
+      }
+    }
+  }
+
+  const duplicates = [];
+  for (const [, locations] of functionBodies) {
+    // Must appear in different files
+    const uniqueFiles = new Set(locations.map(l => l.file));
+    if (uniqueFiles.size > 1) {
+      duplicates.push(locations.map(l => `${l.file}:${l.line}`));
+    }
+  }
+
+  if (duplicates.length === 0) return [];
+
+  const flatFiles = [...new Set(duplicates.flat())].slice(0, 15);
+  return [{
+    severity: 'info',
+    title: `${duplicates.length} code blocks appear duplicated across files`,
+    impact: 'Bug fixes need to be applied in multiple places',
+    files: flatFiles,
+    autoFixable: false,
+    promptId: 'DUPLICATE_CODE',
+    effort: 'medium',
+  }];
+}
+
+function checkDeadFeatures(projectDir, scan) {
+  // Look for route/page files that aren't linked from anywhere
+  if (!scan.frontend.detected) return [];
+
+  const srcDir = path.join(projectDir, scan.frontend.directory || 'src');
+  if (!fs.existsSync(srcDir)) return [];
+
+  const allFiles = findFiles(srcDir, '.ts').concat(findFiles(srcDir, '.tsx'), findFiles(srcDir, '.js'), findFiles(srcDir, '.jsx'));
+  const dead = [];
+
+  for (const file of allFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+
+    // Check for disabled/commented-out route handlers
+    if (content.includes('// export') && (content.includes('function GET') || content.includes('function POST'))) {
+      dead.push(`${path.relative(projectDir, file)} (commented-out route handler)`);
+    }
+
+    // Check for components with only a TODO placeholder
+    if (content.includes('TODO') && content.split('\n').length < 10) {
+      dead.push(`${path.relative(projectDir, file)} (stub/placeholder only)`);
+    }
+  }
+
+  if (dead.length === 0) return [];
+
+  return [{
+    severity: 'info',
+    title: `${dead.length} potentially dead or stub features`,
+    impact: 'Dead code adds confusion and maintenance burden',
+    files: dead,
+    autoFixable: false,
+    promptId: 'DEAD_FEATURES',
+    effort: 'quick',
+  }];
+}
+
+function checkAIPrompts(projectDir) {
+  const sourceDirs = ['src', 'backend', 'app', 'frontend/src', 'lib'];
+  const issues = [];
+
+  for (const dir of sourceDirs) {
+    const fullDir = path.join(projectDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    const files = findFiles(fullDir, '.ts').concat(findFiles(fullDir, '.tsx'), findFiles(fullDir, '.js'), findFiles(fullDir, '.jsx'), findFiles(fullDir, '.py'));
+
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf-8');
+
+      // Check for inline prompts (strings containing common prompt patterns)
+      if (/(?:system|user)\s*(?:message|prompt|role)\s*[:=]/i.test(content) ||
+          content.includes('openai.chat.completions') || content.includes('anthropic.messages') ||
+          content.includes('ChatCompletion') || content.includes('messages=[')) {
+
+        // Check if prompts are inline strings rather than imported from a prompts file
+        const basename = path.basename(file);
+        if (!basename.includes('prompt') && !basename.includes('template')) {
+          const relPath = path.relative(projectDir, file);
+          issues.push(relPath);
+        }
+      }
+    }
+  }
+
+  if (issues.length === 0) return [];
+
+  return [{
+    severity: 'info',
+    title: `${issues.length} files have inline AI prompts — consider a prompts file`,
+    impact: 'Inline prompts are hard to version, test, and iterate on',
+    files: issues,
+    autoFixable: false,
+    promptId: 'INLINE_AI_PROMPTS',
+    effort: 'medium',
+  }];
+}
+
+// Helpers
+
+function findFiles(dir, ext) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (['node_modules', '.next', '__pycache__', '.git', 'venv', '.venv', 'dist', 'build'].includes(entry.name)) continue;
+        results.push(...findFiles(fullPath, ext));
+      } else if (entry.name.endsWith(ext)) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+    // Permission errors, etc.
+  }
+
+  return results;
+}