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/audit_auth_shared_mutations.py

View on GitHub
#!/usr/bin/env python3
"""Audit test mutations of auth/browser classes and shared-lifetime owners.

The module-patch scorecard cannot see a patch moved from ``module._STATE`` to
``Owner._STATE`` or ``Owner.process_default().reset()``.  This companion audit
therefore freezes those shared-object operations, including their lexical
owner.  Unknown/dynamic mutation names against a resolved owner fail closed.
Fresh instances assigned inside a test do not resolve as shared owners.

This is a repository-specific shrink-only ratchet, not a general Python or
pytest analyzer. It supports explicit family imports/aliases, direct
attribute/item/namespace mutation, literal finite names and containers without
unpacking, the suite-used syntactic ``list(...)`` wrapper, and direct local
helper forwarding with explicit finite arguments. A resolved
shared owner is counted, a proven-fresh/non-family value is excluded, and an
unresolved family-related target fails closed. Unsupported syntax cannot
justify a metric decrease; make it statically resolvable or preserve the
existing projected row. Unknown ownership is treated conservatively only when
reached from a statically resolved family/shared owner within this grammar.
"""

from __future__ import annotations

import argparse
import ast
import json
import sys
from collections import defaultdict
from dataclasses import dataclass
from pathlib import Path

if __package__ in {None, ""}:  # direct ``python scripts/...`` execution
    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from scripts.audit_auth_patch_sites import (
    _AMBIGUOUS_FAMILY_ALIAS,
    AuditError,
    _alias_context,
    _call_arg,
    _definitely_nonfamily_typed_parameters,
    _dotted_name,
    _forwarded_alias_variants,
    _forwarded_parameter_context,
    _function_definitions,
    _literal_constants_context,
    _literal_mapping_keys,
    _literal_strings,
    _literal_values_context,
    _module_string_constants,
    _owner_metadata,
    _scope_declarations,
)

REPO_ROOT = Path(__file__).resolve().parent.parent
FAMILY = {
    "notebooklm._auth": REPO_ROOT / "src/notebooklm/_auth",
    "notebooklm._browser": REPO_ROOT / "src/notebooklm/_browser",
}
MUTATORS = {
    "append",
    "clear",
    "discard",
    "extend",
    "pop",
    "popitem",
    "remove",
    "setdefault",
    "update",
}
READ_ONLY_METHODS = {
    "_active_paths_for_tests",
    "_scheduled_paths_for_tests",
    "_workers_for_tests",
    "await_flight",
    "empty",
    "full",
    "is_set",
    "isdisjoint",
    "issubset",
    "locked",
    "process_default",
    "qsize",
    "read_success_epoch",
}


@dataclass(frozen=True, order=True)
class SharedMutation:
    package: str
    owner: str
    attribute: str
    idiom: str
    path: str
    lineno: int
    owner_qualname: str
    owner_kind: str


@dataclass(frozen=True)
class _Inventory:
    classes: dict[str, set[str]]
    singletons: dict[str, set[str]]
    module_aliases: dict[str, dict[str, str]]
    class_aliases: dict[str, dict[str, tuple[str, str]]]
    shared_aliases: dict[str, dict[str, str]]
    gateways: dict[str, dict[str, tuple[tuple[str, str], ...]]]


