@telorun/analyzer 0.31.0 → 0.33.0

package/dist/sources/integrity.js

@@ -0,0 +1,92 @@
+/** Inline module integrity — the `#sha256-<base64url>` fragment carried on a
+ *  remote import ref. Browser-safe: uses Web Crypto (`crypto.subtle`) and
+ *  `btoa`, both globals in Node and the browser. No Node built-ins.
+ *
+ *  The fragment is authoritative across every transport: a source's `read()`
+ *  hashes the fetched bytes and compares against it before the manifest is
+ *  parsed or cached. A mismatch is a terminal error — never a cache miss. */
+/** Only a `#<alg>-<base64url>` suffix is treated as integrity; other `#`
+ *  fragments (rare in module refs) pass through untouched. `sha256` is the
+ *  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) {
+        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. */
+export function splitIntegrity(ref) {
+    const match = ref.match(INTEGRITY_FRAGMENT);
+    if (!match)
+        return { base: ref };
+    return { base: ref.slice(0, match.index), integrity: match[1] };
+}
+/** Attach an integrity hash to a ref as a `#<alg>-...` fragment. No-op when the
+ *  hash is absent/non-string or the ref already carries a fragment (an
+ *  author-authored pin is never overwritten). Inverse of `splitIntegrity`;
+ *  used to fold the object form's `integrity:` sibling into the source string. */
+export function foldIntegrity(source, integrity) {
+    return typeof integrity === "string" && !source.includes("#")
+        ? `${source}#${integrity}`
+        : source;
+}
+function toBase64Url(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Normalize an encoded digest to unpadded base64url so a standard-base64 or
+ *  padded input still compares equal to our canonical form. */
+function normalizeDigest(value) {
+    return value.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** SHA-256 of `bytes` as unpadded base64url — the canonical inline-hash form. */
+export async function sha256Base64Url(bytes) {
+    // Copy into a plain ArrayBuffer: a Uint8Array may be backed by a
+    // SharedArrayBuffer, which `crypto.subtle.digest` does not accept.
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    const digest = await crypto.subtle.digest("SHA-256", buffer);
+    return toBase64Url(new Uint8Array(digest));
+}
+/** Hash `bytes` and compare against `integrity` (`<alg>-<digest>`). Throws a
+ *  terminal error on mismatch or an unsupported algorithm. `describe` names the
+ *  artifact in the error (e.g. the module ref) so the failure is actionable. */
+export async function verifyIntegrity(bytes, integrity, describe) {
+    const dash = integrity.indexOf("-");
+    const algorithm = dash > 0 ? integrity.slice(0, dash) : "";
+    const expected = dash > 0 ? integrity.slice(dash + 1) : "";
+    if (algorithm !== "sha256") {
+        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 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.`);
+    }
+}
+/** The single verified network read for remote manifests: fetch `fetchUrl`,
+ *  verify the raw bytes against `integrity` (when pinned), and return both the
+ *  bytes and the decoded text. The one choke point every network `ManifestSource`
+ *  routes through, so verification cannot drift between them. `describe` names
+ *  the artifact in error messages. */
+export async function verifiedFetch(fetchUrl, integrity, describe) {
+    const response = await fetch(fetchUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch manifest ${describe}: ${response.status} ${response.statusText} (${fetchUrl})`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (integrity)
+        await verifyIntegrity(bytes, integrity, describe);
+    return { bytes, text: new TextDecoder().decode(bytes) };
+}

package/dist/sources/module-ref.d.ts

@@ -0,0 +1,21 @@
+/** 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 declare function isRegistryRef(url: string): boolean;
+/** 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 declare function parseModuleRef(ref: string): ParsedModuleRef;
+//# sourceMappingURL=module-ref.d.ts.map

package/dist/sources/module-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-ref.d.ts","sourceRoot":"","sources":["../../src/sources/module-ref.ts"],"names":[],"mappings":"AAEA;;yDAEyD;AACzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASlD;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAgB3D"}

package/dist/sources/module-ref.js

@@ -0,0 +1,36 @@
+import { splitIntegrity } from "./integrity.js";
+/** 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) {
+    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) {
+    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/dist/sources/registry-source.d.ts

@@ -10,6 +10,5 @@ export declare class RegistrySource implements ManifestSource {
     resolveRelative(base: string, relative: string): string;
     private toRegistryModuleBase;
     private toRegistryUrl;
-    private parseModuleRef;
 }
 //# sourceMappingURL=registry-source.d.ts.map

package/dist/sources/registry-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-source.d.ts","sourceRoot":"","sources":["../../src/sources/registry-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7E,qBAAa,cAAe,YAAW,cAAc;IACvC,OAAO,CAAC,WAAW;gBAAX,WAAW,SAAuB;IAEtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA4BxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvD,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;CAmBvB"}
+{"version":3,"file":"registry-source.d.ts","sourceRoot":"","sources":["../../src/sources/registry-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAM7E,qBAAa,cAAe,YAAW,cAAc;IACvC,OAAO,CAAC,WAAW;gBAAX,WAAW,SAAuB;IAEtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvD,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,aAAa;CAGtB"}

package/dist/sources/registry-source.js

@@ -1,4 +1,6 @@
 import { DEFAULT_MANIFEST_FILENAME } from "../types.js";
+import { splitIntegrity, verifiedFetch } from "./integrity.js";
+import { isRegistryRef, parseModuleRef } from "./module-ref.js";
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
 export class RegistrySource {
     registryUrl;
@@ -6,20 +8,12 @@ export class RegistrySource {
         this.registryUrl = registryUrl;
     }
     supports(url) {
-        return (!url.startsWith("http://") &&
-            !url.startsWith("https://") &&
-            !url.startsWith("/") &&
-            !url.startsWith(".") &&
-            url.includes("@") &&
-            url.includes("/"));
+        return isRegistryRef(url);
     }
     async read(moduleRef) {
-        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
@@ -30,7 +24,7 @@ export class RegistrySource {
             const detail = codeMatch && messageMatch
                 ? `${codeMatch[1]}: ${messageMatch[1]}`
                 : text.slice(0, 200);
-            throw new Error(`Registry returned a non-manifest response for ${moduleRef} ` +
+            throw new Error(`Registry returned a non-manifest response for ${base} ` +
                 `(URL: ${fetchUrl}): ${detail}`);
         }
         return { text, source: fetchUrl };
@@ -41,27 +35,11 @@ export class RegistrySource {
         return new URL(relative, baseWithSlash).href;
     }
     toRegistryModuleBase(moduleRef) {
-        const parsed = this.parseModuleRef(moduleRef);
+        const parsed = parseModuleRef(moduleRef);
         const normalizedBase = this.registryUrl.replace(/\/+$/, "");
         return `${normalizedBase}/${parsed.modulePath}/${parsed.version}`;
     }
     toRegistryUrl(moduleRef) {
         return `${this.toRegistryModuleBase(moduleRef)}/${DEFAULT_MANIFEST_FILENAME}`;
     }
-    parseModuleRef(moduleRef) {
-        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/dist/validate-kind-descriptions.d.ts

@@ -0,0 +1,20 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * 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 declare function validateKindDescriptions(manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-kind-descriptions.d.ts.map

package/dist/validate-kind-descriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-kind-descriptions.d.ts","sourceRoot":"","sources":["../src/validate-kind-descriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CA2C5F"}

package/dist/validate-kind-descriptions.js

@@ -0,0 +1,65 @@
+import { DiagnosticSeverity } 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) {
+    const diagnostics = [];
+    // Local Telo.Definition docs keyed by `<module>/<name>`.
+    const definitions = new Map();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const name = m.metadata?.name;
+        const mod = m.metadata?.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;
+        if (!moduleName)
+            continue;
+        const exportedKinds = m.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?.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?.source,
+                    path: "metadata.description",
+                },
+            });
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,13 +42,13 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.10.0"
+    "@telorun/templating": "0.10.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.38.0"
+    "@telorun/sdk": "0.41.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"