@telorun/analyzer 0.1.1

package/src/types.ts

@@ -0,0 +1,68 @@
+/** Matches LSP DiagnosticSeverity values exactly.
+ *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity */
+export const DiagnosticSeverity = {
+  Error: 1,
+  Warning: 2,
+  Information: 3,
+  Hint: 4,
+} as const;
+export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
+
+export interface Position {
+  /** 0-based line number */
+  line: number;
+  /** 0-based character offset */
+  character: number;
+}
+
+export interface Range {
+  start: Position;
+  end: Position;
+}
+
+/** Maps a dotted field path (e.g. "config.handler", "kind") to its source Range.
+ *  Built from the YAML AST before conversion to plain objects, so positions reflect
+ *  the actual text locations in the source file. */
+export type PositionIndex = Map<string, Range>;
+
+/** LSP-compatible Diagnostic shape. range is optional because parsed YAML may not carry
+ *  position info when only the parsed object (not raw text) is available. */
+export interface AnalysisDiagnostic {
+  range?: Range;
+  severity?: DiagnosticSeverity;
+  code?: string | number;
+  /** e.g. "telo-analyzer" */
+  source?: string;
+  message: string;
+  /** Telo-specific extras such as { resource: { kind, name }, path } */
+  data?: unknown;
+}
+
+export interface ManifestAdapter {
+  supports(url: string): boolean;
+  read(url: string): Promise<{ text: string; source: string }>;
+  resolveRelative(base: string, relative: string): string;
+}
+
+export interface LoadOptions {
+  /** When true, each YAML document is passed through the CEL precompiler before being
+   *  returned. All `${{ expr }}` template strings are replaced with `CompiledValue` wrappers
+   *  so the kernel can evaluate them at runtime. Leave unset (false) for static analysis —
+   *  the analyzer works on raw strings and does not need compiled values. */
+  compile?: boolean;
+}
+
+export interface AnalysisOptions {
+  strictContexts?: boolean;
+}
+
+/** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does
+ *  not rebuild from scratch on every call. The provided instances are mutated — new definitions
+ *  and aliases found in the analysed manifests are registered into them. A single context can
+ *  be reused across successive analyze() calls and accumulates state over time, which is the
+ *  intended pattern for browser editors (persistent state across edits) and the kernel (live
+ *  registry updated as resources are registered at runtime). */
+export interface AnalysisContext {
+  aliases?: import("./alias-resolver.js").AliasResolver;
+  definitions?: import("./definition-registry.js").DefinitionRegistry;
+}

package/src/validate-cel-context.ts

