sourcecode 1.30.1__py3-none-any.whl → 1.30.2__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -1866,6 +1866,8 @@ def prepare_context_cmd(
             out["review_hotspots"] = output.review_hotspots
         if output.suggested_review_order:
             out["suggested_review_order"] = output.suggested_review_order
+        if output.execution_paths:
+            out["execution_paths"] = output.execution_paths
         if output.impact_summary:
             out["impact_summary"] = output.impact_summary
         if output.why_these_files:

sourcecode/flow_analyzer.py

@@ -0,0 +1,310 @@
+"""flow_analyzer.py — Evidence-based execution path extraction for PR context.
+
+Builds Entry → Service → Repository → EndState ordered sequences using ONLY
+direct code evidence: field injection, constructor params, type annotations,
+method calls, explicit instantiation.
+
+V3: execution_paths with runtime_notes — conditional branches, optional execution,
+and async side-effects are surfaced when explicit code signals exist.
+No inference, no naming, no invented behavior.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Callable, Optional
+
+_ENTRY_ARTIFACT_TYPES = frozenset({"controller", "entrypoint"})
+_SERVICE_ARTIFACT_TYPES = frozenset({"service"})
+_REPO_ARTIFACT_TYPES = frozenset({"repository", "mapper"})
+
+_DB_KEYWORDS = frozenset({"repository", "dao", "mapper", "store", "jpa", "jdbc", "sql"})
+_EVENT_KEYWORDS = frozenset({"event", "publish", "emit", "kafka", "queue", "rabbit", "sns", "bus"})
+
+_HTTP_ENTRY_RE = re.compile(
+    r'@(?:Get|Post|Put|Delete|Patch|Request)Mapping[^)]*\)'
+    r'|@(?:Get|Post|Put|Delete|Patch)\([^)]*\)'
+    r'|@\w+\.(?:get|post|put|delete|patch)\([^)]*\)',
+    re.IGNORECASE,
+)
+_METHOD_NAME_RE = re.compile(
+    r'(?:public\s+|async\s+|def\s+|function\s+)*'
+    r'(?:[\w<>\[\]]+\s+)?'
+    r'(\w+)\s*\(',
+)
+
+# Runtime signal patterns: (compiled_regex, note_text)
+# Only signals with explicit code evidence — no inference.
+# Three categories: condition | branch | async
+_RUNTIME_SIGNALS: list[tuple[re.Pattern, str]] = [
+    # ── Conditional / auth guards ─────────────────────────────────────────────
+    (re.compile(r'@PreAuthorize|@Secured|@RolesAllowed', re.IGNORECASE),
+     "condition: authorization check present (@PreAuthorize / @Secured)"),
+    (re.compile(r'isAuthenticated\(\)|hasRole\(|hasAuthority\(|SecurityContextHolder', re.IGNORECASE),
+     "condition: reads authentication context"),
+    (re.compile(r'featureFlag|FeatureToggle|\.isEnabled\s*\(|\.isActive\s*\(', re.IGNORECASE),
+     "condition: feature flag gates execution"),
+    # Null/empty guard with early return — matches if (...null/empty...) return/throw on same line
+    (re.compile(r'if\s*\([^)]*(?:==\s*null|!=\s*null|isEmpty\s*\(\)|isBlank\s*\(\))[^)]*\)'
+                r'\s*(?:\{?\s*)?(?:return|throw)\b', re.IGNORECASE),
+     "condition: null/empty guard with early return"),
+
+    # ── Optional execution / branching ────────────────────────────────────────
+    (re.compile(r'@Cacheable|@CacheEvict|@CachePut', re.IGNORECASE),
+     "branch: Spring cache may short-circuit downstream call"),
+    (re.compile(r'\.getIfPresent\s*\(|cache\.get\s*\(|cacheManager\.', re.IGNORECASE),
+     "branch: manual cache lookup may short-circuit"),
+    (re.compile(r'Optional\s*<|\.orElseThrow\s*\(|\.orElseGet\s*\(|\.orElse\s*\(', re.IGNORECASE),
+     "branch: result may be absent (Optional)"),
+
+    # ── Async / side effects ──────────────────────────────────────────────────
+    (re.compile(r'@Async\b'),
+     "async: runs in separate thread (@Async)"),
+    (re.compile(r'CompletableFuture|\.supplyAsync\s*\(|\.runAsync\s*\('),
+     "async: non-blocking future-based execution"),
+    (re.compile(r'\basync\s+def\b|\bawait\b', re.IGNORECASE),
+     "async: non-blocking (async/await)"),
+    (re.compile(r'publishEvent\s*\(|applicationEventPublisher|eventPublisher\.', re.IGNORECASE),
+     "async: Spring application event emitted"),
+    (re.compile(r'kafkaTemplate\.|KafkaProducer|@KafkaListener', re.IGNORECASE),
+     "async: Kafka message produced"),
+    (re.compile(r'rabbitTemplate\.|amqpTemplate\.|@RabbitListener', re.IGNORECASE),
+     "async: RabbitMQ message sent"),
+]
+
+
+def _detect_lang(path: str) -> str:
+    return {
+        ".java": "java", ".kt": "kotlin",
+        ".py": "python",
+        ".ts": "typescript", ".tsx": "typescript",
+        ".js": "javascript", ".jsx": "javascript",
+        ".go": "go", ".cs": "csharp", ".rb": "ruby", ".php": "php",
+    }.get(Path(path).suffix.lower(), "unknown")
+
+
+def _strip_comments(content: str, lang: str) -> str:
+    content = re.sub(r"/\*.*?\*/", " ", content, flags=re.DOTALL)
+    content = re.sub(r"//[^\n]*", " ", content)
+    if lang in ("python", "ruby", "go"):
+        content = re.sub(r"#[^\n]*", " ", content)
+    return content
+
+
+def _read_safe(root: Path, rel_path: str) -> str:
+    try:
+        return (root / rel_path).read_text(encoding="utf-8", errors="ignore")
+    except (OSError, ValueError):
+        return ""
+
+
+def _collect_runtime_notes(content: str, lang: str) -> list[str]:
+    """Scan comment-stripped content for explicit runtime behavior signals.
+
+    Returns only notes backed by a direct code pattern match.
+    Returns [] when no signals are found.
+    """
+    clean = _strip_comments(content, lang)
+    notes: list[str] = []
+    seen: set[str] = set()
+    for pattern, note in _RUNTIME_SIGNALS:
+        if note not in seen and pattern.search(clean):
+            notes.append(note)
+            seen.add(note)
+    return notes
+
+
+def _find_entry_method(clean: str) -> Optional[str]:
+    m = _HTTP_ENTRY_RE.search(clean)
+    if not m:
+        return None
+    after = clean[m.end():]
+    mn = _METHOD_NAME_RE.match(after.lstrip())
+    if mn:
+        name = mn.group(1)
+        if name.lower() not in ("public", "async", "def", "function", "void", "override"):
+            return name
+    return None
+
+
+def _build_field_map(clean: str) -> dict[str, str]:
+    """Map field_name_lower → ClassName from injection patterns."""
+    fmap: dict[str, str] = {}
+    for m in re.finditer(r"private\s+(\w+)(?:<[^>]+>)?\s+(\w+)\s*[;=,)]", clean):
+        fmap[m.group(2).lower()] = m.group(1)
+    for m in re.finditer(r"(?:private|protected|readonly)\s+(\w+)\s*:\s*(\w+)", clean):
+        fmap[m.group(1).lower()] = m.group(2)
+    for m in re.finditer(r"self\.(\w+)\s*=\s*(\w+)\s*\(", clean):
+        fmap[m.group(1).lower()] = m.group(2)
+    return fmap
+
+
+def _find_called_method(clean: str, class_name: str, fmap: dict[str, str]) -> Optional[str]:
+    fields = [f for f, t in fmap.items() if t.lower() == class_name.lower()]
+    for field in fields:
+        pat = rf"\bthis\.{re.escape(field)}\.(\w+)\s*\(|\b{re.escape(field)}\.(\w+)\s*\("
+        for m in re.finditer(pat, clean, re.IGNORECASE):
+            name = m.group(1) or m.group(2)
+            if name and name.lower() not in ("class", "new", "super", "get", "set"):
+                return name
+    for m in re.finditer(rf"\b{re.escape(class_name)}\.(\w+)\s*\(", clean, re.IGNORECASE):
+        name = m.group(1)
+        if name.lower() not in ("class", "new", "super"):
+            return name
+    return None
+
+
+def _has_code_evidence(clean: str, class_name: str) -> bool:
+    """True only when class_name has direct code evidence in pre-stripped content."""
+    esc = re.escape(class_name)
+    if re.search(rf"\b(?:private|protected)\s+{esc}\b", clean, re.IGNORECASE):
+        return True
+    if re.search(rf"[,(]\s*{esc}\s+\w+", clean, re.IGNORECASE):
+        return True
+    if re.search(rf":\s*{esc}\b", clean, re.IGNORECASE):
+        return True
+    if re.search(rf"\bnew\s+{esc}\s*\(", clean, re.IGNORECASE):
+        return True
+    if re.search(rf"\b{esc}\s*\(", clean):
+        return True
+    if re.search(rf"\b{esc}\b", clean, re.IGNORECASE):
+        non_import = re.search(
+            rf"^(?!\s*(?:import|require|from|//|#|\*)\b).*\b{esc}\b",
+            clean, re.IGNORECASE | re.MULTILINE,
+        )
+        if non_import:
+            return True
+    return False
+
+
+def _find_evidenced_ordered(
+    root: Path,
+    source_path: str,
+    candidates: list[str],
+) -> list[tuple[str, Optional[str]]]:
+    """Return (class_name, method_or_None) for candidates with direct code evidence,
+    ordered by their first appearance position in the source file."""
+    content = _read_safe(root, source_path)
+    if not content:
+        return []
+    lang = _detect_lang(source_path)
+    clean = _strip_comments(content, lang)
+    fmap = _build_field_map(clean)
+
+    positioned: list[tuple[int, str, Optional[str]]] = []
+    for cand_path in candidates:
+        class_name = Path(cand_path).stem
+        if not _has_code_evidence(clean, class_name):
+            continue
+        method = _find_called_method(clean, class_name, fmap)
+        m = re.search(rf"\b{re.escape(class_name)}\b", clean, re.IGNORECASE)
+        pos = m.start() if m else len(clean)
+        positioned.append((pos, class_name, method))
+
+    positioned.sort(key=lambda x: x[0])
+    return [(cls, meth) for _, cls, meth in positioned]
+
+
+def _detect_end_state(path: list[str]) -> str:
+    for step in path:
+        s = step.lower()
+        if any(kw in s for kw in _DB_KEYWORDS):
+            return "DB write"
+        if any(kw in s for kw in _EVENT_KEYWORDS):
+            return "event emitted"
+    return "HTTP response"
+
+
+def _step_label(class_name: str, method: Optional[str]) -> str:
+    return f"{class_name}.{method}" if method else class_name
+
+
+def _path_name(entry_class: str) -> str:
+    domain = re.sub(
+        r"(?:RestController|Controller|Resource|Handler|Api|Endpoint|Router|Servlet)$",
+        "", entry_class, flags=re.IGNORECASE,
+    )
+    return re.sub(r"(?<=[a-z])(?=[A-Z])", " ", domain).strip()
+
+
+def analyze_execution_paths(
+    changed_files: list[str],
+    all_paths: list[str],
+    root: Path,
+    classify_fn: Callable[[str], dict],
+    max_paths: int = 3,
+) -> list[dict]:
+    """Build ordered execution paths with runtime behavior signals.
+
+    Each path:
+    - One service per entry point (most evident, earliest-referenced)
+    - Each step requires direct code evidence
+    - runtime_notes populated from explicit code signals only (never inferred)
+    - Forward-only: Controller → Service → Repository
+
+    Returns list of: {name, entry_point, path, runtime_notes, end_state}
+    Returns [] when no verifiable path exists.
+    """
+    entry_files = [
+        f for f in changed_files
+        if classify_fn(f)["artifact_type"] in _ENTRY_ARTIFACT_TYPES
+    ]
+    if not entry_files:
+        return []
+
+    all_services = [p for p in all_paths if classify_fn(p)["artifact_type"] in _SERVICE_ARTIFACT_TYPES]
+    all_repos = [p for p in all_paths if classify_fn(p)["artifact_type"] in _REPO_ARTIFACT_TYPES]
+
+    result: list[dict] = []
+
+    for entry_path in entry_files[:max_paths]:
+        entry_class = Path(entry_path).stem
+        lang = _detect_lang(entry_path)
+
+        entry_content = _read_safe(root, entry_path)
+        entry_clean = _strip_comments(entry_content, lang) if entry_content else ""
+        entry_method = _find_entry_method(entry_clean) if entry_clean else None
+        entry_point_str = _step_label(entry_class, entry_method)
+
+        evidenced_svcs = _find_evidenced_ordered(root, entry_path, all_services)
+        if not evidenced_svcs:
+            continue
+
+        svc_class, svc_method = evidenced_svcs[0]
+        svc_label = _step_label(svc_class, svc_method)
+
+        svc_path = next((p for p in all_services if Path(p).stem == svc_class), None)
+        svc_content = _read_safe(root, svc_path) if svc_path else ""
+        svc_lang = _detect_lang(svc_path) if svc_path else "unknown"
+
+        # Service step — notes scoped to service file only
+        path_items: list[dict] = [
+            {"step": svc_label,
+             "notes": _collect_runtime_notes(svc_content, svc_lang) if svc_content else []},
+        ]
+
+        # Repository step — notes scoped to repo file only
+        if svc_path:
+            evidenced_repos = _find_evidenced_ordered(root, svc_path, all_repos)
+            if evidenced_repos:
+                repo_class, repo_method = evidenced_repos[0]
+                repo_label = _step_label(repo_class, repo_method)
+                repo_path = next((p for p in all_repos if Path(p).stem == repo_class), None)
+                repo_content = _read_safe(root, repo_path) if repo_path else ""
+                repo_lang = _detect_lang(repo_path) if repo_path else "unknown"
+                path_items.append(
+                    {"step": repo_label,
+                     "notes": _collect_runtime_notes(repo_content, repo_lang) if repo_content else []},
+                )
+
+        # Entry-point notes scoped to controller file
+        entry_notes = _collect_runtime_notes(entry_content, lang) if entry_content else []
+
+        result.append({
+            "name": _path_name(entry_class),
+            "entry_point": {"step": entry_point_str, "notes": entry_notes},
+            "path": path_items,
+            "end_state": _detect_end_state([item["step"] for item in path_items]),
+        })
+
+    return result

sourcecode/prepare_context.py

@@ -351,6 +351,7 @@ class TaskOutput:
     test_coverage_risk: dict = field(default_factory=dict)
     review_hotspots: list[str] = field(default_factory=list)
     suggested_review_order: list[str] = field(default_factory=list)
+    execution_paths: list[dict] = field(default_factory=list)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -874,6 +875,17 @@ class TaskContextBuilder:
                     _pr_suggested_review_order.append(_f)
                     _seen_order.add(_f)
 
+        # ── 6d. review-pr: execution paths ──────────────────────────────────
+        _execution_paths: list[dict] = []
+        if task_name == "review-pr" and _delta_files:
+            from sourcecode.flow_analyzer import analyze_execution_paths
+            _execution_paths = analyze_execution_paths(
+                changed_files=sorted(_delta_files),
+                all_paths=all_paths,
+                root=self.root,
+                classify_fn=self._classify_changed_file,
+            )
+
         # ── 6c. Symptom keyword boost + related notes (fix-bug + --symptom) ──
         symptom_keywords: list[str] = []
         related_notes: list[dict] = []
@@ -1104,6 +1116,7 @@ class TaskContextBuilder:
             test_coverage_risk=_pr_test_coverage_risk,
             review_hotspots=_pr_review_hotspots,
             suggested_review_order=_pr_suggested_review_order,
+            execution_paths=_execution_paths,
         )
 
     def render_prompt(self, output: TaskOutput) -> str:

{sourcecode-1.30.1.dist-info → sourcecode-1.30.2.dist-info}/METADATA

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

{sourcecode-1.30.1.dist-info → sourcecode-1.30.2.dist-info}/RECORD

@@ -1,10 +1,10 @@
-sourcecode/__init__.py,sha256=gRPMqEDn0fO_SPt0SwGDW592WxUJP93fNtbrm1ay9ms,103
+sourcecode/__init__.py,sha256=ERxetwuKJX_1UzzbbdymfXL8AXwRFp03HJG6sY-iJO4,103
 sourcecode/adaptive_scanner.py,sha256=RTNExwWPXzjgLaRueT7UuxkPj5ZEToWjGbx1j0LSZ9E,10250
 sourcecode/architecture_analyzer.py,sha256=MyBa0Hf5HmkudZQDLKrjcWDKETXETXl0mQX1swtTwAA,39091
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
 sourcecode/ast_extractor.py,sha256=XgrZg2DcWcUm9r87cRG3KGO7IK2TIL_N-CvhSbUmmh4,49901
 sourcecode/classifier.py,sha256=pYve2J1LqtYssU3lYLMDz18PT-CjN5c18QYE7R_IG1Q,7507
-sourcecode/cli.py,sha256=iWzo7u-wmWjj0GYAF54UpbicfpXt2OUxPRy44h2VaCI,80646
+sourcecode/cli.py,sha256=1qVMsC2swT-OtCK6XziIM0J4xKp8kcRhUzfOaHr7vRU,80743
 sourcecode/code_notes_analyzer.py,sha256=y1MJBnPZHYp4i6cQCXUb9ATIyifS_qMQWjw_8lPkpsU,9215
 sourcecode/confidence_analyzer.py,sha256=xw_Jv8pAd0wd8t2vvQlorw8Ih0rSF3YCoFS8K-_4aXg,15762
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -17,10 +17,11 @@ sourcecode/doc_analyzer.py,sha256=afA4uJFwXZ_uR2l4J0pQwbeTkRkGmKdN9KhRVYePBUw,24
 sourcecode/entrypoint_classifier.py,sha256=gvKgl0f5T8ol1r4JMmkeqGHuZTfZJiOwFOWdc7EYwYw,4061
 sourcecode/env_analyzer.py,sha256=GxCidahAAIptTdDFIlVB6URd4HBnBlIX_SqUov3MBRQ,22076
 sourcecode/file_classifier.py,sha256=48ly5Z6exkzBy8lNy1AkdP4-oJqIA1zT3LZfffuTyDo,11572
+sourcecode/flow_analyzer.py,sha256=VQDrItg3NBqOOD8PxHXyntXQnPweUuUn6JtOY8lNWys,12841
 sourcecode/git_analyzer.py,sha256=_pCg2V4d2aa17k9hayTzpexAj8syvyk4y9NYNvvgOAI,12802
 sourcecode/graph_analyzer.py,sha256=iUK-7pSV-cvGqqD2hENdYmhnm0wcXFEyK-xnu5ul8OU,62515
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
-sourcecode/prepare_context.py,sha256=ODGcRvwcJEQKDVdOVE3tGVYBqjNu0x6NkqBY4rnDAwQ,128946
+sourcecode/prepare_context.py,sha256=ELrCIIcttip4B3y9aQZdMPqIgzaEJR0evDdG8QYTBLc,129623
 sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=virVglafZufioHpZpwktjMvUiL0TZELWQCQnQNV8dFo,9360
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
@@ -61,8 +62,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.30.1.dist-info/METADATA,sha256=bbWfG67q8PN5m5nGQpeGJu04bA2zKFNrUZndmIalCRs,23417
-sourcecode-1.30.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.30.1.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.30.1.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.30.1.dist-info/RECORD,,
+sourcecode-1.30.2.dist-info/METADATA,sha256=3bLQsn6BmYa9Rum0jjejw2627bPdOMaYxbqI2XMyOLY,23417
+sourcecode-1.30.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.30.2.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.30.2.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.30.2.dist-info/RECORD,,