Build System

/**
 * Main build module providing streaming build API
 */
const build = {
  /**
   * Initialize bundler with project configuration
   * @param project - Aurelia project instance
   * @returns Promise resolving to initialized bundler
   */
  src(project: Project): Promise<Bundler>;
  
  /**
   * Create bundle transform stream for processing files
   * @returns Transform stream for bundle operations
   */
  bundle(): Transform;
  
  /**
   * Build and write bundles to disk
   * @param options - Build options
   * @returns Promise resolving when build completes
   */
  dest(options?: BuildOptions): Promise<void>;
  
  /**
   * Create loader code for the platform
   * @param project - Aurelia project instance
   * @returns Promise resolving to loader code string
   */
  createLoaderCode(project?: Project): Promise<string>;
  
  /**
   * Create loader configuration object
   * @param project - Aurelia project instance
   * @returns Promise resolving to loader configuration
   */
  createLoaderConfig(project?: Project): Promise<object>;
  
  /**
   * Clear build cache directory
   * @returns Promise resolving when cache is cleared
   */
  clearCache(): Promise<void>;
};

interface BuildOptions {
  env?: string;
  watch?: boolean;
  sourcemaps?: boolean;
  minify?: boolean;
  rev?: boolean;
}

const { build, Project } = require("aurelia-cli");

// Basic build process
const project = await Project.establish("./my-app");

// Initialize and execute build
await build.src(project);
await build.dest({ env: "prod", minify: true });

// Using streaming API
const gulp = require("gulp");

gulp.task("build", () => {
  return gulp.src("src/**/*.js")
    .pipe(build.bundle())
    .pipe(build.dest());
});

// Create loader configuration
const project = await Project.establish("./");
const loaderConfig = await build.createLoaderConfig(project);
console.log(JSON.stringify(loaderConfig, null, 2));

// Clear cache for clean build
await build.clearCache();

/**
 * Advanced bundling engine for Aurelia applications
 */
class Bundler {
  /**
   * Create bundler instance
   * @param project - Aurelia project
   * @param analyzer - Package analyzer instance
   * @param installer - Package installer instance
   * @returns Promise resolving to Bundler
   */
  static create(project: Project, analyzer: PackageAnalyzer, installer: PackageInstaller): Promise<Bundler>;
  
  /**
   * Initialize bundler with project configuration
   * @param project - Aurelia project instance
   * @param packageAnalyzer - Package analyzer for dependency resolution
   * @param packageInstaller - Package installer for auto-install
   */
  constructor(project: Project, packageAnalyzer: PackageAnalyzer, packageInstaller: PackageInstaller);
  
  /**
   * Add file to bundle processing
   * @param file - Vinyl file object
   * @param inclusion - Optional inclusion context
   * @returns BundledSource instance
   */
  addFile(file: VinylFile, inclusion?: object): BundledSource;
  
  /**
   * Update existing file in bundle
   * @param file - Updated vinyl file object
   * @param inclusion - Optional inclusion context
   */
  updateFile(file: VinylFile, inclusion?: object): void;
  
  /**
   * Build all bundles
   * @param options - Build options with callbacks
   * @returns Promise resolving when build completes
   */
  build(options?: {
    onRequiringModule?: (moduleId: string) => void;
    onNotBundled?: (moduleId: string) => void;
  }): Promise<void>;
  
  /**
   * Write bundles to disk
   * @returns Promise resolving when write completes
   */
  write(): Promise<void>;
  
  /**
   * Add bundle to bundler
   * @param bundle - Bundle instance to add
   */
  addBundle(bundle: Bundle): void;
  
  /**
   * Configure dependency for bundling
   * @param dependency - Dependency to configure
   * @returns Promise resolving when configured
   */
  configureDependency(dependency: string | object): Promise<void>;
  
  // Properties
  project: Project;
  bundles: Bundle[];
  loaderOptions: object;
  environment: string;
  buildOptions: Configuration;
}

interface VinylFile {
  path: string;
  contents: Buffer;
  base: string;
}

interface BundledSource {
  path: string;
  contents: Buffer;
  file: VinylFile;
  requiresTransform: boolean;
}

const { Bundler, PackageAnalyzer, PackageInstaller } = require("aurelia-cli");

// Create bundler manually
const project = await Project.establish("./my-app");
const analyzer = new PackageAnalyzer(project);
const installer = new PackageInstaller(project);

const bundler = await Bundler.create(project, analyzer, installer);

// Process files
const fs = require("fs");
const path = require("path");

const file = {
  path: path.resolve("src/main.js"),
  contents: fs.readFileSync("src/main.js"),
  base: path.resolve("src")
};

bundler.addFile(file);
await bundler.build();
await bundler.write();

/**
 * Individual bundle representation
 */
class Bundle {
  /**
   * Initialize bundle
   * @param name - Bundle name
   * @param config - Bundle configuration
   */
  constructor(name: string, config: BundleConfig);
  
