forceupdate 0.1.0__py3-none-any.whl

forceupdate/net/cache.py

@@ -0,0 +1,217 @@
+"""Le cache disque : ce que le réseau a répondu, gardé un temps qui dépend du type de donnée.
+
+Un même paquet revient dans plusieurs projets, plusieurs dépôts et plusieurs analyses : il
+n'est demandé qu'une fois par durée de vie. On y range des valeurs JSON déjà réduites (les
+versions d'un paquet, pas le document de 30 Mo du registre).
+
+Le cache est une base SQLite, dans le dossier de cache de l'utilisateur (``platformdirs``) :
+un seul fichier, des écritures atomiques, et l'interface et la ligne de commande peuvent
+s'en servir en même temps.
+
+- **Sans cache** (``Cache.disabled()``) : rien n'est lu ni écrit.
+- **Hors ligne** : une entrée périmée sert quand même (``stale_ok``). Mieux vaut une donnée
+  datée, et dite datée (``CacheEntry.stored_at``), que rien.
+- **Jetable** : un fichier illisible ou d'un autre format est vidé ; un disque où l'on ne
+  peut pas écrire désactive le cache, avec un avertissement dans les logs. Le cache ne
+  fait jamais échouer une analyse.
+"""
+
+import enum
+import json
+import logging
+import sqlite3
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import platformdirs
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = 1
+"""Version du format de la base, dans ``PRAGMA user_version`` : une autre la fait vider."""
+_KEEP = 30 * 24 * 3600.0
+"""Les entrées plus vieilles que 30 jours sont effacées à l'ouverture, même hors ligne."""
+
+
+class CacheKind(enum.StrEnum):
+    """Un type de donnée du cache, avec sa durée de vie (``ttl``)."""
+
+    VERSIONS = "versions"
+    """Les versions d'un paquet et sa dépréciation : 1 h, une version peut sortir à tout moment."""
+    VULNERABILITIES = "vulnerabilities"
+    """Les failles connues d'une version d'un paquet (leurs identifiants, chez OSV) : 1 h, un
+    avis peut être publié à tout moment."""
+    ADVISORIES = "advisories"
+    """Un avis de sécurité complet (OSV) : 7 jours. Il ne change pas sans que sa date de
+    modification change, et on la vérifie à chaque fois."""
+
+    @property
+    def ttl(self) -> float:
+        """Durée de vie d'une entrée, en secondes."""
+        return _TTLS[self]
+
+
+_TTLS = {
+    CacheKind.VERSIONS: 3600.0,
+    CacheKind.VULNERABILITIES: 3600.0,
+    CacheKind.ADVISORIES: 7 * 24 * 3600.0,
+}
+
+
+@dataclass(frozen=True, kw_only=True)
+class CacheEntry:
+    """Une valeur lue dans le cache."""
+
+    value: Any
+    stored_at: datetime
+    """Quand elle a été rangée (UTC) : la date des données."""
+    fresh: bool
+    """Faux pour une entrée périmée, rendue seulement parce que ``stale_ok`` le permettait."""
+
+
+def default_cache_path() -> Path:
+    """Le fichier du cache, dans le dossier de cache de l'utilisateur :
+    ``%LOCALAPPDATA%\\forceupdate\\Cache`` sous Windows, ``~/.cache/forceupdate`` sous Linux."""
+    return platformdirs.user_cache_path("forceupdate", appauthor=False) / "cache.sqlite3"
+
+
+class Cache:
+    """Le cache disque, rangé dans le fichier ``path`` (créé au besoin) ; ``None`` le désactive.
+
+    Les clés sont des chaînes (l'URL interrogée, en général), les valeurs du JSON. Les
+    méthodes sont synchrones et rapides (une requête SQLite), et sûres entre threads.
+    ``clock`` sert aux tests.
+    """
+
+    def __init__(self, path: Path | None, *, clock: Callable[[], float] = time.time) -> None:
+        self.path = path
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._db: sqlite3.Connection | None = None
+        self._opened = path is None
+
+    @classmethod
+    def default(cls) -> "Cache":
+        """Le cache de l'utilisateur, à ``default_cache_path()``."""
+        return cls(default_cache_path())
+
+    @classmethod
+    def disabled(cls) -> "Cache":
+        """Un cache qui ne lit ni n'écrit rien : l'option « sans cache »."""
+        return cls(None)
+
+    @property
+    def enabled(self) -> bool:
+        """Faux si le cache est désactivé, au départ ou après une erreur du disque."""
+        with self._lock:
+            return self._connection() is not None
+
+    def get(self, kind: CacheKind, key: str, *, stale_ok: bool = False) -> CacheEntry | None:
+        """L'entrée ``key`` de ``kind`` ; ``None`` si elle manque ou a dépassé sa durée de vie.
+
+        ``stale_ok`` rend aussi une entrée périmée (mode hors ligne), avec ``fresh=False``.
+        """
+        with self._lock:
+            row = self._execute(
+                "SELECT stored_at, value FROM entries WHERE kind = ? AND key = ?", (kind, key)
+            )
+        if row is None:
+            return None
+        stored_at, text = row
+        fresh = self._clock() - stored_at < kind.ttl
+        if not fresh and not stale_ok:
+            return None
+        try:
+            value = json.loads(text)
+        except ValueError:
+            return None
+        return CacheEntry(
+            value=value, stored_at=datetime.fromtimestamp(stored_at, UTC), fresh=fresh
+        )
+
+    def set(self, kind: CacheKind, key: str, value: Any) -> None:
+        """Range ``value`` (du JSON) sous ``key``, à la place de l'ancienne entrée."""
+        text = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+        with self._lock:
+            self._execute(
+                "INSERT OR REPLACE INTO entries (kind, key, stored_at, value) VALUES (?, ?, ?, ?)",
+                (kind, key, self._clock(), text),
+                commit=True,
+            )
+
+    def clear(self) -> None:
+        """Vide le cache."""
+        with self._lock:
+            self._execute("DELETE FROM entries", (), commit=True)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._db is not None:
+                self._db.close()
+                self._db = None
+
+    # -- SQLite --------------------------------------------------------------
+
+    def _execute(self, sql: str, params: tuple[Any, ...], *, commit: bool = False) -> Any:
+        """Lance ``sql`` et rend la première ligne ; ``None`` si le cache est désactivé. Une
+        erreur de SQLite désactive le cache pour la suite de la session."""
+        db = self._connection()
+        if db is None:
+            return None
+        try:
+            row = db.execute(sql, params).fetchone()
+            if commit:
+                db.commit()
+        except sqlite3.Error as error:
+            self._disable(error)
+            return None
+        return row
+
+    def _connection(self) -> sqlite3.Connection | None:
+        if not self._opened:
+            self._opened = True
+            assert self.path is not None
+            try:
+                self._db = self._open(self.path)
+            except sqlite3.DatabaseError:
+                # Fichier abîmé, ou qui n'est pas une base : le cache est jetable.
+                try:
+                    self.path.unlink()
+                    self._db = self._open(self.path)
+                except (OSError, sqlite3.Error) as error:
+                    self._disable(error)
+            except (OSError, sqlite3.Error) as error:
+                self._disable(error)
+        return self._db
+
+    def _open(self, path: Path) -> sqlite3.Connection:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        db = sqlite3.connect(path, timeout=5.0, check_same_thread=False)
+        try:
+            # WAL : les lectures d'un processus ne bloquent pas les écritures d'un autre.
+            db.execute("PRAGMA journal_mode = WAL")
+            (version,) = db.execute("PRAGMA user_version").fetchone()
+            if version != _SCHEMA:
+                db.execute("DROP TABLE IF EXISTS entries")
+                db.execute(
+                    "CREATE TABLE entries (kind TEXT NOT NULL, key TEXT NOT NULL,"
+                    " stored_at REAL NOT NULL, value TEXT NOT NULL, PRIMARY KEY (kind, key))"
+                )
+                db.execute(f"PRAGMA user_version = {_SCHEMA}")
+            db.execute("DELETE FROM entries WHERE stored_at < ?", (self._clock() - _KEEP,))
+            db.commit()
+        except BaseException:
+            db.close()
+            raise
+        return db
+
+    def _disable(self, error: BaseException) -> None:
+        logger.warning("cache désactivé (%s) : %s", self.path, error)
+        if self._db is not None:
+            self._db.close()
+        self._db = None

