mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-14 17:10:59 +01:00
Krzysztof kuhy Rudnicki
2a2f18ca56
"Are we on the newest version?" was not mechanically answerable across these repos: constraint styles had drifted per-ecosystem and a caret range is "newest-compatible" by definition, which gives a checker nothing to compare. This gate makes it answerable and then enforces the answer. Checks two things at once -- that every dependency carries an exact pin, and that the pin equals its registry's latest STABLE release -- across pub.dev, PyPI, npm, crates.io, the Go proxy, kuhyx/utils git tags, and the Flutter / Node / Python toolchains. Three deliberate design points: * Pre-releases are rejected per-ecosystem, because every ecosystem leaks them differently and each leak fails GREEN. npm lets a maintainer point `dist-tags.latest` at an rc; crates.io's `max_version` includes them; PyPI's legacy `info.version` includes yanked releases. Unit-tested with fixtures, since an end-to-end run cannot surface a wrong "up to date". * Offline, the gate serves an expired cache entry and PASSES with a DEGRADED banner (exit 3 only under --strict, which is CI). `--no-verify` is banned here, so a hook that hard-failed offline would leave no way to commit at all. * The allowlist has two entry classes. `blocked_by: transitive:<pkg>@<ver>` is a predicate that clears itself when upstream moves and must NOT carry a date; everything else is discretionary and requires `expires`, capped at 90 days. Exact pins plus latest-everywhere is provably unsatisfiable when a dependency internally constrains a shared transitive, and expiring the predicate class on a calendar would turn the gate red for a reason no commit could fix. An entry with nothing left to excuse is itself an error. One hook id, one shim, one shared implementation -- always delegating, so it cannot fork the way the 250-line cap forked into four ids, two of which were independent reimplementations. 256 tests, 100% branch coverage on every module of the gate. Also adds the workflow that runs them, which incidentally gives md_naming's 71 tests their first CI run. Not yet installed in any repo: a repo that gets the gate before its deps are bumped is instantly and permanently red, so the gate and the upgrade land together, per repo. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
93 lines
2.9 KiB
Python
93 lines
2.9 KiB
Python
"""Value types passed between the parsers, the registries and the report.
|
|
|
|
Frozen dataclasses on purpose: a parser hands a `Dep` to a registry resolver
|
|
and gets a `Finding` back, and nothing in between may mutate what was read off
|
|
disk. `Severity` is what the exit code is derived from, so the mapping from
|
|
"what we noticed" to "what the shell sees" lives in one place.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
from enum import Enum
|
|
from pathlib import Path
|
|
|
|
|
|
class Severity(str, Enum):
|
|
"""Why a dependency is being reported."""
|
|
|
|
STALE = "stale" # pinned below latest stable
|
|
UNPINNED = "unpinned" # no exact version to compare against
|
|
LOCK_MISMATCH = "lock-mismatch" # manifest pin != lockfile resolved version
|
|
OVERRIDE = "override" # dependency_overrides / resolutions entry
|
|
UNKNOWN = "unknown" # latest could not be determined at all
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Dep:
|
|
"""One declared dependency, as written in a manifest."""
|
|
|
|
ecosystem: str
|
|
name: str
|
|
constraint: str
|
|
path: Path
|
|
line: int
|
|
pinned: str | None = None # exact version, when the constraint is one
|
|
locked: str | None = None # version the lockfile resolved to
|
|
dev: bool = False
|
|
caret_ok: bool = False # Q13 carve-out: a range is legal here
|
|
override: bool = False
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Finding:
|
|
"""A dependency that fails the gate, or is excused by the allowlist."""
|
|
|
|
dep: Dep
|
|
severity: Severity
|
|
latest: str | None
|
|
detail: str = ""
|
|
excused: str | None = None # allowlist reason, when one applies
|
|
|
|
@property
|
|
def label(self) -> str:
|
|
"""`ecosystem:name` — the key the allowlist matches on."""
|
|
return f"{self.dep.ecosystem}:{self.dep.name}"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Exception_:
|
|
"""One parsed allowlist entry.
|
|
|
|
Named with a trailing underscore so it cannot shadow the builtin in the
|
|
modules that import it; `blocked_by` carries the whole semantics split
|
|
between the predicate and discretionary classes.
|
|
"""
|
|
|
|
ecosystem: str
|
|
package: str
|
|
pinned: str
|
|
reason: str
|
|
blocked_by: str
|
|
latest_known: str | None = None
|
|
expires: str | None = None
|
|
source: Path | None = None
|
|
|
|
@property
|
|
def transitive(self) -> bool:
|
|
"""True when this is a predicate entry that never expires on a date."""
|
|
from dep_freshness._tables import TRANSITIVE_PREFIX
|
|
|
|
return self.blocked_by.startswith(TRANSITIVE_PREFIX)
|
|
|
|
@property
|
|
def blocker(self) -> tuple[str, str] | None:
|
|
"""`(package, version)` this entry claims is holding the pin back."""
|
|
from dep_freshness._tables import TRANSITIVE_PREFIX
|
|
|
|
if not self.transitive:
|
|
return None
|
|
rest = self.blocked_by[len(TRANSITIVE_PREFIX):]
|
|
name, _, version = rest.partition("@")
|
|
return (name.strip(), version.strip())
|