luaut-parser 3.0.0 → 4.0.0

package/README.md

@@ -45,24 +45,32 @@ annotation resolves to, and `expectedTypeOf` what each call argument should
 be, so a tool never has to re-derive a type from text.
 
 `parseWithRecovery(source)` returns `{ program, errors }` instead of throwing —
-use it for editors, where the text is usually mid-edit.
+use it for editors, where the text is usually mid-edit. An error costs as
+little of the tree as it can: a broken value becomes an `ErrorExpression`
+(typed `any`) in its place, a broken field or argument is skipped to the next
+`,`, a missing comma between fields on separate lines, or a missing `)`, `}`,
+`then`, `do` or `end`, is recorded and read past — a missing `end` is placed
+by indentation — and an unclosed string ends at its line. Skipping never lets
+an `end` or `}` inside a skipped function or object close the block around
+it. Valid code parses to exactly the same tree as `parse`.
 
 Neither analysis mutates the AST; both return side tables.
 
 ## Projects
 
-**No types are built in** — not `print`, not `string`, not `game`. A project
-lists the type libraries it uses in `luaut.config.json`, the way TypeScript
-uses `@types/*`:
+**No globals are built in** — not `print`, not `string`, not `game`. Only the
+language's own utility types are (`Partial`, `Pick`, `Omit`, `Record`,
+`ReturnType`, `Truthy`, ...; see `PRELUDE_SOURCE`). A project lists the type
+libraries it uses in `luaut.config.json`, the way TypeScript uses `@types/*`:
 
 ```bash
-npm i -D @luaut/roblox        # or just @luaut/luau
+npm i -D @luaut/roblox        # Luau + Roblox; or @luaut/lua on its own
 ```
 
 ```jsonc
 // luaut.config.json
 {
-  "types": ["roblox"],                          // @luaut/roblox, which brings @luaut/luau
+  "types": ["roblox"],                          // and what it depends on: @luaut/lua
   "paths": { "@shared/*": ["src/shared/*"] },   // import aliases, as in tsconfig
   "sourceMap": "sourcemap.json"                 // a Rojo sourcemap, or null
 }
@@ -96,8 +104,13 @@ the config (or sourcemap) it is about. `host` reads files — pass your own to
 read unsaved editor buffers or to record what was read.
 
 `type` / `typeof` are **not** special-cased in the analyzer either: they are
-overload sets in `@luaut/luau`, and narrowing is derived from them. Without a
-library that declares them, they narrow nothing.
+overload sets in `@luaut/lua` and `@luaut/roblox`, and narrowing is derived
+from them. Without a library that declares them, they narrow nothing.
+
+Libraries stack: a name declared again *adds* to what an earlier library gave
+it — overloads of a function accumulate, and the members of a declared table
+merge. That is how `@luaut/roblox` extends Lua's `table` and `type` without
+restating them.
 
 ## The language, in brief
 
@@ -111,6 +124,31 @@ scope; like a TypeScript function declaration it cannot be reassigned.
 `const` and `let` do not apply to functions. `function T.name()` and
 `function T:name()` define a member.
 
+**Hoisting** — a function declaration is visible to its whole block, above
+itself too, so `let r: ReturnType<typeof load>` may come before `function
+load()`. A closure reads the name its own value is bound to, as in JavaScript
+(`let m = { clear: function() m.items = {} end }`), and a later name in the
+same block; the compiler declares such a name before the statement that fills
+it. A module's top-level names are visible to code that runs later —
+function bodies and `typeof` — wherever that code is written, since a bundle
+declares them all before the module runs. At the top level the whole function
+is hoisted, and can be called above its declaration. Inside a function only
+the name is: other functions can call it, but a call straight in the block
+above the declaration is an error, because nothing is there yet.
+
+**Returns** — a declared return type is checked: what a `return` gives must
+fit it, and a function that declared one must return a value (a guard or an
+`asserts` function needs none). The declared type also types what is written
+there, so a returned callback takes its parameters from it.
+
+**Overloads** — a `function name(...)` with no body is a signature for the
+declaration that follows it, as in TypeScript: the signatures are what a call
+sees, and the last one, with the body, is the implementation. `export` goes on
+every line of the set or none of them. A parameter of the implementation that
+carries no annotation holds what the signatures allow there — under
+`get(stat: "hp")` and `get(stat: "name")`, the implementation's `stat` is
+`"hp" | "name"` rather than `any`.
+
 **Modules** — `import { a, b as c } from "./m"`, `import D from "./m"` and
 `import * as M from "./m"`; `export const`, `export function`, `export default`,
 `export { a as b }`, `export { a } from "./m"` and `export * from "./m"`.
@@ -122,8 +160,58 @@ brings in names that are types and nothing else: unlike TypeScript, using one
 as a value is an error, and only type positions — `typeof A` included — may
 name it. Compiled code keeps no trace of it.
 
+**Array and string methods** — an array and a string answer to methods
+written with `:`, the way JavaScript writes them:
+
+```luau
+const long = names:filter(function(n) return #n > 3 end):map(string.upper)
+const first = names:find(function(n) return n:startsWith("A") end)
+print(names:join(", "), text:trim(), text:replaceAll(",", ";"))
+```
+
+Which methods those are is not the language's business. The analyzer looks for
+two types by name — `ArrayMethods<T>` and `StringMethods` — and reads an
+array's or a string's members out of whichever type library declared them;
+without such a library an array has no methods at all.
+
+Running them is that library's business too. A library points at a JavaScript
+module in its package.json, and the compiler asks it what a call becomes:
+
+```json
+"luaut": { "types": "index.d.luaut", "lowering": "lowering.mjs" }
+```
+
+```ts
+import type { LoweringPlugin } from "luaut-parser"   // the contract, declared here
+
+const plugin: LoweringPlugin = {
+    runtime: { array: "local __NAME__ = {}\nfunction __NAME__.filter(t, test) ... end" },
+    methodCall({ method, receiver, use }) {
+        if (receiver?.kind === "array" && method === "filter") {
+            return { callee: `${use("array")}.filter` }
+        }
+        return undefined
+    },
+}
+export default plugin
+```
+
+`receiver` is the luaut type the analyzer worked out, `use(key)` gives the
+local name that table got — emitted once, at the top of the output, only if a
+call needed it — and the receiver is passed as the call's first argument. An
+answer of `undefined` leaves an ordinary Luau method call, which is what
+`text:upper()` wants, since a string already answers to it.
+
+The compiler lowers the language and nothing else: `filter` appears nowhere in
+it.
+
+`@luaut/lua` ships the JavaScript-shaped set; there, indices are Luau's (the
+first element is 1, `indexOf` answers `nil` rather than -1) and `push`, `pop`,
+`shift`, `unshift`, `sort` and `reverse` change the array they are called on.
+
 **Optionality** — there is no `T?` shorthand. `?` in type position always
-belongs to a conditional type, and in expression position to a ternary.
+belongs to a conditional type, and in expression position to a ternary or an
+optional chain.
 
 ```luau
 name?: T        -- may be absent; its type is `T | nil`
@@ -133,6 +221,13 @@ name: T | nil   -- must be written, but may be nil
 Omitting an argument requires `?` (or a default), as in TypeScript — a
 parameter typed `T | nil` still has to be passed something.
 
+**Optional chaining** — `a?.b` and `a?:m(x)` are nil when `a` is, and then
+nothing further along the chain runs, arguments included: `folder?:FindFirstChild("A")?.Name`
+is a `string | nil`. The `?` must touch the `.` or `:`; `c ? a : b` stays a
+ternary. Parentheses end a chain. A chain cannot be assigned to (`a?.b = 1` is
+an error). A chain that got through narrows what it tested: inside
+`if part?.Parent then`, and `if part?.Name == "Door" then`, `part` is not nil.
+
 **Classes** — types are structural, except for classes. A definitions file
 declares one with `declare class`, and it is nominal, as Roblox's classes are:
 
@@ -172,13 +267,32 @@ is `[]` passed where one is expected, including inside an object literal.
 
 **Calls** — every argument is checked against its parameter, and a generic
 parameter against its constraint (`GetService<K extends keyof Services>`
-rejects `""`).
+rejects `""`). Arguments are checked again once the call's own type arguments
+are known, so `pick("Bones", "Blast1")` is caught where `pick`'s second
+parameter reads `Extract<Rows, { Page: P }>["Skills"][number]`. A type that
+waits on a type parameter — a conditional, an index, `T[K]` — is worked out
+where that parameter is.
+
+**Trailing commas** are allowed wherever TypeScript allows them: parameter
+lists, call arguments, generic parameters and type arguments, tables, arrays,
+tuples, imports and exports.
+
+A value read by a key narrows the key: after `const path = paths[stat]`, the
+`else` of `if path then` leaves `stat` as exactly the keys `paths` does not
+have — the same correlation `pairs` over a record and a destructured union
+already get.
 
 **Narrowing** follows TypeScript's model: references (`x`, `x.a.b`, `x["k"]`)
 rather than just variables, discriminated unions at any depth, `and`/`or`,
 early return, `break`/`continue`, `error()` (declared `-> never`), user type
 guards (`v is T`), and assertion signatures (`asserts v`).
 
