@venn-lang/core 0.1.0

package/src/lang/venn-lexer.ts

@@ -0,0 +1,34 @@
+import { DefaultLexer, type LexerResult, type TokenizeOptions } from "langium";
+
+/** A single lexed token; NL suppression keys off its token-type name. */
+type Token = LexerResult["tokens"][number];
+
+/**
+ * Makes `NL` (a newline or `;`) significant between statements, but suppresses
+ * it inside `( )` and `[ ]` so calls, arg lists and list literals may still
+ * span multiple physical lines. Blocks and maps (`{ }`) keep their newlines.
+ */
+export class VennLexer extends DefaultLexer {
+  override tokenize(text: string, options?: TokenizeOptions): LexerResult {
+    const result = super.tokenize(text, options);
+    result.tokens = suppressBracketedNewlines(result.tokens);
+    return result;
+  }
+}
+
+function suppressBracketedNewlines(tokens: Token[]): Token[] {
+  const kept: Token[] = [];
+  let depth = 0;
+  for (const token of tokens) {
+    depth = Math.max(0, depth + bracketDelta(token.tokenType.name));
+    if (token.tokenType.name === "NL" && depth > 0) continue;
+    kept.push(token);
+  }
+  return kept;
+}
+
+function bracketDelta(name: string): number {
+  if (name === "(" || name === "[") return 1;
+  if (name === ")" || name === "]") return -1;
+  return 0;
+}

package/src/lang/venn-module.ts

@@ -0,0 +1,51 @@
+import {
+  createDefaultCoreModule,
+  createDefaultSharedCoreModule,
+  EmptyFileSystem,
+  inject,
+  type LangiumCoreServices,
+  type LanguageMetaData,
+  type Module,
+} from "langium";
+import {
+  VennGeneratedModule,
+  VennGeneratedSharedModule,
+  VennLanguageMetaData,
+} from "../generated/module.js";
+import { VennLexer } from "./venn-lexer.js";
+
+// The newline-aware lexer: `NL` is suppressed inside brackets.
+const VennLexerModule: Module<LangiumCoreServices, { parser: { Lexer: VennLexer } }> = {
+  parser: { Lexer: (services) => new VennLexer(services) },
+};
+
+function modeModule(
+  mode: LanguageMetaData["mode"],
+): Module<LangiumCoreServices, { LanguageMetaData: LanguageMetaData }> {
+  return { LanguageMetaData: () => ({ ...VennLanguageMetaData, mode }) };
+}
+
+/**
+ * Build the Langium core services on `EmptyFileSystem`, so no `node:*` is
+ * touched and this runs in both the CLI (Node) and the LSP (Web Worker).
+ *
+ * `production` skips Chevrotain's grammar validation, which dominates the cost
+ * of a first parse and only ever checks generated code against itself. That
+ * check belongs in a test, `venn-module.test.ts`, which is why this takes a
+ * mode at all.
+ *
+ * @param mode Langium language mode; `development` re-enables the validation.
+ */
+export function createVennServices(
+  mode: LanguageMetaData["mode"] = "production",
+): LangiumCoreServices {
+  const shared = inject(createDefaultSharedCoreModule(EmptyFileSystem), VennGeneratedSharedModule);
+  const venn = inject(
+    createDefaultCoreModule({ shared }),
+    VennGeneratedModule,
+    VennLexerModule,
+    modeModule(mode),
+  );
+  shared.ServiceRegistry.register(venn);
+  return venn;
+}

package/src/module/index.ts

@@ -0,0 +1,5 @@
+export {
+  isPackageSpecifier,
+  type SpecifierKind,
+  specifierKind,
+} from "./specifier.js";

package/src/module/specifier.ts

