every-cli 0.1.0__py3-none-any.whl

every/judge.py

@@ -0,0 +1,288 @@
+"""The Jev client. Port of reference/sweep.py: embed-per-question batching,
+token-budget packing, bounded concurrency, backoff on overload, split on too-big."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from dataclasses import dataclass, field
+
+import httpx
+
+from .units import (OUTPUT_RESERVE_PER_Q, REQUEST_FIXED_TOKENS, estimate_tokens)
+
+API_URL = "https://api.typesafe.ai/v1/systemone"
+MODEL = "jev-latest"
+MAX_ATTEMPTS = 6
+
+INSTRUCTIONS = (
+    "Answer for the single function in `unit` only. Judge from its source, its file "
+    "path, and any context included with it. Do not assume anything about code you "
+    "cannot see. Question: {question}"
+)
+
+
+@dataclass
+class Item:
+    id: str
+    payload: dict
+    est: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.est:
+            self.est = estimate_tokens(json.dumps(self.payload))
+
+
+@dataclass
+class Stats:
+    requests: int = 0
+    retries: int = 0
+    splits: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    est_tokens: int = 0
+    failed: int = 0
+    latencies: list = field(default_factory=list)
+    last_error: str = ""
+
+    def merge(self, other: "Stats") -> "Stats":
+        return Stats(
+            requests=self.requests + other.requests, retries=self.retries + other.retries,
+            splits=self.splits + other.splits, input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+            est_tokens=self.est_tokens + other.est_tokens, failed=self.failed + other.failed,
+            latencies=self.latencies + other.latencies, last_error=other.last_error or self.last_error,
+        )
+
+
+class TooBig(Exception):
+    pass
+
+
+class Fatal(Exception):
+    pass
+
+
+class Unauthorized(Fatal):
+    """401/403 - the API key was rejected; aborts the whole run."""
+
+
+def criteria_for(question: str) -> dict:
+    return {
+        "true": f"Yes. For this function it is true that: {question}",
+        "false": f"No. For this function it is not true that: {question}",
+    }
+
+
+def request_body(question: str, repo_card: dict, batch: list) -> dict:
+    return {
+        "model": MODEL,
+        "state": {"repo": repo_card,
+                  "note": "Each question below is independent; judge only the unit inside it."},
+        "questions": {
+            f"q{i}": {
+                "type": "noul",
+                "instructions": {"question": INSTRUCTIONS.format(question=question), "unit": it.payload},
+                "criteria": criteria_for(question),
+            }
+            for i, it in enumerate(batch)
+        },
+    }
+
+
+def pack(items: list, budget: int, width: int | None = None) -> list:
+    batches, cur, tok = [], [], REQUEST_FIXED_TOKENS
+    for it in items:
+        t = it.est + OUTPUT_RESERVE_PER_Q
+        if cur and (tok + t > budget or (width and len(cur) >= width)):
+            batches.append(cur)
+            cur, tok = [], REQUEST_FIXED_TOKENS
+        cur.append(it)
+        tok += t
+    if cur:
+        batches.append(cur)
+    return batches
+
+
+def _is_too_big(response) -> bool:
+    try:
+        detail = response.json().get("detail") or {}
+        if isinstance(detail, dict) and detail.get("error_type") == "max_tokens_exceeded":
+            return True
+    except ValueError:
+        pass
+    return "max_tokens_exceeded" in response.text
+
+
+class Judge:
+    def __init__(self, api_key: str, *, api_url: str = API_URL, depth: int = 4,
+                 budget: int = 45_000, timeout: float = 90.0, transport=None, sleep=None) -> None:
+        self.api_key = api_key
+        self.api_url = api_url
+        self.depth = depth
+        self.budget = budget
+        self.timeout = timeout
+        self.transport = transport
+        self._sleep = sleep or asyncio.sleep
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+
+    async def _send(self, client, question, repo_card, batch, stats: Stats) -> dict:
+        body = request_body(question, repo_card, batch)
+        for attempt in range(MAX_ATTEMPTS):
+            last = attempt == MAX_ATTEMPTS - 1
+            t0 = time.perf_counter()
+            try:
+                r = await client.post(self.api_url, json=body)
+            except httpx.HTTPError:          # timeouts, transport errors, protocol errors
+                stats.retries += 1
+                if not last:
+                    await self._sleep(0.5 * 2 ** attempt + random.random() * 0.3)
+                continue
+            stats.latencies.append((time.perf_counter() - t0) * 1000)
+            stats.requests += 1
+            if r.status_code in (401, 403):
+                raise Unauthorized(f"HTTP {r.status_code}: API key rejected")
+            if r.status_code == 200:
+                try:
+                    data = r.json()
+                except ValueError:
+                    raise Fatal("malformed JSON in 200 response")
+                if not isinstance(data, dict):
+                    raise Fatal("unexpected JSON shape in 200 response")
+                usage = data.get("usage") or {}
+                stats.input_tokens += int(usage.get("input_tokens", 0) or 0)
+                stats.output_tokens += int(usage.get("output_tokens", 0) or 0)
+                stats.est_tokens += sum(it.est for it in batch) + REQUEST_FIXED_TOKENS
+                answers = data.get("answers") or {}
+                out = {}
+                for i, it in enumerate(batch):
+                    a = answers.get(f"q{i}")
+                    if isinstance(a, dict) and isinstance(a.get("noul"), (int, float)):
+                        out[it.id] = float(a["noul"])
+                return out
+            if r.status_code == 400 and _is_too_big(r):
+                raise TooBig()
+            if r.status_code in (429, 529) or r.status_code >= 500:
+                stats.retries += 1
+                if not last:
+                    await self._sleep(0.5 * 2 ** attempt + random.random() * 0.3)
+                continue
+            raise Fatal(f"HTTP {r.status_code}: {r.text[:200]}")
+        raise Fatal("retries exhausted")
+
+    async def _process(self, client, batch, question, repo_card, stats: Stats, results: dict,
+                       on_result, queue: asyncio.Queue) -> None:
+        """Judge one batch; split, truncate, or mark failed. Never raises."""
+        try:
+            got = await self._send(client, question, repo_card, batch, stats)
+        except Unauthorized:
+            raise
+        except TooBig:
+            if len(batch) > 1:
+                stats.splits += 1
+                mid = len(batch) // 2
+                queue.put_nowait(batch[:mid])
+                queue.put_nowait(batch[mid:])
+                return
+            it = batch[0]
+            if it.payload.get("truncated"):
+                stats.failed += 1
+                return
+            src = it.payload.get("source", "")
+            it.payload = {**it.payload, "source": src[: max(1, len(src) // 2)] + "\n[truncated]", "truncated": True}
+            it.est = estimate_tokens(json.dumps(it.payload))
+            queue.put_nowait([it])
+            return
+        except Fatal as e:
+            stats.failed += len(batch)
+            stats.last_error = str(e)
+            return
+        except Exception as e:               # one bad batch must never take the run down
+            stats.failed += len(batch)
+            stats.last_error = f"{type(e).__name__}: {e}"[:200]
+            return
+        stats.failed += sum(1 for it in batch if it.id not in got)
+        results.update(got)
+        if on_result and got:
+            try:
+                on_result(got)
+            except Exception as e:      # a side effect must never take the run down
+                stats.last_error = f"on_result: {type(e).__name__}: {e}"[:200]
+
+    async def _run(self, items, question, repo_card, stats: Stats, on_result) -> dict:
+        queue: asyncio.Queue = asyncio.Queue()
+        for b in pack(items, self.budget):
+            queue.put_nowait(b)
+        results: dict = {}
+
+        async def worker(client):
+            while True:
+                batch = await queue.get()      # stays alive until cancelled; splits refill the queue
+                try:
+                    await self._process(client, batch, question, repo_card, stats, results, on_result, queue)
+                finally:
+                    queue.task_done()
+
+        async with httpx.AsyncClient(headers=self._headers(), timeout=self.timeout,
+                                     transport=self.transport) as client:
+            workers = [asyncio.create_task(worker(client)) for _ in range(self.depth)]
+            joiner = asyncio.create_task(queue.join())
+            done, _ = await asyncio.wait({joiner, *workers}, return_when=asyncio.FIRST_COMPLETED)
+            for t in (joiner, *workers):
+                t.cancel()
+            await asyncio.gather(joiner, *workers, return_exceptions=True)
+            first = None
+            for t in done:
+                if t is not joiner and not t.cancelled() and t.exception() is not None:
+                    first = first or t.exception()
+            if first is not None:
+                raise first
+        return results
+
+    def judge(self, items: list, question: str, repo_card: dict, on_result=None) -> tuple:
+        stats = Stats()
+        results = asyncio.run(self._run(items, question, repo_card, stats, on_result))
+        return results, stats
+
+    def judge_with_reask(self, items: list, question: str, repo_card: dict, *,
+                         above: float, band: float = 0.10, on_result=None) -> tuple:
+        scores, stats = self.judge(items, question, repo_card, on_result)
+        near = [it for it in items if it.id in scores and abs(scores[it.id] - above) <= band]
+        if not near:
+            return scores, stats
+        random.Random(7).shuffle(near)
+        second, stats2 = self.judge(near, question, repo_card, on_result)
+        for uid, s in second.items():
+            scores[uid] = (scores[uid] + s) / 2
+        return scores, stats.merge(stats2)
+
+    def choice(self, state: dict, instructions: str, criteria: dict) -> str | None:
+        """One `choice` question. Returns the chosen key, or None on any failure - never raises."""
+        body = {"model": MODEL, "state": state,
+                "questions": {"c": {"type": "choice", "instructions": instructions, "criteria": criteria}}}
+
+        async def go():
+            try:
+                async with httpx.AsyncClient(headers=self._headers(), timeout=self.timeout,
+                                             transport=self.transport) as client:
+                    r = await client.post(self.api_url, json=body)
+                if r.status_code in (401, 403):
+                    raise Unauthorized(f"HTTP {r.status_code}: API key rejected")
+                if r.status_code != 200:
+                    return None
+                data = r.json()
+                if not isinstance(data, dict):
+                    return None
+                answer = (data.get("answers") or {}).get("c")
+                if not isinstance(answer, dict):
+                    return None
+                chosen = answer.get("choice")
+                return chosen if isinstance(chosen, str) else None
+            except (httpx.HTTPError, ValueError, TypeError, AttributeError):
+                return None
+
+        return asyncio.run(go())

every/neighborhood.py

@@ -0,0 +1,45 @@
+"""Bring the context to the question: per-unit text for stage 1 and stage 2."""
+
+from __future__ import annotations
+
+from .units import estimate_tokens
+
+SIGNATURE_CHARS = 160
+
+
+def signature(unit) -> str:
+    first = unit.source.splitlines()[0] if unit.source else unit.name
+    return first[:SIGNATURE_CHARS]
+
+
+def stage1_text(unit, index) -> str:
+    parts = [unit.source]
+    callees = index.callees_of(unit)
+    callers = index.callers_of(unit)
+    if callees:
+        parts.append("# calls:\n" + "\n".join(f"  {c.file}:{c.start_line} {signature(c)}" for c in callees))
+    if callers:
+        parts.append("# called by:\n" + "\n".join(f"  {c.file}:{c.start_line} {signature(c)}" for c in callers))
+    return "\n\n".join(parts)
+
+
+def stage2_text(unit, index, budget_tokens: int = 40_000) -> str:
+    parts = [unit.source]
+    used = estimate_tokens(unit.source)
+    seen = {unit.id}
+    frontier = [("calls", c) for c in index.callees_of(unit)] + \
+               [("called by", c) for c in index.callers_of(unit)]
+    while frontier:
+        relation, n = frontier.pop(0)
+        if n.id in seen:
+            continue
+        seen.add(n.id)
+        block = f"# {relation}: {n.file}:{n.start_line} {n.name}\n{n.source}"
+        cost = estimate_tokens(block)
+        if used + cost > budget_tokens:
+            break
+        parts.append(block)
+        used += cost
+        frontier += [("calls", c) for c in index.callees_of(n)] + \
+                    [("called by", c) for c in index.callers_of(n)]
+    return "\n\n".join(parts)

every/report.py

@@ -0,0 +1,63 @@
+"""Turn scores into a ranked table or JSON."""
+
+from __future__ import annotations
+
+import json
+
+DIM, RESET = "\033[2m", "\033[0m"
+
+
+def build_rows(units: list, scores: dict, stage: dict) -> list:
+    rows = []
+    for u in units:
+        if u.id not in scores:
+            continue
+        rows.append({
+            "score": scores[u.id], "file": u.file, "line": u.start_line, "end_line": u.end_line,
+            "function": u.name, "language": u.lang, "kind": u.kind, "stage": stage.get(u.id, 1),
+        })
+    rows.sort(key=lambda r: (-r["score"], r["file"], r["line"]))
+    return rows
+
+
+def select_rows(rows: list, above: float, top: int) -> list:
+    hits = [r for r in rows if r["score"] >= above]
+    return hits if len(hits) >= top else rows[:top]
+
+
+def _header(meta: dict) -> str:
+    line = (f"scanned {meta['units']:,} functions in {meta['files']:,} files ...   "
+            f"{meta['seconds']:.1f}s   ${meta['cost_usd']:.2f}   class: {meta['class']}")
+    if meta.get("coverage") == "partial":
+        line += "   coverage: partial (neighborhood-level)"
+    if meta.get("partial"):
+        line += "   [interrupted - partial results]"
+    return line
+
+
+def render_table(rows: list, meta: dict, above: float, top: int, color: bool) -> str:
+    out = [_header(meta), ""]
+    selected = select_rows(rows, above, top)
+    shown = selected[:top]
+    width = max((len(f"{r['file']}:{r['line']}") for r in shown), default=10)
+    for r in shown:
+        loc = f"{r['file']}:{r['line']}"
+        line = f" {r['score']:.2f}  {loc:<{width}}   {r['function']}"
+        if r["score"] < above:
+            line += f"   (below {above:.2f})"
+            if color:
+                line = DIM + line + RESET
+        out.append(line)
+    hits = sum(1 for r in rows if r["score"] >= above)
+    out.append("")
+    footer = f" {hits} hits >= {above:.2f} out of {meta['units']:,} functions"
+    if len(selected) > len(shown):
+        footer += f"   (showing {len(shown)}; use --top to see more)"
+    out.append(footer)
+    if meta.get("failed_units"):
+        out.append(f" {meta['failed_units']} functions could not be judged")
+    return "\n".join(out)
+
+
+def render_json(rows: list, meta: dict) -> str:
+    return json.dumps({"results": rows, "meta": meta}, indent=1)

every/selftest.py

@@ -0,0 +1,83 @@
+"""A bundled labelled set: ten functions that swallow errors, ten that don't."""
+
+from __future__ import annotations
+
+from .units import DEFAULT_ABOVE as ABOVE
+from .judge import Item, Judge
+
+SELFTEST_QUESTION = ("Does this function catch an exception or receive an error and then ignore it, "
+                     "without handling, logging, re-raising, or returning it?")
+
+POSITIVES = [
+    ("swallow_pass", "def swallow_pass(path):\n    try:\n        return open(path).read()\n    except Exception:\n        pass\n"),
+    ("swallow_write_failure", "def swallow_write_failure(path, data):\n    try:\n        with open(path, 'w') as fh:\n            fh.write(data)\n    except OSError:\n        pass\n"),
+    ("swallow_bare_except", "def swallow_bare_except(client):\n    try:\n        client.close()\n    except:\n        pass\n"),
+    ("swallow_continue", "def swallow_continue(items):\n    out = []\n    for i in items:\n        try:\n            out.append(parse(i))\n        except Exception:\n            continue\n    return out\n"),
+    ("swallow_ellipsis", "def swallow_ellipsis(conn):\n    try:\n        conn.commit()\n    except Exception:\n        ...\n"),
+    ("swallow_comment_only", "def swallow_comment_only(sock):\n    try:\n        sock.shutdown()\n    except OSError:\n        # already closed\n        pass\n"),
+    ("swallow_go_style", "def swallow_go_style(cmd):\n    result, err = run(cmd)\n    return result\n"),
+    ("swallow_payment_error", "def swallow_payment_error(order):\n    try:\n        charge(order)\n    except PaymentError:\n        pass\n    order.status = 'paid'\n"),
+    ("swallow_nested", "def swallow_nested(rows):\n    for r in rows:\n        try:\n            try:\n                save(r)\n            except KeyError:\n                pass\n        except Exception:\n            pass\n"),
+    ("swallow_callback_error", "def swallow_callback_error(cb):\n    try:\n        cb()\n    except BaseException:\n        return\n"),
+]
+
+NEGATIVES = [
+    ("logs_and_reraises", "def logs_and_reraises(path):\n    try:\n        return open(path).read()\n    except OSError as e:\n        log.error('read failed: %s', e)\n        raise\n"),
+    ("returns_error", "def returns_error(x):\n    try:\n        return int(x), None\n    except ValueError as e:\n        return None, e\n"),
+    ("no_try_at_all", "def no_try_at_all(a, b):\n    return a + b\n"),
+    ("wraps_and_raises", "def wraps_and_raises(url):\n    try:\n        return fetch(url)\n    except TimeoutError as e:\n        raise ServiceError('upstream timeout') from e\n"),
+    ("handles_with_fallback_and_log", "def handles_with_fallback_and_log(cfg):\n    try:\n        return cfg['port']\n    except KeyError:\n        log.warning('port missing, using default')\n        return 8080\n"),
+    ("finally_only", "def finally_only(conn):\n    try:\n        conn.execute('BEGIN')\n    finally:\n        conn.close()\n"),
+    ("checks_error_value", "def checks_error_value(cmd):\n    result, err = run(cmd)\n    if err is not None:\n        raise RuntimeError(err)\n    return result\n"),
+    ("retries_then_raises", "def retries_then_raises(op):\n    for attempt in range(3):\n        try:\n            return op()\n        except IOError:\n            if attempt == 2:\n                raise\n"),
+    ("records_metric", "def records_metric(job):\n    try:\n        job.run()\n    except Exception as e:\n        metrics.increment('job.failed')\n        raise\n"),
+    ("plain_read_no_error_path", "def plain_read_no_error_path(path):\n    with open(path) as fh:\n        return fh.read()\n"),
+]
+
+
+def _items(rows, label):
+    # The label lives only in the id (never sent to the model); the payload is what Jev sees.
+    return [Item(id=f"{label}:{name}", payload={"file": f"selftest/{name}.py", "name": name,
+                                                "language": "python", "kind": "function", "source": src})
+            for name, src in rows]
+
+
+def _label(item) -> str:
+    return item.id.split(":", 1)[0]
+
+
+def run_selftest(judge: Judge, out) -> int:
+    items = _items(POSITIVES, "pos") + _items(NEGATIVES, "neg")
+    scores, stats = judge.judge(items, SELFTEST_QUESTION, {"name": "selftest"})
+    pos_items = [i for i in items if _label(i) == "pos"]
+    neg_items = [i for i in items if _label(i) == "neg"]
+    pos = [scores[i.id] for i in pos_items if i.id in scores]
+    neg = [scores[i.id] for i in neg_items if i.id in scores]
+    unscored = sum(1 for i in items if i.id not in scores)
+    if not pos or not neg:
+        print("selftest: no scores returned" + (f" ({stats.last_error})" if stats.last_error else ""), file=out)
+        return 2
+    recall = sum(s >= ABOVE for s in pos)                 # unscored positives count as missed
+    fp = sum(s >= ABOVE for s in neg)
+    auroc = sum((p > n) + 0.5 * (p == n) for p in pos for n in neg) / (len(pos) * len(neg))
+    print(f"selftest question: {SELFTEST_QUESTION}", file=out)
+    print(f"  positives n={len(pos_items)}  recall@{ABOVE:.2f} = {recall}/{len(pos_items)}   "
+          f"min {min(pos):.2f} mean {sum(pos)/len(pos):.2f} max {max(pos):.2f}", file=out)
+    print(f"  negatives n={len(neg_items)}  FP@{ABOVE:.2f} = {fp}/{len(neg_items)}   "
+          f"min {min(neg):.2f} mean {sum(neg)/len(neg):.2f} max {max(neg):.2f}", file=out)
+    print(f"  AUROC {auroc:.3f} (over {len(pos)}x{len(neg)} scored pairs)   unscored {unscored}   "
+          f"{stats.requests} requests, {stats.input_tokens:,} tokens", file=out)
+    for it in sorted(items, key=lambda i: -scores.get(i.id, -1.0)):
+        label, s = _label(it), scores.get(it.id)
+        flag = ""
+        if label == "pos" and (s is None or s < ABOVE):
+            flag = "   <-- missed"
+        if label == "neg" and s is not None and s >= ABOVE:
+            flag = "   <-- false positive"
+        shown = f"{s:.2f}" if s is not None else " n/a"
+        print(f"  {label}  {shown}  {it.payload['name']}{flag}", file=out)
+    ok = auroc >= 0.9 and unscored == 0
+    if fp > 0:
+        print(f"  note: {fp} negative(s) scored >= {ABOVE:.2f}; consider a higher --above", file=out)
+    print("  PASS" if ok else "  FAIL - see rows above", file=out)
+    return 0 if ok else 2

