@telorun/analyzer 0.1.1

package/dist/validate-references.js

@@ -0,0 +1,275 @@
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues } from "./reference-field-map.js";
+import { navigateJsonPointer } from "./schema-compat.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Abstract"]);
+/**
+ * Checks whether `kind` satisfies the ref constraint in `entry`.
+ * Returns an empty array when valid, or mismatch error strings when not.
+ * Returns an empty array immediately when the ref identity is not registered
+ * (partial context — skip check rather than false-positive).
+ */
+function checkKind(kind, entry, registry, aliases) {
+    const resolved = aliases.resolveKind(kind) ?? kind;
+    const errors = [];
+    for (const refStr of entry.refs) {
+        const targetKind = registry.resolveRef(refStr);
+        if (!targetKind)
+            return [];
+        const targetDef = registry.resolve(targetKind);
+        if (!targetDef)
+            return [];
+        if (targetDef.kind === "Kernel.Abstract") {
+            const implementing = registry.getByExtends(targetKind);
+            if (implementing.length === 0)
+                return []; // partial context — no implementations loaded yet
+            const implementingKinds = new Set(implementing.map((d) => `${d.metadata.module}.${d.metadata.name}`));
+            if (implementingKinds.has(resolved))
+                return [];
+            const options = [...implementingKinds].join(", ");
+            errors.push(`'${kind}' does not implement '${targetKind}' (known implementations: ${options})`);
+        }
+        else {
+            if (resolved === targetKind)
+                return [];
+            errors.push(`'${kind}' (resolved: '${resolved}') does not match required '${targetKind}'`);
+        }
+    }
+    return errors;
+}
+/**
+ * Phase 3 — Reference validation.
+ *
+ * For each x-telo-ref slot in every non-system resource, validates:
+ *   1. Structural — the value has string `kind` and `name` fields.
+ *   2. Kind — the alias-resolved kind satisfies the x-telo-ref constraint
+ *             (abstract: must extend the target; concrete: must equal it exactly).
+ *   3. Resolution — a resource with that name exists in the visible manifest set
+ *                   (outer manifests + scope manifests for in-scope ref paths).
+ *
+ * Ref values with keys beyond kind/name/metadata are treated as inline resources
+ * pending Phase 2 normalization and are skipped without error.
+ *
+ * Returns an empty array when `context.aliases` or `context.definitions` is absent.
+ */
+export function validateReferences(resources, context) {
+    const diagnostics = [];
+    const aliases = context.aliases;
+    const registry = context.definitions;
+    if (!aliases || !registry)
+        return diagnostics;
+    // Build outer resource lookup by name for resolution check.
+    // Exclude system kinds (Kernel.Definition) — they are type blueprints, not instances,
+    // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
+    const byName = new Map();
+    for (const r of resources) {
+        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind))
+            byName.set(r.metadata.name, r);
+    }
+    for (const r of resources) {
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
+        if (!fieldMap)
+            continue;
+        const resourceLabel = `${r.kind}/${r.metadata.name}`;
+        const resourceData = { kind: r.kind, name: r.metadata.name };
+        // Collect scope visibility prefixes (JSON Pointer → dot prefix) and their manifests.
+        // scope field path → flat array of ResourceManifest declared in that scope.
+        const scopeManifestsByPointer = new Map();
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isScopeEntry(entry))
+                continue;
+            const raw = resolveFieldValues(r, fieldPath)
+                .flatMap((v) => (Array.isArray(v) ? v : [v]))
+                .filter((v) => !!v && typeof v === "object");
+            const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
+            for (const pointer of pointers) {
+                scopeManifestsByPointer.set(pointer, raw);
+            }
+        }
+        const scopePrefixes = Array.from(scopeManifestsByPointer.keys()).map((p) => p.replace(/^\//, "").replace(/\//g, "."));
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isRefEntry(entry))
+                continue;
+            const inScope = scopePrefixes.some((prefix) => fieldPath === prefix ||
+                fieldPath.startsWith(prefix + ".") ||
+                fieldPath.startsWith(prefix + "["));
+            // Scope manifests visible to this ref path.
+            const visibleScopeManifests = [];
+            if (inScope) {
+                for (const [pointer, manifests] of scopeManifestsByPointer) {
+                    const prefix = pointer.replace(/^\//, "").replace(/\//g, ".");
+                    if (fieldPath === prefix ||
+                        fieldPath.startsWith(prefix + ".") ||
+                        fieldPath.startsWith(prefix + "[")) {
+                        visibleScopeManifests.push(...manifests);
+                    }
+                }
+            }
+            for (const val of resolveFieldValues(r, fieldPath)) {
+                if (!val)
+                    continue;
+                // Name-only reference (plain string) — look up by name to validate.
+                if (typeof val === "string") {
+                    const target = byName.get(val) ?? visibleScopeManifests.find((m) => m.metadata?.name === val);
+                    if (!target) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "UNRESOLVED_REFERENCE",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
+                            data: { resource: resourceData, path: fieldPath },
+                        });
+                        continue;
+                    }
+                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                    if (kindErrors.length > 0) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "REFERENCE_KIND_MISMATCH",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
+                            data: { resource: resourceData, path: fieldPath },
+                        });
+                    }
+                    continue;
+                }
+                if (typeof val !== "object")
+                    continue;
+                const refVal = val;
+                // Skip inline resources — Phase 2 normalization hasn't run yet.
+                if (isInlineResource(refVal))
+                    continue;
+                // 1. Structural check
+                if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "INVALID_REFERENCE",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                    continue;
+                }
+                // 2. Kind check
+                const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+                if (kindErrors.length > 0) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "REFERENCE_KIND_MISMATCH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                }
+                // 3. Resolution check — resource with this name must exist.
+                const exists = byName.has(refVal.name) ||
+                    visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+                if (!exists) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "UNRESOLVED_REFERENCE",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                }
+            }
+        }
+    }
+    // Phase 3b — x-telo-schema-from validation.
+    // For each field with a schemaFrom path expression, resolve the anchor ref to get the
+    // concrete kind, navigate the JSON Pointer into that kind's definition schema, and
+    // validate the field value against the resulting sub-schema.
+    for (const r of resources) {
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
+        if (!fieldMap)
+            continue;
+        const resourceLabel = `${r.kind}/${r.metadata.name}`;
+        const resourceData = { kind: r.kind, name: r.metadata.name };
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isSchemaFromEntry(entry))
+                continue;
+            const { schemaFrom } = entry;
+            const isAbsolute = schemaFrom.startsWith("/");
+            const expr = isAbsolute ? schemaFrom.slice(1) : schemaFrom;
+            const slashIdx = expr.indexOf("/");
+            if (slashIdx === -1) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "INVALID_SCHEMA_FROM",
+                    source: SOURCE,
+                    message: `${resourceLabel}: x-telo-schema-from "${schemaFrom}" must contain at least one "/" to separate anchor from JSON Pointer`,
+                    data: { resource: resourceData, path: fieldPath },
+                });
+                continue;
+            }
+            const anchorName = expr.slice(0, slashIdx);
+            const jsonPointer = "/" + expr.slice(slashIdx + 1);
+            // Derive the anchor path in the resource config.
+            let anchorPath;
+            if (isAbsolute) {
+                anchorPath = anchorName;
+            }
+            else {
+                // Relative: replace the last dot-segment of fieldPath with anchorName.
+                // e.g. "nodes[].options" → "nodes[].backend"
+                const lastDot = fieldPath.lastIndexOf(".");
+                anchorPath = lastDot === -1 ? anchorName : fieldPath.slice(0, lastDot + 1) + anchorName;
+            }
+            const anchorValues = resolveFieldValues(r, anchorPath);
+            if (anchorValues.length === 0)
+                continue; // anchor field not set — nothing to validate
+            const fieldValues = resolveFieldValues(r, fieldPath);
+            for (let i = 0; i < fieldValues.length; i++) {
+                const fieldValue = fieldValues[i];
+                if (fieldValue == null)
+                    continue;
+                // For absolute paths, the single anchor applies to all field values.
+                const anchorVal = isAbsolute ? anchorValues[0] : anchorValues[i];
+                if (!anchorVal || typeof anchorVal !== "object")
+                    continue;
+                const refVal = anchorVal;
+                if (typeof refVal.kind !== "string")
+                    continue;
+                const refResolvedKind = aliases.resolveKind(refVal.kind) ?? refVal.kind;
+                const refDef = registry.resolve(refVal.kind) ?? registry.resolve(refResolvedKind);
+                if (!refDef?.schema) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "SCHEMA_FROM_MISSING_PATH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                    continue;
+                }
+                const subSchema = navigateJsonPointer(refDef.schema, jsonPointer);
+                if (subSchema === undefined) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "SCHEMA_FROM_MISSING_PATH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                    continue;
+                }
+                const issues = registry.validateWithRefs(fieldValue, subSchema);
+                for (const issue of issues) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "DEPENDENT_SCHEMA_MISMATCH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
+                        data: { resource: resourceData, path: fieldPath },
+                    });
+                }
+            }
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@telorun/analyzer",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "src/**"
+  ],
+  "dependencies": {
+    "@marcbachmann/cel-js": "^7.5.3",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.8.3",
+    "jsonpath-plus": "^10.3.0",
+    "@telorun/sdk": "0.2.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}

package/src/adapters/http-adapter.ts

@@ -0,0 +1,23 @@
+import type { ManifestAdapter } from "../types.js";
+
+export class HttpAdapter implements ManifestAdapter {
+  supports(url: string): boolean {
+    return url.startsWith("http://") || url.startsWith("https://");
+  }
+
+  async read(url: string): Promise<{ text: string; source: string }> {
+    const fetchUrl = url.includes(".yaml") ? url : `${url}/module.yaml`;
+    const response = await fetch(fetchUrl);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch manifest from ${fetchUrl}: ${response.status} ${response.statusText}`,
+      );
+    }
+    return { text: await response.text(), source: fetchUrl };
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const baseWithSlash = base.endsWith("/") ? base : `${base}/`;
+    return new URL(relative, baseWithSlash).href;
+  }
+}

package/src/adapters/node-adapter.ts

@@ -0,0 +1,38 @@
+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);
+}

package/src/adapters/registry-adapter.ts

@@ -0,0 +1,43 @@
+import type { ManifestAdapter } from "../types.js";
+
+const REGISTRY_BASE = "https://registry.telo.run";
+
+export class RegistryAdapter implements ManifestAdapter {
+  supports(url: string): boolean {
+    return (
+      !url.startsWith("http://") &&
+      !url.startsWith("https://") &&
+      !url.startsWith("/") &&
+      !url.startsWith(".") &&
+      url.includes("@") &&
+      url.includes("/")
+    );
+  }
+
+  async read(moduleRef: string): Promise<{ text: string; source: string }> {
+    const fetchUrl = this.toRegistryUrl(moduleRef);
+    const response = await fetch(fetchUrl);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch manifest ${moduleRef}: ${response.status} ${response.statusText}`,
+      );
+    }
+    return { text: await response.text(), source: fetchUrl };
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const baseUrl = this.supports(base)
+      ? this.toRegistryUrl(base).replace("/module.yaml", "")
+      : base;
+    const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    return new URL(relative, baseWithSlash).href;
+  }
+
+  private toRegistryUrl(moduleRef: string): string {
+    const atIdx = moduleRef.lastIndexOf("@");
+    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`;
+  }
+}

package/src/alias-resolver.ts

@@ -0,0 +1,37 @@
+/** Pure alias → real module name resolver.
+ *  Ported from ModuleContext.resolveKind() without any lifecycle dependency. */
+export class AliasResolver {
+  private readonly importAliases = new Map<string, string>();
+  private readonly importedKinds = new Map<string, Set<string>>();
+
+  registerImport(alias: string, targetModule: string, exportedKinds: string[]): void {
+    this.importAliases.set(alias, targetModule);
+    if (exportedKinds.length > 0) {
+      this.importedKinds.set(alias, new Set(exportedKinds));
+    }
+  }
+
+  /** Resolves "Http.Api" → "http-server.Api". Returns undefined if alias is unknown. */
+  resolveKind(kind: string): string | undefined {
+    if (!kind) {
+      return undefined;
+    }
+    const dot = kind.indexOf(".");
+    if (dot === -1) return undefined;
+    const prefix = kind.slice(0, dot);
+    const suffix = kind.slice(dot + 1);
+    const realModule = this.importAliases.get(prefix);
+    if (!realModule) return undefined;
+    const allowed = this.importedKinds.get(prefix);
+    if (allowed !== undefined && !allowed.has(suffix)) return undefined;
+    return `${realModule}.${suffix}`;
+  }
+
+  hasAlias(alias: string): boolean {
+    return this.importAliases.has(alias);
+  }
+
+  knownAliases(): string[] {
+    return Array.from(this.importAliases.keys());
+  }
+}

