db-agent-kit 0.2.0__py3-none-any.whl

db_agent/engines/sqlserver/rules.py

@@ -0,0 +1,141 @@
+"""Upgrade-risk rules for T-SQL module code.
+
+Built from Microsoft's lists, fetched 2026-11-05:
+  DEPRECATED: Deprecated Database Engine Features in SQL Server 2016 (the cumulative baseline)
+  DISCONTINUED: Discontinued Database Engine Functionality in SQL Server
+Microsoft's pages for 2017, 2019 and 2022 add a few items (for example Distributed Replay, Machine
+Learning Server). They are not detectable from module code and are not in this table.
+See docs/risk-rules.md for the list and what each rule is based on.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+DOC_DEPRECATED = (
+    "https://learn.microsoft.com/en-us/previous-versions/sql/database-engine/"
+    "deprecated-database-engine-features-in-sql-server-2016"
+)
+DOC_DISCONTINUED = "https://learn.microsoft.com/en-us/sql/database-engine/discontinued-database-engine-functionality-in-sql-server"
+DOC_COMPAT = "https://learn.microsoft.com/en-us/sql/t-sql/statements/alter-database-transact-sql-compatibility-level"
+DOC_AZURE_DIFF = "https://learn.microsoft.com/en-us/azure/azure-sql/database/transact-sql-tsql-differences-sql-server"
+
+# Compatibility level for each major version.
+COMPAT_BY_MAJOR = {13: 130, 14: 140, 15: 150, 16: 160, 17: 170}
+
+
+@dataclass(frozen=True)
+class CodeRule:
+    id: str
+    severity: str  # high | medium | low
+    title: str
+    pattern: re.Pattern
+    replacement: str
+    doc: str = DOC_DEPRECATED
+    needs_strings: bool = False  # the rule looks inside string literals (for example HASHBYTES('MD5', ...))
+
+
+def _r(p: str) -> re.Pattern:
+    return re.compile(p, re.IGNORECASE)
+
+
+_SYS_PROCS = (
+    "sp_addlogin sp_droplogin sp_adduser sp_dropuser sp_grantdbaccess sp_revokedbaccess sp_addrole "
+    "sp_droprole sp_password sp_approlepassword sp_changeobjectowner sp_defaultdb sp_defaultlanguage "
+    "sp_denylogin sp_grantlogin sp_revokelogin sp_addapprole sp_dropapprole sp_change_users_login "
+    "sp_depends sp_renamedb sp_dbcmptlevel sp_attach_db sp_attach_single_file_db sp_addtype sp_droptype "
+    "sp_bindefault sp_unbindefault sp_bindrule sp_unbindrule sp_helpdevice sp_lock sp_indexoption "
+    "sp_dbremove sp_addremotelogin sp_addserver sp_dropremotelogin sp_helpremotelogin sp_remoteoption "
+    "sp_resetstatus sp_bindsession sp_getbindtoken sp_addextendedproc sp_dropextendedproc "
+    "sp_helpextendedproc xp_grantlogin xp_revokelogin xp_loginconfig sp_certify_removable "
+    "sp_create_removable sp_srvrolepermission sp_dbfixedrolepermission sp_trace_create sp_trace_setevent "
+    "sp_trace_setfilter sp_trace_setstatus sp_db_vardecimal_storage_format "
+    "sp_estimated_rowsize_reduction_for_vardecimal"
+).split()
+
+_COMPAT_VIEWS = (
+    "sysaltfiles syscacheobjects syscolumns syscomments sysconfigures sysconstraints syscurconfigs "
+    "sysdatabases sysdepends sysdevices sysfilegroups sysfiles sysforeignkeys sysfulltextcatalogs "
+    "sysindexes sysindexkeys syslockinfo syslogins sysmembers sysmessages sysobjects sysoledbusers "
+    "sysopentapes sysperfinfo syspermissions sysprocesses sysprotects sysreferences sysremotelogins "
+    "sysservers systypes sysusers"
+).split()
+
+_HINTS = (
+    "NOLOCK|READUNCOMMITTED|HOLDLOCK|UPDLOCK|ROWLOCK|TABLOCKX|TABLOCK|READPAST|NOWAIT|XLOCK|PAGLOCK|"
+    "SERIALIZABLE|REPEATABLEREAD|READCOMMITTED"
+)
+
+CODE_RULES: list[CodeRule] = [
+    CodeRule("dep-sp-removed-security-and-admin", "medium",
+             "Deprecated system stored procedure",
+             _r(r"\b(" + "|".join(_SYS_PROCS) + r")\b"),
+             "Use the current statement (CREATE LOGIN, CREATE USER, ALTER DATABASE, sys.dm_* views, Extended Events). See the replacement column in Microsoft's list."),
+    CodeRule("dep-compat-views", "medium",
+             "Compatibility system view (sysobjects, syscolumns and similar)",
+             _r(r"(?<![\w.])(?:(?:master|msdb|tempdb|\w+)\.)?(?:dbo\.|sys\.)?(" + "|".join(_COMPAT_VIEWS) + r")\b"),
+             "Use catalog views (sys.objects, sys.columns, sys.indexes, ...)."),
+    CodeRule("dep-set-rowcount", "low",
+             "SET ROWCOUNT (deprecated for INSERT, UPDATE and DELETE)",
+             _r(r"\bSET\s+ROWCOUNT\b"), "Use TOP. SET ROWCOUNT 0 only resets the setting; review before changing."),
+    CodeRule("dep-set-fmtonly", "medium", "SET FMTONLY",
+             _r(r"\bSET\s+FMTONLY\b"), "Use sp_describe_first_result_set or sys.dm_exec_describe_first_result_set."),
+    CodeRule("dep-group-by-all", "medium", "GROUP BY ALL",
+             _r(r"\bGROUP\s+BY\s+ALL\b"), "Rewrite with a derived table or UNION."),
+    CodeRule("dep-set-ansi-off", "medium", "SET ANSI_NULLS / ANSI_PADDING / CONCAT_NULL_YIELDS_NULL OFF, SET OFFSETS",
+             _r(r"\bSET\s+(ANSI_NULLS|ANSI_PADDING|CONCAT_NULL_YIELDS_NULL)\s+OFF\b|\bSET\s+OFFSETS\b"),
+             "These options are always ON in a future version. Test the code with them ON."),
+    CodeRule("dep-table-hint-without-with", "low", "Table hint without the WITH keyword",
+             _r(r"(\bWITH\s*)?\(\s*(?:" + _HINTS + r")\b"),
+             "Write WITH (NOLOCK), not (NOLOCK)."),
+    CodeRule("dep-textptr", "medium", "READTEXT / WRITETEXT / UPDATETEXT / TEXTPTR / TEXTVALID",
+             _r(r"\b(READTEXT|WRITETEXT|UPDATETEXT|TEXTPTR|TEXTVALID)\b"), "Use varchar(max), nvarchar(max), varbinary(max)."),
+    CodeRule("dep-dbcc", "low", "DBCC DBREINDEX / INDEXDEFRAG / SHOWCONTIG / PINTABLE / UNPINTABLE",
+             _r(r"\bDBCC\s+(DBREINDEX|INDEXDEFRAG|SHOWCONTIG|PINTABLE|UNPINTABLE)\b"),
+             "ALTER INDEX ... REBUILD / REORGANIZE, sys.dm_db_index_physical_stats."),
+    CodeRule("dep-functions", "low", "Deprecated function",
+             _r(r"\b(fn_get_sql|USER_ID|PERMISSIONS|INDEXKEY_PROPERTY|fn_virtualservernodes|fn_servershareddrives)\s*\("),
+             "fn_get_sql -> sys.dm_exec_sql_text, USER_ID -> DATABASE_PRINCIPAL_ID, PERMISSIONS -> sys.fn_my_permissions."),
+    CodeRule("dep-colon-colon-function", "low", "'::' function-calling syntax",
+             _r(r"::\s*fn_\w+"), "Use SELECT ... FROM sys.fn_name()."),
+    CodeRule("dep-setuser", "medium", "SETUSER", _r(r"\bSETUSER\b"), "Use EXECUTE AS."),
+    CodeRule("dep-grant-all", "low", "GRANT / DENY / REVOKE ALL",
+             _r(r"\b(GRANT|DENY|REVOKE)\s+ALL\b"), "Grant specific permissions."),
+    CodeRule("dep-weak-crypto", "high", "RC4 / DESX encryption or MD2, MD4, MD5, SHA, SHA1 hashing",
+             _r(r"\bALGORITHM\s*=\s*(RC4|RC4_128|DESX)\b|\bHASHBYTES\s*\(\s*'(MD2|MD4|MD5|SHA|SHA1)'"),
+             "Use AES for encryption and SHA2_256 or SHA2_512 for hashing.", needs_strings=True),
+    CodeRule("dep-xmldata", "low", "FOR XML ... XMLDATA", _r(r"\bXMLDATA\b"), "Use XSD generation."),
+    CodeRule("dep-sys-views", "low", "Deprecated catalog view",
+             _r(r"\bsys\.(sql_dependencies|numbered_procedures|numbered_procedure_parameters|traces|trace_events|trace_event_bindings|trace_categories|trace_columns|trace_subclass_values|soap_endpoints|endpoint_webmethods)\b"),
+             "sys.sql_dependencies -> sys.sql_expression_dependencies; SQL Trace views -> Extended Events."),
+    CodeRule("dep-identitycol-rowguidcol", "low", "IDENTITYCOL / ROWGUIDCOL as a column name",
+             _r(r"\b(IDENTITYCOL|ROWGUIDCOL)\b"), "Use $identity and $rowguid."),
+    CodeRule("dep-create-default-rule", "low", "CREATE DEFAULT / CREATE RULE",
+             _r(r"\bCREATE\s+(DEFAULT|RULE)\b|\bDROP\s+(DEFAULT|RULE)\b"), "Use DEFAULT and CHECK constraints."),
+    CodeRule("dep-raiserror-old", "low", "Old RAISERROR syntax without parentheses",
+             _r(r"\bRAISERROR\s+\d+\s+['@]"), "Use RAISERROR (msg, severity, state) or THROW. Not on Microsoft's deprecated list; removed earlier."),
+    CodeRule("dep-sqloledb", "medium", "SQLOLEDB provider",
+             _r(r"\bSQLOLEDB\b"), "Use Microsoft OLE DB Driver for SQL Server (MSOLEDBSQL)."),
+]
+
+
+def scan_code(code: str) -> list[tuple[CodeRule, int, str]]:
+    """Return (rule, line number, matched text) for every rule hit. Line numbers start at 1.
+
+    Strings, comments and quoted names are blanked first, so dynamic SQL held in a string is
+    not scanned (documented limit).
+    """
+    from .guard import sanitize
+
+    clean = sanitize(code, preserve_length=True)
+    with_strings = sanitize(code, preserve_length=True, keep_strings=True)
+    hits: list[tuple[CodeRule, int, str]] = []
+    for rule in CODE_RULES:
+        text = with_strings if rule.needs_strings else clean
+        for m in rule.pattern.finditer(text):
+            if rule.id == "dep-table-hint-without-with" and m.group(1):
+                continue  # WITH (NOLOCK) is the correct form
+            line = clean.count("\n", 0, m.start()) + 1
+            hits.append((rule, line, m.group(0).strip()))
+    return hits

db_agent/engines/sqlserver/sqlrefs.py

@@ -0,0 +1,103 @@
+"""Find the tables, views and procedures a dataset query uses. Best effort, with a confidence flag.
+
+high   : sqlglot parsed every statement.
+medium : sqlglot parsed some statements; the rest were read with a text fallback.
+low    : sqlglot failed; names come from a text fallback only.
+n/a    : nothing to parse (empty, or a stored procedure call, or a non-SQL language).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+import sqlglot
+from sqlglot import exp
+
+from .guard import sanitize
+
+_FALLBACK_RE = re.compile(
+    r"\b(?:FROM|JOIN|INTO|UPDATE|MERGE\s+INTO)\s+((?:\[[^\]]+\]|[\w#@$]+)(?:\s*\.\s*(?:\[[^\]]+\]|[\w#@$]+)){0,3})",
+    re.IGNORECASE,
+)
+_EXEC_RE = re.compile(r"\bEXEC(?:UTE)?\s+((?:\[[^\]]+\]|[\w$]+)(?:\.(?:\[[^\]]+\]|[\w$]+)){0,2})", re.IGNORECASE)
+_SQL_KEYWORDS = {"select", "values", "(", "lateral", "openquery", "openrowset"}
+
+
+@dataclass
+class Refs:
+    tables: list[str] = field(default_factory=list)  # tables and views (cannot tell which from text)
+    procedures: list[str] = field(default_factory=list)
+    temp_tables: list[str] = field(default_factory=list)
+    confidence: str = "n/a"
+    error: str | None = None
+
+
+def _clean_name(name: str) -> str:
+    return re.sub(r"\s*\.\s*", ".", name.replace("[", "").replace("]", "")).strip()
+
+
+def _fallback(sql: str) -> tuple[list[str], list[str]]:
+    clean = sanitize(sql, preserve_length=False)
+    tables = [m.group(1) for m in _FALLBACK_RE.finditer(sql)]
+    procs = [m.group(1) for m in _EXEC_RE.finditer(clean)]
+    return tables, procs
+
+
+def extract(sql: str, command_type: str = "Text") -> Refs:
+    refs = Refs()
+    text = (sql or "").strip()
+    if not text:
+        return refs
+    if command_type == "StoredProcedure":
+        refs.procedures = [_clean_name(text)]
+        refs.confidence = "high"
+        return refs
+    if text.startswith("="):
+        refs.confidence = "n/a"
+        refs.error = "query is an expression, not static SQL"
+        return refs
+    tables: set[str] = set()
+    temps: set[str] = set()
+    procs: set[str] = set()
+    try:
+        trees = [t for t in sqlglot.parse(text, read="tsql") if t is not None]
+    except Exception as exc:  # noqa: BLE001
+        t_fallback, p_fallback = _fallback(text)
+        refs.error = f"parse failed: {str(exc).splitlines()[0][:140]}"
+        refs.confidence = "low"
+        for n in t_fallback:
+            (temps if _clean_name(n).startswith("#") else tables).add(_clean_name(n))
+        procs.update(_clean_name(p) for p in p_fallback)
+    else:
+        degraded = False
+        for tree in trees:
+            if isinstance(tree, exp.Command):
+                degraded = True
+                t_fallback, p_fallback = _fallback(tree.sql(dialect="tsql"))
+                for n in t_fallback:
+                    (temps if _clean_name(n).startswith("#") else tables).add(_clean_name(n))
+                procs.update(_clean_name(p) for p in p_fallback)
+                continue
+            ctes = {c.alias.lower() for c in tree.find_all(exp.CTE) if c.alias}
+            exec_targets = set()
+            for ex in tree.find_all(exp.Execute):
+                if isinstance(ex.this, exp.Table):
+                    exec_targets.add(id(ex.this))
+                    procs.add(".".join(p for p in (ex.this.catalog, ex.this.db, ex.this.name) if p))
+            for t in tree.find_all(exp.Table):
+                if not t.name or id(t) in exec_targets:
+                    continue
+                if not t.args.get("db") and t.name.lower() in ctes:
+                    continue
+                parts = [p for p in (t.catalog, t.db, t.name) if p]
+                is_temp = isinstance(t.this, exp.Identifier) and bool(t.this.args.get("temporary"))
+                if is_temp:
+                    temps.add("#" + t.name)
+                else:
+                    tables.add(".".join(parts))
+        refs.confidence = "medium" if degraded else "high"
+    refs.tables = sorted(tables, key=str.lower)
+    refs.temp_tables = sorted(temps)
+    refs.procedures = sorted(procs, key=str.lower)
+    return refs

