mt-lang 0.2.0

data/lib/milk_tea/tooling/debug_map.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module MilkTea
+  class DebugMap
+    VERSION = 1
+
+    Entry = Data.define(:name, :linkage_name, :line) do
+      def to_h
+        payload = {
+          "name" => name,
+          "cName" => linkage_name,
+        }
+        payload["line"] = line if line
+        payload
+      end
+    end
+
+    Function = Data.define(:name, :linkage_name, :source_path, :line, :params, :locals) do
+      def to_h(base_dir: nil)
+        payload = {
+          "name" => name,
+          "cName" => linkage_name,
+          "params" => params.map(&:to_h),
+          "locals" => locals.map(&:to_h),
+        }
+        serialized_source_path = DebugMap.path_for_payload(source_path, base_dir)
+        payload["sourcePath"] = serialized_source_path if serialized_source_path
+        payload["line"] = line if line
+        payload
+      end
+    end
+
+    attr_reader :binary_path, :program_source_path, :functions
+
+    def initialize(binary_path:, program_source_path:, functions:)
+      @binary_path = binary_path ? File.expand_path(binary_path) : nil
+      @program_source_path = program_source_path ? File.expand_path(program_source_path) : nil
+      @functions = functions
+      @functions_by_c_name = functions.each_with_object({}) do |function, memo|
+        memo[function.linkage_name] ||= function
+      end
+    end
+
+    def self.sidecar_path_for(binary_path)
+      "#{File.expand_path(binary_path)}.mtdbg.json"
+    end
+
+    def self.load(path)
+      resolved_path = File.expand_path(path)
+      base_dir = File.dirname(resolved_path)
+      payload = JSON.parse(File.read(resolved_path))
+      functions = Array(payload["functions"]).map do |function|
+        Function.new(
+          name: function.fetch("name"),
+          linkage_name: function.fetch("cName"),
+          source_path: path_from_payload(function["sourcePath"], base_dir),
+          line: function["line"],
+          params: load_entries(function["params"]),
+          locals: load_entries(function["locals"])
+        )
+      end
+
+      new(
+        binary_path: path_from_payload(payload["binaryPath"], base_dir),
+        program_source_path: path_from_payload(payload["programSourcePath"], base_dir),
+        functions:
+      )
+    end
+
+    def self.load_for_binary(binary_path)
+      path = sidecar_path_for(binary_path)
+      return nil unless File.file?(path)
+
+      load(path)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.from_ir(ir_program, binary_path:)
+      functions = ir_program.functions.map do |function|
+        source_path = first_statement_source_path(function.body) || ir_program.source_path
+        Function.new(
+          name: function.name.to_s,
+          linkage_name: function.linkage_name.to_s,
+          source_path: source_path ? File.expand_path(source_path) : nil,
+          line: first_statement_line(function.body),
+          params: function.params.map { |param| Entry.new(name: param.name.to_s, linkage_name: param.linkage_name.to_s, line: nil) },
+          locals: collect_locals(function.body)
+        )
+      end
+
+      new(binary_path:, program_source_path: ir_program.source_path, functions:)
+    end
+
+    def write(path)
+      resolved_path = File.expand_path(path)
+      base_dir = File.dirname(resolved_path)
+      FileUtils.mkdir_p(base_dir)
+      File.write(resolved_path, JSON.pretty_generate(to_h(base_dir:)) + "\n")
+    end
+
+    def function_for_c_name(c_name)
+      @functions_by_c_name[c_name.to_s]
+    end
+
+    def variable_for(function_c_name, c_name)
+      function = function_for_c_name(function_c_name)
+      return nil unless function
+
+      function.params.find { |entry| entry.linkage_name == c_name.to_s } ||
+        function.locals.find { |entry| entry.linkage_name == c_name.to_s }
+    end
+
+    def source_variable_for(function_c_name, source_name)
+      function = function_for_c_name(function_c_name)
+      return nil unless function
+
+      matches = (function.params + function.locals).select { |entry| entry.name == source_name.to_s }
+      return nil if matches.empty?
+
+      return matches.first if matches.map(&:linkage_name).uniq.one?
+
+      nil
+    end
+
+    def to_h(base_dir: nil)
+      payload = {
+        "version" => VERSION,
+        "functions" => functions.map { |function| function.to_h(base_dir:) },
+      }
+      serialized_binary_path = self.class.path_for_payload(binary_path, base_dir)
+      payload["binaryPath"] = serialized_binary_path if serialized_binary_path
+      serialized_program_source_path = self.class.path_for_payload(program_source_path, base_dir)
+      payload["programSourcePath"] = serialized_program_source_path if serialized_program_source_path
+      payload
+    end
+
+    def self.path_for_payload(path, base_dir)
+      return nil unless path
+      return path.tr("\\", "/") unless base_dir
+
+      expanded_path = File.expand_path(path)
+      begin
+        Pathname.new(expanded_path).relative_path_from(Pathname.new(base_dir)).to_s.tr("\\", "/")
+      rescue ArgumentError
+        expanded_path.tr("\\", "/")
+      end
+    end
+
+    def self.path_from_payload(path, base_dir)
+      return nil unless path
+      return path if path.empty?
+      return path if absolute_path_string?(path)
+      return path unless base_dir
+
+      File.expand_path(path, base_dir)
+    end
+
+    def self.absolute_path_string?(path)
+      path.start_with?("/") || path.start_with?("\\\\") || path.match?(/\A[A-Za-z]:[\\\/]/)
+    end
+
+    class << self
+      private
+
+      def load_entries(entries)
+        Array(entries).map do |entry|
+          Entry.new(name: entry.fetch("name"), linkage_name: entry.fetch("cName"), line: entry["line"])
+        end
+      end
+
+      def collect_locals(statements, locals = [])
+        Array(statements).each do |statement|
+          case statement
+          when IR::LocalDecl
+            locals << Entry.new(name: statement.name.to_s, linkage_name: statement.linkage_name.to_s, line: statement.line)
+          when IR::BlockStmt, IR::WhileStmt
+            collect_locals(statement.body, locals)
+          when IR::ForStmt
+            collect_locals([statement.init], locals)
+            collect_locals(statement.body, locals)
+            collect_locals([statement.post], locals)
+          when IR::IfStmt
+            collect_locals(statement.then_body, locals)
+            collect_locals(statement.else_body, locals)
+          when IR::SwitchStmt
+            statement.cases.each do |switch_case|
+              collect_locals(switch_case.body, locals)
+            end
+          end
+        end
+
+        locals
+      end
+
+      def first_statement_source_path(statements)
+        Array(statements).each do |statement|
+          if statement.respond_to?(:source_path) && statement.source_path
+            return statement.source_path
+          end
+
+          nested = nested_statements(statement)
+          nested.each do |branch|
+            source_path = first_statement_source_path(branch)
+            return source_path if source_path
+          end
+        end
+
+        nil
+      end
+
+      def first_statement_line(statements)
+        Array(statements).each do |statement|
+          if statement.respond_to?(:line) && statement.line
+            return statement.line
+          end
+
+          nested = nested_statements(statement)
+          nested.each do |branch|
+            line = first_statement_line(branch)
+            return line if line
+          end
+        end
+
+        nil
+      end
+
+      def nested_statements(statement)
+        case statement
+        when IR::BlockStmt, IR::WhileStmt
+          [statement.body]
+        when IR::ForStmt
+          [[statement.init], statement.body, [statement.post]]
+        when IR::IfStmt
+          [statement.then_body, statement.else_body]
+        when IR::SwitchStmt
+          statement.cases.map(&:body)
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/milk_tea/tooling/docs_app.rb

