Compiler API

/**
 * Main Stencil compiler interface
 */
interface Compiler {
  /** Build the project once */
  build(): Promise<CompilerBuildResults>;
  /** Create a file watcher for continuous builds */
  createWatcher(): Promise<CompilerWatcher>;
  /** Destroy the compiler and clean up resources */
  destroy(): Promise<void>;
  /** Compiler system instance */
  sys: CompilerSystem;
}

/**
 * Results from a compiler build operation
 */
interface CompilerBuildResults {
  /** Unique build identifier */
  buildId: number;
  /** Component dependency graph */
  componentGraph?: BuildResultsComponentGraph;
  /** Compilation diagnostics and errors */
  diagnostics: Diagnostic[];
  /** Directories added during build */
  dirsAdded: string[];
  /** Directories deleted during build */
  dirsDeleted: string[];
  /** Build duration in milliseconds */
  duration: number;
  /** Files added during build */
  filesAdded: string[];
  /** Files changed during build */
  filesChanged: string[];
  /** Files deleted during build */
  filesDeleted: string[];
  /** Files updated during build */
  filesUpdated: string[];
  /** Whether build had errors */
  hasError: boolean;
  /** Whether build was successful */
  hasSuccessfulBuild: boolean;
  /** Hot module replacement data */
  hmr?: HotModuleReplacement;
  /** Path to hydrate app file */
  hydrateAppFilePath?: string;
  /** Whether this was a rebuild */
  isRebuild: boolean;
  /** Project namespace */
  namespace: string;
  /** Build outputs generated */
  outputs: BuildOutput[];
  /** Root directory path */
  rootDir: string;
  /** Source directory path */
  srcDir: string;
  /** Build timestamp */
  timestamp: string;
}

interface BuildResultsComponentGraph {
  [scopeId: string]: string[];
}

interface BuildOutput {
  /** Output target type */
  type: string;
  /** Generated files */
  files: string[];
}

/**
 * Create a new Stencil compiler instance
 * @param config - Stencil configuration object
 * @returns Promise resolving to a Compiler instance
 */
function createCompiler(config: StencilConfig): Promise<Compiler>;

import { createCompiler } from '@stencil/core/compiler';

async function buildProject() {
  const compiler = await createCompiler({
    // Stencil config
    namespace: 'MyApp',
    outputTargets: [
      { type: 'dist' },
      { type: 'www' }
    ]
  });

  try {
    const results = await compiler.build();
    
    console.log(`Build completed in ${results.duration}ms`);
    console.log(`Generated ${results.outputs.length} outputs`);
    
    if (results.hasError) {
      console.error('Build had errors:');
      results.diagnostics.forEach(diagnostic => {
        console.error(diagnostic.messageText);
      });
    }
  } finally {
    await compiler.destroy();
  }
}

/**
 * File watcher for continuous builds
 */
interface CompilerWatcher extends BuildOnEvents {
  /** Start watching for file changes */
  start: () => Promise<WatcherCloseResults>;
  /** Stop watching and close */
  close: () => Promise<WatcherCloseResults>;
  /** Request specific file processing */
  request: (data: CompilerRequest) => Promise<CompilerRequestResponse>;
}

interface WatcherCloseResults {
  /** Exit code from watcher */
  exitCode: number;
}

interface CompilerRequest {
  /** File path to process */
  path?: string;
}

interface CompilerRequestResponse {
  /** Requested file path */
  path: string;
  /** Node module ID */
  nodeModuleId: string;
  /** Node module version */
  nodeModuleVersion: string;
  /** Resolved Node module path */
  nodeResolvedPath: string;
  /** Cache file path */
  cachePath: string;
  /** Whether result was from cache */
  cacheHit: boolean;
  /** File content */
  content: string;
  /** HTTP status code */
  status: number;
}

async function watchProject() {
  const compiler = await createCompiler(config);
  const watcher = await compiler.createWatcher();
  
  // Listen to build events
  watcher.on('buildStart', (buildStart) => {
    console.log(`Build ${buildStart.buildId} started`);
  });
  
  watcher.on('buildFinish', (buildResults) => {
    console.log(`Build ${buildResults.buildId} finished in ${buildResults.duration}ms`);
    if (buildResults.hasError) {
      console.error('Build errors occurred');
    }
  });
  
  watcher.on('buildLog', (buildLog) => {
    console.log(`Build ${buildLog.buildId}: ${buildLog.messages.join(' ')}`);
  });
  
  // Start watching
  const results = await watcher.start();
  console.log(`Watcher exited with code ${results.exitCode}`);
}

/**
 * Compiler system abstraction for file operations
 */
interface CompilerSystem {
  /** System name identifier */
  name: 'node' | 'in-memory';
  /** System version */
  version: string;
  /** Build events system */
  events?: BuildEvents;
  /** System details */
  details?: SystemDetails;
  
