limbowatch 0.1.0a1__py3-none-any.whl

limbowatch/__init__.py

@@ -0,0 +1,3 @@
+"""Limbowatch: track published security advisories stuck in limbo."""
+
+__version__ = "0.1.0a1"

limbowatch/classify.py

@@ -0,0 +1,77 @@
+"""Classify an advisory from its facts. Pure: no I/O.
+
+Facts are independent (repo advisory, review, OSV, CVE, NVD) and change in any order, so the
+status is recomputed from scratch every time (PHASE0_PLAN §3).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+
+from limbowatch.ecosystems import reviewable
+from limbowatch.models import GITHUB_CNA, Assessment, CveLabel, Facts, RepoAdvisory, Status
+
+
+def status(f: Facts) -> Status:
+    if f.reviewed or f.in_osv:
+        return Status.REVIEWED
+    if f.repo_state == "withdrawn":
+        return Status.WITHDRAWN
+    if f.repo_state != "published":
+        return Status.NOT_PUBLISHED
+    if f.duplicate_of:
+        return Status.DUPLICATE
+    return Status.LIMBO
+
+
+def cve_label(f: Facts) -> CveLabel:
+    if f.cited_cve:
+        if f.cited_cve_state == "PUBLISHED":
+            return CveLabel.PUBLISHED_CITED
+        if f.cited_cve_state == "RESERVED":
+            return CveLabel.RESERVED
+        return CveLabel.OTHER
+    if f.uncited_cves:
+        return CveLabel.PUBLISHED_UNCITED
+    return CveLabel.NONE
+
+
+def assess(adv: RepoAdvisory, f: Facts) -> Assessment:
+    ecos = tuple(sorted({p.ecosystem for p in adv.packages} or {"other"}))
+    return Assessment(
+        ghsa_id=adv.ghsa_id,
+        status=status(f),
+        cve_label=cve_label(f),
+        likely_permanent=not any(reviewable(e) for e in ecos),
+        ecosystems=ecos,
+    )
+
+
+def facts_hash(f: Facts) -> str:
+    return hashlib.sha256(json.dumps(f.model_dump(mode="json"), sort_keys=True).encode()).hexdigest()
+
+
+def transitions(old: Facts | None, new: Facts, cnas: Mapping[str, str | None] | None = None) -> list[str]:
+    """Human-readable events between two fact snapshots (empty if nothing meaningful changed).
+
+    `cnas` maps uncited CVE IDs to their CNA, so GitHub's own CVEs aren't called another CNA's (F-067)."""
+    if old is None:
+        return ["first seen"]
+    ev = []
+    if status(old) != status(new):
+        ev.append(f"{status(old).value} -> {status(new).value}")
+    if old.cited_cve != new.cited_cve:
+        ev.append(f"cites {new.cited_cve or 'no CVE'} (was {old.cited_cve or 'none'})")
+    elif old.cited_cve_state != new.cited_cve_state and new.cited_cve:
+        ev.append(f"{new.cited_cve} {old.cited_cve_state or '?'} -> {new.cited_cve_state}")
+    added = sorted(set(new.uncited_cves) - set(old.uncited_cves))
+    github = [c for c in added if (cnas or {}).get(c) == GITHUB_CNA]
+    if github:
+        ev.append(f"new CVE from GitHub's CNA, not cited: {', '.join(github)}")
+    if other := [c for c in added if c not in github]:
+        ev.append(f"new CVE from another CNA: {', '.join(other)}")
+    if not old.duplicate_of and new.duplicate_of:
+        ev.append(f"duplicate of reviewed {', '.join(new.duplicate_of)}")
+    return ev

limbowatch/csvsafe.py