def _inventory(source: Path, package: str) -> _Inventory:
    classes: dict[str, set[str]] = {}
    singletons: dict[str, set[str]] = {}
    trees: dict[str, ast.Module] = {}
    module_aliases: dict[str, dict[str, str]] = {}
    class_aliases: dict[str, dict[str, tuple[str, str]]] = {}
    for path in sorted(source.glob("*.py")):
        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        trees[path.stem] = tree
        module_classes: set[str] = set()
        module_singletons: set[str] = set()
        imported_modules: dict[str, str] = {}
        imported_classes: dict[str, tuple[str, str]] = {}
        for statement in tree.body:
            if isinstance(statement, ast.ClassDef):
                module_classes.add(statement.name)
            elif isinstance(statement, ast.ImportFrom):
                imported_module: str | None = None
                if statement.level == 1 and statement.module is None:
                    for alias in statement.names:
                        imported_modules[alias.asname or alias.name] = alias.name
                    continue
                if statement.level == 1 and statement.module:
                    imported_module = statement.module.split(".", 1)[0]
                elif statement.module and statement.module.startswith(f"{package}."):
                    imported_module = statement.module[len(package) + 1 :].split(".", 1)[0]
                if imported_module:
                    for alias in statement.names:
                        imported_classes[alias.asname or alias.name] = (
                            imported_module,
                            alias.name,
                        )
            elif isinstance(statement, ast.Assign):
                if isinstance(statement.value, ast.Dict | ast.List | ast.Set | ast.Call):
                    for target in statement.targets:
                        if isinstance(target, ast.Name):
                            module_singletons.add(target.id)
            elif (
                isinstance(statement, ast.AnnAssign)
                and isinstance(statement.target, ast.Name)
                and isinstance(statement.value, ast.Dict | ast.List | ast.Set | ast.Call)
            ):
                module_singletons.add(statement.target.id)
        classes[path.stem] = module_classes
        singletons[path.stem] = module_singletons
        module_aliases[path.stem] = imported_modules
        class_aliases[path.stem] = imported_classes

    def class_owner(module: str, node: ast.AST) -> str | None:
        if isinstance(node, ast.Name):
            if node.id in classes.get(module, set()):
                return f"{package}.{module}.{node.id}"
            imported = class_aliases.get(module, {}).get(node.id)
            if imported and imported[1] in classes.get(imported[0], set()):
                return f"{package}.{imported[0]}.{imported[1]}"
        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
            target_module = module_aliases.get(module, {}).get(node.value.id)
            if target_module and node.attr in classes.get(target_module, set()):
                return f"{package}.{target_module}.{node.attr}"
        return None

    def process_owner(module: str, node: ast.AST) -> str | None:
        if not (
            isinstance(node, ast.Call)
            and isinstance(node.func, ast.Attribute)
            and node.func.attr == "process_default"
        ):
            return None
        owner = class_owner(module, node.func.value)
        return f"{owner}.process_default()" if owner else None

    shared_aliases: dict[str, dict[str, str]] = defaultdict(dict)
    gateways: dict[str, dict[str, tuple[tuple[str, str], ...]]] = defaultdict(dict)
    for module, tree in trees.items():
        for statement in tree.body:
            if isinstance(statement, ast.Assign) and len(statement.targets) == 1:
                target = statement.targets[0]
                value = statement.value
                if isinstance(target, ast.Name) and isinstance(value, ast.Attribute):
                    owner = process_owner(module, value.value)
                    if owner:
                        shared_aliases[module][target.id] = f"{owner}.{value.attr}"
            if not isinstance(statement, ast.FunctionDef | ast.AsyncFunctionDef):
                continue
            delegated: list[tuple[str, str]] = []
            for call in (node for node in ast.walk(statement) if isinstance(node, ast.Call)):
                if not isinstance(call.func, ast.Attribute):
                    continue
                owner = process_owner(module, call.func.value)
                if owner:
                    delegated.append((owner, call.func.attr))
            if delegated:
                gateways[module][statement.name] = tuple(sorted(set(delegated)))
    return _Inventory(
        classes,
        singletons,
        dict(module_aliases),
        dict(class_aliases),
        {module: dict(values) for module, values in shared_aliases.items()},
        {module: dict(values) for module, values in gateways.items()},
    )


def _absolute_dotted(node: ast.AST, aliases: dict[str, str]) -> str | None:
    dotted = _dotted_name(node)
    if dotted is None:
        return None
    head, separator, tail = dotted.partition(".")
    target = aliases.get(head)
    if target is None:
        return dotted
    if target == _AMBIGUOUS_FAMILY_ALIAS:
        raise AuditError("mutation target is an ambiguous family alias after control-flow merge")
    return target + (separator + tail if separator else "")


def _merge_alias_bindings(destination: dict[str, str], source: dict[str, str]) -> None:
    """Merge family bindings without silently choosing one possible owner."""
    for name, target in source.items():
        if name not in destination:
            destination[name] = target
        elif destination[name] != target:
            destination[name] = _AMBIGUOUS_FAMILY_ALIAS


def _normalize_private_module(
    dotted: str, inventories: dict[str, _Inventory]
) -> tuple[str, str, list[str]] | None:
    for package, inventory in inventories.items():
        prefix = f"{package}."
        if not dotted.startswith(prefix):
            continue
        parts = dotted[len(prefix) :].split(".")
        if not parts:
            continue
        module, tail = parts[0], parts[1:]
        seen: set[tuple[str, str]] = set()
        while tail:
            alias = tail[0]
            target = inventory.module_aliases.get(module, {}).get(alias)
            if target is None or (module, alias) in seen:
                break
            seen.add((module, alias))
            module, tail = target, tail[1:]
        return package, module, tail
    return None


