chklib 0.1.0__py3-none-any.whl

chklib/__init__.py

@@ -0,0 +1,47 @@
+"""chklib - a read/write library for StarCraft map data."""
+
+from .chk import SECTION_HEADER_SIZE, Chk, Diagnostic, Section
+from .records import (
+    Action,
+    Condition,
+    IsomRect,
+    Location,
+    Sprite,
+    Trigger,
+    Unit,
+)
+from .views import (
+    Forces,
+    Dimensions,
+    PlayerRaces,
+    PlayerSlots,
+    RecordArrayView,
+    ScenarioProperties,
+    FogGrid,
+    IsomGrid,
+    StringTable,
+    StringTableView,
+    TileGrid,
+    TilesetRef,
+    TriggerListView,
+    Version,
+    string_table_for,
+    isom_for,
+    terrain_for,
+    view_for,
+    TYPED_SECTIONS,
+)
+
+__all__ = [
+    # container
+    "Chk", "Section", "Diagnostic", "SECTION_HEADER_SIZE",
+    # records
+    "Unit", "Sprite", "Location", "Condition", "Action", "Trigger", "IsomRect",
+    # views
+    "Dimensions", "Version", "TilesetRef", "PlayerSlots", "PlayerRaces",
+    "ScenarioProperties", "Forces", "RecordArrayView", "TriggerListView",
+    "StringTableView", "StringTable", "TileGrid", "FogGrid",
+    "IsomGrid", "terrain_for", "isom_for", "string_table_for", "view_for",
+    "TYPED_SECTIONS",
+]
+__version__ = "0.1.0"

chklib/chk.py

