20389851973

Committed 20 Dec 2025 05:31AM UTC coverage: 89.185% (+0.04%) from 89.145%

Build # 20389851973

Build Type

push

github

Committed by

bramp

Commit Message

Add support for `ty` to the pyproject.toml.

Run Details

13384 of 15007 relevant lines covered (89.19%)

0.89 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

99.53

/src/build_a_long/pdf_extract/validation/validation_test.py

"""Tests for validation module."""

from typing import Any

import pydantic

from build_a_long.pdf_extract.classifier import (
    BatchClassificationResult,
    Candidate,
    ClassificationResult,
    TextHistogram,
)
from build_a_long.pdf_extract.classifier.test_utils import TestScore
from build_a_long.pdf_extract.extractor import PageData
from build_a_long.pdf_extract.extractor.bbox import BBox
from build_a_long.pdf_extract.extractor.lego_page_elements import (
    Background,
    CatalogContent,
    Divider,
    InstructionContent,
    Manual,
    Page,
    PageNumber,
    Part,
    PartCount,
    PartImage,
    PartsList,
    ProgressBar,
    ProgressBarBar,
    Step,
    StepNumber,
)

from .printer import print_validation
from .rules import (
    format_ranges,
    validate_catalog_coverage,
    validate_elements_within_page,
    validate_first_page_number,
    validate_missing_page_numbers,
    validate_no_divider_intersection,
    validate_page_number_sequence,
    validate_parts_list_has_parts,
    validate_parts_lists_no_overlap,
    validate_progress_bar_sequence,
    validate_step_sequence,
    validate_steps_have_parts,
    validate_steps_no_significant_overlap,
)
from .runner import validate_results
from .types import ValidationIssue, ValidationResult, ValidationSeverity


class TestValidationResult:
    """Tests for ValidationResult class."""

    def test_empty_result(self) -> None:
        """Test empty validation result."""
        result = ValidationResult()
        assert result.error_count == 0
        assert result.warning_count == 0
        assert result.info_count == 0
        assert not result.has_issues()

    def test_add_issue(self) -> None:
        """Test adding issues to result."""
        result = ValidationResult()
        result.add(
            ValidationIssue(
                severity=ValidationSeverity.ERROR,
                rule="test",
                message="test error",
            )
        )
        result.add(
            ValidationIssue(
                severity=ValidationSeverity.WARNING,
                rule="test",
                message="test warning",
            )
        )
        result.add(
            ValidationIssue(
                severity=ValidationSeverity.INFO,
                rule="test",
                message="test info",
            )
        )

        assert result.error_count == 1
        assert result.warning_count == 1
        assert result.info_count == 1
        assert result.has_issues()

    def test_frozen_issue(self) -> None:
        """Test that ValidationIssue is immutable."""

        issue = ValidationIssue(
            severity=ValidationSeverity.ERROR,
            rule="test",
            message="test",
        )
        # Should not be able to modify (Pydantic frozen model raises ValidationError)
        try:
            issue.message = "new message"  # type: ignore[misc]
            raise AssertionError("Expected frozen model to raise")
        except pydantic.ValidationError:
            pass  # Expected


class TestFormatRanges:
    """Tests for format_ranges helper function."""

    def test_empty_list(self) -> None:
        """Test empty list."""
        assert format_ranges([]) == ""

    def test_single_number(self) -> None:
        """Test single number."""
        assert format_ranges([5]) == "5"

    def test_consecutive_range(self) -> None:
        """Test consecutive numbers form a range."""
        assert format_ranges([1, 2, 3, 4, 5]) == "1-5"

    def test_separate_numbers(self) -> None:
        """Test non-consecutive numbers."""
        assert format_ranges([1, 3, 5]) == "1, 3, 5"

    def test_mixed_ranges(self) -> None:
        """Test mixed ranges and single numbers."""
        assert format_ranges([1, 2, 3, 5, 7, 8, 9]) == "1-3, 5, 7-9"

    def test_long_list_truncation(self) -> None:
        """Test that very long output is truncated."""
        # Create a list that would produce a very long string
        numbers = list(range(1, 200, 2))  # Odd numbers 1-199
        result = format_ranges(numbers)
        assert len(result) <= 100
        assert result.endswith("...")