def _resolved_dotted_owner(
    dotted: str,
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
) -> tuple[str, str] | None:
    facade_prefix = "notebooklm.auth."
    if dotted.startswith(facade_prefix):
        parts = dotted[len(facade_prefix) :].split(".")
        owner = facade_aliases.get(parts[0])
        if owner:
            owner = ".".join((owner, *parts[1:])) if len(parts) > 1 else owner
            package = next(
                (candidate for candidate in inventories if owner.startswith(f"{candidate}.")),
                "notebooklm._auth",
            )
            return package, owner
    normalized = _normalize_private_module(dotted, inventories)
    if normalized is None:
        return None
    package, module, tail = normalized
    if not tail:
        return None
    inventory = inventories[package]
    root, rest = tail[0], tail[1:]
    owner = inventory.shared_aliases.get(module, {}).get(root)
    imported_class = inventory.class_aliases.get(module, {}).get(root)
    if owner is None and imported_class is not None:
        owner = f"{package}.{imported_class[0]}.{imported_class[1]}"
    if owner is None and (
        root in inventory.classes.get(module, set())
        or root in inventory.singletons.get(module, set())
    ):
        owner = f"{package}.{module}.{root}"
    if owner is None:
        return None
    if rest:
        owner = ".".join((owner, *rest))
    return package, owner


def _is_bare_class(owner: tuple[str, str], inventories: dict[str, _Inventory]) -> bool:
    package, dotted = owner
    inventory = inventories[package]
    return any(
        dotted == f"{package}.{module}.{class_name}"
        for module, classes in inventory.classes.items()
        for class_name in classes
    )


def _facade_shared_aliases(facade_file: Path, inventories: dict[str, _Inventory]) -> dict[str, str]:
    if not facade_file.is_file():
        return {}
    tree = ast.parse(facade_file.read_text(encoding="utf-8"), filename=str(facade_file))
    imports: dict[str, str] = {}
    result: dict[str, str] = {}
    for statement in tree.body:
        if not isinstance(statement, ast.ImportFrom):
            continue
        module = statement.module or ""
        if statement.level == 1 and module == "_auth":
            for alias in statement.names:
                imports[alias.asname or alias.name] = f"notebooklm._auth.{alias.name}"
        elif statement.level == 1 and module.startswith("_auth."):
            target_module = module[len("_auth.") :].split(".", 1)[0]
            for alias in statement.names:
                dotted = f"notebooklm._auth.{target_module}.{alias.name}"
                resolved = _resolved_dotted_owner(dotted, inventories, {})
                if resolved is not None:
                    result[alias.asname or alias.name] = resolved[1]
        elif module in inventories:
            for alias in statement.names:
                imports[alias.asname or alias.name] = f"{module}.{alias.name}"
    for statement in tree.body:
        if not (
            isinstance(statement, ast.Assign)
            and len(statement.targets) == 1
            and isinstance(statement.targets[0], ast.Name)
        ):
            continue
        assignment_dotted = _absolute_dotted(statement.value, imports)
        resolved = (
            _resolved_dotted_owner(assignment_dotted, inventories, {})
            if assignment_dotted is not None
            else None
        )
        if resolved is not None:
            result[statement.targets[0].id] = resolved[1]
    return result


def _gateway_rows(
    call: ast.Call,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
) -> list[tuple[str, str, str, str]] | None:
    dotted = _absolute_dotted(call.func, aliases)
    normalized = _normalize_private_module(dotted, inventories) if dotted else None
    if normalized is None:
        return None
    package, module, tail = normalized
    if len(tail) != 1:
        return None
    delegated = inventories[package].gateways.get(module, {}).get(tail[0])
    if delegated is None:
        return None
    rows: list[tuple[str, str, str, str]] = []
    for owner, method in delegated:
        if method in READ_ONLY_METHODS:
            continue
        kind = "gateway-mutator" if method in MUTATORS else "gateway-method-or-unknown"
        rows.append((package, owner, method, kind))
    return rows


def _direct_symbol_context(
    tree: ast.Module,
    package: str,
    owners: dict[int, tuple[str, str]],
) -> tuple[dict[str, str], dict[str, dict[str, str]], dict[str, set[str]]]:
    """Direct ``from package.module import Class`` bindings by lexical scope."""

    module_aliases: dict[str, str] = {}
    local_aliases: dict[str, dict[str, str]] = defaultdict(dict)
    local_names: dict[str, set[str]] = {}
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda):
            owner = (
                owners.get(id(next(iter(node.body), node)), ("<module>", "helper"))[0]
                if not isinstance(node, ast.Lambda)
                else "<lambda>"
            )
            local_names[owner] = _scope_declarations(node)[0]
        if not isinstance(node, ast.ImportFrom):
            continue
        module = node.module or ""
        if not module.startswith(f"{package}."):
            continue
        owner = owners.get(id(node), ("<module>", "helper"))[0]
        destination = module_aliases if owner == "<module>" else local_aliases[owner]
        for alias in node.names:
            destination[alias.asname or alias.name] = f"{module}.{alias.name}"
    return module_aliases, local_aliases, local_names


