stackvitals 0.1.0__py3-none-any.whl

stackvitals/deps/lockfiles.py

@@ -0,0 +1,198 @@
+"""Packages and versions from the lockfiles projects commit: npm's package-lock, and pip, uv, Poetry and Pipenv files."""
+import json
+import re
+import tomllib
+from collections import deque
+from pathlib import Path
+from urllib.parse import urlparse
+
+from mergescout.signals.bumps import _norm
+
+SUPPORTED = "package-lock.json, npm-shrinkwrap.json, requirements*.txt, uv.lock, poetry.lock, Pipfile.lock"
+REGISTRY_HOSTS = {"npm": ("registry.npmjs.org", "registry.yarnpkg.com"), "pypi": ("pypi.org", "files.pythonhosted.org")}
+REQUIREMENT = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*(?:==\s*([^\s,;]+))?")
+
+
+def read_lockfile(path: Path) -> list[tuple[str, str, str | None]]:
+    """(ecosystem, name, version) for every package the file pins, sorted; a file it can't read is a clear error."""
+    path = Path(path)
+    return parse_lockfile(path.name, path.read_text(encoding="utf-8"))
+
+
+def is_lockfile(filename: str) -> bool:
+    name = filename.rsplit("/", 1)[-1].lower()
+    return name in ("package-lock.json", "npm-shrinkwrap.json", "uv.lock", "poetry.lock", "pipfile.lock") or (
+        name.startswith("requirements") and name.endswith(".txt"))
+
+
+def parse_lockfile(filename: str, text: str) -> list[tuple[str, str, str | None]]:
+    name = filename.rsplit("/", 1)[-1].lower()
+    if name in ("package-lock.json", "npm-shrinkwrap.json"):
+        found = _npm(json.loads(text))
+    elif name.endswith(".txt"):
+        found = _requirements(text)
+    elif name in ("uv.lock", "poetry.lock"):
+        found = {("pypi", _norm("pypi", p["name"]), p.get("version")) for p in tomllib.loads(text).get("package") or []
+                 if p.get("name") and not _local((p.get("source") or {}))}
+    elif name == "pipfile.lock":
+        doc = json.loads(text)
+        found = {("pypi", _norm("pypi", n), (v.get("version") or "").lstrip("=") or None)
+                 for section in ("default", "develop") for n, v in (doc.get(section) or {}).items()}
+    else:
+        raise ValueError(f"{filename} isn't a lockfile this reads yet; it reads {SUPPORTED}.")
+    return sorted(found, key=lambda t: (t[0], t[1], t[2] or ""))
+
+
+def _local(source: dict) -> bool:
+    # uv lists the project itself and path dependencies; they aren't registry packages.
+    return any(k in source for k in ("editable", "virtual", "directory", "path"))
+
+
+def _npm(doc: dict) -> set:
+    if isinstance(doc.get("packages"), dict):
+        # v2/v3: "node_modules/a/node_modules/b" is package b, nested under a; an alias ("react": "npm:other@1") names the real one.
+        return {("npm", _npm_name(key, v), v.get("version")) for key, v in doc["packages"].items()
+                if key and "node_modules/" in key and isinstance(v, dict) and not v.get("link")}
+    found = set()
+
+    def walk(deps: dict) -> None:
+        for n, v in (deps or {}).items():
+            found.add(("npm", *_v1_alias(n, (v or {}).get("version"))))
+            walk((v or {}).get("dependencies"))
+    walk(doc.get("dependencies"))
+    return found
+
+
+def _v1_alias(name: str, version) -> tuple[str, str | None]:
+    # v1 writes an alias as "version": "npm:real-name@1.2.3".
+    if isinstance(version, str) and version.startswith("npm:") and "@" in version[5:]:
+        real, _, ver = version[4:].rpartition("@")
+        return real, ver
+    return name, version
+
+
+def _npm_name(key: str, entry: dict) -> str:
+    name = entry.get("name")
+    return name if isinstance(name, str) and name else key.rsplit("node_modules/", 1)[1]
+
+
+def _host(url: str) -> str:
+    parsed = urlparse(url.removeprefix("git+"))
+    return parsed.hostname or (url.split(":", 1)[0] if ":" in url else "a local path")
+
+
+def foreign_sources(filename: str, text: str) -> dict[tuple[str, str], str]:
+    """Packages installed from somewhere other than the public registry (a git repo, a tarball URL, another index), with
+    where from: evidence about the registry package of that name doesn't describe them."""
+    name, out = filename.rsplit("/", 1)[-1].lower(), {}
+    if name in ("package-lock.json", "npm-shrinkwrap.json"):
+        doc = json.loads(text)
+        if isinstance(doc.get("packages"), dict):
+            entries = [(_npm_name(k, v), v) for k, v in doc["packages"].items()
+                       if k and "node_modules/" in k and isinstance(v, dict) and not v.get("link")]
+        else:
+            entries = []
+
+            def walk(deps):
+                for n, v in (deps or {}).items():
+                    entries.append((_v1_alias(n, (v or {}).get("version"))[0], v or {}))
+                    walk((v or {}).get("dependencies"))
+            walk(doc.get("dependencies"))
+        for pkg, v in entries:
+            url = v.get("resolved")
+            if isinstance(url, str) and url and _host(url) not in REGISTRY_HOSTS["npm"]:
+                out[("npm", pkg)] = _host(url)
+    elif name in ("uv.lock", "poetry.lock"):
+        for p in tomllib.loads(text).get("package") or []:
+            src = p.get("source") or {}
+            if not p.get("name") or _local(src):
+                continue
+            url = src.get("git") or src.get("url") or src.get("registry") or ""
+            if isinstance(url, str) and url and (src.get("type") or "git") != "directory" and _host(url) not in REGISTRY_HOSTS["pypi"]:
+                out[("pypi", _norm("pypi", p["name"]))] = _host(url)
+    elif name == "pipfile.lock":
+        doc = json.loads(text)
+        for section in ("default", "develop"):
+            for n, v in (doc.get(section) or {}).items():
+                if isinstance(v, dict) and isinstance(v.get("git") or v.get("file"), str):
+                    out[("pypi", _norm("pypi", n))] = _host(v.get("git") or v.get("file"))
+    return out
+
+
+def _requirements(text: str) -> set:
+    found = set()
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip()
+        # Options (-e, -r, --hash) and URLs aren't registry packages.
+        if not line or line.startswith("-") or "://" in line:
+            continue
+        m = REQUIREMENT.match(line)
+        if m:
+            found.add(("pypi", _norm("pypi", m.group(1)), m.group(2)))
+    return found
+
+
+def dependency_paths(filename: str, text: str, targets: set[str]) -> dict[str, list[str]]:
+    """The shortest chain from a direct dependency to each target package (["express", "qs", "side-channel"]), for
+    lockfiles that record the graph and which packages are direct (npm v2/v3, uv); none for the rest (poetry.lock
+    doesn't say which are direct, so a guessed chain could name the wrong one) or a file that can't be read."""
+    name = filename.rsplit("/", 1)[-1].lower()
+    npm = name in ("package-lock.json", "npm-shrinkwrap.json")
+    try:
+        if npm:
+            roots, children = _npm_graph(json.loads(text))
+        elif name == "uv.lock":
+            roots, children = _uv_graph(tomllib.loads(text))
+        else:
+            return {}
+    except (ValueError, TypeError, AttributeError):
+        return {}
+    want = set(targets) if npm else {_norm("pypi", t) for t in targets}
+    found, queue, seen = {}, deque((r, [label]) for r, label in roots), set()
+    while queue and len(found) < len(want):
+        node, path = queue.popleft()
+        if node in seen:
+            continue
+        seen.add(node)
+        if path[-1] in want and path[-1] not in found:
+            found[path[-1]] = path
+        queue.extend((child, path + [label]) for child, label in children.get(node, ()))
+    return found
+
+
+def _npm_graph(doc: dict) -> tuple[list, dict]:
+    pkgs = doc.get("packages")
+    if not isinstance(pkgs, dict):
+        return [], {}
+
+    def deps(entry: dict) -> list[str]:
+        return [n for key in ("dependencies", "optionalDependencies", "devDependencies", "peerDependencies")
+                for n in (entry.get(key) or {})]
+
+    def resolve(parent: str, child: str) -> str | None:
+        # Node looks in the parent's own node_modules, then each folder above it, then the top.
+        here = parent
+        while True:
+            key = f"{here}/node_modules/{child}" if here else f"node_modules/{child}"
+            if key in pkgs:
+                return key
+            if not here:
+                return None
+            here = here.rsplit("/node_modules/", 1)[0] if "/node_modules/" in here else ""
+    children = {key: [(k, _npm_name(k, pkgs[k])) for c in deps(v) if (k := resolve(key, c))]
+                for key, v in pkgs.items() if isinstance(v, dict)}
+    return children.get("", []), children
+
+
+def _uv_graph(doc: dict) -> tuple[list, dict]:
+    packages = [p for p in doc.get("package") or [] if p.get("name")]
+    edges = {_norm("pypi", p["name"]): [_norm("pypi", d["name"]) for key in ("dependencies",)
+                                         for d in p.get(key) or [] if d.get("name")]
+             + [_norm("pypi", d["name"]) for group in ("optional-dependencies", "dev-dependencies")
+                for ds in (p.get(group) or {}).values() for d in ds if d.get("name")]
+             for p in packages}
+    # The project's own entries (a local source) name its direct dependencies.
+    local = [_norm("pypi", p["name"]) for p in packages if _local(p.get("source") or {})]
+    roots = [d for proj in local for d in edges.get(proj, [])]
+    children = {n: [(d, d) for d in ds if d in edges] for n, ds in edges.items()}
+    return [(r, r) for r in roots if r in edges], children

