Code Analysis & Context Engineering MCP

A sophisticated Model Context Protocol (MCP) server that provides deep codebase understanding through architectural analysis, pattern detection, dependency mapping, test coverage analysis, and AI-optimized context generation.

Features

• 🏗️ Architecture Analysis: Comprehensive architectural overview with component relationships, data flow, and navigation patterns
• 🔍 Pattern Detection: Identify framework-specific patterns, custom implementations, and antipatterns
• 📊 Dependency Mapping: Visualize module dependencies, detect circular dependencies, and analyze coupling
• 🧪 Coverage Analysis: Find untested code with actionable test suggestions based on complexity
• ✅ Convention Validation: Validate adherence to project-specific naming and coding conventions
• 🤖 Context Generation: Build optimal AI context packs respecting token limits and maximizing relevance
• 🔒 Security Analysis: Detect vulnerabilities with OWASP mapping, framework-aware checks, and positive pattern recognition

Supported Frameworks & Platforms

Web Frameworks

• ✅ React - Hooks, Context API, HOCs, Render Props, Compound Components
• ✅ Vue 3 - Composition API, SFCs, Composables, provide/inject, Pinia stores
• ✅ Nuxt 3 & 4 - Auto-imports, file-based routing, server routes (Nitro), layouts, middleware, plugins, Pinia stores

Mobile Frameworks

• ✅ React Native - React Navigation (Stack/Tab/Drawer), Platform-specific code, Native modules, Animations (Reanimated), Gesture handlers
• ✅ Expo - Expo Router, Expo SDK, File-based routing, Platform features (Camera, Location, Notifications)

Backend Frameworks

• ✅ Fastify - Routes, plugins, hooks, decorators, JSON Schema validation
• ✅ PostgreSQL - Query patterns, parameterized queries, transactions
• ✅ Kafka - Producers, consumers, topics, error handling
• ✅ Alyxstream - Stream processing tasks, operators, windowing, Kafka integration

UI Libraries

• ✅ Nuxt UI 4 - Component detection (UButton, UCard, UInput, UModal), Theming patterns, Design system integration

Test Frameworks

• ✅ Vitest - Test generation, coverage analysis, Vue/Nuxt testing with @vue/test-utils
• ✅ Jest - Test scaffolding, React/React Native testing with Testing Library
• ✅ Playwright - E2E testing patterns

State Management

• ✅ Pinia - Store detection, test generation with setActivePinia
• ✅ Context API - Provider patterns, hook-based state
• ✅ Zustand - Store pattern detection
• ✅ Redux - Action/reducer patterns

Installation

npm install
npm run build

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "code-analysis": {
      "command": "node",
      "args": ["/path/to/code-analysis-context-mcp/dist/index.js"]
    }
  }
}

Available Tools

1. arch

Generate comprehensive architectural overview:

React / React Native projects:

{
  "path": "/path/to/react-project",
  "depth": "d",
  "types": ["comp", "hooks", "nav"],
  "diagrams": true,
  "metrics": true,
  "details": true,  // Include per-file metrics
  "minCx": 15,      // Only show files with complexity >= 15
  "maxFiles": 20    // Limit to top 20 most complex files
}

Nuxt 3/4 & Vue 3 projects:

{
  "path": "/path/to/nuxt-project",
  "depth": "d",
  "types": ["comp", "use", "store", "route", "layout", "mid"],
  "fw": "nuxt3",    // or "vue3"
  "diagrams": true,
  "metrics": true,
  "details": true,
  "minCx": 10,
  "maxFiles": 30
}

Fastify Backend projects:

{
  "path": "/path/to/fastify-project",
  "depth": "d",
  "fw": "fastify",
  "diagrams": true,
  "metrics": true,
  "details": true,
  "minCx": 5,
  "maxFiles": 40
}

New Features:

• Per-file metrics: Set details: true to get complexity, lines, imports/exports, and patterns
• Auto-optimization: For projects >100 files, automatically filters to complexity ≥ 10 (top 50 files) to reduce response size
• Complexity filtering: Use minCx to only show files above a threshold (e.g., 15 for refactoring candidates)
• Result limiting: Use maxFiles to limit response size for large projects (e.g., top 20 most complex)
• Automatic framework globs: Supports both root-level and src/ directory structures for all frameworks
• Files automatically sorted by complexity (most complex first)

Response Size Optimization:

• Small projects (<100 files): Returns all files (~5-10k tokens)
• Large projects (>100 files): Auto-filters to complexity ≥ 10, top 50 files (~3-5k tokens) ⭐
• Override with explicit minCx: 0 or maxFiles: 999 if you need all files

LLM Memory Integration 🧠:

Store analysis results in the llm_memory MCP for persistent project knowledge:

{
  "path": "/path/to/project",
  "details": true,
  "memSuggest": true  // Generate memory suggestions
}

This returns structured memorySuggestions that Claude Code can store across different scopes:

Example Output:

{
  "memorySuggestions": [
    {
      "scope": "committed",
      "type": "insight",
      "title": "High Complexity Files in MyProject",
      "text": "Critical refactoring targets:\n- src/services/Tracking.ts (complexity: 161, 450 lines)\n- src/components/Dashboard.tsx (complexity: 87, 324 lines)\n\nThese files exceed complexity threshold of 20...",
      "tags": ["complexity", "refactoring", "technical-debt", "nuxt3"],
      "files": ["src/services/Tracking.ts", "src/components/Dashboard.tsx"],
      "confidence": 0.9
    },
    {
      "scope": "local",
      "type": "pattern",
      "title": "MyProject Architecture Pattern",
      "text": "Framework: nuxt3\nState Management: pinia\nArchitecture Layers: Pages, Components, Composables, Stores, Server\n\nThis project follows a modular structure with 45 components.",
      "tags": ["architecture", "nuxt3", "overview"],
      "confidence": 0.95
    },
    {
      "scope": "global",
      "type": "pattern",
      "title": "Nuxt 3 Auto-Import Pattern",
      "text": "Nuxt 3 projects auto-import composables and components:\n- Composables from composables/ directory\n- Components from components/ directory\n- No explicit imports needed",
      "tags": ["nuxt3", "composables", "auto-import", "pattern"],
      "confidence": 0.85
    }
  ]
}

Memory Scopes:

• global: Reusable knowledge across all projects (framework patterns, best practices)
• local: Current session context (architecture overview, metrics)
• committed: Project-persistent, team-visible (high-complexity files, stores config)

Usage with llm_memory MCP:

After receiving memory suggestions, Claude Code can store them:

// Claude Code automatically calls llm_memory MCP for each suggestion
memory_upsert({
  scope: "committed",
  type: "insight",
  title: "High Complexity Files in MyProject",
  text: "Critical refactoring targets...",
  tags: ["complexity", "refactoring", "technical-debt", "nuxt3"],
  files: ["src/services/Tracking.ts"],
  confidence: 0.9,
});

Benefits:

• 📝 Persistent project knowledge survives conversation compacting
• 🎯 Critical insights available across sessions (high-complexity files, architecture decisions)
• 🌍 Reusable patterns stored globally (framework best practices)
• 👥 Team-visible technical debt tracking (committed scope)

2. deps

Visualize and analyze module dependencies with circular dependency detection, coupling metrics, and dependency hotspot identification:

{
  "path": "/path/to/project",
  "inc": ["src/**/*.{ts,tsx,js,jsx,vue}"],
  "exc": ["**/node_modules/**", "**/*.test.*"],
  "circular": true,      // Detect circular dependencies
  "metrics": true,       // Calculate coupling/cohesion/stability
  "diagram": true,       // Generate Mermaid diagram
  "focus": "src/services",  // Focus on specific module
  "depth": 3,            // Maximum dependency depth
  "external": false      // Include node_modules dependencies
}

Features:

