@nexus-ioc/core 0.6.2 → 0.7.0

package/dist/esm/core/graph/module-graph.js

@@ -1,27 +1,60 @@
 import { EdgeTypeEnum, MODULE_TOKEN_WATERMARK, MODULE_WATERMARK, NodeTypeEnum, PROPERTY_DEPS_METADATA, PROPERTY_OPTIONAL_DEPS_METADATA, SELF_DECLARED_DEPS_METADATA, SELF_DECLARED_OPTIONAL_DEPS_METADATA, } from "../../interfaces/index.js";
-import { getDependencyToken, getProviderToken, isModule, } from "../../utils/helpers.js";
+import { isForwardRef } from "../../utils/forward-ref.js";
+import { getDependencyToken, getModuleLabel, getProviderToken, isModule, } from "../../utils/helpers.js";
+import { isLazyModule } from "../../utils/lazy-module.js";
+import { AnalyzeLazyModule } from "./analyze-lazy-module.js";
 import { AnalyzeModule } from "./analyze-module.js";
 import { isAnalyzeClassProvider, isAnalyzeFactoryProvider, isAnalyzeFunctionProvider, } from "./helpers/index.js";
 import { ProviderFactory } from "./providers/provider-factory.js";
 /**
- * Helper function to safely convert InjectionToken to string for error messages
+ * Helper function to safely convert ProviderToken to string for error messages
  */
 function tokenToString(token) {
     return typeof token === "function" ? token.name : String(token);
 }
