exposuregate 0.1.0__py3-none-any.whl

exposuregate/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

exposuregate/__main__.py

@@ -0,0 +1,200 @@
+"""Command line interface (spec 4.1, 4.2)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import replace
+from datetime import date
+from pathlib import Path
+
+from exposuregate import __version__
+from exposuregate.config import REPORT_FORMATS, Config, ConfigError, load_config
+from exposuregate.gitio import GitError
+from exposuregate.lockfiles import PARSERS
+from exposuregate.report import to_json, to_markdown
+from exposuregate.scan import ScanOptions, UsageError, run_scan
+from exposuregate.store import DataInvalid, DataMissing
+
+USAGE_EXIT = 2
+
+
+def _iso_date(value: str) -> date:
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"invalid date {value!r}, expected YYYY-MM-DD") from None
+
+
+def _non_negative(value: str) -> int:
+    try:
+        n = int(value)
+    except ValueError:
+        n = -1
+    if n < 0:
+        raise argparse.ArgumentTypeError(f"expected a non-negative integer, got {value!r}")
+    return n
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="exposuregate")
+    p.add_argument("--version", action="version", version=f"exposuregate {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="grade dependency versions added in lockfiles")
+    s.add_argument("--mode", choices=["pre-commit", "pr", "full"])
+    s.add_argument("--target-branch", default="main")
+    s.add_argument("--base")
+    s.add_argument("--head")
+    s.add_argument("--old", type=Path)
+    s.add_argument("--new", type=Path)
+    s.add_argument("--lockfile-type", choices=sorted(PARSERS))
+    s.add_argument("--manifest", type=Path)
+    s.add_argument("--path", type=Path, default=Path("."))
+    s.add_argument("--config", type=Path)
+    s.add_argument("--format", nargs="+", choices=REPORT_FORMATS, dest="formats")
+    s.add_argument("--output-dir", type=Path)
+    s.add_argument("--data-dir", type=Path)
+    s.add_argument("--oebc", type=Path)
+    s.add_argument("--osv-dir", type=Path)
+    s.add_argument("--as-of", type=_iso_date)
+    s.add_argument("--replay", action="store_true")
+    s.add_argument("--archive", type=Path)
+    s.add_argument("--max-age-days", type=_non_negative)
+    s.add_argument("--fail-open", action="store_true")
+
+    u = sub.add_parser("update-data", help="download OEBC and OSV data (uses the network)")
+    u.add_argument("--data-dir", type=Path)
+    u.add_argument("--ecosystems", nargs="+", default=["PyPI", "npm"], choices=["PyPI", "npm"])
+
+    r = sub.add_parser("rebuild-oebc", help="rebuild an OEBC catalog as of a past date")
+    r.add_argument("--as-of", type=_iso_date, required=True)
+    r.add_argument("--kev", type=Path, required=True)
+    r.add_argument("--epss-dir", type=Path, required=True)
+    r.add_argument("--oebc", type=Path, required=True)
+    r.add_argument("--out", type=Path, required=True)
+
+    i = sub.add_parser("data-info", help="show the local data snapshot")
+    i.add_argument("--data-dir", type=Path)
+    return p
+
+
+def _scan_mode(p: argparse.ArgumentParser, a: argparse.Namespace) -> str:
+    """Validate the mutually exclusive input selections and return the scan mode."""
+    git_refs = a.base is not None or a.head is not None
+    files = a.old is not None or a.new is not None
+    if sum([a.mode is not None, git_refs, files]) > 1:
+        p.error("choose one input: --mode, --base/--head, or --old/--new")
+    if git_refs and (a.base is None or a.head is None):
+        p.error("--base and --head must be given together")
+    if files and a.new is None:
+        p.error("--old needs --new")
+    if a.new is not None and a.lockfile_type is None:
+        p.error("--new needs --lockfile-type")
+    if a.new is None and (a.lockfile_type is not None or a.manifest is not None):
+        p.error("--lockfile-type and --manifest are only valid with --new")
+    if a.replay and a.as_of is None:
+        p.error("--replay needs --as-of")
+    if a.archive is not None and a.as_of is None:
+        p.error("--archive needs --as-of")
+    if a.archive is not None and (a.oebc is not None or a.osv_dir is not None):
+        p.error("--archive cannot be combined with --oebc/--osv-dir")
+    if git_refs:
+        return "explicit"
+    if files:
+        return "files"
+    return a.mode or "pre-commit"
+
+
+def _resolve(base: Path, p: Path) -> Path:
+    p = p.expanduser()
+    return p if p.is_absolute() else base / p
+
+
+def _scan(p: argparse.ArgumentParser, a: argparse.Namespace) -> int:
+    mode = _scan_mode(p, a)
+    cfg: Config = load_config(a.config, a.path)
+    # Precedence: CLI flags > EXPOSUREGATE_DATA_DIR (applied by load_config) > config file.
+    if a.data_dir is not None:
+        cfg = replace(cfg, data_dir=a.data_dir.expanduser())
+    if a.max_age_days is not None:
+        cfg = replace(cfg, max_age_days=a.max_age_days)  # per-source overrides still win
+    formats = a.formats or cfg.report_formats
+    out_dir = a.output_dir or (Path(cfg.output_dir) if cfg.output_dir else None)
+    opts = ScanOptions(
+        mode=mode, target_branch=a.target_branch, base=a.base, head=a.head,
+        old_file=a.old, new_file=a.new, lockfile_type=a.lockfile_type, manifest_file=a.manifest,
+        path=a.path, data_dir=cfg.data_dir, oebc_file=a.oebc, osv_dir=a.osv_dir, as_of=a.as_of,
+        replay=a.replay, archive=a.archive, fail_open=a.fail_open, formats=formats,
+        output_dir=_resolve(a.path, out_dir) if out_dir else None,
+    )
+    print(f"exposuregate: scanning ({mode})", file=sys.stderr)
+    report, code = run_scan(opts, cfg)
+    rendered = {"json": to_json(report), "markdown": to_markdown(report)}
+    for fmt in formats:
+        sys.stdout.write(rendered[fmt].rstrip("\n") + "\n")
+    if opts.output_dir is not None:
+        opts.output_dir.mkdir(parents=True, exist_ok=True)
+        names = {"json": "report.json", "markdown": "report.md"}
+        for fmt in formats:
+            (opts.output_dir / names[fmt]).write_text(rendered[fmt], encoding="utf-8")
+        print(f"exposuregate: reports written to {opts.output_dir}", file=sys.stderr)
+    s = report["summary"]
+    print(
+        f"exposuregate: {report['verdict']} ({s['block']} block, {s['warn']} warn,"
+        f" {s['pass']} pass, {s['denials']} denials)",
+        file=sys.stderr,
+    )
+    return code
+
+
+def _data_dir(a: argparse.Namespace) -> Path:
+    if a.data_dir is not None:
+        return Path(a.data_dir).expanduser()
+    return load_config(None, Path(".")).data_dir
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = _parser()
+    try:
+        a = p.parse_args(argv)
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else USAGE_EXIT
+    try:
+        if a.command == "scan":
+            return _scan(p, a)
+        if a.command == "update-data":
+            from exposuregate.update import update_data
+
+            data_dir = _data_dir(a)
+            print(f"exposuregate: updating data in {data_dir}", file=sys.stderr)
+            update_data(data_dir, list(a.ecosystems))
+            return 0
+        if a.command == "rebuild-oebc":
+            from exposuregate.rebuild import rebuild_oebc
+
+            cat = rebuild_oebc(a.as_of, a.kev, a.epss_dir, a.oebc, a.out)
+            print(f"exposuregate: rebuilt OEBC as of {a.as_of}: {cat['count']} CVEs -> {a.out}",
+                  file=sys.stderr)
+            return 0
+        if a.command == "data-info":
+            from exposuregate.update import data_info
+
+            print(data_info(_data_dir(a)))
+            return 0
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else USAGE_EXIT
+    except (ConfigError, GitError, UsageError) as e:
+        print(f"exposuregate: error: {e}", file=sys.stderr)
+        return USAGE_EXIT
+    except (DataMissing, DataInvalid) as e:
+        print(f"exposuregate: error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:  # noqa: BLE001 - exit 1 means BLOCK, so never let a crash reach it
+        print(f"exposuregate: unexpected error: {type(e).__name__}: {e}", file=sys.stderr)
+        return USAGE_EXIT
+    return USAGE_EXIT
+
+
+if __name__ == "__main__":
+    sys.exit(main())

exposuregate/archive.py

@@ -0,0 +1,145 @@
+"""Reader for the daily snapshot archive (spec 6.5; layout of paper/eval/archive/archive.py).
+
+Layout under the root:
+  days/<D>.json                       manifest: "sources" per source, "errors" per failed source
+  blobs/<source>/<sha256>.<ext>       KEV JSON and OEBC catalog
+  osv/<eco>/index-<D>.jsonl.gz        every advisory {"id", "modified"} in that day's export
+  osv/<eco>/delta-<D>.jsonl.gz        records whose (id, modified) was new that day
+
+OSV state as of D: for each id in index-D, the record with that id and the same ``modified``
+from delta files dated <= D.
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+from collections.abc import Iterable, Iterator
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from exposuregate.store import DataInvalid, DataMissing, MemoryStore, parse_osv_record
+
+
+def _read_manifest(path: Path) -> dict[str, Any]:
+    try:
+        man: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(man.get("sources"), dict) or not isinstance(man.get("errors", {}), dict):
+            raise ValueError("sources/errors are not objects")
+    except (OSError, ValueError, AttributeError) as e:
+        raise DataInvalid(f"invalid archive manifest {path}: {e}") from e
+    return man
+
+
+def _usable(man: dict[str, Any], needed: list[str]) -> bool:
+    errors = man.get("errors", {})
+    return all(s in man["sources"] and s not in errors for s in needed)
+
+
+def _pick_day(root: Path, as_of: date, ecosystems: list[str]) -> tuple[str, dict[str, Any]]:
+    """Latest manifest dated <= as_of with every needed source present and error-free."""
+    days_dir = root / "days"
+    if not days_dir.is_dir():
+        raise DataMissing(f"no snapshot archive at {root} (missing days/)")
+    days: list[date] = []
+    for p in days_dir.glob("*.json"):
+        try:
+            days.append(date.fromisoformat(p.stem))
+        except ValueError:
+            continue
+    needed = ["oebc", *(f"osv-{e}" for e in ecosystems)]
+    for d in sorted((d for d in days if d <= as_of), reverse=True):
+        man = _read_manifest(days_dir / f"{d.isoformat()}.json")
+        if _usable(man, needed):
+            return d.isoformat(), man
+    raise DataMissing(
+        f"archive {root}: no day on or before {as_of} with {', '.join(needed)} archived"
+    )
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _jsonl(path: Path) -> Iterator[str]:
+    try:
+        with gzip.open(path, "rt", encoding="utf-8") as g:
+            yield from (line for line in g if line.strip())
+    except (OSError, EOFError, UnicodeDecodeError) as e:
+        raise DataInvalid(f"cannot read {path}: {e}") from e
+
+
+def _osv_state(root: Path, eco: str, day: str, entry: dict[str, Any]) -> Iterator[dict[str, Any]]:
+    """Every record of ``eco`` as it stood on ``day``."""
+    rel = entry.get("index") if isinstance(entry, dict) else None
+    index = root / str(rel or f"osv/{eco}/index-{day}.jsonl.gz")
+    if not index.is_file():
+        raise DataMissing(f"archive index missing: {index}")
+    wanted: dict[str, str] = {}
+    for line in _jsonl(index):
+        try:
+            row = json.loads(line)
+            wanted[str(row["id"])] = str(row["modified"])
+        except (ValueError, KeyError, TypeError) as e:
+            raise DataInvalid(f"invalid archive index line in {index}: {e!r}") from e
+    deltas = sorted(
+        p for p in (root / "osv" / eco).glob("delta-*.jsonl.gz")
+        if p.name[len("delta-"):-len(".jsonl.gz")] <= day
+    )
+    for delta in deltas:
+        if not wanted:
+            break
+        for line in _jsonl(delta):
+            rec = parse_osv_record(line, str(delta))
+            if wanted.get(rec["id"]) == rec.get("modified", ""):
+                del wanted[rec["id"]]
+                yield rec
+    if wanted:
+        sample = ", ".join(sorted(wanted)[:5])
+        raise DataInvalid(
+            f"archive {root}: {len(wanted)} {eco} records of {day} not found in deltas ({sample})"
+        )
+
+
+class ArchiveStore:
+    @staticmethod
+    def open(root: Path, as_of: date, ecosystems: Iterable[str] = ()) -> MemoryStore:
+        """Data as archived on the latest day <= as_of whose OEBC and needed OSV were archived.
+
+        ``ecosystems``: the OSV ecosystems to load; a day with an error for any of them (or for
+        OEBC) is skipped. Archived state is already as of that day, so no ``published`` filter.
+        """
+        names = sorted(set(ecosystems))
+        day, man = _pick_day(root, as_of, names)
+        oebc_entry = man["sources"]["oebc"]
+        try:
+            blob = root / str(oebc_entry["blob"])
+            expected = str(oebc_entry["sha256"])
+        except (KeyError, TypeError) as e:
+            raise DataInvalid(f"archive manifest {day}: bad oebc entry: {e!r}") from e
+        if not blob.is_file():
+            raise DataMissing(f"archived OEBC blob missing: {blob}")
+        if _sha256(blob) != expected:
+            raise DataInvalid(f"archived OEBC blob {blob} does not match sha256 {expected}")
+        seen: set[str] = set()
+
+        def records() -> Iterator[dict[str, Any]]:
+            for eco in names:
+                for rec in _osv_state(root, eco, day, man["sources"][f"osv-{eco}"]):
+                    if rec["id"] not in seen:  # an advisory in two ecosystems' exports
+                        seen.add(rec["id"])
+                        yield rec
+
+        store = MemoryStore.from_records(blob, records())
+        store.meta.replay = {"osv_mode": "archived", "archive_day": day}
+        if store.meta.oebc is not None:
+            store.meta.oebc.extra["source"] = f"{blob} (archive {root}, day {day})"
+        for eco, src in store.meta.osv.items():
+            src.extra["source"] = f"{root / 'osv' / eco} (archive {root}, day {day})"
+        return store

