GO TO DEFINITION REBUILD REQUIRED

Comprehensive guidelines for AI-assisted development within the Editor platform

⚠️ Go to Definition Fix Requires Rebuild

Date: October 20, 2025
Issue: After enabling declaration maps, "Go to Definition" still opens dist files
Root Cause: Libraries were not rebuilt after config changes

🔍 The Problem

What Happened:

✅ We enabled declarationMap: true in all tsconfig.lib.json files
✅ Committed the changes
✅ Reloaded Cursor with "Developer: Reload Window"
❌ "Go to Definition" still opened dist/ files!

Why It Didn't Work:

# Check for mapping files:
$ find dist/libs/core-models -name "*.d.ts.map"
(no results)

# The .d.ts.map files don't exist yet!

Declaration maps are generated during the build process.
Changing the config doesn't retroactively add maps to already-built libraries!

✅ The Solution

Step 1: Rebuild Libraries ⚠️ CRITICAL

# Option A: Rebuild a specific library
yarn nx run core-models:build

# Option B: Rebuild all libraries (recommended)
yarn build:libs

# Option C: Clean build (if you have issues)
yarn nx reset
yarn build:libs

Step 2: Verify Declaration Maps Were Generated

# Check for .d.ts.map files
find dist/libs/core-models -name "*.d.ts.map" | head -5

# Should see files like:
# dist/libs/core-models/src/lib/types/space-map/space-map.types.d.ts.map

Step 3: Reload TypeScript Server

# In Cursor/VSCode:
Cmd+Shift+P → "TypeScript: Restart TS Server"

# Or reload the entire window:
Cmd+Shift+P → "Developer: Reload Window"

Step 4: Test It!

Open any component (e.g., create-galaxy-dialog.component.ts)
Option+Click on a type (e.g., GalaxyGroupingStrategy)
✅ Should now open: libs/core-models/src/lib/types/space-map/space-map.types.ts (source!)
❌ Should NOT open: dist/libs/core-models/... (dist!)

🎓 Why This Happens

The Build Process:

1. Developer changes tsconfig.lib.json
   ├─ Adds: "declarationMap": true
   └─ Commits the change

2. Existing dist/ files are untouched
   ├─ They were built BEFORE the config change
   └─ They don't have .d.ts.map files

3. Developer runs "Developer: Reload Window"
   ├─ Cursor/VSCode reloads
   └─ TypeScript server looks for .d.ts.map files
   └─ Files don't exist yet!
   └─ "Go to Definition" still opens dist/ files

4. Developer rebuilds libraries
   ├─ TypeScript compiler sees "declarationMap": true
   ├─ Generates .d.ts.map files alongside .d.ts files
   └─ Maps point to source files

5. TypeScript server picks up new maps
   └─ "Go to Definition" now opens source files! ✅

Key Insight:

Declaration maps are build artifacts, not config artifacts.
Changing the config doesn't magically add maps to existing builds!

🚨 Common Mistakes

❌ Mistake 1: Forgetting to Rebuild

# Changed tsconfig ✅
git commit -m "Enable declaration maps"

# Reloaded Cursor ✅
# "Developer: Reload Window"

# Forgot to rebuild ❌
# Still opens dist/ files!

Fix: Always rebuild after changing build configs!

❌ Mistake 2: Rebuilding Only One Library

# Rebuilt one library
yarn nx run core-models:build ✅

# But you import from multiple libraries
# Other libraries still missing maps ❌

Fix: Rebuild all libraries: yarn build:libs

❌ Mistake 3: Not Restarting TypeScript Server

# Rebuilt libraries ✅
yarn build:libs

# Didn't restart TS server ❌
# TypeScript still using old cache!

Fix: Always restart TS server after rebuilding!

📋 Complete Checklist

Use this checklist when enabling declaration maps:

1. Enable declarationMap: true in tsconfig.lib.json files
2. Enable sourceMap: true in tsconfig.lib.json files
3. Update .vscode/settings.json with TypeScript preferences
4. Update .cursor/settings.json with TypeScript preferences
5. Commit the config changes
6. ⚠️ REBUILD ALL LIBRARIES: yarn build:libs
7. Verify maps exist: find dist -name "*.d.ts.map" | wc -l
8. Restart TS server: Cmd+Shift+P → "TypeScript: Restart TS Server"
9. Test: Option+Click on types → Should open source files!

🔧 Troubleshooting

Issue 1: Still opening dist/ files after rebuild

# Check if maps were actually generated
find dist/libs -name "*.d.ts.map" | wc -l

# Should show a number > 0
# If 0, check tsconfig.lib.json:
grep -A2 "declarationMap" libs/core-models/tsconfig.lib.json

# Should show:
# "declarationMap": true,
# "sourceMap": true

Issue 2: Maps exist but TS server not using them

# Restart TS server manually
# Cmd+Shift+P → "TypeScript: Restart TS Server"

# Or reload entire window
# Cmd+Shift+P → "Developer: Reload Window"

# Or kill TS server process
pkill -f "tsserver"

Issue 3: Maps missing for some libraries

# Check which libraries are missing maps
for lib in dist/libs/*; do
  count=$(find "$lib" -name "*.d.ts.map" | wc -l)
  echo "$(basename $lib): $count maps"
done

# Rebuild specific libraries with missing maps
yarn nx run <library-name>:build

🎯 Summary

The Problem:

Config changes don't retroactively affect already-built files
Declaration maps are generated during build, not from config

The Solution:

✅ Change config (declarationMap: true)
✅ Commit changes
⚠️ REBUILD libraries (critical step!)
✅ Restart TypeScript server
✅ Test "Go to Definition"

Remember:

Always rebuild after changing build configurations!

📚 Related Documentation

GO-TO-DEFINITION-FIX.md - Technical explanation of the fix
GO-TO-DEFINITION-FIX-SUMMARY.md - Quick reference guide
DECLARATION-MAPS-NO-REPO-IMPACT.md - Repo size impact analysis
tools/scripts/enable-declaration-maps.js - Script that enabled maps

Last Updated: October 20, 2025
Status: ✅ RESOLVED - Declaration maps enabled and libraries rebuilt
Key Lesson: Build configs require rebuilds to take effect!