@telorun/analyzer 0.1.1

package/src/definition-registry.ts

@@ -0,0 +1,170 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import { KERNEL_BUILTINS } from "./builtins.js";
+import { buildReferenceFieldMap, type ReferenceFieldMap } from "./reference-field-map.js";
+import { createAjv, formatSingleError } from "./schema-compat.js";
+
+/** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+export class DefinitionRegistry {
+  constructor() {
+    for (const def of KERNEL_BUILTINS) this.register(def);
+  }
+
+  /** Per-instance AJV for cross-module $ref resolution. Isolated so each registry
+   *  (and thus each AnalysisContext) has its own schema store — no stale schemas
+   *  across analyze() calls and no unbounded growth across the process lifetime. */
+  private readonly ajv = createAjv();
+  private readonly registeredSchemaIds = new Set<string>();
+
+  private readonly defs = new Map<string, ResourceDefinition>();
+  private readonly fieldMaps = new Map<string, ReferenceFieldMap>();
+  /** Reverse inheritance index: parent kind → direct child kinds. */
+  private readonly extendedBy = new Map<string, string[]>();
+  /** Module identity table: identity string → canonical module name.
+   *  "kernel" → "Kernel", "std/pipeline" → "pipeline", etc. */
+  private readonly identityMap = new Map<string, string>();
+  /** Reverse identity table: canonical module name → full identity string.
+   *  "Kernel" → "kernel", "pipeline" → "std/pipeline", etc.
+   *  Used to compute definition $id values for the AJV schema store. */
+  private readonly reverseIdentityMap = new Map<string, string>();
+
+  register(definition: ResourceDefinition): void {
+    const { name, module: mod } = definition.metadata;
+    const key = mod ? `${mod}.${name}` : name;
+    this.defs.set(key, definition);
+    this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+    if (definition.capability) {
+      const children = this.extendedBy.get(definition.capability);
+      if (children) {
+        children.push(key);
+      } else {
+        this.extendedBy.set(definition.capability, [key]);
+      }
+    }
+    // Auto-register the kernel identity when any Kernel built-in is registered.
+    if (definition.kind === "Kernel.Abstract" && mod === "Kernel") {
+      this.identityMap.set("kernel", "Kernel");
+      this.reverseIdentityMap.set("Kernel", "kernel");
+    }
+    // If identity is already known, register the schema in AJV immediately.
+    if (mod && definition.schema) {
+      this.tryRegisterSchema(mod, name as string, definition.schema as Record<string, any>);
+    }
+  }
+
+  /** Register a module identity for x-telo-ref resolution.
+   *  Call once per Kernel.Module manifest when the manifest is loaded.
+   *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for kernel built-ins.
+   *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
+  registerModuleIdentity(namespace: string | null, moduleName: string): void {
+    const identity = namespace ? `${namespace}/${moduleName}` : "kernel";
+    this.identityMap.set(identity, moduleName);
+    this.reverseIdentityMap.set(moduleName, identity);
+    // Retroactively register AJV schemas for definitions of this module already in the registry.
+    for (const def of this.defs.values()) {
+      if (def.metadata.module === moduleName && def.schema) {
+        this.tryRegisterSchema(
+          moduleName,
+          def.metadata.name as string,
+          def.schema as Record<string, any>,
+        );
+      }
+    }
+  }
+
+  /** Computes the $id for a definition schema: "<identity>/<TypeName>".
+   *  Returns undefined when the module identity is not yet registered. */
+  computeId(moduleName: string, typeName: string): string | undefined {
+    const identity = this.reverseIdentityMap.get(moduleName);
+    if (!identity) return undefined;
+    return `${identity}/${typeName}`;
+  }
+
+  /** Validates data against a schema using this registry's AJV instance, which has all
+   *  registered definition schemas loaded — enabling cross-module $ref resolution. */
+  validateWithRefs(data: unknown, schema: Record<string, any>): string[] {
+    let validate: ReturnType<typeof this.ajv.compile>;
+    try {
+      validate = this.ajv.compile(schema);
+    } catch {
+      return [];
+    }
+    if (validate(data)) return [];
+    return (validate.errors ?? []).map(formatSingleError);
+  }
+
+  private tryRegisterSchema(
+    moduleName: string,
+    typeName: string,
+    schema: Record<string, any>,
+  ): void {
+    const id = this.computeId(moduleName, typeName);
+    if (!id || this.registeredSchemaIds.has(id)) return;
+    if (this.ajv.getSchema(id)) {
+      throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
+    }
+    this.ajv.addSchema(schema, id);
+    this.registeredSchemaIds.add(id);
+  }
+
+  /** Resolves an x-telo-ref string to a canonical registry kind key.
+   *  Splits on "#", looks up the left side in the identity table, and returns
+   *  "<canonicalModule>.<TypeName>".
+   *
+   *  "kernel#Invocable"       → "Kernel.Invocable"
+   *  "std/pipeline#Job"       → "pipeline.Job"
+   *  "std/http-server#Server" → "http-server.Server"
+   *
+   *  Returns undefined when the string is malformed or the identity is not registered. */
+  resolveRef(xTeloRef: string): string | undefined {
+    const hash = xTeloRef.indexOf("#");
+    if (hash === -1 || hash === xTeloRef.length - 1) return undefined;
+    const identity = xTeloRef.slice(0, hash);
+    const typeName = xTeloRef.slice(hash + 1);
+    const moduleName = this.identityMap.get(identity);
+    if (!moduleName) return undefined;
+    return `${moduleName}.${typeName}`;
+  }
+
+  resolve(kind: string): ResourceDefinition | undefined {
+    return this.defs.get(kind);
+  }
+
+  /** Returns the cached reference field map for the given kind, built once during register(). */
+  getFieldMap(kind: string): ReferenceFieldMap | undefined {
+    return this.fieldMaps.get(kind);
+  }
+
+  /** Returns the field map for `kind`, falling back to the alias-resolved kind when not found. */
+  getFieldMapForKind(
+    kind: string,
+    aliases?: { resolveKind(k: string): string | undefined },
+  ): ReferenceFieldMap | undefined {
+    const fm = this.getFieldMap(kind);
+    if (fm) return fm;
+    const resolved = aliases?.resolveKind(kind);
+    return resolved ? this.getFieldMap(resolved) : undefined;
+  }
+
+  /** Returns all definitions that transitively extend the given abstract kind.
+   *  Follows the capability chain to any depth (equivalent to instanceof in OOP).
+   *  Definitions are included regardless of registration order. */
+  getByExtends(abstractKind: string): ResourceDefinition[] {
+    const result: ResourceDefinition[] = [];
+    const queue = [abstractKind];
+    while (queue.length > 0) {
+      const parent = queue.shift()!;
+      const children = this.extendedBy.get(parent);
+      if (!children) continue;
+      for (const child of children) {
+        const def = this.defs.get(child);
+        if (def) result.push(def);
+        queue.push(child);
+      }
+    }
+    return result;
+  }
+
+  kinds(): string[] {
+    return Array.from(this.defs.keys());
+  }
+}

