Update Code Index

Update Code Index

Regenerates CODE_INDEX.md by scanning the codebase for all functions, classes, hooks, and components. Organizes by capability to prevent semantic duplication.

---

What This Command Does

1. Scans source files - Finds all exported functions, classes, hooks, components
2. Extracts docstrings - Gets descriptions from JSDoc/docstrings
3. Categorizes by capability - Groups by what things DO, not where they live
4. Generates CODE_INDEX.md - Creates/updates the semantic index

---

Phase 1: Detect Project Type

# Check language
ls package.json pyproject.toml 2>/dev/null

# Check source directories
ls -d src/ lib/ app/ 2>/dev/null

---

Phase 2: Scan Codebase

For TypeScript/JavaScript

Scan for exports:

# Find all exported functions
grep -rn "export function\|export const\|export class\|export default" src/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"

# Find React hooks
grep -rn "export function use[A-Z]\|export const use[A-Z]" src/ --include="*.ts" --include="*.tsx"

# Find React components (PascalCase exports)
grep -rn "export function [A-Z]\|export const [A-Z].*=.*=>" src/ --include="*.tsx" --include="*.jsx"

For Python

# Find all function definitions
grep -rn "^def \|^async def \|^class " src/ --include="*.py"

# Check __all__ exports
grep -rn "__all__" src/ --include="*.py"

---

Phase 3: Extract Documentation

For each found export, extract:

1. Name - Function/class name
2. Location - File path and line number
3. Description - From JSDoc @description or first line of docstring
4. Parameters - Function signature
5. Returns - Return type if available

TypeScript Example

/**
 * Formats a date into a human-readable relative string.
 * @param date - The date to format
 * @returns Relative time string like "2 days ago"
 */
