mojox-core 0.5.0__tar.gz

mojox_core-0.5.0/.gitignore

@@ -0,0 +1,10 @@
+# Local working docs (project context, specs, plans)
+docs/
+specs/
+plans/
+
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.venv/

mojox_core-0.5.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: mojox-core
+Version: 0.5.0
+Summary: Pure model layer for mojox: manifest parsing, target discovery, policy resolution, and build planning.
+Project-URL: Repository, https://github.com/Conobi/mojox
+Author: Conobi
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: packaging>=23.0
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# mojox-core
+
+Pure model layer for the [mojox](https://github.com/Conobi/mojox) build system.
+No I/O, no subprocess, no filesystem access at module level.
+All data types are frozen dataclasses; every transformer is a pure function
+(data in, data out).
+
+## Install
+
+```bash
+uv add mojox-core
+```
+
+Requires Python 3.10+. Only runtime dependency is `packaging>=23.0`
+(plus `tomli` on Python < 3.11).
+
+## Pipeline
+
+The core exposes a five-stage pipeline where each step takes immutable data
+and returns immutable data:
+
+```
+parse  ->  discover  ->  resolve  ->  plan  ->  serialize
+```
+
+I/O readers live in the separate `mojox_core.io` subpackage. Consumers can
+skip them entirely and feed fixtures directly into the pipeline.
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from mojox_core import (
+    parse_manifest,
+    discover,
+    resolve,
+    plan,
+    serialize,
+    LocalSettings,
+)
+from mojox_core.io.manifest import read as read_manifest
+from mojox_core.io.toolchain import resolve as resolve_toolchain
+from mojox_core.io.environment import (
+    read_distributions,
+    read_lockfile,
+    read_host_facts,
+)
+from mojox_core import build_env
+
+# 1. Read raw TOML (I/O)
+raw = read_manifest(Path("."))
+
+# 2. Parse manifest (pure)
+manifest = parse_manifest(raw)
+
+# 3. Discover targets by convention (pure)
+targets = discover(manifest, Path("."))
+
+# 4. Resolve build policy from all precedence layers (pure)
+policy = resolve(manifest, "dev", {}, LocalSettings.EMPTY)
+
+# 5. Detect toolchain and build environment (I/O)
+toolchain = resolve_toolchain()
+dists = read_distributions()
+lock = read_lockfile(Path("."))
+env = build_env(dists, lock, toolchain.mojo_path, toolchain.version)
+host = read_host_facts(Path("."))
+
+# 6. Plan mojo invocations (pure)
+commands = plan(targets, env, policy, toolchain, host)
+
+for cmd in commands:
+    print(cmd.kind, cmd.argv)
+
+# 7. Serialize to the `mojox metadata` JSON schema (pure)
+metadata = serialize(targets, env, policy, commands, toolchain, diagnostics=())
+```
+
+## Public API
+
+### Types
+
+All exported from `mojox_core`. Every type is a frozen dataclass or enum.
+
+| Type | Description |
+|------|-------------|
+| `Manifest` | Parsed `[tool.mojox]` config and PEP 621 project metadata |
+| `Command` | A planned mojo invocation (data, not execution) |
+| `CommandKind` | Enum of command kinds |
+| `Policy` | Resolved build policy (profile + defines + flags) |
+| `Profile` | Build profile (`dev` or `release`) with optimization/debug settings |
+| `Target` | A single build/test/example/binary target |
+| `TargetKind` | Enum of target kinds |
+| `TargetGraph` | The full set of discovered targets |
+| `ResolvedEnv` | Resolved environment (import paths, library paths, mojo binary) |
+| `Toolchain` | Detected Mojo toolchain info |
+| `HostFacts` | Host platform facts |
+| `LocalSettings` | Parsed `.mojox/config.toml` settings |
+| `Diagnostic` | Lint diagnostic |
+| `LintConfig` | Lint configuration |
+| `DistEntry` | Distribution metadata entry |
+| `DistKind` | Enum of distribution kinds |
+| `BinaryEntry` | Binary entry in a distribution |
+
+### Transformers
+
+Pure functions. No side effects, no I/O.
+
+```python
+parse_manifest(data: dict) -> Manifest
+discover(manifest: Manifest, root: Path) -> TargetGraph
+resolve(manifest: Manifest, profile_name: str, cli_overrides: dict, settings: LocalSettings) -> Policy
+plan(graph: TargetGraph, env: ResolvedEnv, policy: Policy, toolchain: Toolchain, host: HostFacts) -> tuple[Command, ...]
+build_env(dists: list[dict], lock_data: dict | None, mojo_path: str, mojo_version: str) -> ResolvedEnv
+serialize(graph: TargetGraph, env: ResolvedEnv, policy: Policy, commands: tuple[Command, ...], toolchain: Toolchain, diagnostics: tuple[Diagnostic, ...]) -> dict
+parse_settings(user: dict | None, project: dict | None, env: dict[str, str]) -> LocalSettings
+```
+
+### I/O readers
+
+In the `mojox_core.io` subpackage. These are the only functions that touch
+the filesystem or run subprocesses.
+
+```python
+mojox_core.io.manifest.read(path: Path) -> dict                    # read & parse pyproject.toml
+mojox_core.io.toolchain.resolve() -> Toolchain                     # detect installed Mojo compiler
+mojox_core.io.environment.read_distributions(platlib=None) -> list[dict]  # scan installed dists
+mojox_core.io.environment.read_lockfile(project_root: Path) -> dict | None
+mojox_core.io.environment.read_host_facts(manifest_dir: Path) -> HostFacts
+```
+
+### Errors
+
+```python
+class ConfigError(Exception):
+    key_path: str  # dotted path to the offending key
+    message: str  # human-readable explanation
+```
+
+Raised on invalid manifest or settings. No `KeyError` or `TypeError` reaches
+the caller -- every rejection is a `ConfigError` with a structured key path.
+
+## Testing without I/O
+
+Because the pipeline is pure, you can test any stage by constructing fixtures
+directly:
+
+```python
+from mojox_core import Manifest, discover, TargetGraph
+
+manifest = Manifest(...)  # build the frozen dataclass by hand
+graph = discover(manifest, some_temp_dir)
+assert isinstance(graph, TargetGraph)
+```
+
+No mojo compiler, no installed packages, no pyproject.toml required.
+
+## See also
+
+- [mojox](https://github.com/Conobi/mojox) -- CLI that drives the full build
+- [mojox-build](https://github.com/Conobi/mojox/tree/main/packages/mojox-build) -- PEP 517 build backend
+
+## License
+
+MIT

mojox_core-0.5.0/README.md

@@ -0,0 +1,166 @@
+# mojox-core
+
+Pure model layer for the [mojox](https://github.com/Conobi/mojox) build system.
+No I/O, no subprocess, no filesystem access at module level.
+All data types are frozen dataclasses; every transformer is a pure function
+(data in, data out).
+
+## Install
+
+```bash
+uv add mojox-core
+```
+
+Requires Python 3.10+. Only runtime dependency is `packaging>=23.0`
+(plus `tomli` on Python < 3.11).
+
+## Pipeline
+
+The core exposes a five-stage pipeline where each step takes immutable data
+and returns immutable data:
+
+```
+parse  ->  discover  ->  resolve  ->  plan  ->  serialize
+```
+
+I/O readers live in the separate `mojox_core.io` subpackage. Consumers can
+skip them entirely and feed fixtures directly into the pipeline.
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from mojox_core import (
+    parse_manifest,
+    discover,
+    resolve,
+    plan,
+    serialize,
+    LocalSettings,
+)
+from mojox_core.io.manifest import read as read_manifest
+from mojox_core.io.toolchain import resolve as resolve_toolchain
+from mojox_core.io.environment import (
+    read_distributions,
+    read_lockfile,
+    read_host_facts,
+)
+from mojox_core import build_env
+
+# 1. Read raw TOML (I/O)
+raw = read_manifest(Path("."))
+
+# 2. Parse manifest (pure)
+manifest = parse_manifest(raw)
+
+# 3. Discover targets by convention (pure)
+targets = discover(manifest, Path("."))
+
+# 4. Resolve build policy from all precedence layers (pure)
+policy = resolve(manifest, "dev", {}, LocalSettings.EMPTY)
+
+# 5. Detect toolchain and build environment (I/O)
+toolchain = resolve_toolchain()
+dists = read_distributions()
+lock = read_lockfile(Path("."))
+env = build_env(dists, lock, toolchain.mojo_path, toolchain.version)
+host = read_host_facts(Path("."))
+
+# 6. Plan mojo invocations (pure)
+commands = plan(targets, env, policy, toolchain, host)
+
+for cmd in commands:
+    print(cmd.kind, cmd.argv)
+
+# 7. Serialize to the `mojox metadata` JSON schema (pure)
+metadata = serialize(targets, env, policy, commands, toolchain, diagnostics=())
+```
+
+## Public API
+
+### Types
+
+All exported from `mojox_core`. Every type is a frozen dataclass or enum.
+
+| Type | Description |
+|------|-------------|
+| `Manifest` | Parsed `[tool.mojox]` config and PEP 621 project metadata |
+| `Command` | A planned mojo invocation (data, not execution) |
+| `CommandKind` | Enum of command kinds |
+| `Policy` | Resolved build policy (profile + defines + flags) |
+| `Profile` | Build profile (`dev` or `release`) with optimization/debug settings |
+| `Target` | A single build/test/example/binary target |
+| `TargetKind` | Enum of target kinds |
+| `TargetGraph` | The full set of discovered targets |
+| `ResolvedEnv` | Resolved environment (import paths, library paths, mojo binary) |
+| `Toolchain` | Detected Mojo toolchain info |
+| `HostFacts` | Host platform facts |
+| `LocalSettings` | Parsed `.mojox/config.toml` settings |
+| `Diagnostic` | Lint diagnostic |
+| `LintConfig` | Lint configuration |
+| `DistEntry` | Distribution metadata entry |
+| `DistKind` | Enum of distribution kinds |
+| `BinaryEntry` | Binary entry in a distribution |
+
+### Transformers
+
+Pure functions. No side effects, no I/O.
+
+```python
+parse_manifest(data: dict) -> Manifest
+discover(manifest: Manifest, root: Path) -> TargetGraph
+resolve(manifest: Manifest, profile_name: str, cli_overrides: dict, settings: LocalSettings) -> Policy
+plan(graph: TargetGraph, env: ResolvedEnv, policy: Policy, toolchain: Toolchain, host: HostFacts) -> tuple[Command, ...]
+build_env(dists: list[dict], lock_data: dict | None, mojo_path: str, mojo_version: str) -> ResolvedEnv
+serialize(graph: TargetGraph, env: ResolvedEnv, policy: Policy, commands: tuple[Command, ...], toolchain: Toolchain, diagnostics: tuple[Diagnostic, ...]) -> dict
+parse_settings(user: dict | None, project: dict | None, env: dict[str, str]) -> LocalSettings
+```
+
+### I/O readers
+
+In the `mojox_core.io` subpackage. These are the only functions that touch
+the filesystem or run subprocesses.
+
+```python
+mojox_core.io.manifest.read(path: Path) -> dict                    # read & parse pyproject.toml
+mojox_core.io.toolchain.resolve() -> Toolchain                     # detect installed Mojo compiler
+mojox_core.io.environment.read_distributions(platlib=None) -> list[dict]  # scan installed dists
+mojox_core.io.environment.read_lockfile(project_root: Path) -> dict | None
+mojox_core.io.environment.read_host_facts(manifest_dir: Path) -> HostFacts
+```
+
+### Errors
+
+```python
+class ConfigError(Exception):
+    key_path: str  # dotted path to the offending key
+    message: str  # human-readable explanation
+```
+
+Raised on invalid manifest or settings. No `KeyError` or `TypeError` reaches
+the caller -- every rejection is a `ConfigError` with a structured key path.
+
+## Testing without I/O
+
+Because the pipeline is pure, you can test any stage by constructing fixtures
+directly:
+
+```python
+from mojox_core import Manifest, discover, TargetGraph
+
+manifest = Manifest(...)  # build the frozen dataclass by hand
+graph = discover(manifest, some_temp_dir)
+assert isinstance(graph, TargetGraph)
+```
+
+No mojo compiler, no installed packages, no pyproject.toml required.
+
+## See also
+
+- [mojox](https://github.com/Conobi/mojox) -- CLI that drives the full build
+- [mojox-build](https://github.com/Conobi/mojox/tree/main/packages/mojox-build) -- PEP 517 build backend
+
+## License
+
+MIT

mojox_core-0.5.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "mojox-core"
+version = "0.5.0"
+description = "Pure model layer for mojox: manifest parsing, target discovery, policy resolution, and build planning."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Conobi" }]
+dependencies = [
+  "packaging>=23.0",
+  'tomli >= 1.1.0; python_version < "3.11"',
+]
+
+[project.urls]
+Repository = "https://github.com/Conobi/mojox"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mojox_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true

mojox_core-0.5.0/src/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-0.5.0/src/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-0.5.0/src/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, ...]