  /** Add cleanup callback */
  addDestroy(cb: () => void): void;
  /** Check file/directory access */
  access(p: string): Promise<boolean>;
  /** Synchronous access check */
  accessSync(p: string): boolean;
  /** Copy file between paths */
  copyFile(src: string, dst: string): Promise<boolean>;
  /** Destroy system and cleanup */
  destroy(): Promise<void>;
  /** Create directory */
  createDir(p: string, opts?: CompilerSystemCreateDirectoryOptions): Promise<CompilerSystemCreateDirectoryResults>;
  /** Synchronous create directory */
  createDirSync(p: string, opts?: CompilerSystemCreateDirectoryOptions): CompilerSystemCreateDirectoryResults;
  /** Get home directory */
  homeDir(): string;
  /** Check if running in TTY */
  isTTY(): boolean;
  /** Encode string to base64 */
  encodeToBase64(str: string): string;
  /** Exit process */
  exit(exitCode: number): Promise<void>;
  /** Get current directory */
  getCurrentDirectory(): string;
  /** Get compiler executing path */
  getCompilerExecutingPath(): string;
  /** Get dev server executing path */
  getDevServerExecutingPath?(): string;
  /** Get environment variable */
  getEnvironmentVar?(key: string): string;
  /** Get local module path */
  getLocalModulePath(opts: { rootDir: string; moduleId: string; path: string }): string;
  /** Get remote module URL */
  getRemoteModuleUrl(opts: { moduleId: string; path?: string; version?: string }): string;
  /** Hardware concurrency (CPU cores) */
  hardwareConcurrency: number;
  /** Check if path is symbolic link */
  isSymbolicLink(p: string): Promise<boolean>;
  /** Schedule next tick callback */
  nextTick(cb: () => void): void;
  /** Normalize file path */
  normalizePath(p: string): string;
  /** Platform path utilities */
  platformPath: PlatformPath;
  /** Read directory contents */
  readDir(p: string): Promise<string[]>;
  /** Synchronous read directory */
  readDirSync(p: string): string[];
  /** Read file content */
  readFile(p: string): Promise<string>;
  readFile(p: string, encoding: 'utf8'): Promise<string>;
  readFile(p: string, encoding: 'binary'): Promise<any>;
  /** Synchronous read file */
  readFileSync(p: string, encoding?: string): string;
  /** Resolve real path */
  realpath(p: string): Promise<CompilerSystemRealpathResults>;
  /** Synchronous resolve real path */
  realpathSync(p: string): CompilerSystemRealpathResults;
  /** Remove destroy callback */
  removeDestroy(cb: () => void): void;
  /** Rename file/directory */
  rename(oldPath: string, newPath: string): Promise<CompilerSystemRenameResults>;
  /** Resolve path */
  resolvePath(p: string): string;
  /** Remove directory */
  removeDir(p: string, opts?: CompilerSystemRemoveDirectoryOptions): Promise<CompilerSystemRemoveDirectoryResults>;
  /** Synchronous remove directory */
  removeDirSync(p: string, opts?: CompilerSystemRemoveDirectoryOptions): CompilerSystemRemoveDirectoryResults;
  /** Remove file */
  removeFile(p: string): Promise<CompilerSystemRemoveFileResults>;
  /** Synchronous remove file */
  removeFileSync(p: string): CompilerSystemRemoveFileResults;
  /** Get file/directory stats */
  stat(p: string): Promise<CompilerFsStats>;
  /** Synchronous get file/directory stats */
  statSync(p: string): CompilerFsStats;
  /** Get temporary directory */
  tmpDirSync(): string;
  /** Watch timeout in milliseconds */
  watchTimeout?: number;
  /** Write file content */
  writeFile(p: string, content: string): Promise<CompilerSystemWriteFileResults>;
  /** Synchronous write file */
  writeFileSync(p: string, content: string): CompilerSystemWriteFileResults;
}

interface CompilerFsStats {
  /** Whether path is a directory */
  isDirectory: boolean;
  /** Whether path is a file */
  isFile: boolean;
  /** Whether path is a symbolic link */
  isSymbolicLink: boolean;
  /** File size in bytes */
  size: number;
  /** Modified time in milliseconds */
  mtimeMs?: number;
  /** Error if operation failed */
  error: any;
}

interface SystemDetails {
  /** CPU model */
  cpuModel: string;
  /** Free memory function */
  freemem(): number;
  /** Platform identifier */
  platform: 'darwin' | 'windows' | 'linux' | '';
  /** OS release version */
  release: string;
  /** Total memory */
  totalmem: number;
}

/**
 * Build event system for monitoring compilation
 */
interface BuildEvents extends BuildOnEvents, BuildEmitEvents {
  /** Unsubscribe all event listeners */
  unsubscribeAll(): void;
}

