@venn-lang/core 0.1.0

package/src/typecheck/seed-values.ts

@@ -0,0 +1,64 @@
+import type { AstNode } from "langium";
+import type { DecoDecl, Document, LetStmt } from "../generated/ast.js";
+import * as ast from "../generated/ast.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import { createContext } from "./context.js";
+import type { Infer, Slot } from "./infer.js";
+import { collectNamedTypes } from "./named-types.js";
+import type { SeedRun } from "./seed-params.js";
+import { solidify } from "./solidify.js";
+import type { Type } from "./type.types.js";
+
+/** What the file's own top-level values turned out to be, by the name they carry. */
+export type ValueSeeds = ReadonlyMap<string, Type>;
+
+/**
+ * A first pass, in silence: what the file's top-level `const`s and `let`s hold.
+ *
+ * A named `fn` is checked before those bindings exist, because generalising it
+ * is what lets two callers use it at two types, and a binding written above it
+ * may call it. So the file's values cannot simply be bound first. A function
+ * body is still free to read them, since it runs later when they are all there,
+ * and this pass is what gives those reads a type.
+ *
+ * Unlike the parameter seeds, a conflict elsewhere does not throw the answers
+ * away. A value's type is written in the file, not guessed from a caller, and a
+ * half-typed line somewhere else is the normal state of a file being edited:
+ * exactly when the help is worth most.
+ */
+export function seedValues(args: {
+  document: Document;
+  catalog?: TypeCatalog;
+  decos?: ReadonlyMap<string, DecoDecl>;
+  parsed?: Map<AstNode, Slot[]>;
+  run: SeedRun;
+}): ValueSeeds {
+  const values = topLevelValues(args.document);
+  if (values.length === 0 || !args.document.decls.some(ast.isFnDecl)) return new Map();
+  const ctx = createContext();
+  const infer: Infer = {
+    ctx,
+    named: collectNamedTypes(args.document, ctx, args.catalog),
+    catalog: args.catalog,
+    decos: args.decos,
+    parsed: args.parsed,
+    types: new Map(),
+    seeding: true,
+  };
+  args.run(args.document, infer);
+  return settled(values, infer);
+}
+
+function topLevelValues(document: Document): LetStmt[] {
+  return document.decls.filter(ast.isLetStmt);
+}
+
+function settled(values: readonly LetStmt[], infer: Infer): ValueSeeds {
+  const seeds = new Map<string, Type>();
+  for (const decl of values) {
+    const found = infer.types?.get(decl);
+    const solid = found && solidify(found);
+    if (solid) seeds.set(decl.name, solid);
+  }
+  return seeds;
+}

package/src/typecheck/show.ts

@@ -0,0 +1,64 @@
+import type { RecordType, Type } from "./type.types.js";
+import { prune } from "./unify.js";
+
+const LETTERS = "abcdefghijklmnopqrstuvwxyz";
+
+/** Render one type for a hover or a diagnostic, naming variables `a`, `b`, … */
+export function showType(type: Type): string {
+  return render(type, new Map());
+}
+
+/**
+ * Several types that belong together, named as one.
+ *
+ * Rendering them one at a time restarts the alphabet each time, so the two
+ * unrelated parameters of `fn (nome, idade)` would both come back as `a`. That
+ * says they are the same type, which is the opposite of what is known.
+ */
+export function showTypes(types: readonly Type[]): string[] {
+  const names = new Map<number, string>();
+  return types.map((type) => render(type, names));
+}
+
+function render(type: Type, names: Map<number, string>): string {
+  const t = prune(type);
+  switch (t.kind) {
+    case "prim":
+      return t.name;
+    case "dynamic":
+      return "dynamic";
+    case "var":
+      return nameOf(t.id, names);
+    case "list":
+      return `list<${render(t.element, names)}>`;
+    case "fn":
+      return `fn(${t.params.map((p) => render(p, names)).join(", ")}) -> ${render(t.result, names)}`;
+    case "record":
+      return renderRecord(t, names);
+    case "literal":
+      return typeof t.value === "string" ? `"${t.value}"` : String(t.value);
+    case "union":
+      return t.members.map((m) => render(m, names)).join(" | ");
+    case "opaque":
+      return t.name;
+  }
+}
+
+/** Named keys read as a shape; unnamed ones read as the map they are. */
+function renderRecord(type: RecordType, names: Map<number, string>): string {
+  const rest = type.rest ? `map<${render(type.rest, names)}>` : undefined;
+  if (type.fields.size === 0) return rest ?? "{}";
+  const body = [...type.fields]
+    .map(([name, field]) => `${name}: ${render(field, names)}`)
+    .join(", ");
+  return `{ ${body}${rest ? `, …: ${render(type.rest as Type, names)}` : ""} }`;
+}
+
+function nameOf(id: number, names: Map<number, string>): string {
+  const existing = names.get(id);
+  if (existing) return existing;
+  const index = names.size;
+  const name = index < LETTERS.length ? (LETTERS[index] as string) : `t${index}`;
+  names.set(id, name);
+  return name;
+}