@@ -0,0 +1,369 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "json"
+require "open3"
+
+module MilkTea
+  class DocsApp < Sinatra::Base
+    SNAPSHOT_CACHE = {}
+
+    MODULE_CATEGORIES = {
+      "Collections" => %w[vec deque binary_heap priority_queue ordered_set ordered_map map set linked_map linked_set counter multiset queue stack],
+      "Memory" => %w[mem cell],
+      "Text & Format" => %w[string str fmt cstring encoding base64],
+      "Math & Random" => %w[math random],
+      "Data & Serialization" => %w[binary bytes json toml tar gzip zstd crypto hash],
+      "Concurrency" => %w[async jobs sync thread],
+      "Files & I/O" => %w[fs path stdio],
+      "System" => %w[ctype errno process time c],
+      "Network & HTTP" => %w[net http uri cookie curl],
+      "Game & Graphics" => %w[raylib box2d flecs enet cgltf cjson],
+      "Algorithms & AI" => %w[fsm behavior_tree goap],
+      "Database & Matching" => %w[sqlite3 pcre2],
+      "Utilities" => %w[cli terminal span spatial asset_pack],
+    }.freeze
+
+    configure do
+      set :views, File.expand_path("views", __dir__)
+      set :public_folder, File.expand_path("public", __dir__)
+      set :static, true
+      set :logging, false
+      set :show_exceptions, false
+    end
+
+    helpers do
+      def stdlib_root
+        @stdlib_root ||= File.expand_path("../../../std", __dir__)
+      end
+
+      def reference_index
+        @reference_index ||= File.expand_path("../../../docs/index.html", __dir__)
+      end
+
+      def h(text)
+        Rack::Utils.escape_html(text.to_s)
+      end
+
+      def active?(path)
+        request.path_info == path ? "active" : ""
+      end
+
+      def stdlib_modules
+        @stdlib_modules ||= discover_modules.freeze
+      end
+
+      def categorized_modules
+        @categorized_modules ||= begin
+          cats = {}
+          uncategorized = []
+
+          stdlib_modules.each do |mod|
+            cat = MODULE_CATEGORIES.find { |_, names| names.include?(mod[:name]) }&.first
+            if cat
+              (cats[cat] ||= []) << mod
+            else
+              uncategorized << mod
+            end
+          end
+
+          cats["Other"] = uncategorized unless uncategorized.empty?
+          cats
+        end.freeze
+      end
+
+      def snapshot_available?
+        !!snapshot_script_path
+      end
+
+      def snapshot_for(source_path)
+        return nil unless snapshot_available?
+
+        cache_key = "#{source_path}:#{File.mtime(source_path).to_i}"
+        cached = SNAPSHOT_CACHE[cache_key]
+        return cached if cached
+
+        html = run_snapshot(source_path)
+        SNAPSHOT_CACHE[cache_key] = html if html
+        html
+      end
+
+      private
+
+      def snapshot_script_path
+        return @snapshot_script_path if defined?(@snapshot_script_path)
+
+        candidate = File.expand_path("../../../bindings/vscode/scripts/snapshot.js", __dir__)
+        @snapshot_script_path = File.file?(candidate) ? candidate : nil
+      end
+
+      def snapshot_theme_path
+        return @snapshot_theme_path if defined?(@snapshot_theme_path)
+
+        candidate = File.expand_path("../../../bindings/vscode/themes/2026-dark.json", __dir__)
+        @snapshot_theme_path = File.file?(candidate) ? candidate : nil
+      end
+
+      def run_snapshot(source_path)
+        script = snapshot_script_path
+        theme = snapshot_theme_path
+        return nil unless script && theme
+
+        stdout, stderr, status = Open3.capture3("node", script, source_path, "-t", theme)
+
+        unless status.success?
+          warn("snapshot failed for #{source_path}: #{stderr}")
+          return nil
+        end
+
+        stdout
+      end
+
+      private
+
+      def discover_modules
+        mods = []
+        root = stdlib_root
+        return mods unless File.directory?(root)
+
+        dir_names = Dir.glob(File.join(root, "*")).filter_map do |entry|
+          next unless File.directory?(entry)
+          name = File.basename(entry)
+          mts = Dir.glob(File.join(entry, "*.mt"))
+          next if mts.empty?
+          mods << { name:, path: entry, kind: :dir }
+          name
+        end
+
+        Dir.glob(File.join(root, "*.mt")).sort.each do |file|
+          name = File.basename(file, ".mt")
+          next if name.end_with?(".linux", ".windows", ".wasm")
+          next if dir_names.include?(name)
+          mods << { name:, path: file, kind: :file }
+        end
+
+        mods
+      end
+
+      def extract_doc_comment(source)
+        lines = source.lines
+        doc_lines = []
+        in_doc = false
+
+        lines.each do |line|
+          if line.start_with?("##")
+            doc_lines << line.sub(/^## ?/, "").rstrip
+            in_doc = true
+          elsif in_doc && line.strip.empty?
+            break
+          elsif in_doc
+            break
+          end
+        end
+
+        doc_lines.join("\n").strip
+      end
+
+      def extract_declarations(source)
+        decls = []
+        extend_parent = nil
+        extend_indent = nil
+        doc_lines = []
+
+        source.each_line do |line|
+          stripped = line.strip
+          indent = line[/\A */].length
+
+          if stripped.start_with?("##")
+            doc_lines << stripped.sub(/^## ?/, "").rstrip
+            next
+          end
+
+          next if stripped.empty? || stripped.start_with?("#") || stripped.start_with?("import")
+
+          if extend_parent && indent <= extend_indent
+            extend_parent = nil
+            extend_indent = nil
+          end
+
+          kind, name = classify_declaration(stripped)
+
+          unless kind && name
+            doc_lines = []
+            next
+          end
+
+          if kind == "extend"
+            extend_parent = name
+            extend_indent = indent
+            next
+          end
+
+          doc = doc_lines.empty? ? nil : doc_lines.join("\n")
+          doc_lines = []
+
+          if extend_parent && indent > extend_indent
+            decls << { kind:, name:, line: stripped, parent: extend_parent, doc: }
+          else
+            decls << { kind:, name:, line: stripped, doc: }
+          end
+        end
+        decls
+      end
+
+      def classify_declaration(stripped)
+        case stripped
+        when /\A(public\s+)?(?:(?:external|foreign|async|const|static|editable)\s+)*function\s+(\w+)/
+          ["func", $2]
+        when /\A(public\s+)?const\s+(\w+)/
+          ["const", $2]
+        when /\A(public\s+)?struct\s+(\w+)/
+          ["struct", $2]
+        when /\A(public\s+)?enum\s+(\w+)/
+          ["enum", $2]
+        when /\A(public\s+)?flags\s+(\w+)/
+          ["flags", $2]
+        when /\A(public\s+)?variant\s+(\w+)/
+          ["variant", $2]
+        when /\A(public\s+)?union\s+(\w+)/
+          ["union", $2]
+        when /\A(public\s+)?opaque\s+(\w+)/
+          ["opaque", $2]
+        when /\A(public\s+)?type\s+(\w+)/
+          ["type", $2]
+        when /\A(public\s+)?interface\s+(\w+)/
+          ["interface", $2]
+        when /\A(public\s+)?event\s+(\w+)/
+          ["event", $2]
+        when /\Aextending\s+([^\[:\s]+)/
+          ["extend", $1]
+        when /\A(public\s+)?attribute\[/
+          ["attr", stripped[/attribute\[.*?\]\s+(\w+)/, 1]]
+        end
+      end
+
+      def read_module_source(path)
+        File.read(path)
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def module_files(mod)
+        if mod[:kind] == :dir
+          Dir.glob(File.join(mod[:path], "*.mt")).sort.filter_map do |f|
+            basename = File.basename(f, ".mt")
+            next if basename.end_with?(".linux", ".windows", ".wasm")
+            { name: basename, path: f }
+          end
+        else
+          [{ name: mod[:name], path: mod[:path] }]
+        end
+      end
+
+      def resolve_source_path(mod, file_name)
+        if mod[:kind] == :dir
+          candidate = File.join(mod[:path], "#{file_name}.mt")
+          File.file?(candidate) ? candidate : nil
+        elsif file_name == mod[:name]
+          mod[:path]
+        end
+      end
+    end
+
+    # ---- Routes ----
+
+    get "/" do
+      content_type :html
+      File.read(reference_index)
+    end
+
+    get "/reference" do
+      redirect "/reference/"
+    end
+
+    get "/reference/" do
+      content_type :html
+      File.read(reference_index)
+    end
+
+    get "/stdlib" do
+      @breadcrumbs = [["Reference", "/"], ["Standard Library", nil]]
+      @modules = stdlib_modules.map do |mod|
+        primary = if mod[:kind] == :dir
+          File.join(mod[:path], "#{mod[:name]}.mt")
+        else
+          mod[:path]
+        end
+        source = read_module_source(primary)
+        doc = source ? extract_doc_comment(source) : ""
+        decl_count = source ? extract_declarations(source).size : 0
+        mod.merge(doc:, decl_count:)
+      end
+      erb :stdlib
+    end
+
+    get "/stdlib/:name" do
+      @name = params[:name]
+      mod = stdlib_modules.find { |m| m[:name] == @name }
+      halt 404 unless mod
+
+      @breadcrumbs = [["Reference", "/"], ["Standard Library", "/stdlib"], [@name, nil]]
+      @mod = mod
+      @files = module_files(mod).filter_map do |f|
+        source = read_module_source(f[:path])
+        next unless source
+        { name: f[:name], doc: extract_doc_comment(source), decls: extract_declarations(source) }
+      end
+
+      erb :module
+    end
+
+    get "/stdlib/:name/source/:file" do
+      mod = stdlib_modules.find { |m| m[:name] == params[:name] }
+      halt 404 unless mod
+
+      file_path = resolve_source_path(mod, params[:file])
+      halt 404 unless file_path && File.file?(file_path)
+      content_type "text/plain"
+      File.read(file_path)
+    end
+
+    get "/stdlib/:name/source/:file/hl" do
+      mod = stdlib_modules.find { |m| m[:name] == params[:name] }
+      halt 404 unless mod
+
+      file_path = resolve_source_path(mod, params[:file])
+      halt 404 unless file_path && File.file?(file_path)
+
+      html = snapshot_for(file_path)
+      unless html
+        content_type "text/plain"
+        halt 503, "Syntax highlighting unavailable (node.js or snapshot dependencies not found)"
+      end
+
+      content_type :html
+      html
+    end
+
+    get "/api/search" do
+      content_type :json
+      query = (params[:q] || "").downcase.strip
+      return "[]" if query.empty? || query.length < 2
+
+      results = stdlib_modules.filter_map do |mod|
+        next unless mod[:name].downcase.include?(query)
+
+        primary = mod[:kind] == :dir ? File.join(mod[:path], "#{mod[:name]}.mt") : mod[:path]
+        source = read_module_source(primary)
+        doc_line = source ? extract_doc_comment(source).lines.first&.strip : nil
+
+        { name: mod[:name], kind: mod[:kind].to_s, summary: doc_line }
+      end
+      results.to_json
+    end
+
+    error 404 do
+      erb :"404"
+    end
+  end
+end

data/lib/milk_tea/tooling/error_formatter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module MilkTea
+  module ErrorFormatter
+    def self.format(error, path: nil, source: nil, color: true)
+      error_message = error.respond_to?(:message) ? error.message : error.to_s
+      return error_message unless error.respond_to?(:line) && error.line
+      return error_message unless error.respond_to?(:column) && error.column
+
+      path ||= error.respond_to?(:path) ? error.path : nil
+      return error_message unless path
+
+      line = error.line.to_i
+      column = error.column.to_i
+      length = error.respond_to?(:length) ? error.length.to_i : 0
+      severity = error.respond_to?(:severity) ? error.severity : :error
+      code = error.respond_to?(:code) ? error.code : nil
+
+      source ||= read_source(path)
+      return "#{severity_label(severity)}: #{error_message} at #{path}:#{line}:#{column}" unless source
+
+      source_lines = source.split("\n", -1)
+      source_line = source_lines[line - 1] || ""
+      stripped = source_line.gsub(/\t/, " ")
+
+      indent = " " * [column - 1, 0].max
+      highlight = if length && length > 1
+                    "^" + "~" * (length - 1)
+                  else
+                    "^"
+                  end
+
+      bold  = color ? "\e[1m"  : ""
+      red   = color ? "\e[31m" : ""
+      yellow = color ? "\e[33m" : ""
+      cyan  = color ? "\e[36m" : ""
+      reset = color ? "\e[0m"  : ""
+
+      sev_color, sev_text = case severity
+                            when :error   then [red,    "error"]
+                            when :warning then [yellow, "warning"]
+                            when :info    then [cyan,   "info"]
+                            when :hint    then [cyan,   "hint"]
+                            else               [red,    "error"]
+                            end
+
+      code_text = code ? "#{cyan}[#{code}]#{reset}" : ""
+
+      [
+        "#{bold}#{sev_color}#{sev_text}#{code_text}#{reset}: #{error_message}",
+        "  #{bold}-->#{reset} #{path}:#{line}:#{column}",
+        "   #{bold}|#{reset}",
+        "#{line.to_s.rjust(5)} #{bold}|#{reset} #{stripped}",
+        "      #{bold}|#{reset} #{sev_color}#{indent}#{highlight}#{reset}",
+        *error_suggestion_lines(error, color, bold, reset),
+      ].join("\n")
+    end
+
+    def self.error_suggestion_lines(error, color, bold, reset)
+      suggestion = error.respond_to?(:suggestion) ? error.suggestion : nil
+      return [] unless suggestion
+
+      suggestions = suggestion.is_a?(Array) ? suggestion : [suggestion]
+      suggestions.map do |s|
+        label = color ? "#{bold}= help:#{reset}" : "= help:"
+        "  #{label} #{s}"
+      end
+    end
+
+    def self.read_source(path)
+      File.read(path)
+    rescue Errno::ENOENT, Errno::EISDIR
+      nil
+    end
+
+    def self.severity_label(severity)
+      case severity
+      when :error   then "error"
+      when :warning then "warning"
+      when :info    then "info"
+      when :hint    then "hint"
+      else               "error"
+      end
+    end
+  end
+end