class TestValidateMissingPageNumbers:
    """Tests for validate_missing_page_numbers rule."""

    def test_no_missing_pages(self) -> None:
        """Test when all pages have page numbers."""
        validation = ValidationResult()
        validate_missing_page_numbers(validation, [], 10)
        assert not validation.has_issues()

    def test_high_coverage(self) -> None:
        """Test >90% coverage produces INFO."""
        validation = ValidationResult()
        validate_missing_page_numbers(validation, [1], 20)  # 95% coverage
        assert validation.info_count == 1
        assert validation.issues[0].severity == ValidationSeverity.INFO

    def test_medium_coverage(self) -> None:
        """Test 50-90% coverage produces WARNING."""
        validation = ValidationResult()
        validate_missing_page_numbers(validation, [1, 2, 3], 10)  # 70% coverage
        assert validation.warning_count == 1

    def test_low_coverage(self) -> None:
        """Test <50% coverage produces ERROR."""
        validation = ValidationResult()
        validate_missing_page_numbers(validation, list(range(1, 8)), 10)  # 30% coverage
        assert validation.error_count == 1


class TestValidateStepSequence:
    """Tests for validate_step_sequence rule."""

    def test_empty_steps(self) -> None:
        """Test empty step list."""
        validation = ValidationResult()
        validate_step_sequence(validation, [])
        assert not validation.has_issues()

    def test_valid_sequence(self) -> None:
        """Test valid step sequence starting at 1."""
        validation = ValidationResult()
        validate_step_sequence(validation, [(1, 1), (2, 2), (3, 3)])
        assert not validation.has_issues()

    def test_duplicate_steps(self) -> None:
        """Test duplicate step numbers."""
        validation = ValidationResult()
        validate_step_sequence(validation, [(1, 1), (2, 1), (3, 2)])  # Step 1 twice
        # Should have warning about duplicates
        assert any(i.rule == "duplicate_steps" for i in validation.issues)

    def test_step_gaps(self) -> None:
        """Test gaps in step sequence."""
        validation = ValidationResult()
        validate_step_sequence(validation, [(1, 1), (2, 3)])  # Missing step 2
        assert any(i.rule == "step_gaps" for i in validation.issues)

    def test_step_not_starting_at_one(self) -> None:
        """Test sequence not starting at 1."""
        validation = ValidationResult()
        validate_step_sequence(validation, [(1, 5), (2, 6), (3, 7)])  # Starts at 5
        assert any(i.rule == "step_start" for i in validation.issues)


class TestValidateFirstPageNumber:
    """Tests for validate_first_page_number rule."""

    def test_no_page_numbers(self) -> None:
        """Test when no page numbers detected."""
        validation = ValidationResult()
        validate_first_page_number(validation, [])
        assert validation.error_count == 1
        assert validation.issues[0].rule == "no_page_numbers"

    def test_reasonable_first_page(self) -> None:
        """Test reasonable first page number."""
        validation = ValidationResult()
        validate_first_page_number(validation, [1, 2, 3])
        assert not validation.has_issues()

    def test_high_first_page(self) -> None:
        """Test high first page number."""
        validation = ValidationResult()
        validate_first_page_number(validation, [15, 16, 17])
        assert any(i.rule == "high_first_page" for i in validation.issues)


