@teqfw/di 2.7.0 → 2.8.0

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);
+        };
+    }
+}

package/src/Parser.mjs

@@ -2,7 +2,7 @@
 
 /**
  * @namespace TeqFw_Di_Parser
- * @description CDC parser that builds dependency identity DTOs.
+ * @description Dependency Specifier parser that builds dependency identity DTOs.
  */
 
 import TeqFw_Di_Enum_Composition from './Enum/Composition.mjs';
@@ -11,7 +11,7 @@ import TeqFw_Di_Enum_Platform from './Enum/Platform.mjs';
 import {Factory as TeqFw_Di_Dto_DepId_Factory} from './Dto/DepId.mjs';
 
 /**
- * Parser for CDC identifiers into frozen dependency identity DTO.
+ * Parser for Dependency Specifiers into frozen dependency identity DTOs.
 */
 export default class TeqFw_Di_Parser {
     /**
@@ -26,7 +26,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Detects platform prefix and strips it from the source string.
          *
-         * @param {string} source CDC source without validation.
+         * @param {string} source Dependency Specifier source without validation.
          * @returns {{platform: typeof TeqFw_Di_Enum_Platform[keyof typeof TeqFw_Di_Enum_Platform], source: string}}
          */
         const detectPlatform = function (source) {
@@ -49,7 +49,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Parses lifecycle and wrapper suffix from the source string.
          *
-         * @param {string} source CDC source without platform prefix.
+         * @param {string} source Dependency Specifier source without platform prefix.
          * @param {typeof TeqFw_Di_Enum_Platform[keyof typeof TeqFw_Di_Enum_Platform]} platform
          * @returns {{core: string, life: typeof TeqFw_Di_Enum_Life[keyof typeof TeqFw_Di_Enum_Life] | null, lifecycleDeclared: boolean, wrappers: string[]}}
          */
@@ -89,7 +89,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Splits module and export names from canonical core string.
          *
-         * @param {string} core CDC core without lifecycle suffix.
+         * @param {string} core Dependency Specifier core without lifecycle suffix.
          * @returns {{moduleName: string, exportName: string|null}}
          */
         const parseModuleExport = function (core) {
@@ -139,20 +139,20 @@ export default class TeqFw_Di_Parser {
         };
 
         /**
-         * Parses one CDC identifier and returns normalized frozen dependency DTO.
+         * Parses one Dependency Specifier and returns a normalized frozen dependency DTO.
          *
-         * @param {string} cdc CDC identifier string.
+         * @param {string} specifier Dependency Specifier string.
          * @returns {TeqFw_Di_DepId__DTO}
          */
-        this.parse = function (cdc) {
-            if (logger) logger.log(`Parser.parse: input='${cdc}'.`);
-            if (typeof cdc !== 'string') throw new Error('CDC must be a string.');
-            if (cdc.length === 0) throw new Error('CDC must be non-empty.');
-            if (!/^[\x00-\x7F]+$/.test(cdc)) throw new Error('CDC must be ASCII.');
+        this.parse = function (specifier) {
+            if (logger) logger.log(`Parser.parse: input='${specifier}'.`);
+            if (typeof specifier !== 'string') throw new Error('Dependency Specifier must be a string.');
+            if (specifier.length === 0) throw new Error('Dependency Specifier must be non-empty.');
+            if (!/^[\x00-\x7F]+$/.test(specifier)) throw new Error('Dependency Specifier must be ASCII.');
 
             /** @type {string} */
-            const origin = cdc;
-            const detected = detectPlatform(cdc);
+            const origin = specifier;
+            const detected = detectPlatform(specifier);
             const platform = detected.platform;
             const source = detected.source;
             if (source.length === 0) throw new Error('moduleName must be non-empty.');

package/types.d.ts

@@ -1,8 +1,13 @@
 declare global {
+  type TeqFw_Di_Node_Registry_Namespace = import("./src/Node/Registry/Namespace.mjs").default;
   type TeqFw_Di_Config_NamespaceRegistry = import("./src/Config/NamespaceRegistry.mjs").default;
+  type TeqFw_Di_Node_Registry_Namespace_Entry = Readonly<{prefix: string, dirAbs: string, ext: string}>;
+  type TeqFw_Di_Node_Registry_Package = import("./src/Node/Registry/Package.mjs").default;
+  type TeqFw_Di_Node_Registry_Package_Record = Readonly<{name: string, rootAbs: string, rootReal: string, packageJson: Readonly<Record<string, unknown>>, dependencies: ReadonlyArray<string>}>;
   type TeqFw_Di_Container = import("./src/Container.mjs").default;
   type TeqFw_Di_Container_Instantiate = import("./src/Container/Instantiate.mjs").default;
   type TeqFw_Di_Container_Lifecycle = import("./src/Container/Lifecycle.mjs").default;
+  type TeqFw_Di_Container_Postprocess_Context = Readonly<{depId: TeqFw_Di_DepId__DTO}>;
   type TeqFw_Di_Container_GraphResolver = import("./src/Container/GraphResolver.mjs").default;
   type TeqFw_Di_Container_Executor = import("./src/Container/Executor.mjs").default;
   type TeqFw_Di_Parser = import("./src/Parser.mjs").default;

package/ai/concepts.md

@@ -1,25 +0,0 @@
-# concepts.md
-
-Version: 20260606
-
-## Late Binding
-
-Dependencies are resolved at runtime rather than through direct static imports between application modules. This keeps modules independent of concrete implementations and moves dependency binding into the container.
-
-## Runtime Linker
-
-The container acts as a runtime linker for ES modules. It interprets CDC identifiers, resolves modules, selects exports, and produces linked values for callers.
-
-## Dependency Contracts
-
-Dependencies are declared through CDC strings and module-level `__deps__` descriptors. Together they form the contract between module code and runtime composition.
-
-The canonical `__deps__` form is hierarchical and keyed by export name.
-
-## Namespace Mapping
-
-Logical module identifiers are translated into module-specifier bases through namespace roots. This keeps dependency addressing independent from concrete filesystem paths or URL locations.
-
-## Immutable Linked Values
-
-Values returned by the container are frozen after linking. Consumers should treat them as stable resolved values rather than mutable construction targets.