metaobjects 0.9.0__py3-none-any.whl

metaobjects/codegen/fr010_field_mapping.py

@@ -0,0 +1,220 @@
+"""Shared field-kind mapping for the FR-010 codegen emitters (``extract_schema_emitter``
++ ``output_format_spec_emitter``).
+
+Maps a metadata field subtype onto the render engine's ``FieldKind`` member, the
+idiomatic ``X | None`` Python type used by the extract mirror dataclass, and the
+``extract_map.as_*`` accessor that reads it from the forgiving outcome map.
+
+Mirrors the C# ``Fr010FieldMapping`` and the Java ``ExtractSchemaEmitter`` ordering.
+Bounded scope (parity with Java / Kotlin / C#): scalar / enum / scalar-array. Nested
+object + array-of-enum are deferred (see ``render/extract/KNOWN_GAPS.md``).
+
+Python has a single ``int`` type, so the ``LONG`` and ``CURRENCY`` subtypes map to the
+``LONG`` ``FieldKind`` (and ``extract_map.as_long`` — identical to ``as_int``), keeping
+the cross-port ``FieldKind`` vocabulary intact even though the emitted accessor is the
+same. The mirror annotation collapses ``INT``/``LONG`` to ``int`` (one numeric int type).
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from metaobjects.meta.core.field import field_constants as fc
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.meta.template.template_constants import TEMPLATE_ATTR_XML_TEXT
+from metaobjects.shared.base_types import TYPE_FIELD
+from metaobjects.shared.structural import KEY_IS_ARRAY
+
+
+def fields(vo: MetaData) -> list[MetaData]:
+    """The field children of a payload value-object, in declaration order
+    (effective children — own + inherited via ``extends``)."""
+    return [c for c in vo.children() if c.type == TYPE_FIELD]
+
+
+def is_array(field: MetaData) -> bool:
+    """Array-ness from either form: the node property (programmatic build) or the
+    ``@isArray`` attr (how metadata loads from JSON)."""
+    return bool(field.is_array) or field.attr(KEY_IS_ARRAY) is True
+
+
+def is_required(field: MetaData) -> bool:
+    """``@required`` — accepts a bool ``True`` or the string ``"true"``."""
+    v = field.attr(fc.FIELD_ATTR_REQUIRED)
+    if v is True:
+        return True
+    return isinstance(v, str) and v.lower() == "true"
+
+
+def xml_text(field: MetaData) -> bool:
+    """``@xmlText`` — the XML text-content extract marker (accepts a bool ``True`` or the
+    string ``"true"``). When set, codegen bakes a ``FieldSpec.text_content_field(...)``.
+    Mirrors the TS ``xmlText(field)`` helper."""
+    v = field.attr(TEMPLATE_ATTR_XML_TEXT)
+    if v is True:
+        return True
+    return isinstance(v, str) and v.lower() == "true"
+
+
+def enum_values(field: MetaData) -> list[str]:
+    """The string members of an enum field's ``@values`` attr (empty when absent)."""
+    v = field.attr(fc.FIELD_ATTR_VALUES)
+    if isinstance(v, (list, tuple)):
+        return [str(x) for x in v]
+    return []
+
+
+def _own_attr_string(node: MetaData, name: str) -> str | None:
+    """The own (locally declared) string value of attr *name*, or ``None``."""
+    v = node.attr(name)
+    return v if isinstance(v, str) else None
+
+
+def coerce_default(field: MetaData) -> str | None:
+    """FR-011: the enum field's own ``@coerceDefault`` member, or ``None``."""
+    return _own_attr_string(field, fc.FIELD_ATTR_COERCE_DEFAULT)
+
+
+def default_value(field: MetaData) -> str | None:
+    """FR-011: the enum field's own ``@default`` absent-fill member, or ``None``."""
+    return _own_attr_string(field, fc.FIELD_ATTR_DEFAULT)
+
+
+def resolve_normalize(field: MetaData, owner: MetaData | None) -> str:
+    """FR-011: resolve the enum normalization mode — field-level ``@normalize``, else the
+    owning ``object.value``'s ``@normalize`` (the per-object default), else the global
+    default (``"strip"``). Mirrors the Java/Kotlin/C#/TS ``resolveNormalize``."""
+    field_mode = _own_attr_string(field, fc.FIELD_ATTR_NORMALIZE)
+    if field_mode is not None:
+        return field_mode
+    if owner is not None:
+        owner_mode = _own_attr_string(owner, fc.FIELD_ATTR_NORMALIZE)
+        if owner_mode is not None:
+            return owner_mode
+    return fc.NORMALIZE_DEFAULT
+
+
+def scalar_kind(sub_type: str) -> str | None:
+    """The render-engine ``FieldKind`` member name for a scalar field subtype, or
+    ``None`` if the subtype is non-scalar (enum / object)."""
+    if sub_type in (
+        fc.FIELD_SUBTYPE_STRING,
+        fc.FIELD_SUBTYPE_DATE,
+        fc.FIELD_SUBTYPE_TIME,
+        fc.FIELD_SUBTYPE_TIMESTAMP,
+    ):
+        return "STRING"
+    if sub_type == fc.FIELD_SUBTYPE_INT:
+        return "INT"
+    if sub_type in (fc.FIELD_SUBTYPE_LONG, fc.FIELD_SUBTYPE_CURRENCY):
+        return "LONG"
+    if sub_type in (
+        fc.FIELD_SUBTYPE_DOUBLE,
+        fc.FIELD_SUBTYPE_FLOAT,
+        fc.FIELD_SUBTYPE_DECIMAL,
+    ):
+        return "DOUBLE"
+    if sub_type == fc.FIELD_SUBTYPE_BOOLEAN:
+        return "BOOLEAN"
+    return None
+
+
+def mirror_type(field: MetaData) -> str:
+    """The ``X | None`` Python annotation for a field in the extract mirror dataclass.
+
+    A extracted array can contain null elements where individual items were lost, so
+    the array type is ``list[str | None] | None`` (matches ``extract_map.as_string_list``).
+    """
+    # Nested object (single OR array): the self-contained path defers to a typed null;
+    # the runtime-delegating path overrides this with the nested mirror type. Checked
+    # BEFORE the generic is_array branch so an array-of-objects is NOT mistyped as a
+    # string array. Mirrors the Java/TS fix.
+    if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
+        return "object | None"  # nested deferred (self-contained path)
+    if is_array(field):
+        return "list[str | None] | None"
+    if field.sub_type == fc.FIELD_SUBTYPE_ENUM:
+        return "str | None"  # enum is string-backed
+    kind = scalar_kind(field.sub_type)
+    if kind in ("INT", "LONG"):
+        return "int | None"
+    if kind == "DOUBLE":
+        return "float | None"
+    if kind == "BOOLEAN":
+        return "bool | None"
+    return "str | None"
+
+
+def extract_map_helper(field: MetaData) -> str | None:
+    """The ``extract_map`` accessor a field reads through, or ``None``
+    (object/deferred fields read no helper).
+
+    Single source of the field → accessor decision; ``extract_map_call`` builds
+    the ``as_*(d, "name")`` call on top of this."""
+    # Nested object (single OR array) → no helper in the self-contained path. Checked
+    # BEFORE is_array so an array-of-objects is NOT read via as_string_list. Mirrors the
+    # Java/TS fix.
+    if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
+        return None
+    if is_array(field):
+        return "as_string_list"
+    if field.sub_type == fc.FIELD_SUBTYPE_ENUM:
+        return "as_string"
+    return {
+        "INT": "as_int",
+        "LONG": "as_long",
+        "DOUBLE": "as_double",
+        "BOOLEAN": "as_bool",
+    }.get(scalar_kind(field.sub_type) or "", "as_string")
+
+
+def extract_map_call(field: MetaData) -> str:
+    """The ``as_*(d, "name")`` call that reads this field from the forgiving map ``d``.
+
+    The helpers are imported by name into the generated module (see
+    ``extract_schema_emitter.extract_map_imports``)."""
+    helper = extract_map_helper(field)
+    if helper is None:
+        # Nested object: the self-contained initializer leaves it None (the
+        # runtime-delegating path populates it). Bare ``None`` — no trailing inline
+        # comment: this expr is joined into a ``Name(field=..., …)`` call-args list.
+        return "None"
+    return f'{helper}(d, "{field.name}")'
+
+
+def py_string_literal(value: str) -> str:
+    """A safe Python double-quoted string literal for embedding free text
+    (``@example`` / ``@instruction`` / ``@enumDoc`` values) into emitted source.
+
+    Uses ``json.dumps`` — a JSON string is a valid Python string literal and escapes
+    backslashes / quotes / control chars correctly (NOT naive quoting)."""
+    import json
+
+    return json.dumps(value, ensure_ascii=False)
+
+
+def string_list_literal(values: Iterable[str]) -> str:
+    """A Python ``["a", "b"]`` list literal for enum members."""
+    return "[" + ", ".join(py_string_literal(v) for v in values) + "]"
+
+
+def properties_map_literal(attr: object) -> str:
+    """A Python ``{"k": "v", …}`` dict literal for a properties-shaped attr
+    (``@enumAlias`` / ``@enumDoc``), or ``"None"`` when absent/empty.
+
+    Null values are dropped; keys are sorted to match the canonical-serializer
+    properties sort (deterministic output)."""
+    if not isinstance(attr, dict):
+        return "None"
+    entries = [
+        (k, v)
+        for k, v in attr.items()
+        if v is not None
+    ]
+    if not entries:
+        return "None"
+    entries.sort(key=lambda kv: str(kv[0]))
+    parts = [
+        f"{py_string_literal(str(k))}: {py_string_literal(str(v))}"
+        for k, v in entries
+    ]
+    return "{" + ", ".join(parts) + "}"

