Skip to content

teng-lin/notebooklm-py

notebooklm

Verified

Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.

FileKindSize
SKILL.mdskill md16.0 KB
examples/bulk-import.pyscript3.4 KB
examples/chat.pyscript6.9 KB
examples/notes.pyscript9.8 KB
examples/quickstart.pyscript2.3 KB
examples/refresh_browser_cookies.pyscript2.9 KB
examples/research-to-podcast.pyscript3.2 KB
examples/video.pyscript5.9 KB
scripts/__init__.pyscript73 B
scripts/_ci_e2e_notebooks.pyscript19.0 KB
scripts/_ci_progress.pyscript2.5 KB
scripts/_ci_rpc_progress.pyscript7.5 KB
scripts/_live_auth_scenarios/__init__.pyscript2.6 KB
scripts/_live_auth_scenarios/_contract.pyscript1.9 KB
scripts/_live_auth_scenarios/browser_refresh.pyscript3.1 KB
scripts/_live_auth_scenarios/crash_safe_writer.pyscript1.9 KB
scripts/_live_auth_scenarios/master_token_recovery.pyscript3.3 KB
scripts/_live_auth_scenarios/mcp_recovery.pyscript3.0 KB
scripts/_live_auth_scenarios/rest_recovery.pyscript5.9 KB
scripts/_live_auth_scenarios/sibling_concurrent_reload.pyscript3.9 KB
scripts/_live_auth_scenarios/storage_reload.pyscript2.9 KB
scripts/_onetime_rescrub_cookies.pyscript6.6 KB
scripts/_onetime_retarget_cassette_hosts.pyscript8.5 KB
scripts/_strip_audit_refs.pyscript15.9 KB
scripts/_tracked_files.pyscript872 B
scripts/aggregate_ci_e2e_outcomes.pyscript10.8 KB
scripts/android_grpc_canary.pyscript26.6 KB
scripts/api-compat-allowlist.jsonconfig163 B
scripts/audit_auth_import_graph.pyscript7.5 KB
scripts/audit_auth_patch_sites.pyscript83.6 KB
scripts/audit_auth_shared_mutations.pyscript41.7 KB
scripts/audit_backend_coupling.pyscript32.8 KB
scripts/audit_public_api_compat.pyscript47.4 KB
scripts/audit_test_suite.pyscript10.7 KB
scripts/capture_mobile_grpc.jsscript5.1 KB
scripts/capture_rpc_registry.pyscript44.5 KB
scripts/check_action_pinning.pyscript6.7 KB
scripts/check_auth_behavior_scenario_policy.pyscript37.1 KB
scripts/check_auth_coverage_delta.pyscript23.2 KB
scripts/check_auth_lifecycle_cleanup_policy.pyscript11.7 KB
scripts/check_base_wheel.pyscript6.3 KB
scripts/check_ci_install_parity.pyscript8.8 KB
scripts/check_claude_md_freshness.pyscript8.0 KB
scripts/check_coverage_thresholds.pyscript8.4 KB
scripts/check_deprecation_targets.pyscript33.1 KB
scripts/check_docs_module_refs.pyscript14.4 KB
scripts/check_rpc_health.pyscript112.0 KB
scripts/check_workflow_permissions.pyscript5.3 KB
scripts/check_workflow_secret_gates.pyscript40.4 KB
scripts/decode_mobile_grpc.pyscript7.2 KB
scripts/diagnose_get_notebook.pyscript9.1 KB
scripts/extract_blutter_grpc_signatures.pyscript7.6 KB
scripts/live_auth_matrix.pyscript40.2 KB
scripts/manage_ci_e2e_notebooks.pyscript67.4 KB
scripts/materialize_ci_auth.pyscript8.0 KB
scripts/mcp_live_smoke.pyexecutablescript224 B
scripts/parse_pbenums.pyscript8.6 KB
scripts/parse_pbschema.pyscript11.8 KB
scripts/regen_baselines.pyscript2.7 KB
scripts/regenerate_android_protos.pyscript16.3 KB
scripts/rescrub-cassettes.pyscript13.3 KB
scripts/scrub_rpc_har.pyscript9.4 KB
scripts/select_ci_account.pyscript4.8 KB
scripts/stress_fault_server.pyscript20.6 KB
scripts/test_taxonomy_inventory.pyscript16.1 KB
scripts/verify_ci_artifacts.pyscript35.3 KB

scripts/check_deprecation_targets.py

