@hyperscale0/hsx 2.4.1 → 3.0.0

package/examples/library.hsx

@@ -0,0 +1,59 @@
+program library "Standard library"
+use money
+use marketplace
+use escrow
+use wallet
+use financing
+use lending
+use insurance
+use approvals
+use collections
+use travel
+use cards
+use savings
+party buyer: person
+party seller: business
+party officer: staff role credit_underwriter
+party carrier: business role insurance_carrier
+party merchant: business
+
+transfer = money.transfer { payer: buyer, payee: seller, amount: 100 SAR }
+hold = money.hold { payer: buyer, payee: seller, amount: 100 SAR }
+split = money.split { payer: buyer, amount: 100 SAR, shares { seller: 70%, merchant: 30% } }
+schedule = money.schedule { payer: buyer, payee: seller, amount: 100 SAR, count: 3 }
+pool = money.pool { payer: buyer, payee: seller, target: 100 SAR, closes: 2030-01-01 }
+swap = money.swap { first: buyer, second: seller, first_amount: 100 SAR, second_amount: 50 SAR, expires: 2030-01-01 }
+deposit = money.deposit { payer: buyer, payee: seller, amount: 100 SAR, expires: 2030-01-01, approval: officer }
+payout = money.payout { payer: seller, payee: buyer, amount: 100 SAR, reconcile_within: 3d }
+metered = money.metered { payer: buyer, payee: seller, unit_price: 10 SAR, units: 2 }
+batch = money.batch { payer: buyer, payee: seller, closes: 2030-01-01, approval: officer }
+listing = marketplace.listing { seller: seller }
+order = marketplace.order { listing: listing, buyer: buyer }
+sale = escrow.hold { payer: buyer, payee: seller, for: order, fee { seller: 1% cap 750 SAR, tax: 15% }, dispute { refund_after: return_verified } }
+purse = wallet.balance { holder: buyer, spend_limit: 1000 SAR }
+spend = wallet.spend { wallet: purse, payee: seller }
+limits = financing.limits { per_borrower: 10000 SAR, portfolio: 100000 SAR, borrower: buyer }
+plan = financing.installments { months: 3, profit: 3%, funds: sale, approval: officer }
+plan_schedule = financing.installments { months: 6, profit: 3%, funds: sale, approval: officer, disburse_to: borrower, profit_earned: by_schedule, apply: principal_profit, payoff_rebate: 50% }
+plan_upfront = financing.installments { months: 3, profit: 3%, funds: sale, approval: officer, disburse_to: funds, profit_earned: at_disbursement, apply: pro_rata, payoff_rebate: 0% }
+late = financing.late_charge { on: [plan, plan_schedule, plan_upfront], approval: officer, fines_to: seller, costs_to: seller }
+line = financing.credit_line { borrower: buyer, lender: seller, limit: 1000 SAR, expires: 2030-01-01 }
+advance = financing.advance { line: line, amount: 100 SAR }
+round = lending.round { borrower: buyer, capital: seller, plan: plan }
+ticket = lending.commitment { round: round, wallet: purse }
+distribution = lending.distribution { round: round, receipt: plan.settlement, residual_to: seller }
+cover = insurance.cover { holder: buyer, insurer: carrier, covers: sale, commission: 10% }
+claim = insurance.claim { cover: cover, approved_by: carrier }
+decision = approvals.decision { for: transfer, approved_by: officer, action: "pay" }
+case = collections.case { on: plan, agency: seller, fee: 20% }
+contact = collections.contact { case: case, agency: seller }
+package = travel.package { price: 1000 SAR, supplier_cost: 700 SAR, departure: 2030-01-01 }
+booking = travel.booking { package: package, buyer: buyer, supplier: seller, cover: travel_cover }
+cardholder = cards.cardholder { holder: buyer }
+card = cards.card { holder: cardholder, spend_limit: 100 SAR }
+authorization = cards.authorization { card: card, merchant: merchant, approval: officer }
+transaction = cards.transaction { authorization: authorization }
+dispute = cards.dispute { transaction: transaction, approved_by: officer }
+circle = savings.circle { contribution: 100 SAR, members: 3, starts: 2030-01-01 }
+membership = savings.membership { circle: circle, member: buyer }
+travel_cover = insurance.cover { holder: buyer, insurer: carrier, commission: 10%, covers: booking }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "2.4.1",
+  "version": "3.0.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -40,10 +40,6 @@
       "types": "./dist/src/cost.d.ts",
       "default": "./dist/src/cost.js"
     },
