2026-03-31 | 🔀 The Reversed Path and the Broken Regex 🐛
🔍 The Symptom
🚨 The internal linking pipeline was only finding one file to process. 📊 Out of 947 indexed books, the breadth-first search traversal that starts from the most recent reflection file reported just a single reachable file. 🧊 No links were added, and the system quietly moved on, doing nothing.
🕵️ The Investigation
🧭 Internal linking works by starting at the most recent daily reflection note and following outgoing wikilinks and markdown links to discover connected content. 🌐 Normally, a reflection links to dozens of notes, which in turn link to others, forming a dense reachable graph across the knowledge base. 📉 Getting only one reachable file meant the traversal was finding the starting reflection but discovering zero outgoing links from it.
🔬 The Haskell port of the internal linking module contains its own copies of path-handling utilities, ported from the social posting module. 🔎 Comparing the two implementations side by side revealed two bugs hiding in plain sight.
🐛 Bug One: The Missing Reverse
🔧 The function that normalizes file paths works by splitting a path into segments, folding over them to resolve dot and dot-dot references, and joining them back together. ⚡ The fold operation uses a left fold with cons, which builds the result list in reverse order. 🔀 The social posting module corrects this with a reverse call after the fold. 🚫 The internal linking module was missing that reverse call.
🎭 This meant a path like “reflections/dot-dot/books/foo.md” would normalize to “foo.md/books” instead of “books/foo.md”. 💥 Every resolved path came out backwards, producing nonsense file locations that could never match any real file in the content directory.
🐛 Bug Two: The Broken Bracket Expression
🔧 Wikilink extraction used a POSIX regular expression with a negated character class. 📐 The intent was to match any character that is not a close bracket, pipe, or hash. ⚠️ In POSIX regex, a backslash inside a bracket expression is not an escape character. The close bracket immediately terminates the bracket expression.
🎯 This meant the pattern was really matching just one character that is not a backslash, followed by an alternation. 📏 For a wikilink like double-bracket-some-book-double-bracket, only the first character “s” was captured instead of the full “some-book” target.
🛡️ The social posting module had already solved this by using a manual character-by-character parser instead of regex. 🔄 Porting that parser to the internal linking module fixed the second bug.
🧪 Why the Tests Missed It
🔍 The normalizeFilePath tests existed only in the social posting test module, testing the correct implementation. 📋 The internal linking tests for extractLinkedPaths used wikilinks with explicit paths like “books/a”, which contain a forward slash. 🛣️ When a wikilink target contains a slash, the code takes a direct path that bypasses both normalizeFilePath and the wikilink regex. 🕳️ The bug only manifests for plain wikilinks without slashes, which are the most common kind in real reflection files.
✅ The Fix
🔧 Adding the missing reverse call to normalizeFilePath was a one-word change. 🔄 Replacing the regex-based wikilink parser with the proven manual parser from the social posting module was a clean swap. 🧪 Six new tests were added: direct normalizeFilePath tests mirroring the social posting suite, plus extractLinkedPaths tests for plain wikilinks and relative markdown links that exercise both code paths. 📊 All 708 Haskell tests and 160 TypeScript tests pass.
💡 Lessons Learned
🧬 When porting code between modules, subtle omissions like a single function call can silently break functionality. 📋 Tests that only verify list lengths without checking actual values can mask incorrect behavior. 🎯 Duplicated utility code is a maintenance hazard: the social posting version was correct, but the copied version drifted. 🔬 The red-green testing cycle matters: writing a failing test first would have caught this instantly.
📚 Book Recommendations
📖 Similar
- Release It! by Michael T. Nygard is relevant because it covers patterns for building resilient production systems, including the importance of monitoring subtle failures that silently degrade service quality, much like the linking pipeline quietly doing nothing.
- 🧱🛠️ Working Effectively with Legacy Code by Michael Feathers is relevant because it addresses strategies for safely modifying and testing code that lacks adequate test coverage, exactly the situation that allowed these porting bugs to slip through.
↔️ Contrasting
- 🧑💻📈 The Pragmatic Programmer: Your Journey to Mastery by David Thomas and Andrew Hunt offers a broader view on software craftsmanship that would argue against code duplication in the first place, favoring shared abstractions over copied implementations.
🔗 Related
- 🐣🌱👨🏫💻 Haskell Programming from First Principles by Christopher Allen and Julie Moronuki explores the Haskell type system and functional patterns that could have prevented these bugs through stronger abstractions like shared modules or newtypes for file paths.