codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/tui/widgets/claims_table.py

@@ -0,0 +1,50 @@
+"""DataTable displaying claims with their verification verdicts."""
+
+from __future__ import annotations
+
+from textual.widgets import DataTable
+
+from receipts.verify.verifier import VerificationResult
+
+_VERDICT_STYLE = {
+    "verified": "[green]verified[/green]",
+    "plausible": "[yellow]plausible[/yellow]",
+    "unsupported": "[red]unsupported[/red]",
+}
+
+
+class ClaimsTable(DataTable):
+    """Table showing each claim, its type, verdict, and explanation.
+
+    Narrow terminals truncate the explanation column — selecting a row
+    (Enter/click) surfaces the FULL claim, bullet, explanation, and
+    evidence in the Log tab via ``result_at``.
+    """
+
+    DEFAULT_CSS = """
+    ClaimsTable {
+        height: 1fr;
+    }
+    """
+
+    def on_mount(self) -> None:
+        self.add_columns("Type", "Value", "Verdict", "Section", "Explanation")
+        self.cursor_type = "row"
+        self.zebra_stripes = True
+        self._results: list[VerificationResult] = []
+
+    def add_result(self, result: VerificationResult) -> None:
+        self._results.append(result)
+        styled = _VERDICT_STYLE.get(result.verdict, result.verdict)
+        self.add_row(
+            result.claim.claim_type,
+            result.claim.value,
+            styled,
+            result.claim.section,
+            result.explanation[:80],
+        )
+
+    def result_at(self, row_index: int) -> VerificationResult | None:
+        if 0 <= row_index < len(self._results):
+            return self._results[row_index]
+        return None

receipts/tui/widgets/diff_view.py

@@ -0,0 +1,38 @@
+"""Diff view showing original vs rewritten resume bullets."""
+
+from __future__ import annotations
+
+from textual.widgets import RichLog
+
+from receipts.verify.rewriter import RewriteResult
+
+
+class DiffView(RichLog):
+    """RichLog that shows original / rewritten bullet pairs."""
+
+    DEFAULT_CSS = """
+    DiffView {
+        height: 1fr;
+    }
+    """
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(markup=True, wrap=True, **kwargs)
+
+    def add_rewrite(self, rw: RewriteResult) -> None:
+        self.write("")
+        self.write("[bold]ORIGINAL:[/bold]")
+        self.write(f"  [red]{_escape(rw.original)}[/red]")
+        self.write("[bold]REWRITTEN:[/bold]")
+        self.write(f"  [green]{_escape(rw.rewritten)}[/green]")
+        self.write(f"  [dim]{_escape(rw.explanation)}[/dim]")
+        self.write("─" * 60)
+
+    def show_no_rewrites(self) -> None:
+        self.write("")
+        msg = "All bullets are backed by code — no rewrites needed."
+        self.write(f"[green]{msg}[/green]")
+
+
+def _escape(text: str) -> str:
+    return text.replace("[", "\\[")

receipts/tui/widgets/status_bar.py

