@telorun/analyzer 0.1.1 → 0.1.3

package/dist/kernel-globals.d.ts

@@ -0,0 +1,34 @@
+import type { ResourceManifest } from "@telorun/sdk";
+/**
+ * Kernel global names available in every CEL evaluation context at runtime.
+ * Both `buildKernelGlobalsSchema` (chain-access validation) and
+ * `buildTypedCelEnvironment` in cel-environment.ts (CEL type-checking)
+ * must stay in sync with this list.
+ *
+ * Note: `env` is only available in the root module context. Child modules
+ * loaded via Kernel.Import do not receive host environment variables.
+ * There is no `imports` namespace at runtime — import snapshots are stored
+ * under `resources.<alias>`.
+ */
+export declare const KERNEL_GLOBAL_NAMES: readonly ["variables", "secrets", "resources", "env"];
+/**
+ * Build a typed JSON Schema describing the kernel globals available in the
+ * given manifest set. Used to merge into `x-telo-context` schemas so that
+ * chain-access validation recognises kernel globals without module authors
+ * having to re-declare them.
+ *
+ * - `variables` / `secrets`: typed from the `Kernel.Module` declaration
+ * - `resources`: enumerates all non-system resource names
+ * - `env`: dynamic (runtime env vars, root module only)
+ */
+export declare function buildKernelGlobalsSchema(manifests: ResourceManifest[]): Record<string, any>;
+/**
+ * Merge kernel globals into an `x-telo-context` schema so chain-access
+ * validation recognises `variables`, `secrets`, `resources`, `env`
+ * without module authors having to re-declare them.
+ *
+ * Context-specific properties take precedence over globals (spread order).
+ * The original `additionalProperties` setting is preserved.
+ */
+export declare function mergeKernelGlobalsIntoContext(contextSchema: Record<string, any>, globalsSchema: Record<string, any>): Record<string, any>;
+//# sourceMappingURL=kernel-globals.d.ts.map

package/dist/kernel-globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-globals.d.ts","sourceRoot":"","sources":["../src/kernel-globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,uDAAwD,CAAC;AAQzF;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA6BrB;AA2BD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB"}

package/dist/kernel-globals.js

@@ -0,0 +1,94 @@
+/**
+ * Kernel global names available in every CEL evaluation context at runtime.
+ * Both `buildKernelGlobalsSchema` (chain-access validation) and
+ * `buildTypedCelEnvironment` in cel-environment.ts (CEL type-checking)
+ * must stay in sync with this list.
+ *
+ * Note: `env` is only available in the root module context. Child modules
+ * loaded via Kernel.Import do not receive host environment variables.
+ * There is no `imports` namespace at runtime — import snapshots are stored
+ * under `resources.<alias>`.
+ */
+export const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "env"];
+const SYSTEM_KINDS = new Set([
+    "Kernel.Definition",
+    "Kernel.Module",
+    "Kernel.Abstract",
+]);
+/**
+ * Build a typed JSON Schema describing the kernel globals available in the
+ * given manifest set. Used to merge into `x-telo-context` schemas so that
+ * chain-access validation recognises kernel globals without module authors
+ * having to re-declare them.
+ *
+ * - `variables` / `secrets`: typed from the `Kernel.Module` declaration
+ * - `resources`: enumerates all non-system resource names
+ * - `env`: dynamic (runtime env vars, root module only)
+ */
+export function buildKernelGlobalsSchema(manifests) {
+    const moduleManifest = manifests.find((m) => m.kind === "Kernel.Module");
+    const resourceProps = {};
+    for (const m of manifests) {
+        const name = m.metadata?.name;
+        if (!name || !m.kind)
+            continue;
+        // Kernel.Import snapshots are stored under resources.<alias> at runtime,
+        // so they appear here alongside regular resources.
+        if (!SYSTEM_KINDS.has(m.kind)) {
+            resourceProps[name] = { type: "object", additionalProperties: true };
+        }
+    }
+    return {
+        type: "object",
+        properties: {
+            variables: buildSchemaMapSchema(moduleManifest?.variables),
+            secrets: buildSchemaMapSchema(moduleManifest?.secrets),
+            resources: {
+                type: "object",
+                properties: resourceProps,
+                additionalProperties: false,
+            },
+            env: { type: "object", additionalProperties: true },
+        },
+    };
+}
+/** Wrap a JSON Schema property map (like `Kernel.Module.variables`) into a
+ *  closed object schema suitable for chain-access validation. Falls back to
+ *  an open map when the module declares no variables/secrets. */
+function buildSchemaMapSchema(schemaMap) {
+    if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
+        return { type: "object", additionalProperties: true };
+    }
+    const props = {};
+    for (const [key, value] of Object.entries(schemaMap)) {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            props[key] = value;
+        }
+    }
+    if (Object.keys(props).length === 0) {
+        return { type: "object", additionalProperties: true };
+    }
+    return {
+        type: "object",
+        properties: props,
+        additionalProperties: false,
+    };
+}
+/**
+ * Merge kernel globals into an `x-telo-context` schema so chain-access
+ * validation recognises `variables`, `secrets`, `resources`, `env`
+ * without module authors having to re-declare them.
+ *
+ * Context-specific properties take precedence over globals (spread order).
+ * The original `additionalProperties` setting is preserved.
+ */
+export function mergeKernelGlobalsIntoContext(contextSchema, globalsSchema) {
+    return {
+        ...contextSchema,
+        properties: {
+            ...globalsSchema.properties,
+            ...(contextSchema.properties ?? {}),
+        },
+        additionalProperties: contextSchema.additionalProperties ?? false,
+    };
+}

