@telorun/analyzer 0.32.0 → 0.34.0

package/src/extends-resolution.ts

@@ -0,0 +1,124 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import { mergeTypeSchemas } from "@telorun/sdk";
+
+/** Resolves a kind string (canonical or alias form, depending on the caller's
+ *  registry) to its `Telo.Definition` / `Telo.Abstract`, or undefined. */
+export type DefResolver = (kind: string) => ResourceDefinition | undefined;
+
+/** The template-body / controller fields a definition may carry. Kept local
+ *  because `ResourceDefinition` intentionally types only the stable surface;
+ *  template bodies are read structurally. */
+interface DefinitionBody {
+  extends?: string;
+  capability?: string;
+  controllers?: unknown[];
+  invoke?: unknown;
+  run?: unknown;
+  provide?: unknown;
+  mount?: unknown;
+  resources?: unknown[];
+  base?: Record<string, unknown>;
+  schema?: Record<string, any>;
+}
+
+const body = (def: ResourceDefinition | undefined): DefinitionBody =>
+  (def ?? {}) as unknown as DefinitionBody;
+
+/** The definition a given definition directly `extends`, or undefined when it
+ *  extends nothing / the target can't be resolved. */
+export function resolveParent(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): ResourceDefinition | undefined {
+  const ext = body(def).extends;
+  if (typeof ext !== "string" || ext.length === 0) return undefined;
+  return resolve(ext);
+}
+
+/** The `extends` ancestor chain, nearest-first, excluding `def` itself.
+ *  Cycle-guarded so a malformed self/mutual `extends` can't loop forever. */
+export function ancestorChain(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): ResourceDefinition[] {
+  const chain: ResourceDefinition[] = [];
+  const seen = new Set<ResourceDefinition>();
+  let cur = resolveParent(def, resolve);
+  while (cur && !seen.has(cur)) {
+    seen.add(cur);
+    chain.push(cur);
+    cur = resolveParent(cur, resolve);
+  }
+  return chain;
+}
+
+/** True when a definition carries its own controller (`controllers:`) or a
+ *  template body (`invoke:` / `run:` / `provide:` / `mount:` / `resources:`). */
+export function hasOwnControllerOrTemplate(def: ResourceDefinition | undefined): boolean {
+  const d = body(def);
+  return !!(
+    (d.controllers && d.controllers.length) ||
+    d.invoke ||
+    d.run ||
+    d.provide ||
+    d.mount ||
+    d.resources
+  );
+}
+
+/** The nearest concrete ancestor that provides a controller (own `controllers:`
+ *  or a template body) — the definition whose controller an inherited child
+ *  delegates to. Undefined when no controller-bearing concrete ancestor exists. */
+export function controllerBearingAncestor(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): ResourceDefinition | undefined {
+  for (const a of ancestorChain(def, resolve)) {
+    if (a.kind === "Telo.Abstract") continue;
+    if (hasOwnControllerOrTemplate(a)) return a;
+  }
+  return undefined;
+}
+
+/** True when this definition inherits its controller by delegation: it declares
+ *  `extends`, has no own controller/template body, and its nearest concrete
+ *  ancestor is controller-bearing. */
+export function isInheritedDelegation(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): boolean {
+  if (!body(def).extends || hasOwnControllerOrTemplate(def)) return false;
+  return controllerBearingAncestor(def, resolve) !== undefined;
+}
+
+/** The effective (possibly inherited) capability: the nearest self-or-ancestor
+ *  that declares a `capability`. Undefined when none in the chain does. */
+export function inheritedCapability(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): string | undefined {
+  if (body(def).capability) return body(def).capability;
+  for (const a of ancestorChain(def, resolve)) {
+    if (body(a).capability) return body(a).capability;
+  }
+  return undefined;
+}
+
+/** The author-facing schema for a definition:
+ *  - with `base:` present → the definition's **own** schema (the parent's config
+ *    fields are internal, set solely through `base:`).
+ *  - without `base:` but with `extends` → `merge(parent-effective, own)` (a pure
+ *    additive extension; child overrides on key conflicts), reusing the same
+ *    `mergeTypeSchemas` that `Type.JsonSchema.extends` uses.
+ *  - no `extends` → the own schema unchanged. */
+export function effectiveAuthorSchema(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): Record<string, any> {
+  const own = (body(def).schema ?? {}) as Record<string, any>;
+  const parent = resolveParent(def, resolve);
+  if (!parent) return own;
+  if (body(def).base) return own;
+  const parentSchema = effectiveAuthorSchema(parent, resolve);
+  return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
+}

package/src/index.ts

