Codebase Analysis

Codebase Analysis

Extract an Intermediate Representation (IR) from source code to enable cross-language conversion and analysis.

Usage

/codebase-analysis <path> [--language <lang>] [--depth <0-4>] [--output <format>]

Parameters

Process

1. Language Detection

If --language is not specified, detect based on:

• File extension (.py, .rs, .ts, .go, .scala, .roc)
• Shebang line
• Package files (pyproject.toml, Cargo.toml, package.json)

2. Module Discovery

Identify all modules and their relationships:

• Import/export statements
• Module boundaries
• Dependency graph

3. Type Extraction

Extract type definitions and relationships:

• Struct/class/record definitions
• Enum/ADT/union types
• Type aliases and generics
• Trait/interface definitions

4. Function Analysis

Extract function signatures and semantics:

• Parameter types and defaults
• Return types
• Purity annotations (where inferrable)
• Effect annotations (I/O, async, etc.)

5. Semantic Annotation

Infer semantic properties:

• Nullability (Option, nullable, undefined)
• Mutability (const, let, var)
• Error handling patterns (Result, exceptions, error returns)
• Concurrency patterns (async, channels, actors)

6. Gap Detection

Mark concepts that may not convert cleanly:

• Language-specific patterns (ownership, HKT, macros)
• Family-specific idioms (pattern matching, effects)
• Cross-language semantic gaps

Output

IR Layers

The IR is organized into 5 layers of increasing abstraction:

IR Schema

ir:
  version: "1.0"
  source_language: "python"
  source_path: "src/main.py"

  modules:
    - name: "main"
      imports: [...]
      exports: [...]

  types:
    - name: "User"
      kind: "struct"
      properties:
        - name: "id"
          type: "int"
        - name: "name"
          type: "str"

  functions:
    - name: "get_user"
      parameters:
        - name: "id"
          type: "int"
      return_type: "Optional[User]"
      purity: "pure"

  annotations:
    - kind: "PY-003"
      target: "get_user"
      message: "Generator usage detected"
      severity: "medium"

Gap Annotations

Gaps are annotated with:

• kind: Gap identifier (e.g., "PY-RS-001")
• target: What element has the gap
• message: Human-readable description
• severity: critical, high, medium, low, info
• suggestion: Recommended resolution

Examples

Analyze a Python file

/codebase-analysis src/models.py

Analyze a Rust crate with summary

/codebase-analysis ./src --language rust --output summary

Analyze specific depth level

/codebase-analysis lib/ --depth 2  # Control flow only

Reference

• IR Overview
• IR Schema
• Extraction Guide
• Tool Usage
• Language Families
• Python Patterns
• Rust Patterns
• TypeScript Patterns

Related Skills

• codebase-implement-from-ir - Synthesize code from IR
• idiomatic-python - Python-specific idioms
• idiomatic-rust - Rust-specific idioms