TSConfig Integration

/**
 * TSConfig integration configuration
 */
interface ITSConfigSupport {
  /** Path to tsconfig.json file or containing directory */
  tsconfig?: string;
  /** Ignore compiler settings from tsconfig.json */
  ignoreSettings?: boolean;
  /** Ignore files array from tsconfig.json */
  ignoreFiles?: boolean;
  /** Overwrite filesGlob with src glob from grunt-ts */
  overwriteFilesGlob?: boolean;
  /** Update files array based on filesGlob evaluation */
  updateFiles?: boolean;
  /** Use TypeScript --project option directly (pass-through mode) */
  passThrough?: boolean;
}

// Usage forms
interface TSConfigUsage {
  /** Boolean form - use tsconfig.json in same directory as Gruntfile.js */
  tsconfig: boolean;
  /** String form - path to tsconfig.json or containing directory */
  tsconfig: string;
  /** Object form - detailed configuration */
  tsconfig: ITSConfigSupport;
}

interface BooleanTSConfigBehavior {
  /** Uses tsconfig.json in same folder as Gruntfile.js */
  configLocation: "same-as-gruntfile";
  /** Processes filesGlob if present, otherwise uses files array */
  fileResolution: "filesGlob-then-files";
  /** Uses all compiler options from tsconfig.json */
  compilerOptions: "all-from-tsconfig";
  /** Grunt-ts src globs are NOT added to tsconfig files */
  srcIgnored: boolean;
}

grunt.initConfig({
  ts: {
    default: {
      tsconfig: true // Uses ./tsconfig.json with all its settings
    }
  }
});

interface StringTSConfigBehavior {
  /** Path can be to tsconfig.json file or containing directory */
  pathResolution: "file-or-directory";
  /** If directory specified, looks for tsconfig.json inside */
  directoryHandling: "automatic-tsconfig-lookup";
  /** Same behavior as boolean form for file processing */
  fileProcessing: "same-as-boolean";
}

// Specific file path
ts: {
  custom: {
    tsconfig: './config/tsconfig.json'
  }
}

// Directory path - uses tsconfig.json inside
ts: {
  subproject: {
    tsconfig: './src/subproject' // Uses ./src/subproject/tsconfig.json
  }
}

interface ObjectTSConfigOptions {
  tsconfig?: string;           // Path (default: './tsconfig.json')
  ignoreFiles?: boolean;       // Ignore files/filesGlob (default: false)
  ignoreSettings?: boolean;    // Ignore compilerOptions (default: false)
  overwriteFilesGlob?: boolean; // Replace filesGlob with src (default: false)
  updateFiles?: boolean;       // Update files array (default: true)
  passThrough?: boolean;       // Use tsc --project mode (default: false)
}

// Use tsconfig compiler options but custom file list
ts: {
  customFiles: {
    src: ['app/**/*.ts'],
    tsconfig: {
      tsconfig: './tsconfig.json',
      ignoreFiles: true // Use src instead of tsconfig files
    }
  }
}

// Use tsconfig files but custom compiler options
ts: {
  customOptions: {
    tsconfig: {
      tsconfig: './tsconfig.json', 
      ignoreSettings: true // Use options below instead
    },
    options: {
      target: 'es6',
      module: 'es2015'
    }
  }
}

// Overwrite tsconfig filesGlob with grunt-ts src
ts: {
  overwriteGlob: {
    src: ['newSrc/**/*.ts'],
    tsconfig: {
      overwriteFilesGlob: true, // Replace filesGlob with src
      updateFiles: true         // Update files array accordingly
    }
  }
}

interface ITSConfigFile {
  /** TypeScript compiler options */
  compilerOptions?: ICompilerOptions;
  /** Explicit list of files to include */
  files?: string[];
  /** Patterns to exclude from compilation */
  exclude?: string[];
  /** Glob patterns for finding files (grunt-ts extension) */
  filesGlob?: string[];
}

interface ICompilerOptions {
  target?: string;
  module?: string;
  outDir?: string;
  sourceMap?: boolean;
  declaration?: boolean;
  // ... all standard TypeScript compiler options
}

interface FileResolutionBehavior {
  /** If filesGlob exists, it takes precedence over files */
  filesGlobPrecedence: boolean;
  /** filesGlob is evaluated and results update files array */
  filesGlobEvaluation: "updates-files-array";
  /** exclude is ignored when filesGlob or files is present */
  excludeIgnored: "when-explicit-files-specified";
  /** If neither filesGlob nor files, uses all .ts/.tsx with exclude */
  fallbackBehavior: "all-ts-files-minus-exclude";
}

// tsconfig.json with filesGlob (grunt-ts extension)
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs"
  },
  "filesGlob": [
    "src/**/*.ts",
    "!src/**/*.spec.ts"
  ],
  "files": [] // Will be populated by grunt-ts
}

// tsconfig.json with explicit files
{
  "compilerOptions": {
    "target": "es5"
  },
  "files": [
    "src/app.ts",
    "src/utils.ts"
  ]
}

// tsconfig.json with exclude pattern
{
  "compilerOptions": {
    "target": "es5"
  },
  "exclude": [
    "node_modules",
    "test/**/*"
  ]
  // Includes all .ts/.tsx files except excluded
}

interface PassThroughMode {
  /** Uses tsc --project <directory> directly */
  compilationMethod: "tsc-project-option";
  /** Supports custom TypeScript compilers with tsconfig support */
  customCompilerSupport: boolean;
  /** TSConfig path must be directory, not file */
  pathRequirement: "directory-only";
  /** Only additionalFlags are passed in addition to --project */
  limitedOptions: "project-and-additional-flags-only";
}

ts: {
  passThrough: {
    tsconfig: {
      tsconfig: './src',  // Directory containing tsconfig.json
      passThrough: true   // Use tsc --project ./src
    },
    options: {
      additionalFlags: '--listFiles --pretty'
    }
  }
}

interface TSConfigFeatureIntegration {
  /** Works with Visual Studio projects (tsconfig overrides VS settings) */
  visualStudioCompatible: boolean;
  /** Compatible with transforms */
  transformsCompatible: boolean;
  /** Compatible with HTML processing */
  htmlProcessingCompatible: boolean;
  /** Compatible with reference files */
  referenceFilesCompatible: boolean;
  /** Fast compilation works with tsconfig */
  fastCompilationCompatible: boolean;
}

interface FileOrderingRules {
  /** Order: tsconfig files, then VS files, then src files */
  combinedOrder: "tsconfig-vs-src";
  /** Files from tsconfig maintain their specified order */
  tsconfigOrder: "preserved";
  /** Duplicates are removed automatically */
  deduplication: "automatic";
}

interface TSConfigUpdateBehavior {
  /** filesGlob is evaluated and results written to files array */
  filesArrayUpdate: "when-updateFiles-true";
  /** filesGlob can be overwritten with src glob */
  filesGlobOverwrite: "when-overwriteFilesGlob-true";
  /** Original tsconfig.json is modified on disk */
  fileModification: boolean;
  /** Backup is not created automatically */
  backupCreation: false;
}

interface TSConfigLimitations {
  /** files configuration not compatible with overwriteFilesGlob */
  filesConfigConflict: "not-supported-with-multiple-file-entries";
  /** filesGlob patterns are relative to tsconfig.json location */
  globPathResolution: "relative-to-tsconfig";
  /** passThrough requires directory path, not file path */
  passThroughPathReq: "directory-only";
  /** Some grunt-ts features may not work in passThrough mode */
  passThroughLimitations: "reduced-functionality";
}

interface TSConfigErrorHandling {
  /** Errors when tsconfig.json file is not found */
  missingConfigFile: "compilation-aborted";
  /** Errors when tsconfig.json has invalid JSON */
  parseErrors: "compilation-aborted";
  /** Warnings when filesGlob matches no files */
  emptyFilesGlob: "warning-issued";
  /** Warnings when exclude patterns are ignored */
  excludeIgnored: "warning-when-files-present";
}