metaobjects 1.0.11__tar.gz → 1.0.13__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.11"
+version = "1.0.13"
 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.13}/src/metaobjects/apidocs/naming.py

@@ -74,6 +74,52 @@ def _route_snake_case(name: str) -> str:
     return to_snake_case(name)
 
 
+_ALREADY_PLURAL_EXCLUDED_PRECEDING_CHARS = "suia"
+"""The four letters that precede a genuinely SINGULAR "...s" ending in the common
+patterns this codebase's entity names hit — status, address, bonus, alias, gas,
+analysis. Anything else before a final "s" reads as already-plural."""
+
+
+def _is_already_plural(word: str) -> bool:
+    """True when ``word`` already reads as a plural noun, so running it through
+    the ordinary suffix rule would double it — the real defect this exists to
+    fix: ``program_purchase_stats`` -> ``program_purchase_statses`` shipped as a
+    REST collection path in an adopter's app.
+
+    Heuristic, not a dictionary: a word ending in ``s`` is already-plural UNLESS
+    the character immediately before that final ``s`` is one of s/u/i/a
+    (case-insensitive). Covers stats, settings, details, news, analytics,
+    series, photos; leaves status, address, bonus, alias, gas, analysis on the
+    ordinary suffix path (unchanged).
+
+    Known miss, deliberately not fixed here: a genuinely singular word ending in
+    "...s" with none of those four letters before it reads as already-plural too
+    — ``lens`` -> ``lens`` (correct plural ``lenses``). Fixing that needs a real
+    dictionary, which this is not; the heuristic optimizes for the shape the
+    doubling defect actually hits (entity names that are already a plural
+    concept)."""
+    if len(word) < 2:
+        return False
+    lowered = word.lower()
+    if lowered[-1] != "s":
+        return False
+    return lowered[-2] not in _ALREADY_PLURAL_EXCLUDED_PRECEDING_CHARS
+
+
+def _pluralize_legacy_suffix_only(name: str) -> str:
+    """FROZEN — byte-for-byte the pre-fix suffix-only pluralization rule, with no
+    already-plural detection. Exposed only so :func:`pluralize` can fall back to
+    it. The DEFAULT PHYSICAL name fallback lives in a completely separate,
+    independently-frozen implementation (``meta_source._pluralize``) — this is
+    NOT that one, and the two must never be merged into a single call site."""
+    lowered = name.lower()
+    if lowered.endswith(("s", "x", "z", "ch", "sh")):
+        return name + "es"
+    if len(name) >= 2 and lowered[-1] == "y" and lowered[-2] not in "aeiou":
+        return name[:-1] + "ies"
+    return name + "s"
+
+
 def pluralize(name: str) -> str:
     """``post_category`` → ``post_categories``; ``address`` → ``addresses``.
 
@@ -82,13 +128,16 @@ def pluralize(name: str) -> str:
     ``y`` becomes ``ies``; anything else takes ``s``. The cross-port
     byte-identity covers the already-lowercased word :func:`route_path` feeds
     in — suffix tests here run on a lowercased copy, unlike the JVM port's
-    case-sensitive ones, so mixed-case input may diverge."""
-    lowered = name.lower()
-    if lowered.endswith(("s", "x", "z", "ch", "sh")):
-        return name + "es"
-    if len(name) >= 2 and lowered[-1] == "y" and lowered[-2] not in "aeiou":
-        return name[:-1] + "ies"
-    return name + "s"
+    case-sensitive ones, so mixed-case input may diverge.
+
+    Adds already-plural detection (:func:`_is_already_plural`) on top of that
+    historical suffix rule (:func:`_pluralize_legacy_suffix_only`) — API/code-
+    surface pluralization only; the DEFAULT PHYSICAL table name fallback is
+    frozen separately (``meta_source._pluralize``), so an existing adopter
+    database never sees a proposed rename."""
+    if _is_already_plural(name):
+        return name
+    return _pluralize_legacy_suffix_only(name)
 
 
 def model_class_name(obj: MetaData) -> str:

{metaobjects-1.0.11 → metaobjects-1.0.13}/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.13/src/metaobjects/codegen/collection_name_collision.py

@@ -0,0 +1,58 @@
+"""Collection-name collision refusal — the single choke point every route/router/
+finder generator path goes through (called once, in ``run_gen``, over the full
+entity set BEFORE any generator runs).
+
+Two DISTINCT entities/projections pluralizing to the SAME API-surface collection
+name (REST path, generated router module/finder names) is reachable from stock
+metadata now that :func:`metaobjects.apidocs.naming.pluralize` no longer doubles an
+already-plural word: ``Address`` (not already-plural: legacy-pluralizes to
+``Addresses``) and ``Addresses`` (already-plural: left unchanged, ALSO
+``Addresses``) collide, where before the fix they did not (``Addresses`` legacy-
+pluralized to ``Addresseses``). Silently letting two entities share one collection
+name would mean whichever generator runs second silently wins, or a straight
+duplicate-module/route registration two files downstream of the real cause. This
+refuses at the one place that can see the WHOLE set, with a message naming both
+entities and the colliding name.
+"""
+from __future__ import annotations
+
+from metaobjects.apidocs.naming import pluralize
+from metaobjects.errors import ErrorCode
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.core.object.object_constants import OBJECT_SUBTYPE_VALUE
+
+ERR_COLLECTION_NAME_COLLISION = ErrorCode.ERR_COLLECTION_NAME_COLLISION.value
+
+
+def assert_no_collection_name_collisions(entities: list[MetaObject]) -> None:
+    """Refuse a generation run in which two DISTINCT entities/projections pluralize
+    to the same API-surface collection name.
+
+    Scope: every object EXCEPT ``object.value`` (a value object never gets a route,
+    router module, or finder name — it is pure shape, so it cannot collide on any of
+    those). A TPH subtype IS included: it gets its own generated names against the
+    shared base table, so two subtypes (or a subtype and an unrelated top-level
+    entity) sharing a pluralized name collide on those generated symbols exactly as
+    two top-level entities would.
+
+    A PURE function of the entity set — never of traversal order: the reported pair
+    is deterministic (first-seen-by-input-order "owner" of a plural; raised as soon
+    as a second, different entity claims the same plural).
+    """
+    owner_of_plural: dict[str, MetaObject] = {}
+    for obj in entities:
+        if obj.sub_type == OBJECT_SUBTYPE_VALUE:
+            continue
+        plural = pluralize(obj.name)
+        existing = owner_of_plural.get(plural)
+        if existing is not None:
+            if existing.resolution_key() != obj.resolution_key():
+                raise ValueError(
+                    f"{ERR_COLLECTION_NAME_COLLISION}: \"{existing.name}\" and \"{obj.name}\" both "
+                    f'pluralize to the API-surface collection name "{plural}" (REST path, generated '
+                    "router module/finder names) — rename one entity so its pluralized name is "
+                    "distinct. Default PHYSICAL table names are unaffected by this rule and are not "
+                    "involved in the collision."
+                )
+        else:
+            owner_of_plural[plural] = obj

{metaobjects-1.0.11 → metaobjects-1.0.13}/src/metaobjects/codegen/runner.py

@@ -10,6 +10,7 @@ from metaobjects.meta.meta_root import MetaRoot
 from metaobjects.meta.meta_data import MetaData
 from metaobjects.meta.core.object.meta_object import MetaObject
 from metaobjects.shared.base_types import TYPE_OBJECT
+from .collection_name_collision import assert_no_collection_name_collisions
 from .config import GenConfig
 from .constants import generated_package_init
 from .generator import GenContext, Generator
@@ -107,6 +108,10 @@ def run_gen(
     if not safe:
         return result
 
+    # Refuse before any generator runs — the one choke point that sees the WHOLE
+    # entity set every route/router-emitting generator below reads from.
+    assert_no_collection_name_collisions(safe)
+
     emitted: dict[str, tuple[str, str]] = {}  # full_path -> (content, generated_by)
     for gen in generators:
         ctx = GenContext(

{metaobjects-1.0.11 → metaobjects-1.0.13}/src/metaobjects/errors.py

@@ -200,6 +200,12 @@ class ErrorCode(str, Enum):
     # Codegen (ADR-0044): two value-object FQNs in one payload artifact derive the same
     # emitted record name even after package-qualification. Peer of ERR_VAR_NOT_ON_PAYLOAD.
     ERR_PAYLOAD_NAME_COLLISION = "ERR_PAYLOAD_NAME_COLLISION"
+    # Codegen: two DISTINCT entities/projections in one generation run pluralize to the
+    # SAME API-surface collection name (route path, generated router/finder names) —
+    # e.g. "Address" and "Addresses" both resolving to "Addresses". A codegen-time (not
+    # loader) error, peer of ERR_PAYLOAD_NAME_COLLISION: refused rather than silently
+    # letting one entity's route win.
+    ERR_COLLECTION_NAME_COLLISION = "ERR_COLLECTION_NAME_COLLISION"
     ERR_OUTPUT_TAG_MISSING = "ERR_OUTPUT_TAG_MISSING"
     # SP-H Unit9 — @filterable: true on a field subtype with no filter-operator
     # band (e.g. field.object). Would silently generate an empty-ops filter.

metaobjects-1.0.13/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.13}/src/metaobjects/meta/persistence/source/meta_source.py

@@ -47,7 +47,17 @@ def _to_snake_case(s: str) -> str:
 
 
 def _pluralize(s: str) -> str:
-    """Trivial cross-port pluralization (matches TS ``pluralize``)."""
+    """FROZEN — the DEFAULT PHYSICAL name derivation only (step 4 below, reached
+    only when metadata declares no explicit physical name). Matches the TS
+    reference ``pluralizeTableNameLegacy`` (metadata/src/naming.ts) — NOT the TS
+    ``pluralize``, which now differs for an already-plural word, deliberately
+    with NO already-plural detection. An adopter's live database was created
+    with this rule; adding the already-plural check here would make a schema
+    migration propose a rename for every already-plural entity name on the next
+    run. The API-surface analog (``metaobjects.apidocs.naming.pluralize``) has
+    that fix — this one must not, and the two are intentionally separate,
+    independently-maintained implementations (never merge them into one call
+    site)."""
     if not s:
         return s
     lower = s.lower()
@@ -128,7 +138,8 @@ class MetaSource(MetaData):
             2. Legacy ``@table`` for non-table kind (pre-1.0 fallback).
             3. Source's bare structural ``name`` via snake_case
                (no pluralize — the source's name IS the logical name).
-            4. Owning entity's name via ``pluralize(snake_case())``.
+            4. Owning entity's name via the frozen legacy ``pluralize(snake_case())``
+               — see module-level ``_pluralize``'s docstring for why it is frozen.
 
         Callers needing the legacy raw ``@table`` slot only should use
         :meth:`table_name`; codegen / runtime should use ``physical_name``.

{metaobjects-1.0.11 → metaobjects-1.0.13}/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.13}/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)