onejs-sl 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.1.6
+
+`diagnose(source)` returns every error in a file, for an editor checking as it is typed (`Specs/SL_NEXT.md` 5). Nothing a program compiles to changes.
+
+- `diagnose` finds a mistake in each statement and declaration, in source order, and never throws one
+- A refused local is still declared, so its uses are not reported again
+
+## 0.1.5
+
+What an editor needs, and errors that fix themselves (`Specs/SL_NEXT.md` 5 and 9). Every program that compiled before compiles to exactly what it did, unless it names something after a keyword or a type.
+
+- `classify` returns every token with its class, comments included, and never throws
+- `SL_KEYWORDS`, `SL_TYPES` and `TYPE_WIDTH` are exported from `onejs-sl/tables`
+- `BUILTIN_DOCS`, `INPUT_DOCS` and `PRELUDE_DOCS` describe every builtin, input and prelude function in a line
+- `SLParseError` carries `text`, its message alone, and `offset`
+- An error carries a one click `fix` where the fix is certain: a GLSL rename or a "did you mean"
+- A GLSL name used as a value, such as `gl_FragCoord`, gets the HLSL name
+- `break`, `continue` and `switch` say why they are not there
+- A keyword or a type cannot name a value, a function or a parameter
+- Something missing at the end of a line or the file is marked on the last token before it
+- Errors from inside the EDSL say `float3`, not `vec3`
+- `BodyTarget.sample` documents what the body expects of a sample
+
 ## 0.1.4
 
 Four things that were errors now compile, the most common mistakes in cold runs of authors writing from the docs alone (`Specs/SL_NEXT.md` 2). Every program that compiled before compiles to exactly what it did.

package/README.md

@@ -35,9 +35,9 @@ only what it calls.
 
 | Entry | Contents |
 |---|---|
-| `onejs-sl` | `parse` and `analyze`, the TypeScript form `sl`, the IR types, `SL_IR_VERSION`, `toJSON`/`fromJSON`, `SLParseError` (file, line, column, length) |
+| `onejs-sl` | `parse` and `analyze`, `diagnose` (every error in a file, not just the first), `classify` (every token with its class, comments kept, never throws), the TypeScript form `sl`, the IR types, `SL_IR_VERSION`, `toJSON`/`fromJSON`, `SLParseError` (file, line, column, offset, length, the bare `text`, and a `fix` where one is certain) |
 | `onejs-sl/core` | the same without the parser: what a game needs at run time |
-| `onejs-sl/tables` | `BUILTINS`, `SL_HLSL`, `INPUTS`, `SL_SDF_SHAPES`, `SL_SDF_PARAMS`: what completion and highlighting read. `BUILTIN_PARAMS`, `SL_SDF_PARAM_NAMES` and `LIB_SIGNATURES` name every parameter, so an editor can show `lerp(x, y, s)` |
+| `onejs-sl/tables` | `BUILTINS`, `SL_HLSL`, `INPUTS`, `SL_SDF_SHAPES`, `SL_SDF_PARAMS`, `SL_KEYWORDS`, `SL_TYPES`, `TYPE_WIDTH`, `PRELUDE_NAMES`: what completion and highlighting read. `BUILTIN_PARAMS`, `SL_SDF_PARAM_NAMES` and `LIB_SIGNATURES` name every parameter, so an editor can show `lerp(x, y, s)`, and `BUILTIN_DOCS`, `INPUT_DOCS` and `PRELUDE_DOCS` give each a line for its tooltip |
 | `onejs-sl/limits` | `vmFit(program)`: whether the VM runs it, and why not, without encoding |
 | `onejs-sl/vm` | `encode`, `SL_WIRE_VERSION` |
 | `onejs-sl/emit/hlsl-body` | `emitBody`: a program as a function body for a host's own frame; `emitLibrary`: the library functions it calls |