every/symbols.py

@@ -0,0 +1,109 @@
+"""Call-site extraction and the repo-wide symbol index."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+# Node types that represent a call, per language.
+CALL_NODES = {
+    "python": {"call"},
+    "javascript": {"call_expression", "new_expression"},
+    "typescript": {"call_expression", "new_expression"},
+    "tsx": {"call_expression", "new_expression"},
+    "go": {"call_expression"},
+    "java": {"method_invocation", "object_creation_expression"},
+    "rust": {"call_expression"},
+    "csharp": {"invocation_expression", "object_creation_expression"},
+    "ruby": {"call"},
+    "php": {"function_call_expression", "member_call_expression",
+            "scoped_call_expression", "object_creation_expression"},
+}
+# Field names that hold the callee expression on a call node, tried in order.
+FUNC_FIELDS = ("function", "name", "method", "constructor", "type")
+# Leaf node types that are identifiers.
+IDENT_TYPES = {"identifier", "property_identifier", "field_identifier", "type_identifier",
+               "name", "constant", "simple_identifier"}
+# Fields that point at the "last segment" of a dotted/member expression.
+SUB_FIELDS = ("attribute", "property", "name", "field", "method")
+
+
+def _text(node, src: bytes) -> str:
+    return src[node.start_byte:node.end_byte].decode("utf-8", "replace")
+
+
+def _last_ident(node, src: bytes) -> str | None:
+    """The identifier a call resolves to: `db.save` -> save, `pkg.Make` -> Make."""
+    if node is None:
+        return None
+    if node.type in IDENT_TYPES and node.child_count == 0:
+        return _text(node, src)
+    for f in SUB_FIELDS:
+        child = node.child_by_field_name(f)
+        if child is not None:
+            found = _last_ident(child, src)
+            if found:
+                return found
+    found = None
+    for child in node.children:
+        got = _last_ident(child, src)
+        if got:
+            found = got
+    return found
+
+
+def callee_names(node, lang: str, src: bytes) -> list[str]:
+    """Unique callee names inside `node`, in source (preorder) order."""
+    call_types = CALL_NODES.get(lang)
+    if not call_types:
+        return []
+    out: list[str] = []
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if n.type in call_types:
+            for f in FUNC_FIELDS:
+                target = n.child_by_field_name(f)
+                if target is not None:
+                    name = _last_ident(target, src)
+                    if name and name not in out:
+                        out.append(name)
+                    break
+        stack.extend(reversed(n.children))   # reversed so the first child is popped first
+    return out
+
+
+class SymbolIndex:
+    """name -> definitions, plus reverse call edges, over one run's units."""
+
+    def __init__(self, units: list) -> None:
+        self.units = units
+        self.by_name: dict[str, list] = defaultdict(list)
+        for u in units:
+            if u.kind == "function":
+                self.by_name[u.name.split(".")[-1]].append(u)
+        self._callers: dict[str, list] = defaultdict(list)
+        seen: set = set()
+        for u in units:
+            if u.kind != "function":
+                continue
+            for name in u.calls:
+                for callee in self.by_name.get(name, []):
+                    if callee is u or (callee.id, u.id) in seen:
+                        continue
+                    seen.add((callee.id, u.id))
+                    self._callers[callee.id].append(u)
+
+    def callees_of(self, unit, limit: int = 8) -> list:
+        out, seen = [], {unit.id}
+        for name in unit.calls:
+            for d in self.by_name.get(name, []):
+                if d.id in seen:
+                    continue
+                seen.add(d.id)
+                out.append(d)
+                if len(out) >= limit:
+                    return out
+        return out
+
+    def callers_of(self, unit, limit: int = 8) -> list:
+        return self._callers.get(unit.id, [])[:limit]

