@venn-lang/runtime 0.1.0

package/src/check/check-calls.ts

@@ -0,0 +1,82 @@
+import {
+  type ActionCall,
+  type AstNode,
+  buildProblem,
+  type CaptureStmt,
+  CODES,
+  type LetStmt,
+  type MapLit,
+  type Problem,
+} from "@venn-lang/core";
+import { actionTarget, nodeSpan, PRELUDE, resolveTarget, splitTarget } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+import { checkOptions } from "./check-options.js";
+
+/** `http.get "…"` written as a statement. */
+export function checkAction(call: ActionCall, ctx: CheckContext): Problem[] {
+  return checkTarget({ node: call, target: call.target, opts: call.opts, ctx });
+}
+
+/**
+ * `let auth = http.post url { … }`. Only the unmistakable call is checked: with
+ * no arguments the path could be a field of a variable this pass cannot see, and
+ * a false "unknown action" is worse than a missed one.
+ */
+export function checkLet(stmt: LetStmt, ctx: CheckContext): Problem[] {
+  if (stmt.args.length === 0 && !stmt.opts) return [];
+  const target = actionTarget(stmt.value);
+  if (target === undefined) {
+    return [problem(stmt, ctx, CODES.VN2003_UNKNOWN_ACTION, "This is not an action to call.")];
+  }
+  return checkTarget({ node: stmt, target, opts: stmt.opts, ctx });
+}
+
+/** `capture` is folded into `let`; say so where it is written. */
+export function checkCapture(stmt: CaptureStmt, ctx: CheckContext): Problem {
+  const title =
+    "`capture` was removed — use `let` for a value that changes, `const` for one that does not.";
+  return problem(stmt, ctx, CODES.VN5001_REMOVED_KEYWORD, title);
+}
+
+/**
+ * A namespace is only usable when this file brought it in with `use` (or it is
+ * a resource). Loading the whole stdlib must not make `use` optional.
+ */
+function checkTarget(args: {
+  node: AstNode;
+  target: string;
+  opts: MapLit | undefined;
+  ctx: CheckContext;
+}): Problem[] {
+  const { node, target, ctx } = args;
+  if (PRELUDE.has(target)) return [];
+  const written = splitTarget(target).namespace;
+  if (ctx.bound.has(written)) return [];
+  if (!ctx.imported.has(written)) return [missingImport(args, written)];
+  const resolved = ctx.registry.action(resolveTarget(target, ctx.aliases));
+  if (!resolved) {
+    return [problem(node, ctx, CODES.VN2003_UNKNOWN_ACTION, `Unknown action "${target}".`)];
+  }
+  return checkOptions({ opts: args.opts, params: resolved.action.params, ctx });
+}
+
+function missingImport(
+  args: { node: AstNode; target: string; ctx: CheckContext },
+  namespace: string,
+): Problem {
+  if (!args.ctx.registry.hasNamespace(namespace)) {
+    const title = `Unknown action "${args.target}" — no loaded plugin provides it.`;
+    return problem(args.node, args.ctx, CODES.VN2003_UNKNOWN_ACTION, title);
+  }
+  const title = `"${namespace}" is not imported in this file — add a \`use\` for its package.`;
+  return problem(args.node, args.ctx, CODES.VN2007_NAMESPACE_NOT_IMPORTED, title);
+}
+
+function problem(
+  node: AstNode,
+  ctx: CheckContext,
+  spec: (typeof CODES)[keyof typeof CODES],
+  title: string,
+): Problem {
+  return buildProblem({ spec, span: nodeSpan(node, ctx.uri), title });
+}

package/src/check/check-deco-body.ts

