@tilua/compiler 1.0.2 → 1.1.0

package/README.md

@@ -168,6 +168,33 @@ needed it; the receiver becomes the call's first argument unless
 `passReceiver: false`. The last library loaded is asked first, and `undefined`
 leaves an ordinary Luau method call.
 
+Hooks also get the call site (`at`) and what the compiler knew about each
+argument (`arguments`: type, the code it was written as, and what a name was
+declared as). An answer can `prepend` Luau expressions ahead of the written
+arguments. `globalCall` and `globalValue` answer for a global, such as
+`print(x)` or a bare `print`. A runtime can read `__LINES__` to reach the
+bundle's line map. See the `@tilua/parser` README for the details.
+`console:log` is not built into the compiler: `@tilua-types/lua` implements it
+with these hooks.
+
+## Errors at runtime
+
+A bundle is one Luau file, so a position Luau reports names a line of that
+file. The entry therefore runs under `xpcall`. If an error reaches the top,
+its message is rewritten from bundle lines to the places in the project that
+wrote them, a traceback of those places is added, and the error is raised
+again:
+
+```
+src/util.tilua:3: attempt to index nil with 'value'
+    at src/util.tilua:3 (boom)
+    at src/main.tilua:3 (load)
+```
+
+A message that is not a string is raised unchanged. A position that is already
+in the project's files, such as one from `error` in `@tilua-types/lua`, is
+left as it is.
+
 ## Modules
 
 Roblox's `require` takes an Instance, so the bundle has its own. Each module

package/dist/{chunk-QSRDDIU4.js → chunk-2IPPO4V3.js}

@@ -11,7 +11,7 @@ function resolveConfig(input, entry, cwd = process.cwd()) {
 
 // src/lower.ts
 import { formatType } from "@tilua/parser";
-import { parse as parseLuau } from "luau-parser";
+import { parse as parseLuau, parseExpressionFromSource } from "luau-parser";
 
 // src/luau.ts
 var NO_SPAN = { line: { start: 0, end: 0 }, column: { start: 0, end: 0 } };
@@ -101,144 +101,6 @@ function isLuauName(name) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !LUAU_KEYWORDS.has(name);
 }
 
