@telorun/templating 0.11.1 → 0.13.0

package/src/engines/include.ts

@@ -0,0 +1,153 @@
+import type { EngineFileClaim, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import { INCLUDE_BYTES_ENGINE, INCLUDE_TEXT_ENGINE, makeTaggedSentinel } from "../sentinel.js";
+
+/** Characters that would make a path a pattern rather than a name. Globs are
+ *  excluded deliberately: a claim has to name one file for publish to place it
+ *  in a layer, and a pattern that matches nothing on the publishing machine
+ *  would ship an artifact missing a file the manifest reads. */
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/** `scheme:` prefix — a URL, or a Windows drive letter. Either way not a
+ *  module-relative path. */
+const URI_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+
+export interface NormalizedIncludePath {
+  /** Module-root-relative path with `./` and `.` segments folded out, `/`
+   *  separated. Absent when the source is not a usable path. */
+  readonly path?: string;
+  readonly diagnostic?: EngineDiagnostic;
+}
+
+/**
+ * Normalize an `!include-*` source to a module-root-relative path, or explain
+ * why it is not one.
+ *
+ * Pure string work, deliberately: this runs in the analyzer, which must load in
+ * a browser, so confinement is decided from the written path alone and never by
+ * asking a filesystem where it lands. That is possible because the path is
+ * root-relative by definition — the module root is the one directory every path
+ * is measured from, so `..` below depth zero is an escape regardless of where
+ * the module happens to sit on disk.
+ */
+export function normalizeIncludePath(source: string): NormalizedIncludePath {
+  const raw = source.trim();
+  if (raw === "") {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message: "the path is empty — name a file relative to the module root.",
+      },
+    };
+  }
+  if (URI_SCHEME.test(raw)) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message:
+          `'${raw}' names a location outside the module. An include path is a file that ships ` +
+          `inside the module artifact, written relative to the module root. To read a file at ` +
+          `runtime from somewhere else, use Fs.File.`,
+      },
+    };
+  }
+  if (GLOB_CHARS.test(raw)) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message:
+          `'${raw}' looks like a pattern. An include path names exactly one file, because ` +
+          `publish places each claimed file into a layer by name.`,
+      },
+    };
+  }
+  if (raw.startsWith("/") || raw.startsWith("\\")) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_ESCAPES_MODULE",
+        message:
+          `'${raw}' is an absolute path. An include path is written relative to the module ` +
+          `root, so the same manifest resolves identically from a checkout and from a ` +
+          `published artifact.`,
+      },
+    };
+  }
+
+  const out: string[] = [];
+  for (const segment of raw.split(/[/\\]+/)) {
+    if (segment === "" || segment === ".") continue;
+    if (segment !== "..") {
+      out.push(segment);
+      continue;
+    }
+    // Depth zero is the module root. Popping past it would read a file the
+    // artifact cannot contain, so it is an escape rather than a path to
+    // normalize — and catching it here is what keeps the check static.
+    if (out.length === 0) {
+      return {
+        diagnostic: {
+          code: "INCLUDE_PATH_ESCAPES_MODULE",
+          message:
+            `'${raw}' points above the module root. An include path may only name a file ` +
+            `inside the module, since that is the only thing its artifact can carry.`,
+        },
+      };
+    }
+    out.pop();
+  }
+  if (out.length === 0) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message: `'${raw}' resolves to the module root, not to a file.`,
+      },
+    };
+  }
+  return { path: out.join("/") };
+}
+
+/**
+ * The `!include-text` / `!include-bytes` engines — a file that ships inside the
+ * module artifact, embedded as a manifest value.
+ *
+ * `compile` returns the sentinel unchanged rather than a value. Two things
+ * follow, and both are the point. The read is deferred to resource creation, so
+ * loading a manifest does not pull payload layers — the artifact spec makes
+ * `telo.yaml` its own layer precisely so that reading a manifest cannot drag the
+ * whole artifact in, and an app loads every imported library's manifest. And
+ * because the marker survives precompile the way a `!ref` does, the analyzer can
+ * type the slot without opening the file, which is what keeps it browser-safe.
+ * Unlike `!ref`, no special case is needed in `precompileDoc`: an engine whose
+ * `compile` is identity on its own marker passes through the generic path.
+ *
+ * `analyze` reports why a path is unusable; `fileClaims` reports the path itself
+ * so publish can place the file in a layer without recognising the tag by name.
+ */
+function includeEngine(name: string): TemplatingEngine {
+  return {
+    name,
+
+    compile(source) {
+      return makeTaggedSentinel(name, source);
+    },
+
+    analyze(source) {
+      const { diagnostic } = normalizeIncludePath(source);
+      return { diagnostics: diagnostic ? [diagnostic] : [], calls: [] };
+    },
+
+    fileClaims(source): readonly EngineFileClaim[] {
+      const { path } = normalizeIncludePath(source);
+      // A malformed path claims nothing. `analyze` is what says why, so
+      // claiming a half-understood path here would produce a second, worse
+      // report from publish about the same mistake.
+      return path ? [{ path }] : [];
+    },
+  };
+}
+
+/** Embeds a file's contents as a UTF-8 string. */
+export const includeTextEngine: TemplatingEngine = includeEngine(INCLUDE_TEXT_ENGINE);
+
+/** Embeds a file's contents as raw bytes — a `Uint8Array`, the shape every
+ *  `x-telo-binary` slot accepts. */
+export const includeBytesEngine: TemplatingEngine = includeEngine(INCLUDE_BYTES_ENGINE);