class TestValidatePageNumberSequence:
    """Tests for validate_page_number_sequence rule."""

    def test_single_page(self) -> None:
        """Test single page number."""
        validation = ValidationResult()
        validate_page_number_sequence(validation, [1])
        assert not validation.has_issues()

    def test_valid_sequence(self) -> None:
        """Test valid consecutive sequence."""
        validation = ValidationResult()
        validate_page_number_sequence(validation, [1, 2, 3, 4, 5])
        assert not validation.has_issues()

    def test_valid_sequence_starting_later(self) -> None:
        """Test valid consecutive sequence that doesn't start at 1.

        First few pages missing is OK (e.g., cover pages without page numbers).
        """
        validation = ValidationResult()
        validate_page_number_sequence(validation, [5, 6, 7, 8, 9])
        assert not validation.has_issues()

    def test_valid_sequence_ending_early(self) -> None:
        """Test valid consecutive sequence that might end before the last page.

        Last few pages missing is OK (e.g., back cover without page numbers).
        This tests the sequence is consecutive - we don't know total pages here.
        """
        validation = ValidationResult()
        # Sequence 10-14 is consecutive, even if there could be more pages
        validate_page_number_sequence(validation, [10, 11, 12, 13, 14])
        assert not validation.has_issues()

    def test_valid_sequence_starting_later_and_ending_early(self) -> None:
        """Test consecutive sequence with both start and end pages missing.

        Both first N and last M pages can be missing, as long as there are no
        gaps in the middle.
        """
        validation = ValidationResult()
        validate_page_number_sequence(validation, [5, 6, 7, 8, 9, 10])
        assert not validation.has_issues()

    def test_decreasing_sequence(self) -> None:
        """Test decreasing page numbers."""
        validation = ValidationResult()
        validate_page_number_sequence(validation, [1, 2, 5, 3, 4])  # Decreases at 3
        assert any(i.rule == "page_sequence" for i in validation.issues)

    def test_gap_in_middle(self) -> None:
        """Test gap in the middle of page numbers."""
        validation = ValidationResult()
        validate_page_number_sequence(validation, [1, 2, 5, 6])  # Gap: 2->5
        assert any(i.rule == "page_gaps" for i in validation.issues)
        # Should be a warning now
        gap_issue = next(i for i in validation.issues if i.rule == "page_gaps")
        assert gap_issue.severity == ValidationSeverity.WARNING

    def test_small_gap_not_allowed(self) -> None:
        """Test that even small gaps (>1) are flagged."""
        validation = ValidationResult()
        validate_page_number_sequence(validation, [1, 2, 4, 5])  # Gap: 2->4
        assert any(i.rule == "page_gaps" for i in validation.issues)


class TestValidateProgressBarSequence:
    """Tests for validate_progress_bar_sequence rule."""

    def test_empty_progress_bars(self) -> None:
        """Test empty progress bar list."""
        validation = ValidationResult()
        validate_progress_bar_sequence(validation, [])
        assert not validation.has_issues()

    def test_valid_sequence(self) -> None:
        """Test valid monotonically increasing sequence."""
        validation = ValidationResult()
        # (page, value) tuples
        validate_progress_bar_sequence(
            validation, [(1, 0.1), (2, 0.2), (3, 0.3), (4, 0.4)]
        )
        assert not validation.has_issues()

    def test_decreasing_sequence(self) -> None:
        """Test decreasing progress bar values."""
        validation = ValidationResult()
        validate_progress_bar_sequence(
            validation,
            [(1, 0.5), (2, 0.4), (3, 0.6)],  # Decreases at p.2
        )
        assert validation.warning_count == 1
        assert validation.issues[0].rule == "progress_bar_decrease"

    def test_consistent_increments(self) -> None:
        """Test consistent progress increments (steady rate)."""
        validation = ValidationResult()
        # Constant 0.1 increment
        validate_progress_bar_sequence(
            validation,
            [(1, 0.1), (2, 0.2), (3, 0.3), (4, 0.4), (5, 0.5), (6, 0.6)],
        )
        assert not validation.has_issues()

    def test_inconsistent_increments(self) -> None:
        """Test inconsistent progress increments (high variance)."""
        validation = ValidationResult()
        # Increments vary wildly: 0.01, 0.4, 0.01, 0.01, 0.01
        validate_progress_bar_sequence(
            validation,
            [(1, 0.1), (2, 0.11), (3, 0.51), (4, 0.52), (5, 0.53), (6, 0.54)],
        )
        assert any(i.rule == "progress_bar_inconsistent" for i in validation.issues)
        issue = next(
            i for i in validation.issues if i.rule == "progress_bar_inconsistent"
        )
        assert issue.severity == ValidationSeverity.INFO

    def test_not_enough_samples(self) -> None:
        """Test that consistency check is skipped for few samples."""
        validation = ValidationResult()
        # Highly inconsistent, but only 5 samples (needs >5)
        validate_progress_bar_sequence(
            validation,
            [(1, 0.1), (2, 0.11), (3, 0.51), (4, 0.52), (5, 0.53)],
        )
        # Should be ignored because there are fewer than 5 samples
        assert not validation.has_issues()


