mojox-core 0.5.0__py3-none-any.whl

mojox_core/__init__.py

@@ -0,0 +1,63 @@
+"""mojox-core: pure model layer for Mojo build tooling.
+
+Public API:
+  - Types: Manifest, Command, Policy, ResolvedEnv, TargetGraph, etc.
+  - Transformers: parse_manifest, build_env, discover, resolve, plan, serialize
+  - Errors: ConfigError
+"""
+
+from ._errors import ConfigError
+from ._types import (
+    BinaryEntry,
+    Command,
+    CommandKind,
+    Diagnostic,
+    DistEntry,
+    DistKind,
+    HostFacts,
+    LintConfig,
+    LocalSettings,
+    Manifest,
+    Policy,
+    Profile,
+    ResolvedEnv,
+    Target,
+    TargetGraph,
+    TargetKind,
+    Toolchain,
+)
+from .environment import build_env
+from .manifest import parse_manifest
+from .metadata import serialize
+from .plan import plan
+from .policy import resolve
+from .settings import parse_settings
+from .targets import discover
+
+__all__ = [
+    "BinaryEntry",
+    "Command",
+    "CommandKind",
+    "ConfigError",
+    "Diagnostic",
+    "DistEntry",
+    "DistKind",
+    "HostFacts",
+    "LintConfig",
+    "LocalSettings",
+    "Manifest",
+    "Policy",
+    "Profile",
+    "ResolvedEnv",
+    "Target",
+    "TargetGraph",
+    "TargetKind",
+    "Toolchain",
+    "build_env",
+    "discover",
+    "parse_manifest",
+    "parse_settings",
+    "plan",
+    "resolve",
+    "serialize",
+]

mojox_core/_errors.py

@@ -0,0 +1,16 @@
+"""User-facing configuration errors with structured key paths."""
+
+from __future__ import annotations
+
+
+class ConfigError(Exception):
+    """A configuration error carrying the offending key path and a remediation.
+
+    No KeyError, no TypeError, no stack trace reaches the user — every
+    rejection produces one of these with a human-readable message.
+    """
+
+    def __init__(self, key_path: str, message: str) -> None:
+        self.key_path = key_path
+        self.message = message
+        super().__init__(f"[{key_path}] {message}")

mojox_core/_types.py

