2026-04-10 | 🧹 Extracting Pure Utilities from the God Module ✨
🎯 The Mission
🏗️ Earlier today we broke RunScheduled.hs from 906 lines down to 722 by extracting TaskRunner, VaultSync, and CliArgs modules.
🔬 But 722 lines still means pure utility functions hiding inside an app-level orchestrator, untested and duplicated.
✨ This session continues the decomposition by extracting five pure functions to their owning domain modules, adding 47 new tests, and eliminating a three-way code duplication.
🗂️ What We Extracted
🔤 generateSlug to Automation.BlogPrompt
🐌 The slug generation function converts a blog title into a URL-safe kebab-case string by stripping emojis, lowercasing, replacing non-alphanumeric characters with spaces, and collapsing those spaces into hyphens.
🏠 It belongs in BlogPrompt because that module already owns the Slug newtype and the mkSlug smart constructor.
🧪 We added 13 tests: 10 unit tests covering emoji stripping, special characters, digit preservation, whitespace handling, and empty input, plus 3 property tests verifying no uppercase letters appear, no leading or trailing hyphens, and the output contains only lowercase letters, digits, and hyphens.
📝 stripCodeFences to Automation.Text
🤖 Large language models often wrap their output in markdown code fences, even when you ask them not to.
✂️ This pure function strips those fences, handling the three common variants: triple-backtick-markdown, triple-backtick-md, and plain triple-backtick.
🧪 Nine tests cover all three fence variants, partial fences with only an opening or closing fence, empty content between fences, internal code fences that should be preserved, and multiline content.
🔗 overrideModelChain to Automation.Gemini
🔁 The most satisfying extraction: this identical pattern appeared three times in RunScheduled.hs.
📋 Each task runner needed to read an optional environment variable, parse it into a model, prepend it to a default chain, and remove duplicates.
🧹 Now it is a single pure function in the Gemini module that takes an optional text value and a default chain, returning the overridden chain.
🧪 Eight tests cover the Nothing case, empty strings, whitespace-only strings, known model overrides with deduplication, custom model overrides, trimming of leading and trailing whitespace, and the special case where the override matches the first element in the chain.
📅 isReflectionFile and extractCreativeTitle to Automation.ReflectionTitle
🗂️ The reflection title generation task needed to find recent reflection files and extract their creative titles for style reference.
🧩 The IO function mixed file listing with pure predicate logic and pure title parsing.
🔬 We separated the two pure functions: isReflectionFile validates the YYYY-MM-DD.md filename pattern, and extractCreativeTitle parses the creative portion of a title from frontmatter content.
🧪 Eight tests cover isReflectionFile with valid files, wrong extensions, wrong lengths, non-numeric characters, and boundary dates.
🧪 Eight tests cover extractCreativeTitle with pipe-separated titles, missing pipes, missing title lines, single-quoted values, double-quoted values, unquoted values, empty content, and titles with multiple pipe separators.
📐 Lessons Learned
🔁 DRY via Pure Extraction
🔍 When you see the same pattern three or more times in an app module, that is a pure function begging to be extracted.
📦 The model chain override logic was the clearest example: three nearly identical blocks of code doing the same thing with different environment variable names and default chains.
🧪 Extracting it to a pure function not only eliminated duplication but made the logic testable for the first time, and we immediately found that one of the three call sites was subtly different in how it handled deduplication.
🏠 Place Functions in Their Owning Domain Module
🧭 The question is not where does this utility live, but what domain concept does it belong to.
🔤 generateSlug belongs with the Slug type in BlogPrompt, not in a generic utilities module.
✂️ stripCodeFences belongs in Text alongside other text transformations like truncation and similarity.
📅 isReflectionFile and extractCreativeTitle belong in ReflectionTitle because they are part of the reflection title generation domain.
📐 This follows the vertical slicing principle: the function lives where its type is defined.
🧩 Separate IO from Pure Logic in IO Functions
🔀 The original extractRecentCreativeTitles function read files from disk, filtered by filename pattern, and parsed titles from content, all in one monolithic IO action.
🧹 After extraction, the IO function is a thin wrapper that reads files and delegates to two pure functions: isReflectionFile for filtering and extractCreativeTitle for parsing.
🧪 The pure functions are now independently testable with deterministic inputs, while the IO wrapper remains a simple orchestrator.
📊 By the Numbers
📉 RunScheduled.hs shrank from 722 to 665 lines, a further 8 percent reduction.
🧪 47 new tests were added, bringing the total from 1153 to 1200.
🔧 Zero hlint hints and zero compiler warnings across all changed files.
🔁 Eliminated a three-way code duplication in model chain override logic.
📦 Five pure functions moved from the app module to three library modules.
🔮 What Remains
📏 At 665 lines, RunScheduled.hs is nearing a reasonable size for an application entry point with orchestration logic.
⚠️ Seven non-startup error calls still exist in the task runner functions, where runtime crashes should be replaced with proper Either returns.
🏗️ The three largest library modules, SocialPosting at 921 lines, BlogImage at 1291 lines, and InternalLinking at 961 lines, are candidates for the same decomposition treatment.
🗺️ The architecture roadmap now includes a prioritized list of these remaining improvements, ready for future sessions to tackle one vertical slice at a time.
📚 Book Recommendations
📖 Similar
- Thinking with Types by Sandy Maguire is relevant because it demonstrates how to use Haskell’s type system to enforce correctness at compile time, which is the philosophy behind extracting pure functions with precise type signatures rather than leaving untyped logic in a monolithic orchestrator.
- 🧑💻📈 The Pragmatic Programmer: Your Journey to Mastery by David Thomas and Andrew Hunt is relevant because its DRY principle and orthogonality guidance are exactly what drove the elimination of three-way code duplication and the placement of functions in their domain-owning modules.
↔️ Contrasting
- 🧱🛠️ Working Effectively with Legacy Code by Michael Feathers is relevant because it focuses on safely modifying code that lacks tests, while our approach takes the opposite direction, extracting code so we can add tests before modifying it, showing two complementary philosophies of managing code evolution.
🔗 Related
- Haskell in Depth by Vitaly Bragilevsky is relevant because it covers advanced module organization, pure function extraction, and property-based testing patterns in Haskell, all of which we exercised in this session.