Code Cartographer

Code Cartographer is a powerful VS Code extension that automatically generates comprehensive documentation of your codebase, optimized for providing context to Large Language Models (LLMs).

Features

• Project Documentation: Generate detailed file structure and content documentation
• Flexible Configuration: Use a dedicated configuration file to control what gets documented
• Intelligent Filtering: Skip binary files, generated code, and large files automatically
• Multiple Output Formats: Choose between JSON, TXT, and CSV outputs
• Interactive Views: Preview generated documentation in a rich interactive view
• Quick Project Analysis: Get a quick overview of your project's structure and file distribution
• Enhanced Debugging: Comprehensive logging to help diagnose issues

Why Use Code Cartographer with LLMs

Code Cartographer was designed with LLM workflows in mind:

• Optimized Context: Generate documentation that fits within LLM context windows
• Better Comprehension: Help LLMs understand your codebase structure and relationships
• Efficient Interaction: Get more accurate code suggestions by providing complete project context
• Focused Documentation: Include only the files and code that matter using flexible configuration

Getting Started

Installation

Install from the VS Code Marketplace or:

1. Press Ctrl+P (or Cmd+P on Mac)
2. Type ext install pi22by7.code-cartographer

Quick Start

1. Right-click on a project folder in the explorer
2. Select "Generate Documentation"
3. Choose your output location
4. View the generated documentation

Using a Configuration File

For more control over what gets documented, create a configuration file:

1. Right-click on a project folder in the explorer
2. Select "Create Config File" to generate a cartographer.config.json file
3. Customize the patterns for included and excluded files
4. Run "Generate Documentation" to use your custom configuration

Configuration

Configuration File

The recommended way to configure Code Cartographer is with a cartographer.config.json file in your project root. This gives you precise control over what gets documented:

{
  "version": "1.0",
  "include": [
    "src/**/*",
    "*.json",
    "*.md"
  ],
  "exclude": [
    "**/*.min.js",
    "**/*.test.ts",
    "node_modules/**",
    ".git/**",
    "dist/**"
  ],
  "maxFileSize": 500000,
  "skipBinaryFiles": true,
  "skipGeneratedFiles": true,
  "customFiles": {
    "large-important-files": {
      "include": ["src/some-important-file.ts"],
      "maxSize": 2000000
    }
  },
  "documentation": {
    "type": "both",
    "format": "json",
    "outputPath": "./documentation.json"
  }
}

You can also configure the extension through the VS Code settings UI:

1. Go to the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac)
2. Type "Code Cartographer: Configure Settings"
3. Use the form interface to adjust your configuration

Configuration Options

Commands

Code Cartographer provides several commands available from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac):

• Generate Documentation: Creates comprehensive documentation for your project
• View Documentation: Opens an existing documentation file in the viewer
• Configure Settings: Opens the configuration UI
• Create Config File: Generates a default configuration file in your project root
• Quick Analyze Project: Provides a fast overview of your project structure
• Show Logs: Opens the extension logs for troubleshooting

Troubleshooting

If you encounter issues with Code Cartographer, here are some steps to try:

1. Enable Debug Mode: Set codeCartographer.debugMode to true in your VS Code settings
2. Check the Logs: Run the "Show Logs" command to view detailed diagnostic information
3. Verify Configuration: Make sure your cartographer.config.json file or VS Code settings have the correct format and values
4. Review Exclusions: If files are missing, check that they aren't being excluded by your configuration

Common problems and solutions:

• No files documented: Check your include/exclude patterns and make sure they match your project structure
• Large files skipped: Increase the maxFileSize value or use customFiles to allow specific large files
• Crashes on large projects: Try documenting smaller parts of your project first, then increase scope

Release Notes

0.3.0 - Enhanced Configuration

• Added support for cartographer.config.json configuration files
• New configuration UI for easy setup
• Improved file filtering with custom file overrides
• Enhanced documentation viewer
• Added debug mode with detailed logging
• Fixed issues with large repositories
• Added quick project analysis feature

0.2.1

• Fixed issue where the extension would generate empty documentation with no files
• Improved directory traversal to better handle large projects
• Enhanced file structure display with proper path tracking
• Made .gitignore parsing more robust (won't fail if file is missing)
• Added better error handling during file processing
• Improved performance by skipping ignored directories early
• Added detailed logging for troubleshooting

0.1.0

• Initial release
• Generate documentation for your codebase in JSON, TXT or CSV format
• Support for file structure and content documentation
• Integration with .gitignore to exclude unwanted files
• Opens the generated document upon clicking 'View Documentation'