sourcecode 1.31.29__tar.gz → 1.31.30__tar.gz

sourcecode-1.31.30/.continue-here.md

@@ -0,0 +1,89 @@
+# Handoff — Sesión 34 (2026-05-26)
+
+## Position
+
+**Project:** sourcecode (atlas-cli)  
+**Activity:** Post-audit bug fixing + new feature (MCP nudge)  
+**Branch:** master  
+**Last commit:** 11d23b0 — feat(mcp): add one-time MCP setup nudge after successful commands  
+**Tests:** 1601 passed, 3 skipped ✅
+
+---
+
+## Work Done This Session
+
+### Session 34 (this session)
+**New feature: one-time MCP setup nudge**
+
+**FEAT — `sourcecode mcp_nudge.py` (new module)**
+- `nudge_mcp_if_needed()`: fires after first successful analysis command when Claude Desktop/Cursor installed but sourcecode not yet in MCP config. Writes to stderr only. Creates `~/.sourcecode/nudge_shown` flag to fire at most once per session.
+- `clear_nudge_flag()`: called by `mcp init` on success — next run finds `is_installed=True` → no nudge.
+- Module-level imports for testability; `_IMPORTS_OK=False` stubs if onboarding package missing.
+
+**CLI hooks (4 call sites in `cli.py`):**
+| Command | Location |
+|---|---|
+| `sourcecode . --compact` | `main()` — after clipboard copy |
+| `sourcecode prepare-context` / `onboard` | `prepare_context_cmd()` — end |
+| `sourcecode endpoints` | `endpoints_cmd()` — end |
+| `sourcecode impact` | `impact_cmd()` — success path only (after not_found check) |
+
+**`mcp init` success** → `clear_nudge_flag()` called.
+
+**Tests:** `tests/test_mcp_nudge.py` — 11 tests, all pass.
+
+---
+
+## Remaining from Bug Audit Backlog
+
+### P1 backlog
+| # | Issue | File | Effort |
+|---|---|---|---|
+| P1-5 | `project_summary` quality — picks license/badges/marketing blurbs | `summarizer.py` | Medium |
+| P1-6 | `relevant_files.score` ranking quality audit (score exposed, ranking weak) | `ranking_engine.py` | Medium |
+
+### P2 unfixed
+| # | Issue | File | Effort |
+|---|---|---|---|
+| P2-13 | `--no-cache` flag inconsistent across subcommands | `cli.py` | Medium |
+| P2-14 | URLs in code_notes truncated (needs repro) | `code_notes_analyzer.py` | Low |
+| P2-16 | `entry_points.controllers.methods` mismatches `endpoints` count | `cli.py` | Medium |
+| P2-17 | `--compact --help` token claim stale (now runs arch analyzer too) | `cli.py` | Trivial |
+| P2-18 | `impact <file_path>` fails FQN resolution | `repository_ir.py` | Low |
+
+---
+
+## Key Files Modified (this session)
+
+```
+src/sourcecode/mcp_nudge.py         — NEW: nudge_mcp_if_needed, clear_nudge_flag
+src/sourcecode/cli.py               — 4 nudge call sites + clear_nudge_flag in mcp_init
+tests/test_mcp_nudge.py             — NEW: 11 tests
+```
+
+---
+
+## Decisions This Session
+
+| Decision | Rationale |
+|---|---|
+| Module-level imports in mcp_nudge.py (not lazy) | Enables `patch("sourcecode.mcp_nudge.detect_clients", ...)` in tests |
+| Flag at `~/.sourcecode/nudge_shown` | Reuses existing state root; simple touch file |
+| Nudge on impact only when resolution != not_found | not_found = exit 1 = failure; no nudge on failed commands |
+| `clear_nudge_flag()` in mcp_init success, not in detection | Separation: flag reset is explicit intent (user ran init), not a side effect of checking |
+
+---
+
+## Next Session
+
+**Recommended:** P2-17 (trivial) → P2-18 (low) → P2-14 (low, needs repro) → P1-5 (medium) → P1-6 (medium) → P2-13 (medium) → P2-16 (medium)
+
+**P2-17:** `--compact --help` says token count — verify claim still accurate after P2-10 fix (compact now runs ArchitectureAnalyzer). Update if stale.
+
+**P2-18:** `sourcecode impact <file_path>` — resolve file path to FQN before IR lookup. Currently passes raw path to `_resolve_target()`, fails to match.
+
+**P1-5:** Audit `summarizer.py`. Prefer: first real descriptive paragraph, architecture description, domain/stack. Exclude: 'Important:', license, badges, install snippets, TOC, link collections, sponsorship, release notes.
+
+**Resume command:** `/gsd:resume-work`
+
+**Test baseline:** `python3 -m pytest tests/ → 1601 passed, 3 skipped`

