@ldclabs/kip-lang 0.3.0 → 0.4.0

package/dist/parser.js

@@ -20,6 +20,7 @@ class Parser {
         const start = this.currentPos();
         this.skipComments();
         while (!this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.isAtEnd())
                 break;
@@ -32,6 +33,11 @@ class Parser {
                 // Error recovery: skip to next statement-level keyword
                 this.recoverToNextStatement();
             }
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         const end = this.currentPos();
         return {
@@ -74,6 +80,7 @@ class Parser {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
         this.expect(TokenType.Find);
+        const lparen = this.current();
         this.expect(TokenType.LParen);
         const projections = [];
         if (!this.check(TokenType.RParen)) {
@@ -82,6 +89,9 @@ class Parser {
                 projections.push(this.parseExpression());
             }
         }
+        if (projections.length === 0) {
+            this.error(`FIND must declare at least one output expression, e.g. FIND(?var)`, lparen);
+        }
         this.expect(TokenType.RParen);
         let where;
         let orderBy;
@@ -116,11 +126,12 @@ class Parser {
     parseUpsertStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Upsert);
+        this.expectKeywordWithSpace(TokenType.Upsert);
         this.expect(TokenType.LBrace);
         const blocks = [];
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.Concept)) {
                 blocks.push(this.parseConceptBlock());
@@ -136,6 +147,11 @@ class Parser {
                 this.advance();
             }
             this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         this.expect(TokenType.RBrace);
         let metadata;
@@ -153,8 +169,12 @@ class Parser {
     parseConceptBlock() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Concept);
-        const handle = this.expectVariable();
+        this.expectKeywordWithSpace(TokenType.Concept);
+        // The handle is optional: a block nothing else refers to needs no name.
+        let handle;
+        if (this.check(TokenType.Variable)) {
+            handle = this.expectVariable();
+        }
         this.expect(TokenType.LBrace);
         const matcher = this.parseConceptMatcher();
         let expectVersion;
@@ -166,16 +186,17 @@ class Parser {
         let metadata;
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.Set)) {
                 const setStart = this.currentPos();
-                this.advance(); // skip SET
+                const setTok = this.advance(); // skip SET
                 if (this.check(TokenType.Attributes)) {
-                    this.advance();
+                    this.expectSecondWord(TokenType.Attributes, setTok);
                     setAttributes = this.parseSetAttributesBody(setStart);
                 }
                 else if (this.check(TokenType.Propositions)) {
-                    this.advance();
+                    this.expectSecondWord(TokenType.Propositions, setTok);
                     setPropositions = this.parseSetPropositionsBody(setStart);
                 }
                 else {
@@ -197,6 +218,11 @@ class Parser {
                 this.advance();
             }
             this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         this.expect(TokenType.RBrace);
         // Concept-level WITH METADATA (outside the CONCEPT braces)
@@ -218,7 +244,7 @@ class Parser {
     parsePropositionBlock() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Proposition);
+        this.expectKeywordWithSpace(TokenType.Proposition);
         let handle;
         if (this.check(TokenType.Variable)) {
             handle = this.expectVariable();
@@ -233,12 +259,13 @@ class Parser {
         let metadata;
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.Set)) {
                 const setStart = this.currentPos();
-                this.advance();
+                const setTok = this.advance();
                 if (this.check(TokenType.Attributes)) {
-                    this.advance();
+                    this.expectSecondWord(TokenType.Attributes, setTok);
                     setAttributes = this.parseSetAttributesBody(setStart);
                 }
                 else {
@@ -250,9 +277,15 @@ class Parser {
                 break;
             }
             else {
+                this.error(`Unexpected token '${this.current().value}' in PROPOSITION block`, this.current());
                 this.advance();
             }
             this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         this.expect(TokenType.RBrace);
         if (this.check(TokenType.With)) {
@@ -278,20 +311,21 @@ class Parser {
     parseUpdateStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Update);
+        this.expectKeywordWithSpace(TokenType.Update);
         const target = this.expectVariable();
         let setAttributes;
         let setMetadata;
         this.skipComments();
         while (this.check(TokenType.Set) && !this.isAtEnd()) {
+            const before = this.pos;
             const setStart = this.currentPos();
-            this.advance();
+            const setTok = this.advance();
             if (this.check(TokenType.Attributes)) {
-                this.advance();
+                this.expectSecondWord(TokenType.Attributes, setTok);
                 setAttributes = this.parseSetAttributesBody(setStart);
             }
             else if (this.check(TokenType.Metadata)) {
-                this.advance();
+                this.expectSecondWord(TokenType.Metadata, setTok);
                 setMetadata = this.parseSetMetadataBody(setStart);
             }
             else {
@@ -299,6 +333,11 @@ class Parser {
                 this.advance();
             }
             this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         if (!setAttributes && !setMetadata) {
             this.error(`Expected SET ATTRIBUTES or SET METADATA in UPDATE statement`, this.current());
@@ -325,8 +364,8 @@ class Parser {
     parseMergeStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Merge);
-        this.expect(TokenType.Concept);
+        const mergeTok = this.expect(TokenType.Merge);
+        this.expectSecondWord(TokenType.Concept, mergeTok);
         const source = this.expectVariable();
         this.expect(TokenType.Into);
         const target = this.expectVariable();
@@ -346,7 +385,7 @@ class Parser {
     parseDeleteStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Delete);
+        this.expectKeywordWithSpace(TokenType.Delete);
         let deleteType;
         let keys;
         let target;
@@ -419,7 +458,7 @@ class Parser {
     parseDescribeStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Describe);
+        this.expectKeywordWithSpace(TokenType.Describe);
         let describeType;
         let typeName;
         let typeNameValue;
@@ -434,14 +473,14 @@ class Parser {
             this.advance();
         }
         else if (this.check(TokenType.Concept)) {
-            this.advance();
+            const headTok = this.advance();
             if (this.check(TokenType.Types)) {
                 describeType = 'CONCEPT_TYPES';
-                this.advance();
+                this.expectSecondWord(TokenType.Types, headTok);
             }
             else if (this.check(TokenType.Type)) {
                 describeType = 'CONCEPT_TYPE';
-                this.advance();
+                this.expectSecondWord(TokenType.Type, headTok);
                 typeNameValue = this.parseStringOrParameterValue('DESCRIBE CONCEPT TYPE');
                 typeName =
                     typeNameValue.kind === 'StringLiteral'
@@ -454,14 +493,14 @@ class Parser {
             }
         }
         else if (this.check(TokenType.Proposition)) {
-            this.advance();
+            const headTok = this.advance();
             if (this.check(TokenType.Types)) {
                 describeType = 'PROPOSITION_TYPES';
-                this.advance();
+                this.expectSecondWord(TokenType.Types, headTok);
             }
             else if (this.check(TokenType.Type)) {
                 describeType = 'PROPOSITION_TYPE';
-                this.advance();
+                this.expectSecondWord(TokenType.Type, headTok);
                 typeNameValue = this.parseStringOrParameterValue('DESCRIBE PROPOSITION TYPE');
                 typeName =
                     typeNameValue.kind === 'StringLiteral'
@@ -477,10 +516,18 @@ class Parser {
             this.error(`Expected PRIMER, DOMAINS, CONCEPT, or PROPOSITION after DESCRIBE`, this.current());
             describeType = 'PRIMER';
         }
+        // Only the plural `... TYPES` forms are paginated (§5.1.3 / §5.1.5).
+        const paginable = describeType === 'CONCEPT_TYPES' || describeType === 'PROPOSITION_TYPES';
         if (this.check(TokenType.Limit)) {
+            if (!paginable) {
+                this.error(`LIMIT is only valid on DESCRIBE CONCEPT TYPES / PROPOSITION TYPES`, this.current());
+            }
             limit = this.parseLimitClause();
         }
         if (this.check(TokenType.Cursor)) {
+            if (!paginable) {
+                this.error(`CURSOR is only valid on DESCRIBE CONCEPT TYPES / PROPOSITION TYPES`, this.current());
+            }
             cursor = this.parseCursorClause();
         }
         return {
@@ -500,15 +547,15 @@ class Parser {
     parseSearchStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Search);
+        this.expectKeywordWithSpace(TokenType.Search);
         let searchTarget;
         if (this.check(TokenType.Concept)) {
             searchTarget = 'CONCEPT';
-            this.advance();
+            this.expectKeywordWithSpace(TokenType.Concept);
         }
         else if (this.check(TokenType.Proposition)) {
             searchTarget = 'PROPOSITION';
-            this.advance();
+            this.expectKeywordWithSpace(TokenType.Proposition);
         }
         else {
             this.error(`Expected CONCEPT or PROPOSITION after SEARCH`, this.current());
@@ -522,10 +569,15 @@ class Parser {
         let modeValue;
         let threshold;
         let limit;
+        // Clauses may appear in any order but each at most once — a second
+        // `LIMIT` is trailing input, not an override.
         while (!this.isAtEnd()) {
+            const before = this.pos;
+            const clause = this.current();
             if (this.check(TokenType.With)) {
-                this.advance();
-                this.expect(TokenType.Type);
+                this.rejectRepeat(withTypeValue, 'WITH TYPE', clause);
+                const withTok = this.advance();
+                this.expectSecondWord(TokenType.Type, withTok);
                 withTypeValue = this.parseStringOrParameterValue('SEARCH WITH TYPE');
                 withType =
                     withTypeValue.kind === 'StringLiteral'
@@ -533,20 +585,28 @@ class Parser {
                         : withTypeValue.name;
             }
             else if (this.check(TokenType.Mode)) {
+                this.rejectRepeat(modeValue, 'MODE', clause);
                 this.advance();
                 modeValue = this.parseStringOrParameterValue('SEARCH MODE');
                 mode =
                     modeValue.kind === 'StringLiteral' ? modeValue.parsed : modeValue.name;
             }
             else if (this.check(TokenType.Threshold)) {
+                this.rejectRepeat(threshold, 'THRESHOLD', clause);
                 threshold = this.parseThresholdClause();
             }
             else if (this.check(TokenType.Limit)) {
+                this.rejectRepeat(limit, 'LIMIT', clause);
                 limit = this.parseLimitClause();
             }
             else {
                 break;
             }
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         return {
             kind: 'SearchStatement',
@@ -569,18 +629,23 @@ class Parser {
     parseExportStatement() {
         const start = this.currentPos();
         const comments = this.collectLeadingComments();
-        this.expect(TokenType.Export);
+        this.expectKeywordWithSpace(TokenType.Export);
         const target = this.expectVariable();
         const where = this.parseWhereClause();
         let limit;
+        let cursor;
         if (this.check(TokenType.Limit)) {
             limit = this.parseLimitClause();
         }
+        if (this.check(TokenType.Cursor)) {
+            cursor = this.parseCursorClause();
+        }
         return {
             kind: 'ExportStatement',
             target,
             where,
             limit,
+            cursor,
             range: { start, end: this.currentPos() },
             leadingComments: comments.length > 0 ? comments : undefined
         };
@@ -604,6 +669,7 @@ class Parser {
         const patterns = [];
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.RBrace))
                 break;
@@ -611,6 +677,11 @@ class Parser {
             if (pattern)
                 patterns.push(pattern);
             this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         return patterns;
     }
@@ -678,8 +749,12 @@ class Parser {
     }
     parseConceptMatcher() {
         const start = this.currentPos();
-        this.expect(TokenType.LBrace);
-        const entries = this.parseObjectEntries();
+        const brace = this.expect(TokenType.LBrace);
+        const seen = { trailingComma: false };
+        const entries = this.parseObjectEntries(seen);
+        if (seen.trailingComma) {
+            this.error(`A concept matcher takes no trailing comma`, brace);
+        }
         this.expect(TokenType.RBrace);
         return {
             kind: 'ConceptMatcher',
@@ -820,17 +895,11 @@ class Parser {
     parseHopRange() {
         const start = this.currentPos();
         this.expect(TokenType.LBrace);
-        const minTok = this.current();
-        if (minTok.type !== TokenType.Number) {
-            this.error(`Expected number in hop range`, minTok);
-        }
-        const min = Number(minTok.value);
-        this.advance();
+        const min = this.expectHopCount();
         let max;
         if (this.match(TokenType.Comma)) {
             if (this.check(TokenType.Number)) {
-                max = Number(this.current().value);
-                this.advance();
+                max = this.expectHopCount();
             }
             // else: {m,} means unbounded
         }
@@ -845,6 +914,27 @@ class Parser {
             range: { start, end: this.currentPos() }
         };
     }
+    /**
+     * Reads one bound of a `{m,n}` hop quantifier.
+     *
+     * A hop count is a plain 16-bit integer — no sign, no decimal point, no
+     * exponent. `"p"{1e9,}` is not an enormous traversal, it is a typo, and
+     * accepting it would hand the engine a bound it cannot honour.
+     */
+    expectHopCount() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Number || !/^[0-9]+$/.test(tok.value)) {
+            this.error(`Expected a whole number in a hop range`, tok);
+            this.advance();
+            return 0;
+        }
+        const value = Number(tok.value);
+        if (value > 0xffff) {
+            this.error(`Hop count ${tok.value} exceeds the maximum of 65535`, tok);
+        }
+        this.advance();
+        return value;
+    }
     parseFilterClause() {
         const start = this.currentPos();
         this.expect(TokenType.Filter);
@@ -921,11 +1011,22 @@ class Parser {
         const items = [];
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.RBrace))
                 break;
             items.push(this.parsePropositionItem());
             this.skipComments();
+            // Items are juxtaposed, but a separating comma — including a trailing
+            // one — is tolerated. Generated KML reaches for it constantly, and the
+            // reference grammar accepts it.
+            this.match(TokenType.Comma);
+            this.skipComments();
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         this.expect(TokenType.RBrace);
         return {
@@ -954,8 +1055,19 @@ class Parser {
         };
     }
     isIdMatcherStart() {
-        const next = this.tokens[this.pos + 1];
-        return this.isIdKeyToken(this.current()) && next?.type === TokenType.Colon;
+        if (!this.isIdKeyToken(this.current()))
+            return false;
+        const next = this.peekPast(this.pos + 1);
+        // `(id: "...")` may be written with a comment between the key and the
+        // colon; comments are trivia everywhere else, so they are here too.
+        return (next?.type === TokenType.Colon ||
+            (next?.type === TokenType.Parameter && next.value.startsWith(':')));
+    }
+    /** The first non-comment token at or after `i`. */
+    peekPast(i) {
+        while (this.tokens[i]?.type === TokenType.Comment)
+            i++;
+        return this.tokens[i];
     }
     parseIdMatcherValue() {
         const keyTok = this.current();
@@ -974,7 +1086,7 @@ class Parser {
             return {
                 kind: 'StringLiteral',
                 value: tok.value,
-                parsed: this.unescapeString(tok.value),
+                parsed: this.unescapeString(tok.value, tok),
                 range: { start, end: this.currentPos() }
             };
         }
@@ -1000,8 +1112,8 @@ class Parser {
     }
     parseWithMetadata() {
         const start = this.currentPos();
-        this.expect(TokenType.With);
-        this.expect(TokenType.Metadata);
+        const withTok = this.expect(TokenType.With);
+        this.expectSecondWord(TokenType.Metadata, withTok);
         this.expect(TokenType.LBrace);
         const entries = this.parseObjectEntries();
         this.expect(TokenType.RBrace);
@@ -1013,8 +1125,8 @@ class Parser {
     }
     parseExpectVersion() {
         const start = this.currentPos();
-        this.expect(TokenType.Expect);
-        this.expect(TokenType.Version);
+        const expectTok = this.expect(TokenType.Expect);
+        this.expectSecondWord(TokenType.Version, expectTok);
         const value = this.parseNumberOrParameterValue('EXPECT VERSION');
         return {
             kind: 'ExpectVersion',
@@ -1027,8 +1139,8 @@ class Parser {
     // ────────────────────────────────────────────────────────────────────
     parseOrderBy() {
         const start = this.currentPos();
-        this.expect(TokenType.Order);
-        this.expect(TokenType.By);
+        const orderTok = this.expect(TokenType.Order);
+        this.expectSecondWord(TokenType.By, orderTok);
         const keys = [];
         keys.push(this.parseOrderByKey());
         while (this.match(TokenType.Comma)) {
@@ -1064,7 +1176,7 @@ class Parser {
     }
     parseThresholdClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Threshold);
+        this.expectKeywordWithSpace(TokenType.Threshold);
         const value = this.parseNumberOrParameterValue('THRESHOLD');
         return {
             kind: 'ThresholdClause',
@@ -1107,7 +1219,7 @@ class Parser {
     }
     parseLimitClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Limit);
+        this.expectKeywordWithSpace(TokenType.Limit);
         const value = this.parseNumberOrParameterValue('LIMIT');
         return {
             kind: 'LimitClause',
@@ -1117,14 +1229,14 @@ class Parser {
     }
     parseCursorClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Cursor);
+        this.expectKeywordWithSpace(TokenType.Cursor);
         const tok = this.current();
         let value;
         if (tok.type === TokenType.String) {
             value = {
                 kind: 'StringLiteral',
                 value: tok.value,
-                parsed: this.unescapeString(tok.value),
+                parsed: this.unescapeString(tok.value, tok),
                 range: { start: this.currentPos(), end: this.currentPos() }
             };
             this.advance();
@@ -1247,13 +1359,27 @@ class Parser {
                 name,
                 range: { start, end: this.currentPos() }
             };
-            // Dot access chain
+            // Dot access chain. A dot path is written with no whitespace anywhere
+            // inside it: `?x.name` is a path, but `?x. name` is a path followed by
+            // stray input, and reading them alike would let `ORDER BY ?x.name. ASC`
+            // silently sort by a field named `ASC` with no direction.
+            let prevEnd = tok.offset + tok.value.length;
             while (this.check(TokenType.Dot)) {
+                const dotTok = this.current();
+                if (dotTok.offset !== prevEnd) {
+                    this.error(`Unexpected whitespace before '.' in a dot path`, dotTok);
+                    break;
+                }
                 this.advance();
                 const propTok = this.current();
+                if (propTok.offset !== dotTok.offset + 1) {
+                    this.error(`Expected property name after '.'`, propTok);
+                    break;
+                }
                 if (propTok.type === TokenType.Identifier ||
                     this.isNonAmbiguousKeyword(propTok.type)) {
                     const prop = propTok.value;
+                    prevEnd = propTok.offset + propTok.value.length;
                     this.advance();
                     expr = {
                         kind: 'DotExpression',
@@ -1284,7 +1410,7 @@ class Parser {
             return {
                 kind: 'StringLiteral',
                 value: tok.value,
-                parsed: this.unescapeString(tok.value),
+                parsed: this.unescapeString(tok.value, tok),
                 range: { start, end: this.currentPos() }
             };
         }
@@ -1329,6 +1455,7 @@ class Parser {
         }
         // System identifier as literal
         if (tok.type === TokenType.SystemIdent) {
+            this.error(`Unquoted value '${tok.value}': KIP values are JSON values, so write "${tok.value}"`, tok);
             this.advance();
             return {
                 kind: 'StringLiteral',
@@ -1337,8 +1464,12 @@ class Parser {
                 range: { start, end: this.currentPos() }
             };
         }
-        // Identifier (bare word — could be used as a key value)
+        // A bare word is not a KIP value — only object *keys* may go unquoted, and
+        // those never reach here. Recover as a string so the tree stays usable in
+        // an editor, and report it: `lower` sees only the tree, so it is the
+        // caller's error-diagnostic check that keeps this reading off the wire.
         if (tok.type === TokenType.Identifier) {
+            this.error(`Unquoted value '${tok.value}': KIP values are JSON values, so write "${tok.value}"`, tok);
             this.advance();
             return {
                 kind: 'StringLiteral',
@@ -1389,13 +1520,16 @@ class Parser {
         const start = this.currentPos();
         this.expect(TokenType.LBracket);
         const elements = [];
+        let trailingComma = false;
         this.skipComments();
         if (!this.check(TokenType.RBracket)) {
             elements.push(this.parseExpression());
             while (this.match(TokenType.Comma)) {
                 this.skipComments();
-                if (this.check(TokenType.RBracket))
+                if (this.check(TokenType.RBracket)) {
+                    trailingComma = true;
                     break;
+                }
                 elements.push(this.parseExpression());
             }
         }
@@ -1404,30 +1538,34 @@ class Parser {
         return {
             kind: 'ArrayLiteral',
             elements,
+            trailingComma,
             range: { start, end: this.currentPos() }
         };
     }
     parseObjectLiteral() {
         const start = this.currentPos();
         this.expect(TokenType.LBrace);
-        const entries = this.parseObjectEntries();
+        const seen = { trailingComma: false };
+        const entries = this.parseObjectEntries(seen);
         this.expect(TokenType.RBrace);
         return {
             kind: 'ObjectLiteral',
             entries,
+            trailingComma: seen.trailingComma,
             range: { start, end: this.currentPos() }
         };
     }
-    parseObjectEntries() {
+    parseObjectEntries(seen) {
         const entries = [];
         this.skipComments();
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
             this.skipComments();
             if (this.check(TokenType.RBrace))
                 break;
             const entryStart = this.currentPos();
             const { key, isQuoted } = this.expectKeyWithQuoting();
-            this.expect(TokenType.Colon);
+            this.expectObjectColon(key);
             const value = this.parseExpression();
             entries.push({
                 kind: 'ObjectEntry',
@@ -1441,9 +1579,16 @@ class Parser {
                 break;
             if (this.match(TokenType.Comma)) {
                 this.skipComments();
+                if (seen && this.check(TokenType.RBrace))
+                    seen.trailingComma = true;
                 continue;
             }
             this.error(`Expected ',' or '}' after object entry`, this.current());
+            // A sub-parser that rejects its first token reports and returns
+            // without consuming it, so a loop keyed on that token would spin
+            // forever building diagnostics. Stop as soon as nothing moved.
+            if (this.pos === before)
+                break;
         }
         return entries;
     }
@@ -1491,6 +1636,28 @@ class Parser {
         }
         return this.advance();
     }
+    /**
+     * Consumes a keyword that the grammar requires to be followed by whitespace.
+     *
+     * Most KIP keywords only need a word boundary, so `WHERE{...}` is legal.
+     * A handful — the statement introducers and the clause keywords whose
+     * operand may itself start with a brace or a quote — require real
+     * whitespace, which is what keeps `UPSERT{` from reading as a statement.
+     * The distinction is per-keyword-position, not per-keyword, so it lives at
+     * the call site rather than in the lexer.
+     */
+    expectKeywordWithSpace(type) {
+        const tok = this.current();
+        if (tok.type !== type) {
+            this.error(`Expected '${type}' but got '${tok.value}'`, tok);
+            return tok;
+        }
+        const after = this.source[tok.offset + tok.value.length] ?? '';
+        if (after !== ' ' && after !== '\t' && after !== '\r' && after !== '\n') {
+            this.error(`'${tok.value}' must be followed by whitespace`, tok, 'KIP_1001');
+        }
+        return this.advance();
+    }
     expectVariable() {
         const tok = this.current();
         if (tok.type !== TokenType.Variable) {
@@ -1507,7 +1674,7 @@ class Parser {
             return '';
         }
         this.advance();
-        return this.unescapeString(tok.value);
+        return this.unescapeString(tok.value, tok);
     }
     expectStringValue() {
         const tok = this.current();
@@ -1516,29 +1683,13 @@ class Parser {
             return '';
         }
         this.advance();
-        return this.unescapeString(tok.value);
-    }
-    expectKey() {
-        const tok = this.current();
-        // Keys can be identifiers, strings, or even some keywords used as keys
-        if (tok.type === TokenType.String) {
-            this.advance();
-            return this.unescapeString(tok.value);
-        }
-        if (tok.type === TokenType.Identifier ||
-            this.isNonAmbiguousKeyword(tok.type)) {
-            this.advance();
-            return tok.value;
-        }
-        this.error(`Expected object key but got '${tok.value}'`, tok);
-        this.advance();
-        return tok.value;
+        return this.unescapeString(tok.value, tok);
     }
     expectKeyWithQuoting() {
         const tok = this.current();
         if (tok.type === TokenType.String) {
             this.advance();
-            return { key: this.unescapeString(tok.value), isQuoted: true };
+            return { key: this.unescapeString(tok.value, tok), isQuoted: true };
         }
         if (tok.type === TokenType.Identifier ||
             this.isNonAmbiguousKeyword(tok.type)) {
@@ -1549,6 +1700,12 @@ class Parser {
         this.advance();
         return { key: tok.value, isQuoted: false };
     }
+    /** Reports a clause written twice in a statement that allows it once. */
+    rejectRepeat(seen, name, tok) {
+        if (seen !== undefined) {
+            this.error(`Duplicate ${name} clause`, tok);
+        }
+    }
     skipComments() {
         while (this.pos < this.tokens.length &&
             this.current().type === TokenType.Comment) {
@@ -1565,6 +1722,62 @@ class Parser {
         }
         return comments;
     }
+    /**
+     * Consume the `:` separating an object key from its value. A colon written
+     * with no space before an identifier value (e.g. `status:active`) is lexed as
+     * a single parameter placeholder token (`:active`), so surface a targeted hint
+     * instead of the generic "Expected ':'" message.
+     */
+    /**
+     * Consumes the second word of a two-word keyword (`SET ATTRIBUTES`,
+     * `ORDER BY`, `EXPECT VERSION`, ...).
+     *
+     * The grammar joins these with whitespace only. A comment between the words
+     * is not a smaller gap, it is a different token sequence, and reading
+     * `SET//c\nMETADATA` as `SET METADATA` would accept text the reference
+     * grammar rejects.
+     */
+    expectSecondWord(type, first) {
+        const tok = this.current();
+        const gap = this.source.slice(first.offset + first.value.length, tok.offset);
+        if (tok.type === type && !/^\s+$/.test(gap)) {
+            this.error(`'${first.value} ${tok.value}' must be separated by whitespace only`, tok);
+        }
+        return this.expect(type);
+    }
+    expectObjectColon(_key) {
+        if (this.check(TokenType.Colon)) {
+            this.advance();
+            return;
+        }
+        // `{"a":true}` lexes as a key followed by the parameter `:true`, because
+        // `:name` is the placeholder syntax and the lexer cannot see that this
+        // colon separates a key from its value. In key position the separator
+        // reading is the only valid one, so split the token back apart and re-lex
+        // the tail as the value.
+        const tok = this.current();
+        if (tok.type === TokenType.Parameter) {
+            this.splitParameterAfterColon(tok);
+            return;
+        }
+        this.expect(TokenType.Colon);
+    }
+    /**
+     * Rewrites a `:value` parameter token in separator position into the value
+     * tokens it spells, so the parser sees `: value`.
+     */
+    splitParameterAfterColon(tok) {
+        const tail = tok.value.slice(1);
+        const retoken = tokenize(tail)
+            .filter((t) => !isTrivia(t.type) && t.type !== TokenType.EOF)
+            .map((t) => ({
+            ...t,
+            offset: tok.offset + 1 + t.offset,
+            line: tok.line,
+            column: tok.column + 1 + t.column
+        }));
+        this.tokens.splice(this.pos, 1, ...retoken);
+    }
     isFunctionToken(type) {
         return (type === TokenType.Count ||
             type === TokenType.Sum ||
@@ -1607,15 +1820,31 @@ class Parser {
             type === TokenType.Mode ||
             type === TokenType.Threshold);
     }
-    unescapeString(raw) {
-        if (raw.startsWith('"') && raw.endsWith('"')) {
+    /**
+     * Reads the value of a string token.
+     *
+     * KIP strings are JSON strings, so `"a\xb"` and an unterminated literal are
+     * both errors — but an editor still wants a tree, so the malformed value is
+     * recovered leniently *and* reported. The lenient reading survives into the
+     * tree: `lower` is handed a `Program` and never sees a diagnostic, so a
+     * caller must reject on `severity === 'error'` before lowering, or `"a\xb"`
+     * reaches the engine as `axb`.
+     */
+    unescapeString(raw, tok) {
+        if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
             try {
                 return JSON.parse(raw);
             }
             catch {
+                if (tok) {
+                    this.error(`Invalid string literal ${raw}: KIP strings are JSON strings`, tok);
+                }
                 raw = raw.slice(1, -1);
             }
         }
+        else if (tok) {
+            this.error(`Unterminated string literal ${raw}`, tok);
+        }
         return raw.replace(/\\(.)/g, (_, ch) => {
             switch (ch) {
                 case 'n':
@@ -1635,7 +1864,7 @@ class Parser {
             }
         });
     }
-    error(message, token) {
+    error(message, token, code = 'KIP_1001') {
         this.diagnostics.push({
             range: {
                 start: { line: token.line, column: token.column },
@@ -1643,7 +1872,7 @@ class Parser {
             },
             severity: 'error',
             message,
-            code: 'KIP_PARSE'
+            code
         });
     }
     recoverToNextStatement() {