/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 `