stackvitals/deps/lookalike.py

@@ -0,0 +1,80 @@
+"""Names that imitate a popular package (typosquats): one edit away, or the same letters with other separators. The
+popular names are the ones the dependency evidence already covers (the crawl's most-used and most-upgraded packages)."""
+import re
+
+MIN_LENGTH = 5  # shorter popular names have too many real neighbours ("chalk", "chai")
+
+
+def _norm(eco: str, name: str) -> str:
+    name = name.lower()
+    return re.sub(r"[-_.]+", "-", name) if eco == "pypi" else name
+
+
+def _one_edit(a: str, b: str) -> bool:
+    """True when b is a with one letter added, dropped, changed, or two neighbours swapped."""
+    if a == b or abs(len(a) - len(b)) > 1:
+        return False
+    if len(a) == len(b):
+        diff = [i for i in range(len(a)) if a[i] != b[i]]
+        return len(diff) == 1 or (len(diff) == 2 and diff[1] == diff[0] + 1 and a[diff[0]] == b[diff[1]] and a[diff[1]] == b[diff[0]])
+    short, long_ = (a, b) if len(a) < len(b) else (b, a)
+    i = 0
+    while i < len(short) and short[i] == long_[i]:
+        i += 1
+    return short[i:] == long_[i + 1:]
+
+
+def lookalike(eco: str, name: str, popular: dict[str, set[str]]) -> str | None:
+    """The popular package `name` imitates, or None (a popular name itself, a scoped one, or nothing close)."""
+    names = {_norm(eco, p): p for p in popular.get(eco) or ()}
+    mine = _norm(eco, name)
+    if not names or mine in names or mine.startswith("@"):
+        return None
+    bare = re.sub(r"[-_.]", "", mine)
+    for norm, original in sorted(names.items()):
+        if len(norm) < MIN_LENGTH or norm.startswith("@"):
+            continue
+        if _one_edit(norm, mine) or (bare == re.sub(r"[-_.]", "", norm) and bare != mine):
+            return original
+    return None
+
+
+# On OpenSSF's malicious look-alikes the weekly downloads were 1 to 75; legitimate look-alikes of popular names had
+# 823,598 to 192 million (bench/accuracy/deps). Under this, a look-alike is flagged.
+LOW_DOWNLOADS = 1000
+
+
+NPM_STATS, PYPI_STATS = "https://api.npmjs.org", "https://pypistats.org"
+
+
+def weekly_downloads(eco: str, name: str, client) -> int | None:
+    """Last week's downloads from the registry's free stats (npm's API, pypistats for PyPI); None when unknown."""
+    import httpx
+    url = (f"{NPM_STATS}/downloads/point/last-week/{name}" if eco == "npm"
+           else f"{PYPI_STATS}/api/packages/{_norm('pypi', name)}/recent" if eco == "pypi" else None)
+    if not url or client is None:
+        return None
+    try:
+        resp = client.get(url)
+        body = resp.json() if resp.status_code == 200 else {}
+    except (httpx.HTTPError, ValueError):
+        return None
+    value = body.get("downloads") if eco == "npm" else (body.get("data") or {}).get("last_week")
+    return value if isinstance(value, int) else None
+
+
+def judge(eco: str, name: str, popular: dict[str, set[str]], client) -> dict | None:
+    """A verdict for a package a PR adds whose name imitates a popular one and that few people use, else None."""
+    target = lookalike(eco, name, popular)
+    if not target:
+        return None
+    downloads = weekly_downloads(eco, name, client)
+    if downloads is not None and downloads >= LOW_DOWNLOADS:
+        return None
+    if downloads is None:
+        # Without the download count the name alone false-alarms on real neighbours (preact and react): a note, not an alarm.
+        return {"verdict": "monitor", "reasons": [f"Its name is one edit from the popular {target}, and its downloads "
+                                                 f"couldn't be checked. Check you meant {target}."]}
+    return {"verdict": "investigate", "reasons": [f"Its name is one edit from the popular {target} and it has "
+                                                 f"{downloads:,} downloads last week: a common way to slip in a malicious "
+                                                 f"package. Check you meant {target}."]}