class TestValidateCatalogCoverage:
    """Tests for validate_catalog_coverage rule."""

    def _make_part_with_image(
        self,
        image_id: str | None = None,
        xref: int | None = None,
        digest: bytes | None = None,
    ) -> Part:
        """Create a Part with a diagram image ID, xref, and/or digest."""

        return Part(
            bbox=BBox(0, 0, 10, 10),
            count=PartCount(bbox=BBox(0, 0, 5, 5), count=1),
            diagram=PartImage(
                bbox=BBox(0, 0, 10, 10),
                image_id=image_id,
                xref=xref,
                digest=digest,
            ),
        )

    def _make_manual(
        self,
        instruction_parts_config: list[dict[str, Any]],
        catalog_parts_config: list[dict[str, Any]],
    ) -> Manual:
        """Create a Manual with specified parts.

        Args:
            instruction_parts_config: List of dicts with keys 'image_id', 'xref',
                'digest'
            catalog_parts_config: List of dicts with keys 'image_id', 'xref',
                'digest'
        """
        pages = []

        # Instruction page
        if instruction_parts_config:
            parts = [
                self._make_part_with_image(**cfg) for cfg in instruction_parts_config
            ]
            step = Step(
                bbox=BBox(0, 0, 100, 100),
                step_number=StepNumber(bbox=BBox(0, 0, 10, 10), value=1),
                parts_list=PartsList(bbox=BBox(0, 0, 50, 50), parts=parts),
            )
            pages.append(
                Page(
                    bbox=BBox(0, 0, 100, 100),
                    pdf_page_number=1,
                    page_number=PageNumber(bbox=BBox(90, 90, 100, 100), value=1),
                    categories={Page.PageType.INSTRUCTION},
                    instruction=InstructionContent(steps=[step]),
                )
            )

        # Catalog page
        if catalog_parts_config:
            parts = [self._make_part_with_image(**cfg) for cfg in catalog_parts_config]
            pages.append(
                Page(
                    bbox=BBox(0, 0, 100, 100),
                    pdf_page_number=2,
                    page_number=PageNumber(bbox=BBox(90, 90, 100, 100), value=2),
                    categories={Page.PageType.CATALOG},
                    catalog=CatalogContent(parts=parts),
                )
            )

        return Manual(pages=pages)

    def test_no_catalog_pages(self) -> None:
        """Test when no catalog pages are present."""
        manual = self._make_manual([{"xref": 1}], [])
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)
        assert not validation.has_issues()

    def test_no_instruction_parts(self) -> None:
        """Test when no instruction parts are found."""
        manual = self._make_manual([], [{"xref": 1}])
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)
        assert not validation.has_issues()

    def test_perfect_coverage_xref(self) -> None:
        """Test when all instruction parts are in catalog using xref."""
        manual = self._make_manual(
            [{"xref": 1}, {"xref": 2}],
            [{"xref": 1}, {"xref": 2}, {"xref": 3}],
        )
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)
        assert validation.info_count == 1
        assert "100.0%" in validation.issues[0].message

    def test_perfect_coverage_digest(self) -> None:
        """Test when all instruction parts are in catalog using digest."""
        manual = self._make_manual(
            [{"digest": b"a"}, {"digest": b"b"}],
            [{"digest": b"a"}, {"digest": b"b"}, {"digest": b"c"}],
        )
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)
        assert validation.info_count == 1
        assert "100.0%" in validation.issues[0].message

    def test_mixed_matching(self) -> None:
        """Test matching using both xref and digest."""
        manual = self._make_manual(
            [
                {"xref": 1},  # Matches by xref
                {"digest": b"b"},  # Matches by digest
                {"xref": 3, "digest": b"c"},  # Matches by xref (preferred)
            ],
            [
                {"xref": 1, "digest": b"x"},
                {"xref": 9, "digest": b"b"},
                {"xref": 3, "digest": b"z"},
            ],
        )
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)
        assert validation.info_count == 1
        assert "100.0%" in validation.issues[0].message

    def test_partial_coverage_experimental(self) -> None:
        """Test partial coverage with experimental flag (INFO)."""
        # 1 match (xref), 1 missing
        manual = self._make_manual(
            [{"xref": 1}, {"xref": 2}],
            [{"xref": 1}],
        )
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual, experimental=True)

        # 1 INFO for coverage stat, 1 INFO for missing parts (experimental)
        assert validation.info_count == 2
        assert validation.warning_count == 0
        assert any(i.rule == "missing_from_catalog" for i in validation.issues)
        missing_issue = next(
            i for i in validation.issues if i.rule == "missing_from_catalog"
        )
        assert missing_issue.severity == ValidationSeverity.INFO
        assert "[EXPERIMENTAL]" in missing_issue.message
        assert missing_issue.details is not None
        assert "xref:2" in missing_issue.details

    def test_partial_coverage_strict(self) -> None:
        """Test partial coverage without experimental flag (WARNING)."""
        # 1 match, 1 missing
        manual = self._make_manual(
            [{"digest": b"a"}, {"digest": b"b"}],
            [{"digest": b"a"}],
        )
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual, experimental=False)

        # 1 INFO for coverage stat, 1 WARNING for missing parts
        assert validation.info_count == 1
        assert validation.warning_count == 1
        assert any(i.rule == "missing_from_catalog" for i in validation.issues)
        missing_issue = next(
            i for i in validation.issues if i.rule == "missing_from_catalog"
        )
        assert missing_issue.severity == ValidationSeverity.WARNING
        assert "[EXPERIMENTAL]" not in missing_issue.message
        assert missing_issue.details is not None
        assert "digest:" in missing_issue.details  # Hex representation of b"b"

    def test_zero_coverage(self) -> None:
        """Test zero coverage (should not warn, assumes no image reuse)."""
        manual = self._make_manual([{"xref": 1}], [{"xref": 2}])
        validation = ValidationResult()
        validate_catalog_coverage(validation, manual)

        # Only stats info, no warning because coverage is 0%
        assert validation.info_count == 1
        assert validation.warning_count == 0
        assert "0.0%" in validation.issues[0].message


