🚨 CRITICAL: Build Script Override Issue

Date: October 20, 2025
Severity: ⚠️ BLOCKING
Status: 🔧 FIX REQUIRED

🔍 The Problem

What We Did:

1. ✅ Enabled declarationMap: true in all tsconfig.lib.json files
2. ✅ Enabled sourceMap: true in all tsconfig.lib.json files
3. ✅ Committed the changes
4. ✅ Rebuilt libraries with yarn build:libs

Why "Go to Definition" Still Opens dist/ Files:

The custom build script is OVERRIDING our tsconfig settings!

declarationMap: false,  // ❌ OVERRIDES tsconfig.lib.json!
sourceMap: false,       // ❌ OVERRIDES tsconfig.lib.json!

This means:

• ❌ Even though tsconfig.lib.json has declarationMap: true
• ❌ The build script forces it to false
• ❌ No .d.ts.map files are generated
• ❌ "Go to Definition" still opens dist files

📊 Evidence

Check 1: tsconfig.lib.json Settings ✅

grep -A2 "declarationMap" libs/core-models/tsconfig.lib.json

# Output:
"declarationMap": true,
"sourceMap": true

✅ Config is correct!

Check 2: Build Script Override ❌

grep -A2 "declarationMap" tools/scripts/build-scripts/build-angular-library.js

# Output:
declarationMap: false,  // ❌ HARD-CODED TO FALSE!
sourceMap: false,       // ❌ HARD-CODED TO FALSE!

❌ Build script overrides config!

Check 3: Generated Files ❌

find dist/libs -name "*.d.ts.map" | wc -l

# Output: 0 (or very few)

❌ No declaration maps generated!

🎯 The Solution

Option 1: Fix Build Script to Respect tsconfig (RECOMMENDED)

Change in tools/scripts/build-scripts/build-angular-library.js:

// BEFORE (Lines 122-124):
declaration: true,
declarationMap: false,  // ❌ Hard-coded
sourceMap: false,       // ❌ Hard-coded

// AFTER:
declaration: true,
declarationMap: libTsConfig.compilerOptions?.declarationMap ?? false,  // ✅ Respect tsconfig
sourceMap: libTsConfig.compilerOptions?.sourceMap ?? false,            // ✅ Respect tsconfig

Why this works:

• ✅ Reads settings from each library's tsconfig.lib.json
• ✅ Falls back to false if not set (safe default)
• ✅ Preserves existing behavior for libraries that haven't enabled maps
• ✅ Respects our new settings for libraries that have enabled maps

Option 2: Use NX Native Build (ALTERNATIVE)

Instead of custom builder, use NX's built-in Angular builder:

// project.json
{
  "build": {
    "executor": "@nx/angular:ng-packagr-lite",
    "options": {
      "project": "libs/core-models/ng-package.json"
    }
  }
}

Pros:

• ✅ Respects tsconfig settings natively
• ✅ Standard Angular tooling
• ✅ Better maintained

Cons:

• ❌ Requires changes to 42+ project.json files
• ❌ Need to create ng-package.json for each library
• ❌ More work to implement

🔧 Implementation Plan (Option 1)

Step 1: Update Build Script

// File: tools/scripts/build-scripts/build-angular-library.js
// Lines: 122-124

// Change from:
declarationMap: false,
sourceMap: false,

// Change to:
declarationMap: libTsConfig.compilerOptions?.declarationMap ?? false,
sourceMap: libTsConfig.compilerOptions?.sourceMap ?? false,

Step 2: Verify It Won't Cause Source Pollution

The build script already has source pollution prevention:

// Line 176-178: Cleanup function
console.log('Cleaning up any source directory pollution...');
await cleanupSourcePollution(libPath);

// Line 354-388: Comprehensive cleanup
async function cleanupSourcePollution(libPath) {
  // Removes .js, .d.ts, .js.map from src/
  // But NOT .d.ts.map (declaration maps)
}

⚠️ WARNING: We need to ensure .d.ts.map files in source are also cleaned up!

Updated cleanup function needed:

const generatedFiles = await findFiles(srcPath, '.js');
const declarationFiles = await findFiles(srcPath, '.d.ts');
const mapFiles = await findFiles(srcPath, '.js.map');
const declarationMapFiles = await findFiles(srcPath, '.d.ts.map');  // NEW!

const allFiles = [...generatedFiles, ...declarationFiles, ...mapFiles, ...declarationMapFiles];  // UPDATED!

Step 3: Rebuild All Libraries

# Clean previous builds
yarn nx reset

# Rebuild with updated script
yarn build:libs

# Verify declaration maps exist
find dist/libs -name "*.d.ts.map" | wc -l
# Should show > 0

Step 4: Test "Go to Definition"

1. Cmd+Shift+P → "TypeScript: Restart TS Server"
2. Option+Click on any type
3. ✅ Should open source file!

🚨 Why This Happened

Design Philosophy:

The custom build script was designed to prevent source pollution at all costs.

From the AGENTS.md:

"Disable all source map generation to prevent pollution"

Original Intent:

• Prevent .d.ts, .js, .js.map files in source directories
• Keep source clean for development
• Only output to dist/

Unintended Consequence:

• Also disabled declarationMap which is NEEDED for "Go to Definition"
• No way to navigate from compiled files back to source
• Harder debugging experience

📈 Impact Analysis

Current State (declarationMap: false):

Developer Experience:
  ❌ Option+Click opens dist/ files (read-only)
  ❌ Hard to debug type issues
  ❌ Can't easily modify types
  ❌ Confusion between source and compiled files

Repo Size:
  ✅ No .d.ts.map files committed (good)

Local Disk:
  ✅ Minimal dist/ size

After Fix (declarationMap: true):

Developer Experience:
  ✅ Option+Click opens source files (editable!)
  ✅ Easy to debug type issues
  ✅ Can modify types directly
  ✅ Clear source vs compiled distinction

Repo Size:
  ✅ Still no .d.ts.map files committed (dist/ is gitignored)

Local Disk:
  ⚠️ +0.3 MB in dist/ (negligible)

Verdict: ✅ The fix is worth it!

🎯 Recommendation

ACTION REQUIRED:

1. Fix the build script (Option 1 above)
2. Update cleanup function to handle .d.ts.map files
3. Rebuild all libraries
4. Test "Go to Definition"
5. Document the change

Why This Is Safe:

1. ✅ No repo impact - dist/ is gitignored
2. ✅ Source stays clean - cleanup function removes pollution
3. ✅ Minimal disk impact - ~0.3 MB total
4. ✅ Better DX - developers can navigate to source
5. ✅ Respects config - libraries can opt-in or opt-out

📚 Related Files

• tools/scripts/build-scripts/build-angular-library.js - Custom builder (needs fix)
• tools/scripts/build-scripts/AGENTS.md - Build system documentation
• libs/**/tsconfig.lib.json - Library TypeScript configs (42 files)
• tools/scripts/enable-declaration-maps.js - Script that enabled maps

Last Updated: October 20, 2025
Status: 🔧 FIX REQUIRED BEFORE GO TO DEFINITION WORKS
Priority: ⚠️ HIGH - Blocking developer experience improvement