repair-broken-references

用

項引舊時用此技：

• 文有內鏈斷
• 外 URL 返 404
• 入述引已移或刪模
• 檔間交引失同步
• 檔存而無處引

勿用為重構模依或重設訊構。此技修現引、非重構。

入

Parameter	Type	Required	Description
project_path	string	Yes	Absolute path to project root
check_external	boolean	No	Verify external URLs (default: true, slow)
fix_mode	enum	No	auto (fix obvious), report (document only), interactive (prompt)
orphan_threshold	integer	No	Days since last modified to flag as orphan (default: 180)

行

一：掃斷內鏈

尋諸 markdown 鏈指不存檔。

# Find all markdown files
find . -name "*.md" -type f > markdown_files.txt

# Extract all markdown links: [text](path)
grep -oP '\[.*?\]\(\K[^)]+' *.md | sort | uniq > all_links.txt

# For each link:
while read link; do
  # Skip external URLs (http/https)
  if [[ "$link" =~ ^https?:// ]]; then
    continue
  fi

  # Resolve relative path
  target=$(realpath -m "$link")

  # Check if target exists
  if [ ! -e "$target" ]; then
    echo "BROKEN: $link (referenced in $file)" >> broken_internal.txt
  fi
done < all_links.txt

得：broken_internal.txt 列諸斷內引

敗：realpath 不可用→手察各鏈

二：察外 URL

驗外鏈仍可達（HTTP 200 應）。

# Extract external URLs
grep -ohP 'https?://[^\s\)]+' *.md | sort | uniq > external_urls.txt

# Check each URL (rate-limit to avoid bans)
while read url; do
  status=$(curl -o /dev/null -s -w "%{http_code}" "$url")

  if [ "$status" -ge 400 ]; then
    echo "DEAD ($status): $url" >> dead_urls.txt
  fi

  sleep 0.5  # Rate limit
done < external_urls.txt

得：dead_urls.txt 列返 4xx/5xx 之 URL

敗：curl 不可用或封→用線上鏈察或略

注：某 URL 或返 403 因機檢而瀏覽中行。需手審。

三：尋斷入

察諸 import/require 述引存模。

JavaScript/TypeScript：

# Find all import statements
grep -rh "^import.*from ['\"]" . | sed -E "s/.*from ['\"]([^'\"]+)['\"].*/\1/" > imports.txt

# For each import:
while read import; do
  # Skip node_modules and external packages
  if [[ "$import" =~ ^[./] ]]; then
    # Resolve to file path
    target="${import}.js"  # Try .js, .ts, .jsx, .tsx

    if [ ! -e "$target" ]; then
      echo "BROKEN IMPORT: $import" >> broken_imports.txt
    fi
  fi
done < imports.txt

Python：

# Find all import statements
grep -rh "^from .* import\|^import " . --include="*.py" | \
  sed -E "s/from ([^ ]+) import.*/\1/" | \
  sed -E "s/import ([^ ]+)/\1/" > imports.txt

# For each local import (starts with .)
# Check if module file exists

R：

# Find library() and source() calls
grep -rh "library(\\|source(" . --include="*.R" | \
  sed -E 's/.*library\("([^"]+)"\).*/\1/' > packages.txt

# For source() calls, check if file exists
# For library() calls, check if package installed
Rscript -e "installed.packages()[,'Package']" > installed_packages.txt

得：broken_imports.txt 列諸已刪/移模引

敗：語特具不可用→手審近重構提交

四：尋孤檔

識存而無處引之檔。

# Find all code files
find . -type f \( -name "*.js" -o -name "*.py" -o -name "*.R" \) > all_files.txt

# For each file:
while read file; do
  basename=$(basename "$file")

  # Search for references (import, require, source, href, link)
  refs=$(grep -r "$basename" . --exclude-dir=node_modules --exclude-dir=.git | wc -l)

  # If only 1 reference (itself):
  if [ "$refs" -le 1 ]; then
    # Check last modified date
    last_mod=$(git log -1 --format="%ci" "$file")

    # If modified more than orphan_threshold days ago
    # Flag as potential orphan
    echo "ORPHAN: $file (last modified: $last_mod)" >> orphans.txt
  fi
done < all_files.txt

得：orphans.txt 列他處不引之檔

敗：git log 敗→用檔系 mtime 代

注：某檔（如 CLI 入點、頂層本）正當不引而非孤。需手審。

五：修內鏈

以三策修斷內引：

策一：尋移檔

# For each broken link, search for file by name
while read broken_link; do
  filename=$(basename "$broken_link")

  # Search for file in project
  found=$(find . -name "$filename" | head -1)

  if [ -n "$found" ]; then
    # Update link to new path
    old_path="$broken_link"
    new_path="$found"

    # Use Edit tool to replace in all markdown files
    echo "FIX: $old_path -> $new_path"
  fi
done < broken_internal.txt

策二：建轉檔

# If file was deleted intentionally, create redirect stub
echo "# Moved" > "$broken_link"
echo "This content moved to [new location](new_path.md)" >> "$broken_link"

策三：除死鏈

# If content no longer exists, remove link (keep text)
# Replace [text](broken_link) with text (plain)

得：諸斷內鏈或修、或轉、或除

敗：自動修破脈→升手審

六：修斷入

更入述指移後正路。

JavaScript 例：

// Before (broken)
import { helper } from './utils/helper';

// After (fixed — file moved to lib/)
import { helper } from './lib/helper';

各斷入：

1. 定移模（似五）
2. 更入路於諸引檔
3. 行 linter/型察驗修

得：諸入正解；無 module-not-found 錯

敗：模真已刪→升、定其功仍需乎

七：書孤檔

孤標檔、定處：

1. 留：正當不引（入點、本、模板）
2. 存：舊碼不需而存史
3. 刪：死碼無值

# Orphaned Files Review

| File | Last Modified | Recommendation | Reason |
|------|---------------|----------------|--------|
| scripts/old_deploy.sh | 2024-01-05 | Archive | Replaced by CI/CD |
| src/legacy_api.js | 2023-06-12 | Delete | API v1 fully deprecated |
| bin/cli.py | 2025-12-01 | Keep | CLI entry point (unreferenced by design) |

得：孤審文已建；自動決標待人准

敗：（無——無顯處亦書）

八：生修報

摘諸斷引與所施修。

# Reference Repair Report

**Date**: YYYY-MM-DD
**Project**: <project_name>
**Fix Mode**: auto | report | interactive

## Broken Internal Links

- Total: X
- Fixed: Y
- Redirected: Z
- Escalated: W

Details:
- [file.md](file.md) line 45: Fixed broken link to moved doc
- [another.md](another.md) line 12: Created redirect stub

## Dead External URLs

- Total: X
- Fixed (wayback machine): Y
- Removed: Z

Details:
- https://example.com/old-page (404) → Removed
- https://api.old.com/docs (gone) → Replaced with new docs

## Broken Imports

- Total: X
- Fixed: Y
- Escalated: Z

Details:
- src/main.js line 3: Updated import path after refactor

## Orphaned Files

- Total: X
- Kept: Y
- Archived: Z
- Escalated for review: W

See ORPHAN_REVIEW.md for full analysis.

## Validation

- [x] All tests pass after fixes
- [x] Linter reports no module-not-found errors
- [x] Dead links documented in report

得：報存於 REFERENCE_REPAIR_REPORT.md

敗：（無——皆生報）

驗

修後：

• 文無斷內鏈
• 死外 URL 已書（非皆可修）
• 諸入正解
• 孤檔已審決
• 入修後試過
• Linter 報無未解引
• Git 史保（移皆用 git mv）

忌

1. 自 URL 修破脈：代死鏈以 web.archive.org URL 或非作者意。某鏈宜除
2. 過刪孤：入點、CLI 本、模板正當不引。勿審而刪
3. 入路設：設諸相對入用同基。異模系（CommonJS、ES6、TypeScript）路異
4. 外 URL 假陽：某站封 curl/機而瀏覽中行。死 URL 常手驗
5. 環引陷：A 入 B、B 入 A。更一破他。需並修
6. 忽段識：修 [link](#section) 需察 #section 錨存、非僅檔存
7. 混系誤 R 二進：WSL 或 Docker、Rscript 或解至跨平台包代原 R。which Rscript && Rscript --version 察。常用原 R 二進（如 Linux/WSL /usr/local/bin/Rscript）為信。見 Setting Up Your Environment 為 R 路設

參

• clean-codebase — 確孤後除死碼
• tidy-project-structure — 重組檔（或致斷引）
• escalate-issues — 引複問導至專
• compliance/documentation-audit — 全文審
• web-dev/link-checker — 進階外 URL 驗