@tilua/compiler 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,233 @@
+import * as T from '@tilua/parser';
+import { LoweringPlugin, BuildTarget, TypeAnalysis, ScopeAnalysis, TiluaConfig, ConfigProblem } from '@tilua/parser';
+export { LoweringPlugin, MethodCall, MethodLowering } from '@tilua/parser';
+import * as L from 'luau-parser';
+
+/**
+ * Fresh local names for what lowering introduces — a destructuring temporary,
+ * a required module, a helper function.
+ *
+ * A generated name must not capture or shadow anything the source means, so
+ * every name the file mentions anywhere is taken up front. A name is only
+ * reused by coincidence of a different spelling, never by accident.
+ */
+
+declare class Names {
+    private readonly taken;
+    private constructor();
+    /** The names `programs` mention — a bundle takes every module's, so that
+     *  a name shared across modules (the module table) collides with none. */
+    static from(...programs: T.Program[]): Names;
+    /** A copy that goes on to take names independently — one per module, each
+     *  starting from what the whole bundle already takes. */
+    fork(): Names;
+    /** `base`, or `base2`, `base3`, ... — whichever is free first. */
+    fresh(base: string): string;
+}
+
+interface LoadedLowering {
+    readonly plugin: LoweringPlugin;
+    /** The package it came from, for reporting. */
+    readonly from: string;
+}
+interface LoweringProblem {
+    readonly file: string;
+    readonly message: string;
+}
+/** Load what the project's type libraries lower. A module that will not load,
+ *  or exports the wrong shape, is reported and skipped: the rest of the build
+ *  is still worth having. */
+declare function loadLowerings(modules: readonly {
+    file: string;
+    from: string;
+}[]): Promise<{
+    lowerings: LoadedLowering[];
+    problems: LoweringProblem[];
+}>;
+
+/**
+ * tilua AST -> Luau AST.
+ *
+ * Everything tilua adds over Luau is rewritten into plain Luau here; the
+ * result is an ordinary luau-parser tree, printed by luau-parser's printer.
+ *
+ *   const { a, b } = value          local a, b = value.a, value.b
+ *   const [x, y] = list             local x, y = list[1], list[2]
+ *   { name: "n", count }            { name = "n", count = count }
+ *   [...xs, 1]                      concat(xs, { 1 })
+ *   `${a} any`                      ("%s any"):format(tostring(a))
+ *   function f(n = 1) ... end       function f(n) if n == nil then n = 1 end ... end
+ *   x as T / x satisfies T          x
+ *
+ * Types have no runtime meaning, so every annotation, alias and `declare` is
+ * dropped: the output is untyped Luau.
+ *
+ * ## Modules
+ *
+ * In a bundle each file becomes a function that fills in its `exports` table
+ * (see `bundle.ts`), and modules behave the way ES modules do:
+ *
+ *   - **Live bindings.** An exported binding lives on `exports` itself, so
+ *     every read and write of it goes through `exports.name`. An imported name
+ *     is read through the imported module's table (`util.clamp`), never
+ *     copied — a value the other module sets later is still seen.
+ *   - **Hoisting.** Every top-level name is declared before any code runs, and
+ *     every top-level function is defined then too, ahead of the imports. In a
+ *     cycle — `a` imports `b`, which imports `a` while `a` is still loading —
+ *     `b` receives `a`'s partly filled table, and can already call its
+ *     functions.
+ */
+
+/** What lowering a file as a module of a bundle needs. */
+interface ModuleContext {
+    /** The bundle's name for this module. */
+    readonly name: string;
+    /** The bundle's name for the module `specifier` imports, or `undefined`
+     *  when there is no such module (reported). */
+    resolve(specifier: string): string | undefined;
+    /** The bundle's `require`: an expression that, called with a module's
+     *  name, returns its exports table. */
+    readonly require: L.Expression;
+    /** Luau reaching the bundle's line map — what `console:error` reads to
+     *  name the file a frame was written in. */
+    readonly lines?: string;
+}
+interface LowerOptions {
+    /** Lower the file as a module of a bundle. Without it, `import` and
+     *  `export` are errors. */
+    readonly module?: ModuleContext;
+    /** Names already taken beyond the file's own — a bundle's. */
+    readonly names?: Names;
+    /** The file's types. They decide what `for x in t` means: over a table
+     *  it yields the values, which in Luau needs a key variable before `x`.
+     *  They also say what a method call is called on, which decides whether
+     *  `methods` claims it. */
+    readonly types?: TypeAnalysis;
+    /** What the project's type libraries lower, already loaded (see
+     *  `loadLowerings`). The compiler lowers the language; a call written
+     *  against a library's types is the library's to explain. */
+    readonly lowerings?: readonly LoadedLowering[];
+    /** The file's own text, so `console:log` can show a function as the code it
+     *  was written as. Without it a function shows only its type. */
+    readonly source?: string;
+    /** Which Lua the output has to run on. Default `"luau"`. `"lua51"` also
+     *  lowers what Luau adds to Lua and 5.1 has no syntax for — `a += b`,
+     *  `continue`, `if c then a else b` as an expression, `//`. */
+    readonly target?: Target;
+}
+/** `"luau"` is Roblox's Lua. `"lua51"` is stock Lua 5.1, which has none of
+ *  Luau's additions — and no `goto` either, so `continue` has to be built out
+ *  of the loops 5.1 does have. */
+type Target = BuildTarget;
+interface LowerDiagnostic {
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+}
+interface LowerResult {
+    readonly statements: L.Statement[];
+    /** In a module: the parameter the statements fill in with the exports. */
+    readonly exportsName: string;
+    /** In a module: what the bundle's `require` needs to know about it. */
+    readonly module: ModuleInfo;
+    readonly diagnostics: LowerDiagnostic[];
+    /** The line of the *source* file each emitted statement came from. With the
+     *  file it was lowered from, this is what turns a line of the bundle back
+     *  into a place someone can open. */
+    readonly origins: WeakMap<L.Statement, number>;
+}
+/** How a module's exports behave at runtime, beyond what its code assigns. */
+interface ModuleInfo {
+    /** Names the module itself exports. Reading one before the module has
+     *  initialized it is an error, as in ES modules. */
+    readonly names: string[];
+    /** Names re-exported from another module — `export { x as y } from` —
+     *  read from that module on every access, so they stay live.
+     *  `imported` is `undefined` for the whole module (`import * as M; export { M }`). */
+    readonly links: {
+        name: string;
+        module: string;
+        imported?: string;
+    }[];
+    /** `export * from` modules, consulted live for any other name. */
+    readonly stars: string[];
+    /** Whether the module exports anything. */
+    exports: boolean;
+}
+declare function lower(program: T.Program, scopes: ScopeAnalysis, options?: LowerOptions): LowerResult;
+
+/** What `tilua.config.json` holds. */
+interface TiluaConfigJson {
+    /** Type libraries to check against: `["roblox"]` loads `@tilua-types/roblox`. */
+    types?: string[];
+    /** Import path aliases, as in tsconfig: `{ "@shared/*": ["src/shared/*"] }`. */
+    paths?: Record<string, string[]>;
+    /** Where `paths` targets resolve from. Default: the config's folder. */
+    baseUrl?: string;
+    /** A Rojo sourcemap, or `null`. */
+    sourceMap?: string | null;
+    /** Which Lua the output must run on. `"luau"` (the default) keeps Luau's
+     *  own syntax; `"lua51"` also lowers what stock Lua 5.1 cannot parse —
+     *  `a += b`, `continue`, `if c then a else b` as an expression, `//`,
+     *  digit separators and binary literals. */
+    target?: Target;
+}
+/** A config file's path, or the config itself. Relative paths — to a config
+ *  file, and inside an inline config — resolve from `cwd`. */
+type ConfigInput = string | TiluaConfigJson;
+interface ResolvedConfig {
+    readonly config?: TiluaConfig;
+    readonly problems: readonly ConfigProblem[];
+}
+/** The config for a build of `entry`: the one given, or else the nearest
+ *  `tilua.config.json` above the entry. */
+declare function resolveConfig(input: ConfigInput | undefined, entry: string, cwd?: string): ResolvedConfig;
+
+interface BundleOptions {
+    /** The file the bundle runs. */
+    readonly entry: string;
+    /** A `tilua.config.json` path or contents. Default: the nearest config above the entry. */
+    readonly config?: ConfigInput;
+    /** The project folder. Modules are named by their path from it, and an
+     *  inline config's relative paths resolve from it. Default: the config
+     *  file's folder, or else the entry's. */
+    readonly root?: string;
+    /** Check types against the config's `types` too. Default: true. */
+    readonly typeCheck?: boolean;
+    /** Which Lua the output must run on. Overrides the config's `target`. */
+    readonly target?: Target;
+}
+interface BundleDiagnostic {
+    /** Absolute path of the file it is about. */
+    readonly file: string;
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+    /** `type` and `config` problems are reported without stopping the build;
+     *  `syntax`, `scope` (such as assigning to an import) and `module`
+     *  problems leave no bundle. */
+    readonly category: "syntax" | "scope" | "module" | "type" | "config";
+}
+interface BundleResult {
+    /** The bundle, or `undefined` when a module could not be compiled. Type
+     *  errors are reported but do not stop it. */
+    readonly code?: string;
+    /** The bundled modules' names, entry first. */
+    readonly modules: string[];
+    readonly diagnostics: BundleDiagnostic[];
+}
+declare function bundle(options: BundleOptions): Promise<BundleResult>;
+
+interface Diagnostic {
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+}
+interface CompileResult {
+    /** The Luau source, or `undefined` when the file has errors. */
+    readonly code?: string;
+    readonly diagnostics: Diagnostic[];
+}
+declare function compile(source: string, config?: ConfigInput): Promise<CompileResult>;
+
+export { type BundleDiagnostic, type BundleOptions, type BundleResult, type CompileResult, type ConfigInput, type Diagnostic, type LoadedLowering, type LowerDiagnostic, type LowerOptions, type LowerResult, type LoweringProblem, type ModuleContext, type ResolvedConfig, type TiluaConfigJson, bundle, compile, loadLowerings, lower, resolveConfig };

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import * as T from '@tilua/parser';
+import { LoweringPlugin, BuildTarget, TypeAnalysis, ScopeAnalysis, TiluaConfig, ConfigProblem } from '@tilua/parser';
+export { LoweringPlugin, MethodCall, MethodLowering } from '@tilua/parser';
+import * as L from 'luau-parser';
+
+/**
+ * Fresh local names for what lowering introduces — a destructuring temporary,
+ * a required module, a helper function.
+ *
+ * A generated name must not capture or shadow anything the source means, so
+ * every name the file mentions anywhere is taken up front. A name is only
+ * reused by coincidence of a different spelling, never by accident.
+ */
+
+declare class Names {
+    private readonly taken;
+    private constructor();
+    /** The names `programs` mention — a bundle takes every module's, so that
+     *  a name shared across modules (the module table) collides with none. */
+    static from(...programs: T.Program[]): Names;
+    /** A copy that goes on to take names independently — one per module, each
+     *  starting from what the whole bundle already takes. */
+    fork(): Names;
+    /** `base`, or `base2`, `base3`, ... — whichever is free first. */
+    fresh(base: string): string;
+}
+
+interface LoadedLowering {
+    readonly plugin: LoweringPlugin;
+    /** The package it came from, for reporting. */
+    readonly from: string;
+}
+interface LoweringProblem {
+    readonly file: string;
+    readonly message: string;
+}
+/** Load what the project's type libraries lower. A module that will not load,
+ *  or exports the wrong shape, is reported and skipped: the rest of the build
+ *  is still worth having. */
+declare function loadLowerings(modules: readonly {
+    file: string;
+    from: string;
+}[]): Promise<{
+    lowerings: LoadedLowering[];
+    problems: LoweringProblem[];
+}>;
+
+/**
+ * tilua AST -> Luau AST.
+ *
+ * Everything tilua adds over Luau is rewritten into plain Luau here; the
+ * result is an ordinary luau-parser tree, printed by luau-parser's printer.
+ *
+ *   const { a, b } = value          local a, b = value.a, value.b
+ *   const [x, y] = list             local x, y = list[1], list[2]
+ *   { name: "n", count }            { name = "n", count = count }
+ *   [...xs, 1]                      concat(xs, { 1 })
+ *   `${a} any`                      ("%s any"):format(tostring(a))
+ *   function f(n = 1) ... end       function f(n) if n == nil then n = 1 end ... end
+ *   x as T / x satisfies T          x
+ *
+ * Types have no runtime meaning, so every annotation, alias and `declare` is
+ * dropped: the output is untyped Luau.
+ *
+ * ## Modules
+ *
+ * In a bundle each file becomes a function that fills in its `exports` table
+ * (see `bundle.ts`), and modules behave the way ES modules do:
+ *
+ *   - **Live bindings.** An exported binding lives on `exports` itself, so
+ *     every read and write of it goes through `exports.name`. An imported name
+ *     is read through the imported module's table (`util.clamp`), never
+ *     copied — a value the other module sets later is still seen.
+ *   - **Hoisting.** Every top-level name is declared before any code runs, and
+ *     every top-level function is defined then too, ahead of the imports. In a
+ *     cycle — `a` imports `b`, which imports `a` while `a` is still loading —
+ *     `b` receives `a`'s partly filled table, and can already call its
+ *     functions.
+ */
+
+/** What lowering a file as a module of a bundle needs. */
+interface ModuleContext {
+    /** The bundle's name for this module. */
+    readonly name: string;
+    /** The bundle's name for the module `specifier` imports, or `undefined`
+     *  when there is no such module (reported). */
+    resolve(specifier: string): string | undefined;
+    /** The bundle's `require`: an expression that, called with a module's
+     *  name, returns its exports table. */
+    readonly require: L.Expression;
+    /** Luau reaching the bundle's line map — what `console:error` reads to
+     *  name the file a frame was written in. */
+    readonly lines?: string;
+}
+interface LowerOptions {
+    /** Lower the file as a module of a bundle. Without it, `import` and
+     *  `export` are errors. */
+    readonly module?: ModuleContext;
+    /** Names already taken beyond the file's own — a bundle's. */
+    readonly names?: Names;
+    /** The file's types. They decide what `for x in t` means: over a table
+     *  it yields the values, which in Luau needs a key variable before `x`.
+     *  They also say what a method call is called on, which decides whether
+     *  `methods` claims it. */
+    readonly types?: TypeAnalysis;
+    /** What the project's type libraries lower, already loaded (see
+     *  `loadLowerings`). The compiler lowers the language; a call written
+     *  against a library's types is the library's to explain. */
+    readonly lowerings?: readonly LoadedLowering[];
+    /** The file's own text, so `console:log` can show a function as the code it
+     *  was written as. Without it a function shows only its type. */
+    readonly source?: string;
+    /** Which Lua the output has to run on. Default `"luau"`. `"lua51"` also
+     *  lowers what Luau adds to Lua and 5.1 has no syntax for — `a += b`,
+     *  `continue`, `if c then a else b` as an expression, `//`. */
+    readonly target?: Target;
+}
+/** `"luau"` is Roblox's Lua. `"lua51"` is stock Lua 5.1, which has none of
+ *  Luau's additions — and no `goto` either, so `continue` has to be built out
+ *  of the loops 5.1 does have. */
+type Target = BuildTarget;
+interface LowerDiagnostic {
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+}
+interface LowerResult {
+    readonly statements: L.Statement[];
+    /** In a module: the parameter the statements fill in with the exports. */
+    readonly exportsName: string;
+    /** In a module: what the bundle's `require` needs to know about it. */
+    readonly module: ModuleInfo;
+    readonly diagnostics: LowerDiagnostic[];
+    /** The line of the *source* file each emitted statement came from. With the
+     *  file it was lowered from, this is what turns a line of the bundle back
+     *  into a place someone can open. */
+    readonly origins: WeakMap<L.Statement, number>;
+}
+/** How a module's exports behave at runtime, beyond what its code assigns. */
+interface ModuleInfo {
+    /** Names the module itself exports. Reading one before the module has
+     *  initialized it is an error, as in ES modules. */
+    readonly names: string[];
+    /** Names re-exported from another module — `export { x as y } from` —
+     *  read from that module on every access, so they stay live.
+     *  `imported` is `undefined` for the whole module (`import * as M; export { M }`). */
+    readonly links: {
+        name: string;
+        module: string;
+        imported?: string;
+    }[];
+    /** `export * from` modules, consulted live for any other name. */
+    readonly stars: string[];
+    /** Whether the module exports anything. */
+    exports: boolean;
+}
+declare function lower(program: T.Program, scopes: ScopeAnalysis, options?: LowerOptions): LowerResult;
+
+/** What `tilua.config.json` holds. */
+interface TiluaConfigJson {
+    /** Type libraries to check against: `["roblox"]` loads `@tilua-types/roblox`. */
+    types?: string[];
+    /** Import path aliases, as in tsconfig: `{ "@shared/*": ["src/shared/*"] }`. */
+    paths?: Record<string, string[]>;
+    /** Where `paths` targets resolve from. Default: the config's folder. */
+    baseUrl?: string;
+    /** A Rojo sourcemap, or `null`. */
+    sourceMap?: string | null;
+    /** Which Lua the output must run on. `"luau"` (the default) keeps Luau's
+     *  own syntax; `"lua51"` also lowers what stock Lua 5.1 cannot parse —
+     *  `a += b`, `continue`, `if c then a else b` as an expression, `//`,
+     *  digit separators and binary literals. */
+    target?: Target;
+}
+/** A config file's path, or the config itself. Relative paths — to a config
+ *  file, and inside an inline config — resolve from `cwd`. */
+type ConfigInput = string | TiluaConfigJson;
+interface ResolvedConfig {
+    readonly config?: TiluaConfig;
+    readonly problems: readonly ConfigProblem[];
+}
+/** The config for a build of `entry`: the one given, or else the nearest
+ *  `tilua.config.json` above the entry. */
+declare function resolveConfig(input: ConfigInput | undefined, entry: string, cwd?: string): ResolvedConfig;
+
+interface BundleOptions {
+    /** The file the bundle runs. */
+    readonly entry: string;
+    /** A `tilua.config.json` path or contents. Default: the nearest config above the entry. */
+    readonly config?: ConfigInput;
+    /** The project folder. Modules are named by their path from it, and an
+     *  inline config's relative paths resolve from it. Default: the config
+     *  file's folder, or else the entry's. */
+    readonly root?: string;
+    /** Check types against the config's `types` too. Default: true. */
+    readonly typeCheck?: boolean;
+    /** Which Lua the output must run on. Overrides the config's `target`. */
+    readonly target?: Target;
+}
+interface BundleDiagnostic {
+    /** Absolute path of the file it is about. */
+    readonly file: string;
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+    /** `type` and `config` problems are reported without stopping the build;
+     *  `syntax`, `scope` (such as assigning to an import) and `module`
+     *  problems leave no bundle. */
+    readonly category: "syntax" | "scope" | "module" | "type" | "config";
+}
+interface BundleResult {
+    /** The bundle, or `undefined` when a module could not be compiled. Type
+     *  errors are reported but do not stop it. */
+    readonly code?: string;
+    /** The bundled modules' names, entry first. */
+    readonly modules: string[];
+    readonly diagnostics: BundleDiagnostic[];
+}
+declare function bundle(options: BundleOptions): Promise<BundleResult>;
+
+interface Diagnostic {
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+}
+interface CompileResult {
+    /** The Luau source, or `undefined` when the file has errors. */
+    readonly code?: string;
+    readonly diagnostics: Diagnostic[];
+}
+declare function compile(source: string, config?: ConfigInput): Promise<CompileResult>;
+
+export { type BundleDiagnostic, type BundleOptions, type BundleResult, type CompileResult, type ConfigInput, type Diagnostic, type LoadedLowering, type LowerDiagnostic, type LowerOptions, type LowerResult, type LoweringProblem, type ModuleContext, type ResolvedConfig, type TiluaConfigJson, bundle, compile, loadLowerings, lower, resolveConfig };