def _resolve_shared_owner(
    node: ast.AST,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
    accessors: dict[str, tuple[str, str]] | None = None,
) -> tuple[str, str] | None:
    if isinstance(node, ast.Call):
        if (
            isinstance(node.func, ast.Name)
            and not node.args
            and not node.keywords
            and accessors is not None
            and node.func.id in accessors
        ):
            return accessors[node.func.id]
        if isinstance(node.func, ast.Attribute) and node.func.attr == "process_default":
            resolved = _resolve_shared_owner(
                node.func.value, aliases, inventories, facade_aliases, accessors
            )
            if resolved is not None:
                package, owner = resolved
                return package, f"{owner}.process_default()"
        return None
    if isinstance(node, ast.Subscript):
        parent = _resolve_shared_owner(node.value, aliases, inventories, facade_aliases, accessors)
        if parent is None:
            return None
        try:
            key = ast.literal_eval(node.slice)
        except (ValueError, TypeError, SyntaxError) as exc:
            raise AuditError("dynamic nested key against a resolved shared owner") from exc
        if not isinstance(key, str | int | float | bool | tuple) and key is not None:
            raise AuditError("unsupported nested key against a resolved shared owner")
        return parent[0], f"{parent[1]}[{key!r}]"
    dotted = _absolute_dotted(node, aliases)
    if dotted is not None:
        resolved = _resolved_dotted_owner(dotted, inventories, facade_aliases)
        if resolved is not None:
            return resolved
    if isinstance(node, ast.Attribute):
        parent = _resolve_shared_owner(node.value, aliases, inventories, facade_aliases, accessors)
        if parent is not None:
            return parent[0], f"{parent[1]}.{node.attr}"
    return None


def _namespace_owner(
    node: ast.AST,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
    accessors: dict[str, tuple[str, str]] | None = None,
) -> tuple[str, str] | None:
    if isinstance(node, ast.Attribute) and node.attr == "__dict__":
        return _resolve_shared_owner(node.value, aliases, inventories, facade_aliases, accessors)
    if (
        isinstance(node, ast.Call)
        and isinstance(node.func, ast.Name)
        and node.func.id == "vars"
        and len(node.args) == 1
    ):
        return _resolve_shared_owner(node.args[0], aliases, inventories, facade_aliases, accessors)
    return _resolve_shared_owner(node, aliases, inventories, facade_aliases, accessors)


def _namespace_method_rows(
    call: ast.Call,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
    constants: dict[str, str],
    context: str,
    expanded: dict[str, tuple[str, ...]] | None,
    accessors: dict[str, tuple[str, str]] | None,
) -> list[tuple[str, str, str, str]] | None:
    if not isinstance(call.func, ast.Attribute):
        return None
    value = call.func.value
    is_namespace = (
        isinstance(value, ast.Attribute)
        and value.attr == "__dict__"
        or isinstance(value, ast.Call)
        and isinstance(value.func, ast.Name)
        and value.func.id == "vars"
    )
    if not is_namespace:
        return None
    owner = _namespace_owner(value, aliases, inventories, facade_aliases, accessors)
    if owner is None:
        return None
    method = call.func.attr
    if method in {"get", "items", "keys", "values", "copy", "__contains__"}:
        return []
    if method == "update":
        attributes: list[str] = []
        if call.args:
            attributes.extend(
                _literal_mapping_keys(
                    call.args[0],
                    context=context,
                    constants=constants,
                    expanded=expanded,
                )
            )
        for keyword in call.keywords:
            if keyword.arg is None:
                attributes.extend(
                    _literal_mapping_keys(
                        keyword.value,
                        context=context,
                        constants=constants,
                        expanded=expanded,
                    )
                )
            else:
                attributes.append(keyword.arg)
        if not attributes:
            raise AuditError(f"{context}: unexpandable shared namespace update")
        return [(owner[0], owner[1], attribute, "namespace.update") for attribute in attributes]
    if method in {"setdefault", "pop", "__setitem__", "__delitem__"}:
        attributes = _literal_strings(_call_arg(call, 0, "key"), constants, expanded)
        if not attributes:
            raise AuditError(f"{context}: dynamic shared namespace {method}")
        return [(owner[0], owner[1], attribute, f"namespace.{method}") for attribute in attributes]
    raise AuditError(f"{context}: unexpandable shared namespace method {method}")