-    "./lsp": {
-      "types": "./dist/src/lsp/server.d.ts",
-      "default": "./dist/src/lsp/server.js"
-    },
     "./package.json": "./package.json",
     "./std/*": "./std/*"
   },
@@ -59,7 +55,6 @@
     "dist",
     "docs",
     "examples",
-    "skills",
     "std",
     "src"
   ],
@@ -70,22 +65,19 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun run generate && tsc -p tsconfig.build.json",
-    "check": "bun run generate && bun test && bun run playground:check && tsc -p tsconfig.json && bun run build && bun scripts/check-bin.ts",
-    "docs:build": "bun scripts/docs/build.ts && bun scripts/docs/check.ts",
-    "examples:build": "bun scripts/examples/build.ts",
-    "playground:build": "bun scripts/build-playground.ts",
-    "playground:check": "bun scripts/build-playground.ts --check",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun test test",
+    "docs:build": "bun scripts/docs.ts",
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "std:bundle": "bun scripts/bundle-std.ts",
-    "test": "bun run generate && bun test",
-    "typecheck": "bun run generate && tsc -p tsconfig.json",
+    "generate": "bun run std:bundle && bun run docs:build",
     "prepare": "bun run std:bundle",
-    "generate": "bun run std:bundle && bun run docs:build && bun run playground:build"
+    "check": "bun run generate && bun run typecheck && bun run build && tsc -p playground/tsconfig.json && bun scripts/build-playground.ts && bun test test"
   },
   "dependencies": {
-    "@hyperscale0/udl": "2.6.0"
+    "@hyperscale0/udl": "3.0.0"
   },
   "devDependencies": {
     "bun-types": "1.4.2",
@@ -96,5 +88,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "0b840277c3cc73b5b4ca6d2c322d75c294524d29"
+  "gitHead": "b84ee93a5016401a5f8287745a2fb23ba5647e43"
 }

package/src/ast.ts

@@ -1,454 +1,95 @@
-/**
- * The HSX abstract syntax tree.
- *
- * Every node carries a byte-offset span into the original source. Spans are
- * the compiler's source-mapping currency: diagnostics at every later stage
- * (typecheck, lowering, verdicts) point at source coordinates, never at
- * lowered IR paths. Offsets convert to line/column via `lineColAt`.
- */
-
 export interface Span {
-  /** Inclusive start byte offset into the source text. */
-  readonly start: number;
-  /** Exclusive end byte offset into the source text. */
-  readonly end: number;
+  start: number;
+  end: number;
 }
