ciphergate-cli 0.7.0__py3-none-any.whl

ciphergate/readers/text_reader.py

@@ -0,0 +1,59 @@
+"""Plain text / log adapter: each line is one record, scanned as free text.
+
+Lines are never interpreted as structured key/value data. Original line endings (LF, CRLF, CR) are
+preserved. Multi-line private key blocks are tracked across lines by the detector set.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import IO, Any
+
+from ciphergate.constants import InputFormat
+from ciphergate.models.finding import ScanItem
+from ciphergate.readers.base import (
+    ReaderOptions,
+    ReadStats,
+    Record,
+    decode_line,
+    has_utf8_bom,
+    read_bounded_lines,
+    split_line_ending,
+)
+
+
+class TextReader:
+    format = InputFormat.TEXT
+
+    def __init__(self, path: Path, options: ReaderOptions) -> None:
+        self.path = path
+        self.options = options
+        self.stats = ReadStats()
+        self.has_bom = options.encoding.startswith("utf-8") and has_utf8_bom(path)
+
+    def records(self) -> Iterator[Record]:
+        with self.path.open("rb") as fh:
+            for line_no, raw in read_bounded_lines(fh, self.options, self.stats):
+                text = decode_line(raw, self.options.encoding, line_no, first=line_no == 1)
+                content, ending = split_line_ending(text)
+                self.stats.records = line_no
+                yield Record(index=line_no - 1, line=line_no, data=content, line_ending=ending)
+
+    def iter_items(self, record: Record) -> Iterator[ScanItem]:
+        yield ScanItem(record.index, record.line, "", None, record.data)
+
+
+class TextWriter:
+    def __init__(self, stream: IO[str], reader: TextReader) -> None:
+        self._stream = stream
+        self._bom_pending = reader.has_bom
+
+    def write_record(self, record: Record, data: Any) -> None:
+        if self._bom_pending:
+            self._stream.write("")
+            self._bom_pending = False
+        self._stream.write(str(data) + record.line_ending)
+
+    def close(self) -> None:
+        self._stream.flush()

ciphergate/reporting/__init__.py

@@ -0,0 +1 @@
+"""Privacy-safe report building, serialization and terminal rendering."""

ciphergate/reporting/audit.py

@@ -0,0 +1,85 @@
+"""Builds ``RunReport`` objects from analysis results (privacy-safe metadata only)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import secrets
+from typing import Any
+
+from ciphergate import __version__
+from ciphergate.constants import PSEUDONYM_VERSION
+from ciphergate.models.report import RescanSummary, RunReport, RunStatus
+from ciphergate.pipeline.paths import display_path
+from ciphergate.pipeline.planner import Analysis
+
+
+def new_run_id() -> str:
+    return secrets.token_hex(8)
+
+
+def utc_now() -> str:
+    return dt.datetime.now(dt.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build_report(
+    command: str,
+    analysis: Analysis,
+    *,
+    status: RunStatus | None = None,
+    output: dict[str, Any] | None = None,
+    changes: dict[str, Any] | None = None,
+    rescan: RescanSummary | None = None,
+    extra_warnings: list[str] | None = None,
+) -> RunReport:
+    setup = analysis.setup
+    policy = setup.policy
+    path_mode = setup.runtime.path_display
+    stats = analysis.stats
+    acc = analysis.acc
+    warnings = list(policy.warnings) + list(extra_warnings or [])
+    if stats.blank_lines:
+        action = "preserved" if policy.document.settings.preserve_blank_lines else "removed"
+        warnings.append(f"{stats.blank_lines} blank line(s) {action} in output")
+    summary = acc.summary()
+    summary["dropped_columns"] = [acc.dropped_columns[i] for i in sorted(acc.dropped_columns)]
+    return RunReport(
+        command=command,
+        status=status or analysis.status,
+        run_id=new_run_id(),
+        timestamp=utc_now(),
+        version=__version__,
+        input={
+            "path": display_path(setup.input_path, path_mode),
+            "format": str(setup.fmt),
+            "bytes": stats.bytes_read,
+            "records": stats.records,
+            "blank_lines": stats.blank_lines,
+        },
+        policy={
+            "name": policy.name,
+            "policy_version": policy.version,
+            "digest": policy.digest,
+            "source": policy.source_name if path_mode != "redacted" else None,
+            "strict": policy.document.settings.strict,
+        },
+        context=setup.ctx.to_report(),
+        gates=[g.to_dict() for g in analysis.gates],
+        transfer_approvals=list(analysis.approvals),
+        summary=summary,
+        items=acc.items,
+        items_truncated=acc.truncated,
+        keys=[
+            {
+                "key_env": name,
+                "source": analysis.key_sources.get(name, "env"),
+                "status": str(state),
+                "transform_version": PSEUDONYM_VERSION,
+            }
+            for name, state in analysis.key_statuses.items()
+        ],
+        changes=changes or {},
+        parse_errors=[{"line": line, "code": code} for line, code in stats.parse_errors[:100]],
+        output=output or {"written": False},
+        rescan=rescan,
+        warnings=warnings,
+    )

ciphergate/reporting/safe_text.py

@@ -0,0 +1,71 @@
+"""Make user-controlled strings (field paths, header names, file names) safe to display/store.
+
+* Control characters (including ANSI escape introducers) are escaped as ``\\xNN``/``\\uNNNN``.
+* Path segments that themselves look like sensitive values (emails, secrets, card numbers, phone
+  numbers, IP addresses) are replaced with ``<redacted-key>`` — JSON keys and CSV headers can carry
+  data too.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from ciphergate.detectors.email import EmailDetector
+from ciphergate.detectors.ip_address import IPAddressDetector
+from ciphergate.detectors.payment_card import PaymentCardDetector
+from ciphergate.detectors.phone import PhoneDetector
+from ciphergate.detectors.secrets import SecretDetector
+from ciphergate.models.finding import ScanItem
+
+MAX_DISPLAY = 200
+# Line/paragraph separators and bidi overrides can disguise terminal output.
+_INVISIBLE = frozenset(
+    chr(c)
+    for c in (
+        0x2028,
+        0x2029,
+        0x202A,
+        0x202B,
+        0x202C,
+        0x202D,
+        0x202E,
+        0x2066,
+        0x2067,
+        0x2068,
+        0x2069,
+    )
+)
+_PROBES = (EmailDetector(), SecretDetector(), PaymentCardDetector(), IPAddressDetector())
+_PHONE = PhoneDetector()
+
+
+def escape_control(text: str) -> str:
+    out: list[str] = []
+    for ch in text:
+        code = ord(ch)
+        if code < 0x20 or code == 0x7F or 0x80 <= code < 0xA0 or ch in _INVISIBLE:
+            out.append(f"\\x{code:02x}" if code < 0x100 else f"\\u{code:04x}")
+        else:
+            out.append(ch)
+    result = "".join(out)
+    return result if len(result) <= MAX_DISPLAY else result[: MAX_DISPLAY - 3] + "..."
+
+
+def _segment_is_sensitive(segment: str) -> bool:
+    if not segment or segment.isdigit() or segment.startswith("#"):
+        return False
+    probe = ScanItem(0, None, "", None, segment)
+    if any(detector.detect(probe) for detector in _PROBES):
+        return True
+    return any(f.confidence >= 0.5 for f in _PHONE.detect(probe))
+
+
+@lru_cache(maxsize=4096)
+def safe_field_path(path: str) -> str:
+    if not path:
+        return path
+    if path.startswith("/"):
+        segments = path.split("/")[1:]
+        cleaned = ["<redacted-key>" if _segment_is_sensitive(s) else s for s in segments]
+        return escape_control("/" + "/".join(cleaned))
+    return escape_control("<redacted-key>" if _segment_is_sensitive(path) else path)

ciphergate/reporting/serializer.py

@@ -0,0 +1,44 @@
+"""Report serialization and atomic report-file writing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ciphergate.models.report import RunReport
+from ciphergate.pipeline.atomic_output import AtomicOutput
+from ciphergate.pipeline.batch import BatchReport
+from ciphergate.reporting.terminal import render_batch_summary, render_summary
+
+
+def report_to_json(report: RunReport) -> str:
+    return json.dumps(report.to_dict(), indent=2, ensure_ascii=False, allow_nan=False) + "\n"
+
+
+def render_report(report: RunReport, report_format: str) -> str:
+    if report_format == "json":
+        return report_to_json(report)
+    return render_summary(report, verbose=True)
+
+
+def write_report_file(report: RunReport, path: Path, report_format: str, *, force: bool) -> None:
+    with AtomicOutput(path, force=force) as out:
+        out.stream.write(render_report(report, report_format))
+        out.publish()
+
+
+def batch_report_to_json(report: BatchReport) -> str:
+    return json.dumps(report.to_dict(), indent=2, ensure_ascii=False, allow_nan=False) + "\n"
+
+
+def write_batch_report_file(
+    report: BatchReport, path: Path, report_format: str, *, force: bool
+) -> None:
+    text = (
+        batch_report_to_json(report)
+        if report_format == "json"
+        else render_batch_summary(report, verbose=True)
+    )
+    with AtomicOutput(path, force=force) as out:
+        out.stream.write(text)
+        out.publish()

ciphergate/reporting/terminal.py

@@ -0,0 +1,147 @@
+"""Plain-text summaries for terminals and CI logs (no colour, no values, control chars escaped)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ciphergate.constants import DISCLAIMER
+from ciphergate.models.report import RunReport
+from ciphergate.pipeline.batch import BatchReport
+from ciphergate.reporting.safe_text import escape_control
+
+SUMMARY_ITEMS = 15
+
+
+def _counts(data: dict[str, int]) -> str:
+    return ", ".join(f"{escape_control(k)}={v}" for k, v in data.items()) or "-"
+
+
+def _location(loc: dict[str, Any]) -> str:
+    parts = []
+    if loc.get("line") is not None:
+        parts.append(f"line {loc['line']}")
+    else:
+        parts.append(f"record {loc.get('record')}")
+    if loc.get("field_path"):
+        parts.append(f"field {escape_control(str(loc['field_path']))}")
+    if loc.get("span"):
+        parts.append(f"chars {loc['span'][0]}-{loc['span'][1]}")
+    if loc.get("in_key"):
+        parts.append("(key)")
+    return ", ".join(parts)
+
+
+def render_summary(report: RunReport, *, verbose: bool = False) -> str:
+    d = report.to_dict()
+    lines = [f"CipherGate {d['command']}: {d['status'].upper()} (exit {d['exit_code']})"]
+    inp = d["input"]
+    lines.append(
+        f"  input:   {escape_control(str(inp['path']))} [{inp['format']}, "
+        f"{inp['records']} record(s), {inp['bytes']} bytes]"
+    )
+    pol = d["policy"]
+    lines.append(
+        f"  policy:  {escape_control(pol['name'])} v{pol['policy_version']} "
+        f"({pol['digest'][:19]}...)"
+    )
+    ctx = ", ".join(f"{k}={v['value'] or '-'}[{v['source']}]" for k, v in d["context"].items())
+    lines.append(f"  context: {ctx}")
+    s = d["summary"]
+    lines.append(
+        f"  findings: {s.get('findings_total', 0)}  blocked: {s.get('blocked', 0)}  "
+        f"review: {s.get('review_required', 0)}"
+    )
+    if s.get("findings_total"):
+        lines.append(f"    by category: {_counts(s['by_category'])}")
+        lines.append(f"    by action:   {_counts(s['by_action'])}")
+        lines.append(f"    by reason:   {_counts(s['by_reason_code'])}")
+    if s.get("dropped_columns"):
+        lines.append(f"    dropped columns: {', '.join(s['dropped_columns'])}")
+    for gate in d["gates"]:
+        lines.append(f"  gate [{gate['severity']}] {gate['reason_code']}: {gate['message']}")
+    for approval in d["transfer_approvals"]:
+        lines.append(f"  transfer approval used: {escape_control(approval)}")
+    for key in d["keys"]:
+        lines.append(f"  key {key['key_env']}: {key['status']}")
+    for err in d["parse_errors"][:10]:
+        lines.append(f"  parse error at line {err['line']}: {err['code']}")
+    items = d["items"]
+    important = [i for i in items if i["decision"]["action"] in ("block", "review")]
+    shown = items if verbose else (important or items)[:SUMMARY_ITEMS]
+    if shown:
+        lines.append("  items:" if verbose else "  items (first shown; use --verbose or --report):")
+    for item in shown:
+        dec = item["decision"]
+        rule = dec.get("rule_id") or "-"
+        lines.append(
+            f"    {_location(item['location'])}: {item['category']} "
+            f"({item['band']}, {item['detector']}) -> {dec['action']} "
+            f"[{dec['reason_code']}; rule {escape_control(rule)}]"
+        )
+    if d["items_truncated"]:
+        lines.append("  (item list truncated; counts above are complete)")
+    if d["changes"]:
+        c = d["changes"]
+        lines.append(
+            f"  changes: records written={c.get('records_written')}, dropped="
+            f"{c.get('records_dropped')}, values changed={c.get('values_changed')}, "
+            f"type changes={c.get('type_changes')}"
+        )
+    if d["rescan"]:
+        r = d["rescan"]
+        verdict = "FAILED" if r["failed"] else "passed"
+        lines.append(
+            f"  rescan: {verdict} (strict={r['strict']}) residuals: {_counts(r['counts'])}"
+        )
+        if r["gating_by_category"]:
+            lines.append(f"    gating residuals: {_counts(r['gating_by_category'])}")
+    out = d["output"]
+    if out:
+        if out.get("written"):
+            lines.append(f"  output:  written to {escape_control(str(out.get('path')))}")
+        elif out.get("withheld_reason"):
+            lines.append(f"  output:  not written ({out['withheld_reason']})")
+    for warning in d["warnings"]:
+        lines.append(f"  warning: {escape_control(warning)}")
+    lines.append(f"  note: {DISCLAIMER}")
+    return "\n".join(lines) + "\n"
+
+
+def render_batch_summary(report: BatchReport, *, verbose: bool = False) -> str:
+    d = report.to_dict()
+    s = d["summary"]
+    lines = [
+        f"CipherGate {d['command']} (directory): {d['status'].upper()} (exit {d['exit_code']})"
+    ]
+    recursive = " (recursive)" if d["input"]["recursive"] else ""
+    lines.append(f"  input:   {escape_control(str(d['input']['path']))}{recursive}")
+    if d["policy"]:
+        lines.append(f"  policy:  {escape_control(d['policy']['name'])}")
+    lines.append(
+        f"  files: {s['files_total']}  ok: {s['files_ok']}  failed: {s['files_failed']}  "
+        f"skipped: {s['files_skipped']}"
+    )
+    lines.append(
+        f"  findings: {s['findings_total']}  blocked: {s['blocked']}  "
+        f"review: {s['review_required']}"
+    )
+    for entry in d["files"]:
+        detail = entry["status"]
+        if "error" in entry:
+            detail = f"error[{entry['error']['code']}]"
+        elif verbose:
+            detail += f", findings={entry['report']['summary'].get('findings_total', 0)}"
+        lines.append(f"    {escape_control(entry['path'])}: {detail} (exit {entry['exit_code']})")
+    for skip in d["skipped"]:
+        lines.append(f"    skipped {escape_control(skip['path'])}: {skip['reason']}")
+    out = d["output"]
+    if out:
+        if out.get("written"):
+            lines.append(f"  output:  directory written to {escape_control(str(out['path']))}")
+        else:
+            lines.append(f"  output:  not written ({out.get('withheld_reason')})")
+    for warning in d["warnings"]:
+        lines.append(f"  warning: {escape_control(warning)}")
+    lines.append("  note: per-file details are in the JSON report (--report).")
+    lines.append(f"  note: {DISCLAIMER}")
+    return "\n".join(lines) + "\n"

ciphergate/templates/starter_policy.yml

@@ -0,0 +1,77 @@
+# CipherGate starter policy — TEMPLATE, REVIEW BEFORE USE.
+#
+# Generated by `ciphergate init`. It is a conservative starting point, not a guaranteed-safe or
+# compliant configuration. Review every rule against your data, environments and destinations.
+# Context (environment/destination) is NOT pinned: supply it per run, e.g.
+#   ciphergate inspect app.log --policy ciphergate-policy.yml --environment dev --destination local_dev
+policy_version: 1
+name: starter-policy
+metadata:
+  description: "Starter template generated by ciphergate init. Template requiring review."
+  template: true
+requirements:
+  environment: true
+  destination: true
+settings:
+  strict: true
+  scan_json_keys: true  # keys can carry data; required for untrusted destinations
+  unknown_sensitive_behavior: review
+  fail_on_parse_error: true
+  report_raw_values: false
+  rescan:
+    enabled: true
+rules:
+  - id: block-credentials-untrusted
+    description: Credentials never leave for external, public or unknown destinations.
+    hard: true
+    priority: 1000
+    match:
+      categories: [credential.secret]
+      destinations: [external_vendor, external_ai, public_repository, unknown]
+    action: block
+    reason: credentials_not_permitted_for_destination
+
+  - id: redact-credentials
+    description: Elsewhere, remove credentials completely (no partial masking).
+    priority: 900
+    match:
+      categories: [credential.secret]
+    action: redact
+    reason: remove_credential
+
+  - id: redact-telemetry-untrusted
+    priority: 400
+    match:
+      categories: [network.telemetry, security.internal]
+      destinations: [external_vendor, external_ai, public_repository, unknown]
+    action: redact
+    reason: hide_internal_infrastructure
+
+  - id: keep-telemetry-internal
+    description: Internal hosts, private IPs and trace IDs are useful for internal debugging.
+    priority: 400
+    match:
+      categories: [network.telemetry]
+      destinations: [local_dev, approved_internal, staging_test, production_monitoring]
+    action: allow
+    reason: keep_debug_context_internally
+
+  - id: redact-personal-and-sensitive
+    priority: 300
+    match:
+      categories:
+        - pii.*
+        - health.phi
+        - financial.sensitive
+        - employment.sensitive
+        - security.internal
+    action: redact
+    reason: remove_identifier
+
+defaults:
+  date.generic:
+    action: allow
+  location.coarse:
+    action: redact
+  identifier.generic:
+    action: review

ciphergate/transforms/__init__.py

@@ -0,0 +1,6 @@
+"""Transformations that execute approved policy decisions."""
+
+from ciphergate.transforms.keys import KeyProvider, KeyStatus
+from ciphergate.transforms.registry import Transformer, ValueOutcome
+
+__all__ = ["KeyProvider", "KeyStatus", "Transformer", "ValueOutcome"]

ciphergate/transforms/date_shift.py

@@ -0,0 +1,79 @@
+"""Keyed date shifting that preserves intervals within a scope.
+
+Offsets are derived with HMAC-SHA-256 from the key and a scope value, in ``[-max_days, -1]`` or
+``[1, max_days]`` (never zero):
+
+* ``scope: dataset`` — one offset for the whole run (all relationships preserved).
+* ``scope: entity`` — one offset per value of ``entity_field`` in the same record (per-subject
+  consistency; structured formats only).
+
+Supported inputs: ``iso`` (``YYYY-MM-DD``, ``YYYY-MM-DD[T ]HH:MM[:SS[.ffffff]][Z|±HH:MM]``) or
+explicit ``strptime`` patterns. Fixed UTC offsets are preserved as written; named time zones and
+epoch integers are not supported. Leap days are handled by calendar arithmetic (Feb 29 + 1 day =
+Mar 1). Unparseable or out-of-range values raise ``TransformError``.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import hmac
+import re
+from typing import Any
+
+from ciphergate.errors import TransformError
+from ciphergate.models.policy import DateShiftParams
+from ciphergate.transforms.pseudonymize import canonical_value
+
+_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_ISO_DATETIME = re.compile(
+    r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:\d{2})?$"
+)
+
+
+def derive_offset_days(key: bytes, namespace: str, scope_value: Any, max_days: int) -> int:
+    tag, canonical = canonical_value(scope_value, "nfc")
+    message = f"ciphergate:dateshift:v1:{namespace}".encode() + b"\x00" + tag + b"\x00" + canonical
+    digest = hmac.new(key, message, hashlib.sha256).digest()
+    n = int.from_bytes(digest[:8], "big") % (2 * max_days)
+    return n - max_days if n < max_days else n - max_days + 1
+
+
+def _fail() -> TransformError:
+    return TransformError(
+        "date_shift cannot parse a value with the configured formats", code="date_shift_unparseable"
+    )
+
+
+def shift_date_text(text: str, offset_days: int, formats: list[str]) -> str:
+    delta = dt.timedelta(days=offset_days)
+    stripped = text.strip()
+    for fmt in formats:
+        try:
+            if fmt == "iso":
+                if _ISO_DATE.match(stripped):
+                    return (dt.date.fromisoformat(stripped) + delta).isoformat()
+                if _ISO_DATETIME.match(stripped):
+                    parsed = dt.datetime.fromisoformat(stripped.replace("Z", "+00:00"))
+                    sep = "T" if "T" in stripped else " "
+                    out = (parsed + delta).isoformat(sep=sep)
+                    if stripped.endswith("Z"):
+                        out = out.removesuffix("+00:00") + "Z"
+                    return out
+                continue
+            parsed = dt.datetime.strptime(stripped, fmt)
+            return (parsed + delta).strftime(fmt)
+        except ValueError:
+            continue
+        except OverflowError:
+            raise TransformError(
+                "date_shift result is outside the supported date range",
+                code="date_shift_out_of_range",
+            ) from None
+    raise _fail()
+
+
+def date_shift(value: Any, params: DateShiftParams, *, offset_days: int) -> str:
+    if not isinstance(value, str):
+        raise _fail()
+    return shift_date_text(value, offset_days, params.formats)

