@telorun/analyzer 0.1.1 → 0.1.2

package/dist/validate-cel-context.js

@@ -1,3 +1,34 @@
+/**
+ * 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 function resolveTypeFieldToSchema(value, allManifests) {
+    if (!value)
+        return undefined;
+    if (typeof value === "string") {
+        // Named type reference — find a Kernel.Type resource by name
+        const typeManifest = allManifests.find((m) => m.metadata?.name === value &&
+            typeof m.kind === "string" &&
+            /\bType\b/.test(m.kind) &&
+            typeof m.schema === "object" &&
+            m.schema !== null);
+        return typeManifest?.schema;
+    }
+    if (typeof value === "object" && value !== null) {
+        const obj = value;
+        // Inline type resource: { kind: "Type.JsonSchema", schema: {...} }
+        if (obj.schema && typeof obj.schema === "object") {
+            return obj.schema;
+        }
+        // Raw JSON Schema (has type or properties)
+        if (obj.type || obj.properties) {
+            return obj;
+        }
+    }
+    return undefined;
+}
 /**
  * Extract all member-access chains from a CEL AST.
  * Returns arrays like ["request", "query", "name"] for `request.query.name`.
@@ -87,36 +118,36 @@ export function validateChainAgainstSchema(chain, schema) {
         const key = chain[i];
         if (!current || typeof current !== "object")
             return null;
-        // Open schema: no properties declared or explicitly allows additional properties
         const props = current.properties;
         if (!props)
             return null;
+        if (key in props) {
+            // Known property — drill into it even if additionalProperties is true
+            current = props[key];
+            continue;
+        }
+        // Unknown property — only flag if schema is closed
         if (current.additionalProperties === true)
             return null;
-        if (!(key in props)) {
-            const path = chain.slice(0, i + 1).join(".");
-            const available = Object.keys(props).join(", ");
-            return `'${path}' is not defined (available: ${available})`;
-        }
-        current = props[key];
+        const path = chain.slice(0, i + 1).join(".");
+        const available = Object.keys(props).join(", ");
+        return `'${path}' is not defined (available: ${available})`;
     }
     return 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 function pathMatchesScope(exprPath, scope) {
     const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
-    const lastDot = stripped.lastIndexOf(".");
-    if (lastDot <= 0)
+    if (!stripped)
         return false;
-    const container = stripped.slice(0, lastDot); // e.g. "routes[*]"
     // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
-    const parts = container.split("[*]");
+    const parts = stripped.split("[*]");
     let remaining = exprPath;
     for (let i = 0; i < parts.length; i++) {
         const part = parts[i];
@@ -134,3 +165,80 @@ export function pathMatchesScope(exprPath, scope) {
     // Expression must end here or continue into a child path
     return remaining === "" || remaining[0] === "." || remaining[0] === "[";
 }
+/**
+ * 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 function resolveContextAnnotations(schema, manifestItem, allManifests) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const from = schema["x-telo-context-from"];
+    if (from) {
+        const resolved = navigatePath(manifestItem, from.split("/"));
+        // `resolved` is a map of property names → sub-schemas (e.g. { query: {...}, body: {...} })
+        return {
+            ...schema,
+            properties: { ...(schema.properties ?? {}), ...(resolved ?? {}) },
+            additionalProperties: false,
+        };
+    }
+    const refFrom = schema["x-telo-context-ref-from"];
+    if (refFrom && allManifests) {
+        const slashIdx = refFrom.indexOf("/");
+        const refProp = slashIdx === -1 ? refFrom : refFrom.slice(0, slashIdx);
+        const subpath = slashIdx === -1 ? undefined : refFrom.slice(slashIdx + 1);
+        const ref = manifestItem[refProp];
+        if (ref &&
+            typeof ref === "object" &&
+            typeof ref.kind === "string" &&
+            typeof ref.name === "string" &&
+            subpath) {
+            const refManifest = allManifests.find((m) => m.kind === ref.kind && m.metadata?.name === ref.name);
+            if (refManifest) {
+                const resolved = resolveTypeFieldToSchema(navigatePath(refManifest, subpath.split("/")), allManifests);
+                if (resolved && typeof resolved === "object") {
+                    return resolved;
+                }
+            }
+        }
+        // Fallback: open schema (no false errors when outputType is not declared)
+        return { ...schema, additionalProperties: true };
+    }
+    if (schema.properties) {
+        const props = {};
+        for (const [k, v] of Object.entries(schema.properties)) {
+            props[k] = resolveContextAnnotations(v, manifestItem, allManifests);
+        }
+        return { ...schema, properties: props };
+    }
+    return schema;
+}
+/**
+ * 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 function getManifestItem(exprPath, scope, manifest) {
+    const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+    const wildcardIdx = stripped.indexOf("[*]");
+    if (wildcardIdx === -1)
+        return manifest;
+    const arrayProp = stripped.slice(0, wildcardIdx); // e.g. "routes"
+    const m = exprPath.match(new RegExp(`^${arrayProp}\\[(\\d+)\\]`));
+    if (!m)
+        return manifest;
+    return manifest[arrayProp]?.[Number(m[1])] ?? manifest;
+}
+function navigatePath(obj, segments) {
+    let cur = obj;
+    for (const seg of segments) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -22,7 +22,7 @@
     "ajv-formats": "^3.0.1",
     "yaml": "^2.8.3",
     "jsonpath-plus": "^10.3.0",
-    "@telorun/sdk": "0.2.6"
+    "@telorun/sdk": "0.2.7"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/adapters/http-adapter.ts

@@ -17,7 +17,7 @@ export class HttpAdapter implements ManifestAdapter {
   }
 
   resolveRelative(base: string, relative: string): string {
-    const baseWithSlash = base.endsWith("/") ? base : `${base}/`;
-    return new URL(relative, baseWithSlash).href;
+    const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);
+    return new URL(relative, baseDir).href;
   }
 }

package/src/adapters/registry-adapter.ts

@@ -1,8 +1,10 @@
 import type { ManifestAdapter } from "../types.js";
 
-const REGISTRY_BASE = "https://registry.telo.run";
+const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
 
 export class RegistryAdapter implements ManifestAdapter {
+  constructor(private registryUrl = DEFAULT_REGISTRY_URL) {}
+
   supports(url: string): boolean {
     return (
       !url.startsWith("http://") &&
@@ -26,18 +28,38 @@ export class RegistryAdapter implements ManifestAdapter {
   }
 
   resolveRelative(base: string, relative: string): string {
-    const baseUrl = this.supports(base)
-      ? this.toRegistryUrl(base).replace("/module.yaml", "")
-      : base;
+    const baseUrl = this.supports(base) ? this.toRegistryModuleBase(base) : base;
     const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
     return new URL(relative, baseWithSlash).href;
   }
 
+  private toRegistryModuleBase(moduleRef: string): string {
+    const parsed = this.parseModuleRef(moduleRef);
+    const normalizedBase = this.registryUrl.replace(/\/+$/, "");
+    return `${normalizedBase}/${parsed.modulePath}/${parsed.version}`;
+  }
+
   private toRegistryUrl(moduleRef: string): string {
+    return `${this.toRegistryModuleBase(moduleRef)}/module.yaml`;
+  }
+
+  private parseModuleRef(moduleRef: string): { modulePath: string; version: string } {
     const atIdx = moduleRef.lastIndexOf("@");
+    if (atIdx <= 0 || atIdx === moduleRef.length - 1) {
+      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
+    }
+
     const modulePath = moduleRef.slice(0, atIdx);
-    const version = moduleRef.slice(atIdx + 1);
-    const versionSegment = version.startsWith("v") ? version.substring(1) : version;
-    return `${REGISTRY_BASE}/${modulePath}/${versionSegment}/module.yaml`;
+    if (!modulePath.includes("/")) {
+      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
+    }
+
+    const rawVersion = moduleRef.slice(atIdx + 1);
+    const version = rawVersion.startsWith("v") ? rawVersion.substring(1) : rawVersion;
+    if (!version) {
+      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
+    }
+
+    return { modulePath, version };
   }
 }

package/src/analysis-registry.ts

@@ -61,6 +61,16 @@ export class AnalysisRegistry {
     return KERNEL_BUILTINS;
   }
 
+  resolveDefinition(kind: string): ResourceDefinition | undefined {
+    const ctx = this._context();
+    const resolved = ctx.aliases?.resolveKind(kind);
+    return ctx.definitions?.resolve(kind) ?? (resolved ? ctx.definitions?.resolve(resolved) : undefined);
+  }
+
+  allKinds(): string[] {
+    return this._context().definitions?.kinds() ?? [];
+  }
+
   /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
   _context(): AnalysisContext {
     return { aliases: this.aliases, definitions: this.defs };

package/src/analyzer.ts

@@ -6,15 +6,18 @@ import { DefinitionRegistry } from "./definition-registry.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import {
-  type SchemaIssue,
   celTypeSatisfiesJsonSchema,
   substituteCelFields,
   validateAgainstSchema,
+  type SchemaIssue,
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
   extractAccessChains,
+  getManifestItem,
   pathMatchesScope,
+  resolveContextAnnotations,
+  resolveTypeFieldToSchema,
   validateChainAgainstSchema,
 } from "./validate-cel-context.js";
 import { validateReferences } from "./validate-references.js";
@@ -78,6 +81,87 @@ function extractContextsFromSchema(
   return results;
 }
 
+/**
+ * Build a `steps` context schema from `x-telo-step-context` annotation.
+ * Walks each step in the manifest array, resolves the invoked resource's outputType,
+ * and builds `steps.<name>.result` context entries.
+ */
+function buildStepContextSchema(
+  manifest: Record<string, any>,
+  defSchema: Record<string, any>,
+  allManifests: Record<string, any>[],
+): Record<string, any> | undefined {
+  const props = defSchema.properties as Record<string, any> | undefined;
+  if (!props) return undefined;
+
+  for (const [fieldName, fieldSchema] of Object.entries(props)) {
+    const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
+    if (!stepCtx) continue;
+
+    const invokeField = stepCtx.invoke;
+    const outputTypeField = stepCtx.outputType;
+    if (!invokeField || !outputTypeField) continue;
+
+    const steps = manifest[fieldName];
+    if (!Array.isArray(steps)) continue;
+
+    const stepProperties: Record<string, any> = {};
+    const collectSteps = (items: unknown[]) => {
+      for (const step of items) {
+        if (!step || typeof step !== "object") continue;
+        const s = step as Record<string, any>;
+        const name = s.name;
+        if (typeof name === "string") {
+          const invoke = s[invokeField] as Record<string, any> | undefined;
+          let outputSchema: Record<string, any> | undefined;
+          if (invoke && typeof invoke === "object") {
+            const invokedKind = invoke.kind as string | undefined;
+            const invokedName = invoke.name as string | undefined;
+            if (invokedName) {
+              const invokedManifest = allManifests.find(
+                (m) =>
+                  (m.metadata as any)?.name === invokedName &&
+                  (!invokedKind || m.kind === invokedKind),
+              ) as Record<string, any> | undefined;
+              if (invokedManifest) {
+                outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
+              }
+            } else {
+              outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
+            }
+          }
+          stepProperties[name] = {
+            type: "object",
+            properties: {
+              result: outputSchema ?? { type: "object", additionalProperties: true },
+            },
+          };
+        }
+        // Recurse into nested step arrays (then, else, do, catch, finally, try, default, cases)
+        for (const nested of ["then", "else", "do", "catch", "finally", "try", "default"]) {
+          if (Array.isArray(s[nested])) collectSteps(s[nested]);
+        }
+        // cases is an object map of arrays
+        if (s.cases && typeof s.cases === "object") {
+          for (const arr of Object.values(s.cases)) {
+            if (Array.isArray(arr)) collectSteps(arr);
+          }
+        }
+      }
+    };
+    collectSteps(steps);
+
+    if (Object.keys(stepProperties).length > 0) {
+      return {
+        type: "object",
+        properties: stepProperties,
+      };
+    }
+  }
+
+  return undefined;
+}
+
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
@@ -132,7 +216,14 @@ function collectCelTypeIssues(
     const itemSchema = (schema.items ?? {}) as Record<string, any>;
     for (let i = 0; i < data.length; i++) {
       issues.push(
-        ...collectCelTypeIssues(data[i], itemSchema, `${path}[${i}]`, definition, manifest, baseEnv),
+        ...collectCelTypeIssues(
+          data[i],
+          itemSchema,
+          `${path}[${i}]`,
+          definition,
+          manifest,
+          baseEnv,
+        ),
       );
     }
   } else if (data !== null && typeof data === "object") {
@@ -310,6 +401,15 @@ export class StaticAnalyzer {
       const mDefinition =
         defs.resolve(m.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
 
+      // Pre-compute step context for manifests with x-telo-step-context
+      const stepContextSchema = mDefinition?.schema
+        ? buildStepContextSchema(
+            m as Record<string, any>,
+            mDefinition.schema as Record<string, any>,
+            allManifests as Record<string, any>[],
+          )
+        : undefined;
+
       walkCelExpressions(m, "", (expr, path) => {
         let parsed: ReturnType<typeof celEnvironment.parse> | undefined;
         try {
@@ -325,24 +425,52 @@ export class StaticAnalyzer {
           return;
         }
 
+        const accessChains = extractAccessChains(parsed.ast);
+
         const contexts = mDefinition?.schema ? extractContextsFromSchema(mDefinition.schema) : [];
         const invocationContext = (m.metadata as any)?.xTeloInvocationContext as
           | Record<string, any>
           | undefined;
-        if (contexts.length === 0 && !invocationContext) return;
+
+        // If no static context but we have step context, inject it
+        if (contexts.length === 0 && !invocationContext && !stepContextSchema) return;
 
         let matchedContext: Record<string, any> | undefined;
+        let matchedScope: string | undefined;
         for (const ctx of contexts) {
           if (pathMatchesScope(path, ctx.scope)) {
             matchedContext = ctx.schema;
+            matchedScope = ctx.scope;
             break;
           }
         }
         if (!matchedContext) matchedContext = invocationContext;
+
+        // Merge step context into the effective context
+        if (stepContextSchema) {
+          const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+          matchedContext = {
+            ...base,
+            properties: {
+              ...(base.properties ?? {}),
+              steps: stepContextSchema,
+            },
+          };
+        }
+
         if (!matchedContext) return;
 
-        for (const chain of extractAccessChains(parsed.ast)) {
-          const err = validateChainAgainstSchema(chain, matchedContext);
+        const manifestItem = matchedScope
+          ? getManifestItem(path, matchedScope, m as Record<string, any>)
+          : (m as Record<string, any>);
+        const effectiveContext = resolveContextAnnotations(
+          matchedContext,
+          manifestItem,
+          allManifests as Record<string, any>[],
+        );
+
+        for (const chain of accessChains) {
+          const err = validateChainAgainstSchema(chain, effectiveContext);
           if (!err) continue;
           diagnostics.push({
             severity: DiagnosticSeverity.Error,

package/src/index.ts

@@ -7,9 +7,7 @@ export { Loader } from "./manifest-loader.js";
 export { DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,
-    AnalysisOptions,
-    LoadOptions,
-    ManifestAdapter,
+    AnalysisOptions, LoaderInitOptions, LoadOptions, ManifestAdapter,
     Position,
     PositionIndex,
     Range

package/src/manifest-loader.ts

@@ -3,13 +3,32 @@ import { isMap, isPair, isScalar, isSeq, parseAllDocuments, type Document } from
 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()];
+  protected adapters: ManifestAdapter[];
 
-  constructor(extraAdapters: ManifestAdapter[] = []) {
-    this.adapters.unshift(...extraAdapters);
+  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,6 +42,11 @@ 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 parsedDocuments = parseAllDocuments(text);
@@ -79,7 +103,16 @@ 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,
+            });
+          }
         }
       }
     }
@@ -87,6 +120,47 @@ export class Loader {
     return 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[]> {
     const visited = new Set<string>([entryUrl]);
     const entry = await this.loadModule(entryUrl);
@@ -100,7 +174,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 +190,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);