exposuregate/config.py

@@ -0,0 +1,242 @@
+"""Configuration loading with strict validation (spec section 8)."""
+
+from __future__ import annotations
+
+import copy
+import os
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ACTIONS = ("block", "warn", "pass")
+REPORT_FORMATS = ("json", "markdown")
+CONFIG_FILENAME = ".exposuregate.yml"
+
+DEFAULTS: dict[str, Any] = {
+    "fail_closed": True,
+    "data": {
+        "dir": "~/.cache/exposuregate",
+        "max_age_days": 7,
+        "oebc_max_age_days": None,
+        "osv_max_age_days": None,
+    },
+    "policy": {
+        "CRITICAL": "block",
+        "HIGH": "warn",
+        "MEDIUM": "pass",
+        "LOW": "pass",
+        "not_in_oebc": "warn",
+        "no_cve": "warn",
+        "unparseable_version": "warn",
+        "unpinned": "warn",
+        "unsupported_lockfile": "warn",
+        "transitive_max_action": "block",
+    },
+    "lockfiles": {
+        "requirements": {"enabled": True, "globs": ["requirements*.txt"]},
+        "poetry": {"enabled": True, "globs": ["poetry.lock"]},
+        "uv": {"enabled": True, "globs": ["uv.lock"]},
+        "npm": {"enabled": True, "globs": ["package-lock.json"]},
+    },
+    "unsupported_globs": [
+        "yarn.lock", "pnpm-lock.yaml", "Pipfile.lock", "bun.lock", "bun.lockb",
+        "Cargo.lock", "go.sum", "Gemfile.lock", "composer.lock", "gradle.lockfile",
+    ],
+    "exclusions": {"paths": []},
+    "suppressions": [],
+    "reporting": {"format": ["json", "markdown"], "output_dir": ".exposuregate/reports"},
+}
+
+_SUPPRESSION_KEYS = {"id", "reason", "expires", "package", "ecosystem"}
+
+
+class ConfigError(Exception):
+    """Invalid configuration (exit code 2)."""
+
+
+@dataclass
+class Suppression:
+    id: str
+    reason: str
+    expires: date
+    package: str | None = None
+    ecosystem: str | None = None
+
+
+@dataclass
+class LockfileTypeConfig:
+    enabled: bool
+    globs: list[str]
+
+
+@dataclass
+class Config:
+    fail_closed: bool
+    data_dir: Path
+    max_age_days: int
+    oebc_max_age_days: int | None
+    osv_max_age_days: int | None
+    policy: dict[str, str]
+    transitive_max_action: str
+    lockfiles: dict[str, LockfileTypeConfig]
+    unsupported_globs: list[str]
+    excluded_paths: list[str]
+    suppressions: list[Suppression]
+    report_formats: list[str]
+    output_dir: str | None
+
+    def max_age(self, source: str) -> int:
+        if source == "oebc":
+            override = self.oebc_max_age_days
+        elif source == "osv":
+            override = self.osv_max_age_days
+        else:
+            raise ValueError(f"unknown data source: {source!r}")
+        return self.max_age_days if override is None else override
+
+
+def _is_int(v: Any) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool)
+
+
+def _str_list(v: Any, path: str) -> list[str]:
+    if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+        raise ConfigError(f"{path}: expected a list of strings")
+    return list(v)
+
+
+def _merge(default: Any, user: Any, path: str) -> Any:
+    """Deep-merge user over default, rejecting unknown keys in dict sections."""
+    if not isinstance(default, dict):
+        return user
+    if not isinstance(user, dict):
+        raise ConfigError(f"{path or '<root>'}: expected a mapping")
+    merged = copy.deepcopy(default)
+    for key, value in user.items():
+        kpath = f"{path}.{key}" if path else str(key)
+        if key not in default:
+            raise ConfigError(f"unknown key: {kpath}")
+        merged[key] = _merge(default[key], value, kpath)
+    return merged
+
+
+def _validate_scalar_types(d: dict[str, Any]) -> None:
+    if not isinstance(d["fail_closed"], bool):
+        raise ConfigError("fail_closed: expected a boolean")
+    data = d["data"]
+    if not isinstance(data["dir"], str) or not data["dir"]:
+        raise ConfigError("data.dir: expected a non-empty string")
+    if not _is_int(data["max_age_days"]) or data["max_age_days"] < 0:
+        raise ConfigError("data.max_age_days: expected a non-negative integer")
+    for k in ("oebc_max_age_days", "osv_max_age_days"):
+        v = data[k]
+        if v is not None and (not _is_int(v) or v < 0):
+            raise ConfigError(f"data.{k}: expected a non-negative integer or null")
+    for k, v in d["policy"].items():
+        if v not in ACTIONS:
+            raise ConfigError(f"policy.{k}: invalid action {v!r}, expected one of {list(ACTIONS)}")
+    for name, lf in d["lockfiles"].items():
+        if not isinstance(lf["enabled"], bool):
+            raise ConfigError(f"lockfiles.{name}.enabled: expected a boolean")
+        _str_list(lf["globs"], f"lockfiles.{name}.globs")
+    _str_list(d["unsupported_globs"], "unsupported_globs")
+    _str_list(d["exclusions"]["paths"], "exclusions.paths")
+    fmts = _str_list(d["reporting"]["format"], "reporting.format")
+    for f in fmts:
+        if f not in REPORT_FORMATS:
+            raise ConfigError(
+                f"reporting.format: invalid format {f!r}, expected one of {list(REPORT_FORMATS)}"
+            )
+    out = d["reporting"]["output_dir"]
+    if out is not None and not isinstance(out, str):
+        raise ConfigError("reporting.output_dir: expected a string or null")
+
+
+def _parse_suppression(raw: Any, idx: int) -> Suppression:
+    path = f"suppressions[{idx}]"
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path}: expected a mapping")
+    for key in raw:
+        if key not in _SUPPRESSION_KEYS:
+            raise ConfigError(f"unknown key: {path}.{key}")
+    for key in ("id", "reason", "expires"):
+        if key not in raw or raw[key] is None:
+            raise ConfigError(f"{path}.{key}: required")
+    for key in ("id", "reason"):
+        if not isinstance(raw[key], str) or not raw[key].strip():
+            raise ConfigError(f"{path}.{key}: expected a non-empty string")
+    for key in ("package", "ecosystem"):
+        v = raw.get(key)
+        if v is not None and (not isinstance(v, str) or not v):
+            raise ConfigError(f"{path}.{key}: expected a non-empty string")
+    exp = raw["expires"]
+    if isinstance(exp, datetime):
+        exp = exp.date()
+    elif isinstance(exp, str):
+        try:
+            exp = date.fromisoformat(exp)
+        except ValueError:
+            raise ConfigError(f"{path}.expires: invalid date {exp!r}") from None
+    elif not isinstance(exp, date):
+        raise ConfigError(f"{path}.expires: expected a date (YYYY-MM-DD)")
+    return Suppression(
+        id=raw["id"], reason=raw["reason"], expires=exp,
+        package=raw.get("package"), ecosystem=raw.get("ecosystem"),
+    )
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as e:
+        raise ConfigError(f"cannot read config {path}: {e}") from e
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise ConfigError(f"{path}: top level must be a mapping")
+    return loaded
+
+
+def load_config(path: Path | None, cwd: Path) -> Config:
+    user: dict[str, Any] = {}
+    if path is not None:
+        if not path.is_file():
+            raise ConfigError(f"config file not found: {path}")
+        user = _read_yaml(path)
+    elif (cwd / CONFIG_FILENAME).is_file():
+        user = _read_yaml(cwd / CONFIG_FILENAME)
+
+    # Suppressions and lockfile entries are validated separately: lists are
+    # replaced wholesale, and lockfile types are a closed set from the defaults.
+    suppressions_raw = user.pop("suppressions", [])
+    if not isinstance(suppressions_raw, list):
+        raise ConfigError("suppressions: expected a list")
+    merged = _merge({**DEFAULTS, "suppressions": None}, {**user, "suppressions": None}, "")
+    merged["suppressions"] = suppressions_raw
+    _validate_scalar_types(merged)
+
+    env_dir = os.environ.get("EXPOSUREGATE_DATA_DIR")
+    data = merged["data"]
+    policy = dict(merged["policy"])
+    transitive = policy.pop("transitive_max_action")
+    return Config(
+        fail_closed=merged["fail_closed"],
+        data_dir=Path(env_dir or data["dir"]).expanduser(),
+        max_age_days=data["max_age_days"],
+        oebc_max_age_days=data["oebc_max_age_days"],
+        osv_max_age_days=data["osv_max_age_days"],
+        policy=policy,
+        transitive_max_action=transitive,
+        lockfiles={
+            n: LockfileTypeConfig(enabled=lf["enabled"], globs=list(lf["globs"]))
+            for n, lf in merged["lockfiles"].items()
+        },
+        unsupported_globs=list(merged["unsupported_globs"]),
+        excluded_paths=list(merged["exclusions"]["paths"]),
+        suppressions=[_parse_suppression(s, i) for i, s in enumerate(suppressions_raw)],
+        report_formats=list(merged["reporting"]["format"]),
+        output_dir=merged["reporting"]["output_dir"],
+    )

