sourcecode 1.30.3__tar.gz → 1.30.5__tar.gz

sourcecode-1.30.5/.continue-here.md

@@ -0,0 +1,163 @@
+# Continue Here — atlas-cli sesión 9
+
+**Paused:** 2026-05-16 (sesión 9)
+**Repo:** `/Users/user/Downloads/atlas-cli`
+**Branch:** master
+**Último commit:** `88e1ebd` — Actualizando README
+**Working tree:** DIRTY (sin commit — usuario pidió "no hagas commit" esta sesión)
+
+---
+
+## Lo que se hizo esta sesión
+
+### Fix: test regresivo stale en `test_signal_hierarchy.py`
+
+`test_prepare_context_review_pr_task` esperaba exit_code 0 pero la nueva conducta (desde `7085e97`) devuelve exit_code 1 cuando no hay diff. El test corría contra atlas-cli (no tmp_project — el arg se consume por `_preprocess_args`), entonces era frágil: con cambios pendientes en atlas-cli → exit 0, sin cambios → exit 1.
+
+**Fix:** test acepta ambos exit codes y verifica estructura JSON en cada caso.
+
+---
+
+### Feature: `behavioral_impact` para `review-pr`
+
+Nueva capability: en vez de "archivos relacionados por heurística", modelar impacto causal del cambio.
+
+**Nueva sección top-level en output de review-pr:**
+```json
+{
+  "behavioral_impact": [{
+    "entry_point": "ArticleController.favoriteArticle",
+    "affected_path": ["ArticleFavoriteService.favorite", "ArticleFavoriteRepository.save"],
+    "impact": ["article favorite persistence affected"],
+    "end_state": "DB write"
+  }]
+}
+```
+
+**Dos traversals:**
+
+| Archivo cambiado | Estrategia | entry_point |
+|---|---|---|
+| Controller | Forward: ctrl → svc → repo | El propio controller |
+| Service/Repo/Domain | Reverse: buscar qué controller inyecta/llama la cadena | Controller que lo usa |
+
+**Reverse lookup:** primero directo (ctrl usa clase directamente), luego indirecto (ctrl → svc mediador → clase cambiada).
+
+**Impact generation:** basado en artifact_type + end_state + nombre de clase sin sufijo:
+- Repository → `"X persistence affected"`
+- Service + DB write → `"X data persistence behavior may change"`
+- Service + event → `"X event emission affected"`
+- + si hay `@PreAuthorize`/`@Secured` en controller → `"authorization check present on entry point"`
+
+**Sin evidencia → no emitir path.** `_has_code_evidence` gate en cada paso.
+
+---
+
+## Archivos modificados (sin commit)
+
+| Archivo | Cambio |
+|---------|--------|
+| `src/sourcecode/flow_analyzer.py` | `analyze_behavioral_impact()` + helpers `_domain_from_class`, `_impact_descriptions`, `_impact_descriptions_for_controller` (~205 líneas nuevas) |
+| `src/sourcecode/prepare_context.py` | Campo `behavioral_impact` en `TaskOutput`, bloque 6d llama `analyze_behavioral_impact` |
+| `src/sourcecode/cli.py` | Serializa `behavioral_impact` en output de review-pr |
+| `tests/test_signal_hierarchy.py` | Fix stale test `test_prepare_context_review_pr_task` |
+| `tests/test_v1_10_regressions.py` | Clase `TestBehavioralImpact` con 5 tests unitarios |
+
+---
+
+## Tests al pausar
+
+```
+777 passed, 3 skipped, 1 deselected
+```
+
+Los 5 tests nuevos en `TestBehavioralImpact` pasan:
+- `test_service_change_finds_controller_entry_point` ✓
+- `test_repository_change_finds_controller_via_service` ✓
+- `test_controller_change_forward_traversal` ✓
+- `test_no_evidence_returns_empty` ✓
+- `test_impact_strings_describe_behavior_not_files` ✓
+
+---
+
+## Pendiente de sesión anterior (sigue vigente)
+
+1. **Smoke test `delta`** — verificar Fix 1-3 (BFS module constraint) no afecta `delta`:
+   ```bash
+   cd ~/Documents/workspace/spring-boot-realworld-example-app
+   sourcecode prepare-context delta . --since HEAD~1 2>/dev/null | python3 -c "
+   import json,sys; d=json.load(sys.stdin)
+   print('relevant_files:', len(d.get('relevant_files', [])))
+   "
+   ```
+
+2. **Smoke test `security_change` path** — cambio real en auth logic debe expandir security chain.
+
+3. **Tests unitarios para `_classify_diff_severity`** — sin tests actualmente.
+
+4. **`User.java` clasificado como `"source"` no `"domain_model"`** — fix opcional en `_classify_changed_file`.
+
+5. **Smoke tests saint-server** — pendiente sesión 4/5.
+
+---
+
+## Pendiente de esta sesión (nuevo)
+
+1. **COMMIT** — toda la sesión sin commit. Hacer commit:
+   ```bash
+   git add src/sourcecode/flow_analyzer.py \
+           src/sourcecode/prepare_context.py \
+           src/sourcecode/cli.py \
+           tests/test_signal_hierarchy.py \
+           tests/test_v1_10_regressions.py
+   git commit -m "feat(review-pr): behavioral_impact — impacto causal de cambio, no expansión heurística"
+   ```
+
+2. **Smoke test `behavioral_impact`** en repo real:
+   ```bash
+   /Users/user/.local/pipx/venvs/sourcecode/bin/python -m pip install -e . -q
+   cd ~/Documents/workspace/spring-boot-realworld-example-app
+   # Modificar un service (ej. ArticleFavoriteService.java) sin commit y correr:
+   sourcecode prepare-context review-pr . 2>/dev/null | python3 -c "
+   import json, sys
+   d = json.load(sys.stdin)
+   for bi in d.get('behavioral_impact', []):
+       print('entry:', bi['entry_point'])
+       print('path:', bi['affected_path'])
+       print('impact:', bi['impact'])
+       print('end_state:', bi['end_state'])
+       print()
+   "
+   ```
+
+3. **Evaluar si `execution_paths` sigue siendo útil** o si `behavioral_impact` lo reemplaza completamente. Ambos coexisten ahora.
+
+4. **Impact generation refinement** — para service changes, `"X data persistence behavior may change"` es verbose. Podría simplificarse a `"X persistence affected"`.
+
+---
+
+## Para retomar
+
+```bash
+cd /Users/user/Downloads/atlas-cli
+git log --oneline -3
+git diff --stat HEAD   # verá los 5 archivos sin commit
+
+# Verificar import
+python3 -c "from sourcecode.flow_analyzer import analyze_behavioral_impact; print('OK')"
+
+# Tests completos
+python3 -m pytest tests/ \
+  --ignore=tests/test_block2_coverage.py \
+  --ignore=tests/test_packaging.py \
+  --deselect=tests/test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile_keeps_declared_versions \
+  -q
+# Expected: 777 passed
+
+# Tests nuevos específicamente
+python3 -m pytest tests/test_v1_10_regressions.py::TestBehavioralImpact -v
+```
+
+---
+
+*Pausado 2026-05-16 sesión 9 — gsd:pause-work*

{sourcecode-1.30.3 → sourcecode-1.30.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.3
+Version: 1.30.5
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -219,9 +219,9 @@ Description-Content-Type: text/markdown
 
 # sourcecode
 
-**Compressed AI-ready context for Java/Spring enterprise codebases.**
+**Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.3-blue)
+![Version](https://img.shields.io/badge/version-1.30.5-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -230,6 +230,8 @@ Description-Content-Type: text/markdown
 
 `sourcecode` analyzes a repository and produces structured JSON or YAML designed to be fed directly to AI agents or language models. It solves the "stuff the whole repo into the prompt" problem by extracting a deterministic, high-signal summary: stack detection, entry points, dependencies, git hotspots, inline annotations, and confidence metadata.
 
+For PR review specifically, `sourcecode` extracts **execution paths**: ordered chains from entry point through service to data access, with runtime signals (auth guards, cache short-circuits, async execution) anchored to the specific step where they affect behavior. A reviewer sees _what the system does_ under this change, not just which files changed.
+
 Optimized for Java/Spring Boot monorepos. Works on any codebase.
 
 ---
@@ -255,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.3
+# sourcecode 1.30.5
 ```
 
 ---
@@ -342,7 +344,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `fix-bug` | Files ranked by risk (annotations, churn, uncommitted changes), suspected areas | Debugging session |
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
-| `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
+| `review-pr` | Execution paths with per-step runtime signals, security/transactional impact, test coverage gaps | Pre-merge behavior review |
 | `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
@@ -423,6 +425,80 @@ sourcecode prepare-context delta . --since main
 
 ---
 
+## `review-pr` — behavior-aware PR analysis
+
+Extracts **execution paths**: ordered chains from entry point through service to data access layer, with runtime signals anchored to the specific step where they affect behavior.
+
+```bash
+sourcecode prepare-context review-pr [PATH] --since REF
+# or against uncommitted working-tree changes:
+sourcecode prepare-context review-pr
+```
+
+**`execution_paths` schema:**
+
+```json
+{
+  "execution_paths": [
+    {
+      "name": "Order",
+      "entry_point": {
+        "step": "OrderController.createOrder",
+        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+      },
+      "path": [
+        {
+          "step": "ShippingService.process",
+          "notes": [
+            "branch: Spring cache may short-circuit downstream call",
+            "async: runs in separate thread (@Async)"
+          ]
+        },
+        {
+          "step": "OrderRepository.save",
+          "notes": []
+        }
+      ],
+      "end_state": "DB write"
+    }
+  ]
+}
+```
+
+**Path rules:**
+
+- One path per changed entry point — most-evident downstream call, not all branches
+- Each step requires direct code evidence: field injection, constructor param, method call, or type annotation
+- `notes` are scanned from that step's own source file — no cross-contamination between steps
+- Path terminates where evidence ends; no gap-filling by naming convention or module similarity
+
+**Runtime signals detected per step:**
+
+| Signal | Example code | Note emitted |
+|--------|-------------|--------------|
+| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
+| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
+| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
+| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+
+**Other `review-pr` output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `review_hotspots` | Top changed files ranked by impact score |
+| `suggested_review_order` | Security → API → Service → Persistence → Config |
+| `security_impact` | Changed files touching the security surface |
+| `transactional_impact` | Files crossing transaction boundaries |
+| `test_coverage_risk` | Changed source files with no corresponding test |
+| `affected_modules` | DDD domain modules touched by the change |
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.30.3 → sourcecode-1.30.5}/README.md

@@ -1,8 +1,8 @@
 # sourcecode
 
-**Compressed AI-ready context for Java/Spring enterprise codebases.**
+**Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.3-blue)
+![Version](https://img.shields.io/badge/version-1.30.5-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -11,6 +11,8 @@
 
 `sourcecode` analyzes a repository and produces structured JSON or YAML designed to be fed directly to AI agents or language models. It solves the "stuff the whole repo into the prompt" problem by extracting a deterministic, high-signal summary: stack detection, entry points, dependencies, git hotspots, inline annotations, and confidence metadata.
 
+For PR review specifically, `sourcecode` extracts **execution paths**: ordered chains from entry point through service to data access, with runtime signals (auth guards, cache short-circuits, async execution) anchored to the specific step where they affect behavior. A reviewer sees _what the system does_ under this change, not just which files changed.
+
 Optimized for Java/Spring Boot monorepos. Works on any codebase.
 
 ---
@@ -36,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.3
+# sourcecode 1.30.5
 ```
 
 ---
@@ -123,7 +125,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `fix-bug` | Files ranked by risk (annotations, churn, uncommitted changes), suspected areas | Debugging session |
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
-| `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
+| `review-pr` | Execution paths with per-step runtime signals, security/transactional impact, test coverage gaps | Pre-merge behavior review |
 | `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
@@ -204,6 +206,80 @@ sourcecode prepare-context delta . --since main
 
 ---
 
+## `review-pr` — behavior-aware PR analysis
+
+Extracts **execution paths**: ordered chains from entry point through service to data access layer, with runtime signals anchored to the specific step where they affect behavior.
+
+```bash
+sourcecode prepare-context review-pr [PATH] --since REF
+# or against uncommitted working-tree changes:
+sourcecode prepare-context review-pr
+```
+
+**`execution_paths` schema:**
+
+```json
+{
+  "execution_paths": [
+    {
+      "name": "Order",
+      "entry_point": {
+        "step": "OrderController.createOrder",
+        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+      },
+      "path": [
+        {
+          "step": "ShippingService.process",
+          "notes": [
+            "branch: Spring cache may short-circuit downstream call",
+            "async: runs in separate thread (@Async)"
+          ]
+        },
+        {
+          "step": "OrderRepository.save",
+          "notes": []
+        }
+      ],
+      "end_state": "DB write"
+    }
+  ]
+}
+```
+
+**Path rules:**
+
+- One path per changed entry point — most-evident downstream call, not all branches
+- Each step requires direct code evidence: field injection, constructor param, method call, or type annotation
+- `notes` are scanned from that step's own source file — no cross-contamination between steps
+- Path terminates where evidence ends; no gap-filling by naming convention or module similarity
+
+**Runtime signals detected per step:**
+
+| Signal | Example code | Note emitted |
+|--------|-------------|--------------|
+| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
+| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
+| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
+| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+
+**Other `review-pr` output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `review_hotspots` | Top changed files ranked by impact score |
+| `suggested_review_order` | Security → API → Service → Persistence → Config |
+| `security_impact` | Changed files touching the security surface |
+| `transactional_impact` | Files crossing transaction boundaries |
+| `test_coverage_risk` | Changed source files with no corresponding test |
+| `affected_modules` | DDD domain modules touched by the change |
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.30.3 → sourcecode-1.30.5}/pyproject.toml

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

{sourcecode-1.30.3 → sourcecode-1.30.5}/src/sourcecode/__init__.py

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

{sourcecode-1.30.3 → sourcecode-1.30.5}/src/sourcecode/cli.py

@@ -1633,7 +1633,7 @@ def prepare_context_cmd(
       refactor       Structural issues, improvement opportunities
       generate-tests Untested source files, test gap analysis
       onboard        Full project context for new agents/developers
-      review-pr      PR diff: changed files, security/transactional impact, test gaps (requires git diff or --since)
+      review-pr      PR diff: execution paths with per-step runtime signals, security/transactional impact, test gaps (requires git diff or --since)
       delta          Incremental context: git-changed files only
 
     \b
@@ -1868,6 +1868,8 @@ def prepare_context_cmd(
             out["suggested_review_order"] = output.suggested_review_order
         if output.execution_paths:
             out["execution_paths"] = output.execution_paths
+        if output.behavioral_impact:
+            out["behavioral_impact"] = output.behavioral_impact
         if output.impact_summary:
             out["impact_summary"] = output.impact_summary
         if output.why_these_files: