python-cad-tools 0.1.0rc1__py3-none-any.whl

python_cad_tools/build.py

@@ -0,0 +1,270 @@
+"""Typed build, validation, and safe-clean project operations."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ._locking import project_lock
+from ._project_loader import (
+    LoadedProject,
+    project_execution,
+    reject_nested_project_execution,
+)
+from ._project_loader import (
+    load_project_model_guarded as load_project_model,
+)
+from ._transaction import promote_directory, recover_promotion, staging_directory
+from .artifacts import ArtifactRecord, artifact_records, validate_export_tree, verify_output_root
+from .determinism import semantic_hash, sha256_file, write_json
+from .exceptions import BuildExportError, ModelValidationError, ProjectConfigError, UnsafePathError
+from .exporters import GlbExporter, IfcExporter, QuantityExporter, StepExporter
+from .exporters.drawings import DrawingExporter
+from .manifests import build_manifest_document, design_manifest, write_preinventory_manifests
+from .project_config import FORMAT_ORDER, load_project_config, output_path, resolve_project_root
+from .validation import ValidationIssue, fatal_issues
+
+type FormatName = Literal["step", "ifc", "glb", "drawings", "quantities"]
+
+
+@dataclass(frozen=True, slots=True)
+class BuildOptions:
+    project_root: Path
+    formats: tuple[FormatName, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationOptions:
+    project_root: Path
+    formats: tuple[FormatName, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BuildResult:
+    project_root: Path
+    output_root: Path
+    formats: tuple[FormatName, ...]
+    artifacts: tuple[ArtifactRecord, ...]
+    build_manifest: Path
+    source_set_hash: str
+    design_semantic_hash: str
+    artifact_set_hash: str
+    stable_artifact_set_hash: str
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationReport:
+    project_root: Path
+    formats: tuple[FormatName, ...]
+    issues: tuple[ValidationIssue, ...]
+    source_set_hash: str
+    design_semantic_hash: str
+    annotation_provider_id: str | None
+
+    @property
+    def ok(self) -> bool:
+        return not fatal_issues(self.issues)
+
+
+EXPORTERS: dict[str, type[Any]] = {
+    "step": StepExporter,
+    "ifc": IfcExporter,
+    "glb": GlbExporter,
+    "drawings": DrawingExporter,
+    "quantities": QuantityExporter,
+}
+
+
+def build_project(options: BuildOptions) -> BuildResult:
+    if not isinstance(options, BuildOptions):
+        raise TypeError("build_project expects BuildOptions")
+    requested = _validate_requested_formats(options.formats)
+    root = resolve_project_root(options.project_root)
+    with project_execution():
+        with project_lock(root):
+            config = load_project_config(root)
+            formats = config.default_formats if requested is None else requested
+            destination = output_path(root, config)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            recover_promotion(destination, lambda candidate: verify_output_root(candidate))
+            loaded = load_project_model(root, include_drawings="drawings" in formats)
+            _raise_fatal_model_issues(loaded.issues)
+            source_inputs, source_set_hash = _source_records(loaded)
+            staging = staging_directory(destination)
+            try:
+                staging.mkdir()
+                if (destination / ".gitkeep").is_file() and not (destination / ".gitkeep").is_symlink():
+                    (staging / ".gitkeep").touch()
+                for name in formats:
+                    try:
+                        if name == "drawings":
+                            DrawingExporter().export(
+                                loaded.model,
+                                staging,
+                                loaded.drawing_sheets,
+                                loaded.annotations,
+                            )
+                        else:
+                            EXPORTERS[name]().export(loaded.model, staging)
+                    except (BuildExportError, ImportError):
+                        raise
+                    except Exception as error:
+                        raise BuildExportError(f"{name} exporter failed: {error}") from error
+                _, _, design = write_preinventory_manifests(loaded.model, staging, formats)
+                validate_export_tree(staging, formats, loaded.model.artifact_stem)
+                records = artifact_records(staging)
+                artifact_set_hash = semantic_hash([_record_dict(record) for record in records])
+                stable_artifact_set_hash = semantic_hash(
+                    [_record_dict(record) for record in records if not record.volatile]
+                )
+                manifest = build_manifest_document(
+                    project_name=root.name,
+                    source_revision=loaded.source_revision,
+                    source_dirty=loaded.source_dirty,
+                    source_inputs=source_inputs,
+                    source_set_hash=source_set_hash,
+                    config_schema_version=loaded.project_config.schema_version,
+                    selected_formats=formats,
+                    annotation_import=loaded.project_config.drawing_annotations_target,
+                    annotation_provider_id=(
+                        None if loaded.annotations is None else loaded.annotations.provider_id
+                    ),
+                    artifacts=records,
+                    design_semantic_hash=design["semantic_hash"],
+                    artifact_set_hash=artifact_set_hash,
+                    stable_artifact_set_hash=stable_artifact_set_hash,
+                    issues=loaded.issues,
+                )
+                write_json(staging / "manifests/build-manifest.json", manifest)
+                verify_output_root(staging, root)
+                promote_directory(staging, destination, lambda candidate: verify_output_root(candidate, root))
+            finally:
+                if staging.exists():
+                    shutil.rmtree(staging)
+            verified = verify_output_root(destination, root)
+            return BuildResult(
+                project_root=root,
+                output_root=destination,
+                formats=formats,
+                artifacts=verified.artifacts,
+                build_manifest=verified.build_manifest,
+                source_set_hash=source_set_hash,
+                design_semantic_hash=design["semantic_hash"],
+                artifact_set_hash=verified.artifact_set_hash,
+                stable_artifact_set_hash=verified.stable_artifact_set_hash,
+            )
+
+
+def validate_project(options: ValidationOptions) -> ValidationReport:
+    if not isinstance(options, ValidationOptions):
+        raise TypeError("validate_project expects ValidationOptions")
+    requested = _validate_requested_formats(options.formats)
+    root = resolve_project_root(options.project_root)
+    with project_execution():
+        with project_lock(root):
+            config = load_project_config(root)
+            formats = config.default_formats if requested is None else requested
+            loaded = load_project_model(root, include_drawings="drawings" in formats)
+            _, source_set_hash = _source_records(loaded)
+            return ValidationReport(
+                project_root=loaded.project_root,
+                formats=formats,
+                issues=loaded.issues,
+                source_set_hash=source_set_hash,
+                design_semantic_hash=design_manifest(loaded.model)["semantic_hash"],
+                annotation_provider_id=(
+                    None if loaded.annotations is None else loaded.annotations.provider_id
+                ),
+            )
+
+
+def clean_project(project_root: Path) -> None:
+    reject_nested_project_execution()
+    root = resolve_project_root(project_root)
+    config = load_project_config(root)
+    generated = output_path(root, config)
+    with project_lock(root):
+        recover_promotion(generated, lambda candidate: verify_output_root(candidate))
+        _validate_clean_target(root, generated)
+        if not generated.exists():
+            return
+        anchor = generated / ".gitkeep"
+        keep_anchor = anchor.is_file() and not anchor.is_symlink()
+        for path in generated.rglob("*"):
+            if path.is_symlink():
+                raise UnsafePathError(f"Refusing to clean an output tree containing a symlink: {path}")
+        if keep_anchor:
+            for child in generated.iterdir():
+                if child == anchor:
+                    continue
+                if child.is_dir():
+                    shutil.rmtree(child)
+                else:
+                    child.unlink()
+        else:
+            shutil.rmtree(generated)
+
+
+def _validate_requested_formats(requested: tuple[FormatName, ...] | None) -> tuple[FormatName, ...] | None:
+    if requested is None:
+        return None
+    if not isinstance(requested, tuple) or not requested:
+        raise ProjectConfigError("formats must be None or a nonempty tuple")
+    if not all(isinstance(item, str) for item in requested):
+        raise ProjectConfigError("formats must contain only format names")
+    if len(requested) != len(set(requested)):
+        raise ProjectConfigError("formats contains a duplicate")
+    unknown = sorted(set(requested) - set(FORMAT_ORDER))
+    if unknown:
+        raise ProjectConfigError(f"Unsupported format(s): {', '.join(unknown)}")
+    selected = set(requested)
+    return tuple(name for name in FORMAT_ORDER if name in selected)
+
+
+def _raise_fatal_model_issues(issues: tuple[ValidationIssue, ...]) -> None:
+    fatals = fatal_issues(issues)
+    if fatals:
+        details = "; ".join(f"{issue.code}: {issue.message} ({issue.element_id or 'model'})" for issue in fatals)
+        raise ModelValidationError(f"Model validation failed: {details}")
+
+
+def _source_records(loaded: LoadedProject) -> tuple[list[dict[str, Any]], str]:
+    records = []
+    for relative in sorted(loaded.project_config.source_inputs):
+        path = loaded.project_root / relative
+        records.append({"path": relative, "size": path.stat().st_size, "sha256": sha256_file(path)})
+    return records, semantic_hash(records)
+
+
+def _record_dict(record: ArtifactRecord) -> dict[str, Any]:
+    return {
+        "path": record.path,
+        "size": record.size,
+        "sha256": record.sha256,
+        "media_type": record.media_type,
+        "producer": record.producer,
+        "schema_id": record.schema_id,
+        "schema_version": record.schema_version,
+        "volatile": record.volatile,
+    }
+
+
+def _validate_clean_target(root: Path, generated: Path) -> None:
+    if generated.is_symlink() or not generated.resolve(strict=False).is_relative_to(root):
+        raise UnsafePathError(f"Refusing to clean unsafe output directory: {generated}")
+    if generated.exists() and not generated.is_dir():
+        raise UnsafePathError(f"Configured output path is not a directory: {generated}")
+
+
+__all__ = [
+    "BuildOptions",
+    "BuildResult",
+    "FormatName",
+    "ValidationOptions",
+    "ValidationReport",
+    "build_project",
+    "clean_project",
+    "validate_project",
+]

python_cad_tools/cli.py

@@ -0,0 +1,212 @@
+"""Installed ``python-cad`` command for project operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .exceptions import (
+    ArtifactIntegrityError,
+    BuildExportError,
+    BuildLockedError,
+    ModelValidationError,
+    ProjectConfigError,
+    SiteError,
+    UnsafePathError,
+)
+from .project_config import FORMAT_ORDER, resolve_project_root
+
+
+def parser() -> argparse.ArgumentParser:
+    value = argparse.ArgumentParser(
+        prog="python-cad",
+        description="Validate, build, verify, and clean Python CAD Tools projects.",
+    )
+    value.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    value.add_argument("--verbose", action="store_true", help="Include a traceback for unexpected failures.")
+    commands = value.add_subparsers(dest="command", required=True)
+    for name in ("validate", "build"):
+        operation = commands.add_parser(name, help=f"{name.title()} the configured project.")
+        _project_root_argument(operation)
+        operation.add_argument(
+            "--format",
+            action="append",
+            choices=FORMAT_ORDER,
+            dest="formats",
+            help="Select one output format; repeat for several.",
+        )
+    verify = commands.add_parser("verify", help="Verify final bytes, schemas, and parsability.")
+    _project_root_argument(verify)
+    clean = commands.add_parser("clean", help="Safely remove the configured generated output.")
+    _project_root_argument(clean)
+    init = commands.add_parser("init", help="Create a generic Python CAD project scaffold.")
+    init.add_argument("--destination", type=Path, required=True, help="Destination project directory.")
+    init.add_argument("--force", action="store_true", help="Allow a non-empty destination; existing scaffold files are overwritten.")
+    prepare_site = commands.add_parser("prepare-site", help="Prepare a verified, Node-free viewer site.")
+    _project_root_argument(prepare_site)
+    prepare_site.add_argument("--destination", type=Path, required=True, help="Managed site destination.")
+    prepare_site.add_argument("--base-path", default="/", help="Deployment URL base path; defaults to /.")
+    serve = commands.add_parser("serve", help="Prepare and serve a verified viewer site.")
+    _project_root_argument(serve)
+    serve.add_argument("--host", default="127.0.0.1", help="Bind host; defaults to loopback.")
+    serve.add_argument("--port", type=int, default=8000, help="Bind port; use 0 for an ephemeral port.")
+    serve.add_argument("--build", action="store_true", help="Build the project before serving.")
+    serve.add_argument("--allow-unsafe-bind", action="store_true", help="Explicitly allow a non-loopback bind.")
+    return value
+
+
+def main(argv: list[str] | None = None, project_dir: Path | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        from .artifacts import verify_build_output
+        from .build import BuildOptions, ValidationOptions, build_project, clean_project, validate_project
+        from .site import prepare_site, serve_project
+
+        _configure_logging()
+        if args.command == "init":
+            from ._scaffold import scaffold_project
+
+            result = scaffold_project(args.destination, force=args.force)
+            _print_json(
+                {
+                    "status": "ok",
+                    "operation": "init",
+                    "destination": str(result.destination),
+                    "created_files": list(result.created_files),
+                }
+            )
+            return 0
+        root = resolve_project_root(project_dir if project_dir is not None else args.project_root)
+        if args.command == "serve":
+            serve_result = serve_project(
+                root,
+                host=args.host,
+                port=args.port,
+                build=args.build,
+                allow_unsafe_bind=args.allow_unsafe_bind,
+            )
+            return 130 if serve_result.interrupted else 0
+        if args.command == "prepare-site":
+            site_result = prepare_site(root, args.destination, args.base_path)
+            _print_json(
+                {
+                    "status": "ok",
+                    "operation": "prepare-site",
+                    "destination": str(site_result.destination),
+                    "base_path": site_result.base_path,
+                    "design_build_hash": site_result.design_build_hash,
+                    "file_count": site_result.file_count,
+                }
+            )
+        elif args.command == "clean":
+            clean_project(root)
+            _print_json({"status": "ok", "operation": "clean", "project_root": str(root)})
+        elif args.command == "verify":
+            verification = verify_build_output(root)
+            _print_json(
+                {
+                    "status": "ok",
+                    "operation": "verify",
+                    "artifact_count": len(verification.artifacts),
+                    "stable_artifact_set_hash": verification.stable_artifact_set_hash,
+                }
+            )
+        elif args.command == "validate":
+            formats = None if args.formats is None else tuple(args.formats)
+            report = validate_project(ValidationOptions(root, formats))
+            errors = [issue for issue in report.issues if issue.severity == "error"]
+            if errors:
+                raise ModelValidationError("; ".join(f"{issue.code}: {issue.message}" for issue in errors))
+            _print_json(
+                {
+                    "status": "ok",
+                    "operation": "validate",
+                    "formats": list(report.formats),
+                    "warning_count": len(report.issues),
+                    "design_semantic_hash": report.design_semantic_hash,
+                }
+            )
+        else:
+            formats = None if args.formats is None else tuple(args.formats)
+            build_result = build_project(BuildOptions(root, formats))
+            _print_json(
+                {
+                    "status": "ok",
+                    "operation": "build",
+                    "artifact_count": len(build_result.artifacts),
+                    "output_root": str(build_result.output_root),
+                    "stable_artifact_set_hash": build_result.stable_artifact_set_hash,
+                }
+            )
+        return 0
+    except KeyboardInterrupt:
+        _print_error("interrupted", "Operation interrupted")
+        return 130
+    except BaseException as error:
+        code, name = _error_code(error)
+        _print_error(name, _concise_message(error))
+        if getattr(args, "verbose", False) and code == 1:
+            traceback.print_exc()
+        return code
+
+
+def _project_root_argument(command: argparse.ArgumentParser) -> None:
+    command.add_argument("--project-root", type=Path, default=None, help="Project directory; defaults to the current directory.")
+
+
+def _error_code(error: BaseException) -> tuple[int, str]:
+    if isinstance(error, (ProjectConfigError, argparse.ArgumentError)):
+        return 2, "project_config"
+    if isinstance(error, ModelValidationError):
+        return 3, "model_validation"
+    if isinstance(error, (BuildExportError, ImportError)):
+        return 4, "build_export"
+    if isinstance(error, ArtifactIntegrityError):
+        return 5, "artifact_integrity"
+    if isinstance(error, (UnsafePathError, BuildLockedError)):
+        return 6, "unsafe_or_locked"
+    if isinstance(error, SiteError):
+        return 7, "site"
+    return 1, "internal"
+
+
+def _concise_message(error: BaseException) -> str:
+    message = str(error).strip() or type(error).__name__
+    return " ".join(message.splitlines())
+
+
+def _print_json(value: dict[str, Any]) -> None:
+    print(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False))
+
+
+def _print_error(code: str, message: str) -> None:
+    print(
+        json.dumps(
+            {"error": {"code": code, "message": message}, "status": "error"},
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ),
+        file=sys.stderr,
+    )
+
+
+def _configure_logging() -> None:
+    value = os.environ.get("PYTHON_CAD_LOG_LEVEL", "WARNING").upper()
+    levels = {
+        "CRITICAL": logging.CRITICAL,
+        "ERROR": logging.ERROR,
+        "WARNING": logging.WARNING,
+        "INFO": logging.INFO,
+        "DEBUG": logging.DEBUG,
+    }
+    if value not in levels:
+        raise ProjectConfigError("PYTHON_CAD_LOG_LEVEL must be CRITICAL, ERROR, WARNING, INFO, or DEBUG")
+    logging.getLogger("python_cad_tools").setLevel(levels[value])

