@telorun/analyzer 0.12.0 → 0.13.0

package/src/validate-unused-declarations.ts

@@ -0,0 +1,95 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { extractAccessChains, INDEX_SEGMENT, walkCelExpressions } from "@telorun/templating";
+import { type AnalysisDiagnostic, DiagnosticSeverity } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** Module-doc namespaces whose entries are consumed via `<ns>.<name>` CEL
+ *  access. One table drives the whole check — adding a namespace is an entry,
+ *  not a branch. */
+const NAMESPACES = ["variables", "secrets", "ports"] as const;
+
+/**
+ * Warn about declared `variables` / `secrets` / `ports` entries that no CEL
+ * expression references. A declared-but-unconsumed entry is dead weight at
+ * best and misleading at worst (an unbound `ports` entry makes a runner
+ * advertise a port the app never listens on).
+ *
+ * Generic across all three namespaces. References are collected from every CEL
+ * expression (both `${{ … }}` and `!cel`, via `walkCelExpressions`) by
+ * extracting member-access chains: a `<ns>.<name>` chain marks `<name>` used.
+ * Dynamic access (`<ns>[expr]`, or the namespace passed whole, e.g.
+ * `keys(variables)`) yields a chain that stops at the namespace root — that
+ * can't be attributed to a name, so the whole namespace is conservatively
+ * suppressed to avoid false positives.
+ *
+ * Application-only: an Application's `variables` / `secrets` / `ports` flow
+ * exclusively through CEL (into resource fields, or into `Telo.Import` inputs),
+ * so unreferenced means dead. A `Telo.Library`'s `variables` / `secrets` are a
+ * public input contract consumed by its controllers — invisible to CEL
+ * analysis — so they are deliberately not flagged.
+ */
+export function validateUnusedDeclarations(
+  manifests: ResourceManifest[],
+  celEnv: Environment,
+): AnalysisDiagnostic[] {
+  const moduleManifest = manifests.find((m) => m.kind === "Telo.Application") as
+    | Record<string, any>
+    | undefined;
+  if (!moduleManifest) return [];
+
+  const declared = new Map<string, string[]>();
+  for (const ns of NAMESPACES) {
+    const block = moduleManifest[ns];
+    if (block && typeof block === "object" && !Array.isArray(block)) {
+      const names = Object.keys(block);
+      if (names.length > 0) declared.set(ns, names);
+    }
+  }
+  if (declared.size === 0) return [];
+
+  const used = new Map<string, Set<string>>(NAMESPACES.map((ns) => [ns, new Set<string>()]));
+  const suppressed = new Set<string>();
+
+  for (const m of manifests) {
+    walkCelExpressions(m, "", (expr, _path, engineName) => {
+      if (engineName !== "cel") return;
+      let ast: unknown;
+      try {
+        ast = celEnv.parse(expr).ast;
+      } catch {
+        return; // syntax errors are reported by the CEL engine pass
+      }
+      for (const chain of extractAccessChains(ast as Parameters<typeof extractAccessChains>[0])) {
+        const ns = chain[0];
+        if (!used.has(ns)) continue;
+        const member = chain[1];
+        // No static member after the namespace root — either the namespace is
+        // used whole (`keys(ports)` → ["ports"]) or accessed dynamically
+        // (`ports[x]` → ["ports", "[*]"]). Neither can be attributed to a
+        // declared name, so suppress the namespace rather than false-positive.
+        if (member === undefined || member === INDEX_SEGMENT) suppressed.add(ns);
+        else used.get(ns)!.add(member);
+      }
+    });
+  }
+
+  const diagnostics: AnalysisDiagnostic[] = [];
+  const filePath = (moduleManifest.metadata as { source?: string } | undefined)?.source;
+  for (const [ns, names] of declared) {
+    if (suppressed.has(ns)) continue;
+    const seen = used.get(ns)!;
+    for (const name of names) {
+      if (seen.has(name)) continue;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Warning,
+        code: "UNUSED_DECLARATION",
+        source: SOURCE,
+        message: `${ns}.${name} is declared but never referenced in any CEL expression.`,
+        data: { filePath, path: `${ns}.${name}` },
+      });
+    }
+  }
+  return diagnostics;
+}

package/dist/adapters/http-adapter.d.ts

@@ -1,10 +0,0 @@
-import { type ManifestAdapter } from "../types.js";
-export declare class HttpAdapter implements ManifestAdapter {
-    supports(url: string): boolean;
-    read(url: string): Promise<{
-        text: string;
-        source: string;
-    }>;
-    resolveRelative(base: string, relative: string): string;
-}
-//# sourceMappingURL=http-adapter.d.ts.map

package/dist/adapters/http-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"http-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/http-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9E,qBAAa,WAAY,YAAW,eAAe;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAWlE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAIxD"}

package/dist/adapters/http-adapter.js

