@telorun/cel 0.0.0-stage → 0.107.0

package/src/function-catalog.ts

@@ -0,0 +1,140 @@
+/**
+ * Loading the function catalog into an environment.
+ *
+ * The catalog is the **dialect**: the functions a manifest may call beside CEL's own
+ * library. Like the standard library it is **data** (`signatures/function-catalog.json`)
+ * read through the same registration surface a host uses — here literally the public one,
+ * `CelEnvironment.registerFunction`, with no privileged door of any kind. A host may
+ * register the catalog, leave it out, replace one of its signatures or remove a name, and
+ * nothing in the engine behaves differently for it.
+ *
+ * **One surface, read by everything that lists the catalog.** `functionCatalog()` answers
+ * each function with its display signature, its category, its summary and its two flags,
+ * which is exactly what a `functions` listing prints; a consumer never reconstructs that
+ * from registrations.
+ *
+ * What a function DOES is beside it, per runtime — `catalog-runtime.ts`, keyed by the same
+ * dispatch key the registry resolves on. A declared signature with no behaviour there is
+ * refused at registration rather than at evaluation, which is the failure class the two
+ * artifacts exist to remove.
+ */
+
+import data from "./signatures/function-catalog.json" with { type: "json" };
+import type { CelCatalogHandlers } from "./catalog-runtime.js";
+import { catalogImplementation, catalogLiteralCheck } from "./catalog-runtime.js";
+import type { CelEnvironment } from "./environment.js";
+import { parseSignature, signatureKey } from "./signature.js";
+
+interface CatalogEntryData {
+  readonly name: string;
+  readonly signature: string;
+  readonly signatures: readonly string[];
+  readonly category: string;
+  readonly summary: string;
+  readonly deterministic: boolean;
+  readonly hostBacked: boolean;
+  readonly checksLiteralArguments?: boolean;
+}
+
+interface CatalogData {
+  readonly generation: number;
+  readonly spec: boolean;
+  readonly reason: string;
+  readonly categories: readonly string[];
+  readonly functions: readonly CatalogEntryData[];
+}
+
+const DATA = data as unknown as CatalogData;
+
+export const FUNCTION_CATALOG_GENERATION = DATA.generation;
+
+/** The categories the catalog groups its functions under, for a grouped listing. */
+export function catalogCategories(): readonly string[] {
+  return DATA.categories;
+}
+
+/** One function of the catalog, as a listing prints it. */
+export interface CatalogFunction {
+  readonly name: string;
+  /**
+   * The signature a human reads, which is not always one registration: an optional
+   * parameter is written `fn(string?): string` and registers one signature per arity.
+   */
+  readonly signature: string;
+  /** Every signature the function registers, in registration order. */
+  readonly signatures: readonly string[];
+  readonly category: string;
+  readonly summary: string;
+  /** False where two calls with the same arguments may answer differently. */
+  readonly deterministic: boolean;
+  /** Whether the implementation is the host's rather than the engine's. */
+  readonly hostBacked: boolean;
+  /** Whether the function refuses an argument written as a literal, at check. */
+  readonly checksLiteralArguments: boolean;
+}
+
+/** The catalog, as the one surface a listing reads. */
+export function functionCatalog(): readonly CatalogFunction[] {
+  return DATA.functions.map((entry) => ({
+    name: entry.name,
+    signature: entry.signature,
+    signatures: entry.signatures,
+    category: entry.category,
+    summary: entry.summary,
+    deterministic: entry.deterministic,
+    hostBacked: entry.hostBacked,
+    checksLiteralArguments: entry.checksLiteralArguments ?? false,
+  }));
+}
+
+/** Every signature the catalog registers, for a validator and for a docs listing. */
+export function catalogSignatures(): readonly string[] {
+  return DATA.functions.flatMap((entry) => entry.signatures);
+}
+
+export interface RegisterCatalogOptions {
+  /**
+   * The implementations of the nine host-backed functions. Each may be left out — the
+   * registration is still made, so an expression calling it still type-checks, and
+   * evaluating one answers an `unbound_function` error naming the function. That is what
+   * a consumer which only ever CHECKS (an analyzer, an editor) needs.
+   */
+  readonly handlers?: Partial<CelCatalogHandlers>;
+}
+
+/**
+ * Registers the catalog onto an environment, through the public registration surface.
+ *
+ * A signature the runtime table does not answer for is refused here: a declaration with
+ * no behaviour type-checks and then fails at evaluation, which is precisely the failure
+ * the declaration/behaviour split exists to catch at registration instead.
+ */
+export function registerFunctionCatalog(
+  environment: CelEnvironment,
+  options: RegisterCatalogOptions = {},
+): void {
+  const handlers = options.handlers ?? {};
+  for (const entry of DATA.functions) {
+    const check = entry.checksLiteralArguments ? catalogLiteralCheck(entry.name) : undefined;
+    if (entry.checksLiteralArguments && check === undefined) {
+      throw new Error(
+        `the catalog declares that ${entry.name} checks its literal arguments, and no guard answers for it`,
+      );
+    }
+    for (const signature of entry.signatures) {
+      const key = signatureKey(parseSignature(signature));
+      const implementation = catalogImplementation(key, handlers);
+      if (implementation === undefined) {
+        throw new Error(`the catalog declares ${signature} and nothing implements ${key}`);
+      }
+      environment.registerFunction(signature, {
+        implementation,
+        deterministic: entry.deterministic,
+        hostBacked: entry.hostBacked,
+        description: entry.summary,
+        origin: "function-catalog",
+        ...(check === undefined ? {} : { checkArguments: check }),
+      });
+    }
+  }
+}