class TestValidateStepsHaveParts:
    """Tests for validate_steps_have_parts rule."""

    def test_all_steps_have_parts(self) -> None:
        """Test when all steps have parts."""
        validation = ValidationResult()
        validate_steps_have_parts(validation, [])
        assert not validation.has_issues()

    def test_some_steps_missing_parts(self) -> None:
        """Test some steps missing parts."""
        validation = ValidationResult()
        # (page, step_number) tuples
        validate_steps_have_parts(validation, [(1, 1), (3, 5), (5, 10)])
        assert validation.info_count == 1
        issue = validation.issues[0]
        assert issue.rule == "steps_without_parts"
        assert issue.pages == [1, 3, 5]
        assert issue.details is not None
        assert "step 1 (p.1)" in issue.details
        assert "step 5 (p.3)" in issue.details
        assert "step 10 (p.5)" in issue.details


def _make_page_data(page_num: int) -> PageData:
    """Create a minimal PageData for testing."""
    return PageData(
        page_number=page_num,
        bbox=BBox(0, 0, 100, 100),
        blocks=[],
    )


def _make_classification_result(
    page_data: PageData,
    page_number_val: int | None = None,
    step_numbers: list[int] | None = None,
    include_parts: bool = True,
) -> ClassificationResult:
    """Create a ClassificationResult with a Page for testing.

    Args:
        page_data: The PageData to associate
        page_number_val: The LEGO page number value (None for no page number)
        step_numbers: List of step numbers to include
        include_parts: Whether to include parts lists in steps
    """
    result = ClassificationResult(page_data=page_data)

    # Build the Page object
    page_num_elem = (
        PageNumber(bbox=BBox(0, 90, 10, 100), value=page_number_val)
        if page_number_val is not None
        else None
    )

    step_elems: list[Step] = []
    if step_numbers:
        for step_num in step_numbers:
            parts_list = None
            if include_parts:
                parts_list = PartsList(
                    bbox=BBox(0, 0, 20, 10),
                    parts=[
                        Part(
                            bbox=BBox(0, 0, 10, 10),
                            count=PartCount(bbox=BBox(0, 0, 5, 5), count=1),
                        )
                    ],
                )
            step_elems.append(
                Step(
                    bbox=BBox(0, 0, 80, 80),
                    step_number=StepNumber(bbox=BBox(0, 10, 10, 20), value=step_num),
                    parts_list=parts_list,
                )
            )

    page = Page(
        bbox=BBox(0, 0, 100, 100),
        pdf_page_number=page_data.page_number,
        page_number=page_num_elem,
        instruction=InstructionContent(steps=step_elems) if step_elems else None,
    )

    # Add a candidate for the page
    candidate = Candidate(
        label="page",
        source_blocks=[],
        bbox=page.bbox,
        score=1.0,
        score_details=TestScore(),
        constructed=page,
    )
    result.add_candidate(candidate)

    return result


