sourcecode 1.30.14__py3-none-any.whl → 1.30.15__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -1622,6 +1622,11 @@ def prepare_context_cmd(
         "--symptom",
         help="(fix-bug) Keyword hint for the bug: boosts matching files and surfaces related code notes.",
     ),
+    format: Optional[str] = typer.Option(
+        None,
+        "--format",
+        help="Output format: json (default) | github-comment (Markdown PR comment for review-pr task)",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1895,7 +1900,12 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
-    _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+    if format == "github-comment" and task == "review-pr":
+        from sourcecode.pr_comment_renderer import render_github_comment
+        _pc_content = render_github_comment(out)
+    else:
+        _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+
     if output_path is not None:
         output_path.write_text(_pc_content, encoding="utf-8")
     else:

sourcecode/flow_analyzer.py

@@ -33,43 +33,57 @@ _METHOD_NAME_RE = re.compile(
     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]] = [
+# Runtime signal patterns: (compiled_regex, note_text, epistemic_level)
+# epistemic_level follows the 4-value contract:
+#   STRUCTURAL SIGNAL  — annotation or type-system evidence directly observed in source
+#   INFERRED (LOW CONFIDENCE) — heuristic code-pattern match; no full structural proof
+_RUNTIME_SIGNALS: list[tuple[re.Pattern, str, str]] = [
     # ── Conditional / auth guards ─────────────────────────────────────────────
     (re.compile(r'@PreAuthorize|@Secured|@RolesAllowed', re.IGNORECASE),
-     "condition: authorization check present (@PreAuthorize / @Secured)"),
+     "condition: authorization check present (@PreAuthorize / @Secured)",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'isAuthenticated\(\)|hasRole\(|hasAuthority\(|SecurityContextHolder', re.IGNORECASE),
-     "condition: reads authentication context"),
+     "condition: reads authentication context",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'featureFlag|FeatureToggle|\.isEnabled\s*\(|\.isActive\s*\(', re.IGNORECASE),
-     "condition: feature flag gates execution"),
+     "condition: feature flag gates execution",
+     "INFERRED (LOW CONFIDENCE)"),
     # 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"),
+     "condition: null/empty guard with early return",
+     "STRUCTURAL SIGNAL"),
 
     # ── Optional execution / branching ────────────────────────────────────────
     (re.compile(r'@Cacheable|@CacheEvict|@CachePut', re.IGNORECASE),
-     "branch: Spring cache may short-circuit downstream call"),
+     "branch: Spring cache annotation present — downstream call may be short-circuited",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\.getIfPresent\s*\(|cache\.get\s*\(|cacheManager\.', re.IGNORECASE),
-     "branch: manual cache lookup may short-circuit"),
+     "branch: manual cache lookup detected — downstream call may be short-circuited",
+     "INFERRED (LOW CONFIDENCE)"),
     (re.compile(r'Optional\s*<|\.orElseThrow\s*\(|\.orElseGet\s*\(|\.orElse\s*\(', re.IGNORECASE),
-     "branch: result may be absent (Optional)"),
+     "branch: Optional type in use — result may be absent",
+     "STRUCTURAL SIGNAL"),
 
     # ── Async / side effects ──────────────────────────────────────────────────
     (re.compile(r'@Async\b'),
-     "async: runs in separate thread (@Async)"),
+     "async: @Async annotation present — runs in separate thread",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'CompletableFuture|\.supplyAsync\s*\(|\.runAsync\s*\('),
-     "async: non-blocking future-based execution"),
+     "async: CompletableFuture detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\basync\s+def\b|\bawait\b', re.IGNORECASE),
-     "async: non-blocking (async/await)"),
+     "async: async/await detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'publishEvent\s*\(|applicationEventPublisher|eventPublisher\.', re.IGNORECASE),
-     "async: Spring application event emitted"),
+     "async: Spring application event emitted",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'kafkaTemplate\.|KafkaProducer|@KafkaListener', re.IGNORECASE),
-     "async: Kafka message produced"),
+     "async: Kafka producer detected",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'rabbitTemplate\.|amqpTemplate\.|@RabbitListener', re.IGNORECASE),
-     "async: RabbitMQ message sent"),
+     "async: RabbitMQ producer detected",
+     "STRUCTURAL SIGNAL"),
 ]
 
 
@@ -98,18 +112,19 @@ def _read_safe(root: Path, rel_path: str) -> str:
         return ""
 
 
