Code Index

Intelligent code analysis tool for TypeScript/JavaScript projects

Code Index analyzes codebases and generates structured JSON registries that help developers, LLMs, and CI/CD systems understand code structure. Provides dependency analysis, dead code detection, test coverage analysis, and automated documentation generation.

Installation

npm install -g @apart-tech/code-index

Quick Start

# Analyze your project
code-index analyze --auto

# Search for functions and types
code-index search code-index.json "UserService"

# Find where a symbol is used
code-index find-usage code-index.json "createUser"

# Show codebase statistics
code-index stats code-index.json

# Find dead code
code-index dead-code code-index.json

# Generate documentation
code-index docs code-index.json -o API.md

Commands

analyze - Generate Code Registry

Analyzes TypeScript/JavaScript projects and generates a structured JSON registry.

code-index analyze [options]

Key Options:

• -p, --project <path> - Project directory or feature folder (default: current directory)
• -o, --output <file> - Output file path (default: code-index.json)
• --auto - Auto-detect optimization based on project size
• --compact - Reduce output size by 80-90% (recommended for LLMs)
• --exported-only - Only include exported items (public API)
• --include-implementations - Include function bodies
• --max-definition-length <n> - Truncate long type definitions

Examples:

# Auto-optimize based on project size
code-index analyze --auto

# Analyze specific feature
code-index analyze -p ./src/features/auth --compact -o auth.json

# Public API only
code-index analyze --exported-only -o public-api.json

When to use:

• 🤖 LLM Context: Use --compact --exported-only for minimal token usage
• 📊 Large Projects: Use -p ./specific/feature for feature-based analysis
• 🔍 Documentation: Use --exported-only for public API

deps - Dependency Analysis

Analyzes dependencies and builds a dependency graph.

code-index deps <registry> [options]

Key Options:

• -f, --file <path> - Show dependencies for specific file
• --transitive - Include transitive dependencies
• --depth <number> - Max depth for transitive dependencies (default: 3)
• --stats - Show dependency statistics
• --circular - Detect circular dependencies

Examples:

# Overall statistics
code-index deps code-index.json --stats

# File dependencies
code-index deps code-index.json --file src/api/users.ts

# Find circular dependencies
code-index deps code-index.json --circular

# Transitive dependencies
code-index deps code-index.json --file src/cli.ts --transitive

When to use:

• 🔍 Impact Analysis: Find what breaks when you change a file
• 🔄 Circular Dependencies: Detect and fix circular imports
• 🎯 Refactoring: Understand module relationships

diff - Compare Registries

Compares two code registries and shows differences.

code-index diff <before> <after> [options]

Key Options:

• -o, --output <file> - Output diff to file
• --format <type> - Output format: json, markdown, text (default: text)
• --breaking-only - Only show breaking changes

Examples:

# Compare versions
code-index diff v1.0.json v2.0.json

# Save to file
code-index diff before.json after.json -o diff.json --format json

# Only breaking changes
code-index diff main.json feature.json --breaking-only

When to use:

• 🔄 Code Reviews: Generate diffs for pull requests
• 📊 Release Notes: Track changes between versions
• ⚠️ API Changes: Identify what changed

check-breaking - CI/CD Breaking Change Detection

Checks for breaking changes and exits with code 1 if found (perfect for CI/CD).

code-index check-breaking <before> <after> [options]

Key Options:

• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file

Examples:

# CI/CD: Fail build if breaking changes
code-index check-breaking main.json feature.json

# Generate markdown for PR comment
code-index check-breaking main.json feature.json --format markdown -o breaking.md

Breaking Change Types:

• function_removed - Exported function removed (major)
• function_signature_changed - Function signature modified (major/minor)
• type_removed - Exported type removed (major)
• type_modified - Type definition changed (minor)
• export_removed - Export statement removed (major)

When to use:

