@telorun/analyzer 0.10.1 → 1.1.0

package/dist/validate-provider-coherence.d.ts

@@ -0,0 +1,23 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * 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 declare function validateProviderCoherence(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-provider-coherence.d.ts.map

package/dist/validate-provider-coherence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAyItB"}

package/dist/validate-provider-coherence.js

@@ -0,0 +1,148 @@
+import { DiagnosticSeverity } 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, registry, aliases) {
+    const diagnostics = [];
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata
+            ?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const name = m.metadata?.name;
+        if (!name)
+            continue;
+        const ownModule = m.metadata?.module;
+        if (ownModule && importedModules.has(ownModule))
+            continue;
+        const filePath = m.metadata?.source;
+        const resource = { kind: m.kind, name };
+        const label = `${m.kind}/${name}`;
+        const md = m;
+        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;
+            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?.metadata;
+                    return typeof meta?.name === "string" && meta.name === providedName;
+                });
+                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.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/dist/validate-references.js

@@ -1,4 +1,4 @@
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues } from "./reference-field-map.js";
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
@@ -119,7 +119,7 @@ export function validateReferences(resources, context) {
                     }
                 }
             }
-            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.
@@ -142,8 +142,8 @@ export function validateReferences(resources, context) {
                             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;
                     }
@@ -153,8 +153,8 @@ export function validateReferences(resources, context) {
                             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;
@@ -171,8 +171,8 @@ export function validateReferences(resources, context) {
                         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;
                 }
@@ -183,8 +183,8 @@ export function validateReferences(resources, context) {
                         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 },
                     });
                 }
                 // 3. Resolution check — resource with this name must exist.
@@ -195,8 +195,8 @@ export function validateReferences(resources, context) {
                         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 },
                     });
                 }
             }
@@ -279,7 +279,7 @@ export function validateReferences(resources, context) {
                     });
                     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);
@@ -288,8 +288,8 @@ export function validateReferences(resources, context) {
                             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 },
                         });
                     }
                 }
@@ -309,9 +309,9 @@ export function validateReferences(resources, context) {
             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];
+            const fieldEntries = resolveFieldEntries(r, fieldPath);
+            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.
@@ -328,8 +328,8 @@ export function validateReferences(resources, context) {
                         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;
                 }
@@ -339,8 +339,8 @@ export function validateReferences(resources, context) {
                         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;
                 }
@@ -350,8 +350,8 @@ export function validateReferences(resources, context) {
                         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 },
                     });
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.10.1",
+  "version": "1.1.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,14 +41,16 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.11.1",
-    "@telorun/templating": "0.2.3"
+    "@telorun/templating": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "1.0.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",
     "test": "vitest run",

package/src/analysis-registry.ts

@@ -101,6 +101,43 @@ export class AnalysisRegistry {
     return computeSuggestKind(badKind, this.aliases, this.defs);
   }
 
+  /** Returns every user-facing (alias-form) kind that satisfies the given
+   *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+   *  Resolution mirrors `validateReferences.checkKind`: abstract targets expand to
+   *  the set of definitions extending them; concrete targets yield just themselves.
+   *  Returns `undefined` when the ref can't be resolved (e.g. unregistered identity),
+   *  so callers can fall back to the unfiltered kind list. */
+  userFacingKindsForRef(xTeloRef: string): string[] | undefined {
+    const targetKind = this.defs.resolveRef(xTeloRef);
+    if (!targetKind) return undefined;
+    const targetDef = this.defs.resolve(targetKind);
+    if (!targetDef) return undefined;
+
+    const canonicalKinds: string[] = [];
+    if (targetDef.kind === "Telo.Abstract") {
+      for (const def of this.defs.getByExtends(targetKind)) {
+        const module = (def.metadata as { module?: string } | undefined)?.module;
+        if (module && def.metadata?.name) {
+          canonicalKinds.push(`${module}.${def.metadata.name as string}`);
+        }
+      }
+    } else {
+      canonicalKinds.push(targetKind);
+    }
+
+    const out = new Set<string>();
+    for (const kind of canonicalKinds) {
+      const dot = kind.indexOf(".");
+      if (dot === -1) continue;
+      const moduleName = kind.slice(0, dot);
+      const typeName = kind.slice(dot + 1);
+      for (const alias of this.aliases.aliasesFor(moduleName)) {
+        out.add(`${alias}.${typeName}`);
+      }
+    }
+    return Array.from(out);
+  }
+
   /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
   _context(): AnalysisContext {
     return { aliases: this.aliases, definitions: this.defs, aliasesByModule: this.aliasesByModule };