stackvitals/deps/reach.py

@@ -0,0 +1,59 @@
+"""Reachability from govulncheck (Go's own free scanner, run in the team's workflow): for each advisory, whether the code
+only requires the module, imports the vulnerable package, or calls the vulnerable function, with the call path."""
+import json
+
+LEVELS = ("required", "imported", "called")
+
+
+def _short(frame: dict) -> str:
+    # "example.com/app/web" + "render" reads as "web.render"; the program's entry stays "main".
+    fn = frame.get("function") or ""
+    pkg = (frame.get("package") or "").rsplit("/", 1)[-1]
+    if frame.get("receiver"):
+        fn = f"{frame['receiver'].lstrip('*')}.{fn}"
+    return fn if fn == "main" or not pkg else f"{pkg}.{fn}"
+
+
+def read_govulncheck(text: str) -> dict:
+    """govulncheck -format json output: each advisory's deepest reach, its fixing version, aliases and call path."""
+    osv, found, scanner = {}, {}, None
+    for line in _objects(text):
+        if isinstance(line.get("config"), dict):
+            c = line["config"]
+            scanner = f"{c.get('scanner_name', 'govulncheck')} {c.get('scanner_version', '')}".strip()
+        elif isinstance(line.get("osv"), dict) and line["osv"].get("id"):
+            osv[line["osv"]["id"]] = line["osv"]
+        elif isinstance(line.get("finding"), dict) and line["finding"].get("osv"):
+            f = line["finding"]
+            trace = [t for t in f.get("trace") or [] if isinstance(t, dict)]
+            top = trace[0] if trace else {}
+            reach = "called" if top.get("function") else "imported" if top.get("package") else "required"
+            mine = found.setdefault(f["osv"], {"id": f["osv"], "reach": reach, "fixed": f.get("fixed_version"),
+                                                "module": top.get("module"), "version": top.get("version"), "path": []})
+            if LEVELS.index(reach) >= LEVELS.index(mine["reach"]):
+                mine["reach"] = reach
+                if reach == "called":
+                    mine["path"] = [_short(t) for t in reversed(trace) if t.get("function")]
+    findings = []
+    for i, f in sorted(found.items()):
+        o = osv.get(i) or {}
+        findings.append({**f, "aliases": list(o.get("aliases") or []), "summary": str(o.get("summary") or "")[:200]})
+    return {"scanner": scanner, "findings": findings,
+            "counts": {level: sum(1 for f in findings if f["reach"] == level) for level in LEVELS}}
+
+
+def _objects(text: str):
+    # govulncheck writes indented JSON objects one after another; read them whole, skipping anything else.
+    decoder, at = json.JSONDecoder(), 0
+    while at < len(text):
+        start = text.find("{", at)
+        if start < 0:
+            return
+        try:
+            obj, end = decoder.raw_decode(text, start)
+        except ValueError:
+            at = start + 1
+            continue
+        at = end
+        if isinstance(obj, dict):
+            yield obj

