@loutrejs/loutre 0.5.0 → 0.7.0

package/dist/core/model/modules.d.ts

@@ -0,0 +1,2 @@
+import type { ModelBuildContext } from './context.js';
+export declare function collectModuleDeclarations(context: ModelBuildContext): void;

package/dist/core/model/modules.js

@@ -0,0 +1,101 @@
+import { collectInjectedDependencies } from '../injection.js';
+import { diagnostic } from '../diagnostic.js';
+import { asModuleInstance } from '../module.js';
+import { normalizeProvider } from '../provider.js';
+import { tokenName } from '../token.js';
+import { appendLifecycleNodes } from './lifecycle.js';
+import { snapshotProvider } from './snapshot.js';
+import { getSourceLocation } from '../source-location.js';
+export function collectModuleDeclarations(context) {
+    const { modules, moduleIds, nodes, edges, diagnostics, providers, providerNodes, } = context;
+    const moduleNames = new Set();
+    for (const module of modules) {
+        const moduleId = moduleIds.get(module);
+        if (module.definition.name) {
+            if (moduleNames.has(module.definition.name)) {
+                diagnostics.push(diagnostic('LUTRE_MODULE_NAME_COLLISION', `Module name ${module.definition.name} is already registered.`, moduleId));
+            }
+            moduleNames.add(module.definition.name);
+        }
+        const moduleSource = getSourceLocation(module.template);
+        nodes.push({
+            kind: 'module',
+            id: moduleId,
+            ...(moduleSource === undefined ? {} : { source: moduleSource }),
+            ...(module.definition.name === undefined
+                ? {}
+                : { name: module.definition.name }),
+            ...(module.definition.description === undefined
+                ? {}
+                : { description: module.definition.description }),
+        });
+        for (const imported of module.definition.imports ?? []) {
+            const target = moduleIds.get(asModuleInstance(imported));
+            if (target)
+                edges.push({ from: moduleId, to: target, kind: 'imports' });
+        }
+        for (const declaration of module.definition.providers ?? []) {
+            const normalized = normalizeProvider(declaration);
+            const provider = snapshotProvider(normalized);
+            const providerSource = normalized.kind === 'class'
+                ? getSourceLocation(normalized.useClass)
+                : getSourceLocation(declaration);
+            const providerId = context.nextProviderId();
+            const existingProvider = providerNodes.get(provider.provide);
+            if (existingProvider?.provider.kind === 'environment' &&
+                provider.kind === 'environment') {
+                edges.push({ from: moduleId, to: existingProvider.id, kind: 'owns' });
+                if (module.definition.exports?.includes(provider.provide)) {
+                    edges.push({
+                        from: moduleId,
+                        to: existingProvider.id,
+                        kind: 'exports',
+                    });
+                }
+                continue;
+            }
+            if (existingProvider) {
+                diagnostics.push(diagnostic('LUTRE_PROVIDER_DUPLICATE', `Provider ${tokenName(provider.provide)} is declared more than once.`, providerId));
+                continue;
+            }
+            const node = {
+                kind: 'provider',
+                id: providerId,
+                token: provider.provide,
+                provider,
+                moduleId,
+                dependencies: collectProviderDependencies(provider),
+                ...(providerSource === undefined ? {} : { source: providerSource }),
+            };
+            providers.push(provider);
+            providerNodes.set(provider.provide, node);
+            nodes.push(node);
+            edges.push({ from: moduleId, to: providerId, kind: 'owns' });
+            if (module.definition.exports?.includes(provider.provide)) {
+                edges.push({ from: moduleId, to: providerId, kind: 'exports' });
+            }
+        }
+        appendLifecycleNodes(module, moduleId, nodes, edges);
+    }
+}
+function collectProviderDependencies(provider) {
+    switch (provider.kind) {
+        case 'class':
+            return Object.freeze(collectInjectedDependencies(provider.provide, () => Reflect.construct(provider.useClass, [])));
+        case 'factory':
+            return Object.freeze([...provider.inject]);
+        case 'conditional': {
+            const dependencies = new Set();
+            for (const implementation of Object.values(provider.mapping)) {
+                for (const dependency of collectInjectedDependencies(provider.provide, () => Reflect.construct(implementation, []))) {
+                    dependencies.add(dependency);
+                }
+            }
+            return Object.freeze([...dependencies]);
+        }
+        case 'value':
+        case 'environment':
+        case 'arguments':
+            return Object.freeze([]);
+    }
+}

package/dist/core/model/providers.d.ts