@@ -0,0 +1,21 @@
+/** What a specifier written in an `import` names. */
+export type SpecifierKind = "relative" | "alias" | "package";
+
+/**
+ * Which of the three a specifier is.
+ *
+ * The rule is Node's, so there is no `npm:` prefix and nothing new to learn:
+ * `./util.vn` is a file beside this one, `#shared/auth.vn` goes through
+ * `[paths]`, and a bare `zod` is an installed package. The shape of what is
+ * written already says which it is.
+ */
+export function specifierKind(spec: string): SpecifierKind {
+  if (spec.startsWith(".") || spec.startsWith("/")) return "relative";
+  if (spec.startsWith("#")) return "alias";
+  return "package";
+}
+
+/** Whether the specifier names an installed package rather than a file. */
+export function isPackageSpecifier(spec: string): boolean {
+  return specifierKind(spec) === "package";
+}

package/src/parse/error-to-problem.ts

@@ -0,0 +1,43 @@
+import { buildProblem, CODES } from "../codes/index.js";
+import type { Problem, Span } from "../problem/index.js";
+
+/** Structural view of a Chevrotain lexer error (avoids importing chevrotain). */
+interface LexerError {
+  offset: number;
+  line?: number;
+  column?: number;
+  length: number;
+  message: string;
+}
+
+/** Structural view of a Chevrotain parser (recognition) error. */
+interface RecognitionError {
+  token: { startOffset: number; startLine?: number; startColumn?: number; image: string };
+  message: string;
+}
+
+/** Map a lexer error to VN1001. */
+export function lexerErrorToProblem(args: { error: LexerError; uri: string }): Problem {
+  const e = args.error;
+  const span: Span = {
+    uri: args.uri,
+    offset: e.offset,
+    length: e.length,
+    line: e.line ?? 1,
+    column: e.column ?? 1,
+  };
+  return buildProblem({ spec: CODES.VN1001_LEX, span, title: e.message });
+}
+
+/** Map a parser error to VN1002. */
+export function parserErrorToProblem(args: { error: RecognitionError; uri: string }): Problem {
+  const t = args.error.token;
+  const span: Span = {
+    uri: args.uri,
+    offset: t.startOffset,
+    length: t.image?.length ?? 1,
+    line: t.startLine ?? 1,
+    column: t.startColumn ?? 1,
+  };
+  return buildProblem({ spec: CODES.VN1002_PARSE, span, title: args.error.message });
+}

package/src/parse/index.ts

@@ -0,0 +1,3 @@
+export { parse } from "./parse.js";
+export { EXPRESSION_OFFSET, parseExpression } from "./parse-expression.js";
+export type { ParseOutput } from "./parse-output.types.js";

package/src/parse/parse-expression.ts

@@ -0,0 +1,27 @@
+import type { ExpectStmt, Expr, FlowDecl, StepDecl } from "../generated/ast.js";
+import { parse } from "./parse.js";
+
+const PREFIX = 'flow "e" { step "e" { expect ';
+const SUFFIX = " } }";
+
+/**
+ * How far {@link parseExpression} shifts CST offsets. Exported because the
+ * editor maps the parsed expression back onto the `${…}` it came from, and a
+ * hand-counted constant there would rot the moment this wrapper changes.
+ */
+export const EXPRESSION_OFFSET: number = PREFIX.length;
+
+/**
+ * Parse a standalone expression by wrapping it in a minimal flow and extracting
+ * the `expect` subject. Used by string interpolation (`${…}`).
+ *
+ * @returns The expression, or `undefined` when the source does not parse.
+ */
+export function parseExpression(source: string): Expr | undefined {
+  const { ast, problems } = parse(`${PREFIX}${source}${SUFFIX}`);
+  if (problems.length > 0) return undefined;
+  const flow = ast.decls[0] as FlowDecl | undefined;
+  const step = flow?.body.stmts[0] as StepDecl | undefined;
+  const stmt = step?.body.stmts[0] as ExpectStmt | undefined;
+  return stmt?.subject;
+}

package/src/parse/parse-output.types.ts