stackvitals/deps/release.py

@@ -0,0 +1,110 @@
+"""Signs a new release may be compromised, before any advisory exists: it is only hours old, it adds an install script,
+it pulls in new dependencies, or the signed record of where it was built is gone. Compared with the version it
+replaces, from the registries' own metadata. A sign is a reason to look first, never a block."""
+from datetime import datetime, timedelta
+from urllib.parse import quote
+
+NPM = "https://registry.npmjs.org"
+PYPI = "https://pypi.org"
+DEPS_DEV = "https://api.deps.dev/v3/systems"
+HOOKS = ("preinstall", "install", "postinstall")
+# 2025-26 compromised releases stayed up from 40 minutes to a few hours; a release younger than this gets a sign.
+COOLDOWN = timedelta(hours=48)
+MAX_PACKAGES = 30
+
+
+def _key(version: str) -> list:
+    import re
+    return [(0, int(p)) if p.isdigit() else (1, p) for p in re.split(r"[.\-+_]", str(version)) if p]
+
+
+def _get(client, url: str) -> dict | None:
+    try:
+        r = client.get(url)
+    except Exception:  # noqa: BLE001 - a registry hiccup means no sign, never a failed check
+        return None
+    return r.json() if r.status_code == 200 else None
+
+
+def _age(published: str | None, now: datetime) -> str | None:
+    if not published:
+        return None
+    when = datetime.fromisoformat(published.replace("Z", "+00:00"))
+    hours = (now - when).total_seconds() / 3600
+    if 0 <= hours < COOLDOWN.total_seconds() / 3600:
+        n = max(1, round(hours))
+        return (f"Released {n} hour{'' if n == 1 else 's'} ago: compromised releases are usually found and pulled within hours, "
+                "so a few days' wait is safer.")
+    return None
+
+
+def npm_signs(client, name: str, old: str | None, new: str, now: datetime) -> list[str]:
+    path = quote(name, safe="@")
+    after = _get(client, f"{NPM}/{path}/{quote(new)}")
+    if not after:
+        return []
+    signs = []
+    meta = _get(client, f"{DEPS_DEV}/npm/packages/{quote(name, safe='')}/versions/{quote(new, safe='')}") or {}
+    if age := _age(meta.get("publishedAt"), now):
+        signs.append(age)
+    before = _get(client, f"{NPM}/{path}/{quote(old)}") if old else None
+    hooks = [h for h in HOOKS if (after.get("scripts") or {}).get(h)]
+    if before is not None:
+        added = [h for h in hooks if not (before.get("scripts") or {}).get(h)]
+        if added:
+            signs.append(f"Adds an install script ({', '.join(added)}) that {old} didn't have: it runs when the package installs.")
+        new_deps = sorted(set(after.get("dependencies") or {}) - set(before.get("dependencies") or {}))
+        if new_deps:
+            signs.append(f"New dependencies since {old}: {', '.join(new_deps[:5])}{' and more' if len(new_deps) > 5 else ''}.")
+        if (before.get("dist") or {}).get("attestations") and not (after.get("dist") or {}).get("attestations"):
+            signs.append(f"{old} carried build provenance (a signed record of where it was built); {new} doesn't.")
+    return signs
+
+
+def _pypi_release(client, name: str, version: str) -> dict | None:
+    return _get(client, f"{PYPI}/pypi/{quote(name)}/{quote(version)}/json")
+
+
+def _pypi_provenance(client, name: str, version: str, doc: dict) -> bool | None:
+    files = doc.get("urls") or []
+    if not files:
+        return None
+    try:
+        r = client.get(f"{PYPI}/integrity/{quote(name)}/{quote(version)}/{quote(files[0]['filename'])}/provenance")
+    except Exception:  # noqa: BLE001
+        return None
+    return r.status_code == 200
+
+
+def pypi_signs(client, name: str, old: str | None, new: str, now: datetime) -> list[str]:
+    after = _pypi_release(client, name, new)
+    if not after:
+        return []
+    signs = []
+    times = sorted(u.get("upload_time_iso_8601") for u in after.get("urls") or [] if u.get("upload_time_iso_8601"))
+    if age := _age(times[0] if times else None, now):
+        signs.append(age)
+    before = _pypi_release(client, name, old) if old else None
+    if before is not None:
+        def names(doc):
+            import re
+            return {re.split(r"[\s<>=!~;\[(]", r, 1)[0].lower() for r in (doc.get("info") or {}).get("requires_dist") or []
+                    if "extra ==" not in r}
+        new_deps = sorted(names(after) - names(before))
+        if new_deps:
+            signs.append(f"New dependencies since {old}: {', '.join(new_deps[:5])}{' and more' if len(new_deps) > 5 else ''}.")
+        if _pypi_provenance(client, name, old, before) and _pypi_provenance(client, name, new, after) is False:
+            signs.append(f"{old} carried build provenance (a signed record of where it was built); {new} doesn't.")
+    return signs
+
+
+def release_signs(client, ecosystem: str, name: str, old_versions: list[str], new_versions: list[str],
+                  now: datetime) -> list[str]:
+    """Signs for the newest version a change installs, against the newest version it replaces."""
+    if not new_versions or ecosystem not in ("npm", "pypi"):
+        return []
+    new = max(new_versions, key=_key)
+    old = max(old_versions, key=_key) if old_versions else None
+    if old and _key(old) >= _key(new):
+        return []  # a downgrade or the same version: nothing new arrived
+    return (npm_signs if ecosystem == "npm" else pypi_signs)(client, name, old, new, now)