@@ -0,0 +1,38 @@
+"""Persistent status bar showing live token count and session cost."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+
+class StatusBar(Static):
+    """Footer-style bar displaying token usage, cost, and provider."""
+
+    input_tokens = reactive(0)
+    output_tokens = reactive(0)
+    provider_name = reactive("—")
+    status_text = reactive("Ready")
+
+    DEFAULT_CSS = """
+    StatusBar {
+        dock: bottom;
+        height: 1;
+        background: $primary-background;
+        color: $text;
+        padding: 0 1;
+    }
+    """
+
+    def render(self) -> str:
+        total = self.input_tokens + self.output_tokens
+        return (
+            f" {self.status_text}"
+            f"  |  tokens: {total:,}"
+            f" (in: {self.input_tokens:,}  out: {self.output_tokens:,})"
+            f"  |  provider: {self.provider_name}"
+        )
+
+    def add_tokens(self, input_t: int, output_t: int) -> None:
+        self.input_tokens += input_t
+        self.output_tokens += output_t

receipts/verify/bm25.py

@@ -0,0 +1,112 @@
+"""Okapi BM25 lexical index — built from scratch, zero dependencies.
+
+Dense embeddings blur exact identifiers: "pgvector", "Alembic",
+"docker-compose" are lexical signals that resume claims are full of and
+that cosine similarity treats as fuzz. BM25 nails them. This index is the
+sparse half of hybrid retrieval (Phase 22A): both retrievers run, their
+rankings merge via reciprocal rank fusion, and every surfaced candidate
+still has to pass the verifier's semantic distance threshold — BM25 adds
+recall, never credulity.
+
+The implementation is textbook Okapi BM25 (k1=1.5, b=0.75) over a
+code-aware tokenizer that splits snake_case and camelCase identifiers into
+sub-tokens while keeping the original, so "KnowledgeBase" matches
+"knowledge base" and "kb_dir_for_url" matches "url".
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+
+_TOKEN_RE = re.compile(r"[A-Za-z0-9_]+")
+_CAMEL_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
+
+_K1 = 1.5
+_B = 0.75
+
+#: Reciprocal-rank-fusion constant — the standard 60 from the RRF paper.
+RRF_K = 60
+
+
+def tokenize(text: str) -> list[str]:
+    """Code-aware tokens: whole identifiers plus their snake/camel parts."""
+    out: list[str] = []
+    for raw in _TOKEN_RE.findall(text):
+        low = raw.lower()
+        out.append(low)
+        if "_" in raw:
+            out.extend(p for p in low.split("_") if len(p) > 1)
+        parts = _CAMEL_RE.findall(raw)
+        if len(parts) > 1:
+            out.extend(p.lower() for p in parts if len(p) > 1)
+    return out
+
+
+class BM25Index:
+    """In-memory BM25 over ``{doc_id: text}``.
+
+    Built lazily from the Chroma collection's own documents, so it can
+    never drift out of sync with the vector store — there is no second
+    index on disk to corrupt or forget to update.
+    """
+
+    def __init__(self, docs: dict[str, str]) -> None:
+        self._tf: dict[str, Counter[str]] = {}
+        self._doc_len: dict[str, int] = {}
+        df: Counter[str] = Counter()
+
+        for doc_id, text in docs.items():
+            tokens = tokenize(text)
+            counts = Counter(tokens)
+            self._tf[doc_id] = counts
+            self._doc_len[doc_id] = len(tokens)
+            df.update(counts.keys())
+
+        n_docs = max(len(docs), 1)
+        self._avgdl = sum(self._doc_len.values()) / n_docs if self._doc_len else 1.0
+        self._idf = {
+            term: math.log((n_docs - freq + 0.5) / (freq + 0.5) + 1.0)
+            for term, freq in df.items()
+        }
+
+    def __len__(self) -> int:
+        return len(self._tf)
+
+    def search(self, query: str, n: int = 10) -> list[tuple[str, float]]:
+        """Top ``n`` (doc_id, score) for the query, best first."""
+        q_terms = [t for t in tokenize(query) if t in self._idf]
+        if not q_terms:
+            return []
+
+        scores: dict[str, float] = {}
+        for doc_id, tf in self._tf.items():
+            dl = self._doc_len[doc_id] or 1
+            score = 0.0
+            for term in q_terms:
+                f = tf.get(term, 0)
+                if not f:
+                    continue
+                idf = self._idf[term]
+                score += (
+                    idf * (f * (_K1 + 1)) / (f + _K1 * (1 - _B + _B * dl / self._avgdl))
+                )
+            if score > 0:
+                scores[doc_id] = score
+
+        ranked = sorted(scores.items(), key=lambda kv: -kv[1])
+        return ranked[:n]
+
+
+def rrf_fuse(rankings: list[list[str]], *, k: int = RRF_K) -> list[str]:
+    """Reciprocal rank fusion: merge rankings into one, best first.
+
+    score(d) = Σ over rankings 1/(k + rank_of_d). Documents high in ANY
+    ranking surface; documents high in SEVERAL rankings surface first.
+    """
+    scores: dict[str, float] = {}
+    for ranking in rankings:
+        for rank, doc_id in enumerate(ranking, start=1):
+            scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
+    return [d for d, _ in sorted(scores.items(), key=lambda kv: -kv[1])]

