Core Compilation

/**
 * Compile CoffeeScript code to JavaScript
 * @param code - CoffeeScript source code to compile
 * @param options - Compilation options
 * @returns Compiled JavaScript code or compilation result object
 */
function compile(code: string, options?: CompileOptions): string | CompilationResult;

interface CompileOptions {
  /** Source filename for error reporting and source maps */
  filename?: string;
  /** Generate source map as separate object */
  sourceMap?: boolean;
  /** Include source map inline in compiled JavaScript */
  inlineMap?: boolean;
  /** Compile without wrapping in closure (for Node.js modules) */
  bare?: boolean;
  /** Include generated header comment */
  header?: boolean;
  /** Return Abstract Syntax Tree instead of JavaScript */
  ast?: boolean;
  /** Transpile resulting JavaScript using Babel */
  transpile?: TranspileOptions;
}

interface CompilationResult {
  /** Compiled JavaScript code */
  js: string;
  /** Source map object (if sourceMap: true) */
  sourceMap?: SourceMap;
  /** Source map in v3 format (if sourceMap: true) */
  v3SourceMap?: string;
}

interface TranspileOptions {
  /** Babel presets to apply */
  presets?: any[];
  /** Babel plugins to apply */
  plugins?: any[];
  /** Internal transpile function (set automatically) */
  transpile?: Function;
}

const CoffeeScript = require('coffeescript');

// Basic compilation
const jsCode = CoffeeScript.compile('square = (x) -> x * x');
console.log(jsCode);
// Output: var square = function(x) { return x * x; };

// Compilation with source map
const result = CoffeeScript.compile('add = (a, b) -> a + b', {
  sourceMap: true,
  filename: 'math.coffee'
});
console.log(result.js);
console.log(result.v3SourceMap);

// Bare compilation (no wrapper function)
const bareCode = CoffeeScript.compile('module.exports = (x) -> x * 2', {
  bare: true
});

// Get Abstract Syntax Tree instead of JavaScript
const ast = CoffeeScript.compile('square = (x) -> x * x', {
  ast: true
});
console.log(ast.constructor.name); // 'File' (root AST node)

// Compilation with transpilation
const modernJs = CoffeeScript.compile('add = (a, b) -> a + b', {
  transpile: {
    presets: [['@babel/preset-env', { targets: 'node 8' }]]
  }
});

/**
 * Compile and execute CoffeeScript code with Node.js context
 * @param code - CoffeeScript source code to run
 * @param options - Execution options
 * @returns Result of code execution
 */
function run(code: string, options?: RunOptions): any;

interface RunOptions {
  /** Filename for context (__filename, __dirname, require paths) */
  filename?: string;
}

const CoffeeScript = require('coffeescript');

// Run CoffeeScript code
CoffeeScript.run(`
  console.log 'Hello from CoffeeScript!'
  square = (x) -> x * x
  console.log square 5
`);

// Run with filename context
CoffeeScript.run(`
  console.log __filename
  console.log __dirname
`, { filename: '/path/to/script.coffee' });

/**
 * Compile and evaluate CoffeeScript in controlled environment
 * @param code - CoffeeScript source code to evaluate
 * @param options - Evaluation options
 * @returns Result of code evaluation
 */
function eval(code: string, options?: EvalOptions): any;

interface EvalOptions {
  /** Filename for error reporting */
  filename?: string;
  /** Module name for require context */
  modulename?: string;
  /** Sandbox object for evaluation context */
  sandbox?: any;
}

const CoffeeScript = require('coffeescript');

// Evaluate expression
const result = CoffeeScript.eval('2 + 3');
console.log(result); // 5

// Evaluate with sandbox
const sandbox = { x: 10, y: 20 };
const result = CoffeeScript.eval('x + y', { sandbox });
console.log(result); // 30

// Evaluate with custom context
const result = CoffeeScript.eval('process.version', {
  filename: 'repl',
  sandbox: { process: process }
});

/**
 * Transpile JavaScript using Babel (requires @babel/core)
 * @param js - JavaScript code to transpile
 * @param options - Babel options
 * @returns Transpiled code result
 */
function transpile(js: string, options?: any): BabelResult;

interface BabelResult {
  /** Transpiled JavaScript code */
  code: string;
  /** Source map (if enabled) */
  map?: any;
}

const CoffeeScript = require('coffeescript');

// Transpile JavaScript (requires @babel/core)
const result = CoffeeScript.transpile('const add = (a, b) => a + b;', {
  presets: [['@babel/preset-env', { targets: 'ie 11' }]]
});
console.log(result.code);

/**
 * Compile raw file content with filename context
 * @param raw - Raw file content
 * @param filename - Source filename
 * @param options - Compilation options
 * @returns Compiled JavaScript
 */
function _compileRawFileContent(raw: string, filename: string, options?: CompileOptions): string;

/**
 * Read and compile CoffeeScript file from filesystem
 * @param filename - Path to CoffeeScript file
 * @param options - Compilation options
 * @returns Compiled JavaScript
 */
function _compileFile(filename: string, options?: CompileOptions): string;

try {
  CoffeeScript.compile('invalid syntax ->');
} catch (error) {
  console.log(error.name);        // 'SyntaxError'  
  console.log(error.message);     // Error description
  console.log(error.location);    // { first_line, last_line, first_column, last_column }
  console.log(error.filename);    // Source filename (if provided)
}

try {
  CoffeeScript.transpile('code here');
} catch (error) {
  // Error: To use the transpile option, you must have the '@babel/core' module installed
}