View on GitHub
"""Release gate: a deprecation must never name the version shipping it.

The recurring defect (issue #1214): a ``DeprecationWarning`` message says the
feature "will be removed in vX.Y.Z" while ``pyproject.toml`` is *currently at*
vX.Y.Z. Shipping that release publishes a deprecation whose stated removal
target is the release itself — the shim is simultaneously "still here" and
"already past its removal version", which is incoherent and means the shim
should have been deleted (or the target bumped) before the release.

This gate scans every ``warnings.warn(...)`` / ``DeprecationWarning(...)``
message string under ``src/notebooklm/`` and fails if any names the version
in ``pyproject.toml`` as a *removal target* (``removed in vX.Y.Z`` /
``will be removed in vX.Y.Z`` / ``removal in vX.Y.Z``). It also parses the
immutable ``DEPRECATION_SPECS`` auth-storage table and its literal registered
calls without importing package code. Keys/callsites must match, versions must
be literal semantic versions, and public replacements must resolve structurally.
It is wired alongside the other ``scripts/check_*.py`` static gates and is also
exercised by ``tests/unit/test_check_deprecation_targets.py``.

Allowlist
---------
``LAPSED_ALLOWLIST`` holds deprecation sites whose stated removal target has
*already lapsed* and whose shim removal is tracked separately. They are
allowlisted (keyed by file + the offending version) with the tracking issue so
this gate does not block the current release; once the tracking PR deletes the
shim, the matching site disappears and the entry should be dropped (a stale
allowlist entry is reported, keeping the list tightening).

Usage::

    python scripts/check_deprecation_targets.py
    python scripts/check_deprecation_targets.py --pyproject path/to/pyproject.toml

Exit codes:
    0  No deprecation message names the current release as its removal target
       (modulo documented allowlist entries), and the registry is coherent.
    1  One or more offending messages or registry errors were found.
    2  Argument / parse error (missing pyproject, unreadable version, etc.).
"""

from __future__ import annotations

import argparse
import ast
import re
import sys
from pathlib import Path

if sys.version_info >= (3, 11):
    import tomllib
else:  # pragma: no cover - 3.10 path
    try:
        import tomli as tomllib  # type: ignore[import-not-found,no-redef]
    except ImportError:
        print(
            "tomli is required on Python 3.10. Install with: uv pip install tomli",
            file=sys.stderr,
        )
        sys.exit(2)

REPO_ROOT = Path(__file__).resolve().parents[1]
SRC_ROOT = REPO_ROOT / "src" / "notebooklm"

# Calls whose first string argument is treated as a user-facing deprecation
# message:
#   * ``warnings.warn`` — the canonical attribute-access form.
#   * bare ``warn`` — the ``from warnings import warn; warn(...)`` form.
#   * ``DeprecationWarning(...)`` — a constructed/raised warning instance.
# The bare ``warn`` is broad on purpose (a release gate prefers a false
# positive over a missed deprecation); the version-naming regex in
# ``_removal_pattern`` keeps incidental ``warn()`` calls from matching unless
# they actually name the shipping version as a removal target.
_DEPRECATION_CALL_NAMES = frozenset({"warnings.warn", "warn", "DeprecationWarning"})
_REGISTERED_EMITTER = "warn_registered_deprecation"
_SPEC_TABLE = "DEPRECATION_SPECS"
_SPEC_FIELDS = ("key", "message", "category", "replacement", "since", "removal", "stacklevel")
_REGISTERED_SPEC_KEYS = frozenset(
    {
        "artifact_ambiguous_absence",
        "artifact_raw_download_prefetch",
        "mind_map_legacy_terminal_hydration",
        "auth_tokens_flat_cookies",
        "auth_tokens_from_storage",
        "auth_tokens_replace_cookie_jar",
        "auth_tokens_sync_storage_construction",
        "artifact_from_api_response",
        "artifact_from_mind_map",
        "artifact_poll_absence_thresholds",
        "artifact_poll_follower_callback",
        "artifact_poll_follower_options",
        "client_rpc_call_android",
        "client_rpc_call_web",
        "client_legacy_constructor_options",
        "client_legacy_from_storage_options",
        "collection_from_api_response",
        "label_from_api_response",
        "mcp_confirmed_name_references",
        "notebook_from_api_response",
        "share_status_from_api_response",
        "shared_user_from_api_response",
        "source_from_api_response",
        "source_from_row",
    }
)
_SEMVER = re.compile(r"^[0-9]+\.[0-9]+(?:\.[0-9]+)?$")