• Circular Dependency Detection: Uses DFS with recursion stack to identify cycles

  • Critical severity for short cycles (≤3 modules)
  • Warning severity for longer cycles
  • Provides cycle path visualization (A → B → C → A)

• Dependency Metrics:

  • Coupling: Average of (inDegree + outDegree) across all modules
  • Cohesion: Inverse of average fanout (simplified LCOM)
  • Stability: Ce / (Ca + Ce) where Ce = efferent, Ca = afferent coupling
  • Average dependencies per module
  • Maximum dependencies (highest fanout)

• Hotspot Identification:

  • Hubs: Modules with high in-degree (≥5 dependents) → Core utilities
  • Bottlenecks: Modules with high out-degree (≥10 dependencies) → Refactoring candidates
  • God Objects: High in both directions → Architecture issues

• Mermaid Diagram Generation:

  • Color-coded nodes (green=hub, pink=god object, yellow=bottleneck)
  • Dotted lines for circular dependencies
  • Dynamic import indicators
  • Module type classification (component/hook/utility/service/store/composable)

• Module Focusing: BFS-based filtering to analyze specific module and its dependencies

• Depth Limiting: Control analysis depth for large projects

Example Output:

{
  "project": {
    "name": "MyProject",
    "totalFiles": 120
  },
  "graph": {
    "nodes": [
      {
        "id": "src/utils/api-client.ts",
        "path": "src/utils/api-client.ts",
        "type": "service",
        "exports": ["ApiClient", "fetchData"],
        "metrics": {
          "inDegree": 15,  // 15 modules depend on this
          "outDegree": 3,
          "centrality": 0.15
        }
      }
    ],
    "edges": [
      {
        "from": "src/components/Dashboard.tsx",
        "to": "src/utils/api-client.ts",
        "type": "import",
        "imports": ["ApiClient", "fetchData"]
      }
    ]
  },
  "circularDependencies": [
    {
      "cycle": ["src/services/auth.ts", "src/services/user.ts", "src/services/auth.ts"],
      "severity": "critical",
      "description": "Circular dependency detected: src/services/auth.ts → src/services/user.ts → src/services/auth.ts"
    }
  ],
  "metrics": {
    "totalModules": 120,
    "avgDependencies": 4.5,
    "maxDependencies": 18,
    "coupling": 9.2,
    "cohesion": 0.22,
    "stability": 0.45
  },
  "hotspots": [
    {
      "file": "src/utils/api-client.ts",
      "inDegree": 15,
      "outDegree": 3,
      "centrality": 0.15,
      "type": "hub",
      "description": "Core module: 15 modules depend on this"
    },
    {
      "file": "src/components/Dashboard.tsx",
      "inDegree": 2,
      "outDegree": 18,
      "centrality": 0.167,
      "type": "bottleneck",
      "description": "Potential bottleneck: depends on 18 modules"
    }
  ],
  "diagram": "graph TD\n  N0[\"api-client.ts\"]:::hub\n  N1[\"Dashboard.tsx\"]:::bottleneck\n  ...",
  "recommendations": [
    "⚠️ CRITICAL: Found 1 circular dependencies. These can cause runtime errors and make code hard to maintain.",
    "High coupling detected (9.20). Consider applying dependency inversion and interface segregation principles.",
    "Some modules depend on 18 other modules. Consider reducing dependencies through better abstractions."
  ],
  "summary": {
    "totalDependencies": 540,
    "averageDepth": 3.2,
    "isolatedModules": 5,
    "circularCount": 1
  }
}

Use Cases:

1. Identify Core Utilities: Find hub modules that are heavily imported
2. Detect Refactoring Candidates: Bottleneck modules with too many dependencies
3. Fix Architecture Issues: Circular dependencies and god objects
4. Assess Modularity: Coupling and stability metrics
5. Visualize Dependencies: Mermaid diagrams for team discussions

3. patterns

Detect framework-specific patterns, custom implementations, and antipatterns:

React projects:

{
  "path": "/path/to/react-project",
  "types": ["hooks", "hoc", "prov", "rp"],
  "custom": true,
  "best": true,
  "suggest": true
}

Nuxt 3/Vue 3 projects:

{
  "path": "/path/to/nuxt-project",
  "types": ["use", "pinia", "plug", "mod", "mid"],
  "custom": true,
  "best": true,
  "suggest": true
}

Detected Patterns:

React & React Native:

• Hooks: Standard (useState, useEffect, etc.) and custom hooks
• HOCs: Higher-Order Components (withAuth, withRouter)
• Render Props: Components using render/children function props
• Compound Components: Parent.Child component patterns
• Context Providers: Context API usage
• React Navigation: useNavigation, NavigationContainer, Stack/Tab/Drawer navigators
• Platform-Specific Code: Platform.OS, Platform.select, .ios/.android file extensions
• Animations: Animated API, Reanimated (useAnimatedStyle, withTiming)
• Gesture Handlers: PanGestureHandler, TapGestureHandler, GestureDetector
• Mobile Storage: AsyncStorage, SecureStore, MMKV
• Permission Handling: Permissions API, requestPermission patterns
• Push Notifications: Notifications API, FCM integration
• Media Access: Camera, ImagePicker, MediaLibrary
• Location Services: Location API, getCurrentPosition, watchPosition
• Native Modules: NativeModules, requireNativeComponent, NativeEventEmitter
• Deep Linking: Linking API, universal links, URL schemes

Vue 3 & Nuxt 3:

• Composables: Composition API functions (use* pattern)
• Pinia Stores: Store definitions with state/getters/actions
• Vue Plugins: Plugins with install functions
• Vue Directives: Custom v-* directives
• Nuxt Modules: Module definitions (defineNuxtModule)
• Nuxt Middleware: Route middleware patterns

Common Patterns:

• Data Fetching: fetch, axios, useFetch, useQuery patterns
• Error Handling: try-catch blocks, Error Boundaries
• Forms: useForm, Formik, native form patterns

Parameters:

• types: Filter specific pattern types to detect
• custom: Identify frequently used custom patterns (≥3 files)
• best: Compare against industry standards
• suggest: Get detailed refactoring recommendations

Example Output:

{
  "project": {
    "name": "MyProject",
    "type": "react",
    "totalFiles": 45
  },
  "patterns": {
    "customHooks": [
      {
        "name": "useAuth",
        "file": "src/hooks/useAuth.ts",
        "line": 12,
        "type": "custom-hooks",
        "confidence": 0.9,
        "description": "Custom React hook: useAuth"
      }
    ],
    "hocs": [
      {
        "name": "withAuth",
        "file": "src/hoc/withAuth.tsx",
        "wrappedComponent": "Component",
        "enhancedProps": []
      }
    ],
    "providers": [
      {
        "name": "AuthContext.Provider",
        "file": "src/context/AuthContext.tsx",
        "line": 25,
        "type": "providers",
        "confidence": 1.0,
        "description": "Context Provider usage"
      }
    ]
  },
  "antipatterns": [
    {
      "type": "excessive-providers",
      "file": "multiple",
      "severity": "warning",
      "description": "Found 12 Context providers",
      "suggestion": "Consider consolidating providers or using a state management library"
    }
  ],
  "bestPractices": [
    {
      "pattern": "Functional Components with Hooks",
      "status": "follows",
      "details": "Project uses React hooks for state management",
      "suggestions": null
    }
  ],
  "recommendations": [
    "Consider extracting reusable logic into custom hooks.",
    "Many Context providers detected. Consider using Redux or Zustand."
  ],
  "summary": {
    "totalPatterns": 45,
    "byType": {
      "customHooks": 12,
      "hooks": 23,
      "providers": 8,
      "dataFetching": 2
    },
    "mostCommon": ["hooks", "customHooks", "providers"]
  }
}

4. coverage

Identify untested code with meaningful, actionable test suggestions prioritized by criticality and complexity:

