@hyperscale0/hsx 1.0.0-alpha.1

package/src/cli.ts

@@ -0,0 +1,173 @@
+/**
+ * The `hsx` command line: two subcommands over the one compiler entry point.
+ *
+ * `check` prints diagnostics and says nothing else; `build` writes the
+ * compiled artifacts as JSON. Neither reads the environment, neither touches
+ * a network, and neither writes outside the path the caller names.
+ *
+ * Everything here is a pure function of `argv` plus the injected `Io`, so the
+ * spec drives the real code paths with an in-memory filesystem instead of
+ * asserting on a subprocess's scrollback.
+ */
+
+import { compile, type CompileResult } from "./compile.ts";
+import { HSX_IR_VERSION, HSX_VERSION } from "./version.ts";
+
+/** Filesystem and streams, injected so the CLI stays testable. */
+export interface Io {
+  readonly err: (line: string) => void;
+  readonly out: (line: string) => void;
+  readonly readFile: (path: string) => Promise<string>;
+  readonly writeFile: (path: string, contents: string) => Promise<void>;
+}
+
+/**
+ * Exit codes. `warning` exits 0 because a lint note is not a failure; pass
+ * `--strict` to make it one.
+ */
+const OK = 0;
+const REFUSED = 1;
+const USAGE = 2;
+
+const USAGE_TEXT = `hsx ${HSX_VERSION}, the HSX compiler
+
+Usage:
+  hsx check <file.hsx> [--strict]
+  hsx build <file.hsx> [--out <file.json>] [--strict]
+  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.
+
+Options:
+  --out <file>  Write build output to this path instead of stdout.
+  --strict      Treat warning-severity diagnostics as failures.
+
+Exit codes:
+  0  the program compiled (verdict valid, or warning without --strict)
+  1  the program was refused (verdict invalid, or warning with --strict)
+  2  the command line or the input file could not be used`;
+
+export async function runCli(argv: readonly string[], io: Io): Promise<number> {
+  const [command, ...rest] = argv;
+
+  if (command === undefined || command === "--help" || command === "-h") {
+    io.out(USAGE_TEXT);
+    return command === undefined ? USAGE : OK;
+  }
+  if (command === "--version" || command === "-v") {
+    io.out(`${HSX_VERSION} (IR version ${HSX_IR_VERSION})`);
+    return OK;
+  }
+  if (command !== "check" && command !== "build") {
+    io.err(`hsx: unknown command "${command}"`);
+    io.err(USAGE_TEXT);
+    return USAGE;
+  }
+
+  const parsed = parseOptions(rest, command);
+  if ("error" in parsed) {
+    io.err(`hsx: ${parsed.error}`);
+    return USAGE;
+  }
+
+  let source: string;
+  try {
+    source = await io.readFile(parsed.file);
+  } catch (cause) {
+    io.err(`hsx: cannot read ${parsed.file}: ${messageOf(cause)}`);
+    return USAGE;
+  }
+
+  const result = compile(source);
+  for (const line of diagnosticLines(parsed.file, result)) io.err(line);
+
+  const refused =
+    result.verdict === "invalid" ||
+    (parsed.strict && result.verdict === "warning");
+
+  if (command === "check") {
+    return refused ? REFUSED : OK;
+  }
+
+  if (!result.artifacts) return REFUSED;
+  const json = `${JSON.stringify(
+    {
+      document: result.artifacts.document,
+      frame: result.artifacts.frame,
+    },
+    null,
+    2,
+  )}\n`;
+  if (parsed.out === undefined) {
+    io.out(json.trimEnd());
+  } else {
+    try {
+      await io.writeFile(parsed.out, json);
+    } catch (cause) {
+      io.err(`hsx: cannot write ${parsed.out}: ${messageOf(cause)}`);
+      return USAGE;
+    }
+  }
+  return refused ? REFUSED : OK;
+}
+
+interface Options {
+  readonly file: string;
+  readonly out?: string;
+  readonly strict: boolean;
+}
+
+function parseOptions(
+  args: readonly string[],
+  command: "build" | "check",
+): Options | { readonly error: string } {
+  let file: string | undefined;
+  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") {
+      strict = true;
+      continue;
+    }
+    if (argument === "--out") {
+      if (command !== "build") return { error: "--out belongs to hsx build" };
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        return { error: "--out needs a file path" };
+      }
+      out = value;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("-")) {
+      return { error: `unknown option "${argument}"` };
+    }
+    if (file !== undefined) {
+      return { error: `hsx ${command} takes one file, got "${argument}" too` };
+    }
+    file = argument;
+  }
+
+  if (file === undefined) return { error: `hsx ${command} needs a file` };
+  return { file, ...(out === undefined ? {} : { out }), strict };
+}
+
+/** `file:line:col: severity [stage] message`, the shape editors already parse. */
+function diagnosticLines(
+  file: string,
+  result: CompileResult,
+): readonly string[] {
+  return result.diagnostics.map(
+    (diagnostic) =>
+      `${file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.severity} [${diagnostic.stage}] ${diagnostic.message}`,
+  );
+}
+
+function messageOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}

