@bleedingdev/modern-js-code-tools 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/dist/esm/strict-effect-runtime.js

@@ -0,0 +1,324 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { SourceSyntaxError, parseSource, traverseSource, unwrapExpression } from "./source-analysis.js";
+import * as __rspack_external__babel_types_6e8337dd from "@babel/types";
+const edge = '@modern-js/bff-effect/effect-edge';
+const nodeRuntime = '@modern-js/bff-effect/effect';
+const assembly = '@modern-js/bff-effect/assembly';
+const failure = 'Generated API entries must export defineEffectBff(...) or the native Effect BFF assembly helper with an explicitly composed handler Layer and an unshadowed executable root; entries must implement handlers through HttpApiBuilder.group.';
+const MAX_API_SOURCE_MODULES = 256;
+function createEffectApiImportResolver(filename) {
+    const directory = node_fs.realpathSync(node_path.dirname(filename));
+    const owner = node_fs.realpathSync(node_path.resolve(directory, '..'));
+    const resolve = (from)=>(specifier)=>{
+            if (!specifier.startsWith('.')) return;
+            const target = node_path.resolve(node_path.dirname(from), specifier);
+            if (!target.startsWith(`${owner}${node_path.sep}`)) return;
+            for (const candidate of [
+                target,
+                `${target}.ts`,
+                `${target}.mts`
+            ])try {
+                const real = node_fs.realpathSync(candidate);
+                if (!real.startsWith(`${owner}${node_path.sep}`) || node_fs.statSync(real).size > 1000000) return;
+                return {
+                    id: real,
+                    source: node_fs.readFileSync(real, 'utf8'),
+                    resolveImport: resolve(real)
+                };
+            } catch  {}
+        };
+    return resolve(node_path.join(directory, node_path.basename(filename)));
+}
+function strictEffectRuntimeTopologyViolation(source, resolveImport) {
+    const modules = new Map();
+    const owners = new Map();
+    const paths = new Map();
+    const mutated = new Set();
+    const load = (input)=>{
+        const existing = modules.get(input.id);
+        if (existing) return existing;
+        if (modules.size >= MAX_API_SOURCE_MODULES || input.source.length > 1000000) throw new SourceSyntaxError('API source budget exceeded');
+        const file = parseSource(input.source, input.id, 'Invalid API syntax');
+        const module = {
+            ...input,
+            file
+        };
+        modules.set(input.id, module);
+        traverseSource(file, {
+            enter (nodePath) {
+                paths.set(nodePath.node, nodePath);
+                owners.set(nodePath.node, module);
+                if (nodePath.isAssignmentExpression() || nodePath.isUpdateExpression() || nodePath.isUnaryExpression({
+                    operator: 'delete'
+                })) {
+                    let target = nodePath.isAssignmentExpression() ? nodePath.node.left : nodePath.node.argument;
+                    while(__rspack_external__babel_types_6e8337dd.isMemberExpression(target))target = target.object;
+                    if (__rspack_external__babel_types_6e8337dd.isIdentifier(target)) {
+                        const binding = nodePath.scope.getBinding(target.name);
+                        if (binding) mutated.add(binding);
+                    }
+                }
+                if (nodePath.isTSModuleDeclaration() && __rspack_external__babel_types_6e8337dd.isIdentifier(nodePath.node.id)) {
+                    const binding = nodePath.scope.getBinding(nodePath.node.id.name);
+                    if (binding) mutated.add(binding);
+                }
+            }
+        });
+        return module;
+    };
+    try {
+        const entry = load({
+            id: '/entry.ts',
+            source,
+            resolveImport
+        });
+        const unwrap = (node)=>unwrapExpression(node, true);
+        const binding = (node)=>{
+            node = unwrap(node);
+            if (!__rspack_external__babel_types_6e8337dd.isIdentifier(node)) return;
+            const nodePath = paths.get(node);
+            if (!nodePath) throw new Error('Missing API lexical scope');
+            const value = nodePath.scope.getBinding(node.name);
+            return value?.constant && !mutated.has(value) ? value : void 0;
+        };
+        const declaration = (node)=>binding(node)?.path.node;
+        const imported = (node)=>{
+            const value = binding(node);
+            const decl = value?.path.node;
+            if (!decl || !__rspack_external__babel_types_6e8337dd.isImportSpecifier(decl) && !__rspack_external__babel_types_6e8337dd.isImportNamespaceSpecifier(decl) || __rspack_external__babel_types_6e8337dd.isImportSpecifier(decl) && 'type' === decl.importKind) return;
+            const statement = value.path.parent;
+            if (!__rspack_external__babel_types_6e8337dd.isImportDeclaration(statement) || 'type' === statement.importKind) return;
+            return {
+                namespace: __rspack_external__babel_types_6e8337dd.isImportNamespaceSpecifier(decl),
+                name: __rspack_external__babel_types_6e8337dd.isImportNamespaceSpecifier(decl) ? '*' : __rspack_external__babel_types_6e8337dd.isIdentifier(decl.imported) ? decl.imported.name : decl.imported.value,
+                specifier: statement.source.value
+            };
+        };
+        const namespaceSources = {
+            HttpApi: [
+                edge,
+                'effect/unstable/httpapi'
+            ],
+            HttpApiBuilder: [
+                edge,
+                'effect/unstable/httpapi'
+            ],
+            HttpRouter: [
+                edge,
+                'effect/unstable/http'
+            ]
+        };
+        const native = (node, name, sources)=>{
+            const value = imported(node);
+            if (!value) return false;
+            const importedNameMatches = value.namespace ? value.specifier === `effect/${name}` : value.name === name && value.specifier !== `effect/${name}`;
+            return importedNameMatches && (sources ?? namespaceSources[name] ?? [
+                edge
+            ]).includes(value.specifier);
+        };
+        const method = (node, namespace, member, sources)=>{
+            node = unwrap(node);
+            return __rspack_external__babel_types_6e8337dd.isMemberExpression(node) && !node.computed && __rspack_external__babel_types_6e8337dd.isIdentifier(node.property, {
+                name: member
+            }) && native(node.object, namespace, sources);
+        };
+        const initialized = (node)=>{
+            const value = binding(node);
+            return value?.kind === 'const' && __rspack_external__babel_types_6e8337dd.isVariableDeclarator(value.path.node) ? value.path.node.init ?? void 0 : void 0;
+        };
+        const moduleFor = (node)=>{
+            const value = imported(node);
+            if (!value) return;
+            const input = owners.get(node)?.resolveImport?.(value.specifier);
+            return input ? {
+                module: load(input),
+                name: value.name
+            } : void 0;
+        };
+        const exported = (module, name)=>{
+            for (const statement of module.file.program.body)if (__rspack_external__babel_types_6e8337dd.isExportNamedDeclaration(statement) && 'type' !== statement.exportKind) {
+                if (__rspack_external__babel_types_6e8337dd.isVariableDeclaration(statement.declaration)) {
+                    for (const decl of statement.declaration.declarations)if (__rspack_external__babel_types_6e8337dd.isIdentifier(decl.id, {
+                        name
+                    })) return decl.id;
+                }
+                if (!statement.source) {
+                    const specifier = statement.specifiers.find((element)=>__rspack_external__babel_types_6e8337dd.isExportSpecifier(element) && 'type' !== element.exportKind && (__rspack_external__babel_types_6e8337dd.isIdentifier(element.exported) ? element.exported.name : element.exported.value) === name);
+                    if (__rspack_external__babel_types_6e8337dd.isExportSpecifier(specifier)) return specifier.local;
+                }
+            }
+        };
+        const externalValue = (node)=>{
+            const value = moduleFor(node);
+            return value ? exported(value.module, value.name) : void 0;
+        };
+        const apiIdentity = (node, seen = new Set())=>{
+            node = unwrap(node);
+            if (seen.has(node)) return;
+            seen.add(node);
+            const value = imported(node);
+            if (value) {
+                if (!value.specifier.startsWith('.')) return;
+                const module = moduleFor(node);
+                const exportedValue = module && exported(module.module, module.name);
+                if (exportedValue) return apiIdentity(exportedValue, seen);
+                if (module && /(?:^|\/)shared\/(?:api|rpc)\.ts$/u.test(value.specifier)) return `${module.module.id}:import:${value.name}`;
+                if (!owners.get(node)?.resolveImport && /(?:^|\/)shared\/(?:api|rpc)\.ts$/u.test(value.specifier)) return `${value.specifier}:${value.name}`;
+                return;
+            }
+            const init = initialized(node);
+            if (init && __rspack_external__babel_types_6e8337dd.isIdentifier(unwrap(init))) return apiIdentity(init, seen);
+            const valueBinding = binding(node);
+            return valueBinding ? `${owners.get(valueBinding.path.node)?.id}:${valueBinding.identifier.start}` : void 0;
+        };
+        const properties = (node)=>{
+            node = unwrap(node);
+            if (!__rspack_external__babel_types_6e8337dd.isObjectExpression(node)) return;
+            const result = new Map();
+            for (const prop of node.properties){
+                if (!__rspack_external__babel_types_6e8337dd.isObjectProperty(prop) || prop.computed || !__rspack_external__babel_types_6e8337dd.isIdentifier(prop.key) || result.has(prop.key.name)) return;
+                result.set(prop.key.name, prop.value);
+            }
+            return result;
+        };
+        const active = new Set();
+        const guarded = (node, check)=>{
+            node = unwrap(node);
+            if (active.has(node) || active.size > 128) return false;
+            active.add(node);
+            try {
+                return check(node);
+            } finally{
+                active.delete(node);
+            }
+        };
+        const layerSources = [
+            edge,
+            'effect',
+            'effect/Layer'
+        ];
+        const returned = (body)=>{
+            if (!__rspack_external__babel_types_6e8337dd.isBlockStatement(body)) return body;
+            const statements = body.body;
+            const last = statements.at(-1);
+            return statements.slice(0, -1).every((statement)=>__rspack_external__babel_types_6e8337dd.isVariableDeclaration(statement) || __rspack_external__babel_types_6e8337dd.isTSTypeAliasDeclaration(statement) || __rspack_external__babel_types_6e8337dd.isTSInterfaceDeclaration(statement)) && __rspack_external__babel_types_6e8337dd.isReturnStatement(last) ? last.argument : void 0;
+        };
+        const pipe = (node, check)=>__rspack_external__babel_types_6e8337dd.isMemberExpression(node.callee) && !node.callee.computed && __rspack_external__babel_types_6e8337dd.isIdentifier(node.callee.property, {
+                name: 'pipe'
+            }) && check(node.callee.object) && node.arguments.every((argument)=>method(argument, 'Layer', 'orDie', layerSources) || __rspack_external__babel_types_6e8337dd.isCallExpression(argument) && method(argument.callee, 'Layer', 'provide', layerSources) && argument.arguments.length > 0);
+        const handled = (node)=>{
+            node = unwrap(node);
+            if (!__rspack_external__babel_types_6e8337dd.isArrowFunctionExpression(node) && !__rspack_external__babel_types_6e8337dd.isFunctionExpression(node)) return false;
+            const parameter = node.params[0];
+            if (!__rspack_external__babel_types_6e8337dd.isIdentifier(parameter)) return false;
+            const body = returned(node.body);
+            const chain = (value, count = 0)=>{
+                value = unwrap(value);
+                if (__rspack_external__babel_types_6e8337dd.isIdentifier(value)) return count > 0 && declaration(value) === parameter;
+                return __rspack_external__babel_types_6e8337dd.isCallExpression(value) && __rspack_external__babel_types_6e8337dd.isMemberExpression(value.callee) && !value.callee.computed && __rspack_external__babel_types_6e8337dd.isIdentifier(value.callee.property) && [
+                    'handle',
+                    'handleRaw'
+                ].includes(value.callee.property.name) && 2 === value.arguments.length && chain(value.callee.object, count + 1);
+            };
+            return !!body && chain(body);
+        };
+        const handlers = (node, api)=>guarded(node, (node)=>{
+                const init = initialized(node) ?? externalValue(node);
+                if (init) return handlers(init, api);
+                if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node)) return false;
+                if (pipe(node, (value)=>handlers(value, api))) return true;
+                if (method(node.callee, 'Layer', 'mergeAll', layerSources)) return node.arguments.length > 0 && node.arguments.every((argument)=>handlers(argument, api));
+                return method(node.callee, 'HttpApiBuilder', 'group') && 3 === node.arguments.length && apiIdentity(node.arguments[0]) === api && handled(node.arguments[2]);
+            });
+        const transport = (node)=>guarded(node, (node)=>{
+                const init = initialized(node);
+                if (init) return transport(init);
+                if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node)) return method(node, 'Layer', 'empty', layerSources);
+                return pipe(node, transport) || method(node.callee, 'HttpRouter', 'cors') || method(node.callee, 'Layer', 'mergeAll', layerSources) && node.arguments.length > 0 && node.arguments.every(transport);
+            });
+        const directLayer = (node, api)=>guarded(node, (node)=>{
+                const init = initialized(node);
+                if (init) return directLayer(init, api);
+                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'
+                })) return false;
+                const base = unwrap(node.callee.object);
+                return __rspack_external__babel_types_6e8337dd.isCallExpression(base) && method(base.callee, 'HttpApiBuilder', 'layer') && 1 === base.arguments.length && apiIdentity(base.arguments[0]) === api && node.arguments.length > 0 && node.arguments.every((argument)=>__rspack_external__babel_types_6e8337dd.isCallExpression(argument) && method(argument.callee, 'Layer', 'provide', layerSources) && 1 === argument.arguments.length && handlers(argument.arguments[0], api));
+            });
+        const rpc = (values)=>{
+            const api = values.get('api');
+            const apiLayer = values.get('layer');
+            const apiInit = api && (initialized(api) ?? unwrap(api));
+            if (!apiInit || !__rspack_external__babel_types_6e8337dd.isCallExpression(apiInit) || !method(apiInit.callee, 'HttpApi', 'make') || 1 !== apiInit.arguments.length || !apiLayer || !transport(apiLayer)) return false;
+            const config = values.get('rpc');
+            const fields = config && properties(config);
+            const route = fields?.get('path');
+            const serialization = fields?.get('serialization');
+            if (!__rspack_external__babel_types_6e8337dd.isStringLiteral(route, {
+                value: '/rpc'
+            }) || !__rspack_external__babel_types_6e8337dd.isStringLiteral(serialization, {
+                value: 'json'
+            })) return false;
+            const group = fields?.get('group');
+            const layer = fields?.get('layer');
+            const value = group && imported(group);
+            if (!group || !layer || value?.specifier !== '../shared/rpc.ts') return false;
+            const groupValue = externalValue(group);
+            const groupInit = groupValue && initialized(groupValue);
+            if (!groupInit || !__rspack_external__babel_types_6e8337dd.isCallExpression(groupInit) || !method(groupInit.callee, 'RpcGroup', 'make', [
+                'effect/unstable/rpc',
+                '@modern-js/bff-effect/effect-client'
+            ])) return false;
+            const layerInit = initialized(layer) ?? unwrap(layer);
+            if (!__rspack_external__babel_types_6e8337dd.isCallExpression(layerInit) || !__rspack_external__babel_types_6e8337dd.isMemberExpression(layerInit.callee) || layerInit.callee.computed || !__rspack_external__babel_types_6e8337dd.isIdentifier(layerInit.callee.property, {
+                name: 'toLayer'
+            }) || apiIdentity(layerInit.callee.object) !== apiIdentity(group) || 1 !== layerInit.arguments.length) return false;
+            const implementation = unwrap(layerInit.arguments[0]);
+            if (!__rspack_external__babel_types_6e8337dd.isCallExpression(implementation) || !__rspack_external__babel_types_6e8337dd.isMemberExpression(implementation.callee) || implementation.callee.computed || !__rspack_external__babel_types_6e8337dd.isIdentifier(implementation.callee.property, {
+                name: 'of'
+            }) || apiIdentity(implementation.callee.object) !== apiIdentity(group) || 1 !== implementation.arguments.length) return false;
+            const entries = properties(implementation.arguments[0]);
+            return !!entries?.size && [
+                ...entries.values()
+            ].every((value)=>__rspack_external__babel_types_6e8337dd.isArrowFunctionExpression(value) || __rspack_external__babel_types_6e8337dd.isFunctionExpression(value));
+        };
+        const runtime = (node)=>guarded(node, (node)=>{
+                const init = initialized(node);
+                if (init) return runtime(init);
+                if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node)) return false;
+                const value = imported(node.callee);
+                if (value?.name === 'defineEffectBff' && [
+                    edge,
+                    nodeRuntime
+                ].includes(value.specifier) || value?.name === 'assembleEffectBffRuntime' && value.specifier === assembly) {
+                    if (1 !== node.arguments.length) return false;
+                    const values = properties(node.arguments[0]);
+                    if (!values) return false;
+                    if ('defineEffectBff' === value.name && values.has('rpc')) return rpc(values);
+                    const api = values.get('api');
+                    const apiBinding = api && imported(api);
+                    if (!api || apiBinding?.specifier !== '../shared/api.ts') return false;
+                    const identity = apiIdentity(api);
+                    if (!identity) return false;
+                    const layer = values.get('defineEffectBff' === value.name ? 'layer' : 'handlers');
+                    const extra = values.get('transport');
+                    return void 0 !== layer && ('defineEffectBff' === value.name ? directLayer(layer, identity) : handlers(layer, identity)) && (!extra || transport(extra));
+                }
+                const decl = declaration(node.callee);
+                const factory = decl && __rspack_external__babel_types_6e8337dd.isFunctionDeclaration(decl) ? decl : initialized(node.callee);
+                if (!factory || !__rspack_external__babel_types_6e8337dd.isFunctionDeclaration(factory) && !__rspack_external__babel_types_6e8337dd.isArrowFunctionExpression(factory) && !__rspack_external__babel_types_6e8337dd.isFunctionExpression(factory) || !factory.body) return false;
+                const result = returned(factory.body);
+                return !!result && runtime(result);
+            });
+        const root = entry.file.program.body.find((statement)=>__rspack_external__babel_types_6e8337dd.isExportDefaultDeclaration(statement));
+        return root && runtime(root.declaration) ? void 0 : failure;
+    } catch (cause) {
+        if (cause instanceof SourceSyntaxError) return failure;
+        const message = 'object' == typeof cause && null !== cause && 'message' in cause && 'string' == typeof cause.message ? cause.message : String(cause);
+        throw new Error(`Strict Effect API analysis failed: ${message}`, {
+            cause
+        });
+    }
+}
+export { createEffectApiImportResolver, strictEffectRuntimeTopologyViolation };

