rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/project/symbols/symbols.py

@@ -0,0 +1,352 @@
+"""Project-owned schematic symbols: pins, graphics, properties, revisions."""
+
+from ...interfaces.errors import ContractError
+
+#: Component name symbols carry on their entity.
+SYMBOL_COMPONENT = "Symbol"
+
+#: Electrical pin types a symbol pin may carry.
+PIN_TYPES = ("input", "output", "inout", "passive", "power")
+
+
+def _is_int(value):
+    """True for real ints (bools excluded)."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def validate_pin(pin):
+    """Validate one symbol pin record at edit time.
+
+    Args:
+        pin: Pin mapping with name, pin_type, x, and y keys.
+
+    Returns:
+        Normalized pin copy.
+
+    Raises:
+        ContractError: invalid_symbol for any shape violation.
+    """
+    if not isinstance(pin, dict):
+        raise ContractError(
+            "invalid_symbol", f"Symbol pin must be a mapping, got {pin!r}."
+        )
+    for key in pin:
+        if key not in ("name", "pin_type", "x", "y"):
+            raise ContractError(
+                "invalid_symbol", f"Unknown symbol pin key: {key}."
+            )
+    name = pin.get("name")
+    if not isinstance(name, str) or not name:
+        raise ContractError(
+            "invalid_symbol", "Symbol pin name must be non-empty text."
+        )
+    if pin.get("pin_type") not in PIN_TYPES:
+        raise ContractError(
+            "invalid_symbol",
+            f"Symbol pin type must be one of {PIN_TYPES}.",
+        )
+    for axis in ("x", "y"):
+        if not _is_int(pin.get(axis)):
+            raise ContractError(
+                "invalid_symbol",
+                f"Symbol pin {axis} must be an int, got "
+                f"{pin.get(axis)!r}.",
+            )
+    return {
+        "name": name, "pin_type": pin["pin_type"],
+        "x": pin["x"], "y": pin["y"],
+    }
+
+
+def validate_symbol(symbol):
+    """Validate a Symbol component mapping at edit time.
+
+    Args:
+        symbol: Symbol mapping with name, pins, graphics,
+            properties, and revision keys.
+
+    Returns:
+        Normalized Symbol copy.
+
+    Raises:
+        ContractError: invalid_symbol for any shape violation.
+    """
+    if not isinstance(symbol, dict):
+        raise ContractError(
+            "invalid_symbol", f"Symbol must be a mapping, got {symbol!r}."
+        )
+    for key in symbol:
+        if key not in ("name", "pins", "graphics", "properties",
+                       "revision"):
+            raise ContractError(
+                "invalid_symbol", f"Unknown Symbol key: {key}."
+            )
+    name = symbol.get("name")
+    if not isinstance(name, str) or not name:
+        raise ContractError(
+            "invalid_symbol", "Symbol name must be non-empty text."
+        )
+    pins = symbol.get("pins", [])
+    if not isinstance(pins, list):
+        raise ContractError(
+            "invalid_symbol", "Symbol pins must be a list."
+        )
+    clean_pins = [validate_pin(pin) for pin in pins]
+    seen = [pin["name"] for pin in clean_pins]
+    if len(set(seen)) != len(seen):
+        raise ContractError(
+            "invalid_symbol", "Symbol pin names must be distinct."
+        )
+    graphics = symbol.get("graphics", [])
+    if not isinstance(graphics, list) or not all(
+        isinstance(item, dict) and isinstance(item.get("kind"), str)
+        for item in graphics
+    ):
+        raise ContractError(
+            "invalid_symbol",
+            "Symbol graphics must be a list of {kind, ...} items.",
+        )
+    properties = symbol.get("properties", {})
+    if not isinstance(properties, dict) or not all(
+        isinstance(key, str) and isinstance(val, str)
+        for key, val in properties.items()
+    ):
+        raise ContractError(
+            "invalid_symbol",
+            "Symbol properties must map text to text.",
+        )
+    revision = symbol.get("revision", 1)
+    if not _is_int(revision) or revision < 1:
+        raise ContractError(
+            "invalid_symbol", "Symbol revision must be a positive int."
+        )
+    return {
+        "name": name, "pins": clean_pins,
+        "graphics": [dict(item) for item in graphics],
+        "properties": dict(properties), "revision": revision,
+    }
+
+
+def _read_symbol(store, symbol_id):
+    """Return the normalized Symbol for one entity id."""
+    try:
+        raw = store.get_component(symbol_id, SYMBOL_COMPONENT)
+    except LookupError:
+        raise ContractError(
+            "unknown_symbol",
+            f"No such symbol entity: {symbol_id!r}.",
+        ) from None
+    value = validate_symbol(raw)
+    value["id"] = symbol_id
+    return value
+
+
+def _all_symbols(store):
+    """List every symbol mapping, name-sorted."""
+    found = []
+    for entity in store.entities_with(SYMBOL_COMPONENT):
+        try:
+            found.append(_read_symbol(store, entity))
+        except ContractError:
+            continue
+    found.sort(key=lambda item: item["name"])
+    return found
+
+
+def _check_name_free(store, name, except_id=None):
+    """Fail loudly when a symbol name is already taken."""
+    for item in _all_symbols(store):
+        if item["name"] == name and item["id"] != except_id:
+            raise ContractError(
+                "symbol_exists", f"Symbol already exists: {name!r}."
+            )
+
+
+def create_symbol(store, actor, name, pins, graphics=None,
+                  properties=None):
+    """Create one project-owned symbol definition.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        name: Unique symbol name.
+        pins: Pin records with name, pin_type, x, and y.
+        graphics: Editable graphics items ({kind, ...}).
+        properties: Text-to-text symbol properties.
+
+    Returns:
+        Receipt with op, actor, revision, symbol id, and events.
+
+    Raises:
+        ContractError: invalid_symbol for a malformed symbol,
+            symbol_exists for a duplicate name.
+    """
+    value = validate_symbol({
+        "name": name, "pins": pins, "graphics": graphics or [],
+        "properties": properties or {}, "revision": 1,
+    })
+    _check_name_free(store, value["name"])
+    made = store.create_entity(actor, f"create_symbol {value['name']}")
+    store.attach_component(
+        actor, made["id"], SYMBOL_COMPONENT, value,
+        f"create_symbol {value['name']}",
+    )
+    return {
+        "op": "create_symbol", "actor": actor,
+        "revision": made["revision"], "symbol": made["id"],
+        "events": [
+            {"event": "entity_created", "entity": made["id"]},
+            {"event": "component_changed", "entity": made["id"],
+             "component": SYMBOL_COMPONENT},
+        ],
+    }
+
+
+def copy_symbol(store, actor, symbol_id, name):
+    """Copy one symbol definition under a new name at revision 1.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        symbol_id: Source symbol entity id.
+        name: New unique symbol name.
+
+    Returns:
+        Receipt with op, actor, revision, symbol id, and events.
+
+    Raises:
+        ContractError: unknown_symbol for a missing source,
+            symbol_exists for a duplicate name.
+    """
+    source = _read_symbol(store, symbol_id)
+    return create_symbol(
+        store, actor, name, source["pins"],
+        graphics=source["graphics"], properties=source["properties"],
+    )
+
+
+def rename_symbol(store, actor, symbol_id, name):
+    """Rename one symbol; refuse while instances reference it.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        symbol_id: Symbol entity id to rename.
+        name: New unique symbol name.
+
+    Returns:
+        Receipt with op, actor, revision, symbol id, and name.
+
+    Raises:
+        ContractError: unknown_symbol for a missing symbol,
+            symbol_exists for a duplicate name, symbol_in_use
+            when instances reference the old name.
+    """
+    value = _read_symbol(store, symbol_id)
+    if not isinstance(name, str) or not name:
+        raise ContractError(
+            "invalid_symbol", "Symbol name must be non-empty text."
+        )
+    _check_name_free(store, name, except_id=symbol_id)
+    for entity in store.entities_with("Instance"):
+        try:
+            instance = store.get_component(entity, "Instance")
+        except LookupError:
+            continue
+        if (
+            isinstance(instance, dict)
+            and instance.get("symbol") == value["name"]
+        ):
+            raise ContractError(
+                "symbol_in_use",
+                f"Symbol {value['name']!r} is placed on instance "
+                f"{entity!r}.",
+            )
+    clean = validate_symbol({
+        "name": name, "pins": value["pins"],
+        "graphics": value["graphics"],
+        "properties": value["properties"],
+        "revision": value["revision"],
+    })
+    changed = store.set_component(
+        actor, symbol_id, SYMBOL_COMPONENT, clean,
+        f"rename_symbol {name}",
+    )
+    return {
+        "op": "rename_symbol", "actor": actor,
+        "revision": changed["revision"], "symbol": symbol_id,
+        "name": name, "events": [],
+    }
+
+
+def revise_symbol(store, actor, symbol_id, pins=None, graphics=None,
+                  properties=None):
+    """Revise one symbol definition, bumping its revision.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        symbol_id: Symbol entity id to revise.
+        pins: Replacement pin records, or None to keep.
+        graphics: Replacement graphics items, or None to keep.
+        properties: Replacement properties, or None to keep.
+
+    Returns:
+        Receipt with op, actor, revision, symbol id, and the
+            new symbol revision.
+
+    Raises:
+        ContractError: unknown_symbol for a missing symbol,
+            invalid_symbol for a malformed revision.
+    """
+    value = _read_symbol(store, symbol_id)
+    clean = validate_symbol({
+        "name": value["name"],
+        "pins": pins if pins is not None else value["pins"],
+        "graphics": (
+            graphics if graphics is not None else value["graphics"]
+        ),
+        "properties": (
+            properties if properties is not None
+            else value["properties"]
+        ),
+        "revision": value["revision"] + 1,
+    })
+    changed = store.set_component(
+        actor, symbol_id, SYMBOL_COMPONENT, clean,
+        f"revise_symbol {value['name']}",
+    )
+    return {
+        "op": "revise_symbol", "actor": actor,
+        "revision": changed["revision"], "symbol": symbol_id,
+        "symbol_revision": clean["revision"], "events": [],
+    }
+
+
+def get_symbol(store, symbol_id):
+    """Read one symbol definition by entity id.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        symbol_id: Symbol entity id to read.
+
+    Returns:
+        Symbol mapping with id, name, pins, graphics,
+            properties, and revision.
+
+    Raises:
+        ContractError: unknown_symbol for a missing symbol.
+    """
+    return _read_symbol(store, symbol_id)
+
+
+def list_symbols(store):
+    """List every symbol definition, name-sorted.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+
+    Returns:
+        Symbol mappings with ids, name-sorted.
+    """
+    return _all_symbols(store)

rocket_engine/project/templates/__init__.py

@@ -0,0 +1,303 @@
+"""Runtime-modifiable project templates (TEMPLATE-RUNTIME).
+
+The engine ships one versioned base shape; PDKs and power users
+extend it with extra named areas and custom config without forking
+the engine. Extensions land only where allowed: unknown top-level
+keys fail loudly naming the key, area entries admit exactly name
+plus label, and the `engine.` config namespace stays reserved for
+the engine. Older templates migrate through registered one-step
+links; newer-than-known templates refuse with future_format and
+unlinked steps name their missing_migration.
+"""
+
+from __future__ import annotations
+
+import copy
+import re
+
+from ruamel.yaml import YAML
+
+from .errors import TemplateError
+
+TEMPLATE_VERSION = 1
+
+BASE_TEMPLATE_ID = "default"
+
+_TOP_LEVEL_KEYS = frozenset(
+    {"template_version", "id", "base", "description", "areas", "config"}
+)
+
+_AREA_KEYS = frozenset({"name", "label"})
+
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]*$")
+
+_RESERVED_CONFIG_PREFIX = "engine."
+
+_SCALARS = (str, int, float, bool)
+
+_MIGRATIONS = {}
+
+
+def register_migration(old, new, fn):
+    """Register one chained migration link between template versions.
+
+    Links chain one step at a time (new must be old + 1); migrate
+    walks them from the template version to the head. Registration
+    is additive: engine upgrades add links, never rewrite old ones.
+
+    Args:
+        old: Source template_version this link migrates from.
+        new: Target template_version (must be old + 1).
+        fn: Callable taking the old mapping and returning the new
+            mapping.
+
+    Raises:
+        TemplateError: invalid_migration for a skipped version
+            step or a conflicting link, invalid_template when fn
+            is not callable.
+    """
+    if not callable(fn):
+        raise TemplateError(
+            "invalid_template",
+            f"Template migrator {old}->{new} is not callable.",
+        )
+    if new != old + 1:
+        raise TemplateError(
+            "invalid_migration",
+            f"Template migration must step one version, got {old}->{new}.",
+        )
+    if old in _MIGRATIONS:
+        raise TemplateError(
+            "invalid_migration",
+            f"Template already migrates from version {old}.",
+        )
+    _MIGRATIONS[old] = (new, fn)
+
+
+def clear_migrations():
+    """Drop registered migration links (a test seam, not a feature).
+
+    Returns:
+        Count of dropped links.
+    """
+    count = len(_MIGRATIONS)
+    _MIGRATIONS.clear()
+    return count
+
+
+def _check_id(value, what):
+    if not isinstance(value, str) or not _SLUG_RE.match(value):
+        raise TemplateError(
+            "invalid_template", f"Template {what} must be a slug: {value!r}."
+        )
+
+
+def _check_areas(areas):
+    if not isinstance(areas, list):
+        raise TemplateError(
+            "invalid_template",
+            f"Template areas must be a list: {areas!r}.",
+        )
+    for index, area in enumerate(areas):
+        if not isinstance(area, dict):
+            raise TemplateError(
+                "invalid_template",
+                f"Template areas[{index}] must be a mapping: {area!r}.",
+            )
+        unknown = set(area) - _AREA_KEYS
+        if unknown:
+            raise TemplateError(
+                "invalid_template",
+                f"Template areas[{index}] allows only "
+                f"{sorted(_AREA_KEYS)}, got: {sorted(unknown)}.",
+            )
+        name = area.get("name")
+        if not isinstance(name, str) or not _SLUG_RE.match(name):
+            raise TemplateError(
+                "invalid_template",
+                f"Template areas[{index}] needs a slug name: {area!r}.",
+            )
+        label = area.get("label")
+        if label is not None and not isinstance(label, str):
+            raise TemplateError(
+                "invalid_template",
+                f"Template areas[{index}] label must be text: {area!r}.",
+            )
+
+
+def _check_config(config):
+    if not isinstance(config, dict):
+        raise TemplateError(
+            "invalid_template",
+            f"Template config must be a mapping: {config!r}.",
+        )
+    for key, value in config.items():
+        if not isinstance(key, str) or not key:
+            raise TemplateError(
+                "invalid_template",
+                f"Template config keys must be text: {key!r}.",
+            )
+        if key.startswith(_RESERVED_CONFIG_PREFIX):
+            raise TemplateError(
+                "invalid_template",
+                f"Template config key {key!r} is engine-reserved "
+                f"({_RESERVED_CONFIG_PREFIX}* namespace).",
+            )
+        if not isinstance(value, _SCALARS):
+            raise TemplateError(
+                "invalid_template",
+                f"Template config {key!r} must be a scalar: {value!r}.",
+            )
+
+
+def validate_template(data):
+    """Check one head-version template mapping against the base.
+
+    Extensions land only where allowed: the fixed top-level key
+    set, name-plus-label area entries, and scalar config outside
+    the engine-reserved namespace.
+
+    Args:
+        data: Template mapping already at TEMPLATE_VERSION.
+
+    Returns:
+        Validated deep copy of the template mapping.
+
+    Raises:
+        TemplateError: invalid_template for a non-mapping,
+            unknown key, bad id/base, or malformed area/config.
+    """
+    if not isinstance(data, dict):
+        raise TemplateError(
+            "invalid_template",
+            f"Template must be a mapping: {data!r}.",
+        )
+    unknown = set(data) - _TOP_LEVEL_KEYS
+    if unknown:
+        raise TemplateError(
+            "invalid_template",
+            f"Template allows only {sorted(_TOP_LEVEL_KEYS)}, "
+            f"got: {sorted(unknown)}.",
+        )
+    _check_id(data.get("id"), "id")
+    base = data.get("base")
+    if not isinstance(base, str) or not base:
+        raise TemplateError(
+            "invalid_template",
+            f"Template base must name its base template: {base!r}.",
+        )
+    description = data.get("description")
+    if description is not None and not isinstance(description, str):
+        raise TemplateError(
+            "invalid_template",
+            f"Template description must be text: {description!r}.",
+        )
+    _check_areas(data.get("areas", []))
+    _check_config(data.get("config", {}))
+    return copy.deepcopy(data)
+
+
+def migrate_template(data):
+    """Migrate one template mapping to the known head version.
+
+    Walks registered one-step links from the mapping's version
+    upward; each step's output re-enters the chain so multi-step
+    upgrades compose. Migration is pure (no I/O).
+
+    Args:
+        data: Template mapping at some older template_version.
+
+    Returns:
+        Migrated mapping stamped at TEMPLATE_VERSION.
+
+    Raises:
+        TemplateError: invalid_template for a non-mapping or a
+            non-integer version, future_format for a mapping
+            newer than the head, missing_migration for a version
+            step with no registered link, invalid_migration when
+            a migrator returns a non-mapping or raises.
+    """
+    if not isinstance(data, dict):
+        raise TemplateError(
+            "invalid_template",
+            f"Template must be a mapping: {data!r}.",
+        )
+    version = data.get("template_version")
+    if isinstance(version, bool) or not isinstance(version, int):
+        raise TemplateError(
+            "invalid_template",
+            f"Template version must be an integer: {version!r}.",
+        )
+    if version > TEMPLATE_VERSION:
+        raise TemplateError(
+            "future_format",
+            f"Template is at version {version}; "
+            f"this engine knows {TEMPLATE_VERSION}.",
+        )
+    current = copy.deepcopy(data)
+    while version < TEMPLATE_VERSION:
+        link = _MIGRATIONS.get(version)
+        if link is None:
+            raise TemplateError(
+                "missing_migration",
+                f"No template migration from version {version}.",
+            )
+        new, fn = link
+        try:
+            current = fn(current)
+        except TemplateError:
+            raise
+        except Exception as exc:
+            raise TemplateError(
+                "invalid_migration",
+                f"Template migrator {version}->{new} failed: {exc}.",
+            ) from exc
+        if not isinstance(current, dict):
+            raise TemplateError(
+                "invalid_migration",
+                f"Template migrator {version}->{new} "
+                "did not return a mapping.",
+            )
+        current["template_version"] = new
+        version = new
+    return current
+
+
+def load_template(data):
+    """Migrate then validate one custom template mapping.
+
+    Args:
+        data: Custom template mapping at any known version.
+
+    Returns:
+        Validated template mapping at TEMPLATE_VERSION.
+
+    Raises:
+        TemplateError: future_format, missing_migration,
+            invalid_migration, or invalid_template naming the
+            violating key, area, or config entry.
+    """
+    return validate_template(migrate_template(data))
+
+
+def loads_template(text):
+    """Parse YAML text then migrate and validate one template.
+
+    Args:
+        text: YAML text of a custom template document.
+
+    Returns:
+        Validated template mapping at TEMPLATE_VERSION.
+
+    Raises:
+        TemplateError: invalid_template when the text is not a
+            YAML mapping, plus every load_template verdict.
+    """
+    try:
+        data = YAML(typ="safe").load(text)
+    except Exception as exc:
+        raise TemplateError(
+            "invalid_template",
+            f"Template is not YAML: {exc}.",
+        ) from exc
+    return load_template(data)

rocket_engine/project/templates/errors.py

@@ -0,0 +1,25 @@
+"""Custom project template errors (TEMPLATE-RUNTIME)."""
+
+from __future__ import annotations
+
+
+class TemplateError(Exception):
+    """Typed custom-template failure; `code` names the verdict.
+
+    Codes: invalid_template for a non-mapping, bad YAML, unknown
+    key, or malformed area/config entry; future_format for a
+    template newer than this engine; missing_migration for a
+    version step with no registered link; invalid_migration for
+    a skipped step, a conflicting link, or a migrator that does
+    not return a mapping.
+    """
+
+    def __init__(self, code, message):
+        """Bind one machine-readable verdict code to its message.
+
+        Args:
+            code: Verdict code naming the failure.
+            message: Human-readable detail naming the violation.
+        """
+        super().__init__(message)
+        self.code = code