pi's AI provider and tooling layers carry the highest activity risk — 5 functions to address first

Pi's OpenAI provider and tooling hotspots dominate activity-weighted risk, led by convertMessages at CC 40, nesting depth 8, and fan-out 31.

Stephen Collins · May 8, 2026

oss typescript refactoring code-health

Activity Risk19.87Low

Hottest FunctionconvertMessages

Hottest Filepackages/ai/src/providers/openai-completions.ts

Antipatterns Detected

Key Points

What is a god function and why does it matter in pi?

A god function is one that takes on too many responsibilities at once — it handles so many cases and calls so many other functions that it becomes the gravitational centre of its module. In concrete terms, fan-out measures the count of distinct functions directly called by a single function; a fan-out of 31, as seen in `convertMessages`, means a change to any one of those 31 callees can require revisiting this function too, and vice versa. This makes the function hard to test in isolation (you need to account for all 31 dependencies), hard to reason about (40 cyclomatic complexity paths), and high-risk to modify (any edit can affect behaviour across a wide surface). Pi has 5 functions flagged with the god-function pattern across its top hotspots, and both AI-provider converters exhibit it alongside complex branching and deep nesting simultaneously.

How do I reduce cyclomatic complexity in TypeScript?

The most effective technique is extract-method refactoring: identify clusters of branches that share a coherent purpose — for example, all logic handling a single message role or content type — and move each cluster into its own named function with a clear signature. A cyclomatic complexity above 15 is a signal to consider splitting; above 30 (as with `convertMessages` at CC 40) it warrants immediate decomposition. A practical first step for `convertMessages` is to locate each top-level conditional that discriminates on message type or role, extract its body into a dedicated converter function (e.g. `convertSystemMessage`, `convertToolResultMessage`), and replace the original branch with a single call — each extracted function will typically land below CC 5, and the parent function's complexity drops by the number of paths you removed. Decompose-conditional and replace-conditional-with-polymorphism are secondary techniques useful once the primary branches are separated.

Is pi actively maintained?

Yes, and the table shows where active development risk is concentrated. The top five hotspots include OpenAI provider conversion, model-data generation, autocomplete suggestions, and response-stream processing. Active development and high structural complexity are not mutually exclusive; the risk is that iterating quickly on structurally dense functions increases the probability of regressions.

How do I reproduce this analysis?

The analysis was produced by the Hotspots CLI (available at github.com/hotspots-dev/hotspots) against commit 0bcaab4 of earendil-works/pi. To reproduce it, run `git checkout 0bcaab4` inside a local clone of the repo, then execute `hotspots analyze . --mode snapshot --explain-patterns --force`. The same command works on any local git repository without additional configuration, so you can run it against your own projects immediately.

What does activity-weighted risk mean?

Activity-weighted risk multiplies structural complexity — derived from cyclomatic complexity, nesting depth, and fan-out — by recent commit frequency, so that functions which are both hard to understand and actively changing score the highest. A function with cyclomatic complexity 80 that hasn't been touched in two years scores much lower than one with CC 20 that is touched every week, because the complex-but-dormant function carries lower near-term regression risk. In pi, `convertMessages` illustrates this well: its CC of 40, nesting depth of 8, and fan-out of 31 push its activity risk to 19.87 — the highest in the codebase. This prioritisation helps teams focus refactoring effort where it reduces the probability of bugs being introduced right now, not just where code looks complicated in the abstract.

At commit 0bcaab4, pi’s sharpest risk is concentrated in its OpenAI provider layer: convertMessages in openai-completions.ts carries an activity risk of 19.87 and is structurally extreme, with CC 40, nesting depth 8, and fan-out 31. The same pattern holds for its neighbour convertResponsesMessages, which scores 19.54. Across the codebase, pi spans 3,642 functions, 418 of which are rated critical, and the top five also include model generation, autocomplete, and response-stream processing.

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
`convertMessages`	packages/ai/src/providers/openai-completions.ts	19.9	40	8	31
`convertResponsesMessages`	packages/ai/src/providers/openai-responses-shared.ts	19.5	29	8	27
`loadModelsDevData`	packages/ai/scripts/generate-models.ts	19.5	218	7	15
`getFileSuggestions`	packages/tui/src/autocomplete.ts	18.9	40	7	27
`processResponsesStream`	packages/ai/src/providers/openai-responses-shared.ts	18.8	80	17	16

Hotspot Analysis

`convertMessages` — packages/ai/src/providers/openai-completions.ts

Based on its name and file path, convertMessages almost certainly transforms an internal message representation into the format expected by OpenAI’s completions API — a task that accumulates branches for every role type, content variant, and edge case the API supports. The metrics confirm this: a cyclomatic complexity of 40 means 40 independent execution paths, a max nesting depth of 8 means deeply stacked conditionals that are hard to reason about at a glance, and a fan-out of 31 means it directly calls 31 distinct functions, giving it broad coupling across the codebase.