+Reading a member of, indexing or calling a value that may be nil is an error
+until a check narrows the nil away, as with TypeScript's `strictNullChecks`:
+`FindFirstChild("A"):FindFirstChild("B")` reports that the first call is
+possibly nil. Use `?.` / `?:`, or check first. The read is still typed from the
+non-nil part.
+
 Only `nil` and `false` are falsy — `0` and `""` are truthy, unlike JavaScript.
 
 **Types** — unions, intersections, tuples `[A, B]`, type packs `(A, B)` (the
@@ -186,7 +300,14 @@ several values a function returns), `keyof`, `T[K]`, conditional types with
 `infer`, mapped types with `as` remapping, template literal types
 (`` `on${Event}` ``), and set difference `A - B`. The utility types
 (`Partial`, `Pick`, `Omit`, `ReturnType`, `Parameters`, `Exclude`, …) are
-written in luaut on top of those, not built in.
+built in, and written in luaut on top of those rather than special-cased in
+the analyzer. A type library or a file may declare one again; the later
+declaration wins.
+
+A call may write its type arguments out — `find<Folder>("Remotes")`,
+`inst:WaitForChild<Folder>("Remotes")` — and a type parameter may have a
+default (`<T = Instance>`) for the calls that do not. `a < b > (c)` is still
+three operators: only a call after the `>` makes it type arguments.
 
 `<const T>` infers an argument at its narrowest, as in TypeScript 5.
 
