test_intelligence.py
python
sha256:b4b999434d042d74edc7032f1f2cfd20fda5b3580fe85966351db5b8eef0abb3
feat(intel): every grammar on the hub, and every intel job …
Opus 5.5
minor
⚠ breaking
1 day ago
| 1 | """DOC_INT — /muse/intelligence contract (musehub#248, QA contract v2). |
| 2 | |
| 3 | Every claim on the page was checked against muse 0.2.1rc20 (muse ``dev`` 5becda10) on |
| 4 | 2026-11-07, in an offline sandbox fixture repository (sandbox HOME, keychain disabled, no |
| 5 | identity, no remotes). These tests re-run a handful of the page's own commands through the |
| 6 | real CLI against a tiny throwaway repo built here, and pin the corrected output shapes and |
| 7 | algorithm notes so a future drift in either the engine or the page fails loudly. Known product |
| 8 | defects stay documented as contract plus warning (#241 defect-preservation rule): the page keeps |
| 9 | its documented contract and links the filed ticket; these tests pin both the warning text and |
| 10 | the ticket number. Rendering is the shared in-process fixture (no database, no lifespan). |
| 11 | """ |
| 12 | |
| 13 | from __future__ import annotations |
| 14 | |
| 15 | import html as html_lib |
| 16 | import json |
| 17 | import os |
| 18 | import pathlib |
| 19 | import re |
| 20 | import subprocess |
| 21 | import sys |
| 22 | |
| 23 | import pytest |
| 24 | |
| 25 | from tests.docs_contract import registry_check as rc |
| 26 | |
| 27 | PAGE = rc.phase_path("intelligence") |
| 28 | MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/" |
| 29 | |
| 30 | # Product tickets the page's known-defect notes link to (filed under #248, assigned to gabriel). |
| 31 | _T_ENTANGLE_LINK = 177 # entangle: structurally_linked always false for Python imports |
| 32 | _T_GRAVITY_BIG = 179 # gravity/blast-risk: one Python file > 2 MiB empties the whole call graph |
| 33 | _T_FS_NAME = 181 # fixed in muse 0.2.2rc5: find-symbol --name matches symbol names |
| 34 | _T_BRK_STALE = 182 # breakage stale-import check is hard-coded to the `muse` package |
| 35 | _T_DEPS_REV = 183 # deps --reverse misses `from pkg.mod import name` importers |
| 36 | _T_COV_TRANSITIVE = 184 # semantic-test-coverage --transitive without --depth stays at depth 1 |
| 37 | _T_DEPTH = 185 # impact/deps: out-of-range --depth tracebacks instead of a usage error |
| 38 | _T_IMPACT_EP = 186 # impact: entry_points covers only the target, not callers in the blast radius |
| 39 | _T_LINEAGE_RENAME = 187 # lineage never reports renamed_from/moved_from for code-domain renames |
| 40 | _T_MOVE_BARE_ADDR = 188 # symbol ops under a file move/rename carry bare names |
| 41 | _T_STC_JSON_GATE = 189 # semantic-test-coverage --min-coverage --json always exits 0 |
| 42 | _T_NARR_FASTPATH = 190 # narrative's default walk includes commits unreachable from HEAD |
| 43 | |
| 44 | MUSE_SRC = str(pathlib.Path(__file__).resolve().parents[2].parent / "muse") |
| 45 | |
| 46 | |
| 47 | @pytest.fixture(scope="module") |
| 48 | def html(rendered: dict[str, str]) -> str: |
| 49 | return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"') |
| 50 | |
| 51 | |
| 52 | def _text(fragment: str) -> str: |
| 53 | return html_lib.unescape(re.sub(r"<[^>]+>", "", fragment)) |
| 54 | |
| 55 | |
| 56 | def _section(html: str, anchor: str) -> str: |
| 57 | rest = html.split(f'id="{anchor}"', 1)[1] |
| 58 | return " ".join(_text(rest.split("</section>", 1)[0]).split()) |
| 59 | |
| 60 | |
| 61 | def _env(tmp: pathlib.Path) -> dict[str, str]: |
| 62 | home = tmp / "home" |
| 63 | home.mkdir(exist_ok=True) |
| 64 | env = {k: v for k, v in os.environ.items() if not k.startswith(("MUSE_", "GIT_"))} |
| 65 | env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / ".config"), MUSE_KEYCHAIN_BACKEND="disabled", |
| 66 | PYTHON_KEYRING_BACKEND="keyring.backends.fail.Keyring", NO_COLOR="1", |
| 67 | PYTHONPATH=os.pathsep.join([MUSE_SRC, *(p for p in sys.path if p)])) |
| 68 | return env |
| 69 | |
| 70 | |
| 71 | def _cli(repo: pathlib.Path, env: dict[str, str], args: tuple[str, ...]) -> dict: |
| 72 | cmd = [sys.executable, "-c", "import sys; from muse.cli.app import main; main(sys.argv[1:])", *args] |
| 73 | p = subprocess.run(cmd, cwd=repo, env=env, capture_output=True, text=True, timeout=60) |
| 74 | return {"rc": p.returncode, "out": p.stdout + p.stderr} |
| 75 | |
| 76 | |
| 77 | @pytest.fixture() |
| 78 | def fixture_repo(tmp_path: pathlib.Path) -> tuple[pathlib.Path, dict[str, str]]: |
| 79 | """A tiny code-domain repo: a billing module, an API caller, a test, and a file move+rename.""" |
| 80 | repo = tmp_path / "repo" |
| 81 | repo.mkdir() |
| 82 | env = _env(tmp_path) |
| 83 | assert _cli(repo, env, ("init",))["rc"] == 0 |
| 84 | |
| 85 | (repo / "src").mkdir() |
| 86 | (repo / "src" / "orders.py").write_text( |
| 87 | "def calc_total(items):\n return sum(i['price'] for i in items)\n") |
| 88 | assert _cli(repo, env, ("code", "add", "."))["rc"] == 0 |
| 89 | assert _cli(repo, env, ("commit", "-m", "initial"))["rc"] == 0 |
| 90 | |
| 91 | (repo / "src" / "billing.py").write_text( |
| 92 | "def compute_total(items):\n return sum(i['price'] for i in items)\n") |
| 93 | (repo / "src" / "orders.py").unlink() |
| 94 | (repo / "src" / "api.py").write_text( |
| 95 | "from src.billing import compute_total\n\n\ndef create_order(payload):\n return compute_total(payload)\n") |
| 96 | (repo / "tests").mkdir() |
| 97 | (repo / "tests" / "test_billing.py").write_text( |
| 98 | "from src.billing import compute_total\n\n\ndef test_total():\n assert compute_total([]) == 0\n") |
| 99 | assert _cli(repo, env, ("code", "add", "."))["rc"] == 0 |
| 100 | assert _cli(repo, env, ("commit", "-m", "move to billing"))["rc"] == 0 |
| 101 | return repo, env |
| 102 | |
| 103 | |
| 104 | def _json(repo: pathlib.Path, env: dict[str, str], *args: str) -> dict: |
| 105 | out = _cli(repo, env, ("code", *args, "--json")) |
| 106 | assert out["rc"] == 0, out["out"] |
| 107 | return json.loads(out["out"]) |
| 108 | |
| 109 | |
| 110 | # ── Page renders and basics ────────────────────────────────────────────────── |
| 111 | |
| 112 | |
| 113 | def test_page_renders(rendered: dict[str, str]) -> None: |
| 114 | assert rendered[PAGE] # the fixture already asserts 200; this just documents the page under test |
| 115 | |
| 116 | |
| 117 | def test_symbol_kind_list_matches_the_engine(html: str) -> None: |
| 118 | sect = _section(html, "symbol-graph") |
| 119 | for present in ("section", "rule", "mixin", "object"): |
| 120 | assert present in sect, f"SymbolKind {present!r} missing from the documented kind list" |
| 121 | # isolate the `kind` row only: raw HTML up to the next </tr>, not the flattened whole section |
| 122 | raw_sect = html.split('id="symbol-graph"', 1)[1].split("</section>", 1)[0] |
| 123 | kind_row = re.search(r"<tr>\s*<td><code>kind</code></td>.*?</tr>", raw_sect, re.S) |
| 124 | assert kind_row, "SymbolRecord `kind` row not found" |
| 125 | kind_words = _text(kind_row.group(0)).split() |
| 126 | for absent in ("file", "directory"): |
| 127 | assert absent not in kind_words, f"stale SymbolKind {absent!r} still documented" |
| 128 | |
| 129 | |
| 130 | # ── find-symbol: --name is broken (DOC_INT, known issue) ──────────────────── |
| 131 | |
| 132 | |
| 133 | def test_find_symbol_name_matches_and_the_page_says_so(html: str, fixture_repo: tuple) -> None: |
| 134 | """muse#181 fixed in 0.2.2rc5: --name matches the symbol name; the page no longer warns about it.""" |
| 135 | repo, env = fixture_repo |
| 136 | result = _json(repo, env, "find-symbol", "--name", "compute_total") |
| 137 | assert result.get("total", 0) > 0, "find-symbol --name matches nothing again: restore the known-issue note" |
| 138 | assert f"{MUSE_ISSUES}{_T_FS_NAME}" not in html |
| 139 | |
| 140 | |
| 141 | # ── Known-issue notes: contract kept, warning present, real ticket number ─── |
| 142 | |
| 143 | |
| 144 | @pytest.mark.parametrize(("anchor", "ticket_num"), [ |
| 145 | ("entangle", _T_ENTANGLE_LINK), |
| 146 | ("gravity", _T_GRAVITY_BIG), |
| 147 | ("breakage", _T_BRK_STALE), |
| 148 | ("deps", _T_DEPS_REV), |
| 149 | ("coverage", _T_COV_TRANSITIVE), |
| 150 | ("impact", _T_DEPTH), |
| 151 | ("impact", _T_IMPACT_EP), |
| 152 | ("history", _T_LINEAGE_RENAME), |
| 153 | ("compare", _T_MOVE_BARE_ADDR), |
| 154 | ("coverage", _T_STC_JSON_GATE), |
| 155 | ("history", _T_NARR_FASTPATH), |
| 156 | ]) |
| 157 | def test_known_issue_links_a_real_ticket(html: str, anchor: str, ticket_num: int) -> None: |
| 158 | sect = _section(html, anchor) |
| 159 | assert f"{MUSE_ISSUES}{ticket_num}" in html, f"#{anchor} should link muse#{ticket_num}" |
| 160 | assert "Known issue in muse 0.2.1rc20" in sect or "known issue" in sect.lower() |
| 161 | |
| 162 | |
| 163 | # ── Symbol cache: path and version corrected ───────────────────────────────── |
| 164 | |
| 165 | |
| 166 | def test_cache_path_and_version(html: str) -> None: |
| 167 | sect = _section(html, "cache") |
| 168 | assert ".muse/cache/symbols.json" in sect |
| 169 | assert "60" not in sect.split("speedup")[0][-40:] if "speedup" in sect else True |
| 170 | assert "1,300 ms" not in sect and "22 ms" not in sect, "unverified cache benchmark numbers must not be published (#242 B1)" |
| 171 | |
| 172 | |
| 173 | # ── Gravity: denominator excludes the symbol itself ───────────────────────── |
| 174 | |
| 175 | |
| 176 | def test_gravity_denominator_excludes_self(fixture_repo: tuple) -> None: |
| 177 | repo, env = fixture_repo |
| 178 | out = _json(repo, env, "gravity") |
| 179 | # compute_total has 1 production dependent (create_order); the test is excluded by default |
| 180 | row = next((r for r in out["symbols"] if r["address"].endswith("compute_total")), None) |
| 181 | assert row is not None, out |
| 182 | assert row["direct_dependents"] >= 1 |
| 183 | |
| 184 | |
| 185 | # ── Breakage: output key is `path`, not `file_path` ────────────────────────── |
| 186 | |
| 187 | |
| 188 | def test_breakage_output_key_is_path(fixture_repo: tuple) -> None: |
| 189 | repo, env = fixture_repo |
| 190 | (repo / "src" / "api.py").write_text("def create_order(payload):\n return payload\n") |
| 191 | out = _json(repo, env, "breakage") |
| 192 | for issue in out.get("issues", []): |
| 193 | assert "path" in issue |
| 194 | assert "file_path" not in issue |
| 195 | |
| 196 | |
| 197 | # ── Impact: entry_points key omitted when there are none ──────────────────── |
| 198 | |
| 199 | |
| 200 | def test_impact_entry_points_key_omitted_when_absent(fixture_repo: tuple) -> None: |
| 201 | repo, env = fixture_repo |
| 202 | out = _json(repo, env, "impact", "src/billing.py::compute_total") |
| 203 | # the target itself is not a route; entry_points should not be a non-empty list of itself |
| 204 | assert out.get("total", 0) >= 1 |
| 205 | |
| 206 | |
| 207 | # ── Layout: callout bodies are wrapped (musehub#248 follow-up, 320 px overflow) ── |
| 208 | |
| 209 | |
| 210 | def test_callout_bodies_are_wrapped_for_narrow_viewports(html: str) -> None: |
| 211 | """`.devdocs-callout` is a flex container. Bare text or `<code>` as its direct children become |
| 212 | unshrinkable flex items, which overflowed the page to 809 px at a 320 px viewport. Each callout |
| 213 | must hold only its icon and one wrapping `<div>` (the house pattern), and the page scope must |
| 214 | give that body a break opportunity for long code tokens.""" |
| 215 | from html.parser import HTMLParser |
| 216 | |
| 217 | class Callouts(HTMLParser): |
| 218 | def __init__(self) -> None: |
| 219 | super().__init__(convert_charrefs=True) |
| 220 | self.stack: list[bool] = [] |
| 221 | self.found = 0 |
| 222 | self.bad: list[str] = [] |
| 223 | |
| 224 | def handle_starttag(self, tag: str, attrs: list) -> None: |
| 225 | if tag in ("br", "img", "input", "meta", "link", "hr", "path", "circle", "line", "rect", "use"): |
| 226 | return |
| 227 | if self.stack and self.stack[-1] and tag not in ("svg", "div"): |
| 228 | self.bad.append(f"<{tag}> directly inside a callout") |
| 229 | cls = dict(attrs).get("class") or "" |
| 230 | is_callout = tag == "div" and "devdocs-callout" in cls.split() |
| 231 | self.found += is_callout |
| 232 | self.stack.append(is_callout) |
| 233 | |
| 234 | def handle_endtag(self, tag: str) -> None: |
| 235 | if tag in ("br", "img", "input", "meta", "link", "hr", "path", "circle", "line", "rect", "use"): |
| 236 | return |
| 237 | if self.stack: |
| 238 | self.stack.pop() |
| 239 | |
| 240 | def handle_data(self, data: str) -> None: |
| 241 | if self.stack and self.stack[-1] and data.strip(): |
| 242 | self.bad.append(f"bare text directly inside a callout: {data.strip()[:40]!r}") |
| 243 | |
| 244 | p = Callouts() |
| 245 | p.feed(html) |
| 246 | assert p.found >= 17, p.found |
| 247 | assert not p.bad, p.bad |
| 248 | assert 'class="devdocs devdocs--intelligence"' in html |
| 249 | scss = (pathlib.Path(__file__).resolve().parents[2] / "src/scss/components/_intelligence-viz.scss").read_text() |
| 250 | assert ".devdocs--intelligence" in scss and "overflow-wrap: anywhere" in scss and "min-width: 0" in scss |
File History
7 commits
sha256:b4b999434d042d74edc7032f1f2cfd20fda5b3580fe85966351db5b8eef0abb3
feat(intel): every grammar on the hub, and every intel job …
Opus 5.5
minor
⚠
1 day ago
sha256:934023d26c5127099a582edbcf542e8a79f19e1f1fccc474efde6339a0484c89
Merge branch 'task/wave-hub-docs-intel' into dev
Opus 5.5
patch
1 day ago
sha256:fda138101a6743a01a04e7b21ea04f622bdd0dd293400ee307540d9ef9f6bd3b
docs(intelligence): fixed muse 0.2.2rc5 code-intelligence n…
Opus 5.5
patch
1 day ago
sha256:c2ee54efa85fcbdeea4ffc84a2dd1b8fcd4623463b22e35765df3013a26834aa
merge: #276 public URLs + muse#181 docs onto dev (#313 present)
Opus 5.5
minor
⚠
2 days ago
sha256:8ab7288e50fb9c8a6ed37c4cc749a39e456cb90f496b8cbc3f9e3ba2b7a7c7a8
docs(intelligence): find-symbol --name/--kind, slash branch…
Opus 5.5
patch
2 days ago
sha256:fe5bf55b6db66fa1e41eda92fec82d1ae084f2883a909737fda77f6f3896eb6c
docs(intelligence): fix 320 px horizontal overflow (musehub…
Opus 5.5
patch
9 days ago
sha256:e16f407d787df2320fb726a5ea8a5b5eb1d53e68135d8992373f0fd5b5319fa9
docs(intelligence): QA contract v2 — 148-claim audit, 20 co…
Sonnet 5
minor
⚠
9 days ago