@@ -0,0 +1,18 @@
+"""Spreadsheet-safe CSV cells. Pure.
+
+Spreadsheets treat a cell starting with = + - @ as a formula. Advisory fields are typed by maintainers, so a
+cell starting with = gets a leading ', and so does one starting with + - @ that could call anything (a function,
+a link, DDE). npm scopes like `@scope/pkg; other` and numbers like -1 stay as entered.
+"""
+
+from __future__ import annotations
+
+import re
+
+_CALLS = re.compile(r"[()|!\"'&\[\]{}$\t\r\n]")  # what a formula needs to call a function, a link or DDE
+
+
+def cell(v: str) -> str:
+    if v[:1] in ("=", "\t", "\r") or (v[:1] in ("+", "-", "@") and _CALLS.search(v)):
+        return f"'{v}"
+    return v

limbowatch/ecosystems.py

@@ -0,0 +1,123 @@
+"""Ecosystem registry: GHSA ecosystem name -> OSV ecosystem, purl type, review support.
+
+Adding an ecosystem means adding one entry here (and, for version evaluation, a comparator in
+versions.py). Everything else looks ecosystems up through `info()`.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EcosystemInfo:
+    ghsa: str  # GHSA / GitHub Advisory Database ecosystem name
+    osv: str | None  # OSV ecosystem name (None: OSV has no equivalent)
+    purl_type: str | None
+    reviewable: bool  # GitHub reviews advisories for this ecosystem (FINDINGS F-015, F-023)
+    name_rule: str = r".+"  # what a well-formed package name looks like, after cleaning
+    name_style: str = ""  # "pep503" / "lower": the canonical spelling scanners compare; "url": a path, not a URL
+    depsdev: str | None = None  # deps.dev system, for mapping a package to its source repo
+
+
+_REGISTRY: dict[str, EcosystemInfo] = {
+    e.ghsa: e
+    for e in (
+        # Name rules follow each registry's documented naming (FINDINGS F-069)
+        EcosystemInfo("npm", "npm", "npm", True, r"(?:@[A-Za-z0-9~-][\w.~-]*/)?[A-Za-z0-9~-][\w.~-]*", depsdev="npm"),
+        EcosystemInfo("pip", "PyPI", "pypi", True, r"[a-z0-9]+(?:-[a-z0-9]+)*", "pep503", depsdev="pypi"),
+        EcosystemInfo(
+            "go", "Go", "golang", True, r"stdlib|toolchain|[a-z0-9.-]+\.[a-z]{2,}(?:/[\w.~+-]+)*", "url", depsdev="go"
+        ),
+        EcosystemInfo("rust", "crates.io", "cargo", True, r"[A-Za-z0-9_-]+", depsdev="cargo"),
+        EcosystemInfo("maven", "Maven", "maven", True, r"[\w.-]+:[\w.-]+", depsdev="maven"),
+        EcosystemInfo("nuget", "NuGet", "nuget", True, r"[\w.-]+", depsdev="nuget"),
+        EcosystemInfo(
+            "composer",
+            "Packagist",
+            "composer",
+            True,
+            r"[a-z0-9]([_.-]?[a-z0-9]+)*/[a-z0-9](([_.]|-{1,2})?[a-z0-9]+)*",
+            "lower",
+        ),
+        EcosystemInfo("rubygems", "RubyGems", "gem", True, r"[\w.-]+", depsdev="rubygems"),
+        EcosystemInfo("erlang", "Hex", "hex", True, r"[a-z][a-z0-9_]*"),
+        EcosystemInfo("actions", "GitHub Actions", "githubactions", True, r"[\w.-]+/[\w.-]+(?:/[\w./-]+)?", "url"),
+        EcosystemInfo("pub", "Pub", "pub", True, r"[a-z_][a-z0-9_]*"),
+        EcosystemInfo("swift", "SwiftURL", "swift", True, r"[a-z0-9.-]+\.[a-z]{2,}(?:/[\w.-]+){2,}", "url"),
+    )
+}
+
+
+def info(ghsa_ecosystem: str | None) -> EcosystemInfo:
+    """Registry entry; unknown, empty or free-text ecosystems are not reviewable."""
+    key = (ghsa_ecosystem or "").strip().lower()
+    return _REGISTRY.get(key) or EcosystemInfo(key or "other", None, None, False)
+
+
+def reviewable(ghsa_ecosystem: str | None) -> bool:
+    return info(ghsa_ecosystem).reviewable
+
+
+_BY_OSV = {e.osv: e for e in _REGISTRY.values() if e.osv}
+_BY_PURL = {e.purl_type: e for e in _REGISTRY.values() if e.purl_type}
+
+
+def by_osv(osv_ecosystem: str) -> EcosystemInfo | None:
+    """Registry entry for an OSV ecosystem name such as "PyPI" or "crates.io" (or "Debian:12")."""
+    return _BY_OSV.get(osv_ecosystem.split(":", 1)[0])
+
+
+def by_purl_type(purl_type: str) -> EcosystemInfo | None:
+    return _BY_PURL.get(purl_type.lower())
+
+
+# OSV's ecosystem list (https://osv-vulnerabilities.storage.googleapis.com/ecosystems.txt, 2026-10-31).
+# OSV-Scanner's offline mode fails the whole scan when an ecosystem it needs has no zip, so the feed
+# serves one for each, and the watcher's inventory step uses an empty one for each (F-074, F-078).
+OSV_ECOSYSTEMS = (
+    "AlmaLinux", "Alpaquita", "Alpine", "Android", "Azure Linux", "BellSoft Hardened Containers", "Bitnami", "CRAN",
+    "Chainguard", "CleanStart", "Debian", "Echo", "GHC", "GIT", "GSD", "GitHub Actions", "Go", "Hackage", "Hex",
+    "Julia", "Linux", "Mageia", "Maven", "MinimOS", "NuGet", "OSS-Fuzz", "Packagist", "Pub", "PyPI", "Red Hat",
+    "Red Hat Lightwell", "Rocky Linux", "Root", "RubyGems", "SUSE", "SwiftURL", "TuxCare", "UVI", "Ubuntu", "VSCode",
+    "Wolfi", "crates.io", "npm", "opam", "openEuler", "openSUSE",
+)  # fmt: skip
+
+
+@dataclass(frozen=True)
+class PackageName:
+    name: str  # the name to publish and match on
+    raw: str  # as the maintainer entered it
+    valid: bool  # well-formed for its ecosystem; an invalid name can't match any real package
+
+    @property
+    def cleaned(self) -> bool:
+        return self.name != self.raw
+
+
+_MD_LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)")
+
+
+def package_name(ghsa_ecosystem: str | None, raw: str | None) -> PackageName | None:
+    """A maintainer-entered package name, cleaned only where the result is certain (FINDINGS F-069).
+
+    Scanners compare names exactly (PyPI and Composer after canonicalizing their own side), so a
+    stray space, a URL or the wrong case means the advisory silently never matches. Names that still
+    don't fit the ecosystem's naming rule are flagged, never guessed at.
+    """
+    if raw is None or not raw.strip():
+        return None
+    e = info(ghsa_ecosystem)
+    s = _MD_LINK.sub(r"\1", raw).strip().strip("`'\"").strip()
+    if e.name_style == "url":
+        s = re.sub(r"^(?:git\+)?https?://", "", s).removesuffix("/").removesuffix(".git")
+        if e.ghsa == "actions":
+            s = s.removeprefix("github.com/")
+    elif e.name_style == "pep503":
+        if m := re.search(r"#egg=([\w.-]+)", s):
+            s = m.group(1)
+        s = re.sub(r"[-_.]+", "-", s).lower()
+    elif e.name_style == "lower":
+        s = s.lower()
+    return PackageName(s, raw, re.fullmatch(e.name_rule, s) is not None)

limbowatch/http.py

@@ -0,0 +1,229 @@
+"""The only module that builds HTTP requests.
+
+- Per-host concurrency limits, retries with exponential backoff, Retry-After.
+- GitHub primary and secondary rate limits; a request budget for the run (304s are free and
+  don't count, FINDINGS F-058).
+- Conditional requests: ETags are only valid for the token that obtained them (the response
+  varies by Authorization), so the client exposes a token fingerprint to store alongside them.
+- The token is never logged, printed or returned.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from limbowatch import __version__
+
+log = logging.getLogger(__name__)
+USER_AGENT = f"limbowatch/{__version__} (+https://limbo.watch)"
+GITHUB_API = "api.github.com"
+HOST_CONCURRENCY = {
+    GITHUB_API: 8,
+    "api.osv.dev": 16,
+    "cveawg.mitre.org": 16,
+    "services.nvd.nist.gov": 1,
+    "raw.githubusercontent.com": 8,
+    "api.deps.dev": 16,
+    "rubygems.org": 4,  # its API asks for at most about 10 requests a second
+}
+
+
+class BudgetExhausted(Exception):
+    """The run's GitHub request budget (or the primary rate limit) is used up."""
+
+
+class DeadlineReached(Exception):
+    """The run's wall-clock deadline has passed."""
+
+
+@dataclass
+class Response:
+    status: int
+    body: Any
+    etag: str | None = None
+    link: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status == 200
+
+
+@dataclass
+class Stats:
+    requests: dict[str, int] = field(default_factory=dict)
+    github_counted: int = 0
+    github_not_modified: int = 0
+    failures: int = 0
+
+
+class HttpClient:
+    def __init__(
+        self,
+        github_token: str | None = None,
+        *,
+        github_budget: int | None = None,
+        deadline: float | None = None,
+        nvd_api_key: str | None = None,
+        max_rate_limit_wait: float = 900.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Any = asyncio.sleep,
+    ) -> None:
+        self._token = github_token
+        self.token_fingerprint = hashlib.sha256(github_token.encode()).hexdigest()[:16] if github_token else "anonymous"
+        self.github_budget = github_budget
+        self.deadline = deadline
+        self._nvd_key = nvd_api_key
+        self._nvd_spacing = 0.7 if nvd_api_key else 6.5
+        self._nvd_last = 0.0
+        self._max_wait = max_rate_limit_wait
+        self._sleep = sleep
+        self._sems = {h: asyncio.Semaphore(n) for h, n in HOST_CONCURRENCY.items()}
+        self._default_sem = asyncio.Semaphore(8)
+        self._nvd_lock = asyncio.Lock()
+        self.stats = Stats()
+        self._client = httpx.AsyncClient(
+            timeout=60, follow_redirects=True, headers={"User-Agent": USER_AGENT}, transport=transport
+        )
+
+    async def __aenter__(self) -> HttpClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self._client.aclose()
+
+    def budget_left(self) -> int | None:
+        return None if self.github_budget is None else self.github_budget - self.stats.github_counted
+
+    def _check_deadline(self) -> None:
+        if self.deadline is not None and time.monotonic() > self.deadline:
+            raise DeadlineReached
+
+    async def get(self, url: str, *, etag: str | None = None, json_body: Any = None, raw: bool = False) -> Response:
+        """GET (or POST with `json_body`). Returns status 304 with no body when `etag` still matches.
+
+        With `raw`, the body is the response bytes (e.g. a zip), and `etag` is sent to any host.
+        """
+        self._check_deadline()
+        host = urlsplit(url).hostname or ""
+        is_gh = host == GITHUB_API
+        if is_gh and (left := self.budget_left()) is not None and left <= 0:
+            raise BudgetExhausted
+        headers: dict[str, str] = {}
+        if is_gh:
+            headers.update({"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28"})
+            if self._token:
+                headers["Authorization"] = f"Bearer {self._token}"
+            if etag:
+                headers["If-None-Match"] = etag
+        elif raw and etag:
+            headers["If-None-Match"] = etag
+        if host == "services.nvd.nist.gov":
+            if self._nvd_key:
+                headers["apiKey"] = self._nvd_key
+            async with self._nvd_lock:  # NVD: one request per spacing interval
+                wait = self._nvd_last + self._nvd_spacing - time.monotonic()
+                if wait > 0:
+                    await self._sleep(wait)
+                self._nvd_last = time.monotonic()
+        sem = self._sems.get(host, self._default_sem)
+        async with sem:
+            r = await self._send(url, headers, json_body, is_gh)
+        self.stats.requests[host] = self.stats.requests.get(host, 0) + 1
+        if r is None:
+            self.stats.failures += 1
+            return Response(-1, None)
+        if is_gh:
+            if r.status_code == 304:
+                self.stats.github_not_modified += 1
+            else:
+                self.stats.github_counted += 1
+        if r.status_code == 304:
+            return Response(304, None, etag=etag)
+        if raw:
+            return Response(r.status_code, r.content, etag=r.headers.get("etag"), link=r.headers.get("link"))
+        try:
+            body: Any = r.json()
+        except ValueError:
+            body = r.text
+        return Response(r.status_code, body, etag=r.headers.get("etag"), link=r.headers.get("link"))
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        auth: tuple[str, str],
+        json_body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Response:
+        """A request to an issue tracker (GitLab, Gitea): any method, a caller-supplied auth header.
+
+        The header value is a token; it's sent only to `url`'s host and never logged.
+        """
+        self._check_deadline()
+        host = urlsplit(url).hostname or ""
+        r: httpx.Response | None = None
+        async with self._sems.get(host, self._default_sem):
+            for attempt in range(5):
+                try:
+                    r = await self._client.request(method, url, headers={auth[0]: auth[1]}, json=json_body,
+                                                   params=params)  # fmt: skip
+                except httpx.HTTPError as e:
+                    log.warning("http error", extra={"host": host, "error": type(e).__name__, "attempt": attempt})
+                    await self._sleep(min(30, 2**attempt))
+                    continue
+                if r.status_code in (429, 502, 503, 504):
+                    await self._sleep(min(60, int(r.headers.get("retry-after", 2 ** (attempt + 1)))))
+                    continue
+                break
+        self.stats.requests[host] = self.stats.requests.get(host, 0) + 1
+        if r is None:
+            self.stats.failures += 1
+            return Response(-1, None)
+        try:
+            body: Any = r.json()
+        except ValueError:
+            body = r.text
+        return Response(r.status_code, body, etag=r.headers.get("etag"), link=r.headers.get("link"))
+
+    async def _send(self, url: str, headers: dict[str, str], json_body: Any, is_gh: bool) -> httpx.Response | None:
+        for attempt in range(6):
+            self._check_deadline()
+            try:
+                if json_body is None:
+                    r = await self._client.get(url, headers=headers)
+                else:
+                    r = await self._client.post(url, headers=headers, json=json_body)
+            except httpx.HTTPError as e:
+                log.warning("http error", extra={"url": url, "error": type(e).__name__, "attempt": attempt})
+                await self._sleep(min(60, 2**attempt))
+                continue
+            if is_gh and r.status_code in (403, 429):
+                if r.headers.get("x-ratelimit-remaining") == "0":
+                    await self._wait_for_reset(r)
+                    continue
+                if "retry-after" in r.headers or "secondary rate limit" in r.text.lower():
+                    await self._sleep(int(r.headers.get("retry-after", 60)) + 1)
+                    continue
+            if r.status_code in (429, 500, 502, 503, 504):
+                await self._sleep(min(60, int(r.headers.get("retry-after", 2 ** (attempt + 1)))))
+                continue
+            if is_gh and int(r.headers.get("x-ratelimit-remaining", "1000")) < 20:
+                await self._wait_for_reset(r)
+            return r
+        return None
+
+    async def _wait_for_reset(self, r: httpx.Response) -> None:
+        wait = max(5.0, float(r.headers.get("x-ratelimit-reset", time.time() + 60)) - time.time() + 5)
+        if wait > self._max_wait:
+            raise BudgetExhausted
+        log.info("github rate limit low; waiting", extra={"seconds": round(wait)})
+        await self._sleep(wait)

limbowatch/inventory/__init__.py

@@ -0,0 +1,5 @@
+"""The watcher's inventory: what a project depends on, and what can't be checked (Phase 4).
+
+Two backends: OSV-Scanner over a source tree (`osv_scanner`), or an SBOM (`sbom`). Both report every
+dependency they can't check as an `UnresolvedDependency` with a reason; nothing is dropped.
+"""

limbowatch/inventory/checks.py

@@ -0,0 +1,161 @@
+"""Re-reading lockfiles for what OSV-Scanner's inventory gets wrong without saying so (FINDINGS F-078).
+
+Pure functions over file text: each returns what one kind of file says about how a package was
+installed, so the inventory can report a dependency as unchecked instead of matching a wrong version.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+
+PINNED, RANGE, VCS, PATH = "pinned", "range", "vcs", "path"
+
+
+@dataclass(frozen=True)
+class Requirement:
+    name: str  # PEP 503 normalized; "" when a VCS or path line doesn't say
+    kind: str  # PINNED, RANGE, VCS or PATH
+    spec: str  # the line as written, for the report
+    line: int
+
+
+def pep503(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def requirements(text: str) -> list[Requirement]:
+    """Each requirement line of a pip requirements file, classified by how exactly it pins a version."""
+    out: list[Requirement] = []
+    joined: list[tuple[int, str]] = []
+    buf, start = "", 0
+    for n, raw in enumerate(text.splitlines(), 1):
+        if not buf:
+            start = n
+        if raw.rstrip().endswith("\\"):
+            buf += raw.rstrip()[:-1] + " "
+            continue
+        joined.append((start, buf + raw))
+        buf = ""
+    if buf:
+        joined.append((start, buf))
+    for n, raw in joined:
+        line = re.sub(r"(^|\s)#.*$", "", raw).strip()  # a comment, but not "#egg=" inside a URL
+        if not line:
+            continue
+        editable = re.match(r"(?:-e|--editable)[\s=]+(.+)", line)
+        if editable:
+            target = editable.group(1).strip()
+            kind = VCS if "://" in target or target.startswith("git+") else PATH
+            out.append(Requirement(_egg(target), kind, line, n))
+            continue
+        if line.startswith("-"):
+            continue  # -r, -c, --index-url, --hash and other options
+        if re.match(r"(?:[a-z][a-z0-9+.-]*\+)?[a-z]+://", line, re.I) or " @ " in line or line.startswith("git+"):
+            name = re.match(r"([A-Za-z0-9][A-Za-z0-9._-]*)\s*@", line)
+            target = line.split("@", 1)[-1] if name else line
+            kind = PATH if target.strip().startswith("file:") else VCS
+            out.append(Requirement(pep503(name.group(1)) if name else _egg(line), kind, line, n))
+            continue
+        if line.startswith((".", "/")) or re.search(r"\.(whl|tar\.gz|zip)$", line):
+            out.append(Requirement(_egg(line), PATH, line, n))
+            continue
+        m = re.match(r"([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*([^;]*)", line)
+        if not m:
+            continue
+        spec = re.sub(r"\s*--[\w-]+(?:[=\s]+\S+)?", "", m.group(2)).strip()  # drop --hash and other options
+        pinned = re.fullmatch(r"===?\s*[^,*\s]+", spec) is not None
+        out.append(Requirement(pep503(m.group(1)), PINNED if pinned else RANGE, line, n))
+    return out
+
+
+def _egg(target: str) -> str:
+    m = re.search(r"#egg=([A-Za-z0-9][A-Za-z0-9._-]*)", target)
+    return pep503(m.group(1)) if m else ""
+
+
+def cargo_sources(text: str) -> dict[tuple[str, str], str]:
+    """(name, version) -> "registry", "vcs" or "path", from a Cargo.lock. Local crates have no `source`."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        return {}
+    out = {}
+    for p in data.get("package", []):
+        src = str(p.get("source") or "")
+        kind = "registry" if src.startswith(("registry+", "sparse+")) else VCS if src.startswith("git+") else PATH
+        out[(str(p.get("name", "")), str(p.get("version", "")))] = kind
+    return out
+
+
+def uv_sources(text: str) -> dict[str, str]:
+    """name -> "registry", "vcs" or "path", from a uv.lock. The project itself is `editable` or `virtual`."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        return {}
+    out = {}
+    for p in data.get("package", []):
+        src = p.get("source") or {}
+        kind = "registry" if "registry" in src else VCS if "git" in src or "url" in src else PATH
+        out[str(p.get("name", ""))] = kind
+    return out
+
+
+def npm_registry_without_resolved(text: str) -> set[tuple[str, str]]:
+    """(name, version) of package-lock entries that are registry packages despite having no `resolved`.
+
+    npm leaves `resolved` out under `omit-lockfile-registry-resolved`; OSV-Scanner 2.7.0 then treats
+    the package as local and doesn't check it (osv-scanner#3177, FINDINGS F-078). A real local
+    package is a link, or resolves to a path.
+    """
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return set()
+    out = set()
+    for key, entry in (data.get("packages") or {}).items():
+        if not key.startswith("node_modules/") and "/node_modules/" not in key:
+            continue
+        if not isinstance(entry, dict) or entry.get("link") or "resolved" in entry or "version" not in entry:
+            continue
+        name = entry.get("name") or key.rsplit("node_modules/", 1)[-1]
+        out.add((str(name), str(entry["version"])))
+    return out
+
+
+def locate(text: str, filename: str, name: str, version: str = "") -> int:
+    """The 1-based line that declares `name` in a lockfile or manifest, or 1 if it can't be found.
+
+    Code Quality and SARIF alerts need a line; OSV-Scanner doesn't report one (FINDINGS F-078, F-079).
+    """
+    lines = text.splitlines()
+    patterns = []
+    base = filename.rsplit("/", 1)[-1]
+    if base in ("package-lock.json", "npm-shrinkwrap.json"):
+        patterns.append(re.compile(rf'"(?:[^"]*/)?node_modules/{re.escape(name)}"'))
+    if base == "Cargo.lock":
+        patterns.append(re.compile(rf'^name = "{re.escape(name)}"$'))
+    if base.endswith(".txt"):
+        patterns.append(re.compile(rf"^\s*{_pep503_pattern(name)}\s*(?:[\[=<>!~;@ ]|$)", re.I))
+    patterns.append(re.compile(rf"(?<![\w./-]){re.escape(name)}(?![\w-])"))
+    if "/" in name:  # e.g. a Git URL: the lockfile names the package by its last path segment
+        tail = re.sub(r"\.git$", "", name.rstrip("/").rsplit("/", 1)[-1])
+        patterns.append(
+            re.compile(rf'"(?:[^"]*/)?node_modules/{re.escape(tail)}"|(?<![\w.-]){re.escape(tail)}(?![\w-])')
+        )
+    for pat in patterns:
+        hits = [i for i, ln in enumerate(lines, 1) if pat.search(ln)]
+        if not hits:
+            continue
+        if version and len(hits) > 1:
+            near = [i for i in hits if any(version in ln for ln in lines[i - 1 : i + 3])]
+            hits = near or hits
+        return hits[0]
+    return 1
+
+
+def _pep503_pattern(name: str) -> str:
+    return "[-_.]+".join(re.escape(part) for part in re.split(r"[-_.]+", name))