forceupdate/net/http.py

@@ -0,0 +1,270 @@
+"""Le client HTTP commun : un ``httpx.AsyncClient`` partagé, ses délais, ses reprises et ses
+limites par hôte.
+
+Tout ce qui parle au réseau passe par ``HttpClient`` :
+
+- un User-Agent qui dit qui on est (crates.io l'exige, E21) ;
+- des délais maximaux : 10 s pour se connecter, 30 s sans rien recevoir, 2 min pour un
+  essai entier (un serveur qui envoie un octet toutes les 29 s ne le fait pas durer) ;
+- des reprises sur 429, 5xx, coupures et délais dépassés, en attendant ce que demande
+  ``Retry-After`` ; s'il demande plus d'une minute, on abandonne ;
+- au plus 8 requêtes à la fois par hôte ;
+- un hôte resté injoignable après ses reprises (ou qui limite le débit) n'est plus
+  interrogé de la session : sans réseau, chaque paquet attendrait sinon ses reprises ;
+- une réponse de plus de 128 Mo est refusée (le document npm de ``next`` en fait 32).
+
+Une requête qui n'aboutit pas lève ``NetworkError``, avec un message en français fait pour
+le rapport. Un statut final (200, 404, 403…) n'est pas une erreur du client : c'est à
+l'appelant de dire ce qu'il veut dire.
+"""
+
+import asyncio
+import email.utils
+import json
+import logging
+import random
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from forceupdate import __version__
+
+logger = logging.getLogger(__name__)
+
+USER_AGENT = f"forceupdate/{__version__} (+https://github.com/Pauzzle-ozz/forceupdate)"
+
+TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+"""Les délais d'httpx : 10 s pour se connecter, 30 s pour le reste (entre deux octets…)."""
+DEADLINE = 120.0
+"""Durée maximale d'un essai, en secondes, réponse lue en entier."""
+RETRIES = 3
+"""Reprises après le premier essai, pour une requête qu'on peut rejouer."""
+MAX_PER_HOST = 8
+"""Requêtes simultanées par hôte."""
+MAX_BODY = 128 * 1024 * 1024
+"""Taille maximale d'une réponse, décompressée, en octets."""
+MAX_RETRY_AFTER = 60.0
+"""Attente maximale demandée par ``Retry-After``, en secondes : au-delà, on abandonne."""
+
+_BACKOFF = 0.5
+"""Première attente entre deux essais sans ``Retry-After`` ; elle double à chaque reprise."""
+_IDEMPOTENT = frozenset({"GET", "HEAD", "OPTIONS"})
+_RETRYABLE = (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError, TimeoutError)
+"""Les échecs qui peuvent passer en réessayant : délai dépassé, connexion refusée ou coupée."""
+_DIGITS = re.compile(r"[0-9]+")
+
+
+class NetworkError(Exception):
+    """Une requête n'a pas abouti : réseau coupé, délai dépassé, serveur en erreur, mode hors
+    ligne… Le constat qui en dépend est « non concluant ».
+
+    Le message, en français, est fait pour être montré tel quel dans le rapport. Il cite
+    l'hôte, jamais l'URL (une URL peut contenir un token).
+    """
+
+
+@dataclass(frozen=True, kw_only=True)
+class Response:
+    """Une réponse HTTP, lue en entier."""
+
+    url: str
+    """L'URL finale, après les redirections."""
+    status_code: int
+    headers: httpx.Headers
+    content: bytes
+    """Le corps, décompressé."""
+
+    @property
+    def media_type(self) -> str:
+        """Le type du corps sans ses paramètres, en minuscules (``application/json``)."""
+        return self.headers.get("content-type", "").partition(";")[0].strip().lower()
+
+    def json(self) -> Any:
+        """Le corps lu en JSON ; lève ``ValueError`` s'il n'en est pas."""
+        return json.loads(self.content)
+
+
+class _TooLarge(Exception):
+    pass
+
+
+class HttpClient:
+    """Le client HTTP d'une session : une analyse en ligne de commande, ou l'interface web.
+
+    Un seul par session, pour garder les connexions ouvertes et que les limites par hôte
+    vaillent pour tout le monde. À fermer après usage : ``async with HttpClient() as http``.
+
+    ``offline`` : aucune requête ne part, chacune lève ``NetworkError`` ; les registres se
+    contentent alors du cache. ``sleep`` sert aux tests, pour ne pas attendre les reprises.
+    """
+
+    def __init__(
+        self,
+        *,
+        offline: bool = False,
+        retries: int = RETRIES,
+        max_per_host: int = MAX_PER_HOST,
+        max_body: int = MAX_BODY,
+        deadline: float = DEADLINE,
+        sleep: Callable[[float], Awaitable[object]] = asyncio.sleep,
+    ) -> None:
+        self.offline = offline
+        self._retries = retries
+        self._max_per_host = max_per_host
+        self._max_body = max_body
+        self._deadline = deadline
+        self._sleep = sleep
+        self._slots: dict[str, asyncio.Semaphore] = {}
+        self._down: dict[str, str] = {}
+        """Les hôtes abandonnés pour la session, avec le message de leur échec."""
+        self._client = httpx.AsyncClient(
+            headers={"User-Agent": USER_AGENT},
+            timeout=TIMEOUT,
+            follow_redirects=True,
+            limits=httpx.Limits(max_connections=64, max_keepalive_connections=32),
+        )
+
+    async def __aenter__(self) -> "HttpClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def get(self, url: str, *, headers: Mapping[str, str] | None = None) -> Response:
+        """``GET url`` ; voir ``request``."""
+        return await self.request("GET", url, headers=headers)
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        json: Any = None,
+        retry: bool | None = None,
+    ) -> Response:
+        """Envoie la requête et rend la réponse, quel que soit son statut final.
+
+        Réessaie sur 429, 5xx, coupure ou délai dépassé, si la requête peut être rejouée :
+        par défaut ``GET``, ``HEAD`` et ``OPTIONS`` ; ``retry=True`` pour une autre qui ne
+        change rien (une recherche en ``POST``). ``json`` est envoyé en corps JSON.
+
+        Lève ``NetworkError`` quand la requête n'aboutit pas, ou que le statut reste 429 ou
+        5xx après les reprises.
+        """
+        host = httpx.URL(url).host
+        if self.offline:
+            raise NetworkError(f"mode hors ligne : {host} n'est pas interrogé.")
+        if host in self._down:
+            raise NetworkError(self._down[host])
+        if retry is None:
+            retry = method.upper() in _IDEMPOTENT
+        attempts = 1 + (self._retries if retry else 0)
+        for attempt in range(attempts):
+            final = attempt == attempts - 1
+            try:
+                response = await self._send(host, method, url, headers, json)
+            except _TooLarge:
+                limit = self._max_body // 2**20
+                raise NetworkError(f"réponse de {host} trop grosse (plus de {limit} Mo).") from None
+            except _RETRYABLE as error:
+                logger.debug(
+                    "%s %s : %r (essai %d sur %d)", method, url, error, attempt + 1, attempts
+                )
+                if final:
+                    message = _failure(host, error)
+                    self._down[host] = message
+                    raise NetworkError(message) from error
+                await self._sleep(_backoff(attempt))
+                continue
+            except httpx.HTTPError as error:
+                raise NetworkError(
+                    f"requête vers {host} impossible ({type(error).__name__})."
+                ) from error
+            status = response.status_code
+            if status != 429 and status < 500:
+                return response
+            wait = _retry_after(response.headers)
+            logger.debug(
+                "%s %s : HTTP %d (essai %d sur %d)", method, url, status, attempt + 1, attempts
+            )
+            if final or (wait is not None and wait > MAX_RETRY_AFTER):
+                message = _status_failure(host, status, wait)
+                if status == 429:
+                    self._down[host] = message
+                raise NetworkError(message)
+            await self._sleep(_backoff(attempt) if wait is None else wait)
+        raise AssertionError("inaccessible : le dernier essai rend ou lève")
+
+    async def _send(
+        self, host: str, method: str, url: str, headers: Mapping[str, str] | None, body: Any
+    ) -> Response:
+        async with (
+            self._slot(host),
+            asyncio.timeout(self._deadline),
+            self._client.stream(method, url, headers=headers, json=body) as response,
+        ):
+            declared = response.headers.get("content-length", "")
+            if _DIGITS.fullmatch(declared) and int(declared) > self._max_body:
+                raise _TooLarge
+            chunks = []
+            size = 0
+            async for chunk in response.aiter_bytes():
+                size += len(chunk)
+                if size > self._max_body:
+                    raise _TooLarge
+                chunks.append(chunk)
+            return Response(
+                url=str(response.url),
+                status_code=response.status_code,
+                headers=response.headers,
+                content=b"".join(chunks),
+            )
+
+    def _slot(self, host: str) -> asyncio.Semaphore:
+        slot = self._slots.get(host)
+        if slot is None:
+            slot = self._slots[host] = asyncio.Semaphore(self._max_per_host)
+        return slot
+
+
+def _backoff(attempt: int) -> float:
+    """L'attente avant la reprise n° ``attempt + 1`` : 0,5 s, 1 s, 2 s…, un peu au hasard
+    pour que les requêtes en échec ne reviennent pas toutes ensemble."""
+    return _BACKOFF * 2**attempt + random.uniform(0, _BACKOFF)
+
+
+def _retry_after(headers: httpx.Headers) -> float | None:
+    """L'attente demandée par ``Retry-After``, en secondes (un nombre, ou une date HTTP) ;
+    ``None`` sans en-tête lisible."""
+    value = headers.get("retry-after", "").strip()
+    if _DIGITS.fullmatch(value):
+        return float(value)
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, (when - datetime.now(UTC)).total_seconds())
+
+
+def _failure(host: str, error: BaseException) -> str:
+    if isinstance(error, httpx.TimeoutException | TimeoutError):
+        return f"{host} ne répond pas (délai dépassé)."
+    return f"{host} injoignable ({type(error).__name__})."
+
+
+def _status_failure(host: str, status: int, wait: float | None) -> str:
+    if status != 429:
+        return f"{host} en erreur (HTTP {status})."
+    if wait is not None and wait > MAX_RETRY_AFTER:
+        return f"{host} limite le débit (HTTP 429) : réessayer dans {round(wait / 60) or 1} min."
+    return f"{host} limite le débit (HTTP 429)."

