contexta-ai 2.0.0__py3-none-any.whl

contexta_ai-2.0.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: contexta-ai
+Version: 2.0.0
+Summary: AI-native codebase context engine. Scans projects and serves intelligent context packs to Claude Code, Cursor, Windsurf, and any MCP-compatible tool.
+Project-URL: Homepage, https://github.com/pablokaua03/contexta
+Project-URL: Repository, https://github.com/pablokaua03/contexta
+Author-email: Pablo Kaua <help@spacegroupusa.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,codebase,context,cursor,developer-tools,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer<4,>=3.4
+Requires-Dist: mcp[cli]<2,>=1.9
+Requires-Dist: pathspec<1.1,>=0.12
+Requires-Dist: rapidfuzz<4,>=3.14
+Requires-Dist: tiktoken<1,>=0.12
+Requires-Dist: tree-sitter-language-pack<2,>=1.6
+Requires-Dist: tree-sitter<0.26,>=0.25
+Provides-Extra: all-ai
+Requires-Dist: anthropic<1,>=0.52; extra == 'all-ai'
+Requires-Dist: google-genai<2,>=1.14; extra == 'all-ai'
+Requires-Dist: openai<2,>=1.82; extra == 'all-ai'
+Provides-Extra: claude
+Requires-Dist: anthropic<1,>=0.52; extra == 'claude'
+Provides-Extra: gemini
+Requires-Dist: google-genai<2,>=1.14; extra == 'gemini'
+Provides-Extra: gui
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.82; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Contexta
+
+**AI-native codebase context engine. Serves intelligent project context to Claude Code, Cursor, Windsurf, and any MCP-compatible tool — or generates curated context packs for manual use.**
+
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python&logoColor=white)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)]()
+[![Version](https://img.shields.io/badge/Version-2.0.0-purple)]()
+[![MCP](https://img.shields.io/badge/MCP-Compatible-orange)]()
+
+<br>
+
+[<img src="https://img.shields.io/badge/pip%20install%20contexta--ai-3776AB?style=for-the-badge&logo=pypi&logoColor=white" height="42">](https://pypi.org/project/contexta-ai/)
+&nbsp;&nbsp;
+[<img src="https://img.shields.io/badge/Download%20for%20Windows-0078D4?style=for-the-badge&logo=windows&logoColor=white" height="42">](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta.exe)
+&nbsp;&nbsp;
+[<img src="https://img.shields.io/badge/Download%20for%20Linux-E95420?style=for-the-badge&logo=linux&logoColor=white" height="42">](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta-linux.tar.gz)
+
+> Install via pip, download the portable executable, or run from source.
+
+<br>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/white.png">
+  <img alt="Contexta interface preview" src="assets/dark.png">
+</picture>
+
+</div>
+
+---
+
+## What is Contexta
+
+Contexta analyzes codebases and serves intelligent, curated context to AI tools. Instead of dumping files blindly, it understands project structure, detects frameworks, ranks files by importance, and delivers exactly what an AI needs.
+
+**Three ways to use it:**
+
+| Mode | Command | What it does |
+|---|---|---|
+| **MCP Server** | `contexta serve` | Runs as a tool server — Claude Code, Cursor, Windsurf call it automatically |
+| **CLI** | `contexta ./project --pack onboarding` | Generates a context pack Markdown file |
+| **GUI** | `contexta` | Desktop app with visual controls |
+
+---
+
+## MCP Server (recommended)
+
+The MCP server is the primary way to use Contexta. AI coding assistants call it as a tool to understand your project — no copy-paste needed.
+
+### Setup
+
+Add to your MCP configuration (Claude Code, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "contexta": {
+      "command": "contexta",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Or if running from source:
+
+```json
+{
+  "mcpServers": {
+    "contexta": {
+      "command": "python",
+      "args": ["/path/to/contexta_mcp.py"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | What it does |
+|---|---|
+| `scan_project` | Quick fingerprint — type, language, frameworks, deps, entry points |
+| `get_architecture` | Module relationships, folder structure, risks, key patterns |
+| `generate_context` | Full AI-optimized context pack with all preset options |
+| `find_files` | Search files by name, extension, or keyword |
+| `read_files` | Read specific file contents |
+| `list_packs` | List available pack presets |
+| `cache_status` | Show cache hit/miss statistics |
+| `refresh_cache` | Force-refresh cached analysis |
+
+### Smart cache
+
+Results are cached in memory with automatic invalidation. First call analyzes the project (~700ms), subsequent calls return in ~2ms until files change on disk. The cache monitors file mtimes and manifest files — when you edit code, the next call recomputes automatically.
+
+---
+
+## Install
+
+### Option A: pip (recommended)
+
+```bash
+pip install contexta-ai
+```
+
+Optional AI API integrations:
+
+```bash
+pip install contexta-ai[claude]    # Claude API
+pip install contexta-ai[gemini]    # Gemini API
+pip install contexta-ai[openai]    # OpenAI API
+pip install contexta-ai[all-ai]    # All three
+```
+
+### Option B: Portable executables
+
+- **Windows**: download [`contexta.exe`](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta.exe)
+- **Linux**: download [`contexta-linux.tar.gz`](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta-linux.tar.gz)
+
+### Option C: From source
+
+```bash
+git clone https://github.com/pablokaua03/Contexta.git
+cd Contexta
+pip install -r requirements.txt
+python contexta.py
+```
+
+---
+
+## CLI usage
+
+```bash
+# Generate context packs
+contexta ./project                                          # default pack
+contexta ./project --pack onboarding                        # understand a new codebase
+contexta ./project --pack raw_files                         # clean path + content dump
+contexta ./project --pack pr_review --diff --copy           # review changes
+contexta ./project --mode debug --focus "auth flow"         # debug a specific area
+
+# AI API integration — send context + question directly to an AI
+contexta ./project --ask "what are the main security risks?"
+contexta ./project --ask "explain the architecture" --provider claude
+
+# Configure AI API keys
+contexta --configure-ai
+```
+
+### CLI flags
+
+| Flag | Description |
+|---|---|
+| `--pack` | Preset: `custom`, `chatgpt`, `onboarding`, `pr_review`, `risk_review`, `debug`, `backend`, `frontend`, `changes_related`, `raw_files` |
+| `--mode` | Context mode: `full`, `debug`, `feature`, `diff`, `onboarding`, `refactor` |
+| `--compression` | `full`, `balanced`, `focused`, `signatures`, `lean` |
+| `--ai` | Target AI profile: `generic`, `chatgpt`, `claude`, `gemini`, `copilot` |
+| `--task` | Task profile: `general`, `ai_handoff`, `bug_report`, `code_review`, `explain_project`, `risk_analysis`, `refactor_request`, `pr_summary`, `write_tests`, `find_dead_code` |
+| `--focus` | Bias scoring around a topic (e.g. `"auth flow"`, `"database"`) |
+| `--diff` / `--staged` | Use git changes as context |
+| `--ask` | Send context pack + prompt to an AI API |
+| `--provider` | AI provider: `claude`, `gemini`, `openai` |
+| `--api-key` | API key (also reads `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENAI_API_KEY`) |
+| `--configure-ai` | Interactive AI API setup |
+| `-c` / `--copy` | Copy output to clipboard |
+| `-o` / `--output` | Custom output path |
+
+---
+
+## Context packs
+
+| Pack | Best for |
+|---|---|
+| `onboarding` | Understanding a new codebase fast |
+| `pr_review` | Code review with change context |
+| `risk_review` | Regression hotspots, missing coverage, broad-impact modules |
+| `debug` | Bug hunting with changed/suspicious files prioritized |
+| `backend` / `frontend` | Bias toward one side of the app |
+| `changes_related` | Git changes + nearby relevant files |
+| `raw_files` | Clean dump of important files — path + full content, no analysis |
+| `chatgpt` | General-purpose ChatGPT preset |
+| `custom` | Full manual control |
+
+---
+
+## What Contexta exports
+
+Depending on pack, mode, and task, the output can include:
+
+- Project summary with detected technologies, entry points, purpose, and central modules
+- Read-this-first path through the repository
+- Main execution flow narrative
+- Core files, supporting files, related tests, and changed-file context
+- Relationship maps and risk notes
+- Score breakdown explaining why each file was selected
+- Curated Markdown payload ready for any AI tool
+
+---
+
+## Main features
+
+| Feature | Detail |
+|---|---|
+| **MCP Server** | `contexta serve` — AI tools call it as a tool server with smart caching |
+| **AI API integration** | `--ask` sends context directly to Claude, Gemini, or OpenAI |
+| **Smart cache** | ~2ms cached responses with automatic mtime-based invalidation |
+| **Raw files pack** | Clean path + content dump for simple AI workflows |
+| **GUI + CLI** | Desktop app for visual use, CLI for scripting and automation |
+| **Project fingerprinting** | Detects stack, frameworks, domain, and project type automatically |
+| **Syntax-aware analysis** | tree-sitter + heuristic fallback for symbol extraction |
+| **Multi-language** | Python, JS/TS, Go, Rust, PHP, Java, C#, Kotlin, Swift, C++ and more |
+| **Token guidance** | tiktoken-backed estimates for pack sizing |
+| **Inline blob protection** | Collapses base64/binary literals automatically |
+| **PyPI package** | `pip install contexta-ai` with optional AI extras |
+
+---
+
+## Build from source
+
+```bash
+# Windows (requires Visual Studio C++ Build Tools)
+.\build.bat
+
+# Linux / macOS
+chmod +x build.sh && ./build.sh
+```
+
+Build outputs: `dist/contexta.exe` (Windows), `dist/contexta` (Linux/macOS), `dist/contexta-linux.tar.gz` (Linux bundle).
+
+---
+
+## Run tests
+
+```bash
+python -m pytest tests/ -k "not test_relation_score"
+```
+
+---
+
+## Security and behavior
+
+- Read-only: Contexta does not modify the scanned project
+- No runtime telemetry or network requirement (except optional `--ask` AI calls)
+- Scan limits prevent runaway exports
+- Embedded binary/blob payloads are suppressed automatically
+- AI API keys are stored locally in `~/.contexta/ai_config.json` when using `--configure-ai`
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE) © [pablokaua03](https://github.com/pablokaua03)

contexta_ai-2.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+contexta_app/__init__.py,sha256=1sFrjiDsOqTfdTMOhOPtx5qNwJ9p_MHr9CEIEQGfb98,38
+contexta_app/ai_client.py,sha256=1WwOY61KtMsb4Wge8RkZXu2IAf7oSnhGxzoCJzTlSSk,5366
+contexta_app/cache.py,sha256=hGqM9vAiZW9TO1FxEuS68iMJ075U6Z6zlu992AxL1KU,4169
+contexta_app/cli.py,sha256=WJv2WJpse0vyxE9gMHTAQK-Scaqp_IH1MjJn_eNT0JA,7725
+contexta_app/context_engine.py,sha256=4Bs0W7Ac_2KNjAAP0No8hnu2Vy5dk7mp4-lPvp-Iehs,231598
+contexta_app/embedded_icon_data.py,sha256=_CImjDgPdmIrTCTe0U7aeUCMlm3wx8hS_6mugi5csoE,33637
+contexta_app/mcp_server.py,sha256=SubradWolkrtAxT_qB-wI94wHFuSBWVotay8bx9KqDg,11317
+contexta_app/renderer.py,sha256=L2CGlgAeZXk-XF8dIFaZgjOnHVZ0LEpMmZCuOWSX0H0,79649
+contexta_app/scanner.py,sha256=mWaRYinpBUpwHx7aie2qpEZbFzX-j9R5wrQpLsfU_vY,13614
+contexta_app/syntax.py,sha256=F41VfxPJDJdgS6DbCiUufqYH6-z3_be53-WGIE9m0Ss,6216
+contexta_app/theme.py,sha256=OgaIwSYCq3MSOg3CX8tC7NbU-n5zsnPTcGTMD561WOM,4700
+contexta_app/ui.py,sha256=gdJiCIbagWciiDIaR4kH3VbQWAVhfvDVMBnldpFtxVs,84704
+contexta_app/utils.py,sha256=DE0QGhNT8-VVdNa2XEZoBclzkRUqlbuEgIm5hJsBu3I,771
+contexta_ai-2.0.0.dist-info/METADATA,sha256=w-eNqTJalqx0e8Ty7usALZtPZv74aS2oihsVbwLrIxI,10799
+contexta_ai-2.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+contexta_ai-2.0.0.dist-info/entry_points.txt,sha256=uiU3v16omDQFbRjybKBk7RIlxIfCy4c3G3KqJ_TDZog,43
+contexta_ai-2.0.0.dist-info/licenses/LICENSE,sha256=Hj-WZf4KcurgEbiLdQnqWwIewx_bJmcrgawyQDraCmE,1068
+contexta_ai-2.0.0.dist-info/RECORD,,

contexta_ai-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

contexta_ai-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contexta = contexta:main

contexta_ai-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pablokaua03
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contexta_app/__init__.py

@@ -0,0 +1,3 @@
+"""
+Contexta application package.
+"""

contexta_app/ai_client.py

@@ -0,0 +1,182 @@
+"""AI API client for sending context packs directly to Claude, Gemini, or OpenAI."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".contexta" / "ai_config.json"
+
+ENV_VARS = {
+    "claude": "ANTHROPIC_API_KEY",
+    "gemini": "GOOGLE_API_KEY",
+    "openai": "OPENAI_API_KEY",
+}
+
+DEFAULT_MODELS = {
+    "claude": "claude-sonnet-4-20250514",
+    "gemini": "gemini-2.5-flash",
+    "openai": "gpt-4o",
+}
+
+PROVIDER_LABELS = {
+    "claude": "Claude (Anthropic)",
+    "gemini": "Gemini (Google)",
+    "openai": "ChatGPT / GPT-4 (OpenAI)",
+}
+
+
+@dataclass
+class AIConfig:
+    provider: str = ""  # "claude", "gemini", "openai"
+    api_key: str = ""
+    model: str = ""
+
+    @staticmethod
+    def load() -> "AIConfig":
+        if CONFIG_PATH.exists():
+            data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+            return AIConfig(**{k: v for k, v in data.items() if k in AIConfig.__dataclass_fields__})
+        return AIConfig()
+
+    def save(self) -> None:
+        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        CONFIG_PATH.write_text(
+            json.dumps(
+                {"provider": self.provider, "api_key": self.api_key, "model": self.model},
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+
+
+def get_available_providers() -> list[str]:
+    """Return provider keys whose SDK is installed."""
+    available = []
+    try:
+        import anthropic  # noqa: F401
+        available.append("claude")
+    except ImportError:
+        pass
+    try:
+        import google.genai  # noqa: F401
+        available.append("gemini")
+    except ImportError:
+        pass
+    try:
+        import openai  # noqa: F401
+        available.append("openai")
+    except ImportError:
+        pass
+    return available
+
+
+def resolve_api_key(provider: str, explicit_key: str = "") -> str:
+    """Resolve API key: explicit flag > env var > saved config."""
+    if explicit_key:
+        return explicit_key
+    env_var = ENV_VARS.get(provider, "")
+    if env_var:
+        env_val = os.environ.get(env_var, "")
+        if env_val:
+            return env_val
+    cfg = AIConfig.load()
+    if cfg.provider == provider and cfg.api_key:
+        return cfg.api_key
+    return ""
+
+
+def send_to_ai(
+    context_markdown: str,
+    prompt: str,
+    provider: str,
+    api_key: str,
+    model: str = "",
+) -> str:
+    """Send context + prompt to the chosen AI and return the response text."""
+    if not model:
+        model = DEFAULT_MODELS.get(provider, "")
+
+    system_msg = (
+        "You are a senior software engineer. The user will provide a project context "
+        "pack followed by a question or task. Analyze the context and respond helpfully."
+    )
+
+    if provider == "claude":
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=api_key)
+        response = client.messages.create(
+            model=model,
+            max_tokens=8192,
+            system=system_msg,
+            messages=[{"role": "user", "content": f"{context_markdown}\n\n---\n\n{prompt}"}],
+        )
+        return response.content[0].text
+
+    elif provider == "gemini":
+        from google import genai
+
+        client = genai.Client(api_key=api_key)
+        response = client.models.generate_content(
+            model=model,
+            contents=f"{system_msg}\n\n{context_markdown}\n\n---\n\n{prompt}",
+        )
+        return response.text
+
+    elif provider == "openai":
+        import openai as oai
+
+        client = oai.OpenAI(api_key=api_key)
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": f"{context_markdown}\n\n---\n\n{prompt}"},
+            ],
+        )
+        return response.choices[0].message.content
+
+    else:
+        raise ValueError(f"Unknown provider: {provider}")
+
+
+def configure_interactive() -> None:
+    """Interactive setup: choose provider, enter API key and model, save to config."""
+    available = get_available_providers()
+    all_providers = list(PROVIDER_LABELS.keys())
+
+    print("AI Configuration for Contexta")
+    print("=" * 40)
+    print("\nAvailable providers (SDK installed):")
+    for p in all_providers:
+        installed = p in available
+        label = PROVIDER_LABELS[p]
+        status = "installed" if installed else "not installed"
+        print(f"  {p:10s} - {label} [{status}]")
+
+    print()
+    provider = input(f"Choose provider ({', '.join(all_providers)}): ").strip().lower()
+    if provider not in all_providers:
+        print(f"Unknown provider '{provider}'. Aborting.")
+        return
+
+    if provider not in available:
+        pkg = {"claude": "anthropic", "gemini": "google-genai", "openai": "openai"}[provider]
+        print(f"\nWarning: '{pkg}' is not installed. Install it with: pip install {pkg}")
+
+    api_key = input("API key: ").strip()
+    if not api_key:
+        print("No API key provided. Aborting.")
+        return
+
+    default_model = DEFAULT_MODELS.get(provider, "")
+    model = input(f"Model (default: {default_model}): ").strip()
+    if not model:
+        model = default_model
+
+    cfg = AIConfig(provider=provider, api_key=api_key, model=model)
+    cfg.save()
+    print(f"\nSaved to {CONFIG_PATH}")

contexta_app/cache.py

@@ -0,0 +1,163 @@
+"""
+cache.py - Smart project cache with file-change detection.
+
+Keeps ProjectAnalysis in memory and invalidates when source files change.
+No background threads — checks mtimes on access, so it's safe for MCP's
+async model.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from contexta_app.context_engine import ExportConfig, ProjectAnalysis, build_analysis
+from contexta_app.scanner import (
+    build_tree,
+    count_files,
+    get_git_changed_files,
+    load_gitignore_patterns,
+)
+
+
+@dataclass
+class _CacheEntry:
+    analysis: ProjectAnalysis
+    tree: dict
+    file_count: int
+    mtimes: dict[str, float]
+    created_at: float
+    hit_count: int = 0
+
+
+_NOOP_LOG = lambda msg, tag="": None
+_MAX_CACHE_AGE = 300.0
+_MAX_ENTRIES = 10
+
+_cache: dict[str, _CacheEntry] = {}
+_stats = {"hits": 0, "misses": 0, "invalidations": 0}
+
+
+def _snapshot_mtimes(path: Path, file_paths: list[Path]) -> dict[str, float]:
+    result = {}
+    for fp in file_paths:
+        try:
+            result[str(fp)] = fp.stat().st_mtime
+        except OSError:
+            result[str(fp)] = 0.0
+
+    for marker in ("package.json", "pyproject.toml", "Cargo.toml", "go.mod",
+                    "requirements.txt", "composer.json", "Gemfile", ".gitignore"):
+        candidate = path / marker
+        if candidate.exists():
+            try:
+                result[str(candidate)] = candidate.stat().st_mtime
+            except OSError:
+                pass
+    return result
+
+
+def _has_changes(entry: _CacheEntry) -> bool:
+    if time.time() - entry.created_at > _MAX_CACHE_AGE:
+        return True
+
+    for fpath, old_mtime in entry.mtimes.items():
+        try:
+            current = Path(fpath).stat().st_mtime
+            if current != old_mtime:
+                return True
+        except OSError:
+            return True
+    return False
+
+
+def _evict_oldest():
+    if len(_cache) < _MAX_ENTRIES:
+        return
+    oldest_key = min(_cache, key=lambda k: _cache[k].created_at)
+    del _cache[oldest_key]
+
+
+def get_analysis(
+    project_path: Path,
+    config: ExportConfig | None = None,
+    force_refresh: bool = False,
+    log_cb=None,
+) -> tuple[ProjectAnalysis, dict, int, bool]:
+    """Return (analysis, tree, file_count, was_cached).
+
+    Uses cached analysis if files haven't changed, otherwise recomputes.
+    """
+    if log_cb is None:
+        log_cb = _NOOP_LOG
+    if config is None:
+        config = ExportConfig()
+
+    key = str(project_path.resolve())
+    entry = _cache.get(key)
+
+    if entry is not None and not force_refresh and not _has_changes(entry):
+        entry.hit_count += 1
+        _stats["hits"] += 1
+        return entry.analysis, entry.tree, entry.file_count, True
+
+    if entry is not None:
+        _stats["invalidations"] += 1
+
+    _stats["misses"] += 1
+    _evict_oldest()
+
+    gitignore = load_gitignore_patterns(project_path)
+    counter = [0]
+    tree = build_tree(
+        root=project_path,
+        include_hidden=False,
+        include_unknown=False,
+        log_cb=log_cb,
+        counter=counter,
+        gitignore_patterns=gitignore,
+        project_root=project_path,
+    )
+    file_count = count_files(tree)
+    changed = get_git_changed_files(project_path) or []
+    analysis = build_analysis(
+        project_path=project_path,
+        full_tree=tree,
+        changed_files=changed,
+        config=config,
+        log_cb=log_cb,
+    )
+
+    all_paths = [f.path for f in analysis.all_files]
+    mtimes = _snapshot_mtimes(project_path, all_paths)
+
+    _cache[key] = _CacheEntry(
+        analysis=analysis,
+        tree=tree,
+        file_count=file_count,
+        mtimes=mtimes,
+        created_at=time.time(),
+    )
+
+    return analysis, tree, file_count, False
+
+
+def get_cache_stats() -> dict:
+    return {
+        "entries": len(_cache),
+        "projects": list(_cache.keys()),
+        **_stats,
+    }
+
+
+def invalidate(project_path: Path | None = None) -> int:
+    if project_path is None:
+        count = len(_cache)
+        _cache.clear()
+        return count
+    key = str(project_path.resolve())
+    if key in _cache:
+        del _cache[key]
+        return 1
+    return 0