@@ -0,0 +1,77 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  type DecoDecl,
+  decoCannotCall,
+  isActionCall,
+  isDecoDecl,
+  isLetStmt,
+  type Problem,
+} from "@venn-lang/core";
+import { actionTarget, nodeSpan, PRELUDE, splitTarget } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+
+/**
+ * Check a node written inside a `deco` body, which is not the program and so is
+ * not resolved against the registry: `target.wrap(f)` is a verb on the handle
+ * the body was handed, and expansion settles what the rest means. The one
+ * refusal this pass can make is a verb from a plugin, which cannot work in a
+ * `deco` because a decorator runs before the program exists.
+ *
+ * @returns The node's problems, or `undefined` when the node is not inside a
+ * `deco`, which tells the caller to apply the ordinary document checks instead.
+ */
+export function checkInsideDeco(node: AstNode, ctx: CheckContext): Problem[] | undefined {
+  const deco = enclosingDeco(node);
+  if (!deco) return undefined;
+  const target = calledTarget(node);
+  const refused = target === undefined ? undefined : pluginVerb({ deco, target, ctx });
+  return refused ? [problem(node, ctx, refused)] : [];
+}
+
+/** The `deco` this node is written inside, if any. */
+function enclosingDeco(node: AstNode): DecoDecl | undefined {
+  for (let at: AstNode | undefined = node; at; at = at.$container) {
+    if (isDecoDecl(at)) return at;
+  }
+  return undefined;
+}
+
+/** The dotted name this statement calls, if calling is what it does. */
+function calledTarget(node: AstNode): string | undefined {
+  if (isActionCall(node)) return node.target;
+  if (!isLetStmt(node) || (node.args.length === 0 && !node.opts)) return undefined;
+  return actionTarget(node.value);
+}
+
+/**
+ * Why this call cannot be made from here, if it cannot. Only a head the file can
+ * already account for is refused: an imported namespace, a resource, a namespace
+ * some loaded plugin owns. Anything else is a name only expansion resolves, and
+ * guessing at it would put an error on every well-written decorator.
+ */
+function pluginVerb(args: {
+  deco: DecoDecl;
+  target: string;
+  ctx: CheckContext;
+}): string | undefined {
+  const { namespace } = splitTarget(args.target);
+  if (PRELUDE.has(args.target) || paramNames(args.deco).has(namespace)) return undefined;
+  if (!reachesTheWorld(namespace, args.ctx)) return undefined;
+  return decoCannotCall(args.target);
+}
+
+function reachesTheWorld(namespace: string, ctx: CheckContext): boolean {
+  return (
+    ctx.imported.has(namespace) || ctx.bound.has(namespace) || ctx.registry.hasNamespace(namespace)
+  );
+}
+
+function paramNames(deco: DecoDecl): Set<string> {
+  return new Set((deco.params?.params ?? []).map((param) => param.name));
+}
+
+function problem(node: AstNode, ctx: CheckContext, title: string): Problem {
+  return buildProblem({ spec: CODES.VN2016_DECO_IMPURE, span: nodeSpan(node, ctx.uri), title });
+}

package/src/check/check-document.ts