forceupdate/parsers/__init__.py

@@ -0,0 +1,43 @@
+"""Les parseurs : lire les manifestes et lockfiles d'un projet, et en tirer ses dépendances.
+
+Un module par écosystème : Python (E03) et npm (E04) pour l'instant, les autres en
+phase F. Chacun relie les manifestes (dépendances directes, contraintes et leur
+emplacement) aux lockfiles (versions installées, transitives), avec ce qui est
+commun dans ``lockfiles.py``.
+"""
+
+from collections.abc import Callable, Sequence
+
+from forceupdate.detect.manifests import ecosystem_for_manifest
+from forceupdate.models import Ecosystem, Notice, Project
+from forceupdate.parsers import npm, python
+from forceupdate.parsers.base import ParseError, ReadText
+
+__all__ = ["ParseError", "ReadText", "parse_project"]
+
+_PARSERS: dict[Ecosystem, Callable[[Project, ReadText, Sequence[str]], None]] = {
+    Ecosystem.PYPI: lambda project, read_text, _: python.parse_project(project, read_text),
+    Ecosystem.NPM: npm.parse_project,
+}
+
+
+def parse_project(project: Project, read_text: ReadText, project_dirs: Sequence[str] = ()) -> None:
+    """Remplit ``project.dependencies`` en lisant ses fichiers avec ``read_text``.
+
+    Ajoute à ``project.notices`` ce qui n'a pas pu être lu, et retire de
+    ``project.lockfiles`` un lockfile de workspace dont le projet n'est pas membre.
+    Un écosystème que forceupdate ne lit pas encore donne une remarque, pour que le
+    rapport ne laisse pas croire que le projet n'a pas de dépendances.
+
+    ``project_dirs`` sont les dossiers de tous les projets de la source : un
+    workspace Yarn 1 ne liste pas ses membres dans son lockfile.
+    """
+    for ecosystem in project.ecosystems:
+        parser = _PARSERS.get(ecosystem)
+        if parser is not None:
+            parser(project, read_text, project_dirs)
+            continue
+        files = project.manifests + project.lockfiles
+        first = next(path for path in files if ecosystem_for_manifest(path) is ecosystem)
+        message = f"dépendances {ecosystem} pas encore lues par forceupdate."
+        project.notices.append(Notice(file=first, message=message))

forceupdate/parsers/base.py

@@ -0,0 +1,22 @@
+"""Ce qui est commun aux parseurs de tous les écosystèmes."""
+
+from collections.abc import Callable
+
+ReadText = Callable[[str], str | None]
+"""Lit un fichier de la source par son chemin POSIX relatif : ``Source.read_text``.
+Rend ``None`` si le fichier est illisible ou trop gros ; lève ``ValueError`` si le
+chemin sort de la source."""
+
+REASON_GIT = "dépendance git"
+REASON_LOCAL = "chemin local"
+REASON_URL = "téléchargée depuis une URL"
+REASON_WORKSPACE = "membre du workspace"
+"""Raisons courantes pour lesquelles une dépendance n'est pas vérifiable. Une raison ne
+cite jamais l'URL ni le chemin : une URL peut contenir un token."""
+
+
+class ParseError(ValueError):
+    """Un fichier de dépendances ne peut pas être lu : TOML ou JSON invalide…
+
+    Le message, en français, est fait pour être montré tel quel dans le rapport.
+    """

forceupdate/parsers/json_spans.py

@@ -0,0 +1,123 @@
+"""Retrouver où sont écrites les chaînes d'un document JSON.
+
+``json`` donne les valeurs d'un document, pas leur position. Comme ``toml_spans``
+pour TOML, ce module parcourt le texte d'un document que ``json.loads`` a déjà
+accepté, et rend, pour chaque chaîne, sa ligne et ses colonnes. C'est ce qui donne
+l'emplacement exact d'une contrainte dans un ``package.json`` (et plus tard un
+``composer.json``, E23), pour la réécrire sans toucher au reste (E10).
+
+Une chaîne est repérée par son chemin dans le document, le même que dans ce que
+rend ``json.loads`` : des clés et des indices de tableaux.
+``{"dependencies": {"lodash": "^4.17.21"}}`` donne ``("dependencies", "lodash")``.
+Seules les valeurs sont rendues, pas les clés. Une clé écrite deux fois dans un
+objet garde sa dernière valeur, comme avec ``json.loads``.
+"""
+
+import bisect
+import json
+import logging
+
+from forceupdate.parsers.toml_spans import StringSpan
+
+logger = logging.getLogger(__name__)
+
+JsonPath = tuple[str | int, ...]
+"""Le chemin d'une valeur : clés et indices de tableaux, comme dans ``json.loads``."""
+
+BOM = ""
+"""L'indicateur d'ordre des octets qu'ajoutent certains éditeurs Windows en tête de
+fichier. ``json.loads`` le refuse ; npm l'ignore."""
+
+
+def string_spans(text: str) -> dict[JsonPath, StringSpan]:
+    """Les chaînes du document JSON ``text``, par chemin.
+
+    ``text`` doit avoir été accepté par ``json.loads`` (après avoir retiré un
+    ``BOM`` de tête, qui compte quand même pour les colonnes de la ligne 1) : il
+    n'est pas revalidé. Les lignes sont comptées sur ``\\n`` seulement, comme
+    ``Location`` ; une chaîne JSON tient toujours sur une ligne.
+    """
+    scanner = _Scanner(text)
+    try:
+        scanner.value(())
+    except (IndexError, ValueError) as err:
+        # Ne devrait pas arriver sur un document valide : on garde ce qui a été trouvé.
+        logger.debug("JSON parcouru en partie seulement : %s", err)
+    return scanner.spans
+
+
+class _Scanner:
+    """Parcourt un document JSON valide et note la position des chaînes."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.pos = 1 if text.startswith(BOM) else 0
+        self.spans: dict[JsonPath, StringSpan] = {}
+        self._line_starts = [0] + [i + 1 for i, char in enumerate(text) if char == "\n"]
+
+    def value(self, path: JsonPath) -> None:
+        self._skip_blank()
+        char = self.text[self.pos]
+        if char == '"':
+            start = self.pos + 1
+            self._skip_string()
+            self._record(path, start, self.pos - 1)
+        elif char == "{":
+            self._object(path)
+        elif char == "[":
+            self._array(path)
+        else:
+            # Nombre, true, false, null : on passe jusqu'au prochain séparateur.
+            while self.pos < len(self.text) and self.text[self.pos] not in ",]} \t\r\n":
+                self.pos += 1
+
+    def _object(self, path: JsonPath) -> None:
+        self.pos += 1
+        while True:
+            self._skip_blank()
+            if self.text[self.pos] == "}":
+                self.pos += 1
+                return
+            start = self.pos
+            self._skip_string()
+            key = json.loads(self.text[start : self.pos])
+            self._skip_blank()
+            self.pos += 1  # les deux-points
+            self.value((*path, key))
+            self._skip_blank()
+            if self.text[self.pos] == ",":
+                self.pos += 1
+
+    def _array(self, path: JsonPath) -> None:
+        self.pos += 1
+        index = 0
+        while True:
+            self._skip_blank()
+            if self.text[self.pos] == "]":
+                self.pos += 1
+                return
+            self.value((*path, index))
+            index += 1
+            self._skip_blank()
+            if self.text[self.pos] == ",":
+                self.pos += 1
+
+    def _skip_string(self) -> None:
+        """Avance après une chaîne ``"…"`` ; ``pos`` est sur le guillemet ouvrant."""
+        index = self.pos + 1
+        while self.text[index] != '"':
+            index += 2 if self.text[index] == "\\" else 1
+        self.pos = index + 1
+
+    def _record(self, path: JsonPath, start: int, end: int) -> None:
+        line = bisect.bisect_right(self._line_starts, start)
+        self.spans[path] = StringSpan(
+            line=line,
+            column=start - self._line_starts[line - 1],
+            raw=self.text[start:end],
+            literal=False,
+        )
+
+    def _skip_blank(self) -> None:
+        while self.pos < len(self.text) and self.text[self.pos] in " \t\r\n":
+            self.pos += 1