forje 0.1.0__py3-none-any.whl

forje/__init__.py

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

forje/backend/__init__.py

@@ -0,0 +1,3 @@
+from .backend import Backend
+
+__all__ = ["Backend"]

forje/backend/android.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+from typing import final, override
+
+from resforge import Color
+from resforge.android import ValuesWriter
+from resforge.io import MemorySink, WriteSink
+
+from forje.backend import Backend
+from forje.ir import ArtifactNode, TargetNode, TokenMapping
+from forje.ir.models import ColorNode
+
+
+def _to_color(node: ColorNode) -> Color:
+    return Color(
+        x=node.coords[0],
+        y=node.coords[1],
+        z=node.coords[2],
+        alpha=node.alpha,
+    )
+
+
+def _write_tokens(sink: WriteSink, path: Path, nodes: dict[str, ColorNode]) -> None:
+    with ValuesWriter(path, sink=sink) as res:
+        colors = {name: _to_color(node) for name, node in nodes.items()}
+        res.color(**colors)
+
+
+@final
+class Android(Backend):
+    """Generates Android XML resource files for colors from design tokens."""
+
+    @override
+    def codegen(self, target: TargetNode, artifact: ArtifactNode) -> dict[str, bytes]:
+        colors = [t for t in target.tokens.values() if t.kind == "color"]
+
+        def get_mapping(mode: TokenMapping) -> dict[str, ColorNode]:
+            return {t.name: t.mapping[mode] for t in colors if mode in t.mapping}
+
+        light = get_mapping("light")
+        dark = get_mapping("dark")
+
+        sink = MemorySink()
+        base_path = Path(artifact.path)
+        stem = artifact.stem or "colors"
+
+        _write_tokens(sink, base_path / "values" / f"{stem}.xml", light)
+        _write_tokens(sink, base_path / "values-night" / f"{stem}.xml", dark)
+
+        return sink.files

forje/backend/apple.py

@@ -0,0 +1,55 @@
+import re
+from typing import final, override
+
+from resforge import Color
+from resforge.apple import Appearance, AppleColor, AssetCatalog
+from resforge.io import MemorySink
+
+from forje.backend import Backend
+from forje.ir import ArtifactNode, ColorNode, TargetNode, TokenMapping
+
+_APPEARANCE_MAP: dict[TokenMapping, list[Appearance]] = {
+    "light": [],
+    "dark": [Appearance.Dark],
+    "high_contrast_light": [Appearance.HighContrast, Appearance.Light],
+    "high_contrast_dark": [Appearance.HighContrast, Appearance.Dark],
+}
+
+
+def _to_pascal_case(value: str) -> str:
+    words = re.split(r"[-_]+", value)
+    return "".join(w.capitalize() for w in words if w)
+
+
+def _to_color(node: ColorNode) -> Color:
+    return Color(
+        x=node.coords[0],
+        y=node.coords[1],
+        z=node.coords[2],
+        alpha=node.alpha,
+    )
+
+
+@final
+class Apple(Backend):
+    """Generates Apple Asset Catalogs from design tokens."""
+
+    @override
+    def codegen(self, target: TargetNode, artifact: ArtifactNode) -> dict[str, bytes]:
+        color_tokens = (t for t in target.tokens.values() if t.kind == "color")
+        sink = MemorySink()
+
+        with AssetCatalog(
+            artifact.path,
+            artifact.stem or "Assets",
+            sink=sink,
+        ) as catalog:
+            for token in color_tokens:
+                name = _to_pascal_case(token.name)
+                apple_colors = [
+                    AppleColor(_to_color(node), appearances=_APPEARANCE_MAP[mode])
+                    for mode, node in token.mapping.items()
+                ]
+                catalog.colorset(name, *apple_colors)
+
+        return sink.files

forje/backend/backend.py

@@ -0,0 +1,22 @@
+from typing import Protocol, runtime_checkable
+
+from forje.ir import ArtifactNode, TargetNode
+
+__all__ = ["Backend"]
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """Interface for platform-specific code generators."""
+
+    def codegen(
+        self,
+        target: TargetNode,
+        artifact: ArtifactNode,
+    ) -> dict[str, bytes]:
+        """Generates platform assets for a target.
+
+        Returns:
+            File paths relative to the base directory mapped to their contents.
+        """
+        ...

forje/backend/css.py

