@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/src/ast.ts

@@ -35,6 +35,36 @@ export function lineColAt(source: string, offset: number): LineCol {
   return { column: clamped - lineStart + 1, line };
 }
 
+const utf8Encoder = new TextEncoder();
+
+/**
+ * Convert a UTF-8 byte offset to a UTF-16 code-unit offset over a string.
+ * Walks Unicode code points, counting UTF-8 bytes and UTF-16 code units.
+ * Clamps to [0, source.length].
+ */
+export function byteOffsetToCodeUnit(
+  source: string,
+  byteOffset: number,
+): number {
+  if (byteOffset <= 0) return 0;
+  let currentByte = 0;
+  let codeUnit = 0;
+
+  for (const char of source) {
+    const charBytes = utf8Encoder.encode(char).length;
+    if (currentByte + charBytes > byteOffset) {
+      return codeUnit;
+    }
+    currentByte += charBytes;
+    codeUnit += char.length;
+    if (currentByte === byteOffset) {
+      return codeUnit;
+    }
+  }
+
+  return source.length;
+}
+
 /**
  * One source scanned once, so many offsets resolve without rescanning it.
  * `lineColAt` walks from offset zero every time, which turns a run of d
@@ -78,6 +108,8 @@ export function lineColIn(index: LineIndex, offset: number): LineCol {
 export interface IdentExpr {
   readonly kind: "ident";
   readonly name: string;
+  /** A literal quoted block key keeps its exact spelling during JSON lowering. */
+  readonly quoted?: boolean;
   readonly span: Span;
 }
 
@@ -87,13 +119,51 @@ export interface StringExpr {
   readonly value: string;
 }
 