{
  "path": "/path/to/project",
  "report": "coverage/lcov.info",  // Optional: LCOV or JSON
  "fw": "vitest",                  // Auto-detected if not specified
  "threshold": {                   // Coverage thresholds
    "lines": 80,
    "functions": 80,
    "branches": 75,
    "statements": 80
  },
  "priority": "high",              // "crit" | "high" | "med" | "low" | "all"
  "inc": ["src/**/*.{ts,tsx,js,jsx,vue}"],
  "exc": ["**/*.test.*", "**/*.spec.*"],
  "tests": true,                   // Generate test scaffolds
  "cx": true                       // Factor complexity into priority
}

Core Features:

• Intelligent Prioritization: Multi-factor scoring system

  • File Criticality: Directory-based classification (core/important/standard/peripheral)
    • Core: utils/, lib/, services/, api/, stores/, composables/ (high-impact utilities)
    • Important: hooks/, providers/, context/ (widely-used abstractions)
    • Standard: components/, pages/ (UI layers)
    • Peripheral: Other files
  • Complexity Analysis: Cyclomatic complexity scoring (AST-based)
  • Import Frequency: Files imported by many others → higher criticality
  • Coverage Deficits: Below-threshold gaps weighted by criticality

• Priority Formula:

  CRITICAL: core files with 0% coverage + complexity >30, OR core files below threshold
  HIGH:     important files with low coverage, OR complexity >50 + coverage <50%
  MEDIUM:   standard files below threshold
  LOW:      peripheral files or above threshold

• Test Framework Detection: Auto-detects from package.json and existing tests

  • Vitest (prioritized for modern projects)
  • Jest
  • Playwright
  • Mocha
  • Ava

• Coverage Report Parsing:

  • LCOV format: Parses SF/DA/FN/FNDA/BRF/BRH records
  • JSON format: Istanbul/NYC coverage data (l/f/b/s)
  • Gracefully handles missing reports (analyzes all files as untested)

• Existing Test Pattern Detection: Analyzes your existing tests to extract:

  • Import statement patterns
  • Assertion library (expect vs assert)
  • Mocking library (vi.mock vs jest.mock)
  • Render function (render vs mount)
  • Setup patterns (beforeEach, afterEach, beforeAll)
  • Common test helpers and utilities

