@telorun/templating 0.2.0

package/src/cel/walk.ts

@@ -0,0 +1,43 @@
+import { isTaggedSentinel } from "../sentinel.js";
+import { TEMPLATE_REGEX } from "./compile.js";
+
+/** Walks `value` and emits each templated source segment with its dotted
+ *  path (e.g. `routes[0].handler.body`) and the engine that owns it.
+ *
+ *  - Untagged strings: every `${{ ... }}` segment is emitted with
+ *    `engineName = "cel"` (the implicit engine for the legacy interpolation
+ *    syntax).
+ *  - Tagged sentinels: emitted once with the sentinel's declared engine.
+ *    This includes engines that may produce no diagnostics (`literal`) —
+ *    routing through the registry stays generic so adding a third engine
+ *    that wants real analysis doesn't require touching the walker.
+ *  - Compiled values are skipped so a precompiled tree won't be re-walked. */
+export function walkCelExpressions(
+  value: unknown,
+  path: string,
+  cb: (source: string, path: string, engineName: string) => void,
+): void {
+  if (isTaggedSentinel(value)) {
+    cb(value.source, path, value.engine);
+    return;
+  }
+  if (typeof value === "string") {
+    for (const m of value.matchAll(TEMPLATE_REGEX)) {
+      cb(m[1].trim(), path, "cel");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => walkCelExpressions(v, `${path}[${i}]`, cb));
+    return;
+  }
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    !(value as { __compiled?: unknown }).__compiled
+  ) {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      walkCelExpressions(v, path ? `${path}.${k}` : k, cb);
+    }
+  }
+}

package/src/engine.ts

@@ -0,0 +1,53 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { CompiledValue } from "@telorun/sdk";
+
+/** Compile-time environment passed to `engine.compile`. Engines that need to
+ *  parse against a CEL environment (the `cel` engine) read it from `celEnv`;
+ *  engines that resolve fully at compile time (`literal`) ignore it. */
+export interface CompileEnv {
+  readonly celEnv: Environment;
+}
+
+/** Analyze-time environment passed to `engine.analyze`. The walker resolves
+ *  the path-specific effective context (kernel globals merged in, x-telo-context
+ *  applied) and hands the engine a single closed schema. The engine validates
+ *  member-access chains against it. `null` means "open context" — no chain
+ *  validation possible. */
+export interface AnalyzeEnv {
+  readonly celEnv: Environment;
+  readonly contextSchema: Record<string, unknown> | null;
+}
+
+/** A single static-analysis finding produced by an engine. Stable codes match
+ *  the analyzer's existing diagnostic codes so downstream filtering keeps
+ *  working unchanged across the engine boundary. */
+export interface EngineDiagnostic {
+  readonly message: string;
+  readonly code?: string;
+}
+
+/** Per-property templating engine. Matches a YAML tag (`!<name>`); the kernel
+ *  and analyzer dispatch through the registry rather than knowing about
+ *  specific engines. */
+export interface TemplatingEngine {
+  /** Registry key matching the YAML tag name (without `!`). */
+  readonly name: string;
+
+  /** Optional Monaco language id for editor syntax highlighting. Currently
+   *  unread — the editor's CelFieldWrapper uses a plain `<input>`. Wiring
+   *  this through to a Monaco editor instance is tracked separately; the
+   *  field is documented intent so engine authors don't have to revisit
+   *  the interface when Monaco lands.
+   *  TODO(editor): consume `engine.language` from the field renderer. */
+  readonly language?: string;
+
+  /** Convert a tagged source string into a runtime value. Called once at
+   *  precompile. Returns either a CompiledValue (engines that defer evaluation
+   *  to a runtime EvalContext, like `cel`) or a plain value (engines like
+   *  `literal` that resolve fully at compile time). */
+  compile(source: string, env: CompileEnv): CompiledValue | unknown;
+
+  /** Static analysis hook. Engines that can't statically check (e.g. `literal`)
+   *  return []. The walker accumulates diagnostics across all values. */
+  analyze(source: string, env: AnalyzeEnv): readonly EngineDiagnostic[];
+}

