@telorun/analyzer 0.1.1

package/dist/manifest-loader.js

@@ -0,0 +1,194 @@
+import { isMap, isPair, isScalar, isSeq, parseAllDocuments } from "yaml";
+import { HttpAdapter } from "./adapters/http-adapter.js";
+import { RegistryAdapter } from "./adapters/registry-adapter.js";
+import { precompileDoc } from "./precompile.js";
+export class Loader {
+    adapters = [new HttpAdapter(), new RegistryAdapter()];
+    constructor(extraAdapters = []) {
+        this.adapters.unshift(...extraAdapters);
+    }
+    register(adapter) {
+        this.adapters.unshift(adapter);
+        return this;
+    }
+    pick(url) {
+        const a = this.adapters.find((a) => a.supports(url));
+        if (!a)
+            throw new Error(`No adapter found for: ${url}`);
+        return a;
+    }
+    async loadModule(url, options) {
+        const { text, source } = await this.pick(url).read(url);
+        const parsedDocuments = parseAllDocuments(text);
+        const rawDocs = parsedDocuments.map((d) => d.toJSON());
+        const offsets = documentLineOffsets(text);
+        const lineOffsets = buildLineOffsets(text);
+        const resolved = [];
+        let docIdx = 0;
+        for (const rawDoc of rawDocs) {
+            const currentDocIdx = docIdx++;
+            const sourceLine = offsets[currentDocIdx] ?? 0;
+            const positionIndex = buildPositionIndex(parsedDocuments[currentDocIdx], lineOffsets);
+            if (rawDoc === null || rawDoc === undefined)
+                continue;
+            let compiledDocs;
+            if (options?.compile) {
+                try {
+                    const result = precompileDoc(rawDoc);
+                    compiledDocs = Array.isArray(result) ? result : [result];
+                }
+                catch (error) {
+                    throw new Error(`Failed to compile manifest in ${source}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                compiledDocs = [rawDoc];
+            }
+            for (const doc of compiledDocs) {
+                if (doc === null || doc === undefined)
+                    continue;
+                const manifest = doc;
+                const metadata = { ...manifest.metadata, source, sourceLine };
+                // positionIndex is non-enumerable so it is invisible to spread, JSON.stringify,
+                // and schema validation — but still accessible via (m.metadata as any).positionIndex.
+                Object.defineProperty(metadata, "positionIndex", {
+                    value: positionIndex,
+                    enumerable: false,
+                    writable: true,
+                    configurable: true,
+                });
+                resolved.push({ ...manifest, metadata });
+            }
+        }
+        const moduleManifests = resolved.filter((m) => m.kind === "Kernel.Module");
+        if (moduleManifests.length > 1) {
+            throw new Error(`File '${source}' contains ${moduleManifests.length} Kernel.Module declarations. Maximum one is allowed.`);
+        }
+        const moduleManifest = moduleManifests[0];
+        const moduleName = moduleManifest?.metadata?.name;
+        if (moduleName) {
+            for (const manifest of resolved) {
+                if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
+                    manifest.metadata = { ...manifest.metadata, module: moduleName };
+                }
+            }
+        }
+        return resolved;
+    }
+    async loadManifests(entryUrl) {
+        const visited = new Set([entryUrl]);
+        const entry = await this.loadModule(entryUrl);
+        const importedDefs = [];
+        const queue = [...entry];
+        while (queue.length > 0) {
+            const m = queue.shift();
+            if (m.kind !== "Kernel.Import")
+                continue;
+            const importSource = m.source;
+            if (!importSource)
+                continue;
+            const base = m.metadata?.source ?? entryUrl;
+            const importUrl = this.pick(base).resolveRelative(base, importSource);
+            if (visited.has(importUrl))
+                continue;
+            visited.add(importUrl);
+            let imported;
+            try {
+                imported = await this.loadModule(importUrl);
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                e.sourceLine = m.metadata?.sourceLine ?? 0;
+                throw e;
+            }
+            const importedModule = imported.find((im) => im.kind === "Kernel.Module");
+            if (importedModule?.metadata?.name) {
+                m.metadata = {
+                    ...m.metadata,
+                    resolvedModuleName: importedModule.metadata.name,
+                    resolvedNamespace: importedModule.metadata.namespace ?? null,
+                };
+            }
+            for (const im of imported) {
+                if (im.kind === "Kernel.Definition")
+                    importedDefs.push(im);
+                if (im.kind === "Kernel.Import")
+                    queue.push(im);
+            }
+        }
+        return [...entry, ...importedDefs];
+    }
+}
+function documentLineOffsets(text) {
+    const offsets = [0];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trimEnd();
+        if (t === "---" || t.startsWith("--- "))
+            offsets.push(i + 1);
+    }
+    return offsets;
+}
+/** Builds a byte-offset-to-line/character lookup table from raw text. */
+function buildLineOffsets(text) {
+    const offsets = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n")
+            offsets.push(i + 1);
+    }
+    return offsets;
+}
+function offsetToPosition(offset, lineOffsets) {
+    let lo = 0;
+    let hi = lineOffsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineOffsets[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo, character: offset - lineOffsets[lo] };
+}
+/** Walks the YAML AST and records source ranges for every field value, keyed by
+ *  dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+function buildPositionIndex(doc, lineOffsets) {
+    const index = new Map();
+    function recordNode(node, path) {
+        if (!node || !node.range)
+            return;
+        const [start, , end] = node.range;
+        index.set(path, {
+            start: offsetToPosition(start, lineOffsets),
+            end: offsetToPosition(end, lineOffsets),
+        });
+    }
+    function walk(node, path) {
+        if (isMap(node)) {
+            for (const pair of node.items) {
+                if (!isPair(pair))
+                    continue;
+                const key = isScalar(pair.key) ? String(pair.key.value) : null;
+                if (key == null)
+                    continue;
+                const childPath = path ? `${path}.${key}` : key;
+                if (pair.value != null) {
+                    recordNode(pair.value, childPath);
+                    walk(pair.value, childPath);
+                }
+            }
+        }
+        else if (isSeq(node)) {
+            for (let i = 0; i < node.items.length; i++) {
+                const item = node.items[i];
+                const childPath = `${path}[${i}]`;
+                recordNode(item, childPath);
+                walk(item, childPath);
+            }
+        }
+    }
+    if (doc.contents) {
+        walk(doc.contents, "");
+    }
+    return index;
+}

package/dist/normalize-inline-resources.d.ts

@@ -0,0 +1,22 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { AliasResolver } from "./alias-resolver.js";
+/**
+ * Phase 2 — Inline resource normalization.
+ *
+ * After all manifests and definitions are loaded, walks every non-system resource's
+ * x-telo-ref slots. For each inline resource value (has keys beyond kind/name/metadata),
+ * assigns a deterministic name, extracts it as a first-class manifest, and replaces
+ * the inline value in-place with `{kind, name}`. Newly extracted resources are enqueued
+ * so nested inlines are resolved in the same pass.
+ *
+ * Naming scheme:
+ *   {parentName}_{pathSegment}[_{itemName|index}]_{fieldName}
+ *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
+ *        TestBasicAddition_steps_0_invoke  (when step has no name)
+ *
+ * Returns a new array containing the original manifests (mutated in-place) plus all
+ * extracted manifests. The original array is not mutated.
+ */
+export declare function normalizeInlineResources(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver): ResourceManifest[];
+//# sourceMappingURL=normalize-inline-resources.d.ts.map

package/dist/normalize-inline-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-inline-resources.d.ts","sourceRoot":"","sources":["../src/normalize-inline-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,GACtB,gBAAgB,EAAE,CAkDpB"}

package/dist/normalize-inline-resources.js

@@ -0,0 +1,136 @@
+import { isRefEntry, isScopeEntry, isInlineResource } from "./reference-field-map.js";
+const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Module", "Kernel.Import"]);
+/** Replaces characters outside [a-zA-Z0-9_] with underscores. */
+function sanitizeName(raw) {
+    return raw.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+/**
+ * Phase 2 — Inline resource normalization.
+ *
+ * After all manifests and definitions are loaded, walks every non-system resource's
+ * x-telo-ref slots. For each inline resource value (has keys beyond kind/name/metadata),
+ * assigns a deterministic name, extracts it as a first-class manifest, and replaces
+ * the inline value in-place with `{kind, name}`. Newly extracted resources are enqueued
+ * so nested inlines are resolved in the same pass.
+ *
+ * Naming scheme:
+ *   {parentName}_{pathSegment}[_{itemName|index}]_{fieldName}
+ *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
+ *        TestBasicAddition_steps_0_invoke  (when step has no name)
+ *
+ * Returns a new array containing the original manifests (mutated in-place) plus all
+ * extracted manifests. The original array is not mutated.
+ */
+export function normalizeInlineResources(resources, registry, aliases) {
+    const result = [...resources];
+    // Queue: all non-system resources with a name. Extracted resources are appended.
+    const queue = resources.filter((r) => typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind));
+    let i = 0;
+    while (i < queue.length) {
+        const resource = queue[i++];
+        const fieldMap = registry.getFieldMapForKind(resource.kind, aliases);
+        if (!fieldMap)
+            continue;
+        const parentName = resource.metadata.name;
+        const parentModule = resource.metadata.module;
+        // Collect scope visibility prefixes so we can route extracted resources correctly.
+        const scopePrefixes = [];
+        for (const [, entry] of fieldMap) {
+            if (!isScopeEntry(entry))
+                continue;
+            const paths = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
+            for (const p of paths) {
+                scopePrefixes.push(p.replace(/^\//, "").replace(/\//g, "."));
+            }
+        }
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isRefEntry(entry))
+                continue;
+            const inScope = scopePrefixes.some((prefix) => fieldPath === prefix ||
+                fieldPath.startsWith(prefix + ".") ||
+                fieldPath.startsWith(prefix + "["));
+            const invocationContext = isRefEntry(entry) ? entry.context : undefined;
+            const extracted = extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext);
+            for (const manifest of extracted) {
+                result.push(manifest);
+                queue.push(manifest);
+                // TODO Phase 5: when inScope, add to parent's scope array instead of outer set
+                void inScope;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal).
+ * Mutates the resource in-place: replaces each inline value with `{kind, name}`.
+ * Returns the extracted manifests.
+ */
+function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext) {
+    const extracted = [];
+    const parts = fieldPath.split(".");
+    function traverse(obj, partsLeft, nameParts) {
+        if (!obj || typeof obj !== "object" || partsLeft.length === 0)
+            return;
+        const [head, ...rest] = partsLeft;
+        const isArr = head.endsWith("[]");
+        const key = isArr ? head.slice(0, -2) : head;
+        const container = obj;
+        const val = container[key];
+        if (val == null)
+            return;
+        if (isArr) {
+            if (!Array.isArray(val))
+                return;
+            for (let idx = 0; idx < val.length; idx++) {
+                const elem = val[idx];
+                if (!elem || typeof elem !== "object")
+                    continue;
+                const elemId = typeof elem.name === "string"
+                    ? elem.name
+                    : String(idx);
+                if (rest.length === 0) {
+                    // Array element itself is the ref slot
+                    if (isInlineResource(elem)) {
+                        const name = sanitizeName([parentName, ...nameParts, key, elemId].join("_"));
+                        extracted.push(buildManifest(elem, name, parentModule, invocationContext));
+                        val[idx] = { kind: elem.kind, name };
+                    }
+                }
+                else {
+                    traverse(elem, rest, [...nameParts, key, elemId]);
+                }
+            }
+        }
+        else {
+            if (rest.length === 0) {
+                // val is the ref slot
+                if (val && typeof val === "object" && !Array.isArray(val) && isInlineResource(val)) {
+                    const name = sanitizeName([parentName, ...nameParts, key].join("_"));
+                    extracted.push(buildManifest(val, name, parentModule, invocationContext));
+                    container[key] = { kind: val.kind, name };
+                }
+            }
+            else {
+                traverse(val, rest, [...nameParts, key]);
+            }
+        }
+    }
+    traverse(resource, parts, []);
+    return extracted;
+}
+function buildManifest(inline, name, parentModule, invocationContext) {
+    const existingMeta = inline.metadata && typeof inline.metadata === "object"
+        ? inline.metadata
+        : {};
+    return {
+        ...inline,
+        metadata: {
+            ...existingMeta,
+            name,
+            // Inherit parent module only if the inline doesn't already declare one
+            ...(parentModule && !existingMeta.module ? { module: parentModule } : {}),
+            ...(invocationContext ? { xTeloInvocationContext: invocationContext } : {}),
+        },
+    };
+}

package/dist/precompile.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Walks a raw YAML document and replaces all "${{ expr }}" strings with
+ * CompiledValue wrappers. Throws on CEL syntax errors.
+ * Intended to be called once per document at load time.
+ * Kernel.Definition documents are returned unchanged — their schema fields
+ * are static metadata and must not be treated as CEL templates.
+ */
+export declare function precompileDoc(doc: unknown): unknown;
+//# sourceMappingURL=precompile.d.ts.map

package/dist/precompile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAanD"}

package/dist/precompile.js

@@ -0,0 +1,51 @@
+import { celEnvironment } from "./cel-environment.js";
+const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+/**
+ * Walks a raw YAML document and replaces all "${{ expr }}" strings with
+ * CompiledValue wrappers. Throws on CEL syntax errors.
+ * Intended to be called once per document at load time.
+ * Kernel.Definition documents are returned unchanged — their schema fields
+ * are static metadata and must not be treated as CEL templates.
+ */
+export function precompileDoc(doc) {
+    if (typeof doc === "string")
+        return compileString(doc);
+    if (Array.isArray(doc))
+        return doc.map(precompileDoc);
+    // Only recurse into plain objects. Class instances (ResourceInstance, ScopeHandle, etc.)
+    // are returned as-is — their prototype methods must not be lost by object reconstruction.
+    if (doc !== null && typeof doc === "object" && Object.getPrototypeOf(doc) === Object.prototype) {
+        const result = {};
+        for (const [k, v] of Object.entries(doc)) {
+            result[k] = precompileDoc(v);
+        }
+        return result;
+    }
+    return doc;
+}
+function compileString(s) {
+    if (!s.includes("${{"))
+        return s;
+    const exact = s.match(EXACT_TEMPLATE_REGEX);
+    if (exact) {
+        const fn = celEnvironment.parse(exact[1].trim());
+        return { __compiled: true, call: (ctx) => fn(ctx) };
+    }
+    // Interpolated template — collect literal parts + compiled sub-expressions
+    const parts = [];
+    let last = 0;
+    for (const m of s.matchAll(TEMPLATE_REGEX)) {
+        if (m.index > last)
+            parts.push(s.slice(last, m.index));
+        const fn = celEnvironment.parse(m[1].trim());
+        parts.push({ __compiled: true, call: (ctx) => fn(ctx) });
+        last = m.index + m[0].length;
+    }
+    if (last < s.length)
+        parts.push(s.slice(last));
+    return {
+        __compiled: true,
+        call: (ctx) => parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
+    };
+}

package/dist/reference-field-map.d.ts

@@ -0,0 +1,53 @@
+/** An entry for a field that carries one or more x-telo-ref constraints. */
+export interface RefFieldEntry {
+    /** One or more canonical ref strings ("namespace/module#TypeName" or "kernel#TypeName").
+     *  Multiple entries arise from anyOf branches. */
+    refs: string[];
+    /** True when the field path traversed through at least one array (path contains "[]"). */
+    isArray: boolean;
+    /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
+     *  context available to resources placed in this slot. */
+    context?: Record<string, any>;
+}
+/** An entry for a field that declares an execution scope (x-telo-scope). */
+export interface ScopeFieldEntry {
+    /** JSON Pointer(s) (RFC 6901) declaring where x-telo-ref slots within this field can
+     *  resolve to the scoped resources. */
+    scope: string | string[];
+}
+/** An entry for a field whose schema is resolved dynamically from a referenced resource's
+ *  definition schema (x-telo-schema-from). */
+export interface SchemaFromFieldEntry {
+    /** Full path expression as written in the schema, e.g.:
+     *  - "backend/$defs/NodeOptions"   (relative: sibling x-telo-ref property)
+     *  - "/backend/$defs/NodeOptions"  (absolute: root-level x-telo-ref property) */
+    schemaFrom: string;
+}
+export type FieldMapEntry = RefFieldEntry | ScopeFieldEntry | SchemaFromFieldEntry;
+/** Map from field path to its reference or scope metadata.
+ *  Paths use dot notation; array traversal is denoted by `[]` (e.g. "steps[].invoke"). */
+export type ReferenceFieldMap = Map<string, FieldMapEntry>;
+export declare function isRefEntry(entry: FieldMapEntry): entry is RefFieldEntry;
+export declare function isScopeEntry(entry: FieldMapEntry): entry is ScopeFieldEntry;
+export declare function isSchemaFromEntry(entry: FieldMapEntry): entry is SchemaFromFieldEntry;
+/** Keys that a named reference object may have. Values beyond these indicate an inline resource. */
+export declare const REFERENCE_KEYS: Set<string>;
+/** True when `val` is an inline resource definition rather than a named reference.
+ *  A named reference (has string `name`) may carry extra keys (e.g. `inputs`) that
+ *  are runtime call parameters — those are never inline resources. */
+export declare function isInlineResource(val: Record<string, unknown>): boolean;
+/** Resolves all values at a field map path in a resource config.
+ *  `[]` in a path segment means "iterate array at this key". */
+export declare function resolveFieldValues(obj: unknown, path: string): unknown[];
+/**
+ * Traverses a definition's JSON Schema once and returns a field map recording every
+ * x-telo-ref slot and every x-telo-scope slot.
+ *
+ * - A node with `x-telo-ref` → RefFieldEntry with refs: [that value]
+ * - A node with `anyOf` whose branches have `x-telo-ref` → RefFieldEntry with all branch refs
+ * - A node with `x-telo-scope` → ScopeFieldEntry
+ * - A node with `type: array` + `items` → recurse into items with path "fieldName[]"
+ * - A node with `properties` → recurse into each property
+ */
+export declare function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFieldMap;
+//# sourceMappingURL=reference-field-map.d.ts.map

package/dist/reference-field-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;sDACkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;sEAEsE;AACtE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAGtE;AAED;gEACgE;AAChE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAiBxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF"}

package/dist/reference-field-map.js

@@ -0,0 +1,107 @@
+export function isRefEntry(entry) {
+    return "refs" in entry;
+}
+export function isScopeEntry(entry) {
+    return "scope" in entry;
+}
+export function isSchemaFromEntry(entry) {
+    return "schemaFrom" in entry;
+}
+/** Keys that a named reference object may have. Values beyond these indicate an inline resource. */
+export const REFERENCE_KEYS = new Set(["kind", "name", "metadata"]);
+/** True when `val` is an inline resource definition rather than a named reference.
+ *  A named reference (has string `name`) may carry extra keys (e.g. `inputs`) that
+ *  are runtime call parameters — those are never inline resources. */
+export function isInlineResource(val) {
+    if (typeof val.name === "string")
+        return false;
+    return Object.keys(val).some((k) => !REFERENCE_KEYS.has(k));
+}
+/** Resolves all values at a field map path in a resource config.
+ *  `[]` in a path segment means "iterate array at this key". */
+export function resolveFieldValues(obj, path) {
+    const parts = path.split(".");
+    let current = [obj];
+    for (const part of parts) {
+        const isArray = part.endsWith("[]");
+        const key = isArray ? part.slice(0, -2) : part;
+        const next = [];
+        for (const item of current) {
+            if (!item || typeof item !== "object")
+                continue;
+            const val = item[key];
+            if (val == null)
+                continue;
+            if (isArray && Array.isArray(val))
+                next.push(...val);
+            else if (!isArray)
+                next.push(val);
+        }
+        current = next;
+    }
+    return current;
+}
+/**
+ * Traverses a definition's JSON Schema once and returns a field map recording every
+ * x-telo-ref slot and every x-telo-scope slot.
+ *
+ * - A node with `x-telo-ref` → RefFieldEntry with refs: [that value]
+ * - A node with `anyOf` whose branches have `x-telo-ref` → RefFieldEntry with all branch refs
+ * - A node with `x-telo-scope` → ScopeFieldEntry
+ * - A node with `type: array` + `items` → recurse into items with path "fieldName[]"
+ * - A node with `properties` → recurse into each property
+ */
+export function buildReferenceFieldMap(schema) {
+    const map = new Map();
+    if (schema.properties) {
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+            traverseNode(propSchema, key, map);
+        }
+    }
+    return map;
+}
+function collectRefs(node) {
+    const refs = [];
+    if (typeof node["x-telo-ref"] === "string") {
+        refs.push(node["x-telo-ref"]);
+    }
+    if (Array.isArray(node.anyOf)) {
+        for (const branch of node.anyOf) {
+            if (branch && typeof branch["x-telo-ref"] === "string") {
+                refs.push(branch["x-telo-ref"]);
+            }
+        }
+    }
+    return refs;
+}
+function traverseNode(node, path, map) {
+    // Scope slot — record and stop; do not recurse into scope contents
+    if ("x-telo-scope" in node) {
+        map.set(path, { scope: node["x-telo-scope"] });
+        return;
+    }
+    // Schema-from slot — record and stop; no further traversal needed
+    if ("x-telo-schema-from" in node) {
+        map.set(path, { schemaFrom: node["x-telo-schema-from"] });
+        return;
+    }
+    // Reference slot (direct or via anyOf)
+    const refs = collectRefs(node);
+    if (refs.length > 0) {
+        const entry = { refs, isArray: path.includes("[]") };
+        if (node["x-telo-context"])
+            entry.context = node["x-telo-context"];
+        map.set(path, entry);
+        return;
+    }
+    // Array — recurse into items
+    if (node.type === "array" && node.items) {
+        traverseNode(node.items, path + "[]", map);
+    }
+    // Object — recurse into properties
+    if (node.properties) {
+        for (const [key, propSchema] of Object.entries(node.properties)) {
+            traverseNode(propSchema, `${path}.${key}`, map);
+        }
+    }
+}

package/dist/schema-compat.d.ts

@@ -0,0 +1,42 @@
+declare const Ajv: any;
+/** Creates a configured AJV instance (allErrors, strict: false, with formats).
+ *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+export declare function createAjv(): InstanceType<typeof Ajv>;
+export interface CompatibilityResult {
+    compatible: boolean;
+    issues: string[];
+}
+/** Conservative structural JSON Schema compatibility check.
+ *  Only flags definite mismatches: missing required fields and primitive type conflicts.
+ *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
+export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>): CompatibilityResult;
+export declare function formatSingleError(err: any): string;
+export declare function formatAjvErrors(errors: any[] | null | undefined): string;
+/** A schema validation issue with a dotted-path pointer to the offending field. */
+export interface SchemaIssue {
+    message: string;
+    /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
+    path: string;
+}
+/** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
+export declare function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[];
+/** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
+ *  Returns undefined when any segment along the path is missing or not an object. */
+export declare function navigateJsonPointer(schema: unknown, pointer: string): unknown;
+/** Navigate a JSON Schema following a `walkCelExpressions`-style path
+ *  (e.g. `port`, `routes[0].handler.when`).
+ *  Dot-separated segments navigate `properties`; `[N]` indices navigate `items`.
+ *  Stops and returns the current node when a union type (`anyOf`/`oneOf`) is reached.
+ *  Returns `undefined` if any segment cannot be resolved. */
+export declare function navigateSchemaToExprPath(schema: Record<string, any>, path: string): Record<string, any> | undefined;
+/** Map a JSON Schema type annotation to a CEL type string. */
+export declare function jsonSchemaToCelType(schema: Record<string, any> | undefined): string;
+/** Check whether a CEL return type is compatible with a JSON Schema type constraint. */
+export declare function celTypeSatisfiesJsonSchema(celType: string, schema: Record<string, any>): boolean;
+/** Return a literal placeholder value of the correct schema type for AJV. */
+export declare function celPlaceholderForSchema(schema: Record<string, any>): unknown;
+/** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
+ *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
+export declare function substituteCelFields(data: unknown, schema: Record<string, any>): unknown;
+export {};
+//# sourceMappingURL=schema-compat.d.ts.map

package/dist/schema-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;0FAC0F;AAC1F,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAMpD;AAID,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAGlD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAY/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAgBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,OAAO,CAqBT;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAW5E;AAID;iGACiG;AACjG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBvF"}