resources/src/mediawiki.inspect.js

   1 /*!
   2  * The mediawiki.inspect module.
   3  *
   4  * @author Ori Livneh
   5  * @since 1.22
   6  */
   7
   8 /* eslint-disable no-console */
   9
  10 ( function ( mw, $ ) {
  11
  12         // mw.inspect is a singleton class with static methods
  13         // that itself can also be invoked as a function (mediawiki.base/mw#inspect).
  14         // In JavaScript, that is implemented by starting with a function,
  15         // and subsequently setting additional properties on the function object.
  16
  17         /**
  18          * Tools for inspecting page composition and performance.
  19          *
  20          * @class mw.inspect
  21          * @singleton
  22          */
  23
  24         var inspect = mw.inspect,
  25                 byteLength = require( 'mediawiki.String' ).byteLength,
  26                 hasOwn = Object.prototype.hasOwnProperty;
  27
  28         function sortByProperty( array, prop, descending ) {
  29                 var order = descending ? -1 : 1;
  30                 return array.sort( function ( a, b ) {
  31                         return a[ prop ] > b[ prop ] ? order : a[ prop ] < b[ prop ] ? -order : 0;
  32                 } );
  33         }
  34
  35         function humanSize( bytes ) {
  36                 var i,
  37                         units = [ '', ' KiB', ' MiB', ' GiB', ' TiB', ' PiB' ];
  38
  39                 if ( !$.isNumeric( bytes ) || bytes === 0 ) { return bytes; }
  40
  41                 for ( i = 0; bytes >= 1024; bytes /= 1024 ) { i++; }
  42                 // Maintain one decimal for kB and above, but don't
  43                 // add ".0" for bytes.
  44                 return bytes.toFixed( i > 0 ? 1 : 0 ) + units[ i ];
  45         }
  46
  47         /**
  48          * Return a map of all dependency relationships between loaded modules.
  49          *
  50          * @return {Object} Maps module names to objects. Each sub-object has
  51          *  two properties, 'requires' and 'requiredBy'.
  52          */
  53         inspect.getDependencyGraph = function () {
  54                 var modules = inspect.getLoadedModules(),
  55                         graph = {};
  56
  57                 modules.forEach( function ( moduleName ) {
  58                         var dependencies = mw.loader.moduleRegistry[ moduleName ].dependencies || [];
  59
  60                         if ( !hasOwn.call( graph, moduleName ) ) {
  61                                 graph[ moduleName ] = { requiredBy: [] };
  62                         }
  63                         graph[ moduleName ].requires = dependencies;
  64
  65                         dependencies.forEach( function ( depName ) {
  66                                 if ( !hasOwn.call( graph, depName ) ) {
  67                                         graph[ depName ] = { requiredBy: [] };
  68                                 }
  69                                 graph[ depName ].requiredBy.push( moduleName );
  70                         } );
  71                 } );
  72                 return graph;
  73         };
  74
  75         /**
  76          * Calculate the byte size of a ResourceLoader module.
  77          *
  78          * @param {string} moduleName The name of the module
  79          * @return {number|null} Module size in bytes or null
  80          */
  81         inspect.getModuleSize = function ( moduleName ) {
  82                 var module = mw.loader.moduleRegistry[ moduleName ],
  83                         args, i, size;
  84
  85                 if ( module.state !== 'ready' ) {
  86                         return null;
  87                 }
  88
  89                 if ( !module.style && !module.script ) {
  90                         return 0;
  91                 }
  92
  93                 function getFunctionBody( func ) {
  94                         return String( func )
  95                                 // To ensure a deterministic result, replace the start of the function
  96                                 // declaration with a fixed string. For example, in Chrome 55, it seems
  97                                 // V8 seemingly-at-random decides to sometimes put a line break between
  98                                 // the opening brace and first statement of the function body. T159751.
  99                                 .replace( /^\s*function\s*\([^)]*\)\s*{\s*/, 'function(){' )
 100                                 .replace( /\s*}\s*$/, '}' );
 101                 }
 102
 103                 // Based on the load.php response for this module.
 104                 // For example: `mw.loader.implement("example", function(){}, {"css":[".x{color:red}"]});`
 105                 // @see mw.loader.store.set().
 106                 args = [
 107                         moduleName,
 108                         module.script,
 109                         module.style,
 110                         module.messages,
 111                         module.templates
 112                 ];
 113                 // Trim trailing null or empty object, as load.php would have done.
 114                 // @see ResourceLoader::makeLoaderImplementScript and ResourceLoader::trimArray.
 115                 i = args.length;
 116                 while ( i-- ) {
 117                         if ( args[ i ] === null || ( $.isPlainObject( args[ i ] ) && $.isEmptyObject( args[ i ] ) ) ) {
 118                                 args.splice( i, 1 );
 119                         } else {
 120                                 break;
 121                         }
 122                 }
 123
 124                 size = 0;
 125                 for ( i = 0; i < args.length; i++ ) {
 126                         if ( typeof args[ i ] === 'function' ) {
 127                                 size += byteLength( getFunctionBody( args[ i ] ) );
 128                         } else {
 129                                 size += byteLength( JSON.stringify( args[ i ] ) );
 130                         }
 131                 }
 132
 133                 return size;
 134         };
 135
 136         /**
 137          * Given CSS source, count both the total number of selectors it
 138          * contains and the number which match some element in the current
 139          * document.
 140          *
 141          * @param {string} css CSS source
 142          * @return {Object} Selector counts
 143          * @return {number} return.selectors Total number of selectors
 144          * @return {number} return.matched Number of matched selectors
 145          */
 146         inspect.auditSelectors = function ( css ) {
 147                 var selectors = { total: 0, matched: 0 },
 148                         style = document.createElement( 'style' );
 149
 150                 style.textContent = css;
 151                 document.body.appendChild( style );
 152                 $.each( style.sheet.cssRules, function ( index, rule ) {
 153                         selectors.total++;
 154                         // document.querySelector() on prefixed pseudo-elements can throw exceptions
 155                         // in Firefox and Safari. Ignore these exceptions.
 156                         // https://bugs.webkit.org/show_bug.cgi?id=149160
 157                         // https://bugzilla.mozilla.org/show_bug.cgi?id=1204880
 158                         try {
 159                                 if ( document.querySelector( rule.selectorText ) !== null ) {
 160                                         selectors.matched++;
 161                                 }
 162                         } catch ( e ) {}
 163                 } );
 164                 document.body.removeChild( style );
 165                 return selectors;
 166         };
 167
 168         /**
 169          * Get a list of all loaded ResourceLoader modules.
 170          *
 171          * @return {Array} List of module names
 172          */
 173         inspect.getLoadedModules = function () {
 174                 return mw.loader.getModuleNames().filter( function ( module ) {
 175                         return mw.loader.getState( module ) === 'ready';
 176                 } );
 177         };
 178
 179         /**
 180          * Print tabular data to the console, using console.table, console.log,
 181          * or mw.log (in declining order of preference).
 182          *
 183          * @param {Array} data Tabular data represented as an array of objects
 184          *  with common properties.
 185          */
 186         inspect.dumpTable = function ( data ) {
 187                 try {
 188                         // Use Function.prototype#call to force an exception on Firefox,
 189                         // which doesn't define console#table but doesn't complain if you
 190                         // try to invoke it.
 191                         // eslint-disable-next-line no-useless-call
 192                         console.table.call( console, data );
 193                         return;
 194                 } catch ( e ) {}
 195                 try {
 196                         console.log( JSON.stringify( data, null, 2 ) );
 197                 } catch ( e ) {}
 198         };
 199
 200         /**
 201          * Generate and print reports.
 202          *
 203          * When invoked without arguments, prints all available reports.
 204          *
 205          * @param {...string} [reports] One or more of "size", "css", or "store".
 206          */
 207         inspect.runReports = function () {
 208                 var reports = arguments.length > 0 ?
 209                         Array.prototype.slice.call( arguments ) :
 210                         Object.keys( inspect.reports );
 211
 212                 reports.forEach( function ( name ) {
 213                         if ( console.group ) {
 214                                 console.group( 'mw.inspect ' + name + ' report' );
 215                         } else {
 216                                 console.log( 'mw.inspect ' + name + ' report' );
 217                         }
 218                         inspect.dumpTable( inspect.reports[ name ]() );
 219                         if ( console.group ) {
 220                                 console.groupEnd( 'mw.inspect ' + name + ' report' );
 221                         }
 222                 } );
 223         };
 224
 225         /**
 226          * Perform a string search across the JavaScript and CSS source code
 227          * of all loaded modules and return an array of the names of the
 228          * modules that matched.
 229          *
 230          * @param {string|RegExp} pattern String or regexp to match.
 231          * @return {Array} Array of the names of modules that matched.
 232          */
 233         inspect.grep = function ( pattern ) {
 234                 if ( typeof pattern.test !== 'function' ) {
 235                         pattern = new RegExp( mw.RegExp.escape( pattern ), 'g' );
 236                 }
 237
 238                 return inspect.getLoadedModules().filter( function ( moduleName ) {
 239                         var module = mw.loader.moduleRegistry[ moduleName ];
 240
 241                         // Grep module's JavaScript
 242                         if ( typeof module.script === 'function' && pattern.test( module.script.toString() ) ) {
 243                                 return true;
 244                         }
 245
 246                         // Grep module's CSS
 247                         if (
 248                                 $.isPlainObject( module.style ) && Array.isArray( module.style.css ) &&
 249                                 pattern.test( module.style.css.join( '' ) )
 250                         ) {
 251                                 // Module's CSS source matches
 252                                 return true;
 253                         }
 254
 255                         return false;
 256                 } );
 257         };
 258
 259         /**
 260          * @class mw.inspect.reports
 261          * @singleton
 262          */
 263         inspect.reports = {
 264                 /**
 265                  * Generate a breakdown of all loaded modules and their size in
 266                  * kilobytes. Modules are ordered from largest to smallest.
 267                  *
 268                  * @return {Object[]} Size reports
 269                  */
 270                 size: function () {
 271                         // Map each module to a descriptor object.
 272                         var modules = inspect.getLoadedModules().map( function ( module ) {
 273                                 return {
 274                                         name: module,
 275                                         size: inspect.getModuleSize( module )
 276                                 };
 277                         } );
 278
 279                         // Sort module descriptors by size, largest first.
 280                         sortByProperty( modules, 'size', true );
 281
 282                         // Convert size to human-readable string.
 283                         modules.forEach( function ( module ) {
 284                                 module.sizeInBytes = module.size;
 285                                 module.size = humanSize( module.size );
 286                         } );
 287
 288                         return modules;
 289                 },
 290
 291                 /**
 292                  * For each module with styles, count the number of selectors, and
 293                  * count how many match against some element currently in the DOM.
 294                  *
 295                  * @return {Object[]} CSS reports
 296                  */
 297                 css: function () {
 298                         var modules = [];
 299
 300                         inspect.getLoadedModules().forEach( function ( name ) {
 301                                 var css, stats, module = mw.loader.moduleRegistry[ name ];
 302
 303                                 try {
 304                                         css = module.style.css.join();
 305                                 } catch ( e ) { return; } // skip
 306
 307                                 stats = inspect.auditSelectors( css );
 308                                 modules.push( {
 309                                         module: name,
 310                                         allSelectors: stats.total,
 311                                         matchedSelectors: stats.matched,
 312                                         percentMatched: stats.total !== 0 ?
 313                                                 ( stats.matched / stats.total * 100 ).toFixed( 2 ) + '%' : null
 314                                 } );
 315                         } );
 316                         sortByProperty( modules, 'allSelectors', true );
 317                         return modules;
 318                 },
 319
 320                 /**
 321                  * Report stats on mw.loader.store: the number of localStorage
 322                  * cache hits and misses, the number of items purged from the
 323                  * cache, and the total size of the module blob in localStorage.
 324                  *
 325                  * @return {Object[]} Store stats
 326                  */
 327                 store: function () {
 328                         var raw, stats = { enabled: mw.loader.store.enabled };
 329                         if ( stats.enabled ) {
 330                                 $.extend( stats, mw.loader.store.stats );
 331                                 try {
 332                                         raw = localStorage.getItem( mw.loader.store.getStoreKey() );
 333                                         stats.totalSizeInBytes = byteLength( raw );
 334                                         stats.totalSize = humanSize( byteLength( raw ) );
 335                                 } catch ( e ) {}
 336                         }
 337                         return [ stats ];
 338                 }
 339         };
 340
 341         if ( mw.config.get( 'debug' ) ) {
 342                 mw.log( 'mw.inspect: reports are not available in debug mode.' );
 343         }
 344
 345 }( mediaWiki, jQuery ) );