package/src/function-registry.ts

@@ -0,0 +1,229 @@
+/**
+ * Which functions an environment has, and which one a call resolves to.
+ *
+ * **Nothing here is privileged.** The standard library registers through exactly this
+ * surface, so a host can replace one of its signatures or remove it — the capability
+ * the whole package exists for. Registration is last-wins by dispatch key
+ * (`signature.ts`), removal is by the same key, and both are per environment: a
+ * clone inherits and may then diverge without touching its parent.
+ *
+ * **Resolution answers WHY it failed**, never just "no". A call on a name nothing
+ * registers, a call written in the wrong form, and a call whose arguments no overload
+ * takes are three different mistakes with three different repairs, and the engine
+ * being replaced reported one sentence for all three — which is why a separate
+ * classifier had to re-derive the cause after the fact. The checker decides it here,
+ * once, with the candidates it considered.
+ */
+
+import type { CelType } from "./cel-type.js";
+import { assignable, DYN, formatType, isDyn } from "./cel-type.js";
+import type { CallForm, CelSignature, FunctionMetadata } from "./signature.js";
+import { formatSignature, signatureKey } from "./signature.js";
+
+export interface RegisteredFunction {
+  readonly signature: CelSignature;
+  readonly metadata: FunctionMetadata;
+}
+
+export type ResolutionFailure =
+  /** No function of that name is registered, in any form. */
+  | { readonly reason: "unknown"; readonly candidates: readonly RegisteredFunction[] }
+  /** The name is registered, but only in the other call form. */
+  | { readonly reason: "wrong-form"; readonly candidates: readonly RegisteredFunction[] }
+  /** The name and form are registered; no overload takes these arguments. */
+  | { readonly reason: "no-overload"; readonly candidates: readonly RegisteredFunction[] };
+
+export interface Resolution {
+  readonly resolved: RegisteredFunction;
+  /** The return type with every type parameter substituted by what this call bound. */
+  readonly returns: CelType;
+}
+
+export class FunctionRegistry {
+  private readonly byName: Map<string, RegisteredFunction[]>;
+
+  constructor(inherited?: FunctionRegistry) {
+    this.byName = new Map();
+    if (inherited) {
+      for (const [name, entries] of inherited.byName) this.byName.set(name, [...entries]);
+    }
+  }
+
+  /** Registers a function, replacing any registration answering the same call. */
+  register(signature: CelSignature, metadata: FunctionMetadata = {}): void {
+    const entries = this.byName.get(signature.name) ?? [];
+    const key = signatureKey(signature);
+    const at = entries.findIndex((entry) => signatureKey(entry.signature) === key);
+    const entry: RegisteredFunction = { signature, metadata };
+    if (at === -1) entries.push(entry);
+    else entries[at] = entry;
+    this.byName.set(signature.name, entries);
+  }
+
+  /** Removes the one registration answering that call. Answers whether it was there. */
+  remove(signature: CelSignature): boolean {
+    const entries = this.byName.get(signature.name);
+    if (!entries) return false;
+    const key = signatureKey(signature);
+    const at = entries.findIndex((entry) => signatureKey(entry.signature) === key);
+    if (at === -1) return false;
+    entries.splice(at, 1);
+    if (entries.length === 0) this.byName.delete(signature.name);
+    return true;
+  }
+
+  /** Removes every registration of a name. Answers how many went. */
+  removeName(name: string): number {
+    const entries = this.byName.get(name);
+    if (!entries) return 0;
+    this.byName.delete(name);
+    return entries.length;
+  }
+
+  has(name: string): boolean {
+    return this.byName.has(name);
+  }
+
+  /** Every registration, in name order then registration order. */
+  list(): readonly RegisteredFunction[] {
+    return [...this.byName.keys()].sort().flatMap((name) => this.byName.get(name)!);
+  }
+
+  named(name: string): readonly RegisteredFunction[] {
+    return this.byName.get(name) ?? [];
+  }
+
+  /**
+   * The function a call resolves to. `receiver` is the type the call is written on,
+   * absent for a global call.
+   */
+  resolve(
+    name: string,
+    form: CallForm,
+    args: readonly CelType[],
+    receiver?: CelType,
+  ): Resolution | ResolutionFailure {
+    const all = this.byName.get(name);
+    if (!all || all.length === 0) return { reason: "unknown", candidates: [] };
+    const inForm = all.filter((entry) => entry.signature.form === form);
+    if (inForm.length === 0) return { reason: "wrong-form", candidates: all };
+
+    const arity = inForm.filter((entry) => entry.signature.parameters.length === args.length);
+    const viable = arity.length === 0 ? inForm : arity;
+    // Exact first, then a candidate `dyn` makes viable, which is what keeps an
+    // unlisted variable from turning one mistake into two.
+    const exact = this.match(viable, args, receiver, false);
+    if (exact) return exact;
+    const loose = this.match(viable, args, receiver, true);
+    if (loose) return loose;
+    return { reason: "no-overload", candidates: inForm };
+  }
+
+  private match(
+    candidates: readonly RegisteredFunction[],
+    args: readonly CelType[],
+    receiver: CelType | undefined,
+    allowDyn: boolean,
+  ): Resolution | undefined {
+    for (const candidate of candidates) {
+      const { signature } = candidate;
+      if (signature.parameters.length !== args.length) continue;
+      const bindings = new Map<string, CelType>();
+      if (signature.receiver && !this.fits(receiver ?? DYN, signature.receiver, bindings, allowDyn)) continue;
+      if (!signature.parameters.every((want, at) => this.fits(args[at]!, want, bindings, allowDyn))) continue;
+      return { resolved: candidate, returns: substitute(signature.returns, bindings) };
+    }
+    return undefined;
+  }
+
+  /**
+   * Whether an argument fits a parameter, binding type parameters as it goes.
+   *
+   * **A type parameter is bound by the first argument that mentions it**, and a later
+   * argument does not refine it: `[] + [3, 4]` is `list<T>`, because the empty list
+   * fixed the element type as "unknown" and the second argument cannot retroactively
+   * decide what the first one held.
+   */
+  private fits(
+    argument: CelType,
+    parameter: CelType,
+    bindings: Map<string, CelType>,
+    allowDyn: boolean,
+  ): boolean {
+    if (parameter.kind === "parameter") {
+      const bound = bindings.get(parameter.name);
+      if (!bound) {
+        bindings.set(parameter.name, argument);
+        return true;
+      }
+      // A binding that holds an unresolved parameter holds no information, so a later
+      // concrete argument refines it: `optional.none().orValue(42)` is an int.
+      if (bound.kind === "parameter" && argument.kind !== "parameter") {
+        bindings.set(parameter.name, argument);
+        return true;
+      }
+      if (bound.kind === "parameter" || argument.kind === "parameter") return true;
+      return assignable(argument, bound) || (allowDyn && (isDyn(argument) || isDyn(bound)));
+    }
+    if (parameter.kind === "list" && argument.kind === "list") {
+      return this.fits(argument.element, parameter.element, bindings, allowDyn);
+    }
+    if (parameter.kind === "map" && argument.kind === "map") {
+      return (
+        this.fits(argument.key, parameter.key, bindings, allowDyn) &&
+        this.fits(argument.value, parameter.value, bindings, allowDyn)
+      );
+    }
+    if (parameter.kind === "optional" && argument.kind === "optional") {
+      return this.fits(argument.value, parameter.value, bindings, allowDyn);
+    }
+    if (
+      parameter.kind === "nominal" &&
+      argument.kind === "nominal" &&
+      parameter.name === argument.name &&
+      parameter.args.length === argument.args.length
+    ) {
+      // A named type's arguments are invariant, so they fit one for one — which is also
+      // where a signature written over `Self` binds its own type parameters.
+      return parameter.args.every((want, at) => this.fits(argument.args[at]!, want, bindings, allowDyn));
+    }
+    if (isDyn(argument)) return allowDyn || isDyn(parameter);
+    return assignable(argument, parameter);
+  }
+}
+
+/** The type with every bound parameter replaced; an unbound one stays as it is. */
+export function substitute(type: CelType, bindings: ReadonlyMap<string, CelType>): CelType {
+  switch (type.kind) {
+    case "parameter":
+      return bindings.get(type.name) ?? type;
+    case "list": {
+      const element = substitute(type.element, bindings);
+      return element === type.element ? type : { kind: "list", element };
+    }
+    case "map": {
+      const key = substitute(type.key, bindings);
+      const value = substitute(type.value, bindings);
+      return key === type.key && value === type.value ? type : { kind: "map", key, value };
+    }
+    case "optional": {
+      const value = substitute(type.value, bindings);
+      return value === type.value ? type : { kind: "optional", value };
+    }
+    case "nominal": {
+      const args = type.args.map((argument) => substitute(argument, bindings));
+      return args.every((argument, at) => argument === type.args[at]) ? type : { ...type, args };
+    }
+    default:
+      return type;
+  }
+}
+
+/** How a resolution failure names what it looked at, for a message a human reads. */
+export function describeCandidates(candidates: readonly RegisteredFunction[]): string {
+  return candidates.map((candidate) => formatSignature(candidate.signature)).join(", ");
+}
+
+export function describeArguments(args: readonly CelType[]): string {
+  return args.map((type) => formatType(type)).join(", ");
+}