package/src/analysis-registry.ts

@@ -0,0 +1,68 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { AliasResolver } from "./alias-resolver.js";
+import { KERNEL_BUILTINS } from "./builtins.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
+import type { AnalysisContext } from "./types.js";
+
+/**
+ * Accumulates type and alias knowledge for a running kernel or analysis session.
+ * Wraps AliasResolver and DefinitionRegistry into a single domain-level interface
+ * so callers never touch the raw registries directly.
+ */
+export class AnalysisRegistry {
+  private readonly defs = new DefinitionRegistry();
+  private readonly aliases = new AliasResolver();
+
+  registerDefinition(def: ResourceDefinition): void {
+    this.defs.register(def);
+  }
+
+  registerModuleIdentity(namespace: string | null, name: string): void {
+    this.defs.registerModuleIdentity(namespace, name);
+  }
+
+  registerImport(alias: string, target: string, kinds: string[]): void {
+    this.aliases.registerImport(alias, target, kinds);
+  }
+
+  resolveKind(kind: string): string | undefined {
+    return this.aliases.resolveKind(kind);
+  }
+
+  /**
+   * Iterates a resource's reference and scope fields as declared by its definition.
+   * Calls onRef for each plain reference field and onScope for each scope field.
+   */
+  iterateFieldEntries(
+    resource: ResourceManifest,
+    onRef: (fieldPath: string) => void,
+    onScope: (fieldPath: string) => void,
+  ): void {
+    const fieldMap = this.defs.getFieldMapForKind(resource.kind, this.aliases);
+    if (!fieldMap) return;
+    for (const [fieldPath, entry] of fieldMap) {
+      if (isScopeEntry(entry)) {
+        onScope(fieldPath);
+        continue;
+      }
+      if (isRefEntry(entry)) {
+        onRef(fieldPath);
+      }
+    }
+  }
+
+  /**
+   * Returns the built-in kernel definitions. The underlying DefinitionRegistry already
+   * seeds these on construction; this method exposes them so callers (e.g. the kernel's
+   * controller registry) can iterate them without importing KERNEL_BUILTINS directly.
+   */
+  builtinDefinitions(): ResourceDefinition[] {
+    return KERNEL_BUILTINS;
+  }
+
+  /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
+  _context(): AnalysisContext {
+    return { aliases: this.aliases, definitions: this.defs };
+  }
+}