@xdbml/parse 0.4.0 → 0.5.1

package/dist/name-resolver.js

@@ -1,5 +1,5 @@
 /**
- * Name resolution pass (spec §26.10 / §26.15, parser batch P6).
+ * Name resolution pass (spec §27.10 / §27.15, parser batch P6).
  *
  * `resolveNames(doc)` walks an xDBML document (the flattened view; clone
  * blocks have been merged) and produces:
@@ -41,6 +41,7 @@
 import { SCALAR_TYPES, BSON_TYPES } from "./keywords.js";
 import { flatten } from "./module-resolver.js";
 import { checkRelationships } from "./relationships.js";
+import { checkSupertypeGroups } from "./supertypes.js";
 /**
  * Read-only handle on the collected symbol table.
  *
@@ -95,11 +96,18 @@ export class SymbolTable {
  * Built-in type recognition
  *
  * Field type expressions can name a builtin scalar (`int`, `varchar`),
- * a BSON type (`objectId`), or a user-defined Named Type (`Email`).
- * The parser doesn't distinguish at parse time -- they all land as
+ * a BSON type (`objectId`), a user-defined Named Type (`Email`) or Enum,
+ * or any other target-native type (`number`, `clob`, `serial`). The
+ * parser doesn't distinguish at parse time -- they all land as
  * ScalarType nodes (or NamedTypeReference in some contexts). The
- * resolver uses these sets to decide whether to look up a name in the
- * symbol table.
+ * resolver uses these sets only to skip the symbol-table lookup for
+ * names that can never be a Named Type reference.
+ *
+ * The sets are not a type vocabulary. Scalar type names pass through
+ * as written (spec §1.2, principle 4), so a name that is neither a
+ * builtin nor a declared Type or Enum is a target-native type, not an
+ * error. See `nearMissTypeName()` for the one diagnostic such a name
+ * can raise.
  *
  * Matching is case-insensitive: `Int`, `int`, `INT` all map to the same
  * builtin per spec §3.8.
@@ -111,6 +119,87 @@ const BUILTIN_TYPES = new Set([
 function isBuiltinType(name) {
     return BUILTIN_TYPES.has(name.toLowerCase());
 }
+/**
+ * The declared Types and Enums a bare type name can refer to. More than
+ * one entry means the name is declared in several containers (Enums can
+ * be container-scoped); the name still refers to a declaration, so it
+ * is neither a target-native type nor a near miss.
+ */
+function typeOrEnumDeclarations(name, symbols) {
+    const qualified = symbols.lookup(name);
+    if (qualified && (qualified.kind === 'type' || qualified.kind === 'enum'))
+        return [qualified];
+    return symbols.lookupAllBare(name).filter((e) => e.kind === 'type' || e.kind === 'enum');
+}
+/**
+ * Near-miss detection for target-native type names.
+ *
+ * A type name that is neither a builtin nor a declared Type or Enum is
+ * accepted as a target-native type. The one case worth flagging is a
+ * name that differs only slightly from a declared Type or Enum -- most
+ * likely a misspelling (`Adress` for `Address`, `email` for `Email`).
+ * Returns the declared name to suggest, or undefined when nothing is
+ * close enough.
+ *
+ * Comparison is case-insensitive, so a difference of case alone counts
+ * as a near miss (identifiers are case-sensitive, spec §3.8). The edit
+ * distance allowed grows with the length of the name: none beyond case
+ * for three characters or fewer, one edit up to seven characters, two
+ * edits from eight. An adjacent transposition counts as one edit.
+ */
+function nearMissTypeName(name, symbols) {
+    const lower = name.toLowerCase();
+    const maxDistance = lower.length <= 3 ? 0 : lower.length <= 7 ? 1 : 2;
+    // A qualified name (`core.job_stauts`) compares against qualified
+    // declarations, a bare name against bare ones.
+    const qualified = name.includes('.');
+    let best;
+    for (const entry of symbols.entries()) {
+        if (entry.kind !== 'type' && entry.kind !== 'enum')
+            continue;
+        const declared = qualified ? entry.qualifiedName : entry.name;
+        const candidate = declared.toLowerCase();
+        if (Math.abs(candidate.length - lower.length) > maxDistance)
+            continue;
+        const distance = editDistance(lower, candidate, maxDistance);
+        if (distance <= maxDistance && (!best || distance < best.distance)) {
+            best = { name: declared, distance };
+        }
+    }
+    return best?.name;
+}
+/**
+ * Optimal string alignment distance (Levenshtein plus adjacent
+ * transposition). Returns `limit + 1` as soon as every alignment of a
+ * row exceeds `limit`, since callers only compare against the limit.
+ */
+function editDistance(a, b, limit) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const d = [];
+    for (let i = 0; i < rows; i++) {
+        d.push(new Array(cols).fill(0));
+        d[i][0] = i;
+    }
+    for (let j = 0; j < cols; j++)
+        d[0][j] = j;
+    for (let i = 1; i < rows; i++) {
+        let rowMin = Infinity;
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let v = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                v = Math.min(v, d[i - 2][j - 2] + 1);
+            }
+            d[i][j] = v;
+            if (v < rowMin)
+                rowMin = v;
+        }
+        if (rowMin > limit)
+            return limit + 1;
+    }
+    return d[rows - 1][cols - 1];
+}
 /* -------------------------------------------------------------------------
  * Main entry point
  * ----------------------------------------------------------------------- */
