@telorun/analyzer 0.12.0 → 0.13.0

package/dist/validate-cel-context.js

@@ -219,3 +219,41 @@ function navigatePath(obj, segments) {
     }
     return cur;
 }
+/**
+ * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
+ * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
+ * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
+ */
+export function extractContextsFromSchema(schema, path = "$") {
+    const all = collectContexts(schema, path);
+    return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+function collectContexts(schema, path) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const results = [];
+    if (schema["x-telo-context"]) {
+        results.push({ scope: path, schema: schema["x-telo-context"] });
+    }
+    if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            results.push(...collectContexts(value, `${path}.${key}`));
+        }
+    }
+    if (schema.items && typeof schema.items === "object") {
+        results.push(...collectContexts(schema.items, `${path}[*]`));
+    }
+    for (const key of ["oneOf", "anyOf", "allOf"]) {
+        if (Array.isArray(schema[key])) {
+            for (const subschema of schema[key]) {
+                results.push(...collectContexts(subschema, path));
+            }
+        }
+    }
+    return results;
+}

package/dist/validate-nested-inline.d.ts

@@ -0,0 +1,30 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/** Minimal view of a definition needed to validate an inline resource's config. */
+export interface InlineDefinitionLookup {
+    (kind: string): {
+        schema?: Record<string, any>;
+    } | undefined;
+}
+/**
+ * Validates inline resources nested inside a resource body against their kind's
+ * config schema. The per-resource walk in `analyze()` validates a resource's
+ * own top-level config; inline resources at `x-telo-ref` slots reachable only
+ * through a local `$ref` (notably `Run.Sequence`'s `steps[].invoke`, hidden
+ * behind `#/$defs/step`) never reach the reference field map, so they would
+ * otherwise escape schema validation — e.g. `invoke: { kind: Console.ReadLine,
+ * prompt: "…" }`, where `prompt` belongs in the step's `inputs`, not the config.
+ *
+ * Walks the manifest data together with its definition schema, resolving local
+ * `$ref`s (so step trees of arbitrary depth are covered). At each `x-telo-ref`
+ * slot holding an inline resource, the inline's config is validated against its
+ * own kind's schema, then recursed into so inline resources nested inside
+ * inline resources are covered.
+ *
+ * Non-mutating: reads `manifest` and emits diagnostics anchored to its identity
+ * and a concrete dotted path matching the position-index key format;
+ * `rewriteSyntheticOrigins` reroutes those on inline-extracted (synthetic)
+ * manifests back to the root doc.
+ */
+export declare function validateNestedInlineResources(manifest: ResourceManifest, rootSchema: Record<string, any>, lookupDefinition: InlineDefinitionLookup): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-nested-inline.d.ts.map

package/dist/validate-nested-inline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-nested-inline.d.ts","sourceRoot":"","sources":["../src/validate-nested-inline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,gBAAgB,EAAE,sBAAsB,GACvC,kBAAkB,EAAE,CAoHtB"}

package/dist/validate-nested-inline.js

