codebase-structure-audit

Codebase Structure Audit & Safe Refactoring

Systematic approach to understanding a project's dependency graph and making safe, incremental changes. Designed for the "안전한 것부터 하나씩" workflow.

When to Use

• Before refactoring a codebase you're unfamiliar with
• When asked to "구조 파악" or map file dependencies
• Before deleting files you suspect are dead code
• When consolidating duplicate resources (CSS, data files, templates)
• When planning incremental refactoring with live verification

Do NOT use for: greenfield architecture, performance profiling, or dependency upgrades.

Step 1 — Map the Dependency Graph

File Discovery

find . -type f \( -name '*.ts' -o -name '*.js' -o -name '*.css' -o -name '*.html' \) \
  -not -path './node_modules/*' -not -path './dist/*' -not -path './.wrangler/*' | sort

Import/Reference Tracing

# TypeScript/JS imports
grep -rn "import " --include='*.ts' --include='*.js' \
  --exclude-dir=node_modules --exclude-dir=dist . | sort

# CSS @import chain
grep -rn "@import" --include='*.css' --exclude-dir=node_modules . | sort

# HTML script/style references
grep -rn 'src=\|href=' --include='*.html' --exclude-dir=node_modules . | sort

Component Isolation Check

For each suspected subsystem, verify whether it shares a common CSS/JS entry point or maintains its own:

for html in $(find public -name '*.html' -not -path '*/node_modules/*'); do
  echo "=== $(basename $html) ==="
  grep -o 'href="[^"]*\.css[^"]*"' "$html" | sed 's/href="//;s/"//'
done

Step 2 — Dead Code Detection

File-Level Reference Check

Never delete a file before confirming zero references:

grep -rn "target-filename\|TargetModule" --include='*.{ts,js,html}' \
  --exclude-dir=node_modules . | grep -v "target-file.js"

# For CSS: check HTML href references
grep -rn "target.css" --include='*.html' --exclude-dir=node_modules .

Dead Code Categories

Signal	Likelihood	Confidence
import from broken path (e.g. ../public/js/ doesn't exist)	100% dead	Certain
File exports but zero import from other files across project	>95% dead	High
Config key defined but zero grep hits for the key name	>95% dead	High
CSS file not in any @import chain nor directly linked from HTML	100% dead	Certain