metaobjects 0.25.0__tar.gz → 1.0.0__tar.gz

{metaobjects-0.25.0 → metaobjects-1.0.0}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.25.0"
+version = "1.0.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.25.0 → metaobjects-1.0.0}/src/metaobjects/agent_context/scaffold.py

@@ -80,31 +80,112 @@ class Manifest:
 # The sentinel a port stamps when it cannot resolve its own installed version.
 _UNRESOLVED_VERSION = "0.0.0"
 
-_RELEASE_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
-
-
-def _release_series(version: object) -> tuple[int, int] | None:
-    """Ordered release coordinate ``(minor, patch)``, or ``None`` when not orderable.
-
-    The MAJOR is deliberately dropped. It is a per-registry constant, not information:
-    npm/PyPI/NuGet ship ``0.<m>.<p>`` and Maven Central the same ``<m>.<p>`` on its
-    historical major ``7``, so minor.patch IS the shared release coordinate across all
-    four ports.
-
-    ``None`` means "not orderable, so nudge", and deliberately covers prereleases
-    (``0.24.5-rc.1``), build metadata (``0.24.5+abc``) and the ``0.0.0`` sentinel. Each
-    must keep nudging: an RC-scaffolded context against a final release is still worth
-    refreshing, and an unknown install must never assert "in sync".
+#: A release with an optional PRE-RELEASE segment, in either spelling one ecosystem uses.
+#: npm/NuGet/Maven write ``1.0.0-rc.5``; PEP 440 writes ``1.0.0rc5``. Both are the SAME
+#: release, and comparing their SPELLINGS is what made the nudge unsatisfiable — see
+#: ``_same_release``.
+_PRERELEASE_RE = re.compile(
+    r"^(\d+)\.(\d+)\.(\d+)"       # release
+    r"(?:-?([A-Za-z]+)\.?(\d+)?)?$"  # optional pre-release: -rc.5 | rc5 | -beta | b2
+)
+
+
+#: PEP 440 abbreviates the pre-release labels that npm spells out, and normalizing to ONE
+#: of them is what makes `1.1.0-beta.2` and `1.1.0b2` the same release. Only the spellings
+#: PEP 440 itself defines as equivalent — this is a rename table, not a similarity guess.
+_PEP440_LABEL_ALIASES = {
+    "a": "alpha",
+    "b": "beta",
+    "c": "rc",
+    "pre": "rc",
+    "preview": "rc",
+}
+
+
+def _release_coordinate(version: object) -> tuple[int, int, int, str, int] | None:
+    """``(major, minor, patch, pre_label, pre_number)`` for a version in ANY ecosystem
+    spelling.
+
+    The MAJOR is INFORMATION on this port, and both helpers here used to drop it. That
+    reduction is correct on the JVM and only there: Maven Central carries a historical
+    major of npm-major + 7 by design, so ``7.24.1`` and ``0.24.1`` genuinely name one
+    release and the coordinate must ignore the major to see it. Nothing of the kind holds
+    here — ``generatedBy`` is stamped by the Node CLI (an npm version) and
+    :func:`installed_metaobjects_version` reads the PyPI distribution version, and npm and
+    PyPI share the major by policy. Dropping it made ``1.0.0`` and ``2.0.0`` compare EQUAL,
+    and made a ``0.25.0``-stamped context read as NEWER than a ``1.0.0`` install — so the
+    1.0 upgrade, the single upgrade this advisory exists to catch, produced no nudge.
+
+    The pre-release label is lower-cased and its separators dropped, so ``-rc.5``,
+    ``rc5`` and ``-RC5`` all reduce to ``("rc", 5)``. A final release sorts ABOVE every
+    pre-release of the same number, which is what ``("", 0)`` vs ``("rc", 5)`` gives under
+    tuple ordering only because ``""`` < ``"rc"`` — so finals carry a sentinel label that
+    sorts last instead.
+
+    ``None`` means "not orderable, so nudge": the ``0.0.0`` unresolved-install sentinel,
+    build metadata, or anything this cannot parse. Those must never assert "in sync".
     """
     if not isinstance(version, str):
         return None
     v = version.strip()
     if v == _UNRESOLVED_VERSION:
         return None
-    m = _RELEASE_RE.match(v)
+    m = _PRERELEASE_RE.match(v)
     if m is None:
         return None
-    return int(m.group(2)), int(m.group(3))
+    label = _PEP440_LABEL_ALIASES.get((m.group(4) or "").lower(), (m.group(4) or "").lower())
+    number = int(m.group(5)) if m.group(5) is not None else 0
+    # A FINAL release is newer than every pre-release of the same number. "~" sorts above
+    # every ASCII letter, so the sentinel does that with plain tuple comparison.
+    return (
+        int(m.group(1)),
+        int(m.group(2)),
+        int(m.group(3)),
+        label if label else "~",
+        number,
+    )
+
+
+def _same_release(generated_by: object, current_version: str) -> bool:
+    """True when two version strings name the SAME release in different spellings.
+
+    The nudge compared spellings, so on the 1.0 RC line it could never be satisfied: the
+    canonical scaffolder is the Node CLI (ADR-0033), which stamps npm's ``1.0.0-rc.5``,
+    while this port reports PEP 440's ``1.0.0rc5``. Those are one release written two
+    ways, ``==`` says otherwise, and the remedy re-runs the scaffolder, which re-stamps
+    the same npm string — so the advisory fires on every invocation, forever, including
+    when the context is perfectly in sync. That is issue #347 with a different pair of
+    ecosystems; the fix for it reasoned about ORDERING and never about spelling.
+
+    Deliberately narrow. Only two versions that parse as the same release coordinate are
+    equal; anything unparseable (including the ``0.0.0`` sentinel) still nudges, and an
+    ``rc.4`` context against an ``rc.5`` install is a REAL difference and still nudges.
+    """
+    stamped = _release_coordinate(generated_by)
+    installed = _release_coordinate(current_version)
+    return stamped is not None and stamped == installed
+
+
+def _release_series(version: object) -> tuple[int, int, int] | None:
+    """Ordered release coordinate ``(major, minor, patch)``, or ``None`` when not orderable.
+
+    Derived from :func:`_release_coordinate` rather than parsed again. These two functions
+    used to answer the same grammar with two different regexes — differential-checked
+    identical over 200k inputs, which is the good outcome of a coin flip, not a guarantee.
+    The ordering coordinate simply IS the equality coordinate restricted to FINAL releases,
+    and saying so in code means the two cannot drift apart.
+
+    ``None`` means "not orderable, so nudge", and deliberately covers prereleases
+    (``0.24.5-rc.1``, ``1.0.0rc5``), build metadata (``0.24.5+abc``) and the ``0.0.0``
+    sentinel. Each must keep nudging: an RC-scaffolded context against a final release is
+    still worth refreshing, and an unknown install must never assert "in sync".
+    """
+    coord = _release_coordinate(version)
+    # A pre-release carries a real label; a final carries the "~" sentinel. Only finals are
+    # orderable here, which is what the previous release-only regex enforced by construction.
+    if coord is None or coord[3] != "~":
+        return None
+    return coord[0], coord[1], coord[2]
 
 
 def _context_is_ahead_of_install(generated_by: object, current_version: str) -> bool:
@@ -141,16 +222,19 @@ def agent_context_staleness(
     is in sync — and a one-line advisory message otherwise. Pure + advisory:
     never raises, never blocks, never writes.
 
-    The comparison is **exact equality** first: ANY drift nudges (a re-scaffold is
-    cheap + idempotent), so this is not a semver compare — a prerelease or
-    build-metadata difference is still a reason to refresh. See
-    ``_context_is_ahead_of_install`` for the ONE case that is exempt.
+    ANY REAL drift nudges (a re-scaffold is cheap + idempotent), so this is not a semver
+    compare — an ``rc.4`` context against an ``rc.5`` install is still a reason to
+    refresh. Two exemptions, both for cases where nudging can never be SATISFIED:
+    ``_same_release`` (one release, two ecosystem spellings) and
+    ``_context_is_ahead_of_install`` (a port legitimately behind the npm scaffolder).
     """
     if manifest is None:
         return None  # no agent context here → nothing to nudge
     generated_by = manifest.get("generatedBy")
     if generated_by == current_version:
         return None  # in sync
