functionalscript 0.44.0 → 0.46.0

package/fjs/djs/parser/module.f.mjs

@@ -10,7 +10,7 @@
  * @import { OrderedMap } from '../../types/ordered_map/types.ts'
  * @import { AstArray, AstConst, AstModule, AstModuleRef } from '../ast/types.ts'
  * @import { TokenMetadata } from '../../js/tokenizer/types.ts'
- * @import { ParseError } from './types.ts'
+ * @import { ParseError, _ValueToken } from './types.ts'
  */
 
 import { error, ok } from '../../types/result/module.f.mjs'
@@ -60,10 +60,22 @@ import { assertEq } from '../../asserts/module.f.mjs'
  *   readonly module: _ModuleState
  * }} _ExportState */
 
+/**
+ * Where the value parser stands inside the value it is reading.
+ *
+ * The object states spell a property out left to right: `'{'` expects a key,
+ * `'{k'` the `:` after one, `'{:'` the value, `'{v'` the `,` or `}` after it,
+ * and `'{,'` the next key. A computed key `["a"]` takes the two extra steps
+ * `'{['` (the string inside the brackets) and `'{[k'` (the closing `]`), then
+ * rejoins the plain path at `'{k'`.
+ *
+ * @typedef {'' | '[' | '[v' | '[,' | '{' | '{[' | '{[k' | '{k' | '{:' | '{v' | '{,'} _ValueState
+ */
+
 /** @typedef {{
  *   readonly state: 'constValue' | 'exportValue'
  *   readonly module: _ModuleState
- *   readonly valueState: '' | '[' | '[v' | '[,' | '{' | '{k' | '{:' | '{v' | '{,'
+ *   readonly valueState: _ValueState
  *   readonly top: _DjsStackElement | null
  *   readonly stack: _DjsStack
  * }} _ParseValueState */
@@ -78,7 +90,21 @@ import { assertEq } from '../../asserts/module.f.mjs'
  *   readonly error: ParseError
  * }} _ErrorState */
 
