mt-lang 0.2.0

data/lib/milk_tea/tooling/cli.rb

@@ -0,0 +1,2688 @@
+# frozen_string_literal: true
+
+require "pp"
+require "json"
+require "socket"
+require "stringio"
+require "tempfile"
+require "timeout"
+require "tmpdir"
+
+module MilkTea
+  class CLI
+    GENERATED_FILE_HEADER_PREFIX = "# generated by mtc".freeze
+
+    # Single source of truth for the top-level command set: used by the help
+    # overview and shell-completion generation so they cannot drift.
+    COMMANDS = [
+      ["check",       "Type-check and lint source files"],
+      ["build",       "Compile a source file or package"],
+      ["run",         "Build and execute a program"],
+      ["run-module",  "Resolve, build, and run a module by name"],
+      ["test",        "Discover and run @[test] functions"],
+      ["new",         "Scaffold a new package"],
+      ["format",      "Format source files in place or check formatting"],
+      ["lint",        "Lint source files and report warnings"],
+      ["lex",         "Print the lexer token stream"],
+      ["parse",       "Parse source and print the AST"],
+      ["lower",       "Lower source to IR and print it"],
+      ["emit-c",      "Compile source to C and print it"],
+      ["debug",       "Print tokens, AST, facts, and diagnostics"],
+      ["deps",        "Manage package dependencies"],
+      ["toolchain",   "Manage the native toolchain"],
+      ["bindgen",     "Generate a binding module from a C header"],
+      ["cache",       "Inspect and manage the build cache"],
+      ["docs",        "Serve the local documentation site"],
+      ["snapshot",    "Render a highlighted HTML snapshot"],
+      ["lsp",         "Start the Language Server Protocol server"],
+      ["dap",         "Start the Debug Adapter Protocol server"],
+      ["completions", "Print a shell completion script"],
+    ].freeze
+
+    def self.start(argv = ARGV, out: $stdout, err: $stderr, source_overrides: nil, build_frontend: nil)
+      new(argv, out:, err:, source_overrides:, build_frontend:).start
+    end
+
+    def initialize(argv, out:, err:, source_overrides: nil, build_frontend: nil)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @include_module_roots = []
+      @include_path_flags = []
+      @ambient_module_roots = MilkTea::ModuleRoots.roots_for_path(Dir.pwd)
+      @source_overrides = normalize_source_overrides(source_overrides)
+      @build_frontend = build_frontend
+      @color = :auto
+      @verbose = false
+      @quiet = false
+    end
+
+    def start
+      return 1 unless extract_global_options!
+
+      extract_include_paths!
+      command = @argv.shift
+
+      if version_request?(command)
+        @out.puts("mtc #{MilkTea::VERSION}")
+        return 0
+      end
+
+      if help_request?(command)
+        topic = command == "help" ? @argv.shift : nil
+        if topic
+          print_command_help(topic, @out)
+        else
+          print_help(@out)
+        end
+        return 0
+      end
+
+      if command && @include_module_roots.any? && !command_supports_include_paths?(command)
+        @err.puts("unknown option #{@include_path_flags.first} for #{command}")
+        print_usage(@err)
+        return 1
+      end
+
+      if @argv.first == "--help" || @argv.first == "-h"
+        @argv.shift
+        print_command_help(command, @out)
+        return 0
+      end
+
+      case command
+      when "lex"
+        lex_command
+      when "parse"
+        parse_command
+      when "format"
+        format_command
+      when "lint"
+        lint_command
+      when "check"
+        check_command
+      when "lower"
+        lower_command
+      when "emit-c"
+        emit_c_command
+      when "build"
+        build_command
+      when "test"
+        test_command
+      when "run"
+        run_command
+      when "run-module"
+        app_command
+      when "new"
+        new_command
+      when "debug"
+        debug_command
+      when "toolchain"
+        toolchain_command
+      when "deps"
+        deps_command
+      when "bindgen"
+        bindgen_command
+      when "cache"
+        cache_command
+      when "docs"
+        docs_command
+      when "snapshot"
+        snapshot_command
+      when "lsp"
+        lsp_command
+      when "dap"
+        dap_command
+      when "completions"
+        completions_command
+      else
+        print_usage(@err)
+        1
+      end
+    rescue StandardError => e
+      raise unless handled_cli_error?(e)
+
+      @err.puts(ErrorFormatter.format(e, color: error_color?(@err)))
+      1
+    end
+
+    private
+
+    def version_request?(command)
+      %w[version --version -V].include?(command)
+    end
+
+    def help_request?(command)
+      command.nil? || %w[help --help -h].include?(command)
+    end
+
+    # Pulls global options that may appear before the first `--` separator out of
+    # @argv so each subcommand parser sees a clean argument list. Stops at `--` so
+    # arguments forwarded to a run target (e.g. `mtc run app -- --verbose`) are
+    # preserved verbatim.
+    def extract_global_options!
+      remaining = []
+      forwarding = false
+      i = 0
+      while i < @argv.length
+        arg = @argv[i]
+        if forwarding
+          remaining << arg
+          i += 1
+          next
+        end
+
+        case arg
+        when "--"
+          forwarding = true
+          remaining << arg
+          i += 1
+        when "-v", "--verbose"
+          @verbose = true
+          i += 1
+        when "-q", "--quiet"
+          @quiet = true
+          i += 1
+        when "--color"
+          value = @argv[i + 1]
+          return invalid_color(value) unless valid_color?(value)
+
+          @color = value.to_sym
+          i += 2
+        when /\A--color=(.*)\z/
+          value = ::Regexp.last_match(1)
+          return invalid_color(value) unless valid_color?(value)
+
+          @color = value.to_sym
+          i += 1
+        else
+          remaining << arg
+          i += 1
+        end
+      end
+      @argv = remaining
+      true
+    end
+
+    def valid_color?(value)
+      %w[auto always never].include?(value)
+    end
+
+    def invalid_color(value)
+      @err.puts("--color must be auto, always, or never#{value ? " (got #{value})" : ''}")
+      false
+    end
+
+    def error_color?(io)
+      case @color
+      when :always then true
+      when :never then false
+      else io.respond_to?(:tty?) && io.tty?
+      end
+    end
+
+    # Prints an informational/progress line unless --quiet was given.
+    def info(message)
+      @out.puts(message) unless @quiet
+    end
+
+
+    def lex_command
+      path = nil
+
+      args = @argv.dup
+      @argv = []
+      until args.empty?
+        arg = args.shift
+        next if arg == "--"
+
+        if path.nil?
+          path = arg
+        else
+          @err.puts("unknown option: #{arg}")
+          print_usage(@err)
+          return 1
+        end
+      end
+
+      unless path
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      tokens = Lexer.lex(read_source_file(path), path: path)
+      @out.write(PP.pp(tokens, +""))
+      0
+    end
+
+    def parse_command
+      args = @argv.dup
+      @argv = []
+      until args.empty?
+        arg = args.shift
+        @argv << arg
+      end
+
+      unless @argv.any?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      resolution = extract_resolution_flags!
+      input_paths = @argv.dup
+      return 1 unless ensure_known_source_operands!("parse", input_paths)
+
+      paths = expand_source_paths(input_paths)
+      return 0 if print_no_source_files_if_empty(paths, input_paths)
+
+      ensure_current_lockfiles!(paths) if resolution[:frozen]
+
+      multiple = paths.length > 1
+      paths.each_with_index do |path, index|
+        ast = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).load_file(path)
+        if multiple
+          @out.puts("# --- #{path} ---")
+        end
+        @out.write(PrettyPrinter.format_ast(ast))
+        @out.puts if multiple && index < paths.length - 1
+      end
+      0
+    end
+
+    def format_command
+      parsed = parse_format_options
+      return 1 unless parsed
+
+      options = parsed[:options]
+      input_paths = parsed[:input_paths]
+
+      if input_paths.empty?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      paths = expand_source_paths(input_paths)
+      return 0 if print_no_source_files_if_empty(paths, input_paths)
+
+      multiple_sources = input_paths.length > 1 || input_paths.any? { |path| File.directory?(path) }
+      if multiple_sources
+        unless options[:check] || options[:write]
+          @err.puts("format on multiple sources requires --check or --write")
+          print_usage(@err)
+          return 1
+        end
+
+        return format_paths(paths, options)
+      end
+
+      path = paths.first
+
+      source = read_source_file(path)
+      format_profile = options[:profile] ? Linter::Profile.new : nil
+      start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+      result = Formatter.check_source(source, path: path, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
+      elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
+
+      rc = if options[:check]
+        announce_file_action(path, "format-check")
+        if result.changed
+          info("needs formatting #{path}")
+          1
+        else
+          info("already formatted #{path}")
+          0
+        end
+      elsif options[:write]
+        announce_file_action(path, "format-write")
+        if result.changed
+          File.write(path, result.formatted_source)
+          info("formatted #{path}")
+        else
+          info("already formatted #{path}")
+        end
+        0
+      else
+        @out.write(result.formatted_source)
+        0
+      end
+
+      print_file_profiles([{ path:, total_ms: elapsed_ms, profile: format_profile }], "format") if options[:profile]
+      rc
+    end
+
+    def format_paths(paths, options)
+      format_profiles = []
+      if options[:check]
+        needs_fmt = []
+        paths.each do |p|
+          announce_file_action(p, "format-check")
+          format_profile = options[:profile] ? Linter::Profile.new : nil
+          start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+          result = Formatter.check_source(read_source_file(p), path: p, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
+          elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
+          format_profiles << { path: p, total_ms: elapsed_ms, profile: format_profile } if options[:profile]
+          needs_fmt << p if result.changed
+        end
+        print_file_profiles(format_profiles, "format") if options[:profile]
+        if needs_fmt.empty?
+          info("all #{paths.size} file(s) already formatted")
+          return 0
+        end
+        needs_fmt.each { |p| info("needs formatting #{p}") }
+        info("#{needs_fmt.size} file(s) need formatting")
+        return 1
+      end
+
+      # --write
+      changed = 0
+      paths.each do |p|
+        announce_file_action(p, "format-write")
+        format_profile = options[:profile] ? Linter::Profile.new : nil
+        start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+        result = Formatter.check_source(read_source_file(p), path: p, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
+        elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
+        format_profiles << { path: p, total_ms: elapsed_ms, profile: format_profile } if options[:profile]
+        if result.changed
+          File.write(p, result.formatted_source)
+          info("formatted #{p}")
+          changed += 1
+        end
+      end
+      print_file_profiles(format_profiles, "format") if options[:profile]
+      info("formatted #{changed} of #{paths.size} file(s)")
+      0
+    end
+
+    def lint_command
+      resolution = { locked: false, frozen: false }
+      select = nil
+      ignore = nil
+      fix = false
+      init = false
+      ignore_generated = false
+      profile = false
+      input_paths = []
+      until @argv.empty?
+        arg = @argv.shift
+        unless arg.start_with?("--")
+          input_paths << arg
+          next
+        end
+
+        flag = arg
+        case flag
+        when "--select"
+          arg = @argv.shift
+          unless arg
+            @err.puts("--select requires a comma-separated list of rule codes")
+            return 1
+          end
+          select = arg.split(",").map(&:strip).to_set
+        when "--ignore"
+          arg = @argv.shift
+          unless arg
+            @err.puts("--ignore requires a comma-separated list of rule codes")
+            return 1
+          end
+          ignore = arg.split(",").map(&:strip).to_set
+        when "--fix"
+          fix = true
+        when "--init"
+          init = true
+        when "--locked"
+          resolution[:locked] = true
+        when "--frozen"
+          resolution[:locked] = true
+          resolution[:frozen] = true
+        when "--ignore-generated"
+          ignore_generated = true
+        when "--timings"
+          profile = true
+        when "--"
+          input_paths.concat(@argv)
+          @argv.clear
+        else
+          @err.puts("unknown lint flag: #{flag}")
+          return 1
+        end
+      end
+
+      if init
+        if input_paths.empty? && !select && !ignore && !fix && !resolution[:locked] && !resolution[:frozen]
+          return init_lint_config
+        end
+
+        @err.puts("--init does not accept source paths or lint options")
+        return 1
+      end
+
+      if input_paths.empty?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      paths = input_paths.flat_map do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, "**/*.mt")).sort
+        else
+          [path]
+        end
+      end.uniq
+
+      if paths.empty?
+        label = input_paths.length == 1 ? input_paths.first : input_paths.join(", ")
+        @out.puts("no .mt files found in #{label}")
+        return 0
+      end
+
+      ensure_current_lockfiles!(paths) if resolution[:frozen]
+
+      if fix
+        lint_profiles = []
+        paths.each do |p|
+          announce_file_action(p, "lint-fix")
+          source = read_source_file(p)
+          if ignore_generated && generated_source?(source)
+            @out.puts("ignored generated #{p}")
+            next
+          end
+
+          facts = lint_sema_facts_for(source, p, locked: resolution[:locked])
+          prof = profile ? Linter::Profile.new : nil
+          start_time = profile ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+
+          fixed = Linter.fix_source(
+            source,
+            path: p,
+            sema_facts: facts,
+            select:,
+            ignore:,
+            profile: prof,
+          )
+          total_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
+          lint_profiles << { path: p, profile: prof, mode: :pre_fix_scan, total_ms: } if prof
+          if fixed != source
+            File.write(p, fixed)
+            @out.puts("fixed #{p}")
+          end
+        end
+        print_lint_rule_profiles(lint_profiles) if profile
+        print_lint_file_profiles(lint_profiles) if profile
+        return 0
+      end
+
+      lint_profiles = []
+      all_warnings = paths.flat_map do |p|
+        announce_file_action(p, "lint")
+        source = read_source_file(p)
+        next [] if ignore_generated && generated_source?(source)
+
+        facts = lint_sema_facts_for(source, p, locked: resolution[:locked])
+        prof = profile ? Linter::Profile.new : nil
+        start_time = profile ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+        warnings = Linter.lint_source(source, path: p, select:, ignore:, sema_facts: facts, profile: prof)
+        total_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
+        lint_profiles << { path: p, profile: prof, mode: :lint, total_ms: } if prof
+        warnings
+      end
+
+      if all_warnings.empty?
+        if input_paths.length == 1
+          info("clean #{input_paths.first}")
+        else
+          info("clean #{paths.size} file(s)")
+        end
+        print_lint_file_profiles(lint_profiles) if profile
+        return 0
+      end
+
+      all_warnings.each do |warning|
+        @out.puts("#{warning.path}:#{warning.line}: #{warning.code}: #{warning.message}")
+      end
+
+      print_lint_rule_profiles(lint_profiles) if profile
+      print_lint_file_profiles(lint_profiles) if profile
+
+      file_count = all_warnings.map(&:path).uniq.size
+      noun = all_warnings.size == 1 ? "warning" : "warnings"
+      files_str = file_count == 1 ? "1 file" : "#{file_count} files"
+      @out.puts("Found #{all_warnings.size} #{noun} in #{files_str}.")
+      1
+    end
+
+    def init_lint_config
+      path = File.join(Dir.pwd, Linter::DEFAULT_CONFIG_FILE_NAME)
+      if File.exist?(path)
+        @err.puts("lint config already exists at #{path}")
+        return 1
+      end
+
+      File.write(path, Linter.default_config_source)
+      info("created #{path}")
+      0
+    end
+
+    def print_lint_rule_profiles(lint_profiles, limit: 12)
+      lint_profiles.each do |entry|
+        profile = entry[:profile]
+        next unless profile
+
+        rows = profile.rule_breakdown(limit:, min_ms: 0.0)
+        rule_total = profile.total_time_ms(prefix: "rule.")
+        overall_total = profile.total_time_ms
+        mode_label = entry[:mode] == :pre_fix_scan ? "pre-fix scan" : "lint scan"
+        @out.puts("lint profile #{entry[:path]} (#{mode_label}): rules=#{format('%.1f', rule_total)}ms total=#{format('%.1f', overall_total)}ms")
+
+        if rows.empty?
+          @out.puts("  no rule timing data captured")
+          next
+        end
+
+        rows.each do |row|
+          share = rule_total.positive? ? ((row[:total_ms] / rule_total) * 100.0) : 0.0
+          @out.puts(
+            "  #{row[:code]}: #{row[:count]}x total=#{format('%.1f', row[:total_ms])}ms avg=#{format('%.2f', row[:avg_ms])}ms share=#{format('%.1f', share)}%"
+          )
+        end
+
+        non_rule_rows = profile.timings_ms
+          .filter_map do |name, total_ms|
+            next if name.start_with?("rule.")
+            next if total_ms < 1.0
+
+            [name, total_ms]
+          end
+          .sort_by { |_name, total_ms| -total_ms }
+          .first(5)
+          .map do |name, total_ms|
+            count = profile.counts[name]
+            "#{name}:#{count}x/#{format('%.1f', total_ms)}ms"
+          end
+
+        @out.puts("  non-rule hot phases: #{non_rule_rows.join(', ')}") unless non_rule_rows.empty?
+      end
+    end
+
+    def print_lint_file_profiles(lint_profiles)
+      file_entries = lint_profiles.filter_map do |entry|
+        total = entry[:total_ms]
+        next unless total
+
+        phases = entry[:profile]&.timings_ms&.reject { |name, _| name.start_with?("rule.") }&.sort_by { |_, ms| -ms }
+        { path: entry[:path], total_ms: total, phases: }
+      end
+      return if file_entries.empty?
+
+      sorted = file_entries.sort_by { |e| -e[:total_ms] }
+      @out.puts
+      @out.puts("Profile (lint): #{sorted.size} file(s)")
+      sorted.each do |entry|
+        phase_str = entry[:phases]&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 1.0 }&.join(", ")
+        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
+        @out.puts("  #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
+      end
+      total = sorted.sum { |e| e[:total_ms] }
+      @out.puts("Total: #{format('%.1f', total)}ms")
+    end
+
+    def print_file_profiles(file_profiles, label)
+      sorted = file_profiles.sort_by { |fp| -fp[:total_ms] }
+      return if sorted.empty?
+
+      @out.puts
+      if sorted.size == 1
+        entry = sorted.first
+        phases = entry[:profile]&.timings_ms&.sort_by { |_, ms| -ms }
+        phase_str = phases&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 0.1 }&.join(", ")
+        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
+        @out.puts("#{label} profile #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
+        return
+      end
+
+      @out.puts("Profile (#{label}): #{sorted.size} file(s)")
+      sorted.each do |entry|
+        phases = entry[:profile]&.timings_ms&.sort_by { |_, ms| -ms }
+        phase_str = phases&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 1.0 }&.join(", ")
+        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
+        @out.puts("  #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
+      end
+      total = sorted.sum { |fp| fp[:total_ms] }
+      @out.puts("Total: #{format('%.1f', total)}ms")
+    end
+
+    def check_command
+      args = @argv.dup
+      @argv = []
+      until args.empty?
+        arg = args.shift
+        @argv << arg
+      end
+
+      unless @argv.any?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      resolution = extract_resolution_flags!
+      input_paths = @argv.dup
+      return 1 unless ensure_known_source_operands!("check", input_paths)
+
+      paths = expand_source_paths(input_paths)
+      return 0 if print_no_source_files_if_empty(paths, input_paths)
+
+      ensure_current_lockfiles!(paths) if resolution[:frozen]
+
+      all_diagnostics = []
+      paths.each do |path|
+        diagnostics, module_name, closure_errors = check_single_reporting_all(path, locked: resolution[:locked])
+        closure_errors = [] if paths.length > 1
+        diagnostics = sort_by_location(diagnostics)
+
+        if diagnostics.any? || closure_errors.any?
+          source = read_source_file(path)
+          diagnostics.each do |d|
+            @err.puts(ErrorFormatter.format(d, source:, color: error_color?(@err)))
+          end
+          closure_errors.each do |d|
+            @err.puts(ErrorFormatter.format(d, color: error_color?(@err)))
+          end
+          all_diagnostics.concat(diagnostics)
+          all_diagnostics.concat(closure_errors)
+        elsif module_name
+          info("checked #{path} as #{module_name}")
+        end
+      end
+
+      return 0 if all_diagnostics.empty?
+
+      error_count = all_diagnostics.count { |d| !d.respond_to?(:severity) || d.severity == :error }
+      warning_count = all_diagnostics.count { |d| d.respond_to?(:severity) && d.severity == :warning }
+      info_count = all_diagnostics.count { |d| d.respond_to?(:severity) && (d.severity == :info || d.severity == :hint) }
+
+      @err.puts
+      parts = []
+      parts << "#{error_count} #{error_count == 1 ? 'error' : 'errors'}" if error_count > 0
+      parts << "#{warning_count} #{warning_count == 1 ? 'warning' : 'warnings'}" if warning_count > 0
+      parts << "#{info_count} #{info_count == 1 ? 'note' : 'notes'}" if info_count > 0
+      body = parts.join("; ")
+      if error_count > 0
+        @err.puts("error: could not check due to #{body}")
+      elsif warning_count > 0
+        @err.puts("warning: #{body}")
+      end
+      final_error_count = error_count + (resolution[:warnings_as_errors] ? warning_count : 0)
+      final_error_count > 0 ? 1 : 0
+    end
+
+    def check_single_reporting_all(path, locked: false)
+      loader = make_module_loader(path, locked:, platform: ModuleLoader.default_host_platform)
+      resolved_path = File.expand_path(path)
+      ast = loader.load_file(resolved_path)
+      module_name = ast.module_name.to_s
+
+      import_result = loader.send(:imported_modules_for_ast_collecting_errors, ast, importer_path: resolved_path)
+      errors = import_result.errors.dup
+
+      analysis = nil
+      begin
+        result = SemanticAnalyzer.check_collecting_errors(ast, imported_modules: import_result.modules, path: resolved_path)
+        errors.concat(result[:errors])
+        analysis = result[:analysis]
+      rescue SemanticError => e
+        errors << e
+      end
+
+      if analysis && errors.empty?
+        source = read_source_file(path)
+        warnings = Linter.lint_source(source, path: resolved_path, sema_facts: analysis, lint_tier: :full)
+        errors.concat(warnings)
+      end
+
+      closure_errors = loader.collecting_path_errors.values.flatten.compact
+      [errors, module_name, closure_errors]
+    rescue ModuleLoadError, PackageLockError, SemanticError => e
+      [[e], nil, []]
+    end
+
+    def sort_by_location(errors)
+      errors.sort_by do |e|
+        actual = e.respond_to?(:error) ? e.error : e
+        line = actual.respond_to?(:line) ? actual.line.to_i : 0
+        column = actual.respond_to?(:column) ? actual.column.to_i : 0
+        [line, column]
+      end
+    end
+
+    def lower_command
+      args = @argv.dup
+      @argv = []
+      until args.empty?
+        arg = args.shift
+        @argv << arg
+      end
+
+      unless @argv.any?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      resolution = extract_resolution_flags!
+      input_paths = @argv.dup
+      return 1 unless ensure_known_source_operands!("lower", input_paths)
+
+      paths = expand_source_paths(input_paths)
+      return 0 if print_no_source_files_if_empty(paths, input_paths)
+
+      ensure_current_lockfiles!(paths) if resolution[:frozen]
+
+      multiple = paths.length > 1
+      paths.each_with_index do |path, index|
+        program = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).check_program(path)
+        if multiple
+          @out.puts("# --- #{path} ---")
+        end
+        @out.write(PrettyPrinter.format_ir(Lowering.lower(program)))
+        @out.puts if multiple && index < paths.length - 1
+      end
+      0
+    end
+
+    def emit_c_command
+      args = @argv.dup
+      @argv = []
+      until args.empty?
+        arg = args.shift
+        @argv << arg
+      end
+
+      unless @argv.any?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      resolution = extract_resolution_flags!
+      input_paths = @argv.dup
+      return 1 unless ensure_known_source_operands!("emit-c", input_paths)
+
+      program_paths = input_paths.map { |p| resolve_program_path(p) }
+      return 1 if program_paths.include?(nil)
+
+      ensure_current_lockfiles!(input_paths) if resolution[:frozen]
+
+      multiple = program_paths.length > 1
+      program_paths.each_with_index do |path, index|
+        program = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).check_program(path)
+        if multiple
+          @out.puts("/* --- #{path} --- */")
+        end
+        @out.write(CBackend.generate_c(Lowering.lower(program), emit_line_directives: false))
+        @out.puts if multiple && index < program_paths.length - 1
+      end
+      0
+    end
+
+    def resolve_program_path(path)
+      return path unless File.directory?(path)
+
+      manifest_path = File.join(path, "package.toml")
+      unless File.file?(manifest_path)
+        @err.puts("no package.toml found in #{path}")
+        return nil
+      end
+
+      manifest = PackageManifest.load(path)
+      entry_path = manifest.source_path
+      unless entry_path && File.file?(entry_path)
+        @err.puts("no build entry found for #{path}")
+        return nil
+      end
+
+      entry_path
+    rescue PackageManifestError => e
+      @err.puts("failed to load package manifest for #{path}: #{e.message}")
+      nil
+    end
+
+    def build_command
+      path, options = extract_path_and_options(allow_clean: true)
+      return 1 unless path
+
+      if options.delete(:clean)
+        cleaned_path = Build.clean(path, output_path: options[:output_path], profile: options[:profile], platform: options[:platform], bundle: options[:bundle], archive: options[:archive])
+        info("cleaned #{cleaned_path}")
+        return 0
+      end
+
+      frozen = options.delete(:frozen)
+      ensure_current_lockfile!(path) if frozen
+      locked = options.delete(:locked)
+      bundle = options[:bundle]
+      package_graph = package_graph_for(path, locked:)
+      result = Build.build(path, module_roots: module_roots_for(path, locked:), package_graph:, frontend: @build_frontend, **options.except(:timings))
+      if bundle
+        info("built #{path} -> #{File.dirname(result.output_path)}")
+        info("entry executable #{result.output_path}")
+        info("  [cached]") if result.cached
+        info("archive #{result.archive_path}") if result.archive_path
+      elsif result.cached
+        info("built #{path} -> #{result.output_path}  [cached]")
+      else
+        info("built #{path} -> #{result.output_path}")
+      end
+      info("saved C to #{result.c_path}") if result.c_path
+      0
+    end
+
+    def test_command
+      limits = extract_test_limit_flags!
+      return 1 unless limits
+
+      @test_timeout_seconds, @test_memory_bytes, @test_jobs, @test_sanitize, @test_filter, @test_format = limits
+
+      path, options = extract_path_and_options
+      return 1 unless path
+
+      frozen = options.delete(:frozen)
+      ensure_current_lockfile!(path) if frozen
+      locked = options.delete(:locked)
+
+      return dispatch_test_run(path, options:, locked:) if @test_format == :human
+
+      buffer = StringIO.new
+      real_out = @out
+      real_err = @err
+      @out = buffer
+      @err = buffer
+      begin
+        exit_code = dispatch_test_run(path, options:, locked:)
+      ensure
+        @out = real_out
+        @err = real_err
+      end
+
+      emit_machine_results(parse_test_output(buffer.string), @test_format, real_out)
+      exit_code
+    end
+
+    def dispatch_test_run(path, options:, locked:)
+      if File.directory?(path)
+        run_test_directory(path, options:, locked:)
+      elsif File.file?(path)
+        if compile_fail_fixture?(File.read(path))
+          run_compile_fail_test(path) ? 0 : 1
+        else
+          run_test_file(path, options:, locked:)
+        end
+      else
+        @err.puts("mtc test: not a file or directory: #{path}")
+        1
+      end
+    end
+
+    def extract_test_limit_flags!
+      timeout_seconds = TEST_RUN_TIMEOUT_SECONDS
+      memory_bytes = TEST_RUN_MEMORY_LIMIT_BYTES
+      jobs = 1
+      sanitize = false
+      filter = nil
+      format = :human
+      remaining = []
+      until @argv.empty?
+        arg = @argv.shift
+        case arg
+        when "--timeout"
+          value = @argv.shift
+          seconds = value && Integer(value, exception: false)
+          unless seconds&.positive?
+            @err.puts("--timeout requires a positive integer (seconds)")
+            return nil
+          end
+          timeout_seconds = seconds
+        when "--mem"
+          value = @argv.shift
+          megabytes = value && Integer(value, exception: false)
+          unless megabytes&.positive?
+            @err.puts("--mem requires a positive integer (megabytes)")
+            return nil
+          end
+          memory_bytes = megabytes * 1024 * 1024
+        when "--jobs"
+          value = @argv.shift
+          count = value && Integer(value, exception: false)
+          unless count&.positive?
+            @err.puts("--jobs requires a positive integer")
+            return nil
+          end
+          jobs = count
+        when "--sanitize"
+          sanitize = true
+        when "-n", "--name"
+          value = @argv.shift
+          unless value
+            @err.puts("-n requires a name substring")
+            return nil
+          end
+          filter = value
+        when "--format"
+          value = @argv.shift
+          unless %w[human tap junit].include?(value)
+            @err.puts("--format must be human, tap, or junit")
+            return nil
+          end
+          format = value.to_sym
+        when "--"
+          remaining << arg
+          remaining.concat(@argv)
+          @argv.clear
+        else
+          remaining << arg
+        end
+      end
+      @argv.replace(remaining)
+      [timeout_seconds, memory_bytes, jobs, sanitize, filter, format]
+    end
+
+    TestResult = Data.define(:name, :status, :detail)
+
+    def parse_test_output(text)
+      results = []
+      current_file = nil
+      text.each_line do |raw|
+        line = raw.chomp
+        case line
+        when /\A# (.+)\z/
+          current_file = ::Regexp.last_match(1)
+        when /\Aok   - (.+)\z/
+          results << TestResult.new(name: ::Regexp.last_match(1), status: :pass, detail: nil)
+        when /\Askip - (.+?)(?:: (.*))?\z/
+          results << TestResult.new(name: ::Regexp.last_match(1), status: :skip, detail: ::Regexp.last_match(2))
+        when /\AFAIL - (.+?)(?:: (.*))?\z/
+          results << TestResult.new(name: ::Regexp.last_match(1), status: :fail, detail: ::Regexp.last_match(2))
+        when /\AFAILED - (.+?) \(build error\)\z/
+          results << TestResult.new(name: "#{::Regexp.last_match(1)} (build error)", status: :fail, detail: "build error")
+        when /\Atest run (?:timed out|crashed)/, /\ASUMMARY: \w+Sanitizer/
+          results << TestResult.new(name: "#{current_file || 'test'} (#{line})", status: :fail, detail: line)
+        end
+      end
+      results
+    end
+
+    def emit_machine_results(results, format, out)
+      case format
+      when :tap then emit_tap(results, out)
+      when :junit then emit_junit(results, out)
+      end
+    end
+
+    def emit_tap(results, out)
+      out.puts("TAP version 13")
+      out.puts("1..#{results.length}")
+      results.each_with_index do |result, index|
+        number = index + 1
+        case result.status
+        when :pass
+          out.puts("ok #{number} - #{result.name}")
+        when :skip
+          out.puts("ok #{number} - #{result.name} # SKIP#{result.detail ? " #{result.detail}" : ''}")
+        when :fail
+          out.puts("not ok #{number} - #{result.name}")
+          next unless result.detail
+
+          out.puts("  ---")
+          out.puts("  message: #{result.detail}")
+          out.puts("  ...")
+        end
+      end
+    end
+
+    def emit_junit(results, out)
+      failures = results.count { |result| result.status == :fail }
+      skipped = results.count { |result| result.status == :skip }
+      out.puts(%(<?xml version="1.0" encoding="UTF-8"?>))
+      out.puts(%(<testsuites tests="#{results.length}" failures="#{failures}" skipped="#{skipped}">))
+      out.puts(%(  <testsuite name="mtc test" tests="#{results.length}" failures="#{failures}" skipped="#{skipped}">))
+      results.each do |result|
+        name = xml_escape(result.name)
+        case result.status
+        when :pass
+          out.puts(%(    <testcase name="#{name}"/>))
+        when :skip
+          out.puts(%(    <testcase name="#{name}"><skipped/></testcase>))
+        when :fail
+          out.puts(%(    <testcase name="#{name}"><failure message="#{xml_escape(result.detail || 'failed')}"/></testcase>))
+        end
+      end
+      out.puts("  </testsuite>")
+      out.puts("</testsuites>")
+    end
+
+    def xml_escape(value)
+      value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+    end
+
+    def run_test_directory(directory, options:, locked:)
+      test_files = discover_test_files(directory)
+      if test_files.empty?
+        if @test_filter
+          @out.puts("no tests matched -n '#{@test_filter}' under #{directory}")
+        else
+          @out.puts("no @[test] functions or # expect-error: fixtures found under #{directory}")
+        end
+        return 0
+      end
+
+      jobs = @test_jobs || 1
+      return run_test_files_parallel(test_files, jobs:, options:, locked:) if jobs > 1 && Process.respond_to?(:fork)
+
+      failed = 0
+      test_files.each do |file, kind|
+        @out.puts("# #{file}")
+        @out.flush if @out.respond_to?(:flush)
+        failed += 1 unless run_classified_file(file, kind, options:, locked:).zero?
+      end
+
+      @out.puts("")
+      @out.puts("#{test_files.length} test file(s), #{failed} failed")
+      failed.zero? ? 0 : 1
+    end
+
+    def run_classified_file(file, kind, options:, locked:)
+      if kind == :compile_fail
+        run_compile_fail_test(file) ? 0 : 1
+      else
+        run_test_file_guarded(file, options:, locked:)
+      end
+    end
+
+    def run_compile_fail_test(path)
+      source = File.read(path)
+      expectations = extract_expect_error_directives(source)
+      messages = compile_fail_diagnostics(path)
+
+      if messages.empty?
+        @out.puts("FAIL - #{path} (compile-fail): expected a compile error, but it compiled cleanly")
+        @out.flush if @out.respond_to?(:flush)
+        return false
+      end
+
+      unmatched = expectations.find { |expected| messages.none? { |message| message.include?(expected) } }
+      if unmatched
+        @out.puts("FAIL - #{path} (compile-fail): no diagnostic matched #{unmatched.inspect}")
+        @out.flush if @out.respond_to?(:flush)
+        return false
+      end
+
+      @out.puts("ok   - #{path} (compile-fail)")
+      @out.flush if @out.respond_to?(:flush)
+      true
+    end
+
+    def extract_expect_error_directives(source)
+      source.each_line.filter_map do |line|
+        match = line.match(/^\s*#\s*expect-error:\s*(.+?)\s*$/)
+        match && match[1]
+      end
+    end
+
+    def compile_fail_diagnostics(path)
+      errors, = check_single_reporting_all(path, locked: false)
+      errors
+        .select { |diagnostic| !diagnostic.respond_to?(:severity) || diagnostic.severity == :error }
+        .map { |diagnostic| ErrorFormatter.format(diagnostic, color: false) }
+    rescue StandardError => e
+      raise unless handled_cli_error?(e)
+
+      [ErrorFormatter.format(e, color: false)]
+    end
+
+    def run_test_file_guarded(file, options:, locked:)
+      run_test_file(file, options:, locked:)
+    rescue StandardError => e
+      raise unless handled_cli_error?(e)
+
+      @err.puts("FAILED - #{file} (build error)")
+      @err.puts(ErrorFormatter.format(e, color: error_color?(@err)))
+      1
+    end
+
+    def run_test_files_parallel(test_files, jobs:, options:, locked:)
+      results = Array.new(test_files.length)
+      result_paths = {}
+      active = {}
+      cursor = 0
+
+      while cursor < test_files.length || !active.empty?
+        while active.size < jobs && cursor < test_files.length
+          index = cursor
+          cursor += 1
+          result_path = File.join(Dir.tmpdir, "mttest_result_#{Process.pid}_#{index}")
+          result_paths[index] = result_path
+          pid = fork do
+            captured = StringIO.new
+            @out = captured
+            @err = captured
+            file, kind = test_files[index]
+            code = run_classified_file(file, kind, options:, locked:)
+            File.binwrite(result_path, [code].pack("N") + captured.string)
+            exit!(0)
+          end
+          active[pid] = index
+        end
+
+        finished_pid, = Process.wait2
+        index = active.delete(finished_pid)
+        next unless index
+
+        path = result_paths[index]
+        data = begin
+          File.binread(path)
+        rescue StandardError
+          (+"").b
+        end
+        File.delete(path) if File.exist?(path)
+        results[index] =
+          if data.bytesize >= 4
+            [data[0, 4].unpack1("N"), data.byteslice(4..).force_encoding(Encoding::UTF_8)]
+          else
+            [1, +""]
+          end
+      end
+
+      failed = 0
+      test_files.each_with_index do |(file, _kind), index|
+        code, output = results[index]
+        @out.puts("# #{file}")
+        @out.write(output.to_s)
+        failed += 1 unless code&.zero?
+      end
+      @out.flush if @out.respond_to?(:flush)
+      @out.puts("")
+      @out.puts("#{test_files.length} test file(s), #{failed} failed")
+      failed.zero? ? 0 : 1
+    end
+
+    def discover_test_files(directory)
+      Dir.glob(File.join(directory, "**", "*.mt")).sort.filter_map do |file|
+        next if File.basename(file).start_with?("__mt_test_runner_")
+
+        kind = classify_test_file(file)
+        kind && [file, kind]
+      end
+    end
+
+    def classify_test_file(file)
+      source = File.read(file)
+      if compile_fail_fixture?(source)
+        return nil if @test_filter && !File.basename(file, ".mt").include?(@test_filter)
+
+        return :compile_fail
+      end
+
+      ast = begin
+        MilkTea::Parser.parse(source, path: file)
+      rescue ParseError
+        return nil
+      end
+      has_match = ast.declarations.any? do |decl|
+        decl.is_a?(AST::FunctionDef) && test_attribute?(decl) && matches_filter?(decl.name)
+      end
+      has_match ? :test : nil
+    end
+
+    def compile_fail_fixture?(source)
+      source.match?(/^\s*#\s*expect-error:/)
+    end
+
+    def test_attribute?(decl)
+      decl.attributes.any? { |attribute| attribute.name.parts == ["test"] }
+    end
+
+    def matches_filter?(name)
+      @test_filter.nil? || name.include?(@test_filter)
+    end
+
+    def run_test_file(path, options:, locked:)
+      source = File.read(path)
+      ast = MilkTea::Parser.parse(source, path:)
+
+      if ast.declarations.any? { |decl| decl.is_a?(AST::FunctionDef) && decl.name == "main" }
+        @err.puts("a test file must not define 'main': #{path}")
+        return 1
+      end
+
+      tests = ast.declarations.select { |decl| decl.is_a?(AST::FunctionDef) && test_attribute?(decl) }
+
+      if tests.empty?
+        @out.puts("no @[test] functions found in #{path}")
+        return 0
+      end
+
+      tests = tests.select { |test| matches_filter?(test.name) }
+      return 0 if tests.empty?
+
+      invalid = tests.find { |test| !test.params.empty? }
+      if invalid
+        @err.puts("@[test] function '#{invalid.name}' must take no parameters")
+        return 1
+      end
+
+      testing_import = ast.imports.find { |import| import.path.parts == %w[std testing] }
+      unless testing_import
+        @err.puts("a test file must import std.testing: #{path}")
+        return 1
+      end
+      testing_alias = testing_import.alias_name || testing_import.path.parts.last
+
+      death_tests, normal_tests = tests.partition { |test| expect_fatal_attribute?(test) }
+
+      exit_code = 0
+
+      unless normal_tests.empty?
+        runner_source = source.dup
+        runner_source << "\n\n" << test_runner_main(testing_alias, normal_tests.map(&:name))
+        exit_code = run_synthesized_tests(path, runner_source, options:, locked:)
+      end
+
+      death_tests.each do |death_test|
+        exit_code = 1 unless run_death_test(path, source, death_test.name, options:, locked:)
+      end
+
+      exit_code
+    end
+
+    def expect_fatal_attribute?(decl)
+      decl.attributes.any? { |attribute| attribute.name.parts == ["expect_fatal"] }
+    end
+
+    def run_death_test(source_path, source, test_name, options:, locked:)
+      runner_source = source.dup
+      runner_source << "\n\n" << death_test_runner_main(test_name)
+      classification = with_synthesized_binary(source_path, runner_source, options:, locked:) do |binary_path|
+        classify_death_test(binary_path)
+      end
+
+      passed = classification == :aborted
+      line =
+        if passed
+          "ok   - #{test_name} (expect_fatal)"
+        elsif classification == :timed_out
+          "FAIL - #{test_name} (expect_fatal): timed out"
+        else
+          "FAIL - #{test_name} (expect_fatal): expected a fatal abort, but the test returned"
+        end
+      @out.puts(line)
+      @out.flush if @out.respond_to?(:flush)
+      passed
+    end
+
+    def classify_death_test(binary_path)
+      _output, status, timed_out = spawn_sandboxed(binary_path)
+      return :timed_out if timed_out
+      return :returned if status&.exited? && status.exitstatus&.zero?
+
+      :aborted
+    end
+
+    def death_test_runner_main(test_name)
+      [
+        "function main() -> int:",
+        "    match #{test_name}():",
+        "        Result.success:",
+        "            return 0",
+        "        Result.failure:",
+        "            return 0",
+      ].join("\n") + "\n"
+    end
+
+    def test_runner_main(testing_alias, test_names)
+      lines = ["function main() -> int:"]
+      lines << "    var __mt_test_stats = #{testing_alias}.Stats.create()"
+      test_names.each do |name|
+        lines << "    __mt_test_stats = #{testing_alias}.record(__mt_test_stats, #{name.inspect}, #{name}())"
+      end
+      lines << "    return #{testing_alias}.summarize(__mt_test_stats)"
+      lines.join("\n") + "\n"
+    end
+
+    def run_synthesized_tests(source_path, runner_source, options:, locked:)
+      with_synthesized_binary(source_path, runner_source, options:, locked:) do |binary_path|
+        run_test_binary(binary_path)
+      end
+    end
+
+    def with_synthesized_binary(source_path, runner_source, options:, locked:)
+      directory = File.dirname(File.expand_path(source_path))
+      runner_path = File.join(directory, "__mt_test_runner_#{Process.pid}.mt")
+      binary_path = File.join(Dir.tmpdir, "__mt_test_runner_#{Process.pid}")
+
+      File.write(runner_path, runner_source)
+      begin
+        build_opts = options.except(:timings, :output_path, :bundle, :archive)
+        build_opts[:debug_guards] = false
+        Build.build(
+          runner_path,
+          output_path: binary_path,
+          module_roots: module_roots_for(source_path, locked:),
+          package_graph: package_graph_for(source_path, locked:),
+          frontend: @build_frontend,
+          sanitize: @test_sanitize,
+          **build_opts,
+        )
+        yield binary_path
+      ensure
+        File.delete(runner_path) if File.exist?(runner_path)
+        File.delete(binary_path) if File.exist?(binary_path)
+      end
+    end
+
+    TEST_RUN_TIMEOUT_SECONDS = 30
+    TEST_RUN_MEMORY_LIMIT_BYTES = 1024 * 1024 * 1024
+
+    def run_test_binary(binary_path)
+      output, status, timed_out = spawn_sandboxed(binary_path)
+      @out.write(output)
+      @out.flush if @out.respond_to?(:flush)
+
+      if timed_out
+        @err.puts("test run timed out after #{@test_timeout_seconds || TEST_RUN_TIMEOUT_SECONDS}s")
+        return 1
+      end
+      if status&.signaled?
+        @err.puts("test run crashed (signal #{status.termsig})")
+        return 1
+      end
+
+      status&.exitstatus || 1
+    end
+
+    def spawn_sandboxed(binary_path)
+      timeout_seconds = @test_timeout_seconds || TEST_RUN_TIMEOUT_SECONDS
+      memory_bytes = @test_memory_bytes || TEST_RUN_MEMORY_LIMIT_BYTES
+      reader, writer = IO.pipe
+      spawn_options = { out: writer, err: writer, pgroup: true }
+      spawn_options[:rlimit_as] = memory_bytes unless @test_sanitize
+      pid = Process.spawn(binary_path, **spawn_options)
+      writer.close
+
+      status = nil
+      timed_out = false
+      begin
+        Timeout.timeout(timeout_seconds) { _, status = Process.wait2(pid) }
+      rescue Timeout::Error
+        timed_out = true
+        begin
+          Process.kill("-KILL", Process.getpgid(pid))
+          Process.wait(pid)
+        rescue StandardError
+          nil
+        end
+      end
+
+      output = reader.read
+      reader.close
+      [output, status, timed_out]
+    end
+
+    def run_command
+      path, options = extract_path_and_options
+      return 1 unless path
+
+      run_and_print_result(path, options)
+    end
+
+    def app_command
+      options = parse_build_options
+      return 1 unless options
+
+      module_name = @argv.shift
+      unless module_name
+        @err.puts("missing module name")
+        print_usage(@err)
+        return 1
+      end
+
+      path = resolve_app_module(module_name)
+      unless path
+        @err.puts("run-module module not found: #{module_name}")
+        return 1
+      end
+
+      frozen = options.delete(:frozen)
+      ensure_current_lockfile!(path) if frozen
+
+      run_and_print_result(path, options)
+    end
+
+    def extract_path_and_options(allow_clean: false)
+      options = parse_build_options(allow_clean:)
+      return nil unless options
+
+      path = @argv.shift
+      unless path
+        if File.file?(File.join(Dir.pwd, "package.toml"))
+          path = Dir.pwd
+        else
+          @err.puts("missing source file path")
+          print_usage(@err)
+          return nil
+        end
+      end
+
+      [path, options]
+    end
+
+    def run_and_print_result(path, options)
+      frozen = options.delete(:frozen)
+      ensure_current_lockfile!(path) if frozen
+      locked = options.delete(:locked)
+      package_graph = package_graph_for(path, locked:)
+      preview_notice_emitted = false
+      preview_started = lambda do |message|
+        preview_notice_emitted = true
+        @out.write(message)
+        @out.flush if @out.respond_to?(:flush)
+      end
+
+      result = Run.run(
+        path,
+        module_roots: module_roots_for(path, locked:),
+        package_graph:,
+        frontend: @build_frontend,
+        preview_started:,
+        argv: @argv.dup,
+        **options.except(:timings)
+      )
+      unless @out.equal?($stdout) || preview_notice_emitted
+        @out.write(result.stdout)
+      end
+      @out.flush if @out.respond_to?(:flush)
+      @err.write(result.stderr) unless @err.equal?($stderr)
+      info("[cached]") if result.cached
+      result.exit_status
+    end
+
+    def resolve_app_module(name)
+      relative = name.tr(".", "/").sub(%r{^/}, "") + ".mt"
+
+      module_roots_for(Dir.pwd).each do |root|
+        candidate = File.join(root, "std", relative)
+        return File.expand_path(candidate) if File.file?(candidate)
+
+        candidate = File.join(root, relative)
+        return File.expand_path(candidate) if File.file?(candidate)
+      end
+
+      nil
+    end
+
+    def new_command
+      name = @argv.shift
+      unless name
+        @err.puts("missing project name")
+        print_usage(@err)
+        return 1
+      end
+
+      if @argv.any?
+        @err.puts("unknown new option #{@argv.first}")
+        print_usage(@err)
+        return 1
+      end
+
+      result = ProjectScaffold.create(name)
+      info("created #{result.root_path}")
+      0
+    end
+
+    def deps_command
+      PackageManagerCLI.start(
+        @argv,
+        out: @out,
+        err: @err,
+        help_printer: method(:print_deps_help),
+        services: package_services,
+      )
+    end
+
+    def docs_command
+      port = nil
+      open_flag = false
+
+      while (arg = @argv.first)
+        case arg
+        when "--port", "-p"
+          @argv.shift
+          port = @argv.shift.to_i
+          port = nil if port <= 0 || port > 65535
+        when "--open", "-o"
+          open_flag = true
+          @argv.shift
+        else
+          break
+        end
+      end
+
+      port = resolve_docs_port(port)
+
+      DocsApp.set :port, port
+      DocsApp.set :bind, "127.0.0.1"
+      DocsApp.set :environment, :production
+      DocsApp.set :server, :puma
+
+      url = "http://127.0.0.1:#{port}/"
+
+      @out.puts("Serving Milk Tea docs at #{url}")
+      @out.puts("Press Ctrl+C to stop.")
+
+      if open_flag
+        open_browser(url)
+      end
+
+      DocsApp.run!
+      0
+    rescue Interrupt
+      0
+    end
+
+    def resolve_docs_port(preferred)
+      return preferred if preferred
+
+      server = TCPServer.new("127.0.0.1", 0)
+      port = server.addr[1]
+      server.close
+      port
+    rescue StandardError
+      4567
+    end
+
+    def snapshot_command
+      input_path = nil
+      theme_path = nil
+      output_path = nil
+
+      until @argv.empty?
+        arg = @argv.first
+        case arg
+        when "--theme", "-t"
+          @argv.shift
+          theme_path = @argv.shift
+          unless theme_path
+            @err.puts("snapshot: missing value for --theme")
+            return 1
+          end
+        when "--output", "-o"
+          @argv.shift
+          output_path = @argv.shift
+          unless output_path
+            @err.puts("snapshot: missing value for --output")
+            return 1
+          end
+        else
+          if arg.start_with?("-")
+            @err.puts("snapshot: unknown option #{arg}")
+            return 1
+          end
+          unless input_path
+            input_path = @argv.shift
+          else
+            @err.puts("snapshot: unexpected argument #{@argv.shift}")
+            return 1
+          end
+        end
+      end
+
+      unless input_path
+        @err.puts("snapshot: missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      unless File.file?(input_path)
+        @err.puts("snapshot: source file not found: #{input_path}")
+        return 1
+      end
+
+      input_path = File.expand_path(input_path)
+      theme_path = File.expand_path(theme_path) if theme_path
+      output_path = File.expand_path(output_path) if output_path
+
+      if theme_path && !File.file?(theme_path)
+        @err.puts("snapshot: theme file not found: #{theme_path}")
+        return 1
+      end
+
+      snapshot_script = MilkTea.root.join("bindings/vscode/scripts/snapshot.js").to_s
+      unless File.file?(snapshot_script)
+        @err.puts("snapshot: internal script not found at #{snapshot_script}")
+        return 1
+      end
+
+      args = ["node", snapshot_script, input_path]
+      args.push("-t", theme_path) if theme_path
+      args.push("-o", output_path) if output_path
+
+      semantic_result = nil
+      begin
+        semantic_result = MilkTea::LSP::Server.semantic_tokens_for_path(input_path)
+      rescue => e
+        @err.puts("snapshot: semantic analysis skipped: #{e.message}")
+      end
+
+      if semantic_result && semantic_result[:entries] && !semantic_result[:entries].empty?
+        source = File.read(input_path)
+        lines = source.split("\n", -1)
+        semantic_result[:entries].each do |entry|
+          byte_start = entry[:startChar]
+          byte_len = entry[:length]
+          line_text = lines[entry[:line]]
+          unless line_text && byte_start && byte_len
+            entry[:startChar] = 0
+            entry[:length] = 0
+            next
+          end
+          char_start = line_text.byteslice(0, byte_start).length
+          char_length = line_text.byteslice(byte_start, byte_len).length
+          char_length = line_text.length - char_start if char_start + char_length > line_text.length
+          entry[:startChar] = char_start
+          entry[:length] = char_length
+        end
+
+        temp = Tempfile.new(["mt_semantic", ".json"])
+        temp.write(JSON.generate(semantic_result[:entries]))
+        temp.close
+        args.push("-s", temp.path)
+        system(*args)
+        temp.unlink
+      else
+        system(*args)
+      end
+      $?.success? ? 0 : 1
+    end
+
+    def lsp_command
+      log_level = nil
+
+      until @argv.empty?
+        arg = @argv.shift
+        case arg
+        when "--log-level"
+          log_level = @argv.shift&.downcase
+          unless log_level && %w[trace debug info warn error].include?(log_level)
+            @err.puts("lsp: invalid --log-level #{log_level.inspect} (expected trace, debug, info, warn, or error)")
+            return 1
+          end
+        when /\A--log-level=(.+)\z/
+          log_level = ::Regexp.last_match(1).downcase
+          unless %w[trace debug info warn error].include?(log_level)
+            @err.puts("lsp: invalid --log-level #{log_level.inspect} (expected trace, debug, info, warn, or error)")
+            return 1
+          end
+        when "--stdio"
+          # stdio is the only transport; accept the flag as a no-op
+        else
+          if arg.start_with?("-")
+            @err.puts("lsp: unknown option #{arg}")
+            return 1
+          end
+          @err.puts("lsp: unexpected argument #{arg}")
+          return 1
+        end
+      end
+
+      require "milk_tea/lsp/server" unless defined?(MilkTea::LSP::Server)
+      server = MilkTea::LSP::Server.new
+      server.run
+      0
+    end
+
+    def dap_command
+      preferred_backend_kind = "process"
+      adapter_command = nil
+
+      until @argv.empty?
+        arg = @argv.shift
+        case arg
+        when "--log-level"
+          @argv.shift
+        when /\A--log-level=(.+)\z/
+          # accept and ignore
+        when "--backend"
+          preferred_backend_kind = @argv.shift&.downcase
+        when /\A--backend=(.+)\z/
+          preferred_backend_kind = ::Regexp.last_match(1).downcase
+        when "--adapter-path"
+          adapter_path = @argv.shift
+          adapter_command = resolve_adapter_path(adapter_path)
+          return 1 unless adapter_command
+        when /\A--adapter-path=(.+)\z/
+          adapter_path = ::Regexp.last_match(1)
+          adapter_command = resolve_adapter_path(adapter_path)
+          return 1 unless adapter_command
+        else
+          if arg.start_with?("-")
+            @err.puts("dap: unknown option #{arg}")
+            return 1
+          end
+          @err.puts("dap: unexpected argument #{arg}")
+          return 1
+        end
+      end
+
+      require "milk_tea/dap/server" unless defined?(MilkTea::DAP::Server)
+      server = MilkTea::DAP::Server.new(
+        preferred_backend_kind:,
+        adapter_command:,
+      )
+      server.run
+      0
+    end
+
+    def resolve_adapter_path(adapter_path)
+      unless adapter_path && File.file?(adapter_path)
+        @err.puts("dap: adapter path not found: #{adapter_path}")
+        return nil
+      end
+      expanded = File.expand_path(adapter_path)
+      adapter_path.end_with?(".rb") ? [RbConfig.ruby, expanded] : [expanded]
+    end
+
+    def toolchain_command
+      ToolchainCLI.start(
+        @argv,
+        out: @out,
+        err: @err,
+        help_printer: method(:print_toolchain_help),
+      )
+    end
+
+    def debug_command
+      unless @argv.any?
+        @err.puts("missing source file path")
+        print_usage(@err)
+        return 1
+      end
+
+      resolution = extract_resolution_flags!
+      input_paths = @argv.dup
+      return 1 unless ensure_known_source_operands!("debug", input_paths)
+
+      path = expand_source_paths(input_paths).first
+      unless path
+        @err.puts("no .mt files found in #{input_paths.join(', ')}")
+        return 1
+      end
+
+      ensure_current_lockfile!(path) if resolution[:frozen]
+
+      source = read_source_file(path)
+      resolved_path = File.expand_path(path)
+
+      tokens = MilkTea::Lexer.lex(source, path: resolved_path)
+
+      parse_result = MilkTea::Parser.parse_collecting_errors(source, path: resolved_path)
+      ast = parse_result.ast
+      parse_errors = parse_result.errors.dup
+
+      facts = nil
+      snapshot = nil
+      loader_ast = ast
+
+      if ast && parse_errors.empty?
+        begin
+          loader = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform)
+          loader_ast = loader.load_file(resolved_path)
+
+          import_result = loader.send(:imported_modules_for_ast_collecting_errors, loader_ast, importer_path: resolved_path)
+          import_errors = import_result.respond_to?(:errors) ? import_result.errors : []
+          parse_errors.concat(import_errors) unless import_errors.empty?
+
+          snapshot = MilkTea::SemanticAnalyzer.tooling_snapshot(
+            loader_ast,
+            imported_modules: import_result.modules,
+            allow_missing_imports: true,
+            path: resolved_path,
+          )
+          facts = snapshot&.facts
+        rescue MilkTea::LexError, MilkTea::ParseError, ModuleLoadError, SemanticError => e
+          parse_errors << e
+        end
+      end
+
+      text = DebugInfoFormatter.format_all(
+        content: source,
+        tokens: tokens,
+        ast: loader_ast,
+        parse_errors: parse_errors,
+        facts: facts,
+        snapshot: snapshot,
+        path: resolved_path,
+      )
+
+      @out.puts(text)
+      0
+    rescue MilkTea::LexError => e
+      @err.puts(ErrorFormatter.format(e, color: error_color?(@err)))
+      1
+    end
+
+    def bindgen_command
+      BindgenCLI.start(@argv, out: @out, err: @err, help_printer: method(:print_bindgen_help))
+    end
+
+    def cache_command
+      subcommand = @argv.shift
+      unless subcommand
+        @err.puts("missing cache subcommand")
+        print_command_help("cache", @err)
+        return 1
+      end
+
+      cache_root = MilkTea.data_root.join("tmp", "mtc-cache")
+
+      case subcommand
+      when "purge"
+        if File.directory?(cache_root)
+          FileUtils.rm_rf(cache_root)
+          @out.puts("purged #{cache_root}")
+        else
+          @out.puts("cache is already empty")
+        end
+        0
+      when "status"
+        unless File.directory?(cache_root)
+          @out.puts("cache directory does not exist: #{cache_root}")
+          return 0
+        end
+        program_dirs = Dir.glob(File.join(cache_root, "programs", "*", "*")).select { |d| File.directory?(d) }
+        binary_files = Dir.glob(File.join(cache_root, "binaries", "*", "*", "binary")).select { |f| File.file?(f) }
+        total_size = (program_dirs + binary_files).sum { |p|
+          File.file?(p) ? File.size(p) : Dir.glob(File.join(p, "**", "*")).sum { |f| File.file?(f) ? File.size(f) : 0 }
+        }
+        @out.puts("cache  #{program_dirs.length} programs, #{binary_files.length} binaries  (#{format_size(total_size)})")
+        @out.puts("  root  #{cache_root}")
+        0
+      else
+        @err.puts("unknown cache subcommand #{subcommand}")
+        print_command_help("cache", @err)
+        1
+      end
+    end
+
+    def completions_command
+      shell = @argv.shift
+      unless %w[bash zsh fish].include?(shell)
+        @err.puts("completions: shell must be bash, zsh, or fish")
+        print_command_help("completions", @err)
+        return 1
+      end
+
+      @out.puts(completion_script(shell))
+      0
+    end
+
+    def completion_script(shell)
+      names = COMMANDS.map(&:first)
+      case shell
+      when "bash"
+        [
+          "# mtc bash completion. Source this file or install it into your bash",
+          "# completion directory (e.g. /etc/bash_completion.d/mtc).",
+          "_mtc() {",
+          %(  local cur="${COMP_WORDS[COMP_CWORD]}"),
+          %(  if [ "${COMP_CWORD}" -eq 1 ]; then),
+          %(    COMPREPLY=( $(compgen -W "#{(names + %w[help version]).join(' ')}" -- "${cur}") )),
+          "  fi",
+          "}",
+          "complete -F _mtc mtc",
+        ].join("\n")
+      when "zsh"
+        lines = ["#compdef mtc", "# mtc zsh completion. Install onto your $fpath as _mtc.", "_mtc() {", "  local -a commands", "  commands=("]
+        COMMANDS.each { |name, summary| lines << "    '#{name}:#{summary}'" }
+        lines.concat(["  )", "  if (( CURRENT == 2 )); then", "    _describe 'mtc command' commands", "  fi", "}", %(_mtc "$@")])
+        lines.join("\n")
+      when "fish"
+        lines = ["# mtc fish completion. Install into ~/.config/fish/completions/mtc.fish."]
+        COMMANDS.each do |name, summary|
+          lines << "complete -c mtc -f -n '__fish_use_subcommand' -a #{name} -d '#{summary}'"
+        end
+        lines.join("\n")
+      end
+    end
+
+    def parse_build_options(allow_clean: false)
+      options = {
+        output_path: nil,
+        cc: ENV.fetch("CC", "cc"),
+        keep_c_path: nil,
+        profile: nil,
+        platform: nil,
+        bundle: false,
+        archive: false,
+        locked: false,
+        frozen: false,
+        no_cache: false,
+        kind: :executable,
+        timings: false,
+        debug_guards: nil,
+      }
+      options[:clean] = false if allow_clean
+
+      positional = []
+      until @argv.empty?
+        option = @argv.shift
+        case option
+        when "-o", "--output"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:output_path] = value
+        when "--cc"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:cc] = value
+        when "--keep-c"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:keep_c_path] = value
+        when "--profile"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:profile] = value
+        when "--platform"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:platform] = value
+        when "--bundle"
+          options[:bundle] = true
+        when "--archive"
+          options[:bundle] = true
+          options[:archive] = true
+        when "--locked"
+          options[:locked] = true
+        when "--frozen"
+          options[:locked] = true
+          options[:frozen] = true
+        when "--no-cache"
+          options[:no_cache] = true
+        when "--debug-guards"
+          options[:debug_guards] = true
+        when "--no-debug-guards"
+          options[:debug_guards] = false
+        when "--timings"
+          options[:timings] = true
+        when "--kind"
+          value = @argv.shift
+          return missing_option_value(option) unless value
+
+          options[:kind] = case value
+                           when "executable", "exe", "bin" then :executable
+                           when "static", "staticlib" then :static
+                           when "shared", "dylib", "dll", "so" then :shared
+                           else
+                             @err.puts("unknown build kind #{value}; expected executable|static|shared")
+                             print_usage(@err)
+                             return nil
+                           end
+        when "--clean"
+          if allow_clean
+            options[:clean] = true
+          else
+            @err.puts("unknown build option #{option}")
+            print_usage(@err)
+            return nil
+          end
+        when "--"
+          positional.concat(@argv)
+          @argv.clear
+        else
+          if option.start_with?("-")
+            @err.puts("unknown build option #{option}")
+            print_usage(@err)
+            return nil
+          end
+          positional << option
+        end
+      end
+
+      @argv = positional
+      options
+    end
+
+    def parse_format_options
+      options = {
+        check: false,
+        write: false,
+        mode: :safe,
+        max_line_length: nil,
+        profile: false,
+      }
+      input_paths = []
+
+      until @argv.empty?
+        option = @argv.shift
+        if option.start_with?("-")
+          case option
+          when "--check"
+            options[:check] = true
+          when "--write", "-w"
+            options[:write] = true
+          when "--preserve"
+            options[:mode] = :preserve
+          when "--canonical"
+            options[:mode] = :canonical
+          when "--safe"
+            options[:mode] = :safe
+          when "--tidy"
+            options[:mode] = :tidy
+          when "--max-line-length"
+            value = @argv.shift
+            return missing_option_value(option) unless value
+
+            line_length = Integer(value, exception: false)
+            unless line_length && line_length.positive?
+              @err.puts("--max-line-length must be a positive integer")
+              print_usage(@err)
+              return nil
+            end
+
+            options[:max_line_length] = line_length
+          when "--timings"
+            options[:profile] = true
+          when "--"
+            input_paths.concat(@argv)
+            @argv.clear
+          else
+            @err.puts("unknown format option #{option}")
+            print_usage(@err)
+            return nil
+          end
+        else
+          input_paths << option
+        end
+      end
+
+      if options[:check] && options[:write]
+        @err.puts("format options --check and --write cannot be combined")
+        print_usage(@err)
+        return nil
+      end
+
+      { options:, input_paths: }
+    end
+
+    def ensure_known_source_operands!(command, operands)
+      return true unless operands.any? { |arg| arg.start_with?("-") }
+
+      @err.puts("unexpected argument(s) for #{command}: #{operands.join(' ')}")
+      print_command_help(command, @err)
+      false
+    end
+
+    def expand_source_paths(input_paths)
+      input_paths.flat_map do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, "**/*.mt")).sort
+        else
+          [path]
+        end
+      end.uniq
+    end
+
+    def print_no_source_files_if_empty(paths, input_paths)
+      return false unless paths.empty?
+
+      label = input_paths.length == 1 ? input_paths.first : input_paths.join(", ")
+      @out.puts("no .mt files found in #{label}")
+      true
+    end
+
+    def missing_option_value(option)
+      @err.puts("missing value for #{option}")
+      print_usage(@err)
+      nil
+    end
+
+    def handled_cli_error?(error)
+      handled_error_classes.any? { |klass| error.is_a?(klass) }
+    end
+
+    def handled_error_classes
+      classes = [LexError, ParseError, ModuleLoadError, SemanticError, LoweringError, CBackendError, BuildError, RunError, FormatterError, PackageManifestError, PackageManifestEditorError, PackageGraphError, PackageLockError, PackageSourceResolverError, PackageSourceFetcherError, PackageRegistryStoreError, PackageRegistryMetadataProviderError, PackageDependencySolverError, PackageVersionError, ProjectScaffoldError]
+      classes << BindgenError if MilkTea.const_defined?(:BindgenError, false)
+      classes << UpstreamSources::Error if MilkTea.const_defined?(:UpstreamSources, false)
+      classes
+    end
+
+    def read_source_file(path)
+      resolved_path = File.expand_path(path.to_s)
+      @source_overrides.fetch(resolved_path) { File.read(resolved_path) }
+    rescue Errno::ENOENT
+      raise ModuleLoadError.new("source file not found", path: path)
+    rescue Errno::EISDIR
+      raise ModuleLoadError.new("expected a source file, got a directory", path: path)
+    end
+
+    def generated_source?(source)
+      source.start_with?(GENERATED_FILE_HEADER_PREFIX)
+    end
+
+    ACTION_LABELS = {
+      "format-check" => "checking",
+      "format-write" => "formatting",
+      "lint" => "linting",
+      "lint-fix" => "fixing",
+    }.freeze
+
+    def announce_file_action(path, action)
+      return unless @verbose
+
+      @out.puts("#{ACTION_LABELS.fetch(action, action)} #{path}")
+    end
+
+    def make_module_loader(path = nil, locked: false, platform: nil)
+      ModuleLoader.new(module_roots: module_roots_for(path, locked:), package_graph: package_graph_for(path, locked:), source_overrides: @source_overrides, platform:)
+    end
+
+    def normalize_source_overrides(source_overrides)
+      return {} unless source_overrides
+
+      source_overrides.each_with_object({}) do |(path, source), overrides|
+        overrides[File.expand_path(path.to_s)] = source.to_s
+      end
+    end
+
+    def module_roots_for(path = nil, locked: false)
+      roots = @include_module_roots.dup
+
+      if path
+        MilkTea::ModuleRoots.roots_for_path(path, locked:).each do |root|
+          roots << root unless roots.include?(root)
+        end
+      end
+
+      @ambient_module_roots.each do |root|
+        roots << root unless roots.include?(root)
+      end
+      roots
+    end
+
+    def package_graph_for(path = nil, locked: false)
+      return nil unless path
+
+      PackageGraph.load(path, locked:)
+    rescue PackageManifestError
+      nil
+    end
+
+    def package_services
+      @package_services ||= PackageServices.new
+    end
+
+    def extract_resolution_flags!
+      locked = false
+      frozen = false
+      warnings_as_errors = false
+      remaining = []
+      i = 0
+      while i < @argv.length
+        arg = @argv[i]
+        if arg == "--locked"
+          locked = true
+        elsif arg == "--frozen"
+          locked = true
+          frozen = true
+        elsif arg == "-Werror" || arg == "--warnings-as-errors"
+          warnings_as_errors = true
+        elsif arg == "--"
+          remaining.concat(@argv[i + 1..])
+          break
+        else
+          remaining << arg
+        end
+        i += 1
+      end
+      @argv = remaining
+      { locked:, frozen:, warnings_as_errors: }
+    end
+
+    def ensure_no_extra_arguments!(command)
+      return true if @argv.empty?
+
+      @err.puts("unexpected argument(s) for #{command}: #{@argv.join(' ')}")
+      print_command_help(command, @err)
+      false
+    end
+
+    def ensure_current_lockfile!(path)
+      result = PackageLock.check(path, source_resolver: package_services.source_resolver(:cache))
+      return if result.current?
+
+      message = if result.missing?
+                  "package.lock is missing: #{result.lock_path}"
+                else
+                  "package.lock is out of date: #{result.lock_path}"
+                end
+      raise PackageLockError, message
+    end
+
+    def ensure_current_lockfiles!(paths)
+      checked = {}
+
+      paths.each do |path|
+        result = PackageLock.check(path, source_resolver: package_services.source_resolver(:cache))
+        next if checked[result.lock_path]
+
+        checked[result.lock_path] = true
+        next if result.current?
+
+        message = if result.missing?
+                    "package.lock is missing: #{result.lock_path}"
+                  else
+                    "package.lock is out of date: #{result.lock_path}"
+                  end
+        raise PackageLockError, message
+      end
+    end
+
+    def lint_sema_facts_for(source, path, locked: false)
+      ast = Parser.parse(source, path: path)
+      imported_modules = make_module_loader(path, locked:, platform: ModuleLoader.default_host_platform).imported_modules_for_ast(ast, importer_path: path)
+      SemanticAnalyzer.tooling_snapshot(ast, imported_modules: imported_modules, path: path).facts
+    rescue MilkTea::LexError, MilkTea::ParseError, SemanticError, ModuleLoadError
+      nil
+    end
+
+    def extract_include_paths!
+      remaining = []
+      i = 0
+      while i < @argv.length
+        if @argv[i] == "-I" || @argv[i] == "--include-path"
+          value = @argv[i + 1]
+          if value && !value.start_with?("-")
+            @include_path_flags << @argv[i]
+            @include_module_roots << File.expand_path(value)
+            i += 2
+          else
+            @err.puts("missing value for #{@argv[i]}")
+            i += 1
+          end
+        else
+          remaining << @argv[i]
+          i += 1
+        end
+      end
+      @argv = remaining
+    end
+
+    def open_browser(url)
+      command = host_platform == :windows ? ["cmd", "/c", "start", "", url] : ["xdg-open", url]
+      pid = Process.spawn(*command, out: File::NULL, err: File::NULL)
+      Process.detach(pid)
+    rescue Errno::ENOENT
+      @err.puts("note: could not open browser (#{command.first} not found)")
+    end
+
+    def host_platform
+      MilkTea.host_platform
+    end
+
+    def command_supports_include_paths?(command)
+      %w[parse lint check lower emit-c build run test debug].include?(command)
+    end
+
+    COMMAND_HELP = {
+      "test"            => <<~HELP,
+        Usage: mtc test PATH|DIR [--cc COMPILER] [--profile debug|release] [--platform linux|windows|wasm] [--timeout SECONDS] [--mem MB] [--jobs N] [--sanitize] [-n SUBSTRING] [--format human|tap|junit] [--locked] [--frozen] [-I PATH]
+
+          Discover and run @[test] functions in a Milk Tea source file or directory.
+
+          Given a file, runs its @[test] functions. Given a directory (or a package
+          root), recursively discovers every .mt file that contains @[test] functions,
+          runs each as its own test binary, and prints an aggregate summary.
+
+          Functions annotated with @[test] must take no parameters and return
+          std.testing.Check. `mtc test` synthesizes a runner that invokes each
+          test through std.testing and reports the results; a test file must import
+          std.testing and must not define `main`.
+
+          Each test binary runs under a wall-clock timeout and an address-space
+          memory cap so a hanging or runaway test cannot stall or exhaust the host.
+          Override them with --timeout SECONDS (default 30) and --mem MB (default 1024).
+          For a directory, --jobs N builds and runs N files in parallel (default 1; output
+          stays in file order).
+          A file containing `# expect-error: <text>` is a compile-fail fixture: `mtc test`
+          requires the compiler to reject it with a diagnostic containing that text.
+          --sanitize builds test binaries with AddressSanitizer/UBSan (including leak
+          detection); any sanitizer error fails the run.
+          -n SUBSTRING runs only @[test] functions whose name contains SUBSTRING (and, in a
+          directory, compile-fail fixtures whose filename matches).
+          --format tap|junit emits machine-readable results (TAP / JUnit XML) instead of the
+          human summary, for CI.
+        HELP
+      "debug"           => "Usage: mtc debug PATH [--locked] [--frozen] [-I PATH]\n\n  Print debug information for a source file: tokens, AST, semantic facts,\n  binding resolution, and diagnostics.",
+      "lex"             => "Usage: mtc lex PATH\n\n  Tokenize a source file and print the token stream.",
+      "parse"           => "Usage: mtc parse PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]\n\n  Parse one or more source files and print the AST.\n\n  Options:\n    --locked               Resolve dependencies from package.lock.\n    --frozen               Require a current package.lock.\n    -I, --include-path     Add an extra module root.",
+      "format"          => <<~HELP,
+        Usage: mtc format PATH|DIR [PATH|DIR ...] [OPTIONS]
+
+          Format Milk Tea source files.
+
+          Options:
+            --check          Report files that need formatting without writing them.
+            --write, -w      Rewrite files in place.
+            --safe           Format only unambiguous style changes (default).
+            --canonical      Apply all canonical style normalisations.
+            --preserve       Preserve existing formatting where possible.
+            --tidy           Apply tidy formatting with line wrapping and blank-line normalization.
+            --max-line-length N
+                             Override the line length used by tidy mode.
+            --timings        Print per-file format timing breakdown.
+
+          When formatting directories or multiple files, --check or --write is required.
+        HELP
+      "lint"            => <<~HELP,
+        Usage: mtc lint PATH|DIR [OPTIONS]
+               mtc lint --init
+
+          Lint Milk Tea source files and report warnings.
+          Some rules and auto-fixes are semantic/import-aware, so lint can use
+          the same dependency resolution mode as check/build.
+
+          Options:
+            --init                  Create a default .mt-lint.yml in the current directory.
+            --select RULES          Comma-separated list of rule codes to enable.
+            --ignore RULES          Comma-separated list of rule codes to suppress.
+            --fix                   Apply auto-fixable changes in place.
+            --ignore-generated      Skip files that start with '# generated by mtc'.
+            --timings               Print lint timing: per-file summary and per-rule breakdown.
+            --locked                Use package.lock for semantic dependency resolution.
+            --frozen                Require a current package.lock before semantic dependency resolution.
+            -I, --include-path PATH Add an extra module root for semantic resolution.
+        HELP
+      "check"           => <<~HELP,
+        Usage: mtc check PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-Werror] [-I PATH]
+
+          Run semantic analysis on one or more source files and report errors.
+
+          Options:
+            -Werror                     Treat warnings as errors.
+            --locked / --frozen         Dependency resolution mode.
+            -I, --include-path PATH     Add an extra module root.
+        HELP
+      "lower"           => "Usage: mtc lower PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]\n\n  Lower one or more source files to IR and print it.",
+      "emit-c"          => "Usage: mtc emit-c PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]\n\n  Compile one or more source files to C and print the output.",
+      "build"           => <<~HELP,
+        Usage: mtc build [PATH_OR_PACKAGE] [OPTIONS]
+
+          Compile a source file or package. Defaults to current directory if a
+          package.toml is present.
+
+          Options:
+            -o, --output OUTPUT          Output path for the compiled artifact.
+            --cc COMPILER                C compiler to use (default: $CC or cc).
+            --keep-c C_PATH              Write the generated C source to this path.
+            --profile PROFILE            debug (default) | release.
+            --platform PLATFORM          linux (default) | windows | wasm.
+            --bundle                     Package a native package build into a distributable directory.
+            --archive                    Also write a .tar.gz archive for the native bundle (implies --bundle).
+             --locked                     Resolve dependencies from package.lock.
+             --frozen                     Require a current package.lock and use locked resolution.
+             --no-cache                   Skip build cache, force rebuild from source.
+             --debug-guards               Enable loop iteration and recursion guards (default: on in debug, off in release).
+             --no-debug-guards            Disable loop iteration and recursion guards.
+             --clean                      Remove existing build outputs and exit.
+             -I, --include-path PATH      Add an extra module root.
+         HELP
+      "new"             => <<~HELP,
+        Usage: mtc new NAME
+
+          Create a new application package scaffold with package.toml and src/main.mt.
+          NAME selects the target directory, and its basename is normalized to
+          snake_case for package.name and the generated module declaration.
+          The target may be a new directory or an existing empty directory.
+        HELP
+      "run"             => <<~HELP,
+        Usage: mtc run [PATH_OR_PACKAGE] [OPTIONS]
+
+          Build and execute an executable target. For wasm targets this starts a
+          local preview server, opens the generated HTML in your browser, and
+          keeps serving until you press Ctrl-C.
+          Defaults to current directory if a package.toml is present.
+
+          Options:
+            -o, --output OUTPUT          Output path for the compiled binary.
+            --cc COMPILER                C compiler to use (default: $CC or cc).
+            --keep-c C_PATH              Write the generated C source to this path.
+            --profile PROFILE            debug (default) | release.
+            --platform PLATFORM          linux (default) | windows | wasm.
+             --locked                     Resolve dependencies from package.lock.
+             --frozen                     Require a current package.lock and use locked resolution.
+             --no-cache                   Skip build cache, force rebuild from source.
+             --debug-guards               Enable loop iteration and recursion guards (default: on in debug, off in release).
+             --no-debug-guards            Disable loop iteration and recursion guards.
+             -I, --include-path PATH      Add an extra module root.
+         HELP
+       "run-module"      => <<~HELP,
+        Usage: mtc run-module MODULE [OPTIONS] [-- ARGS...]
+
+          Resolve a standard-library module by name, build it, and run it.
+          Like `python -m module.name`, this finds the module in the module
+          roots (e.g., std/http/server.mt for `http/server`), compiles it, and
+          forwards remaining arguments to the program.
+
+          Module name can use / or . separators (e.g., http/server or http.server).
+
+          Options:
+            --cc COMPILER                C compiler to use (default: $CC or cc).
+            --profile PROFILE            debug (default) | release.
+            --platform PLATFORM          linux (default) | windows | wasm.
+            --locked                     Resolve dependencies from package.lock.
+            --frozen                     Require a current package.lock and use locked resolution.
+            -I, --include-path PATH      Add an extra module root.
+
+          Arguments after -- are forwarded to the module as-is.
+        HELP
+      "toolchain"       => <<~HELP,
+        Usage: mtc toolchain SUBCOMMAND
+
+          Manage the local native toolchain and upstream native library checkouts.
+
+          Subcommands:
+            bootstrap    Download and prepare all upstream native libraries.
+            doctor       Check that all required tools and libraries are available.
+            tools        Build vendored tool binaries (e.g. tracy-profiler).
+        HELP
+      "deps"            => <<~HELP,
+        Usage: mtc deps SUBCOMMAND
+
+          Manage package dependencies and package.lock state.
+
+          Subcommands:
+            add          Add or update a package dependency and refresh package.lock.
+            remove       Remove a package dependency and refresh package.lock.
+            update       Re-resolve dependencies and refresh package.lock.
+            tree         Print the package dependency tree for a local package.
+            lock         Write or verify a deterministic package.lock for a local package.
+            publish      Publish an exact-version package into the local or configured upstream registry store.
+            fetch        Materialize cache-backed sources from package.lock explicitly.
+        HELP
+      "bindgen"         => <<~HELP,
+        Usage: mtc bindgen MODULE HEADER [OPTIONS]
+
+          Generate a Milk Tea binding module from a C header.
+
+          Options:
+            -o, --output OUTPUT    Write the generated module to this file.
+            --nullable-report PATH Write the remaining manual nullable policy report to this file.
+            --link LIB             Link against this library (repeatable).
+            --include HEADER       Extra #include directive (repeatable).
+            --clang PATH           Clang binary to use (default: $CLANG or clang).
+            --clang-arg ARG        Extra argument to pass to clang (repeatable).
+        HELP
+      "cache"           => <<~HELP,
+        Usage: mtc cache SUBCOMMAND
+
+          Inspect and manage the build cache.
+
+          Subcommands:
+            purge        Remove the entire build cache.
+            status       Show cache directory, entry counts, and total size.
+        HELP
+      "docs"            => <<~HELP,
+        Usage: mtc docs [OPTIONS]
+
+          Start a local documentation server for Milk Tea with language reference
+          and standard library exploration.
+
+          Options:
+            --open, -o            Open the docs in your default browser.
+            --port, -p PORT       Listen on a specific port (default: random).
+        HELP
+      "snapshot"        => <<~HELP,
+        Usage: mtc snapshot INPUT.mt [OPTIONS]
+
+          Generate an HTML snapshot of a Milk Tea source file with VS Code syntax
+          highlighting using the active TextMate grammar and the configured theme.
+
+          Options:
+            --theme, -t PATH      VS Code theme JSON file (default: 2026 Dark).
+            --output, -o PATH     Write HTML to PATH instead of stdout.
+        HELP
+      "lsp"             => <<~HELP,
+        Usage: mtc lsp [OPTIONS]
+
+          Start the Milk Tea Language Server. Reads JSON-RPC messages from stdin
+          and writes responses to stdout. Stderr is reserved for logging.
+
+          Options:
+            --log-level LEVEL     Log verbosity: trace, debug, info, warn, or
+                                  error (default: warn, set by extension).
+            --stdio               Enable stdio transport (default).
+        HELP
+      "dap"             => <<~HELP,
+        Usage: mtc dap [OPTIONS]
+
+          Start the Milk Tea Debug Adapter. Reads DAP messages from stdin
+          and writes responses to stdout.
+
+          Options:
+            --backend KIND        Debug backend kind (default: process).
+            --adapter-path PATH   Path to an lldb-dap or cppdbg adapter
+                                  executable or Ruby bridge script.
+        HELP
+      "completions"     => <<~HELP,
+        Usage: mtc completions bash|zsh|fish
+
+          Print a shell completion script to stdout. Source it (or install it into
+          your shell's completion directory) to get tab-completion for mtc commands.
+
+          Examples:
+            mtc completions bash > /etc/bash_completion.d/mtc
+            mtc completions zsh  > ~/.zsh/completions/_mtc
+            mtc completions fish > ~/.config/fish/completions/mtc.fish
+        HELP
+    }.freeze
+
+    def format_size(bytes)
+      return "0 B" if bytes.zero?
+
+      units = %w[B KiB MiB GiB]
+      exp = (Math.log(bytes) / Math.log(1024)).to_i
+      exp = units.length - 1 if exp >= units.length
+      format("%.1f %s", bytes.to_f / (1024**exp), units[exp])
+    end
+
+    def print_command_help(command, io)
+      text = COMMAND_HELP[command]
+      if text
+        io.puts(text.chomp)
+      else
+        print_usage(io)
+      end
+    end
+
+    def print_toolchain_help(io)
+      print_command_help("toolchain", io)
+    end
+
+    def print_deps_help(io)
+      print_command_help("deps", io)
+    end
+
+    def print_bindgen_help(io)
+      print_command_help("bindgen", io)
+    end
+
+    def print_cache_help(io)
+      print_command_help("cache", io)
+    end
+
+    def print_usage(io)
+      io.puts("Usage: mtc lex PATH")
+      io.puts("       mtc parse PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc format PATH|DIR [PATH|DIR ...] [--check|--write] [--safe|--canonical|--preserve|--tidy] [--max-line-length N] [--timings]")
+      io.puts("       mtc lint PATH|DIR [--select RULES] [--ignore RULES] [--fix] [--ignore-generated] [--timings] [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc lint --init")
+      io.puts("       mtc check PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-Werror] [-I PATH]")
+      io.puts("       mtc debug PATH [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc lower PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc emit-c PATH|DIR [PATH|DIR ...] [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc build [PATH_OR_PACKAGE] [-o OUTPUT] [--cc COMPILER] [--keep-c C_PATH] [--profile debug|release] [--platform linux|windows|wasm] [--bundle] [--archive] [--locked] [--frozen] [--no-cache] [--debug-guards|--no-debug-guards] [--clean] [-I PATH]")
+      io.puts("       mtc new NAME")
+      io.puts("       mtc run [PATH_OR_PACKAGE] [-o OUTPUT] [--cc COMPILER] [--keep-c C_PATH] [--profile debug|release] [--platform linux|windows|wasm] [--locked] [--frozen] [-I PATH] [--debug-guards|--no-debug-guards]")
+      io.puts("       mtc test PATH|DIR [--cc COMPILER] [--profile debug|release] [--platform linux|windows|wasm] [--timeout SECONDS] [--mem MB] [--jobs N] [--sanitize] [-n SUBSTRING] [--format human|tap|junit] [--locked] [--frozen] [-I PATH]")
+      io.puts("       mtc run-module MODULE [--cc COMPILER] [--profile debug|release] [--platform linux|windows|wasm] [--locked] [--frozen] [-I PATH] [-- ARGS...]")
+      io.puts("       mtc toolchain bootstrap")
+      io.puts("       mtc toolchain doctor")
+      io.puts("       mtc toolchain tools")
+      io.puts("       mtc deps add [PATH_OR_PACKAGE] NAME[@VERSION_REQ] [--path PATH] [--git URL --rev REV [--subdir DIR]] [--version VERSION_REQ]")
+      io.puts("       mtc deps remove [PATH_OR_PACKAGE] NAME")
+      io.puts("       mtc deps update [PATH_OR_PACKAGE] [NAME ...]")
+      io.puts("       mtc deps tree [PATH_OR_PACKAGE]")
+      io.puts("       mtc deps lock [PATH_OR_PACKAGE] [--check]")
+      io.puts("       mtc deps publish [PATH_OR_PACKAGE] [--upstream]")
+      io.puts("       mtc deps fetch [PATH_OR_PACKAGE]")
+      io.puts("       mtc bindgen MODULE HEADER [-o OUTPUT] [--nullable-report PATH] [--link LIB] [--include HEADER] [--clang PATH] [--clang-arg ARG]")
+      io.puts("       mtc cache purge|status")
+      io.puts("       mtc docs [--open] [--port PORT]")
+      io.puts("       mtc snapshot INPUT.mt [--theme PATH] [-o OUTPUT]")
+      io.puts("       mtc lsp [--log-level LEVEL] [--stdio]")
+      io.puts("       mtc dap [--backend KIND] [--adapter-path PATH]")
+      io.puts("       mtc completions bash|zsh|fish")
+    end
+
+    def print_help(io)
+      io.puts("mtc #{MilkTea::VERSION} \u2014 the Milk Tea compiler")
+      io.puts
+      io.puts("Usage: mtc <command> [options]")
+      io.puts
+      io.puts("Commands:")
+      width = COMMANDS.map { |name, _| name.length }.max
+      COMMANDS.each do |name, summary|
+        io.puts("  #{name.ljust(width)}  #{summary}")
+      end
+      io.puts
+      io.puts("Global options:")
+      io.puts("  -h, --help        Show this help (use `mtc help <command>` for command help)")
+      io.puts("  -V, --version     Print the compiler version")
+      io.puts("  -q, --quiet       Suppress informational output")
+      io.puts("  -v, --verbose     Print per-file progress")
+      io.puts("      --color WHEN  Colorize diagnostics: auto (default), always, never")
+      io.puts
+      io.puts("Run `mtc <command> --help` for detailed usage of a command.")
+      io.puts
+      print_usage(io)
+    end
+  end
+end