-def _collect_runtime_notes(content: str, lang: str) -> list[str]:
+def _collect_runtime_notes(content: str, lang: str) -> list[dict]:
     """Scan comment-stripped content for explicit runtime behavior signals.
 
     Returns only notes backed by a direct code pattern match.
+    Each entry: {note: str, epistemic_level: str}.
     Returns [] when no signals are found.
     """
     clean = _strip_comments(content, lang)
-    notes: list[str] = []
+    notes: list[dict] = []
     seen: set[str] = set()
-    for pattern, note in _RUNTIME_SIGNALS:
+    for pattern, note, epistemic_level in _RUNTIME_SIGNALS:
         if note not in seen and pattern.search(clean):
-            notes.append(note)
+            notes.append({"note": note, "epistemic_level": epistemic_level})
             seen.add(note)
     return notes
 
@@ -348,8 +363,11 @@ def analyze_execution_paths(
             "entry_point": {"step": entry_point_str, "notes": entry_notes},
             "path": path_items,
             "end_state": _detect_end_state([item["step"] for item in path_items]),
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
         })
 
+    return result
+
 
 # ── Behavioral impact helpers ─────────────────────────────────────────────────
 
@@ -363,9 +381,13 @@ def _domain_from_class(class_name: str) -> str:
     return re.sub(r"(?<=[a-z])(?=[A-Z])", " ", stripped).strip().lower()
 
 
-def _impact_item(statement: str, support: str, certainty: str) -> dict:
-    truth_level = "observed" if certainty == "high" else "inferred"
-    return {"statement": statement, "support": support, "certainty": certainty, "truth_level": truth_level}
+def _impact_item(statement: str, support: str, certainty: str, *, epistemic_level: Optional[str] = None) -> dict:
+    if epistemic_level is None:
+        if certainty in ("high", "medium"):
+            epistemic_level = "STRUCTURAL SIGNAL"
+        else:
+            epistemic_level = "INFERRED (LOW CONFIDENCE)"
+    return {"statement": statement, "support": support, "epistemic_level": epistemic_level}
 
 
 def _impact_descriptions(
@@ -449,6 +471,7 @@ def _impact_descriptions_for_controller(
             "controller entry point modified",
             "controller entry point is in changed files (direct diff evidence)",
             certainty,
+            epistemic_level="FACT",
         ))
 
     if re.search(r"@PreAuthorize|@Secured|@RolesAllowed|hasRole\(|isAuthenticated", ctrl_clean, re.IGNORECASE):