• ✅ CI/CD: Prevent accidental breaking changes in PRs
• 📦 Semantic Versioning: Determine version bump type
• 🔒 API Stability: Enforce API contract

dead-code - Dead Code Detection

Identifies unused exports, functions, and potentially dead code.

code-index dead-code <registry> [options]

Key Options:

• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file
• --show-all - Show all categories (even if empty)

Examples:

# Basic analysis
code-index dead-code code-index.json

# Generate report
code-index dead-code code-index.json --format markdown -o dead-code-report.md

What it detects:

• Unused Exports - Exported but never imported
• Isolated Files - Files with exports but no dependents
• Files Without Exports - Files that don't export anything
• Unused Functions - Non-exported functions never called
• Unused Types - Non-exported types never referenced
• Potential Savings - Estimated LOC that could be removed

When to use:

• 🧹 Code Cleanup: Regular cleanup to remove dead code
• 📉 Bundle Size: Reduce bundle size
• 🔍 Refactoring: Safely identify deletable code

coverage - Test Coverage Analysis

Analyzes test coverage by comparing source and test registries.

code-index coverage <source> <tests> [options]

Key Options:

• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file
• --threshold <number> - Minimum coverage % required (exits 1 if below)

Examples:

# Generate indices
code-index analyze -p ./src --exported-only -o src.json
code-index analyze -p ./tests -o tests.json

# Analyze coverage
code-index coverage src.json tests.json

# Enforce threshold in CI/CD
code-index coverage src.json tests.json --threshold 80

What it analyzes:

• Coverage Percentage - Overall % of functions tested
• Untested Functions - Functions without tests
• Suggested Test Files - Where tests should be created
• Orphaned Tests - Test files without corresponding source
• Per-File Coverage - Coverage breakdown by file

When to use:

• ✅ CI/CD: Enforce minimum coverage thresholds
• 📊 Quality Metrics: Track coverage over time
• 🎯 Test Planning: Identify what needs testing

docs - Documentation Generation

Generates markdown documentation from code registry.

code-index docs <registry> [options]

Key Options:

• -o, --output <file> - Output file path (default: API.md)
• --style <type> - Documentation style: api, readme (default: api)
• --title <title> - Documentation title
• --description <desc> - Documentation description
• --include-private - Include non-exported items
• --group-by <type> - Group by: file, type (default: file)
• --no-toc - Disable table of contents

Examples:

# Generate API documentation
code-index docs code-index.json -o API.md

# Generate README
code-index docs code-index.json --style readme -o README.md

# Customize
code-index docs code-index.json \
  --title "My API" \
  --group-by type \
  --include-private

Documentation Styles:

• api - Complete API reference with all details
• readme - Project README with quick start and overview

When to use:

• 📚 API Documentation: Auto-generate always up-to-date docs
• 🔄 CI/CD: Regenerate docs on every commit
• 📖 Developer Onboarding: Provide comprehensive reference

search - Search Code Registry

Search for functions, types, and files in the code registry without grepping files.

code-index search <registry> <query> [options]

Key Options:

• --type <filter> - Filter by: function, type, file, all (default: all)
• --exported-only - Only show exported items
• --case-sensitive - Case-sensitive matching
• --regex - Treat query as regular expression
• --limit <number> - Limit number of results (default: 50)
• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file

Examples:

# Basic search
code-index search code-index.json "analyze"

# Search only functions
code-index search code-index.json "buildGraph" --type function

# Search with regex
code-index search code-index.json ".*Project$" --regex

# Export to markdown
code-index search code-index.json "Registry" --format markdown -o results.md

What it searches:

• Function names and signatures
• Type names and definitions
• File paths
• JSDoc comments
• Parameters and return types

When to use:

• 🔍 Quick Discovery: Find functions/types without grepping
• 📚 Code Exploration: Understand what's available
• 🎯 Targeted Search: Find specific patterns with regex

find-usage - Find Symbol Usage

