From 149f87102d92a2dfba0a78ca981490cb52d40d44 Mon Sep 17 00:00:00 2001 From: DucPhamNgoc <108916011+DucPhamNgoc08@users.noreply.github.com> Date: Tue, 11 Nov 2025 03:44:45 +0700 Subject: [PATCH] Revise README for improved clarity and detail Updated README.md to enhance project description, features, and usage instructions. --- README.md | 451 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 298 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 41c2a2d..16c0100 100644 --- a/README.md +++ b/README.md @@ -1,230 +1,375 @@ -# CodeVisualizer + + + +[![Contributors][contributors-shield]][contributors-url] +[![Forks][forks-shield]][forks-url] +[![Stargazers][stars-shield]][stars-url] +[![Issues][issues-shield]][issues-url] +[![MIT License][license-shield]][license-url] +[![VS Code][vscode-shield]][vscode-url] + + +
+
+ + Logo + + +

CodeVisualizer

+ +

+ Real-time interactive flowcharts and dependency visualization for your code +
+ Download Extension + · + Report Bug + · + Request Feature +

+
+ + +
+ Table of Contents +
    +
  1. + About The Project + +
    2. +
  2. + Getting Started + +
    3. +
  3. Usage
    4. +
  4. Supported Languages
    5. +
  5. How It Works
    6. +
  6. Privacy & Security
    7. +
  7. Contributing
    8. +
  8. License
    9. +
  9. Contact
    10. +
+
+ + +## About The Project + +[![CodeVisualizer Demo][product-video]](https://github.com/user-attachments/assets/e74b33ba-a22d-48a4-8f7c-e7edc9077e62) + +CodeVisualizer is a powerful VS Code extension that transforms the way you understand and navigate code. Whether you're diving into a new codebase, debugging complex logic, or documenting your architecture, CodeVisualizer provides instant visual insights through two powerful visualization modes. + +**Why CodeVisualizer?** + +* Understand complex codebases instantly with interactive dependency graphs showing how your modules connect +* Debug and comprehend function logic through beautiful flowcharts that reveal control flow, loops, and decision points +* Save hours of manual diagramming - generate production-ready visualizations in seconds +* Support for 7+ programming languages with intelligent semantic analysis +* Privacy-first design - all code analysis happens locally on your machine + +CodeVisualizer bridges the gap between code and comprehension, making it easier for developers to onboard, debug, and maintain software projects of any size. + +

(back to top)

+ +### Built With + +This extension leverages cutting-edge technologies to deliver fast, accurate code analysis and beautiful visualizations: + +* [![TypeScript][TypeScript]][TypeScript-url] +* [![Node.js][Node.js]][Node-url] +* [![VS Code API][VSCode]][VSCode-url] +* [![Tree-sitter][Tree-sitter]][Tree-sitter-url] +* [![Mermaid][Mermaid]][Mermaid-url] +* [![WebAssembly][WASM]][WASM-url] + +

(back to top)

