"""The command-semantics contract, loaded from config/command_semantics.json.

This is the fairness guarantee of the whole suite: which exact command each

subject kind runs per operation and track. It is data, not code, so outsiders

can audit it by reading one JSON file, and a fairness decision (for example

adopting `oak diff --stat` as agent-default once published agent docs do) is a

one-line data edit plus a version bump that every row records (ADR-0005).

"""

from __future__ import annotations

import json

from pathlib import Path

from typing import Any

ROOT = Path(__file__).resolve().parents[2]

DEFAULT_CONFIG = ROOT / "config" / "command_semantics.json"

TRACKS = ("agent-default", "core-equivalent")

class CommandSemantics:

    def __init__(self, config_path: Path = DEFAULT_CONFIG) -> None:

        data = json.loads(config_path.read_text())

        self.version: str = str(data["version"])

        self._tracks: dict[str, Any] = data["harness_tracks"]

        self._output_formats = data.get("output_formats", {})

        self._agent_native_json_probes: dict[str, Any] = data.get("agent_native_json_probes") or {}

    def _kind(self, kind: str) -> dict[str, Any]:

        if kind not in self._tracks:

            raise ValueError(f"unknown subject kind for command semantics: {kind!r}")

        return self._tracks[kind]

    def init_args(self, kind: str) -> list[str]:

        return list(self._kind(kind)["init"])

    def stage_args(self, kind: str) -> list[str] | None:

        value = self._kind(kind)["stage"]

        return list(value) if value is not None else None

    def commit_args(self, kind: str, message: str) -> list[str]:

        return [part.replace("{message}", message) for part in self._kind(kind)["commit"]]

    def branch_create_args(self, kind: str) -> list[str]:

        return list(self._kind(kind)["branch_create"])

    def status_args(self, kind: str, track: str) -> list[str]:

        return list(self._kind(kind)["status"][track])

    def diff_args(self, kind: str, track: str) -> list[str]:

        return list(self._kind(kind)["diff"][track])

    def output_format(self, kind: str, operation: str, track: str) -> str:

        family = "status" if operation.startswith("status.") else "diff"

        if operation == "diff.full":

            track = "core-equivalent"

        value = self._output_formats[kind][family][track]

        if value not in {"status", "stat", "diff", "porcelain-z", "oak-json"}:

            raise ValueError(f"unsupported configured output format: {value!r}")

        return value

    def agent_native_json_probes(self, kind: str, branch_name: str) -> dict[str, dict[str, Any]]:

        self._kind(kind)

        probes = self._agent_native_json_probes.get(kind) or {}

        result: dict[str, dict[str, Any]] = {}

        for operation, spec in probes.items():

            result[str(operation)] = {

                "output_format": str(spec.get("output_format", "json")),

                "args": [

                    str(part).replace("{branch}", branch_name)

                    for part in spec.get("args", [])

                ],

                "help_args": [str(part) for part in spec.get("help_args", [])],

                "required_fields": [str(part) for part in spec.get("required_fields", [])],

            }

            if spec.get("minimum_oak_version") is not None:

                result[str(operation)]["minimum_oak_version"] = str(spec["minimum_oak_version"])

        return result

    def snapshot_commands(self, bin_path: str, kind: str, message: str) -> list[list[str]]:

        """Full snapshot sequence: git pays stage+commit as two calls, oak one."""

        commands: list[list[str]] = []

        stage = self.stage_args(kind)

        if stage is not None:

            commands.append([bin_path, *stage])

        commands.append([bin_path, *self.commit_args(kind, message)])

        return commands

    def status_display(self, kind: str, track: str) -> str:

        return " ".join([kind, *self.status_args(kind, track)])

    def diff_display(self, kind: str, track: str) -> str:

        return " ".join([kind, *self.diff_args(kind, track)])

_semantics: CommandSemantics | None = None

def semantics() -> CommandSemantics:

    global _semantics

    if _semantics is None:

        _semantics = CommandSemantics()

    return _semantics