+    if _same_release(generated_by, current_version):
+        return None  # one release, two ecosystem spellings — see below
     if _context_is_ahead_of_install(generated_by, current_version):
         return None  # scaffolded by a NEWER release than this install — see below
     frm = generated_by if generated_by else "an older MetaObjects"

{metaobjects-0.25.0 → metaobjects-1.0.0}/src/metaobjects/cli.py

@@ -44,6 +44,7 @@ from __future__ import annotations
 import argparse
 import dataclasses
 import json
+import os
 import re
 import sys
 import tempfile
@@ -376,6 +377,9 @@ def _run_suite(
     emit_package_init: bool = True,
     gen_state_dir: str | None = None,
     column_naming: str = DEFAULT_COLUMN_NAMING,
+    project_root: str | None = None,
+    baseline: str = "default",
+    refused_out: list[str] | None = None,
 ) -> list[str]:
     """Run a generator suite against an ALREADY-LOADED ``root`` into ``out_dir``.
 
@@ -405,11 +409,26 @@ def _run_suite(
         emit_package_init=emit_package_init,
         gen_state_dir=gen_state_dir,
         column_naming=column_naming,
+        # Manifest keys are relative to the PROJECT, which is what the manifest is
+        # anchored on — not to ``--out``, which varies per run while the manifest does
+        # not. Passed alongside gen_state_dir because the two are one decision: state
+        # that lives in the project must be keyed by the project.
+        project_root=project_root,
+        # `--baseline=adopt`: record what is on disk and write nothing. The refusal it
+        # exists for is the pre-manifest one, so it reaches every real gen path and no
+        # verify path (those pass gen_state_dir=None and record nothing at all).
+        baseline=baseline,
     )
     suite = generators if generators is not None else _default_generators()
     result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
     for warning in result.warnings:
         print(f"warning: {warning}")
+    # A refusal is a FAILED gate, and the return value carries only what was WRITTEN — so
+    # without this the one fact a CI step reads (the exit code) could not see it. An
+    # out-list rather than a changed return type: five call sites read the written paths,
+    # and only the ones that own an exit code care about the refusals.
+    if refused_out is not None:
+        refused_out.extend(path for path, status in result.files if status == "refused")
     return [path for path, status in result.files if status != "refused"]
 
 
@@ -463,12 +482,17 @@ def _generate(
 def gen_state_dir_for(metadata_dir: str) -> str:
     """Where a project's codegen hash manifest lives.
 
