oneport-impact 0.1.0__tar.gz

oneport_impact-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: oneport-impact
+Version: 0.1.0
+Summary: Blast-radius engine — what breaks if I touch this? Reverse call graph + git co-change mining + ownership, judged by an LLM, run entirely on your machine.
+Author: Oneport
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# Oneport Impact
+
+**"What breaks if I touch this?" — the blast-radius engine that reads your repo's own structure and history, on your machine.**
+
+Before you change a function, one command tells you who calls it, which tests
+cover it, which files *historically change with it*, and who to ask — then an LLM
+judges how load-bearing it is. `grep` finds text; Sourcegraph finds references.
+Neither tells you that `models.py` and `serializers.py` change together **83% of
+the time** even though there's no import between them. That temporal coupling
+lives only in git history — and Impact mines it locally, so nothing is uploaded
+to learn it.
+
+```
+$ oneport-impact analyze billing/stripe.py
+
+Blast radius: billing/stripe.py  (file)
+  LOAD-BEARING  ·  128 call site(s) across 34 file(s)  ·  61 commits in history
+
+  This is core payment code exercised across the app; a signature change here
+  ripples into checkout, webhooks, and the admin refund flow.
+  Check first: billing/webhooks.py  — changes with this file 83% of the time
+
+  Changes together with  (temporal coupling)
+     83%  billing/webhooks.py       (51/61 commits)
+     44%  tests/test_payments.py     (27/61 commits)
+  Ask
+     @payments-team  [CODEOWNER]
+     Priya Nair  (22 commits, last 2026-05-30)
+```
+
+## Why it's different
+
+| Tool | What it gives you | The gap |
+|---|---|---|
+| `grep` / IDE "find usages" | text matches | no ranking, no history, no judgment |
+| Sourcegraph | cross-repo references | search, not *risk*; needs your code on their servers |
+| **oneport-impact** | callers **+ temporal coupling + ownership + risk verdict** | **local-first — your code never leaves the machine** |
+
+Every fact is deterministic (Python `ast` + `git log`); the model only *judges*
+the facts. When a symbol's name is too common to attribute reliably (`__init__`,
+`get`), Impact **refuses to guess** rather than report an inflated number — the
+line between "structured, better than grep" and "confidently wrong."
+
+## Install
+
+```bash
+pip install oneport-impact
+# optional, for the risk verdict — detection works without it:
+export GEMINI_API_KEY=AIza...    # free at https://aistudio.google.com/apikey
+```
+
+## Use
+
+```bash
+# Query the blast radius of a symbol or file
+oneport-impact analyze charge                       # by name
+oneport-impact analyze billing.stripe.Client.charge # by qualname
+oneport-impact analyze billing/stripe.py            # by file
+
+# Gate a change set (for pre-commit / CI)
+oneport-impact check --staged        # what you're about to commit
+oneport-impact check --head          # the last commit
+oneport-impact check --staged --format json   # machine-readable
+
+oneport-impact analyze charge --no-llm   # facts only, no API key
+```
+
+Exit code is `1` when a change trips a blocking finding (per `--fail-on`),
+`0` otherwise — drop `check` straight into CI.
+
+### What the gate flags
+
+- **IMP001 — wide blast radius:** you're changing a symbol many places call.
+- **IMP010 — missing co-change companion:** you changed a file but *not* the file
+  it historically changes with, e.g. *"you changed `model.py` but not
+  `serializer.py`, which changes with it 80% of the time."*
+
+## Configure — `.oneportrc`
+
+```yaml
+thresholds:
+  fan_in_warn: 8            # callers before a change is "wide"
+  fan_in_error: 25          # …before it's "very wide"
+  cochange_confidence: 0.5  # a companion must co-change this often to be flagged
+  cochange_min_together: 3  # …and at least this many times
+  max_commits: 1500         # history depth mined for co-change
+```
+
+The same `.oneport/guidelines.md` the rest of the suite reads is fed to the risk
+verdict as context ("our payments module is business-critical").
+
+## In the Oneport gate
+
+`oneport-impact` is an opt-in gate in [`op ship`](https://pypi.org/project/oneport/).
+Enable it in `.oneport/oneport.yaml`:
+
+```yaml
+enable:
+  - impact
+```
+
+It's advisory by default (warns, blocks only on critical) — it informs the
+ship decision without nagging.
+
+## Privacy
+
+Serverless by design. The call graph, co-change mining, and ownership all run on
+your machine from your repo's own `.git`. Only the optional one-paragraph risk
+verdict calls a model, on your key. There is no Oneport server; your code never
+leaves the building.
+
+## How it works
+
+- **`callgraph.py`** — reverse call graph via the `ast` module, with an ambiguity
+  guard so common names don't inflate fan-in.
+- **`cochange.py`** — temporal-coupling miner over `git log`, skipping mass-change
+  commits that would couple everything.
+- **`ownership.py`** — git authors + CODEOWNERS.
+- **`advisor.py`** — the LLM risk verdict; judgment only, never invents facts.
+
+MIT licensed.

oneport_impact-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Oneport Impact
+
+**"What breaks if I touch this?" — the blast-radius engine that reads your repo's own structure and history, on your machine.**
+
+Before you change a function, one command tells you who calls it, which tests
+cover it, which files *historically change with it*, and who to ask — then an LLM
+judges how load-bearing it is. `grep` finds text; Sourcegraph finds references.
+Neither tells you that `models.py` and `serializers.py` change together **83% of
+the time** even though there's no import between them. That temporal coupling
+lives only in git history — and Impact mines it locally, so nothing is uploaded
+to learn it.
+
+```
+$ oneport-impact analyze billing/stripe.py
+
+Blast radius: billing/stripe.py  (file)
+  LOAD-BEARING  ·  128 call site(s) across 34 file(s)  ·  61 commits in history
+
+  This is core payment code exercised across the app; a signature change here
+  ripples into checkout, webhooks, and the admin refund flow.
+  Check first: billing/webhooks.py  — changes with this file 83% of the time
+
+  Changes together with  (temporal coupling)
+     83%  billing/webhooks.py       (51/61 commits)
+     44%  tests/test_payments.py     (27/61 commits)
+  Ask
+     @payments-team  [CODEOWNER]
+     Priya Nair  (22 commits, last 2026-05-30)
+```
+
+## Why it's different
+
+| Tool | What it gives you | The gap |
+|---|---|---|
+| `grep` / IDE "find usages" | text matches | no ranking, no history, no judgment |
+| Sourcegraph | cross-repo references | search, not *risk*; needs your code on their servers |
+| **oneport-impact** | callers **+ temporal coupling + ownership + risk verdict** | **local-first — your code never leaves the machine** |
+
+Every fact is deterministic (Python `ast` + `git log`); the model only *judges*
+the facts. When a symbol's name is too common to attribute reliably (`__init__`,
+`get`), Impact **refuses to guess** rather than report an inflated number — the
+line between "structured, better than grep" and "confidently wrong."
+
+## Install
+
+```bash
+pip install oneport-impact
+# optional, for the risk verdict — detection works without it:
+export GEMINI_API_KEY=AIza...    # free at https://aistudio.google.com/apikey
+```
+
+## Use
+
+```bash
+# Query the blast radius of a symbol or file
+oneport-impact analyze charge                       # by name
+oneport-impact analyze billing.stripe.Client.charge # by qualname
+oneport-impact analyze billing/stripe.py            # by file
+
+# Gate a change set (for pre-commit / CI)
+oneport-impact check --staged        # what you're about to commit
+oneport-impact check --head          # the last commit
+oneport-impact check --staged --format json   # machine-readable
+
+oneport-impact analyze charge --no-llm   # facts only, no API key
+```
+
+Exit code is `1` when a change trips a blocking finding (per `--fail-on`),
+`0` otherwise — drop `check` straight into CI.
+
+### What the gate flags
+
+- **IMP001 — wide blast radius:** you're changing a symbol many places call.
+- **IMP010 — missing co-change companion:** you changed a file but *not* the file
+  it historically changes with, e.g. *"you changed `model.py` but not
+  `serializer.py`, which changes with it 80% of the time."*
+
+## Configure — `.oneportrc`
+
+```yaml
+thresholds:
+  fan_in_warn: 8            # callers before a change is "wide"
+  fan_in_error: 25          # …before it's "very wide"
+  cochange_confidence: 0.5  # a companion must co-change this often to be flagged
+  cochange_min_together: 3  # …and at least this many times
+  max_commits: 1500         # history depth mined for co-change
+```
+
+The same `.oneport/guidelines.md` the rest of the suite reads is fed to the risk
+verdict as context ("our payments module is business-critical").
+
+## In the Oneport gate
+
+`oneport-impact` is an opt-in gate in [`op ship`](https://pypi.org/project/oneport/).
+Enable it in `.oneport/oneport.yaml`:
+
+```yaml
+enable:
+  - impact
+```
+
+It's advisory by default (warns, blocks only on critical) — it informs the
+ship decision without nagging.
+
+## Privacy
+
+Serverless by design. The call graph, co-change mining, and ownership all run on
+your machine from your repo's own `.git`. Only the optional one-paragraph risk
+verdict calls a model, on your key. There is no Oneport server; your code never
+leaves the building.
+
+## How it works
+
+- **`callgraph.py`** — reverse call graph via the `ast` module, with an ambiguity
+  guard so common names don't inflate fan-in.
+- **`cochange.py`** — temporal-coupling miner over `git log`, skipping mass-change
+  commits that would couple everything.
+- **`ownership.py`** — git authors + CODEOWNERS.
+- **`advisor.py`** — the LLM risk verdict; judgment only, never invents facts.
+
+MIT licensed.

oneport_impact-0.1.0/oneport_impact/__init__.py

@@ -0,0 +1,11 @@
+"""
+oneport-impact — the blast-radius engine.
+
+Answers "what breaks if I touch this?" from the repo's own structure and history:
+a reverse call graph (who calls it), git co-change mining (what moves with it), and
+ownership (who to ask) — judged by an LLM, run entirely on your machine.
+
+Part of the Oneport developer OS. Detection is deterministic; the model only judges.
+"""
+
+__version__ = "0.1.0"

oneport_impact-0.1.0/oneport_impact/advisor.py

@@ -0,0 +1,97 @@
+"""
+The risk-verdict layer — judgment, and only judgment.
+
+Input to the model: the deterministic facts about one target (fan-in, the caller
+files, the co-change partners with confidences, the owners) plus optional team
+guidelines. Output: a short plain-English risk read and the single consumer most
+worth checking. The model never adds a caller or partner — if it names something
+not in the facts, we ignore it.
+
+Skipped cleanly (leaving facts-only output) when there's no key or --no-llm.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from oneport_impact.config import Config
+from oneport_impact.exceptions import ImpactError
+from oneport_impact.llm import call_llm
+from oneport_impact.result import BlastRadius
+
+SYSTEM_PROMPT = """\
+You are a staff engineer assessing the blast radius of a proposed code change.
+You are given ONLY deterministic facts already computed from the repository:
+the target symbol/file, how many places call it (fan-in), the files that call it,
+the files that historically change together with it (temporal coupling, with a
+confidence %), and its owners.
+
+Do NOT invent callers, files, partners, or owners — reason only from the facts
+given. Judge how risky it is to change this target, and name the SINGLE consumer
+or coupled file most worth checking before the change ships.
+
+Reply with ONLY this JSON (no prose, no fences):
+{"verdict": "<2-3 sentences: how load-bearing is this, and why>",
+ "riskiest": "<one file or caller to check first, path only>",
+ "reason": "<one line: why that one>"}
+"""
+
+
+def _facts_block(br: BlastRadius, guidelines: str) -> str:
+    lines = [
+        f"Target: {br.target}  ({br.target_kind})",
+        f"Fan-in: {br.fan_in} call site(s) across {br.caller_files} file(s)",
+        f"History: the target file(s) changed in {br.target_commits} commit(s)",
+        "",
+        "Top calling files:",
+    ]
+    caller_files: dict[str, int] = {}
+    for c in br.callers:
+        caller_files[c.file] = caller_files.get(c.file, 0) + 1
+    for f, n in sorted(caller_files.items(), key=lambda x: -x[1])[:10]:
+        lines.append(f"  - {f} ({n} call site(s))")
+    if not caller_files:
+        lines.append("  (none found — no static callers)")
+
+    lines += ["", "Historically co-changed files (temporal coupling):"]
+    for p in br.partners[:10]:
+        lines.append(f"  - {p.path}  ({p.pct}% of the target's commits, {p.together}/{p.target_commits})")
+    if not br.partners:
+        lines.append("  (none)")
+
+    if br.owners:
+        lines += ["", "Owners: " + ", ".join(
+            (o.name + (" [CODEOWNER]" if o.codeowner else "")) for o in br.owners)]
+    if guidelines:
+        lines += ["", "Team guidelines (context; do not change the JSON schema):", guidelines[:1500]]
+    return "\n".join(lines)
+
+
+def _parse(text: str) -> dict:
+    cleaned = re.sub(r"^```(?:json)?\s*", "", text.strip())
+    cleaned = re.sub(r"\s*```$", "", cleaned)
+    m = re.search(r"\{.*\}", cleaned, re.DOTALL)
+    if m:
+        cleaned = m.group(0)
+    data = json.loads(cleaned)
+    if not isinstance(data, dict):
+        raise ValueError("expected a JSON object")
+    return data
+
+
+def assess(br: BlastRadius, config: Config, guidelines: str = "") -> int:
+    """Fill br.verdict/riskiest/reason in place. Returns tokens used (0 on skip)."""
+    if not config.api_key:
+        return 0
+    user = _facts_block(br, guidelines)
+    try:
+        text, tokens = call_llm(config.model, config.api_key, SYSTEM_PROMPT, user, config.max_tokens)
+        data = _parse(text)
+    except (ImpactError, ValueError, json.JSONDecodeError) as exc:
+        br.reason = f"(risk verdict unavailable: {str(exc)[:120]})"
+        return 0
+    br.verdict = str(data.get("verdict", "")).strip()
+    br.riskiest = str(data.get("riskiest", "")).strip()
+    br.reason = str(data.get("reason", "")).strip()
+    return tokens

oneport_impact-0.1.0/oneport_impact/analyzer.py

@@ -0,0 +1,206 @@
+"""
+The orchestrator: run the deterministic engines, assemble a BlastRadius, and — in
+gate mode — distil findings whose JSON matches the Oneport contract so `op ship`
+can merge impact with the other gates.
+
+Order per target: call graph (who calls it) + co-change (what moves with it) +
+ownership (who to ask) → optional LLM risk verdict. Facts first, judgment last.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from oneport_impact import advisor
+from oneport_impact.callgraph import CallGraph, build_call_graph
+from oneport_impact.cochange import CoChangeIndex, build_cochange_index
+from oneport_impact.config import Config
+from oneport_impact.exceptions import ResolveError
+from oneport_impact.guidelines import load_guidelines
+from oneport_impact.integrations import local_git
+from oneport_impact.ownership import owners_of
+from oneport_impact.result import (
+    BlastRadius, CallSite, Finding, ImpactReport, Severity, Symbol, TestRef,
+    compute_blocking,
+)
+
+_TEST_HINTS = ("test_", "_test", "/tests/", "tests/", "conftest", "/testing/")
+
+
+def is_test_path(path: str) -> bool:
+    p = path.replace("\\", "/").lower()
+    base = p.rsplit("/", 1)[-1]
+    return ("/tests/" in p or p.startswith("tests/") or "/testing/" in p
+            or base.startswith("test_") or base.endswith("_test.py") or "conftest" in base)
+
+
+class Analyzer:
+    def __init__(self, config: Config, root: str | Path = ".") -> None:
+        self.config = config
+        self.root = Path(root).resolve()
+        self._graph: CallGraph | None = None
+        self._cochange: CoChangeIndex | None = None
+        self._guidelines = load_guidelines(config.guidelines_path)
+        self._has_git = local_git.is_repo(self.root)
+
+    # ── shared, lazily-built indexes ─────────────────────────────────────────
+    @property
+    def graph(self) -> CallGraph:
+        if self._graph is None:
+            self._graph = build_call_graph(self.root)
+        return self._graph
+
+    @property
+    def cochange(self) -> CoChangeIndex:
+        if self._cochange is None:
+            self._cochange = (
+                build_cochange_index(self.root, max_commits=self.config.thresholds.max_commits)
+                if self._has_git else CoChangeIndex()
+            )
+        return self._cochange
+
+    # ── analyze mode ─────────────────────────────────────────────────────────
+    def analyze(self, query: str, use_llm: bool = True) -> ImpactReport:
+        start = time.monotonic()
+        report = ImpactReport(mode="analyze", target=query, model=self.config.model)
+
+        symbols = self.graph.resolve(query)
+        as_file = self._as_file(query)
+        if as_file and not (symbols and not as_file):
+            file_syms = self.graph.symbols_in_file(as_file)
+            br = self._blast_for_symbols(as_file, "file", file_syms, file_scope=as_file)
+        elif symbols:
+            br = self._blast_for_symbols(query, "symbol", symbols)
+        else:
+            raise ResolveError(
+                f"Could not find '{query}' as a symbol or a file in {self.root.name}. "
+                "Try a function/class name, a dotted qualname, or a repo-relative path."
+            )
+
+        skipped = self._ambiguous_skipped(br)
+        if skipped:
+            report.notes.append(
+                f"{skipped} symbol(s) here have names too common to attribute callers "
+                "reliably (e.g. __init__, get); their call sites are excluded to keep "
+                "fan-in honest.")
+        if not self._has_git:
+            report.notes.append("Not a git repo — co-change and ownership were skipped.")
+        if use_llm and self.config.api_key:
+            report.total_tokens += advisor.assess(br, self.config, self._guidelines)
+
+        report.blast_radii = [br]
+        report.elapsed_ms = int((time.monotonic() - start) * 1000)
+        return report
+
+    # ── check (gate) mode ────────────────────────────────────────────────────
+    def check(self, mode: str, use_llm: bool = True, fail_on: Severity = Severity.ERROR) -> ImpactReport:
+        start = time.monotonic()
+        report = ImpactReport(mode="check", target=mode, model=self.config.model)
+        local_git.require_repo(self.root)
+
+        changed = [f for f in local_git.changed_files(self.root, mode)]
+        changed_set = set(changed)
+        if not changed:
+            report.notes.append(f"No {mode} changes to analyze.")
+            report.elapsed_ms = int((time.monotonic() - start) * 1000)
+            return report
+
+        th = self.config.thresholds
+        radii: list[BlastRadius] = []
+        for f in changed:
+            if not (self.root / f).exists():
+                continue  # deleted file
+            file_syms = self.graph.symbols_in_file(f) if f.endswith(".py") else []
+            br = self._blast_for_symbols(f, "file", file_syms, file_scope=f)
+            radii.append(br)
+
+            # 1) wide blast radius
+            if br.fan_in >= th.fan_in_error:
+                report.findings.append(Finding(
+                    severity=Severity.ERROR, file=f, line=1, rule_id="IMP001",
+                    message=(f"Changing {f} affects {br.fan_in} call sites across "
+                             f"{br.caller_files} files — very wide blast radius."),
+                    fix="Split the change, add a compatibility shim, or land it behind a flag; "
+                        "review the top callers before merging."))
+            elif br.fan_in >= th.fan_in_warn:
+                report.findings.append(Finding(
+                    severity=Severity.WARNING, file=f, line=1, rule_id="IMP001",
+                    message=(f"Changing {f} affects {br.fan_in} call sites across "
+                             f"{br.caller_files} files — wide blast radius."),
+                    fix="Check the callers listed in the analysis before merging."))
+
+            # 2) companions you didn't touch
+            for p in br.partners:
+                if (p.confidence >= th.cochange_confidence and p.together >= th.cochange_min_together
+                        and p.path not in changed_set):
+                    report.findings.append(Finding(
+                        severity=Severity.WARNING, file=f, line=1, rule_id="IMP010",
+                        message=(f"You changed {f} but not {p.path}, which changes with it "
+                                 f"{p.pct}% of the time ({p.together}/{p.target_commits} commits)."),
+                        fix=f"Confirm {p.path} doesn't also need updating for this change."))
+
+        # LLM verdict on the single widest-radius file (cheap; enriches the report).
+        if use_llm and self.config.api_key and radii:
+            widest = max(radii, key=lambda b: b.fan_in)
+            if widest.fan_in > 0:
+                report.total_tokens += advisor.assess(widest, self.config, self._guidelines)
+
+        report.findings.sort(key=lambda f: (-f.severity.rank, f.file))
+        report.blast_radii = radii
+        report.blocking = compute_blocking(report.findings, fail_on)
+        report.elapsed_ms = int((time.monotonic() - start) * 1000)
+        return report
+
+    # ── core: assemble a BlastRadius from the engines ────────────────────────
+    def _blast_for_symbols(
+        self, target: str, kind: str, symbols: list[Symbol], file_scope: str | None = None,
+    ) -> BlastRadius:
+        # De-dupe callers by (file,line,called); a call site inside the target's own
+        # file is internal, not external blast radius.
+        seen: set[tuple] = set()
+        callers: list[CallSite] = []
+        for sym in symbols:
+            for c in self.graph.callers_of(sym):
+                if file_scope and c.file == file_scope:
+                    continue
+                key = (c.file, c.line, c.called)
+                if key in seen:
+                    continue
+                seen.add(key)
+                callers.append(c)
+
+        # co-change + ownership key off the file(s) involved.
+        files = sorted({s.file for s in symbols} or ({file_scope} if file_scope else set()))
+        partners = []
+        target_commits = 0
+        owners = []
+        if self._has_git and files:
+            primary = file_scope or files[0]
+            partners = self.cochange.partners(
+                primary, min_together=2, top=12)
+            target_commits = self.cochange.target_commit_count(primary)
+            owners = owners_of(self.root, primary, top=4)
+
+        tests = [
+            TestRef(test=c.caller_qualname, file=c.file, line=c.line)
+            for c in callers if is_test_path(c.file)
+        ]
+        non_test_callers = [c for c in callers if not is_test_path(c.file)]
+
+        return BlastRadius(
+            target=target, target_kind=kind, symbols=symbols,
+            callers=non_test_callers, tests=tests, partners=partners, owners=owners,
+            fan_in=len(non_test_callers),
+            caller_files=len({c.file for c in non_test_callers}),
+            target_commits=target_commits,
+        )
+
+    def _ambiguous_skipped(self, br: BlastRadius) -> int:
+        return sum(1 for s in br.symbols if not self.graph.attributable(s))
+
+    def _as_file(self, query: str) -> str | None:
+        rel = query.replace("\\", "/")
+        if (self.root / rel).is_file() and rel.endswith(".py"):
+            return rel
+        return None