Naming and renaming things...

Naming things is easily one of the most frustrating parts of development. I’m convinced that half of "clarity" in a project is just giving parts the right labels.

However, as codebases grow—especially now that we can generate blocks of code so quickly—things get messy fast. A standard "Search and Replace All" is too much of a sledgehammer. I wanted something more like a scalpel. Asking an LLM to rename a whole project is hit-or-miss and usually misses the architectural nuances you actually care about. I built this tool to handle the heavy lifting while keeping the codebase intact.

View on GitHub: 311ecode/deepShift

DeepShift: Precise project refactoring

DeepShift is a collection of utilities for project-wide renaming. It treats a "name" as an identity that exists across your folders, filenames, and the code itself.

Context-Aware Changes

This tool is for those moments when a name is baked into everything. If you have a directory called iDoNotKnow, a file inside it called iDoNotKnow.ts, and a variable inside that called iDoNotKnow, DeepShift handles it all at once:

  • Structural moves: It can shift paths deeply (like moving old/ into very/deep/new/).
  • Atomic updates: It renames the directory, then the files, then every variable and import reference in one go.
  • Syncing: It keeps the folder structure and internal logic aligned, even if you flatten or extend paths.

The Tools

deepShift The core engine. It handles global string replacements, path moves, and renames files or directories if you target them specifically. Use this for variable renames, fixing typos, or moving specific paths.

codeShift This looks for filenames that match a pattern, renames them, and then fixes every import and reference across the project. Good for renaming components (e.g., changing User.ts to Account.ts).

dirShift Specifically for directories. It renames folder structures and then runs a cleanup to fix any broken relative imports caused by the move. Useful for restructuring architectural layers, like moving utils/ to helpers/.

Comparison

Goal Tool Logic
Rename userId to accId deepShift Content only
Rename src/auth/ to src/identity/ dirShift Directory move + ref fix
Swap utils/ for helpers/ dirShift Recursive folder patterns
Rename User.ts to Account.ts codeShift File match + ref fix

Evolution and Performance

The first version of DeepShift was written in Bash. It was simple and had zero dependencies, but it eventually hit a wall. On projects larger than 50KB, global replacements started taking upwards of ten seconds.

I decided to rewrite it in Node.js. Since I already had a solid Bash-level test suite, porting the logic was straightforward. I kept the integration tests but gained a significant speed boost. Now, even heavy refactors happen almost instantly.

Engineering Standards

I focused on three things: Precision, Automation, and Safety.

  1. Git Integration: It checks .gitignore and runs safety checks before touching your files.
  2. Loop Prevention: It won't get stuck in an infinite loop trying to rename a to ab.
  3. Cross-Platform: The logic works across both GNU sed (Linux) and BSD sed (macOS).