purecontext-mcp 1.1.8 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/AGENT_INSTRUCTIONS.md +393 -0
  2. package/AGENT_INSTRUCTIONS_SHORT.md +53 -0
  3. package/AST-SEARCH.md +274 -0
  4. package/CHANGELOG.md +62 -0
  5. package/CODE-INTELLIGENCE.md +369 -0
  6. package/HEALTH-DASHBOARDS.md +241 -0
  7. package/README.md +7 -0
  8. package/REFACTORING-SAFELY.md +279 -0
  9. package/UNDERSTANDING-RELATIONSHIPS.md +240 -0
  10. package/USER-GUIDE.md +14 -0
  11. package/VISUALIZING-CODE.md +199 -0
  12. package/WORKFLOW-TECH-DEBT.md +286 -0
  13. package/dist/core/db/dep-store.d.ts +75 -0
  14. package/dist/core/db/dep-store.d.ts.map +1 -1
  15. package/dist/core/db/dep-store.js +277 -0
  16. package/dist/core/db/dep-store.js.map +1 -1
  17. package/dist/core/db/schema.d.ts.map +1 -1
  18. package/dist/core/db/schema.js +12 -0
  19. package/dist/core/db/schema.js.map +1 -1
  20. package/dist/core/index-manager.js +1 -1
  21. package/dist/core/index-manager.js.map +1 -1
  22. package/dist/core/types.d.ts +5 -0
  23. package/dist/core/types.d.ts.map +1 -1
  24. package/dist/graph/diagram-renderer.d.ts +83 -0
  25. package/dist/graph/diagram-renderer.d.ts.map +1 -0
  26. package/dist/graph/diagram-renderer.js +294 -0
  27. package/dist/graph/diagram-renderer.js.map +1 -0
  28. package/dist/graph/graph-traversal.d.ts +92 -0
  29. package/dist/graph/graph-traversal.d.ts.map +1 -1
  30. package/dist/graph/graph-traversal.js +440 -2
  31. package/dist/graph/graph-traversal.js.map +1 -1
  32. package/dist/server/mcp-server.d.ts.map +1 -1
  33. package/dist/server/mcp-server.js +145 -0
  34. package/dist/server/mcp-server.js.map +1 -1
  35. package/dist/server/tools/check-delete-safe.d.ts +50 -0
  36. package/dist/server/tools/check-delete-safe.d.ts.map +1 -0
  37. package/dist/server/tools/check-delete-safe.js +308 -0
  38. package/dist/server/tools/check-delete-safe.js.map +1 -0
  39. package/dist/server/tools/check-move-safe.d.ts +44 -0
  40. package/dist/server/tools/check-move-safe.d.ts.map +1 -0
  41. package/dist/server/tools/check-move-safe.js +266 -0
  42. package/dist/server/tools/check-move-safe.js.map +1 -0
  43. package/dist/server/tools/check-rename-safe.d.ts +48 -0
  44. package/dist/server/tools/check-rename-safe.d.ts.map +1 -0
  45. package/dist/server/tools/check-rename-safe.js +218 -0
  46. package/dist/server/tools/check-rename-safe.js.map +1 -0
  47. package/dist/server/tools/diff-health-radar.d.ts +44 -0
  48. package/dist/server/tools/diff-health-radar.d.ts.map +1 -0
  49. package/dist/server/tools/diff-health-radar.js +192 -0
  50. package/dist/server/tools/diff-health-radar.js.map +1 -0
  51. package/dist/server/tools/find-cycles.d.ts +31 -0
  52. package/dist/server/tools/find-cycles.d.ts.map +1 -0
  53. package/dist/server/tools/find-cycles.js +85 -0
  54. package/dist/server/tools/find-cycles.js.map +1 -0
  55. package/dist/server/tools/find-implementations.d.ts +47 -0
  56. package/dist/server/tools/find-implementations.d.ts.map +1 -0
  57. package/dist/server/tools/find-implementations.js +167 -0
  58. package/dist/server/tools/find-implementations.js.map +1 -0
  59. package/dist/server/tools/find-untested-symbols.d.ts +52 -0
  60. package/dist/server/tools/find-untested-symbols.d.ts.map +1 -0
  61. package/dist/server/tools/find-untested-symbols.js +308 -0
  62. package/dist/server/tools/find-untested-symbols.js.map +1 -0
  63. package/dist/server/tools/get-architecture-snapshot.d.ts +43 -0
  64. package/dist/server/tools/get-architecture-snapshot.d.ts.map +1 -0
  65. package/dist/server/tools/get-architecture-snapshot.js +292 -0
  66. package/dist/server/tools/get-architecture-snapshot.js.map +1 -0
  67. package/dist/server/tools/get-call-hierarchy.d.ts +43 -0
  68. package/dist/server/tools/get-call-hierarchy.d.ts.map +1 -0
  69. package/dist/server/tools/get-call-hierarchy.js +119 -0
  70. package/dist/server/tools/get-call-hierarchy.js.map +1 -0
  71. package/dist/server/tools/get-class-hierarchy.d.ts +36 -0
  72. package/dist/server/tools/get-class-hierarchy.d.ts.map +1 -0
  73. package/dist/server/tools/get-class-hierarchy.js +125 -0
  74. package/dist/server/tools/get-class-hierarchy.js.map +1 -0
  75. package/dist/server/tools/get-complexity-hotspots.d.ts +50 -0
  76. package/dist/server/tools/get-complexity-hotspots.d.ts.map +1 -0
  77. package/dist/server/tools/get-complexity-hotspots.js +282 -0
  78. package/dist/server/tools/get-complexity-hotspots.js.map +1 -0
  79. package/dist/server/tools/get-coupling-map.d.ts +39 -0
  80. package/dist/server/tools/get-coupling-map.d.ts.map +1 -0
  81. package/dist/server/tools/get-coupling-map.js +107 -0
  82. package/dist/server/tools/get-coupling-map.js.map +1 -0
  83. package/dist/server/tools/get-debt-report.d.ts +44 -0
  84. package/dist/server/tools/get-debt-report.d.ts.map +1 -0
  85. package/dist/server/tools/get-debt-report.js +606 -0
  86. package/dist/server/tools/get-debt-report.js.map +1 -0
  87. package/dist/server/tools/get-entry-points.d.ts +79 -0
  88. package/dist/server/tools/get-entry-points.d.ts.map +1 -0
  89. package/dist/server/tools/get-entry-points.js +362 -0
  90. package/dist/server/tools/get-entry-points.js.map +1 -0
  91. package/dist/server/tools/get-public-api.d.ts +53 -0
  92. package/dist/server/tools/get-public-api.d.ts.map +1 -0
  93. package/dist/server/tools/get-public-api.js +218 -0
  94. package/dist/server/tools/get-public-api.js.map +1 -0
  95. package/dist/server/tools/get-test-coverage-map.d.ts +66 -0
  96. package/dist/server/tools/get-test-coverage-map.d.ts.map +1 -0
  97. package/dist/server/tools/get-test-coverage-map.js +588 -0
  98. package/dist/server/tools/get-test-coverage-map.js.map +1 -0
  99. package/dist/server/tools/get-todos.d.ts +51 -0
  100. package/dist/server/tools/get-todos.d.ts.map +1 -0
  101. package/dist/server/tools/get-todos.js +180 -0
  102. package/dist/server/tools/get-todos.js.map +1 -0
  103. package/dist/server/tools/get-type-graph.d.ts +73 -0
  104. package/dist/server/tools/get-type-graph.d.ts.map +1 -0
  105. package/dist/server/tools/get-type-graph.js +437 -0
  106. package/dist/server/tools/get-type-graph.js.map +1 -0
  107. package/dist/server/tools/health-radar.d.ts +50 -0
  108. package/dist/server/tools/health-radar.d.ts.map +1 -0
  109. package/dist/server/tools/health-radar.js +426 -0
  110. package/dist/server/tools/health-radar.js.map +1 -0
  111. package/dist/server/tools/plan-refactoring.d.ts +74 -0
  112. package/dist/server/tools/plan-refactoring.d.ts.map +1 -0
  113. package/dist/server/tools/plan-refactoring.js +644 -0
  114. package/dist/server/tools/plan-refactoring.js.map +1 -0
  115. package/dist/server/tools/render-call-graph.d.ts +40 -0
  116. package/dist/server/tools/render-call-graph.d.ts.map +1 -0
  117. package/dist/server/tools/render-call-graph.js +215 -0
  118. package/dist/server/tools/render-call-graph.js.map +1 -0
  119. package/dist/server/tools/render-class-hierarchy.d.ts +42 -0
  120. package/dist/server/tools/render-class-hierarchy.d.ts.map +1 -0
  121. package/dist/server/tools/render-class-hierarchy.js +265 -0
  122. package/dist/server/tools/render-class-hierarchy.js.map +1 -0
  123. package/dist/server/tools/render-dep-matrix.d.ts +38 -0
  124. package/dist/server/tools/render-dep-matrix.d.ts.map +1 -0
  125. package/dist/server/tools/render-dep-matrix.js +186 -0
  126. package/dist/server/tools/render-dep-matrix.js.map +1 -0
  127. package/dist/server/tools/render-diagram.d.ts +47 -0
  128. package/dist/server/tools/render-diagram.d.ts.map +1 -0
  129. package/dist/server/tools/render-diagram.js +266 -0
  130. package/dist/server/tools/render-diagram.js.map +1 -0
  131. package/dist/server/tools/render-import-graph.d.ts +41 -0
  132. package/dist/server/tools/render-import-graph.d.ts.map +1 -0
  133. package/dist/server/tools/render-import-graph.js +158 -0
  134. package/dist/server/tools/render-import-graph.js.map +1 -0
  135. package/dist/server/tools/search-ast.d.ts +55 -0
  136. package/dist/server/tools/search-ast.d.ts.map +1 -0
  137. package/dist/server/tools/search-ast.js +279 -0
  138. package/dist/server/tools/search-ast.js.map +1 -0
  139. package/dist/server/tools/search-by-complexity.d.ts +92 -0
  140. package/dist/server/tools/search-by-complexity.d.ts.map +1 -0
  141. package/dist/server/tools/search-by-complexity.js +268 -0
  142. package/dist/server/tools/search-by-complexity.js.map +1 -0
  143. package/dist/server/tools/search-by-decorator.d.ts +48 -0
  144. package/dist/server/tools/search-by-decorator.d.ts.map +1 -0
  145. package/dist/server/tools/search-by-decorator.js +518 -0
  146. package/dist/server/tools/search-by-decorator.js.map +1 -0
  147. package/dist/server/tools/search-by-signature.d.ts +56 -0
  148. package/dist/server/tools/search-by-signature.d.ts.map +1 -0
  149. package/dist/server/tools/search-by-signature.js +200 -0
  150. package/dist/server/tools/search-by-signature.js.map +1 -0
  151. package/dist/ui/assets/BlastRadius-QdgESOL8.js +1 -0
  152. package/dist/ui/assets/{DependencyGraph-B60SMPbX.js → DependencyGraph-BSMhzwWV.js} +1 -1
  153. package/dist/ui/assets/{NotFound-Bsg8Wppk.js → NotFound-CipFP_s1.js} +1 -1
  154. package/dist/ui/assets/{RepoDetail-Cie0D4_s.js → RepoDetail-Dfp5z5Kq.js} +1 -1
  155. package/dist/ui/assets/{RepoList-CldNt89M.js → RepoList-BKtST3hB.js} +1 -1
  156. package/dist/ui/assets/{Search-CgvpHMOi.js → Search-DzhGDViy.js} +1 -1
  157. package/dist/ui/assets/{SymbolView-B9h0LZTz.js → SymbolView-ryVEwAHG.js} +1 -1
  158. package/dist/ui/assets/{index-DADf5y_L.css → index-Ny8gn9F0.css} +1 -1
  159. package/dist/ui/assets/{index-eK0wMkUR.js → index-nX2chMqi.js} +2 -2
  160. package/dist/ui/assets/{useSearch-KAl3Qyi2.js → useSearch-BnBCRKui.js} +1 -1
  161. package/dist/ui/index.html +2 -2
  162. package/dist/version.d.ts +1 -1
  163. package/dist/version.js +1 -1
  164. package/docs/dev/jcodemunch-gap-analysis.md +198 -0
  165. package/package.json +9 -1
  166. package/user-manual.md +2466 -0
  167. package/dist/ui/assets/BlastRadius-RP7vJEyQ.js +0 -1