class _Offender:
    __slots__ = ("path", "lineno", "version", "snippet")

    def __init__(self, path: str, lineno: int, version: str, snippet: str) -> None:
        self.path = path
        self.lineno = lineno
        self.version = version
        self.snippet = snippet

    @property
    def key(self) -> tuple[str, str]:
        return (self.path, self.version)


# ---------------------------------------------------------------------------
# Allowlist — deprecation sites whose stated removal target has already lapsed.
#
# These are removed by a separate tracking PR; allowlisting them (with the
# issue reference) keeps this gate from blocking the current release while the
# shim deletion lands. Keyed by (relative-posix-path, offending-version).
# ---------------------------------------------------------------------------
class _LapsedEntry:
    __slots__ = ("path", "version", "issue", "reason")

    def __init__(self, path: str, version: str, issue: int, reason: str) -> None:
        self.path = path
        self.version = version
        self.issue = issue
        self.reason = reason

    @property
    def key(self) -> tuple[str, str]:
        return (self.path, self.version)


LAPSED_ALLOWLIST: tuple[_LapsedEntry, ...] = ()

_ALLOWLIST_BY_KEY = {entry.key: entry for entry in LAPSED_ALLOWLIST}


def _read_version(pyproject: Path) -> str:
    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
    try:
        version = data["project"]["version"]
    except (KeyError, TypeError) as exc:  # pragma: no cover - malformed pyproject
        raise KeyError("project.version not found in pyproject.toml") from exc
    if not isinstance(version, str):  # pragma: no cover - defensive
        raise TypeError(f"project.version is not a string: {version!r}")
    return version


def _removal_pattern(version: str) -> re.Pattern[str]:
    """Match removal language naming *version* (with or without a ``v`` prefix).

    Examples matched (version == ``0.6.0``)::

        will be removed in v0.6.0
        removed in 0.6.0
        removal in v0.6.0
        scheduled for removal in 0.6.0
    """
    escaped = re.escape(version)
    return re.compile(
        r"(?:will\s+be\s+)?remov(?:ed|al)\s+in\s+v?" + escaped + r"\b",
        re.IGNORECASE,
    )


def _flatten_message(node: ast.AST) -> str:
    """Best-effort flatten of a (possibly f-string / concatenated) message arg.

    Concatenated string literals (``"a" "b"``) parse as a single ``Constant``;
    implicit ``+`` concatenation and f-strings need walking. We collect every
    string constant reachable from the first argument so split removal phrases
    like ``"... removed in " f"v{X}"`` are not the concern here (the version is
    a literal in the offending sites), but multi-literal messages still match.
    """
    parts: list[str] = []
    for child in ast.walk(node):
        if isinstance(child, ast.Constant) and isinstance(child.value, str):
            parts.append(child.value)
    return " ".join(parts)


def _call_name(node: ast.AST) -> str:
    if isinstance(node, ast.Name):
        return node.id
    if isinstance(node, ast.Attribute):
        base = _call_name(node.value)
        return f"{base}.{node.attr}" if base else node.attr
    return ""


def _target_name(node: ast.Assign | ast.AnnAssign) -> str | None:
    targets = node.targets if isinstance(node, ast.Assign) else [node.target]
    names = [target.id for target in targets if isinstance(target, ast.Name)]
    return names[0] if len(names) == 1 else None


def _literal(node: ast.AST, field: str, problems: list[str]) -> object | None:
    if isinstance(node, ast.Constant) and isinstance(node.value, (str, int)):
        return node.value
    problems.append(f"{field} must be a string/integer literal")
    return None


def _spec_arguments(node: ast.Call, problems: list[str]) -> dict[str, ast.AST]:
    if len(node.args) > len(_SPEC_FIELDS):
        problems.append("DeprecationSpec has too many positional arguments")
        return {}
    values = dict(zip(_SPEC_FIELDS, node.args, strict=False))
    for keyword in node.keywords:
        if keyword.arg is None:
            problems.append("DeprecationSpec may not use ** expansion")
            continue
        if keyword.arg not in _SPEC_FIELDS:
            problems.append(f"DeprecationSpec has unknown field {keyword.arg!r}")
            continue
        if keyword.arg in values:
            problems.append(f"DeprecationSpec repeats field {keyword.arg!r}")
            continue
        values[keyword.arg] = keyword.value
    missing = sorted(set(_SPEC_FIELDS) - values.keys())
    if missing:
        problems.append(f"DeprecationSpec is missing fields: {', '.join(missing)}")
    return values


def _statement_binds_name(statement: ast.stmt, name: str) -> bool:
    """Conservatively detect an effective or conditional module-name binding."""
    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
        return statement.name == name
    if isinstance(statement, (ast.Import, ast.ImportFrom)):
        return any((alias.asname or alias.name.split(".")[0]) == name for alias in statement.names)
    return any(
        isinstance(node, ast.Name)
        and node.id == name
        and isinstance(getattr(node, "ctx", None), (ast.Store, ast.Del))
        for node in ast.walk(statement)
    )


def _effective_top_level_binding(module: ast.Module, name: str) -> ast.stmt | None:
    binding = None
    for statement in module.body:
        if _statement_binds_name(statement, name):
            binding = statement
    return binding


def _eager_statement_references_name(statement: ast.stmt, name: str) -> bool:
    """Check module-executed parts while excluding deferred function bodies."""
    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
        eager_nodes: list[ast.AST] = [*statement.decorator_list, *statement.args.defaults]
        eager_nodes.extend(default for default in statement.args.kw_defaults if default is not None)
        eager_nodes.extend(
            annotation
            for argument in [
                *statement.args.posonlyargs,
                *statement.args.args,
                *statement.args.kwonlyargs,
            ]
            if (annotation := argument.annotation) is not None
        )
        if statement.args.vararg is not None and statement.args.vararg.annotation is not None:
            eager_nodes.append(statement.args.vararg.annotation)
        if statement.args.kwarg is not None and statement.args.kwarg.annotation is not None:
            eager_nodes.append(statement.args.kwarg.annotation)
        if statement.returns is not None:
            eager_nodes.append(statement.returns)
        eager_nodes.extend(getattr(statement, "type_params", ()))
        return any(
            isinstance(node, ast.Name) and node.id == name
            for eager in eager_nodes
            for node in ast.walk(eager)
        )
    return any(isinstance(node, ast.Name) and node.id == name for node in ast.walk(statement))


def _canonical_lazy_export_map(module: ast.Module) -> str | None:
    """Return the literal map used by the canonical module ``__getattr__`` shape."""
    hook = _effective_top_level_binding(module, "__getattr__")
    if not isinstance(hook, ast.FunctionDef) or hook.decorator_list:
        return None
    args = hook.args
    positional = [*args.posonlyargs, *args.args]
    if (
        len(positional) != 1
        or args.vararg is not None
        or args.kwarg is not None
        or args.kwonlyargs
        or args.defaults
    ):
        return None
    body = hook.body
    if (
        body
        and isinstance(body[0], ast.Expr)
        and isinstance(body[0].value, ast.Constant)
        and isinstance(body[0].value.value, str)
    ):
        body = body[1:]
    if len(body) != 4:
        return None

    lookup, missing_guard, unpack, returned = body
    if (
        not isinstance(lookup, ast.Assign)
        or len(lookup.targets) != 1
        or not isinstance(lookup.targets[0], ast.Name)
        or not isinstance(lookup.value, ast.Call)
        or not isinstance(lookup.value.func, ast.Attribute)
        or lookup.value.func.attr != "get"
        or not isinstance(lookup.value.func.value, ast.Name)
        or len(lookup.value.args) != 1
        or not isinstance(lookup.value.args[0], ast.Name)
        or lookup.value.args[0].id != positional[0].arg
        or lookup.value.keywords
    ):
        return None
    value_name = lookup.targets[0].id
    map_name = lookup.value.func.value.id
    if not map_name.startswith("_LAZY") or not map_name.endswith("EXPORTS"):
        return None
    if (
        not isinstance(missing_guard, ast.If)
        or missing_guard.orelse
        or len(missing_guard.body) != 1
        or not isinstance(missing_guard.body[0], ast.Raise)
        or not isinstance(missing_guard.test, ast.Compare)
        or not isinstance(missing_guard.test.left, ast.Name)
        or missing_guard.test.left.id != value_name
        or len(missing_guard.test.ops) != 1
        or not isinstance(missing_guard.test.ops[0], ast.Is)
        or len(missing_guard.test.comparators) != 1
        or not isinstance(missing_guard.test.comparators[0], ast.Constant)
        or missing_guard.test.comparators[0].value is not None
    ):
        return None
    if (
        not isinstance(unpack, ast.Assign)
        or len(unpack.targets) != 1
        or not isinstance(unpack.targets[0], (ast.Tuple, ast.List))
        or len(unpack.targets[0].elts) != 2
        or not all(isinstance(item, ast.Name) for item in unpack.targets[0].elts)
        or not isinstance(unpack.value, ast.Name)
        or unpack.value.id != value_name
    ):
        return None
    module_var, attribute_var = (item.id for item in unpack.targets[0].elts)
    local_names = {positional[0].arg, value_name, module_var, attribute_var}
    if len(local_names) != 4 or local_names & {map_name, "importlib", "getattr"}:
        return None
    if not isinstance(returned, ast.Return) or not isinstance(returned.value, ast.Call):
        return None
    outer = returned.value
    if (
        not isinstance(outer.func, ast.Name)
        or outer.func.id != "getattr"
        or len(outer.args) != 2
        or outer.keywords
        or not isinstance(outer.args[0], ast.Call)
        or not isinstance(outer.args[1], ast.Name)
        or outer.args[1].id != attribute_var
    ):
        return None
    importer = outer.args[0]
    if (
        not isinstance(importer.func, ast.Attribute)
        or not isinstance(importer.func.value, ast.Name)
        or importer.func.value.id != "importlib"
        or importer.func.attr != "import_module"
        or len(importer.args) != 1
        or not isinstance(importer.args[0], ast.Name)
        or importer.args[0].id != module_var
        or importer.keywords
    ):
        return None
    importlib_binding = _effective_top_level_binding(module, "importlib")
    if not (
        isinstance(importlib_binding, ast.Import)
        and len(importlib_binding.names) == 1
        and importlib_binding.names[0].name == "importlib"
        and importlib_binding.names[0].asname is None
    ):
        return None
    if _effective_top_level_binding(module, "getattr") is not None:
        return None
    return map_name