@@ -0,0 +1,106 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  isActionCall,
+  isCall,
+  isCaptureStmt,
+  isLetStmt,
+  isMatcherClause,
+  isRunStmt,
+  type MatcherClause,
+  type Problem,
+  type RunStmt,
+  walkAst,
+} from "@venn-lang/core";
+import {
+  collectAliases,
+  collectBoundNames,
+  collectNamespaces,
+  nodeSpan,
+} from "../scheduler/index.js";
+import type { CheckArgs, CheckContext } from "./check.types.js";
+import { checkAction, checkCapture, checkLet } from "./check-calls.js";
+import { checkInsideDeco } from "./check-deco-body.js";
+import { checkEnv } from "./check-env.js";
+import { checkFragmentCall } from "./check-fragment-call.js";
+import { checkInterpolation } from "./check-interpolation.js";
+import { checkUncalledAction } from "./check-uncalled.js";
+
+/**
+ * Statically resolve every action, matcher and fragment reference in a parsed
+ * document. The errors the runner would otherwise raise mid-run are surfaced all
+ * at once, each with its source span.
+ *
+ * @param args Document, registry, known fragments and the declared `env` names.
+ * @returns One `Problem` per unresolved reference; empty when the document is clean.
+ */
+export function checkDocument(args: CheckArgs): Problem[] {
+  const ctx: CheckContext = {
+    registry: args.registry,
+    fragments: args.fragments,
+    aliases: collectAliases(args.document, args.registry),
+    imported: collectNamespaces(args.document, args.registry),
+    bound: collectBoundNames(args.document),
+    env: args.env ? new Set(args.env) : undefined,
+    uri: args.uri ?? "memory://inline.vn",
+  };
+  const problems: Problem[] = [];
+  for (const node of walkAst(args.document)) {
+    const inDeco = checkInsideDeco(node, ctx);
+    if (inDeco) problems.push(...inDeco);
+    else problems.push(...everyCheck(node, ctx));
+  }
+  return problems;
+}
+
+function everyCheck(node: AstNode, ctx: CheckContext): Problem[] {
+  return [
+    ...checkNode(node, ctx),
+    ...checkEnv(node, ctx),
+    ...checkInterpolation(node, ctx),
+    ...one(checkUncalledAction(node, ctx)),
+  ];
+}
+
+function checkNode(node: AstNode, ctx: CheckContext): Problem[] {
+  if (isActionCall(node)) return checkAction(node, ctx);
+  if (isLetStmt(node)) return checkLet(node, ctx);
+  if (isCaptureStmt(node)) return [checkCapture(node, ctx)];
+  if (isMatcherClause(node)) return one(checkMatcher(node, ctx));
+  if (isRunStmt(node)) return one(checkFragment(node, ctx));
+  if (isCall(node)) return one(checkFragmentCall(node, ctx));
+  return [];
+}
+
+function one(problem: Problem | undefined): Problem[] {
+  return problem ? [problem] : [];
+}
+
+/**
+ * A matcher comes from a plugin like any action, so the file has to bring that
+ * plugin in. Resolving against the whole loaded stdlib would make `use` decorative.
+ */
+function checkMatcher(clause: MatcherClause, ctx: CheckContext): Problem | undefined {
+  const owner = ctx.registry.matcher(clause.name);
+  if (!owner) {
+    return problem(clause, ctx, CODES.VN2004_UNKNOWN_MATCHER, `Unknown matcher "${clause.name}".`);
+  }
+  if (ctx.imported.has(owner.plugin.namespace)) return undefined;
+  const title = `"${clause.name}" comes from "${owner.plugin.namespace}", which is not imported in this file.`;
+  return problem(clause, ctx, CODES.VN2007_NAMESPACE_NOT_IMPORTED, title);
+}
+
+function checkFragment(stmt: RunStmt, ctx: CheckContext): Problem | undefined {
+  if (ctx.fragments.has(stmt.target)) return undefined;
+  return problem(stmt, ctx, CODES.VN2005_UNKNOWN_FRAGMENT, `Unknown fragment "${stmt.target}".`);
+}
+
+function problem(
+  node: AstNode,
+  ctx: CheckContext,
+  spec: (typeof CODES)[keyof typeof CODES],
+  title: string,
+): Problem {
+  return buildProblem({ spec, span: nodeSpan(node, ctx.uri), title });
+}

package/src/check/check-env.ts

