xml-cmpr 0.2.0__py3-none-any.whl

xml_cmpr/cli.py

@@ -0,0 +1,261 @@
+"""Point d'entrée en ligne de commande."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Iterator
+from contextlib import ExitStack, contextmanager
+from pathlib import Path
+
+from .archive import (
+    MAX_ENTRIES,
+    MAX_EXTRACTED_SIZE,
+    ArchiveError,
+    ArchiveSizeError,
+    as_directory,
+    is_archive,
+)
+from .campaign import run_comparison
+from .canonical import ExcludeError
+from .report import DEFAULT_FORMATS, ReportFormat, parse_format, write_reports
+
+EXIT_OK = 0
+EXIT_DIFFERENCES = 1
+EXIT_ERROR = 2
+#: Au moins un fichier n'a pas pu être lu. Distinct de EXIT_DIFFERENCES : la campagne
+#: a bien tourné dans le premier cas, elle est incomplète dans le second.
+EXIT_FILE_ERRORS = 3
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="xml-cmpr",
+        description=(
+            "Compare les fichiers XML de deux sources — répertoire ou archive ZIP — et "
+            "produit un rapport des différences dans le répertoire de sortie."
+        ),
+    )
+    parser.add_argument(
+        "source_a", type=Path, metavar="SOURCE_A", help="source A : répertoire ou archive ZIP"
+    )
+    parser.add_argument(
+        "source_b", type=Path, metavar="SOURCE_B", help="source B : répertoire ou archive ZIP"
+    )
+    parser.add_argument("output", type=Path, metavar="OUTPUT", help="répertoire de sortie")
+    parser.add_argument(
+        "--pattern", default="*.xml", help="motif des fichiers de A (défaut: %(default)s)"
+    )
+    parser.add_argument(
+        "--no-recursive",
+        dest="recursive",
+        action="store_false",
+        help="ne pas descendre dans les sous-répertoires",
+    )
+    parser.add_argument(
+        "--keep-whitespace",
+        action="store_true",
+        help="ne pas normaliser les espaces des nœuds texte",
+    )
+    parser.add_argument(
+        "--exclude",
+        type=Path,
+        metavar="FICHIER",
+        help=(
+            "fichier listant des XPath à exclure de la comparaison (un par ligne, "
+            "'#' pour un commentaire) ; les éléments et attributs sélectionnés n'entrent "
+            "ni dans l'empreinte d'identité ni dans le diff. Sans préfixe déclaré, "
+            "utiliser Q{uri}local pour un nom avec espace de noms"
+        ),
+    )
+    parser.add_argument(
+        "--max-diffs-per-file",
+        type=_max_diffs,
+        default=50,
+        help="nombre de différences détaillées par fichier (défaut: %(default)s, 0 = illimité)",
+    )
+    parser.add_argument(
+        "--format",
+        dest="formats",
+        type=_parse_formats,
+        action="extend",
+        metavar="FORMATS",
+        help=(
+            "formats du rapport, séparés par des virgules ou répétés : md, json (défaut : md,json)"
+        ),
+    )
+    parser.add_argument(
+        "--no-size-limit",
+        dest="archive_limits",
+        action="store_false",
+        help=(
+            "extraire une archive ZIP quels que soient sa taille décompressée et son "
+            "nombre d'entrées (par défaut, au-delà de 1 Gio ou de 100 000 entrées par "
+            "archive, la source est refusée)"
+        ),
+    )
+    parser.add_argument(
+        "--fail-on-diff",
+        action="store_true",
+        help="code de sortie 1 si au moins une différence est détectée",
+    )
+    parser.add_argument(
+        "--fail-on-error",
+        action="store_true",
+        help="code de sortie 3 si au moins un fichier n'a pas pu être lu",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="afficher la progression sur stderr"
+    )
+    return parser
+
+
+def _parse_formats(value: str) -> list[ReportFormat]:
+    """`"md,json"` -> `[MARKDOWN, JSON]`, pour `--format`."""
+    formats = []
+    for chunk in value.split(","):
+        if not chunk.strip():
+            continue
+        try:
+            fmt = parse_format(chunk)
+        except ValueError:
+            expected = ", ".join(f.value for f in ReportFormat)
+            raise argparse.ArgumentTypeError(
+                f"format inconnu : {chunk.strip()} (attendus : {expected})"
+            ) from None
+        if fmt not in formats:
+            formats.append(fmt)
+    if not formats:
+        raise argparse.ArgumentTypeError("aucun format demandé")
+    return formats
+
+
+def _chosen_formats(args: argparse.Namespace) -> list[ReportFormat]:
+    """Formats demandés : ceux de `--format`, dédoublonnés, sinon le défaut."""
+    if args.formats:
+        return list(dict.fromkeys(args.formats))
+    return list(DEFAULT_FORMATS)
+
+
+def _max_diffs(value: str) -> int:
+    """Borne de différences détaillées : un entier positif, `0` valant « illimité ».
+
+    Une valeur négative passerait pour « illimité » sans le dire — la campagne compare
+    `0 < max_diffs < len(differences)` — alors que l'aide n'annonce que `0`.
+    """
+    try:
+        bound = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"nombre entier attendu : {value!r}") from None
+    if bound < 0:
+        raise argparse.ArgumentTypeError(f"borne négative : {bound} (utiliser 0 pour « illimité »)")
+    return bound
+
+
+def _read_exclude_file(path: Path) -> list[str]:
+    """Lit un fichier de XPath à exclure : un par ligne.
+
+    Une ligne dont le premier caractère non blanc est `#` est un commentaire. Partout
+    ailleurs le `#` appartient au XPath : les URI de namespace se terminent souvent par
+    `#` (`Q{http://www.w3.org/1999/02/22-rdf-syntax-ns#}Description`), et couper là
+    rendait la notation `Q{uri}local` inutilisable sur tout un pan des vocabulaires.
+    """
+    xpaths = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        xpath = line.strip()
+        if xpath and not xpath.startswith("#"):
+            xpaths.append(xpath)
+    return xpaths
+
+
+@contextmanager
+def _open_source(source: Path, label: str, verbose: bool, limits: bool) -> Iterator[Path]:
+    """Répertoire de travail pour une source, en extrayant l'archive le cas échéant.
+
+    `limits` faux lève d'un coup les deux bornes d'extraction : `--no-size-limit` vaut
+    pour le volume comme pour le nombre d'entrées.
+    """
+    if verbose and is_archive(source):
+        print(f"… extraction de {source}", file=sys.stderr)
+    with as_directory(
+        source,
+        label=label,
+        size_limit=MAX_EXTRACTED_SIZE if limits else None,
+        entry_limit=MAX_ENTRIES if limits else None,
+    ) as directory:
+        yield directory
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    exclude_xpaths: list[str] | None = None
+    if args.exclude is not None:
+        if not args.exclude.is_file():
+            print(f"erreur : fichier d'exclusion introuvable : {args.exclude}", file=sys.stderr)
+            return EXIT_ERROR
+        try:
+            exclude_xpaths = _read_exclude_file(args.exclude)
+        except (OSError, UnicodeDecodeError) as err:
+            print(f"erreur : fichier d'exclusion illisible : {err}", file=sys.stderr)
+            return EXIT_ERROR
+
+    try:
+        args.output.mkdir(parents=True, exist_ok=True)
+    except OSError as err:
+        print(f"erreur : répertoire de sortie inutilisable : {err}", file=sys.stderr)
+        return EXIT_ERROR
+
+    try:
+        with ExitStack() as stack:
+            dir_a = stack.enter_context(
+                _open_source(args.source_a, "a", args.verbose, args.archive_limits)
+            )
+            dir_b = stack.enter_context(
+                _open_source(args.source_b, "b", args.verbose, args.archive_limits)
+            )
+            summary = run_comparison(
+                dir_a,
+                dir_b,
+                pattern=args.pattern,
+                recursive=args.recursive,
+                keep_whitespace=args.keep_whitespace,
+                exclude_xpaths=exclude_xpaths,
+                max_diffs_per_file=args.max_diffs_per_file,
+                verbose=args.verbose,
+                label_a=args.source_a,
+                label_b=args.source_b,
+            )
+    except ArchiveSizeError as err:
+        print(f"erreur : {err} (--no-size-limit pour l'extraire quand même)", file=sys.stderr)
+        return EXIT_ERROR
+    except ArchiveError as err:
+        print(f"erreur : {err}", file=sys.stderr)
+        return EXIT_ERROR
+    except ExcludeError as err:
+        print(f"erreur : XPath d'exclusion invalide : {err}", file=sys.stderr)
+        return EXIT_ERROR
+
+    written = write_reports(summary, args.output, _chosen_formats(args))
+
+    print(
+        f"{len(summary.results)} fichier(s) analysé(s) · "
+        f"{len(summary.identical)} identique(s) · "
+        f"{len(summary.different)} différent(s) · "
+        f"{len(summary.errored)} en erreur · "
+        f"{len(summary.skipped)} ignoré(s)"
+    )
+    for path in written:
+        print(f"rapport : {path}")
+
+    # Les erreurs passent avant les différences : une campagne incomplète est un
+    # résultat moins sûr qu'une campagne qui a tout comparé.
+    if args.fail_on_error and summary.errored:
+        return EXIT_FILE_ERRORS
+    if args.fail_on_diff and summary.different:
+        return EXIT_DIFFERENCES
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xml_cmpr/diff.py

@@ -0,0 +1,181 @@
+"""Comparaison structurelle de deux arbres canoniques.
+
+L'appariement des éléments frères se fait en trois passes : d'abord sur l'empreinte des
+sous-arbres (les blocs strictement identiques s'alignent), puis, à l'intérieur des trous,
+sur le nom des éléments (deux éléments de même nom sont alors comparés en détail plutôt
+que rapportés comme une suppression suivie d'un ajout), enfin, dans ce qui reste, sur le
+contenu hors nom (deux éléments qui ne diffèrent que par leur nom sont un renommage).
+C'est ce qui fait qu'une insertion au milieu d'une liste coûte une différence et non un
+décalage en cascade.
+
+Un renommage n'est reconnu que si le contenu est strictement le même : un élément à la
+fois renommé et modifié reste une suppression suivie d'un ajout, faute de quoi deux
+éléments sans rapport finiraient appariés pour la seule raison qu'ils occupent la même
+place.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import Counter
+from collections.abc import Callable, Iterator
+from difflib import SequenceMatcher
+
+from .model import Difference, Kind, Node, clark_local, display_name
+
+#: Une paire de frères appariés, désignés par leur position — `None` d'un côté quand
+#: l'élément n'existe que de l'autre.
+Pair = tuple[int | None, int | None]
+
+
+def diff_documents(a: Node, b: Node) -> list[Difference]:
+    """Liste des différences entre deux documents canoniques, en ordre de lecture de A."""
+    differences: list[Difference] = []
+    _diff_nodes(a, b, "/" + a.local_name, differences)
+    return differences
+
+
+def _diff_nodes(a: Node, b: Node, path: str, out: list[Difference]) -> None:
+    if a.fingerprint == b.fingerprint:
+        return
+
+    if a.name != b.name:
+        out.append(
+            Difference(path, Kind.ELEMENT_RENAMED, display_name(a.name), display_name(b.name))
+        )
+
+    _diff_attributes(a, b, path, out)
+
+    if a.text != b.text:
+        out.append(Difference(path, Kind.TEXT_CHANGED, a.text, b.text))
+
+    _diff_children(a, b, path, out)
+
+
+def _diff_attributes(a: Node, b: Node, path: str, out: list[Difference]) -> None:
+    for name in sorted(a.attrs.keys() | b.attrs.keys()):
+        value_a = a.attrs.get(name)
+        value_b = b.attrs.get(name)
+        if value_a == value_b:
+            continue
+        attr_path = f"{path}/@{clark_local(name)}"
+        if value_a is None:
+            out.append(Difference(attr_path, Kind.ATTRIBUTE_ADDED, None, value_b))
+        elif value_b is None:
+            out.append(Difference(attr_path, Kind.ATTRIBUTE_REMOVED, value_a, None))
+        else:
+            out.append(Difference(attr_path, Kind.ATTRIBUTE_CHANGED, value_a, value_b))
+
+
+def _diff_children(a: Node, b: Node, path: str, out: list[Difference]) -> None:
+    segments_a = _segments(a.children)
+    segments_b = _segments(b.children)
+
+    for i, j in _align(a.children, b.children):
+        if i is not None and j is not None:
+            _diff_nodes(a.children[i], b.children[j], f"{path}/{segments_a[i]}", out)
+        elif i is not None:
+            child_a = a.children[i]
+            kind = Kind.TEXT_REMOVED if child_a.is_text else Kind.ELEMENT_REMOVED
+            out.append(Difference(f"{path}/{segments_a[i]}", kind, child_a.summary(), None))
+        elif j is not None:
+            child_b = b.children[j]
+            kind = Kind.TEXT_ADDED if child_b.is_text else Kind.ELEMENT_ADDED
+            out.append(Difference(f"{path}/{segments_b[j]}", kind, None, child_b.summary()))
+
+
+def _segments(nodes: list[Node]) -> list[str]:
+    """Segment de chemin de chaque enfant, avec prédicat quand le nom est répété."""
+    totals = Counter(node.local_name for node in nodes)
+    seen: Counter[str] = Counter()
+    segments = []
+    for node in nodes:
+        local = node.local_name
+        seen[local] += 1
+        segments.append(f"{local}[{seen[local]}]" if totals[local] > 1 else local)
+    return segments
+
+
+def _align(a_nodes: list[Node], b_nodes: list[Node]) -> Iterator[Pair]:
+    """Apparie deux listes de frères : par sous-arbre identique, par nom, puis par contenu.
+
+    L'appariement rend des **positions**, jamais les nœuds eux-mêmes : deux frères
+    peuvent être égaux, voire être le même objet `Node` réutilisé à deux places par un
+    appelant de l'API, et doivent malgré tout garder chacun leur chemin au rapport.
+    """
+    yield from _cascade(
+        a_nodes, b_nodes, list(range(len(a_nodes))), list(range(len(b_nodes))), _KEYS
+    )
+
+
+def _fingerprint(node: Node) -> str:
+    return node.fingerprint
+
+
+def _name(node: Node) -> str:
+    return node.name
+
+
+def _content(node: Node) -> str:
+    """Clé de la passe « renommage » : le contenu hors nom, pour un élément seulement.
+
+    Calculée à la demande, sur les seuls frères restés sans partenaire : la payer à la
+    construction de chaque `Node` coûterait un second hachage par élément de chaque
+    document, pour une passe qui ne voit d'ordinaire que quelques nœuds.
+
+    Un nœud texte garde son empreinte complète : `{}#text` contenant « x » et `<a>x</a>`
+    ont le même contenu, mais un texte remplacé par un élément n'est pas un renommage.
+    """
+    if node.is_text:
+        return node.fingerprint
+    h = hashlib.sha256()
+    for key, value in node.attrs.items():
+        h.update(f"{key}\x01{value}\x02".encode())
+    h.update(f"{node.text}\x03".encode())
+    for child in node.children:
+        h.update(child.fingerprint.encode())
+    return h.hexdigest()
+
+
+#: Les passes d'appariement, de la plus stricte à la plus lâche.
+_KEYS: tuple[Callable[[Node], str], ...] = (_fingerprint, _name, _content)
+
+
+def _cascade(
+    a_nodes: list[Node],
+    b_nodes: list[Node],
+    positions_a: list[int],
+    positions_b: list[int],
+    keys: tuple[Callable[[Node], str], ...],
+) -> Iterator[Pair]:
+    """Aligne sur `keys[0]`, puis rejoue les passes suivantes dans chaque trou.
+
+    Ce qui reste sans partenaire après la dernière passe est rendu non apparié.
+    """
+    if not keys or not positions_a or not positions_b:
+        yield from ((i, None) for i in positions_a)
+        yield from ((None, j) for j in positions_b)
+        return
+    for tag, chunk_a, chunk_b in _blocks(a_nodes, b_nodes, positions_a, positions_b, keys[0]):
+        if tag == "equal":
+            yield from zip(chunk_a, chunk_b, strict=True)
+        else:
+            yield from _cascade(a_nodes, b_nodes, chunk_a, chunk_b, keys[1:])
+
+
+def _blocks(
+    a_nodes: list[Node],
+    b_nodes: list[Node],
+    positions_a: list[int],
+    positions_b: list[int],
+    key: Callable[[Node], str],
+) -> Iterator[tuple[str, list[int], list[int]]]:
+    """Découpe deux suites de positions en blocs alignés (`equal`) et en trous, selon `key`."""
+    matcher = SequenceMatcher(
+        None,
+        [key(a_nodes[i]) for i in positions_a],
+        [key(b_nodes[j]) for j in positions_b],
+        autojunk=False,
+    )
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        yield tag, positions_a[i1:i2], positions_b[j1:j2]

xml_cmpr/discovery.py

@@ -0,0 +1,40 @@
+"""Parcours du répertoire source A et appariement avec le répertoire source B."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class Pairing:
+    """Fichiers de A appariés avec leur homologue de B, et ceux qui n'en ont pas."""
+
+    matched: list[tuple[str, Path, Path]] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+
+
+def discover(
+    source_a: Path,
+    source_b: Path,
+    *,
+    pattern: str = "*.xml",
+    recursive: bool = True,
+) -> Pairing:
+    """Apparie les fichiers de `source_a` avec ceux de `source_b`.
+
+    La clé d'appariement est le chemin relatif à la racine de chaque source. Un fichier
+    de A sans homologue dans B est ignoré (et signalé dans `skipped`).
+    """
+    pairing = Pairing()
+    candidates = source_a.rglob(pattern) if recursive else source_a.glob(pattern)
+    for path_a in sorted(candidates):
+        if not path_a.is_file():
+            continue
+        relative = path_a.relative_to(source_a).as_posix()
+        path_b = source_b / relative
+        if path_b.is_file():
+            pairing.matched.append((relative, path_a, path_b))
+        else:
+            pairing.skipped.append(relative)
+    return pairing

xml_cmpr/model.py

@@ -0,0 +1,207 @@
+"""Structures de données partagées par tout le pipeline de comparaison."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+
+#: Pseudo-nom d'un nœud texte de contenu mixte, tel que l'émet `normalize.xsl`.
+TEXT_NODE = "{}#text"
+
+
+def clark_local(name: str) -> str:
+    """`{urn:f}Ligne` -> `Ligne`. Un nom sans namespace est rendu tel quel."""
+    if name.startswith("{"):
+        return name[name.index("}") + 1 :]
+    return name
+
+
+def display_name(name: str) -> str:
+    """Nom d'élément tel qu'affiché au rapport : local sans namespace, Clark sinon.
+
+    `{}Ligne` -> `Ligne`, `{urn:f}Ligne` -> `{urn:f}Ligne` : l'URI ne s'affiche que
+    lorsqu'elle existe, puisque c'est alors elle qui distingue deux noms.
+    """
+    return name if clark_uri(name) else clark_local(name)
+
+
+def clark_uri(name: str) -> str:
+    """`{urn:f}Ligne` -> `urn:f`. Chaîne vide si le nom n'est pas dans un namespace."""
+    if name.startswith("{"):
+        return name[1 : name.index("}")]
+    return ""
+
+
+@dataclass(slots=True)
+class Node:
+    """Un élément de la forme canonique.
+
+    `name` est en notation de Clark (`{uri}local`), `attrs` est trié par nom, et `text`
+    est la concaténation normalisée des nœuds texte enfants directs. Les commentaires et
+    instructions de traitement conservés apparaissent dans `children` sous les pseudo-noms
+    `{}#comment` et `{}#pi`.
+
+    En contenu mixte — du texte et des éléments sous le même parent — `text` est vide et
+    chaque nœud texte est un enfant `{}#text` à sa place dans `children` : c'est ce qui
+    fait qu'un texte déplacé autour d'un élément compte comme une différence.
+    """
+
+    name: str
+    attrs: dict[str, str] = field(default_factory=dict)
+    text: str = ""
+    children: list[Node] = field(default_factory=list)
+    fingerprint: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        h = hashlib.sha256()
+        h.update(self.name.encode())
+        h.update(b"\x00")
+        for key, value in self.attrs.items():
+            h.update(key.encode())
+            h.update(b"\x01")
+            h.update(value.encode())
+            h.update(b"\x02")
+        h.update(self.text.encode())
+        h.update(b"\x03")
+        for child in self.children:
+            h.update(child.fingerprint.encode())
+        self.fingerprint = h.hexdigest()
+
+    @property
+    def local_name(self) -> str:
+        return clark_local(self.name)
+
+    @property
+    def namespace(self) -> str:
+        return clark_uri(self.name)
+
+    @property
+    def is_text(self) -> bool:
+        """Vrai pour un nœud texte de contenu mixte, faux pour un élément."""
+        return self.name == TEXT_NODE
+
+    def summary(self, max_len: int = 60) -> str:
+        """Représentation courte d'un sous-arbre, pour la colonne d'un rapport."""
+        if self.is_text:
+            rendered = self.text
+        else:
+            attrs = "".join(f' {clark_local(k)}="{v}"' for k, v in self.attrs.items())
+            inner = self.text or ("…" if self.children else "")
+            rendered = f"<{self.local_name}{attrs}>{inner}"
+        if len(rendered) > max_len:
+            rendered = rendered[: max_len - 1] + "…"
+        return rendered
+
+    @classmethod
+    def from_json(cls, data: dict) -> Node:
+        """Reconstruit un arbre depuis la sortie JSON de `normalize.xsl`."""
+        return cls(
+            name=data["n"],
+            attrs=dict(data["a"]),
+            text=data["t"],
+            children=[cls.from_json(child) for child in data["c"]],
+        )
+
+
+class Kind(StrEnum):
+    """Nature d'une différence. La valeur sert de libellé dans le rapport."""
+
+    ELEMENT_ADDED = "élément ajouté en B"
+    ELEMENT_REMOVED = "élément absent de B"
+    ELEMENT_RENAMED = "élément renommé"
+    ATTRIBUTE_ADDED = "attribut ajouté en B"
+    ATTRIBUTE_REMOVED = "attribut absent de B"
+    ATTRIBUTE_CHANGED = "attribut modifié"
+    TEXT_CHANGED = "texte modifié"
+    TEXT_ADDED = "texte ajouté en B"
+    TEXT_REMOVED = "texte absent de B"
+
+
+@dataclass(slots=True, frozen=True)
+class Difference:
+    path: str
+    kind: Kind
+    value_a: str | None = None
+    value_b: str | None = None
+
+    def as_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "kind": self.kind.name.lower(),
+            "label": str(self.kind),
+            "a": self.value_a,
+            "b": self.value_b,
+        }
+
+
+class Status(StrEnum):
+    IDENTICAL = "identique"
+    DIFFERENT = "different"
+    ERROR = "erreur"
+
+
+@dataclass(slots=True)
+class FileResult:
+    """Résultat de la comparaison d'un fichier, désigné par son chemin relatif."""
+
+    path: str
+    status: Status
+    differences: list[Difference] = field(default_factory=list)
+    error: str | None = None
+    truncated: int = 0
+
+    def as_dict(self) -> dict:
+        data: dict = {"path": self.path, "status": self.status.value}
+        if self.status is Status.DIFFERENT:
+            data["differences"] = [d.as_dict() for d in self.differences]
+            if self.truncated:
+                data["truncated"] = self.truncated
+        if self.error:
+            data["error"] = self.error
+        return data
+
+
+@dataclass(slots=True)
+class RunSummary:
+    """Bilan d'une campagne de comparaison.
+
+    `generated_at` date la campagne (heure locale, avec son décalage) : c'est la même
+    date que portent le rapport Markdown et le rapport JSON.
+    """
+
+    source_a: Path
+    source_b: Path
+    results: list[FileResult] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    generated_at: datetime = field(default_factory=lambda: datetime.now(tz=UTC).astimezone())
+
+    @property
+    def identical(self) -> list[FileResult]:
+        return [r for r in self.results if r.status is Status.IDENTICAL]
+
+    @property
+    def different(self) -> list[FileResult]:
+        return [r for r in self.results if r.status is Status.DIFFERENT]
+
+    @property
+    def errored(self) -> list[FileResult]:
+        return [r for r in self.results if r.status is Status.ERROR]
+
+    def as_dict(self) -> dict:
+        return {
+            "summary": {
+                "source_a": str(self.source_a),
+                "source_b": str(self.source_b),
+                "generated_at": self.generated_at.isoformat(timespec="seconds"),
+                "analyzed": len(self.results),
+                "identical": len(self.identical),
+                "different": len(self.different),
+                "errors": len(self.errored),
+                "skipped": len(self.skipped),
+            },
+            "files": [r.as_dict() for r in self.results],
+            "skipped": self.skipped,
+        }