def _call_rows(
    call: ast.Call,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
    constants: dict[str, str],
    context: str,
    expanded: dict[str, tuple[str, ...]] | None = None,
    accessors: dict[str, tuple[str, str]] | None = None,
) -> list[tuple[str, str, str, str]]:
    name = _dotted_name(call.func) or ""
    tail = name.rsplit(".", 1)[-1]
    receiver = name.rsplit(".", 1)[0] if "." in name else ""
    patch_receiver = receiver.split(".")[-1] == "patch"
    namespace_rows = _namespace_method_rows(
        call, aliases, inventories, facade_aliases, constants, context, expanded, accessors
    )
    if namespace_rows is not None:
        return namespace_rows
    gateway_rows = _gateway_rows(call, aliases, inventories)
    if gateway_rows is not None:
        return gateway_rows

    if tail in {"setattr", "delattr"} or name in {"setattr", "delattr"}:
        target = _call_arg(call, 0, "target", "obj", "object")
        if target is None or isinstance(target, ast.Constant):
            return []
        owner = _resolve_shared_owner(target, aliases, inventories, facade_aliases, accessors)
        if owner is None:
            return []
        attributes = _literal_strings(_call_arg(call, 1, "name", "attribute"), constants, expanded)
        if not attributes:
            raise AuditError(f"{context}: dynamic shared-owner attribute")
        prefix = "builtin" if name in {"setattr", "delattr"} else "monkeypatch"
        return [(owner[0], owner[1], attribute, f"{prefix}.{tail}") for attribute in attributes]

    if patch_receiver and tail == "object":
        target = _call_arg(call, 0, "target")
        owner = (
            _resolve_shared_owner(target, aliases, inventories, facade_aliases, accessors)
            if target is not None
            else None
        )
        if owner is None:
            return []
        attributes = _literal_strings(_call_arg(call, 1, "attribute", "name"), constants, expanded)
        if not attributes:
            raise AuditError(f"{context}: dynamic patch.object shared-owner attribute")
        return [(owner[0], owner[1], attribute, "patch.object") for attribute in attributes]

    if patch_receiver and tail == "multiple":
        target = _call_arg(call, 0, "target")
        owner = (
            _resolve_shared_owner(target, aliases, inventories, facade_aliases, accessors)
            if target is not None
            else None
        )
        if owner is None:
            return []
        multiple_attributes: list[str] = []
        for keyword in call.keywords:
            if keyword.arg is None:
                multiple_attributes.extend(
                    _literal_mapping_keys(
                        keyword.value,
                        context=context,
                        constants=constants,
                        expanded=expanded,
                    )
                )
                continue
            if keyword.arg != "target":
                multiple_attributes.append(keyword.arg)
        if not multiple_attributes:
            raise AuditError(f"{context}: unexpandable patch.multiple shared owner")
        return [
            (owner[0], owner[1], attribute, "patch.multiple") for attribute in multiple_attributes
        ]

    if (patch_receiver and tail == "dict") or tail in {"setitem", "delitem"}:
        target = _call_arg(call, 0, "in_dict", "dic", "mapping")
        owner = (
            _namespace_owner(target, aliases, inventories, facade_aliases, accessors)
            if target is not None
            else None
        )
        if owner is None:
            return []
        if patch_receiver and tail == "dict":
            attributes = _literal_mapping_keys(
                _call_arg(call, 1, "values"),
                context=context,
                constants=constants,
                expanded=expanded,
            )
            for keyword in call.keywords:
                if keyword.arg is None:
                    raise AuditError(f"{context}: dynamic patch.dict shared owner")
                if keyword.arg not in {"in_dict", "values", "clear"}:
                    attributes.append(keyword.arg)
            if not attributes:
                raise AuditError(f"{context}: unexpandable patch.dict shared owner")
            return [(owner[0], owner[1], attribute, "patch.dict") for attribute in attributes]
        attributes = _literal_strings(_call_arg(call, 1, "key", "name"), constants, expanded)
        if not attributes:
            raise AuditError(f"{context}: dynamic shared-owner item key")
        return [(owner[0], owner[1], attribute, f"monkeypatch.{tail}") for attribute in attributes]

    if isinstance(call.func, ast.Attribute):
        owner = _resolve_shared_owner(
            call.func.value, aliases, inventories, facade_aliases, accessors
        )
        if (
            owner is not None
            and not _is_bare_class(owner, inventories)
            and call.func.attr not in READ_ONLY_METHODS
        ):
            kind = "mutator" if call.func.attr in MUTATORS else "method-or-unknown"
            return [(owner[0], owner[1], call.func.attr, kind)]
    return []