@@ -0,0 +1,96 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  isMember,
+  type Problem,
+  type Span,
+} from "@venn-lang/core";
+import { actionTarget, nodeSpan } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+
+/** `env.NAME` as it appears inside a `${…}` placeholder. */
+const ENV_READ = /\benv\.([A-Za-z_]\w*)/g;
+
+/** Always present: the runner sets it to the `--env` that was selected. */
+const BUILT_IN = new Set(["name"]);
+
+/**
+ * Match every `env.*` read against what `venn.toml` declares, so a typo is an
+ * error rather than an empty string and a puzzling 404.
+ *
+ * Nothing is reported when the manifest could not be read: a wrong error about a
+ * variable that does exist is worse than no error at all.
+ */
+export function checkEnv(node: AstNode, ctx: CheckContext): Problem[] {
+  if (!isMember(node) || isMember(node.$container)) return [];
+  const path = actionTarget(node);
+  const name = path?.startsWith("env.") ? path.slice(4) : undefined;
+  if (name === undefined || name.includes(".")) return [];
+  const span = nodeSpan(node, ctx.uri);
+  if (!ctx.imported.has("env")) return [notImported(span)];
+  if (!ctx.env || declared(name, ctx.env)) return [];
+  return [envProblem(name, span, ctx)];
+}
+
+/**
+ * Configuration is brought in like anything else. Reading `env.*` without saying
+ * where it comes from is the same hole `use` closes for actions and matchers:
+ * the reader should not have to know which names are magic.
+ */
+function notImported(span: Span): Problem {
+  return buildProblem({
+    spec: CODES.VN2007_NAMESPACE_NOT_IMPORTED,
+    span,
+    title: '"env" is not imported in this file — add `use "venn/env"`.',
+  });
+}
+
+/** The same checks for text the parser never turned into nodes: `"${env.X}"`. */
+export function envProblemsIn(source: string, span: Span, ctx: CheckContext): Problem[] {
+  const names = [...source.matchAll(ENV_READ)].map((match) => match[1] ?? "").filter(Boolean);
+  if (names.length === 0) return [];
+  if (!ctx.imported.has("env")) return [notImported(span)];
+  const env = ctx.env;
+  if (!env) return [];
+  return names.filter((name) => !declared(name, env)).map((name) => envProblem(name, span, ctx));
+}
+
+function declared(name: string, env: ReadonlySet<string>): boolean {
+  return env.has(name) || BUILT_IN.has(name);
+}
+
+/** The undeclared-variable problem, with the nearest declared name as a hint. */
+export function envProblem(name: string, span: Span, ctx: CheckContext): Problem {
+  const hint = nearest(name, [...(ctx.env ?? [])]);
+  const title = hint
+    ? `"env.${name}" is not declared in venn.toml — did you mean "env.${hint}"?`
+    : `"env.${name}" is not declared in venn.toml.`;
+  return buildProblem({ spec: CODES.VN2006_UNKNOWN_ENV, span, title });
+}
+
+function nearest(name: string, known: readonly string[]): string | undefined {
+  const best = known
+    .map((candidate) => ({ candidate, distance: distance(name, candidate) }))
+    .sort((left, right) => left.distance - right.distance)[0];
+  const tolerance = Math.max(2, Math.floor(name.length / 3));
+  return best && best.distance <= tolerance ? best.candidate : undefined;
+}
+
+/** Levenshtein edit distance, kept to two rows because only the score is needed. */
+function distance(left: string, right: string): number {
+  let previous = Array.from({ length: right.length + 1 }, (_value, index) => index);
+  for (let i = 1; i <= left.length; i += 1) {
+    const current = [i];
+    for (let j = 1; j <= right.length; j += 1) {
+      const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+      current[j] = Math.min(
+        (current[j - 1] ?? 0) + 1,
+        (previous[j] ?? 0) + 1,
+        (previous[j - 1] ?? 0) + cost,
+      );
+    }
+    previous = current;
+  }
+  return previous[right.length] ?? 0;
+}

package/src/check/check-fragment-call.ts

@@ -0,0 +1,27 @@
+import { buildProblem, type Call, CODES, isRef, type Problem } from "@venn-lang/core";
+import { nodeSpan } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+
+/**
+ * Refuse a fragment called as though it were a function.
+ *
+ * The two look alike where they are written but are different kinds of thing: a
+ * `fn` gives back a value, a `fragment` gives back steps, and steps are recorded
+ * in the report, can fail and belong to a flow. So a fragment is invoked with
+ * `run`. `run entrar(…)` never reaches here: its target is a name, not an
+ * expression.
+ *
+ * @param call The call expression to inspect.
+ * @param ctx The document's resolved check context.
+ * @returns A `VN3013` problem, or `undefined` when the callee is not a fragment.
+ */
+export function checkFragmentCall(call: Call, ctx: CheckContext): Problem | undefined {
+  const callee = call.callee;
+  if (!isRef(callee) || !ctx.fragments.has(callee.name)) return undefined;
+  return buildProblem({
+    spec: CODES.VN3013_NOT_CALLABLE,
+    span: nodeSpan(call, ctx.uri),
+    title: `${callee.name} is a fragment, so it cannot be called for a value.`,
+    note: `Invoke it with \`run ${callee.name}(…)\`, which records its steps in the report.`,
+  });
+}

package/src/check/check-imports.ts

