codigest 0.3.2__tar.gz → 0.3.5__tar.gz

codigest-0.3.5/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: codigest
+Version: 0.3.5
+Summary: Human-Centered Codebase Context Manager for LLMs
+Project-URL: Homepage, https://github.com/SJB777/codigest
+Project-URL: Repository, https://github.com/SJB777/codigest
+Project-URL: Issues, https://github.com/SJB777/codigest/issues
+Author-email: Codigest Team <sngd024@google.com>
+License: MIT
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Requires-Dist: loguru
+Requires-Dist: pathspec
+Requires-Dist: pyperclip
+Requires-Dist: rich
+Requires-Dist: tomli-w
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# Codigest
+
+**Codigest** is a standalone CLI tool designed to extract, structure, and track the context of your codebase for Large Language Models (LLMs).
+
+Unlike simple copy-paste tools, Codigest employs a **Context Anchor** system (Shadow Git) to track changes locally without polluting your main version control history. It also features **Semantic Analysis** to detect structural changes in your code.
+
+> **Note:** You can use the short alias **`cdg`** instead of `codigest` for faster typing.
+
+## Core Philosophy
+
+* **Read-Only & Safe**: Codigest never modifies your source code. It only reads, analyzes, and formats context.
+* **Context-Aware**: Instead of dumping raw text, it structures code into XML snapshots designed for LLM comprehension.
+* **Session-Based Tracking**: It maintains an internal anchor to track "work-in-progress" changes independently of your Git commits.
+* **Environment Isolated**: Runs in its own isolated Python 3.14 environment via `uv`, ensuring it never conflicts with your project's dependencies.
+
+## Installation
+
+Codigest runs as a global tool. You don't need to add it to your project's `requirements.txt`.
+We strongly recommend using **uv** for the best experience.
+
+### Step 1: Install `uv`
+
+If you don't have `uv` installed, use **Winget** (Windows) or curl (macOS/Linux).
+
+```powershell
+# Windows (via Winget)
+winget install --id astral-sh.uv
+
+# macOS/Linux
+curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
+
+```
+
+### Step 2: Install `codigest`
+
+Install Codigest globally. `uv` will automatically manage the required Python 3.14 environment for you.
+
+```bash
+uv tool install codigest
+```
+
+### Step 3: Update Path (Important!)
+
+To run `codigest` (or `cdg`) from any terminal, ensure your tools directory is in your PATH.
+
+```bash
+uv tool update-shell
+```
+
+*> **Note:** Restart your terminal (or VS Code) after this step to apply changes.*
+
+---
+
+## Workflow & Commands
+
+Once installed, use the **`cdg`** command anywhere.
+
+### 1. Initialization
+
+Sets up the `.codigest` directory and captures the initial baseline anchor.
+
+```bash
+cdg init
+```
+
+### 2. Full Context Snapshot (`scan`)
+
+Scans the codebase and generates a structured XML snapshot. Includes a **Pre-flight Check** to prevent accidental token overflow.
+
+* **Output:** `.codigest/snapshot.xml`
+* **Features:**
+* **Smart Confirmation:** Automatically skips confirmation for small contexts, but warns you for large ones (>30k tokens).
+* **Dependency Resolution (`-r`):** Automatically finds and includes local files imported by your target files.
+* **Scope Control:** You can specify folders or files to scan.
+
+
+
+```bash
+# Basic scan (Interactive confirmation if large)
+cdg scan
+
+# Scan specific folder with dependency resolution (Smart Context)
+cdg scan src/main.py -r
+
+# Force execution without confirmation (Good for CI/CD)
+cdg scan -y --message "Automated snapshot"
+```
+
+### 3. Incremental Changes (`diff`)
+
+Tracks text-based changes between the last `scan` and the current working tree.
+
+* **Output:** `.codigest/changes.diff`
+* **Use Case:** "I modified 3 files. Here is exactly what changed since the last snapshot."
+* **Note:** Checks against the internal Shadow Git, enabling tracking without committing to the real Git.
+
+```bash
+cdg diff
+```
+
+### 4. Semantic Analysis (`semdiff`)
+
+Analyzes **structural changes** (AST-based) rather than line-by-line text differences.
+
+* **Output:** `.codigest/semdiff.xml`
+* **Use Case:** "I refactored the API. Show me added/removed functions or signature changes."
+* **Benefit:** Reduces token usage by ignoring formatting/comment changes.
+
+```bash
+cdg semdiff
+```
+
+### 5. Project Tree (`tree`)
+
+Visualizes the project structure. Respects `.gitignore`.
+
+* **Style:** Professional, cleaner output without emojis for better readability.
+* **Use Case:** Quickly verifying which files are being tracked.
+
+```bash
+cdg tree
+```
+
+### 6. Architecture Digest (`digest`)
+
+Generates a high-level outline of the project structure (Classes, Functions, Methods only).
+
+* **Output:** `.codigest/digest.xml`
+* **Use Case:** "Don't read the implementation details. Just understand the class hierarchy."
+
+```bash
+cdg digest
+```
+
+---
+
+## Configuration
+
+You can customize behavior in `.codigest/config.toml`.
+
+```toml
+[filter]
+# Target extensions
+extensions = [".py", ".ts", ".rs", ".md", ".json"]
+
+# Exclude patterns (Gitignore syntax)
+exclude_patterns = [
+    "*.lock",
+    "tests/data/",
+    "legacy_code/"
+]
+
+[output]
+format = "xml"
+```
+
+## Architecture Details
+
+**Context Anchor (Shadow Git)**
+Codigest maintains a hidden, lightweight Git repository inside `.codigest/anchor/.shadow_git`.
+
+* It is renamed to `.shadow_git` to prevent VS Code and other IDEs from confusing it with your project's actual repository.
+* When you run `scan`, the current state is committed to this anchor.
+* When you run `diff`, the tool compares your working directory against this anchor.
+
+**Safety Mechanisms**
+
+* **Pre-flight Check:** Calculates estimated token count before processing to prevent context overflow errors.
+* **Structure-Aware Dedent:** Ensures XML tags are perfectly aligned (flush-left) to prevent indentation artifacts in LLM prompts.
+* **XML Injection Protection:** Automatically escapes content within XML tags.
+
+## License
+
+MIT License