@@ -0,0 +1,4 @@
+import type { ModelBuildContext } from './context.js';
+export declare function resolveModuleExports(context: ModelBuildContext): void;
+export declare function compileArgumentsProvider(context: ModelBuildContext): void;
+export declare function resolveProviderDependencies(context: ModelBuildContext): void;

package/dist/core/model/providers.js

@@ -0,0 +1,74 @@
+import { diagnostic } from '../diagnostic.js';
+import { argumentsProvider } from '../provider.js';
+import { isFrameworkProvidedToken } from '../token-internal.js';
+import { tokenName } from '../token.js';
+import { snapshotProvider } from './snapshot.js';
+import { isTokenVisible, moduleDeclaresToken } from './visibility.js';
+export function resolveModuleExports(context) {
+    const { modules, moduleIds, providerNodes, edges, diagnostics } = context;
+    for (const module of modules) {
+        const moduleId = moduleIds.get(module);
+        for (const exported of module.definition.exports ?? []) {
+            if (moduleDeclaresToken(module, exported))
+                continue;
+            const provider = providerNodes.get(exported);
+            const providerModule = provider
+                ? modules.find((candidate) => moduleIds.get(candidate) === provider.moduleId)
+                : undefined;
+            if (provider &&
+                providerModule &&
+                isTokenVisible(module, providerModule, exported)) {
+                edges.push({ from: moduleId, to: provider.id, kind: 'exports' });
+                continue;
+            }
+            diagnostics.push(diagnostic('LUTRE_MODULE_EXPORT_UNRESOLVED', `Module export ${tokenName(exported)} is neither declared by the Module nor re-exported from an imported Module.`, `${moduleId}.exports.${tokenName(exported)}`));
+        }
+    }
+}
+export function compileArgumentsProvider(context) {
+    const { options, providerNodes, diagnostics, providers, nodes } = context;
+    if (!options.arguments)
+        return;
+    const existingProvider = providerNodes.get(options.arguments);
+    if (existingProvider) {
+        diagnostics.push(diagnostic('LUTRE_ARGS_001', `Arguments ${tokenName(options.arguments)} is runtime-managed and cannot also be declared as a normal provider.`, existingProvider.id));
+    }
+    const provider = snapshotProvider(argumentsProvider(options.arguments));
+    const node = {
+        kind: 'provider',
+        id: context.nextProviderId(),
+        token: options.arguments,
+        provider,
+        moduleId: 'application',
+        dependencies: Object.freeze([]),
+    };
+    providers.push(provider);
+    providerNodes.set(options.arguments, node);
+    nodes.push(node);
+}
+export function resolveProviderDependencies(context) {
+    const { providerNodes, modules, moduleIds, edges, diagnostics } = context;
+    for (const provider of providerNodes.values()) {
+        if (provider.moduleId === 'application')
+            continue;
+        const sourceModule = modules.find((candidate) => moduleIds.get(candidate) === provider.moduleId);
+        if (!sourceModule)
+            continue;
+        for (const dependency of provider.dependencies) {
+            const target = providerNodes.get(dependency);
+            if (target) {
+                edges.push({ from: provider.id, to: target.id, kind: 'injects' });
+                const targetModule = modules.find((candidate) => moduleIds.get(candidate) === target.moduleId);
+                if (targetModule &&
+                    target.moduleId !== provider.moduleId &&
+                    !moduleDeclaresToken(sourceModule, dependency) &&
+                    !isTokenVisible(sourceModule, targetModule, dependency)) {
+                    diagnostics.push(diagnostic('LUTRE_MODULE_VISIBILITY', `Provider ${tokenName(provider.token)} depends on private ${tokenName(dependency)} from another Module.`, provider.id));
+                }
+            }
+            else if (!isFrameworkProvidedToken(dependency)) {
+                diagnostics.push(diagnostic('LUTRE_PROVIDER_DEPENDENCY_MISSING', `Provider ${tokenName(provider.token)} requires ${tokenName(dependency)}, but no provider is declared.`, provider.id));
+            }
+        }
+    }
+}

package/dist/core/model/snapshot.d.ts

@@ -0,0 +1,6 @@
+import type { ExecutionExtension } from '../extension.js';
+import type { LifecycleHook } from '../lifecycle.js';
+import type { ProviderDescriptor } from '../provider.js';
+export declare function snapshotProvider(provider: ProviderDescriptor): ProviderDescriptor;
+export declare function snapshotLifecycleHook(hook: LifecycleHook<any>): LifecycleHook<any>;
+export declare function snapshotExecutionExtension(extension: ExecutionExtension): ExecutionExtension;

