@telorun/analyzer 0.1.1

package/src/analyzer.ts

@@ -0,0 +1,399 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { AliasResolver } from "./alias-resolver.js";
+import { AnalysisRegistry } from "./analysis-registry.js";
+import { buildTypedCelEnvironment, celEnvironment } from "./cel-environment.js";
+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,
+} from "./schema-compat.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
+import {
+  extractAccessChains,
+  pathMatchesScope,
+  validateChainAgainstSchema,
+} from "./validate-cel-context.js";
+import { validateReferences } from "./validate-references.js";
+
+const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+
+function walkCelExpressions(
+  value: unknown,
+  path: string,
+  cb: (expr: string, path: string) => void,
+): void {
+  if (typeof value === "string") {
+    for (const m of value.matchAll(TEMPLATE_REGEX)) {
+      cb(m[1].trim(), path);
+    }
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => walkCelExpressions(v, `${path}[${i}]`, cb));
+  } else if (value !== null && typeof value === "object") {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      walkCelExpressions(v, path ? `${path}.${k}` : k, cb);
+    }
+  }
+}
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
+ * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
+ * the same format the analyzer uses for CEL context validation.
+ */
+function extractContextsFromSchema(
+  schema: Record<string, any>,
+  path = "$",
+): Array<{ scope: string; schema: Record<string, any> }> {
+  if (!schema || typeof schema !== "object") return [];
+  const results: Array<{ scope: string; schema: Record<string, any> }> = [];
+
+  if (schema["x-telo-context"]) {
+    results.push({ scope: path, schema: schema["x-telo-context"] });
+  }
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      results.push(...extractContextsFromSchema(value, `${path}.${key}`));
+    }
+  }
+
+  if (schema.items && typeof schema.items === "object") {
+    results.push(...extractContextsFromSchema(schema.items, `${path}[*]`));
+  }
+
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const subschema of schema[key]) {
+        results.push(...extractContextsFromSchema(subschema, path));
+      }
+    }
+  }
+
+  return results;
+}
+
+const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
+const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
+
+/** Recursively walk `data`+`schema` together, type-checking every pure CEL template
+ *  string via `env.check()`. Returns `SchemaIssue[]` for any type mismatches found. */
+function collectCelTypeIssues(
+  data: unknown,
+  schema: Record<string, any>,
+  path: string,
+  definition: { schema?: Record<string, any> },
+  manifest: ResourceManifest,
+  baseEnv: ReturnType<typeof buildTypedCelEnvironment>,
+): SchemaIssue[] {
+  const issues: SchemaIssue[] = [];
+
+  if (typeof data === "string" && CEL_PURE_RE.test(data)) {
+    const exprMatch = data.match(CEL_EXPR_RE);
+    if (exprMatch) {
+      const expr = exprMatch[1].trim();
+
+      // Merge x-telo-context variables for this path if applicable
+      let typedEnv = baseEnv;
+      if (definition.schema) {
+        for (const ctx of extractContextsFromSchema(definition.schema)) {
+          if (!pathMatchesScope(path, ctx.scope)) continue;
+          typedEnv = buildTypedCelEnvironment(manifest, ctx.schema);
+          break;
+        }
+      }
+
+      let checkResult: ReturnType<typeof typedEnv.check> | undefined;
+      try {
+        checkResult = typedEnv.check(expr);
+      } catch {
+        /* degrade gracefully */
+      }
+
+      if (checkResult?.valid && checkResult.type && schema) {
+        const celType = checkResult.type.split("<")[0]!;
+        if (!celTypeSatisfiesJsonSchema(celType, schema)) {
+          issues.push({
+            message: `CEL returns '${checkResult.type}' but field expects '${schema.type ?? "unknown"}'`,
+            path,
+          });
+        }
+      }
+    }
+    return issues;
+  }
+
+  if (Array.isArray(data)) {
+    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),
+      );
+    }
+  } else if (data !== null && typeof data === "object") {
+    const props = (schema.properties ?? {}) as Record<string, any>;
+    for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+      issues.push(
+        ...collectCelTypeIssues(
+          v,
+          (props[k] ?? {}) as Record<string, any>,
+          path ? `${path}.${k}` : k,
+          definition,
+          manifest,
+          baseEnv,
+        ),
+      );
+    }
+  }
+
+  return issues;
+}
+
+export class StaticAnalyzer {
+  analyze(
+    manifests: ResourceManifest[],
+    options?: AnalysisOptions,
+    registry?: AnalysisRegistry,
+  ): AnalysisDiagnostic[] {
+    const diagnostics: AnalysisDiagnostic[] = [];
+
+    // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.
+    // New aliases/definitions found in the manifests are accumulated into the provided instance
+    // so state builds up across successive calls (e.g. incremental editor validation).
+    const ctx = registry?._context();
+    const aliases = ctx?.aliases ?? new AliasResolver();
+    const defs = ctx?.definitions ?? new DefinitionRegistry();
+
+    // Register module identities and aliases.
+    // The root Kernel.Module provides its own identity; imported modules surface their
+    // identity via resolvedModuleName/resolvedNamespace stamped onto the Kernel.Import
+    // by the loader (so we don't need to include imported Kernel.Module manifests in
+    // the analysis set, avoiding false reference errors in the parent context).
+    for (const m of manifests) {
+      if (m.kind === "Kernel.Module") {
+        const namespace = ((m.metadata as any).namespace as string | undefined) ?? null;
+        const moduleName = m.metadata.name as string;
+        if (moduleName) defs.registerModuleIdentity(namespace, moduleName);
+      }
+      if (m.kind === "Kernel.Import") {
+        const alias = m.metadata.name as string;
+        const source = (m as any).source as string | undefined;
+        const exportedKinds: string[] = (m as any).exports?.kinds ?? [];
+        const resolvedModuleName = (m.metadata as any).resolvedModuleName as string | undefined;
+        const resolvedNamespace = (m.metadata as any).resolvedNamespace as
+          | string
+          | null
+          | undefined;
+        if (alias && source) {
+          const targetModule =
+            resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
+          aliases.registerImport(alias, targetModule, exportedKinds);
+          if (resolvedModuleName) {
+            defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
+          }
+        }
+      }
+    }
+
+    // Register definitions from Kernel.Definition resources.
+    // Normalize alias-prefixed `capability` to canonical form so extendedBy lookup works
+    // (e.g. "Workflow.Backend" → "workflow.Backend" when "Workflow" is a known alias).
+    for (const m of manifests) {
+      if (m.kind === "Kernel.Definition") {
+        const def = m as unknown as ResourceDefinition;
+        const resolvedCapability = def.capability
+          ? (aliases.resolveKind(def.capability) ?? def.capability)
+          : def.capability;
+        defs.register(
+          resolvedCapability !== def.capability ? { ...def, capability: resolvedCapability } : def,
+        );
+      }
+    }
+
+    // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
+    const allManifests = normalizeInlineResources(manifests, defs, aliases);
+
+    // Build a name→manifest map for looking up referenced resources
+    const byName = new Map<string, ResourceManifest>();
+    for (const m of allManifests) {
+      if (m.metadata?.name) {
+        byName.set(m.metadata.name as string, m);
+      }
+    }
+
+    // Validate each non-definition, non-system resource
+    for (const m of allManifests) {
+      if (!m.kind || !m.metadata?.name) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "MISSING_KIND_OR_NAME",
+          source: SOURCE,
+          message: "Resource is missing required 'kind' or 'metadata.name' field.",
+          data: { path: !m.kind ? "kind" : "metadata.name" },
+        });
+        continue;
+      }
+      if (m.kind === "Kernel.Definition" || m.kind === "Kernel.Abstract") {
+        continue;
+      }
+
+      const resource = { kind: m.kind, name: m.metadata?.name as string };
+
+      // Resolve kind through alias if needed; direct lookup takes priority so that
+      // aliases whose name matches the module name (the common case) work without
+      // path-derived name mangling.
+      const resolvedKind = aliases.resolveKind(m.kind);
+      const definition =
+        defs.resolve(m.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
+      if (!definition) {
+        const knownAliases = aliases.knownAliases();
+        const knownKinds = defs.kinds();
+        const parts: string[] = [];
+        if (knownAliases.length > 0) parts.push(`imports: ${knownAliases.join(", ")}`);
+        if (knownKinds.length > 0) parts.push(`kinds: ${knownKinds.join(", ")}`);
+        const hint = parts.length > 0 ? ` Known ${parts.join(" | ")}` : "";
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "UNDEFINED_KIND",
+          source: SOURCE,
+          message: `No Kernel.Definition found for kind '${m.kind}'.${hint}`,
+          data: { resource, path: "kind" },
+        });
+        continue;
+      }
+
+      // Validate resource config against definition schema.
+      // `kind` and `metadata` are implicit on every resource — inject them so module
+      // authors don't have to repeat them when using additionalProperties: false.
+      if (definition.schema) {
+        const schema =
+          definition.schema.additionalProperties === false
+            ? {
+                ...definition.schema,
+                properties: {
+                  kind: { type: "string" },
+                  metadata: { type: "object" },
+                  ...definition.schema.properties,
+                },
+              }
+            : definition.schema;
+        // Phase 1: CEL type checking — walk data+schema together, check env.check() return types
+        const baseEnv = buildTypedCelEnvironment(m);
+        const celIssues = collectCelTypeIssues(m, schema, "", definition, m, baseEnv);
+        // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
+        const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
+        const issues = [...celIssues, ...ajvIssues];
+        for (const issue of issues) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SCHEMA_VIOLATION",
+            source: SOURCE,
+            message: `${m.kind}/${resource.name}: ${issue.message}`,
+            data: { resource, path: issue.path },
+          });
+        }
+      }
+
+      // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
+    }
+
+    // Validate CEL syntax and context variable access in all manifests
+    for (const m of allManifests) {
+      const resource = { kind: m.kind, name: m.metadata?.name as string };
+
+      const resolvedKind = aliases.resolveKind(m.kind);
+      const mDefinition =
+        defs.resolve(m.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
+
+      walkCelExpressions(m, "", (expr, path) => {
+        let parsed: ReturnType<typeof celEnvironment.parse> | undefined;
+        try {
+          parsed = celEnvironment.parse(expr);
+        } catch (e) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "CEL_SYNTAX_ERROR",
+            source: SOURCE,
+            message: `CEL syntax error at ${path}: ${e instanceof Error ? e.message : String(e)}`,
+            data: { resource, path },
+          });
+          return;
+        }
+
+        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;
+
+        let matchedContext: Record<string, any> | undefined;
+        for (const ctx of contexts) {
+          if (pathMatchesScope(path, ctx.scope)) {
+            matchedContext = ctx.schema;
+            break;
+          }
+        }
+        if (!matchedContext) matchedContext = invocationContext;
+        if (!matchedContext) return;
+
+        for (const chain of extractAccessChains(parsed.ast)) {
+          const err = validateChainAgainstSchema(chain, matchedContext);
+          if (!err) continue;
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "CEL_UNKNOWN_FIELD",
+            source: SOURCE,
+            message: `${m.kind}/${resource.name}: CEL at '${path}': ${err}`,
+            data: { resource, path },
+          });
+        }
+      });
+    }
+
+    // Validate resource references (Phase 3)
+    diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs }));
+
+    return diagnostics;
+  }
+
+  analyzeErrors(
+    manifests: ResourceManifest[],
+    options?: AnalysisOptions,
+    registry?: AnalysisRegistry,
+  ): AnalysisDiagnostic[] {
+    return this.analyze(manifests, options, registry).filter(
+      (d) => d.severity === DiagnosticSeverity.Error,
+    );
+  }
+
+  normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
+    const ctx = registry._context();
+    return normalizeInlineResources(manifests, ctx.definitions!, ctx.aliases);
+  }
+
+  prepare(
+    manifests: ResourceManifest[],
+    registry: AnalysisRegistry,
+  ): { diagnostics: AnalysisDiagnostic[]; order: string[] | null; cycleError: string | null } {
+    const ctx = registry._context();
+    const diagnostics = validateReferences(manifests, ctx);
+    const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+    if (errors.length > 0) {
+      return { diagnostics: errors, order: null, cycleError: null };
+    }
+    const graph = buildDependencyGraph(manifests, ctx.definitions!, ctx.aliases);
+    if (graph.cycle) {
+      return { diagnostics: [], order: null, cycleError: formatCycle(graph.cycle) };
+    }
+    return {
+      diagnostics: [],
+      order: graph.order ? graph.order.map((n) => n.name) : null,
+      cycleError: null,
+    };
+  }
+}

