<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/architecture-todo.md - fork/gdu @ master</title>
<meta name="description" content="docs/architecture-todo.md in fork/gdu at master.">
<meta property="og:title" content="docs/architecture-todo.md - fork/gdu @ master">
<meta property="og:description" content="docs/architecture-todo.md in fork/gdu at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="c636c61a7fb7f1f9a9ac9306790b41a011cbabb9">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/gdu</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/gdu</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Daniel Milde</span><span class="commit-message" data-commit="35cba00b300fad74462fafbf66588d986589e1bf">fix: StoreDir fixes (#644)</span><span class="snapshot-sha sha" data-commit="35cba00b300fad74462fafbf66588d986589e1bf">35cba00</span><time datetime="2026-08-27T14:06:29+02:00" title="2026-08-27 14:06:29 +0200">2026-08-27</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a href="/fork/gdu/ref/ignore/">ignore</a><a class="current" href="/fork/gdu/ref/master/">master</a><a href="/fork/gdu/ref/subvolume/">subvolume</a><a class="all" href="/fork/gdu/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/gdu/">gdu</a> / <a href="/fork/gdu/ref/master/tree/docs/">docs</a> / <span class="cur">architecture-todo.md</span></nav>
<span class="view-stats"><span>12.6 KiB</span><span>231 lines</span></span><span class="actions"><a class="raw" href="/fork/gdu/raw/f173b78e504f6037893e9a899a4ed68651c4e24c/docs/architecture-todo.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Architecture TODO — Deepening Opportunities</h1>
<p>Prioritized list of refactors that turn <strong>shallow modules</strong> (interface nearly as
complex as implementation) into <strong>deep</strong> ones — a lot of behaviour behind a small
interface, placed at a clean <strong>seam</strong>, testable through that interface. Ordered by
leverage (payback across call sites and tests) weighted toward recently-changed
hot spots (<code>pkg/analyze</code>, <code>tui</code>, <code>stdout</code>, <code>report</code>).</p>
<p>Vocabulary: <em>module, interface, depth, seam, adapter, leverage, locality</em> (see the
<code>codebase-design</code> skill). The <strong>deletion test</strong>: if deleting a module makes
complexity vanish it was a pass-through; if complexity reappears across N callers
it was earning its keep.</p>
<p>No <code>CONTEXT.md</code> or ADRs exist yet, so the code's own domain terms are used:
<em>analyzer</em>, <em>Item</em>, <em>Dir</em>, <em>storage strategy</em>, <em>hard-link tracker</em>.</p>
<hr />
<h2>P0 — One entry-resolution module behind a storage-strategy seam</h2>
<p><strong>Strength: Strong</strong></p>
<ul>
<li><strong>Files:</strong> <code>pkg/analyze/parallel.go:30</code>, <code>sequential.go:25</code>, <code>parallel_stable.go:25</code>,
<code>stored.go:33</code>, <code>parallel_top_dir.go:40</code>, <code>sqlite.go:896</code> (six <code>AnalyzeDir</code> +
<code>processDir</code> implementations); prototype already in <code>sqlite.go:983</code> (<code>processFile</code>)
and <code>sqlite.go:948</code> (<code>fileStat</code>).</li>
<li><strong>Problem:</strong> Six analyzers each re-implement the same per-entry pipeline
(<code>os.ReadDir</code> → filter → <code>f.Info()</code> → follow symlink → time filter → archive branch
→ build item + flag → platform stat). ~700 duplicated lines. The duplication is
already breeding drift bugs:
<ul>
<li><code>stored.go:152</code> handles <code>.zip</code> archives but <strong>silently drops <code>.tar</code> support</strong> that
<code>parallel.go:161</code> and <code>sequential.go:134</code> have.</li>
<li><code>totalUsage</code> (<code>parallel.go:190</code>) vs <code>totalSize</code> (<code>sequential.go:163</code>) name the same
value inconsistently.</li>
<li>Only <code>parallel.go</code> and <code>sequential.go</code> call <code>setCurrentDir</code>, so scan <strong>preview</strong>
(<code>GetCurrentDir</code>) is silently broken for the other four analyzers.</li>
</ul>
</li>
<li><strong>Solution:</strong> Extract the per-<code>os.DirEntry</code> pipeline into <strong>one deep function</strong>
returning a resolved item + stats (generalize <code>sqlite.go</code>'s <code>processFile</code>/<code>fileStat</code>).
Each analyzer becomes a thin <strong>storage-strategy adapter</strong> (~30 lines) that only decides
<em>how to store</em> the result: append to <code>Dir.Files</code>, send over a channel, insert into
badger, insert into SQLite, aggregate into <code>TopDir</code>.</li>
<li><strong>Deletion test:</strong> deleting the shared resolver concentrates the traversal complexity
back into six places → it earns its keep. Strong signal.</li>
<li><strong>Benefits:</strong> <em>Locality</em> — symlink/archive/time-filter/hard-link logic fixed once,
fixed everywhere; the tar-in-stored and preview divergences disappear structurally.
<em>Leverage</em> — the resolver is the one place tests exercise the whole pipeline.
<em>Testability</em> — the resolver is a pure-ish function testable without standing up an
analyzer; storage adapters test in isolation.</li>
</ul>
<hr />
<h2>P1 — Consolidate size/count formatting into one <code>common</code> module</h2>
<p><strong>Strength: Strong</strong></p>
<ul>
<li><strong>Files:</strong> <code>stdout/stdout.go:596</code> &amp; <code>:618</code>; <code>report/export.go:328</code> &amp; <code>:350</code>;
<code>tui/format.go:281</code> &amp; <code>:302</code> (size); <code>stdout/stdout.go:564</code> &amp; <code>tui/format.go:263</code>
(count). Constants already shared in <code>internal/common/ui.go</code>.</li>
<li><strong>Problem:</strong> The binary-prefix and decimal-prefix formatting cascades are copied
<strong>byte-for-byte three times</strong>; <code>formatSize</code>/<code>formatCount</code> wrappers likewise. The only
difference is how color is applied (color object vs inline markup). ~180 duplicated
lines. <code>report/export.go</code>'s copies have <strong>no direct format test</strong> — only golden files.</li>
<li><strong>Solution:</strong> One deep <code>common.FormatSize(size, opts)</code> / <code>common.FormatCount(count)</code>
returning a plain string; callers apply color. This is the target state the codebase
already reached for top-N (<code>analyze.CollectTopFiles</code> is shared by stdout/export).</li>
<li><strong>Deletion test:</strong> deleting the shared formatter reappears as three cascades → keeps.</li>
<li><strong>Benefits:</strong> <em>Locality</em> — a unit change (new prefix, rounding fix) lands once.
<em>Testability</em> — one formatter with one table-driven test replaces three partial ones
and closes the untested <code>report</code> path.</li>
</ul>
<hr />
<h2>P2 — Collapse the empty-directory size to a single constant — <strong>mostly done</strong></h2>
<p><strong>Strength: Strong</strong> (cheap, high-correctness)</p>
<ul>
<li><strong>Files:</strong> <code>pkg/analyze/file.go</code> — <code>EmptyDirSize</code>, <code>dirTotals</code>, <code>resolveDirStats</code> and
<code>aggregateDirEntries</code> are now the single definition of directory accounting.
<code>Dir.updateStats</code>, <code>StoredDir.updateStats</code> and <code>SqliteAnalyzer.processDir</code> all route
through it; <code>parallel_top_dir.go</code> and <code>top_dir.go</code> already used the constant.</li>
<li><strong>Was:</strong> raw <code>4096</code> hardcoded as the directory's own size <em>and usage</em> in
<code>stored.go</code> and <code>sqlite.go</code>, so <code>--db</code> scans charged every directory 4096 bytes of disk
usage that the in-memory analyzer did not. An empty directory reported 4096/4096 instead
of 512/0, and the error compounded up the tree. Fixed, with
<code>TestEmptyDirStatsAcrossAnalyzers</code> locking parity across all five analyzers.</li>
<li><strong>Remaining:</strong> <code>zipdir.go:164-165</code> and <code>tardir.go:241-242</code> still seed synthetic archive
directories with <code>Size: 4096, Usage: 4096</code>. These are dead values — <code>Dir.updateStats</code>
overwrites them — but they are misleading and should be dropped or set from
<code>EmptyDirSize</code>.</li>
<li><strong>Benefits:</strong> <em>Locality</em> — one number, one place; removes silent per-analyzer divergence.</li>
</ul>
<hr />
<h2>P3 — Split the 24-method <code>fs.Item</code> interface</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> <code>pkg/fs/file.go:31-54</code> (24 methods). Implementations that panic on most of it:
<code>analyze/top_dir.go:76-86,122,157-162</code> (<code>SimpleDir</code>), <code>analyze/stored.go:444</code>
(<code>ParentDir</code>), <code>analyze/file.go:157-174</code> (<code>File</code> mutation methods),
<code>analyze/sqlite.go</code> (<code>SqliteItem</code>).</li>
<li><strong>Problem:</strong> A <strong>fat interface</strong> forces shallow types to satisfy it by
<code>panic("not implemented")</code>. The interface (the full test surface) is far wider than any
single consumer needs; export/stdout only read.</li>
<li><strong>Solution:</strong> Segment into a read-only core (<code>GetSize</code>/<code>GetName</code>/<code>GetFiles</code>/…), a
<code>Directory</code> facet (children + mutation: <code>AddFile</code>/<code>RemoveFile</code>/<code>SetParent</code>), <code>Encodable</code>
(<code>EncodeJSON</code>), and <code>Lockable</code> (<code>RLock</code>). Consumers depend on the narrow facet they use.</li>
<li><strong>Deletion test:</strong> partial — the panics are a symptom, not a pass-through; the win is
narrower seams, not deleted code.</li>
<li><strong>Benefits:</strong> <em>Leverage</em> — export/stdout depend on a small read interface. <em>Testability</em>
— the "preview only works on 2 of 6 analyzers" class of gap becomes a compile-time fact;
the panicking stubs disappear. Larger, riskier change — sequence it after P0.</li>
</ul>
<hr />
<h2>P4 — Consolidate hard-link "count once" into one tracker module</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> <code>analyze/file.go:108</code> (<code>alreadyCounted</code>, package-global <code>fileFlagMu</code>),
<code>analyze/parallel_top_dir.go:237</code> (<code>sync.Map</code>), <code>analyze/sqlite.go:1028</code>
(<code>hasInodeLocked</code>), plus the badger path via <code>Dir.updateStats</code>.</li>
<li><strong>Problem:</strong> "Count each inode once" is implemented <strong>four times</strong> with four different
mechanisms; they can (and do) drift on symlink-target recording. <code>fileFlagMu</code>
(<code>file.go:17</code>) is a single process-global <code>RWMutex</code> guarding every <code>File.Flag</code> — a global
serialization point under parallel scans.</li>
<li><strong>Solution:</strong> One <code>HardLinkTracker</code> module (interface: "have I seen this inode?") injected
into the shared resolver from P0. Removes the global mutex coupling.</li>
<li><strong>Benefits:</strong> <em>Locality</em> + <em>Testability</em> — hard-link semantics are one testable module,
not an emergent property spread across four files. Best done together with P0.</li>
</ul>
<hr />
<h2>P5 — Introduce a <code>Walker</code> seam for depth-limit / summarize / top-N</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> depth-limit <code>stdout/stdout.go:410</code> vs <code>report/export.go:174</code>; summarize
<code>stdout/stdout.go:301</code> vs <code>report/export.go:209</code>; top-N already shared via
<code>analyze/top.go:33</code>.</li>
<li><strong>Problem:</strong> Each output backend re-codes tree traversal + depth-limiting + summarize on
top of the raw <code>Item</code> tree. JSON encoding is model-owned (<code>Item.EncodeJSON</code>) while text
formatting is UI-owned — inconsistent placement of "turn an Item into output". SQLite even
duplicates JSON encoding a 4th time (<code>sqlite.go:642</code>).</li>
<li><strong>Solution:</strong> A <code>Walker</code>/<code>Formatter</code> seam — walk once, emit per node via a sink. stdout,
JSON export, TUI, and web differ only in the per-node sink.</li>
<li><strong>Benefits:</strong> <em>Leverage</em> — one traversal reused by four backends. <em>Locality</em> — depth/
summarize semantics fixed once. Depends conceptually on P3 (narrow read interface).</li>
</ul>
<hr />
<h2>P6 — Break <code>report</code>'s concrete <code>analyze</code> coupling</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> <code>report/import.go:15</code> returns <code>*analyze.Dir</code>; <code>report/export.go:162,175,216</code>
type-assert <code>dir.(*analyze.Dir)</code> and <code>f.(*analyze.File)</code>.</li>
<li><strong>Problem:</strong> The <code>report</code> layer reaches through the <code>fs.Item</code> abstraction to concrete
<code>analyze</code> types (layering inversion), so export transforms can only be tested by building
real <code>analyze</code> trees.</li>
<li><strong>Solution:</strong> Have <code>import.ReadAnalysis</code> return <code>fs.Item</code> and drive export transforms
through the interface (enabled by P3's read facet).</li>
<li><strong>Benefits:</strong> <em>Testability</em> — transforms testable with fakes; removes the casts.</li>
</ul>
<hr />
<h2>P7 — Shrink the <code>app.UI</code> interface / give export a sub-interface</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> <code>cmd/gdu/app/app.go:33-52</code> (19-method <code>UI</code>); <code>report/export.go:76-96</code>
(five no-op stub methods only present to satisfy it: <code>StartUILoop</code>, <code>SetCollapsePath</code>,
<code>SetShowSymlinkTarget</code>, <code>ListDevices</code>, <code>ReadAnalysis</code>).</li>
<li><strong>Problem:</strong> A fat <code>app.UI</code> interface forces the export backend to carry stubs it never
uses — pure interface tax.</li>
<li><strong>Solution:</strong> Split <code>app.UI</code> so export depends on the subset it implements.</li>
<li><strong>Benefits:</strong> <em>Locality</em> — no dead stubs; each backend's interface is its real surface.</li>
</ul>
<hr />
<h2>P8 — Remove global mutable state in output modules</h2>
<p><strong>Strength: Worth exploring</strong></p>
<ul>
<li><strong>Files:</strong> <code>color.NoColor</code> set as a package-global side effect in <code>report/export.go:69</code>
and <code>stdout/stdout.go:92</code>; <code>progressRunes</code>/<code>progressRunesCount</code> package vars
<code>stdout/stdout.go:40-44</code> mutated by <code>UseOldProgressRunes()</code>; <code>stdout.AnalyzePath</code> calls
<code>os.Stat</code> directly (<code>stdout/stdout.go:206</code>) with no injected path-checker (contrast the
injectable <code>PathChecker</code> in <code>cmd/gdu/app/app.go:206</code>).</li>
<li><strong>Problem:</strong> Constructing one UI mutates process-wide flags affecting the other and all
tests → order-dependent, non-parallelizable tests.</li>
<li><strong>Solution:</strong> Make color/progress-runes per-UI fields; inject a <code>PathChecker</code> into
<code>stdout.UI</code>.</li>
<li><strong>Benefits:</strong> <em>Testability</em> — no order-sensitive globals; color/path behaviour injectable.</li>
</ul>
<hr />
<h2>P9 — Decompose the TUI <code>UI</code> god object</h2>
<p><strong>Strength: Speculative</strong> (large, invasive; do last)</p>
<ul>
<li><strong>Files:</strong> <code>tui/tui.go:28-113</code> — <code>UI</code> has <strong>84 fields</strong> and <strong>127 methods</strong> (36 exported)
across 15 files; embeds <code>common.UI</code> (13 more fields). Deletion-related logic spans 5 files
with the <code>action → deleteFun</code> switch copied 4× (<code>actions.go:236</code>, <code>background.go:35</code>,
<code>marked.go:58</code>, plus confirm dialogs). <code>formatFileRow</code> ≈ <code>formatCollapsedRow</code>
(<code>tui/format.go:43</code> vs <code>:152</code>, ~80% identical). <code>ui.app.(*tview.Application)</code> force-cast
(<code>keys.go:157</code>) defeats the <code>TermApplication</code> mock, making Ctrl-Z untestable.</li>
<li><strong>Problem:</strong> Widget refs, config, injected deps, live model, concurrency primitives, and
ephemeral view state all sit on one struct. Almost nothing is testable except by driving a
real tview widget tree and manually pumping the mocked draw queue.</li>
<li><strong>Solution (incremental):</strong> Peel cohesive sub-modules off the god object one seam at a
time — a <code>Deletion</code> module (one <code>action → deleteFun</code> mapping used by sync/async/marked),
a shared row-builder for <code>formatFileRow</code>/<code>formatCollapsedRow</code>, a config struct for the
~25 one-line setters (<code>tui.go:251-495</code>). Route Ctrl-Z through the <code>TermApplication</code>
interface.</li>
<li><strong>Benefits:</strong> <em>Locality</em> + <em>Testability</em> — deletion and row-formatting become testable
without a screen. Marked Speculative because the god object is load-bearing and the
payoff is gradual; tackle the small internal seams first, not a big-bang rewrite.</li>
</ul>
<hr />
<h2>Top recommendation</h2>
<p>Start with <strong>P0 (shared entry-resolution + storage-strategy seam)</strong>. It is the highest-
leverage move by a wide margin: it collapses ~700 duplicated lines across six analyzers,
and it structurally eliminates three already-live bugs (missing <code>.tar</code> in stored, the
<code>totalUsage</code>/<code>totalSize</code> drift, and preview being broken for four of six analyzers) rather
than patching them one by one. <code>sqlite.go</code>'s <code>processFile</code>/<code>fileStat</code> already sketches the
deep function, so the design risk is low. P2 (empty-dir constant) and P4 (hard-link tracker)
naturally fold into the same change, and P1 (formatting) is an independent, cheap Strong win
that can proceed in parallel.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Architecture TODO — Deepening Opportunities</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Prioritized list of refactors that turn **shallow modules** (interface nearly as</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">complex as implementation) into **deep** ones — a lot of behaviour behind a small</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">interface, placed at a clean **seam**, testable through that interface. Ordered by</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">leverage (payback across call sites and tests) weighted toward recently-changed</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">hot spots (`pkg/analyze`, `tui`, `stdout`, `report`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">Vocabulary: _module, interface, depth, seam, adapter, leverage, locality_ (see the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">`codebase-design` skill). The **deletion test**: if deleting a module makes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">complexity vanish it was a pass-through; if complexity reappears across N callers</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">it was earning its keep.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">No `CONTEXT.md` or ADRs exist yet, so the code&#39;s own domain terms are used:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">_analyzer_, _Item_, _Dir_, _storage strategy_, _hard-link tracker_.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>##</a-p> <a-tt>P0 — One entry-resolution module behind a storage-strategy seam</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">**Strength: Strong**</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>- </a-p>**Files:** `pkg/analyze/parallel.go:30`, `sequential.go:25`, `parallel_stable.go:25`,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>  </a-p>`stored.go:33`, `parallel_top_dir.go:40`, `sqlite.go:896` (six `AnalyzeDir` +</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>  </a-p>`processDir` implementations); prototype already in `sqlite.go:983` (`processFile`)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>  </a-p>and `sqlite.go:948` (`fileStat`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>- </a-p>**Problem:** Six analyzers each re-implement the same per-entry pipeline</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>  </a-p>(`os.ReadDir` → filter → `f.Info()` → follow symlink → time filter → archive branch</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>  </a-p>→ build item + flag → platform stat). ~700 duplicated lines. The duplication is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>  </a-p>already breeding drift bugs:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>  - </a-p>`stored.go:152` handles `.zip` archives but **silently drops `.tar` support** that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>    </a-p>`parallel.go:161` and `sequential.go:134` have.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>  - </a-p>`totalUsage` (`parallel.go:190`) vs `totalSize` (`sequential.go:163`) name the same</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>    </a-p>value inconsistently.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>  - </a-p>Only `parallel.go` and `sequential.go` call `setCurrentDir`, so scan **preview**</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>    </a-p>(`GetCurrentDir`) is silently broken for the other four analyzers.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>- </a-p>**Solution:** Extract the per-`os.DirEntry` pipeline into **one deep function**</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>  </a-p>returning a resolved item + stats (generalize `sqlite.go`&#39;s `processFile`/`fileStat`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>  </a-p>Each analyzer becomes a thin **storage-strategy adapter** (~30 lines) that only decides</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>  </a-p>_how to store_ the result: append to `Dir.Files`, send over a channel, insert into</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>  </a-p>badger, insert into SQLite, aggregate into `TopDir`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>- </a-p>**Deletion test:** deleting the shared resolver concentrates the traversal complexity</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>  </a-p>back into six places → it earns its keep. Strong signal.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>- </a-p>**Benefits:** _Locality_ — symlink/archive/time-filter/hard-link logic fixed once,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>  </a-p>fixed everywhere; the tar-in-stored and preview divergences disappear structurally.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>  </a-p>_Leverage_ — the resolver is the one place tests exercise the whole pipeline.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>  </a-p>_Testability_ — the resolver is a pure-ish function testable without standing up an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>  </a-p>analyzer; storage adapters test in isolation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>## </a-p><a-tt>P1 — Consolidate size/count formatting into one `common` module</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>**Strength: Strong**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>- **Files:** `stdout/stdout.go:596` &amp; `:618`; `report/export.go:328` &amp; `:350`;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>  `tui/format.go:281` &amp; `:302` (size); `stdout/stdout.go:564` &amp; `tui/format.go:263`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>  (count). Constants already shared in `internal/common/ui.go`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>- **Problem:** The binary-prefix and decimal-prefix formatting cascades are copied</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>  **byte-for-byte three times**; `formatSize`/`formatCount` wrappers likewise. The only</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>  difference is how color is applied (color object vs inline markup). ~180 duplicated</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>  lines. `report/export.go`&#39;s copies have **no direct format test** — only golden files.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>- **Solution:** One deep `common.FormatSize(size, opts)` / `common.FormatCount(count)`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>  returning a plain string; callers apply color. This is the target state the codebase</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>  already reached for top-N (`analyze.CollectTopFiles` is shared by stdout/export).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>- **Deletion test:** deleting the shared formatter reappears as three cascades → keeps.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>- **Benefits:** _Locality_ — a unit change (new prefix, rounding fix) lands once.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>  _Testability_ — one formatter with one table-driven test replaces three partial ones</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>  and closes the untested `report` path.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>## </a-p><a-tt>P2 — Collapse the empty-directory size to a single constant — **mostly done**</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>**Strength: Strong** (cheap, high-correctness)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>- **Files:** `pkg/analyze/file.go` — `EmptyDirSize`, `dirTotals`, `resolveDirStats` and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>  `aggregateDirEntries` are now the single definition of directory accounting.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>  `Dir.updateStats`, `StoredDir.updateStats` and `SqliteAnalyzer.processDir` all route</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>  through it; `parallel_top_dir.go` and `top_dir.go` already used the constant.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>- **Was:** raw `4096` hardcoded as the directory&#39;s own size _and usage_ in</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>  `stored.go` and `sqlite.go`, so `--db` scans charged every directory 4096 bytes of disk</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>  usage that the in-memory analyzer did not. An empty directory reported 4096/4096 instead</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>  of 512/0, and the error compounded up the tree. Fixed, with</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>  `TestEmptyDirStatsAcrossAnalyzers` locking parity across all five analyzers.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>- **Remaining:** `zipdir.go:164-165` and `tardir.go:241-242` still seed synthetic archive</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>  directories with `Size: 4096, Usage: 4096`. These are dead values — `Dir.updateStats`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>  overwrites them — but they are misleading and should be dropped or set from</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>  `EmptyDirSize`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>- **Benefits:** _Locality_ — one number, one place; removes silent per-analyzer divergence.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>## </a-p><a-tt>P3 — Split the 24-method `fs.Item` interface</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>- **Files:** `pkg/fs/file.go:31-54` (24 methods). Implementations that panic on most of it:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>  `analyze/top_dir.go:76-86,122,157-162` (`SimpleDir`), `analyze/stored.go:444`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>  (`ParentDir`), `analyze/file.go:157-174` (`File` mutation methods),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>  `analyze/sqlite.go` (`SqliteItem`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>- **Problem:** A **fat interface** forces shallow types to satisfy it by</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>  `panic(&quot;not implemented&quot;)`. The interface (the full test surface) is far wider than any</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>  single consumer needs; export/stdout only read.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>- **Solution:** Segment into a read-only core (`GetSize`/`GetName`/`GetFiles`/…), a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>  `Directory` facet (children + mutation: `AddFile`/`RemoveFile`/`SetParent`), `Encodable`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>  (`EncodeJSON`), and `Lockable` (`RLock`). Consumers depend on the narrow facet they use.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>- **Deletion test:** partial — the panics are a symptom, not a pass-through; the win is</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>  narrower seams, not deleted code.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"><a-p>- **Benefits:** _Leverage_ — export/stdout depend on a small read interface. _Testability_</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>  — the &quot;preview only works on 2 of 6 analyzers&quot; class of gap becomes a compile-time fact;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>  the panicking stubs disappear. Larger, riskier change — sequence it after P0.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>## </a-p><a-tt>P4 — Consolidate hard-link &quot;count once&quot; into one tracker module</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>- **Files:** `analyze/file.go:108` (`alreadyCounted`, package-global `fileFlagMu`),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>  `analyze/parallel_top_dir.go:237` (`sync.Map`), `analyze/sqlite.go:1028`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>  (`hasInodeLocked`), plus the badger path via `Dir.updateStats`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>- **Problem:** &quot;Count each inode once&quot; is implemented **four times** with four different</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>  mechanisms; they can (and do) drift on symlink-target recording. `fileFlagMu`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>  (`file.go:17`) is a single process-global `RWMutex` guarding every `File.Flag` — a global</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>  serialization point under parallel scans.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>- **Solution:** One `HardLinkTracker` module (interface: &quot;have I seen this inode?&quot;) injected</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>  into the shared resolver from P0. Removes the global mutex coupling.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>- **Benefits:** _Locality_ + _Testability_ — hard-link semantics are one testable module,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>  not an emergent property spread across four files. Best done together with P0.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"><a-p>## </a-p><a-tt>P5 — Introduce a `Walker` seam for depth-limit / summarize / top-N</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>- **Files:** depth-limit `stdout/stdout.go:410` vs `report/export.go:174`; summarize</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>  `stdout/stdout.go:301` vs `report/export.go:209`; top-N already shared via</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"><a-p>  `analyze/top.go:33`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>- **Problem:** Each output backend re-codes tree traversal + depth-limiting + summarize on</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"><a-p>  top of the raw `Item` tree. JSON encoding is model-owned (`Item.EncodeJSON`) while text</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>  formatting is UI-owned — inconsistent placement of &quot;turn an Item into output&quot;. SQLite even</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"><a-p>  duplicates JSON encoding a 4th time (`sqlite.go:642`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>- **Solution:** A `Walker`/`Formatter` seam — walk once, emit per node via a sink. stdout,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"><a-p>  JSON export, TUI, and web differ only in the per-node sink.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>- **Benefits:** _Leverage_ — one traversal reused by four backends. _Locality_ — depth/</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"><a-p>  summarize semantics fixed once. Depends conceptually on P3 (narrow read interface).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"><a-p>## </a-p><a-tt>P6 — Break `report`&#39;s concrete `analyze` coupling</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"><a-p>- **Files:** `report/import.go:15` returns `*analyze.Dir`; `report/export.go:162,175,216`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>  type-assert `dir.(*analyze.Dir)` and `f.(*analyze.File)`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>- **Problem:** The `report` layer reaches through the `fs.Item` abstraction to concrete</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>  `analyze` types (layering inversion), so export transforms can only be tested by building</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>  real `analyze` trees.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>- **Solution:** Have `import.ReadAnalysis` return `fs.Item` and drive export transforms</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>  through the interface (enabled by P3&#39;s read facet).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"><a-p>- **Benefits:** _Testability_ — transforms testable with fakes; removes the casts.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>## </a-p><a-tt>P7 — Shrink the `app.UI` interface / give export a sub-interface</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>- **Files:** `cmd/gdu/app/app.go:33-52` (19-method `UI`); `report/export.go:76-96`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"><a-p>  (five no-op stub methods only present to satisfy it: `StartUILoop`, `SetCollapsePath`,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>  `SetShowSymlinkTarget`, `ListDevices`, `ReadAnalysis`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>- **Problem:** A fat `app.UI` interface forces the export backend to carry stubs it never</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>  uses — pure interface tax.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"><a-p>- **Solution:** Split `app.UI` so export depends on the subset it implements.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>- **Benefits:** _Locality_ — no dead stubs; each backend&#39;s interface is its real surface.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>## </a-p><a-tt>P8 — Remove global mutable state in output modules</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>**Strength: Worth exploring**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>- **Files:** `color.NoColor` set as a package-global side effect in `report/export.go:69`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"><a-p>  and `stdout/stdout.go:92`; `progressRunes`/`progressRunesCount` package vars</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-p>  `stdout/stdout.go:40-44` mutated by `UseOldProgressRunes()`; `stdout.AnalyzePath` calls</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"><a-p>  `os.Stat` directly (`stdout/stdout.go:206`) with no injected path-checker (contrast the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>  injectable `PathChecker` in `cmd/gdu/app/app.go:206`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>- **Problem:** Constructing one UI mutates process-wide flags affecting the other and all</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"><a-p>  tests → order-dependent, non-parallelizable tests.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"><a-p>- **Solution:** Make color/progress-runes per-UI fields; inject a `PathChecker` into</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"><a-p>  `stdout.UI`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"><a-p>- **Benefits:** _Testability_ — no order-sensitive globals; color/path behaviour injectable.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p>## </a-p><a-tt>P9 — Decompose the TUI `UI` god object</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"><a-p>**Strength: Speculative** (large, invasive; do last)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p>- **Files:** `tui/tui.go:28-113` — `UI` has **84 fields** and **127 methods** (36 exported)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"><a-p>  across 15 files; embeds `common.UI` (13 more fields). Deletion-related logic spans 5 files</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"><a-p>  with the `action → deleteFun` switch copied 4× (`actions.go:236`, `background.go:35`,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"><a-p>  `marked.go:58`, plus confirm dialogs). `formatFileRow` ≈ `formatCollapsedRow`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"><a-p>  (`tui/format.go:43` vs `:152`, ~80% identical). `ui.app.(*tview.Application)` force-cast</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"><a-p>  (`keys.go:157`) defeats the `TermApplication` mock, making Ctrl-Z untestable.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"><a-p>- **Problem:** Widget refs, config, injected deps, live model, concurrency primitives, and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"><a-p>  ephemeral view state all sit on one struct. Almost nothing is testable except by driving a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>  real tview widget tree and manually pumping the mocked draw queue.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"><a-p>- **Solution (incremental):** Peel cohesive sub-modules off the god object one seam at a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"><a-p>  time — a `Deletion` module (one `action → deleteFun` mapping used by sync/async/marked),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"><a-p>  a shared row-builder for `formatFileRow`/`formatCollapsedRow`, a config struct for the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"><a-p>  ~25 one-line setters (`tui.go:251-495`). Route Ctrl-Z through the `TermApplication`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"><a-p>  interface.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"><a-p>- **Benefits:** _Locality_ + _Testability_ — deletion and row-formatting become testable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"><a-p>  without a screen. Marked Speculative because the god object is load-bearing and the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"><a-p>  payoff is gradual; tackle the small internal seams first, not a big-bang rewrite.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>## </a-p><a-tt>Top recommendation</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text">Start with **P0 (shared entry-resolution + storage-strategy seam)**. It is the highest-</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text">leverage move by a wide margin: it collapses ~700 duplicated lines across six analyzers,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text">and it structurally eliminates three already-live bugs (missing `.tar` in stored, the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text">`totalUsage`/`totalSize` drift, and preview being broken for four of six analyzers) rather</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text">than patching them one by one. `sqlite.go`&#39;s `processFile`/`fileStat` already sketches the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text">deep function, so the design risk is low. P2 (empty-dir constant) and P4 (hard-link tracker)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text">naturally fold into the same change, and P1 (formatting) is an independent, cheap Strong win</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text">that can proceed in parallel.</span></span></pre></div></div>
</main>
</body>
</html>
