@telorun/templating 0.12.0 → 0.14.0

package/src/manifest-schemas.ts

@@ -60,104 +60,6 @@ export const ResourceRefSchema = {
   ],
 };
 
-const REF_ANNOTATION = "x-telo-ref";
-
-// The legacy base types a reference slot used to pin when references were
-// written as plain strings. Post-migration a reference resolves to an object
-// (the `{kind, name, alias?}` shape, or an unresolved `!ref` sentinel), so a
-// scalar `type` on a ref slot is a stale constraint that would reject the
-// resolved value. Object / array `type`s are left alone — they already admit
-// the reference object (and any inline value a slot like `inputType` accepts).
-const LEGACY_REF_SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
-
-// JSON Schema keywords whose values are themselves subschemas. Split by shape so
-// the ref-slot normalizer recurses only into schema positions — never into
-// data-bearing keywords (`default`, `const`, `enum`, `examples`), where a stray
-// `x-telo-ref` key would be data, not an annotation.
-const SUBSCHEMA_SINGLE = [
-  "additionalProperties",
-  "additionalItems",
-  "contains",
-  "not",
-  "if",
-  "then",
-  "else",
-  "propertyNames",
-  "unevaluatedItems",
-  "unevaluatedProperties",
-] as const;
-const SUBSCHEMA_LIST = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
-const SUBSCHEMA_MAP = [
-  "properties",
-  "patternProperties",
-  "$defs",
-  "definitions",
-  "dependentSchemas",
-] as const;
-
-/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
- *  reference-slot node — one carrying an `x-telo-ref` string annotation.
- *
- *  A reference slot's value is always a `!ref` sentinel or its resolved
- *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
- *  published modules still pin `type: "string"` on these slots — the encoding
- *  references took when they were written as plain strings — which now rejects
- *  the resolved object. Removing only the scalar `type` lets the analyzer and
- *  kernel accept references uniformly across module versions during the
- *  migration away from `{kind, name}` / string references, without disturbing
- *  slots that legitimately accept an inline object (e.g. `inputType` /
- *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
- *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
- *  checked separately by the analyzer's reference walker, which reads the
- *  original schema — not this validation-only copy. */
-export function normalizeRefSlots(schema: unknown): unknown {
-  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
-    return schema;
-  }
-  const node = schema as Record<string, 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 (
-    node[REF_ANNOTATION] !== undefined &&
-    typeof node.type === "string" &&
-    LEGACY_REF_SCALAR_TYPES.has(node.type)
-  ) {
-    delete out.type;
-  }
-  for (const key of SUBSCHEMA_SINGLE) {
-    const value = node[key];
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-      out[key] = normalizeRefSlots(value);
-    }
-  }
-  for (const key of SUBSCHEMA_LIST) {
-    const value = node[key];
-    if (Array.isArray(value)) out[key] = value.map(normalizeRefSlots);
-  }
-  // `items` is either a single subschema or a tuple of subschemas.
-  if (Array.isArray(node.items)) {
-    out.items = node.items.map(normalizeRefSlots);
-  } else if (node.items && typeof node.items === "object") {
-    out.items = normalizeRefSlots(node.items);
-  }
-  for (const key of SUBSCHEMA_MAP) {
-    const value = node[key];
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-      const mapped: Record<string, unknown> = {};
-      for (const [name, sub] of Object.entries(value as Record<string, unknown>)) {
-        mapped[name] = normalizeRefSlots(sub);
-      }
-      out[key] = mapped;
-    }
-  }
-  return out;
-}
 
 /** Stable URI under which the shared manifest root schema is registered
  *  with module-side AJV instances. Module YAMLs reach the fragments via

package/src/sentinel.ts

@@ -32,3 +32,65 @@ export function makeTaggedSentinel(engine: string, source: string): TaggedSentin
 export function isRefSentinel(v: unknown): v is TaggedSentinel & { engine: "ref" } {
   return isTaggedSentinel(v) && v.engine === "ref";
 }
+
+/** The CEL engine's name. Beside the other sentinel predicates for the same
+ *  reason they are: a consumer that spells an engine name inline is a second
+ *  place the registry's key is written down. */
+export const CEL_ENGINE = "cel";
+
+/** 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";
+
+/**
+ * The dotted chain a value names, or undefined.
+ *
+ * Only a PLAIN CHAIN — `steps.encode.result.output` — in either spelling a
+ * manifest may carry it: a `!cel` sentinel or the `${{ }}` string form. An
+ * expression that COMPUTES rather than names has no schema to read off a context,
+ * so a caller that navigates one gets nothing and reports nothing: silence where
+ * the analyzer knows least is the conservative direction.
+ *
+ * Here rather than in each caller because "is this expression a plain chain" is
+ * one question, and two copies of the answer would eventually disagree about a
+ * shape like `a.b[0]`.
+ */
+export function plainChainOf(value: unknown): string | undefined {
+  const source = isTaggedSentinel(value)
+    ? value.engine === CEL_ENGINE
+      ? value.source
+      : undefined
+    : typeof value === "string"
+      ? /^\s*\$\{\{(.+)\}\}\s*$/.exec(value)?.[1]
+      : undefined;
+  if (typeof source !== "string") return undefined;
+  const trimmed = source.trim();
+  return /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(trimmed)
+    ? trimmed
+    : undefined;
+}
+
+/** 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)
+  );
+}