@@ -56,7 +56,11 @@ intrinsic at its exact type, since Metal overloads where HLSL converts). The `Bo
 for each input, the float4 holding a uniform slot, a texture sample, whether
 `toLinear` is real (`colour: "linear"`) or the identity (`"gamma"`), and
 optionally a local to assign the result to. It returns the uniform and texture
-slots the body uses and the library functions it calls. OneJS's Unity shader is
+slots the body uses and the library functions it calls. The sample's contract
+is on `BodyTarget.sample`: straight alpha in and out, rgb in the space `colour`
+names (an sRGB texture decoded before filtering when it is `linear`), and
+filtering and wrapping left to the host, which OneJS's hosts take from the
+bound texture's own settings. OneJS's Unity shader is
 one frame over it (`hlsl.ts`); Magerie's compute kernel is another, and its
 target is in `src/body.test.ts` so an opcode cannot change without the text
 Magerie compiles changing in front of a test.
@@ -175,7 +179,7 @@ generated HLSL after an eject, with no edit in between. Both backends exist:
 and `hlsl.ts` feeds its `Editor/SLShaderGenerator.cs`. Nobody writes a manifest for the
 second: an editor that interprets a program asks the encoded program for its
 `hlsl` (a lazy getter, never read in Play), records it into
-`Assets/OneJS.Generated/Shaders/Recorded.sl.json`, generates the shader and
+`Assets/OneJS/Recorded.sl.json`, generates the shader and
 moves the live material onto it. `manifest()` is still there for an app that
 would rather write its programs out at build time.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL, GLSL ES or a VM buffer",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/body.ts

@@ -31,12 +31,30 @@ export interface BodyTarget {
     inputs: Record<InputName, string>
     /** The float4 holding a uniform slot. The body swizzles it down to the uniform's width. */
     uniform: (slot: number, name: string) => string
-    /** A float4 sample of the texture in `slot` at the float2 expression `uv`, straight alpha. */
+    /**
+     * A float4 sample of the texture in `slot` at the float2 expression `uv`.
+     *
+     * The contract the body is written against, which is what OneJS's own hosts
+     * do with the GPU's sampler:
+     *
+     * - **Straight alpha**, not premultiplied, in and out: the body never
+     *   multiplies or divides by alpha, and its result is straight too.
+     * - **In the space `colour` names.** With `linear`, rgb is linear light, so
+     *   an sRGB texture is decoded before it is filtered, as an sRGB sampler
+     *   does; with `gamma`, rgb is as stored.
+     * - **Filtered and wrapped by the host.** The body does neither. OneJS's
+     *   hosts, the generated shader, the VM and the web backends alike, use the
+     *   bound texture's own filter and wrap modes, so a host that filters by
+     *   hand draws the same picture by following the texture's settings.
+     *
+     * What becomes of the result is the host's: OneJS writes it to the target
+     * as it is, and a host that composites premultiplied multiplies on write.
+     */
     sample: (slot: number, uv: string) => string
     /**
      * `linear`: `toLinear` calls `sl_toLinear`, for a host whose target holds
      * linear light. `gamma`: `toLinear` is the identity, decided here, so hex
-     * colours and ramps stay as written.
+     * colours and ramps stay as written. `sample` reads in the same space.
      */
     colour: "gamma" | "linear"
     /** Assign the result to this local instead of returning it. */

package/src/index.ts

@@ -6,7 +6,7 @@
  * HLSL, WGSL or GLSL ES) is a separate entry, so a host bundles only what it
  * calls:
  *
- *   onejs-sl             this: parse, the TypeScript form, the IR, its JSON
+ *   onejs-sl             this: parse, diagnose, classify, the TypeScript form, the IR, its JSON
  *   onejs-sl/core        the same without the parser, for a game at run time
  *   onejs-sl/tables      builtins, opcodes, inputs, shapes: what an editor reads
  *   onejs-sl/limits      whether a program fits the VM, without encoding it
@@ -19,6 +19,8 @@
  */
 export * from "./core"
 export {
-    analyze, parse, parseUnit, preludeFunctions, tokenize, PRELUDE_SOURCE, SLParseError,
+    analyze, classify, diagnose, parse, parseUnit, preludeFunctions, tokenize, PRELUDE_SOURCE, SLParseError,
+} from "./lang"
+export type {
+    Checked, Expr, FuncDecl, ParseOptions, Pos, SLClassifiedToken, SLFix, SLTokenClass, Stmt, Token, Unit,
 } from "./lang"
-export type { Checked, Expr, FuncDecl, ParseOptions, Pos, Stmt, Token, Unit } from "./lang"

package/src/lang/README.md

@@ -168,11 +168,49 @@ lowering it changes recorded behaviour rather than parser behaviour.
 
 ## Errors
 
-Every one carries file, line and column, and an error that starts inside the
-EDSL keeps the EDSL's wording. `"z" is component 3 of a vec2, which has 2` is
-already the right sentence; what it lacked was a place. `errors.test.ts` checks
-the positions as strictly as the words, because a marker under the wrong
-character sends the reader to look at something that is fine.
+Every one carries file, line, column, offset and length, and `text`, the
+message without its tag and its `file:line:col: `, for an editor that puts the
+words in a marker of its own. An error that starts inside the EDSL keeps the
+EDSL's wording, with its type names put in the file's: `"z" is component 3 of
+a float2, which has 2` was already the right sentence; what it lacked was a
+place. `errors.test.ts` checks the positions as strictly as the words, because
+a marker under the wrong character sends the reader to look at something that
+is fine. Something missing at the end of a line or the file marks the last
+token before it, where there is a character to underline.
+
+Where the fix is certain, the error carries it as `fix`: a title and the text
+for the marked range, one click in an editor. A GLSL spelling that means the
+same in HLSL (`mix`, `fract`, `vec3`, `gl_FragCoord`, `iTime`, two argument
+`atan`) and a "did you mean" both have one. `mod` does not, since GLSL's floors
+and `%` truncates, and neither does `int`, since float would change what
+dividing it does. That is Decision 1 kept as `Specs/SL_NEXT.md` 5 A has it:
+one spelling, and every hint a fix.
+
+## Several errors at once
+
+`parse` throws the first error; `diagnose(source)` returns all of them, in
+source order, and never throws one, for an editor checking as the file is
+typed. Each stage carries on past a mistake: the parser skips to the next
+statement or declaration, the checker and the lowering move to the next one,
+and a local whose line was refused is still declared, as a zero of its type, so
+its uses are not reported again. A later stage runs only when the earlier ones
+found nothing: names are not checked in a file that cannot be read, since those
+errors would be about the hole. `diagnose.test.ts` holds it to the property that
+matters, that whatever `parse` refuses a file with, `diagnose` reports at the
+same place, over every program one token short of a real one.
+
+## For an editor
+
+`classify(source)` is every token with its class (keyword, type, builtin,
+input, prelude, number, hex, comment, punct, member, ident, or invalid), built
+on the parser's own scanner and word lists, so the highlighting is the parser's.
+It never throws, since it runs on every keystroke. It classifies by spelling,
+not scope: a local named `circle` still reads as a builtin where it is used.
+
+`SL_KEYWORDS` and `SL_TYPES` (`words.ts`) are the lists the parser reads, and a
+name may be neither. `onejs-sl/tables` carries them with a one line description
+of every builtin, input and prelude function; a prelude function's is the
+comment above it in `prelude-source.ts`.
 
 ## See also
 

package/src/lang/check.ts

@@ -34,10 +34,22 @@ import { SL_GLSL_HINT } from "../ops"
 import { BUILTINS, NOT_YET } from "./builtins"
 import { SL_SDF_SHAPES } from "../shapes"
 import type { Expr, FuncDecl, Stmt, Unit } from "./ast"
-import { SLParseError, type Pos } from "./lexer"
+import { SLParseError, type Pos, type SLFix } from "./lexer"
 
 const INPUT_NAMES = new Set(Object.keys(INPUTS))
 
+/**
+ * The GLSL spellings whose HLSL name means the same wherever it is written, so
+ * the hint can be a one click fix (`Specs/SL_NEXT.md` 5, Decision 1 A). The
+ * rest of `SL_GLSL_HINT` gets the hint alone: `mod` floors where `%` truncates,
+ * `ivec2` truncates where `float2` does not, `atan` is `atan2` only with two
+ * arguments (handled at the call), and `textureLod` names a builtin that is not
+ * implemented yet.
+ */
+const GLSL_RENAMES = new Set(["mix", "fract", "texture", "vec2", "vec3", "vec4", "gl_FragCoord", "iTime", "iResolution"])
+
+const rename = (from: string, to: string): SLFix => ({ title: `Replace ${from} with ${to}`, replacement: to })
+
 export interface Checked {
     unit: Unit
     /** Every callable function by name, the file's shadowing the prelude's. */
@@ -57,6 +69,8 @@ export interface Checked {
 export interface CheckOptions {
     /** Off for the prelude, which is functions only. See `parseUnit`. */
     requireMain?: boolean
+    /** Where to collect errors instead of throwing the first. See `diagnose`. */
+    errors?: SLParseError[]
 }
 
 export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {}): Checked {
@@ -65,10 +79,27 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     // terminating control flow when the callee's `never` comes from an explicit
     // type, so without this every `if (x.k !== "ident") fail(...)` below would
     // fail to narrow.
-    const fail: (message: string, pos: Pos, length?: number) => never =
-        (message, pos, length = 1) => {
-            throw new SLParseError(message, file, pos, length)
+    const fail: (message: string, pos: Pos, length?: number, fix?: SLFix) => never =
+        (message, pos, length = 1, fix) => {
+            throw new SLParseError(message, file, pos, length, fix)
+        }
+
+    /**
+     * One declaration's or one statement's checks. Collecting, an error is
+     * recorded and the next one is checked; the name it declares is still
+     * declared, so a later use of it is not a second, false error.
+     */
+    const attempt = (check: () => void): boolean => {
+        if (options.errors === undefined) { check(); return true }
+        try {
+            check()
+            return true
+        } catch (e) {
+            if (!(e instanceof SLParseError)) throw e
+            options.errors.push(e)
+            return false
         }
+    }
 
     const funcs = new Map<string, FuncDecl>()
     for (const fn of prelude) funcs.set(fn.name, fn)
@@ -114,11 +145,14 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     }
 
     for (const u of unit.uniforms) {
-        const clash = valueClash(u.name)
-        if (clash !== null) fail(`"${u.name}" already names ${clash}`, u.pos, u.name.length)
-        uniforms.set(u.name, u)
+        attempt(() => {
+            const clash = valueClash(u.name)
+            if (clash !== null) fail(`"${u.name}" already names ${clash}`, u.pos, u.name.length)
+        })
+        if (!uniforms.has(u.name)) uniforms.set(u.name, u)
     }
-    if (uniforms.size > VM_UNIFORMS) {
+    attempt(() => {
+        if (uniforms.size <= VM_UNIFORMS) return
         const over = unit.uniforms[VM_UNIFORMS]!
         fail(
             `this file declares ${uniforms.size} uniforms and a program may hold ${VM_UNIFORMS}. ` +
@@ -127,14 +161,17 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             `a float4.`,
             over.pos, over.name.length,
         )
-    }
+    })
 
     for (const t of unit.textures) {
-        const clash = valueClash(t.name)
-        if (clash !== null) fail(`"${t.name}" already names ${clash}`, t.pos, t.name.length)
-        textures.set(t.name, t)
+        attempt(() => {
+            const clash = valueClash(t.name)
+            if (clash !== null) fail(`"${t.name}" already names ${clash}`, t.pos, t.name.length)
+        })
+        if (!textures.has(t.name)) textures.set(t.name, t)
     }
-    if (textures.size > VM_TEXTURES) {
+    attempt(() => {
+        if (textures.size <= VM_TEXTURES) return
         const over = unit.textures[VM_TEXTURES]!
         fail(
             `this file declares ${textures.size} textures and a program may sample ${VM_TEXTURES}. ` +
@@ -142,24 +179,28 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             `and its own after an eject, which is two different pictures from one file.`,
             over.pos, over.name.length,
         )
-    }
+    })
 
     for (const c of unit.consts) {
-        const clash = valueClash(c.name)
-        if (clash !== null) fail(`"${c.name}" already names ${clash}`, c.pos, c.name.length)
-        consts.set(c.name, c)
+        attempt(() => {
+            const clash = valueClash(c.name)
+            if (clash !== null) fail(`"${c.name}" already names ${clash}`, c.pos, c.name.length)
+        })
+        if (!consts.has(c.name)) consts.set(c.name, c)
     }
 
     for (const fn of unit.funcs) {
-        const clash = taken(fn.name)
-        if (clash !== null) fail(`"${fn.name}" already names ${clash}`, fn.pos, fn.name.length)
-        if (unit.funcs.filter((f) => f.name === fn.name).length > 1) {
-            fail(
-                `this file declares ${fn.name} more than once. There is no overloading: a function ` +
-                `inlines, so two bodies under one name have nothing to pick between them`,
-                fn.pos, fn.name.length,
-            )
-        }
+        attempt(() => {
+            const clash = taken(fn.name)
+            if (clash !== null) fail(`"${fn.name}" already names ${clash}`, fn.pos, fn.name.length)
+            if (unit.funcs.filter((f) => f.name === fn.name).length > 1) {
+                fail(
+                    `this file declares ${fn.name} more than once. There is no overloading: a function ` +
+                    `inlines, so two bodies under one name have nothing to pick between them`,
+                    fn.pos, fn.name.length,
+                )
+            }
+        })
         funcs.set(fn.name, fn)
     }
 
@@ -167,19 +208,23 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     if (main === null) {
         if (options.requireMain ?? true) throw new Error("check() reached a unit with no main")
         for (const fn of unit.funcs) checkFunction(fn)
-        refuseRecursion()
+        attempt(refuseRecursion)
         return { unit, funcs, uniforms, textures, consts }
     }
-    if (main.ret !== "float4") {
-        fail(`main returns a colour, so it is declared \`float4 main()\`, not ${main.ret}`, main.pos)
-    }
-    if (main.params.length > 0) {
-        fail(
-            "main takes no parameters: what a program is given are the free identifiers uv, " +
-            "fragCoord, resolution, time and aspect",
-            main.params[0]!.pos,
-        )
-    }
+    attempt(() => {
+        if (main.ret !== "float4") {
+            fail(`main returns a colour, so it is declared \`float4 main()\`, not ${main.ret}`, main.pos)
+        }
+    })
+    attempt(() => {
+        if (main.params.length > 0) {
+            fail(
+                "main takes no parameters: what a program is given are the free identifiers uv, " +
+                "fragCoord, resolution, time and aspect",
+                main.params[0]!.pos,
+            )
+        }
+    })
 
     // MARK: bodies
 
