@telorun/analyzer 0.12.1 → 1.0.0

package/dist/validate-unused-declarations.js

@@ -0,0 +1,91 @@
+import { extractAccessChains, INDEX_SEGMENT, walkCelExpressions } from "@telorun/templating";
+import { 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"];
+/**
+ * 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, celEnv) {
+    const moduleManifest = manifests.find((m) => m.kind === "Telo.Application");
+    if (!moduleManifest)
+        return [];
+    const declared = new Map();
+    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(NAMESPACES.map((ns) => [ns, new Set()]));
+    const suppressed = new Set();
+    for (const m of manifests) {
+        walkCelExpressions(m, "", (expr, _path, engineName) => {
+            if (engineName !== "cel")
+                return;
+            let ast;
+            try {
+                ast = celEnv.parse(expr).ast;
+            }
+            catch {
+                return; // syntax errors are reported by the CEL engine pass
+            }
+            for (const chain of extractAccessChains(ast)) {
+                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 = [];
+    const filePath = moduleManifest.metadata?.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.12.1",
+  "version": "1.0.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.3.0"
+    "@telorun/templating": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -50,7 +50,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "1.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",

package/src/analysis-registry.ts

@@ -3,6 +3,7 @@ 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 { visitManifest as runVisitManifest, type ManifestVisitor } from "./manifest-visitor.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 import type { AnalysisContext } from "./types.js";
 
@@ -62,6 +63,25 @@ export class AnalysisRegistry {
     }
   }
 
+  /**
+   * Walks a manifest's annotation sites (refs, scopes, schema-from, CEL) via
+   * the shared manifest visitor, bound to this registry's definitions and
+   * aliases. The public seam for hosts (editor overview graph, tooling) that
+   * need the same site discovery the analyzer's own passes use, without
+   * reaching into the internal DefinitionRegistry.
+   */
+  visitManifest(
+    resources: ResourceManifest[],
+    visitor: ManifestVisitor,
+    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean; discoverNestedRefs?: boolean },
+  ): void {
+    runVisitManifest(resources, this.defs, visitor, {
+      aliases: this.aliases,
+      aliasesByModule: this.aliasesByModule,
+      ...opts,
+    });
+  }
+
   /**
    * Returns the built-in kernel definitions. The underlying DefinitionRegistry already
    * seeds these on construction; this method exposes them so callers (e.g. the kernel's