• Framework-Specific Test Scaffolds: Generates meaningful tests based on file type and framework:

  React Components (*.tsx, *.jsx):

  import { describe, it, expect } from 'vitest';
  import { render, screen } from '@testing-library/react';
  import Dashboard from './Dashboard';
  
  describe('Dashboard', () => {
    it('should render without crashing', () => {
      const { container } = render(<Dashboard />);
      expect(container).toBeTruthy();
    });
  
    it('should render with correct props', () => {
      render(<Dashboard />);
      // Add assertions based on component props
    });
  
    it('should handle onClick correctly', () => {
      render(<Dashboard />);
      // Test onClick functionality
    });
  });

  React Hooks (use*.ts in hooks/):

  import { describe, it, expect } from 'vitest';
  import { renderHook, act } from '@testing-library/react';
  import { useAuth } from './useAuth';
  
  describe('useAuth', () => {
    it('should initialize with correct default values', () => {
      const { result } = renderHook(() => useAuth());
      expect(result.current).toBeDefined();
    });
  
    it('should update state correctly', () => {
      const { result } = renderHook(() => useAuth());
      act(() => {
        // Trigger state updates
      });
      // Add assertions
    });
  });

  React Native Components (*.tsx, *.jsx in screens/):

  import { describe, it, expect } from 'jest';
  import { render, fireEvent, screen } from '@testing-library/react-native';
  import { NavigationContainer } from '@react-navigation/native';
  import HomeScreen from './HomeScreen';
  
  // Mock navigation
  const mockNavigation = {
    navigate: jest.fn(),
    goBack: jest.fn(),
    setOptions: jest.fn(),
  };
  
  const mockRoute = {
    params: {},
    key: 'test',
    name: 'HomeScreen',
  };
  
  describe('HomeScreen', () => {
    it('should render without crashing', () => {
      const { container } = render(
        <NavigationContainer>
          <HomeScreen navigation={mockNavigation} route={mockRoute} />
        </NavigationContainer>
      );
      expect(container).toBeTruthy();
    });
  
    it('should handle navigation correctly', () => {
      render(
        <NavigationContainer>
          <HomeScreen navigation={mockNavigation} route={mockRoute} />
        </NavigationContainer>
      );
  
      fireEvent.press(screen.getByText('Go to Profile'));
      expect(mockNavigation.navigate).toHaveBeenCalledWith('Profile');
    });
  });

  React Native Hooks (use*.ts in hooks/):

  import { describe, it, expect } from 'jest';
  import { renderHook, act, waitFor } from '@testing-library/react-native';
  import { useLocation } from './useLocation';
  
  describe('useLocation', () => {
    it('should initialize with correct default values', () => {
      const { result } = renderHook(() => useLocation());
      expect(result.current).toBeDefined();
    });
  
    it('should handle async operations', async () => {
      const { result } = renderHook(() => useLocation());
  
      await waitFor(() => {
        expect(result.current.loading).toBe(false);
      });
  
      expect(result.current.location).toBeDefined();
    });
  });

  Vue 3 Components (*.vue):

  import { describe, it, expect, beforeEach } from 'vitest';
  import { mount, flushPromises } from '@vue/test-utils';
  import { mockNuxtImport } from '@nuxt/test-utils/runtime';
  import MyComponent from './MyComponent.vue';
  
  describe('MyComponent', () => {
    beforeEach(() => {
      // Reset mocks before each test (Nuxt projects)
      vi.clearAllMocks();
    });
  
    it('should mount successfully', () => {
      const wrapper = mount(MyComponent);
      expect(wrapper.exists()).toBe(true);
    });
  
    it('should render with correct props', async () => {
      const wrapper = mount(MyComponent, {
        props: { title: 'Test Title' }
      });
      expect(wrapper.text()).toContain('Test Title');
    });
  
    it('should emit events correctly', async () => {
      const wrapper = mount(MyComponent);
      await wrapper.find('button').trigger('click');
      expect(wrapper.emitted('submit')).toBeTruthy();
    });
  
    it('should work with Nuxt auto-imports', async () => {
      const wrapper = mount(MyComponent);
      // Test composables, navigateTo, etc.
      await flushPromises();
      expect(wrapper.vm).toBeDefined();
    });
  });

  Vue 3 Composables (use*.ts in composables/):

  import { describe, it, expect, beforeEach } from 'vitest';
  import { mockNuxtImport } from '@nuxt/test-utils/runtime';
  import { useMyComposable } from './useMyComposable';
  
  describe('useMyComposable', () => {
    beforeEach(() => {
      vi.clearAllMocks();
    });
  
    it('should return expected values', () => {
      const result = useMyComposable();
      expect(result).toBeDefined();
      // Verify returned refs, computed, or functions
    });
  
    it('should handle reactive state correctly', () => {
      const { count, increment } = useMyComposable();
      increment();
      expect(count.value).toBe(1);
    });
  
    it('should handle async operations', async () => {
      const { data, fetchData } = useMyComposable();
      await fetchData();
      expect(data.value).toBeDefined();
    });
  
    it('should work with Nuxt auto-imports', () => {
      // Test composables that use useRoute, useRouter, navigateTo, etc.
      const result = useMyComposable();
      expect(result).toBeDefined();
    });
  });

  Pinia Stores (stores/*.ts):

  import { describe, it, expect, beforeEach } from 'vitest';
  import { setActivePinia, createPinia } from 'pinia';
  import { useMyStore } from './useMyStore';
  
  describe('useMyStore', () => {
    beforeEach(() => {
      // Create a fresh pinia instance for each test
      setActivePinia(createPinia());
    });
  
    it('should initialize with default state', () => {
      const store = useMyStore();
      expect(store.count).toBe(0);
    });
  
    it('should update state correctly', () => {
      const store = useMyStore();
      store.count = 10;
      expect(store.count).toBe(10);
    });
  
    it('should compute derived state', () => {
      const store = useMyStore();
      store.count = 5;
      expect(store.doubleCount).toBe(10);
    });
  
    it('should handle actions correctly', async () => {
      const store = useMyStore();
      await store.increment();
      expect(store.count).toBe(1);
    });
  });

  Nuxt Server Routes (server/api/*.ts):

  import { describe, it, expect, beforeEach } from 'vitest';
  import { mockNuxtImport } from '@nuxt/test-utils/runtime';
  import handler from './users';
  
  describe('Server Route: users', () => {
    beforeEach(() => {
      vi.clearAllMocks();
    });
  
    it('should handle GET request', async () => {
      const event = {
        node: {
          req: { method: 'GET', url: '/api/users' },
          res: { statusCode: 200 }
        }
      };
  
      const response = await handler(event);
      expect(response).toBeDefined();
      expect(Array.isArray(response)).toBe(true);
    });
  
    it('should handle POST request with body', async () => {
      const event = {
        node: {
          req: { method: 'POST', url: '/api/users' },
          res: { statusCode: 200 }
        }
      };
  
      // Mock readBody
      mockNuxtImport('readBody', () => vi.fn().mockResolvedValue({
        name: 'Test User'
      }));
  
      const response = await handler(event);
      expect(response).toBeDefined();
    });
  
    it('should handle errors gracefully', async () => {
      const event = {
        node: {
          req: { method: 'GET', url: '/api/users' },
          res: { statusCode: 200 }
        }
      };
  
      expect(async () => await handler(event)).not.toThrow();
    });
  });

  Utility Functions (utils/, lib/, helpers/):

  import { describe, it, expect } from 'vitest';
  import { formatDate, parseDate } from './date-utils';
  
  describe('date-utils', () => {
    describe('formatDate', () => {
      it('should handle valid input', () => {
        const result = formatDate(new Date('2025-01-01'));
        expect(result).toBeDefined();
      });
  
      it('should handle edge cases', () => {
        // Test edge cases: null, undefined, invalid dates
      });
  
      it('should throw on invalid input', () => {
        expect(() => formatDate(null)).toThrow();
      });
    });
  });

Example Output:

{
  "project": {
    "name": "MyProject",
    "totalFiles": 120,
    "framework": "react"
  },
  "summary": {
    "overallCoverage": {
      "lines": 65.5,
      "functions": 58.2,
      "branches": 45.0,
      "statements": 64.8
    },
    "testedFiles": 85,
    "untestedFiles": 25,
    "partiallyTestedFiles": 10,
    "testFramework": "vitest"
  },
  "threshold": {
    "lines": 80,
    "functions": 80,
    "branches": 75,
    "statements": 80
  },
  "gaps": [
    {
      "file": "src/utils/api-client.ts",
      "priority": "critical",
      "criticality": "core",
      "complexity": 87,
      "coverage": {
        "lines": 0,
        "functions": 0,
        "branches": 0,
        "statements": 0
      },
      "reasons": [
        "No test coverage",
        "Core utility - high impact if bugs present",
        "High complexity (87) - error-prone"
      ],
      "untestedFunctions": [
        { "name": "fetchData", "line": 15, "complexity": 25 },
        { "name": "postData", "line": 42, "complexity": 18 },
        { "name": "handleError", "line": 78, "complexity": 12 }
      ],
      "untestedLines": [15, 16, 17, 42, 43, 78, 79],
      "testSuggestions": [
        {
          "type": "unit",
          "framework": "vitest",
          "testFilePath": "src/utils/api-client.test.ts",
          "scaffold": "import { describe, it, expect } from 'vitest';\nimport { fetchData, postData } from './api-client';\n\ndescribe('api-client', () => {\n  describe('fetchData', () => {\n    it('should handle valid input', () => {\n      const result = fetchData(/* valid input */);\n      expect(result).toBeDefined();\n    });\n\n    it('should handle edge cases', () => {\n      // Test edge cases: null, undefined, empty, etc.\n    });\n\n    it('should throw on invalid input', () => {\n      expect(() => fetchData(/* invalid input */)).toThrow();\n    });\n  });\n});",
          "description": "Utility tests for 3 functions: fetchData, postData, handleError",
          "priority": "critical",
          "estimatedEffort": "high"
        }
      ]
    },
    {
      "file": "src/hooks/useAuth.ts",
      "priority": "high",
      "criticality": "important",
      "complexity": 45,
      "coverage": {
        "lines": 25.5,
        "functions": 20.0,
        "branches": 15.0,
        "statements": 24.0
      },
      "reasons": [
        "Line coverage 25.5% below threshold 80%",
        "Function coverage 20.0% below threshold 80%",
        "Important file - widely used across codebase",
        "Moderate complexity (45) - needs testing"
      ],
      "untestedFunctions": [
        { "name": "login", "complexity": 15 },
        { "name": "logout", "complexity": 8 }
      ],
      "untestedLines": [23, 24, 25, 56, 57],
      "testSuggestions": [
        {
          "type": "hook",
          "framework": "vitest",
          "testFilePath": "src/hooks/useAuth.test.ts",
          "scaffold": "import { describe, it, expect } from 'vitest';\nimport { renderHook, act } from '@testing-library/react';\nimport { useAuth } from './useAuth';\n\ndescribe('useAuth', () => {\n  it('should initialize with correct default values', () => {\n    const { result } = renderHook(() => useAuth());\n    expect(result.current).toBeDefined();\n  });\n\n  it('should update state correctly', () => {\n    const { result } = renderHook(() => useAuth());\n\n    act(() => {\n      // Trigger state updates\n    });\n\n    // Add assertions\n  });\n\n  it('should handle login correctly', () => {\n    const { result } = renderHook(() => useAuth());\n    // Test login functionality\n  });\n\n  it('should handle logout correctly', () => {\n    const { result } = renderHook(() => useAuth());\n    // Test logout functionality\n  });\n});",
          "description": "Hook test for useAuth covering 2 functions",
          "priority": "high",
          "estimatedEffort": "medium"
        }
      ]
    }
  ],
  "criticalGaps": [
    {
      "file": "src/utils/api-client.ts",
      "priority": "critical",
      "criticality": "core",
      "complexity": 87
    }
  ],
  "existingTestPatterns": {
    "framework": "vitest",
    "patterns": {
      "importStatements": [
        "import { describe, it, expect } from 'vitest'",
        "import { render, screen } from '@testing-library/react'"
      ],
      "setupPatterns": ["beforeEach", "afterEach"],
      "assertionLibrary": "expect",
      "mockingLibrary": "vi.mock",
      "renderFunction": "render",
      "commonHelpers": []
    },
    "exampleFiles": [
      "src/components/__tests__/Button.test.tsx",
      "src/hooks/__tests__/useData.test.ts"
    ]
  },
  "recommendations": [
    "⚠️ CRITICAL: Found 1 high-priority coverage gaps in core files. These should be addressed immediately.",
    "Line coverage is 65.5%, 14.5% below target. Focus on testing untested core utilities first.",
    "1 core utility files lack adequate coverage. These are high-impact - start here.",
    "2 high-complexity files (complexity > 50) need tests. Complex code is error-prone."
  ],
  "metadata": {
    "coverageReportPath": "coverage/lcov.info",
    "analyzedAt": "2025-10-09T14:30:00.000Z",
    "gapsAboveThreshold": 2
  }
}

Use Cases:

1. Identify Critical Testing Gaps:

   • Core utilities with 0% coverage
   • High-complexity files without tests
   • Widely-imported modules with low coverage

2. Generate Meaningful Test Scaffolds:

   • Framework-aware (React vs Vue vs generic)
   • Matches existing project test patterns
   • Includes all untested functions
   • Provides descriptive test names

