@hyperscale0/hsx 5.2.0 → 5.4.0

package/src/diagnostics.ts

@@ -0,0 +1,28 @@
+import type { Diagnostic, Span } from "./ast.ts";
+
+export class CompileFailure extends Error {
+  constructor(readonly diagnostic: Diagnostic) {
+    super(diagnostic.message);
+  }
+}
+export function fail(
+  expr: { span: Span; source?: string },
+  message: string,
+  fix: string,
+): never {
+  return failWithCode(expr, "HSX1001", message, fix);
+}
+export function failWithCode(
+  expr: { span: Span; source?: string },
+  code: string,
+  message: string,
+  fix: string,
+): never {
+  throw new CompileFailure({
+    code,
+    message,
+    fix,
+    span: expr.span,
+    ...(expr.source ? { source: expr.source } : {}),
+  });
+}

package/src/header-source.ts

@@ -0,0 +1,54 @@
+import { parseProgram } from "./parse.ts";
+import { CompileFailure, fail } from "./diagnostics.ts";
+
+/** Compilation and editor metadata admit the same named header declarations. */
+export function parseHeader(source: string, name: string) {
+  const parsed = parseProgram(source);
+  if (parsed.diagnostics.length)
+    throw new CompileFailure({ ...parsed.diagnostics[0]!, source: name });
+  const program = parsed.program;
+  const locate = (value: unknown): void => {
+    if (!value || typeof value !== "object") return;
+    if ("span" in value) Object.assign(value, { source: name });
+    for (const child of Object.values(value)) locate(child);
+  };
+  locate(program);
+  if (!program.header || program.name !== name)
+    fail(
+      program,
+      `${name}: expected header ${name}`,
+      `start with header ${name}`,
+    );
+  const names = new Set<string>();
+  for (const decl of program.decls) {
+    if (decl.kind !== "instrument") continue;
+    if (names.has(decl.name))
+      fail(
+        decl,
+        `duplicate instrument ${name}.${decl.name}`,
+        "give each instrument a distinct name",
+      );
+    names.add(decl.name);
+    const parameters = new Set<string>();
+    for (const parameter of decl.parameters) {
+      if (parameters.has(parameter.key))
+        fail(
+          parameter,
+          `duplicate parameter ${parameter.key}`,
+          "declare each parameter once",
+        );
+      parameters.add(parameter.key);
+      const type =
+        parameter.value.kind === "default"
+          ? parameter.value.type
+          : parameter.value;
+      if (type.kind === "call" && !["enum", "integer"].includes(type.name))
+        fail(
+          type,
+          `unsupported tunable constructor ${type.name}`,
+          "Only enum(choices) and integer(minimum, maximum) are supported tunable constructors. This constructor's restrictions cannot be enforced.",
+        );
+    }
+  }
+  return program;
+}

package/src/headers.ts

@@ -3,7 +3,7 @@ import {
   parameterDiagnostics,
 } from "./binding-contract.ts";
 import { tunableBounds } from "./tunables.ts";
-import { parseProgram } from "./parse.ts";
+import { parseHeader } from "./header-source.ts";
 import { bundledStandardLibrary, type StandardLibrary } from "./std-library.ts";
 import type { BlockExpr, Expr } from "./ast.ts";
 