@@ -0,0 +1,82 @@
+import {
+  buildProblem,
+  CODES,
+  type Document,
+  isDecoDecl,
+  isFnDecl,
+  isFragmentDecl,
+  isValueImport,
+  type Problem,
+  type ValueImport,
+} from "@venn-lang/core";
+import type { ImportGraph } from "../scheduler/index.js";
+import { nodeSpan } from "../scheduler/index.js";
+
+/**
+ * Check every name a file imports against what the file it names publishes.
+ * Otherwise a misspelt import stays quietly `undefined` until something calls
+ * it, and the run blames the call site rather than the import.
+ *
+ * @param args The importing document, its URI, and the resolved import graph.
+ * @returns One `VN2009` problem per name the target does not publish.
+ */
+export function checkImports(args: {
+  document: Document;
+  uri: string;
+  graph: ImportGraph;
+}): Problem[] {
+  const problems: Problem[] = [];
+  for (const decl of args.document.imports) {
+    if (!isValueImport(decl)) continue;
+    const target = args.graph.resolve(args.uri, decl.path);
+    const module = args.graph.modules.get(target);
+    // A path that reads nothing is already reported by whoever tried to read it.
+    if (module) problems.push(...missing({ decl, module, uri: args.uri, path: decl.path }));
+  }
+  return problems;
+}
+
+function missing(args: {
+  decl: ValueImport;
+  module: Document;
+  uri: string;
+  path: string;
+}): Problem[] {
+  const published = exported(args.module);
+  return args.decl.names
+    .filter((name) => !published.has(name))
+    .map((name) =>
+      buildProblem({
+        spec: CODES.VN2009_NOT_EXPORTED,
+        span: nodeSpan(args.decl, args.uri),
+        title: `"${args.path}" does not publish ${name}.`,
+        note: hint(name, args.module),
+      }),
+    );
+}
+
+/**
+ * Why it is not there: written but kept private, or not written at all. The two
+ * are different mistakes with different fixes, and a reader told only "not
+ * published" goes looking for a typo they did not make.
+ */
+function hint(name: string, module: Document): string {
+  const declared = module.decls.some(
+    (decl) =>
+      (isFnDecl(decl) || isFragmentDecl(decl) || isDecoDecl(decl)) &&
+      (decl as { name?: string }).name === name,
+  );
+  return declared
+    ? `It is declared there, but not marked \`pub\`.`
+    : `Nothing of that name is declared there.`;
+}
+
+/** Everything a file marked `pub`: functions, fragments and decorators alike. */
+function exported(document: Document): Set<string> {
+  const names = new Set<string>();
+  for (const decl of document.decls) {
+    if (!isFnDecl(decl) && !isFragmentDecl(decl) && !isDecoDecl(decl)) continue;
+    if (decl.export) names.add(decl.name);
+  }
+  return names;
+}

package/src/check/check-interpolation.ts

@@ -0,0 +1,58 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  type InterpolationSlot,
+  isStringLit,
+  type Problem,
+  parseExpression,
+  type Span,
+  scanInterpolations,
+} from "@venn-lang/core";
+import type { CheckContext } from "./check.types.js";
+import { envProblemsIn } from "./check-env.js";
+
+/**
+ * Check each `${…}` placeholder in a string literal and point at the placeholder
+ * itself, not at the whole string. A slot that does not parse would otherwise
+ * evaluate to an empty string, so a typo inside a URL fails as a puzzling 404.
+ */
+export function checkInterpolation(node: AstNode, ctx: CheckContext): Problem[] {
+  const cst = node.$cstNode;
+  if (!isStringLit(node) || !cst) return [];
+  return scanInterpolations(cst.text).flatMap((slot) =>
+    inSlot(slot, spanOf(slot, { cst, uri: ctx.uri }), ctx),
+  );
+}
+
+/** A URL is where `env` reads live, so they are checked here as well as in the AST. */
+function inSlot(slot: InterpolationSlot, span: Span, ctx: CheckContext): Problem[] {
+  if (!parseExpression(slot.source)) return [unreadable(slot, span)];
+  return envProblemsIn(slot.source, span, ctx);
+}
+
+function unreadable(slot: InterpolationSlot, span: Span): Problem {
+  return buildProblem({
+    spec: CODES.VN1002_PARSE,
+    span,
+    title: `Cannot read \`\${${slot.source}}\` — that is not an expression.`,
+  });
+}
+
+/** The span of the placeholder itself: line and column follow the string's own start. */
+function spanOf(
+  slot: InterpolationSlot,
+  target: {
+    cst: { offset: number; range?: { start: { line: number; character: number } } };
+    uri: string;
+  },
+): Span {
+  const start = target.cst.range?.start;
+  return {
+    uri: target.uri,
+    offset: target.cst.offset + slot.start,
+    length: slot.end - slot.start,
+    line: (start?.line ?? 0) + 1,
+    column: (start?.character ?? 0) + 1 + slot.start,
+  };
+}

package/src/check/check-options.ts

@@ -0,0 +1,18 @@
+import type { MapLit, Problem } from "@venn-lang/core";
+import { unknownOptions } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+
+/**
+ * Check the keys of an options map against the action's own schema.
+ *
+ * The runtime refuses an unknown key too, but only when the flow reaches that
+ * line. Both read the same list and say the same sentence, so the editor can
+ * mark the word before anything runs.
+ */
+export function checkOptions(args: {
+  opts: MapLit | undefined;
+  params: unknown;
+  ctx: CheckContext;
+}): Problem[] {
+  return unknownOptions({ opts: args.opts, params: args.params, uri: args.ctx.uri });
+}

