metaobjects 0.12.0__tar.gz → 0.13.0__tar.gz

{metaobjects-0.12.0 → metaobjects-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.12.0
+Version: 0.13.0
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.12.0 → metaobjects-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.12.0"
+version = "0.13.0"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-0.12.0 → metaobjects-0.13.0}/src/metaobjects/cli.py

@@ -3,9 +3,13 @@
 Two subcommands:
 
   metaobjects gen    <metadataDir> --out <dir> [--package <pkg>]
+                     [--template-spec <json> [--templates <dir>]]
       Load metadata, run the Python codegen generator suite, and write files
       under ``--out`` (guarded by the @generated header). Prints each written
-      file. Non-zero exit on a load error.
+      file. Non-zero exit on a load error. ``--template-spec`` appends the
+      declarative Mustache template generators (scope perEntity/perPackage/
+      perModel + outputPattern) described by a JSON spec, resolving template
+      refs under ``--templates`` (default ``templates``).
 
   metaobjects verify <metadataDir> [--codegen] [--templates] [--db URL] ...
       Drift gate with explicit subverbs (ADR-0021 D2 — one verify vocabulary
@@ -138,11 +142,38 @@ def _parse_entities(value: str | None) -> list[str] | None:
     return names or None
 
 
+def _run_suite(
+    root: MetaData,
+    out_dir: str,
+    generators: list[Generator] | None = None,
+    entity_filter: list[str] | None = None,
+    emit_package_init: bool = True,
+) -> list[str]:
+    """Run a generator suite against an ALREADY-LOADED ``root`` into ``out_dir``.
+
+    Split out from :func:`_generate` so a single gen invocation can load the
+    metadata once and run multiple passes against it (the default Python suite +
+    the ``--template-spec`` pass). See :func:`_generate` for the parameter
+    semantics. Returns the written paths.
+
+    NOTE: ``run_gen``'s output-path collision guard is per-pass — a
+    ``--template-spec`` ``outputPattern`` that collides with a default-suite path
+    is not flagged across the two passes (it would overwrite, since default files
+    carry the ``@generated`` header). Accepted marginal limitation (requires user
+    misconfiguration).
+    """
+    config = GenConfig(out_dir=out_dir, emit_package_init=emit_package_init)
+    suite = generators if generators is not None else _default_generators()
+    result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
+    return [path for path, status in result.files if status != "refused"]
+
+
 def _generate(
     metadata_dir: str,
     out_dir: str,
     generators: list[Generator] | None = None,
     entity_filter: list[str] | None = None,
+    emit_package_init: bool = True,
 ) -> tuple[list[str], list[str]]:
     """Run the generator suite into ``out_dir``.
 
@@ -150,18 +181,17 @@ def _generate(
     resolved subset for ``--generators``. ``entity_filter`` (the ``--entities``
     allowlist) restricts which entities are EMITTED while the WHOLE model is still
     loaded, so cross-entity references (``extends`` bases, ``@objectRef`` VOs)
-    resolve — emit a subset without splitting the metadata. Returns
+    resolve — emit a subset without splitting the metadata. ``emit_package_init``
+    is ``False`` for the format-agnostic ``--template-spec`` generators (whose
+    output is text/markdown/csv/json/xml/html, never a Python package) so no
+    spurious ``__init__.py`` is scattered through their output tree. Returns
     ``(written_paths, errors)``. On a load error, ``errors`` is non-empty and no
     files are written.
     """
     root, errors = _load_root(metadata_dir)
     if root is None:
         return [], errors
-    config = GenConfig(out_dir=out_dir)
-    suite = generators if generators is not None else _default_generators()
-    result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
-    written = [path for path, status in result.files if status != "refused"]
-    return written, []
+    return _run_suite(root, out_dir, generators, entity_filter, emit_package_init), []
 
 
 #: The default api-surface subdir (the cross-port contract's ``api/python``).
@@ -293,13 +323,54 @@ def _cmd_gen(args: argparse.Namespace) -> int:
                 print(f"  {msg}", file=sys.stderr)
             return 1
 
+    # SP-1: declarative Mustache generators from a JSON template-spec. Their output
+    # is format-agnostic (text/markdown/csv/json/xml/html), so they run as a SECOND,
+    # SEPARATE pass with emit_package_init=False — no Python __init__.py is injected
+    # into their (possibly non-Python) output tree. Templates resolve under
+    # --templates via a FilesystemProvider.
+    spec_gens: list[Generator] = []
+    if getattr(args, "template_spec", None):
+        from metaobjects.codegen.template_codegen.template_spec import (
+            parse_template_spec,
+            template_spec_to_generators,
+        )
+
+        try:
+            spec = parse_template_spec(json.loads(Path(args.template_spec).read_text(encoding="utf-8")))
+        except (OSError, ValueError) as exc:
+            print(f"error: invalid --template-spec: {exc}", file=sys.stderr)
+            return 1
+        provider = FilesystemProvider(args.templates)
+        spec_gens = template_spec_to_generators(spec, provider)
+
     entities = _parse_entities(getattr(args, "entities", None))
-    written, errors = _generate(args.metadata_dir, args.out, generators, entities)
-    if errors:
+    # Load the metadata ONCE; both the default suite and the (optional)
+    # --template-spec pass run against this single loaded root.
+    root, load_errors = _load_root(args.metadata_dir)
+    if root is None:
         print("error: failed to load metadata:", file=sys.stderr)
-        for msg in errors:
+        for msg in load_errors:
             print(f"  {msg}", file=sys.stderr)
         return 1
+    written = _run_suite(root, args.out, generators, entities)
+    if spec_gens:
+        # The template-spec pass renders user-supplied templates: a bad ref or a
+        # wrong --templates dir raises RenderError (not OSError/ValueError, so it
+        # escapes the parse-time guard above). Report it as a clean error.
+        from metaobjects.render.renderer import RenderError
+
+        try:
+            spec_written = _run_suite(
+                root, args.out, spec_gens, entities, emit_package_init=False
+            )
+        except RenderError as exc:
+            print(
+                f"error: --template-spec render failed (check the template refs and "
+                f"--templates dir {args.templates!r}): {exc}",
+                file=sys.stderr,
+            )
+            return 1
+        written = list(written) + spec_written
     for path in written:
         print(path)
     print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
@@ -581,6 +652,23 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="list registered generators (stable name + description) and exit",
     )
