draft: Proposal: Modular Refactoring — Split 6 Coupling Hotspots#3
Merged
Conversation
added 5 commits
April 21, 2026 00:23
…d by graph analysis Graph analysis (3128 nodes, 5713 edges) revealed 6 modules with degree 10-100x above average (3.65). This proposal splits them into focused sub-modules following clean architecture, with re-export hubs for backward compatibility. Hotspots: Export.HTML (436), Domain.Types (342), LSP.Client (292), UseCase.Extract (254), Domain.Graph (208), Export cross-coupling. 15 subtasks organized in 7 dependency-ordered batches.
… sub-modules Domain.Types (342 degree) → Node, Edge, Graph, Pipeline, Analysis sub-modules + re-export hub for backward compatibility. Domain.Graph (208 degree) → Core, Query, Analysis, Diff sub-modules + re-export hub (extending existing FGL sub-module pattern). All 75 tests pass. Build compiles with -Wall -Werror.
…se + Extraction LSP.Client (292 degree) → 4 sub-modules: - ServerMap: 30+ language→server command mappings + findLSPServer - Transport: JSON-RPC messaging, connectToLSP, disconnectLSP - CapabilityParse: server capability parsing from init responses - Extraction: document symbols, workspace symbols, symbol→node/edge conversion LSP.Client is now a thin re-export hub. All 75 tests pass.
UseCase.Extract (254 degree) → 3 sub-modules: - Extract.Haskell: stub extraction, parse imports/decls, makeStubNode - Extract.Markdown: doc extraction, headers, tags, wikilinks - Extract remains the composition orchestrator (LSP dispatch, threading, merging) All 75 tests pass. Build compiles with -Wall -Werror.
Triggered on v* tags. Uses same GHC/Cabal setup as CI. After build + test pass, copies the binary and SHA256 checksum to a GitHub Release via softprops/action-gh-release.
jeremiepas
force-pushed
the
refactor/modular-split-hotspots
branch
from
bf8919e to
a5e9b19
Compare
added 3 commits
April 21, 2026 09:19
When HLS crashes mid-extraction, hPutBuf throws 'resource vanished (Broken pipe)'. The sendLSPMessage call in extractDocumentSymbols was not wrapped in catch, so the exception propagated up and killed the entire LSP group extraction. Now returns [] on failure, matching the error handling pattern of extractViaLSP and extractWorkspaceSymbols.
HLS runs cabal v2-repl to determine build flags before responding to the initialize request. This can take 2-3 minutes on first run, often causing the previous 60s timeout to fire. Changes: - defaultLSPConfig lspTimeout: 60 → 300 seconds - extractAll/extractFromFile lspTimeout: 60 → 300 seconds - Better timeout error message with HLS-specific tip
Two strategies to bridge the code-documentation gap: 1. Name alignment: doc nodes whose label matches a code node label get References edges (e.g. doc mentions 'Boond.Types' → code node) 2. Path alignment: doc file 'Foo.md' ↔ code file 'Foo.hs' sharing the same base name get References edges Applied at all density levels (even Sparse) since code↔doc linking is fundamental for knowledge graph navigation. Fixes the issue where extracted graphs had 0 edges between code and documentation nodes due to incompatible NodeId schemes.
jeremiepas
changed the title
Add IORef connection state to LSPClient with isProcessAlive check and sendLSPMessageSafe that catches IOException (ResourceVanished) instead of letting it crash the process. All extraction call sites now use the safe send. disconnectLSP skips cleanup when already disconnected.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Hotspots Identified
Infrastructure.Export.HTMLDomain.TypesInfrastructure.LSP.ClientUseCase.ExtractDomain.GraphRefactoring Strategy
Domain.Export.VisualizationDomain.Export.Formattype class to eliminate CommunityGraph mediatorExecution Plan
15 subtasks in 7 dependency-ordered batchesed. Each step must pass
cabal build+cabal testindependently.Full Proposal
See
docs/proposals/modular-refactoring.mdfor complete details including subtask definitions, dependency graph, and exit criteria.Test Plan
cabal build+cabal testbefore next batch