+ +### Key Features + +> **Note on Language Support:** +> - **Function-Level Flowcharts**: Supports Python, TypeScript/JavaScript, Java, C++, C, Rust, and Go +> - **Codebase Dependency Visualization**: Currently supports TypeScript/JavaScript and Python (more languages coming soon) +> - **AI-Powered Features**: Available only for Function-Level Flowcharts + +#### Function-Level Flowchart Generation -**Real-time interactive flowcharts and dependency visualization for your code** +Transform individual functions into interactive, visual flowcharts to understand control flow, decision points, and execution paths. -CodeVisualizer is a powerful VS Code extension that provides two main visualization capabilities: function-level flowcharts for understanding code control flow, and codebase-level dependency graphs for analyzing project structure and module relationships. +**Capabilities:** +- **Multi-language Support**: Parse and visualize functions across Python, TypeScript/JavaScript, Java, C++, C, Rust, and Go +- **Interactive Visualization**: Click nodes to navigate to code, zoom and pan for detailed exploration +- **Multiple Views**: Sidebar view for quick reference and detachable panel windows for deep analysis +- **Semantic Analysis**: Intelligent understanding of control flow, loops, exceptions, and async operations +- **9 Beautiful Themes**: Choose from Monokai, Catppuccin, GitHub, Solarized, One Dark Pro, Dracula, Material Theme, Nord, or Tokyo Night +- **Auto-refresh**: Automatically update flowcharts as you edit code -![CodeVisualizer](https://img.shields.io/badge/version-1.0.2-blue.svg) -![VS Code](https://img.shields.io/badge/VS%20Code-1.105.0+-green.svg) -![License](https://img.shields.io/badge/license-MIT-orange.svg) +#### Codebase Dependency Visualization +Analyze and visualize your entire codebase structure, revealing module dependencies, file relationships, and project architecture at a glance. +**Capabilities:** +- **Dependency Graph**: Complete visualization of import/require relationships between modules +- **Color-Coded Categories**: Automatic file classification into Core, Report, Config, Tool, and Entry categories +- **VSCode Theme Integration**: Seamless dark/light theme support matching your editor +- **High-Contrast Visualization**: Color-coded edges and strokes for instant comprehension +- **Interactive Navigation**: Zoom, pan, and explore even the largest dependency graphs smoothly +- **Folder Hierarchy**: Smart subgraphs organized by your directory structure +#### AI-Powered Features (Function Flowcharts) -https://github.com/user-attachments/assets/60b544ed-5149-4b79-b187-35325a3c41fe +**Note:** AI features enhance function-level flowcharts only, making complex logic instantly readable. +- **Smart Labels**: AI-generated human-friendly descriptions replace cryptic variable names and expressions +- **Multiple Providers**: Works with OpenAI, Gemini, Groq, Ollama (local), and Anthropic +- **Intelligent Caching**: Minimizes API calls and costs through efficient label caching +- **Customizable Styles**: Choose between concise, explanatory, or technical label formats +- **Multi-language Support**: Generate labels in your preferred language for global teams -https://github.com/user-attachments/assets/b323bbc8-5c1d-4865-aa12-3235706a33fc +

(back to top)

+ +## Getting Started +Get CodeVisualizer up and running in your VS Code environment in just a few clicks. -## Main Features +### Prerequisites -### 1. Function-Level Flowchart Generation +* Visual Studio Code version 1.105.0 or higher +* Active workspace with supported programming languages (Python, TypeScript/JavaScript, Java, C++, C, Rust, or Go) -Transform individual functions into interactive, visual flowcharts to understand control flow, decision points, and execution paths. +### Installation -**Supported Languages:** -- Python -- TypeScript/JavaScript -- Java -- C++ -- C -- Rust -- Go +1. **Install from VS Code Marketplace** + - Open VS Code + - Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (Mac) to open Extensions + - Search for "CodeVisualizer" + - Click **Install** -**Capabilities:** -- **Multi-language Support**: Parse and visualize functions across 7 programming languages -- **Interactive Visualization**: Click nodes to navigate to code, zoom and pan -- **Multiple Views**: Sidebar view and detachable panel windows -- **Semantic Analysis**: Understand control flow, loops, exceptions, and async operations -- **Export Options**: Export flowcharts as PNG, SVG, or PDF (coming soon) +2. **Install from VSIX file** (if applicable) + ```sh + code --install-extension codevisualizer-1.0.2.vsix + ``` -### 2. Codebase Dependency Visualization +3. **Configure AI Features (Optional)** + - Open Settings: `Ctrl+,` (Windows/Linux) or `Cmd+,` (Mac) + - Search for "CodeVisualizer" + - Enable AI labels and add your API key for supported providers + - Or use Ollama for completely local AI processing -Analyze and visualize the entire codebase structure, showing module dependencies, file relationships, and project architecture. +4. **Start Visualizing** + - Right-click any function → "CodeVisualizer: Open flowchart in new window" + - Right-click any folder → "Visualize Codebase Flow" -**Supported Languages:** -- TypeScript/JavaScript (`.js`, `.ts`, `.mjs`, `.cjs`) -- Python (`.py`) +

(back to top)