@@ -0,0 +1,235 @@
+"""All frozen dataclasses for the mojox-core model layer.
+
+Every type here is immutable (frozen=True). No type in this module imports
+subprocess or performs I/O. Path-valued fields use PurePosixPath for lexical
+paths (manifest-relative) and str for resolved absolute paths (from readers).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import PurePosixPath
+from typing import ClassVar, Literal
+
+# -- Enums -----------------------------------------------------------------
+
+
+class CommandKind(Enum):
+    """The kind of mojo invocation a Command represents."""
+
+    COMPILE_PACKAGE = "compile-package"
+    COMPILE_BINARY = "compile-binary"
+    RUN_TEST = "run-test"
+    CHECK_EXAMPLE = "check-example"
+    RUN = "run"
+
+
+class TargetKind(Enum):
+    """Discovered target kinds."""
+
+    LIB = "lib"
+    BIN = "bin"
+    TEST = "test"
+    EXAMPLE = "example"
+
+
+class DistKind(Enum):
+    """How a distribution provides its Mojo packages."""
+
+    SOURCE = "source"
+    PRECOMPILED = "precompiled"
+
+
+# -- Leaf types ------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BinaryEntry:
+    """One executable produced by ``mojo build``."""
+
+    source: str
+    name: str
+
+
+@dataclass(frozen=True)
+class LintConfig:
+    """Lint settings that translate to compiler flags."""
+
+    warnings_as_errors: bool = False
+    check_doc_strings: bool = False
+    missing_doc_strings: bool = False
+    unstable_apis: bool = False
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """A compiler or mojox diagnostic."""
+
+    kind: Literal["error", "warning", "note"]
+    message: str
+    file: str | None = None
+    line: int | None = None
+    column: int | None = None
+    source_text: str | None = None
+
+
+@dataclass(frozen=True)
+class Target:
+    """A discovered build target."""
+
+    kind: TargetKind
+    path: str
+    target_id: str
+
+
+@dataclass(frozen=True)
+class DistEntry:
+    """One installed distribution contributing to the include sequence."""
+
+    name: str
+    include_dir: str
+    kind: DistKind
+    packages: tuple[str, ...]
+    provenance: str
+    native_lib_dirs: tuple[str, ...] = ()
+
+
+# -- Compound types --------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Profile:
+    """A named compilation profile (dev, release, or user-declared)."""
+
+    optimize: int | None = None
+    debug_level: str | None = None
+    defines: dict[str, str] = field(default_factory=dict)
+    flags: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """Parsed pyproject.toml -- portable, published, versioned with the code."""
+
+    # [project]
+    name: str
+    version: str
+    description: str | None
+    readme: str | None
+    license_expr: str | None
+    license_files: tuple[str, ...]
+    requires_python: str | None
+    dependencies: tuple[str, ...]
+    optional_dependencies: dict[str, tuple[str, ...]]
+    keywords: tuple[str, ...]
+    authors: tuple[dict[str, str], ...]
+    maintainers: tuple[dict[str, str], ...]
+    urls: dict[str, str]
+    classifiers: tuple[str, ...]
+
+    # [tool.mojox]
+    packages: tuple[str, ...] | None
+    package_root: str
+    binaries: tuple[BinaryEntry, ...]
+    test_roots: tuple[str, ...]
+    test_parallel: bool
+    defines: dict[str, str]
+    flags: tuple[str, ...]
+    lints: LintConfig
+    optimize: int | None
+    debug_level: str | None
+    pre_build: tuple[tuple[str, ...], ...]
+    native_libs: tuple[str, ...]
+    source_include: tuple[str, ...] | None
+    source_exclude: tuple[str, ...]
+    wheel_exclude: tuple[str, ...]
+    profiles: dict[str, Profile]
+    build_profile: str
+
+
+@dataclass(frozen=True)
+class TargetGraph:
+    """Discovered targets in topological order (lib targets first)."""
+
+    targets: tuple[Target, ...]
+    edges: tuple[tuple[str, str], ...]
+    unsearched_test_dirs: tuple[tuple[str, int], ...] = ()
+
+
+@dataclass(frozen=True)
+class ResolvedEnv:
+    """The resolved build environment -- include sequence, mojo binary, provenance."""
+
+    include_sequence: tuple[DistEntry, ...]
+    mojo_path: str
+    mojo_version: str
+    path_mojo: str | None
+    lock_version: int | None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+@dataclass(frozen=True)
+class Toolchain:
+    """Resolved Mojo toolchain identity."""
+
+    mojo_path: str
+    version: str
+    subcommand: str
+    extension: str
+
+
+@dataclass(frozen=True)
+class HostFacts:
+    """Machine-specific facts injected into the planner for determinism."""
+
+    cpu_count: int
+    available_memory_mb: int
+    manifest_dir: PurePosixPath
+
+
+@dataclass(frozen=True)
+class LocalSettings:
+    """Machine-local settings (from .mojox/config.toml + env vars)."""
+
+    jobs: int | None = None
+    timeout_s: int | None = None
+    config_paths: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+
+    EMPTY: ClassVar[LocalSettings]  # set below
+
+
+# Bootstrap the EMPTY sentinel after the class is defined.
+LocalSettings.EMPTY = LocalSettings()
+
+
+@dataclass(frozen=True)
+class Policy:
+    """The fully resolved flag set the planner consumes."""
+
+    optimize: int
+    debug_level: str
+    defines: dict[str, str]
+    flags: tuple[str, ...]
+    include_paths: tuple[str, ...]
+    lints: LintConfig
+    jobs: int
+    jobs_compile: int
+    jobs_tests: int
+    timeout_s: int
+
+
+@dataclass(frozen=True)
+class Command:
+    """One mojo invocation the planner produces."""
+
+    argv: tuple[str, ...]
+    cwd: PurePosixPath
+    env: Mapping[str, str]
+    kind: CommandKind
+    target_id: str
+    timeout_s: int | None
+    outputs: tuple[str, ...]
+    depends_on: tuple[str, ...]

mojox_core/environment.py

@@ -0,0 +1,134 @@
+"""Build the resolved environment from distribution data.
+
+Pure transformer -- receives pre-read distribution info and returns ResolvedEnv.
+The IO reader that enumerates distributions lives in mojox_core.io.environment.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._errors import ConfigError
+from ._types import Diagnostic, DistEntry, DistKind, ResolvedEnv
+
+_MAX_KNOWN_LOCK_VERSION = 1
+
+
+def build_env(
+    dists: list[dict[str, Any]],
+    lock_data: dict[str, Any] | None,
+    mojo_path: str,
+    mojo_version: str,
+    *,
+    path_mojo: str | None = None,
+) -> ResolvedEnv:
+    """Build a ResolvedEnv from distribution data and optional lockfile.
+
+    Args:
+        dists: List of distribution dicts, each containing 'name',
+            'include_dir', 'kind', 'packages', 'provenance', and
+            'native_lib_dirs' keys.
+        lock_data: Parsed lockfile data (with 'version' key), or None.
+        mojo_path: Path to the Mojo compiler in the virtual environment.
+        mojo_version: Version string of the Mojo compiler.
+        path_mojo: Path to Mojo found on PATH, if different from mojo_path.
+
+    Returns:
+        A fully resolved ResolvedEnv instance.
+
+    Raises:
+        ConfigError: If a package appears as both source and precompiled
+            in the same include directory.
+    """
+    diagnostics: list[Diagnostic] = []
+    entries: list[DistEntry] = []
+
+    _check_source_shadows_precompiled(dists)
+
+    for d in dists:
+        entries.append(
+            DistEntry(
+                name=d["name"],
+                include_dir=d["include_dir"],
+                kind=d["kind"],
+                packages=tuple(d["packages"]),
+                provenance=d.get("provenance", "unknown"),
+                native_lib_dirs=tuple(d.get("native_lib_dirs", ())),
+            )
+        )
+
+    lock_version = _extract_lock_version(lock_data, diagnostics)
+
+    if path_mojo is not None and path_mojo != mojo_path:
+        diagnostics.append(
+            Diagnostic(
+                kind="warning",
+                message=f"PATH mojo ({path_mojo}) differs from environment mojo "
+                f"({mojo_path}). The environment mojo will be used.",
+            )
+        )
+
+    return ResolvedEnv(
+        include_sequence=tuple(entries),
+        mojo_path=mojo_path,
+        mojo_version=mojo_version,
+        path_mojo=path_mojo,
+        lock_version=lock_version,
+        diagnostics=tuple(diagnostics),
+    )
+
+
+def _check_source_shadows_precompiled(dists: list[dict[str, Any]]) -> None:
+    """Raise ConfigError if any package is both source and precompiled in the same dir.
+
+    Args:
+        dists: List of distribution dicts to validate.
+
+    Raises:
+        ConfigError: If a source-shadows-precompiled conflict is detected.
+    """
+    dir_packages: dict[str, dict[str, list[DistKind]]] = {}
+    for d in dists:
+        include_dir = d["include_dir"]
+        by_name = dir_packages.setdefault(include_dir, {})
+        for pkg in d["packages"]:
+            by_name.setdefault(pkg, []).append(d["kind"])
+
+    for include_dir, pkgs_by_name in dir_packages.items():
+        for pkg_name, kinds in pkgs_by_name.items():
+            if DistKind.SOURCE in kinds and DistKind.PRECOMPILED in kinds:
+                raise ConfigError(
+                    f"environment.{include_dir}",
+                    f"source-shadows-precompiled: package {pkg_name!r} exists "
+                    f"as both source and precompiled in {include_dir!r}. The "
+                    "source silently wins and the consumer is on the slow "
+                    "path. Remove one.",
+                )
+
+
+def _extract_lock_version(
+    lock_data: dict[str, Any] | None,
+    diagnostics: list[Diagnostic],
+) -> int | None:
+    """Extract and validate the lockfile schema version.
+
+    Args:
+        lock_data: Parsed lockfile data, or None.
+        diagnostics: Mutable list to append warnings to.
+
+    Returns:
+        The lock version integer, or None if no lockfile was provided.
+    """
+    if lock_data is None:
+        return None
+    lock_version = lock_data.get("version")
+    if lock_version is not None and lock_version > _MAX_KNOWN_LOCK_VERSION:
+        diagnostics.append(
+            Diagnostic(
+                kind="warning",
+                message=f"uv.lock schema version {lock_version} is above the "
+                f"known maximum ({_MAX_KNOWN_LOCK_VERSION}). Provenance data "
+                "may be incomplete.",
+            )
+        )
+    return lock_version