@@ -1,18 +0,0 @@
-import { DEFAULT_MANIFEST_FILENAME } from "../types.js";
-export class HttpAdapter {
-    supports(url) {
-        return url.startsWith("http://") || url.startsWith("https://");
-    }
-    async read(url) {
-        const fetchUrl = url.includes(".yaml") ? url : `${url}/${DEFAULT_MANIFEST_FILENAME}`;
-        const response = await fetch(fetchUrl);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch manifest from ${fetchUrl}: ${response.status} ${response.statusText}`);
-        }
-        return { text: await response.text(), source: fetchUrl };
-    }
-    resolveRelative(base, relative) {
-        const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);
-        return new URL(relative, baseDir).href;
-    }
-}

package/dist/adapters/node-adapter.d.ts

@@ -1,17 +0,0 @@
-import { type ManifestAdapter } from "../types.js";
-/** Node.js fs-based ManifestAdapter for local files. Not browser-compatible. */
-export declare class NodeAdapter implements ManifestAdapter {
-    private readonly cwd;
-    constructor(cwd?: string);
-    supports(url: string): boolean;
-    read(url: string): Promise<{
-        text: string;
-        source: string;
-    }>;
-    resolveRelative(base: string, relative: string): string;
-    expandGlob(base: string, patterns: string[]): Promise<string[]>;
-    resolveOwnerOf(fileUrl: string): Promise<string | null>;
-}
-/** @deprecated Use `new NodeAdapter(cwd)` instead */
-export declare function createNodeAdapter(cwd?: string): ManifestAdapter;
-//# sourceMappingURL=node-adapter.d.ts.map

package/dist/adapters/node-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"node-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/node-adapter.ts"],"names":[],"mappings":"AAIA,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9E,gFAAgF;AAChF,qBAAa,WAAY,YAAW,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,MAAsB;IAExD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAUxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IASlE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAKjD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAc/D,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAoB9D;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,eAAe,CAE9E"}

package/dist/adapters/node-adapter.js

@@ -1,71 +0,0 @@
-import * as fs from "fs/promises";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import { minimatch } from "minimatch";
-import { DEFAULT_MANIFEST_FILENAME } from "../types.js";
-function toFilePath(url) {
-    return url.startsWith("file://") ? fileURLToPath(url) : url;
-}
-/** Node.js fs-based ManifestAdapter for local files. Not browser-compatible. */
-export class NodeAdapter {
-    cwd;
-    constructor(cwd = process.cwd()) {
-        this.cwd = cwd;
-    }
-    supports(url) {
-        return (url.startsWith("file://") ||
-            url.startsWith("/") ||
-            url.startsWith("./") ||
-            url.startsWith("../") ||
-            (!url.includes("://") && !url.includes("@")));
-    }
-    async read(url) {
-        const filePath = toFilePath(url);
-        const stat = await fs.stat(filePath).catch(() => null);
-        const resolvedPath = stat?.isDirectory() ? path.join(filePath, DEFAULT_MANIFEST_FILENAME) : filePath;
-        const text = await fs.readFile(resolvedPath, "utf8");
-        return { text, source: resolvedPath };
-    }
-    resolveRelative(base, relative) {
-        const baseDir = path.dirname(path.resolve(this.cwd, toFilePath(base)));
-        return path.resolve(baseDir, relative);
-    }
-    async expandGlob(base, patterns) {
-        const baseDir = path.dirname(path.resolve(this.cwd, toFilePath(base)));
-        const entries = await fs.readdir(baseDir, { recursive: true, encoding: "utf8" });
-        const normalizedPatterns = patterns.map((p) => p.replace(/\\/g, "/").replace(/^\.\//, ""));
-        const matched = [];
-        for (const entry of entries) {
-            const normalized = entry.replace(/\\/g, "/");
-            if (normalizedPatterns.some((p) => minimatch(normalized, p))) {
-                matched.push(path.resolve(baseDir, entry));
-            }
-        }
-        return matched.sort();
-    }
-    async resolveOwnerOf(fileUrl) {
-        const resolved = path.resolve(this.cwd, toFilePath(fileUrl));
-        let dir = path.dirname(resolved);
-        while (true) {
-            const candidate = path.join(dir, DEFAULT_MANIFEST_FILENAME);
-            if (candidate !== resolved) {
-                try {
-                    await fs.access(candidate);
-                    return candidate;
-                }
-                catch {
-                    // telo.yaml not found at this level
-                }
-            }
-            const parent = path.dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-        return null;
-    }
-}
-/** @deprecated Use `new NodeAdapter(cwd)` instead */
-export function createNodeAdapter(cwd = process.cwd()) {
-    return new NodeAdapter(cwd);
-}

package/dist/adapters/registry-adapter.d.ts

@@ -1,15 +0,0 @@
-import { type ManifestAdapter } from "../types.js";
-export declare class RegistryAdapter implements ManifestAdapter {
-    private registryUrl;
-    constructor(registryUrl?: string);
-    supports(url: string): boolean;
-    read(moduleRef: string): Promise<{
-        text: string;
-        source: string;
-    }>;
-    resolveRelative(base: string, relative: string): string;
-    private toRegistryModuleBase;
-    private toRegistryUrl;
-    private parseModuleRef;
-}
-//# sourceMappingURL=registry-adapter.d.ts.map

package/dist/adapters/registry-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"registry-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/registry-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9E,qBAAa,eAAgB,YAAW,eAAe;IACzC,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;IAWxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvD,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;CAmBvB"}

package/dist/adapters/registry-adapter.js

@@ -1,53 +0,0 @@
-import { DEFAULT_MANIFEST_FILENAME } from "../types.js";
-const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
-export class RegistryAdapter {
-    registryUrl;
-    constructor(registryUrl = DEFAULT_REGISTRY_URL) {
-        this.registryUrl = registryUrl;
-    }
-    supports(url) {
-        return (!url.startsWith("http://") &&
-            !url.startsWith("https://") &&
-            !url.startsWith("/") &&
-            !url.startsWith(".") &&
-            url.includes("@") &&
-            url.includes("/"));
-    }
-    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}`);
-        }
-        return { text: await response.text(), source: fetchUrl };
-    }
-    resolveRelative(base, relative) {
-        const baseUrl = this.supports(base) ? this.toRegistryModuleBase(base) : base;
-        const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
-        return new URL(relative, baseWithSlash).href;
-    }
-    toRegistryModuleBase(moduleRef) {
-        const parsed = this.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 };
-    }
-}