-**Capabilities:** -- **Dependency Graph**: Visualize import/require relationships between modules -- **Color-Coded Categories**: Automatic classification of files into categories: - - Core: Logic, extract, schema, enrich modules - - Report: Report, transform, graph operations - - Config: Validate, config, CLI, utilities - - Tool: Tools, cache, special interfaces - - Entry: Entry points, common utilities -- **VSCode Theme Integration**: Node backgrounds adapt to your VSCode theme (dark/light) -- **High-Contrast Visualization**: Color-coded edges and strokes for easy identification -- **Interactive Navigation**: Zoom, pan, and explore large dependency graphs -- **Folder Hierarchy**: Subgraphs organized by directory structure + +## Usage -**Usage:** -- Right-click on a folder in the Explorer → "Visualize Codebase Flow" -- Or use Command Palette: "Visualize Codebase Flow" +### Generating Function Flowcharts -### Customization +1. Open any supported source file in VS Code +2. Right-click in the editor +3. Select **"CodeVisualizer: Open flowchart in new window"** + - Alternatively, use Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type "CodeVisualizer" +4. Explore the interactive flowchart: + - Click nodes to jump to corresponding code + - Zoom in/out with mouse wheel + - Pan by clicking and dragging + - Switch themes from the settings icon -- **9 Beautiful Themes**: Monokai, Catppuccin, GitHub, Solarized, One Dark Pro, Dracula, Material Theme, Nord, Tokyo Night -- **Auto-refresh**: Automatically update flowcharts on code changes -- **Performance Optimized**: Efficient parsing with Tree-sitter (WASM) +### Visualizing Codebase Dependencies + +1. In the Explorer sidebar, right-click on any folder containing your source code + - Alternatively, use Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type "Visualize Codebase Flow" +2. Select **"Visualize Codebase Flow"** +3. Explore the dependency graph: + - View color-coded file categories + - Trace import chains between modules + - Identify circular dependencies + - Understand your project architecture at a glance -### AI-Powered Features (Function Flowcharts Only) +### AI-Enhanced Labels (Function Flowcharts) -**Note:** AI features are only available for function-level flowcharts, not for codebase dependency visualization. +1. Enable AI labels in Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type "CodeVisualizer: Enable AI Labels" +2. Configure your preferred LLM provider and API key +3. Generate a flowchart - AI labels will automatically replace technical labels -- **Smart Labels**: AI-generated human-friendly node labels for function flowcharts -- **Multiple Providers**: OpenAI, Gemini, Groq, Ollama (local), Anthropic -- **Intelligent Caching**: Efficient caching to minimize API calls -- **Customizable Style**: Concise, explanatory, or technical label styles -- **Multi-language Support**: Generate labels in your preferred language +

(back to top)

+ + +## Supported Languages + +### Function-Level Flowcharts + +| Language | Status | +|----------|--------| +| Python | Full Support | +| TypeScript/JavaScript | Full Support | +| Java | Full Support | +| C++ | Full Support | +| C | Full Support | +| Rust | Full Support | +| Go | Full Support | + +### Codebase Dependency Visualization -When enabled, AI labels replace technical node labels (like variable names, condition expressions) with more readable descriptions, making flowcharts easier to understand at a glance. +| Language | Status | File Extensions | Import Styles | +|----------|--------|----------------|---------------| +| TypeScript/JavaScript | Full Support | `.js`, `.ts`, `.mjs`, `.cjs` | ES6 imports, CommonJS require | +| Python | Full Support | `.py` | import, from...import | -### Developer Experience +**Planned Support:** Java, C++, C, Rust, Go dependency analysis coming in future releases. -- **Auto-refresh**: Automatically update flowcharts on code changes -- **Performance Optimized**: Efficient parsing with Tree-sitter (WASM) -- **Keyboard Shortcuts**: Quick access to all features +

(back to top)

