modelwright 0.1.0a1__py3-none-any.whl

modelwright/graph.py

@@ -0,0 +1,591 @@
+"""Dependency graph records built from extracted workbook facts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from openpyxl.utils.cell import get_column_letter, range_boundaries
+
+from modelwright.extraction import CellRecord, TableRecord, WorkbookRecord
+from modelwright.references import WorkbookReference, normalize_reference
+
+
+JsonValue = str | int | float | bool | None | list[Any] | dict[str, Any]
+EdgeKind = Literal["semantic", "execution"]
+
+
+@dataclass(frozen=True)
+class DependencyEdge:
+    """One dependency edge from an upstream source to a formula cell target."""
+
+    source: WorkbookReference
+    target: WorkbookReference
+    edge_kind: EdgeKind
+    raw_reference: str
+    resolved_from: WorkbookReference | None = None
+    diagnostic_code: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DependencyEdge":
+        resolved_from_data = data.get("resolved_from")
+        return cls(
+            source=WorkbookReference.from_dict(data["source"]),
+            target=WorkbookReference.from_dict(data["target"]),
+            edge_kind=data["edge_kind"],
+            raw_reference=data["raw_reference"],
+            resolved_from=WorkbookReference.from_dict(resolved_from_data) if resolved_from_data is not None else None,
+            diagnostic_code=data.get("diagnostic_code"),
+        )
+
+    def to_dict(self) -> dict[str, JsonValue]:
+        return {
+            "source": self.source.to_dict(),
+            "target": self.target.to_dict(),
+            "edge_kind": self.edge_kind,
+            "raw_reference": self.raw_reference,
+            "resolved_from": self.resolved_from.to_dict() if self.resolved_from is not None else None,
+            "diagnostic_code": self.diagnostic_code,
+        }
+
+
+@dataclass(frozen=True)
+class DependencyGraph:
+    """Dependency edges for one workbook extraction."""
+
+    workbook_id: str
+    edges: tuple[DependencyEdge, ...] = field(default_factory=tuple)
+    diagnostics: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def semantic_edges(self) -> tuple[DependencyEdge, ...]:
+        return tuple(edge for edge in self.edges if edge.edge_kind == "semantic")
+
+    @property
+    def execution_edges(self) -> tuple[DependencyEdge, ...]:
+        return tuple(edge for edge in self.edges if edge.edge_kind == "execution")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DependencyGraph":
+        return cls(
+            workbook_id=data["workbook_id"],
+            edges=tuple(DependencyEdge.from_dict(edge) for edge in data.get("edges", [])),
+            diagnostics=tuple(data.get("diagnostics", [])),
+        )
+
+    def to_dict(self) -> dict[str, JsonValue]:
+        return {
+            "workbook_id": self.workbook_id,
+            "edges": [edge.to_dict() for edge in self.edges],
+            "diagnostics": list(self.diagnostics),
+        }
+
+
+def build_dependency_graph(workbook: WorkbookRecord) -> DependencyGraph:
+    """Build semantic and execution dependency edges from extracted formulas."""
+
+    named_ranges = _named_range_destinations(workbook)
+    tables = {table.name: table for table in workbook.tables}
+    edges: list[DependencyEdge] = []
+    diagnostics: list[str] = []
+
+    for cell in workbook.cells:
+        if cell.formula is None:
+            continue
+
+        target = _target_reference(cell)
+        current_sheet = target.sheet
+        for raw_reference in cell.formula.raw_references:
+            source = normalize_reference(raw_reference, current_sheet=current_sheet)
+            execution_edges = _execution_edges_for(
+                source,
+                target,
+                raw_reference,
+                named_ranges,
+                tables,
+                raw_formula=cell.formula.raw_formula,
+            )
+            diagnostic_code = source.diagnostic_code
+            if source.kind == "structured" and all(edge.diagnostic_code is None for edge in execution_edges):
+                diagnostic_code = None
+            edges.append(
+                DependencyEdge(
+                    source=source,
+                    target=target,
+                    edge_kind="semantic",
+                    raw_reference=raw_reference,
+                    diagnostic_code=diagnostic_code,
+                )
+            )
+            edges.extend(execution_edges)
+
+    diagnostics.extend(_diagnostic_codes(edges))
+    diagnostics.extend(_circular_dependency_codes(edges))
+    return DependencyGraph(workbook_id=workbook.workbook_id, edges=tuple(edges), diagnostics=tuple(dict.fromkeys(diagnostics)))
+
+
+def _named_range_destinations(workbook: WorkbookRecord) -> dict[str, tuple[WorkbookReference, ...]]:
+    return {
+        named_range.name: tuple(
+            reference
+            for destination in named_range.destinations
+            if (reference := normalize_reference(destination)).kind in {"cell", "range"}
+        )
+        for named_range in workbook.named_ranges
+    }
+
+
+def _target_reference(cell: CellRecord) -> WorkbookReference:
+    target = normalize_reference(cell.cell_ref)
+    if target.kind != "cell":
+        raise ValueError(f"formula cell target is not a cell reference: {cell.cell_ref}")
+    return target
+
+
+def _execution_edges_for(
+    source: WorkbookReference,
+    target: WorkbookReference,
+    raw_reference: str,
+    named_ranges: dict[str, tuple[WorkbookReference, ...]],
+    tables: dict[str, TableRecord],
+    *,
+    raw_formula: str,
+) -> tuple[DependencyEdge, ...]:
+    if static_offset_reference := _static_offset_reference(
+        raw_formula=raw_formula,
+        raw_reference=raw_reference,
+        source=source,
+        target=target,
+        tables=tables,
+    ):
+        return (
+            DependencyEdge(
+                source=static_offset_reference.shifted,
+                target=target,
+                edge_kind="execution",
+                raw_reference=raw_reference,
+                resolved_from=static_offset_reference.base,
+            ),
+        )
+
+    if source.kind == "cell":
+        return (
+            DependencyEdge(
+                source=source,
+                target=target,
+                edge_kind="execution",
+                raw_reference=raw_reference,
+            ),
+        )
+
+    if source.kind == "range":
+        return tuple(
+            DependencyEdge(
+                source=range_cell,
+                target=target,
+                edge_kind="execution",
+                raw_reference=raw_reference,
+                resolved_from=source,
+            )
+            for range_cell in _expand_range_reference(source)
+        )
+
+    if source.kind == "named_range" and source.name in named_ranges:
+        edges: list[DependencyEdge] = []
+        for destination in named_ranges[source.name]:
+            if destination.kind == "range":
+                edges.extend(
+                    DependencyEdge(
+                        source=range_cell,
+                        target=target,
+                        edge_kind="execution",
+                        raw_reference=raw_reference,
+                        resolved_from=destination,
+                    )
+                    for range_cell in _expand_range_reference(destination)
+                )
+                continue
+            edges.append(
+                DependencyEdge(
+                    source=destination,
+                    target=target,
+                    edge_kind="execution",
+                    raw_reference=raw_reference,
+                    resolved_from=source,
+                )
+            )
+        return tuple(edges)
+
+    if source.kind == "structured":
+        resolved = _resolve_structured_reference(source, target, tables)
+        if resolved is not None:
+            return (
+                DependencyEdge(
+                    source=resolved,
+                    target=target,
+                    edge_kind="execution",
+                    raw_reference=raw_reference,
+                    resolved_from=source,
+                ),
+            )
+
+    return (
+        DependencyEdge(
+            source=source,
+            target=target,
+            edge_kind="execution",
+            raw_reference=raw_reference,
+            diagnostic_code=source.diagnostic_code or f"unsupported_{source.kind}_dependency",
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class _StaticOffsetReference:
+    base: WorkbookReference
+    shifted: WorkbookReference
+
+
+def _static_offset_reference(
+    *,
+    raw_formula: str,
+    raw_reference: str,
+    source: WorkbookReference,
+    target: WorkbookReference,
+    tables: dict[str, TableRecord],
+) -> _StaticOffsetReference | None:
+    for arguments in _offset_argument_lists(raw_formula):
+        if len(arguments) != 3:
+            continue
+        base_argument, row_argument, column_argument = arguments
+        if base_argument != raw_reference:
+            continue
+        row_offset = _static_integer_argument(row_argument)
+        column_offset = _static_integer_argument(column_argument)
+        if row_offset is None or column_offset is None:
+            continue
+        base = _static_offset_base(source, target, tables)
+        if base is None:
+            continue
+        shifted = _shift_cell_reference(base, row_offset=row_offset, column_offset=column_offset)
+        if shifted is not None:
+            return _StaticOffsetReference(base=base, shifted=shifted)
+    return None
+
+
+def _offset_argument_lists(raw_formula: str) -> tuple[tuple[str, ...], ...]:
+    formula = raw_formula.removeprefix("=")
+    argument_lists: list[tuple[str, ...]] = []
+    search_from = 0
+    while True:
+        offset_index = formula.upper().find("OFFSET(", search_from)
+        if offset_index == -1:
+            return tuple(argument_lists)
+        args_start = offset_index + len("OFFSET(")
+        args_end = _matching_parenthesis(formula, args_start - 1)
+        if args_end is None:
+            search_from = args_start
+            continue
+        argument_lists.append(_split_formula_arguments(formula[args_start:args_end]))
+        search_from = args_end + 1
+
+
+def _matching_parenthesis(formula: str, open_index: int) -> int | None:
+    depth = 0
+    bracket_depth = 0
+    in_string = False
+    index = open_index
+    while index < len(formula):
+        character = formula[index]
+        if character == '"':
+            in_string = not in_string
+        elif not in_string:
+            if character == "[":
+                bracket_depth += 1
+            elif character == "]" and bracket_depth:
+                bracket_depth -= 1
+            elif bracket_depth == 0 and character == "(":
+                depth += 1
+            elif bracket_depth == 0 and character == ")":
+                depth -= 1
+                if depth == 0:
+                    return index
+        index += 1
+    return None
+
+
+def _split_formula_arguments(arguments: str) -> tuple[str, ...]:
+    parts: list[str] = []
+    current: list[str] = []
+    paren_depth = 0
+    bracket_depth = 0
+    in_string = False
+    for character in arguments:
+        if character == '"':
+            in_string = not in_string
+            current.append(character)
+            continue
+        if not in_string:
+            if character == "[":
+                bracket_depth += 1
+            elif character == "]" and bracket_depth:
+                bracket_depth -= 1
+            elif bracket_depth == 0 and character == "(":
+                paren_depth += 1
+            elif bracket_depth == 0 and character == ")" and paren_depth:
+                paren_depth -= 1
+            elif bracket_depth == 0 and paren_depth == 0 and character == ",":
+                parts.append("".join(current).strip())
+                current = []
+                continue
+        current.append(character)
+    parts.append("".join(current).strip())
+    return tuple(parts)
+
+
+def _static_integer_argument(argument: str) -> int | None:
+    try:
+        return int(argument)
+    except ValueError:
+        return None
+
+
+def _static_offset_base(
+    source: WorkbookReference,
+    target: WorkbookReference,
+    tables: dict[str, TableRecord],
+) -> WorkbookReference | None:
+    if source.kind == "cell":
+        return source
+    if source.kind == "structured":
+        resolved = _resolve_structured_reference(source, target, tables)
+        return resolved if resolved is not None and resolved.kind == "cell" else None
+    return None
+
+
+def _shift_cell_reference(
+    reference: WorkbookReference,
+    *,
+    row_offset: int,
+    column_offset: int,
+) -> WorkbookReference | None:
+    if reference.sheet is None or reference.start_cell is None:
+        return None
+    try:
+        min_col, min_row, max_col, max_row = range_boundaries(reference.start_cell)
+    except ValueError:
+        return None
+    if min_col != max_col or min_row != max_row:
+        return None
+    shifted_column = min_col + column_offset
+    shifted_row = min_row + row_offset
+    if shifted_column < 1 or shifted_row < 1:
+        return None
+    return normalize_reference(f"{reference.sheet}!{get_column_letter(shifted_column)}{shifted_row}")
+
+
+def _resolve_structured_reference(
+    source: WorkbookReference,
+    target: WorkbookReference,
+    tables: dict[str, TableRecord],
+) -> WorkbookReference | None:
+    parsed = _parse_structured_reference(source.original)
+    if parsed is None:
+        return None
+
+    table = tables.get(parsed.table_name) if parsed.table_name is not None else _table_containing_target(target, tables)
+    if table is None:
+        return None
+
+    try:
+        min_col, min_row, max_col, max_row = range_boundaries(table.ref)
+    except ValueError:
+        return None
+
+    if parsed.column is None:
+        start_row = min_row if parsed.include_headers else min_row + 1
+        return normalize_reference(
+            f"{table.sheet}!{_column_name(min_col)}{start_row}:{_column_name(max_col)}{max_row}"
+        )
+
+    try:
+        column_offset = table.columns.index(parsed.column)
+    except ValueError:
+        return None
+
+    column_name = _column_name(min_col + column_offset)
+    data_start_row = min_row + 1
+    if parsed.current_row:
+        if target.sheet != table.sheet or target.start_cell is None:
+            return _resolve_cross_table_current_row(
+                source_table=table,
+                target=target,
+                column_name=column_name,
+                tables=tables,
+            )
+        try:
+            _target_col, target_row, _target_max_col, _target_max_row = range_boundaries(target.start_cell)
+        except ValueError:
+            return None
+        if target_row < data_start_row or target_row > max_row:
+            return _resolve_cross_table_current_row(
+                source_table=table,
+                target=target,
+                column_name=column_name,
+                tables=tables,
+            )
+        return normalize_reference(f"{table.sheet}!{column_name}{target_row}")
+
+    return normalize_reference(f"{table.sheet}!{column_name}{data_start_row}:{column_name}{max_row}")
+
+
+def _resolve_cross_table_current_row(
+    *,
+    source_table: TableRecord,
+    target: WorkbookReference,
+    column_name: str,
+    tables: dict[str, TableRecord],
+) -> WorkbookReference | None:
+    target_table = _table_containing_target(target, tables)
+    if target_table is None or target.start_cell is None:
+        return None
+
+    try:
+        _target_col, target_row, _target_max_col, _target_max_row = range_boundaries(target.start_cell)
+        _source_min_col, source_min_row, _source_max_col, source_max_row = range_boundaries(source_table.ref)
+        _target_min_col, target_min_row, _target_table_max_col, target_max_row = range_boundaries(target_table.ref)
+    except ValueError:
+        return None
+
+    source_data_rows = source_max_row - source_min_row
+    target_data_rows = target_max_row - target_min_row
+    if source_data_rows != target_data_rows:
+        return None
+
+    target_offset = target_row - (target_min_row + 1)
+    mapped_row = source_min_row + 1 + target_offset
+    if mapped_row < source_min_row + 1 or mapped_row > source_max_row:
+        return None
+    return normalize_reference(f"{source_table.sheet}!{column_name}{mapped_row}")
+
+
+@dataclass(frozen=True)
+class _StructuredReferenceParts:
+    table_name: str | None
+    column: str | None
+    current_row: bool
+    include_headers: bool
+
+
+def _parse_structured_reference(reference: str) -> _StructuredReferenceParts | None:
+    if "[" not in reference or "]" not in reference:
+        return None
+
+    table_name = reference.split("[", 1)[0] or None
+    bracketed_parts = _bracketed_parts(reference)
+    current_row = any(part == "#This Row" or part.startswith("@") for part in bracketed_parts)
+    if reference.startswith("[@"):
+        current_row = True
+    include_headers = any(part == "#All" for part in bracketed_parts)
+
+    column = next(
+        (
+            _clean_structured_selector(part)
+            for part in reversed(bracketed_parts)
+            if not part.startswith("#")
+        ),
+        None,
+    )
+    return _StructuredReferenceParts(
+        table_name=table_name,
+        column=column,
+        current_row=current_row,
+        include_headers=include_headers,
+    )
+
+
+def _bracketed_parts(reference: str) -> tuple[str, ...]:
+    parts: list[str] = []
+    current: list[str] = []
+    depth = 0
+    for character in reference:
+        if character == "[":
+            if depth > 0:
+                current.append(character)
+            depth += 1
+            continue
+        if character == "]":
+            depth -= 1
+            if depth == 0:
+                part = "".join(current)
+                current = []
+                if part.startswith("[") and part.endswith("]"):
+                    parts.extend(_bracketed_parts(part))
+                elif part:
+                    parts.append(part)
+                continue
+            current.append(character)
+            continue
+        if depth > 0:
+            current.append(character)
+    return tuple(parts)
+
+
+def _clean_structured_selector(selector: str) -> str:
+    return selector.removeprefix("@").replace("''", "'")
+
+
+def _table_containing_target(target: WorkbookReference, tables: dict[str, TableRecord]) -> TableRecord | None:
+    if target.sheet is None or target.start_cell is None:
+        return None
+
+    try:
+        target_col, target_row, _target_max_col, _target_max_row = range_boundaries(target.start_cell)
+    except ValueError:
+        return None
+
+    for table in tables.values():
+        if table.sheet != target.sheet:
+            continue
+        try:
+            min_col, min_row, max_col, max_row = range_boundaries(table.ref)
+        except ValueError:
+            continue
+        if min_col <= target_col <= max_col and min_row <= target_row <= max_row:
+            return table
+    return None
+
+
+def _expand_range_reference(source: WorkbookReference) -> tuple[WorkbookReference, ...]:
+    if source.sheet is None or source.start_cell is None or source.end_cell is None:
+        return ()
+
+    min_col, min_row, max_col, max_row = range_boundaries(f"{source.start_cell}:{source.end_cell}")
+    return tuple(
+        normalize_reference(f"{source.sheet}!{_column_name(column)}{row}")
+        for row in range(min_row, max_row + 1)
+        for column in range(min_col, max_col + 1)
+    )
+
+
+def _diagnostic_codes(edges: list[DependencyEdge]) -> tuple[str, ...]:
+    return tuple(edge.diagnostic_code for edge in edges if edge.diagnostic_code is not None)
+
+
+def _circular_dependency_codes(edges: list[DependencyEdge]) -> tuple[str, ...]:
+    execution_pairs = {
+        (edge.source.normalized, edge.target.normalized)
+        for edge in edges
+        if edge.edge_kind == "execution" and edge.source.kind == "cell" and edge.target.kind == "cell"
+    }
+    if any((target, source) in execution_pairs for source, target in execution_pairs):
+        return ("circular_dependency",)
+    return ()
+
+
+def _column_name(index: int) -> str:
+    name = ""
+    while index:
+        index, remainder = divmod(index - 1, 26)
+        name = chr(65 + remainder) + name
+    return name

modelwright/oracle_validation.py

@@ -0,0 +1,59 @@
+"""Validation report helpers for oracle-backed comparisons."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from modelwright.oracles import OracleResult
+from modelwright.validation import (
+    Diagnostic,
+    JsonValue,
+    ValidationReport,
+    ValidationScenario,
+    build_validation_report,
+)
+
+
+def build_oracle_validation_report(
+    *,
+    scenario: ValidationScenario,
+    generated_values: Mapping[str, JsonValue],
+    oracle_result: OracleResult,
+) -> ValidationReport:
+    """Compare generated values against an oracle result for one scenario."""
+
+    report = build_validation_report(
+        scenario=scenario,
+        generated_values=generated_values,
+        oracle_values=oracle_result.outputs,
+    )
+    diagnostics = list(_oracle_diagnostics(oracle_result))
+
+    if scenario.oracle.backend != oracle_result.backend:
+        diagnostics.append(
+            Diagnostic(
+                diagnostic_code="oracle_backend_mismatch",
+                message="scenario oracle backend does not match oracle result backend",
+                severity="error",
+                location=scenario.scenario_id,
+            )
+        )
+
+    return ValidationReport(
+        scenario_id=report.scenario_id,
+        oracle_backend=oracle_result.backend,
+        comparisons=report.comparisons,
+        diagnostics=tuple(diagnostics),
+    )
+
+
+def _oracle_diagnostics(oracle_result: OracleResult) -> tuple[Diagnostic, ...]:
+    return tuple(
+        Diagnostic(
+            diagnostic_code=diagnostic.diagnostic_code,
+            message=diagnostic.message,
+            severity=diagnostic.severity,
+            location=diagnostic.location,
+        )
+        for diagnostic in oracle_result.diagnostics
+    )