@telorun/cel 0.0.0-stage → 0.108.0

package/src/nominal-type.ts

@@ -0,0 +1,149 @@
+/**
+ * Named types a host registers — the one mechanism, with none of the vocabulary.
+ *
+ * A nominal type is a name over a base type, with its own operators, comparisons,
+ * conversions and member functions, and with named **invariant** type parameters. It
+ * is not its base: a value of the base does not stand where the named type is wanted,
+ * and only what the definition declares applies to it. That is what makes a named type
+ * worth having — a slot that wants one refuses a plain value of the base, which is
+ * exactly what an engine typing by wrapper class cannot express.
+ *
+ * Invariance is deliberate: `Holder<string>` and `Holder<int>` are unrelated, so a
+ * type argument that differs is a mistake with its own diagnostic rather than a silent
+ * widening to the base.
+ *
+ * `Self` inside a definition names the type being defined, with its own parameters
+ * applied, so a member can answer its own type without repeating it.
+ */
+
+import type { CelType, NominalType } from "./cel-type.js";
+import { parameterOf } from "./cel-type.js";
+import type { NominalResolver } from "./type-expression.js";
+import { parseTypeExpression } from "./type-expression.js";
+
+export interface NominalOperatorDeclaration {
+  readonly operator: string;
+  /** Type expressions; `Self` names the type being defined. */
+  readonly parameters: readonly string[];
+  readonly returns: string;
+}
+
+export interface NominalTypeDefinition {
+  readonly name: string;
+  /** The type expression a value of this type is, underneath. */
+  readonly base: string;
+  /** Invariant type parameter names, each a single capital letter. */
+  readonly parameters?: readonly string[];
+  /** Operators over the type, written with `Self`. */
+  readonly operators?: readonly NominalOperatorDeclaration[];
+  /** Operator symbols to register as `(Self, Self): bool`. */
+  readonly comparisons?: readonly string[];
+  /** Conversion signatures, e.g. `string(Self): string`. */
+  readonly conversions?: readonly string[];
+  /** Member signatures, e.g. `Self.scaled(int): Self`. */
+  readonly members?: readonly string[];
+  readonly description?: string;
+}
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+const PARAMETER = /^[A-Z]$/;
+const LANGUAGE_NAMES = new Set([
+  "dyn",
+  "int",
+  "uint",
+  "double",
+  "bool",
+  "string",
+  "bytes",
+  "null",
+  "null_type",
+  "type",
+  "list",
+  "map",
+  "optional",
+  "timestamp",
+  "duration",
+]);
+
+export class CelTypeRegistrationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CelTypeRegistrationError";
+  }
+}
+
+/** A registered nominal type: its definition, its base, and the type `Self` names. */
+export interface RegisteredType {
+  readonly definition: NominalTypeDefinition;
+  readonly base: CelType;
+  readonly parameters: readonly string[];
+  /** The type with its own parameters applied — what `Self` resolves to. */
+  readonly self: NominalType;
+}
+
+export function validateTypeName(name: string): void {
+  if (!NAME.test(name)) {
+    throw new CelTypeRegistrationError(`${JSON.stringify(name)} is not spelled as a type name`);
+  }
+  if (LANGUAGE_NAMES.has(name)) {
+    throw new CelTypeRegistrationError(`${JSON.stringify(name)} is a type of the language and cannot be redefined`);
+  }
+  if (PARAMETER.test(name)) {
+    throw new CelTypeRegistrationError(
+      `${JSON.stringify(name)} is a single capital letter, which a signature reads as a type parameter`,
+    );
+  }
+}
+
+/**
+ * Builds the registered form of a definition. `resolveNominal` resolves names the
+ * definition's own base or members mention, including itself through `Self`.
+ */
+export function buildRegisteredType(
+  definition: NominalTypeDefinition,
+  resolveNominal: NominalResolver,
+): RegisteredType {
+  validateTypeName(definition.name);
+  const parameters = definition.parameters ?? [];
+  for (const parameter of parameters) {
+    if (!PARAMETER.test(parameter)) {
+      throw new CelTypeRegistrationError(
+        `type parameter ${JSON.stringify(parameter)} of ${definition.name} must be a single capital letter`,
+      );
+    }
+  }
+  const self: NominalType = {
+    kind: "nominal",
+    name: definition.name,
+    base: { kind: "dyn" },
+    args: parameters.map(parameterOf),
+  };
+  const withSelf: NominalResolver = (name, args) =>
+    name === "Self" || name === definition.name
+      ? { ...self, args: args.length > 0 ? args : self.args }
+      : resolveNominal(name, args);
+  let base: CelType;
+  try {
+    base = parseTypeExpression(definition.base, withSelf);
+  } catch (cause) {
+    throw new CelTypeRegistrationError(
+      `the base of ${definition.name} does not read as a type: ${(cause as Error).message}`,
+    );
+  }
+  return { definition, base, parameters, self: { ...self, base } };
+}
+
+/** The signatures a definition declares, as text, in registration order. */
+export function nominalSignatures(definition: NominalTypeDefinition): readonly string[] {
+  return [...(definition.conversions ?? []), ...(definition.members ?? [])];
+}
+
+/** The operator declarations a definition implies, its comparisons expanded. */
+export function nominalOperators(definition: NominalTypeDefinition): readonly NominalOperatorDeclaration[] {
+  const comparisons = (definition.comparisons ?? []).map((operator) => ({
+    operator,
+    parameters: ["Self", "Self"],
+    returns: "bool",
+  }));
+  return [...(definition.operators ?? []), ...comparisons];
+}

