@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0-rc.1

package/src/entry-overrides.ts

@@ -1,19 +1,35 @@
 /**
  * Data-driven replacement of existing settlement entries. This is not syntax:
  * callers select a slot that already exists in the parsed program, replace its
- * literal value, then run the ordinary checker and lowerer again.
+ * literal value, then run the ordinary general compiler again.
  */
 
-import type { BlockExpr, Entry, Expr, Program, SettlementDecl } from "./ast.ts";
+import type {
+  BlockExpr,
+  Entry,
+  Expr,
+  InstrumentApplyDecl,
+  Program,
+} from "./ast.ts";
 
 export type ProgramEntryOverrideValue =
   | { readonly kind: "integer"; readonly value: number }
-  | { readonly kind: "basis_points"; readonly value: number };
+  | { readonly kind: "basis_points"; readonly value: number }
+  | {
+      readonly currency: string;
+      readonly kind: "money";
+      readonly value: number;
+    }
+  | { readonly kind: "duration"; readonly value: string };
 
-export interface ProgramEntryOverrideBounds {
-  readonly max: number;
-  readonly min: number;
-}
+export type ProgramEntryOverrideBounds =
+  | { readonly max: number; readonly min: number }
+  | {
+      readonly currency: string;
+      readonly max: number;
+      readonly min: number;
+    }
+  | { readonly max: string; readonly min: string };
 
 export interface ProgramEntryOverride {
   readonly bounds: ProgramEntryOverrideBounds;
@@ -52,49 +68,151 @@ function percentRaw(bps: number): string {
     : `${whole}.${String(fraction).padStart(2, "0").replace(/0$/, "")}`;
 }
 
+function durationMagnitude(
+  value: string,
+): { readonly amount: number; readonly family: "days" | "months" } | undefined {
+  const match = /^P([1-9][0-9]{0,3})([DWMY])$/.exec(value);
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  switch (match[2]) {
+    case "D":
+      return { amount, family: "days" };
+    case "W":
+      return { amount: amount * 7, family: "days" };
+    case "M":
+      return { amount, family: "months" };
+    case "Y":
+      return { amount: amount * 12, family: "months" };
+    default:
+      return undefined;
+  }
+}
+
 function replacementExpr(
   current: Expr,
   value: ProgramEntryOverrideValue,
-): Expr {
+): { readonly expr?: Expr; readonly issue?: string } {
   if (value.kind === "integer") {
-    return { kind: "number", raw: String(value.value), span: current.span };
+    return current.kind === "number"
+      ? {
+          expr: {
+            kind: "number",
+            raw: String(value.value),
+            span: current.span,
+          },
+        }
+      : { issue: "target is not an integer literal" };
+  }
+  if (value.kind === "basis_points") {
+    return current.kind === "percent"
+      ? {
+          expr: {
+            bps: value.value,
+            kind: "percent",
+            raw: percentRaw(value.value),
+            span: current.span,
+          },
+        }
+      : { issue: "target is not a percentage literal" };
+  }
+  if (value.kind === "duration") {
+    return current.kind === "ident" && durationMagnitude(current.name)
+      ? {
+          expr: { kind: "ident", name: value.value, span: current.span },
+        }
+      : { issue: "target is not an ISO-8601 duration literal" };
+  }
+  if (
+    current.kind !== "binding" ||
+    current.type.kind !== "call" ||
+    current.type.callee.name !== "money" ||
+    current.type.args.length !== 2 ||
+    current.type.args[0]?.kind !== "ident" ||
+    current.type.args[1]?.kind !== "number"
+  ) {
+    return { issue: "target is not a fixed money literal" };
+  }
+  if (current.type.args[0].name !== value.currency) {
+    return {
+      issue: `target currency ${current.type.args[0].name} does not match ${value.currency}`,
+    };
   }
   return {
-    bps: value.value,
-    kind: "percent",
-    raw: percentRaw(value.value),
-    span: current.span,
+    expr: {
+      ...current,
+      type: {
+        ...current.type,
+        args: [
+          current.type.args[0],
+          {
+            kind: "number",
+            raw: String(value.value),
+            span: current.type.args[1].span,
+          },
+        ],
+      },
+    },
   };
 }
 
-function replaceEntry(
+function selectedEntry(
   block: BlockExpr,
   path: readonly string[],
-  value: ProgramEntryOverrideValue,
-): { readonly block?: BlockExpr; readonly issue?: string } {
+):
+  | {
+      readonly match: { readonly entry: Entry; readonly index: number };
+      readonly tail: readonly string[];
+    }
+  | { readonly issue: string } {
   const [head, ...tail] = path;
   const matches = block.entries
     .map((entry, index) => ({ entry, index }))
     .filter(({ entry }) => entry.key.name === head);
   if (matches.length === 0) return { issue: `entry ${head} does not exist` };
-  if (matches.length > 1) return { issue: `entry ${head} is ambiguous` };
+  if (matches.length === 1) return { match: matches[0]!, tail };
+  const occurrence = Number(tail[0]);
+  if (!Number.isInteger(occurrence) || occurrence < 0) {
+    return { issue: `entry ${head} is ambiguous` };
+  }
+  const match = matches[occurrence];
+  return match
+    ? { match, tail: tail.slice(1) }
+    : { issue: `entry ${head} occurrence ${occurrence} does not exist` };
+}
 
-  const match = matches[0] as { readonly entry: Entry; readonly index: number };
+function replaceEntry(
+  block: BlockExpr,
+  path: readonly string[],
+  value: ProgramEntryOverrideValue,
+): { readonly block?: BlockExpr; readonly issue?: string } {
+  const selected = selectedEntry(block, path);
+  if (!("match" in selected)) return selected;
+  const { match, tail } = selected;
   let nextEntry: Entry;
   if (tail.length === 0) {
-    if (
-      match.entry.value.kind !== "number" &&
-      match.entry.value.kind !== "percent"
-    ) {
-      return { issue: `entry ${head} is not a numeric literal` };
+    const replacement = replacementExpr(match.entry.value, value);
+    if (!replacement.expr) return replacement;
+    nextEntry = {
+      ...match.entry,
+      value: replacement.expr,
+    };
+  } else if (
+    tail.length === 1 &&
+    tail[0] === "within" &&
+    match.entry.value.kind === "port_ref" &&
+    match.entry.value.within
+  ) {
+    const replacement = replacementExpr(match.entry.value.within, value);
+    if (!replacement.expr || replacement.expr.kind !== "ident") {
+      return replacement;
     }
     nextEntry = {
       ...match.entry,
-      value: replacementExpr(match.entry.value, value),
+      value: { ...match.entry.value, within: replacement.expr },
     };
   } else {
     if (match.entry.value.kind !== "block") {
-      return { issue: `entry ${head} is not a block` };
+      return { issue: `entry ${match.entry.key.name} is not a block` };
     }
     const nested = replaceEntry(match.entry.value, tail, value);
     if (!nested.block) return nested;
@@ -114,17 +232,80 @@ function replaceEntry(
 function settlementByName(
   program: Program,
   name: string,
-): SettlementDecl | undefined {
+): InstrumentApplyDecl | undefined {
   return program.decls.find(
-    (decl): decl is SettlementDecl =>
-      decl.kind === "settlement" && decl.name.name === name,
+    (decl): decl is InstrumentApplyDecl =>
+      decl.kind === "instrument_apply" && decl.name.name === name,
   );
 }
 
+function applicationBody(settlement: InstrumentApplyDecl): BlockExpr {
+  return {
+    entries: settlement.application.args.flatMap((argument) =>
+      argument.kind === "binding"
+        ? [
+            {
+              key: argument.name,
+              qualifiers: [],
+              span: argument.span,
+              value: argument.type,
+            },
+          ]
+        : [],
+    ),
+    kind: "block",
+    span: settlement.application.span,
+  };
+}
+
 function validateOverride(
   override: ProgramEntryOverride,
 ): ProgramEntryOverrideIssue | undefined {
   const { max, min } = override.bounds;
+  if (override.value.kind === "duration") {
+    if (typeof min !== "string" || typeof max !== "string") {
+      return issue(
+        override,
+        "invalid_bounds",
+        "duration bounds must be ISO-8601 durations",
+      );
+    }
+    const minDuration = durationMagnitude(min);
+    const maxDuration = durationMagnitude(max);
+    if (
+      !minDuration ||
+      !maxDuration ||
+      minDuration.family !== maxDuration.family ||
+      minDuration.amount > maxDuration.amount
+    ) {
+      return issue(
+        override,
+        "invalid_bounds",
+        `duration bounds ${min}..${max} must be valid, comparable, and ordered`,
+      );
+    }
+    const value = durationMagnitude(override.value.value);
+    if (
+      !value ||
+      value.family !== minDuration.family ||
+      value.amount < minDuration.amount ||
+      value.amount > maxDuration.amount
+    ) {
+      return issue(
+        override,
+        "invalid_value",
+        `override value ${override.value.value} is outside ${min}..${max}`,
+      );
+    }
+    return undefined;
+  }
+  if (typeof min !== "number" || typeof max !== "number") {
+    return issue(
+      override,
+      "invalid_bounds",
+      "numeric bounds must be finite nonnegative integers",
+    );
+  }
   if (
     !Number.isFinite(min) ||
     !Number.isInteger(min) ||
@@ -133,33 +314,54 @@ function validateOverride(
     !Number.isInteger(max) ||
     max < min
   ) {
-    return {
-      code: "invalid_bounds",
-      message: `override bounds ${min}..${max} must be finite nonnegative integers with min at most max`,
-      path: override.path,
-      settlement: override.settlement,
-    };
+    return issue(
+      override,
+      "invalid_bounds",
+      `override bounds ${min}..${max} must be finite nonnegative integers with min at most max`,
+    );
   }
 
   const { value } = override.value;
   if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
-    return {
-      code: "invalid_value",
-      message: `override value ${value} must be a finite nonnegative integer`,
-      path: override.path,
-      settlement: override.settlement,
-    };
+    return issue(
+      override,
+      "invalid_value",
+      `override value ${value} must be a finite nonnegative integer`,
+    );
   }
   if (value < min || value > max) {
-    return {
-      code: "invalid_value",
-      message: `override value ${value} is outside ${min}..${max}`,
-      path: override.path,
-      settlement: override.settlement,
-    };
+    return issue(
+      override,
+      "invalid_value",
+      `override value ${value} is outside ${min}..${max}`,
+    );
+  }
+  if (override.value.kind === "money") {
+    const boundsCurrency =
+      "currency" in override.bounds ? override.bounds.currency : undefined;
+    if (!boundsCurrency || boundsCurrency !== override.value.currency) {
+      return issue(
+        override,
+        "invalid_bounds",
+        `money bounds must use currency ${override.value.currency}`,
+      );
+    }
   }
 }
 
+function issue(
+  override: ProgramEntryOverride,
+  code: ProgramEntryOverrideIssue["code"],
+  message: string,
+): ProgramEntryOverrideIssue {
+  return {
+    code,
+    message,
+    path: override.path,
+    settlement: override.settlement,
+  };
+}
+
 /**
  * Applies every override atomically. A missing or non-literal slot returns
  * issues and no program, so callers never lower a partially configured shape.
@@ -187,7 +389,7 @@ export function overrideProgramEntries(
       continue;
     }
     const replaced = replaceEntry(
-      settlement.body,
+      applicationBody(settlement),
       override.path,
       override.value,
     );
@@ -203,7 +405,20 @@ export function overrideProgramEntries(
     current = {
       ...current,
       decls: current.decls.map((decl) =>
-        decl === settlement ? { ...settlement, body: replaced.block! } : decl,
+        decl === settlement
+          ? {
+              ...settlement,
+              application: {
+                ...settlement.application,
+                args: replaced.block!.entries.map((entry) => ({
+                  kind: "binding" as const,
+                  name: entry.key,
+                  span: entry.span,
+                  type: entry.value,
+                })),
+              },
+            }
+          : decl,
       ),
     };
   }

package/src/format.ts

@@ -0,0 +1,261 @@
+import type { BlockExpr, Decl, Diagnostic, Entry, Expr, Span } from "./ast.ts";
+import { lex, type CommentTrivia } from "./lex.ts";
+import { parseProgram } from "./parse.ts";
+
+export type FormatResult =
+  | { readonly formatted: string; readonly ok: true }
+  | { readonly diagnostics: readonly Diagnostic[]; readonly ok: false };
+
+export function format(source: string): FormatResult {
+  const parsed = parseProgram(source);
+  if (parsed.diagnostics.length > 0) {
+    return { diagnostics: parsed.diagnostics, ok: false };
+  }
+
+  const context: FormatContext = { comments: lex(source).comments, source };
+  return {
+    formatted: `${renderSequence(
+      parsed.program.decls,
+      parsed.program.span,
+      0,
+      (decl) => renderDecl(decl, context),
+      context,
+    )}\n`,
+    ok: true,
+  };
+}
+
+interface FormatContext {
+  readonly comments: readonly CommentTrivia[];
+  readonly source: string;
+}
+
+function renderDecl(decl: Decl, context: FormatContext): string {
+  switch (decl.kind) {
+    case "module":
+      return `module ${renderExpr(decl.name, 0, context)};`;
+    case "program":
+      return `program ${decl.name.name}${decl.title ? ` ${renderExpr(decl.title, 0, context)}` : ""};`;
+    case "use":
+      return `use ${decl.instrument.name};`;
+    case "expose":
+      return `expose ${decl.instrument.name}.${decl.action.name} as ${decl.publicName.name};`;
+    case "import":
+      return `import { ${decl.names.map((name) => name.name).join(", ")} } from ${renderExpr(decl.from, 0, context)};`;
+    case "party":
+      return renderBlockDecl(
+        `party ${decl.name.name}: ${decl.partyKind.name}`,
+        decl.attrs,
+        context,
+      );
+    case "asset":
+      return renderBlockDecl(
+        `asset ${decl.name.name}: ${decl.assetKind.name}`,
+        decl.attrs,
+        context,
+      );
+    case "subject":
+      return `subject ${decl.name.name} ${renderBlock(decl.body, 0, context)}`;
+    case "port":
+      return `port ${decl.name.name} ${renderBlock(decl.body, 0, context)}`;
+    case "instrument": {
+      const exported = decl.exported ? "export " : "";
+      const typeParameters =
+        decl.typeParameters.length > 0
+          ? `<${decl.typeParameters.map((parameter) => parameter.name.name).join(", ")}>`
+          : "";
+      const parameters = decl.hasParameterList
+        ? `(${decl.parameters
+            .map(
+              (parameter) =>
+                `${parameter.name.name}: ${renderExpr(parameter.type, 0)}`,
+            )
+            .join(", ")})`
+        : "";
+      return `${exported}instrument ${decl.name.name}${typeParameters}${parameters} ${renderBlock(decl.body, 0, context)}`;
+    }
+    case "instrument_apply":
+      return `${decl.exported ? "export " : ""}instrument ${decl.name.name} = ${renderExpr(decl.application, 0, context)}${decl.metadata ? ` ${renderBlock(decl.metadata, 0, context)}` : ";"}`;
+    case "type":
+      return `${decl.exported ? "export " : ""}type ${decl.name.name} = ${renderExpr(decl.value, 0, context)};`;
+    case "const": {
+      const type = decl.type ? `: ${renderExpr(decl.type, 0, context)}` : "";
+      return `${decl.exported ? "export " : ""}const ${decl.name.name}${type} = ${renderExpr(decl.value, 0, context)};`;
+    }
+  }
+}
+
+function renderBlockDecl(
+  header: string,
+  body: BlockExpr | undefined,
+  context: FormatContext,
+): string {
+  return body ? `${header} ${renderBlock(body, 0, context)}` : `${header};`;
+}
+
+function renderBlock(
+  block: BlockExpr,
+  indent: number,
+  context: FormatContext,
+): string {
+  const rows = renderSequence(
+    block.entries,
+    block.span,
+    indent + 1,
+    (entry) =>
+      `${spaces(indent + 1)}${renderEntry(entry, indent + 1, context)}`,
+    context,
+  );
+  if (rows.length === 0) return "{}";
+  return `{\n${rows}\n${spaces(indent)}}`;
+}
+
+function renderEntry(
+  entry: Entry,
+  indent: number,
+  context: FormatContext,
+): string {
+  const key = entry.key.name;
+  const identifierKey =
+    /^[A-Za-z][A-Za-z0-9_]*(?:\[[A-Za-z][A-Za-z0-9_]*\][A-Za-z0-9_]*)?$/.test(
+      key,
+    );
+  const renderedKey =
+    !entry.key.quoted && identifierKey ? key : JSON.stringify(key);
+  if (entry.iteration && entry.value.kind === "block") {
+    return `for ${entry.iteration.binding.name} in ${renderExpr(entry.iteration.bound, indent, context)} ${renderBlock(entry.value, indent, context)}`;
+  }
+  if (key === "action" && entry.value.kind === "block") {
+    return `action ${entry.qualifiers[0]?.name ?? ""} ${renderBlock(entry.value, indent, context)}`;
+  }
+  if (key === "states" && entry.value.kind === "list") {
+    return `states ${entry.value.items.map((item) => renderExpr(item, indent, context)).join(" ")};`;
+  }
+  if (key === "initial") {
+    return `initial ${renderExpr(entry.value, indent, context)};`;
+  }
+  if (key === "parked") {
+    return `parked ${entry.qualifiers[0]?.name ?? ""} reason ${renderExpr(entry.value, indent, context)};`;
+  }
+  if (key === "on") {
+    const [action, ...states] = entry.qualifiers;
+    return `on ${action?.name ?? ""}: ${states.map((state) => state.name).join(" | ")} -> ${renderExpr(entry.value, indent, context)};`;
+  }
+  if (key === "notify") {
+    return `notify ${entry.qualifiers[0]?.name ?? ""} via ${entry.qualifiers[1]?.name ?? ""};`;
+  }
+
+  const qualifier = renderQualifier(key, entry);
+  if (entry.value.kind === "block") {
+    return `${renderedKey}${qualifier} ${renderBlock(entry.value, indent, context)}`;
+  }
+  return `${renderedKey}${qualifier}: ${renderExpr(entry.value, indent, context)};`;
+}
+
+function renderQualifier(key: string, entry: Entry): string {
+  if (entry.qualifiers.length === 0) return "";
+  const names = entry.qualifiers.map((qualifier) => qualifier.name);
+  return key === "requires" || key === "computes"
+    ? ` ${names.join(" ")}`
+    : `(${names.join(", ")})`;
+}
+
+function renderExpr(
+  expr: Expr,
+  indent: number,
+  context?: FormatContext,
+): string {
+  switch (expr.kind) {
+    case "ident":
+      return expr.name;
+    case "string":
+      return `"${expr.value}"`;
+    case "number":
+      return expr.raw;
+    case "boolean":
+      return String(expr.value);
+    case "money":
+      return `${expr.currency.name} ${expr.raw}`;
+    case "percent":
+      return `${expr.raw}%`;
+    case "path":
+      return expr.parts.map((part) => part.name).join(".");
+    case "settlement_ref":
+      return `${expr.owner.name}.${expr.member.name}`;
+    case "type_apply":
+      return `${expr.callee.name}<${expr.args.map((arg) => renderExpr(arg, indent, context)).join(", ")}>`;
+    case "call":
+      return `${expr.callee.name}(${expr.args.map((arg) => renderExpr(arg, indent, context)).join(", ")})`;
+    case "apply": {
+      const typeArgs =
+        expr.typeArgs.length > 0
+          ? `<${expr.typeArgs.map((arg) => renderExpr(arg, indent, context)).join(", ")}>`
+          : "";
+      return `${renderExpr(expr.callee, indent, context)}${typeArgs}(${expr.args
+        .map((arg) => renderExpr(arg, indent, context))
+        .join(", ")})`;
+    }
+    case "binding":
+      return `${expr.name.name}: ${renderExpr(expr.type, indent, context)}`;
+    case "list":
+      return `[${expr.items.map((item) => renderExpr(item, indent, context)).join(", ")}]`;
+    case "block":
+      return renderBlock(expr, indent, context as FormatContext);
+    case "decided_amount":
+      return `decided ${renderBlock(expr.body, indent, context as FormatContext)}`;
+    case "port_ref": {
+      const within = expr.within ? ` within ${expr.within.name}` : "";
+      const deadline = expr.deadline ? ` | at(${expr.deadline.name})` : "";
+      return `port ${expr.name.name}${within}${deadline}`;
+    }
+  }
+}
+
+function renderSequence<T extends { readonly span: Span }>(
+  children: readonly T[],
+  container: Span,
+  indent: number,
+  render: (child: T) => string,
+  context: FormatContext,
+): string {
+  const rows: string[] = [];
+  let cursor = container.start;
+  for (const child of children) {
+    appendComments(rows, cursor, child.span.start, indent, context);
+    rows.push(render(child));
+    cursor = child.span.end;
+  }
+  appendComments(rows, cursor, container.end, indent, context);
+  return rows.join("\n");
+}
+
+function appendComments(
+  rows: string[],
+  start: number,
+  end: number,
+  indent: number,
+  context: FormatContext,
+): void {
+  for (const comment of context.comments) {
+    if (comment.span.start < start || comment.span.end > end) continue;
+    const trailing =
+      rows.length > 0 &&
+      !context.source.slice(start, comment.span.start).includes("\n");
+    if (trailing) {
+      const last = rows.pop() as string;
+      const newline = last.lastIndexOf("\n");
+      rows.push(
+        newline < 0
+          ? `${last} ${comment.text}`
+          : `${last.slice(0, newline + 1)}${last.slice(newline + 1)} ${comment.text}`,
+      );
+    } else {
+      rows.push(`${spaces(indent)}${comment.text}`);
+    }
+    start = comment.span.end;
+  }
+}
+
+function spaces(indent: number): string {
+  return "  ".repeat(indent);
+}

package/src/index.ts

@@ -1,11 +1,39 @@
-export { checkProgram } from "./check.ts";
-export { compile } from "./compile.ts";
+export {
+  compile,
+  type CompileDiagnostic,
+  type CompileOptions,
+  type CompileOriginMapEntry,
+  type CompileResult,
+} from "./compile.ts";
+export {
+  buildUdlCostManifest,
+  computeUdlFixedCost,
+  evaluateUdlCostManifest,
+  type HsxEffectKind,
+  type UdlCostManifest,
+  type UdlCostTable,
+} from "./cost.ts";
+export {
+  hsxDiagnostics,
+  type HsxDiagnosticCatalogEntry,
+} from "./diagnostics.ts";
+export type { HsxCompilerHost, ModuleSource } from "./modules.ts";
+export { format, type FormatResult } from "./format.ts";
+export { KEYWORDS } from "./lex.ts";
 export {
   overrideProgramEntries,
   type ProgramEntryOverride,
   type ProgramEntryOverrideIssue,
   type ProgramEntryOverrideValue,
 } from "./entry-overrides.ts";
-export { lowerProgram, MONEY_EVENT_BUDGET } from "./lower.ts";
+export { type OriginMapEntry } from "./emit.ts";
+export { lowerGeneralProgram } from "./emit.ts";
 export { parseProgram } from "./parse.ts";
-export type { Program } from "./ast.ts";
+export { checkGeneralProgram, type GeneralCheckOptions } from "./typecheck.ts";
+export type {
+  BlockExpr,
+  ExposeDecl,
+  Program,
+  ProgramDecl,
+  UseDecl,
+} from "./ast.ts";