@zohodesk/client_build_tool 0.0.11-exp.15 → 0.0.11-exp.15.2

package/docs/client_build_tool_source_doc.md

@@ -0,0 +1,390 @@
+# Client Build Tool — Source Documentation
+
+This document summarizes functionality, imports/exports, and key APIs for each source file in `packages/client_build_tool`, excluding `node_modules`, built `lib/dist/build` outputs, and OS/editor artifacts. It is maintained as a single, append-only reference. In addition, the first sections provide a narrative of the overall architecture and flows so you can answer “how does this work?” end-to-end.
+
+## Architecture Overview
+
+- **Purpose:** A configurable client build tool and dev server wrapper that standardizes Webpack, Babel, and PostCSS setup for React apps, with advanced features such as i18n chunking/indexing, RTL splitting, CDN path customization, EFC SDK generation, and service worker support.
+- **Execution model:**
+  - CLI entry `cli.js` resolves arguments and delegates to `src/commandsRouter.js`.
+  - Each command (`start`, `buildEs`, `buildLib`, `mockServer`, `pre_process`, `template`, `version`) lives under `src/commands/<name>` with a lifecycle of optional files: `optionsProcessor` → `deprecationHandler` → `preProcessor` → `commandExecutor` → `postProcessor`.
+  - Configuration is resolved once via `src/schemas/readOptions.js` from three sources: defaults (`defaultConfigValues.js`) + user config (package.json or `cbt.config.js`) + CLI/env (npm_config_*, `--key=value`).
+- **Build pipeline:**
+  - For app builds: Webpack 5 configured via `src/shared/bundler/webpack/webpackConfig.js` (entry/output/loaders/plugins/stats/resolve/optimization/devtool).
+  - For library/ES transpiles: file-watcher pipeline (`watchRun.js`) dispatches to Babel/PostCSS/copy based on file extension.
+- **Dev server:**
+  - Express app with permissive CORS, optional mock API proxy, and webpack-dev-middleware. HTTP and HTTPS listeners are started concurrently using computed publicPath/ports.
+  - Initial HTML is dynamically modified for mock/demo of locale/dir, and to normalize protocol.
+- **i18n support:**
+  - Two modes:
+    - Chunk split at build-time (`I18nSplitPlugin`) to emit per-locale chunks and runtime loader glue.
+    - Numeric indexing (`I18nNumericIndexPlugin`) to emit numeric-keyed resources (optionally single-file mode) and inject initial assets tags into HTML.
+- **CSS and RTL:**
+  - PostCSS pipeline with custom plugins (selector/value replacement, hover/active media split, variable modifications).
+  - Build-time RTL split emits `[dir]`-templated CSS names and rewrites paths in HTML/runtime where needed.
+- **Extensibility:**
+  - Pluggable PostCSS plugins with per-file pattern filters.
+  - Webpack plugin config layer for toggling features via options.
+  - Custom loaders via `options.customLoaders` and module resolution override via `resolve.moduleResolvePath`.
+  - Quick Start: See `init/README.md` and `init/cbt.config.example.js` for installation, scripts, and a minimal configuration you can copy into your app.
+
+## End-to-End Flows
+
+- **Start dev server (`cbt start`)**
+  - CLI → `route('start')` → `optionsProcessor` computes server extras (ports/URLs/https), publicPath, context folder.
+  - Optional `preProcessor` runs app-provided script under `nodemon` (e.g., generators/mocks).
+  - `commandExecutor` boots Express (`initExpressApp`) + CORS + mock API + webpack-dev-middleware with `webpackConfigCreator(options)`.
+  - Servers: `startHttpsServer` (if cert package available) and `startHttpServer`. `initialHTMLHandling` serves `index.html` with optional template token replacements for locale/dir.
+
+- **Transpile to ES or lib (`cbt build:es` / `cbt build:lib`)**
+  - CLI → `route('buildEs'|'buildLib')` → parse `extraArgs` for `src` and `target` (defaults to `app/src` and `app/es|lib`).
+  - Optional pre-process runs once or in watch mode.
+  - `watchRun` performs a single pass (and optionally watches):
+    - `.js` → Babel (`runBabelForJSFile` with `babelWebConfig`)
+    - `.ts,.tsx` → Babel TS path with TS preset when `typeScript.enable` is true
+    - `.css` → PostCSS (`runPostCssForCssFile`) with plugins allowed by file patterns
+    - others → streamed copy
+
+- **App build (via dev-middleware and plugin stack)**
+  - `webpackConfigCreator` composes:
+    - `entryConfig`: `main` plus optional EFC entry
+    - `outputConfig`: hashed name templates, `publicPath`, JSONP global
+    - loaders: `babel-loader`, TSX, CSS (MiniCssExtractPlugin + PostCSS), assets, workers, HTML templates
+    - plugins (order matters): env defines → attributes → TP hash mapping → copy public → ignore → CSS extract → selector weight → variable conversion → i18n split → RTL CSS → HTML → i18n numeric index → custom script loading → CDN mapping → SW → EFC SDK → resource hints → bundle analyzer → manifests → source maps → progress → integrity report → runtime cleanup → user `webpackPlugins`
+    - optimization: Terser/CSS minimizers, split-chunks (vendor/react + custom groups), runtime chunk naming (locale suffix when needed)
+
+- **Mock API**
+  - If `mockServer.enable` and `separateSeverPort`: proxy `mockPrefix` (default `/api`) to the external mock server (you can run `cbt mock:server`).
+  - Otherwise, mount the app’s mock file path (resolved via `joinWithAppPath`) under the Express app.
+
+- **i18n flows**
+  - Chunk split: Emit per-locale chunk files using templates from `nameTemplates('i18njs')`, a manifest, and runtime assembly for loading.
+  - Numeric index: Parse source `.properties` and JS resources, generate either per-locale numeric/dynamic files or a single-file bundle, optionally with contenthash and a manifest; inject initial assets in HTML.
+
+- **CDN & runtime URL control**
+  - `CdnChangePlugin` can prefix JS/CSS/i18n URLs with template placeholders and patch Webpack runtime to use a global variable for chunk paths (e.g., SMAP variable). Works together with separate source maps if enabled.
+
+## Configuration Resolution & Validation
+
+- **Sources & precedence:**
+  - Base schema: `src/schemas/defaultConfigValues.js` (supports nested keys and CLI aliases via `cli` field)
+  - User config: `package.json[react-cli]` or `cbt.config.js` (via `--config_file`)
+  - CLI args/env: `npm_config_*` and inline `--key=value` become camel/underscore keys per parser rules
+  - Merger: `applyValuesToSchema` recursively resolves each schema leaf, preferring CLI/env over user config over defaults
+- **Compatibility shims:**
+  - `app_domain`, `app_port`, `app_host` CLI/env keys map to `domain`, `port`, `host`; `app_domain === 'kubernetes'` enables `server.k8s`
+  - `deprecatedOptionsHandler` mutates legacy keys and prints warnings
+- **Validation:**
+  - `configValidator` exposes `validateConfig`/`validateConfigWithWarnings`, type guards, path checks, port ranges, and i18n-indexing cross-field constraints (e.g., templates must contain `[locale]`).
+
+## Extensibility & Customization
+
+- **PostCSS:**
+  - Enable or disable built-ins in `options.css.plugins` and scope them by `patterns`.
+  - Add custom plugins via `options.css.customPlugins` (string module path or function) with per-file patterns.
+- **Webpack:**
+  - Pass additional plugin instances in `options.webpackPlugins`.
+  - Add custom webpack loaders via `options.customLoaders`.
+  - Override module resolution root via `options.resolve.moduleResolvePath` (local/global resolver package), or prefer local node_modules first.
+- **Paths & templates:**
+  - Control asset name templates and hashing via `nameTemplates`-related options (`enableFileNameHashing`, `devLikeHash`, etc.).
+  - Configure publicPath calculation and server URLs using `server` and `context` options.
+- **EFC SDK:**
+  - Enable `options.efc.hasEFC` and `createSDkFile` to emit a templated SDK file with initial assets function and publicPath injection.
+
+## Operational Notes
+
+- **Node support:** `doBasicRequirementCheck` enforces Node v14–v18.
+- **Verbose logging:** Set `VERBOSE=true` to enable `verboseLogger` output (yellow-tagged logs).
+- **HTTPS certs:** `server.httpsCerts` may refer to a local/global npm package exposing `{ httpsOptions }`. Defaults to `@zohodesk-private/client_dev_cert` if present globally.
+- **Cross-origin & CSP:** `InitialHtmlPlugin` injects a nonce attribute placeholder into tags; `corsHandling` sets permissive headers for dev.
+- **Kubernetes:** With `server.k8s=true`, server URL resolves to `https://<domain>/` without explicit port; otherwise dual-port scheme is used (HTTPS `port`, HTTP `port+1`).
+
+
+## CLI Entrypoint
+
+### cli.js
+- Purpose: Executable entry; polyfills, prints version, parses CLI option/args, routes command.
+- Imports: `./polyfillForOldNodeVersion`, `./lib/logger`, `./lib/commandsRouter`, `./lib/shared/commands-utils`, `./lib/shared/utils/versionPrint` (built outputs).
+- Exports: none; runs on invoke.
+- Flow: Calls `polyfillForOldNodeVersion()`, logs banner via `verboseLogger`, `versionPrint(verboseLogger)`, reads option/args, `doBasicRequirementCheck()`, then `route(option)`.
+
+### polyfillForOldNodeVersion.js
+- Purpose: Adds `String.prototype.replaceAll` for older Node versions.
+- Exports: `polyfillForOldNodeVersion()` (CommonJS `exports`).
+
+## Public API
+
+### src/index.js
+- Purpose: Thin programmatic API for running commands.
+- Imports: `runCommand` from `./commandsRouter`.
+- Exports: `run(commandName, options)` → `runCommand`.
+
+## Command Router and Logging
+
+### src/commandsRouter.js
+- Purpose: Dispatches a command through standard lifecycle steps.
+- Imports: `fs.existsSync`, `path.join`, `allCommandsConfigs`, `{ errorLogger, verboseLogger, warnLogger }`, `getOptions`.
+- Exports:
+  - `runCommand(commandName, options)`: Locates matching command config; dynamically requires and executes files in the command dir: `optionsProcessor`, `deprecationHandler`, `preProcessor`, `commandExecutor`, `postProcessor` (if present).
+  - `route(commandName)`: Builds `options` via `getOptions()` and calls `runCommand` with error logging.
+- Internal: `findCommandConfig(option)` checks by `name` or `alias`.
+
+### src/logger.js
+- Purpose: CLI logging helpers.
+- Exports: `verboseLogger`, `warnLogger`, `messageLogger`, `debugLogger`, `errorLogger`.
+
+### src/allCommandsConfigs.js
+- Purpose: Auto-discovers `src/commands/*/config.js` and aggregates default exports.
+- Exports: default array of configs.
+
+## Commands
+
+### start (src/commands/start/*)
+- config.js: Default export `{ name: 'start', alias: ['dstart','devSeverStart'], dirname }`.
+- optionsProcessor.js:
+  - Computes `serverExtras` (ports, URLs, HTTPS options), `publicPath` (unless `noPublicPath`), `contextFolderPath` via `joinWithAppPath`, and normalizes `mode` to `dev|prod`.
+  - Exports: `optionsProcessor(options)`.
+- preProcessor.js: Runs `runPreProcess(options, 'nodemon')` before server.
+- commandExecutor.js: Starts dev server via `shared/server/serverBywebpackDevMiddleware.run(options)`.
+
+### buildEs (src/commands/buildEs/*)
+- config.js: Default export `{ name: 'buildEs', alias: ['build_es','build:es'], dirname }`.
+- preProcessor.js: Detects `-w` watch; runs `runPreProcess` with `'nodemon'` if watch else `'node'`.
+- commandExecutor.js: Parses `[src,target]` from `extraArgs` (defaults `src -> app/src`, `target -> app/es`), then calls `watchRun({ mode: 'es' })`.
+
+### buildLib (src/commands/buildLib/*)
+- config.js: Default export `{ name: 'buildLib', alias: ['build:lib','build_lib'], dirname }`.
+- preProcessor.js: Same watch handling as buildEs.
+- commandExecutor.js: Defaults `target -> app/lib`, runs `watchRun({ mode: 'lib' })`.
+
+### mockServer (src/commands/mockserver/*)
+- config.js: Default export `{ name: 'mockServer', alias: ['mockserver','mock_server','mock-server','mock:server'], dirname }`.
+- commandExecutor.js:
+  - Reads `options.mockServer { enable, separateSeverPort, mockEntryFile, disableNodemon }`.
+  - If separate port: proxies requests; otherwise runs CLI-managed mock server; logs target paths.
+
+### pre_process (src/commands/pre_process/*)
+- config.js: Default export `{ name: 'pre_process', alias: ['preprocess','pre:process','preProcess'], dirname }`.
+- commandExecutor.js: Detects `-w`; runs preprocessing via `runPreProcess`. Exits with status when not watching.
+
+### template (src/commands/template/*)
+- config.js: Default export `{ name: 'template', alias: ['template','templates'], dirname }`.
+- commandExecutor.js: Supports templates: `app`, `library`. Copies with `cp -r getTemplatePath(templateName)` using `spawnSyncIO`.
+
+### version (src/commands/version/*)
+- config.js: Default export `{ name: 'version', alias: ['v','-v','--v','-version','--version'], dirname }`.
+- commandExecutor.js: Invokes `versionPrint(messageLogger)`.
+
+## Schemas and Options
+
+### src/schemas/defaultConfigValues.js
+- Purpose: Full schema describing options, defaults, and CLI mapping keys for `applyValuesToSchema`.
+- Exports: default object with nested option trees (server, mockServer, css plugins, i18nChunkSplit, i18nIndexing, resolve, htmlTemplate, efc, etc.).
+- Notables: `server.k8s`, `httpsCerts`, `disableContextURL`; `mockServer` settings; rich CSS plugin customization; i18n splitting/indexing blocks; `preProcess` runner options; `typeScript.enable`; `customScriptLoadingStrategey`.
+
+### src/schemas/defaultConfigValuesOnly.js
+- Purpose: Plain default values (no CLI mapping) suitable for config file generation or validation baselines.
+- Exports: default object mirroring many keys (context, devtool, server, etc.).
+
+### src/schemas/cliArgsToObject.js
+- Purpose: Experimental parser for `--key=value` or `--flag` CLI args to an object.
+- Exports: `cliArgsToObject(cliArgs)` using `giveDefaultValue` and `key.replace(/-|:/g,'_')`.
+
+### src/schemas/giveDefaultValue.js
+- Purpose: Coerces `'true'|'false'|''` to booleans; otherwise returns the value.
+- Exports: `giveDefaultValue(value)`.
+
+### src/schemas/npmConfigToObject.js
+- Purpose: Reads `process.env.npm_config_*` into object, duplicating colon-keys with underscores to avoid conflicts (warns on collisions).
+- Exports: `npmConfigToObject()`.
+
+### src/schemas/getNpmVersion.js
+- Purpose: Best-effort major npm version detection via `npm -v` (defaults to `'6'`).
+- Exports: `getNpmVersion()`.
+
+### src/schemas/deprecatedOptionsHandler.js
+- Purpose: Mutates options to handle deprecated keys and logs warnings.
+- Exports: `deprecatedOptionsHandler(options)`; updates/aliases legacy paths (e.g., `app.context -> context`, RTL flags to new locations).
+
+### src/schemas/readOptionsForConfigFile.js
+- Purpose: Reads CBT config from package.json under `BASE_CONFIG_KEY` or from an explicit config file.
+- Imports: `BASE_CONFIG_KEY` from `shared/constants`.
+- Exports:
+  - `readOptionsForPackageJson(appPath)` → object or empty.
+  - `readOptionsForConfigFile(appPath, configFile)` → `{config}` or null.
+
+### src/schemas/applyValuesToSchema/*
+- index.js: Core merger `applyValuesToSchema(schemas, customOptions, processEnv)` that:
+  - For leaf schema: returns `customOptions[key] ?? default` unless `cli` is present, in which case it prefers `processEnv[cli]`.
+  - For objects: recurses into nested schema.
+  - Also exports helpers `isObject(obj)` and `isValid(value, fallback)`.
+- isObject.js: Same object guard as above (non-null object and not array).
+- isValid.js: Nullish coalescing with a `Number.isNaN` guard for numbers.
+
+### src/schemas/readOptions.js
+- Purpose: Composes final `options` for the CLI by merging defaults, package/config file, and environment/CLI args.
+- Exports:
+  - `args`: `process.argv.slice(2)`.
+  - `getOptions()`: Memoized; merges `defaultConfigValues` with config sources via `applyValuesToSchema`, runs `deprecatedOptionsHandler`, attaches `npmVersion`, `cwd`, `packageVersion`, `extraArgs`, and `commandOption`.
+  - CLI compatibility shims: maps `app_domain|app_port|app_host` into `domain|port|host` and infers `k8s`.
+
+### src/schemas/configValidator.js
+- Purpose: Runtime validators and a structured `ConfigValidationError`.
+- Exports:
+  - `ConfigValidationError` (class).
+  - `validateType`, `validateFilePath`, `validateDirectoryPath`, `validatePort`.
+  - `validateI18nIndexingDependencies(i18nConfig, basePath)`.
+  - `validateConfig(config, basePath)` and `validateConfigWithWarnings(config, basePath, strict)`; the latter logs warnings instead of throwing.
+
+## Shared Constants and Preprocess
+
+### src/shared/constants.js
+- Purpose: Paths and constants used across the tool.
+- Exports: `BASE_CONFIG_KEY='react-cli'`, `cliRootPath`, `CONFIG_ROOT`, `cliNodeModulesPath`, `babelrcPath`, `appPath`, `joinWithAppPath(filePath)`, `appNodeModules`, `templatesPath`, `getTemplatePath(...filePath)`.
+
+### src/shared/pre_process/runPreProcess.js
+- Purpose: Executes an app-provided preprocess script under `nodemon` or `node`.
+- Exports: `runPreProcess(options, runnerCli='node')` which resolves the app runner path, watches the directory for changes when using nodemon, and returns the spawn result. Logs and exits if path is missing.
+
+## Build Pipeline Helpers
+
+### src/shared/fileUtils/directoryIterator.js
+- Purpose: Depth-first traversal; invokes callback for files and recurses into directories.
+- Exports: `directoryIterator(filename, cb)`.
+
+### src/shared/fileUtils/copyFile.js
+- Purpose: Ensure parent dirs exist and copy a file stream-to-stream.
+- Exports: `createParentDir`, `copyFile(filename, outputFile)`, `writeFile(filename, data)`.
+
+### src/shared/fileUtils/watchRun.js
+- Purpose: One-shot and watch-based compilation/copy pipeline for JS/TS/CSS/other assets.
+- Exports: `watchRun({ options, src, target, canWatch, mode })` that dispatches by ext to Babel or PostCSS, copies others, prints counts/timing, and sets up `Watcher` if `canWatch`.
+
+### src/shared/commands-utils/*
+- doBasicRequirementCheck.js: Throws if Node major version not in [14..18].
+- getCliPath.js: Resolves binaries from CLI-local `node_modules/.bin` (adds `.cmd` on Windows); falls back to bare name.
+- readArgsFormCommandLine.js / readOptionFormCommandLine.js: Simple argv readers.
+- log.js: Minimal passthrough logger.
+- index.js: Re-exports the above.
+
+### src/shared/commands-utils/spawnSyncIO.js
+- Purpose: Spawn wrappers with CLI-local binary resolution.
+- Exports: `defaultSpawnSyncOptions`, `spawnSyncIO(commandName, args, options)`, `spawnIO(commandName, args, cb)` with error logging.
+
+## Dev Server Composition
+
+### src/shared/server/*
+- corsHandling.js: Adds permissive CORS headers and handles `OPTIONS` preflight.
+- initExpressApp.js: Creates and configures Express app with JSON/urlencoded.
+- configWebpackDevMiddleware.js: Creates webpack config, compiler, and applies dev middleware with headers and stats.
+- startHttpsServer.js: Starts HTTPS server when `httpsOptions` is available; logs URL.
+- startHttpServer.js: Starts HTTP listener; logs URL.
+- initialHTMLHandling.js: Serves index HTML at `contextURL/*`, applies mock replacements for locale/dir, and flips https→http if request protocol is HTTP.
+- mockApiHandler.js: If `mockServer.enable`, proxies to external mock server or mounts in-process handler based on options.
+- getServerURL.js: `getServerDomain({host,domain,k8s})` and `getServerUrl({domain,k8s,port,protocol})` helpers.
+- httpsOptions.js: `httpsOptionsWithUserFriendlyError(options)` loads certs from configured/local/global packages; logs user-friendly errors and exits if misconfigured.
+- urlConcat.js: Joins base URL and path with slash-normalization.
+- getIp.js: Returns first IPv4 address or `127.0.0.1`.
+- serverBywebpackDevMiddleware.js: Orchestrates middleware composition and starts HTTP/HTTPS servers.
+
+## Webpack Bundler (Configs and Utilities)
+
+### Core config
+- webpackConfig.js: Composes entry/output, loaders (JS/TS/CSS/assets), plugins, externals, resolve, and stats; uses `getWebpackMode`.
+- plugins.js: Returns ordered plugin instances based on options (HTML, i18n split, RTL CSS, CDN, SW, EFC SDK, manifests, resource hints, integrity report, etc.).
+- entryConfig.js: Adds `main` entry and optional EFC entry.
+- outputConfig.js: Sets `filename`, `chunkFilename`, `publicPath`, `chunkLoadingGlobal` and target output path; supports `crossorigin`.
+- jsLoaders.js: Applies `babel-loader` (+ optional i18n ID replace loader when numeric indexing is enabled).
+- tsLoaders.js: Adds TSX support via Babel.
+- cssLoaders.js and getCSSLoaders.js: Configure MiniCssExtractPlugin, css-loader, and PostCSS.
+- loaderConfigs/*: Asset loaders, HTML template loader, Web Worker loader, Babel loader wrapper, and `checkIsPatternsMatchFilename` using `ignore` syntax.
+- splitChunksConfig.js: Builds default vendor/react cache groups and user-defined custom cache groups using filename pattern tests.
+- optimizationConfig.js: Terser + CSS minimizer, runtime chunk naming (optionally locale-suffixed when i18n chunks use contenthash).
+- statsConfig.js: Minimal stats with overrides via `options.statsLogConfig`.
+- devtoolConfig.js: Enables `devtool` only when `createSeparateSMap` is true.
+- externals.js: Adds `ZC: '$ZC'` and merges `options.externals`.
+- resolvers.js: Module and loader resolvers with optional package-group resolver; merges default library alias map; extension list `.ts,.js,.json,.tsx`.
+
+### Webpack common helpers
+- common/nameTemplates.js: Template names (dev vs prod) for assets; `nameTemplates(type, options)`, `isI18nFile(url)`.
+- common/modeUtils.js: Mode helpers and JSONP global naming.
+- common/decidePublicPath.js: Builds server extras and selects `publicPath`.
+- common/resourceBasedPublicPath.js: Returns public path or JS expression for i18n resources.
+- common/libAlias.js: Maps internal packages from `/lib` to `/es`.
+
+### Webpack plugin configs (selected)
+- configHtmlWebpackPlugin.js: Wraps InitialHtmlPlugin with minifier options and template path.
+- configCdnChangePlugin.js: Enables CDN URL rewriting in production via CdnChangePlugin.
+- configCopyPublicFolders.js: Copies app public folders to build output; supports defaults and merging with `...` placeholder.
+- configMiniCSSExtractPlugin.js: Emits CSS filenames (with `[dir]` variants when RTL split is enabled).
+- configI18nSplitPlugin.js: Configures i18n chunk splitting with filename templates and publicPath.
+- configI18nNumericIndexPlugin.js: Validates i18n indexing settings, reads resources, and returns NumericIndex + HTML injector plugins.
+- configEFCTemplatePlugin.js: Generates an EFC SDK file based on a template and initial assets.
+- configServiceWorkerPlugin.js: Emits service worker with awareness of i18n/RTL assets.
+- configResourceHintsPlugin.js: Adds runtime resource hinting hooks.
+- configRuntimeResourceCleanup.js: Injects runtime cleanup when EFC and resource cleanup are enabled.
+- configManifestJsonPlugin.js: Emits asset manifests for app, i18n, and license files.
+- configSelectorWeightPlugin.js: Applies selector weighting plugin based on config.
+- configBundleAnalyzer.js: Adds Webpack Bundle Analyzer for production when enabled.
+- configBundleIntegrityReport.js: Emits a trimmed stats JSON report at build end.
+- configEnvVariables.js: Injects environment defines based on dev/prod and `disableReactDevWarning`.
+- configTPHashMappingPlugin.js: Emits a mapping file of hashed filenames to a variable for TP integration.
+- configSourceMapPlugin.js: Adds separate source map plugin when enabled.
+- configCustomAttributesPlugin.js: Injects custom attributes into tags in generated HTML.
+- configCustomScriptLoadingStrategyPlugin.js: Applies per-file script loading strategies (blocking/defer/async/module) via tag transformation.
+
+## Webpack Custom Plugins (selected)
+
+- CustomScriptLoadingPlugin.js (class `CustomScriptLoadingStrategyPlugin`): Adds/removes `defer/async/module` attributes on selected script tags.
+- InitialHtmlPlugin.js: Thin wrapper around HtmlWebpackPlugin that injects nonce and reorders tags.
+- ResourceHintsPlugin.js: Hooks Webpack runtime to compute prefetch/preload URLs for JS/CSS/i18n chunks, honoring `publicPath`.
+- BundleIntegrityReport/index.js: Streams a filtered `stats.toJson()` to a file as a post-build report.
+- CdnChangePlugin/index.js + webpackCustomJsUrlLoader.js: Rewrites emitted asset URLs with CDN templates; patches Webpack runtime to prefix chunk filenames via a global variable.
+- RtlSplitPlugin/*:
+  - RtlCssPlugin.js: Splits CSS into LTR/RTL variants (via PostCSS RTLSplitPlugin) and adjusts output asset paths; uses OverwriteCssPathForRTL and helpers.
+  - OverwriteCssPathForRTL.js, replaceCssDirTemplate.js: Path templating and injection into runtime/HTML.
+- EFCTemplatePlugin.js (class): Generates an SDK file using a template; injects a function returning initial asset URLs; supports RTL/i18n splitting.
+- ManifestJsonPlugin/*: Adds configurable manifest JSONs (app/i18n/license) by inspecting emitted assets.
+- I18nSplitPlugin/*: Orchestrates i18n key identification, file emission, and runtime handling for on-demand i18n chunks.
+- I18nNumericIndexPlugin/*: Emits numeric-indexed i18n bundles and injects HTML placeholders for initial i18n assets.
+
+## Babel Pipeline
+
+### src/shared/babel/*
+- addDefaultPlugins.js: Returns plugin tuple when enabled.
+- babel_plugins/removeAttributesPlugin.js: Removes specified JSX attributes.
+- babelWebConfig.js: Presets/plugins for web builds; respects TS and browser targets.
+- getBabelPlugin.js: Production-only plugins from `options.babelCustomizations`.
+- runBabelForJSFile.js / runBabelForTsFile.js: Transform-and-write helpers for JS/TSX.
+
+## PostCSS Pipeline
+
+### Core helpers
+- filterPluginsAllowedForSpecficFile.js: Select built-in/custom plugins by filename patterns.
+- getAllowedPostCssPlugins.js: Returns `{ plugins: [...] }` for a file; `postcssPluginGetter(options)` closure.
+- getSpecificPostCssPlugin.js: Maps option names to actual plugin instances; supports RTL, selector/value replacement, hover/active, and variable replacement.
+- runPostCssForCssFile.js: Runs PostCSS on a file and writes output.
+
+### Custom plugins
+- RTLSplitPlugin.js: Splits CSS into LTR/RTL variants by removing opposite selectors/keyframes and minifying dir markers.
+- HoverActivePlugin/*: Moves `:hover` to `(hover:hover)` media and `:active` to `(hover:none)` with ignore comments and AST helpers.
+- SelectorReplace.js: Generic selector search/replace plugin with validation.
+- ValueReplacer.js: Replaces declaration values per prop mapping (longest-key-first replacement).
+- VariableModificationPlugin/index.js: Converts numeric CSS values into configured CSS variables and reports via error handler.
+- EmptyPlugin.js: No-op extension point.
+
+## Utilities
+
+- loaderConfigs/checkIsPatternsMatchFilename.js: Filename pattern matching with include/exclude (ignore syntax) and helpers to invert patterns.
+- utils/updateArrayWithDefault.js: Replaces `...` in an array with default values.
+- utils/getArrayWithDefaultWithCustomEqual.js: Like above with custom equality to avoid duplicates.
+- utils/propertiesParser.js: Parses `.properties` content into object or set; decodes unicode escapes.
+- utils/object-manipulation.js: Helpers for object key removal and streaming stringification.
+- utils/getFilenameFromModule.js: Extracts userRequest/filename from Webpack modules.
+
+---
+
+Progress
+- Status: Completed
+- Scope: All non-generated sources in `src` and CLI entry summarized; tests and built outputs ignored.

package/lib/schemas/defaultConfigValues.js

@@ -115,7 +115,10 @@ var _default = {
     // Name Suggestions  `customizations` this will be easier then `plugin` to understand for developers
     plugins: {
       rtlSplit: {
-        enableRTLSplit: false,
+        enableRTLSplit: {
+          value: false,
+          cli: 'enable_rtl_split'
+        },
         templateLabel: '{{--dir}}',
         disableMinifySelector: false,
         dirVarName: 'document.dir'
@@ -171,27 +174,27 @@ var _default = {
     localeVarName: 'document.documentElement.lang',
     jsonpFunc: 'console.log',
     jsResource: null,
-    propertiesFolder: null,
-    useNumericIndexing: false
+    propertiesFolder: null
   },
   i18nIndexing: {
-    enable: false,
-    devMode: false,
-    jsResourcePath: './deskapp/properties/JSResources.properties',
-    propertiesFolderPath: './deskapp/properties',
-    numericMapPath: './deskapp/properties/i18n-numeric-map.json',
+    enable: {
+      value: false,
+      cli: 'i18n_indexing'
+    },
+    jsResourcePath: null,
+    propertiesFolderPath: null,
+    numericMapPath: null,
     numericFilenameTemplate: 'i18n-chunk/[locale]/numeric.i18n.js',
     dynamicFilenameTemplate: 'i18n-chunk/[locale]/dynamic.i18n.js',
-    singleFileTemplate: 'i18n/[locale].js',
     jsonpFunc: 'window.loadI18nChunk',
     htmlTemplateLabel: '{{--user-locale}}',
     localeVarName: 'window.userLangCode',
-    singleFile: false,
-    includeContentHash: false,
-    generateManifest: false,
-    manifestPath: null
+    customGroups: null
+  },
+  publicFolders: {
+    dev: ['...'],
+    prod: ['...']
   },
-  publicFolders: ['...'],
   app: {
     entryFile: {
       value: 'src/index.js',

package/lib/schemas/defaultConfigValuesOnly.js

@@ -94,29 +94,12 @@ var _default = {
     localeVarName: 'document.documentElement.lang',
     jsonpFunc: 'console.log',
     jsResource: null,
-    propertiesFolder: null,
-    useNumericIndexing: false
+    propertiesFolder: null
   },
-  i18nIndexing: {
-    enable: false,
-    devMode: false,
-    jsResourcePath: './deskapp/properties/JSResources.properties',
-    propertiesFolderPath: './deskapp/properties',
-    numericMapPath: './deskapp/properties/i18n-numeric-map.json',
-    numericFilenameTemplate: 'i18n-chunk/[locale]/numeric.i18n.js',
-    dynamicFilenameTemplate: 'i18n-chunk/[locale]/dynamic.i18n.js',
-    jsonpFunc: 'window.loadI18nChunk',
-    htmlTemplateLabel: '{{--user-locale}}',
-    localeVarName: 'window.userLangCode',
-    singleFile: false,
-    includeContentHash: false,
-    generateManifest: false,
-    manifestPath: null
+  publicFolders: {
+    dev: ['...'],
+    prod: ['...']
   },
-  publicFolders: ['...', {
-    source: './deskapp/tp/',
-    target: './tp/'
-  }],
   app: {
     entryFile: 'src/index.js',
     tpFolder: null,

package/lib/shared/babel/getBabelPlugin.js

@@ -19,7 +19,8 @@ const babelPluginOrder = ['removeAttribute', 'removePropTypes', 'devConsoleExclu
 function getBabelPlugin(options) {
   const {
     mode
-  } = options;
+  } = options; // let customPlugins = [];
+
   let customPlugins = [];
   const {
     babelCustomizations
@@ -32,6 +33,4 @@ function getBabelPlugin(options) {
   }
 
   return customPlugins.filter(Boolean);
-}
-
-;
+}

package/lib/shared/babel/runBabelForTsFile.js

@@ -25,6 +25,6 @@ function runBabelForTSFile({
     // const jsSourceCode = readFileSync(filename).toString();
     const babelConfig = (0, _babelWebConfig.babelWebConfig)(options, mode);
     const result = (0, _core.transformFileSync)(filename, babelConfig);
-    (0, _copyFile.writeFile)(outputFile.replace('.tsx', '.js'), result.code);
+    (0, _copyFile.writeFile)(outputFile.replace('.tsx', '.js').replace('.ts', '.js'), result.code);
   }
 }

package/lib/shared/bundler/webpack/custom_plugins/BundleIntegrityReport/index.js

@@ -30,6 +30,16 @@ class BundleIntegrityReport {
 
   apply(compiler) {
     compiler.hooks.done.tapAsync(pluginName, (stats, callback) => {
+      if (stats.hasErrors()) {
+        console.error(stats.toString({
+          all: false,
+          errors: true,
+          errorDetails: true,
+          colors: true
+        }));
+        return callback(new Error('Build failed due to compilation errors.'));
+      }
+
       const statsJson = (0, _objectManipulation.removeKeysFromObject)(stats.toJson(this.statsOptions), this.excludeKeysInStat);
       this.emitStats(statsJson).on('end', () => {
         callback();

package/lib/shared/bundler/webpack/custom_plugins/I18nNumericIndexPlugin/I18nGroupRuntimeModule.js

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.I18nGroupRuntimeModule = void 0;
+
+var _webpack = require("webpack");
+
+class I18nGroupRuntimeModule extends _webpack.RuntimeModule {
+  constructor(options) {
+    super('i18n-group-loader');
+    this.options = options;
+  }
+
+  generate() {
+    const {
+      customGroups,
+      localeVarName,
+      jsonpFunc
+    } = this.options; // Build chunk-to-group mapping from config
+
+    const chunkToGroup = {};
+    Object.entries(customGroups || {}).forEach(([groupName, config]) => {
+      (config.chunks || []).forEach(chunkName => {
+        chunkToGroup[chunkName] = groupName;
+      });
+    });
+    return `
+    // I18n Group Loading Runtime
+    (function() {
+      var loadedGroups = {};
+      var chunkToGroup = ${JSON.stringify(chunkToGroup)};
+      
+      // Store original webpack chunk loading function
+      var originalEnsureChunk = __webpack_require__.e;
+      
+      // Override webpack's chunk loading
+      __webpack_require__.e = function(chunkId) {
+        var promise = originalEnsureChunk.apply(this, arguments);
+        
+        // Check if this chunk needs an i18n group
+        var groupName = chunkToGroup[chunkId];
+        if (groupName && !loadedGroups[groupName]) {
+          // Load the i18n group
+          var locale = ${localeVarName} || 'en_US';
+          var groupConfig = ${JSON.stringify(customGroups)};
+          var config = groupConfig[groupName];
+          
+          if (config) {
+            var i18nUrl = config.filenameTemplate
+              .replace('[locale]', locale)
+              .replace('i18n-chunk/', __webpack_require__.p + 'i18n-chunk/');
+            
+            // Create script tag to load i18n chunk
+            var script = document.createElement('script');
+            script.src = i18nUrl;
+            script.async = true;
+            
+            // Mark as loaded when script loads
+            script.onload = function() {
+              loadedGroups[groupName] = true;
+            };
+            
+            document.head.appendChild(script);
+            
+            // If prefetch is enabled, prefetch other locales
+            if (config.prefetch && !config.preload) {
+              var link = document.createElement('link');
+              link.rel = 'prefetch';
+              link.href = i18nUrl;
+              document.head.appendChild(link);
+            }
+          }
+        }
+        
+        return promise;
+      };
+      
+      // Also check for webpackI18nGroup comments in dynamic imports
+      if (typeof __webpack_require__.l !== 'undefined') {
+        var originalLoadScript = __webpack_require__.l;
+        __webpack_require__.l = function(url, done, key, chunkId) {
+          // Check if chunk has i18n group
+          var groupName = chunkToGroup[chunkId];
+          if (groupName && !loadedGroups[groupName]) {
+            // Load i18n before main chunk
+            var locale = ${localeVarName} || 'en_US';
+            var groupConfig = ${JSON.stringify(customGroups)};
+            var config = groupConfig[groupName];
+            
+            if (config) {
+              var i18nUrl = config.filenameTemplate
+                .replace('[locale]', locale)
+                .replace('i18n-chunk/', __webpack_require__.p + 'i18n-chunk/');
+              
+              // Load i18n first, then the chunk
+              var i18nScript = document.createElement('script');
+              i18nScript.src = i18nUrl;
+              i18nScript.onload = function() {
+                loadedGroups[groupName] = true;
+                // Now load the original chunk
+                originalLoadScript.call(__webpack_require__, url, done, key, chunkId);
+              };
+              i18nScript.onerror = function() {
+                // Continue even if i18n fails
+                originalLoadScript.call(__webpack_require__, url, done, key, chunkId);
+              };
+              document.head.appendChild(i18nScript);
+              return;
+            }
+          }
+          
+          // Default behavior
+          return originalLoadScript.call(__webpack_require__, url, done, key, chunkId);
+        };
+      }
+    })();
+    `;
+  }
+
+}
+
+exports.I18nGroupRuntimeModule = I18nGroupRuntimeModule;