@checkstack/template-engine 0.2.0

package/src/renderer.ts

@@ -0,0 +1,274 @@
+import type { Expr, TemplateNode } from "./ast";
+import {
+  TemplateRenderError,
+  UnknownFilterError,
+} from "./errors";
+import {
+  createDefaultFilterRegistry,
+  isTruthy,
+} from "./filters";
+import type {
+  FilterRegistry,
+  ParsedCondition,
+  ParsedTemplate,
+  SourceRange,
+  TemplateContext,
+} from "./types";
+
+export interface RenderOptions {
+  /**
+   * Custom filter registry. Defaults to the built-in registry. Pass a
+   * pre-loaded registry when integrating with extra plugin-contributed
+   * filters.
+   */
+  filters?: FilterRegistry;
+  /**
+   * When true, accessing an undefined path throws instead of resolving to
+   * the empty string. Default: false (graceful missing → empty string).
+   * The dispatch engine flips this on at certain audit-critical sites.
+   */
+  strict?: boolean;
+}
+
+/**
+ * Render a parsed template to a string. Handles literal segments and
+ * `{{ expression }}` interpolation. Unknown identifiers resolve to the
+ * empty string by default (operators see this as a missing value).
+ */
+export function render(
+  template: ParsedTemplate,
+  context: TemplateContext,
+  options: RenderOptions = {},
+): string {
+  const filters = options.filters ?? createDefaultFilterRegistry();
+  let out = "";
+  const nodes = template.nodes as TemplateNode[];
+  for (const node of nodes) {
+    if (node.kind === "text") {
+      out += node.value;
+      continue;
+    }
+    const value = evaluateExpr(
+      node.expression,
+      context,
+      template.source,
+      filters,
+      options,
+    );
+    out += stringify(value);
+  }
+  return out;
+}
+
+/**
+ * Evaluate a parsed condition expression against context and return the
+ * raw value. Use `isTruthy()` to coerce to boolean if needed.
+ */
+export function evaluate(
+  condition: ParsedCondition,
+  context: TemplateContext,
+  options: RenderOptions = {},
+): unknown {
+  const filters = options.filters ?? createDefaultFilterRegistry();
+  return evaluateExpr(
+    condition.root,
+    context,
+    condition.source,
+    filters,
+    options,
+  );
+}
+
+/**
+ * Evaluate a condition and coerce to boolean using the engine's truthiness
+ * rule. Convenience over `evaluate()` for the common case.
+ */
+export function evaluateBoolean(
+  condition: ParsedCondition,
+  context: TemplateContext,
+  options: RenderOptions = {},
+): boolean {
+  return isTruthy(evaluate(condition, context, options));
+}
+
+// ─── Internal evaluator ────────────────────────────────────────────────────
+
+function evaluateExpr(
+  expr: Expr,
+  context: TemplateContext,
+  source: string,
+  filters: FilterRegistry,
+  options: RenderOptions,
+): unknown {
+  switch (expr.kind) {
+    case "literal": {
+      return expr.value;
+    }
+
+    case "identifier": {
+      return resolveIdentifier(expr.name, context, expr.range, source, options);
+    }
+
+    case "member": {
+      const obj = evaluateExpr(expr.object, context, source, filters, options);
+      return resolveMember(obj, expr.property, expr.range, source, options);
+    }
+
+    case "index": {
+      const obj = evaluateExpr(expr.object, context, source, filters, options);
+      const key = evaluateExpr(expr.index, context, source, filters, options);
+      return resolveMember(obj, String(key ?? ""), expr.range, source, options);
+    }
+
+    case "unary": {
+      return !isTruthy(
+        evaluateExpr(expr.operand, context, source, filters, options),
+      );
+    }
+
+    case "binary": {
+      const left = evaluateExpr(expr.left, context, source, filters, options);
+      // Short-circuit logical operators
+      if (expr.op === "&&") {
+        if (!isTruthy(left)) return left;
+        return evaluateExpr(expr.right, context, source, filters, options);
+      }
+      if (expr.op === "||") {
+        if (isTruthy(left)) return left;
+        return evaluateExpr(expr.right, context, source, filters, options);
+      }
+      const right = evaluateExpr(expr.right, context, source, filters, options);
+      return applyComparison(expr.op, left, right);
+    }
+
+    case "ternary": {
+      return isTruthy(
+        evaluateExpr(expr.condition, context, source, filters, options),
+      )
+        ? evaluateExpr(expr.consequent, context, source, filters, options)
+        : evaluateExpr(expr.alternate, context, source, filters, options);
+    }
+
+    case "pipe": {
+      const value = evaluateExpr(expr.value, context, source, filters, options);
+      const filter = filters.get(expr.filter);
+      if (!filter) {
+        throw new UnknownFilterError({
+          filterName: expr.filter,
+          source,
+          range: expr.range,
+        });
+      }
+      const args = expr.args.map((a) =>
+        evaluateExpr(a, context, source, filters, options),
+      );
+      return filter(value, ...args);
+    }
+  }
+}
+
+function resolveIdentifier(
+  name: string,
+  context: TemplateContext,
+  range: SourceRange,
+  source: string,
+  options: RenderOptions,
+): unknown {
+  if (Object.prototype.hasOwnProperty.call(context, name)) {
+    return (context as Record<string, unknown>)[name];
+  }
+  if (options.strict) {
+    throw new TemplateRenderError({
+      message: `Unknown reference "${name}"`,
+      source,
+      range,
+      path: name,
+    });
+  }
+  return undefined;
+}
+
+function resolveMember(
+  object: unknown,
+  property: string,
+  range: SourceRange,
+  source: string,
+  options: RenderOptions,
+): unknown {
+  if (object === null || object === undefined) {
+    if (options.strict) {
+      throw new TemplateRenderError({
+        message: `Cannot access "${property}" of ${object === null ? "null" : "undefined"}`,
+        source,
+        range,
+        path: property,
+      });
+    }
+    return undefined;
+  }
+  if (typeof object !== "object") return undefined;
+  return (object as Record<string, unknown>)[property];
+}
+
+function applyComparison(
+  op: "==" | "!=" | "<" | ">" | "<=" | ">=",
+  left: unknown,
+  right: unknown,
+): boolean {
+  switch (op) {
+    case "==": {
+      return looseEquals(left, right);
+    }
+    case "!=": {
+      return !looseEquals(left, right);
+    }
+    case "<": {
+      return compareNumeric(left, right) < 0;
+    }
+    case ">": {
+      return compareNumeric(left, right) > 0;
+    }
+    case "<=": {
+      return compareNumeric(left, right) <= 0;
+    }
+    case ">=": {
+      return compareNumeric(left, right) >= 0;
+    }
+  }
+}
+
+/**
+ * Equality used by `==`. Strings compare by content, numbers by value,
+ * and across types coerced to string when one side is a string. Mirrors
+ * what operators expect when comparing event ids to literals.
+ */
+function looseEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || a === undefined) return a === b;
+  if (b === null || b === undefined) return false;
+  if (typeof a === typeof b) return a === b;
+  return String(a) === String(b);
+}
+
+function compareNumeric(a: unknown, b: unknown): number {
+  const na = typeof a === "number" ? a : Number(a);
+  const nb = typeof b === "number" ? b : Number(b);
+  if (Number.isFinite(na) && Number.isFinite(nb)) {
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+    return 0;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  if (sa < sb) return -1;
+  if (sa > sb) return 1;
+  return 0;
+}
+
+function stringify(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  return JSON.stringify(value);
+}

package/src/tokenizer.ts

@@ -0,0 +1,338 @@
+import { TemplateParseError, pointRange } from "./errors";
+import type { SourcePosition, SourceRange } from "./types";
+
+/**
+ * Tokens produced by the template tokenizer.
+ *
+ * Templates are a sequence of LITERAL text segments interleaved with
+ * `{{ ... }}` expression blocks. Inside an expression block the tokens
+ * are typed (idents, literals, operators).
+ */
+export type TokenKind =
+  // Top-level segments
+  | "LITERAL"        // text outside {{ }}
+  | "EXPR_OPEN"      // {{
+  | "EXPR_CLOSE"     // }}
+  // Inside an expression
+  | "IDENT"
+  | "NUMBER"
+  | "STRING"
+  | "TRUE"
+  | "FALSE"
+  | "NULL"
+  | "DOT"
+  | "COMMA"
+  | "LPAREN"
+  | "RPAREN"
+  | "LBRACKET"
+  | "RBRACKET"
+  | "QUESTION"
+  | "COLON"
+  | "PIPE"
+  | "EQ"
+  | "NEQ"
+  | "LT"
+  | "GT"
+  | "LTE"
+  | "GTE"
+  | "AND"
+  | "OR"
+  | "NOT"
+  | "EOF";
+
+export interface Token {
+  kind: TokenKind;
+  value: string;
+  range: SourceRange;
+}
+
+/**
+ * Tokenizer state machine.
+ *
+ * Switches between "literal" mode (collecting raw text) and "expression"
+ * mode (lexing identifiers, operators, etc.). The mode flips on `{{` and
+ * back on `}}`.
+ */
+export class Tokenizer {
+  private pos = 0;
+  private line = 1;
+  private column = 1;
+  private mode: "literal" | "expression" = "literal";
+
+  constructor(private readonly source: string) {}
+
+  /**
+   * Drive the tokenizer to completion and return all tokens. Empty LITERAL
+   * tokens are skipped — they add nothing but noise.
+   */
+  tokenize(): Token[] {
+    const tokens: Token[] = [];
+    while (this.pos < this.source.length) {
+      const token = this.next();
+      if (token.kind === "LITERAL" && token.value.length === 0) continue;
+      tokens.push(token);
+    }
+    tokens.push({
+      kind: "EOF",
+      value: "",
+      range: pointRange(this.position()),
+    });
+    return tokens;
+  }
+
+  private next(): Token {
+    if (this.mode === "literal") {
+      return this.readLiteral();
+    }
+    return this.readExpression();
+  }
+
+  private readLiteral(): Token {
+    const start = this.position();
+    let value = "";
+    while (this.pos < this.source.length) {
+      // Check for {{ — start of expression
+      if (this.peek() === "{" && this.peekAt(1) === "{") {
+        if (value.length === 0) {
+          // No literal before — emit EXPR_OPEN
+          const openStart = this.position();
+          this.advance();
+          this.advance();
+          this.mode = "expression";
+          return {
+            kind: "EXPR_OPEN",
+            value: "{{",
+            range: { start: openStart, end: this.position() },
+          };
+        }
+        // Emit accumulated literal; next call will see {{
+        return {
+          kind: "LITERAL",
+          value,
+          range: { start, end: this.position() },
+        };
+      }
+      value += this.peek();
+      this.advance();
+    }
+    return {
+      kind: "LITERAL",
+      value,
+      range: { start, end: this.position() },
+    };
+  }
+
+  private readExpression(): Token {
+    this.skipWhitespace();
+    if (this.pos >= this.source.length) {
+      throw new TemplateParseError({
+        message: "Unterminated expression: missing closing `}}`",
+        source: this.source,
+        range: pointRange(this.position()),
+      });
+    }
+    const start = this.position();
+
+    // Closing braces }}
+    if (this.peek() === "}" && this.peekAt(1) === "}") {
+      this.advance();
+      this.advance();
+      this.mode = "literal";
+      return {
+        kind: "EXPR_CLOSE",
+        value: "}}",
+        range: { start, end: this.position() },
+      };
+    }
+
+    const c = this.peek();
+
+    // Numeric literal
+    if (this.isDigit(c)) {
+      return this.readNumber(start);
+    }
+
+    // String literal
+    if (c === '"' || c === "'") {
+      return this.readString(start, c);
+    }
+
+    // Identifier / keyword
+    if (this.isIdentStart(c)) {
+      return this.readIdentifier(start);
+    }
+
+    // Operators & punctuation
+    return this.readOperator(start);
+  }
+
+  private readNumber(start: SourcePosition): Token {
+    let value = "";
+    while (this.pos < this.source.length && this.isDigit(this.peek())) {
+      value += this.peek();
+      this.advance();
+    }
+    if (this.peek() === "." && this.isDigit(this.peekAt(1) ?? "")) {
+      value += ".";
+      this.advance();
+      while (this.pos < this.source.length && this.isDigit(this.peek())) {
+        value += this.peek();
+        this.advance();
+      }
+    }
+    return {
+      kind: "NUMBER",
+      value,
+      range: { start, end: this.position() },
+    };
+  }
+
+  private readString(start: SourcePosition, quote: string): Token {
+    this.advance(); // skip opening quote
+    let value = "";
+    while (this.pos < this.source.length && this.peek() !== quote) {
+      if (this.peek() === "\\") {
+        this.advance();
+        const esc = this.peek();
+        const escMap: Record<string, string> = {
+          n: "\n",
+          t: "\t",
+          r: "\r",
+          "\\": "\\",
+          '"': '"',
+          "'": "'",
+        };
+        value += escMap[esc] ?? esc;
+        this.advance();
+      } else {
+        value += this.peek();
+        this.advance();
+      }
+    }
+    if (this.pos >= this.source.length) {
+      throw new TemplateParseError({
+        message: "Unterminated string literal",
+        source: this.source,
+        range: { start, end: this.position() },
+      });
+    }
+    this.advance(); // closing quote
+    return {
+      kind: "STRING",
+      value,
+      range: { start, end: this.position() },
+    };
+  }
+
+  private readIdentifier(start: SourcePosition): Token {
+    let value = "";
+    while (this.pos < this.source.length && this.isIdentCont(this.peek())) {
+      value += this.peek();
+      this.advance();
+    }
+    const range = { start, end: this.position() };
+    if (value === "true") return { kind: "TRUE", value, range };
+    if (value === "false") return { kind: "FALSE", value, range };
+    if (value === "null") return { kind: "NULL", value, range };
+    return { kind: "IDENT", value, range };
+  }
+
+  private readOperator(start: SourcePosition): Token {
+    const c = this.peek();
+    const next = this.peekAt(1);
+
+    const two = c + (next ?? "");
+    const twoMap: Record<string, TokenKind> = {
+      "==": "EQ",
+      "!=": "NEQ",
+      "<=": "LTE",
+      ">=": "GTE",
+      "&&": "AND",
+      "||": "OR",
+    };
+    if (twoMap[two]) {
+      this.advance();
+      this.advance();
+      return {
+        kind: twoMap[two],
+        value: two,
+        range: { start, end: this.position() },
+      };
+    }
+
+    const oneMap: Record<string, TokenKind> = {
+      ".": "DOT",
+      ",": "COMMA",
+      "(": "LPAREN",
+      ")": "RPAREN",
+      "[": "LBRACKET",
+      "]": "RBRACKET",
+      "?": "QUESTION",
+      ":": "COLON",
+      "|": "PIPE",
+      "<": "LT",
+      ">": "GT",
+      "!": "NOT",
+    };
+    if (oneMap[c]) {
+      this.advance();
+      return {
+        kind: oneMap[c],
+        value: c,
+        range: { start, end: this.position() },
+      };
+    }
+
+    throw new TemplateParseError({
+      message: `Unexpected character "${c}" in expression`,
+      source: this.source,
+      range: pointRange(start),
+    });
+  }
+
+  private skipWhitespace(): void {
+    while (this.pos < this.source.length && /\s/.test(this.peek())) {
+      this.advance();
+    }
+  }
+
+  private peek(): string {
+    return this.source[this.pos] ?? "";
+  }
+
+  private peekAt(offset: number): string | undefined {
+    return this.source[this.pos + offset];
+  }
+
+  private advance(): void {
+    const c = this.source[this.pos];
+    this.pos += 1;
+    if (c === "\n") {
+      this.line += 1;
+      this.column = 1;
+    } else {
+      this.column += 1;
+    }
+  }
+
+  private position(): SourcePosition {
+    return { line: this.line, column: this.column };
+  }
+
+  private isDigit(c: string): boolean {
+    return c >= "0" && c <= "9";
+  }
+
+  private isIdentStart(c: string): boolean {
+    return (
+      (c >= "a" && c <= "z") ||
+      (c >= "A" && c <= "Z") ||
+      c === "_" ||
+      c === "$"
+    );
+  }
+
+  private isIdentCont(c: string): boolean {
+    return this.isIdentStart(c) || this.isDigit(c);
+  }
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Public types for the template engine.
+ *
+ * The template engine is used in two contexts:
+ *
+ *   1. Server-side at automation dispatch time — render the actual values
+ *      for provider config fields, choose conditions, condition guards, etc.
+ *   2. Client-side at edit time — preview the rendered output against a
+ *      sample context for UX validation.
+ *
+ * Both contexts share this surface.
+ */
+
+/**
+ * The context object an expression is rendered against.
+ *
+ * Keys typically include `trigger`, `nodes`, `config`, `variables`, plus
+ * platform helpers like `now()`.
+ *
+ * Unknown is used at the value level because the shape depends on the
+ * automation's topology (which triggers / upstream artifacts are in scope).
+ */
+export type TemplateContext = Record<string, unknown>;
+
+/**
+ * A parsed template program — opaque to consumers. Pass it to `render()`.
+ */
+export interface ParsedTemplate {
+  /** Discriminator so future versions can detect mismatch. */
+  readonly version: 1;
+  /** Internal AST nodes (kept as `unknown` to avoid exposing internals). */
+  readonly nodes: ReadonlyArray<unknown>;
+  /** Original source text — kept for error message context. */
+  readonly source: string;
+}
+
+/**
+ * A parsed condition expression — opaque to consumers. Pass it to `evaluate()`.
+ *
+ * Conditions are pure expressions (no surrounding literal text), unlike
+ * full templates which interleave text and `{{ ... }}` segments.
+ */
+export interface ParsedCondition {
+  readonly version: 1;
+  readonly root: import("./ast").Expr;
+  readonly source: string;
+}
+
+/**
+ * A position in source text. 1-indexed line and column, matching what
+ * editors expect.
+ */
+export interface SourcePosition {
+  line: number;
+  column: number;
+}
+
+/**
+ * A source range — start and end position pair.
+ */
+export interface SourceRange {
+  start: SourcePosition;
+  end: SourcePosition;
+}
+
+/**
+ * Built-in filter signature.
+ *
+ * A filter is invoked as `value | name` or `value | name(arg1, arg2)`. The
+ * first argument is always the piped value; remaining are literal args
+ * from the call site.
+ */
+export type Filter = (value: unknown, ...args: unknown[]) => unknown;
+
+/**
+ * Filter registry — name → implementation mapping.
+ */
+export interface FilterRegistry {
+  register(name: string, filter: Filter): void;
+  get(name: string): Filter | undefined;
+  has(name: string): boolean;
+  list(): string[];
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    }
+  ]
+}