texdiff 0.2.0__tar.gz

texdiff-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoBobr
+
+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.

texdiff-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: texdiff
+Version: 0.2.0
+Summary: AST-driven semantic diff for LaTeX documents
+Author: GoBobr
+License: MIT License
+        
+        Copyright (c) 2026 GoBobr
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/GoBobr/texdiff
+Keywords: latex,diff,latexdiff,ast,track-changes
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pylatexenc>=2.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: pymdown-extensions>=10; extra == "docs"
+Dynamic: license-file
+
+# texdiff
+
+**AST-driven semantic diff for LaTeX documents.**
+
+`texdiff` compares two revisions of a LaTeX document and produces a single
+marked-up `diff.tex` that compiles with `pdflatex` — added text in blue,
+deleted text struck out — while preserving the original document's styling,
+cross-references and custom classes.
+
+## Why
+
+[`latexdiff`](https://www.ctan.org/pkg/latexdiff) is the de-facto standard for
+review-marked LaTeX, but it diffs *token soup*: it guesses word boundaries with
+regexes and re-injects markup into the merged text, hoping braces still
+balance. On real-world documents the result is markup that crosses brace /
+environment boundaries, glues old and new table cells together, and corrupts
+listings — which is why every serious latexdiff user eventually ends up
+maintaining a pile of fragile pre/post-processing scripts around it.
+
+`texdiff` takes the other road: **diff the tree, never the text.**
+
+1. Parse old and new documents into a LaTeX syntax tree
+   ([pylatexenc](https://github.com/phfaist/pylatexenc) — a faithful concrete
+   syntax tree carrying exact source spans, no macro expansion).
+2. Align the trees level by level (document → environments → groups → text
+   runs) with difflib-style sequence matching. A change can never leak across
+   a node boundary.
+3. Walk the merged tree and emit `\DIFadd{...}` / `\DIFdel{...}` markup —
+   latexdiff-compatible rendering, valid by construction.
+
+Restructured tables (re-ordered rows, changed column layouts), math,
+listings and verbatim environments are handled as atomic or row-aligned
+blocks instead of being shredded by a word diff.
+
+Multi-file sources are flattened automatically (`\input`/`\include`
+resolved relative to each file, like `latexdiff --flatten`), and the
+preamble of the new revision is used verbatim so custom classes and
+macros keep working.
+
+## Usage
+
+```sh
+texdiff old/main.tex new/main.tex > diff.tex   # \input expansion built in
+pdflatex diff.tex                              # done - no pre/postprocessing
+texdiff old.tex new.tex -o diff.tex --check    # + fail loudly if it won't compile
+texdiff old.tex new.tex --stats                # "611 unchanged, 29 added, ..."
+```
+
+```sh
+pip install texdiff        # or from a checkout:
+pip install -e ".[dev]" && pytest
+```
+
+Status: **v0.2.0** — core pipeline plus flattening, row-granular table
+alignment, preamble policy, `--check` and a compile-guaranteed corpus in
+CI; validated on a 65-page generated longtable-heavy document. See the
+[roadmap](https://gobobr.github.io/texdiff/roadmap/) for what is next.
+
+## License
+
+MIT

texdiff-0.2.0/README.md

@@ -0,0 +1,61 @@
+# texdiff
+
+**AST-driven semantic diff for LaTeX documents.**
+
+`texdiff` compares two revisions of a LaTeX document and produces a single
+marked-up `diff.tex` that compiles with `pdflatex` — added text in blue,
+deleted text struck out — while preserving the original document's styling,
+cross-references and custom classes.
+
+## Why
+
+[`latexdiff`](https://www.ctan.org/pkg/latexdiff) is the de-facto standard for
+review-marked LaTeX, but it diffs *token soup*: it guesses word boundaries with
+regexes and re-injects markup into the merged text, hoping braces still
+balance. On real-world documents the result is markup that crosses brace /
+environment boundaries, glues old and new table cells together, and corrupts
+listings — which is why every serious latexdiff user eventually ends up
+maintaining a pile of fragile pre/post-processing scripts around it.
+
+`texdiff` takes the other road: **diff the tree, never the text.**
+
+1. Parse old and new documents into a LaTeX syntax tree
+   ([pylatexenc](https://github.com/phfaist/pylatexenc) — a faithful concrete
+   syntax tree carrying exact source spans, no macro expansion).
+2. Align the trees level by level (document → environments → groups → text
+   runs) with difflib-style sequence matching. A change can never leak across
+   a node boundary.
+3. Walk the merged tree and emit `\DIFadd{...}` / `\DIFdel{...}` markup —
+   latexdiff-compatible rendering, valid by construction.
+
+Restructured tables (re-ordered rows, changed column layouts), math,
+listings and verbatim environments are handled as atomic or row-aligned
+blocks instead of being shredded by a word diff.
+
+Multi-file sources are flattened automatically (`\input`/`\include`
+resolved relative to each file, like `latexdiff --flatten`), and the
+preamble of the new revision is used verbatim so custom classes and
+macros keep working.
+
+## Usage
+
+```sh
+texdiff old/main.tex new/main.tex > diff.tex   # \input expansion built in
+pdflatex diff.tex                              # done - no pre/postprocessing
+texdiff old.tex new.tex -o diff.tex --check    # + fail loudly if it won't compile
+texdiff old.tex new.tex --stats                # "611 unchanged, 29 added, ..."
+```
+
+```sh
+pip install texdiff        # or from a checkout:
+pip install -e ".[dev]" && pytest
+```
+
+Status: **v0.2.0** — core pipeline plus flattening, row-granular table
+alignment, preamble policy, `--check` and a compile-guaranteed corpus in
+CI; validated on a 65-page generated longtable-heavy document. See the
+[roadmap](https://gobobr.github.io/texdiff/roadmap/) for what is next.
+
+## License
+
+MIT

texdiff-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "texdiff"
+version = "0.2.0"
+description = "AST-driven semantic diff for LaTeX documents"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "GoBobr" }]
+keywords = ["latex", "diff", "latexdiff", "ast", "track-changes"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+]
+dependencies = [
+    "pylatexenc>=2.10",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9",
+    "mkdocstrings[python]>=0.24",
+    "pymdown-extensions>=10",
+]
+
+[project.scripts]
+texdiff = "texdiff.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/GoBobr/texdiff"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+texdiff = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=texdiff --cov-report=term-missing --cov-fail-under=80"
+
+[tool.coverage.run]
+source = ["texdiff"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

texdiff-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

texdiff-0.2.0/src/texdiff/__init__.py

@@ -0,0 +1,45 @@
+"""texdiff - AST-driven semantic diff for LaTeX documents.
+
+The pipeline IS::
+
+    old.tex ─┐
+             ├─> parse → align trees → emit markup → diff.tex
+    new.tex ─┘
+
+ latexdiff diffs characters and breaks structure;
+ texdiff diffs structure and never breaks characters.
+"""
+
+from .align import Delete, Edit, Insert, Match, Modify, align
+from .api import DiffResult, DiffStats, diff_documents, diff_files
+from .emit import LatexdiffMarkup, render
+from .flatten import Flattener, flatten_file, flatten_source
+from .nodes import Node
+from .parse import ParseError, parse, parse_file
+from .textdiff import Chunk, word_diff
+
+__all__ = [
+    "align",
+    "Chunk",
+    "Delete",
+    "diff_documents",
+    "diff_files",
+    "DiffResult",
+    "DiffStats",
+    "Edit",
+    "Flattener",
+    "flatten_file",
+    "flatten_source",
+    "Insert",
+    "LatexdiffMarkup",
+    "Match",
+    "Modify",
+    "Node",
+    "parse",
+    "ParseError",
+    "parse_file",
+    "render",
+    "word_diff",
+]
+
+__version__ = "0.1.0"

texdiff-0.2.0/src/texdiff/align.py

@@ -0,0 +1,202 @@
+"""Tree alignment: match two node lists into aligned pairs and edits.
+
+The aligner is where latexdiff's heuristics become data. It produces,
+for a pair of node lists, an edit script of three shapes:
+
+* ``match(old, new)`` - same signature, identical text → keep verbatim
+* ``modify(old, new)`` - same signature, different text → recurse if
+  both sides have children (block diff), else whole-block replacement
+* ``insert(new)`` / ``delete(old)`` - no counterpart
+
+Uses :class:`difflib.SequenceMatcher` over node signatures; runs of
+equal signature with different text become ``modify`` pairs aligned
+positionally within the run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+
+from .nodes import Node
+
+
+@dataclass(frozen=True)
+class Match:
+    """A node kept verbatim (identical on both sides)."""
+
+    node: Node
+
+
+@dataclass(frozen=True)
+class Modify:
+    """A node pair to be diffed further (recursed) - or replaced.
+
+    Attributes:
+        old: the node from the old revision.
+        new: the node from the new revision.
+        inner: the recursive edit script of the children, when both
+            sides are recursable; ``None`` means whole-block replace.
+    """
+
+    old: Node
+    new: Node
+    inner: "list[Edit] | None" = None
+
+
+@dataclass(frozen=True)
+class Insert:
+    """A node present only in the new version."""
+
+    new: Node
+
+
+@dataclass(frozen=True)
+class Delete:
+    """A node present only in the old version."""
+
+    old: Node
+
+
+Edit = Match | Modify | Insert | Delete
+
+
+def align(old: list[Node], new: list[Node]) -> list[Edit]:
+    """Align two node lists into an edit script.
+
+    The returned script is in document order, interleaving old and new
+    positions like a unified diff.
+
+    Algorithm:
+
+    1. an equal *prefix* and *suffix* of signatures anchors the
+       alignment first: ``SequenceMatcher`` finds the globally
+       longest matching block, which can let a later identical run
+       steal the match from the earliest identical nodes - an
+       inserted chapter between two near-identical passages then
+       drags unchanged leading lines into the insertion (they
+       render as added);
+    2. ``SequenceMatcher`` over the remaining node *signatures*
+       yields runs of same-signature positions deemed "matching";
+    3. within a run, nodes are paired positionally: identical source
+       text becomes :class:`Match`, differing text :class:`Modify`;
+    4. gap regions become ``Delete`` (old-only) then ``Insert``
+       (new-only) sequences, preserving document order.
+    """
+
+    def _pair(o: Node, n: Node) -> Edit:
+        if o.text == n.text:
+            return Match(node=o)
+        if o.kind == "row" and n.kind == "row" and o.name == n.name:
+            # equal row signature (content key) with differing text
+            # means the difference is purely structural: \hline on
+            # the other side of the row, whitespace, comments.
+            # Duplicating such a pair (del + add) would emit the
+            # table header material (\endfirsthead, \endhead ...)
+            # twice inside one longtable, which can throw longtable
+            # into an infinite loop. Keep the old row verbatim.
+            return Match(node=o)
+        return Modify(old=o, new=n)
+
+    # 1. common prefix, paired positionally (identical to what a
+    # matching-block run does - only the anchoring is stronger)
+    pre = 0
+    while (
+        pre < len(old)
+        and pre < len(new)
+        and old[pre].signature() == new[pre].signature()
+    ):
+        pre += 1
+    # common suffix (may not overlap the prefix)
+    suf = 0
+    while (
+        suf < len(old) - pre
+        and suf < len(new) - pre
+        and old[len(old) - 1 - suf].signature() == new[len(new) - 1 - suf].signature()
+    ):
+        suf += 1
+    mid_old = old[pre : len(old) - suf]
+    mid_new = new[pre : len(new) - suf]
+
+    sm = SequenceMatcher(
+        a=[n.signature() for n in mid_old],
+        b=[n.signature() for n in mid_new],
+        autojunk=False,
+    )
+
+    edits: list[Edit] = [_pair(o, n) for o, n in zip(old[:pre], new[:pre])]
+    prev_a = prev_b = 0
+    for block in sm.get_matching_blocks():
+        # gap before this matching block: deletions then insertions.
+        # Block-head refinement: ``SequenceMatcher`` extends a matching
+        # block as far as equal *signatures* reach - with the wildcard
+        # ``text`` signature, a run may begin by pairing two text nodes
+        # whose contents share nothing, while the node that should pair
+        # with the old head sits at the START of the insertion gap just
+        # before the block. When that pairing is clearly better, consume
+        # the gap head into a Modify pair, emit the rest of the gap as
+        # inserts, and let the block start one position later on both
+        # sides (its first new-side node then lands at the gap end).
+        new_gap = mid_new[prev_b : block.b]
+        head_a, head_b = block.a, block.b
+        if (
+            block.size
+            and new_gap
+            and mid_old[block.a].kind == "text"
+            and new_gap[0].kind == "text"
+            and mid_new[block.b].kind == "text"
+        ):
+            o_head = mid_old[block.a]
+            best = max(
+                range(min(len(new_gap), 4)),
+                key=lambda k: _text_similarity(o_head.text, new_gap[k].text),
+            )
+            n_head = new_gap[best]
+            if _text_similarity(o_head.text, n_head.text) > (
+                _text_similarity(o_head.text, mid_new[block.b].text) + 0.2
+            ):
+                edits.extend(Delete(old=n) for n in mid_old[prev_a : block.a])
+                edits.extend(Insert(new=n) for n in new_gap[:best])
+                edits.append(_pair(o_head, n_head))
+                edits.extend(Insert(new=n) for n in new_gap[best + 1 :])
+                edits.append(Insert(new=mid_new[block.b]))
+                head_a, head_b = block.a + 1, block.b + 1
+                for i in range(1, block.size):
+                    edits.append(
+                        _pair(mid_old[block.a + i], mid_new[block.b + i])
+                    )
+                prev_a, prev_b = block.a + block.size, block.b + block.size
+                continue
+        edits.extend(Delete(old=n) for n in mid_old[prev_a : block.a])
+        edits.extend(Insert(new=n) for n in new_gap)
+        # the matching run: pair positionally, decide Match vs Modify
+        for i in range(head_a, head_a + block.size):
+            edits.append(
+                _pair(mid_old[i], mid_new[head_b + (i - head_a)])
+            )
+        prev_a, prev_b = head_a + block.size, head_b + block.size
+    edits.extend(Delete(old=n) for n in mid_old[prev_a:])
+    edits.extend(Insert(new=n) for n in mid_new[prev_b:])
+    # common suffix, in document order
+    edits.extend(
+        _pair(o, n)
+        for o, n in zip(
+            old[len(old) - suf :], new[len(new) - suf :]
+        )
+    )
+    return edits
+
+
+def _text_similarity(a: str, b: str) -> float:
+    """Quick content similarity of two text runs, in ``[0, 1]``.
+
+    Used only to compare pairing candidates at matching-block
+    boundaries, so a cheap ``SequenceMatcher.ratio`` over word
+    tokens (not raw characters) is enough - and stays stable for
+    long runs where character noise would dominate.
+    """
+    wa = [t for t in a.split() if t]
+    wb = [t for t in b.split() if t]
+    if not wa or not wb:
+        return 0.0
+    return SequenceMatcher(a=wa, b=wb, autojunk=False).ratio()