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

package/dist/esm/oxlint-plugin/rules/strict-effect-api-boundaries.js

@@ -20,7 +20,7 @@ const createStrictEffectApiBoundariesRule = ()=>({
                     });
                     reportProgramPattern(context, node, source, /@modern-js\/plugin-bff\/(?:server|hono-server)(?![\w-])/u, 'UltraModern API workspaces must not import Hono server helpers; use @modern-js/bff-effect/effect-edge and HttpApi.');
                     reportProgramPattern(context, node, source, /\bruntimeFramework\s*(?::|=)\s*['"]hono['"]/u, 'UltraModern API apps must use bff.runtimeFramework: "effect".');
-                    reportProgramPattern(context, node, source, /(?:from|import)\s*['"][^'"]*(?:api\/effect|shared\/effect)[^'"]*['"]|shared-effect-api/u, 'Import API code from direct api/index.ts, shared/api.ts or src/api/* paths, not api/effect, shared/effect or shared Effect API packages.');
+                    reportProgramPattern(context, node, source, /(?:from|import)\s*['"][^'"]*(?:api\/effect|shared\/effect)(?=\/|\.[cm]?[jt]sx?['"]|['"])[^'"]*['"]|shared-effect-api/u, 'Import API code from direct api/index.ts, shared/api.ts or src/api/* paths, not api/effect, shared/effect or shared Effect API packages.');
                     reportProgramPattern(context, node, source, /\bstrictEffectApproach\s*(?::|=)\s*false\b/u, 'UltraModern API apps must keep strictEffectApproach enabled.');
                     if (isApiEntryFile(filename)) {
                         const violation = strictEffectRuntimeTopologyViolation(source, createEffectApiImportResolver(filename));

package/dist/esm/source-analysis.js

@@ -0,0 +1,48 @@
+import { parse } from "@babel/parser";
+import traverse, { Hub, NodePath } from "@babel/traverse";
+import * as __rspack_external__babel_types_6e8337dd from "@babel/types";
+const consumerParserPlugins = (filePath)=>/\.[jt]sx$/u.test(filePath) ? [
+        "typescript",
+        'decorators',
+        'decoratorAutoAccessors',
+        'jsx'
+    ] : [
+        "typescript",
+        'decorators',
+        'decoratorAutoAccessors'
+    ];
+class SourceSyntaxError extends Error {
+}
+class SourceValidationHub extends Hub {
+    buildError(_node, message) {
+        return new SourceSyntaxError(message);
+    }
+}
+function parseSource(source, filename, syntaxMessage) {
+    try {
+        return parse(source, {
+            sourceType: 'module',
+            sourceFilename: filename,
+            plugins: consumerParserPlugins(filename)
+        });
+    } catch (cause) {
+        if ('object' == typeof cause && null !== cause && 'code' in cause && 'BABEL_PARSER_SYNTAX_ERROR' === cause.code && 'reasonCode' in cause && 'string' == typeof cause.reasonCode) throw new SourceSyntaxError(syntaxMessage ?? (cause instanceof Error ? cause.message : String(cause)));
+        throw cause;
+    }
+}
+function traverseSource(file, visitor) {
+    const program = NodePath.get({
+        hub: new SourceValidationHub(),
+        parentPath: void 0,
+        parent: file,
+        container: file,
+        key: 'program'
+    });
+    program.setContext();
+    traverse(file, visitor, program.scope, void 0, program);
+}
+function unwrapExpression(node, includeAssertions = false) {
+    while(__rspack_external__babel_types_6e8337dd.isTSAsExpression(node) || __rspack_external__babel_types_6e8337dd.isParenthesizedExpression(node) || __rspack_external__babel_types_6e8337dd.isTSSatisfiesExpression(node) || includeAssertions && (__rspack_external__babel_types_6e8337dd.isTSTypeAssertion(node) || __rspack_external__babel_types_6e8337dd.isTSNonNullExpression(node) || __rspack_external__babel_types_6e8337dd.isTSInstantiationExpression(node)))node = node.expression;
+    return node;
+}
+export { SourceSyntaxError, consumerParserPlugins, parseSource, traverseSource, unwrapExpression };

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

@@ -1,23 +1,25 @@
 import node_fs from "node:fs";
 import node_path from "node:path";
-import { parse } from "@babel/parser";
-import traverse, { Hub, NodePath } from "@babel/traverse";
+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 sharedRuntime = /^@[^/]+\/shared-contracts\/server\/effect-bff-runtime$/u;
-const failure = 'Generated API entries must export defineEffectBff(...) or the server-only shared Effect BFF assembly helper with an explicitly composed handler Layer and an unshadowed executable root; entries must implement handlers through HttpApiBuilder.group.';
-const invalidSources = new WeakSet();
-function invalidSource(message) {
-    const error = new Error(message);
-    invalidSources.add(error);
-    return error;
-}
-class SourceValidationHub extends Hub {
-    buildError(_node, message) {
-        return invalidSource(message);
-    }
-}
+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;
+const httpRouteMethods = new Set([
+    '*',
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'HEAD',
+    'OPTIONS',
+    'TRACE',
+    'CONNECT',
+    'QUERY'
+]);
 function createEffectApiImportResolver(filename) {
     const directory = node_fs.realpathSync(node_path.dirname(filename));
     const owner = node_fs.realpathSync(node_path.resolve(directory, '..'));
@@ -49,34 +51,14 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
     const load = (input)=>{
         const existing = modules.get(input.id);
         if (existing) return existing;
-        if (modules.size >= 64 || input.source.length > 1000000) throw invalidSource('API source budget exceeded');
-        let file;
-        try {
-            file = parse(input.source, {
-                sourceType: 'module',
-                sourceFilename: input.id,
-                plugins: [
-                    "typescript"
-                ]
-            });
-        } catch (cause) {
-            if ('object' == typeof cause && null !== cause && 'code' in cause && 'BABEL_PARSER_SYNTAX_ERROR' === cause.code && 'reasonCode' in cause && 'string' == typeof cause.reasonCode) throw invalidSource('Invalid API syntax');
-            throw cause;
-        }
+        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);
-        const program = NodePath.get({
-            hub: new SourceValidationHub(),
-            parentPath: void 0,
-            parent: file,
-            container: file,
-            key: 'program'
-        });
-        program.setContext();
-        traverse(file, {
+        traverseSource(file, {
             enter (nodePath) {
                 paths.set(nodePath.node, nodePath);
                 owners.set(nodePath.node, module);
@@ -85,9 +67,12 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
                 })) {
                     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);
+                    let binding = __rspack_external__babel_types_6e8337dd.isIdentifier(target) ? nodePath.scope.getBinding(target.name) : void 0;
+                    while(binding && !mutated.has(binding)){
+                        mutated.add(binding);
+                        const declarator = binding.path.node;
+                        const alias = 'const' === binding.kind && __rspack_external__babel_types_6e8337dd.isVariableDeclarator(declarator) && declarator.init ? unwrapExpression(declarator.init, true) : void 0;
+                        binding = __rspack_external__babel_types_6e8337dd.isIdentifier(alias) ? binding.path.scope.getBinding(alias.name) : void 0;
                     }
                 }
                 if (nodePath.isTSModuleDeclaration() && __rspack_external__babel_types_6e8337dd.isIdentifier(nodePath.node.id)) {
@@ -95,7 +80,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
                     if (binding) mutated.add(binding);
                 }
             }
-        }, program.scope, void 0, program);
+        });
         return module;
     };
     try {
@@ -104,10 +89,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
             source,
             resolveImport
         });
-        const unwrap = (node)=>{
-            while(__rspack_external__babel_types_6e8337dd.isParenthesizedExpression(node) || __rspack_external__babel_types_6e8337dd.isTSSatisfiesExpression(node) || __rspack_external__babel_types_6e8337dd.isTSAsExpression(node) || __rspack_external__babel_types_6e8337dd.isTSTypeAssertion(node) || __rspack_external__babel_types_6e8337dd.isTSNonNullExpression(node))node = node.expression;
-            return node;
-        };
+        const unwrap = (node)=>unwrapExpression(node, true);
         const binding = (node)=>{
             node = unwrap(node);
             if (!__rspack_external__babel_types_6e8337dd.isIdentifier(node)) return;
@@ -132,15 +114,15 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
         const namespaceSources = {
             HttpApi: [
                 edge,
-                'effect/unstable/httpapi'
+                'effect/http-api'
             ],
             HttpApiBuilder: [
                 edge,
-                'effect/unstable/httpapi'
+                'effect/http-api'
             ],
             HttpRouter: [
                 edge,
-                'effect/unstable/http'
+                'effect/http'
             ]
         };
         const native = (node, name, sources)=>{
@@ -236,7 +218,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
             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.isReturnStatement(last) ? last.argument : void 0;
+            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'
@@ -265,11 +247,48 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
                 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 effectSources = [
+            edge,
+            'effect',
+            'effect/Effect'
+        ];
+        const routeHandler = (node)=>{
+            node = unwrap(node);
+            if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node) || !method(node.callee, 'HttpRouter', 'add') || 3 !== node.arguments.length) return;
+            const [verb, route, handler] = node.arguments;
+            return __rspack_external__babel_types_6e8337dd.isStringLiteral(verb) && httpRouteMethods.has(verb.value) && __rspack_external__babel_types_6e8337dd.isStringLiteral(route) && (route.value.startsWith('/') || '*' === route.value) && (__rspack_external__babel_types_6e8337dd.isArrowFunctionExpression(handler) || __rspack_external__babel_types_6e8337dd.isFunctionExpression(handler)) ? handler : void 0;
+        };
+        const effectReference = (node)=>guarded(node, (node)=>{
+                const init = initialized(node);
+                if (init) return __rspack_external__babel_types_6e8337dd.isIdentifier(unwrap(init)) && effectReference(init);
+                const value = imported(node);
+                return !!value && !value.namespace;
+            });
+        const capturedRouteFactory = (node)=>guarded(node, (node)=>{
+                const init = initialized(node) ?? externalValue(node);
+                if (init) return capturedRouteFactory(init);
+                if (!__rspack_external__babel_types_6e8337dd.isArrowFunctionExpression(node) || node.async || 1 !== node.params.length || !__rspack_external__babel_types_6e8337dd.isIdentifier(node.params[0]) || __rspack_external__babel_types_6e8337dd.isBlockStatement(node.body)) return false;
+                const handler = routeHandler(node.body);
+                const parameter = binding(node.params[0]);
+                return !!handler && !!parameter && parameter.referencePaths.some((reference)=>!!reference.findParent((path)=>path.node === handler));
+            });
+        const capturedTransport = (node)=>guarded(node, (node)=>{
                 const init = initialized(node);
-                if (init) return transport(init);
+                if (init) return capturedTransport(init);
+                if (!__rspack_external__babel_types_6e8337dd.isCallExpression(node)) return false;
+                if (method(node.callee, 'Effect', 'map', effectSources)) return 2 === node.arguments.length && effectReference(node.arguments[0]) && capturedRouteFactory(node.arguments[1]);
+                if (!__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 || !effectReference(node.callee.object)) return false;
+                const map = unwrap(node.arguments[0]);
+                return __rspack_external__babel_types_6e8337dd.isCallExpression(map) && method(map.callee, 'Effect', 'map', effectSources) && 1 === map.arguments.length && capturedRouteFactory(map.arguments[0]);
+            });
+        const transport = (node, provided = false)=>guarded(node, (node)=>{
+                const init = initialized(node) ?? externalValue(node);
+                if (init) return transport(init, provided);
                 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 providedHere = provided || node.arguments.some((argument)=>__rspack_external__babel_types_6e8337dd.isCallExpression(argument) && method(argument.callee, 'Layer', 'provide', layerSources) && 1 === argument.arguments.length);
+                return pipe(node, (value)=>transport(value, providedHere)) || void 0 !== routeHandler(node) || provided && method(node.callee, 'Layer', 'unwrap', layerSources) && 1 === node.arguments.length && capturedTransport(node.arguments[0]) || method(node.callee, 'HttpRouter', 'cors') || method(node.callee, 'Layer', 'mergeAll', layerSources) && node.arguments.length > 0 && node.arguments.every((argument)=>transport(argument, provided));
             });
         const directLayer = (node, api)=>guarded(node, (node)=>{
                 const init = initialized(node);
@@ -301,7 +320,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
             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',
+                'effect/rpc',
                 '@modern-js/bff-effect/effect-client'
             ])) return false;
             const layerInit = initialized(layer) ?? unwrap(layer);
@@ -325,7 +344,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
                 if (value?.name === 'defineEffectBff' && [
                     edge,
                     nodeRuntime
-                ].includes(value.specifier) || value?.name === 'assembleEffectBffRuntime' && sharedRuntime.test(value.specifier)) {
+                ].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;
@@ -348,7 +367,7 @@ function strictEffectRuntimeTopologyViolation(source, resolveImport) {
         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 ('object' == typeof cause && null !== cause && invalidSources.has(cause)) return failure;
+        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

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

@@ -1,28 +1,47 @@
 import "node:module";
+import node_path from "node:path";
+import { pathToFileURL } from "node:url";
 import { checkMicroVerticalApiBoundaries, checkMicroVerticalApiConsumerFiles } from "../microvertical-api-boundary.js";
-function runMicroVerticalApiCheckCli(args = process.argv.slice(2), filesOnly = false) {
+const flags = [
+    '--workspace-root',
+    '--baseline-package-directory',
+    '--rules'
+];
+async function loadSourceRules(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 source 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>]\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.'}\nWorkspace defaults to ULTRAMODERN_WORKSPACE_ROOT then cwd. Exit codes: 0 valid, 1 consumer violation, 2 tool/configuration failure.`);
+            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.'}\nThe baseline owner defaults to each contract's native package resolver. --baseline-package-directory requires that exact installed owner for every contract.\n--rules loads a module whose default export is an array of source rules; each rule runs once per workspace source file with the shared module graph.\nWorkspace defaults to ULTRAMODERN_WORKSPACE_ROOT then cwd. Exit codes: 0 valid, 1 consumer violation, 2 tool/configuration failure.`);
             return 0;
         }
-        if (![
-            '--workspace-root',
-            '--baseline-package-directory'
-        ].includes(argument ?? '') || !args[index + 1] || args[index + 1]?.startsWith('--')) {
+        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 sourceRules = [];
+    for (const file of ruleFiles)try {
+        sourceRules.push(...await loadSourceRules(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
+        baselinePackageDirectory,
+        sourceRules
     });
     for (const diagnostic of result.diagnostics)console.error(`API violation: ${diagnostic}`);
     for (const error of result.toolErrors)console.error(`API tool error: ${error}`);

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