wireforge 0.1.0__py3-none-any.whl

wireforge/vcs.py

@@ -0,0 +1,44 @@
+"""What git says about a project directory: commit, repository root and local changes."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+GIT_TIMEOUT_SECONDS = 20
+
+
+def _git(directory: Path, *arguments: str) -> str | None:
+    git = shutil.which("git")
+    if git is None:
+        return None
+    try:
+        done = subprocess.run(
+            [git, *arguments],
+            cwd=directory,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=GIT_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout.strip() if done.returncode == 0 else None
+
+
+def commit(directory: Path) -> str | None:
+    """Return the commit the working copy is at (None outside a repository)."""
+    return _git(directory, "rev-parse", "HEAD")
+
+
+def root(directory: Path) -> Path | None:
+    """Return the top directory of the repository."""
+    top = _git(directory, "rev-parse", "--show-toplevel")
+    return Path(top).resolve() if top else None
+
+
+def dirty(directory: Path) -> bool:
+    """Return whether files below `directory` differ from the commit (untracked ones count)."""
+    changes = _git(directory, "status", "--porcelain", "--", ".")
+    return bool(changes)

wireforge/vectors.py

@@ -0,0 +1,222 @@
+"""Requirement test vectors: the user's expectations checked against the reference codec.
+
+A vector is bytes from the ICD with what they must decode to (or what a value must encode to).
+`run()` plays every vector through the reference codec in each profile it applies to and `check()`
+reports the disagreements as SR-22, so a wrong vector or a wrong model is found before code is
+generated. The codec never replaces the user's expectation: the generated C++ test compares with
+what the vector says, not with what the codec answered.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from wireforge import expr
+from wireforge.codec import CodecError, ReferenceCodec
+from wireforge.expr import ExprError
+from wireforge.issues import Issue, errors_only
+from wireforge.loader import load_project
+from wireforge.validate import Validator
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from wireforge.codec import ChecksumPlugin
+    from wireforge.model import Field, Project, Struct, Vector
+
+OK = "Ok"
+NO_PLUGIN = "no plugin for custom checksum"
+
+
+@dataclass(frozen=True)
+class VectorRun:
+    """One vector played through the reference codec in one profile.
+
+    `status` is the codec's answer in `phase` (`decode` or `encode`): the first direction that
+    failed, or the last one that ran when all agree (`Ok`). `decoded` is the decoded value and
+    `encoded` the produced bytes.
+    """
+
+    vector: Vector
+    profile: str | None
+    phase: str
+    status: str
+    detail: str
+    decoded: dict[str, Any] | None
+    encoded: bytes | None
+
+
+def profiles_of(project: Project, vector: Vector) -> list[str | None]:
+    """Return the profiles a vector applies to (all of them unless the vector names one)."""
+    if vector.profile is not None:
+        return [vector.profile]
+    return list(project.profiles) or [None]
+
+
+def f32(value: float) -> float:
+    """Round a number to the nearest 32-bit float."""
+    return float(struct.unpack(">f", struct.pack(">f", value))[0])
+
+
+def _holds(codec: ReferenceCodec, message: Struct) -> bool:
+    if message.condition is None:
+        return True
+    try:
+        return expr.evaluate(expr.parse_condition(message.condition), codec.variant.scope) != 0
+    except ExprError:
+        return True
+
+
+def _decode(codec: ReferenceCodec, vector: Vector, data: bytes) -> tuple[str, str, Any]:
+    try:
+        if vector.interface is None:
+            return OK, "", codec.decode_message(vector.message, data)
+        frame = codec.decode_frame(vector.interface, data)
+    except CodecError as error:
+        return error.status, str(error), None
+    if frame.message != vector.message:
+        return "UnknownMessageId", f"the frame carries message {frame.message}", None
+    return OK, "", frame.value
+
+
+def _encode(codec: ReferenceCodec, vector: Vector) -> tuple[str, str, bytes | None]:
+    value = vector.fields or {}
+    try:
+        if vector.interface is None:
+            return OK, "", codec.encode_message(vector.message, value)
+        return OK, "", codec.encode_frame(vector.interface, vector.message, value)
+    except CodecError as error:
+        return error.status, str(error), None
+
+
+def run(project: Project, plugins: dict[str, ChecksumPlugin] | None = None) -> list[VectorRun]:
+    """Play every well-formed vector through the reference codec, once per profile."""
+    runs: list[VectorRun] = []
+    for vector in project.vectors.values():
+        message = project.messages.get(vector.message)
+        known = vector.interface is None or vector.interface in project.interfaces
+        if message is None or vector.data is None or not known:
+            continue  # the validator reports it (SR-22)
+        for profile in profiles_of(project, vector):
+            if profile is not None and profile not in project.profiles:
+                continue
+            codec = ReferenceCodec(project, profile, plugins)
+            if not _holds(codec, message):
+                continue
+            runs.append(_play(codec, vector, vector.data, profile))
+    return runs
+
+
+def _play(codec: ReferenceCodec, vector: Vector, data: bytes, profile: str | None) -> VectorRun:
+    phase, status, detail, decoded, encoded = "decode", OK, "", None, None
+    if vector.direction in {"decode", "both"}:
+        status, detail, decoded = _decode(codec, vector, data)
+    if vector.direction in {"encode", "both"} and status == OK:
+        phase = "encode"
+        status, detail, encoded = _encode(codec, vector)
+    return VectorRun(vector, profile, phase, status, detail, decoded, encoded)
+
+
+# --- comparison --------------------------------------------------------------------------------
+
+
+def _expected_value(project: Project, item: Field, value: object) -> object:
+    """Round the floats the way the codec does (f32 fields hold 32-bit values)."""
+    inner = project.types.get(item.type)
+    if isinstance(value, list):
+        return [_expected_value(project, _single(item), element) for element in value]
+    if inner is not None and isinstance(value, dict):
+        return _expected_fields(project, inner, value)
+    if item.type == "f32" and isinstance(value, (int, float)) and not isinstance(value, bool):
+        return f32(float(value))
+    return value
+
+
+def _single(item: Field) -> Field:
+    """Return the field as one element (arrays are compared element by element)."""
+    return type(item)(item.name, item.type, item.source)
+
+
+def _expected_fields(project: Project, struct_: Struct, values: dict[str, Any]) -> dict[str, Any]:
+    by_name = {item.name: item for item in struct_.fields}
+    return {
+        name: _expected_value(project, by_name[name], value) if name in by_name else value
+        for name, value in values.items()
+    }
+
+
+def _differences(expected: object, actual: object, path: str) -> list[str]:
+    """List where `actual` differs from `expected` (a mapping is compared by its keys only)."""
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            return [f"{path or 'value'} is {actual!r}, expected {expected!r}"]
+        found: list[str] = []
+        for key, value in expected.items():
+            if key not in actual:
+                found.append(f"{path}{key} is absent, expected {value!r}")
+            else:
+                found += _differences(value, actual[key], f"{path}{key}.")
+        return found
+    if isinstance(expected, list):
+        if not isinstance(actual, list) or len(actual) != len(expected):
+            size = len(actual) if isinstance(actual, list) else actual
+            return [f"{path.rstrip('.')} has {size} elements, expected {len(expected)}"]
+        found = []
+        for index, value in enumerate(expected):
+            found += _differences(value, actual[index], f"{path.rstrip('.')}[{index}].")
+        return found
+    if expected != actual or isinstance(expected, bool) != isinstance(actual, bool):
+        return [f"{path.rstrip('.')} is {actual!r}, expected {expected!r}"]
+    return []
+
+
+def _problems(project: Project, item: VectorRun) -> list[str]:
+    vector = item.vector
+    if vector.status is not None:
+        if item.status == vector.status:
+            return []
+        return [f"decodes with status {item.status}, expected {vector.status}"]
+    if item.status != OK:
+        word = "decodes" if item.phase == "decode" else "encodes"
+        return [f"{word} with status {item.status}, expected Ok"]
+    problems: list[str] = []
+    if item.decoded is not None and vector.fields is not None:
+        message = project.messages[vector.message]
+        expected = _expected_fields(project, message, vector.fields)
+        problems += [f"field {text}" for text in _differences(expected, item.decoded, "")]
+    if item.encoded is not None and item.encoded != vector.data:
+        problems.append(f"encodes to {item.encoded.hex(' ')}, expected {vector.text.strip()}")
+    return problems
+
+
+def check(project: Project, plugins: dict[str, ChecksumPlugin] | None = None) -> list[Issue]:
+    """Return SR-22 issues where the codec and a vector disagree.
+
+    Without plugins a vector that needs a custom checksum is skipped with a warning.
+    """
+    issues: list[Issue] = []
+    for item in run(project, plugins):
+        source = item.vector.source
+        label = f"vector {item.vector.name}"
+        label += f" (profile {item.profile})" if item.profile else ""
+        if NO_PLUGIN in item.detail:
+            text = f"[SR-22] {label}: skipped, a custom checksum needs its plugin"
+            issues.append(Issue(source.file, source.line, source.pointer, text, "warning"))
+            continue
+        issues += [source.issue("SR-22", f"{label}: {text}") for text in _problems(project, item)]
+    return issues
+
+
+def validate_project(
+    location: Path, plugins: dict[str, ChecksumPlugin] | None = None
+) -> list[Issue]:
+    """Load a project and return its structural, semantic and vector issues."""
+    result = load_project(location)
+    if result.project is None:
+        return result.issues
+    issues = result.issues + Validator(result.project).run()
+    if not errors_only(issues):
+        issues += check(result.project, plugins)
+    return issues