def _literal_lazy_exports(module: ast.Module, map_name: str) -> dict[str, tuple[str, str]] | None:
    binding = _effective_top_level_binding(module, map_name)
    if (
        not isinstance(binding, ast.Assign)
        or len(binding.targets) != 1
        or not isinstance(binding.targets[0], ast.Name)
        or binding.targets[0].id != map_name
        or not isinstance(binding.value, ast.Call)
        or not isinstance(binding.value.func, ast.Name)
        or binding.value.func.id != "MappingProxyType"
        or len(binding.value.args) != 1
        or binding.value.keywords
        or not isinstance(binding.value.args[0], ast.Dict)
    ):
        return None
    proxy_binding = _effective_top_level_binding(module, "MappingProxyType")
    if not (
        isinstance(proxy_binding, ast.ImportFrom)
        and proxy_binding.level == 0
        and proxy_binding.module == "types"
        and len(proxy_binding.names) == 1
        and proxy_binding.names[0].name == "MappingProxyType"
        and proxy_binding.names[0].asname is None
    ):
        return None
    binding_index = module.body.index(binding)
    if module.body.index(proxy_binding) > binding_index:
        return None
    literal = binding.value.args[0]
    if len(literal.keys) != len(literal.values):
        return None
    for statement in module.body[binding_index + 1 :]:
        if _eager_statement_references_name(statement, map_name):
            return None
    exports: dict[str, tuple[str, str]] = {}
    for key, value in zip(literal.keys, literal.values, strict=False):
        if (
            not isinstance(key, ast.Constant)
            or not isinstance(key.value, str)
            or key.value in exports
            or not isinstance(value, ast.Tuple)
            or len(value.elts) != 2
            or not all(
                isinstance(item, ast.Constant) and isinstance(item.value, str)
                for item in value.elts
            )
        ):
            return None
        module_name, attribute = (item.value for item in value.elts)
        exports[key.value] = (module_name, attribute)
    return exports