-/**
- * Type guard to check if a node is an AnalyzeProvider
- */
-function isProviderNode(entry) {
-    return entry[1].type === NodeTypeEnum.PROVIDER;
-}
 export class ModuleGraph {
-    constructor(_root) {
+    constructor(_root, _internalRoots = [], options = {}) {
         this._root = _root;
+        this._internalRoots = _internalRoots;
+        this.options = options;
         this._nodes = new Map();
         this._edges = new Map();
         this._globalModules = new Map();
+        /** Module token -> its own declared provider tokens. */
+        this._moduleProviders = new Map();
+        /**
+         * Module token -> the other module tokens that need it alive: every
+         * module that imports it, plus every module owning a provider that
+         * depends (via a resolved `DEPENDENCY` edge, including one resolved
+         * through a `@Global()` module) on one of its providers.
+         */
+        this._moduleReferrers = new Map();
+        /**
+         * Late-bound edge index: target token -> source provider token -> whether
+         * the edge is bound. A `lateBound` edge is an `@Optional()` static edge
+         * whose target was not visible from the source's module when it was
+         * compiled (it may not have existed yet). The resolver injects its target
+         * only while the target exists and is visible. "Bound" means that held
+         * when a segment added the target (or a global module exposing it), so
+         * the source's module was recorded as a referrer of the target's module;
+         * only a bound edge counts in `moduleDependencies`, which keeps the
+         * referrer purge symmetric with the recording.
+         */
+        this._lateBound = new Map();
+        /**
+         * Child declaration index: the child's module class (or the `LazyModule.id`
+         * symbol of a lazy ref) -> the token of the one module declaring it.
+         */
+        this._childDeclarations = new Map();
         this._errors = [];
+        /**
+         * While a segment compiles, its errors are collected here instead of in
+         * `_errors`, so they are never mixed with (or mistaken for) errors of the
+         * eager graph or of another segment.
+         */
+        this._errorSink = null;
+        /** See `version`. */
+        this._version = 0;
     }
     get nodes() {
         return this._nodes;
@@ -32,11 +65,389 @@ export class ModuleGraph {
     get errors() {
         return this._errors;
     }
+    get rootToken() {
+        return this._root.token;
+    }
+    get internalRootTokens() {
+        return this._internalRoots.map((root) => root.token);
+    }
+    /**
+     * Bumped whenever `compile`, `compileSegment` or `unloadSegment` may have
+     * changed which providers exist or which modules see them. A cache of
+     * `isProviderVisible` results is valid while this number is unchanged.
+     */
+    get version() {
+        return this._version;
+    }
+    /** Records a graph error in the active sink, or in the shared list. */
+    pushError(error) {
+        (this._errorSink ?? this._errors).push(error);
+    }
+    /**
+     * Compiles the eager graph. Internal roots are added before the user root so
+     * `_globalModules` already contains the internal modules when user providers
+     * are checked by `isProviderExported`.
+     */
     async compile() {
-        await this.addModules();
-        await this.addDependencies();
-        await this.detectCircularDependencies();
-        await this.detectCircularImports();
+        const moduleTokens = [];
+        const providerTokens = [];
+        for (const root of [...this._internalRoots, this._root]) {
+            const added = await this.addModules(root, false);
+            moduleTokens.push(...added.moduleTokens);
+            providerTokens.push(...added.providerTokens);
+        }
+        await this.addDependencies(providerTokens);
+        await this.detectCircularDependencies(providerTokens);
+        await this.detectCircularImports(moduleTokens);
+        this._version++;
+    }
+    /**
+     * Compiles the part of the graph reachable from `root` that is not already
+     * registered, attributing it to the `lazyModule` placeholder node.
+     *
+     * The pass is atomic: if it produces any error the segment is rolled back
+     * (every node, edge, global registration and LAZY placeholder it created is
+     * removed) and the placeholder stays unloaded. On success the placeholder is
+     * marked loaded. A placeholder that already existed before the segment
+     * started is never removed.
+     *
+     * The segment's errors are collected in a segment-local sink and never
+     * reach `this.errors`, so they cannot be attributed to the eager graph or
+     * to another segment. The caller (`Container.load`) runs one segment at a
+     * time, which is what makes the sink and the graph mutations safe under
+     * concurrent loads of different refs.
+     */
+    async compileSegment(root, lazyModule) {
+        const createdPlaceholder = !this._nodes.has(lazyModule.id);
+        if (createdPlaceholder) {
+            this.addNode(lazyModule.id, new AnalyzeLazyModule(lazyModule));
+        }
+        const errors = [];
+        const previousSink = this._errorSink;
+        this._errorSink = errors;
+        try {
+            const added = await this.addModules(root, true);
+            await this.addDependencies(added.providerTokens);
+            await this.detectCircularDependencies(added.providerTokens);
+            await this.detectCircularImports(added.moduleTokens);
+            if (errors.length > 0) {
+                this.removeTokens([
+                    ...added.moduleTokens,
+                    ...added.providerTokens,
+                    ...added.lazyTokens,
+                    ...(createdPlaceholder ? [lazyModule.id] : []),
+                ]);
+            }
+            else {
+                this.bindLateEdges(added.moduleTokens, added.providerTokens);
+                this._nodes.get(lazyModule.id).markLoaded(root.token);
+            }
+            return {
+                lazyModule,
+                moduleContainer: root,
+                moduleTokens: added.moduleTokens,
+                providerTokens: added.providerTokens,
+                errors,
+            };
+        }
+        finally {
+            this._errorSink = previousSink;
+            // Even a rolled-back segment was briefly part of the graph.
+            this._version++;
+        }
+    }
+    /**
+     * Binds the late-bound edges (see `_lateBound`) whose target this
+     * segment made visible to the edge's source, recording the referrer the
+     * resolver's injection now implies. The same visibility check as the
+     * resolver's, so bookkeeping and injection always agree.
+     *
+     * Only two things can make a late-bound target visible to an existing
+     * source: the target's node being added (looked up per added provider)
+     * or a new `@Global()` module exposing it (compiled modules' imports
+     * never change). Only a segment adding a global module rechecks every
+     * indexed target; the index holds only late-bound edges, so it is small.
+     *
+     * Once bound, an edge keeps the target's module pinned for the consumer
+     * module's lifetime, even after the global module that exposed it
+     * unloads. This is deliberately safe: instances created meanwhile may
+     * still hold the target.
+     */
+    bindLateEdges(addedModuleTokens, addedProviderTokens) {
+        if (this._lateBound.size === 0) {
+            return;
+        }
+        const addsGlobal = addedModuleTokens.some((token) => this._globalModules.has(token));
+        const targets = addsGlobal
+            ? [...this._lateBound.keys()]
+            : addedProviderTokens.filter((token) => this._lateBound.has(token));
+        for (const target of targets) {
+            if (this._nodes.get(target)?.type !== NodeTypeEnum.PROVIDER) {
+                continue;
+            }
+            const sources = this._lateBound.get(target);
+            for (const [source, bound] of sources) {
+                const consumer = this._nodes.get(source);
+                if (bound || consumer?.type !== NodeTypeEnum.PROVIDER) {
+                    continue;
+                }
+                if (this.isProviderVisible(consumer.moduleContainer, target)) {
+                    sources.set(source, true);
+                    this.recordCrossModuleReferrer(source, target, true);
+                }
+            }
+        }
+    }
+    /**
+     * Drops removed sources from the late-bound index and unbinds edges
+     * whose target was removed (a later load of the target binds them
+     * again). Runs after `purgeModuleIndexes`, which reads the bound state.
+     */
+    purgeLateBound(tokens) {
+        if (this._lateBound.size === 0) {
+            return;
+        }
+        const removed = new Set(tokens);
+        for (const [target, sources] of this._lateBound) {
+            for (const [source, bound] of sources) {
+                if (removed.has(source)) {
+                    sources.delete(source);
+                }
+                else if (bound && removed.has(target)) {
+                    sources.set(source, false);
+                }
+            }
+            if (sources.size === 0) {
+                this._lateBound.delete(target);
+            }
+        }
+    }
+    /**
+     * Rolls back a segment that failed validation: removes every node, edge
+     * and global registration it created (module, provider and LAZY
+     * placeholder tokens are all passed in together). Also purges
+     * `_moduleProviders`/`_moduleReferrers` index entries for `tokens` via
+     * `purgeModuleIndexes` — without this, a referrer entry recorded by
+     * `addModuleImports` before the rollback (pointing at a module token
+     * that no longer exists) would survive and could later be mistaken by
+     * `rescueCandidates` for a live outside referrer of a module reused by a
+     * different, successful segment.
+     */
+    removeTokens(tokens) {
+        this.purgeModuleIndexes(tokens);
+        this.purgeLateBound(tokens);
+        for (const token of tokens) {
+            this._nodes.delete(token);
+            this._edges.delete(token);
+            this._globalModules.delete(token);
+        }
+    }
+    /**
+     * Unloads a loaded lazy segment. Scoped to the segment's own subgraph,
+     * not the whole live graph: collects everything reachable from the
+     * segment's root (pruned at any module in `protectedRoots` — the eager
+     * root, internal roots, and every *other* currently loaded segment's
+     * root), then rescues back anything a survivor still needs. Returns the
+     * modules and providers that were actually destroyed; a no-op (empty
+     * result) if the ref is not currently loaded.
+     */
+    unloadSegment(lazyModule, protectedRoots) {
+        const placeholder = this._nodes.get(lazyModule.id);
+        if (!placeholder ||
+            !placeholder.loaded ||
+            placeholder.moduleToken === null) {
+            return { destroyedModules: [], destroyedProviders: [] };
+        }
+        const candidates = this.collectCandidates(placeholder.moduleToken, protectedRoots);
+        const alive = this.rescueCandidates(candidates);
+        const destroyedModules = [];
+        const destroyedProviders = [];
+        for (const moduleToken of candidates) {
+            if (alive.has(moduleToken)) {
+                continue;
+            }
+            destroyedModules.push(moduleToken);
+            for (const providerToken of this._moduleProviders.get(moduleToken) ??
+                []) {
+                destroyedProviders.push(providerToken);
+            }
+        }
+        this.removeModuleTokens(destroyedModules, destroyedProviders);
+        placeholder.markUnloaded();
+        this._version++;
+        return { destroyedModules, destroyedProviders };
+    }
+    /** A module's own `IMPORT` targets, plus the declaring modules of
+     * whatever its own providers depend on in another module. Shared by
+     * candidate collection, rescue propagation and teardown cleanup. */
+    moduleDependencies(moduleToken) {
+        const dependencies = [];
+        for (const edge of this.getEdge(moduleToken)) {
+            if (edge.type === EdgeTypeEnum.IMPORT) {
+                dependencies.push(edge.source);
+            }
+        }
+        for (const providerToken of this._moduleProviders.get(moduleToken) ?? []) {
+            for (const edge of this.getEdge(providerToken)) {
+                if (edge.type !== EdgeTypeEnum.DEPENDENCY ||
+                    edge.metadata.unreached ||
+                    edge.metadata.external ||
+                    (edge.metadata.lateBound &&
+                        this._lateBound.get(edge.target)?.get(providerToken) !== true)) {
+                    continue;
+                }
+                const dependency = this._nodes.get(edge.target);
+                if (dependency?.type === NodeTypeEnum.PROVIDER) {
+                    dependencies.push(dependency.moduleContainer.token);
+                }
+            }
+        }
+        return dependencies;
+    }
+    collectCandidates(rootToken, protectedRoots) {
+        const candidates = new Set();
+        const queue = [rootToken];
+        while (queue.length) {
+            const moduleToken = queue.shift();
+            if (protectedRoots.has(moduleToken) || candidates.has(moduleToken)) {
+                continue;
+            }
+            candidates.add(moduleToken);
+            queue.push(...this.moduleDependencies(moduleToken));
+        }
+        return candidates;
+    }
+    /**
+     * A candidate survives if something outside the candidate set still
+     * needs it (a "seed"), or if it is only reachable through a candidate
+     * that survives. A plain per-node check for the first case alone is not
+     * enough — see the "rescues a module only reachable through a surviving
+     * sibling candidate" test.
+     */
+    rescueCandidates(candidates) {
+        const alive = new Set();
+        const queue = [];
+        for (const moduleToken of candidates) {
+            const referrers = this._moduleReferrers.get(moduleToken);
+            const hasOutsideReferrer = referrers &&
+                [...referrers].some((referrer) => !candidates.has(referrer));
+            if (hasOutsideReferrer) {
+                queue.push(moduleToken);
+            }
+        }
+        while (queue.length) {
+            const moduleToken = queue.shift();
+            if (alive.has(moduleToken)) {
+                continue;
+            }
+            alive.add(moduleToken);
+            queue.push(...this.moduleDependencies(moduleToken).filter((token) => candidates.has(token)));
+        }
+        return alive;
+    }
+    removeModuleTokens(moduleTokens, providerTokens) {
+        // Drop stale referrer entries, and the modules' own index entries,
+        // before deleting the edges they were derived from, so a module that
+        // stays alive never keeps a phantom referrer from a module that no
+        // longer exists.
+        //
+        // Note: this only removes edges from the maps keyed by the destroyed
+        // tokens themselves, not from every place a destroyed token might
+        // still appear as an edge *target* elsewhere — e.g. an
+        // `unreached: true` DEPENDENCY edge left on a surviving provider, or
+        // a LAZY placeholder edge whose declaring module was destroyed.
+        // That's safe for resolution (`Resolver.resolveProvider` already
+        // returns `undefined` for a missing node), but graph-introspection
+        // consumers (like `graph-analyzer`) can still see these as orphaned
+        // edge references.
+        this.purgeModuleIndexes(moduleTokens);
+        this.purgeLateBound(providerTokens);
+        // Defensive: a runtime (inject()) edge also records its source's module
+        // as a referrer of the target's module, so a provider that survives
+        // this unload should never hold one to a destroyed provider. Should it
+        // happen anyway, drop the edge; it is re-discovered on the next creation.
+        const destroyedProviders = new Set(providerTokens);
+        for (const [source, edges] of this._edges) {
+            if (destroyedProviders.has(source)) {
+                continue;
+            }
+            if (edges.some((e) => e.metadata.inject === "runtime" && destroyedProviders.has(e.target))) {
+                this._edges.set(source, edges.filter((e) => !(e.metadata.inject === "runtime" &&
+                    destroyedProviders.has(e.target))));
+            }
+        }
+        for (const providerToken of providerTokens) {
+            this._nodes.delete(providerToken);
+            this._edges.delete(providerToken);
+        }
+        for (const moduleToken of moduleTokens) {
+            this._nodes.delete(moduleToken);
+            this._edges.delete(moduleToken);
+            this._globalModules.delete(moduleToken);
+        }
+    }
+    /**
+     * Purges `_moduleProviders`/`_moduleReferrers` index entries for
+     * `tokens`, and removes each of them from any surviving module's
+     * referrer set. Shared by `removeModuleTokens` (destroying a live
+     * segment) and `removeTokens` (rolling back a failed one).
+     *
+     * `tokens` may freely mix module tokens with provider or LAZY
+     * placeholder tokens: both indexes are keyed by module tokens only, so a
+     * lookup or delete with a non-module key is a harmless no-op.
+     *
+     * Must run before the tokens' own `_edges` entries (and, for a removed
+     * module, its `_moduleProviders` entry) are deleted — `moduleDependencies`
+     * reads both to determine what each token itself depended on.
+     */
+    purgeModuleIndexes(tokens) {
+        for (const token of tokens) {
+            for (const dependencyModule of this.moduleDependencies(token)) {
+                this._moduleReferrers.get(dependencyModule)?.delete(token);
+            }
+        }
+        const purged = new Set(tokens);
+        for (const [child, declarer] of this._childDeclarations) {
+            if (purged.has(declarer)) {
+                this._childDeclarations.delete(child);
+            }
+        }
+        for (const token of tokens) {
+            this._moduleProviders.delete(token);
+            this._moduleReferrers.delete(token);
+        }
+    }
+    addRuntimeDependency(source, target) {
+        // inject() only gets here for a visible target. Recorded even when an
+        // edge already exists: a static late-bound edge to the same target
+        // (an @Optional one compiled while the target was not visible) may
+        // not be bound yet, and then recorded no referrer. Idempotent.
+        this.recordCrossModuleReferrer(source, target, true);
+        const exists = this.getEdge(source).some((edge) => edge.type === EdgeTypeEnum.DEPENDENCY && edge.target === target);
+        if (exists) {
+            // Bind it, so moduleDependencies sees it and the purge drops the
+            // referrer just recorded when either side unloads.
+            const sources = this._lateBound.get(target);
+            if (sources?.has(source)) {
+                sources.set(source, true);
+            }
+            return;
+        }
+        this.addEdge(source, {
+            type: EdgeTypeEnum.DEPENDENCY,
+            source,
+            target,
+            metadata: { inject: "runtime", unreached: false, isCircular: false },
+        });
+    }
+    findChildDeclaration(child) {
+        const key = isLazyModule(child) ? child.id : child;
+        const declarer = this._childDeclarations.get(key);
+        if (declarer === undefined) {
+            return undefined;
+        }
+        const node = this._nodes.get(declarer);
+        return node instanceof AnalyzeModule ? node.moduleContainer : undefined;
     }
     getNode(token) {
         return this._nodes.get(token);
@@ -51,43 +462,121 @@ export class ModuleGraph {
         return [...this._nodes.values()];
     }
     // modules analyze
-    async addModules() {
+    async addModules(root, strictTokens) {
+        const moduleTokens = [];
+        const providerTokens = [];
+        const lazyTokens = [];
         const visited = new Set();
-        const imports = [this._root];
+        const imports = [root];
         while (imports.length) {
             const importModule = imports.shift();
             if (!importModule || visited.has(importModule.token)) {
                 continue;
             }
+            visited.add(importModule.token);
+            if (this._nodes.has(importModule.token)) {
+                // Already part of the graph (eager module or an earlier segment).
+                continue;
+            }
             const analyzeModule = new AnalyzeModule(importModule);
             await this.addModule(analyzeModule);
-            await this.addModuleImports(analyzeModule);
-            await this.addModuleProviders(analyzeModule);
+            moduleTokens.push(analyzeModule.id);
+            lazyTokens.push(...(await this.addModuleImports(analyzeModule)));
+            providerTokens.push(...(await this.addModuleProviders(analyzeModule, strictTokens)));
             imports.push(...(await analyzeModule.imports));
-            visited.add(analyzeModule.id);
         }
+        return { moduleTokens, providerTokens, lazyTokens };
     }
     async addModule(analyzeModule) {
         this.addNode(analyzeModule.id, analyzeModule);
+        this.indexChildren(analyzeModule);
         if (analyzeModule.isGlobal) {
             this._globalModules.set(analyzeModule.id, analyzeModule.moduleContainer);
         }
     }
+    /**
+     * Records the module's declared children. Children are never compiled into
+     * this graph; only the declaration is indexed. A child declared by a second
+     * module is a graph error and keeps its first declarer.
+     */
+    indexChildren(analyzeModule) {
+        for (const child of analyzeModule.moduleContainer.children) {
+            const key = isLazyModule(child) ? child.id : child;
+            const existing = this._childDeclarations.get(key);
+            if (existing === undefined) {
+                this._childDeclarations.set(key, analyzeModule.id);
+            }
+            else if (existing !== analyzeModule.id) {
+                // A second declarer; a module meeting its own entry is only
+                // listing the child twice, which is not an error.
+                this.pushError({
+                    type: "CHILD_DECLARED_TWICE",
+                    child: child.name,
+                    modules: [
+                        this.moduleLabel(existing),
+                        this.moduleLabel(analyzeModule.id),
+                    ],
+                });
+            }
+        }
+    }
+    moduleLabel(moduleToken) {
+        const node = this._nodes.get(moduleToken);
+        if (node instanceof AnalyzeModule) {
+            return getModuleLabel(node.moduleContainer.metatype);
+        }
+        return moduleToken;
+    }
+    /**
+     * @returns the ids of the LAZY placeholder nodes this call created, so a
+     * rolled back segment can remove them again. Placeholders that already
+     * existed are not reported and must never be removed.
+     */
     async addModuleImports(analyzeModule) {
+        const createdLazyIds = [];
         const imports = await analyzeModule.edges;
         for (const importEdge of imports) {
             this.addEdge(analyzeModule.id, importEdge);
+            this.addModuleReferrer(importEdge.source, analyzeModule.id);
+        }
+        for (const lazyModule of analyzeModule.lazyImports) {
+            if (!this._nodes.has(lazyModule.id)) {
+                this.addNode(lazyModule.id, new AnalyzeLazyModule(lazyModule));
+                createdLazyIds.push(lazyModule.id);
+            }
+        }
+        for (const lazyEdge of analyzeModule.lazyEdges) {
+            this.addEdge(analyzeModule.id, lazyEdge);
         }
+        return createdLazyIds;
     }
-    async addModuleProviders(analyzeModule) {
+    async addModuleProviders(analyzeModule, strictTokens) {
+        const added = [];
         for (const provider of analyzeModule.providers) {
             const analyzeProvider = ProviderFactory(provider, analyzeModule.moduleContainer);
             if (analyzeProvider === null) {
                 continue;
             }
+            const existing = this._nodes.get(analyzeProvider.id);
+            if (strictTokens &&
+                existing &&
+                existing.type === NodeTypeEnum.PROVIDER &&
+                existing.moduleContainer.token !==
+                    analyzeModule.moduleContainer.token) {
+                this.pushError({
+                    type: "PROVIDER_TOKEN_CONFLICT",
+                    token: analyzeProvider.label,
+                    module: analyzeModule.label,
+                    existingModule: getModuleLabel(existing.moduleContainer.metatype),
+                });
+                continue;
+            }
             this.addNode(analyzeProvider.id, analyzeProvider);
             this.addEdge(analyzeModule.id, analyzeProvider.edge);
+            this.addModuleProvider(analyzeModule.id, analyzeProvider.id);
+            added.push(analyzeProvider.id);
         }
+        return added;
     }
     // modules analyze
     // graph helpers
@@ -99,13 +588,68 @@ export class ModuleGraph {
     addNode(token, node) {
         this._nodes.set(token, node);
     }
+    addModuleProvider(moduleToken, providerToken) {
+        const providers = this._moduleProviders.get(moduleToken) ?? new Set();
+        providers.add(providerToken);
+        this._moduleProviders.set(moduleToken, providers);
+    }
+    addModuleReferrer(dependencyModule, referrerModule) {
+        const referrers = this._moduleReferrers.get(dependencyModule) ?? new Set();
+        referrers.add(referrerModule);
+        this._moduleReferrers.set(dependencyModule, referrers);
+    }
+    /**
+     * Bookkeeping for a static `DEPENDENCY` edge just added: a late-bound
+     * edge is indexed (its referrer is recorded by `bindLateEdges` once the
+     * target is visible), any other edge records its referrer now.
+     */
+    recordStaticDependency(source, target, countsAsReferrer, lateBound) {
+        if (!lateBound) {
+            this.recordCrossModuleReferrer(source, target, countsAsReferrer);
+            return;
+        }
+        const sources = this._lateBound.get(target) ?? new Map();
+        if (!sources.has(source)) {
+            sources.set(source, false);
+        }
+        this._lateBound.set(target, sources);
+    }
+    /**
+     * Records that `consumerToken` (a provider) keeps `dependencyToken`'s
+     * declaring module alive, when the two providers are declared in
+     * different modules. Called after every `DEPENDENCY` edge is added,
+     * regardless of how the dependency was resolved (own module, import, or
+     * `@Global()` fallback) — the edge already reflects that, so this needs
+     * no help from `isProviderExported`.
+     *
+     * @param countsAsReferrer - False for an edge that keeps nothing in this
+     *   graph alive: an unreached dependency, or an external one (resolved
+     *   through the parent link, so its target lives in another container).
+     */
+    recordCrossModuleReferrer(consumerToken, dependencyToken, countsAsReferrer) {
+        if (!countsAsReferrer) {
+            return;
+        }
+        const consumer = this._nodes.get(consumerToken);
+        const dependency = this._nodes.get(dependencyToken);
+        if (consumer?.type !== NodeTypeEnum.PROVIDER ||
+            dependency?.type !== NodeTypeEnum.PROVIDER) {
+            return;
+        }
+        const consumerModule = consumer.moduleContainer.token;
+        const dependencyModule = dependency.moduleContainer
+            .token;
+        if (consumerModule !== dependencyModule) {
+            this.addModuleReferrer(dependencyModule, consumerModule);
+        }
+    }
     // graph helpers
     // providers dependencies
-    async addDependencies() {
+    async addDependencies(providerTokens) {
         const visited = new Set();
-        const providerNodes = [...this.nodes].filter(isProviderNode);
-        for (const [token, node] of providerNodes) {
-            if (visited.has(token)) {
+        for (const token of providerTokens) {
+            const node = this._nodes.get(token);
+            if (!node || node.type !== NodeTypeEnum.PROVIDER || visited.has(token)) {
                 continue;
             }
             if (isAnalyzeFactoryProvider(node)) {
@@ -124,11 +668,13 @@ export class ModuleGraph {
         const constructorDependencies = this.getConstructorDependencies(node.metatype);
         const optionalDependency = this.getOptionalConstructorDependencies(node.metatype);
         for (const [index, dependency] of constructorDependencies.entries()) {
-            const dependencyToken = getDependencyToken(dependency.param);
-            const isExported = optionalDependency.includes(index) ||
-                (await this.isProviderExported(node.moduleContainer, dependencyToken));
-            if (!isExported) {
-                this.errors.push({
+            const isLazy = isForwardRef(dependency.param);
+            const dependencyToken = isLazy
+                ? dependency.param.forwardRef()
+                : getDependencyToken(dependency.param);
+            const { reachable, external, lateBound } = await this.reachDependency(node.moduleContainer, dependencyToken, optionalDependency.includes(index));
+            if (!reachable) {
+                this.pushError({
                     type: "UNREACHED_DEP_CONSTRUCTOR",
                     token: node.label,
                     dependency: tokenToString(dependencyToken),
@@ -140,22 +686,25 @@ export class ModuleGraph {
                 source: token,
                 target: dependencyToken,
                 metadata: {
-                    unreached: !isExported,
+                    unreached: !reachable,
+                    ...(external && { external: true }),
+                    ...(lateBound && { lateBound: true }),
                     isCircular: false,
+                    lazy: isLazy,
                     index: dependency.index,
                     inject: "constructor",
                 },
             };
             this.addEdge(token, newEdge);
+            this.recordStaticDependency(token, dependencyToken, reachable && !external, lateBound);
         }
         const propertiesDependencies = this.getPropertiesDependencies(node.metatype);
         const optionalProperties = this.getOptionalPropertyDependencies(node.metatype);
         for (const dependency of propertiesDependencies) {
             const dependencyToken = getDependencyToken(dependency.type);
-            const isExported = optionalProperties.includes(dependency.key) ||
-                (await this.isProviderExported(node.moduleContainer, dependencyToken));
-            if (!isExported) {
-                this.errors.push({
+            const { reachable, external, lateBound } = await this.reachDependency(node.moduleContainer, dependencyToken, optionalProperties.includes(dependency.key));
+            if (!reachable) {
+                this.pushError({
                     type: "UNREACHED_DEP_PROPERTY",
                     token: node.label,
                     dependency: tokenToString(dependencyToken),
@@ -167,13 +716,16 @@ export class ModuleGraph {
                 source: token,
                 target: dependencyToken,
                 metadata: {
-                    unreached: !isExported,
+                    unreached: !reachable,
+                    ...(external && { external: true }),
+                    ...(lateBound && { lateBound: true }),
                     isCircular: false,
                     key: dependency.key,
                     inject: "property",
                 },
             };
             this.addEdge(token, newEdge);
+            this.recordStaticDependency(token, dependencyToken, reachable && !external, lateBound);
         }
     }
     async addClassProviderDependency(token, node) {
@@ -181,11 +733,13 @@ export class ModuleGraph {
         const constructorDependencies = this.getConstructorDependencies(Class);
         const optionalDependency = this.getOptionalConstructorDependencies(Class);
         for (const [index, dependency] of constructorDependencies.entries()) {
-            const dependencyToken = getDependencyToken(dependency.param);
-            const isExported = optionalDependency.includes(index) ||
-                (await this.isProviderExported(node.moduleContainer, dependencyToken));
-            if (!isExported) {
-                this.errors.push({
+            const isLazy = isForwardRef(dependency.param);
+            const dependencyToken = isLazy
+                ? dependency.param.forwardRef()
+                : getDependencyToken(dependency.param);
+            const { reachable, external, lateBound } = await this.reachDependency(node.moduleContainer, dependencyToken, optionalDependency.includes(index));
+            if (!reachable) {
+                this.pushError({
                     type: "UNREACHED_DEP_CONSTRUCTOR",
                     token: node.label,
                     dependency: tokenToString(dependencyToken),
@@ -197,22 +751,25 @@ export class ModuleGraph {
                 source: token,
                 target: dependencyToken,
                 metadata: {
-                    unreached: !isExported,
+                    unreached: !reachable,
+                    ...(external && { external: true }),
+                    ...(lateBound && { lateBound: true }),
                     isCircular: false,
+                    lazy: isLazy,
                     index: dependency.index,
                     inject: "constructor",
                 },
             };
             this.addEdge(token, newEdge);
+            this.recordStaticDependency(token, dependencyToken, reachable && !external, lateBound);
         }
         const propertiesDependencies = this.getPropertiesDependencies(Class);
         const optionalProperty = this.getOptionalPropertyDependencies(Class);
         for (const dependency of propertiesDependencies) {
             const dependencyToken = getDependencyToken(dependency.type);
-            const isExported = optionalProperty.includes(dependency.key) ||
-                (await this.isProviderExported(node.moduleContainer, dependencyToken));
-            if (!isExported) {
-                this.errors.push({
+            const { reachable, external, lateBound } = await this.reachDependency(node.moduleContainer, dependencyToken, optionalProperty.includes(dependency.key));
+            if (!reachable) {
+                this.pushError({
                     type: "UNREACHED_DEP_PROPERTY",
                     token: node.label,
                     dependency: tokenToString(dependencyToken),
@@ -224,58 +781,101 @@ export class ModuleGraph {
                 source: token,
                 target: dependencyToken,
                 metadata: {
-                    unreached: !isExported,
+                    unreached: !reachable,
+                    ...(external && { external: true }),
+                    ...(lateBound && { lateBound: true }),
                     isCircular: false,
                     key: dependency.key,
                     inject: "property",
                 },
             });
+            this.recordStaticDependency(token, dependencyToken, reachable && !external, lateBound);
         }
     }
     async addFactoryProviderDependency(token, node) {
         const dependencies = node.inject || [];
         let index = 0;
         for (const dependency of dependencies) {
-            const isExported = await this.isProviderExported(node.moduleContainer, dependency);
-            if (!isExported) {
-                this.errors.push({
+            const isLazy = isForwardRef(dependency);
+            const dependencyToken = isLazy
+                ? dependency.forwardRef()
+                : dependency;
+            const { reachable, external, lateBound } = await this.reachDependency(node.moduleContainer, dependencyToken, false);
+            if (!reachable) {
+                this.pushError({
                     type: "UNREACHED_DEP_FACTORY",
                     token: node.label,
-                    dependency: tokenToString(dependency),
+                    dependency: tokenToString(dependencyToken),
                     key: index,
                 });
             }
             const factoryDependency = {
                 type: EdgeTypeEnum.DEPENDENCY,
                 source: token,
-                target: dependency,
+                target: dependencyToken,
                 metadata: {
-                    unreached: !isExported,
+                    unreached: !reachable,
+                    ...(external && { external: true }),
+                    ...(lateBound && { lateBound: true }),
                     isCircular: false,
+                    lazy: isLazy,
                     index: index++,
                     inject: "constructor",
                 },
             };
             this.addEdge(token, factoryDependency);
+            this.recordStaticDependency(token, dependencyToken, reachable && !external, lateBound);
         }
     }
+    /**
+     * How a dependency of a provider declared in `moduleContainer` is
+     * satisfied: locally (own module, imports, globals), by the parent
+     * container chain, or not at all. Optional dependencies count as
+     * satisfied; a parent that can provide one is still preferred. An
+     * optional dependency satisfied only by being optional is `lateBound`:
+     * the resolver injects it only once it exists and is visible.
+     */
+    async reachDependency(moduleContainer, token, optional) {
+        if (await this.isProviderExported(moduleContainer, token)) {
+            return { reachable: true, external: false, lateBound: false };
+        }
+        if (this.options.externalLookup?.(token)) {
+            return { reachable: true, external: true, lateBound: false };
+        }
+        return { reachable: optional, external: false, lateBound: optional };
+    }
     // providers dependencies
     async isProviderExported(moduleContainer, dependencyToken) {
-        // check globals
+        await moduleContainer.imports;
+        return this.isProviderVisible(moduleContainer, dependencyToken);
+    }
+    isProviderVisible(moduleContainer, dependencyToken) {
+        // globals, including what they re-export through a module class
+        const globalExports = [];
         for (const globalModule of this._globalModules.values()) {
-            if (globalModule.exports.some((provider) => provider === dependencyToken)) {
-                return true;
-            }
+            globalExports.push(...globalModule.exports);
+        }
+        if (this.exportsReach(globalExports, dependencyToken)) {
+            return true;
         }
-        // check globals
-        // check internals
+        // own providers
         if (moduleContainer.providers.some((provider) => getProviderToken(provider) === dependencyToken)) {
             return true;
         }
-        // externals
-        const containerImports = await moduleContainer.imports;
+        // imports
+        const containerImports = moduleContainer.resolvedImports;
+        if (!containerImports) {
+            throw new Error("Module imports are not resolved yet");
+        }
+        return this.exportsReach(containerImports.flatMap((imported) => imported.exports), dependencyToken);
+    }
+    /**
+     * Whether `dependencyToken` is among `exports`, following module-class
+     * re-exports through the modules' own exports.
+     */
+    exportsReach(exports, dependencyToken) {
         const visitedModules = new Set();
-        const queue = containerImports.flatMap((firstLevelContainer) => firstLevelContainer.exports);
+        const queue = [...exports];
         while (queue.length) {
             const currentExportToken = queue.shift();
             if (!currentExportToken || visitedModules.has(currentExportToken)) {
@@ -298,14 +898,13 @@ export class ModuleGraph {
         }
         return false;
     }
-    async detectCircularDependencies() {
+    async detectCircularDependencies(startTokens) {
         const visit = (nodeId, path, visited, stack) => {
             if (stack.has(nodeId)) {
                 const cyclePath = path.map((node, index) => [node, path[index + 1] || nodeId]);
                 const from = cyclePath[0];
                 const to = cyclePath[cyclePath.length - 1];
                 if (from[0] === to[1]) {
-                    const _edges = this._edges.get(nodeId);
                     for (const [from, to] of cyclePath) {
                         const edges = this._edges.get(from);
                         if (edges) {
@@ -315,10 +914,20 @@ export class ModuleGraph {
                             }
                         }
                     }
-                    this.errors.push({
-                        type: "CD_PROVIDERS",
-                        path: cyclePath,
+                    // Only push CD_PROVIDERS if NO edge in cycle has forwardRef (lazy)
+                    const hasForwardRef = cyclePath.some(([from, to]) => {
+                        const edges = this._edges.get(from);
+                        if (!edges)
+                            return false;
+                        const edge = edges.find((e) => e.target === to && e.type === EdgeTypeEnum.DEPENDENCY);
+                        return edge?.metadata.lazy === true;
                     });
+                    if (!hasForwardRef) {
+                        this.pushError({
+                            type: "CD_PROVIDERS",
+                            path: cyclePath,
+                        });
+                    }
                 }
                 return true;
             }
@@ -328,20 +937,27 @@ export class ModuleGraph {
             visited.add(nodeId);
             stack.add(nodeId);
             path.push(nodeId);
+            // Runtime (inject()) edges are followed too. That is safe: one is
+            // recorded only after inject() returned its target, and a cycle
+            // through inject() throws CircularInjectionError during creation
+            // before the edge is recorded. So runtime edges only mirror
+            // dependencies that were actually created without a cycle.
             const edges = this.getEdge(nodeId) || [];
             for (const edge of edges) {
+                // An external edge ends here: its target lives in the parent chain.
+                if (edge.metadata.external)
+                    continue;
                 visit(edge.target, path, visited, stack);
             }
             stack.delete(nodeId);
             path.pop();
             return false;
         };
-        const providers = [...this._nodes].filter(([_, node]) => node.type === NodeTypeEnum.PROVIDER);
-        for (const [nodeId, _] of providers) {
+        for (const nodeId of new Set(startTokens)) {
             visit(nodeId, [], new Set(), new Set());
         }
     }
-    async detectCircularImports() {
+    async detectCircularImports(startTokens) {
         const visit = (nodeId, path, visited, stack) => {
             if (stack.has(nodeId)) {
                 const cycleStartIndex = path.indexOf(nodeId);
@@ -353,7 +969,7 @@ export class ModuleGraph {
                     if (edges) {
                         const edge = edges.find((e) => e.source === to);
                         if (edge && edge.type === EdgeTypeEnum.IMPORT) {
-                            this.errors.push({
+                            this.pushError({
                                 type: "CD_IMPORTS",
                                 path: cyclePath
                                     .map((token) => this.getNode(token))
@@ -381,8 +997,7 @@ export class ModuleGraph {
             stack.delete(nodeId);
             path.pop();
         };
-        const modules = [...this._nodes].filter(([_, node]) => node.type === NodeTypeEnum.MODULE);
-        for (const [nodeId, _] of modules) {
+        for (const nodeId of new Set(startTokens)) {
             visit(nodeId, [], new Set(), new Set());
         }
     }