class TestValidateResults:
    """Tests for the main validate_results function."""

    def test_perfect_document(self) -> None:
        """Test document with no issues."""
        pages = [_make_page_data(i) for i in range(1, 4)]
        results = [
            _make_classification_result(pages[0], page_number_val=1, step_numbers=[1]),
            _make_classification_result(pages[1], page_number_val=2, step_numbers=[2]),
            _make_classification_result(pages[2], page_number_val=3, step_numbers=[3]),
        ]
        batch_result = BatchClassificationResult(
            results=results, histogram=TextHistogram.empty()
        )

        validation = validate_results(batch_result)
        # No errors or warnings expected
        assert validation.error_count == 0
        assert validation.warning_count == 0

    def test_missing_page_numbers(self) -> None:
        """Test detection of missing page numbers."""
        pages = [_make_page_data(i) for i in range(1, 4)]
        results = [
            _make_classification_result(
                pages[0], page_number_val=None, step_numbers=[1]
            ),
            _make_classification_result(pages[1], page_number_val=2, step_numbers=[2]),
            _make_classification_result(
                pages[2], page_number_val=None, step_numbers=[3]
            ),
        ]
        batch_result = BatchClassificationResult(
            results=results, histogram=TextHistogram.empty()
        )

        validation = validate_results(batch_result)
        assert any(i.rule == "missing_page_numbers" for i in validation.issues)

    def test_step_sequence_issues(self) -> None:
        """Test detection of step sequence issues."""
        pages = [_make_page_data(i) for i in range(1, 4)]
        results = [
            _make_classification_result(pages[0], page_number_val=1, step_numbers=[1]),
            _make_classification_result(
                pages[1], page_number_val=2, step_numbers=[3]
            ),  # Skipped step 2
            _make_classification_result(pages[2], page_number_val=3, step_numbers=[4]),
        ]
        batch_result = BatchClassificationResult(
            results=results, histogram=TextHistogram.empty()
        )

        validation = validate_results(batch_result)
        assert any(i.rule == "step_gaps" for i in validation.issues)


class TestPrintValidation:
    """Tests for print_validation function."""

    def test_print_no_issues(self, capsys: object) -> None:
        """Test printing when no issues."""
        validation = ValidationResult()
        print_validation(validation)
        # Check output contains success message
        captured = capsys.readouterr()  # type: ignore[union-attr]
        assert "passed" in captured.out

    def test_print_with_issues(self, capsys: object) -> None:
        """Test printing with various issues."""
        validation = ValidationResult()
        validation.add(
            ValidationIssue(
                severity=ValidationSeverity.ERROR,
                rule="test_error",
                message="Test error message",
                pages=[1, 2, 3],
            )
        )
        validation.add(
            ValidationIssue(
                severity=ValidationSeverity.WARNING,
                rule="test_warning",
                message="Test warning message",
                details="Some details",
            )
        )

        print_validation(validation, use_color=False)
        captured = capsys.readouterr()  # type: ignore[union-attr]

        assert "test_error" in captured.out
        assert "Test error message" in captured.out
        assert "test_warning" in captured.out
        assert "Some details" in captured.out


# =============================================================================
# Domain Invariant Validation Rules Tests
# =============================================================================


