@telorun/analyzer 0.31.0 → 0.33.0

package/src/sources/module-ref.ts

@@ -0,0 +1,49 @@
+import { splitIntegrity } from "./integrity.js";
+
+/** A parsed registry module reference. `modulePath` is `namespace/name`,
+ *  `version` has any leading `v` stripped, and `integrity` carries the inline
+ *  `sha256-<base64url>` hash when the ref was pinned. */
+export interface ParsedModuleRef {
+  modulePath: string;
+  version: string;
+  integrity?: string;
+}
+
+/** True when `url` has the bare registry-ref shape `namespace/name@version`
+ *  (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.includes("://") &&
+    !base.startsWith("/") &&
+    !base.startsWith(".") &&
+    base.includes("@") &&
+    base.includes("/")
+  );
+}
+
+/** Canonical parser for `namespace/name@version[#sha256-...]` refs. The single
+ *  source of truth shared by the registry source, the kernel manifest cache,
+ *  and the CLI (install / upgrade / bundle). Throws on a malformed ref. */
+export function parseModuleRef(ref: string): ParsedModuleRef {
+  const { base, integrity } = splitIntegrity(ref);
+  const atIdx = base.lastIndexOf("@");
+  if (atIdx <= 0 || atIdx === base.length - 1) {
+    throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
+  }
+  const modulePath = base.slice(0, atIdx);
+  if (!modulePath.includes("/")) {
+    throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
+  }
+  const rawVersion = base.slice(atIdx + 1);
+  const version = rawVersion.startsWith("v") ? rawVersion.slice(1) : rawVersion;
+  if (!version) {
+    throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
+  }
+  return { modulePath, version, integrity };
+}

package/src/sources/registry-source.ts

@@ -1,4 +1,6 @@
 import { DEFAULT_MANIFEST_FILENAME, type ManifestSource } from "../types.js";
+import { splitIntegrity, verifiedFetch } from "./integrity.js";
+import { isRegistryRef, parseModuleRef } from "./module-ref.js";
 
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
 
@@ -6,25 +8,13 @@ export class RegistrySource implements ManifestSource {
   constructor(private registryUrl = DEFAULT_REGISTRY_URL) {}
 
   supports(url: string): boolean {
-    return (
-      !url.startsWith("http://") &&
-      !url.startsWith("https://") &&
-      !url.startsWith("/") &&
-      !url.startsWith(".") &&
-      url.includes("@") &&
-      url.includes("/")
-    );
+    return isRegistryRef(url);
   }
 
   async read(moduleRef: string): Promise<{ text: string; source: string }> {
-    const fetchUrl = this.toRegistryUrl(moduleRef);
-    const response = await fetch(fetchUrl);
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch manifest ${moduleRef}: ${response.status} ${response.statusText}`,
-      );
-    }
-    const text = await response.text();
+    const { base, integrity } = splitIntegrity(moduleRef);
+    const fetchUrl = this.toRegistryUrl(base);
+    const { text } = await verifiedFetch(fetchUrl, integrity, base);
     // Some object-storage backends (e.g. Cloudflare R2 / S3) surface auth or
     // permission failures by returning a 200 status with an XML error body.
     // Catch this here so the loader produces a precise error rather than
@@ -37,7 +27,7 @@ export class RegistrySource implements ManifestSource {
           ? `${codeMatch[1]}: ${messageMatch[1]}`
           : text.slice(0, 200);
       throw new Error(
-        `Registry returned a non-manifest response for ${moduleRef} ` +
+        `Registry returned a non-manifest response for ${base} ` +
           `(URL: ${fetchUrl}): ${detail}`,
       );
     }
@@ -51,7 +41,7 @@ export class RegistrySource implements ManifestSource {
   }
 
   private toRegistryModuleBase(moduleRef: string): string {
-    const parsed = this.parseModuleRef(moduleRef);
+    const parsed = parseModuleRef(moduleRef);
     const normalizedBase = this.registryUrl.replace(/\/+$/, "");
     return `${normalizedBase}/${parsed.modulePath}/${parsed.version}`;
   }
@@ -59,24 +49,4 @@ export class RegistrySource implements ManifestSource {
   private toRegistryUrl(moduleRef: string): string {
     return `${this.toRegistryModuleBase(moduleRef)}/${DEFAULT_MANIFEST_FILENAME}`;
   }
-
-  private parseModuleRef(moduleRef: string): { modulePath: string; version: string } {
-    const atIdx = moduleRef.lastIndexOf("@");
-    if (atIdx <= 0 || atIdx === moduleRef.length - 1) {
-      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
-    }
-
-    const modulePath = moduleRef.slice(0, atIdx);
-    if (!modulePath.includes("/")) {
-      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
-    }
-
-    const rawVersion = moduleRef.slice(atIdx + 1);
-    const version = rawVersion.startsWith("v") ? rawVersion.substring(1) : rawVersion;
-    if (!version) {
-      throw new Error(`Invalid module reference '${moduleRef}', expected namespace/name@version`);
-    }
-
-    return { modulePath, version };
-  }
 }

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;
+}