@@ -0,0 +1,8 @@
+import type { Document } from "../generated/ast.js";
+import type { Problem } from "../problem/index.js";
+
+/** The result of {@link parse}: a (possibly partial) AST plus VN1xxx problems. */
+export interface ParseOutput {
+  ast: Document;
+  problems: Problem[];
+}

package/src/parse/parse.ts

@@ -0,0 +1,26 @@
+import type { ParseResult } from "langium";
+import type { Document } from "../generated/ast.js";
+import { vennServices } from "../lang/index.js";
+import type { Problem } from "../problem/index.js";
+import { lexerErrorToProblem, parserErrorToProblem } from "./error-to-problem.js";
+import type { ParseOutput } from "./parse-output.types.js";
+
+/**
+ * Parse `.vn` source into an AST plus VN1xxx problems. Synchronous and
+ * filesystem-free (Chevrotain error recovery keeps a partial AST on failure).
+ * It never throws: bad syntax comes back in `problems`.
+ *
+ * @param options.uri Source URI recorded on every span, for editors and reports.
+ */
+export function parse(text: string, options: { uri?: string } = {}): ParseOutput {
+  const uri = options.uri ?? "memory://inline.vn";
+  const result = vennServices().parser.LangiumParser.parse<Document>(text);
+  return { ast: result.value, problems: collectProblems({ result, uri }) };
+}
+
+function collectProblems(args: { result: ParseResult<Document>; uri: string }): Problem[] {
+  const { result, uri } = args;
+  const lexical = result.lexerErrors.map((error) => lexerErrorToProblem({ error, uri }));
+  const syntactic = result.parserErrors.map((error) => parserErrorToProblem({ error, uri }));
+  return [...lexical, ...syntactic];
+}

package/src/problem/build-diff.ts

@@ -0,0 +1,116 @@
+import type { Diff, DiffEntry } from "./diff.types.js";
+import { clamp, formatValue } from "./format-value.js";
+
+/** Past this many fields a wall of text stops being a diff. */
+const MAX_ENTRIES = 40;
+
+/**
+ * Past this the walk stops descending. A value that contains itself has no
+ * bottom, and a stack overflow inside a failure report is a crash, not a report.
+ */
+const MAX_DEPTH = 16;
+
+/**
+ * Turn the two sides a producer compared into a {@link Diff}. Two structures are
+ * walked field by field, so the failure names the field that moved instead of
+ * printing the same rendering twice; anything else stays a plain pair.
+ */
+export function buildDiff(args: {
+  /** Heading for the field-by-field form. */
+  label: string;
+  expected: unknown;
+  actual: unknown;
+  /**
+   * Whether the two sides correspond position by position. Pass `false` for a
+   * comparison that does not, such as `contains`. See {@link walkable}.
+   */
+  aligned?: boolean;
+}): Diff {
+  const entries: DiffEntry[] = [];
+  const { expected, actual } = args;
+  if (walkable(args)) walk({ expected, actual, path: "", entries, depth: 0 });
+  if (entries.length === 0) return pair(expected, actual);
+  return { kind: "fields", label: args.label, entries };
+}
+
+/**
+ * A field-by-field walk claims the two sides correspond position by position.
+ * `equals` claims that; `contains` holds one needle against every item, and
+ * lining that needle up with the haystack would invent a comparison nobody
+ * made, such as `[0] expected 5, actual [1,2]`.
+ */
+function walkable(args: { expected: unknown; actual: unknown; aligned?: boolean }): boolean {
+  return args.aligned !== false && comparable(args.expected, args.actual);
+}
+
+function pair(expected: unknown, actual: unknown): Diff {
+  return {
+    kind: "scalar",
+    expected: clamp(formatValue(expected)),
+    actual: clamp(formatValue(actual)),
+  };
+}
+
+/** Only two structures of the same shape are worth walking side by side. */
+function comparable(expected: unknown, actual: unknown): boolean {
+  if (Array.isArray(expected) !== Array.isArray(actual)) return false;
+  return isStructure(expected) && isStructure(actual);
+}
+
+function isStructure(value: unknown): boolean {
+  return typeof value === "object" && value !== null;
+}
+
+function walk(args: {
+  expected: unknown;
+  actual: unknown;
+  path: string;
+  entries: DiffEntry[];
+  depth: number;
+}): void {
+  const list = Array.isArray(args.expected);
+  for (const key of keysOf(args.expected, args.actual)) {
+    if (args.entries.length >= MAX_ENTRIES) return;
+    visit({ from: args, key, path: childPath({ parent: args.path, key, list }) });
+  }
+}
+
+/**
+ * One field of the walk. It descends only where the two sides disagree: an
+ * untouched subtree is worth one line of context, not fifty.
+ */
+function visit(args: {
+  from: { expected: unknown; actual: unknown; entries: DiffEntry[]; depth: number };
+  key: string;
+  path: string;
+}): void {
+  const expected = read(args.from.expected, args.key);
+  const actual = read(args.from.actual, args.key);
+  const { entries, depth } = args.from;
+  const entry = entryOf(args.path, expected, actual);
+  if (entry.same || depth >= MAX_DEPTH || !comparable(expected, actual)) entries.push(entry);
+  else walk({ expected, actual, path: args.path, entries, depth: depth + 1 });
+}
+
+function entryOf(path: string, expected: unknown, actual: unknown): DiffEntry {
+  const left = formatValue(expected);
+  const right = formatValue(actual);
+  return { path, expected: clamp(left), actual: clamp(right), same: left === right };
+}
+
+/** Every field either side has, in expected-first order. */
+function keysOf(expected: unknown, actual: unknown): string[] {
+  const keys = Object.keys(expected as object);
+  for (const key of Object.keys(actual as object)) {
+    if (!keys.includes(key)) keys.push(key);
+  }
+  return keys;
+}
+
+function childPath(args: { parent: string; key: string; list: boolean }): string {
+  return args.list ? `${args.parent}[${args.key}]` : `${args.parent}.${args.key}`;
+}
+
+function read(value: unknown, key: string): unknown {
+  return (value as Record<string, unknown>)[key];
+}

package/src/problem/diff.types.ts

@@ -0,0 +1,20 @@
+/**
+ * One field of a structured comparison. Fields that agree are carried too: what
+ * makes a diff readable is the one line that moved standing among the ones that
+ * did not.
+ */
+export interface DiffEntry {
+  /** Where the field sits under the subject: `.status`, `[2]`, `.items[0].id`. */
+  path: string;
+  expected: string;
+  actual: string;
+  same: boolean;
+}
+
+/** Structured expected-vs-actual (§16), never a `toString`. */
+export type Diff =
+  | { kind: "scalar"; expected: string; actual: string }
+  | { kind: "json"; path: string; expected: unknown; actual: unknown }
+  | { kind: "text"; expected: string; actual: string }
+  /** The two sides walked field by field; a list position counts as a field. */
+  | { kind: "fields"; label: string; entries: readonly DiffEntry[] };

package/src/problem/format-value.ts

@@ -0,0 +1,40 @@
+/** Past this a value stops informing and starts scrolling. */
+const LIMIT = 200;
+
+/**
+ * One side of a diff, rendered the way the language shows values: strings quoted
+ * so `"1"` never reads as `1`, structures as compact JSON. Never `[object
+ * Object]`, because a failure that hides what it compared is not a report.
+ */
+export function formatValue(value: unknown): string {
+  if (value === undefined) return "absent";
+  if (value === null) return "null";
+  if (typeof value === "function") return "fn";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value !== "object") return String(value);
+  return json(value);
+}
+
+/** Trim for display only. Sameness is decided on the untrimmed rendering. */
+export function clamp(text: string): string {
+  return text.length <= LIMIT ? text : `${text.slice(0, LIMIT)}…`;
+}
+
+function json(value: object): string {
+  try {
+    return JSON.stringify(value) ?? shapeOf(value);
+  } catch {
+    // Cyclic, or a BigInt inside: say what it is rather than what it prints as.
+    return shapeOf(value);
+  }
+}
+
+function shapeOf(value: object): string {
+  if (Array.isArray(value)) return `a list of ${value.length} ${plural("item", value.length)}`;
+  const count = Object.keys(value).length;
+  return `a map with ${count} ${plural("field", count)}`;
+}
+
+function plural(noun: string, count: number): string {
+  return count === 1 ? noun : `${noun}s`;
+}