db_agent/engines/sqlserver/ssrs.py

@@ -0,0 +1,230 @@
+"""Build the SSRS report inventory from a folder of RDL files or from a ReportServer database."""
+
+from __future__ import annotations
+
+import copy
+import csv
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from . import classify as classify_mod
+from . import rdl, sqlrefs
+from .db import SafeConnection
+from .usage import UsageData
+
+# Catalog.Type values used by SSRS. Folder=1, Report=2, Resource=3, LinkedReport=4, DataSource=5,
+# Model=6, Dataset=8. Only 2, 4, 5 and 8 are read here.
+Q_CATALOG = (
+    "SELECT ItemID, Path, Name, Type, LinkSourceID, Content FROM dbo.Catalog WHERE Type IN (2, 4, 5, 8)"
+)
+Q_SUBSCRIPTIONS = """
+SELECT c.Path AS ItemPath, COUNT(*) AS subs,
+       SUM(CASE WHEN s.DataSettings IS NOT NULL THEN 1 ELSE 0 END) AS data_driven,
+       SUM(CASE WHEN s.DeliveryExtension <> 'Report Server Email' THEN 1 ELSE 0 END) AS non_email
+FROM dbo.Subscriptions s JOIN dbo.Catalog c ON c.ItemID = s.Report_OID
+GROUP BY c.Path
+"""
+
+
+def load_subscriptions_csv(path: Path) -> dict[str, dict[str, Any]]:
+    """Sidecar file for folder mode. Columns: ItemPath, DeliveryExtension, DataDriven (yes/no)."""
+    out: dict[str, dict[str, Any]] = {}
+    with open(path, newline="", encoding="utf-8-sig") as fh:
+        for r in csv.DictReader(fh):
+            lr = {k.lower(): (v or "") for k, v in r.items()}
+            key = lr.get("itempath", "").strip().lower()
+            if not key:
+                continue
+            e = out.setdefault(key, {"count": 0, "data_driven": 0, "non_email": 0})
+            e["count"] += 1
+            e["data_driven"] += 1 if lr.get("datadriven", "").strip().lower() in ("yes", "true", "1") else 0
+            e["non_email"] += 1 if lr.get("deliveryextension", "Report Server Email").strip() not in ("", "Report Server Email") else 0
+    return out
+
+
+def _unresolved(report: rdl.Report, shared_ds: dict[str, Any], shared_src: dict[str, Any]) -> bool:
+    for d in report.datasets:
+        if d.shared_dataset_reference and _key(d.shared_dataset_reference) not in shared_ds:
+            return True
+    for s in report.data_sources:
+        if s.shared_reference and _key(s.shared_reference) not in shared_src:
+            return True
+    return False
+
+
+def _key(ref: str) -> str:
+    return ref.strip().rstrip("/").split("/")[-1].lower()
+
+
+def _dataset_rows(report: rdl.Report, shared_ds: dict[str, rdl.DataSet]) -> list[dict[str, Any]]:
+    rows = []
+    for d in report.datasets:
+        eff = d
+        if d.shared_dataset_reference and _key(d.shared_dataset_reference) in shared_ds:
+            sd = shared_ds[_key(d.shared_dataset_reference)]
+            eff = rdl.DataSet(name=d.name, data_source=sd.data_source, command_type=sd.command_type, command_text=sd.command_text,
+                              query_parameters=sd.query_parameters or d.query_parameters, field_count=sd.field_count)
+        src = next((s for s in report.data_sources if s.name == eff.data_source), None)
+        non_sql = bool(src and (src.provider or "").upper() in rdl.NON_SQL_PROVIDERS)
+        refs = sqlrefs.Refs(confidence="n/a", error="non-SQL data source") if non_sql else sqlrefs.extract(eff.command_text, eff.command_type)
+        rows.append(
+            {
+                "name": d.name,
+                "shared_reference": d.shared_dataset_reference,
+                "data_source": eff.data_source,
+                "command_type": eff.command_type,
+                "command_text": eff.command_text,
+                "query_parameters": eff.query_parameters,
+                "tables": refs.tables,
+                "procedures": refs.procedures,
+                "temp_tables": refs.temp_tables,
+                "confidence": refs.confidence,
+                "parse_error": refs.error,
+            }
+        )
+    return rows
+
+
+def _report_row(
+    report: rdl.Report,
+    shared_ds: dict[str, rdl.DataSet],
+    shared_src: dict[str, Any],
+    usage: UsageData | None,
+    subs: dict[str, Any],
+    cfg: dict[str, Any],
+    linked_from: str | None = None,
+) -> dict[str, Any]:
+    datasets = _dataset_rows(report, shared_ds)
+    unresolved = _unresolved(report, shared_ds, shared_src)
+    failed = [d["name"] for d in datasets if d["confidence"] == "low"]
+    cls = classify_mod.classify(report, usage, cfg, subs, unresolved, failed)
+    servers = sorted({f"{s.server or '?'}/{s.database or '?'}" for s in report.data_sources if s.server or s.database})
+    tables = sorted({t for d in datasets for t in d["tables"]}, key=str.lower)
+    procs = sorted({p for d in datasets for p in d["procedures"]}, key=str.lower)
+    confidences = {d["confidence"] for d in datasets if d["confidence"] != "n/a"}
+    order = ["low", "medium", "high"]
+    overall = min(confidences, key=order.index) if confidences else "n/a"
+    return {
+        "name": report.name,
+        "folder": report.folder,
+        "path": report.path,
+        "file": report.file,
+        "rdl_version": report.rdl_version,
+        "linked_report_of": linked_from,
+        **cls,
+        "datasets": datasets,
+        "dataset_count": len(datasets),
+        "data_sources": [
+            {"name": s.name, "shared_reference": s.shared_reference, "provider": s.provider, "server": s.server,
+             "database": s.database, "integrated_security": s.integrated_security, "embedded_credentials": s.embedded_credentials}
+            for s in report.data_sources
+        ],
+        "data_source_servers": servers,
+        "tables": tables,
+        "procedures": procs,
+        "ref_confidence": overall,
+        "parameters": report.parameters,
+        "parameter_count": len(report.parameters),
+        "subreports": report.subreports,
+        "drillthrough": sorted(set(report.drillthrough)),
+        "custom_code": report.has_custom_code,
+        "custom_assemblies": report.custom_assemblies,
+        "embedded_images": report.embedded_images,
+        "expressions": report.expressions,
+        "complex_expressions": report.complex_expressions,
+        "layout": report.layout,
+        "embedded_credentials": any(s.embedded_credentials for s in report.data_sources),
+        "parse_error": report.parse_error,
+    }
+
+
+def from_folder(
+    folder: Path,
+    usage: UsageData | None,
+    cfg: dict[str, Any],
+    subscriptions_csv: Path | None = None,
+) -> dict[str, Any]:
+    folder = folder.resolve()
+    reports = [rdl.parse_rdl_file(p, folder) for p in sorted(folder.rglob("*.rdl"))]
+    shared_ds: dict[str, rdl.DataSet] = {}
+    for p in folder.rglob("*.rsd"):
+        d = rdl.parse_shared_dataset_bytes(p.read_bytes())
+        if d:
+            shared_ds[p.stem.lower()] = d
+    shared_src: dict[str, Any] = {}
+    for p in folder.rglob("*.rds"):
+        s = rdl.parse_shared_datasource_bytes(p.read_bytes())
+        if s:
+            shared_src[p.stem.lower()] = s
+    sidecar = subscriptions_csv or (folder / "subscriptions.csv")
+    subs = load_subscriptions_csv(sidecar) if sidecar.exists() else {}
+    rows = [_report_row(r, shared_ds, shared_src, usage, subs, cfg) for r in reports]
+    return _wrap(rows, usage, "rdl-folder", subs_known=bool(subs))
+
+
+def from_reportserver(conn: SafeConnection, usage: UsageData | None, cfg: dict[str, Any]) -> dict[str, Any]:
+    catalog = conn.query(Q_CATALOG)
+    subs_rows = conn.query(Q_SUBSCRIPTIONS)
+    subs = {
+        (r["ItemPath"] or "").lower(): {"count": int(r["subs"]), "data_driven": int(r["data_driven"] or 0), "non_email": int(r["non_email"] or 0)}
+        for r in subs_rows
+    }
+    by_id = {r["ItemID"]: r for r in catalog}
+    shared_ds: dict[str, rdl.DataSet] = {}
+    shared_src: dict[str, Any] = {}
+    for r in catalog:
+        content = bytes(r["Content"]) if r["Content"] is not None else b""
+        if r["Type"] == 8:
+            d = rdl.parse_shared_dataset_bytes(content)
+            if d:
+                shared_ds[_key(r["Path"])] = d
+        elif r["Type"] == 5:
+            s = rdl.parse_shared_datasource_bytes(content)
+            if s:
+                shared_src[_key(r["Path"])] = s
+    rows: list[dict[str, Any]] = []
+    parsed_by_id: dict[Any, rdl.Report] = {}
+    for r in catalog:
+        if r["Type"] != 2:
+            continue
+        content = bytes(r["Content"]) if r["Content"] is not None else b""
+        path = r["Path"]
+        rep = rdl.parse_rdl_bytes(content, path.lstrip("/") + ".rdl", None)
+        folder = path.rsplit("/", 1)[0] or "/"
+        rep.name, rep.folder, rep.path = r["Name"], folder, path
+        parsed_by_id[r["ItemID"]] = rep
+        rows.append(_report_row(rep, shared_ds, shared_src, usage, subs, cfg))
+    for r in catalog:
+        if r["Type"] != 4:
+            continue
+        src = parsed_by_id.get(r["LinkSourceID"])
+        if src is None:
+            continue
+        path = r["Path"]
+        linked = copy.deepcopy(src)  # the source definition under the linked report's name
+        linked.name, linked.folder, linked.path = r["Name"], path.rsplit("/", 1)[0] or "/", path
+        rows.append(_report_row(linked, shared_ds, shared_src, usage, subs, cfg, linked_from=by_id[r["LinkSourceID"]]["Path"]))
+    return _wrap(rows, usage, "reportserver", subs_known=True)
+
+
+def _wrap(rows: list[dict[str, Any]], usage: UsageData | None, source: str, subs_known: bool) -> dict[str, Any]:
+    rows.sort(key=lambda r: (r["folder"].lower(), r["name"].lower()))
+    counts = Counter(r["classification"] for r in rows)
+    table_use = Counter(t for r in rows for t in r["tables"])
+    return {
+        "source": source,
+        "report_count": len(rows),
+        "usage": {
+            "source": usage.source if usage else None,
+            "log_window_days": usage.window_days if usage else None,
+            "oldest": usage.oldest.strftime("%Y-%m-%d") if usage and usage.oldest else None,
+            "newest": usage.newest.strftime("%Y-%m-%d") if usage and usage.newest else None,
+            "as_of": usage.as_of.strftime("%Y-%m-%d") if usage else None,
+            "note": None if usage else "No usage data supplied. Reports are never classified retire without it.",
+        },
+        "subscriptions_known": subs_known,
+        "classification_counts": dict(counts),
+        "table_usage": table_use.most_common(),
+        "reports": rows,
+    }

db_agent/engines/sqlserver/templates/summary.html.j2

@@ -0,0 +1,142 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SQL Server upgrade and SSRS report summary</title>
+<style>
+  :root { --ink:#1b2430; --muted:#5b6675; --line:#d9dfe7; --bg:#ffffff; --panel:#f5f7fa; --accent:#1f3a5f;
+          --high:#b3261e; --medium:#a35a00; --low:#4a5a6a; --move:#1d7a46; --review:#a35a00; --retire:#6b4aa0; --pass:#1d7a46; --fail:#b3261e; }
+  * { box-sizing: border-box; }
+  body { font: 15px/1.5 -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; color: var(--ink); background: var(--bg); margin: 0; }
+  main { max-width: 960px; margin: 0 auto; padding: 28px 20px 48px; }
+  h1 { font-size: 26px; margin: 0 0 4px; color: var(--accent); }
+  h2 { font-size: 19px; margin: 34px 0 10px; padding-bottom: 6px; border-bottom: 2px solid var(--line); color: var(--accent); }
+  h3 { font-size: 15px; margin: 18px 0 6px; }
+  .sub { color: var(--muted); margin: 0 0 18px; }
+  .tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 10px; margin: 14px 0; }
+  .tile { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; }
+  .tile b { display: block; font-size: 24px; line-height: 1.2; }
+  .tile span { color: var(--muted); font-size: 13px; }
+  table { border-collapse: collapse; width: 100%; font-size: 13.5px; margin: 8px 0; }
+  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { background: var(--panel); font-weight: 600; }
+  td.n, th.n { text-align: right; font-variant-numeric: tabular-nums; }
+  .tag { display: inline-block; padding: 1px 8px; border-radius: 10px; font-size: 12px; font-weight: 600; color: #fff; }
+  .high,.fail { background: var(--high); } .medium { background: var(--medium); } .low,.skipped,.info { background: var(--low); }
+  .move,.pass { background: var(--move); } .review { background: var(--review); } .retire { background: var(--retire); }
+  .bar { display: flex; height: 22px; border-radius: 6px; overflow: hidden; margin: 8px 0; border: 1px solid var(--line); }
+  .bar i { display: block; height: 100%; }
+  .note { background: #fff7e6; border: 1px solid #f0d49b; border-radius: 8px; padding: 10px 12px; margin: 12px 0; }
+  .legend span { margin-right: 14px; font-size: 13px; }
+  ol.steps li { margin: 4px 0; }
+  a { color: var(--accent); }
+  footer { margin-top: 40px; padding-top: 12px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
+  .small { color: var(--muted); font-size: 12.5px; }
+  @media print { main { max-width: none; padding: 0; } h2 { break-after: avoid; } table, .tile { break-inside: avoid; } a { color: inherit; text-decoration: none; } }
+</style>
+</head>
+<body>
+<main>
+<h1>SQL Server upgrade and SSRS report summary</h1>
+<p class="sub">Generated {{ s.generated }} by db-agent {{ s.version }}. Read-only: nothing was changed on any server.</p>
+
+<h2>Executive summary</h2>
+<div class="tiles">
+  {% if s.have_inventory %}
+  <div class="tile"><b>{{ s.server.product_version }}</b><span>{{ s.server.edition }}</span></div>
+  <div class="tile"><b>{{ s.eos.date or 'not in table' }}</b><span>{{ s.eos.name }} end of support{% if s.eos.days is not none %}, {% if s.eos.days < 0 %}ended {{ -s.eos.days }} days ago{% else %}{{ s.eos.days }} days left{% endif %}{% endif %}</span></div>
+  <div class="tile"><b>{{ s.db_count }}</b><span>user databases, {{ s.db_size_gb }} GB</span></div>
+  <div class="tile"><b>{{ s.risk_counts.get('high', 0) }} / {{ s.risk_counts.get('medium', 0) }} / {{ s.risk_counts.get('low', 0) }}</b><span>risks: high / medium / low</span></div>
+  {% endif %}
+  {% if s.have_ssrs %}
+  <div class="tile"><b>{{ s.ssrs.total }}</b><span>SSRS reports</span></div>
+  <div class="tile"><b>{{ s.ssrs.used }} / {{ s.ssrs.unused }}</b><span>used / not used (365 days)</span></div>
+  <div class="tile"><b>{{ s.ssrs.counts.get('move', 0) }} / {{ s.ssrs.counts.get('review', 0) }} / {{ s.ssrs.counts.get('retire', 0) }}</b><span>move / review / retire</span></div>
+  {% endif %}
+  {% if s.have_validation %}
+  <div class="tile"><b>{{ s.validation.counts.get('pass', 0) }} / {{ s.validation.counts.get('fail', 0) }} / {{ s.validation.counts.get('skipped', 0) }}</b><span>validation pass / fail / skipped</span></div>
+  {% endif %}
+</div>
+
+<h3>Suggested next steps</h3>
+<ol class="steps">{% for t in s.next_steps %}<li>{{ t }}</li>{% endfor %}</ol>
+
+{% if s.have_inventory %}
+<h2>Databases</h2>
+<table>
+<tr><th>Database</th><th class="n">Compat level</th><th class="n">Data MB</th><th class="n">Log MB</th><th>Recovery</th></tr>
+{% for d in s.databases %}<tr><td>{{ d.name }}</td><td class="n">{{ d.compatibility_level }}</td><td class="n">{{ d.data_mb }}</td><td class="n">{{ d.log_mb }}</td><td>{{ d.recovery_model_desc }}</td></tr>{% endfor %}
+</table>
+
+<h2>Top risks</h2>
+<table>
+<tr><th>Severity</th><th>Finding</th><th class="n">Count</th><th>Example</th><th>Source</th></tr>
+{% for r in s.top_risks %}<tr><td><span class="tag {{ r.severity }}">{{ r.severity }}</span></td><td>{{ r.title }}<div class="small">{{ r.detail }}</div></td><td class="n">{{ r.count }}</td><td>{{ r.example }}</td><td><a href="{{ r.doc }}">Microsoft docs</a></td></tr>{% endfor %}
+</table>
+<p class="small">Every risk is in risks.csv. Rules come from Microsoft's deprecated and discontinued feature lists. Dynamic SQL held in strings is not scanned.</p>
+{% if s.warnings %}<div class="note"><b>Not collected:</b> {{ s.warnings | length }} item(s), for example missing permissions. See inventory.md.</div>{% endif %}
+{% endif %}
+
+{% if s.have_ssrs %}
+<h2>SSRS reports</h2>
+{% set c = s.ssrs.counts %}{% set t = s.ssrs.total or 1 %}
+<div class="bar">
+  <i style="width:{{ 100 * c.get('move', 0) / t }}%; background:var(--move)"></i>
+  <i style="width:{{ 100 * c.get('review', 0) / t }}%; background:var(--review)"></i>
+  <i style="width:{{ 100 * c.get('retire', 0) / t }}%; background:var(--retire)"></i>
+</div>
+<p class="legend"><span><span class="tag move">move</span> {{ c.get('move', 0) }}</span><span><span class="tag review">review</span> {{ c.get('review', 0) }}</span><span><span class="tag retire">retire</span> {{ c.get('retire', 0) }}</span></p>
+{% if s.ssrs.usage.source %}
+<p>Usage comes from {{ s.ssrs.usage.source }}. The log reaches back {{ s.ssrs.usage.log_window_days }} days (oldest entry {{ s.ssrs.usage.oldest }}).</p>
+{% if (s.ssrs.usage.log_window_days or 0) < 365 %}<div class="note"><b>The usage log is shorter than a year.</b> SSRS keeps 60 days by default, so a quarterly or yearly report can look unused. No report is marked retire until the log covers 365 days.</div>{% endif %}
+{% else %}<div class="note"><b>No usage data.</b> Without it, no report is marked retire.</div>{% endif %}
+
+<h3>Hard-to-move features</h3>
+<table>
+<tr><th>Feature</th><th class="n">Reports</th></tr>
+<tr><td>Custom code blocks</td><td class="n">{{ s.ssrs.hard.custom_code }}</td></tr>
+<tr><td>Custom assemblies</td><td class="n">{{ s.ssrs.hard.custom_assemblies }}</td></tr>
+<tr><td>Subreports</td><td class="n">{{ s.ssrs.hard.subreports }}</td></tr>
+<tr><td>Drillthrough</td><td class="n">{{ s.ssrs.hard.drillthrough }}</td></tr>
+<tr><td>Subscriptions{% if not s.ssrs.subscriptions_known %} (not read){% endif %}</td><td class="n">{{ s.ssrs.hard.subscriptions }}</td></tr>
+<tr><td>SQL that could not be fully parsed</td><td class="n">{{ s.ssrs.hard.parse_problems }}</td></tr>
+</table>
+<p class="small">Layout hint only: {{ s.ssrs.paginated_hint }} look like printable tabular reports (suit Power BI paginated reports); {{ s.ssrs.interactive_hint }} use charts, gauges, maps or show/hide toggles (likely an interactive rebuild).</p>
+
+<h3>Top 20 reports by use (last 365 days)</h3>
+<table>
+<tr><th>Report</th><th class="n">Runs 365d</th><th class="n">Runs 90d</th><th class="n">Users</th><th>Last run</th><th>Class</th></tr>
+{% for r in s.ssrs.top_used %}<tr><td>{{ r.path }}</td><td class="n">{{ r.runs_365 }}</td><td class="n">{{ r.runs_90 }}</td><td class="n">{{ r.distinct_users }}</td><td>{{ r.last_run }}</td><td><span class="tag {{ r.classification }}">{{ r.classification }}</span></td></tr>
+{% else %}<tr><td colspan="6">No usage data.</td></tr>{% endfor %}
+</table>
+
+<h3>Tables used most by reports</h3>
+<table>
+<tr><th>Table</th><th class="n">Reports</th></tr>
+{% for tbl, n in s.ssrs.tables %}<tr><td>{{ tbl }}</td><td class="n">{{ n }}</td></tr>{% endfor %}
+</table>
+<p class="small">Best effort from parsing report SQL. Reports that call stored procedures list the procedure, not its tables.</p>
+
+{% if s.ssrs.retire %}<h3>Retire candidates</h3>
+<table><tr><th>Report</th><th>Reason</th></tr>
+{% for r in s.ssrs.retire %}<tr><td>{{ r.path }}</td><td>{{ r.reasons | join('; ') }}</td></tr>{% endfor %}</table>{% endif %}
+
+{% if s.ssrs.review %}<h3>Needs review</h3>
+<table><tr><th>Report</th><th>Reason</th></tr>
+{% for r in s.ssrs.review %}<tr><td>{{ r.path }}</td><td>{{ r.reasons | join('; ') }}</td></tr>{% endfor %}</table>{% endif %}
+{% endif %}
+
+{% if s.have_validation %}
+<h2>Validation after the move</h2>
+<p>Row counts and totals of numeric columns were compared between the old and new server. No row values are stored.</p>
+<table>
+<tr><th>Report</th><th>Dataset</th><th>Status</th><th class="n">Source rows</th><th class="n">Target rows</th><th>Note</th></tr>
+{% for v in s.validation.rows %}<tr><td>{{ v.report }}</td><td>{{ v.dataset }}</td><td><span class="tag {{ v.status }}">{{ v.status }}</span></td><td class="n">{{ v.source_rows if v.source_rows is not none else '' }}</td><td class="n">{{ v.target_rows if v.target_rows is not none else '' }}</td><td>{{ v.differences or v.reason }}</td></tr>{% endfor %}
+</table>
+{% endif %}
+
+<footer>{{ s.footer }}</footer>
+</main>
+</body>
+</html>