receipts/verify/enrich.py

@@ -0,0 +1,128 @@
+"""Contextual chunk enrichment (Phase 22B) — Anthropic's contextual retrieval.
+
+A bare code chunk is ambiguous at query time: `def connect()` could belong
+to anything. Before embedding, each artifact gets ONE generated line of
+context ("connection factory for the postgres pool in backend/db") prepended
+to its text, so both the embedding and the BM25 index see where the chunk
+lives and what it's for.
+
+Costs one LLM call per artifact at ingest time (free on Ollama, metered like
+every other call), which is why it's OFF by default (``RECEIPTS_ENRICH=1``
+to enable). Context lines are cached by the RAW chunk's content hash in the
+KB directory, so re-ingesting regenerates nothing for unchanged code — the
+incremental-sync guarantee survives enrichment.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from collections.abc import Callable
+from dataclasses import replace
+from pathlib import Path
+
+from receipts.ingest.artifact_extractor import Artifact
+from receipts.llm.json_utils import parse_json_loose
+from receipts.llm.provider import LLMProvider
+
+_CONTEXT_PREFIX = "[context]"
+
+_CONTEXT_SYSTEM = """\
+You label code chunks for a search index. Given a file path and a chunk of
+code from that file, write ONE line (maximum 25 words) saying what the
+chunk does and where it sits in the project. Plain, concrete, no fluff.
+
+Respond in JSON: {"context": "one line here"}
+"""
+
+
+def enrich_enabled() -> bool:
+    """Contextual enrichment toggle — off unless RECEIPTS_ENRICH=1."""
+    return os.environ.get("RECEIPTS_ENRICH", "0").strip() == "1"
+
+
+def _raw_hash(artifact: Artifact) -> str:
+    return hashlib.sha256(artifact.code.encode("utf-8", errors="replace")).hexdigest()[
+        :16
+    ]
+
+
+def _load_cache(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save_cache(path: Path, cache: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(cache, indent=0), encoding="utf-8")
+    tmp.replace(path)
+
+
+def contextualize_artifacts(
+    artifacts: list[Artifact],
+    provider: LLMProvider,
+    *,
+    cache_path: Path,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> tuple[list[Artifact], int]:
+    """Prepend a generated context line to every artifact's code.
+
+    Returns (enriched_artifacts, llm_calls_made). Cached context lines are
+    reused by raw-content hash; already-enriched chunks (idempotence guard)
+    pass through untouched. A failed generation falls back to a mechanical
+    context line built from the path — never blocks the ingest.
+    """
+    cache = _load_cache(cache_path)
+    calls = 0
+    enriched: list[Artifact] = []
+
+    for i, artifact in enumerate(artifacts, 1):
+        if artifact.code.startswith(_CONTEXT_PREFIX) or artifact.kind in (
+            "facts",
+            "summary",
+        ):
+            # Already enriched, or a synthetic corpus-level chunk that is
+            # self-describing text — never double-wrap either.
+            enriched.append(artifact)
+            continue
+
+        key = _raw_hash(artifact)
+        context = cache.get(key)
+        if context is None:
+            user = (
+                f"FILE: {artifact.rel_path}\n"
+                f"KIND: {artifact.kind} {artifact.name}\n"
+                f"CODE:\n{artifact.code[:1500]}"
+            )
+            try:
+                completion = provider.complete(_CONTEXT_SYSTEM, user, json_mode=True)
+                calls += 1
+                parsed = parse_json_loose(completion.text)
+                context = str(parsed.get("context", "")).strip()
+            except Exception:
+                context = ""
+            if not context:
+                # Mechanical fallback — still better than nothing, and it
+                # keeps enrichment deterministic for the sync hash.
+                context = f"{artifact.kind} {artifact.name} in {artifact.rel_path}"
+            context = context.splitlines()[0][:200]
+            cache[key] = context
+            _save_cache(cache_path, cache)
+
+        enriched.append(
+            replace(
+                artifact,
+                code=f"{_CONTEXT_PREFIX} {context}\n{artifact.code}",
+            )
+        )
+        if on_progress is not None:
+            on_progress(i, len(artifacts))
+
+    return enriched, calls

receipts/verify/jd_fetch.py

@@ -0,0 +1,101 @@
+"""Fetch a job description from a URL and strip it to plain text.
+
+Stdlib only (urllib + html.parser) — no new dependency for one HTTP GET.
+Job boards that block bots (LinkedIn, Indeed, anything behind a JS wall)
+fail with a clear instruction to paste the JD into a file and use ``--jd``
+instead — never a crash, never a silent empty gap analysis.
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from html.parser import HTMLParser
+
+from receipts.errors import ReceiptsError
+
+#: Below this many characters of extracted text, assume the page didn't
+#: actually serve the JD (bot wall, JS-rendered shell, login redirect).
+_MIN_TEXT_CHARS = 200
+
+_MAX_BYTES = 2_000_000
+
+_FALLBACK_HINT = (
+    "  Copy the job description text into a file and pass it with --jd"
+    " instead — that path always works."
+)
+
+_SKIP_TAGS = {"script", "style", "noscript", "head", "svg", "template"}
+
+
+class _TextExtractor(HTMLParser):
+    """Collect visible text, skipping script/style and collapsing whitespace."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._chunks: list[str] = []
+        self._skip_depth = 0
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        if tag in _SKIP_TAGS:
+            self._skip_depth += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _SKIP_TAGS and self._skip_depth:
+            self._skip_depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._skip_depth == 0 and data.strip():
+            self._chunks.append(data.strip())
+
+    def text(self) -> str:
+        return "\n".join(self._chunks)
+
+
+def html_to_text(html: str) -> str:
+    """Strip HTML to readable plain text."""
+    parser = _TextExtractor()
+    parser.feed(html)
+    return parser.text()
+
+
+def fetch_jd_text(url: str, *, timeout: float = 20.0) -> str:
+    """Fetch ``url`` and return the page's visible text.
+
+    Raises ReceiptsError with an actionable message on every failure mode:
+    bad URL, HTTP error, bot-blocked page, or a page with almost no text.
+    """
+    if not url.startswith(("http://", "https://")):
+        raise ReceiptsError(f"'{url}' is not an http(s) URL.\n{_FALLBACK_HINT}")
+
+    request = urllib.request.Request(
+        url,
+        # A plain-browser UA: some boards 403 the default Python UA outright.
+        headers={"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) receipts-cli"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as resp:
+            raw = resp.read(_MAX_BYTES)
+            charset = resp.headers.get_content_charset() or "utf-8"
+    except urllib.error.HTTPError as exc:
+        blocked = exc.code in (401, 403, 429, 451, 999)
+        why = (
+            "the site is blocking automated access"
+            if blocked
+            else f"the server returned HTTP {exc.code}"
+        )
+        raise ReceiptsError(
+            f"Could not fetch the JD from {url} — {why}.\n{_FALLBACK_HINT}"
+        ) from None
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise ReceiptsError(
+            f"Could not fetch the JD from {url} — {exc}.\n{_FALLBACK_HINT}"
+        ) from None
+
+    text = html_to_text(raw.decode(charset, errors="replace"))
+    if len(text) < _MIN_TEXT_CHARS:
+        raise ReceiptsError(
+            f"The page at {url} returned almost no text — it is probably"
+            " JS-rendered or behind bot protection.\n" + _FALLBACK_HINT
+        )
+    return text