@telorun/analyzer 0.1.3 → 0.2.0

package/src/manifest-loader.ts

@@ -1,16 +1,27 @@
+import type { Environment } from "@marcbachmann/cel-js";
 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 { buildCelEnvironment } from "./cel-environment.js";
+import { isModuleKind } from "./module-kinds.js";
 import { precompileDoc } from "./precompile.js";
-import type {
-  LoadOptions,
-  LoaderInitOptions,
-  ManifestAdapter,
-  Position,
-  PositionIndex,
+import {
+  DEFAULT_MANIFEST_FILENAME,
+  type LoadOptions,
+  type LoaderInitOptions,
+  type ManifestAdapter,
+  type Position,
+  type PositionIndex,
 } from "./types.js";
 
+const SYSTEM_KINDS = new Set([
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+  "Telo.Definition",
+]);
+
 export class Loader {
   private static readonly moduleCache = new Map<
     string,
@@ -18,6 +29,7 @@ export class Loader {
   >();
 
   protected adapters: ManifestAdapter[];
+  private readonly celEnv: Environment;
 
   constructor(extraAdaptersOrOptions: ManifestAdapter[] | LoaderInitOptions = []) {
     const options: LoaderInitOptions = Array.isArray(extraAdaptersOrOptions)
@@ -34,6 +46,8 @@ export class Loader {
     if (options.extraAdapters?.length) {
       this.adapters.unshift(...options.extraAdapters);
     }
+
+    this.celEnv = buildCelEnvironment(options.celHandlers);
   }
 
   register(adapter: ManifestAdapter): this {
@@ -76,7 +90,7 @@ export class Loader {
       let compiledDocs: unknown[];
       if (options?.compile) {
         try {
-          const result = precompileDoc(rawDoc);
+          const result = precompileDoc(rawDoc, this.celEnv);
           compiledDocs = Array.isArray(result) ? result : [result];
         } catch (error) {
           throw new Error(
@@ -103,17 +117,19 @@ export class Loader {
       }
     }
 
-    const moduleManifests = resolved.filter((m) => m.kind === "Kernel.Module");
+    const moduleManifests = resolved.filter((m) => isModuleKind(m.kind));
     if (moduleManifests.length > 1) {
+      const kinds = moduleManifests.map((m) => m.kind).join(", ");
       throw new Error(
-        `File '${source}' contains ${moduleManifests.length} Kernel.Module declarations. Maximum one is allowed.`,
+        `File '${source}' contains ${moduleManifests.length} module declarations (${kinds}). ` +
+          `A file may declare at most one Telo.Application or Telo.Library.`,
       );
     }
     const moduleManifest = moduleManifests[0];
     const moduleName = moduleManifest?.metadata?.name as string | undefined;
     if (moduleName) {
       for (const manifest of resolved) {
-        if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
+        if (!isModuleKind(manifest.kind) && !manifest.metadata?.module) {
           const pi = (manifest.metadata as any)?.positionIndex;
           manifest.metadata = { ...manifest.metadata, module: moduleName };
           if (pi) {
@@ -128,10 +144,152 @@ export class Loader {
       }
     }
 
-    Loader.moduleCache.set(cacheKey, { text, manifests: resolved });
+    // Expand include directives — load partial files into the same module scope.
+    // Results with includes are NOT cached because partial file content is not
+    // tracked in the cache key — the cache would serve stale data if a partial changes.
+    let hasIncludes = false;
+    if (moduleManifest) {
+      const includePatterns = (moduleManifest as any).include as string[] | undefined;
+      if (includePatterns?.length) {
+        hasIncludes = true;
+        const adapter = this.pick(source);
+        const includedFiles = await this.resolveIncludes(source, includePatterns, adapter);
+        for (const includedUrl of includedFiles) {
+          const partialManifests = await this.loadPartialFile(includedUrl, moduleName, options);
+          resolved.push(...partialManifests);
+        }
+      }
+    }
+
+    if (!hasIncludes) {
+      Loader.moduleCache.set(cacheKey, { text, manifests: resolved });
+    }
     return cloneManifestArray(resolved);
   }
 
+  private async resolveIncludes(
+    ownerSource: string,
+    patterns: string[],
+    adapter: ManifestAdapter,
+  ): Promise<string[]> {
+    const hasGlobs = patterns.some((p) => /[*?{}\[\]]/.test(p));
+    if (hasGlobs) {
+      if (!adapter.expandGlob) {
+        throw new Error(
+          `Include patterns in '${ownerSource}' contain globs but the adapter for this source ` +
+            `does not support glob expansion. Use explicit file paths instead of patterns like: ` +
+            patterns.filter((p) => /[*?{}\[\]]/.test(p)).join(", "),
+        );
+      }
+      return adapter.expandGlob(ownerSource, patterns);
+    }
+    // Literal relative paths — deduplicate in case the same file appears under multiple patterns.
+    return [...new Set(patterns.map((p) => adapter.resolveRelative(ownerSource, p)))];
+  }
+
+  private async loadPartialFile(
+    url: string,
+    ownerModuleName: string | undefined,
+    options?: LoadOptions,
+  ): Promise<ResourceManifest[]> {
+    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: ResourceManifest[] = [];
+    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;
+
+      const kind = rawDoc.kind as string | undefined;
+      if (kind && SYSTEM_KINDS.has(kind)) {
+        throw new Error(
+          `Included file '${source}' contains '${kind}' which is not allowed in partial files. ` +
+            `Only the owner telo.yaml may declare ${kind} resources.`,
+        );
+      }
+
+      let compiledDocs: unknown[];
+      if (options?.compile) {
+        try {
+          const result = precompileDoc(rawDoc, this.celEnv);
+          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 as ResourceManifest;
+        const metadata = {
+          ...manifest.metadata,
+          source,
+          sourceLine,
+          ...(ownerModuleName && !manifest.metadata?.module ? { module: ownerModuleName } : {}),
+        };
+        Object.defineProperty(metadata, "positionIndex", {
+          value: positionIndex,
+          enumerable: false,
+          writable: true,
+          configurable: true,
+        });
+        resolved.push({ ...manifest, metadata });
+      }
+    }
+
+    return resolved;
+  }
+
+  async loadModuleForFile(
+    fileUrl: string,
+  ): Promise<{
+    ownerUrl: string;
+    manifests: ResourceManifest[];
+    sourceManifests: Map<string, ResourceManifest[]>;
+  } | null> {
+    // Try loading as a regular module first (it might be a telo.yaml itself).
+    // Use loadManifests (not loadModule) so imported definitions are included —
+    // otherwise the analyzer won't know about kinds from Telo.Import sources.
+    try {
+      const docs = await this.loadModule(fileUrl);
+      const hasModule = docs.some((d) => isModuleKind(d.kind));
+      if (hasModule) {
+        const { source } = await this.pick(fileUrl).read(fileUrl);
+        const manifests = await this.loadManifests(fileUrl);
+        return { ownerUrl: source, manifests, sourceManifests: groupBySource(manifests) };
+      }
+    } catch (err) {
+      // If the file looks like an owner manifest (named telo.yaml), rethrow —
+      // a broken owner shouldn't silently fall through to parent lookup.
+      const normalized = fileUrl.replace(/\\/g, "/");
+      if (normalized.endsWith(`/${DEFAULT_MANIFEST_FILENAME}`) || normalized === DEFAULT_MANIFEST_FILENAME) {
+        throw err;
+      }
+      // Otherwise fall through to owner lookup — this is likely a partial file
+    }
+
+    // Find the owning telo.yaml via parent-directory traversal
+    const adapter = this.pick(fileUrl);
+    if (!adapter.resolveOwnerOf) return null;
+    const ownerUrl = await adapter.resolveOwnerOf(fileUrl);
+    if (!ownerUrl) return null;
+
+    // Load the owner module (which will load included files via include expansion)
+    const manifests = await this.loadManifests(ownerUrl);
+    return { ownerUrl, manifests, sourceManifests: groupBySource(manifests) };
+  }
+
   async loadModuleGraph(
     entryUrl: string,
     onError?: (url: string, error: Error) => void,
@@ -146,7 +304,7 @@ export class Loader {
 
     while (queue.length > 0) {
       const m = queue.shift()!;
-      if (m.kind !== "Kernel.Import") continue;
+      if (m.kind !== "Telo.Import") continue;
       const importSource = (m as any).source as string | undefined;
       if (!importSource) continue;
       const base = (m.metadata as any)?.source ?? entryUrl;
@@ -166,7 +324,7 @@ export class Loader {
       }
       result.set(importUrl, imported);
       for (const im of imported) {
-        if (im.kind === "Kernel.Import") queue.push(im);
+        if (im.kind === "Telo.Import") queue.push(im);
       }
     }
 
@@ -182,7 +340,7 @@ export class Loader {
 
     while (queue.length > 0) {
       const m = queue.shift()!;
-      if (m.kind !== "Kernel.Import") continue;
+      if (m.kind !== "Telo.Import") continue;
       const importSource = (m as any).source as string | undefined;
       if (!importSource) continue;
       const base = (m.metadata as any)?.source ?? entryUrl;
@@ -200,7 +358,20 @@ export class Loader {
         (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
         throw e;
       }
-      const importedModule = imported.find((im) => im.kind === "Kernel.Module");
+      // Import target must be a Telo.Library. Check the Library branch
+      // explicitly rather than "anything that's a module kind" so that a
+      // future third kind can't silently slip past as a valid import target.
+      const importedLibrary = imported.find((im) => im.kind === "Telo.Library");
+      const importedApplication = imported.find((im) => im.kind === "Telo.Application");
+      if (importedApplication) {
+        const e = new Error(
+          `Telo.Import target '${importSource}' is a Telo.Application. ` +
+            `Only Telo.Library modules may be imported. Applications are run directly, not imported.`,
+        );
+        (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
+        throw e;
+      }
+      const importedModule = importedLibrary;
       if (importedModule?.metadata?.name) {
         const pi = (m.metadata as any)?.positionIndex;
         m.metadata = {
@@ -218,8 +389,8 @@ export class Loader {
         }
       }
       for (const im of imported) {
-        if (im.kind === "Kernel.Definition") importedDefs.push(im);
-        if (im.kind === "Kernel.Import") queue.push(im);
+        if (im.kind === "Telo.Definition") importedDefs.push(im);
+        if (im.kind === "Telo.Import") queue.push(im);
       }
     }
 
@@ -253,6 +424,20 @@ function cloneManifestValue<T>(value: T): T {
   return value;
 }
 
+function groupBySource(manifests: ResourceManifest[]): Map<string, ResourceManifest[]> {
+  const map = new Map<string, ResourceManifest[]>();
+  for (const m of manifests) {
+    const src = (m.metadata?.source as string) ?? "unknown";
+    let list = map.get(src);
+    if (!list) {
+      list = [];
+      map.set(src, list);
+    }
+    list.push(m);
+  }
+  return map;
+}
+
 function documentLineOffsets(text: string): number[] {
   const offsets = [0];
   const lines = text.split("\n");

package/src/module-kinds.ts

@@ -0,0 +1,6 @@
+export const MODULE_KINDS = ["Telo.Application", "Telo.Library"] as const;
+export type ModuleKind = (typeof MODULE_KINDS)[number];
+
+export function isModuleKind(kind: string | undefined): kind is ModuleKind {
+  return kind === "Telo.Application" || kind === "Telo.Library";
+}

package/src/normalize-inline-resources.ts

@@ -3,7 +3,12 @@ import { isRefEntry, isScopeEntry, isInlineResource } from "./reference-field-ma
 import type { DefinitionRegistry } from "./definition-registry.js";
 import type { AliasResolver } from "./alias-resolver.js";
 
-const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Module", "Kernel.Import"]);
+const SYSTEM_KINDS = new Set([
+  "Telo.Definition",
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+]);
 
 /** Replaces characters outside [a-zA-Z0-9_] with underscores. */
 function sanitizeName(raw: string): string {

package/src/precompile.ts

@@ -1,5 +1,5 @@
 import type { CompiledValue } from "@telorun/sdk";
-import { celEnvironment } from "./cel-environment.js";
+import type { Environment } from "@marcbachmann/cel-js";
 
 const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
@@ -8,31 +8,32 @@ 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
+ * Telo.Definition documents are returned unchanged — their schema fields
  * are static metadata and must not be treated as CEL templates.
  */
-export function precompileDoc(doc: unknown): unknown {
-  if (typeof doc === "string") return compileString(doc);
-  if (Array.isArray(doc)) return doc.map(precompileDoc);
+export function precompileDoc(doc: unknown, env: Environment): unknown {
+  if (typeof doc === "string") return compileString(doc, env);
+  if (Array.isArray(doc)) return doc.map((item) => precompileDoc(item, env));
   // 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: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(doc as Record<string, unknown>)) {
-      result[k] = precompileDoc(v);
+      result[k] = precompileDoc(v, env);
     }
     return result;
   }
   return doc;
 }
 
-function compileString(s: string): unknown {
+function compileString(s: string, env: Environment): unknown {
   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: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue;
+    const expr = exact[1].trim();
+    const fn = env.parse(expr);
+    return { __compiled: true, source: expr, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue;
   }
 
   // Interpolated template — collect literal parts + compiled sub-expressions
@@ -40,14 +41,16 @@ function compileString(s: string): unknown {
   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: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue);
+    const expr = m[1].trim();
+    const fn = env.parse(expr);
+    parts.push({ __compiled: true, source: expr, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue);
     last = m.index! + m[0].length;
   }
   if (last < s.length) parts.push(s.slice(last));
 
   return {
     __compiled: true,
+    source: s,
     call: (ctx: Record<string, unknown>) =>
       parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
   } satisfies CompiledValue;

package/src/reference-field-map.ts

@@ -1,6 +1,6 @@
 /** 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").
+  /** One or more canonical ref strings ("namespace/module#TypeName" or "telo#TypeName").
    *  Multiple entries arise from anyOf branches. */
   refs: string[];
   /** True when the field path traversed through at least one array (path contains "[]"). */