codigest-0.3.5/README.md

@@ -0,0 +1,174 @@
+# Codigest
+
+**Codigest** is a standalone CLI tool designed to extract, structure, and track the context of your codebase for Large Language Models (LLMs).
+
+Unlike simple copy-paste tools, Codigest employs a **Context Anchor** system (Shadow Git) to track changes locally without polluting your main version control history. It also features **Semantic Analysis** to detect structural changes in your code.
+
+> **Note:** You can use the short alias **`cdg`** instead of `codigest` for faster typing.
+
+## Core Philosophy
+
+* **Read-Only & Safe**: Codigest never modifies your source code. It only reads, analyzes, and formats context.
+* **Context-Aware**: Instead of dumping raw text, it structures code into XML snapshots designed for LLM comprehension.
+* **Session-Based Tracking**: It maintains an internal anchor to track "work-in-progress" changes independently of your Git commits.
+* **Environment Isolated**: Runs in its own isolated Python 3.14 environment via `uv`, ensuring it never conflicts with your project's dependencies.
+
+## Installation
+
+Codigest runs as a global tool. You don't need to add it to your project's `requirements.txt`.
+We strongly recommend using **uv** for the best experience.
+
+### Step 1: Install `uv`
+
+If you don't have `uv` installed, use **Winget** (Windows) or curl (macOS/Linux).
+
+```powershell
+# Windows (via Winget)
+winget install --id astral-sh.uv
+
+# macOS/Linux
+curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
+
+```
+
+### Step 2: Install `codigest`
+
+Install Codigest globally. `uv` will automatically manage the required Python 3.14 environment for you.
+
+```bash
+uv tool install codigest
+```
+
+### Step 3: Update Path (Important!)
+
+To run `codigest` (or `cdg`) from any terminal, ensure your tools directory is in your PATH.
+
+```bash
+uv tool update-shell
+```
+
+*> **Note:** Restart your terminal (or VS Code) after this step to apply changes.*
+
+---
+
+## Workflow & Commands
+
+Once installed, use the **`cdg`** command anywhere.
+
+### 1. Initialization
+
+Sets up the `.codigest` directory and captures the initial baseline anchor.
+
+```bash
+cdg init
+```
+
+### 2. Full Context Snapshot (`scan`)
+
+Scans the codebase and generates a structured XML snapshot. Includes a **Pre-flight Check** to prevent accidental token overflow.
+
+* **Output:** `.codigest/snapshot.xml`
+* **Features:**
+* **Smart Confirmation:** Automatically skips confirmation for small contexts, but warns you for large ones (>30k tokens).
+* **Dependency Resolution (`-r`):** Automatically finds and includes local files imported by your target files.
+* **Scope Control:** You can specify folders or files to scan.
+
+
+
+```bash
+# Basic scan (Interactive confirmation if large)
+cdg scan
+
+# Scan specific folder with dependency resolution (Smart Context)
+cdg scan src/main.py -r
+
+# Force execution without confirmation (Good for CI/CD)
+cdg scan -y --message "Automated snapshot"
+```
+
+### 3. Incremental Changes (`diff`)
+
+Tracks text-based changes between the last `scan` and the current working tree.
+
+* **Output:** `.codigest/changes.diff`
+* **Use Case:** "I modified 3 files. Here is exactly what changed since the last snapshot."
+* **Note:** Checks against the internal Shadow Git, enabling tracking without committing to the real Git.
+
+```bash
+cdg diff
+```
+
+### 4. Semantic Analysis (`semdiff`)
+
+Analyzes **structural changes** (AST-based) rather than line-by-line text differences.
+
+* **Output:** `.codigest/semdiff.xml`
+* **Use Case:** "I refactored the API. Show me added/removed functions or signature changes."
+* **Benefit:** Reduces token usage by ignoring formatting/comment changes.
+
+```bash
+cdg semdiff
+```
+
+### 5. Project Tree (`tree`)
+
+Visualizes the project structure. Respects `.gitignore`.
+
+* **Style:** Professional, cleaner output without emojis for better readability.
+* **Use Case:** Quickly verifying which files are being tracked.
+
+```bash
+cdg tree
+```
+
+### 6. Architecture Digest (`digest`)
+
+Generates a high-level outline of the project structure (Classes, Functions, Methods only).
+
+* **Output:** `.codigest/digest.xml`
+* **Use Case:** "Don't read the implementation details. Just understand the class hierarchy."
+
+```bash
+cdg digest
+```
+
+---
+
+## Configuration
+
+You can customize behavior in `.codigest/config.toml`.
+
+```toml
+[filter]
+# Target extensions
+extensions = [".py", ".ts", ".rs", ".md", ".json"]
+
+# Exclude patterns (Gitignore syntax)
+exclude_patterns = [
+    "*.lock",
+    "tests/data/",
+    "legacy_code/"
+]
+
+[output]
+format = "xml"
+```
+
+## Architecture Details
+
+**Context Anchor (Shadow Git)**
+Codigest maintains a hidden, lightweight Git repository inside `.codigest/anchor/.shadow_git`.
+
+* It is renamed to `.shadow_git` to prevent VS Code and other IDEs from confusing it with your project's actual repository.
+* When you run `scan`, the current state is committed to this anchor.
+* When you run `diff`, the tool compares your working directory against this anchor.
+
+**Safety Mechanisms**
+
+* **Pre-flight Check:** Calculates estimated token count before processing to prevent context overflow errors.
+* **Structure-Aware Dedent:** Ensures XML tags are perfectly aligned (flush-left) to prevent indentation artifacts in LLM prompts.
+* **XML Injection Protection:** Automatically escapes content within XML tags.
+
+## License
+
+MIT License