@@ -32,9 +32,7 @@ export function headerManifest(
     headers: names.map((name) => {
       const source = library.source(name);
       if (!source) throw new Error(`Missing standard header ${name}`);
-      const parsed = parseProgram(source);
-      if (parsed.diagnostics.length)
-        throw new Error(`${name}: ${parsed.diagnostics[0]!.message}`);
+      const parsed = parseHeader(source, name);
       const spelling = (expression: Expr) =>
         source.slice(expression.span.start, expression.span.end).trim();
       const actions = (
@@ -66,7 +64,7 @@ export function headerManifest(
       };
       return {
         name,
-        objects: parsed.program.decls
+        objects: parsed.decls
           .filter((d) => d.kind === "instrument")
           .map((decl) => {
             const tunables = decl.parameters.map((parameter) => {
@@ -184,7 +182,7 @@ export function headerManifest(
                   if (subject?.kind !== "block") continue;
                   for (const field of subject.entries) {
                     const type = spelling(field.value);
-                    if (type !== "adapter") fields.set(field.key, type);
+                    if (field.key !== "adapter") fields.set(field.key, type);
                   }
                 }
                 return [...fields].map(([name, type]) => ({ name, type }));

package/src/keywords.ts

@@ -9,11 +9,11 @@ export const KEYWORD_HELP = {
   header: ["Names a reusable library of instruments."],
   use: ["Makes a header's instruments available to this program."],
   party: [
-    "Declares a person or business that can own accounts or act in an agreement.",
+    "Declares a person, business or staff party. Staff authority requires a permission role.",
     "Parties",
   ],
   role: ["Names the responsibility a declared party has in this product."],
-  currency: ["Sets the currency used by the program's money amounts."],
+  currency: ["Declares SAR, the currency supported by this compiler."],
   instrument: [
     "Defines an agreement's fields, states and permitted actions.",
     "Instruments",
@@ -37,7 +37,9 @@ export const KEYWORD_HELP = {
   of: [
     "Names the owner of an account, or the records included in a count or sum.",
   ],
-  when: ["Includes rules only when a parameter selects the stated option."],
+  when: [
+    "Includes clauses for a selected enum value or a field present on a bound reference.",
+  ],
   constraints: [
     "Requires parameter values to agree with each other before the program can be used.",
   ],
@@ -61,9 +63,15 @@ export const KEYWORD_HELP = {
     "Requires a referenced agreement to be in one of the listed states.",
     "State requirement",
   ],
-  by: ["Names who performs the stated operation."],
-  for: ["Identifies the subject of the stated rule."],
   is: ["Selects rules for one named parameter choice."],
+  has: ["Selects clauses when a bound reference declares the named field."],
+  family: ["Names an instrument family or the family of an evidence check."],
+  check: ["Names the provider check whose evidence the action requires."],
+  result: ["Names the required outcome of an evidence check."],
+  maxAge: ["Limits how old the required evidence may be."],
+  instruction: ["Binds evidence to the captured boundary instruction."],
+  boundary: ["Dispatches a reserved move through a bound ADL adapter."],
+  key: ["Names a move within its action."],
   unique: [
     "Rejects a repeated combination of values in the named namespace.",
     "Unique requirement",

package/src/lex.ts

@@ -23,9 +23,8 @@ export const KEYWORDS = [
   "from",
   "to",
   "in",
-  "by",
-  "for",
   "is",
+  "has",
   "unique",
   "on",
   "count",
@@ -35,10 +34,17 @@ export const KEYWORDS = [
   "and",
   "timezone",
   "evidence",
+  "family",
+  "check",
+  "result",
+  "maxAge",
+  "instruction",
   "reserve",
   "post",
   "void",
   "capture",
+  "boundary",
+  "key",
   "fee",
   "shares",
   "object",
@@ -99,9 +105,11 @@ export function scan(
       kind = "name";
       text = name[0];
     } else if (tail[0] === '"') {
-      const quoted = /^"(?:[^"\\\n]|\\["\\/bfnrt]|\\u[0-9a-fA-F]{4})*"/.exec(
-        tail,
-      );
+      const quoted =
+        // oxlint-disable-next-line no-control-regex -- JSON strings must escape raw control characters.
+        /^"(?:[^"\\\u0000-\u001f]|\\["\\/bfnrt]|\\u[0-9a-fA-F]{4})*"/.exec(
+          tail,
+        );
       if (!quoted) {
         diagnostics.push({
           code: "HSX1000",

package/src/parse.ts

@@ -37,6 +37,18 @@ export function parseProgram(source: string): {
         },
       ],
     };
+  if (/^\s*[[{]/.test(source))
+    return {
+      program: empty,
+      diagnostics: [
+        {
+          code: "HSX1014",
+          message: "JSON is not HSX source",
+          fix: 'write program name "Title" followed by HSX declarations',
+          span: { start: source.search(/\S/), end: source.search(/\S/) + 1 },
+        },
+      ],
+    };
   const result = lex(source);
   if (result.diagnostics.length)
     return { program: empty, diagnostics: result.diagnostics };
@@ -71,12 +83,12 @@ class Parser {
     this.take();
     return true;
   }
-  private fail(message: string, fix: string): never {
+  private fail(message: string, fix: string, span = this.peek().span): never {
     throw new ParseFailure({
       code: "HSX1000",
       message,
       fix,
-      span: this.peek().span,
+      span,
     });
   }
   private expect(text: string): void {
@@ -114,11 +126,19 @@ class Parser {
         );
       program.title = JSON.parse(this.take().text) as string;
     }
+    let currencyDeclared = false;
     while (this.peek().kind !== "eof") {
       this.separators();
       if (this.peek().kind === "eof") break;
       const start = this.peek().span.start;
-      if (this.eat("currency")) {
+      if (this.at("currency")) {
+        if (currencyDeclared)
+          this.fail(
+            "currency is declared twice",
+            "keep one currency declaration",
+          );
+        this.take();
+        currencyDeclared = true;
         program.currency = this.identifier();
         continue;
       }
@@ -326,8 +346,12 @@ class Parser {
   private operator(): Expr {
     const operator = this.take();
     if (!["==", "!=", "<", "<=", ">", ">="].includes(operator.text))
-      this.fail("expected a comparison", "write ==, !=, <, <=, >, or >=");
-    return this.node(operator.text);
+      this.fail(
+        "expected a comparison",
+        "write ==, !=, <, <=, >, or >=",
+        operator.span,
+      );
+    return { kind: "text", value: operator.text, span: operator.span };
   }
   private requirement(): BlockExpr {
     if (this.eat("unique")) {