diffmonkey 1.0.0__py3-none-any.whl

diffmonkey/compare.py

@@ -0,0 +1,253 @@
+"""The ``compare()`` entry point: end-to-end structural diff of two datasets.
+
+This module exists to orchestrate the pipeline — column mapping, key indexing
+(:mod:`diffmonkey.matching`), per-column type-aware comparison
+(:mod:`diffmonkey.comparators`) and bucketing into a :class:`DiffResult`
+(:mod:`diffmonkey.models`). It holds no comparison logic of its own; it decides
+*what* to compare and *how to categorise* the outcome.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Sequence
+
+from .comparators import CompareSettings, make_comparator
+from .matching import index_rows, make_key, validate_policies
+from .models import DiffResult, DiffSummary, FieldChange, RowDiff
+
+Row = Mapping[str, Any]
+
+
+def _coerce_key(key: str | Sequence[str]) -> tuple[str, ...]:
+    if isinstance(key, str):
+        return (key,)
+    key_t = tuple(key)
+    if not key_t:
+        raise ValueError("`key` must name at least one column")
+    if not all(isinstance(k, str) for k in key_t):
+        raise TypeError("`key` columns must be strings")
+    return key_t
+
+
+def _apply_column_map(
+    rows: Iterable[Row], column_map: Mapping[str, str] | None
+) -> list[dict[str, Any]]:
+    """Return rows as dicts, renaming old->new column names where mapped.
+
+    A mapping ``{"old_name": "new_name"}`` is applied to *old* rows so both
+    sides share the new namespace. If both ``old_name`` and ``new_name`` are
+    present in a row, the explicitly-new value wins (the rename target is not
+    clobbered).
+    """
+    if not column_map:
+        return [dict(r) for r in rows]
+    out: list[dict[str, Any]] = []
+    for r in rows:
+        rd = dict(r)
+        for old_name, new_name in column_map.items():
+            if old_name in rd:
+                value = rd.pop(old_name)
+                rd.setdefault(new_name, value)
+        out.append(rd)
+    return out
+
+
+def _resolve_columns(
+    old_rows: list[dict[str, Any]],
+    new_rows: list[dict[str, Any]],
+    key_columns: tuple[str, ...],
+    columns: Sequence[str] | None,
+    ignore: Sequence[str] | None,
+) -> tuple[str, ...]:
+    """Decide which columns to compare.
+
+    Default is the union of all columns seen on either side, in first-seen
+    order, minus key columns and minus the ignore list. An explicit ``columns``
+    list overrides the union (still minus key and ignore).
+    """
+    ignore_set = set(ignore or ())
+    key_set = set(key_columns)
+    if columns is not None:
+        ordered = list(columns)
+    else:
+        ordered = []
+        seen: set[str] = set()
+        for row in (*old_rows, *new_rows):
+            for col in row:
+                if col not in seen:
+                    seen.add(col)
+                    ordered.append(col)
+    return tuple(c for c in ordered if c not in key_set and c not in ignore_set)
+
+
+def compare(
+    old: Iterable[Row],
+    new: Iterable[Row],
+    *,
+    key: str | Sequence[str],
+    columns: Sequence[str] | None = None,
+    ignore: Sequence[str] | None = None,
+    column_map: Mapping[str, str] | None = None,
+    rel_tol: float = 1e-9,
+    abs_tol: float = 0.0,
+    normalize_whitespace: bool = True,
+    null_equivalent: bool = True,
+    type_aware: bool = True,
+    date_aware: bool = True,
+    locale: str | None = None,
+    null_values: Iterable[str] | None = None,
+    include_unchanged: bool = False,
+    on_duplicate: str = "warn",
+    on_missing_key: str = "warn",
+) -> DiffResult:
+    """Compare two tabular datasets and categorise the differences.
+
+    Args:
+        old: The baseline rows (list of mappings / dicts).
+        new: The current rows to compare against the baseline.
+        key: Identity column name, or a sequence of names for a composite key.
+            Names refer to the *new* namespace (i.e. after ``column_map``).
+        columns: Restrict comparison to these columns. Default: every non-key
+            column seen on either side.
+        ignore: Columns to exclude from comparison (timestamps, audit fields,
+            row numbers). Applied after ``columns``.
+        column_map: ``{old_name: new_name}`` renames applied to ``old`` rows so
+            renamed columns are not reported as removed+added.
+        rel_tol: Relative floating-point tolerance for numeric columns
+            (``math.isclose``). Default ``1e-9``.
+        abs_tol: Absolute floating-point tolerance for numeric columns. Default
+            ``0.0`` — set this to compare values near zero.
+        normalize_whitespace: Collapse/strip whitespace and drop invisible
+            characters before comparing strings (via ``cleanmonkey``). Default
+            True.
+        null_equivalent: Treat all null spellings (``None``, ``""``,
+            whitespace-only, ``"na"``, …) as one value, so two different nulls
+            are equal and null↔value is a change. Default True.
+        type_aware: Infer each column's type and compare accordingly (numbers
+            by value, dates by calendar date, booleans by truth). When False,
+            every column is compared as a normalised string. Default True.
+        date_aware: Within type-aware mode, compare date columns by parsed date
+            rather than as strings. Default True.
+        locale: Number/date locale hint (``"us"``/``"eu"``). Default None
+            (auto-detect).
+        null_values: Override the null vocabulary (an iterable of spellings).
+            Default None (use typemonkey's default set).
+        include_unchanged: Populate :attr:`DiffResult.unchanged`. Default False
+            (unchanged rows are counted but not retained).
+        on_duplicate: Duplicate-key policy: ``"warn"`` (keep first + warn),
+            ``"first"``, ``"last"``, or ``"error"``. Any other value raises
+            :class:`ValueError`.
+        on_missing_key: Missing-key policy: ``"warn"`` (keep + warn), ``"skip"``,
+            or ``"error"``. Any other value raises :class:`ValueError`.
+
+    Returns:
+        A :class:`DiffResult` with added/removed/changed/unchanged buckets and a
+        :class:`DiffSummary`.
+
+    Raises:
+        ValueError: if ``key`` is empty, or ``on_duplicate`` / ``on_missing_key``
+            is not one of its documented values.
+        TypeError: if a ``key`` column name is not a string.
+    """
+    key_columns = _coerce_key(key)
+    # Validate configuration before consuming `old`/`new`, which may be
+    # expensive, side-effecting, or non-terminating generators: a misspelled
+    # policy must raise ValueError without touching the inputs.
+    validate_policies(on_duplicate, on_missing_key)
+    null_set = frozenset(null_values) if null_values is not None else None
+    settings = CompareSettings(
+        rel_tol=rel_tol,
+        abs_tol=abs_tol,
+        normalize_whitespace=normalize_whitespace,
+        null_equivalent=null_equivalent,
+        type_aware=type_aware,
+        date_aware=date_aware,
+        locale=locale,
+        null_values=null_set,
+    )
+
+    old_rows = _apply_column_map(old, column_map)
+    new_rows = [dict(r) for r in new]
+
+    compared = _resolve_columns(old_rows, new_rows, key_columns, columns, ignore)
+
+    warnings: list[str] = []
+    old_index, total_old, dup_old = index_rows(
+        old_rows,
+        key_columns,
+        side="old",
+        on_duplicate=on_duplicate,
+        on_missing_key=on_missing_key,
+        warnings=warnings,
+    )
+    new_index, total_new, dup_new = index_rows(
+        new_rows,
+        key_columns,
+        side="new",
+        on_duplicate=on_duplicate,
+        on_missing_key=on_missing_key,
+        warnings=warnings,
+    )
+
+    # Build one comparator per compared column over both sides' values.
+    comparators = {}
+    for col in compared:
+        old_vals = [r.get(col) for r in old_index.values()]
+        new_vals = [r.get(col) for r in new_index.values()]
+        comparators[col] = make_comparator(col, old_vals, new_vals, settings)
+
+    added: list[RowDiff] = []
+    removed: list[RowDiff] = []
+    changed: list[RowDiff] = []
+    unchanged: list[RowDiff] = []
+
+    # Matched + added, in new-dataset order.
+    for k, new_row in new_index.items():
+        old_row = old_index.get(k)
+        if old_row is None:
+            added.append(RowDiff(key=k, new=new_row))
+            continue
+        field_changes: list[FieldChange] = []
+        for col in compared:
+            ov = old_row.get(col)
+            nv = new_row.get(col)
+            if not comparators[col].equal(ov, nv):
+                field_changes.append(FieldChange(column=col, old=ov, new=nv))
+        if field_changes:
+            changed.append(
+                RowDiff(key=k, old=old_row, new=new_row, changes=tuple(field_changes))
+            )
+        elif include_unchanged:
+            unchanged.append(RowDiff(key=k, old=old_row, new=new_row))
+
+    # Removed, in old-dataset order.
+    for k, old_row in old_index.items():
+        if k not in new_index:
+            removed.append(RowDiff(key=k, old=old_row))
+
+    matched = sum(1 for k in new_index if k in old_index)
+    unchanged_count = matched - len(changed)
+
+    summary = DiffSummary(
+        total_old=total_old,
+        total_new=total_new,
+        matched=matched,
+        added=len(added),
+        removed=len(removed),
+        changed=len(changed),
+        unchanged=unchanged_count,
+        key_columns=key_columns,
+        compared_columns=compared,
+        duplicate_keys=dup_old + dup_new,
+    )
+
+    return DiffResult(
+        added=added,
+        removed=removed,
+        changed=changed,
+        unchanged=unchanged,
+        summary=summary,
+        key_columns=key_columns,
+        compared_columns=compared,
+        warnings=warnings,
+    )

diffmonkey/formatters/__init__.py

@@ -0,0 +1,13 @@
+"""Report renderers for a :class:`diffmonkey.models.DiffResult`.
+
+Each submodule exports a single ``render(result, ...) -> str`` function. They
+live behind :class:`DiffResult`'s ``to_markdown`` / ``to_html`` / ``to_csv``
+methods so callers rarely import them directly, but they are importable for
+golden-file testing and custom pipelines.
+"""
+
+from __future__ import annotations
+
+from . import csv_out, html, markdown
+
+__all__ = ["markdown", "html", "csv_out"]

diffmonkey/formatters/csv_out.py

@@ -0,0 +1,55 @@
+"""CSV of changes.
+
+This module exists to produce a flat, spreadsheet-friendly record of *every*
+field-level change plus added/removed rows — one CSV row per change — so an
+analyst can pivot/filter the diff. The schema is fixed:
+
+``change_type, key, column, old, new``
+
+* ``change_type`` is ``changed`` / ``added`` / ``removed``.
+* ``key`` is the row key rendered as ``col=value`` (joined by ``; `` for
+  composite keys).
+* For ``added``/``removed`` rows there is no per-field breakdown, so one row is
+  emitted with empty ``column``/``old``/``new`` (added) or ``column``/``new``
+  empty (removed) — the presence of the row is the change.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any
+
+from ..models import DiffResult, RowDiff
+
+HEADER = ["change_type", "key", "column", "old", "new"]
+
+
+def _key_str(rd: RowDiff, key_columns: tuple[str, ...]) -> str:
+    return "; ".join(
+        f"{col}={'' if val is None else val}" for col, val in zip(key_columns, rd.key)
+    )
+
+
+def _cell(value: Any) -> str:
+    """CSV cell text: ``None`` becomes empty string (csv has no null)."""
+    return "" if value is None else str(value)
+
+
+def render(result: DiffResult) -> str:
+    """Render ``result`` as CSV text (``\\n`` line endings, UTF-8 ready)."""
+    buf = io.StringIO()
+    writer = csv.writer(buf, lineterminator="\n")
+    writer.writerow(HEADER)
+    kc = result.key_columns
+
+    for rd in result.changed:
+        key = _key_str(rd, kc)
+        for ch in rd.changes:
+            writer.writerow(["changed", key, ch.column, _cell(ch.old), _cell(ch.new)])
+    for rd in result.added:
+        writer.writerow(["added", _key_str(rd, kc), "", "", ""])
+    for rd in result.removed:
+        writer.writerow(["removed", _key_str(rd, kc), "", "", ""])
+
+    return buf.getvalue()

diffmonkey/formatters/html.py

@@ -0,0 +1,93 @@
+"""Standalone HTML diff report.
+
+This module exists to produce a single self-contained HTML document (inline
+CSS, no external assets) suitable for emailing or attaching to a build. All
+dynamic values are HTML-escaped via the stdlib ``html.escape`` so cell content
+containing ``<``/``&``/quotes cannot break the markup or inject script.
+"""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+from ..models import DiffResult, RowDiff
+
+_STYLE = """\
+body{font-family:-apple-system,Segoe UI,Roboto,sans-serif;margin:2rem;color:#1a1a1a}
+h1{font-size:1.4rem}h2{font-size:1.1rem;border-bottom:1px solid #ddd;padding-bottom:.2rem}
+.summary{font-weight:600;margin:.5rem 0 1rem}
+table{border-collapse:collapse;width:100%;margin:.5rem 0}
+th,td{border:1px solid #ddd;padding:.3rem .5rem;text-align:left;vertical-align:top}
+th{background:#f4f4f4}
+.old{background:#ffecec}.new{background:#eaffea}
+.null{color:#999;font-style:italic}
+.meta{color:#555;font-size:.9rem}
+"""
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return '<span class="null">(null)</span>'
+    return escape(str(value))
+
+
+def _key_label(rd: RowDiff, key_columns: tuple[str, ...]) -> str:
+    return escape(
+        ", ".join(
+            f"{col}={'' if val is None else val}"
+            for col, val in zip(key_columns, rd.key)
+        )
+    )
+
+
+def render(result: DiffResult, *, title: str = "diffmonkey report") -> str:
+    """Render ``result`` as a complete HTML document string."""
+    s = result.summary
+    parts: list[str] = [
+        "<!DOCTYPE html>",
+        '<html lang="en"><head><meta charset="utf-8">',
+        f"<title>{escape(title)}</title>",
+        f"<style>{_STYLE}</style></head><body>",
+        f"<h1>{escape(title)}</h1>",
+        f'<p class="summary">{escape(s.one_line())}</p>',
+        '<p class="meta">Key: '
+        + escape(", ".join(result.key_columns))
+        + " &middot; Compared: "
+        + escape(", ".join(result.compared_columns) or "(none)")
+        + f" &middot; {s.total_old} old &rarr; {s.total_new} new</p>",
+    ]
+
+    parts.append(f"<h2>Changed ({s.changed})</h2>")
+    if result.changed:
+        parts.append("<table><tr><th>Key</th><th>Column</th><th>Old</th><th>New</th></tr>")
+        for rd in result.changed:
+            klabel = _key_label(rd, result.key_columns)
+            for i, ch in enumerate(rd.changes):
+                key_cell = klabel if i == 0 else ""
+                parts.append(
+                    f"<tr><td>{key_cell}</td><td>{escape(ch.column)}</td>"
+                    f'<td class="old">{_cell(ch.old)}</td>'
+                    f'<td class="new">{_cell(ch.new)}</td></tr>'
+                )
+        parts.append("</table>")
+
+    parts.append(f"<h2>Added ({s.added})</h2>")
+    if result.added:
+        parts.append("<ul>")
+        parts.extend(f"<li>{_key_label(rd, result.key_columns)}</li>" for rd in result.added)
+        parts.append("</ul>")
+
+    parts.append(f"<h2>Removed ({s.removed})</h2>")
+    if result.removed:
+        parts.append("<ul>")
+        parts.extend(f"<li>{_key_label(rd, result.key_columns)}</li>" for rd in result.removed)
+        parts.append("</ul>")
+
+    if result.warnings:
+        parts.append(f"<h2>Warnings ({len(result.warnings)})</h2><ul>")
+        parts.extend(f"<li>{escape(w)}</li>" for w in result.warnings)
+        parts.append("</ul>")
+
+    parts.append("</body></html>")
+    return "\n".join(parts) + "\n"

diffmonkey/formatters/markdown.py

@@ -0,0 +1,94 @@
+"""Markdown diff report.
+
+This module exists to turn a :class:`DiffResult` into a human-skimmable report
+for PRs, emails and chat. The layout is deliberately stable (fixed section
+order, fixed headline wording) so it can be pinned with golden-file tests and
+downstream scripts can rely on its shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models import DiffResult, RowDiff
+
+
+def _fmt(value: Any) -> str:
+    """Render a cell value for display; ``None`` becomes ``(null)``."""
+    if value is None:
+        return "(null)"
+    return str(value)
+
+
+def _key_label(rd: RowDiff, key_columns: tuple[str, ...]) -> str:
+    parts = [f"{col}={_fmt(val)}" for col, val in zip(key_columns, rd.key)]
+    return ", ".join(parts)
+
+
+def _limit(rows: list[RowDiff], max_rows: int | None) -> tuple[list[RowDiff], int]:
+    """Return ``(shown_rows, hidden_count)`` honouring ``max_rows``."""
+    if max_rows is None or len(rows) <= max_rows:
+        return rows, 0
+    return rows[:max_rows], len(rows) - max_rows
+
+
+def render(result: DiffResult, *, max_rows: int | None = None) -> str:
+    """Render ``result`` as a markdown string.
+
+    ``max_rows`` caps the number of rows listed *per section* (added, removed,
+    changed); the omitted count is noted with an ellipsis line. ``None`` (the
+    default) lists every row. The summary headline always reflects full counts.
+    """
+    s = result.summary
+    lines: list[str] = ["# diffmonkey report", "", f"**{s.one_line()}**", ""]
+
+    key_label = ", ".join(f"`{c}`" for c in result.key_columns)
+    cols_label = ", ".join(f"`{c}`" for c in result.compared_columns) or "_(none)_"
+    lines.append(f"- Key: {key_label}")
+    lines.append(f"- Compared columns: {cols_label}")
+    lines.append(f"- Rows: {s.total_old} old → {s.total_new} new")
+    if s.duplicate_keys:
+        lines.append(f"- Duplicate keys: {s.duplicate_keys}")
+    lines.append("")
+
+    # Changed
+    lines.append(f"## Changed ({s.changed})")
+    lines.append("")
+    shown, hidden = _limit(result.changed, max_rows)
+    for rd in shown:
+        lines.append(f"### {_key_label(rd, result.key_columns)}")
+        for ch in rd.changes:
+            lines.append(f"- **{ch.column}**: `{_fmt(ch.old)}` → `{_fmt(ch.new)}`")
+        lines.append("")
+    if hidden:
+        lines.append(f"_… and {hidden} more changed row(s)._")
+        lines.append("")
+
+    # Added
+    lines.append(f"## Added ({s.added})")
+    lines.append("")
+    shown, hidden = _limit(result.added, max_rows)
+    for rd in shown:
+        lines.append(f"- {_key_label(rd, result.key_columns)}")
+    if hidden:
+        lines.append(f"_… and {hidden} more added row(s)._")
+    lines.append("")
+
+    # Removed
+    lines.append(f"## Removed ({s.removed})")
+    lines.append("")
+    shown, hidden = _limit(result.removed, max_rows)
+    for rd in shown:
+        lines.append(f"- {_key_label(rd, result.key_columns)}")
+    if hidden:
+        lines.append(f"_… and {hidden} more removed row(s)._")
+    lines.append("")
+
+    if result.warnings:
+        lines.append(f"## Warnings ({len(result.warnings)})")
+        lines.append("")
+        for w in result.warnings:
+            lines.append(f"- {w}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip("\n") + "\n"

diffmonkey/matching.py

@@ -0,0 +1,141 @@
+"""Key-based row matching.
+
+This module exists to turn two row lists into a keyed lookup so ``compare()``
+can find the partner (if any) of each row. It owns the messy parts of matching:
+composite keys, duplicate key values, and rows missing a key column. Each of
+those has a configurable policy because there is no single right answer — see
+``on_duplicate`` / ``on_missing_key`` in :func:`compare`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping
+
+from .models import DuplicateKeyError, MissingKeyError
+
+_MISSING = object()
+
+DUPLICATE_POLICIES = frozenset({"warn", "first", "last", "error"})
+MISSING_KEY_POLICIES = frozenset({"warn", "skip", "error"})
+
+
+def validate_policies(on_duplicate: str, on_missing_key: str) -> None:
+    """Validate duplicate/missing-key policy names, raising :class:`ValueError`.
+
+    Shared by :func:`index_rows` and :func:`diffmonkey.compare.compare` so both
+    entry points reject a misspelled policy with the same message and neither
+    drifts from the supported set. Callers should invoke this *before* consuming
+    their input rows so configuration errors fail eagerly.
+    """
+    if on_duplicate not in DUPLICATE_POLICIES:
+        raise ValueError(
+            f"on_duplicate must be one of {sorted(DUPLICATE_POLICIES)}, "
+            f"got {on_duplicate!r}"
+        )
+    if on_missing_key not in MISSING_KEY_POLICIES:
+        raise ValueError(
+            f"on_missing_key must be one of {sorted(MISSING_KEY_POLICIES)}, "
+            f"got {on_missing_key!r}"
+        )
+
+
+def make_key(row: Mapping[str, Any], key_columns: tuple[str, ...]) -> tuple[Any, ...]:
+    """Extract the key tuple for ``row``.
+
+    A column absent from the row contributes ``None`` (so a missing key column
+    and an explicit ``None`` collide, which the missing-key policy handles).
+    """
+    return tuple(row.get(col, None) for col in key_columns)
+
+
+def _has_missing_component(
+    row: Mapping[str, Any], key_columns: tuple[str, ...]
+) -> bool:
+    for col in key_columns:
+        if row.get(col, _MISSING) in (_MISSING, None):
+            return True
+    return False
+
+
+def index_rows(
+    rows: Iterable[Mapping[str, Any]],
+    key_columns: tuple[str, ...],
+    *,
+    side: str,
+    on_duplicate: str = "warn",
+    on_missing_key: str = "warn",
+    warnings: list[str] | None = None,
+) -> tuple[dict[tuple[Any, ...], dict[str, Any]], int, int]:
+    """Index ``rows`` by key.
+
+    Returns ``(index, total_rows, duplicate_keys)`` where ``index`` maps each
+    key tuple to a single row dict, ``total_rows`` is the number of rows that
+    made it into the index, and ``duplicate_keys`` is the count of *distinct*
+    keys that appeared more than once.
+
+    Policies:
+
+    * ``on_duplicate``: ``"warn"`` keeps the first occurrence and records a
+      warning; ``"first"``/``"last"`` keep that occurrence silently; ``"error"``
+      raises :class:`DuplicateKeyError`.
+    * ``on_missing_key``: ``"warn"`` keeps the row (key components default to
+      ``None``) and records a warning; ``"skip"`` drops the row; ``"error"``
+      raises :class:`MissingKeyError`.
+    """
+    # Validate policies eagerly (before touching any row) so a misspelled
+    # data-integrity policy fails loudly rather than silently degrading to a
+    # default that changes which data is compared.
+    validate_policies(on_duplicate, on_missing_key)
+
+    warnings = warnings if warnings is not None else []
+    index: dict[tuple[Any, ...], dict[str, Any]] = {}
+    seen_counts: dict[tuple[Any, ...], int] = {}
+    duplicate_keys = 0
+    total = 0
+
+    for position, row in enumerate(rows):
+        rowd = dict(row)
+        if _has_missing_component(rowd, key_columns):
+            if on_missing_key == "error":
+                raise MissingKeyError(
+                    f"{side} row {position} is missing key column(s) "
+                    f"{key_columns}: {rowd!r}"
+                )
+            if on_missing_key == "skip":
+                warnings.append(
+                    f"{side}: row {position} skipped (missing key column)"
+                )
+                continue
+            # "warn": keep, with None for the missing component
+            warnings.append(
+                f"{side}: row {position} has a missing/None key component "
+                f"(key={make_key(rowd, key_columns)!r})"
+            )
+
+        key = make_key(rowd, key_columns)
+        prior = seen_counts.get(key, 0)
+        seen_counts[key] = prior + 1
+
+        if prior == 0:
+            index[key] = rowd
+            total += 1
+            continue
+
+        # Duplicate key.
+        if prior == 1:
+            duplicate_keys += 1  # count this key once, on its first repeat
+        if on_duplicate == "error":
+            raise DuplicateKeyError(
+                f"{side}: duplicate key {key!r} (first at an earlier row, "
+                f"again at row {position})"
+            )
+        if on_duplicate == "last":
+            index[key] = rowd  # overwrite; total unchanged
+        elif on_duplicate == "warn":
+            warnings.append(
+                f"{side}: duplicate key {key!r} at row {position}; "
+                f"keeping first occurrence"
+            )
+        # "first" / "warn": keep existing; "last": already overwrote.
+
+    return index, total, duplicate_keys