@@ -22,6 +22,18 @@ export {
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  ancestorChain,
+  controllerBearingAncestor,
+  effectiveAuthorSchema,
+  hasOwnControllerOrTemplate,
+  inheritedCapability,
+  isInheritedDelegation,
+  resolveParent,
+} from "./extends-resolution.js";
+export type { DefResolver } from "./extends-resolution.js";
+export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
+export type { ReferenceFieldMap, RefFieldEntry } from "./reference-field-map.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,
@@ -59,6 +71,7 @@ export {
   verifyIntegrity,
   verifiedFetch,
   sha256Base64Url,
+  IntegrityError,
 } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";

package/src/sources/integrity.ts

@@ -11,6 +11,17 @@
  *  only algorithm accepted today; the prefix leaves room to migrate. */
 const INTEGRITY_FRAGMENT = /#(sha256-[A-Za-z0-9_+/=-]+)$/;
 
+/** A failed integrity/tamper check — always terminal, never best-effort. A
+ *  distinct type so a caller doing best-effort network handling (e.g. the
+ *  bundle extractor warning-and-skipping on a fetch blip) can still let a
+ *  tamper error propagate rather than swallow it. */
+export class IntegrityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+}
+
 /** Split a trailing integrity fragment off a ref/URL. Returns the bare ref in
  *  `base` (safe to build fetch URLs and cache paths from) and the fragment in
  *  `integrity` (e.g. `sha256-<base64url>`), or `undefined` when absent. */
