@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/dist/src/parse.js

@@ -23,6 +23,20 @@ export function parseProgram(source) {
             program: { decls: [], span: { end: 0, start: 0 } },
         };
     }
+    const first = source.search(/\S/);
+    if (first >= 0 && source[first] === "{") {
+        return {
+            diagnostics: [
+                {
+                    code: "HSX1014",
+                    fix: "replace the JSON object with HSX declarations",
+                    message: "JSON is not HSX",
+                    span: { end: first + 1, start: first },
+                },
+            ],
+            program: { decls: [], span: { end: source.length, start: 0 } },
+        };
+    }
     const lexed = lex(source);
     const parser = new Parser(lexed.tokens, [...lexed.diagnostics]);
     const program = parser.parseProgram(source.length);
@@ -40,6 +54,10 @@ class Parser {
     parseProgram(sourceLength) {
         const decls = [];
         while (!this.at("eof")) {
+            if (this.atPunct(";")) {
+                this.advance();
+                continue;
+            }
             const decl = this.parseDecl();
             if (decl) {
                 decls.push(decl);
@@ -50,33 +68,187 @@ class Parser {
         return { decls, span: { end: sourceLength, start: 0 } };
     }
     // --- Declarations --------------------------------------------------------
-    parseDecl() {
+    parseDecl(exported = false) {
         const token = this.peek();
         if (token.kind !== "keyword" || token.text === "from") {
             this.error(token.span, token.kind === "eof"
                 ? "the program ends unexpectedly"
-                : `expected a declaration (program, import, party, asset, settlement, or port), found "${token.text}"`);
+                : `expected a declaration (module, program, use, expose, import, party, asset, subject, instrument, settlement, type, const, or port), found "${token.text}"`);
             return undefined;
         }
         switch (token.text) {
+            case "export":
+                this.advance();
+                return this.parseDecl(true);
+            case "module":
+                return this.parseModuleDecl(exported);
             case "program":
                 return this.parseProgramDecl();
+            case "use":
+                return this.parseUseDecl();
+            case "expose":
+                return this.parseExposeDecl();
             case "import":
                 return this.parseImportDecl();
             case "party":
                 return this.parsePartyDecl();
             case "asset":
                 return this.parseAssetDecl();
+            case "subject":
+                return this.parseSubjectDecl(exported);
+            case "instrument":
+                return this.parseInstrumentDecl(exported);
             case "settlement":
                 return this.parseSettlementDecl();
             case "port":
                 return this.parsePortDecl();
+            case "type":
+                return this.parseTypeDecl(exported);
+            case "const":
+                return this.parseConstDecl(exported);
             default:
                 this.error(token.span, `"${token.text}" cannot start a declaration`);
                 this.advance();
                 return undefined;
         }
     }
+    parseModuleDecl(exported) {
+        const start = this.advance();
+        if (exported) {
+            this.error(start.span, "a module declaration cannot be exported");
+        }
+        const name = this.parsePath("the module needs a dotted name");
+        return name
+            ? { kind: "module", name, span: this.spanFrom(start.span) }
+            : undefined;
+    }
+    parseInstrumentDecl(exported) {
+        const start = this.advance();
+        const name = this.expectIdent("the instrument needs a snake_case name");
+        if (!name)
+            return undefined;
+        const typeParameters = this.parseTypeParameters();
+        if (!typeParameters)
+            return undefined;
+        const hasParameterList = this.atPunct("(");
+        const parameters = hasParameterList ? this.parseParameters() : [];
+        if (!parameters)
+            return undefined;
+        if (this.atPunct("=")) {
+            this.advance();
+            const application = this.parseApplication();
+            if (!application)
+                return undefined;
+            const metadata = this.atPunct("{") ? this.parseBlock() : undefined;
+            return {
+                application,
+                exported,
+                kind: "instrument_apply",
+                ...(metadata ? { metadata } : {}),
+                name,
+                span: this.spanFrom(start.span),
+            };
+        }
+        if (!this.atPunct("{")) {
+            this.error(this.peek().span, `instrument ${name.name} needs a body or an exported instrument application`);
+            return undefined;
+        }
+        const body = this.parseBlock();
+        if (!body)
+            return undefined;
+        return {
+            body,
+            exported,
+            hasParameterList,
+            kind: "instrument",
+            name,
+            parameters,
+            span: this.spanFrom(start.span),
+            typeParameters,
+        };
+    }
+    parseTypeDecl(exported) {
+        const start = this.advance();
+        const name = this.expectIdent("the type needs a name");
+        if (!name)
+            return undefined;
+        if (!this.expectPunct("=", `type ${name.name} needs = before its definition`)) {
+            return undefined;
+        }
+        const value = this.parseExpr();
+        return value
+            ? { exported, kind: "type", name, span: this.spanFrom(start.span), value }
+            : undefined;
+    }
+    parseConstDecl(exported) {
+        const start = this.advance();
+        const name = this.expectIdent("the constant needs a name");
+        if (!name)
+            return undefined;
+        let type;
+        if (this.atPunct(":")) {
+            this.advance();
+            type = this.parseExpr();
+            if (!type)
+                return undefined;
+        }
+        if (!this.expectPunct("=", `const ${name.name} needs = before its value`)) {
+            return undefined;
+        }
+        const value = this.parseExpr();
+        return value
+            ? {
+                exported,
+                kind: "const",
+                name,
+                span: this.spanFrom(start.span),
+                ...(type ? { type } : {}),
+                value,
+            }
+            : undefined;
+    }
+    parseTypeParameters() {
+        if (!this.atPunct("<"))
+            return [];
+        this.advance();
+        const parameters = [];
+        while (!this.atPunct(">") && !this.at("eof")) {
+            const name = this.expectIdent("expected a type parameter");
+            if (!name)
+                return undefined;
+            parameters.push({ name, span: name.span });
+            if (this.atPunct(","))
+                this.advance();
+        }
+        return this.expectPunct(">", "the type parameter list never closes")
+            ? parameters
+            : undefined;
+    }
+    parseParameters() {
+        this.advance();
+        const parameters = [];
+        while (!this.atPunct(")") && !this.at("eof")) {
+            const name = this.expectIdent("expected a parameter name");
+            if (!name)
+                return undefined;
+            if (!this.expectPunct(":", `parameter ${name.name} needs a type`)) {
+                return undefined;
+            }
+            const type = this.parseExpr();
+            if (!type)
+                return undefined;
+            parameters.push({
+                name,
+                span: { start: name.span.start, end: type.span.end },
+                type,
+            });
+            if (this.atPunct(","))
+                this.advance();
+        }
+        return this.expectPunct(")", "the parameter list never closes")
+            ? parameters
+            : undefined;
+    }
     parseProgramDecl() {
         const start = this.advance();
         const name = this.expectIdent("the program needs a snake_case name");
@@ -94,9 +266,43 @@ class Parser {
             ...(title ? { title } : {}),
         };
     }
+    parseUseDecl() {
+        const start = this.advance();
+        const instrument = this.expectIdent("use needs a published instrument id, like: use held_settlement");
+        return instrument
+            ? { instrument, kind: "use", span: this.spanFrom(start.span) }
+            : undefined;
+    }
+    parseExposeDecl() {
+        const start = this.advance();
+        const instrument = this.expectIdent("expose needs an instrument action, like: expose held_settlement.release as releaseFunds");
+        if (!instrument)
+            return undefined;
+        if (!this.expectPunct(".", "expose separates the instrument and action with .")) {
+            return undefined;
+        }
+        const action = this.expectName("expose needs an action after the instrument id");
+        if (!action)
+            return undefined;
+        if (!this.at("keyword") || this.peek().text !== "as") {
+            this.error(this.peek().span, "expose needs as before its public action name");
+            return undefined;
+        }
+        this.advance();
+        const publicName = this.expectIdent("expose needs a camelCase public action name");
+        return publicName
+            ? {
+                action,
+                instrument,
+                kind: "expose",
+                publicName,
+                span: this.spanFrom(start.span),
+            }
+            : undefined;
+    }
     parseImportDecl() {
         const start = this.advance();
-        if (!this.expectPunct("{", 'import lists its names in braces: import { held_payment } from "settlement"')) {
+        if (!this.expectPunct("{", 'import lists its names in braces: import { held_payment } from "std/settlements"')) {
             return undefined;
         }
         const names = [];
@@ -112,12 +318,12 @@ class Parser {
             return undefined;
         }
         if (!this.at("keyword") || this.peek().text !== "from") {
-            this.error(this.peek().span, 'import needs from: import { held_payment } from "settlement"');
+            this.error(this.peek().span, 'import needs from: import { held_payment } from "std/settlements"');
             return undefined;
         }
         this.advance();
         if (!this.at("string")) {
-            this.error(this.peek().span, 'the import source must be a quoted module name like "settlement"');
+            this.error(this.peek().span, 'the import source must be a quoted module name like "std/settlements"');
             return undefined;
         }
         const sourceToken = this.advance();
@@ -175,6 +381,23 @@ class Parser {
             span: this.spanFrom(start.span),
         };
     }
+    parseSubjectDecl(exported) {
+        const start = this.advance();
+        if (exported) {
+            this.error(start.span, "a subject declaration cannot be exported");
+        }
+        const name = this.expectIdent("the subject needs a snake_case kind name");
+        if (!name)
+            return undefined;
+        if (!this.atPunct("{")) {
+            this.error(this.peek().span, `subject ${name.name} needs a body`);
+            return undefined;
+        }
+        const body = this.parseBlock();
+        return body
+            ? { body, kind: "subject", name, span: this.spanFrom(start.span) }
+            : undefined;
+    }
     parseSettlementDecl() {
         const start = this.advance();
         const name = this.expectIdent("the settlement needs a name, like: settlement sale = held_payment { ... }");
@@ -194,9 +417,20 @@ class Parser {
         if (!body)
             return undefined;
         return {
-            archetype,
-            body,
-            kind: "settlement",
+            application: {
+                args: body.entries.map((row) => ({
+                    kind: "binding",
+                    name: row.key,
+                    span: row.value.span,
+                    type: row.value,
+                })),
+                callee: { kind: "path", parts: [archetype], span: archetype.span },
+                kind: "apply",
+                span: { start: archetype.span.start, end: body.span.end },
+                typeArgs: [],
+            },
+            exported: false,
+            kind: "instrument_apply",
             name,
             span: this.spanFrom(start.span),
         };
@@ -238,19 +472,23 @@ class Parser {
         this.depth += 1;
         return true;
     }
-    parseBlock() {
+    parseBlock(context = "general") {
         if (!this.enterNesting(this.peek().span))
             return undefined;
-        const block = this.parseBlockUnguarded();
+        const block = this.parseBlockUnguarded(context);
         this.depth -= 1;
         return block;
     }
-    parseBlockUnguarded() {
+    parseBlockUnguarded(context) {
         const open = this.advance();
         const entries = [];
         while (!this.atPunct("}") && !this.at("eof")) {
+            if (this.atPunct(";") || this.atPunct(",")) {
+                this.advance();
+                continue;
+            }
             const before = this.index;
-            const entry = this.parseEntry();
+            const entry = this.parseEntry(context);
             if (!entry) {
                 this.recoverInBlock();
                 // recoverInBlock bails without consuming when it lands on a depth-0
@@ -262,7 +500,7 @@ class Parser {
                 continue;
             }
             entries.push(entry);
-            if (this.atPunct(","))
+            if (this.atPunct(",") || this.atPunct(";"))
                 this.advance();
         }
         if (!this.expectPunct("}", "this block never closes; add the matching }")) {
@@ -270,15 +508,172 @@ class Parser {
         }
         return { entries, kind: "block", span: this.spanFrom(open.span) };
     }
-    parseEntry() {
-        const key = this.expectIdent("expected an entry name here");
+    parseEntry(context) {
+        const token = this.peek();
+        const key = token.kind === "string"
+            ? (() => {
+                this.advance();
+                return {
+                    kind: "ident",
+                    name: token.value,
+                    quoted: !token.value.includes("["),
+                    span: token.span,
+                };
+            })()
+            : this.isName(token) && (token.text === "action" || token.text === "on")
+                ? this.parseIdent()
+                : this.parseTemplatedName("expected an entry name here");
         if (!key)
             return undefined;
         const qualifiers = [];
+        if (key.name === "for") {
+            const binding = this.expectIdent("for needs a compile-time binding name");
+            const inWord = binding
+                ? this.expectName("for needs in before its finite bound")
+                : undefined;
+            if (!binding || inWord?.name !== "in") {
+                this.error(this.peek().span, "write `for item in <finite bound> { ... }`");
+                return undefined;
+            }
+            const bound = this.parseExpr();
+            if (!bound || !this.atPunct("{")) {
+                this.error(this.peek().span, "a bounded comprehension needs a body in braces");
+                return undefined;
+            }
+            const value = this.parseBlock(context);
+            return value
+                ? {
+                    iteration: { binding, bound },
+                    key,
+                    qualifiers,
+                    span: { start: key.span.start, end: value.span.end },
+                    value,
+                }
+                : undefined;
+        }
+        if (key.name === "action" &&
+            (this.isName(this.peek()) || this.atPunct("["))) {
+            const action = this.parseTemplatedName("action needs a name");
+            if (!action)
+                return undefined;
+            qualifiers.push(action);
+            if (!this.atPunct("{")) {
+                this.error(this.peek().span, `action ${qualifiers[0]?.name ?? ""} needs a body`);
+                return undefined;
+            }
+            const value = this.parseBlock();
+            return value
+                ? {
+                    key,
+                    qualifiers,
+                    span: { start: key.span.start, end: value.span.end },
+                    value,
+                }
+                : undefined;
+        }
+        if (context === "lifecycle" && key.name === "states") {
+            const items = [];
+            while (!this.atPunct(";") && !this.atPunct("}") && !this.at("eof")) {
+                const state = this.parseTemplatedName("expected a lifecycle state");
+                if (!state)
+                    return undefined;
+                items.push(state);
+            }
+            const end = items.at(-1)?.span.end ?? key.span.end;
+            return {
+                key,
+                qualifiers,
+                span: { start: key.span.start, end },
+                value: { items, kind: "list", span: { start: key.span.end, end } },
+            };
+        }
+        if (context === "lifecycle" && key.name === "initial") {
+            const value = this.parseTemplatedName("initial needs one declared lifecycle state");
+            return value
+                ? {
+                    key,
+                    qualifiers,
+                    span: { start: key.span.start, end: value.span.end },
+                    value,
+                }
+                : undefined;
+        }
+        if (context === "lifecycle" && key.name === "parked") {
+            const state = this.parseTemplatedName("parked needs a lifecycle state");
+            if (!state)
+                return undefined;
+            qualifiers.push(state);
+            const reasonWord = this.expectName('parked needs reason "..."');
+            if (!reasonWord || reasonWord.name !== "reason" || !this.at("string")) {
+                this.error(this.peek().span, 'parked needs reason "..."');
+                return undefined;
+            }
+            const token = this.advance();
+            const value = {
+                kind: "string",
+                span: token.span,
+                value: token.value,
+            };
+            return {
+                key,
+                qualifiers,
+                span: { start: key.span.start, end: value.span.end },
+                value,
+            };
+        }
+        if (context === "lifecycle" && key.name === "on") {
+            const action = this.parseTemplatedName("on needs an action name");
+            if (!action)
+                return undefined;
+            qualifiers.push(action);
+            if (!this.expectPunct(":", `on ${action.name} needs : before its source states`)) {
+                return undefined;
+            }
+            while (!this.atPunct("->") && !this.at("eof")) {
+                const state = this.parseTemplatedName("expected a source lifecycle state");
+                if (!state)
+                    return undefined;
+                qualifiers.push(state);
+                if (this.atPunct("|"))
+                    this.advance();
+            }
+            if (!this.expectPunct("->", `on ${action.name} needs -> before its target state`)) {
+                return undefined;
+            }
+            const value = this.parseTemplatedName("expected a target lifecycle state");
+            return value
+                ? {
+                    key,
+                    qualifiers,
+                    span: { start: key.span.start, end: value.span.end },
+                    value,
+                }
+                : undefined;
+        }
+        if (key.name === "notify") {
+            const role = this.expectName("notify needs a declared role");
+            const via = role
+                ? this.expectName("notify needs via before its channel")
+                : undefined;
+            const channel = via
+                ? this.expectName("notify needs a channel")
+                : undefined;
+            if (!role || via?.name !== "via" || !channel)
+                return undefined;
+            qualifiers.push(role, channel);
+            return {
+                key,
+                qualifiers,
+                span: { start: key.span.start, end: channel.span.end },
+                value: { kind: "boolean", span: channel.span, value: true },
+            };
+        }
         if (this.atPunct("(")) {
             this.advance();
             while (!this.atPunct(")") && !this.at("eof")) {
-                const qualifier = this.expectIdent(`expected a qualifier inside ${key.name}( ... )`);
+                const qualifier = this.at("number")
+                    ? this.parseIdent()
+                    : this.expectIdent(`expected a qualifier inside ${key.name}( ... )`);
                 if (!qualifier)
                     return undefined;
                 qualifiers.push(qualifier);
@@ -289,12 +684,26 @@ class Parser {
                 return undefined;
             }
         }
+        if ((key.name === "requires" || key.name === "computes") &&
+            this.isName(this.peek())) {
+            while (this.isName(this.peek()))
+                qualifiers.push(this.parseIdent());
+        }
         let value;
         if (this.atPunct("{")) {
-            value = this.parseBlock();
+            value = this.parseBlock(key.name === "lifecycle" || context === "lifecycle"
+                ? "lifecycle"
+                : "general");
         }
         else if (this.atPunct(":")) {
             this.advance();
+            value = this.atPunct("{")
+                ? this.parseBlock(key.name === "lifecycle" || context === "lifecycle"
+                    ? "lifecycle"
+                    : "general")
+                : this.parseExpr();
+        }
+        else if (this.canStartExpr(this.peek())) {
             value = this.parseExpr();
         }
         else {
@@ -392,8 +801,40 @@ class Parser {
                 ...(within ? { within } : {}),
             };
         }
+        if (token.kind === "keyword") {
+            return this.parseIdent();
+        }
+        if (token.kind === "ident" &&
+            /^[A-Z]{3}$/.test(token.text) &&
+            this.peekAt(1).kind === "number") {
+            const currency = this.parseIdent();
+            const amount = this.advance();
+            return {
+                currency,
+                kind: "money",
+                raw: amount.value,
+                span: { start: currency.span.start, end: amount.span.end },
+            };
+        }
         if (token.kind === "ident") {
             const ident = this.parseIdent();
+            if (ident.name === "true" || ident.name === "false") {
+                return {
+                    kind: "boolean",
+                    span: ident.span,
+                    value: ident.name === "true",
+                };
+            }
+            if (ident.name === "decided" && this.atPunct("{")) {
+                const body = this.parseBlock();
+                if (!body)
+                    return undefined;
+                return {
+                    body,
+                    kind: "decided_amount",
+                    span: { end: body.span.end, start: ident.span.start },
+                };
+            }
             if (this.atPunct(".")) {
                 this.advance();
                 const member = this.expectIdent(`expected the exit after ${ident.name}., like ${ident.name}.release`);
@@ -406,6 +847,17 @@ class Parser {
                     span: { end: member.span.end, start: ident.span.start },
                 };
             }
+            if (this.atPunct("<")) {
+                const args = this.parseAngleArguments();
+                if (!args)
+                    return undefined;
+                return {
+                    args,
+                    callee: ident,
+                    kind: "type_apply",
+                    span: this.spanFrom(ident.span),
+                };
+            }
             if (this.atPunct("(")) {
                 this.advance();
                 const args = [];
@@ -482,6 +934,9 @@ class Parser {
     peek() {
         return this.tokens[this.index];
     }
+    peekAt(offset) {
+        return this.tokens[Math.min(this.index + offset, this.tokens.length - 1)];
+    }
     previous() {
         return this.tokens[Math.max(0, this.index - 1)];
     }
@@ -502,6 +957,124 @@ class Parser {
         const token = this.advance();
         return { kind: "ident", name: token.text, span: token.span };
     }
+    isName(token) {
+        return token.kind === "ident" || token.kind === "keyword";
+    }
+    expectName(message) {
+        if (this.isName(this.peek()))
+            return this.parseIdent();
+        this.error(this.peek().span, message);
+        return undefined;
+    }
+    parseTemplatedName(message) {
+        if (this.atPunct("[")) {
+            const open = this.advance();
+            const binding = this.expectIdent("an indexed name needs its loop binding");
+            if (!binding || !this.expectPunct("]", "an indexed name needs ]")) {
+                return undefined;
+            }
+            const suffix = this.isName(this.peek()) ? this.parseIdent() : undefined;
+            return {
+                kind: "ident",
+                name: `[${binding.name}]${suffix?.name ?? ""}`,
+                span: {
+                    start: open.span.start,
+                    end: suffix?.span.end ?? this.previous().span.end,
+                },
+            };
+        }
+        const base = this.expectName(message);
+        if (!base || !this.atPunct("["))
+            return base;
+        this.advance();
+        const binding = this.expectIdent("an indexed name needs its loop binding");
+        if (!binding || !this.expectPunct("]", "an indexed name needs ]")) {
+            return undefined;
+        }
+        const suffix = this.isName(this.peek()) ? this.parseIdent() : undefined;
+        return {
+            kind: "ident",
+            name: `${base.name}[${binding.name}]${suffix?.name ?? ""}`,
+            span: {
+                start: base.span.start,
+                end: suffix?.span.end ?? this.previous().span.end,
+            },
+        };
+    }
+    canStartExpr(token) {
+        return (token.kind === "ident" ||
+            token.kind === "keyword" ||
+            token.kind === "number" ||
+            token.kind === "percent" ||
+            token.kind === "string" ||
+            (token.kind === "punct" && (token.text === "{" || token.text === "[")));
+    }
+    parsePath(message) {
+        const first = this.expectName(message);
+        if (!first)
+            return undefined;
+        const parts = [first];
+        while (this.atPunct(".")) {
+            this.advance();
+            const part = this.expectName("expected a name after .");
+            if (!part)
+                return undefined;
+            parts.push(part);
+        }
+        return {
+            kind: "path",
+            parts,
+            span: {
+                start: first.span.start,
+                end: parts.at(-1)?.span.end ?? first.span.end,
+            },
+        };
+    }
+    parseAngleArguments() {
+        this.advance();
+        const args = [];
+        while (!this.atPunct(">") && !this.at("eof")) {
+            const arg = this.parseExpr();
+            if (!arg)
+                return undefined;
+            args.push(arg);
+            if (this.atPunct(","))
+                this.advance();
+        }
+        return this.expectPunct(">", "the type argument list never closes")
+            ? args
+            : undefined;
+    }
+    parseApplication() {
+        const callee = this.parsePath("expected an instrument function name");
+        if (!callee)
+            return undefined;
+        const typeArgs = this.atPunct("<") ? this.parseAngleArguments() : [];
+        if (!typeArgs)
+            return undefined;
+        if (!this.expectPunct("(", "an instrument application needs arguments in parentheses")) {
+            return undefined;
+        }
+        const args = [];
+        while (!this.atPunct(")") && !this.at("eof")) {
+            const arg = this.parseExpr();
+            if (!arg)
+                return undefined;
+            args.push(arg);
+            if (this.atPunct(","))
+                this.advance();
+        }
+        if (!this.expectPunct(")", "the instrument argument list never closes")) {
+            return undefined;
+        }
+        return {
+            args,
+            callee,
+            kind: "apply",
+            span: { start: callee.span.start, end: this.previous().span.end },
+            typeArgs,
+        };
+    }
     expectIdent(message) {
         if (this.at("ident"))
             return this.parseIdent();