@venn-lang/core 0.1.0

package/src/typecheck/check-types.ts

@@ -0,0 +1,232 @@
+import type { AstNode } from "langium";
+import { buildProblem, CODES } from "../codes/index.js";
+import type { ImportedDeco } from "../expand/index.js";
+import type { Declaration, Document, Expr, FnDecl } from "../generated/ast.js";
+import * as ast from "../generated/ast.js";
+import type { Problem, Span } from "../problem/index.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import { checkDecoBody, checkDecos, decosInReach } from "./check-deco.js";
+import { checkBlock, checkFragment, checkStatement } from "./check-stmts.js";
+import { createContext, type TypeContext, type TypeMismatch } from "./context.js";
+import { type Infer, inferFn, type Slot } from "./infer.js";
+import { collectNamedTypes } from "./named-types.js";
+import { PRELUDE_SPECS } from "./prelude-types.js";
+import { reshapedFns } from "./reshaped-fns.js";
+import { generalize, mono } from "./scheme.js";
+import { seedParams } from "./seed-params.js";
+import { seedValues } from "./seed-values.js";
+import { showType } from "./show.js";
+import { DYNAMIC, type Type } from "./type.types.js";
+import { emptyEnv, type TypeEnv } from "./type-env.js";
+import { prune, unify } from "./unify.js";
+
+/** What one check of a document produced. */
+export interface CheckTypesResult {
+  problems: Problem[];
+  /** Every expression's inferred type, keyed by node, for hover. */
+  types: Map<object, Type>;
+  /** Per string literal, the expression parsed from each of its ${…} slots. */
+  slots: Map<object, (Expr | undefined)[]>;
+}
+
+/** What the checker may be told about the world outside the file. */
+export interface CheckTypesOptions {
+  uri?: string;
+  /** The types and signatures the loaded plugins contribute. */
+  catalog?: TypeCatalog;
+  /** The `pub deco`s this file's imports reach. Without them an imported
+   * `@name` is a name the checker knows nothing about, and says nothing about. */
+  decos?: ReadonlyMap<string, ImportedDeco>;
+  /** What the names this file imports turned out to be, from the files it names. */
+  imports?: ReadonlyMap<string, Type>;
+}
+
+/**
+ * Infer and check the types across a document.
+ *
+ * Errors are raised only where a type is actually known. Anything touching
+ * `dynamic`, such as a plugin that published no signature or an HTTP response,
+ * is left alone, so the checker helps without ever blocking.
+ *
+ * @returns the problems found, plus the inferred type of every expression and
+ * the expressions parsed out of each `${…}`, both of which the editor reads.
+ */
+export function checkTypes(document: Document, options: CheckTypesOptions = {}): CheckTypesResult {
+  const uri = options.uri ?? "memory://inline.vn";
+  const ctx = createContext();
+  // Shared with the seeding pass: parsing every `${…}` twice is the one part of
+  // a second walk that would actually cost something.
+  const parsed = new Map<AstNode, Slot[]>();
+  const decos = decosInReach({ document, imported: options.decos });
+  const shared = { document, catalog: options.catalog, decos, parsed, run: pass };
+  const values = seedValues(shared);
+  const seeds = seedParams(shared);
+  const infer: Infer = {
+    ctx,
+    named: collectNamedTypes(document, ctx, options.catalog),
+    catalog: options.catalog,
+    decos,
+    seeds,
+    values,
+    parsed,
+    imports: options.imports,
+    types: new Map(),
+    slots: new Map(),
+  };
+  pass(document, infer);
+  // After the pass, so a decorator's arguments are read once, and before the
+  // mismatches are turned into problems, since that is where they land.
+  const deco = checkDecos({ document, infer, uri });
+  return {
+    problems: [...ctx.mismatches.map((m) => problem(m, uri)), ...deco],
+    types: infer.types ?? new Map(),
+    slots: infer.slots ?? new Map(),
+  };
+}
+
+/** One walk of the whole document: top-level bindings, then everything that runs. */
+function pass(document: Document, infer: Infer): void {
+  walk(document, topLevelEnv(document, infer), infer);
+}
+
+/**
+ * Hoist functions and bind top-level values, so the whole file sees them.
+ *
+ * Generalising is what makes a helper reusable at more than one type, and also
+ * what stops a call site from ever reaching the declaration, since each use gets
+ * its own copy. The seeding pass therefore skips it: that pass exists precisely
+ * to let the callers speak.
+ */
+function topLevelEnv(document: Document, infer: Infer): TypeEnv {
+  const fns = document.decls.filter(ast.isFnDecl);
+  // A decorator may hand this function a shape nobody here can read; its body is
+  // still checked, but its signature is not the one callers will meet.
+  const reshaped = reshapedFns({ document, decos: infer.decos ?? new Map() });
+  const outer = withImports(preludeEnv(), infer);
+  let env = withSeededValues(hoist({ fns, reshaped, ctx: infer.ctx, env: outer }), infer);
+  for (const decl of fns) {
+    const inferred = inferFn(decl, env, infer);
+    if (!reshaped.has(decl)) unify(env.lookup(decl.name)?.type ?? placeholder(infer), inferred);
+  }
+  if (!infer.seeding) env = generalizeFns(fns, env, infer);
+  return bindValues(document, env, infer);
+}
+
+/**
+ * What the file's values hold, put in reach of the function bodies about to be
+ * checked. The real binding still happens below, in source order and with the
+ * annotations read; this only stops a body from meeting a name it cannot know.
+ */
+function withSeededValues(env: TypeEnv, infer: Infer): TypeEnv {
+  let next = env;
+  for (const [name, type] of infer.values ?? []) next = next.with(name, mono(type));
+  return next;
+}
+
+/**
+ * The names this file imported, each with the type its own module gave it.
+ *
+ * Generalised over everything free in them, for two reasons: a generic helper
+ * stays generic across the file boundary, and the variables belonging to the
+ * pass that inferred them are replaced with fresh ones here rather than being
+ * unified with anything in this file.
+ */
+function withImports(env: TypeEnv, infer: Infer): TypeEnv {
+  let next = env;
+  for (const [name, type] of infer.imports ?? []) next = next.with(name, generalize(type, EMPTY));
+  return next;
+}
+
+const EMPTY: ReadonlySet<number> = new Set();
+
+/** The prelude is in scope everywhere, so inference knows what its verbs return. */
+function preludeEnv(): TypeEnv {
+  let env = emptyEnv();
+  for (const [name, spec] of Object.entries(PRELUDE_SPECS)) env = env.with(name, mono(spec.type));
+  return env;
+}
+
+function hoist(args: {
+  fns: readonly FnDecl[];
+  reshaped: ReadonlySet<FnDecl>;
+  ctx: TypeContext;
+  env: TypeEnv;
+}): TypeEnv {
+  let next = args.env;
+  for (const decl of args.fns) {
+    next = next.with(decl.name, mono(args.reshaped.has(decl) ? DYNAMIC : args.ctx.fresh()));
+  }
+  return next;
+}
+
+function generalizeFns(fns: readonly FnDecl[], env: TypeEnv, infer: Infer): TypeEnv {
+  let next = env;
+  for (const decl of fns) {
+    const type = env.lookup(decl.name)?.type;
+    if (!type) continue;
+    // The declaration carries its own type, so hovering the name shows it.
+    infer.types?.set(decl, prune(type));
+    next = next.with(decl.name, generalize(prune(type), new Set()));
+  }
+  return next;
+}
+
+function bindValues(document: Document, env: TypeEnv, infer: Infer): TypeEnv {
+  let next = env;
+  for (const decl of document.decls) {
+    if (ast.isLetStmt(decl)) next = checkStatement(decl, next, infer);
+  }
+  return next;
+}
+
+/** Check the executable parts: flows, fragments, and top-level statements. */
+function walk(document: Document, env: TypeEnv, infer: Infer): void {
+  for (const decl of document.decls) checkDeclaration(decl, env, infer);
+}
+
+function checkDeclaration(decl: Declaration, env: TypeEnv, infer: Infer): void {
+  if (ast.isFlowDecl(decl)) checkBlock(decl.body, env, infer);
+  else if (ast.isFragmentDecl(decl)) checkFragment(decl, env, infer);
+  else if (ast.isDecoDecl(decl)) checkDecoBody(decl, env, infer);
+  else if (!ast.isFnDecl(decl) && !ast.isLetStmt(decl) && isExecutable(decl)) {
+    checkStatement(decl as never, env, infer);
+  }
+}
+
+function isExecutable(decl: Declaration): boolean {
+  return !(ast.isTypeDecl(decl) || ast.isConfigDecl(decl) || ast.isMatrixDecl(decl));
+}
+
+function placeholder(infer: Infer): Type {
+  return infer.ctx.fresh();
+}
+
+function problem(mismatch: TypeMismatch, uri: string): Problem {
+  const title = titleOf(mismatch);
+  return buildProblem({
+    spec: mismatch.unit ? CODES.VN3012_UNIT_MISMATCH : CODES.VN3010_TYPE_MISMATCH,
+    span: spanOf(mismatch.node, uri),
+    title,
+  });
+}
+
+/** A unit clash already reads as a sentence; anything else is a type mismatch. */
+function titleOf(mismatch: TypeMismatch): string {
+  if (mismatch.unit) return mismatch.note ?? "These values cannot be combined.";
+  if (mismatch.note) return `Type ${showType(mismatch.expected)} ${mismatch.note}.`;
+  return `Type mismatch: expected ${showType(mismatch.expected)}, found ${showType(mismatch.actual)}.`;
+}
+
+function spanOf(node: { $cstNode?: unknown }, uri: string): Span {
+  const cst = node.$cstNode as
+    | { offset: number; length: number; range?: { start: { line: number; character: number } } }
+    | undefined;
+  const start = cst?.range?.start;
+  return {
+    uri,
+    offset: cst?.offset ?? 0,
+    length: cst?.length ?? 0,
+    line: (start?.line ?? 0) + 1,
+    column: (start?.character ?? 0) + 1,
+  };
+}

