sqlmirror 0.2.0__py3-none-any.whl

sqlmirror/sqlcheck.py

@@ -0,0 +1,647 @@
+"""Check and rewrite Data Center report SQL so it runs against the mirror.
+
+For every statement it:
+  1. parses it in the source dialect (Postgres, SQL Server, MySQL, Oracle);
+  2. flags tables the mirror does not provide, and columns that are always NULL;
+  3. finds hard-coded Data Center ids (statuses, custom fields, projects...) and
+     usernames, which all change in a Cloud migration, and rewrites them when an
+     id map is supplied;
+  4. fixes identifier case (Active Objects tables are quoted upper-case,
+     everything else lower-case) and boolean comparisons on sprint flags;
+  5. transpiles to the mirror's database: Postgres, or SQL Server (T-SQL),
+     fixing what a plain translation gets wrong (|| with numbers, GROUP BY 1,
+     LATERAL, date_trunc, extract(epoch ...), ::numeric);
+  6. optionally compiles the result against a mirror to prove it binds
+     (EXPLAIN on Postgres, sp_describe_first_result_set on SQL Server).
+"""
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import sqlglot
+from sqlglot import exp
+from sqlglot.errors import ErrorLevel, ParseError
+
+from .idmap import IdMap
+from .schema import ALWAYS_NULL_COLUMNS, TABLE_BY_NAME, UNSUPPORTED_TABLES
+
+TARGETS = {"postgres": "postgres", "postgresql": "postgres", "sqlserver": "tsql", "mssql": "tsql", "tsql": "tsql"}
+
+DIALECTS = {"postgres": "postgres", "postgresql": "postgres", "sqlserver": "tsql", "mssql": "tsql", "tsql": "tsql",
+            "mysql": "mysql", "mariadb": "mysql", "oracle": "oracle"}
+
+MIRROR_TABLES = {name.lower(): name for name in TABLE_BY_NAME if not name.startswith("sqlmirror_")}
+AO_TABLES = {name.lower(): name for name in TABLE_BY_NAME if name.startswith("AO_")}
+AO_COLUMNS = {name.lower(): {c.lower(): c for c in TABLE_BY_NAME[name].column_names} for name in AO_TABLES.values()}
+AO_BOOLEAN_COLUMNS = {"started", "closed"}
+
+# (table, column) -> entity whose ids differ between Data Center and Cloud.
+ID_COLUMNS: dict[tuple[str, str], str] = {
+    ("jiraissue", "issuestatus"): "status",
+    ("jiraissue", "priority"): "priority",
+    ("jiraissue", "resolution"): "resolution",
+    ("jiraissue", "issuetype"): "issuetype",
+    ("jiraissue", "project"): "project",
+    ("jiraissue", "id"): "issue",
+    ("jiraissue", "security"): "securitylevel",
+    ("projectversion", "project"): "project",
+    ("component", "project"): "project",
+    ("customfieldvalue", "customfield"): "customfield",
+    ("customfieldvalue", "issue"): "issue",
+    ("customfieldoption", "customfield"): "customfield",
+    ("label", "fieldid"): "customfield",
+    ("label", "issue"): "issue",
+    ("issuelink", "linktype"): "issuelinktype",
+    ("issuelink", "source"): "issue",
+    ("issuelink", "destination"): "issue",
+    ("changegroup", "issueid"): "issue",
+    ("worklog", "issueid"): "issue",
+    ("jiraaction", "issueid"): "issue",
+    ("issuestatus", "id"): "status",
+    ("priority", "id"): "priority",
+    ("resolution", "id"): "resolution",
+    ("issuetype", "id"): "issuetype",
+    ("project", "id"): "project",
+    ("customfield", "id"): "customfield",
+    ("issuelinktype", "id"): "issuelinktype",
+    ("projectversion", "id"): "version",
+    ("component", "id"): "component",
+    ("customfieldoption", "id"): "option",
+    ("ao_60db71_sprint", "id"): "sprint",
+}
+# Column names distinctive enough to map without knowing the table.
+ID_COLUMN_NAMES = {"issuestatus": "status", "issuetype": "issuetype", "customfield": "customfield",
+                   "linktype": "issuelinktype", "fieldid": "customfield"}
+USER_COLUMNS = {"assignee", "reporter", "creator", "author", "updateauthor", "lead", "user_key", "lower_user_name",
+                "user_name", "owner_user_name"}
+AMBIGUOUS_ID_COLUMNS = {("customfieldvalue", "stringvalue"): "option or sprint ids stored as text",
+                        ("customfieldvalue", "numbervalue"): "version, project or issue ids stored as numbers",
+                        ("nodeassociation", "sink_node_id"): "version or component ids",
+                        ("changeitem", "oldvalue"): "status, user or other ids in change history",
+                        ("changeitem", "newvalue"): "status, user or other ids in change history"}
+
+ENTITY_HELP = {
+    "status": "compare issuestatus.pname instead, or map ids with --id-map",
+    "priority": "compare priority.pname instead, or map ids with --id-map",
+    "resolution": "compare resolution.pname instead, or map ids with --id-map",
+    "issuetype": "compare issuetype.pname instead, or map ids with --id-map",
+    "project": "compare project.pkey instead, or map ids with --id-map",
+    "customfield": "compare customfield.cfname instead, or map ids with --id-map",
+    "issuelinktype": "compare issuelinktype.linkname instead, or map ids with --id-map",
+    "version": "compare projectversion.vname instead, or map ids with --id-map",
+    "component": "compare component.cname instead, or map ids with --id-map",
+    "option": "compare customfieldoption.customvalue instead, or map ids with --id-map",
+    "sprint": "compare \"AO_60DB71_SPRINT\".\"NAME\" instead, or map ids with --id-map",
+    "issue": "issue ids change in migration; use project key + issue number instead",
+    "user": "Cloud identifies users by account id; join cwd_user on display_name or email, or map with --id-map",
+    "securitylevel": "security level ids change in migration",
+}
+
+
+_TARGET_NAMES = {"postgres": "Postgres", "tsql": "SQL Server"}
+_TEXT_TYPES = (exp.DataType.Type.VARCHAR, exp.DataType.Type.NVARCHAR, exp.DataType.Type.CHAR,
+               exp.DataType.Type.NCHAR, exp.DataType.Type.TEXT)
+
+
+@dataclass
+class Finding:
+    severity: str  # "error" | "warning" | "fix" | "info"
+    message: str
+
+
+@dataclass
+class StatementResult:
+    index: int
+    original: str
+    rewritten: str | None
+    findings: list[Finding] = field(default_factory=list)
+    explain: str | None = None  # None = not run, "ok" or the error text
+
+    @property
+    def verdict(self) -> str:
+        sev = {f.severity for f in self.findings}
+        if "error" in sev or (self.explain not in (None, "ok")):
+            return "needs work"
+        if "warning" in sev:
+            return "check"
+        if "fix" in sev:
+            return "rewritten"
+        return "works as-is"
+
+
+class _Capture(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.messages: list[str] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.messages.append(record.getMessage())
+
+
+def _literal_value(node: exp.Expression) -> str | None:
+    if isinstance(node, exp.Literal):
+        return node.this
+    if isinstance(node, exp.Neg) and isinstance(node.this, exp.Literal):
+        return "-" + node.this.this
+    return None
+
+
+def _set_literal(node: exp.Expression, value: str) -> None:
+    if isinstance(node, exp.Literal):
+        if node.is_string:
+            node.replace(exp.Literal.string(value))
+        elif re.fullmatch(r"-?\d+(\.\d+)?", value):
+            node.replace(exp.Literal.number(value))
+        else:
+            node.replace(exp.Literal.string(value))
+
+
+class Checker:
+    """``mirror`` (a PgMirror / MssqlMirror) or ``conn`` (a Postgres connection) enables the compile check."""
+
+    def __init__(self, read_dialect: str = "postgres", idmap: IdMap | None = None, conn: Any = None,
+                 *, mirror: Any = None, target: str | None = None):
+        if read_dialect.lower() not in DIALECTS:
+            raise ValueError(f"unknown dialect {read_dialect}; use one of {', '.join(sorted(DIALECTS))}")
+        self.read = DIALECTS[read_dialect.lower()]
+        self.idmap = idmap
+        self.mirror = mirror
+        self.conn = conn if conn is not None else getattr(mirror, "conn", None)
+        if target is None:
+            target = getattr(mirror, "dialect", None) or "postgres"
+        if target.lower() not in TARGETS:
+            raise ValueError(f"unknown target {target}; use postgres or sqlserver")
+        self.target = TARGETS[target.lower()]
+        if mirror is not None and getattr(mirror, "dialect", self.target) != self.target:
+            raise ValueError(f"the mirror is {mirror.dialect}, but --target is {self.target}")
+
+    # -------------------------------------------------------------- public
+    def check_text(self, text: str) -> list[StatementResult]:
+        try:
+            statements = sqlglot.parse(text, read=self.read)
+        except ParseError as exc:
+            return [StatementResult(1, text, None, [Finding("error", f"Could not parse: {str(exc).splitlines()[0]}")])]
+        results = []
+        for i, stmt in enumerate(s for s in statements if s is not None):
+            results.append(self.check_statement(i + 1, stmt))
+        return results
+
+    def check_statement(self, index: int, stmt: exp.Expression) -> StatementResult:
+        original = stmt.sql(dialect=self.read, pretty=True)
+        res = StatementResult(index, original, None)
+        if isinstance(stmt, (exp.Insert, exp.Update, exp.Delete, exp.Merge, exp.Create, exp.Drop, exp.Alter)):
+            res.findings.append(Finding("error", f"{stmt.key.upper()} statements are not supported: the mirror is "
+                                                 "read-only and rewritten by every sync."))
+            return res
+        if not isinstance(stmt, (exp.Select, exp.Union, exp.Intersect, exp.Except, exp.Subquery)):
+            res.findings.append(Finding("error", f"{stmt.key.upper()} statements are not report queries; skipped."))
+            return res
+
+        stmt = stmt.copy()
+        aliases = self._aliases(stmt)
+        self._check_tables(stmt, res)
+        self._fix_dialect_quirks(stmt, res)
+        self._fix_identifiers(stmt, aliases, res)
+        self._check_columns(stmt, aliases, res)
+        self._check_literals(stmt, aliases, res)
+        if self.target == "tsql" and self.read != "tsql":
+            stmt = self._to_tsql(stmt, aliases, res)
+
+        capture = _Capture()
+        logger = logging.getLogger("sqlglot")
+        logger.addHandler(capture)
+        try:
+            res.rewritten = stmt.sql(dialect=self.target, pretty=True, unsupported_level=ErrorLevel.WARN)
+        finally:
+            logger.removeHandler(capture)
+        for msg in capture.messages:
+            res.findings.append(Finding("warning", f"Dialect translation: {msg}"))
+        if self.read != self.target:
+            res.findings.append(Finding("info", f"Translated from {self.read} to {_TARGET_NAMES[self.target]}."))
+        if res.rewritten and (self.mirror is not None or self.conn is not None):
+            res.explain = self.mirror.explain(res.rewritten) if self.mirror is not None else self._explain(res.rewritten)
+        return res
+
+    # ------------------------------------------------------------ analysis
+    @staticmethod
+    def _aliases(stmt: exp.Expression) -> dict[str, str]:
+        """alias or table name (lower) -> real table name (lower). CTE names map to themselves."""
+        out: dict[str, str] = {}
+        for t in stmt.find_all(exp.Table):
+            name = t.name.lower()
+            out[t.alias_or_name.lower()] = name
+            out.setdefault(name, name)
+        return out
+
+    @staticmethod
+    def _cte_names(stmt: exp.Expression) -> set[str]:
+        return {c.alias_or_name.lower() for c in stmt.find_all(exp.CTE)}
+
+    def _check_tables(self, stmt: exp.Expression, res: StatementResult) -> None:
+        ctes = self._cte_names(stmt)
+        seen = set()
+        for t in stmt.find_all(exp.Table):
+            name = t.name.lower()
+            if name in ctes or name in seen or not name:
+                continue
+            seen.add(name)
+            if name in MIRROR_TABLES:
+                continue
+            if name in UNSUPPORTED_TABLES:
+                res.findings.append(Finding("error", f"Table {name} is not in the mirror: {UNSUPPORTED_TABLES[name]}."))
+            elif name.startswith("ao_"):
+                res.findings.append(Finding("error", f"Table {t.name} belongs to a Data Center add-on and is not mirrored."))
+            else:
+                res.findings.append(Finding("warning", f"Table {t.name} is not a Jira table the mirror provides."))
+
+    def _fix_dialect_quirks(self, stmt: exp.Expression, res: StatementResult) -> None:
+        """Rewrites sqlglot can't infer without column types."""
+        changed = []
+        if self.read == "tsql" and self.target == "postgres":
+            # SQL Server concatenates strings with "+"; Postgres needs "||".
+            def stringy(node: exp.Expression) -> bool:
+                if isinstance(node, exp.Literal) and node.is_string:
+                    return True
+                if isinstance(node, exp.Cast) and node.to.this in (exp.DataType.Type.VARCHAR, exp.DataType.Type.NVARCHAR,
+                                                                    exp.DataType.Type.CHAR, exp.DataType.Type.NCHAR,
+                                                                    exp.DataType.Type.TEXT):
+                    return True
+                if isinstance(node, (exp.Add, exp.DPipe)):
+                    return stringy(node.this) or stringy(node.expression)
+                return False
+
+            for add in list(stmt.find_all(exp.Add)):
+                if add.parent is not None and stringy(add):
+                    add.replace(exp.DPipe(this=add.this, expression=add.expression))
+                    changed.append("string concatenation + -> ||")
+        if self.read == "mysql":
+            # MySQL CAST(x AS CHAR) means "as text"; in Postgres CHAR is one character.
+            for cast in list(stmt.find_all(exp.Cast)):
+                if cast.to.this == exp.DataType.Type.CHAR and not cast.to.expressions:
+                    cast.set("to", exp.DataType.build("VARCHAR"))
+                    changed.append("CAST(... AS CHAR) -> VARCHAR")
+        for msg in sorted(set(changed)):
+            res.findings.append(Finding("fix", f"Dialect fix: {msg}."))
+
+    def _fix_identifiers(self, stmt: exp.Expression, aliases: dict[str, str], res: StatementResult) -> None:
+        fixed = False
+        for t in stmt.find_all(exp.Table):
+            name = t.name.lower()
+            ident = t.this
+            if not isinstance(ident, exp.Identifier):
+                continue
+            if name in AO_TABLES:
+                want = AO_TABLES[name]
+                if ident.this != want or not ident.quoted:
+                    t.set("this", exp.Identifier(this=want, quoted=True))
+                    fixed = True
+            elif name in MIRROR_TABLES and (ident.quoted or ident.this != name):
+                t.set("this", exp.Identifier(this=name, quoted=False))
+                fixed = True
+            # Drop schema / database qualifiers (jiradb.dbo.jiraissue -> jiraissue).
+            if name in MIRROR_TABLES and (t.args.get("db") or t.args.get("catalog")):
+                t.set("db", None)
+                t.set("catalog", None)
+                fixed = True
+
+        single_table = None
+        real = {v for k, v in aliases.items()} - self._cte_names(stmt)
+        if len(real) == 1:
+            single_table = next(iter(real))
+        for col in stmt.find_all(exp.Column):
+            table = aliases.get(col.table.lower()) if col.table else single_table
+            ident = col.this
+            if not isinstance(ident, exp.Identifier) or not table:
+                continue
+            if table in AO_TABLES:
+                want = AO_COLUMNS[table].get(ident.this.lower())
+                if want and (ident.this != want or not ident.quoted):
+                    col.set("this", exp.Identifier(this=want, quoted=True))
+                    fixed = True
+            elif table in MIRROR_TABLES and (ident.quoted or ident.this != ident.this.lower()):
+                col.set("this", exp.Identifier(this=ident.this.lower(), quoted=False))
+                fixed = True
+
+        # Sprint flags are booleans on Postgres; MySQL/SQL Server reports compare them with 0/1.
+        # (On a SQL Server mirror they are bit columns, so 0/1 is already right.)
+        for cmp in list(stmt.find_all(exp.EQ, exp.NEQ)) if self.target == "postgres" else []:
+            col, lit = (cmp.this, cmp.expression)
+            if not isinstance(col, exp.Column):
+                col, lit = lit, col
+            if not isinstance(col, exp.Column) or not isinstance(lit, exp.Literal) or lit.is_string:
+                continue
+            table = aliases.get(col.table.lower()) if col.table else single_table
+            if table in AO_TABLES and col.name.lower() in AO_BOOLEAN_COLUMNS and lit.this in ("0", "1"):
+                lit.replace(exp.Boolean(this=lit.this == "1"))
+                fixed = True
+        if fixed:
+            res.findings.append(Finding("fix", f"Adjusted identifier case / types for {_TARGET_NAMES[self.target]}."))
+
+    def _check_columns(self, stmt: exp.Expression, aliases: dict[str, str], res: StatementResult) -> None:
+        reported = set()
+        for col in stmt.find_all(exp.Column):
+            table = aliases.get(col.table.lower()) if col.table else None
+            if not table:
+                continue
+            real = TABLE_BY_NAME.get(AO_TABLES.get(table, table))
+            key = (real.name if real else table, col.name if (real and real.quoted) else col.name.lower())
+            if key in ALWAYS_NULL_COLUMNS and key not in reported:
+                reported.add(key)
+                res.findings.append(Finding("warning", f"{key[0]}.{key[1]} is always NULL in the mirror: {ALWAYS_NULL_COLUMNS[key]}."))
+            if real and real.mode != "state":
+                names = {c.lower() for c in real.column_names}
+                if col.name.lower() not in names and (table, col.name.lower()) not in reported:
+                    reported.add((table, col.name.lower()))
+                    res.findings.append(Finding("error", f"Column {table}.{col.name} does not exist in the mirror."))
+
+    def _entity_for(self, col: exp.Column, aliases: dict[str, str], single_table: str | None) -> tuple[str | None, str | None]:
+        name = col.name.lower()
+        table = aliases.get(col.table.lower()) if col.table else single_table
+        if table and (table, name) in ID_COLUMNS:
+            return ID_COLUMNS[(table, name)], table
+        if table and (table, name) in AMBIGUOUS_ID_COLUMNS:
+            return "ambiguous", table
+        if name in ID_COLUMN_NAMES and (not table or table == "jiraissue" or table in MIRROR_TABLES):
+            return ID_COLUMN_NAMES[name], table
+        if name in USER_COLUMNS:
+            return "user", table
+        return None, table
+
+    def _check_literals(self, stmt: exp.Expression, aliases: dict[str, str], res: StatementResult) -> None:
+        real = {v for v in aliases.values()} - self._cte_names(stmt)
+        single_table = next(iter(real)) if len(real) == 1 else None
+        comparisons = list(stmt.find_all(exp.EQ, exp.NEQ, exp.GT, exp.GTE, exp.LT, exp.LTE, exp.In))
+        for cmp in comparisons:
+            if isinstance(cmp, exp.In):
+                col, lits = cmp.this, list(cmp.expressions)
+            else:
+                col, other = cmp.this, cmp.expression
+                if not isinstance(col, exp.Column):
+                    col, other = other, col
+                lits = [other]
+            if not isinstance(col, exp.Column):
+                continue
+            lits = [lit for lit in lits if _literal_value(lit) is not None]
+            if not lits:
+                continue
+            entity, table = self._entity_for(col, aliases, single_table)
+            if entity is None:
+                continue
+            where = f"{col.sql()} {'IN' if isinstance(cmp, exp.In) else cmp.key.upper()}"
+            if entity == "ambiguous" and self.idmap and (table, col.name.lower()) == ("customfieldvalue", "stringvalue"):
+                # Option and sprint ids are stored as text; rewrite when exactly one mapping matches.
+                remaining = []
+                for lit in lits:
+                    value = _literal_value(lit)
+                    hits = {e: self.idmap.lookup(e, value) for e in ("option", "sprint")}
+                    hits = {e: v for e, v in hits.items() if v is not None}
+                    if len(hits) == 1:
+                        ent, mapped = next(iter(hits.items()))
+                        _set_literal(lit, mapped)
+                        res.findings.append(Finding("fix", f"{where}: Data Center {ent} {value} -> Cloud {mapped}."))
+                    else:
+                        remaining.append(lit)
+                lits = remaining
+                if not lits:
+                    continue
+            if entity == "ambiguous":
+                vals = ", ".join(_literal_value(lit) for lit in lits)
+                res.findings.append(Finding("warning", f"{where} {vals}: hard-coded value in {table}.{col.name} "
+                                                       f"({AMBIGUOUS_ID_COLUMNS[(table, col.name.lower())]}); "
+                                                       "check it still means the same thing in Cloud."))
+                continue
+            for lit in lits:
+                value = _literal_value(lit)
+                if entity == "user" and not (isinstance(lit, exp.Literal) and lit.is_string):
+                    continue
+                if entity != "user" and not re.fullmatch(r"-?\d+", value or ""):
+                    continue
+                mapped = self.idmap.lookup(entity, value) if self.idmap else None
+                if mapped is not None:
+                    _set_literal(lit, mapped)
+                    res.findings.append(Finding("fix", f"{where}: Data Center {entity} {value} -> Cloud {mapped}."))
+                else:
+                    res.findings.append(Finding("warning", f"{where} {value}: hard-coded Data Center {entity} "
+                                                           f"{'id' if entity != 'user' else 'name'}. {ENTITY_HELP.get(entity, '')}"))
+
+    # ------------------------------------------------------- to SQL Server
+    def _to_tsql(self, stmt: exp.Expression, aliases: dict[str, str], res: StatementResult) -> exp.Expression:
+        """Fix what a plain Postgres/MySQL/Oracle -> T-SQL translation gets wrong."""
+        fixes: list[str] = []
+        real = {v for v in aliases.values()} - self._cte_names(stmt)
+        single_table = next(iter(real)) if len(real) == 1 else None
+
+        def is_text(node: exp.Expression) -> bool:
+            if isinstance(node, exp.Literal):
+                return node.is_string
+            if isinstance(node, exp.Cast):
+                return node.to.this in _TEXT_TYPES
+            if isinstance(node, exp.Column):
+                table = aliases.get(node.table.lower()) if node.table else single_table
+                t = TABLE_BY_NAME.get(AO_TABLES.get(table, table)) if table else None
+                if t is not None:
+                    typ = dict((c.lower(), ty) for c, ty in t.columns).get(node.name.lower())
+                    return typ in ("str", "text")
+            if isinstance(node, (exp.Upper, exp.Lower, exp.Trim, exp.Substring, exp.Concat)):
+                return True
+            if isinstance(node, exp.Coalesce):
+                return is_text(node.this)
+            return False
+
+        # 1. a || b: T-SQL "+" adds numbers, so cast every non-text operand to text.
+        for dp in list(stmt.find_all(exp.DPipe)):
+            for side in ("this", "expression"):
+                part = dp.args.get(side)
+                if part is None or isinstance(part, exp.DPipe) or is_text(part):
+                    continue
+                part.replace(exp.Cast(this=part.copy(), to=exp.DataType.build("NVARCHAR(MAX)", dialect="tsql")))
+                fixes.append("|| with a non-text value -> + with CAST(... AS NVARCHAR(MAX))")
+
+        # 2. JOIN LATERAL (...) ON true -> CROSS APPLY / OUTER APPLY.
+        for join in list(stmt.find_all(exp.Join)):
+            lat = join.this
+            if not isinstance(lat, exp.Lateral):
+                continue
+            on = join.args.get("on")
+            if on is not None and not (isinstance(on, exp.Boolean) and on.this):
+                res.findings.append(Finding("warning", "LATERAL join with a join condition: move the condition into "
+                                                       "the subquery's WHERE and use CROSS APPLY."))
+                continue
+            outer = (join.side or "").upper() == "LEFT"
+            join.replace(exp.Join(this=exp.Lateral(this=lat.this.copy(), alias=lat.args.get("alias"),
+                                                   cross_apply=not outer)))
+            fixes.append("JOIN LATERAL -> " + ("OUTER APPLY" if outer else "CROSS APPLY"))
+
+        # 3. GROUP BY 1, 2 -> the expressions (T-SQL only allows ordinals in ORDER BY).
+        for select in list(stmt.find_all(exp.Select)):
+            group = select.args.get("group")
+            items = select.expressions
+            for g in list(group.expressions) if group else []:
+                if isinstance(g, exp.Literal) and not g.is_string and g.this.isdigit() and 0 < int(g.this) <= len(items):
+                    target = items[int(g.this) - 1]
+                    g.replace((target.this if isinstance(target, exp.Alias) else target).copy())
+                    fixes.append("GROUP BY position -> GROUP BY expression")
+
+            # ORDER BY 1 too, so NULLs sort as on Postgres (T-SQL can't do that for a position).
+            order = select.args.get("order")
+            if order and select.args.get("distinct"):
+                # Postgres sorts NULLs last; emulating that adds a CASE to ORDER BY, which SQL Server
+                # rejects with DISTINCT (Msg 145). Keep SQL Server's order and say so.
+                for o in order.expressions:
+                    if isinstance(o, exp.Ordered):
+                        o.set("nulls_first", not o.args.get("desc"))
+                res.findings.append(Finding("warning", "SELECT DISTINCT ... ORDER BY: SQL Server sorts NULLs first "
+                                                       "(Postgres sorts them last)."))
+            if order and not select.args.get("distinct") and not isinstance(select.parent, exp.SetOperation):
+                for o in list(order.expressions):
+                    pos = o.this
+                    if isinstance(pos, exp.Literal) and not pos.is_string and pos.this.isdigit() \
+                            and 0 < int(pos.this) <= len(items):
+                        target = items[int(pos.this) - 1]
+                        pos.replace((target.this if isinstance(target, exp.Alias) else target).copy())
+
+        # 4. date_trunc -> DATEADD(unit, DATEDIFF(unit, 0, x), 0), which works on every SQL Server version.
+        for node in list(stmt.find_all(exp.TimestampTrunc, exp.DateTrunc)):
+            unit = (node.args.get("unit").name if node.args.get("unit") is not None else "").upper()
+            if unit in ("YEAR", "QUARTER", "MONTH", "DAY", "HOUR", "MINUTE"):
+                tmpl = sqlglot.parse_one(f"DATEADD({unit}, DATEDIFF({unit}, 0, __sqlm_x), 0)", read="tsql")
+                tmpl.find(exp.Column).replace(node.this.copy())
+                node.replace(tmpl)
+                fixes.append(f"date_trunc('{unit.lower()}') -> DATEADD/DATEDIFF")
+            else:
+                res.findings.append(Finding("warning", f"date_trunc('{unit.lower()}') becomes DATETRUNC, which needs "
+                                                       "SQL Server 2022 or Azure SQL."))
+
+        # 5. extract(epoch FROM a - b) -> DATEDIFF_BIG(MILLISECOND, b, a) / 1000.0
+        for node in list(stmt.find_all(exp.Extract)):
+            if node.name.upper() != "EPOCH":
+                continue
+            arg = node.expression
+            while isinstance(arg, exp.Paren):
+                arg = arg.this
+            if isinstance(arg, exp.Sub):
+                start, end = arg.expression, arg.this
+            else:
+                start, end = sqlglot.parse_one("CAST('1970-01-01' AS DATETIME)", read="tsql"), arg
+            tmpl = sqlglot.parse_one("DATEDIFF_BIG(MILLISECOND, __sqlm_a, __sqlm_b) / 1000.0", read="tsql")
+            for col in list(tmpl.find_all(exp.Column)):
+                col.replace((start if col.name == "__sqlm_a" else end).copy())
+            node.replace(exp.Paren(this=tmpl))
+            fixes.append("extract(epoch ...) -> DATEDIFF_BIG(MILLISECOND, ...) / 1000.0")
+
+        # 6. ::numeric without precision is numeric(18,0) on SQL Server; keep the decimals.
+        for cast in list(stmt.find_all(exp.Cast)):
+            if cast.to.this == exp.DataType.Type.DECIMAL and not cast.to.expressions:
+                cast.set("to", exp.DataType.build("NUMERIC(38, 10)", dialect="tsql"))
+                fixes.append("CAST(... AS numeric) -> NUMERIC(38, 10)")
+
+        # 7. now(): the mirror stores UTC.
+        if getattr(self.mirror, "tz_name", "UTC") == "UTC":
+            for node in list(stmt.find_all(exp.CurrentTimestamp)):
+                node.replace(exp.Anonymous(this="GETUTCDATE", expressions=[]))
+                fixes.append("now() -> GETUTCDATE() (the mirror stores UTC)")
+        elif any(True for _ in stmt.find_all(exp.CurrentTimestamp)):
+            res.findings.append(Finding("warning", f"now() becomes GETDATE(), the SQL Server machine's local time; "
+                                                   f"the mirror stores {self.mirror.tz_name} time."))
+
+        # 8. ::text / ::varchar -> NVARCHAR(MAX) (VARCHAR would lose characters outside the code page).
+        for cast in list(stmt.find_all(exp.Cast)):
+            to = cast.to
+            if to.this == exp.DataType.Type.TEXT or (to.this == exp.DataType.Type.VARCHAR and not to.expressions):
+                cast.set("to", exp.DataType.build("NVARCHAR(MAX)", dialect="tsql"))
+
+        # 9. ILIKE -> LIKE: SQL Server's default collation is already case-insensitive.
+        for node in list(stmt.find_all(exp.ILike)):
+            node.replace(exp.Like(this=node.this.copy(), expression=node.expression.copy()))
+            fixes.append("ILIKE -> LIKE (case-insensitive under SQL Server's default collation)")
+
+        # 10. x +/- interval 'n unit' -> DATEADD(unit, +/-n, x)
+        for node in list(stmt.find_all(exp.Add, exp.Sub)):
+            iv = node.expression
+            if not isinstance(iv, exp.Interval):
+                continue
+            amount = iv.this.this if isinstance(iv.this, exp.Literal) else None
+            unit = iv.args.get("unit")
+            unit_name = (unit.name if unit is not None else "").upper().rstrip("S")
+            parts = (amount or "").split()
+            if len(parts) == 2 and not unit_name:  # interval '7 days'
+                amount, unit_name = parts[0], parts[1].upper().rstrip("S")
+            if unit_name not in ("YEAR", "QUARTER", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND") \
+                    or not re.fullmatch(r"-?\d+", amount or ""):
+                res.findings.append(Finding("warning", f"Interval arithmetic {node.sql()} has no direct T-SQL form; "
+                                                       "use DATEADD."))
+                continue
+            n = int(amount) * (-1 if isinstance(node, exp.Sub) else 1)
+            tmpl = sqlglot.parse_one(f"DATEADD({unit_name}, {n}, __sqlm_x)", read="tsql")
+            tmpl.find(exp.Column).replace(node.this.copy())
+            node.replace(tmpl)
+            fixes.append("date +/- interval -> DATEADD")
+
+        # 11. Regular expressions: not in T-SQL (before SQL Server 2025).
+        if any(True for _ in stmt.find_all(exp.RegexpLike)):
+            res.findings.append(Finding("warning", "Regular expression match (~): SQL Server has no regex before "
+                                                   "SQL Server 2025; rewrite with LIKE."))
+
+        for msg in sorted(set(fixes)):
+            res.findings.append(Finding("fix", f"SQL Server: {msg}."))
+        return stmt
+
+    def _explain(self, sql_text: str) -> str:
+        try:
+            with self.conn.cursor() as cur:
+                cur.execute("EXPLAIN " + sql_text)
+            self.conn.rollback()
+            return "ok"
+        except Exception as exc:  # psycopg.Error, kept generic so the checker works without a DB driver
+            self.conn.rollback()
+            return str(exc).strip().splitlines()[0]
+
+
+# ---------------------------------------------------------------- reporting
+def check_paths(paths: list[Path], checker: Checker) -> dict[Path, list[StatementResult]]:
+    files: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            files.extend(sorted(p.rglob("*.sql")))
+        else:
+            files.append(p)
+    return {f: checker.check_text(f.read_text(encoding="utf-8", errors="replace")) for f in files}
+
+
+def write_outputs(results: dict[Path, list[StatementResult]], out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for path, stmts in results.items():
+        body = ";\n\n".join(s.rewritten for s in stmts if s.rewritten)
+        if body:
+            (out_dir / path.name).write_text(body + ";\n", encoding="utf-8")
+
+
+def markdown_report(results: dict[Path, list[StatementResult]], *, dialect: str, explained: bool,
+                    target: str = "postgres") -> str:
+    counts: dict[str, int] = {}
+    for stmts in results.values():
+        for s in stmts:
+            counts[s.verdict] = counts.get(s.verdict, 0) + 1
+    total = sum(counts.values())
+    lines = ["# SQL Mirror: Data Center SQL check", "",
+             f"Checked {total} statements in {len(results)} files (source dialect: {dialect}, "
+             f"mirror: {_TARGET_NAMES.get(TARGETS.get(target, target), target)})."
+             + (" Each rewritten statement was compiled against the mirror." if explained else ""), ""]
+    for verdict in ("works as-is", "rewritten", "check", "needs work"):
+        if counts.get(verdict):
+            lines.append(f"- **{verdict}**: {counts[verdict]}")
+    lines.append("")
+    for path, stmts in results.items():
+        lines.append(f"## {path.name}")
+        for s in stmts:
+            label = f"Statement {s.index}" if len(stmts) > 1 else "Result"
+            lines.append(f"**{label}: {s.verdict}**" + (f" (EXPLAIN: {s.explain})" if s.explain else ""))
+            for f in s.findings:
+                if f.severity != "info":
+                    lines.append(f"- {f.severity}: {f.message}")
+            lines.append("")
+    return "\n".join(lines)