wireforge/versioning.py

@@ -0,0 +1,137 @@
+"""File-format identity, compatibility policy and migrations.
+
+Policy (rule SR-19):
+- major newer than this tool supports -> error (upgrade WireForge)
+- major older -> error unless imported through `migrate_document`
+- same major, minor newer than supported -> error
+- generator newer than this tool -> warning only
+"""
+
+from __future__ import annotations
+
+import re
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from wireforge import __version__
+from wireforge.issues import Issue
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, MutableMapping
+
+FORMAT_MAJOR = 1
+FORMAT_MINOR = 2
+GENERATOR_NAME = "wireforge"
+TOOL_VERSION = __version__
+
+_MIGRATIONS: dict[int, Callable[[MutableMapping[str, object]], None]] = {}
+_SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def register_migration(
+    from_major: int, step: Callable[[MutableMapping[str, object]], None]
+) -> None:
+    """Register the step upgrading a document from `from_major` to `from_major + 1` in place."""
+    _MIGRATIONS[from_major] = step
+
+
+@contextmanager
+def temporary_migration(
+    from_major: int, step: Callable[[MutableMapping[str, object]], None]
+) -> Iterator[None]:
+    """Register a migration for the duration of a `with` block (tests and tooling)."""
+    previous = _MIGRATIONS.get(from_major)
+    _MIGRATIONS[from_major] = step
+    try:
+        yield
+    finally:
+        if previous is None:
+            _MIGRATIONS.pop(from_major, None)
+        else:
+            _MIGRATIONS[from_major] = previous
+
+
+def migration_path(from_major: int) -> list[int] | None:
+    """Majors whose steps must run to reach FORMAT_MAJOR, or None when a step is missing."""
+    path = list(range(from_major, FORMAT_MAJOR))
+    return path if all(major in _MIGRATIONS for major in path) else None
+
+
+def _semver_tuple(text: object) -> tuple[int, int, int] | None:
+    match = _SEMVER.match(text) if isinstance(text, str) else None
+    return None if match is None else (int(match[1]), int(match[2]), int(match[3]))
+
+
+def check_document(
+    document: MutableMapping[str, object], *, file: str, line: int | None = None
+) -> list[Issue]:
+    """Apply the compatibility policy to the version stamp of one document."""
+    version = document.get("schema_version")
+    if isinstance(version, bool) or not isinstance(version, int):
+        message = "[SR-19] missing or invalid schema_version: the file does not say its format"
+        return [Issue(file, line, "/schema_version", message)]
+    if version > FORMAT_MAJOR:
+        message = (
+            f"[SR-19] file uses format version {version} but this WireForge {TOOL_VERSION} "
+            f"supports up to {FORMAT_MAJOR}; upgrade WireForge"
+        )
+        return [Issue(file, line, "/schema_version", message)]
+    if version < FORMAT_MAJOR:
+        hint = (
+            "run `wireforge import` to migrate it"
+            if migration_path(version) is not None
+            else "no migration path is available"
+        )
+        message = f"[SR-19] file uses older format version {version}; {hint}"
+        return [Issue(file, line, "/schema_version", message)]
+    issues: list[Issue] = []
+    minor = document.get("schema_minor", 0)
+    if isinstance(minor, int) and minor > FORMAT_MINOR:
+        message = (
+            f"[SR-19] file needs format {version}.{minor} but this WireForge supports "
+            f"{FORMAT_MAJOR}.{FORMAT_MINOR}"
+        )
+        issues.append(Issue(file, line, "/schema_minor", message))
+    generator = document.get("generator")
+    generator_version = generator.get("version") if isinstance(generator, dict) else None
+    written = _semver_tuple(generator_version)
+    current = _semver_tuple(TOOL_VERSION)
+    if written is not None and current is not None and written[:2] > current[:2]:
+        message = (
+            f"file was written by WireForge {generator_version}, newer than {TOOL_VERSION}; "
+            "unknown features may be rejected"
+        )
+        issues.append(Issue(file, line, "/generator", message, severity="warning"))
+    return issues
+
+
+def migrate_document(document: MutableMapping[str, object]) -> list[str]:
+    """Upgrade `document` in place to the current format; returns the applied steps.
+
+    Raises TypeError without an integer schema_version, ValueError when the file is newer than
+    supported or a migration step is missing.
+    """
+    version = document.get("schema_version")
+    if isinstance(version, bool) or not isinstance(version, int):
+        message = "document has no integer schema_version"
+        raise TypeError(message)
+    if version > FORMAT_MAJOR:
+        message = f"format {version} is newer than supported {FORMAT_MAJOR}"
+        raise ValueError(message)
+    path = migration_path(version)
+    if path is None:
+        message = f"no migration path from format {version} to {FORMAT_MAJOR}"
+        raise ValueError(message)
+    applied = []
+    for major in path:
+        _MIGRATIONS[major](document)
+        applied.append(f"format {major} -> {major + 1}")
+    stamp(document)
+    return applied
+
+
+def stamp(document: MutableMapping[str, object]) -> None:
+    """Write the current format and generator stamp into `document`."""
+    document["schema_version"] = FORMAT_MAJOR
+    document["schema_minor"] = FORMAT_MINOR
+    document["generator"] = {"name": GENERATOR_NAME, "version": TOOL_VERSION}