@venn-lang/contracts 0.1.0

package/src/port/missing-capabilities.ts

@@ -0,0 +1,14 @@
+import type { HostCapability } from "../capabilities/index.js";
+
+/**
+ * The gap between what is required and what the host offers.
+ *
+ * @returns the required capabilities absent from `caps`, in the order required.
+ */
+export function missingCapabilities(args: {
+  requires: readonly HostCapability[];
+  caps: readonly HostCapability[];
+}): readonly HostCapability[] {
+  const present = new Set(args.caps);
+  return args.requires.filter((cap) => !present.has(cap));
+}

package/src/port/port.types.ts

@@ -0,0 +1,36 @@
+import type { HostCapability } from "../capabilities/index.js";
+
+/**
+ * A typed contract carrying at least two implementations, one real and one
+ * double.
+ *
+ * Deliberately not a Zod schema: in Zod 4 `z.function` is a factory rather than
+ * a validatable type, so a port's function shape cannot be expressed as data.
+ * `methods` buys a compile-time check (each entry must be a key of `T`) and a
+ * load-time one (`typeof` per method); the behavioural guarantee is the
+ * conformance suite.
+ *
+ * @typeParam T - the interface the implementation must satisfy.
+ */
+export interface Port<T> {
+  /** Stable identity, e.g. "venn.port.filesystem". */
+  readonly id: string;
+  /** Version of the contract, not of the package. Removing a method bumps it. */
+  readonly version: number;
+  /** Capabilities negotiated against `Host.caps` before binding. */
+  readonly requires: readonly HostCapability[];
+  /** Methods an implementation must provide. Each must be a key of `T`. */
+  readonly methods: readonly (keyof T & string)[];
+}
+
+/**
+ * A `Port<T>` with its element type erased. Every `Port<T>` is assignable to it
+ * (its `methods` widen to `string[]`), so a heterogeneous collection of ports,
+ * such as the runtime's binding table, types without variance friction.
+ */
+export type AnyPort = {
+  readonly id: string;
+  readonly version: number;
+  readonly requires: readonly HostCapability[];
+  readonly methods: readonly string[];
+};

package/src/ports/clock/clock.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "../../port/index.js";
+import type { Clock } from "./clock.types.js";
+
+/**
+ * The {@link Clock} contract. Implementations: `system-clock`, `virtual-clock`.
+ *
+ * `advance` and `setTime` are absent on purpose: they are how a test drives a
+ * virtual clock, not something a caller of the port may reach for.
+ */
+export const ClockPort: Port<Clock> = {
+  id: "venn.port.clock",
+  version: 1,
+  requires: ["clock"],
+  methods: ["now", "sleep"],
+};

package/src/ports/clock/clock.types.ts