exposuregate/diffing.py

@@ -0,0 +1,40 @@
+"""Diff two parsed lockfiles into added/changed pins."""
+
+from __future__ import annotations
+
+from functools import cmp_to_key
+
+from exposuregate.models import ChangedPin, ParsedLockfile, Pin
+from exposuregate.versions import InvalidVersion, compare
+
+
+def _cmp(ecosystem: str, a: str, b: str) -> int:
+    try:
+        return compare(ecosystem, a, b)
+    except InvalidVersion:
+        return (a > b) - (a < b)
+
+
+def changed_pins(old: ParsedLockfile | None, new: ParsedLockfile) -> list[ChangedPin]:
+    """Pins in new whose key is not in old, with the lowest differing old version."""
+    old_pins = old.pins if old is not None else []
+    old_keys = {p.key for p in old_pins}
+    old_versions: dict[str, set[str]] = {}
+    for p in old_pins:
+        if p.version:
+            old_versions.setdefault(p.name, set()).add(p.version)
+
+    def previous(pin: Pin) -> str | None:
+        if not pin.version:
+            return None
+        others = [v for v in old_versions.get(pin.name, ()) if v != pin.version]
+        if not others:
+            return None
+        def cmp(a: str, b: str) -> int:
+            return _cmp(pin.ecosystem, a, b)
+
+        return min(others, key=cmp_to_key(cmp))
+
+    out = [ChangedPin(p, previous(p)) for p in new.pins if p.key not in old_keys]
+    out.sort(key=lambda c: (c.pin.name, c.pin.version or c.pin.unpinned_spec or ""))
+    return out

