@loutrejs/loutre 0.2.0 → 0.4.0

package/dist/core/contract.js

@@ -1,15 +1,64 @@
-export function procedure(definition) {
-    return { kind: 'procedure', protocols: definition.protocols };
+export function protocolGroup(protocol, procedures) {
+    return Object.freeze({
+        kind: 'protocol-group',
+        protocol,
+        procedures: Object.freeze({ ...procedures }),
+    });
 }
-export function contract(procedures, options = {}) {
-    assertUniqueDispatchKeys(procedures, options.name);
-    return {
+function defineContract(groups) {
+    if (groups.length === 0) {
+        throw new Error('contract([]) requires at least one protocol group');
+    }
+    const procedures = {};
+    for (const group of groups) {
+        for (const [procedureName, descriptor] of Object.entries(group.procedures)) {
+            const current = procedures[procedureName];
+            if (Object.hasOwn(current?.protocols ?? {}, group.protocol)) {
+                throw new Error(`Duplicate contract procedure protocol: ${procedureName}.${group.protocol}`);
+            }
+            procedures[procedureName] = {
+                kind: 'procedure',
+                protocols: {
+                    ...current?.protocols,
+                    [group.protocol]: descriptor,
+                },
+            };
+        }
+    }
+    assertUniqueDispatchKeys(procedures);
+    return Object.freeze({
+        kind: 'contract',
+        procedures: Object.freeze(procedures),
+    });
+}
+function mergeContracts(contracts) {
+    if (contracts.length === 0) {
+        throw new Error('contract.merge([]) requires at least one Contract');
+    }
+    const procedures = {};
+    for (const source of contracts) {
+        for (const [procedureName, procedureDefinition] of Object.entries(source.procedures)) {
+            const current = procedures[procedureName];
+            const protocols = { ...current?.protocols };
+            for (const [protocolName, descriptor] of Object.entries(procedureDefinition.protocols)) {
+                if (Object.hasOwn(protocols, protocolName)) {
+                    throw new Error(`Duplicate contract procedure protocol: ${procedureName}.${protocolName}`);
+                }
+                protocols[protocolName] = descriptor;
+            }
+            procedures[procedureName] = { kind: 'procedure', protocols };
+        }
+    }
+    assertUniqueDispatchKeys(procedures);
+    return Object.freeze({
         kind: 'contract',
-        ...(options.name === undefined ? {} : { name: options.name }),
-        procedures,
-    };
+        procedures: Object.freeze(procedures),
+    });
 }
-function assertUniqueDispatchKeys(procedures, contractName) {
+export const contract = Object.assign(defineContract, {
+    merge: mergeContracts,
+});
+function assertUniqueDispatchKeys(procedures) {
     const paths = new Map();
     for (const [procedureName, procedureDefinition] of Object.entries(procedures)) {
         for (const [protocolName, protocol] of Object.entries(procedureDefinition.protocols)) {
@@ -19,7 +68,7 @@ function assertUniqueDispatchKeys(procedures, contractName) {
             if (typeof dispatchKey !== 'string') {
                 throw new Error(`Protocol dispatchKey must be a string or null: ${procedureName}.${protocolName}`);
             }
-            const path = `${contractName ?? 'Contract'}.${procedureName}.${protocolName}`;
+            const path = `${procedureName}.${protocolName}`;
             const existing = paths.get(dispatchKey);
             if (existing) {
                 throw new Error(`Duplicate protocol dispatch key "${dispatchKey}" between ${existing} and ${path}`);

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const LOUTRE_VERSION = "0.2.0";
+export declare const LOUTRE_VERSION = "0.4.0";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // package manifestとのずれを避けるため、scripts/generate-version.mjsがbuild前に更新する。
-export const LOUTRE_VERSION = '0.2.0';
+export const LOUTRE_VERSION = '0.4.0';

package/dist/graph/compiler.d.ts

@@ -0,0 +1,4 @@
+import { type ApplicationCompilationInput } from './graph.js';
+import type { CompilationResult } from './ir.js';
+export declare function compileApplication(input: ApplicationCompilationInput): CompilationResult;
+export declare const buildApplicationGraph: typeof compileApplication;

package/dist/graph/compiler.js

@@ -0,0 +1,228 @@
+import { asModuleInstance, normalizeProvider, tokenName, } from '../core/index.js';
+import { compileApplication as compileBaseApplication, } from './graph.js';
+export function compileApplication(input) {
+    const base = compileBaseApplication(input);
+    const modules = collectModules(input.modules);
+    const moduleIds = new Map(modules.map((module, index) => [module, `module:${index + 1}`]));
+    const implementationModules = collectImplementationModules(modules, moduleIds);
+    const implementationNames = new Map(base.graph.implementations.map((implementation) => [
+        implementation.id,
+        implementation.name,
+    ]));
+    const graphModules = new Map(base.graph.modules.map((module) => [module.id, module]));
+    const executionModules = new Map();
+    for (const execution of base.graph.executions) {
+        if (execution.kind !== 'protocol')
+            continue;
+        const implementationName = implementationNames.get(execution.implementation);
+        const module = implementationName
+            ? implementationModules.get(implementationName)
+            : undefined;
+        if (!module)
+            continue;
+        executionModules.set(`${execution.contract}:${execution.procedure}:${execution.protocol}`, module);
+    }
+    const providerModules = collectProviderModules(modules, moduleIds);
+    const nodes = base.graph.nodes.map((node) => {
+        const module = node.module ??
+            providerModules.get(node.label) ??
+            moduleForImplementation(node, implementationModules) ??
+            moduleForLifecycle(node) ??
+            moduleForLayer(node, executionModules);
+        if (!module)
+            return node;
+        const owner = graphModules.get(module);
+        if (!owner)
+            return node;
+        return {
+            ...node,
+            module,
+            visibility: owner.exports.includes(node.label) ? 'exported' : 'private',
+        };
+    });
+    const diagnostics = [
+        ...base.diagnostics,
+        ...validateModuleExports(base.graph.modules),
+        ...validateModuleVisibility(base.graph, nodes),
+    ];
+    const graph = {
+        ...base.graph,
+        nodes,
+        diagnostics,
+    };
+    return { graph, diagnostics };
+}
+export const buildApplicationGraph = compileApplication;
+function collectModules(roots) {
+    const modules = [];
+    const seen = new Set();
+    const visit = (candidate) => {
+        const module = asModuleInstance(candidate);
+        if (seen.has(module))
+            return;
+        seen.add(module);
+        for (const imported of module.definition.imports ?? [])
+            visit(imported);
+        modules.push(module);
+    };
+    for (const root of roots)
+        visit(root);
+    return modules;
+}
+function collectProviderModules(modules, moduleIds) {
+    const result = new Map();
+    const ambiguous = new Set();
+    for (const module of modules) {
+        const moduleId = moduleIds.get(module);
+        if (!moduleId)
+            continue;
+        for (const declaration of module.definition.providers ?? []) {
+            const provider = normalizeProvider(declaration);
+            const labels = [
+                tokenName(provider.provide),
+                ...(provider.kind === 'class' ? [provider.useClass.name] : []),
+                ...(provider.kind === 'conditional'
+                    ? Reflect.ownKeys(provider.mapping).flatMap((key) => {
+                        const candidate = provider.mapping[key];
+                        return candidate ? [candidate.name] : [];
+                    })
+                    : []),
+            ];
+            for (const label of labels) {
+                const current = result.get(label);
+                if (current && current !== moduleId)
+                    ambiguous.add(label);
+                else
+                    result.set(label, moduleId);
+            }
+        }
+    }
+    for (const label of ambiguous)
+        result.delete(label);
+    return result;
+}
+function collectImplementationModules(modules, moduleIds) {
+    const result = new Map();
+    const ambiguous = new Set();
+    for (const module of modules) {
+        const moduleId = moduleIds.get(module);
+        if (!moduleId)
+            continue;
+        for (const implementation of module.definition.implementations ?? []) {
+            const current = result.get(implementation.name);
+            if (current && current !== moduleId)
+                ambiguous.add(implementation.name);
+            else
+                result.set(implementation.name, moduleId);
+        }
+    }
+    for (const name of ambiguous)
+        result.delete(name);
+    return result;
+}
+function moduleForImplementation(node, modules) {
+    return node.kind === 'implementation' ? modules.get(node.label) : undefined;
+}
+function moduleForLifecycle(node) {
+    if (node.kind !== 'framework' || !node.id.startsWith('lifecycle:module:')) {
+        return undefined;
+    }
+    const match = /^lifecycle:(module:\d+):/.exec(node.id);
+    return match?.[1];
+}
+function moduleForLayer(node, executionModules) {
+    if (node.kind !== 'layer')
+        return undefined;
+    const match = /^layer:(contract:\d+)\/([^/]+)\/([^/]+)\//.exec(node.id);
+    if (!match)
+        return undefined;
+    const [, contract, procedure, protocol] = match;
+    return executionModules.get(`${contract}:${procedure}:${protocol}`);
+}
+function validateModuleExports(modules) {
+    const byId = new Map(modules.map((module) => [module.id, module]));
+    return modules.flatMap((module) => module.exports.flatMap((token) => declaresToken(module, token) ||
+        canResolveExport(module, token, byId, new Set())
+        ? []
+        : [
+            {
+                code: 'LUTRE_MODULE_EXPORT_UNRESOLVED',
+                message: `${describeModule(module)} exports ${token}, but the token is neither declared nor re-exported from an imported Module.`,
+                path: `${module.id}.exports.${token}`,
+            },
+        ]));
+}
+function declaresToken(module, token) {
+    return module.providers.includes(token) || module.environment.includes(token);
+}
+function canResolveExport(source, token, modules, visited) {
+    if (visited.has(source.id))
+        return false;
+    visited.add(source.id);
+    for (const importedId of source.imports) {
+        const imported = modules.get(importedId);
+        if (!imported || !imported.exports.includes(token))
+            continue;
+        if (declaresToken(imported, token))
+            return true;
+        if (canResolveExport(imported, token, modules, new Set(visited)))
+            return true;
+    }
+    return false;
+}
+function validateModuleVisibility(graph, nodes) {
+    const modules = new Map(graph.modules.map((module) => [module.id, module]));
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    const seen = new Set();
+    const diagnostics = [];
+    for (const edge of graph.edges) {
+        const consumer = nodesById.get(edge.from);
+        const dependency = nodesById.get(edge.to);
+        if (!consumer?.module ||
+            !dependency?.module ||
+            consumer.module === dependency.module ||
+            !modules.has(consumer.module) ||
+            !modules.has(dependency.module)) {
+            continue;
+        }
+        const key = `${consumer.id}->${dependency.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (isTokenVisibleFrom(consumer.module, dependency.module, dependency.label, modules)) {
+            continue;
+        }
+        diagnostics.push({
+            code: 'LUTRE_MODULE_VISIBILITY',
+            message: `${consumer.label} in ${describeModuleId(consumer.module, modules)} depends on private ${dependency.label} from ${describeModuleId(dependency.module, modules)}. Export the dependency and import its Module explicitly.`,
+            path: consumer.id,
+        });
+    }
+    return diagnostics;
+}
+function isTokenVisibleFrom(sourceId, targetId, token, modules, visited = new Set()) {
+    if (visited.has(sourceId))
+        return false;
+    visited.add(sourceId);
+    const source = modules.get(sourceId);
+    if (!source)
+        return false;
+    for (const importedId of source.imports) {
+        const imported = modules.get(importedId);
+        if (!imported || !imported.exports.includes(token))
+            continue;
+        if (importedId === targetId)
+            return true;
+        if (isTokenVisibleFrom(importedId, targetId, token, modules, new Set(visited))) {
+            return true;
+        }
+    }
+    return false;
+}
+function describeModule(module) {
+    return module.name ?? module.description ?? module.id;
+}
+function describeModuleId(id, modules) {
+    const module = modules.get(id);
+    return module ? describeModule(module) : id;
+}

package/dist/graph/graph.js

@@ -38,17 +38,29 @@ export function compileApplication(input) {
     validateNamedDescriptors(queues, 'LUTRE_QUEUE_DUPLICATE', diagnostics);
     validateCronTriggers(triggers, diagnostics);
     diagnostics.push(...validateQueueDrivers(input.modules, queueTriggers));
-    const contractNames = new Map();
-    let contractSequence = 0;
-    const nameContract = (contract) => {
-        const current = contractNames.get(contract);
+    const contractIds = new Map();
+    const idContract = (contract) => {
+        const current = contractIds.get(contract);
         if (current)
             return current;
-        const name = contract.name ?? `Contract${++contractSequence}`;
-        contractNames.set(contract, name);
-        return name;
+        const id = `contract:${contractIds.size + 1}`;
+        contractIds.set(contract, id);
+        return id;
+    };
+    const implementationIds = new Map();
+    const idImplementation = (implementation) => {
+        const current = implementationIds.get(implementation);
+        if (current)
+            return current;
+        const id = `implementation:${implementationIds.size + 1}`;
+        implementationIds.set(implementation, id);
+        return id;
     };
     const descriptors = modules.flatMap((module) => module.definition.implementations ?? []);
+    for (const implementation of new Set(descriptors)) {
+        idContract(implementation.contract);
+        idImplementation(implementation);
+    }
     const targets = [];
     for (const implementation of descriptors) {
         for (const procedureName of implementation.procedures) {
@@ -58,13 +70,14 @@ export function compileApplication(input) {
                 diagnostics.push({
                     code: 'LUTRE_IMPL_003',
                     message: `${procedureName} is not declared for protocol ${implementation.protocol}`,
-                    path: `${nameContract(implementation.contract)}.${procedureName}.${implementation.protocol}`,
+                    path: `${idContract(implementation.contract)}.${procedureName}.${implementation.protocol}`,
                 });
                 continue;
             }
             targets.push({
                 implementation,
-                contractName: nameContract(implementation.contract),
+                contractId: idContract(implementation.contract),
+                implementationId: idImplementation(implementation),
                 procedure: procedureName,
                 protocol: implementation.protocol,
                 dispatchKey: protocol.dispatchKey,
@@ -77,28 +90,27 @@ export function compileApplication(input) {
         }
     }
     validateDispatchKeys(targets, diagnostics);
-    validateCoverage(descriptors, contractNames, diagnostics);
+    validateCoverage(descriptors, contractIds, diagnostics);
     validateDuplicateProviders(modules, diagnostics);
     const tokensById = collectCustomTokens(providers, targets, diagnostics);
     const contextKeysByName = collectContextKeys(targets, diagnostics);
     const pipelines = [];
-    const implementations = [];
     for (const target of targets) {
         validatePipeline(target, diagnostics);
         pipelines.push({
-            contract: target.contractName,
+            contract: target.contractId,
             procedure: target.procedure,
             protocol: target.protocol,
             layers: target.pipeline.map(toLayerIR),
         });
-        implementations.push({
-            contract: target.contractName,
-            procedure: target.procedure,
-            protocol: target.protocol,
-            implementation: target.implementation.name,
-            method: target.procedure,
-        });
     }
+    const implementations = [...new Set(descriptors)].map((implementation) => ({
+        id: idImplementation(implementation),
+        name: implementation.name,
+        contract: idContract(implementation.contract),
+        protocol: implementation.protocol,
+        procedures: implementation.procedures,
+    }));
     const dependencyGraph = buildDependencyGraph(modules, descriptors, targets, tasks, diagnostics);
     const probedTokenIds = dependencyGraph.nodes
         .filter((node) => node.kind === 'token')
@@ -150,7 +162,7 @@ export function compileApplication(input) {
         })),
         tokens: [...new Set([...tokensById.keys(), ...probedTokenIds])].map((id) => ({ id })),
         contextKeys: [...contextKeysByName.keys()].map((name) => ({ name })),
-        contracts: [...contractNames.values()],
+        contracts: [...contractIds.entries()].map(([contract, id]) => toContractIR(contract, id)),
         pipelines,
         implementations,
         tasks: tasks.map((task) => ({
@@ -161,12 +173,12 @@ export function compileApplication(input) {
         queues: queues.map(toQueueIR),
         executions: [
             ...targets.map((target) => ({
-                id: `protocol:${target.protocol}:${target.contractName}.${target.procedure}`,
+                id: `protocol:${target.contractId}:${target.procedure}:${target.protocol}`,
                 kind: 'protocol',
                 protocol: target.protocol,
-                contract: target.contractName,
+                contract: target.contractId,
                 procedure: target.procedure,
-                implementation: target.implementation.name,
+                implementation: target.implementationId,
             })),
             ...publicTasks.map((task) => ({
                 id: `task:${task.name}`,
@@ -177,7 +189,7 @@ export function compileApplication(input) {
         ],
         capabilities: [
             ...targets.flatMap((target) => {
-                const requiredBy = `${target.contractName}.${target.procedure}`;
+                const requiredBy = `${target.contractId}.${target.procedure}`;
                 return [
                     { name: 'crypto.random', scope: 'execution', requiredBy },
                     ...(target.protocol === 'http'
@@ -257,7 +269,7 @@ function validateDispatchKeys(targets, diagnostics) {
     for (const target of targets) {
         if (target.dispatchKey === null)
             continue;
-        const path = `${target.contractName}.${target.procedure}.${target.protocol}`;
+        const path = `${target.contractId}.${target.procedure}.${target.protocol}`;
         const existing = targetsByKey.get(target.dispatchKey);
         if (existing) {
             if (existing.implementation.contract === target.implementation.contract &&
@@ -265,7 +277,7 @@ function validateDispatchKeys(targets, diagnostics) {
                 existing.protocol === target.protocol) {
                 continue;
             }
-            const existingPath = `${existing.contractName}.${existing.procedure}.${existing.protocol}`;
+            const existingPath = `${existing.contractId}.${existing.procedure}.${existing.protocol}`;
             diagnostics.push({
                 code: 'LUTRE_PROTOCOL_001',
                 message: `Duplicate protocol dispatch key "${target.dispatchKey}": ${existingPath}, ${path}`,
@@ -736,7 +748,7 @@ function buildDependencyGraph(modules, descriptors, targets, tasks, diagnostics)
             const definition = layerDefinitionOf(item);
             const consumer = {
                 kind: 'layer-consumer',
-                id: `layer:${target.contractName}:${target.procedure}:${target.protocol}:${indexPath.join('.')}`,
+                id: `layer:${target.contractId}/${target.procedure}/${target.protocol}/${indexPath.join('.')}`,
                 name: definition.name,
             };
             if (!nodes.some(({ id }) => id === consumer.id)) {
@@ -847,7 +859,7 @@ function collectCustomTokens(providers, targets, diagnostics) {
 function collectContextKeys(targets, diagnostics) {
     const keys = new Map();
     for (const target of targets) {
-        const path = `${target.contractName}.${target.procedure}.${target.protocol}`;
+        const path = `${target.contractId}.${target.procedure}.${target.protocol}`;
         visitPipelineItems(target.pipeline, (item) => {
             if (item.kind !== 'layer')
                 return;
@@ -867,6 +879,19 @@ function collectContextKeys(targets, diagnostics) {
     }
     return keys;
 }
+function toContractIR(contract, id) {
+    return {
+        id,
+        procedures: Object.entries(contract.procedures).map(([procedureName, procedure]) => ({
+            name: procedureName,
+            protocols: Object.entries(procedure.protocols).map(([protocolName, protocol]) => ({
+                name: protocolName,
+                dispatchKey: protocol.dispatchKey,
+                interaction: protocol.interaction ?? 'unary',
+            })),
+        })),
+    };
+}
 export function assertValidCompilation(result) {
     if (result.diagnostics.length > 0) {
         throw new StaticValidationError(result.diagnostics, result.graph);
@@ -889,7 +914,7 @@ function collectModules(roots) {
         visit(root);
     return modules;
 }
-function validateCoverage(implementations, contractNames, diagnostics) {
+function validateCoverage(implementations, contractIds, diagnostics) {
     const contracts = new Set(implementations.map((implementation) => implementation.contract));
     for (const contract of contracts) {
         const protocols = new Set(Object.values(contract.procedures).flatMap((procedure) => Object.keys(procedure.protocols)));
@@ -900,7 +925,7 @@ function validateCoverage(implementations, contractNames, diagnostics) {
                 const covering = implementations.filter((implementation) => implementation.contract === contract &&
                     implementation.protocol === protocol &&
                     implementation.procedures.includes(procedureName));
-                const path = `${contractNames.get(contract) ?? 'Contract'}.${procedureName}.${protocol}`;
+                const path = `${contractIds.get(contract) ?? 'contract:unknown'}.${procedureName}.${protocol}`;
                 if (covering.length === 0) {
                     diagnostics.push({
                         code: 'LUTRE_IMPL_001',
@@ -920,7 +945,7 @@ function validateCoverage(implementations, contractNames, diagnostics) {
     }
 }
 function validatePipeline(target, diagnostics) {
-    const path = `${target.contractName}.${target.procedure}.${target.protocol}`;
+    const path = `${target.contractId}.${target.procedure}.${target.protocol}`;
     const flattened = [];
     visitPipelineItems(target.pipeline, (item, indexPath) => {
         flattened.push({ item, indexPath });

package/dist/graph/index.d.ts

@@ -1,2 +1,3 @@
 export * from './ir.js';
-export * from './graph.js';
+export { StaticValidationError, assertValidCompilation, validateGraph, type ApplicationCompilationInput, } from './graph.js';
+export { buildApplicationGraph, compileApplication } from './compiler.js';

package/dist/graph/index.js

@@ -1,2 +1,3 @@
 export * from './ir.js';
-export * from './graph.js';
+export { StaticValidationError, assertValidCompilation, validateGraph, } from './graph.js';
+export { buildApplicationGraph, compileApplication } from './compiler.js';

package/dist/graph/ir.d.ts

@@ -21,6 +21,7 @@ export interface DependencyNodeIR {
     readonly kind: 'class' | 'token' | 'factory' | 'conditional' | 'environment' | 'arguments' | 'implementation' | 'layer' | 'task' | 'framework';
     readonly scope?: 'application' | 'transient';
     readonly module?: string;
+    readonly visibility?: 'private' | 'exported';
 }
 export interface DependencyEdgeIR {
     readonly from: string;
@@ -57,18 +58,33 @@ export interface LayerIR {
         readonly response?: Readonly<Record<string, unknown>>;
     }[];
 }
+export type ContractId = `contract:${number}`;
+export type ImplementationId = `implementation:${number}`;
+export interface ContractProtocolIR {
+    readonly name: string;
+    readonly dispatchKey: string | null;
+    readonly interaction: string;
+}
+export interface ContractProcedureIR {
+    readonly name: string;
+    readonly protocols: readonly ContractProtocolIR[];
+}
+export interface ContractIR {
+    readonly id: ContractId;
+    readonly procedures: readonly ContractProcedureIR[];
+}
 export interface PipelineIR {
-    readonly contract: string;
+    readonly contract: ContractId;
     readonly procedure: string;
     readonly protocol: string;
     readonly layers: readonly LayerIR[];
 }
 export interface ImplementationIR {
-    readonly contract: string;
-    readonly procedure: string;
+    readonly id: ImplementationId;
+    readonly name: string;
+    readonly contract: ContractId;
     readonly protocol: string;
-    readonly implementation: string;
-    readonly method: string;
+    readonly procedures: readonly string[];
 }
 export interface CapabilityIR {
     readonly name: string;
@@ -79,9 +95,9 @@ export interface ProtocolExecutionRootIR {
     readonly id: `protocol:${string}`;
     readonly kind: 'protocol';
     readonly protocol: string;
-    readonly contract: string;
+    readonly contract: ContractId;
     readonly procedure: string;
-    readonly implementation: string;
+    readonly implementation: ImplementationId;
 }
 export interface ApplicationArgumentsIR {
     readonly name: string;
@@ -136,7 +152,7 @@ export interface ApplicationGraphIR {
     readonly providers: readonly ProviderIR[];
     readonly tokens: readonly TokenIR[];
     readonly contextKeys: readonly ContextKeyIR[];
-    readonly contracts: readonly string[];
+    readonly contracts: readonly ContractIR[];
     readonly pipelines: readonly PipelineIR[];
     readonly implementations: readonly ImplementationIR[];
     readonly tasks: readonly TaskIR[];