package/src/typecheck/context.ts

@@ -0,0 +1,31 @@
+import type { AstNode } from "langium";
+import type { Type, TypeVar } from "./type.types.js";
+
+/**
+ * Per-run inference state: a fresh-variable source and the list of type
+ * mismatches found. Held in a context (not a module global) so two checks never
+ * share variable ids or leak diagnostics into each other.
+ */
+export interface TypeContext {
+  fresh(): TypeVar;
+  mismatches: TypeMismatch[];
+}
+
+/** One place where two types could not be made equal, at a source node. */
+export interface TypeMismatch {
+  node: AstNode;
+  expected: Type;
+  actual: Type;
+  note?: string;
+  /** A unit clash rather than a plain type clash: VN3012 instead of VN3010. */
+  unit?: boolean;
+}
+
+/** A fresh inference context: variable ids from zero, no mismatches recorded. */
+export function createContext(): TypeContext {
+  let next = 0;
+  return {
+    fresh: () => ({ kind: "var", id: next++, ref: undefined }),
+    mismatches: [],
+  };
+}

package/src/typecheck/imported-types.ts

@@ -0,0 +1,127 @@
+import type { TypeSpec } from "@venn-lang/types";
+import type { Document } from "../generated/ast.js";
+import * as ast from "../generated/ast.js";
+import { isPackageSpecifier } from "../module/index.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import { checkTypes } from "./check-types.js";
+import { type ResolveRef, specToType } from "./spec-to-type.js";
+import { record, type Type } from "./type.types.js";
+
+/** What the names a file imported turned out to be, ready to bind in its env. */
+export type ImportedTypes = ReadonlyMap<string, Type>;
+
+export interface ImportedTypesArgs {
+  document: Document;
+  uri: string;
+  /** Every module the import graph reached, already parsed, by resolved URI. */
+  modules: ReadonlyMap<string, Document>;
+  /** How a specifier written in one file names another. */
+  resolve: (from: string, spec: string) => string;
+  catalog?: TypeCatalog;
+  /**
+   * What each installed package publishes, derived from its `.d.ts`.
+   *
+   * Keyed by the specifier as written, because that is what the import says.
+   * Absent for a host that has not derived any, which is every run in an editor
+   * that has not installed anything yet.
+   */
+  packages?: ReadonlyMap<string, Record<string, TypeSpec>>;
+}
+
+/**
+ * The types of the names a document imports, worked out from the files it names.
+ *
+ * Each module is checked on its own, with *its* imports resolved first, so a
+ * `pub fn` that calls another file has the signature it really has. That is what
+ * lets `triplo("texto")` be refused against a `fn(number) -> number` declared
+ * one file away.
+ *
+ * @returns a type per imported name. A name whose module publishes nothing for
+ * it is simply absent, and the checker treats it as `dynamic`.
+ */
+export function importedTypes(args: ImportedTypesArgs): ImportedTypes {
+  const state: State = {
+    modules: args.modules,
+    resolve: args.resolve,
+    catalog: args.catalog,
+    packages: args.packages,
+    done: new Map(),
+    busy: new Set([args.uri]),
+  };
+  return bindingsOf({ document: args.document, uri: args.uri, state });
+}
+
+interface State {
+  modules: ReadonlyMap<string, Document>;
+  resolve: (from: string, spec: string) => string;
+  catalog?: TypeCatalog;
+  packages?: ReadonlyMap<string, Record<string, TypeSpec>>;
+  done: Map<string, Map<string, Type>>;
+  busy: Set<string>;
+}
+
+/** What each name a document imports binds to, following `import { … }` and `* as`. */
+function bindingsOf(args: { document: Document; uri: string; state: State }): Map<string, Type> {
+  const out = new Map<string, Type>();
+  for (const decl of args.document.imports) {
+    if (!ast.isValueImport(decl)) continue;
+    const published = isPackageSpecifier(decl.path)
+      ? packageTypes(decl.path, args.state)
+      : publishedBy(args.state.resolve(args.uri, decl.path), args.state);
+    if (decl.wildcard) out.set(decl.wildcard, record(published));
+    else for (const name of decl.names) take(out, published, name);
+  }
+  return out;
+}
+
+function take(out: Map<string, Type>, published: ReadonlyMap<string, Type>, name: string): void {
+  const found = published.get(name);
+  if (found) out.set(name, found);
+}
+
+/**
+ * What an installed package publishes, as this language's types.
+ *
+ * Derived elsewhere, by whoever can read a `.d.ts`, and handed over already
+ * converted, so the checker stays a checker and never learns what npm is.
+ */
+function packageTypes(spec: string, state: State): ReadonlyMap<string, Type> {
+  const found = state.packages?.get(spec);
+  if (!found) return new Map();
+  // A package's types name nothing of this language's, so a reference in one is
+  // a name from a `.d.ts` that did not survive the conversion: `dynamic`.
+  const unknown: ResolveRef = () => undefined;
+  return new Map(Object.entries(found).map(([name, one]) => [name, specToType(one, unknown)]));
+}
+
+/**
+ * The types a module publishes, checked once.
+ *
+ * A module already being checked answers with nothing rather than looping: two
+ * files that call each other cannot both be inferred from the other, and the
+ * honest answer for the second is that its signature is not yet known. Whatever
+ * it declared outright is still read on its own next time round.
+ */
+function publishedBy(uri: string, state: State): ReadonlyMap<string, Type> {
+  const cached = state.done.get(uri);
+  if (cached) return cached;
+  const module = state.modules.get(uri);
+  if (!module || state.busy.has(uri)) return new Map();
+  state.busy.add(uri);
+  const out = exportedTypes(module, uri, state);
+  state.busy.delete(uri);
+  state.done.set(uri, out);
+  return out;
+}
+
+function exportedTypes(module: Document, uri: string, state: State): Map<string, Type> {
+  const imports = bindingsOf({ document: module, uri, state });
+  const checked = checkTypes(module, { uri, catalog: state.catalog, imports });
+  const out = new Map<string, Type>();
+  for (const decl of module.decls) {
+    if (!ast.isFnDecl(decl) || !decl.export) continue;
+    const found = checked.types.get(decl);
+    if (found) out.set(decl.name, found);
+  }
+  return out;
+}