@@ -0,0 +1,129 @@
+import { collectRefs, isInlineResource } from "./reference-field-map.js";
+import { collectProperties, resolveRef, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Validates inline resources nested inside a resource body against their kind's
+ * config schema. The per-resource walk in `analyze()` validates a resource's
+ * own top-level config; inline resources at `x-telo-ref` slots reachable only
+ * through a local `$ref` (notably `Run.Sequence`'s `steps[].invoke`, hidden
+ * behind `#/$defs/step`) never reach the reference field map, so they would
+ * otherwise escape schema validation — e.g. `invoke: { kind: Console.ReadLine,
+ * prompt: "…" }`, where `prompt` belongs in the step's `inputs`, not the config.
+ *
+ * Walks the manifest data together with its definition schema, resolving local
+ * `$ref`s (so step trees of arbitrary depth are covered). At each `x-telo-ref`
+ * slot holding an inline resource, the inline's config is validated against its
+ * own kind's schema, then recursed into so inline resources nested inside
+ * inline resources are covered.
+ *
+ * Non-mutating: reads `manifest` and emits diagnostics anchored to its identity
+ * and a concrete dotted path matching the position-index key format;
+ * `rewriteSyntheticOrigins` reroutes those on inline-extracted (synthetic)
+ * manifests back to the root doc.
+ */
+export function validateNestedInlineResources(manifest, rootSchema, lookupDefinition) {
+    const diagnostics = [];
+    const resource = { kind: manifest.kind, name: manifest.metadata?.name };
+    const filePath = manifest.metadata?.source;
+    function validateInline(inline, path) {
+        const kind = inline.kind;
+        const def = lookupDefinition(kind);
+        // Unknown kind: these `$ref`-hidden slots are invisible to the field-map
+        // driven reference checks too, so nothing else would flag it — report here.
+        if (!def) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "UNDEFINED_KIND",
+                source: SOURCE,
+                message: `${resource.kind}/${resource.name}: inline ${kind} at '${path}': No Telo.Definition found for kind '${kind}'.`,
+                data: { resource, filePath, path: `${path}.kind` },
+            });
+            return;
+        }
+        // Kind exists but declares no config schema (e.g. a pure Telo.Type): no
+        // config to validate and no schema-declared slots to nest resources in.
+        if (!def.schema)
+            return;
+        const schema = def.schema;
+        // `kind` / `metadata` are implicit on every resource; inject them so a
+        // strict `additionalProperties: false` config schema doesn't reject them.
+        const effectiveSchema = schema.additionalProperties === false
+            ? {
+                ...schema,
+                properties: {
+                    kind: { type: "string" },
+                    metadata: { type: "object" },
+                    ...schema.properties,
+                },
+            }
+            : schema;
+        // Inline resources omit `metadata` — it is synthesized when the kernel
+        // registers them (and by `normalizeInlineResources` for extracted slots,
+        // which assigns a derived `metadata.name`). Config schemas conventionally
+        // declare `required: ["metadata", …]` with `metadata.name` required, so add
+        // a placeholder before validating to mirror the post-registration shape.
+        const existingMeta = inline.metadata && typeof inline.metadata === "object"
+            ? inline.metadata
+            : {};
+        const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
+        const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
+        for (const issue of validateAgainstSchema(substituted, effectiveSchema)) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "SCHEMA_VIOLATION",
+                source: SOURCE,
+                message: `${resource.kind}/${resource.name}: inline ${kind} at '${path}': ${issue.message}`,
+                data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+            });
+        }
+        // Recurse into the inline body against its own schema so deeper inline
+        // resources (e.g. an inline Run.Sequence's own steps) are validated too.
+        walk(inline, schema, schema, path);
+    }
+    function walk(data, schema, schemaRoot, path) {
+        if (!schema || typeof schema !== "object")
+            return;
+        const resolved = resolveRef(schema, schemaRoot);
+        // Reference slot: the value is either a named reference (`{kind, name}`,
+        // validated as its own manifest) or an inline resource to validate here.
+        if (collectRefs(resolved).length > 0) {
+            if (data &&
+                typeof data === "object" &&
+                !Array.isArray(data) &&
+                isInlineResource(data)) {
+                validateInline(data, path);
+            }
+            return;
+        }
+        if (Array.isArray(data)) {
+            const itemSchema = resolved.items;
+            if (!itemSchema)
+                return;
+            for (let i = 0; i < data.length; i++) {
+                walk(data[i], itemSchema, schemaRoot, `${path}[${i}]`);
+            }
+            return;
+        }
+        if (data && typeof data === "object") {
+            const props = collectProperties(resolved);
+            const additional = resolved.additionalProperties &&
+                typeof resolved.additionalProperties === "object" &&
+                !Array.isArray(resolved.additionalProperties)
+                ? resolved.additionalProperties
+                : undefined;
+            // Descend only where the schema declares structure. Freeform fields
+            // (`additionalProperties: true`, e.g. step `inputs`) carry caller data
+            // that may coincidentally look like `{kind: …}`; not descending there
+            // keeps the inline-resource detection anchored to real ref slots.
+            for (const [key, value] of Object.entries(data)) {
+                const propSchema = props[key] ?? additional;
+                if (!propSchema)
+                    continue;
+                walk(value, propSchema, schemaRoot, path ? `${path}.${key}` : key);
+            }
+        }
+    }
+    walk(manifest, rootSchema, rootSchema, "");
+    return diagnostics;
+}

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAsbtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA0YtB"}

package/dist/validate-references.js

@@ -1,5 +1,6 @@
 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";
@@ -147,142 +148,36 @@ 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;
-                }
-                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") {
+    // 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(resources, 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 target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                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 '${refName}' 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 +187,100 @@ 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;
+            // 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.
+            const 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(resources, 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 +292,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 +317,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 +328,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 +339,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 +355,7 @@ export function validateReferences(resources, context) {
                         });
                     }
                 }
-                continue;
+                return;
             }
             // Derive the anchor path in the resource config.
             let anchorPath;
@@ -413,7 +370,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 +417,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"}