@@ -0,0 +1,199 @@
1
+ # Visualizing Code Structure
2
+
3
+ Reading code is one way to understand structure. Seeing it is faster.
4
+
5
+ PureContext can generate diagrams of your codebase — import graphs, call graphs, class hierarchies, and dependency matrices — directly from the indexed symbol data. The output is Mermaid or DOT format: Mermaid renders natively in GitHub, VS Code, Claude, and most documentation tools; DOT feeds Graphviz.
6
+
7
+ ---
8
+
9
+ ## Import graphs: understanding module structure at a glance
10
+
11
+ The most common architectural question is also the simplest: *what imports what?*
12
+
13
+ **Scenario:** You're about to refactor the authentication module. Before you touch anything, you want to see how the auth files relate to each other and what the rest of the codebase is connected to.
14
+
15
+ > "Generate a diagram of the import relationships in src/auth/."
16
+
17
+ ```
18
+ render_import_graph(repoId, filePath: "src/auth/", maxNodes: 20) →
19
+
20
+ ```mermaid
21
+ graph TD
22
+ subgraph auth
23
+ A[auth.ts] --> B[validator.ts]
24
+ A --> C[session.ts]
25
+ B --> D[crypto.ts]
26
+ C --> E[db/session-store.ts]
27
+ end
28
+ F[api/routes/login.ts] --> A
29
+ G[api/middleware/auth-guard.ts] --> A
30
+ H[workers/session-cleanup.ts] --> C
31
+ ```
32
+ ```
33
+
34
+ Paste this into any Mermaid renderer and you see the auth module's external surface immediately: two API files import the main `auth.ts`, one worker imports `session.ts` directly. The validator and session modules are internal to auth.
35
+
36
+ **Whole-repo import graph (scoped to top-level directories):**
37
+
38
+ ```
39
+ render_diagram(repoId, type: "module", maxNodes: 15, maxDepth: 2) →
40
+ [diagram showing how src/api, src/core, src/db, src/workers relate]
41
+ ```
42
+
43
+ Use `maxNodes` to keep the diagram readable. A 300-file codebase doesn't need 300 nodes — 15–30 representative files gives you the architectural skeleton.
44
+
45
+ ---
46
+
47
+ ## Call graphs: tracing execution paths visually
48
+
49
+ A call graph shows the actual runtime flow: when function A runs, what does it call, and what do those call?
50
+
51
+ **Scenario:** You're debugging an intermittent timeout. Requests to `/api/orders` are slow. You want to see the full execution path visually.
52
+
53
+ > "Draw the call graph for the processOrder function, 3 levels deep."
54
+
55
+ ```
56
+ render_call_graph(repoId, symbolId: "processOrder-id", direction: "callees", maxDepth: 3) →
57
+
58
+ ```mermaid
59
+ flowchart TD
60
+ ROOT["processOrder()"]:::root
61
+ ROOT --> A["validateCart()"]
62
+ ROOT --> B["calculateTax()"]
63
+ ROOT --> C["chargePayment()"]
64
+ A --> D["checkInventory()"]
65
+ A --> E["applyDiscounts()"]
66
+ B --> F["fetchTaxRates()"]
67
+ C --> G["callPaymentGateway()"]
68
+ C -.->|cyclic| C
69
+ classDef root fill:#f0a500
70
+ ```
71
+ ```
72
+
73
+ The orange root node is `processOrder`. The dashed self-arrow on `chargePayment` — marked `cyclic` — indicates a retry loop. `callPaymentGateway` is the leaf that makes the external call. That's your timeout candidate.
74
+
75
+ **Bidirectional view — callers and callees:**
76
+
77
+ ```
78
+ render_call_graph(repoId, symbolId: "sendEmail-id", direction: "both") →
79
+ [callers above the root, callees below]
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Class hierarchy diagrams: visualizing inheritance
85
+
86
+ For codebases with significant inheritance — frameworks, plugin systems, ORM models — seeing the hierarchy visually is far faster than tracing it through source files.
87
+
88
+ **Scenario:** You're onboarding a new developer to the project. They need to understand the controller hierarchy before they can write a new endpoint.
89
+
90
+ > "Generate a class diagram of the controller hierarchy."
91
+
92
+ ```
93
+ render_class_hierarchy(repoId, symbolId: "BaseController-id", direction: "descendants") →
94
+
95
+ ```mermaid
96
+ classDiagram
97
+ BaseController <|-- AuthenticatedController
98
+ BaseController <|-- PublicController
99
+ AuthenticatedController <|-- UserController
100
+ AuthenticatedController <|-- AdminController
101
+ AuthenticatedController <|-- ApiController
102
+ ApiController <|-- RestApiController
103
+ ApiController <|-- GraphQLController
104
+ PublicController <|-- LandingController
105
+ ```
106
+ ```
107
+
108
+ This goes straight into the architecture documentation. The diagram is generated from the live code — not hand-drawn — so it's always accurate.
109
+
110
+ ---
111
+
112
+ ## Dependency matrices: finding coupling hotspots
113
+
114
+ A dependency matrix shows the same information as an import graph but in table form. It's better for spotting dense coupling between specific files.
115
+
116
+ **Scenario:** You have a suspicion that certain modules in `src/core/` are too tightly coupled to each other. You want to see the exact coupling pattern.
117
+
118
+ > "Show me the dependency matrix for the 8 most coupled files in src/core/."
119
+
120
+ ```
121
+ render_dep_matrix(repoId, filePath: "src/core/", topN: 8) →
122
+
123
+ auth billing events models session utils crypto db
124
+ auth — 1 0 1 1 1 1 1
125
+ billing 0 — 1 1 0 1 0 1
126
+ events 1 1 — 0 1 1 0 0
127
+ models 0 0 0 — 0 0 0 1
128
+ session 1 0 1 1 — 1 0 1
129
+ utils 0 0 0 0 0 — 0 0
130
+ crypto 0 0 0 0 0 1 — 0
131
+ db 0 0 0 0 0 0 0 —
132
+ ```
133
+
134
+ Cell `[row][col] = 1` means the row file imports the column file. You can immediately see that `auth`, `events`, and `session` form a triangle of mutual imports — a strong signal of circular dependency. `utils` imports nothing (it's a pure leaf), confirming it's safe to change. `models` only imports `db` — appropriately isolated.
135
+
136
+ ---
137
+
138
+ ## Architecture snapshots: tracking structural change over time
139
+
140
+ The tools above show you the current state. Architecture snapshots let you compare state across time — before and after a refactoring, between a feature branch and main.
141
+
142
+ **Scenario:** Your team spent three weeks breaking circular dependencies and reducing coupling. You want to prove the improvement with data.
143
+
144
+ > "Create a snapshot of the architecture before we start the refactoring sprint."
145
+
146
+ ```
147
+ get_architecture_snapshot(repoId, action: "create", label: "before-dec-sprint") →
148
+ { snapshotId: "snap_a1b2c3", label: "before-dec-sprint", createdAt: "..." }
149
+ ```
150
+
151
+ [Three weeks and a re-index later]
152
+
153
+ > "Create another snapshot and compare it to the one from before the sprint."
154
+
155
+ ```
156
+ get_architecture_snapshot(repoId, action: "create", label: "after-dec-sprint") →
157
+ { snapshotId: "snap_d4e5f6" }
158
+
159
+ get_architecture_snapshot(repoId, action: "diff",
160
+ snapshotId: "snap_a1b2c3", compareId: "snap_d4e5f6") →
161
+
162
+ Structural change (after vs before):
163
+
164
+ fileCount: +12 (12 new files created during extraction)
165
+ symbolCount: +34 (more focused, smaller functions)
166
+ edgeCount: -41 (fewer total imports — less coupling)
167
+ cycleCount: -7 (7 circular deps eliminated)
168
+ avgCoupling: 3.4 → 2.1 (modules are less interconnected)
169
+ avgComplexity: 4.8 → 3.9 (simpler on average)
170
+ ```
171
+
172
+ Fewer edges, fewer cycles, lower coupling, lower complexity. This is the before-and-after you show in the sprint retrospective.
173
+
174
+ **Use snapshots for PR review too:**
175
+
176
+ ```
177
+ 1. Index main → get_architecture_snapshot(action: "create", label: "main")
178
+ 2. Index feature branch → get_architecture_snapshot(action: "create", label: "pr-42")
179
+ 3. diff the two snapshots to see the structural impact of the PR
180
+ ```
181
+
182
+ ---
183
+
184
+ ## Choosing the right diagram
185
+
186
+ | Question | Tool |
187
+ |----------|------|
188
+ | How are the files in this directory connected? | `render_import_graph` |
189
+ | What does this function call at runtime? | `render_call_graph` |
190
+ | What extends/implements this class? | `render_class_hierarchy` |
191
+ | Which files are most tightly coupled? | `render_dep_matrix` |
192
+ | I want a single diagram — call, class, or module | `render_diagram` (general-purpose) |
193
+ | Did this PR improve or worsen the architecture? | `get_architecture_snapshot` + diff |
194
+
195
+ All tools support `format: "dot"` if you prefer Graphviz output for more powerful layout options.
196
+
197
+ ---
198
+
199
+ → Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `render_diagram`, `render_call_graph`, `render_import_graph`, `render_class_hierarchy`, `render_dep_matrix`, `get_architecture_snapshot`
@@ -0,0 +1,286 @@
1
+ # Workflow: Running a Tech Debt Review Sprint
2
+
3
+ **Scenario:** It's the start of a new quarter. Your team has been shipping features for six months and the codebase has drifted. You have two weeks set aside for a technical debt sprint. You need to figure out what to work on, prioritize it, execute it safely, and prove the improvement.
4
+
5
+ This workflow shows how PureContext turns a vague "debt sprint" into a structured, measurable campaign.
6
+
7
+ ---
8
+
9
+ ## Phase 1: Assess — what are we dealing with?
10
+
11
+ Before writing any code, get a complete picture of the codebase's health.
12
+
13
+ **You:** "Before we start the sprint, give me a full health assessment of the codebase."
14
+
15
+ **Claude** runs `health_radar`:
16
+
17
+ ```
18
+ Health Radar — before Q2 sprint
19
+
20
+ complexity 58 ██████████░░░░░░░░░░ Warning
21
+ coupling 44 ████████░░░░░░░░░░░░ Poor
22
+ maintainability 71 ██████████████░░░░░░ Fair
23
+ documentation 31 ██████░░░░░░░░░░░░░░ Poor
24
+ stability 62 ████████████░░░░░░░░ Fair
25
+
26
+ Overall Health: 53 Grade: D
27
+ ```
28
+
29
+ Not good. Coupling and documentation are the weakest axes. Complexity is borderline. Now get the details.
30
+
31
+ **You:** "Generate a full debt report. I want to know which files to focus on."
32
+
33
+ **Claude** runs `get_debt_report(topN: 10)`:
34
+
35
+ ```
36
+ Technical Debt Report
37
+
38
+ Overall Debt Score: 49/100 Grade: C-
39
+
40
+ Structural Debt: 68 ← worst category
41
+ 3 circular dependencies
42
+ 14 files with fan-out > 10
43
+ 2 god classes (UserManager.ts, helpers.ts)
44
+
45
+ Complexity Debt: 55
46
+ 18 functions with cyclomatic > 8
47
+ 4 functions > 20 complexity
48
+
49
+ Maintainability: 41
50
+ 2 god classes
51
+ 29 dead exports
52
+ 81 undocumented exported symbols
53
+
54
+ Volatility: 44
55
+ 6 high-churn files with complexity > 8 (highest risk)
56
+
57
+ Top Debt Files:
58
+
59
+ 1. src/legacy/UserManager.ts score: 91
60
+ 2. src/utils/helpers.ts score: 79
61
+ 3. src/core/auth.ts score: 68 ← highest churn + cycles
62
+ 4. src/api/routes/legacy.ts score: 61
63
+ 5. src/billing/processor.ts score: 58
64
+ ```
65
+
66
+ **Snapshot the state before you start:**
67
+
68
+ ```
69
+ get_architecture_snapshot(repoId, action: "create", label: "before-Q2-sprint")
70
+ → snapshotId: "snap_before"
71
+ ```
72
+
73
+ You'll diff against this at the end to prove the improvement.
74
+
75
+ ---
76
+
77
+ ## Phase 2: Understand — cycles, coupling, relationships
78
+
79
+ Before breaking cycles and reducing coupling, understand the exact structure.
80
+
81
+ **You:** "Find all circular dependencies. Show me the cycles involving our core modules."
82
+
83
+ ```
84
+ find_cycles(repoId, filePath: "src/core/") →
85
+
86
+ Cycle 1 (ERROR — tight 2-node):
87
+ src/core/auth.ts ↔ src/core/session.ts
88
+
89
+ Cycle 2 (ERROR — tight 3-node):
90
+ src/core/billing.ts → src/utils/currency.ts → src/core/billing.ts
91
+
92
+ Cycle 3 (WARNING):
93
+ src/core/events.ts → src/handlers/payment.ts → src/core/billing.ts
94
+ → src/core/events.ts
95
+ ```
96
+
97
+ Three cycles. Two errors — these are the structural problems that make the core modules hard to test independently.
98
+
99
+ **You:** "Show me the coupling map for the most coupled files."
100
+
101
+ ```
102
+ get_coupling_map(repoId, topN: 8) →
103
+
104
+ src/utils/helpers.ts instability: 0.06 (42 files depend on it)
105
+ src/core/auth.ts instability: 0.24 (28 files depend on it)
106
+ src/models/user.ts instability: 0.19 (31 files depend on it)
107
+ ...
108
+ ```
109
+
110
+ `helpers.ts` is the most dangerous file to change — 42 files depend on it. It's also identified as a god class in the debt report. It's the highest-priority structural target.
111
+
112
+ **You:** "Before I split helpers.ts, show me its class hierarchy and who implements its exported interfaces."
113
+
114
+ ```
115
+ get_class_hierarchy(symbolId: "BaseHelper-id", direction: "descendants") →
116
+ [hierarchy showing no subclasses — it's not a class hierarchy issue, it's a module cohesion issue]
117
+
118
+ get_coupling_map(repoId, filePath: "src/utils/helpers.ts", direction: "efferent") →
119
+ [shows helpers.ts imports from: lodash, moment, crypto, db/queries ← 4 completely unrelated domains]
120
+ ```
121
+
122
+ The helper file mixes formatting, crypto, date handling, and database utilities in one place. The plan: split it into `src/format/`, `src/crypto/`, `src/date/`, `src/db/utils/`.
123
+
124
+ ---
125
+
126
+ ## Phase 3: Plan — sequence the work safely
127
+
128
+ Before executing, get a sequenced plan for each major change.
129
+
130
+ **You:** "Give me a refactoring plan for splitting helpers.ts into focused modules."
131
+
132
+ ```
133
+ plan_refactoring(repoId, goal: "extract-module", filePath: "src/utils/helpers.ts") →
134
+
135
+ Goal: extract-module
136
+ Estimated files affected: 42
137
+ Risk: HIGH (42 files import this — proceed carefully)
138
+
139
+ Recommended steps:
140
+
141
+ 1. [LOW RISK] Create new module files
142
+ src/format/currency.ts — move formatCurrency, formatPrice, formatPercent
143
+ src/date/utils.ts — move formatDate, parseDate, addDays
144
+ src/crypto/utils.ts — move hashToken, compareHash, generateSecret
145
+ src/db/helpers.ts — move buildQuery, sanitizeSql
146
+
147
+ 2. [MEDIUM RISK] Update leaf importers (files with few other importers)
148
+ 12 test files — update imports one by one, run tests after each
149
+ 8 utility consumers — update in batches of 2-3
150
+
151
+ 3. [HIGH RISK] Update hub importers (files imported by many others)
152
+ src/core/auth.ts (imported by 28 files) — update last
153
+ src/api/middleware/auth.ts (imported by 14 files) — update last
154
+
155
+ 4. [FINAL] Deprecate src/utils/helpers.ts
156
+ Add re-exports for backward compatibility
157
+ Schedule removal in next major release
158
+
159
+ Warnings:
160
+ - Do not remove helpers.ts immediately — it takes 42 files off the air simultaneously
161
+ - Use re-exports during a transition period to avoid breaking the team's in-progress work
162
+ ```
163
+
164
+ ---
165
+
166
+ ## Phase 4: Execute — safely, one step at a time
167
+
168
+ For each specific change, check safety before you start.
169
+
170
+ **Breaking the billing ↔ currency cycle:**
171
+
172
+ **You:** "Before I break the circular dependency between billing.ts and currency.ts, show me the exact imports causing the cycle."
173
+
174
+ ```
175
+ find_cycles(repoId, filePath: "src/core/billing.ts") →
176
+
177
+ Cycle:
178
+ src/core/billing.ts:3 import { formatCurrency } from '../utils/currency'
179
+ src/utils/currency.ts:7 import { DEFAULT_CURRENCY } from '../core/billing'
180
+ ```
181
+
182
+ `billing.ts` imports `formatCurrency` from currency. `currency.ts` imports `DEFAULT_CURRENCY` from billing. The fix: move `DEFAULT_CURRENCY` to a `constants.ts` file that both can import without creating a cycle.
183
+
184
+ **Renaming a function as part of the cleanup:**
185
+
186
+ **You:** "I'm renaming formatCurrency to formatMoney as part of the extraction. Is that safe?"
187
+
188
+ ```
189
+ check_rename_safe(repoId, symbolId: "formatCurrency-id", newName: "formatMoney") →
190
+
191
+ safe: true — 23 files affected, all call sites and imports
192
+ No string-literal references. No name conflicts.
193
+ ```
194
+
195
+ Safe. Proceed.
196
+
197
+ **Deleting dead exports found by the debt report:**
198
+
199
+ **You:** "The debt report listed 29 dead exports. Confirm that the top 5 are safe to delete."
200
+
201
+ ```
202
+ check_delete_safe(repoId, symbolId: "LegacyTokenParser-id") → safe: true
203
+ check_delete_safe(repoId, symbolId: "OldSessionFormat-id") → safe: true
204
+ check_delete_safe(repoId, symbolId: "validateBasicAuth-id") → safe: true
205
+ check_delete_safe(repoId, symbolId: "generateJWT-id") →
206
+ safe: false — 1 live reference in src/integrations/legacy-sso.ts:45
207
+ check_delete_safe(repoId, symbolId: "parseQueryString-id") → safe: true
208
+ ```
209
+
210
+ Four of five are clean deletes. `generateJWT` has one live reference in the legacy SSO integration — update that first, then delete.
211
+
212
+ ---
213
+
214
+ ## Phase 5: Verify — did it work?
215
+
216
+ After two weeks of work, measure the improvement.
217
+
218
+ **You:** "Re-index and generate a new health radar. How did we do?"
219
+
220
+ ```
221
+ health_radar(repoId) →
222
+
223
+ Health Radar — after Q2 sprint
224
+
225
+ complexity 65 ████████████░░░░░░░░ Fair (was: 58 ▲ +7)
226
+ coupling 61 ████████████░░░░░░░░ Fair (was: 44 ▲ +17)
227
+ maintainability 79 ███████████████░░░░░ Good (was: 71 ▲ +8)
228
+ documentation 52 ██████████░░░░░░░░░░ Warning (was: 31 ▲ +21)
229
+ stability 67 █████████████░░░░░░░ Fair (was: 62 ▲ +5)
230
+
231
+ Overall Health: 65 Grade: C+ (was: D)
232
+ ```
233
+
234
+ Every axis improved. Documentation saw the biggest gain — from a nearly failing 31 to 52. Coupling improved by 17 points. Overall grade went from D to C+.
235
+
236
+ **Compare the architecture snapshots:**
237
+
238
+ ```
239
+ get_architecture_snapshot(repoId, action: "diff",
240
+ snapshotId: "snap_before", compareId: "snap_after") →
241
+
242
+ fileCount: +8 (helpers.ts split into 4 focused modules + 4 new test files)
243
+ symbolCount: -12 (29 dead exports removed, net negative after new code)
244
+ edgeCount: -34 (fewer total imports — better modularization)
245
+ cycleCount: -3 (3 circular deps eliminated)
246
+ avgCoupling: 4.2 → 2.8 (-1.4 — significantly less coupled)
247
+ avgComplexity: 5.1 → 4.3 (-0.8 — lower average complexity)
248
+ ```
249
+
250
+ Concrete structural improvement. Three cycles eliminated. Coupling down 33%.
251
+
252
+ **Run the debt report to verify the top files improved:**
253
+
254
+ ```
255
+ get_debt_report(repoId, topN: 5) →
256
+
257
+ Overall Debt Score: 31/100 Grade: B- (was: 49/100)
258
+
259
+ src/legacy/UserManager.ts score: 67 (was: 91 ▼ -24)
260
+ src/utils/format/currency.ts score: 12 (was: 79 as helpers.ts ▼ -67 — split completed)
261
+ src/core/auth.ts score: 44 (was: 68 ▼ -24)
262
+ src/api/routes/legacy.ts score: 58 (was: 61 ▼ -3)
263
+ src/billing/processor.ts score: 55 (was: 58 ▼ -3)
264
+ ```
265
+
266
+ The dramatic improvement in `helpers.ts` (79 → 12 average across the split modules) shows the extraction was the right call. `UserManager.ts` dropped 24 points from the class extraction. The sprint achieved its goals.
267
+
268
+ ---
269
+
270
+ ## What made this sprint effective
271
+
272
+ **Measured before and after.** Snapshots gave concrete proof of improvement — not just "we refactored things" but "+17 coupling score, 3 cycles eliminated."
273
+
274
+ **Prioritized by impact, not feeling.** The debt report ranked files objectively. `UserManager.ts` and `helpers.ts` were the right targets because the data said so — not intuition.
275
+
276
+ **Checked safety before every change.** `check_rename_safe`, `check_delete_safe`, and `check_move_safe` prevented breaking changes. The one "not safe" flag on `generateJWT` caught a real dependency that would have caused a production regression.
277
+
278
+ **Understood structure before touching code.** `find_cycles` showed the exact imports causing each cycle. `get_coupling_map` showed why `helpers.ts` was so dangerous to change. The actual edits were straightforward once the structure was understood.
279
+
280
+ ---
281
+
282
+ → See also:
283
+ → [Code Health & Architecture Analysis](CODE-HEALTH.md) — quality metrics and anti-pattern detection
284
+ → [Health Dashboards & Debt Reporting](HEALTH-DASHBOARDS.md) — health_radar, diff_health_radar, get_debt_report
285
+ → [Refactoring Safely](REFACTORING-SAFELY.md) — pre-flight checks before any structural change
286
+ → [Understanding Relationships](UNDERSTANDING-RELATIONSHIPS.md) — cycles, coupling, and call hierarchies
@@ -10,6 +10,81 @@ export declare function getForwardDeps(db: Database.Database, repoId: string, so
10
10
  export declare function getReverseDeps(db: Database.Database, repoId: string, targetFile: string, tenantId?: string): DepEdge[];
11
11
  /** Distinct file paths that import `targetFile`. */
12
12
  export declare function getImportersOf(db: Database.Database, repoId: string, targetFile: string, tenantId?: string): string[];
13
+ export interface CouplingRow {
14
+ filePath: string;
15
+ efferentCoupling: number;
16
+ afferentCoupling: number;
17
+ instability: number;
18
+ efferentDeps: string[];
19
+ afferentDeps: string[];
20
+ }
21
+ /**
22
+ * Build a per-file coupling map from dep_edges.
23
+ *
24
+ * All edges in dep_edges are internal (external npm imports are dropped at
25
+ * graph-build time), so no external-package filtering is needed.
26
+ *
27
+ * When `filePath` is provided only that file's row is returned.
28
+ */
29
+ export declare function getCouplingMap(db: Database.Database, repoId: string, filePath?: string): CouplingRow[];
30
+ /**
31
+ * Find all class/interface symbols whose signature contains `extends TargetName`.
32
+ * Used for building the descendant tree in get_class_hierarchy.
33
+ *
34
+ * The LIKE query is an over-approximation; callers should post-filter with a
35
+ * word-boundary regex when exact matching is needed.
36
+ */
37
+ export declare function findClassesExtending(db: Database.Database, repoId: string, targetName: string): ImplementorRow[];
38
+ /**
39
+ * Find a class or interface symbol by exact name.
40
+ * Returns the first match (expected to be unique per name+kind in a repo).
41
+ */
42
+ export declare function findClassOrInterfaceByName(db: Database.Database, repoId: string, name: string): ImplementorRow | null;
43
+ export interface ImplementorRow {
44
+ id: string;
45
+ name: string;
46
+ kind: string;
47
+ filePath: string;
48
+ startByte: number;
49
+ endByte: number;
50
+ signature: string;
51
+ summary: string;
52
+ }
53
+ /**
54
+ * Find all class / interface symbols in the repo whose signature contains
55
+ * `implements {targetName}` or `extends {targetName}`.
56
+ *
57
+ * Two passes are used:
58
+ * 1. Name-based: LIKE query on signature (fast, covers most cases).
59
+ * 2. Import-based: check files that import the interface's file — any class
60
+ * there that matches is also included (catches cases where the LIKE
61
+ * didn't fire because the signature was truncated).
62
+ *
63
+ * When `includeAbstract` is false, classes with `abstract` in their signature
64
+ * are excluded. The `limit` is applied after both passes are merged.
65
+ */
66
+ export declare function findClassImplementations(db: Database.Database, repoId: string, targetName: string, targetFilePath: string, includeAbstract: boolean, limit: number): ImplementorRow[];
67
+ /**
68
+ * Return the method name stems (the part after the dot) for all method symbols
69
+ * belonging to a given class in the symbol index.
70
+ *
71
+ * e.g. `JwtAuthProvider.authenticate` → `'authenticate'`
72
+ *
73
+ * Note: interface methods are NOT indexed as separate symbols by the TypeScript
74
+ * handler. Use `extractInterfaceMethodNames` for interface method extraction.
75
+ */
76
+ export declare function getMethodNamesForSymbol(db: Database.Database, repoId: string, ownerName: string, filePath: string): string[];
77
+ /**
78
+ * Extract method/property names from an interface or abstract class body by
79
+ * scanning the raw file content between the symbol's byte offsets.
80
+ *
81
+ * Used for `missingMethods` computation when interface methods are not indexed
82
+ * as separate symbol rows.
83
+ *
84
+ * Strategy: scan lines within the byte range for `identifier(` patterns,
85
+ * skipping the declaration line itself and accessor keywords.
86
+ */
87
+ export declare function extractInterfaceMethodNames(fileContent: Buffer, startByte: number, endByte: number): string[];
13
88
  /**
14
89
  * Returns exported symbols whose file is never imported by any other file in
15
90
  * the repo. Phase 1: file-level dead code detection.
@@ -1 +1 @@
1
- {"version":3,"file":"dep-store.d.ts","sourceRoot":"","sources":["../../../src/core/db/dep-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AA4DrE,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,OAAO,EAAE,EAChB,QAAQ,SAAU,GACjB,IAAI,CAkCN;AAED,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,IAAI,CAIN;AAED,uCAAuC;AACvC,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,EAAE,CAaX;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,EAAE,CAeX;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,EAAE,CAeX;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,EAAE,CAeV;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,EAAE,CAmChB"}
1
+ {"version":3,"file":"dep-store.d.ts","sourceRoot":"","sources":["../../../src/core/db/dep-store.ts"],"names":[],"mappings":"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"}