package/dist/manifest-loader.d.ts

@@ -1,11 +1,14 @@
-import type { ResourceManifest } from "@telorun/sdk";
-import type { LoadOptions, ManifestAdapter } from "./types.js";
+import { type ResourceManifest } from "@telorun/sdk";
+import type { LoadOptions, LoaderInitOptions, ManifestAdapter } from "./types.js";
 export declare class Loader {
+    private static readonly moduleCache;
     protected adapters: ManifestAdapter[];
-    constructor(extraAdapters?: ManifestAdapter[]);
+    constructor(extraAdaptersOrOptions?: ManifestAdapter[] | LoaderInitOptions);
     register(adapter: ManifestAdapter): this;
     private pick;
+    resolveEntryPoint(url: string): Promise<string>;
     loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]>;
+    loadModuleGraph(entryUrl: string, onError?: (url: string, error: Error) => void): Promise<Map<string, ResourceManifest[]>>;
     loadManifests(entryUrl: string): Promise<ResourceManifest[]>;
 }
 //# sourceMappingURL=manifest-loader.d.ts.map

package/dist/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AAExF,qBAAa,MAAM;IACjB,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,CAA8C;gBAEvE,aAAa,GAAE,eAAe,EAAO;IAIjD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKxC,OAAO,CAAC,IAAI;IAMN,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgE3E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAwCnE"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKtE,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAEpB,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAG/B;IAEJ,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;gBAE1B,sBAAsB,GAAE,eAAe,EAAE,GAAG,iBAAsB;IAiB9E,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKxC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgF3E,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAoDnE"}

package/dist/manifest-loader.js

@@ -1,11 +1,25 @@
+import { isCompiledValue } from "@telorun/sdk";
 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);
