@telorun/analyzer 0.1.1 → 0.1.3

package/src/kernel-globals.ts

@@ -0,0 +1,110 @@
+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 const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "env"] as const;
+
+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: ResourceManifest[],
+): Record<string, any> {
+  const moduleManifest = manifests.find((m) => m.kind === "Kernel.Module") as
+    | Record<string, any>
+    | undefined;
+
+  const resourceProps: Record<string, any> = {};
+  for (const m of manifests) {
+    const name = m.metadata?.name as string | undefined;
+    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: Record<string, any> | null | undefined,
+): Record<string, any> {
+  if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
+    return { type: "object", additionalProperties: true };
+  }
+  const props: Record<string, any> = {};
+  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: Record<string, any>,
+  globalsSchema: Record<string, any>,
+): Record<string, any> {
+  return {
+    ...contextSchema,
+    properties: {
+      ...globalsSchema.properties,
+      ...(contextSchema.properties ?? {}),
+    },
+    additionalProperties: contextSchema.additionalProperties ?? false,
+  };
+}

package/src/manifest-loader.ts

@@ -1,15 +1,39 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import { isCompiledValue, type ResourceManifest } from "@telorun/sdk";
 import { isMap, isPair, isScalar, isSeq, parseAllDocuments, type Document } from "yaml";
 import { HttpAdapter } from "./adapters/http-adapter.js";
 import { RegistryAdapter } from "./adapters/registry-adapter.js";
 import { precompileDoc } from "./precompile.js";