stackvitals/deps/runtimes.py

@@ -0,0 +1,161 @@
+"""The language runtimes a repo builds and runs on (Node.js, Python, PHP, Ruby, Go), read from its version files,
+Dockerfiles and workflow setup steps, checked against endoflife.date: a release line out of support gets no security
+fixes, and a pinned patch older than the newest one misses the fixes since. Runtime flaws (PHP's in October 2026) are
+not package advisories, so lockfile scans never see them."""
+import json
+import re
+
+EOL_API = "https://endoflife.date/api"
+PRODUCTS = {"node": "nodejs", "python": "python", "php": "php", "ruby": "ruby", "go": "go", "debian": "debian", "ubuntu": "ubuntu",
+            "alpine": "alpine-linux"}
+FILES = re.compile(r"(^|/)(\.nvmrc|\.node-version|\.python-version|\.php-version|\.ruby-version|\.tool-versions|runtime\.txt"
+                   r"|go\.mod|package\.json|composer\.json|Dockerfile[^/]*|\.github/workflows/[^/]+\.ya?ml)$")
+SKIP = re.compile(r"(^|/)(node_modules|vendor|third_party|testdata|fixtures?|examples?)/")
+MAX_FILES = 40
+VERSION = r"v?(\d+(?:\.\d+){0,2})"
+SETUP = {"node": re.compile(rf"node-version:\s*['\"]?{VERSION}"), "python": re.compile(rf"python-version:\s*['\"]?{VERSION}"),
+         "php": re.compile(rf"php-version:\s*['\"]?{VERSION}"), "ruby": re.compile(rf"ruby-version:\s*['\"]?{VERSION}"),
+         "go": re.compile(rf"go-version:\s*['\"]?{VERSION}")}
+MATRIX_KEYS = {"php": "php", "php-version": "php", "php-versions": "php", "python": "python", "python-version": "python",
+               "python-versions": "python", "node": "node", "node-version": "node", "node-versions": "node", "ruby": "ruby",
+               "ruby-version": "ruby", "go": "go", "go-version": "go"}
+MATRIX = re.compile(r"(?mi)^\s*(" + "|".join(re.escape(k) for k in MATRIX_KEYS) + r")\s*:\s*(?:\[([^\]\n]*)\]|\n((?:[ \t]*-[ \t]*['\"]?[\d.]+['\"]?[ \t]*\n)+))")
+IMAGE = re.compile(rf"(?mi)^\s*FROM\s+(?:[\w./-]+/)?(node|python|php|ruby|golang)[:@]{VERSION}")
+# Base operating system images, by version or codename (endoflife.date's debian, ubuntu and alpine).
+DEBIAN = {"stretch": "9", "buster": "10", "bullseye": "11", "bookworm": "12", "trixie": "13"}
+UBUNTU = {"bionic": "18.04", "focal": "20.04", "jammy": "22.04", "noble": "24.04", "oracular": "24.10", "plucky": "25.04"}
+CODENAMES = {**DEBIAN, **UBUNTU}
+OS_IMAGE = re.compile(r"(?mi)^\s*FROM\s+(?:--platform=\S+\s+)?(?:[\w./-]+/)?(debian|ubuntu|alpine)[:]([\w.]+)")
+SUFFIX = re.compile(r"(?mi)^\s*FROM\s+(?:--platform=\S+\s+)?(?:[\w./-]+/)?(?:node|python|php|ruby|golang)[:][\w.]*?-(?:slim-)?("
+                    + "|".join(CODENAMES) + r")\b")
+
+
+def wanted(path: str) -> bool:
+    return bool(FILES.search(path)) and not SKIP.search(path)
+
+
+def detect(files: dict[str, str]) -> list[dict]:
+    """Every runtime version a repo names, with where: [{"runtime", "version", "file"}]; versions that aren't a number
+    ("lts/*", ">=18") are left out rather than guessed."""
+    found = []
+
+    def add(runtime, version, file, use="runs"):
+        # "runs": what the project runs on; "tests": a test matrix, where old lines are often kept on purpose.
+        if version and re.fullmatch(r"\d+(\.\d+){0,2}", version):
+            found.append({"runtime": runtime, "version": version, "file": file, "use": use})
+    for path, text in files.items():
+        name = path.rsplit("/", 1)[-1]
+        first = text.strip().splitlines()[0].strip() if text.strip() else ""
+        if name in (".nvmrc", ".node-version"):
+            add("node", first.lstrip("v"), path)
+        elif name == ".python-version":
+            add("python", first, path)
+        elif name == ".php-version":
+            add("php", first, path)
+        elif name == ".ruby-version":
+            add("ruby", first.removeprefix("ruby-"), path)
+        elif name == "runtime.txt":
+            m = re.match(rf"(python|php|ruby)-{VERSION}", first)
+            if m:
+                add(m.group(1), m.group(2), path)
+        elif name == ".tool-versions":
+            for line in text.splitlines():
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] in ("nodejs", "python", "php", "ruby", "golang"):
+                    add({"nodejs": "node", "golang": "go"}.get(parts[0], parts[0]), parts[1], path)
+        elif name == "go.mod":
+            m = re.search(r"(?m)^go\s+(\d+\.\d+(?:\.\d+)?)", text)
+            if m:
+                add("go", m.group(1), path)
+        elif name.startswith("Dockerfile"):
+            for runtime, version in IMAGE.findall(text):
+                add({"golang": "go"}.get(runtime.lower(), runtime.lower()), version, path)
+            # The operating system under the image: debian:bookworm, ubuntu:22.04, alpine:3.18, or a language image's
+            # suffix (python:3.11-slim-bookworm). An end-of-life base gets no security fixes for its packages.
+            for os_name, tag in OS_IMAGE.findall(text):
+                version = CODENAMES.get(tag.split("-")[0].lower(), tag.split("-")[0])
+                add(os_name.lower(), version, path)
+            for codename in SUFFIX.findall(text):
+                add("debian" if codename.lower() in DEBIAN else "ubuntu", CODENAMES[codename.lower()], path)
+        elif path.startswith(".github/workflows/"):
+            for runtime, pattern in SETUP.items():
+                for version in pattern.findall(text):
+                    add(runtime, version, path)
+            # A matrix names the versions: "php: [8.2, 8.3]" or a "- '3.12'" list under "python:".
+            for key, inline, block in MATRIX.findall(text):
+                runtime = MATRIX_KEYS[key.lower()]
+                for version in re.findall(r"['\"]?(\d+(?:\.\d+){0,2})['\"]?", inline or block):
+                    add(runtime, version, path, "tests")
+        elif name == "package.json":
+            try:
+                engine = str(((json.loads(text) or {}).get("engines") or {}).get("node") or "")
+            except ValueError:
+                engine = ""
+            m = re.fullmatch(rf"\s*[\^~]?{VERSION}(\.x)?\s*", engine)
+            if m:
+                add("node", m.group(1), path)
+    seen, out = set(), []
+    for f in found:
+        k = (f["runtime"], f["version"], f["file"], f["use"])
+        if k not in seen:
+            seen.add(k)
+            out.append(f)
+    return out
+
+
+def _cycle(product: str, version: str, cycles: list[dict]) -> dict | None:
+    # The release line a version belongs to: "8.3" for PHP 8.3.4, "20" for Node 20.11, "3.11" for Python 3.11.2.
+    parts = version.split(".")
+    for n in (2, 1):
+        name = ".".join(parts[:n])
+        hit = next((c for c in cycles if str(c.get("cycle")) == name), None)
+        if hit:
+            return hit
+    return None
+
+
+def judge(found: list[dict], cycles: dict[str, list[dict]], today: str) -> list[dict]:
+    """For each runtime version found: its release line, whether that line is out of support (and since when), and
+    the newest patch when the repo pins an older one."""
+    out = []
+    for f in found:
+        product = PRODUCTS[f["runtime"]]
+        c = _cycle(product, f["version"], cycles.get(product) or [])
+        if not c:
+            out.append({**f, "status": "unknown"})
+            continue
+        eol = c.get("eol")
+        ended = eol is True or (isinstance(eol, str) and eol <= today)
+        latest = str(c.get("latest") or "")
+        pinned = f["version"].count(".") >= 2  # a full version; "8.3" or "20" installs the newest patch
+        behind = pinned and latest and _key(f["version"]) < _key(latest)
+        out.append({**f, "cycle": str(c.get("cycle")), "eol": eol if isinstance(eol, str) else None, "latest": latest or None,
+                    "latest_date": c.get("latestReleaseDate"),
+                    "status": "end of life" if ended else "behind the newest patch" if behind else "supported"})
+    return out
+
+
+def _key(version: str) -> list:
+    return [int(p) if p.isdigit() else 0 for p in version.split(".")]
+
+
+def runtimes(api, ref: str, client) -> list[dict]:
+    """Read the files that name runtimes at `ref` (one tree read, at most 40 files) and judge each version."""
+    tree = api._get(f"/repos/{api.repo}/git/trees/{ref}", {"recursive": "1"})
+    paths = [t["path"] for t in tree.get("tree") or [] if t.get("type") == "blob" and wanted(t["path"])][:MAX_FILES]
+    files = {}
+    for p in paths:
+        try:
+            files[p] = api.file(p, ref).decode("utf-8", "replace")
+        except Exception:  # noqa: BLE001 - one unreadable file is skipped
+            continue
+    found = detect(files)
+    cycles = {}
+    for product in sorted({PRODUCTS[f["runtime"]] for f in found}):
+        try:
+            r = client.get(f"{EOL_API}/{product}.json")
+            cycles[product] = r.json() if r.status_code == 200 else []
+        except Exception:  # noqa: BLE001
+            cycles[product] = []
+    from datetime import date
+    return judge(found, cycles, date.today().isoformat())