metaobjects 1.0.11__tar.gz → 1.0.12__tar.gz

{metaobjects-1.0.11 → metaobjects-1.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.11
+Version: 1.0.12
 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-1.0.11 → metaobjects-1.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.11"
+version = "1.0.12"
 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-1.0.11 → metaobjects-1.0.12}/src/metaobjects/cli.py

@@ -1069,6 +1069,132 @@ def _cmd_list(_args: argparse.Namespace) -> int:
     return 0
 
 
+def _describe_fmt_report(report: "object", cwd: Path) -> str:
+    from metaobjects import fmt
+
+    try:
+        rel = report.path.relative_to(cwd)
+    except ValueError:
+        rel = report.path
+    if report.status == fmt.STATUS_FORMATTED:
+        return f"  reformatted  {rel}"
+    if report.status == fmt.STATUS_WOULD_FORMAT:
+        return f"  not canonical  {rel}"
+    if report.status == fmt.STATUS_UNCHANGED:
+        return f"  ok           {rel}"
+    if report.status == fmt.STATUS_SKIPPED_YAML:
+        return f"  skipped (yaml)     {rel} — {report.detail}"
+    if report.status == fmt.STATUS_SKIPPED_OVERLAY:
+        return (
+            f"  skipped (overlay)  {rel} — this file declares an overlay fmt "
+            "cannot resolve standalone"
+        )
+    if report.status == fmt.STATUS_ERROR:
+        return f"  error        {rel} — {report.detail}"
+    return f"  {report.status}  {rel}"  # pragma: no cover — exhaustive in practice
+
+
+def _cmd_fmt(args: argparse.Namespace) -> int:
+    """``fmt`` (#304) — rewrite metadata files into canonical form; ``--check``
+    lists non-canonical files and exits non-zero without changing anything.
+
+    Mirrors the TS reference surface exactly: no ``metadata_dir`` positional —
+    files come from the neutral ``.metaobjects/config.json`` ladder
+    (:func:`resolve_metadata_location`, rungs 3-4; this command does not read
+    this port's own ``metaobjects.config.yaml`` rung 2, matching the scope the
+    C# and Java ports also keep for `fmt`), optionally narrowed by explicit
+    file arguments.
+    """
+    from metaobjects import fmt
+    from metaobjects.core_types import core_providers
+    from metaobjects.library import library_sources
+    from metaobjects.provider import compose_registry
+
+    providers_extra, providers_ok = _providers_from_args(args)
+    if not providers_ok:
+        return 1
+    providers = [*core_providers, *providers_extra]
+    registry = compose_registry(providers)
+
+    cwd = Path.cwd()
+    collection = _resolve_metadata_location_or_print_error(None, cwd)
+    if collection is None:
+        return 1
+
+    all_files = list(collection.files)
+    own_files = list(collection.own_files)
+
+    if args.files:
+        wanted = [Path(f).resolve() for f in args.files]
+        owned_set = {p.resolve() for p in own_files}
+        missing = [str(p) for p in wanted if p not in owned_set]
+        if missing:
+            print(
+                "error: not among this project's resolved metadata sources: "
+                + ", ".join(missing),
+                file=sys.stderr,
+            )
+            print(
+                "metaobjects fmt only formats files the metadata-location ladder "
+                "already resolves — pass no arguments to format every one of them.",
+                file=sys.stderr,
+            )
+            return 1
+        wanted_set = {p for p in wanted}
+        targets = [p for p in own_files if p.resolve() in wanted_set]
+    else:
+        targets = own_files
+
+    lib_sources = library_sources(list(collection.libraries)) if collection.libraries else []
+
+    result = fmt.run(
+        all_files=all_files,
+        target_files=targets,
+        file_ids=dict(collection.file_ids),
+        registry=registry,
+        lib_sources=lib_sources,
+        check=bool(args.check),
+        providers=providers,
+    )
+
+    if result.fatal is not None:
+        print(f"error: {result.fatal}", file=sys.stderr)
+        return 1
+
+    if not result.files:
+        print("metaobjects fmt — no metadata files to format.")
+        return 0
+
+    for report in result.files:
+        print(_describe_fmt_report(report, cwd))
+
+    errored = sum(1 for r in result.files if r.status == fmt.STATUS_ERROR)
+    needs_format = sum(1 for r in result.files if r.status == fmt.STATUS_WOULD_FORMAT)
+    reformatted = sum(1 for r in result.files if r.status == fmt.STATUS_FORMATTED)
+
+    if args.check:
+        if needs_format or errored:
+            suffix = f", {errored} error(s)" if errored else ""
+            print(
+                f"metaobjects fmt --check — {needs_format} file(s) not canonical{suffix}. "
+                "Run `metaobjects fmt` to fix.",
+                file=sys.stderr,
+            )
+            return 1
+        print("metaobjects fmt --check — every file is already canonical.")
+        return 0
+
+    if errored:
+        print(
+            f"metaobjects fmt — {errored} file(s) could not be formatted safely (left unchanged).",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"metaobjects fmt — {reformatted} file(s) reformatted.")
+    return 0
+
+
 def _cmd_eject(args: argparse.Namespace) -> int:
     """Copy reference generators into ``codegen/generators/`` to own (ADR-0034 Am. 3)."""
     root = Path(args.root) if args.root else Path.cwd()
