patchsight 0.2.0__py3-none-any.whl → 0.3.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.
patchsight/db.py CHANGED
@@ -10,11 +10,12 @@ its vulnerability, so the scanner can look up whatever ID OSV returns.
10
10
 
11
11
  Stdlib ``sqlite3`` only, so the scan path can read it without any pipeline dependency.
12
12
 
13
- Compatibility: the ``extraction`` table (second-opinion model and the reason for the tier)
14
- and the ``evidence`` table (each flagged symbol's rationale and cited hunk locations) were
15
- added within schema version 1. Readers that predate them never query them, so they keep
16
- working; this reader treats a database without them as having no such provenance. Evidence
17
- holds commit SHAs, paths and line ranges only, never code (rule 13).
13
+ Compatibility: three tables were added within schema version 1. ``extraction`` holds the
14
+ second-opinion model and the reason for the tier; ``evidence`` holds each flagged symbol's
15
+ rationale and cited hunk locations; ``builds`` is the ledger of every vulnerability
16
+ considered, with its input hash, for incremental updates. Readers that predate them never
17
+ query them, so they keep working; this reader treats a database without them as having no
18
+ such data. Evidence holds commit SHAs, paths and line ranges only, never code (rule 13).
18
19
  """
19
20
 
20
21
  import json
@@ -68,6 +69,11 @@ CREATE TABLE extraction (
68
69
  tier_reason TEXT,
69
70
  PRIMARY KEY (vulnerability, package)
70
71
  );
72
+ CREATE TABLE builds (
73
+ vulnerability TEXT PRIMARY KEY,
74
+ input_hash TEXT NOT NULL,
75
+ status TEXT NOT NULL
76
+ );
71
77
  CREATE TABLE evidence (
72
78
  vulnerability TEXT NOT NULL,
73
79
  package TEXT NOT NULL,
@@ -90,6 +96,17 @@ class FixCommitRef(BaseModel):
90
96
  sha: str
91
97
 
92
98
 
99
+ class BuildEntry(BaseModel):
100
+ """One vulnerability the builder considered, with or without a record: the ledger an
101
+ incremental update compares against (ADR 0001: re-extract only when inputs change)."""
102
+
103
+ model_config = ConfigDict(frozen=True)
104
+
105
+ vulnerability: str
106
+ input_hash: str
107
+ status: str
108
+
109
+
93
110
  class HunkLocation(BaseModel):
94
111
  """Where a cited diff hunk sits: the fix commit, the file and both line ranges."""
95
112
 
@@ -152,7 +169,11 @@ class Record(BaseModel):
152
169
 
153
170
 
154
171
  def write(
155
- path: Path, records: Iterable[Record], aliases: dict[str, str], meta: dict[str, str]
172
+ path: Path,
173
+ records: Iterable[Record],
174
+ aliases: dict[str, str],
175
+ meta: dict[str, str],
176
+ builds: Iterable[BuildEntry] = (),
156
177
  ) -> int:
157
178
  """Write a fresh database file. Returns the number of records written."""
158
179
  if path.exists():
@@ -167,6 +188,10 @@ def write(
167
188
  sorted({**meta, "schema_version": str(SCHEMA_VERSION)}.items()),
168
189
  )
169
190
  connection.executemany("INSERT INTO aliases VALUES (?, ?)", sorted(aliases.items()))
191
+ connection.executemany(
192
+ "INSERT INTO builds VALUES (?, ?, ?)",
193
+ sorted((b.vulnerability, b.input_hash, b.status) for b in builds),
194
+ )
170
195
  for record in records:
171
196
  count += 1
172
197
  connection.execute(
@@ -256,6 +281,7 @@ class SymbolDatabase:
256
281
  }
257
282
  self._has_extraction = "extraction" in tables
258
283
  self._has_evidence = "evidence" in tables
284
+ self._has_builds = "builds" in tables
259
285
 
260
286
  def close(self) -> None:
261
287
  self._connection.close()
@@ -269,6 +295,32 @@ class SymbolDatabase:
269
295
  ).fetchone()
270
296
  return str(row[0]) if row else None
271
297
 
298
+ def confidence_counts(self) -> dict[str, int]:
299
+ """Records by confidence tier."""
300
+ rows = self._connection.execute(
301
+ "SELECT confidence, COUNT(*) FROM records GROUP BY confidence ORDER BY confidence"
302
+ )
303
+ return {str(r[0]): int(r[1]) for r in rows}
304
+
305
+ def vulnerabilities(self) -> list[str]:
306
+ """Every vulnerability that has at least one record."""
307
+ rows = self._connection.execute(
308
+ "SELECT DISTINCT vulnerability FROM records ORDER BY vulnerability"
309
+ )
310
+ return [str(r[0]) for r in rows]
311
+
312
+ def alias_map(self) -> dict[str, str]:
313
+ """Every advisory ID and alias, mapped to its vulnerability."""
314
+ rows = self._connection.execute("SELECT identifier, vulnerability FROM aliases")
315
+ return {str(r[0]): str(r[1]) for r in rows}
316
+
317
+ def build_ledger(self) -> dict[str, BuildEntry]:
318
+ """Every vulnerability the builder considered; empty for an older database."""
319
+ if not self._has_builds:
320
+ return {}
321
+ rows = self._connection.execute("SELECT vulnerability, input_hash, status FROM builds")
322
+ return {r[0]: BuildEntry(vulnerability=r[0], input_hash=r[1], status=r[2]) for r in rows}
323
+
272
324
  def identifiers_for(self, vulnerability: str) -> list[str]:
273
325
  """Every advisory ID and alias that points at this vulnerability."""
274
326
  rows = self._connection.execute(
@@ -0,0 +1,118 @@
1
+ """Failure causes for extraction errors (proposal §10, "failure analysis").
2
+
3
+ Every missed true symbol (a false negative) gets exactly one cause, checked in this order:
4
+
5
+ * ``not_changed``: the fix did not change the symbol, so no patch-based method can find it
6
+ (the ceiling ChangedFuncs also hits: "vulnerable function unchanged, callee changed");
7
+ * ``name_format``: the fix changed a definition that matches the symbol only on a dotted
8
+ boundary (GoVulnDB's ``decryptTicket`` for the method ``Conn.decryptTicket``): a naming
9
+ difference in the ground truth, not a missed function;
10
+ * ``dead_letter``: the symbol was changed, but the extraction failed;
11
+ * ``truncated``: changed, but dropped from the prompt to fit the token budget;
12
+ * ``model_missed``: shown to the model and judged not vulnerable.
13
+
14
+ Every false positive is either ``name_format`` (it matches a true symbol on a dotted
15
+ boundary) or ``model_false_positive``.
16
+
17
+ A report-level miss (no true symbol found: the safety metric) is attributed to its most
18
+ actionable cause: a shown-but-missed symbol first, then truncation, then the rest.
19
+
20
+ Not separated: "the fix adds a new helper". The replay data does not record which side of
21
+ the diff a candidate comes from, so such cases fall under ``model_false_positive``.
22
+ """
23
+
24
+ from collections import Counter
25
+ from collections.abc import Mapping, Set
26
+
27
+ from pydantic import BaseModel, ConfigDict
28
+
29
+ from patchsight.eval.safety import lenient_match
30
+
31
+ MISS_CAUSES = ("not_changed", "name_format", "dead_letter", "truncated", "model_missed")
32
+ REPORT_MISS_ORDER = ("model_missed", "truncated", "dead_letter", "name_format", "not_changed")
33
+ VALID = frozenset({"ok", "repaired"})
34
+
35
+
36
+ class ReportInput(BaseModel):
37
+ model_config = ConfigDict(frozen=True)
38
+
39
+ truth: frozenset[str]
40
+ changed: frozenset[str] # every changed function (ChangedFuncs)
41
+ shown: frozenset[str] # the candidates the prompt kept
42
+ status: str
43
+ predicted: frozenset[str]
44
+
45
+
46
+ class FailureBreakdown(BaseModel):
47
+ model_config = ConfigDict(frozen=True)
48
+
49
+ reports: int
50
+ truth_symbols: int
51
+ false_negatives: dict[str, int]
52
+ false_positives: dict[str, int]
53
+ report_misses: dict[str, int]
54
+ examples: dict[str, tuple[str, ...]] # cause -> report IDs (sorted)
55
+
56
+
57
+ def miss_cause(symbol: str, report: ReportInput) -> str:
58
+ if symbol not in report.changed:
59
+ if any(lenient_match(c, symbol) for c in report.changed):
60
+ return "name_format"
61
+ return "not_changed"
62
+ if report.status not in VALID:
63
+ return "dead_letter"
64
+ if symbol not in report.shown:
65
+ return "truncated"
66
+ return "model_missed"
67
+
68
+
69
+ def breakdown(reports: Mapping[str, ReportInput]) -> FailureBreakdown:
70
+ negatives: Counter[str] = Counter()
71
+ positives: Counter[str] = Counter()
72
+ misses: Counter[str] = Counter()
73
+ examples: dict[str, set[str]] = {}
74
+ total = 0
75
+ for rid, report in sorted(reports.items()):
76
+ total += len(report.truth)
77
+ causes = {miss_cause(s, report) for s in report.truth - report.predicted}
78
+ for symbol in report.truth - report.predicted:
79
+ cause = miss_cause(symbol, report)
80
+ negatives[cause] += 1
81
+ examples.setdefault(cause, set()).add(rid)
82
+ for symbol in report.predicted - report.truth:
83
+ cause = (
84
+ "name_format"
85
+ if any(lenient_match(symbol, t) for t in report.truth)
86
+ else "model_false_positive"
87
+ )
88
+ positives[cause] += 1
89
+ examples.setdefault(f"fp:{cause}", set()).add(rid)
90
+ if report.truth and not report.truth & report.predicted:
91
+ misses[next(c for c in REPORT_MISS_ORDER if c in causes)] += 1
92
+ return FailureBreakdown(
93
+ reports=len(reports),
94
+ truth_symbols=total,
95
+ false_negatives={c: negatives[c] for c in MISS_CAUSES},
96
+ false_positives={c: positives[c] for c in ("name_format", "model_false_positive")},
97
+ report_misses={c: misses[c] for c in REPORT_MISS_ORDER},
98
+ examples={k: tuple(sorted(v)) for k, v in sorted(examples.items())},
99
+ )
100
+
101
+
102
+ def as_inputs(
103
+ truth: Mapping[str, Set[str]],
104
+ changed: Mapping[str, Set[str]],
105
+ shown: Mapping[str, Set[str]],
106
+ status: Mapping[str, str],
107
+ predicted: Mapping[str, Set[str]],
108
+ ) -> dict[str, ReportInput]:
109
+ return {
110
+ r: ReportInput(
111
+ truth=frozenset(truth[r]),
112
+ changed=frozenset(changed.get(r, set())),
113
+ shown=frozenset(shown.get(r, set())),
114
+ status=status.get(r, "dead_letter"),
115
+ predicted=frozenset(predicted.get(r, set())),
116
+ )
117
+ for r in truth
118
+ }
@@ -30,10 +30,16 @@ from patchsight.pipeline.extract.prompt import load_template
30
30
  from patchsight.pipeline.ingest import ghsa_repo, snapshot
31
31
  from patchsight.pipeline.ingest.aliases import AliasGroup, alias_groups
32
32
  from patchsight.pipeline.ingest.osv import Advisory, Excluded, Quarantined, normalise_dump
33
- from patchsight.pipeline.llm.client import QuotaExhaustedError, RateLimitedError, client_for
33
+ from patchsight.pipeline.llm.client import (
34
+ QuotaExhaustedError,
35
+ RateLimitedError,
36
+ cache_only_client,
37
+ client_for,
38
+ )
34
39
  from patchsight.pipeline.llm.config import load_config
35
40
  from patchsight.pipeline.llm.tokens import HfTokenizer
36
41
  from patchsight.pipeline.pypi import PyPIClient
42
+ from patchsight.scan import dbcache
37
43
 
38
44
  app = typer.Typer(name="patchsight-pipeline", no_args_is_help=True, add_completion=False)
39
45
 
@@ -535,7 +541,10 @@ def build_db_command(
535
541
  if llm is not None:
536
542
  meta["records_by_tier"] = json.dumps(dict(Counter(r.confidence for r in records)))
537
543
  target = root / out
538
- db.write(target.with_name(target.name + ".sqlite"), records, aliases, meta)
544
+ db.write(
545
+ target.with_name(target.name + ".sqlite"), records, aliases, meta,
546
+ builds=build_db.ledger(report.outcomes),
547
+ ) # fmt: skip
539
548
  target.with_name(target.name + ".jsonl").write_text(build_db.jsonl(records), "utf-8")
540
549
  target.with_name(target.name + "-build.json").write_text(
541
550
  report.model_dump_json(indent=2) + "\n", "utf-8"
@@ -809,6 +818,95 @@ def parity_report_command(
809
818
  typer.echo("\n".join(lines[9:]))
810
819
 
811
820
 
821
+ @app.command("failure-report")
822
+ def failure_report_command(
823
+ tag: Annotated[str, typer.Argument(help="Run tag of a committed replay bundle.")],
824
+ part: Annotated[str, typer.Option("--split", help="Split part: dev, test or all.")] = "all",
825
+ root: Root = Path(),
826
+ ) -> None:
827
+ """Tag every extraction error with a cause, from committed files (no network)."""
828
+ from patchsight.eval import failures
829
+
830
+ data = bundle.load(root / DUNLAP_BUNDLE)
831
+ frozen = splits.load_split(root / DUNLAP_SPLIT)
832
+ ids = frozen.split.ids(part)
833
+ run = replay.load(root / DUNLAP_BUNDLE.parent / f"extraction-{tag}.json")
834
+ answered = {r.id: r for r in run.reports if r.id in ids}
835
+ truth = {r.id: set(r.symbols) for r in data.reports if r.id in ids}
836
+ changed = {r.id: r.changed_functions() for r in data.reports if r.id in ids}
837
+ shown = {rid: {c.name for c in r.candidates} for rid, r in answered.items()}
838
+ status: dict[str, str] = {}
839
+ predicted: dict[str, set[str]] = {}
840
+ for rid, report in answered.items():
841
+ status[rid], predicted[rid] = replay.replay_report(report, run.prompt_version)
842
+ result = failures.breakdown(failures.as_inputs(truth, changed, shown, status, predicted))
843
+ fn_total = sum(result.false_negatives.values())
844
+ fp_total = sum(result.false_positives.values())
845
+ miss_total = sum(result.report_misses.values())
846
+ labels = {
847
+ "dead_letter": "Extraction failed (dead letter)",
848
+ "not_changed": "Not changed by the fix (patch ceiling)",
849
+ "name_format": "Name format only (dotted-boundary match)",
850
+ "truncated": "Dropped to fit the token budget",
851
+ "model_missed": "Shown to the model, judged not vulnerable",
852
+ "model_false_positive": "Judged vulnerable, not in the ground truth",
853
+ }
854
+
855
+ def share(n: int, total: int) -> str:
856
+ return f"{n} ({n / total:.0%})" if total else "0"
857
+
858
+ lines = [
859
+ f"# Failure causes on the Dunlap `{part}` split: `{tag}`",
860
+ "",
861
+ "Generated by `python -m patchsight.pipeline failure-report`; do not edit by hand. "
862
+ "Computed offline from the committed candidate and replay bundles.",
863
+ "",
864
+ f"- Model: `{run.model}`, prompt `{run.prompt_version}`",
865
+ f"- Split `{frozen.split.name}:{part}` (SHA-256 `{frozen.sha256}`): {result.reports} "
866
+ f"reports, {result.truth_symbols} true symbols",
867
+ "",
868
+ "Causes are assigned in a fixed order; see `src/patchsight/eval/failures.py`. "
869
+ '"The fix adds a new helper" cannot be separated from this data and falls under '
870
+ "false positives.",
871
+ "",
872
+ f"## Missed true symbols ({fn_total})",
873
+ "",
874
+ "| Cause | Symbols |",
875
+ "|---|---|",
876
+ *(f"| {labels[c]} | {share(n, fn_total)} |" for c, n in result.false_negatives.items()),
877
+ "",
878
+ f"## Reports with no true symbol found ({miss_total}): the safety metric",
879
+ "",
880
+ "Each is attributed to its most actionable cause.",
881
+ "",
882
+ "| Cause | Reports |",
883
+ "|---|---|",
884
+ *(f"| {labels[c]} | {share(n, miss_total)} |" for c, n in result.report_misses.items()),
885
+ "",
886
+ f"## False positives ({fp_total})",
887
+ "",
888
+ "| Cause | Symbols |",
889
+ "|---|---|",
890
+ *(f"| {labels[c]} | {share(n, fp_total)} |" for c, n in result.false_positives.items()),
891
+ "",
892
+ "## Reports by cause",
893
+ "",
894
+ *(
895
+ f"- {labels.get(k.removeprefix('fp:'), k)}"
896
+ f"{' (false positive)' if k.startswith('fp:') else ''}: "
897
+ + ", ".join(f"`{r}`" for r in v)
898
+ for k, v in result.examples.items()
899
+ ),
900
+ "",
901
+ ]
902
+ target = root / "docs" / "reports" / f"failures-dunlap-{part}-{tag}"
903
+ target.with_name(target.name + ".md").write_text("\n".join(lines), "utf-8")
904
+ target.with_name(target.name + ".json").write_text(
905
+ result.model_dump_json(indent=2) + "\n", "utf-8"
906
+ )
907
+ typer.echo("\n".join(lines[10:36]))
908
+
909
+
812
910
  @app.command("reproduce")
813
911
  def reproduce_command(root: Root = Path()) -> None:
814
912
  """Recompute the benchmark tables offline from committed files. No network, no API key."""
@@ -866,6 +964,195 @@ def reproduce_command(root: Root = Path()) -> None:
866
964
  typer.echo(f"\nMatches docs/reports/extraction-dunlap-*-{tag}.json exactly.")
867
965
 
868
966
 
967
+ @app.command("update-db")
968
+ def update_db_command(
969
+ previous: Annotated[Path, typer.Argument(help="The previous database (SQLite).")],
970
+ root: Root = Path(),
971
+ cache: Annotated[Path, typer.Option(help="HTTP response cache.")] = Path(".cache/http"),
972
+ out: Annotated[Path, typer.Option(help="Output path, without extension.")] = Path(
973
+ "data/build/patchsight-update"
974
+ ),
975
+ llm: Annotated[
976
+ Path | None, typer.Option(help="Extractor outcomes for the rebuilt vulnerabilities.")
977
+ ] = None,
978
+ second: Annotated[Path | None, typer.Option(help="Second-opinion outcomes for them.")] = None,
979
+ ) -> None:
980
+ """Update a database from the pinned snapshot, rebuilding only changed vulnerabilities
981
+ (needs GITHUB_TOKEN)."""
982
+ from patchsight.pipeline import llm_records, update_db
983
+
984
+ token = _github_token()
985
+ manifest, dump = _load_verified(root)
986
+ by_id, groups = _github_fix_groups(dump, None, None, 0)
987
+ dump_entry = manifest.file(DUMP)
988
+ version = dump_entry.retrieved_at.strftime("%Y.%m.%d")
989
+ prior = db.SymbolDatabase(root / previous)
990
+ prior_meta = dict(prior.meta)
991
+ github = GitHubClient(root / cache / "github", token=token, wait_for_rate_limit=3900)
992
+ pypi = PyPIClient(root / cache / "pypi")
993
+ try:
994
+ records, aliases, builds, report = update_db.update(
995
+ prior, groups, by_id, github, pypi, version,
996
+ progress=lambda done, total: typer.echo(f"rebuilt {done}/{total}", err=True),
997
+ ) # fmt: skip
998
+ except update_db.NoLedgerError as error:
999
+ raise typer.BadParameter(str(error)) from None
1000
+ finally:
1001
+ prior.close()
1002
+ github.close()
1003
+ pypi.close()
1004
+ merged: dict[str, int] = {}
1005
+ if llm is not None:
1006
+ fresh = set(report.to_extract)
1007
+ primaries = llm_records.load(root / llm)
1008
+ secondaries = llm_records.load(root / second) if second is not None else {}
1009
+ upgraded, merged = llm_records.apply(
1010
+ [r for r in records if r.vulnerability in fresh], primaries, secondaries
1011
+ )
1012
+ records = [r for r in records if r.vulnerability not in fresh] + upgraded
1013
+ commit = subprocess.run( # noqa: S603 - fixed argv, no shell
1014
+ ["git", "-C", str(root), "rev-parse", "HEAD"], # noqa: S607
1015
+ capture_output=True, text=True, check=False,
1016
+ ).stdout.strip() # fmt: skip
1017
+ meta = {
1018
+ "db_version": version,
1019
+ "built_at": datetime.now(UTC).isoformat(),
1020
+ "builder": prior_meta.get("builder", "fallback-v1") if llm is None else "llm-v1",
1021
+ "snapshot_sha256": dump_entry.sha256,
1022
+ "code_commit": commit,
1023
+ "updated_from": prior_meta.get("db_version", "?"),
1024
+ }
1025
+ target = root / out
1026
+ db.write(target.with_name(target.name + ".sqlite"), records, aliases, meta, builds=builds)
1027
+ target.with_name(target.name + "-update.json").write_text(
1028
+ report.model_dump_json(indent=2) + "\n", "utf-8"
1029
+ )
1030
+ typer.echo(
1031
+ f"db {version} from {report.previous_version}: carried {report.carried}, "
1032
+ f"rebuilt {report.rebuilt}, new {report.new}, removed {report.removed}; "
1033
+ f"{len(records)} records; to extract {len(report.to_extract)}; {report.status}"
1034
+ )
1035
+ if merged:
1036
+ typer.echo(f"LLM merge: {merged}")
1037
+
1038
+
1039
+ @app.command("gate-db")
1040
+ def gate_db_command(
1041
+ candidate: Annotated[Path, typer.Argument(help="The candidate database.")],
1042
+ previous: Annotated[Path, typer.Option(help="The previous release's database.")],
1043
+ root: Root = Path(),
1044
+ out: Annotated[Path, typer.Option(help="Report path, without extension.")] = Path(
1045
+ "data/build/gate"
1046
+ ),
1047
+ ) -> None:
1048
+ """Run the release gate on a candidate database; exit 1 if any check fails."""
1049
+ from patchsight.pipeline import gate
1050
+
1051
+ new, old = db.SymbolDatabase(root / candidate), db.SymbolDatabase(root / previous)
1052
+ try:
1053
+ report = gate.run(new, old)
1054
+ finally:
1055
+ new.close()
1056
+ old.close()
1057
+ target = root / out
1058
+ target.parent.mkdir(parents=True, exist_ok=True)
1059
+ markdown = gate.render_markdown(report)
1060
+ target.with_name(target.name + ".md").write_text(markdown, "utf-8")
1061
+ target.with_name(target.name + ".json").write_text(
1062
+ report.model_dump_json(indent=2) + "\n", "utf-8"
1063
+ )
1064
+ typer.echo(markdown)
1065
+ if not report.passed:
1066
+ raise typer.Exit(code=1)
1067
+
1068
+
1069
+ ATTRIBUTION = """## Attribution and licence
1070
+
1071
+ Advisory identifiers and affected-package data come from [OSV.dev](https://osv.dev), which \
1072
+ aggregates the [GitHub Advisory Database](https://github.com/github/advisory-database) and the \
1073
+ [PyPA Advisory Database](https://github.com/pypa/advisory-database). All three are licensed \
1074
+ CC BY 4.0.
1075
+
1076
+ **Changes made:** PatchSight resolved each advisory's fix commit on GitHub, mapped the changed \
1077
+ lines to function names with tree-sitter, and, where shown, had language models choose the \
1078
+ vulnerable ones. It stores those names with file paths, line ranges and commit SHAs. No \
1079
+ third-party source code is included.
1080
+ """
1081
+
1082
+
1083
+ @app.command("release-notes")
1084
+ def release_notes_command(
1085
+ database: Annotated[Path, typer.Argument(help="The database being released.")],
1086
+ pointer: Annotated[Path, typer.Option(help="Its pointer (package-db output).")] = Path(
1087
+ "releases/latest.json"
1088
+ ),
1089
+ update: Annotated[Path | None, typer.Option(help="The update-db report, if any.")] = None,
1090
+ gate: Annotated[Path | None, typer.Option(help="The gate-db report, if any.")] = None,
1091
+ root: Root = Path(),
1092
+ out: Annotated[Path, typer.Option(help="Notes file to write.")] = Path(
1093
+ "data/build/release-notes.md"
1094
+ ),
1095
+ ) -> None:
1096
+ """Write release notes for a database release, with provenance and attribution."""
1097
+ from patchsight.pipeline.gate import GateReport
1098
+ from patchsight.pipeline.update_db import UpdateReport
1099
+
1100
+ opened = db.SymbolDatabase(root / database)
1101
+ try:
1102
+ meta, tiers, total = dict(opened.meta), opened.confidence_counts(), opened.record_count()
1103
+ vulnerabilities = len(opened.vulnerabilities())
1104
+ finally:
1105
+ opened.close()
1106
+ published = dbcache.Pointer.model_validate_json((root / pointer).read_text("utf-8"))
1107
+ version = meta.get("db_version", "?")
1108
+ origin = f", updated from {meta['updated_from']}" if "updated_from" in meta else ""
1109
+ lines = [
1110
+ f"Symbol database **{version}**{origin}.",
1111
+ "",
1112
+ "```bash",
1113
+ "patchsight db update # downloads this release and verifies its SHA-256",
1114
+ "```",
1115
+ "",
1116
+ "## Contents",
1117
+ "",
1118
+ f"- **{vulnerabilities:,} PyPI vulnerabilities**, {total:,} records: "
1119
+ + ", ".join(f"{n:,} {tier} confidence" for tier, n in sorted(tiers.items())),
1120
+ "- Low-confidence records list every definition the fix changed; they can mark an "
1121
+ "alert CALLED, never IMPORTED, NOT CALLED.",
1122
+ ]
1123
+ if update is not None:
1124
+ report = UpdateReport.model_validate_json((root / update).read_text("utf-8"))
1125
+ lines += [
1126
+ f"- **Changes since {report.previous_version}:** {report.carried:,} carried "
1127
+ f"unchanged, {report.rebuilt} rebuilt, {report.new} new, {report.removed} removed"
1128
+ + (f"; {report.aliases_added} aliases added" if report.aliases_added else "")
1129
+ + (f", {report.aliases_removed} removed" if report.aliases_removed else ""),
1130
+ ]
1131
+ if gate is not None:
1132
+ result = GateReport.model_validate_json((root / gate).read_text("utf-8"))
1133
+ lines += [
1134
+ "",
1135
+ f"## Release gate: {'passed' if result.passed else 'FAILED'}",
1136
+ "",
1137
+ *(f"- `{c.name}`: {c.detail}" for c in result.checks),
1138
+ ]
1139
+ lines += [
1140
+ "",
1141
+ "## Provenance",
1142
+ "",
1143
+ f"- OSV PyPI dump SHA-256: `{meta.get('snapshot_sha256', '?')}`",
1144
+ f"- Built by PatchSight commit `{meta.get('code_commit', '?')}` "
1145
+ f"(builder `{meta.get('builder', '?')}`, schema version {meta.get('schema_version', '?')})",
1146
+ f"- Asset SHA-256: `{published.sha256}`",
1147
+ "",
1148
+ ATTRIBUTION,
1149
+ ]
1150
+ target = root / out
1151
+ target.parent.mkdir(parents=True, exist_ok=True)
1152
+ target.write_text("\n".join(lines), "utf-8")
1153
+ typer.echo(f"wrote {target}")
1154
+
1155
+
869
1156
  @app.command("pypi-extract")
870
1157
  def pypi_extract_command(
871
1158
  root: Root = Path(),
@@ -899,6 +1186,12 @@ def pypi_extract_command(
899
1186
  "--priority", help="Most-downloaded packages first (needs fetch-top-packages)."
900
1187
  ),
901
1188
  ] = False,
1189
+ cache_only: Annotated[
1190
+ bool,
1191
+ typer.Option(
1192
+ "--cache-only", help="Answer only from the response cache; never call a model."
1193
+ ),
1194
+ ] = False,
902
1195
  ) -> None:
903
1196
  """Run LLM extraction on PyPI vulnerabilities (needs the model's key, and GITHUB_TOKEN
904
1197
  unless --offline)."""
@@ -954,7 +1247,8 @@ def pypi_extract_command(
954
1247
  f"{sum(p.truncated for p in sized)}"
955
1248
  )
956
1249
  return
957
- llm, model_id = client_for(llm_config, role, root / cache / "llm", counter)
1250
+ make_client = cache_only_client if cache_only else client_for
1251
+ llm, model_id = make_client(llm_config, role, root / cache / "llm", counter)
958
1252
  try:
959
1253
  results, summary = pypi_extract.run(
960
1254
  groups, by_id, github, pypi, llm, llm_config, role, template, counter,
@@ -20,7 +20,7 @@ from datetime import UTC, datetime
20
20
 
21
21
  from pydantic import BaseModel
22
22
 
23
- from patchsight.db import FixCommitRef, Record, Symbol
23
+ from patchsight.db import BuildEntry, FixCommitRef, Record, Symbol
24
24
  from patchsight.names import module_for_path
25
25
  from patchsight.pipeline.diffs.commits import CommitMapping, map_commit
26
26
  from patchsight.pipeline.diffs.github import GitHubClient
@@ -39,6 +39,7 @@ MAX_SYMBOLS = 500
39
39
  class BuildOutcome(BaseModel):
40
40
  vulnerability: str
41
41
  status: str
42
+ input_hash: str = ""
42
43
  records: int = 0
43
44
  symbols: int = 0
44
45
  commits: int = 0
@@ -178,9 +179,12 @@ def fallback_records(
178
179
  pypi: PyPIClient,
179
180
  now: datetime,
180
181
  ) -> tuple[list[Record], BuildOutcome]:
182
+ digest = input_hash(group, by_id)
181
183
  fixes = fix_mappings(group, by_id, github, pypi)
182
184
  if fixes.status != "mapped":
183
- return [], BuildOutcome(vulnerability=group.key, status=fixes.status, commits=fixes.commits)
185
+ return [], BuildOutcome(
186
+ vulnerability=group.key, status=fixes.status, commits=fixes.commits, input_hash=digest
187
+ )
184
188
  symbols = changed_symbols(fixes.mappings)
185
189
  used = [FixCommitRef(repo=m.repo, sha=m.sha) for m in fixes.mappings]
186
190
  packages = fixes.packages
@@ -189,11 +193,11 @@ def fallback_records(
189
193
  # says nothing about where the bug is. Publishing it would make almost any use of
190
194
  # the package CALLED; without a record the scanner says UNKNOWN, which is honest.
191
195
  return [], BuildOutcome(
192
- vulnerability=group.key, status="too_broad", symbols=len(symbols), commits=len(used)
193
- )
196
+ vulnerability=group.key, status="too_broad", symbols=len(symbols),
197
+ commits=len(used), input_hash=digest,
198
+ ) # fmt: skip
194
199
  roots = tuple(sorted({s.module.split(".")[0] for s in symbols.values() if s.module}))
195
200
  modified = max(by_id[i].modified for i in group.advisory_ids)
196
- digest = input_hash(group, by_id)
197
201
  records = [
198
202
  Record(
199
203
  vulnerability=group.key,
@@ -219,6 +223,7 @@ def fallback_records(
219
223
  records=len(records),
220
224
  symbols=len(symbols),
221
225
  commits=len(used),
226
+ input_hash=digest,
222
227
  )
223
228
 
224
229
 
@@ -258,3 +263,11 @@ def build(
258
263
 
259
264
  def jsonl(records: Iterable[Record]) -> str:
260
265
  return "".join(r.model_dump_json() + "\n" for r in records)
266
+
267
+
268
+ def ledger(outcomes: Iterable[BuildOutcome]) -> list[BuildEntry]:
269
+ """The builds ledger: every vulnerability considered, with its input hash and status."""
270
+ return [
271
+ BuildEntry(vulnerability=o.vulnerability, input_hash=o.input_hash, status=o.status)
272
+ for o in outcomes
273
+ ]
@@ -120,26 +120,37 @@ def terms(text: str) -> list[str]:
120
120
  return found
121
121
 
122
122
 
123
+ # Scores are compared at this many decimal places, far below any meaningful difference.
124
+ SCORE_DECIMALS = 9
125
+
126
+
123
127
  def bm25_rank(query: str, documents: Sequence[str], k1: float = 1.5, b: float = 0.75) -> list[int]:
124
- """Document indices, best match first. Ties keep the original order."""
128
+ """Document indices, best match first. Ties keep the original order.
129
+
130
+ The ranking must not depend on the process or the platform (rule 12): it decides which
131
+ candidates a truncated prompt keeps, and so the prompt's cache key. Query terms are
132
+ visited in sorted order, each score is summed exactly (``math.fsum``), and scores are
133
+ compared after rounding, so a last-bit difference between platforms' ``math.log`` cannot
134
+ reorder a tie either.
135
+ """
125
136
  tokenised = [terms(doc) for doc in documents]
126
137
  count = len(tokenised)
127
138
  if not count:
128
139
  return []
129
140
  average = sum(len(t) for t in tokenised) / count or 1.0
130
141
  frequency = Counter(term for t in tokenised for term in set(t))
131
- query_terms = set(terms(query))
142
+ query_terms = sorted(set(terms(query)))
132
143
  scores = []
133
144
  for index, tokens in enumerate(tokenised):
134
145
  counts = Counter(tokens)
135
- score = 0.0
146
+ parts = []
136
147
  for term in query_terms:
137
148
  tf = counts.get(term, 0)
138
149
  if not tf:
139
150
  continue
140
151
  idf = math.log(1 + (count - frequency[term] + 0.5) / (frequency[term] + 0.5))
141
- score += idf * tf * (k1 + 1) / (tf + k1 * (1 - b + b * len(tokens) / average))
142
- scores.append((-score, index))
152
+ parts.append(idf * tf * (k1 + 1) / (tf + k1 * (1 - b + b * len(tokens) / average)))
153
+ scores.append((-round(math.fsum(parts), SCORE_DECIMALS), index))
143
154
  return [index for _, index in sorted(scores)]
144
155
 
145
156
 
@@ -0,0 +1,153 @@
1
+ """The release gate: checks a candidate database must pass before it is published.
2
+
3
+ Every check is deterministic and reads only the candidate and the previous release, so the
4
+ gate gives the same answer from the same inputs. A failure stops publishing; the nightly
5
+ workflow then opens an issue with this report instead.
6
+
7
+ * ``ledger``: the builds ledger exists and covers every vulnerability with a record, so the
8
+ next incremental update can run.
9
+ * ``symbols``: every record names at least one symbol and no more than ``MAX_SYMBOLS``.
10
+ * ``aliases``: every vulnerability with a record is found by its own ID, and every alias
11
+ points at a vulnerability with a record.
12
+ * ``no_mass_loss``: few vulnerabilities lose their records at once (at most
13
+ ``MAX_LOST_SHARE`` of the previous ones, or ``MIN_LOST_ALLOWED``, whichever is larger).
14
+ A bigger drop means a broken snapshot or builder, not real withdrawals.
15
+ * ``high_kept``: a high-confidence record whose extraction inputs did not change stays high.
16
+ """
17
+
18
+ from pydantic import BaseModel, ConfigDict
19
+
20
+ from patchsight.db import SymbolDatabase
21
+ from patchsight.pipeline.build_db import MAX_SYMBOLS
22
+
23
+ MAX_LOST_SHARE = 0.02
24
+ MIN_LOST_ALLOWED = 10
25
+ EXAMPLES = 10
26
+
27
+
28
+ class Check(BaseModel):
29
+ model_config = ConfigDict(frozen=True)
30
+
31
+ name: str
32
+ passed: bool
33
+ detail: str
34
+
35
+
36
+ class GateReport(BaseModel):
37
+ model_config = ConfigDict(frozen=True)
38
+
39
+ candidate_version: str
40
+ previous_version: str
41
+ passed: bool
42
+ checks: tuple[Check, ...]
43
+
44
+
45
+ def _sample(items: list[str]) -> str:
46
+ shown = ", ".join(items[:EXAMPLES])
47
+ return shown + (f" and {len(items) - EXAMPLES} more" if len(items) > EXAMPLES else "")
48
+
49
+
50
+ def run(candidate: SymbolDatabase, previous: SymbolDatabase) -> GateReport:
51
+ checks: list[Check] = []
52
+ ledger = candidate.build_ledger()
53
+ vulnerabilities = candidate.vulnerabilities()
54
+ records = {v: candidate.records_for(v) for v in vulnerabilities}
55
+
56
+ unledgered = [v for v in vulnerabilities if v not in ledger]
57
+ checks.append(
58
+ Check(
59
+ name="ledger",
60
+ passed=bool(ledger) and not unledgered,
61
+ detail=f"{len(ledger)} entries"
62
+ + (f"; records without an entry: {_sample(unledgered)}" if unledgered else "")
63
+ + ("" if ledger else "; no ledger"),
64
+ )
65
+ )
66
+
67
+ bad = [
68
+ f"{r.vulnerability}/{r.package} ({len(r.symbols)})"
69
+ for rs in records.values()
70
+ for r in rs
71
+ if not 1 <= len(r.symbols) <= MAX_SYMBOLS
72
+ ]
73
+ checks.append(
74
+ Check(
75
+ name="symbols",
76
+ passed=not bad,
77
+ detail=f"{sum(len(rs) for rs in records.values())} records"
78
+ + (f"; outside 1 to {MAX_SYMBOLS} symbols: {_sample(bad)}" if bad else ""),
79
+ )
80
+ )
81
+
82
+ aliases = candidate.alias_map()
83
+ unreachable = [v for v in vulnerabilities if aliases.get(v) != v]
84
+ dangling = sorted(i for i, v in aliases.items() if v not in records)
85
+ checks.append(
86
+ Check(
87
+ name="aliases",
88
+ passed=not unreachable and not dangling,
89
+ detail=f"{len(aliases)} identifiers"
90
+ + (
91
+ f"; vulnerabilities not found by their ID: {_sample(unreachable)}"
92
+ if unreachable
93
+ else ""
94
+ )
95
+ + (f"; aliases without a record: {_sample(dangling)}" if dangling else ""),
96
+ )
97
+ )
98
+
99
+ before = previous.vulnerabilities()
100
+ lost = [v for v in before if v not in records]
101
+ allowed = max(MIN_LOST_ALLOWED, int(MAX_LOST_SHARE * len(before)))
102
+ checks.append(
103
+ Check(
104
+ name="no_mass_loss",
105
+ passed=len(lost) <= allowed,
106
+ detail=f"{len(lost)} of {len(before)} vulnerabilities lost their records "
107
+ f"(at most {allowed} allowed)" + (f": {_sample(lost)}" if lost else ""),
108
+ )
109
+ )
110
+
111
+ old_ledger = previous.build_ledger()
112
+ demoted = [
113
+ f"{r.vulnerability}/{r.package}"
114
+ for v in before
115
+ if v in records and v in old_ledger and v in ledger
116
+ and old_ledger[v].input_hash == ledger[v].input_hash
117
+ for r in previous.records_for(v)
118
+ if r.confidence == "high"
119
+ and not any(c.package == r.package and c.confidence == "high" for c in records[v])
120
+ ] # fmt: skip
121
+ checks.append(
122
+ Check(
123
+ name="high_kept",
124
+ passed=not demoted,
125
+ detail="unchanged high-confidence records stay high"
126
+ + (f"; demoted: {_sample(demoted)}" if demoted else ""),
127
+ )
128
+ )
129
+ return GateReport(
130
+ candidate_version=candidate.meta.get("db_version", "?"),
131
+ previous_version=previous.meta.get("db_version", "?"),
132
+ passed=all(c.passed for c in checks),
133
+ checks=tuple(checks),
134
+ )
135
+
136
+
137
+ def render_markdown(report: GateReport) -> str:
138
+ verdict = "PASSED" if report.passed else "FAILED"
139
+ lines = [
140
+ f"# Release gate {verdict}: database {report.candidate_version}",
141
+ "",
142
+ f"Candidate `{report.candidate_version}` against the previous release "
143
+ f"`{report.previous_version}`. Checks are described in `src/patchsight/pipeline/gate.py`.",
144
+ "",
145
+ "| Check | Result | Detail |",
146
+ "|---|---|---|",
147
+ *(
148
+ f"| `{c.name}` | {'pass' if c.passed else '**FAIL**'} | {c.detail} |"
149
+ for c in report.checks
150
+ ),
151
+ "",
152
+ ]
153
+ return "\n".join(lines)
@@ -268,6 +268,24 @@ class LLMClient:
268
268
  return LLMResponse(**record, cached=False, seconds=seconds)
269
269
 
270
270
 
271
+ class ResponseNotCachedError(RuntimeError):
272
+ """Cache-only mode: the response is not in the cache, and no model may be called."""
273
+
274
+
275
+ def cache_only_client(
276
+ config: LLMConfig, role: str, cache_dir: Path, counter: TokenCounter
277
+ ) -> tuple[LLMClient, str]:
278
+ """A client that answers only from the cache, for replaying a run made elsewhere (such as
279
+ on Kaggle) with no model server and no key. A miss raises ResponseNotCachedError."""
280
+
281
+ def refuse(request: LLMRequest) -> tuple[str, int, int]:
282
+ raise ResponseNotCachedError(f"no cached response for this {request.model} prompt")
283
+
284
+ return LLMClient(refuse, RateLimiter(10**9, 10**9), cache_dir, counter), config.models[
285
+ role
286
+ ].model
287
+
288
+
271
289
  def client_for(
272
290
  config: LLMConfig, role: str, cache_dir: Path, counter: TokenCounter
273
291
  ) -> tuple[LLMClient, str]:
@@ -31,7 +31,7 @@ from patchsight.pipeline.extract.prompt import AdvisoryText, PromptTemplate, ren
31
31
  from patchsight.pipeline.http import CacheMissError
32
32
  from patchsight.pipeline.ingest.aliases import AliasGroup
33
33
  from patchsight.pipeline.ingest.osv import Advisory
34
- from patchsight.pipeline.llm.client import LLMClient
34
+ from patchsight.pipeline.llm.client import LLMClient, ResponseNotCachedError
35
35
  from patchsight.pipeline.llm.config import LLMConfig
36
36
  from patchsight.pipeline.llm.tokens import TokenCounter
37
37
  from patchsight.pipeline.pypi import PyPIClient
@@ -233,11 +233,14 @@ def extract_vulnerability(
233
233
  if len(build_db.changed_symbols(fixes.mappings)) > build_db.MAX_SYMBOLS:
234
234
  return "too_broad"
235
235
  inputs, known = candidate_inputs(fixes.mappings, PYTHON_KINDS)
236
- outcome = extract(
237
- llm, config.models[role], template, advisory_text(group, by_id), inputs, known,
238
- config.prompt_budget(role), counter, config.budget.max_hunk_lines,
239
- config.candidate_limit(role),
240
- ) # fmt: skip
236
+ try:
237
+ outcome = extract(
238
+ llm, config.models[role], template, advisory_text(group, by_id), inputs, known,
239
+ config.prompt_budget(role), counter, config.budget.max_hunk_lines,
240
+ config.candidate_limit(role),
241
+ ) # fmt: skip
242
+ except ResponseNotCachedError:
243
+ return "not_cached" # cache-only replay of a run made elsewhere: never a model call
241
244
  kinds = {(i.path, i.name): i.kind for i in inputs}
242
245
  return PyPIExtraction(
243
246
  entry_points=qualify_entry_points(outcome.entry_points, fixes.mappings),
@@ -0,0 +1,124 @@
1
+ """Incremental database update: rebuild only what changed (the core of the nightly run).
2
+
3
+ The previous database's ``builds`` ledger records every vulnerability its builder
4
+ considered, with the hash of the inputs extraction reads (ADR 0001). Against a new snapshot:
5
+
6
+ * **carried:** the hash is unchanged, so the vulnerability keeps its records exactly as they
7
+ were, LLM tiers and evidence included, and its ledger entry;
8
+ * **rebuilt** (hash changed) or **new** (not in the ledger): built again as fallback records,
9
+ and listed for extraction if they have a record;
10
+ * **removed:** in the ledger but no longer in the snapshot (withdrawn, or merged into another
11
+ alias group), so it is dropped.
12
+
13
+ Aliases are always recomputed from the new snapshot, so a carried vulnerability picks up any
14
+ new alias. A database without a ledger cannot be updated; rebuild it with ``build-db``.
15
+
16
+ ``changed`` says whether anything users can see differs: records or aliases.
17
+ """
18
+
19
+ from collections import Counter
20
+ from collections.abc import Callable, Sequence
21
+ from datetime import UTC, datetime
22
+
23
+ from pydantic import BaseModel, ConfigDict
24
+
25
+ from patchsight.db import BuildEntry, Record, SymbolDatabase
26
+ from patchsight.pipeline.build_db import fallback_records, input_hash
27
+ from patchsight.pipeline.diffs.github import GitHubClient
28
+ from patchsight.pipeline.ingest.aliases import AliasGroup
29
+ from patchsight.pipeline.ingest.osv import Advisory
30
+ from patchsight.pipeline.pypi import PyPIClient
31
+
32
+
33
+ class UpdateReport(BaseModel):
34
+ model_config = ConfigDict(frozen=True)
35
+
36
+ previous_version: str
37
+ db_version: str
38
+ carried: int
39
+ rebuilt: int
40
+ new: int
41
+ removed: int
42
+ aliases_added: int
43
+ aliases_removed: int
44
+ status: dict[str, int] # build statuses of the rebuilt and new vulnerabilities
45
+ to_extract: tuple[str, ...] # rebuilt or new vulnerabilities that have a record
46
+
47
+
48
+ def changed(report: "UpdateReport") -> bool:
49
+ """Whether the update differs from the previous database in records or aliases."""
50
+ return bool(
51
+ report.rebuilt or report.new or report.removed
52
+ or report.aliases_added or report.aliases_removed
53
+ ) # fmt: skip
54
+
55
+
56
+ class NoLedgerError(RuntimeError):
57
+ """The previous database has no builds ledger, so changes cannot be detected."""
58
+
59
+
60
+ def update(
61
+ previous: SymbolDatabase,
62
+ groups: Sequence[AliasGroup],
63
+ by_id: dict[str, Advisory],
64
+ github: GitHubClient,
65
+ pypi: PyPIClient,
66
+ db_version: str,
67
+ now: datetime | None = None,
68
+ progress: Callable[[int, int], None] | None = None,
69
+ ) -> tuple[list[Record], dict[str, str], list[BuildEntry], UpdateReport]:
70
+ ledger = previous.build_ledger()
71
+ if not ledger:
72
+ raise NoLedgerError("the previous database has no builds ledger; run build-db instead")
73
+ now = now or datetime.now(UTC)
74
+ records: list[Record] = []
75
+ aliases: dict[str, str] = {}
76
+ builds: list[BuildEntry] = []
77
+ statuses: Counter[str] = Counter()
78
+ counts: Counter[str] = Counter()
79
+ to_extract: list[str] = []
80
+ ordered = sorted(groups, key=lambda g: g.key)
81
+ changed = {
82
+ g.key
83
+ for g in ordered
84
+ if (entry := ledger.get(g.key)) is None or entry.input_hash != input_hash(g, by_id)
85
+ }
86
+ done = 0
87
+ for group in ordered:
88
+ entry = ledger.get(group.key)
89
+ if entry is not None and group.key not in changed:
90
+ kept = previous.records_for(group.key)
91
+ builds.append(entry)
92
+ counts["carried"] += 1
93
+ else:
94
+ kept, outcome = fallback_records(group, by_id, github, pypi, now)
95
+ builds.append(
96
+ BuildEntry(
97
+ vulnerability=group.key, input_hash=outcome.input_hash, status=outcome.status
98
+ )
99
+ )
100
+ counts["new" if entry is None else "rebuilt"] += 1
101
+ statuses[outcome.status] += 1
102
+ if kept:
103
+ to_extract.append(group.key)
104
+ done += 1
105
+ if progress is not None:
106
+ progress(done, len(changed))
107
+ if kept:
108
+ records.extend(kept)
109
+ aliases.update(dict.fromkeys(group.identifiers, group.key))
110
+ current = {g.key for g in ordered}
111
+ before = previous.alias_map()
112
+ report = UpdateReport(
113
+ previous_version=previous.meta.get("db_version", "?"),
114
+ db_version=db_version,
115
+ carried=counts["carried"],
116
+ rebuilt=counts["rebuilt"],
117
+ new=counts["new"],
118
+ removed=sum(1 for key in ledger if key not in current),
119
+ aliases_added=sum(1 for i, v in aliases.items() if before.get(i) != v),
120
+ aliases_removed=sum(1 for i in before if i not in aliases),
121
+ status=dict(sorted(statuses.items())),
122
+ to_extract=tuple(to_extract),
123
+ )
124
+ return records, aliases, builds, report
@@ -1,8 +1,9 @@
1
1
  """Fetch and cache the published symbol database.
2
2
 
3
- Releases are immutable files attached to GitHub releases. A small pointer,
4
- ``releases/latest.json`` in the repository, names the current one with its SHA-256, so
5
- rolling back is one commit that moves the pointer back.
3
+ Releases are immutable files attached to GitHub releases. A small pointer, ``latest.json``,
4
+ names the current one with its SHA-256, so rolling back is one commit that moves the pointer
5
+ back (ADR 0006). The nightly pipeline keeps it on the ``db-pointer`` branch; the copy at
6
+ ``releases/latest.json`` on ``main`` is the fallback, and what CLIs before 0.3.0 read.
6
7
 
7
8
  ``update`` downloads over HTTPS only, verifies the SHA-256, checks the schema version by
8
9
  opening the file, and only then replaces the cached copy, so a failed or tampered download
@@ -13,6 +14,7 @@ import gzip
13
14
  import hashlib
14
15
  import os
15
16
  import shutil
17
+ from collections.abc import Sequence
16
18
  from datetime import datetime
17
19
  from pathlib import Path
18
20
  from typing import Literal
@@ -22,7 +24,9 @@ from pydantic import BaseModel, ConfigDict
22
24
 
23
25
  from patchsight.db import SCHEMA_VERSION, DatabaseError, SymbolDatabase
24
26
 
25
- POINTER_URL = "https://raw.githubusercontent.com/professor3333/PatchSight/main/releases/latest.json"
27
+ _RAW = "https://raw.githubusercontent.com/professor3333/PatchSight"
28
+ POINTER_URLS = (f"{_RAW}/db-pointer/latest.json", f"{_RAW}/main/releases/latest.json")
29
+ POINTER_URL = POINTER_URLS[-1]
26
30
  _CHUNK = 1 << 20
27
31
 
28
32
 
@@ -54,11 +58,17 @@ def _https(url: str) -> str:
54
58
  return url
55
59
 
56
60
 
57
- def fetch_pointer(client: httpx.Client, url: str = POINTER_URL) -> Pointer:
58
- response = client.get(_https(url))
59
- if response.status_code == 404:
61
+ def fetch_pointer(client: httpx.Client, urls: str | Sequence[str] = POINTER_URLS) -> Pointer:
62
+ """The first published pointer among ``urls``. Only "not found" moves on to the next;
63
+ any other failure is an error, never a silent fallback."""
64
+ for url in (urls,) if isinstance(urls, str) else urls:
65
+ response = client.get(_https(url))
66
+ if response.status_code == 404:
67
+ continue
68
+ response.raise_for_status()
69
+ break
70
+ else:
60
71
  raise DatabaseError("no database has been published yet")
61
- response.raise_for_status()
62
72
  pointer = Pointer.model_validate_json(response.content)
63
73
  if pointer.schema_version != SCHEMA_VERSION:
64
74
  raise DatabaseError(
@@ -70,7 +80,7 @@ def fetch_pointer(client: httpx.Client, url: str = POINTER_URL) -> Pointer:
70
80
 
71
81
  def update(
72
82
  client: httpx.Client | None = None,
73
- pointer_url: str = POINTER_URL,
83
+ pointer_url: str | Sequence[str] = POINTER_URLS,
74
84
  target: Path | None = None,
75
85
  ) -> tuple[Literal["updated", "current"], Pointer]:
76
86
  owns = client is None
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: patchsight
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Know which vulnerable Python dependencies your code actually calls: symbol-level triage, no LLM at scan time.
5
5
  Keywords: security,vulnerability,dependencies,supply-chain,sca,static-analysis,reachability,osv,pypi,cli
6
6
  Author: Niroj33
@@ -93,7 +93,7 @@ The F1 95% interval is 0.62 to 0.74. The reports and a one-command offline repro
93
93
  ## Status: early release
94
94
 
95
95
  - Reads `requirements.txt` (exact `==` pins only), `uv.lock` and `poetry.lock`. Packages without a PyPI release version (unpinned requirements, git, URL or local sources) are listed, not guessed.
96
- - The current symbol database ([`db-2026.11.14`](https://github.com/professor3333/PatchSight/releases/tag/db-2026.11.14)) covers 3,505 PyPI vulnerabilities with **fallback records**: every function the fix changed, at low confidence. Expect many UNKNOWN verdicts until LLM-extracted, high-confidence records are published.
96
+ - The [symbol database](https://github.com/professor3333/PatchSight/releases) is updated every night and covers about 3,500 PyPI vulnerabilities, all at **low confidence** so far: every function the fix changed, plus the model's picks where the backfill has reached. Expect many UNKNOWN verdicts until high-confidence records are published.
97
97
  - Transitive use and dynamic code (`getattr` with a computed name, `importlib`, star imports) aren't analysed. They give UNKNOWN or NOT IMPORTED, never a false "not called".
98
98
 
99
99
  ## Links
@@ -1,14 +1,15 @@
1
1
  patchsight/__init__.py,sha256=vLpEyF0c4CjQA7vDNOpCfo9guKqHqKSOkNxf_219MTQ,154
2
2
  patchsight/cli.py,sha256=3oMH1awk91yiwjqp0k1l78NOrRm_qcPDf0UEEXjNToE,6185
3
- patchsight/db.py,sha256=49qrdsBkmpy9tG1aD3EUNzXjfNb47hbXdCYqDzmlT98,12530
3
+ patchsight/db.py,sha256=DK9wsO5h49wzYp-poAo9nOTKLvb-cl7MP47wP0XGsKU,14554
4
4
  patchsight/eval/__init__.py,sha256=KwJIvfvJA5OWGk8RnX8_VMZvJGe4ABkS1Y9Zwh-X0wk,89
5
5
  patchsight/eval/confidence.py,sha256=B5b5yR-5CDUDHNWNo70VzTO3cmo3T3AqI6AMwl-ca5g,6665
6
+ patchsight/eval/failures.py,sha256=8j7KoFHB6ReBsrQPVoOZ6r0q-40hVrjWvzhfKu89kPg,4634
6
7
  patchsight/eval/metrics.py,sha256=Mcp3IZK4cjdbbfAGA0BbCU1_K6cvmlip1yocD2cEIck,4167
7
8
  patchsight/eval/parity.py,sha256=-hFDEzRXKLhSGqBzz7-2nfK9U5i3nqAfldcSU-4TKvU,3969
8
9
  patchsight/eval/safety.py,sha256=MfKvuutlO8w2lhPSMfkgQ8titzR8mSNEqZ_KUFG_2lM,2030
9
10
  patchsight/names.py,sha256=SiexkbF5gwmFcAa4ob-B-TQU8K7ynIynmiub6gIWfUE,2762
10
11
  patchsight/pipeline/__init__.py,sha256=XA8KUKirqgHgTrMBVCJOiH3HXbhhYV9_1wvaq7IIKlw,171
11
- patchsight/pipeline/__main__.py,sha256=1giBw1kVkLyHv-gf8WUBu7OaaWj3WNoi2adEf5R4XaE,49708
12
+ patchsight/pipeline/__main__.py,sha256=8ATm_y3WlBUja9lvRdOngUqrGx1mwzae6zw_yyPmm-I,62292
12
13
  patchsight/pipeline/benchmarks/__init__.py,sha256=qdH_AVokG14O4QO3J9k5swF7opMj2wcNqprm_LdWBIk,56
13
14
  patchsight/pipeline/benchmarks/bundle.py,sha256=GwN9YKAWJ1U7lbAwK_vszNH44lNqTL2AhkKmEuWJ9l0,3806
14
15
  patchsight/pipeline/benchmarks/changedfuncs.py,sha256=JK9HpwbDcMiaJoy_x0dHO8D2cTcNnPdbgPUeAHbT77g,11875
@@ -16,7 +17,7 @@ patchsight/pipeline/benchmarks/dunlap.py,sha256=nYpKNs3FsCqFnpMhIhX3LWuxusmHk9TR
16
17
  patchsight/pipeline/benchmarks/extraction.py,sha256=AJi9IhQWKY6BXV1tQAayU0hjXQ4itjNnEvqzycUdZZ0,9562
17
18
  patchsight/pipeline/benchmarks/replay.py,sha256=cg4FtNJRob5-932a5uy8BXtulyBBjDVrM5wajfQAqJo,6481
18
19
  patchsight/pipeline/benchmarks/splits.py,sha256=FFrJrtgoQYE8gLA-uVfYAjOIDTRpHmjZN-irVudh5cM,4197
19
- patchsight/pipeline/build_db.py,sha256=g6x1E1VcEXJXr_2zHhb8xqwTV3B6ckMUDhSOcKcS4Fc,9856
20
+ patchsight/pipeline/build_db.py,sha256=aK3ckiNRVE_1pq0erxaCi5w-MWLbqKCUoUxhDPt5y54,10304
20
21
  patchsight/pipeline/diffs/__init__.py,sha256=S9ucrGp9Iyx_Rmnn37oASE5f_1e6Q9j1dFQUNdal4mg,80
21
22
  patchsight/pipeline/diffs/commits.py,sha256=B59ov4f8VK2N6SSAG4MgvEiatDpRkn8hGia0CKOs0KQ,3377
22
23
  patchsight/pipeline/diffs/github.py,sha256=DOJAvwU90X-131jid7rflvYxHvHiwoZluy0IXcGpqUQ,6109
@@ -25,10 +26,11 @@ patchsight/pipeline/diffs/mapping.py,sha256=RpiHdT8eU9xGwFfvx5sSgEUgjK_-Y6SA2pp6
25
26
  patchsight/pipeline/diffs/paths.py,sha256=YoFiizl9R1Fxn5DKZNHLSV_16_zmC7NrJAwb3dLU5n0,4190
26
27
  patchsight/pipeline/extract/__init__.py,sha256=RfboNSI_gdlD8mNxJ62heVtbSP1DUz4u-bjYWsPYjfQ,82
27
28
  patchsight/pipeline/extract/extractor.py,sha256=KXLvIjp7WtxbjHw_skEMS0lMl9JFt76b8Sd7wiMDTR0,6569
28
- patchsight/pipeline/extract/prompt.py,sha256=UuJo7t5PU6Hc44pCLz1bKRe_c5E3-bC6rEp9LE_uDDg,8920
29
+ patchsight/pipeline/extract/prompt.py,sha256=NawxXChwmhinjVamfin6huXowVjNJxsUK2my8U7axEU,9469
29
30
  patchsight/pipeline/extract/schema.py,sha256=qZt0SvZUDXmXXjTr6SSRLaS-d_9A3IF2NIsxb5YNXnc,1180
30
31
  patchsight/pipeline/extract/validate.py,sha256=m7V-wv9So3Lhv4F6hIJuj-JDtqzvRAcfEU4kbJZoZUU,3479
31
32
  patchsight/pipeline/fix_sample.py,sha256=c3633C7f8grjG2HpIaiXDhOj3TaD50FQuPclYUbxZT0,15096
33
+ patchsight/pipeline/gate.py,sha256=vuZZ_ChLtbJLZsTiS3l928bdHx6P5Ck0jv-LSHtzIJ4,5386
32
34
  patchsight/pipeline/http.py,sha256=qeKFSTYK1uMUpAETayaJbw518dcskDwT8NLDD1VcXv8,6175
33
35
  patchsight/pipeline/ingest/__init__.py,sha256=5quqlyH2AOBfAlJsEFJlepT0JDHwkgv1TedBRDe2pok,91
34
36
  patchsight/pipeline/ingest/aliases.py,sha256=QdAjQJkM3U_UlJX_Dv-mxUHmTIUM407rRvNh8Q4gydw,2565
@@ -38,17 +40,18 @@ patchsight/pipeline/ingest/references.py,sha256=-S3rHdgnKwIcNO1DGK0fffJb_-buuWQQ
38
40
  patchsight/pipeline/ingest/snapshot.py,sha256=AjfKjWSsBNaGobmhF2jiOQiLZzHgmv2xfO6_btYmJlA,4983
39
41
  patchsight/pipeline/kaggle_inputs.py,sha256=OWZmwNNCHXfUcS8LMuj0RwYYewYSKzFmqKj-IXRJJcM,5643
40
42
  patchsight/pipeline/llm/__init__.py,sha256=eT120LTL9rMmsjDgmk6xC9FRoFCS3bQiy3mmFgrmFuw,98
41
- patchsight/pipeline/llm/client.py,sha256=5h_8QSuJ22kNETHpACiFVnNAwEKsJRpc2U-2-z0wFZU,11337
43
+ patchsight/pipeline/llm/client.py,sha256=ZkXf_N0Tp0FoPODLfJqSVs6aRKdkPyqmoWe88L0EL9U,12053
42
44
  patchsight/pipeline/llm/config.py,sha256=QZJP1JsJ19DStzueC7sWS47ReLRYfWYeXe0lkwgHA3g,2660
43
45
  patchsight/pipeline/llm/tokens.py,sha256=BaKQx5tVPkIVj2nhK4HYiWTBISFbxuG__xQB70HbVbA,2584
44
46
  patchsight/pipeline/llm_records.py,sha256=wzAOB6NyOfoeME9bxguwIqBFvAoc-JoQOzQoY2RIpHs,5766
45
47
  patchsight/pipeline/pypi.py,sha256=faHaALTJJ6GFqKEA43qnfnGF-uqDdejatSKmuuNiUQc,2331
46
- patchsight/pipeline/pypi_extract.py,sha256=BVhE4N6j8RsLQ491-SUFsht9WT1XSEX5gn1D_a2XrRA,12419
48
+ patchsight/pipeline/pypi_extract.py,sha256=bSq4eC-loAKlmrVNitUKrVb_bK2kZZjBc5oYtP5icQ4,12600
49
+ patchsight/pipeline/update_db.py,sha256=WbpRdHqJXa9m9MB_kkEsILcHsfoRo-wP4NIAg_K24T4,4779
47
50
  patchsight/pipeline/week1.py,sha256=Gfj_EyCKoxJNsfGJyBZNg_wQPfthmHocbUBVumQ9btM,13193
48
51
  patchsight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
49
52
  patchsight/scan/__init__.py,sha256=R0wT7nQDIGlGCMbH9n9K4A_HSHWi6dqUAdOa6_TukWw,171
50
53
  patchsight/scan/ast_scanner.py,sha256=wy-ygB_0VFsMQFgljSSVdeJKXZXPahjOMom9gCuHZjs,9835
51
- patchsight/scan/dbcache.py,sha256=Q7zq6Hkl2bspXi8LocCEhdftJCozbYYJ4dSjAOwYx_o,4209
54
+ patchsight/scan/dbcache.py,sha256=4r0-ORVm804zOK6rc85u_5si3TB6I49rGTRtDsz5ui0,4778
52
55
  patchsight/scan/explain.py,sha256=aemXDT3mi8IjPuoadd418WGzJXDqCaRlgilOKMZ3djc,4838
53
56
  patchsight/scan/lockfiles/__init__.py,sha256=8z0djgmXYAcobGermLOkP3YmOS4G26LNMSSc8THTwec,1520
54
57
  patchsight/scan/lockfiles/poetry.py,sha256=D6C6nowWxP1C2v8kzk3yDCKNZ-NN2HIQBn6pHdDQ39Q,738
@@ -59,8 +62,8 @@ patchsight/scan/osv_client.py,sha256=RYe4OeuuJOIv8d4pTpsDxPHjlPLdoWEZXD9nIRpr17Q
59
62
  patchsight/scan/report.py,sha256=SsoBRfeHlt85MnLcE8xTyuuApMemDwLzm11wVanzPxs,3554
60
63
  patchsight/scan/run.py,sha256=zVaV6u4aG_hK3ieQ-RmCMjhVJLW00D5lxxHM2jgeMa8,1796
61
64
  patchsight/scan/verdicts.py,sha256=3S62XGAQ7NcpCwIOsW39jT2HxlDLtC0k4eOkbo6vkX8,6633
62
- patchsight-0.2.0.dist-info/licenses/LICENSE,sha256=yVuuHRzgI17MzTVgt3LsHvuX80innw--CmNPDCzO_iw,11358
63
- patchsight-0.2.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
64
- patchsight-0.2.0.dist-info/entry_points.txt,sha256=QqhXwY_t6ArVLxt9xXQ60NkidQyl0P2um1J46dY0bqw,51
65
- patchsight-0.2.0.dist-info/METADATA,sha256=taMYvhDskxaPGdR1LWrvwTbH_V-BznQiOqE7HMwdac4,6279
66
- patchsight-0.2.0.dist-info/RECORD,,
65
+ patchsight-0.3.0.dist-info/licenses/LICENSE,sha256=yVuuHRzgI17MzTVgt3LsHvuX80innw--CmNPDCzO_iw,11358
66
+ patchsight-0.3.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
67
+ patchsight-0.3.0.dist-info/entry_points.txt,sha256=QqhXwY_t6ArVLxt9xXQ60NkidQyl0P2um1J46dY0bqw,51
68
+ patchsight-0.3.0.dist-info/METADATA,sha256=sl7D4S-ikhRNOQWZqpeiAjP-_BuGQeoK7oQR4KXfpEc,6297
69
+ patchsight-0.3.0.dist-info/RECORD,,