sdr-visualizer 1.1.0__py3-none-any.whl

sdr_visualizer/__init__.py

@@ -0,0 +1,3 @@
+"""sdr-visualizer: visual catalog generator for CJA / AA implementations."""
+
+__version__ = "1.1.0"

sdr_visualizer/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m sdr_visualizer`."""
+
+from sdr_visualizer.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sdr_visualizer/adapters/aa.py

@@ -0,0 +1,440 @@
+"""AA adapter: aa_auto_sdr JSON output -> normalized Implementation.
+
+eVars and props both map to dimensions (with platform_specific preserving
+allocation/expiration/prop-specific flags); events map to metrics;
+classifications attach as tags on the parent dimension.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sdr_visualizer.core.exceptions import InvalidSnapshotError
+from sdr_visualizer.core.models import (
+    CalculatedMetric,
+    Component,
+    Implementation,
+    Segment,
+)
+from sdr_visualizer.core.structure_limits import (
+    validate_decoded_structure,
+    validate_definition_structure,
+    validate_snapshot_structure,
+    validate_unicode_scalars,
+)
+
+
+def adapt(snapshot: dict[str, Any], *, source: str = "<unknown>") -> Implementation:
+    """Convert a parsed aa_auto_sdr JSON snapshot into an Implementation."""
+    if not isinstance(snapshot, dict):
+        raise InvalidSnapshotError(f"expected top-level JSON object, got {type(snapshot).__name__}")
+    validate_snapshot_structure(snapshot, label="AA snapshot")
+
+    if "report_suite" in snapshot:
+        rs = snapshot["report_suite"]
+    elif "reportSuite" in snapshot:
+        rs = snapshot["reportSuite"]
+    else:
+        raise InvalidSnapshotError("AA snapshot missing 'report_suite' object; not an AA snapshot?")
+    if not isinstance(rs, dict):
+        raise InvalidSnapshotError(
+            f"AA snapshot 'report_suite' must be an object; got {type(rs).__name__}"
+        )
+    instance_id = rs.get("rsid") or rs.get("RSID")
+    if not instance_id:
+        raise InvalidSnapshotError("AA snapshot 'report_suite' missing 'rsid'")
+    instance_name = rs.get("name") or instance_id
+    snapshot_taken_at = snapshot.get("captured_at") or snapshot.get("captured")
+    if isinstance(snapshot_taken_at, str):
+        snapshot_taken_at = snapshot_taken_at.strip() or None
+    else:
+        snapshot_taken_at = None
+    adapter_version = str(snapshot.get("tool_version") or "unknown")
+
+    dims_raw = _ensure_list(snapshot, "dimensions")
+    metrics_raw = _ensure_list(snapshot, "metrics")
+    classifications_by_parent = _index_classifications(snapshot.get("classifications"))
+
+    dimensions = [
+        _component_from_record(r, "dimension", classifications_by_parent) for r in dims_raw
+    ]
+    metrics = [_component_from_record(r, "metric", classifications_by_parent) for r in metrics_raw]
+    calculated_metrics = [
+        _calc_from_record(r) for r in _optional_list(snapshot, "calculated_metrics")
+    ]
+    segments = [_segment_from_record(r) for r in _optional_list(snapshot, "segments")]
+
+    return Implementation(
+        platform="aa",
+        instance_id=str(instance_id),
+        instance_name=str(instance_name),
+        snapshot_taken_at=snapshot_taken_at,
+        snapshot_source=source,
+        adapter_version=adapter_version,
+        metrics=metrics,
+        dimensions=dimensions,
+        segments=segments,
+        calculated_metrics=calculated_metrics,
+        derived_fields=[],  # CJA-only concept
+        raw=snapshot,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Components (dimensions and metrics)
+# ---------------------------------------------------------------------------
+
+
+def _component_from_record(
+    record: Any, component_type: str, classifications_by_parent: dict[str, list[str]]
+) -> Component:
+    if not isinstance(record, dict):
+        raise InvalidSnapshotError(
+            f"expected {component_type} record to be an object, got {type(record).__name__}"
+        )
+    component_id = record.get("id")
+    if not component_id:
+        raise InvalidSnapshotError(f"{component_type} record is missing 'id': {record!r}")
+
+    name = record.get("name") or component_id
+    description = _normalize_description(record.get("description"))
+    data_type = record.get("type")
+    polarity = _normalize_polarity(record.get("polarity"))
+    tags = _parse_tag_list(record.get("tags"))
+    # Pick up classifications attached to this component as tags.
+    extra_class_tags = classifications_by_parent.get(str(component_id), [])
+    if extra_class_tags:
+        tags = sorted(set([*tags, *extra_class_tags]))
+
+    handled = {"id", "name", "description", "type", "polarity", "tags"}
+    platform_specific = {k: v for k, v in record.items() if k not in handled}
+
+    return Component(
+        id=str(component_id),
+        name=str(name),
+        description=description,
+        component_type=component_type,  # type: ignore[arg-type]
+        data_type=str(data_type) if data_type else None,
+        polarity=polarity,
+        created_at=_optional_timestamp(record.get("created")),
+        modified_at=_optional_timestamp(record.get("modified")),
+        owner=str(record.get("owner_id")) if record.get("owner_id") else None,
+        tags=tags,
+        platform_specific=platform_specific,
+    )
+
+
+def _index_classifications(classifications: Any) -> dict[str, list[str]]:
+    """AA classifications attach to a parent dimension by ID; surface as tags."""
+    out: dict[str, list[str]] = {}
+    if not isinstance(classifications, list):
+        return out
+    for entry in classifications:
+        if not isinstance(entry, dict):
+            continue
+        parent = entry.get("parent")
+        if not parent:
+            continue
+        label = entry.get("name") or entry.get("id")
+        if not label:
+            continue
+        out.setdefault(str(parent), []).append(str(label))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Calculated metrics
+# ---------------------------------------------------------------------------
+
+
+def _stringify_formula(formula: dict[str, Any]) -> str:
+    func = formula.get("func")
+    if not func:
+        return ""
+    args = formula.get("args") or []
+    if not isinstance(args, list):
+        args = [args]
+    return f"{func}({', '.join(_stringify_formula_arg(a) for a in args)})"
+
+
+def _stringify_formula_arg(arg: Any) -> str:
+    if isinstance(arg, dict):
+        # Nested formula: render it the same way instead of leaking a
+        # Python dict repr into user-facing formula summaries.
+        rendered = _stringify_formula(arg)
+        return rendered or str(arg.get("func") or "?")
+    return str(arg)
+
+
+def _calc_from_record(record: Any) -> CalculatedMetric:
+    if not isinstance(record, dict):
+        raise InvalidSnapshotError(
+            f"expected calculated metric to be an object, got {type(record).__name__}"
+        )
+    metric_id = record.get("id")
+    if not metric_id:
+        raise InvalidSnapshotError(f"calc metric missing 'id': {record!r}")
+    name = record.get("name") or metric_id
+    description = _normalize_description(record.get("description"))
+    definition = record.get("definition") or {}
+    formula = definition.get("formula") if isinstance(definition, dict) else {}
+    if isinstance(formula, dict):
+        validate_definition_structure(formula, label=f"calculated metric formula {metric_id!r}")
+        formula_text = _stringify_formula(formula)
+    else:
+        formula_text = ""
+    references = _extract_aa_calc_refs(formula)
+
+    return CalculatedMetric(
+        id=str(metric_id),
+        name=str(name),
+        description=description,
+        formula=formula if isinstance(formula, dict) else {},
+        formula_text=formula_text,
+        attribution_model=record.get("attribution") or record.get("attribution_model"),
+        allocation=record.get("allocation"),
+        complexity_score=_as_float(record.get("complexity_score")),
+        references=references,
+        created_at=_optional_timestamp(record.get("created") or record.get("created_at")),
+        modified_at=_optional_timestamp(record.get("modified") or record.get("modified_at")),
+        owner=str(record.get("owner_id")) if record.get("owner_id") else None,
+    )
+
+
+def _extract_aa_calc_refs(formula: Any) -> list[str]:
+    """Walk an AA calc-metric formula and collect any metrics/* args."""
+    refs: list[str] = []
+    seen: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            args = node.get("args")
+            if isinstance(args, list):
+                for arg in args:
+                    if isinstance(arg, str) and arg.startswith(("metrics/", "variables/")):
+                        if arg not in seen:
+                            seen.add(arg)
+                            refs.append(arg)
+                    else:
+                        walk(arg)
+            for value in node.values():
+                if value is args:
+                    continue
+                walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(formula)
+    return refs
+
+
+# ---------------------------------------------------------------------------
+# Segments
+# ---------------------------------------------------------------------------
+
+
+def _segment_from_record(record: Any) -> Segment:
+    if not isinstance(record, dict):
+        raise InvalidSnapshotError(f"expected segment to be an object, got {type(record).__name__}")
+    segment_id = record.get("id")
+    if not segment_id:
+        raise InvalidSnapshotError(f"segment missing 'id': {record!r}")
+    name = record.get("name") or segment_id
+    description = _normalize_description(record.get("description"))
+    definition = record.get("definition") or {}
+    if isinstance(definition, dict):
+        validate_definition_structure(definition, label=f"segment definition {segment_id!r}")
+    nesting_depth, container_types = _walk_segment_definition(definition)
+    references: list[str] = []  # AA segments don't expose direct cross-refs in the basic shape
+
+    return Segment(
+        id=str(segment_id),
+        name=str(name),
+        description=description,
+        definition=definition if isinstance(definition, dict) else {},
+        nesting_depth=nesting_depth,
+        container_types=container_types,
+        references=references,
+        created_at=_optional_timestamp(record.get("created")),
+        modified_at=_optional_timestamp(record.get("modified")),
+        owner=str(record.get("owner_id")) if record.get("owner_id") else None,
+    )
+
+
+def _walk_segment_definition(definition: Any) -> tuple[int, list[str]]:
+    """Compute container nesting depth and distinct container contexts.
+
+    Depth counts only `func == "container"` nodes along the deepest
+    container chain — not raw JSON nesting. A definition with no
+    containers has depth 0.
+    """
+    contexts: list[str] = []
+    seen: set[str] = set()
+
+    def visit(node: Any, depth: int) -> int:
+        max_depth = depth
+        if isinstance(node, dict):
+            child_depth = depth
+            if node.get("func") == "container":
+                child_depth = depth + 1
+                max_depth = child_depth
+                if node.get("context"):
+                    ctx = str(node["context"])
+                    if ctx not in seen:
+                        seen.add(ctx)
+                        contexts.append(ctx)
+            for value in node.values():
+                max_depth = max(max_depth, visit(value, child_depth))
+        elif isinstance(node, list):
+            for item in node:
+                max_depth = max(max_depth, visit(item, depth))
+        return max_depth
+
+    return visit(definition, 0), contexts
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+# The newest aa_auto_sdr version this release was validated against
+# (bundled fixtures + the private real corpus; re-derive at each release:
+# grep -rho '"Tool Version": "[^"]*"|"tool_version": "[^"]*"' over corpus
+# and fixtures, take the max). The compatibility policy warns — never refuses.
+TESTED_THROUGH_GENERATOR_VERSION = "1.21.10"
+
+
+def generator_version_warning(adapter_version: str) -> str | None:
+    """Return warning text when the snapshot's generator is newer than the
+    newest version this release was tested against, else None. Unparseable
+    versions ("unknown", empty, suffixed builds) never warn. This helper has a
+    behavior-identical sibling copy in sdr-grader; the per-platform constant
+    value is the one deliberate difference."""
+    tested = _version_tuple(TESTED_THROUGH_GENERATOR_VERSION)
+    seen = _version_tuple(adapter_version)
+    if tested is None or seen is None or seen <= tested:
+        return None
+    return (
+        f"snapshot generator version {adapter_version} is newer than the "
+        f"newest version this release was tested against "
+        f"({TESTED_THROUGH_GENERATOR_VERSION}); newer snapshot fields may "
+        "not be represented"
+    )
+
+
+def _version_tuple(value: str) -> tuple[int, ...] | None:
+    parts = str(value).strip().split(".")
+    try:
+        return tuple(int(p) for p in parts)
+    except ValueError:
+        return None
+
+
+def _optional_timestamp(value: Any) -> str | None:
+    """Keep created_at/modified_at only if they're already a non-empty string.
+
+    aa_auto_sdr's created/modified fields are declared str|None in the
+    internal model, but a raw export can carry a non-string value (e.g. an
+    epoch int); a bare passthrough would leak that shape straight into the
+    payload. A non-string timestamp is treated as *missing* rather than
+    coerced to a numeric string: `_compact` then drops the key, and the
+    client renders the em-dash it already shows for a genuinely absent
+    timestamp — which beats both a stringified epoch and the 1970-date bug a
+    raw int would cause downstream. Same helper as cja.py's copy (adapters
+    stay standalone reference examples, so it's intentionally duplicated;
+    see cja.py's `_optional_str` for the parallel owner/data_type guard,
+    which AA doesn't need — its owner_id path is already cast)."""
+    return value if isinstance(value, str) and value else None
+
+
+def _parse_tag_list(value: Any) -> list[str]:
+    """aa_auto_sdr can ship `tags` as a JSON-encoded list string, same as
+    cja_auto_sdr (see cja.py's copy — adapters stay standalone reference
+    examples, so this helper is intentionally duplicated). Handles native
+    lists and stringified lists. Ordinary JSON syntax failures fall back to
+    `[]`; decoder resource failures are invalid snapshot input. Kept
+    behavior-identical to sdr-grader's copy."""
+    if value is None or value == "":
+        return []
+    if isinstance(value, list):
+        return [str(t) for t in value]
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return []
+        except (ValueError, RecursionError) as exc:
+            raise InvalidSnapshotError("tag list JSON exceeds decoder limits") from exc
+        validate_decoded_structure(parsed, label="tag list")
+        validate_unicode_scalars(parsed, label="tag list")
+        if isinstance(parsed, list):
+            return [str(t) for t in parsed]
+    return []
+
+
+def _optional_list(snapshot: dict[str, Any], key: str) -> list[Any]:
+    """Optional sections (segments, calculated_metrics) may be absent or null,
+    but a present non-list value is a malformed export, not an empty one.
+    Kept behavior-identical to the sibling copy in sdr-grader."""
+    value = snapshot.get(key)
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise InvalidSnapshotError(
+            f"AA snapshot '{key}' must be a list, got {type(value).__name__}"
+        )
+    return value
+
+
+def _as_float(value: Any) -> float:
+    """The visualizer's variant of sdr-grader's `_safe_float`.
+    Two intentional deltas from the grader, both driven by visualizer-only
+    behavior — do NOT reconcile them away to match the sibling:
+
+    1. A present but unconvertible value RAISES InvalidSnapshotError (the
+       grader returns a default). Trend mode relies on the raise to skip a
+       malformed snapshot; a single snapshot exits 3.
+    2. NaN/Infinity pass through unchanged (the grader coerces them to a
+       default). The renderer's allow_nan=False guard then rejects the
+       snapshot loudly (audit H2) — a report that cannot boot in a browser is
+       worse than a rejected one.
+
+    Falsy input keeps the old `value or 0.0` default."""
+    if not value:
+        return 0.0
+    try:
+        return float(value)
+    except (TypeError, ValueError) as exc:
+        raise InvalidSnapshotError(f"expected a number, got {value!r}") from exc
+
+
+def _ensure_list(snapshot: dict[str, Any], key: str) -> list[Any]:
+    value = snapshot.get(key) or []
+    if not isinstance(value, list):
+        raise InvalidSnapshotError(
+            f"AA snapshot '{key}' must be a list, got {type(value).__name__}"
+        )
+    return value
+
+
+def _normalize_description(value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    if not stripped or stripped == "-":
+        return None
+    return stripped
+
+
+def _normalize_polarity(value: Any):
+    if not isinstance(value, str):
+        return None
+    lowered = value.strip().lower()
+    if lowered in {"positive", "negative", "neutral"}:
+        return lowered  # type: ignore[return-value]
+    return None

sdr_visualizer/adapters/base.py

@@ -0,0 +1 @@
+"""Adapter protocol for the normalized implementation boundary."""