api: deprecate UserItem.CSVImport.validate_file_for_import in favor of a safer replacement

[jacalata]

validate_file_for_import is public API and its current shape invited the class of bug that #1829 patched. Proposing an additive replacement plus a deprecation on the existing method - no breaking change now, removal on the next major version.

Current signature:

def validate_file_for_import(csv_file, logger) -> tuple[int, list[str]]

Two problems with the shape:

• Logger as a parameter made security: _validate_import_line_or_throw logs credential fields at DEBUG level #1829 possible in the first place - a caller-supplied verbose logger could receive credential material. Prefer a module logger with documented levels.
• Returning raw invalid lines forces callers to re-parse to give a useful error, and hands credential-bearing rows back to the caller (mitigated by _redact_password_column but the shape invites the bug).

Proposed replacement:

@dataclass(frozen=True)
class CsvImportError:
    row: int
    column: ColumnType | None
    reason: str  # never the raw field value

@dataclass
class CsvImportResult:
    valid_count: int
    errors: list[CsvImportError]

@staticmethod
def validate_import_file(csv_file) -> CsvImportResult: ...

Migration:

1. Add validate_import_file returning the structured result.
2. Reimplement validate_file_for_import as a thin wrapper that emits DeprecationWarning and adapts back to the old return shape.
3. Update samples/ to use the new method.
4. Remove the deprecated method on the next major version bump.

🤖 Generated with Claude Code