Cataloguing In-Tree Utilities to Prevent Duplicate Work

A developer needs a retry wrapper with exponential backoff and jitter. They check their current package, search the repository for retry, glance through twenty irrelevant test helpers, and give up. Fifteen minutes later, they commit src/utils/backoff.ts.

It is the fifth backoff implementation in the codebase. Two of the older implementations handle clock skew correctly. The new one does not.

Duplicate work rarely happens because engineers are careless. It happens because searching an unindexed codebase has a higher cognitive cost than rewriting a utility from scratch. Over time, this pattern degrades a repository. Uncoordinated utilities drift apart, subtle bug fixes apply to only one copy, and what should be simple maintenance becomes a persistent layer of technical debt.

The Search-Cost Threshold

When a developer needs a pure utility—a date formatter, a cryptographic hash wrapper, a byte-stream chunker—they evaluate two paths:

1. Search across multiple packages, verify whether an existing implementation handles their edge cases, verify its test coverage, and figure out how to import it without creating an illegal dependency boundary.
2. Write forty lines of TypeScript or Go, add two unit tests, and move on with their feature.

Path 2 takes ten minutes and carries zero immediate friction. The cost is deferred to the team: five distinct implementations of the same primitive, four of which will miss future security or performance patches.

Standard tooling does not help. Text search matches variable names, not capabilities. Static analysis tools flag copy-pasted blocks of code, but they fail to catch semantic duplicates—implementations written independently with different variable names and divergent control flow to achieve the same end state.

A meaningful repository audit must look deeper than token duplication. It needs to index what the code actually does: its inputs, its outputs, and its operational invariants.

Indexing Primitives Instead of Text

Cataloguing in-tree capability requires treating utilities as standalone primitives rather than incidental file contents.

To turn scattered helpers into an organized internal library, you have to extract and classify them by capability:

1. Isolation. Identify pure or near-pure functions buried inside domain directories (billing/helpers.go, auth/time.ts).
2. Contract Extraction. Determine the input space, return types, and invariant guarantees. Does the string trimmer handle zero-width spaces? Does the retry helper swallow context cancellations?
3. Canonical Selection. Select or synthesise the single best implementation that satisfies all known callers.

This process is explored in detail in our guide on extracting pure primitives from tangled monoliths. Once a primitive is isolated and thoroughly exercised, it stops being someone's private helper and becomes a reusable catalog entry.

// Canonical definition: isolated, typed, fully specified
export interface BackoffPolicy {
  initialDelayMs: number;
  maxDelayMs: number;
  factor: number;
  jitter: boolean;
}

export function computeDelay(attempt: number, policy: BackoffPolicy): number {
  const base = Math.min(policy.maxDelayMs, policy.initialDelayMs * Math.pow(policy.factor, attempt));
  return policy.jitter ? Math.floor(Math.random() * base) : base;
}

When this utility lives in a known, searchable path with verified boundaries, the search cost drops below the rewrite cost. Developers harvest the working solution instead of manufacturing a fresh set of edge-case bugs.

Bridging the Audit to the Repair

Running a code reuse audit that produces a list of duplicated utilities solves nothing on its own. A spreadsheet showing twelve different hashing helpers just sits in a ticket backlog while a thirteenth is written.

The audit has value only if it leads directly to consolidation. As we outline in closing the loop from repository audit to merged repair, discovery must terminate in small, verifiable pull requests that replace old call sites with the indexed primitive.

This step is where the hard work lies. You will discover that Call Site A relied on an undocumented quirk of implementation #2 (such as silently returning an empty string on null), while Call Site B expected an error. You cannot blindly replace all callers with a single function without reconciling these behavioral discrepancies.

The correct approach is incremental:

• Place the canonical primitive in your shared core or internal library.
• Add regression test suites covering the invariants of all existing callers.
• Migrate call sites one package at a time. Do not attempt a multi-package global refactor in a single pull request.

If you want an automated baseline of what your current repository holds before you begin, you can run a free repository evaluation to map the existing landscape.

What to Do on Monday

Do not try to catalogue your entire repository at once. Start with one recurring category.

1. Pick one utility family. Common targets include date range manipulation, exponential backoff, URL query parsing, or structured error wrapping.
2. Find all variants. Run a structural search across all service boundaries. Collect every function that attempts to solve that specific problem.
3. Compare their contracts. Write down the edge cases each handles: empty inputs, out-of-bounds numbers, context cancellation.
4. Publish the canonical version. Hoist the most robust implementation to a shared package, ensure its test suite asserts every discovered edge case, and delete the first duplicate via a single pull request.

Once an internal utility is visible, verified, and easy to import, writing an ad-hoc duplicate becomes the path of higher resistance. That is how you keep technical debt from quietly compounding.