mojox_core/io/__init__.py

@@ -0,0 +1 @@
+"""Effectful IO readers — separated from pure transformers."""

mojox_core/io/environment.py

@@ -0,0 +1,114 @@
+"""Read the installed environment — the effectful half of environment building.
+
+Enumerates installed distributions via importlib.metadata, checks which
+ship mojo_packages/, reads uv.lock when present, and gathers HostFacts.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import os
+import sysconfig
+from pathlib import Path
+from typing import Any
+
+from .._types import DistKind, HostFacts
+
+
+def read_distributions(platlib: str | None = None) -> list[dict[str, Any]]:
+    """Enumerate installed distributions that ship Mojo packages.
+
+    Returns a list of dicts suitable for passing to environment.build_env().
+    """
+    if platlib is None:
+        platlib = sysconfig.get_path("platlib")
+    assert platlib is not None
+
+    mojo_packages_dir = Path(platlib) / "mojo_packages"
+    if not mojo_packages_dir.is_dir():
+        return []
+
+    dists: list[dict[str, Any]] = []
+    for dist in importlib.metadata.distributions():
+        if dist.files is None:
+            continue
+        has_mojo = False
+        packages: list[str] = []
+
+        for f in dist.files:
+            parts = str(f).split("/")
+            if len(parts) >= 2 and parts[0] == "mojo_packages":
+                has_mojo = True
+                pkg_name = parts[1]
+                if pkg_name.endswith((".mojoc", ".mojopkg")):
+                    pkg_name = pkg_name.rsplit(".", 1)[0]
+                    kind = DistKind.PRECOMPILED
+                elif not pkg_name.startswith("_") and pkg_name != "lib":
+                    kind = DistKind.SOURCE
+                else:
+                    continue
+                if pkg_name not in packages:
+                    packages.append(pkg_name)
+
+        if has_mojo and packages:
+            dists.append(
+                {
+                    "name": dist.metadata["Name"],
+                    "include_dir": str(mojo_packages_dir),
+                    "kind": kind,
+                    "packages": packages,
+                    "provenance": dist.metadata.get("Version", "unknown"),
+                    "native_lib_dirs": (),
+                }
+            )
+
+    return dists
+
+
+def read_lockfile(project_root: Path) -> dict[str, Any] | None:
+    """Read uv.lock if it exists, returning parsed TOML or None."""
+    import sys
+
+    if sys.version_info >= (3, 11):
+        import tomllib
+    else:
+        import tomli as tomllib  # type: ignore[import-not-found, no-redef]
+
+    lock_path = project_root / "uv.lock"
+    if not lock_path.is_file():
+        return None
+
+    try:
+        with open(lock_path, "rb") as f:
+            return tomllib.load(f)
+    except Exception:
+        return None
+
+
+def read_host_facts(manifest_dir: Path) -> HostFacts:
+    """Gather machine-specific facts for the planner."""
+    from pathlib import PurePosixPath
+
+    cpu_count = os.cpu_count() or 1
+    mem_mb = _available_memory_mb()
+
+    return HostFacts(
+        cpu_count=cpu_count,
+        available_memory_mb=mem_mb,
+        manifest_dir=PurePosixPath(str(manifest_dir.resolve())),
+    )
+
+
+def _available_memory_mb() -> int:
+    """Best-effort available memory in MB."""
+    try:
+        import resource  # noqa: F401
+
+        # Try /proc/meminfo on Linux
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemAvailable:"):
+                    return int(line.split()[1]) // 1024
+    except (ImportError, OSError):
+        pass
+    return 16384

mojox_core/io/manifest.py

@@ -0,0 +1,29 @@
+"""Read pyproject.toml from disk — the effectful half of manifest parsing."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .._errors import ConfigError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found, no-redef]
+
+
+def read(path: Path) -> dict[str, Any]:
+    """Read and parse a pyproject.toml file.
+
+    Returns the parsed dict. Raises ConfigError if the file is missing or
+    contains invalid TOML.
+    """
+    if not path.is_file():
+        raise ConfigError("pyproject.toml", f"{path} not found")
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except Exception as e:
+        raise ConfigError("pyproject.toml", f"failed to parse: {e}") from e