python_cad_tools/context.py

@@ -0,0 +1,67 @@
+"""Immutable contexts passed to trusted project entry points."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, BinaryIO, Literal, TextIO, overload
+
+from ._project_state import open_authoritative_source
+
+if TYPE_CHECKING:
+    from .drawings import DrawingSheet
+    from .elements import DesignModel
+
+
+@dataclass(frozen=True, slots=True)
+class BuildContext:
+    project_root: Path
+    config: Any
+    source_revision: str | None
+    source_dirty: bool
+
+    def source_path(self, relative_path: str | Path) -> Path:
+        """Return and record a declared authoritative project file."""
+        stream = open_authoritative_source(self.project_root, relative_path, "rb", None)
+        try:
+            return Path(stream.name)
+        finally:
+            stream.close()
+
+    @overload
+    def open_source(self, relative_path: str | Path, mode: Literal["r"] = "r", *, encoding: str = "utf-8") -> TextIO: ...
+
+    @overload
+    def open_source(self, relative_path: str | Path, mode: Literal["rb"], *, encoding: None = None) -> BinaryIO: ...
+
+    def open_source(
+        self,
+        relative_path: str | Path,
+        mode: Literal["r", "rb"] = "r",
+        *,
+        encoding: str | None = "utf-8",
+    ) -> TextIO | BinaryIO:
+        """Open and record a declared authoritative source in read-only mode."""
+        return open_authoritative_source(self.project_root, relative_path, mode, encoding)
+
+    def read_text(self, relative_path: str | Path, *, encoding: str = "utf-8") -> str:
+        """Read and record a declared authoritative UTF-8 source file."""
+        with self.open_source(relative_path, "r", encoding=encoding) as stream:
+            return stream.read()
+
+    def read_bytes(self, relative_path: str | Path) -> bytes:
+        """Read and record a declared authoritative binary source file."""
+        with self.open_source(relative_path, "rb", encoding=None) as stream:
+            return stream.read()
+
+
+@dataclass(frozen=True, slots=True)
+class DrawingContext:
+    project_root: Path
+    config: Any
+    model: DesignModel
+    sheets: tuple[DrawingSheet, ...]
+    length_unit: Literal["mm"] = "mm"
+
+
+__all__ = ["BuildContext", "DrawingContext"]

python_cad_tools/determinism.py

@@ -0,0 +1,66 @@
+"""Deterministic serialization and hashing helpers for Python CAD Tools."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .exceptions import ProjectConfigError
+
+DEFAULT_BUILD_EPOCH = datetime(1980, 1, 1, tzinfo=UTC)
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    return (
+        json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        )
+        + "\n"
+    ).encode("utf-8")
+
+
+def write_json(path: Path, value: Any) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(canonical_json_bytes(value))
+    return path
+
+
+def sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def semantic_hash(value: Any) -> str:
+    return sha256_bytes(canonical_json_bytes(value))
+
+
+def normalized_build_epoch() -> datetime:
+    """Return the validated reproducible-build epoch for deterministic writers."""
+    raw = os.environ.get("SOURCE_DATE_EPOCH")
+    if raw is None:
+        return DEFAULT_BUILD_EPOCH
+    if not raw.isascii() or not raw.isdigit():
+        raise ProjectConfigError("SOURCE_DATE_EPOCH must be a nonnegative integer Unix timestamp")
+    try:
+        return datetime.fromtimestamp(int(raw), UTC)
+    except (OverflowError, OSError, ValueError) as error:
+        raise ProjectConfigError("SOURCE_DATE_EPOCH is outside the supported timestamp range") from error
+
+
+def normalized_epoch_iso() -> str:
+    return normalized_build_epoch().isoformat().replace("+00:00", "Z")