@@ -137,6 +226,8 @@ export function resolveNames(doc) {
     resolveReferences(flat, symbols, diagnostics);
     // Pass 3: relationship rules that the grammar cannot express (spec 11.11).
     diagnostics.push(...checkRelationships(flat));
+    // Pass 4: supertype group rules (spec 12.8).
+    diagnostics.push(...checkSupertypeGroups(flat));
     return { diagnostics, symbols };
 }
 /* -------------------------------------------------------------------------
@@ -156,9 +247,20 @@ function addTopLevelDeclaration(stmt, entries, diagnostics, seen) {
         case 'TypeDeclaration':
             addEntry(stmt.name, undefined, 'type', stmt, stmt.span, entries, diagnostics, seen);
             return;
-        case 'EnumDeclaration':
-            addEntry(stmt.name, undefined, 'enum', stmt, stmt.span, entries, diagnostics, seen);
+        case 'EnumDeclaration': {
+            // `enum core.job_status { ... }` (the DBML form) files the Enum
+            // under container `core`, exactly as `Container core { Enum
+            // job_status { ... } }` does: same qualified name, same bare name,
+            // and declaring both is a duplicate (spec §16).
+            const dot = stmt.name.lastIndexOf('.');
+            if (dot > 0) {
+                addEntry(stmt.name.slice(dot + 1), stmt.name.slice(0, dot), 'enum', stmt, stmt.span, entries, diagnostics, seen);
+            }
+            else {
+                addEntry(stmt.name, undefined, 'enum', stmt, stmt.span, entries, diagnostics, seen);
+            }
             return;
+        }
         case 'EdgeDeclaration':
             addEntry(stmt.name, undefined, 'edge', stmt, stmt.span, entries, diagnostics, seen);
             return;
@@ -360,16 +462,18 @@ function resolveFieldDeclaration(field, symbols, diagnostics) {
 function resolveTypeExpression(expr, symbols, diagnostics) {
     switch (expr.kind) {
         case 'ScalarType':
-            // A ScalarType is either a builtin or a reference to a Named Type
-            // (the parser doesn't distinguish at parse time). Look up only
-            // when the name isn't a builtin.
-            if (!isBuiltinType(expr.name)) {
-                const found = symbols.lookup(expr.name) ?? symbols.lookupBare(expr.name);
-                if (!found || found.kind !== 'type') {
+            // A ScalarType is a builtin, a reference to a declared Type or
+            // Enum, or a target-native type passed through as written (spec
+            // §1.2, principle 4) -- the parser doesn't distinguish at parse
+            // time. A target-native name is valid; the only diagnostic is a
+            // warning when it is a near miss of a declared Type or Enum.
+            if (!isBuiltinType(expr.name) && typeOrEnumDeclarations(expr.name, symbols).length === 0) {
+                const suggestion = nearMissTypeName(expr.name, symbols);
+                if (suggestion) {
                     diagnostics.push({
-                        severity: 'error',
-                        code: 'unresolved-type',
-                        message: `Type '${expr.name}' is not a built-in type or declared Named Type.`,
+                        severity: 'warning',
+                        code: 'possible-type-typo',
+                        message: `Type '${expr.name}' is not declared; did you mean '${suggestion}'? Otherwise it is kept as a target-native type.`,
                         span: expr.span,
                     });
                 }
@@ -821,9 +925,18 @@ function dereferenceNamedType(type, symbols, depth) {
         return type;
     }
     const sym = symbols.lookup(name) ?? symbols.lookupBare(name);
+    if (type.kind === 'ScalarType' && (!sym || sym.kind !== 'type')) {
+        // An Enum or a target-native type: an opaque scalar, so a path that
+        // navigates into it gets the walker's shape diagnostic. A name
+        // declared as a Type or Enum in several containers stays unresolved.
+        if (typeOrEnumDeclarations(name, symbols).length > 1)
+            return undefined;
+        return type;
+    }
     if (!sym || sym.kind !== 'type' || sym.declaration.kind !== 'TypeDeclaration') {
-        // Unresolved -- the field-type pass will diagnose this. Return
-        // undefined so the walker bails without emitting a duplicate error.
+        // Unresolved Named Type reference -- the field-type pass diagnoses
+        // this. Return undefined so the walker bails without emitting a
+        // duplicate error.
         return undefined;
     }
     const td = sym.declaration;

package/dist/parser.d.ts

@@ -13,8 +13,22 @@ import type { ParseOptions, Position, XDbmlDocument } from './ast.ts';
 import type { Token } from './lexer.ts';
 export declare class ParseError extends Error {
     position: Position;
-    constructor(message: string, position: Position);
+    /**
+     * Optional machine-readable reason. Set for the errors a caller may want
+     * to tell apart from a plain syntax error: `unsupported-version` when a
+     * document declares a newer version than this parser supports (spec 4.1).
+     */
+    code?: string;
+    constructor(message: string, position: Position, code?: string);
 }
