sourcecode 1.32.6__py3-none-any.whl → 1.33.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -155,11 +155,20 @@ def _build_help_text() -> str:
     text = f"""\
 [bold]sourcecode[/bold]  {plan_badge}
 
-Deterministic codebase context for AI coding agents.
+Persistent structural context and ultra-fast repeated analysis for AI coding agents.
+
+Cache warms on first scan; every subsequent call returns pre-built context in milliseconds.
+Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
 
 [bold]Primary usage:[/bold]
-  sourcecode --compact                  high-signal summary (~600-800 tokens)
+  sourcecode --compact                  high-signal summary (~2,500–4,000 tokens)
   sourcecode --compact --git-context    include git hotspots and uncommitted files
+  sourcecode --agent                    full structured JSON for AI agents
+
+[bold]Cache commands:[/bold]
+  cache status                 [dim]# cache size, hit keys, last-warmed timestamp[/dim]
+  cache warm                   [dim]# pre-build cache ahead of an agent session[/dim]
+  cache clear                  [dim]# clear all cached results for this repo[/dim]
 
 [bold]Examples:[/bold]
   sourcecode saint-server --compact
@@ -3753,6 +3762,24 @@ def config_cmd() -> None:
     typer.echo("  sourcecode telemetry status")
 
 
+# ── cold-start (RIS bootstrap for external MCP and agents) ───────────────────
+
+@app.command("cold-start")
+def cold_start_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+) -> None:
+    """Output Repository Intelligence Snapshot bootstrap context as JSON.
+
+    Returns instantly from persisted RIS — zero re-analysis cost.
+    status: cold_start_ready | cold_start_stale | no_ris
+    """
+    import json as _json
+    from sourcecode.ris import get_cold_start_context as _gcs
+    target = Path(path).resolve()
+    result = _gcs(target)
+    typer.echo(_json.dumps(result, indent=2, ensure_ascii=False))
+
+
 # ── analyze (legacy alias) ────────────────────────────────────────────────────
 
 @app.command("analyze", hidden=True)
@@ -4207,11 +4234,13 @@ def cache_warm_cmd(
     agent: bool = typer.Option(False, "--agent", help="Also warm agent view."),
 ) -> None:
     """Pre-populate the cache by running a fresh analysis."""
+    import shutil as _shutil
     import subprocess as _sub
     import sys as _sys
     target = Path(path).resolve()
     typer.echo(f"Warming cache for {target} …", err=True)
-    cmd = [_sys.executable, "-m", "sourcecode", str(target)]
+    _sc_bin = _shutil.which("sourcecode") or _sys.argv[0]
+    cmd = [_sc_bin, str(target)]
     if compact:
         cmd.append("--compact")
     if agent:

sourcecode/prepare_context.py

@@ -734,6 +734,77 @@ class TaskContextBuilder:
     def __init__(self, root: Path) -> None:
         self.root = root
 
+    # ------------------------------------------------------------------
+    # RIS fast-path: serve onboard/explain from warm snapshot (<50ms)
+    # ------------------------------------------------------------------
+
+    def _try_ris_fast_path(self, task_name: str, spec: "TaskSpec") -> Optional[TaskOutput]:
+        """Return TaskOutput from a warm RIS without running the full scan.
+
+        Only activated for onboard/explain when git HEAD matches stored RIS.
+        Falls through (returns None) on any error or cache miss.
+        """
+        try:
+            import subprocess as _sp
+            from sourcecode.ris import load_ris as _lris
+            _ris = _lris(self.root)
+            if _ris is None or not _ris.compact_summary:
+                return None
+            _r = _sp.run(
+                ["git", "-C", str(self.root), "rev-parse", "--short", "HEAD"],
+                capture_output=True, text=True, timeout=2,
+            )
+            if _r.returncode != 0 or _r.stdout.strip() != _ris.git_head:
+                return None
+
+            compact = _ris.compact_summary
+            struct = _ris.structural_map
+
+            entry_points = struct.get("entrypoints") or compact.get("entry_points") or []
+            controllers = struct.get("controllers") or []
+            services = struct.get("services") or []
+
+            _seen: set = set()
+            relevant: list[RelevantFile] = []
+            for fp in entry_points[:10]:
+                if isinstance(fp, str) and fp not in _seen:
+                    _seen.add(fp)
+                    relevant.append(RelevantFile(path=fp, role="entrypoint", score=1.0, reason="entry_point", why="Primary entry point"))
+            for fp in controllers[:8]:
+                if isinstance(fp, str) and fp not in _seen:
+                    _seen.add(fp)
+                    relevant.append(RelevantFile(path=fp, role="source", score=0.9, reason="controller", why="Controller"))
+            for fp in services[:8]:
+                if isinstance(fp, str) and fp not in _seen:
+                    _seen.add(fp)
+                    relevant.append(RelevantFile(path=fp, role="source", score=0.8, reason="service", why="Service layer"))
+
+            # compact_summary uses "analysis_gaps" (list[dict]) not "gaps" (list[str])
+            _raw_gaps = compact.get("gaps") or compact.get("analysis_gaps") or []
+            _gap_strs: list[str] = [
+                g.get("reason", str(g)) if isinstance(g, dict) else str(g)
+                for g in _raw_gaps
+                if g
+            ]
+
+            return TaskOutput(
+                task=task_name,
+                goal=spec.goal,
+                project_summary=compact.get("project_summary") or compact.get("summary"),
+                architecture_summary=compact.get("architecture_summary"),
+                relevant_files=relevant,
+                suspected_areas=[],
+                improvement_opportunities=[],
+                test_gaps=[],
+                key_dependencies=compact.get("key_dependencies") or [],
+                code_notes_summary=None,
+                limitations=[],
+                confidence=compact.get("confidence") or compact.get("confidence_summary") or "high",
+                gaps=_gap_strs,
+            )
+        except Exception:
+            return None
+
     def build(self, task_name: str, *, since: Optional[str] = None, symptom: Optional[str] = None, fast: bool = False, include_config: bool = False, all_gaps: bool = False) -> TaskOutput:
         if task_name not in TASKS:
             raise ValueError(
@@ -741,6 +812,12 @@ class TaskContextBuilder:
             )
         spec = TASKS[task_name]
 
+        # ── RIS fast-path (onboard / explain only) ────────────────────────────
+        if task_name in ("onboard", "explain") and not fast:
+            _warm = self._try_ris_fast_path(task_name, spec)
+            if _warm is not None:
+                return _warm
+
         # ── 0. review-pr: git-first scope resolution (before any filesystem scan) ─
         _pr_git_root: Optional[Path] = None
         _pr_scope_files: Optional[list[str]] = None

sourcecode/ris.py

@@ -362,7 +362,8 @@ def get_cold_start_context(repo_root: Path) -> dict:
         current_head = _current_git_head(repo_root)
         stale = bool(current_head and ris.git_head and current_head != ris.git_head)
 
-        return {
+        endpoints = ris.api_surface.get("endpoints", [])
+        result: dict = {
             "status": "cold_start_stale" if stale else "cold_start_ready",
             "repo_id": ris.repo_id,
             "git_head": ris.git_head,
@@ -370,8 +371,18 @@ def get_cold_start_context(repo_root: Path) -> dict:
             "last_updated_at": ris.last_updated_at,
             "summary": ris.compact_summary,
             "entrypoints": ris.structural_map.get("entrypoints", []),
-            "endpoints": ris.api_surface.get("endpoints", []),
+            "endpoints": endpoints,
             "hotspots": ris.git_context_snapshot.get("hotspots", []),
         }
+        if not endpoints:
+            _is_java = (repo_root / "pom.xml").exists() or \
+                       (repo_root / "build.gradle").exists() or \
+                       (repo_root / "build.gradle.kts").exists()
+            if _is_java:
+                result["endpoints_hint"] = (
+                    "Java repo detected but no endpoint index found. "
+                    "Call get_endpoints (or: sourcecode endpoints <path>) to populate."
+                )
+        return result
     except Exception:
         return {"status": "no_ris"}

sourcecode-1.33.0.dist-info/METADATA

@@ -0,0 +1,437 @@
+Metadata-Version: 2.4
+Name: sourcecode
+Version: 1.33.0
+Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
+License-File: LICENSE
+Keywords: agents,ai,codebase,context,developer-tools,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pathspec>=1.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.24
+Provides-Extra: ast
+Requires-Dist: tree-sitter-javascript>=0.21; extra == 'ast'
+Requires-Dist: tree-sitter-typescript>=0.21; extra == 'ast'
+Requires-Dist: tree-sitter>=0.21; extra == 'ast'
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# sourcecode
+
+**Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
+
+![Version](https://img.shields.io/badge/version-1.33.0-blue)
+![Python](https://img.shields.io/badge/python-3.10%2B-green)
+
+---
+
+## The problem
+
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+
+`sourcecode` solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+
+**The cache is not a performance optimization. It is what makes sourcecode usable as infrastructure rather than a one-off tool.**
+
+---
+
+## Cache performance — measured on real repos
+
+| Repo | Size | Cold scan | Cache hit | Speedup |
+|------|------|-----------|-----------|---------|
+| Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
+| BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
+
+Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+
+**Token output (measured):**
+
+| Mode | BroadleafCommerce | Keycloak |
+|------|------------------|---------|
+| `--compact` | ~2,900 | ~4,000 |
+| `--agent` | ~4,800 | ~5,500 |
+| `onboard` | ~2,600 | n/a |
+| `fix-bug` (trimmed) | ~27,000 | ~4,600 |
+
+---
+
+## What changes at 0.3s vs 2.7s
+
+At 2.7s per call, you use sourcecode to occasionally inspect a repo.
+
+At 0.3s per call, you use sourcecode as **constant infrastructure** inside agent loops:
+
+```
+agent loop iteration:
+  1. sourcecode . --compact          # 0.3s — instant structural context
+  2. sourcecode impact PaymentService . --depth 1   # 0.4s — blast radius check
+  3. agent makes targeted change
+  4. repeat
+```
+
+Sub-second context retrieval changes the cost model for agent workflows. You can call sourcecode before every edit, before every PR review, before every test run — without batching or caching calls manually.
+
+---
+
+## Installation
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap haroundominique/sourcecode
+brew install sourcecode
+```
+
+### pip / pipx
+
+```bash
+pip install sourcecode
+# or with isolation:
+pipx install sourcecode
+```
+
+### Verify
+
+```bash
+sourcecode version
+# sourcecode 1.33.0
+```
+
+---
+
+## Quickstart
+
+```bash
+# High-signal summary — warm cache: ~0.3s, cold: 2–10s depending on repo size
+sourcecode --compact
+
+# Add git hotspots and uncommitted file count
+sourcecode --compact --git-context
+
+# Structured output for AI agents — bounded, noise-free, ready to inject
+sourcecode --agent
+
+# Blast radius: what breaks if this class changes?
+sourcecode impact OrderService /path/to/repo
+
+# REST endpoint surface
+sourcecode endpoints /path/to/repo
+
+# Onboard to an unfamiliar codebase
+sourcecode onboard /path/to/repo
+
+# PR review: risk, test gaps, changed modules
+sourcecode review-pr /path/to/repo --since main
+
+# Bug triage: risk-ranked files by symptom
+sourcecode fix-bug /path/to/repo --symptom "NullPointerException in checkout"
+```
+
+---
+
+## Cache system
+
+sourcecode maintains a persistent cache at `.sourcecode-cache/` inside each repository. Two layers:
+
+- **L1 (core):** analysis result keyed by `(git_sha, analysis_flags)`. Survives format changes — you can regenerate `--compact` vs `--agent` views from the same core.
+- **L2 (view):** rendered output keyed by `(core_hash, view_flags)`. Exact output match — no recomputation.
+
+**Lookup order:** L2 exact hit → L1 hit + view rebuild → full cold scan
+
+**Cache invalidation:** Keyed on git commit SHA. Any commit invalidates the core cache for that repo. Uncommitted changes are not cached.
+
+```bash
+# Inspect cache state
+sourcecode cache status
+
+# Warm the cache ahead of an agent session
+sourcecode cache warm
+
+# Clear cache
+sourcecode cache clear
+```
+
+**`--no-cache`** bypasses both layers and forces a fresh scan. Use in CI or when you need to verify a fresh result.
+
+**Visibility:** Cache hits are silent. Use `sourcecode cache status` to see cache size, hit keys, and last-warmed timestamp.
+
+---
+
+## Agent workflow patterns
+
+### Start of session — structural grounding
+
+```bash
+# Inject as first message to agent (bounded, deterministic)
+sourcecode /repo --compact              # ~2,500–4,000 tokens
+sourcecode /repo --agent               # ~4,500–5,500 tokens — more detail
+sourcecode onboard /repo               # task-structured: entry points, key files, gaps
+```
+
+### Before every change — blast radius check
+
+```bash
+# Always target the INTERFACE in Spring projects, not the implementation:
+sourcecode impact OrderService /repo           # ✓ 30 callers, 11 endpoints
+sourcecode impact OrderServiceImpl /repo       # ✗ 0 callers (Spring DI blindness)
+
+# Large hub interfaces — depth=1 is faster and still the most actionable signal:
+sourcecode impact KeycloakSession /repo --depth 1
+```
+
+### Continuous agent loop — delta context
+
+```bash
+# Only changed files + their transitive importers — minimal token cost:
+sourcecode prepare-context delta /repo --since HEAD~1
+sourcecode . --changed-only --git-context
+```
+
+### PR review — structured risk signal
+
+```bash
+# JSON for programmatic use:
+sourcecode review-pr /repo --since main --output review.json
+jq '.ci_decision' review.json    # "analysis_success" | "git_ref_error"
+
+# Markdown for GitHub comment:
+sourcecode review-pr /repo --since main --format github-comment
+```
+
+### Bug triage — symptom-driven
+
+```bash
+# Specific symptoms produce the best signal:
+sourcecode fix-bug /repo --symptom "OIDC token refresh fails after realm update"
+sourcecode fix-bug /repo --symptom "NullPointerException in OrderService during checkout"
+
+# Generic symptoms produce noisy output — be specific.
+sourcecode fix-bug /repo --symptom "payment timeout" --output triage.json
+```
+
+### In CI — cached, deterministic, fast
+
+```bash
+# Content-hash cached — safe to run on every commit; cold only when code changes
+sourcecode /repo --compact --output context.json
+
+# PR gate
+sourcecode review-pr /repo --since $BASE_REF --output review.json
+DECISION=$(jq -r '.ci_decision' review.json)
+if [ "$DECISION" != "analysis_success" ]; then echo "Review failed: $DECISION"; fi
+```
+
+---
+
+## What sourcecode does (and doesn't)
+
+**sourcecode reduces exploration cost.** It accelerates context acquisition and minimizes repeated repo parsing. It does not replace reading code — it reduces how often an agent needs to.
+
+Specifically:
+
+- Extracts structural signals: entry points, Spring roles, REST surfaces, dependency graphs, transactional boundaries
+- Builds and caches these on first scan; serves from cache on subsequent calls
+- Produces bounded, noise-free JSON designed for direct injection into agent context windows
+- Computes blast radius (impact graph) from a class or interface, traversing reverse dependencies
+
+**What it does NOT do:**
+
+- No runtime analysis — all signals are static (annotation, import graph, file structure)
+- No semantic code understanding — reads structure, not logic
+- No replacement for reading code — reduces how often that's needed, not whether
+- Architecture pattern detection best for Spring MVC layered apps; SPI/plugin architectures (e.g. Quarkus extension model) may be misclassified
+- Endpoint recall for JAX-RS subresource locator pattern is ~65%
+- `impact` on implementation classes (e.g. `OrderServiceImpl`) returns 0 callers in Spring Boot — callers inject the interface via `@Autowired`. Always target the interface. When `direct_callers: []` with `confidence_level: high` for a `@Service` class, re-query the interface.
+- `no_security_signal` on endpoints means no method-level annotations found — does **not** mean the endpoint is unsecured. Projects using Spring Security filter chains show 100% `no_security_signal` even when fully secured.
+
+---
+
+## Command reference
+
+### `--compact` and `--agent`
+
+Core flags. Feed directly to AI agents as first-message context.
+
+| Flag | Output | Tokens |
+|------|--------|--------|
+| `--compact` | High-signal summary: stacks, entry points, dependencies, confidence, gaps | ~2,500–4,000 |
+| `--agent` | Structured JSON: identity, entry points, architecture, event flows | ~4,500–5,500 |
+
+### `impact` — blast-radius analysis
+
+```bash
+sourcecode impact ClassName /path/to/repo
+sourcecode impact org.example.OrderService /path/to/repo   # FQN also accepted
+sourcecode impact OrderService . --depth 2                 # limit BFS depth
+```
+
+| Field | Description |
+|-------|-------------|
+| `direct_callers` | Classes that directly import or inject the target |
+| `indirect_callers` | Transitive callers up to `--depth` (default: 4) |
+| `endpoints_affected` | HTTP endpoints whose call chain includes the target |
+| `transactional_boundaries_touched` | `@Transactional` classes in the blast cone |
+| `mappers_affected` | `@Repository` / `@Mapper` / DAO classes in the blast cone |
+| `security_surface_affected` | Security policies on affected endpoints |
+| `cross_module_impact` | Subsystems touched, ordered by affected symbol count |
+| `risk_score` | 0–100 quantified change risk |
+| `confidence_score` | 0–1 confidence in the analysis |
+| `explanation` | Human-readable risk summary |
+| `candidates` | On partial match: up to 10 FQNs ranked by relevance |
+
+**Best practices:**
+- Target **interfaces**, not implementations: `impact OrderService` > `impact OrderServiceImpl`
+- Use `--depth 1` when target has 200+ callers — direct endpoints are already the most actionable signal
+- Second `impact` run on the same repo is significantly faster (cache applies to underlying IR scan)
+
+### `endpoints` — REST API surface
+
+```bash
+sourcecode endpoints /path/to/repo
+sourcecode endpoints /path/to/repo --output endpoints.json
+```
+
+Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.) and JAX-RS (`@GET`, `@POST`, `@Path`) endpoint methods. Returns HTTP method, path, controller class, and handler method.
+
+### `repo-ir` — symbol-level IR
+
+```bash
+sourcecode repo-ir /path/to/repo --summary-only          # ~20K tokens
+sourcecode repo-ir /path/to/repo --since HEAD~1           # symbol-level diff
+sourcecode repo-ir /path/to/repo --files src/.../OrderService.java
+```
+
+Builds a deterministic symbol graph: classes, methods, import/injection edges, Spring roles, subsystems.
+
+**Size warning:** Without `--summary-only`, output can exceed 1MB for mid-size repos. Always use `--summary-only` unless you need the full graph for downstream tooling.
+
+### `onboard` — codebase orientation
+
+```bash
+sourcecode onboard /path/to/repo
+```
+
+Entry points, architecture summary, key files, confidence level, and gaps. Designed to be injected as agent context at the start of a session.
+
+### `review-pr` — [Pro] PR review context
+
+```bash
+sourcecode review-pr /path/to/repo --since main
+sourcecode review-pr /path/to/repo --since HEAD~3
+```
+
+Changed files, risk ranking, test coverage gaps, affected modules, and blast radius of changed classes. Returns a `ci_decision` field for CI/CD integration.
+
+### `fix-bug` — [Pro] Bug triage context
+
+```bash
+sourcecode fix-bug /path/to/repo --symptom "NullPointerException in checkout"
+```
+
+Risk-ranked file list correlated to the symptom: keyword extraction, path matching, content matching, git commit correlation.
+
+### `modernize` — [Pro] Modernization planning
+
+```bash
+sourcecode modernize /path/to/repo
+```
+
+High-coupling nodes (high fan-in = risky to change), dead zone candidates (isolated symbols), subsystem tangles.
+
+### `prepare-context` — task-specific context
+
+Low-level access to all tasks with full options:
+
+```bash
+sourcecode prepare-context TASK [PATH] [OPTIONS]
+```
+
+| Task | What it surfaces |
+|------|-----------------|
+| `explain` | Architecture, entry points, key dependencies |
+| `onboard` | Full structural context for new agents/developers |
+| `fix-bug` | Files ranked by symptom correlation, risk, annotations |
+| `refactor` | Structural issues, improvement opportunities |
+| `generate-tests` | Source files without test pairs, coverage gap analysis |
+| `review-pr` | PR diff with risk ranking, test gaps, module impact |
+| `delta` | Incremental context: git-changed files + transitive import graph |
+
+---
+
+## Flags reference
+
+| Flag | Alias | Default | Description |
+|------|-------|---------|-------------|
+| `--compact` | | off | High-signal summary (typically 2,500–4,000 tokens for mid-to-large Java repos): stacks, entry points, dependencies, confidence, gaps. |
+| `--agent` | | off | Structured JSON for AI agents: project identity, entry points, architecture, dependencies, confidence. ~4,500–5,500 tokens. |
+| `--full` | | off | Remove truncation limits on `transactional_boundaries`, `mybatis.dto_mappers`, and other capped lists. |
+| `--git-context` | `-g` | off | Include git activity: recent commits, change hotspots, and uncommitted file count. |
+| `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). |
+| `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
+| `--format` | `-f` | `json` | Output format: `json` or `yaml`. |
+| `--output` | `-o` | stdout | Write output to a file instead of stdout. |
+| `--no-cache` | | off | Bypass scan cache and force a fresh analysis. |
+| `--copy` | `-c` | off | Copy output to clipboard after a successful run. |
+| `--no-redact` | | off | Disable automatic secret redaction. |
+| `--version` | `-v` | — | Show version and exit. |
+
+---
+
+## Output schema
+
+All outputs include:
+- `schema_version`: output format version
+- `confidence_summary`: `overall`, `stack`, `entry_points` confidence levels (`high`/`medium`/`low`)
+- `analysis_gaps`: list of what could not be analyzed and why
+
+### Java/Spring-specific fields (when detected)
+
+| Field | Description |
+|-------|-------------|
+| `language_version` | Java version from `maven.compiler.source` or equivalent |
+| `deployment.spring_boot_version` | Spring Boot version |
+| `deployment.packaging` | `jar` or `war` |
+| `mybatis` | Mapper interface / XML file pairing summary |
+| `transactional_boundaries` | Classes annotated with `@Transactional` |
+| `deployment_risks` | Static risk flags: `spring-boot-2.x-eol`, `legacy-java-runtime` |
+
+---
+
+## Telemetry
+
+Anonymous, opt-in. Collects: version, OS, commands, flags, duration, repo size range, errors. No source code, paths, secrets, or output content.
+
+```bash
+sourcecode telemetry status
+sourcecode telemetry enable
+sourcecode telemetry disable
+```
+
+Or: `export SOURCECODE_TELEMETRY=0`
+
+---
+
+## Configuration
+
+```bash
+sourcecode config    # show version, config file path, telemetry status
+```

{sourcecode-1.32.6.dist-info → sourcecode-1.33.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=KgyhBn2jfjwXzdBpdStMZoNfqCUlHHAwk1wuU3Nez1M,103
+sourcecode/__init__.py,sha256=Fk3-VcGm9_CNfTjflFer8o6KMnle3o1Zvum4r66pj4E,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=qh749a7ykPtGmQI1MR9y6j8TtL_jBdVYFx9YRsLqOMw,44121
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -7,7 +7,7 @@ sourcecode/cache.py,sha256=h1BT-9PG_7HK---ZzH0j5u3PN0dz2s6IRAUOjQIPYH4,28055
 sourcecode/cache.tmp_new,sha256=-IvV7CojiZjqeKMln1m-lqI0QVA2uFGWmYir4XRFOUk,27970
 sourcecode/canonical_ir.py,sha256=_HM3AUmKSdna9u4dCoU6rpgSA6HdF8gzOKZykIUCNGY,23277
 sourcecode/classifier.py,sha256=2lYoSH3vOTkXZYPU7Go2WIet1-IuNzTWVhc-ULnXtgw,8024
-sourcecode/cli.py,sha256=PJbs8ltIdsBmedJlBJ6HG9UCRBLDtUhG_eIqyazP_sU,170992
+sourcecode/cli.py,sha256=fIY-kaSbQ_YilCwR9jqsm8n2_kMfyYrHrudee6KQaQE,172312
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -29,14 +29,14 @@ sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7
 sourcecode/output_budget.py,sha256=43307mJEyUPU3MI-QEQoVxrcAvNyUzdzF_SAPgisBQE,6603
 sourcecode/path_filters.py,sha256=ROFRQ8eSLBEMiixK9f45-RO7um4VEEcjoD5AA4I427I,3739
 sourcecode/pr_comment_renderer.py,sha256=smHslxiG14lrytCkq5nFrFu-qTHgA-t-LFYfdrfjz2o,14423
-sourcecode/prepare_context.py,sha256=TFg8GDJ8kotJtR4rOTAvwQGVNSj0x-Usamy-mtjxeqs,201681
+sourcecode/prepare_context.py,sha256=uZo0r7QBXUmQdfTp3w_A1XI-OzFAlcoH7F76_p7IQjo,205311
 sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=ZAucq_YX2KkWUuAZf4P0lhtQ_38vEFnUhuGtSZd1S0E,12970
 sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=MYF4FFkveAQps9SmTeTlh6ODiBz2F--_hWNeHMLtUHQ,8405
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
 sourcecode/repository_ir.py,sha256=-NjBQUT7zyya4ng8Hq0-ChoiHZkUif9lr-Q878gmj8M,153163
-sourcecode/ris.py,sha256=CqNfiIbzfHZQZx0mWLjyVD4o8u5ZLnbv3Ia7D7gYhQY,14212
+sourcecode/ris.py,sha256=2pQcNN-5akweoBjjWAk_x3QpJ06wukQInmMlMj7WxwI,14737
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
@@ -80,8 +80,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-1.32.6.dist-info/METADATA,sha256=Aa7pmdWB0T8LkQYd6rihJOQQwE1Ts_nJ7AHUyYT2gF0,19120
-sourcecode-1.32.6.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.32.6.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.32.6.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.32.6.dist-info/RECORD,,
+sourcecode-1.33.0.dist-info/METADATA,sha256=2Xbq33fdfqhc4P5EfadeJgzSkGCcJ-c1DdZJiwiGch8,16440
+sourcecode-1.33.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.33.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.33.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.33.0.dist-info/RECORD,,

sourcecode-1.32.6.dist-info/METADATA

@@ -1,456 +0,0 @@
-Metadata-Version: 2.4
-Name: sourcecode
-Version: 1.32.6
-Summary: Deterministic codebase context for AI coding agents
-License-File: LICENSE
-Keywords: agents,ai,codebase,context,developer-tools,llm
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Utilities
-Requires-Python: >=3.9
-Requires-Dist: mcp>=1.0.0
-Requires-Dist: pathspec>=1.0
-Requires-Dist: ruamel-yaml>=0.18
-Requires-Dist: tomli>=2.0; python_version < '3.11'
-Requires-Dist: typer>=0.24
-Provides-Extra: ast
-Requires-Dist: tree-sitter-javascript>=0.21; extra == 'ast'
-Requires-Dist: tree-sitter-typescript>=0.21; extra == 'ast'
-Requires-Dist: tree-sitter>=0.21; extra == 'ast'
-Provides-Extra: dev
-Requires-Dist: mcp>=1.0.0; extra == 'dev'
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest>=8; extra == 'dev'
-Requires-Dist: ruff>=0.15; extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Description-Content-Type: text/markdown
-
-# sourcecode
-
-**AI-ready change intelligence for Java/Spring enterprise monoliths.**
-
-![Version](https://img.shields.io/badge/version-1.32.0-blue)
-![Python](https://img.shields.io/badge/python-3.10%2B-green)
-
----
-
-## What is it?
-
-`sourcecode` analyzes a Java/Spring repository and produces structured JSON designed to be fed directly to AI agents or used in CI/CD pipelines. It solves two hard problems:
-
-**1. "What breaks if I change X?"** — `sourcecode impact ClassName /repo` traverses the reverse dependency graph and returns every HTTP endpoint, transactional boundary, and downstream module affected by a change. In seconds, not hours.
-
-**2. "What does this codebase do before I touch it?"** — `sourcecode onboard /repo` produces a bounded, AI-ready context bundle: entry points, architecture, key files, confidence, and gaps. Feed it directly to Claude/GPT-4 as a system prompt.
-
-**Optimized for:** Spring Boot / Spring MVC monoliths. Works with JAX-RS (Quarkus, Jersey) at ~65% endpoint recall. Works on any codebase for stack detection and onboarding context.
-
----
-
-## Installation
-
-### Homebrew (macOS / Linux)
-
-```bash
-brew tap haroundominique/sourcecode
-brew install sourcecode
-```
-
-### pip / pipx
-
-```bash
-pip install sourcecode
-# or with isolation:
-pipx install sourcecode
-```
-
-### Verify
-
-```bash
-sourcecode version
-# sourcecode 1.32.0
-```
-
----
-
-## Quickstart
-
-```bash
-# High-signal summary (typically 2000–4000 tokens depending on repo size)
-sourcecode --compact
-
-# Add git hotspots and uncommitted file count
-sourcecode --compact --git-context
-
-# Structured output for AI agents — bounded, noise-free, ready to inject
-sourcecode --agent
-
-# Blast radius: what breaks if this class changes?
-sourcecode impact OrderService /path/to/repo
-
-# REST endpoint surface
-sourcecode endpoints /path/to/repo
-
-# Onboard to an unfamiliar codebase
-sourcecode onboard /path/to/repo
-
-# PR review: risk, test gaps, changed modules
-sourcecode review-pr /path/to/repo --since main
-
-# Bug triage: risk-ranked files by symptom
-sourcecode fix-bug /path/to/repo --symptom "NullPointerException in checkout"
-```
-
----
-
-## Real-world benchmarks
-
-Measured against open-source enterprise Java repos:
-
-| Repo | Java files | Cold scan (`--compact`) | Cache hit | Cache speedup | Endpoints found |
-|------|-----------|------------------------|-----------|---------------|----------------|
-| BroadleafCommerce | 2,985 | 2.9s | 0.20s | ~13x | 130 |
-| Keycloak | 7,885 | 9.0s | 0.27s | ~33x | 693 |
-
-The cache is keyed on file content hashes — invalidated only when source changes. Speedup varies by repo size and OS I/O.
-
-**Token sizes (measured):**
-
-| Mode | BroadleafCommerce | Keycloak |
-|------|------------------|---------|
-| `--compact` | ~2,900 | ~4,000 |
-| `--agent` | ~4,800 | ~5,500 |
-| `onboard` | ~2,600 | n/a |
-| `fix-bug` (trimmed) | ~27,000 | ~4,600 |
-
-**`impact` on high-fan-in classes:**  
-For hub interfaces (1000+ direct dependents), use `--depth 1` — direct endpoints are already the most actionable signal. Depth=4 on very large repos may take 90+ seconds.
-
----
-
-## Flags reference
-
-| Flag | Alias | Default | Description |
-|------|-------|---------|-------------|
-| `--compact` | | off | High-signal summary (typically 2,500–4,000 tokens for mid-to-large Java repos): stacks, entry points, dependencies, confidence, gaps. Includes `transactional_boundaries` for Spring projects. |
-| `--agent` | | off | Structured JSON for AI agents: project identity, entry points, architecture, dependencies, confidence. More detail than `--compact`. ~4500–5500 tokens. |
-| `--full` | | off | Remove truncation limits on `transactional_boundaries`, `mybatis.dto_mappers`, and other capped lists. |
-| `--git-context` | `-g` | off | Include git activity: recent commits, change hotspots, and uncommitted file count. |
-| `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). |
-| `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
-| `--format` | `-f` | `json` | Output format: `json` or `yaml`. |
-| `--output` | `-o` | stdout | Write output to a file instead of stdout. |
-| `--no-cache` | | off | Bypass scan cache and force a fresh analysis. |
-| `--copy` | `-c` | off | Copy output to clipboard after a successful run. |
-| `--no-redact` | | off | Disable automatic secret redaction. |
-| `--version` | `-v` | — | Show version and exit. |
-
----
-
-## `impact` — Blast-radius analysis
-
-**Who calls this class, and what breaks if it changes?**
-
-```bash
-sourcecode impact ClassName /path/to/repo
-sourcecode impact org.example.OrderService /path/to/repo   # FQN also accepted
-sourcecode impact OrderService . --depth 2                 # limit BFS depth
-```
-
-**Output fields:**
-
-| Field | Description |
-|-------|-------------|
-| `direct_callers` | Classes that directly import or inject the target |
-| `indirect_callers` | Transitive callers up to `--depth` (default: 4) |
-| `endpoints_affected` | HTTP endpoints whose call chain includes the target |
-| `transactional_boundaries_touched` | `@Transactional` classes in the blast cone |
-| `mappers_affected` | `@Repository` / `@Mapper` / DAO classes in the blast cone |
-| `security_surface_affected` | Security policies on affected endpoints |
-| `cross_module_impact` | Subsystems touched, ordered by affected symbol count |
-| `risk_score` | 0–100 quantified change risk |
-| `confidence_score` | 0–1 confidence in the analysis |
-| `explanation` | Human-readable risk summary |
-| `candidates` | On partial match: up to 10 FQNs ranked by relevance |
-
-**Best practices:**
-- Target **interfaces**, not implementations: `impact OrderService` > `impact OrderServiceImpl`. In Spring projects, callers inject the interface via `@Autowired` — the impl has zero direct callers in the graph even though it runs all the code. Querying the impl returns `direct_callers: []` with no error; querying the interface returns the real blast radius.
-- Use `--depth 1` when the target has 200+ callers — direct endpoints are already the most actionable signal.
-- The cache applies to the underlying IR scan — second `impact` run on the same repo is significantly faster.
-- When you get `direct_callers: 0` for a `@Service` or `@Repository` class, that is almost certainly the interface-injection pattern. Re-run with the interface name.
-
-**Supported targets:**
-- Simple class name: `OrderService`
-- Fully-qualified name: `org.broadleafcommerce.core.order.service.OrderService`
-- File path: `src/main/java/.../OrderService.java`
-
----
-
-## `endpoints` — REST API surface
-
-```bash
-sourcecode endpoints /path/to/repo
-sourcecode endpoints /path/to/repo --output endpoints.json
-```
-
-Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.) and JAX-RS (`@GET`, `@POST`, `@Path`) endpoint methods. Returns HTTP method, path, controller class, and handler method.
-
-**Scope limitations:**
-- JAX-RS subresource locators (endpoints mounted dynamically without class-level `@Path`) are not counted as standalone endpoints — they appear in `impact` output when transitively reached.
-- Security context on endpoints reflects method-level annotations (`@PreAuthorize`, `@Secured`). Class-level or programmatic security shows as `no_security_signal`.
-
----
-
-## `repo-ir` — Symbol-level IR
-
-```bash
-sourcecode repo-ir /path/to/repo --summary-only          # recommended: analysis + impact, no full graph (~20K tokens)
-sourcecode repo-ir /path/to/repo --since HEAD~1           # symbol-level diff
-sourcecode repo-ir /path/to/repo --files src/.../OrderService.java   # single-file IR
-sourcecode repo-ir /path/to/repo --max-nodes 200 --max-edges 500     # limits forward graph only — see note below
-```
-
-Builds a deterministic symbol graph: classes, methods, import/injection edges, Spring roles, subsystems. Output is JSON with `graph`, `reverse_graph`, `impact`, `subsystems`, and `route_surface`.
-
-**Size warning:** Without `--summary-only`, output can exceed 1MB for mid-size repos. `--max-nodes`/`--max-edges` limit the forward `graph` section only — the `reverse_graph` section is not bounded by these flags and is the largest component. Always use `--summary-only` unless you need the full graph for downstream tooling.
-
----
-
-## `onboard` — [OSS Core] Codebase orientation
-
-```bash
-sourcecode onboard /path/to/repo
-```
-
-Entry points, architecture summary, key files, confidence level, and gaps. Designed to be injected as AI agent context at the start of a session.
-
----
-
-## `review-pr` — [Pro] PR review context
-
-```bash
-sourcecode review-pr /path/to/repo --since main
-sourcecode review-pr /path/to/repo --since HEAD~3
-```
-
-Changed files, risk ranking, test coverage gaps, affected modules, and blast radius of changed classes. Returns a structured `ci_decision` field for CI/CD integration.
-
-**Test coverage note:** Coverage gaps are detected by stem matching (e.g. `OrderService.java` ↔ `OrderServiceTest.java`). Tests in the same diff are counted.
-
----
-
-## `fix-bug` — [Pro] Bug triage context
-
-```bash
-sourcecode fix-bug /path/to/repo --symptom "NullPointerException in checkout"
-```
-
-Risk-ranked file list correlated to the symptom: keyword extraction, path matching, content matching, and git commit correlation. Output includes `symptom_explain` with the full evidence chain.
-
----
-
-## `modernize` — [Pro] Modernization planning
-
-```bash
-sourcecode modernize /path/to/repo
-```
-
-Identifies high-coupling nodes (high fan-in = risky to change), dead zone candidates (isolated symbols), and subsystem tangles. 
-
-**Interpreting output:** `hotspot_candidates` is a subset of `high_coupling_nodes` filtered to service/repository/controller roles. In annotation-heavy codebases, the highest-coupled nodes are often annotation types or JPA entities — check `high_coupling_nodes` directly for the full coupling picture.
-
----
-
-## `prepare-context` — Task-specific context
-
-Low-level access to all tasks with full options:
-
-```bash
-sourcecode prepare-context TASK [PATH] [OPTIONS]
-```
-
-| Task | What it surfaces |
-|------|-----------------|
-| `explain` | Architecture, entry points, key dependencies |
-| `onboard` | Full structural context for new agents/developers |
-| `fix-bug` | Files ranked by symptom correlation, risk, annotations |
-| `refactor` | Structural issues, improvement opportunities |
-| `generate-tests` | Source files without test pairs, coverage gap analysis |
-| `review-pr` | PR diff with risk ranking, test gaps, module impact |
-| `delta` | Incremental context: git-changed files + transitive import graph |
-
-```bash
-sourcecode prepare-context fix-bug --symptom "NullPointerException in OrderService"
-sourcecode prepare-context review-pr --since main --format github-comment
-sourcecode prepare-context onboard --llm-prompt
-sourcecode prepare-context --task-help    # list all tasks
-```
-
-Note: `sourcecode onboard`, `sourcecode fix-bug`, `sourcecode review-pr`, and `sourcecode modernize` are shorthand aliases for the corresponding `prepare-context` tasks — output is identical.
-
----
-
-## How to use sourcecode effectively
-
-### Onboarding — new repo, new agent session
-
-```bash
-# Bounded context at session start (~2,500–5,500 tokens)
-sourcecode /repo --compact              # fast overview
-sourcecode /repo --agent               # more detail: file relevance, architecture, event flows
-sourcecode onboard /repo               # task-structured: entry points, key files, gaps
-```
-
-Use `--compact` or `--agent` as first-prompt injection for AI coding agents. Both are bounded and deterministic.
-
-### Impact analysis — before touching a class
-
-```bash
-# Always target the INTERFACE in Spring projects:
-sourcecode impact OrderService /repo           # ✓ correct: 30 callers, 11 endpoints
-sourcecode impact OrderServiceImpl /repo       # ✗ wrong: 0 callers (Spring DI blindness)
-
-# Large hub interfaces — depth=1 is faster and still actionable:
-sourcecode impact KeycloakSession /repo --depth 1
-
-# If you get direct_callers:[] for a @Service class, re-query the interface.
-```
-
-### Bug triage — symptom-driven
-
-```bash
-# Specific symptoms produce the best signal:
-sourcecode fix-bug /repo --symptom "OIDC token refresh fails after realm update"
-sourcecode fix-bug /repo --symptom "NullPointerException in OrderService during checkout"
-
-# Generic symptoms produce noisy output (100s of files) — be specific.
-# Use --output to capture full output without budget truncation.
-sourcecode fix-bug /repo --symptom "payment timeout" --output triage.json
-```
-
-### PR review
-
-```bash
-# JSON for programmatic use:
-sourcecode review-pr /repo --since main --output review.json
-jq '.ci_decision' review.json    # "analysis_success" | "git_ref_error"
-
-# Markdown for GitHub comment:
-sourcecode review-pr /repo --since main --format github-comment
-
-# CI/CD gate — parse risk and test coverage fields:
-jq '{ci_decision, test_coverage_risk, impact_summary}' review.json
-```
-
-### Modernization planning
-
-```bash
-sourcecode modernize /repo
-# high_coupling_nodes: classes most risky to change (by fan-in degree)
-# dead_zone_candidates: classes with zero callers — safe to remove or refactor
-# Note: hotspot_candidates may be empty in annotation-heavy codebases —
-#       check high_coupling_nodes directly for coupling signal.
-```
-
-### Symbol IR for downstream tooling
-
-```bash
-# Always use --summary-only unless you need the full graph:
-sourcecode repo-ir /repo --summary-only --output ir.json   # ~20K tokens
-sourcecode repo-ir /repo --since HEAD~3 --summary-only     # changed symbols only
-
-# Full graph warning: output can exceed 1MB for mid-size repos.
-# --max-nodes/--max-edges only limit the forward graph, not reverse_graph.
-```
-
-### With AI agents (Claude, GPT-4, etc.)
-
-```bash
-# Start agent session with bounded context:
-sourcecode /repo --agent --output context.json && cat context.json | agent-cli
-
-# For a specific change task, combine context + impact:
-sourcecode /repo --compact > context.json
-sourcecode impact PaymentService /repo --depth 1 >> impact.json
-# Feed both to agent: "Given this context and impact, what are the risks of changing PaymentService?"
-
-# For PR review:
-sourcecode review-pr /repo --since main --format github-comment
-# Paste directly into GitHub PR description or feed to agent
-```
-
-### In CI/CD pipelines
-
-```bash
-# Deterministic, content-hash cached — safe to run on every commit
-sourcecode /repo --compact --no-cache --output context.json
-
-# PR gate
-sourcecode review-pr /repo --since $BASE_REF --output review.json
-DECISION=$(jq -r '.ci_decision' review.json)
-if [ "$DECISION" != "analysis_success" ]; then echo "Review failed: $DECISION"; fi
-```
-
----
-
-## What sourcecode does NOT do
-
-- No runtime analysis — all signals are static (annotation, import graph, file structure)
-- No semantic code understanding — it reads structure, not logic
-- Architecture pattern detection works best for Spring MVC layered apps; SPI/plugin architectures (e.g. Quarkus extension model) are classified as "layered" which may be inaccurate
-- Endpoint recall for JAX-RS subresource locator pattern is ~65% — endpoints mounted dynamically via factory methods are not individually counted. JAX-RS sub-resource paths (method-level `@Path` inside a `@Path`-annotated class) are extracted as relative paths, not the fully composed URL.
-- `impact` on implementation classes (e.g. `OrderServiceImpl`) reflects callers of the implementation specifically — **in Spring Boot projects this is almost always zero**, because callers inject the interface via `@Autowired`. Always target the interface (`OrderService`) to get the real blast radius. The tool does not auto-resolve impl → interface. When `direct_callers: []` is returned with `confidence_level: high` for a `@Service` class, treat it as a prompt to re-query the interface.
-- `no_security_signal` on endpoints means no method-level security annotations (`@PreAuthorize`, `@Secured`) were found — it does **not** mean the endpoint is unsecured. Projects using Spring Security filter chains, XML security config, or custom filters will show 100% `no_security_signal` even when fully secured.
-- `hotspot_candidates` in `modernize` output reflects graph coupling, not git churn — in annotation-heavy codebases it is often empty even though real hotspots exist. Check `high_coupling_nodes` directly for the coupling picture.
-- `project_summary` is extracted from the repository README — it may reflect marketing language rather than architectural description
-
----
-
-## Output schema
-
-All outputs include:
-- `schema_version`: output format version
-- `confidence_summary`: `overall`, `stack`, `entry_points` confidence levels (`high`/`medium`/`low`)
-- `analysis_gaps`: list of what could not be analyzed and why
-
-### Java/Spring-specific fields (when detected)
-
-| Field | Description |
-|-------|-------------|
-| `language_version` | Java version from `maven.compiler.source` or equivalent |
-| `deployment.spring_boot_version` | Spring Boot version |
-| `deployment.packaging` | `jar` or `war` |
-| `mybatis` | Mapper interface / XML file pairing summary |
-| `transactional_boundaries` | Classes annotated with `@Transactional` |
-| `deployment_risks` | Static risk flags: `spring-boot-2.x-eol`, `legacy-java-runtime` |
-
----
-
-## Telemetry
-
-Anonymous, opt-in. Collects: version, OS, commands, flags, duration, repo size range, errors. No source code, paths, secrets, or output content.
-
-```bash
-sourcecode telemetry status
-sourcecode telemetry enable
-sourcecode telemetry disable
-```
-
-Or: `export SOURCECODE_TELEMETRY=0`
-
----
-
-## Configuration
-
-```bash
-sourcecode config    # show version, config file path, telemetry status
-```