wireforge 0.1.0__py3-none-any.whl

wireforge/generate.py

@@ -0,0 +1,644 @@
+"""C++17 code generator: data types, defaults, validation and wire sizes of a project.
+
+Output (relative to the output directory):
+- `<project>/user_prelude.hpp`: application headers, prelude lines and checks of user constants;
+- `<project>/model.hpp`: defines, enums, structs and messages with `validate()`,
+  `min_wire_size()` and `max_wire_size()` overloads.
+
+The output depends only on the model, never on the profile: profile differences are expressed with
+`#if` blocks and overridable define constants, so one generated tree serves every profile.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from wireforge import bundle, test_project, versioning
+from wireforge.cpp import Names, Writer, guard, plain_count, string_literal, wire_only
+from wireforge.cpp_codec import CodecWriter, checksum_type
+from wireforge.cpp_interface import InterfaceError, InterfaceHeader
+from wireforge.issues import Issue
+from wireforge.llr import requirement_notes
+from wireforge.loader import load_project
+from wireforge.model import BUILTIN_BITS, Field, Project, Scalar, Source, Struct, UserConstant
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+BYTE_BITS = 8
+RUNTIME_HEADERS = (
+    "wireforge/bit_utils.hpp",
+    "wireforge/byte_io.hpp",
+    "wireforge/checksum.hpp",
+    "wireforge/codec_support.hpp",
+    "wireforge/expr_support.hpp",
+    "wireforge/span.hpp",
+    "wireforge/static_vector.hpp",
+    "wireforge/status.hpp",
+    "wireforge/validation.hpp",
+)
+
+
+@dataclass(frozen=True)
+class Banner:
+    """Identity of the generated files."""
+
+    project: str
+    version: str | None
+    content_hash: str
+
+    def lines(self) -> list[str]:
+        """Doxygen paragraph describing the generator run."""
+        version = f" {self.version}" if self.version else ""
+        tool = (
+            f"WireForge {versioning.TOOL_VERSION} (file format "
+            f"{versioning.FORMAT_MAJOR}.{versioning.FORMAT_MINOR})"
+        )
+        return [
+            f" * Generated by {tool} from project {self.project}{version}.",
+            f" * Model hash: {self.content_hash}.",
+            " * Do not edit; regenerate instead.",
+        ]
+
+
+def source_text(project: Project, source: Source) -> str:
+    """Return `file:line` of a model element, relative to the project directory."""
+    root = Path(project.source.file).parent
+    relative = Path(os.path.relpath(source.file, root)).as_posix()
+    return f"{relative}:{source.line}" if source.line is not None else relative
+
+
+def _namespace(project: Project) -> str:
+    return project.namespace or project.name
+
+
+def _description(text: str | None, fallback: str) -> str:
+    return " ".join((text or fallback).split())
+
+
+def _type_order(project: Project) -> list[Struct]:
+    """Types sorted so that every type comes after the types it contains."""
+    ordered: list[Struct] = []
+    seen: set[str] = set()
+
+    def visit(name: str) -> None:
+        if name in seen:
+            return
+        seen.add(name)
+        for item in project.types[name].fields:
+            if item.type in project.types:
+                visit(item.type)
+        ordered.append(project.types[name])
+
+    for name in project.types:
+        visit(name)
+    return ordered
+
+
+class _ModelHeader:
+    """Writes model.hpp."""
+
+    def __init__(self, project: Project, banner: Banner, notes: dict[str, list[str]]) -> None:
+        self.project = project
+        self.names = Names(project)
+        self.banner = banner
+        self.notes = notes
+        self.out = Writer()
+        self.codec = CodecWriter(project, self.out)
+
+    def render(self) -> str:
+        out = self.out
+        name = self.project.name
+        out.line("/**")
+        out.line(f" * @file {name}/model.hpp")
+        out.line(f" * @brief Data types of the {name} messages: defaults, validation, codec.")
+        out.line(" *")
+        for text in self.banner.lines():
+            out.line(text)
+        out.line(" */")
+        out.line(f"#ifndef {guard(name, 'MODEL_HPP')}")
+        out.line(f"#define {guard(name, 'MODEL_HPP')}")
+        out.line()
+        out.line(f'#include "{name}/user_prelude.hpp"')
+        out.line()
+        for header in RUNTIME_HEADERS:
+            out.line(f"#include <{header}>")
+        out.line()
+        custom = sorted({c.include for c in self.project.checksums.values() if c.include})
+        for header in custom:
+            out.line(f'#include "{header}"')
+        if custom:
+            out.line()
+        for header in ("array", "cstddef", "cstdint"):
+            out.line(f"#include <{header}>")
+        out.line()
+        out.line(f"/// @brief Generated code of project {name}.")
+        out.line(f"namespace {_namespace(self.project)} {{")
+        out.line()
+        self.defines()
+        self.checksums()
+        self.enums()
+        for item in _type_order(self.project):
+            self.struct(item, "Type")
+        for item in self.project.messages.values():
+            self.struct(item, "Message")
+        out.line(f"}} // namespace {_namespace(self.project)}")
+        out.line()
+        out.line(f"#endif // {guard(name, 'MODEL_HPP')}")
+        return out.text()
+
+    # --- defines and enums ----------------------------------------------------------------------
+
+    def defines(self) -> None:
+        if not self.project.defines:
+            return
+        out = self.out
+        out.line("/// @brief Model defines; each can be overridden with -D<NAME>=<value>.")
+        out.line("namespace defines {")
+        out.line()
+        for define in self.project.defines.values():
+            out.line(f"#if defined({define.name})")
+            out.line(f"inline constexpr std::int64_t k{define.name} = {define.name};")
+            out.line("#else")
+            out.line(f"/// @brief Value of define {define.name} (default {define.value}).")
+            out.line(f"inline constexpr std::int64_t k{define.name} = {define.value};")
+            out.line("#endif")
+        out.line()
+        out.line("} // namespace defines")
+        out.line()
+
+    def note(self, owner: str) -> None:
+        """Write the requirement trace of an element (nothing without a requirements catalog)."""
+        for text in self.notes.get(owner, ()):
+            self.out.line(text)
+
+    def checksums(self) -> None:
+        if not self.project.checksums:
+            return
+        out = self.out
+        out.line("/// @brief Checksum algorithms of the model.")
+        out.line("namespace checksums {")
+        out.line()
+        for checksum in self.project.checksums.values():
+            out.line(f"/// @brief Checksum {checksum.name} ({checksum.algo}).")
+            self.note(checksum.name)
+            out.line(f"using {checksum.name} = {checksum_type(checksum)};")
+            out.line(
+                f"static_assert(wireforge::is_checksum_v<{checksum.name}>, "
+                f'"{checksum.name} must satisfy the checksum contract");'
+            )
+        out.line()
+        out.line("} // namespace checksums")
+        out.line()
+
+    def enums(self) -> None:
+        out = self.out
+        for enum in self.project.enums.values():
+            underlying = self.names.scalar(enum.type)
+            out.line(f"/// @brief Enumeration {enum.name}.")
+            self.note(enum.name)
+            out.line(f"enum class {enum.name} : {underlying} {{")
+            out.indent()
+            signed = enum.type.startswith("i")
+            for member, value in enum.values.items():
+                literal = str(value) if signed or value < 0 else f"{value}U"
+                out.line(f"{member} = {literal}, ///< {member}")
+            out.dedent()
+            out.line("};")
+            out.line()
+            out.line(f"/// @brief true when @p value is a member of {enum.name}.")
+            out.line(f"[[nodiscard]] constexpr bool is_valid({enum.name} value) noexcept {{")
+            out.indent()
+            # A comparison chain, not a switch: a switch over every member needs a default label
+            # that compilers with -Wcovered-switch-default reject.
+            terms = [f"value == {enum.name}::{member}" for member in enum.values]
+            for position, term in enumerate(terms):
+                joiner = " ||" if position < len(terms) - 1 else ";"
+                prefix = "return " if position == 0 else "       "
+                out.line(f"{prefix}{term}{joiner}")
+            out.dedent()
+            out.line("}")
+            out.line()
+
+    # --- structs --------------------------------------------------------------------------------
+
+    def conditional(self, item: Field, lines: Iterable[str]) -> None:
+        lines = list(lines)
+        if not lines:
+            return
+        if item.condition is not None:
+            self.out.line(f"#if {self.names.condition(item.condition)}")
+        for text in lines:
+            self.out.line(text)
+        if item.condition is not None:
+            self.out.line("#endif")
+
+    def struct(self, item: Struct, kind: str) -> None:
+        out = self.out
+        hidden = wire_only(item)
+        if item.condition is not None:
+            out.line(f"#if {self.names.condition(item.condition)}")
+        out.line(f"/// @brief {_description(item.description, f'{kind} {item.name}.')}")
+        out.line(
+            f"/// Defined in {source_text(self.project, item.source)} ({item.source.pointer})."
+        )
+        self.note(item.name)
+        out.line(f"struct {item.name} {{")
+        out.indent()
+        for field in item.fields:
+            if field.name not in hidden:
+                self.conditional(field, [self.member(field)])
+        out.dedent()
+        out.line("};")
+        out.line()
+        self.validate(item, hidden)
+        self.sizes(item)
+        self.codec.encode_struct(item)
+        self.codec.decode_struct(item)
+        if item.message is not None:
+            self.codec.message_api(item)
+        if item.condition is not None:
+            out.line("#endif")
+            out.line()
+
+    def member(self, item: Field) -> str:
+        names = self.names
+        doc = _description(item.description, item.name)
+        if item.units:
+            doc += f" [{item.units}]"
+        doc += f" ({source_text(self.project, item.source)})"
+        return f"{names.member_type(item)} {item.name}{self.initializer(item)}; ///< {doc}"
+
+    def initializer(self, item: Field) -> str:
+        default = item.default
+        dynamic = item.occurs is not None and (
+            item.occurs.count is not None or item.occurs.fill or item.type == "char"
+        )
+        if default is None:
+            return "" if dynamic else "{}"
+        if item.occurs is None:
+            single = default if not isinstance(default, list) else None
+            return "{}" if single is None else f"{{{self.names.literal(item, single)}}}"
+        return self.array_initializer(item, default, dynamic=dynamic)
+
+    def array_initializer(
+        self, item: Field, default: Scalar | list[Scalar], *, dynamic: bool
+    ) -> str:
+        names = self.names
+        if item.type == "char" and isinstance(default, str):
+            return f"{{{string_literal(default)}}}"
+        if isinstance(default, list):
+            values = ", ".join(names.literal(item, value) for value in default)
+            return f"{{{values}}}" if dynamic else f"{{{{{values}}}}}"
+        if dynamic or item.occurs is None:
+            return ""  # a dynamic array starts empty; the default applies to new elements
+        element = names.scalar(item.type)
+        capacity = names.capacity(item.occurs.max)
+        return f"{{wireforge::filled<{element}, {capacity}>({names.literal(item, default)})}}"
+
+    # --- validate -------------------------------------------------------------------------------
+
+    def value_checks(self, item: Field, subject: str, members: set[str]) -> list[str]:
+        """Return the checks of one scalar value (`subject` is its C++ expression)."""
+        names = self.names
+        checks: list[str] = []
+        if item.type in self.project.enums:
+            checks.append(f"wireforge::check_true(is_valid({subject}))")
+        base = names.base(item.type)
+        if item.bits is not None and item.bits < BUILTIN_BITS[base] and base in BUILTIN_BITS:
+            value = subject
+            if item.type in self.project.enums:
+                value = f"static_cast<{names.scalar(base)}>({subject})"
+            if base != "bool":
+                checks.append(f"wireforge::check_bits({value}, {item.bits}U)")
+        checks += self.bound_checks(item, subject, members)
+        return checks
+
+    def bound_checks(self, item: Field, subject: str, members: set[str]) -> list[str]:
+        names = self.names
+        limits = names.type_limits(item)
+        low, high = item.min, item.max
+        if limits is not None and isinstance(low, int) and low <= limits[0]:
+            low = None
+        if limits is not None and isinstance(high, int) and high >= limits[1]:
+            high = None
+        if low is not None and high is not None:
+            bounds = f"{names.bound(item, low, members)}, {names.bound(item, high, members)}"
+            return [f"wireforge::check_range({subject}, {bounds})"]
+        if low is not None:
+            return [f"wireforge::check_min({subject}, {names.bound(item, low, members)})"]
+        if high is not None:
+            return [f"wireforge::check_max({subject}, {names.bound(item, high, members)})"]
+        return []
+
+    def field_checks(self, item: Field, owner: Struct, members: set[str]) -> list[str]:
+        subject = f"value.{item.name}"
+        if item.occurs is None:
+            if self.names.is_struct(item):
+                return [f"validate({subject})"]
+            return self.value_checks(item, subject, members)
+        checks = self.count_checks(item, owner, members)
+        if self.names.is_struct(item):
+            checks.append(f"wireforge::validate_each({subject})")
+        elif item.type != "char":
+            inner = self.value_checks(item, "element", members)
+            if inner:
+                element = self.names.scalar(item.type)
+                body = (
+                    inner[0] if len(inner) == 1 else f"wireforge::first_error({', '.join(inner)})"
+                )
+                checks.append(
+                    f"wireforge::check_each({subject}, [](const {element}& element) "
+                    f"{{ return {body}; }})"
+                )
+        return checks
+
+    def count_checks(self, item: Field, owner: Struct, members: set[str]) -> list[str]:
+        occurs = item.occurs
+        if occurs is None or (occurs.count is None and not occurs.fill):
+            return []
+        names = self.names
+        size = f"value.{item.name}.size()"
+        checks = []
+        low = occurs.min or 0
+        if low != 0:
+            bounds = f"{names.capacity(low)}, {names.capacity(occurs.max)}"
+            checks.append(f"wireforge::check_count({size}, {bounds})")
+        counter = plain_count(item)
+        if counter is None and occurs.count is not None:
+            checks.append(
+                f"wireforge::check_count_equals({size}, {names.value(occurs.count, members)})"
+            )
+        elif counter is not None and counter not in members:
+            checks += self.counter_checks(item, owner, counter, size)
+        return checks
+
+    def counter_checks(self, item: Field, owner: Struct, counter: str, size: str) -> list[str]:
+        """Range of a wire-only count field, and equal sizes of arrays sharing it."""
+        target = next(field for field in owner.fields if field.name == counter)
+        checks = self.bound_checks(target, size, set())
+        first = next(field for field in owner.fields if plain_count(field) == counter)
+        if first.name != item.name:
+            checks.append(
+                f"wireforge::check_count_equals({size}, "
+                f"static_cast<std::int64_t>(value.{first.name}.size()))"
+            )
+        return checks
+
+    def validate(self, item: Struct, hidden: set[str]) -> None:
+        out = self.out
+        members = {field.name for field in item.fields if field.name not in hidden}
+        out.line("/// @brief Checks ranges, enum values and element counts of @p value.")
+        signature = f"constexpr wireforge::Status validate(const {item.name}& value) noexcept"
+        out.line(f"[[nodiscard]] {signature} {{")
+        out.indent()
+        blocks = [
+            (field, self.field_checks(field, item, members))
+            for field in item.fields
+            if field.name not in hidden
+        ]
+        if not any(checks for _, checks in blocks):
+            out.line("static_cast<void>(value);")
+            out.line("return wireforge::Status::Ok;")
+        else:
+            out.line("return wireforge::first_error(")
+            out.indent()
+            for field, checks in blocks:
+                self.conditional(field, [f"{check}," for check in checks] if checks else [])
+            out.line("wireforge::Status::Ok);")
+            out.dedent()
+        out.dedent()
+        out.line("}")
+        out.line()
+
+    # --- wire sizes -----------------------------------------------------------------------------
+
+    def group_bits(self, item: Field) -> int | None:
+        if item.occurs is not None:
+            return None
+        if item.bits is not None:
+            return item.bits
+        inner = self.project.types.get(item.type)
+        if inner is None or not inner.fields or any(f.bits is None for f in inner.fields):
+            return None
+        return sum(f.bits or 0 for f in inner.fields)
+
+    def element_size(self, item: Field, which: str) -> str:
+        if item.type in self.project.types or item.type in self.project.user_types:
+            cpp_name = self.names.scalar(item.type)
+            return f"{which}_wire_size(wireforge::type_tag<{cpp_name}>)"
+        return f"{BUILTIN_BITS[self.names.base(item.type)] // BYTE_BITS}U"
+
+    def field_size(self, item: Field, which: str) -> str:
+        element = self.element_size(item, which)
+        occurs = item.occurs
+        if occurs is None:
+            return element
+        dynamic = occurs.count is not None or occurs.fill
+        count = occurs.max if which == "max" or not dynamic else (occurs.min or 0)
+        if count == 0:
+            return "0U"
+        if isinstance(count, int):
+            return f"std::size_t{{{count}U}} * {element}"
+        return f"{self.names.capacity(count)} * {element}"
+
+    def size_lines(self, item: Struct, which: str) -> list[tuple[Field, str]]:
+        lines: list[tuple[Field, str]] = []
+        group: list[Field] = []
+        for field in [*item.fields, None]:
+            bits = None if field is None else self.group_bits(field)
+            if bits is not None and field is not None:
+                group.append(field)
+                continue
+            if group:
+                total = sum(self.group_bits(member) or 0 for member in group)
+                lines.append((group[0], f"{(total + BYTE_BITS - 1) // BYTE_BITS}U"))
+                group = []
+            if field is not None:
+                lines.append((field, self.field_size(field, which)))
+        return lines
+
+    def sizes(self, item: Struct) -> None:
+        out = self.out
+        for which, text in (("min", "Smallest"), ("max", "Largest")):
+            out.line(f"/// @brief {text} encoded size of {item.name} in bytes.")
+            out.line(
+                f"[[nodiscard]] constexpr std::size_t {which}_wire_size("
+                f"wireforge::TypeTag<{item.name}> /*tag*/) noexcept {{"
+            )
+            out.indent()
+            out.line("std::size_t size = 0U;")
+            for field, size in self.size_lines(item, which):
+                if size != "0U":
+                    self.conditional(field, [f"size += {size};"])
+            out.line("return size;")
+            out.dedent()
+            out.line("}")
+            out.line()
+
+
+def _user_prelude(project: Project, banner: Banner) -> str:
+    out = Writer()
+    name = project.name
+    names = Names(project)
+    out.line("/**")
+    out.line(f" * @file {name}/user_prelude.hpp")
+    out.line(f" * @brief Application headers and constants used by the {name} generated code.")
+    out.line(" *")
+    for text in banner.lines():
+        out.line(text)
+    out.line(" */")
+    out.line(f"#ifndef {guard(name, 'USER_PRELUDE_HPP')}")
+    out.line(f"#define {guard(name, 'USER_PRELUDE_HPP')}")
+    out.line()
+    out.line("#include <cstdint>")
+    if project.user_types:
+        out.line("#include <wireforge/validation.hpp>")
+    for header in project.headers:
+        include = f'"{header.path}"' if header.style == "quote" else f"<{header.path}>"
+        if header.condition is not None:
+            out.line(f"#if {names.condition(header.condition)}")
+        out.line(f"#include {include}")
+        if header.condition is not None:
+            out.line("#endif")
+    _user_type_support(out, project, names)
+    for constant in project.constants.values():
+        _constant_checks(out, constant)
+    out.line()
+    out.line(f"#endif // {guard(name, 'USER_PRELUDE_HPP')}")
+    return out.text()
+
+
+def _user_type_support(out: Writer, project: Project, names: Names) -> None:
+    """Each user type's own header include, plus its generated (fixed) size free functions."""
+    for user_type in project.user_types.values():
+        if user_type.include is not None:
+            quoted = user_type.style == "quote"
+            include = f'"{user_type.include}"' if quoted else f"<{user_type.include}>"
+            out.line(f"#include {include}")
+    if not project.user_types:
+        return
+    out.line()
+    out.line("namespace wireforge {")
+    for user_type in project.user_types.values():
+        cpp_name = names.scalar(user_type.name)
+        for which, text in (("max", "Largest"), ("min", "Smallest")):
+            out.line(f"/// @brief {text} encoded size of {cpp_name} in bytes (fixed).")
+            out.line(
+                f"constexpr std::size_t {which}_wire_size(TypeTag<{cpp_name}> /*tag*/) "
+                f"noexcept {{ return {user_type.size_bytes}U; }}"
+            )
+    out.line("} // namespace wireforge")
+
+
+def _constant_checks(out: Writer, constant: UserConstant) -> None:
+    """static_assert that the application constant matches the model (per profile)."""
+    branches = [
+        (f"defined(WIREFORGE_PROFILE_{profile})", value)
+        for profile, value in constant.profile_values.items()
+    ]
+    if not branches and constant.value is None:
+        return
+    out.line()
+    for index, (condition, value) in enumerate(branches):
+        out.line(f"#{'if' if index == 0 else 'elif'} {condition}")
+        out.line(_constant_assert(constant.cpp, value))
+    if constant.value is not None:
+        if branches:
+            out.line("#else")
+        out.line(_constant_assert(constant.cpp, constant.value))
+    if branches:
+        out.line("#endif")
+
+
+def _constant_assert(cpp: str, value: int) -> str:
+    return (
+        f"static_assert(static_cast<std::int64_t>({cpp}) == {value}, "
+        f'"{cpp} differs from the value in the WireForge model");'
+    )
+
+
+def render(project: Project, content_hash: str) -> dict[str, str]:
+    """Return the generated files of a valid project: relative path -> content."""
+    banner = Banner(project.name, project.version, content_hash)
+    notes = requirement_notes(project)
+    files = {
+        f"{project.name}/user_prelude.hpp": _user_prelude(project, banner),
+        f"{project.name}/model.hpp": _ModelHeader(project, banner, notes).render(),
+    }
+    for interface in project.interfaces.values():
+        relative = f"{project.name}/interfaces/{interface.name}.hpp"
+        files[relative] = InterfaceHeader(
+            project, interface, banner, notes.get(interface.name, [])
+        ).render()
+    return files
+
+
+def generate(
+    location: Path, output: Path, tests: test_project.TestOptions | None = None
+) -> list[Issue]:
+    """Validate the project at `location` and write its generated files below `output`.
+
+    With `tests`, the GoogleTest project `<output>/<project>/generated_tests/` is written as well.
+    """
+    try:
+        content_hash = bundle.build_bundle(location)["bundle"]["content_hash"]
+    except bundle.BundleError as error:
+        return error.issues or [Issue(str(location), None, "", str(error))]
+    result = load_project(location)
+    if result.project is None:
+        return result.issues
+    try:
+        files = render(result.project, content_hash)
+    except InterfaceError as error:
+        return [Issue(str(location), None, "/interfaces", str(error))]
+    for relative, text in files.items():
+        target = output / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if not target.exists() or target.read_text(encoding="utf-8") != text:
+            target.write_text(text, encoding="utf-8")
+    if tests is None:
+        return []
+    return test_project.write_test_project(result.project, location, output, tests)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Command line: python -m wireforge.generate PROJECT -o OUTPUT [--tests ...]."""
+    parser = argparse.ArgumentParser(prog="python -m wireforge.generate")
+    parser.add_argument("project", type=Path)
+    parser.add_argument("-o", "--output", type=Path, required=True)
+    parser.add_argument(
+        "--tests", action="store_true", help="also write the GoogleTest project generated_tests/"
+    )
+    parser.add_argument("--plugins", type=Path, help="Python file defining checksum PLUGINS")
+    parser.add_argument(
+        "--runtime",
+        type=Path,
+        default=test_project.RUNTIME_INCLUDE,
+        help="WireForge runtime include directory used by the test project",
+    )
+    parser.add_argument(
+        "--coverage-threshold",
+        type=int,
+        default=test_project.DEFAULT_COVERAGE,
+        help="minimum line coverage of the test project's coverage target (percent)",
+    )
+    args = parser.parse_args(argv)
+    options = (
+        test_project.TestOptions(args.plugins, args.runtime, args.coverage_threshold)
+        if args.tests
+        else None
+    )
+    issues = generate(args.project, args.output, options)
+    for issue in issues:
+        sys.stdout.write(f"{issue}\n")
+    return 1 if issues else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())