Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

12.5 KB
Raw Blame
"""Guard ADR-0011's durable source-provenance result.

The historical branch diff cannot be re-derived with a future
``origin/main...HEAD`` after squash merge: that boundary collapses or includes
unrelated later work. ADR-0011 therefore pins the exact revisions and aggregate
measurement, while this guardian checks those facts and the current successor
mechanisms that remain meaningful.
"""

# allow: no-sut-import — this test parses documentation and source modules.
# Focused behavior tests exercise the production imports.

import re
from pathlib import Path

from tests.migration_evidence_nodes import (
    active_pytest_nodes,
    source_definition_kinds,
)


REPO_ROOT = Path(__file__).resolve().parents[1]
ADR_FILE = (
    REPO_ROOT
    / "docs/decisions/0011-source-provenance-across-the-fastapi-migration.md"
)
SNAPSHOT_SHA = "e5133246d03aea8bbcec8cfed8a4ea2df7b3a94d"
COMPARISON_SHA = "956f4f99c571990d11f672338eec3d3469d6787d"

EXPECTED_SOURCE_COUNTS = {
    "Source modules deleted": 30,
    "Source modules added": 25,
    "Source modules modified": 54,
    "Rename-paired modules reviewed separately": 11,
    "Symbols in deleted modules": 290,
    "Leaf name present somewhere on the migration tree": 206,
    "Leaf name absent from the migration tree": 84,
    "Symbols removed from modified modules": 28,
    "Removed symbols whose leaf name was absent": 6,
}

SUCCESSOR_SYMBOLS = {
    "src/local_deep_research/web/services/socketio_asgi.py": {
        "connect": "async-function",
        "on_subscribe": "async-function",
        "on_unsubscribe": "async-function",
        "disconnect_session": "function",
    },
    "src/local_deep_research/web/dependencies/rate_limit.py": {
        "_is_trusted_peer": "function",
        "_get_client_ip": "function",
    },
    "src/local_deep_research/web/fastapi_app.py": {
        "lifespan": "async-function",
        "SecurityHeadersMiddleware": "class",
        "DatabaseMiddleware": "class",
        "_register_exception_handlers": "function",
        "_setup_template_globals": "function",
    },
    "src/local_deep_research/web/template_config.py": {
        "_LDRTemplates": "class",
        "_LDRTemplates::TemplateResponse": "method",
    },
    "src/local_deep_research/web/dependencies/auth.py": {
        "require_auth": "function",
        "get_db_session_dep": "function",
    },
    "src/local_deep_research/utilities/request_context.py": {
        "set_request_user": "function",
        "get_current_username": "function",
    },
    "src/local_deep_research/web/routers/settings.py": {
        "_shape_egress_scope_setting": "function",
        "_shape_pdf_storage_mode_setting": "function",
        "_apply_env_override": "function",
        "_filter_editable_settings": "function",
        "_resolve_model_discovery_policy": "function",
        "_log_available_models_duration": "function",
    },
    "src/local_deep_research/web/routers/news_flask_api.py": {
        "_start_research_in_process": "function",
        "require_scheduler_control": "function",
    },
}

