Tech debt: decompose oversized modules — `resolver.rs` (2554L) and `build.rs` (2020L) block safe incremental work

[dean0x]

Rescoped 2026-08-09 against 113f472.

• Size drift corrected. crates/mds-core/src/resolver.rs 2518 -> 2554 lines; crates/mds-cli/src/build.rs 1964 -> 2020 lines.
• Location fix (the material one). The body located process_module_intrinsic_opts and process_module in build.rs. Both are actually in crates/mds-core/src/resolver.rs. Phase 1 was therefore scoped as a build.rs-only phase; it is not — it spans both files.
• Function sizes corrected. run_build 265 -> 348 L; process_module_intrinsic_opts 163 -> 203 L; process_module 128 -> 355 L. process_module nearly tripled against the recorded figure and is now the largest of the three.
• Absorbed two folded-in items: CX-2 from Refactor oversized source-map core functions (CX-1, CX-2, CX-3) #184 and ISS-25 from build.rs DRY: consolidate embed_sources warnings and sidecar/stdout ladder duplication #229. Both name functions already inside this issue's scope; see the table below. (Linking comments are being filed separately on the origin issues.)
• Sequencing constraint recorded: this issue is scheduled strictly last among all waves.
• The title still carries the pre-rescope figures (2518L / 1964L). This pass edits bodies only; the body is authoritative.
• Figures not listed above (the six #[allow(clippy::too_many_arguments)] annotations, the watch.rs context-struct line references) were not re-measured in this pass and should be re-checked before Phase 3 starts.

Correction 2026-08-26 (6d41777) — one figure was materially wrong, not merely drifted:

• process_module is 127 L, not 355 L. Measured crates/mds-core/src/resolver.rs:1006-1132. It was also 127 L at the 113f472 rescope baseline (measured 997-1123 in git show 113f472:crates/mds-core/src/resolver.rs), so the recorded "355 L / nearly tripled" claim was wrong when written — it is not drift. This materially over-sizes the Phase 1 decomposition being proposed: process_module is not the largest of the three and may not warrant extraction at all under the <= 80 L criterion.
• resolver.rs 2554 -> 2564 L; build.rs 2020 -> 2071 L (both grew).
• run_build 348 -> 335 L (crates/mds-cli/src/build.rs:1081-1415; cited :1051 is stale).
• process_module_intrinsic_opts 203 -> 198 L (crates/mds-core/src/resolver.rs:777-974; cited :768 is stale).
• #[allow(clippy::too_many_arguments)] count in watch.rs/error.rs is 4, not 6 — watch.rs:1039, watch.rs:1951, watch.rs:2316, error.rs:576. (A fifth exists at crates/mds-python/src/lib.rs:464, outside Phase 3 scope.) This figure was flagged "not re-measured" in the 2026-08-09 pass; it is now measured.
• Scope, phasing, and acceptance criteria are unchanged.

---

Background

crates/mds-core/src/resolver.rs (2564 lines) and crates/mds-cli/src/build.rs (2071 lines) are the two largest files in the codebase. Both exceed the practical size threshold for safe incremental modification. Within each file, several functions have accumulated #[allow(clippy::too_many_arguments)] annotations (watch.rs/error.rs carry 4 pre-existing allows), and the three largest individual functions are:

Function	File	Size
run_build	crates/mds-cli/src/build.rs:1081-1415	335 L
process_module_intrinsic_opts	crates/mds-core/src/resolver.rs:777-974	198 L
process_module	crates/mds-core/src/resolver.rs:1006-1132	127 L — was recorded as 355 L; that figure was wrong

Ledger ID: #91 (complexity-preexisting_oversized_modules)
Originating reviewer: Complexity (pre-existing informational)

Absorbed items

This issue now subsumes two findings filed elsewhere against functions already in its scope:

Folded in	Origin	Function	Location	Size
CX-2	#184	process_module_intrinsic_opts	crates/mds-core/src/resolver.rs:768	203 L
ISS-25	#229	run_build	crates/mds-cli/src/build.rs:1051	348 L

Neither is separately actionable — extracting either function without the surrounding decomposition just relocates the problem.

Problem

At 2564 lines, resolver.rs contains the compiler's resolution logic, import threading, type inference, span construction, and the two oversized module-processing functions (process_module, process_module_intrinsic_opts) in a single module. PR #196 threaded additional arguments through this module (+125 lines) without worsening structure, but the module is already past the upper bound of what can be safely modified without unintended coupling.

At 2071 lines, build.rs contains the CLI build driver, source-map construction, and output formatting interleaved, with run_build (335 L) as the driver.

Four pre-existing #[allow(clippy::too_many_arguments)] annotations in watch.rs and error.rs are the same category: functions that grew beyond the point where introducing a context struct is the obvious fix.

Sequencing constraint — this issue goes LAST

#223 is scheduled strictly last among all waves. It rewrites resolver.rs and build.rs wholesale. Every behavior fix that touches either file would have to be rebased across this decomposition if it landed first, so all such work ships before #223 starts, not after. Do not pull this forward to unblock anything — nothing is blocked by it.

Why deferred from PR #196

Decomposing a 2500+-line resolver is a system restructure, not a refactor. It must be sequenced against ADR-005 sourcemap threading and ADR-001 formatter gate work that both run through these modules. Explicitly out of scope for a pre-release remediation branch.

Proposed approach

This is not a single PR — it is a phased decomposition:

1. Phase 1 — Extract the three oversized functions. run_build -> BuildPipeline::run() in build.rs; process_module_intrinsic_opts -> IntrinsicOpts::apply() and process_module -> ModuleProcessor::process(), both out of resolver.rs, not build.rs. These have clear seams. This phase closes CX-2 (Refactor oversized source-map core functions (CX-1, CX-2, CX-3) #184) and ISS-25 (build.rs DRY: consolidate embed_sources warnings and sidecar/stdout ladder duplication #229).

2. Phase 2 — resolver.rs module split: separate resolution/import-threading from span-construction and type-inference. This needs design work first (ADR on module boundaries).

3. Phase 3 — watch.rs/error.rs context structs: replace #[allow(clippy::too_many_arguments)] functions with FileCompileCtx/DirWatchCtx structs (the pattern already introduced in watch.rs for the same reason — see issue Tech Debt Backlog #6 and PR fix: v0.4.0 remediation — dogfooding blockers, bug batch, UX polish, docs sweep #196 notes; re-locate those references before starting, they were not re-measured in this rescope).

Acceptance Criteria

Each phase has its own AC; tracked here as the umbrella:

• Phase 1: all three oversized functions extracted — run_build out of build.rs, process_module and process_module_intrinsic_opts out of resolver.rs — each replaced by a unit of <= 80 lines
• Phase 1: build.rs reduced to <= 500 lines with functions <= 80 lines each
• Phase 1: CX-2 (Refactor oversized source-map core functions (CX-1, CX-2, CX-3) #184) and ISS-25 (build.rs DRY: consolidate embed_sources warnings and sidecar/stdout ladder duplication #229) are resolved by this phase and closed against it
• Phase 2: resolver.rs split into at least 2 sub-modules; no single file exceeds 1000 lines
• Phase 3: All #[allow(clippy::too_many_arguments)] in watch.rs/error.rs eliminated via context structs
• Cargo test suite passes at each phase boundary
• No #[allow(clippy::too_many_arguments)] added in any phase

Deferred from: PR #196 (identified as pre-existing, explicitly not in scope for remediation)
Absorbs: CX-2 (#184), ISS-25 (#229)
Note: This is a multi-sprint effort, scheduled last. Open sub-issues per phase as work begins.

Reference-corrected 2026-08-26 against main @ 6d41777 — locations and completion state only; scope and acceptance criteria unchanged.

[dean0x]

Absorbed scope (2026-08-09, verified against 113f472)

This issue now absorbs two items that were previously tracked separately. Both were partial folds — their parent issues stay open for their remaining items.

Absorbed item	Function	Location	Size	Folded from
CX-2	process_module_intrinsic_opts	crates/mds-core/src/resolver.rs:768	203 L	#184 (CX-1 and CX-3 remain open there)
ISS-25	run_build	crates/mds-cli/src/build.rs:1051	348 L	#229 (ISS-07 and ISS-20 remain open there)

Both functions are already named by this issue's decomposition scope, so tracking them separately was redundant.

Not folded: #184's CX-1 (invoke_function, crates/mds-core/src/evaluator.rs:587, 194 L) stays in #184 — its duplicated call-stack tail is safety-critical and #184's own body forbids folding it into a sweep. #184's CX-3 (evaluate_nodes, evaluator.rs:209, 167 L) also stays in #184.