@@ -2493,6 +2619,31 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     verify.set_defaults(func=_cmd_verify)
 
+    fmt_p = sub.add_parser(
+        "fmt",
+        help="rewrite metadata files into canonical form (#304)",
+    )
+    fmt_p.add_argument(
+        "files",
+        nargs="*",
+        metavar="FILE",
+        help="optional explicit file(s) to format — must be members of this "
+        "project's resolved metadata sources; omit to format every one of them",
+    )
+    fmt_p.add_argument(
+        "--check",
+        action="store_true",
+        help="list files that are not canonical and exit non-zero; changes nothing",
+    )
+    fmt_p.add_argument(
+        "--provider",
+        action="append",
+        default=None,
+        metavar="MODULE:SYMBOL",
+        help="consumer-registered Provider(s), repeatable (module:symbol)",
+    )
+    fmt_p.set_defaults(func=_cmd_fmt)
+
     eject_p = sub.add_parser(
         "eject",
         help="copy reference generators into codegen/generators/ to own and edit",

metaobjects-1.0.12/src/metaobjects/fmt.py

@@ -0,0 +1,214 @@
+"""``metaobjects fmt`` (#304) — rewrite metadata files into the canonical form
+the cross-port canonical serializer already produces. ``--check`` lists files
+that are not canonical and exits non-zero without changing anything.
+
+Mirrors the TS reference (``packages/metadata/src/fmt.ts`` +
+``packages/cli/src/lib/fmt-engine.ts``) and the C#/Java ports exactly:
+
+- Each file is formatted STANDALONE — own-mode, declared-here layer only
+  (ADR-0039). ``parse_document`` already builds a fresh, unmerged tree per
+  document (this port's loader does parse -> merge -> super-resolve as three
+  separate steps, unlike TS/C#'s accumulating-root parser) — calling it
+  directly and never running ``merge_roots``/``resolve_supers`` is what makes
+  a cross-file ``extends`` round-trip untouched (the raw ``super_ref`` string
+  is read directly by ``canonical_serialize``, never its resolution) and an
+  ``overlay: true`` node never even attempt a merge.
+- An ``overlay: true`` node is tagged (``is_overlay``) by the parser but never
+  resolved here — Python's overlay MERGE only happens in ``loader/merge.py``,
+  which this module never calls. A file containing one anywhere in its tree
+  (detected by :func:`_contains_overlay`) is reported as a skip rather than
+  guessed at — the concrete shape of "overlay files stay overlays".
+- YAML is always skipped: no canonical YAML emitter exists (ADR-0006).
+- Before writing, the whole project is reloaded with the candidate
+  substituted in via an in-memory source (never touching disk until proven
+  safe) and the write is refused unless that reload has no errors AND its
+  canonical form is byte-identical to the untouched baseline.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from metaobjects.errors import MetaError
+from metaobjects.loader.meta_data_loader import MetaDataLoader
+from metaobjects.loader.sources.file_source import FileSource
+from metaobjects.loader.sources.meta_data_source import InMemoryStringSource, MetaDataSource
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.parser import parse_document
+from metaobjects.registry import TypeRegistry
+from metaobjects.serializer_json import canonical_serialize
+
+#: Statuses a single file's run can report.
+STATUS_FORMATTED = "formatted"
+STATUS_WOULD_FORMAT = "would-format"
+STATUS_UNCHANGED = "unchanged"
+STATUS_SKIPPED_YAML = "skipped-yaml"
+STATUS_SKIPPED_OVERLAY = "skipped-overlay"
+STATUS_ERROR = "error"
+
+
+@dataclass
+class FormatFileResult:
+    ok: bool
+    overlay: bool = False
+    text: str | None = None
+    message: str | None = None
+
+
+def _contains_overlay(node: MetaData) -> bool:
+    """Whether *node* or any descendant (own children only — this tree was
+    never merged, so every child already is its own) carries ``overlay: true``.
+    """
+    if getattr(node, "is_overlay", False):
+        return True
+    return any(_contains_overlay(child) for child in node.own_children())
+
+
+def format_file(content: str, registry: TypeRegistry, source_id: str) -> FormatFileResult:
+    """Format one file's own content. Parses *content* standalone via
+    :func:`parse_document` — never merged with any other file, super
+    resolution never run — and, on a clean parse with no overlay anywhere in
+    the tree, returns the canonical serialization of the resulting file root.
+    Never raises for a malformed file; that comes back as ``ok=False``.
+    """
+    # Strip a UTF-8 BOM before parsing — json.loads rejects one outright
+    # ("Unexpected UTF-8 BOM (decode using utf-8-sig)"), and Java-authored
+    # files often carry one.
+    normalized = content[1:] if content.startswith("") else content
+    try:
+        doc = json.loads(normalized)
+    except json.JSONDecodeError as exc:
+        return FormatFileResult(ok=False, message=f"invalid JSON: {exc}")
+
+    try:
+        result = parse_document(doc, registry, source_id)
+    except Exception as exc:  # a few structural failures raise rather than record
+        return FormatFileResult(ok=False, message=str(exc))
+
+    if result.errors:
+        message = "; ".join(e.message for e in result.errors)
+        return FormatFileResult(ok=False, message=message)
+
+    if _contains_overlay(result.root):
+        return FormatFileResult(
+            ok=False,
+            overlay=True,
+            message="this file declares an overlay fmt cannot resolve standalone",
+        )
+
+    return FormatFileResult(ok=True, text=canonical_serialize(result.root))
+
+
+@dataclass
+class FileReport:
+    path: Path
+    status: str
+    detail: str | None = None
+
+
+@dataclass
+class RunResult:
+    files: list[FileReport] = field(default_factory=list)
+    fatal: str | None = None
+
+
+def run(
+    all_files: list[Path],
+    target_files: list[Path],
+    file_ids: dict[Path, str],
+    registry: TypeRegistry,
+    lib_sources: list[MetaDataSource],
+    check: bool,
+    providers: list[object] | None = None,
+) -> RunResult:
+    """Run fmt over *target_files* (a subset of *all_files* — the project's
+    FULL resolved file set, needed for the whole-project safety-check reload
+    regardless of which files are in scope to format).
+
+    *providers* must be the SAME provider list *registry* (used for every
+    standalone per-file parse) was composed from — the whole-project baseline
+    and safety-check reloads build their own `MetaDataLoader`, which recomposes
+    a registry from *providers* itself rather than taking `registry` directly,
+    so passing a different set here would silently check two vocabularies
+    against each other.
+    """
+
+    def source_id(path: Path) -> str:
+        return file_ids.get(path) or path.name
+
+    def build_sources(
+        override_path: Path | None = None, override_text: str | None = None
+    ) -> list[MetaDataSource]:
+        sources: list[MetaDataSource] = list(lib_sources)
+        for p in all_files:
+            if override_path is not None and p == override_path:
+                sources.append(InMemoryStringSource(override_text or "", id=source_id(p)))
+            else:
+                sources.append(FileSource(p, id=source_id(p)))
+        return sources
+
+    baseline = MetaDataLoader(providers=providers, strict=False).load(build_sources())
+    if baseline.errors:
+        detail = "\n".join(f"  {e.code}: {e.message}" for e in baseline.errors)
+        return RunResult(
+            fatal=(
+                "this project's metadata does not currently load cleanly — fix the "
+                f"error(s) below, then re-run fmt:\n{detail}"
+            )
+        )
+    baseline_canonical = canonical_serialize(baseline.root)
+
+    reports: list[FileReport] = []
+    for path in target_files:
+        ext = path.suffix.lower()
+        if ext in (".yaml", ".yml"):
+            reports.append(
+                FileReport(
+                    path,
+                    STATUS_SKIPPED_YAML,
+                    "no canonical YAML emitter exists (ADR-0006: JSON is the canonical "
+                    "interchange form) — left untouched",
+                )
+            )
+            continue
+
+        content = path.read_text(encoding="utf-8")
+        formatted = format_file(content, registry, source_id(path))
+        if not formatted.ok:
+            reports.append(
+                FileReport(
+                    path,
+                    STATUS_SKIPPED_OVERLAY if formatted.overlay else STATUS_ERROR,
+                    formatted.message,
+                )
+            )
+            continue
+
+        if formatted.text == content:
+            reports.append(FileReport(path, STATUS_UNCHANGED))
+            continue
+
+        test_load = MetaDataLoader(providers=providers, strict=False).load(
+            build_sources(path, formatted.text)
+        )
+        safe = not test_load.errors and canonical_serialize(test_load.root) == baseline_canonical
+        if not safe:
+            reports.append(
+                FileReport(
+                    path,
+                    STATUS_ERROR,
+                    "formatting this file would change the loaded model's meaning — left unchanged",
+                )
+            )
+            continue
+
+        if check:
+            reports.append(FileReport(path, STATUS_WOULD_FORMAT))
+        else:
+            path.write_text(formatted.text, encoding="utf-8")
+            reports.append(FileReport(path, STATUS_FORMATTED))
+
+    return RunResult(files=reports)

{metaobjects-1.0.11 → metaobjects-1.0.12}/src/metaobjects/render/extract/__init__.py

@@ -25,6 +25,7 @@ from metaobjects.render.extract.types import (
     Format,
     Normalizer,
     OnField,
+    OnLocate,
     ExtractOptions,
     ExtractionOutcome,
     ExtractSchema,
@@ -45,6 +46,7 @@ __all__ = [
     "JsonForgivingReader",
     "Normalizer",
     "OnField",
+    "OnLocate",
     "ExtractOptions",
     "ExtractionOutcome",
     "ExtractSchema",

{metaobjects-1.0.11 → metaobjects-1.0.12}/src/metaobjects/render/extract/extract.py

@@ -38,23 +38,55 @@ def extract(
     stripped = _strip.strip(text)
     ci = o.tolerance != Tolerance.STRICT
 
+    # FR-364: the document-level on_locate hook runs BEFORE the default locator. A non-None
+    # return is the payload span, fed into the same format-specific forgiving reader a
+    # default-located span would be — tolerance/coercion/normalizers/on_field downstream are
+    # unaffected. A None return (or no hook) falls through to the default locate strategy
+    # unchanged. A raised exception propagates (not swallowed), matching on_field.
+    located: str | None = None if o.on_locate is None else o.on_locate(text if text is not None else "", schema.format)
+
     # XML rootless (opts.rootless): the payload's fields ARE the top-level elements — there
     # is no enclosing root to locate — so parse the whole stripped text's top-level elements
     # directly. Otherwise locate the <rootName> span as before. JSON is unaffected. Mirrors
     # Java Extract.extract.
     span: str | None
     raw: dict[str, object]
-    if schema.format == Format.JSON:
+    # Whether the SELECTED region (not the original reply) was itself empty/blank — the signal
+    # mark_empty() keys on below. For the default path this is the pre-existing "nothing to
+    # parse" test (stripped == "" or span is None); for on_locate it must be judged against the
+    # hook's OWN return, not the original text — otherwise an empty located span (e.g. the hook
+    # deliberately returning "") reports "not empty" while every field is LOST, because the
+    # original reply was non-blank even though the thing on_locate chose to parse was.
+    region_blank: bool
+    if located is not None:
+        span = located
+        if schema.format == Format.JSON:
+            raw = JsonForgivingReader().read(located)
+        elif o.rootless:
+            raw = XmlForgivingReader().read_rootless(located, ci)
+        else:
+            raw = XmlForgivingReader().read(located, ci)
+        # `from_` is deliberately left empty rather than the original text: a document-level
+        # audit entry that copied the whole raw reply (which can be arbitrarily large) into the
+        # report on every call would make the report itself heavy for no benefit `to`'s length
+        # doesn't already give. `to` is the located span's LENGTH, not the span text, for the
+        # same reason.
+        report.add_coercion(Coercion("", "", str(len(located)), "onLocate"))
+        region_blank = located.strip() == ""
+    elif schema.format == Format.JSON:
         span = _select_json(text, stripped, schema.fields, ci)
         raw = {} if span is None else JsonForgivingReader().read(span)
+        region_blank = stripped == "" or span is None
     elif o.rootless:
         span = None if stripped == "" else stripped
         raw = {} if span is None else XmlForgivingReader().read_rootless(stripped, ci)
+        region_blank = stripped == "" or span is None
     else:
         span = _locate.xml(stripped, schema.root_name, ci)
         raw = {} if span is None else XmlForgivingReader().read(span, ci)
+        region_blank = stripped == "" or span is None
 
-    if not raw and (stripped == "" or span is None):
+    if not raw and region_blank:
         report.mark_empty()
 
     _extract(schema.fields, raw, "", data, report, o, ci)

{metaobjects-1.0.11 → metaobjects-1.0.12}/src/metaobjects/render/extract/types.py

@@ -27,6 +27,17 @@ T = TypeVar("T")
 OnField = Callable[[str, str, "FieldSpec"], object | None]
 Normalizer = Callable[[str], object | None]
 
+# FR-364: the document-level locate hook: (text, format) -> payload substring | None.
+# Receives the RAW reply text (never None; an absent document is normalized to ``""``
+# before the hook runs) and the schema's declared ``Format``. Returning ``None`` falls
+# back to the default locator (the fenced-then-first-object rule #363 fixed). A non-None
+# return is parsed by the normal pipeline exactly like a default-located span —
+# tolerance, coercion, ``normalizers``, and ``on_field`` downstream are unaffected — so
+# this hook only decides WHICH text is the payload, never how it is parsed. The returned
+# text need not be a literal substring of the input (the hook may synthesize it). A
+# raised exception propagates (it is not swallowed), matching ``on_field``.
+OnLocate = Callable[[str, "Format"], "str | None"]
+
 
 class Format(Enum):
     """Document format the extract pipeline targets."""
@@ -248,7 +259,8 @@ class ExtractOptions:
     """Bounded runtime override surface (the "20%").
 
     ``aliases``/``normalizers`` are MERGED with the schema's, runtime winning on key
-    conflict. ``on_field`` is the single bespoke-coercion hook.
+    conflict. ``on_field`` is the single per-field bespoke-coercion hook; ``on_locate``
+    is the single document-level (payload-location) hook.
 
     ``rootless`` (XML only): when ``True``, the input has NO enclosing root element —
     the payload's fields ARE the top-level elements (a flat sequence like
@@ -259,6 +271,7 @@ class ExtractOptions:
     aliases: dict[str, str] = field(default_factory=dict)
     normalizers: dict[str, Normalizer] = field(default_factory=dict)
     on_field: OnField | None = None
+    on_locate: OnLocate | None = None
     rootless: bool = False
 
     @staticmethod
@@ -271,6 +284,19 @@ class ExtractOptions:
             aliases=dict(self.aliases),
             normalizers=dict(self.normalizers),
             on_field=self.on_field,
+            on_locate=self.on_locate,
+            rootless=self.rootless,
+        )
+
+    def with_on_locate(self, hook: OnLocate | None) -> "ExtractOptions":
+        """The single document-level locate hook. See ``OnLocate``. Returns a copy
+        with ``on_locate`` set."""
+        return ExtractOptions(
+            tolerance=self.tolerance,
+            aliases=dict(self.aliases),
+            normalizers=dict(self.normalizers),
+            on_field=self.on_field,
+            on_locate=hook,
             rootless=self.rootless,
         )
 
@@ -282,6 +308,7 @@ class ExtractOptions:
             aliases=dict(self.aliases),
             normalizers=dict(self.normalizers),
             on_field=self.on_field,
+            on_locate=self.on_locate,
             rootless=r,
         )
 

metaobjects-1.0.12/tests/codegen/test_cli_fmt.py

@@ -0,0 +1,137 @@
+"""`metaobjects fmt` (#304) — rewrite metadata files into canonical form.
+
+Mirrors the TS reference's integration test and the C#/Java ports' Mojo/CLI
+tests: a messy file reformats, an already-canonical file is untouched, an
+overlay file with no local base is skipped, and a YAML file is always
+skipped. No `metadata_dir` positional — matches the TS reference surface:
+files come from the neutral `.metaobjects/config.json` ladder (here, just
+the default `metaobjects/` directory, since no project in these tests
+declares a config), optionally narrowed by explicit file arguments.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from metaobjects.cli import main
+
+MESSY_WIDGET = """\
+{ "metadata.root": { "package": "acme", "children": [
+  { "object.entity": { "@description": "A widget", "name": "Widget", "children": [
+    { "field.string": { "name": "sku", "@maxLength": 40, "@required": true } }
+  ]}}
+]}}
+"""
+
+CANONICAL_GADGET = (
+    "{\n  \"metadata.root\": {\n    \"package\": \"acme\",\n    \"children\": [\n"
+    "      {\n        \"object.entity\": {\n          \"name\": \"Gadget\",\n"
+    "          \"children\": [\n            {\n              \"field.string\": {\n"
+    "                \"name\": \"label\"\n              }\n            }\n          ]\n"
+    "        }\n      }\n    ]\n  }\n}\n"
+)
+
+OVERLAY_WIDGET_UI = """\
+{ "metadata.root": { "package": "acme", "children": [
+  { "object.entity": { "name": "Widget", "overlay": true, "children": [
+    { "field.string": { "name": "notes" } }
+  ]}}
+]}}
+"""
+
+EXTRA_YAML = "metadata:\n  package: acme\n  children: []\n"
+
+
+def _project(tmp_path: Path) -> Path:
+    meta = tmp_path / "metaobjects"
+    meta.mkdir()
+    (meta / "meta.base.json").write_text(MESSY_WIDGET, encoding="utf-8")
+    (meta / "meta.already-canonical.json").write_text(CANONICAL_GADGET, encoding="utf-8")
+    (meta / "meta.widget.ui.json").write_text(OVERLAY_WIDGET_UI, encoding="utf-8")
+    (meta / "meta.extra.yaml").write_text(EXTRA_YAML, encoding="utf-8")
+    return meta
+
+
+def test_reformats_messy_leaves_canonical_skips_overlay_and_yaml(tmp_path, monkeypatch, capsys) -> None:
+    meta = _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+
+    rc = main(["fmt"])
+    assert rc == 0
+
+    out = capsys.readouterr().out
+    assert "reformatted" in out
+    assert "skipped (yaml)" in out
+    assert "skipped (overlay)" in out
+
+    assert (meta / "meta.already-canonical.json").read_text(encoding="utf-8") == CANONICAL_GADGET
+    assert (meta / "meta.base.json").read_text(encoding="utf-8") != MESSY_WIDGET
+    assert (meta / "meta.widget.ui.json").read_text(encoding="utf-8") == OVERLAY_WIDGET_UI
+    assert (meta / "meta.extra.yaml").read_text(encoding="utf-8") == EXTRA_YAML
+
+    # The reformatted file round-trips to valid, equivalent JSON.
+    reformatted = json.loads((meta / "meta.base.json").read_text(encoding="utf-8"))
+    assert reformatted["metadata.root"]["package"] == "acme"
+
+
+def test_is_idempotent(tmp_path, monkeypatch) -> None:
+    _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    assert main(["fmt"]) == 0
+    once = (tmp_path / "metaobjects" / "meta.base.json").read_text(encoding="utf-8")
+    assert main(["fmt"]) == 0
+    assert (tmp_path / "metaobjects" / "meta.base.json").read_text(encoding="utf-8") == once
+
+
+def test_check_mode_lists_drift_and_changes_nothing(tmp_path, monkeypatch, capsys) -> None:
+    meta = _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    before = (meta / "meta.base.json").read_text(encoding="utf-8")
+
+    rc = main(["fmt", "--check"])
+    assert rc == 1
+    assert "not canonical" in capsys.readouterr().err
+
+    assert (meta / "meta.base.json").read_text(encoding="utf-8") == before
+
+
+def test_check_mode_passes_once_canonical(tmp_path, monkeypatch) -> None:
+    _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    assert main(["fmt"]) == 0
+    assert main(["fmt", "--check"]) == 0
+
+
+def test_explicit_file_narrows_the_run(tmp_path, monkeypatch) -> None:
+    meta = _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    before_base = (meta / "meta.base.json").read_text(encoding="utf-8")
+
+    rc = main(["fmt", "metaobjects/meta.already-canonical.json"])
+    assert rc == 0
+    # Untouched — only the named (already-canonical) file was in scope.
+    assert (meta / "meta.base.json").read_text(encoding="utf-8") == before_base
+
+
+def test_explicit_file_outside_resolved_sources_fails(tmp_path, monkeypatch, capsys) -> None:
+    _project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "outside.json").write_text("{}", encoding="utf-8")
+
+    rc = main(["fmt", "outside.json"])
+    assert rc == 1
+    assert "not among this project's resolved metadata sources" in capsys.readouterr().err
+
+
+def test_refuses_when_project_does_not_load_cleanly(tmp_path, monkeypatch, capsys) -> None:
+    meta = tmp_path / "metaobjects"
+    meta.mkdir()
+    (meta / "bad.json").write_text("{ this is not valid json", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    rc = main(["fmt"])
+    assert rc == 1
+    assert "does not currently load cleanly" in capsys.readouterr().err
+    assert (meta / "bad.json").read_text(encoding="utf-8") == "{ this is not valid json"