3. Prioritize Test Development:

   • Focus on critical/high priority first
   • Complexity-based ordering within priority
   • Estimated effort per test suggestion

4. Track Coverage Progress:

   • Overall coverage percentages
   • Files tested vs untested
   • Gap count by priority level

5. Enforce Coverage Standards:

   • Configurable thresholds per metric
   • Identify files below threshold
   • CI/CD integration ready

5. conventions

Validate adherence to project-specific naming, structure, and coding conventions with intelligent auto-detection and auto-fix capabilities:

{
  "path": "/path/to/project",
  "inc": ["**/*.{ts,tsx,js,jsx,vue}"],
  "exc": ["**/node_modules/**", "**/dist/**"],
  "rules": {                         // Optional: Provide custom conventions
    "naming": {
      "components": {
        "pattern": "PascalCase",
        "description": "Components should use PascalCase"
      },
      "hooks": {
        "pattern": "use[A-Z][a-zA-Z]+",
        "description": "Hooks must start with 'use'"
      }
    },
    "imports": {
      "grouping": true,
      "style": "relative"
    },
    "style": {
      "quotes": "single",
      "semicolons": true
    }
  },
  "auto": true,                      // Auto-detect from existing code
  "severity": "warn"                 // Minimum severity: "err" | "warn" | "info"
}

Core Features:

• Auto-Detection of Project Conventions: Analyzes existing codebase to learn your conventions:

  • Component Naming: Detects PascalCase vs kebab-case vs camelCase (70%+ confidence threshold)
  • Hook/Composable Naming: Identifies use* prefix patterns
  • Import Style: Relative vs absolute imports
  • Quote Style: Single vs double quotes
  • Provides confidence scores for each detected pattern

• Multi-Category Validation:

  • Naming: Components, hooks, composables, utilities, constants, types, files, directories
  • Structure: Directory organization, file organization patterns
  • Imports: Import order, grouping, style (relative/absolute)
  • Style: Quotes, semicolons, trailing commas, indentation
  • Framework-Specific: React hooks, Vue composables, Nuxt conventions

• Severity Levels:

  • Error: Critical violations that break functionality or best practices
  • Warning: Important consistency issues affecting maintainability
  • Info: Style preferences for improved consistency

• Framework-Specific Rules:

  React/React Native:

  • Hooks must start with use prefix (useAuth, useState, useEffect)
  • Components in PascalCase
  • Custom hooks in hooks/ directory

  Vue 3/Nuxt 3:

  • Composables must start with use prefix
  • Components in components/ directory
  • Auto-import awareness (Nuxt 3)

  All Frameworks:

  • Utility functions in camelCase
  • Constants in SCREAMING_SNAKE_CASE
  • Types/Interfaces in PascalCase

• Auto-Fix Capabilities:

  Safe Auto-Fixes (can be applied automatically):

  • Rename files to match casing conventions
  • Reorder imports by type (external, internal, relative)
  • Replace quote styles (single ↔ double)
  • Add blank lines between import groups

  Manual Fixes (suggestions provided):

  • Convert absolute imports to relative (or vice versa)
  • Restructure file organization
  • Fix complex naming violations

• Consistency Scoring:

  • Overall consistency score (0-100%)
  • Per-category scores (naming, imports, style, etc.)
  • Strengths: Categories with ≥90% consistency
  • Weaknesses: Categories with <70% consistency

Example Output:

{
  "project": {
    "name": "MyProject",
    "framework": "react",
    "totalFiles": 85
  },
  "detectedConventions": [
    {
      "category": "naming",
      "rule": "Component naming",
      "pattern": "PascalCase",
      "confidence": 0.95,
      "occurrences": 42,
      "examples": [
        "src/components/Dashboard.tsx",
        "src/components/UserProfile.tsx",
        "src/screens/HomeScreen.tsx"
      ]
    },
    {
      "category": "naming",
      "rule": "Hook naming",
      "pattern": "use[A-Z][a-zA-Z]+",
      "confidence": 0.98,
      "occurrences": 12,
      "examples": ["useAuth.ts", "useData.ts", "useLocalStorage.ts"]
    },
    {
      "category": "imports",
      "rule": "Import style",
      "pattern": "relative",
      "confidence": 0.85,
      "occurrences": 156,
      "examples": [
        "import { Button } from './components/Button'",
        "import { useAuth } from '../hooks/useAuth'"
      ]
    },
    {
      "category": "style",
      "rule": "Quote style",
      "pattern": "single",
      "confidence": 0.92,
      "occurrences": 487,
      "examples": [
        "const name = 'value';",
        "import React from 'react';"
      ]
    }
  ],
  "conventions": {
    "naming": {
      "components": {
        "pattern": "PascalCase",
        "description": "Components should use PascalCase",
        "examples": ["Dashboard", "UserProfile", "HomeScreen"]
      },
      "hooks": {
        "pattern": "use[A-Z][a-zA-Z]+",
        "description": "Hooks should start with 'use' followed by PascalCase name",
        "examples": ["useAuth", "useData"]
      }
    },
    "imports": {
      "grouping": true,
      "order": ["external", "internal", "relative"],
      "style": "relative"
    },
    "style": {
      "quotes": "single",
      "semicolons": true
    }
  },
  "violations": [
    {
      "file": "src/components/user-settings.tsx",
      "line": null,
      "column": null,
      "category": "naming",
      "severity": "warning",
      "rule": "Component naming",
      "message": "File name should use PascalCase",
      "expected": "PascalCase (e.g., MyComponent)",
      "actual": "user-settings",
      "autoFixable": true,
      "autoFix": {
        "type": "rename",
        "description": "Rename to UserSettings",
        "currentValue": "user-settings",
        "newValue": "UserSettings",
        "safe": true,
        "preview": "user-settings → UserSettings"
      }
    },
    {
      "file": "src/hooks/getUser.ts",
      "category": "naming",
      "severity": "warning",
      "rule": "Hook naming",
      "message": "File name should use PascalCase",
      "expected": "use[A-Z][a-zA-Z]+",
      "actual": "getUser",
      "autoFixable": true,
      "autoFix": {
        "type": "rename",
        "description": "Rename to useUser (hooks should start with 'use')",
        "currentValue": "getUser",
        "newValue": "useUser",
        "safe": true
      }
    },
    {
      "file": "src/components/Dashboard.tsx",
      "line": 5,
      "category": "imports",
      "severity": "info",
      "rule": "Import grouping",
      "message": "Imports should be grouped by type (external, internal, relative)",
      "autoFixable": true,
      "autoFix": {
        "type": "reorder",
        "description": "Group imports by type with blank lines",
        "safe": true
      }
    },
    {
      "file": "src/utils/api-client.ts",
      "line": 42,
      "category": "style",
      "severity": "info",
      "rule": "Quote style",
      "message": "Project uses single quotes",
      "expected": "single quotes (')",
      "actual": "double quotes (\")",
      "autoFixable": true,
      "autoFix": {
        "type": "replace",
        "description": "Replace double quotes with single quotes",
        "safe": true
      }
    }
  ],
  "consistency": {
    "overall": 87,
    "byCategory": {
      "naming": 85,
      "structure": 100,
      "imports": 78,
      "exports": 100,
      "style": 92,
      "framework-specific": 95
    },
    "strengths": [
      "structure: 100% consistent",
      "exports: 100% consistent",
      "framework-specific: 95% consistent",
      "style: 92% consistent"
    ],
    "weaknesses": [
      "imports: 78% consistent"
    ]
  },
  "summary": {
    "totalViolations": 18,
    "byCategory": {
      "naming": 5,
      "structure": 0,
      "imports": 8,
      "exports": 0,
      "style": 5,
      "framework-specific": 0
    },
    "bySeverity": {
      "error": 0,
      "warning": 5,
      "info": 13
    },
    "autoFixableCount": 15
  },
  "autoFixSuggestions": [
    {
      "category": "naming",
      "severity": "warning",
      "affectedFiles": [
        "src/components/user-settings.tsx",
        "src/hooks/getUser.ts"
      ],
      "description": "Fix Component naming violations in 2 file(s)",
      "fixes": [
        {
          "type": "rename",
          "description": "Rename to UserSettings",
          "currentValue": "user-settings",
          "newValue": "UserSettings",
          "safe": true,
          "preview": "user-settings → UserSettings"
        },
        {
          "type": "rename",
          "description": "Rename to useUser",
          "currentValue": "getUser",
          "newValue": "useUser",
          "safe": true
        }
      ],
      "estimatedImpact": "low",
      "safe": true
    },
    {
      "category": "imports",
      "severity": "info",
      "affectedFiles": [
        "src/components/Dashboard.tsx",
        "src/components/UserProfile.tsx",
        "src/hooks/useAuth.ts"
      ],
      "description": "Fix Import grouping violations in 3 file(s)",
      "fixes": [
        {
          "type": "reorder",
          "description": "Group imports by type with blank lines",
          "safe": true
        }
      ],
      "estimatedImpact": "low",
      "safe": true
    }
  ],
  "recommendations": [
    "Good consistency (87%), but there's room for improvement.",
    "Found 5 naming inconsistencies. Consider using a consistent casing style for components.",
    "Found 8 import style inconsistencies. Use a tool like ESLint to enforce import ordering.",
    "15 violations can be auto-fixed. Run with applyAutoFixes: true to fix them."
  ],
  "metadata": {
    "analyzedAt": "2025-10-09T15:45:00.000Z",
    "filesAnalyzed": 85
  }
}