-// src/console.ts
-var CONSOLE_RUNTIME = `
-local __NAME__ = (function()
-    local console = {}
-    local MAX_DEPTH = 4
-    local ESCAPES = { ["\\n"] = "\\\\n", ["\\r"] = "\\\\r", ["\\t"] = "\\\\t", ["\\""] = "\\\\\\"", ["\\\\"] = "\\\\\\\\" }
-
-    local function quote(text)
-        return '"' .. text:gsub('[%c"\\\\]', function(c) return ESCAPES[c] or ("\\\\%d"):format(c:byte()) end) .. '"'
-    end
-
-    -- A table with 1..n and nothing else prints as a list, as it was written.
-    local function isArray(value)
-        local count = 0
-        for key in pairs(value) do
-            if type(key) ~= "number" then return false end
-            count = count + 1
-        end
-        return count == #value
-    end
-
-    local function isIdentifier(key)
-        return type(key) == "string" and key:match("^[A-Za-z_][A-Za-z0-9_]*$") ~= nil
-    end
-
-    local render
-
-    local function renderTable(value, meta, seen, depth, indent)
-        if seen[value] then return "<cycle>" end
-        if depth > MAX_DEPTH then return "..." end
-        seen[value] = true
-        local inner = indent .. "  "
-        local parts = {}
-        if isArray(value) then
-            for i = 1, #value do
-                parts[#parts + 1] = inner .. render(value[i], nil, seen, depth + 1, inner)
-            end
-        else
-            local keys = {}
-            for key in pairs(value) do keys[#keys + 1] = key end
-            table.sort(keys, function(a, b) return tostring(a) < tostring(b) end)
-            for _, key in ipairs(keys) do
-                local name = isIdentifier(key) and key or ("[" .. render(key, nil, seen, depth + 1, inner) .. "]")
-                parts[#parts + 1] = inner .. name .. " = " .. render(value[key], nil, seen, depth + 1, inner)
-            end
-        end
-        seen[value] = nil
-        if #parts == 0 then return "{}" end
-        local open = isArray(value) and "[" or "{"
-        local close = isArray(value) and "]" or "}"
-        return open .. "\\n" .. table.concat(parts, ",\\n") .. "\\n" .. indent .. close
-    end
-
-    -- \`meta\` is what the compiler knew about this value and the runtime cannot:
-    -- a function's type, and the code it was written as.
-    render = function(value, meta, seen, depth, indent)
-        local kind = type(value)
-        if kind == "string" then return quote(value) end
-        if kind == "number" or kind == "boolean" or kind == "nil" then return tostring(value) end
-        if kind == "function" then
-            if meta == nil then return "function" end
-            if meta[2] == nil or meta[2] == "" then return meta[1] end
-            return meta[1] .. "  " .. meta[2]
-        end
-        if kind == "table" then
-            local shown = rawget(value, "__tostring") == nil and getmetatable(value)
-            -- A value with its own \`__tostring\` (a Roblox Vector3, a class
-            -- instance that says how it reads) is trusted to describe itself.
-            if shown ~= nil and rawget(shown, "__tostring") ~= nil then return tostring(value) end
-            return renderTable(value, meta, seen, depth, indent)
-        end
-        return tostring(value)
-    end
-
-    local function describe(meta, index, value)
-        return render(value, meta ~= nil and meta[index] or nil, {}, 1, "")
-    end
-
-    local function join(meta, count, ...)
-        local parts = {}
-        for i = 1, count do
-            parts[#parts + 1] = describe(meta, i, (select(i, ...)))
-        end
-        return table.concat(parts, " ")
-    end
-
-    -- A line of the bundle, as the place in the project that wrote it.
-    local lines = __LINES__
-    local function place(line)
-        local origin = lines ~= nil and lines[tonumber(line)]
-        if origin == nil then return nil end
-        return origin[1] .. ":" .. tostring(origin[2])
-    end
-
-    -- Luau names the bundle in every frame; the project's files are what the
-    -- reader knows. Frames the map has nothing for are dropped: they are this
-    -- runtime's own, and the bundle's.
-    local function trace(level)
-        local raw = debug.traceback(nil, level)
-        local out = {}
-        for frame in raw:gmatch("[^\\n]+") do
-            local line = frame:match(":(%d+)")
-            local at = line ~= nil and place(line) or nil
-            if at ~= nil then
-                local name = frame:match("function ([%w_.:]+)")
-                out[#out + 1] = "    at " .. at .. (name ~= nil and (" (" .. name .. ")") or "")
-            end
-        end
-        return table.concat(out, "\\n")
-    end
-
-    -- Never on the caller's thread: reporting a problem must not become one.
-    local detach = (task ~= nil and task.spawn) or function(f) return f() end
-
-    local function raise(prefix, meta, count, ...)
-        local message = prefix .. join(meta, count, ...)
-        local where = trace(3)
-        detach(function()
-            error(where ~= "" and (message .. "\\n" .. where) or message, 0)
-        end)
-    end
-
-    function console.log(meta, ...)
-        print(join(meta, select("#", ...), ...))
-    end
-
-    function console.warn(meta, ...)
-        raise("[warn] ", meta, select("#", ...), ...)
-    end
-
-    function console.error(meta, ...)
-        raise("", meta, select("#", ...), ...)
-    end
-
-    return console
-end)()
-`;
-
 // src/names.ts
 var Names = class _Names {
   constructor(taken) {
@@ -386,60 +248,9 @@ var Lowerer = class {
   }
   loweringNames = /* @__PURE__ */ new Map();
   loweringUsed = [];
-  /** What a library says `receiver:method(...)` is. The last library
-   *  loaded is asked first, so a project's own library can answer for a
-   *  method an earlier one also claims; no answer leaves an ordinary Luau
-   *  method call, which is what a value that answers to the method itself
-   *  wants (`text:upper()`). */
-  /** `console:log(a, f)` and its two siblings.
-   *
-   *  Handled here rather than through a library's lowering because what they
-   *  need is not a different callee but *more than was written*: a function
-   *  prints as its type and its code, and neither survives to runtime. The
-   *  compiler is the only thing that has both, so it passes them along:
-   *
-   *      console:log(a, double)
-   *      -- becomes
-   *      tilua_console.log({ [2] = { "(x: number) => number", "(x: number) => x * 2" } }, a, double)
-   *
-   *  The meta table is `nil` when nothing was worth saying, which is most
-   *  calls. `console` itself is never passed: it holds nothing. */
-  consoleCall(node) {
-    if (node.object.type !== "Identifier" || node.object.name !== "console") return void 0;
-    const method = node.method.name;
-    if (method !== "log" && method !== "warn" && method !== "error") return void 0;
-    const binding = this.scopes.bindingOf.get(node.object);
-    if (binding !== void 0 && this.scopes.bindings.get(binding)?.kind !== "global") return void 0;
-    const meta = this.consoleMeta(node.arguments);
-    return call(
-      member(this.helper("console"), method),
-      [meta ?? nil(), ...this.values(node.arguments)]
-    );
-  }
-  /** What the compiler knows about the arguments and the runtime cannot:
-   *  for each function argument, the type it was inferred as and the code it
-   *  was written as. Keyed by position, so an argument that needs nothing
-   *  costs nothing. */
-  consoleMeta(args) {
-    const fields = [];
-    args.forEach((argument, index2) => {
-      const type = this.options.types?.typeOf.get(argument);
-      if (!type || !isFunctionType(type)) return;
-      const written = this.writtenSource(this.declarationOf(argument) ?? argument);
-      fields.push({
-        type: "TableFieldComputed",
-        key: number(index2 + 1),
-        value: table([
-          { type: "TableFieldPositional", value: string(formatType(type)) },
-          { type: "TableFieldPositional", value: string(written) }
-        ])
-      });
-    });
-    return fields.length ? table(fields) : void 0;
-  }
   /** What a name was declared as: the value of `const f = ...`, or the whole
-   *  `function f() { ... }`. Built once, on the first `console` call that
-   *  needs it — most files have none. */
+   *  `function f() { ... }`. Built once, on the first call a library asks
+   *  about — most files have none. */
   declarationOf(argument) {
     if (argument.type !== "Identifier") return void 0;
     if (!this.declarations) {
@@ -478,21 +289,127 @@ var Lowerer = class {
     const trim = (line) => line.startsWith(indent) ? line.slice(indent.length) : line;
     return [first, ...middle.map(trim), trim(last)].join("\n");
   }
+  /** Where `node` was written, as a library is told it. */
+  callSite(node) {
+    return { file: this.options.file, line: node.line.start, column: node.column.start };
+  }
+  /** What the compiler knows about each argument and the runtime cannot:
+   *  its type, and the code it — or what it names — was written as. Built
+   *  only if a library reads it. */
+  argumentInfo(args) {
+    return args.map((argument) => {
+      const declaration = this.declarationOf(argument);
+      const type = this.options.types?.typeOf.get(argument);
+      return {
+        type,
+        typeText: type ? formatType(type) : void 0,
+        source: this.writtenSource(argument),
+        declaration: declaration ? this.writtenSource(declaration) : void 0,
+        spread: argument.type === "SpreadElement"
+      };
+    });
+  }
+  /** The name a global is read by at `node`, or `undefined` when `node` is
+   *  not a global — a local of the same name is the author's. */
+  globalName(node) {
+    if (node.type !== "Identifier") return void 0;
+    const id = this.scopes.bindingOf.get(node);
+    if (id === void 0) return node.name;
+    return this.scopes.bindings.get(id)?.kind === "global" ? node.name : void 0;
+  }
+  /** What a library says `receiver:method(...)` is. The last library
+   *  loaded is asked first, so a project's own library can answer for a
+   *  method an earlier one also claims; no answer leaves an ordinary Luau
+   *  method call, which is what a value that answers to the method itself
+   *  wants (`text:upper()`). */
   loweredMethodCall(node) {
     const lowerings = this.options.lowerings;
-    if (!lowerings?.length) return void 0;
+    if (!lowerings?.some((l) => l.plugin.methodCall)) return void 0;
     const receiver = this.options.types?.typeOf.get(node.object);
+    const receiverGlobal = this.globalName(node.object);
+    const info = this.lazyArguments(node.arguments);
     for (let i = lowerings.length - 1; i >= 0; i--) {
-      const answer = lowerings[i].plugin.methodCall?.({
+      const plugin = lowerings[i].plugin;
+      if (!plugin.methodCall) continue;
+      const answer = plugin.methodCall({
         method: node.method.name,
         receiver,
+        receiverGlobal,
         argumentCount: node.arguments.length,
+        at: this.callSite(node.method),
+        get arguments() {
+          return info();
+        },
         use: (runtime2) => this.loweringRuntime(i, runtime2)
       });
-      if (answer) return { callee: answer.callee, passReceiver: answer.passReceiver !== false };
+      if (answer) {
+        return {
+          callee: answer.callee,
+          prepend: this.prepended(answer.prepend, i, node),
+          passReceiver: answer.passReceiver !== false
+        };
+      }
     }
     return void 0;
   }
+  /** What a library says a call to a global — `print(x)` — is. */
+  loweredGlobalCall(node) {
+    const lowerings = this.options.lowerings;
+    if (!lowerings?.some((l) => l.plugin.globalCall)) return void 0;
+    const name = this.globalName(node.callee);
+    if (name === void 0) return void 0;
+    const info = this.lazyArguments(node.arguments);
+    for (let i = lowerings.length - 1; i >= 0; i--) {
+      const plugin = lowerings[i].plugin;
+      if (!plugin.globalCall) continue;
+      const answer = plugin.globalCall({
+        name,
+        at: this.callSite(node.callee),
+        get arguments() {
+          return info();
+        },
+        use: (runtime2) => this.loweringRuntime(i, runtime2)
+      });
+      if (answer) return { callee: answer.callee, prepend: this.prepended(answer.prepend, i, node) };
+    }
+    return void 0;
+  }
+  /** What a library says a global read as a value — `local p = print` — is. */
+  loweredGlobalValue(node) {
+    const lowerings = this.options.lowerings;
+    if (!lowerings?.some((l) => l.plugin.globalValue)) return void 0;
+    const name = this.globalName(node);
+    if (name === void 0) return void 0;
+    for (let i = lowerings.length - 1; i >= 0; i--) {
+      const answer = lowerings[i].plugin.globalValue?.({
+        name,
+        at: this.callSite(node),
+        use: (runtime2) => this.loweringRuntime(i, runtime2)
+      });
+      if (answer !== void 0) return this.libraryExpression(answer, i, node);
+    }
+    return void 0;
+  }
+  lazyArguments(args) {
+    let info;
+    return () => info ??= this.argumentInfo(args);
+  }
+  prepended(sources, index2, node) {
+    return (sources ?? []).flatMap((source) => {
+      const expression = this.libraryExpression(source, index2, node);
+      return expression ? [expression] : [];
+    });
+  }
+  /** Luau a library wrote as an expression. One that does not parse is the
+   *  library's mistake, reported at the call it was written for. */
+  libraryExpression(source, index2, node) {
+    try {
+      return parseExpressionFromSource(source);
+    } catch (error) {
+      this.report(node, `'${this.options.lowerings[index2].from}' lowered this to Luau that does not parse: ${JSON.stringify(source)} (${error.message})`);
+      return void 0;
+    }
+  }
   helperDefinitions() {
     const out = [];
     const assign2 = this.helpers.get("assign");
@@ -520,12 +437,9 @@ var Lowerer = class {
         });
         continue;
       }
-      out.push(...parseLuau(source.replace(/__NAME__/g, name)).body.statements);
-    }
-    const console = this.helpers.get("console");
-    if (console) {
       const lines = this.options.module?.lines ?? "nil";
-      out.push(...parseLuau(CONSOLE_RUNTIME.replace(/__NAME__/g, console).replace(/__LINES__/g, lines)).body.statements);
+      const fail = this.options.module?.fail ?? "nil";
+      out.push(...parseLuau(source.replace(/__NAME__/g, name).replace(/__LINES__/g, lines).replace(/__FAIL__/g, fail)).body.statements);
     }
     const concat = this.helpers.get("concat");
     if (concat) {
@@ -1383,7 +1297,7 @@ end
     }
     switch (node.type) {
       case "Identifier":
-        return this.reference(node);
+        return this.loweredGlobalValue(node) ?? this.reference(node);
       case "NilLiteral":
         return nil();
       case "BooleanLiteral":
@@ -1432,7 +1346,11 @@ end
       case "MethodCallExpression": {
         const chain = optionalChain(node);
         if (chain) return this.optionalChainExpression(chain);
-        return this.link(node, this.expression(linkObject(node)));
+        const object = linkObject(node);
+        if (node.type === "CallExpression" && object.type === "Identifier") {
+          return this.link(node, this.reference(object));
+        }
+        return this.link(node, this.expression(object));
       }
       case "ParenthesizedExpression":
         return parenthesized(this.expression(node.expression));
@@ -1477,15 +1395,21 @@ end
         return member(object, node.property.name);
       case "IndexExpression":
         return index(object, this.expression(node.index));
-      case "CallExpression":
-        return call(object, this.values(node.arguments));
-      case "MethodCallExpression": {
-        const consoleCall = this.consoleCall(node);
-        if (consoleCall) return consoleCall;
+      case "CallExpression": {
+        const lowered = this.loweredGlobalCall(node);
         const args = this.values(node.arguments);
+        if (lowered) return call(calleePath(lowered.callee), [...lowered.prepend, ...args]);
+        return call(object, args);
+      }
+      case "MethodCallExpression": {
         const lowered = this.loweredMethodCall(node);
+        const args = this.values(node.arguments);
         if (lowered) {
-          return call(calleePath(lowered.callee), lowered.passReceiver ? [object, ...args] : args);
+          return call(calleePath(lowered.callee), [
+            ...lowered.prepend,
+            ...lowered.passReceiver ? [object] : [],
+            ...args
+          ]);
         }
         if (!isLuauName(node.method.name)) {
           this.report(node.method, `'${node.method.name}' is a Luau keyword and cannot be called with ':'`);
@@ -1898,10 +1822,6 @@ function mentions(expression, name) {
   walk(expression);
   return found;
 }
-function isFunctionType(type) {
-  if (type.kind === "function") return true;
-  return type.kind === "intersection" && type.types.some((t) => t.kind === "function");
-}
 function allNodes(root) {
   const out = [];
   const visit = (value) => {
@@ -1960,7 +1880,7 @@ import {
   ParseError,
   LexError
 } from "@tilua/parser";
-import { parse as parseLuau2, parseExpressionFromSource, print } from "luau-parser";
+import { parse as parseLuau2, parseExpressionFromSource as parseExpressionFromSource2, print } from "luau-parser";
 
 // src/linemap.ts
 function statementsOf(node) {
@@ -2043,16 +1963,19 @@ async function bundle(options) {
     const file = pending.shift();
     if (modules.has(file)) continue;
     const source = sources.get(file);
+    const shown = relative(root, file).replace(/\\/g, "/");
     const lowered = lower(source.program, source.scopes, {
       names,
       types: analysis.types.get(file),
       lowerings,
       target: options.target ?? config?.target,
       source: source.text,
+      file: shown,
       module: {
         name: source.name,
         require: requireExpression,
         lines: `${G}.lines`,
+        fail: `${G}.fail`,
         resolve: (specifier) => {
           const target = resolveModulePath(file, specifier, config);
           if (!target || target.endsWith(".d.tilua") || !sources.has(target)) return void 0;
@@ -2062,7 +1985,6 @@ async function bundle(options) {
       }
     });
     for (const d of lowered.diagnostics) diagnostics.push({ file, ...d, category: "module" });
-    const shown = relative(root, file).replace(/\\/g, "/");
     for (const statement of allStatements(lowered.statements)) {
       const line = lowered.origins.get(statement);
       if (line !== void 0) origins.set(statement, { file: shown, line });
@@ -2112,13 +2034,23 @@ async function bundle(options) {
     fields.push(field("load", functionExpression(functionBody([module.exportsName], module.statements, true))));
     modulesTable.fields.push({ type: "TableFieldComputed", key: string(module.name), value: table(fields) });
   }
-  const start = call(requireExpression, [string(sources.get(entry).name)]);
-  program2.body.statements.push(modules.get(entry).info.exports ? returns([start]) : callStatement(start));
+  const ok = names.fresh("ok");
+  const result = names.fresh("result");
+  const entryStatements = parseLuau2(`
+local ${ok}, ${result} = xpcall(function()
+    return ${G}.require(${JSON.stringify(sources.get(entry).name)})
+end, ${G}.fail)
+if not ${ok} then
+    error(${result}, 0)
+end
+${modules.get(entry).info.exports ? `return ${result}` : ""}
+`).body.statements;
+  program2.body.statements.push(...entryStatements);
   const map = buildLineMap(program2, parseLuau2(print(program2)), origins);
   if (map.size) {
-    program2.body.statements.splice(program2.body.statements.length - 1, 0, assign(
+    program2.body.statements.splice(program2.body.statements.length - entryStatements.length, 0, assign(
       [member(identifier(G), "lines")],
-      [parseExpressionFromSource(lineMapSource(map))]
+      [parseExpressionFromSource2(lineMapSource(map))]
     ));
   }
   return { code: print(program2) + "\n", modules: moduleNames, diagnostics };
@@ -2128,6 +2060,52 @@ function runtime(G) {
 local ${G}
 ${G} = {
     modules = {},
+    -- Filled in just before the entry runs: bundle line -> { file, line }.
+    lines = nil,
+    -- What an error nothing caught says, in the project's files: the bundle's
+    -- own positions in the message are replaced by the places they came from,
+    -- and a traceback of those places follows. A message that is not a string
+    -- is left as it is, and a position that is not this bundle's (a library
+    -- that raised its error with one already mapped) is left alone.
+    fail = function(message)
+        if type(message) ~= "string" then
+            return message
+        end
+        local lines = ${G}.lines
+        if lines == nil then
+            return debug.traceback(message, 2)
+        end
+        local chunk
+        if debug.info ~= nil then
+            chunk = debug.info(1, "s")
+        else
+            chunk = debug.getinfo(1, "S").short_src
+        end
+        local prefix = chunk:gsub("%p", "%%%0")
+        local function place(line)
+            local origin = lines[tonumber(line)]
+            if origin == nil then
+                return nil
+            end
+            return origin[1] .. ":" .. tostring(origin[2])
+        end
+        local mapped = message:gsub(prefix .. ":(%d+)", function(line)
+            return place(line)
+        end)
+        local frames = {}
+        for frame in debug.traceback("", 2):gmatch("[^\\n]+") do
+            local line = frame:match(prefix .. ":(%d+)")
+            local at = line ~= nil and place(line) or nil
+            if at ~= nil then
+                local name = frame:match("function ([%w_.:]+)")
+                frames[#frames + 1] = "    at " .. at .. (name ~= nil and (" (" .. name .. ")") or "")
+            end
+        end
+        if #frames == 0 then
+            return mapped
+        end
+        return mapped .. "\\n" .. table.concat(frames, "\\n")
+    end,
     records = {},
     require = function(name)
         local record = ${G}.records[name]