+/**
+ * The newest specification version this parser implements. A document
+ * declaring a later version is refused (spec 4.1) rather than parsed with
+ * semantics it does not have.
+ */
+export declare const SUPPORTED_XDBML_VERSION = "0.5";
+/** Compare dotted version strings numerically: -1, 0 or 1. */
+export declare function compareVersions(a: string, b: string): number;
 export declare class Parser {
     private tokens;
     private idx;
@@ -30,7 +44,7 @@ export declare class Parser {
      * The set of file paths currently being parsed in the resolution chain.
      * Used for cycle detection: when resolving a directive whose `from` path
      * is already in this set, the parser produces an empty clone for that
-     * directive rather than recursing (matching spec §26.15: cycles are
+     * directive rather than recursing (matching spec §27.15: cycles are
      * allowed; name resolution handles them). The set is passed by reference
      * across recursive parse() calls so all transitive levels see it.
      *
@@ -83,13 +97,13 @@ export declare class Parser {
     private parseEntityBody;
     private parsePartialInjection;
     /**
-     * Parse a `records { ... }` block inside an entity body (§25.1, implicit
+     * Parse a `records { ... }` block inside an entity body (§26.1, implicit
      * column list). Values are stored as SettingValue cells; row boundaries
      * are determined by source line (see `parseRecordRow`).
      */
     private parseRecordsBlock;
     /**
-     * Top-level records declaration (§25.2, new in v0.2):
+     * Top-level records declaration (§26.2, new in v0.2):
      *
      *     records users (id, name, email) { ... }
      *     records core.users (id, name, email) { ... }
@@ -151,12 +165,12 @@ export declare class Parser {
      * that match the import items by name and element type (matching is
      * downstream-consumer's job; the parser is permissive).
      *
-     * Per spec §26.6, clone content uses the importing file's vocabulary
+     * Per spec §27.6, clone content uses the importing file's vocabulary
      * (aliases already applied) and is parsed under the importing file's
      * xdbml version directive.
      *
      * Most clone-block content uses TopLevelStatement shapes (Entity, Type,
-     * Container, etc.). The exception is field imports (§26.8): when the
+     * Container, etc.). The exception is field imports (§27.8): when the
      * directive imports one or more fields via `field <path>` items, the
      * clone block holds each field as a bare FieldDeclaration with no entity
      * wrapper. The dispatch below checks whether the next token starts a
@@ -278,7 +292,7 @@ export declare class Parser {
     private parseCardinalityOperator;
     private parseRefEndpoint;
     /**
-     * Parse a dotted path with the §18 segment vocabulary:
+     * Parse a dotted path with the §20 segment vocabulary:
      *
      *   IDENTIFIER                  -- a field segment
      *   .IDENTIFIER                 -- field
@@ -297,6 +311,16 @@ export declare class Parser {
     private parsePathSegments;
     private parseTablePartial;
     private parseTableGroup;
+    /**
+     * `SupertypeGroup <name> [supertype: X, ...] { Sub1  Sub2 [strategy: y] }`.
+     * Members are separated like TableGroup members: newline, comma or
+     * semicolon (spec §3.9). A name is required (§12.1); a writer exporting a
+     * group that has none emits `undefinedGroup1`, `undefinedGroup2`, ... so
+     * the parser never supplies one. Values are validated after parsing, by
+     * `checkSupertypeGroups()`, so an unknown value gets a located diagnostic
+     * rather than stopping the parse.
+     */
+    private parseSupertypeGroup;
     private parseIndexes;
     private parseIndexEntry;
     private parseIndexComponent;

package/dist/parser.js

@@ -13,11 +13,37 @@ import { TokenKind, tokenize, } from "./lexer.js";
 import { resolveImport, classifyModuleSource, ModuleSourceError } from "./module-resolver.js";
 export class ParseError extends Error {
     position;
-    constructor(message, position) {
+    /**
+     * Optional machine-readable reason. Set for the errors a caller may want
+     * to tell apart from a plain syntax error: `unsupported-version` when a
+     * document declares a newer version than this parser supports (spec 4.1).
+     */
+    code;
+    constructor(message, position, code) {
         super(`${message} (line ${position.line}, column ${position.column})`);
         this.position = position;
+        if (code)
+            this.code = code;
     }
 }
+/**
+ * The newest specification version this parser implements. A document
+ * declaring a later version is refused (spec 4.1) rather than parsed with
+ * semantics it does not have.
+ */
+export const SUPPORTED_XDBML_VERSION = '0.5';
+/** Compare dotted version strings numerically: -1, 0 or 1. */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map((n) => Number(n) || 0);
+    const pb = b.split('.').map((n) => Number(n) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
 /* -------------------------------------------------------------------------
  * Keyword recognition.
  *
@@ -31,13 +57,13 @@ const CONTAINER_KEYWORDS = new Set([
 const ENTITY_KEYWORDS = new Set(['table', 'entity', 'collection', 'record']);
 /**
  * Element-type keywords accepted in module-system import items
- * (spec §26.3). Stored lowercased; matching is case-insensitive.
+ * (spec §27.3). Stored lowercased; matching is case-insensitive.
  *
  * `field` is recognized but explicitly rejected by parseImportItem in P4
  * (field-level imports have special declaration-vs-placement semantics
  * that will land in a later batch).
  *
- * `project` is intentionally excluded -- spec §26.1 forbids importing
+ * `project` is intentionally excluded -- spec §27.1 forbids importing
  * Project declarations.
  */
 const IMPORT_ELEMENT_TYPES = new Set([
@@ -45,7 +71,7 @@ const IMPORT_ELEMENT_TYPES = new Set([
     'enum', 'tablepartial', 'note',
     'schema', 'container', 'tablegroup',
     'type', 'edge', 'view', 'diagramview',
-    'field',
+    'field', 'supertypegroup',
 ]);
 const STRUCTURAL_TYPE_KEYWORDS = new Set([
     'object', 'struct', 'record', 'array', 'list', 'map', 'dict', 'dictionary',
@@ -98,7 +124,7 @@ export class Parser {
      * The set of file paths currently being parsed in the resolution chain.
      * Used for cycle detection: when resolving a directive whose `from` path
      * is already in this set, the parser produces an empty clone for that
-     * directive rather than recursing (matching spec §26.15: cycles are
+     * directive rather than recursing (matching spec §27.15: cycles are
      * allowed; name resolution handles them). The set is passed by reference
      * across recursive parse() calls so all transitive levels see it.
      *
@@ -179,6 +205,11 @@ export class Parser {
         this.advance(); // xdbml
         this.expect(TokenKind.Colon, "Expected ':' after 'xdbml'");
         const numTok = this.expect(TokenKind.NumberLiteral, 'Expected version number');
+        if (compareVersions(numTok.text, SUPPORTED_XDBML_VERSION) > 0) {
+            throw new ParseError(`This document declares 'xdbml: ${numTok.text}', which is newer than the ` +
+                `latest version this parser supports (${SUPPORTED_XDBML_VERSION}). ` +
+                'Use a newer parser, or declare a supported version.', numTok.start, 'unsupported-version');
+        }
         return {
             kind: 'VersionDeclaration',
             version: numTok.text,
@@ -231,6 +262,8 @@ export class Parser {
             return this.parseTablePartial();
         if (k === 'tablegroup')
             return this.parseTableGroup();
+        if (k === 'supertypegroup')
+            return this.parseSupertypeGroup();
         if (k === 'note')
             return this.parseNoteDeclaration();
         if (k === 'records')
@@ -477,7 +510,7 @@ export class Parser {
         };
     }
     /**
-     * Parse a `records { ... }` block inside an entity body (§25.1, implicit
+     * Parse a `records { ... }` block inside an entity body (§26.1, implicit
      * column list). Values are stored as SettingValue cells; row boundaries
      * are determined by source line (see `parseRecordRow`).
      */
@@ -497,7 +530,7 @@ export class Parser {
         };
     }
     /**
-     * Top-level records declaration (§25.2, new in v0.2):
+     * Top-level records declaration (§26.2, new in v0.2):
      *
      *     records users (id, name, email) { ... }
      *     records core.users (id, name, email) { ... }
@@ -587,7 +620,7 @@ export class Parser {
             span: this.spanFrom(start),
         };
     }
-    /* ----- Module-system directives (spec §26, new in v0.2) ----- */
+    /* ----- Module-system directives (spec §27, new in v0.2) ----- */
     /**
      * Parse a `use` or `reuse` directive. Called from both the top-level
      * dispatcher and the Container body dispatcher; the caller indicates
@@ -701,7 +734,7 @@ export class Parser {
                         resolvedPath = result.resolvedPath;
                         break;
                     case 'cycle':
-                        // Per spec §26.15, cycles are allowed; the parser produces a
+                        // Per spec §27.15, cycles are allowed; the parser produces a
                         // directive with no clone, and name resolution (P6+) is
                         // expected to bridge the cycle. We leave clone undefined.
                         resolvedPath = result.resolvedPath;
@@ -759,12 +792,12 @@ export class Parser {
                 `Expected one of: ${Array.from(IMPORT_ELEMENT_TYPES).join(', ')}.`, elemTok.start);
         }
         if (elementType === 'field' && context !== 'file-scope') {
-            // Spec §26.8: field imports must appear at file scope. Inside a
+            // Spec §27.8: field imports must appear at file scope. Inside a
             // Container body, the field's eventual placement (as a Named Type)
             // would have no meaningful container scope -- field imports are
             // always lifted to file scope by flatten(), regardless of where
             // the directive sits.
-            throw new ParseError(`Field-level imports must appear at file scope, not inside a Container body (spec §26.8).`, elemTok.start);
+            throw new ParseError(`Field-level imports must appear at file scope, not inside a Container body (spec §27.8).`, elemTok.start);
         }
         this.advance(); // consume element type keyword
         // Dotted source path.
@@ -795,12 +828,12 @@ export class Parser {
      * that match the import items by name and element type (matching is
      * downstream-consumer's job; the parser is permissive).
      *
-     * Per spec §26.6, clone content uses the importing file's vocabulary
+     * Per spec §27.6, clone content uses the importing file's vocabulary
      * (aliases already applied) and is parsed under the importing file's
      * xdbml version directive.
      *
      * Most clone-block content uses TopLevelStatement shapes (Entity, Type,
-     * Container, etc.). The exception is field imports (§26.8): when the
+     * Container, etc.). The exception is field imports (§27.8): when the
      * directive imports one or more fields via `field <path>` items, the
      * clone block holds each field as a bare FieldDeclaration with no entity
      * wrapper. The dispatch below checks whether the next token starts a
@@ -816,7 +849,7 @@ export class Parser {
                 statements.push(this.parseTopLevelStatement());
             }
             else {
-                // Bare field declaration -- the field-import case. Per spec §26.6
+                // Bare field declaration -- the field-import case. Per spec §27.6
                 // the field appears without an entity wrapper.
                 statements.push(this.parseFieldDeclaration());
             }
@@ -1256,7 +1289,14 @@ export class Parser {
             throw new ParseError(`Expected type name, got ${t.kind} ${JSON.stringify(t.text)}`, t.start);
         }
         this.advance();
-        const name = t.kind === TokenKind.QuotedIdentifier ? (t.value ?? '') : t.text;
+        let name = t.kind === TokenKind.QuotedIdentifier ? (t.value ?? '') : t.text;
+        // A qualified type name, `core.job_status`, names an Enum declared in
+        // a container (spec §16), or a target-native type such as
+        // `public.geometry` that passes through as written.
+        while (this.check(TokenKind.Dot)) {
+            this.advance();
+            name += `.${this.parseIdentLikeName('type name after dot')}`;
+        }
         let params;
         if (this.check(TokenKind.LParen)) {
             this.advance();
@@ -1284,7 +1324,7 @@ export class Parser {
         }
         throw new ParseError(`Expected type parameter, got ${t.kind}`, t.start);
     }
-    /* ----- Type declaration (§13) ----- */
+    /* ----- Type declaration (§15) ----- */
     parseTypeDecl() {
         const start = this.peek().start;
         this.advance(); // Type
@@ -1293,7 +1333,7 @@ export class Parser {
         //
         //   { ... }                           v0.1 object form, no pre-body settings
         //   [ settings ] { ... }              v0.1 object form, pre-body settings (permissive)
-        //   typeExpression                    v0.2 scalar form (spec §14.7)
+        //   typeExpression                    v0.2 scalar form (spec §15.7)
         //   typeExpression [ settings ]       v0.2 scalar form with field-level settings
         //
         // Note that LBrace and LBracket are distinct from any start-of-type-expression
@@ -1422,7 +1462,13 @@ export class Parser {
     parseEnum() {
         const start = this.peek().start;
         const kwTok = this.advance(); // enum
-        const name = this.parseIdentLikeName('enum name');
+        // DBML form `enum core.job_status { ... }`: the qualifier names the
+        // container, as for a schema-qualified Table (spec §7.3, §16).
+        let name = this.parseIdentLikeName('enum name');
+        while (this.check(TokenKind.Dot)) {
+            this.advance();
+            name += `.${this.parseIdentLikeName('enum name after dot')}`;
+        }
         this.expect(TokenKind.LBrace, "Expected '{' after enum name");
         const values = [];
         while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
@@ -1572,7 +1618,7 @@ export class Parser {
         };
     }
     /**
-     * Parse a dotted path with the §18 segment vocabulary:
+     * Parse a dotted path with the §20 segment vocabulary:
      *
      *   IDENTIFIER                  -- a field segment
      *   .IDENTIFIER                 -- field
@@ -1746,6 +1792,67 @@ export class Parser {
             span: this.spanFrom(start),
         };
     }
+    /* ----- SupertypeGroup (spec §12, new in v0.5) ----- */
+    /**
+     * `SupertypeGroup <name> [supertype: X, ...] { Sub1  Sub2 [strategy: y] }`.
+     * Members are separated like TableGroup members: newline, comma or
+     * semicolon (spec §3.9). A name is required (§12.1); a writer exporting a
+     * group that has none emits `undefinedGroup1`, `undefinedGroup2`, ... so
+     * the parser never supplies one. Values are validated after parsing, by
+     * `checkSupertypeGroups()`, so an unknown value gets a located diagnostic
+     * rather than stopping the parse.
+     */
+    parseSupertypeGroup() {
+        const start = this.peek().start;
+        this.advance(); // SupertypeGroup
+        const nameTok = this.peek();
+        if (nameTok.kind !== TokenKind.Identifier && nameTok.kind !== TokenKind.QuotedIdentifier) {
+            throw new ParseError('Expected a name after SupertypeGroup. Every group has a name (spec §12.1); ' +
+                'a group exported without one is written undefinedGroup1, undefinedGroup2, ...', nameTok.start);
+        }
+        const name = this.parseIdentLikeName('SupertypeGroup name');
+        const settings = this.maybeSettingsBlock();
+        this.expect(TokenKind.LBrace, "Expected '{' after SupertypeGroup name and settings");
+        const members = [];
+        while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
+            const t = this.peek();
+            if (t.kind === TokenKind.Identifier || t.kind === TokenKind.QuotedIdentifier) {
+                const memberStart = t.start;
+                this.advance();
+                let n = t.kind === TokenKind.QuotedIdentifier ? (t.value ?? '') : t.text;
+                while (this.check(TokenKind.Dot)) {
+                    this.advance();
+                    const next = this.peek();
+                    if (next.kind !== TokenKind.Identifier && next.kind !== TokenKind.QuotedIdentifier) {
+                        throw new ParseError('Expected identifier after dot in subtype path', next.start);
+                    }
+                    this.advance();
+                    n += `.${next.kind === TokenKind.QuotedIdentifier ? (next.value ?? '') : next.text}`;
+                }
+                const memberSettings = this.maybeSettingsBlock();
+                members.push({
+                    kind: 'SupertypeGroupMember',
+                    name: n,
+                    settings: memberSettings,
+                    span: this.spanFrom(memberStart),
+                });
+            }
+            else if (t.kind === TokenKind.Semicolon || t.kind === TokenKind.Comma) {
+                this.advance();
+            }
+            else {
+                throw new ParseError(`Unexpected ${t.kind} in SupertypeGroup body; expected a subtype entity name`, t.start);
+            }
+        }
+        this.expect(TokenKind.RBrace, "Expected '}' closing SupertypeGroup");
+        return {
+            kind: 'SupertypeGroupDeclaration',
+            name,
+            settings,
+            members,
+            span: this.spanFrom(start),
+        };
+    }
     /* ----- Indexes ----- */
     parseIndexes() {
         const start = this.peek().start;