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

receipts/verify/rewriter.py

@@ -0,0 +1,172 @@
+"""Propose honest rewrites for weak resume bullets.
+
+A rewrite is only ever as strong as what the knowledge base can support.
+Unsupported numbers are removed; plausible claims are softened; verified
+claims stay intact. The rewriter never invents new unverifiable metrics —
+but it CAN substitute numbers mined from the codebase itself (route
+counts, model counts, commit history), because those are provable.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from receipts.llm.json_utils import parse_json_loose
+from receipts.llm.provider import CompletionResult, LLMProvider
+from receipts.verify.verifier import VerificationResult
+
+_SYSTEM = """\
+You are a resume bullet rewriter. Given a bullet and its verification \
+results from a code evidence check, rewrite the bullet to be honest yet \
+strong.
+
+Rules
+-----
+- ONLY claim what the code evidence supports. Never invent numbers.
+- Remove or soften "unsupported" numeric claims.
+- Remove "unsupported" technology claims from the rewrite.
+- Keep "verified" claims as-is or strengthen them with evidence details.
+- Soften "plausible" claims (drop exact numbers, use qualitative language).
+- The rewrite must still read like a strong resume bullet: concise, \
+  active voice, impact-oriented — just grounded in provable facts.
+- If everything was verified, return the original bullet unchanged.
+
+Respond in JSON:
+{"rewritten": "the rewritten bullet", "explanation": "what changed and why"}
+"""
+
+_GROUNDING_TEMPLATE = """\
+
+PROVABLE FACTS mined from the codebase and its git history. When you remove
+an unprovable number, replace it with a relevant number from this list — a
+provable specific beats a vague qualitative phrase. You may ONLY use numbers
+that appear here or in verified claims; never any other number:
+{facts}
+"""
+
+_KEYWORDS_TEMPLATE = """\
+
+CODE-SUPPORTED KEYWORDS from the target job description (the codebase
+demonstrably uses these). Weave one in ONLY where it fits the bullet's
+actual content — never force or stuff them:
+{keywords}
+"""
+
+
+@dataclass(frozen=True)
+class RewriteResult:
+    original: str
+    rewritten: str
+    explanation: str
+    completion: CompletionResult | None = None
+    original_raw: str = ""  # raw TeX of the source bullet, for exact replacement
+
+
+def _build_user_prompt(bullet_text: str, results: list[VerificationResult]) -> str:
+    parts = [f"ORIGINAL BULLET: {bullet_text}", "", "VERIFICATION RESULTS:"]
+    for r in results:
+        parts.append(
+            f'  - {r.claim.claim_type} "{r.claim.value}": '
+            f"{r.verdict} — {r.explanation}"
+        )
+        if r.evidence:
+            for e in r.evidence[:2]:
+                parts.append(f"    evidence: {e.rel_path}::{e.name}")
+    return "\n".join(parts)
+
+
+def _build_system_prompt(
+    grounded_facts: str | None,
+    addable_keywords: list[str] | None,
+    extra_constraint: str | None,
+) -> str:
+    system = _SYSTEM
+    if grounded_facts:
+        system += _GROUNDING_TEMPLATE.format(facts=grounded_facts)
+    if addable_keywords:
+        system += _KEYWORDS_TEMPLATE.format(keywords=", ".join(addable_keywords))
+    if extra_constraint:
+        system += f"\nADDITIONAL CONSTRAINT:\n{extra_constraint}\n"
+    return system
+
+
+def rewrite_bullet(
+    bullet_text: str,
+    results: list[VerificationResult],
+    provider: LLMProvider,
+    *,
+    grounded_facts: str | None = None,
+    addable_keywords: list[str] | None = None,
+    extra_constraint: str | None = None,
+    original_raw: str = "",
+) -> RewriteResult:
+    """Rewrite a single bullet based on its verification results.
+
+    ``grounded_facts`` is a pre-formatted block of provable numbers (from
+    the code metrics miner / git history) the model may substitute in.
+    ``addable_keywords`` are JD keywords the codebase demonstrably supports.
+    ``extra_constraint`` is appended verbatim — used by the score-aware
+    retry loop to pin down a regression. ``original_raw`` is the bullet's
+    raw TeX, carried through so the .tex rewriter can replace it exactly.
+    """
+    verdicts = {r.verdict for r in results}
+
+    if not original_raw and results:
+        original_raw = getattr(results[0].claim, "bullet_raw", "")
+
+    if verdicts == {"verified"} and not extra_constraint:
+        return RewriteResult(
+            original=bullet_text,
+            rewritten=bullet_text,
+            explanation="All claims verified — no changes needed.",
+            original_raw=original_raw,
+        )
+
+    system = _build_system_prompt(grounded_facts, addable_keywords, extra_constraint)
+    user_prompt = _build_user_prompt(bullet_text, results)
+    completion = provider.complete(system, user_prompt, json_mode=True)
+
+    try:
+        parsed = parse_json_loose(completion.text)
+        rewritten = parsed.get("rewritten", bullet_text)
+        explanation = parsed.get("explanation", "")
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        rewritten = bullet_text
+        explanation = "Could not parse rewrite response."
+
+    return RewriteResult(
+        original=bullet_text,
+        rewritten=rewritten,
+        explanation=explanation,
+        completion=completion,
+        original_raw=original_raw,
+    )
+
+
+def rewrite_weak_bullets(
+    results: list[VerificationResult],
+    provider: LLMProvider,
+    *,
+    grounded_facts: str | None = None,
+    addable_keywords: list[str] | None = None,
+) -> list[RewriteResult]:
+    """Rewrite bullets that have any non-verified claims."""
+    by_bullet: dict[str, list[VerificationResult]] = {}
+    for r in results:
+        by_bullet.setdefault(r.claim.bullet_text, []).append(r)
+
+    rewrites: list[RewriteResult] = []
+    for bullet_text, bullet_results in by_bullet.items():
+        verdicts = {r.verdict for r in bullet_results}
+        if verdicts != {"verified"}:
+            rewrites.append(
+                rewrite_bullet(
+                    bullet_text,
+                    bullet_results,
+                    provider,
+                    grounded_facts=grounded_facts,
+                    addable_keywords=addable_keywords,
+                )
+            )
+    return rewrites

receipts/verify/router.py

@@ -0,0 +1,211 @@
+"""Multi-repo verification routing.
+
+Resumes list 2–5 projects, but a knowledge base holds one codebase — so
+with a single KB every *other* project's claims read "unsupported" for
+the wrong reason. This module maps resume entries to their own ingested
+KBs and routes each bullet's claims to the right one:
+
+- entry matched to a mapping        → verified against that repo's KB
+- skills-section claims            → searched across ALL mapped KBs
+- entry with no mapping            → "no codebase mapped" (plausible),
+                                      zero LLM calls, zero embeds
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from receipts.errors import ReceiptsError
+from receipts.llm.provider import LLMProvider
+from receipts.resume.claim_extractor import Claim
+from receipts.verify.kb import KnowledgeBase, SearchResult, default_kb_dir
+from receipts.verify.verifier import (
+    DISTANCE_THRESHOLD,
+    VerificationResult,
+    _short_circuit,
+    group_claims_by_bullet,
+    verify_bullet_claims,
+    verify_claim,
+)
+
+
+@dataclass(frozen=True)
+class EntryKBMap:
+    entry_filter: str  # substring matched against entry headings
+    source_path: Path
+    # Phase 19: pre-resolved KB dir for URL/alias sources. None means the
+    # classic local-folder behavior (default_kb_dir of source_path).
+    kb_dir: Path | None = None
+    label: str = ""  # display label; falls back to source_path.name
+
+    @property
+    def display_label(self) -> str:
+        return self.label or self.source_path.name
+
+
+def parse_map_options(
+    raw: list[str],
+    *,
+    resolve: Callable[[str], tuple[Path, str]] | None = None,
+) -> list[EntryKBMap]:
+    """Parse repeatable ``--map "entry substring=<source>"`` options.
+
+    ``<source>`` may be a local folder, and — when a ``resolve`` callable is
+    supplied (the CLI passes its source resolver) — also a git URL or a
+    manifest alias. ``resolve(spec)`` returns ``(kb_dir, label)``.
+    """
+    maps: list[EntryKBMap] = []
+    for item in raw:
+        if "=" not in item:
+            raise ReceiptsError(
+                f'Bad --map value "{item}". Expected format:'
+                ' --map "entry substring=<folder | git URL | alias>"'
+            )
+        entry_filter, _, spec = item.partition("=")
+        entry_filter = entry_filter.strip()
+        spec = spec.strip()
+        if not entry_filter or not spec:
+            raise ReceiptsError(
+                f'Bad --map value "{item}". Both sides of "=" are required.'
+            )
+        if resolve is not None and not Path(spec).is_dir():
+            kb_dir, label = resolve(spec)
+            maps.append(
+                EntryKBMap(
+                    entry_filter=entry_filter,
+                    source_path=Path(spec),
+                    kb_dir=kb_dir,
+                    label=label,
+                )
+            )
+        else:
+            maps.append(EntryKBMap(entry_filter=entry_filter, source_path=Path(spec)))
+    return maps
+
+
+class MultiKB:
+    """Facade over several KBs — search merges the best evidence of all.
+
+    Evidence paths are prefixed with the repo label so a verdict's citation
+    says which codebase it came from. Quacks like ``KnowledgeBase`` for the
+    parts the verifier uses (``search`` / ``count``).
+    """
+
+    def __init__(self, labeled_kbs: list[tuple[str, KnowledgeBase]]) -> None:
+        self._labeled = labeled_kbs
+
+    def search(
+        self,
+        query: str,
+        provider: LLMProvider,
+        n_results: int = 5,
+    ) -> list[SearchResult]:
+        merged: list[SearchResult] = []
+        for label, kb in self._labeled:
+            for r in kb.search(query, provider, n_results=n_results):
+                merged.append(replace(r, rel_path=f"[{label}] {r.rel_path}"))
+        merged.sort(key=lambda r: r.distance)
+        return merged[:n_results]
+
+    def count(self) -> int:
+        return sum(kb.count() for _, kb in self._labeled)
+
+
+class KBRouter:
+    """Maps resume entry headings to their ingested knowledge bases."""
+
+    def __init__(
+        self,
+        maps: list[EntryKBMap],
+        *,
+        kb_dir_fn: Callable[[Path], Path] = default_kb_dir,
+    ) -> None:
+        self.maps = maps
+        self._kbs: list[tuple[EntryKBMap, KnowledgeBase]] = [
+            (m, KnowledgeBase(m.kb_dir or kb_dir_fn(m.source_path))) for m in maps
+        ]
+
+    def empty_sources(self) -> list[str]:
+        """Display labels of mapped codebases whose KB was never ingested."""
+        return [m.display_label for m, kb in self._kbs if kb.count() == 0]
+
+    def kb_for_entry(self, entry_heading: str) -> KnowledgeBase | None:
+        lowered = entry_heading.lower()
+        for m, kb in self._kbs:
+            if m.entry_filter.lower() in lowered:
+                return kb
+        return None
+
+    def multi_kb(self) -> MultiKB:
+        return MultiKB([(m.display_label, kb) for m, kb in self._kbs])
+
+    def entry_filters(self) -> list[str]:
+        return [m.entry_filter for m in self.maps]
+
+
+def _unmapped_result(claim: Claim) -> VerificationResult:
+    short = _short_circuit(claim)
+    if short is not None:
+        return short
+    return VerificationResult(
+        claim=claim,
+        verdict="plausible",
+        explanation=(
+            "No codebase mapped for this entry — claim is plausible but"
+            " unverifiable. Map one with --map to verify it."
+        ),
+        evidence=[],
+        llm_used=False,
+    )
+
+
+def verify_claims_routed(
+    claims: list[Claim],
+    router: KBRouter,
+    provider: LLMProvider,
+    *,
+    distance_threshold: float = DISTANCE_THRESHOLD,
+    batch: bool = False,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> list[VerificationResult]:
+    """Verify claims, routing each bullet to its entry's knowledge base.
+
+    Skills-section bullets search across every mapped KB (a skill is
+    demonstrated if ANY of your projects uses it). Bullets from entries
+    with no mapping are classified without spending a single token.
+    """
+    results: list[VerificationResult] = []
+    groups = group_claims_by_bullet(claims)
+    done = 0
+
+    for group in groups:
+        first = group[0]
+        sec_type = getattr(first, "section_type", "project")
+
+        kb: KnowledgeBase | MultiKB | None
+        if sec_type == "skills":
+            kb = router.multi_kb()
+        else:
+            kb = router.kb_for_entry(first.entry_heading)
+
+        if kb is None:
+            results.extend(_unmapped_result(c) for c in group)
+        elif batch:
+            results.extend(
+                verify_bullet_claims(
+                    group, kb, provider, distance_threshold=distance_threshold
+                )
+            )
+        else:
+            results.extend(
+                verify_claim(c, kb, provider, distance_threshold=distance_threshold)
+                for c in group
+            )
+
+        done += len(group)
+        if on_progress is not None:
+            on_progress(done, len(claims))
+
+    return results

receipts/verify/summaries.py

@@ -0,0 +1,258 @@
+"""Corpus-level intelligence (Phase 22C) — the "knows the whole repo" layer.
+
+Single-chunk retrieval cannot evidence whole-repo claims: "microservices
+architecture", "22 API routes", "modular service layer" are properties of
+the corpus, not of any one function. This module synthesizes corpus-level
+artifacts and stores them in the KB as first-class searchable chunks, so
+retrieval can surface them exactly like code:
+
+Zero-LLM (always on):
+- a CODE FACTS chunk — Phase 12's mined counts (routes, models, components,
+  tests, languages) plus git evidence when available;
+- an IMPORT MAP chunk — which modules import which, a lightweight
+  dependency picture.
+
+LLM-powered (``RECEIPTS_SUMMARIES=1``, metered, cached by content hash):
+- RAPTOR-style hierarchical summaries: per-file → per-directory → one
+  repo-level architecture summary, each embedded as its own chunk. A claim
+  about overall architecture retrieves the repo summary; a feature claim
+  retrieves its module summary.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from collections.abc import Callable
+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
+
+_IMPORT_RE = re.compile(
+    r"^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+)"
+    r"|import\s+.*?from\s+['\"]([^'\"]+)['\"])",
+    re.MULTILINE,
+)
+
+_SUMMARY_SYSTEM = """\
+You summarize code for a search index. Given the artifacts of one file (or
+the summaries of one directory), write 1-2 plain sentences describing what
+it does and the key technologies involved. Concrete nouns, no marketing.
+
+Respond in JSON: {"summary": "..."}
+"""
+
+_REPO_SUMMARY_SYSTEM = """\
+You are describing a repository's architecture for a search index. Given
+per-directory summaries, write 3-5 sentences covering: what the project is,
+the major components/layers, and the main technologies. Concrete, no fluff.
+
+Respond in JSON: {"summary": "..."}
+"""
+
+
+def summaries_enabled() -> bool:
+    """Hierarchical LLM summaries toggle — off unless RECEIPTS_SUMMARIES=1."""
+    return os.environ.get("RECEIPTS_SUMMARIES", "0").strip() == "1"
+
+
+def _tokens(text: str) -> int:
+    return max(1, len(text) // 4)
+
+
+def _global_artifact(name: str, text: str) -> Artifact:
+    return Artifact(
+        rel_path=f"[repo] {name}",
+        language="text",
+        kind="facts",
+        name=name,
+        start_line=1,
+        end_line=max(1, text.count("\n") + 1),
+        code=text,
+        token_estimate=_tokens(text),
+    )
+
+
+def build_facts_artifact(source_path: Path) -> Artifact | None:
+    """CODE FACTS chunk from Phase 12's zero-LLM miners. None on failure."""
+    try:
+        from receipts.mine.code_metrics import mine_code_facts
+        from receipts.mine.git_evidence import mine_git_evidence
+
+        facts = mine_code_facts(source_path)
+        lines = ["CODE FACTS (mined from the codebase, zero guesswork):"]
+        lines.extend(facts.summary_lines())
+        git_ev = mine_git_evidence(source_path)
+        if git_ev.available:
+            lines.extend(git_ev.summary_lines())
+    except Exception:
+        return None
+    return _global_artifact("code-facts", "\n".join(lines))
+
+
+def build_import_map_artifact(artifacts: list[Artifact]) -> Artifact | None:
+    """IMPORT MAP chunk: per-file imports, a cheap dependency picture."""
+    per_file: dict[str, set[str]] = {}
+    for a in artifacts:
+        if a.kind == "facts" or a.language == "text":
+            continue
+        found: set[str] = set()
+        for m in _IMPORT_RE.finditer(a.code):
+            target = next((g for g in m.groups() if g), "")
+            if target:
+                found.add(target)
+        if found:
+            per_file.setdefault(a.rel_path, set()).update(found)
+
+    if not per_file:
+        return None
+
+    lines = ["IMPORT MAP (which modules depend on which):"]
+    for rel_path in sorted(per_file)[:80]:  # cap — this is a sketch, not a graph db
+        deps = ", ".join(sorted(per_file[rel_path])[:12])
+        lines.append(f"  {rel_path} -> {deps}")
+    return _global_artifact("import-map", "\n".join(lines))
+
+
+def _cached_summary(
+    cache: dict[str, str],
+    cache_path: Path,
+    key_text: str,
+    system: str,
+    user: str,
+    provider: LLMProvider,
+) -> str:
+    key = hashlib.sha256(key_text.encode("utf-8", errors="replace")).hexdigest()[:16]
+    hit = cache.get(key)
+    if hit is not None:
+        return hit
+    try:
+        completion = provider.complete(system, user, json_mode=True)
+        parsed = parse_json_loose(completion.text)
+        summary = str(parsed.get("summary", "")).strip()
+    except Exception:
+        summary = ""
+    cache[key] = summary
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = cache_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(cache, indent=0), encoding="utf-8")
+    tmp.replace(cache_path)
+    return summary
+
+
+def build_hierarchical_summaries(
+    artifacts: list[Artifact],
+    provider: LLMProvider,
+    *,
+    cache_path: Path,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> list[Artifact]:
+    """File → directory → repo summaries, each as a searchable artifact.
+
+    Every summary is cached by a hash of its inputs, so re-ingesting an
+    unchanged corpus makes zero LLM calls here.
+    """
+    cache: dict[str, str] = {}
+    if cache_path.is_file():
+        try:
+            loaded = json.loads(cache_path.read_text(encoding="utf-8"))
+            cache = loaded if isinstance(loaded, dict) else {}
+        except (OSError, json.JSONDecodeError):
+            cache = {}
+
+    by_file: dict[str, list[Artifact]] = {}
+    for a in artifacts:
+        if a.kind == "facts":
+            continue
+        by_file.setdefault(a.rel_path, []).append(a)
+
+    out: list[Artifact] = []
+    file_summaries: dict[str, str] = {}
+    total = len(by_file)
+    for i, (rel_path, arts) in enumerate(sorted(by_file.items()), 1):
+        heads = "\n".join(f"- {a.kind} {a.name}: {a.code[:200]}" for a in arts[:12])
+        summary = _cached_summary(
+            cache,
+            cache_path,
+            f"file:{rel_path}\n{heads}",
+            _SUMMARY_SYSTEM,
+            f"FILE: {rel_path}\nARTIFACTS:\n{heads}",
+            provider,
+        )
+        if summary:
+            file_summaries[rel_path] = summary
+            out.append(
+                Artifact(
+                    rel_path=f"[summary] {rel_path}",
+                    language="text",
+                    kind="summary",
+                    name=rel_path,
+                    start_line=1,
+                    end_line=1,
+                    code=f"FILE SUMMARY {rel_path}: {summary}",
+                    token_estimate=_tokens(summary),
+                )
+            )
+        if on_progress is not None:
+            on_progress(i, total)
+
+    by_dir: dict[str, list[str]] = {}
+    for rel_path, summary in file_summaries.items():
+        top = rel_path.split("/", 1)[0] if "/" in rel_path else "."
+        by_dir.setdefault(top, []).append(f"{rel_path}: {summary}")
+
+    dir_summaries: dict[str, str] = {}
+    for dir_name, entries in sorted(by_dir.items()):
+        joined = "\n".join(entries[:40])
+        summary = _cached_summary(
+            cache,
+            cache_path,
+            f"dir:{dir_name}\n{joined}",
+            _SUMMARY_SYSTEM,
+            f"DIRECTORY: {dir_name}\nFILE SUMMARIES:\n{joined}",
+            provider,
+        )
+        if summary:
+            dir_summaries[dir_name] = summary
+            out.append(
+                Artifact(
+                    rel_path=f"[summary] {dir_name}/",
+                    language="text",
+                    kind="summary",
+                    name=f"{dir_name}/",
+                    start_line=1,
+                    end_line=1,
+                    code=f"DIRECTORY SUMMARY {dir_name}/: {summary}",
+                    token_estimate=_tokens(summary),
+                )
+            )
+
+    if dir_summaries:
+        joined = "\n".join(f"{d}: {s}" for d, s in sorted(dir_summaries.items()))
+        repo_summary = _cached_summary(
+            cache,
+            cache_path,
+            f"repo:\n{joined}",
+            _REPO_SUMMARY_SYSTEM,
+            f"DIRECTORY SUMMARIES:\n{joined}",
+            provider,
+        )
+        if repo_summary:
+            out.append(
+                Artifact(
+                    rel_path="[summary] <repository>",
+                    language="text",
+                    kind="summary",
+                    name="<repository>",
+                    start_line=1,
+                    end_line=1,
+                    code=f"REPOSITORY ARCHITECTURE: {repo_summary}",
+                    token_estimate=_tokens(repo_summary),
+                )
+            )
+
+    return out