@telorun/analyzer 0.1.2 → 0.1.4

package/src/manifest-loader.ts

@@ -1,17 +1,25 @@
-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,
-  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(["Kernel.Module", "Kernel.Import", "Kernel.Definition"]);
+
 export class Loader {
+  private static readonly moduleCache = new Map<
+    string,
+    { text: string; manifests: ResourceManifest[] }
+  >();
+
   protected adapters: ManifestAdapter[];
 
   constructor(extraAdaptersOrOptions: ManifestAdapter[] | LoaderInitOptions = []) {
@@ -49,6 +57,12 @@ export class Loader {
 
   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);
@@ -117,9 +131,152 @@ export class Loader {
       }
     }
 
+    // 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);
+          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 Kernel.Import sources.
+    try {
+      const docs = await this.loadModule(fileUrl);
+      const hasModule = docs.some((d) => d.kind === "Kernel.Module");
+      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,
@@ -215,6 +372,46 @@ 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 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/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;
@@ -131,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) => ({
@@ -260,25 +264,55 @@ export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
 
 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;
@@ -42,6 +45,16 @@ export interface ManifestAdapter {
   supports(url: string): boolean;
   read(url: string): Promise<{ text: string; source: string }>;
   resolveRelative(base: string, relative: string): string;
+
+  /** Expand glob patterns relative to a base source. Returns sources in the same
+   *  format as read().source — suitable to pass back into read() / resolveRelative().
+   *  Optional — only filesystem-capable adapters implement this. */
+  expandGlob?(base: string, patterns: string[]): Promise<string[]>;
+
+  /** Walk parent directories from fileUrl looking for the nearest telo.yaml.
+   *  Returns the source in the same format as read().source, or null if none found.
+   *  Optional — only filesystem-capable adapters implement this. */
+  resolveOwnerOf?(fileUrl: string): Promise<string | null>;
 }
 
 export interface LoadOptions {

package/src/validate-references.ts

@@ -134,10 +134,22 @@ export function validateReferences(
         if (!val) continue;
 
         // Name-only reference (plain string) — look up by name to validate.
+        // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
+        // extract the resource name from the last dot segment.
         if (typeof val === "string") {
+          const lastDot = val.lastIndexOf(".");
+          const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
+          const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
           const target =
-            byName.get(val) ?? visibleScopeManifests.find((m) => m.metadata?.name === val);
+            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
           if (!target) {
+            // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
+            // The resource lives in the imported module's scope and can't be validated here.
+            // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
+            // kinds — those must be validated.
+            if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
+              continue;
+            }
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",

package/src/adapters/node-adapter.ts

@@ -1,38 +0,0 @@
-import * as fs from "fs/promises";
-import * as path from "path";
-import type { ManifestAdapter } from "../types.js";
-
-/** Node.js fs-based ManifestAdapter for local files. Not browser-compatible. */
-export class NodeAdapter implements ManifestAdapter {
-  constructor(private readonly cwd: string = process.cwd()) {}
-
-  supports(url: string): boolean {
-    return (
-      url.startsWith("file://") ||
-      url.startsWith("/") ||
-      url.startsWith("./") ||
-      url.startsWith("../") ||
-      (!url.includes("://") && !url.includes("@"))
-    );
-  }
-
-  async read(url: string): Promise<{ text: string; source: string }> {
-    const filePath = url.startsWith("file://") ? new URL(url).pathname : url;
-    const stat = await fs.stat(filePath).catch(() => null);
-    const resolvedPath =
-      stat?.isDirectory() ? path.join(filePath, "module.yaml") : filePath;
-    const text = await fs.readFile(resolvedPath, "utf8");
-    return { text, source: resolvedPath };
-  }
-
-  resolveRelative(base: string, relative: string): string {
-    const basePath = base.startsWith("file://") ? new URL(base).pathname : base;
-    const baseDir = path.dirname(path.resolve(this.cwd, basePath));
-    return path.resolve(baseDir, relative);
-  }
-}
-
-/** @deprecated Use `new NodeAdapter(cwd)` instead */
-export function createNodeAdapter(cwd: string = process.cwd()): ManifestAdapter {
-  return new NodeAdapter(cwd);
-}