pr-context-engine 0.1.0__py3-none-any.whl

pr_context_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: pr-context-engine
+Version: 0.1.0
+Summary: An AI tool that reads every PR and posts a senior-engineer-style briefing.
+Project-URL: Homepage, https://github.com/paramahastha/pr-context-engine
+Project-URL: Repository, https://github.com/paramahastha/pr-context-engine
+Project-URL: Issues, https://github.com/paramahastha/pr-context-engine/issues
+Project-URL: Changelog, https://github.com/paramahastha/pr-context-engine/blob/main/CHANGELOG.md
+Author-email: Kautsar <paramahastha@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,code-review,github,llm,pull-request
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastembed>=0.4
+Requires-Dist: google-genai>=1.0
+Requires-Dist: groq>=0.13
+Requires-Dist: pygithub>=2.4
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.32
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# PR Context Engine
+
+[![CI](https://github.com/paramahastha/pr-context-engine/actions/workflows/pr-review.yml/badge.svg)](https://github.com/paramahastha/pr-context-engine/actions/workflows/pr-review.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pr-context-engine)](https://pypi.org/project/pr-context-engine/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+
+> An AI tool that reads every PR and writes the briefing — and the fixes — a senior engineer would, with the calibration data to prove it's not just guessing.
+
+## What it does
+
+Every PR opens with three problems for the reviewer: _what is this actually doing_, _what could it break_, and _what should I push back on_. A diff doesn't answer any of those.
+
+PR Context Engine reads the diff plus surrounding code, recent git history, and semantically similar code from elsewhere in the repo, then posts a terse briefing written like a senior backend engineer would write it:
+
+```markdown
+## PR Briefing
+
+**What changed**
+Refactors the session token storage from an in-memory dict to Redis, adding a
+configurable TTL. The auth middleware is updated to hit Redis on every request.
+
+**Blast radius**
+Any caller of `get_session()` now depends on Redis being reachable. If Redis is
+down, all authenticated requests will 401. The previous in-memory store had no
+such single point of failure.
+
+**Risk flags**
+- `modifies_auth`: src/auth/session.py line 42 — `token = generate_token(user_id)`
+
+**Questions for the reviewer**
+
+1. The Redis client is initialised once at import time — is there a reconnect
+   strategy if the connection drops mid-deploy?
+2. `SESSION_TTL` defaults to 3600 but the old in-memory store had no TTL — have
+   existing sessions been migrated or will they all expire immediately after deploy?
+3. There are no tests for the Redis-down path — is 401-on-outage the intended
+   degradation, or should it fall back to the old store?
+```
+
+No praise. No filler. No "this LGTM." Just the context a reviewer needs.
+
+## Quickstart (5 minutes)
+
+### Option A — GitHub Action (recommended)
+
+1. Get a free [Groq API key](https://console.groq.com/keys) — no credit card.
+2. Add it as a secret: **Settings → Secrets → Actions → New secret** → `GROQ_API_KEY`.
+3. Enable write permissions: **Settings → Actions → General → Workflow permissions → Read and write**.
+4. Add this to `.github/workflows/pr-briefing.yml`:
+
+```yaml
+name: PR Briefing
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  brief:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: paramahastha/pr-context-engine@main
+        with:
+          groq-api-key: ${{ secrets.GROQ_API_KEY }}
+```
+
+That's it. Every new PR gets a briefing comment automatically.
+
+### Option B — CLI (any CI or local)
+
+```bash
+pipx install pr-context-engine
+export GROQ_API_KEY=<your-groq-key>
+export GITHUB_TOKEN=$(gh auth token)
+
+# Check your setup first
+pr-context-engine quickstart
+
+# Dry-run: see the briefing without posting it
+pr-context-engine review --pr 42 --repo owner/name --dry-run
+
+# Post the real comment
+pr-context-engine review --pr 42 --repo owner/name
+```
+
+## Switching LLM providers
+
+Set `LLM_PROVIDER` to any of `groq` (default), `gemini`, `ollama`, or `anthropic`. Nothing downstream changes.
+
+| Provider | Key env var | Notes |
+|---|---|---|
+| `groq` *(default)* | `GROQ_API_KEY` | Free, ~1 000 req/day, fast |
+| `gemini` | `GEMINI_API_KEY` | Free-tier fallback; auto-engaged on Groq 429 |
+| `ollama` | — | Local, offline, no rate limits |
+| `anthropic` | `ANTHROPIC_API_KEY` | BYO key, no free tier |
+
+**Automatic failover:** if `GEMINI_API_KEY` is set, the tool fails over to Gemini on any Groq 429 or error and notes it in the PR comment footer. See [ADR-7](docs/design-decisions.md).
+
+## Fix suggestions (opt-in)
+
+When `ENABLE_FIXES=true`, the tool generates confidence-gated patch suggestions for located issues. Only `high`/`medium` confidence suggestions become one-click GitHub suggestion blocks; `low` confidence produces prose notes only. Max 3 suggestions per PR.
+
+```yaml
+- uses: paramahastha/pr-context-engine@main
+  with:
+    groq-api-key: ${{ secrets.GROQ_API_KEY }}
+    enable-fixes: "true"
+```
+
+See [ADR-5](docs/design-decisions.md) for why this is opt-in and confidence-gated.
+
+## Eval results
+
+`pytest tests/eval/` produces a scorecard across five rubric dimensions (Accuracy, Blast radius, Risk flags, Question quality, Brevity) plus fix correctness and calibration rate.
+
+```
+pytest tests/eval/ -v
+```
+
+Results are committed to `tests/eval/scores/` so improvements are visible in git history. The headline metrics are **fix correctness rate** and **false-confidence rate** (when the model said `high` confidence, how often was the patch actually correct).
+
+## Architecture
+
+```
+Front door A:                    Front door B:
+GitHub Action wrapper            pipx install + run in any CI / locally
+(paramahastha/pr-context-engine@main)
+     │                                 │
+     └────────────┬────────────────────┘
+                  ▼
+     ┌─────────────────────────────────────┐
+     │  CLI core (src/cli.py + orchestrator)│
+     └─────────────────────────────────────┘
+                  │
+     ├──► analyzers/   diff → FileChange objects, AST symbols, risk flags
+     ├──► context/     git history, sqlite-vec codebase index (RAG)
+     ├──► briefing/    prompt assembly → LLM call → structured output
+     ├──► fixes/       confidence-gated patch suggestions (opt-in)
+     ├──► llm/         pluggable providers + FailoverProvider
+     └──► github_api/  fetch diff, post comment + suggestion blocks
+```
+
+The CLI is the product; the GitHub Action is a thin wrapper. See [docs/architecture.md](docs/architecture.md) and [docs/design-decisions.md](docs/design-decisions.md).
+
+## Data & privacy
+
+**What leaves your machine:**
+
+- The PR diff and parsed metadata (file paths, function names, changed lines) are sent to the active LLM provider (Groq or Gemini by default).
+- No source code beyond the diff is sent to any external API. The codebase index (RAG) runs entirely locally via `fastembed` + `sqlite-vec`.
+- Git history and PR metadata are fetched from the GitHub API using your `GITHUB_TOKEN`.
+
+**Provider data policies:**
+
+- Groq and Gemini free tiers may use inputs for model improvement. See their respective privacy policies before using on private/sensitive repos.
+- Use `LLM_PROVIDER=ollama` or `LLM_PROVIDER=anthropic` (with `ANTHROPIC_API_KEY`) if you need a provider with stronger data-isolation guarantees.
+- The tool has no shared backend. Your API key, your quota, your data.
+
+## Configuration
+
+See [CONFIG.md](CONFIG.md) for the full reference of every env var and flag.
+
+## Design decisions
+
+See [docs/design-decisions.md](docs/design-decisions.md) for ADRs covering: why provider abstraction is built early, why SQLite over Pinecone, why fixes are opt-in, why MIT license, and more.
+
+## Cost
+
+**$0/month** for a portfolio-scale project on public repos.
+
+- GitHub Actions: free for public repos.
+- Groq: free tier, ~1 000 req/day.
+- Gemini fallback: free tier (~1 500 req/day).
+- Local embeddings (`fastembed`): $0, no API.
+- The tool has no shared backend — your usage costs stay yours regardless of how many repos adopt it.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and feature requests go in [Issues](https://github.com/paramahastha/pr-context-engine/issues).

pr_context_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+src/__init__.py,sha256=9U8spJ1Nik8O_SIaxHfvCziQNnDznBLkFLTmwh6PTWo,86
+src/cli.py,sha256=7N38jtvZaUf0-By3InV5amvJu_V3EBVz8cOTbWiPBdk,12485
+src/config.py,sha256=mtKU-yQ08yW97Q0q5vm1WKzcmP_HuygI1_Z6Xlh3mmw,4330
+src/analyzers/__init__.py,sha256=jFjeVTITbZkwyBJdDaPNmqAWUKoRSW9anPM6ehC118E,67
+src/analyzers/ast_walker.py,sha256=diPpIkkHCUoBc3BajhnQcMEqP9WS6xgkRknb9aNQGhQ,3077
+src/analyzers/diff_parser.py,sha256=BQxARCilVCOEKCCtIueFJ97Pqfcppmi7-1hs6czy660,4597
+src/analyzers/risk_scorer.py,sha256=xorEGUJufNkSIwByI74GEiSIS19WGmwwQ3FwXxqC4wE,4432
+src/briefing/__init__.py,sha256=BbZvpF8rkJCMMa-wHOrP8d6_63sr1gEqBTs_at8GYng,268
+src/briefing/generator.py,sha256=dwgNQQZVPYWUFnqANmjF8D1VWjXDh7DPCXX0SYOuPSI,8524
+src/briefing/prompt_templates.py,sha256=hETpUrnCnFVAUM9N1kBhspRU2f4TVSlJJx0hgYuQj7w,2977
+src/context/__init__.py,sha256=bvCr3d-RGYzl9TJKB45FCsYV-jKqZdLj8kCWnMXD9A4,63
+src/context/codebase_index.py,sha256=BoL43v7gx7WsFKiWWgA3rzMVFqB3r3pDXoCB_W68zTE,12855
+src/context/git_history.py,sha256=xH6-tzQcm98eZgvif8Tdtrn1OpCdy3TUdlqZgLkGlLE,6998
+src/fixes/__init__.py,sha256=AKT9jw7a5t7N4CgExQFXwzkPoVzqMQxjYbwO2asuAKU,77
+src/fixes/confidence.py,sha256=XHCYz-Gvfo1x13iqgsiXoOWpscURbZ_zTlKXU7QmbF4,2362
+src/fixes/fix_generator.py,sha256=wVhWw2mGJyrB6YkAqKXkbzWlXmbgVDDqAtllSrIOES4,5246
+src/github_api/__init__.py,sha256=Yfp6ghTndiB9W8ZwihQtn7sV2j1W2sjEqP7Rt-8_AZ0,119
+src/github_api/comment_poster.py,sha256=MABH2IXgrkxtYdurNKDop-HXWYw8Yo_Pw3cR7wvQ1i8,3606
+src/llm/__init__.py,sha256=-Cq5eXoq-PA8eCXMTVpobExO1WDVoWopDcFp1-XDK1M,3992
+src/llm/anthropic_provider.py,sha256=CiyOy_39NoMeCJtFKnGb6wJq80cTvRuztof3HBm6MDk,1115
+src/llm/base.py,sha256=znllM7OL2-bUuMiQWZXfso4CEgKdw2brnfnCoK2FZSc,380
+src/llm/gemini_provider.py,sha256=Ebt9U5PokIv6zo6TMIocjyqsTF4h5YDfmMbnkmH1zmg,1108
+src/llm/groq_provider.py,sha256=AfxWuHqweiR32A4k9fgI65Hg5rRWnN70YpbF9vpia-g,1024
+src/llm/ollama_provider.py,sha256=8Cuk-XC5wAmtxbEJPu5xtDjKwskVD1Zzdys9cbOlHVw,1338
+pr_context_engine-0.1.0.dist-info/METADATA,sha256=Nu0j59OAfsK0QSdQfAJ5spS3wAbNdrim7q9RlIWjrUg,9135
+pr_context_engine-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pr_context_engine-0.1.0.dist-info/entry_points.txt,sha256=2oEE7GUgLRI-AEZjdwZNAUWozo0WSZ4CdFWTpY3wBfM,50
+pr_context_engine-0.1.0.dist-info/licenses/LICENSE,sha256=loMg3YX5UJ1jw9YfqlBrQRWiBb60WkMTM6OcwlLheIk,1064
+pr_context_engine-0.1.0.dist-info/RECORD,,

pr_context_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pr_context_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pr-context-engine = src.cli:app

pr_context_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kautsar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/__init__.py

@@ -0,0 +1 @@
+"""PR Context Engine — an AI tool that briefs pull requests for human reviewers."""

src/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Diff analysis: parsing, symbol extraction, and risk scoring."""

src/analyzers/ast_walker.py

@@ -0,0 +1,91 @@
+"""Extract names of changed functions and classes from a FileChange.
+
+Uses Python's `ast` module for Python files and language-specific regexes
+for JavaScript, TypeScript, and Go. Falls back to a generic regex for unknown
+languages. Only lines that appear in the diff (added or removed) are scanned —
+we report which named symbols were touched, not a full symbol table.
+"""
+import ast
+import logging
+import re
+
+from src.analyzers.diff_parser import FileChange
+
+logger = logging.getLogger(__name__)
+
+# Patterns keyed by language; each pattern has one capturing group: the symbol name.
+_PATTERNS: dict[str, list[re.Pattern[str]]] = {
+    "python": [
+        re.compile(r"^(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^class\s+([A-Za-z_][A-Za-z0-9_]*)"),
+    ],
+    "javascript": [
+        re.compile(r"^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)"),
+        re.compile(r"^(?:export\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)"),
+        re.compile(
+            r"^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+            r"\s*=\s*(?:async\s+)?(?:function|\()"
+        ),
+    ],
+    "go": [
+        re.compile(r"^func\s+(?:\([^)]+\)\s+)?([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^type\s+([A-Za-z_][A-Za-z0-9_]*)\s+struct"),
+    ],
+}
+_PATTERNS["typescript"] = _PATTERNS["javascript"]
+
+
+def _names_via_regex(lines: list[str], language: str) -> list[str]:
+    patterns = _PATTERNS.get(language, [])
+    names: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        for pat in patterns:
+            m = pat.match(stripped)
+            if m:
+                names.append(m.group(1))
+                break
+    return names
+
+
+def _names_via_ast(lines: list[str]) -> list[str]:
+    """Try to parse Python lines as a module and extract def/class names at any depth.
+
+    Returns an empty list on any parse failure — the caller falls back to regex.
+    """
+    source = "\n".join(lines)
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+    names: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            names.append(node.name)
+    return names
+
+
+def extract_changed_symbols(change: FileChange) -> list[str]:
+    """Return deduplicated names of functions/classes touched in this file's diff.
+
+    Combines names found in both added and removed lines so the caller knows
+    which symbols were modified (added, changed, or deleted).
+    """
+    all_lines = change.added_lines + change.removed_lines
+
+    names: list[str] = []
+    if change.language == "python":
+        names = _names_via_ast(all_lines)
+        if not names:
+            names = _names_via_regex(all_lines, "python")
+    else:
+        names = _names_via_regex(all_lines, change.language)
+
+    # preserve order while deduplicating
+    seen: set[str] = set()
+    unique: list[str] = []
+    for name in names:
+        if name not in seen:
+            seen.add(name)
+            unique.append(name)
+    return unique

src/analyzers/diff_parser.py

@@ -0,0 +1,158 @@
+"""Parse a unified diff string into structured FileChange objects."""
+import os
+import re
+from dataclasses import dataclass, field
+
+_EXT_LANG: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".go": "go",
+    ".rb": "ruby",
+    ".java": "java",
+    ".rs": "rust",
+    ".c": "c",
+    ".cpp": "cpp",
+    ".cs": "csharp",
+    ".php": "php",
+    ".sh": "shell",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".json": "json",
+    ".toml": "toml",
+    ".sql": "sql",
+    ".md": "markdown",
+    ".html": "html",
+    ".css": "css",
+}
+
+def detect_language(path: str) -> str:
+    """Return the markdown fence language identifier for a file path, or empty string."""
+    return _EXT_LANG.get(os.path.splitext(path)[1].lower(), "")
+
+
+_HUNK_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+
+
+@dataclass
+class Hunk:
+    """One @@ block from a unified diff, with its raw diff lines."""
+
+    old_start: int
+    old_count: int
+    new_start: int
+    new_count: int
+    lines: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FileChange:
+    """All changes for a single file extracted from a unified diff."""
+
+    path: str
+    language: str
+    added_lines: list[str]
+    removed_lines: list[str]
+    hunks: list[Hunk]
+    is_new_file: bool = False
+    is_deleted_file: bool = False
+
+
+def _detect_language(path: str) -> str:
+    if "." not in path:
+        return "unknown"
+    suffix = "." + path.rsplit(".", 1)[-1].lower()
+    return _EXT_LANG.get(suffix, "unknown")
+
+
+def parse_diff(diff_text: str) -> list[FileChange]:
+    """Parse a unified diff string into a list of FileChange objects.
+
+    Handles new files (--- /dev/null), deleted files (+++ /dev/null), and
+    standard modifications. Each FileChange includes per-hunk line data with
+    positional information needed by the risk scorer.
+    """
+    changes: list[FileChange] = []
+    current: FileChange | None = None
+    current_hunk: Hunk | None = None
+    pending_new = False
+    pending_deleted = False
+    pending_old_path = ""
+
+    def _push_hunk() -> None:
+        nonlocal current_hunk
+        if current is not None and current_hunk is not None:
+            current.hunks.append(current_hunk)
+            current_hunk = None
+
+    def _push_file() -> None:
+        nonlocal current, pending_new, pending_deleted, pending_old_path
+        _push_hunk()
+        if current is not None:
+            changes.append(current)
+        current = None
+        pending_new = False
+        pending_deleted = False
+        pending_old_path = ""
+
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git "):
+            _push_file()
+            continue
+
+        if line.startswith("new file mode"):
+            pending_new = True
+            continue
+
+        if line.startswith("deleted file mode"):
+            pending_deleted = True
+            continue
+
+        if line.startswith("--- "):
+            raw = line[4:]
+            pending_old_path = raw[2:] if raw.startswith("a/") else raw
+            if pending_old_path == "/dev/null":
+                pending_new = True
+            continue
+
+        if line.startswith("+++ "):
+            _push_hunk()
+            raw = line[4:]
+            new_path = raw[2:] if raw.startswith("b/") else raw
+            if new_path == "/dev/null":
+                pending_deleted = True
+                new_path = pending_old_path
+            current = FileChange(
+                path=new_path,
+                language=_detect_language(new_path),
+                added_lines=[],
+                removed_lines=[],
+                hunks=[],
+                is_new_file=pending_new,
+                is_deleted_file=pending_deleted,
+            )
+            continue
+
+        if line.startswith("@@") and current is not None:
+            _push_hunk()
+            m = _HUNK_RE.match(line)
+            if m:
+                current_hunk = Hunk(
+                    old_start=int(m.group(1)),
+                    old_count=int(m.group(2) or "1"),
+                    new_start=int(m.group(3)),
+                    new_count=int(m.group(4) or "1"),
+                )
+            continue
+
+        if current_hunk is not None and current is not None:
+            current_hunk.lines.append(line)
+            if line.startswith("+") and not line.startswith("+++"):
+                current.added_lines.append(line[1:])
+            elif line.startswith("-") and not line.startswith("---"):
+                current.removed_lines.append(line[1:])
+
+    _push_file()
+    return changes

src/analyzers/risk_scorer.py

@@ -0,0 +1,121 @@
+"""Heuristic risk-flag detection over parsed diff changes.
+
+Each flag is a located issue object carrying enough information for Milestone 8's
+fix generator: which file, which line (or None when a specific line doesn't apply),
+and a short snippet. Flags where `line` is None are briefing-only and never fix-eligible.
+"""
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from src.analyzers.diff_parser import FileChange
+
+_AUTH_RE = re.compile(
+    # Use letter-only boundaries so compound names like auth_token / AUTH_SECRET match.
+    r"(?<![a-zA-Z])(auth|token|password|secret|permission|credential|api_key|apikey)(?![a-zA-Z])",
+    re.IGNORECASE,
+)
+
+# Top-level function/method definition patterns for public-API deletion detection.
+# We only match lines with no leading whitespace (top-level scope).
+_FUNC_DEF_RE = re.compile(
+    r"^(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)"  # Python
+    r"|^func\s+(?:\([^)]+\)\s+)?([A-Za-z_][A-Za-z0-9_]*)"  # Go
+    r"|^export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)"  # JS/TS named function
+    r"|^export\s+(?:const|let)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s+)?\("  # JS/TS arrow
+)
+
+_MIGRATION_MARKERS = ("migrations/", "alembic/", "alembic_migrations/")
+
+
+@dataclass
+class RiskFlag:
+    """A located risk signal from heuristic analysis of a diff.
+
+    `line` is the line number in the relevant file version:
+      - new-file line for `modifies_auth` (the code being added)
+      - old-file line for `deletes_public_api` (where the definition existed)
+      - None for whole-file flags (`touches_migration`, `changes_config`)
+    """
+
+    flag: str
+    file: str
+    line: int | None
+    snippet: str
+
+
+def _is_migration(path: str) -> bool:
+    lower = path.lower()
+    return any(m in lower for m in _MIGRATION_MARKERS) or lower.endswith(".sql")
+
+
+def _is_config(path: str) -> bool:
+    """True for .env*, config.*, or *.yaml/yml files at the repo root."""
+    name = Path(path).name.lower()
+    parts = path.replace("\\", "/").split("/")
+    at_root = len(parts) == 1
+
+    if name.startswith(".env"):
+        return True
+    if name.startswith("config.") and at_root:
+        return True
+    if name.endswith((".yaml", ".yml")) and at_root:
+        return True
+    return False
+
+
+def score(changes: list[FileChange]) -> list[RiskFlag]:
+    """Return all risk flags detected across the list of file changes."""
+    flags: list[RiskFlag] = []
+
+    for change in changes:
+        if _is_migration(change.path):
+            flags.append(
+                RiskFlag(flag="touches_migration", file=change.path, line=None, snippet=change.path)
+            )
+
+        if _is_config(change.path):
+            flags.append(
+                RiskFlag(flag="changes_config", file=change.path, line=None, snippet=change.path)
+            )
+
+        for hunk in change.hunks:
+            new_lineno = hunk.new_start
+            old_lineno = hunk.old_start
+
+            for raw in hunk.lines:
+                if raw.startswith("+") and not raw.startswith("+++"):
+                    content = raw[1:]
+                    if _AUTH_RE.search(content):
+                        flags.append(
+                            RiskFlag(
+                                flag="modifies_auth",
+                                file=change.path,
+                                line=new_lineno,
+                                snippet=content.strip()[:200],
+                            )
+                        )
+                    new_lineno += 1
+
+                elif raw.startswith("-") and not raw.startswith("---"):
+                    content = raw[1:]
+                    # Only flag top-level (no leading whitespace) function removals
+                    if not content[:1].isspace():
+                        m = _FUNC_DEF_RE.match(content)
+                        if m:
+                            flags.append(
+                                RiskFlag(
+                                    flag="deletes_public_api",
+                                    file=change.path,
+                                    line=old_lineno,
+                                    snippet=content.strip()[:200],
+                                )
+                            )
+                    old_lineno += 1
+
+                else:
+                    # context line — advances both counters
+                    new_lineno += 1
+                    old_lineno += 1
+
+    return flags

src/briefing/__init__.py

@@ -0,0 +1,5 @@
+"""PR briefing generation with senior-engineer-voice prompts and structured output."""
+from src.briefing.generator import Briefing, generate_briefing
+from src.briefing.prompt_templates import SYSTEM_PROMPT
+
+__all__ = ["Briefing", "generate_briefing", "SYSTEM_PROMPT"]