@@ -64,14 +75,14 @@ export async function verifyIntegrity(
   const algorithm = dash > 0 ? integrity.slice(0, dash) : "";
   const expected = dash > 0 ? integrity.slice(dash + 1) : "";
   if (algorithm !== "sha256") {
-    throw new Error(
+    throw new IntegrityError(
       `Unsupported integrity algorithm '${algorithm || integrity}' for ${describe}. ` +
         `Only sha256 is supported (sha256-<base64url>).`,
     );
   }
   const actual = await sha256Base64Url(bytes);
   if (actual !== normalizeDigest(expected)) {
-    throw new Error(
+    throw new IntegrityError(
       `Integrity check failed for ${describe}: expected sha256-${normalizeDigest(expected)}, ` +
         `got sha256-${actual}. The fetched bytes do not match the recorded hash — ` +
         `the module may have been tampered with or republished.`,

package/src/sources/module-ref.ts

@@ -10,17 +10,18 @@ export interface ParsedModuleRef {
 }
 
 /** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme, no leading `/` or `.`, contains both `@` and `/`). The integrity
- *  fragment, if any, does not affect the classification. */
+ *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
+ *  The integrity fragment, if any, does not affect the classification.
+ *
+ *  A registry ref never carries a `scheme://` — that guard is what keeps an
+ *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
+ *  scheme-owning transport claims it instead. */
 export function isRegistryRef(url: string): boolean {
   const { base } = splitIntegrity(url);
   return (
-    !base.startsWith("http://") &&
-    !base.startsWith("https://") &&
+    !base.includes("://") &&
     !base.startsWith("/") &&
     !base.startsWith(".") &&
-    !base.startsWith("file://") &&
-    !base.startsWith("memory://") &&
     base.includes("@") &&
     base.includes("/")
   );

package/src/validate-base-mapping.ts

@@ -0,0 +1,154 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { isCompiledValue } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { effectiveAuthorSchema, resolveParent, type DefResolver } from "./extends-resolution.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** True when a value subtree contains a compiled CEL leaf — such a value can
+ *  produce anything at runtime, so its type is not statically checkable. */
+function containsCel(value: unknown): boolean {
+  if (isCompiledValue(value)) return true;
+  if (Array.isArray(value)) return value.some(containsCel);
+  if (value && typeof value === "object") {
+    return Object.values(value as Record<string, unknown>).some(containsCel);
+  }
+  return false;
+}
+
+/**
+ * Phase 3c — Static validation of a definition's `base:` construction mapping
+ * against the parent kind's config schema. The kernel evaluates `base:` and
+ * passes the result to the inherited controller's `create()`, which validates it
+ * at boot; this mirrors that check statically so an omitted required field or a
+ * wrong literal type surfaces at `telo check`, not first boot.
+ *
+ * Diagnostics:
+ *  - BASE_MISSING_REQUIRED: `base:` omits a field the parent schema requires.
+ *  - BASE_UNKNOWN_FIELD: `base:` sets a field the parent schema (with
+ *    `additionalProperties: false`) does not declare.
+ *  - BASE_SCHEMA_MISMATCH: a CEL-free `base:` value violates the parent field's
+ *    schema (wrong type / constraint). CEL-bearing values are skipped — their
+ *    runtime value is unknown — but still count as present for required checks.
+ */
+export function validateBaseMapping(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+  const resolveDef: DefResolver = (k) =>
+    registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
+
+  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 base = (m as { base?: unknown }).base;
+    if (!base || typeof base !== "object" || Array.isArray(base)) 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 parent = resolveParent(m as unknown as ResourceDefinition, resolveDef);
+    // Missing / unresolved `extends` is already reported by validateExtends.
+    if (!parent) continue;
+    const parentSchema = effectiveAuthorSchema(parent, resolveDef);
+    if (!parentSchema || typeof parentSchema !== "object") continue;
+
+    const filePath = (m.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: m.kind, name };
+    const label = `${m.kind}/${name}`;
+    checkObject(base as Record<string, unknown>, parentSchema, "base", {
+      diagnostics,
+      registry,
+      label,
+      resource,
+      filePath,
+    });
+  }
+
+  return diagnostics;
+}
+
+interface CheckCtx {
+  diagnostics: AnalysisDiagnostic[];
+  registry: DefinitionRegistry;
+  label: string;
+  resource: { kind: string; name: string };
+  filePath: string | undefined;
+}
+
+function checkObject(
+  value: Record<string, unknown>,
+  schema: Record<string, any>,
+  path: string,
+  ctx: CheckCtx,
+): void {
+  const properties = (schema.properties ?? {}) as Record<string, Record<string, any>>;
+  const required = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+  const additionalFalse = schema.additionalProperties === false;
+
+  for (const req of required) {
+    if (!(req in value)) {
+      ctx.diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "BASE_MISSING_REQUIRED",
+        source: SOURCE,
+        message: `${ctx.label}: '${path}' does not set required parent field '${req}'.`,
+        data: { resource: ctx.resource, filePath: ctx.filePath, path },
+      });
+    }
+  }
+
+  for (const [key, fieldValue] of Object.entries(value)) {
+    const fieldPath = `${path}.${key}`;
+    const propSchema = properties[key];
+    if (!propSchema) {
+      if (additionalFalse) {
+        ctx.diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "BASE_UNKNOWN_FIELD",
+          source: SOURCE,
+          message: `${ctx.label}: '${fieldPath}' is not a field of the parent kind's schema.`,
+          data: { resource: ctx.resource, filePath: ctx.filePath, path: fieldPath },
+        });
+      }
+      continue;
+    }
+    // A CEL-bearing value produces its shape at runtime — not statically
+    // checkable. Recurse into a partially-CEL nested object so its literal
+    // sub-fields still get validated; fully-literal values validate directly.
+    if (containsCel(fieldValue)) {
+      if (
+        fieldValue &&
+        typeof fieldValue === "object" &&
+        !Array.isArray(fieldValue) &&
+        !isCompiledValue(fieldValue) &&
+        propSchema.type === "object" &&
+        propSchema.properties
+      ) {
+        checkObject(fieldValue as Record<string, unknown>, propSchema, fieldPath, ctx);
+      }
+      continue;
+    }
+    const issues = ctx.registry.validateWithRefs(fieldValue, propSchema);
+    for (const issue of issues) {
+      ctx.diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "BASE_SCHEMA_MISMATCH",
+        source: SOURCE,
+        message: `${ctx.label}: '${fieldPath}' does not match the parent field's schema: ${issue}`,
+        data: { resource: ctx.resource, filePath: ctx.filePath, path: fieldPath },
+      });
+    }
+  }
+}

package/src/validate-extends.ts

@@ -1,6 +1,7 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { inheritedCapability, type DefResolver } from "./extends-resolution.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -119,16 +120,28 @@ export function validateExtends(
                 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" },
-              });
+            } else {
+              // General single inheritance: any concrete or abstract kind may be
+              // extended. What inheritance must NOT do is change the lifecycle
+              // role — a child that restates `capability` differently from an
+              // ancestor is a hard error (no silent capability change).
+              const resolveDef: DefResolver = (k) =>
+                registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
+              const ownCap = (m as { capability?: unknown }).capability;
+              const ownCapResolved =
+                typeof ownCap === "string" ? aliases.resolveKind(ownCap) ?? ownCap : undefined;
+              const ancestorCap = inheritedCapability(targetDef, resolveDef);
+              if (ownCapResolved && ancestorCap && ownCapResolved !== ancestorCap) {
+                diagnostics.push({
+                  severity: DiagnosticSeverity.Error,
+                  code: "EXTENDS_CAPABILITY_MISMATCH",
+                  source: SOURCE,
+                  message:
+                    `${label}: declares 'capability: ${ownCap}' but extends '${extendsValue}' whose inherited capability is '${ancestorCap}'. ` +
+                    `Capability is inherited and immutable — omit 'capability' or restate it identically.`,
+                  data: { resource, filePath, path: "capability" },
+                });
+              }
             }
           }
         }

package/src/validate-kind-descriptions.ts

@@ -0,0 +1,65 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Warns when a library exports a kind (via `exports.kinds`) whose local
+ * `Telo.Definition` carries no `metadata.description`.
+ *
+ * The description is the primary human text the federated-discovery hub embeds
+ * for semantic search (`search_resources`), so an exported kind without one is
+ * undiscoverable by meaning. A warning (not an error) so the stdlib backfill is
+ * incremental and CI isn't blocked mid-migration.
+ *
+ * Scope: only kinds a library *exports* and *defines locally* are checked.
+ * Re-exported kinds (`exports.kinds: [Alias.Kind]`) belong to their owning
+ * module and are skipped; an exported name that isn't a local Telo.Definition
+ * (e.g. a Telo.Abstract) is skipped too. The check keys off the root library's
+ * own module doc, which is only present when that library is analyzed directly
+ * — so importing an under-described library never leaks warnings to its consumer.
+ */
+export function validateKindDescriptions(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  // Local Telo.Definition docs keyed by `<module>/<name>`.
+  const definitions = new Map<string, ResourceManifest>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    const mod = (m.metadata as { module?: string } | undefined)?.module;
+    if (name && mod) definitions.set(`${mod}/${name}`, m);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Library") continue;
+    const moduleName = m.metadata?.name as string | undefined;
+    if (!moduleName) continue;
+    const exportedKinds = (m as { exports?: { kinds?: unknown } }).exports?.kinds;
+    if (!Array.isArray(exportedKinds)) continue;
+
+    for (const entry of exportedKinds) {
+      // Re-export (`Alias.Kind`) — the owning module owns its description.
+      if (typeof entry !== "string" || entry.includes(".")) continue;
+      const def = definitions.get(`${moduleName}/${entry}`);
+      if (!def) continue; // not a local Telo.Definition (e.g. an abstract)
+      const description = (def.metadata as { description?: unknown } | undefined)?.description;
+      if (typeof description === "string" && description.trim() !== "") continue;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Warning,
+        code: "KIND_MISSING_DESCRIPTION",
+        source: SOURCE,
+        message:
+          `${moduleName}.${entry}: exported kind has no 'metadata.description'. Add a one-line ` +
+          `description — it is the primary text indexed for semantic discovery (search_resources).`,
+        data: {
+          resource: { kind: "Telo.Definition", name: entry },
+          filePath: (def.metadata as { source?: string } | undefined)?.source,
+          path: "metadata.description",
+        },
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/validate-provider-coherence.ts

@@ -1,6 +1,7 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { controllerBearingAncestor, type DefResolver } from "./extends-resolution.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -234,7 +235,16 @@ export function validateProviderCoherence(
       }
     }
 
-    if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
+    // A definition that inherits a controller by delegation (concrete `extends`,
+    // no own controller/template) satisfies the implementation requirement
+    // through its parent — `base:` supplies the parent's config.
+    const resolveDef: DefResolver = (k) =>
+      registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
+    const inheritsController =
+      typeof md.extends === "string" &&
+      controllerBearingAncestor(m as ResourceDefinition, resolveDef) !== undefined;
+
+    if (capability === "Telo.Provider" && !hasControllers && !hasProvide && !inheritsController) {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
         code: "PROVIDER_MISSING_IMPLEMENTATION",

package/src/validate-references.ts

@@ -29,20 +29,24 @@ function checkKind(
     if (!targetKind) return [];
     const targetDef = registry.resolve(targetKind);
     if (!targetDef) return [];
+    // Liskov substitutability: a value satisfies the slot when it transitively
+    // extends the target kind, or — for a CONCRETE target — IS that kind.
+    // `getByExtends` is the same transitive subtype index for abstract and
+    // concrete targets alike; an abstract is satisfied only by an implementer,
+    // never by the abstract kind itself (which is non-instantiable).
+    if (targetDef.kind !== "Telo.Abstract" && resolved === targetKind) return [];
+    const subtypes = registry.getByExtends(targetKind);
+    const subtypeKinds = new Set(subtypes.map((d) => `${d.metadata.module}.${d.metadata.name}`));
+    if (subtypeKinds.has(resolved)) return [];
     if (targetDef.kind === "Telo.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(", ");
+      if (subtypes.length === 0) return []; // partial context — no implementations loaded yet
+      const options = [...subtypeKinds].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}'`);
+      const options = subtypeKinds.size > 0 ? ` or a subtype (${[...subtypeKinds].join(", ")})` : "";
+      errors.push(`'${kind}' (resolved: '${resolved}') does not match required '${targetKind}'${options}`);
     }
   }
   return errors;