package/src/typecheck/index.ts

@@ -0,0 +1,26 @@
+export type { BuiltinType } from "./builtin-types.js";
+export { BUILTIN_TYPES, isBuiltinType } from "./builtin-types.js";
+export { memberType, resolveMember } from "./builtins.js";
+export type { TypeCatalog } from "./catalog.types.js";
+export type { CheckTypesOptions, CheckTypesResult } from "./check-types.js";
+export { checkTypes } from "./check-types.js";
+export { createContext } from "./context.js";
+export { type ImportedTypes, importedTypes } from "./imported-types.js";
+export { KIND_SPECS, KIND_TYPES } from "./kind-types.js";
+export type { MemberDoc } from "./member-docs.js";
+export { MEMBER_DOCS, memberKind } from "./member-docs.js";
+export type { PreludeArg, PreludeSpec } from "./prelude-types.js";
+export { isPrelude, PRELUDE_SPECS } from "./prelude-types.js";
+export { showType, showTypes } from "./show.js";
+export type { ResolveRef } from "./spec-to-type.js";
+export { specToType } from "./spec-to-type.js";
+export type {
+  FnType,
+  LiteralType,
+  OpaqueType,
+  RecordType,
+  Type,
+  UnionType,
+} from "./type.types.js";
+export { DYNAMIC, literal, opaque, union } from "./type.types.js";
+export { prune } from "./unify.js";