codefusion 1.0.0

A powerful, interactive CLI tool to compile source code into a single document for AI analysis, featuring a rich interactive TUI, clipboard integration, and token estimation.

📜 CodeFusion 🚀

Unify your code! A powerful command-line tool to concatenate source code files into a single, well-formatted document, ideal for documentation, code review, or sharing context with AI/LLMs.

CodeFusion intelligently combines multiple source code files while respecting .gitignore rules, custom ignore files, and specified file extensions. It now features parallel processing for enhanced speed, colored CLI output for better readability, and a suite of new developer-centric options.

✨ Key Features

• Interactive TUI: Rich terminal user interface with interactive menus to configure options on the fly (press o at the prompt).
• Clipboard Integration: Automatically copy the compiled code to your clipboard for easy sharing with AI tools.
• Token Estimation: Displays estimated token count for the compiled context, helping you stay within LLM limits.
• Single-File Compilation: Combines multiple source code files into a single, readable document.
• Parallel Processing: Leverages multi-threading to read and process files concurrently, significantly speeding up compilation for large codebases.
• .gitignore Compliance: Fully respects your project's .gitignore file, preventing unwanted files from being included. (Powered by gitignore_parser)
• Custom Ignore Files: Supports custom ignore files (e.g., .codeignore) with .gitignore-style syntax for fine-grained control over file exclusion.
• Smart Exclusions: Automatically excludes .git, venv, node_modules, .vscode, .idea, and now also excludes .gitignore and secret files (e.g., .env, *.pem, *.key) by default.
• Flexible Extension Filtering: Specify desired file extensions (e.g., py js html) or automatically detect them based on the project's files.
• Directory Exclusion: Excludes common directories by default. Customize exclusions further with additional patterns.
• Clean Formatting: Inserts headers and separators between files for enhanced readability.
• Colored CLI Output: Provides visually distinct and readable log messages and progress updates using colorama.
• Progress Bar: Provides real-time feedback during compilation using tqdm.
• Verbose Logging: Offers detailed logging output for debugging and troubleshooting.
• Cross-Platform Compatibility: Works seamlessly on Linux, macOS, and Windows.
• Modern Python Design: Leverages type hints, pathlib, and is designed for Python 3.7+ (tested with 3.12.6) for optimal performance and maintainability.
• Pre-commit Hooks: Integrates with pre-commit hooks for consistent code formatting and quality enforcement.
• Single Pass Efficiency: Processes files in a single pass for improved performance.

🎮 Interactive Mode

CodeFusion now supports an interactive workflow. After scanning your files, you will see a summary and a prompt:

📁 Project (15 files)
...
Estimated Tokens: ~4,200

Actions:
  y : Proceed with compilation
  o : Options (Filters, Output, Clipboard)
  n : Cancel

Press o to enter the Options Menu where you can:

• Change the Output File (or switch to stdout).
• Toggle Copy to Clipboard.
• Filter by Extensions (e.g., only py and js).
• Toggle inclusion of Empty Files.
• Change the Output Template (Default, Markdown, JSON, HTML).
• Update the Ignore File to use.

📦 Installation

1. Install via PyPI (Recommended):

   pip install codefusion
   

🚀 Usage

codefusion [options] [directory]

• [directory] (Optional): The root directory containing the code files. Defaults to the current directory.

Options

Option	Description	Default Value
-o, --output	The output file name/path. If not specified, output will be printed to stdout.	code_compilation.txt
--stdout	Print the compiled code directly to stdout instead of writing to a file.	(Disabled)
--workers	Number of parallel workers to use for file processing. Defaults to the number of CPU cores.	os.cpu_count()
--dry-run	Perform a dry run: list files that would be processed without actually compiling them.	(Disabled)
--include-empty	Include empty files in the compilation. By default, empty files are skipped.	(Disabled)
--min-size	Minimum file size in bytes to include in the compilation. Files smaller than this size will be skipped.	0 (bytes)
-i, --ignore-file	Name of the custom ignore file (uses .gitignore syntax).	.codeignore
-e, --extensions	Space-separated list of file extensions to include (e.g., py js html). If omitted, includes all extensions found after applying ignore rules.	(Auto-detect)
--no-gitignore	Do not use the .gitignore file found in the root directory. (Note: .gitignore file itself is excluded from output by default).	(Use .gitignore)
--exclude	Space-separated list of fnmatch patterns for files/directories to exclude (applied relative to the root directory). Example: "*_test.py" "*/tests/*" "data/*"	(None)
--list-default-exclusions	List the built-in default exclusion patterns and exit. Useful for understanding which files are excluded automatically.	(Don't List)
--include-dirs	Space-separated list of directories to explicitly include in the compilation. Paths are relative to the main directory argument.	(All)
-v, --verbose	Enable verbose DEBUG logging output.	(No verbose output)
--version	Show the program's version number and exit.

Examples

# Compile all files in the current directory (respects .gitignore by default)
codefusion .

# Compile files ignoring .gitignore rules
codefusion . --no-gitignore

# Compile files in a specific directory
codefusion /path/to/your/project

# Specify output file
codefusion -o my_project_code.md /path/to/your/project

# Filter by extensions (e.g., only Python and JavaScript)
codefusion -e py js /path/to/your/project

# Exclude specific patterns (e.g., tests and data)
codefusion --exclude "*_test.py" "*/tests/*" "data/*" .

# Include empty files and set a minimum file size
codefusion . --include-empty --min-size 100

# Output to stdout (useful for piping)
codefusion . --stdout | pbcopy  # Copy to clipboard on Mac

# Dry run to see what files would be included
codefusion . --dry-run

# Use a custom ignore file
codefusion -i .myignore .

# Enable verbose logging for debugging
codefusion -v .

⚙️ Configuration

Custom Ignore File (.codeignore)

Create a .codeignore file in the root directory of your project to specify additional files and directories to exclude. The syntax is the same as .gitignore. This is useful for excluding files that are specific to CodeFusion, but not necessarily to your version control.

Example .codeignore:

# Exclude test files
*_test.py
tests/

# Exclude IDE-specific files
.idea/
.vscode/

# Exclude documentation build output
docs/_build/

Default Exclusions

CodeFusion automatically excludes common directories and files (e.g., .git, venv, node_modules, .vscode, .idea) to avoid including irrelevant content in the output. You can view the complete list using the --list-default-exclusions option.

Caching

CodeFusion uses a cache to speed up binary file detection on subsequent runs. You can manage the cache with:

• --cache-stats: View cache statistics.
• --clear-cache: Clear cache for the current project.
• --no-cache: Run without using the cache.

📝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues to suggest improvements or report bugs.

⚖️ License

license-badge See the LICENSE file for details.

🔗 Links