projext 0.1.0

Generate a project map from a directory.

🧩 projext: Project-to-Text Mapper

A versatile CLI tool that scans your project directories and generates a comprehensive "map" of your codebase.

---

English README (Click to expand)

projext is a versatile CLI tool that scans your project directories and generates a comprehensive "map" of your codebase in various formats. It's designed to help you quickly understand project structures, analyze code components, and create context for Large Language Models (LLMs).

Features

• Dual Output Modes: Generate a map with the full content of files (full mode) or a structured summary of Python files using AST (ast mode).
• Directory Tree Generation: Output a classic directory tree structure, similar to the tree command.
• Flexible Configuration: Fine-tune what to include/exclude with options for file extensions, size limits, exclusion patterns, and per-file mode overrides.
• Multiple Formats: Output the project map as Markdown for human readability or JSON for machine processing (e.g., RAG pipelines).
• AST Analysis: In ast mode, projext extracts key information from Python files, including classes, functions (with type hints and docstrings), and imports.

Installation

pip install projext

Usage

projext has two main commands: map and tree.

projext map <path> [options]

Scans a directory and generates a detailed map of file contents.

Arguments

• <path> (Required): The root directory of the project you want to scan.

Options

Option	Description	Default
--ext	A comma-separated list of file extensions to include in the scan.	.py,.json,.md
--out	The name of the output file.	project_tree.md
--format	The output format. Can be md (Markdown) or json.	md
--max-file-size	The maximum size for a single file to be included. (e.g., 1MB, 500K).	1MB
--mode	The default processing mode: full (file content) or ast (Python code summary).	full
--full	A file or directory path to force full mode on, overriding the default. Can be used multiple times.	N/A
--ast	A file or directory path to force ast mode on for Python files, overriding the default. Can be used multiple times.	N/A
--exclude	A glob pattern to exclude files or directories. Can be used multiple times.	N/A

projext tree <path> [options]

Generates a classic directory tree structure.

Arguments

• <path> (Required): The root directory to create a tree from.

Options

Option	Description	Default
--out	The name of the output file.	project_tree.txt
--exclude	A glob pattern to exclude files or directories. Can be used multiple times.	N/A

Use Cases & Examples

1. Basic Project Overview (AST Mode)

Generate a structural summary of a Python project. This is useful for quickly understanding the architecture.

projext map ./my-python-app --mode ast --out ast_summary.md

2. Full Content Map

Create a complete map of a project with the full content of all specified files.

projext map ./my-project --ext .py,.md --out overview.md

3. Directory Tree

Generate a simple, clean directory tree, excluding node_modules and .git by default.

projext tree . --out tree.txt

4. Hybrid Mode for Mixed Analysis

Use full mode as the default, but specifically request an AST summary for a complex part of the application.

projext map ./my-project --mode full --ast ./my-project/core/

5. Excluding Files and Directories

Generate a map while excluding test files and temporary directories.

projext map . --exclude "tests/*" --exclude "temp/"

License

This project is licensed under the MIT License.

日本語 README (クリックして展開)

projext は、プロジェクトディレクトリをスキャンし、コードベースの包括的な「マップ」を様々な形式で生成する、多機能なCLIツールです。プロジェクト構造の迅速な理解、コードコンポーネントの分析、そして大規模言語モデル（LLM）向けのコンテキスト作成を支援します。

✨ 主な機能

• デュアル出力モード: ファイルの全コンテンツを含むマップ（fullモード）または、Pythonファイルの構造化サマリ（astモード）を生成します。
• ディレクトリツリー生成: treeコマンドに似た、クラシックなディレクトリツリー構造を出力します。
• 柔軟な設定: ファイル拡張子、サイズ上限、除外パターン、ファイルごとのモード上書きなど、スキャン対象を細かく調整できます。
• 複数フォーマット対応: 人間が読みやすいMarkdown形式、または機械処理（RAGパイプラインなど）に適したJSON形式でマップを出力します。
• AST解析: astモードでは、クラス、関数（型ヒントやdocstringを含む）、インポート文など、Pythonファイルの重要な情報を抽出します。

📦 インストール

pip install projext

使い方

projext には map と tree の2つの主要なコマンドがあります。

projext map <path> [options]

ディレクトリをスキャンし、ファイルコンテンツの詳細なマップを生成します。

引数

• <path> (必須): スキャンしたいプロジェクトのルートディレクトリ。

オプション

オプション	説明	デフォルト
--ext	スキャンに含めるファイル拡張子をカンマ区切りで指定します。	.py,.json,.md
--out	出力ファイル名。	project_tree.md
--format	出力フォーマット。md (Markdown) または json を指定できます。	md
--max-file-size	スキャンに含める単一ファイルの最大サイズ（例: 1MB, 500K）。	1MB
--mode	デフォルトの処理モード: full (ファイル全体) または ast (Pythonコードの要約)。	full
--full	デフォルトモードを上書きし、fullモードを強制するファイル/ディレクトリ。複数回指定可能。	N/A
--ast	デフォルトモードを上書きし、Pythonファイルにastモードを強制するファイル/ディレクトリ。複数回指定可能。	N/A
--exclude	除外するファイルやディレクトリのglobパターン。複数回指定可能。	N/A

projext tree <path> [options]

クラシックなディレクトリツリー構造を生成します。

引数

• <path> (必須): ツリーを生成するルートディレクトリ。

オプション

オプション	説明	デフォルト
--out	出力ファイル名。	project_tree.txt
--exclude	除外するファイルやディレクトリのglobパターン。複数回指定可能。	N/A

ユースケースと実行例

1. 基本的なプロジェクト概要（ASTモード）

Pythonプロジェクトの構造的なサマリを生成します。アーキテクチャを素早く理解するのに役立ちます。

projext map ./my-python-app --mode ast --out ast_summary.md

2. フルコンテンツ・マップ

指定されたすべてのファイルの全コンテンツを含む完全なマップを作成します。

projext map ./my-project --ext .py,.md --out overview.md

3. ディレクトリツリー

node_modules や .git などをデフォルトで除外した、シンプルでクリーンなディレクトリツリーを生成します。

projext tree . --out tree.txt

4. ハイブリッドモードでの複合分析

デフォルトは full モードを使いつつ、アプリケーションの複雑な部分だけASTサマリをリクエストします。

projext map ./my-project --mode full --ast ./my-project/core/

5. ファイルとディレクトリの除外

テストファイルや一時ディレクトリを除外してマップを生成します。

projext map . --exclude "tests/*" --exclude "temp/"

ライセンス

このプロジェクトはMITライセンスの下で公開されています。