Use Cases:

1. Enforce Project Standards:

   • Ensure all team members follow the same conventions
   • Catch inconsistencies during code review
   • CI/CD integration for automated checks

2. Onboard New Developers:

   • Auto-detect and document existing conventions
   • Provide clear examples of project patterns
   • Immediate feedback on convention violations

3. Refactor Legacy Code:

   • Identify inconsistencies across the codebase
   • Generate auto-fix suggestions for bulk updates
   • Track consistency improvements over time

4. Framework Migration:

   • Validate Vue 3 composable naming (use* prefix)
   • Ensure React hooks follow conventions
   • Verify Nuxt 3 auto-import patterns

5. Pre-Commit Hooks:

   • Validate conventions before commit
   • Auto-fix safe violations
   • Block commits with critical violations

Workflow Examples:

// 1. Initial analysis - detect what conventions exist
conventions({
  path: "/path/to/project",
  auto: true
});
// → Returns detected patterns with confidence scores

// 2. Validate against detected conventions
conventions({
  path: "/path/to/project",
  auto: true,
  severity: "warn"  // Only show warnings and errors
});
// → Returns violations with severity ≥ warning

// 3. Validate against custom conventions
conventions({
  path: "/path/to/project",
  rules: {
    naming: {
      components: {
        pattern: "kebab-case",
        description: "Components use kebab-case"
      }
    }
  }
});
// → Validates against your specific rules

6. context

Build optimal AI context packs for LLM tools (Claude Code, Codex, Cursor) by intelligently selecting and ranking files based on task relevance:

React projects:

{
  "task": "Add authentication with JWT tokens and refresh logic",
  "path": "/path/to/react-project",
  "tokens": 50000,
  "include": ["files", "arch", "deps", "tests"],
  "focus": ["src/auth", "src/hooks"],
  "history": false,
  "format": "md",
  "lineNums": true,
  "strategy": "rel"
}

Nuxt 3 projects:

{
  "task": "Add user profile management with Pinia store",
  "path": "/path/to/nuxt-project",
  "tokens": 50000,
  "include": ["files", "arch", "deps", "tests"],
  "focus": ["composables", "stores", "server"],
  "history": false,
  "format": "md",
  "lineNums": true,
  "strategy": "rel"
}

Core Features:

• Intelligent Task Analysis: Parses task description to extract:

  • Task type (feature/bug/refactor/investigation/documentation)
  • Keywords and domain concepts (auth, login, payment, etc.)
  • Framework concepts (hooks, composables, stores, etc.)
  • Explicitly mentioned files/paths

• Smart File Relevance Scoring:

  • 100 points: Explicitly mentioned files (e.g., "fix src/auth.ts")
  • 50 points: Files in focus areas
  • 20-30 points: Domain concept matches (auth, payment, user)
  • 10-20 points: Keyword matches in file path/content
  • 15 points: Test files for bug-related tasks
  • Files sorted by relevance score descending

• Token Budget Management:

  • Relevance strategy (default): 60% primary files, 15% dependencies, 10% architecture, 10% tests, 5% types
  • Breadth strategy: More files with less detail (50% primary, 20% dependencies, 15% architecture)
  • Depth strategy: Fewer files with full context (70% primary, 15% dependencies, 5% architecture)
  • Intelligent content truncation when files exceed budget (keeps first 60% and last 20%)

• Architectural Context: Optional high-level project overview including:

  • Framework type and structure
  • State management pattern
  • Navigation approach
  • Component/hook/composable counts

• Dependency Traversal: Automatically includes files imported by relevant files

  • Resolves relative imports
  • Limits to top 10 dependencies to avoid explosion
  • Respects token budget for dependencies

• Multiple Output Formats:

  • Markdown (default): Best for Claude Code, with syntax highlighting and line numbers
  • JSON: Structured data for programmatic consumption
  • XML: Alternative structured format

Example Output:

{
  "task": "Add authentication with JWT tokens",
  "taskAnalysis": {
    "type": "feature",
    "keywords": ["authentication", "tokens", "login"],
    "domainConcepts": ["auth", "login", "user"],
    "frameworkConcepts": ["hook", "component", "service"],
    "actionVerbs": ["add", "implement"],
    "mentionedFiles": []
  },
  "strategy": "relevance",
  "tokenBudget": {
    "max": 50000,
    "used": 42500,
    "remaining": 7500,
    "breakdown": {
      "architecture": 5000,
      "relevantFiles": 30000,
      "dependencies": 5000,
      "tests": 2000,
      "types": 500
    }
  },
  "architecture": {
    "framework": "react",
    "structure": "modular",
    "stateManagement": "context",
    "navigation": "stack",
    "overview": "react project with 4 layers, 45 components, 12 hooks"
  },
  "files": [
    {
      "path": "src/hooks/useAuth.ts",
      "relevanceScore": 85.5,
      "reasons": [
        "Path contains domain concept: auth",
        "Content contains \"authentication\" (5 times)",
        "Path contains framework concept: hook"
      ],
      "content": "import { useState, useEffect } from 'react';\n...",
      "lineNumbers": true,
      "truncated": false,
      "tokenCount": 450,
      "category": "primary"
    },
    {
      "path": "src/services/auth-service.ts",
      "relevanceScore": 72.0,
      "reasons": [
        "Path contains domain concept: auth",
        "Content contains \"jwt\" (3 times)",
        "Path contains framework concept: service"
      ],
      "content": "export class AuthService {\n...",
      "lineNumbers": true,
      "truncated": false,
      "tokenCount": 680,
      "category": "primary"
    },
    {
      "path": "src/types/auth.ts",
      "relevanceScore": 45.0,
      "reasons": ["Dependency of src/hooks/useAuth.ts"],
      "content": "export interface User {...}",
      "lineNumbers": true,
      "truncated": false,
      "tokenCount": 120,
      "category": "dependency"
    }
  ],
  "relatedTests": ["src/hooks/__tests__/useAuth.test.ts"],
  "conventions": [
    "Custom hooks use 'use' prefix",
    "Services in services/ directory"
  ],
  "patterns": ["React Hooks", "Context API", "Async/Await"],
  "suggestions": [
    "✅ Found 5 highly relevant files - great starting point!",
    "💡 Review similar components/hooks to follow existing patterns",
    "💡 Consider adding tests for your new feature"
  ],
  "formattedOutput": "# Context Pack: Add authentication with JWT tokens\n\n...",
  "metadata": {
    "totalFilesAnalyzed": 120,
    "filesIncluded": 8,
    "avgRelevanceScore": 62.3,
    "generatedAt": "2025-10-09T12:30:45.123Z"
  }
}