@@ -0,0 +1,96 @@
+import math
+from pathlib import Path
+from typing import final, override
+
+from resforge import Color
+from resforge.io import MemorySink
+
+from forje.backend import Backend
+from forje.ir import ArtifactNode, ColorNode, TargetNode, TokenMapping
+
+__all__ = ["CSS"]
+
+_QUERY_CONTRAST = "(prefers-contrast: more)"
+_QUERY_LIGHT = "(prefers-color-scheme: light)"
+_QUERY_DARK = "(prefers-color-scheme: dark)"
+_QUERIES: dict[TokenMapping, str | None] = {
+    "light": None,
+    "dark": f"@media {_QUERY_DARK}",
+    "high_contrast_light": f"@media {_QUERY_CONTRAST} and {_QUERY_LIGHT}",
+    "high_contrast_dark": f"@media {_QUERY_CONTRAST} and {_QUERY_DARK}",
+}
+
+
+def _to_color(node: ColorNode) -> Color:
+    return Color(
+        x=node.coords[0],
+        y=node.coords[1],
+        z=node.coords[2],
+        alpha=node.alpha,
+    )
+
+
+def _to_css_vars(name: str, node: ColorNode) -> tuple[str, str]:
+    name = f"--color-{name.lower().strip().replace('_', '-')}"
+    color = _to_color(node)
+
+    r, g, b, a_srgb = color.to_srgb_components()
+    r = round(r * 255)
+    g = round(g * 255)
+    b = round(b * 255)
+
+    l, c, h, a_oklch = color.to_oklch_components()
+    h = "none" if math.isnan(h) else round(h, 3)
+
+    return (
+        f"{name}: rgb({r} {g} {b} / {a_srgb:.3f});",
+        f"{name}: oklch({l:.3f} {c:.3f} {h} / {a_oklch:.3f});",
+    )
+
+
+def _add_indent(lines: list[str], level: int = 1) -> list[str]:
+    return [f"{'  ' * level}{l}" for l in lines]
+
+
+def _to_css_block(vars_: list[str], query: str | None = None) -> str:
+    query = (query or "").strip()
+
+    block = [":root {", *_add_indent(vars_), "}"]
+
+    if query:
+        block = [f"{query} {{", *_add_indent(block), "}"]
+
+    return "\n".join(block)
+
+
+@final
+class CSS(Backend):
+    """Generates CSS custom properties from design tokens."""
+
+    @override
+    def codegen(self, target: TargetNode, artifact: ArtifactNode) -> dict[str, bytes]:
+        vars_: dict[TokenMapping, list[str]] = {
+            "light": [],
+            "dark": [],
+            "high_contrast_light": [],
+            "high_contrast_dark": [],
+        }
+
+        color_tokens = (t for t in target.tokens.values() if t.kind == "color")
+
+        for token in color_tokens:
+            for mode, node in token.mapping.items():
+                vars_[mode].extend(v for v in _to_css_vars(token.name, node))
+
+        blocks: list[str] = [
+            _to_css_block(v, _QUERIES[m]) for m, v in vars_.items() if v
+        ]
+
+        css = "\n\n".join(blocks) + "\n"
+
+        sink = MemorySink()
+        sink.write(
+            Path(artifact.path) / f"{artifact.stem or 'tokens'}.css",
+            css.encode(),
+        )
+        return sink.files

forje/cli/main.py

