bimdelta 0.4.0__py3-none-any.whl

bimdelta-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+bimdelta_cli/__init__.py,sha256=VBHsWNkVLfLoC9EUlwuKA2LiV9dSHNsENB53PnkteDM,224
+bimdelta_cli/__main__.py,sha256=kNzCcCqnolrhVed4G-dka0u_bNu88EPIXO7rVV9NV1c,49
+bimdelta_cli/blame.py,sha256=v1P6W2TjlRMhJ_xeQfzDZ3Nn_1AOJWnmAVVx3b_RHhY,9707
+bimdelta_cli/filters.py,sha256=hk2CYqEr-avjAY64OtCY9i7aS3H6Kgb9-0GHlCYUa8M,1629
+bimdelta_cli/gitdriver.py,sha256=7He5KJOmBtJUOXXVcZEpgiuGkeW1b6uf7Y8us7N6X5M,4115
+bimdelta_cli/gitutil.py,sha256=3Pj3ki6TlXiTC2NoQWsComNHrW1NbY66nQY3x82UXaY,2633
+bimdelta_cli/main.py,sha256=GgxRIoqRg8I0Gg4Mdg4FNVRIA1wAilsE_gcZQ62oVOc,13798
+bimdelta_cli/render.py,sha256=fGqet-Xzunn9G_Wd3VtgJOCV4A1WsTwfzNeCrX4rJdA,8206
+bimdelta_cli/snapshot.py,sha256=smhDR3SsyuXbPM10tzpmPnJyWgNQ69TgY4Df5AxZwuU,3502
+bimdelta-0.4.0.dist-info/METADATA,sha256=rCOxm5NjJZ4SU2uz3ex8kcS9aUx1BDZE-V405h3lNIc,2000
+bimdelta-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bimdelta-0.4.0.dist-info/entry_points.txt,sha256=t1l8Yk6jNSPWviknUpvz-OSbIrY3Ns50TwTxBTet0es,51
+bimdelta-0.4.0.dist-info/RECORD,,

bimdelta-0.4.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

bimdelta-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bimdelta = bimdelta_cli.main:app

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_cli/__main__.py

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

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_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_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=")

bimdelta_cli/gitutil.py

@@ -0,0 +1,70 @@
+"""Small helpers around the ``git`` executable."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+LFS_POINTER_HEADER = b"version https://git-lfs.github.com/spec/v1"
+# LFS pointer files are tiny; anything bigger is real content.
+LFS_POINTER_MAX_BYTES = 1024
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def git(*args: str, cwd: Path | str | None = None, input: bytes | None = None) -> bytes:
+    try:
+        proc = subprocess.run(
+            ["git", *args], cwd=cwd, input=input, capture_output=True, check=False
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git was not found on PATH") from exc
+    if proc.returncode != 0:
+        msg = proc.stderr.decode("utf-8", "replace").strip()
+        raise GitError(msg or f"git {' '.join(args)} failed with exit code {proc.returncode}")
+    return proc.stdout
+
+
+def git_text(*args: str, cwd: Path | str | None = None) -> str:
+    return git(*args, cwd=cwd).decode("utf-8", "replace").strip()
+
+
+def repo_root(start: Path | str = ".") -> Path:
+    return Path(git_text("rev-parse", "--show-toplevel", cwd=start))
+
+
+def git_dir(start: Path | str = ".") -> Path:
+    """The directory shared by all worktrees of the repository (normally ``.git``)."""
+    path = Path(git_text("rev-parse", "--git-common-dir", cwd=start))
+    return path if path.is_absolute() else (Path(start) / path).resolve()
+
+
+def is_lfs_pointer(data: bytes) -> bool:
+    return len(data) <= LFS_POINTER_MAX_BYTES and data.startswith(LFS_POINTER_HEADER)
+
+
+def resolve_lfs(path: Path, scratch: Path, cwd: Path | str | None = None) -> Path:
+    """If ``path`` holds a Git LFS pointer, write the real content into the ``scratch``
+    directory and return that file; otherwise return ``path`` unchanged.
+
+    Git hands diff drivers the stored blob, which for LFS-tracked files is the pointer, not
+    the model. The object must already be in the local LFS store (``git lfs fetch``).
+    """
+    with open(path, "rb") as f:
+        head = f.read(LFS_POINTER_MAX_BYTES + 1)
+    if not is_lfs_pointer(head):
+        return path
+    try:
+        content = git("lfs", "smudge", cwd=cwd, input=path.read_bytes())
+    except GitError as exc:
+        raise GitError(
+            f"{path.name} is a Git LFS pointer and its content is not available locally "
+            f"(run `git lfs fetch`): {exc}"
+        ) from exc
+    if is_lfs_pointer(content[: LFS_POINTER_MAX_BYTES + 1]):
+        raise GitError(f"{path.name}: Git LFS object is not downloaded (run `git lfs fetch`)")
+    resolved = scratch / f"lfs-{path.stem}.ifc"
+    resolved.write_bytes(content)
+    return resolved

bimdelta_cli/main.py

@@ -0,0 +1,398 @@
+"""The ``bimdelta`` command."""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, NoReturn
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+from rich.text import Text
+
+import bimdelta_core
+from bimdelta_core import (
+    CONFIG_FILENAME,
+    Settings,
+    filter_result,
+    load_settings,
+    quantity_delta,
+    run_diff,
+)
+from bimdelta_core.engine import IFC_LOCK
+from bimdelta_core.parser import parse_ifc
+
+from . import __version__, gitdriver
+from .blame import BlameError
+from .blame import blame as run_blame
+from .filters import FilterError, parse_filter
+from .gitutil import GitError, resolve_lfs
+from .render import has_changes, md_escape, print_table, to_markdown
+from .snapshot import snapshot
+
+app = typer.Typer(
+    name="bimdelta",
+    help="Code review for building models: element-level diffs of IFC files.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode=None,
+)
+
+console = Console()
+# For messages: long paths and commit subjects should not be broken across lines.
+say = Console(soft_wrap=True)
+err = Console(stderr=True, soft_wrap=True)
+
+EXIT_CHANGES = 1
+EXIT_ERROR = 2
+
+
+class Format(str, Enum):
+    table = "table"
+    json = "json"
+    markdown = "markdown"
+
+
+class GroupBy(str, Enum):
+    by_class = "class"
+    material = "material"
+
+
+def _fail(message: str) -> NoReturn:
+    err.print(Text(f"error: {message}", style="red"))
+    raise typer.Exit(EXIT_ERROR)
+
+
+def _utf8_stdout() -> None:
+    # Windows consoles and pipes default to a legacy code page; output contains → and ∅.
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8", errors="replace")
+
+
+def find_config(start: Path) -> Path | None:
+    """The nearest ``.bimdelta.yml`` in ``start`` or one of its parents."""
+    for directory in (start.resolve(), *start.resolve().parents):
+        candidate = directory / CONFIG_FILENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _settings(config: Path | None, strict: bool) -> Settings:
+    path = config if config is not None else find_config(Path.cwd())
+    overrides = {"strict": True} if strict else {}
+    try:
+        return load_settings(path, **overrides)
+    except (OSError, ValueError) as exc:
+        _fail(str(exc))
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"bimdelta {__version__} (bimdelta-core {bimdelta_core.__version__})")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = False,
+) -> None:
+    _utf8_stdout()
+
+
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--config",
+        help=f"Settings file. Default: the nearest {CONFIG_FILENAME} here or in a parent.",
+        dir_okay=False,
+    ),
+]
+StrictOption = Annotated[
+    bool, typer.Option("--strict", help="Turn the noise filter off and report every difference.")
+]
+ExistingFile = Annotated[Path, typer.Argument(exists=True, dir_okay=False, readable=True)]
+
+
+@app.command()
+def diff(
+    v1: ExistingFile,
+    v2: ExistingFile,
+    format: Annotated[Format, typer.Option("--format", "-f", help="Output format.")] = Format.table,
+    summary_only: Annotated[
+        bool, typer.Option("--summary-only", help="Counts only, no element list.")
+    ] = False,
+    filter: Annotated[
+        str | None,
+        typer.Option(
+            "--filter",
+            help="Keep matching elements only, e.g. 'class=IfcWall*,storey=Level 1'. "
+            "Keys: class, storey, change, name, id. Same key = OR, different keys = AND.",
+        ),
+    ] = None,
+    strict: StrictOption = False,
+    config: ConfigOption = None,
+    limit: Annotated[
+        int, typer.Option(help="Most elements to list in table/markdown output; 0 = all.")
+    ] = 100,
+    exit_code: Annotated[
+        bool, typer.Option("--exit-code", help="Exit with 1 if there are changes, like git diff.")
+    ] = False,
+) -> None:
+    """Compare two versions of an IFC model."""
+    cfg = _settings(config, strict)
+    keep = None
+    if filter:
+        try:
+            keep = parse_filter(filter)
+        except FilterError as exc:
+            _fail(f"--filter: {exc}")
+
+    try:
+        result = run_diff(str(v1), v1.name, str(v2), v2.name, cfg)
+    except Exception as exc:
+        _fail(f"could not compare the models: {exc}")
+    if keep is not None:
+        result = filter_result(result, keep)
+
+    if format == Format.json:
+        payload = result.summary if summary_only else result
+        sys.stdout.write(payload.model_dump_json(indent=2) + "\n")
+    elif format == Format.markdown:
+        sys.stdout.write(to_markdown(result, summary_only=summary_only, limit=limit))
+    else:
+        print_table(console, result, summary_only=summary_only, limit=limit)
+
+    if exit_code and has_changes(result):
+        raise typer.Exit(EXIT_CHANGES)
+
+
+@app.command()
+def quantities(
+    v1: ExistingFile,
+    v2: ExistingFile,
+    by: Annotated[GroupBy, typer.Option("--by", help="Group by IFC class or material.")] = (
+        GroupBy.by_class
+    ),
+    format: Annotated[Format, typer.Option("--format", "-f")] = Format.table,
+) -> None:
+    """Quantity take-off of two versions and the change, from the exported quantity sets."""
+    try:
+        result = quantity_delta(str(v1), v1.name, str(v2), v2.name, by.value)
+    except Exception as exc:
+        _fail(f"could not read quantities: {exc}")
+
+    if format == Format.json:
+        sys.stdout.write(result.model_dump_json(indent=2) + "\n")
+        return
+
+    rows = [*result.rows, result.total]
+    head = [
+        "Class" if by == GroupBy.by_class else "Material",
+        "Count",
+        "Length m",
+        "Area m²",
+        "Volume m³",
+    ]
+
+    def cells(row) -> list[str]:
+        out = [f"{row.v2.count} ({row.delta.count:+d})"]
+        for attr in ("length", "area", "volume"):
+            new, delta = getattr(row.v2, attr), getattr(row.delta, attr)
+            out.append(f"{new:,.2f} ({delta:+,.2f})")
+        return out
+
+    missing = [
+        f"{n} element(s) in {name} have no quantities (export base quantities to include them)."
+        for n, name in (
+            (result.v1_without_quantities, result.v1_filename),
+            (result.v2_without_quantities, result.v2_filename),
+        )
+        if n
+    ]
+
+    if format == Format.markdown:
+        lines = [
+            f"### Quantities: {md_escape(result.v1_filename)} → {md_escape(result.v2_filename)}",
+            "",
+            "| " + " | ".join(head) + " |",
+            "|---|" + "---:|" * (len(head) - 1),
+        ]
+        for row in rows:
+            group = f"**{row.group}**" if row is result.total else md_escape(row.group)
+            lines.append(f"| {group} | " + " | ".join(cells(row)) + " |")
+        lines += [f"\n> {m}" for m in missing]
+        sys.stdout.write("\n".join(lines) + "\n")
+        return
+
+    table = Table(title=f"{result.v1_filename} → {result.v2_filename}  (v2 value, change)")
+    for i, h in enumerate(head):
+        table.add_column(h, justify="left" if i == 0 else "right")
+    for row in result.rows:
+        table.add_row(Text(row.group), *cells(row))
+    table.add_section()
+    table.add_row(Text("Total", "bold"), *cells(result.total))
+    console.print(table)
+    for m in missing:
+        console.print(Text(m, "dim"))
+
+
+@app.command()
+def textconv(
+    path: ExistingFile,
+    strict: StrictOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Print one model as stable text (Git textconv protocol)."""
+    cfg = _settings(config, strict)
+    with tempfile.TemporaryDirectory(prefix="bimdelta-") as tmp:
+        try:
+            model = resolve_lfs(path, Path(tmp))
+            sys.stdout.write(snapshot(str(model), path.name, cfg))
+        except Exception as exc:
+            # A failure here would abort the whole `git log -p`; print a line instead.
+            sys.stdout.write(f"# bimdelta: could not read {path.name}: {exc}\n")
+
+
+@app.command("git-diff", hidden=True)
+def git_diff(
+    args: Annotated[list[str], typer.Argument(help="Arguments passed by Git.")],
+    strict: StrictOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """External diff driver: path old-file old-hex old-mode new-file new-hex new-mode."""
+    if len(args) < 7:
+        _fail("git-diff expects the 7 arguments of GIT_EXTERNAL_DIFF")
+    name, old_file, _old_hex, old_mode, new_file, _new_hex, new_mode = args[:7]
+    cfg = _settings(config, strict)
+
+    sys.stdout.write(f"diff --bimdelta a/{name} b/{name}\n")
+    with tempfile.TemporaryDirectory(prefix="bimdelta-") as tmp:
+        try:
+            old = None if old_mode == "." else resolve_lfs(Path(old_file), Path(tmp))
+            new = None if new_mode == "." else resolve_lfs(Path(new_file), Path(tmp))
+            if old is None or new is None:
+                present = old or new
+                with IFC_LOCK:
+                    count = len(parse_ifc(str(present), name).elements)
+                state = "new file" if old is None else "deleted file"
+                sys.stdout.write(f"### BIMDelta: {md_escape(name)} ({state}, {count} elements)\n")
+                return
+            result = run_diff(str(old), name, str(new), name, cfg)
+            sys.stdout.write(to_markdown(result, title=name))
+        except Exception as exc:
+            sys.stdout.write(f"bimdelta: could not compare {name}: {exc}\n")
+        finally:
+            sys.stdout.flush()
+
+
+@app.command("install-git-driver")
+def install_git_driver(
+    global_: Annotated[
+        bool, typer.Option("--global", help="Configure for all repositories of this user.")
+    ] = False,
+    command: Annotated[
+        str | None,
+        typer.Option(help="How Git should run bimdelta. Default: detected from this install."),
+    ] = None,
+    uninstall: Annotated[
+        bool, typer.Option("--uninstall", help="Remove the driver configuration.")
+    ] = False,
+) -> None:
+    """Make `git diff`, `git log -p` and `git show` understand .ifc files."""
+    try:
+        if uninstall:
+            gitdriver.uninstall(global_)
+            say.print("Removed the [bold]diff.ifc[/] driver configuration.")
+            return
+        report = gitdriver.install(global_, command)
+    except GitError as exc:
+        _fail(str(exc))
+
+    say.print(f"Configured the [bold]diff.ifc[/] driver ({report.scope}): {escape(report.command)}")
+    if report.attributes_changed:
+        say.print(f"Added '*.ifc diff=ifc' to {escape(str(report.attributes_file))}")
+    else:
+        say.print(f"{escape(str(report.attributes_file))} already maps *.ifc to the driver")
+    if not global_:
+        say.print(
+            Text(
+                "Commit .gitattributes so others get the mapping; each clone still needs "
+                "`bimdelta install-git-driver` once.",
+                "dim",
+            )
+        )
+
+
+@app.command()
+def blame(
+    global_id: Annotated[str, typer.Argument(metavar="GLOBALID", help="Element GlobalId.")],
+    path: Annotated[
+        str | None,
+        typer.Argument(help="IFC file in the repository. Optional if only one is tracked."),
+    ] = None,
+    repo: Annotated[Path, typer.Option(help="Repository directory.", file_okay=False)] = Path("."),
+    rev: Annotated[str, typer.Option(help="Revision to start from.")] = "HEAD",
+    max_commits: Annotated[
+        int | None, typer.Option("--max-commits", min=1, help="Only look at the N latest commits.")
+    ] = None,
+    format: Annotated[Format, typer.Option("--format", "-f")] = Format.table,
+    strict: StrictOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Show the commits that added, changed or removed an element."""
+    cfg = _settings(config if config is not None else find_config(repo), strict)
+    try:
+        result = run_blame(global_id, path, cfg, repo=repo, rev=rev, max_commits=max_commits)
+    except (BlameError, GitError) as exc:
+        _fail(str(exc))
+
+    if format == Format.json:
+        sys.stdout.write(json.dumps(result.to_dict(), indent=2, ensure_ascii=False) + "\n")
+        return
+
+    md = format == Format.markdown
+    if md:
+        sys.stdout.write(f"### History of `{result.global_id}` in {md_escape(result.path)}\n\n")
+    for ev in result.events:
+        what = f"{ev.ifc_class or ''} {ev.name or ''}".strip()
+        line = f'{ev.change} @ {ev.sha[:10]} ({ev.author}, {ev.date[:10]}): "{ev.subject}"'
+        if md:
+            sys.stdout.write(f"- {md_escape(line)}\n")
+            for d in ev.details:
+                sys.stdout.write(f"  - {md_escape(d)}\n")
+            continue
+        style = {"added": "green", "removed": "red", "modified": "yellow"}.get(ev.change, "cyan")
+        say.print(
+            Text.assemble(
+                (f"{ev.change:<12}", style),
+                (ev.sha[:10], "bold"),
+                "  ",
+                f"{ev.date[:10]}  {ev.author}  ",
+                (f'"{ev.subject}"', "italic"),
+                (f"  {what}" if what else "", "dim"),
+            )
+        )
+        for d in ev.details:
+            say.print(Text(f"{'':12}{d}", "dim"))
+    tail = []
+    if result.present_before:
+        tail.append(f"already present before the {result.commits_scanned} commit(s) scanned")
+    elif result.truncated:
+        tail.append(f"history limited to {result.commits_scanned} commits")
+    if not result.events and not tail:
+        tail.append("no changes found")
+    for t in tail:
+        if md:
+            sys.stdout.write(f"\n_{md_escape(t)}_\n")
+        else:
+            say.print(Text(t, "dim"))

bimdelta_cli/render.py

@@ -0,0 +1,232 @@
+"""Text renderings of a DiffResult: a Rich terminal table and Markdown."""
+
+from __future__ import annotations
+
+import re
+
+from rich import box
+from rich.console import Console, Group
+from rich.markup import escape
+from rich.table import Table
+from rich.text import Text
+
+from bimdelta_core import ChangeType, DiffResult, ElementDiff
+
+CHANGE_ORDER = (ChangeType.MODIFIED, ChangeType.ADDED, ChangeType.REMOVED)
+CHANGE_STYLE = {
+    ChangeType.ADDED: "green",
+    ChangeType.REMOVED: "red",
+    ChangeType.MODIFIED: "yellow",
+    ChangeType.UNCHANGED: "dim",
+}
+COLUMNS = ("added", "removed", "modified", "unchanged")
+
+
+def format_value(value) -> str:
+    if value is None:
+        return "∅"
+    if isinstance(value, float):
+        return f"{value:.6g}"
+    return str(value)
+
+
+def describe_changes(el: ElementDiff) -> list[str]:
+    """What changed on a modified element, one short phrase per change."""
+    parts = [
+        f"{p.pset_name}.{p.property_name}: {format_value(p.old_value)} → "
+        f"{format_value(p.new_value)}"
+        for p in el.property_changes
+    ]
+    if el.type_changed:
+        parts.append(f"type: {el.old_type_name} → {el.new_type_name}")
+    if el.name_changed:
+        parts.append(f"name: {el.old_name} → {el.name}")
+    if el.storey_changed:
+        parts.append(f"storey: {el.old_storey} → {el.storey}")
+    if el.placement_changed:
+        parts.append("moved")
+    if el.geometry_changed:
+        parts.append("geometry changed")
+    if el.geometry_unknown:
+        parts.append("geometry not evaluated")
+    return parts
+
+
+def identity_note(el: ElementDiff) -> str | None:
+    if el.matched_global_id and el.match_method is not None:
+        return f"matched by {el.match_method.value.replace('_', ' ')}, was {el.matched_global_id}"
+    return None
+
+
+def changed_elements(result: DiffResult, change: ChangeType) -> list[ElementDiff]:
+    els = [el for el in result.elements if el.change_type == change]
+    return sorted(els, key=lambda el: (el.ifc_class, el.storey or "", el.name or "", el.global_id))
+
+
+def has_changes(result: DiffResult) -> bool:
+    s = result.summary
+    return bool(s.added or s.removed or s.modified)
+
+
+# --- Markdown -------------------------------------------------------------------------
+
+_MD_SPECIAL = re.compile(r"([\\`*_{}\[\]<>|#~])")
+
+
+def md_escape(text: str) -> str:
+    """Escape text from a model (names, values) so it cannot inject Markdown or HTML."""
+    return _MD_SPECIAL.sub(r"\\\1", text.replace("\r", " ").replace("\n", " "))
+
+
+def to_markdown(
+    result: DiffResult,
+    *,
+    summary_only: bool = False,
+    limit: int = 100,
+    title: str | None = None,
+) -> str:
+    s = result.summary
+    title = title or f"{result.v1_filename} → {result.v2_filename}"
+    lines = [f"### BIMDelta: {md_escape(title)}", ""]
+
+    if not has_changes(result):
+        lines.append(f"No element changes ({s.unchanged} unchanged).")
+    else:
+        lines += [
+            "| Class | Added | Removed | Modified | Unchanged |",
+            "|---|---:|---:|---:|---:|",
+            f"| **Total** | {s.added} | {s.removed} | {s.modified} | {s.unchanged} |",
+        ]
+        for cls, counts in sorted(s.by_class.items()):
+            if not any(counts.get(c, 0) for c in COLUMNS[:3]):
+                continue
+            cells = " | ".join(str(counts.get(c, 0)) for c in COLUMNS)
+            lines.append(f"| {md_escape(cls)} | {cells} |")
+
+    lines += _markdown_notes(result)
+
+    if not summary_only:
+        for change in CHANGE_ORDER:
+            els = changed_elements(result, change)
+            if not els:
+                continue
+            lines += ["", f"#### {change.value.capitalize()} ({len(els)})", ""]
+            shown = els if limit <= 0 else els[:limit]
+            lines += [_markdown_element(el) for el in shown]
+            if len(els) > len(shown):
+                lines.append(f"- … and {len(els) - len(shown)} more")
+
+    return "\n".join(lines) + "\n"
+
+
+def _markdown_element(el: ElementDiff) -> str:
+    head = f"- `{el.ifc_class}` **{md_escape(el.name or '(unnamed)')}**"
+    if el.storey:
+        head += f" ({md_escape(el.storey)})"
+    head += f" `{el.global_id}`"
+    details = describe_changes(el) if el.change_type == ChangeType.MODIFIED else []
+    note = identity_note(el)
+    if note:
+        details.append(note)
+    if details:
+        head += " — " + "; ".join(md_escape(d) for d in details)
+    return head
+
+
+def notes(result: DiffResult, esc=str, strong=str) -> list[str]:
+    """Model-level remarks: storey moves, unevaluated geometry, what the noise filter hid.
+
+    ``esc`` escapes text taken from the models; ``strong`` emphasises it.
+    """
+    s = result.summary
+    out: list[str] = []
+    for ch in s.storey_elevation_changes:
+        out.append(
+            f"Storey {strong(esc(ch.storey_name))} elevation: "
+            f"{ch.old_elevation:.3f} → {ch.new_elevation:.3f} m"
+        )
+    if s.geometry_unknown:
+        out.append(f"Geometry could not be evaluated for {s.geometry_unknown} element(s).")
+    if s.noise is not None and not s.noise.strict:
+        hidden = []
+        if s.noise.ignored_property_changes:
+            hidden.append(f"{s.noise.ignored_property_changes} property difference(s) ignored")
+        one_sided = s.noise.one_sided_psets
+        if one_sided:
+            names = ", ".join(esc(p.pset_name) for p in one_sided[:5])
+            if len(one_sided) > 5:
+                names += f" and {len(one_sided) - 5} more"
+            hidden.append(f"property sets in one version only: {names}")
+        if hidden:
+            out.append("Noise filter: " + "; ".join(hidden) + " (--strict shows them).")
+    return out
+
+
+def _markdown_notes(result: DiffResult) -> list[str]:
+    found = notes(result, esc=md_escape, strong=lambda t: f"**{t}**")
+    return ["", *(f"> {n}" for n in found)] if found else []
+
+
+# --- Terminal -------------------------------------------------------------------------
+
+
+def print_table(
+    console: Console, result: DiffResult, *, summary_only: bool = False, limit: int = 100
+) -> None:
+    s = result.summary
+    console.print(
+        Text.assemble(
+            ("BIMDelta  ", "bold"),
+            (result.v1_filename, "cyan"),
+            " → ",
+            (result.v2_filename, "cyan"),
+            (f"   ({result.v1_ifc_schema} → {result.v2_ifc_schema})", "dim"),
+        )
+    )
+
+    summary = Table(box=box.SIMPLE_HEAD, show_edge=False)
+    summary.add_column("Class")
+    for col in COLUMNS:
+        summary.add_column(col.capitalize(), justify="right", style=CHANGE_STYLE[ChangeType(col)])
+    summary.add_row(
+        "[bold]Total[/]", str(s.added), str(s.removed), str(s.modified), str(s.unchanged)
+    )
+    summary.add_section()
+    for cls, counts in sorted(s.by_class.items()):
+        summary.add_row(escape(cls), *(str(counts.get(c, 0)) for c in COLUMNS))
+    console.print(summary)
+
+    for note in notes(result):
+        console.print(Text(note, "dim"))
+
+    if summary_only or not has_changes(result):
+        return
+
+    elements = Table(box=box.SIMPLE_HEAD, show_edge=False, expand=False)
+    elements.add_column("Change")
+    elements.add_column("Class")
+    elements.add_column("Name", overflow="fold")
+    elements.add_column("Storey")
+    elements.add_column("GlobalId", style="dim", no_wrap=True)
+    elements.add_column("What changed", overflow="fold")
+
+    rows = [el for change in CHANGE_ORDER for el in changed_elements(result, change)]
+    shown = rows if limit <= 0 else rows[:limit]
+    for el in shown:
+        details = describe_changes(el) if el.change_type == ChangeType.MODIFIED else []
+        note = identity_note(el)
+        if note:
+            details.append(note)
+        elements.add_row(
+            Text(el.change_type.value, CHANGE_STYLE[el.change_type]),
+            Text(el.ifc_class),
+            Text(el.name or ""),
+            Text(el.storey or ""),
+            Text(el.global_id),
+            Group(*(Text(d) for d in details)) if details else Text(""),
+        )
+    console.print(elements)
+    if len(rows) > len(shown):
+        console.print(
+            Text(f"… and {len(rows) - len(shown)} more (use --limit 0 to list all)", "dim")
+        )

bimdelta_cli/snapshot.py

@@ -0,0 +1,92 @@
+"""A line-oriented text form of one IFC model, for Git's textconv protocol.
+
+Git runs textconv on each version separately and line-diffs the outputs, so the text has
+to be stable: one header line per element, sorted, followed by indented lines for its
+type, placement, geometry and properties. A changed property then shows up as one
+``-``/``+`` pair under the element's header (which ``diff.ifc.xfuncname`` puts in the
+hunk header). For a matched, noise-filtered comparison use ``bimdelta diff``.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterator
+
+from bimdelta_core import Settings
+from bimdelta_core.engine import IFC_LOCK
+from bimdelta_core.geometry import representation_fingerprint
+from bimdelta_core.noise import PropertyFilter
+from bimdelta_core.parser import ParsedElement, parse_ifc
+
+from .render import format_value
+
+# Matches the element header lines below; used as the Git hunk header pattern.
+XFUNCNAME = "^Ifc[A-Za-z]+ .*$"
+
+
+def snapshot(path: str, filename: str, cfg: Settings) -> str:
+    return "\n".join(snapshot_lines(path, filename, cfg)) + "\n"
+
+
+def snapshot_lines(path: str, filename: str, cfg: Settings) -> Iterator[str]:
+    with IFC_LOCK:
+        model = parse_ifc(path, filename, cfg.include_openings)
+        memo: dict[int, str] = {}
+        ifc = model._ifc_file
+        fingerprints = {
+            gid: representation_fingerprint(ifc.by_id(el._ifc_entity_id), memo)
+            for gid, el in model.elements.items()
+            if el.has_representation and el._ifc_entity_id is not None
+        }
+
+    prop_filter = (
+        PropertyFilter()
+        if cfg.strict
+        else PropertyFilter(ignore_patterns=tuple(cfg.ignore_properties))
+    )
+
+    classes = Counter(el.ifc_class for el in model.elements.values())
+    yield f"# {filename}  {model.ifc_schema}  {len(model.elements)} elements"
+    yield ""
+    yield "## Storeys"
+    for name, elevation in sorted(model.storeys.items(), key=lambda kv: (kv[1], kv[0])):
+        yield f"  {name}  {elevation:+.3f} m"
+    yield ""
+    yield "## Classes"
+    for cls, n in sorted(classes.items()):
+        yield f"  {cls}  {n}"
+    yield ""
+    yield "## Elements"
+
+    for el in sorted(model.elements.values(), key=_sort_key):
+        yield _header(el)
+        if el.tag:
+            yield f"    tag: {el.tag}"
+        if el.type_name:
+            yield f"    type: {el.type_name}"
+        x, y, z = (float(v) for v in el.world_placement[:3, 3])
+        yield f"    placement: {x:.3f}, {y:.3f}, {z:.3f}"
+        fp = fingerprints.get(el.global_id)
+        yield f"    geometry: {fp[:12] if fp else 'none'}"
+        for prop in sorted(el.properties, key=lambda p: (p.source, p.pset_name, p.property_name)):
+            if prop_filter.is_ignored(prop.pset_name, prop.property_name):
+                continue
+            prefix = "type " if prop.source == "type" else ""
+            yield (
+                f"    {prefix}{prop.pset_name}.{prop.property_name} = "
+                f"{_one_line(format_value(prop.value))}"
+            )
+
+
+def _sort_key(el: ParsedElement) -> tuple:
+    return (el.ifc_class, el.storey or "", el.name or "", el.tag or "", el.global_id)
+
+
+def _header(el: ParsedElement) -> str:
+    name = _one_line(el.name or "(unnamed)")
+    storey = f"  @ {_one_line(el.storey)}" if el.storey else ""
+    return f"{el.ifc_class} {el.global_id}  {name}{storey}"
+
+
+def _one_line(text: str) -> str:
+    return text.replace("\r", " ").replace("\n", " ")