def _find_public_symbol(
    module: ast.Module, name: str
) -> ast.AST | tuple[int, str | None, str] | None:
    for statement in module.body:
        if isinstance(statement, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
            if statement.name == name:
                return statement
        if isinstance(statement, ast.ImportFrom):
            for alias in statement.names:
                if (alias.asname or alias.name) == name:
                    return statement.level, statement.module, alias.name
    map_name = _canonical_lazy_export_map(module)
    exports = _literal_lazy_exports(module, map_name) if map_name is not None else None
    if exports is None or name not in exports:
        return None
    module_name, attribute = exports[name]
    return 0, module_name, attribute


def _module_source(module_parts: tuple[str, ...]) -> tuple[Path, bool] | None:
    """Return one unambiguous in-package module source and whether it is a package."""
    module_path = SRC_ROOT.joinpath(*module_parts)
    module_file = module_path.with_suffix(".py") if module_parts else SRC_ROOT / "__init__.py"
    package_file = module_path / "__init__.py" if module_parts else None
    candidates = [(module_file, False)]
    if package_file is not None:
        candidates.append((package_file, True))
    existing = [candidate for candidate in candidates if candidate[0].is_file()]
    if len(existing) != 1:
        return None
    return existing[0]


def _imported_module_parts(
    current_parts: tuple[str, ...],
    current_is_package: bool,
    level: int,
    imported_module: str | None,
) -> tuple[str, ...] | None:
    """Resolve an ``ImportFrom`` module relative to its containing package."""
    imported_parts = tuple(imported_module.split(".")) if imported_module else ()
    if level == 0:
        if not imported_parts or imported_parts[0] != "notebooklm":
            return None
        return imported_parts[1:]

    package_parts = current_parts if current_is_package else current_parts[:-1]
    parents_to_drop = level - 1
    if parents_to_drop > len(package_parts):
        return None
    if parents_to_drop:
        package_parts = package_parts[:-parents_to_drop]
    return package_parts + imported_parts


def _replacement_resolves(replacement: str) -> bool:
    """Resolve a dotted public target structurally, without importing package code."""
    parts = replacement.split(".")
    if len(parts) < 2 or parts[0] != "notebooklm" or any(not part for part in parts):
        return False

    # Prefer the longest concrete public module prefix.  Most historical
    # replacements start from a symbol re-exported by ``notebooklm.__init__``;
    # backend-selected raw replacements intentionally start from the public
    # ``notebooklm.raw`` module instead.
    module_parts: tuple[str, ...] = ()
    symbol_index = 1
    for index in range(len(parts) - 1, 1, -1):
        candidate = tuple(parts[1:index])
        if _module_source(candidate) is not None:
            module_parts = candidate
            symbol_index = index
            break
    symbol_name = parts[symbol_index]
    visited_reexports: set[tuple[tuple[str, ...], str]] = set()
    while True:
        visit = (module_parts, symbol_name)
        if visit in visited_reexports:
            return False
        visited_reexports.add(visit)

        source_info = _module_source(module_parts)
        if source_info is None:
            return False
        source, is_package = source_info
        module = ast.parse(source.read_text(encoding="utf-8"), filename=str(source))
        target = _find_public_symbol(module, symbol_name)
        if not isinstance(target, tuple):
            if target is None:
                return False
            break
        level, imported_module, symbol_name = target
        resolved_parts = _imported_module_parts(
            module_parts,
            is_package,
            level,
            imported_module,
        )
        if resolved_parts is None:
            return False
        module_parts = resolved_parts

    for attribute in parts[symbol_index + 1 :]:
        if not isinstance(target, ast.ClassDef):
            return False
        target = next(
            (
                statement
                for statement in target.body
                if (
                    isinstance(statement, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))
                    and statement.name == attribute
                )
                or (
                    isinstance(statement, ast.AnnAssign)
                    and isinstance(statement.target, ast.Name)
                    and statement.target.id == attribute
                )
            ),
            None,
        )
        if target is None:
            return False
    return True


def _version_key(version: str) -> tuple[int, ...]:
    parts = [int(part) for part in version.split(".")]
    while len(parts) > 1 and parts[-1] == 0:
        parts.pop()
    return tuple(parts)


