#854 EPIC: 50 source files exceed the 550-line hard cap - split without module shadowing

closed high file-size tech-debt Created 2026-08-22 11:45 · Updated 2026-08-22 14:31

Description

Edit
EARS SPEC (program-level): - Every source file in the Highway stack shall be at most 500 lines (soft) and shall NEVER exceed 550 lines (hard cap). - When a file is split, the module path callers already import shall keep working unchanged. - The split shall NEVER produce module shadowing: a package and a module of the same name shall not coexist on the same path (e.g. workflows.py alongside workflows/), because the import that resolves is then ambiguous and silently version-dependent. - After every split, the API route table, the tool registry and the CLI command tree shall be byte-identical to the pre-split baseline. SCOPE: 50 source files exceed the 550-line hard cap. Tests, generated models and SQL dumps are excluded per the rule (not code). Full inventory and per-file tickets are children of this epic. REGRESSION ORACLES captured BEFORE any change (2026-08-22), to be re-checked after each split: routes: 283 (rule + endpoint + methods, from api.app.create_app().url_map) tools: 126 (enterprise.tools.registry.get_tool_registry().list_tools()) cli: 50 (enterprise.cli.hwe.cli command tree) A split that changes any of these three counts, or any entry within them, is a regression. ANTI-SHADOWING RULE (explicit, this is the trap): Do NOT create `foo/` next to an existing `foo.py`. Either (a) keep `foo.py` as the public surface and extract into SIBLING modules with DISTINCT names (foo_queries.py, foo_handlers.py), which foo.py imports; or (b) convert `foo.py` INTO `foo/__init__.py` + submodules and DELETE `foo.py`. Never both. Option (a) is preferred for Quart blueprint files, because route registration order and the `v1_bp` decorator surface stay obvious. NOTE ON MEASUREMENT: the inventory uses raw `wc -l` (includes blanks, comments, docstrings). If the cap is intended against logical LOC the list shrinks; confirm before mass-refactoring.

Comments

Loading comments...

Context

Loading context...

Audit History

View All
Loading audit history...