package/src/compile.ts

@@ -0,0 +1,98 @@
+/**
+ * The HSX compiler driver: source text in, three-verdict result out.
+ *
+ * - `valid`: the program lowers cleanly; the IR document and frame are ready
+ *   for the independent checker.
+ * - `warning`: the program lowers, and the compiler's lint voice has notes
+ *   the author should read (the artifacts are still present and usable).
+ * - `invalid`: the program cannot be lowered; diagnostics say why, in the
+ *   author's language, each anchored to a source line and column.
+ *
+ * Every diagnostic points at SOURCE coordinates, never at lowered IR paths.
+ */
+
+import { lineColAt } from "./ast.ts";
+import { checkProgram } from "./check.ts";
+import { lowerProgram } from "./lower.ts";
+import { parseProgram } from "./parse.ts";
+
+type Json = Record<string, unknown>;
+
+type CompileVerdict = "invalid" | "valid" | "warning";
+
+interface CompileDiagnostic {
+  /** 1-indexed source column. */
+  readonly column: number;
+  /** 1-indexed source line. */
+  readonly line: number;
+  readonly message: string;
+  readonly severity: "error" | "warning";
+  /** The stage that raised it: parse, check, or lower. */
+  readonly stage: "check" | "lower" | "parse";
+}
+
+interface CompileArtifacts {
+  /** The lowered HSX-JSON IR document, for the independent checker. */
+  readonly document: Json;
+  /** The congruent Business Frame. */
+  readonly frame: Json;
+}
+
+export interface CompileResult {
+  /** Present exactly when the verdict is not `invalid`. */
+  readonly artifacts?: CompileArtifacts;
+  readonly diagnostics: readonly CompileDiagnostic[];
+  readonly verdict: CompileVerdict;
+}
+
+export function compile(source: string): CompileResult {
+  const diagnostics: CompileDiagnostic[] = [];
+  const at = (
+    stage: CompileDiagnostic["stage"],
+    severity: CompileDiagnostic["severity"],
+    message: string,
+    offset: number,
+  ): void => {
+    const position = lineColAt(source, offset);
+    diagnostics.push({
+      column: position.column,
+      line: position.line,
+      message,
+      severity,
+      stage,
+    });
+  };
+
+  const parsed = parseProgram(source);
+  for (const diagnostic of parsed.diagnostics) {
+    at("parse", "error", diagnostic.message, diagnostic.span.start);
+  }
+  if (parsed.diagnostics.length > 0) {
+    return { diagnostics, verdict: "invalid" };
+  }
+
+  const checked = checkProgram(parsed.program);
+  for (const diagnostic of checked.diagnostics) {
+    at("check", diagnostic.severity, diagnostic.message, diagnostic.span.start);
+  }
+  if (!checked.program) {
+    return { diagnostics, verdict: "invalid" };
+  }
+
+  const loweredResult = lowerProgram(checked.program);
+  if (!loweredResult.ok) {
+    for (const issue of loweredResult.issues) {
+      at("lower", "error", issue.message, issue.span.start);
+    }
+    return { diagnostics, verdict: "invalid" };
+  }
+
+  return {
+    artifacts: {
+      document: loweredResult.value.document,
+      frame: loweredResult.value.frame,
+    },
+    diagnostics,
+    verdict: diagnostics.length > 0 ? "warning" : "valid",
+  };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export type {
+  BlockExpr,
+  CallExpr,
+  ListExpr,
+  PercentExpr,
+  PortDecl,
+  PortRefExpr,
+  SettlementDecl,
+} from "./ast.ts";
+export { lineColAt } from "./ast.ts";
+export { checkProgram } from "./check.ts";
+export { compile } from "./compile.ts";
+export type { CompileResult } from "./compile.ts";
+export { lowerProgram, MONEY_EVENT_BUDGET } from "./lower.ts";
+export { parseProgram } from "./parse.ts";
+export { HSX_IR_VERSION, HSX_VERSION } from "./version.ts";

package/src/lex.ts

@@ -0,0 +1,161 @@
+/**
+ * The HSX lexer. Hand-written, total: every input produces a token stream
+ * ending in `eof`, with malformed stretches reported as diagnostics and
+ * skipped. Tokens carry byte-offset spans; whitespace and `//` comments are
+ * insignificant everywhere.
+ */
+
+import type { Diagnostic, Span } from "./ast.ts";
+
+type TokenKind =
+  | "eof"
+  | "ident"
+  | "keyword"
+  | "number"
+  | "percent"
+  | "punct"
+  | "string";
+
+const KEYWORDS = [
+  "asset",
+  "from",
+  "import",
+  "party",
+  "port",
+  "program",
+  "settlement",
+] as const;
+
+export interface Token {
+  readonly kind: TokenKind;
+  readonly span: Span;
+  /** Identifier name, keyword, punctuation glyph, or raw literal text. */
+  readonly text: string;
+  /** Decoded value for string literals; raw digits for numbers/percents. */
+  readonly value: string;
+}
+
+const PUNCT = new Set(["{", "}", "(", ")", "[", "]", ":", ",", "=", "|", "."]);
+const KEYWORD_SET: ReadonlySet<string> = new Set(KEYWORDS);
+
+// Case conventions (snake_case declarations, uppercase currency codes) are
+// semantic rules the typechecker words per position; the lexer stays permissive.
+const isIdentStart = (ch: string): boolean => /[A-Za-z]/.test(ch);
+const isIdentPart = (ch: string): boolean => /[A-Za-z0-9_]/.test(ch);
+const isDigit = (ch: string): boolean => ch >= "0" && ch <= "9";
+
+export interface LexResult {
+  readonly diagnostics: readonly Diagnostic[];
+  readonly tokens: readonly Token[];
+}
+
+export function lex(source: string): LexResult {
+  const tokens: Token[] = [];
+  const diagnostics: Diagnostic[] = [];
+  let index = 0;
+
+  const push = (kind: TokenKind, start: number, text: string, value = text) => {
+    tokens.push({ kind, span: { end: index, start }, text, value });
+  };
+
+  while (index < source.length) {
+    const ch = source[index] as string;
+
+    if (ch === " " || ch === "\t" || ch === "\r" || ch === "\n") {
+      index += 1;
+      continue;
+    }
+
+    if (ch === "/" && source[index + 1] === "/") {
+      while (index < source.length && source[index] !== "\n") index += 1;
+      continue;
+    }
+
+    if (PUNCT.has(ch)) {
+      const start = index;
+      index += 1;
+      push("punct", start, ch);
+      continue;
+    }
+
+    if (ch === '"') {
+      const start = index;
+      index += 1;
+      let value = "";
+      let closed = false;
+      while (index < source.length) {
+        const next = source[index] as string;
+        if (next === '"') {
+          index += 1;
+          closed = true;
+          break;
+        }
+        if (next === "\n") break;
+        value += next;
+        index += 1;
+      }
+      if (!closed) {
+        diagnostics.push({
+          message: "this string never closes; add the ending double quote",
+          span: { end: index, start },
+        });
+      }
+      push("string", start, source.slice(start, index), value);
+      continue;
+    }
+
+    if (isDigit(ch)) {
+      const start = index;
+      while (index < source.length && isDigit(source[index] as string)) {
+        index += 1;
+      }
+      if (source[index] === "." && isDigit(source[index + 1] ?? "")) {
+        index += 1;
+        while (index < source.length && isDigit(source[index] as string)) {
+          index += 1;
+        }
+      }
+      const raw = source.slice(start, index);
+      if (source[index] === "%") {
+        index += 1;
+        push("percent", start, source.slice(start, index), raw);
+      } else {
+        push("number", start, raw, raw);
+      }
+      continue;
+    }
+
+    if (isIdentStart(ch)) {
+      const start = index;
+      while (index < source.length && isIdentPart(source[index] as string)) {
+        index += 1;
+      }
+      const text = source.slice(start, index);
+      push(KEYWORD_SET.has(text) ? "keyword" : "ident", start, text);
+      continue;
+    }
+
+    const start = index;
+    while (
+      index < source.length &&
+      !/[\sA-Za-z0-9_"]/.test(source[index] as string) &&
+      !PUNCT.has(source[index] as string) &&
+      !(source[index] === "/" && source[index + 1] === "/")
+    ) {
+      index += 1;
+    }
+    if (index === start) index += 1;
+    diagnostics.push({
+      message: `"${source.slice(start, index)}" is not part of the HSX language`,
+      span: { end: index, start },
+    });
+  }
+
+  tokens.push({
+    kind: "eof",
+    span: { end: source.length, start: source.length },
+    text: "",
+    value: "",
+  });
+  return { diagnostics, tokens };
+}