-
-export interface LineCol {
-  /** 1-indexed line. */
-  readonly line: number;
-  /** 1-indexed column, counted in UTF-16 code units. */
-  readonly column: number;
-}
-
-/** Convert a byte offset to a 1-indexed line/column position. */
-export function lineColAt(source: string, offset: number): LineCol {
-  let line = 1;
-  let lineStart = 0;
-  const clamped = Math.max(0, Math.min(offset, source.length));
-  for (let index = 0; index < clamped; index += 1) {
-    if (source.charCodeAt(index) === 10) {
-      line += 1;
-      lineStart = index + 1;
-    }
-  }
-  return { column: clamped - lineStart + 1, line };
+export interface Diagnostic {
+  code: string;
+  message: string;
+  fix: string;
+  span: Span;
 }
-
-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;
+export type Expr =
+  | {
+      kind:
+        | "name"
+        | "text"
+        | "number"
+        | "money"
+        | "percent"
+        | "duration"
+        | "date";
+      value: string;
+      span: Span;
     }
-    currentByte += charBytes;
-    codeUnit += char.length;
-    if (currentByte === byteOffset) {
-      return codeUnit;
+  | { kind: "list"; items: Expr[]; span: Span }
+  | { kind: "block"; entries: Entry[]; span: Span }
+  | { kind: "call"; name: string; args: Expr[]; span: Span }
+  | {
+      kind: "type";
+      name: string;
+      target?: string;
+      owner?: string;
+      optional: boolean;
+      many?: boolean;
+      span: Span;
     }
-  }
-
-  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
- * diagnostics over an n-byte source into O(n*d) work. A caller holding this
- * pays O(n) once and O(log n) per offset.
- */
-export interface LineIndex {
-  /** Source length, so `lineColIn` clamps exactly as `lineColAt` does. */
-  readonly length: number;
-  /** Offset of the first character of each line, ascending. Line 1 starts at 0. */
-  readonly starts: readonly number[];
-}
-
-/** Scan a source once for the offset every line starts at. */
-export function lineIndex(source: string): LineIndex {
-  const starts = [0];
-  for (let index = 0; index < source.length; index += 1) {
-    if (source.charCodeAt(index) === 10) starts.push(index + 1);
-  }
-  return { length: source.length, starts };
-}
-
-/**
- * Resolve one offset against a prebuilt index. Returns exactly what
- * `lineColAt` returns for the same source and offset.
- */
-export function lineColIn(index: LineIndex, offset: number): LineCol {
-  const clamped = Math.max(0, Math.min(offset, index.length));
-  let low = 0;
-  let high = index.starts.length - 1;
-  while (low < high) {
-    const middle = Math.floor((low + high + 1) / 2);
-    if ((index.starts[middle] as number) <= clamped) low = middle;
-    else high = middle - 1;
-  }
-  return { column: clamped - (index.starts[low] as number) + 1, line: low + 1 };
-}
-
-// --- Expressions -----------------------------------------------------------
-
-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;
-}
-
-export interface StringExpr {
-  readonly kind: "string";
-  readonly span: Span;
-  readonly value: string;
-}
-
-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;
-  readonly kind: "percent";
-  readonly raw: string;
-  readonly span: Span;
-}
-
-/** A type or constructor application: `money(SAR)`, `id(vehicle)`. */
-export interface CallExpr {
-  readonly args: readonly Expr[];
-  readonly callee: IdentExpr;
-  readonly kind: "call";
-  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
- * (`port approve_release | at(releaseDueAt)`).
- */
-export interface PortRefExpr {
-  /** `| at(<field>)`, the stored date field that resolves an undecided hold. */
-  readonly deadline?: IdentExpr;
-  readonly kind: "port_ref";
-  readonly name: IdentExpr;
-  readonly span: Span;
-  readonly within?: IdentExpr;
-}
-
-/**
- * `retention.release`, one settlement naming another settlement's declared
- * referenceable exit. The checker resolves it wholly before lowering.
- */
-export interface SettlementRefExpr {
-  readonly kind: "settlement_ref";
-  /** The exit named on the owner, e.g. `release`. */
-  readonly member: IdentExpr;
-  /** The settlement being referenced. */
-  readonly owner: IdentExpr;
-  readonly span: Span;
-}
-
-export interface ListExpr {
-  readonly items: readonly Expr[];
-  readonly kind: "list";
-  readonly span: Span;
-}
-
-/** A brace block of entries: `{ buyer: 1%, seller: 2% }`. */
-export interface BlockExpr {
-  readonly entries: readonly Entry[];
-  readonly kind: "block";
-  readonly span: Span;
-}
-
-/**
- * A named typed binding inside an expression position:
- * `amount: price: money(SAR)` binds the field name `price` to type
- * `money(SAR)`: the entry key is `amount`, the value is this binding.
- */
-export interface BindingExpr {
-  readonly kind: "binding";
-  readonly name: IdentExpr;
-  readonly span: Span;
-  readonly type: Expr;
-}
-
-export type Expr =
-  | ApplyExpr
-  | BindingExpr
-  | BlockExpr
-  | BooleanExpr
-  | CallExpr
-  | DecidedAmountExpr
-  | IdentExpr
-  | ListExpr
-  | MoneyExpr
-  | NumberExpr
-  | PathExpr
-  | PercentExpr
-  | PortRefExpr
-  | SettlementRefExpr
-  | StringExpr
-  | TypeApplyExpr;
-
-// --- Entries ---------------------------------------------------------------
-
-/**
- * One keyed entry inside a declaration body. Three surface shapes normalize
- * here: `payer: buyer` (key + value), `fees { ... }` (key + block value),
- * and `on_cancel(funded) { ... }` (key + qualifiers + block value).
- */
+  | { kind: "default"; type: Expr; value: Expr; span: Span }
+  | { kind: "capped"; rate: Expr; cap: Expr; span: Span };
 export interface Entry {
-  /** Port dependencies retained through compile-time selection and substitution. */
-  readonly conditionPorts?: readonly string[];
-  /** `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;
-  readonly value: Expr;
-}
-
-// --- Declarations ----------------------------------------------------------
-
-/** `program used_car_escrow "Used-car escrow"` names the company program. */
-export interface ProgramDecl {
-  readonly kind: "program";
-  readonly name: IdentExpr;
-  readonly span: Span;
-  readonly title?: StringExpr;
-}
-
-/** `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/money_flows"`. */
-export interface ImportDecl {
-  readonly from: StringExpr;
-  readonly kind: "import";
-  readonly names: readonly IdentExpr[];
-  readonly span: Span;
-}
-
-/** `party buyer: person` with an optional attribute block. */
-export interface PartyDecl {
-  readonly attrs?: BlockExpr;
-  readonly kind: "party";
-  readonly name: IdentExpr;
-  readonly partyKind: IdentExpr;
-  readonly span: Span;
-}
-
-/** `asset vehicle: good { title_transfer: off_platform }`. */
-export interface AssetDecl {
-  readonly assetKind: IdentExpr;
-  readonly attrs?: BlockExpr;
-  readonly kind: "asset";
-  readonly name: IdentExpr;
-  readonly span: Span;
-}
-
-/** A full UDL subject-kind declaration. `asset` remains shorthand for this form. */
-export interface SubjectDecl {
-  readonly body: BlockExpr;
-  readonly kind: "subject";
-  readonly name: IdentExpr;
-  readonly span: Span;
-}
-
-/** `port confirm_handover { allowed: [buyer], ... }`. */
-export interface PortDecl {
-  readonly body: BlockExpr;
-  readonly kind: "port";
-  readonly name: IdentExpr;
-  readonly span: Span;
+  key: string;
+  value: Expr;
+  span: Span;
 }
-
-/** `module std.money_flows` 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;
+  kind: "instrument";
+  name: string;
+  parameters: Entry[];
+  body: Extract<Expr, { kind: "block" }>;
+  span: Span;
+}
+export interface ObjectDecl {
+  kind: "object";
+  name: string;
+  object: string;
+  body: Extract<Expr, { kind: "block" }>;
+  span: Span;
 }
-
-export type ApplicationScopeDecl =
-  | ConstDecl
-  | InstrumentDecl
-  | PartyDecl
-  | PortDecl
-  | TypeDecl;
-
 export type Decl =
-  | AssetDecl
-  | ConstDecl
-  | ExposeDecl
-  | ImportDecl
-  | InstrumentApplyDecl
   | InstrumentDecl
-  | ModuleDecl
-  | PartyDecl
-  | PortDecl
-  | ProgramDecl
-  | SubjectDecl
-  | TypeDecl
-  | UseDecl;
-
-// --- Program ---------------------------------------------------------------
-
+  | ObjectDecl
+  | {
+      kind: "party";
+      name: string;
+      partyKind: string;
+      role?: string;
+      span: Span;
+    }
+  | { kind: "use"; name: string; span: Span }
+  | { kind: "expose"; target: string; name: string; span: Span }
+  | { kind: "hide"; target: string; span: Span };
 export interface Program {
-  readonly decls: readonly Decl[];
-  readonly span: Span;
-}
-
-// --- Diagnostics -----------------------------------------------------------
-
-/**
- * A parse-stage problem, worded for the program's author. Parsing is total:
- * 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;
+  name: string;
+  title: string;
+  currency: string;
+  header: boolean;
+  decls: Decl[];
+  span: Span;
+}
+export const lineColAt = (source: string, offset: number) => {
+  const before = source.slice(0, offset);
+  return {
+    line: before.split("\n").length,
+    column: offset - before.lastIndexOf("\n"),
+  };
+};
+export function byteOffsetToCodeUnit(source: string, offset: number): number {
+  let bytes = 0;
+  let units = 0;
+  for (const c of source) {
+    bytes += new TextEncoder().encode(c).length;
+    if (bytes > offset) break;
+    units += c.length;
+  }
+  return units;
 }
+export type BlockExpr = Extract<Expr, { kind: "block" }>;