metaobjects/codegen/generator.py

@@ -0,0 +1,62 @@
+"""Codegen plugin engine — Generator protocol + per-entity/once-per-run helpers.
+Mirrors server/typescript/packages/codegen-ts/src/generator.ts."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.meta_data import MetaData
+from .config import GenConfig
+
+
+@dataclass
+class EmittedFile:
+    path: str            # relative to GenConfig.out_dir
+    content: str         # final, formatted Python source
+    generated_by: str = ""  # set by the runner from Generator.name
+
+
+@dataclass
+class GenContext:
+    entities: list[MetaObject]
+    loaded_root: MetaData | None
+    matches: Callable[[MetaObject], bool]
+    config: GenConfig
+    warn: Callable[[str], None]
+
+
+class Generator(Protocol):
+    name: str
+
+    def generate(self, ctx: GenContext) -> list[EmittedFile]: ...
+
+
+def per_entity(
+    fn: Callable[[MetaObject, GenContext], "EmittedFile | list[EmittedFile]"],
+) -> Callable[[GenContext], list[EmittedFile]]:
+    """One-file-per-entity convenience; selects via ctx.matches."""
+
+    def run(ctx: GenContext) -> list[EmittedFile]:
+        out: list[EmittedFile] = []
+        for e in ctx.entities:
+            if not ctx.matches(e):
+                continue
+            r = fn(e, ctx)
+            out.extend(r if isinstance(r, list) else [r])
+        return out
+
+    return run
+
+
+def once_per_run(
+    fn: Callable[[list[MetaObject], GenContext], "EmittedFile | list[EmittedFile]"],
+) -> Callable[[GenContext], list[EmittedFile]]:
+    """Called once with all matching entities (barrels / cross-entity files)."""
+
+    def run(ctx: GenContext) -> list[EmittedFile]:
+        matched = [e for e in ctx.entities if ctx.matches(e)]
+        r = fn(matched, ctx)
+        return r if isinstance(r, list) else [r]
+
+    return run

metaobjects/codegen/generator_registry.py

@@ -0,0 +1,163 @@
+"""ADR-0021 D3 — stable-name generator registry (Python port).
+
+Generators are identified by a STABLE string id (e.g. ``entity``, ``routes``,
+``render-helper``) rather than by a language-specific factory import. The id is
+the cross-port contract: the same logical generator carries the same stable name
+in every port. This module is the discoverability + identity surface behind
+``metaobjects gen --list`` and the ``--generators a,b`` selection path.
+
+It is ADDITIVE. The default suite in ``cli.py`` (``_default_generators``) and the
+``run_gen(..., generators=[...])`` factory-array path keep working unchanged — the
+registry powers ``--list`` and stable identity; it does not replace those paths.
+
+The registry's name set is conformance-tested for SET EQUALITY against the Python
+slice of the canonical manifest
+(``fixtures/generator-registry-conformance/registry.json``): exactly the manifest
+entries whose ``ports`` array includes ``python``. All Python entries are
+``tier: native``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from metaobjects.codegen.generator import Generator
+from metaobjects.codegen.generators.entity_model import entity_model
+from metaobjects.codegen.generators.extractor_generator import extractor_generator
+from metaobjects.codegen.generators.filter_allowlist_generator import (
+    filter_allowlist_generator,
+)
+from metaobjects.codegen.generators.output_parser_generator import (
+    output_parser_generator,
+)
+from metaobjects.codegen.generators.output_prompt_generator import (
+    output_prompt_generator,
+)
+from metaobjects.codegen.generators.payload_vo_generator import payload_vo_generator
+from metaobjects.codegen.generators.render_helper_generator import (
+    render_helper_generator,
+)
+from metaobjects.codegen.generators.router_generator import router_generator
+from metaobjects.codegen.generators.template_generator import template_generator
+from metaobjects.codegen.generators.trace_helper_generator import trace_helper_generator
+from metaobjects.render.verify import InMemoryProvider
+
+GeneratorTier = str  # "native" | "neutral"
+
+
+@dataclass(frozen=True)
+class GeneratorEntry:
+    """A registry entry: stable name + one-line description + tier + factory."""
+
+    #: Stable, cross-port-consistent id. Equals the registry map key.
+    name: str
+    #: One-line (no newline) human description for ``--list``.
+    description: str
+    #: "native" = recommended ``metaobjects gen`` suite; "neutral" = ``meta docs``-owned.
+    tier: GeneratorTier
+    #: Constructs the generator with sensible defaults. Calling it must not throw.
+    factory: Callable[[], Generator]
+
+
+def _template_primitive() -> Generator:
+    """A no-op default for the ``template`` PRIMITIVE generator.
+
+    ``template_generator`` requires caller-supplied ``template`` / ``walk`` /
+    ``provider`` (it is not a zero-config per-entity emitter). For registry
+    identity + ``--list`` we expose a default that constructs a valid Generator
+    without throwing and walks to zero outputs; real use passes opts via the
+    factory-array config path. Mirrors the TS ``templatePrimitive()``.
+    """
+    return template_generator(
+        name="template",
+        template="",
+        walk=lambda _root: [],
+        provider=InMemoryProvider(),
+    )
+
+
+def _render_helper_default() -> Generator:
+    """Construct ``render-helper`` with a default ``template_root``.
+
+    The factory ctor only requires ``template_root`` to be non-empty (it builds a
+    ``FilesystemProvider`` lazily; no disk access at construction). Real use passes
+    the caller's on-disk template root via the factory-array config path; this
+    default exists only so registry identity + ``--list`` construct without throwing.
+    """
+    return render_helper_generator(template_root="templates")
+
+
+#: Stable name -> GeneratorEntry. The 10 native generators whose manifest `ports`
+#: include `python` (ADR-0021 D3). Set-equality conformance-tested vs the manifest.
+GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
+    "entity": GeneratorEntry(
+        name="entity",
+        description="Per-entity model/class — the entity module (table-backed or value object).",
+        tier="native",
+        factory=entity_model,
+    ),
+    "routes": GeneratorEntry(
+        name="routes",
+        description="Per-entity REST endpoint surface (controllers / routes / router).",
+        tier="native",
+        factory=router_generator,
+    ),
+    "output-parser": GeneratorEntry(
+        name="output-parser",
+        description="Per-template tolerant output parser (recover-on-receipt).",
+        tier="native",
+        factory=output_parser_generator,
+    ),
+    "output-prompt": GeneratorEntry(
+        name="output-prompt",
+        description="Per-template output-format prompt fragment generator.",
+        tier="native",
+        factory=output_prompt_generator,
+    ),
+    "render-helper": GeneratorEntry(
+        name="render-helper",
+        description="Per-template.output render helper (document/email typed wrappers).",
+        tier="native",
+        factory=_render_helper_default,
+    ),
+    "extractor": GeneratorEntry(
+        name="extractor",
+        description="Per-template strict typed extract<Name> helper (strict payload extraction).",
+        tier="native",
+        factory=extractor_generator,
+    ),
+    "template": GeneratorEntry(
+        name="template",
+        description="Generic Mustache template primitive (walk + template -> files).",
+        tier="native",
+        factory=_template_primitive,
+    ),
+    "filter-allowlist": GeneratorEntry(
+        name="filter-allowlist",
+        description="Per-entity REST filter allowlist (queryable-field guard).",
+        tier="native",
+        factory=filter_allowlist_generator,
+    ),
+    "payload": GeneratorEntry(
+        name="payload",
+        description="Per-template payload value object (the strict payload type).",
+        tier="native",
+        factory=payload_vo_generator,
+    ),
+    "trace-helper": GeneratorEntry(
+        name="trace-helper",
+        description="Per-entity typed record<Entity> LLM-trace helper (extract + buildLlmCallRow + persist).",
+        tier="native",
+        factory=trace_helper_generator,
+    ),
+}
+
+
+def list_generators() -> list[GeneratorEntry]:
+    """All registry entries, sorted by stable name."""
+    return sorted(GENERATOR_REGISTRY.values(), key=lambda e: e.name)
+
+
+def get_generator(name: str) -> GeneratorEntry | None:
+    """Resolve a generator entry by its stable id, or ``None`` if unknown."""
+    return GENERATOR_REGISTRY.get(name)