Split oversized modules: dashboard.js (4.6k lines), mcp/server.py, web/reports.py

[hyoshi]

What

Several load-bearing files have grown well past the point where one reader can hold them, measured today (post-v0.13.0):

File	Lines
mureo/_data/web/dashboard.js	4,624
mureo/mcp/server.py	1,559
mureo/web/reports.py	1,070
mureo/mcp/tools_mureo_context.py	916

Why now

Each of the last several changes (#663, #665, #670, #671) paid a growing tax: implementers merge-conflict inside dashboard.js on unrelated features, and reviewers must re-derive which of its ~40 render functions belong to which view. reports_format.js (618 lines) shows the pattern that works — a focused module with its own test file and an export-surface pin in tests/js/browser_contract.test.js.

Proposed cuts (mechanical moves, no behaviour change)

• dashboard.js → keep bootstrapping/nav/bindings; move the reports view renderers (renderReportsLatest, buildReportStat*, triage wiring) next to reports_triage.js/reports_overview.js where their logic already lives; move settings/clients/security view renderers into per-view modules. Every move keeps its DOM pins; browser_contract.test.js re-pins the new surfaces.
• mureo/mcp/server.py → hoist the instructions composition (_server_instructions, _workspace_instruction, _platform_model_instruction, _plugin_tool_owners) into a module; hoist validation/dispatch helpers.
• mureo/web/reports.py → split the STATE.json read layer (document resolution, tolerant re-read) from the summary/aggregation layer.
• mureo/tools_mureo_context.py is at the boundary; split only if a natural seam exists (schema constants vs handlers).

One PR per file, byte-identical behaviour asserted by the existing suites; no API changes.

[hyoshi]

Order of work, and a rule for the dashboard.js cut

Recording two decisions and the measurements behind them, because the dashboard.js half of this issue is harder than the proposal above assumed and whoever picks it up should not have to re-derive why.

Order: mcp/server.py and web/reports.py first, dashboard.js last. Python has no static text pins of the kind dashboard.js has (below), so those two can be proved equivalent by "existing suites unmodified, all green" alone. #684 does the first of them.

Why dashboard.js cannot be split without touching the pytest pins

dashboard.js has no test runner that can drive its DOM, so twenty pytest files pin its behaviour by grepping the served asset — 126 read-sites of _read("dashboard.js") / (_WEB / "dashboard.js").read_text(). Two shapes:

1. Signature pins. Sixteen call sites use

   def _function_body(js: str, signature: str) -> str:
       assert signature in js, f"{signature} missing"

   as _function_body(_read("dashboard.js"), "function renderReportsLatest("). The sixteen functions pinned this way are exactly the ones this issue proposes moving: renderReportsLatest, buildReportStatElement, buildReportStatsRow, buildReportCard, buildClientCard, buildClientCardItem, buildTriageRow, renderReportsTriage, renderReportsPortfolio, buildPortfolioFigureCell, renderReportsPlatforms, renderReportsActionFeed, buildReportsFeedRow, renderReportsIndex, setReportsView, renderReports, applyReportsHealthFilter.

2. String pins on i18n keys, data-* attributes and endpoints. A pin breaks when every occurrence of its string moves out. Counting only those, per candidate region:

   region	lines	pins that go unsatisfied
   reports renderers	1,928	252
   plugin credentials	619	41
   about / updates	394	26
   host / basic / providers / env / creative-studio / demo	791	21
   BYOD + native	310	8
   creative gallery	116	7
   advisors	229	2

   No function in the file is free of pins, and there is exactly one unpinned contiguous run of ≥25 lines in all 4,624.

Consequence: the "≤800 lines per file" target is unreachable while the pins stand — the floor for dashboard.js is roughly 3,700 lines.

Rule 1 — the pytest pins may be retargeted mechanically

When dashboard.js is split, _read("dashboard.js") → _read("<new module>.js") at the affected read-sites is allowed. Signatures and assertion contents stay identical; only the file the assertion reads changes. The equivalence proof is then the one bridge #133 used, not "tests untouched":

• verbatim confirmation of each moved block,
• per-function normalised-text equality between old and new,
• an accounting of every line that did not move.

Rule 2 — three manifests are implementation, not test

Adding a filename to any of these is part of the change, the same way adding a <script> tag to app.html is:

• tests/js/dom_harness.js — its load array is a mirror of app.html's <script> order, not an assertion. No split of any size is possible without it: the harness evaluates exactly six files, so a new module would simply never run and every harness-driven suite would see undefined renderers.
• MODULES in tests/js/browser_contract.test.js — a new row is forced for any new reports_*.js, since the table is deepEqual-checked against the directory glob. Rows may be added; existing rows may not be rewritten. A new module also needs its entry in dashboard.js's missingReportsModules guard.
• _STATIC_ALLOWLIST in mureo/web/handlers.py — plainly implementation.

Baselines at the time of measuring (ddaa398)

node --test tests/js/*.test.js → 355 pass, 0 fail. The web-asset pytest group (test_web_assets_*.py, test_web_about.py, test_report_kind_vocabulary.py, test_web_static_serving.py) → 359 passed, none skipped.

[hyoshi]

mureo/mcp/tools_mureo_context.py — measured, and not split

The issue put this file "at the boundary; split only if a natural seam exists (schema constants vs handlers)". Measured against the real file, that seam does not exist, and the one cut that is available makes the file harder to read rather than easier. Recording the numbers so nobody re-derives them.

The coupling that blocked mcp/server.py is absent here

	mcp/server.py	tools_mureo_context.py
importlib.reload of the module in tests	5 suites	none
monkeypatch.setattr on its own names	11 names	none
tests reading it as source text	n/a	none
external surface	40+ names	TOOLS, handle_tool

So this file could be cut. The reason not to is the shape of what is in it.

Anatomy

block	lines
docstring + imports	56
_METRICS_WINDOWS, _PERIOD_BUCKET_PROPERTY, _PATH_PROPERTY	21
_ACTION_LOG_ENTRY_PROPERTY	145
_ADS_PROPERTY	46
_CAMPAIGN_PROPERTY	105
TOOLS — one list literal, 11 Tool(...) entries	515
_HANDLERS + handle_tool	28

Roughly 90% of the file is one declarative data structure. The only executable code is an 11-line dispatcher.

Why the proposed seam is not there

The handlers are already extracted. mureo/mcp/_handlers_mureo_context.py is 568 lines and holds every handler this module dispatches to. The "schema constants vs handlers" cut has already happened; what is left on this side is the schemas plus the tool list.

The "constants" are not a shared vocabulary — 93% of them are one tool's schema each. Counting call sites:

• _ACTION_LOG_ENTRY_PROPERTY (145 lines) — 1 use, by mureo_state_action_log_append
• _CAMPAIGN_PROPERTY (105 lines) — 1 use, by mureo_state_upsert_campaign
• _ADS_PROPERTY (46 lines) — 1 use, nested inside _CAMPAIGN_PROPERTY
• _PERIOD_BUCKET_PROPERTY (9 lines) — 1 use
• _METRICS_WINDOWS (2 lines) — 2 uses
• _PATH_PROPERTY (10 lines) — 10 uses

They were hoisted out of the Tool(...) literals for line length, not for reuse. Moving them to a sibling module would put a tool's own input schema in a different file from its Tool(...) entry, so "what arguments does mureo_state_upsert_campaign accept?" becomes a two-file question. That is the opposite of what #678 is for.

The genuinely shared vocabulary is _PATH_PROPERTY + _METRICS_WINDOWS + _PERIOD_BUCKET_PROPERTY = 21 lines. A module for 21 lines is glue heavier than body — the same test that decided the shape of #684.

Splitting TOOLS in half would desynchronise it from _HANDLERS. The two are keyed by the same 11 tool names and are already the one place those names are written down twice. An 11-element list has no seam in it, so any cut is arbitrary, and a TOOLS = [*TOOLS_A, *TOOLS_B] reassembly would leave two files free to drift from the dispatch table. That is the exact failure #680 was filed about — a hand-maintained second answer to "which tools exist" falling one entry behind.

Conclusion

Not split. The 800-line threshold exists for code a reader has to hold at once; eleven independent schema literals and an 11-line dispatcher do not compound the way 4,624 lines of interdependent DOM renderers did. Re-open this if the tool count grows enough that the list itself becomes the problem — at that point the cut is per-tool-family (_tools_context_strategy.py / _tools_context_state.py) with _HANDLERS derived from the same tables, not schemas-vs-tools.

One finding, not fixed here

The module docstring opens "Ten tools that expose mureo's context layer over MCP". There are 11 (TOOLS has 11 entries, _HANDLERS has 11 keys). No test pins that sentence, which is why it went stale — the same class of drift #679 pinned for the documented MCP total. Left alone so this issue closes with no code change; worth a one-line fix on the next pass through the file.

[hyoshi]

Closing. All four files named here have been measured and dealt with.

file	lines then	outcome
mureo/_data/web/dashboard.js	4,624	332 + 7 section modules — #686
mureo/mcp/server.py	1,559	1,163 + 2 modules — #684
mureo/web/reports.py	1,070	386 + 2 modules — #685
mureo/mcp/tools_mureo_context.py	916	not split — measured above, no seam

Twelve new modules, every moved function verbatim, no behaviour change and no API change in any of the three PRs.

What this issue actually taught

Two of the four files did not reach the 800-line target, and in both cases the obstacle was structural rather than a lack of effort. Worth keeping, because it will decide how the next split is planned:

• mcp/server.py (1,163) — importlib.reload(mureo.mcp.server) is how five suites re-trigger startup, so every module-level statement that builds the registry has to stay in that one module body; and eleven names are monkey-patched on the module, so each dispatch chain has to stay whole. Only functions of their arguments could move.
• dashboard_reports.js (2,110) — six lets are written on one side of every candidate seam and read on the other, and two <script> IIFEs cannot share a let. Cutting needs the view state promoted onto an object, which is a redesign rather than a move. Filed as Split dashboard_reports.js (2,110 lines): promote the Reports view state so the file can be cut #687.
• web/reports.py cut cleanly precisely because it had none of that: no reload, no monkey-patch on its own names, and its one patch seam (get_runtime_context) had already been moved to report_clients.py.

The rule that came out of it, and that #686 ran on: a file is splittable when nothing reloads it, nothing patches names on it, and its state does not straddle the seam. Test pins — the 121 _read("dashboard.js") sites — turned out to be the cheap part, mechanically retargetable with assertion content unchanged. Test mechanisms (reload, monkey-patch) are the expensive part.

Remaining work is tracked in #687.