{codigest-0.3.2 → codigest-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codigest"
-version = "0.3.2"
+version = "0.3.5"
 description = "Human-Centered Codebase Context Manager for LLMs"
 authors = [{name = "Codigest Team", email = "sngd024@google.com"}]
 readme = "README.md"
@@ -32,6 +32,7 @@ Issues = "https://github.com/SJB777/codigest/issues"
 
 [project.scripts]
 codigest = "codigest.main:app"
+cdg = "codigest.main:app"
 
 [build-system]
 requires = ["hatchling"]

{codigest-0.3.2 → codigest-0.3.5}/src/codigest/commands/diff.py

@@ -4,15 +4,13 @@ from pathlib import Path
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
-from ..core import scanner, prompts, shadow
-from .scan import _load_config_filters 
+from ..core import prompts, shadow, tags, common
 
 app = typer.Typer()
 console = Console()
 
 @app.callback(invoke_without_command=True)
 def handle(
-    # target 인자 추가
     target: Path = typer.Argument(
         Path.cwd(), 
         help="Target directory to check diff",
@@ -24,24 +22,29 @@ def handle(
     copy: bool = typer.Option(True, help="Auto-copy to clipboard"),
     save: bool = typer.Option(True, help="Save to .codigest/changes.diff"),
     message: str = typer.Option("", "--message", "-m", help="Add specific instruction context"),
+    # [추가] resolve 옵션
+    resolve: bool = typer.Option(False, "-r", "--resolve", help="Recursively resolve imports"),
 ):
     """
     [Context Update] Shows changes since the last 'codigest scan'.
     Useful for updating LLM context without re-uploading everything.
     """
-    root_path = target
-    anchor = shadow.ContextAnchor(root_path)
+    # [1] Context Setup
+    ctx = common.get_context(target)
+    root_path = ctx.root_path
     
-    # 1. Check Baseline Existence
+    anchor = shadow.ContextAnchor(root_path)
+
+    # Check Baseline
     last_update = anchor.get_last_update_time()
     if last_update == "Never":
         console.print("[yellow]⚠️  No scan history found.[/yellow]")
-        console.print("   Run [bold cyan]codigest scan[/bold cyan] first to establish a baseline.")
+        console.print("   Run [bold cyan]cdg scan[/bold cyan] first to establish a baseline.")
         raise typer.Exit(1)
 
     console.print(f"[dim]Checking changes since last scan ({last_update})...[/dim]")
 
-    # 2. Calculate Diff
+    # [2] Calculate Diff via Context
     with Progress(
         SpinnerColumn(),
         TextColumn("[bold blue]Analyzing changes...[/bold blue]"),
@@ -49,23 +52,20 @@ def handle(
         console=console
     ) as progress:
         task = progress.add_task("diff", total=None)
-        
-        # Load same filters as scan
-        extensions, extra_ignores = _load_config_filters(root_path)
-        
-        # Get current valid files (Working Tree)
-        current_files = scanner.scan_project(root_path, extensions, extra_ignores)
-        
+
+        # ★ Use common context to get files (handles config & resolve)
+        current_files = ctx.get_target_files(resolve_deps=resolve)
+
         # Compare Working Tree vs Anchor
         diff_content = anchor.get_changes(current_files)
-        
+
         progress.update(task, completed=100)
 
     if not diff_content.strip():
-        console.print("[green]✨ No changes detected since last scan.[/green]")
+        console.print("[green]No changes detected since last scan.[/green]")
         return
 
-    # 3. Render
+    # [3] Render
     prompt_engine = prompts.get_engine(root_path)
     try:
         formatted_diff = prompt_engine.render(
@@ -76,18 +76,19 @@ def handle(
             instruction=message
         )
     except Exception:
-        # Fallback if template fails
-        formatted_diff = f"<diff>\n{diff_content}\n</diff>"
+        # Fallback if template fails (using safe escaping via tags)
+        safe_content = tags.escape_xml_value(diff_content)
+        formatted_diff = f"<diff>\n{safe_content}\n</diff>"
 
-    # 4. Output
-    console.print(f"[bold green]✔ Changes Detected![/bold green] ({len(formatted_diff)} chars)")
+    # [4] Output
+    console.print(f"[bold green]Changes Detected![/bold green] ({len(formatted_diff)} chars)")
     
     if copy:
         pyperclip.copy(formatted_diff)
-        console.print("[dim]📋 Copied to clipboard[/dim]")
+        console.print("[dim]Clipboard copied[/dim]")
 
     if save:
         out_path = root_path / ".codigest" / "changes.diff"
         out_path.parent.mkdir(exist_ok=True)
         out_path.write_text(formatted_diff, encoding="utf-8")
-        console.print(f"[dim]💾 Saved to {out_path}[/dim]")
+        console.print(f"[dim]Saved to {out_path}[/dim]")

{codigest-0.3.2 → codigest-0.3.5}/src/codigest/commands/digest.py

@@ -4,10 +4,7 @@ from pathlib import Path
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
-from ..core import scanner, structure, prompts, semdiff, tags, tokenizer
-
-# Reuse config loader
-from .scan import _load_config_filters 
+from ..core import structure, prompts, semdiff, tags, tokenizer, common
 
 app = typer.Typer()
 console = Console()
@@ -18,14 +15,17 @@ def handle(
     copy: bool = typer.Option(True, help="Auto-copy to clipboard"),
     save: bool = typer.Option(True, help="Save to .codigest/digest.xml"),
     message: str = typer.Option("", "--message", "-m", help="Add specific instruction"),
+    # [추가]
+    resolve: bool = typer.Option(False, "-r", "--resolve", help="Recursively resolve imports"),
 ):
     """
     [Architectural View] Summarizes the codebase structure (Classes/Functions only).
     """
-    root_path = target.resolve()
+    # [1] Context Setup
+    ctx = common.get_context(target)
+    root_path = ctx.root_path
     
     prompt_engine = prompts.get_engine(root_path)
-    extensions, extra_ignores = _load_config_filters(root_path)
 
     with Progress(
         SpinnerColumn(),
@@ -36,19 +36,24 @@ def handle(
         
         task = progress.add_task("digest", total=None)
         
-        files = scanner.scan_project(root_path, extensions, extra_ignores)
+        # [2] File Discovery via Context
+        files = ctx.get_target_files(ignore_config=False, resolve_deps=resolve)
+        
         tree_str = structure.generate_ascii_tree(files, root_path)
 
         summary_blocks = []
         for file_path in files:
-            # Only summarize Python files via AST
             if file_path.suffix in (".py", ".pyi"):
                 try:
                     content = file_path.read_text(encoding="utf-8")
                     summary = semdiff.summarize(content)
                     
                     if summary:
-                        rel_path = file_path.relative_to(root_path).as_posix()
+                        try:
+                            rel_path = file_path.relative_to(root_path).as_posix()
+                        except ValueError:
+                            rel_path = f"[EXTERNAL]/{file_path.name}"
+
                         block = tags.file(rel_path, summary)
                         summary_blocks.append(block)
                 except Exception:
@@ -71,7 +76,7 @@ def handle(
         progress.update(task, completed=100)
 
     token_count = tokenizer.estimate_tokens(digest_content)
-    console.print(f"[bold green]✔ Digest Generated![/bold green] ([bold cyan]~{token_count:,} Tokens[/bold cyan])")
+    console.print(f"[bold green]Digest Generated![/bold green] ([bold cyan]~{token_count:,} Tokens[/bold cyan])")
     
     if copy:
         pyperclip.copy(digest_content)
@@ -81,4 +86,4 @@ def handle(
         out_path = root_path / ".codigest" / "digest.xml"
         out_path.parent.mkdir(exist_ok=True)
         out_path.write_text(digest_content, encoding="utf-8")
-        console.print(f"[dim]💾 Saved to {out_path}[/dim]")
+        console.print(f"[dim]💾 Saved to {out_path}[/dim]")