wireforge 0.1.0__py3-none-any.whl

wireforge/results.py

@@ -0,0 +1,377 @@
+"""Results of a test run of the generated test project, and the deviations that explain gaps.
+
+`load()` reads the `results/` directory the generated CMake project writes next to its build
+(`junit/<executable>/*.xml`, `ctest.xml`, `coverage.json`, `coverage_runtime.json`,
+`toolchain.json`) and the `.su` stack-usage files of the compiler. The reader is strict: a
+missing or damaged file is an error, never a silently empty report. The only optional file is the
+runtime coverage, which is measured only when the build asked for it.
+
+`load_deviations()` reads the optional `deviations.yaml` of a project: justifications for lines the
+tests do not reach. `match_coverage()` says which uncovered lines are justified.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+from xml.parsers import expat
+
+from wireforge import schema
+from wireforge.plain import to_plain
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+DEVIATIONS_FILE = "deviations.yaml"
+LAST_CHUNK = True  # expat's positional `isfinal`
+SU_FIELDS = 2  # bytes and qualifier follow the function
+SU_LINE = re.compile(r"^(?P<file>.*?):(?P<line>\d+):\d+:(?P<function>.*)$")
+
+
+class ResultsError(ValueError):
+    """A result file is missing, damaged or does not follow the expected layout."""
+
+
+@dataclass
+class Node:
+    """An XML element: the few things the result readers need."""
+
+    tag: str
+    attrs: dict[str, str]
+    children: list[Node]
+    text: str = ""
+
+    def all_text(self) -> str:
+        """Return the text of the element and of everything below it, in document order."""
+        return self.text + "".join(child.all_text() for child in self.children)
+
+    def find(self, tag: str) -> Node | None:
+        """Return the first direct child with this tag."""
+        return next((child for child in self.children if child.tag == tag), None)
+
+    def iter(self, tag: str) -> list[Node]:
+        """Return every descendant with this tag."""
+        found = [child for child in self.children if child.tag == tag]
+        for child in self.children:
+            found += child.iter(tag)
+        return found
+
+    def get(self, name: str, default: str = "") -> str:
+        """Return an attribute."""
+        return self.attrs.get(name, default)
+
+
+def parse_xml(text: str) -> Node:
+    """Parse XML text into nodes (external entities are not resolved)."""
+    root = Node("", {}, [])
+    stack = [root]
+
+    def start(tag: str, attrs: dict[str, str]) -> None:
+        node = Node(tag.rsplit(":", 1)[-1], dict(attrs), [])
+        stack[-1].children.append(node)
+        stack.append(node)
+
+    def characters(data: str) -> None:
+        stack[-1].text += data
+
+    parser = expat.ParserCreate()
+    parser.CharacterDataHandler = characters
+    parser.StartElementHandler = start
+    parser.EndElementHandler = lambda _tag: stack.pop()
+    parser.Parse(text, LAST_CHUNK)
+    return root.children[0]
+
+
+@dataclass(frozen=True)
+class TestResult:
+    """Outcome of one test."""
+
+    __test__ = False  # not a pytest class
+
+    id: str
+    executable: str
+    outcome: str
+    requirements: tuple[str, ...]
+    message: str
+
+
+@dataclass(frozen=True)
+class FileCoverage:
+    """Statement and branch coverage of one header; `uncovered` lists (line, function)."""
+
+    file: str
+    lines_total: int
+    lines_covered: int
+    uncovered: tuple[tuple[int, str], ...]
+    branches_total: int
+    branches_covered: int
+
+
+@dataclass(frozen=True)
+class StackEntry:
+    """Stack use of one function, the largest over all translation units."""
+
+    file: str
+    line: int
+    function: str
+    bytes: int
+    qualifier: str
+
+
+@dataclass(frozen=True)
+class Results:
+    """Everything a test run produced."""
+
+    tests: tuple[TestResult, ...]
+    selftests: tuple[TestResult, ...]
+    generated: tuple[FileCoverage, ...]
+    runtime: tuple[FileCoverage, ...] | None
+    stack: tuple[StackEntry, ...]
+    toolchain: dict[str, str]
+
+
+@dataclass(frozen=True)
+class Deviation:
+    """A reviewed justification for a coverage gap."""
+
+    kind: str
+    file: str
+    function: str
+    category: str
+    rationale: str
+    reviewer: str
+    lines: tuple[int, ...] = ()
+    tool: str = ""
+    rule: str = ""
+
+
+def _need(path: Path) -> Path:
+    if not path.exists():
+        message = f"{path}: missing, the test run did not write it"
+        raise ResultsError(message)
+    return path
+
+
+def _xml(path: Path) -> Node:
+    try:
+        return parse_xml(_need(path).read_text(encoding="utf-8"))
+    except (expat.ExpatError, OSError, IndexError) as error:
+        message = f"{path}: cannot read test results: {error}"
+        raise ResultsError(message) from error
+
+
+def _json(path: Path) -> dict[str, Any]:
+    try:
+        loaded = json.loads(_need(path).read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as error:
+        message = f"{path}: cannot read: {error}"
+        raise ResultsError(message) from error
+    if not isinstance(loaded, dict):
+        message = f"{path}: not a JSON object"
+        raise ResultsError(message)
+    return loaded
+
+
+def _case(element: Node, executable: str, name: str, classname: str) -> TestResult:
+    ident = f"{classname}.{name}" if classname else name
+    outcome, message = "passed", ""
+    failure = element.find("failure") or element.find("error")
+    if failure is not None:
+        outcome = "failed"
+        message = next(iter(failure.get("message").splitlines()), "")
+    elif element.find("skipped") is not None or element.get("status") in {"notrun", "disabled"}:
+        outcome = "skipped"
+    requirements: tuple[str, ...] = ()
+    for item in element.iter("property"):
+        if item.get("name") == "requirements":
+            requirements = tuple(part for part in item.get("value").split(",") if part)
+    return TestResult(ident, executable, outcome, requirements, message)
+
+
+def read_gtest(directory: Path) -> tuple[TestResult, ...]:
+    """Read the GoogleTest XML files below `directory`; the folder name is the executable."""
+    if not directory.is_dir() or not any(directory.rglob("*.xml")):
+        message = f"{directory}: no GoogleTest results (junit/<executable>/*.xml)"
+        raise ResultsError(message)
+    found: list[TestResult] = []
+    for path in sorted(directory.rglob("*.xml")):
+        executable = path.parent.name if path.parent != directory else ""
+        found += [
+            _case(element, executable, element.get("name"), element.get("classname"))
+            for element in _xml(path).iter("testcase")
+        ]
+    return tuple(found)
+
+
+def _selftests(path: Path) -> tuple[TestResult, ...]:
+    root = _xml(path)
+    return tuple(
+        _case(element, element.get("name"), element.get("name"), "")
+        for element in root.iter("testcase")
+        if "_selftest" in element.get("name")
+    )
+
+
+def read_coverage(path: Path) -> tuple[FileCoverage, ...]:
+    """Read a gcovr JSON report."""
+    files: list[FileCoverage] = []
+    entries = _json(path).get("files", [])
+    if not entries:
+        message = f"{path}: lists no files; the coverage filter matched nothing"
+        raise ResultsError(message)
+    for entry in entries:
+        lines = [line for line in entry.get("lines", []) if not line.get("gcovr/noncode")]
+        branches = [branch for line in lines for branch in line.get("branches", [])]
+        uncovered = tuple(
+            (int(line["line_number"]), str(line.get("function_name", "")))
+            for line in lines
+            if line.get("count", 0) == 0
+        )
+        files.append(
+            FileCoverage(
+                str(entry["file"]),
+                len(lines),
+                len(lines) - len(uncovered),
+                uncovered,
+                len(branches),
+                sum(1 for branch in branches if branch.get("count", 0) > 0),
+            )
+        )
+    return tuple(sorted(files, key=lambda item: item.file))
+
+
+def normalize_header(path: str) -> str | None:
+    """Return the project- or runtime-relative name of a header, None for other files."""
+    parts = Path(path).as_posix().split("/")
+    if "interfaces" in parts and parts[-1].endswith(".hpp"):
+        return "/".join(parts[parts.index("interfaces") - 1 :])
+    if parts[-1] == "model.hpp" and len(parts) > 1:
+        return "/".join(parts[-2:])
+    if "wireforge" in parts and parts[-1].endswith(".hpp"):
+        return "/".join(parts[len(parts) - 1 - parts[::-1].index("wireforge") :])
+    return None
+
+
+def _stack(build_dir: Path) -> tuple[StackEntry, ...]:
+    largest: dict[tuple[str, str], StackEntry] = {}
+    for path in sorted(build_dir.rglob("*.su")):
+        for text in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            head, _, rest = text.partition("\t")
+            match = SU_LINE.match(head)
+            sizes = rest.split("\t")
+            name = normalize_header(match["file"]) if match else None
+            if match is None or name is None or len(sizes) < SU_FIELDS:
+                continue
+            entry = StackEntry(name, int(match["line"]), match["function"], int(sizes[0]), sizes[1])
+            key = (name, entry.function)
+            if key not in largest or entry.bytes > largest[key].bytes:
+                largest[key] = entry
+    return tuple(sorted(largest.values(), key=lambda item: (item.file, item.line, item.function)))
+
+
+def load(build_dir: Path) -> Results:
+    """Read the results of a test run in `build_dir` (the build directory, not `results/`)."""
+    results = build_dir / "results"
+    if not results.is_dir():
+        message = f"{results}: no results directory; build the coverage target of the test project"
+        raise ResultsError(message)
+    runtime_file = results / "coverage_runtime.json"
+    toolchain = {str(key): str(value) for key, value in _json(results / "toolchain.json").items()}
+    return Results(
+        read_gtest(results / "junit"),
+        _selftests(results / "ctest.xml"),
+        read_coverage(results / "coverage.json"),
+        read_coverage(runtime_file) if runtime_file.exists() else None,
+        _stack(build_dir),
+        toolchain,
+    )
+
+
+# --- deviations ---------------------------------------------------------------------------------
+
+
+def load_deviations(project_dir: Path) -> list[Deviation]:
+    """Read the deviations of a project directory (none without `deviations.yaml`)."""
+    path = project_dir / DEVIATIONS_FILE
+    if not path.exists():
+        return []
+    document = schema.load_yaml(path)
+    issues = schema.validate_document(
+        document, "deviations.schema.json", file=str(path), source=document
+    )
+    if issues:
+        message = "\n".join(str(issue) for issue in issues)
+        raise ResultsError(message)
+    entries: list[dict[str, Any]] = cast("dict[str, Any]", to_plain(document))["deviations"]
+    return [
+        Deviation(
+            item["kind"],
+            item["file"],
+            item.get("function", "*"),
+            item["category"],
+            item["rationale"],
+            item["reviewer"],
+            tuple(item.get("lines", ())),
+            item.get("tool", ""),
+            item.get("rule", ""),
+        )
+        for item in entries
+    ]
+
+
+def glob(pattern: str, text: str) -> bool:
+    """Match `text` against a pattern where `*` stands for any characters."""
+    expression = ".*".join(re.escape(part) for part in pattern.split("*"))
+    return re.fullmatch(expression, text) is not None
+
+
+@dataclass(frozen=True)
+class Gap:
+    """Uncovered lines of one function of one file."""
+
+    file: str
+    function: str
+    lines: tuple[int, ...]
+
+
+def gaps(coverage: Iterable[FileCoverage]) -> list[Gap]:
+    """Group the uncovered lines by file and function."""
+    found: dict[tuple[str, str], list[int]] = {}
+    for item in coverage:
+        for line, function in item.uncovered:
+            found.setdefault((item.file, function), []).append(line)
+    return [Gap(file, function, tuple(lines)) for (file, function), lines in sorted(found.items())]
+
+
+def match_coverage(
+    coverage: Iterable[FileCoverage], deviations: list[Deviation]
+) -> tuple[list[Gap], list[Deviation]]:
+    """Split the gaps into unjustified ones and report the deviations nobody used.
+
+    A deviation covers a gap when file and function match; with `lines` it covers only those lines,
+    so a runtime update that moves the line makes the gap unjustified again.
+    """
+    used: set[int] = set()
+    unjustified: list[Gap] = []
+    for gap in gaps(coverage):
+        remaining = list(gap.lines)
+        for index, deviation in enumerate(deviations):
+            if deviation.kind != "coverage" or not (
+                glob(deviation.file, gap.file) and glob(deviation.function, gap.function)
+            ):
+                continue
+            covered = [line for line in remaining if not deviation.lines or line in deviation.lines]
+            if covered:
+                used.add(index)
+                remaining = [line for line in remaining if line not in covered]
+        if remaining:
+            unjustified.append(Gap(gap.file, gap.function, tuple(remaining)))
+    unused = [
+        item
+        for index, item in enumerate(deviations)
+        if item.kind == "coverage" and index not in used
+    ]
+    return unjustified, unused

wireforge/runtime_reqs.py

@@ -0,0 +1,147 @@
+"""Requirements of the runtime library (`runtime/requirements.yaml`) and their link to its tests.
+
+The runtime is written by hand and does not come from a model, so its requirements are written and
+reviewed by people. This module reads the file, checks it against the headers (rules RR-1 to RR-3),
+finds the requirement ids the runtime tests record and answers which runtime requirements realize
+which kind of generated low-level requirement.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, cast
+
+from wireforge import resources, schema
+from wireforge.issues import Issue
+from wireforge.plain import to_plain
+
+HEAD = re.compile(r"^(?:TEST|TEST_F|TYPED_TEST|TEST_P)\((\w+), (\w+)\) \{$", re.MULTILINE)
+PROPERTY = re.compile(r'^\s*::testing::Test::RecordProperty\("requirements", "([^"]*)"\);')
+VERSION = re.compile(r"kVersion(Major|Minor|Patch) = (\d+)U;")
+# Generated requirements without a runtime counterpart: they come from the model alone.
+GENERATED_ONLY = frozenset({"DEFAULT", "VALUES"})
+
+
+@dataclass(frozen=True)
+class RuntimeRequirement:
+    """One requirement of the runtime."""
+
+    id: str
+    text: str
+    header: str
+    code: tuple[str, ...]
+    verification: str
+    realizes: tuple[str, ...] = ()
+    retired: bool = False
+
+
+@dataclass(frozen=True)
+class RuntimeTest:
+    """A runtime unit test and the requirement ids it records."""
+
+    id: str
+    ids: tuple[str, ...]
+    file: str
+
+
+def load(path: Path | None = None) -> list[RuntimeRequirement]:
+    """Read and validate the requirements file (schema errors raise ValueError)."""
+    path = path or resources.runtime_requirements()
+    document = schema.load_yaml(path)
+    issues = schema.validate_document(
+        document, "runtime_requirements.schema.json", file=str(path), source=document
+    )
+    if issues:
+        raise ValueError("\n".join(str(issue) for issue in issues))
+    entries = cast("dict[str, Any]", to_plain(document))["requirements"]
+    return [
+        RuntimeRequirement(
+            ident,
+            item["text"],
+            item["header"],
+            tuple(item["code"]),
+            item["verification"],
+            tuple(item.get("realizes", ())),
+            bool(item.get("retired", False)),
+        )
+        for ident, item in entries.items()
+    ]
+
+
+def check(
+    requirements: list[RuntimeRequirement], include_dir: Path, *, file: str = "requirements.yaml"
+) -> list[Issue]:
+    """Check the requirements against the headers.
+
+    RR-1: the id names the header it belongs to. RR-2: the header exists. RR-3: every code symbol
+    appears in the header.
+    """
+    issues: list[Issue] = []
+    for item in requirements:
+        pointer = f"/requirements/{item.id}"
+        if item.id.split("-")[1] != Path(item.header).stem:
+            text = f"[RR-1] {item.id} belongs to {item.header}, the id names another header"
+            issues.append(Issue(file, None, pointer, text))
+        header = include_dir / "wireforge" / item.header
+        if not header.exists():
+            issues.append(Issue(file, None, pointer, f"[RR-2] {item.header} does not exist"))
+            continue
+        source = header.read_text(encoding="utf-8")
+        issues += [
+            Issue(file, None, pointer, f"[RR-3] {symbol} is not in {item.header}")
+            for symbol in item.code
+            if re.search(rf"\b{re.escape(symbol)}\b", source) is None
+        ]
+    return issues
+
+
+def symbol_line(item: RuntimeRequirement, include_dir: Path) -> str:
+    """Return `wireforge/<header>:<line>` of the first code symbol found in the header."""
+    header = include_dir / "wireforge" / item.header
+    lines = header.read_text(encoding="utf-8").splitlines()
+    for symbol in item.code:
+        pattern = re.compile(rf"\b{re.escape(symbol)}\b")
+        for number, text in enumerate(lines, start=1):
+            if pattern.search(text) and not text.lstrip().startswith(("///", "*", "/*")):
+                return f"wireforge/{item.header}:{number}"
+    return f"wireforge/{item.header}"
+
+
+@lru_cache(maxsize=1)
+def realized_by_kind() -> dict[str, tuple[str, ...]]:
+    """Map each generated requirement kind to the active runtime requirements that realize it."""
+    path = resources.runtime_requirements()
+    if not path.exists():
+        return {}
+    found: dict[str, list[str]] = {}
+    for item in load(path):
+        if not item.retired:
+            for kind in item.realizes:
+                found.setdefault(kind, []).append(item.id)
+    return {kind: tuple(ids) for kind, ids in found.items()}
+
+
+def tests(directory: Path) -> list[RuntimeTest]:
+    """Find the unit tests of a directory with the requirement ids each one records."""
+    found: list[RuntimeTest] = []
+    for path in sorted(directory.glob("*_test.cpp")):
+        lines = path.read_text(encoding="utf-8").splitlines()
+        for index, line in enumerate(lines):
+            head = HEAD.match(line)
+            if head is None:
+                continue
+            following = lines[index + 1] if index + 1 < len(lines) else ""
+            recorded = PROPERTY.match(following)
+            ids = tuple(part for part in recorded[1].split(",") if part) if recorded else ()
+            found.append(RuntimeTest(f"{head[1]}.{head[2]}", ids, path.name))
+    return found
+
+
+def version(include_dir: Path) -> str:
+    """Return the runtime version from `version.hpp`."""
+    text = (include_dir / "wireforge" / "version.hpp").read_text(encoding="utf-8")
+    parts = dict(VERSION.findall(text))
+    return f"{parts.get('Major', '?')}.{parts.get('Minor', '?')}.{parts.get('Patch', '?')}"

