pretext's analysis core carries the highest activity risk — 5 functions to address first

The most urgent risk in chenglou/pretext sits at the intersection of structural complexity and live commit activity: buildMergedSegmentation in src/analysis.ts carries a cyclomatic complexity of 68 and the highest activity-weighted risk in the codebase (18.5), placing it squarely in the “fire” quadrant — meaning it is both hard to reason about and actively being changed, a combination that makes every edit a regression gamble. Pretext is a TypeScript project with 833 total functions, of which 51 have been flagged as critical-band hotspots. All five top-ranked functions are in the fire quadrant, meaning the structural debt is not sitting idle — it is being actively worked on right now.

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
buildMergedSegmentation	src/analysis.ts	18.5	68	8	21
walkPreparedLines	src/line-break.ts	17.1	37	5	13
stepPreparedChunkLineGeometry	src/line-break.ts	17.1	40	5	11
render	pages/demos/editorial-engine.ts	15.9	43	3	20
parseBlockTokens	pages/demos/markdown-chat.model.ts	15.7	33	3	12

Hotspot Analysis

buildMergedSegmentation — src/analysis.ts

Based on its name and location in src/analysis.ts, buildMergedSegmentation likely constructs a unified segmentation structure by merging multiple analysis passes or data sources — the kind of function that sits at the heart of a text-analysis pipeline. Its cyclomatic complexity of 68 means there are 68 independent execution paths to reason about and test; its max nesting depth of 8 puts it well past the point where local reasoning breaks down; and a fan-out of 21 means it calls 21 distinct functions, giving it an exceptionally wide blast radius. In the fire quadrant with the highest risk score in the top five, this is not backlog debt — it is actively changing under high structural load right now, making every commit a live regression risk.

Recommendation: Add characterization tests that capture current output across representative inputs before any further changes, then decompose the function by extracting each merge stage into a named sub-function — the god-function and long-function patterns both signal that meaningful extraction is achievable. Review all 21 fan-out callees to understand which ones would be affected by a signature or behavioral change here.

walkPreparedLines — src/line-break.ts

As a traversal function in src/line-break.ts, walkPreparedLines likely iterates over a prepared sequence of line structures, applying geometry or break logic at each step. A cyclomatic complexity of 37 combined with the exit-heavy pattern means the function has numerous early-return or break paths, each of which is both a required test case and a source of subtle ordering bugs. A nesting depth of 5 and fan-out of 13 compound this: the logic branches deeply and delegates broadly. Its fire-quadrant classification puts it alongside buildMergedSegmentation, meaning both line-break hotspots are being simultaneously modified under high structural pressure.

Recommendation: The exit-heavy pattern specifically calls for mapping out all return paths before refactoring — document each exit condition, then consider consolidating them into a single result-accumulation loop. Extract the per-line processing logic into a dedicated helper to reduce CC toward a manageable single-digit value.

stepPreparedChunkLineGeometry — src/line-break.ts

Sitting in the same file as walkPreparedLines, stepPreparedChunkLineGeometry likely advances the geometric state of a single prepared chunk within a line-breaking pass — probably a core step function called repeatedly during layout. Its cyclomatic complexity of 40 and exit-heavy pattern indicate a dense decision tree with multiple bail-out conditions, while a nesting depth of 5 and fan-out of 11 show that geometry decisions are both deeply conditional and broadly coupled to other layout utilities. Both share a risk score of 17.1 — the two functions in src/line-break.ts are essentially co-evolving under identical fire-quadrant pressure.

Recommendation: Because this function and walkPreparedLines share a file, band, quadrant, and near-identical activity scores, they should be refactored as a coordinated effort rather than independently — changes to chunk geometry logic and line-walking logic are likely tightly coupled, and extract-method work on one will surface opportunities in the other.

render — pages/demos/editorial-engine.ts

In pages/demos/editorial-engine.ts, render is almost certainly the top-level rendering function for a demo page — responsible for taking some document or engine state and producing the final output. A cyclomatic complexity of 43 means 43 independent execution paths, typically the result of accumulated rendering conditions: handling different node types, applying formatting rules, managing state transitions, or guarding against edge cases in document structure. Fan-out of 20 is the second highest in the top five, indicating broad coupling to helpers, formatters, and layout utilities; any refactoring here will require mapping those 20 callees first. With nesting depth of 3 — moderate in isolation — the complexity is horizontal rather than deeply stacked, driven by the complex_branching and god_function patterns. Its fire-quadrant classification means this rendering function is under active development, compounding the structural risk.

Recommendation: Extract each document node type or rendering case into its own named handler — the god_function pattern signals that this function is doing far more than rendering, and each of the 20 fan-out callees is a potential extraction boundary. A dedicated handler per node type will bring CC below 10 per unit while making the rendering pipeline auditable in isolation.

parseBlockTokens — pages/demos/markdown-chat.model.ts

parseBlockTokens in pages/demos/markdown-chat.model.ts is responsible for parsing a stream of block-level markdown tokens — headings, paragraphs, code fences, lists, blockquotes — and converting them into structured model objects. A cyclomatic complexity of 33 reflects the variety of token types and their edge cases: optional attributes, nested structures, malformed input handling, and state transitions between block contexts. Fan-out of 12 and the god_function pattern confirm this parser is doing more than dispatching — it is resolving, transforming, and accumulating, all in one body. As a fire-quadrant function, it is actively changing, meaning new token types or parsing rules are being added under existing structural debt.

Recommendation: Introduce a per-token-type dispatch pattern — a lookup table or a parseXxxToken() helper per block type — so that parseBlockTokens becomes a flat dispatcher rather than a monolithic implementation. Each extracted parser can then be tested independently with targeted token fixtures, and adding a new token type becomes a contained, isolated change rather than a modification to the central function.

Patterns Found

Antipatterns detected across the top functions in this snapshot:

Pattern	Occurrences
god_function	5
long_function	5
exit_heavy	4
complex_branching	3
deeply_nested	3

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

• buildMergedSegmentation in src/analysis.ts has a cyclomatic complexity of 68 and a fan-out of 21 — add characterization tests immediately, before the next commit lands, to catch regressions across its 68 execution paths.
• Both functions in src/line-break.ts — walkPreparedLines (CC 37) and stepPreparedChunkLineGeometry (CC 40) — are fire-quadrant and co-evolving; refactor them as a coordinated pair rather than in isolation to avoid introducing inconsistencies between the walking and geometry-stepping logic.
• All five critical hotspots are flagged as god functions and long functions, meaning extract-method refactoring is the highest-leverage structural intervention across the board — not a rewrite, but disciplined decomposition into named, testable sub-functions.
• render in pages/demos/editorial-engine.ts (CC 43, FO 20) and parseBlockTokens in pages/demos/markdown-chat.model.ts (CC 33, FO 12) are fire-quadrant risks in demo code that may be evolving into production patterns — address the structural debt before that transition hardens it.

Reproduce This Analysis

git clone https://github.com/chenglou/pretext
cd pretext
git checkout a52268864195edc76d5f382d264dafb33f6be462
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 →

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

$ cargo install hotspots-cli

$ hotspots analyze .