package/dist/esm-node/cli/microvertical-api-check.js

@@ -0,0 +1,53 @@
+import "node:module";
+import node_path from "node:path";
+import { pathToFileURL } from "node:url";
+import { checkMicroVerticalApiBoundaries, checkMicroVerticalApiConsumerFiles } from "../microvertical-api-boundary.js";
+const flags = [
+    '--workspace-root',
+    '--baseline-package-directory',
+    '--rules'
+];
+async function loadContractRules(file) {
+    const rules = (await import(pathToFileURL(node_path.resolve(file)).href)).default;
+    if (!Array.isArray(rules) || !rules.every((rule)=>'function' == typeof rule)) throw new Error(`${file}: default export must be an array of contract rule functions, e.g. \`export default [myRule]\``);
+    return rules;
+}
+async function runMicroVerticalApiCheckCli(args = process.argv.slice(2), filesOnly = false) {
+    let workspaceRoot = process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd();
+    let baselinePackageDirectory;
+    const ruleFiles = [];
+    for(let index = 0; index < args.length; index += 1){
+        const argument = args[index];
+        if ('--help' === argument || '-h' === argument) {
+            console.log(`${filesOnly ? 'modern-api-check-files' : 'modern-api-check'} [--workspace-root <path>] [--baseline-package-directory <path>] [--rules <module>]...\n${filesOnly ? 'Checks consumer files, contracts, package exports and owner identity. Does not analyze runtime topology; run the strict Effect source phase separately.' : 'Checks consumer files, contracts, package exports, owner identity and runtime topology once per API entry.'}\n--rules loads a module whose default export is an array of contract rules; each rule receives the module graph of every API contract.\nWorkspace defaults to ULTRAMODERN_WORKSPACE_ROOT then cwd. Exit codes: 0 valid, 1 consumer violation, 2 tool/configuration failure.`);
+            return 0;
+        }
+        if (!flags.includes(argument ?? '') || !args[index + 1] || args[index + 1]?.startsWith('--')) {
+            console.error(`Invalid argument: ${argument ?? ''}. Use --help.`);
+            return 2;
+        }
+        const value = args[++index];
+        if ('--workspace-root' === argument) workspaceRoot = value;
+        else if ('--rules' === argument) ruleFiles.push(value);
+        else baselinePackageDirectory = value;
+    }
+    const contractRules = [];
+    for (const file of ruleFiles)try {
+        contractRules.push(...await loadContractRules(file));
+    } catch (error) {
+        console.error(`API tool error: --rules ${error instanceof Error ? error.message : String(error)}`);
+        return 2;
+    }
+    const result = (filesOnly ? checkMicroVerticalApiConsumerFiles : checkMicroVerticalApiBoundaries)({
+        workspaceRoot,
+        baselinePackageDirectory,
+        contractRules
+    });
+    for (const diagnostic of result.diagnostics)console.error(`API violation: ${diagnostic}`);
+    for (const error of result.toolErrors)console.error(`API tool error: ${error}`);
+    if (result.toolErrors.length) return 2;
+    if (result.diagnostics.length) return 1;
+    console.log(`UltraModern API ${filesOnly ? 'consumer files' : 'boundary'} check passed.`);
+    return 0;
+}
+export { runMicroVerticalApiCheckCli };