Optimization Strategies:

1. Relevance (default - best for focused work):

   • Prioritizes most relevant files
   • Includes essential dependencies
   • Minimal architectural context
   • Best for: Feature development, bug fixes

2. Breadth (survey mode):

   • More files with abbreviated content
   • Wider coverage of codebase
   • More architectural context
   • Best for: Investigation, understanding unfamiliar code

3. Depth (deep dive):

   • Fewer files with complete content
   • Full dependency chains
   • Minimal truncation
   • Best for: Complex refactoring, deep debugging

Use Cases:

1. Feature Development: "Add payment processing with Stripe"

   • Finds existing payment-related code
   • Includes API service patterns
   • Suggests similar implementations to follow

2. Bug Investigation: "Fix login redirect loop on mobile"

   • Prioritizes navigation/auth files
   • Includes related test files
   • Shows error handling patterns

3. Code Refactoring: "Extract dashboard logic into composables"

   • Finds dashboard components
   • Shows existing composable patterns
   • Includes dependent files

4. API Integration: "Integrate new GraphQL endpoint for user profiles"

   • Finds existing API client code
   • Shows GraphQL query patterns
   • Includes type definitions

7. security

Perform comprehensive security vulnerability analysis with OWASP Top 10 mapping, framework-aware detection, and positive security pattern recognition:

{
  "path": "/path/to/project",
  "inc": ["src/**/*.{ts,tsx,js,jsx,vue}"],
  "exc": ["**/node_modules/**", "**/*.test.*"],
  "sev": ["critical", "high"],      // Filter by severity
  "cats": ["injection", "crypto"],  // Filter by category
  "fw": "expo",                     // Override framework detection
  "pos": true,                      // Include positive patterns (default: true)
  "report": false,                  // Generate markdown report
  "page": 1,                        // Pagination
  "pageSize": 50                    // Results per page
}

Core Features:

• OWASP Top 10 2021 Mapping: Each vulnerability mapped to specific OWASP category
• Severity Levels: Critical, High, Medium, Low, Info
• Framework-Aware Detection: Specialized checks for React, React Native/Expo, Vue/Nuxt, Fastify
• Positive Pattern Recognition: Identifies good security practices already in place
• Security Score: 0-100 score based on vulnerability findings
• Actionable Recommendations: Prioritized remediation guidance

Vulnerability Categories:

| Category | OWASP | Description | |----------|-------|-------------| | injection | A03:2021 | SQL, XSS, Command, NoSQL, Template injection | | crypto | A02:2021 | Hardcoded secrets, weak crypto, insecure storage | | access_control | A01:2021 | CORS misconfiguration, missing auth, IDOR, open redirects | | misconfiguration | A05:2021 | Debug mode, verbose errors, insecure cookies | | data_exposure | A02:2021 | Sensitive data in state/props, server secrets leaked | | mobile | Mobile-Specific | Insecure storage, missing cert pinning, deep links | | react | Framework-Specific | dangerouslySetInnerHTML, URL injection, CSRF, Next.js leaks | | vue_nuxt | Framework-Specific | v-html XSS, exposed runtime config, SSR issues | | fastify_backend | Framework-Specific | Missing validation, rate limiting, auth hooks | | dependencies | A06:2021 | Vulnerable npm packages via OSV database |

Detection Examples:

Injection Vulnerabilities (A03):

// SQL Injection - detected
db.query(`SELECT * FROM users WHERE id = ${userId}`);

// Safe - parameterized query recognized as positive pattern
db.query('SELECT * FROM users WHERE id = $1', [userId]);

Cryptographic Failures (A02):

// Hardcoded secrets - detected
const API_KEY = 'sk-1234567890abcdef';
const JWT_SECRET = 'mysecretkey';

// Weak crypto - detected
const hash = crypto.createHash('md5').update(password).digest('hex');
const id = Math.random().toString(36);

Access Control Issues (A01):

// CORS wildcard - detected
app.use(cors({ origin: '*' }));

// Insecure cookies - detected
res.cookie('session', token, { httpOnly: false, secure: false });

Mobile-Specific (React Native/Expo):

// Insecure token storage - detected
await AsyncStorage.setItem('authToken', token);

// Safe - positive pattern recognized
await SecureStore.setItemAsync('authToken', token);

React Web Specific:

// XSS via dangerouslySetInnerHTML - detected
<div dangerouslySetInnerHTML={{ __html: userContent }} />

// Safe - sanitized content recognized as positive pattern
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />

// Open redirect vulnerability - detected
const returnUrl = searchParams.get('redirect');
window.location.href = returnUrl;  // Unvalidated redirect

// URL injection in href - detected
<a href={userProvidedUrl}>Click here</a>  // Could be javascript:

// Sensitive data in React state - detected
const [password, setPassword] = useState('');  // Visible in DevTools

// Next.js server secrets leaked to client - detected
export async function getServerSideProps() {
  return { props: { apiKey: process.env.SECRET_KEY } };  // Sent to browser!
}

Vue/Nuxt Specific:

// XSS vulnerability - detected
<div v-html="userContent"></div>

// Exposed secrets - detected
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiKey: 'secret-key'  // Should be in private
    }
  }
});

Fastify Backend Specific:

// Route without validation - detected
fastify.post('/api/users', async (req) => {
  return db.insert(req.body);  // No schema validation
});

// Safe - validation recognized
fastify.post('/api/users', {
  schema: { body: UserSchema }
}, handler);

Dependency Vulnerabilities (A06):

Scans npm dependencies using the OSV (Open Source Vulnerabilities) database - similar to Dependabot but accessible via MCP:

// Scan only dependencies
security({ path: "/project", cats: ["dependencies"] });

// Example vulnerability finding:
{
  "id": "DEP-001",
  "category": "dependencies",
  "owasp": "A06:2021-Vulnerable and Outdated Components",
  "severity": "high",
  "title": "[email protected]: Prototype Pollution",
  "cve": "CVE-2021-23337",
  "ghsa": "GHSA-35jh-r3h4-6jhm",
  "remediation": "Upgrade lodash to version 4.17.21 or later"
}

// Positive patterns detected:
// - Package lockfile (package-lock.json)
// - Node.js engine constraints
// - Dependabot/Renovate configurations
// - npm overrides for forced upgrades

How it compares to Dependabot:

The approach is conceptually similar but uses a different (though overlapping) data source:

• Dependabot uses GitHub's Advisory Database directly, integrated into the GitHub platform
• This implementation uses the OSV (Open Source Vulnerabilities) database via the public OSV.dev API

OSV aggregates multiple vulnerability databases including:

• GitHub Security Advisories (GHSA)
• National Vulnerability Database (NVD)
• npm Registry Advisories
• Python PyPA advisories
• And other ecosystem-specific sources

The core approach is the same:

1. Parse package.json and package-lock.json to get exact dependency versions
2. Query the vulnerability database with package name + version
3. Return matches with CVE/GHSA IDs, severity, and remediation info

Why OSV?

• Provides a free, public API with no authentication required
• Aggregates multiple sources (including the same data Dependabot uses)
• Supports batch queries for efficiency
• Maintained by Google and the open source community

Example Output:

{
  "projectPath": "/path/to/project",
  "framework": "expo",
  "analyzedAt": "2025-01-12T15:30:00.000Z",
  "severitySummary": {
    "critical": 2,
    "high": 5,
    "medium": 8,
    "low": 3,
    "info": 1,
    "total": 19
  },
  "categorySummary": {
    "injection": 4,
    "crypto": 6,
    "access_control": 3,
    "misconfiguration": 2,
    "mobile": 4,
    "vue_nuxt": 0,
    "fastify_backend": 0,
    "data_exposure": 0,
    "dependencies": 0
  },
  "statusSummary": {
    "needs_fix": 12,
    "review": 5,
    "acceptable": 2
  },
  "vulnerabilities": [
    {
      "id": "CRYPTO-001",
      "category": "crypto",
      "owasp": "A02:2021-Cryptographic Failures",
      "severity": "critical",
      "status": "needs_fix",
      "title": "Hardcoded API Key",
      "description": "API key found in source code: OPENAI_API_KEY",
      "location": {
        "file": "src/services/api.ts",
        "line": 15,
        "codeSnippet": "const OPENAI_API_KEY = 'sk-..."
      },
      "risk": "API key exposed in source code can be extracted and abused",
      "remediation": "Move to environment variable: process.env.OPENAI_API_KEY",
      "cweId": "CWE-798",
      "confidence": 0.95,
      "autoFixable": false,
      "references": ["https://owasp.org/Top10/A02_2021-Cryptographic_Failures/"]
    },
    {
      "id": "MOBILE-001",
      "category": "mobile",
      "owasp": "Mobile-Specific",
      "severity": "high",
      "status": "needs_fix",
      "title": "Insecure Token Storage",
      "description": "Auth token stored in AsyncStorage which is not encrypted",
      "location": {
        "file": "src/utils/auth.ts",
        "line": 42
      },
      "risk": "Tokens in AsyncStorage can be extracted from device backups",
      "remediation": "Use expo-secure-store or react-native-keychain for sensitive data",
      "cweId": "CWE-312",
      "confidence": 0.9,
      "framework": "expo",
      "autoFixable": false
    }
  ],
  "positivePatterns": [
    {
      "id": "POS-001",
      "category": "injection",
      "title": "Input Validation Library",
      "description": "Uses Zod for runtime input validation",
      "location": { "file": "src/schemas/user.ts" },
      "benefit": "Prevents injection attacks through validated input"
    },
    {
      "id": "POS-002",
      "category": "crypto",
      "title": "Secure Password Hashing",
      "description": "Uses bcrypt for password hashing",
      "location": { "file": "src/services/auth.ts" },
      "benefit": "Protects passwords with industry-standard hashing"
    },
    {
      "id": "POS-003",
      "category": "mobile",
      "title": "Secure Token Storage",
      "description": "Uses expo-secure-store for sensitive data",
      "location": { "file": "src/utils/secure-storage.ts" },
      "benefit": "Encrypts sensitive data in device keychain"
    }
  ],
  "metrics": {
    "filesAnalyzed": 85,
    "securityScore": 72,
    "riskLevel": "moderate",
    "analysisTime": 1250
  },
  "recommendations": [
    {
      "priority": 1,
      "title": "Remove Hardcoded Secrets",
      "description": "Found 2 critical hardcoded secrets. Move to environment variables immediately.",
      "category": "crypto",
      "affectedFiles": ["src/services/api.ts", "src/config/keys.ts"]
    },
    {
      "priority": 2,
      "title": "Migrate to Secure Storage",
      "description": "Found 3 instances of AsyncStorage for sensitive data. Use SecureStore instead.",
      "category": "mobile",
      "affectedFiles": ["src/utils/auth.ts", "src/hooks/useAuth.ts"]
    },
    {
      "priority": 3,
      "title": "Add Input Validation",
      "description": "5 routes lack input validation. Add schema validation to prevent injection.",
      "category": "injection",
      "affectedFiles": ["src/api/users.ts", "src/api/orders.ts"]
    }
  ],
  "metadata": {
    "page": 1,
    "pageSize": 50,
    "totalVulnerabilities": 19,
    "hasMore": false
  }
}

Security Score Calculation:

Score = 100 - (critical × 15) - (high × 8) - (medium × 3) - (low × 1)
Score = max(0, min(100, Score))

Risk Levels:
- 90-100: Low risk (excellent security posture)
- 70-89: Moderate risk (some improvements needed)
- 50-69: High risk (significant vulnerabilities)
- 0-49: Critical risk (immediate action required)

Use Cases:

1. Pre-Deployment Security Audit:

   security({ path: "/app", sev: ["critical", "high"] });
   // Focus on blocking issues before release

2. Mobile App Security Review:

   security({ path: "/mobile-app", fw: "expo", cats: ["mobile", "crypto"] });
   // Focus on mobile-specific and credential issues

3. API Security Assessment:

   security({ path: "/api", cats: ["injection", "access_control"] });
   // Focus on backend security concerns

4. Security Posture Overview:

   security({ path: "/project", pos: true });
   // Get full picture including positive patterns

5. CI/CD Integration:

   security({ path: ".", sev: ["critical"] });
   // Fail pipeline on critical vulnerabilities

6. Dependency Vulnerability Scan (like Dependabot):

   security({ path: "/project", cats: ["dependencies"] });
   // Check npm packages against OSV vulnerability database
   // Returns CVE/GHSA IDs, severity, and upgrade recommendations

Positive Patterns Detected:

The tool also recognizes good security practices:

| Pattern | Library/Practice | Benefit | |---------|-----------------|---------| | Input Validation | Zod, Yup, Joi | Prevents injection attacks | | Parameterized Queries | pg, mysql2, Prisma | Prevents SQL injection | | Password Hashing | bcrypt, argon2 | Secure credential storage | | Security Headers | Helmet | Protects against common attacks | | Rate Limiting | express-rate-limit | Prevents abuse | | Secure Storage | SecureStore, Keychain | Encrypted credential storage | | HTTPS Enforcement | redirect middleware | Encrypted transport | | CORS Configuration | Specific origins | Controlled cross-origin access | | Package Lockfile | package-lock.json | Reproducible builds, version pinning | | Engine Constraints | engines field | Prevents unsupported Node.js versions | | Dependency Automation | Dependabot, Renovate | Automatic security updates |

Example: Detailed Metrics Output

When you use includeDetailedMetrics: true in the architecture analysis, you'll receive per-file metrics like this:

{
  "metrics": {
    "totalFiles": 45,
    "totalLines": 5234,
    "avgComplexity": 12.5,
    "maxComplexity": 87,
    "detailedMetrics": [
      {
        "path": "src/components/Dashboard.tsx",
        "lines": 324,
        "complexity": 87,
        "exports": ["Dashboard", "useDashboardData"],
        "imports": 15,
        "patterns": {
          "isReact": true,
          "isVue": false,
          "hasHooks": true,
          "hasComposables": false
        }
      },
      {
        "path": "src/utils/api-client.ts",
        "lines": 156,
        "complexity": 45,
        "exports": ["fetchData", "postData", "ApiClient"],
        "imports": 8,
        "patterns": {
          "isReact": false,
          "isVue": false,
          "hasHooks": false,
          "hasComposables": false
        }
      }
    ]
  }
}

Key Benefits:

• Identify complexity hotspots: Files are sorted by complexity (highest first)
• Guide refactoring: Target files with high complexity for improvement
• Track technical debt: Monitor complexity trends over time
• Better code reviews: Focus on files with highest complexity scores

Common Use Cases

1. Find High Complexity Files for Refactoring

Ask Claude Code: "Find the most complex files in my project that need refactoring"

Optimized approach (filters at source, reduces response size):

arch({
  path: "/path/to/project",
  details: true,
  minCx: 15,     // Only files with complexity >= 15
  maxFiles: 20   // Top 20 most complex files
});

Previous approach (returns all files, larger response):

arch({
  path: "/path/to/project",
  details: true
  // Claude then filters the results manually
});

Example workflow:

1. Identify files with cyclomatic complexity > 50
2. Break down complex funct