@@ -0,0 +1,291 @@
+"""The CHK section container.
+
+A ``scenario.chk`` is a flat sequence of sections, each an 8-byte header -- a
+4-byte name and a signed little-endian 32-bit length -- followed by that many
+payload bytes.
+
+The container below preserves three things that existing CHK readers throw
+away, and that anything claiming to round-trip a map has to keep:
+
+**Order.** StarCraft applies sections in file order, with later sections
+overriding earlier ones of the same name. A reader that returns a mapping has
+already destroyed the information needed to know which one wins.
+
+**Duplicates.** Deliberately duplicated sections are a standard map-protection
+technique. A ``dict[name] -> bytes`` silently keeps one and discards the rest.
+
+**Raw bytes.** Sections this library does not understand -- and sections whose
+declared length disagrees with reality -- survive a read/write cycle untouched.
+
+Malformed input is reported as :class:`Diagnostic` values rather than raised.
+A large share of interesting maps in the wild are malformed on purpose, and a
+parser that refuses them is useless for exactly the maps people care about.
+
+``Chk.from_bytes(raw).to_bytes() == raw`` holds for every input, including
+truncated and protected files. That is guaranteed by construction: each section
+re-emits its own verbatim header fields and payload, and anything the parser
+could not interpret is preserved in :attr:`Chk.trailing`.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Iterator, Sequence
+
+__all__ = ["Chk", "Section", "Diagnostic", "SECTION_HEADER_SIZE"]
+
+SECTION_HEADER_SIZE = 8
+
+_NAME_STRUCT = struct.Struct("<4si")
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """Something notable about the input, reported rather than raised."""
+
+    code: str
+    message: str
+    offset: int
+    severity: str = "warning"
+
+    def __str__(self) -> str:
+        return f"{self.severity}: {self.code} at 0x{self.offset:X}: {self.message}"
+
+
+@dataclass(frozen=True, slots=True)
+class Section:
+    """One CHK section, exactly as it appeared in the file."""
+
+    name: bytes
+    """The 4 name bytes verbatim. Not necessarily printable ASCII."""
+
+    declared_size: int
+    """The header's signed int32 length, verbatim -- may disagree with ``data``."""
+
+    data: bytes
+    """The payload bytes actually present in the file."""
+
+    offset: int
+    """Byte offset of this section's header within the source."""
+
+    @property
+    def label(self) -> str:
+        """A printable name for display. Non-printable bytes become ``.``."""
+        return "".join(
+            chr(b) if 0x20 <= b < 0x7F else "." for b in self.name
+        )
+
+    @property
+    def key(self) -> bytes:
+        """The name with trailing spaces stripped, e.g. ``b'VER'`` for ``b'VER '``."""
+        return self.name.rstrip(b" ")
+
+    @property
+    def is_truncated(self) -> bool:
+        """True when the file ended before ``declared_size`` bytes were available."""
+        return len(self.data) != self.declared_size
+
+    @property
+    def header_bytes(self) -> bytes:
+        return _NAME_STRUCT.pack(self.name, self.declared_size)
+
+    def to_bytes(self) -> bytes:
+        return self.header_bytes + self.data
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        trunc = (
+            f", truncated(declared={self.declared_size})" if self.is_truncated else ""
+        )
+        return (
+            f"Section({self.label!r}, {len(self.data)} bytes"
+            f"{trunc}, offset=0x{self.offset:X})"
+        )
+
+
+def _normalize(name: str | bytes) -> bytes:
+    """Accept ``'VER'``, ``'VER '`` or ``b'VER '`` and return the 4-byte form."""
+    raw = name.encode("ascii") if isinstance(name, str) else bytes(name)
+    if len(raw) > 4:
+        raise ValueError(f"section name must be at most 4 bytes, got {raw!r}")
+    return raw.ljust(4, b" ")
+
+
+@dataclass(slots=True)
+class Chk:
+    """An ordered, duplicate-preserving sequence of CHK sections."""
+
+    sections: list[Section] = field(default_factory=list)
+    """Every section, in file order, duplicates included."""
+
+    trailing: bytes = b""
+    """Bytes after the last section the parser could interpret."""
+
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    """Problems found while parsing. Never raised."""
+
+    # -- reading ----------------------------------------------------------
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> "Chk":
+        """Parse ``raw``. Never raises on malformed input."""
+        sections: list[Section] = []
+        diagnostics: list[Diagnostic] = []
+        trailing = b""
+        total = len(raw)
+        offset = 0
+
+        while offset + SECTION_HEADER_SIZE <= total:
+            name, declared = _NAME_STRUCT.unpack_from(raw, offset)
+            body = offset + SECTION_HEADER_SIZE
+
+            if declared < 0:
+                # A negative length is not a size; it is a backwards jump used
+                # by "jump section" protectors. Following it would mean
+                # emulating StarCraft's parser, including its overlaps. We stop
+                # and keep the remainder verbatim so the file still round-trips.
+                diagnostics.append(
+                    Diagnostic(
+                        "negative-section-length",
+                        f"section {name!r} declares length {declared}; stopping and "
+                        f"preserving the remaining {total - offset} bytes verbatim",
+                        offset,
+                        "error",
+                    )
+                )
+                trailing = raw[offset:]
+                offset = total
+                break
+
+            end = body + declared
+            if end > total:
+                available = total - body
+                diagnostics.append(
+                    Diagnostic(
+                        "truncated-section",
+                        f"section {name!r} declares {declared} bytes but only "
+                        f"{available} remain",
+                        offset,
+                        "error",
+                    )
+                )
+                sections.append(Section(name, declared, raw[body:], offset))
+                offset = total
+                break
+
+            sections.append(Section(name, declared, raw[body:end], offset))
+            offset = end
+
+        if offset < total and not trailing:
+            trailing = raw[offset:]
+            diagnostics.append(
+                Diagnostic(
+                    "trailing-bytes",
+                    f"{len(trailing)} bytes after the last section are too few to "
+                    f"form a {SECTION_HEADER_SIZE}-byte header",
+                    offset,
+                )
+            )
+
+        chk = cls(sections=sections, trailing=trailing, diagnostics=diagnostics)
+        chk._diagnose_names()
+        return chk
+
+    def _diagnose_names(self) -> None:
+        for section in self.sections:
+            if any(b < 0x20 or b >= 0x7F for b in section.name):
+                self.diagnostics.append(
+                    Diagnostic(
+                        "non-printable-section-name",
+                        f"section name {section.name!r} is not printable ASCII",
+                        section.offset,
+                    )
+                )
+
+    # -- writing ----------------------------------------------------------
+
+    def to_bytes(self) -> bytes:
+        """Serialize. Round-trips byte-exactly if nothing has been modified."""
+        return b"".join(s.to_bytes() for s in self.sections) + self.trailing
+
+    def replace_section(self, name: str | bytes, data: bytes) -> Section:
+        """Replace the payload of the *effective* section ``name``.
+
+        The effective section is the last one with that name, matching the
+        override order StarCraft applies. Earlier duplicates are left alone --
+        they are still what the file contained, and collapsing them would be a
+        silent edit.
+
+        Returns the new :class:`Section`. Raises :class:`KeyError` if absent.
+        """
+        wanted = _normalize(name)
+        for index in range(len(self.sections) - 1, -1, -1):
+            section = self.sections[index]
+            if section.name == wanted:
+                replacement = Section(wanted, len(data), bytes(data), section.offset)
+                self.sections[index] = replacement
+                return replacement
+        raise KeyError(f"no {wanted!r} section to replace")
+
+    def add_section(self, name: str | bytes, data: bytes) -> Section:
+        """Append a new section. Its offset is recorded as the current end."""
+        wanted = _normalize(name)
+        section = Section(wanted, len(data), bytes(data), len(self.to_bytes()))
+        self.sections.append(section)
+        return section
+
+    # -- lookup -----------------------------------------------------------
+
+    def find(self, name: str | bytes) -> list[Section]:
+        """Every section with this name, in file order."""
+        wanted = _normalize(name)
+        return [s for s in self.sections if s.name == wanted]
+
+    def last(self, name: str | bytes) -> Section | None:
+        """The section StarCraft would use: the last one with this name.
+
+        Later sections override earlier ones, so this is the effective value.
+        Returns ``None`` when absent.
+        """
+        wanted = _normalize(name)
+        for section in reversed(self.sections):
+            if section.name == wanted:
+                return section
+        return None
+
+    def __contains__(self, name: str | bytes) -> bool:
+        return self.last(name) is not None
+
+    def __iter__(self) -> Iterator[Section]:
+        return iter(self.sections)
+
+    def __len__(self) -> int:
+        return len(self.sections)
+
+    # -- summary ----------------------------------------------------------
+
+    @property
+    def duplicated_names(self) -> list[bytes]:
+        """Names appearing more than once, in first-appearance order."""
+        seen: dict[bytes, int] = {}
+        for section in self.sections:
+            seen[section.name] = seen.get(section.name, 0) + 1
+        return [name for name, count in seen.items() if count > 1]
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == "error" for d in self.diagnostics)
+
+    def describe(self) -> str:
+        """A short human-readable summary. Not the ``inspect`` output format."""
+        lines = [f"{len(self.sections)} sections, {len(self.to_bytes())} bytes"]
+        for section in self.sections:
+            lines.append(f"  {section.label}  {len(section.data):>8} bytes")
+        if self.trailing:
+            lines.append(f"  <trailing> {len(self.trailing):>8} bytes")
+        for diagnostic in self.diagnostics:
+            lines.append(f"  ! {diagnostic}")
+        return "\n".join(lines)