@@ -197,6 +318,47 @@ written in luaut on top of those, not built in.
 
 **Modules** — `import` / `export`, export lists, re-exports and `export *`.
 
+**`satisfies`** — checks a value against a type without giving it that type,
+as in TypeScript 4.9:
+
+```luau
+type Shape = { kind: "circle" | "rect", size: number }
+const circle = { kind: "circle", size: 2 } satisfies Shape  -- { kind: "circle", size: number }
+const handlers = {
+    Click: function(x) return x + 1 end,                     -- x: number, from the contract
+} satisfies { [string]: (x: number) -> number }
+```
+
+The contract types callbacks and empty arrays, and a literal stays a literal
+where the contract asks for literals (`kind: "circle"`, not `string`). A value
+that does not fit is an error. So is a property the contract does not know —
+TypeScript's excess property check, which applies to an object literal written
+straight into an annotation (`const s: Shape = { ..., typo: 1 }`) too. A value
+that already has a type of its own keeps it exactly: `{ ... } as const
+satisfies T` stays readonly and literal. `as` reinterprets instead of
+checking, and compiled code keeps neither.
+
+**Undeclared names** — `analyzeScopes(program, { builtinGlobals, reportUndeclared: true })`
+reports each read of a name nothing declares: "Cannot find name 'x'". A global
+assigned in the file (`x = 1`) and a `declare` count as declarations.
+`analyzeTypes(program, scopes, { reportUnknownTypes: true })` does the same for
+type names. Both are off by default, since they are only right when the type
+libraries the file names are loaded.
+
+**Directives** — comments that switch checking off, as TypeScript's
+`// @ts-...` do. They silence scope and type errors, never syntax errors:
+
+```luau
+--@luaut-nocheck          -- before the first line of code: the whole file
+--@luaut-ignore           -- the next line of code
+--@luaut-expect-error     -- the next line of code, which must have an error
+```
+
+`parseWithRecovery` returns them as `directives`; `directivesOf(source)` reads
+them for a caller that parsed some other way, and
+`applyDirectives(directives, diagnostics, lineOf)` filters a list and names
+each `expect-error` that had nothing to suppress.
+
 ## Options
 
 ```ts