def _assignment_rows(
    node: ast.Assign | ast.AnnAssign | ast.AugAssign | ast.Delete,
    aliases: dict[str, str],
    inventories: dict[str, _Inventory],
    facade_aliases: dict[str, str],
    constants: dict[str, str],
    context: str,
    expanded: dict[str, tuple[str, ...]] | None = None,
    accessors: dict[str, tuple[str, str]] | None = None,
) -> list[tuple[str, str, str, str]]:
    if isinstance(node, ast.Assign):
        targets, idiom = node.targets, "assignment"
    elif isinstance(node, ast.AnnAssign):
        targets = [node.target] if node.value is not None else []
        idiom = "annotated-assignment"
    elif isinstance(node, ast.AugAssign):
        targets, idiom = [node.target], "augmented-assignment"
    else:
        targets, idiom = node.targets, "deletion"
    rows: list[tuple[str, str, str, str]] = []
    for target in targets:
        target_idiom = idiom
        owner: tuple[str, str] | None
        attributes: list[str]
        if isinstance(target, ast.Attribute):
            owner = _resolve_shared_owner(
                target.value, aliases, inventories, facade_aliases, accessors
            )
            attributes = [target.attr]
        elif isinstance(target, ast.Subscript):
            owner = _namespace_owner(target.value, aliases, inventories, facade_aliases, accessors)
            attributes = _literal_strings(target.slice, constants, expanded)
            if owner is not None and not attributes:
                raise AuditError(f"{context}: dynamic shared-owner item assignment")
            target_idiom = f"item-{target_idiom}"
        else:
            owner, attributes = None, []
        if owner is not None:
            rows.extend((owner[0], owner[1], attribute, target_idiom) for attribute in attributes)
    return rows


