@hoanghainh/komagu 2.0.0 → 2.1.0

package/assess/lsa/tests/test_nextjs.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Next.js stack detection and route inventory (Issue #324).
+
+Covers App Router route handlers (route groups, dynamic and catch-all segments, `export const`
+handlers), Pages Router API routes, server actions (file-level and inline "use server"), dynamic
+server-component pages, and middleware / proxy notes.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Dict, List
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from detect_stack import detect  # noqa: E402
+from lsa_common import load_config  # noqa: E402
+from map_routes import map_routes  # noqa: E402
+
+FILES: Dict[str, str] = {
+    "next.config.ts": "const nextConfig = {};\nexport default nextConfig;\n",
+    "src/proxy.ts": (
+        'import { NextResponse } from "next/server";\n'
+        "export async function proxy(request) { return NextResponse.next(); }\n"
+        'export const config = { matcher: ["/((?!_next|login).*)"] };\n'
+    ),
+    # unguarded BOLA: id from the path, no owner filter
+    "src/app/api/orders/[id]/route.ts": (
+        'import { db } from "@/db";\n'
+        "export async function GET(request, { params }) {\n"
+        "  const { id } = await params;\n"
+        "  return Response.json(await db.query.orders.findFirst({ where: eq(orders.id, id) }));\n"
+        "}\n"
+        "\n"
+        "export async function DELETE(request, { params }) {\n"
+        "  const session = await auth();\n"
+        "  await db.delete(orders).where(eq(orders.id, params.id));\n"
+        "  return new Response(null, { status: 204 });\n"
+        "}\n"
+    ),
+    # route group, export const with a guard wrapper, query + JSON body inputs
+    "src/app/(admin)/api/users/[userId]/route.ts": (
+        'import { withAuth } from "@/lib/auth/guard";\n'
+        "export const PATCH = withAuth(async (request, { actor, params }) => {\n"
+        "  const { role, tenantId } = await request.json();\n"
+        '  const dry = request.nextUrl.searchParams.get("dryRun");\n'
+        "  return changeRole(actor, params.userId, role);\n"
+        '}, { permission: "users.manage" });\n'
+    ),
+    "app/api/files/[...path]/route.js": "export async function GET(req, ctx) { return serve(ctx.params.path); }\n",
+    "app/api/health/route.ts": "export function GET() { return Response.json({ ok: true }); }\n",
+    # private folder: not routable
+    "app/_lib/route.ts": "export function GET() {}\n",
+    "pages/api/invoices/[invoiceId].ts": (
+        "export default async function handler(req, res) {\n"
+        '  if (req.method === "DELETE") { await removeInvoice(req.query.invoiceId); }\n'
+        '  if (req.method === "GET") { res.json(await getInvoice(req.query.invoiceId)); }\n'
+        "}\n"
+    ),
+    "pages/api/index.ts": "export default function handler(req, res) { res.json({}); }\n",
+    "src/app/orders/actions.ts": (
+        '"use server";\n'
+        'import { auth } from "@/auth";\n'
+        "export async function cancelOrder(orderId: number, reason: string) {\n"
+        "  const session = await auth();\n"
+        "  await db.update(orders).set({ status: 'cancelled' }).where(eq(orders.id, orderId));\n"
+        "}\n"
+        "export const archiveOrder = async (formData: FormData) => {\n"
+        '  const id = formData.get("orderId");\n'
+        "  await db.delete(orders).where(eq(orders.id, id));\n"
+        "};\n"
+        "function helper() {}\n"
+    ),
+    "src/app/orders/[code]/page.tsx": (
+        "export default async function OrderPage({ params }) {\n"
+        "  const { code } = await params;\n"
+        "  const order = await getOrderByCode(code);\n"
+        "  async function approve() {\n"
+        '    "use server";\n'
+        "    await approveOrder(order.id);\n"
+        "  }\n"
+        "  return <form action={approve}><p>{order.code}</p></form>;\n"
+        "}\n"
+    ),
+    "src/app/about/page.tsx": "export default function About() { return <p>about</p>; }\n",
+}
+
+
+def _write(root: Path) -> None:
+    for rel, text in FILES.items():
+        p = root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+
+
+def _routes(root: Path) -> List[Dict]:
+    cfg = load_config(None)
+    stacks = {s["id"] for s in detect(root, cfg)["stacks"]}
+    return map_routes(root, cfg, stacks)["candidates"]
+
+
+def _find(routes: List[Dict], method: str, path: str) -> Dict:
+    hits = [r for r in routes if r["path"] == path and method in r["method"]]
+    if len(hits) != 1:
+        raise AssertionError(f"{method} {path}: {len(hits)} hits in {[(r['method'], r['path']) for r in routes]}")
+    return hits[0]
+
+
+def _names(route: Dict) -> Dict[str, str]:
+    return {p["name"]: p["source"] for p in route["id_params"]}
+
+
+class TestNextjs(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls._td = tempfile.TemporaryDirectory()
+        cls.root = Path(cls._td.name)
+        _write(cls.root)
+        cls.routes = _routes(cls.root)
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls._td.cleanup()
+
+    def test_stack_detected(self) -> None:
+        prof = detect(self.root, load_config(None))
+        self.assertIn("node-nextjs", {s["id"] for s in prof["stacks"]})
+        self.assertIn("knowledge/stacks/nextjs.md", prof["knowledge_files"])
+
+    def test_all_routes_are_nextjs(self) -> None:
+        self.assertEqual({r["stack"] for r in self.routes}, {"node-nextjs"})
+
+    def test_route_handlers_per_method(self) -> None:
+        get = _find(self.routes, "GET", "/api/orders/{id}")
+        self.assertEqual(get["kind"], "declared_route")
+        self.assertEqual(get["handler"]["file"], "src/app/api/orders/[id]/route.ts")
+        self.assertEqual(get["handler"]["line"], 2)
+        self.assertEqual(_names(get), {"id": "path"})
+        self.assertTrue(get["needs_audit_hint"])
+        self.assertEqual(get["guard_hints"], [])
+        delete = _find(self.routes, "DELETE", "/api/orders/{id}")
+        self.assertTrue(any("auth()" in g["hint"] for g in delete["guard_hints"]))
+
+    def test_route_group_and_export_const(self) -> None:
+        patch = _find(self.routes, "PATCH", "/api/users/{userId}")
+        self.assertEqual(_names(patch), {"userId": "path", "role": "body", "tenantId": "body", "dryRun": "query"})
+        hints = " ".join(g["hint"] for g in patch["guard_hints"])
+        self.assertIn("withAuth", hints)
+        self.assertIn("users.manage", hints)
+
+    def test_catch_all_and_static(self) -> None:
+        _find(self.routes, "GET", "/api/files/{path*}")
+        self.assertEqual(_find(self.routes, "GET", "/api/health")["id_params"], [])
+
+    def test_private_folder_skipped(self) -> None:
+        self.assertFalse(any(r["handler"]["file"] == "app/_lib/route.ts" for r in self.routes))
+
+    def test_pages_api(self) -> None:
+        inv = _find(self.routes, "DELETE", "/api/invoices/{invoiceId}")
+        self.assertEqual(sorted(inv["method"]), ["DELETE", "GET"])
+        self.assertEqual(_names(inv)["invoiceId"], "path")
+        self.assertEqual(_find(self.routes, "ANY", "/api")["handler"]["file"], "pages/api/index.ts")
+
+    def test_server_actions(self) -> None:
+        cancel = _find(self.routes, "POST", "action:src/app/orders/actions.ts#cancelOrder")
+        self.assertEqual(_names(cancel), {"orderId": "body", "reason": "body"})
+        self.assertTrue(any("auth" in g["hint"] for g in cancel["guard_hints"]))
+        archive = _find(self.routes, "POST", "action:src/app/orders/actions.ts#archiveOrder")
+        self.assertEqual(_names(archive), {"orderId": "form"})
+        self.assertFalse(any(r["path"].endswith("#helper") for r in self.routes))
+
+    def test_inline_server_action_and_page(self) -> None:
+        _find(self.routes, "POST", "action:src/app/orders/[code]/page.tsx#approve")
+        page = _find(self.routes, "GET", "/orders/{code}")
+        self.assertEqual(page["kind"], "file_endpoint")
+        self.assertEqual(_names(page), {"code": "path"})
+        self.assertFalse(any(r["path"] == "/about" for r in self.routes))
+
+    def test_use_server_after_comments(self) -> None:
+        from nextjs_routes import _starts_with_use_server
+
+        self.assertTrue(_starts_with_use_server('// x\n/* y */\n  "use server";\nexport async function a() {}'))
+        self.assertFalse(_starts_with_use_server('import x from "y";\n"use server";'))
+        self.assertFalse(_starts_with_use_server("/*" + "*//*" * 5000))
+
+    def test_proxy_noted(self) -> None:
+        get = _find(self.routes, "GET", "/api/orders/{id}")
+        self.assertIn("src/proxy.ts", get["notes"])
+        self.assertIn("matcher", get["notes"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/assess/lsa/tests/test_privilege_tier2.py

@@ -242,6 +242,36 @@ class TestScoring(unittest.TestCase):
             self.assertEqual(report["per_category"]["mass_assignment"]["recall"], 0.0)
             self.assertNotIn("bola", report["per_category"])
 
+    def test_verdict_level_ignores_misplaced_findings(self) -> None:
+        """--verdicts credits the auditor's route / candidate verdict even when the finding has a wrong path (#286)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            truth = Path(tmp) / "gt.json"
+            write_json(truth, {"items": [
+                {"file": "admin.js", "line": 9, "category": "bfla", "vulnerable": True, "label": "BFLA"},
+                {"file": "admin.js", "line": 13, "category": "bfla", "vulnerable": False, "label": "SAFE-BFLA"},
+                {"file": "p.php", "line": 6, "category": "mass_assignment", "vulnerable": True, "label": "MASS"},
+                {"file": "p.php", "line": 9, "category": "mass_assignment", "vulnerable": False, "label": "SAFE-MASS"},
+            ]})
+            out = Path(tmp) / "out"
+            write_json(out / "findings.json", {"findings": [
+                {"finding_id": "BFLA-R-1-1", "category": "bfla", "status": "confirmed",
+                 "location": {"file": "routes.js", "start_line": 1}, "evidence": []}]})
+            write_json(out / "routes" / "routes-001.json", {"routes": [
+                {"route_id": "R-1", "handler": {"file": "admin.js", "line": 8}},
+                {"route_id": "R-2", "handler": {"file": "admin.js", "line": 12}}]})
+            write_json(out / "mass-assignment.candidates.json", {"candidates": [
+                {"candidate_id": "M-1", "file": "p.php", "line": 6}]})
+            write_json(out / "findings" / "priv-privilege-001.json", {
+                "privilege_route_verdicts": [{"route_id": "R-1", "verdict": "vulnerable"}],
+                "candidate_verdicts": [{"candidate_id": "M-1", "verdict": "needs_review"}], "findings": []})
+            res = subprocess.run([sys.executable, str(SCORE), "--verdicts", str(truth), str(out)], capture_output=True, text=True)
+            report = json.loads(res.stdout)
+            self.assertEqual(report["per_category"]["bfla"]["found"], 0)
+            self.assertEqual(report["verdict_level"]["bfla"], {"truth_vulnerable": 1, "found": 1, "recall": 1.0,
+                                                              "flagged_safe": [], "missed": []})
+            self.assertEqual(report["verdict_level"]["mass_assignment"]["found"], 1)
+            self.assertEqual(report["verdict_level"]["mass_assignment"]["flagged_safe"], [])
+
 
 if __name__ == "__main__":
     unittest.main()

package/operate/ai/anchoring.py

@@ -0,0 +1,130 @@
+"""Anchor model-written finding locations to the Tier 1 routes and candidates they refer to (#319).
+
+Small local models judge the right route or candidate but often write a wrong or non-existent path
+into the finding (Evaluation Run 4: `routes.js`, `app.py`, `dotnet-mvc/...`). Tier 1 already knows
+where every route handler and query / binding candidate is, so the location comes from there.
+
+Rules:
+- route findings (`route_id`): the file is the route handler's file; the model's line is kept when
+  it falls inside the handler span (handler line up to the next route in the same file, or the end
+  of the file), otherwise the handler line is used.
+- candidate findings (`candidate_id`): file and line are the candidate's.
+- evidence entries are re-pointed the same way; entries whose file does not exist and cannot be
+  re-pointed are dropped.
+- findings with an unknown `route_id` / `candidate_id` keep their location, get `confidence: low`
+  and are reported as unanchored.
+
+Standard-library only (Python 3.8+ compatible).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+CANDIDATE_FILES = ("injection.candidates.json", "mass-assignment.candidates.json")
+
+
+@dataclass(frozen=True)
+class Anchor:
+    file: str
+    line: int
+    end_line: Optional[int]  # last line of the handler span; None for an exact candidate site
+
+
+@dataclass
+class AnchorReport:
+    moved: List[str] = field(default_factory=list)
+    unanchored: List[str] = field(default_factory=list)
+
+
+def _read(path: Path) -> Dict[str, Any]:
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+        return doc if isinstance(doc, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _line_count(target_dir: Path, rel_file: str) -> int:
+    try:
+        return len((target_dir / rel_file).read_text(encoding="utf-8", errors="replace").splitlines())
+    except OSError:
+        return 0
+
+
+def load_anchors(out_dir: Path, target_dir: Path) -> Dict[str, Anchor]:
+    """route_id / candidate_id -> Anchor, from OUT/routes/*.json and the Tier 1 candidate files."""
+    handlers: List[Tuple[str, int, str]] = []
+    for path in sorted((out_dir / "routes").glob("*.json")):
+        for route in _read(path).get("routes") or []:
+            if not isinstance(route, dict):
+                continue
+            handler = route.get("handler") or {}
+            if route.get("route_id") and handler.get("file") and isinstance(handler.get("line"), int):
+                handlers.append((handler["file"], handler["line"], route["route_id"]))
+
+    anchors: Dict[str, Anchor] = {}
+    for rel_file, line, route_id in handlers:
+        later = sorted(ln for f, ln, _ in handlers if f == rel_file and ln > line)
+        end = later[0] - 1 if later else max(_line_count(target_dir, rel_file), line)
+        anchors[route_id] = Anchor(rel_file, line, end)
+
+    for name in CANDIDATE_FILES:
+        for cand in _read(out_dir / name).get("candidates") or []:
+            if isinstance(cand, dict) and cand.get("candidate_id") and cand.get("file") and isinstance(cand.get("line"), int):
+                anchors[cand["candidate_id"]] = Anchor(cand["file"], cand["line"], None)
+    return anchors
+
+
+def _anchored_line(anchor: Anchor, line: Any) -> int:
+    if anchor.end_line is None or not isinstance(line, int):
+        return anchor.line
+    return line if anchor.line <= line <= anchor.end_line else anchor.line
+
+
+def _repoint_evidence(evidence: Any, anchor: Anchor, target_dir: Path) -> List[Dict[str, Any]]:
+    kept = []
+    for ev in evidence if isinstance(evidence, list) else []:
+        if not isinstance(ev, dict):
+            continue
+        rel = str(ev.get("file") or "")
+        if rel == anchor.file or (rel and (target_dir / rel).is_file()):
+            kept.append(ev)
+        elif anchor.end_line is not None and isinstance(ev.get("line"), int) and anchor.line <= ev["line"] <= anchor.end_line:
+            kept.append({**ev, "file": anchor.file})
+    return kept or [{"file": anchor.file, "line": anchor.line, "why": "Location taken from the Tier 1 inventory"}]
+
+
+def anchor_finding(finding: Dict[str, Any], anchors: Dict[str, Anchor], target_dir: Path) -> Tuple[Dict[str, Any], Optional[bool]]:
+    """Return (finding with Tier 1 location, moved?); moved is None when the finding has no known anchor."""
+    key = finding.get("route_id") or finding.get("candidate_id")
+    anchor = anchors.get(key) if key else None
+    if anchor is None:
+        return {**finding, "confidence": "low"}, None
+    loc = finding.get("location") if isinstance(finding.get("location"), dict) else {}
+    # a wrong path with a line inside the handler span is most likely the right line in the wrong file
+    new_loc = {**loc, "file": anchor.file, "start_line": _anchored_line(anchor, loc.get("start_line"))}
+    if anchor.end_line is None:
+        new_loc.pop("end_line", None)
+    moved = (loc.get("file"), loc.get("start_line")) != (new_loc["file"], new_loc["start_line"])
+    evidence = _repoint_evidence(finding.get("evidence"), anchor, target_dir)
+    return {**finding, "location": new_loc, "evidence": evidence}, moved
+
+
+def anchor_findings(findings: List[Dict[str, Any]], anchors: Dict[str, Anchor], target_dir: Path,
+                    report: AnchorReport) -> List[Dict[str, Any]]:
+    out = []
+    for f in findings:
+        if not isinstance(f, dict):
+            out.append(f)
+            continue
+        anchored, moved = anchor_finding(f, anchors, target_dir)
+        if moved is None:
+            report.unanchored.append(str(f.get("finding_id")))
+        elif moved:
+            report.moved.append(str(f.get("finding_id")))
+        out.append(anchored)
+    return out

package/operate/ai/client.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import re
+import time
 import urllib.error
 import urllib.request
 from typing import Any, Dict, List, Optional
@@ -30,6 +31,8 @@ class LLMClient:
         self.model = model
         self.api_key = api_key or "ollama"
         self.timeout = timeout
+        # Running totals across chat() calls, read by the runner for ai-run-stats.json
+        self.usage: Dict[str, float] = {"calls": 0, "prompt_tokens": 0, "completion_tokens": 0, "seconds": 0.0}
 
     def chat(
         self,
@@ -54,10 +57,12 @@ class LLMClient:
         }
 
         req = urllib.request.Request(self.endpoint, data=data, headers=headers, method="POST")
+        started = time.monotonic()
         try:
             with urllib.request.urlopen(req, timeout=self.timeout) as resp:
                 body = resp.read().decode("utf-8")
                 res_json = json.loads(body)
+                self._record_usage(res_json.get("usage") or {}, time.monotonic() - started)
                 choices = res_json.get("choices", [])
                 if not choices:
                     raise RuntimeError(f"LLM API returned no choices: {body}")
@@ -69,6 +74,14 @@ class LLMClient:
         except urllib.error.URLError as e:
             raise RuntimeError(f"Failed to connect to LLM endpoint at {self.endpoint}: {e.reason}") from e
 
+    def _record_usage(self, usage: Dict[str, Any], seconds: float) -> None:
+        self.usage = {
+            "calls": self.usage["calls"] + 1,
+            "prompt_tokens": self.usage["prompt_tokens"] + int(usage.get("prompt_tokens") or 0),
+            "completion_tokens": self.usage["completion_tokens"] + int(usage.get("completion_tokens") or 0),
+            "seconds": round(self.usage["seconds"] + seconds, 3),
+        }
+
     @staticmethod
     def extract_json(content: str) -> Any:
         """Extract and parse JSON from Markdown code blocks or raw text string."""

package/operate/ai/context.py

@@ -0,0 +1,105 @@
+"""Code context for the headless agents: snippets, server-side includes and bound model classes.
+
+Standard-library only (Python 3.8+ compatible).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def _read_snippet(target_dir: Path, rel_file: str, line: int, radius: int = 15) -> str:
+    """Read a window of code around target line from the audited repository."""
+    full_path = target_dir / rel_file
+    if not full_path.is_file():
+        return f"[File not found: {rel_file}]"
+    try:
+        lines = full_path.read_text(encoding="utf-8", errors="replace").splitlines()
+        start = max(0, line - radius - 1)
+        end = min(len(lines), line + radius)
+        numbered = [f"{i + 1:4d} | {lines[i]}" for i in range(start, end)]
+        return "\n".join(numbered)
+    except Exception as e:
+        return f"[Error reading {rel_file}: {e}]"
+
+
+# Server-side includes whose content a verifier must see to judge a control (PHP, Classic ASP, ColdFusion)
+_INCLUDE_RE = re.compile(
+    r"(?:require|include)(?:_once)?\s*\(?\s*['\"]([^'\"]+)['\"]"
+    r"|<!--\s*#include\s+(?:file|virtual)\s*=\s*\"([^\"]+)\""
+    r"|<cfinclude\s+template\s*=\s*\"([^\"]+)\"",
+    re.IGNORECASE,
+)
+
+
+def _included_files(target_dir: Path, rel_file: str) -> List[str]:
+    """Repository-relative paths of files that rel_file includes, if they exist."""
+    target_dir = target_dir.resolve()
+    path = target_dir / rel_file
+    if not path.is_file():
+        return []
+    text = path.read_text(encoding="utf-8", errors="replace")
+    found: List[str] = []
+    for m in _INCLUDE_RE.finditer(text):
+        ref = next(g for g in m.groups() if g)
+        candidate = (path.parent / ref).resolve()
+        try:
+            rel = str(candidate.relative_to(target_dir))
+        except ValueError:
+            continue
+        if candidate.is_file() and rel not in found:
+            found.append(rel)
+    return found
+
+
+_MODEL_EXTENSIONS = (".java", ".cs", ".vb", ".php", ".py", ".js", ".ts", ".rb", ".cfc")
+_NEW_OBJECT_RE = re.compile(r"\bnew\s+([A-Z][A-Za-z0-9_]*)\s*\(")
+
+
+def _model_source(target_dir: Path, name: Optional[str], near_file: str = "", near_line: int = 1) -> Optional[Dict[str, Any]]:
+    """Definition of the bound model class, so the privilege auditor can see its fields (#319).
+
+    name is the Tier 1 binding target; when it is unknown, the first `new Foo(` near the binding is used.
+    """
+    if not name and near_file:
+        m = _NEW_OBJECT_RE.search(_read_snippet(target_dir, near_file, near_line, radius=4))
+        name = m.group(1) if m else None
+    if not name or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+        return None
+    class_re = re.compile(rf"\bclass\s+{name}\b")
+    # same application and language as the binding: a Node route must not pick up a PHP model of the same name
+    suffix = Path(near_file).suffix.lower()
+    suffixes = (suffix,) if suffix in _MODEL_EXTENSIONS else _MODEL_EXTENSIONS
+    parts = Path(near_file).parts
+    root = target_dir / parts[0] if len(parts) > 1 and (target_dir / parts[0]).is_dir() else target_dir
+    for path in sorted(root.rglob("*")):
+        if path.suffix.lower() not in suffixes or not path.is_file():
+            continue
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        for i, text in enumerate(lines):
+            if class_re.search(text):
+                rel = str(path.relative_to(target_dir))
+                return {"class": name, "file": rel, "code": _read_snippet(target_dir, rel, i + 16, radius=15)}
+    return {"class": name, "file": None, "code": "[definition not found in the repository]"}
+
+
+def _verification_context(target_dir: Path, finding: Dict[str, Any]) -> Dict[str, Any]:
+    """Code the verifier needs: the finding's site, its file header, evidence lines and included files."""
+    loc = finding.get("location") or {}
+    rel = str(loc.get("file") or "")
+    line = int(loc.get("start_line") or 1)
+    ctx: Dict[str, Any] = {"location": _read_snippet(target_dir, rel, line, radius=20)}
+    if line > 40:
+        ctx["file_header"] = _read_snippet(target_dir, rel, 13, radius=12)
+    others = []
+    for ev in finding.get("evidence") or []:
+        if isinstance(ev, dict) and ev.get("file") and ev.get("file") != rel:
+            others.append({"file": ev["file"], "code": _read_snippet(target_dir, str(ev["file"]), int(ev.get("line") or 1), radius=6)})
+    if others:
+        ctx["evidence"] = others[:3]
+    includes = [{"file": inc, "code": _read_snippet(target_dir, inc, 30, radius=30)} for inc in _included_files(target_dir, rel)[:3]]
+    if includes:
+        ctx["included_files"] = includes
+    return ctx