dsp-tools 0.9.13__py3-none-any.whl → 18.3.0.post13__py3-none-any.whl

dsp_tools/commands/update_legal/CLAUDE.md

@@ -0,0 +1,344 @@
+# Update Legal Metadata Command
+
+## Purpose
+
+The `update-legal` command converts legal metadata in XML files from the old format (text properties)
+to the new format (bitstream attributes). This migration is necessary because:
+
+- **Old format**: Legal metadata (authorship, copyright, license) stored as `<text-prop>` elements within resources
+- **New format**: Legal metadata stored as attributes directly on `<bitstream>` or `<iiif-uri>` elements
+
+This command automates the migration while handling validation, error correction, and authorship deduplication.
+
+## Command Usage
+
+```bash
+dsp-tools update-legal \
+  --authorship_prop=":hasAuthor" \
+  --copyright_prop=":hasCopyright" \
+  --license_prop=":hasLicense" \
+  --authorship_default="Project Member" \
+  --copyright_default="University" \
+  --license_default="CC BY" \
+  --fixed_errors="data_legal_errors.csv" \
+  data.xml
+```
+
+See [docs/special-workflows/update-legal.md](../../../../docs/special-workflows/update-legal.md) for user documentation.
+
+## Architecture Overview
+
+### Data Flow Pipeline
+
+The command follows a multi-stage pipeline:
+
+1. **Parse & Validate**: Parse XML file and validate property names exist
+2. **Extract Metadata**: For each resource with media, extract legal metadata using priority system
+3. **Validation**: Check for missing/invalid values
+4. **Error Handling**: If errors exist, write CSV for manual correction
+5. **Update XML**: If no errors, apply metadata as attributes and write updated XML
+6. **Iteration**: User fixes CSV and reruns command until all errors resolved
+
+### Priority System
+
+Metadata values are resolved using this priority order:
+
+1. **CSV corrections** (from `--fixed_errors` file)
+2. **XML properties** (extracted from text-prop elements)
+3. **Default values** (from `--*_default` flags)
+4. **None** (triggers validation error)
+
+## Module Responsibilities
+
+### [core.py](core.py)
+
+Main orchestration and validation logic:
+
+- `update_legal_metadata()`: Entry point that coordinates entire workflow
+- `_validate_flags()`: Ensures property names exist in XML
+- `_update_xml_tree()`: Iterates through resources, collects metadata once per resource, decides whether to apply changes
+- `_has_problems()`: Checks if metadata contains FIXME markers or missing values
+- `_update_counter()`: Tracks statistics for final report
+
+Key patterns:
+
+- Uses functional approach with pure helper functions
+- Clear separation: collection (read-only) vs application (mutations)
+- Single-pass metadata collection eliminates duplicate work
+- Authorship deduplication via `auth_text_to_id` dictionary (maps authorship text to unique ID)
+
+### [models.py](models.py)
+
+Data structures and configuration:
+
+- `LegalProperties`: Configuration for XML property names (e.g., `:hasAuthor`)
+- `LegalMetadata`: Represents legal metadata for a single resource (license, copyright, authorships)
+- `LegalMetadataDefaults`: Default values with automatic license parsing
+- `Problem`: Represents validation error for CSV export
+- `UpdateCounter`: Statistics tracker for final report
+
+Important notes:
+
+- `LegalMetadataDefaults.__init__()` automatically validates and parses license strings
+  using `xmllib.find_license_in_string()`
+- All dataclasses use frozen=True for immutability where appropriate
+
+### [csv_operations.py](csv_operations.py)
+
+CSV I/O for error handling workflow:
+
+- `ProblemAggregator`: Converts problems to DataFrame with dynamic authorship columns
+- `read_corrections_csv()`: Parses CSV corrections into `dict[resource_id, LegalMetadata]`
+- `write_problems_to_csv()`: Writes validation errors to CSV with helpful FIXME markers
+- `is_fixme_value()`: Checks if value starts with "FIXME:" prefix
+
+**CSV format:**
+
+- Fixed columns: `file`, `resource_id`, `license`, `copyright`
+- Dynamic columns: `authorship_1`, `authorship_2`, ... (as many as needed)
+- Sorted by resource_id for easy navigation
+
+**Error prevention:**
+
+- Refuses to overwrite existing CSV unless `--fixed_errors` flag provided
+- Helpful error message suggests correct flag usage
+
+### [xml_operations.py](xml_operations.py)
+
+XML manipulation and metadata application:
+
+- `collect_metadata()`: Pure function that collects metadata from CSV, XML, or defaults (read-only)
+- `apply_metadata_to_resource()`: Applies metadata as attributes and removes old text properties (mutations)
+- `_resolve_metadata_values()`: Implements priority system (CSV > XML > defaults)
+- `_extract_license_from_xml()`: Extracts license and validates with `xmllib.find_license_in_string()`
+- `_extract_copyright_from_xml()`: Extracts copyright, detects duplicates
+- `_extract_authorships_from_xml()`: Collects all authorship values
+- `_apply_metadata_to_element()`: Applies metadata as attributes on media element
+- `_remove_text_properties()`: Removes old text-prop elements
+- `add_authorship_definitions_to_xml()`: Creates `<authorship>` definitions at root level
+- `write_final_xml()`: Writes updated XML with statistics
+
+**Authorship deduplication:**
+
+- Multiple resources can share same authorship (e.g., "Jane Doe, Alice Jenkins")
+- `auth_text_to_id` dictionary tracks unique authorships and assigns sequential IDs
+- Authorship definitions added to root as `<authorship id="authorship_0">` elements
+- Media elements reference via `authorship-id="authorship_0"` attribute
+
+**Multiple value detection:**
+
+- If multiple copyright values found: returns `"FIXME: Multiple copyrights found. Choose one: ..."`
+- If multiple license values found: returns `"FIXME: Multiple licenses found. Choose one: ..."`
+- This triggers CSV export for manual resolution
+
+## Architectural Improvements
+
+### Separation of Collection and Application
+
+The codebase follows a clear pattern separating read operations from write operations:
+
+**Collection Phase (`collect_metadata()`):**
+
+- Pure function with no side effects
+- Reads from CSV, XML properties, and defaults
+- Returns `LegalMetadata` object
+- Can be called safely without modifying the XML tree
+- Executes exactly once per resource
+
+**Application Phase (`apply_metadata_to_resource()`):**
+
+- Mutates the XML tree in-place
+- Applies metadata as attributes on media elements
+- Removes old text properties
+- Manages authorship deduplication dictionary
+- Only called for valid resources (no problems)
+
+**Benefits:**
+
+- **Performance**: Eliminates duplicate XPath queries (~50% reduction for valid resources)
+- **Clarity**: Clear contract - collection is read-only, application mutates
+- **Safety**: Impossible to accidentally mutate during problem detection
+- **Testability**: Each phase can be tested independently
+
+## Key Algorithms
+
+### Authorship Deduplication
+
+Problem: Multiple resources may share the same authorship (e.g., "Jane Doe, Alice Jenkins").
+
+Solution:
+
+1. Maintain `auth_text_to_id: dict[str, int]` throughout tree traversal
+2. When applying authorship to media element:
+   - Join all authorship values with ", " separator
+   - Check if this text already has an ID
+   - If not, assign next sequential ID
+   - Add `authorship-id="authorship_{id}"` attribute to media element
+3. After tree traversal, create `<authorship>` definitions at root level
+4. Each definition contains `<author>` child elements
+
+Result: Shared authorships stored once at root, referenced by multiple resources.
+
+### FIXME Value Detection
+
+Problem: Need to distinguish between missing values and values that need manual correction.
+
+Solution:
+
+- Use "FIXME:" prefix for values that need correction
+- `is_fixme_value()` checks for this prefix
+- During extraction:
+    - Multiple values: `"FIXME: Multiple X found. Choose one: A, B"`
+    - Invalid license: `"FIXME: Invalid license: courtesy of museum"`
+- During validation: FIXME values treated same as missing values
+- During CSV reading: FIXME values converted back to None
+
+Result: Clear distinction between "missing" and "needs correction" in CSV workflow.
+
+### License Parsing
+
+Problem: License strings come in many formats (`CC BY`, `CC-BY-4.0`, `http://rdfh.ch/licenses/cc-by-4.0`).
+
+Solution:
+
+- Use `xmllib.find_license_in_string()` to parse license text into standardized License enum
+- If parsing fails, return `"FIXME: Invalid license: {text}"`
+- In defaults, parse license string during `__init__()` to fail fast if invalid
+
+Result: All licenses normalized to standard IRIs.
+
+## Error Handling Strategy
+
+### Iterative CSV Correction Workflow
+
+1. **First run**: User provides property names and defaults
+   - Command extracts metadata using priority system
+   - Validates all values
+   - If errors found: writes CSV with FIXME markers
+   - No XML output created
+
+2. **Manual correction**: User fixes CSV
+   - Replaces FIXME markers with correct values
+   - Can add missing values
+   - Can choose between multiple values
+   - **Important**: Can modify ANY column (not just FIXME ones) - see "CSV Override Behavior" below
+
+3. **Second run**: User provides `--fixed_errors` flag
+   - Command loads corrections from CSV
+   - CSV corrections take highest priority
+   - Validates again
+   - If still errors: writes new CSV
+   - If no errors: writes updated XML
+
+4. **Repeat** until all errors resolved
+
+### Validation Rules
+
+A resource has problems if:
+
+- License is None or FIXME value
+- Copyright is None or FIXME value
+- Authorships is empty list or contains FIXME value
+
+Important: A resource must have ALL THREE components valid to avoid CSV export.
+
+### CSV Override Behavior
+
+**Critical implementation detail:**
+
+When `--fixed_errors` is used, ALL non-None CSV values override XML properties and defaults for resources in that CSV.
+This applies to every column, not just FIXME markers.
+
+**Priority resolution in `_resolve_metadata_values()`:**
+
+1. If CSV has non-None value: use it (skip XML extraction and defaults)
+2. Else if XML has value: use it (skip defaults)
+3. Else if defaults provided: use them
+4. Else: None (triggers validation error)
+
+**Note:** FIXME-prefixed values are converted to None during CSV reading, allowing fallback to XML/defaults.
+
+### Error Messages
+
+User-facing error messages:
+
+- Missing property: Caught early in `_validate_flags()` with clear message
+- Existing CSV: Suggests using `--fixed_errors` flag
+- Invalid license default: Raised during `LegalMetadataDefaults.__init__()`
+- FIXME markers in CSV: Provide context about what needs fixing
+
+## Testing Considerations
+
+### Unit Testing
+
+Test each function in isolation:
+
+- **Extraction functions**: Test with various XML structures (missing, single, multiple values)
+- **Priority resolution**: Test all combinations of CSV/XML/defaults
+- **FIXME detection**: Test all FIXME marker formats
+- **CSV operations**: Test round-trip (write problems → read corrections)
+- **Authorship deduplication**: Test ID assignment and reuse
+
+### Integration Testing
+
+Test file I/O and cross-module interactions:
+
+- **Full workflow**: Input XML → CSV → corrected CSV → output XML
+- **Property validation**: Missing properties raise correct error
+- **Default values**: Applied when XML values missing
+- **CSV overwrite protection**: Existing CSV prevents accidental overwrite
+
+### E2E Testing
+
+Test realistic scenarios:
+
+- **Simple case**: All metadata present and valid
+- **Missing values**: Some resources missing authorship/copyright/license
+- **Invalid licenses**: Test "courtesy" and other invalid formats
+- **Multiple values**: Resources with multiple copyright/license values
+- **Shared authorships**: Multiple resources with same authorship
+- **Iterative correction**: Multiple runs with CSV corrections
+
+### Edge Cases
+
+- Empty authorship text values (should be filtered out)
+- Whitespace-only values (should be treated as empty)
+- Resources without media elements (should be skipped)
+- Both bitstream and iiif-uri present (first one used)
+- Unicode in authorship names
+- Very long authorship lists
+
+## Common Pitfalls
+
+1. **Forgetting `--fixed_errors` flag**: Command will refuse to overwrite existing CSV
+2. **Not providing any property flags**: Caught early with validation error
+3. **Property names with wrong namespace**: Caught early when no matches found
+4. **Leaving FIXME markers in CSV**: Treated as missing values, triggers new CSV
+5. **Invalid license default**: Fails during defaults initialization, not during execution
+
+## Performance Considerations
+
+- **Single-pass tree traversal**: All resources processed in one iteration
+- **In-memory CSV**: Entire corrections CSV loaded into memory as dictionary
+- **lxml XPath**: Efficient XPath queries for property extraction
+- **Authorship deduplication**: O(1) lookup via dictionary
+- **CSV sorting**: Results sorted by resource_id for easier navigation
+
+For typical XML files (thousands of resources), performance should be near-instantaneous.
+
+## Dependencies
+
+- **lxml**: XML parsing and manipulation
+- **pandas**: CSV I/O with proper column handling
+- **xmllib**: License parsing utilities (`find_license_in_string()`)
+- **dsp_tools.utils.xml_parsing**: XML parsing/validation utilities
+
+## Future Improvements
+
+Possible enhancements:
+
+- Batch processing: Process multiple XML files at once
+- Auto-detection: Try to guess property names from XML structure
+- Validation preview: Show what would be changed without modifying XML
+- Undo functionality: Revert XML back to text properties
+- License suggestions: Use fuzzy matching for invalid licenses

