Fast Compilation

/**
 * Fast compilation mode configuration
 */
interface FastCompilationModes {
  /** Never use fast compilation - always compile all files */
  never: "never";
  /** Always use fast compilation when possible */
  always: "always";  
  /** Use fast compilation only in watch mode (default) */
  watch: "watch";
}

// Usage in options
interface FastCompilationConfig {
  fast?: "never" | "always" | "watch";
}

interface FastCompilationBehavior {
  /** Only external modules support fast compilation */
  moduleSupport: "external-modules-only";
  /** File change detection using hash-based caching */
  changeDetection: "hash-based-file-comparison";
  /** Cache stored in .tscache directory */
  cacheLocation: ".tscache/";
  /** Base directory file (.baseDir.ts) ensures correct outDir structure */
  baseDirFile: "automatic-creation";
}

/**
 * Determines if compilation result should refresh fast cache
 */
function compileResultMeansFastCacheShouldBeRefreshed(
  options: IGruntTSOptions, 
  result: ICompileResult
): boolean;

/**
 * Main compilation function with fast compilation support
 */
function compileAllFiles(
  options: IGruntTSOptions, 
  compilationInfo: IGruntTSCompilationInfo
): Promise<ICompileResult>;

/**
 * Cache utility functions for fast compilation
 */
interface CacheUtilities {
  /** Get files that have changed since last compilation */
  getNewFilesForTarget(files: string[], targetName: string): string[];
  /** Mark compilation as successful and update cache */
  compileSuccessfull(files: string[], targetName: string): void;
  /** Clear cache for a specific target */
  clearCache(targetName: string): void;
}

interface CacheStorage {
  /** Cache directory created automatically */
  location: ".tscache/";
  /** Per-target cache files */
  structure: "target-specific-cache-files";
  /** File hashes stored for change detection */
  content: "file-hash-mappings";
}

interface FastCompilationProcess {
  /** 1. Check if fast compilation is enabled for current mode */
  enablementCheck: "based-on-fast-option-and-watch-mode";
  /** 2. Compare file hashes with cached versions */
  changeDetection: "hash-comparison-with-cache";
  /** 3. Compile only changed files plus dependencies */
  selectiveCompilation: "changed-files-only";
  /** 4. Update cache with new file hashes on success */
  cacheUpdate: "on-successful-compilation";
  /** 5. Create .baseDir.ts file to maintain outDir structure */
  baseDirMaintenance: "automatic";
}

// Simplified internal flow
function fastCompileProcess(options: IGruntTSOptions, files: string[]) {
  if (options.fast === 'never') {
    return compileAllFiles(files);
  }
  
  // Get changed files
  const changedFiles = getChangedFiles(files, targetName);
  
  if (changedFiles.length === 0) {
    return { success: true, message: 'No changes detected' };
  }
  
  // Compile only changed files
  const result = compileFiles(changedFiles);
  
  if (result.success) {
    updateCache(files, targetName);
  }
  
  return result;
}

interface BaseDirManagement {
  /** Automatically creates .baseDir.ts file when needed */
  baseDirFile: ".baseDir.ts";
  /** Ensures outDir structure matches source structure */
  structurePreservation: boolean;
  /** Generated in calculated common path or specified baseDir */
  location: "common-path-or-basedir-option";
  /** Compiled to .baseDir.js and .baseDir.js.map in outDir */
  outputs: [".baseDir.js", ".baseDir.js.map"];
}

ts: {
  fastWithOutDir: {
    src: ["src/**/*.ts"],
    outDir: "built/",
    options: {
      fast: "always",
      baseDir: "src/"  // Explicitly set base directory
    }
  }
}

// Creates src/.baseDir.ts and built/.baseDir.js to maintain structure

interface FastCompilationLogging {
  /** Changed files are highlighted with special prefix */
  changedFilePrefix: "### Fast Compile >>";
  /** Shows timing for fast compilation */
  timingInfo: "compilation-duration";
  /** Indicates number of files actually compiled */
  fileCount: "actual-files-compiled";
}

### Fast Compile >> src/app.ts
### Fast Compile >> src/services/api.ts
TypeScript compilation complete: 0.45s for 2 TypeScript files.

interface FastCompilationRequirements {
  /** Only works with external modules (not internal modules) */
  moduleSystem: "external-modules-required";
  /** Cannot be used with files configuration */
  filesConfigCompatibility: false;
  /** Works best with outDir (not out/concatenation) */
  outputPreference: "outDir-preferred";
  /** Requires writable .tscache directory */
  cacheDirectoryAccess: "write-permission-required";
}

interface FastWatchIntegration {
  /** Default fast mode when watch is enabled */
  defaultMode: "watch";
  /** File changes trigger incremental compilation */
  changeTriggering: "automatic";
  /** Cache persists between watch compilations */
  cachePersistence: "maintained-across-watches";
  /** Optimal for development workflows */
  useCase: "development-focused";
}

ts: {
  dev: {
    src: ["src/**/*.ts"],
    outDir: "built/",
    watch: "src/",
    options: {
      fast: "watch", // Default behavior with watch
      target: "es5",
      module: "commonjs"
    }
  }
}

interface CacheInvalidation {
  /** Cache cleared on first run after grunt process restart */
  processRestart: "cache-cleared-once";
  /** Successful compilation updates cache with new hashes */
  successfulCompilation: "cache-updated";
  /** Failed compilation may not update cache */
  failedCompilation: "cache-unchanged";
  /** Manual cache clearing available */
  manualClear: "clearCache-function";
}

// Internal cache management
interface CacheManagement {
  /** Per-target cache clearing flag */
  cacheClearedOnce: "{ [targetName: string]: boolean }";
  /** Cache refresh based on compilation result */
  refreshCondition: "success-or-type-errors-only";
}

interface FastCompilationPerformance {
  /** Typical speedup for incremental changes */
  performanceGain: "5x-to-50x-faster";
  /** Best performance with small change sets */
  optimalScenario: "few-changed-files";
  /** Overhead minimal for small projects */
  overhead: "negligible-for-small-projects";
  /** Scales well with project size */
  scalability: "better-with-larger-codebases";
}

interface FastCompilationTroubleshooting {
  /** Cache corruption - clear .tscache directory */
  cacheCorruption: "delete-tscache-directory";
  /** Permission issues - check .tscache write access */
  permissionIssues: "verify-write-permissions";
  /** Inconsistent results - disable fast for debugging */
  inconsistentResults: "set-fast-never-temporarily";
  /** Module dependency issues - fast may miss indirect dependencies */
  dependencyIssues: "full-compilation-may-be-needed";
}

interface FastCompilationLimitations {
  /** Not compatible with grunt files configuration */
  filesConfig: "not-supported";
  /** May miss complex dependency changes */
  dependencyTracking: "limited-to-direct-changes";
  /** Internal modules not supported */
  moduleSupport: "external-modules-only";
  /** Reference files with out may disable fast compilation */
  referenceWithOut: "disables-fast-compilation";
  /** Concatenation (out) not optimal for fast compilation */
  concatenationLimits: "outDir-preferred";
}

interface DisablingFastCompilation {
  /** Set fast to "never" to always compile all files */
  disableCompletely: 'fast: "never"';
  /** Useful for production builds */
  productionBuilds: "recommended-to-disable";
  /** Debugging compilation issues */
  debugging: "temporarily-disable";
  /** CI/CD environments may prefer full compilation */
  cicdBuilds: "consider-disabling";
}

ts: {
  dev: {
    src: ["src/**/*.ts"],
    outDir: "built/",
    options: {
      fast: "watch" // Fast for development
    }
  },
  prod: {
    src: ["src/**/*.ts"],  
    outDir: "dist/",
    options: {
      fast: "never", // Full compilation for production
      removeComments: true,
      sourceMap: false
    }
  }
}