CodeMap Visualizer

中文文档

CodeMap Visualizer is a modern, interactive web application designed to render, analyze, and share structured code analysis data. It transforms complex JSON data representing code execution flows and architecture into beautiful, easy-to-understand visual guides.

Built with Angular (Zoneless, Signals), Tailwind CSS, and Mermaid.js.

🚀 Features

• Interactive Architecture Diagrams: Automatically renders high-level architectural graphs using Mermaid.js.
• Step-by-Step Code Traces: Navigate through complex execution flows with detailed explanations and context.
• Rich Text Guides: Renders Markdown-based guides with syntax highlighting for better readability.
• Code Syntax Highlighting: accurate syntax highlighting for code snippets using Highlight.js.
• History Management: Automatically saves your recently viewed maps to local storage for quick access.
• Easy Import/Export:
  • Paste JSON directly.
  • Import .json files or scan folders.
  • Download maps or copy them to the clipboard.
• Dark Mode UI: A polished, developer-friendly dark theme inspired by modern IDEs.

🛠️ Tech Stack

• Framework: Angular v18+ (Standalone Components, Signals, Zoneless Change Detection)
• Styling: Tailwind CSS
• Visualization: Mermaid.js
• Markdown Rendering: Marked.js
• Syntax Highlighting: Highlight.js
• Icons: Heroicons (SVG)

📖 User Guide

1. Importing Data

You can load a CodeMap in three ways:

1. Paste JSON: Click "New Import" and paste your raw JSON string into the text area.
2. Select File: Upload a valid .json file from your computer.
3. Select Folder: Select a folder containing a .json file to automatically find and load it.

2. Navigating the Viewer

Once loaded, the screen is split into two main areas:

• Sidebar (Left): Displays metadata about the generation (timestamp, mode) and a list of available Trace Flows. Click a trace to focus on it.
• Main View (Right):
  • Architecture Diagram: A visual overview of the system components and their relationships.
  • Trace Details: Scroll down to see specific flows. Each trace includes a "Trace Guide" (Markdown explanation), an ASCII flow diagram, and a sequence of "Code Locations" showing the actual source code with context.

3. Managing History

• Click the History button in the top navigation bar to see previously loaded maps.
• Maps are stored locally in your browser.
• You can clear the history at any time.

📄 Data Format (JSON Schema)

To generate your own CodeMaps, your JSON data must follow this structure:

interface CodeMap {
  schemaVersion: number;      // e.g., 2
  title: string;              // Title of the visualization
  description: string;        // Brief summary
  mermaidDiagram: string;     // Mermaid graph definition (e.g., "graph TD; A-->B;")
  metadata: {
    mode: 'FAST' | 'SMART' | 'ENHANCED';
    generationTimestamp: string; // ISO date string
    originalPrompt?: string;
    [key: string]: any;
  };
  traces: Trace[];
}

interface Trace {
  id: string;
  title: string;              // Name of the specific flow
  description: string;        // Summary of what this trace does
  traceGuide: string;         // Markdown content explaining the flow
  traceTextDiagram: string;   // ASCII or simple text representation of the flow
  locations: Location[];      // Ordered list of code snippets
}

interface Location {
  id: string;
  path: string;               // File path (e.g., "src/app.component.ts")
  lineNumber: number;         // Line number of interest
  lineContent: string;        // Actual code content
  title: string;              // Short title for this step
  description: string;        // Explanation of what happens here
}

📦 Development

This project is built as a Zoneless Angular Application.

Key files structure:

• src/main.ts: Application entry point (bootstraps AppComponent).
• src/models/codemap.model.ts: TypeScript interfaces for the data domain.
• src/services/codemap-history.service.ts: Handles LocalStorage persistence.
• src/components/:
  • codemap-viewer: The main layout component.
  • trace-detail: Handles rendering individual traces, markdown, and code highlighting.

External Dependencies

The project loads several heavy libraries via CDN in index.html to keep the bundle size small and leverage caching:

• Tailwind CSS (Script)
• Mermaid.js
• Marked
• Highlight.js

---

Generated by Google Gemini