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.

9.3 KB
Raw Blame
"""Guard against the global-name-shadowing class of bug.

base.html loads the shared service scripts (services/api.js, services/ui.js,
services/formatting.js, ...) with ``defer``, and the notes page templates load
their page scripts (pages/note-detail.js, pages/notes.js) with ``defer`` too
(after their dependencies, for load-order correctness). Among deferred scripts
load order is document order, so if two DISTINCT scripts each declare the same
top-level ``function NAME`` / ``const NAME`` / ``let NAME`` / ``var NAME``, the
later one OVERWRITES the earlier — one version silently never runs.

This is exactly what broke "Start Research does nothing": api.js's
``startResearch(query, mode)`` clobbered note-detail.js's ``startResearch()``
(the modal posted a serialized DOM element as the query), and ui.js's
``showError(container, message)`` clobbered the pages' ``showError(message)``
so every error toast no-opped.

The collision was removed by renaming the page-local functions. This test
locks the invariant so it cannot silently regress: no top-level name in a
page script listed below may collide with a top-level name in a script
base.html loads. If you add a page-level helper, give it a name unique from
the shared service scripts (or wrap the page script in an IIFE/module).
"""

import re
from pathlib import Path

import local_deep_research

_WEB = Path(local_deep_research.__file__).parent / "web"
_STATIC = _WEB / "static"
_BASE_HTML = _WEB / "templates" / "base.html"

# Top-level declarations = no leading whitespace (column 0). Page scripts are
# plain scripts (not modules), so these land on the global object and collide.
_DECL_RE = re.compile(
    r"^(?:async\s+)?function\s+([A-Za-z_$][\w$]*)"
    r"|^(?:let|var|const)\s+([A-Za-z_$][\w$]*)"
    # `class` is a lexical top-level declaration too: two same-named
    # `class`/`let`/`const` across classic <script> tags in one document
    # throw "Identifier already declared" at parse time. safe-fetch.js
    # (a base.html-shared script) ships `class HTTPError`, so this must be
    # covered or the guard has a blind spot for the exact declaration kind.
    r"|^class\s+([A-Za-z_$][\w$]*)",
    re.MULTILINE,
)

# Classic (non-module) page scripts that declare top-level names of their own
# and must not collide with one of the base.html-shared scripts' top-level
# names. The notes page scripts that had the original collisions, plus
# delete_manager.js (a top-level `const formatBytes` wrapping the shared
# window.formatBytes -- a same-named top-level declaration later added to a
# base.html-shared script would crash with SyntaxError, not silently shadow
# it). Collection, embedding-settings, and news scripts are emitted from
# their templates' content blocks before base.html's shared deferred scripts.
# Their page-local alert helpers must have names distinct from ui.js's
# showError/showAlert declarations (#6585, #7018).
_PAGE_SCRIPTS = [
    "js/pages/note-detail.js",
    "js/pages/notes.js",
    "js/pages/news.js",
    "js/deletion/delete_manager.js",
    "js/collection_details.js",
    "js/collections_manager.js",
    "js/collection_create.js",
    "js/collection_upload.js",
    "js/embedding_settings.js",
]

_CONTENT_BLOCK_PAGES = {
    "collection_details.html": "js/collection_details.js",
    "collections.html": "js/collections_manager.js",
    "collection_create.html": "js/collection_create.js",
    "collection_upload.html": "js/collection_upload.js",
    "embedding_settings.html": "js/embedding_settings.js",
    "news.html": "js/pages/news.js",
    "news_cleaned.html": "js/pages/news.js",
}


def test_affected_page_scripts_run_before_shared_ui():
    """Keep the ordering assumption behind this collision guard explicit."""
    base = _BASE_HTML.read_text(encoding="utf-8")
    assert base.index("{% block content %}") < base.index(
        "/static/js/services/ui.js"
    )
    for template, script in _CONTENT_BLOCK_PAGES.items():
        html = (_WEB / "templates" / "pages" / template).read_text(
            encoding="utf-8"
        )
        content = html.split("{% block content %}", 1)[1].split(
            "{% endblock %}", 1
        )[0]
        assert f'<script defer src="/static/{script}"></script>' in content
        assert script in _PAGE_SCRIPTS


def _top_level_names(js_path: Path) -> set[str]:
    text = js_path.read_text(encoding="utf-8")
    names = set()
    for m in _DECL_RE.finditer(text):
        names.add(m.group(1) or m.group(2) or m.group(3))
    return names


