prism-code-review 2.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
prism/reports.py ADDED
@@ -0,0 +1,277 @@
1
+ """
2
+ Local report storage for PRISM findings.
3
+
4
+ Saves every review result to .prism-reports/ so developers can:
5
+ - View history of all reviews
6
+ - See what was fixed and what remains
7
+ - Track risk score over time
8
+ - Review past findings without re-running
9
+
10
+ No server, no database, no cloud — just local JSON files.
11
+ """
12
+
13
+ import json
14
+ import os
15
+ from datetime import datetime, timezone
16
+ from pathlib import Path
17
+ from typing import List, Optional
18
+
19
+ REPORTS_DIR = ".prism-reports"
20
+ REPORT_INDEX = os.path.join(REPORTS_DIR, "index.json")
21
+
22
+
23
+ def _ensure_dir():
24
+ Path(REPORTS_DIR).mkdir(parents=True, exist_ok=True)
25
+
26
+
27
+ def _next_report_id() -> str:
28
+ """Return a report ID that no stored report is already using.
29
+
30
+ The ID is a timestamp with microsecond precision, and the Windows clock
31
+ advances in ~15 ms steps, so two reviews saved back to back could be handed
32
+ the same ID. The second report then overwrote the first on disk while the
33
+ index kept both entries, so the totals counted one report twice and a review
34
+ vanished. A suffix keeps both files and keeps the ID readable.
35
+ """
36
+ base = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
37
+ candidate, suffix = base, 1
38
+ while os.path.exists(os.path.join(REPORTS_DIR, "{}.json".format(candidate))):
39
+ candidate = "{}-{}".format(base, suffix)
40
+ suffix += 1
41
+ return candidate
42
+
43
+
44
+ def save_report(
45
+ files_reviewed: List[str],
46
+ findings: List[dict],
47
+ risk_score: float,
48
+ blocking: int,
49
+ commit_allowed: bool,
50
+ commit_hash: str = "",
51
+ branch: str = "",
52
+ token_usage: Optional[dict] = None,
53
+ ) -> str:
54
+ """Save a review report to .prism-reports/ and return the report ID.
55
+
56
+ ``token_usage`` is the per-review ledger snapshot from
57
+ :func:`prism.token_usage.summary`. Reports written before token tracking
58
+ existed simply lack the field; readers must treat "absent" as unknown, not
59
+ as zero, or cost trends get a fake dip.
60
+ """
61
+ _ensure_dir()
62
+
63
+ report_id = _next_report_id()
64
+ report = {
65
+ "id": report_id,
66
+ "timestamp": datetime.now(timezone.utc).isoformat(),
67
+ "commit_hash": commit_hash,
68
+ "branch": branch,
69
+ "files_reviewed": files_reviewed,
70
+ "total_findings": len(findings),
71
+ "blocking": blocking,
72
+ "risk_score": risk_score,
73
+ "commit_allowed": commit_allowed,
74
+ "token_usage": token_usage,
75
+ "findings": findings,
76
+ }
77
+
78
+ # Save individual report
79
+ report_path = os.path.join(REPORTS_DIR, f"{report_id}.json")
80
+ with open(report_path, "w") as f:
81
+ json.dump(report, f, indent=2)
82
+
83
+ # Update index
84
+ _update_index(report_id, report)
85
+
86
+ return report_id
87
+
88
+
89
+ def _update_index(report_id: str, report: dict):
90
+ """Add or update entry in the index file."""
91
+ index = load_index()
92
+ index["reports"].append({
93
+ "id": report_id,
94
+ "timestamp": report["timestamp"],
95
+ "commit_hash": report["commit_hash"],
96
+ "branch": report["branch"],
97
+ "files_reviewed": report["files_reviewed"],
98
+ "total_findings": report["total_findings"],
99
+ "blocking": report["blocking"],
100
+ "risk_score": report["risk_score"],
101
+ "commit_allowed": report["commit_allowed"],
102
+ "token_usage": report.get("token_usage"),
103
+ })
104
+ # Keep last 500 entries
105
+ if len(index["reports"]) > 500:
106
+ index["reports"] = index["reports"][-500:]
107
+
108
+ with open(REPORT_INDEX, "w") as f:
109
+ json.dump(index, f, indent=2)
110
+
111
+
112
+ def load_index() -> dict:
113
+ """Load the report index."""
114
+ if os.path.exists(REPORT_INDEX):
115
+ with open(REPORT_INDEX) as f:
116
+ return json.load(f)
117
+ return {"reports": []}
118
+
119
+
120
+ def load_report(report_id: str) -> Optional[dict]:
121
+ """Load a specific report by ID."""
122
+ path = os.path.join(REPORTS_DIR, f"{report_id}.json")
123
+ if os.path.exists(path):
124
+ with open(path) as f:
125
+ return json.load(f)
126
+ return None
127
+
128
+
129
+ def get_recent_reports(limit: int = 20) -> List[dict]:
130
+ """Get the most recent reports."""
131
+ index = load_index()
132
+ return index["reports"][-limit:]
133
+
134
+
135
+ def get_findings_history() -> dict:
136
+ """Get a summary of findings over time for trend analysis."""
137
+ index = load_index()
138
+ trends = {
139
+ "total_reviews": len(index["reports"]),
140
+ "total_findings": 0,
141
+ "total_blocking": 0,
142
+ "commits_blocked": 0,
143
+ "risk_scores": [],
144
+ "findings_by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0},
145
+ "findings_by_agent": {},
146
+ "findings_by_rule": {},
147
+ # Token accounting. ``ai_reviews`` counts only reports that actually
148
+ # spent tokens, so a repo that never configured a key shows 0 rather
149
+ # than "one review with zero tokens".
150
+ "total_tokens": 0,
151
+ "input_tokens": 0,
152
+ "output_tokens": 0,
153
+ "ai_reviews": 0,
154
+ "estimated_token_calls": 0,
155
+ }
156
+
157
+ for r in index["reports"]:
158
+ trends["total_findings"] += r["total_findings"]
159
+ trends["total_blocking"] += r["blocking"]
160
+ if not r["commit_allowed"]:
161
+ trends["commits_blocked"] += 1
162
+ trends["risk_scores"].append({
163
+ "timestamp": r["timestamp"],
164
+ "risk_score": r["risk_score"],
165
+ })
166
+
167
+ # Scan individual reports for detailed stats
168
+ for r in index["reports"]:
169
+ report = load_report(r["id"])
170
+ if report:
171
+ token_usage = report.get("token_usage")
172
+ if token_usage:
173
+ trends["total_tokens"] += token_usage.get("total_tokens", 0)
174
+ trends["input_tokens"] += token_usage.get("input_tokens", 0)
175
+ trends["output_tokens"] += token_usage.get("output_tokens", 0)
176
+ trends["estimated_token_calls"] += token_usage.get(
177
+ "estimated_calls", 0)
178
+ if token_usage.get("calls"):
179
+ trends["ai_reviews"] += 1
180
+ for f in report.get("findings", []):
181
+ sev = f.get("severity", "unknown")
182
+ agent = f.get("agent", "unknown")
183
+ rule = f.get("rule_id", "unknown")
184
+ trends["findings_by_severity"][sev] = \
185
+ trends["findings_by_severity"].get(sev, 0) + 1
186
+ trends["findings_by_agent"][agent] = \
187
+ trends["findings_by_agent"].get(agent, 0) + 1
188
+ if rule:
189
+ trends["findings_by_rule"][rule] = \
190
+ trends["findings_by_rule"].get(rule, 0) + 1
191
+
192
+ return trends
193
+
194
+
195
+ def delete_report(report_id: str) -> bool:
196
+ """Delete a specific report by ID. Returns True if deleted, False if not found."""
197
+ report_path = os.path.join(REPORTS_DIR, f"{report_id}.json")
198
+ if os.path.exists(report_path):
199
+ os.remove(report_path)
200
+ # Update index
201
+ index = load_index()
202
+ index["reports"] = [r for r in index["reports"] if r["id"] != report_id]
203
+ with open(REPORT_INDEX, "w") as f:
204
+ json.dump(index, f, indent=2)
205
+ return True
206
+ return False
207
+
208
+
209
+ def clear_reports() -> int:
210
+ """Delete all report files. Returns the number of reports deleted.
211
+
212
+ Deletes files individually rather than rmtree-ing the directory, because
213
+ on Windows the directory itself can be locked (e.g. open in Explorer or
214
+ a file handle held by the dashboard), causing PermissionError.
215
+ """
216
+ if not os.path.exists(REPORTS_DIR):
217
+ return 0
218
+ count = 0
219
+ for name in os.listdir(REPORTS_DIR):
220
+ if not name.endswith(".json"):
221
+ continue
222
+ # index.json is bookkeeping, not a report: deleting it is fine, but it
223
+ # must not inflate the "Deleted N report(s)" count.
224
+ is_index = name == "index.json"
225
+ path = os.path.join(REPORTS_DIR, name)
226
+ try:
227
+ os.remove(path)
228
+ if not is_index:
229
+ count += 1
230
+ except OSError:
231
+ pass
232
+ return count
233
+
234
+
235
+ def get_report_summary() -> str:
236
+ """Get a human-readable summary of all reports."""
237
+ trends = get_findings_history()
238
+ lines = [
239
+ "PRISM Report Summary",
240
+ "====================",
241
+ f"Total reviews: {trends['total_reviews']}",
242
+ f"Total findings: {trends['total_findings']}",
243
+ f"Commits blocked: {trends['commits_blocked']}",
244
+ ]
245
+
246
+ if trends["total_tokens"]:
247
+ lines.append(
248
+ f"Total tokens: {trends['total_tokens']:,} "
249
+ f"(in {trends['input_tokens']:,} / out {trends['output_tokens']:,}) "
250
+ f"across {trends['ai_reviews']} AI review(s)")
251
+ if trends["estimated_token_calls"]:
252
+ lines.append(
253
+ f" {trends['estimated_token_calls']} call(s) used estimated "
254
+ f"counts (provider reported no usage)")
255
+
256
+ lines.extend([
257
+ "",
258
+ "By Severity:",
259
+ ])
260
+ for sev, count in trends["findings_by_severity"].items():
261
+ lines.append(f" {sev}: {count}")
262
+
263
+ lines.append("")
264
+ lines.append("By Agent:")
265
+ for agent, count in trends["findings_by_agent"].items():
266
+ lines.append(f" {agent}: {count}")
267
+
268
+ if trends["findings_by_rule"]:
269
+ lines.append("")
270
+ lines.append("Top Rules:")
271
+ for rule, count in sorted(
272
+ trends["findings_by_rule"].items(),
273
+ key=lambda x: x[1], reverse=True
274
+ )[:10]:
275
+ lines.append(f" {rule}: {count}")
276
+
277
+ return "\n".join(lines)
prism/token_usage.py ADDED
@@ -0,0 +1,93 @@
1
+ """Token accounting for AI provider calls.
2
+
3
+ Providers report usage differently (Gemini ``usage_metadata``, OpenAI
4
+ ``usage``, Anthropic ``usage``). This module normalizes them into a
5
+ process-wide ledger, and estimates tokens when a provider does not report
6
+ them so the CLI can always show a number.
7
+
8
+ Call ``reset()`` at the start of a review, ``record()`` from each provider
9
+ call, and ``summary()``/``format_summary()`` to report.
10
+ """
11
+
12
+ import logging
13
+ import threading
14
+
15
+ logger = logging.getLogger(__name__)
16
+
17
+ _lock = threading.Lock()
18
+ _usage = [] # list of dicts: provider, model, input_tokens, output_tokens, estimated
19
+
20
+ # Average characters per token across common BPE tokenizers. Only used when a
21
+ # provider does not return an exact count.
22
+ _CHARS_PER_TOKEN = 4
23
+
24
+
25
+ def estimate_tokens(text):
26
+ """Cheap token estimate for text (used only as a fallback)."""
27
+ if not text:
28
+ return 0
29
+ return max(1, len(text) // _CHARS_PER_TOKEN)
30
+
31
+
32
+ def record(provider, model, input_tokens, output_tokens, estimated=False):
33
+ """Append one provider call to the ledger (thread-safe)."""
34
+ with _lock:
35
+ _usage.append({
36
+ "provider": provider,
37
+ "model": model,
38
+ "input_tokens": int(input_tokens or 0),
39
+ "output_tokens": int(output_tokens or 0),
40
+ "estimated": bool(estimated),
41
+ })
42
+
43
+
44
+ def reset():
45
+ """Clear the ledger (call once per review)."""
46
+ with _lock:
47
+ _usage.clear()
48
+
49
+
50
+ def snapshot():
51
+ """Return a copy of the raw per-call records."""
52
+ with _lock:
53
+ return list(_usage)
54
+
55
+
56
+ def summary():
57
+ """Aggregate the ledger into a reportable dict."""
58
+ with _lock:
59
+ calls = len(_usage)
60
+ input_tokens = sum(u["input_tokens"] for u in _usage)
61
+ output_tokens = sum(u["output_tokens"] for u in _usage)
62
+ estimated = sum(1 for u in _usage if u["estimated"])
63
+ by_provider = {}
64
+ for u in _usage:
65
+ entry = by_provider.setdefault(u["provider"], {
66
+ "calls": 0, "input_tokens": 0, "output_tokens": 0,
67
+ })
68
+ entry["calls"] += 1
69
+ entry["input_tokens"] += u["input_tokens"]
70
+ entry["output_tokens"] += u["output_tokens"]
71
+ return {
72
+ "calls": calls,
73
+ "input_tokens": input_tokens,
74
+ "output_tokens": output_tokens,
75
+ "total_tokens": input_tokens + output_tokens,
76
+ "estimated_calls": estimated,
77
+ "by_provider": by_provider,
78
+ }
79
+
80
+
81
+ def format_summary():
82
+ """Human-readable one-liner for CLI output."""
83
+ s = summary()
84
+ if not s["calls"]:
85
+ return "Token usage: 0 tokens (no AI calls)"
86
+ return (
87
+ "Token usage: {total:,} total "
88
+ "(in {inp:,} / out {out:,}), {calls} call(s){est}".format(
89
+ total=s["total_tokens"], inp=s["input_tokens"],
90
+ out=s["output_tokens"], calls=s["calls"],
91
+ est=" (estimated)" if s["estimated_calls"] else "",
92
+ )
93
+ )