@telorun/analyzer 0.2.1 → 0.4.0

package/dist/validate-extends.d.ts

@@ -0,0 +1,26 @@
+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";
+/**
+ * Phase 3b — Validate `extends` fields on Telo.Definition docs, and flag the legacy
+ * `capability: <UserAbstract>` overload with CAPABILITY_SHADOWS_EXTENDS so users migrate.
+ *
+ * `extends` uses alias form ("<Alias>.<Name>") resolved against the declaring file's
+ * Telo.Import declarations — same pattern as `kind:` prefixes. The analyzer pre-resolves
+ * via AliasResolver before register() is called, so by the time this validator runs,
+ * the definition's effective `extends` is either the canonical form (when the alias was
+ * known) or the original alias-prefixed string (when it wasn't).
+ *
+ * Diagnostics:
+ *  - EXTENDS_MALFORMED: value not in "<Alias>.<Name>" alias form, or not resolvable
+ *    via the declaring file's imports (alias unknown → can't distinguish from a typo).
+ *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
+ *    registered definition with the target name.
+ *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
+ *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
+ *    never trigger this — they're lifecycle roles by design.
+ */
+export declare function validateExtends(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-extends.d.ts.map

package/dist/validate-extends.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-extends.d.ts","sourceRoot":"","sources":["../src/validate-extends.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;AAOzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CA4ItB"}

package/dist/validate-extends.js

@@ -0,0 +1,163 @@
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** Alias-form pattern for `extends`: "<Alias>.<AbstractName>", two PascalCase segments. */
+const EXTENDS_ALIAS_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+/**
+ * Phase 3b — Validate `extends` fields on Telo.Definition docs, and flag the legacy
+ * `capability: <UserAbstract>` overload with CAPABILITY_SHADOWS_EXTENDS so users migrate.
+ *
+ * `extends` uses alias form ("<Alias>.<Name>") resolved against the declaring file's
+ * Telo.Import declarations — same pattern as `kind:` prefixes. The analyzer pre-resolves
+ * via AliasResolver before register() is called, so by the time this validator runs,
+ * the definition's effective `extends` is either the canonical form (when the alias was
+ * known) or the original alias-prefixed string (when it wasn't).
+ *
+ * Diagnostics:
+ *  - EXTENDS_MALFORMED: value not in "<Alias>.<Name>" alias form, or not resolvable
+ *    via the declaring file's imports (alias unknown → can't distinguish from a typo).
+ *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
+ *    registered definition with the target name.
+ *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
+ *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
+ *    never trigger this — they're lifecycle roles by design.
+ */
+export function validateExtends(manifests, registry, aliases) {
+    const diagnostics = [];
+    // Defs forwarded from imported libraries carry `metadata.module` set to that
+    // library's name (stamped by the loader). The analyzer's Phase 1 already normalized
+    // their `extends` against the declaring library's own alias scope (`aliasesByModule`
+    // in analyzer.ts), so the canonical-form value is correct. What this validator can't
+    // re-check is whether the original alias was well-formed in the library's source —
+    // that's the library author's concern, surfaced when the library is analyzed as a
+    // root. Re-validating here against the consumer's alias scope (which doesn't know
+    // the library's internal aliases) would produce false-positive EXTENDS_MALFORMED /
+    // EXTENDS_UNKNOWN_TARGET. Skip forwarded defs entirely.
+    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}`;
+        // --- extends validation ---
+        // At this point `m.extends` is whatever the manifest declared (alias form, e.g.
+        // "Ai.Model"). Resolve through the AliasResolver to the canonical form before
+        // looking up the target definition.
+        const extendsValue = m.extends;
+        if (extendsValue !== undefined) {
+            if (typeof extendsValue !== "string") {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "EXTENDS_MALFORMED",
+                    source: SOURCE,
+                    message: `${label}: 'extends' must be a string in alias form "<Alias>.<Name>"`,
+                    data: { resource, filePath, path: "extends" },
+                });
+            }
+            else if (!EXTENDS_ALIAS_RE.test(extendsValue)) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "EXTENDS_MALFORMED",
+                    source: SOURCE,
+                    message: `${label}: 'extends: ${extendsValue}' must be in alias form "<Alias>.<Name>" ` +
+                        `(e.g. "Ai.Model"), resolved via this file's Telo.Import declarations.`,
+                    data: { resource, filePath, path: "extends" },
+                });
+            }
+            else {
+                const prefix = extendsValue.slice(0, extendsValue.indexOf("."));
+                if (!aliases.hasAlias(prefix)) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "EXTENDS_MALFORMED",
+                        source: SOURCE,
+                        message: `${label}: 'extends: ${extendsValue}' — alias '${prefix}' is not a Telo.Import ` +
+                            `in this file's scope. Declare the import or correct the alias.`,
+                        data: { resource, filePath, path: "extends" },
+                    });
+                }
+                else {
+                    const canonical = aliases.resolveKind(extendsValue);
+                    if (!canonical) {
+                        // Alias exists but the suffix isn't in its exported kinds — behave like
+                        // an unknown target so users see the symbol is wrong, not that the alias is.
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "EXTENDS_UNKNOWN_TARGET",
+                            source: SOURCE,
+                            message: `${label}: 'extends' target '${extendsValue}' is not an exported kind of alias '${prefix}'.`,
+                            data: { resource, filePath, path: "extends" },
+                        });
+                    }
+                    else {
+                        const targetDef = registry.resolve(canonical);
+                        if (!targetDef) {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "EXTENDS_UNKNOWN_TARGET",
+                                source: SOURCE,
+                                message: `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is not a registered definition.`,
+                                data: { resource, filePath, path: "extends" },
+                            });
+                        }
+                        else if (targetDef.kind !== "Telo.Abstract") {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "EXTENDS_NON_ABSTRACT",
+                                source: SOURCE,
+                                message: `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is a ${targetDef.kind}, not a Telo.Abstract. ` +
+                                    `Only Telo.Abstract declarations may be extended.`,
+                                data: { resource, filePath, path: "extends" },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // --- legacy capability-as-abstract warning ---
+        // `capability` is expected to name either a builtin lifecycle (module "Telo") or a
+        // user-declared abstract. The latter is the pre-`extends` overload — emit a warning
+        // suggesting the canonical form. Resolve through aliases first because the manifest
+        // retains the alias-prefixed form (e.g. "AbstractLib.Greeter"); the registered key
+        // is the canonical form after alias resolution (e.g. "abstract-lib.Greeter").
+        const capability = m.capability;
+        if (typeof capability === "string") {
+            const resolvedCap = aliases.resolveKind(capability) ?? capability;
+            const capDef = registry.resolve(resolvedCap);
+            if (capDef &&
+                capDef.kind === "Telo.Abstract" &&
+                capDef.metadata.module !== "Telo") {
+                // Build suggestion using the original alias form if aliases can produce it.
+                const aliasesForModule = aliases.aliasesFor(capDef.metadata.module);
+                const suggestion = aliasesForModule.length > 0
+                    ? `${aliasesForModule[0]}.${capDef.metadata.name}`
+                    : `${capDef.metadata.module}.${capDef.metadata.name}`;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Warning,
+                    code: "CAPABILITY_SHADOWS_EXTENDS",
+                    source: SOURCE,
+                    message: `${label}: 'capability: ${capability}' names a user-declared abstract. ` +
+                        `Prefer 'extends' for implements-this-abstract declarations; 'capability' should ` +
+                        `name a lifecycle role. Use \`extends: "${suggestion}"\` with a lifecycle ` +
+                        `\`capability\` (e.g. Telo.Invocable, Telo.Provider, Telo.Service).`,
+                    data: { resource, filePath, path: "capability" },
+                });
+            }
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,7 +41,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.3.2"
+    "@telorun/sdk": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/alias-resolver.ts

