@hyperscale0/udl 1.0.0-alpha.1

package/src/canonical.ts

@@ -0,0 +1,41 @@
+import { assertValidUdl } from "./validation.js";
+
+const INDENT = "  ";
+
+export function serializeUdl(value: unknown): string {
+  const document = assertValidUdl(value);
+  return `${writeJson(document, 0)}\n`;
+}
+
+function writeJson(value: unknown, depth: number): string {
+  if (value === null || typeof value !== "object") {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+      throw new TypeError("UDL canonical JSON received a non-JSON value");
+    }
+    return encoded;
+  }
+
+  const indent = INDENT.repeat(depth);
+  const childIndent = INDENT.repeat(depth + 1);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return `[\n${value
+      .map((item) => `${childIndent}${writeJson(item, depth + 1)}`)
+      .join(",\n")}\n${indent}]`;
+  }
+
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort(compareCodeUnits);
+  if (keys.length === 0) return "{}";
+  return `{\n${keys
+    .map(
+      (key) =>
+        `${childIndent}${JSON.stringify(key)}: ${writeJson(record[key], depth + 1)}`,
+    )
+    .join(",\n")}\n${indent}}`;
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/cli.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * The `udl` command. Three verbs over the same library the compiler uses:
+ * `validate` answers whether a document is admissible, `fmt` writes the
+ * canonical bytes, and `diff` answers whether a change is legal against a
+ * document that already has live instances.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+
+import {
+  canonicalizeUdl,
+  diffUdlEvolution,
+  parseUdl,
+  UdlError,
+  type UdlDocument,
+} from "./index.js";
+
+const USAGE = `udl - the Universal Domain Language toolchain
+
+usage:
+  udl validate <file>          parse <file> and report every issue found
+  udl fmt <file> [--write]     print the canonical form, or rewrite the file
+  udl diff <live> <next>       check <next> against the append-only law
+  udl help                     print this
+
+exit codes:
+  0  the document is admissible, or the change is additive
+  1  the document was refused, or the change breaks the append-only law
+  2  the command line was wrong, or a file could not be read`;
+
+async function main(argv: readonly string[]): Promise<number> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "help":
+    case "-h":
+    case "--help":
+      console.log(USAGE);
+      return 0;
+    case "validate":
+      return validateCommand(rest);
+    case "fmt":
+      return formatCommand(rest);
+    case "diff":
+      return diffCommand(rest);
+    case undefined:
+      return usageError("udl: no command given");
+    default:
+      return usageError(`udl: unknown command ${command}`);
+  }
+}
+
+async function validateCommand(args: readonly string[]): Promise<number> {
+  const [file, ...extra] = args;
+  if (file === undefined || extra.length > 0) {
+    return usageError("usage: udl validate <file>");
+  }
+  const bytes = await readDocument(file);
+  if (bytes === null) return 2;
+  if (parseDocument(file, bytes) === null) return 1;
+  console.log(`${file}: ok`);
+  return 0;
+}
+
+async function formatCommand(args: readonly string[]): Promise<number> {
+  const write = args.includes("--write");
+  const [file, ...extra] = args.filter((argument) => argument !== "--write");
+  if (file === undefined || extra.length > 0) {
+    return usageError("usage: udl fmt <file> [--write]");
+  }
+  const bytes = await readDocument(file);
+  if (bytes === null) return 2;
+
+  let canonical: string;
+  try {
+    canonical = canonicalizeUdl(bytes);
+  } catch (error) {
+    return reportIssues(file, error);
+  }
+
+  if (!write) {
+    process.stdout.write(canonical);
+    return 0;
+  }
+  // The bytes decoded cleanly already: canonicalizeUdl refuses anything else.
+  if (new TextDecoder().decode(bytes) === canonical) return 0;
+  await writeFile(file, canonical);
+  console.log(`${file}: formatted`);
+  return 0;
+}
+
+async function diffCommand(args: readonly string[]): Promise<number> {
+  const [livePath, nextPath, ...extra] = args;
+  if (livePath === undefined || nextPath === undefined || extra.length > 0) {
+    return usageError("usage: udl diff <live> <next>");
+  }
+  const liveBytes = await readDocument(livePath);
+  const nextBytes = await readDocument(nextPath);
+  if (liveBytes === null || nextBytes === null) return 2;
+
+  const live = parseDocument(livePath, liveBytes);
+  const next = parseDocument(nextPath, nextBytes);
+  if (live === null || next === null) return 1;
+
+  const violations = diffUdlEvolution(live, next);
+  if (violations.length === 0) {
+    console.log(`${nextPath}: additive`);
+    return 0;
+  }
+  for (const violation of violations)
+    console.error(`${nextPath}: ${violation}`);
+  return 1;
+}
+
+async function readDocument(file: string): Promise<Uint8Array | null> {
+  try {
+    return await readFile(file);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    console.error(`udl: cannot read ${file}: ${reason}`);
+    return null;
+  }
+}
+
+/** Parses one document, printing its issues. Null means the document was refused. */
+function parseDocument(file: string, bytes: Uint8Array): UdlDocument | null {
+  try {
+    return parseUdl(bytes);
+  } catch (error) {
+    reportIssues(file, error);
+    return null;
+  }
+}
+
+function reportIssues(file: string, error: unknown): number {
+  if (!(error instanceof UdlError)) throw error;
+  for (const issue of error.issues) {
+    console.error(`${file}: ${issue.code} ${issue.path}: ${issue.message}`);
+  }
+  return 1;
+}
+
+function usageError(message: string): number {
+  console.error(message);
+  console.error(USAGE);
+  return 2;
+}
+
+process.exitCode = await main(process.argv.slice(2));

package/src/duration.ts

@@ -0,0 +1,26 @@
+const fixedIsoDurationPattern =
+  /^P(?!$)(\d{1,7}W)?(\d{1,7}D)?(T(?!$)(\d{1,7}H)?(\d{1,7}M)?(\d{1,7}S)?)?$/;
+
+// Four-digit ISO date-time anchors plus this bound stay inside both the JS Date
+// range and PostgreSQL's timestamp range. The parser is the admission owner;
+// downstream runtimes never approximate or clamp an accepted duration.
+const MAX_FIXED_DURATION_MS = 8_000_000_000_000_000;
+
+/** Milliseconds in a fixed ISO-8601 duration, or null for invalid/calendar units. */
+export function fixedIsoDurationMs(duration: string): number | null {
+  const match = fixedIsoDurationPattern.exec(duration);
+  if (!match) return null;
+  const [, weeks, days, , hours, minutes, seconds] = match;
+  const integer = (part: string | undefined): number =>
+    part ? Number.parseInt(part, 10) : 0;
+  const milliseconds =
+    integer(weeks) * 604_800_000 +
+    integer(days) * 86_400_000 +
+    integer(hours) * 3_600_000 +
+    integer(minutes) * 60_000 +
+    integer(seconds) * 1_000;
+  return Number.isSafeInteger(milliseconds) &&
+    milliseconds <= MAX_FIXED_DURATION_MS
+    ? milliseconds
+    : null;
+}