+    gen.add_argument(
+        "--template-spec",
+        dest="template_spec",
+        default=None,
+        help=(
+            "path to a JSON template-spec ({\"generators\":[{name,template,scope,"
+            "outputPattern,format?}]}) — declarative Mustache generators appended "
+            "to the suite (SP-1). Templates resolve under --templates. For output "
+            "to be regenerable, the template must emit the @generated header itself "
+            "(the codegen write path refuses to overwrite files lacking it)."
+        ),
+    )
+    gen.add_argument(
+        "--templates",
+        default="templates",
+        help="templates root for --template-spec (default: templates)",
+    )
     gen.add_argument(
         "--package",
         default=None,

{metaobjects-0.12.0 → metaobjects-0.13.0}/src/metaobjects/codegen/generator.py

@@ -60,3 +60,35 @@ def once_per_run(
         return r if isinstance(r, list) else [r]
 
     return run
+
+
+def per_package(
+    fn: Callable[[str, list[MetaObject], GenContext], "EmittedFile | list[EmittedFile]"],
+) -> Callable[[GenContext], list[EmittedFile]]:
+    """One-file-per-package convenience. Groups matched entities by effective
+    package, runs ``fn(pkg, entities, ctx)`` once per package (packages ascending,
+    entities keeping ``ctx.entities`` order). The package scope from
+    codegen-concepts §10 (object + model already exist via per_entity + per_model)."""
+
+    def run(ctx: GenContext) -> list[EmittedFile]:
+        # Local import avoids a module cycle (template_data imports nothing from here).
+        from metaobjects.codegen.template_codegen.template_data import package_of
+
+        by_pkg: dict[str, list[MetaObject]] = {}
+        for e in ctx.entities:
+            if not ctx.matches(e):
+                continue
+            by_pkg.setdefault(package_of(e), []).append(e)
+        out: list[EmittedFile] = []
+        for pkg in sorted(by_pkg):
+            r = fn(pkg, by_pkg[pkg], ctx)
+            out.extend(r if isinstance(r, list) else [r])
+        return out
+
+    return run
+
+
+#: App-scope alias — run once over the whole model. The canonical name for the
+#: one-shot scope (``once_per_run`` stays as a soft-deprecated alias; "run" is
+#: ambiguous under multi-target output, ``per_model`` names the data scope).
+per_model = once_per_run

metaobjects-0.13.0/src/metaobjects/codegen/generators/template_generator.py

@@ -0,0 +1,138 @@
+"""template_generator() — Python port of the TS rc.12 factory.
+
+Walks the loaded MetaRoot -> renders shared Mustache templates via the
+metaobjects.render engine -> returns EmittedFile[]. Same Generator Protocol
+as the per-entity hand-coded generators; just adds the "Mustache template"
++ "walk that yields a data dict per output" primitives.
+
+Design: spec/design-docs/2026-05-28-cross-port-template-generator.md.
+Cross-port byte-equivalence verified via fixtures/render-conformance/template-generator/.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Sequence
+
+from metaobjects.codegen.generator import EmittedFile, GenContext, Generator
+from metaobjects.codegen.template_codegen.output_pattern import expand_output_pattern
+from metaobjects.codegen.template_codegen.template_data import (
+    build_entity_template_data,
+    build_model_template_data,
+    build_package_template_data,
+    bare_name,
+    is_concrete,
+    package_of,
+)
+from metaobjects.render import escapers
+from metaobjects.render.renderer import RenderRequest, render
+from metaobjects.render.verify import Provider
+
+#: The three built-in walk scopes (SP-1 §3.1).
+SCOPES = ("perEntity", "perPackage", "perModel")
+
+
+def _scope_walk(scope: str, pattern: str) -> Callable[[Any], list[dict]]:
+    """Derive a walk from a built-in scope + output pattern. Each scope yields the
+    neutral data dict for its unit and names the file via the pattern."""
+
+    def walk(root: Any) -> list[dict]:
+        from metaobjects.meta.core.object.meta_object import MetaObject
+
+        objects = [c for c in root.children() if isinstance(c, MetaObject)]
+        concrete = [o for o in objects if is_concrete(o)]
+        if scope == "perEntity":
+            return [
+                {
+                    "data": build_entity_template_data(o),
+                    "output_path": expand_output_pattern(pattern, bare_name(o), package_of(o)),
+                }
+                for o in concrete
+            ]
+        if scope == "perPackage":
+            by_pkg: dict[str, list[Any]] = {}
+            for o in concrete:
+                by_pkg.setdefault(package_of(o), []).append(o)
+            return [
+                {
+                    "data": build_package_template_data(pkg, by_pkg[pkg]),
+                    "output_path": expand_output_pattern(pattern, None, pkg),
+                }
+                for pkg in sorted(by_pkg)
+            ]
+        # perModel — one file over the whole model.
+        return [
+            {
+                "data": build_model_template_data(objects),
+                "output_path": expand_output_pattern(pattern, None, None),
+            }
+        ]
+
+    return walk
+
+
+@dataclass
+class _TemplateGenerator:
+    name: str
+    template: str
+    walk: Callable[[Any], Sequence[dict]]
+    provider: Provider
+    format: str = escapers.FORMAT_TEXT
+
+    def generate(self, ctx: GenContext) -> list[EmittedFile]:
+        walk_results: Iterable[dict] = self.walk(ctx.loaded_root)
+        files: list[EmittedFile] = []
+        for entry in walk_results:
+            content = render(
+                RenderRequest(
+                    payload=entry["data"],
+                    provider=self.provider,
+                    ref=self.template,
+                    format=self.format,
+                )
+            )
+            files.append(EmittedFile(path=entry["output_path"], content=content))
+        return files
+
+
+def template_generator(
+    *,
+    name: str,
+    template: str,
+    provider: Provider,
+    walk: Callable[[Any], Sequence[dict]] | None = None,
+    scope: str | None = None,
+    output_pattern: str | None = None,
+    format: str = escapers.FORMAT_TEXT,
+) -> Generator:
+    """Build a Generator that renders a Mustache template per walk entry.
+
+    Provide exactly one of ``walk`` (the power-user escape hatch) or
+    (``scope`` + ``output_pattern``) — the declarative built-in walk.
+
+    Args:
+        name: kebab-case identifier; surfaces in diagnostics.
+        template: ref resolved by the provider (e.g. "custom/hello").
+        provider: ref-resolver for the template.
+        walk: callback taking the loaded MetaRoot, returning dicts shaped
+            {"data": <payload>, "output_path": <relative path>}.
+        scope: built-in walk scope (perEntity/perPackage/perModel).
+        output_pattern: output path pattern for the built-in scope walk.
+        format: render format ("text", "html", "markdown", ...). Defaults to text.
+    """
+    has_walk = walk is not None
+    has_scope = scope is not None
+    if has_walk == has_scope:
+        raise ValueError(
+            f"template_generator({name}): provide exactly one of `walk` or "
+            "(`scope` + `output_pattern`)"
+        )
+    if has_scope and not output_pattern:
+        raise ValueError(f"template_generator({name}): `scope` requires `output_pattern`")
+    resolved_walk = walk if has_walk else _scope_walk(scope, output_pattern)  # type: ignore[arg-type]
+    return _TemplateGenerator(
+        name=name,
+        template=template,
+        walk=resolved_walk,
+        provider=provider,
+        format=format,
+    )

metaobjects-0.13.0/src/metaobjects/codegen/template_codegen/output_pattern.py

@@ -0,0 +1,54 @@
+"""Expands the cross-port output-pattern grammar (SP-1 §3.3): ``{name}``,
+``{Name}`` (PascalCase), ``{package}`` (``::`` -> ``/``). An empty ``{package}``
+collapses its trailing/leading slash so ``{package}/{name}`` with no package
+yields just ``{name}``. Unknown placeholders raise.
+
+Byte-equivalent to the TypeScript ``output-pattern.ts`` and the JVM
+``OutputPattern``.
+"""
+
+from __future__ import annotations
+
+import re
+
+_TOKEN = re.compile(r"\{(\w+)\}")
+
+
+def _pascal(s: str) -> str:
+    return "".join(w[:1].upper() + w[1:] for w in re.split(r"[^A-Za-z0-9]+", s) if w)
+
+
+def expand_output_pattern(
+    pattern: str, name: str | None, package: str | None
+) -> str:
+    """Expand ``pattern``. ``name`` may be ``None`` (perPackage/perModel);
+    ``package`` may be ``None``/empty."""
+    pkg_empty = False
+
+    def repl(m: re.Match[str]) -> str:
+        nonlocal pkg_empty
+        token = m.group(1)
+        if token == "package":
+            p = (package or "").replace("::", "/")
+            if p == "":
+                pkg_empty = True
+            return p
+        if token == "name":
+            if name is None:
+                raise ValueError(
+                    f"output pattern {pattern!r} uses {{name}} but no entity name is in scope"
+                )
+            return name
+        if token == "Name":
+            if name is None:
+                raise ValueError(
+                    f"output pattern {pattern!r} uses {{Name}} but no entity name is in scope"
+                )
+            return _pascal(name)
+        raise ValueError(f"unknown placeholder {{{token}}} in output pattern {pattern!r}")
+
+    out = _TOKEN.sub(repl, pattern)
+    if pkg_empty:
+        out = re.sub(r"^/+", "", out)
+        out = re.sub(r"/{2,}", "/", out)
+    return out

metaobjects-0.13.0/src/metaobjects/codegen/template_codegen/template_data.py

@@ -0,0 +1,119 @@
+"""The NEUTRAL, structural codegen template data dict (SP-1 §3.2) for Python.
+
+Plain ``dict``/``list`` mirroring the TS ``EntityTemplateData`` keys EXACTLY — a
+byte-gated cross-port contract (verified against the TS-produced
+``fixtures/template-codegen-conformance/expected/``). Optional keys
+(``maxLength``, ``enumValues``) are OMITTED when absent so a ``{{#maxLength}}``
+section gates identically to TS.
+
+Own-vs-effective discipline (matching the TS ``ownAttr`` semantics, per the JVM
+review): ``is_abstract`` per-node; ``@required`` attr + ``maxLength`` read from
+``own_attrs()`` (own-only); the required-*validator* branch effective; enum
+``values`` from ``attrs()`` (effective); effective package derived from
+``resolution_key()`` (matching the TS ``effectivePackage``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from metaobjects.shared.base_types import (
+    TYPE_IDENTITY,
+    TYPE_RELATIONSHIP,
+    TYPE_VALIDATOR,
+)
+from metaobjects.shared.separators import PACKAGE_SEP
+
+_SUBTYPE_ENUM = "enum"
+_VALIDATOR_REQUIRED = "required"
+
+
+def bare_name(o: Any) -> str:
+    """The object name. Python objects already carry the bare leaf name."""
+    return o.name
+
+
+def package_of(o: Any) -> str:
+    """Effective package, matching the TS ``effectivePackage(resolutionKey)``.
+
+    Derived from ``resolution_key()`` (own ``package`` → ``file_default_package`` →
+    nearest ancestor's ``package``) by stripping the trailing ``::<name>`` suffix —
+    so programmatically-built / plugin trees (no ``file_default_package``, package
+    only on an ancestor) resolve the ancestor package like TS does. "" when the
+    resolution key carries no package segment.
+    """
+    key = o.resolution_key()
+    idx = key.rfind(PACKAGE_SEP)
+    return key[:idx] if idx >= 0 else ""
+
+
+def is_concrete(o: Any) -> bool:
+    return not o.is_abstract
+
+
+def _is_required(f: Any) -> bool:
+    if f.own_attrs().get(_VALIDATOR_REQUIRED) is True:
+        return True
+    return any(
+        c.type == TYPE_VALIDATOR and c.sub_type == _VALIDATOR_REQUIRED
+        for c in f.children()
+    )
+
+
+def _field_data(f: Any) -> dict[str, Any]:
+    d: dict[str, Any] = {
+        "name": f.name,
+        "type": f.sub_type,
+        "required": _is_required(f),
+        "isArray": bool(f.is_array),
+    }
+    own = f.own_attrs()
+    if "maxLength" in own:
+        d["maxLength"] = int(own["maxLength"])
+    if f.sub_type == _SUBTYPE_ENUM:
+        values = f.attrs().get("values")
+        if isinstance(values, list):
+            d["enumValues"] = [str(v) for v in values]
+    return d
+
+
+def build_entity_template_data(o: Any) -> dict[str, Any]:
+    fields = [_field_data(f) for f in o.fields()]
+    identities: list[dict[str, Any]] = []
+    relationships: list[dict[str, Any]] = []
+    for c in o.children():
+        if c.type == TYPE_IDENTITY:
+            id_fields = c.own_attrs().get("fields")
+            identities.append(
+                {"kind": c.sub_type, "fields": list(id_fields) if isinstance(id_fields, list) else []}
+            )
+        elif c.type == TYPE_RELATIONSHIP:
+            own = c.own_attrs()
+            relationships.append(
+                {
+                    "name": c.name,
+                    "cardinality": own.get("cardinality", "") or "",
+                    "targetRef": own.get("objectRef", "") or "",
+                }
+            )
+    return {
+        "name": bare_name(o),
+        "package": package_of(o),
+        "fields": fields,
+        "identities": identities,
+        "relationships": relationships,
+    }
+
+
+def build_package_template_data(pkg: str, entities: list[Any]) -> dict[str, Any]:
+    return {"package": pkg, "entities": [build_entity_template_data(o) for o in entities]}
+
+
+def build_model_template_data(objects: list[Any]) -> dict[str, Any]:
+    by_pkg: dict[str, list[Any]] = {}
+    for o in objects:
+        if not is_concrete(o):
+            continue
+        by_pkg.setdefault(package_of(o), []).append(o)
+    packages = [build_package_template_data(p, by_pkg[p]) for p in sorted(by_pkg)]
+    return {"packages": packages}

metaobjects-0.13.0/src/metaobjects/codegen/template_codegen/template_spec.py

@@ -0,0 +1,90 @@
+"""The declarative JSON template-spec the CLI ports (Python/C#) consume.
+
+The JSON shape is the cross-port contract (SP-1 §4) — a JSON Schema sits beside
+the TS port at codegen-ts/src/template-codegen/template-spec.schema.json. This
+module validates + maps it to runnable Generators.
+
+Regenerability note: ``--template-spec`` output flows through the standard codegen
+write path, which refuses to overwrite a file that lacks the ``@generated`` marker
+(the hand-edit guard the rest of codegen and the TS port share). For a template's
+output to be safely regenerable, the **template author** must emit the
+``@generated`` header in the template body itself — the same author responsibility
+the rest of the codegen pipeline relies on.
+
+The Python port has no output-*target* concept (the codegen pipeline writes every
+``EmittedFile`` relative to a single ``out_dir``). A per-generator ``target`` field
+is therefore REJECTED rather than silently dropped, so a cross-port spec authored
+with ``target`` fails loudly here instead of producing a different layout than TS.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from metaobjects.codegen.generator import Generator
+from metaobjects.codegen.generators.template_generator import SCOPES, template_generator
+from metaobjects.render import escapers
+from metaobjects.render.verify import Provider
+
+_FORMATS = escapers.FORMATS
+
+_REQUIRED_STR = ("name", "template", "scope", "outputPattern")
+
+
+def parse_template_spec(obj: object) -> dict[str, Any]:
+    """Validate + return a normalized ``{"generators": [...]}`` dict. Raises
+    ``ValueError`` on any shape violation."""
+    if not isinstance(obj, dict) or not isinstance(obj.get("generators"), list):
+        raise ValueError("template-spec: expected an object with a `generators` array")
+    generators: list[dict[str, Any]] = []
+    for i, raw in enumerate(obj["generators"]):
+        if not isinstance(raw, dict):
+            raise ValueError(f"template-spec generators[{i}]: expected an object")
+        for key in _REQUIRED_STR:
+            if not isinstance(raw.get(key), str) or raw[key] == "":
+                raise ValueError(
+                    f"template-spec generators[{i}]: missing or empty required string {key!r}"
+                )
+        if raw["scope"] not in SCOPES:
+            raise ValueError(
+                f"template-spec generators[{i}]: scope must be one of "
+                f"{' | '.join(SCOPES)}, got {raw['scope']!r}"
+            )
+        entry: dict[str, Any] = {
+            "name": raw["name"],
+            "template": raw["template"],
+            "scope": raw["scope"],
+            "outputPattern": raw["outputPattern"],
+        }
+        if "format" in raw:
+            if raw["format"] not in _FORMATS:
+                raise ValueError(
+                    f"template-spec generators[{i}]: format must be one of "
+                    f"{' | '.join(_FORMATS)}, got {raw['format']!r}"
+                )
+            entry["format"] = raw["format"]
+        if "target" in raw:
+            raise ValueError(
+                f"template-spec generators[{i}]: target is not supported by the "
+                "Python port — it has no output-target concept"
+            )
+        generators.append(entry)
+    return {"generators": generators}
+
+
+def template_spec_to_generators(spec: dict[str, Any], provider: Provider) -> list[Generator]:
+    """Map a parsed spec into runnable Generators (one per entry). The caller
+    supplies the ``provider`` (the CLI builds a ``FilesystemProvider``)."""
+    out: list[Generator] = []
+    for e in spec["generators"]:
+        out.append(
+            template_generator(
+                name=e["name"],
+                template=e["template"],
+                scope=e["scope"],
+                output_pattern=e["outputPattern"],
+                provider=provider,
+                format=e.get("format", escapers.FORMAT_TEXT),
+            )
+        )
+    return out