-/** @type {(token: DjsTokenWithMetadata) => (state: _InitialState) => _ParserState} */
+/**
+ * A statement begins with `import`, `const`, or `export` and with nothing
+ * else. The three are a whitelist that grows as the language does, not a
+ * closed set; what a statement may never begin with is a **value**. A text
+ * that does — `42`, `[1,2]`, `{"a":1}` — is a JSON document, and reading it
+ * as a module would give it a value no JavaScript engine gives it: as
+ * JavaScript `{"a":1}` does not parse at all, and `[1,2]` is an expression
+ * statement exporting nothing.
+ *
+ * The statements are also ordered: every `import` precedes every `const`, and
+ * `export default` ends the module. `eof` here is a module with no
+ * `export default`, which is what "unexpected end" reports.
+ *
+ * @type {(token: DjsTokenWithMetadata) => (state: _InitialState) => _ParserState}
+ */
 const parseInitialOp = ({ token, metadata }) => state => {
     switch (token.kind)
     {
@@ -88,13 +114,17 @@ const parseInitialOp = ({ token, metadata }) => state => {
         case '/*': return state
         case 'id': {
             switch (token.value) {
-                case 'import': return { ...state, state: 'import' }
+                case 'import': return length(state.module.consts) === 0
+                    ? { ...state, state: 'import' }
+                    : { state: 'error', error: { message: 'import must come before const', metadata } }
                 case 'const': return { ...state, state: 'const' }
                 case 'export': return { ...state, state: 'export' }
             }
+            break
         }
+        case 'eof': return { state: 'error', error: { message: 'unexpected end', metadata } }
     }
-    return foldOp({ token, metadata })({ ...state, state: 'exportValue', valueState: '', top: null, stack: null })
+    return { state: 'error', error: { message: 'unexpected token', metadata } }
 }
 
 /** @type {(token: DjsTokenWithMetadata) => (state: _NewLineRequiredState) => _ParserState} */
@@ -230,12 +260,34 @@ const addValueToObject = obj => value => (['object', setReplace(obj[2])(value)(o
 /** @type {(array: _DjsStackArray) => (value: AstConst) => _DjsStackArray} */
 const addToArray = array => value => (['array', concat(array[1])([value])])
 
-/** @type {(state: _ParseValueState) => (key: string) => (metadata: TokenMetadata) => _ParserState} */
-const pushKey = state => key => metadata => {
-    if (state.top?.[0] === 'object') { return { ...state, valueState: '{k', top: addKeyToObject(state.top)(key), stack: state.stack } }
+/**
+ * The key of `{ __proto__: v }` and `{ "__proto__": v }`. JavaScript reads
+ * both as an instruction to replace the object's prototype instead of as a
+ * property, so FunctionalScript rejects them and accepts only the computed
+ * spelling `{ ["__proto__"]: v }`, which denotes an ordinary property.
+ * See [spec: the `__proto__` key](../../../spec/README.md#the-__proto__-key).
+ */
+const protoKey = '__proto__'
+
+/** @type {(valueState: _ValueState) => (state: _ParseValueState) => (key: string) => (metadata: TokenMetadata) => _ParserState} */
+const pushKey = valueState => state => key => metadata => {
+    if (state.top?.[0] === 'object') { return { ...state, valueState, top: addKeyToObject(state.top)(key), stack: state.stack } }
     return { state: 'error', error: { message: 'error', metadata } }
 }
 
+/**
+ * A key written as an identifier or a string literal, which is every key but
+ * the computed one — so this is where `__proto__` is refused. A JSON document
+ * spells that key the same way and means an ordinary property by it, but a
+ * JSON document is not a module and this parser does not read one
+ * ([spec: the `__proto__` key](../../../spec/README.md#the-__proto__-key)).
+ *
+ * @type {(state: _ParseValueState) => (key: string) => (metadata: TokenMetadata) => _ParserState}
+ */
+const pushPlainKey = state => key => metadata => key === protoKey
+    ? { state: 'error', error: { message: '__proto__ requires the computed key form', metadata } }
+    : pushKey('{k')(state)(key)(metadata)
+
 /** @type {(state: _ParseValueState) => (value: AstConst) => _ParserState} */
 const pushValue = state => value => {
     if (state.top === null) {
@@ -302,7 +354,12 @@ const endObject = state => {
     return pushValue(newState)(obj)
 }
 
-/** @type {(token: DjsToken) => AstConst} */
+/**
+ * Only ever called on a token `isValueToken` has already confirmed carries a
+ * value, so the switch covers every `_ValueToken` case with no fallback arm.
+ *
+ * @type {(token: _ValueToken) => AstConst}
+ */
 const tokenToValue = token => {
     switch (token.kind) {
         case 'null': return null
@@ -312,11 +369,13 @@ const tokenToValue = token => {
         case 'string': return token.value
         case 'bigint': return token.value
         case 'undefined': return undefined
-        default: return null
     }
 }
 
-/** @type {(token: DjsToken) => boolean} */
+/**
+ * @param {DjsToken} token
+ * @returns {token is _ValueToken}
+ */
 const isValueToken = token => {
     switch (token.kind) {
         case 'null':
@@ -391,7 +450,8 @@ const parseObjectStartOp = ({ token, metadata }) => state => {
     {
         case 'string':
         case 'id':
-            return pushKey(state)(String(token.value))(metadata)
+            return pushPlainKey(state)(token.value)(metadata)
+        case '[': return { ...state, valueState: '{[' }
         case '}': return endObject(state)
         case 'ws':
         case 'nl':
@@ -402,6 +462,35 @@ const parseObjectStartOp = ({ token, metadata }) => state => {
     }
 }
 
+// computed property keys with a constant string key (#2470)
+/** @type {(token: DjsTokenWithMetadata) => (state: _ParseValueState) => _ParserState} */
+const parseObjectComputedKeyOp = ({ token, metadata }) => state => {
+    switch (token.kind)
+    {
+        case 'string': return pushKey('{[k')(state)(token.value)(metadata)
+        case 'ws':
+        case 'nl':
+        case '//':
+        case '/*': return state
+        case 'eof': return { state: 'error', error: { message: 'unexpected end', metadata } }
+        default: return { state: 'error', error: { message: 'unexpected token', metadata } }
+    }
+}
+
+/** @type {(token: DjsTokenWithMetadata) => (state: _ParseValueState) => _ParserState} */
+const parseObjectComputedKeyEndOp = ({ token, metadata }) => state => {
+    switch (token.kind)
+    {
+        case ']': return { ...state, valueState: '{k' }
+        case 'ws':
+        case 'nl':
+        case '//':
+        case '/*': return state
+        case 'eof': return { state: 'error', error: { message: 'unexpected end', metadata } }
+        default: return { state: 'error', error: { message: 'unexpected token', metadata } }
+    }
+}
+
 /** @type {(token: DjsTokenWithMetadata) => (state: _ParseValueState) => _ParserState} */
 const parseObjectKeyOp = ({ token, metadata }) => state => {
     switch (token.kind)
@@ -455,7 +544,8 @@ const parseObjectCommaOp = ({ token, metadata }) => state => {
         case '}': return endObject(state)
         case 'string':
         case 'id':
-            return pushKey(state)(String(token.value))(metadata)
+            return pushPlainKey(state)(token.value)(metadata)
+        case '[': return { ...state, valueState: '{[' }
         case 'ws':
         case 'nl':
         case '//':
@@ -488,6 +578,8 @@ const foldOp = token => state => {
                 case '[v': return parseArrayValueOp(token)(state)
                 case '[,': return parseValueOp(token)(state)
                 case '{': return parseObjectStartOp(token)(state)
+                case '{[': return parseObjectComputedKeyOp(token)(state)
+                case '{[k': return parseObjectComputedKeyEndOp(token)(state)
                 case '{k': return parseObjectKeyOp(token)(state)
                 case '{:': return parseObjectColonOp(token)(state)
                 case '{v': return parseObjectNextOp(token)(state)
@@ -497,11 +589,20 @@ const foldOp = token => state => {
     }
 }
 
-/** @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>} */
+/**
+ * Reads the token list as a FunctionalScript module: `import` statements, then
+ * `const` statements, then one `export default`.
+ *
+ * This is the only language the parser reads. A JSON document is data, not a
+ * module, and `fjs/media/json` is its reader
+ * ([spec: JSON input](../../../spec/README.md#json-input)).
+ *
+ * @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>}
+ */
 export const parseFromTokens = tokenList => {
     const state = fold(foldOp)({ state: '', module: { refs: null, modules: null, consts: null } })(tokenList)
     switch (state.state) {
-        case 'result': return ok(/** @type {AstModule} */ ([toArray(state.module.modules), toArray(state.module.consts)]))
+        case 'result': return ok(/** @satisfies {AstModule} */ ([toArray(state.module.modules), toArray(state.module.consts)]))
         case 'error': return error(state.error)
         default: return error({ message: 'unexpected end', metadata: null })
     }
@@ -522,7 +623,7 @@ export const proof = {
                 top: null,
                 stack: null,
             }
-            const result = pushKey(state)('key')({ path: 'test', line: 0, column: 0 })
+            const result = pushKey('{k')(state)('key')({ path: 'test', line: 0, column: 0 })
             assertEq(result.state, 'error')
         },
     },
@@ -544,4 +645,22 @@ export const proof = {
             assertEq(result.state, 'result')
         },
     },
+    endObject: {
+        // `endObject` is only ever invoked while `state.top` is an object
+        // (the `'{'`/`'{k'`/`'{:'`/`'{v'`/`'{,'` value-states guarantee it),
+        // so its non-object guard is a defensive branch unreachable through
+        // `parseFromTokens`. Call it directly to cover that branch.
+        nonObjectTop: () => {
+            /** @type {_ParseValueState} */
+            const state = {
+                state: 'exportValue',
+                module: { refs: null, modules: null, consts: null },
+                valueState: '{,',
+                top: null,
+                stack: null,
+            }
+            const result = endObject(state)
+            assertEq(result.state, 'result')
+        },
+    },
 }

package/fjs/djs/parser/proof.f.d.mts

@@ -1,9 +1,16 @@
+/**
+ * @import { DjsTokenWithMetadata } from '../tokenizer/types.ts'
+ */
 export declare const proof: {
     valid: (() => void)[];
+    computedKey: (() => void)[];
+    invalidComputedKey: (() => void)[];
+    protoKey: (() => void)[];
     invalid: (() => void)[];
     errorMetadata: (() => void)[];
     validWhiteSpaces: (() => void)[];
-    validJson: (() => void)[];
+    jsonDocumentIsNotAModule: (() => void)[];
+    statementOrder: (() => void)[];
     invalidModule: (() => void)[];
     validWithConst: (() => void)[];
     invalidWithConst: (() => void)[];

package/fjs/djs/parser/proof.f.mjs

@@ -1,6 +1,9 @@
+/**
+ * @import { DjsTokenWithMetadata } from '../tokenizer/types.ts'
+ */
+
 import { parseFromTokens } from './module.f.mjs'
 import { tokenize } from '../tokenizer/module.f.mjs'
-/** @import { DjsTokenWithMetadata } from '../tokenizer/types.ts' */
 import { toArray } from '../../types/list/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
 import { stringToList } from '../../text/utf16/module.f.mjs'
@@ -156,6 +159,108 @@ export const proof = {
             if (result !== '[[],[{"a":1}]]') { throw result }
         }
     ],
+    // A computed key `["a"]` is a third spelling of an ordinary key, next to
+    // the identifier and the string literal (#2470).
+    computedKey: [
+        () => {
+            const tokenList = tokenizeString('export default {["a"]:1}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'ok', obj)
+            const result = stringifyDjsModule(obj[1])
+            assertEq(result, '[[],[{"a":1}]]')
+        },
+        () => {
+            // all three spellings in one object, plus a trailing comma
+            const tokenList = tokenizeString('export default {a:1,"b":2,["c"]:3,}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'ok', obj)
+            const result = stringifyDjsModule(obj[1])
+            assertEq(result, '[[],[{"a":1,"b":2,"c":3}]]')
+        },
+        () => {
+            // trivia is trivia inside the brackets too
+            const tokenList = tokenizeString('export default { [ /* c */ \n // c \n "a" /* c */ \n // c \n ] : 1 }')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'ok', obj)
+            const result = stringifyDjsModule(obj[1])
+            assertEq(result, '[[],[{"a":1}]]')
+        },
+        () => {
+            // the key that has no other spelling
+            const tokenList = tokenizeString('export default {["__proto__"]:{"a":42}}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'ok', obj)
+            const result = stringifyDjsModule(obj[1])
+            assertEq(result, '[[],[{"__proto__":{"a":42}}]]')
+        },
+    ],
+    invalidComputedKey: [
+        () => {
+            // the brackets hold a string literal, not a number
+            const tokenList = tokenizeString('export default {[1]:2}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // eof inside the brackets, before the key
+            const tokenList = tokenizeString('export default {[')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // the brackets are not closed
+            const tokenList = tokenizeString('export default {["a"}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // eof after the key, before ']'
+            const tokenList = tokenizeString('export default {["a"')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // a computed key still needs its ':'
+            const tokenList = tokenizeString('export default {["a"]}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+    ],
+    // `{__proto__: v}` and `{"__proto__": v}` assign a prototype in JavaScript
+    // instead of adding a property, so FunctionalScript rejects both spellings
+    // and accepts only the computed one (#2480).
+    protoKey: [
+        () => {
+            const tokenList = tokenizeString('export default {__proto__:1}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, '__proto__ requires the computed key form')
+        },
+        () => {
+            const tokenList = tokenizeString('export default {"__proto__":1}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, '__proto__ requires the computed key form')
+        },
+        () => {
+            // the same two spellings after a ',', the parser's other key state
+            const tokenList = tokenizeString('export default {"a":1,__proto__:2}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, '__proto__ requires the computed key form')
+        },
+        () => {
+            const tokenList = tokenizeString('export default {"a":1,"__proto__":2}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, '__proto__ requires the computed key form')
+        },
+    ],
     invalid: [
         () => {
             const tokenList = tokenizeString('export default')
@@ -297,6 +402,115 @@ export const proof = {
             assert(obj[0] === 'error', obj)
             assertEq(obj[1].message, 'unexpected token')
         },
+        () => {
+            // 'export' with no 'default' before eof.
+            const tokenList = tokenizeString('export')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // 'const' with no name before eof.
+            const tokenList = tokenizeString('const')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // 'const <name>' with no '=' before eof.
+            const tokenList = tokenizeString('const x')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // 'const <name>' followed by a token that isn't '='.
+            const tokenList = tokenizeString('const x 5')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // 'import' with no name before eof.
+            const tokenList = tokenizeString('import')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // 'import' followed by a token that isn't an id.
+            const tokenList = tokenizeString('import 5')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // 'import <name>' with no 'from' before eof.
+            const tokenList = tokenizeString('import a')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // 'import <name> from' with no module string before eof.
+            const tokenList = tokenizeString('import a from')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // Array opened but eof arrives before any value/']'.
+            const tokenList = tokenizeString('export default [')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // Object opened but eof arrives before any key/'}'.
+            const tokenList = tokenizeString('export default {')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // Object key given but eof arrives before ':'.
+            const tokenList = tokenizeString('export default {"a"')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // Object ':' given but eof arrives before the value.
+            const tokenList = tokenizeString('export default {"a":')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // Object value given, followed by a token that's neither ',' nor '}'.
+            const tokenList = tokenizeString('export default {"a":1 2}')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // Object ',' given but eof arrives before the next key/'}'.
+            const tokenList = tokenizeString('export default {"a":1,')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // `parseFromTokens` itself, called with no tokens at all (the
+            // tokenizer never produces this — it always emits at least an
+            // `eof` token — but the exported function's own contract must
+            // still handle it: the initial state is neither 'result' nor
+            // 'error', so it falls through to the same "unexpected end".
+            const obj = parseFromTokens(null)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+            assertEq(obj[1].metadata, null)
+        },
     ],
     errorMetadata: [
         () => {
@@ -340,41 +554,92 @@ export const proof = {
             if (result !== '[[],[{"a":0,"b":1}]]') { throw result }
         },
     ],
-    validJson:[
+    // A JSON document is not a module: a statement begins with `import`,
+    // `const`, or `export` and never with a value. `fjs/media/json` is the
+    // reader for these texts.
+    jsonDocumentIsNotAModule: [
         () => {
             const tokenList = tokenizeString('null')
             const obj = parseFromTokens(tokenList)
-            assert(obj[0] === 'ok', obj)
-            const result = stringifyDjsModule(obj[1])
-            assertEq(result, '[[],[null]]')
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
         },
         () => {
             const tokenList = tokenizeString('1')
             const obj = parseFromTokens(tokenList)
-            assert(obj[0] === 'ok', obj)
-            const result = stringifyDjsModule(obj[1])
-            assertEq(result, '[[],[1]]')
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
         },
         () => {
             const tokenList = tokenizeString('[]')
             const obj = parseFromTokens(tokenList)
-            assert(obj[0] === 'ok', obj)
-            const result = stringifyDjsModule(obj[1])
-            assertEq(result, '[[],[["array",[]]]]')
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
         },
         () => {
             const tokenList = tokenizeString('{"valid":"json"}')
             const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // an identifier that is not a statement keyword is no better
+            const tokenList = tokenizeString('a')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
+        () => {
+            // an empty module has no `export default`
+            const tokenList = tokenizeString('')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+        () => {
+            // …and neither has one that only declares constants
+            const tokenList = tokenizeString('const a = 1\n')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end')
+        },
+    ],
+    // Statements are ordered: imports, then constants, then `export default`.
+    statementOrder: [
+        () => {
+            const tokenList = tokenizeString('import a from "a.f.js" \n const b = 1 \n export default [a,b]')
+            const obj = parseFromTokens(tokenList)
             assert(obj[0] === 'ok', obj)
             const result = stringifyDjsModule(obj[1])
-            if (result !== '[[],[{"valid":"json"}]]') { throw result }
-        }
+            assertEq(result, '[["a.f.js"],[1,["array",[["aref",0],["cref",0]]]]]')
+        },
+        () => {
+            const tokenList = tokenizeString('const b = 1 \n import a from "a.f.js" \n export default [a,b]')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'import must come before const')
+        },
+        () => {
+            // nothing follows `export default` but trivia
+            const tokenList = tokenizeString('export default 1 \n const a = 2')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token')
+        },
     ],
     invalidModule:[
         () => {
+            // `module` is not one of the statement keywords
             const tokenList = tokenizeString('module=null')
             const obj = parseFromTokens(tokenList)
             assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected token', obj)
+        },
+        () => {
+            // a reference the module never declared, in a value position
+            const tokenList = tokenizeString('export default a')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
             assertEq(obj[1].message, 'const not found', obj)
         },
         () => {
@@ -439,6 +704,15 @@ export const proof = {
             assert(obj[0] === 'error', obj)
             assertEq(obj[1].message, 'duplicate id', obj)
         },
+        () => {
+            // No newline after the const's value: the parser hits `eof` while
+            // still in the newline-required state, instead of the following
+            // `nl` token every other `const` test provides.
+            const tokenList = tokenizeString('const a = 1')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end', obj)
+        },
     ],
     validWithArgs:[
         () => {

package/fjs/djs/parser/types.d.ts

@@ -1,11 +1,17 @@
 /**
  * Type-level API for `fjs/djs/parser/module.f.mjs`: the `ParseError` shape
- * `parseFromTokens` reports.
+ * `parseFromTokens` reports, and the `_ValueToken` subset `tokenToValue`
+ * accepts.
  *
  * @module
  */
 import type { TokenMetadata } from '../../js/tokenizer/types.ts';
+import type { DjsToken } from '../tokenizer/types.ts';
 export type ParseError = {
     readonly message: string;
     readonly metadata: TokenMetadata | null;
 };
+/** DJS tokens that carry a directly-usable value. */
+export type _ValueToken = Extract<DjsToken, {
+    readonly kind: 'null' | 'false' | 'true' | 'undefined' | 'string' | 'number' | 'bigint';
+}>;