def _make_page_with_steps(
    step_data: list[tuple[int, BBox, BBox | None]],  # (step_num, step_bbox, pl_bbox)
    page_number_val: int = 1,
    page_bbox: BBox | None = None,
) -> tuple[Page, PageData]:
    """Create a Page with steps for testing domain invariants.

    Args:
        step_data: List of (step_number, step_bbox, parts_list_bbox) tuples.
            If parts_list_bbox is None, no parts list is added.
        page_number_val: The page number value
        page_bbox: The page bounding box (default 0,0,100,100)

    Returns:
        Tuple of (Page, PageData)
    """
    if page_bbox is None:
        page_bbox = BBox(0, 0, 100, 100)

    page_data = PageData(
        page_number=1,
        bbox=page_bbox,
        blocks=[],
    )

    steps = []
    for step_num, step_bbox, pl_bbox in step_data:
        parts_list = None
        if pl_bbox is not None:
            # Create a parts list with one part
            part = Part(
                bbox=BBox(pl_bbox.x0, pl_bbox.y0, pl_bbox.x1, pl_bbox.y1 - 5),
                count=PartCount(
                    bbox=BBox(pl_bbox.x0, pl_bbox.y1 - 5, pl_bbox.x1, pl_bbox.y1),
                    count=1,
                ),
            )
            parts_list = PartsList(bbox=pl_bbox, parts=[part])

        step = Step(
            bbox=step_bbox,
            step_number=StepNumber(
                bbox=BBox(
                    step_bbox.x0, step_bbox.y0, step_bbox.x0 + 10, step_bbox.y0 + 10
                ),
                value=step_num,
            ),
            parts_list=parts_list,
        )
        steps.append(step)

    page = Page(
        bbox=page_bbox,
        pdf_page_number=1,
        page_number=PageNumber(bbox=BBox(90, 90, 100, 100), value=page_number_val),
        instruction=InstructionContent(steps=steps) if steps else None,
    )

    return page, page_data


class TestValidatePartsListHasParts:
    """Tests for validate_parts_list_has_parts rule."""

    def test_no_empty_parts_lists(self) -> None:
        """Test page with all parts lists having parts."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 50, 50), BBox(40, 0, 50, 20)),
            ]
        )
        validation = ValidationResult()
        validate_parts_list_has_parts(validation, page, page_data)
        assert not validation.has_issues()

    def test_empty_parts_list(self) -> None:
        """Test detection of empty parts list."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 50, 50), BBox(40, 0, 50, 20)),
            ]
        )
        # Manually empty the parts list
        assert page.instruction is not None
        page.instruction.steps[0].parts_list.parts = []  # type: ignore[union-attr]

        validation = ValidationResult()
        validate_parts_list_has_parts(validation, page, page_data)
        assert validation.warning_count == 1
        assert validation.issues[0].rule == "empty_parts_list"


class TestValidatePartsListsNoOverlap:
    """Tests for validate_parts_lists_no_overlap rule."""

    def test_non_overlapping_parts_lists(self) -> None:
        """Test page with non-overlapping parts lists."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 45, 50), BBox(35, 0, 45, 20)),
                (2, BBox(55, 0, 100, 50), BBox(90, 0, 100, 20)),
            ]
        )
        validation = ValidationResult()
        validate_parts_lists_no_overlap(validation, page, page_data)
        assert not validation.has_issues()

    def test_overlapping_parts_lists(self) -> None:
        """Test detection of overlapping parts lists."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 60, 50), BBox(40, 0, 60, 20)),
                (2, BBox(40, 0, 100, 50), BBox(40, 0, 60, 20)),  # Same bbox!
            ]
        )
        validation = ValidationResult()
        validate_parts_lists_no_overlap(validation, page, page_data)
        assert validation.error_count == 1
        assert validation.issues[0].rule == "overlapping_parts_lists"


class TestValidateStepsNoSignificantOverlap:
    """Tests for validate_steps_no_significant_overlap rule."""

    def test_non_overlapping_steps(self) -> None:
        """Test page with non-overlapping steps."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 45, 50), None),
                (2, BBox(55, 0, 100, 50), None),
            ]
        )
        validation = ValidationResult()
        validate_steps_no_significant_overlap(validation, page, page_data)
        assert not validation.has_issues()

    def test_significantly_overlapping_steps(self) -> None:
        """Test detection of significantly overlapping steps."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 80, 50), None),
                (2, BBox(20, 0, 100, 50), None),  # 60% overlap
            ]
        )
        validation = ValidationResult()
        validate_steps_no_significant_overlap(
            validation, page, page_data, overlap_threshold=0.05
        )
        assert validation.warning_count == 1
        assert validation.issues[0].rule == "overlapping_steps"

    def test_minor_overlap_allowed(self) -> None:
        """Test that minor overlap below threshold is allowed."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(0, 0, 51, 50), None),
                (2, BBox(50, 0, 100, 50), None),  # 1px overlap
            ]
        )
        validation = ValidationResult()
        validate_steps_no_significant_overlap(
            validation, page, page_data, overlap_threshold=0.05
        )
        assert not validation.has_issues()


class TestValidateElementsWithinPage:
    """Tests for validate_elements_within_page rule."""

    def test_elements_within_bounds(self) -> None:
        """Test page with all elements within bounds."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(10, 10, 90, 90), BBox(70, 10, 90, 30)),
            ]
        )
        validation = ValidationResult()
        validate_elements_within_page(validation, page, page_data)
        assert not validation.has_issues()

    def test_element_outside_bounds(self) -> None:
        """Test detection of element outside page bounds."""
        page, page_data = _make_page_with_steps(
            [
                (1, BBox(10, 10, 110, 90), None),  # Extends past right edge
            ]
        )
        validation = ValidationResult()
        validate_elements_within_page(validation, page, page_data)
        assert validation.error_count >= 1
        assert any(i.rule == "element_outside_page" for i in validation.issues)


