@hyperscale0/hsx 1.0.0 → 1.0.124

package/src/format.ts

@@ -1,261 +1,17 @@
-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 {
+/** Preserve authored comments and literals; normalize line endings and trailing whitespace. */
+export function format(source: string) {
   const parsed = parseProgram(source);
-  if (parsed.diagnostics.length > 0) {
-    return { diagnostics: parsed.diagnostics, ok: false };
-  }
-
-  const context: FormatContext = { comments: lex(source).comments, source };
+  if (parsed.diagnostics.length)
+    return { ok: false as const, diagnostics: parsed.diagnostics };
   return {
-    formatted: `${renderSequence(
-      parsed.program.decls,
-      parsed.program.span,
-      0,
-      (decl) => renderDecl(decl, context),
-      context,
-    )}\n`,
-    ok: true,
+    ok: true as const,
+    formatted:
+      source
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .trimEnd() + "\n",
   };
 }
-
-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/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

@@ -0,0 +1,195 @@
+import {
+  bindingDependencies,
+  parameterDiagnostics,
+} from "./binding-contract.ts";
+import { tunableBounds } from "./tunables.ts";
+import { parseHeader } from "./header-source.ts";
+import { bundledStandardLibrary, type StandardLibrary } from "./std-library.ts";
+import type { BlockExpr, Expr } from "./ast.ts";
+
+export const HEADER_NAMES = [
+  "money",
+  "marketplace",
+  "escrow",
+  "wallet",
+  "financing",
+  "lending",
+  "insurance",
+  "collections",
+  "cards",
+  "savings",
+  "reporting",
+] as const;
+
+/** The compiler frontend owns header metadata used by docs and catalogue consumers. */
+export function headerManifest(
+  library: StandardLibrary = bundledStandardLibrary,
+  names: readonly string[] = HEADER_NAMES,
+) {
+  return {
+    version: 1,
+    headers: names.map((name) => {
+      const source = library.source(name);
+      if (!source) throw new Error(`Missing standard header ${name}`);
+      const parsed = parseHeader(source, name);
+      const spelling = (expression: Expr) =>
+        source.slice(expression.span.start, expression.span.end).trim();
+      const actions = (
+        body: BlockExpr,
+        prefix = "",
+      ): Array<{ name: string; summary: string; actor: string }> => {
+        const result = body.entries
+          .filter((e) => e.key.startsWith("action "))
+          .map((entry) => {
+            const slots =
+              entry.value.kind === "block" ? entry.value.entries : [];
+            const summary = slots.find((e) => e.key === "summary")?.value;
+            const actor = slots.find((e) => e.key === "actor")?.value;
+            return {
+              name: prefix + entry.key.slice(7),
+              summary:
+                summary?.kind === "text"
+                  ? summary.value
+                  : entry.key.slice(7).replaceAll("_", " "),
+              actor: actor ? spelling(actor) : "caller",
+            };
+          });
+        const records = body.entries.find((e) => e.key === "records")?.value;
+        if (records?.kind === "block")
+          for (const record of records.entries)
+            if (record.value.kind === "block")
+              result.push(...actions(record.value, `${prefix}${record.key}.`));
+        return result;
+      };
+      return {
+        name,
+        objects: parsed.decls
+          .filter((d) => d.kind === "instrument")
+          .map((decl) => {
+            const tunables = decl.parameters.map((parameter) => {
+              const type =
+                parameter.value.kind === "default"
+                  ? parameter.value.type
+                  : parameter.value;
+              const fallback =
+                parameter.value.kind === "default"
+                  ? parameter.value.value
+                  : undefined;
+              return {
+                name: parameter.key,
+                type: spelling(type),
+                ...(type.kind === "call" && type.name === "enum"
+                  ? { values: type.args.map(spelling) }
+                  : {}),
+                ...tunableBounds(type),
+                required: !fallback && !(type.kind === "type" && type.optional),
+                ...(fallback ? { default: spelling(fallback) } : {}),
+              };
+            });
+            // Reference selectors need program context, and text can name a target
+            // action. Templates require explicit bindings instead of guessing them.
+            const bindings = tunables.filter((tunable, index) => {
+              const value = decl.parameters[index]!.value;
+              return (
+                tunable.required ||
+                tunable.type === "text" ||
+                (value.kind === "default" &&
+                  value.value.kind === "call" &&
+                  ["object", "party"].includes(value.value.name))
+              );
+            });
+            const summary = decl.body.entries.find(
+              (e) => e.key === "summary",
+            )?.value;
+            return {
+              name: decl.name,
+              qualifiedName: `${name}.${decl.name}`,
+              signature: source
+                .slice(decl.span.start, decl.body.span.start)
+                .replace(/^instrument\s+/, "")
+                .trim(),
+              states: (() => {
+                const lifecycle = decl.body.entries.find(
+                  (entry) => entry.key === "lifecycle",
+                )?.value;
+                const states =
+                  lifecycle?.kind === "block"
+                    ? lifecycle.entries.find((entry) => entry.key === "states")
+                        ?.value
+                    : undefined;
+                return states?.kind === "list"
+                  ? states.items.map(spelling)
+                  : [];
+              })(),
+              summary:
+                summary?.kind === "text"
+                  ? summary.value
+                  : decl.name.replaceAll("_", " "),
+              authoringTemplate: {
+                requiredImport: `use ${name}`,
+                instancePlaceholder: "${instance}",
+                source:
+                  "attach ${instance} = " +
+                  `${name}.${decl.name} { ` +
+                  bindings
+                    .map((t) => t.name + ": ${" + t.name + "}")
+                    .join(", ") +
+                  " }",
+                requiredBindings: bindings.map((t) => ({
+                  name: t.name,
+                  type: t.type,
+                  placeholder: "${" + t.name + "}",
+                })),
+              },
+              tunables,
+              dependencies: bindingDependencies(decl).map(
+                ({ span: _span, ...dependency }) => dependency,
+              ),
+              parameterDiagnostics: parameterDiagnostics(decl),
+              constraints: (() => {
+                const block = decl.body.entries.find(
+                  (entry) => entry.key === "constraints",
+                )?.value;
+                return block?.kind === "block"
+                  ? block.entries.map((entry) => {
+                      if (
+                        entry.value.kind !== "call" ||
+                        entry.value.args.length !== 1
+                      )
+                        throw new Error("invalid tunable constraint");
+                      return {
+                        tunable: entry.key,
+                        relation: entry.value.name,
+                        other: spelling(entry.value.args[0]!),
+                      };
+                    })
+                  : [];
+              })(),
+              parties: tunables
+                .filter((t) => t.type === "party")
+                .map((t) => t.name),
+              // Fields the attached object must carry (or rename to) before
+              // the instrument's actions can read them.
+              subject: (() => {
+                const fields = new Map<string, string>();
+                for (const entry of decl.body.entries) {
+                  if (!entry.key.startsWith("action ")) continue;
+                  if (entry.value.kind !== "block") continue;
+                  const subject = entry.value.entries.find(
+                    (slot) => slot.key === "subject",
+                  )?.value;
+                  if (subject?.kind !== "block") continue;
+                  for (const field of subject.entries) {
+                    const type = spelling(field.value);
+                    if (field.key !== "adapter") fields.set(field.key, type);
+                  }
+                }
+                return [...fields].map(([name, type]) => ({ name, type }));
+              })(),
+              actions: actions(decl.body),
+            };
+          }),
+      };
+    }),
+  };
+}

package/src/index.ts

@@ -2,40 +2,25 @@ export {
   compile,
   type CompileDiagnostic,
   type CompileOptions,
-  type CompileOriginMapEntry,
   type CompileResult,
+  type CompileOriginMapEntry,
+  type AdapterBindingTarget,
 } 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 { type OriginMapEntry } from "./emit.ts";
-export { lowerGeneralProgram } from "./emit.ts";
+export type { ProviderAdapter } from "@hyperscale0/adl";
 export { parseProgram } from "./parse.ts";
-export { checkGeneralProgram, type GeneralCheckOptions } from "./typecheck.ts";
-export {
-  byteOffsetToCodeUnit,
-  type BlockExpr,
-  type ExposeDecl,
-  type Program,
-  type ProgramDecl,
-  type UseDecl,
-} from "./ast.ts";
+export { lex, KEYWORDS } from "./lex.ts";
+export { format } from "./format.ts";
 export { bundledStandardLibrary, type StandardLibrary } from "./std-library.ts";
+export { buildUdlCostManifest, type UdlCostManifest } from "./cost.ts";
+export type {
+  Program,
+  Decl,
+  AssignmentDecl,
+  ObjectDecl,
+  InstrumentDecl,
+  Expr,
+  Span,
+  Diagnostic,
+} from "./ast.ts";
+
+export { headerManifest, HEADER_NAMES } from "./headers.ts";