@@ -34,4 +34,15 @@ export class AliasResolver {
   knownAliases(): string[] {
     return Array.from(this.importAliases.keys());
   }
+
+  /** Returns every alias that currently points at `targetModule`.
+   *  Used by clients that need to convert a canonical kind key (e.g. "http-server.Server")
+   *  back into its user-facing alias form (e.g. "Http.Server"). */
+  aliasesFor(targetModule: string): string[] {
+    const result: string[] = [];
+    for (const [alias, mod] of this.importAliases) {
+      if (mod === targetModule) result.push(alias);
+    }
+    return result;
+  }
 }

package/src/analysis-registry.ts

@@ -2,6 +2,7 @@ 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 { computeSuggestKind, computeValidUserFacingKinds } from "./kind-suggest.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 import type { AnalysisContext } from "./types.js";
 
@@ -71,6 +72,26 @@ export class AnalysisRegistry {
     return this._context().definitions?.kinds() ?? [];
   }
 
+  /** Returns every import alias that points at `moduleName` (the canonical, kebab-case
+   *  module name). Empty when no import declares that target. */
+  aliasesFor(moduleName: string): string[] {
+    return this.aliases.aliasesFor(moduleName);
+  }
+
+  /** Returns every user-facing kind that is legal in the current scope:
+   *  Telo root kinds plus the alias form of each non-abstract imported definition.
+   *  Used by editor hosts to drive completion and by the analyzer to produce
+   *  "did you mean" hints. */
+  validUserFacingKinds(): string[] {
+    return computeValidUserFacingKinds(this.aliases, this.defs);
+  }
+
+  /** Returns the closest user-facing kind to `badKind`, or undefined when nothing
+   *  is close enough (or multiple candidates tie). Case-sensitive. */
+  suggestKind(badKind: string): string | undefined {
+    return computeSuggestKind(badKind, this.aliases, this.defs);
+  }
+
   /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
   _context(): AnalysisContext {
     return { aliases: this.aliases, definitions: this.defs };

package/src/analyzer.ts

@@ -10,6 +10,7 @@ import {
 import { DefinitionRegistry } from "./definition-registry.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
+import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import {
@@ -27,6 +28,7 @@ import {
   resolveTypeFieldToSchema,
   validateChainAgainstSchema,
 } from "./validate-cel-context.js";
+import { validateExtends } from "./validate-extends.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
@@ -292,9 +294,24 @@ export class StaticAnalyzer {
     // Register module identities and aliases.
     // The root module doc (Telo.Application or Telo.Library) provides its own
     // identity; imported modules surface their identity via resolvedModuleName/
-    // resolvedNamespace stamped onto the Telo.Import by the loader (so we don't
-    // need to include imported module manifests in the analysis set, avoiding false
-    // reference errors in the parent context).
+    // resolvedNamespace stamped onto the Telo.Import by the loader.
+    //
+    // Two alias scopes are tracked:
+    //  - `aliases` — the consumer's aliases, populated from Telo.Imports declared in
+    //    the entry manifest (its own module).
+    //  - `aliasesByModule` — per-imported-library aliases, populated from Telo.Imports
+    //    forwarded by the loader from inside imported libraries. A library may use
+    //    different alias names than the consumer for the same dependency; resolving
+    //    a forwarded def's `extends` / `capability` against the consumer's scope
+    //    would either fail or pick the wrong target. Each forwarded def is normalized
+    //    in its own library's scope.
+    const rootModules = new Set<string>();
+    for (const m of manifests) {
+      if (isModuleKind(m.kind) && m.metadata?.name) {
+        rootModules.add(m.metadata.name as string);
+      }
+    }
+    const aliasesByModule = new Map<string, AliasResolver>();
     for (const m of manifests) {
       if (isModuleKind(m.kind)) {
         const namespace = ((m.metadata as any).namespace as string | undefined) ?? null;
@@ -310,30 +327,60 @@ export class StaticAnalyzer {
           | string
           | null
           | undefined;
+        const ownModule = (m.metadata as { module?: string } | undefined)?.module;
         if (alias && source) {
           const targetModule =
             resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
-          aliases.registerImport(alias, targetModule, exportedKinds);
+          // Module identity is registered globally so x-telo-ref resolution sees
+          // transitively-imported modules regardless of which scope brought them in.
           if (resolvedModuleName) {
             defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
           }
+          // Alias registration is scoped: consumer imports vs. imported-library imports.
+          if (!ownModule || rootModules.has(ownModule)) {
+            aliases.registerImport(alias, targetModule, exportedKinds);
+          } else {
+            let libResolver = aliasesByModule.get(ownModule);
+            if (!libResolver) {
+              libResolver = new AliasResolver();
+              aliasesByModule.set(ownModule, libResolver);
+            }
+            libResolver.registerImport(alias, targetModule, exportedKinds);
+          }
         }
       }
     }
 
-    // Register definitions from Telo.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).
+    // Register definitions from Telo.Definition AND Telo.Abstract resources.
+    // Abstracts declare contracts that implementations target via `extends` (canonical)
+    // or `capability: <AbstractKind>` (legacy). Until they're registered, validateReferences
+    // can't resolve x-telo-ref entries pointing at library-declared abstracts — so abstracts
+    // must go through register() too, not just the kernel builtins in the constructor.
+    //
+    // Normalize alias-prefixed `capability` and `extends` to canonical form using the
+    // declaring scope's resolver, so `extendedBy` is keyed by canonical kind regardless
+    // of alias choices. `capability` covers the legacy implements-this-abstract overload;
+    // `extends` is the canonical first-class form.
     for (const m of manifests) {
-      if (m.kind === "Telo.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,
-        );
-      }
+      if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
+      const def = m as unknown as ResourceDefinition;
+      const ownModule = (def.metadata as { module?: string } | undefined)?.module;
+      const scopeResolver =
+        ownModule && !rootModules.has(ownModule)
+          ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
+          : aliases;
+      const resolvedCapability = def.capability
+        ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
+        : def.capability;
+      const resolvedExtends = def.extends
+        ? (scopeResolver.resolveKind(def.extends) ?? def.extends)
+        : def.extends;
+      const needsPatch =
+        resolvedCapability !== def.capability || resolvedExtends !== def.extends;
+      const normalized = needsPatch
+        ? { ...def, capability: resolvedCapability, extends: resolvedExtends }
+        : def;
+      defs.register(normalized);
     }
 
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
@@ -377,18 +424,14 @@ export class StaticAnalyzer {
       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(" | ")}` : "";
+        const suggestedKind = computeSuggestKind(m.kind, aliases, defs);
+        const hint = suggestedKind ? ` Did you mean '${suggestedKind}'?` : "";
         diagnostics.push({
           severity: DiagnosticSeverity.Error,
           code: "UNDEFINED_KIND",
           source: SOURCE,
           message: `No Telo.Definition found for kind '${m.kind}'.${hint}`,
-          data: { resource, filePath, path: "kind" },
+          data: { resource, filePath, path: "kind", suggestedKind },
         });
         continue;
       }
@@ -523,6 +566,9 @@ export class StaticAnalyzer {
     // Validate resource references (Phase 3)
     diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs }));
 
+    // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
+    diagnostics.push(...validateExtends(allManifests, defs, aliases));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 

package/src/builtins.ts

@@ -27,9 +27,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           additionalProperties: true,
         },
         capability: { type: "string" },
+        schema: { type: "object", additionalProperties: true },
       },
       required: ["metadata"],
-      additionalProperties: false,
+      // Telo.Abstract is an extension point by design — it must accept forward-compatible
+      // fields (e.g. inputType/outputType from the typed-abstracts plan) without requiring
+      // the analyzer to enumerate them here.
+      additionalProperties: true,
     },
   },
   {
@@ -55,6 +59,12 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         source: { type: "string" },
         variables: { type: "object" },
         secrets: { type: "object" },
+        runtime: {
+          oneOf: [
+            { type: "string" },
+            { type: "array", items: { type: "string" } },
+          ],
+        },
       },
       required: ["metadata", "source"],
       additionalProperties: false,

package/src/definition-registry.ts

@@ -32,13 +32,22 @@ export class DefinitionRegistry {
     const key = mod ? `${mod}.${name}` : name;
     this.defs.set(key, definition);
     this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+    // `capability` populates extendedBy for backward-compat with the legacy pattern where
+    // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
+    // this abstract." The canonical pattern is `extends` (below). Both populate the index,
+    // unioned — so in-flight modules pre-migration keep working.
     if (definition.capability) {
-      const children = this.extendedBy.get(definition.capability);
-      if (children) {
-        children.push(key);
-      } else {
-        this.extendedBy.set(definition.capability, [key]);
-      }
+      this.addExtendedBy(definition.capability, key);
+    }
+    // `extends` — first-class "implements-this-abstract" edge. Alias-form resolution
+    // happens in the analyzer before register() is called (analyzer.ts pre-resolves
+    // via aliases.resolveKind), so the value here is already the canonical kind string
+    // (e.g. "workflow.Backend"). If the analyzer could not resolve the alias (partial
+    // context, or the declaring file doesn't import the target's alias), the value
+    // stays as the original alias-prefixed form; validateExtends emits EXTENDS_MALFORMED
+    // or EXTENDS_UNKNOWN_TARGET depending on the case.
+    if (definition.extends) {
+      this.addExtendedBy(definition.extends, key);
     }
     // Auto-register the telo identity when any Telo built-in is registered.
     if (definition.kind === "Telo.Abstract" && mod === "Telo") {
@@ -51,6 +60,15 @@ export class DefinitionRegistry {
     }
   }
 
+  private addExtendedBy(parent: string, child: string): void {
+    const children = this.extendedBy.get(parent);
+    if (children) {
+      if (!children.includes(child)) children.push(child);
+    } else {
+      this.extendedBy.set(parent, [child]);
+    }
+  }
+
   /** Register a module identity for x-telo-ref resolution.
    *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.

package/src/kind-suggest.ts

@@ -0,0 +1,77 @@
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { distance } from "./levenshtein.js";
+
+/** User-facing root kinds that are always legal regardless of imports. */
+const ROOT_KINDS = [
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+  "Telo.Definition",
+] as const;
+
+/** Definition kinds that are not user-instantiable and should be excluded
+ *  from completion / suggestion lists. */
+const ABSTRACT_DEF_KINDS = new Set(["Telo.Abstract", "Telo.Template"]);
+
+/** Computes the set of user-facing kind strings available in the given
+ *  (aliases, defs) context:
+ *    - The hardcoded Telo root kinds.
+ *    - For every registered non-abstract definition, the alias form
+ *      `${alias}.${TypeName}` for each import alias that points at its
+ *      module. Canonical kebab-case forms (e.g. `http-server.Server`) are
+ *      deliberately excluded — users write manifests via alias. */
+export function computeValidUserFacingKinds(
+  aliases: AliasResolver,
+  defs: DefinitionRegistry,
+): string[] {
+  const out = new Set<string>(ROOT_KINDS);
+
+  for (const kind of defs.kinds()) {
+    const def = defs.resolve(kind);
+    if (!def || ABSTRACT_DEF_KINDS.has(def.kind)) continue;
+
+    const dot = kind.indexOf(".");
+    if (dot === -1) continue;
+    const moduleName = kind.slice(0, dot);
+    const typeName = kind.slice(dot + 1);
+
+    for (const alias of aliases.aliasesFor(moduleName)) {
+      out.add(`${alias}.${typeName}`);
+    }
+  }
+
+  return Array.from(out);
+}
+
+/** Returns the closest user-facing kind to `badKind` within an edit-distance
+ *  threshold, or undefined when nothing close enough exists (including ties).
+ *  Case-sensitive — kinds are PascalCase by contract. */
+export function computeSuggestKind(
+  badKind: string,
+  aliases: AliasResolver,
+  defs: DefinitionRegistry,
+): string | undefined {
+  if (!badKind) return undefined;
+  const candidates = computeValidUserFacingKinds(aliases, defs);
+  const threshold = Math.min(3, Math.floor(badKind.length / 3));
+  if (threshold < 1) return undefined;
+
+  let best: string | undefined;
+  let bestDist = threshold + 1;
+  let tied = false;
+
+  for (const c of candidates) {
+    const d = distance(badKind, c);
+    if (d < bestDist) {
+      best = c;
+      bestDist = d;
+      tied = false;
+    } else if (d === bestDist) {
+      tied = true;
+    }
+  }
+
+  if (!best || bestDist > threshold || tied) return undefined;
+  return best;
+}

package/src/levenshtein.ts

@@ -0,0 +1,36 @@
+/** Classic Wagner-Fischer Levenshtein distance. Iterative with two rolling rows
+ *  so memory is O(min(a, b)); sufficient for short strings like resource kind
+ *  identifiers (a few dozen characters at most). */
+export function distance(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Ensure b is the shorter string so the row buffer stays small.
+  if (a.length < b.length) {
+    const tmp = a;
+    a = b;
+    b = tmp;
+  }
+
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,      // insertion
+        prev[j] + 1,          // deletion
+        prev[j - 1] + cost,   // substitution
+      );
+    }
+    const swap = prev;
+    prev = curr;
+    curr = swap;
+  }
+
+  return prev[b.length];
+}