@@ -189,7 +234,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     // which is not the author's mistake and not a name they can see.
     for (const fn of [...unit.funcs, main]) checkFunction(fn)
 
-    refuseRecursion()
+    attempt(refuseRecursion)
 
     /**
      * A function inlines, so a cycle is not slow, it is infinite.
@@ -260,9 +305,11 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     function checkFunction(fn: FuncDecl): void {
         const params = new Set<string>()
         for (const p of fn.params) {
-            const clash = valueClash(p.name)
-            if (clash !== null) fail(`"${p.name}" already names ${clash}`, p.pos, p.name.length)
-            if (params.has(p.name)) fail(`${fn.name} already has a parameter called "${p.name}"`, p.pos)
+            attempt(() => {
+                const clash = valueClash(p.name)
+                if (clash !== null) fail(`"${p.name}" already names ${clash}`, p.pos, p.name.length)
+                if (params.has(p.name)) fail(`${fn.name} already has a parameter called "${p.name}"`, p.pos)
+            })
             params.add(p.name)
         }
         checkBody(fn, fn.body, new Set(params), true)
@@ -279,8 +326,20 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         let returned: Stmt | null = null
         for (const s of body) {
             if (returned !== null) {
-                fail("this is after the return, so it can never run", s.pos)
+                // Once: everything after it is the same mistake.
+                attempt(() => fail("this is after the return, so it can never run", s.pos))
+                break
             }
+            attempt(() => checkStmt(s))
+            if (s.k === "var" || s.k === "const") scope.add(s.name)
+            // Only the outermost return ends a body; one inside an if is refused as that.
+            if (s.k === "return" && outermost) returned = s
+        }
+        if (outermost && returned === null) {
+            attempt(() => fail(`${fn.name} never returns a ${fn.ret}`, fn.pos, fn.name.length))
+        }
+
+        function checkStmt(s: Stmt): void {
             switch (s.k) {
                 case "var":
                 case "const": {
@@ -288,7 +347,6 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     if (clash !== null) fail(`"${s.name}" already names ${clash}`, s.pos, s.name.length)
                     if (scope.has(s.name)) fail(`"${s.name}" is already declared in this body`, s.pos)
                     checkExpr(fn, s.init, scope)
-                    scope.add(s.name)
                     break
                 }
                 case "assign": {
@@ -316,9 +374,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                             target.pos, n.length,
                         )
                     }
-                    if (!scope.has(n)) {
-                        fail(unknown(n, scope), target.pos, n.length)
-                    }
+                    if (!scope.has(n)) unknown(n, scope, target.pos)
                     checkExpr(fn, s.value, scope)
                     break
                 }
@@ -337,8 +393,11 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     const inner = new Set(scope)
                     inner.add(s.counter)
                     counters.add(s.counter)
-                    checkBody(fn, s.body, inner, false)
-                    counters.delete(s.counter)
+                    try {
+                        checkBody(fn, s.body, inner, false)
+                    } finally {
+                        counters.delete(s.counter)
+                    }
                     break
                 }
                 case "return":
@@ -351,13 +410,9 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                         )
                     }
                     checkExpr(fn, s.value, scope)
-                    returned = s
                     break
             }
         }
-        if (outermost && returned === null) {
-            fail(`${fn.name} never returns a ${fn.ret}`, fn.pos, fn.name.length)
-        }
     }
 
     // MARK: expressions
@@ -382,7 +437,8 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                 if (funcs.has(e.name) || BUILTINS[e.name] !== undefined) {
                     fail(`${e.name} is a function; call it, as in \`${e.name}(...)\``, e.pos, e.name.length)
                 }
-                fail(unknown(e.name, scope), e.pos, e.name.length)
+                glsl(e.name, e.pos)
+                unknown(e.name, scope, e.pos)
                 break
             }
             case "member":
@@ -493,10 +549,16 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                 callee.pos, n.length,
             )
         }
-        if (SL_GLSL_HINT[n] !== undefined) {
-            fail(`${n} is GLSL; this is HLSL, so write ${SL_GLSL_HINT[n]}`, callee.pos, n.length)
-        }
-        fail(unknown(n, scope), callee.pos, n.length)
+        glsl(n, callee.pos, e.args.length)
+        unknown(n, scope, callee.pos)
+    }
+
+    /** Refuses a GLSL spelling by its HLSL name, with the fix where the rename is certain. */
+    function glsl(n: string, pos: Pos, args?: number): void {
+        const hint = SL_GLSL_HINT[n]
+        if (hint === undefined) return
+        const certain = GLSL_RENAMES.has(n) || (n === "atan" && args === 2)
+        fail(`${n} is GLSL; this is HLSL, so write ${hint}`, pos, n.length, certain ? rename(n, hint) : undefined)
     }
 
     function arity(e: Extract<Expr, { k: "call" }>, n: string, min: number, max: number): void {
@@ -505,13 +567,14 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         fail(`${n} takes ${want} argument${max === 1 ? "" : "s"}, got ${e.args.length}`, e.pos)
     }
 