every/units.py

@@ -0,0 +1,34 @@
+"""Shared types and the token-estimate constants used by every module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Measured 2026-09-16 against jev-latest on code+JSON payloads (see reference/).
+CHARS_PER_TOKEN = 2.3
+PER_QUESTION_OVERHEAD = 80      # instructions + criteria + key, per question
+REQUEST_FIXED_TOKENS = 262      # state + envelope, per request
+OUTPUT_RESERVE_PER_Q = 25       # ~18 output tokens per noul answer, rounded up
+USD_PER_INPUT_TOKEN = 0.042 / 1_000_000   # output tokens are free
+DEFAULT_ABOVE = 0.75            # score at/above which a result is a hit. Set from the live
+                                # selftest on 2026-09-16: positives 0.82-0.98, negatives 0.05-0.29
+                                # with one borderline at 0.68; 0.75 splits the gap.
+
+
+def estimate_tokens(text: str) -> int:
+    """Conservative input-token estimate for one embedded question."""
+    return int(len(text) / CHARS_PER_TOKEN) + PER_QUESTION_OVERHEAD
+
+
+@dataclass(eq=False)
+class Unit:
+    """One judgeable thing: a function/method, or a file chunk for unsupported languages."""
+    id: str            # "<file>:<start_line>:<name>", unique within a run
+    file: str          # path relative to the scanned root, forward slashes
+    lang: str
+    name: str          # "outer.inner" for nested functions; "chunk@<line>" for chunks
+    start_line: int    # 1-based, inclusive
+    end_line: int
+    source: str        # possibly truncated with a trailing "[truncated]" marker
+    kind: str = "function"                       # "function" | "chunk"
+    calls: list = field(default_factory=list)    # callee names (last identifier segment)