@@ -0,0 +1,142 @@
+import type { ASTNode } from "@marcbachmann/cel-js";
+
+/**
+ * Extract all member-access chains from a CEL AST.
+ * Returns arrays like ["request", "query", "name"] for `request.query.name`.
+ * Chains that start with a call or non-identifier root are ignored.
+ * Bound variables in comprehension macros (filter, map, exists, all, exists_one) are excluded.
+ */
+export function extractAccessChains(node: ASTNode): string[][] {
+  const chains: string[][] = [];
+  visitNode(node, chains, new Set());
+  return chains;
+}
+
+// CEL comprehension macros that bind a variable: list.filter(x, ...), list.map(x, ...), etc.
+const COMPREHENSION_METHODS = new Set(["filter", "map", "exists", "all", "exists_one"]);
+
+function visitNode(node: ASTNode, chains: string[][], boundVars: Set<string>): void {
+  const chain = extractChain(node, boundVars);
+  if (chain !== null) {
+    chains.push(chain);
+    return; // don't recurse into parts of an already-collected chain
+  }
+
+  // Comprehension macros bind a variable in their body — handle them specially
+  // AST shape: { op: "rcall", args: [methodName, receiver, [boundVarId, body, ...]] }
+  if (
+    node.op === "rcall" &&
+    Array.isArray(node.args) &&
+    typeof node.args[0] === "string" &&
+    COMPREHENSION_METHODS.has(node.args[0])
+  ) {
+    const receiver = node.args[1];
+    const comprehensionArgs = node.args[2];
+    if (isASTNode(receiver)) visitNode(receiver, chains, boundVars);
+    if (
+      Array.isArray(comprehensionArgs) &&
+      comprehensionArgs.length >= 2 &&
+      isASTNode(comprehensionArgs[0]) &&
+      (comprehensionArgs[0] as ASTNode).op === "id"
+    ) {
+      const newBoundVars = new Set(boundVars);
+      newBoundVars.add((comprehensionArgs[0] as ASTNode).args as string);
+      for (let i = 1; i < comprehensionArgs.length; i++) {
+        const arg = comprehensionArgs[i];
+        if (isASTNode(arg)) visitNode(arg as ASTNode, chains, newBoundVars);
+      }
+    }
+    return;
+  }
+
+  const args = node.args;
+  if (Array.isArray(args)) {
+    for (const arg of args) {
+      if (isASTNode(arg)) {
+        visitNode(arg, chains, boundVars);
+      } else if (Array.isArray(arg)) {
+        for (const item of arg) {
+          if (isASTNode(item)) visitNode(item, chains, boundVars);
+        }
+      }
+    }
+  }
+}
+
+function isASTNode(v: unknown): v is ASTNode {
+  return v !== null && typeof v === "object" && "op" in (v as object);
+}
+
+/** Returns the member-access chain for a node if it is purely an id or "." chain; else null. */
+function extractChain(node: ASTNode, boundVars: Set<string>): string[] | null {
+  if (node.op === "id") {
+    const name = node.args as string;
+    if (boundVars.has(name)) return null; // bound by a comprehension macro, not a free access
+    return [name];
+  }
+  if (node.op === ".") {
+    const [obj, field] = node.args as [ASTNode, string];
+    const parent = extractChain(obj, boundVars);
+    if (parent !== null) return [...parent, field];
+  }
+  return null;
+}
+
+/**
+ * Check whether a member-access chain accesses only fields declared in a JSON Schema.
+ * Returns an error string if a field is unknown in a schema that declares explicit
+ * properties without `additionalProperties: true`.
+ * Returns null when the chain is valid or the schema is too open to judge.
+ */
+export function validateChainAgainstSchema(
+  chain: string[],
+  schema: Record<string, any>,
+): string | null {
+  let current: Record<string, any> = schema;
+  for (let i = 0; i < chain.length; i++) {
+    const key = chain[i]!;
+    if (!current || typeof current !== "object") return null;
+    // Open schema: no properties declared or explicitly allows additional properties
+    const props: Record<string, any> | undefined = current.properties;
+    if (!props) return null;
+    if (current.additionalProperties === true) return null;
+    if (!(key in props)) {
+      const path = chain.slice(0, i + 1).join(".");
+      const available = Object.keys(props).join(", ");
+      return `'${path}' is not defined (available: ${available})`;
+    }
+    current = props[key];
+  }
+  return null;
+}
+
+/**
+ * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].handler.inputs.name")
+ * falls within the container region of a context scope (e.g. "$.routes[*].handler").
+ *
+ * The container is derived by stripping the last dot-separated segment from the scope, so that
+ * sibling fields within the same parent (e.g. routes[*].response) also match.
+ */
+export function pathMatchesScope(exprPath: string, scope: string): boolean {
+  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+  const lastDot = stripped.lastIndexOf(".");
+  if (lastDot <= 0) return false;
+  const container = stripped.slice(0, lastDot); // e.g. "routes[*]"
+
+  // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
+  const parts = container.split("[*]");
+  let remaining = exprPath;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (!remaining.startsWith(part)) return false;
+    remaining = remaining.slice(part.length);
+    if (i < parts.length - 1) {
+      // Expect a concrete array index like [0], [12], ...
+      const m = remaining.match(/^\[\d+\]/);
+      if (!m) return false;
+      remaining = remaining.slice(m[0].length);
+    }
+  }
+  // Expression must end here or continue into a child path
+  return remaining === "" || remaining[0] === "." || remaining[0] === "[";
+}

package/src/validate-references.ts

@@ -0,0 +1,311 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+import { navigateJsonPointer } from "./schema-compat.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.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: string,
+  entry: RefFieldEntry,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): string[] {
+  const resolved = aliases.resolveKind(kind) ?? kind;
+  const errors: string[] = [];
+  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: ResourceManifest[],
+  context: AnalysisContext,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+  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<string, ResourceManifest>();
+  for (const r of resources) {
+    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) byName.set(r.metadata.name as string, 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 as string}`;
+    const resourceData = { kind: r.kind, name: r.metadata.name as string };
+
+    // 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<string, ResourceManifest[]>();
+    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 is ResourceManifest => !!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: ResourceManifest[] = [];
+      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 as string, 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 as Record<string, unknown>;
+
+        // 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 as string}`;
+    const resourceData = { kind: r.kind, name: r.metadata.name as string };
+
+    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: string;
+      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 as Record<string, unknown>;
+        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 as Record<string, any>);
+        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;
+}