package/src/dependency-graph.ts

@@ -0,0 +1,187 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+
+export interface ResourceNode {
+  kind: string;
+  name: string;
+}
+
+export interface DependencyGraph {
+  /** Topological order: each resource appears after all its dependencies (leaves first).
+   *  Present only when the graph is acyclic. */
+  order?: ReadonlyArray<ResourceNode>;
+  /** The cycle path when a circular dependency is detected.
+   *  The first and last elements are the same resource, tracing the full loop. */
+  cycle?: ReadonlyArray<ResourceNode>;
+}
+
+/** System resource kinds that are not runtime nodes in the dependency graph. */
+const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Import"]);
+
+const nodeKey = (kind: string, name: string) => `${kind}\0${name}`;
+
+/**
+ * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
+ * returns either a topological initialization order or the cycle path.
+ *
+ * Edges represent boot-time dependencies only:
+ * - x-telo-ref fields that fall within a scope visibility path are excluded
+ *   (scoped resources are initialized on demand at runtime, not at boot).
+ * - x-telo-scope fields themselves are excluded from the graph.
+ *
+ * The registry is queried for each resource's field map by kind — callers do
+ * not pre-compute or pass field maps separately.
+ */
+export function buildDependencyGraph(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+): DependencyGraph {
+  // --- Build node set ---
+  const nodes = new Map<string, ResourceNode>();
+  for (const r of resources) {
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+    const key = nodeKey(r.kind, r.metadata.name as string);
+    nodes.set(key, { kind: r.kind, name: r.metadata.name as string });
+  }
+
+  // --- Build adjacency: from → deps (from depends on dep) ---
+  const deps = new Map<string, Set<string>>();
+  for (const key of nodes.keys()) deps.set(key, new Set());
+
+  for (const r of resources) {
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+
+    const sourceKey = nodeKey(r.kind, r.metadata.name as string);
+    const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
+    if (!fieldMap) continue;
+
+    // Collect names of resources declared inside scope fields — these are initialized
+    // on-demand at runtime, not at boot, so edges pointing to them are excluded from the DAG.
+    const scopedNames = new Set<string>();
+    for (const [scopeFieldPath, entry] of fieldMap) {
+      if (!isScopeEntry(entry)) continue;
+      const scopeVal = (r as Record<string, unknown>)[scopeFieldPath];
+      if (!Array.isArray(scopeVal)) continue;
+      for (const item of scopeVal) {
+        const name = (item as any)?.metadata?.name;
+        if (typeof name === "string") scopedNames.add(name);
+      }
+    }
+
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isRefEntry(entry)) continue;
+
+      for (const val of resolveFieldValues(r, fieldPath)) {
+        if (!val || typeof val !== "object") continue;
+        const ref = val as Record<string, unknown>;
+        if (!ref.kind || !ref.name) continue;
+        // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG
+        if (scopedNames.has(ref.name as string)) continue;
+        const targetKey = nodeKey(ref.kind as string, ref.name as string);
+        if (nodes.has(targetKey)) {
+          deps.get(sourceKey)!.add(targetKey);
+        }
+      }
+    }
+  }
+
+  // --- Kahn's topological sort ---
+  // in-degree[X] = number of X's dependencies (size of deps[X])
+  // reverse[dep] = set of nodes that depend on dep (for degree decrement)
+  const inDegree = new Map<string, number>();
+  const reverse = new Map<string, Set<string>>();
+  for (const key of nodes.keys()) {
+    inDegree.set(key, deps.get(key)!.size);
+    reverse.set(key, new Set());
+  }
+  for (const [from, depSet] of deps) {
+    for (const dep of depSet) {
+      reverse.get(dep)?.add(from);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [key, deg] of inDegree) {
+    if (deg === 0) queue.push(key);
+  }
+
+  const sorted: ResourceNode[] = [];
+  while (queue.length > 0) {
+    const key = queue.shift()!;
+    sorted.push(nodes.get(key)!);
+    for (const dependent of reverse.get(key)!) {
+      const deg = inDegree.get(dependent)! - 1;
+      inDegree.set(dependent, deg);
+      if (deg === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length === nodes.size) {
+    return { order: sorted };
+  }
+
+  return { cycle: findCycle(nodes, deps) };
+}
+
+/**
+ * Formats a cycle result into a human-readable error string matching the spec:
+ *
+ *   Circular dependency detected:
+ *     Run.Sequence "DataSync"
+ *       → Http.Server "Api"
+ *       → Run.Sequence "DataSync"
+ */
+export function formatCycle(cycle: ReadonlyArray<ResourceNode>): string {
+  const lines = ["Circular dependency detected:"];
+  lines.push(`  ${cycle[0].kind} "${cycle[0].name}"`);
+  for (const node of cycle.slice(1)) {
+    lines.push(`    → ${node.kind} "${node.name}"`);
+  }
+  return lines.join("\n");
+}
+
+// --- Internals ---
+
+/** DFS cycle detection — returns the cycle path with the repeated start node appended. */
+function findCycle(
+  nodes: Map<string, ResourceNode>,
+  deps: Map<string, Set<string>>,
+): ResourceNode[] {
+  type State = "unvisited" | "visiting" | "visited";
+  const state = new Map<string, State>();
+  for (const key of nodes.keys()) state.set(key, "unvisited");
+
+  const stack: string[] = [];
+
+  function dfs(key: string): string[] | null {
+    state.set(key, "visiting");
+    stack.push(key);
+
+    for (const dep of deps.get(key) ?? []) {
+      if (state.get(dep) === "visiting") {
+        const start = stack.indexOf(dep);
+        return [...stack.slice(start), dep];
+      }
+      if (state.get(dep) === "unvisited") {
+        const result = dfs(dep);
+        if (result) return result;
+      }
+    }
+
+    stack.pop();
+    state.set(key, "visited");
+    return null;
+  }
+
+  for (const key of nodes.keys()) {
+    if (state.get(key) === "unvisited") {
+      const result = dfs(key);
+      if (result) return result.map((k) => nodes.get(k)!);
+    }
+  }
+
+  return [];
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { HttpAdapter } from "./adapters/http-adapter.js";
+export { createNodeAdapter, NodeAdapter } from "./adapters/node-adapter.js";
+export { RegistryAdapter } from "./adapters/registry-adapter.js";
+export { AnalysisRegistry } from "./analysis-registry.js";
+export { StaticAnalyzer } from "./analyzer.js";
+export { Loader } from "./manifest-loader.js";
+export { DiagnosticSeverity } from "./types.js";
+export type {
+    AnalysisDiagnostic,
+    AnalysisOptions,
+    LoadOptions,
+    ManifestAdapter,
+    Position,
+    PositionIndex,
+    Range
+} from "./types.js";
+

package/src/manifest-loader.ts

@@ -0,0 +1,203 @@
+import 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";
+
+export class Loader {
+  protected adapters: ManifestAdapter[] = [new HttpAdapter(), new RegistryAdapter()];
+
+  constructor(extraAdapters: ManifestAdapter[] = []) {
+    this.adapters.unshift(...extraAdapters);
+  }
+
+  register(adapter: ManifestAdapter): this {
+    this.adapters.unshift(adapter);
+    return this;
+  }
+
+  private pick(url: string): ManifestAdapter {
+    const a = this.adapters.find((a) => a.supports(url));
+    if (!a) throw new Error(`No adapter found for: ${url}`);
+    return a;
+  }
+
+  async loadModule(url: string, 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;
+
+      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 };
+        // positionIndex is non-enumerable so it is invisible to spread, JSON.stringify,
+        // and schema validation — but still accessible via (m.metadata as any).positionIndex.
+        Object.defineProperty(metadata, "positionIndex", {
+          value: positionIndex,
+          enumerable: false,
+          writable: true,
+          configurable: true,
+        });
+        resolved.push({ ...manifest, metadata });
+      }
+    }
+
+    const moduleManifests = resolved.filter((m) => m.kind === "Kernel.Module");
+    if (moduleManifests.length > 1) {
+      throw new Error(
+        `File '${source}' contains ${moduleManifests.length} Kernel.Module declarations. Maximum one is allowed.`,
+      );
+    }
+    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) {
+          manifest.metadata = { ...manifest.metadata, module: moduleName };
+        }
+      }
+    }
+
+    return resolved;
+  }
+
+  async loadManifests(entryUrl: string): Promise<ResourceManifest[]> {
+    const visited = new Set<string>([entryUrl]);
+    const entry = await this.loadModule(entryUrl);
+
+    const importedDefs: ResourceManifest[] = [];
+    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 = this.pick(base).resolveRelative(base, importSource);
+      if (visited.has(importUrl)) continue;
+      visited.add(importUrl);
+      let imported: ResourceManifest[];
+      try {
+        imported = await this.loadModule(importUrl);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
+        throw e;
+      }
+      const importedModule = imported.find((im) => im.kind === "Kernel.Module");
+      if (importedModule?.metadata?.name) {
+        m.metadata = {
+          ...m.metadata,
+          resolvedModuleName: importedModule.metadata.name as string,
+          resolvedNamespace: (importedModule.metadata as any).namespace ?? null,
+        };
+      }
+      for (const im of imported) {
+        if (im.kind === "Kernel.Definition") importedDefs.push(im);
+        if (im.kind === "Kernel.Import") queue.push(im);
+      }
+    }
+
+    return [...entry, ...importedDefs];
+  }
+}
+
+function documentLineOffsets(text: string): number[] {
+  const offsets = [0];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trimEnd();
+    if (t === "---" || t.startsWith("--- ")) offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+/** Builds a byte-offset-to-line/character lookup table from raw text. */
+function buildLineOffsets(text: string): number[] {
+  const offsets: number[] = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+function offsetToPosition(offset: number, lineOffsets: number[]): Position {
+  let lo = 0;
+  let hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineOffsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return { line: lo, character: offset - lineOffsets[lo] };
+}
+
+/** Walks the YAML AST and records source ranges for every field value, keyed by
+ *  dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+function buildPositionIndex(doc: Document, lineOffsets: number[]): PositionIndex {
+  const index: PositionIndex = new Map();
+
+  function recordNode(node: any, path: string): void {
+    if (!node || !node.range) return;
+    const [start, , end] = node.range as [number, number, number];
+    index.set(path, {
+      start: offsetToPosition(start, lineOffsets),
+      end: offsetToPosition(end, lineOffsets),
+    });
+  }
+
+  function walk(node: any, path: string): void {
+    if (isMap(node)) {
+      for (const pair of node.items) {
+        if (!isPair(pair)) continue;
+        const key = isScalar(pair.key) ? String(pair.key.value) : null;
+        if (key == null) continue;
+        const childPath = path ? `${path}.${key}` : key;
+        if (pair.value != null) {
+          recordNode(pair.value, childPath);
+          walk(pair.value, childPath);
+        }
+      }
+    } else if (isSeq(node)) {
+      for (let i = 0; i < node.items.length; i++) {
+        const item = node.items[i];
+        const childPath = `${path}[${i}]`;
+        recordNode(item, childPath);
+        walk(item, childPath);
+      }
+    }
+  }
+
+  if (doc.contents) {
+    walk(doc.contents, "");
+  }
+
+  return index;
+}