package/src/problem/index.ts

@@ -0,0 +1,8 @@
+export { buildDiff } from "./build-diff.js";
+export type { Diff, DiffEntry } from "./diff.types.js";
+export { formatValue } from "./format-value.js";
+export type { Problem } from "./problem.types.js";
+export { ProblemError } from "./problem-error.js";
+export type { RelatedInfo } from "./related.types.js";
+export type { Severity } from "./severity.types.js";
+export type { Span } from "./span.types.js";

package/src/problem/problem-error.ts

@@ -0,0 +1,15 @@
+import type { Problem } from "./problem.types.js";
+
+/**
+ * Carries a {@link Problem} across a throw boundary at runtime. Catch it to
+ * recover the structured problem; `message` is only the title.
+ */
+export class ProblemError extends Error {
+  readonly problem: Problem;
+
+  constructor(problem: Problem) {
+    super(problem.title);
+    this.name = "ProblemError";
+    this.problem = problem;
+  }
+}

package/src/problem/problem.types.ts

@@ -0,0 +1,21 @@
+import type { Diff } from "./diff.types.js";
+import type { RelatedInfo } from "./related.types.js";
+import type { Severity } from "./severity.types.js";
+import type { Span } from "./span.types.js";
+
+/**
+ * The single shape shared by compile diagnostics and runtime failures, so one
+ * renderer serves terminal, editor, and UI (§16). Optional fields are populated
+ * as each producer has the information.
+ */
+export interface Problem {
+  code: string;
+  severity: Severity;
+  title: string;
+  span: Span;
+  help?: string;
+  related?: RelatedInfo[];
+  diff?: Diff;
+  note?: string;
+  docs?: string;
+}

package/src/problem/related.types.ts

@@ -0,0 +1,7 @@
+import type { Span } from "./span.types.js";
+
+/** A secondary location, e.g. "here it was declared as…". */
+export interface RelatedInfo {
+  span: Span;
+  label: string;
+}

package/src/problem/severity.types.ts

@@ -0,0 +1,2 @@
+/** How loudly a problem is reported. Only `error` fails a run. */
+export type Severity = "error" | "warning" | "hint";

package/src/problem/span.types.ts

@@ -0,0 +1,8 @@
+/** The exact location of a problem in a source file (1-based line/column). */
+export interface Span {
+  uri: string;
+  offset: number;
+  length: number;
+  line: number;
+  column: number;
+}

package/src/typecheck/action-signature.ts