dsp_tools/commands/update_legal/core.py

@@ -0,0 +1,182 @@
+from pathlib import Path
+
+from lxml import etree
+
+from dsp_tools.commands.update_legal.csv_operations import is_fixme_value
+from dsp_tools.commands.update_legal.csv_operations import read_corrections_csv
+from dsp_tools.commands.update_legal.csv_operations import write_problems_to_csv
+from dsp_tools.commands.update_legal.models import Authorships
+from dsp_tools.commands.update_legal.models import LegalMetadata
+from dsp_tools.commands.update_legal.models import LegalMetadataDefaults
+from dsp_tools.commands.update_legal.models import LegalProperties
+from dsp_tools.commands.update_legal.models import Problem
+from dsp_tools.commands.update_legal.models import UpdateCounter
+from dsp_tools.commands.update_legal.xml_operations import add_authorship_definitions_to_xml
+from dsp_tools.commands.update_legal.xml_operations import apply_metadata_to_resource
+from dsp_tools.commands.update_legal.xml_operations import collect_metadata
+from dsp_tools.commands.update_legal.xml_operations import write_updated_xml
+from dsp_tools.error.exceptions import InputError
+from dsp_tools.utils.xml_parsing.parse_clean_validate_xml import parse_xml_file
+from dsp_tools.utils.xml_parsing.parse_clean_validate_xml import transform_into_localnames
+
+
+def update_legal_metadata(
+    input_file: Path,
+    properties: LegalProperties,
+    defaults: LegalMetadataDefaults,
+    fixed_errors_file: Path | None = None,
+    treat_invalid_licenses_as_unknown: bool = False,
+) -> bool:
+    """
+    Update legal metadata in an XML file, converting text properties to bitstream attributes.
+
+    Args:
+        input_file: Path to the input XML file
+        properties: Configuration for property names to extract from XML
+        defaults: Default values to use when metadata is missing
+        fixed_errors_file: Path to CSV file with corrected values
+        treat_invalid_licenses_as_unknown: If True, invalid licenses are replaced with 'unknown'
+
+    Returns:
+        True if all legal metadata could be updated, False if CSV error file was created
+    """
+    csv_corrections = None
+    if fixed_errors_file:
+        csv_corrections = read_corrections_csv(fixed_errors_file)
+
+    root = parse_xml_file(input_file)
+    root = transform_into_localnames(root)
+    _validate_flags(root, properties)
+
+    root_updated, counter, problems = _update_xml_tree(
+        root=root,
+        properties=properties,
+        defaults=defaults,
+        csv_corrections=csv_corrections,
+        treat_invalid_licenses_as_unknown=treat_invalid_licenses_as_unknown,
+    )
+
+    if len(problems) == 0:
+        # Success - write fully updated XML with _updated suffix
+        write_updated_xml(input_file, root_updated, counter, partial=False)
+        return True
+    else:
+        # Partial update - write both CSV and partial XML
+        write_problems_to_csv(input_file, problems)
+        write_updated_xml(input_file, root_updated, counter, partial=True)
+        return False
+
+
+def _validate_flags(root: etree._Element, properties: LegalProperties) -> None:
+    if not properties.has_any_property():
+        raise InputError("At least one property (authorship_prop, copyright_prop, license_prop) must be provided")
+    text_prop_names = {x for x in root.xpath("//text-prop/@name")}
+    inexisting_props = [
+        x
+        for x in [properties.authorship_prop, properties.copyright_prop, properties.license_prop]
+        if x and x not in text_prop_names
+    ]
+    if inexisting_props:
+        raise InputError(f"The following properties do not exist in the XML file: {', '.join(inexisting_props)}")
+
+
+def _update_xml_tree(
+    root: etree._Element,
+    properties: LegalProperties,
+    defaults: LegalMetadataDefaults,
+    csv_corrections: dict[str, LegalMetadata] | None = None,
+    treat_invalid_licenses_as_unknown: bool = False,
+) -> tuple[etree._Element, UpdateCounter, list[Problem]]:
+    """
+    Update the XML tree with legal metadata, applying corrections and defaults.
+    Resources without problems are fully updated (metadata applied, text properties removed).
+    Resources with problems are left unchanged in the XML, but problems are collected for CSV output.
+
+    Args:
+        root: The XML root element
+        properties: Configuration for property names to extract from XML
+        defaults: Default values to use when metadata is missing
+        csv_corrections: Dictionary of corrections from CSV (or None)
+        treat_invalid_licenses_as_unknown: If True, invalid licenses are replaced with 'unknown'
+
+    Returns:
+        Tuple of (updated root element, counter of updated resources, list of problems)
+    """
+    auth_text_to_id: dict[Authorships, int] = {}
+    problems: list[Problem] = []
+    counter = UpdateCounter()
+
+    for res in root.iterchildren(tag="resource"):
+        if not (media_tag_candidates := res.xpath("bitstream|iiif-uri")):
+            continue
+
+        res_id = res.attrib["id"]
+        media_elem = media_tag_candidates[0]
+        csv_metadata = csv_corrections.get(res_id) if csv_corrections else None
+
+        metadata = collect_metadata(
+            res=res,
+            properties=properties,
+            defaults=defaults,
+            counter=counter,
+            csv_metadata=csv_metadata,
+            treat_invalid_licenses_as_unknown=treat_invalid_licenses_as_unknown,
+        )
+
+        if _has_problems(metadata):
+            authorships = sorted(x for x in metadata.authorships.elems if x) or ["FIXME: Authorship missing"]
+            problem = Problem(
+                file_or_iiif_uri=str(media_elem.text).strip(),
+                res_id=res_id,
+                license=metadata.license or "FIXME: License missing",
+                copyright=metadata.copyright or "FIXME: Copyright missing",
+                authorships=authorships,
+            )
+            problems.append(problem)
+        elif metadata.any():
+            apply_metadata_to_resource(
+                res=res,
+                media_elem=media_elem,
+                metadata=metadata,
+                properties=properties,
+                auth_text_to_id=auth_text_to_id,
+            )
+            _update_counter(counter, metadata)
+
+    if auth_text_to_id:
+        add_authorship_definitions_to_xml(root, auth_text_to_id)
+
+    return root, counter, problems
+
+
+def _has_problems(metadata: LegalMetadata) -> bool:
+    """
+    Check if metadata has any missing or invalid fields that should be reported in CSV.
+
+    Args:
+        metadata: The legal metadata to check
+
+    Returns:
+        True if there are problems, False otherwise
+    """
+    has_license_problem = metadata.license is None or is_fixme_value(metadata.license)
+    has_copyright_problem = metadata.copyright is None or is_fixme_value(metadata.copyright)
+
+    if not any(x for x in metadata.authorships.elems if x):
+        has_authorship_problem = True
+    elif any(is_fixme_value(x) for x in metadata.authorships.elems):
+        has_authorship_problem = True
+    else:
+        has_authorship_problem = False
+
+    return has_license_problem or has_copyright_problem or has_authorship_problem
+
+
+def _update_counter(counter: UpdateCounter, metadata: LegalMetadata) -> None:
+    counter.resources_updated += 1
+    if metadata.license:
+        counter.licenses_set += 1
+    if metadata.copyright:
+        counter.copyrights_set += 1
+    if metadata.authorships:
+        counter.authorships_set += 1

dsp_tools/commands/update_legal/csv_operations.py

@@ -0,0 +1,135 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+import pandas as pd
+import regex
+
+from dsp_tools.commands.update_legal.models import Authorships
+from dsp_tools.commands.update_legal.models import LegalMetadata
+from dsp_tools.commands.update_legal.models import Problem
+from dsp_tools.error.exceptions import InputError
+
+
+@dataclass(frozen=True)
+class ProblemAggregator:
+    """Aggregates multiple problems and provides DataFrame export for CSV generation."""
+
+    problems: list[Problem]
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Convert problems to DataFrame for CSV export."""
+        problem_dicts = []
+        max_authorships = max((len(p.authorships) for p in self.problems), default=0)
+
+        for problem in self.problems:
+            row_dict = {
+                "file": problem.file_or_iiif_uri,
+                "resource_id": problem.res_id,
+                "license": problem.license,
+                "copyright": problem.copyright,
+            }
+
+            # Add authorship columns (authorship_1, authorship_2, etc.)
+            for i in range(1, max_authorships + 1):
+                auth_idx = i - 1
+                authorship_value = problem.authorships[auth_idx] if auth_idx < len(problem.authorships) else ""
+                row_dict[f"authorship_{i}"] = authorship_value
+
+            problem_dicts.append(row_dict)
+
+        df = pd.DataFrame.from_records(problem_dicts)
+        df = df.sort_values(by=["resource_id"])
+
+        # Ensure column order matches documentation
+        base_cols = ["file", "resource_id", "license", "copyright"]
+        auth_cols = [f"authorship_{i}" for i in range(1, max_authorships + 1)]
+        df = df[base_cols + auth_cols]
+
+        return df
+
+    def save_to_csv(self, input_file: Path) -> Path:
+        """
+        Save problems to CSV file.
+
+        Args:
+            input_file: The input XML file path, used to determine the output path
+
+        Returns:
+            Path to the created CSV file
+        """
+        output_path = input_file.parent / f"{input_file.stem}_legal_errors.csv"
+        i = 1
+        while output_path.exists():
+            stem_without_suffix = regex.sub(r"_\d+$", "", output_path.stem)
+            output_path = output_path.with_name(f"{stem_without_suffix}_{i}{output_path.suffix}")
+            i += 1
+        df = self.to_dataframe()
+        df.to_csv(output_path, index=False, mode="x")
+        return output_path
+
+
+def read_corrections_csv(csv_path: Path) -> dict[str, LegalMetadata]:
+    """Read corrected legal metadata from a CSV file, and return a mapping from resource ID to LegalMetadata."""
+    df = pd.read_csv(csv_path)
+
+    # Validate required columns
+    required_cols = {"file", "resource_id", "license", "copyright"}
+    if not required_cols.issubset(df.columns):
+        missing = required_cols - set(df.columns)
+        msg = f"CSV file is missing required columns: {missing}"
+        raise InputError(msg)
+
+    corrections = {}
+    for _, row in df.iterrows():
+        res_id = str(row["resource_id"])
+
+        license_val = str(row["license"]) if pd.notna(row["license"]) else None
+        copyright_val = str(row["copyright"]) if pd.notna(row["copyright"]) else None
+
+        # Skip rows that still have FIXME markers (not yet corrected)
+        if is_fixme_value(license_val):
+            license_val = None
+        if is_fixme_value(copyright_val):
+            copyright_val = None
+
+        # Collect all authorship columns (authorship_1, authorship_2, etc.)
+        authorships = _collect_authorships_from_row(row, df.columns)
+
+        corrections[res_id] = LegalMetadata(
+            license=license_val,
+            copyright=copyright_val,
+            authorships=authorships,
+        )
+
+    return corrections
+
+
+def _collect_authorships_from_row(row: pd.Series, df_columns: pd.Index) -> Authorships:
+    """
+    Collect all authorship values from a CSV row.
+
+    Returns:
+        List of authorship values (excluding FIXME markers)
+    """
+    authorships = []
+    i = 1
+    while f"authorship_{i}" in df_columns:
+        auth_val = row[f"authorship_{i}"]
+        if pd.notna(auth_val):
+            auth_str = str(auth_val)
+            if not is_fixme_value(auth_str):
+                authorships.append(auth_str)
+        i += 1
+    return Authorships.from_iterable(authorships)
+
+
+def is_fixme_value(value: str | None) -> bool:
+    """Check if a value is a FIXME marker"""
+    return value is not None and value.startswith("FIXME:")
+
+
+def write_problems_to_csv(input_file: Path, problems: list[Problem]) -> None:
+    aggregator = ProblemAggregator(problems)
+    csv_path = aggregator.save_to_csv(input_file)
+    print(f"\n⚠️  Legal metadata contains errors. Please fix them in the CSV file:\n    {csv_path}")
+    print(f"\nAfter fixing the errors, rerun the command with:\n    --fixed_errors={csv_path}")