bompage 1.0.0__py3-none-any.whl

bompage/_git.py

@@ -0,0 +1,72 @@
+"""Shared helpers for shelling out to ``git`` against the central bompage
+repository (spec sections 5 and 5.4).
+
+Both :mod:`bompage.push` and :mod:`bompage.prune` clone the central repo with a
+scoped token, modify ``reports/`` and push. The token is handed to git through a
+one-shot ``credential.helper`` that reads it from the child environment, so it
+never lands on a command line (visible to ``ps`` on a shared runner) nor in the
+clone's ``.git/config``.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+DEFAULT_BRANCH = "main"
+DEFAULT_GIT_USER = "bompage-ci"
+DEFAULT_GIT_EMAIL = "bompage-ci@localhost"
+
+_TOKEN_ENV = "BOMPAGE_GIT_TOKEN"
+# git runs this with the credential operation as $1 and reads the answer from
+# stdout; the password comes from the environment, never from argv.
+_CREDENTIAL_HELPER = (
+    f'!f() {{ echo "username=x-access-token"; echo "password=${_TOKEN_ENV}"; }}; f'
+)
+
+
+class GitRepoError(RuntimeError):
+    """A git step (clone, rm, commit, push) failed."""
+
+
+def _redact(text: str, token: str | None) -> str:
+    """Blank out the token wherever git may have echoed it back."""
+    return text.replace(token, "***") if token else text
+
+
+def _git_env(token: str | None) -> dict[str, str]:
+    """Child environment for git: never prompt, carry the token out of argv."""
+    env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
+    if token:
+        env[_TOKEN_ENV] = token
+    return env
+
+
+def _run_git(
+    args: list[str], *, cwd: Path | None = None, token: str | None = None
+) -> None:
+    """Run ``git <args>``; raise :class:`GitRepoError` (token redacted) on failure.
+
+    Every call resets any inherited ``credential.helper`` and installs the
+    env-backed one, so clone and push authenticate without the token ever
+    reaching the command line.
+    """
+    proc = subprocess.run(
+        [
+            "git",
+            "-c",
+            "credential.helper=",
+            "-c",
+            f"credential.helper={_CREDENTIAL_HELPER}",
+            *args,
+        ],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_git_env(token),
+    )
+    if proc.returncode != 0:
+        detail = _redact((proc.stderr or proc.stdout).strip(), token)
+        raise GitRepoError(f"git {args[0]} failed: {detail}")

bompage/_time.py

@@ -0,0 +1,20 @@
+"""Clock helper shared by the commands that derive a calendar day from ``now``.
+
+``build`` (freshness verdict and the recent-changes window), ``push`` (the
+``sbom-YYYYMMDD`` file stamp) and ``prune`` (the retention cutoff) all turn an
+instant into a UTC calendar day. Routing every one through :func:`as_utc` keeps
+that day independent of the caller's timezone -- a naive datetime is assumed to
+already be UTC, an aware one is converted.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+def as_utc(now: datetime | None) -> datetime:
+    """Resolve ``now`` (or the current instant) to an aware UTC datetime."""
+    resolved = now or datetime.now(tz=UTC)
+    if resolved.tzinfo is None:
+        return resolved.replace(tzinfo=UTC)
+    return resolved.astimezone(UTC)

bompage/analysis/drift.py

@@ -0,0 +1,71 @@
+"""Cross-component inverted index and version-drift detection.
+
+``build_package_index`` maps every package name to the list of components that
+carry it, with the version and ecosystem seen on each (spec section 7.3). That
+index powers the transverse search and, via ``active_drifts``, the list of
+dependencies that sit at diverging versions across components (spec section
+7.4), each dated by when the divergence last widened so the dashboard can sort
+by how long it has stood.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+from bompage.models import ComponentReport, Drift, PackageOccurrence
+
+# A drift needs the package on at least this many components, at this many
+# distinct versions.
+_MIN_FOR_DRIFT = 2
+
+
+def build_package_index(
+    components: list[ComponentReport],
+) -> dict[str, list[PackageOccurrence]]:
+    """Map each package name to one occurrence per component that carries it.
+
+    A component may list the same name at several versions (spec section 7.3
+    speaks of "the version detected on each", singular); keep the highest so a
+    within-component duplicate is not mistaken for a cross-component drift.
+    """
+    index: dict[str, list[PackageOccurrence]] = {}
+    for component in sorted(components, key=lambda c: c.name):
+        best: dict[str, PackageOccurrence] = {}
+        for pkg in component.packages:
+            current = best.get(pkg.name)
+            if current is None or (pkg.version or "") > (current.version or ""):
+                best[pkg.name] = PackageOccurrence(
+                    component=component.name,
+                    version=pkg.version,
+                    ecosystem=pkg.ecosystem,
+                )
+        for name, occurrence in best.items():
+            index.setdefault(name, []).append(occurrence)
+    return index
+
+
+def _current_version_date(component: ComponentReport, name: str) -> date:
+    history = component.timeline.get(name)
+    if history:
+        return history[-1].first_seen
+    return component.last_scan_date  # pragma: no cover - guard for inconsistent input
+
+
+def active_drifts(
+    index: dict[str, list[PackageOccurrence]],
+    components: list[ComponentReport],
+) -> list[Drift]:
+    """Packages present on 2+ components at 2+ distinct versions."""
+    by_name = {component.name: component for component in components}
+    drifts: list[Drift] = []
+    for name, occurrences in index.items():
+        if len(occurrences) < _MIN_FOR_DRIFT:
+            continue
+        if len({occ.version for occ in occurrences}) < _MIN_FOR_DRIFT:
+            continue
+        since = max(
+            _current_version_date(by_name[occ.component], name) for occ in occurrences
+        )
+        drifts.append(Drift(name=name, entries=list(occurrences), since=since))
+    drifts.sort(key=lambda d: (d.since, d.name))
+    return drifts

bompage/analysis/freshness.py

@@ -0,0 +1,30 @@
+"""Data-freshness evaluation for a component (spec section 7.5).
+
+Turns a component's most recent scan date plus a staleness threshold into a
+``Freshness`` verdict, so the dashboard can tell "no dependency change" apart
+from "the source pipeline stopped pushing".
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime
+
+from bompage.models import Freshness
+
+
+def evaluate(last_scan: date, *, now: datetime, stale_after: int) -> Freshness:
+    """Days since the last report, and whether that exceeds ``stale_after``.
+
+    ``now`` is taken in UTC (an aware datetime in any zone is converted first, a
+    naive one is assumed to already be UTC), so the day boundary is fixed
+    regardless of the caller's local time and a scan stamped "today" never reads
+    as one day stale near midnight.
+    """
+    now_utc = now if now.tzinfo is not None else now.replace(tzinfo=UTC)
+    # Clamp a future-dated scan (source clock ahead) to 0 rather than show "-3d".
+    days_since_scan = max(0, (now_utc.astimezone(UTC).date() - last_scan).days)
+    return Freshness(
+        last_scan_date=last_scan,
+        days_since_scan=days_since_scan,
+        is_stale=days_since_scan > stale_after,
+    )

bompage/analysis/inventory.py

@@ -0,0 +1,85 @@
+"""Current-inventory computation for a component.
+
+Builds ``current_inventory`` from the latest snapshot: package name, version,
+ecosystem inferred from the ``purl``, and licence, flagging strict copyleft
+licences for the dashboard (spec sections 6.1 point 4 and 7.1).
+"""
+
+from __future__ import annotations
+
+import re
+from functools import cache
+
+from bompage.models import Package
+
+# purl type -> human label shown in the dashboard filter (spec section 7.1).
+_ECOSYSTEMS = {
+    "pypi": "PyPI",
+    "npm": "npm",
+    "deb": "Deb",
+    "apk": "Alpine",
+    "rpm": "RPM",
+    "cargo": "Cargo",
+    "gem": "RubyGems",
+    "golang": "Go",
+    "maven": "Maven",
+    "nuget": "NuGet",
+    "composer": "Composer",
+    "hex": "Hex",
+    "oci": "OCI",
+    "cran": "CRAN",
+}
+
+_PURL_TYPE_RE = re.compile(r"^pkg:(?P<type>[^/]+)/")
+
+# Strong ("strict") copyleft families flagged in the dashboard (spec section 7.1).
+# GPL/AGPL are handled separately so the LGPL exclusion stays correct.
+_STRONG_COPYLEFT = ("EUPL", "OSL", "CECILL", "SSPL", "RPL", "CPAL")
+
+
+def _ecosystem(purl: str | None) -> str | None:
+    if not purl:
+        return None
+    match = _PURL_TYPE_RE.match(purl)
+    if match is None:
+        return None
+    purl_type = match["type"].lower()
+    # Known types get a curated label; any other valid purl type is still shown
+    # and filterable under its own name rather than dropped.
+    return _ECOSYSTEMS.get(purl_type, purl_type.title())
+
+
+# Memoised: pure, and called once per package on the latest snapshot of every
+# component with a very small set of distinct licence strings (``MIT``,
+# ``Apache-2.0``, …). The normalisation below (upper + regex strip + scan) is
+# the priciest bit of inventory enrichment; the process is short-lived so an
+# unbounded cache is safe.
+@cache
+def _is_strong_copyleft(license_id: str | None) -> bool:
+    if not license_id:
+        return False
+    norm = re.sub(r"[^A-Z]", "", license_id.upper())
+    # CeCILL-B is BSD-style permissive and CeCILL-C is LGPL-style weak copyleft;
+    # only plain CeCILL (v1 / v2 / v2.1) is strong. Drop the weak variants
+    # before the scan, the same way LGPL is excluded from the GPL test below.
+    norm = norm.replace("CECILLB", "").replace("CECILLC", "")
+    if any(token in norm for token in _STRONG_COPYLEFT):
+        return True
+    # GPL / AGPL but not (only) LGPL: drop LGPL runs before looking for GPL.
+    return "GPL" in norm.replace("LGPL", "")
+
+
+def build_inventory(packages: list[Package]) -> list[Package]:
+    """Return the deduplicated, ecosystem-enriched inventory, sorted by name."""
+    seen: dict[tuple[str, str | None, str | None], Package] = {}
+    for pkg in packages:
+        key = (pkg.name, pkg.version, pkg.purl)
+        if key in seen:
+            continue
+        seen[key] = pkg.model_copy(
+            update={
+                "ecosystem": _ecosystem(pkg.purl),
+                "is_strong_copyleft": _is_strong_copyleft(pkg.license),
+            }
+        )
+    return sorted(seen.values(), key=lambda p: (p.name.lower(), p.version or ""))

bompage/analysis/timeline.py

@@ -0,0 +1,120 @@
+"""Version history derived from a component's dated snapshots.
+
+- ``build_timeline`` : per package, the sequence of versions it held, a new
+  entry only when the version differs from the last one recorded (spec section
+  6.1 point 4).
+- ``diff_last_two`` : the explicit ``added`` / ``removed`` lists between the two
+  most recent snapshots.
+- ``recent_changes`` : every add / remove / version change whose date falls in a
+  sliding window (spec section 7.2 "changements récents").
+
+All three key off the same per-snapshot ``{name: version}`` view
+(:func:`snapshot_versions`). The build passes that view in precomputed via the
+``versions`` keyword so it is built once per snapshot rather than once per
+function; callers that omit it get it computed on the fly.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from itertools import pairwise
+
+from bompage.models import Change, Package, Snapshot, TimelineEntry
+
+_MIN_SNAPSHOTS_FOR_DIFF = 2
+
+
+def snapshot_versions(snapshot: Snapshot) -> dict[str, str | None]:
+    """Map each package name to its version in this snapshot.
+
+    A name may legitimately appear more than once in one snapshot (e.g. an npm
+    tree that carries two versions of the same package). Keep the highest
+    version -- same ``version or ""`` ordering the inventory sorts by -- so the
+    timeline and the added/removed deltas stay deterministic instead of
+    depending on package order.
+    """
+    versions: dict[str, str | None] = {}
+    for pkg in snapshot.packages:
+        if pkg.name not in versions or (pkg.version or "") > (versions[pkg.name] or ""):
+            versions[pkg.name] = pkg.version
+    return versions
+
+
+def _resolve(
+    snapshots: list[Snapshot], versions: list[dict[str, str | None]] | None
+) -> list[dict[str, str | None]]:
+    if versions is None:
+        return [snapshot_versions(snapshot) for snapshot in snapshots]
+    if len(versions) != len(snapshots):
+        msg = "versions must have one entry per snapshot"
+        raise ValueError(msg)
+    return versions
+
+
+def build_timeline(
+    snapshots: list[Snapshot],
+    *,
+    versions: list[dict[str, str | None]] | None = None,
+) -> dict[str, list[TimelineEntry]]:
+    """Map each package name to its ordered list of version changes."""
+    per_snapshot = _resolve(snapshots, versions)
+    timeline: dict[str, list[TimelineEntry]] = {}
+    for snapshot, snapshot_view in zip(snapshots, per_snapshot, strict=True):
+        for name, version in snapshot_view.items():
+            history = timeline.setdefault(name, [])
+            if not history or history[-1].version != version:
+                history.append(TimelineEntry(version=version, first_seen=snapshot.date))
+    return timeline
+
+
+def diff_last_two(
+    snapshots: list[Snapshot],
+    *,
+    versions: list[dict[str, str | None]] | None = None,
+) -> tuple[list[Package], list[str]]:
+    """Packages added and package names removed between the last two snapshots."""
+    if len(snapshots) < _MIN_SNAPSHOTS_FOR_DIFF:
+        return [], []
+    per_snapshot = _resolve(snapshots, versions)
+    previous = per_snapshot[-2]
+    current = {pkg.name: pkg for pkg in snapshots[-1].packages}
+    added = [pkg for name, pkg in current.items() if name not in previous]
+    removed = [name for name in previous if name not in current]
+    return added, sorted(removed)
+
+
+def recent_changes(
+    snapshots: list[Snapshot],
+    *,
+    since: date,
+    versions: list[dict[str, str | None]] | None = None,
+) -> list[Change]:
+    """Add / remove / version-change events dated on or after ``since``."""
+    per_snapshot = _resolve(snapshots, versions)
+    changes: list[Change] = []
+    paired = zip(snapshots, per_snapshot, strict=True)
+    for (_previous, before), (current, after) in pairwise(paired):
+        if current.date < since:
+            continue
+        for name, version in after.items():
+            if name not in before:
+                changes.append(
+                    Change(
+                        kind="added", package=name, version=version, date=current.date
+                    )
+                )
+            elif before[name] != version:
+                changes.append(
+                    Change(
+                        kind="changed",
+                        package=name,
+                        version=version,
+                        previous_version=before[name],
+                        date=current.date,
+                    )
+                )
+        for name in before:
+            if name not in after:
+                changes.append(Change(kind="removed", package=name, date=current.date))
+    changes.sort(key=lambda c: (c.date, c.package, c.kind))
+    return changes

bompage/bompage.py

@@ -0,0 +1,276 @@
+"""Command-line entry point for ``bompage``.
+
+Defines the ``app`` Typer application, the ``build`` command that turns a
+``reports/`` tree (one directory per component) into the constant dashboard
+assets, the ``data/`` JSON tree they consume at runtime and a copy of each
+component's latest raw manifest (spec section 6.1), and the ``push`` command
+that publishes one SBOM into the central repository (spec sections 5 / 9).
+Version string ``1.0.0`` is substituted at release time.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from bompage._git import (
+    DEFAULT_BRANCH,
+    DEFAULT_GIT_EMAIL,
+    DEFAULT_GIT_USER,
+    GitRepoError,
+)
+from bompage.build import build_site
+from bompage.metadata import parse_component, parse_global
+from bompage.prune import prune_report
+from bompage.push import PushError, push_report
+
+__version__ = "1.0.0"
+
+app = typer.Typer(
+    add_completion=False,
+    help="Track SBOM history of N components and build a static dashboard.",
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version_flag: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """bompage command-line interface."""
+
+
+@app.command()
+def build(
+    reports: Annotated[
+        Path,
+        typer.Option(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Directory holding one sub-directory per component.",
+        ),
+    ] = Path("reports"),
+    output: Annotated[
+        Path,
+        typer.Option(help="Directory the static site is written to."),
+    ] = Path("public"),
+    web_dir: Annotated[
+        Path | None,
+        typer.Option(
+            exists=True,
+            file_okay=False,
+            help="Directory of a pre-built dashboard (index.html + assets/) to "
+            "use instead of the packaged one.",
+        ),
+    ] = None,
+    stale_after: Annotated[
+        int,
+        typer.Option(
+            min=0,
+            help="A component with no new report for more than this many days "
+            "is flagged stale.",
+        ),
+    ] = 2,
+    recent_days: Annotated[
+        int,
+        typer.Option(
+            min=1,
+            help="Sliding window (days) for the dashboard's recent-changes feed.",
+        ),
+    ] = 30,
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--metadata",
+            help='Global metadata row "key=value" for the dashboard header; '
+            "repeatable.",
+        ),
+    ] = None,
+    metadata_component: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--metadata-component",
+            help='Per-component metadata row "component:key=value"; repeatable.',
+        ),
+    ] = None,
+) -> None:
+    """Build the static dashboard and its data/ tree from a reports/ tree."""
+    try:
+        global_metadata = parse_global(metadata or [])
+        by_component = parse_component(metadata_component or [])
+    except ValueError as err:
+        raise typer.BadParameter(str(err)) from err
+    data = build_site(
+        reports,
+        output,
+        web_dir=web_dir,
+        stale_after=stale_after,
+        recent_days=recent_days,
+        metadata=global_metadata,
+        component_metadata=by_component,
+    )
+    total_packages = sum(len(c.packages) for c in data.components)
+    stale = [c.name for c in data.components if c.freshness.is_stale]
+    typer.echo(
+        f"{len(data.components)} component(s), {total_packages} package(s), "
+        f"{len(data.drifts)} drift(s) -> {output}"
+    )
+    if stale:
+        typer.echo(f"  stale: {', '.join(stale)}")
+    for component in data.components:
+        typer.echo(f"  {component.name}: {len(component.packages)} packages")
+
+
+@app.command()
+def push(
+    component: Annotated[
+        str,
+        typer.Option(help="Logical component name (one directory under reports/)."),
+    ],
+    sbom: Annotated[
+        Path,
+        typer.Option(
+            exists=True,
+            dir_okay=False,
+            help="Path to the SBOM file produced by the calling job.",
+        ),
+    ],
+    repo: Annotated[
+        str,
+        typer.Option(help="HTTPS clone URL of the central bompage repository."),
+    ],
+    token: Annotated[
+        str,
+        typer.Option(
+            envvar="BOMPAGE_TOKEN",
+            help="Scoped write token for the central repository.",
+        ),
+    ],
+    branch: Annotated[
+        str,
+        typer.Option(help="Target branch in the central repository."),
+    ] = DEFAULT_BRANCH,
+    sbom_version: Annotated[
+        str | None,
+        typer.Option(help="Version suffix for the SBOM file name."),
+    ] = None,
+    sbom_format: Annotated[
+        str | None,
+        typer.Option(help="Informative (spdx | cyclonedx); recorded in the commit."),
+    ] = None,
+    git_user: Annotated[
+        str, typer.Option(help="Commit author name.")
+    ] = DEFAULT_GIT_USER,
+    git_email: Annotated[
+        str, typer.Option(help="Commit author email.")
+    ] = DEFAULT_GIT_EMAIL,
+) -> None:
+    """Publish one SBOM into the central repository.
+
+    Clones the central repo, drops the SBOM, commits only if it changed, pushes.
+    """
+    try:
+        outcome = push_report(
+            component=component,
+            sbom=sbom,
+            repo=repo,
+            token=token,
+            branch=branch,
+            sbom_version=sbom_version or None,
+            sbom_format=sbom_format or None,
+            git_user=git_user,
+            git_email=git_email,
+        )
+    except PushError as err:
+        typer.echo(f"push: {err}", err=True)
+        raise typer.Exit(1) from err
+
+    if outcome == "unchanged":
+        typer.echo(f"push: {component} unchanged, nothing to commit")
+    else:
+        typer.echo(f"push: committed {component}")
+
+
+@app.command()
+def prune(
+    repo: Annotated[
+        str,
+        typer.Option(help="HTTPS clone URL of the central bompage repository."),
+    ],
+    token: Annotated[
+        str,
+        typer.Option(
+            envvar="BOMPAGE_TOKEN",
+            help="Scoped write token for the central repository.",
+        ),
+    ],
+    branch: Annotated[
+        str,
+        typer.Option(help="Target branch in the central repository."),
+    ] = DEFAULT_BRANCH,
+    keep_days: Annotated[
+        int,
+        typer.Option(
+            min=1,
+            help="Snapshots older than this many days are removed; the most "
+            "recent snapshot of each component is always kept.",
+        ),
+    ] = 90,
+    dry_run: Annotated[
+        bool,
+        typer.Option(help="List what would be removed without committing."),
+    ] = False,
+    git_user: Annotated[
+        str, typer.Option(help="Commit author name.")
+    ] = DEFAULT_GIT_USER,
+    git_email: Annotated[
+        str, typer.Option(help="Commit author email.")
+    ] = DEFAULT_GIT_EMAIL,
+) -> None:
+    """Remove SBOM snapshots older than --keep-days from the central repository.
+
+    Clones the central repo, deletes the stale snapshot files in a single
+    ordinary commit (no history rewrite) and pushes (spec section 5.4).
+    """
+    try:
+        outcome, paths = prune_report(
+            repo=repo,
+            token=token,
+            branch=branch,
+            keep_days=keep_days,
+            dry_run=dry_run,
+            git_user=git_user,
+            git_email=git_email,
+        )
+    except GitRepoError as err:
+        typer.echo(f"prune: {err}", err=True)
+        raise typer.Exit(1) from err
+
+    if outcome == "nothing":
+        typer.echo(f"prune: nothing older than {keep_days} days")
+        return
+    if outcome == "would-prune":
+        for path in paths:
+            typer.echo(f"  {path}")
+        typer.echo(f"prune: {len(paths)} file(s) would be removed (dry run)")
+        return
+    components = len({Path(path).parent.name for path in paths})
+    typer.echo(
+        f"prune: removed {len(paths)} snapshot(s) across {components} component(s)"
+    )