package/src/builtins.ts

@@ -0,0 +1,111 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+
+export const KERNEL_BUILTINS: ResourceDefinition[] = [
+  { kind: "Kernel.Abstract", metadata: { name: "Template", module: "Kernel" } },
+  { kind: "Kernel.Abstract", metadata: { name: "Runnable", module: "Kernel" } },
+  { kind: "Kernel.Abstract", metadata: { name: "Service", module: "Kernel" } },
+  { kind: "Kernel.Abstract", metadata: { name: "Invocable", module: "Kernel" } },
+  { kind: "Kernel.Abstract", metadata: { name: "Mount", module: "Kernel" } },
+  { kind: "Kernel.Abstract", metadata: { name: "Type", module: "Kernel" } },
+  {
+    kind: "Kernel.Abstract",
+    metadata: { name: "Provider", module: "Kernel" },
+    schema: { "x-telo-eval": "compile" },
+  },
+  {
+    kind: "Kernel.Definition",
+    metadata: { name: "Abstract", module: "Kernel" },
+    capability: "Kernel.Template",
+    schema: {
+      type: "object",
+      properties: {
+        kind: { type: "string" },
+        metadata: {
+          type: "object",
+          properties: { name: { type: "string" } },
+          required: ["name"],
+          additionalProperties: true,
+        },
+        capability: { type: "string" },
+      },
+      required: ["metadata"],
+      additionalProperties: false,
+    },
+  },
+  {
+    kind: "Kernel.Definition",
+    metadata: { name: "Definition", module: "Kernel" },
+    capability: "Kernel.Template",
+    schema: { type: "object" },
+  },
+  {
+    kind: "Kernel.Definition",
+    metadata: { name: "Import", module: "Kernel" },
+    capability: "Kernel.Template",
+    schema: {
+      type: "object",
+      properties: {
+        kind: { type: "string" },
+        metadata: {
+          type: "object",
+          properties: { name: { type: "string" } },
+          required: ["name"],
+          additionalProperties: true,
+        },
+        source: { type: "string" },
+        variables: { type: "object" },
+        secrets: { type: "object" },
+      },
+      required: ["metadata", "source"],
+      additionalProperties: false,
+    },
+  },
+  {
+    kind: "Kernel.Definition",
+    metadata: { name: "Module", module: "Kernel" },
+    capability: "Kernel.Template",
+    schema: {
+      type: "object",
+      properties: {
+        kind: { type: "string" },
+        metadata: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            version: { type: "string" },
+            source: { type: "string" },
+            module: { type: "string" },
+          },
+          required: ["name"],
+          additionalProperties: true,
+        },
+        lifecycle: {
+          type: "string",
+          enum: ["shared", "isolated"],
+          default: "shared",
+        },
+        keepAlive: { type: "boolean", default: false },
+        variables: { type: "object" },
+        secrets: { type: "object" },
+        targets: {
+          type: "array",
+          items: {
+            anyOf: [
+              { type: "string", "x-telo-ref": "kernel#Runnable" },
+              { type: "string", "x-telo-ref": "kernel#Service" },
+            ],
+          },
+        },
+        exports: {
+          type: "object",
+          properties: {
+            kinds: { type: "array", items: { type: "string" } },
+          },
+          additionalProperties: true,
+        },
+      },
+      required: ["metadata"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/cel-environment.ts

@@ -0,0 +1,70 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { Environment } from "@marcbachmann/cel-js";
+import { jsonSchemaToCelType } from "./schema-compat.js";
+
+export const celEnvironment = new Environment({ unlistedVariablesAreDyn: true })
+  .registerFunction("join(list, string): string", (list: unknown[], sep: string) =>
+    list.map(String).join(sep),
+  )
+  .registerFunction("keys(map): list", (map: unknown) => {
+    if (map instanceof Map) return [...map.keys()];
+    return Object.keys(map as Record<string, unknown>);
+  })
+  .registerFunction("values(map): list", (map: unknown) => {
+    if (map instanceof Map) return [...map.values()];
+    return Object.values(map as Record<string, unknown>);
+  });
+
+/** Clone `celEnvironment` and register typed variable declarations so that
+ *  `env.check(expr)` can infer return types for expressions referencing known variables.
+ *
+ *  - `variables`: typed from the manifest's `variables` field if it is a schema map
+ *    (only `Kernel.Module` resources carry this); otherwise registered as `map` (dyn).
+ *  - `secrets`, `resources`, `imports`, `env`: always `map` (dyn — output schemas unknown).
+ *  - `extraContextSchema`: additional variables from an `x-telo-context` annotation. */
+export function buildTypedCelEnvironment(
+  manifest: ResourceManifest,
+  extraContextSchema?: Record<string, any> | null,
+): Environment {
+  try {
+    const env = celEnvironment.clone();
+
+    // Build typed ObjectSchema from manifest.variables if it looks like a schema map
+    const vars = (manifest as Record<string, unknown>).variables;
+    if (vars !== null && typeof vars === "object" && !Array.isArray(vars)) {
+      const entries = Object.entries(vars as Record<string, unknown>).filter(
+        ([, v]) => v !== null && typeof v === "object" && !Array.isArray(v),
+      );
+      if (entries.length > 0) {
+        const schema: Record<string, string> = {};
+        for (const [k, v] of entries) {
+          schema[k] = jsonSchemaToCelType(v as Record<string, any>);
+        }
+        (env as any).registerVariable({ name: "variables", schema });
+      } else {
+        env.registerVariable("variables", "map");
+      }
+    } else {
+      env.registerVariable("variables", "map");
+    }
+
+    env.registerVariable("secrets", "map");
+    env.registerVariable("resources", "map");
+    env.registerVariable("imports", "map");
+    env.registerVariable("env", "map");
+
+    if (extraContextSchema?.properties) {
+      for (const [name, propSchema] of Object.entries(
+        extraContextSchema.properties as Record<string, any>,
+      )) {
+        if (!env.hasVariable(name)) {
+          env.registerVariable(name, jsonSchemaToCelType(propSchema as Record<string, any>));
+        }
+      }
+    }
+
+    return env;
+  } catch {
+    return celEnvironment.clone();
+  }
+}