@@ -0,0 +1,125 @@
+import logging
+import time
+from collections.abc import Generator
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from resforge.io import atomic_write
+from rich import print  # noqa: A004
+from rich.logging import RichHandler
+
+from forje import __version__
+from forje.cli.ui import error, success
+from forje.cli.utils import format_elapsed
+from forje.core.driver import Driver
+from forje.core.environment import Environment
+from forje.core.errors import ForjeError
+from forje.core.loader import load_plugins
+from forje.passes.codegen import Codegen
+from forje.passes.color_norm import ColorCanonicalizer
+from forje.passes.validation import PlatformSupport, TargetFilter, TargetValidation
+
+if TYPE_CHECKING:
+    from forje.core.pass_ import Pass
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+
+app = typer.Typer(
+    name="forje",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _find_build_file() -> Path | None:
+    candidate = Path.cwd() / "build.forje"
+    return candidate if candidate.exists() else None
+
+
+def _version_callback(*, value: bool) -> None:
+    if value:
+        print(f"forje {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    _: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Build design system resources from Starlark definitions."""
+
+
+@app.command()
+def build(
+    targets: Annotated[
+        list[str] | None,
+        typer.Option("--target", help="Target to build."),
+    ] = None,
+) -> None:
+    """Build design system resources."""
+    build_file = _find_build_file()
+
+    if build_file is None:
+        error("build.forje not found in current directory.")
+        raise typer.Exit(code=1)
+
+    try:
+        source = build_file.read_text(encoding="utf-8")
+    except OSError as e:
+        error(f"Could not read build.forje: {e.strerror}")
+        raise typer.Exit(code=1) from e
+
+    start = time.perf_counter()
+
+    try:
+        env = Environment(*load_plugins())
+
+        pipeline: list[Pass] = [
+            TargetFilter(targets),
+            TargetValidation(),
+            PlatformSupport(env),
+            ColorCanonicalizer(),
+            *env.passes,
+            Codegen(env),
+        ]
+
+        outputs = Driver(env).build(source, pipeline)
+
+        for _, _, file_path, file_bytes in _walk_files(outputs):
+            with atomic_write(file_path) as f:
+                _ = f.write(file_bytes)
+    except* ForjeError as eg:
+        for e in eg.exceptions:
+            notes = " ".join(getattr(e, "__notes__", []))
+            error(f"{e} {notes}".strip())
+        raise typer.Exit(code=1) from eg
+
+    elapsed = time.perf_counter() - start
+    success(f"Build succeeded in {format_elapsed(elapsed)}")
+
+
+def _walk_files(
+    results: dict[str, dict[str, dict[str, bytes]]],
+) -> Generator[tuple[str, str, str, bytes]]:
+    for target, platforms in results.items():
+        for platform, files in platforms.items():
+            for file_path, file_bytes in files.items():
+                yield target, platform, file_path, file_bytes
+
+
+if __name__ == "__main__":
+    app()

forje/cli/ui.py

@@ -0,0 +1,13 @@
+import typer
+
+__all__ = ["error", "success"]
+
+
+def error(message: str) -> None:
+    """Prints a formatted error message."""
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+
+
+def success(message: str) -> None:
+    """Prints a formatted success message."""
+    typer.secho(message, fg=typer.colors.GREEN)

forje/cli/utils.py

@@ -0,0 +1,12 @@
+__all__ = ["format_elapsed"]
+
+
+def format_elapsed(seconds: float) -> str:
+    """Formats a duration in seconds into a human-readable string."""
+    if seconds >= 60:
+        m = int(seconds // 60)
+        s = int(seconds % 60)
+        return f"{m}m {s}s"
+    if seconds >= 1:
+        return f"{seconds:.1f}s"
+    return f"{seconds:.3f}s"

forje/core/context.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from threading import RLock
+from typing import TYPE_CHECKING, final, override
+
+if TYPE_CHECKING:
+    from forje.ir import IR
+
+__all__ = ["Context", "context_proxy"]
+
+_ctx: ContextVar[Context] = ContextVar("ctx")
+
+
+@final
+@dataclass
+class Context:
+    """Mutable build state for a single Forje evaluation."""
+
+    ir: IR
+    lock: RLock = field(init=False, default_factory=RLock)
+
+
+class _ContextProxy:
+    def __getattr__(self, name: str) -> object:
+        try:
+            return getattr(_ctx.get(), name)  # pyright: ignore[reportAny]
+        except LookupError as e:
+            msg = "No build context active."
+            raise RuntimeError(msg) from e
+
+    @override
+    def __repr__(self) -> str:
+        try:
+            return repr(_ctx.get())
+        except LookupError:
+            return "<empty build context proxy>"
+
+    @classmethod
+    def set_context(cls, ctx: Context) -> Token[Context]:
+        """Sets the current context."""
+        return _ctx.set(ctx)
+
+    @classmethod
+    def reset_context(cls, token: Token[Context]) -> None:
+        """Resets the context to the state before set_context was called."""
+        _ctx.reset(token)
+
+
+context_proxy = _ContextProxy()

forje/core/driver.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from forje.core.frontend import evaluate
+
+if TYPE_CHECKING:
+    from forje.core.environment import Environment
+    from forje.core.pass_ import Pass
+
+__all__ = ["Driver"]
+
+
+@final
+class Driver:
+    """Orchestrates the compilation and artifact generation pipeline."""
+
+    def __init__(self, env: Environment) -> None:
+        self._env = env
+
+    def build(
+        self,
+        source: str,
+        pipeline: list[Pass] | None = None,
+    ) -> dict[str, dict[str, dict[str, bytes]]]:
+        """Evaluates the build script and runs the pass pipeline.
+
+        Args:
+            source: Contents of a build.forje file.
+            pipeline: Ordered list of passes to execute. Defaults to empty.
+
+        Returns:
+            Nested dict keyed by target id -> platform -> file path -> bytes.
+        """
+        ir = evaluate(self._env, source)
+
+        for pass_ in pipeline or []:
+            pass_.run(ir)
+
+        return ir.outputs

forje/core/environment.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import final
+
+from forje.backend import Backend
+from forje.core.pass_ import Pass
+from forje.dsl import Module
+
+__all__ = ["Environment"]
+
+
+@final
+@dataclass(frozen=True)
+class Environment:
+    """Global configuration and available plugins for a Forje build.
+
+    It is intended to be initialized once by the build system and passed into
+    the `Driver` and `Pass` objects.
+    """
+
+    modules: list[Module]
+    passes: list[Pass]
+    backends: dict[str, Backend]

forje/core/errors.py

@@ -0,0 +1,27 @@
+__all__ = [
+    "ForjeError",
+    "ForjeEvalError",
+    "ForjeParseError",
+    "ForjePluginLoadError",
+    "ForjeValidationError",
+]
+
+
+class ForjeError(Exception):
+    """Base class for all Forje errors."""
+
+
+class ForjePluginLoadError(ForjeError):
+    """Error while loading external plugin."""
+
+
+class ForjeParseError(ForjeError):
+    """Starlark parse error in build.forje."""
+
+
+class ForjeEvalError(ForjeError):
+    """Starlark evaluation error in build.forje."""
+
+
+class ForjeValidationError(ForjeError):
+    """Domain constraint violation."""

forje/core/frontend.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import starlark
+
+from forje.core.context import Context, context_proxy
+from forje.core.errors import ForjeEvalError, ForjeParseError
+from forje.ir import IR
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from forje.core.environment import Environment
+    from forje.dsl.module import Module
+
+__all__ = ["evaluate"]
+
+_DIALECT = starlark.Dialect.extended()
+_DIALECT.enable_f_strings = True
+
+_GLOBALS = starlark.Globals.standard().extended_by(
+    [
+        starlark.LibraryExtension.EnumType,
+        starlark.LibraryExtension.Filter,
+        starlark.LibraryExtension.Json,
+        starlark.LibraryExtension.Map,
+        starlark.LibraryExtension.Partial,
+        starlark.LibraryExtension.Pprint,
+        starlark.LibraryExtension.Print,
+        starlark.LibraryExtension.RecordType,
+        starlark.LibraryExtension.RustDecimal,
+        starlark.LibraryExtension.StructType,
+        starlark.LibraryExtension.Typing,
+    ],
+)
+
+
+def _build_module(
+    module: Module,
+    loader: Callable[..., starlark.FrozenModule],
+    into: starlark.Module | None = None,
+) -> starlark.Module | starlark.FrozenModule:
+    mod = starlark.Module() if into is None else into
+
+    for name, value in module.python.items():
+        if callable(value):
+            mod.add_callable(name, value)
+        else:
+            mod[name] = value
+
+    for script in module.starlark:
+        _parse_and_eval(module.name or "build.forje", script, mod, loader)
+
+    return mod.freeze() if into is None else mod
+
+
+def _build_dsl(
+    env: Environment,
+) -> tuple[starlark.Module, Callable[..., starlark.FrozenModule]]:
+
+    modules: dict[str, starlark.FrozenModule] = {}
+    default_module = starlark.Module()
+
+    def loader(name: str) -> starlark.FrozenModule:
+        if name in modules:
+            return modules[name]
+        raise FileNotFoundError
+
+    for module in env.modules:
+        if module.name is None:
+            _ = _build_module(module, loader, into=default_module)
+        else:
+            mod = _build_module(module, loader)
+            if isinstance(mod, starlark.FrozenModule):
+                modules[module.name] = mod
+
+    return default_module, loader
+
+
+def _parse_and_eval(
+    name: str,
+    source: str,
+    module: starlark.Module,
+    loader: Callable[..., starlark.FrozenModule],
+) -> None:
+    try:
+        ast = starlark.parse(name, source, dialect=_DIALECT)
+    except starlark.StarlarkError as e:
+        raise ForjeParseError(str(e)) from e
+
+    try:
+        _ = starlark.eval(module, ast, _GLOBALS, starlark.FileLoader(loader))
+    except starlark.StarlarkError as e:
+        raise ForjeEvalError(str(e)) from e
+
+
+def evaluate(env: Environment, source: str) -> IR:
+    """Evaluate a Forje build script.
+
+    Args:
+        env: The build environment instance containing the standard library
+            and all successfully discovered external modules.
+        source: The contents of a build.forje file as a string.
+
+    Raises:
+        ForjeParseError: If the source contains a Starlark syntax error.
+        ForjeEvalError: If the source fails during Starlark evaluation.
+    """
+    ctx = Context(ir=IR())
+    token = context_proxy.set_context(ctx)
+
+    try:
+        module, loader = _build_dsl(env)
+        _parse_and_eval("build.forje", source, module, loader)
+        return ctx.ir
+    finally:
+        context_proxy.reset_context(token)