@telorun/analyzer 0.10.1 → 1.1.0

package/src/validate-provider-coherence.ts

@@ -0,0 +1,166 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Validates coherence rules for `Telo.Definition` documents that use the `provide:`
+ * template target, plus the implementation-presence rule on `Telo.Provider`
+ * definitions.
+ *
+ * Diagnostics:
+ *  - PROVIDE_ON_NON_PROVIDER: `provide:` declared on a definition whose
+ *    `capability` is not `Telo.Provider`.
+ *  - PROVIDE_DISPATCHER_CONFLICT: `provide:` co-exists with `invoke:` or `run:`
+ *    on the same definition.
+ *  - PROVIDE_TARGET_UNKNOWN: `provide.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - PROVIDE_TARGET_NOT_INVOCABLE: `provide.name` resolves to a resource whose
+ *    kind is registered but not a `Telo.Invocable`.
+ *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
+ *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ */
+export function validateProviderCoherence(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  const importedModules = new Set<string>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const resolved = (m.metadata as { resolvedModuleName?: string } | undefined)
+      ?.resolvedModuleName;
+    if (resolved) importedModules.add(resolved);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    if (!name) continue;
+    const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+    if (ownModule && importedModules.has(ownModule)) continue;
+    const filePath = (m.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: m.kind, name };
+    const label = `${m.kind}/${name}`;
+
+    const md = m as Record<string, unknown>;
+    const capability = typeof md.capability === "string" ? md.capability : undefined;
+    const provide = md.provide;
+    const invoke = md.invoke;
+    const run = md.run;
+    const controllers = md.controllers;
+    const resources = md.resources;
+
+    const hasProvide = provide !== undefined && provide !== null;
+    const hasInvoke = invoke !== undefined && invoke !== null;
+    const hasRun = run !== undefined && run !== null;
+    const hasControllers = Array.isArray(controllers) && controllers.length > 0;
+
+    if (hasProvide && capability !== "Telo.Provider") {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_ON_NON_PROVIDER",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' is only valid on definitions with 'capability: Telo.Provider' ` +
+          `(found '${capability ?? "<unset>"}'). Use 'invoke:' or 'run:' for other capabilities.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && (hasInvoke || hasRun)) {
+      const conflict = hasInvoke ? "invoke" : "run";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_DISPATCHER_CONFLICT",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' cannot co-exist with '${conflict}:'. ` +
+          `A definition declares exactly one dispatch entry-point.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && typeof provide === "object" && !Array.isArray(provide)) {
+      const provideObj = provide as { kind?: unknown; name?: unknown };
+      const providedName = typeof provideObj.name === "string" ? provideObj.name : undefined;
+      const providedKind = typeof provideObj.kind === "string" ? provideObj.kind : undefined;
+      if (providedName && Array.isArray(resources)) {
+        const match = resources.find((r) => {
+          const meta = (r as { metadata?: { name?: unknown } })?.metadata;
+          return typeof meta?.name === "string" && meta.name === providedName;
+        }) as { kind?: unknown } | undefined;
+        if (!match) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "PROVIDE_TARGET_UNKNOWN",
+            source: SOURCE,
+            message:
+              `${label}: 'provide.name: ${providedName}' does not match any entry's ` +
+              `metadata.name in 'resources:'.`,
+            data: { resource, filePath, path: "provide.name" },
+          });
+        } else if (typeof match.kind === "string") {
+          // `provide.kind` is the type contract the analyzer uses to type
+          // `result` CEL against the target's `outputType`. The runtime
+          // dispatches on `provide.name` and ignores `provide.kind`, so a
+          // mismatch silently degrades `result` typing to an open schema
+          // (and at runtime quietly invokes the actually-matched resource).
+          // Flag the divergence so result-typing never lies.
+          if (providedKind) {
+            const providedCanonical = aliases.resolveKind(providedKind) ?? providedKind;
+            const matchCanonical = aliases.resolveKind(match.kind) ?? match.kind;
+            if (providedCanonical !== matchCanonical) {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_KIND_MISMATCH",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.kind: ${providedKind}' disagrees with the matched ` +
+                  `'resources:' entry's kind '${match.kind}' (matched by metadata.name ` +
+                  `'${providedName}'). The runtime dispatches by name, so 'provide.kind' ` +
+                  `is decorative — but the analyzer types 'result:' against it, and a ` +
+                  `mismatch silently turns off that typing.`,
+                data: { resource, filePath, path: "provide.kind" },
+              });
+            }
+          }
+          const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+          const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+          if (targetDef && targetDef.kind === "Telo.Definition") {
+            const targetCap = (targetDef as { capability?: unknown }).capability;
+            if (typeof targetCap === "string" && targetCap !== "Telo.Invocable") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_TARGET_NOT_INVOCABLE",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.name: ${providedName}' resolves to a ${match.kind} ` +
+                  `(capability '${targetCap}'); 'provide:' requires a Telo.Invocable target.`,
+                data: { resource, filePath, path: "provide.name" },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDER_MISSING_IMPLEMENTATION",
+        source: SOURCE,
+        message:
+          `${label}: 'capability: Telo.Provider' requires either 'controllers:' ` +
+          `(TS-backed) or 'provide:' (template-backed) to declare an implementation.`,
+        data: { resource, filePath, path: "capability" },
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/validate-references.ts

@@ -1,5 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, 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";
@@ -142,7 +142,7 @@ export function validateReferences(
         }
       }
 
-      for (const val of resolveFieldValues(r, fieldPath)) {
+      for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
         if (!val) continue;
 
         // Name-only reference (plain string) — look up by name to validate.
@@ -166,8 +166,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
             continue;
           }
@@ -177,8 +177,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "REFERENCE_KIND_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
           continue;
@@ -196,8 +196,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "INVALID_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -209,8 +209,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "REFERENCE_KIND_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
 
@@ -223,8 +223,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "UNRESOLVED_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }
@@ -317,7 +317,7 @@ export function validateReferences(
           continue;
         }
 
-        for (const fieldValue of resolveFieldValues(r, fieldPath)) {
+        for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
           if (fieldValue == null) continue;
           const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
           for (const issue of issues) {
@@ -325,8 +325,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "DEPENDENT_SCHEMA_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: '${fieldPath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
         }
@@ -347,10 +347,10 @@ export function validateReferences(
       const anchorValues = resolveFieldValues(r, anchorPath);
       if (anchorValues.length === 0) continue; // anchor field not set — nothing to validate
 
-      const fieldValues = resolveFieldValues(r, fieldPath);
+      const fieldEntries = resolveFieldEntries(r, fieldPath);
 
-      for (let i = 0; i < fieldValues.length; i++) {
-        const fieldValue = fieldValues[i];
+      for (let i = 0; i < fieldEntries.length; i++) {
+        const { value: fieldValue, path: concretePath } = fieldEntries[i];
         if (fieldValue == null) continue;
 
         // For absolute paths, the single anchor applies to all field values.
@@ -367,8 +367,8 @@ export function validateReferences(
             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, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -379,8 +379,8 @@ export function validateReferences(
             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, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -391,8 +391,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "DEPENDENT_SCHEMA_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: '${concretePath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }