gitcad-core 0.7.7__py3-none-any.whl

gitcad/_version.py

@@ -0,0 +1 @@
+__version__ = "0.7.6"

gitcad/canonical.py

@@ -0,0 +1,56 @@
+"""The one canonicalization policy for every serialized number (ADR-0004).
+
+Canonical text is load-bearing: identities, content hashes, lockfiles, and
+semantic diffs all assume "semantically equal ⇒ byte-identical". Floats are
+where that promise quietly breaks, so every module that serializes model data
+routes numbers through here. The rules:
+
+1. **Non-finite numbers are rejected.** NaN/Infinity are not geometry; JSON's
+   default ``allow_nan=True`` would emit non-JSON and break hash equality
+   (``nan != nan``).
+2. **Negative zero is normalized to zero.** ``round(-1e-9, 6)`` is ``-0.0``,
+   which serializes as ``"-0.0"`` — float noise crossing zero must never split
+   an identity or a hash.
+3. **All non-bool numbers serialize as floats.** ``{"dx": 1}`` and
+   ``{"dx": 1.0}`` are the same model and must hash identically.
+
+(Reviewed 2026-07-22: all three holes were verified live before this module
+existed — see docs/reviews/2026-07-22-early-architecture-review.md.)
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from gitcad.errors import GitcadError
+
+
+def canon_number(v: float) -> float:
+    """Apply rules 1-3 to a single number."""
+    if not math.isfinite(v):
+        raise GitcadError(f"non-finite number is not serializable: {v!r}")
+    return float(v) + 0.0  # int -> float; -0.0 + 0.0 == 0.0
+
+
+def canonicalize(obj: Any) -> Any:
+    """Recursively canonicalize every number in a JSON-able structure.
+    Bools are preserved (bool is an int subclass — check it first)."""
+    if isinstance(obj, bool) or obj is None or isinstance(obj, str):
+        return obj
+    if isinstance(obj, (int, float)):
+        return canon_number(obj)
+    if isinstance(obj, dict):
+        return {k: canonicalize(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [canonicalize(v) for v in obj]
+    raise GitcadError(f"not canonically serializable: {type(obj).__name__}")
+
+
+def canonical_json(obj: Any, *, indent: int | None = None) -> str:
+    """Canonical JSON text: numbers per the rules above, sorted keys, no NaN
+    escape hatch. THE serializer for model/board/part/lock text."""
+    return json.dumps(canonicalize(obj), indent=indent, sort_keys=True,
+                      allow_nan=False,
+                      separators=(",", ":") if indent is None else None)

gitcad/errors.py

@@ -0,0 +1,84 @@
+"""Structured errors.
+
+Errors here are not just for humans — a kernel/validation failure carries enough
+structure to become a *bug-repro payload* (see :mod:`gitcad.report`). Every
+failure exposes a stable ``fingerprint_key`` so 10,000 users hitting one kernel
+bug produce one deduplicated issue, not 10,000.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class GitcadError(Exception):
+    """Base class for all gitcad errors."""
+
+
+@dataclass
+class FailureSignature:
+    """The deduplication key for a failure.
+
+    Deliberately excludes user coordinates and model contents — it is derived
+    only from *what went wrong* (the operation and the kernel's own diagnostic),
+    so it is safe to transmit and stable across unrelated models.
+    """
+
+    op: str
+    """The intent-level operation that failed, e.g. ``"fillet"``."""
+
+    diagnostic: str
+    """The kernel/validator's own message class, e.g. ``"BRepCheck:BadOrientation"``."""
+
+    kernel: str = "unknown"
+    """Backend + version, e.g. ``"occt-7.8.1"``."""
+
+    def key(self) -> str:
+        return f"{self.kernel}|{self.op}|{self.diagnostic}"
+
+
+class KernelError(GitcadError):
+    """A geometry-kernel operation failed.
+
+    Carries a :class:`FailureSignature` so the failure can be fingerprinted and
+    the model auto-reduced to a minimal, synthetic repro before anything leaves
+    the user's machine.
+    """
+
+    def __init__(self, message: str, signature: FailureSignature) -> None:
+        super().__init__(message)
+        self.signature = signature
+
+
+class GeometryInvalidError(KernelError):
+    """A produced shape violated a geometric invariant (e.g. not watertight)."""
+
+
+class IdentityError(GitcadError):
+    """A stable-identity operation failed (e.g. dangling entity reference)."""
+
+    def __init__(self, message: str, *, entity: str | None = None) -> None:
+        super().__init__(message)
+        self.entity = entity
+
+
+@dataclass
+class ValidationReport:
+    """Result of validating a shape or document. Machine-readable by design so
+    an agent can act on it instead of parsing prose."""
+
+    ok: bool
+    checks: dict[str, Any] = field(default_factory=dict)
+    violations: list[str] = field(default_factory=list)
+
+    def raise_if_invalid(self, op: str, kernel: str = "unknown") -> None:
+        if not self.ok:
+            # Fingerprints must carry only the closed-vocabulary violation
+            # CODES, never the per-instance detail after the first colon —
+            # detail embeds designators/dimensions (unsafe to transmit, per
+            # the FailureSignature contract) and varies per model (destroying
+            # dedup). Reviewed 2026-07-22. Violation format: "code:detail".
+            codes = sorted({v.split(":", 1)[0] for v in self.violations})
+            sig = FailureSignature(op=op, diagnostic=";".join(codes), kernel=kernel)
+            raise GeometryInvalidError(f"{op} produced invalid geometry: {self.violations}", sig)

gitcad/expr.py

@@ -0,0 +1,148 @@
+"""Safe arithmetic expressions — the engine behind named parameters.
+
+A tiny, auditable evaluator over Python's ast: numbers, + - * / // % **,
+unary +/-, parentheses, parameter names, and a whitelist of math
+functions. No attribute access, no subscripts, no comprehensions, no
+eval — an expression can compute a dimension and nothing else.
+
+Convention (spreadsheet-style, used across gitcad): a string value
+beginning with ``=`` is an expression; anything else is a literal.
+"""
+
+from __future__ import annotations
+
+import ast
+import math
+from typing import Any, Mapping
+
+from gitcad.errors import GitcadError
+
+
+class ExprError(GitcadError):
+    pass
+
+
+class UndefinedNameError(ExprError):
+    def __init__(self, name: str) -> None:
+        super().__init__(f"undefined name {name!r} in expression")
+        self.name = name
+
+
+_FUNCS: dict[str, Any] = {
+    "sin": lambda x: math.sin(math.radians(x)),
+    "cos": lambda x: math.cos(math.radians(x)),
+    "tan": lambda x: math.tan(math.radians(x)),
+    "asin": lambda x: math.degrees(math.asin(x)),
+    "acos": lambda x: math.degrees(math.acos(x)),
+    "atan": lambda x: math.degrees(math.atan(x)),
+    "atan2": lambda y, x: math.degrees(math.atan2(y, x)),
+    "sqrt": math.sqrt,
+    "abs": abs,
+    "min": min,
+    "max": max,
+    "floor": math.floor,
+    "ceil": math.ceil,
+    "round": round,
+}
+_CONSTS = {"pi": math.pi}
+
+_BINOPS = {
+    ast.Add: lambda a, b: a + b,
+    ast.Sub: lambda a, b: a - b,
+    ast.Mult: lambda a, b: a * b,
+    ast.Div: lambda a, b: a / b,
+    ast.FloorDiv: lambda a, b: a // b,
+    ast.Mod: lambda a, b: a % b,
+    ast.Pow: lambda a, b: a ** b,
+}
+
+
+def eval_expr(expr: str, env: Mapping[str, float]) -> float:
+    """Evaluate ``expr`` with parameter values from ``env``. Angles for
+    trig are DEGREES (the CAD convention). Raises UndefinedNameError for
+    unknown names, ExprError for anything outside the whitelist."""
+    try:
+        tree = ast.parse(expr, mode="eval")
+    except SyntaxError as e:
+        raise ExprError(f"bad expression {expr!r}: {e.msg}") from None
+
+    def ev(node: ast.AST) -> float:
+        if isinstance(node, ast.Expression):
+            return ev(node.body)
+        if isinstance(node, ast.Constant):
+            if isinstance(node.value, (int, float)) and not isinstance(node.value, bool):
+                return float(node.value)
+            raise ExprError(f"non-numeric constant {node.value!r} in {expr!r}")
+        if isinstance(node, ast.Name):
+            if node.id in env:
+                return float(env[node.id])
+            if node.id in _CONSTS:
+                return _CONSTS[node.id]
+            raise UndefinedNameError(node.id)
+        if isinstance(node, ast.BinOp) and type(node.op) in _BINOPS:
+            return _BINOPS[type(node.op)](ev(node.left), ev(node.right))
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.UAdd, ast.USub)):
+            v = ev(node.operand)
+            return -v if isinstance(node.op, ast.USub) else v
+        if isinstance(node, ast.Call):
+            if (isinstance(node.func, ast.Name) and node.func.id in _FUNCS
+                    and not node.keywords):
+                return float(_FUNCS[node.func.id](*[ev(a) for a in node.args]))
+            raise ExprError(f"function not allowed in {expr!r}")
+        raise ExprError(f"construct {type(node).__name__} not allowed in {expr!r}")
+
+    return ev(tree)
+
+
+def is_expression(value: Any) -> bool:
+    """The gitcad convention: strings starting with '=' are expressions."""
+    return isinstance(value, str) and value.startswith("=")
+
+
+def resolve_value(value: Any, env: Mapping[str, float]) -> Any:
+    """Resolve one value: '=expr' strings evaluate; lists/dicts recurse;
+    everything else passes through untouched (enums, paths, ids)."""
+    if is_expression(value):
+        return eval_expr(value[1:], env)
+    if isinstance(value, list):
+        return [resolve_value(v, env) for v in value]
+    if isinstance(value, tuple):
+        return tuple(resolve_value(v, env) for v in value)
+    if isinstance(value, dict):
+        return {k: resolve_value(v, env) for k, v in value.items()}
+    return value
+
+
+def resolve_table(parameters: Mapping[str, Any]) -> dict[str, float]:
+    """Resolve a parameter table where values may reference each other
+    ('=W*2'). Deterministic, cycle-detecting, fail-loud."""
+    env: dict[str, float] = {}
+    pending = dict(parameters)
+    progress = True
+    while pending and progress:
+        progress = False
+        for name in sorted(pending):
+            v = pending[name]
+            if not is_expression(v):
+                try:
+                    env[name] = float(v)
+                except (TypeError, ValueError):
+                    raise ExprError(
+                        f"parameter {name!r}: value {v!r} is neither a number "
+                        f"nor an '=' expression") from None
+                del pending[name]
+                progress = True
+                continue
+            try:
+                env[name] = eval_expr(v[1:], env)
+            except UndefinedNameError as e:
+                if e.name not in pending:
+                    raise ExprError(
+                        f"parameter {name!r} references undefined {e.name!r}") from None
+                continue                      # dependency not resolved yet
+            del pending[name]
+            progress = True
+    if pending:
+        raise ExprError(
+            f"parameter cycle: {sorted(pending)} reference each other")
+    return env

gitcad/identity.py

@@ -0,0 +1,134 @@
+"""Stable entity identity — the topological-naming fix.
+
+The problem: a downstream feature references "face 7". An upstream edit adds a
+feature, the kernel renumbers faces, and "face 7" silently becomes a different
+face. Every reference downstream corrupts. This is FreeCAD's most notorious
+weakness and it is *fatal* to a git workflow, where merges and rebases reorder
+operations constantly (ADR-0003).
+
+The fix: an entity's identity is derived from **how it was constructed** (its
+lineage) plus a **geometric fingerprint** — never from an ordinal index. Two
+rebuilds of the same construction yield the same ID; an unrelated edit upstream
+does not perturb the IDs of entities it didn't touch.
+
+This module is pure Python and has no kernel dependency, so identity logic is
+fully unit-testable without OCCT.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from gitcad.canonical import canonical_json
+from gitcad.errors import GitcadError
+
+
+@dataclass(frozen=True)
+class EntityId:
+    """A durable reference to a topological entity (face/edge/vertex)."""
+
+    value: str
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+def _round_geo(descriptor: dict[str, Any], ndigits: int) -> dict[str, Any]:
+    """Round geometric quantities so floating-point noise doesn't split an
+    identity. ``+ 0.0`` normalizes the ``-0.0`` that rounding a tiny negative
+    produces — without it, noise crossing zero splits identities (reviewed
+    2026-07-22). Non-numeric fields pass through unchanged."""
+    def r(x: Any) -> Any:
+        return round(x, ndigits) + 0.0 if isinstance(x, float) else x
+
+    out: dict[str, Any] = {}
+    for k, v in descriptor.items():
+        if isinstance(v, (list, tuple)):
+            out[k] = [r(x) for x in v]
+        else:
+            out[k] = r(v)
+    return out
+
+
+class IdentityService:
+    """Default identity backend: lineage + rounded geometric fingerprint hash.
+
+    ``assign`` is deterministic and collision-resistant across unrelated
+    constructions. ``resolve`` re-binds a stored ID after a rebuild by scoring
+    candidate entities against the fingerprint embedded in the ID.
+    """
+
+    def __init__(self, *, geo_tolerance_digits: int = 6, id_length: int = 16) -> None:
+        self._digits = geo_tolerance_digits
+        self._id_length = id_length
+        # Maps an assigned id -> the fingerprint payload it was minted from, so
+        # resolve() can re-match without re-deriving lineage.
+        self._registry: dict[str, dict[str, Any]] = {}
+
+    def assign(self, descriptor: dict[str, Any], lineage: tuple[str, ...]) -> str:
+        """Mint a stable id for an entity.
+
+        ``descriptor``: the kernel's order-independent semantic description of
+        the entity (surface type, rounded area, adjacency roles, ...).
+        ``lineage``: the ids of the features that created it (creation history).
+        """
+        payload = {
+            "lineage": list(lineage),
+            "geo": _round_geo(descriptor, self._digits),
+        }
+        digest = hashlib.blake2b(canonical_json(payload).encode(), digest_size=self._id_length).hexdigest()
+        entity_id = f"e_{digest}"
+        self._registry[entity_id] = payload
+        return entity_id
+
+    # -- persistence (ADR-0003: stored ids must resolve in future processes) --
+
+    SCHEMA = "gitcad/identity@1"
+
+    def dumps(self) -> str:
+        """Canonical text of the registry — commit it alongside the model
+        (like a lockfile) so entity ids stored in document text can re-bind
+        after a rebuild in another process."""
+        return canonical_json({"schema": self.SCHEMA, "registry": self._registry}, indent=2) + "\n"
+
+    @classmethod
+    def loads(cls, text: str, **kwargs: Any) -> "IdentityService":
+        doc = json.loads(text)
+        if doc.get("schema") != cls.SCHEMA:
+            raise GitcadError(f"unsupported identity schema {doc.get('schema')!r}")
+        svc = cls(**kwargs)
+        svc._registry = dict(doc["registry"])
+        return svc
+
+    def resolve(self, entity_id: str, candidates: list[dict[str, Any]]) -> dict[str, Any] | None:
+        """Re-bind ``entity_id`` to the best current candidate after a rebuild.
+
+        Returns the winning candidate descriptor, or ``None`` if nothing matches
+        well enough (the entity was genuinely removed). Scoring is a simple
+        geometric-similarity vote; a real backend would weight adjacency too.
+        """
+        payload = self._registry.get(entity_id)
+        if payload is None:
+            return None
+        target = payload["geo"]
+        best: tuple[float, dict[str, Any]] | None = None
+        for cand in candidates:
+            score = _similarity(target, _round_geo(cand, self._digits))
+            if best is None or score > best[0]:
+                best = (score, cand)
+        if best is None or best[0] < 0.5:
+            return None
+        return best[1]
+
+
+def _similarity(a: dict[str, Any], b: dict[str, Any]) -> float:
+    """Fraction of shared keys whose values match. Deliberately simple and
+    explainable — identity heuristics should be auditable, not magical."""
+    keys = set(a) | set(b)
+    if not keys:
+        return 0.0
+    matches = sum(1 for k in keys if a.get(k) == b.get(k))
+    return matches / len(keys)

gitcad/importers/report.py

@@ -0,0 +1,31 @@
+"""The import honesty contract: every importer reports what happened."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ImportReport:
+    """What an import actually did — machine-readable, never silent.
+
+    ``imported`` counts what came through; ``warnings`` are approximations the
+    user should verify (e.g. "outline approximated by bounding box");
+    ``dropped`` is data that did NOT survive the import. An import with drops
+    still succeeds — refusing entirely helps nobody — but the caller (and the
+    agent driving it) can see exactly what to check.
+    """
+
+    source: str
+    format: str
+    imported: dict[str, int] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    dropped: list[str] = field(default_factory=list)
+
+    def count(self, kind: str, n: int = 1) -> None:
+        self.imported[kind] = self.imported.get(kind, 0) + n
+
+    def to_dict(self) -> dict:
+        return {"source": self.source, "format": self.format,
+                "imported": dict(sorted(self.imported.items())),
+                "warnings": self.warnings, "dropped": self.dropped}

gitcad/part/__init__.py

@@ -0,0 +1,29 @@
+"""The Part standard — gitcad's cross-domain interchange contract (ADR-0008/9).
+
+One unit across all domains: a Part is a manifest (domain-neutral) + a body
+(domain-specific) + an interface (domain-neutral). An Assembly is a Part whose
+body is composition. Versioning is interface-semver with a lockfile.
+
+This package is pure Python, kernel-free, and CODEOWNERS-protected: it is the
+most change-resistant surface gitcad owns.
+"""
+
+from gitcad.part.assembly import Assembly, Instance, Mate
+from gitcad.part.bought import assembly_bom, bought_part, is_bought
+from gitcad.part.exploded import ExplodedView, auto_explode
+from gitcad.part.matesolve import MateSolveReport, mate_solve
+from gitcad.part.interference import check_interference
+from gitcad.part.interface import Frame, Interface, Port, check_release, classify_change
+from gitcad.part.lockfile import Lockfile, Workspace, resolve
+from gitcad.part.manifest import PartManifest, new_part_id
+from gitcad.part.semver import Version, satisfies
+
+__all__ = [
+    "PartManifest", "new_part_id",
+    "Interface", "Frame", "Port", "classify_change", "check_release",
+    "Assembly", "Instance", "Mate", "check_interference",
+    "bought_part", "is_bought", "assembly_bom",
+    "ExplodedView", "auto_explode", "MateSolveReport", "mate_solve",
+    "Lockfile", "Workspace", "resolve",
+    "Version", "satisfies",
+]