@teqfw/di 2.6.2 → 2.8.0

package/src/Container.mjs

@@ -8,10 +8,10 @@
 import TeqFw_Di_Parser from './Parser.mjs';
 import {Factory as TeqFw_Di_Dto_Resolver_Config_Factory} from './Dto/Resolver/Config.mjs';
 import TeqFw_Di_Resolver from './Container/Resolver.mjs';
-import TeqFw_Di_Container_Resolve_GraphResolver from './Container/GraphResolver.mjs';
-import TeqFw_Di_Container_Instantiate_Instantiator from './Container/Instantiate.mjs';
-import TeqFw_Di_Container_Lifecycle_Registry from './Container/Lifecycle.mjs';
-import TeqFw_Di_Container_Wrapper_Executor from './Container/Executor.mjs';
+import TeqFw_Di_Container_GraphResolver from './Container/GraphResolver.mjs';
+import TeqFw_Di_Container_Instantiate from './Container/Instantiate.mjs';
+import TeqFw_Di_Container_Lifecycle from './Container/Lifecycle.mjs';
+import TeqFw_Di_Container_Executor from './Container/Executor.mjs';
 import {executeContainerPipeline} from './Container/Pipeline.mjs';
 import TeqFw_Di_Internal_Logger, {TeqFw_Di_Internal_Logger_Noop} from './Internal/Logger.mjs';
 import {buildDependencyKey} from './Internal/DependencyKey.mjs';
@@ -32,7 +32,7 @@ export default class TeqFw_Di_Container {
         let state = 'notConfigured';
         /** @type {((depId: TeqFw_Di_DepId__DTO) => TeqFw_Di_DepId__DTO)[]} */
         const preprocess = [];
-        /** @type {((value: unknown) => unknown)[]} */
+        /** @type {((value: unknown, context: TeqFw_Di_Container_Postprocess_Context) => unknown)[]} */
         const postprocess = [];
         /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace__DTO[]} */
         const namespaceRoots = [];
