Raven-1/tests/test_docs_site.py
userName20260323 e708f34a91
docs: align bilingual documentation with runtime behavior (#551)
## Summary

- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.

## Type

- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Passed on the rebased revision:

```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed

uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed

UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.

## Risk

Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00

275 lines
12 KiB
Python

"""The documentation site's pages keep the three properties a broken move costs.
A repository-relative link in a .md page is already caught by mkdocs build
--strict; this guard catches non-.md targets (e.g., docker/.env) that --strict
misses, and runs in the ordinary test suite without needing the docs uv group.
A page added in one language only leaves the other language's reader on a
fallback they cannot tell from a translation. A brand class names a rule in a
stylesheet no build step connects it to, so renaming either side errors
nowhere, reddens nothing, and is visible only to someone looking at the page.
"""
from __future__ import annotations
import re
import xml.etree.ElementTree as ET
from pathlib import Path
import pytest
from markdown import markdown
from markdown.extensions.toc import slugify
REPO = Path(__file__).resolve().parent.parent
SITE = REPO / "docs-site" / "docs"
STYLESHEET = SITE / "stylesheets" / "evermind.css"
LINK = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
HEADING = re.compile(r"^(#{2,6})\s+(.+?)\s*$", re.M)
ANCHOR = re.compile(r"\{\s*#([\w-]+)\s*\}")
CLASS_ATTR = re.compile(r'class="([^"]*)"')
CSS_SELECTOR = re.compile(r"\.(em-[a-z][a-z0-9-]*)")
# Published fragments are a compatibility contract, independent of current headings.
PROACTIVITY_LEGACY_SECTIONS = {
"proactivity": {
"proactivity-design.md#components-and-assembly": ("architecture-overview",),
"proactivity-design.md#context-and-decision-contracts": (
"1-data-types-sentineltypespy",
"plannerdecision",
"plannercontext",
"3-context-assembly-contextassembler-sentinelpredictorcontext_assemblerpy",
"4-decision-layer-proactiveplanner-sentinelplannerpy",
),
"proactivity-design.md#tick-lifecycle": (
"2-orchestration-sentinelrunner-sentinelexecutorrunnerpy",
"one-tick",
"fast-path-rules-skip-only",
"scheduled-fire-fast-path",
"drive-modes",
"tickoutcome",
),
"proactivity-design.md#action-routing": (
"action",
"degradation",
"6-the-three-nudge-execution-paths",
"nudgedispatcher-sentinelexecutordispatcherpy",
"nudgeinjector-sentinelexecutorinjectorpy",
"defermanager-sentinelexecutordefer_managerpy",
"7-the-spawn_agent-path-proactivespawn-sentinelexecutorspawnpy",
),
"proactivity-design.md#policy-boundaries": (
"5-the-gate-nudgepolicy-sentineltrigger_policypolicypy",
"layered-checks",
"adaptive-multiplier",
"readwrite-split",
"personalization-and-persistence",
),
"proactivity-design.md#state-and-feedback": (
"8-feedback-loop-nudgefeedbacktracker-the-nudge-feedback-tool",
"9-state-files",
),
"proactivity-design.md#routines-and-task-discovery": ("12-task-discovery-anticipatory-menus",),
"proactivity-design.md#cron-heartbeat-and-the-spine": (
"10-cron-schedulerscron",
"11-heartbeat-and-event-driven-wake",
"13-spine-integration-and-the-user-inbound-gates",
"mid-turn-user-input-busypolicyinject",
"ask_user-pausing-a-turn-to-ask-the-user",
),
},
"proactivity-design": {
"#design-rationale": (
"1-three-layers-of-proactivity",
"2-the-core-idea-periodic-planner-plus-on-demand-spawn",
"7-scenarios",
"l2-routine-automation",
"l3-memory-linked-reminder",
"l3-context-aware-resumption",
"l3-proactive-status-check",
),
"#components-and-assembly": ("3-components",),
"#context-and-decision-contracts": (
"proactiveplanner-periodic-reasoner",
"contextassembler-input-packaging",
"planner-decision-quality",
),
"#action-routing": (
"4-action-space",
"proactivespawn-multi-step-execution-bridge",
),
"#policy-boundaries": (
"nudgepolicy-the-shared-anti-spam-gate",
"5-anti-spam-the-nudgepolicy-gate",
"9-risks-and-mitigations",
"over-notification",
),
"#routines-and-task-discovery": (
"routinelearner-behavior-pattern-learning",
"task-discovery-anticipatory-menus",
"history-format-drift",
),
"#cron-heartbeat-and-the-spine": ("6-delivery-and-turn-transport-the-spine",),
"proactivity.md#costs-and-safety-limits": ("8-cost", "spawn-safety"),
},
}
def _pages() -> list[Path]:
return sorted(SITE.glob("*.md"))
def test_every_page_has_both_languages() -> None:
english = {path.stem for path in _pages() if not path.name.endswith(".zh.md")}
chinese = {path.name[: -len(".zh.md")] for path in _pages() if path.name.endswith(".zh.md")}
assert english == chinese, (
f"English page without a Chinese twin: {sorted(english - chinese)}; "
f"Chinese page without an English twin: {sorted(chinese - english)}"
)
assert english, "no pages found -- did SITE move?"
def test_no_page_links_into_the_repository_by_a_relative_path() -> None:
pages = _pages()
assert pages, "no pages found -- did SITE move?"
offenders: list[str] = []
for page in pages:
for target in LINK.findall(page.read_text(encoding="utf-8")):
link = target.split("#", 1)[0].split(" ", 1)[0]
if not link or link.startswith(("http://", "https://", "mailto:")):
continue
if "/" not in link and link.endswith(".md"):
continue
offenders.append(f"{page.name} -> {target}")
assert not offenders, (
"repository-relative links in non-.md targets are not caught by mkdocs "
"build --strict; make them absolute github.com URLs: "
f"{offenders}"
)
def test_pages_do_not_link_to_external_webpages() -> None:
offenders: list[str] = []
for page in _pages():
for target in LINK.findall(page.read_text(encoding="utf-8")):
if target.startswith(("http://", "https://")):
offenders.append(f"{page.name} -> {target}")
assert not offenders, f"site pages must keep documentation links internal: {offenders}"
def test_brand_classes_used_by_a_page_are_the_ones_the_stylesheet_defines() -> None:
used: set[str] = set()
for page in _pages():
for attr in CLASS_ATTR.findall(page.read_text(encoding="utf-8")):
used |= {name for name in attr.split() if name.startswith("em-")}
defined = set(CSS_SELECTOR.findall(STYLESHEET.read_text(encoding="utf-8")))
assert used, "no em-* class found on any page -- did the brand markup move?"
assert used == defined, (
f"class used by a page with no rule to style it: {sorted(used - defined)}; "
f"rule no page reaches: {sorted(defined - used)}"
)
def _headings(text: str) -> list[tuple[int, str, str]]:
"""Every heading below the title, with the anchor it will render with."""
found = []
for hashes, raw in HEADING.findall(text):
pinned = ANCHOR.search(raw)
title = re.sub(r"<[^>]+>", "", ANCHOR.sub("", raw)).strip()
found.append((len(hashes), title, pinned.group(1) if pinned else slugify(title, "-")))
return found
def test_chinese_headings_pin_the_anchor_their_english_twin_gets_for_free() -> None:
"""A CJK heading slugifies to nothing, so Markdown numbers it `_1`, `_2`, ...
Those anchors are positional: inserting one heading renumbers every anchor
below it, silently breaking the links other pages and outside readers hold.
An English title slugifies on its own, so the Chinese page has to say the
same anchor out loud for the two to stay reachable by one link.
"""
offenders: list[str] = []
for english in sorted(page for page in _pages() if not page.name.endswith(".zh.md")):
chinese = english.with_name(f"{english.stem}.zh.md")
if not chinese.exists():
continue
left = _headings(english.read_text(encoding="utf-8"))
right = _headings(chinese.read_text(encoding="utf-8"))
if [depth for depth, _, _ in left] != [depth for depth, _, _ in right]:
offenders.append(
f"{english.stem}: heading levels differ, {[d for d, _, _ in left]} vs {[d for d, _, _ in right]}"
)
continue
for (_, en_title, en_anchor), (_, zh_title, zh_anchor) in zip(left, right):
if not zh_anchor:
offenders.append(f"{chinese.name}: {zh_title!r} has no anchor, so Markdown will number it")
elif zh_anchor != en_anchor:
offenders.append(
f"{chinese.name}: {zh_title!r} lands on #{zh_anchor}, but {en_title!r} lands on #{en_anchor}"
)
assert not offenders, "\n".join(offenders)
def _render_page(name: str) -> ET.Element:
html = markdown(
(SITE / name).read_text(encoding="utf-8"),
extensions=["admonition", "attr_list", "md_in_html", "tables", "toc", "fenced_code"],
)
return ET.fromstring(f"<article>{html}</article>")
@pytest.mark.parametrize("language", ["", ".zh"])
@pytest.mark.parametrize("page", PROACTIVITY_LEGACY_SECTIONS)
def test_proactivity_legacy_sections_reach_current_content(page: str, language: str) -> None:
root = _render_page(f"{page}{language}.md")
elements = list(root.iter())
ids = [element.attrib["id"] for element in elements if "id" in element.attrib]
assert len(ids) == len(set(ids)), f"duplicate IDs in {page}{language}"
by_id = {element.attrib["id"]: element for element in elements if "id" in element.attrib}
parents = {child: parent for parent in elements for child in parent}
for target, legacy_ids in PROACTIVITY_LEGACY_SECTIONS[page].items():
target_page, target_id = target.split("#")
destination = _render_page(f"{Path(target_page).stem}{language}.md") if target_page else root
assert any(element.get("id") == target_id for element in destination.iter("h2")), target
for legacy_id in legacy_ids:
assert legacy_id in by_id, f"{page}{language}.md lost #{legacy_id}"
anchor = by_id[legacy_id]
if target_page:
container = parents[anchor]
assert container.tag in {"li", "p"}, f"#{legacy_id} has no visible migration entry"
assert any(
link.get("href") == target and "".join(link.itertext()).strip() for link in container.iter("a")
), f"#{legacy_id} has no migration link to {target}"
else:
next_heading = next(
element for element in elements[elements.index(anchor) + 1 :] if element.tag == "h2"
)
assert next_heading.get("id") == target_id, f"#{legacy_id} lands before the wrong section"
@pytest.mark.parametrize("language", ["", ".zh"])
@pytest.mark.parametrize("page", PROACTIVITY_LEGACY_SECTIONS)
def test_proactivity_preserves_published_title_anchors(page: str, language: str) -> None:
title_id = "_1" if language else "proactivity-reference" if page == "proactivity" else page
root = _render_page(f"{page}{language}.md")
assert root.find(f"h1[@id='{title_id}']") is not None
@pytest.mark.parametrize(
"document",
[SITE / "tracing-api.md", SITE / "tracing-api.zh.md", REPO / "docs" / "TRACING_STANDARD_API.md"],
)
def test_tracing_descriptor_documentation_points_to_bundled_files(document: Path) -> None:
paths = re.findall(r"`([^`\n]+/descriptors/)`", document.read_text(encoding="utf-8"))
assert paths, f"{document.name} does not name the bundled descriptor directory"
for path in paths:
directory = REPO / path
assert directory.is_dir(), f"{document.name} points to missing directory {path}"
assert any(directory.glob("*.json")), f"{path} has no bundled JSON descriptors"