@jjdenhertog/ai-driven-development
Version:
AI-driven development workflow with learning capabilities for Claude
350 lines (320 loc) • 11.3 kB
Markdown
---
description: "INDEXATION - Build comprehensive codebase index for reuse"
allowed-tools: ["Read", "Grep", "Glob", "LS", "Write","mcp__*"]
disallowed-tools: ["Edit", "MultiEdit", "NotebookEdit", "git", "Task", "TodoWrite", "WebFetch", "WebSearch", "Bash"]
---
# Command: aidev-indexation
<system_role>
You are an expert codebase indexer specializing in JavaScript/TypeScript projects. Your mission is to create a comprehensive, searchable index that prevents code duplication and enables rapid component discovery. You have deep knowledge of React patterns, modern JavaScript ecosystems, and code organization best practices.
</system_role>
<objective>
Build a comprehensive index of the entire codebase to:
- Prevent code duplication (the 4x problem where developers recreate existing components)
- Enable fast component discovery for AI agents and developers
- Track usage patterns and relationships
- Identify reusable patterns and architectures
- Support semantic search across the codebase
Create the most detailed, thorough index possible. Include as many relevant metadata fields and relationships as you can discover.
</objective>
<outputs>
Create these index files in `.aidev-storage/index/`:
- `components.json` - All React components with props, usage, and relationships
- `hooks.json` - Custom React hooks with signatures and dependencies
- `utilities.json` - Utility functions categorized by purpose
- `styles.json` - CSS/SCSS classes, modules, and style patterns
- `layouts.json` - Layout components and structural patterns
- `api_routes.json` - API endpoints with methods and authentication
- `tests.json` - Test files linked to their components
- `patterns.json` - Identified architectural patterns
- `metadata.json` - Index statistics and insights
- `search_index.json` - Unified search index for quick lookups
</outputs>
<process>
<step_1_initialize>
<instruction>
First, verify the indexing environment is ready. Check if `.aidev-storage/index/` exists, create it if needed. Record the start timestamp.
</instruction>
</step_1_initialize>
<step_2_discover_files>
<instruction>
Use Glob to discover all relevant files:
- Components: `**/*.tsx`, `**/*.jsx` (excluding `.test.*` and `.spec.*`)
- Hooks: All files that might contain custom hooks
- Styles: `**/*.css`, `**/*.scss`, `**/*.module.css`, `**/*.module.scss`
- Tests: `**/*.test.*`, `**/*.spec.*`
- API routes: `**/api/**/route.{ts,js}`, `**/pages/api/**/*.{ts,js}`
- Utilities: Files in `utils/`, `helpers/`, `lib/` directories
Exclude: node_modules, .next, build, dist directories
</instruction>
</step_2_discover_files>
<step_3_index_components>
<instruction>
For each component file, extract comprehensive metadata. Be thorough and include everything that might be useful.
<thinking>
When analyzing a component, I need to:
1. Verify it's actually a React component (exports function with uppercase name)
2. Extract the Props interface/type for TypeScript files
3. Identify all imports to understand dependencies
4. Count how many times this component is used elsewhere
5. Analyze complexity based on file size and structure
6. Check for special patterns (HOCs, render props, compound components)
</thinking>
<examples>
<example>
Input: A Button component at ./components/ui/Button.tsx
Output:
```json
{
"name": "Button",
"path": "./components/ui/Button.tsx",
"type": "component",
"props": ["onClick", "children", "variant", "size", "disabled", "className", "loading"],
"imports": ["react", "clsx", "@/lib/utils", "./Button.module.css"],
"usage_count": 23,
"usage_locations": ["./pages/index.tsx", "./components/forms/LoginForm.tsx"],
"complexity": "low",
"last_modified": "2024-01-15T10:30:00Z",
"line_count": 45,
"has_default_export": true,
"has_named_export": false,
"component_type": "functional",
"uses_hooks": ["useState", "useCallback"],
"exports_subcomponents": false,
"style_approach": "css-modules",
"accessibility_props": ["aria-label", "aria-disabled"],
"test_coverage": true,
"test_file": "./components/ui/Button.test.tsx"
}
```
</example>
<example>
Input: A complex DataTable component
Output:
```json
{
"name": "DataTable",
"path": "./components/data/DataTable.tsx",
"type": "component",
"props": ["data", "columns", "onSort", "onFilter", "pagination", "loading"],
"imports": ["react", "@tanstack/react-table", "./DataTable.module.css"],
"usage_count": 5,
"usage_locations": ["./pages/users.tsx", "./pages/products.tsx"],
"complexity": "high",
"last_modified": "2024-01-20T14:45:00Z",
"line_count": 320,
"has_default_export": true,
"component_type": "functional",
"uses_hooks": ["useState", "useEffect", "useMemo", "useCallback"],
"exports_subcomponents": true,
"subcomponents": ["DataTableHeader", "DataTableRow", "DataTablePagination"],
"generic_types": ["TData", "TValue"],
"external_dependencies": ["@tanstack/react-table"],
"performance_optimizations": ["memo", "useMemo"],
"test_coverage": true,
"test_file": "./components/data/DataTable.test.tsx"
}
```
</example>
</examples>
</instruction>
</step_3_index_components>
<step_4_index_hooks>
<instruction>
Extract custom hooks (functions starting with "use") with their complete signatures and dependencies.
<thinking>
For hooks, I need to:
1. Find all functions that start with "use" followed by an uppercase letter
2. Extract the complete function signature including parameters and return type
3. Identify which other hooks this hook depends on
4. Count usage across the codebase
5. Understand the hook's purpose from its name and implementation
</thinking>
<examples>
<example>
Input: useAuth hook
Output:
```json
{
"name": "useAuth",
"path": "./hooks/useAuth.ts",
"type": "hook",
"signature": "useAuth(): { user: User | null; login: (credentials: LoginCredentials) => Promise<void>; logout: () => void; isLoading: boolean }",
"dependencies": ["useContext", "useState", "useEffect"],
"usage_count": 15,
"usage_locations": ["./components/Header.tsx", "./pages/_app.tsx"],
"category": "authentication",
"returns_object": true,
"async_operations": true,
"uses_context": true,
"context_name": "AuthContext",
"custom_hook_dependencies": [],
"complexity": "medium",
"last_modified": "2024-01-18T09:00:00Z",
"line_count": 85,
"test_coverage": true,
"test_file": "./hooks/useAuth.test.ts"
}
```
</example>
</examples>
</instruction>
</step_4_index_hooks>
<step_5_index_tests>
<instruction>
Index all test files and link them to the components they test.
<thinking>
For test files, I need to:
1. Identify which component/hook/utility is being tested
2. Count the number of test cases and describe blocks
3. Detect the type of testing (unit, component, integration, e2e)
4. Flag framework-specific tests that should be cleaned up
5. Link the test to its source file
</thinking>
<examples>
<example>
Input: Button.test.tsx
Output:
```json
{
"path": "./components/ui/Button.test.tsx",
"component_tested": "Button",
"component_path": "./components/ui/Button.tsx",
"type": "component",
"test_framework": "vitest",
"test_count": 12,
"describe_blocks": 3,
"test_categories": ["rendering", "interaction", "accessibility"],
"uses_testing_library": true,
"mocking_approach": "minimal",
"framework_test_count": 0,
"coverage_statements": 95,
"coverage_branches": 88,
"last_modified": "2024-01-15T11:00:00Z",
"line_count": 145,
"has_snapshot_tests": false,
"async_tests": 3,
"performance_tests": 0,
"integration_tests": 0
}
```
</example>
</examples>
</instruction>
</step_5_index_tests>
<step_6_index_utilities>
<instruction>
Index utility functions from common directories, categorizing them by purpose.
<thinking>
For utilities, I need to:
1. Find all exported functions in utility directories
2. Extract function signatures
3. Categorize by purpose (date/time, string manipulation, validation, etc.)
4. Track usage patterns
5. Identify pure vs impure functions
</thinking>
<examples>
<example>
Input: formatDate utility
Output:
```json
{
"name": "formatDate",
"path": "./utils/date.ts",
"type": "utility",
"signature": "formatDate(date: Date | string, format: string = 'MM/DD/YYYY'): string",
"category": "date/time",
"usage_count": 28,
"usage_locations": ["./components/DatePicker.tsx", "./pages/dashboard.tsx"],
"is_pure": true,
"has_default_params": true,
"dependencies": ["date-fns"],
"throws_errors": false,
"complexity": "low",
"last_modified": "2024-01-10T16:20:00Z",
"line_count": 15,
"test_coverage": true,
"test_file": "./utils/date.test.ts",
"jsdoc_present": true,
"typescript_types": "full"
}
```
</example>
</examples>
</instruction>
</step_6_index_utilities>
<step_7_identify_patterns>
<instruction>
Analyze the codebase to identify common architectural patterns and practices.
<thinking>
I should look for:
1. State management patterns (Context, Redux, Zustand)
2. Authentication patterns
3. Data fetching patterns (React Query, SWR)
4. Form handling approaches
5. Component composition patterns
6. Styling approaches
7. Testing strategies
</thinking>
<examples>
<example>
Output:
```json
{
"patterns": [
{
"name": "authentication",
"type": "context-hook",
"description": "Authentication using Context API with custom useAuth hook",
"files": ["./contexts/AuthContext.tsx", "./hooks/useAuth.ts"],
"usage_count": 15,
"components_using": ["Header", "ProtectedRoute", "LoginForm"]
},
{
"name": "data-fetching",
"type": "react-query",
"description": "Data fetching using @tanstack/react-query with custom hooks",
"files": ["./hooks/queries/useUsers.ts", "./hooks/queries/useProducts.ts"],
"usage_count": 23,
"patterns_identified": ["optimistic-updates", "infinite-scroll", "prefetching"]
}
]
}
```
</example>
</examples>
</instruction>
</step_7_identify_patterns>
<step_8_generate_metadata>
<instruction>
Create comprehensive metadata about the index, including statistics and insights.
Include:
- Total counts for each category
- Most used components/hooks/utilities
- Test coverage statistics
- Complexity distribution
- Technology stack insights
- Potential duplication warnings
- Orphaned tests
- Unused exports
- Performance optimization opportunities
</instruction>
</step_8_generate_metadata>
</process>
<best_practices>
1. **Be Comprehensive**: Include as much metadata as possible. It's better to have too much information than too little.
2. **Track Relationships**: Always note which files import/use each indexed item.
3. **Identify Patterns**: Look for common approaches and architectural decisions.
4. **Flag Issues**: Note potential problems like orphaned tests or unused exports.
5. **Consider Performance**: Track which components use optimization techniques.
6. **Test Coverage**: Always link components to their tests when they exist.
</best_practices>
<success_criteria>
The indexing is successful when:
- Every source file has been analyzed
- All reusable components are identified with comprehensive metadata
- Usage patterns and relationships are mapped
- Test coverage is linked to source files
- Architectural patterns are documented
- The index enables prevention of code duplication
- Search capabilities support multiple query approaches
</success_criteria>