@bleedingdev/modern-js-code-tools 3.9.0-ultramodern.9 → 3.9.3-ultramodern.10

package/dist/esm-node/microvertical-api-boundary.js

@@ -2,8 +2,10 @@ import "node:module";
 import node_fs from "node:fs";
 import node_path from "node:path";
 import { parse } from "@babel/parser";
-import { configuredMicroVerticalApiStem, consumerParserPlugins, microVerticalApiBaselineViolation } from "./microvertical-api-baseline.js";
+import { camelCaseStem, configuredMicroVerticalApiStem, microVerticalApiBaselineViolation, pascalCaseStem } from "./microvertical-api-baseline.js";
 import { baselinePackage, resolveBaselinePackageDirectory } from "./microvertical-api-owner.js";
+import { createModuleGraph } from "./module-graph.js";
+import { SourceSyntaxError, consumerParserPlugins, unwrapExpression } from "./source-analysis.js";
 import { createEffectApiImportResolver, strictEffectRuntimeTopologyViolation } from "./strict-effect-runtime.js";
 import * as __rspack_external__babel_types_6e8337dd from "@babel/types";
 const ignored = new Set([
@@ -16,17 +18,54 @@ const ignored = new Set([
     'node_modules',
     'repos'
 ]);
+const MAX_CLOSURE_DEPTH = 128;
+const MAX_CLOSURE_MODULES = 2048;
+const MAX_API_HOPS = 128;
+const MAX_API_VISITS = 2048;
+const identitySources = [
+    'effect',
+    'effect/Function'
+];
 const normalize = (file)=>file.split(node_path.sep).join('/').replace(/^\.\//u, '');
 const errorMessage = (error)=>error instanceof Error ? error.message : String(error);
 const apiApp = (app)=>'vertical' === app.kind && 'ui-only' !== app.surfaceProfile && 'horizontal-remote' !== app.deliveryUnitKind;
 function configuredApps(root, supplied) {
-    const source = supplied ?? JSON.parse(node_fs.readFileSync(node_path.join(root, '.modernjs/ultramodern.json'), 'utf8')).topology?.apps;
-    if (!Array.isArray(source)) throw new Error('.modernjs/ultramodern.json: topology.apps must be an array');
+    const topology = supplied ? void 0 : JSON.parse(node_fs.readFileSync(node_path.join(root, 'topology/reference-topology.json'), 'utf8'));
+    if (topology && (!topology.shell || !Array.isArray(topology.verticals) || void 0 !== topology.shells && !Array.isArray(topology.shells))) throw new Error('topology/reference-topology.json: shell and verticals must be present');
+    const entries = topology?.shell ? [
+        topology.shell,
+        ...topology.shells ?? [],
+        ...topology.verticals ?? []
+    ] : void 0;
+    const source = supplied ?? entries?.map((entry)=>{
+        if (!entry || 'string' != typeof entry.path || !entry.path || node_path.isAbsolute(entry.path) || entry.path.split(/[\\/]/u).includes('..')) throw new Error('topology/reference-topology.json: each app must have an explicit workspace path');
+        const packageFile = node_path.join(root, entry.path, 'package.json');
+        const manifest = JSON.parse(node_fs.readFileSync(packageFile, 'utf8'));
+        if ('string' != typeof manifest.name || !manifest.name || void 0 !== entry.package && entry.package !== manifest.name) throw new Error(`${entry.path}/package.json: package name must match topology`);
+        const api = entry.api;
+        const stem = api?.stem ?? api?.readiness?.endpoint?.match(/^\/([a-z0-9]+(?:-[a-z0-9]+)*)\/readiness$/u)?.[1];
+        return {
+            id: entry.id,
+            kind: entry.kind,
+            path: entry.path,
+            package: manifest.name,
+            surfaceProfile: entry.surfaceProfile,
+            deliveryUnitKind: entry.deliveryUnitKind,
+            ...void 0 === api ? {} : {
+                api: {
+                    stem,
+                    prefix: api.bff?.prefix,
+                    protocol: api.protocol
+                }
+            }
+        };
+    });
+    if (!Array.isArray(source)) throw new Error('topology/reference-topology.json: shell and verticals must describe apps');
     const paths = new Set();
     for (const app of source){
-        if (!app || 'object' != typeof app || 'string' != typeof app.path || !app.path || node_path.isAbsolute(app.path) || app.path.split(/[\\/]/u).includes('..')) throw new Error('.modernjs/ultramodern.json: each app must have a relative workspace path');
+        if (!app || 'object' != typeof app || 'string' != typeof app.path || !app.path || node_path.isAbsolute(app.path) || app.path.split(/[\\/]/u).includes('..')) throw new Error('topology/reference-topology.json: each app must have a relative workspace path');
         const key = normalize(app.path);
-        if (paths.has(key)) throw new Error(`.modernjs/ultramodern.json: duplicate app path ${key}`);
+        if (paths.has(key)) throw new Error(`topology/reference-topology.json: duplicate app path ${key}`);
         paths.add(key);
         for (const name of [
             'id',
@@ -35,7 +74,7 @@ function configuredApps(root, supplied) {
             'surfaceProfile',
             'deliveryUnitKind'
         ])if (void 0 !== app[name] && 'string' != typeof app[name]) throw new Error(`${key}: ${name} must be a string`);
-        for (const [field, allowed] of Object.entries({
+        const allowedFields = {
             kind: [
                 'shell',
                 'vertical'
@@ -49,7 +88,11 @@ function configuredApps(root, supplied) {
                 'microvertical',
                 'horizontal-remote'
             ]
-        }))if (void 0 !== app[field] && !allowed.includes(app[field])) throw new Error(`${key}: invalid ${field}`);
+        };
+        for (const field of Object.keys(allowedFields)){
+            const value = app[field];
+            if ((void 0 !== value || 'kind' === field) && ('string' != typeof value || !allowedFields[field].includes(value))) throw new Error(`${key}: invalid ${field}`);
+        }
         if (void 0 !== app.api) {
             if (!app.api || 'object' != typeof app.api || Array.isArray(app.api)) throw new Error(`${key}: api must be an object`);
             if (void 0 !== app.api.protocol && ![
@@ -90,6 +133,9 @@ function check(options, topology) {
     };
     try {
         const apps = configuredApps(root, options.configuredApps);
+        const workspace = node_fs.realpathSync(root);
+        const realRelative = (file)=>normalize(node_path.relative(workspace, node_fs.realpathSync(absolute(file))));
+        const inside = (directory, real)=>real.startsWith(`${directory}${node_path.sep}`);
         const byPath = new Map(apps.map((app)=>[
                 normalize(app.path),
                 app
@@ -130,39 +176,244 @@ function check(options, topology) {
         const resolveRelative = (fromFile, specifier)=>{
             if (!/^\.\.?\//u.test(specifier)) return;
             const base = node_path.posix.join(node_path.posix.dirname(fromFile), specifier).replace(/\.(?:[cm]?[jt]sx?)$/u, '');
-            return [
+            const candidate = [
                 `${base}.ts`,
                 `${base}.tsx`,
                 `${base}/index.ts`,
                 `${base}/index.tsx`
-            ].find((candidate)=>exists(candidate));
+            ].find((file)=>exists(file));
+            return void 0 === candidate ? void 0 : realRelative(candidate);
+        };
+        const graphBinding = (graph, module, expression, seen = new Set())=>{
+            if (seen.has(expression) || seen.size >= 128) return;
+            seen.add(expression);
+            const binding = __rspack_external__babel_types_6e8337dd.isIdentifier(expression) || __rspack_external__babel_types_6e8337dd.isMemberExpression(expression) ? graph.resolveReference(module, expression) : void 0;
+            return binding?.kind === 'declaration' && (__rspack_external__babel_types_6e8337dd.isIdentifier(binding.expression) || __rspack_external__babel_types_6e8337dd.isMemberExpression(binding.expression)) ? graphBinding(graph, binding.module, binding.expression, seen) : binding;
+        };
+        const clientExportFile = (appPath, exported)=>{
+            if ('string' != typeof exported || !exported.startsWith('./') || exported.split(/[\\/]/u).includes('..') || !/\.[cm]?[jt]sx?$/u.test(exported)) return;
+            const appDirectory = absolute(appPath);
+            const candidate = node_path.resolve(appDirectory, exported);
+            try {
+                const workspace = node_fs.realpathSync(root);
+                const owner = node_fs.realpathSync(appDirectory);
+                const real = node_fs.realpathSync(candidate);
+                if (!owner.startsWith(`${workspace}${node_path.sep}`) || !real.startsWith(`${owner}${node_path.sep}`) || !node_fs.statSync(real).isFile()) return;
+            } catch  {
+                return;
+            }
+            return normalize(node_path.relative(root, candidate));
         };
-        const composedModules = (file)=>{
-            const order = [];
-            const seen = new Set();
+        const composedModules = (file, appPath)=>{
+            const owner = node_fs.realpathSync(absolute(appPath));
+            if (!inside(owner, node_fs.realpathSync(absolute(file)))) throw new Error(`consumer module closure escapes its owner: ${file}`);
+            const entry = realRelative(file);
+            const discovered = new Set([
+                entry
+            ]);
             const queue = [
-                file
+                {
+                    file: entry,
+                    depth: 0
+                }
             ];
-            while(queue.length > 0 && order.length < 128){
-                const current = queue.shift();
-                if (seen.has(current)) continue;
-                seen.add(current);
-                order.push(current);
+            let graph;
+            for (const { file: current, depth } of queue){
                 const ast = parseFile(current);
                 if (!ast) continue;
-                for (const statement of ast.program.body){
-                    const source = (__rspack_external__babel_types_6e8337dd.isImportDeclaration(statement) || __rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(statement) || __rspack_external__babel_types_6e8337dd.isExportAllDeclaration(statement)) && statement.source ? statement.source.value : void 0;
-                    const resolved = void 0 === source ? void 0 : resolveRelative(current, source);
-                    if (void 0 !== resolved && !seen.has(resolved)) queue.push(resolved);
+                const sources = [];
+                let callsRequire = false;
+                for (const statement of ast.program.body)if (__rspack_external__babel_types_6e8337dd.isImportDeclaration(statement) && 'type' !== statement.importKind && 'typeof' !== statement.importKind || (__rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(statement) || __rspack_external__babel_types_6e8337dd.isExportAllDeclaration(statement)) && 'type' !== statement.exportKind && statement.source) sources.push(statement.source.value);
+                __rspack_external__babel_types_6e8337dd.traverseFast(ast, (node)=>{
+                    if (__rspack_external__babel_types_6e8337dd.isImportExpression(node)) {
+                        if (!__rspack_external__babel_types_6e8337dd.isStringLiteral(node.source)) throw new Error(`consumer module closure has nonliteral runtime dependency: ${current}`);
+                        sources.push(node.source.value);
+                    }
+                    if ((__rspack_external__babel_types_6e8337dd.isCallExpression(node) || __rspack_external__babel_types_6e8337dd.isOptionalCallExpression(node)) && __rspack_external__babel_types_6e8337dd.isIdentifier(unwrapExpression(node.callee, true), {
+                        name: 'require'
+                    })) callsRequire = true;
+                });
+                if (callsRequire) {
+                    graph ??= createModuleGraph();
+                    const module = graph.module(absolute(current));
+                    __rspack_external__babel_types_6e8337dd.traverseFast(module.file, (node)=>{
+                        if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node) && !__rspack_external__babel_types_6e8337dd.isOptionalCallExpression(node)) return;
+                        const callee = unwrapExpression(node.callee, true);
+                        if (!__rspack_external__babel_types_6e8337dd.isIdentifier(callee, {
+                            name: 'require'
+                        }) || !graph.isUnboundReference(module, callee)) return;
+                        const [argument] = node.arguments;
+                        if (1 !== node.arguments.length || !__rspack_external__babel_types_6e8337dd.isStringLiteral(argument)) throw new Error(`consumer module closure has nonliteral runtime dependency: ${current}`);
+                        sources.push(argument.value);
+                    });
+                }
+                for (const source of sources){
+                    if (!/^\.\.?\//u.test(source)) continue;
+                    const resolved = resolveRelative(current, source);
+                    if (void 0 === resolved) throw new Error(`consumer module closure has unresolved relative dependency: ${current} -> ${source}`);
+                    if (!inside(owner, node_path.join(workspace, resolved))) throw new Error(`consumer module closure escapes its owner: ${current} -> ${source}`);
+                    if (!discovered.has(resolved)) {
+                        if (depth + 1 >= MAX_CLOSURE_DEPTH) throw new Error(`consumer module closure exceeds ${MAX_CLOSURE_DEPTH} import-depth analysis budget`);
+                        if (discovered.size >= MAX_CLOSURE_MODULES) throw new Error(`consumer module closure exceeds ${MAX_CLOSURE_MODULES}-module analysis budget`);
+                        discovered.add(resolved);
+                        queue.push({
+                            file: resolved,
+                            depth: depth + 1
+                        });
+                    }
                 }
             }
-            return order;
+            return queue.map((item)=>item.file);
         };
-        const moduleShape = (file, imports, calls, patterns = [], defaultExport, composed = false)=>{
+        const foreignClientConstructions = (client, appPath, contract, stem, rpc)=>{
+            const graph = createModuleGraph();
+            const contractModule = graph.module(absolute(contract));
+            const factory = rpc ? 'makeEffectRpcClient' : 'makeEffectHttpApiClient';
+            const ownExport = graph.resolve(contractModule, rpc ? `${pascalCaseStem(stem)}RpcGroup` : `${camelCaseStem(stem)}Api`, 'export');
+            const isIdentity = (value)=>'external' === value.kind && identitySources.includes(value.specifier) && 'identity' === value.name && 0 === value.members.length;
+            const identityPipe = (module, node)=>{
+                if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node) || !__rspack_external__babel_types_6e8337dd.isMemberExpression(node.callee) || node.callee.computed || !__rspack_external__babel_types_6e8337dd.isIdentifier(node.callee.property, {
+                    name: 'pipe'
+                }) || 1 !== node.arguments.length) return false;
+                const values = graph.evaluate(module, node.arguments[0]);
+                return values.length > 0 && values.every(isIdentity);
+            };
+            const withoutIdentity = (module, value)=>{
+                let node = unwrapExpression(value, true);
+                for(let pipes = 0; identityPipe(module, node); pipes += 1){
+                    if (pipes >= MAX_API_HOPS) return value;
+                    node = unwrapExpression(node.callee.object, true);
+                }
+                return node;
+            };
+            const normalizedApi = (initial)=>{
+                let binding = initial;
+                const seen = new Set();
+                for(let hops = 0; hops < MAX_API_HOPS; hops += 1){
+                    const expression = withoutIdentity(binding.module, binding.expression);
+                    if (seen.has(expression)) break;
+                    seen.add(expression);
+                    if (!__rspack_external__babel_types_6e8337dd.isIdentifier(expression) && !__rspack_external__babel_types_6e8337dd.isMemberExpression(expression)) return {
+                        ...binding,
+                        expression: expression
+                    };
+                    const next = graphBinding(graph, binding.module, expression);
+                    if (next?.kind !== 'declaration') break;
+                    binding = next;
+                }
+            };
+            const apiBinding = (module, value)=>{
+                const binding = graphBinding(graph, module, withoutIdentity(module, value));
+                return binding?.kind === 'declaration' ? normalizedApi(binding) : void 0;
+            };
+            const ownedApis = new Map();
+            const own = (binding)=>{
+                const identities = ownedApis.get(binding.module.path) ?? new Set();
+                identities.add(binding.expression);
+                ownedApis.set(binding.module.path, identities);
+            };
+            const proven = new Set();
+            const active = new Set();
+            let visits = 0;
+            const builtApi = (module, expression)=>{
+                const initial = withoutIdentity(module, expression);
+                if (active.has(initial) || active.size >= MAX_API_HOPS) return false;
+                active.add(initial);
+                try {
+                    const children = [];
+                    for(let node = initial;;){
+                        if (++visits > MAX_API_VISITS) return false;
+                        if (__rspack_external__babel_types_6e8337dd.isIdentifier(node) || __rspack_external__babel_types_6e8337dd.isMemberExpression(node)) {
+                            const receiver = apiBinding(module, node);
+                            if (!receiver || !builtApi(receiver.module, receiver.expression)) return false;
+                            break;
+                        }
+                        if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node)) return false;
+                        const callee = graph.evaluate(module, node.callee);
+                        if (callee.length > 0 && callee.every((value)=>'external' === value.kind && httpApiSources.includes(value.specifier) && 'HttpApi' === value.name && 1 === value.members.length && 'make' === value.members[0])) {
+                            if (1 !== node.arguments.length || !__rspack_external__babel_types_6e8337dd.isStringLiteral(node.arguments[0])) return false;
+                            break;
+                        }
+                        if (!__rspack_external__babel_types_6e8337dd.isMemberExpression(node.callee) || node.callee.computed || !__rspack_external__babel_types_6e8337dd.isIdentifier(node.callee.property)) return false;
+                        const method = node.callee.property.name;
+                        const count = node.arguments.length;
+                        const [first] = node.arguments;
+                        if ('addHttpApi' === method && 1 === count) children.push(first);
+                        else if (!('add' === method && count > 0 || 'annotate' === method && 2 === count || [
+                            'annotateMerge',
+                            'middleware'
+                        ].includes(method) && 1 === count || 'prefix' === method && 1 === count && __rspack_external__babel_types_6e8337dd.isStringLiteral(first) && first.value.startsWith('/'))) return false;
+                        node = withoutIdentity(module, node.callee.object);
+                    }
+                    return children.every((child)=>{
+                        const binding = apiBinding(module, child);
+                        return void 0 !== binding && collectApi(binding);
+                    });
+                } finally{
+                    active.delete(initial);
+                }
+            };
+            const collectApi = (binding)=>{
+                if (proven.has(binding.expression)) return true;
+                if (!builtApi(binding.module, binding.expression)) return false;
+                proven.add(binding.expression);
+                if (binding.module.boundary === contractModule.boundary) own(binding);
+                return true;
+            };
+            if (!rpc && ownExport?.kind === 'declaration') {
+                const root = normalizedApi(ownExport);
+                if (root && collectApi(root)) own(root);
+                else ownedApis.clear();
+            }
+            const immutablePipeAliases = (module, target)=>{
+                if (0 === module.mutations.length) return true;
+                let valid = true;
+                __rspack_external__babel_types_6e8337dd.traverseFast(module.file, (node)=>{
+                    if (!__rspack_external__babel_types_6e8337dd.isVariableDeclarator(node) || !__rspack_external__babel_types_6e8337dd.isIdentifier(node.id) || !node.init) return;
+                    let initializer = unwrapExpression(node.init, true);
+                    let identityOnly = true;
+                    let piped = false;
+                    while(__rspack_external__babel_types_6e8337dd.isCallExpression(initializer) && __rspack_external__babel_types_6e8337dd.isMemberExpression(initializer.callee) && !initializer.callee.computed && __rspack_external__babel_types_6e8337dd.isIdentifier(initializer.callee.property, {
+                        name: 'pipe'
+                    })){
+                        piped = true;
+                        identityOnly &&= identityPipe(module, initializer);
+                        initializer = unwrapExpression(initializer.callee.object, true);
+                    }
+                    if (!piped) return;
+                    const receiver = apiBinding(module, initializer);
+                    if (receiver?.module.path !== target.module.path || receiver.expression !== target.expression) return;
+                    if (!identityOnly || graph.resolveReference(module, node.id)?.kind !== 'declaration') valid = false;
+                });
+                return valid;
+            };
+            const ownedBy = (module, argument)=>{
+                if (!argument) return false;
+                if (rpc) {
+                    const binding = graphBinding(graph, module, argument);
+                    return binding?.kind === 'declaration' && ownExport?.kind === 'declaration' && binding.module.path === ownExport.module.path && binding.expression === ownExport.expression;
+                }
+                const binding = apiBinding(module, argument);
+                return void 0 !== binding && !!ownedApis.get(binding.module.path)?.has(binding.expression) && immutablePipeAliases(module, binding);
+            };
+            const violations = new Set();
+            for (const source of composedModules(client, appPath)){
+                const module = graph.module(absolute(source));
+                __rspack_external__babel_types_6e8337dd.traverseFast(module.file, (node)=>{
+                    if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node) && !__rspack_external__babel_types_6e8337dd.isOptionalCallExpression(node)) return;
+                    const native = graph.evaluate(module, node.callee).some((value)=>'external' === value.kind && value.specifier === effect && value.name === factory);
+                    if (native && !ownedBy(module, node.arguments[0])) violations.add(`${source}: must construct the client from its own API contract`);
+                });
+            }
+            return [
+                ...violations
+            ];
+        };
+        const moduleShape = (file, imports, calls, patterns = [], defaultExport, composedAppPath)=>{
             if (!exists(file)) return;
             const ast = parseFile(file);
             if (!ast) return;
-            const shapeFiles = composed ? composedModules(file) : [
+            const shapeFiles = composedAppPath ? composedModules(file, composedAppPath) : [
                 file
             ];
             const body = shapeFiles.flatMap((shapeFile)=>parseFile(shapeFile)?.program.body ?? []);
@@ -195,6 +446,14 @@ function check(options, topology) {
                 })), `${file}: must default-export ${defaultExport}`);
         };
         const effect = '@modern-js/bff-effect/effect-client';
+        const httpApiSources = [
+            effect,
+            'effect/http-api'
+        ];
+        const clientFactories = new Set([
+            'makeEffectHttpApiClient',
+            'makeEffectRpcClient'
+        ]);
         const appDirectories = [
             ...new Set([
                 ...directories('apps'),
@@ -255,7 +514,6 @@ function check(options, topology) {
                 if (violation) diagnostics.push(`${file}: ${violation}`);
             }
         });
-        let owner;
         for (const appPath of appDirectories)guarded(appPath, ()=>{
             const app = byPath.get(appPath);
             const emits = app ? apiApp(app) || 'vertical' !== app.kind && void 0 !== app.api : appPath.startsWith('verticals/') || exists(`${appPath}/api/index.ts`) || exists(`${appPath}/shared/api.ts`);
@@ -272,19 +530,25 @@ function check(options, topology) {
                 }
                 return;
             }
-            if (app?.kind === 'vertical') assert(void 0 !== app.api, `${appPath}: vertical must declare its Effect API in .modernjs/ultramodern.json`);
+            if (app?.kind === 'vertical') assert(void 0 !== app.api, `${appPath}: vertical must declare its Effect API in topology/reference-topology.json`);
             const stem = app?.api?.stem ?? node_path.posix.basename(appPath);
             const rpc = app?.api?.protocol === 'rpc';
             const contract = `${appPath}/shared/${rpc ? 'rpc' : 'api'}.ts`;
-            const client = `${appPath}/src/api/${stem}-${rpc ? 'rpc-client' : 'client'}.ts`;
             const entry = `${appPath}/api/index.ts`;
             for (const file of [
                 entry,
-                contract,
-                client
+                contract
             ])assert(exists(file), `${file}: required API surface is missing`);
+            const packageFile = `${appPath}/package.json`;
+            assert(exists(packageFile), `${packageFile}: required API package is missing`);
+            if (!exists(packageFile)) return;
+            const manifest = JSON.parse(read(packageFile));
+            assert(manifest.exports?.['./api'] === `./shared/${rpc ? 'rpc' : 'api'}.ts`, `${packageFile}: invalid ./api export`);
+            const clientKey = `./api/${rpc ? 'rpc-client' : 'client'}`;
+            const client = clientExportFile(appPath, manifest.exports?.[clientKey]);
+            assert(void 0 !== client, `${packageFile}: invalid API client export`);
+            assert(manifest.exports?.[`./api/${rpc ? 'client' : 'rpc-client'}`] === void 0, `${packageFile}: forbidden opposite protocol client export`);
             noPath(`${appPath}/shared/${rpc ? 'api' : 'rpc'}.ts`, `must not emit a ${rpc ? 'REST' : 'RPC'} contract`);
-            noPath(`${appPath}/src/api/${stem}-${rpc ? 'client' : 'rpc-client'}.ts`, `must not emit a ${rpc ? 'REST' : 'RPC'} client`);
             if (rpc) {
                 moduleShape(entry, [
                     [
@@ -315,7 +579,7 @@ function check(options, topology) {
                 ], 'apiRuntime');
                 moduleShape(contract, [
                     [
-                        'effect/unstable/rpc',
+                        'effect/rpc',
                         [
                             'Rpc',
                             'RpcGroup'
@@ -333,7 +597,7 @@ function check(options, topology) {
                     'Schema.Struct'
                 ]);
             } else if (exists(contract)) {
-                owner ??= options.baselinePackageDirectory ?? resolveBaselinePackageDirectory(node_path.join(root, 'package.json'));
+                const owner = options.baselinePackageDirectory ?? resolveBaselinePackageDirectory(absolute(contract));
                 const apiPrefix = app?.api?.prefix ?? `/${stem}-api`;
                 const basePath = `${apiPrefix}/${stem}`;
                 const expectation = {
@@ -350,21 +614,25 @@ function check(options, topology) {
                 const violation = microVerticalApiBaselineViolation(stem, absolute(contract), expectation);
                 if (violation) diagnostics.push(`${contract}: ${violation}`);
             }
-            moduleShape(client, [
-                [
-                    effect,
+            if (client) {
+                const relativeContract = node_path.posix.relative(node_path.posix.dirname(client), contract);
+                moduleShape(client, [
+                    [
+                        effect,
+                        [
+                            'Effect',
+                            rpc ? 'makeEffectRpcClient' : 'makeEffectHttpApiClient'
+                        ]
+                    ],
                     [
-                        'Effect',
-                        rpc ? 'makeEffectRpcClient' : 'makeEffectHttpApiClient'
+                        relativeContract.startsWith('.') ? relativeContract : `./${relativeContract}`,
+                        []
                     ]
-                ],
-                [
-                    rpc ? '../../shared/rpc.ts' : '../../shared/api',
-                    []
-                ]
-            ], [
-                rpc ? 'makeEffectRpcClient' : 'makeEffectHttpApiClient'
-            ], [], void 0, true);
+                ], [
+                    rpc ? 'makeEffectRpcClient' : 'makeEffectHttpApiClient'
+                ], [], void 0, appPath);
+                if (exists(contract)) diagnostics.push(...foreignClientConstructions(client, appPath, contract, stem, rpc));
+            }
             moduleShape(`${appPath}/api/effect-api.ts`, [], [], [
                 [
                     /\bbackendFederationContract\b/u,
@@ -405,28 +673,200 @@ function check(options, topology) {
                     'must enable strictEffectApproach'
                 ]
             ]);
-            const packageFile = `${appPath}/package.json`;
-            if (exists(packageFile)) {
-                const manifest = JSON.parse(read(packageFile));
-                assert(manifest.exports?.['./api'] === `./shared/${rpc ? 'rpc' : 'api'}.ts`, `${packageFile}: invalid ./api export`);
-                assert(manifest.exports?.[`./api/${rpc ? 'rpc-client' : 'client'}`] === `./src/api/${stem}-${rpc ? 'rpc-client' : 'client'}.ts`, `${packageFile}: invalid API client export`);
-                assert(manifest.exports?.[`./api/${rpc ? 'client' : 'rpc-client'}`] === void 0, `${packageFile}: forbidden opposite protocol client export`);
+        });
+        const sourceRules = options.sourceRules ?? [];
+        for (const file of sourceRules.length ? sourceFiles : [])if (/\.[cm]?[jt]sx?$/u.test(file)) guarded(file, ()=>{
+            const graph = createModuleGraph();
+            let module;
+            try {
+                module = graph.module(absolute(file));
+            } catch (error) {
+                if (!(error instanceof SourceSyntaxError)) throw error;
+                diagnostics.push(`${file}: source rules need parseable source (${error.message})`);
+                return;
+            }
+            for (const rule of sourceRules){
+                const messages = rule({
+                    file,
+                    module,
+                    graph
+                });
+                if (!Array.isArray(messages) || !messages.every((message)=>'string' == typeof message)) throw new Error(`rule ${rule.name || 'anonymous'} must return an array of violation messages (return [] when the file passes)`);
+                for (const message of messages)diagnostics.push(`${file}: ${message}`);
             }
         });
-        const shell = 'apps/shell-super-app';
-        const verticals = apps.filter((app)=>app.path.startsWith('verticals/') && apiApp(app));
-        if (exists(shell) && verticals.length) {
-            const file = `${shell}/src/api/vertical-clients.ts`;
-            assert(exists(file), `${file}: must aggregate vertical API clients`);
-            if (exists(file)) guarded(file, ()=>{
-                const ast = parseFile(file);
-                for (const app of verticals){
-                    const specifier = `${app.package}/api/${app.api?.protocol === 'rpc' ? 'rpc-client' : 'client'}`;
-                    assert(ast?.program.body.some((item)=>__rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(item) && item.source?.value === specifier), `${file}: must re-export ${specifier}`);
+        const checkShellExports = (shellPath)=>{
+            const packageFile = `${shellPath}/package.json`;
+            const manifest = JSON.parse(read(packageFile));
+            noPath(`${shellPath}/src/api/vertical-clients.ts`, 'Shell client registries are forbidden; import each owner client directly');
+            assert(!Object.hasOwn(manifest.exports ?? {}, './api/clients'), `${packageFile}: Shell ./api/clients exports are forbidden`);
+            const owner = node_fs.realpathSync(absolute(shellPath));
+            const invalidExport = ()=>assert(false, `${packageFile}: invalid Shell public source export`);
+            const targets = (exported)=>'string' == typeof exported ? [
+                    exported
+                ] : exported && 'object' == typeof exported ? Object.values(exported).flatMap(targets) : [];
+            const filesUnder = (directory, seen = new Set())=>{
+                const real = node_fs.realpathSync(absolute(directory));
+                if (real !== owner && !inside(owner, real)) {
+                    invalidExport();
+                    return [];
                 }
-            });
+                if (seen.has(real)) return [];
+                seen.add(real);
+                return node_fs.readdirSync(absolute(directory), {
+                    withFileTypes: true
+                }).flatMap((entry)=>{
+                    if (ignored.has(entry.name)) return [];
+                    const file = `${directory}/${entry.name}`;
+                    const stat = node_fs.statSync(absolute(file));
+                    return stat.isDirectory() ? filesUnder(file, seen) : stat.isFile() ? [
+                        file
+                    ] : [];
+                });
+            };
+            const exportedFiles = (target)=>{
+                if (!target.includes('*')) return [
+                    `${shellPath}/${target.slice(2)}`
+                ];
+                const prefix = target.slice(0, target.indexOf('*'));
+                const pattern = new RegExp(`^${target.split('*').map((part)=>part.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&')).join('.*')}$`, 'u');
+                return filesUnder(`${shellPath}/${prefix.slice(2, prefix.lastIndexOf('/'))}`).filter((file)=>pattern.test(`./${node_path.posix.relative(shellPath, file)}`));
+            };
+            const ownClientPrefix = `${manifest.name}/api/`;
+            const foreignSpecifier = (specifier)=>/\/api\/(?:rpc-)?client$/u.test(specifier) && !specifier.startsWith(ownClientPrefix);
+            for (const target of targets(manifest.exports))if (/\.[cm]?[jt]sx?$/u.test(target)) {
+                if (!target.startsWith('./') || target.split(/[\\/]/u).includes('..')) {
+                    invalidExport();
+                    continue;
+                }
+                for (const candidate of exportedFiles(target)){
+                    const file = clientExportFile(shellPath, `./${node_path.posix.relative(shellPath, candidate)}`);
+                    if (!file) {
+                        invalidExport();
+                        continue;
+                    }
+                    assert(!exposesForeignClient(file, owner, foreignSpecifier), `${file}: Shell public exports must not expose another owner's API client`);
+                }
+            }
+        };
+        const exposesForeignClient = (entry, owner, foreignSpecifier)=>{
+            const graph = createModuleGraph();
+            const seenValues = new Set();
+            const seenExports = new Map();
+            const workspacePath = (module)=>normalize(node_path.relative(workspace, module.path));
+            const resolveSource = (from, specifier)=>resolveRelative(from, specifier) ?? ownerClients.get(specifier);
+            const returnExpressions = (node)=>{
+                if (__rspack_external__babel_types_6e8337dd.isReturnStatement(node)) return node.argument ? [
+                    node.argument
+                ] : [];
+                if (__rspack_external__babel_types_6e8337dd.isFunction(node)) return [];
+                return (__rspack_external__babel_types_6e8337dd.VISITOR_KEYS[node.type] ?? []).flatMap((key)=>{
+                    const value = Reflect.get(node, key);
+                    return (Array.isArray(value) ? value : [
+                        value
+                    ]).flatMap((child)=>__rspack_external__babel_types_6e8337dd.isNode(child) ? returnExpressions(child) : []);
+                });
+            };
+            const nestedValues = (node)=>{
+                if (__rspack_external__babel_types_6e8337dd.isObjectExpression(node)) return node.properties.flatMap((property)=>__rspack_external__babel_types_6e8337dd.isObjectProperty(property) ? [
+                        property.value
+                    ] : __rspack_external__babel_types_6e8337dd.isObjectMethod(property) ? returnExpressions(property.body) : __rspack_external__babel_types_6e8337dd.isSpreadElement(property) ? [
+                        property.argument
+                    ] : []);
+                if (__rspack_external__babel_types_6e8337dd.isArrayExpression(node)) return node.elements.filter((element)=>null !== element);
+                if (__rspack_external__babel_types_6e8337dd.isFunction(node)) return __rspack_external__babel_types_6e8337dd.isBlockStatement(node.body) ? returnExpressions(node.body) : [
+                    node.body
+                ];
+                return [];
+            };
+            const foreignValue = (value, from)=>{
+                if ('external' === value.kind) {
+                    const source = resolveSource(workspacePath(from), value.specifier);
+                    if (!source) return foreignSpecifier(value.specifier);
+                    return '*' === value.name ? inspect(source) : exportedValue(source, value.name);
+                }
+                if ('unresolved' === value.kind && __rspack_external__babel_types_6e8337dd.isImportDeclaration(value.node) && value.node.specifiers.some((specifier)=>__rspack_external__babel_types_6e8337dd.isImportNamespaceSpecifier(specifier))) {
+                    const specifier = value.node.source.value;
+                    const source = resolveSource(workspacePath(value.module), specifier);
+                    return source ? inspect(source) : foreignSpecifier(specifier);
+                }
+                if ('node' !== value.kind || seenValues.has(value.node)) return false;
+                seenValues.add(value.node);
+                const { node, module } = value;
+                if ((__rspack_external__babel_types_6e8337dd.isCallExpression(node) || __rspack_external__babel_types_6e8337dd.isOptionalCallExpression(node)) && graph.evaluate(module, node.callee).some((callee)=>'external' === callee.kind && callee.specifier === effect && clientFactories.has(callee.name))) {
+                    const [argument] = node.arguments;
+                    const binding = argument ? graphBinding(graph, module, argument) : void 0;
+                    if (module.boundary !== owner || binding?.kind !== 'declaration' || binding.module.boundary !== owner) return true;
+                }
+                return nestedValues(node).some((expression)=>graph.evaluate(module, expression).some((nested)=>foreignValue(nested, module)));
+            };
+            const exportName = (node)=>__rspack_external__babel_types_6e8337dd.isIdentifier(node) ? node.name : node.value;
+            const names = (source, visited = new Set())=>{
+                if (visited.has(source)) return [];
+                visited.add(source);
+                return graph.module(absolute(source)).file.program.body.flatMap((statement)=>{
+                    if (__rspack_external__babel_types_6e8337dd.isExportDefaultDeclaration(statement)) return [
+                        'default'
+                    ];
+                    if (!__rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(statement) && !__rspack_external__babel_types_6e8337dd.isExportAllDeclaration(statement) || 'type' === statement.exportKind) return [];
+                    if (__rspack_external__babel_types_6e8337dd.isExportAllDeclaration(statement)) {
+                        const target = resolveSource(source, statement.source.value);
+                        return target ? names(target, visited).filter((name)=>'default' !== name) : [];
+                    }
+                    return statement.declaration ? Object.keys(__rspack_external__babel_types_6e8337dd.getOuterBindingIdentifiers(statement.declaration)) : statement.specifiers.flatMap((specifier)=>__rspack_external__babel_types_6e8337dd.isExportSpecifier(specifier) && 'type' === specifier.exportKind ? [] : [
+                            exportName(specifier.exported)
+                        ]);
+                });
+            };
+            const exportedValue = (source, name)=>{
+                const visited = seenExports.get(source) ?? new Set();
+                if (visited.has(name)) return false;
+                visited.add(name);
+                seenExports.set(source, visited);
+                const module = graph.module(absolute(source));
+                const evaluates = (from, node)=>graph.evaluate(from, node).some((value)=>foreignValue(value, from));
+                const binding = graph.resolve(module, name, 'export');
+                if (binding?.kind === 'external') return foreignValue({
+                    ...binding,
+                    members: []
+                }, module);
+                if (binding?.kind === 'declaration') return evaluates(binding.module, binding.expression);
+                for (const statement of module.file.program.body){
+                    if (__rspack_external__babel_types_6e8337dd.isExportDefaultDeclaration(statement) && 'default' === name) return evaluates(module, statement.declaration);
+                    if (!__rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(statement) || 'type' === statement.exportKind) continue;
+                    if (__rspack_external__babel_types_6e8337dd.isFunctionDeclaration(statement.declaration) && statement.declaration.id?.name === name) return evaluates(module, statement.declaration);
+                    const specifier = statement.specifiers.find((item)=>exportName(item.exported) === name);
+                    if (!specifier) continue;
+                    if (__rspack_external__babel_types_6e8337dd.isExportSpecifier(specifier) && 'type' === specifier.exportKind) return false;
+                    if (!statement.source) return __rspack_external__babel_types_6e8337dd.isExportSpecifier(specifier) ? evaluates(module, specifier.local) : false;
+                    const target = resolveSource(source, statement.source.value);
+                    if (!target) return foreignSpecifier(statement.source.value);
+                    if (__rspack_external__babel_types_6e8337dd.isExportNamespaceSpecifier(specifier)) return inspect(target);
+                    if (__rspack_external__babel_types_6e8337dd.isExportSpecifier(specifier)) return exportedValue(target, exportName(specifier.local));
+                }
+                return module.file.program.body.some((statement)=>{
+                    if (!__rspack_external__babel_types_6e8337dd.isExportAllDeclaration(statement) || 'type' === statement.exportKind) return false;
+                    const target = resolveSource(source, statement.source.value);
+                    return !!target && names(target).includes(name) && exportedValue(target, name);
+                });
+            };
+            const inspect = (source)=>[
+                    ...new Set(names(source))
+                ].some((name)=>exportedValue(source, name));
+            return inspect(entry);
+        };
+        const ownerClients = new Map();
+        for (const app of apps)if (exists(`${app.path}/package.json`)) {
+            const manifest = JSON.parse(read(`${app.path}/package.json`));
+            for (const key of [
+                './api/client',
+                './api/rpc-client'
+            ]){
+                const file = clientExportFile(app.path, manifest.exports?.[key]);
+                if (file) ownerClients.set(`${manifest.name}${key.slice(1)}`, file);
+            }
         }
-        if (exists(`${shell}/package.json`)) guarded(`${shell}/package.json`, ()=>assert(JSON.parse(read(`${shell}/package.json`)).exports?.['./api/clients'] === './src/api/vertical-clients.ts', `${shell}/package.json: must export ./api/clients`));
+        for (const shell of apps.filter((app)=>'shell' === app.kind))guarded(shell.path, ()=>checkShellExports(normalize(shell.path)));
         if (exists('topology/reference-topology.json')) guarded('topology/reference-topology.json', ()=>{
             for (const vertical of JSON.parse(read('topology/reference-topology.json')).verticals ?? []){
                 if (vertical.api?.runtime === 'effect') {
@@ -447,4 +887,4 @@ function check(options, topology) {
 }
 const checkMicroVerticalApiBoundaries = (options)=>check(options, true);
 const checkMicroVerticalApiConsumerFiles = (options)=>check(options, false);
-export { checkMicroVerticalApiBoundaries, checkMicroVerticalApiConsumerFiles, configuredMicroVerticalApiStem, microVerticalApiBaselineViolation };
+export { checkMicroVerticalApiBoundaries, checkMicroVerticalApiConsumerFiles, configuredMicroVerticalApiStem, createModuleGraph, microVerticalApiBaselineViolation };