package/src/typecheck/solidify.ts

@@ -0,0 +1,60 @@
+import { list, type RecordType, record, type Type, union } from "./type.types.js";
+import { prune } from "./unify.js";
+
+/**
+ * The same type with every variable resolved, or nothing if any is still open.
+ *
+ * A type solved during one pass carries variables belonging to that pass's
+ * context; handing one to the next pass would smuggle in a variable nobody owns.
+ * Only a fully settled type crosses, so `undefined` here is an answer rather
+ * than a failure.
+ */
+export function solidify(type: Type): Type | undefined {
+  const t = prune(type);
+  switch (t.kind) {
+    case "var":
+      return undefined;
+    case "list":
+      return map1(solidify(t.element), list);
+    case "union":
+      return all(t.members)?.length ? union(all(t.members) as Type[]) : undefined;
+    case "record":
+      return solidRecord(t);
+    case "fn":
+      return solidFn(t.params, t.result, t);
+    default:
+      return t;
+  }
+}
+
+function map1(inner: Type | undefined, wrap: (type: Type) => Type): Type | undefined {
+  return inner ? wrap(inner) : undefined;
+}
+
+function all(types: readonly Type[]): Type[] | undefined {
+  const solid = types.map(solidify);
+  return solid.some((type) => type === undefined) ? undefined : (solid as Type[]);
+}
+
+function solidRecord(type: RecordType): Type | undefined {
+  const out = new Map<string, Type>();
+  for (const [name, field] of type.fields) {
+    const solid = solidify(field);
+    if (!solid) return undefined;
+    out.set(name, solid);
+  }
+  const rest = type.rest ? solidify(type.rest) : undefined;
+  if (type.rest && !rest) return undefined;
+  return record(out, type.open, rest);
+}
+
+function solidFn(
+  params: readonly Type[],
+  result: Type,
+  shape: { variadic?: boolean; ignorableFrom?: number },
+): Type | undefined {
+  const solidParams = all(params);
+  const solidResult = solidify(result);
+  if (!solidParams || !solidResult) return undefined;
+  return { kind: "fn", params: solidParams, result: solidResult, ...shape };
+}

package/src/typecheck/spec-to-type.ts

@@ -0,0 +1,88 @@
+import type { FnSpec, RecordSpec, TypeSpec } from "@venn-lang/types";
+import {
+  DYNAMIC,
+  fn,
+  list,
+  literal,
+  mapOf,
+  NULL,
+  opaque,
+  prim,
+  record,
+  type Type,
+  union,
+} from "./type.types.js";
+
+/** How a `ref` finds what it points at. Returning undefined is fine: the
+ * reference degrades to `dynamic` rather than failing. */
+export type ResolveRef = (name: string) => Type | undefined;
+
+/**
+ * Read the published form of a type into the checker's own.
+ *
+ * The wire format is plain data with no inference variables; the checker's type
+ * is a live thing that unification writes into. Keeping them apart is what lets
+ * a signature be written by hand, generated from a `.d.ts`, or shipped as JSON
+ * without any of them reaching into the compiler.
+ */
+export function specToType(spec: TypeSpec, resolve: ResolveRef): Type {
+  switch (spec.kind) {
+    case "prim":
+      return prim(spec.name);
+    case "literal":
+      return literal(spec.value);
+    case "list":
+      return list(specToType(spec.element, resolve));
+    case "map":
+      return mapOf(specToType(spec.value, resolve));
+    default:
+      return compound(spec, resolve);
+  }
+}
+
+function compound(spec: TypeSpec, resolve: ResolveRef): Type {
+  switch (spec.kind) {
+    case "record":
+      return recordType(spec, resolve);
+    case "fn":
+      return fnType(spec, resolve);
+    case "union":
+      return union(spec.members.map((member) => specToType(member, resolve)));
+    case "opaque":
+      return opaque(spec.name, opaqueMembers(spec.members, resolve));
+    case "ref":
+      return resolve(spec.name) ?? DYNAMIC;
+    default:
+      return DYNAMIC;
+  }
+}
+
+/** An optional field is one that may not be there: `T | null`, said plainly. */
+function recordType(spec: RecordSpec, resolve: ResolveRef): Type {
+  const optional = new Set(spec.optional ?? []);
+  const fields = new Map<string, Type>();
+  for (const [name, field] of Object.entries(spec.fields)) {
+    const type = specToType(field, resolve);
+    fields.set(name, optional.has(name) ? union([type, NULL]) : type);
+  }
+  return record(fields, spec.open ?? false);
+}
+
+/** What a handle publishes, read into the checker's own types. */
+function opaqueMembers(
+  members: Readonly<Record<string, TypeSpec>> | undefined,
+  resolve: ResolveRef,
+): ReadonlyMap<string, Type> | undefined {
+  if (!members) return undefined;
+  const into = new Map<string, Type>();
+  for (const [name, spec] of Object.entries(members)) into.set(name, specToType(spec, resolve));
+  return into;
+}
+
+function fnType(spec: FnSpec, resolve: ResolveRef): Type {
+  const params = spec.params.map((param) => specToType(param, resolve));
+  const result = specToType(spec.result, resolve);
+  return spec.takes === undefined
+    ? fn(params, result)
+    : { kind: "fn", params, result, ignorableFrom: spec.takes };
+}

package/src/typecheck/type-env.ts

@@ -0,0 +1,46 @@
+import { freeVars, type Scheme } from "./scheme.js";
+
+/**
+ * The names in scope during inference, mapped to their type schemes. Chained, so
+ * a function body sees the outer scope. Names it does not know resolve to
+ * `dynamic` at the use site: the type checker only ever settles type
+ * consistency, never name resolution, which is the runtime's static check.
+ */
+export interface TypeEnv {
+  lookup(name: string): Scheme | undefined;
+  with(name: string, scheme: Scheme): TypeEnv;
+  /** Ids of the variables free across every binding: what must not generalise. */
+  freeVars(): Set<number>;
+}
+
+export function emptyEnv(): TypeEnv {
+  return envOf(new Map(), undefined);
+}
+
+function envOf(bindings: Map<string, Scheme>, parent: TypeEnv | undefined): TypeEnv {
+  return {
+    lookup: (name) => bindings.get(name) ?? parent?.lookup(name),
+    with(name, scheme) {
+      return envOf(new Map([[name, scheme]]), this);
+    },
+    freeVars() {
+      const free = parent ? parent.freeVars() : new Set<number>();
+      for (const scheme of bindings.values()) collect(scheme, free);
+      return free;
+    },
+  };
+}
+
+/** A binding's contribution to the environment's free variables: the ones it did
+ * not quantify. */
+function collect(scheme: Scheme, into: Set<number>): void {
+  const quantified = new Set(scheme.quantified);
+  for (const id of freeVars(scheme.type)) if (!quantified.has(id)) into.add(id);
+}
+
+/** Extend an environment with several bindings at once. */
+export function withAll(env: TypeEnv, bindings: Iterable<[string, Scheme]>): TypeEnv {
+  let next = env;
+  for (const [name, scheme] of bindings) next = next.with(name, scheme);
+  return next;
+}

package/src/typecheck/type-ref.ts