package/src/engines/literal.ts

@@ -11,6 +11,6 @@ export const literalEngine: TemplatingEngine = {
   },
 
   analyze() {
-    return [];
+    return { diagnostics: [], calls: [] };
   },
 };

package/src/engines/ref.ts

@@ -17,6 +17,6 @@ export const refEngine: TemplatingEngine = {
   },
 
   analyze() {
-    return [];
+    return { diagnostics: [], calls: [] };
   },
 };

package/src/engines/sql.ts

@@ -1,7 +1,12 @@
 import { isParameterizedSql, type CompiledValue, type ParameterizedSql } from "@telorun/sdk";
 import { analyzeCelExpression } from "./cel.js";
 import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
-import type { TemplatingEngine } from "../engine.js";
+import type {
+  CallSite,
+  DiagnosticFix,
+  EngineDiagnostic,
+  TemplatingEngine,
+} from "../engine.js";
 
 export { isParameterizedSql, type ParameterizedSql };
 
@@ -30,15 +35,44 @@ export const sqlEngine: TemplatingEngine = {
   analyze(source, env) {
     // Each `${{ }}` interpolation is its own CEL expression; reuse the shared
     // per-expression analyzer so diagnostics match the `!cel` engine exactly.
-    return expressionsOf(source).flatMap((expr) => analyzeCelExpression(expr, env));
+    // Each interpolation's offset is kept so a fix computed against the bare
+    // expression is re-anchored to the whole SQL scalar — the only thing that
+    // ever made `!sql` fix-less was dropping it here.
+    const diagnostics: EngineDiagnostic[] = [];
+    const calls: CallSite[] = [];
+    for (const { expr, start } of expressionsOf(source)) {
+      const result = analyzeCelExpression(expr, env);
+      for (const d of result.diagnostics) {
+        diagnostics.push(d.fix ? { ...d, fix: reanchor(source, expr, start, d.fix) } : d);
+      }
+      for (const c of result.calls) {
+        calls.push({ ...c, start: start + c.start, end: start + c.end });
+      }
+    }
+    // No `type`: a SQL template is a string built from many expressions, so
+    // there is no single checked type to report.
+    return { diagnostics, calls };
   },
 };
 
