logicdiff 0.1.0__py3-none-any.whl

logicdiff/__init__.py

@@ -0,0 +1,3 @@
+"""logicdiff — a whitespace- and reflow-blind diff. Zero dependencies."""
+
+__version__ = "0.1.0"

logicdiff/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

logicdiff/cli.py

@@ -0,0 +1,167 @@
+import json
+import os
+import re
+import signal
+import sys
+
+from . import __version__
+from . import core
+
+DEFAULT_MAX_TOKENS = 2000000
+
+
+def _color_on(mode):
+    if mode == "always":
+        return True
+    if mode == "never":
+        return False
+    return sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _mk_paint(on):
+    def col(c, s):
+        return f"\x1b[{c}m{s}\x1b[0m" if on else s
+    return {
+        "red": lambda s: col("31", s), "green": lambda s: col("32", s),
+        "yellow": lambda s: col("33", s), "dim": lambda s: col("2", s),
+        "bold": lambda s: col("1", s), "cyan": lambda s: col("36", s),
+    }
+
+
+def _help():
+    b = _mk_paint(_color_on("auto"))["bold"]
+    return (
+        f"{b('logicdiff')} — a whitespace- and reflow-blind diff. Zero dependencies.\n"
+        "\n"
+        "Diffs two files but folds away pure formatting — respacing AND line reflow — and\n"
+        "shows only the logical changes. Where `git diff -w` still flags a re-wrapped block,\n"
+        "logicdiff says \"only formatting differs\". Language-agnostic, no parser.\n"
+        "\n"
+        f"{b('Usage')}\n"
+        "  logicdiff <old> <new>      Compare two files (use - for stdin)\n"
+        "\n"
+        f"{b('Options')}\n"
+        "  --stat             Print only the counts (machine-friendly key=value)\n"
+        "  --json             Machine-readable output (byte-identical across Node and Python)\n"
+        "  -q, --quiet        No output; exit code only\n"
+        "  --color=auto|always|never   Colorize (default auto)\n"
+        f"  --max-tokens N     Bail (exit 2) over N tokens total (default {DEFAULT_MAX_TOKENS})\n"
+        "  --help | --version\n"
+        "\n"
+        f"{b('Exit')}  0 identical or formatting-only · 1 logical changes · 2 error\n"
+    )
+
+
+class _Exit(Exception):
+    def __init__(self, code):
+        self.code = code
+
+
+def _out(s):
+    sys.stdout.buffer.write(s.encode("latin-1"))
+
+
+def main(argv=None):
+    try:
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    except (AttributeError, ValueError):
+        pass
+
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    def die(msg):
+        sys.stderr.write(_mk_paint(_color_on("auto"))["red"](f"logicdiff: {msg}\n"))
+        raise _Exit(2)
+
+    try:
+        dd_idx = argv.index("--") if "--" in argv else len(argv)
+        pre = argv[:dd_idx]
+        if "-h" in pre or "--help" in pre:
+            sys.stdout.write(_help())
+            return 0
+        if "-v" in pre or "--version" in pre:
+            sys.stdout.write(__version__ + "\n")
+            return 0
+
+        as_stat = as_json = quiet = False
+        color = "auto"
+        max_tokens = DEFAULT_MAX_TOKENS
+        files = []
+        dd = False
+        i = 0
+        while i < len(argv):
+            a = argv[i]
+            if dd:
+                files.append(a); i += 1; continue
+            if a == "--":
+                dd = True; i += 1; continue
+            eq = a.find("=") if a.startswith("--") else -1
+            flag = a[:eq] if eq != -1 else a
+            inline = a[eq + 1:] if eq != -1 else None
+            if flag == "--stat":
+                as_stat = True
+            elif flag == "--json":
+                as_json = True
+            elif a == "-q" or flag == "--quiet":
+                quiet = True
+            elif flag == "--color":
+                color = inline if inline is not None else (argv[i + 1] if i + 1 < len(argv) else "")
+                if inline is None:
+                    i += 1
+                if color not in ("auto", "always", "never"):
+                    die("--color must be auto, always or never")
+            elif flag == "--max-tokens":
+                val = inline if inline is not None else (argv[i + 1] if i + 1 < len(argv) else "")
+                if inline is None:
+                    i += 1
+                # Strict integer grammar (optional leading +, decimal digits only) so this
+                # parses byte-identically to the Node build. fullmatch (not $) avoids Python's
+                # trailing-newline match; int() alone would accept PEP-515 '1_000'.
+                if not re.fullmatch(r"\+?[0-9]+", val):
+                    die("--max-tokens must be a positive integer")
+                max_tokens = int(val)
+                if max_tokens <= 0:
+                    die("--max-tokens must be a positive integer")
+            elif a in ("-h", "--help", "-v", "--version"):
+                pass
+            elif a.startswith("-") and a != "-":
+                die(f"unknown option: {a} (use -- to end options)")
+            else:
+                files.append(a)
+            i += 1
+
+        if len(files) != 2:
+            die(f"expected exactly 2 files, got {len(files)} (usage: logicdiff <old> <new>)")
+
+        def read_input(p):
+            try:
+                buf = sys.stdin.buffer.read() if p == "-" else open(p, "rb").read()
+            except OSError:
+                die(f"cannot read '{p}'")  # OS-specific detail omitted for Node/Python parity
+            if b"\x00" in buf:
+                return None
+            return buf.decode("latin-1")
+
+        a_text = read_input(files[0])
+        b_text = read_input(files[1])
+        if a_text is None or b_text is None:
+            if not quiet:
+                sys.stderr.write("logicdiff: binary file, not diffed\n")
+            return 2
+
+        try:
+            result = core.compare(a_text, b_text, {"maxTokens": max_tokens})
+        except ValueError as e:
+            die(str(e))
+
+        paint = _mk_paint(_color_on(color) and not as_json and not as_stat)
+        if as_json:
+            _out(json.dumps(core.to_json(result, files[0], files[1]), indent=2, ensure_ascii=False) + "\n")
+        elif as_stat:
+            _out(core.stat_line(result) + "\n")
+        elif not quiet:
+            _out(core.format_human(result, files[0], files[1], paint) + "\n")
+
+        return 0 if (result["identical"] or result["formattingOnly"]) else 1
+    except _Exit as ex:
+        return ex.code

logicdiff/core.py

@@ -0,0 +1,225 @@
+"""logicdiff core — pure whitespace-and-reflow-blind diff. No fs, no clock.
+
+The trick: diff the two files as sequences of TOKENS (words + single punctuation
+chars), with whitespace dropped, so respacing AND line-reflow are invisible. If the
+token sequences are equal, the files differ only in formatting. Token comparison is
+on TEXT ONLY (line numbers are metadata) — that's what makes reflow fold.
+
+Byte-for-byte identical to the Node build: everything runs on a latin-1
+(byte-faithful) string, the tokenizer uses explicit ASCII classes (never \\w/\\s), and
+the diff is the canonical Myers O(ND) algorithm with a pinned tie-break.
+"""
+
+WS = "\x20\x09\x0a\x0d\x0c\x0b"  # space, tab, LF, CR, FF, VT
+
+
+def is_word(code):
+    return (65 <= code <= 90) or (97 <= code <= 122) or (48 <= code <= 57) or code == 95
+
+
+def tokenize(s):
+    """[{text,line}]; word=[A-Za-z0-9_] run, else single non-ws char; ws dropped;
+    only '\\n' increments the 1-based line (lone '\\r' does not -> CRLF == LF)."""
+    toks = []
+    line = 1
+    i = 0
+    n = len(s)
+    while i < n:
+        ch = s[i]
+        if ch == "\n":
+            line += 1
+            i += 1
+            continue
+        if ch in WS:
+            i += 1
+            continue
+        if is_word(ord(ch)):
+            j = i + 1
+            while j < n and is_word(ord(s[j])):
+                j += 1
+            toks.append({"text": s[i:j], "line": line})
+            i = j
+        else:
+            toks.append({"text": ch, "line": line})
+            i += 1
+    return toks
+
+
+def split_lines(s):
+    return s.split("\n")
+
+
+# ---- canonical Myers O(ND) diff over string arrays -------------------------
+# Coglan reference variant. Tie-break: prefer "down" (insertion) only when
+# k == -d OR (k != d AND V[k-1] < V[k+1]) with strict <. Snapshot V before each
+# d-round. Implemented identically in the Node build.
+
+# Bail before the O(D*(n+m)) trace exhausts memory (D = edit distance). ~1.2e8 ints keeps
+# the Node build well under its default heap cap; this build bails at the same point.
+MAX_TRACE_ELEMENTS = 120000000
+
+
+def shortest_edit(a, b, max_trace=None):
+    n, m = len(a), len(b)
+    mx = n + m
+    cap = max_trace or MAX_TRACE_ELEMENTS
+    trace = []
+    if mx == 0:
+        return trace, n, m
+    v = [0] * (2 * mx + 1)
+    for d in range(0, mx + 1):
+        # The trace holds one full V-snapshot (length 2*mx+1) per d-round, so worst-case
+        # memory is O(D*(n+m)); bail deterministically (identically in both builds) before it
+        # exhausts the heap. Triggered only by very dissimilar inputs (large edit distance).
+        if (d + 1) * (2 * mx + 1) > cap:
+            raise ValueError("input too large to diff (too many differences between the inputs)")
+        trace.append(v[:])
+        for k in range(-d, d + 1, 2):
+            if k == -d or (k != d and v[k - 1 + mx] < v[k + 1 + mx]):
+                x = v[k + 1 + mx]
+            else:
+                x = v[k - 1 + mx] + 1
+            y = x - k
+            while x < n and y < m and a[x] == b[y]:
+                x += 1
+                y += 1
+            v[k + mx] = x
+            if x >= n and y >= m:
+                return trace, n, m
+    return trace, n, m
+
+
+def diff_seq(a, b, max_trace=None):
+    n, m = len(a), len(b)
+    mx = n + m
+    trace, _, _ = shortest_edit(a, b, max_trace)
+    x, y = n, m
+    moves = []
+    for d in range(len(trace) - 1, -1, -1):
+        v = trace[d]
+        k = x - y
+        if k == -d or (k != d and v[k - 1 + mx] < v[k + 1 + mx]):
+            prev_k = k + 1
+        else:
+            prev_k = k - 1
+        prev_x = v[prev_k + mx]
+        prev_y = prev_x - prev_k
+        while x > prev_x and y > prev_y:
+            moves.append({"op": "keep", "a": x - 1, "b": y - 1})
+            x -= 1
+            y -= 1
+        if d > 0:
+            if x == prev_x:
+                moves.append({"op": "ins", "b": y - 1})
+            else:
+                moves.append({"op": "del", "a": x - 1})
+            x, y = prev_x, prev_y
+    moves.reverse()
+    return moves
+
+
+# ---- top-level comparison --------------------------------------------------
+
+def compare(a_str, b_str, opts=None):
+    opts = opts or {}
+    max_trace = opts.get("maxTrace")
+    a_toks, b_toks = tokenize(a_str), tokenize(b_str)
+    max_tokens = opts.get("maxTokens")
+    if max_tokens and len(a_toks) + len(b_toks) > max_tokens:
+        raise ValueError(f"input too large ({len(a_toks) + len(b_toks)} tokens > --max-tokens {max_tokens})")
+    moves = diff_seq([t["text"] for t in a_toks], [t["text"] for t in b_toks], max_trace)
+
+    tokens_added = tokens_removed = 0
+    del_lines, ins_lines = set(), set()
+    for mv in moves:
+        if mv["op"] == "del":
+            tokens_removed += 1
+            del_lines.add(a_toks[mv["a"]]["line"])
+        elif mv["op"] == "ins":
+            tokens_added += 1
+            ins_lines.add(b_toks[mv["b"]]["line"])
+    del_line_arr = sorted(del_lines)
+    ins_line_arr = sorted(ins_lines)
+
+    a_lines, b_lines = split_lines(a_str), split_lines(b_str)
+    git_would_show = sum(1 for mv in diff_seq(a_lines, b_lines, max_trace) if mv["op"] != "keep")
+    logical_lines_changed = len(del_line_arr) + len(ins_line_arr)
+
+    return {
+        "identical": a_str == b_str,
+        "formattingOnly": tokens_added == 0 and tokens_removed == 0,
+        "stats": {
+            "tokensAdded": tokens_added, "tokensRemoved": tokens_removed,
+            "logicalLinesChanged": logical_lines_changed,
+            "linesReflowed": max(0, git_would_show - logical_lines_changed),
+            "gitWouldShow": git_would_show,
+        },
+        "delLines": del_line_arr, "insLines": ins_line_arr,
+        "aLines": a_lines, "bLines": b_lines,
+    }
+
+
+# ---- rendering -------------------------------------------------------------
+
+PLAIN = {"red": lambda s: s, "green": lambda s: s, "yellow": lambda s: s,
+         "dim": lambda s: s, "bold": lambda s: s, "cyan": lambda s: s}
+
+
+def strip_cr(s):
+    return s[:-1] if s and s[-1] == "\r" else s
+
+
+def format_human(r, file_a, file_b, paint=None):
+    p = paint or PLAIN
+    # Output is written as latin-1 bytes (to round-trip file content faithfully),
+    # so all decoration here is ASCII-only.
+    if r["identical"]:
+        return p["dim"]("identical")
+    if r["formattingOnly"]:
+        n = r["stats"]["gitWouldShow"]
+        return p["green"]("only formatting differs") + p["dim"](
+            f" - no logical change (a line diff would show {n} changed line{'' if n == 1 else 's'})")
+    lines = [p["bold"]("--- " + file_a), p["bold"]("+++ " + file_b)]
+    for L in r["delLines"]:
+        lines.append(p["red"]("-" + str(L) + ": " + strip_cr(r["aLines"][L - 1])))
+    for L in r["insLines"]:
+        lines.append(p["green"]("+" + str(L) + ": " + strip_cr(r["bLines"][L - 1])))
+    lines.append("")
+    s = r["stats"]
+    summary = f"{s['tokensRemoved']} token{'' if s['tokensRemoved'] == 1 else 's'} removed, {s['tokensAdded']} added"
+    summary += f" across {s['logicalLinesChanged']} logical line{'' if s['logicalLinesChanged'] == 1 else 's'}"
+    if s["linesReflowed"] > 0:
+        summary += f" ({s['linesReflowed']} line{'' if s['linesReflowed'] == 1 else 's'} folded as reflow/whitespace)"
+    lines.append(p["red"](summary))
+    return "\n".join(lines)
+
+
+def stat_line(r):
+    s = r["stats"]
+    return "\n".join([
+        "formatting_only=" + ("1" if r["formattingOnly"] else "0"),
+        "tokens_added=" + str(s["tokensAdded"]),
+        "tokens_removed=" + str(s["tokensRemoved"]),
+        "logical_lines_changed=" + str(s["logicalLinesChanged"]),
+        "lines_reflowed=" + str(s["linesReflowed"]),
+        "git_would_show_lines=" + str(s["gitWouldShow"]),
+    ])
+
+
+def to_json(r, file_a, file_b):
+    s = r["stats"]
+    return {
+        "fileA": file_a, "fileB": file_b,
+        "identical": r["identical"],
+        "formatting_only": r["formattingOnly"],
+        "exit_code": 0 if (r["identical"] or r["formattingOnly"]) else 1,
+        "stats": {
+            "tokens_added": s["tokensAdded"],
+            "tokens_removed": s["tokensRemoved"],
+            "logical_lines_changed": s["logicalLinesChanged"],
+            "lines_reflowed": s["linesReflowed"],
+            "git_would_show_lines": s["gitWouldShow"],
+        },
+        "removed": [{"line": L, "text": strip_cr(r["aLines"][L - 1])} for L in r["delLines"]],
+        "added": [{"line": L, "text": strip_cr(r["bLines"][L - 1])} for L in r["insLines"]],
+    }

logicdiff-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: logicdiff
+Version: 0.1.0
+Summary: A whitespace- and reflow-blind diff: folds respacing AND line re-wrapping that git diff -w can't, and tells you if a change is logical or just formatting. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/logicdiff-py
+Project-URL: Repository, https://github.com/jjdoor/logicdiff-py
+Project-URL: Issues, https://github.com/jjdoor/logicdiff-py/issues
+Keywords: diff,whitespace,reflow,format,git,code-review,cli,ci,devtools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# logicdiff
+
+**A whitespace- and reflow-blind diff.** A pull request reindents a file and
+rewraps a few long lines, and now `git diff` shows 80 changed lines — but did
+anything *actually* change? `logicdiff` answers that: it folds away pure
+formatting (respacing **and** line reflow) and shows only the logical changes.
+
+```bash
+logicdiff old.js new.js
+#   only formatting differs - no logical change (a line diff would show 80 changed lines)
+
+logicdiff a.js b.js
+#   --- a.js
+#   +++ b.js
+#   -42:   const total = price * qty;
+#   +51:   const total = price + qty;
+#
+#   1 token removed, 1 added across 2 logical lines (78 lines folded as reflow/whitespace)
+```
+
+Exit `0` when the change is formatting-only (or identical), `1` when there's a
+real logical change — so CI can ask "is this PR just a reformat?" Zero
+dependencies, language-agnostic, also on npm (`npx logicdiff`) — the two
+builds produce **byte-for-byte identical** output.
+
+## Why not `git diff -w`?
+
+`git diff -w` (ignore-all-space) folds *respacing* — but it is still
+line-anchored, so it **cannot fold reflow**. Re-wrap a function signature across
+three lines and `git diff -w` still shows 1 removed + 3 added, even though not a
+single token changed. That exact gap is [GitHub discussion #20610]
+("Ignore Format Changes in Diff"), open and unanswered for years.
+
+`difftastic` solves it beautifully with per-language tree-sitter parsing — but
+it's a multi-megabyte binary, needs a grammar for each language (config/log/DSL
+files fall back to text), and it's a *display* tool with no "is this
+formatting-only?" exit code.
+
+`logicdiff` is the lightweight middle ground: **zero-config, zero-dependency,
+language-agnostic** (works on any text — code, YAML, logs, DSLs), folds *both*
+whitespace and reflow, and gives a one-shot CLI answer plus a CI exit code.
+
+## How it works
+
+It tokenizes each file into a sequence of tokens — a token is a run of
+`[A-Za-z0-9_]` or a single punctuation character, and **whitespace is dropped**.
+So `a+b`, `a + b`, and `a +\n  b` all become the same token stream `[a, + , b]`:
+respacing and line breaks become invisible. It then runs the canonical
+[Myers diff] on the token streams. If the streams are equal, the change is
+formatting-only. If not, the changed tokens are mapped back to their line
+numbers and shown.
+
+Because it has no language parser, whitespace **inside string literals** is also
+ignored — `x = "a b"` and `x = "a  b"` are "formatting only", exactly like
+`git diff -w`. That's a deliberate, documented limitation, not a bug.
+
+## Usage
+
+```bash
+logicdiff old new            # human diff (or "only formatting differs")
+logicdiff old new --stat     # just the counts, machine-friendly key=value
+logicdiff old new --json     # structured output (byte-identical both builds)
+logicdiff old new -q         # no output, exit code only (the CI gate)
+cat new | logicdiff old -     # - reads stdin
+```
+
+`--color=auto|always|never`, `--max-tokens N` (bail over N tokens, default 2,000,000).
+Two wildly dissimilar inputs (a huge edit distance) also bail with exit `2` instead of
+risking the heap — logicdiff is for spotting a real change inside a reformat, not for
+diffing unrelated files.
+
+Exit codes: `0` identical or formatting-only · `1` logical changes · `2` error.
+
+```yaml
+# CI: warn when a PR is more than a reformat
+- run: logicdiff "$BASE" "$HEAD" -q || echo "::warning::real code change, review carefully"
+```
+
+## Install
+
+```bash
+pip install logicdiff # or pipx run logicdiff
+npm i -g logicdiff    # Node build, identical behaviour
+```
+
+Python ≥ 3.8 or Node ≥ 18. No dependencies.
+
+[GitHub discussion #20610]: https://github.com/orgs/community/discussions/20610
+[Myers diff]: https://blog.jcoglan.com/2017/02/12/the-myers-diff-algorithm-part-1/
+
+## License
+
+MIT

logicdiff-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+logicdiff/__init__.py,sha256=AfMUlnHl8u8rZjoIx5oPgdiXLPhM2PZX49rmVZ3y-7s,99
+logicdiff/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+logicdiff/cli.py,sha256=-_ReZ2oKRQGUkHJktc4AsY35pAEPFvsowmqwfGgru7o,5994
+logicdiff/core.py,sha256=H2weFqKTw3kil8avR_TmQaq4dUaWy7hVZNHwkiW12LY,8437
+logicdiff-0.1.0.dist-info/licenses/LICENSE,sha256=N6691UqSpfX5o4zAQqDPGXJbfI_AdM29qLeC5x0sCCs,1079
+logicdiff-0.1.0.dist-info/METADATA,sha256=DykId1XrF-eluVQ_8NQ8Eilr5YLATEN5h_Qe3ceOVVo,4795
+logicdiff-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+logicdiff-0.1.0.dist-info/entry_points.txt,sha256=ZLn9FyvhMwSOIDxvL2H_yLja2h5VyGWjUjkBhAwaGuo,49
+logicdiff-0.1.0.dist-info/top_level.txt,sha256=rJ5O3iVEE-hB24K604G2VaZWdBPCe8kQYpD15C60bb0,10
+logicdiff-0.1.0.dist-info/RECORD,,

logicdiff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logicdiff-0.1.0.dist-info/entry_points.txt

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

logicdiff-0.1.0.dist-info/licenses/LICENSE

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

logicdiff-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+logicdiff