Core Compilation API

/**
 * Main entry point for the Scala 3 compiler
 * Extends Driver with default settings for command-line usage
 */
object Main extends Driver {
  /**
   * Command-line entry point for batch compilation
   * @param args Array of command-line arguments including source files and options
   */
  def main(args: Array[String]): Unit
}

// Command-line style compilation
dotty.tools.dotc.Main.main(Array(
  "src/main/scala/MyClass.scala",
  "-d", "target/classes",
  "-classpath", "lib/dependency.jar"
))

// With compiler flags
dotty.tools.dotc.Main.main(Array(
  "src/main/scala/MyClass.scala",
  "-Xfatal-warnings",
  "-feature",
  "-deprecation"
))

/**
 * Core compiler driver with customizable compilation process
 * Provides multiple entry points for different integration scenarios
 */
class Driver {
  /**
   * Simple compilation entry point with default reporter
   * @param args Array of compilation arguments
   * @return Reporter containing compilation results and diagnostics
   */
  def process(args: Array[String]): Reporter
  
  /**
   * Principal compilation entry point with custom reporter and callback
   * @param args Array of compilation arguments
   * @param reporter Custom reporter for handling diagnostics (null for default)
   * @param callback Custom callback for compilation events (null for no callback)
   * @return Reporter containing compilation results and diagnostics
   */
  def process(args: Array[String], reporter: Reporter | Null, callback: CompilerCallback | Null): Reporter
  
  /**
   * Java reflection-friendly entry point using SimpleReporter interface
   * @param args Array of compilation arguments
   * @param simple SimpleReporter implementation for Java interop
   * @param callback CompilerCallback for compilation events
   * @return ReporterResult with compilation outcome
   */
  def process(args: Array[String], simple: SimpleReporter | Null, callback: CompilerCallback | Null): ReporterResult
  
  /**
   * Setup compilation context from command-line arguments
   * @param args Array of compilation arguments
   * @param rootCtx Root compilation context
   * @return Option containing source files and configured context, or None if setup failed
   */
  def setup(args: Array[String], rootCtx: Context): Option[(List[AbstractFile], Context)]
}

import dotty.tools.dotc.Driver
import dotty.tools.dotc.interfaces.{SimpleReporter, CompilerCallback}

val driver = new Driver

// Simple compilation
val reporter = driver.process(Array("MyFile.scala", "-d", "output"))
if (reporter.hasErrors) {
  println("Compilation failed")
}

// With custom reporter
val customReporter = new SimpleReporter {
  override def report(diagnostic: Diagnostic): Unit = {
    println(s"[${diagnostic.level}] ${diagnostic.message}")
  }
}

val callback = new CompilerCallback {
  override def onClassGenerated(source, generatedClass, className) = {
    println(s"Generated: $className")
  }
}

val result = driver.process(
  Array("MyFile.scala", "-classpath", "lib/*"),
  customReporter,
  callback
)

/**
 * Central class managing compilation phases and runs
 * Coordinates the entire compilation pipeline
 */
class Compiler {
  /**
   * Complete list of compilation phases organized by phase groups
   * Each inner list represents phases that can run in parallel
   * @return Nested list of Phase objects representing the compilation pipeline
   */
  def phases: List[List[Phase]]
  
  /**
   * Create a new compilation run within the given context
   * @param ctx Compilation context
   * @return New Run instance for processing source files
   */
  def newRun(using Context): Run
  
  /**
   * Generate unique run identifier for tracking compilation runs
   * @return Unique integer identifier for the next compilation run
   */
  def nextRunId: Int
  
  /**
   * Reset compiler state for clean compilation
   * Clears caches and resets internal state
   * @param ctx Compilation context
   */
  def reset()(using Context): Unit
}

/**
 * Represents a single compilation run with file processing
 * Manages the execution of compilation phases on a set of source files
 */
class Run {
  /**
   * Compile the given source files
   * @param files List of source files to compile
   */
  def compile(files: List[AbstractFile])(using Context): Unit
  
  /**
   * Get the unique identifier for this compilation run
   * @return Integer run ID
   */
  def runId: Int
  
  /**
   * Check if this compilation run produced any errors
   * @return True if errors were reported during compilation
   */
  def hasErrors: Boolean
}

/**
 * Represents a single source file being compiled
 * Contains source content, parsing results, and compilation metadata
 */
class CompilationUnit {
  /**
   * The source file being compiled
   */
  def source: SourceFile
  
  /**
   * The abstract syntax tree for this compilation unit
   */
  def untpdTree: Tree[?]
  
  /**
   * The typed abstract syntax tree (available after typing phase)
   */
  def tpdTree: Tree[?]
}

import dotty.tools.dotc.{Compiler, Driver}
import dotty.tools.dotc.core.Contexts._

// Custom compiler usage
class MyCompiler extends Compiler {
  override def phases = 
    List(List(/* custom phases */)) ++ super.phases
}

val driver = new Driver {
  override def newCompiler(using Context) = new MyCompiler
}

// Using compiler directly
given Context = initContext()
val compiler = new Compiler
val run = compiler.newRun
// run.compile(sourceFiles)

/**
 * Abstract representation of a file or directory
 * Used throughout the compiler for source files and output locations
 */
abstract class AbstractFile {
  def name: String
  def path: String
  def isDirectory: Boolean
  def exists: Boolean
}

/**
 * Represents a source file with content and metadata
 */
class SourceFile {
  def file: AbstractFile
  def content: Array[Char]
  def lineIndices: Array[Int]
}

/**
 * Base class for compilation reporting
 * Handles diagnostics, errors, and warnings during compilation
 */
abstract class Reporter {
  def hasErrors: Boolean
  def hasWarnings: Boolean
  def errorCount: Int
  def warningCount: Int
}