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

receipts/llm/token_estimate.py

@@ -0,0 +1,35 @@
+"""Local token-count estimation for providers that don't report usage.
+
+Uses tiktoken's ``cl100k_base`` as a reasonable cross-model approximation.
+Counts produced here are ESTIMATES and must be labeled as such in the ledger
+(``CompletionResult.tokens_estimated=True``).
+
+tiktoken downloads its encoding file on first use, so this module is only
+imported by providers that already require network/daemon access (Ollama) —
+never by the fake provider or the test suite.
+"""
+
+from __future__ import annotations
+
+import functools
+
+_CHARS_PER_TOKEN_FALLBACK = 4
+
+
+@functools.lru_cache(maxsize=1)
+def _encoding():
+    import tiktoken
+
+    return tiktoken.get_encoding("cl100k_base")
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimated token count for ``text`` — never a measured value."""
+    if not text:
+        return 0
+    # tiktoken 0.13.x has a known Windows crash (access violation in the Rust
+    # backend) on certain inputs when called from a large scan loop.  The
+    # chars/4 heuristic is accurate enough for the token-budget gate in the
+    # artifact extractor, and tiktoken is still used by Ollama for per-call
+    # ledger estimates where individual calls are short and isolated.
+    return max(1, len(text) // _CHARS_PER_TOKEN_FALLBACK)

receipts/mine/__init__.py

@@ -0,0 +1 @@
+"""Evidence mining — provable facts from code and git history, zero LLM calls."""

receipts/mine/code_metrics.py

@@ -0,0 +1,246 @@
+"""Static code metrics miner — counts things the codebase can PROVE.
+
+Zero LLM calls. Walks the scanned file tree (respecting .gitignore) and
+counts concrete, checkable artifacts: API routes, database models,
+migrations, UI components, tests, service modules, and lines of code per
+language. Every count carries file-level provenance so a number in a
+rewritten resume bullet can always be traced back to the files that
+produced it.
+
+Regex-based on purpose: it must work identically on Windows (where
+tree-sitter support is spotty) and the patterns only need to be precise
+enough to count, not to parse.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from receipts.ingest import scanner
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MetricCount:
+    key: str  # machine name, e.g. "api_routes"
+    label: str  # human name, e.g. "API route definitions"
+    count: int
+    files: list[str] = field(default_factory=list)  # provenance (rel paths)
+
+
+@dataclass(frozen=True)
+class CodeFacts:
+    metrics: list[MetricCount]
+    languages: dict[str, int]  # language -> lines of code
+    total_files: int
+
+    def metric(self, key: str) -> MetricCount | None:
+        for m in self.metrics:
+            if m.key == key:
+                return m
+        return None
+
+    def summary_lines(self) -> list[str]:
+        """Human-readable one-liners for CLI/TUI output."""
+        lines = [f"{m.label}: {m.count}" for m in self.metrics if m.count > 0]
+        if self.languages:
+            top = sorted(self.languages.items(), key=lambda kv: -kv[1])[:5]
+            lang_str = ", ".join(f"{name} ({loc:,} LOC)" for name, loc in top)
+            lines.append(f"Languages: {lang_str}")
+        return lines
+
+    def prompt_facts(self) -> str:
+        """Facts formatted for a rewrite prompt — numbers with provenance."""
+        lines: list[str] = []
+        for m in self.metrics:
+            if m.count == 0:
+                continue
+            examples = ", ".join(m.files[:3])
+            suffix = f" (e.g. {examples})" if examples else ""
+            lines.append(f"- {m.count} {m.label.lower()}{suffix}")
+        if self.languages:
+            top = sorted(self.languages.items(), key=lambda kv: -kv[1])[:5]
+            lines.append(
+                "- languages by size: "
+                + ", ".join(f"{name} ({loc:,} lines)" for name, loc in top)
+            )
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Pattern-based counters
+# ---------------------------------------------------------------------------
+
+# FastAPI/Flask decorators and Express-style route registrations.
+_PY_ROUTE_RE = re.compile(
+    r"@(?:\w+\.)?(?:app|router|api_router|blueprint|bp)\."
+    r"(?:get|post|put|delete|patch|route|websocket)\s*\(",
+    re.IGNORECASE,
+)
+_JS_ROUTE_RE = re.compile(
+    r"\b(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*['\"`]/"
+)
+
+# SQLAlchemy declarative / Django / generic ORM model classes.
+_PY_MODEL_RE = re.compile(
+    r"^class\s+\w+\s*\((?:[^)]*\b(?:Base|db\.Model|models\.Model)\b)[^)]*\)\s*:",
+    re.MULTILINE,
+)
+
+# React/Vue-style component definitions in .tsx/.jsx files.
+_COMPONENT_RE = re.compile(
+    r"(?:export\s+(?:default\s+)?)?(?:function|const)\s+([A-Z]\w+)\s*(?:=|\()"
+)
+
+_PY_TEST_RE = re.compile(r"^def\s+test_\w+", re.MULTILINE)
+_JS_TEST_RE = re.compile(r"^\s*(?:it|test)\s*\(\s*['\"`]", re.MULTILINE)
+
+_EXT_LANGUAGE = {
+    ".py": "Python",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".sql": "SQL",
+    ".html": "HTML",
+    ".css": "CSS",
+    ".sh": "Shell",
+    ".yaml": "YAML",
+    ".yml": "YAML",
+}
+
+
+def _count_matches(pattern: re.Pattern[str], content: str) -> int:
+    return len(pattern.findall(content))
+
+
+def _is_migration(rel_path: str) -> bool:
+    lowered = rel_path.lower()
+    return (
+        (
+            "alembic/versions/" in lowered
+            or "/migrations/" in lowered
+            or lowered.startswith("migrations/")
+        )
+        and lowered.endswith(".py")
+        and not lowered.endswith("__init__.py")
+    )
+
+
+def _is_service_module(rel_path: str) -> bool:
+    lowered = rel_path.lower()
+    name = lowered.rsplit("/", 1)[-1]
+    return name.endswith("_service.py") or (
+        "/services/" in lowered and name.endswith(".py") and name != "__init__.py"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def mine_code_facts(root: Path) -> CodeFacts:
+    """Mine provable counts from a codebase folder. No network, no LLM."""
+    result = scanner.scan(root)
+
+    routes = 0
+    route_files: list[str] = []
+    models = 0
+    model_files: list[str] = []
+    components = 0
+    component_files: list[str] = []
+    tests = 0
+    test_files: list[str] = []
+    migration_files: list[str] = []
+    service_files: list[str] = []
+    languages: dict[str, int] = {}
+
+    for file in result.text_files:
+        rel = file.rel_path
+        ext = "." + rel.rsplit(".", 1)[-1].lower() if "." in rel else ""
+
+        language = _EXT_LANGUAGE.get(ext)
+        content: str | None = None
+        if language or ext in (".py", ".ts", ".tsx", ".js", ".jsx"):
+            content = scanner.read_text(root, rel)
+
+        if language and content is not None:
+            loc = sum(1 for line in content.splitlines() if line.strip())
+            languages[language] = languages.get(language, 0) + loc
+
+        if content is None:
+            continue
+
+        if ext == ".py":
+            n = _count_matches(_PY_ROUTE_RE, content)
+            if n:
+                routes += n
+                route_files.append(rel)
+            n = _count_matches(_PY_MODEL_RE, content)
+            if n:
+                models += n
+                model_files.append(rel)
+            n = _count_matches(_PY_TEST_RE, content)
+            if n:
+                tests += n
+                test_files.append(rel)
+            if _is_migration(rel):
+                migration_files.append(rel)
+            if _is_service_module(rel):
+                service_files.append(rel)
+
+        elif ext in (".ts", ".js"):
+            n = _count_matches(_JS_ROUTE_RE, content)
+            if n:
+                routes += n
+                route_files.append(rel)
+            n = _count_matches(_JS_TEST_RE, content)
+            if n:
+                tests += n
+                test_files.append(rel)
+
+        elif ext in (".tsx", ".jsx"):
+            n = _count_matches(_COMPONENT_RE, content)
+            if n:
+                components += n
+                component_files.append(rel)
+            n = _count_matches(_JS_TEST_RE, content)
+            if n:
+                tests += n
+                test_files.append(rel)
+
+    metrics = [
+        MetricCount("api_routes", "API route definitions", routes, route_files),
+        MetricCount("db_models", "Database models", models, model_files),
+        MetricCount(
+            "migrations",
+            "Schema migrations",
+            len(migration_files),
+            migration_files,
+        ),
+        MetricCount("ui_components", "UI components", components, component_files),
+        MetricCount(
+            "service_modules",
+            "Service modules",
+            len(service_files),
+            service_files,
+        ),
+        MetricCount("tests", "Test functions", tests, test_files),
+    ]
+
+    return CodeFacts(
+        metrics=metrics,
+        languages=languages,
+        total_files=len(result.files),
+    )

receipts/mine/git_evidence.py

@@ -0,0 +1,109 @@
+"""Git history evidence — proves what code content can't.
+
+Duration claims ("2 years"), collaboration claims ("team of 5"), and
+delivery-volume claims ("shipped 40+ features") are invisible to code
+content but provable from commit history. Zero LLM calls; everything is
+read from the local repository. If the folder isn't a git repo (or is a
+shallow clone with no useful history), the result says so honestly —
+never guess.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+_MAX_COMMITS = 5000  # backstop against pathological histories
+
+
+@dataclass(frozen=True)
+class GitEvidence:
+    available: bool
+    reason: str = ""  # why unavailable, when available is False
+    first_commit_date: str = ""  # ISO date
+    last_commit_date: str = ""
+    active_months: int = 0
+    commit_count: int = 0
+    contributor_count: int = 0
+    contributors: list[str] = field(default_factory=list)
+    merge_count: int = 0
+
+    def summary_lines(self) -> list[str]:
+        if not self.available:
+            return [f"Git history: unavailable ({self.reason})"]
+        span = (
+            f"{self.first_commit_date} to {self.last_commit_date}"
+            f" (~{self.active_months} month(s))"
+        )
+        return [
+            f"Git history: {self.commit_count} commit(s) over {span}",
+            f"Contributors: {self.contributor_count}",
+            f"Merges: {self.merge_count}",
+        ]
+
+    def prompt_facts(self) -> str:
+        """Facts formatted for a rewrite prompt."""
+        if not self.available:
+            return ""
+        lines = [
+            f"- development span: {self.first_commit_date} to"
+            f" {self.last_commit_date} (~{self.active_months} months)",
+            f"- {self.commit_count} commits by"
+            f" {self.contributor_count} contributor(s)",
+        ]
+        if self.merge_count:
+            lines.append(f"- {self.merge_count} merge commits")
+        return "\n".join(lines)
+
+
+def mine_git_evidence(root: Path) -> GitEvidence:
+    """Read commit history from a local repo. Never raises for non-repos."""
+    try:
+        from git import InvalidGitRepositoryError, NoSuchPathError, Repo
+    except ImportError:  # pragma: no cover - GitPython is a hard dep
+        return GitEvidence(available=False, reason="GitPython not installed")
+
+    try:
+        repo = Repo(root, search_parent_directories=False)
+    except (InvalidGitRepositoryError, NoSuchPathError):
+        return GitEvidence(available=False, reason="not a git repository")
+
+    try:
+        commits = list(repo.iter_commits(max_count=_MAX_COMMITS))
+    except Exception as exc:  # empty repo, detached corruption, etc.
+        return GitEvidence(available=False, reason=f"no readable history: {exc}")
+
+    if not commits:
+        return GitEvidence(available=False, reason="repository has no commits")
+
+    # iter_commits yields newest first.
+    newest = commits[0]
+    oldest = commits[-1]
+
+    def _date(commit) -> datetime:
+        return datetime.fromtimestamp(commit.committed_date, tz=timezone.utc)
+
+    first_date = _date(oldest)
+    last_date = _date(newest)
+    span_days = max(0, (last_date - first_date).days)
+    active_months = max(1, round(span_days / 30.4))
+
+    authors: set[str] = set()
+    merge_count = 0
+    for c in commits:
+        name = (c.author.name or "").strip() or (c.author.email or "unknown")
+        authors.add(name)
+        if len(c.parents) > 1:
+            merge_count += 1
+
+    return GitEvidence(
+        available=True,
+        first_commit_date=first_date.date().isoformat(),
+        last_commit_date=last_date.date().isoformat(),
+        active_months=active_months,
+        commit_count=len(commits),
+        contributor_count=len(authors),
+        contributors=sorted(authors),
+        merge_count=merge_count,
+    )

receipts/prep/__init__.py

@@ -0,0 +1 @@
+"""Interview-prep artifacts — defense dossier and readiness tracking."""