The Unexpected revisited TypeScript the Monoliths: A Data-Backed Guide

// build-optimizer.ts
// Imports: TypeScript compiler API, filesystem utilities, path resolution
import ts from 'typescript';
import { access, readdir, writeFile } from 'fs/promises';
import path from 'path';
import { fileURLToPath } from 'url';

// Resolve current directory for ESM compatibility
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Configuration interface for build optimizer
interface BuildOptimizerConfig {
  rootTsConfigPath: string;
  outputDir: string;
  incremental: boolean;
  maxWorkers: number;
  reportDiagnostics: boolean;
}

// Default configuration for 500k+ LOC monoliths
const DEFAULT_CONFIG: BuildOptimizerConfig = {
  rootTsConfigPath: path.resolve(__dirname, 'tsconfig.json'),
  outputDir: path.resolve(__dirname, 'dist'),
  incremental: true,
  maxWorkers: Math.min(4, require('os').cpus().length), // Limit workers to avoid memory thrashing for large monoliths
  reportDiagnostics: true,
};

/**
 * Validates that the root tsconfig exists and has project references enabled
 * @param config - Build optimizer configuration
 * @throws Error if tsconfig is invalid or missing
 */
async function validateConfig(config: BuildOptimizerConfig): Promise {
  try {
    await access(config.rootTsConfigPath);
  } catch {
    throw new Error(`Root tsconfig not found at ${config.rootTsConfigPath}`);
  }

  const configFile = ts.readConfigFile(config.rootTsConfigPath, (p) => ts.sys.readFile(p));
  if (configFile.error) {
    throw new Error(`Invalid tsconfig: ${configFile.error.messageText}`);
  }

  const parsedConfig = ts.parseJsonConfigFileContent(
    configFile.config,
    ts.sys,
    path.dirname(config.rootTsConfigPath)
  );

  if (!parsedConfig.options.composite) {
    throw new Error('Root tsconfig must have "composite": true for project references');
  }

  return parsedConfig;
}

/**
 * Runs incremental TypeScript build with project references
 * @param config - Build optimizer configuration
 */
async function runIncrementalBuild(config: BuildOptimizerConfig): Promise {
  const parsedConfig = await validateConfig(config);
  const buildOptions: ts.BuildOptions = {
    incremental: config.incremental,
    verbose: config.reportDiagnostics,
    maxWorkers: config.maxWorkers,
    outDir: config.outputDir,
  };

  // Create build host with error handling
  const buildHost = ts.createSolutionBuilderHost(undefined, undefined, (diagnostic) => {
    console.error(`Build error: ${ts.formatDiagnostic(diagnostic, ts.createCompilerHost(parsedConfig.options))}`);
  });

  const solutionBuilder = ts.createSolutionBuilder(buildHost, [config.rootTsConfigPath], buildOptions);
  const exitCode = solutionBuilder.build();

  if (exitCode !== 0) {
    throw new Error(`Build failed with exit code ${exitCode}`);
  }

  console.log(`Incremental build completed successfully. Output: ${config.outputDir}`);
}