mojox_core/io/toolchain.py

@@ -0,0 +1,98 @@
+"""Resolve the Mojo toolchain from installed distributions.
+
+Uses importlib.metadata to find the mojo-compiler distribution, its
+console script entry point, and version. Never invokes mojo --version.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from .._errors import ConfigError
+from .._types import Toolchain
+
+
+def resolve() -> Toolchain:
+    """Resolve the installed Mojo toolchain.
+
+    Reads the mojo-compiler distribution metadata to find the binary path
+    and version. Never runs a subprocess.
+
+    Returns:
+        A ``Toolchain`` with the mojo binary path, version string,
+        subcommand (``"precompile"``), and extension (``".mojoc"``).
+
+    Raises:
+        ConfigError: If ``mojo-compiler`` is not installed or its ``mojo``
+            binary cannot be located in the distribution's file list.
+    """
+    try:
+        dist = importlib.metadata.distribution("mojo-compiler")
+    except importlib.metadata.PackageNotFoundError:
+        raise ConfigError(
+            "toolchain",
+            "mojo-compiler is not installed. Install it with: uv add mojo-compiler",
+        )
+
+    version = dist.metadata["Version"]
+
+    # Find the mojo console script
+    mojo_path = _find_console_script(dist)
+
+    # Determine subcommand and extension based on version
+    subcommand = "precompile"
+    extension = ".mojoc"
+
+    return Toolchain(
+        mojo_path=mojo_path,
+        version=version,
+        subcommand=subcommand,
+        extension=extension,
+    )
+
+
+def _find_console_script(dist: importlib.metadata.Distribution) -> str:
+    """Find the mojo console script path from the distribution.
+
+    Searches the distribution's recorded file list for a file named ``mojo``
+    (either at the top of a scripts directory or under ``bin/``). Falls back
+    to inspecting entry_points if the file list doesn't yield a match.
+
+    Args:
+        dist: The ``mojo-compiler`` distribution object.
+
+    Returns:
+        The absolute path to the ``mojo`` binary as a string.
+
+    Raises:
+        ConfigError: If the binary cannot be located.
+    """
+    # Look in the scripts directory
+    if dist.files:
+        for f in dist.files:
+            parts = str(f).split("/")
+            if len(parts) >= 1 and parts[-1] == "mojo":
+                located = dist.locate_file(f)
+                if located and Path(str(located)).exists():
+                    return str(Path(str(located)).resolve())
+
+    # Fallback: try the entry_points
+    eps = dist.entry_points
+    for ep in eps:
+        if ep.name == "mojo":
+            # entry_points don't directly give us a path; use the scripts dir
+            break
+
+    # Last resort: look in the same directory as the package
+    pkg_files = dist.files or []
+    for f in pkg_files:
+        if str(f).endswith("/bin/mojo") or str(f) == "bin/mojo":
+            located = dist.locate_file(f)
+            if located:
+                return str(Path(str(located)).resolve())
+
+    raise ConfigError(
+        "toolchain",
+        "mojo-compiler is installed but the `mojo` binary was not found in its file list",
+    )