Recommendation: Before the next modification, add characterization tests that cover each major branch (role types, content variants, error paths); then apply extract-method refactoring to pull each message-type handler into its own named function, targeting a CC below 15 per extracted unit. The 4 exit-heavy paths and god-function pattern mean test coverage gaps are the most likely source of silent regressions.

`convertResponsesMessages` — packages/ai/src/providers/openai-responses-shared.ts

Sitting in a shared provider file, convertResponsesMessages likely handles the parallel conversion task for OpenAI’s Responses API surface — a separate but structurally similar job to convertMessages. Its CC of 29 represents 29 independent paths, its nesting depth of 8 matches its sibling, and a fan-out of 27 signals nearly as wide coupling. The shared-file location also implies that changes here can ripple into multiple consumers without obvious call-site visibility.

Recommendation: Map the 27 callee functions to understand the blast radius before making further changes, then decompose the function along the boundaries of distinct response types — each type becoming its own well-named converter. Prioritise this alongside convertMessages since both share the deeply-nested, exit-heavy god-function profile and were changed in the same recent window.

`loadModelsDevData` — packages/ai/scripts/generate-models.ts

loadModelsDevData sits in the model-generation script, where it likely reads provider model metadata and prepares development data. Its CC of 218 is the largest value in the table by a wide margin, with nesting depth 7 and fan-out 15. Even though the fan-out is lower than the provider converters, the branch count alone makes it difficult to reason about expected behavior from inspection.

Recommendation: Preserve current output with snapshot or fixture tests, then split the script by provider, parsing step, or normalization phase. A function at CC 218 should become a coordinator over smaller, independently tested transformations.

`getFileSuggestions` — packages/tui/src/autocomplete.ts

getFileSuggestions likely powers TUI autocomplete for file paths or project files. Its CC 40, nesting depth 7, and fan-out 27 indicate a dense mix of filtering, ranking, filesystem state, and UI-oriented formatting. Autocomplete code often accumulates edge cases quickly, so these metrics suggest a function that needs clearer phase boundaries.

Recommendation: Extract candidate discovery, filtering, scoring, and rendering preparation into separate helpers. Add fixtures for empty input, partial paths, hidden files, duplicate matches, and nested directories.

`processResponsesStream` — packages/ai/src/providers/openai-responses-shared.ts

processResponsesStream is the fifth-ranked hotspot and likely handles streamed Responses API events. Its CC 80 and nesting depth 17 are both extreme, and fan-out 16 shows it coordinates a meaningful set of downstream operations while inside deeply nested event handling. This is the strongest case in the table for flattening control flow before the next feature lands.

Recommendation: Add stream fixtures for each event type and error path, then replace nested event handling with a dispatch table or per-event handler functions. The goal is to make the parent stream loop read as orchestration rather than deeply nested protocol logic.

Patterns Found

Antipatterns detected across the top functions in this snapshot:

Pattern	Occurrences
`complex_branching`	5
`deeply_nested`	5
`god_function`	5
`long_function`	5
`exit_heavy`	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

Prioritise convertMessages (CC 40, nesting depth 8, fan-out 31) for characterization tests immediately; its 40 execution paths need coverage before the next change lands.
Treat convertMessages and convertResponsesMessages as a paired refactoring workstream: both share the same deeply-nested, exit-heavy, god-function profile, so improvements to one should inform the decomposition strategy for the other.
loadModelsDevData has CC 218, so preserve its generated output with fixtures before trying to split it.
processResponsesStream has nesting depth 17, making stream event handling the clearest candidate for dispatch-table or per-event-handler decomposition.

Reproduce This Analysis

git clone https://github.com/earendil-works/pi
cd pi
git checkout 0bcaab4206a3ddbdba60cef2ce61497797f22a0b
hotspots analyze . --mode snapshot --explain-patterns --force

To 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 →

Run this on your own codebase

Hotspots runs locally in under a minute — no account, no data leaves your machine.

macOS

$ brew install Stephen-Collins-tech/tap/hotspots

Linux / cargo

$ cargo install hotspots-cli

Run in any repo

$ hotspots analyze .

★ Star on GitHub

Related Analyses

FlowiseAI/Flowise FlowiseAI/Flowise's agent execution layer carries the highest activity risk — 5 functions to address first

complex_branchingdeeply_nestedexit_heavy

eslint/eslint eslint's rule engine carries the highest activity risk — 2 functions to address first

exit_heavygod_functionlong_function

TanStack/query TanStack/query's persistence and devtools layers carry the highest activity risk — 3 functions to address first

exit_heavycomplex_branchingdeeply_nested