interface BuildOnEvents {
  /** Listen to any build event */
  on(cb: (eventName: CompilerEventName, data: any) => void): BuildOnEventRemove;
  /** Listen to file add events */
  on(eventName: 'fileAdd', cb: (path: string) => void): BuildOnEventRemove;
  /** Listen to file delete events */
  on(eventName: 'fileDelete', cb: (path: string) => void): BuildOnEventRemove;
  /** Listen to file update events */
  on(eventName: 'fileUpdate', cb: (path: string) => void): BuildOnEventRemove;
  /** Listen to directory add events */
  on(eventName: 'dirAdd', cb: (path: string) => void): BuildOnEventRemove;
  /** Listen to directory delete events */
  on(eventName: 'dirDelete', cb: (path: string) => void): BuildOnEventRemove;
  /** Listen to build start events */
  on(eventName: 'buildStart', cb: (buildStart: CompilerBuildStart) => void): BuildOnEventRemove;
  /** Listen to build finish events */
  on(eventName: 'buildFinish', cb: (buildResults: CompilerBuildResults) => void): BuildOnEventRemove;
  /** Listen to build log events */
  on(eventName: 'buildLog', cb: (buildLog: BuildLog) => void): BuildOnEventRemove;
  /** Listen to build no-change events */
  on(eventName: 'buildNoChange', cb: () => void): BuildOnEventRemove;
}

interface BuildEmitEvents {
  /** Emit build events */
  emit(eventName: CompilerEventName, path: string): void;
  emit(eventName: 'buildStart', buildStart: CompilerBuildStart): void;
  emit(eventName: 'buildFinish', buildResults: CompilerBuildResults): void;
  emit(eventName: 'buildNoChange', buildNoChange: BuildNoChangeResults): void;
  emit(eventName: 'buildLog', buildLog: BuildLog): void;
  emit(eventName: 'fsChange', fsWatchResults: FsWatchResults): void;
}

type BuildOnEventRemove = () => boolean;

interface CompilerBuildStart {
  /** Build identifier */
  buildId: number;
  /** Build start timestamp */
  timestamp: string;
}

interface BuildLog {
  /** Build identifier */
  buildId: number;
  /** Log messages */
  messages: string[];
  /** Build progress percentage */
  progress: number;
}

interface BuildNoChangeResults {
  /** Build identifier */
  buildId: number;
  /** No changes detected flag */
  noChange: boolean;
}

interface FsWatchResults {
  /** Directories added */
  dirsAdded: string[];
  /** Directories deleted */
  dirsDeleted: string[];
  /** Files updated */
  filesUpdated: string[];
  /** Files added */
  filesAdded: string[];
  /** Files deleted */
  filesDeleted: string[];
}

/**
 * Transpile TypeScript/JSX code to JavaScript
 * @param code - Source code to transpile
 * @param opts - Transpilation options
 * @returns Transpilation results
 */
function transpile(code: string, opts?: TranspileOptions): Promise<TranspileResults>;

interface TranspileOptions {
  /** Component export style */
  componentExport?: 'customelement' | 'module' | string | undefined;
  /** Component metadata handling */
  componentMetadata?: 'runtimestatic' | 'compilerstatic' | string | undefined;
  /** Core import path */
  coreImportPath?: string;
  /** Current working directory */
  currentDirectory?: string;
  /** Input file name */
  file?: string;
  /** Module format */
  module?: 'cjs' | 'esm' | string;
  /** Property proxy style */
  proxy?: 'defineproperty' | string | undefined;
  /** Style handling */
  style?: 'static' | string | undefined;
  /** Style import data format */
  styleImportData?: 'queryparams' | string | undefined;
  /** Compilation target */
  target?: CompileTarget;
  /** Source map generation */
  sourceMap?: boolean | 'inline';
  /** Base URL for module resolution */
  baseUrl?: string;
  /** Path mapping for module resolution */
  paths?: { [key: string]: string[] };
  /** Compiler system */
  sys?: CompilerSystem;
  /** Transform aliased import paths */
  transformAliasedImportPaths?: boolean;
}

interface TranspileResults {
  /** Compiled JavaScript code */
  code: string;
  /** Additional data */
  data?: any[];
  /** Compilation diagnostics */
  diagnostics: Diagnostic[];
  /** Import statements found */
  imports?: { path: string }[];
  /** Input file extension */
  inputFileExtension: string;
  /** Input file path */
  inputFilePath: string;
  /** Generated source map */
  map: any;
  /** Output file path */
  outputFilePath: string;
}

type CompileTarget = 
  | 'latest'
  | 'esnext'
  | 'es2020'
  | 'es2019'
  | 'es2018'
  | 'es2017'
  | 'es2015'
  | 'es5'
  | string
  | undefined;

import { transpile } from '@stencil/core/compiler';

async function transpileComponent() {
  const sourceCode = `
    import { Component, h } from '@stencil/core';
    
    @Component({
      tag: 'my-component'
    })
    export class MyComponent {
      render() {
        return <div>Hello World</div>;
      }
    }
  `;
  
  const results = await transpile(sourceCode, {
    module: 'esm',
    target: 'es2017',
    componentExport: 'customelement',
    file: 'my-component.tsx'
  });
  
  console.log('Transpiled code:', results.code);
  
  if (results.diagnostics.length > 0) {
    console.log('Diagnostics:', results.diagnostics);
  }
}