{sourcecode-1.31.29 → sourcecode-1.31.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.29
+Version: 1.31.30
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.29-blue)
+![Version](https://img.shields.io/badge/version-1.31.30-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -263,7 +263,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.29
+# sourcecode 1.31.30
 ```
 
 ---

{sourcecode-1.31.29 → sourcecode-1.31.30}/README.md

@@ -2,7 +2,7 @@
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.29-blue)
+![Version](https://img.shields.io/badge/version-1.31.30-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -40,7 +40,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.29
+# sourcecode 1.31.30
 ```
 
 ---

{sourcecode-1.31.29 → sourcecode-1.31.30}/pyproject.toml

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

{sourcecode-1.31.29 → sourcecode-1.31.30}/src/sourcecode/__init__.py

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

{sourcecode-1.31.29 → sourcecode-1.31.30}/src/sourcecode/cli.py

@@ -760,8 +760,11 @@ def main(
             err=True,
         )
 
-    # P0-2 FIX: --changed-only silently implies --compact; inform the user.
-    if changed_only and not compact and not agent:
+    # P1-2 FIX: --changed-only silently implies --compact; inform only on TTY.
+    # PowerShell 5.1 interprets any stderr write (even with exit 0) as NativeCommandError.
+    # Gate on isatty() so pipeline consumers never see informational noise on stderr.
+    import sys as _sys_tty
+    if changed_only and not compact and not agent and _sys_tty.stderr.isatty():
         typer.echo(
             "[info] --changed-only implies --compact (bounding output to changed files).",
             err=True,
@@ -2184,7 +2187,11 @@ def prepare_context_cmd(
 
     target = path.resolve()
     if not target.exists() or not target.is_dir():
-        typer.echo(f"Error: '{target}' is not a valid directory.", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+        )
         raise typer.Exit(code=1)
 
     if dry_run:
@@ -2316,6 +2323,13 @@ def prepare_context_cmd(
         out["improvement_opportunities"] = output.improvement_opportunities
     if _task_include("test_gaps") and output.test_gaps:
         out["test_gaps"] = output.test_gaps
+    # P0-2: fast-mode truncation transparency — always emit when truncated, even if test_gaps is []
+    # Use `is True` (strict) so MagicMock objects in tests don't trigger this branch.
+    if getattr(output, "truncated", False) is True:
+        out["truncated"] = True
+        _tr = getattr(output, "truncated_reason", None)
+        if isinstance(_tr, str) and _tr:
+            out["truncated_reason"] = _tr
     if _task_include("code_notes_summary") and output.code_notes_summary:
         out["code_notes_summary"] = output.code_notes_summary
     if _task_include("changed_files") and output.changed_files:
@@ -2704,7 +2718,11 @@ def repo_ir_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     if files:
@@ -2856,7 +2874,11 @@ def impact_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     file_list = find_java_files(root)
@@ -2959,7 +2981,11 @@ def endpoints_cmd(
 
     target = path.resolve()
     if not target.exists() or not target.is_dir():
-        typer.echo(f"Error: '{target}' is not a valid directory.", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+        )
         raise typer.Exit(code=1)
 
     data = _extract_java_endpoints(target)
@@ -3075,7 +3101,10 @@ def review_pr_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] PR review: blast radius, risk ranking, execution paths, security/txn impact.
+    """[Pro*] PR review: blast radius, risk ranking, execution paths, security/txn impact.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "What does this PR break and how risky is it?"
@@ -3135,7 +3164,10 @@ def fix_bug_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] Bug triage: risk-ranked files, suspected areas, related annotations.
+    """[Pro*] Bug triage: risk-ranked files, suspected areas, related annotations.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "Where in this codebase should I look to fix this symptom?"
@@ -3187,7 +3219,10 @@ def modernize_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] Modernization planning: coupling, dead zones, risky modules, refactor candidates.
+    """[Pro*] Modernization planning: coupling, dead zones, risky modules, refactor candidates.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "Where should I refactor first, and what's safest to touch?"
@@ -3218,7 +3253,11 @@ def modernize_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     file_list = find_java_files(root)
@@ -3443,6 +3482,24 @@ def mcp_serve() -> None:
     from sourcecode.mcp.server import mcp as _mcp
 
     log = logging.getLogger(__name__)
+
+    # P0-1: Strip UTF-8 BOM from stdin.buffer before the MCP server reads it.
+    # PowerShell 5.1 on Windows writes \xEF\xBB\xBF at the start of stdin,
+    # which breaks JSON parsing at line 1 column 1.
+    # peek(3) loads bytes into BufferedReader's internal buffer without consuming;
+    # read(3) discards only if the prefix is the UTF-8 BOM sequence.
+    # No-op on Linux/macOS/Git Bash where stdin never starts with a BOM.
+    # Guard: CliRunner / test stubs replace sys.stdin with StringIO (no .buffer).
+    try:
+        _stdin_buf = getattr(_sys.stdin, "buffer", None)
+        if _stdin_buf is not None and hasattr(_stdin_buf, "peek"):
+            _bom_prefix = _stdin_buf.peek(3)[:3]
+            if _bom_prefix == b"\xef\xbb\xbf":
+                _stdin_buf.read(3)
+                log.info("sourcecode-mcp stripped UTF-8 BOM from stdin (PowerShell 5.1 workaround)")
+    except Exception:
+        pass  # Never abort server startup over BOM detection
+
     log.info("sourcecode-mcp starting (stdio transport)")
     try:
         _mcp.run()

{sourcecode-1.31.29 → sourcecode-1.31.30}/src/sourcecode/prepare_context.py

@@ -388,6 +388,9 @@ class TaskOutput:
     deployment_risks: list[str] = field(default_factory=list)
     deployment: Optional[dict] = None
     entry_points_structured: Optional[dict] = None
+    # P0-2: fast-mode truncation transparency
+    truncated: bool = False
+    truncated_reason: Optional[str] = None
 
 
 @dataclass
@@ -1991,6 +1994,21 @@ class TaskContextBuilder:
                 untested.sort(key=lambda p: (len(p.split("/")), p))
                 test_gaps = untested[:15]
 
+        # P0-2: fast mode truncation transparency for generate-tests.
+        # When --fast is active the test-gap discovery block is skipped entirely,
+        # so test_gaps stays []. Without a signal the receiver interprets [] as
+        # "no gaps", which is incorrect. Emit explicit truncation metadata and
+        # downgrade confidence so the agent knows the analysis is incomplete.
+        _fast_truncated = fast and task_name == "generate-tests"
+        _fast_truncated_reason = "fast mode skips test gap discovery" if _fast_truncated else None
+        if _fast_truncated:
+            import sys as _sys_warn
+            _sys_warn.stderr.write(
+                "[warn] prepare-context generate-tests --fast: test gap discovery skipped. "
+                "Output will contain truncated=true and confidence=low.\n"
+            )
+            _sys_warn.stderr.flush()
+
         # ── 8. Confidence + gaps ──────────────────────────────────────────────
         from sourcecode.confidence_analyzer import ConfidenceAnalyzer
         from dataclasses import asdict as _asdict
@@ -2012,6 +2030,9 @@ class TaskContextBuilder:
 
         conf_summary, analysis_gaps = ConfidenceAnalyzer().analyze(sm_for_conf)
         confidence = conf_summary.overall
+        # P0-2: fast-mode truncation overrides confidence to signal incomplete analysis
+        if _fast_truncated:
+            confidence = "low"
         _has_mybatis = any(
             f.name == "MyBatis"
             for s in stacks
@@ -2130,6 +2151,9 @@ class TaskContextBuilder:
             deployment_risks=_cb_deploy_risks,
             deployment=_cb_deployment,
             entry_points_structured=_cb_bootstrap,
+            # P0-2: fast-mode truncation transparency
+            truncated=_fast_truncated,
+            truncated_reason=_fast_truncated_reason,
         )
 
     def render_prompt(self, output: TaskOutput) -> str:

sourcecode-1.31.29/.continue-here.md

@@ -1,98 +0,0 @@
-# Handoff — Sesión 33 (2026-05-26)
-
-## Position
-
-**Project:** sourcecode (atlas-cli)  
-**Activity:** Post-audit bug fixing — four correctness fixes (P0/P1/P2)  
-**Branch:** master  
-**Last commit:** f3d44c3 — fix(prepare-context,cli,mcp): four correctness fixes — fast fallback, flag errors, review-pr CI, modernize MCP  
-**Tests:** 1590 passed, 3 skipped ✅
-
----
-
-## Work Done This Session
-
-### Session 33 (this session)
-**Four bugs fixed from new audit batch + backlog:**
-
-**FIX 1 — P0: `--fast` returns `relevant_files: []`** (`prepare_context.py`)
-- When `fast=True` on large repo, `_rank_files` received only noise/IDE files → returned `[]`
-- Added fast-mode fallback block after `_rank_files`: injects entry points + git log -10 files +
-  symptom path matches (up to 20) when `relevant_files` is empty and `fast=True`
-- Validated: `sourcecode prepare-context fix-bug . --fast --symptom "spinner"` → 3 results
-
-**FIX 2 — P1: Incompatible flags → stderr plain text** (`cli.py`)
-- `--compact --full` wrote plain text to stderr; agents couldn't parse it
-- Replaced `typer.echo(err=True)` with `sys.stdout.write(json.dumps({...}))` for `incompatible_flags`
-- Validated: `sourcecode . --compact --full 2>/dev/null | jq .error` → `"incompatible_flags"`
-
-**FIX 3 — P1: `review-pr` without `--since` exits 0 silently in CI** (`prepare_context.py`)
-- Clean tree (CI) → previously fell back to HEAD~1 diff silently, masking missing --since
-- Removed HEAD~1 fallback: clean tree + no `--since` → `_get_pr_scope_files` returns
-  `([], "no_staged_changes", [], [])` sentinel
-- Step 5d detects sentinel → `no_diff_source` error (exit 1)
-- Staged/unstaged changes still proceed normally (local dev use case)
-- Validated: clean repo → `error: no_diff_source`, `exit_code=1`
-- Test `test_review_pr_requires_git_diff` updated: added `no_diff_source` to expected error set
-
-**FIX 4 — P2: `modernize` missing from MCP server** (`mcp/server.py`)
-- Added `modernize_context` as MCP tool #17 (was #16 before)
-- Mirrors CLI `sourcecode modernize <repo_path>` exactly
-- Returns: hotspot_candidates, dead_zones, high_coupling_nodes, subsystem_summary, recommendation
-
----
-
-## Remaining from AUDIT_v1.31.23.md
-
-### P1 backlog (from HANDOFF.json session 28)
-| # | Issue | File | Effort |
-|---|---|---|---|
-| P1-5 | `project_summary` quality — picks license/badges/marketing blurbs | `summarizer.py` | Medium |
-| P1-6 | `relevant_files.score` ranking quality audit (score exposed, ranking weak) | `ranking_engine.py` | Medium |
-
-### P2 unfixed
-| # | Issue | File | Effort |
-|---|---|---|---|
-| P2-13 | `--no-cache` flag inconsistent across subcommands | `cli.py` | Medium |
-| P2-14 | URLs in code_notes truncated (needs repro) | `code_notes_analyzer.py` | Low |
-| P2-16 | `entry_points.controllers.methods` mismatches `endpoints` count | `cli.py` | Medium |
-| P2-17 | `--compact --help` token claim stale (now runs arch analyzer too) | `cli.py` | Trivial |
-| P2-18 | `impact <file_path>` fails FQN resolution | `repository_ir.py` | Low |
-
----
-
-## Key Files Modified (this session)
-
-```
-src/sourcecode/prepare_context.py   — FIX 1: fast-mode fallback; FIX 3: no_diff_source sentinel
-src/sourcecode/cli.py               — FIX 2: incompatible_flags to stdout JSON
-src/sourcecode/mcp/server.py        — FIX 4: modernize_context tool
-tests/test_v1_10_regressions.py     — test: no_diff_source added to expected error set
-```
-
----
-
-## Decisions This Session
-
-| Decision | Rationale |
-|---|---|
-| Fast-mode fallback injects after `_rank_files`, not before | Keeps ranking path clean; fallback only fires when needed |
-| `no_diff_source` check via sentinel in `_get_pr_scope_files` | Allows test mocks to bypass (mock overrides entire method); inline check before mock fires broke tests |
-| HEAD~1 fallback removed entirely for `since=None` clean tree | CI pipelines always commit first; HEAD~1 fallback was silently hiding missing `--since` |
-| `modernize_context` MCP `format` param is cosmetic (only json) | CLI `modernize` has no `--format` flag; param included per spec schema, yaml rejected with INVALID_ARGUMENT |
-
----
-
-## Next Session
-
-**Recommended:** P2-17 (trivial) → P2-18 (low) → P2-14 (low, needs repro) → P1-5 (medium) → P1-6 (medium) → P2-13 (medium) → P2-16 (medium)
-
-**P2-17:** `--compact --help` says token count — now that `--compact` also runs ArchitectureAnalyzer (P2-10 fix from session 32), verify claim still accurate. Update if stale.
-
-**P2-18:** `sourcecode impact <file_path>` — resolve file path to FQN before IR lookup. Currently passes raw path to `_resolve_target()`, fails to match.
-
-**P1-5:** Audit `summarizer.py`. Prefer: first real descriptive paragraph, architecture, domain/stack description. Exclude: 'Important:', license, badges, install snippets, TOC, link collections, sponsorship, release notes.
-
-**Resume command:** `/gsd:resume-work`
-
-**Test baseline:** `python3 -m pytest tests/ → 1590 passed, 3 skipped`