forje 0.1.0__tar.gz

forje-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Forje build files
+*.forje
+
+# macOS
+.DS_Store

forje-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: forje
+Version: 0.1.0
+Summary: The build system for your design system
+Project-URL: Homepage, https://kipila.dev
+Project-URL: Repository, https://github.com/kipila-dev/forje
+Author-email: Kipila Ltd <hello@kipila.dev>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: coloraide
+Requires-Dist: pydantic
+Requires-Dist: resforge
+Requires-Dist: starlark-pyo3
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# Forje
+
+For full documentation, see the
+[main repository README](https://github.com/kipila-dev/forje/blob/main/README.md).

forje-0.1.0/README.md

@@ -0,0 +1,4 @@
+# Forje
+
+For full documentation, see the
+[main repository README](https://github.com/kipila-dev/forje/blob/main/README.md).

forje-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forje"
+dynamic = ["version"]
+description = "The build system for your design system"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Kipila Ltd", email = "hello@kipila.dev" }]
+dependencies = ["coloraide", "pydantic", "resforge", "starlark-pyo3", "typer"]
+
+[project.urls]
+Homepage = "https://kipila.dev"
+Repository = "https://github.com/kipila-dev/forje"
+
+[project.scripts]
+forje = "forje.cli.main:app"
+
+[project.entry-points."forje.dsl"]
+core = "forje.dsl.core:module"
+stdlib = "forje.dsl.stdlib:module"
+wcag = "forje.wcag.dsl:module"
+
+[project.entry-points."forje.pass"]
+wcag = "forje.wcag.passes:WCAGValidation"
+
+[project.entry-points."forje.backend"]
+android = "forje.backend.android:Android"
+apple = "forje.backend.apple:Apple"
+css = "forje.backend.css:CSS"
+
+[tool.hatch.version]
+path = "src/forje/__init__.py"
+
+[tool.uv.sources]
+resforge = { workspace = true }

forje-0.1.0/src/forje/__init__.py

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

forje-0.1.0/src/forje/backend/__init__.py

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

forje-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"