  /**
   * Add dependency to bundle
   * @param description - Dependency description
   */
  addDependency(description: DependencyDescription): void;
  
  /**
   * Get all bundled modules
   * @returns Array of bundled modules
   */
  getBundledModules(): BundledModule[];
  
  /**
   * Get bundled dependencies
   * @returns Array of bundled dependencies
   */
  getBundledDependencies(): BundledDependency[];
  
  /**
   * Get bundle filename for loader type and environment
   * @param loaderType - Loader type (requirejs, systemjs)
   * @param environment - Build environment
   * @returns Bundle filename
   */
  getBundleName(loaderType: string, environment: string): string;
  
  /**
   * Write bundle to destination
   * @param destination - Output directory
   * @param transform - Optional transform function
   * @returns Promise resolving when write completes
   */
  write(destination: string, transform?: Function): Promise<void>;
  
  // Properties
  name: string;
  config: BundleConfig;
  dependencies: DependencyDescription[];
  includes: string[];
  excludes: string[];
}

interface BundleConfig {
  name: string;
  source: string[];
  options?: {
    inject?: boolean;
    minify?: boolean;
    rev?: boolean;
  };
}

/**
 * Package analyzer for dependency resolution
 */
class PackageAnalyzer {
  /**
   * Initialize analyzer with project
   * @param project - Aurelia project instance
   */
  constructor(project: Project);
  
  /**
   * Analyze package dependencies
   * @param packageName - Name of package to analyze
   * @returns Promise resolving to analysis result
   */
  analyze(packageName: string): Promise<AnalysisResult>;
  
  /**
   * Reverse engineer package structure
   * @param description - Dependency description
   * @returns Promise resolving to package structure
   */
  reverseEngineer(description: DependencyDescription): Promise<PackageStructure>;
  
  // Properties
  project: Project;
  cache: Map<string, AnalysisResult>;
}

interface AnalysisResult {
  name: string;
  version: string;
  main: string;
  dependencies: string[];
  peerDependencies: string[];
  files: string[];
}

/**
 * Report webpack development server readiness
 * @param options - Webpack server options
 */
function reportWebpackReadiness(options: WebpackOptions): void;

interface WebpackOptions {
  /** Server host */
  host?: string;
  /** Server port */
  port?: number;
  /** Use HTTPS */
  https?: boolean;
  /** Public URL */
  public?: string;
  /** Public path for assets */
  publicPath?: string;
  /** Content base directory */
  contentBase?: string | string[];
  /** Socket path for HMR */
  socket?: string;
  /** History API fallback configuration */
  historyApiFallback?: {
    index?: string;
  };
}

const { reportWebpackReadiness } = require("aurelia-cli");

// Report webpack server status
const webpackOptions = {
  host: "localhost",
  port: 8080,
  https: false,
  publicPath: "/",
  contentBase: ["src", "static"],
  historyApiFallback: {
    index: "/index.html"
  }
};

reportWebpackReadiness(webpackOptions);
// Output: Project is running at http://localhost:8080
//         webpack output is served from /
//         Content not from webpack is served from src, static
//         404s will fallback to /index.html

/**
 * Module loader configuration generation
 */
interface LoaderConfig {
  /** Base URL for module resolution */
  baseUrl?: string;
  /** Path mappings for modules */
  paths?: { [key: string]: string };
  /** Package configurations */
  packages?: { [key: string]: PackageConfig };
  /** Bundle configurations */
  bundles?: { [key: string]: string[] };
  /** Module dependencies */
  deps?: { [key: string]: string[] };
}

interface PackageConfig {
  name: string;
  location?: string;
  main?: string;
  defaultExtension?: string;
}

// Generated loader config example
const loaderConfig = await build.createLoaderConfig(project);

/*
{
  "baseUrl": "src",
  "paths": {
    "npm:*": "../node_modules/*"
  },
  "packages": {
    "app": {
      "main": "main.js",
      "defaultExtension": "js"
    }
  },
  "bundles": {
    "app-bundle.js": [
      "app/main",
      "app/app",
      "app/components/hello-world"
    ],
    "vendor-bundle.js": [
      "npm:aurelia-framework",
      "npm:aurelia-bootstrapper"
    ]
  }
}
*/

// Use in HTML
const loaderCode = await build.createLoaderCode(project);
// Generates System.js or RequireJS configuration code

/**
 * Build pipeline stages:
 * 1. Source file discovery and analysis
 * 2. Dependency resolution and bundling
 * 3. Module transformation (TypeScript, Babel)
 * 4. Asset optimization (minification, source maps)
 * 5. Bundle generation and writing
 */

interface BuildPipeline {
  /** Source files matching */
  sources: string[];
  /** Bundle configurations */
  bundles: BundleConfig[];
  /** Transformation options */
  transforms: TransformConfig[];
  /** Output options */
  output: OutputConfig;
}

interface TransformConfig {
  name: string;
  filePattern: string;
  options: object;
}

interface OutputConfig {
  path: string;
  filename: string;
  sourceMap: boolean;
  minify: boolean;
}