-interface NumberExpr {
+export interface NumberExpr {
   readonly kind: "number";
   /** The literal exactly as written, e.g. "99.5". Interpretation is typed later. */
   readonly raw: string;
   readonly span: Span;
 }
 
+export interface BooleanExpr {
+  readonly kind: "boolean";
+  readonly span: Span;
+  readonly value: boolean;
+}
+
+/** A currency-indexed literal. The checker converts it to integer minor units. */
+export interface MoneyExpr {
+  readonly currency: IdentExpr;
+  readonly kind: "money";
+  readonly raw: string;
+  readonly span: Span;
+}
+
+/** A dotted name used for modules, UDL operations, and field paths. */
+export interface PathExpr {
+  readonly kind: "path";
+  readonly parts: readonly IdentExpr[];
+  readonly span: Span;
+}
+
+/** A nominal type application such as `money<SAR>` or `ref<invoice>`. */
+export interface TypeApplyExpr {
+  readonly args: readonly Expr[];
+  readonly callee: IdentExpr;
+  readonly kind: "type_apply";
+  readonly span: Span;
+}
+
+/** A general instrument or constant application, with optional type arguments. */
+export interface ApplyExpr {
+  readonly args: readonly Expr[];
+  readonly callee: PathExpr;
+  readonly kind: "apply";
+  readonly span: Span;
+  readonly typeArgs: readonly Expr[];
+}
+
 export interface PercentExpr {
   /** Exact basis points: 99.5% is 9950. Percents never round. */
   readonly bps: number;
@@ -110,6 +180,16 @@ export interface CallExpr {
   readonly span: Span;
 }
 
+/**
+ * An exit amount chosen by a decision port and bounded by stored money:
+ * `decided { field: damageAmount, bound: depositAmount, remainder: return }`.
+ */
+export interface DecidedAmountExpr {
+  readonly body: BlockExpr;
+  readonly kind: "decided_amount";
+  readonly span: Span;
+}
+
 /**
  * A reference to a decision port, optionally bounded (`port dispute within
  * P14D`) or carrying the date that decides when the port has not
@@ -155,7 +235,7 @@ export interface BlockExpr {
  * `amount: price: money(SAR)` binds the field name `price` to type
  * `money(SAR)`: the entry key is `amount`, the value is this binding.
  */
-interface BindingExpr {
+export interface BindingExpr {
   readonly kind: "binding";
   readonly name: IdentExpr;
   readonly span: Span;
@@ -163,16 +243,22 @@ interface BindingExpr {
 }
 
 export type Expr =
+  | ApplyExpr
   | BindingExpr
   | BlockExpr
+  | BooleanExpr
   | CallExpr
+  | DecidedAmountExpr
   | IdentExpr
   | ListExpr
+  | MoneyExpr
   | NumberExpr
+  | PathExpr
   | PercentExpr
   | PortRefExpr
   | SettlementRefExpr
-  | StringExpr;
+  | StringExpr
+  | TypeApplyExpr;
 
 // --- Entries ---------------------------------------------------------------
 
@@ -182,6 +268,11 @@ export type Expr =
  * and `on_cancel(funded) { ... }` (key + qualifiers + block value).
  */
 export interface Entry {
+  /** `for item in bound { ... }`, expanded before binding or UDL lowering. */
+  readonly iteration?: {
+    readonly binding: IdentExpr;
+    readonly bound: Expr;
+  };
   readonly key: IdentExpr;
   readonly qualifiers: readonly IdentExpr[];
   readonly span: Span;
@@ -198,7 +289,23 @@ export interface ProgramDecl {
   readonly title?: StringExpr;
 }
 
-/** `import { held_payment } from "settlement"`. */
+/** `use held_settlement` selects one published catalog instrument. */
+export interface UseDecl {
+  readonly instrument: IdentExpr;
+  readonly kind: "use";
+  readonly span: Span;
+}
+
+/** `expose held_settlement.release as releaseFunds` names a public action. */
+export interface ExposeDecl {
+  readonly action: IdentExpr;
+  readonly instrument: IdentExpr;
+  readonly kind: "expose";
+  readonly publicName: IdentExpr;
+  readonly span: Span;
+}
+
+/** `import { held_payment } from "std/settlements"`. */
 export interface ImportDecl {
   readonly from: StringExpr;
   readonly kind: "import";
@@ -224,11 +331,10 @@ export interface AssetDecl {
   readonly span: Span;
 }
 
-/** `settlement sale = held_payment { ... }`, an archetype instantiation. */
-export interface SettlementDecl {
-  readonly archetype: IdentExpr;
+/** A full UDL subject-kind declaration. `asset` remains shorthand for this form. */
+export interface SubjectDecl {
   readonly body: BlockExpr;
-  readonly kind: "settlement";
+  readonly kind: "subject";
   readonly name: IdentExpr;
   readonly span: Span;
 }
@@ -241,13 +347,89 @@ export interface PortDecl {
   readonly span: Span;
 }
 
+/** `module std.settlements` gives a file its importable module name. */
+export interface ModuleDecl {
+  readonly kind: "module";
+  readonly name: PathExpr;
+  readonly span: Span;
+}
+
+export interface TypeParameter {
+  readonly name: IdentExpr;
+  readonly span: Span;
+}
+
+export interface Parameter {
+  readonly name: IdentExpr;
+  readonly span: Span;
+  readonly type: Expr;
+}
+
+/** The single general instrument definition form. */
+export interface InstrumentDecl {
+  readonly body: BlockExpr;
+  /** Module-local declarations carried only while this template is bound. */
+  readonly declarationScope?: readonly ApplicationScopeDecl[];
+  readonly exported: boolean;
+  /** True when the source declared a parameter list, including an empty `()`. */
+  readonly hasParameterList: boolean;
+  readonly kind: "instrument";
+  readonly name: IdentExpr;
+  readonly parameters: readonly Parameter[];
+  readonly span: Span;
+  readonly typeParameters: readonly TypeParameter[];
+}
+
+/** Instantiation of an exported parameterized instrument. */
+export interface InstrumentApplyDecl {
+  readonly application: ApplyExpr;
+  /** Module-local declarations carried only while this application is bound. */
+  readonly declarationScope?: readonly ApplicationScopeDecl[];
+  readonly exported: boolean;
+  readonly kind: "instrument_apply";
+  readonly metadata?: BlockExpr;
+  readonly name: IdentExpr;
+  readonly span: Span;
+}
+
+export interface TypeDecl {
+  readonly exported: boolean;
+  readonly kind: "type";
+  readonly name: IdentExpr;
+  readonly span: Span;
+  readonly value: Expr;
+}
+
+export interface ConstDecl {
+  readonly exported: boolean;
+  readonly kind: "const";
+  readonly name: IdentExpr;
+  readonly span: Span;
+  readonly type?: Expr;
+  readonly value: Expr;
+}
+
+export type ApplicationScopeDecl =
+  | ConstDecl
+  | InstrumentDecl
+  | PartyDecl
+  | PortDecl
+  | TypeDecl;
+
 export type Decl =
   | AssetDecl
+  | ConstDecl
+  | ExposeDecl
   | ImportDecl
+  | InstrumentApplyDecl
+  | InstrumentDecl
+  | ModuleDecl
   | PartyDecl
   | PortDecl
   | ProgramDecl
-  | SettlementDecl;
+  | SubjectDecl
+  | TypeDecl
+  | UseDecl;
 
 // --- Program ---------------------------------------------------------------
 
@@ -263,6 +445,8 @@ export interface Program {
  * it never throws, it returns the best-effort tree plus these.
  */
 export interface Diagnostic {
+  readonly code?: string;
+  readonly fix?: string;
   readonly message: string;
   readonly span: Span;
 }

package/src/cli.ts

@@ -1,5 +1,5 @@
 /**
- * The `hsx` command line: two subcommands over the one compiler entry point.
+ * The `hsx` command line over the one compiler entry point and catalog.
  *
  * `check` prints diagnostics and says nothing else; `build` writes the
  * compiled artifacts as JSON. Neither reads the environment, neither touches
@@ -10,8 +10,13 @@
  * asserting on a subprocess's scrollback.
  */
 
+import { fileURLToPath } from "node:url";
 import { compile, type CompileResult } from "./compile.ts";
-import { HSX_IR_VERSION, HSX_VERSION } from "./version.ts";
+import type { UdlCostManifest, UdlCostTable } from "./cost.ts";
+import { hsxDiagnostics } from "./diagnostics.ts";
+import { format } from "./format.ts";
+import { startLspServer } from "./lsp/server.ts";
+import { HSX_TARGET_UDL_VERSION, HSX_VERSION } from "./version.ts";
 
 /** Filesystem and streams, injected so the CLI stays testable. */
 export interface Io {
@@ -19,6 +24,8 @@ export interface Io {
   readonly out: (line: string) => void;
   readonly readFile: (path: string) => Promise<string>;
   readonly writeFile: (path: string, contents: string) => Promise<void>;
+  readonly stdin?: NodeJS.ReadableStream;
+  readonly stdout?: NodeJS.WritableStream;
 }
 
 /**
@@ -29,20 +36,29 @@ const OK = 0;
 const REFUSED = 1;
 const USAGE = 2;
 
-const USAGE_TEXT = `hsx ${HSX_VERSION}, the HSX compiler
+export const USAGE_TEXT = `hsx ${HSX_VERSION}, the HSX compiler
 
 Usage:
   hsx check <file.hsx> [--strict]
   hsx build <file.hsx> [--out <file.json>] [--strict]
+  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  hsx explain <HSX####>
+  hsx format <file.hsx>
+  hsx lsp
   hsx --version
   hsx --help
 
 Commands:
   check   Compile and report diagnostics. Prints nothing when the program is clean.
-  build   Compile and write the HSX-JSON IR document and Business Frame as JSON.
+  build   Compile and write canonical UDL as JSON.
+  cost    Compile and print the version-pinned cost manifest as a table or JSON.
+  explain Print one diagnostic title, fix, and source example.
+  format  Print the source in the one canonical HSX style.
+  lsp     Run the language server over stdin and stdout.
 
 Options:
-  --out <file>  Write build output to this path instead of stdout.
+  --json        Print the cost manifest as JSON instead of a table.
+  --out <file>  Write build or cost JSON to this path instead of stdout.
   --strict      Treat warning-severity diagnostics as failures.
 
 Exit codes:
@@ -58,10 +74,25 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     return command === undefined ? USAGE : OK;
   }
   if (command === "--version" || command === "-v") {
-    io.out(`${HSX_VERSION} (IR version ${HSX_IR_VERSION})`);
+    io.out(`${HSX_VERSION} (UDL version ${HSX_TARGET_UDL_VERSION})`);
     return OK;
   }
-  if (command !== "check" && command !== "build") {
+  if (command === "explain") return explainDiagnostic(rest, io);
+  if (command === "lsp") {
+    const input = io.stdin ?? process.stdin;
+    const output = io.stdout ?? process.stdout;
+    return new Promise<number>((resolve) => {
+      startLspServer(input, output, {
+        onExit: resolve,
+      });
+    });
+  }
+  if (
+    command !== "check" &&
+    command !== "build" &&
+    command !== "cost" &&
+    command !== "format"
+  ) {
     io.err(`hsx: unknown command "${command}"`);
     io.err(USAGE_TEXT);
     return USAGE;
@@ -81,7 +112,26 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     return USAGE;
   }
 
-  const result = compile(source);
+  if (command === "format") {
+    const result = format(source);
+    if (!result.ok) {
+      for (const diagnostic of result.diagnostics) {
+        io.err(`${parsed.file}:1:1: error [parse] ${diagnostic.message}`);
+      }
+      return REFUSED;
+    }
+    io.out(result.formatted.trimEnd());
+    return OK;
+  }
+
+  let costTable: UdlCostTable;
+  try {
+    costTable = await readDefaultCostTable(io);
+  } catch (cause) {
+    io.err(`hsx: cannot read the packaged cost table: ${messageOf(cause)}`);
+    return USAGE;
+  }
+  const result = compile(source, { costTable });
   for (const line of diagnosticLines(parsed.file, result)) io.err(line);
 
   const refused =
@@ -93,14 +143,20 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
   }
 
   if (!result.artifacts) return REFUSED;
-  const json = `${JSON.stringify(
-    {
-      document: result.artifacts.document,
-      frame: result.artifacts.frame,
-    },
-    null,
-    2,
-  )}\n`;
+  if (command === "cost") {
+    const json = `${JSON.stringify(result.artifacts.costManifest, null, 2)}\n`;
+    if (parsed.out !== undefined) {
+      const writeCode = await writeOutput(parsed.out, json, io);
+      return writeCode === OK && refused ? REFUSED : writeCode;
+    }
+    io.out(
+      parsed.json
+        ? json.trimEnd()
+        : renderCostTable(result.artifacts.costManifest),
+    );
+    return refused ? REFUSED : OK;
+  }
+  const json = `${JSON.stringify(result.artifacts.document, null, 2)}\n`;
   if (parsed.out === undefined) {
     io.out(json.trimEnd());
   } else {
@@ -116,26 +172,38 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
 
 interface Options {
   readonly file: string;
+  readonly json: boolean;
   readonly out?: string;
   readonly strict: boolean;
 }
 
 function parseOptions(
   args: readonly string[],
-  command: "build" | "check",
+  command: "build" | "check" | "cost" | "format",
 ): Options | { readonly error: string } {
   let file: string | undefined;
+  let json = false;
   let out: string | undefined;
   let strict = false;
 
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index] as string;
     if (argument === "--strict") {
+      if (command === "format") {
+        return { error: "hsx format has no style options" };
+      }
       strict = true;
       continue;
     }
+    if (argument === "--json") {
+      if (command !== "cost") return { error: "--json belongs to hsx cost" };
+      json = true;
+      continue;
+    }
     if (argument === "--out") {
-      if (command !== "build") return { error: "--out belongs to hsx build" };
+      if (command !== "build" && command !== "cost") {
+        return { error: "--out belongs to hsx build or hsx cost" };
+      }
       const value = args[index + 1];
       if (value === undefined || value.startsWith("--")) {
         return { error: "--out needs a file path" };
@@ -154,7 +222,98 @@ function parseOptions(
   }
 
   if (file === undefined) return { error: `hsx ${command} needs a file` };
-  return { file, ...(out === undefined ? {} : { out }), strict };
+  return { file, json, ...(out === undefined ? {} : { out }), strict };
+}
+
+function explainDiagnostic(args: readonly string[], io: Io): number {
+  if (args.length !== 1 || args[0]?.startsWith("-")) {
+    io.err("hsx: explain needs one diagnostic code");
+    return USAGE;
+  }
+  const diagnostic = hsxDiagnostics.find(({ code }) => code === args[0]);
+  if (!diagnostic) {
+    io.err(`hsx: unknown diagnostic code ${args[0]}`);
+    return USAGE;
+  }
+  io.out(
+    [
+      `${diagnostic.code} ${diagnostic.title}`,
+      `Stage: ${diagnostic.stage}`,
+      `Fix: ${diagnostic.fix}`,
+      diagnostic.example === null
+        ? "Example: unavailable from source alone"
+        : `Example:\n${diagnostic.example}`,
+    ].join("\n"),
+  );
+  return OK;
+}
+
+function renderCostTable(manifest: UdlCostManifest): string {
+  const rows = [
+    `costTableVersion\t${manifest.costTableVersion}`,
+    "instrument.action\teffect\tunit\tcount\ttotal\tpayer",
+  ];
+  for (const action of manifest.actions) {
+    for (const component of action.components) {
+      const fixed = BigInt(component.perEventMinor) * BigInt(component.count);
+      const unit = [
+        `${component.perEventMinor} ${manifest.currency} minor`,
+        component.bps > 0 ? `${component.bps} bps` : undefined,
+      ]
+        .filter((part): part is string => part !== undefined)
+        .join(" + ");
+      const total =
+        component.bps === 0
+          ? `${fixed} ${manifest.currency} minor`
+          : [
+              fixed === 0n ? undefined : `${fixed} ${manifest.currency} minor`,
+              `amount-dependent (${component.bps} bps)`,
+            ]
+              .filter((part): part is string => part !== undefined)
+              .join(" + ");
+      rows.push(
+        [
+          `${action.instrument}.${action.action}`,
+          component.signature,
+          unit,
+          component.count,
+          total,
+          component.payer,
+        ].join("\t"),
+      );
+    }
+  }
+  return rows.join("\n");
+}
+
+async function writeOutput(
+  path: string,
+  contents: string,
+  io: Io,
+): Promise<number> {
+  try {
+    await io.writeFile(path, contents);
+  } catch (cause) {
+    io.err(`hsx: cannot write ${path}: ${messageOf(cause)}`);
+    return USAGE;
+  }
+  return OK;
+}
+
+async function readDefaultCostTable(io: Io): Promise<UdlCostTable> {
+  const candidates = [
+    fileURLToPath(new URL("../examples/cost-table.json", import.meta.url)),
+    fileURLToPath(new URL("../../examples/cost-table.json", import.meta.url)),
+  ];
+  let lastError: unknown;
+  for (const path of candidates) {
+    try {
+      return JSON.parse(await io.readFile(path)) as UdlCostTable;
+    } catch (cause) {
+      lastError = cause;
+    }
+  }
+  throw lastError;
 }
 
 /** `file:line:col: severity [stage] message`, the shape editors already parse. */
@@ -164,10 +323,22 @@ function diagnosticLines(
 ): readonly string[] {
   return result.diagnostics.map(
     (diagnostic) =>
-      `${file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.severity} [${diagnostic.stage}] ${diagnostic.message}`,
+      `${diagnostic.file ?? file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.severity} [${diagnostic.stage}] ${diagnostic.message}`,
   );
 }
 
 function messageOf(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }
+
+if (import.meta.main) {
+  const { readFile, writeFile } = await import("node:fs/promises");
+  process.exitCode = await runCli(process.argv.slice(2), {
+    err: (line) => process.stderr.write(`${line}\n`),
+    out: (line) => process.stdout.write(`${line}\n`),
+    readFile: (path) => readFile(path, "utf8"),
+    writeFile: (path, contents) => writeFile(path, contents, "utf8"),
+    stdin: process.stdin,
+    stdout: process.stdout,
+  });
+}