@@ -0,0 +1,62 @@
+import type { SingleType, TypeRef } from "../generated/ast.js";
+import { isNamedType } from "../generated/ast.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import type { TypeContext } from "./context.js";
+import type { NamedTypes } from "./named-types.js";
+import { DYNAMIC, fn, list, literal, prim, type Type, union } from "./type.types.js";
+
+const PRIMS = new Set(["number", "string", "bool", "null", "void"]);
+
+/** Everything resolving a written annotation may need to look something up. */
+export interface RefScope {
+  ctx: TypeContext;
+  named: NamedTypes;
+  /** Where a qualified name like `http.Request` is found. */
+  catalog?: TypeCatalog;
+}
+
+/**
+ * Read a written annotation (`list<number>`, `User`, `http.Request`,
+ * `"GET" | "POST"`) into a type. An unknown name stays `dynamic`, so an
+ * annotation never adds friction: being wrong about a name must not be worse
+ * than saying nothing.
+ */
+export function typeRefToType(args: RefScope & { ref: TypeRef | undefined }): Type {
+  if (!args.ref) return args.ctx.fresh();
+  const members = args.ref.members.map((single) => singleToType({ ...args, single }));
+  if (members.length === 0) return DYNAMIC;
+  return union(members as Type[]);
+}
+
+function singleToType(args: RefScope & { single: SingleType }): Type {
+  const { single } = args;
+  // A `SingleType` that is not a name is a written-out literal such as `"GET"`,
+  // and it means that one value. Widening it to `string` would enforce nothing.
+  if (!isNamedType(single)) return literalOf(single);
+  const name = single.name;
+  const generic = genericType(name, single, args);
+  if (generic) return generic;
+  if (PRIMS.has(name)) return prim(name as "number");
+  return args.named.get(name) ?? args.catalog?.typeOf(name) ?? DYNAMIC;
+}
+
+/** `"GET"` written as a type. The quotes are the grammar's, not the value's. */
+function literalOf(single: SingleType): Type {
+  const written = (single as { value?: string }).value ?? "";
+  return literal(written.replace(/^["']|["']$/g, ""));
+}
+
+function genericType(
+  name: string,
+  single: SingleType & { args?: TypeRef[] },
+  args: RefScope,
+): Type | undefined {
+  // `ref` last, deliberately: the scope threaded down here still carries the
+  // *outer* annotation, and spreading it afterwards would hand each argument its
+  // own parent, leaving `list<number>` reading itself forever.
+  const params = (single.args ?? []).map((ref) => typeRefToType({ ...args, ref }));
+  if (name === "list") return list(params[0] ?? DYNAMIC);
+  if (name === "fn") return fn(params.slice(0, -1), params[params.length - 1] ?? DYNAMIC);
+  if (name === "map") return DYNAMIC;
+  return undefined;
+}

package/src/typecheck/type.types.ts

@@ -0,0 +1,168 @@
+/**
+ * A static type. `dynamic` is the escape hatch for the result of a plugin
+ * action, an HTTP response, `json`: anything the checker cannot know. It unifies
+ * with everything and never produces an error, so the effectful world places no
+ * annotation burden on the pure one.
+ */
+export type Type =
+  | PrimType
+  | LiteralType
+  | ListType
+  | RecordType
+  | FnType
+  | UnionType
+  | OpaqueType
+  | DynamicType
+  | TypeVar;
+
+export type PrimName =
+  | "number"
+  | "string"
+  | "bool"
+  | "null"
+  | "void"
+  | "duration"
+  | "size"
+  | "percent"
+  | "instant";
+
+export interface PrimType {
+  readonly kind: "prim";
+  readonly name: PrimName;
+}
+
+/** One value, standing for itself: `"GET"`, `200`, `true`. */
+export interface LiteralType {
+  readonly kind: "literal";
+  readonly value: string | number | boolean;
+}
+
+export interface ListType {
+  readonly kind: "list";
+  readonly element: Type;
+}
+
+/** One of several. What makes `"GET" | "POST"` more than a string. */
+export interface UnionType {
+  readonly kind: "union";
+  readonly members: readonly Type[];
+}
+
+/**
+ * A handle with a name and no visible inside: a server, a browser, a connection.
+ *
+ * This is the border with the world outside. Whatever a JavaScript class really
+ * is, it arrives here as a name its own namespace's verbs understand and nothing
+ * else can open, which keeps the object graph of another language out of this
+ * one.
+ */
+export interface OpaqueType {
+  readonly kind: "opaque";
+  readonly name: string;
+  /** What it publishes. Absent means a name and nothing more. */
+  readonly members?: ReadonlyMap<string, Type>;
+}
+
+/** A map/object with known fields. `open` records tolerate extra fields. */
+export interface RecordType {
+  readonly kind: "record";
+  readonly fields: ReadonlyMap<string, Type>;
+  readonly open: boolean;
+  /**
+   * What a key nobody listed holds: `Record<string, string>` written as a type.
+   * Without it an open record answers `dynamic` for everything it did not name,
+   * which is right for a loose map and wrong for `headers`.
+   */
+  readonly rest?: Type;
+}
+
+/** A function: what it takes, what it gives back, and how strictly it is called. */
+export interface FnType {
+  readonly kind: "fn";
+  readonly params: readonly Type[];
+  readonly result: Type;
+  /** Takes any number of arguments, as `str(a, b, c)` and `range(1, 4)` do. Its
+   * params describe the shape it accepts, not a count to enforce. */
+  readonly variadic?: boolean;
+  /** Params from this index on are handed over but may be ignored: `map` offers
+   * the index to a callback that is free to take only the item. */
+  readonly ignorableFrom?: number;
+}
+
+export interface DynamicType {
+  readonly kind: "dynamic";
+}
+
+/** A unification variable. `ref` is filled in as inference solves it. */
+export interface TypeVar {
+  readonly kind: "var";
+  readonly id: number;
+  ref: Type | undefined;
+}
+
+/** The one `dynamic`. Shared, since it carries no state to keep apart. */
+export const DYNAMIC: DynamicType = { kind: "dynamic" };
+
+/** One of the language's primitive types, by name. */
+export function prim(name: PrimName): PrimType {
+  return { kind: "prim", name };
+}
+
+export const NUMBER: PrimType = prim("number");
+export const STRING: PrimType = prim("string");
+export const BOOL: PrimType = prim("bool");
+export const NULL: PrimType = prim("null");
+export const VOID: PrimType = prim("void");
+
+export function list(element: Type): ListType {
+  return { kind: "list", element };
+}
+
+export function fn(params: readonly Type[], result: Type): FnType {
+  return { kind: "fn", params, result };
+}
+
+/** A function of any arity, e.g. `str(…)`: only its result is fixed. */
+export function variadic(params: readonly Type[], result: Type): FnType {
+  return { kind: "fn", params, result, variadic: true };
+}
+
+/**
+ * A callback that is handed `params` but need only take the first `takes` of
+ * them. `list.map` passes the index alongside the item, and `p => p.age` is
+ * still a perfectly good argument to it.
+ */
+export function callback(params: readonly Type[], result: Type, takes: number): FnType {
+  return { kind: "fn", params, result, ignorableFrom: takes };
+}
+
+export function record(fields: ReadonlyMap<string, Type>, open = false, rest?: Type): RecordType {
+  return rest ? { kind: "record", fields, open, rest } : { kind: "record", fields, open };
+}
+
+/** Keys unknown, values all alike: `map<string>`. */
+export function mapOf(value: Type): RecordType {
+  return record(new Map(), true, value);
+}
+
+/** One value standing for itself, as `"GET"` does where a type is written. */
+export function literal(value: string | number | boolean): LiteralType {
+  return { kind: "literal", value };
+}
+
+/** A named handle, with the surface it publishes, or a bare name without one. */
+export function opaque(name: string, members?: ReadonlyMap<string, Type>): OpaqueType {
+  return members ? { kind: "opaque", name, members } : { kind: "opaque", name };
+}
+
+/** A union of one is that one: `string | string` helps nobody read anything. */
+export function union(members: readonly Type[]): Type {
+  const flat = members.flatMap((m) => (m.kind === "union" ? m.members : [m]));
+  return flat.length === 1 ? (flat[0] as Type) : { kind: "union", members: flat };
+}
+
+/** Which primitive a literal is one of: `"GET"` is a string, and unifies as one. */
+export function baseOf(value: LiteralType["value"]): PrimName {
+  if (typeof value === "number") return "number";
+  return typeof value === "boolean" ? "bool" : "string";
+}