Find where a specific symbol (function/type) is used throughout the codebase.

code-index find-usage <registry> <symbol> [options]

Key Options:

• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file

Examples:

# Find where a function is used
code-index find-usage code-index.json "buildDependencyGraph"

# Generate markdown report
code-index find-usage code-index.json "analyzeProject" --format markdown -o usage.md

What it shows:

• Symbol definition location
• Files that import the symbol
• Import statements
• Direct usage count
• Indirect impact (files affected transitively)
• Total impact radius

When to use:

• 🔄 Refactoring: Assess impact before changing a function
• 🎯 Impact Analysis: See what breaks when you modify code
• 📊 Usage Patterns: Understand how APIs are used

stats - Codebase Statistics

Show comprehensive statistics and metrics about the codebase.

code-index stats <registry> [options]

Key Options:

• --format <type> - Output format: text, json, markdown (default: text)
• -o, --output <file> - Save output to file
• --detailed - Show detailed breakdowns

Examples:

# Show statistics
code-index stats code-index.json

# Generate detailed markdown report
code-index stats code-index.json --detailed --format markdown -o stats.md

Metrics provided:

• Overview: File/function/type/export counts
• Functions: Async %, exported %, avg parameters, complexity indicators
• Types: Interface/type/class/enum breakdown
• Dependencies: Avg per file, max dependencies, circular deps
• Largest Files: Top files by function count
• Most Imported: Files with most dependents
• Complexity Warnings: Functions with many parameters (≥5)

When to use:

• 📊 Health Metrics: Track codebase complexity over time
• 🎯 Technical Debt: Identify complexity hotspots
• 📈 Growth Tracking: Monitor codebase growth
• 🔍 Code Review: Quick overview for new developers

validate - Validate Registry

Validates the structure of a code registry file.

code-index validate <file>

Example:

code-index validate code-index.json

Common Workflows

LLM Context

# Generate minimal context for LLMs
code-index analyze -p ./src/features/auth \
  --compact \
  --exported-only \
  --max-definition-length 150 \
  -o context.json

Pre-Release Check

# Generate baseline
git checkout main
code-index analyze --exported-only -o baseline.json

# Check feature branch
git checkout feature-branch
code-index analyze --exported-only -o feature.json

# Detect breaking changes
code-index check-breaking baseline.json feature.json

Code Cleanup

# Find dead code
code-index analyze --auto -o project.json
code-index dead-code project.json --format markdown -o cleanup.md

Test Coverage

# Analyze coverage
code-index analyze -p ./src --exported-only -o src.json
code-index analyze -p ./tests -o tests.json
code-index coverage src.json tests.json --threshold 80

Output Format

Generated registries are JSON files with this structure:

{
  "metadata": {
    "projectName": "my-app",
    "fileCount": 42,
    "totalFunctions": 156,
    "totalTypes": 89
  },
  "files": {
    "src/users.ts": {
      "functions": {
        "createUser": {
          "signature": "async function createUser(data: UserData): Promise<User>",
          "parameters": [...],
          "returnType": "Promise<User>",
          "isExported": true,
          "line": 15
        }
      },
      "types": {...},
      "exports": [...],
      "imports": {...}
    }
  }
}

Best Practices

For Developers

• Use --auto for automatic optimization
• Use --compact when sharing with LLMs
• Run dead-code quarterly for cleanup
• Use deps --circular to catch circular dependencies

For Large Projects (3000+ files)

• Use feature-based analysis: -p ./src/features/feature-name
• Always use --compact mode
• Focus on public API with --exported-only

For CI/CD

• Use check-breaking to fail builds on breaking changes
• Use coverage --threshold to enforce minimum coverage
• Generate docs automatically on merge

For LLM Integration

• Use --compact --exported-only --max-definition-length 200
• Analyze only relevant features
• Regenerate before each LLM session

License

MIT

Made for developers and LLMs • Documentation • npm