jsonout.py

Go to the documentation of this file.

"""JSON output: the same parsed save the Markdown writer gets, as a machine-readable
document against a published schema.
 
The Markdown is written for a person (or an LLM) to read; this is written for a
program. Both start from `parse_save`, so a field can never say one thing in one
format and something else in the other.
 
Two rules shape the document. Nothing is invented to fill a hole — a field the save
does not carry is simply absent, exactly as in the Markdown, so a consumer can tell
"not in this game" from "zero". And nothing about the machine that produced it is
guessed: the environment block holds only what the caller passed on the command line.
"""
 
import json
import os
from collections import OrderedDict
from datetime import datetime, timezone
 
from validators import run_validation
from validators.file_rules import run_file_validation
 
from .bnd4 import checksum_ok, parse_bnd4
from .convert import REPO_URL
 
## @brief Where the schema is published. Static file at the site root, so a consumer
#  can resolve it without cloning anything.
SCHEMA_URL = "https://sl2-analyzer.darthdemono.com/schema.json"
 
## @brief Schema version, semver. MINOR for a new optional field, MAJOR for anything
#  that would break a reader which trusted the previous shape.
SCHEMA_VERSION = "1.3.0"
 
## @brief Environment keys the schema names explicitly. Any other key is still
#  accepted and written through — this list is what gets documented and type-checked,
#  not a whitelist. The point of the block is that a save alone cannot tell you which
#  store sold the game, which patch it ran, or what it ran under.
KNOWN_META = (
    "source",
    "version",
    "dlc",
    "os",
    "launcher",
    "proton",
    "gamemode",
    "mangohud",
    "notes",
)
 
 
##
# @brief Normalise a CLI metadata key: lowercase, spaces and dashes to underscores.
# @details "Proton version" and "proton-version" are the same key. The value is left
#  exactly as typed — only the key is canonicalised, because the key is what a
#  consumer looks up.
# @param key Raw key as typed. @return The canonical form.
def meta_key(key):
    return key.strip().lower().replace(" ", "_").replace("-", "_")
 
 
##
# @brief Build the environment block from repeated `--meta key=value` arguments and
#        an optional JSON file.
# @details A key given more than once becomes a LIST, in the order given — that is how
#  `--meta dlc=X --meta dlc=Y` says two DLCs, with no comma-splitting guesswork (item
#  and boss names are full of commas, so splitting on one would be a bug waiting).
#  The JSON file is merged first so an explicit `--meta` on the command line wins.
# @param pairs List of "key=value" strings, or None.
# @param path  Path to a JSON object to merge underneath, or None.
# @return An OrderedDict, empty when nothing was passed.
# @throws ValueError on an argument with no "=", or a JSON file that is not an object.
def parse_meta(pairs, path=None):
    meta = OrderedDict()
    if path:
        with open(path, encoding="utf-8") as f:
            loaded = json.load(f)
        if not isinstance(loaded, dict):
            raise ValueError(f"{path}: expected a JSON object at the top level")
        for k, v in loaded.items():
            meta[meta_key(k)] = v
    for pair in pairs or []:
        if "=" not in pair:
            raise ValueError(f"--meta expects key=value, got {pair!r}")
        key, value = pair.split("=", 1)
        key, value = meta_key(key), value.strip()
        if key in meta:
            # Repeat means "and also", so the first repeat turns the value into a list.
            meta[key] = (meta[key] if isinstance(meta[key], list) else [meta[key]]) + [
                value
            ]
        else:
            meta[key] = value
    return meta
 
 
##
# @brief Make a parsed value safe for json.dump, without changing what it says.
# @details The parser uses sets for boss evidence and tuples for fixed-shape rows;
#  both become lists, and a set is sorted so two runs of the same save produce the
#  same bytes. Everything else passes through untouched.
def jsonable(value):
    if isinstance(value, dict):
        return OrderedDict((k, jsonable(v)) for k, v in value.items())
    if isinstance(value, set):
        return sorted(value)
    if isinstance(value, (list, tuple)):
        return [jsonable(v) for v in value]
    return value
 
 
##
# @brief One character as a JSON object: its slot number, then every field the parse
#        actually set.
# @details Absent stays absent. The keys are the parser's own, which is deliberate —
#  the Markdown, the web app and this document all name a field the same thing.
# @param slot_no 1-based slot number. @param ch The character dict.
# @param report  A validation @ref validators.models.Report, or None when the caller
#        did not ask for one. It is emitted whole — findings, the rule count and the
#        unimplemented list — because a consumer reading "no findings" is entitled to
#        the same caveat the Markdown prints.
def character_json(slot_no, ch, report=None):
    out = OrderedDict([("slot", slot_no)])
    for key, value in ch.items():
        if value is None or value == [] or value == {}:
            continue
        out[key] = jsonable(value)
    if report is not None:
        out["validation"] = report.as_dict()
    return out
 
 
##
# @brief Build the whole JSON document for a parsed save.
# @param save     A @ref sl2.convert.SaveData.
# @param filename The source filename, recorded so an export can be traced back.
# @param meta     The environment block from @ref parse_meta, or None.
# @param validate Attach each character's validation report (off by default).
# @param data     The file bytes, when the caller has them: the file-level rules read
#                 the container rather than a character.
# @return A dict ready for json.dump.
def build_json(save, filename, meta=None, validate=False, data=None):
    cfg = save.cfg
    source = OrderedDict(
        [
            ("filename", os.path.basename(filename)),
            ("game", save.game),
            ("game_title", cfg["title"]),
            ("support_tier", cfg["tier"]),
        ]
    )
    # What the tier does NOT cover, where the game has a gap a reader would otherwise
    # not guess from the word "full". Only Sekiro has one today.
    if cfg.get("coverage"):
        source["support_tier_coverage"] = cfg["coverage"]
    # Both are properties of the FILE, not of any character, and both are frequently
    # absent — DS2 has no version word, and only ER carries a regulation version.
    if save.version is not None:
        source["save_format_version"] = save.version
    if save.patch is not None:
        source["game_patch"] = save.patch
    # The owning Steam account, where the game records one. The account id is a plain
    # uint32, but the SteamID64 is emitted as TEXT on purpose: it is larger than the
    # integer a JSON parser is obliged to represent exactly, and a consumer reading it
    # into a double would silently lose the last digits.
    if save.owner is not None:
        source["steam_account_id"] = save.owner[0]
        source["steam_id64"] = save.owner[1]
    if save.folder is not None:
        source["save_folder"] = save.folder
 
    doc = OrderedDict(
        [
            ("$schema", SCHEMA_URL),
            ("schema_version", SCHEMA_VERSION),
            ("generated", datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")),
            ("tool", OrderedDict([("name", "sl2-analyzer"), ("url", REPO_URL)])),
            ("source", source),
        ]
    )
    if meta:
        doc["environment"] = OrderedDict(meta)
    doc["characters"] = [
        character_json(
            i - cfg["slots"].start + 1,
            ch,
            run_validation(ch, save.game) if validate else None,
        )
        for i, ch in save.characters
    ]
    if validate and data is not None:
        entries = parse_bnd4(data) or []
        doc["file_validation"] = run_file_validation(
            save.game, entries, data, checksum_ok
        ).as_dict()
    return doc