exposuregate/freshness.py

@@ -0,0 +1,58 @@
+"""Data freshness checks (spec 6.3, 6.4)."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+
+from exposuregate.config import Config
+from exposuregate.models import Denial
+from exposuregate.store import DataMeta, SourceMeta
+
+
+def _utc_date(dt: datetime) -> date:
+    if dt.tzinfo is None:
+        return dt.date()
+    return dt.astimezone(timezone.utc).date()
+
+
+def _check_source(
+    label: str, name: str, src: SourceMeta, now: date, max_age: int, out: list[Denial]
+) -> None:
+    d = _utc_date(src.date)
+    if d > now:
+        out.append(
+            Denial("data_from_future", f"{label} {name} {d} is after as-of date {now}")
+        )
+        return
+    age = (now - d).days
+    if age > max_age:
+        out.append(
+            Denial("data_stale", f"{label} {name} {d} is {age} days old (max {max_age})")
+        )
+
+
+def check(
+    meta: DataMeta | None,
+    needed_ecosystems: set[str],
+    now: date,
+    cfg: Config,
+    replay: bool,
+) -> list[Denial]:
+    if not needed_ecosystems:
+        return []
+    if meta is None:
+        return [Denial("data_missing", "no advisory data store found; run update-data")]
+    out: list[Denial] = []
+    if meta.oebc is None:
+        out.append(Denial("data_missing", "OEBC catalog is missing from the data store"))
+    else:
+        _check_source("OEBC", "generated", meta.oebc, now, cfg.max_age("oebc"), out)
+    for eco in sorted(needed_ecosystems):
+        src = meta.osv.get(eco)
+        if src is None:
+            out.append(
+                Denial("data_missing", f"OSV {eco} data is missing from the data store")
+            )
+        elif not replay:
+            _check_source("OSV", f"{eco} as of", src, now, cfg.max_age("osv"), out)
+    return out