@@ -0,0 +1,53 @@
+import { splitCall } from "../ast/index.js";
+import type { Expr, MapLit } from "../generated/ast.js";
+import type { Infer } from "./infer.js";
+import { inferExpr } from "./infer.js";
+import type { FnType, Type } from "./type.types.js";
+import { DYNAMIC } from "./type.types.js";
+import type { TypeEnv } from "./type-env.js";
+import { unify } from "./unify.js";
+
+/** A verb call, however it was written: bound to a name, or standing alone. */
+export interface CallSite {
+  target: string;
+  args: readonly Expr[];
+  opts?: MapLit;
+}
+
+/**
+ * What a verb gives back, and what it makes of the arguments on the way.
+ *
+ * This is where a typed world meets an untyped one. With no signature the result
+ * is `dynamic` and nothing is checked, because the language has to keep working
+ * with plugins that never say a word about types. With one, the arguments are
+ * unified against it, which is how `http.on api req => …` learns that `req` is a
+ * request without anyone writing it down.
+ */
+export function callType(site: CallSite, env: TypeEnv, infer: Infer): Type {
+  const signature = infer.catalog?.signatureOf(site.target);
+  // The trailing `{ … }` is the options in both spellings, so it is told apart
+  // here too. Otherwise `http.get(url, { … })` would line the map up against the
+  // URL's parameter and the checker would disagree with the runtime.
+  const split = splitCall(site.args, signature?.params.length ?? 0);
+  const args = split.args.map((arg) => inferExpr(arg, env, infer));
+  const opts = site.opts ?? split.opts;
+  if (opts) inferExpr(opts, env, infer);
+  if (!signature) return DYNAMIC;
+  applyParams(signature, args);
+  return signature.result;
+}
+
+/**
+ * Line the arguments up with the parameters, quietly.
+ *
+ * A mismatch here is not reported: the options map, the trailing arguments and
+ * the shorthands mean a verb can be called in more shapes than one signature
+ * describes. The purpose is to *inform* the argument types, a callback's
+ * parameters above all, not to police the call.
+ */
+function applyParams(signature: FnType, args: readonly Type[]): void {
+  const width = Math.min(signature.params.length, args.length);
+  for (let at = 0; at < width; at += 1) {
+    unify(args[at] as Type, signature.params[at] as Type);
+  }
+}

package/src/typecheck/builtin-types.ts

@@ -0,0 +1,63 @@
+/** What a built-in type is, and how it reads when written. */
+export interface BuiltinType {
+  /** One line, in the reader's terms rather than the compiler's. */
+  doc: string;
+  /** How it is written where a type goes. */
+  example: string;
+}
+
+/**
+ * The types the language brings with it, described once.
+ *
+ * These are the words a reader meets first, so the hover and the completion list
+ * read from here. A built-in that cannot explain itself is a built-in nobody
+ * discovers.
+ */
+export const BUILTIN_TYPES: Readonly<Record<string, BuiltinType>> = {
+  string: {
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: Venn's own interpolation, quoted for a reader.
+    doc: "Text. Interpolates with `${…}` and carries the string methods.",
+    example: "name: string",
+  },
+  number: {
+    doc: "A number, whole or not. There is no separate integer type.",
+    example: "age: number",
+  },
+  bool: {
+    doc: "`true` or `false`, and nothing else — no truthiness, no coercion.",
+    example: "active: bool",
+  },
+  null: { doc: "The absence of a value. Written `null`.", example: "found: string | null" },
+  void: { doc: "What a verb answers with when it answers nothing.", example: "-> void" },
+  dynamic: {
+    doc: "A value whose shape nothing can know — a parsed response, a JSON field. Name a type and annotate a binding to give it one.",
+    example: "const price: Price = res.json",
+  },
+  list: { doc: "Many of one thing, in order.", example: "tags: list<string>" },
+  map: { doc: "Keys not known ahead of time, values all alike.", example: "headers: map<string>" },
+  duration: {
+    doc: "A length of time: `500ms`, `2s`, `1m`. Arithmetic keeps the unit.",
+    example: "timeout: duration",
+  },
+  size: {
+    doc: "A size in bytes: `4kb`, `2mb`. Arithmetic keeps the unit.",
+    example: "limit: size",
+  },
+  percent: {
+    doc: "A proportion: `5%`, `99.9%`. Reads back as `.ratio` or `.percent`.",
+    example: "rate: percent",
+  },
+  instant: {
+    doc: "A moment in time, written as an ISO date: `2026-07-27T12:00:00Z`.",
+    example: "at: instant",
+  },
+  never: {
+    doc: "What a verb that always fails answers with. No value has this type.",
+    example: "-> never",
+  },
+};
+
+/** Whether a name is one of the language's own types. */
+export function isBuiltinType(name: string): boolean {
+  return name in BUILTIN_TYPES;
+}