bimdelta 0.4.0__tar.gz

bimdelta-0.4.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.production
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Node
+node_modules/
+
+# IFC temp files
+*.ifc.tmp
+
+# Docker
+docker-compose.override.yml
+
+# Claude
+.claude/
+
+# Revit project and family files, including backups (*.0001.rvt)
+*.rvt
+*.rfa
+
+# Local session file
+\!sessionid.txt

bimdelta-0.4.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: bimdelta
+Version: 0.4.0
+Summary: Code review for building models: element-level IFC diffs in the terminal and in Git
+Project-URL: Repository, https://github.com/kaan36875/BIMDelta
+License-Expression: MIT
+Keywords: bim,diff,git,ifc,ifcopenshell,openbim
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: bimdelta-core==0.4.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bimdelta
+
+Code review for building models. `bimdelta` compares two versions of an IFC model element by
+element and plugs into Git, so `git diff model.ifc` shows which walls, doors and columns changed
+instead of thousands of lines of STEP text.
+
+```sh
+pip install bimdelta
+
+bimdelta diff rev-a.ifc rev-b.ifc                 # table in the terminal
+bimdelta diff rev-a.ifc rev-b.ifc -f markdown     # for a pull request or a report
+bimdelta diff rev-a.ifc rev-b.ifc -f json         # the full DiffResult
+bimdelta diff rev-a.ifc rev-b.ifc --filter "class=IfcWall*,storey=Level 1"
+
+bimdelta install-git-driver                       # once per clone
+git diff HEAD~1 -- model.ifc
+bimdelta blame 2O2Fr$t4X7Zf8NOew3FLOH model.ifc   # commits that touched one element
+bimdelta quantities rev-a.ifc rev-b.ifc --by material
+```
+
+The diff engine is [`bimdelta-core`](https://pypi.org/project/bimdelta-core/), built on
+[IfcOpenShell](https://ifcopenshell.org). Documentation:
+[CLI reference](https://github.com/kaan36875/BIMDelta/blob/main/docs/cli.md) and
+[Git integration](https://github.com/kaan36875/BIMDelta/blob/main/docs/git-integration.md).
+
+Part of [BIMDelta](https://github.com/kaan36875/BIMDelta). MIT licensed.

bimdelta-0.4.0/README.md

@@ -0,0 +1,26 @@
+# bimdelta
+
+Code review for building models. `bimdelta` compares two versions of an IFC model element by
+element and plugs into Git, so `git diff model.ifc` shows which walls, doors and columns changed
+instead of thousands of lines of STEP text.
+
+```sh
+pip install bimdelta
+
+bimdelta diff rev-a.ifc rev-b.ifc                 # table in the terminal
+bimdelta diff rev-a.ifc rev-b.ifc -f markdown     # for a pull request or a report
+bimdelta diff rev-a.ifc rev-b.ifc -f json         # the full DiffResult
+bimdelta diff rev-a.ifc rev-b.ifc --filter "class=IfcWall*,storey=Level 1"
+
+bimdelta install-git-driver                       # once per clone
+git diff HEAD~1 -- model.ifc
+bimdelta blame 2O2Fr$t4X7Zf8NOew3FLOH model.ifc   # commits that touched one element
+bimdelta quantities rev-a.ifc rev-b.ifc --by material
+```
+
+The diff engine is [`bimdelta-core`](https://pypi.org/project/bimdelta-core/), built on
+[IfcOpenShell](https://ifcopenshell.org). Documentation:
+[CLI reference](https://github.com/kaan36875/BIMDelta/blob/main/docs/cli.md) and
+[Git integration](https://github.com/kaan36875/BIMDelta/blob/main/docs/git-integration.md).
+
+Part of [BIMDelta](https://github.com/kaan36875/BIMDelta). MIT licensed.

bimdelta-0.4.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bimdelta"
+version = "0.4.0"
+description = "Code review for building models: element-level IFC diffs in the terminal and in Git"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["ifc", "bim", "diff", "git", "openbim", "ifcopenshell"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    # Released together; keep in step with this package's version.
+    "bimdelta-core==0.4.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+]
+
+[project.scripts]
+bimdelta = "bimdelta_cli.main:app"
+
+[project.urls]
+Repository = "https://github.com/kaan36875/BIMDelta"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bimdelta_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bimdelta-0.4.0/src/bimdelta_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command-line interface and Git integration for BIMDelta."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bimdelta")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

bimdelta-0.4.0/src/bimdelta_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app(prog_name="bimdelta")

bimdelta-0.4.0/src/bimdelta_cli/blame.py

@@ -0,0 +1,275 @@
+"""History of one element through the commits that touched an IFC file.
+
+Consecutive versions of the file are compared with the diff engine, so an element is
+followed the same way ``bimdelta diff`` matches it: by GlobalId, then Tag, then placement.
+A re-export that changes an element's GlobalId therefore does not break its history.
+
+Each comparison is cached in ``<git dir>/bimdelta-cache`` keyed by the two blob ids and the
+diff settings; a later blame of any element in the same file reuses it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from bimdelta_core import ChangeType, Settings, __version__, run_diff
+from bimdelta_core.engine import IFC_LOCK
+from bimdelta_core.parser import parse_ifc
+
+from .gitutil import GitError, git, git_dir, git_text, repo_root, resolve_lfs
+from .render import describe_changes
+
+CACHE_DIRNAME = "bimdelta-cache"
+CACHE_FORMAT = 1
+_SEP = "\x1f"
+
+
+@dataclass
+class Commit:
+    sha: str
+    author: str
+    date: str
+    subject: str
+    blob: str | None  # None where the file does not exist in this commit
+
+
+@dataclass
+class BlameEvent:
+    change: str  # added | modified | removed | reidentified
+    sha: str
+    author: str
+    date: str
+    subject: str
+    global_id: str
+    ifc_class: str | None = None
+    name: str | None = None
+    details: list[str] = field(default_factory=list)
+
+
+@dataclass
+class BlameResult:
+    global_id: str
+    path: str
+    commits_scanned: int
+    truncated: bool
+    events: list[BlameEvent]  # newest first
+    # The element already existed before the oldest commit scanned (--max-commits).
+    present_before: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class BlameError(RuntimeError):
+    pass
+
+
+def blame(
+    global_id: str,
+    path: str | None,
+    cfg: Settings,
+    repo: Path | str = ".",
+    rev: str = "HEAD",
+    max_commits: int | None = None,
+) -> BlameResult:
+    root = repo_root(repo)
+    rel_path = _resolve_path(root, path, rev)
+    # One commit more than asked for: the version just before the window is what the
+    # oldest commit in it is compared with.
+    commits = _history(root, rel_path, rev, None if max_commits is None else max_commits + 1)
+    if not commits:
+        raise BlameError(f"{rel_path} has no history at {rev}")
+    truncated = max_commits is not None and len(commits) > max_commits
+    window = commits[:max_commits] if truncated else commits
+
+    cache = _Cache(git_dir(root) / CACHE_DIRNAME, cfg)
+
+    events: list[BlameEvent] = []
+    tracked = global_id
+    newest = commits[0].blob
+    found = newest is not None and tracked in cache.element_ids(root, newest)
+    present_before = False
+
+    # Walk from newest to oldest; each step compares a commit with its predecessor.
+    for i, newer in enumerate(window):
+        older = commits[i + 1] if i + 1 < len(commits) else None
+        if newer.blob is None:
+            continue
+        older_blob = older.blob if older is not None else None
+        if older_blob is None:
+            # File created (or re-created) here: everything in it was added.
+            info = cache.element_ids(root, newer.blob).get(tracked)
+            if info is not None:
+                events.append(_event("added", newer, tracked, info))
+                found = True
+                break
+            continue
+        if older_blob == newer.blob:
+            continue
+
+        rec = cache.pair(root, older_blob, newer.blob).get(tracked)
+        if rec is None:
+            continue
+        found = True
+        change = rec["change"]
+        if change == ChangeType.ADDED.value:
+            events.append(_event("added", newer, tracked, rec))
+            break
+        if change == ChangeType.REMOVED.value:
+            events.append(_event("removed", newer, tracked, rec))
+            continue
+        previous_id = rec.get("matched_global_id") or tracked
+        if change == ChangeType.MODIFIED.value:
+            events.append(_event("modified", newer, tracked, rec))
+        elif previous_id != tracked:
+            events.append(_event("reidentified", newer, tracked, rec))
+        tracked = previous_id
+    else:
+        if truncated and commits[-1].blob is not None:
+            present_before = tracked in cache.element_ids(root, commits[-1].blob)
+            found = found or present_before
+
+    if not found:
+        raise BlameError(f"no element with GlobalId {global_id} in the history of {rel_path}")
+
+    return BlameResult(
+        global_id=global_id,
+        path=rel_path,
+        commits_scanned=len(window),
+        truncated=truncated,
+        events=events,
+        present_before=present_before,
+    )
+
+
+def _event(change: str, commit: Commit, global_id: str, rec: dict | None) -> BlameEvent:
+    rec = rec or {}
+    return BlameEvent(
+        change=change,
+        sha=commit.sha,
+        author=commit.author,
+        date=commit.date,
+        subject=commit.subject,
+        global_id=global_id,
+        ifc_class=rec.get("ifc_class"),
+        name=rec.get("name"),
+        details=list(rec.get("details", [])),
+    )
+
+
+def _resolve_path(root: Path, path: str | None, rev: str) -> str:
+    if path is not None:
+        full = Path(path)
+        if not full.is_absolute():
+            full = (Path.cwd() / full).resolve()
+        try:
+            return full.relative_to(root.resolve()).as_posix()
+        except ValueError:
+            raise BlameError(f"{path} is not inside the repository at {root}") from None
+    tracked = [
+        p
+        for p in git_text("ls-tree", "-r", "--name-only", rev, cwd=root).splitlines()
+        if p.lower().endswith(".ifc")
+    ]
+    if len(tracked) == 1:
+        return tracked[0]
+    if not tracked:
+        raise BlameError(f"no .ifc file is tracked at {rev}")
+    raise BlameError("several .ifc files are tracked; name one: " + ", ".join(tracked))
+
+
+def _history(root: Path, rel_path: str, rev: str, max_commits: int | None) -> list[Commit]:
+    args = ["log", f"--format=%H{_SEP}%an{_SEP}%aI{_SEP}%s"]
+    if max_commits is not None:
+        args.append(f"--max-count={max_commits}")
+    out = git_text(*args, rev, "--", rel_path, cwd=root)
+    commits = []
+    for line in out.splitlines():
+        sha, author, date, subject = line.split(_SEP, 3)
+        commits.append(Commit(sha, author, date, subject, _blob(root, sha, rel_path)))
+    return commits
+
+
+def _blob(root: Path, sha: str, rel_path: str) -> str | None:
+    try:
+        return git_text("rev-parse", "--verify", "--quiet", f"{sha}:{rel_path}", cwd=root)
+    except GitError:
+        return None
+
+
+class _Cache:
+    def __init__(self, directory: Path, cfg: Settings):
+        self.dir = directory
+        self.cfg = cfg
+        key = f"{CACHE_FORMAT}|{__version__}|{cfg.model_dump_json()}"
+        self.settings_key = hashlib.blake2b(key.encode(), digest_size=8).hexdigest()
+
+    def pair(self, root: Path, old_blob: str, new_blob: str) -> dict[str, dict]:
+        """Every element of the newer version that differs from the older one, keyed by
+        its GlobalId; removed elements are keyed by their GlobalId in the older version."""
+        path = self.dir / f"pair-{old_blob}-{new_blob}-{self.settings_key}.json"
+        cached = self._read(path)
+        if cached is not None:
+            return cached
+
+        with tempfile.TemporaryDirectory(prefix="bimdelta-") as tmp:
+            old = _materialise(root, old_blob, Path(tmp), "old")
+            new = _materialise(root, new_blob, Path(tmp), "new")
+            result = run_diff(str(old), "old.ifc", str(new), "new.ifc", self.cfg)
+
+        records: dict[str, dict] = {}
+        for el in result.elements:
+            if el.change_type == ChangeType.UNCHANGED and not el.matched_global_id:
+                continue
+            records[el.global_id] = {
+                "change": el.change_type.value,
+                "ifc_class": el.ifc_class,
+                "name": el.name,
+                "matched_global_id": el.matched_global_id,
+                "details": describe_changes(el) if el.change_type == ChangeType.MODIFIED else [],
+            }
+        self._write(path, records)
+        return records
+
+    def element_ids(self, root: Path, blob: str) -> dict[str, dict]:
+        """Class and name of every element in one version, keyed by GlobalId."""
+        path = self.dir / f"elements-{blob}.json"
+        cached = self._read(path)
+        if cached is not None:
+            return cached
+
+        with tempfile.TemporaryDirectory(prefix="bimdelta-") as tmp:
+            file = _materialise(root, blob, Path(tmp), "model")
+            with IFC_LOCK:
+                model = parse_ifc(str(file), "model.ifc", self.cfg.include_openings)
+                elements = {
+                    gid: {"ifc_class": el.ifc_class, "name": el.name}
+                    for gid, el in model.elements.items()
+                }
+        self._write(path, elements)
+        return elements
+
+    def _read(self, path: Path):
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+
+    def _write(self, path: Path, data) -> None:
+        try:
+            self.dir.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(data), encoding="utf-8")
+            tmp.replace(path)
+        except OSError:
+            pass  # The cache is an optimisation only.
+
+
+def _materialise(root: Path, blob: str, directory: Path, stem: str) -> Path:
+    path = directory / f"{stem}.ifc"
+    path.write_bytes(git("cat-file", "blob", blob, cwd=root))
+    return resolve_lfs(path, directory, cwd=root)

bimdelta-0.4.0/src/bimdelta_cli/filters.py

@@ -0,0 +1,49 @@
+"""The ``--filter`` expression: ``class=IfcWall*,storey=Level 1,change=modified``.
+
+Terms are separated by commas. Terms with the same key are alternatives (OR), different
+keys must all match (AND). Values are case-insensitive and may use ``*`` and ``?``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from fnmatch import fnmatchcase
+
+from bimdelta_core import ElementDiff
+
+KEYS = ("class", "storey", "change", "name", "id")
+
+
+class FilterError(ValueError):
+    pass
+
+
+def parse_filter(expression: str) -> Callable[[ElementDiff], bool]:
+    terms: dict[str, list[str]] = {}
+    for raw in expression.split(","):
+        if not raw.strip():
+            continue
+        key, sep, value = raw.partition("=")
+        key = key.strip().lower()
+        if not sep or not value.strip():
+            raise FilterError(f"expected key=value, got {raw.strip()!r}")
+        if key not in KEYS:
+            raise FilterError(f"unknown filter key {key!r}; valid keys: {', '.join(KEYS)}")
+        terms.setdefault(key, []).append(value.strip().lower())
+
+    def keep(el: ElementDiff) -> bool:
+        fields = {
+            "class": [el.ifc_class],
+            "storey": [el.storey or "", el.old_storey or ""],
+            "change": [el.change_type.value],
+            "name": [el.name or "", el.old_name or ""],
+            "id": [el.global_id, el.matched_global_id or ""],
+        }
+        return all(
+            any(
+                fnmatchcase(field.lower(), pattern) for field in fields[key] for pattern in patterns
+            )
+            for key, patterns in terms.items()
+        )
+
+    return keep

bimdelta-0.4.0/src/bimdelta_cli/gitdriver.py

@@ -0,0 +1,120 @@
+"""Registering BIMDelta as Git's diff driver for ``*.ifc`` files.
+
+Two hooks are installed under ``[diff "ifc"]``:
+
+* ``command``: an external diff driver. ``git diff`` hands it both versions of the file,
+  so it shows the real matched, noise-filtered element diff as Markdown.
+* ``textconv``: turns one version into stable text (see ``snapshot``). Git uses it where no
+  external driver runs: ``git log -p``, ``git show`` and ``git diff --no-ext-diff``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .gitutil import git, git_text, repo_root
+from .snapshot import XFUNCNAME
+
+DRIVER = "ifc"
+PATTERN = "*.ifc"
+
+
+@dataclass
+class InstallReport:
+    scope: str
+    command: str
+    attributes_file: Path
+    attributes_changed: bool
+
+
+def default_command() -> str:
+    """How Git should invoke this CLI.
+
+    The ``bimdelta`` script is used when it is on PATH. Otherwise (e.g. installed in a
+    virtual environment that is not activated) the current interpreter is called directly,
+    so the driver keeps working from any shell.
+    """
+    if shutil.which("bimdelta"):
+        return "bimdelta"
+    python = Path(sys.executable).as_posix()
+    return f'"{python}" -m bimdelta_cli'
+
+
+def install(
+    global_: bool = False, command: str | None = None, cwd: Path | str = "."
+) -> InstallReport:
+    command = command or default_command()
+    scope = ["--global"] if global_ else []
+    if not global_:
+        cwd = repo_root(cwd)
+
+    git("config", *scope, f"diff.{DRIVER}.command", f"{command} git-diff", cwd=cwd)
+    git("config", *scope, f"diff.{DRIVER}.textconv", f"{command} textconv", cwd=cwd)
+    git("config", *scope, f"diff.{DRIVER}.xfuncname", XFUNCNAME, cwd=cwd)
+
+    attributes = global_attributes_file(cwd) if global_ else Path(cwd) / ".gitattributes"
+    changed = ensure_attribute(attributes)
+    return InstallReport(
+        scope="global" if global_ else "repository",
+        command=command,
+        attributes_file=attributes,
+        attributes_changed=changed,
+    )
+
+
+def uninstall(global_: bool = False, cwd: Path | str = ".") -> None:
+    """Remove the ``[diff "ifc"]`` section. The ``.gitattributes`` line is left in place: it
+    is committed and shared, and does nothing without the driver."""
+    scope = ["--global"] if global_ else []
+    if not global_:
+        cwd = repo_root(cwd)
+    git("config", *scope, "--remove-section", f"diff.{DRIVER}", cwd=cwd)
+
+
+def global_attributes_file(cwd: Path | str = ".") -> Path:
+    try:
+        configured = git_text("config", "--global", "--path", "core.attributesFile", cwd=cwd)
+    except Exception:
+        configured = ""
+    if configured:
+        return Path(configured).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "git" / "attributes"
+
+
+def ensure_attribute(path: Path) -> bool:
+    """Make ``*.ifc`` use ``diff=ifc`` in an attributes file. Returns True if it changed.
+
+    An existing ``*.ifc`` line keeps its other attributes; Git LFS writes ``diff=lfs`` there,
+    which is replaced (LFS still works: content is resolved through ``git lfs smudge``).
+    """
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    lines = text.splitlines()
+    wanted = f"diff={DRIVER}"
+    for i, line in enumerate(lines):
+        fields = line.split()
+        if not fields or fields[0] != PATTERN:
+            continue
+        attrs = [a for a in fields[1:] if not _is_diff_attr(a)]
+        new_line = " ".join([PATTERN, *attrs, wanted])
+        if fields[1:].count(wanted) == 1 and not any(
+            _is_diff_attr(a) and a != wanted for a in fields[1:]
+        ):
+            return False
+        lines[i] = new_line
+        break
+    else:
+        lines.append(f"{PATTERN} {wanted}")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+    return True
+
+
+def _is_diff_attr(attr: str) -> bool:
+    return attr in ("diff", "-diff", "!diff") or attr.startswith("diff=")