-import type { LoadOptions, ManifestAdapter, Position, PositionIndex } from "./types.js";
+import type {
+  LoadOptions,
+  LoaderInitOptions,
+  ManifestAdapter,
+  Position,
+  PositionIndex,
+} from "./types.js";
 
 export class Loader {
-  protected adapters: ManifestAdapter[] = [new HttpAdapter(), new RegistryAdapter()];
+  private static readonly moduleCache = new Map<
+    string,
+    { text: string; manifests: ResourceManifest[] }
+  >();
 
-  constructor(extraAdapters: ManifestAdapter[] = []) {
-    this.adapters.unshift(...extraAdapters);
+  protected adapters: ManifestAdapter[];
+
+  constructor(extraAdaptersOrOptions: ManifestAdapter[] | LoaderInitOptions = []) {
+    const options: LoaderInitOptions = 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: ManifestAdapter): this {
@@ -23,8 +47,19 @@ export class Loader {
     return a;
   }
 
+  async resolveEntryPoint(url: string): Promise<string> {
+    const { source } = await this.pick(url).read(url);
+    return source;
+  }
+
   async loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]> {
     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);
@@ -79,12 +114,63 @@ export class Loader {
     if (moduleName) {
       for (const manifest of resolved) {
         if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
+          const pi = (manifest.metadata as any)?.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: string,
+    onError?: (url: string, error: Error) => void,
+  ): Promise<Map<string, ResourceManifest[]>> {
+    const visited = new Set<string>([entryUrl]);
+    const result = new Map<string, ResourceManifest[]>();
+
+    const entry = await this.loadModule(entryUrl);
+    result.set(entryUrl, entry);
+
+    const queue: ResourceManifest[] = [...entry];
+
+    while (queue.length > 0) {
+      const m = queue.shift()!;
+      if (m.kind !== "Kernel.Import") continue;
+      const importSource = (m as any).source as string | undefined;
+      if (!importSource) continue;
+      const base = (m.metadata as any)?.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: ResourceManifest[];
+      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: string): Promise<ResourceManifest[]> {
@@ -100,7 +186,10 @@ export class Loader {
       const importSource = (m as any).source as string | undefined;
       if (!importSource) continue;
       const base = (m.metadata as any)?.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);
       let imported: ResourceManifest[];
@@ -113,11 +202,20 @@ export class Loader {
       }
       const importedModule = imported.find((im) => im.kind === "Kernel.Module");
       if (importedModule?.metadata?.name) {
+        const pi = (m.metadata as any)?.positionIndex;
         m.metadata = {
           ...m.metadata,
           resolvedModuleName: importedModule.metadata.name as string,
           resolvedNamespace: (importedModule.metadata as any).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") importedDefs.push(im);
@@ -129,6 +227,32 @@ export class Loader {
   }
 }
 
+function cloneManifestArray(manifests: ResourceManifest[]): ResourceManifest[] {
+  return manifests.map((manifest) => cloneManifestValue(manifest));
+}
+
+function cloneManifestValue<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneManifestValue(entry)) as T;
+  }
+  if (isCompiledValue(value)) {
+    return value;
+  }
+  if (value !== null && typeof value === "object") {
+    const source = value as Record<string, unknown>;
+    const clone: Record<string, unknown> = {};
+    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 as T;
+  }
+  return value;
+}
+
 function documentLineOffsets(text: string): number[] {
   const offsets = [0];
   const lines = text.split("\n");

package/src/schema-compat.ts

@@ -14,6 +14,7 @@ export function createAjv(): InstanceType<typeof Ajv> {
 }
 
 const ajv = createAjv();
+const compiledSchemaValidators = new WeakMap<Record<string, any>, ReturnType<typeof ajv.compile>>();
 
 export interface CompatibilityResult {
   compatible: boolean;
@@ -81,7 +82,19 @@ function checkProperty(
 
 export function formatSingleError(err: any): string {
   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 as unknown[])?.join(" | ")})`;
+    case "type":
+      return `${p} must be ${params.type} (got ${typeof err.data})`;
+    default:
+      return `${p} ${err.message ?? "is invalid"}`;
+  }
 }
 
 export function formatAjvErrors(errors: any[] | null | undefined): string {
@@ -119,11 +132,14 @@ export interface SchemaIssue {
 
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[] {
-  let validate: ReturnType<typeof ajv.compile>;
-  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 [];
   return (validate.errors ?? []).map((err: any) => ({
@@ -182,13 +198,20 @@ export function jsonSchemaToCelType(schema: Record<string, any> | undefined): st
   if (schema.anyOf || schema.oneOf || schema.allOf) return "dyn";
   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";
   if (schema.items) return "list";
@@ -196,10 +219,7 @@ export function jsonSchemaToCelType(schema: Record<string, any> | undefined): st
 }
 
 /** Check whether a CEL return type is compatible with a JSON Schema type constraint. */
-export function celTypeSatisfiesJsonSchema(
-  celType: string,
-  schema: Record<string, any>,
-): boolean {
+export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<string, any>): boolean {
   if (celType === "dyn") return true;
   if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf) return true;
   if (schema.anyOf || schema.oneOf || schema.allOf) return true;
@@ -227,36 +247,72 @@ export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
   if (schema.default !== undefined) 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: Record<string, any>, root: Record<string, any>): Record<string, any> {
+  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: Record<string, any>): Record<string, any> {
+  const props: Record<string, any> = { ...(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 as Record<string, any>)) {
+        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: unknown, schema: Record<string, any>): unknown {
+export function substituteCelFields(
+  data: unknown,
+  schema: Record<string, any>,
+  rootSchema?: Record<string, any>,
+): unknown {
+  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 ?? {}) as Record<string, any>;
-    return data.map((item) => substituteCelFields(item, itemSchema));
+    const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
+    return data.map((item) => substituteCelFields(item, itemSchema, root));
   }
   if (data !== null && typeof data === "object") {
-    const props = (schema.properties ?? {}) as Record<string, any>;
+    const props = collectProperties(resolved);
     const addlProps =
-      schema.additionalProperties && typeof schema.additionalProperties === "object"
-        ? (schema.additionalProperties as Record<string, any>)
+      resolved.additionalProperties && typeof resolved.additionalProperties === "object"
+        ? (resolved.additionalProperties as Record<string, any>)
         : undefined;
     const result: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>);
+      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>, root);
     }
     return result;
   }

package/src/types.ts

@@ -8,6 +8,9 @@ export const DiagnosticSeverity = {
 } as const;
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
 
+/** Default entry-point filename when a directory is given instead of a file. */
+export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+
 export interface Position {
   /** 0-based line number */
   line: number;
@@ -52,6 +55,17 @@ export interface LoadOptions {
   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;
 }