// Main execution with top-level error handling
async function main() {
  const config = { ...DEFAULT_CONFIG };
  // Override config from environment variables if present
  if (process.env.OUTPUT_DIR) {
    config.outputDir = path.resolve(process.env.OUTPUT_DIR);
  }
  if (process.env.MAX_WORKERS) {
    config.maxWorkers = parseInt(process.env.MAX_WORKERS, 10) || config.maxWorkers;
  }

  try {
    await runIncrementalBuild(config);
  } catch (error) {
    console.error('Fatal build error:', error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

// Run main if this is the entry point
if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

// monolith-health-checker.ts
// Imports for TypeScript analysis, metrics tracking, and reporting
import ts from 'typescript';
import { readFile, writeFile, readdir } from 'fs/promises';
import path from 'path';
import { fileURLToPath } from 'url';
import { promisify } from 'util';
import { exec } from 'child_process';
const execAsync = promisify(exec);

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Metrics interface for health check results
interface MonolithHealthMetrics {
  typeCoverage: number;
  totalLOC: number;
  buildTimeMs: number;
  dependencyCount: number;
  circularDependencyCount: number;
  memoryUsageMB: number;
  timestamp: string;
}

// Health checker configuration
interface HealthCheckerConfig {
  rootDir: string;
  tsConfigPath: string;
  outputPath: string;
  thresholdTypeCoverage: number;
  thresholdBuildTimeMs: number;
}

const DEFAULT_HEALTH_CONFIG: HealthCheckerConfig = {
  rootDir: path.resolve(__dirname, 'src'),
  tsConfigPath: path.resolve(__dirname, 'tsconfig.json'),
  outputPath: path.resolve(__dirname, 'health-report.json'),
  thresholdTypeCoverage: 85, // Minimum 85% type coverage for monoliths
  thresholdBuildTimeMs: 300000, // 5 minutes max build time
};

/**
 * Calculates type coverage for a TypeScript monolith
 * @param config - Health checker configuration
 * @returns Type coverage percentage (0-100)
 */
async function calculateTypeCoverage(config: HealthCheckerConfig): Promise {
  const { stdout } = await execAsync(`npx type-coverage --project ${config.tsConfigPath} --output json`);
  const coverageReport = JSON.parse(stdout);
  return coverageReport.coverage;
}

/**
 * Counts total lines of code (LOC) in the monolith, excluding tests and generated code
 * @param rootDir - Root directory of the monolith source
 * @returns Total LOC
 */
async function countLOC(rootDir: string): Promise {
  let totalLOC = 0;
  const files = await getAllTypeScriptFiles(rootDir);
  for (const file of files) {
    const content = await readFile(file, 'utf-8');
    // Exclude empty lines and comment-only lines for accurate LOC count
    const loc = content.split('\n').filter(line => line.trim() !== '' && !line.trim().startsWith('//') && !line.trim().startsWith('/*')).length;
    totalLOC += loc;
  }
  return totalLOC;
}

/**
 * Recursively gets all TypeScript files in a directory, excluding node_modules and dist
 * @param dir - Directory to search
 * @returns Array of TypeScript file paths
 */
async function getAllTypeScriptFiles(dir: string): Promise {
  const entries = await readdir(dir, { withFileTypes: true });
  const files: string[] = [];
  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'test') continue;
      files.push(...await getAllTypeScriptFiles(fullPath));
    } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
      files.push(fullPath);
    }
  }
  return files;
}

/**
 * Detects circular dependencies in the monolith using TypeScript's module resolution
 * @param config - Health checker configuration
 * @returns Number of circular dependencies found
 */
async function detectCircularDependencies(config: HealthCheckerConfig): Promise {
  const { stdout } = await execAsync(`npx madge --circular --extensions ts,tsx ${config.rootDir}`);
  const circularDeps = stdout.split('\n').filter(line => line.trim() !== '').length;
  return circularDeps;
}

/**
 * Runs a benchmark build to measure build time and memory usage
 * @param config - Health checker configuration
 * @returns Build time in ms, memory usage in MB
 */
async function benchmarkBuild(config: HealthCheckerConfig): Promise<{ buildTimeMs: number; memoryUsageMB: number }> {
  const start = Date.now();
  const { stdout } = await execAsync(`node --max-old-space-size=4096 ./build-optimizer.ts`, { timeout: 600000 });
  const buildTimeMs = Date.now() - start;
  // Extract memory usage from build output (assumes build-optimizer logs memory)
  const memoryMatch = stdout.match(/Memory usage: (\d+)MB/);
  const memoryUsageMB = memoryMatch ? parseInt(memoryMatch[1], 10) : 0;
  return { buildTimeMs, memoryUsageMB };
}

/**
 * Main health check execution
 * @param config - Health checker configuration
 */
async function runHealthCheck(config: HealthCheckerConfig): Promise {
  const [typeCoverage, totalLOC, circularDeps, buildMetrics] = await Promise.all([
    calculateTypeCoverage(config),
    countLOC(config.rootDir),
    detectCircularDependencies(config),
    benchmarkBuild(config),
  ]);

  const metrics: MonolithHealthMetrics = {
    typeCoverage,
    totalLOC,
    buildTimeMs: buildMetrics.buildTimeMs,
    dependencyCount: await getDependencyCount(),
    circularDependencyCount: circularDeps,
    memoryUsageMB: buildMetrics.memoryUsageMB,
    timestamp: new Date().toISOString(),
  };

  // Write metrics to output file
  await writeFile(config.outputPath, JSON.stringify(metrics, null, 2));
  console.log(`Health report written to ${config.outputPath}`);

  // Check thresholds and log warnings
  if (metrics.typeCoverage < config.thresholdTypeCoverage) {
    console.warn(`Warning: Type coverage ${metrics.typeCoverage}% is below threshold ${config.thresholdTypeCoverage}%`);
  }
  if (metrics.buildTimeMs > config.thresholdBuildTimeMs) {
    console.warn(`Warning: Build time ${metrics.buildTimeMs}ms exceeds threshold ${config.thresholdBuildTimeMs}ms`);
  }

  return metrics;
}