+    static moduleCache = new Map();
+    adapters;
+    constructor(extraAdaptersOrOptions = []) {
+        const options = Array.isArray(extraAdaptersOrOptions)
+            ? { extraAdapters: extraAdaptersOrOptions }
+            : extraAdaptersOrOptions;
+        const includeHttpAdapter = options.includeHttpAdapter ?? true;
+        const includeRegistryAdapter = options.includeRegistryAdapter ?? true;
+        this.adapters = [];
+        if (includeHttpAdapter)
+            this.adapters.push(new HttpAdapter());
+        if (includeRegistryAdapter)
+            this.adapters.push(new RegistryAdapter(options.registryUrl));
+        if (options.extraAdapters?.length) {
+            this.adapters.unshift(...options.extraAdapters);
+        }
     }
     register(adapter) {
         this.adapters.unshift(adapter);
@@ -17,8 +31,17 @@ export class Loader {
             throw new Error(`No adapter found for: ${url}`);
         return a;
     }
+    async resolveEntryPoint(url) {
+        const { source } = await this.pick(url).read(url);
+        return source;
+    }
     async loadModule(url, options) {
         const { text, source } = await this.pick(url).read(url);
+        const cacheKey = `${options?.compile ? "compiled" : "raw"}:${source}`;
+        const cached = Loader.moduleCache.get(cacheKey);
+        if (cached && cached.text === text) {
+            return cloneManifestArray(cached.manifests);
+        }
         const parsedDocuments = parseAllDocuments(text);
         const rawDocs = parsedDocuments.map((d) => d.toJSON());
         const offsets = documentLineOffsets(text);
@@ -69,11 +92,58 @@ export class Loader {
         if (moduleName) {
             for (const manifest of resolved) {
                 if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
+                    const pi = manifest.metadata?.positionIndex;
                     manifest.metadata = { ...manifest.metadata, module: moduleName };
+                    if (pi) {
+                        Object.defineProperty(manifest.metadata, "positionIndex", {
+                            value: pi,
+                            enumerable: false,
+                            writable: true,
+                            configurable: true,
+                        });
+                    }
                 }
             }
         }
-        return resolved;
+        Loader.moduleCache.set(cacheKey, { text, manifests: resolved });
+        return cloneManifestArray(resolved);
+    }
+    async loadModuleGraph(entryUrl, onError) {
+        const visited = new Set([entryUrl]);
+        const result = new Map();
+        const entry = await this.loadModule(entryUrl);
+        result.set(entryUrl, entry);
+        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 = importSource.startsWith(".") || importSource.startsWith("/")
+                ? this.pick(base).resolveRelative(base, importSource)
+                : importSource;
+            if (visited.has(importUrl))
+                continue;
+            visited.add(importUrl);
+            let imported;
+            try {
+                imported = await this.loadModule(importUrl);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                onError?.(importUrl, error);
+                continue;
+            }
+            result.set(importUrl, imported);
+            for (const im of imported) {
+                if (im.kind === "Kernel.Import")
+                    queue.push(im);
+            }
+        }
+        return result;
     }
     async loadManifests(entryUrl) {
         const visited = new Set([entryUrl]);
@@ -88,7 +158,9 @@ export class Loader {
             if (!importSource)
                 continue;
             const base = m.metadata?.source ?? entryUrl;
-            const importUrl = this.pick(base).resolveRelative(base, importSource);
+            const importUrl = importSource.startsWith(".") || importSource.startsWith("/")
+                ? this.pick(base).resolveRelative(base, importSource)
+                : importSource;
             if (visited.has(importUrl))
                 continue;
             visited.add(importUrl);
@@ -103,11 +175,20 @@ export class Loader {
             }
             const importedModule = imported.find((im) => im.kind === "Kernel.Module");
             if (importedModule?.metadata?.name) {
+                const pi = m.metadata?.positionIndex;
                 m.metadata = {
                     ...m.metadata,
                     resolvedModuleName: importedModule.metadata.name,
                     resolvedNamespace: importedModule.metadata.namespace ?? null,
                 };
+                if (pi) {
+                    Object.defineProperty(m.metadata, "positionIndex", {
+                        value: pi,
+                        enumerable: false,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
             }
             for (const im of imported) {
                 if (im.kind === "Kernel.Definition")
@@ -119,6 +200,30 @@ export class Loader {
         return [...entry, ...importedDefs];
     }
 }
+function cloneManifestArray(manifests) {
+    return manifests.map((manifest) => cloneManifestValue(manifest));
+}
+function cloneManifestValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneManifestValue(entry));
+    }
+    if (isCompiledValue(value)) {
+        return value;
+    }
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const clone = {};
+        for (const [key, entry] of Object.entries(source)) {
+            clone[key] = cloneManifestValue(entry);
+        }
+        const positionIndex = Object.getOwnPropertyDescriptor(source, "positionIndex");
+        if (positionIndex) {
+            Object.defineProperty(clone, "positionIndex", positionIndex);
+        }
+        return clone;
+    }
+    return value;
+}
 function documentLineOffsets(text) {
     const offsets = [0];
     const lines = text.split("\n");

package/dist/schema-compat.d.ts

@@ -37,6 +37,6 @@ export declare function celTypeSatisfiesJsonSchema(celType: string, schema: Reco
 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 declare function substituteCelFields(data: unknown, schema: Record<string, any>, rootSchema?: Record<string, any>): unknown;
 export {};
 //# sourceMappingURL=schema-compat.d.ts.map

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

@@ -1 +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"}
+{"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;AAKD,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,CAelD;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,CAe/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,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAwBT"}

package/dist/schema-compat.js

@@ -11,6 +11,7 @@ export function createAjv() {
     return instance;
 }
 const ajv = createAjv();
+const compiledSchemaValidators = new WeakMap();
 /** 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. */
@@ -51,7 +52,19 @@ function checkProperty(source, target, path, issues) {
 }
 export function formatSingleError(err) {
     const p = err.instancePath || "/";
-    return `${p} ${err.message ?? "is invalid"}`;
+    const params = err.params ?? {};
+    switch (err.keyword) {
+        case "additionalProperties":
+            return `${p} must NOT have additional properties ('${params.additionalProperty}' is not allowed)`;
+        case "required":
+            return `${p} is missing required property '${params.missingProperty}'`;
+        case "enum":
+            return `${p} ${err.message ?? "is invalid"} (${params.allowedValues?.join(" | ")})`;
+        case "type":
+            return `${p} must be ${params.type} (got ${typeof err.data})`;
+        default:
+            return `${p} ${err.message ?? "is invalid"}`;
+    }
 }
 export function formatAjvErrors(errors) {
     if (!errors || errors.length === 0)
@@ -81,12 +94,15 @@ function ajvErrorToPath(err) {
 }
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data, schema) {
-    let validate;
-    try {
-        validate = ajv.compile(schema);
-    }
-    catch {
-        return [];
+    let validate = compiledSchemaValidators.get(schema);
+    if (!validate) {
+        try {
+            validate = ajv.compile(schema);
+            compiledSchemaValidators.set(schema, validate);
+        }
+        catch {
+            return [];
+        }
     }
     if (validate(data))
         return [];
@@ -153,13 +169,20 @@ export function jsonSchemaToCelType(schema) {
     if (Array.isArray(schema.type))
         return "dyn";
     switch (schema.type) {
-        case "integer": return "int";
-        case "number": return "double";
-        case "string": return "string";
-        case "boolean": return "bool";
-        case "array": return "list";
-        case "object": return "map";
-        case "null": return "null_type";
+        case "integer":
+            return "int";
+        case "number":
+            return "double";
+        case "string":
+            return "string";
+        case "boolean":
+            return "bool";
+        case "array":
+            return "list";
+        case "object":
+            return "map";
+        case "null":
+            return "null_type";
     }
     if (schema.properties)
         return "map";
@@ -200,33 +223,64 @@ export function celPlaceholderForSchema(schema) {
         return schema.default;
     switch (schema.type) {
         case "integer":
-        case "number": return schema.minimum ?? 0;
-        case "string": return "";
-        case "boolean": return false;
-        case "array": return [];
-        case "object": return {};
-        default: return null;
+        case "number":
+            return schema.minimum ?? 0;
+        case "string":
+            return "";
+        case "boolean":
+            return false;
+        case "array":
+            return [];
+        case "object":
+            return {};
+        default:
+            return null;
     }
 }
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
+/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
+function resolveRef(schema, root) {
+    if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
+        const defName = schema.$ref.slice("#/$defs/".length);
+        const resolved = root.$defs?.[defName];
+        if (resolved)
+            return resolved;
+    }
+    return schema;
+}
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+function collectProperties(schema) {
+    const props = { ...(schema.properties ?? {}) };
+    for (const sub of schema.oneOf ?? schema.anyOf ?? []) {
+        if (sub && typeof sub === "object" && sub.properties) {
+            for (const [k, v] of Object.entries(sub.properties)) {
+                if (!(k in props))
+                    props[k] = v;
+            }
+        }
+    }
+    return props;
+}
 /** 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 function substituteCelFields(data, schema) {
+export function substituteCelFields(data, schema, rootSchema) {
+    const root = rootSchema ?? schema;
+    const resolved = resolveRef(schema, root);
     if (typeof data === "string" && CEL_PURE_RE.test(data)) {
-        return celPlaceholderForSchema(schema);
+        return celPlaceholderForSchema(resolved);
     }
     if (Array.isArray(data)) {
-        const itemSchema = (schema.items ?? {});
-        return data.map((item) => substituteCelFields(item, itemSchema));
+        const itemSchema = resolveRef((resolved.items ?? {}), root);
+        return data.map((item) => substituteCelFields(item, itemSchema, root));
     }
     if (data !== null && typeof data === "object") {
-        const props = (schema.properties ?? {});
-        const addlProps = schema.additionalProperties && typeof schema.additionalProperties === "object"
-            ? schema.additionalProperties
+        const props = collectProperties(resolved);
+        const addlProps = resolved.additionalProperties && typeof resolved.additionalProperties === "object"
+            ? resolved.additionalProperties
             : undefined;
         const result = {};
         for (const [k, v] of Object.entries(data)) {
-            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}));
+            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}), root);
         }
         return result;
     }

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export declare const DiagnosticSeverity: {
     readonly Hint: 4;
 };
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
+/** Default entry-point filename when a directory is given instead of a file. */
+export declare const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 export interface Position {
     /** 0-based line number */
     line: number;
@@ -48,6 +50,16 @@ export interface LoadOptions {
      *  the analyzer works on raw strings and does not need compiled values. */
     compile?: boolean;
 }
+export interface LoaderInitOptions {
+    /** Adapters inserted with highest priority before built-ins. */
+    extraAdapters?: ManifestAdapter[];
+    /** Include built-in HttpAdapter. Defaults to true. */
+    includeHttpAdapter?: boolean;
+    /** Include built-in RegistryAdapter. Defaults to true. */
+    includeRegistryAdapter?: boolean;
+    /** Base URL used by built-in RegistryAdapter when enabled. */
+    registryUrl?: string;
+}
 export interface AnalysisOptions {
     strictContexts?: boolean;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}

package/dist/types.js

@@ -6,3 +6,5 @@ export const DiagnosticSeverity = {
     Information: 3,
     Hint: 4,
 };
+/** Default entry-point filename when a directory is given instead of a file. */
+export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";

package/dist/validate-cel-context.d.ts

@@ -1,4 +1,11 @@
 import type { ASTNode } from "@marcbachmann/cel-js";
+/**
+ * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
+ * - String: look up the named type in allManifests (Type.JsonSchema resources)
+ * - Object with `kind` + `schema`: inline type definition → return the `schema`
+ * - Object with `type` or `properties`: raw JSON Schema, return as-is
+ */
+export declare function resolveTypeFieldToSchema(value: unknown, allManifests: Record<string, any>[]): Record<string, any> | undefined;
 /**
  * Extract all member-access chains from a CEL AST.
  * Returns arrays like ["request", "query", "name"] for `request.query.name`.
@@ -14,11 +21,26 @@ export declare function extractAccessChains(node: ASTNode): string[][];
  */
 export declare function validateChainAgainstSchema(chain: string[], schema: Record<string, any>): string | null;
 /**
- * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].handler.inputs.name")
- * falls within the container region of a context scope (e.g. "$.routes[*].handler").
+ * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
+ * falls within the scope of a context (e.g. "$.routes[*].inputs").
  *
- * The container is derived by stripping the last dot-separated segment from the scope, so that
- * sibling fields within the same parent (e.g. routes[*].response) also match.
+ * The scope is matched directly (no sibling sharing): a context at "$.routes[*].inputs" only
+ * applies to expressions whose path starts with "routes[N].inputs", not to other sibling fields.
  */
 export declare function pathMatchesScope(exprPath: string, scope: string): boolean;
+/**
+ * Resolves `x-telo-context-from` annotations in a context schema using the concrete
+ * manifest item. Navigates the manifest item at the given slash-separated path and merges
+ * the result as named properties into the annotated node (locking additionalProperties: false).
+ *
+ * Example: `x-telo-context-from: "request/schema"` on the `request` context node replaces
+ * the open `request` schema with a closed schema whose properties are the keys of
+ * `manifestItem.request.schema` (e.g. `query`, `body`, `params`, `headers`).
+ */
+export declare function resolveContextAnnotations(schema: Record<string, any>, manifestItem: Record<string, any>, allManifests?: Record<string, any>[]): Record<string, any>;
+/**
+ * Extracts the concrete manifest array item for a given expression path + scope.
+ * e.g. exprPath="routes[0].inputs.q", scope="$.routes[*].inputs" → manifest.routes[0]
+ */
+export declare function getManifestItem(exprPath: string, scope: string, manifest: Record<string, any>): Record<string, any>;
 //# sourceMappingURL=validate-cel-context.d.ts.map

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AAwED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CAiBf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAsBzE"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AAwED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CAmBf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqDrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}