@@ -0,0 +1,17 @@
+/** Now, sleeping, deadlines. */
+export interface Clock {
+  /** Milliseconds since the epoch, or since the virtual clock's start. */
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+
+/**
+ * A {@link Clock} whose flow of time a test controls.
+ *
+ * `advance` and `setTime` sit outside the negotiated contract, so code holding
+ * a `Clock` can never reach them.
+ */
+export interface VirtualClock extends Clock {
+  advance(ms: number): void;
+  setTime(epochMs: number): void;
+}

package/src/ports/clock/index.ts

@@ -0,0 +1,4 @@
+export { ClockPort } from "./clock.port.js";
+export type { Clock, VirtualClock } from "./clock.types.js";
+export { createSystemClock } from "./system-clock.js";
+export { createVirtualClock } from "./virtual-clock.js";

package/src/ports/clock/system-clock.ts

@@ -0,0 +1,9 @@
+import type { Clock } from "./clock.types.js";
+
+/** Wall-clock time, on the `Date` and `setTimeout` globals. */
+export function createSystemClock(): Clock {
+  return {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  };
+}

package/src/ports/clock/virtual-clock.ts

@@ -0,0 +1,22 @@
+import type { VirtualClock } from "./clock.types.js";
+
+/**
+ * The double. `sleep` advances internal time and resolves at once, so a test
+ * about a timeout costs nothing to run.
+ *
+ * @param args.start - the epoch this clock begins at. Defaults to 0.
+ */
+export function createVirtualClock(args: { start?: number } = {}): VirtualClock {
+  let time = args.start ?? 0;
+  const advance = (ms: number): void => {
+    time += Math.max(0, ms);
+  };
+  return {
+    now: () => time,
+    sleep: async (ms) => advance(ms),
+    advance,
+    setTime: (epochMs) => {
+      time = epochMs;
+    },
+  };
+}

package/src/ports/console/console.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "../../port/index.js";
+import type { Console } from "./console.types.js";
+
+/**
+ * The {@link Console} contract. Implementations: `node-console`,
+ * `memory-console`.
+ */
+export const ConsolePort: Port<Console> = {
+  id: "venn.port.console",
+  version: 1,
+  requires: ["io"],
+  methods: ["write", "writeError", "readLine", "args"],
+};

package/src/ports/console/console.types.ts

@@ -0,0 +1,17 @@
+/**
+ * The program's console: standard streams and process arguments.
+ *
+ * Everything a script needs to talk to the outside world without knowing
+ * whether it runs on Node, in a test, or in a browser worker. The host supplies
+ * the wiring.
+ */
+export interface Console {
+  /** Write to standard output, exactly as given (no trailing newline). */
+  write(text: string): void;
+  /** Write to standard error. */
+  writeError(text: string): void;
+  /** Read the next line from standard input, or null at end of input. */
+  readLine(): Promise<string | null>;
+  /** The command-line arguments passed after the script path. */
+  args(): readonly string[];
+}

package/src/ports/console/index.ts

@@ -0,0 +1,3 @@
+export { ConsolePort } from "./console.port.js";
+export type { Console } from "./console.types.js";
+export { createMemoryConsole, type MemoryConsole } from "./memory-console.js";

package/src/ports/console/memory-console.ts

@@ -0,0 +1,36 @@
+import type { Console } from "./console.types.js";
+
+/** A {@link Console} that keeps its transcript instead of printing it. */
+export interface MemoryConsole extends Console {
+  readonly out: string;
+  readonly err: string;
+}
+
+/**
+ * The double: records what was written, reads from a scripted input.
+ *
+ * @param args.input - the lines `readLine` hands back, in order.
+ * @param args.argv - what `args()` reports.
+ */
+export function createMemoryConsole(
+  args: { input?: readonly string[]; argv?: readonly string[] } = {},
+): MemoryConsole {
+  const state = { out: "", err: "" };
+  const input = [...(args.input ?? [])];
+  return {
+    write: (text) => {
+      state.out += text;
+    },
+    writeError: (text) => {
+      state.err += text;
+    },
+    readLine: () => Promise.resolve(input.length > 0 ? (input.shift() ?? null) : null),
+    args: () => args.argv ?? [],
+    get out() {
+      return state.out;
+    },
+    get err() {
+      return state.err;
+    },
+  };
+}

package/src/ports/console/node-console.ts

@@ -0,0 +1,80 @@
+import { createInterface, type Interface } from "node:readline";
+import type { Console } from "./console.types.js";
+
+/**
+ * Where a node console reads and writes. Injectable, so a test can drive the
+ * real implementation and read back what a script printed.
+ */
+export interface ConsoleStreams {
+  argv?: readonly string[];
+  stdout?: { write(text: string): unknown };
+  stderr?: { write(text: string): unknown };
+  /** Where lines are read from. Defaults to the process's own standard input. */
+  stdin?: NodeJS.ReadableStream & { isTTY?: boolean };
+}
+
+/**
+ * The real console: Node's own streams.
+ *
+ * stdin is opened lazily, on the first `readLine`. A script that never reads
+ * input must not hold the process open waiting for a line that never comes.
+ *
+ * @param streams - overrides for stdin, stdout, stderr and argv. Each defaults
+ * to the process's own.
+ */
+export function createNodeConsole(streams: ConsoleStreams = {}): Console {
+  const lines = createLineReader(streams.stdin ?? process.stdin);
+  const out = streams.stdout ?? process.stdout;
+  const err = streams.stderr ?? process.stderr;
+  return {
+    write: (text) => void out.write(text),
+    writeError: (text) => void err.write(text),
+    readLine: () => lines.next(),
+    args: () => streams.argv ?? [],
+  };
+}
+
+interface LineReaderState {
+  buffered: string[];
+  waiting: ((line: string | null) => void)[];
+  done: boolean;
+  input: NodeJS.ReadableStream & { isTTY?: boolean };
+  reader?: Interface;
+}
+
+function createLineReader(input: NodeJS.ReadableStream & { isTTY?: boolean }): {
+  next(): Promise<string | null>;
+} {
+  const state: LineReaderState = { buffered: [], waiting: [], done: false, input };
+  return { next: () => next(state) };
+}
+
+function next(state: LineReaderState): Promise<string | null> {
+  open(state);
+  if (state.buffered.length > 0) return Promise.resolve(state.buffered.shift() ?? null);
+  if (state.done) return Promise.resolve(null);
+  return new Promise((resolve) => state.waiting.push(resolve));
+}
+
+/** Attach to stdin on the first read; a TTY with no piped input ends at once. */
+function open(state: LineReaderState): void {
+  if (state.reader || state.done) return;
+  if (state.input.isTTY) {
+    state.done = true;
+    return;
+  }
+  state.reader = createInterface({ input: state.input, crlfDelay: Number.POSITIVE_INFINITY });
+  state.reader.on("line", (line) => deliver(state, line));
+  state.reader.on("close", () => finish(state));
+}
+
+function deliver(state: LineReaderState, line: string): void {
+  const resolve = state.waiting.shift();
+  if (resolve) resolve(line);
+  else state.buffered.push(line);
+}
+
+function finish(state: LineReaderState): void {
+  state.done = true;
+  for (const resolve of state.waiting.splice(0)) resolve(null);
+}

package/src/ports/file-system/file-system.errors.ts

@@ -0,0 +1,10 @@
+import { VennError } from "../../errors/index.js";
+
+/** VN8010: a read or a remove targeted a path that does not exist. */
+export function fsNotFound(args: { path: string }): VennError {
+  return new VennError({
+    code: "VN8010",
+    message: `File not found: "${args.path}".`,
+    detail: { path: args.path },
+  });
+}

package/src/ports/file-system/file-system.port.ts

@@ -0,0 +1,12 @@
+import type { Port } from "../../port/index.js";
+import type { FileSystem } from "./file-system.types.js";
+
+/**
+ * The {@link FileSystem} contract. Implementations: `node-fs`, `memory-fs`.
+ */
+export const FileSystemPort: Port<FileSystem> = {
+  id: "venn.port.filesystem",
+  version: 1,
+  requires: ["fs"],
+  methods: ["read", "write", "exists", "remove", "list"],
+};

package/src/ports/file-system/file-system.types.ts

@@ -0,0 +1,27 @@
+/**
+ * Read and write bytes.
+ *
+ * This is the port that lets `@venn-lang/core` run both in Node (the CLI) and in a
+ * Web Worker (the LSP). A leaked `import fs from "node:fs"` in core would break
+ * the editor, so all byte I/O goes through here.
+ */
+export interface FileSystem {
+  /** @throws VennError VN8010 when the path does not exist. */
+  read(path: string): Promise<Uint8Array>;
+  write(path: string, bytes: Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  /** @throws VennError VN8010 when the path does not exist. */
+  remove(path: string): Promise<void>;
+  /**
+   * What a directory holds, one level deep, in no promised order. A path that
+   * is not a directory reads as empty rather than raising: asking what is
+   * inside something that holds nothing has an answer.
+   */
+  list(path: string): Promise<readonly DirEntry[]>;
+}
+
+/** One name inside a directory, and whether it holds more. */
+export interface DirEntry {
+  name: string;
+  directory: boolean;
+}

package/src/ports/file-system/index.ts

@@ -0,0 +1,6 @@
+export { fsNotFound } from "./file-system.errors.js";
+export { FileSystemPort } from "./file-system.port.js";
+export type { DirEntry, FileSystem } from "./file-system.types.js";
+export { createMemoryFs } from "./memory-fs.js";
+// node-fs is deliberately absent: it lives behind @venn-lang/contracts/node, so this
+// barrel stays Worker-safe.

package/src/ports/file-system/memory-fs.ts

@@ -0,0 +1,46 @@
+import { fsNotFound } from "./file-system.errors.js";
+import type { DirEntry, FileSystem } from "./file-system.types.js";
+
+/** The double: byte-exact, isolated per instance, no disk. */
+export function createMemoryFs(): FileSystem {
+  const files = new Map<string, Uint8Array>();
+  return {
+    async read(path) {
+      const bytes = files.get(path);
+      if (!bytes) throw fsNotFound({ path });
+      return bytes.slice();
+    },
+    async write(path, bytes) {
+      files.set(path, bytes.slice());
+    },
+    async exists(path) {
+      return files.has(path);
+    },
+    async remove(path) {
+      if (!files.delete(path)) throw fsNotFound({ path });
+    },
+    async list(path) {
+      return listUnder([...files.keys()], path);
+    },
+  };
+}
+
+/**
+ * What a directory holds, worked out from the paths written.
+ *
+ * There are no directories here, only paths, so a directory is whatever a path
+ * implies one to be. For everything the language does with a directory that is
+ * the same answer the real file system gives, which is what lets the TCK ask
+ * both the same questions.
+ */
+function listUnder(paths: readonly string[], directory: string): DirEntry[] {
+  const prefix = directory === "" || directory === "." ? "" : `${directory.replace(/\/+$/, "")}/`;
+  const seen = new Map<string, boolean>();
+  for (const path of paths) {
+    if (!path.startsWith(prefix)) continue;
+    const rest = path.slice(prefix.length);
+    const slash = rest.indexOf("/");
+    if (rest !== "") seen.set(slash < 0 ? rest : rest.slice(0, slash), slash >= 0);
+  }
+  return [...seen].map(([name, isDirectory]) => ({ name, directory: isDirectory }));
+}

package/src/ports/file-system/node-fs.ts

@@ -0,0 +1,93 @@
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { VennError } from "../../errors/index.js";
+import { fsNotFound } from "./file-system.errors.js";
+import type { DirEntry, FileSystem } from "./file-system.types.js";
+
+/**
+ * The real file system, rooted at `root`.
+ *
+ * @param args.root - where relative paths resolve. Defaults to ".".
+ * @returns a {@link FileSystem} that reports a missing path as VN8010 and any
+ * other failure as VN8019.
+ */
+export function createNodeFs(args: { root?: string } = {}): FileSystem {
+  const root = args.root ?? ".";
+  // A root is where *relative* paths resolve. Joining it onto an absolute path
+  // corrupts the path rather than relocating it: `join(".", "C:/x")` is
+  // `.\C:\x`, which cannot exist, and the failure surfaces far from here.
+  const at = (path: string): string => (isAbsolute(path) ? path : join(root, path));
+  return {
+    read: (path) => readBytes(at(path)),
+    write: (path, bytes) => writeBytes(at(path), bytes),
+    exists: (path) => pathExists(at(path)),
+    remove: (path) => removePath(at(path)),
+    list: (path) => listPath(at(path)),
+  };
+}
+
+async function listPath(directory: string): Promise<DirEntry[]> {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  const found: DirEntry[] = [];
+  for (const entry of entries) {
+    found.push({ name: entry.name, directory: await holdsMore(directory, entry) });
+  }
+  return found;
+}
+
+type Entry = { name: string; isDirectory(): boolean; isSymbolicLink(): boolean };
+
+/**
+ * Whether an entry holds more, following a link if it is one.
+ *
+ * `readdir` reports a symlink as a symlink and not as what it points at, and
+ * whole directory trees are built out of them: pnpm links every installed
+ * package into place, so `node_modules/zod` is a link. Trusting the first
+ * answer finds no packages at all in a full `node_modules`.
+ */
+async function holdsMore(directory: string, entry: Entry): Promise<boolean> {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  const target = await stat(join(directory, entry.name)).catch(() => undefined);
+  return target?.isDirectory() ?? false;
+}
+
+async function readBytes(file: string): Promise<Uint8Array> {
+  try {
+    return new Uint8Array(await readFile(file));
+  } catch (err) {
+    throw mapMissing(err, file);
+  }
+}
+
+async function writeBytes(file: string, bytes: Uint8Array): Promise<void> {
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, bytes);
+}
+
+async function pathExists(file: string): Promise<boolean> {
+  try {
+    await stat(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removePath(file: string): Promise<void> {
+  try {
+    await rm(file);
+  } catch (err) {
+    throw mapMissing(err, file);
+  }
+}
+
+function mapMissing(err: unknown, file: string): VennError {
+  if (isEnoent(err)) return fsNotFound({ path: file });
+  const message = err instanceof Error ? err.message : String(err);
+  return new VennError({ code: "VN8019", message });
+}
+
+function isEnoent(err: unknown): boolean {
+  return typeof err === "object" && err !== null && (err as { code?: string }).code === "ENOENT";
+}

package/src/ports/index.ts

@@ -0,0 +1,9 @@
+export * from "./clock/index.js";
+export * from "./console/index.js";
+export * from "./file-system/index.js";
+export * from "./lock-provider/index.js";
+export * from "./manifest-provider/index.js";
+export * from "./process-provider/index.js";
+export * from "./random/index.js";
+export * from "./secret-provider/index.js";
+export * from "./signal-source/index.js";

package/src/ports/lock-provider/fake-lock.ts

@@ -0,0 +1,6 @@
+import type { LockProvider } from "./lock-provider.types.js";
+
+/** The double: grants immediately and serialises nothing. */
+export function createFakeLock(): LockProvider {
+  return { acquire: async () => () => {} };
+}

package/src/ports/lock-provider/in-process-lock.ts

@@ -0,0 +1,26 @@
+import type { LockProvider, Release } from "./lock-provider.types.js";
+
+/**
+ * The real one: a chained-promise mutex per name. Waiters are served in the
+ * order they asked, and the chain lives only in this process.
+ */
+export function createInProcessLock(): LockProvider {
+  const tails = new Map<string, Promise<void>>();
+  return {
+    acquire: (name) => acquire(tails, name),
+  };
+}
+
+async function acquire(tails: Map<string, Promise<void>>, name: string): Promise<Release> {
+  const previous = tails.get(name) ?? Promise.resolve();
+  let release: Release = () => {};
+  const held = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  tails.set(
+    name,
+    previous.then(() => held),
+  );
+  await previous;
+  return release;
+}

package/src/ports/lock-provider/index.ts

@@ -0,0 +1,4 @@
+export { createFakeLock } from "./fake-lock.js";
+export { createInProcessLock } from "./in-process-lock.js";
+export { LockProviderPort } from "./lock-provider.port.js";
+export type { LockProvider, Release } from "./lock-provider.types.js";

package/src/ports/lock-provider/lock-provider.port.ts

@@ -0,0 +1,16 @@
+import type { Port } from "../../port/index.js";
+import type { LockProvider } from "./lock-provider.types.js";
+
+/**
+ * The {@link LockProvider} contract. Implementations: `in-process-lock`,
+ * `fake-lock`.
+ *
+ * Requires nothing: a mutex is bookkeeping, so it binds even on a host with no
+ * capabilities at all.
+ */
+export const LockProviderPort: Port<LockProvider> = {
+  id: "venn.port.lock",
+  version: 1,
+  requires: [],
+  methods: ["acquire"],
+};

package/src/ports/lock-provider/lock-provider.types.ts

@@ -0,0 +1,8 @@
+/** Releases a held lock. Calling it more than once is a no-op. */
+export type Release = () => void;
+
+/** Named mutexes: the semantics behind `@lock` and `@serial`. */
+export interface LockProvider {
+  /** Resolves once the lock named `name` is held by this caller alone. */
+  acquire(name: string): Promise<Release>;
+}

package/src/ports/manifest-provider/default-manifest.ts

@@ -0,0 +1,31 @@
+import type { Manifest } from "./manifest.types.js";
+import { DEFAULT_PROFILES } from "./read/index.js";
+
+/**
+ * A manifest with nothing declared: what a project without a `venn.toml` is.
+ *
+ * The one place stating what a project gets for saying nothing at all, so a
+ * caller who wants one field need not spell the other dozen.
+ *
+ * @param overrides - fields to state explicitly. `name` and `version` fall back
+ * to `[package]` before falling back to the defaults.
+ */
+export function defaultManifest(overrides: Partial<Manifest> = {}): Manifest {
+  const pkg = { name: "", authors: [], ...overrides.package };
+  return {
+    name: overrides.name ?? pkg.name,
+    version: overrides.version ?? pkg.version ?? "0.0.0",
+    package: pkg,
+    targets: [],
+    dependencies: [],
+    devDependencies: [],
+    patch: [],
+    profiles: { ...DEFAULT_PROFILES },
+    tooling: { manager: "pnpm" },
+    env: {},
+    envFiles: [],
+    paths: {},
+    format: {},
+    ...overrides,
+  };
+}