class TestValidateNoDividerIntersection:
    """Tests for validate_no_divider_intersection rule."""

    def _make_page_with_divider(
        self,
        divider_bbox: BBox,
        element_bbox: BBox,
        element_type: str = "Step",
    ) -> tuple[Page, PageData]:
        """Create a page with a divider and one other element."""

        page_bbox = BBox(0, 0, 100, 100)
        page_data = PageData(page_number=1, bbox=page_bbox, blocks=[])

        divider = Divider(bbox=divider_bbox, orientation=Divider.Orientation.VERTICAL)

        element: Any
        if element_type == "Step":
            element = Step(
                bbox=element_bbox,
                step_number=StepNumber(bbox=element_bbox, value=1),
            )
            steps = [element]
            background = None
            progress_bar = None
        elif element_type == "Background":
            element = Background(bbox=element_bbox)
            steps = []
            background = element
            progress_bar = None
        elif element_type == "ProgressBar":
            bar = ProgressBarBar(bbox=element_bbox)
            element = ProgressBar(bbox=element_bbox, full_width=100, bar=bar)
            steps = []
            background = None
            progress_bar = element
        else:
            raise ValueError(f"Unknown element type: {element_type}")

        page = Page(
            bbox=page_bbox,
            pdf_page_number=1,
            dividers=[divider],
            instruction=InstructionContent(steps=steps) if steps else None,
            background=background,
            progress_bar=progress_bar,
        )

        return page, page_data

    def test_no_dividers(self) -> None:
        """Test checking a page with no dividers."""
        page, page_data = _make_page_with_steps([(1, BBox(0, 0, 10, 10), None)])
        validation = ValidationResult()
        validate_no_divider_intersection(validation, page, page_data)
        assert not validation.has_issues()

    def test_no_intersection(self) -> None:
        """Test element not intersecting divider."""
        page, page_data = self._make_page_with_divider(
            divider_bbox=BBox(50, 0, 51, 100),  # Vertical line at x=50
            element_bbox=BBox(0, 0, 40, 40),  # Left side
        )
        validation = ValidationResult()
        validate_no_divider_intersection(validation, page, page_data)
        assert not validation.has_issues()

    def test_intersection(self) -> None:
        """Test element intersecting divider."""
        page, page_data = self._make_page_with_divider(
            divider_bbox=BBox(50, 0, 51, 100),  # Vertical line at x=50
            element_bbox=BBox(40, 0, 60, 40),  # Crosses x=50
        )
        validation = ValidationResult()
        validate_no_divider_intersection(validation, page, page_data)
        assert validation.warning_count >= 1
        assert any(i.rule == "divider_intersection" for i in validation.issues)

    def test_excluded_elements_ignored(self) -> None:
        """Test that excluded elements (Background, ProgressBar) are ignored."""
        # Test Background intersection
        page, page_data = self._make_page_with_divider(
            divider_bbox=BBox(50, 0, 51, 100),
            element_bbox=BBox(0, 0, 100, 100),  # Full page background
            element_type="Background",
        )
        validation = ValidationResult()
        validate_no_divider_intersection(validation, page, page_data)
        assert not validation.has_issues()

        # Test ProgressBar intersection
        page, page_data = self._make_page_with_divider(
            divider_bbox=BBox(50, 0, 51, 100),
            element_bbox=BBox(0, 90, 100, 100),  # Bottom bar crossing divider
            element_type="ProgressBar",
        )
        validate_no_divider_intersection(validation, page, page_data)
        assert not validation.has_issues()

bramp / build-along / 20389851973

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous