cleanframe-engine 0.3.0__py3-none-any.whl

cleanframe/detectors/dates.py

@@ -0,0 +1,204 @@
+"""Date detection and format inference.
+
+Given a column the profiler flagged as dates, this figures out *which* formats are
+actually present (a file mixing ``31/01/2024``, ``2024-01-31``, and ``1 Jan 2024``
+is the whole point) and proposes a ``parse_date`` op that normalises them to ISO.
+
+Ambiguous day/month order (``05/06/2024``) is resolved from the data when any value
+disambiguates (a component > 12); otherwise it honours the ``dayfirst`` option and
+records the assumption in the issue's evidence rather than guessing silently.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pandas as pd
+
+from .._util import sample_non_null
+from ..issues import Issues, _cap_examples
+from ..profile import COMMON_DATE_FORMATS, _looks_date
+from ..types import Op, Severity
+from .base import DetectorContext, detector
+
+_DAYFIRST_FORMATS = {"%d/%m/%Y", "%d-%m-%Y", "%d.%m.%Y", "%d/%m/%y", "%d-%m-%y"}
+_MONTHFIRST_FORMATS = {"%m/%d/%Y", "%m-%d-%Y", "%m/%d/%y"}
+_SLASH_DATE_RE = re.compile(r"^\s*(\d{1,2})[/\-.](\d{1,2})[/\-.]\d{2,4}\s*$")
+
+
+def _infer_direction(values: list[str]) -> bool | None:
+    """Derive day-first vs month-first from any value with a component > 12.
+
+    A value like ``01/13/2024`` (second component 13 > 12) proves the column is
+    month-first; ``13/01/2024`` proves day-first. Returns ``True`` (day-first),
+    ``False`` (month-first), or ``None`` when nothing disambiguates or the column
+    genuinely mixes both orders. Feeding this into :func:`_infer_formats` stops the
+    greedy cover from producing two contradictory ``d/m`` + ``m/d`` formats that
+    silently swap day and month on the ambiguous (both ≤ 12) values.
+    """
+    saw_dayfirst = saw_monthfirst = False
+    for v in values:
+        m = _SLASH_DATE_RE.match(v)
+        if not m:
+            continue
+        a, b = int(m.group(1)), int(m.group(2))
+        if a > 12 and b <= 12:
+            saw_dayfirst = True
+        elif b > 12 and a <= 12:
+            saw_monthfirst = True
+    if saw_dayfirst and not saw_monthfirst:
+        return True
+    if saw_monthfirst and not saw_dayfirst:
+        return False
+    return None
+
+
+def _ordered_formats(dayfirst: bool | None) -> list[str]:
+    """COMMON_DATE_FORMATS, reordered so the preferred d/m-vs-m/d variant wins ties."""
+    if dayfirst is False:
+        # Prefer month-first: move month-first formats ahead of their day-first twins.
+        monthfirst = [f for f in COMMON_DATE_FORMATS if f in _MONTHFIRST_FORMATS]
+        rest = [f for f in COMMON_DATE_FORMATS if f not in _MONTHFIRST_FORMATS]
+        return monthfirst + rest
+    return list(COMMON_DATE_FORMATS)
+
+
+def _infer_formats(values: list[str], dayfirst: bool | None) -> tuple[list[str], int]:
+    """Greedy minimal cover of ``values`` by common formats. Returns (formats, unparsed)."""
+    dateish = [v for v in values if _looks_date(v)]
+    if not dateish:
+        return [], 0
+    ser = pd.Series(dateish, dtype="object")
+    covered = pd.Series(False, index=ser.index)
+    kept: list[str] = []
+    for fmt in _ordered_formats(dayfirst):
+        pending = ser[~covered]
+        if pending.empty:
+            break
+        parsed = pd.to_datetime(pending, format=fmt, errors="coerce")
+        hit = parsed.notna()
+        if hit.any():
+            kept.append(fmt)
+            covered.loc[pending.index[hit.to_numpy()]] = True
+    kept = _reconcile_slash_formats(kept, dayfirst)
+    # Recount against the formats actually kept: dropping the conflicting d/m vs m/d
+    # family leaves values that no longer parse, and reporting 0 would hide the NaTs.
+    covered = pd.Series(False, index=ser.index)
+    for fmt in kept:
+        pending = ser[~covered]
+        if pending.empty:
+            break
+        parsed = pd.to_datetime(pending, format=fmt, errors="coerce")
+        covered.loc[pending.index[parsed.notna().to_numpy()]] = True
+    unparsed = int((~covered).sum())
+    return kept, unparsed
+
+
+def _reconcile_slash_formats(formats: list[str], dayfirst: bool | None) -> list[str]:
+    """Never keep both day-first and month-first slash formats in one recipe.
+
+    Ambiguous values (both components ≤ 12) would silently swap day/month depending
+    on which format is tried first. Prefer the inferred/option direction; default
+    to day-first when nothing disambiguates (matches COMMON_DATE_FORMATS order).
+    """
+    has_day = any(f in _DAYFIRST_FORMATS for f in formats)
+    has_month = any(f in _MONTHFIRST_FORMATS for f in formats)
+    if not (has_day and has_month):
+        return formats
+    prefer_day = True if dayfirst is None else bool(dayfirst)
+    drop = _MONTHFIRST_FORMATS if prefer_day else _DAYFIRST_FORMATS
+    return [f for f in formats if f not in drop]
+
+
+@detector("dates", priority=40)
+def detect_dates(series: pd.Series, ctx: DetectorContext) -> Issues:
+    """Detect mixed / non-ISO date formats and propose normalising them to ISO."""
+    issues = Issues()
+    cp = ctx.column_profile
+    if cp is None or cp.count == 0 or cp.semantic_type not in ("date", "datetime"):
+        return issues
+    # Already a proper datetime dtype — nothing to normalise.
+    if pd.api.types.is_datetime64_any_dtype(series.dtype):
+        return issues
+
+    values = [v if isinstance(v, str) else str(v) for v in sample_non_null(series)]
+    dayfirst_opt = ctx.option("dayfirst")
+    if dayfirst_opt is None:
+        # Derive day/month order from the data when the user hasn't pinned it, so
+        # the greedy cover uses one consistent slash format for the whole column.
+        dayfirst_opt = _infer_direction(values)
+    formats, unparsed = _infer_formats(values, dayfirst_opt)
+    if not formats:
+        # Looked like dates to the profiler but nothing parses cleanly.
+        issues.add(
+            "unparseable_dates",
+            "Column looks date-like but matches no known format",
+            severity=Severity.WARNING,
+            confidence=0.5,
+            evidence={"examples": _cap_examples(values)},
+        )
+        return issues
+
+    already_iso = formats == ["%Y-%m-%d"] and unparsed == 0
+    if already_iso:
+        return issues
+
+    dayfirst = formats[0] in _DAYFIRST_FORMATS
+    ambiguous = _is_ambiguous(values)
+    kind = "mixed_date_formats" if len(formats) > 1 else "nonstandard_date_format"
+    sev = Severity.WARNING if (len(formats) > 1 or unparsed) else Severity.INFO
+    # Preserve time-of-day if any inferred format carries one (don't truncate to date).
+    output = "%Y-%m-%dT%H:%M:%S" if any("%H" in f for f in formats) else "%Y-%m-%d"
+
+    evidence = {
+        "formats_found": formats,
+        "unparsed": unparsed,
+        "examples": _cap_examples(values),
+    }
+    if ambiguous:
+        evidence["ambiguous_day_month"] = True
+        evidence["assumed"] = "day-first" if dayfirst else "month-first"
+    if any("%y" in f for f in formats):
+        # 2-digit years use strptime's 1969–2068 century pivot — surface it.
+        evidence["two_digit_year_pivot"] = "1969-2068"
+
+    issues.add(
+        kind,
+        _message(formats, unparsed, ambiguous, dayfirst),
+        severity=sev,
+        confidence=0.9 if not ambiguous else 0.75,
+        evidence=evidence,
+        ops=[Op("parse_date", {"formats": formats, "dayfirst": dayfirst, "output": output})],
+    )
+    return issues
+
+
+def _is_ambiguous(values: list[str]) -> bool:
+    """True if no value disambiguates day-vs-month order (all numeric components <= 12)."""
+    import re
+
+    saw_slashlike = False
+    for v in values:
+        m = re.match(r"^\s*(\d{1,2})[/\-.](\d{1,2})[/\-.]\d{2,4}\s*$", v)
+        if not m:
+            continue
+        saw_slashlike = True
+        a, b = int(m.group(1)), int(m.group(2))
+        if a > 12 or b > 12:
+            return False
+    return saw_slashlike
+
+
+def _message(formats: list[str], unparsed: int, ambiguous: bool, dayfirst: bool) -> str:
+    if len(formats) > 1:
+        base = f"{len(formats)} different date formats present"
+    else:
+        base = f"Dates use non-ISO format {formats[0]!r}"
+    if unparsed:
+        base += f"; {unparsed} value(s) unparseable"
+    if ambiguous:
+        base += f" (day/month order ambiguous — assuming {'day' if dayfirst else 'month'}-first)"
+    return base
+
+
+__all__ = ["detect_dates"]

cleanframe/detectors/dedup.py

@@ -0,0 +1,150 @@
+"""Duplicate-row detection — exact and fuzzy.
+
+Exact full-row duplicates are safe to drop, so we propose a ``dedup`` op with high
+confidence. *Key* duplicates (two rows sharing an email/id but differing elsewhere)
+and *fuzzy* near-duplicates on name-like columns are only *reported* with
+reviewable pair evidence — silently collapsing them would lose data.
+"""
+
+from __future__ import annotations
+
+from difflib import SequenceMatcher
+
+import pandas as pd
+
+from .._util import normalize_key
+from ..issues import Issues, _cap_examples
+from ..types import Op, Severity
+from .base import DetectorContext, detector
+
+_KEY_HINTS = ("email", "id", "uuid", "guid")
+_NAME_HINTS = ("name", "customer", "client", "company", "vendor", "title")
+_FUZZY_THRESHOLD = 0.88
+_FUZZY_MAX_ROWS = 200  # pairwise cost; bound for determinism + speed
+
+
+def _key_columns(ctx: DetectorContext) -> list[str]:
+    keys: list[str] = []
+    for cp in ctx.profile.columns:
+        low = cp.name.lower()
+        if cp.semantic_type in ("email", "id") or any(h in low for h in _KEY_HINTS):
+            keys.append(cp.name)
+    return keys
+
+
+def _fuzzy_columns(ctx: DetectorContext) -> list[str]:
+    cols: list[str] = []
+    for cp in ctx.profile.columns:
+        low = cp.name.lower()
+        if cp.semantic_type in ("text", "categorical", "id") and any(
+            h in low for h in _NAME_HINTS
+        ):
+            cols.append(cp.name)
+    return cols
+
+
+def _fuzzy_pairs(df: pd.DataFrame, column: str) -> list[dict]:
+    """Return near-duplicate (i, j, score, values) pairs, sorted deterministically."""
+    if column not in df.columns or len(df) < 2:
+        return []
+    # Cap pairwise work; take a stable head so results don't depend on shuffle.
+    work = df.head(_FUZZY_MAX_ROWS)
+    # Use positional ids (0..n-1) not the index label — labels may be strings,
+    # Timestamps, or anything else, and int(label) would crash on them.
+    values = [
+        (pos, str(v).strip())
+        for pos, (_idx, v) in enumerate(work[column].items())
+        if pd.notna(v)
+    ]
+    pairs: list[dict] = []
+    for i in range(len(values)):
+        idx_i, a = values[i]
+        if not a:
+            continue
+        na = normalize_key(a)
+        for j in range(i + 1, len(values)):
+            idx_j, b = values[j]
+            if not b or a == b:
+                continue
+            # Skip exact-normalized matches — those are category/casing, not fuzzy.
+            if na == normalize_key(b):
+                continue
+            score = SequenceMatcher(None, a.casefold(), b.casefold()).ratio()
+            if score >= _FUZZY_THRESHOLD:
+                pairs.append(
+                    {
+                        "rows": [idx_i, idx_j],
+                        "values": [a, b],
+                        "score": round(score, 3),
+                        "proposal": {"keep": idx_i, "drop": idx_j},
+                    }
+                )
+    pairs.sort(key=lambda p: (-p["score"], p["rows"][0], p["rows"][1]))
+    return pairs
+
+
+@detector("dedup", scope="frame", priority=80)
+def detect_duplicates(df: pd.DataFrame, ctx: DetectorContext) -> Issues:
+    """Propose dropping exact duplicate rows; report key/fuzzy duplicates for review."""
+    issues = Issues()
+    if len(df) == 0:
+        return issues
+
+    # Reuse the profiler's exact-duplicate count instead of hashing the whole frame
+    # a second time (the profiler already computed df.duplicated() for every clean).
+    exact = int(ctx.profile.duplicate_row_count)
+    if exact:
+        issues.add(
+            "duplicate_rows",
+            f"{exact} exact duplicate row(s)",
+            severity=Severity.WARNING,
+            confidence=1.0,
+            evidence={"count": exact},
+            ops=[Op("dedup", {"keep": "first"})],
+        )
+
+    # Key duplicates beyond the exact ones — report, don't auto-merge.
+    for key in _key_columns(ctx):
+        if key not in df.columns:
+            continue
+        dupe_mask = df[key].dropna().duplicated(keep=False)
+        n = int(dupe_mask.sum())
+        if n > exact:
+            examples = (
+                df.loc[df[key].duplicated(keep=False), key]
+                .dropna()
+                .drop_duplicates()
+                .head(5)
+                .tolist()
+            )
+            issues.add(
+                "duplicate_keys",
+                f"Column {key!r} has {n} row(s) sharing a value that should be unique",
+                severity=Severity.WARNING,
+                column=key,
+                confidence=0.6,
+                evidence={"count": n, "examples": _cap_examples(examples)},
+            )
+
+    # Fuzzy near-duplicates on name-like columns — reviewable merge proposals only.
+    for col in _fuzzy_columns(ctx):
+        pairs = _fuzzy_pairs(df, col)
+        if not pairs:
+            continue
+        issues.add(
+            "fuzzy_duplicates",
+            f"{len(pairs)} near-duplicate pair(s) in {col!r} (fuzzy match ≥ {_FUZZY_THRESHOLD:.0%})",
+            severity=Severity.INFO,
+            column=col,
+            confidence=0.55,  # below auto threshold — review mode surfaces it
+            evidence={
+                "count": len(pairs),
+                "threshold": _FUZZY_THRESHOLD,
+                "pairs": pairs[:10],
+            },
+            # No ops — merge is a human decision; evidence carries keep/drop proposals.
+        )
+    return issues
+
+
+__all__ = ["detect_duplicates"]

cleanframe/detectors/nulls.py

@@ -0,0 +1,109 @@
+"""Missing values — real and disguised.
+
+Two distinct jobs:
+
+* **Disguised nulls** (``"NA"``, ``"-"``, ``"unknown"``) are a *fix*: we propose a
+  ``to_na`` op to turn them into real NaN so downstream parsing and counts are
+  honest.
+* **Actually-missing values** are *reported, never imputed*. CleanFrame will tell
+  you a column is 40% empty; it will not silently invent values. (Users who want
+  imputation add an explicit ``fill_na`` op themselves.)
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from .._util import is_string_like, looks_like_code_values, sample_non_null
+from ..issues import Issues
+from ..ops import DEFAULT_NA_TOKENS
+from ..types import Op, Severity
+from .base import DetectorContext, detector
+
+_NA_LOOKUP = {t.strip().casefold() for t in DEFAULT_NA_TOKENS if t}
+#: Tokens that are frequently *legitimate* data (an allergy of "none", a status of
+#: "unknown", a placeholder "-"). We surface these for review but do NOT auto-convert
+#: them below strict review, so a real category is never silently turned into NaN.
+_AMBIGUOUS_NA = {"none", "nil", "-", "--", "?", "unknown"}
+
+
+@detector("nulls", priority=20)
+def detect_nulls(series: pd.Series, ctx: DetectorContext) -> Issues:
+    """Convert disguised nulls to NaN; report genuinely-missing and structural oddities."""
+    issues = Issues()
+    cp = ctx.column_profile
+    if cp is None:
+        return issues
+
+    # 1) Disguised nulls in string columns -> fixable.
+    if is_string_like(series):
+        sample = sample_non_null(series)
+        disguised: dict[str, int] = {}
+        for v in sample:
+            if isinstance(v, str) and v.strip().casefold() in _NA_LOOKUP:
+                disguised[v] = disguised.get(v, 0) + 1
+        if disguised:
+            ambiguous_tokens = set(_AMBIGUOUS_NA)
+            if looks_like_code_values(sample):
+                ambiguous_tokens |= {"na", "nan", "nil", "none"}
+            unambiguous = sorted(
+                v for v in disguised if v.strip().casefold() not in ambiguous_tokens
+            )
+            ambiguous = sorted(v for v in disguised if v.strip().casefold() in ambiguous_tokens)
+            # Unambiguous null tokens ('', 'n/a', 'null', …) — safe to convert.
+            if unambiguous:
+                n = sum(disguised[t] for t in unambiguous)
+                issues.add(
+                    "disguised_nulls",
+                    f"{n} value(s) are disguised nulls ({', '.join(map(repr, unambiguous[:4]))})",
+                    severity=Severity.WARNING,
+                    confidence=1.0,
+                    evidence={"count": n, "tokens": {t: disguised[t] for t in unambiguous}},
+                    ops=[Op("to_na", {"tokens": unambiguous})],
+                )
+            # Ambiguous tokens that may be legitimate data — report, don't auto-convert.
+            if ambiguous:
+                n = sum(disguised[t] for t in ambiguous)
+                issues.add(
+                    "disguised_nulls",
+                    f"{n} value(s) may be disguised nulls "
+                    f"({', '.join(map(repr, ambiguous[:4]))}) — review before converting",
+                    severity=Severity.INFO,
+                    confidence=0.45,  # below the review threshold: surfaced, not auto-applied
+                    evidence={"count": n, "tokens": {t: disguised[t] for t in ambiguous}, "ambiguous": True},
+                    ops=[Op("to_na", {"tokens": ambiguous})],
+                )
+
+    # 2) Genuinely missing values -> report only.
+    if cp.null_count:
+        sev = Severity.WARNING if cp.null_fraction >= 0.2 else Severity.INFO
+        issues.add(
+            "missing_values",
+            f"{cp.null_count} missing value(s) ({cp.null_fraction:.0%} of the column)",
+            severity=sev,
+            confidence=1.0,
+            evidence={"null_count": cp.null_count, "null_fraction": round(cp.null_fraction, 4)},
+        )
+
+    # 3) Structural oddities worth surfacing.
+    if cp.count == 0:
+        issues.add(
+            "empty_column",
+            "Column is entirely empty",
+            severity=Severity.WARNING,
+            confidence=1.0,
+            evidence={},
+        )
+    elif cp.is_constant:
+        only = cp.sample_values[0] if cp.sample_values else None
+        issues.add(
+            "constant_column",
+            f"Column has a single value throughout ({only!r})",
+            severity=Severity.INFO,
+            confidence=1.0,
+            evidence={"value": only},
+        )
+    return issues
+
+
+__all__ = ["detect_nulls"]

