@xdbml/parse 0.1.0-poc.1

package/dist/monarch.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Monaco language configuration and Monarch tokens provider for xDBML.
+ *
+ * Monarch is a regex-based state-machine syntax highlighter that ships
+ * with Monaco. This file produces the highlighting rules; the real parser
+ * lives in ./parser.ts. The two operate independently: Monaco asks
+ * Monarch "what color is each character" for highlighting, and asks the
+ * parser "is the file valid and what's its AST" for everything else.
+ *
+ * The two must stay in sync grammatically (a keyword the parser
+ * recognizes should also be highlighted as a keyword) but they don't
+ * share code or state.
+ *
+ * Reference: https://microsoft.github.io/monaco-editor/monarch.html
+ *
+ * Types are loose `unknown` rather than depending on monaco-editor here,
+ * because @xdbml/parse should be usable without forcing the Monaco
+ * dependency on consumers that just want to parse. The Monaco types
+ * are structurally compatible -- the consumer casts at the boundary.
+ */
+/** Subset of Monaco's LanguageConfiguration -- only the fields we set. */
+export interface XDbmlLanguageConfiguration {
+    comments: {
+        lineComment: string;
+        blockComment: [string, string];
+    };
+    brackets: [string, string][];
+    autoClosingPairs: {
+        open: string;
+        close: string;
+    }[];
+    surroundingPairs: {
+        open: string;
+        close: string;
+    }[];
+    indentationRules?: {
+        increaseIndentPattern: RegExp;
+        decreaseIndentPattern: RegExp;
+    };
+}
+/** Subset of Monaco's IMonarchLanguage -- the shape Monarch consumes. */
+export interface XDbmlMonarchLanguage {
+    tokenPostfix: string;
+    brackets: {
+        open: string;
+        close: string;
+        token: string;
+    }[];
+    decls: string[];
+    containerKeywords: string[];
+    entityKeywords: string[];
+    structuralTypeKeywords: string[];
+    polymorphismKeywords: string[];
+    scalarTypes: string[];
+    bsonTypes: string[];
+    settingFlags: string[];
+    settingKeys: string[];
+    granularityValues: string[];
+    ignoreCase: boolean;
+    unicode: boolean;
+    tokenizer: Record<string, unknown[]>;
+}
+export declare const xdbmlLanguageConfig: XDbmlLanguageConfiguration;
+export declare const xdbmlMonarchTokensProvider: XDbmlMonarchLanguage;

package/dist/monarch.js

