Skip to main content

A tool to generate comprehensive Markdown artifacts of directory structures and file contents

Project description

CodeMapper

Pylint TODO logo

Overview

CodeMapper is a powerful Python tool designed to generate comprehensive Markdown (pdf, xml, and json outputs are on the way) representations of codebases. It bridges the gap between human developers and AI systems by providing a clear, structured view of project architectures and their complete contents. Whether you're working with local directories or GitHub repositories, CodeMapper creates a single, navigable document that encapsulates the full structure and content of a project.

This tool is invaluable for rapid codebase comprehension, whether you're a developer onboarding to a new project or an AI system analyzing code structure.

For audio explanations of this project, see:

  • podcasts (Auto-generated by Gemini using NotebookLLM)

Features

  • Dual-Purpose Output: Generates content optimized for both human readers and AI analysis
  • Intelligent Content Parsing:
    • Respects .gitignore rules
    • Handles various file types appropriately
  • Comprehensive Structure Representation:
    • Creates an accurate, hierarchical file tree
    • Generates a smart table of contents for easy navigation
  • Code-Aware Processing:
    • Applies appropriate syntax highlighting for different file types
    • Intelligently handles large or binary files without bloating the output
  • Flexible Input Handling: Works with local directories and GitHub repositories
  • Encoding Detection: Ensures accurate content reading across various file encodings
  • Customizable Ignore Rules: Option to include files normally ignored by .gitignore
  • Efficient Output Management: Organizes generated documents in a '_codemaps' directory

Roadmap

Requirements

  • Python 3.6+
  • pathspec library (for handling .gitignore rules)
  • chardet library (for file encoding detection)

Installation

From PyPI

Install CodeMapper directly from PyPI using pip:

pip install codemapper

From Source

  1. Clone this repository:

    git clone https://github.com/shaneholloman/codemapper.git
    
  2. Navigate to the cloned directory and install the required dependencies:

    cd codemapper
    pip install -r requirements.txt
    

Usage

Run CodeMapper from the command line, providing the path to the directory or GitHub repository URL you want to analyze:

codemapper <path_to_directory_or_github_url> [--include-ignored]

Options

  • <path_to_directory_or_github_url>: The path to the directory or GitHub repository URL to analyze (required)
  • --include-ignored: Include files that are normally ignored by .gitignore (optional)

Output

CodeMapper generates a Markdown file named <directory_name>_codemap.md in the '_codemaps' directory. This file contains:

  1. A comprehensive table of contents for easy navigation
  2. An accurate file tree representation of the directory structure
  3. The contents of each file, formatted with appropriate syntax highlighting
  4. Information about large and binary files (type and size) without their contents

Example usage and output:

codemapper https://github.com/shaneholloman/ansible-role-apache

View example output here

Use Cases

  • Rapidly understand the structure and content of new or unfamiliar projects
  • Generate comprehensive documentation for code-based AI prompts
  • Facilitate thorough code reviews by providing a complete one-page overview
  • Assist AI systems in analyzing and understanding complex codebases
  • Analyze GitHub repositories without manual cloning

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Thanks to the pathspec and chardet libraries for enhancing CodeMapper's functionality.

Version History

For a detailed version history, please refer to the changelog.md.


If you find CodeMapper useful, don't forget to star this repository!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codemapper-3.7.0.tar.gz (13.9 kB view details)

Uploaded Source

Built Distribution

codemapper-3.7.0-py3-none-any.whl (12.4 kB view details)

Uploaded Python 3

File details

Details for the file codemapper-3.7.0.tar.gz.

File metadata

  • Download URL: codemapper-3.7.0.tar.gz
  • Upload date:
  • Size: 13.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for codemapper-3.7.0.tar.gz
Algorithm Hash digest
SHA256 d8e9aa21f08db7e249449ca9af232acd05f619db31f2d47eb0d3ff2f10a0e067
MD5 0ae6fc0dd37c1575ae7674a50d66cb42
BLAKE2b-256 260e2c42a035aeac79d57bbc3587d08740c644740eab4d279e3a558ac08532af

See more details on using hashes here.

Provenance

File details

Details for the file codemapper-3.7.0-py3-none-any.whl.

File metadata

  • Download URL: codemapper-3.7.0-py3-none-any.whl
  • Upload date:
  • Size: 12.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for codemapper-3.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 277dc63787316cd500fd06fc9d008b535311bcaf252dd2f0cc92327cba87e4b8
MD5 eb31443879cbe9212d50a0a2baade1f6
BLAKE2b-256 0926282043f8e7f0977f9b84818a9b25b74c61bdf88adbc1b7d3e3ea55a130e1

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page