Office365-REST-Python-Client 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

office365/migration/sharepoint/site_scope.py

@@ -0,0 +1,222 @@
+"""Report the site-level scope a client-side migration does not recreate.
+
+A migration replays a list's columns, content types and views, copies the web's
+``Title``/``Description`` and its branding, and says nothing about two things that
+decide what the target site can actually *do*:
+
+* **activated features** — on the web and on its site collection. A site without
+  the publishing, records-management or document-id feature is not the same site,
+  even when every list and file arrived.
+* **regional settings** — time zone, locale, work days, calendar. Values that
+  render and filter by date depend on them.
+
+Both are readable over REST, so they are compared instead of assumed, and a
+difference is reported rather than repaired:
+
+* Activating a feature has side effects the source did not ask for at this point in
+  the run (a publishing feature installs page layouts and swaps the master page),
+  and deactivating one is not something a re-run undoes. It stays an explicit,
+  out-of-band decision.
+* Regional settings have no working REST write path (setting ``TimeZone`` id does
+  not change the web's zone), which is why
+  :mod:`office365.migration.sharepoint.site_settings` never attempts them.
+
+The comparison is **by presence and by value**, read-only: two GETs per side for
+the features, one for the regional settings and one for the time zone. Only what
+the *source* has and the target lacks is a finding — a target feature the source
+does not have is carried in the result (it is a real difference an operator may
+want to see) but is not a fidelity loss, so it does not make the report fail.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Tuple
+
+if TYPE_CHECKING:
+    from office365.sharepoint.client_context import ClientContext
+    from office365.sharepoint.features.feature import Feature
+    from office365.sharepoint.webs.web import Web
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "SiteScope",
+    "SiteScopeDiff",
+    "capture_site_scope",
+    "compare_site_scope",
+    "site_scope_note",
+]
+
+#: How many feature/regional names a single note spells out before counting the rest.
+_MAX_NAMES_IN_NOTE = 5
+
+#: Regional properties that change how values render or filter. A property the
+#: server does not return is ``None`` on both sides, which compares equal.
+_REGIONAL_PROPERTIES = (
+    "LocaleId",
+    "WorkDays",
+    "FirstDayOfWeek",
+    "FirstWeekOfYear",
+    "CalendarType",
+    "AdjustHijriDays",
+    "DateSeparator",
+    "TimeSeparator",
+    "Time24",
+    "DateFormat",
+)
+
+
+def _normalized(feature_id: Optional[str]) -> str:
+    """A feature id as a comparable key (lowercase, no braces)."""
+    return str(feature_id or "").strip().strip("{}").lower()
+
+
+def _feature_ids(features: Iterable["Feature"]) -> List[str]:
+    """The activated feature ids of a collection, sorted and de-duplicated."""
+    ids = {_normalized(feature.definition_id) for feature in features}
+    ids.discard("")
+    return sorted(ids)
+
+
+def _read_features(collection: Any) -> List[str]:
+    """The ids of one activated-feature collection (web or site collection)."""
+    return _feature_ids(collection.get().execute_query())
+
+
+def _read_regional(web: "Web") -> Dict[str, Any]:
+    """The comparable regional settings of ``web``, plus the time zone's identity."""
+    settings = web.regional_settings.get().execute_query()
+    values: Dict[str, Any] = {name: settings.properties.get(name) for name in _REGIONAL_PROPERTIES}
+    values["TimeZoneId"], values["TimeZone"] = _read_time_zone(settings)
+    return values
+
+
+def _read_time_zone(settings: Any) -> Tuple[Optional[int], Optional[str]]:
+    """``(id, description)`` of the web's time zone, or ``(None, None)`` if unreadable."""
+    try:
+        zone = settings.time_zone.get().execute_query()
+    except Exception as e:  # noqa: BLE001 — a time zone that cannot be read is not a finding
+        logger.debug("read time zone failed: %s", e)
+        return None, None
+    return zone.properties.get("Id"), zone.properties.get("Description")
+
+
+@dataclass
+class SiteScope:
+    """One site's site-level scope, as captured (the comparable projection)."""
+
+    web_features: List[str] = field(default_factory=list)
+    site_features: List[str] = field(default_factory=list)
+    regional: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """A JSON-serializable form."""
+        return {
+            "web_features": list(self.web_features),
+            "site_features": list(self.site_features),
+            "regional": dict(self.regional),
+        }
+
+
+@dataclass
+class SiteScopeDiff:
+    """What the source has and the target does not, plus the settings that differ."""
+
+    missing_web_features: List[str] = field(default_factory=list)
+    missing_site_features: List[str] = field(default_factory=list)
+    extra_web_features: List[str] = field(default_factory=list)
+    extra_site_features: List[str] = field(default_factory=list)
+    regional: Dict[str, Tuple[Any, Any]] = field(default_factory=dict)
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the target carries everything the source had (extras are not a loss)."""
+        return not self.missing_web_features and not self.missing_site_features and not self.regional
+
+    def to_dict(self) -> Dict[str, Any]:
+        """A JSON-serializable form (``regional`` maps a name to ``[source, target]``)."""
+        return {
+            "missing_web_features": list(self.missing_web_features),
+            "missing_site_features": list(self.missing_site_features),
+            "extra_web_features": list(self.extra_web_features),
+            "extra_site_features": list(self.extra_site_features),
+            "regional": {name: [value, other] for name, (value, other) in self.regional.items()},
+        }
+
+
+def capture_site_scope(context: "ClientContext") -> SiteScope:
+    """Read one site's activated features and comparable regional settings.
+
+    Args:
+        context: The site's context. The web-scope features come from
+            ``context.web``, the site-collection ones from ``context.site``.
+    """
+    return SiteScope(
+        web_features=_read_features(context.web.features),
+        site_features=_read_features(context.site.features),
+        regional=_read_regional(context.web),
+    )
+
+
+def compare_site_scope(source_context: "ClientContext", target_context: "ClientContext") -> SiteScopeDiff:
+    """What ``target_context``'s site lacks that ``source_context``'s has (read-only).
+
+    Args:
+        source_context: The site the migration reads from.
+        target_context: The site the migration wrote to.
+    """
+    source = capture_site_scope(source_context)
+    target = capture_site_scope(target_context)
+    return SiteScopeDiff(
+        missing_web_features=[name for name in source.web_features if name not in set(target.web_features)],
+        missing_site_features=[name for name in source.site_features if name not in set(target.site_features)],
+        extra_web_features=[name for name in target.web_features if name not in set(source.web_features)],
+        extra_site_features=[name for name in target.site_features if name not in set(source.site_features)],
+        regional={
+            name: (value, target.regional.get(name))
+            for name, value in source.regional.items()
+            if target.regional.get(name) != value
+        },
+    )
+
+
+def _sample_names(names: List[str]) -> str:
+    """Name a few entries inline, counting the rest."""
+    shown = ", ".join(names[:_MAX_NAMES_IN_NOTE])
+    if len(names) <= _MAX_NAMES_IN_NOTE:
+        return shown
+    return f"{shown} (+{len(names) - _MAX_NAMES_IN_NOTE} more)"
+
+
+def _regional_note(regional: Dict[str, Tuple[Any, Any]]) -> str:
+    """One clause naming each differing regional setting: ``TimeZone: 'a' vs 'b'``."""
+    return "; ".join(f"{name}: {value!r} vs {other!r}" for name, (value, other) in regional.items())
+
+
+def site_scope_note(diff: SiteScopeDiff, source_url: Optional[str] = None) -> Optional[str]:
+    """A warning line for the site-level gap, or ``None`` when there is none.
+
+    Args:
+        diff: The result of :func:`compare_site_scope`.
+        source_url: The *source* site's URL, so the note says which site is short.
+    """
+    if diff.is_empty:
+        return None
+    parts: List[str] = []
+    if diff.missing_web_features:
+        parts.append(f"{len(diff.missing_web_features)} web feature(s): {_sample_names(diff.missing_web_features)}")
+    if diff.missing_site_features:
+        parts.append(
+            f"{len(diff.missing_site_features)} site-collection feature(s): {_sample_names(diff.missing_site_features)}"
+        )
+    if diff.regional:
+        parts.append(f"regional settings differ ({_regional_note(diff.regional)})")
+    return (
+        f"site scope is not replayed: the target of {source_url or 'this web'} lacks "
+        + "; ".join(parts)
+        + " — activating a feature changes what the site can do and is not undone by re-running the "
+        "migration, and regional settings have no working REST write path, so both are reported; "
+        "activate the missing features out of band (Enable-SPFeature) if the site depends on them"
+    )

office365/migration/sharepoint/site_settings.py

@@ -0,0 +1,196 @@
+"""Copy the web-scope site settings a client-side migration can carry.
+
+Replaying a list's structure reproduces its columns, content types and views —
+never the web that hosts them, so a migrated site would otherwise keep the
+*target* web's identity. Two of those settings are plain writable strings over
+REST and are what a user actually sees (site header, search results, the site
+card), so they are copied rather than left silently source-specific:
+
+* ``Title``
+* ``Description``
+
+Only **differing** values are written: a blind MERGE of an already-matching
+setting is not harmless (it bumps the web's metadata and, for some properties,
+re-triggers server-side side effects), and it would make every re-run look like a
+change. The copy is therefore idempotent by construction.
+
+What this module deliberately does *not* carry is named instead of being implied
+away (in the docs, and in the ``site_settings`` fidelity dimension's note):
+
+* **branding** — master page, theme, `SiteLogoUrl`, alternate CSS. Those are
+  carried by :mod:`office365.migration.sharepoint.branding` instead, whose rules
+  are different enough (path rebasing, assets that may not exist on the target) to
+  keep it a separate concern.
+* **site-collection and regional settings** — time zone, locale, quotas,
+  sharing capability, hub association. REST exposes no working write path for
+  them (setting a `TimeZone` id does not change the web's zone), so they are not
+  attempted.
+
+The mode vocabulary is the SPMT-flavoured string on
+:attr:`~office365.migration.settings.MigrationSettings.migrate_site_settings`:
+``PRESERVE_ALL_SETTINGS`` (copy the settings above) or ``NONE`` (leave the target
+web alone). An unrecognized value raises rather than silently doing nothing.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from office365.sharepoint.webs.web import Web
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "SITE_SETTINGS_PRESERVE",
+    "SITE_SETTINGS_SKIP",
+    "WebSettings",
+    "WebSettingsReport",
+    "apply_web_settings",
+    "parse_site_settings_mode",
+    "verify_web_settings",
+]
+
+#: Copy the web settings this module carries (the ``migrate_site_settings`` default).
+SITE_SETTINGS_PRESERVE = "PRESERVE_ALL_SETTINGS"
+#: Leave the target web's own settings untouched.
+SITE_SETTINGS_SKIP = "NONE"
+
+_MODES: Dict[str, bool] = {SITE_SETTINGS_PRESERVE: True, SITE_SETTINGS_SKIP: False}
+
+#: The web properties a copy carries. Both are plain strings on ``SP.Web``.
+_CARRIED = ("Title", "Description")
+
+
+def parse_site_settings_mode(mode: Optional[str]) -> bool:
+    """Whether ``mode`` asks for the site settings to be copied.
+
+    Args:
+        mode: The ``migrate_site_settings`` value (``None`` means "not set", which
+            preserves, matching the settings default).
+
+    Returns:
+        ``True`` to copy the carried settings, ``False`` to leave the target alone.
+
+    Raises:
+        ValueError: If the value is not one of the supported modes — a typo must
+            not silently disable (or enable) the copy.
+    """
+    if mode is None:
+        return True
+    key = str(mode).strip().upper()
+    if key not in _MODES:
+        raise ValueError(f"unknown migrate_site_settings {mode!r}; expected one of {sorted(_MODES)}")
+    return _MODES[key]
+
+
+@dataclass(frozen=True)
+class WebSettings:
+    """The web-scope settings a copy carries, read from one projected GET."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+
+    @classmethod
+    def capture(cls, web: "Web") -> "WebSettings":
+        """Read a web's carried settings (one GET projecting ``Title``/``Description``)."""
+        properties = web.select(list(_CARRIED)).get().execute_query().properties
+        return cls(title=properties.get("Title"), description=properties.get("Description"))
+
+    def values(self) -> List[tuple[str, Optional[str]]]:
+        """The carried settings as ``(REST property name, value)`` pairs."""
+        return [("Title", self.title), ("Description", self.description)]
+
+    def changed(self, target: "WebSettings") -> Dict[str, str]:
+        """The properties whose value differs from ``target`` (never blank differences).
+
+        A web always reports a ``Title``, so an unset value is written as an empty
+        string rather than as ``null`` — the server rejects a null for these.
+        """
+        current = {"Title": target.title, "Description": target.description}
+        changes: Dict[str, str] = {}
+        for name, value in self.values():
+            if (value or "") == (current[name] or ""):
+                continue
+            changes[name] = value if value is not None else ""
+        return changes
+
+
+@dataclass
+class WebSettingsReport:
+    """What a web-settings copy wrote — empty ``applied`` when nothing differed."""
+
+    url: str
+    applied: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def changed(self) -> bool:
+        """Whether the copy wrote anything at all."""
+        return bool(self.applied)
+
+    def summary(self) -> str:
+        """A one-line note for the session's warnings (empty when nothing was written)."""
+        if not self.applied:
+            return ""
+        names = ", ".join(sorted(self.applied))
+        return f"site settings: copied {names} onto {self.url}"
+
+
+def _web_url(web: "Web") -> str:
+    """A web's absolute URL, falling back to the site URL of its context.
+
+    A projected read (``select(["Title", "Description"]).get()``) replaces the
+    loaded properties with the ones it asked for, so ``Url`` may be gone by the
+    time a note needs it — the context still knows which site the web belongs to.
+    """
+    for name in ("Url", "ServerRelativeUrl"):
+        value = web.get_property(name)
+        if value:
+            return str(value)
+    return str(getattr(getattr(web, "context", None), "base_url", "") or "")
+
+
+def apply_web_settings(source_web: "Web", target_web: "Web", *, preserve: bool = True) -> WebSettingsReport:
+    """Copy the carried web settings from ``source_web`` onto ``target_web``.
+
+    Reads both sides (one projected GET each), writes only the properties that
+    differ (one MERGE on the target web), so a re-run is a no-op.
+
+    Args:
+        source_web: The source web to read the settings from.
+        target_web: The target web to write them to.
+        preserve: ``False`` leaves the target web untouched.
+    """
+    url = _web_url(target_web)
+    if not preserve:
+        return WebSettingsReport(url=url)
+    changes = WebSettings.capture(source_web).changed(WebSettings.capture(target_web))
+    if not changes:
+        return WebSettingsReport(url=url)
+    for name, value in changes.items():
+        target_web.set_property(name, value)
+    target_web.update().execute_query()
+    report = WebSettingsReport(url=url, applied=dict(changes))
+    logger.info(report.summary())
+    return report
+
+
+def verify_web_settings(source_web: "Web", target_web: "Web") -> List[str]:
+    """Reconcile the carried web settings (read-only; one finding per property).
+
+    Args:
+        source_web: The source web that was copied.
+        target_web: The target web to check.
+    """
+    source = WebSettings.capture(source_web)
+    target = WebSettings.capture(target_web)
+    url = _web_url(target_web)
+    notes: List[str] = []
+    for name, value in source.values():
+        current = dict(target.values())[name]
+        if (value or "") == (current or ""):
+            continue
+        notes.append(f"site settings: {url} {name} is {current!r}, source has {value!r}")
+    return notes

office365/migration/sharepoint/site_verify.py

@@ -0,0 +1,207 @@
+"""Reconcile a migrated web against its source in one read-only report.
+
+Each web-scope concern the whole-site resolver touches has its own verifier —
+:func:`verify_web_settings`, :func:`verify_web_branding`,
+:func:`compare_web_scope_structure`, :func:`compare_site_scope`,
+:func:`verify_navigation`, :func:`verify_page_copy`, :func:`verify_site_security`
+and per list :func:`verify_list_structure`. Calling them one by one is what the
+example did, which makes it easy to forget one and impossible to answer "did this
+web migrate?" with a single value.
+
+:func:`verify_site` folds them into a :class:`SiteVerificationReport`: one
+``ok`` flag, one ``summary()`` line, and a JSON-serializable ``to_dict()`` for an
+evidence pack. It performs **no writes** — every check issues GETs only.
+
+Only the checks a run actually claims are run (a run without
+``preserve_permissions`` does not report missing site groups as a mismatch), and a
+check that *could not* run — an access denied, a web that cannot be read — lands in
+``unverifiable`` rather than in the findings, so a partial verification never reads
+as a pass.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional, Tuple
+
+from office365.migration.sharepoint.branding import verify_web_branding
+from office365.migration.sharepoint.navigation import verify_navigation
+from office365.migration.sharepoint.pages import verify_page_copy
+from office365.migration.sharepoint.security import verify_list_security, verify_site_security
+from office365.migration.sharepoint.site_scope import compare_site_scope, site_scope_note
+from office365.migration.sharepoint.site_settings import verify_web_settings
+from office365.migration.sharepoint.structure import (
+    compare_web_scope_structure,
+    web_scope_note,
+)
+from office365.migration.sharepoint.verify import StructureReport, verify_list_structure
+
+if TYPE_CHECKING:
+    from office365.sharepoint.client_context import ClientContext
+    from office365.sharepoint.lists.list import List as SPList
+    from office365.sharepoint.webs.web import Web
+
+__all__ = ["LIST_SECURITY", "SITE_SCOPE", "SiteVerificationReport", "WEB_SCOPE_STRUCTURE", "verify_site"]
+
+WEB_SCOPE_STRUCTURE = "web-scope structure"
+
+#: Check name for a list's own ACL (as opposed to the web's or an item's).
+LIST_SECURITY = "list security"
+
+#: Check name for the site-level scope a migration never replays (features, regional settings).
+SITE_SCOPE = "site scope"
+
+
+def _web_url(web: "Web") -> str:
+    """The web's URL, falling back to the context's base URL (a projected read drops it)."""
+    for getter in ("url", "server_relative_url"):
+        value = getattr(web, getter, None)
+        if value:
+            return str(value)
+    context = getattr(web, "context", None)
+    return str(getattr(context, "base_url", "") or "")
+
+
+def _site_scope_findings(source_context: "ClientContext", target_context: "ClientContext") -> List[str]:
+    """The features/regional settings the target lacks, as notes (empty = nothing missing)."""
+    note = site_scope_note(compare_site_scope(source_context, target_context), _web_url(source_context.web))
+    return [note] if note else []
+
+
+def _web_scope_findings(source_web: "Web", target_web: "Web") -> List[str]:
+    """The web-scope structure the target lacks, as notes (empty = nothing missing)."""
+    note = web_scope_note(compare_web_scope_structure(source_web, target_web), _web_url(source_web))
+    return [note] if note else []
+
+
+@dataclass
+class SiteVerificationReport:
+    """What a migrated web still lacks, per dimension, in one place."""
+
+    url: str = ""
+    lists: List[StructureReport] = field(default_factory=list)
+    checked: List[str] = field(default_factory=list)
+    findings: Dict[str, List[str]] = field(default_factory=dict)
+    unverifiable: List[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """Whether any check contradicted the target (a check that could not run does not)."""
+        return not self.findings and all(report.ok for report in self.lists)
+
+    @property
+    def complete(self) -> bool:
+        """Whether every requested check actually ran."""
+        return not self.unverifiable
+
+    @property
+    def issues(self) -> List[str]:
+        """Every finding, flattened (dimension names are already in the notes)."""
+        notes = [note for notes in self.findings.values() for note in notes]
+        for report in self.lists:
+            if not report.ok:
+                notes.append(report.summary())
+        return notes
+
+    def summary(self) -> str:
+        """One line: the verdict, then the per-dimension finding counts."""
+        status = "OK" if self.ok else "MISMATCH"
+        if not self.complete:
+            status = f"PARTIAL {status}" if self.findings else "PARTIAL"
+        parts = [f"{name}: {len(self.findings.get(name, []))}" for name in self.checked]
+        if self.lists:
+            failed = sum(1 for report in self.lists if not report.ok)
+            parts.insert(0, f"lists: {len(self.lists)} ({failed} with issues)")
+        detail = ", ".join(parts) if parts else "nothing to check"
+        url = f" {self.url}" if self.url else ""
+        return f"{status} |{url} | {detail}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """A JSON-serializable form (for reports/evidence packs)."""
+        return {
+            "url": self.url,
+            "ok": self.ok,
+            "complete": self.complete,
+            "checked": list(self.checked),
+            "lists": [report.to_dict() for report in self.lists],
+            "findings": {name: list(notes) for name, notes in self.findings.items()},
+            "unverifiable": list(self.unverifiable),
+        }
+
+
+def verify_site(
+    source_context: "ClientContext",
+    target_context: "ClientContext",
+    *,
+    lists: Optional[Iterable[Tuple["SPList", "SPList"]]] = None,
+    structure: bool = True,
+    web_scope_structure: bool = True,
+    navigation: bool = False,
+    pages: bool = False,
+    security: bool = False,
+    settings: bool = True,
+    branding: bool = True,
+    site_scope: bool = True,
+) -> SiteVerificationReport:
+    """Verify a migrated web against its source (read-only).
+
+    Args:
+        source_context: The source web's context.
+        target_context: The target web's context.
+        lists: ``(source_list, target_list)`` pairs to reconcile structurally. Only
+            passed when the caller wants the container compared too; capture is
+            performed here (:func:`verify_list_structure`).
+        structure: Whether to reconcile the ``lists`` pairs (ignored without pairs).
+        web_scope_structure: Report the site columns/content types the target web
+            does not define (structure replay is per list, so this is a note about
+            web scope, not a per-list failure).
+        navigation: Reconcile quick launch and top navigation.
+        pages: Reconcile modern site page copies.
+        security: Reconcile custom site groups, web role assignments and each
+            list's own ACL (a source list that restricts access the target list
+            does not is the finding that matters).
+        settings: Reconcile the web's ``Title``/``Description``.
+        branding: Reconcile the web's master page, logo, alternate CSS and theme
+            folder (compared source-path-rebased).
+        site_scope: Report the features activated on the source site (web and site
+            collection) that the target does not have, and the regional settings
+            that differ. Read-only: neither is replayed by a migration.
+
+    Returns:
+        A :class:`SiteVerificationReport`; a check that raises is recorded in
+        ``unverifiable`` instead of aborting the others.
+    """
+    source_web: "Web" = source_context.web
+    target_web: "Web" = target_context.web
+    report = SiteVerificationReport(url=_web_url(target_web))
+
+    if lists is not None and structure:
+        for source_list, target_list in lists:
+            try:
+                report.lists.append(verify_list_structure(source_list, target_list))
+            except Exception as e:  # noqa: BLE001 — one unreadable list must not hide the rest
+                report.unverifiable.append(f"list structure for {getattr(source_list, 'title', '?')}: {e}")
+
+    checks: Dict[str, Tuple[Callable[[], List[str]], bool]] = {
+        "settings": (lambda: verify_web_settings(source_web, target_web), settings),
+        "branding": (lambda: verify_web_branding(source_web, target_web), branding),
+        WEB_SCOPE_STRUCTURE: (lambda: _web_scope_findings(source_web, target_web), web_scope_structure),
+        SITE_SCOPE: (lambda: _site_scope_findings(source_context, target_context), site_scope),
+        "navigation": (lambda: verify_navigation(source_web, target_web), navigation),
+        "pages": (lambda: verify_page_copy(source_web, target_web), pages),
+        "security": (lambda: verify_site_security(source_web, target_web), security),
+        # A list's own ACL is a separate scope from the web's (and from an item's).
+        LIST_SECURITY: (lambda: verify_list_security(source_web, target_web), security),
+    }
+    for name, (run, enabled) in checks.items():
+        if not enabled:
+            continue
+        report.checked.append(name)
+        try:
+            notes = run()
+        except Exception as e:  # noqa: BLE001 — a check that cannot run is reported, not raised
+            report.unverifiable.append(f"{name}: {e}")
+            continue
+        if notes:
+            report.findings[name] = list(notes)
+    return report