package/src/check/check-uncalled.ts

@@ -0,0 +1,42 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  isCall,
+  isLetStmt,
+  isMember,
+  type Member,
+  type Problem,
+} from "@venn-lang/core";
+import { actionTarget, nodeSpan, resolveTarget } from "../scheduler/index.js";
+import type { CheckContext } from "./check.types.js";
+
+/**
+ * A plugin verb named but never called.
+ *
+ * `let id = data.faker.uuid` runs the verb, because the runtime recognises a
+ * bare path that names an action. The same words inside an expression evaluate
+ * to the verb itself, so a program meaning to read a value gets a function.
+ * Rather than guess which was meant, this asks for the parentheses.
+ */
+export function checkUncalledAction(node: AstNode, ctx: CheckContext): Problem | undefined {
+  if (!isMember(node) || !readsAsValue(node)) return undefined;
+  const target = actionTarget(node);
+  if (target === undefined) return undefined;
+  if (!ctx.registry.action(resolveTarget(target, ctx.aliases))) return undefined;
+  return buildProblem({
+    spec: CODES.VN2008_UNCALLED_ACTION,
+    span: nodeSpan(node, ctx.uri),
+    title: `\`${target}\` is a verb, not a value — write \`${target}()\` to call it.`,
+  });
+}
+
+/**
+ * Where naming the verb produces the verb. Skipped when it is the head of a
+ * longer path or the thing being called, and when it stands as a statement's
+ * value, which the runtime calls anyway.
+ */
+function readsAsValue(node: Member): boolean {
+  const parent = node.$container;
+  return !isMember(parent) && !isCall(parent) && !isLetStmt(parent);
+}

package/src/check/check.types.ts

@@ -0,0 +1,30 @@
+import type { Document } from "@venn-lang/core";
+import type { Registry } from "../registry/index.js";
+
+/** Inputs to a static name-resolution pass over a parsed document. */
+export interface CheckArgs {
+  document: Document;
+  registry: Registry;
+  fragments: ReadonlySet<string>;
+  uri?: string;
+  /**
+   * The variables `venn.toml` declares. Omit it when they are unknown: an
+   * undeclared-variable error is only worth raising when the declaration list is
+   * trustworthy.
+   */
+  env?: readonly string[];
+}
+
+/** Everything a per-node check needs, resolved once per document. */
+export interface CheckContext {
+  registry: Registry;
+  fragments: ReadonlySet<string>;
+  aliases: ReadonlyMap<string, string>;
+  /** Namespaces this file actually brought in with `use`. */
+  imported: ReadonlySet<string>;
+  /** Names this file binds: callable, but their methods cannot be verified. */
+  bound: ReadonlySet<string>;
+  /** Declared `env` variables, or undefined when the manifest could not be read. */
+  env?: ReadonlySet<string>;
+  uri: string;
+}

package/src/check/index.ts

@@ -0,0 +1,4 @@
+export type { CheckArgs } from "./check.types.js";
+export { checkDocument } from "./check-document.js";
+export { checkFragmentCall } from "./check-fragment-call.js";
+export { checkImports } from "./check-imports.js";

package/src/context/action-context.ts

@@ -0,0 +1,20 @@
+import type { Host, Port } from "@venn-lang/contracts";
+import { invoke } from "@venn-lang/core";
+import type { ActionContext } from "@venn-lang/sdk";
+import type { PortResolver } from "../ports/index.js";
+
+/** Build the context an action's `run` receives from the host and port resolver. */
+export function createActionContext(args: {
+  host: Host;
+  ports: PortResolver;
+  config?: Record<string, unknown>;
+}): ActionContext {
+  return {
+    port: <T>(port: Port<T>): T => args.ports.resolve(port),
+    secrets: args.host.secrets,
+    config: args.config ?? {},
+    log: (message) => args.host.log.log({ level: "info", message }),
+    redact: () => {},
+    invoke: (fn, values) => invoke(fn, values),
+  };
+}

package/src/context/index.ts

@@ -0,0 +1 @@
+export { createActionContext } from "./action-context.js";