FOCUSED_EVIDENCE = {
    "tests/web/services/test_socketio_handshake_auth.py": (
        "TestVerifiedUsernameScopesSubscriptions::test_non_owner_gets_not_authorized_and_no_subscription",
    ),
    "tests/web/services/test_socketio_real_websocket_transport.py": (
        "TestRestoredUnsubscribeOwnershipGateRealTransport::test_non_owner_unsubscribe_over_real_ws_runs_the_ownership_check",
    ),
    "tests/security/test_middleware_and_proxy_trust_fastapi.py": (
        "TestDatabaseMiddlewareCleanupCallSite::test_next_request_on_the_same_worker_sees_none_of_the_previous_user",
        "TestTrustedPeerConsequences::test_mapped_public_peer_cannot_choose_its_rate_limit_bucket",
        "TestTrustProxyHeadersUvicornWiring::test_unset_means_forwarded_headers_are_not_trusted",
    ),
    "tests/security/test_followup_and_settings_guards_fastapi.py": (
        "TestFollowupCustomEndpointSsrfPreflight::test_metadata_or_non_http_endpoint_is_rejected_before_any_db_write",
    ),
    "tests/security/test_settings_egress_and_secrets_fastapi.py": (
        "TestModelDiscoveryEgressPolicy::test_private_only_filters_cloud_out_of_the_cached_response",
        "TestFilterEditableSettings::test_bulk_json_save_leaves_a_non_editable_setting_unchanged",
    ),
    "tests/security/test_research_service_isolation_fastapi.py": (
        "TestRunResearchProcessUsernameGate::test_missing_username_raises_before_any_work",
        "TestCancelResearchIsolation::test_colliding_research_id_cancels_only_the_callers_row",
    ),
    "tests/security/test_cross_user_isolation_invariants.py": (
        "TestContextvarIsolationAcrossThreadpool::test_request_user_contextvar_survives_concurrent_threadpool_reuse",
    ),
    "tests/security/test_egress_unprotected_ui_gate.py": (
        "TestShapeEgressScopeSetting::test_hides_unprotected_option_when_operator_has_not_enabled_it",
    ),
    "tests/web/routers/test_settings_port_regressions.py": (
        "TestPdfStorageModeOptionShaping::test_filesystem_hidden_when_gate_off",
    ),
    "tests/web/routers/test_settings_env_lock_write_paths_port.py": (
        "TestSaveAllSettingsEchoLostEnvOverlay::test_save_echo_reports_env_value_and_locks_editable",
    ),
    "tests/web/test_template_environment_census.py": (
        "test_render_template_helper_and_templateresponse_inject_the_same_defaults",
    ),
    "tests/news/test_news_run_subscription_ported.py": (
        "test_start_research_in_process_forwards_the_session_id",
    ),
    "tests/security/test_scheduler_control_and_news_limits_fastapi.py": (
        "TestSchedulerControlGate::test_gate_disabled_returns_403_without_touching_scheduler",
    ),
    "tests/web/test_exception_handler_contract.py": (
        "Test500Contract::test_unhandled_exception_returns_scrubbed_500",
        "Test404Contract::test_api_404_returns_fixed_json_body",
    ),
}


class TestHistoricalSourceMeasurement:
    def test_adr_is_concise_and_pins_the_exact_revisions(self):
        assert ADR_FILE.is_file()
        text = ADR_FILE.read_text(encoding="utf-8")
        normalized = " ".join(text.lower().split())
        assert len(text.splitlines()) <= 155
        assert "**Amendment:** 2026-08-30, tracked in [#6007]" in text
        assert SNAPSHOT_SHA in text
        assert COMPARISON_SHA in text
        assert "git fetch origin refs/pull/3299/head" in normalized
        assert "git cat-file -e" in normalized
        assert "does not promise indefinite pr-ref retention" in normalized
        assert "not current product or security status" in normalized
        assert "github issues" in normalized
        assert "security.md" in normalized
        assert "every python `a`, `d`, `m`, and `r` status entry" in normalized
        assert "all 30 deletions are counted, 29" in normalized
        assert "research_library/deletion/routes/__init__.py" in text
        assert "rename-paired modules" in normalized
        assert "11 such pairs" in normalized
        assert "different historical revisions" in normalized
        assert "extract module-level" in normalized
        assert "recurse through class bodies" in normalized
        assert "do not descend into function or method bodies" in normalized
        assert "compare qualified-name sets" in normalized
        assert "deleted (`d`) and modified (`m`) modules" in normalized
        assert "treat rename (`r`) pairs separately" in normalized
        assert "final qualified-name component" in normalized
        for successor in (
            "_start_research_in_process",
            "require_scheduler_control",
            "_shape_egress_scope_setting",
            "_shape_pdf_storage_mode_setting",
            "_log_available_models_duration",
            "_setup_template_globals",
            "_LDRTemplates.TemplateResponse",
        ):
            assert successor in text

    def test_source_counts_are_exact_and_reconcile(self):
        text = ADR_FILE.read_text(encoding="utf-8")
        parsed = {
            label.strip(): int(count.replace(",", ""))
            for label, count in re.findall(
                r"^\| ([^|]+?) \| ([\d,]+) \|$", text, re.M
            )
        }
        assert parsed == EXPECTED_SOURCE_COUNTS
        assert (
            parsed["Leaf name present somewhere on the migration tree"]
            + parsed["Leaf name absent from the migration tree"]
            == parsed["Symbols in deleted modules"]
        )


class TestCurrentSuccessorMechanisms:
    def test_named_successor_symbols_remain_present(self):
        failures = []
        for relpath, expected in sorted(SUCCESSOR_SYMBOLS.items()):
            path = REPO_ROOT / relpath
            if not path.is_file():
                failures.append(f"{relpath}: missing")
                continue
            try:
                actual = source_definition_kinds(
                    path.read_text(encoding="utf-8")
                )
            except SyntaxError as exc:
                failures.append(f"{relpath}: cannot parse ({exc})")
                continue
            mismatches = {
                name: {"expected": kind, "actual": actual.get(name)}
                for name, kind in expected.items()
                if actual.get(name) != kind
            }
            if mismatches:
                failures.append(f"{relpath}: mismatched {mismatches}")
        assert not failures, "\n".join(failures)

    def test_source_symbol_resolver_requires_exact_structure_and_kind(self):
        definitions = source_definition_kinds(
            """
def top_level():
    def local_only():
        pass

class Owner:
    def direct_method(self):
        def nested_local():
            pass

    class Nested:
        def nested_method(self):
            pass

async def async_top_level():
    pass
"""
        )
        assert definitions == {
            "top_level": "function",
            "Owner": "class",
            "Owner::direct_method": "method",
            "async_top_level": "async-function",
        }
        assert "local_only" not in definitions
        assert "nested_method" not in definitions

    def test_source_symbol_resolver_rejects_later_rebindings_and_deletes(self):
        definitions = source_definition_kinds(
            """
def rebound():
    pass
rebound = object()

def deleted():
    pass
del deleted

class Replaced:
    pass
from replacement import value as Replaced

def unpacked():
    pass
unpacked, other = factory()

def aliased():
    pass
alias = aliased

def wildcard_shadowed():
    pass
from replacement import *

def loop_bound():
    pass
for loop_bound in values:
    pass

def with_bound():
    pass
with manager() as with_bound:
    pass

def exception_bound():
    pass
try:
    raise RuntimeError
except RuntimeError as exception_bound:
    pass

def walrus_bound():
    pass
(walrus_bound := object())

def match_bound():
    pass
match value:
    case {"item": match_bound}:
        pass

def starred_bound():
    pass
*starred_bound, = values

class Repeated:
    def first(self):
        pass
class Repeated:
    def second(self):
        pass

class Owner:
    def rebound_method(self):
        pass
    rebound_method = object()

    def deleted_method(self):
        pass
    del deleted_method

    def loop_bound_method(self):
        pass
    for loop_bound_method in values:
        pass

    def retained_method(self):
        pass

def retained():
    pass
"""
        )
        assert definitions == {
            "Owner": "class",
            "Owner::retained_method": "method",
            "retained": "function",
        }

    def test_source_symbol_resolver_tracks_qualified_member_mutation(self):
        definitions = source_definition_kinds(
            """
class Assigned:
    def guarded(self):
        pass
Assigned.guarded = object()

class Deleted:
    def guarded(self):
        pass
del Deleted.guarded
"""
        )
        assert definitions == {
            "Assigned": "class",
            "Deleted": "class",
        }

    def test_named_focused_behavior_evidence_remains_present(self):
        failures = []
        for relpath, required_names in sorted(FOCUSED_EVIDENCE.items()):
            path = REPO_ROOT / relpath
            if not path.is_file():
                failures.append(f"{relpath}: missing")
                continue
            try:
                tests = active_pytest_nodes(path.read_text(encoding="utf-8"))
            except SyntaxError as exc:
                failures.append(f"{relpath}: cannot parse ({exc})")
                continue
            missing = sorted(set(required_names) - tests)
            if missing:
                failures.append(f"{relpath}: missing {missing}")
        assert not failures, "\n".join(failures)