+ ## How It Works ### Function-Level Flowchart Pipeline -1. **Parsing**: Uses Tree-sitter parsers (compiled to WASM) to parse source code into Abstract Syntax Trees (AST) -2. **Analysis**: Traverses the AST to identify: - - Control flow structures (if/else, switch, loops) - - Function boundaries - - Exception handling - - Async operations - - Data operations (assignments, function calls) -3. **IR Generation**: Converts AST into an Intermediate Representation (IR) with nodes and edges -4. **Visualization**: Generates Mermaid diagram code from IR -5. **Rendering**: Renders interactive flowchart using Mermaid.js in webview +1. **Parsing**: Tree-sitter parsers (compiled to WASM) convert source code into Abstract Syntax Trees (AST) +2. **Analysis**: AST traversal identifies control structures, function boundaries, exception handling, async operations, and data flow +3. **IR Generation**: AST is transformed into an Intermediate Representation (IR) with nodes representing code blocks and edges showing flow +4. **Visualization**: IR is converted to Mermaid diagram syntax +5. **Rendering**: Mermaid.js renders an interactive flowchart in a VS Code webview panel ### Codebase Dependency Analysis Pipeline -1. **File Discovery**: Scans workspace for supported files (TypeScript/JavaScript, Python) -2. **Dependency Extraction**: Parses import/require statements to identify module dependencies +1. **File Discovery**: Scans workspace recursively for supported file types +2. **Dependency Extraction**: Parses import/require statements using language-specific parsers 3. **Path Resolution**: Resolves relative and absolute import paths to actual file locations -4. **Graph Building**: Constructs dependency graph with nodes (files) and edges (dependencies) -5. **Classification**: Categorizes files based on path patterns and naming conventions +4. **Graph Building**: Constructs a directed graph with files as nodes and dependencies as edges +5. **Classification**: Categorizes files based on naming patterns and directory structure 6. **Visualization**: Generates Mermaid flowchart with color-coded nodes and edges -7. **Rendering**: Displays interactive dependency graph with zoom/pan capabilities +7. **Rendering**: Displays an interactive graph with zoom, pan, and navigation features -### AI Label Generation (Function Flowcharts Only) +### AI Label Generation (Function Flowcharts) -**Note:** This feature is only available for function-level flowcharts. Codebase dependency visualization uses file names and paths directly without AI enhancement. - -1. **Extraction**: Extracts node labels from generated Mermaid code for function flowcharts -2. **Caching**: Checks cache for previously generated labels -3. **Translation**: Sends uncached labels to selected LLM provider +1. **Extraction**: Extracts node labels from generated Mermaid code +2. **Caching**: Checks local cache for previously generated labels +3. **Translation**: Sends uncached labels to selected LLM provider with optimized prompts 4. **Replacement**: Replaces technical labels with human-friendly descriptions -5. **Storage**: Caches results for future use +5. **Storage**: Caches results locally to minimize future API calls + +

(back to top)

+ ## Privacy & Security ### Data Handling **Code Analysis:** -- All code parsing happens **locally** on your machine -- No code is sent to external servers for flowchart generation -- AST parsing uses local Tree-sitter WASM parsers +- All code parsing happens **100% locally** on your machine +- No code is ever sent to external servers for flowchart generation +- AST parsing uses local Tree-sitter WASM parsers with zero network requests - Your source code never leaves your computer -**AI Features (Optional):** -- When AI labels are enabled, **only node labels** (not full code) are sent to LLM providers -- API keys are stored securely using VS Code's Secret Storage API -- Caching minimizes API calls and reduces data transmission -- You can use local models (Ollama) for complete privacy -- All AI features are **opt-in** and disabled by default +**AI Features (Optional & Opt-in):** +- When AI labels are enabled, **only node labels** (short text snippets, not full code) are sent to LLM providers +- API keys are stored securely using VS Code's built-in Secret Storage API with encryption +- Smart caching minimizes API calls and reduces data transmission +- Use Ollama for complete privacy with local model processing +- All AI features are **disabled by default** and require explicit user activation ### What Data is Collected? -**None.** CodeVisualizer does not collect, store, or transmit: -- Your source code -- File contents -- Personal information -- Usage statistics -- Telemetry data +**None.** CodeVisualizer does not collect, store, or transmit your data. -**Exception:** Only when AI labels are explicitly enabled, minimal label text is sent to your chosen LLM provider (OpenAI, Gemini, etc.) for translation. This is completely optional and can be disabled at any time. +**Exception:** When AI labels are explicitly enabled by you, minimal label text (e.g., "if x > 0", "return result") is sent to your chosen LLM provider for translation. This is completely optional and can be disabled anytime. -### API Keys +### API Key Security -- API keys are stored using VS Code's secure Secret Storage -- Keys are encrypted and stored locally -- Never transmitted except to the selected LLM provider when making API calls -- You can clear stored keys anytime via settings +- Stored using VS Code's secure Secret Storage (encrypted at rest) +- Never transmitted except to your selected LLM provider during API calls +- Can be cleared instantly via settings +- Not included in any logs or diagnostic reports -## Usage +

(back to top)