package/dist/index.js

@@ -0,0 +1,55 @@
+import {
+  bundle,
+  loadLowerings,
+  lower,
+  program,
+  resolveConfig
+} from "./chunk-S5C4VH6A.js";
+
+// src/compile.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { parse, analyzeScopes, analyzeTypes, resolveTypeLibraries, ParseError, LexError } from "@tilua/parser";
+import { print } from "luau-parser";
+async function compile(source, config) {
+  let program2;
+  try {
+    program2 = parse(source);
+  } catch (error) {
+    if (error instanceof ParseError || error instanceof LexError) {
+      const { line, column } = error;
+      return { diagnostics: [{ message: error.message, line, column }] };
+    }
+    throw error;
+  }
+  const scopes = analyzeScopes(program2);
+  const diagnostics = scopes.diagnostics.map((d) => ({
+    message: d.message,
+    line: d.node.line.start,
+    column: d.node.column.start
+  }));
+  const { config: resolved, problems } = resolveConfig(config, resolve("main.tilua"));
+  const libraries = resolved ? resolveTypeLibraries(resolved) : { files: [], lowerings: [], problems: [] };
+  const { lowerings, problems: loweringProblems } = await loadLowerings(libraries.lowerings);
+  for (const p of [...problems, ...libraries.problems]) {
+    diagnostics.push({ message: p.message, line: p.line ?? 1, column: p.column ?? 1 });
+  }
+  for (const p of loweringProblems) diagnostics.push({ message: p.message, line: 1, column: 1 });
+  const libs = libraries.files.map((file) => parse(readFileSync(file, "utf8")));
+  const lowered = lower(program2, scopes, {
+    types: analyzeTypes(program2, scopes, { libs, diagnostics: false }),
+    lowerings,
+    target: resolved?.target,
+    source
+  });
+  diagnostics.push(...lowered.diagnostics);
+  if (diagnostics.length) return { diagnostics };
+  return { code: print(program(lowered.statements)) + "\n", diagnostics };
+}
+export {
+  bundle,
+  compile,
+  loadLowerings,
+  lower,
+  resolveConfig
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@tilua/compiler",
+  "version": "1.0.0",
+  "description": "Compiles tilua to Luau: lowers the @tilua/parser AST to a luau-parser AST and prints it",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tilua": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": {
+        "require": "./dist/index.d.cts",
+        "import": "./dist/index.d.ts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "test": "tsx scripts/test.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tilua",
+    "luau",
+    "roblox",
+    "compiler"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "luau-parser": "^1.0.3",
+    "@tilua/parser": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Uav3537/tilua-compiler.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}