@@ -46,32 +46,27 @@ export default class TeqFw_Di_Container {
         const configFactory = new TeqFw_Di_Dto_Resolver_Config_Factory();
         /** @type {TeqFw_Di_Resolver|undefined} */
         let resolver;
-        /** @type {TeqFw_Di_Container_Resolve_GraphResolver|undefined} */
+        /** @type {TeqFw_Di_Container_GraphResolver|undefined} */
         let graphResolver;
-        /** @type {TeqFw_Di_Container_Lifecycle_Registry|undefined} */
+        /** @type {TeqFw_Di_Container_Lifecycle|undefined} */
         let lifecycle;
         /** @type {{log(message: string): void, error(message: string, error?: unknown): void}} */
         let logger = TeqFw_Di_Internal_Logger_Noop;
-        /** @type {TeqFw_Di_Container_Instantiate_Instantiator} */
-        const instantiator = new TeqFw_Di_Container_Instantiate_Instantiator();
-        /** @type {TeqFw_Di_Container_Wrapper_Executor} */
-        const wrapperExecutor = new TeqFw_Di_Container_Wrapper_Executor();
+        /** @type {TeqFw_Di_Container_Instantiate} */
+        const instantiator = new TeqFw_Di_Container_Instantiate();
+        /** @type {TeqFw_Di_Container_Executor} */
+        const wrapperExecutor = new TeqFw_Di_Container_Executor();
 
         const getKey = buildDependencyKey;
         const getMockKey = buildDependencyKey;
 
-        const freeze = function (value) {
+        let freeze = function (value) {
             if ((value === null) || (value === undefined)) return value;
             const type = typeof value;
             if ((type !== 'object') && (type !== 'function')) return value;
             if (Object.prototype.toString.call(value) === '[object Module]') return value;
             if (Object.isFrozen(value)) return value;
-            try {
-                Object.freeze(value);
-            } catch (error) {
-                logger.log(`Container.freeze: skipped (${String(error)}).`);
-            }
-            return value;
+            return Object.freeze(value);
         };
 
         const applyPreprocess = function (depId) {
@@ -81,10 +76,26 @@ export default class TeqFw_Di_Container {
             return current;
         };
 
-        const applyPostprocess = function (value) {
+        const canonicalize = function (specifier) {
+            return applyPreprocess(parser.parse(specifier));
+        };
+
+        const findMock = function (depId) {
+            const key = getMockKey(depId);
+            return {found: testMode === true && mockRegistry.has(key), value: mockRegistry.get(key)};
+        };
+
+        const applyPostprocess = function (value, depId) {
             /** @type {unknown} */
             let current = value;
-            for (const fn of postprocess) current = fn(current);
+            /** @type {TeqFw_Di_Container_Postprocess_Context} */
+            const context = Object.freeze({depId});
+            for (const fn of postprocess) {
+                current = fn(current, context);
+                if (current instanceof Promise) {
+                    throw new Error('Postprocess callback must return synchronously (non-Promise).');
+                }
+            }
             return current;
         };
 
@@ -104,8 +115,8 @@ export default class TeqFw_Di_Container {
             const resolverConfig = configFactory.create({namespaces: namespaceRoots});
             if (typeof parser.setLogger === 'function') parser.setLogger(logger);
             resolver = new TeqFw_Di_Resolver({config: resolverConfig, logger});
-            graphResolver = new TeqFw_Di_Container_Resolve_GraphResolver({parser, resolver, logger});
-            lifecycle = new TeqFw_Di_Container_Lifecycle_Registry(logger);
+            graphResolver = new TeqFw_Di_Container_GraphResolver({canonicalize, findMock, resolver, logger});
+            lifecycle = new TeqFw_Di_Container_Lifecycle(logger);
         };
 
         /**
@@ -123,7 +134,7 @@ export default class TeqFw_Di_Container {
         /**
          * Adds a postprocessing hook.
          *
-         * @param {(value: unknown) => unknown} fn
+         * @param {(value: unknown, context: TeqFw_Di_Container_Postprocess_Context) => unknown} fn
          * @returns {void}
          */
         this.addPostprocess = function (fn) {
@@ -132,6 +143,19 @@ export default class TeqFw_Di_Container {
             postprocess.push(fn);
         };
 
+
+        /**
+         * Sets the host hardening policy for every resolved value and mock.
+         *
+         * @param {(value: unknown) => unknown} fn
+         * @returns {void}
+         */
+        this.setHardener = function (fn) {
+            assertBuilderStage();
+            logBuilder('setHardener().');
+            freeze = fn;
+        };
+
         /**
          * Registers namespace root mapping.
          *
@@ -172,29 +196,29 @@ export default class TeqFw_Di_Container {
         };
 
         /**
-         * Registers a mock value for a CDC.
+         * Registers a mock value for a Dependency Specifier.
          *
-         * @param {string} cdc
+         * @param {string} specifier
          * @param {any} mock
          * @returns {void}
          */
-        this.register = function (cdc, mock) {
+        this.register = function (specifier, mock) {
             assertBuilderStage();
-            logBuilder(`register('${cdc}').`);
+            logBuilder(`register('${specifier}').`);
             if (testMode !== true) throw new Error('Container test mode is disabled.');
-            const depId = parser.parse(cdc);
+            const depId = canonicalize(specifier);
             mockRegistry.set(getMockKey(depId), mock);
         };
 
         /**
-         * Resolves a CDC into a frozen linked instance.
+         * Resolves a Dependency Specifier into a frozen Resolved Value.
          *
-         * @param {string} cdc
+         * @param {string} specifier
          * @returns {Promise<any>}
          */
-        this.get = async function (cdc) {
+        this.get = async function (specifier) {
             if (state === 'failed') {
-                logger.error(`Container.get: rejected in failed state cdc='${cdc}'.`);
+                logger.error(`Container.get: rejected in failed state specifier='${specifier}'.`);
                 throw new Error('Container is in failed state.');
             }
 
@@ -202,7 +226,6 @@ export default class TeqFw_Di_Container {
                 initializeInfrastructure();
                 logger.log(`Container.state: '${state}'.`);
                 return await executeContainerPipeline({
-                    parser,
                     resolver,
                     graphResolver,
                     lifecycle,
@@ -212,9 +235,9 @@ export default class TeqFw_Di_Container {
                     testMode,
                     mockRegistry,
                     freeze,
-                    applyPreprocess,
+                    canonicalize,
                     applyPostprocess,
-                }, cdc);
+                }, specifier);
             } catch (error) {
                 logger.error(`Container.transition: operational -> failed.`, error);
                 state = 'failed';
@@ -223,3 +246,12 @@ export default class TeqFw_Di_Container {
         };
     }
 }
+
+        const canonicalize = function (specifier) {
+            return applyPreprocess(parser.parse(specifier));
+        };
+
+        const findMock = function (depId) {
+            const key = getMockKey(depId);
+            return {found: testMode === true && mockRegistry.has(key), value: mockRegistry.get(key)};
+        };

package/src/Dto/DepId.mjs

@@ -47,7 +47,7 @@ export default class DTO {
     /** @type {string[]} Wrapper pipeline names. */
     wrappers;
 
-    /** @type {string} Original CDC string. */
+    /** @type {string} Original Dependency Specifier string. */
     origin;
 }
 

package/src/Internal/DepsDecl.mjs

@@ -9,7 +9,7 @@
  * Reads dependency declaration map for the selected export of a module namespace.
  *
  * @param {object} namespace Loaded module namespace.
- * @param {TeqFw_Di_DepId__DTO} depId Canonical dependency identity.
+ * @param {TeqFw_Di_DepId__DTO} depId Parsed dependency identity.
  * @returns {Record<string, unknown>} Dependency declaration map.
  */
 export function readDepsDecl(namespace, depId) {
@@ -24,7 +24,7 @@ export function readDepsDecl(namespace, depId) {
     if ((exportScoped !== undefined) && (exportScoped !== null) && (typeof exportScoped === 'object') && !Array.isArray(exportScoped)) {
         const values = Object.values(/** @type {Record<string, unknown>} */ (exportScoped));
         if (!values.every((value) => typeof value === 'string')) {
-            throw new Error('__deps__ export entries must map dependency names to CDC strings.');
+            throw new Error('__deps__ export entries must map dependency names to Dependency Specifier strings.');
         }
         return /** @type {Record<string, unknown>} */ (exportScoped);
     }

package/src/Node/Registry/Namespace.mjs

@@ -0,0 +1,208 @@
+// @ts-check
+
+import TeqFw_Di_Node_Registry_Package from './Package.mjs';
+
+/**
+ * @namespace TeqFw_Di_Node_Registry_Namespace
+ * @description Deterministic Node.js namespace registry derived from the runtime package graph.
+ */
+
+/**
+ * @typedef {object} TeqFw_Di_Node_Registry_Namespace_Dependencies
+ * @property {{readFile(path: string, encoding: string): Promise<string>, realpath(path: string): Promise<string>, stat(path: string): Promise<{isDirectory(): boolean}>}} fs
+ * @property {{join(...paths: string[]): string, dirname(path: string): string, relative(from: string, to: string): string, resolve(...paths: string[]): string, isAbsolute(path: string): boolean}} path
+ * @property {string} appRoot
+ */
+
+/**
+ * @typedef {object} TeqFw_Di_Node_Registry_Namespace_Entry
+ * @property {string} prefix
+ * @property {string} dirAbs
+ * @property {string} ext
+ */
+
+/**
+ * Builds a deterministic immutable Node.js namespace registry from runtime package records.
+ */
+export default class TeqFw_Di_Node_Registry_Namespace {
+    /**
+     * @param {TeqFw_Di_Node_Registry_Namespace_Dependencies} deps
+     */
+    constructor({fs, path, appRoot}) {
+        /**
+         * @param {string} rootAbs
+         * @param {string} candidateAbs
+         * @returns {boolean}
+         */
+        const isInside = function (rootAbs, candidateAbs) {
+            const rel = path.relative(rootAbs, candidateAbs);
+            return (rel === '') || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        };
+
+        /**
+         * @param {unknown} value
+         * @returns {value is Record<string, unknown>}
+         */
+        const isRecord = function (value) {
+            return (value !== null) && (typeof value === 'object') && !Array.isArray(value);
+        };
+
+        /**
+         * @param {{name: string, rootAbs: string}} publisher
+         * @returns {string}
+         */
+        const publisherLabel = function (publisher) {
+            return `package '${publisher.name}' at '${publisher.rootAbs}'`;
+        };
+
+        /**
+         * @param {string} absPath
+         * @returns {Promise<boolean>}
+         */
+        const isDirectory = async function (absPath) {
+            try {
+                return (await fs.stat(absPath)).isDirectory();
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * @param {string} packageRootAbs
+         * @param {string} dirAbs
+         * @returns {Promise<void>}
+         */
+        const assertInsidePackageRoot = async function (packageRootAbs, dirAbs) {
+            const packageRootReal = await fs.realpath(packageRootAbs);
+            const dirReal = await fs.realpath(dirAbs);
+            if (!isInside(packageRootReal, dirReal)) {
+                throw new Error('Namespace path resolves outside package root: ' + dirAbs + '.');
+            }
+        };
+
+        /**
+         * @param {unknown} ext
+         * @returns {string}
+         */
+        const normalizeExt = function (ext) {
+            if (ext === undefined) return '.mjs';
+            if ((typeof ext !== 'string') || (ext.length === 0)) {
+                throw new Error('Namespace extension must be a non-empty string.');
+            }
+            const normalized = ext.startsWith('.') ? ext : '.' + ext;
+            if ((normalized !== '.mjs') && (normalized !== '.js')) {
+                throw new Error('Namespace extension is not ESM-compatible: ' + normalized + '.');
+            }
+            return normalized;
+        };
+
+        /**
+         * @param {unknown} raw
+         * @param {{name: string, rootAbs: string}} publisher
+         * @param {{source: 'canonical'|'legacy', index: number}} origin
+         * @returns {Promise<{entry: TeqFw_Di_Node_Registry_Namespace_Entry, origin: {source: 'canonical'|'legacy', index: number}}>}
+         */
+        const normalizeEntry = async function (raw, publisher, origin) {
+            const packageRootAbs = publisher.rootAbs;
+            const source = `${publisherLabel(publisher)} ${origin.source} namespace declaration at index ${origin.index}`;
+            if (!isRecord(raw)) {
+                throw new Error(`DI namespace declared by ${source} must be an object.`);
+            }
+            const item = raw;
+            const prefix = item.prefix;
+            if ((typeof prefix !== 'string') || (prefix.length === 0) || !prefix.endsWith('_')) {
+                throw new Error(`DI namespace prefix declared by ${source} is invalid: ${String(prefix)}.`);
+            }
+
+            const rawPath = item.path;
+            if ((typeof rawPath !== 'string') || (rawPath.length === 0) || path.isAbsolute(rawPath)) {
+                throw new Error(`DI namespace path declared by ${source} must be a non-empty relative path: ${String(rawPath)}.`);
+            }
+            const dirAbs = path.resolve(packageRootAbs, rawPath);
+            if (!isInside(packageRootAbs, dirAbs)) {
+                throw new Error(`DI namespace path declared by ${source} lexically escapes its package root: ${rawPath}.`);
+            }
+            if (!(await isDirectory(dirAbs))) {
+                throw new Error(`DI namespace path declared by ${source} does not point to an existing directory: ${dirAbs}.`);
+            }
+            try {
+                await assertInsidePackageRoot(packageRootAbs, dirAbs);
+            } catch (error) {
+                throw new Error(`DI namespace path declared by ${source} resolves outside its package root: ${dirAbs}.`, {cause: error});
+            }
+            try {
+                return {entry: {prefix, dirAbs, ext: normalizeExt(item.ext)}, origin};
+            } catch (error) {
+                throw new Error(`DI namespace extension declared by ${source} is invalid: ${String(error)}.`, {cause: error});
+            }
+        };
+
+        /**
+         * Selects one supported declaration set without merging schemas.
+         *
+         * @param {Readonly<Record<string, unknown>>} packageJson
+         * @param {{name: string, rootAbs: string}} publisher
+         * @returns {{source: 'canonical'|'legacy', entries: unknown[]}|undefined}
+         */
+        const selectDeclarationSet = function (packageJson, publisher) {
+            const teqfw = packageJson.teqfw;
+            if (teqfw === undefined) return undefined;
+            if (!isRecord(teqfw)) throw new Error(`TeqFW metadata for ${publisherLabel(publisher)} must be an object.`);
+            const fw = teqfw.fw;
+            if (fw !== undefined) {
+                if (!isRecord(fw)) throw new Error(`TeqFW framework metadata for ${publisherLabel(publisher)} must be an object.`);
+                const di = fw.di;
+                if (di !== undefined) {
+                    if (!isRecord(di)) throw new Error(`TeqFW DI metadata for ${publisherLabel(publisher)} must be an object.`);
+                    if (Object.hasOwn(di, 'namespaces')) {
+                        if (!Array.isArray(di.namespaces)) {
+                            throw new Error(`Canonical DI namespaces declared by ${publisherLabel(publisher)} must be an array.`);
+                        }
+                        return {source: 'canonical', entries: di.namespaces};
+                    }
+                }
+            }
+            if (Object.hasOwn(teqfw, 'namespaces')) {
+                if (!Array.isArray(teqfw.namespaces)) {
+                    throw new Error(`Legacy DI namespaces declared by ${publisherLabel(publisher)} must be an array.`);
+                }
+                return {source: 'legacy', entries: teqfw.namespaces};
+            }
+            return undefined;
+        };
+
+        /**
+         * @returns {Promise<ReadonlyArray<TeqFw_Di_Node_Registry_Namespace_Entry>>}
+         */
+        this.build = async function () {
+            const packages = await new TeqFw_Di_Node_Registry_Package({fs, path, appRoot}).build();
+            /** @type {Map<string, {publisher: {name: string, rootAbs: string}, origin: {source: 'canonical'|'legacy', index: number}}>} */
+            const publisherByPrefix = new Map();
+            /** @type {TeqFw_Di_Node_Registry_Namespace_Entry[]} */
+            const entries = [];
+
+            for (const onePackage of packages) {
+                const packageJson = onePackage.packageJson;
+                const publisher = {name: onePackage.name, rootAbs: onePackage.rootAbs};
+                const declarationSet = selectDeclarationSet(packageJson, publisher);
+                if (declarationSet === undefined) continue;
+                for (const [index, raw] of declarationSet.entries.entries()) {
+                    const origin = {source: declarationSet.source, index};
+                    const normalized = await normalizeEntry(raw, publisher, origin);
+                    const existing = publisherByPrefix.get(normalized.entry.prefix);
+                    if (existing) {
+                        throw new Error(`Duplicate DI namespace prefix '${normalized.entry.prefix}' declared by ${publisherLabel(publisher)} ${origin.source} namespace declaration at index ${origin.index} conflicts with ${publisherLabel(existing.publisher)} ${existing.origin.source} namespace declaration at index ${existing.origin.index}.`);
+                    }
+                    publisherByPrefix.set(normalized.entry.prefix, {publisher, origin: normalized.origin});
+                    entries.push(normalized.entry);
+                }
+            }
+
+            entries.sort((a, b) => (b.prefix.length - a.prefix.length) || a.prefix.localeCompare(b.prefix));
+            for (const entry of entries) {
+                Object.freeze(entry);
+            }
+            return Object.freeze(entries);
+        };
+    }
+}

package/src/Node/Registry/Package.mjs

@@ -0,0 +1,215 @@
+// @ts-check
+
+/**
+ * @namespace TeqFw_Di_Node_Registry_Package
+ * @description Deterministic Node.js composition-stage graph of installed runtime packages.
+ */
+
+/**
+ * @typedef {object} TeqFw_Di_Node_Registry_Package_Dependencies
+ * @property {{readFile(path: string, encoding: string): Promise<string>, realpath(path: string): Promise<string>, stat(path: string): Promise<{isDirectory(): boolean}>}} fs
+ * @property {{join(...paths: string[]): string, dirname(path: string): string, relative(from: string, to: string): string, resolve(...paths: string[]): string, isAbsolute(path: string): boolean}} path
+ * @property {string} appRoot
+ */
+
+/**
+ * Builds a deterministic immutable dependency-first list of root and installed runtime packages.
+ */
+export default class TeqFw_Di_Node_Registry_Package {
+    /**
+     * @param {TeqFw_Di_Node_Registry_Package_Dependencies} deps
+     */
+    constructor({fs, path, appRoot}) {
+        const appRootAbs = path.resolve(appRoot);
+
+        /**
+         * @param {unknown} value
+         * @returns {value is Record<string, unknown>}
+         */
+        const isRecord = function (value) {
+            return (value !== null) && (typeof value === 'object') && !Array.isArray(value);
+        };
+
+        /**
+         * @param {object} value
+         * @returns {object}
+         */
+        const freezeDeep = function (value) {
+            for (const nested of Object.values(value)) {
+                if ((nested !== null) && (typeof nested === 'object') && !Object.isFrozen(nested)) {
+                    freezeDeep(nested);
+                }
+            }
+            return Object.freeze(value);
+        };
+
+        /**
+         * @param {string} fileAbs
+         * @returns {Promise<Record<string, unknown>>}
+         */
+        const readJson = async function (fileAbs) {
+            let content;
+            try {
+                content = await fs.readFile(fileAbs, 'utf8');
+            } catch (error) {
+                throw new Error('Unable to read package metadata ' + fileAbs + ': ' + String(error) + '.');
+            }
+            try {
+                const value = JSON.parse(content);
+                if (!isRecord(value)) {
+                    throw new Error('root must be an object');
+                }
+                return value;
+            } catch (error) {
+                throw new Error('Invalid package metadata ' + fileAbs + ': ' + String(error) + '.');
+            }
+        };
+
+        /**
+         * @param {string} packageRootAbs
+         * @returns {Promise<{name: string, packageJson: Record<string, unknown>, dependencies: string[]}>}
+         */
+        const readPackageMetadata = async function (packageRootAbs) {
+            const packageJsonAbs = path.join(packageRootAbs, 'package.json');
+            const packageJson = await readJson(packageJsonAbs);
+            const name = packageJson.name;
+            if ((typeof name !== 'string') || (name.length === 0)) {
+                throw new Error('Invalid package metadata ' + packageJsonAbs + ': name must be a non-empty string.');
+            }
+
+            const rawDependencies = packageJson.dependencies;
+            if (rawDependencies === undefined) {
+                return {name, packageJson, dependencies: []};
+            }
+            if (!isRecord(rawDependencies)) {
+                throw new Error('Invalid dependency metadata ' + packageJsonAbs + ': dependencies must be an object.');
+            }
+            const dependencies = Object.keys(rawDependencies).sort();
+            for (const dependencyName of dependencies) {
+                const dependencyRange = rawDependencies[dependencyName];
+                if ((dependencyName.length === 0) || (typeof dependencyRange !== 'string') || (dependencyRange.length === 0)) {
+                    throw new Error('Invalid dependency metadata ' + packageJsonAbs + ': ' + dependencyName + ' must have a non-empty string declaration.');
+                }
+            }
+            return {name, packageJson, dependencies};
+        };
+
+        /**
+         * @param {string} absPath
+         * @returns {Promise<boolean>}
+         */
+        const isDirectory = async function (absPath) {
+            try {
+                return (await fs.stat(absPath)).isDirectory();
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * @param {string} rootAbs
+         * @param {string} candidateAbs
+         * @returns {boolean}
+         */
+        const isInside = function (rootAbs, candidateAbs) {
+            const rel = path.relative(rootAbs, candidateAbs);
+            return (rel === '') || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        };
+
+        /**
+         * @param {string} candidateAbs
+         * @returns {Promise<boolean>}
+         */
+        const hasPackageJson = async function (candidateAbs) {
+            try {
+                await fs.stat(path.join(candidateAbs, 'package.json'));
+                return true;
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * @param {string} packageName
+         * @param {string} fromPackageRootAbs
+         * @returns {Promise<string>}
+         */
+        const resolveDependencyPackageRoot = async function (packageName, fromPackageRootAbs) {
+            let cursor = fromPackageRootAbs;
+            while (isInside(appRootAbs, cursor)) {
+                const candidate = path.join(cursor, 'node_modules', packageName);
+                if ((await isDirectory(candidate)) && (await hasPackageJson(candidate))) {
+                    return path.resolve(candidate);
+                }
+                if (cursor === appRootAbs) break;
+                const parent = path.dirname(cursor);
+                if (parent === cursor) break;
+                cursor = parent;
+            }
+            throw new Error('Installed dependency is not found: ' + packageName + ' from ' + fromPackageRootAbs + '.');
+        };
+
+        /**
+         * @returns {Promise<ReadonlyArray<TeqFw_Di_Node_Registry_Package_Record>>}
+         */
+        this.build = async function () {
+            /** @type {Map<string, TeqFw_Di_Node_Registry_Package_Record>} */
+            const recordsByRoot = new Map();
+            /** @type {Set<string>} */
+            const visitingRoots = new Set();
+            /** @type {TeqFw_Di_Node_Registry_Package_Record[]} */
+            const records = [];
+            /** @type {string[]} */
+            const pathStack = [];
+
+            /**
+             * Visits a package after all of its dependencies.
+             *
+             * @param {string} rootAbs
+             * @returns {Promise<string>}
+             */
+            const visit = async function (rootAbs) {
+                let rootReal;
+                try {
+                    rootReal = await fs.realpath(rootAbs);
+                } catch (error) {
+                    throw new Error('Unable to resolve package root ' + rootAbs + ': ' + String(error) + '.');
+                }
+                if (recordsByRoot.has(rootReal)) return rootReal;
+                if (visitingRoots.has(rootReal)) {
+                    const cycleStart = pathStack.indexOf(rootReal);
+                    const cycle = [...pathStack.slice(cycleStart), rootReal].join(' -> ');
+                    throw new Error('Cyclic package dependency detected: ' + cycle + '.');
+                }
+                visitingRoots.add(rootReal);
+                pathStack.push(rootReal);
+
+                const metadata = await readPackageMetadata(rootAbs);
+                const packageJson = /** @type {Readonly<Record<string, unknown>>} */ (freezeDeep(metadata.packageJson));
+                /** @type {string[]} */
+                const dependencies = [];
+
+                for (const dependencyName of metadata.dependencies) {
+                    const dependencyRootAbs = await resolveDependencyPackageRoot(dependencyName, rootAbs);
+                    dependencies.push(await visit(dependencyRootAbs));
+                }
+
+                pathStack.pop();
+                visitingRoots.delete(rootReal);
+                const record = Object.freeze({
+                    name: metadata.name,
+                    rootAbs,
+                    rootReal,
+                    packageJson,
+                    dependencies: Object.freeze([...new Set(dependencies)]),
+                });
+                recordsByRoot.set(rootReal, record);
+                records.push(record);
+                return rootReal;
+            };
+
+            await visit(appRootAbs);
+            return Object.freeze(records);
+        };
+    }
+}