-### Generating Function Flowcharts + +## Contributing -1. **Open a file** in your editor -2. **Right-click** → "CodeVisualizer: Open flowchart in new window" - - Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P) +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. -### Visualizing Codebase Dependencies +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". +Don't forget to give the project a star! Thanks again! -1. **Right-click on a folder** in the Explorer panel or use Command Palette: "CodeVisualizer: Visualize Codebase Flow" -2. Select **"Visualize Codebase Flow"** -3. The dependency graph will open in a new panel showing: - - All files in the selected folder and subfolders - - Import/require relationships between modules - - Color-coded file categories - - Interactive zoom and pan controls +1. Fork the Project +2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) +3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the Branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request -## Supported Languages +### Development Setup -### Function-Level Flowcharts +```sh +# Clone the repository +git clone https://github.com/DucPhamNgoc08/CodeVisualizer.git -| Language | Status | -|----------|--------| -| Python | Full Support | -| TypeScript/JavaScript | Full Support | -| Java | Full Support | -| C++ | Full Support | -| C | Full Support | -| Rust | Full Support | -| Go | Full Support | +# Install dependencies +npm install -### Codebase Dependency Visualization +# Open in VS Code +code . -| Language | Status | File Extensions | -|----------|--------|----------------| -| TypeScript/JavaScript | Full Support | `.js`, `.ts`, `.mjs`, `.cjs` | -| Python | Full Support | `.py` | +# Press F5 to launch Extension Development Host +``` -**Note:** Codebase dependency analysis currently supports TypeScript/JavaScript and Python. Support for additional languages (Java, C++, C, Rust, Go) is planned for future releases. +### Top contributors: -## Known Issues + + contrib.rocks image + -- Export functionality is currently in development -- Large files (>10,000 lines) may take longer to parse -- Codebase visualization is limited to TypeScript/JavaScript and Python projects +

(back to top)

-## Contributing + +## License -Contributions are welcome! Please feel free to submit a Pull Request. +Distributed under the MIT License. See `LICENSE.txt` for more information. -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +

(back to top)

-## License + +## Contact -This project is licensed under the MIT License - see the LICENSE file for details. +Duc Pham Ngoc - Ducphamngoc39@gmail.com -## Support +Project Link: [https://github.com/DucPhamNgoc08/CodeVisualizer](https://github.com/DucPhamNgoc08/CodeVisualizer) +Support: - **Issues**: [GitHub Issues](https://github.com/DucPhamNgoc08/CodeVisualizer/issues) -- **Repository**: [GitHub](https://github.com/DucPhamNgoc08/CodeVisualizer) - ---- - -**Made with dedication by Duc Pham Ngoc** +- **Discussions**: [GitHub Discussions](https://github.com/DucPhamNgoc08/CodeVisualizer/discussions) + +

(back to top)

+ + +[contributors-shield]: https://img.shields.io/github/contributors/DucPhamNgoc08/CodeVisualizer.svg?style=for-the-badge +[contributors-url]: https://github.com/DucPhamNgoc08/CodeVisualizer/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/DucPhamNgoc08/CodeVisualizer.svg?style=for-the-badge +[forks-url]: https://github.com/DucPhamNgoc08/CodeVisualizer/network/members +[stars-shield]: https://img.shields.io/github/stars/DucPhamNgoc08/CodeVisualizer.svg?style=for-the-badge +[stars-url]: https://github.com/DucPhamNgoc08/CodeVisualizer/stargazers +[issues-shield]: https://img.shields.io/github/issues/DucPhamNgoc08/CodeVisualizer.svg?style=for-the-badge +[issues-url]: https://github.com/DucPhamNgoc08/CodeVisualizer/issues +[license-shield]: https://img.shields.io/github/license/DucPhamNgoc08/CodeVisualizer.svg?style=for-the-badge +[license-url]: https://github.com/DucPhamNgoc08/CodeVisualizer/blob/master/LICENSE.txt +[vscode-shield]: https://img.shields.io/badge/VS%20Code-1.105.0+-007ACC?style=for-the-badge&logo=visual-studio-code +[vscode-url]: https://code.visualstudio.com/ +[product-screenshot]: images/screenshot.png +[TypeScript]: https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white +[TypeScript-url]: https://www.typescriptlang.org/ +[Node.js]: https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white +[Node-url]: https://nodejs.org/ +[VSCode]: https://img.shields.io/badge/VS%20Code%20API-007ACC?style=for-the-badge&logo=visual-studio-code&logoColor=white +[VSCode-url]: https://code.visualstudio.com/api +[Tree-sitter]: https://img.shields.io/badge/Tree--sitter-3DDC84?style=for-the-badge&logo=tree&logoColor=white +[Tree-sitter-url]: https://tree-sitter.github.io/tree-sitter/ +[Mermaid]: https://img.shields.io/badge/Mermaid-FF3670?style=for-the-badge&logo=mermaid&logoColor=white +[Mermaid-url]: https://mermaid.js.org/ +[WASM]: https://img.shields.io/badge/WebAssembly-654FF0?style=for-the-badge&logo=webassembly&logoColor=white +[WASM-url]: https://webassembly.org/