mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/commands/approve.py

@@ -0,0 +1,136 @@
+"""Implement ``mr-data approve``.
+
+Explicit arguments override derived values. Running the command records approval; approval intent
+is not read from the Recipe, files, or environment. The approver is the named flag value or the
+process owner. Rendering and derivation live in :mod:`mostlyright.data_harness.ux.approve`.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_json_bytes
+from mostlyright.data_harness.recipe import RecipeApproval, RecipeError, parse_fresh_recipe
+from mostlyright.data_harness.ux.approve import (
+    approval_summary,
+    derive_approval_id,
+    derive_approved_at,
+    derive_approved_by,
+    derive_policy_digest,
+)
+from mostlyright.data_harness.ux.commands import CommandSpec
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--recipe",
+        type=Path,
+        required=True,
+        help="the Recipe to freeze",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        required=True,
+        help="where to write the approval; nothing is ever overwritten",
+    )
+    # Every one of these is derived when it is left out. They exist so a value that has to be
+    # exact -- a recorded timestamp, an approver who is not the person at the keyboard, the
+    # fingerprint of a policy that lives somewhere else -- can still be stated outright.
+    parser.add_argument(
+        "--approval-id",
+        help="name this approval yourself instead of naming it after the Recipe",
+    )
+    parser.add_argument(
+        "--approved-by",
+        help="who is approving; the owner of this process when left out",
+    )
+    parser.add_argument(
+        "--approved-at",
+        help="when it was approved, as 2026-07-19T12:00:00Z; now when left out",
+    )
+    parser.add_argument(
+        "--approval-policy",
+        type=Path,
+        help="the approval policy you acted under, as JSON; its fingerprint is recorded",
+    )
+    parser.add_argument(
+        "--approval-policy-digest",
+        help="the fingerprint of an approval policy that is not in a file here",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Imported here, not at the top: this package is loaded while the command line is still being
+    # set up. Reusing the command line's own reader and writer is what keeps this file's
+    # publication receipt identical to the one every other written output carries.
+    from mostlyright.data_harness import cli
+
+    recipe = parse_fresh_recipe(cli._read_json(args.recipe))
+    # One parsed Recipe answers both questions -- what is shown, and what is bound -- so the
+    # summary cannot describe something other than what the fingerprint freezes (T-29-27).
+    summary = approval_summary(recipe)
+    approval = RecipeApproval(
+        approval_id=args.approval_id or derive_approval_id(recipe),
+        recipe_digest=recipe.digest,
+        approved_by=derive_approved_by(args.approved_by),
+        approved_at=derive_approved_at(args.approved_at),
+        approval_policy_digest=_policy_digest(args, cli._read_json),
+    )
+    raw = canonical_json_bytes(approval.to_dict())
+    try:
+        publication = cli._write_output_exclusive(
+            args.output,
+            raw,
+            purpose="recipe approval",
+            authority="stdout_recipe_approval_receipt",
+        )
+    except FileExistsError as exc:
+        raise RecipeError(
+            "RECIPE_OUTPUT_EXISTS",
+            "output",
+            "recipe approval output already exists",
+        ) from exc
+    return {
+        "status": "recipe_approved",
+        "summary": summary.to_dict(),
+        "output": str(args.output),
+        "recipe_digest": recipe.digest,
+        "approval_digest": approval.digest,
+        "approval_id": approval.approval_id,
+        "approved_by": approval.approved_by,
+        "approved_at": approval.approved_at,
+        "approval_policy_digest": approval.approval_policy_digest,
+        "publication": publication,
+    }
+
+
+def _policy_digest(args: argparse.Namespace, read_json: Any) -> str:
+    """The approval policy fingerprint: stated, read from the policy, or derived from none.
+
+    Two contradictory answers are a refusal rather than a silent preference. Which policy an
+    approval was given under is the whole point of recording its fingerprint, so a command that
+    quietly ignored one of them would be recording a guess.
+    """
+
+    if args.approval_policy is not None and args.approval_policy_digest is not None:
+        raise RecipeError(
+            "RECIPE_APPROVAL_POLICY",
+            "approval.approval_policy",
+            "pass either --approval-policy or --approval-policy-digest, not both",
+        )
+    if args.approval_policy_digest is not None:
+        return args.approval_policy_digest
+    if args.approval_policy is not None:
+        return derive_policy_digest(read_json(args.approval_policy))
+    return derive_policy_digest()
+
+
+SPEC = CommandSpec(
+    name="approve",
+    help="freeze one recipe by fingerprint, after showing you exactly what you are freezing",
+    add_arguments=add_arguments,
+    run=run,
+)