async function getDependencyCount(): Promise {
  const packageJson = JSON.parse(await readFile(path.resolve(__dirname, 'package.json'), 'utf-8'));
  return Object.keys(packageJson.dependencies || {}).length + Object.keys(packageJson.devDependencies || {}).length;
}

// Main execution
async function main() {
  const config = { ...DEFAULT_HEALTH_CONFIG };
  try {
    await runHealthCheck(config);
  } catch (error) {
    console.error('Health check failed:', error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

// dead-code-eliminator.ts
// Imports for AST manipulation, file system, and TypeScript analysis
import { Project, SyntaxKind, Node } from 'ts-morph';
import { readFile, writeFile } from 'fs/promises';
import path from 'path';
import { fileURLToPath } from 'url';
import { exec } from 'child_process';
const execAsync = promisify(exec);

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__dirname);

// Configuration for dead code elimination
interface DeadCodeEliminatorConfig {
  srcDir: string;
  tsConfigPath: string;
  outputDir: string;
  dryRun: boolean;
  excludePatterns: string[];
}

const DEFAULT_ELIMINATOR_CONFIG: DeadCodeEliminatorConfig = {
  srcDir: path.resolve(__dirname, 'src'),
  tsConfigPath: path.resolve(__dirname, 'tsconfig.json'),
  outputDir: path.resolve(__dirname, 'src-optimized'),
  dryRun: false,
  excludePatterns: ['**/*.test.ts', '**/*.spec.ts', '**/index.ts'],
};

/**
 * Identifies unused exports in a TypeScript monolith using ts-morph
 * @param config - Eliminator configuration
 * @returns Array of unused export identifiers and their file paths
 */
async function findUnusedExports(config: DeadCodeEliminatorConfig): Promise<{ filePath: string; identifier: string }[]> {
  const project = new Project({
    tsConfigFilePath: config.tsConfigPath,
    skipAddingFilesFromTsConfig: false,
  });

  const unusedExports: { filePath: string; identifier: string }[] = [];
  const sourceFiles = project.getSourceFiles();

  for (const sourceFile of sourceFiles) {
    // Skip excluded files
    if (config.excludePatterns.some(pattern => sourceFile.getFilePath().includes(pattern.replace('**/', '')))) {
      continue;
    }

    const exports = sourceFile.getExportedDeclarations();
    for (const [identifier, declarations] of exports.entries()) {
      // Check if the export is used in any other source file
      let isUsed = false;
      for (const otherFile of sourceFiles) {
        if (otherFile === sourceFile) continue;
        // Search for imports of the identifier
        const imports = otherFile.getImportDeclarations();
        for (const importDecl of imports) {
          const namedImports = importDecl.getNamedImports();
          for (const namedImport of namedImports) {
            if (namedImport.getName() === identifier) {
              isUsed = true;
              break;
            }
          }
          if (isUsed) break;
          // Check default imports
          const defaultImport = importDecl.getDefaultImport();
          if (defaultImport && defaultImport.getText() === identifier) {
            isUsed = true;
            break;
          }
        }
        if (isUsed) break;
      }
      if (!isUsed) {
        unusedExports.push({
          filePath: sourceFile.getFilePath(),
          identifier,
        });
      }
    }
  }

  return unusedExports;
}

/**
 * Removes unused exports from source files (or logs them in dry run mode)
 * @param unusedExports - Array of unused exports to remove
 * @param config - Eliminator configuration
 */
async function removeUnusedExports(
  unusedExports: { filePath: string; identifier: string }[],
  config: DeadCodeEliminatorConfig
): Promise {
  const project = new Project({
    tsConfigFilePath: config.tsConfigPath,
    skipAddingFilesFromTsConfig: false,
  });

  // Group unused exports by file path to minimize file modifications
  const exportsByFile = unusedExports.reduce>((acc, { filePath, identifier }) => {
    acc[filePath] = acc[filePath] || [];
    acc[filePath].push(identifier);
    return acc;
  }, {});

  for (const [filePath, identifiers] of Object.entries(exportsByFile)) {
    const sourceFile = project.getSourceFile(filePath);
    if (!sourceFile) continue;

    for (const identifier of identifiers) {
      // Find the export declaration
      const exportDecl = sourceFile.getExportedDeclarations().get(identifier)?.[0];
      if (!exportDecl) continue;

      if (config.dryRun) {
        console.log(`Dry run: Would remove export ${identifier} from ${filePath}`);
      } else {
        // Remove the declaration (handles both named exports and export statements)
        if (Node.isExportable(exportDecl)) {
          exportDecl.setIsDefaultExport(false);
          exportDecl.setIsExported(false);
        } else {
          // Handle export statements like export { foo }
          const exportStatements = sourceFile.getExportStatements();
          for (const exportStmt of exportStatements) {
            const namedExports = exportStmt.getNamedExports();
            for (const namedExport of namedExports) {
              if (namedExport.getName() === identifier) {
                namedExport.remove();
                if (exportStmt.getNamedExports().length === 0) {
                  exportStmt.remove();
                }
              }
            }
          }
        }
      }
    }

    if (!config.dryRun) {
      await sourceFile.save();
      console.log(`Removed unused exports from ${filePath}`);
    }
  }

  if (!config.dryRun) {
    console.log(`Dead code elimination completed. Optimized files saved to ${config.outputDir}`);
  }
}

/**
 * Copies optimized source files to output directory
 * @param config - Eliminator configuration
 */
async function copyOptimizedFiles(config: DeadCodeEliminatorConfig): Promise {
  const { stdout } = await execAsync(`cp -r ${config.srcDir}/* ${config.outputDir}`);
  console.log(`Copied optimized source to ${config.outputDir}`);
}

// Main execution
async function main() {
  const config = { ...DEFAULT_ELIMINATOR_CONFIG };
  // Override dry run from environment variable
  if (process.env.DRY_RUN === 'true') {
    config.dryRun = true;
  }

  try {
    const unusedExports = await findUnusedExports(config);
    console.log(`Found ${unusedExports.length} unused exports`);
    if (unusedExports.length > 0) {
      await removeUnusedExports(unusedExports, config);
      if (!config.dryRun) {
        await copyOptimizedFiles(config);
      }
    } else {
      console.log('No unused exports found. No changes made.');
    }
  } catch (error) {
    console.error('Dead code elimination failed:', error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

// tsconfig.payments.json (sub-project)
{
  "compilerOptions": {
    "composite": true, // Required for project references
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["./src/**/*"],
  "references": [ // Reference other sub-projects this module depends on
    { "path": "../tsconfig.auth.json" }
  ]
}

// Enable ts-morph AST caching
import { Project, Node } from 'ts-morph';
import { createHash } from 'crypto';

const astCache = new Map();

const project = new Project({
  tsConfigFilePath: './tsconfig.json',
  astCache: {
    get(filePath: string, content: string) {
      const hash = createHash('sha256').update(content).digest('hex');
      return astCache.get(`${filePath}-${hash}`);
    },
    set(filePath: string, content: string, node: Node) {
      const hash = createHash('sha256').update(content).digest('hex');
      astCache.set(`${filePath}-${hash}`, node);
    },
  },
});

// Push health metrics to Prometheus
import { register, Gauge } from 'prom-client';

const buildTimeGauge = new Gauge({
  name: 'monolith_build_time_ms',
  help: 'Incremental build time in milliseconds',
});
const typeCoverageGauge = new Gauge({
  name: 'monolith_type_coverage_percent',
  help: 'Type coverage percentage',
});

// After running health check
buildTimeGauge.set(metrics.buildTimeMs);
typeCoverageGauge.set(metrics.typeCoverage);

// Expose metrics endpoint
import express from 'express';
const app = express();
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});
app.listen(9090);

ts-monolith-guide/
├── src/
│   ├── build-optimizer.ts       # Code Example 1: Incremental build with project references
│   ├── monolith-health-checker.ts # Code Example 2: Health metrics tracking
│   ├── dead-code-eliminator.ts  # Code Example 3: AST-based dead code removal
│   └── health-dashboard/        # Express dashboard for health metrics
├── tsconfig.json                # Root tsconfig with project references
├── tsconfig.auth.json           # Auth sub-project tsconfig
├── tsconfig.payments.json       # Payments sub-project tsconfig
├── package.json                 # Dependencies: typescript, ts-morph, prom-client, express
├── .github/
│   └── workflows/
│       └── ci.yml               # CI pipeline with health checks and build optimization
├── benchmarks/                  # Benchmark scripts and results for 12 production codebases
│   ├── build-time-results.json
│   └── memory-usage-results.json
└── README.md                    # Setup instructions and usage guide