export function formatRelative(date: Date): string {

Extract:

• Name: formatRelative
• Description: "Formats a date into a human-readable relative string"
• Params: (date: Date)
• Returns: string

Python Example

def format_relative(date: datetime) -> str:
    """Formats a date into a human-readable relative string.

    Args:
        date: The date to format

    Returns:
        Relative time string like "2 days ago"
    """

Extract:

• Name: format_relative
• Description: "Formats a date into a human-readable relative string"
• Params: (date: datetime)
• Returns: str

---

Phase 4: Categorize by Capability

Group functions by what they DO:

Category	Keywords to Match
Date/Time	date, time, format, parse, duration, relative, timestamp
Validation	validate, is*, check, verify, sanitize
String Operations	string, text, format, parse, slug, truncate, capitalize
API Clients	fetch, get, post, put, delete, api, request
Authentication	auth, login, logout, session, token, user
Error Handling	error, exception, handle, catch, throw
Database	db, query, find, create, update, delete, repository
Hooks (React)	use*
Components (React)	PascalCase in .tsx/.jsx
Utilities	util, helper, common (catch-all)

---

Phase 5: Generate CODE_INDEX.md

Create or overwrite CODE_INDEX.md:

# Code Index

*Auto-generated by /update-code-index*
*Last updated: [TIMESTAMP]*

> ⚠️ **Before writing new code, search this index first!**
> Find similar functionality? Use or extend it instead of creating new.

## Quick Stats

| Category | Count | Main Location |
|----------|-------|---------------|
| Date/Time | X | src/utils/dates.ts |
| Validation | X | src/utils/validate.ts |
| API Clients | X | src/api/*.ts |
| Hooks | X | src/hooks/*.ts |
| Components | X | src/components/*.tsx |

---

## Date/Time Operations

| Function | Location | Description | Signature |
|----------|----------|-------------|-----------|
| `formatDate()` | utils/dates.ts:15 | Formats Date to locale string | `(date: Date, opts?)` |
| `formatRelative()` | utils/dates.ts:32 | Formats as "2 days ago" | `(date: Date)` |
| ... | ... | ... | ... |

---

## Validation

| Function | Location | Description | Signature |
|----------|----------|-------------|-----------|
| `isEmail()` | utils/validate.ts:10 | Validates email format | `(email: string)` |
| ... | ... | ... | ... |

---

[Continue for each category...]

---

Phase 6: Report Changes

After generating, report:

📊 Code Index Updated

Scanned:
• 45 TypeScript files
• 12 React components
• 8 custom hooks
• 156 exported functions

Categories:
• Date/Time: 5 functions
• Validation: 8 functions
• API Clients: 23 functions
• Hooks: 8 hooks
• Components: 12 components
• Utilities: 42 functions

New since last run:
• + fetchOrders() in api/orders.ts
• + useCart() in hooks/useCart.ts
• + OrderCard component in components/OrderCard.tsx

Possible duplicates detected:
• ⚠️ formatDate() and displayDate() - similar purpose?
• ⚠️ isValid() and validate() - review these

Updated: CODE_INDEX.md

---

Handling Missing Documentation

If a function lacks documentation:

| `myFunction()` | utils/helpers.ts:42 | ⚠️ *No description - add JSDoc* | `(a, b, c)` |

Report at end:

⚠️ 12 functions missing documentation:
• myFunction() in utils/helpers.ts:42
• anotherFunc() in services/user.ts:88
• ...

Run with --add-docs to prompt for descriptions.

---

Options

# Basic update
/update-code-index

# Include private/non-exported functions
/update-code-index --include-private

# Prompt to add missing docs
/update-code-index --add-docs

# Only scan specific directory
/update-code-index src/utils

# Output as JSON (for vector DB ingestion)
/update-code-index --json > code_index.json

# Detect duplicates only (no index update)
/update-code-index --audit-only

---

Audit Mode

When run with --audit-only or as /audit-duplicates:

## Duplicate Audit Report - [DATE]

### 🔴 High Confidence Duplicates

1. **formatDate / displayDate / showDate**
   - `formatDate()` at utils/dates.ts:15
   - `displayDate()` at components/Header.tsx:42
   - `showDate()` at pages/Profile.tsx:28
   - Similarity: 89% (same logic, different names)
   - **Recommendation:** Consolidate into utils/dates.ts

2. **isEmail / validateEmail / checkEmail**
   - `isEmail()` at utils/validate.ts:10
   - `validateEmail()` at forms/signup.ts:55
   - `checkEmail()` at api/users.ts:30
   - Similarity: 95% (identical regex)
   - **Recommendation:** Use isEmail() everywhere

### 🟡 Possible Duplicates (Review)

1. **fetchUser / getUser / loadUser**
   - Different implementations but same purpose
   - May be intentional (different contexts)
   - **Action:** Document if intentional, merge if not

### 🟢 Similar But Distinct

1. **Button / IconButton / LinkButton**
   - Related components with different purposes
   - **Status:** OK - documented variants

---

Integration with Vector DB

If vector DB is set up, also update embeddings:

/update-code-index --vector

This:

1. Generates CODE_INDEX.md (as usual)
2. Creates embeddings for each function description
3. Stores in .chroma/ or .lancedb/
4. Enables semantic search: "find functions that validate user input"

---

Suggested Workflow

Daily

• Index auto-updates on significant code changes
• Claude checks index before writing new code

Weekly

• Run /update-code-index --audit-only
• Review duplicate report
• Merge or document similar functions

After Major Features

• Full index regeneration
• Vector DB re-embedding (if used)

---

File Output

Creates/updates:

• CODE_INDEX.md - Human-readable index
• .code-index.json (optional) - Machine-readable for tooling

---

Claude Instructions

When user runs /update-code-index:

1. Detect project type (TS/JS/Python)
2. Scan source directories
3. Extract all exports with documentation
4. Categorize by capability
5. Generate CODE_INDEX.md
6. Report stats and potential duplicates
7. Commit the updated index

After running, remind user:

"Index updated! I'll check this before writing any new code to avoid duplicating existing functionality."