~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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)
)