@telorun/analyzer 0.12.1 → 0.14.0

package/dist/validate-references.js

@@ -1,8 +1,10 @@
 import { isRefSentinel } from "@telorun/templating";
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
+import { visitManifest } from "./manifest-visitor.js";
+import { isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
+import { isModuleKind } from "./module-kinds.js";
 const SOURCE = "telo-analyzer";
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -94,10 +96,41 @@ export function validateReferences(resources, context) {
     // source, different sourceLine) keep separate fingerprints and still
     // trip the diagnostic. `analyze()` enforces that every non-system
     // manifest carries both positional fields — no defensive guard needed.
+    // Forwarded foreign exports (an imported library's exported instances, carrying a
+    // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
+    // duplicate detection and local name resolution, and never walked as ref sources.
+    const rootModules = new Set();
+    for (const r of resources) {
+        if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
+            rootModules.add(r.metadata.name);
+        }
+    }
+    const moduleOf = (r) => r.metadata?.module;
+    const isForeign = (r) => {
+        const mod = moduleOf(r);
+        return typeof mod === "string" && !rootModules.has(mod);
+    };
+    const byModuleName = new Map();
+    for (const r of resources) {
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+            continue;
+        byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
+    }
+    /** Whether the analysis set actually carries the named module's exported instances.
+     *  False in partial single-file analysis (the import subtree wasn't loaded) — used to
+     *  skip cross-module resolution checks rather than emit false `UNRESOLVED_REFERENCE`. */
+    const moduleLoaded = (module) => {
+        const prefix = `${module}\0`;
+        for (const key of byModuleName.keys())
+            if (key.startsWith(prefix))
+                return true;
+        return false;
+    };
+    const localResources = resources.filter((r) => !isForeign(r));
     const byNameAll = new Map();
     const seen = new Set();
     for (const r of resources) {
-        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import")
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import" || isForeign(r))
             continue;
         const name = r.metadata.name;
         // `analyze()` guarantees both fields are present on non-system manifests.
@@ -139,6 +172,32 @@ export function validateReferences(resources, context) {
             });
         }
     }
+    // A resource name must contain no dot. The `!ref` resolver splits the tag's source on
+    // the first dot to separate an import alias from the resource name, so a dotted name
+    // would mis-resolve into a cross-module lookup. This is the load-bearing invariant of
+    // the reference grammar, so it is enforced here rather than left to the (unenforced)
+    // casing convention.
+    for (const [name, list] of byNameAll) {
+        if (!name.includes("."))
+            continue;
+        for (const r of list) {
+            const m = r.metadata;
+            const range = typeof m?.sourceLine === "number"
+                ? {
+                    start: { line: m.sourceLine, character: 0 },
+                    end: { line: m.sourceLine, character: Number.MAX_SAFE_INTEGER },
+                }
+                : undefined;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "INVALID_RESOURCE_NAME",
+                source: SOURCE,
+                message: `${r.kind}/${name}: resource name must not contain '.' — in a '!ref' the '.' separates an import alias from the resource name`,
+                ...(range ? { range } : {}),
+                data: { resource: { kind: r.kind, name }, filePath: m?.source, path: "metadata.name" },
+            });
+        }
+    }
     // Single-resource map for the resolution / scope lookups below — when a
     // collision exists, falling back to the first occurrence keeps the rest
     // of the pass behaving the same as before the duplicate diagnostic was