-    Anchored on the project — the metadata dir's parent, i.e. the directory holding
-    ``metaobjects/`` — never on ``Path.cwd()``, which is whatever directory the process
-    happens to sit in and would scatter ``.metaobjects/`` into any package that merely
-    runs a generator.
+    Anchored on the project — never on ``Path.cwd()``, which is whatever directory the
+    process happens to sit in and would scatter ``.metaobjects/`` into any package that
+    merely runs a generator.
+
+    It resolves the project through :func:`project_root_for` rather than repeating
+    ``Path(metadata_dir).resolve().parent``. That function's own docstring already claimed
+    this one "is anchored here" while the code spelled the rule out a second time, and the
+    manifest key and the manifest LOCATION have to agree on where the project is or a
+    lookup finds nothing and every file reads as "not ours".
     """
-    return str(Path(metadata_dir).resolve().parent / ".metaobjects" / ".gen-state")
+    return str(project_root_for(metadata_dir) / ".metaobjects" / ".gen-state")
 
 
 #: The conventional declarative-template-spec file (SP-1 §4), discovered when
@@ -792,10 +816,16 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             print(f"  {msg}", file=sys.stderr)
         return 1
     gen_state = gen_state_dir_for(args.metadata_dir)
+    # Same anchor the manifest itself uses. Both passes below key against it, so a
+    # `--template-spec` artifact and a default-suite artifact land in one key space.
+    gen_project_root = str(project_root_for(args.metadata_dir))
     column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
+    baseline = getattr(args, "baseline", None) or "default"
+    refused: list[str] = []
     written = _run_suite(
         root, args.out, generators, entities,
         gen_state_dir=gen_state, column_naming=column_naming,
+        project_root=gen_project_root, baseline=baseline, refused_out=refused,
     )
     if spec_gens:
         # The template-spec pass renders user-supplied templates: a bad ref or a
@@ -807,6 +837,7 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             spec_written = _run_suite(
                 root, args.out, spec_gens, entities, emit_package_init=False,
                 gen_state_dir=gen_state, column_naming=column_naming,
+                project_root=gen_project_root, baseline=baseline, refused_out=refused,
             )
         except RenderError as exc:
             print(
@@ -819,6 +850,17 @@ def _cmd_gen(args: argparse.Namespace) -> int:
     for path in written:
         print(path)
     print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
+    if refused:
+        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
+        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
+        # green while codegen refused to write — a gate that did not gate. The warnings
+        # above carry the detail; this line carries the verdict.
+        print(
+            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
+            f"above; `--baseline=adopt` records what you have and writes nothing)",
+            file=sys.stderr,
+        )
+        return 1
     return 0
 
 
@@ -828,9 +870,17 @@ def _run_gen_targets(
     root: MetaData,
     *,
     gen_state_dir: str | None = None,
+    project_root: str | None = None,
+    baseline: str = "default",
+    refused_out: list[str] | None = None,
 ) -> tuple[list[str], list[str]]:
     """Run each target's suite into its ``outDir``. Returns (all_written, errors).
 
+    This is the path the manifest keying matters most on: every target writes into its
+    OWN ``outDir`` while all of them share ONE ``gen_state_dir``, so out-dir-relative
+    keys meant target B's hash could claim ownership of target A's identically-named
+    file. ``project_root`` is the common anchor that makes the keys distinct.
+
     Cross-target duplicate-output-path guard (#267): ``run_gen``'s collision guard
     is per-pass, so two targets writing the same full path would silently clobber
     (generated files carry the @generated header). We accumulate every written full
@@ -851,7 +901,8 @@ def _run_gen_targets(
         out_dir = config.out_dir_for(t)
         try:
             written = _run_suite(
-                root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir
+                root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir,
+                project_root=project_root, baseline=baseline, refused_out=refused_out,
             )
         except ValueError as exc:  # intra-target run_gen collision → clean error
             errors.append(f"target '{t.name}': {exc}")
@@ -918,13 +969,28 @@ def _cmd_gen_neutral_fallback(args: argparse.Namespace) -> int:
 
     gen_state = str(root_dir.resolve() / ".metaobjects" / ".gen-state")
     column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
+    refused: list[str] = []
     written = _run_suite(
         root, args.out, generators, entities,
         gen_state_dir=gen_state, column_naming=column_naming,
+        project_root=str(root_dir.resolve()),
+        baseline=getattr(args, "baseline", None) or "default",
+        refused_out=refused,
     )
     for path in written:
         print(path)
     print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
+    if refused:
+        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
+        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
+        # green while codegen refused to write — a gate that did not gate. The warnings
+        # above carry the detail; this line carries the verdict.
+        print(
+            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
+            f"above; `--baseline=adopt` records what you have and writes nothing)",
+            file=sys.stderr,
+        )
+        return 1
     return 0
 
 
@@ -981,8 +1047,13 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
             print(f"  {msg}", file=sys.stderr)
         return 1
 
+    refused: list[str] = []
     written, errors = _run_gen_targets(
-        config, targets, root, gen_state_dir=gen_state_dir_for(config.metadata_dir())
+        config, targets, root,
+        gen_state_dir=gen_state_dir_for(config.metadata_dir()),
+        project_root=str(project_root_for(config.metadata_dir())),
+        baseline=getattr(args, "baseline", None) or "default",
+        refused_out=refused,
     )
     if errors:
         for msg in errors:
@@ -993,6 +1064,17 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
     print(
         f"metaobjects gen: wrote {len(written)} file(s) across {len(targets)} target(s)."
     )
+    if refused:
+        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
+        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
+        # green while codegen refused to write — a gate that did not gate. The warnings
+        # above carry the detail; this line carries the verdict.
+        print(
+            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
+            f"above; `--baseline=adopt` records what you have and writes nothing)",
+            file=sys.stderr,
+        )
+        return 1
     return 0
 
 
@@ -1033,7 +1115,22 @@ def _relative_set(root: Path) -> dict[str, str]:
     return files
 
 
-def _is_ours_for(gen_state_dir: str | None):
+def _out_prefix(out_dir: str, project_root: Path) -> str:
+    """The out dir, relative to the project — the translation between this diff's
+    out-dir-relative keys and the manifest's project-relative ones.
+
+    BOTH SIDES RESOLVED, and that is the whole content of this function. `project_root`
+    arrives resolved; relpath from a resolved anchor to an unresolved path is not the
+    path between the two directories, and under a directory symlink it walks OUT of the
+    project. Every lookup then misses, `is_ours` is false for every file, and the gate
+    prints a clean verdict over stale output — silent in the direction that matters.
+    It is written once here rather than at each of the three call sites, because three
+    spellings of one translation is how they came to disagree in the first place.
+    """
+    return os.path.relpath(Path(out_dir).resolve(), project_root)
+
+
+def _is_ours_for(gen_state_dir: str | None, out_prefix: str = ""):
     """Jurisdiction predicate for the ``extra`` verdict: did WE write this path?
 
     ``out_dir`` is a DIRECTORY, not a namespace this tool owns — the same ruling the
@@ -1041,20 +1138,36 @@ def _is_ours_for(gen_state_dir: str | None):
     beyond ``*.py`` means the gate now sees every stranger's file too, and convicting
     those turns a project with zero drift into a red build.
 
-    The manifest already records what we WROTE, keyed relative to ``out_dir`` — the
-    same key space this diff uses — so it answers the ownership question exactly.
+    The manifest already records what we WROTE, so it answers the ownership question
+    exactly — but it is keyed relative to the PROJECT while this diff is keyed relative
+    to ``out_dir``. ``out_prefix`` (the out dir, relative to the project) is what turns
+    one into the other. Getting this wrong is silent in the direction that matters: a
+    lookup that finds nothing makes ``is_ours`` false for every file, and the gate simply
+    stops reporting stale output while still printing a clean verdict.
+
+    The out-dir-relative name is tried as a fallback, because that is how a manifest
+    written before the re-keying spells it — the same fallback ``decide_and_write``
+    makes, so the write path and the gate cannot disagree about which entry is a record
+    of this file.
+
     FAILS CLOSED, matching :func:`is_pristine_generated`: with no manifest at all
     nothing is proven, so every file stays in scope and the old verdict stands.
     """
     if gen_state_dir is None or not has_hash_manifest(gen_state_dir):
         return lambda _rel: True
-    return lambda rel: read_generated_hash(gen_state_dir, rel) is not None
+
+    def is_ours(rel: str) -> bool:
+        key = os.path.join(out_prefix, rel) if out_prefix else rel
+        return read_generated_hash(gen_state_dir, key, legacy_rel_path=rel) is not None
+
+    return is_ours
 
 
 def _diff_report(
     expected: dict[str, str],
     committed: dict[str, str],
     gen_state_dir: str | None = None,
+    out_prefix: str = "",
 ) -> int:
     """Compare a regenerated file map against the committed one; print the
     standard ``verify --codegen`` drift report. Returns 0 (in sync) or 1.
@@ -1065,8 +1178,11 @@ def _diff_report(
 
     ``gen_state_dir`` scopes the ``extra`` verdict to files we have a record of
     writing — see :func:`_is_ours_for`. Omit it to keep the unscoped verdict.
+    ``out_prefix`` is the committed out dir relative to the project, which is what
+    translates this diff's out-dir-relative keys into the manifest's project-relative
+    ones; omit it only when the two coincide.
     """
-    is_ours = _is_ours_for(gen_state_dir)
+    is_ours = _is_ours_for(gen_state_dir, out_prefix)
     changed = sorted(
         k for k in expected if k in committed and expected[k] != committed[k]
     )
@@ -1179,7 +1295,14 @@ def _verify_codegen(args: argparse.Namespace) -> int:
         expected = _relative_set(Path(tmp))
         committed = _relative_set(Path(args.out))
 
-    return _diff_report(expected, committed, gen_state_dir_for(args.metadata_dir))
+    # The manifest is keyed relative to the project; this diff is keyed relative to
+    # `--out`. Hand over the prefix that translates one into the other, or the
+    # jurisdiction lookup finds nothing and the `extra` verdict silently empties.
+    project_root = project_root_for(args.metadata_dir)
+    return _diff_report(
+        expected, committed, gen_state_dir_for(args.metadata_dir),
+        _out_prefix(args.out, project_root),
+    )
 
 
 def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
@@ -1234,7 +1357,8 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
     # `_cmd_gen_neutral_fallback` writes its manifest to), so the jurisdiction lookup
     # must be built from that, not from args.metadata_dir (None here by definition).
     return _diff_report(
-        expected, committed, str(root_dir.resolve() / ".metaobjects" / ".gen-state")
+        expected, committed, str(root_dir.resolve() / ".metaobjects" / ".gen-state"),
+        _out_prefix(args.out, root_dir.resolve()),
     )
 
 
@@ -1351,7 +1475,14 @@ def _verify_codegen_config(args: argparse.Namespace) -> int:
             # Same jurisdiction rule as _diff_report — this rung inlines its diff to
             # report per-target, so the guard has to be inlined with it. Without it,
             # broadening the comparison past *.py convicts every stranger's file.
-            is_ours = _is_ours_for(gen_state_dir_for(config.metadata_dir()))
+            #
+            # PER-TARGET prefix, because that is the whole point on this rung: two
+            # targets with different outDirs share one manifest, and the key that tells
+            # their identically-named files apart is the one anchored on the project.
+            is_ours = _is_ours_for(
+                gen_state_dir_for(config.metadata_dir()),
+                _out_prefix(real_outdir, project_root_for(config.metadata_dir())),
+            )
             extra = sorted(k for k in committed if k not in expected and is_ours(k))
 
             names = "+".join(
@@ -1640,6 +1771,19 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="list registered generators (stable name + description) and exit",
     )
+    gen.add_argument(
+        "--baseline",
+        choices=("default", "adopt"),
+        default="default",
+        help=(
+            "first-time-on-existing-file behaviour. 'default' refuses a file that cannot "
+            "be proved to be generated output; 'adopt' records the files you have as the "
+            "baseline and writes NOTHING — the one run a project with no committed "
+            ".gen-state/.hashes.json can perform, since nothing writes a manifest until a "
+            "gen succeeds. Adopting DECLARES those files to be generated output: the next "
+            "gen regenerates over them, so commit before you run it."
+        ),
+    )
     gen.add_argument(
         "--template-spec",
         dest="template_spec",

{metaobjects-0.25.0 → metaobjects-1.0.0}/src/metaobjects/codegen/config.py

@@ -17,6 +17,22 @@ class GenConfig:
     # ``<project>/.metaobjects/.gen-state``. COMMIT the manifest: it is the only thing
     # that makes hand-edit detection work on a machine that did not generate the code.
     gen_state_dir: str | None = None
+    # The project the manifest belongs to — the directory holding ``metaobjects/`` and
+    # ``.metaobjects/``. Manifest keys are relative to THIS, not to ``out_dir``.
+    #
+    # They used to be out-dir-relative while the manifest itself is anchored on the
+    # project, so two runs with different ``--out`` shared one manifest keyed by names
+    # that mean different files: `gen --out /tmp/a` and `gen --out /tmp/b` both record
+    # `alarm_names.py`, and run B's hash then claims ownership of run A's file. The
+    # manifest is the only thing that can tell "this is exactly what I wrote" from
+    # "somebody edited this" on a machine that did not generate the code, so one that can
+    # be populated from an unrelated tree and keyed ambiguously is one that can say yes to
+    # the wrong file. TS keys project-root-relative, which is also what makes multiple
+    # output targets work.
+    #
+    # None keeps the out-dir-relative keys, so a programmatic caller that never had a
+    # project root is unchanged. The CLI always sets it.
+    project_root: str | None = None
     # Only "flat" is implemented; a non-default value is REFUSED below rather than
     # silently ignored (see __post_init__).
     output_layout: str = "flat"
@@ -37,6 +53,12 @@ class GenConfig:
     # generator emits names a different column than the one a row actually lands
     # in.
     column_naming: str = DEFAULT_COLUMN_NAMING
+    # First-time-on-existing-file behaviour. "default" refuses a file that cannot be
+    # proved to be generated output; "adopt" records what is on disk as the baseline and
+    # writes nothing — the one run a project with no committed manifest can perform (the
+    # refusal used to prescribe committing a manifest nothing had yet produced). A value
+    # this port does not implement is REFUSED in __post_init__ rather than ignored.
+    baseline: str = "default"
     provided_enum_namespace: str | None = None
     provided_enum_packages: dict[str, str] = field(default_factory=dict)
 
@@ -64,6 +86,17 @@ class GenConfig:
                 f"GenConfig.output_layout={self.output_layout!r}: only 'flat' is "
                 "implemented in this port."
             )
+        if self.baseline not in ("default", "adopt"):
+            # `fresh` is deliberately absent from this port rather than silently accepted:
+            # TypeScript implements it (overwrite from fresh + re-baseline) and this port
+            # does not, and taking the value while refusing files anyway is the kind of
+            # cross-port lie this whole method exists to prevent.
+            raise ValueError(
+                f"GenConfig.baseline={self.baseline!r}: this port implements 'default' and "
+                "'adopt'. To discard a refused file's content here, delete the file and "
+                "re-run — it is then written as new. (TypeScript's '--baseline=fresh' does "
+                "that in one step; it is not implemented in this port.)"
+            )
         if self.emit_abstract_shapes is not True:
             raise ValueError(
                 "GenConfig.emit_abstract_shapes=False: this port always emits the abstract "

metaobjects-1.0.0/src/metaobjects/codegen/format.py

@@ -0,0 +1,72 @@
+"""Canonicalize emitted source via ruff: sort imports (isort), then format.
+
+Both passes read stdin / write stdout, so generated code is import-sorted AND
+formatted — i.e. `ruff check`- and `ruff format`-clean for downstream consumers."""
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+
+_STDIN_NAME = "generated.py"
+
+#: ruff is a codegen-time convenience (import-sort + format), not a runtime requirement
+#: of the emitted code. When it's absent we emit valid-but-unformatted Python rather
+#: than hard-failing the whole ``gen``.
+_RUFF_AVAILABLE = importlib.util.find_spec("ruff") is not None
+
+
+def _run_ruff(args: list[str], source: str) -> str:
+    proc = subprocess.run(
+        [sys.executable, "-m", "ruff", *args],
+        input=source,
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        # A non-zero exit is read by the caller as "ruff rejected the source" — a
+        # generator bug. Two things make that reading unsafe, so record what actually
+        # happened instead of asserting a cause.
+        #
+        # First, ruff reports a source it cannot parse as exit 2 WITH stderr (measured,
+        # ruff 0.15.14: `error: Failed to parse at 1:7: ...`). So an EMPTY stderr is not
+        # a source rejection — the process did not get far enough to say anything.
+        # Second, a NEGATIVE returncode is death by signal, which is not a verdict on
+        # the source at all.
+        #
+        # This branch used to raise `ruff format failed:` — trailing off after the colon
+        # whenever stderr was empty, naming neither the exit status nor the fact that
+        # ruff never looked at the source, and sending a reader hunting a syntax error
+        # that did not exist. Always carry the status; never claim a source error for a
+        # process that did not finish, and do not guess at WHY it did not finish.
+        detail = proc.stderr.strip()
+        if proc.returncode < 0:
+            raise RuntimeError(
+                f"ruff {args[0]} was killed by signal {-proc.returncode} before it could "
+                f"format the source — this is not a source error; the formatter never ran "
+                f"to completion" + (f": {detail}" if detail else "")
+            )
+        raise RuntimeError(
+            f"ruff {args[0]} failed (exit {proc.returncode})"
+            + (
+                f": {detail}"
+                if detail
+                else " and wrote nothing to stderr — ruff reports an unparseable source"
+                     " WITH stderr, so this is not a source error"
+            )
+        )
+    return proc.stdout
+
+
+def ruff_format(source: str) -> str:
+    """Sort imports then format *source*; return the canonical text.
+
+    A no-op (returns *source* unchanged) when ruff is not installed — the emitted
+    code is still valid Python, just unformatted. Still raises RuntimeError if ruff
+    IS present but fails (e.g. a syntax error in emitted code — that's a generator bug)."""
+    if not _RUFF_AVAILABLE:
+        return source
+    sorted_src = _run_ruff(
+        ["check", "--select", "I", "--fix", "--stdin-filename", _STDIN_NAME, "-"], source
+    )
+    return _run_ruff(["format", "-"], sorted_src)