def _base_html_shared_scripts() -> list[Path]:
    """Static JS files base.html loads (the deferred shared service layer)."""
    html = _BASE_HTML.read_text(encoding="utf-8")
    srcs = re.findall(r'<script[^>]*\bsrc="(/static/js/[^"]+)"', html)
    paths = []
    for src in srcs:
        p = _STATIC / src.replace("/static/", "")
        if p.exists():
            paths.append(p)
    return paths


def test_base_html_shared_scripts_are_discoverable():
    # Sanity: the parsing finds the known shared service scripts. If this
    # breaks, the collision check below would silently pass on nothing.
    shared = {p.name for p in _base_html_shared_scripts()}
    assert "api.js" in shared
    assert "ui.js" in shared
    assert "formatting.js" in shared


def test_page_scripts_do_not_shadow_shared_globals():
    shared_names: dict[str, str] = {}
    for sp in _base_html_shared_scripts():
        for name in _top_level_names(sp):
            shared_names.setdefault(name, sp.name)

    collisions = []
    for rel in _PAGE_SCRIPTS:
        page = _STATIC / rel
        assert page.exists(), f"missing page script: {rel}"
        for name in _top_level_names(page):
            if name in shared_names:
                collisions.append(
                    f"{rel} top-level '{name}' collides with "
                    f"{shared_names[name]} (deferred → clobbers the page "
                    f"version at runtime)"
                )

    assert not collisions, (
        "Global-name shadowing reintroduced (class — the page "
        "version silently never runs). Rename the page-local symbol(s):\n"
        + "\n".join(f"  - {c}" for c in collisions)
    )


# ---------------------------------------------------------------------------
# Same invariant, page-template level: notes.html / note_detail.html load
# component scripts (components/semantic_search.js) with ``defer`` alongside
# their (also deferred) page script. A column-0 declaration in the page
# script that reuses a semantic_search.js top-level name (or vice versa) is
# silently clobbered at runtime by whichever loads later — the base.html-only
# check above would never see it. The page script is compared only against
# the OTHER deferred scripts on the template (a script cannot shadow itself).
# ---------------------------------------------------------------------------

_PAGE_TEMPLATES = _WEB / "templates" / "pages"

# template → the page script it loads (now deferred, like the components).
_NOTES_TEMPLATE_TO_PAGE_SCRIPT = {
    "notes.html": "js/pages/notes.js",
    "note_detail.html": "js/pages/note-detail.js",
}


def _template_deferred_scripts(template_name: str) -> list[Path]:
    """Static JS files a notes page template loads with ``defer``."""
    html = (_PAGE_TEMPLATES / template_name).read_text(encoding="utf-8")
    paths = []
    for attrs in re.findall(r"<script\b([^>]*)>", html):
        if not re.search(r"\bdefer\b", attrs):
            continue
        m = re.search(r'\bsrc="(/static/js/[^"]+)"', attrs)
        if not m:
            continue
        p = _STATIC / m.group(1).replace("/static/", "")
        if p.exists():
            paths.append(p)
    return paths


def test_notes_template_deferred_scripts_are_discoverable():
    # Sanity: the template parsing finds the known deferred component
    # script on both notes pages. If this breaks, the collision check
    # below would silently pass on nothing.
    for template in _NOTES_TEMPLATE_TO_PAGE_SCRIPT:
        deferred = {p.name for p in _template_deferred_scripts(template)}
        assert "semantic_search.js" in deferred, (
            f"{template} no longer loads semantic_search.js with defer — "
            "update _NOTES_TEMPLATE_TO_PAGE_SCRIPT / this test if the "
            "loading strategy changed."
        )


def test_notes_page_scripts_do_not_shadow_deferred_component_globals():
    collisions = []
    for template, page_rel in _NOTES_TEMPLATE_TO_PAGE_SCRIPT.items():
        page = _STATIC / page_rel
        assert page.exists(), f"missing page script: {page_rel}"
        page_names = _top_level_names(page)
        for dp in _template_deferred_scripts(template):
            if dp.resolve() == page.resolve():
                # The page script is itself loaded with ``defer``; it cannot
                # shadow itself, so compare only against OTHER deferred scripts.
                continue
            for name in _top_level_names(dp):
                if name in page_names:
                    collisions.append(
                        f"{page_rel} top-level '{name}' collides with "
                        f"{dp.name} (deferred by {template} → clobbers "
                        f"the page version at runtime)"
                    )

    assert not collisions, (
        "Global-name shadowing between a notes page script and a deferred "
        "component script (class — the page version silently never "
        "runs). Rename the page-local symbol(s):\n"
        + "\n".join(f"  - {c}" for c in collisions)
    )