macrostates-cli 0.3.1__py3-none-any.whl

macrostates/__init__.py

@@ -0,0 +1,23 @@
+"""The public API. Imports perform no network or project-local file access."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._models import Diagnostic, MacrostatesError, Report
+from ._project import Project
+from ._sources import GitHubSource, SourceProvider
+
+__all__ = ["Diagnostic", "GitHubSource", "MacrostatesError", "Project", "Report", "SourceProvider"]
+
+
+def __getattr__(name: str) -> str:
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    # Read distribution metadata only when a caller explicitly requests a version.
+    try:
+        return version("macrostates-cli")
+    except PackageNotFoundError:
+        return "0+uninstalled"
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals(), "__version__"])

macrostates/__main__.py

@@ -0,0 +1,4 @@
+from ._cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

macrostates/_build_version.py

@@ -0,0 +1,56 @@
+"""Setuptools version source, evaluated only during a distribution build."""
+
+import re
+from collections.abc import Hashable
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class DeclarationLoader(yaml.BaseLoader):
+    """Build isolation cannot import the application; keep this reader standalone."""
+
+    def construct_mapping(self, node: Any, deep: bool = False) -> dict[Hashable, Any]:
+        result: dict[Hashable, Any] = {}
+        for key_node, value_node in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if not isinstance(key, str) or key in result:
+                raise ValueError("Invalid or duplicate build declaration key")
+            result[key] = self.construct_object(value_node, deep=deep)
+        return result
+
+
+def numeric_version(value: Any) -> tuple[int, int, int]:
+    if not isinstance(value, str) or not re.fullmatch(
+        r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)", value
+    ):
+        raise ValueError("Build version must be MAJOR.MINOR.REVISION")
+    major, minor, revision = value.split(".")
+    return int(major), int(minor), int(revision)
+
+
+def release_version() -> str:
+    declaration = Path(__file__).parents[2] / ".macrostates/implementation/release.yaml"
+    if declaration.is_symlink():
+        raise ValueError("Build declaration must not be a symbolic link")
+    data = yaml.load(declaration.read_text(encoding="utf-8"), Loader=DeclarationLoader)
+    if not isinstance(data, dict):
+        raise ValueError("Build declaration must be a mapping")
+    selected = data.get("version")
+    current = numeric_version(selected)
+    baseline = data.get("specification")
+    if not isinstance(baseline, str) or not baseline.startswith("spec-"):
+        raise ValueError("Build declaration needs specification: spec-MAJOR.MINOR.REVISION")
+    if current[:2] != numeric_version(baseline.removeprefix("spec-"))[:2]:
+        raise ValueError("Build declaration Major.Minor is not aligned")
+    stamp = data.get("release_date")
+    if not isinstance(stamp, str) or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", stamp):
+        raise ValueError("Build declaration needs release_date: YYYY-MM-DD")
+    date.fromisoformat(stamp)
+    assert isinstance(selected, str)
+    return selected
+
+
+VERSION = release_version()

macrostates/_cli.py

@@ -0,0 +1,158 @@
+"""Thin argparse interface over the public project API."""
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Sequence
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from . import Project, Report, __version__
+from ._models import MacrostatesError
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(
+        prog="macrostates", description="Compose, install and check Macrostates specifications."
+    )
+    result.add_argument("--version", action="version", version=f"macrostates {__version__}")
+    result.add_argument(
+        "--project", default=".", help="Project directory (default: current directory)"
+    )
+    result.add_argument("--json", action="store_true", help="Output structured JSON")
+    commands = result.add_subparsers(dest="command", required=True)
+    for command, description in (
+        ("init", "Prepare project specification files"),
+        ("install", "Install selected archive packages"),
+        ("lock", "Verify existing copies against source and record integrity"),
+        ("verify", "Check package integrity offline"),
+        ("lint", "Check specification structure offline"),
+        ("info", "Show composition and package dependencies"),
+        ("check", "Run lint and integrity verification"),
+    ):
+        sub = commands.add_parser(command, help=description)
+        sub.add_argument("--project", default=argparse.SUPPRESS)
+        sub.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+        if command == "init":
+            sub.add_argument("--name", help="Project name when selecting packages")
+            sub.add_argument(
+                "--package",
+                action="append",
+                default=[],
+                metavar="NAME@VERSION",
+                help="Explicit package selection, repeatable",
+            )
+            sub.add_argument(
+                "--from",
+                dest="manifest",
+                type=Path,
+                help="Copy a supplied composition, preserving extension fields",
+            )
+            sub.add_argument("--layout", choices=["modern", "legacy"], default="modern")
+        elif command == "install":
+            sub.add_argument(
+                "--locked", action="store_true", help="Require existing, unchanged lock selections"
+            )
+        elif command == "check":
+            sub.add_argument(
+                "--staged", action="store_true", help="Check the Git index instead of working files"
+            )
+    return result
+
+
+def display(payload: dict[str, Any], *, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return
+    if "diagnostics" in payload:
+        for diagnostic in payload["diagnostics"]:
+            path = f" ({diagnostic['path']})" if diagnostic["path"] else ""
+            print(f"{diagnostic['severity']}: [{diagnostic['code']}] {diagnostic['message']}{path}")
+        print("Checks passed." if payload["ok"] else "Checks failed.")
+    elif "packages" in payload:
+        print(
+            f"Project: {payload['project']}\nSpecifications: {payload['specs']}\nFormat: {payload['schema_version']}"
+        )
+        for package in payload["packages"]:
+            source = package["source"]
+            print(
+                f"  {package['name']} {package['version']} — {package['path']} ({source.get('type', 'unspecified')})"
+            )
+            if source.get("repository"):
+                print(f"    {source['repository']} @ {source['tag']}")
+            for dependency in package.get("dependencies", []):
+                print(
+                    f"    requires {dependency['name']} {dependency['constraint']} {dependency['version']}"
+                )
+        print("Reading order: " + " → ".join(payload["reading_order"]))
+        print("Authority (highest first): " + " → ".join(payload["authority_order"]))
+        for scope in payload.get("directory_specifications", []):
+            print(f"Directory scope: {scope['scope']} — {scope['entrypoint']}")
+    else:
+        print(payload.get("message", "Done."))
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = parser().parse_args(argv)
+    logging.basicConfig(level=logging.WARNING)
+    try:
+        if arguments.command == "init":
+            packages = []
+            for selection in arguments.package:
+                parts = selection.rsplit("@", 1)
+                if len(parts) != 2:
+                    raise MacrostatesError("Package selections must be NAME@VERSION")
+                packages.append((parts[0], parts[1]))
+            project = Project.initialize(
+                arguments.project,
+                name=arguments.name,
+                packages=packages,
+                manifest=arguments.manifest,
+                layout=arguments.layout,
+            )
+            display(
+                {
+                    "ok": True,
+                    "message": f"Initialized {project.specs.relative_to(project.root).as_posix()}; review authority and reading order, then run macrostates install.",
+                },
+                json_output=arguments.json,
+            )
+            return 0
+        project = Project.open(arguments.project)
+        if arguments.command == "info":
+            display(project.info(), json_output=arguments.json)
+            return 0
+        report: Report
+        match arguments.command:
+            case "install":
+                report = project.install(locked=arguments.locked)
+            case "lock":
+                report = project.lock()
+            case "verify":
+                report = project.verify()
+            case "lint":
+                report = project.lint()
+            case "check":
+                report = project.check(staged=arguments.staged)
+            case _:
+                raise MacrostatesError("Unknown command")
+        display(
+            {"ok": report.ok, "diagnostics": [asdict(item) for item in report.diagnostics]},
+            json_output=arguments.json,
+        )
+        return 0 if report.ok else 1
+    except (MacrostatesError, OSError, UnicodeError) as exc:
+        if arguments.json:
+            print(
+                json.dumps(
+                    {"ok": False, "error": {"code": "operation.invalid", "message": str(exc)}}
+                )
+            )
+        else:
+            print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("Operation interrupted.", file=sys.stderr)
+        return 130

macrostates/_formats/__init__.py

@@ -0,0 +1,42 @@
+"""Explicit format registry. New formats add readers without changing old readers."""
+
+from typing import Any, Protocol
+
+from .._models import Composition, MacrostatesError, Metadata
+from .v0 import LegacyComposition
+from .v1 import CompositionV1, MetadataV1
+
+
+class CompositionReader(Protocol):
+    def read(self, data: dict[str, Any]) -> Composition: ...
+
+
+class MetadataReader(Protocol):
+    def read(self, data: dict[str, Any]) -> Metadata: ...
+
+
+COMPOSITION_READERS: dict[int, CompositionReader] = {0: LegacyComposition(), 1: CompositionV1()}
+METADATA_READERS: dict[int, MetadataReader] = {1: MetadataV1()}
+
+
+def select_version(data: dict[str, Any], default: int) -> int:
+    selected = data.get("schema_version", default)
+    if type(selected) is not int:
+        raise MacrostatesError("schema_version must be an integer")
+    return selected
+
+
+def read_composition(data: dict[str, Any]) -> Composition:
+    selected = select_version(data, 0)
+    reader = COMPOSITION_READERS.get(selected)
+    if reader is None:
+        raise MacrostatesError(f"Unsupported composition schema_version: {selected}")
+    return reader.read(data)
+
+
+def read_metadata(data: dict[str, Any]) -> Metadata:
+    selected = select_version(data, 1)
+    reader = METADATA_READERS.get(selected)
+    if reader is None:
+        raise MacrostatesError(f"Unsupported package metadata schema_version: {selected}")
+    return reader.read(data)

macrostates/_formats/common.py

@@ -0,0 +1,102 @@
+"""Format-1 field primitives; compatibility changes require new adapter modules."""
+
+import re
+from typing import Any
+
+from .._io import mapping, relative_path, string, version
+from .._models import Composition, Dependency, MacrostatesError, Package
+
+
+def dependencies(raw: Any, label: str) -> tuple[Dependency, ...]:
+    if not isinstance(raw, list):
+        raise MacrostatesError(f"{label} must be a list")
+    result = []
+    for item in raw:
+        item = mapping(item, label)
+        name = string(item.get("name"), "dependency name")
+        selected = string(item.get("version"), "dependency version")
+        version(selected)
+        constraint = string(item.get("constraint"), "dependency constraint")
+        if constraint not in ("exact", "compatible", "at_least"):
+            raise MacrostatesError(f"Unsupported dependency constraint: {constraint}")
+        if name in {dependency.name for dependency in result}:
+            raise MacrostatesError(f"Duplicate dependency: {name}")
+        result.append(Dependency(name, selected, constraint))
+    return tuple(result)
+
+
+def composition_fields(data: dict[str, Any], schema: int) -> Composition:
+    project = mapping(data.get("project"), "project")
+    name = string(project.get("name"), "project.name")
+    entrypoint = relative_path(project.get("entrypoint", "main.md"), "project.entrypoint")
+    selected = data.get("packages")
+    if not isinstance(selected, list) or not selected:
+        raise MacrostatesError("packages must be a nonempty list")
+    packages: list[Package] = []
+    for item in selected:
+        item = mapping(item, "package selection")
+        package_name = string(item.get("name"), "package name")
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", package_name):
+            raise MacrostatesError("Package names must be portable identifiers")
+        selected_version = string(item.get("version"), "package version")
+        version(selected_version)
+        path = relative_path(item.get("path"), "package path")
+        entry = relative_path(item.get("entrypoint", "README.md"), "package entrypoint")
+        if package_name in {package.name for package in packages}:
+            raise MacrostatesError(f"Duplicate package name: {package_name}")
+        for package in packages:
+            left, right = package.path.casefold(), path.casefold()
+            if left == right or left.startswith(right + "/") or right.startswith(left + "/"):
+                raise MacrostatesError("Package destinations overlap or collide by case")
+        source = mapping(item.get("source", {}), "source")
+        if any(
+            key.casefold()
+            in {"token", "password", "credentials", "authorization", "access_token", "github_token"}
+            for key in source
+        ):
+            raise MacrostatesError(
+                "Source credentials belong in explicit authentication, not composition metadata"
+            )
+        if source.get("type") not in (None, "local", "github-archive", "git-subtree"):
+            raise MacrostatesError("Unsupported package source type")
+        if source.get("type") in ("github-archive", "git-subtree"):
+            string(source.get("repository"), "source.repository")
+            if source.get("tag") != "v" + selected_version:
+                raise MacrostatesError("source.tag must equal v<selected package version>")
+            if "commit" in source:
+                raise MacrostatesError("Legacy source.commit needs an explicit tag migration")
+            if source["type"] == "git-subtree":
+                string(source.get("branch"), "source.branch")
+                relative_path(source.get("prefix"), "source.prefix")
+        legacy = {
+            key: item[key] for key in ("dependencies", "optional_dependencies") if key in item
+        }
+        packages.append(Package(package_name, selected_version, path, entry, source, legacy))
+
+    def order(key: str) -> tuple[str, ...]:
+        values = data.get(key, [])
+        if not isinstance(values, list):
+            raise MacrostatesError(f"{key} must be a list")
+        references = {
+            reference: package.name
+            for package in packages
+            for reference in (package.name, package.path + "/" + package.entrypoint)
+        }
+        result = []
+        for value in values:
+            if not isinstance(value, str) or value not in references:
+                raise MacrostatesError(f"{key} references an unselected package or entrypoint")
+            if references[value] in result:
+                raise MacrostatesError(f"{key} contains a duplicate package")
+            result.append(references[value])
+        return tuple(result)
+
+    return Composition(
+        schema,
+        name,
+        entrypoint,
+        tuple(packages),
+        order("authority_order"),
+        order("reading_order"),
+        data,
+    )

macrostates/_formats/v0.py

@@ -0,0 +1,11 @@
+"""Reader for existing unversioned Meta compositions. Never writes a migration."""
+
+from typing import Any
+
+from .._models import Composition
+from .common import composition_fields
+
+
+class LegacyComposition:
+    def read(self, data: dict[str, Any]) -> Composition:
+        return composition_fields(data, 0)

macrostates/_formats/v1.py

@@ -0,0 +1,44 @@
+"""Version 1 archive composition and existing package metadata readers."""
+
+import re
+from datetime import datetime
+from typing import Any
+
+from .._io import relative_path, string, version
+from .._models import Composition, MacrostatesError, Metadata
+from .common import composition_fields, dependencies
+
+
+class CompositionV1:
+    def read(self, data: dict[str, Any]) -> Composition:
+        result = composition_fields(data, 1)
+        names = {package.name for package in result.packages}
+        for field in (result.authority_order, result.reading_order):
+            if set(field) != names:
+                raise MacrostatesError(
+                    "Format 1 requires complete authority_order and reading_order"
+                )
+        return result
+
+
+class MetadataV1:
+    def read(self, data: dict[str, Any]) -> Metadata:
+        name = string(data.get("name"), "package.name")
+        selected = string(data.get("version"), "package.version")
+        version(selected)
+        string(data.get("description"), "package.description")
+        stamp = string(data.get("versioned_at"), "package.versioned_at")
+        if not re.fullmatch(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}", stamp):
+            raise MacrostatesError("versioned_at must be YYYY-MM-DD HH:mm")
+        try:
+            datetime.strptime(stamp, "%Y-%m-%d %H:%M")
+        except ValueError as exc:
+            raise MacrostatesError("versioned_at must be YYYY-MM-DD HH:mm") from exc
+        entry = relative_path(data.get("entrypoint"), "package.entrypoint")
+        return Metadata(
+            name,
+            selected,
+            entry,
+            dependencies(data.get("dependencies", []), "dependencies"),
+            dependencies(data.get("optional_dependencies", []), "optional_dependencies"),
+        )

macrostates/_integrity.py

@@ -0,0 +1,144 @@
+"""Content inventory and bounded extraction of GitHub source archives."""
+
+import hashlib
+import io
+import re
+import tarfile
+from pathlib import Path
+from typing import Any
+
+from ._io import canonical, mapping, relative_path
+from ._models import MacrostatesError, Package
+
+MAX_ARCHIVE = 32 * 1024 * 1024
+MAX_EXTRACTED = 128 * 1024 * 1024
+MAX_FILES = 10000
+
+
+def extract_archive(data: bytes, target: Path) -> None:
+    if len(data) > MAX_ARCHIVE:
+        raise MacrostatesError("Compressed archive exceeds 32 MiB")
+    try:
+        archive = tarfile.open(fileobj=io.BytesIO(data), mode="r:*")
+    except tarfile.TarError as exc:
+        raise MacrostatesError("Source is not a valid tar archive") from exc
+    with archive:
+        seen: set[str] = set()
+        root: str | None = None
+        total = 0
+        plan: list[tuple[tarfile.TarInfo, str]] = []
+        for member in archive:
+            if len(seen) >= MAX_FILES:
+                raise MacrostatesError("Archive exceeds 10000 entries")
+            name = relative_path(member.name.rstrip("/"), "archive member")
+            parts = name.split("/")
+            if root is None:
+                root = parts[0]
+            if parts[0] != root:
+                raise MacrostatesError("Archive must have exactly one root directory")
+            folded = name.casefold()
+            if folded in seen:
+                raise MacrostatesError("Archive has duplicate or case-colliding members")
+            seen.add(folded)
+            if not (member.isfile() or member.isdir()):
+                raise MacrostatesError("Archive links and special files are unsupported")
+            if len(parts) == 1:
+                if not member.isdir():
+                    raise MacrostatesError("Archive files must live below its root directory")
+                continue
+            if member.size < 0:
+                raise MacrostatesError("Archive has an invalid member size")
+            total += member.size
+            if total > MAX_EXTRACTED:
+                raise MacrostatesError("Extracted archive exceeds 128 MiB")
+            plan.append((member, "/".join(parts[1:])))
+        if not plan:
+            raise MacrostatesError("Archive contains no package files")
+        try:
+            for member, relative in plan:
+                destination = target / relative
+                if member.isdir():
+                    destination.mkdir(parents=True, exist_ok=True)
+                else:
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    stream = archive.extractfile(member)
+                    if stream is None:
+                        raise MacrostatesError("Archive member could not be read")
+                    with stream, destination.open("xb") as output:
+                        output.write(stream.read(member.size + 1))
+                    if destination.stat().st_size != member.size:
+                        raise MacrostatesError("Truncated archive member")
+                    destination.chmod(0o755 if member.mode & 0o111 else 0o644)
+        except (OSError, tarfile.TarError) as exc:
+            raise MacrostatesError("Archive has conflicting or invalid file entries") from exc
+
+
+def inventory(root: Path) -> dict[str, dict[str, Any]]:
+    if root.is_symlink() or not root.is_dir():
+        raise MacrostatesError("Package directory is missing or is a symbolic link")
+    result: dict[str, dict[str, Any]] = {}
+    seen: set[str] = set()
+    for path in sorted(root.rglob("*")):
+        if path.is_symlink():
+            raise MacrostatesError("Package contains a symbolic link")
+        relative = relative_path(path.relative_to(root).as_posix(), "package file")
+        if relative.casefold() in seen:
+            raise MacrostatesError("Package contains case-colliding paths")
+        seen.add(relative.casefold())
+        if path.is_dir():
+            continue
+        if not path.is_file():
+            raise MacrostatesError("Package contains a special file")
+        digest = hashlib.sha256()
+        with path.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(65536), b""):
+                digest.update(chunk)
+        result[relative] = {
+            "sha256": digest.hexdigest(),
+            "executable": bool(path.stat().st_mode & 0o111),
+        }
+    return result
+
+
+def content_hash(files: dict[str, Any]) -> str:
+    return hashlib.sha256(canonical(files)).hexdigest()
+
+
+def binding(package: Package) -> dict[str, Any]:
+    return {
+        "name": package.name,
+        "version": package.version,
+        "path": package.path,
+        "entrypoint": package.entrypoint,
+        "source": package.source,
+    }
+
+
+def parse_lock(data: dict[str, Any]) -> dict[str, Any]:
+    if type(data.get("schema_version")) is not int or data["schema_version"] != 1:
+        raise MacrostatesError("Unsupported lock schema_version; supported: 1")
+    packages = mapping(data.get("packages"), "lock.packages")
+    for name, raw in packages.items():
+        record = mapping(raw, "locked package")
+        mapping(record.get("selection"), "lock selection")
+        if not isinstance(record.get("commit"), str) or not re.fullmatch(
+            r"[0-9a-f]{40}|[0-9a-f]{64}", record["commit"]
+        ):
+            raise MacrostatesError("Lock commit must be a full Git object ID")
+        files = mapping(record.get("files"), "lock files")
+        seen: set[str] = set()
+        for path, value in files.items():
+            relative_path(path, "locked file")
+            if path.casefold() in seen:
+                raise MacrostatesError("Lock has case-colliding file paths")
+            seen.add(path.casefold())
+            item = mapping(value, "locked file")
+            if not isinstance(item.get("sha256"), str) or not re.fullmatch(
+                r"[0-9a-f]{64}", item["sha256"]
+            ):
+                raise MacrostatesError("Invalid locked file checksum")
+            if type(item.get("executable")) is not bool:
+                raise MacrostatesError("Locked executable flag must be boolean")
+        if record.get("content_sha256") != content_hash(files):
+            raise MacrostatesError(f"Inconsistent lock checksum for {name}")
+    return packages