claudex-setup 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {

package/src/audit.js

@@ -61,17 +61,20 @@ async function audit(options) {
     });
   }
 
-  const passed = results.filter(r => r.passed);
-  const failed = results.filter(r => !r.passed);
+  // null = not applicable (skip), true = pass, false = fail
+  const applicable = results.filter(r => r.passed !== null);
+  const skipped = results.filter(r => r.passed === null);
+  const passed = applicable.filter(r => r.passed);
+  const failed = applicable.filter(r => !r.passed);
   const critical = failed.filter(r => r.impact === 'critical');
   const high = failed.filter(r => r.impact === 'high');
   const medium = failed.filter(r => r.impact === 'medium');
 
-  // Calculate score
+  // Calculate score only from applicable checks
   const weights = { critical: 15, high: 10, medium: 5 };
-  const maxScore = results.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
+  const maxScore = applicable.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const earnedScore = passed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
-  const score = Math.round((earnedScore / maxScore) * 100);
+  const score = maxScore > 0 ? Math.round((earnedScore / maxScore) * 100) : 0;
 
   // Silent mode: skip all output, just return result
   if (silent) {
@@ -153,7 +156,7 @@ async function audit(options) {
 
   // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
-  console.log(`  ${colorize(`${passed.length}/${results.length}`, 'bold')} checks passing`);
+  console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable)`, 'dim') : ''}`);
 
   if (failed.length > 0) {
     console.log(`  Run ${colorize('npx claudex-setup setup', 'bold')} to fix automatically`);

package/src/setup.js

@@ -25,16 +25,110 @@ function detectScripts(ctx) {
   return found;
 }
 
+// ============================================================
+// Helper: detect key dependencies and generate guidelines
+// ============================================================
+function detectDependencies(ctx) {
+  const pkg = ctx.jsonFile('package.json');
+  if (!pkg) return [];
+  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const guidelines = [];
+
+  // Data fetching
+  if (allDeps['@tanstack/react-query']) {
+    guidelines.push('- Use React Query (TanStack Query) for all server data fetching — never raw useEffect + fetch');
+    guidelines.push('- Define query keys as constants. Invalidate related queries after mutations');
+  }
+  if (allDeps['swr']) {
+    guidelines.push('- Use SWR for data fetching with automatic revalidation');
+  }
+
+  // Validation
+  if (allDeps['zod']) {
+    guidelines.push('- Use Zod for all input validation and type inference (z.infer<typeof schema>)');
+    guidelines.push('- Define schemas in a shared location. Use .parse() at API boundaries');
+  }
+
+  // ORM / Database
+  if (allDeps['prisma'] || allDeps['@prisma/client']) {
+    guidelines.push('- Use Prisma for all database operations. Run `npx prisma generate` after schema changes');
+    guidelines.push('- Never write raw SQL unless Prisma cannot express the query');
+  }
+  if (allDeps['drizzle-orm']) {
+    guidelines.push('- Use Drizzle ORM for database operations. Schema-first approach');
+  }
+  if (allDeps['mongoose']) {
+    guidelines.push('- Use Mongoose for MongoDB operations. Define schemas with validation');
+  }
+
+  // Auth
+  if (allDeps['next-auth'] || allDeps['@auth/core']) {
+    guidelines.push('- Use NextAuth.js for authentication. Access session via auth() in Server Components');
+  }
+  if (allDeps['clerk'] || allDeps['@clerk/nextjs']) {
+    guidelines.push('- Use Clerk for authentication. Protect routes with middleware');
+  }
+
+  // State management
+  if (allDeps['zustand']) {
+    guidelines.push('- Use Zustand for client state. Keep stores small and focused');
+  }
+  if (allDeps['@reduxjs/toolkit']) {
+    guidelines.push('- Use Redux Toolkit for state management. Use createSlice and RTK Query');
+  }
+
+  // Styling
+  if (allDeps['tailwindcss']) {
+    guidelines.push('- Use Tailwind CSS for all styling. Avoid inline styles and CSS modules');
+  }
+  if (allDeps['styled-components'] || allDeps['@emotion/react']) {
+    guidelines.push('- Use CSS-in-JS for component styling. Colocate styles with components');
+  }
+
+  // Testing
+  if (allDeps['vitest']) {
+    guidelines.push('- Use Vitest for testing. Colocate test files with source (*.test.ts)');
+  }
+  if (allDeps['jest']) {
+    guidelines.push('- Use Jest for testing. Follow existing test patterns in the codebase');
+  }
+  if (allDeps['playwright'] || allDeps['@playwright/test']) {
+    guidelines.push('- Use Playwright for E2E tests. Keep tests in tests/ or e2e/');
+  }
+
+  // Python
+  const reqTxt = ctx.fileContent('requirements.txt') || '';
+  if (reqTxt.includes('sqlalchemy')) {
+    guidelines.push('- Use SQLAlchemy for all database operations');
+  }
+  if (reqTxt.includes('pydantic')) {
+    guidelines.push('- Use Pydantic for data validation and serialization');
+  }
+  if (reqTxt.includes('pytest')) {
+    guidelines.push('- Use pytest for testing. Run with `python -m pytest`');
+  }
+
+  return guidelines;
+}
+
 // ============================================================
 // Helper: detect main directories
 // ============================================================
 function detectMainDirs(ctx) {
-  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware'];
+  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware', 'hooks'];
+  // Also check inside src/ for nested structure (common in Next.js, React)
+  const srcNested = ['src/components', 'src/app', 'src/pages', 'src/api', 'src/lib', 'src/hooks', 'src/utils', 'src/services', 'src/models', 'src/middleware', 'src/app/api', 'app/api'];
   const found = [];
-  for (const dir of candidates) {
+  const seenNames = new Set();
+
+  for (const dir of [...candidates, ...srcNested]) {
     if (ctx.hasDir(dir)) {
       const files = ctx.dirFiles(dir);
-      found.push({ name: dir, fileCount: files.length, files: files.slice(0, 10) });
+      const displayName = dir.includes('/') ? dir : dir;
+      if (!seenNames.has(displayName)) {
+        found.push({ name: displayName, fileCount: files.length, files: files.slice(0, 10) });
+        seenNames.add(displayName);
+      }
     }
   }
   return found;
@@ -61,31 +155,63 @@ function generateMermaid(dirs, stacks) {
     return `    ${id}[${label}]`;
   }
 
-  // Entry point
-  nodes.push(addNode('Entry Point', 'round'));
+  // Detect Next.js App Router specifically
+  const hasAppRouter = dirNames.includes('app') || dirNames.includes('src/app');
+  const hasPages = dirNames.includes('pages') || dirNames.includes('src/pages');
+  const hasAppApi = dirNames.includes('app/api') || dirNames.includes('src/app/api');
+  const hasSrcComponents = dirNames.includes('src/components') || dirNames.includes('components');
+  const hasSrcHooks = dirNames.includes('src/hooks') || dirNames.includes('hooks');
+  const hasSrcLib = dirNames.includes('src/lib') || dirNames.includes('lib');
+
+  // Smart entry point based on framework
+  const isNextJs = stackKeys.includes('nextjs');
+  const isDjango = stackKeys.includes('django');
+  const isFastApi = stackKeys.includes('fastapi');
+
+  if (isNextJs) {
+    nodes.push(addNode('Next.js', 'round'));
+  } else if (isDjango) {
+    nodes.push(addNode('Django', 'round'));
+  } else if (isFastApi) {
+    nodes.push(addNode('FastAPI', 'round'));
+  } else {
+    nodes.push(addNode('Entry Point', 'round'));
+  }
+
+  const root = ids['Next.js'] || ids['Django'] || ids['FastAPI'] || ids['Entry Point'];
 
   // Detect layers
-  if (dirNames.includes('app') || dirNames.includes('pages')) {
-    nodes.push(addNode('Pages / Routes', 'default'));
-    edges.push(`    ${ids['Entry Point']} --> ${ids['Pages / Routes']}`);
+  if (hasAppRouter || hasPages) {
+    const label = hasAppRouter ? 'App Router' : 'Pages';
+    nodes.push(addNode(label, 'default'));
+    edges.push(`    ${root} --> ${ids[label]}`);
+  }
+
+  if (hasAppApi) {
+    nodes.push(addNode('API Routes', 'default'));
+    const parent = ids['App Router'] || ids['Pages'] || root;
+    edges.push(`    ${parent} --> ${ids['API Routes']}`);
   }
 
-  if (dirNames.includes('components')) {
+  if (hasSrcComponents) {
     nodes.push(addNode('Components', 'default'));
-    const parent = ids['Pages / Routes'] || ids['Entry Point'];
+    const parent = ids['App Router'] || ids['Pages'] || root;
     edges.push(`    ${parent} --> ${ids['Components']}`);
   }
 
-  if (dirNames.includes('src')) {
-    nodes.push(addNode('src/', 'default'));
-    const parent = ids['Pages / Routes'] || ids['Entry Point'];
-    edges.push(`    ${parent} --> ${ids['src/']}`);
+  if (hasSrcHooks) {
+    nodes.push(addNode('Hooks', 'default'));
+    const parent = ids['Components'] || root;
+    edges.push(`    ${parent} --> ${ids['Hooks']}`);
   }
 
-  if (dirNames.includes('lib')) {
+  if (hasSrcLib) {
     nodes.push(addNode('lib/', 'default'));
-    const parent = ids['src/'] || ids['Entry Point'];
+    const parent = ids['API Routes'] || ids['Hooks'] || ids['Components'] || root;
     edges.push(`    ${parent} --> ${ids['lib/']}`);
+  } else if (dirNames.includes('src') && !hasAppRouter && !hasPages) {
+    nodes.push(addNode('src/', 'default'));
+    edges.push(`    ${root} --> ${ids['src/']}`);
   }
 
   if (dirNames.includes('api') || dirNames.includes('routes') || dirNames.includes('controllers')) {
@@ -316,6 +442,13 @@ npm run lint         # or: npx eslint .`;
       }
     }
 
+    // --- Dependency-specific guidelines ---
+    const depGuidelines = detectDependencies(ctx);
+    const depSection = depGuidelines.length > 0 ? `
+## Key Dependencies
+${depGuidelines.join('\n')}
+` : '';
+
     // --- Verification criteria based on detected commands ---
     const verificationSteps = [];
     verificationSteps.push('1. All existing tests still pass');
@@ -348,7 +481,7 @@ ${mermaid}
 ${dirDescription}
 ## Stack
 ${stackNames}
-${stackSection}${tsSection}
+${stackSection}${tsSection}${depSection}
 ## Build & Test
 \`\`\`bash
 ${buildSection}
@@ -379,6 +512,9 @@ ${verificationSteps.join('\n')}
 - Use descriptive commit messages (why, not what)
 - Create focused PRs — one concern per PR
 - Document non-obvious decisions in code comments
+
+---
+*Generated by [claudex-setup](https://github.com/DnaFin/claudex-setup) v${require('../package.json').version} on ${new Date().toISOString().split('T')[0]}. Customize this file for your project — a hand-crafted CLAUDE.md will always be better than a generated one.*
 `;
   },
 
@@ -413,8 +549,9 @@ echo '{"decision": "allow"}'
 # Appends to .claude/logs/file-changes.log
 
 INPUT=$(cat -)
-TOOL_NAME=$(echo "$INPUT" | grep -oP '"tool_name"\\s*:\\s*"\\K[^"]+' 2>/dev/null || echo "unknown")
-FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\\s*:\\s*"\\K[^"]+' 2>/dev/null || echo "")
+TOOL_NAME=$(echo "$INPUT" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
+TOOL_NAME=\${TOOL_NAME:-unknown}
+FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
 
 if [ -z "$FILE_PATH" ]; then
   exit 0
@@ -590,7 +727,13 @@ async function setup(options) {
 
     if (typeof result === 'string') {
       // Single file template (like CLAUDE.md)
-      const filePath = key === 'claudeMd' ? 'CLAUDE.md' : key;
+      // Map technique keys to actual file paths
+      const filePathMap = {
+        'claudeMd': 'CLAUDE.md',
+        'mermaidArchitecture': 'CLAUDE.md', // mermaid is part of CLAUDE.md, skip separate file
+      };
+      if (key === 'mermaidArchitecture') continue; // Mermaid is generated inside CLAUDE.md template
+      const filePath = filePathMap[key] || key;
       const fullPath = path.join(options.dir, filePath);
 
       if (!fs.existsSync(fullPath)) {

package/src/techniques.js

@@ -344,8 +344,8 @@ const TECHNIQUES = {
     name: 'Default mode is not bypassPermissions',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings) return true; // no settings = not bypassed
-      return settings.defaultMode !== 'bypassPermissions';
+      if (!settings || !settings.permissions) return null; // no settings = skip (not applicable)
+      return settings.permissions.defaultMode !== 'bypassPermissions';
     },
     impact: 'critical',
     rating: 5,
@@ -840,7 +840,7 @@ const TECHNIQUES = {
     name: 'Hooks use specific matchers (not catch-all)',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.hooks) return true; // no hooks = skip
+      if (!settings || !settings.hooks) return null; // no hooks = not applicable
       const hookStr = JSON.stringify(settings.hooks);
       // Check that hooks have matchers, not just catch-all
       return hookStr.includes('matcher');
@@ -852,28 +852,15 @@ const TECHNIQUES = {
     template: null
   },
 
-  permissionsNotBypassed: {
-    id: 2005,
-    name: 'Default mode is not bypassPermissions',
-    check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.permissions) return true;
-      return settings.permissions.defaultMode !== 'bypassPermissions';
-    },
-    impact: 'high',
-    rating: 4,
-    category: 'quality-deep',
-    fix: 'bypassPermissions skips all safety checks. Use "default" or "auto" mode with targeted allow rules instead.',
-    template: null
-  },
+  // permissionsNotBypassed removed - duplicate of noBypassPermissions (#24)
 
   commandsUseArguments: {
     id: 2006,
     name: 'Commands use $ARGUMENTS for flexibility',
     check: (ctx) => {
-      if (!ctx.hasDir('.claude/commands')) return true;
+      if (!ctx.hasDir('.claude/commands')) return null; // not applicable
       const files = ctx.dirFiles('.claude/commands');
-      if (files.length === 0) return true;
+      if (files.length === 0) return null;
       // Check if at least one command uses $ARGUMENTS
       for (const f of files) {
         const content = ctx.fileContent(`.claude/commands/${f}`) || '';
@@ -892,9 +879,9 @@ const TECHNIQUES = {
     id: 2007,
     name: 'Agents have maxTurns limit',
     check: (ctx) => {
-      if (!ctx.hasDir('.claude/agents')) return true;
+      if (!ctx.hasDir('.claude/agents')) return null;
       const files = ctx.dirFiles('.claude/agents');
-      if (files.length === 0) return true;
+      if (files.length === 0) return null;
       for (const f of files) {
         const content = ctx.fileContent(`.claude/agents/${f}`) || '';
         if (!content.includes('maxTurns')) return false;