wireforge/schema.py

@@ -0,0 +1,151 @@
+"""JSON Schema validation of WireForge project files.
+
+This module only checks structure; references, ranges and layout are checked by
+`wireforge.validate`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError, best_match
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.error import YAMLError
+
+from wireforge import resources, versioning
+from wireforge.issues import Issue, errors_only
+
+SCHEMA_DIR = resources.schema_dir()
+SCHEMA_FILES = ("project.schema.json", "fragment.schema.json")
+ROOT_FILE_NAME = "project.yaml"
+
+
+def _registry() -> Registry:
+    resources = []
+    for name in SCHEMA_FILES:
+        contents = json.loads((SCHEMA_DIR / name).read_text(encoding="utf-8"))
+        resources.append(
+            (name, Resource.from_contents(contents, default_specification=DRAFT202012))
+        )
+    return Registry().with_resources(resources)
+
+
+def _validator(schema_file: str) -> Draft202012Validator:
+    contents = json.loads((SCHEMA_DIR / schema_file).read_text(encoding="utf-8"))
+    return Draft202012Validator(contents, registry=_registry())
+
+
+def _line_of(document: object, path: list[str | int]) -> int | None:
+    """Best-effort 1-based line of the node addressed by `path` in a round-trip loaded document."""
+    line: int | None = None
+    current: Any = document
+    for part in path:
+        try:
+            if isinstance(current, CommentedMap) and isinstance(part, str):
+                line = current.lc.key(part)[0]
+            elif isinstance(current, CommentedSeq) and isinstance(part, int):
+                line = current.lc.item(part)[0]
+            else:
+                break
+            current = current[part]
+        except (KeyError, IndexError, AttributeError):
+            break
+    return None if line is None else line + 1
+
+
+def _pointer(path: list[str | int]) -> str:
+    return "".join("/" + str(part).replace("~", "~0").replace("/", "~1") for part in path)
+
+
+def _pick(error: ValidationError) -> ValidationError | None:
+    """Most helpful sub-error of an anyOf/oneOf failure, ignoring wrong-branch type mismatches."""
+    if not error.context:
+        return None
+    relevant = [
+        sub for sub in error.context if not (sub.validator == "type" and not sub.relative_path)
+    ]
+    picked: ValidationError | None = best_match(relevant or error.context)
+    return picked
+
+
+def validate_document(
+    document: object, schema_file: str, *, file: str = "<memory>", source: object | None = None
+) -> list[Issue]:
+    """Validate an already loaded document; `source` (round-trip loaded) enables line numbers."""
+    validator = _validator(schema_file)
+    issues: list[Issue] = []
+    errors: list[ValidationError] = sorted(
+        validator.iter_errors(document), key=lambda error: [str(p) for p in error.absolute_path]
+    )
+    for error in errors:
+        chosen = _pick(error)
+        reported = chosen or error
+        path = list(error.absolute_path) + (list(reported.relative_path) if chosen else [])
+        line = _line_of(source if source is not None else document, path)
+        issues.append(Issue(file, line, _pointer(path), reported.message))
+    return issues
+
+
+def load_yaml(path: Path) -> object:
+    """Load a YAML 1.2 file preserving line information."""
+    return YAML(typ="rt").load(path.read_text(encoding="utf-8"))
+
+
+def validate_file(path: Path, schema_file: str) -> list[Issue]:
+    """Validate one YAML file against the named schema."""
+    try:
+        document = load_yaml(path)
+    except YAMLError as error:
+        return [Issue(str(path), None, "", f"YAML syntax error: {error}")]
+    if not isinstance(document, dict):
+        return [Issue(str(path), 1, "", "top level must be a mapping")]
+    version_issues = versioning.check_document(document, file=str(path), line=1)
+    if errors_only(version_issues):
+        return version_issues
+    return version_issues + validate_document(
+        document, schema_file, file=str(path), source=document
+    )
+
+
+def validate_project(location: Path) -> list[Issue]:
+    """Validate a project root file and every fragment it includes."""
+    root = location / ROOT_FILE_NAME if location.is_dir() else location
+    issues = validate_file(root, "project.schema.json")
+    document = None
+    try:
+        document = load_yaml(root)
+    except YAMLError:
+        return issues
+    patterns = document.get("include", []) if isinstance(document, dict) else []
+    for pattern in patterns if isinstance(patterns, list) else []:
+        for fragment in sorted(root.parent.glob(str(pattern))):
+            issues.extend(validate_file(fragment, "fragment.schema.json"))
+    return issues
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Validate project directories or root files and print one line per issue."""
+    parser = argparse.ArgumentParser(prog="python -m wireforge.schema")
+    parser.add_argument("projects", nargs="+", type=Path)
+    args = parser.parse_args(argv)
+    total = 0
+    for project in args.projects:
+        found = validate_project(project)
+        total += len(found)
+        for issue in found:
+            sys.stdout.write(f"{issue}\n")
+        if not found:
+            sys.stdout.write(f"{project}: OK\n")
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wireforge/server/__init__.py

@@ -0,0 +1 @@
+"""HTTP server of WireForge: workspace storage and REST API."""