def collect_mutations(
    tests_dir: Path,
    family: dict[str, Path] | None = None,
) -> list[SharedMutation]:
    family = family or FAMILY
    inventories = {package: _inventory(path, package) for package, path in family.items()}
    auth_source = family.get("notebooklm._auth")
    facade_aliases = (
        _facade_shared_aliases(auth_source.parent / "auth.py", inventories)
        if auth_source is not None
        else {}
    )
    project_root = tests_dir.parent if tests_dir.name == "tests" else REPO_ROOT
    result: list[SharedMutation] = []
    for path in sorted(tests_dir.rglob("*.py")):
        source_text = path.read_text(encoding="utf-8")
        tree = ast.parse(source_text, filename=str(path))
        contexts = {
            package: _alias_context(tree, package)
            for package in family
            if package in source_text or package.rsplit(".", 1)[-1] in source_text
        }
        if "notebooklm.auth" in source_text or "import auth" in source_text:
            contexts["notebooklm.auth"] = _alias_context(tree, "notebooklm.auth")
        owners = _owner_metadata(tree, path)
        constants = _module_string_constants(tree)
        constant_context = _literal_constants_context(tree, constants)
        literal_values = _literal_values_context(tree, constant_context)
        symbols = {package: _direct_symbol_context(tree, package, owners) for package in family}
        shared_accessors: dict[str, tuple[str, str]] = {}
        # A small module-level wrapper that returns a proven shared owner is an
        # equivalent process-default accessor. Resolve it separately from
        # ordinary aliases so the function object itself is never mistaken for
        # the returned owner.
        for candidate in tree.body:
            if not isinstance(candidate, ast.FunctionDef | ast.AsyncFunctionDef):
                continue
            statements = [
                statement
                for statement in candidate.body
                if not (
                    isinstance(statement, ast.Expr)
                    and isinstance(statement.value, ast.Constant)
                    and isinstance(statement.value.value, str)
                )
            ]
            return_node = statements[0] if len(statements) == 1 else None
            if not isinstance(return_node, ast.Return) or return_node.value is None:
                continue
            accessor_aliases: dict[str, str] = {}
            for context in contexts.values():
                _merge_alias_bindings(accessor_aliases, context.get(id(return_node), {}))
            accessor_lexical_owner = owners.get(id(return_node), (candidate.name, "helper"))[0]
            accessor_blocked_names: set[str] = set()
            for module_aliases, local_aliases, local_names in symbols.values():
                blocked = local_names.get(accessor_lexical_owner, set())
                accessor_blocked_names.update(blocked)
                _merge_alias_bindings(
                    accessor_aliases,
                    {
                        name: target
                        for name, target in module_aliases.items()
                        if name not in blocked
                    },
                )
                _merge_alias_bindings(
                    accessor_aliases, local_aliases.get(accessor_lexical_owner, {})
                )
            callable_accessors = {
                name: owner
                for name, owner in shared_accessors.items()
                if name not in accessor_blocked_names
            }
            resolved = _resolve_shared_owner(
                return_node.value,
                accessor_aliases,
                inventories,
                facade_aliases,
                callable_accessors,
            )
            if resolved is not None:
                shared_accessors[candidate.name] = resolved
        local_shared: dict[str, dict[str, str]] = defaultdict(dict)
        # Resolve simple ``owner = Class.process_default()`` / ``owner =
        # module.SHARED`` bindings.  They remain scoped to their lexical owner;
        # ordinary fresh construction does not resolve and stays excluded.
        simple_assignments = [
            node
            for node in ast.walk(tree)
            if isinstance(node, ast.Assign)
            and len(node.targets) == 1
            and isinstance(node.targets[0], ast.Name)
        ]
        for _ in range(len(simple_assignments) + 1):
            previous_local_shared = {
                owner: dict(bindings) for owner, bindings in local_shared.items()
            }
            for assignment_node in simple_assignments:
                target = assignment_node.targets[0]
                assert isinstance(target, ast.Name)
                assignment_aliases: dict[str, str] = {}
                for context in contexts.values():
                    _merge_alias_bindings(assignment_aliases, context.get(id(assignment_node), {}))
                assignment_owner = owners.get(id(assignment_node), ("<module>", "helper"))[0]
                assignment_blocked_names: set[str] = set()
                for module_aliases, local_aliases, local_names in symbols.values():
                    blocked = local_names.get(assignment_owner, set())
                    assignment_blocked_names.update(blocked)
                    _merge_alias_bindings(
                        assignment_aliases,
                        {
                            name: target
                            for name, target in module_aliases.items()
                            if name not in blocked
                        },
                    )
                    _merge_alias_bindings(
                        assignment_aliases, local_aliases.get(assignment_owner, {})
                    )
                _merge_alias_bindings(assignment_aliases, local_shared.get(assignment_owner, {}))
                assignment_dotted = _dotted_name(assignment_node.value)
                if assignment_dotted is not None:
                    assignment_head = assignment_dotted.partition(".")[0]
                    if assignment_aliases.get(assignment_head) == _AMBIGUOUS_FAMILY_ALIAS:
                        _merge_alias_bindings(
                            local_shared[assignment_owner],
                            {target.id: _AMBIGUOUS_FAMILY_ALIAS},
                        )
                        continue
                assignment_accessors = {
                    name: owner
                    for name, owner in shared_accessors.items()
                    if name not in assignment_blocked_names
                }
                resolved = _resolve_shared_owner(
                    assignment_node.value,
                    assignment_aliases,
                    inventories,
                    facade_aliases,
                    assignment_accessors,
                )
                if resolved is not None:
                    _merge_alias_bindings(local_shared[assignment_owner], {target.id: resolved[1]})
            if local_shared == previous_local_shared:
                break

        def resolution_context(
            node: ast.AST,
            *,
            _contexts: dict[str, dict[int, dict[str, str]]] = contexts,
            _owners: dict[int, tuple[str, str]] = owners,
            _symbols: dict[
                str, tuple[dict[str, str], dict[str, dict[str, str]], dict[str, set[str]]]
            ] = symbols,
            _local_shared: dict[str, dict[str, str]] = local_shared,
            _shared_accessors: dict[str, tuple[str, str]] = shared_accessors,
        ) -> tuple[dict[str, str], dict[str, tuple[str, str]]]:
            aliases: dict[str, str] = {}
            for context in _contexts.values():
                _merge_alias_bindings(aliases, context.get(id(node), {}))
            lexical_owner = _owners.get(id(node), ("<module>", "helper"))[0]
            blocked_names: set[str] = set()
            for module_aliases, local_aliases, local_names in _symbols.values():
                blocked = local_names.get(lexical_owner, set())
                blocked_names.update(blocked)
                _merge_alias_bindings(
                    aliases,
                    {
                        name: target
                        for name, target in module_aliases.items()
                        if name not in blocked
                    },
                )
                _merge_alias_bindings(aliases, local_aliases.get(lexical_owner, {}))
            _merge_alias_bindings(aliases, _local_shared.get(lexical_owner, {}))
            accessors = {
                name: owner
                for name, owner in _shared_accessors.items()
                if name not in blocked_names
            }
            return aliases, accessors

        def resolve_forwarded(argument: ast.AST, call: ast.Call) -> str | None:
            aliases, accessors = resolution_context(call)
            resolved = _resolve_shared_owner(
                argument, aliases, inventories, facade_aliases, accessors
            )
            return resolved[1] if resolved is not None else None

        forwarded = _forwarded_parameter_context(
            tree,
            owners,
            resolve_forwarded,
            context=path.as_posix(),
            include_method_receivers=True,
            excluded_parameters=_definitely_nonfamily_typed_parameters(
                tree, _function_definitions(tree), (*family, "notebooklm.auth")
            ),
        )
        try:
            rel = path.relative_to(project_root).as_posix()
        except ValueError:
            rel = path.as_posix()
        for node in ast.walk(tree):
            aliases, node_accessors = resolution_context(node)
            lexical_owner, owner_kind = owners.get(id(node), ("<module>", "helper"))
            location = f"{rel}:{getattr(node, 'lineno', 0)}"
            rows: list[tuple[str, str, str, str]] = []
            for variant in _forwarded_alias_variants(aliases, lexical_owner, node, forwarded):
                if isinstance(node, ast.Call):
                    rows.extend(
                        _call_rows(
                            node,
                            variant,
                            inventories,
                            facade_aliases,
                            constant_context.get(id(node), {}),
                            location,
                            literal_values.get(id(node), {}),
                            node_accessors,
                        )
                    )
                elif isinstance(node, ast.Assign | ast.AnnAssign | ast.AugAssign | ast.Delete):
                    rows.extend(
                        _assignment_rows(
                            node,
                            variant,
                            inventories,
                            facade_aliases,
                            constant_context.get(id(node), {}),
                            location,
                            literal_values.get(id(node), {}),
                            node_accessors,
                        )
                    )
            for package, shared_owner, attribute, idiom in rows:
                result.append(
                    SharedMutation(
                        package,
                        shared_owner,
                        attribute,
                        idiom,
                        rel,
                        getattr(node, "lineno", 0),
                        lexical_owner,
                        owner_kind,
                    )
                )
    return sorted(result)