chklib/cli.py

@@ -0,0 +1,312 @@
+"""``chkdiff`` -- command line entry point.
+
+``inspect`` and ``diff`` are the tools; ``pack`` and ``unpack`` move a scenario
+in and out of a map archive; ``textconv`` and ``install-textconv`` wire the whole
+thing into ``git diff``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import pathlib
+import sys
+
+from . import __version__
+from .chk import Chk
+from .diff import diff
+from .inspect import FORMAT_VERSION, render
+from .mpq import (
+    MpqArchive,
+    MpqError,
+    SCENARIO_PATH,
+    looks_like_mpq,
+    write_scenario,
+)
+
+__all__ = ["main"]
+
+
+def _load(path: pathlib.Path) -> Chk:
+    """Read a bare ``scenario.chk``, or pull one out of a ``.scm``/``.scx``.
+
+    Map files in a repository are MPQ archives, so accepting them directly is
+    what makes the git integration possible at all.
+    """
+    raw = path.read_bytes()
+    if looks_like_mpq(raw):
+        try:
+            raw = MpqArchive(raw).read_file(SCENARIO_PATH)
+        except MpqError as exc:
+            raise SystemExit(f"{path}: {exc}") from exc
+    return Chk.from_bytes(raw)
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    path = pathlib.Path(args.path)
+    if not path.is_file():
+        raise SystemExit(f"not a file: {path}")
+    chk = _load(path)
+    # --stable omits the source line: git's textconv passes a temporary filename
+    # that changes on every invocation and would appear as a spurious diff.
+    source = None if args.stable else str(path)
+    sys.stdout.write(render(chk, source=source))
+    if args.strict and chk.has_errors:
+        for diagnostic in chk.diagnostics:
+            if diagnostic.severity == "error":
+                print(f"error: {diagnostic}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    left, right = pathlib.Path(args.a), pathlib.Path(args.b)
+    for path in (left, right):
+        if not path.is_file():
+            raise SystemExit(f"not a file: {path}")
+    report = diff(_load(left), _load(right))
+    sys.stdout.write(report.to_json() if args.json else report.to_text())
+    # Exit codes follow diff(1): 0 identical, 1 differences found.
+    return 0 if report.is_empty else 1
+
+
+def _cmd_unpack(args: argparse.Namespace) -> int:
+    """Extract ``staredit\\scenario.chk`` from a map archive."""
+    source = pathlib.Path(args.map)
+    if not source.is_file():
+        raise SystemExit(f"not a file: {source}")
+    raw = source.read_bytes()
+    if not looks_like_mpq(raw):
+        raise SystemExit(f"{source} is not an MPQ archive")
+    try:
+        chk = MpqArchive(raw).read_file(SCENARIO_PATH)
+    except MpqError as exc:
+        raise SystemExit(f"{source}: {exc}") from exc
+    destination = pathlib.Path(args.out)
+    destination.write_bytes(chk)
+    print(f"wrote {destination} ({len(chk)} bytes)")
+    return 0
+
+
+def _cmd_pack(args: argparse.Namespace) -> int:
+    """Wrap a ``scenario.chk`` into a playable map archive."""
+    source = pathlib.Path(args.chk)
+    if not source.is_file():
+        raise SystemExit(f"not a file: {source}")
+    raw = source.read_bytes()
+    if looks_like_mpq(raw):
+        raise SystemExit(f"{source} is already an archive; did you mean unpack?")
+
+    # Refuse to emit something the reader cannot make sense of. A map that fails
+    # to parse here will fail in StarCraft too, and silently writing it wastes
+    # the user's time later rather than now.
+    chk = Chk.from_bytes(raw)
+    if chk.has_errors and not args.force:
+        for diagnostic in chk.diagnostics:
+            if diagnostic.severity == "error":
+                print(f"error: {diagnostic}", file=sys.stderr)
+        raise SystemExit(
+            f"{source} has parse errors; pass --force to pack it anyway"
+        )
+
+    destination = pathlib.Path(args.out)
+    archive = write_scenario(raw, compress=args.compress)
+    destination.write_bytes(archive)
+    ratio = f", {len(archive) / len(raw):.0%} of the scenario" if raw else ""
+    print(f"wrote {destination} ({len(archive)} bytes{ratio})")
+    return 0
+
+
+def _cmd_textconv(args: argparse.Namespace) -> int:
+    """The git textconv driver. Must never fail.
+
+    Git runs this over every blob on both sides of a diff, including historical
+    ones that may be truncated, protected, or not maps at all. A driver that
+    exits non-zero or raises makes ``git diff`` fail outright, so anything
+    unreadable degrades to a short deterministic note instead.
+
+    The note is deliberately content-derived rather than error-derived: two
+    unreadable blobs with the same bytes must produce the same text, or the diff
+    churns.
+    """
+    path = pathlib.Path(args.path)
+    try:
+        chk = _load(path)
+    except SystemExit as exc:
+        # _load raises SystemExit with a human message; keep the reason but not
+        # the path, which git randomises per invocation.
+        reason = str(exc).replace(str(path), "").lstrip(": ").strip()
+        sys.stdout.write(f"# chklib: unreadable ({reason})\n")
+        return 0
+    except Exception as exc:  # noqa: BLE001 - a driver must not propagate
+        sys.stdout.write(f"# chklib: unreadable ({type(exc).__name__})\n")
+        return 0
+    sys.stdout.write(render(chk, source=None))
+    return 0
+
+
+_GIT_SETUP = """\
+# 1. Tell git how to render a map as text (once per machine, or --local):
+git config --global diff.starcraft.textconv "chkdiff textconv"
+git config --global diff.starcraft.binary false
+
+# 2. Tell git which files that applies to. In .gitattributes:
+*.scm diff=starcraft
+*.scx diff=starcraft
+*.chk diff=starcraft
+"""
+
+
+def _cmd_install_textconv(args: argparse.Namespace) -> int:
+    scope = "--local" if args.local else "--global"
+    if not args.write:
+        sys.stdout.write(_GIT_SETUP)
+        sys.stdout.write(
+            "\nRe-run with --write to apply the git config, and --local to scope"
+            " it to this repository.\n"
+        )
+        return 0
+
+    import subprocess
+
+    for key, value in (
+        ("diff.starcraft.textconv", "chkdiff textconv"),
+        ("diff.starcraft.binary", "false"),
+    ):
+        result = subprocess.run(
+            ["git", "config", scope, key, value],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            raise SystemExit(f"git config failed: {result.stderr.strip()}")
+        print(f"set {key} = {value!r} ({scope})")
+    print("\nNow add these lines to .gitattributes:")
+    print("  *.scm diff=starcraft")
+    print("  *.scx diff=starcraft")
+    print("  *.chk diff=starcraft")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="chkdiff",
+        description="Inspect and compare StarCraft scenario data.",
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version=f"chkdiff {__version__} (inspect format v{FORMAT_VERSION})",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inspect = sub.add_parser(
+        "inspect",
+        help="print a stable, deterministic rendering of a scenario",
+        description=(
+            "Print a deterministic textual rendering of a scenario.chk. "
+            "Suitable as a git textconv driver, in which case pass --stable."
+        ),
+    )
+    inspect.add_argument("path", help="path to a scenario.chk")
+    inspect.add_argument(
+        "--stable", action="store_true",
+        help="omit the source filename, for reproducible output (use for git textconv)",
+    )
+    inspect.add_argument(
+        "--strict", action="store_true",
+        help="exit non-zero if the file has parse errors",
+    )
+    inspect.set_defaults(func=_cmd_inspect)
+
+    compare = sub.add_parser(
+        "diff",
+        help="compare two scenarios semantically",
+        description=(
+            "Compare two scenario.chk files by meaning rather than by bytes. "
+            "Exit status follows diff(1): 0 when identical, 1 when they differ."
+        ),
+    )
+    compare.add_argument("a", help="path to the first scenario.chk")
+    compare.add_argument("b", help="path to the second scenario.chk")
+    compare.add_argument(
+        "--json", action="store_true",
+        help="emit machine-readable JSON instead of text",
+    )
+    compare.set_defaults(func=_cmd_diff)
+
+    unpack = sub.add_parser(
+        "unpack", help="extract scenario.chk from a .scm/.scx map archive"
+    )
+    unpack.add_argument("map", help="path to a .scm or .scx")
+    unpack.add_argument("out", help="path to write scenario.chk to")
+    unpack.set_defaults(func=_cmd_unpack)
+
+    pack = sub.add_parser(
+        "pack",
+        help="wrap a scenario.chk into a .scm/.scx map archive",
+        description=(
+            "Wrap a scenario.chk into a map archive. Stores the scenario "
+            "uncompressed by default, which every reader accepts; --compress "
+            "uses zlib, which is what euddraft writes for production maps."
+        ),
+    )
+    pack.add_argument("chk", help="path to a scenario.chk")
+    pack.add_argument("out", help="path to write the map archive to")
+    pack.add_argument(
+        "--compress", action="store_true", help="zlib-compress the scenario"
+    )
+    pack.add_argument(
+        "--force", action="store_true", help="pack even if the scenario has parse errors"
+    )
+    pack.set_defaults(func=_cmd_pack)
+
+    textconv = sub.add_parser(
+        "textconv",
+        help="render a map for git's diff.<driver>.textconv",
+        description=(
+            "Render a map as deterministic text for git. Always exits 0 and "
+            "always prints something, because a textconv driver that fails "
+            "makes git diff fail."
+        ),
+    )
+    textconv.add_argument("path", help="path to a map or scenario.chk")
+    textconv.set_defaults(func=_cmd_textconv)
+
+    install = sub.add_parser(
+        "install-textconv",
+        help="print (or apply) the git configuration for map diffs",
+    )
+    install.add_argument(
+        "--write", action="store_true", help="run the git config commands"
+    )
+    install.add_argument(
+        "--local", action="store_true",
+        help="scope the config to this repository instead of the whole machine",
+    )
+    install.set_defaults(func=_cmd_install_textconv)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:
+        # A downstream consumer closed the pipe -- `chkdiff diff x y | head` is
+        # completely normal usage. Python would otherwise flush stdout again at
+        # shutdown and print a second traceback to stderr, so point the fd at
+        # devnull first. 128 + SIGPIPE(13) is the conventional status.
+        devnull = None
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+        except (OSError, AttributeError, ValueError):
+            # stdout may not be a real file (a test double, or already closed).
+            # There is nothing useful left to do, and raising here would defeat
+            # the purpose of catching BrokenPipeError in the first place.
+            if devnull is not None:
+                os.close(devnull)
+        return 141
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())