ineedvalidation 0.0.1__py3-none-any.whl

ineedvalidation/__init__.py

@@ -0,0 +1,12 @@
+"""Evidence declarations for tests and a validation hierarchy built from them.
+
+The test half is a pytest plugin: :func:`case`, :func:`seam` and
+:func:`regression` mark what a test demonstrates, and the plugin collects those
+marks into an evidence ledger. The render half reads hierarchy node notes plus
+that ledger, lints them against each other, and renders the hierarchy.
+"""
+
+from ineedvalidation._version import __version__
+from ineedvalidation.marks import TIERS, case, regression, seam
+
+__all__ = ["TIERS", "__version__", "case", "regression", "seam"]

ineedvalidation/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

ineedvalidation/cli.py

@@ -0,0 +1,143 @@
+"""Command-line entry point: ``ineedvalidation lint | render | scaffold``."""
+
+import argparse
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+from ineedvalidation import __version__, d2, evidence, nodes, views
+from ineedvalidation.schema import HIERARCHY_TIERS
+
+STUB = """---
+id: {stub_id}
+tier: ''
+title: {case}
+couples_to: []
+cases:
+- {case}
+srqs: []
+referent: ''
+referent_status: none
+validation_level: 0
+---
+# {case}
+
+Stub written by ineedvalidation scaffold. Fill in the tier, the coupling, the
+system response quantities and the referent, then delete this line.
+"""
+
+
+def build_parser():
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="ineedvalidation",
+        description=(
+            "Lint and render a validation hierarchy from node notes and test evidence."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("lint", "render", "scaffold"):
+        command = sub.add_parser(name)
+        command.add_argument(
+            "hierarchy", help="directory holding nodes/, evidence/ and views/"
+        )
+        command.add_argument("--nodes", help="node notes directory")
+        command.add_argument("--evidence", help="evidence files directory")
+    lint = sub.choices["lint"]
+    lint.add_argument("--library-map", help="file listing the known library names")
+    render = sub.choices["render"]
+    render.add_argument("--view", help="render only this named view")
+    render.add_argument(
+        "--all-views", action="store_true", help="render every view file as well"
+    )
+    render.add_argument("--root", help="render only this node and everything below it")
+    render.add_argument("--views", help="view files directory")
+    render.add_argument("--out", help="output directory")
+    return parser
+
+
+def _load(args):
+    """Load the nodes, the evidence files and the merged summary."""
+    root = Path(args.hierarchy)
+    node_dir = Path(args.nodes) if args.nodes else root / "nodes"
+    evidence_dir = Path(args.evidence) if args.evidence else root / "evidence"
+    loaded = nodes.load(node_dir)
+    files = evidence.load_dir(evidence_dir)
+    return root, loaded, files, evidence.summarize(loaded, files)
+
+
+def _lint(args):
+    """Report every problem in the hierarchy."""
+    _, loaded, files, summary = _load(args)
+    library_text = Path(args.library_map).read_text() if args.library_map else None
+    # Without a ledger there is nothing to lint the notes against, so the
+    # two-way rules stay off and the declared fields carry the evidence.
+    problems = nodes.lint(
+        loaded,
+        summary=summary if files else None,
+        library_text=library_text,
+        unfiled=evidence.unfiled_cases(loaded, files) if files else None,
+    )
+    for problem in problems:
+        print("LINT:", problem)
+    census = ", ".join(
+        f"{tier}={sum(node.tier == tier for node in loaded.values())}"
+        for tier in HIERARCHY_TIERS
+    )
+    print(f"{len(loaded)} nodes, {census}")
+    return 1 if problems else 0
+
+
+def _render(args):
+    """Render one view, the two built-in views, or every view."""
+    root, loaded, _, summary = _load(args)
+    views_dir = Path(args.views) if args.views else root / "views"
+    outdir = Path(args.out) if args.out else root / "output"
+    names = [args.view] if args.view else list(views.builtin())
+    if args.all_views:
+        names = sorted(set(names) | set(views.load_dir(views_dir)))
+    for name in names:
+        try:
+            view = views.resolve(name, views_dir)
+        except KeyError as error:
+            print(error.args[0], file=sys.stderr)
+            return 2
+        if args.root:
+            view = replace(
+                view,
+                name=f"{name}_{args.root}",
+                root=args.root,
+                title=view.title or loaded[args.root].title,
+            )
+        selected = nodes.subtree(loaded, view.root) if view.root else loaded
+        d2.render(selected, summary, view, outdir, views_dir)
+        print("rendered", outdir / f"{view.name}.png")
+    return 0
+
+
+def _scaffold(args):
+    """Write a stub note for every case no node owns."""
+    root, loaded, files, _ = _load(args)
+    node_dir = Path(args.nodes) if args.nodes else root / "nodes"
+    written = 0
+    for case, libraries in evidence.unfiled_cases(loaded, files).items():
+        target = node_dir / f"unfiled-{case}.md"
+        if target.exists():
+            print("skipped, already present:", target)
+            continue
+        target.write_text(STUB.format(stub_id=f"unfiled-{case}", case=case))
+        print("wrote", target, "for", ", ".join(libraries))
+        written += 1
+    print(f"{written} stub(s) written")
+    return 0
+
+
+def main(argv=None):
+    """Run the command line."""
+    args = build_parser().parse_args(argv)
+    return {"lint": _lint, "render": _render, "scaffold": _scaffold}[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ineedvalidation/d2.py

@@ -0,0 +1,344 @@
+"""Emit the tiered hierarchy diagram as D2, and drive the rendering binaries.
+
+The layout is deterministic: one row per tier, uniform boxes, and an invisible
+anchor chain that pins each node to its tier rank from above and below, only
+where its real edges would let it drift.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import shutil
+import subprocess
+import textwrap
+from pathlib import Path
+
+from . import views
+from .schema import HIERARCHY_TIERS, NodeSummary, View
+
+NODE_W, NODE_H = 250, 110  # px; uniform for every node
+FONT_FAMILY = "Source Sans 3"
+
+TIER_LABEL = {
+    "complete": "Complete\nsystem",
+    "system": "System\ntier",
+    "subsystem": "Subsystem\ntier",
+    "benchmark": "Benchmark\ntier",
+    "unit": "Unit\nproblems",
+}
+D2_SHAPE = {
+    "complete": "oval",
+    "system": "oval",
+    "subsystem": "hexagon",
+    "benchmark": "rectangle",
+    "unit": "rectangle",
+}
+STATUS_EDGE = {
+    "none": "#9a9a9a",
+    "identified": "#F5D300",
+    "requested": "#FE53BB",
+    "in-hand": "#08F7FE",
+}
+LEVEL_FILL = {0: "#000000", 1: "#3a3a3a", 2: "#0b3d16", 3: "#0f6b25", 4: "#22a544"}
+EVIDENCE_TEXT = {
+    "A": "A  code verification",
+    "C": "C  solution verification",
+    "B": "B  cross-code benchmark",
+    "D": "D  validation against measurement",
+    "E": "E  uncertainty quantification",
+}
+LEVEL_TEXT = {
+    0: "0  insufficient evidence",
+    1: "1  conceptually validated",
+    2: "2  representative system, in domain",
+    3: "3  real system, representative environment",
+    4: "4  real system, operating environment",
+}
+
+
+def _wrap(text: str, chars: int) -> str:
+    """Wrap a label to a width, joined by the D2 line break."""
+    return "\\n".join(textwrap.wrap(text, chars))
+
+
+def _evidence_text(summary: NodeSummary) -> str:
+    """The evidence line for a label: demonstrated plain, claimed in parentheses."""
+    parts = list(summary.demonstrated)
+    if summary.computed:
+        parts += [f"({tier})" for tier in summary.claimed]
+    return " ".join(parts) or "none"
+
+
+def emit(nodes: dict, summary: dict, view: View) -> str:
+    """Render the hierarchy as D2 source for one view."""
+    dark = view.mode == "status"
+    fg, bg = ("#ffffff", "#000000") if dark else ("#000000", "#ffffff")
+    lines = [
+        "direction: down",
+        f"vars: {{ d2-config: {{ layout-engine: {view.layout} }} }}",
+        f'style.fill: "{bg}"',
+    ]
+    tiers = [t for t in HIERARCHY_TIERS if any(n.tier == t for n in nodes.values())]
+    # Rank pinning. Anchor chain A0 -> ... -> A(k): A(i) carries the label of tier i
+    # and shares its rank with row i; A(k) is a hidden floor. A node is pinned from
+    # above (A(i-1) -> node) when no real parent sits in the tier directly above it,
+    # and from below (node -> A(i+1)) when no real child sits in the tier directly
+    # below it. Together with the real edges this fixes every node to its tier rank
+    # under both layout engines with the fewest invisible edges.
+    depth = len(tiers)
+    for i in range(depth + 1):
+        lines.append(
+            f'A{i}: {{ label: ""; shape: rectangle; width: 1; height: 1; '
+            "style.opacity: 0 }"
+        )
+        if i:
+            lines.append(f"A{i - 1} -> A{i}: {{ style.opacity: 0 }}")
+    children = {nid: [c for c in nodes if nid in nodes[c].couples_to] for nid in nodes}
+    highlight = set(view.highlight)
+    for nid, node in nodes.items():
+        dim = bool(highlight) and not highlight & set(summary[nid].libraries)
+        i = tiers.index(node.tier)
+        parents = [p for p in node.couples_to if p in nodes]
+        has_parent_above = any(tiers.index(nodes[p].tier) == i - 1 for p in parents)
+        has_child_below = any(
+            tiers.index(nodes[c].tier) == i + 1 for c in children[nid]
+        )
+        wrap = 26 if node.tier in ("benchmark", "unit") else 22
+        label = _wrap(node.title, wrap)
+        if dark and "libraries" in view.show:
+            label += "\\n" + _wrap(", ".join(summary[nid].libraries), 34)
+        if dark and "tiers" in view.show:
+            label += "\\nevidence " + _evidence_text(summary[nid])
+        fill = LEVEL_FILL[node.validation_level] if dark else bg
+        stroke = STATUS_EDGE[node.referent_status] if dark else fg
+        width = 3 if dark and node.referent_status != "none" else 2
+        box = (
+            NODE_W + 40 if node.tier in ("complete", "system", "subsystem") else NODE_W
+        )
+        lines.append(
+            f'{nid}: {{ label: "{label}"; shape: {D2_SHAPE[node.tier]}; '
+            f"width: {box}; height: {NODE_H}; "
+            f'style.fill: "{fill}"; style.stroke: "{stroke}"; '
+            f"style.stroke-width: {width}; "
+            f'style.font-color: "{fg}"; style.font-size: 15; style.bold: true'
+            + ("; style.border-radius: 8" if node.tier == "benchmark" else "")
+            + ("; style.opacity: 0.25" if dim else "")
+            + " }"
+        )
+        if i > 0 and not has_parent_above:
+            lines.append(f"A{i - 1} -> {nid}: {{ style.opacity: 0 }}")
+        if not has_child_below:
+            lines.append(f"{nid} -> A{i + 1}: {{ style.opacity: 0 }}")
+    for nid, node in nodes.items():
+        for parent in node.couples_to:
+            if parent not in nodes:
+                continue
+            dim = bool(highlight) and not (
+                highlight & set(summary[nid].libraries)
+                and highlight & set(summary[parent].libraries)
+            )
+            lines.append(
+                f'{parent} -> {nid}: {{ style.stroke: "{fg}"; style.stroke-width: 1'
+                + ("; style.opacity: 0.2" if dim else "")
+                + " }"
+            )
+    if dark:
+        present = sorted({n.validation_level for n in nodes.values()})
+        subtitle = (
+            "validation levels present: "
+            + ", ".join(str(v) for v in present)
+            + " (NASA-STD-7009B Table 9; level 2 is the ceiling before launch)"
+        )
+        head = (view.title + "\\n" if view.title else "") + subtitle
+        lines.insert(
+            3,
+            f'title: {{ label: "{head}"; shape: text; near: top-center; '
+            f"style.font-size: {30 if view.title else 18}; "
+            f"style.bold: {'true' if view.title else 'false'}; "
+            f'style.font-color: "{fg}" }}',
+        )
+    elif view.title:
+        lines.insert(
+            3,
+            f'title: {{ label: "{view.title}"; shape: text; near: top-center; '
+            f'style.font-size: 30; style.bold: true; style.font-color: "{fg}" }}',
+        )
+    if dark:
+        lines.append("legend: {")
+        lines.append('  label: ""')
+        lines.append("  near: bottom-center")
+        lines.append("  grid-rows: 3")
+        lines.append("  grid-gap: 6")
+        lines.append(f'  style.fill: "{bg}"')
+        lines.append(f'  style.stroke: "{bg}"')
+        cell = (
+            f"shape: rectangle; width: 300; height: 38; style.font-size: 13; "
+            f'style.font-color: "{fg}"'
+        )
+        # D2 fills a grid-rows grid column by column: three cells per column,
+        # read top to bottom
+        entries = []
+        for level, color in LEVEL_FILL.items():
+            entries.append(
+                f'l{level}: {{ label: "level {LEVEL_TEXT[level]}"; {cell}; '
+                f'style.fill: "{color}"; style.stroke: "{fg}"; style.stroke-width: 1 }}'
+            )
+        entries.append(f'gap1: {{ label: ""; {cell}; style.opacity: 0 }}')
+        for status, color in STATUS_EDGE.items():
+            entries.append(
+                f'r{status}: {{ label: "referent {status}"; {cell}; '
+                f'style.fill: "{bg}"; style.stroke: "{color}"; style.stroke-width: 3 }}'
+            )
+        entries.append(f'gap2: {{ label: ""; {cell}; style.opacity: 0 }}')
+        entries.append(f'gap3: {{ label: ""; {cell}; style.opacity: 0 }}')
+        for tier, text in EVIDENCE_TEXT.items():
+            entries.append(
+                f'e{tier}: {{ label: "evidence {text}"; {cell}; '
+                f'style.fill: "{bg}"; style.stroke: "#555555"; '
+                "style.stroke-width: 1; style.stroke-dash: 3 }"
+            )
+        for entry in entries:
+            lines.append("  " + entry)
+        lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def inject_tier_labels(svg: str, tiers: list[str], fg: str, margin: int = 230) -> str:
+    """Write each tier label at the left margin of its row, and widen the drawing.
+
+    Rows come from the hidden anchors ``A<i>``. The font faces are pointed at the
+    installed family because rsvg-convert cannot read the data-URI faces D2 embeds.
+    """
+    xs = [float(v) for v in re.findall(r'<rect x="([\d.]+)"', svg)]
+    xs += [float(v) for v in re.findall(r'<path d="M ([\d.]+) ', svg)]
+    xs += [
+        float(v) - float(r)
+        for v, r in re.findall(r'<ellipse cx="([\d.]+)" cy="[\d.]+" rx="([\d.]+)"', svg)
+    ]
+    left = min(xs) if xs else 0.0
+    labels = []
+    for i, tier in enumerate(tiers):
+        cls = base64.b64encode(f"A{i}".encode()).decode()
+        found = re.search(
+            r'<g class="'
+            + re.escape(cls)
+            + r'"[^>]*>.*?<rect x="([\d.]+)" y="([\d.]+)" '
+            r'width="[\d.]+" height="([\d.]+)"',
+            svg,
+            re.S,
+        )
+        if not found:
+            continue
+        y = float(found.group(2)) + float(found.group(3)) / 2
+        rows = TIER_LABEL[tier].split("\n")
+        x = left - 40
+        tspans = "".join(
+            f'<tspan x="{x:.1f}" dy="{0 if j == 0 else 26}">{row}</tspan>'
+            for j, row in enumerate(rows)
+        )
+        labels.append(
+            f'<text x="{x:.1f}" y="{y - 13 * (len(rows) - 1) + 8:.1f}" '
+            f'fill="{fg}" class="text-bold" '
+            f'style="text-anchor:end;font-size:22px">{tspans}</text>'
+        )
+    # geometry: outer <svg viewBox="0 0 W H"> wraps inner
+    # <svg width="W" height="H" viewBox="x y w h">
+    svg = re.sub(
+        r'<svg class="([^"]+)" width="([\d.]+)" height="([\d.]+)" '
+        r'viewBox="([-\d.]+) ([-\d.]+) ([\d.]+) ([\d.]+)">',
+        lambda m: (
+            f'<svg class="{m.group(1)}" width="{int(float(m.group(2))) + margin}" '
+            f'height="{m.group(3)}" '
+            f'viewBox="{float(m.group(4)) - margin:.0f} {m.group(5)} '
+            f'{float(m.group(6)) + margin:.0f} {m.group(7)}">'
+        ),
+        svg,
+        count=1,
+    )
+    svg = re.sub(
+        r'(preserveAspectRatio="xMinYMin meet" viewBox=")'
+        r'([-\d.]+) ([-\d.]+) ([\d.]+) ([\d.]+)"',
+        lambda m: (
+            f"{m.group(1)}{m.group(2)} {m.group(3)} "
+            f'{float(m.group(4)) + margin:.0f} {m.group(5)}"'
+        ),
+        svg,
+        count=1,
+    )
+    # background rect of the inner svg: widen too
+    svg = re.sub(
+        r'<rect x="([-\d.]+)" y="([-\d.]+)" width="([\d.]+)" height="([\d.]+)" '
+        r'rx="0.000000" fill="(#[0-9a-fA-F]+)" stroke-width="0" />',
+        lambda m: (
+            f'<rect x="{float(m.group(1)) - margin:.0f}" y="{m.group(2)}" '
+            f'width="{float(m.group(3)) + margin:.0f}" height="{m.group(4)}" '
+            f'rx="0" fill="{m.group(5)}" stroke-width="0" />'
+        ),
+        svg,
+        count=1,
+    )
+    # fonts: rsvg cannot read D2's data-URI faces; use an installed family
+    svg = re.sub(
+        r'font-family: "?d2-\d+-font-bold"?;',
+        f'font-family: "{FONT_FAMILY}"; font-weight: 700;',
+        svg,
+    )
+    svg = re.sub(
+        r'font-family: "?d2-\d+-font-italic"?;',
+        f'font-family: "{FONT_FAMILY}"; font-style: italic;',
+        svg,
+    )
+    svg = re.sub(
+        r'font-family: "?d2-\d+-font-regular"?;', f'font-family: "{FONT_FAMILY}";', svg
+    )
+    svg = re.sub(r"@font-face \{[^}]*\}", "", svg)
+    return svg.replace("</svg>", "".join(labels) + "</svg>", 1)
+
+
+def require_binary(name: str) -> None:
+    """Raise when an external rendering binary is missing."""
+    if shutil.which(name) is None:
+        raise RuntimeError(
+            f"{name} is not on PATH; it is required to render the hierarchy"
+        )
+
+
+def _run(command: list[str]) -> None:
+    """Run an external command and raise with its stderr when it fails."""
+    result = subprocess.run(command, capture_output=True, text=True, check=False)
+    if result.returncode:
+        raise RuntimeError(f"{command[0]} failed: {result.stderr.strip()}")
+
+
+def render(nodes, summary, view, outdir, views_dir=None):
+    """Write the generated D2, compile it or its override, and rasterize."""
+    require_binary("d2")
+    require_binary("rsvg-convert")
+    outdir = Path(outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    generated = outdir / f"{view.name}.gen.d2"
+    generated.write_text(emit(nodes, summary, view))
+    source = views.override_path(views_dir, view.name) or generated
+    svg = outdir / f"{view.name}.svg"
+    theme = "200" if view.mode == "status" else "0"
+    _run(
+        [
+            "d2",
+            "--layout",
+            view.layout,
+            "--theme",
+            theme,
+            "--pad",
+            "30",
+            str(source),
+            str(svg),
+        ]
+    )
+    fg = "#ffffff" if view.mode == "status" else "#000000"
+    tiers = [t for t in HIERARCHY_TIERS if any(n.tier == t for n in nodes.values())]
+    svg.write_text(inject_tier_labels(svg.read_text(), tiers, fg))
+    png = outdir / f"{view.name}.png"
+    background = "black" if view.mode == "status" else "white"
+    _run(["rsvg-convert", "-z", "2", "-b", background, "-o", str(png), str(svg)])
+    return png

ineedvalidation/evidence.py

@@ -0,0 +1,97 @@
+"""Fold per-repository evidence files into one summary per hierarchy node."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .schema import EVIDENCE_ORDER, EvidenceFile, Node, NodeSummary
+
+
+def load_dir(directory: Path) -> list[EvidenceFile]:
+    """Read every ``*.json`` evidence file in a directory."""
+    directory = Path(directory)
+    if not directory.is_dir():
+        return []
+    return [
+        EvidenceFile.from_dict(json.loads(path.read_text()))
+        for path in sorted(directory.glob("*.json"))
+    ]
+
+
+def _order(tiers) -> tuple[str, ...]:
+    """Sort evidence tiers into the reading order A, C, B, D, E."""
+    return tuple(tier for tier in EVIDENCE_ORDER if tier in tiers)
+
+
+def summarize(
+    nodes: dict[str, Node], files: list[EvidenceFile]
+) -> dict[str, NodeSummary]:
+    """One summary per node, computed where tests exist, declared where they do not."""
+    owner = {case: nid for nid, node in nodes.items() for case in node.cases}
+    collected: dict[str, list[tuple[str, object]]] = {nid: [] for nid in nodes}
+    for evidence_file in files:
+        for record in evidence_file.tests:
+            nid = owner.get(record.case)
+            if nid is not None:
+                collected[nid].append((evidence_file.library, record))
+    summaries = {}
+    for nid, node in nodes.items():
+        rows = collected[nid]
+        if not rows:
+            summaries[nid] = NodeSummary(
+                node_id=nid,
+                libraries=node.libraries_planned,
+                demonstrated=_order(node.evidence_declared),
+                computed=False,
+            )
+            continue
+        demonstrated: set[str] = set()
+        claimed: set[str] = set()
+        libraries: list[str] = []
+        srqs: list[str] = []
+        refs: list[str] = []
+        seams: list[tuple[str, str]] = []
+        skipped = 0
+        for library, record in rows:
+            if library not in libraries:
+                libraries.append(library)
+            if record.tier:
+                target = demonstrated if record.outcome == "passed" else claimed
+                target.add(record.tier)
+            if record.srq and record.srq not in srqs:
+                srqs.append(record.srq)
+            if record.ref and record.ref not in refs:
+                refs.append(record.ref)
+            if record.seam and record.seam not in seams:
+                seams.append(record.seam)
+            if record.outcome in ("skipped", "xfailed"):
+                skipped += 1
+        summaries[nid] = NodeSummary(
+            node_id=nid,
+            libraries=tuple(libraries),
+            demonstrated=_order(demonstrated),
+            claimed=_order(claimed - demonstrated),
+            srqs_covered=tuple(srqs),
+            refs=tuple(refs),
+            seams=tuple(seams),
+            tests=len(rows),
+            skipped=skipped,
+            computed=True,
+        )
+    return summaries
+
+
+def unfiled_cases(
+    nodes: dict[str, Node], files: list[EvidenceFile]
+) -> dict[str, tuple[str, ...]]:
+    """Cases named by a test that no node owns, mapped to the libraries naming them."""
+    known = {case for node in nodes.values() for case in node.cases}
+    found: dict[str, list[str]] = {}
+    for evidence_file in files:
+        for record in evidence_file.tests:
+            if record.case and record.case not in known:
+                libraries = found.setdefault(record.case, [])
+                if evidence_file.library not in libraries:
+                    libraries.append(evidence_file.library)
+    return {case: tuple(libraries) for case, libraries in sorted(found.items())}