package/dist/esm-node/cli/oxlint.js

@@ -4,7 +4,7 @@ import node_fs from "node:fs";
 import { createRequire } from "node:module";
 import node_os from "node:os";
 import node_path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 const oxlint_require = createRequire(import.meta.url);
 const ignoredDirectories = new Set([
     '.modern',
@@ -74,22 +74,26 @@ const runOxlintRules = ({ cwd, targets, rules })=>{
         stdout: '',
         stderr: ''
     };
+    const pluginPath = resolvePluginPath();
     const tempDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), 'modern-code-tools-oxlint-'));
     const configPath = node_path.join(tempDir, 'oxlint.config.mjs');
-    const pluginPath = resolvePluginPath();
-    node_fs.writeFileSync(configPath, `export default {
-  jsPlugins: [${JSON.stringify(pluginPath)}],
+    const adapterPath = node_path.join(tempDir, 'oxlint-plugin.mjs');
+    try {
+        node_fs.writeFileSync(adapterPath, `import plugin from ${JSON.stringify(pathToFileURL(pluginPath).href)};
+export default plugin.rules ? plugin : plugin.default;
+`, 'utf-8');
+        node_fs.writeFileSync(configPath, `export default {
+  jsPlugins: [${JSON.stringify(adapterPath)}],
   rules: ${JSON.stringify(rules, null, 2)}
 };
 `, 'utf-8');
-    try {
         const result = spawnSync(process.execPath, [
             resolveOxlintBin(),
             ...resolvedTargets,
             '--config',
             configPath,
             '--format',
-            'unix',
+            'default',
             '--quiet'
         ], {
             cwd,

package/dist/esm-node/cli/workspace-source-check.js

@@ -7,6 +7,11 @@ const DEFAULT_LOCALES = [
     'en',
     'cs'
 ];
+const DEFAULT_SOURCE_ROOTS = [
+    'apps',
+    'verticals',
+    'packages'
+];
 const ignoredDirectories = new Set([
     '.modern',
     '.modernjs',
@@ -40,6 +45,8 @@ const createLocaleJsonMatcher = (locales)=>{
 const resolvePluralCategories = (locale, overrides)=>overrides?.[locale] ?? new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
 const readText = (filePath)=>node_fs.readFileSync(filePath, 'utf-8');
 const localeImportPattern = (locale)=>new RegExp(`import\\s+(?:\\*\\s+as\\s+)?[A-Za-z_$][\\w$]*\\s+from\\s+['"]\\.\\./locales/${escapeRegExp(locale)}/[^'"]+\\.json['"]`, 'u');
+class SourceViolation extends Error {
+}
 const checkRuntimeResources = (root, filePath, text, locales)=>{
     const relative = relativePath(root, filePath);
     if (!relative.endsWith('/src/modern.runtime.ts')) return;
@@ -47,7 +54,7 @@ const checkRuntimeResources = (root, filePath, text, locales)=>{
     const registersResources = /initOptions\s*:\s*\{[\s\S]*?\bresources\s*[,:}]/u.test(text);
     if (missingLocales.length > 0 || !registersResources) {
         const detail = missingLocales.length > 0 ? `missing locale JSON imports for: ${missingLocales.join(', ')}` : 'initOptions does not register a `resources` entry';
-        throw new Error(`${relative} must register locale JSON resources in modern.runtime.ts so Worker SSR and hydration use the same first-render translations (${detail}).`);
+        throw new SourceViolation(`${relative} must register locale JSON resources in modern.runtime.ts so Worker SSR and hydration use the same first-render translations (${detail}).`);
     }
 };
 const visitLocaleKeys = (value, visitor, pathParts = [])=>{
@@ -67,7 +74,7 @@ const checkPluralResources = (root, filePath, json, requiredSuffixes, pluralSuff
     visitLocaleKeys(json, (key, value, pathParts)=>{
         if ('string' != typeof value || !value.includes('{{count}}')) return;
         const suffixMatch = key.match(pluralSuffixPattern);
-        if (!suffixMatch) throw new Error(`${relative} key ${pathParts.join('.')} contains {{count}} but is not plural-suffixed.`);
+        if (!suffixMatch) throw new SourceViolation(`${relative} key ${pathParts.join('.')} contains {{count}} but is not plural-suffixed.`);
         const [, base = '', suffix = ''] = suffixMatch;
         const parentPath = pathParts.slice(0, -1).join('.');
         const groupKey = `${parentPath}.${base}`;
@@ -75,7 +82,7 @@ const checkPluralResources = (root, filePath, json, requiredSuffixes, pluralSuff
         existing.add(suffix);
         groups.set(groupKey, existing);
     });
-    for (const [group, suffixes] of groups)for (const suffix of requiredSuffixes)if (!suffixes.has(suffix)) throw new Error(`${relative} plural group ${group} is missing _${suffix}.`);
+    for (const [group, suffixes] of groups)for (const suffix of requiredSuffixes)if (!suffixes.has(suffix)) throw new SourceViolation(`${relative} plural group ${group} is missing _${suffix}.`);
 };
 const runRuntimeAndLocaleResourceChecks = (root, sourceRoots, locales, pluralCategories)=>{
     if (0 === locales.length) return;
@@ -97,11 +104,7 @@ const runRuntimeAndLocaleResourceChecks = (root, sourceRoots, locales, pluralCat
         checkPluralResources(root, filePath, JSON.parse(readText(filePath)), localeCategories.get(language) ?? [], pluralSuffixPattern);
     }
 };
-const runWorkspaceSourceCheck = ({ cwd = process.cwd(), sourceRoots = [
-    'apps',
-    'verticals',
-    'packages'
-], locales = DEFAULT_LOCALES, pluralCategories } = {})=>{
+const runWorkspaceSourceCheck = ({ cwd = process.cwd(), sourceRoots = DEFAULT_SOURCE_ROOTS, locales = DEFAULT_LOCALES, pluralCategories } = {})=>{
     const oxlintResult = runOxlintRules({
         cwd,
         targets: sourceRoots,
@@ -134,13 +137,83 @@ const runWorkspaceSourceCheck = ({ cwd = process.cwd(), sourceRoots = [
     try {
         runRuntimeAndLocaleResourceChecks(cwd, sourceRoots, locales, pluralCategories);
     } catch (error) {
-        console.error(error instanceof Error ? error.message : 'UltraModern workspace source checks failed.');
-        return 1;
+        console.error(error instanceof Error ? error.message : String(error));
+        return error instanceof SourceViolation ? 1 : 2;
     }
     console.log(WORKSPACE_SOURCE_SUCCESS);
     return 0;
 };
-const main = ()=>{
-    process.exitCode = runWorkspaceSourceCheck();
+const USAGE = `modern-i18n-check [--workspace-root <path>]
+Runs the UltraModern i18n and boundary source checks for a workspace.
+Workspace defaults to ULTRAMODERN_WORKSPACE_ROOT then cwd. Options come from
+package.json "modernjs.i18nCheck": { sourceRoots, locales, pluralCategories }.
+Exit codes: 0 valid, 1 source violation, 2 tool/configuration failure.`;
+const isStringArray = (value)=>Array.isArray(value) && value.every((entry)=>'string' == typeof entry && entry.length > 0);
+const isLocaleArray = (value)=>{
+    if (!isStringArray(value)) return false;
+    try {
+        Intl.getCanonicalLocales(value);
+        return true;
+    } catch  {
+        return false;
+    }
+};
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const isWorkspaceDirectory = (root, entry)=>{
+    if (node_path.isAbsolute(entry)) return false;
+    const target = node_path.resolve(root, entry);
+    if (!node_fs.existsSync(target) || !node_fs.statSync(target).isDirectory()) return false;
+    const relative = node_path.relative(node_fs.realpathSync(root), node_fs.realpathSync(target));
+    return '' !== relative && '..' !== relative && !relative.startsWith(`..${node_path.sep}`) && !node_path.isAbsolute(relative);
+};
+const CLDR_PLURAL_CATEGORIES = new Set([
+    'zero',
+    'one',
+    'two',
+    'few',
+    'many',
+    'other'
+]);
+const isPluralCategories = (value)=>isRecord(value) && Object.values(value).every((categories)=>isStringArray(categories) && categories.includes('other') && categories.every((category)=>CLDR_PLURAL_CATEGORIES.has(category)));
+const readWorkspaceCheckOptions = (root)=>{
+    const manifestPath = node_path.join(root, 'package.json');
+    const modernjs = JSON.parse(readText(manifestPath)).modernjs;
+    const config = isRecord(modernjs) && Object.hasOwn(modernjs, 'i18nCheck') ? modernjs.i18nCheck : {};
+    const invalid = (field, expected)=>new Error(`${manifestPath} "modernjs.i18nCheck${field}" must be ${expected}.`);
+    if (!isRecord(config)) throw invalid('', 'an object');
+    const { locales, pluralCategories } = config;
+    if (void 0 !== locales && !isLocaleArray(locales)) throw invalid('.locales', 'an array of BCP 47 locale codes');
+    if (void 0 !== pluralCategories && !isPluralCategories(pluralCategories)) throw invalid('.pluralCategories', 'an object of locale -> CLDR plural categories including "other"');
+    const sourceRoots = Object.hasOwn(config, 'sourceRoots') ? config.sourceRoots : DEFAULT_SOURCE_ROOTS.filter((entry)=>isWorkspaceDirectory(root, entry));
+    if (!isStringArray(sourceRoots) || 0 === sourceRoots.length || !sourceRoots.every((entry)=>isWorkspaceDirectory(root, entry))) throw invalid('.sourceRoots', `a non-empty array of existing workspace-relative directories (default: whichever of ${DEFAULT_SOURCE_ROOTS.join(', ')} exist)`);
+    return {
+        cwd: root,
+        sourceRoots,
+        locales,
+        pluralCategories
+    };
+};
+const runWorkspaceSourceCheckCli = (args = process.argv.slice(2))=>{
+    let workspaceRoot = process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd();
+    for(let index = 0; index < args.length; index += 1){
+        const argument = args[index];
+        if ('--help' === argument || '-h' === argument) {
+            console.log(USAGE);
+            return 0;
+        }
+        const value = args[index + 1];
+        if ('--workspace-root' !== argument || !value || value.startsWith('--')) {
+            console.error(`Invalid argument: ${argument ?? ''}. Use --help.`);
+            return 2;
+        }
+        workspaceRoot = value;
+        index += 1;
+    }
+    try {
+        return runWorkspaceSourceCheck(readWorkspaceCheckOptions(node_path.resolve(workspaceRoot)));
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
 };
-export { main, runWorkspaceSourceCheck };
+export { runWorkspaceSourceCheck, runWorkspaceSourceCheckCli };