@@ -0,0 +1,205 @@
+/**
+ * Monaco language configuration and Monarch tokens provider for xDBML.
+ *
+ * Monarch is a regex-based state-machine syntax highlighter that ships
+ * with Monaco. This file produces the highlighting rules; the real parser
+ * lives in ./parser.ts. The two operate independently: Monaco asks
+ * Monarch "what color is each character" for highlighting, and asks the
+ * parser "is the file valid and what's its AST" for everything else.
+ *
+ * The two must stay in sync grammatically (a keyword the parser
+ * recognizes should also be highlighted as a keyword) but they don't
+ * share code or state.
+ *
+ * Reference: https://microsoft.github.io/monaco-editor/monarch.html
+ *
+ * Types are loose `unknown` rather than depending on monaco-editor here,
+ * because @xdbml/parse should be usable without forcing the Monaco
+ * dependency on consumers that just want to parse. The Monaco types
+ * are structurally compatible -- the consumer casts at the boundary.
+ */
+import { CONTAINER_KEYWORDS, ENTITY_KEYWORDS, DECLARATION_KEYWORDS, STRUCTURAL_TYPE_KEYWORDS, POLYMORPHISM_KEYWORDS, SCALAR_TYPES, BSON_TYPES, SETTING_FLAGS, SETTING_KEYS, GRANULARITY_VALUES, } from "./keywords.js";
+/* -------------------------------------------------------------------------
+ * Language configuration
+ * ----------------------------------------------------------------------- */
+export const xdbmlLanguageConfig = {
+    comments: {
+        lineComment: '//',
+        blockComment: ['/*', '*/'],
+    },
+    brackets: [
+        ['{', '}'],
+        ['[', ']'],
+        ['(', ')'],
+    ],
+    autoClosingPairs: [
+        { open: '{', close: '}' },
+        { open: '[', close: ']' },
+        { open: '(', close: ')' },
+        { open: '"', close: '"' },
+        { open: "'", close: "'" },
+        { open: '`', close: '`' },
+    ],
+    surroundingPairs: [
+        { open: '{', close: '}' },
+        { open: '[', close: ']' },
+        { open: '(', close: ')' },
+        { open: '"', close: '"' },
+        { open: "'", close: "'" },
+        { open: '`', close: '`' },
+    ],
+    indentationRules: {
+        increaseIndentPattern: /^(.*\{[^}]*|\s*[{[].*)$/,
+        decreaseIndentPattern: /^(.*\}.*|\s*[}\]].*)$/,
+    },
+};
+/* -------------------------------------------------------------------------
+ * Monarch tokens provider
+ *
+ * Token type conventions (these map to the Monaco theme rules):
+ *   keyword                    -- core construct keywords (Project, Container, ...)
+ *   keyword.declaration        -- top-level declaration keywords
+ *   keyword.entity             -- Entity/Table/Collection/Record
+ *   keyword.container          -- Container/Schema/Database/...
+ *   keyword.type               -- structural type keywords (object/array/...)
+ *   keyword.polymorphism       -- oneOf/anyOf/allOf/union
+ *   keyword.directive          -- xdbml:, experimental:
+ *   type                       -- scalar type names (int, varchar, decimal, ...)
+ *   type.bson                  -- BSON type names (objectId, Decimal128, ...)
+ *   identifier                 -- user-supplied names
+ *   identifier.custom-property -- x_-prefixed custom property names
+ *   string / string.multiline  -- string literals
+ *   string.backtick            -- expression literals
+ *   string.quoted-ident        -- double-quoted identifiers
+ *   number                     -- numeric literals
+ *   comment / comment.block    -- comments
+ *   operators                  -- cardinality operators (< > - <>)
+ *   keyword.wildcard           -- [*]
+ *   keyword.partial            -- ~ in partial injection
+ *   delimiter / @bracket       -- punctuation
+ * ----------------------------------------------------------------------- */
+export const xdbmlMonarchTokensProvider = {
+    tokenPostfix: '.xdbml',
+    brackets: [
+        { open: '[', close: ']', token: 'delimiter.square' },
+        { open: '(', close: ')', token: 'delimiter.parenthesis' },
+        { open: '{', close: '}', token: 'delimiter.curly' },
+    ],
+    // Keyword vocabulary is sourced from ./keywords.ts so the TextMate
+    // grammar (in tools/textmate/) and this Monarch tokenizer stay in
+    // sync. To add a keyword: edit ./keywords.ts (one place), then
+    // re-run the TextMate build script. See keywords.ts for the full
+    // workflow.
+    // Top-level declaration keywords
+    decls: [...DECLARATION_KEYWORDS],
+    containerKeywords: [...CONTAINER_KEYWORDS],
+    entityKeywords: [...ENTITY_KEYWORDS],
+    // Structural type expression keywords (used as type expressions inside fields)
+    structuralTypeKeywords: [...STRUCTURAL_TYPE_KEYWORDS],
+    polymorphismKeywords: [...POLYMORPHISM_KEYWORDS],
+    // SQL scalar types -- recognized for highlighting; the parser accepts any
+    // identifier as a scalar type, so this list is for color, not validation.
+    scalarTypes: [...SCALAR_TYPES],
+    // BSON / document-store types
+    bsonTypes: [...BSON_TYPES],
+    // Bare-flag settings: `pk`, `unique`, `not null`, etc.
+    // `not null` and `primary key` are two words but tokenized one at a time
+    // here -- the highlighter colors each as `keyword.setting`.
+    // `required` is a synonym for `not null` (spec §8); the parser
+    // normalizes it to `not null` in the AST, but for highlighting
+    // purposes both spellings get the same `keyword.setting` color.
+    settingFlags: [...SETTING_FLAGS],
+    // Setting keys appearing as `name: value` -- recognized for highlighting.
+    // Open-vocabulary at the parser level; this list drives coloring only.
+    settingKeys: [...SETTING_KEYS],
+    granularityValues: [...GRANULARITY_VALUES],
+    ignoreCase: true,
+    unicode: true,
+    tokenizer: {
+        root: [
+            // xDBML / experimental directives at the very top of files
+            [/^(\s*)(xdbml|experimental)(\s*)(:)/, [
+                    '',
+                    'keyword.directive',
+                    '',
+                    'delimiter',
+                ]],
+            // [*] -- array wildcard token (must precede generic bracket rules)
+            [/\[\*\]/, 'keyword.wildcard'],
+            // ~ prefix for partial injection
+            [/~/, 'keyword.partial'],
+            // Brackets, parens, braces
+            [/[{}[\]()]/, '@bracket'],
+            // Punctuation
+            [/[,.:;]/, 'delimiter'],
+            // Cardinality operators
+            [/<>/, 'operators.cardinality'],
+            [/[<>-](?![A-Za-z_])/, 'operators.cardinality'],
+            // Comments
+            [/\/\/.*$/, 'comment'],
+            [/\/\*/, 'comment.block', '@comment'],
+            // Triple-quoted multi-line strings -- must precede single-quoted
+            [/'''/, { token: 'string.multiline', next: '@multilineString' }],
+            // Quoted identifiers (double-quote)
+            [/"/, { token: 'string.quoted-ident', next: '@quotedIdent' }],
+            // Single-quoted strings
+            [/'/, { token: 'string', next: '@singleString' }],
+            // Backtick expression literals
+            [/`/, { token: 'string.backtick', next: '@backtickExpr' }],
+            // Numbers
+            [/0[xX][0-9a-fA-F]+/, 'number.hex'],
+            [/-?\d+\.\d+([eE][+-]?\d+)?/, 'number.float'],
+            [/-?\d+([eE][+-]?\d+)?/, 'number'],
+            [/#[0-9A-Fa-f]{3,8}\b/, 'number.hex'],
+            // x_ custom property identifiers
+            [/\bx_[a-zA-Z0-9_]+/, 'identifier.custom-property'],
+            // Identifiers and keyword recognition.
+            // The parser is the authority on keyword vs identifier disambiguation;
+            // Monarch does coarse highlighting based on lowercase comparison.
+            [/[a-zA-Z_][\w$]*/, {
+                    cases: {
+                        '@containerKeywords': 'keyword.container',
+                        '@entityKeywords': 'keyword.entity',
+                        '@structuralTypeKeywords': 'keyword.type',
+                        '@polymorphismKeywords': 'keyword.polymorphism',
+                        '@decls': 'keyword.declaration',
+                        '@scalarTypes': 'type',
+                        '@bsonTypes': 'type.bson',
+                        '@settingFlags': 'keyword.setting',
+                        '@settingKeys': 'keyword.setting',
+                        '@granularityValues': 'keyword.value',
+                        'true': 'keyword.literal',
+                        'false': 'keyword.literal',
+                        'null': 'keyword.literal',
+                        '@default': 'identifier',
+                    },
+                }],
+            // Whitespace
+            [/[ \t\r\n]+/, ''],
+        ],
+        comment: [
+            [/[^/*]+/, 'comment.block'],
+            [/\*\//, 'comment.block', '@pop'],
+            [/[/*]/, 'comment.block'],
+        ],
+        singleString: [
+            [/[^\\']+/, 'string'],
+            [/\\./, 'string.escape'],
+            [/'/, { token: 'string', next: '@pop' }],
+        ],
+        multilineString: [
+            [/[^']+/, 'string.multiline'],
+            [/'''/, { token: 'string.multiline', next: '@pop' }],
+            [/'/, 'string.multiline'],
+        ],
+        quotedIdent: [
+            [/[^\\"]+/, 'string.quoted-ident'],
+            [/\\./, 'string.quoted-ident'],
+            [/"/, { token: 'string.quoted-ident', next: '@pop' }],
+        ],
+        backtickExpr: [
+            [/[^`]+/, 'string.backtick'],
+            [/`/, { token: 'string.backtick', next: '@pop' }],
+        ],
+    },
+};

package/dist/name-resolver.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Name resolution pass (spec §26.10 / §26.15, parser batch P6).
+ *
+ * `resolveNames(doc)` walks an xDBML document (the flattened view; clone
+ * blocks have been merged) and produces:
+ *
+ *   - A symbol table mapping qualified names to declarations
+ *   - A list of diagnostics: unresolved references and name conflicts
+ *
+ * The resolver does NOT mutate the AST. It is a pure side computation
+ * that downstream consumers can run for validation, IDE support, code
+ * generation, etc. Spans on diagnostics point to the offending construct
+ * in the source, so callers can surface them as editor markers.
+ *
+ * Per the spec, name resolution is a two-pass process:
+ *
+ *   Pass 1: Collect declarations.
+ *     Walk all top-level + container-body declarations and add them to
+ *     the symbol table. Duplicates (same qualified name + same kind)
+ *     produce a `duplicate-declaration` diagnostic and the LATER
+ *     declaration is silently dropped from the table.
+ *
+ *   Pass 2: Resolve references.
+ *     Walk all reference sites and look up targets in the symbol table.
+ *     References that don't resolve produce diagnostics. Built-in scalar
+ *     and BSON types are recognized via SCALAR_TYPES / BSON_TYPES and
+ *     never produce unresolved-type diagnostics.
+ *
+ * Two passes handle forward references (a Type declared at end of file
+ * can be referenced from a field declared at the top) and circular
+ * imports (cycles are already collapsed by `flatten()` / cycles in P5
+ * resolution; the resolver just sees the merged namespace).
+ *
+ * The resolver flattens its input internally, so callers don't need to
+ * `flatten()` first. Callers that want to surface diagnostics tied to
+ * the original (provenance-preserving) AST can map positions back via
+ * span comparison; in practice the cloned declarations' spans point
+ * into the importing file's clone block, which is where the user can
+ * edit them, so the natural workflow works correctly.
+ */
+import type { EntityDeclaration, EnumDeclaration, Position, Span, TopLevelStatement, TypeDeclaration, XDbmlDocument } from './ast.ts';
+/**
+ * Kind of declaration a symbol refers to. Mirrors the declaration AST
+ * shape vocabulary; useful for diagnostics that want to say
+ * "expected an entity, found a type" or similar.
+ */
+export type SymbolKind = 'entity' | 'type' | 'enum' | 'container' | 'edge' | 'view' | 'tablegroup' | 'tablepartial' | 'note';
+/**
+ * One entry in the symbol table. Carries the declaration node (so
+ * downstream consumers can navigate), the canonical qualified name, and
+ * a source position for diagnostics.
+ */
+export interface SymbolEntry {
+    /** The fully-qualified, dot-separated name (e.g., `core.dim_customer`). */
+    qualifiedName: string;
+    /** The bare, unqualified name as it appears in source. */
+    name: string;
+    /** Container the symbol lives in, if any (top-level entries leave this undefined). */
+    containerName?: string;
+    kind: SymbolKind;
+    /** The declaration node. Type narrows on `kind`. */
+    declaration: EntityDeclaration | TypeDeclaration | EnumDeclaration | TopLevelStatement;
+    /** Source position of the declaration (start of declaration). */
+    position: Position;
+}
+/**
+ * Stable diagnostic code. Tooling can match on these to filter or style
+ * messages without parsing the human-readable text.
+ */
+export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'unresolved-entity' | 'unresolved-field' | 'unresolved-partial' | 'unresolved-tablegroup-member' | 'unresolved-records-entity' | 'unresolved-records-column' | 'empty-import' | 'invalid-nested-path';
+/**
+ * A single resolution diagnostic. Severity is currently always `error`,
+ * but the field is included to leave room for future warnings (e.g.,
+ * style concerns like "redundant alias matches original name").
+ *
+ * Position is given as a Span (start + end) rather than a single Position
+ * so editor integrations (Monaco markers, LSP servers) can underline the
+ * exact offending construct rather than guessing where the squiggle
+ * should end. Each diagnostic's span corresponds to an AST node's own
+ * span (a field's type expression, a path endpoint, an entity name).
+ */
+export interface Diagnostic {
+    severity: 'error' | 'warning';
+    code: DiagnosticCode;
+    message: string;
+    span: Span;
+}
+/**
+ * The result of `resolveNames(doc)`. The symbol table is consultable for
+ * downstream queries (e.g., "given a name, find the declaration"); the
+ * diagnostics list is for surfacing problems.
+ */
+export interface ResolutionResult {
+    diagnostics: Diagnostic[];
+    symbols: SymbolTable;
+}
+/**
+ * Read-only handle on the collected symbol table.
+ *
+ * Lookup is by qualified name (e.g., `core.dim_customer`). The class
+ * also exposes a `lookupBare()` for the common case where the name has
+ * no container prefix and the caller wants to find the unique match
+ * (returns undefined if ambiguous or missing).
+ */
+export declare class SymbolTable {
+    private readonly byQualified;
+    private readonly byBare;
+    constructor(entries: ReadonlyArray<SymbolEntry>);
+    /** Look up by canonical qualified name. */
+    lookup(qualifiedName: string): SymbolEntry | undefined;
+    /**
+     * Look up by bare name. Returns the unique entry if exactly one match,
+     * or undefined when missing or ambiguous (multiple containers contain
+     * an entry with this bare name). For ambiguous cases, callers should
+     * inspect `lookupAllBare()` if they want to disambiguate.
+     */
+    lookupBare(name: string): SymbolEntry | undefined;
+    /** Look up by bare name; returns all matches. */
+    lookupAllBare(name: string): ReadonlyArray<SymbolEntry>;
+    /** Iterate all entries in declaration order. */
+    entries(): IterableIterator<SymbolEntry>;
+    /** Total number of entries. */
+    get size(): number;
+}
+/**
+ * Resolve names in an xDBML document. Flattens the AST internally
+ * (so callers don't need to call `flatten()` first), then runs the
+ * two-pass resolution algorithm. Returns diagnostics and the symbol
+ * table.
+ *
+ * Cost is roughly linear in (declarations + reference sites). For
+ * typical schemas (10s-100s of entities) this is fast enough to run
+ * on every keystroke in an interactive editor.
+ */
+export declare function resolveNames(doc: XDbmlDocument): ResolutionResult;