@@ -541,6 +564,7 @@ def analyze_behavioral_impact(
             "affected_path": affected_path,
             "impact": _impact_descriptions_for_controller(affected_path, end_state, ctrl_clean, evidence_level),
             "end_state": end_state,
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
             "confidence": confidence,
             "evidence_level": evidence_level,
             "trace": trace,
@@ -638,6 +662,7 @@ def analyze_behavioral_impact(
                 "affected_path": affected_path,
                 "impact": _impact_descriptions(changed_class, changed_type, end_state, ctrl_clean, evidence_level),
                 "end_state": end_state,
+                "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
                 "confidence": confidence,
                 "evidence_level": evidence_level,
                 "trace": trace,

sourcecode/pr_comment_renderer.py

@@ -0,0 +1,369 @@
+"""pr_comment_renderer.py — Renders review-pr output as a GitHub PR comment.
+
+Mandatory 5-section format:
+  1. PR Change Summary       — FACT only
+  2. Impacted Execution Flow — STRUCTURAL SIGNAL or FACT only, per-step evidence
+  3. Review Priority Order   — ranked by evidence-backed impact
+  4. Risk / Impact Signals   — labeled signals, never "risk" as conclusion
+  5. Review Guidance         — uncertain items, evidence gaps
+
+Contract:
+- Every statement carries an explicit epistemic label.
+- No speculation without label.
+- No hidden confidence blending.
+- Sections omitted when evidence is insufficient.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_BADGE: dict[str, str] = {
+    "FACT":                      "`FACT`",
+    "STRUCTURAL SIGNAL":         "`STRUCTURAL SIGNAL`",
+    "INFERRED (LOW CONFIDENCE)": "`INFERRED (LOW CONFIDENCE)`",
+    "OMITTED":                   "`OMITTED`",
+}
+
+_STRUCTURAL_EVIDENCE = frozenset({"direct_injection", "direct_call"})
+
+_MAX_PRIORITY_FILES = 10
+_MAX_FLOW_PATHS = 3
+_MAX_SIGNALS = 12
+_MAX_UNCERTAIN = 6
+
+
+def _badge(level: str) -> str:
+    return _BADGE.get(level, f"`{level}`")
+
+
+def _short(path: str) -> str:
+    parts = Path(path).parts
+    return "/".join(parts[-2:]) if len(parts) > 2 else path
+
+
+def _evidence_to_epistemic(evidence_level: str) -> str:
+    if evidence_level in _STRUCTURAL_EVIDENCE:
+        return "STRUCTURAL SIGNAL"
+    if evidence_level == "heuristic_only":
+        return "INFERRED (LOW CONFIDENCE)"
+    return "OMITTED"
+
+
+# ── Section 1: PR Change Summary ──────────────────────────────────────────────
+
+def _section_change_summary(out: dict) -> str:
+    runtime: list[dict] = out.get("runtime_changes", [])
+    build: dict = out.get("build_changes", {})
+    build_files: list[str] = build.get("files", []) if build else []
+    base = out.get("base_ref") or out.get("since") or "HEAD~1"
+
+    committed: list[dict] = out.get("committed_changes", [])
+    uncommitted: list[dict] = out.get("uncommitted_changes", [])
+
+    lines = [
+        "### 1. PR Change Summary",
+        "",
+        f"**Diff:** `git diff {base}...HEAD`  |  "
+        f"**Committed:** {len(committed)} files {_badge('FACT')}  |  "
+        f"**Unstaged:** {len(uncommitted)} files {_badge('FACT')}",
+        "",
+    ]
+
+    if uncommitted:
+        lines.append(
+            f"> **Note:** {len(uncommitted)} file(s) in working tree not committed — "
+            "present in analysis, absent from PR diff."
+        )
+        lines.append("")
+
+    if not runtime and not build_files:
+        lines.append("*No runtime files changed.*")
+        return "\n".join(lines)
+
+    lines += ["| File | Artifact Type | Role | Source |",
+              "|------|--------------|------|--------|"]
+
+    for rc in runtime:
+        path = rc.get("path", "")
+        atype = rc.get("artifact_type", "")
+        effect = rc.get("change_effect", {})
+        stmt = effect.get("statement", "") if isinstance(effect, dict) else ""
+        diff_src = rc.get("diff_source", "committed")
+        src_label = "committed" if "committed" in diff_src else "unstaged"
+        lines.append(f"| `{_short(path)}` | `{atype}` | {stmt} | {src_label} |")
+
+    for bf in build_files:
+        lines.append(f"| `{_short(bf)}` | `build_manifest` | build / dependency configuration | committed |")
+
+    lines.append("")
+    lines.append(f"*All file entries above are {_badge('FACT')} — directly observed in diff.*")
+    return "\n".join(lines)
+
+
+# ── Section 2: Impacted Execution Flow ────────────────────────────────────────
+
+def _section_execution_flow(out: dict) -> str:
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+
+    # Only STRUCTURAL SIGNAL or FACT paths — exclude heuristic_only
+    strong = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") in _STRUCTURAL_EVIDENCE
+    ]
+    weak = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") == "heuristic_only"
+    ]
+
+    lines = ["### 2. Impacted Execution Flow", ""]
+
+    if not strong and not weak:
+        lines.append("*No traceable execution flow — insufficient structural evidence.*")
+        return "\n".join(lines)
+
+    if strong:
+        for bi in strong[:_MAX_FLOW_PATHS]:
+            ev = bi.get("evidence_level", "")
+            ep = _evidence_to_epistemic(ev)
+            entry = bi.get("entry_point", "")
+            affected: list[str] = bi.get("affected_path", [])
+            end_state = bi.get("end_state", "")
+            trace: list[str] = bi.get("trace", [])
+
+            end_state_ep = bi.get("end_state_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+            steps = [f"`{entry}`"] + [f"`{s}`" for s in affected]
+            if end_state:
+                steps.append(f"**{end_state}** {_badge(end_state_ep)}")
+
+            lines.append(f"**Flow:** {' → '.join(steps)}")
+            lines.append(f"**Evidence:** {_badge(ep)}")
+
+            if trace:
+                for t in trace:
+                    lines.append(f"- {t}")
+            lines.append("")
+
+    if weak:
+        lines.append(f"**Excluded from flow** ({len(weak)} path(s) — evidence insufficient):")
+        for bi in weak[:3]:
+            entry = bi.get("entry_point", "")
+            lines.append(
+                f"- `{entry}` path — {_badge('INFERRED (LOW CONFIDENCE)')}: "
+                "class reference detected but no injection or call evidence"
+            )
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+# ── Section 3: Review Priority Order ─────────────────────────────────────────
+
+def _section_priority_order(out: dict) -> str:
+    order: list[str] = out.get("suggested_review_order", []) or out.get("review_hotspots", [])
+    runtime: list[dict] = out.get("runtime_changes", [])
+
+    cls_map: dict[str, dict] = {rc["path"]: rc for rc in runtime}
+
+    lines = ["### 3. Review Priority Order", ""]
+
+    if not order:
+        lines.append("*No priority order available — diff scope too narrow to rank.*")
+        return "\n".join(lines)
+
+    for i, path in enumerate(order[:_MAX_PRIORITY_FILES], 1):
+        rc = cls_map.get(path, {})
+        effect = rc.get("change_effect", {})
+        stmt = effect.get("statement", "application source") if isinstance(effect, dict) else "application source"
+        ep = effect.get("epistemic_level", "STRUCTURAL SIGNAL") if isinstance(effect, dict) else "STRUCTURAL SIGNAL"
+        atype = rc.get("artifact_type", "source")
+        lines.append(f"{i}. `{_short(path)}` — {_badge(ep)}: {atype} — {stmt}")
+
+    return "\n".join(lines)
+
+
+# ── Section 4: Risk / Impact Signals ─────────────────────────────────────────
+
+def _section_signals(out: dict) -> str:
+    lines = ["### 4. Risk / Impact Signals", ""]
+    signals: list[str] = []
+
+    # Security files in diff — FACT (files are in diff)
+    sec = out.get("security_impact", {})
+    if sec:
+        files: list[str] = sec.get("affected_resources", [])
+        ep = sec.get("epistemic_level", "STRUCTURAL SIGNAL")
+        basis = sec.get("basis", "")
+        if files:
+            names = ", ".join(f"`{_short(f)}`" for f in files)
+            signals.append(f"{_badge(ep)}: security-classified files changed — {names}")
+            if basis:
+                signals.append(f"  *Classification basis: {basis}*")
+        risk_ep = sec.get("risk_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+        signals.append(
+            f"{_badge(risk_ep)}: authentication / access-control behavior may be affected — "
+            "inspect changed security files to confirm"
+        )
+
+    # Transactional boundary — STRUCTURAL SIGNAL if @Transactional detected, else INFERRED
+    txn = out.get("transactional_impact", {})
+    if txn:
+        files_t: list[str] = txn.get("affected_transactions", [])
+        ep_t = txn.get("epistemic_level", "STRUCTURAL SIGNAL")
+        basis_t = txn.get("basis", "")
+        risk_ep_t = txn.get("risk_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+        if files_t:
+            names_t = ", ".join(f"`{_short(f)}`" for f in files_t)
+            signals.append(f"{_badge(ep_t)}: service/business-logic files changed — {names_t}")
+            if basis_t:
+                signals.append(f"  *Classification basis: {basis_t}*")
+        signals.append(
+            f"{_badge(risk_ep_t)}: transactional boundary may be affected — "
+            "@Transactional scope not confirmed by AST"
+        )
+
+    # Configuration files — FACT
+    cfg = out.get("configuration_impact", {})
+    if cfg:
+        cfg_files: list[str] = cfg.get("changed_configs", [])
+        if cfg_files:
+            names_c = ", ".join(f"`{_short(f)}`" for f in cfg_files)
+            signals.append(f"{_badge('FACT')}: configuration files modified — {names_c}")
+
+    # Behavioral impact signals — use each item's epistemic_level
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+    for bi in behavioral[:_MAX_FLOW_PATHS]:
+        for item in bi.get("impact", []):
+            stmt = item.get("statement", "")
+            ep_i = item.get("epistemic_level", "INFERRED (LOW CONFIDENCE)")
+            support = item.get("support", "")
+            if stmt:
+                signals.append(f"{_badge(ep_i)}: {stmt}")
+                if support:
+                    signals.append(f"  *{support}*")
+
+    # Runtime notes from execution paths
+    exec_paths: list[dict] = out.get("execution_paths", [])
+    seen_notes: set[str] = set()
+    for ep_dict in exec_paths:
+        entry_notes: list = ep_dict.get("entry_point", {}).get("notes", [])
+        path_notes: list = [n for item in ep_dict.get("path", []) for n in item.get("notes", [])]
+        for note_obj in entry_notes + path_notes:
+            if isinstance(note_obj, dict):
+                note = note_obj.get("note", "")
+                n_ep = note_obj.get("epistemic_level", "STRUCTURAL SIGNAL")
+                if note and note not in seen_notes:
+                    signals.append(f"{_badge(n_ep)}: {note}")
+                    seen_notes.add(note)
+
+    if not signals:
+        lines.append("*No impact signals detected — insufficient evidence.*")
+        return "\n".join(lines)
+
+    lines.extend(signals[:_MAX_SIGNALS])
+    return "\n".join(lines)
+
+
+# ── Section 5: Review Guidance ────────────────────────────────────────────────
+
+def _section_guidance(out: dict) -> str:
+    lines = ["### 5. Review Guidance", ""]
+
+    # Inspect first — top priority files
+    order: list[str] = out.get("suggested_review_order", []) or out.get("review_hotspots", [])
+    runtime: list[dict] = out.get("runtime_changes", [])
+    cls_map: dict[str, dict] = {rc["path"]: rc for rc in runtime}
+
+    if order:
+        lines.append("**Inspect first:**")
+        for path in order[:3]:
+            rc = cls_map.get(path, {})
+            effect = rc.get("change_effect", {})
+            stmt = effect.get("statement", "") if isinstance(effect, dict) else ""
+            ep = effect.get("epistemic_level", "STRUCTURAL SIGNAL") if isinstance(effect, dict) else "STRUCTURAL SIGNAL"
+            label = f" — {stmt}" if stmt else ""
+            lines.append(f"- `{_short(path)}`{label} {_badge(ep)}")
+        lines.append("")
+
+    # Uncertain — heuristic-only behavioral paths
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+    weak_paths = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") == "heuristic_only"
+    ]
+    if weak_paths:
+        lines.append("**Uncertain (heuristic-only — verify manually):**")
+        for bi in weak_paths[:_MAX_UNCERTAIN]:
+            entry = bi.get("entry_point", "")
+            affected: list[str] = bi.get("affected_path", [])
+            path_str = " → ".join(affected) if affected else "unknown"
+            lines.append(
+                f"- `{entry}` → {path_str} "
+                f"{_badge('INFERRED (LOW CONFIDENCE)')}: class reference only, no injection/call proof"
+            )
+        lines.append("")
+
+    # Evidence gaps
+    gaps: list[str] = out.get("gaps", [])
+    cov = out.get("test_coverage_risk", {})
+    test_files: list[str] = cov.get("changed_files_without_tests", [])
+    test_basis = cov.get("basis", "")
+    cov_ep = cov.get("epistemic_level", "INFERRED (LOW CONFIDENCE)")
+
+    gap_items: list[str] = list(gaps)
+    if test_files:
+        shown = test_files[:5]
+        omitted = len(test_files) - len(shown)
+        names = ", ".join(f"`{_short(f)}`" for f in shown)
+        suffix = f" +{omitted} more" if omitted else ""
+        gap_items.append(
+            f"changed files without test coverage: {names}{suffix} "
+            f"{_badge(cov_ep)}"
+            + (f" — {test_basis}" if test_basis else "")
+        )
+
+    if gap_items:
+        lines.append("**Evidence gaps / missing coverage:**")
+        for g in gap_items:
+            lines.append(f"- {g}")
+    else:
+        lines.append("*No evidence gaps detected.*")
+
+    return "\n".join(lines)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def render_github_comment(out: dict) -> str:
+    """Render review-pr TaskOutput dict as a GitHub PR comment (Markdown).
+
+    5 mandatory sections. Every statement carries an explicit epistemic label.
+    """
+    base = out.get("base_ref") or out.get("since") or "HEAD~1"
+    header = (
+        "## sourcecode PR Analysis\n\n"
+        f"**Base:** `{base}`  |  "
+        f"**Review type:** pull request  |  "
+        f"**Epistemic contract:** FACT · STRUCTURAL SIGNAL · INFERRED (LOW CONFIDENCE) · OMITTED"
+    )
+
+    sections = [
+        header,
+        _section_change_summary(out),
+        _section_execution_flow(out),
+        _section_priority_order(out),
+        _section_signals(out),
+        _section_guidance(out),
+    ]
+
+    footer = (
+        "*Generated by [sourcecode](https://github.com/sourcecode-ai/sourcecode). "
+        "Labels: "
+        "`FACT` = diff/AST evidence · "
+        "`STRUCTURAL SIGNAL` = annotation/import/wiring · "
+        "`INFERRED (LOW CONFIDENCE)` = heuristic pattern · "
+        "`OMITTED` = insufficient evidence.*"
+    )
+    sections.append(footer)
+
+    return "\n\n---\n\n".join(s for s in sections if s.strip())

sourcecode/prepare_context.py

@@ -1001,15 +1001,25 @@ class TaskContextBuilder:
             if _security_files:
                 _pr_security_impact = {
                     "affected_resources": _security_files,
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "files classified as security artifact type (name/annotation pattern)",
                     "risk_level": "high",
+                    "risk_epistemic_level": "INFERRED (LOW CONFIDENCE)",
                 }
             if _transaction_files:
                 _pr_transactional_impact = {
                     "affected_transactions": _transaction_files,
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "files classified as service/business_logic artifact type",
                     "risk": "possible transaction boundary change",
+                    "risk_epistemic_level": "INFERRED (LOW CONFIDENCE)",
                 }
             if _config_files:
-                _pr_configuration_impact = {"changed_configs": _config_files}
+                _pr_configuration_impact = {
+                    "changed_configs": _config_files,
+                    "epistemic_level": "FACT",
+                    "basis": "files present in diff",
+                }
 
             # Test coverage risk scoped to changed source files only
             _changed_src = [
@@ -1026,6 +1036,8 @@ class TaskContextBuilder:
             _pr_test_coverage_risk = {
                 "changed_files_without_tests": _untested_changed[:10],
                 "risk_level": _test_risk_level,
+                "epistemic_level": "INFERRED (LOW CONFIDENCE)",
+                "basis": f"{len(_untested_changed)} changed source files have no matching test file by stem",
             }
 
             # Pre-classify changed files once — reused for hotspots, order, and runtime/build split
@@ -1144,6 +1156,10 @@ class TaskContextBuilder:
                     "change_effect": {
                         "statement": _ARTIFACT_CHANGE_EFFECT.get(_f_atype, "application source (artifact role requires annotation inspection)"),
                         "classification_method": _f_cls.get("confidence", "low"),
+                        "epistemic_level": (
+                            "STRUCTURAL SIGNAL" if _f_cls.get("confidence", "low") == "high"
+                            else "INFERRED (LOW CONFIDENCE)"
+                        ),
                     },
                     "evidence_completeness": _impact_entry.get("evidence", {}),
                 }
@@ -1287,7 +1303,8 @@ class TaskContextBuilder:
                     relevant_files = sorted(_synonym_boosted, key=lambda rf: -rf.score)
                     _synonym_note = (
                         f"Frontend concept detected ({', '.join(_frontend_kws)}). "
-                        "Boosted backend service-layer and interceptor files as likely root cause."
+                        "Backend service-layer and interceptor files boosted by symptom keyword match "
+                        "[INFERRED (LOW CONFIDENCE) — pattern heuristic, not structural proof]."
                     )
                     symptom_note = _synonym_note
 
@@ -2706,9 +2723,14 @@ class TaskContextBuilder:
         # Without reverse dependency graph, we cannot make traceable structural claims.
         # Also gated on semantic diff evidence (api_change/security_change) per file.
         _has_graph_ev = bool(graph_edges)
-        behavioral_changes: list[str] = (
+        behavioral_changes: list[dict] = (
             [
-                f"{Path(_p).name}: {_CHANGE_EFFECT.get(_cls['artifact_type'], 'application source (artifact role requires annotation inspection)')} [diff_severity={diff_severities.get(_p)}]"
+                {
+                    "statement": f"{Path(_p).name}: {_CHANGE_EFFECT.get(_cls['artifact_type'], 'application source')}",
+                    "diff_severity": diff_severities.get(_p),
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "diff_severity in (api_change, security_change) with import-graph evidence present",
+                }
                 for _p, _cls in classifications.items()
                 if not _cls["is_noise"]
                 and diff_severities.get(_p, "unknown") in ("api_change", "security_change")
@@ -2716,26 +2738,52 @@ class TaskContextBuilder:
             if _has_graph_ev else []
         )
 
-        def _runtime_impact(tc: dict[str, int]) -> list[str]:
-            _ri: list[str] = []
-            # Only emit claims that are evidence-backed (annotation-confirmed roles)
+        def _runtime_impact(tc: dict[str, int]) -> list[dict]:
+            _ri: list[dict] = []
             if "entrypoint" in tc:
-                _ri.append("Entrypoint-classified file modified — restart required before deploying to production")
+                _ri.append({
+                    "signal": "entrypoint-classified file modified",
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "artifact_type=entrypoint confirmed by annotation or naming evidence",
+                })
             if "spring_config" in tc:
-                _ri.append("Spring @Configuration-classified file modified — bean context rebuild required on restart")
+                _ri.append({
+                    "signal": "Spring @Configuration-classified file modified",
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "@Configuration annotation detected in file content",
+                })
             if "security" in tc:
-                _ri.append("Security-classified file modified — inspect authentication and access control wiring")
+                _ri.append({
+                    "signal": "security-classified file modified",
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "artifact_type=security confirmed by annotation or naming evidence",
+                })
             if "db_migration" in tc:
-                _ri.append("Database schema migration pending — execute before deploying application")
-            # service transactional claim: only if @Service annotation confirmed (not source/unclassified)
+                _ri.append({
+                    "signal": "database schema migration file present in diff",
+                    "epistemic_level": "FACT",
+                    "basis": "artifact_type=db_migration (file extension/naming convention)",
+                })
             _svc = tc.get("service", 0)
             if _svc >= 2:
-                _ri.append(f"{_svc} @Service-annotated file(s) modified — verify business logic consistency")
+                _ri.append({
+                    "signal": f"{_svc} @Service-annotated file(s) modified",
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "@Service annotation detected in file content",
+                })
             _repo = tc.get("repository", 0) + tc.get("mapper", 0)
             if _repo > 0:
-                _ri.append(f"{_repo} persistence-classified component(s) modified — verify data access queries")
+                _ri.append({
+                    "signal": f"{_repo} persistence-classified component(s) modified",
+                    "epistemic_level": "STRUCTURAL SIGNAL",
+                    "basis": "artifact_type in (repository, mapper) confirmed by annotation evidence",
+                })
             if "build_manifest" in tc:
-                _ri.append("Build manifest modified — dependency resolution required before compile")
+                _ri.append({
+                    "signal": "build manifest modified",
+                    "epistemic_level": "FACT",
+                    "basis": "artifact_type=build_manifest (pom.xml/build.gradle/package.json naming)",
+                })
             return _ri
 
         _max_hop = max((e["hop"] for e in graph_edges), default=0)

{sourcecode-1.30.14.dist-info → sourcecode-1.30.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.14
+Version: 1.30.15
 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
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.14-blue)
+![Version](https://img.shields.io/badge/version-1.30.15-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.14
+# sourcecode 1.30.15
 ```
 
 ---
@@ -353,6 +353,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
 | `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
+| `--format TEXT` | Output format: `json` (default) \| `github-comment` (Markdown PR comment, `review-pr` only). |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
@@ -374,6 +375,9 @@ sourcecode prepare-context delta . --since main
 # Onboard with a ready-to-paste LLM prompt
 sourcecode prepare-context onboard --llm-prompt
 
+# PR analysis as a GitHub Markdown comment (paste directly into PR)
+sourcecode prepare-context review-pr --since main --format github-comment
+
 # List all tasks
 sourcecode prepare-context --task-help
 ```
@@ -444,22 +448,25 @@ sourcecode prepare-context review-pr
       "name": "Order",
       "entry_point": {
         "step": "OrderController.createOrder",
-        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+        "notes": [
+          { "note": "condition: authorization check present (@PreAuthorize / @Secured)",
+            "epistemic_level": "STRUCTURAL SIGNAL" }
+        ]
       },
       "path": [
         {
           "step": "ShippingService.process",
           "notes": [
-            "branch: Spring cache may short-circuit downstream call",
-            "async: runs in separate thread (@Async)"
+            { "note": "branch: Spring cache annotation present — downstream call may be short-circuited",
+              "epistemic_level": "STRUCTURAL SIGNAL" },
+            { "note": "async: @Async annotation present — runs in separate thread",
+              "epistemic_level": "STRUCTURAL SIGNAL" }
           ]
         },
-        {
-          "step": "OrderRepository.save",
-          "notes": []
-        }
+        { "step": "OrderRepository.save", "notes": [] }
       ],
-      "end_state": "DB write"
+      "end_state": "DB write",
+      "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)"
     }
   ]
 }
@@ -474,17 +481,33 @@ sourcecode prepare-context review-pr
 
 **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` |
+| Signal | Example code | Note emitted | Epistemic level |
+|--------|-------------|--------------|-----------------|
+| Auth guard | `@PreAuthorize`, `@Secured` | `condition: authorization check present (@PreAuthorize / @Secured)` | `STRUCTURAL SIGNAL` |
+| Auth context read | `isAuthenticated()`, `SecurityContextHolder` | `condition: reads authentication context` | `STRUCTURAL SIGNAL` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` | `INFERRED (LOW CONFIDENCE)` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` | `STRUCTURAL SIGNAL` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache annotation present — downstream call may be short-circuited` | `STRUCTURAL SIGNAL` |
+| Manual cache | `cache.get()`, `cacheManager.` | `branch: manual cache lookup detected — downstream call may be short-circuited` | `INFERRED (LOW CONFIDENCE)` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: Optional type in use — result may be absent` | `STRUCTURAL SIGNAL` |
+| Async thread | `@Async` | `async: @Async annotation present — runs in separate thread` | `STRUCTURAL SIGNAL` |
+| CompletableFuture | `CompletableFuture`, `.supplyAsync()` | `async: CompletableFuture detected — non-blocking execution` | `STRUCTURAL SIGNAL` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` | `STRUCTURAL SIGNAL` |
+| Kafka | `kafkaTemplate.`, `KafkaProducer` | `async: Kafka producer detected` | `STRUCTURAL SIGNAL` |
+| RabbitMQ | `rabbitTemplate.`, `amqpTemplate.` | `async: RabbitMQ producer detected` | `STRUCTURAL SIGNAL` |
+
+**Epistemic contract:**
+
+Every output field in `review-pr` carries an explicit `epistemic_level`:
+
+| Level | Meaning |
+|-------|---------|
+| `FACT` | Directly observed in diff (file present, config changed) |
+| `STRUCTURAL SIGNAL` | Annotation or type-system evidence in source (`@Service`, `@Transactional`, injection) |
+| `INFERRED (LOW CONFIDENCE)` | Heuristic pattern match — no full structural proof |
+| `OMITTED` | Insufficient evidence — field not emitted |
+
+No field blends certainty levels without labeling. `end_state` (e.g. `"DB write"`) is always accompanied by `end_state_epistemic_level: "INFERRED (LOW CONFIDENCE)"` — it is a keyword-match heuristic, not an AST-verified fact.
 
 **Other `review-pr` output fields:**
 
@@ -492,9 +515,9 @@ sourcecode prepare-context review-pr
 |-------|-------------|
 | `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 |
+| `security_impact` | Changed security-classified files (`epistemic_level: STRUCTURAL SIGNAL`) + risk note (`INFERRED (LOW CONFIDENCE)`) |
+| `transactional_impact` | Changed service/business-logic files with possible transaction boundary effect |
+| `test_coverage_risk` | Changed source files with no corresponding test (`epistemic_level: INFERRED (LOW CONFIDENCE)`) |
 | `affected_modules` | DDD domain modules touched by the change |
 
 ---

{sourcecode-1.30.14.dist-info → sourcecode-1.30.15.dist-info}/RECORD

@@ -1,10 +1,10 @@
-sourcecode/__init__.py,sha256=J6N6z5RQFo5wJ4DBIDbgaGji2fockYUeA6wyuudLbU4,104
+sourcecode/__init__.py,sha256=KYWNRSkxZmGHoH3tR6KjNwxcWag6VLEnGLf3A9Tt4E0,104
 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=VGCkJ9DC4U8_ZYJu-MV-TT3zAq4ZCeoyFZLgyN-6aEI,84488
+sourcecode/cli.py,sha256=Qrx5dsnGT_oAk3L2_yTvJDtHPWos7legr8HuWRlN4h4,84881
 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,11 +17,12 @@ 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=1XczDeeIjOplAAO6QLprwBEGFgHk-Qf4T8ZLeyKzgWY,27603
+sourcecode/flow_analyzer.py,sha256=dSiuY4w49k29jW_EPXUOND9B5uVbuCA7kjnuHi-pIWA,28781
 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=OD5dYHiPSk42XSFj0WNIeFS_HFdb4BmN2eY5lxn8vJ8,149941
+sourcecode/pr_comment_renderer.py,sha256=k5pCIP6iBNwy5UYPxu47CAq-62j4E9QZZOPyL3trH80,14799
+sourcecode/prepare_context.py,sha256=pStv1z7bO0_p7YmUTH6NSnc7xjmkNrA9Atdvp6y8UiY,152165
 sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=virVglafZufioHpZpwktjMvUiL0TZELWQCQnQNV8dFo,9360
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
@@ -63,8 +64,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.14.dist-info/METADATA,sha256=OyIxTxe6JrHhKVJJSCThUcol7s0ydMbdAls1m0q1ePE,26773
-sourcecode-1.30.14.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.30.14.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.30.14.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.30.14.dist-info/RECORD,,
+sourcecode-1.30.15.dist-info/METADATA,sha256=rPy2IhCkSCpdxG18m9r2jJKVGL-dLXGBHbYDFrxV4aE,28956
+sourcecode-1.30.15.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.30.15.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.30.15.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.30.15.dist-info/RECORD,,