package/src/engines/cel.ts

@@ -0,0 +1,40 @@
+import { extractAccessChains, validateChainAgainstSchema } from "../cel/analyze.js";
+import { compileExpression } from "../cel/compile.js";
+import type { EngineDiagnostic, TemplatingEngine } from "../engine.js";
+
+/** The `!cel` engine. Treats the entire tagged scalar as a single CEL
+ *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
+ *  as the untagged path: parse → extract member-access chains → validate each
+ *  chain against the effective context schema. */
+export const celEngine: TemplatingEngine = {
+  name: "cel",
+  language: "cel",
+
+  compile(source, env) {
+    return compileExpression(source, env.celEnv);
+  },
+
+  analyze(source, env) {
+    const out: EngineDiagnostic[] = [];
+
+    let parsed: ReturnType<typeof env.celEnv.parse>;
+    try {
+      parsed = env.celEnv.parse(source);
+    } catch (e) {
+      out.push({
+        code: "CEL_SYNTAX_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+      });
+      return out;
+    }
+
+    if (!env.contextSchema) return out;
+
+    const chains = extractAccessChains(parsed.ast);
+    for (const chain of chains) {
+      const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
+      if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+    }
+    return out;
+  },
+};

package/src/engines/literal.ts

@@ -0,0 +1,16 @@
+import type { TemplatingEngine } from "../engine.js";
+
+/** The `!literal` engine. Treats the tagged scalar as opaque text — no CEL
+ *  interpolation, no analysis. Returns the source string verbatim at compile
+ *  time so the runtime sees a plain string. */
+export const literalEngine: TemplatingEngine = {
+  name: "literal",
+
+  compile(source) {
+    return source;
+  },
+
+  analyze() {
+    return [];
+  },
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export {
+  compileExpression,
+  compileString,
+  TEMPLATE_REGEX,
+  EXACT_TEMPLATE_REGEX,
+} from "./cel/compile.js";
+export { extractAccessChains, validateChainAgainstSchema } from "./cel/analyze.js";
+export { walkCelExpressions } from "./cel/walk.js";
+
+export { celEngine } from "./engines/cel.js";
+export { literalEngine } from "./engines/literal.js";
+
+export { TemplatingEngineRegistry } from "./registry.js";
+export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
+export type {
+  AnalyzeEnv,
+  CompileEnv,
+  EngineDiagnostic,
+  TemplatingEngine,
+} from "./engine.js";
+
+export { isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";

package/src/registry.ts

@@ -0,0 +1,25 @@
+import type { TemplatingEngine } from "./engine.js";
+
+export class TemplatingEngineRegistry {
+  private readonly engines = new Map<string, TemplatingEngine>();
+
+  register(engine: TemplatingEngine): void {
+    if (this.engines.has(engine.name)) {
+      throw new Error(`Templating engine '${engine.name}' is already registered.`);
+    }
+    this.engines.set(engine.name, engine);
+  }
+
+  get(name: string): TemplatingEngine | undefined {
+    return this.engines.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.engines.has(name);
+  }
+
+  /** All registered engines in registration order. */
+  list(): readonly TemplatingEngine[] {
+    return [...this.engines.values()];
+  }
+}

package/src/sentinel.ts

@@ -0,0 +1,25 @@
+/** Sentinel object produced by the YAML loader for a tagged scalar (e.g. `!cel
+ *  'variables.port'`). Travels through the manifest tree as the parsed value;
+ *  precompile and the analyzer key off `__tagged === true` to dispatch to the
+ *  right engine. The object is intentionally a plain JSON-shaped record so it
+ *  survives `Document.toJSON()` and `JSON.parse(JSON.stringify(...))` without
+ *  loss. */
+export interface TaggedSentinel {
+  readonly __tagged: true;
+  readonly engine: string;
+  readonly source: string;
+}
+
+export function isTaggedSentinel(v: unknown): v is TaggedSentinel {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    (v as { __tagged?: unknown }).__tagged === true &&
+    typeof (v as { engine?: unknown }).engine === "string" &&
+    typeof (v as { source?: unknown }).source === "string"
+  );
+}
+
+export function makeTaggedSentinel(engine: string, source: string): TaggedSentinel {
+  return { __tagged: true, engine, source };
+}

package/src/yaml-tags.ts

@@ -0,0 +1,71 @@
+import type { ScalarTag } from "yaml";
+import { stringifyString } from "yaml/util";
+import { defaultRegistry } from "./builtins.js";
+import { isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+import type { TemplatingEngineRegistry } from "./registry.js";
+
+/** Build the `customTags` array passed to `yaml`'s `parseAllDocuments` /
+ *  `Document` from the registered engines. Each engine contributes one
+ *  ScalarTag whose `resolve` produces a `TaggedSentinel`, and whose
+ *  `identify` + `stringify` round-trip the sentinel back to its original
+ *  `!<engine> "<source>"` form when the document is re-serialized.
+ *
+ *  Without `stringify`, `Document.toString()` would emit the sentinel as a
+ *  YAML mapping (`{__tagged: true, engine: cel, source: ...}`), corrupting
+ *  the file on the editor's first save. Without `identify`, the serializer
+ *  wouldn't know to use the custom tag at all and would fall through to
+ *  default object serialization.
+ *
+ *  Single source of truth: every `parseAllDocuments` call site in the repo
+ *  calls this factory so the parse-side configuration cannot drift between
+ *  hosts. Each host passes its own registry (in practice always
+ *  `createDefaultRegistry()`), keeping the door open for future
+ *  test-only registries. */
+export function buildCustomTags(registry: TemplatingEngineRegistry): ScalarTag[] {
+  return registry.list().map((engine) => buildTagForEngine(engine.name));
+}
+
+/** Returns `customTags` built from the default registry, freshly each call.
+ *  Every `parseAllDocuments` call site in the repo calls this so they all
+ *  parse the same set of tags. Built from `defaultRegistry()` (the same
+ *  singleton precompile + the analyzer use) so registering a new engine on
+ *  the default registry propagates to YAML parsing on the next call. The
+ *  rebuild cost is negligible (one array of N small ScalarTag objects). */
+export function defaultCustomTags(): ScalarTag[] {
+  return buildCustomTags(defaultRegistry());
+}
+
+function buildTagForEngine(engineName: string): ScalarTag {
+  const tagId = `!${engineName}`;
+  return {
+    tag: tagId,
+    resolve: (value: string): TaggedSentinel => makeTaggedSentinel(engineName, value),
+    identify: (v: unknown): boolean => isTaggedSentinel(v) && v.engine === engineName,
+    stringify(item, ctx, onComment, onChompKeep): string {
+      // Two paths reach this function:
+      // 1. Parsed-then-serialized: the resolver produced a TaggedSentinel
+      //    and we recover the original `source` from it; the original
+      //    Scalar carries the user's chosen quoting style on `item.type`,
+      //    which we pass through so single-quoted stays single-quoted.
+      // 2. setTag applied to an existing scalar: the underlying value is a
+      //    plain primitive (string/number/boolean) — coerce to string and
+      //    let yaml's stringifier pick a safe default style.
+      // Either way, delegate to yaml's `stringifyString` so newlines, tabs,
+      // control characters, leading-whitespace lines, and multi-line content
+      // are all escaped/quoted correctly. The yaml lib emits the tag prefix
+      // itself; this only returns the scalar body.
+      const value = item.value;
+      const source = isTaggedSentinel(value)
+        ? value.source
+        : value === null || value === undefined
+          ? ""
+          : String(value);
+      return stringifyString(
+        { value: source, type: (item as { type?: string }).type },
+        ctx,
+        onComment,
+        onChompKeep,
+      );
+    },
+  } satisfies ScalarTag;
+}