ciphergate/transforms/generalize.py

@@ -0,0 +1,107 @@
+"""Precision-reducing generalization strategies.
+
+* ``year`` / ``year_month``: ISO date or datetime (``YYYY-MM-DD[...]``) or ``YYYY/MM/DD``.
+* ``age_band``: non-negative number -> ``"30-39"`` (band_size 10); ``>= max_age`` -> ``"120+"``.
+* ``round_coordinates``: number within [-180, 180] rounded to ``decimals`` (type preserved).
+* ``numeric_bin``: number -> ``"<a"``, ``"[a, b)"`` or ``">=z"`` using the configured edges.
+
+Values that do not fit the strategy raise ``TransformError`` (fail closed; no partial guessing).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import itertools
+import math
+import re
+from typing import Any
+
+from ciphergate.errors import TransformError
+from ciphergate.models.policy import GeneralizeParams
+
+_DATE_PREFIX = re.compile(r"^(\d{4})[-/](\d{2})[-/](\d{2})(?:$|[T ])")
+YEAR_RE = re.compile(r"^\d{4}$")
+YEAR_MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
+AGE_BAND_RE = re.compile(r"^\d+-\d+$|^\d+\+$")
+
+
+def _fail(strategy: str) -> TransformError:
+    return TransformError(
+        f"generalize ({strategy}) cannot be applied to a value of this shape",
+        code="generalize_unsupported_value",
+    )
+
+
+def _number(value: Any, strategy: str) -> float:
+    if isinstance(value, bool):
+        raise _fail(strategy)
+    if isinstance(value, int | float):
+        number = float(value)
+    elif isinstance(value, str):
+        try:
+            number = float(value.strip())
+        except ValueError:
+            raise _fail(strategy) from None
+    else:
+        raise _fail(strategy)
+    if not math.isfinite(number):
+        raise _fail(strategy)
+    return number
+
+
+def _fmt(number: float) -> str:
+    return f"{number:g}"
+
+
+def generalize(value: Any, params: GeneralizeParams) -> Any:
+    strategy = params.strategy
+    if strategy in ("year", "year_month"):
+        if not isinstance(value, str):
+            raise _fail(strategy)
+        m = _DATE_PREFIX.match(value.strip())
+        if not m:
+            raise _fail(strategy)
+        try:
+            dt.date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+        except ValueError:
+            raise _fail(strategy) from None
+        return m.group(1) if strategy == "year" else f"{m.group(1)}-{m.group(2)}"
+    if strategy == "age_band":
+        age = _number(value, strategy)
+        if age < 0:
+            raise _fail(strategy)
+        if age >= params.max_age:
+            return f"{params.max_age}+"
+        low = int(age // params.band_size) * params.band_size
+        return f"{low}-{min(low + params.band_size - 1, params.max_age - 1)}"
+    if strategy == "round_coordinates":
+        coordinate = _number(value, strategy)
+        if abs(coordinate) > 180:
+            raise _fail(strategy)
+        rounded = round(coordinate, params.decimals)
+        if isinstance(value, str):
+            return f"{rounded:.{params.decimals}f}"
+        return rounded
+    if strategy == "numeric_bin":
+        number = _number(value, strategy)
+        edges = params.bins or []
+        if number < edges[0]:
+            return f"<{_fmt(edges[0])}"
+        for lo, hi in itertools.pairwise(edges):
+            if lo <= number < hi:
+                return f"[{_fmt(lo)}, {_fmt(hi)})"
+        return f">={_fmt(edges[-1])}"
+    raise TransformError("unsupported generalize strategy", code="unsupported_transform")
+
+
+def matches_generalized_shape(text: str, params: GeneralizeParams) -> bool:
+    """Used by rescan: does this text already look like this strategy's output?"""
+    if params.strategy == "year":
+        return bool(YEAR_RE.match(text))
+    if params.strategy == "year_month":
+        return bool(YEAR_MONTH_RE.match(text))
+    if params.strategy == "age_band":
+        return bool(AGE_BAND_RE.match(text))
+    if params.strategy == "numeric_bin":
+        return text.startswith(("<", "[", ">="))
+    return False