sourcecode 1.0.0__tar.gz → 1.1.0__tar.gz

sourcecode-1.1.0/.github/workflows/build-windows.yml

@@ -0,0 +1,40 @@
+name: Build Windows EXE
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install nuitka
+          pip install .
+
+      - name: Build EXE
+        run: |
+          python -m nuitka ^
+            --onefile ^
+            --standalone ^
+            --follow-imports ^
+            --assume-yes-for-downloads ^
+            --output-dir=build ^
+            run_cli.py
+        shell: cmd
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sourcecode-windows
+          path: build/**/*.exe

{sourcecode-1.0.0 → sourcecode-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.0.0
+Version: 1.1.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,349 +221,141 @@ Description-Content-Type: text/markdown
 
 **Deterministic codebase context for AI coding agents.**
 
-[![PyPI](https://img.shields.io/pypi/v/sourcecode)](https://pypi.org/project/sourcecode/)
-[![Python](https://img.shields.io/pypi/pyversions/sourcecode)](https://pypi.org/project/sourcecode/)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
-[![CI](https://img.shields.io/github/actions/workflow/status/sourcecode-ai/sourcecode/ci.yml)](https://github.com/sourcecode-ai/sourcecode/actions)
-
-Turn any repository into structured, reproducible context optimized for AI coding agents — in one command.
-
-```bash
-pip install sourcecode
-sourcecode . --agent
-```
-
-```json
-{
-  "project": {
-    "type": "api",
-    "summary": "Python REST API built with FastAPI and SQLAlchemy. Layered architecture with domain, service, and infrastructure layers.",
-    "primary_stack": "python",
-    "frameworks": ["FastAPI", "SQLAlchemy"]
-  },
-  "entry_points": [
-    { "path": "src/app/main.py", "kind": "server", "confidence": "high" }
-  ],
-  "architecture": "FastAPI application. Clean Architecture with domain, application, and infrastructure layers. Hub modules: schema.py, models.py.",
-  "key_dependencies": [
-    { "name": "fastapi", "declared_version": ">=0.100", "role": "runtime" },
-    { "name": "sqlalchemy", "declared_version": "^2.0", "role": "runtime" },
-    { "name": "pydantic", "declared_version": "^2.0", "role": "runtime" }
-  ],
-  "confidence_summary": { "overall": "high" }
-}
-```
+![Version](https://img.shields.io/badge/version-1.0.0-blue)
+![Status](https://img.shields.io/badge/status-MVP-orange)
+![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
 
-## The problem
+## What is it?
 
-AI coding agents are only as good as the context they receive. In large, real-world repositories, that context is almost always wrong.
-
-- **Agents start blind.** Without repo structure, they hallucinate imports, file paths, and architecture decisions.
-- **Context is noisy.** Raw file trees contain benchmark dirs, generated files, tooling configs, and docs that consume tokens without helping.
-- **Architecture is invisible.** LLMs see files, not systems. They miss layers, plugin systems, entry points, and runtime topology.
-- **Context decays.** What you paste today is stale tomorrow. There's no reproducible baseline.
-- **Manual context doesn't scale.** Handcrafting prompts per project is engineering debt that grows with every new agent, team, and task.
+`sourcecode` analyzes a repository and produces a structured context map (JSON or YAML) designed to be consumed by AI agents or language models. It solves the "stuff the whole repo into the prompt" problem by instead producing a deterministic extract: entry points, dependencies, stacks, inline annotations, environment variables, and git activity. It is an MVP tool under active evolution — the semantic analysis and module graph features work but have known limitations that are explicitly documented below.
 
 ---
 
-## The solution
-
-`sourcecode` analyzes your repository and produces a structured, reproducible context package — ready to inject into any AI coding agent.
-
-**What it does:**
-- Detects stacks, frameworks, entry points, and project type across 10+ languages
-- Infers runtime topology: which packages are core, which are plugins, which are noise
-- Ranks files by operational relevance for agents: git churn + runtime proximity + bootstrap signal
-- Suppresses non-runtime noise: benchmarks, docs, tooling, generated files
-- Produces structured JSON/YAML that agents can reason over, not raw file trees
-- Runs deterministically — same repo, same output, every time
-
-**What it outputs:**
-- `project_summary` — one-sentence natural language description
-- `architecture_summary` — runtime topology: layers, plugin systems, entry flows
-- `entry_points` — where execution actually starts (production, not benchmarks)
-- `key_dependencies` — runtime dependencies with role classification
-- `relevant_files` — ranked by usefulness for coding tasks, not folder position
-- `confidence_summary` — detection quality and analysis gaps
-
-All fields are stable, machine-readable, and designed for LLM consumption.
-
----
+## Installation
 
-## Install
+**Prerequisites:** Python 3.10+
 
 ```bash
 pip install sourcecode
+# or with pipx for isolation:
+pipx install sourcecode
 ```
 
-Requires Python 3.9+. No API keys. No network calls. Runs locally.
-
----
-
-## Quickstart
-
-**Basic analysis:**
-```bash
-sourcecode .
-```
-
-**Agent-optimized output** (structured, noise-free, gap-aware):
-```bash
-sourcecode . --agent
-```
-
-**Task-specific context for coding agents:**
-```bash
-# Explain the project architecture
-sourcecode . prepare-context explain
-
-# Find likely bug locations
-sourcecode . prepare-context fix-bug
-
-# Onboard a new agent to the codebase
-sourcecode . prepare-context onboard
-
-# Ranked context for a specific task
-sourcecode . prepare-context refactor
-```
-
-**Pipe directly into Claude Code or any agent:**
-```bash
-sourcecode . --agent | claude -p "Review the architecture and suggest improvements"
-```
-
-**Write to file for session injection:**
-```bash
-sourcecode . --agent --output context.json
-```
+Verify installation:
 
-**Include git activity signals:**
 ```bash
-sourcecode . --agent --git-context
+sourcecode version
+# sourcecode 1.0.0
 ```
 
 ---
 
-## Use cases
-
-### Claude Code
-```bash
-# Start every session with full context
-sourcecode . --agent > .claude/context.json
-
-# Use with CLAUDE.md for persistent context
-echo "$(sourcecode . --agent --compact)" >> CLAUDE.md
-```
-
-### Cursor / Windsurf / Copilot
-```bash
-# Generate context snapshot before starting a feature
-sourcecode . --agent --git-context --output .cursor/context.json
-```
-
-### OpenAI / Anthropic API
-```python
-import json, subprocess
-
-context = json.loads(
-    subprocess.check_output(["sourcecode", ".", "--agent"])
-)
-
-system_prompt = f"""
-You are working on: {context['project']['summary']}
-Architecture: {context['architecture']}
-Entry points: {[ep['path'] for ep in context['entry_points']]}
-"""
-```
-
-### CI / CD pipelines
-```yaml
-# .github/workflows/context.yml
-- name: Generate codebase context
-  run: sourcecode . --agent --output context.json
-
-- name: AI-assisted code review
-  run: |
-    CONTEXT=$(cat context.json)
-    # Inject into your preferred AI review step
-```
+## Quickstart
 
-### Onboarding new engineers
-```bash
-# Generate human-readable architecture summary
-sourcecode . prepare-context onboard --llm-prompt
-```
+The most useful command for integrating `sourcecode` into an AI agent:
 
-### Architecture audits
 ```bash
-sourcecode . --agent --architecture --graph-modules --dependencies
+sourcecode --agent
 ```
 
----
-
-## How it works
-
-`sourcecode` runs a local, static analysis pipeline on your repository:
+It produces a structured JSON with the essential sections (no noise, no file tree), ready to paste into an LLM context:
 
+```json
+{
+  "project": {
+    "type": "fullstack",
+    "summary": "Full-stack project in Nodejs, mvc, 4075 source files. Domains: atlas-client, atlas-server, atlas-hub, atlas-reports. 3300 dependencies (java, nodejs).",
+    "primary_stack": "nodejs",
+    "secondary_stacks": ["java"]
+  },
+  "entry_points": [
+    {
+      "path": "atlas-server/src/main/java/com/example/atlas/AtlasServerApplication.java",
+      "stack": "java",
+      "kind": "application",
+      "confidence": "high"
+    },
+    {
+      "path": "atlas-client/src/main.ts",
+      "stack": "nodejs",
+      "kind": "entrypoint",
+      "confidence": "high"
+    }
+  ],
+  "runtime_packages": [ ... ],
+  "dependencies": { ... },
+  "env_map": { ... },
+  "code_notes": [ ... ]
+}
 ```
-Repository
-    │
-    ├── Scanner          # File tree, manifests, workspace detection
-    ├── Stack Detectors  # Language, framework, package manager detection
-    ├── Entry Points     # Production entry points (not benchmarks/docs)
-    ├── Git Analyzer     # Churn hotspots, uncommitted changes
-    ├── Relevance Scorer # Runtime proximity × git churn × bootstrap signal
-    └── Serializer       # Structured JSON/YAML output
-```
-
-No LLM calls. No network requests. No sampling. Fully deterministic.
-
-The same repository produces the same output on every run — which means agents can cache it, diff it, and rely on it.
-
----
-
-## Output modes
-
-| Mode | Use case | Size |
-|------|----------|------|
-| `sourcecode .` | Full analysis | Full |
-| `sourcecode . --agent` | AI agent injection | ~600–1000 tokens |
-| `sourcecode . --compact` | Prompts, handoffs | ~500–700 tokens |
-| `sourcecode . prepare-context <task>` | Task-specific context | ~800–1200 tokens |
-
-### Available flags
-
-| Flag | Description |
-|------|-------------|
-| `--agent` | Structured, noise-free output for AI agents. Auto-enables `--dependencies`, `--env-map`, `--code-notes`. |
-| `--dependencies` | Direct dependencies with versions and role classification. |
-| `--git-context` | Recent commits, change hotspots, uncommitted files. |
-| `--architecture` | Layer inference: MVC, layered, hexagonal, domain-based. |
-| `--graph-modules` | Module import graph and call relationships. |
-| `--semantics` | Cross-file symbol resolution and call graph. |
-| `--env-map` | All environment variables referenced in source. |
-| `--code-notes` | TODOs, FIXMEs, HACKs, and Architecture Decision Records. |
-| `--compact` | Minimal output for token-constrained prompts. |
-| `--format yaml` | YAML instead of JSON. |
-| `--output PATH` | Write to file instead of stdout. |
-
-Full reference: `sourcecode --help`
-
-### Prepare-context tasks
-
-| Task | What it produces |
-|------|-----------------|
-| `explain` | Architecture + entry points + key dependencies |
-| `fix-bug` | Risk-ranked files + suspected areas + code annotations |
-| `refactor` | Structural issues + improvement opportunities |
-| `generate-tests` | Untested source files + test gap analysis |
-| `onboard` | Full project understanding for new agents/developers |
-| `review-pr` | Changed files + architectural impact |
-| `delta` | Git-changed files only — incremental context |
-
----
-
-## Philosophy
-
-**Determinism over approximation.** Every run on the same repository produces the same output. Agents, pipelines, and teams can depend on that.
 
-**Runtime topology over file trees.** What matters is where execution starts, what calls what, and which modules are actually critical — not alphabetical file lists.
+For large repositories where context matters, use `--compact` to reduce to ~600-800 tokens:
 
-**Noise suppression by default.** Benchmark dirs, generated files, tooling configs, and docs are suppressed unless explicitly requested. Agents get signal, not inventory.
-
-**Local-first, privacy-respecting.** No code leaves your machine. No API keys required. Analysis is fully offline.
-
-**Composable, not monolithic.** Output is structured data. Pipe it, transform it, inject it, cache it. It's infrastructure, not a magic black box.
-
-**Confidence-aware.** Every analysis includes a confidence summary and gap list. Agents know what they don't know.
-
----
-
-## Supported languages and stacks
-
-| Language | Package detection | Entry points | Frameworks |
-|----------|-------------------|--------------|------------|
-| Python | `pyproject.toml`, `requirements.txt`, `setup.py` | CLI, scripts, `__main__` | FastAPI, Django, Flask, Typer, Click |
-| Node.js | `package.json`, lock files | `main`, `bin`, scripts | Express, Next.js, Fastify, NestJS, React, Vue |
-| Go | `go.mod` | `main.go`, `cmd/` | Standard library, Gin, Echo |
-| Rust | `Cargo.toml` | `main.rs`, `lib.rs` | Tokio, Actix, Axum |
-| Java | `pom.xml`, `build.gradle` | Spring Boot, Quarkus, Micronaut | Spring, Quarkus |
-| Kotlin | `build.gradle.kts` | Spring Boot, Ktor | Spring, Ktor |
-| .NET / C# | `.csproj`, `.sln` | `Program.cs` | ASP.NET, Blazor |
-| PHP | `composer.json` | `index.php` | Laravel, Symfony |
-| Ruby | `Gemfile` | `config.ru` | Rails, Sinatra |
-| Dart | `pubspec.yaml` | `main.dart` | Flutter |
-
-Monorepos with mixed stacks are fully supported.
-
----
-
-## Roadmap
-
-**Now — Core stability**
-- Ranking improvements (git churn, runtime proximity)
-- Better architecture inference
-- Broader language coverage
-
-**Next — Agent integrations**
-- MCP server for native Claude Code integration
-- VS Code extension
-- Context diffing (compare before/after changes)
-- Incremental updates (delta mode improvements)
-
-**Later — Team features**
-- Shared context snapshots
-- Architecture drift detection
-- CI integration templates
-- Governance and compliance context
-
-> Focus is on adoption and utility. No monetization until the core is genuinely useful to the community.
-
----
-
-## Contributing
-
-We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and guidelines.
-
-**Quick start for contributors:**
 ```bash
-git clone https://github.com/sourcecode-ai/sourcecode
-cd sourcecode
-pip install -e ".[dev]"
-pytest tests/
+sourcecode --compact --copy
+# Copies the summary to the clipboard. Ready to paste.
 ```
 
 ---
 
-## Security
-
-`sourcecode` analyzes local repositories. It does not transmit code, paths, or analysis results to any external service. See [SECURITY.md](SECURITY.md) for our security policy and responsible disclosure process.
+## Flags reference
+
+### Global options
+
+| Flag | Alias | Type | Default | Description | Status |
+|------|-------|------|---------|-------------|--------|
+| `--format` | `-f` | `json\|yaml` | `json` | Output format. YAML is more readable, JSON preferred in pipelines. | ✅ CORE |
+| `--output` | `-o` | `PATH` | stdout | Writes output to a file instead of stdout. | ✅ CORE |
+| `--compact` | | flag | off | ~600-800 token output: stacks, entry points, deps, gaps. No file tree. | ✅ CORE |
+| `--agent` | | flag | off | JSON optimized for agents. Automatically enables `--dependencies`, `--env-map`, `--code-notes`. | ✅ CORE |
+| `--dependencies` | | flag | off | Analyzes direct and transitive deps from manifests and lockfiles. | ✅ CORE |
+| `--git-context` | `-g` | flag | off | Includes recent commits, change hotspots, uncommitted changes, contributors. | ✅ CORE |
+| `--git-depth` | | `INT [1–100]` | `20` | Number of recent commits with `--git-context`. | ✅ CORE |
+| `--git-days` | | `INT [1–3650]` | `90` | Window in days to detect hotspots with `--git-context`. | ✅ CORE |
+| `--env-map` | | flag | off | Maps environment variables: key, type, category, files that reference them. | ✅ CORE |
+| `--code-notes` | | flag | off | Extracts inline annotations: TODO, FIXME, HACK, BUG, DEPRECATED, NOTE, etc. | ✅ CORE |
+| `--copy` | `-c` | flag | off | Copies output to the clipboard after successful execution. | ✅ CORE |
+| `--depth` | | `INT [1–20]` | `4` | Maximum file tree traversal depth. Java/Maven requires ≥8. | ✅ CORE |
+| `--mode` | | `contract\|standard\|raw` | `contract` | `contract`: minimal contracts per file. `standard`: full detail. `raw`: project level only. | ✅ CORE |
+| `--tree` | | flag | off | Includes full `file_tree` and `file_paths` in the output. Increases size significantly. | ✅ CORE |
+| `--changed-only` | | flag | off | Contract mode: only files modified in git (staged, unstaged, untracked). | ✅ CORE |
+| `--rank-by` | | `relevance\|centrality\|git-churn` | `relevance` | File ranking strategy in contract mode. | ✅ CORE |
+| `--semantics` | | flag | off | Cross-file symbol resolution, call graph with confidence levels, fan-in/fan-out hotspots. Slower. | 🧪 EXP |
+| `--architecture` | | flag | off | Architectural layer inference (MVC/hexagonal/bounded contexts). Low confidence without `--semantics`. | 🧪 EXP |
+| `--graph-modules` | | flag | off | Structural module graph: nodes (files/symbols) and edges (imports, calls, contains). | 🧪 EXP |
+| `--graph-detail` | | `high\|medium\|full` | `high` | Module graph detail level. | 🧪 EXP |
+| `--max-nodes` | | `INT [≥1]` | — | Maximum nodes in `--graph-modules`. Prevents huge graphs in large repos. | 🧪 EXP |
+| `--graph-edges` | | `TEXT` | all | Edge types for `--graph-modules`, comma-separated: `imports,calls,contains`. | 🧪 EXP |
+| `--docs` | | flag | off | Extracts docstrings, function signatures, and module comments. | 🧪 EXP |
+| `--docs-depth` | | `module\|symbols\|full` | `symbols` | Docs extraction depth. `full` includes private symbols. | 🧪 EXP |
+| `--symbol` | | `TEXT` | — | Contract mode: localized context for a specific symbol. Python, TS, JS only. **Does not support Java.** | 🧪 EXP |
+| `--max-importers` | | `INT [1–10000]` | `50` | Limit on importer files returned by `--symbol`. | 🧪 EXP |
+| `--full-metrics` | | flag | off | Per-file technical metrics: LOC, cyclomatic complexity, coverage. Aimed at CI, not at agents. | 🧪 EXP |
+| `--emit-graph` | | flag | off | Contract mode: includes a compact dependency graph (nodes + edges) in the output. | 🚧 WIP |
+| `--entrypoints-only` | | flag | off | Contract mode: only files with exports or entry points. Note: includes *all* files with exports. | 🚧 WIP |
+| `--max-symbols` | | `INT [≥1]` | — | Limits total exported symbols in contract mode. Discards lower-ranked files. | 🚧 WIP |
+| `--no-redact` | | flag | off | Disables automatic secret redaction. Output may contain sensitive values. | 🚧 WIP |
+| `--trace-pipeline` | | flag | off | Diagnostic mode: includes a trace of each candidate and filtering decision. Debugging only. | 🚧 WIP |
+| `--version` | `-v` | flag | — | Shows version and exits. | ✅ CORE |
 
 ---
 
-## Privacy
+## Subcommands
 
-Telemetry is **opt-in only** and disabled by default. If you choose to enable it, only anonymous usage metadata is collected — never code, paths, or content. See [docs/privacy.md](docs/privacy.md) for full details.
+### `prepare-context TASK [PATH]`
 
-```bash
-sourcecode telemetry status   # check current setting
-sourcecode telemetry enable   # opt in
-sourcecode telemetry disable  # opt out
-```
-
----
+Generates task-specific context for AI agents.
 
-## License
-
-Apache License 2.0. See [LICENSE](LICENSE) for details.
-
----
+| Task | Description | Status |
+|------|-------------|--------|
+| `explain` | Architecture, entry points, key dependencies | ✅ CORE |
+| `fix-bug` | Files prioritized by risk, inline annotations | ✅ CORE |
+| `onboard` | Full context for new agents or developers | ✅ CORE |
+| `delta` | Incremental context: only files changed in git | ✅ CORE |
+| `refactor` | Structural problems, improvement opportunities | 🧪 EXP |
+| `generate-tests` | Files without tests, coverage gap analysis | 🧪 EXP |
+| `review-pr` | Changed files + architectural impact | 🧪 EXP |
 
-<p align="center">
-  Built for the age of AI coding agents.<br>
-  <a href="https://github.com/sourcecode-ai/sourcecode">GitHub</a> ·
-  <a href="https://pypi.org/project/sourcecode/">PyPI</a> ·
-  <a href="docs/getting-started.md">Documentation</a>
-</p>
+...

sourcecode-1.1.0/README.md

@@ -0,0 +1,142 @@
+# sourcecode
+
+**Deterministic codebase context for AI coding agents.**
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue)
+![Status](https://img.shields.io/badge/status-MVP-orange)
+![Python](https://img.shields.io/badge/python-3.10%2B-green)
+
+---
+
+## What is it?
+
+`sourcecode` analyzes a repository and produces a structured context map (JSON or YAML) designed to be consumed by AI agents or language models. It solves the "stuff the whole repo into the prompt" problem by instead producing a deterministic extract: entry points, dependencies, stacks, inline annotations, environment variables, and git activity. It is an MVP tool under active evolution — the semantic analysis and module graph features work but have known limitations that are explicitly documented below.
+
+---
+
+## Installation
+
+**Prerequisites:** Python 3.10+
+
+```bash
+pip install sourcecode
+# or with pipx for isolation:
+pipx install sourcecode
+```
+
+Verify installation:
+
+```bash
+sourcecode version
+# sourcecode 1.0.0
+```
+
+---
+
+## Quickstart
+
+The most useful command for integrating `sourcecode` into an AI agent:
+
+```bash
+sourcecode --agent
+```
+
+It produces a structured JSON with the essential sections (no noise, no file tree), ready to paste into an LLM context:
+
+```json
+{
+  "project": {
+    "type": "fullstack",
+    "summary": "Full-stack project in Nodejs, mvc, 4075 source files. Domains: atlas-client, atlas-server, atlas-hub, atlas-reports. 3300 dependencies (java, nodejs).",
+    "primary_stack": "nodejs",
+    "secondary_stacks": ["java"]
+  },
+  "entry_points": [
+    {
+      "path": "atlas-server/src/main/java/com/example/atlas/AtlasServerApplication.java",
+      "stack": "java",
+      "kind": "application",
+      "confidence": "high"
+    },
+    {
+      "path": "atlas-client/src/main.ts",
+      "stack": "nodejs",
+      "kind": "entrypoint",
+      "confidence": "high"
+    }
+  ],
+  "runtime_packages": [ ... ],
+  "dependencies": { ... },
+  "env_map": { ... },
+  "code_notes": [ ... ]
+}
+```
+
+For large repositories where context matters, use `--compact` to reduce to ~600-800 tokens:
+
+```bash
+sourcecode --compact --copy
+# Copies the summary to the clipboard. Ready to paste.
+```
+
+---
+
+## Flags reference
+
+### Global options
+
+| Flag | Alias | Type | Default | Description | Status |
+|------|-------|------|---------|-------------|--------|
+| `--format` | `-f` | `json\|yaml` | `json` | Output format. YAML is more readable, JSON preferred in pipelines. | ✅ CORE |
+| `--output` | `-o` | `PATH` | stdout | Writes output to a file instead of stdout. | ✅ CORE |
+| `--compact` | | flag | off | ~600-800 token output: stacks, entry points, deps, gaps. No file tree. | ✅ CORE |
+| `--agent` | | flag | off | JSON optimized for agents. Automatically enables `--dependencies`, `--env-map`, `--code-notes`. | ✅ CORE |
+| `--dependencies` | | flag | off | Analyzes direct and transitive deps from manifests and lockfiles. | ✅ CORE |
+| `--git-context` | `-g` | flag | off | Includes recent commits, change hotspots, uncommitted changes, contributors. | ✅ CORE |
+| `--git-depth` | | `INT [1–100]` | `20` | Number of recent commits with `--git-context`. | ✅ CORE |
+| `--git-days` | | `INT [1–3650]` | `90` | Window in days to detect hotspots with `--git-context`. | ✅ CORE |
+| `--env-map` | | flag | off | Maps environment variables: key, type, category, files that reference them. | ✅ CORE |
+| `--code-notes` | | flag | off | Extracts inline annotations: TODO, FIXME, HACK, BUG, DEPRECATED, NOTE, etc. | ✅ CORE |
+| `--copy` | `-c` | flag | off | Copies output to the clipboard after successful execution. | ✅ CORE |
+| `--depth` | | `INT [1–20]` | `4` | Maximum file tree traversal depth. Java/Maven requires ≥8. | ✅ CORE |
+| `--mode` | | `contract\|standard\|raw` | `contract` | `contract`: minimal contracts per file. `standard`: full detail. `raw`: project level only. | ✅ CORE |
+| `--tree` | | flag | off | Includes full `file_tree` and `file_paths` in the output. Increases size significantly. | ✅ CORE |
+| `--changed-only` | | flag | off | Contract mode: only files modified in git (staged, unstaged, untracked). | ✅ CORE |
+| `--rank-by` | | `relevance\|centrality\|git-churn` | `relevance` | File ranking strategy in contract mode. | ✅ CORE |
+| `--semantics` | | flag | off | Cross-file symbol resolution, call graph with confidence levels, fan-in/fan-out hotspots. Slower. | 🧪 EXP |
+| `--architecture` | | flag | off | Architectural layer inference (MVC/hexagonal/bounded contexts). Low confidence without `--semantics`. | 🧪 EXP |
+| `--graph-modules` | | flag | off | Structural module graph: nodes (files/symbols) and edges (imports, calls, contains). | 🧪 EXP |
+| `--graph-detail` | | `high\|medium\|full` | `high` | Module graph detail level. | 🧪 EXP |
+| `--max-nodes` | | `INT [≥1]` | — | Maximum nodes in `--graph-modules`. Prevents huge graphs in large repos. | 🧪 EXP |
+| `--graph-edges` | | `TEXT` | all | Edge types for `--graph-modules`, comma-separated: `imports,calls,contains`. | 🧪 EXP |
+| `--docs` | | flag | off | Extracts docstrings, function signatures, and module comments. | 🧪 EXP |
+| `--docs-depth` | | `module\|symbols\|full` | `symbols` | Docs extraction depth. `full` includes private symbols. | 🧪 EXP |
+| `--symbol` | | `TEXT` | — | Contract mode: localized context for a specific symbol. Python, TS, JS only. **Does not support Java.** | 🧪 EXP |
+| `--max-importers` | | `INT [1–10000]` | `50` | Limit on importer files returned by `--symbol`. | 🧪 EXP |
+| `--full-metrics` | | flag | off | Per-file technical metrics: LOC, cyclomatic complexity, coverage. Aimed at CI, not at agents. | 🧪 EXP |
+| `--emit-graph` | | flag | off | Contract mode: includes a compact dependency graph (nodes + edges) in the output. | 🚧 WIP |
+| `--entrypoints-only` | | flag | off | Contract mode: only files with exports or entry points. Note: includes *all* files with exports. | 🚧 WIP |
+| `--max-symbols` | | `INT [≥1]` | — | Limits total exported symbols in contract mode. Discards lower-ranked files. | 🚧 WIP |
+| `--no-redact` | | flag | off | Disables automatic secret redaction. Output may contain sensitive values. | 🚧 WIP |
+| `--trace-pipeline` | | flag | off | Diagnostic mode: includes a trace of each candidate and filtering decision. Debugging only. | 🚧 WIP |
+| `--version` | `-v` | flag | — | Shows version and exits. | ✅ CORE |
+
+---
+
+## Subcommands
+
+### `prepare-context TASK [PATH]`
+
+Generates task-specific context for AI agents.
+
+| Task | Description | Status |
+|------|-------------|--------|
+| `explain` | Architecture, entry points, key dependencies | ✅ CORE |
+| `fix-bug` | Files prioritized by risk, inline annotations | ✅ CORE |
+| `onboard` | Full context for new agents or developers | ✅ CORE |
+| `delta` | Incremental context: only files changed in git | ✅ CORE |
+| `refactor` | Structural problems, improvement opportunities | 🧪 EXP |
+| `generate-tests` | Files without tests, coverage gap analysis | 🧪 EXP |
+| `review-pr` | Changed files + architectural impact | 🧪 EXP |
+
+...

{sourcecode-1.0.0 → sourcecode-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.0.0"
+version = "1.1.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

sourcecode-1.1.0/run_cli.py

@@ -0,0 +1,4 @@
+from sourcecode.cli import main_entry
+
+if __name__ == "__main__":
+    main_entry()

{sourcecode-1.0.0 → sourcecode-1.1.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"