@automattic/i18n-check-webpack-plugin 1.0.36 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2023-10-03
+### Added
+- Add a sub-plugin, `I18nSafeMangleExportsPlugin`, to allow for avoiding problems with Webpack's `optimization.mangleExports` option occasionally mangling an export to one of the i18n function names. [#33392]
+
 ## [1.0.36] - 2023-09-13
 ### Changed
 - Updated package dependencies. [#33001]
@@ -172,6 +176,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
+[1.1.0]: https://github.com/Automattic/i18n-check-webpack-plugin/compare/v1.0.36...v1.1.0
 [1.0.36]: https://github.com/Automattic/i18n-check-webpack-plugin/compare/v1.0.35...v1.0.36
 [1.0.35]: https://github.com/Automattic/i18n-check-webpack-plugin/compare/v1.0.34...v1.0.35
 [1.0.34]: https://github.com/Automattic/i18n-check-webpack-plugin/compare/v1.0.33...v1.0.34

package/README.md

@@ -32,6 +32,31 @@ Parameters recognized by the plugin are:
    - `babelOptions`: Supply options for Babel.
    - `functions`: Supply a custom list of i18n functions to recognize.
 
+## Export mangling
+
+Webpack's [optimization.mangleExports option](https://webpack.js.org/configuration/optimization/#optimizationmangleexports), enabled by default in production mode, can on occasion mangle an export to the name of one of the i18n functions this module looks for.
+
+If you want export mangling and run into this issue, a slightly modified copy of Webpack's internal `MangleExportsPlugin` is provided. Require it as
+```
+const I18nSafeMangleExportsPlugin = require( '@automattic/i18n-check-webpack-plugin/I18nSafeMangleExportsPlugin' );
+```
+or
+```
+import I18nSafeMangleExportsPlugin from '@automattic/i18n-check-webpack-plugin/I18nSafeMangleExportsPlugin';
+```
+and add it to the `plugins` section of your Webpack config like
+```js
+{
+	plugins: [
+		new I18nSafeMangleExportsPlugin(),
+	],
+};
+```
+
+Parameters recognized by the plugin are:
+
+- `deterministic`: Set false to use the 'size' mode.
+
 ## Known problematic code patterns
 
 These are some code patterns that are known to cause translations to be mangled.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/i18n-check-webpack-plugin",
-	"version": "1.0.36",
+	"version": "1.1.0",
 	"description": "A Webpack plugin to check that WordPress i18n hasn't been mangled by Webpack optimizations.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/i18n-check-webpack-plugin/#readme",
 	"bugs": {
@@ -31,6 +31,7 @@
 	},
 	"exports": {
 		".": "./src/I18nCheckPlugin.js",
+		"./I18nSafeMangleExportsPlugin": "./src/I18nSafeMangleExportsPlugin.js",
 		"./GettextExtractor": "./src/GettextExtractor.js",
 		"./GettextEntries": "./src/GettextEntries.js",
 		"./GettextEntry": "./src/GettextEntry.js"

package/src/I18nSafeMangleExportsPlugin.js

@@ -0,0 +1,178 @@
+/**
+ * Webpack plugin to make export mangling safe to use with I18nCheckWebapckPlugin.
+ *
+ * Based on Webpack's MangleExportsPlugin. This is the same except for the
+ * addition of some default values in the `usedNames` set and the options
+ * accepted by the constructor.
+ */
+
+const {
+	UsageState,
+	Template: {
+		numberToIdentifier,
+		NUMBER_OF_IDENTIFIER_START_CHARS,
+		NUMBER_OF_IDENTIFIER_CONTINUATION_CHARS,
+	},
+	util: {
+		comparators: { compareSelect, compareStringsNumeric },
+	},
+} = require( 'webpack' );
+const { assignDeterministicIds } = require( 'webpack/lib/ids/IdHelpers' );
+
+/** @typedef {import("../Compiler")} Compiler */
+/** @typedef {import("../ExportsInfo")} ExportsInfo */
+/** @typedef {import("../ExportsInfo").ExportInfo} ExportInfo */
+
+/**
+ * Determine if we can mangle.
+ * @param {ExportsInfo} exportsInfo - exports info
+ * @returns {boolean} mangle is possible
+ */
+const canMangle = exportsInfo => {
+	if ( exportsInfo.otherExportsInfo.getUsed( undefined ) !== UsageState.Unused ) {
+		return false;
+	}
+	let hasSomethingToMangle = false;
+	for ( const exportInfo of exportsInfo.exports ) {
+		if ( exportInfo.canMangle === true ) {
+			hasSomethingToMangle = true;
+		}
+	}
+	return hasSomethingToMangle;
+};
+
+// Sort by name
+const comparator = compareSelect( e => e.name, compareStringsNumeric );
+/**
+ * Mangle exports.
+ * @param {boolean} deterministic - use deterministic names
+ * @param {ExportsInfo} exportsInfo - exports info
+ * @param {boolean | undefined} isNamespace - is namespace object
+ * @returns {void}
+ */
+const mangleExportsInfo = ( deterministic, exportsInfo, isNamespace ) => {
+	if ( ! canMangle( exportsInfo ) ) {
+		return;
+	}
+	const usedNames = new Set( [ '__', '_x', '_n', '_nx' ] );
+	/** @type {ExportInfo[]} */
+	const mangleableExports = [];
+
+	// Avoid to renamed exports that are not provided when
+	// 1. it's not a namespace export: non-provided exports can be found in prototype chain
+	// 2. there are other provided exports and deterministic mode is chosen:
+	//    non-provided exports would break the determinism
+	let avoidMangleNonProvided = ! isNamespace;
+	if ( ! avoidMangleNonProvided && deterministic ) {
+		for ( const exportInfo of exportsInfo.ownedExports ) {
+			if ( exportInfo.provided !== false ) {
+				avoidMangleNonProvided = true;
+				break;
+			}
+		}
+	}
+	for ( const exportInfo of exportsInfo.ownedExports ) {
+		const name = exportInfo.name;
+		if ( ! exportInfo.hasUsedName() ) {
+			if (
+				// Can the export be mangled?
+				exportInfo.canMangle !== true ||
+				// Never rename 1 char exports
+				( name.length === 1 && /^[a-zA-Z0-9_$]/.test( name ) ) ||
+				// Don't rename 2 char exports in deterministic mode
+				( deterministic &&
+					name.length === 2 &&
+					/^[a-zA-Z_$][a-zA-Z0-9_$]|^[1-9][0-9]/.test( name ) ) ||
+				// Don't rename exports that are not provided
+				( avoidMangleNonProvided && exportInfo.provided !== true )
+			) {
+				exportInfo.setUsedName( name );
+				usedNames.add( name );
+			} else {
+				mangleableExports.push( exportInfo );
+			}
+		}
+		if ( exportInfo.exportsInfoOwned ) {
+			const used = exportInfo.getUsed( undefined );
+			if ( used === UsageState.OnlyPropertiesUsed || used === UsageState.Unused ) {
+				mangleExportsInfo( deterministic, exportInfo.exportsInfo, false );
+			}
+		}
+	}
+	if ( deterministic ) {
+		assignDeterministicIds(
+			mangleableExports,
+			e => e.name,
+			comparator,
+			( e, id ) => {
+				const name = numberToIdentifier( id );
+				const size = usedNames.size;
+				usedNames.add( name );
+				if ( size === usedNames.size ) {
+					return false;
+				}
+				e.setUsedName( name );
+				return true;
+			},
+			[
+				NUMBER_OF_IDENTIFIER_START_CHARS,
+				NUMBER_OF_IDENTIFIER_START_CHARS * NUMBER_OF_IDENTIFIER_CONTINUATION_CHARS,
+			],
+			NUMBER_OF_IDENTIFIER_CONTINUATION_CHARS,
+			usedNames.size
+		);
+	} else {
+		const usedExports = [];
+		const unusedExports = [];
+		for ( const exportInfo of mangleableExports ) {
+			if ( exportInfo.getUsed( undefined ) === UsageState.Unused ) {
+				unusedExports.push( exportInfo );
+			} else {
+				usedExports.push( exportInfo );
+			}
+		}
+		usedExports.sort( comparator );
+		unusedExports.sort( comparator );
+		let i = 0;
+		for ( const list of [ usedExports, unusedExports ] ) {
+			for ( const exportInfo of list ) {
+				let name;
+				do {
+					name = numberToIdentifier( i++ );
+				} while ( usedNames.has( name ) );
+				exportInfo.setUsedName( name );
+			}
+		}
+	}
+};
+
+class MangleExportsPlugin {
+	constructor( options ) {
+		this._deterministic = options?.deterministic ?? true;
+	}
+	/**
+	 * Apply the plugin
+	 * @param {Compiler} compiler - the compiler instance
+	 * @returns {void}
+	 */
+	apply( compiler ) {
+		const { _deterministic: deterministic } = this;
+		compiler.hooks.compilation.tap( 'MangleExportsPlugin', compilation => {
+			const moduleGraph = compilation.moduleGraph;
+			compilation.hooks.optimizeCodeGeneration.tap( 'MangleExportsPlugin', modules => {
+				if ( compilation.moduleMemCaches ) {
+					throw new Error(
+						"optimization.mangleExports can't be used with cacheUnaffected as export mangling is a global effect"
+					);
+				}
+				for ( const module of modules ) {
+					const isNamespace = module.buildMeta && module.buildMeta.exportsType === 'namespace';
+					const exportsInfo = moduleGraph.getExportsInfo( module );
+					mangleExportsInfo( deterministic, exportsInfo, isNamespace );
+				}
+			} );
+		} );
+	}
+}
+
+module.exports = MangleExportsPlugin;