@@ -147,142 +206,58 @@ export function validateReferences(resources, context) {
     const byName = new Map();
     for (const [name, list] of byNameAll)
         byName.set(name, list[0]);
-    for (const r of resources) {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            continue;
-        // Use the expanded map so refs nested behind x-telo-schema-from get the
-        // same kind-check / unresolved-name validation as locally-declared refs.
-        // Falls back to the base map when aliasesByModule isn't supplied.
-        const fieldMap = aliasesByModule
-            ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-            : registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            continue;
-        const resourceLabel = `${r.kind}/${r.metadata.name}`;
-        const resourceData = { kind: r.kind, name: r.metadata.name };
-        const filePath = r.metadata?.source;
-        // Collect scope visibility prefixes (JSON Pointer → dot prefix) and their manifests.
-        // scope field path → flat array of ResourceManifest declared in that scope.
-        const scopeManifestsByPointer = new Map();
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isScopeEntry(entry))
-                continue;
-            const raw = resolveFieldValues(r, fieldPath)
-                .flatMap((v) => (Array.isArray(v) ? v : [v]))
-                .filter((v) => !!v && typeof v === "object");
-            const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
-            for (const pointer of pointers) {
-                scopeManifestsByPointer.set(pointer, raw);
-            }
-        }
-        const scopePrefixes = Array.from(scopeManifestsByPointer.keys()).map((p) => p.replace(/^\//, "").replace(/\//g, "."));
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isRefEntry(entry))
-                continue;
-            const inScope = scopePrefixes.some((prefix) => fieldPath === prefix ||
-                fieldPath.startsWith(prefix + ".") ||
-                fieldPath.startsWith(prefix + "["));
-            // Scope manifests visible to this ref path.
-            const visibleScopeManifests = [];
-            if (inScope) {
-                for (const [pointer, manifests] of scopeManifestsByPointer) {
-                    const prefix = pointer.replace(/^\//, "").replace(/\//g, ".");
-                    if (fieldPath === prefix ||
-                        fieldPath.startsWith(prefix + ".") ||
-                        fieldPath.startsWith(prefix + "[")) {
-                        visibleScopeManifests.push(...manifests);
-                    }
-                }
-            }
-            for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
-                if (!val)
-                    continue;
-                // `!ref <name>` sentinel — bare resource name marked at parse time as a
-                // reference. Look it up against the slot's x-telo-ref constraint exactly
-                // like the legacy bare-string path; the only difference is the value's
-                // shape (a TaggedSentinel rather than a raw string), which removed the
-                // string/inline ambiguity at the source.
-                if (isRefSentinel(val)) {
-                    const refName = val.source;
-                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                    if (!target) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "UNRESOLVED_REFERENCE",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                        continue;
-                    }
-                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
-                    if (kindErrors.length > 0) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "REFERENCE_KIND_MISMATCH",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                    }
-                    continue;
-                }
-                // Name-only reference (plain string) — look up by name to validate.
-                // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
-                // extract the resource name from the last dot segment.
-                if (typeof val === "string") {
-                    const lastDot = val.lastIndexOf(".");
-                    const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
-                    const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
-                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                    if (!target) {
-                        // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
-                        // The resource lives in the imported module's scope and can't be validated here.
-                        // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
-                        // kinds — those must be validated.
-                        if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
-                            continue;
-                        }
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "UNRESOLVED_REFERENCE",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                        continue;
-                    }
-                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
-                    if (kindErrors.length > 0) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "REFERENCE_KIND_MISMATCH",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                    }
-                    continue;
+    // Phase 3 — per-ref validation. The walker supplies each ref site already
+    // resolved against the schema-from-expanded field map, with its source
+    // enclosure (`inScope`) and the scope manifests visible to it — so this
+    // handler only validates, it does not re-walk.
+    visitManifest(localResources, registry, {
+        onRef: (e) => {
+            const r = e.source;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const { value: val, concretePath, entry, visibleScopeManifests } = e;
+            // `!ref <name>` sentinel — bare resource name marked at parse time as a
+            // reference. Look it up against the slot's x-telo-ref constraint exactly
+            // like the legacy bare-string path; the only difference is the value's
+            // shape (a TaggedSentinel rather than a raw string), which removed the
+            // string/inline ambiguity at the source.
+            if (isRefSentinel(val)) {
+                const refName = val.source;
+                const dot = refName.indexOf(".");
+                const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+                // Cross-module sentinel left unresolved by Phase 2.5 — it qualifies an import
+                // alias. If that module's exports are loaded in this analysis, the miss is real
+                // (name not in exports.resources, or a typo); if not (partial single-file
+                // analysis), skip rather than emit a false UNRESOLVED_REFERENCE.
+                if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+                    const module = aliases.moduleForAlias(aliasPrefix);
+                    if (module && !moduleLoaded(module))
+                        return;
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "UNRESOLVED_REFERENCE",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${concretePath}' → '${refName}' is not exported by module '${module ?? aliasPrefix}' (add it to exports.resources)`,
+                        data: { resource: resourceData, filePath, path: concretePath },
+                    });
+                    return;
                 }
-                if (typeof val !== "object")
-                    continue;
-                const refVal = val;
-                // Skip inline resources — Phase 2 normalization hasn't run yet.
-                if (isInlineResource(refVal))
-                    continue;
-                // 1. Structural check
-                if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
+                // Local reference (bare name or explicit `Self.`-qualified).
+                const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+                const target = byName.get(localName) ??
+                    visibleScopeManifests.find((m) => m.metadata?.name === localName);
+                if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
-                        code: "INVALID_REFERENCE",
+                        code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${localName}' not found`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
-                    continue;
+                    return;
                 }
-                // 2. Kind check
-                const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+                const kindErrors = checkKind(target.kind, entry, registry, aliases);
                 if (kindErrors.length > 0) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
@@ -292,38 +267,118 @@ export function validateReferences(resources, context) {
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
-                // 3. Resolution check — resource with this name must exist.
-                const exists = byName.has(refVal.name) ||
-                    visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
-                if (!exists) {
+                return;
+            }
+            // Name-only reference (plain string) — look up by name to validate.
+            // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
+            // extract the resource name from the last dot segment.
+            if (typeof val === "string") {
+                const lastDot = val.lastIndexOf(".");
+                const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
+                const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
+                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                if (!target) {
+                    // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
+                    // The resource lives in the imported module's scope and can't be validated here.
+                    // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
+                    // kinds — those must be validated.
+                    if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
+                        return;
+                    }
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
+                    return;
                 }
+                const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                if (kindErrors.length > 0) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "REFERENCE_KIND_MISMATCH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                        data: { resource: resourceData, filePath, path: concretePath },
+                    });
+                }
+                return;
             }
