In garrytan/gstack, the highest structural risk is concentrated in the browse layer — handleMetaCommand, handleSnapshot, and handleWriteCommand are all high-complexity and actively changing right now. handleMetaCommand leads with a risk score of 19.6, backed by a cyclomatic complexity of 79 and fan-out of 51, making every commit to it a live regression risk rather than a future cleanup concern. Across 450 total functions, 50 are rated critical — an 11% critical rate that signals concentrated structural debt in the most active parts of the codebase.
The table below ranks functions by activity-weighted risk — a score that multiplies structural complexity by recent commit frequency. A function that is both hard to understand (high cyclomatic complexity) and actively changing is a higher priority than one that is complex but untouched. CC = cyclomatic complexity (independent execution paths); ND = max nesting depth; FO = fan-out (distinct callees).
Top 5 Hotspots
| Function | File | Risk | CC | ND | FO |
|---|---|---|---|---|---|
handleMetaCommand | browse/src/meta-commands.ts | 19.6 | 79 | 6 | 51 |
runCodexSkill | test/helpers/codex-session-runner.ts | 19.2 | 38 | 8 | 31 |
handleSnapshot | browse/src/snapshot.ts | 18.8 | 69 | 5 | 57 |
scanCodex | bin/gstack-global-discover.ts | 18.3 | 27 | 7 | 18 |
handleWriteCommand | browse/src/write-commands.ts | 18.2 | 112 | 4 | 84 |
Hotspot Analysis
handleMetaCommand — browse/src/meta-commands.ts
Based on its name and location, handleMetaCommand is almost certainly the central dispatch point for meta-level commands in the browse subsystem — the kind of function that interprets user or system directives and routes them to downstream handlers. Its cyclomatic complexity of 79 means there are at least 79 independent execution paths to reason about and test; its fan-out of 51 means it directly invokes 51 distinct functions, giving it an enormous blast radius. With a max nesting depth of 6 and high recent commit activity, every active commit here is navigating a dense decision tree with wide coupling — a live regression risk on each change.
Recommendation: Add characterization tests to lock down current behavior before touching this function, then begin extracting cohesive command-handling sub-functions to reduce the CC below 20 and cut fan-out to a manageable surface.
runCodexSkill — test/helpers/codex-session-runner.ts
runCodexSkill lives in the test helpers layer and, judging by its path, likely orchestrates end-to-end Codex skill sessions for testing — coordinating setup, execution, and teardown in a single function. Its max nesting depth of 8 is the deepest in the entire top five and a strong refactoring signal on its own; combined with a cyclomatic complexity of 38 and fan-out of 31, it is a test helper that has grown to god-function proportions. Actively evolving, this function’s deep nesting is actively complicating new test authorship and increasing the chance of silent behavioral regressions.
Recommendation: Flatten the nesting structure by extracting the inner control logic into purpose-named helper functions — each level of nesting beyond 4 is a candidate for extraction — and consider whether a builder or runner pattern could replace the monolithic orchestration.
handleWriteCommand — browse/src/write-commands.ts
handleWriteCommand, also in the browse layer, is the single most structurally complex function in the top five: a cyclomatic complexity of 112 puts it in extreme territory, and its fan-out of 84 is the highest of any hotspot in this dataset — meaning changes here can ripple to 84 call sites or dependencies. Its max nesting depth of 4 is the shallowest of the group, suggesting the complexity is driven by breadth of branching rather than deeply nested logic. This is not a dormant risk — it is a function being actively changed despite carrying an extreme structural load.
Recommendation: Prioritize decomposing handleWriteCommand using the extract-method pattern: identify the discrete write operations it dispatches and pull each into a named, independently testable function, targeting a fan-out reduction from 84 toward the 15–20 range.
Patterns Found
Antipatterns detected across the top functions in this snapshot:
| Pattern | Occurrences |
|---|---|
complex_branching | 5 |
exit_heavy | 5 |
god_function | 5 |
long_function | 5 |
deeply_nested | 4 |
These labels belong to two tiers — Tier 1 (structural): complex_branching, deeply_nested, exit_heavy, long_function, god_function. Tier 2 (relational/temporal): hub_function, cyclic_hub, middle_man, neighbor_risk, stale_complex, churn_magnet, shotgun_target, volatile_god.
Key Takeaways
- handleWriteCommand (CC 112, FO 84) is the single highest-complexity function in the repo — its fan-out of 84 means any refactoring must be preceded by a blast-radius audit across all 84 dependencies.
- runCodexSkill in test/helpers has a max nesting depth of 8, the deepest in the top five — deep nesting in test infrastructure makes new test cases harder to write correctly and silently raises the cost of every future feature.
- All five top hotspots share the god_function and exit_heavy patterns, meaning each has multiple return paths and broad coupling; writing targeted characterization tests before any refactoring is the lowest-risk first step across the board.
Reproduce This Analysis
git clone https://github.com/garrytan/gstack
cd gstack
git checkout f4bbfaa5bdfd2d6ce59541c2145432febde57fed
hotspots analyze . --mode snapshot --explain-patterns --forceTo run the same analysis on your own codebase, run hotspots analyze . --mode snapshot in any local git repo — no configuration required.
Hotspots highlights structural and activity risk — not “bad code.” Findings are a prioritization aid, not a bug predictor. Editorial policy →