cleanframe/detectors/outliers.py

@@ -0,0 +1,73 @@
+"""Outlier detection — flagged with evidence, never auto-"fixed".
+
+Uses a classic Tukey IQR fence on numeric columns. Findings carry the fence
+bounds and example values so a human (or a downstream validator) can decide;
+no ops are attached, matching the README / CONTRIBUTING invariant that outliers
+are detected, never silently corrected.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ..issues import Issues, _cap_examples
+from ..types import Severity
+from .base import DetectorContext, detector
+
+_MIN_VALUES = 8
+_IQR_K = 1.5
+
+
+@detector("outliers", priority=70)
+def detect_outliers(series: pd.Series, ctx: DetectorContext) -> Issues:
+    """Flag numeric outliers via the IQR fence. Report only — never propose a fix."""
+    issues = Issues()
+    cp = ctx.column_profile
+    if cp is None or cp.count < _MIN_VALUES:
+        return issues
+    if cp.semantic_type not in ("integer", "float", "currency"):
+        # Also accept already-numeric dtypes even if semantic type is currency-as-float.
+        if not (
+            pd.api.types.is_numeric_dtype(series.dtype)
+            and not pd.api.types.is_bool_dtype(series.dtype)
+        ):
+            return issues
+
+    numeric = pd.to_numeric(series, errors="coerce").dropna()
+    if len(numeric) < _MIN_VALUES:
+        return issues
+
+    q1 = float(numeric.quantile(0.25))
+    q3 = float(numeric.quantile(0.75))
+    iqr = q3 - q1
+    if iqr == 0:
+        return issues
+    low = q1 - _IQR_K * iqr
+    high = q3 + _IQR_K * iqr
+    mask = (numeric < low) | (numeric > high)
+    n = int(mask.sum())
+    if n == 0:
+        return issues
+
+    # Slice to the cap BEFORE materialising — a column with millions of outliers must
+    # not build a giant throwaway Python list just to keep 5 examples.
+    examples = numeric[mask].head(5).tolist()
+    issues.add(
+        "outliers",
+        f"{n} outlier value(s) outside IQR fence [{low:.4g}, {high:.4g}]",
+        severity=Severity.INFO,
+        confidence=0.85,
+        evidence={
+            "count": n,
+            "low": low,
+            "high": high,
+            "q1": q1,
+            "q3": q3,
+            "examples": _cap_examples(examples),
+        },
+        # Intentionally no ops — outliers are never auto-fixed.
+    )
+    return issues
+
+
+__all__ = ["detect_outliers"]

cleanframe/detectors/schema_mapping.py

@@ -0,0 +1,125 @@
+"""Map a messy file onto a target schema — with confidence scores.
+
+Runs only when the caller supplied a target schema. Performs a deterministic,
+greedy 1:1 assignment of schema columns to source columns using fuzzy name
+similarity nudged by type compatibility, then emits rename proposals (strong
+matches), review-flagged weak matches, and reports for schema columns with no
+home and source columns with no schema slot.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from .._util import similarity
+from ..issues import Issues
+from ..types import Severity
+from .base import DetectorContext, detector
+
+#: Which source semantic types satisfy a given schema dtype (None = anything).
+_COMPAT: dict[str, set[str]] = {
+    "integer": {"integer", "float", "currency"},
+    "float": {"float", "integer", "currency"},
+    "currency": {"currency", "float", "integer"},
+    "date": {"date", "datetime"},
+    "datetime": {"datetime", "date"},
+    "email": {"email", "text", "id"},
+    "phone": {"phone", "text"},
+    "url": {"url", "text"},
+    "category": {"categorical", "text", "id"},
+    "boolean": {"boolean"},
+}
+
+_STRONG = 0.6
+_WEAK = 0.4
+
+
+def _type_ok(schema_dtype: str, source_semantic: str) -> bool:
+    allowed = _COMPAT.get(schema_dtype)
+    return True if allowed is None else source_semantic in allowed
+
+
+@detector("schema_mapping", scope="frame", priority=5, requires_schema=True)
+def detect_schema_mapping(df: pd.DataFrame, ctx: DetectorContext) -> Issues:
+    """Map source columns onto the target schema by fuzzy name + type, with confidence."""
+    issues = Issues()
+    schema = ctx.schema
+    if schema is None:
+        return issues
+
+    sources = [str(c) for c in df.columns]
+    used: set[str] = set()
+
+    for scol in schema.columns:
+        scored: list[tuple[float, float, str]] = []
+        for src in sources:
+            if src in used:
+                continue
+            sim = similarity(scol.name, src)
+            sp = ctx.profile.column(src)
+            compat = _type_ok(scol.dtype, sp.semantic_type) if sp else True
+            score = 1.0 if (src == scol.name or src in (scol.aliases or [])) else sim
+            if not compat:
+                score -= 0.15
+            scored.append((score, sim, src))
+
+        if not scored:
+            issues.add(
+                "missing_schema_column",
+                f"Schema column {scol.name!r} has no candidate in the data",
+                severity=Severity.WARNING,
+                confidence=1.0,
+                evidence={"target": scol.name},
+            )
+            continue
+
+        scored.sort(key=lambda t: (-t[0], t[2]))  # best score, then name asc -> deterministic
+        best_score, best_sim, best_src = scored[0]
+
+        if best_score >= _STRONG:
+            used.add(best_src)
+            if best_src != scol.name:
+                issues.add(
+                    "schema_mapping",
+                    f"Map {best_src!r} → {scol.name!r} ({best_sim:.0%} name match)",
+                    severity=Severity.INFO,
+                    column=best_src,
+                    confidence=round(best_sim, 3),
+                    evidence={"target": scol.name, "score": round(best_sim, 3)},
+                    rename_to=scol.name,
+                )
+        elif best_score >= _WEAK:
+            used.add(best_src)
+            issues.add(
+                "weak_schema_match",
+                f"{best_src!r} only weakly matches schema column {scol.name!r} ({best_sim:.0%})",
+                severity=Severity.WARNING,
+                column=best_src,
+                confidence=round(best_sim, 3),
+                evidence={"target": scol.name, "score": round(best_sim, 3)},
+                rename_to=scol.name,
+            )
+        else:
+            issues.add(
+                "missing_schema_column",
+                f"Schema column {scol.name!r} has no good match "
+                f"(closest {best_src!r} at {best_sim:.0%})",
+                severity=Severity.WARNING,
+                confidence=1.0,
+                evidence={"target": scol.name, "closest": best_src, "score": round(best_sim, 3)},
+            )
+
+    for src in sources:
+        if src not in used:
+            issues.add(
+                "extra_source_column",
+                f"Source column {src!r} is not in the target schema",
+                severity=Severity.INFO,
+                column=src,
+                confidence=1.0,
+                evidence={},
+            )
+    return issues
+
+
+__all__ = ["detect_schema_mapping"]