code-visualizer

仓库: rysweet/amplihack
安装量: 92
排名: #8760

安装

npx skills add https://github.com/rysweet/amplihack --skill code-visualizer

Code Visualizer Skill Purpose

Automatically generate and maintain visual code flow diagrams. This skill analyzes Python module structure, detects import relationships, and generates mermaid diagrams. It also monitors for staleness when code changes but diagrams don't.

Philosophy Alignment

This skill embodies amplihack's core philosophy:

Ruthless Simplicity Single responsibility: Visualize code structure - nothing more Minimal dependencies: Uses only Python AST for analysis, delegates diagram syntax to mermaid-diagram-generator No over-engineering: Timestamp-based staleness is simple and "good enough" for 90% of cases Zero-BS Implementation Real analysis: Actually parses Python AST to extract imports - no mock data Honest limitations: Staleness detection is timestamp-based, not semantic (see Limitations section) Working code: All algorithms shown are functional, not pseudocode Modular Design (Bricks & Studs) This skill is one brick: Code analysis and staleness detection Delegates to other bricks: mermaid-diagram-generator for syntax, visualization-architect for complex diagrams Clear studs (public contract): Analyze modules, generate diagrams, check freshness Skill Delegation Architecture code-visualizer (this skill) ├── Responsibilities: │ ├── Python module analysis (AST parsing) │ ├── Import relationship extraction │ ├── Staleness detection (timestamp-based) │ └── Orchestration of diagram generation │ └── Delegates to: ├── mermaid-diagram-generator skill │ ├── Mermaid syntax generation │ ├── Diagram formatting and styling │ └── Markdown embedding │ └── visualization-architect agent ├── Complex multi-level architecture ├── ASCII art alternatives └── Cross-module dependency graphs

Invocation Pattern:

code-visualizer analyzes code structure

modules = analyze_python_modules("src/") relationships = extract_import_relationships(modules)

Then delegates to mermaid-diagram-generator for syntax

Skill(skill="mermaid-diagram-generator")

Provide: Module relationships, diagram type (flowchart/class), styling preferences

Receive: Valid mermaid syntax ready for embedding

For complex architectures, delegates to visualization-architect

Task(subagent_type="visualization-architect", prompt="Create multi-level diagram for...")

When to Use This Skill New Module Creation: Auto-generate architecture diagram for new modules PR Reviews: Show architecture impact of proposed changes Staleness Detection: Check if existing diagrams reflect current code Dependency Analysis: Visualize import relationships Refactoring: Understand module dependencies before changes Quick Start Generate Diagram for Module User: Generate a code flow diagram for the authentication module

Check Diagram Freshness User: Are my architecture diagrams up to date?

Show PR Impact User: What architecture changes does this PR introduce?

Core Capabilities 1. Module Analysis

Analyzes Python files to extract:

Import statements (internal and external) Class definitions and inheritance Function exports (all) Module dependencies 2. Diagram Generation

Creates mermaid diagrams showing:

Module relationships (flowchart) Class hierarchies (class diagram) Data flow between components Dependency graphs 3. Staleness Detection

Compares:

File modification timestamps Git history for changes Diagram content vs actual code structure Missing modules in diagrams Analysis Process Step 1: Discover Modules

Scan target directory for Python modules

modules = glob("*/.py") packages = identify_packages(modules)

Step 2: Extract Relationships

For each module:

Parse import statements Identify local vs external imports Build dependency graph Detect circular dependencies Step 3: Generate Diagram flowchart TD subgraph core["Core Modules"] auth[auth.py] users[users.py] api[api.py] end

subgraph utils["Utilities"]
    helpers[helpers.py]
    validators[validators.py]
end

api --> auth
api --> users
auth --> helpers
users --> validators

Step 4: Check Freshness

Compare diagram timestamps with source files:

Diagram older than sources = STALE Missing modules in diagram = INCOMPLETE Extra modules in diagram = OUTDATED Diagram Types Module Dependency Graph

Best for: Showing import relationships between files

flowchart LR main[main.py] --> auth[auth/] main --> api[api/] auth --> models[models.py] api --> auth

Class Hierarchy

Best for: Showing inheritance and composition

classDiagram class BaseService { +process() } class AuthService { +login() +logout() } BaseService <|-- AuthService

Data Flow

Best for: Showing how data moves through system

flowchart TD Request[HTTP Request] --> Validate{Validate} Validate -->|Valid| Process[Process] Validate -->|Invalid| Error[Return Error] Process --> Response[HTTP Response]

Staleness Detection How It Works Find Diagrams: Locate mermaid diagrams in README.md, ARCHITECTURE.md Extract Modules: Parse diagram for referenced modules Compare: Check if all current modules are represented Report: Generate freshness report Freshness Report Format

Diagram Freshness Report

Status: STALE

Diagrams Checked: 3 Fresh: 1 Stale: 2

Details

| File | Last Updated | Code Changed | Status |

| ------------ | ------------ | ------------ | ------ |

| README.md | 2025-01-01 | 2025-01-15 | STALE |

| docs/ARCH.md | 2025-01-10 | 2025-01-10 | FRESH |

Missing from Diagrams

  • new_module.py (added 2025-01-12)
  • api/v2.py (added 2025-01-14)
  1. Update README.md architecture diagram
  2. Add new_module.py to dependency graph

PR Architecture Impact What It Shows

For a given PR or set of changes:

New modules/files added Changed import relationships Deleted dependencies Modified class hierarchies Impact Diagram flowchart TD subgraph added["New"] style added fill:#90EE90 new_api[api/v2.py] end

subgraph modified["Modified"]
    style modified fill:#FFE4B5
    auth[auth.py]
end

subgraph existing["Unchanged"]
    users[users.py]
    models[models.py]
end

new_api --> auth
auth --> models
users --> models

Integration with Other Skills Mermaid Diagram Generator

This skill uses mermaid-diagram-generator for:

Syntax generation Diagram formatting Embedding in markdown Visualization Architect Agent

Delegates to visualization-architect for:

Complex architecture visualization ASCII art alternatives Multi-level diagrams Usage Examples Example 1: New Module Diagram User: I just created a new payment module. Generate an architecture diagram.

Claude: 1. Analyzes payment/ directory 2. Extracts imports and dependencies 3. Generates mermaid flowchart 4. Suggests where to embed (README.md)

Example 2: Check Staleness User: Are my diagrams up to date?

Claude: 1. Finds all mermaid diagrams in docs 2. Compares with current codebase 3. Reports stale diagrams 4. Lists missing modules 5. Suggests updates

Example 3: PR Impact User: Show architecture impact of this PR

Claude: 1. Gets changed files from PR 2. Identifies new/modified/deleted modules 3. Generates impact diagram 4. Highlights dependency changes

Detection Algorithms Import Analysis

Extract imports from Python file

import ast

def extract_imports(file_path): """Extract import statements from Python file.""" tree = ast.parse(Path(file_path).read_text()) imports = [] for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: imports.append(alias.name) elif isinstance(node, ast.ImportFrom): if node.module: imports.append(node.module) return imports

Staleness Check def check_staleness(diagram_file, source_dir): """Check if diagram is stale compared to source.""" diagram_mtime = Path(diagram_file).stat().st_mtime

for source in Path(source_dir).rglob("*.py"):
    if source.stat().st_mtime > diagram_mtime:
        return True, source  # Stale

return False, None  # Fresh

Best Practices When to Update Diagrams New modules: Add to dependency graph Changed imports: Update relationships Deleted files: Remove from diagrams Architectural changes: Regenerate completely Diagram Placement Diagram Type Recommended Location Module overview README.md Detailed architecture docs/ARCHITECTURE.md Package structure package/README.md API flow api/README.md Naming Conventions

Architecture

flowchart TD
    ...

Success Criteria

A good visualization:

Shows all current modules Reflects actual import relationships Uses appropriate diagram type Placed in discoverable location Includes freshness metadata Clear and not overcrowded Limitations

IMPORTANT: Understand these limitations before relying on this skill:

Staleness Detection Limitations

Timestamp-based, not semantic: Detection compares file modification times, not actual code changes

A file touched but not meaningfully changed will trigger "stale" Reformatting code triggers false positives Git operations that update mtime trigger false positives

Cannot detect logic changes: Adding a function that doesn't change imports won't be detected

Internal refactoring within a module is invisible Changes to function signatures not reflected New class methods added without import changes won't show

Import-centric view: Only tracks import relationships

Runtime dependencies (dependency injection) not detected Configuration-based connections invisible Duck typing relationships not captured Scope Limitations

Python-only: Currently only analyzes Python files

No TypeScript, JavaScript, Rust, Go support Multi-language projects partially covered

Static analysis only: No runtime information

Dynamic imports (import, importlib) not detected Conditional imports may be missed Plugin architectures not fully represented

Single-project scope: Cannot analyze cross-repository dependencies

External package internals not shown Monorepo relationships require manual configuration Accuracy Expectations Scenario Accuracy Notes New module detection 95%+ Reliable for Python modules Import relationship mapping 90%+ Misses dynamic imports Staleness detection 70-80% False positives common Circular dependency detection 85%+ May miss complex cycles Class hierarchy extraction 85%+ Mixins can be tricky When NOT to Use This Skill Security-critical dependency audits: Use proper security scanning tools Runtime dependency analysis: Use profilers or dynamic analysis tools Cross-language projects: Manual analysis may be more accurate Heavily dynamic codebases: Plugin architectures, metaprogramming Dependencies

This skill requires:

mermaid-diagram-generator skill: Must be available for diagram syntax generation Python 3.8+: For AST parsing features used Git (optional): For enhanced staleness detection using git history

If mermaid-diagram-generator is unavailable, this skill will provide raw relationship data but cannot generate embedded diagrams.

PR Review Integration How Diagrams Appear in PRs

When reviewing PRs, this skill generates impact diagrams that can be added to PR descriptions:

PR Description Template:

Architecture Impact

Changed Dependencies

flowchart LR
    subgraph changed["Modified Modules"]
        style changed fill:#FFE4B5
        auth[auth/service.py]
        api[api/routes.py]
    end

    subgraph added["New Modules"]
        style added fill:#90EE90
        oauth[auth/oauth.py]
    end

    subgraph unchanged["Existing"]
        models[models/user.py]
        db[db/connection.py]
    end

    oauth --> auth
    auth --> models
    api --> auth
    api --> db

Impact Summary

  • New modules: 1 (oauth.py)
  • Modified modules: 2 (auth/service.py, api/routes.py)
  • New dependencies: oauth.py -> auth/service.py
  • Diagrams to update: README.md (STALE)

CI Integration Example

Add to .github/workflows/pr-review.yml:

  • name: Check Diagram Staleness run: | # Claude Code analyzes and reports # Outputs: STALE diagrams that need updating # Generates: Suggested diagram updates

Reviewer Workflow PR opened -> code-visualizer generates impact diagram Reviewer sees -> Visual diff of architecture changes Staleness check -> Warns if existing diagrams need updates Action items -> Lists diagrams requiring manual update Remember

This skill automates what developers often forget:

Keeping diagrams in sync with code Documenting architecture changes Understanding dependency impacts

The goal is diagrams that stay fresh automatically.

But remember the limitations: Staleness detection is approximate. When accuracy matters, verify manually.

← 返回排行榜