resources/src/mediawiki/mediawiki.inspect.js

   1 /*!
   2  * Tools for inspecting page composition and performance.
   3  *
   4  * @author Ori Livneh
   5  * @since 1.22
   6  */
   7 /*jshint devel:true */
   8 ( function ( mw, $ ) {
   9
  10         var inspect,
  11                 hasOwn = Object.prototype.hasOwnProperty;
  12
  13         function sortByProperty( array, prop, descending ) {
  14                 var order = descending ? -1 : 1;
  15                 return array.sort( function ( a, b ) {
  16                         return a[ prop ] > b[ prop ] ? order : a[ prop ] < b[ prop ] ? -order : 0;
  17                 } );
  18         }
  19
  20         function humanSize( bytes ) {
  21                 if ( !$.isNumeric( bytes ) || bytes === 0 ) { return bytes; }
  22                 var i = 0,
  23                         units = [ '', ' kB', ' MB', ' GB', ' TB', ' PB' ];
  24
  25                 for ( ; bytes >= 1024; bytes /= 1024 ) { i++; }
  26                 // Maintain one decimal for kB and above, but don't
  27                 // add ".0" for bytes.
  28                 return bytes.toFixed( i > 0 ? 1 : 0 ) + units[ i ];
  29         }
  30
  31         /**
  32          * @class mw.inspect
  33          * @singleton
  34          */
  35         inspect = {
  36
  37                 /**
  38                  * Return a map of all dependency relationships between loaded modules.
  39                  *
  40                  * @return {Object} Maps module names to objects. Each sub-object has
  41                  *  two properties, 'requires' and 'requiredBy'.
  42                  */
  43                 getDependencyGraph: function () {
  44                         var modules = inspect.getLoadedModules(),
  45                                 graph = {};
  46
  47                         $.each( modules, function ( moduleIndex, moduleName ) {
  48                                 var dependencies = mw.loader.moduleRegistry[ moduleName ].dependencies || [];
  49
  50                                 if ( !hasOwn.call( graph, moduleName ) ) {
  51                                         graph[ moduleName ] = { requiredBy: [] };
  52                                 }
  53                                 graph[ moduleName ].requires = dependencies;
  54
  55                                 $.each( dependencies, function ( depIndex, depName ) {
  56                                         if ( !hasOwn.call( graph, depName ) ) {
  57                                                 graph[ depName ] = { requiredBy: [] };
  58                                         }
  59                                         graph[ depName ].requiredBy.push( moduleName );
  60                                 } );
  61                         } );
  62                         return graph;
  63                 },
  64
  65                 /**
  66                  * Calculate the byte size of a ResourceLoader module.
  67                  *
  68                  * @param {string} moduleName The name of the module
  69                  * @return {number|null} Module size in bytes or null
  70                  */
  71                 getModuleSize: function ( moduleName ) {
  72                         var module = mw.loader.moduleRegistry[ moduleName ],
  73                                 payload = 0;
  74
  75                         if ( mw.loader.getState( moduleName ) !== 'ready' ) {
  76                                 return null;
  77                         }
  78
  79                         if ( !module.style && !module.script ) {
  80                                 return null;
  81                         }
  82
  83                         // Tally CSS
  84                         if ( module.style && $.isArray( module.style.css ) ) {
  85                                 $.each( module.style.css, function ( i, stylesheet ) {
  86                                         payload += $.byteLength( stylesheet );
  87                                 } );
  88                         }
  89
  90                         // Tally JavaScript
  91                         if ( $.isFunction( module.script ) ) {
  92                                 payload += $.byteLength( module.script.toString() );
  93                         }
  94
  95                         return payload;
  96                 },
  97
  98                 /**
  99                  * Given CSS source, count both the total number of selectors it
 100                  * contains and the number which match some element in the current
 101                  * document.
 102                  *
 103                  * @param {string} css CSS source
 104                  * @return {Object} Selector counts
 105                  * @return {number} return.selectors Total number of selectors
 106                  * @return {number} return.matched Number of matched selectors
 107                  */
 108                 auditSelectors: function ( css ) {
 109                         var selectors = { total: 0, matched: 0 },
 110                                 style = document.createElement( 'style' ),
 111                                 sheet, rules;
 112
 113                         style.textContent = css;
 114                         document.body.appendChild( style );
 115                         // Standards-compliant browsers use .sheet.cssRules, IE8 uses .styleSheet.rules…
 116                         sheet = style.sheet || style.styleSheet;
 117                         rules = sheet.cssRules || sheet.rules;
 118                         $.each( rules, function ( index, rule ) {
 119                                 selectors.total++;
 120                                 // document.querySelector() on prefixed pseudo-elements can throw exceptions
 121                                 // in Firefox and Safari. Ignore these exceptions.
 122                                 // https://bugs.webkit.org/show_bug.cgi?id=149160
 123                                 // https://bugzilla.mozilla.org/show_bug.cgi?id=1204880
 124                                 try {
 125                                         if ( document.querySelector( rule.selectorText ) !== null ) {
 126                                                 selectors.matched++;
 127                                         }
 128                                 } catch ( e ) {}
 129                         } );
 130                         document.body.removeChild( style );
 131                         return selectors;
 132                 },
 133
 134                 /**
 135                  * Get a list of all loaded ResourceLoader modules.
 136                  *
 137                  * @return {Array} List of module names
 138                  */
 139                 getLoadedModules: function () {
 140                         return $.grep( mw.loader.getModuleNames(), function ( module ) {
 141                                 return mw.loader.getState( module ) === 'ready';
 142                         } );
 143                 },
 144
 145                 /**
 146                  * Print tabular data to the console, using console.table, console.log,
 147                  * or mw.log (in declining order of preference).
 148                  *
 149                  * @param {Array} data Tabular data represented as an array of objects
 150                  *  with common properties.
 151                  */
 152                 dumpTable: function ( data ) {
 153                         try {
 154                                 // Bartosz made me put this here.
 155                                 if ( window.opera ) { throw window.opera; }
 156                                 // Use Function.prototype#call to force an exception on Firefox,
 157                                 // which doesn't define console#table but doesn't complain if you
 158                                 // try to invoke it.
 159                                 console.table.call( console, data );
 160                                 return;
 161                         } catch ( e ) {}
 162                         try {
 163                                 console.log( JSON.stringify( data, null, 2 ) );
 164                                 return;
 165                         } catch ( e ) {}
 166                         mw.log( data );
 167                 },
 168
 169                 /**
 170                  * Generate and print one more reports. When invoked with no arguments,
 171                  * print all reports.
 172                  *
 173                  * @param {...string} [reports] Report names to run, or unset to print
 174                  *  all available reports.
 175                  */
 176                 runReports: function () {
 177                         var reports = arguments.length > 0 ?
 178                                 Array.prototype.slice.call( arguments ) :
 179                                 $.map( inspect.reports, function ( v, k ) { return k; } );
 180
 181                         $.each( reports, function ( index, name ) {
 182                                 inspect.dumpTable( inspect.reports[ name ]() );
 183                         } );
 184                 },
 185
 186                 /**
 187                  * @class mw.inspect.reports
 188                  * @singleton
 189                  */
 190                 reports: {
 191                         /**
 192                          * Generate a breakdown of all loaded modules and their size in
 193                          * kilobytes. Modules are ordered from largest to smallest.
 194                          */
 195                         size: function () {
 196                                 // Map each module to a descriptor object.
 197                                 var modules = $.map( inspect.getLoadedModules(), function ( module ) {
 198                                         return {
 199                                                 name: module,
 200                                                 size: inspect.getModuleSize( module )
 201                                         };
 202                                 } );
 203
 204                                 // Sort module descriptors by size, largest first.
 205                                 sortByProperty( modules, 'size', true );
 206
 207                                 // Convert size to human-readable string.
 208                                 $.each( modules, function ( i, module ) {
 209                                         module.size = humanSize( module.size );
 210                                 } );
 211
 212                                 return modules;
 213                         },
 214
 215                         /**
 216                          * For each module with styles, count the number of selectors, and
 217                          * count how many match against some element currently in the DOM.
 218                          */
 219                         css: function () {
 220                                 var modules = [];
 221
 222                                 $.each( inspect.getLoadedModules(), function ( index, name ) {
 223                                         var css, stats, module = mw.loader.moduleRegistry[ name ];
 224
 225                                         try {
 226                                                 css = module.style.css.join();
 227                                         } catch ( e ) { return; } // skip
 228
 229                                         stats = inspect.auditSelectors( css );
 230                                         modules.push( {
 231                                                 module: name,
 232                                                 allSelectors: stats.total,
 233                                                 matchedSelectors: stats.matched,
 234                                                 percentMatched: stats.total !== 0 ?
 235                                                         ( stats.matched / stats.total * 100 ).toFixed( 2 )  + '%' : null
 236                                         } );
 237                                 } );
 238                                 sortByProperty( modules, 'allSelectors', true );
 239                                 return modules;
 240                         },
 241
 242                         /**
 243                          * Report stats on mw.loader.store: the number of localStorage
 244                          * cache hits and misses, the number of items purged from the
 245                          * cache, and the total size of the module blob in localStorage.
 246                          */
 247                         store: function () {
 248                                 var raw, stats = { enabled: mw.loader.store.enabled };
 249                                 if ( stats.enabled ) {
 250                                         $.extend( stats, mw.loader.store.stats );
 251                                         try {
 252                                                 raw = localStorage.getItem( mw.loader.store.getStoreKey() );
 253                                                 stats.totalSize = humanSize( $.byteLength( raw ) );
 254                                         } catch ( e ) {}
 255                                 }
 256                                 return [ stats ];
 257                         }
 258                 },
 259
 260                 /**
 261                  * Perform a string search across the JavaScript and CSS source code
 262                  * of all loaded modules and return an array of the names of the
 263                  * modules that matched.
 264                  *
 265                  * @param {string|RegExp} pattern String or regexp to match.
 266                  * @return {Array} Array of the names of modules that matched.
 267                  */
 268                 grep: function ( pattern ) {
 269                         if ( typeof pattern.test !== 'function' ) {
 270                                 pattern = new RegExp( mw.RegExp.escape( pattern ), 'g' );
 271                         }
 272
 273                         return $.grep( inspect.getLoadedModules(), function ( moduleName ) {
 274                                 var module = mw.loader.moduleRegistry[ moduleName ];
 275
 276                                 // Grep module's JavaScript
 277                                 if ( $.isFunction( module.script ) && pattern.test( module.script.toString() ) ) {
 278                                         return true;
 279                                 }
 280
 281                                 // Grep module's CSS
 282                                 if (
 283                                         $.isPlainObject( module.style ) && $.isArray( module.style.css )
 284                                         && pattern.test( module.style.css.join( '' ) )
 285                                 ) {
 286                                         // Module's CSS source matches
 287                                         return true;
 288                                 }
 289
 290                                 return false;
 291                         } );
 292                 }
 293         };
 294
 295         if ( mw.config.get( 'debug' ) ) {
 296                 mw.log( 'mw.inspect: reports are not available in debug mode.' );
 297         }
 298
 299         mw.inspect = inspect;
 300
 301 }( mediaWiki, jQuery ) );