def _registered_deprecation_problems(version: str) -> list[str]:
    """Validate the immutable spec table and its literal registered callsites."""
    spec_path = SRC_ROOT / "_deprecation.py"
    modules: list[tuple[Path, ast.Module]] = []
    calls: dict[str, list[str]] = {}
    problems: list[str] = []
    for path in sorted(SRC_ROOT.rglob("*.py")):
        module = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        modules.append((path, module))
        for node in ast.walk(module):
            if not isinstance(node, ast.Call):
                continue
            if _call_name(node.func).rsplit(".", 1)[-1] != _REGISTERED_EMITTER:
                continue
            rel = path.relative_to(REPO_ROOT).as_posix()
            detail_keywords = [keyword for keyword in node.keywords if keyword.arg == "detail"]
            if (
                len(node.args) != 1
                or len(detail_keywords) != len(node.keywords)
                or len(detail_keywords) > 1
            ):
                problems.append(
                    f"{rel}:{node.lineno}: registered call must have one literal key and "
                    "at most one detail= keyword"
                )
                continue
            key = _literal(node.args[0], "registered deprecation key", problems)
            if not isinstance(key, str):
                continue
            calls.setdefault(key, []).append(f"{rel}:{node.lineno}")

    # Synthetic inline-warning tests intentionally omit the registry module.
    # A real registered call without its table is still a hard failure.
    if not spec_path.is_file():
        if calls:
            problems.append(f"{_SPEC_TABLE} is missing")
        return problems

    spec_module = next(module for path, module in modules if path == spec_path)
    assignments = [
        node
        for node in spec_module.body
        if isinstance(node, (ast.Assign, ast.AnnAssign)) and _target_name(node) == _SPEC_TABLE
    ]
    if len(assignments) != 1:
        problems.append(f"{_SPEC_TABLE} must have exactly one assignment")
        return problems
    value = assignments[0].value
    if (
        not isinstance(value, ast.Call)
        or _call_name(value.func) != "MappingProxyType"
        or len(value.args) != 1
        or value.keywords
        or not isinstance(value.args[0], ast.Dict)
    ):
        problems.append(f"{_SPEC_TABLE} must be one literal MappingProxyType dictionary")
        return problems

    specs: dict[str, dict[str, object]] = {}
    table = value.args[0]
    for key_node, spec_node in zip(table.keys, table.values, strict=True):
        if key_node is None:
            problems.append(f"{_SPEC_TABLE} may not use ** expansion")
            continue
        table_key = _literal(key_node, "deprecation table key", problems)
        if not isinstance(table_key, str) or not table_key:
            problems.append("deprecation table key must be a non-empty string")
            continue
        if table_key in specs:
            problems.append(f"duplicate deprecation spec key: {table_key}")
            continue
        if not isinstance(spec_node, ast.Call) or _call_name(spec_node.func) != "DeprecationSpec":
            problems.append(f"{table_key}: value must be a literal DeprecationSpec call")
            continue
        arguments = _spec_arguments(spec_node, problems)
        if set(arguments) != set(_SPEC_FIELDS):
            continue
        parsed: dict[str, object] = {}
        for field in ("key", "message", "replacement", "since", "removal", "stacklevel"):
            parsed[field] = _literal(arguments[field], f"{table_key}.{field}", problems)
        category = arguments["category"]
        if not isinstance(category, ast.Name) or category.id != "DeprecationWarning":
            problems.append(f"{table_key}.category must be literal DeprecationWarning")
        parsed["category"] = "DeprecationWarning"
        specs[table_key] = parsed

    actual_keys = frozenset(specs)
    if actual_keys != _REGISTERED_SPEC_KEYS:
        problems.append(
            f"{_SPEC_TABLE} keys differ: expected {sorted(_REGISTERED_SPEC_KEYS)!r}, "
            f"got {sorted(actual_keys)!r}"
        )

    for table_key, spec in specs.items():
        if spec.get("key") != table_key:
            problems.append(f"{table_key}: table key and spec.key differ")
        message = spec.get("message")
        if not isinstance(message, str) or not message.strip():
            problems.append(f"{table_key}.message must be a non-empty string literal")
        replacement = spec.get("replacement")
        if not isinstance(replacement, str) or not replacement.strip():
            problems.append(f"{table_key}.replacement must be a non-empty string literal")
        elif not _replacement_resolves(replacement):
            problems.append(f"{table_key}.replacement does not resolve: {replacement}")
        for field in ("since", "removal"):
            field_value = spec.get(field)
            if not isinstance(field_value, str) or not _SEMVER.fullmatch(field_value):
                problems.append(f"{table_key}.{field} must be a literal semantic version")
        since = spec.get("since")
        removal = spec.get("removal")
        valid_since = isinstance(since, str) and _SEMVER.fullmatch(since)
        valid_removal = isinstance(removal, str) and _SEMVER.fullmatch(removal)
        if valid_since and valid_removal and _version_key(since) >= _version_key(removal):
            problems.append(f"{table_key}.since must precede removal")
        if valid_removal and _SEMVER.fullmatch(version):
            if _version_key(removal) <= _version_key(version):
                problems.append(
                    f"{table_key}.removal {removal} is not after shipping version {version}"
                )
        stacklevel = spec.get("stacklevel")
        if not isinstance(stacklevel, int) or isinstance(stacklevel, bool) or stacklevel < 1:
            problems.append(f"{table_key}.stacklevel must be a positive integer literal")

    for key, locations in sorted(calls.items()):
        if key not in specs:
            problems.append(f"registered callsite has no spec: {key} at {', '.join(locations)}")
        elif len(locations) != 1:
            problems.append(f"registered spec {key} has {len(locations)} callsites")
    for key in sorted(specs.keys() - calls.keys()):
        problems.append(f"stale deprecation spec has no callsite: {key}")
    return problems


