Project Management

/**
 * Create a TypeScript project from a tsconfig.json file
 * @param tsConfigFileName - Path to tsconfig.json file
 * @param settings - Additional settings to override or extend tsconfig
 * @returns Project instance for compilation
 */
function createProject(tsConfigFileName: string, settings?: Settings): Project;

/**
 * Create a TypeScript project from inline settings
 * @param settings - Compiler settings and options
 * @returns Project instance for compilation
 */
function createProject(settings?: Settings): Project;

import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';

// Create project from tsconfig.json
const tsProject = ts.createProject('tsconfig.json');

gulp.task('compile', () => {
    return gulp.src('src/**/*.ts')
        .pipe(tsProject())
        .pipe(gulp.dest('dist'));
});

// Create project with custom settings
const libProject = ts.createProject({
    declaration: true,
    target: 'ES2017',
    module: 'commonjs',
    outDir: 'lib'
});

// Override tsconfig.json settings
const devProject = ts.createProject('tsconfig.json', {
    sourceMap: false,
    removeComments: true
});

// Create project with custom TypeScript version
const customTsProject = ts.createProject('tsconfig.json', {
    typescript: require('typescript')
});

interface Project {
    /** 
     * Compile TypeScript files using this project configuration
     * @param reporter - Optional error reporter for handling compilation errors
     * @returns Compilation stream with js and dts sub-streams
     */
    (reporter?: Reporter): ICompileStream;
    
    /** 
     * Get source files from tsconfig.json files/include/exclude patterns
     * Only available for projects created with tsconfig.json
     * @returns ReadWriteStream containing source files
     */
    src(): NodeJS.ReadWriteStream;
    
    /** TypeScript instance used by this project */
    readonly typescript?: typeof ts;
    
    /** Project directory path */
    readonly projectDirectory: string;
    
    /** Configuration file name if created from tsconfig.json */
    readonly configFileName: string;
    
    /** Raw configuration object from tsconfig.json */
    readonly rawConfig: any;
    
    /** Parsed TypeScript configuration */
    readonly config: TsConfig;
    
    /** Resolved compiler options */
    readonly options: ts.CompilerOptions;
    
    /** Project references for composite projects */
    readonly projectReferences: ReadonlyArray<ts.ProjectReference> | undefined;
}

import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';

const tsProject = ts.createProject('tsconfig.json');

// Use project as a function
gulp.task('compile', () => {
    return gulp.src('src/**/*.ts')
        .pipe(tsProject())
        .pipe(gulp.dest('dist'));
});

// Use project.src() to get files from tsconfig
gulp.task('compile-tsconfig-files', () => {
    return tsProject.src()
        .pipe(tsProject())
        .pipe(gulp.dest('dist'));
});

// Access project configuration
gulp.task('show-config', (done) => {
    console.log('Project directory:', tsProject.projectDirectory);
    console.log('Config file:', tsProject.configFileName);
    console.log('Target:', tsProject.options.target);
    console.log('Module:', tsProject.options.module);
    done();
});

// Use project with custom reporter
gulp.task('compile-with-reporter', () => {
    return gulp.src('src/**/*.ts')
        .pipe(tsProject(ts.reporter.longReporter()))
        .pipe(gulp.dest('dist'));
});

interface ProjectInfo {
    /** Input file cache for incremental compilation */
    input: FileCache;
    /** Output stream management */
    output: Output;
    /** Compiler implementation (ProjectCompiler or FileCompiler) */
    compiler: ICompiler;
    /** Whether to generate single output file */
    singleOutput: boolean;
    /** Resolved compiler options */
    options: ts.CompilerOptions;
    /** Project references for composite projects */
    projectReferences: ReadonlyArray<ts.ProjectReference>;
    /** TypeScript instance */
    typescript: typeof ts;
    /** Project directory path */
    directory: string;
    /** Error reporter instance */
    reporter: Reporter;
}

/**
 * Internal function for setting up a project with complete configuration
 * @param projectDirectory - Project directory path
 * @param configFileName - Configuration file name
 * @param rawConfig - Raw configuration object
 * @param config - Parsed TypeScript configuration
 * @param options - Resolved compiler options
 * @param projectReferences - Project references array
 * @param typescript - TypeScript instance
 * @param finalTransformers - Custom transformers
 * @returns Configured project instance
 */
function setupProject(
    projectDirectory: string,
    configFileName: string,
    rawConfig: any,
    config: TsConfig,
    options: ts.CompilerOptions,
    projectReferences: ReadonlyArray<ts.ProjectReference>,
    typescript: typeof ts,
    finalTransformers: FinalTransformers
): Project;

interface TsConfig {
    /** Explicit list of files to include */
    files?: string[];
    /** Include patterns for file matching */
    include?: string[];
    /** Exclude patterns for file matching */
    exclude?: string[];
    /** TypeScript compiler options */
    compilerOptions?: any;
}

type FinalTransformers = undefined | ((program?: ts.Program) => ts.CustomTransformers);