def build_projection(mutations: list[SharedMutation]) -> dict[str, object]:
    rows: dict[tuple[str, str, str, str, str, str, str], int] = defaultdict(int)
    for site in mutations:
        rows[
            (
                site.package,
                site.owner,
                site.attribute,
                site.idiom,
                site.path,
                site.owner_qualname,
                site.owner_kind,
            )
        ] += 1
    owned = [site for site in mutations if site.owner_kind != "test"]
    return {
        "version": 1,
        "summary": {
            "total": len(mutations),
            "private": sum(site.attribute.startswith("_") for site in mutations),
            "helper_or_fixture": len(owned),
            "assignments": sum("assignment" in site.idiom for site in mutations),
        },
        "mutations": [
            {
                "package": package,
                "owner": owner,
                "attribute": attribute,
                "idiom": idiom,
                "path": path,
                "owner_qualname": lexical_owner,
                "owner_kind": owner_kind,
                "count": count,
            }
            for (
                package,
                owner,
                attribute,
                idiom,
                path,
                lexical_owner,
                owner_kind,
            ), count in sorted(rows.items())
        ],
    }


def projection_growth(previous: object, current: object) -> list[str]:
    if not isinstance(previous, dict) or not isinstance(current, dict):
        return ["shared-mutation projection is not an object"]
    fields = ("package", "owner", "attribute", "idiom", "path", "owner_qualname", "owner_kind")
    old = {
        tuple(row[field] for field in fields): int(row["count"])
        for row in previous.get("mutations", [])
    }
    new = {
        tuple(row[field] for field in fields): int(row["count"])
        for row in current.get("mutations", [])
    }
    errors = [
        f"shared mutation {identity} grew {old.get(identity, 0)} -> {count}"
        for identity, count in new.items()
        if count > old.get(identity, 0)
    ]
    for name in ("total", "private", "helper_or_fixture", "assignments"):
        before = int(previous.get("summary", {}).get(name, 0))
        after = int(current.get("summary", {}).get(name, 0))
        if after > before:
            errors.append(f"shared mutation {name} grew {before} -> {after}")
    return errors


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--tests-dir", type=Path, default=REPO_ROOT / "tests")
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args(argv)
    if not args.tests_dir.is_dir():
        parser.error(f"not a directory: {args.tests_dir}")
    projection = build_projection(collect_mutations(args.tests_dir))
    if args.json:
        json.dump(projection, sys.stdout, indent=2, sort_keys=True)
        sys.stdout.write("\n")
    else:
        print(json.dumps(projection["summary"], sort_keys=True))
    return 0


if __name__ == "__main__":
    raise SystemExit(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