def _scan(version: str) -> list[_Offender]:
    pattern = _removal_pattern(version)
    offenders: list[_Offender] = []
    for path in sorted(SRC_ROOT.rglob("*.py")):
        module = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        rel = path.relative_to(REPO_ROOT).as_posix()
        for node in ast.walk(module):
            if not isinstance(node, ast.Call):
                continue
            if _call_name(node.func) not in _DEPRECATION_CALL_NAMES:
                continue
            # The message is the first positional arg, or the ``message=``
            # keyword (``warnings.warn(message=...)``). Checking both keeps a
            # keyword-form deprecation from bypassing the gate.
            message_node: ast.AST | None = node.args[0] if node.args else None
            if message_node is None:
                for kw in node.keywords:
                    if kw.arg == "message":
                        message_node = kw.value
                        break
            if message_node is None:
                continue
            message = _flatten_message(message_node)
            if pattern.search(message):
                snippet = message.strip()
                if len(snippet) > 100:
                    snippet = snippet[:97] + "..."
                offenders.append(_Offender(rel, node.lineno, version, snippet))
    return offenders


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument(
        "--pyproject",
        default=str(REPO_ROOT / "pyproject.toml"),
        help="Path to pyproject.toml (default: repo root)",
    )
    args = ap.parse_args(argv)

    pyproject = Path(args.pyproject)
    if not pyproject.is_file():
        print(f"pyproject.toml not found: {pyproject}", file=sys.stderr)
        return 2
    try:
        version = _read_version(pyproject)
    except (KeyError, TypeError, ValueError) as exc:
        print(f"Could not read project.version: {exc}", file=sys.stderr)
        return 2

    offenders = _scan(version)
    registry_problems = _registered_deprecation_problems(version)

    blocking: list[_Offender] = []
    matched_allowlist_keys: set[tuple[str, str]] = set()
    for offender in offenders:
        if offender.key in _ALLOWLIST_BY_KEY:
            matched_allowlist_keys.add(offender.key)
            continue
        blocking.append(offender)

    stale = sorted(
        f"  {entry.path} (v{entry.version}, #{entry.issue})"
        for entry in LAPSED_ALLOWLIST
        if entry.key not in matched_allowlist_keys
    )

    # Report BOTH problems in one pass: a developer fixing a blocking offender
    # should also see any stale allowlist entry without needing a second run.
    if blocking:
        print(
            f"Deprecation message(s) name the current release version "
            f"v{version} as their removal target:",
            file=sys.stderr,
        )
        for offender in blocking:
            print(f"  {offender.path}:{offender.lineno}: {offender.snippet}", file=sys.stderr)
        print(
            "\nA deprecation must never point at the version shipping it. Either "
            "delete the shim before this release, or bump the stated removal "
            "target to a future version. If the removal is tracked separately, "
            "add the site to LAPSED_ALLOWLIST with its tracking issue.",
            file=sys.stderr,
        )

    if stale:
        print(
            "Stale deprecation-target allowlist entries (no matching deprecation "
            "message found — remove from LAPSED_ALLOWLIST):",
            file=sys.stderr,
        )
        for line in stale:
            print(line, file=sys.stderr)

    if registry_problems:
        print("Registered deprecation specification errors:", file=sys.stderr)
        for problem in registry_problems:
            print(f"  {problem}", file=sys.stderr)

    if blocking or stale or registry_problems:
        return 1

    allowlisted = len(matched_allowlist_keys)
    suffix = f" ({allowlisted} allowlisted, lapsed)" if allowlisted else ""
    print(
        f"OK: no deprecation message names the current release v{version} as a "
        f"removal target{suffix}"
    )
    return 0


if __name__ == "__main__":
    sys.exit(main())
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall