rdfdiff 0.1.0__py3-none-any.whl

rdfdiff-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: rdfdiff
+Version: 0.1.0
+Summary: Read an RDF file's Git history as semantic change rather than text
+Project-URL: Homepage, https://github.com/gbelbe/semanticdiff
+Project-URL: Repository, https://github.com/gbelbe/semanticdiff
+Project-URL: Issues, https://github.com/gbelbe/semanticdiff/issues
+License: MIT License
+        
+        Copyright (c) 2024 gbelbe
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: diff,git,ontology,owl,rdf,semantic-web,skos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.12
+Requires-Dist: rdflib>=7.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rdfdiff
+
+`rdfdiff` reads an RDF file's Git history as changes to its vocabulary,
+rather than as changed characters. It reports classes, properties, individuals,
+
+Equivalent RDF serializations produce no semantic change, so reformatting,
+prefix changes, reordered triples, and blank-node relabeling do not hide actual
+ontology evolution.
+
+## Install
+
+```sh
+uv tool install rdfdiff
+```
+
+Or run the current checkout:
+
+```sh
+uv run semanticdiff log --repo /path/to/ontology-repository
+```
+
+## Use
+
+Summarize every commit that changed an RDF file:
+
+```sh
+semanticdiff log v0.1..v0.2 --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+Trace one entity through a revision range:
+
+```sh
+semanticdiff show ex:Product v0.1..HEAD --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+When a repository has exactly one tracked RDF file, `--file` is optional. Use
+`--text` with `log` to append Git's raw hunks after the semantic report.
+
+## Library API
+
+```python
+from rdflib import Graph
+from semanticdiff import compare
+
+changes = compare(before_graph, after_graph)
+```
+
+`read_history(repo, revision_range, path)` pairs each commit touching `path`
+with its semantic change set. The public vocabulary is exported from the package
+root: `Change`, `ChangeKind`, `ChangeSet`, `CommitChanges`, and `EntityKind`.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy semanticdiff
+uv run pytest -q
+```
+
+The distribution is named `rdfdiff`; its Python import and command-line command
+remain `semanticdiff`. The project deliberately has no dependency on Ster. Ster
+can consume it as an optional integration, but the diff engine and command-line
+tool remain usable with any RDF repository.
+
+## Releases
+
+Releases are published to PyPI by the `pypi-publish.yml` GitHub Actions workflow
+when a `v*` tag is pushed. PyPI trusted publishing must be configured for the
+`gbelbe/semanticdiff` repository, the `pypi-publish.yml` workflow, and the
+  `pypi` environment before the first release tag is created. The pending PyPI
+  publisher must use the `rdfdiff` project name.

rdfdiff-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+semanticdiff/__init__.py,sha256=MAAV8z_tBFUgbniDPwKrSv_wrStKCkEOCyOu763LrYI,831
+semanticdiff/changeset.py,sha256=99ULB_VhFHo8BItWDsANpeVo2u0reIqiyH2xlHumqFw,9577
+semanticdiff/cli.py,sha256=6fE9T00f_lQHRhsc1IwhVMKM6DSFvr96OUIyP7r2CLc,2722
+semanticdiff/git_log.py,sha256=2YT9xXUQIgaYfXITndI3b6UjHYNSFW3U-Q2J8y29nJA,5302
+semanticdiff/history.py,sha256=kWfChXupb5N1USHhcYOkt120P1rjE1-6pbcr2CEYv04,2764
+semanticdiff/loader.py,sha256=qACunIcTLS8dkKMazKLs_6MSHWfIZgG2Z415OPOnidE,990
+semanticdiff/rename.py,sha256=iGuweAn4VcZXg_lkq7oJGyk7Bt9X-LX7gu6fKct6Gcc,2534
+semanticdiff/vocabulary.py,sha256=stgZTFkZwCpfr3vmICM3HIHxrfRp-MzyZC9F6C8_5e8,2738
+semanticdiff/render/__init__.py,sha256=Iv7PBMJRRXp77JUqe6yfZAKj0rRWe-YjrEAaIPLzpLg,221
+semanticdiff/render/rows.py,sha256=fl9w_HckXPEkVbgFmgosDns_LZ4D5QClqL618m8GPfE,3450
+semanticdiff/render/text.py,sha256=ceoj8VGf-RbRxRSsBZtUjpjBwOVdxOBktW8JB9XZiHo,4921
+rdfdiff-0.1.0.dist-info/METADATA,sha256=wOyUf0-T-T9s0U40HY31qwomevZcnT-4FkIk7DQKghg,4403
+rdfdiff-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+rdfdiff-0.1.0.dist-info/entry_points.txt,sha256=vo1WoU7qzzOXe8eq2ZkMPu4zV18AXDBS4hMLKuUYExI,55
+rdfdiff-0.1.0.dist-info/licenses/LICENSE,sha256=4V9QsmJCQc_Zmtcr2VMGiIEtCVI6ALbQxCzYpzUusvQ,1063
+rdfdiff-0.1.0.dist-info/RECORD,,

rdfdiff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

rdfdiff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semanticdiff = semanticdiff.cli:main

rdfdiff-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 gbelbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semanticdiff/__init__.py

@@ -0,0 +1,26 @@
+"""semanticdiff — read a git history of an RDF file as semantic change.
+
+A git diff reports characters. This package reports the vocabulary: which
+classes, properties and concepts were added, modified, renamed, deprecated or
+removed in each commit, so the raw text only has to be opened when the summary
+is not enough.
+
+It deliberately depends on nothing from `ster` — an import contract enforces
+that — so it can be extracted into its own distribution unchanged.
+"""
+
+from __future__ import annotations
+
+from semanticdiff.changeset import compare
+from semanticdiff.history import CommitChanges, read_history
+from semanticdiff.vocabulary import Change, ChangeKind, ChangeSet, EntityKind
+
+__all__ = [
+    "Change",
+    "ChangeKind",
+    "ChangeSet",
+    "CommitChanges",
+    "EntityKind",
+    "compare",
+    "read_history",
+]

semanticdiff/changeset.py

@@ -0,0 +1,243 @@
+"""The semantic core: two graphs in, a set of change operations out.
+
+Pure — no git, no files, no I/O — so the whole vocabulary of change is testable
+from turtle strings. The engine is rdflib's `graph_diff` over the isomorphic
+(blank-node-canonical) form of each graph, which is what makes a re-serialised
+file report as unchanged.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+
+from rdflib import BNode, Graph, Literal, URIRef
+from rdflib.compare import graph_diff, to_isomorphic
+from rdflib.namespace import OWL, RDF, RDFS, SKOS
+from rdflib.term import Node
+
+from semanticdiff.rename import detect_renames
+from semanticdiff.vocabulary import Change, ChangeKind, ChangeSet, EntityKind
+
+# Predicates whose *object* is also touched by the triple. Adding
+# `ex:Vehicle rdfs:subClassOf ex:Product` changes ex:Product too, although
+# ex:Product is never a subject of the added triples; without this table the
+# sentence "class X gained 2 properties" cannot be produced at all. Kept to
+# four entries on purpose — every addition here is a new source of noise.
+_OBJECT_ATTRIBUTION: dict[URIRef, tuple[str, str]] = {
+    RDFS.subClassOf: ("subclass", "subclasses"),
+    SKOS.broader: ("narrower concept", "narrower concepts"),
+    RDFS.domain: ("property", "properties"),
+    RDFS.range: ("property range", "property ranges"),
+}
+
+# Predicates reported as a value transition on the subject: "domain A → B".
+_TRANSITIONS: dict[URIRef, str] = {RDFS.domain: "domain", RDFS.range: "range"}
+
+_TYPE_KINDS: dict[URIRef, EntityKind] = {
+    OWL.Class: EntityKind.CLASS,
+    RDFS.Class: EntityKind.CLASS,
+    OWL.ObjectProperty: EntityKind.PROPERTY,
+    OWL.DatatypeProperty: EntityKind.PROPERTY,
+    OWL.AnnotationProperty: EntityKind.PROPERTY,
+    RDF.Property: EntityKind.PROPERTY,
+    SKOS.Concept: EntityKind.CONCEPT,
+    OWL.Ontology: EntityKind.ONTOLOGY,
+    OWL.NamedIndividual: EntityKind.INDIVIDUAL,
+}
+
+_LABEL_PREDICATES = (SKOS.prefLabel, RDFS.label)
+
+_DEPRECATED = Literal(True)
+
+
+@dataclass(frozen=True)
+class _Delta:
+    """The two delta graphs, plus their incoming edges indexed by object.
+
+    The index exists because the alternative is quadratic. Attributing
+    "+2 properties" to a class means counting the triples pointing *at* it, and
+    scanning the delta once per entity costs entities x delta: on a commit
+    touching 1 827 entities that was 15s of a 16s diff. Indexed once, it is a
+    single pass and a dict lookup each.
+    """
+
+    only_base: Graph
+    only_later: Graph
+    lost: dict[Node, Counter[Node]]
+    gained: dict[Node, Counter[Node]]
+
+
+def compare(base: Graph, later: Graph) -> ChangeSet:
+    """The change operations taking `base` to `later`."""
+    _, only_base, only_later = graph_diff(to_isomorphic(base), to_isomorphic(later))
+    delta = _Delta(
+        only_base=only_base,
+        only_later=only_later,
+        lost=_incoming_index(only_base),
+        gained=_incoming_index(only_later),
+    )
+    touched = _touched(only_base) | _touched(only_later) | _changed_owners(base, later)
+    changes = (_describe(uri, base, later, delta) for uri in sorted(touched))
+    return detect_renames(ChangeSet(tuple(c for c in changes if c is not None)))
+
+
+def _incoming_index(delta: Graph) -> dict[Node, Counter[Node]]:
+    """`{object: {predicate: count}}` for the predicates that credit their object."""
+    index: dict[Node, Counter[Node]] = defaultdict(Counter)
+    for _, predicate, obj in delta:
+        if predicate in _OBJECT_ATTRIBUTION:
+            index[obj][predicate] += 1
+    return index
+
+
+def _touched(delta: Graph) -> set[URIRef]:
+    """Every named entity implicated by the triples in `delta`."""
+    touched: set[URIRef] = set()
+    for subject, predicate, obj in delta:
+        if isinstance(subject, URIRef):
+            touched.add(subject)
+        if predicate in _OBJECT_ATTRIBUTION and isinstance(obj, URIRef):
+            touched.add(obj)
+    return touched
+
+
+def _changed_owners(base: Graph, later: Graph) -> set[URIRef]:
+    """Named entities whose blank-node description changed.
+
+    A change inside a blank node — a restriction's cardinality, a member of an
+    anonymous union, an item in an RDF list — has a blank node as its subject, so
+    subject attribution alone discards it, and the triple joining the owner to the
+    blank node does not itself change. The edit would then be reported nowhere at
+    all, which a reader cannot tell apart from "nothing changed".
+
+    The blank nodes in the diff cannot be traced back: graph_diff canonicalises
+    them, so their identity no longer matches either source graph. Instead each
+    entity that owns a blank node has its description (itself plus everything
+    reachable through blank nodes) compared between the two revisions.
+
+    Only entities that actually own a blank node are examined, so an ontology
+    without any — the common case — pays nothing for this.
+    """
+    owners = {
+        subject
+        for graph in (base, later)
+        for subject, _, obj in graph
+        if isinstance(subject, URIRef) and isinstance(obj, BNode)
+    }
+    return {uri for uri in owners if not _same_description(base, later, uri)}
+
+
+def _same_description(base: Graph, later: Graph, uri: URIRef) -> bool:
+    """Whether the entity's blank-node closure is the same graph on both sides."""
+    return to_isomorphic(base.cbd(uri)) == to_isomorphic(later.cbd(uri))
+
+
+def _describe(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> Change | None:
+    """One change for `uri`, or None when it is only ever referenced, never defined."""
+    in_base = (uri, None, None) in base
+    in_later = (uri, None, None) in later
+    if not in_base and not in_later:
+        return None
+    source = later if in_later else base
+    label, lang = _label(source, uri)
+    return Change(
+        kind=_kind(uri, base, later, in_base=in_base, in_later=in_later),
+        entity=_entity_kind(source, uri),
+        uri=str(uri),
+        curie=_curie(source, uri),
+        label=label,
+        label_lang=lang,
+        detail=_detail(uri, base, later, delta),
+        of_class=_of_class(source, uri),
+    )
+
+
+def _kind(uri: URIRef, base: Graph, later: Graph, *, in_base: bool, in_later: bool) -> ChangeKind:
+    if not in_base:
+        return ChangeKind.ADDED
+    if not in_later:
+        return ChangeKind.REMOVED
+    if (uri, OWL.deprecated, _DEPRECATED) in later and (
+        uri,
+        OWL.deprecated,
+        _DEPRECATED,
+    ) not in base:
+        return ChangeKind.DEPRECATED
+    return ChangeKind.MODIFIED
+
+
+def _entity_kind(graph: Graph, uri: URIRef) -> EntityKind:
+    for type_uri in graph.objects(uri, RDF.type):
+        if isinstance(type_uri, URIRef) and (kind := _TYPE_KINDS.get(type_uri)) is not None:
+            return kind
+    if (uri, RDF.type, None) in graph:
+        return EntityKind.INDIVIDUAL
+    return EntityKind.OTHER
+
+
+def _of_class(graph: Graph, uri: URIRef) -> str | None:
+    """The class an individual instantiates, as the name a reader should see.
+
+    Sorted so a multi-typed individual always reports the same one, and skipping
+    owl:NamedIndividual, which says nothing about what the thing is.
+    """
+    types = sorted(
+        str(t)
+        for t in graph.objects(uri, RDF.type)
+        if isinstance(t, URIRef) and t != OWL.NamedIndividual and t not in _TYPE_KINDS
+    )
+    if not types:
+        return None
+    cls = URIRef(types[0])
+    label, _ = _label(graph, cls)
+    return label or _curie(graph, cls)
+
+
+def _label(graph: Graph, uri: URIRef) -> tuple[str | None, str | None]:
+    """The entity's preferred label, skos:prefLabel winning over rdfs:label."""
+    for predicate in _LABEL_PREDICATES:
+        literals = sorted(
+            (o for o in graph.objects(uri, predicate) if isinstance(o, Literal)),
+            key=lambda lit: (lit.language or "", str(lit)),
+        )
+        if literals:
+            return str(literals[0]), literals[0].language
+    return None, None
+
+
+def _curie(graph: Graph, uri: Node) -> str:
+    """The prefixed form, or the full URI when no prefix is bound."""
+    try:
+        prefix, _, name = graph.namespace_manager.compute_qname(str(uri), generate=False)
+    except (KeyError, ValueError):
+        return str(uri)
+    return f"{prefix}:{name}" if prefix else str(uri)
+
+
+def _detail(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> tuple[str, ...]:
+    return (*_transitions(uri, base, later, delta), *_attributions(uri, delta))
+
+
+def _transitions(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> tuple[str, ...]:
+    """Single-valued predicates that moved, read as 'domain ex:Place → ex:Site'."""
+    parts = []
+    for predicate, name in _TRANSITIONS.items():
+        before = list(delta.only_base.objects(uri, predicate))
+        after = list(delta.only_later.objects(uri, predicate))
+        if len(before) == 1 and len(after) == 1:
+            parts.append(f"{name} {_curie(base, before[0])} → {_curie(later, after[0])}")
+    return tuple(parts)
+
+
+def _attributions(uri: URIRef, delta: _Delta) -> tuple[str, ...]:
+    """What the entity gained or lost through triples pointing at it."""
+    gained = delta.gained.get(uri, Counter())
+    lost = delta.lost.get(uri, Counter())
+    parts = []
+    for predicate, (singular, plural) in _OBJECT_ATTRIBUTION.items():
+        for sign, counted in (("+", gained), ("-", lost)):
+            total = counted[predicate]
+            if total:
+                parts.append(f"{sign}{total} {singular if total == 1 else plural}")
+    return tuple(parts)

semanticdiff/cli.py

@@ -0,0 +1,82 @@
+"""The semanticdiff command line."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from semanticdiff.git_log import RDF_SUFFIXES, GitError, list_tracked
+from semanticdiff.history import read_history
+from semanticdiff.render.text import render_commits, render_entity, render_summary
+
+app = typer.Typer(
+    help="Read a git history of an ontology as semantic change, not as text.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+_REPO = typer.Option(Path("."), "--repo", help="Repository to read.")
+_FILE = typer.Option(None, "--file", help="Tracked RDF file. Autodetected when omitted.")
+_RANGE = typer.Argument("HEAD", help="Revision range, e.g. v0.1..v0.2.")
+
+
+@app.command()
+def log(
+    rev_range: str = _RANGE,
+    repo: Path = _REPO,
+    file: str | None = _FILE,
+    text: bool = typer.Option(False, "--text", help="Also print the raw diff hunks."),
+) -> None:
+    """Summarise every commit in the range as semantic change."""
+    path, history = _load(repo, rev_range, file, with_text=text)
+    typer.echo(path)
+    typer.echo(render_summary(history, rev_range))
+    typer.echo("")
+    typer.echo(render_commits(history, show_text=text))
+
+
+@app.command()
+def show(
+    uri: str = typer.Argument(..., help="Entity to trace, as a CURIE or a full URI."),
+    rev_range: str = _RANGE,
+    repo: Path = _REPO,
+    file: str | None = _FILE,
+) -> None:
+    """Trace one entity through the history."""
+    _, history = _load(repo, rev_range, file, with_text=False)
+    typer.echo(render_entity(history, uri))
+
+
+def _load(repo: Path, rev_range: str, file: str | None, *, with_text: bool) -> tuple[str, list]:
+    if not (repo / ".git").exists():
+        raise _fail(f"{repo} is not a git repository")
+    path = file or _detect(repo)
+    try:
+        return path, read_history(repo, rev_range, path, with_text=with_text)
+    except (GitError, FileNotFoundError) as exc:
+        raise _fail(str(exc)) from exc
+
+
+def _detect(repo: Path) -> str:
+    """The repository's one tracked RDF file, or an error naming the alternatives."""
+    try:
+        tracked = list_tracked(repo)
+    except GitError as exc:
+        raise _fail(str(exc)) from exc
+    candidates = [f for f in tracked if Path(f).suffix.lower() in RDF_SUFFIXES]
+    if not candidates:
+        raise _fail("no RDF file is tracked in this repository; pass --file")
+    if len(candidates) > 1:
+        raise _fail(f"several RDF files tracked ({', '.join(candidates)}); pass --file")
+    return candidates[0]
+
+
+def _fail(message: str) -> typer.Exit:
+    """Report on stdout and exit non-zero — errors are part of the output, not a traceback."""
+    typer.echo(message)
+    return typer.Exit(1)
+
+
+def main() -> None:
+    app()

semanticdiff/git_log.py

@@ -0,0 +1,160 @@
+"""The git adapter — the only module that shells out to git.
+
+Everything above this file works on graphs and dataclasses, so a change of
+version-control backend touches one module.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+RDF_SUFFIXES = frozenset({".ttl", ".rdf", ".owl", ".jsonld", ".nt", ".n3", ".trig", ".nq"})
+
+_FIELD = "\x1f"
+_RECORD = "\x1e"
+_FORMAT = f"{_RECORD}%H{_FIELD}%h{_FIELD}%an{_FIELD}%aI{_FIELD}%s"
+
+
+class GitError(RuntimeError):
+    """git refused the command."""
+
+
+class UnknownRevisionError(GitError):
+    """The revision or range does not resolve in this repository."""
+
+
+@dataclass(frozen=True)
+class Commit:
+    """One commit that touched the tracked ontology."""
+
+    sha: str
+    short_sha: str
+    author: str
+    date: str
+    subject: str
+    other_files: int = 0
+
+
+def walk(repo: Path, rev_range: str, path: str) -> list[Commit]:
+    """Commits in `rev_range` that touched `path`, oldest first."""
+    _require_tracked(repo, path)
+    out = _git(repo, "log", "--reverse", f"--format={_FORMAT}", "--name-only", rev_range)
+    return list(_records(out, path))
+
+
+def raw_diff(repo: Path, sha: str, path: str) -> str:
+    """The unified diff hunk for `path` in one commit — the last layer of the drill-down."""
+    return _git(repo, "show", "--format=", sha, "--", path)
+
+
+def read_blob(repo: Path, rev: str, path: str) -> str | None:
+    """The file's content at a revision, or None when it does not exist there."""
+    result = _run(repo, "show", f"{rev}:{path}")
+    return None if result.returncode != 0 else result.stdout
+
+
+def list_tracked(repo: Path) -> list[str]:
+    """Every path git tracks at HEAD."""
+    return [line for line in _git(repo, "ls-files").splitlines() if line]
+
+
+def resolve(repo: Path, rev: str) -> str | None:
+    """`rev` as a commit sha, or None when it does not exist (a root's parent).
+
+    Used to key a parse cache: `<sha>^` and the sha of the commit before it name
+    the same revision, and only the resolved form makes them share an entry.
+    """
+    result = _run(repo, "rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}")
+    return result.stdout.strip() or None
+
+
+def repo_root(path: Path) -> Path | None:
+    """The repository `path` lives in, or None when it is not tracked anywhere."""
+    result = _run(path.parent if path.is_file() else path, "rev-parse", "--show-toplevel")
+    if result.returncode != 0:
+        return None
+    return Path(result.stdout.strip())
+
+
+def tags_by_commit(repo: Path) -> dict[str, tuple[str, ...]]:
+    """`{sha: tags}` — the release markers a history list shows beside a commit."""
+    out = _git(repo, "for-each-ref", "--format=%(objectname) %(refname:short)", "refs/tags")
+    tags: dict[str, list[str]] = {}
+    for line in out.splitlines():
+        sha, _, name = line.partition(" ")
+        if name:
+            tags.setdefault(_peel(repo, sha), []).append(name)
+    return {sha: tuple(sorted(names)) for sha, names in tags.items()}
+
+
+def _peel(repo: Path, sha: str) -> str:
+    """The commit a tag points at, following an annotated tag's own object."""
+    return _git(repo, "rev-list", "-n", "1", sha).strip() or sha
+
+
+def _require_tracked(repo: Path, path: str) -> None:
+    """Fail loudly when the path was never in this repository at all.
+
+    Checked over the whole history rather than the requested range, so that an
+    empty range reports no commits instead of a missing file.
+    """
+    if not _git(repo, "log", "--all", "--format=%H", "-n", "1", "--", path).strip():
+        raise FileNotFoundError(f"{path} is not tracked in {repo}")
+
+
+def _records(out: str, path: str) -> Iterator[Commit]:
+    for record in out.split(_RECORD):
+        if not record.strip():
+            continue
+        commit = _record(record, path)
+        if commit is not None:
+            yield commit
+
+
+def _record(record: str, path: str) -> Commit | None:
+    header, _, body = record.strip("\n").partition("\n")
+    sha, short_sha, author, date, subject = header.split(_FIELD)
+    files = [line for line in body.splitlines() if line.strip()]
+    if path not in files:
+        return None
+    return Commit(
+        sha=sha,
+        short_sha=short_sha,
+        author=author,
+        date=date,
+        subject=subject,
+        other_files=sum(1 for f in files if Path(f).suffix.lower() not in RDF_SUFFIXES),
+    )
+
+
+# git translates its messages, so a French machine reports "révision inconnue"
+# where CI reports "unknown revision". Pin the locale rather than the wording.
+_C_LOCALE = {"LC_ALL": "C", "LANG": "C"}
+
+
+def _run(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+        env={**os.environ, **_C_LOCALE},
+    )
+
+
+def _git(repo: Path, *args: str) -> str:
+    result = _run(repo, *args)
+    if result.returncode != 0:
+        raise _translate(result.stderr)
+    return result.stdout
+
+
+def _translate(stderr: str) -> GitError:
+    message = stderr.strip() or "git failed"
+    if "unknown revision" in stderr or "bad revision" in stderr:
+        return UnknownRevisionError(message)
+    return GitError(message)

semanticdiff/history.py

@@ -0,0 +1,80 @@
+"""Orchestration: pair every commit in a range with its semantic change set."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from rdflib import Graph
+
+from semanticdiff.changeset import compare
+from semanticdiff.git_log import Commit, raw_diff, resolve, walk
+from semanticdiff.loader import UnreadableRevisionError, graph_at_rev
+from semanticdiff.vocabulary import ChangeSet
+
+
+@dataclass(frozen=True)
+class CommitChanges:
+    """One commit and what it did to the vocabulary."""
+
+    commit: Commit
+    changes: ChangeSet
+    unreadable: bool = False
+    raw_text: str | None = None
+
+
+def read_history(
+    repo: Path,
+    rev_range: str,
+    path: str,
+    *,
+    with_text: bool = False,
+    graphs: dict[str, Graph] | None = None,
+) -> list[CommitChanges]:
+    """Every commit in `rev_range` touching `path`, oldest first, with its changes.
+
+    `graphs` memoises parsed revisions by revision name. Consecutive commits share
+    one — the parent of each is the one before it — so walking N commits parses
+    N+1 revisions rather than 2N, and a caller stepping through a history one
+    commit at a time can hand the same dict back to keep what it already read.
+    """
+    memo: dict[str, Graph] = {} if graphs is None else graphs
+    return [
+        _entry(repo, commit, path, with_text=with_text, graphs=memo)
+        for commit in walk(repo, rev_range, path)
+    ]
+
+
+def _entry(
+    repo: Path, commit: Commit, path: str, *, with_text: bool, graphs: dict[str, Graph]
+) -> CommitChanges:
+    try:
+        later = _at(repo, commit.sha, path, graphs)
+    except UnreadableRevisionError:
+        # One bad revision must not end the walk — flag it and keep going.
+        return CommitChanges(commit=commit, changes=ChangeSet(()), unreadable=True)
+    return CommitChanges(
+        commit=commit,
+        changes=compare(_parent(repo, commit.sha, path, graphs), later),
+        raw_text=raw_diff(repo, commit.sha, path) if with_text else None,
+    )
+
+
+def _at(repo: Path, rev: str, path: str, graphs: dict[str, Graph]) -> Graph:
+    """The graph at `rev`, parsed once per *commit*, not once per name.
+
+    Keyed on the resolved sha: `<sha>^` and the commit before it are the same
+    revision under two names, and only resolving makes them share an entry.
+    """
+    key = resolve(repo, rev) or rev
+    if key not in graphs:
+        graphs[key] = graph_at_rev(repo, rev, path) or Graph()
+    return graphs[key]
+
+
+def _parent(repo: Path, sha: str, path: str, graphs: dict[str, Graph]) -> Graph:
+    """The graph one commit earlier — empty at the first commit, or if it was broken."""
+    try:
+        return _at(repo, f"{sha}^", path, graphs)
+    except UnreadableRevisionError:
+        return Graph()

semanticdiff/loader.py

@@ -0,0 +1,38 @@
+"""Reading the tracked RDF file as it stood at a revision."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rdflib import Graph
+
+from semanticdiff.git_log import read_blob
+
+_FORMATS = {
+    ".ttl": "turtle",
+    ".n3": "n3",
+    ".nt": "nt",
+    ".nq": "nquads",
+    ".trig": "trig",
+    ".rdf": "xml",
+    ".owl": "xml",
+    ".xml": "xml",
+    ".jsonld": "json-ld",
+}
+
+
+class UnreadableRevisionError(RuntimeError):
+    """The file exists at that revision but does not parse as RDF."""
+
+
+def graph_at_rev(repo: Path, rev: str, path: str) -> Graph | None:
+    """The parsed graph at `rev`, or None when the file does not exist there."""
+    blob = read_blob(repo, rev, path)
+    if blob is None:
+        return None
+    graph = Graph()
+    try:
+        graph.parse(data=blob, format=_FORMATS.get(Path(path).suffix.lower(), "turtle"))
+    except Exception as exc:
+        raise UnreadableRevisionError(f"{path} at {rev} does not parse: {exc}") from exc
+    return graph

semanticdiff/rename.py

@@ -0,0 +1,76 @@
+"""Rename detection.
+
+A URI change under an unchanged label is a rename, not a delete plus an add.
+Left undetected it is the ugliest false signal a graph diff produces, so it is
+the one derived operation worth paying for here.
+
+The rule is deliberately conservative: a removal and an addition pair only when
+they agree on entity kind, label text *and* language tag, and when that key is
+unique on both sides. Anything ambiguous stays reported as a delete and an add,
+because a wrong pairing is worse than a missed one.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterator
+
+from semanticdiff.vocabulary import Change, ChangeKind, ChangeSet
+
+_Key = tuple[object, str, str | None]
+
+
+def detect_renames(changes: ChangeSet) -> ChangeSet:
+    """Fold matching removal/addition pairs into single rename operations."""
+    removed = _by_label(changes, ChangeKind.REMOVED)
+    added = _by_label(changes, ChangeKind.ADDED)
+    pairs = {
+        key: (removed[key][0], added[key][0])
+        for key in removed.keys() & added.keys()
+        if len(removed[key]) == 1 and len(added[key]) == 1
+    }
+    if not pairs:
+        return changes
+    return ChangeSet(tuple(_rewrite(changes, pairs)))
+
+
+def _by_label(changes: ChangeSet, kind: ChangeKind) -> dict[_Key, list[Change]]:
+    grouped: dict[_Key, list[Change]] = defaultdict(list)
+    for change in changes:
+        if change.kind is kind and change.label is not None:
+            grouped[_key(change)].append(change)
+    return grouped
+
+
+def _key(change: Change) -> _Key:
+    assert change.label is not None
+    return (change.entity, change.label, change.label_lang)
+
+
+def _rewrite(changes: ChangeSet, pairs: dict[_Key, tuple[Change, Change]]) -> Iterator[Change]:
+    """Emit the changes with each paired removal/addition replaced by one rename."""
+    consumed = {change for pair in pairs.values() for change in pair}
+    emitted: set[_Key] = set()
+    for change in changes:
+        if change not in consumed:
+            yield change
+            continue
+        key = _key(change)
+        if key in emitted:
+            continue
+        emitted.add(key)
+        yield _renamed(*pairs[key])
+
+
+def _renamed(old: Change, new: Change) -> Change:
+    return Change(
+        kind=ChangeKind.RENAMED,
+        entity=new.entity,
+        uri=new.uri,
+        curie=new.curie,
+        label=new.label,
+        label_lang=new.label_lang,
+        previous_uri=old.uri,
+        previous_curie=old.curie,
+        detail=new.detail,
+    )

semanticdiff/render/__init__.py

@@ -0,0 +1,7 @@
+"""Renderers for a read history."""
+
+from __future__ import annotations
+
+from semanticdiff.render.text import render_commits, render_entity, render_summary
+
+__all__ = ["render_commits", "render_entity", "render_summary"]

semanticdiff/render/rows.py

@@ -0,0 +1,99 @@
+"""One commit's changes as rows, before anything decides how to print them.
+
+The tally — bulk individuals counted against their class — used to live inside
+the text renderer, which meant a second front end had to either re-derive it or
+parse text back. It belongs here: the text renderer formats these rows, and so
+can anything else.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from semanticdiff.vocabulary import Change, ChangeKind, EntityKind
+
+# Above this many individuals of one class, in one commit, they are counted
+# rather than named. On a real ontology individuals are ~99% of every commit and
+# bury the class and property changes the reader came for. Below it nothing
+# changes: three names say more than the number three.
+TALLY_ABOVE = 5
+
+# A rename or a deprecation is rare and is the most interesting thing that can
+# happen to an individual, so it is named however many of its siblings counted.
+_NEVER_TALLIED = (ChangeKind.RENAMED, ChangeKind.DEPRECATED)
+
+
+@dataclass(frozen=True)
+class Row:
+    """A line of the change list: either one named entity, or a count of many."""
+
+    kind: ChangeKind
+    entity: EntityKind
+    name: str
+    # The identifier, kept beside the readable name rather than folded into it,
+    # so a front end can show them apart — "Vehicle" large, "ex:Vehicle" dim.
+    curie: str | None = None
+    detail: tuple[str, ...] = ()
+    previous: str | None = None
+    count: int = 1
+    of_class: str | None = None
+
+    @property
+    def counted(self) -> bool:
+        """Whether this row stands for many entities rather than one."""
+        return self.count > 1
+
+
+def summarise(changes: Iterable[Change]) -> list[Row]:
+    """The rows for one commit: entities worth naming, then the counts."""
+    named, counted = _partition(changes)
+    return [_named_row(c) for c in named] + _counted_rows(counted)
+
+
+def _partition(changes: Iterable[Change]) -> tuple[list[Change], dict]:
+    buckets: dict[tuple[ChangeKind, str | None], list[Change]] = defaultdict(list)
+    named: list[Change] = []
+    for change in changes:
+        key = _tally_key(change)
+        if key is None:
+            named.append(change)
+        else:
+            buckets[key].append(change)
+    counted = {k: g for k, g in buckets.items() if len(g) > TALLY_ABOVE}
+    for key, group in buckets.items():
+        if key not in counted:
+            named.extend(group)
+    return named, counted
+
+
+def _tally_key(change: Change) -> tuple[ChangeKind, str | None] | None:
+    """The bucket a change is counted in, or None when it must be named."""
+    if change.entity is not EntityKind.INDIVIDUAL or change.kind in _NEVER_TALLIED:
+        return None
+    return (change.kind, change.of_class)
+
+
+def _named_row(change: Change) -> Row:
+    return Row(
+        kind=change.kind,
+        entity=change.entity,
+        name=change.display,
+        curie=change.curie,
+        detail=change.detail,
+        previous=change.previous_curie,
+    )
+
+
+def _counted_rows(counted: dict[tuple[ChangeKind, str | None], list[Change]]) -> list[Row]:
+    return [
+        Row(
+            kind=kind,
+            entity=EntityKind.INDIVIDUAL,
+            name=f"{len(group)} individuals",
+            count=len(group),
+            of_class=of_class,
+        )
+        for (kind, of_class), group in sorted(counted.items(), key=lambda kv: str(kv[0]))
+    ]

semanticdiff/render/text.py

@@ -0,0 +1,127 @@
+"""Terminal rendering — the three layers of the drill-down.
+
+Layer 0 is the summary over a range, layer 1 the per-commit change list, layer 2
+one entity's story. Layer 3, the raw hunk, is only ever printed on request:
+the whole point is that the text is the escape hatch, not the default.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+
+from semanticdiff.history import CommitChanges
+from semanticdiff.render.rows import Row, summarise
+from semanticdiff.vocabulary import Change, ChangeKind
+
+_MARKERS = {
+    ChangeKind.ADDED: "+",
+    ChangeKind.REMOVED: "-",
+    ChangeKind.MODIFIED: "~",
+    ChangeKind.RENAMED: "»",
+    ChangeKind.DEPRECATED: "⊘",
+}
+
+_ORDER = (
+    ChangeKind.ADDED,
+    ChangeKind.MODIFIED,
+    ChangeKind.RENAMED,
+    ChangeKind.DEPRECATED,
+    ChangeKind.REMOVED,
+)
+
+_NO_COMMITS = "no commits touching this file in this range"
+_INDENT = "    "
+
+# Above this many individuals of one class, in one commit, the report counts them
+# instead of naming them. On a real ontology individuals are the overwhelming
+# majority of every commit — 9 301 of 9 414 lines on adeo-retail-geography, 98.8%
+# — and they bury the class and property changes the reader came for. Below it
+# nothing changes: three names say more than the number three.
+_TALLY_ABOVE = 5
+
+# A rename or a deprecation is rare and is the most interesting thing that can
+# happen to an individual, so it is named however many of its siblings are
+# counted. "city-ro-sibiu → region-ro-sibiu" is the whole point of the report.
+_NEVER_TALLIED = (ChangeKind.RENAMED, ChangeKind.DEPRECATED)
+
+
+def render_summary(history: Sequence[CommitChanges], rev_range: str) -> str:
+    """Layer 0 — the headline: how many commits, and how much moved."""
+    if not history:
+        return f"{rev_range} — {_NO_COMMITS}"
+    counts: Counter[ChangeKind] = Counter()
+    for entry in history:
+        counts.update(entry.changes.counts())
+    tallies = [f"{counts[kind]} {kind.value}" for kind in _ORDER if counts[kind]]
+    headline = f"{rev_range} — {_plural(len(history), 'commit')}"
+    return f"{headline}\n{'  '.join(tallies)}" if tallies else headline
+
+
+def render_commits(history: Sequence[CommitChanges], *, show_text: bool = False) -> str:
+    """Layer 1 — every commit, and what it did to the vocabulary."""
+    if not history:
+        return _NO_COMMITS
+    return "\n\n".join(_block(entry, show_text=show_text) for entry in history)
+
+
+def render_entity(history: Sequence[CommitChanges], uri: str) -> str:
+    """Layer 2 — only the commits that touched one entity."""
+    blocks = [
+        _entity_block(entry, hits) for entry in history if (hits := entry.changes.for_uri(uri))
+    ]
+    if not blocks:
+        return f"{uri} never changed in this range"
+    return "\n\n".join(blocks)
+
+
+def _block(entry: CommitChanges, *, show_text: bool) -> str:
+    lines = [_header(entry), *_change_lines(entry)]
+    if entry.commit.other_files:
+        lines.append(f"{_INDENT}({_plural(entry.commit.other_files, 'non-RDF file')} changed)")
+    if show_text and entry.raw_text:
+        lines.append(entry.raw_text)
+    return "\n".join(lines)
+
+
+def _entity_block(entry: CommitChanges, hits: tuple[Change, ...]) -> str:
+    return "\n".join([_header(entry), *(_row_line(r) for r in summarise(hits))])
+
+
+def _header(entry: CommitChanges) -> str:
+    commit = entry.commit
+    return f"● {commit.short_sha}  {commit.subject}  — {commit.author}  {commit.date[:10]}"
+
+
+def _change_lines(entry: CommitChanges) -> list[str]:
+    if entry.unreadable:
+        return [f"{_INDENT}(ontology unreadable at this revision)"]
+    if not entry.changes:
+        # The walk only lists commits that touched the file, so an empty
+        # changeset means the bytes moved and the graph did not: the file was
+        # re-spelled, not edited. Say that outright — "no semantic change" alone
+        # reads like the tool gave up, when it is in fact the answer.
+        return [f"{_INDENT}(no semantic change \u2014 pure formatting)"]
+    return [_row_line(row) for row in summarise(entry.changes)]
+
+
+def _row_line(row: Row) -> str:
+    where = f"   ({row.of_class})" if row.counted and row.of_class else ""
+    if row.counted:
+        return f"{_INDENT}{_MARKERS[row.kind]}{row.name}{where}"
+    detail = f"   {' \u00b7 '.join(row.detail)}" if row.detail else ""
+    name = _row_name(row)
+    return f"{_INDENT}{_MARKERS[row.kind]} {row.entity.value:<10} {name}{detail}"
+
+
+def _row_name(row: Row) -> str:
+    """The readable name, with the identifier beside it when they differ."""
+    if row.kind is ChangeKind.RENAMED:
+        return f"{row.previous} \u2192 {row.curie}"
+    if row.curie and row.curie != row.name:
+        return f"{row.name} ({row.curie})"
+    return row.name
+
+
+def _plural(count: int, noun: str) -> str:
+    return f"{count} {noun}" if count == 1 else f"{count} {noun}s"

semanticdiff/vocabulary.py

@@ -0,0 +1,90 @@
+"""The change vocabulary — what semanticdiff can say about an edit.
+
+The operation names follow the basic half of COnto-Diff (Hartung, Groß & Rahm):
+insert / delete / update, plus the two derived operations worth the cost here —
+a rename, and a deprecation. Complex operations (merge, split, subtree move) are
+deliberately out of scope.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+
+
+class EntityKind(str, Enum):
+    """What sort of thing changed."""
+
+    CLASS = "class"
+    PROPERTY = "property"
+    INDIVIDUAL = "individual"
+    CONCEPT = "concept"
+    ONTOLOGY = "ontology"
+    OTHER = "other"
+
+
+class ChangeKind(str, Enum):
+    """What happened to it."""
+
+    ADDED = "added"
+    REMOVED = "removed"
+    MODIFIED = "modified"
+    RENAMED = "renamed"
+    DEPRECATED = "deprecated"
+
+
+@dataclass(frozen=True)
+class Change:
+    """One change operation on one entity.
+
+    `uri` is the full URI and `curie` its prefixed form (falling back to the full
+    URI when no prefix is bound), because the summary reads in CURIEs but the
+    caller may address an entity either way.
+    """
+
+    kind: ChangeKind
+    entity: EntityKind
+    uri: str
+    curie: str
+    label: str | None = None
+    label_lang: str | None = None
+    previous_uri: str | None = None
+    previous_curie: str | None = None
+    detail: tuple[str, ...] = ()
+    # For an individual, the class it instantiates, already resolved to the name
+    # a reader should see (label when there is one, else the CURIE) by the same
+    # rule as `display`. Carried on the change so a summary can count individuals
+    # against their class without a second pass over the graph.
+    of_class: str | None = None
+
+    @property
+    def display(self) -> str:
+        """The name a human should see — the label when there is one."""
+        return self.label or self.curie
+
+
+@dataclass(frozen=True)
+class ChangeSet:
+    """The changes between two versions of a graph."""
+
+    changes: tuple[Change, ...] = ()
+
+    def __iter__(self) -> Iterator[Change]:
+        return iter(self.changes)
+
+    def __len__(self) -> int:
+        return len(self.changes)
+
+    def counts(self) -> Counter[ChangeKind]:
+        """How many changes of each kind — the material for the summary line."""
+        return Counter(change.kind for change in self.changes)
+
+    def for_uri(self, uri: str) -> tuple[Change, ...]:
+        """Changes touching `uri`, given either its full URI or its CURIE."""
+        return tuple(
+            change
+            for change in self.changes
+            if uri in (change.uri, change.curie, change.previous_uri, change.previous_curie)
+        )