-        }
-    }
+            if (typeof val !== "object")
+                return;
+            const refVal = val;
+            // Skip inline resources — Phase 2 normalization hasn't run yet.
+            if (isInlineResource(refVal))
+                return;
+            // Polymorphic ref slots (Application `targets`) accept object forms
+            // whose references live in nested slots rather than being a `{kind,
+            // name}` ref themselves — inline `{ invoke }` and gated `{ ref }`.
+            // Those nested refs are validated via their own field-map entries, so
+            // skip the item-level structural check here.
+            if (typeof refVal.kind !== "string" && ("invoke" in refVal || "ref" in refVal))
+                return;
+            // 1. Structural check
+            if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "INVALID_REFERENCE",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+                return;
+            }
+            // 2. Kind check
+            const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+            if (kindErrors.length > 0) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "REFERENCE_KIND_MISMATCH",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+            }
+            // 3. Resolution check — resource with this name must exist.
+            let exists;
+            if (typeof refVal.alias === "string" && refVal.alias !== "Self") {
+                // Cross-module ref resolved by Phase 2.5. Validate against the forwarded
+                // exports when loaded; in partial context (module not loaded) assume resolvable.
+                const module = aliases.moduleForAlias(refVal.alias);
+                exists =
+                    !module || !moduleLoaded(module) || byModuleName.has(`${module}\0${refVal.name}`);
+            }
+            else {
+                exists =
+                    byName.has(refVal.name) ||
+                        visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            }
+            if (!exists) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "UNRESOLVED_REFERENCE",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+            }
+        },
+    }, { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: true });
     // Phase 3b — x-telo-schema-from validation.
     // For each field with a schemaFrom path expression, resolve the anchor ref to get the
     // concrete kind, navigate the JSON Pointer into that kind's definition schema, and
-    // validate the field value against the resulting sub-schema.
-    for (const r of resources) {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            continue;
-        const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            continue;
-        const resourceLabel = `${r.kind}/${r.metadata.name}`;
-        const resourceData = { kind: r.kind, name: r.metadata.name };
-        const filePath = r.metadata?.source;
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isSchemaFromEntry(entry))
-                continue;
-            const { schemaFrom } = entry;
+    // validate the field value against the resulting sub-schema. Driven off the base map
+    // (un-expanded) so each schema-from slot is seen as its own site.
+    visitManifest(localResources, registry, {
+        onSchemaFrom: (e) => {
+            const r = e.source;
+            const fieldPath = e.fieldPath;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const { schemaFrom } = e.entry;
             const isAbsolute = schemaFrom.startsWith("/");
             const expr = isAbsolute ? schemaFrom.slice(1) : schemaFrom;
             const slashIdx = expr.indexOf("/");
@@ -335,7 +390,7 @@ export function validateReferences(resources, context) {
                     message: `${resourceLabel}: x-telo-schema-from "${schemaFrom}" must contain at least one "/" to separate anchor from JSON Pointer`,
                     data: { resource: resourceData, filePath, path: fieldPath },
                 });
-                continue;
+                return;
             }
             const anchorName = expr.slice(0, slashIdx);
             const jsonPointer = "/" + expr.slice(slashIdx + 1);
@@ -360,7 +415,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → cannot resolve alias '${anchorName}'`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 const targetDef = registry.resolve(targetKind);
                 if (!targetDef?.schema) {
@@ -371,7 +426,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 const subSchema = navigateJsonPointer(targetDef.schema, jsonPointer);
                 if (subSchema === undefined) {
@@ -382,7 +437,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema path '${jsonPointer}'`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                     if (fieldValue == null)
@@ -398,7 +453,7 @@ export function validateReferences(resources, context) {
                         });
                     }
                 }
-                continue;
+                return;
             }
             // Derive the anchor path in the resource config.
             let anchorPath;
@@ -413,7 +468,7 @@ export function validateReferences(resources, context) {
             }
             const anchorValues = resolveFieldValues(r, anchorPath);
             if (anchorValues.length === 0)
-                continue; // anchor field not set — nothing to validate
+                return; // anchor field not set — nothing to validate
             const fieldEntries = resolveFieldEntries(r, fieldPath);
             for (let i = 0; i < fieldEntries.length; i++) {
                 const { value: fieldValue, path: concretePath } = fieldEntries[i];
@@ -460,7 +515,7 @@ export function validateReferences(resources, context) {
                     });
                 }
             }
-        }
-    }
+        },
+    }, { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: false });
     return diagnostics;
 }

package/dist/validate-unused-declarations.d.ts

@@ -0,0 +1,25 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * 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 declare function validateUnusedDeclarations(manifests: ResourceManifest[], celEnv: Environment): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-unused-declarations.d.ts.map

package/dist/validate-unused-declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-unused-declarations.d.ts","sourceRoot":"","sources":["../src/validate-unused-declarations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,KAAK,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AASzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,MAAM,EAAE,WAAW,GAClB,kBAAkB,EAAE,CA2DtB"}

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": "0.14.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": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -50,7 +50,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "0.13.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",