@telorun/analyzer 0.12.1 → 0.13.0

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"}

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.13.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.3.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

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 },
+  ): 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