-    /** "unknown x" plus the nearest thing that is spelled almost like it. */
-    function unknown(n: string, scope: Set<string>): string {
+    /** Refuses a name nothing declares, offering the nearest one spelled almost like it. */
+    function unknown(n: string, scope: Set<string>, pos: Pos): never {
         const near = nearest(n, [
             ...scope, ...INPUT_NAMES, ...uniforms.keys(), ...textures.keys(), ...consts.keys(),
             ...funcs.keys(), ...Object.keys(BUILTINS),
         ])
-        return near === null ? `"${n}" is not declared` : `"${n}" is not declared; did you mean ${near}?`
+        if (near === null) fail(`"${n}" is not declared`, pos, n.length)
+        fail(`"${n}" is not declared; did you mean ${near}?`, pos, n.length, rename(n, near))
     }
 
     return { unit, funcs, uniforms, textures, consts }

package/src/lang/classify.ts

@@ -0,0 +1,70 @@
+/**
+ * Every token of a file with what it is, for an editor's highlighting.
+ *
+ * `Specs/SL_NEXT.md` 9. Built on the parser's own scanner and the parser's own
+ * word lists, so what highlights as a keyword is exactly what parses as one,
+ * and a builtin is exactly what `BUILTINS` holds. It never throws: it runs on
+ * every keystroke over half typed text, and a character it cannot read comes
+ * back as `invalid` rather than ending the pass.
+ *
+ * Classification is by spelling and position alone, not by scope. A local
+ * that takes a builtin's name (`float circle = ...`) still reads `builtin`
+ * where it is used; telling the two apart needs `analyze`, and an editor that
+ * wants that should ask it.
+ */
+
+import { INPUTS } from "../ir"
+import { BUILTINS } from "./builtins"
+import { lex } from "./lexer"
+import { PRELUDE_NAMES } from "./prelude-source"
+import { KEYWORD_SET, TYPE_SET } from "./words"
+
+export type SLTokenClass =
+    | "keyword" | "type" | "builtin" | "input" | "prelude"
+    | "number" | "hex" | "comment" | "punct"
+    /** A component after a dot, as in `c.rgb`. */
+    | "member"
+    /** Any other name: a uniform, a local, a function the file declares. */
+    | "ident"
+    /** A character or `#word` the language cannot read, and would refuse. */
+    | "invalid"
+
+export interface SLClassifiedToken {
+    kind: SLTokenClass
+    text: string
+    /** 1 based. */
+    line: number
+    /** 1 based. */
+    col: number
+    offset: number
+    length: number
+}
+
+const INPUT_NAMES: ReadonlySet<string> = new Set(Object.keys(INPUTS))
+
+/** The tokens of `source`, comments included, in order, each with its class. */
+export function classify(source: string): SLClassifiedToken[] {
+    const tokens = lex(source, "", true)
+    const out: SLClassifiedToken[] = []
+    // The last token that was not a comment, which decides what a name after a dot is.
+    let before = ""
+    let beforeThat = ""
+    for (const t of tokens) {
+        if (t.kind === "eof") break
+        let kind: SLTokenClass
+        if (t.kind === "ident") {
+            if (before === ".") kind = beforeThat === "sdf" ? "builtin" : "member"
+            else if (KEYWORD_SET.has(t.text)) kind = "keyword"
+            else if (TYPE_SET.has(t.text)) kind = "type"
+            else if (INPUT_NAMES.has(t.text)) kind = "input"
+            else if (BUILTINS[t.text] !== undefined) kind = "builtin"
+            else if (PRELUDE_NAMES.has(t.text)) kind = "prelude"
+            else kind = "ident"
+        } else {
+            kind = t.kind
+        }
+        out.push({ kind, text: t.text, line: t.line, col: t.col, offset: t.offset, length: t.length })
+        if (t.kind !== "comment") { beforeThat = before; before = t.text }
+    }
+    return out
+}

package/src/lang/index.ts

@@ -19,6 +19,7 @@
 
 import type { Program } from "../ir"
 import { check, type Checked } from "./check"
+import { SLParseError } from "./lexer"
 import { lower } from "./lower"
 import { parseUnit, type ParseOptions } from "./parser"
 import { preludeFunctions } from "./prelude"
@@ -29,9 +30,12 @@ export type {
     Expr, FuncDecl, Param, Stmt, TextureDecl, TypeName, UniformDecl, Unit,
 } from "./ast"
 export { TYPE_WIDTH } from "./ast"
-export { SLParseError } from "./lexer"
-export type { Pos, Token } from "./lexer"
+export { SLParseError }
+export type { Pos, SLFix, Token } from "./lexer"
 export { tokenize } from "./lexer"
+export { classify } from "./classify"
+export type { SLClassifiedToken, SLTokenClass } from "./classify"
+export { SL_KEYWORDS, SL_TYPES } from "./words"
 export { parseUnit } from "./parser"
 export { PRELUDE_SOURCE, preludeFunctions } from "./prelude"
 export { BUILTINS, NOT_YET } from "./builtins"
@@ -53,3 +57,38 @@ export function analyze(source: string, options: ParseOptions = {}): Checked {
     const unit = parseUnit(source, options)
     return check(unit, preludeFunctions(), { requireMain: options.requireMain })
 }
+
+/**
+ * Every error in a file, in source order, for an editor checking as it is
+ * typed. Empty when the file compiles. Never throws a `SLParseError`.
+ *
+ * Errors of one kind at a time, the first kind the file has: what cannot be
+ * read, then names and shapes (`check`), then types and widths (lowering).
+ * Each stage carries on past an error, a statement or a declaration at a time;
+ * a later stage runs only on a file the earlier ones passed, since its errors
+ * about a file with a hole in it would be about the hole.
+ */
+export function diagnose(source: string, options: ParseOptions = {}): SLParseError[] {
+    const errors: SLParseError[] = []
+    try {
+        const unit = parseUnit(source, { ...options, errors })
+        if (errors.length === 0) {
+            const checked = check(unit, preludeFunctions(), { requireMain: options.requireMain, errors })
+            if (errors.length === 0) lower(checked, errors)
+        }
+    } catch (e) {
+        // The lexer's, which stops at the first character it cannot read.
+        if (!(e instanceof SLParseError)) throw e
+        errors.push(e)
+    }
+    // An error in a loop body or an inlined function is found once per copy.
+    const seen = new Set<string>()
+    return errors
+        .filter((e) => {
+            const key = `${e.offset}:${e.text}`
+            if (seen.has(key)) return false
+            seen.add(key)
+            return true
+        })
+        .sort((a, b) => a.offset - b.offset)
+}