-/** Extract each `${{ expr }}` body from a `!sql` template source. */
-function expressionsOf(source: string): string[] {
-  const exprs: string[] = [];
+/** Re-anchor a fix computed against one interpolation onto the full source. */
+function reanchor(source: string, expr: string, start: number, fix: DiagnosticFix): DiagnosticFix {
+  return {
+    replacement: source.slice(0, start) + fix.replacement + source.slice(start + expr.length),
+  };
+}
+
+/** Each `${{ expr }}` body in a `!sql` template, with the body's offset in the
+ *  source. The offset is derived from the opening delimiter and the leading
+ *  whitespace the capture group already trims, never by searching for the
+ *  body text — which a body appearing twice would defeat. */
+function expressionsOf(source: string): { expr: string; start: number }[] {
+  const out: { expr: string; start: number }[] = [];
   for (const m of source.matchAll(TEMPLATE_REGEX)) {
-    exprs.push(m[1]!.trim());
+    const lead = /^\s*/.exec(m[0]!.slice(OPEN.length))![0]!.length;
+    out.push({ expr: m[1]!, start: m.index! + OPEN.length + lead });
   }
-  return exprs;
+  return out;
 }
+
+const OPEN = "${{";

package/src/index.ts

@@ -1,4 +1,9 @@
-export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export {
+  buildCelEnvironment,
+  celBuiltinFunctions,
+  deriveSignatures,
+  type CelHandlers,
+} from "./cel/environment.js";
 export {
   celFunctionCatalog,
   CEL_FUNCTIONS,
@@ -19,9 +24,16 @@ export {
   INDEX_SEGMENT,
   validateChainAgainstSchema,
 } from "./cel/analyze.js";
-export { walkCelExpressions } from "./cel/walk.js";
+export { auditCalls, explainUnresolved, functionIndex, type CallAudit } from "./cel/diagnose.js";
+export { walkCelExpressions, type CelSurface } from "./cel/walk.js";
 
 export { celEngine } from "./engines/cel.js";
+export {
+  includeBytesEngine,
+  includeTextEngine,
+  normalizeIncludePath,
+  type NormalizedIncludePath,
+} from "./engines/include.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
 export { sqlEngine, isParameterizedSql, type ParameterizedSql } from "./engines/sql.js";
@@ -30,12 +42,25 @@ export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
 export type {
   AnalyzeEnv,
+  AnalyzeResult,
+  CallSite,
   CompileEnv,
+  DiagnosticFix,
   EngineDiagnostic,
+  EngineFileClaim,
   TemplatingEngine,
 } from "./engine.js";
 
-export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export {
+  INCLUDE_BYTES_ENGINE,
+  INCLUDE_ENGINE_NAMES,
+  INCLUDE_TEXT_ENGINE,
+  isIncludeSentinel,
+  isRefSentinel,
+  isTaggedSentinel,
+  makeTaggedSentinel,
+  type TaggedSentinel,
+} from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
 export {
   MANIFEST_SCHEMA_URI,

package/src/manifest-schemas.ts

@@ -118,8 +118,13 @@ export function normalizeRefSlots(schema: unknown): unknown {
   const out: Record<string, unknown> = { ...node };
   // Reference slot with a stale scalar `type` (legacy string-ref encoding):
   // drop the constraint so the resolved reference object / sentinel validates.
+  //
+  // A presence test, not a shape test — deliberately, since `templating` sits
+  // BELOW the analyzer in the dependency order and cannot reach the shared
+  // `readRefSlot` accessor. Presence is the only thing this rule needs, and it
+  // is stable across every annotation shape.
   if (
-    typeof node[REF_ANNOTATION] === "string" &&
+    node[REF_ANNOTATION] !== undefined &&
     typeof node.type === "string" &&
     LEGACY_REF_SCALAR_TYPES.has(node.type)
   ) {

package/src/sentinel.ts

@@ -32,3 +32,32 @@ export function makeTaggedSentinel(engine: string, source: string): TaggedSentin
 export function isRefSentinel(v: unknown): v is TaggedSentinel & { engine: "ref" } {
   return isTaggedSentinel(v) && v.engine === "ref";
 }
+
+/** Engine names of the two file-embedding tags. Named here beside the other
+ *  sentinel predicates so the kernel's resolution pass and the engines
+ *  themselves agree on one spelling. */
+export const INCLUDE_TEXT_ENGINE = "include-text";
+export const INCLUDE_BYTES_ENGINE = "include-bytes";
+
+/** Both file-embedding tag names, for a consumer holding an engine NAME rather
+ *  than a value (the analyzer's expression walk reports names). */
+export const INCLUDE_ENGINE_NAMES: ReadonlySet<string> = new Set([
+  INCLUDE_TEXT_ENGINE,
+  INCLUDE_BYTES_ENGINE,
+]);
+
+/** True when `v` is an `!include-text` / `!include-bytes` sentinel — a file
+ *  embed marked at parse time and still unresolved.
+ *
+ *  The kernel's creation-time resolution keys off this the way Phase-5
+ *  injection keys off {@link isRefSentinel}. Both tags survive precompile as
+ *  markers rather than collapsing to a value, because the read is deferred: a
+ *  manifest load must not pull payload layers, and the analyzer that types the
+ *  slot cannot open files at all. */
+export function isIncludeSentinel(
+  v: unknown,
+): v is TaggedSentinel & { engine: typeof INCLUDE_TEXT_ENGINE | typeof INCLUDE_BYTES_ENGINE } {
+  return (
+    isTaggedSentinel(v) && (v.engine === INCLUDE_TEXT_ENGINE || v.engine === INCLUDE_BYTES_ENGINE)
+  );
+}