package/src/nullable-access.ts

@@ -0,0 +1,95 @@
+/**
+ * Which dereferences a guard has proven safe.
+ *
+ * A value whose declared type admits null is only safely dereferenced where something
+ * has proven it is not null, and **what counts as proof is exactly three constructs**:
+ * a ternary, `&&` and `||`. Not more, not less. That bound is not a simplification — a
+ * consumer switching engines must not newly accept an expression (which recognising
+ * another construct would do) nor newly reject one (which recognising fewer would do),
+ * and a guard written as a function call is deliberately not proof.
+ *
+ * The rules, over a condition `c`:
+ *
+ * - `chain != null` proves `chain` where `c` holds; `chain == null` proves it where `c`
+ *   fails. `null` may stand on either side of the comparison.
+ * - `!c` swaps the two.
+ * - `a && b` proves, where it holds, everything `a` and `b` prove; where it fails,
+ *   nothing, since either arm may be the one that failed.
+ * - `a || b` is the mirror: where it fails, both arms failed, so both their negative
+ *   proofs hold.
+ *
+ * A chain is a plain path of named members (`error.code`), which is what a proof can
+ * name: nothing proves anything about `xs[i].code`, because the index is not part of a
+ * name.
+ */
+
+import type { CelNode } from "./syntax-tree.js";
+
+/** The dotted path a node spells, if it is a plain chain of named members. */
+export function chainText(node: CelNode): string | undefined {
+  if (node.kind === "ident") return node.name;
+  if (node.kind !== "select" || node.optional || node.field === "") return undefined;
+  const operand = chainText(node.operand);
+  return operand === undefined ? undefined : `${operand}.${node.field}`;
+}
+
+/**
+ * The name a chain is rooted at, or nothing when it is not a chain of plain members over a
+ * name. It is what says whether the chain's subject is a name the EXPRESSION bound — a
+ * comprehension variable, a `cel.bind` name — rather than one the host declared.
+ */
+export function chainRoot(node: CelNode): string | undefined {
+  if (node.kind === "ident") return node.name;
+  if (node.kind !== "select" || node.optional || node.field === "") return undefined;
+  return chainRoot(node.operand);
+}
+
+/** The chains proven non-null where the condition holds. */
+export function provenWhereTrue(condition: CelNode): readonly string[] {
+  switch (condition.kind) {
+    case "binary":
+      if (condition.operator === "!=") return nullTest(condition);
+      if (condition.operator === "&&") {
+        return [...provenWhereTrue(condition.left), ...provenWhereTrue(condition.right)];
+      }
+      return [];
+    case "unary":
+      return condition.operator === "!" ? provenWhereFalse(condition.operand) : [];
+    default:
+      return [];
+  }
+}
+
+/** The chains proven non-null where the condition fails. */
+export function provenWhereFalse(condition: CelNode): readonly string[] {
+  switch (condition.kind) {
+    case "binary":
+      if (condition.operator === "==") return nullTest(condition);
+      if (condition.operator === "||") {
+        return [...provenWhereFalse(condition.left), ...provenWhereFalse(condition.right)];
+      }
+      return [];
+    case "unary":
+      return condition.operator === "!" ? provenWhereTrue(condition.operand) : [];
+    default:
+      return [];
+  }
+}
+
+/** The chain a comparison against `null` is about, either way round. */
+function nullTest(comparison: Extract<CelNode, { kind: "binary" }>): readonly string[] {
+  const { left, right } = comparison;
+  if (isNullLiteral(right)) {
+    const chain = chainText(left);
+    return chain === undefined ? [] : [chain];
+  }
+  if (isNullLiteral(left)) {
+    const chain = chainText(right);
+    return chain === undefined ? [] : [chain];
+  }
+  return [];
+}
+
+function isNullLiteral(node: CelNode): boolean {
+  return node.kind === "literal" && node.literal.type === "null";
+}

package/src/parse-limits.ts

@@ -0,0 +1,36 @@
+/**
+ * What the front end refuses to read because it is too big.
+ *
+ * An expression arrives from a manifest, from an editor buffer or over a wire, so
+ * the parser is a hostile-input boundary: without a bound, nesting alone exhausts
+ * the call stack of a recursive-descent parser, and a generated list exhausts
+ * memory. Each limit is reported as an ordinary ranged diagnostic — never a
+ * thrown error — so an editor keeps the prefix it could read.
+ *
+ * The defaults are the ones every already-written manifest was accepted under.
+ */
+
+export interface CelParseLimits {
+  /** Nodes in the tree. */
+  readonly maxNodes: number;
+  /** Nesting depth of the expression grammar. */
+  readonly maxDepth: number;
+  /** Elements in one list literal. */
+  readonly maxListElements: number;
+  /** Entries in one map literal. */
+  readonly maxMapEntries: number;
+  /** Arguments at one call. */
+  readonly maxCallArguments: number;
+}
+
+export const DEFAULT_PARSE_LIMITS: CelParseLimits = {
+  maxNodes: 100000,
+  maxDepth: 250,
+  maxListElements: 1000,
+  maxMapEntries: 1000,
+  maxCallArguments: 32,
+};
+
+export function resolveParseLimits(limits?: Partial<CelParseLimits>): CelParseLimits {
+  return limits ? { ...DEFAULT_PARSE_LIMITS, ...limits } : DEFAULT_PARSE_LIMITS;
+}