package/dist/core/model/snapshot.js

@@ -0,0 +1,31 @@
+export function snapshotProvider(provider) {
+    if (provider.kind === 'conditional') {
+        return Object.freeze({
+            ...provider,
+            select: Object.freeze({ ...provider.select }),
+            mapping: Object.freeze({ ...provider.mapping }),
+        });
+    }
+    if (provider.kind === 'factory') {
+        return Object.freeze({
+            ...provider,
+            inject: Object.freeze([...provider.inject]),
+        });
+    }
+    return Object.freeze({ ...provider });
+}
+export function snapshotLifecycleHook(hook) {
+    return Object.freeze({
+        kind: 'lifecycle-hook',
+        inject: Object.freeze([...hook.inject]),
+        run: hook.run,
+    });
+}
+export function snapshotExecutionExtension(extension) {
+    return Object.freeze({
+        ...extension,
+        ...(extension.host === undefined
+            ? {}
+            : { host: Object.freeze({ ...extension.host }) }),
+    });
+}

package/dist/core/model/types.d.ts

@@ -0,0 +1,78 @@
+import type { ArgsClass } from '../args.js';
+import type { AnyExecutionExtension, ExecutionExtension, RuntimeCapability } from '../extension.js';
+import type { LifecycleHook } from '../lifecycle.js';
+import type { ModuleInstance, ModuleTemplate } from '../module.js';
+import type { ProviderDescriptor } from '../provider.js';
+import type { Diagnostic } from '../diagnostic.js';
+import type { TokenLike } from '../token.js';
+import type { SourceLocation } from '../source-location.js';
+export interface ModuleModelNode {
+    readonly kind: 'module';
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly source?: SourceLocation;
+}
+export interface ProviderModelNode {
+    readonly kind: 'provider';
+    readonly id: string;
+    readonly token: TokenLike;
+    readonly provider: ProviderDescriptor;
+    readonly moduleId: string;
+    readonly dependencies: readonly TokenLike[];
+    readonly source?: SourceLocation;
+}
+export interface ExecutionModelNode<TCompiled = unknown> {
+    readonly kind: 'execution';
+    readonly id: string;
+    readonly executionKind: string;
+    readonly moduleId: string;
+    readonly dependencies: readonly TokenLike[];
+    readonly capabilities: readonly RuntimeCapability[];
+    readonly compiled: TCompiled;
+    readonly source?: SourceLocation;
+}
+export interface LifecycleModelNode {
+    readonly kind: 'lifecycle';
+    readonly id: string;
+    readonly moduleId: string;
+    readonly phase: string;
+    readonly hook: LifecycleHook<any>;
+    readonly source?: SourceLocation;
+}
+export interface FrameworkModelNode {
+    readonly kind: 'framework';
+    readonly id: string;
+    readonly frameworkKind: 'runtime-capability' | 'execution-extension';
+    readonly name: string;
+    readonly source?: SourceLocation;
+}
+export type ApplicationModelNode = ModuleModelNode | ProviderModelNode | ExecutionModelNode | LifecycleModelNode | FrameworkModelNode;
+export interface ApplicationModelEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: 'owns' | 'imports' | 'exports' | 'injects' | 'references' | 'requires' | 'starts' | 'wraps';
+}
+export type CompiledOf<TExtension extends AnyExecutionExtension> = TExtension extends ExecutionExtension<any, infer TCompiled, any, any, any> ? TCompiled : never;
+export interface ApplicationModelExtension<TExtension extends AnyExecutionExtension = AnyExecutionExtension> {
+    readonly extension: TExtension;
+    readonly executions: readonly ExecutionModelNode<CompiledOf<TExtension>>[];
+}
+export interface ApplicationModelExtensions extends Iterable<ApplicationModelExtension> {
+    get<TExtension extends AnyExecutionExtension>(extension: TExtension): ApplicationModelExtension<TExtension> | undefined;
+    values(): readonly ApplicationModelExtension[];
+}
+export interface ApplicationModel {
+    readonly kind: 'application-model';
+    readonly arguments?: ArgsClass;
+    readonly providers: readonly ProviderDescriptor[];
+    readonly nodes: readonly ApplicationModelNode[];
+    readonly edges: readonly ApplicationModelEdge[];
+    readonly executions: readonly ExecutionModelNode[];
+    readonly extensions: ApplicationModelExtensions;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ApplicationModelBuildOptions {
+    readonly modules: readonly (ModuleInstance | ModuleTemplate<void>)[];
+    readonly arguments?: ArgsClass;
+}

package/dist/core/model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/model/validation.d.ts

@@ -0,0 +1,4 @@
+import { type Diagnostic } from '../diagnostic.js';
+import type { ApplicationModelExtension, ApplicationModelNode } from './types.js';
+export declare function validateHostNamespaces(extensions: readonly ApplicationModelExtension[], diagnostics: Diagnostic[]): void;
+export declare function validateNodeIds(nodes: readonly ApplicationModelNode[], diagnostics: Diagnostic[]): void;

package/dist/core/model/validation.js

@@ -0,0 +1,40 @@
+import { diagnostic } from '../diagnostic.js';
+export function validateHostNamespaces(extensions, diagnostics) {
+    const reserved = new Set([
+        'graph',
+        'init',
+        'get',
+        'close',
+        'serve',
+        'then',
+        '__proto__',
+        'prototype',
+        'constructor',
+    ]);
+    const owners = new Map();
+    for (const { extension } of extensions) {
+        const namespace = extension.host?.namespace;
+        if (!namespace)
+            continue;
+        if (reserved.has(namespace)) {
+            diagnostics.push(diagnostic('LUTRE_HOST_NAMESPACE_RESERVED', `Host namespace ${namespace} is reserved by the Application or runtime adapter API.`, `host.${namespace}`));
+            continue;
+        }
+        const owner = owners.get(namespace);
+        if (owner && owner.identity !== extension.identity) {
+            diagnostics.push(diagnostic('LUTRE_HOST_NAMESPACE_COLLISION', `Host namespace ${namespace} is contributed by both ${owner.name} and ${extension.name}.`, `host.${namespace}`));
+            continue;
+        }
+        owners.set(namespace, extension);
+    }
+}
+export function validateNodeIds(nodes, diagnostics) {
+    const seen = new Set();
+    for (const node of nodes) {
+        if (!seen.has(node.id)) {
+            seen.add(node.id);
+            continue;
+        }
+        diagnostics.push(diagnostic('LUTRE_APPLICATION_NODE_ID_COLLISION', `Application Model node id ${node.id} is not globally unique.`, node.id));
+    }
+}

package/dist/core/model/visibility.d.ts

@@ -0,0 +1,4 @@
+import { type ModuleInstance } from '../module.js';
+import type { TokenLike } from '../token.js';
+export declare function moduleDeclaresToken(module: ModuleInstance, token: TokenLike): boolean;
+export declare function isTokenVisible(source: ModuleInstance, target: ModuleInstance, token: TokenLike, visited?: Set<ModuleInstance<import("../module.js").ModuleDefinition>>): boolean;

package/dist/core/model/visibility.js

@@ -0,0 +1,20 @@
+import { asModuleInstance } from '../module.js';
+import { normalizeProvider } from '../provider.js';
+export function moduleDeclaresToken(module, token) {
+    return (module.definition.providers ?? []).some((declaration) => normalizeProvider(declaration).provide === token);
+}
+export function isTokenVisible(source, target, token, visited = new Set()) {
+    if (visited.has(source))
+        return false;
+    visited.add(source);
+    for (const importedValue of source.definition.imports ?? []) {
+        const imported = asModuleInstance(importedValue);
+        if (!imported.definition.exports?.includes(token))
+            continue;
+        if (imported === target)
+            return true;
+        if (isTokenVisible(imported, target, token, new Set(visited)))
+            return true;
+    }
+    return false;
+}

package/dist/core/model.d.ts

@@ -0,0 +1,10 @@
+import { type Diagnostic } from './diagnostic.js';
+import type { ApplicationModel, ApplicationModelBuildOptions } from './model/types.js';
+export type { ApplicationModel, ApplicationModelBuildOptions, ApplicationModelEdge, ApplicationModelExtension, ApplicationModelExtensions, ApplicationModelNode, CompiledOf, ExecutionModelNode, FrameworkModelNode, LifecycleModelNode, ModuleModelNode, ProviderModelNode, } from './model/types.js';
+export declare class ApplicationModelError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    readonly code = "LUTRE_APPLICATION_MODEL_INVALID";
+    constructor(diagnostics: readonly Diagnostic[]);
+}
+export declare function assertValidApplicationModel(model: ApplicationModel): ApplicationModel;
+export declare function buildApplicationModel(options: ApplicationModelBuildOptions): ApplicationModel;