Nodeschool Public Materials
    Have ideas to improve npm?Join in the discussion! »

    ui-migration-stats

    2.0.0 • Public • Published

    Build Status

    ui-migration-stats

    Stats for migration and code base.

    Migrating between frameworks can be hard. Having some way to quantify the migration can help with the process. ui-migration-stats provides the specific dependency feedback and numbers related to each your frameworks.

    To contribute look at Contributing and Development or https://github.com/cloudflare/ui-migration-stats/blob/master/CONTRIBUTING.md

    Example

    Say you were trying to migrate from BackboneJS to ReactJS OR maybe you've already started migrating a few modules/components to ReactJS. You now want to see how much of your codebase is migrated and how much is still in Backbone. Additionally, you don't know if migrating your super-important-module will break something. This is where ui-migration-stats comes in, you can use the tool to quantify your migration and also look for dependencies in your codebase for your super-important-module. You can also consume the stats object outputs and make some pretty charts or have a timeline for your migration.

    Installation

    yarn add ui-migration-stats
    

    Or

    npm install ui-migration-stats
    

    Usage

    You can pass command line args to ui-migration-stats

    stats --help
    
    Usage: stats [options]
    
    Options:
    
      -h, --help            output usage information
      -V, --version         output the version number
      -s, --subdirectories  Display subdirectories
      -S, --silent          Be silent
      -c, --config <path>   Set config path, defaults to ./stats.conf.json
    

    Configuring ui-migration-stats

    The script reads a config file that is named stats.conf.json by default. The example uses a file called stats-example.conf.json which is passed in using a --config flag. You can edit your package.json to use your config file as required.

    "scripts": {
      "stats": "stats --config='./your-stats.conf.json'",
    }
    

    It has the following structure

    const config = {
      framework1: {
        name: 'Backbone',
        src: {
          exclude: /test/,
          filetypes: ['.js', '.handlebars', '.json'],
          path: './example/javascripts/'
        },
        test: {
          filetypes: ['.js', '.handlebars', '.json'],
          path: './example/tests/',
          includeOnly: /overview/
        }
      },
      framework2: {
        name: 'React',
        src: {
          filetypes: ['.js', '.json'],
          path: './example/react/src/'
        },
        test: {
          filetypes: ['.js', '.json'],
          path: './example/react/test/'
        }
      },
      options: {
        modules: ['Cell', 'Header'],
        outputFilename: './out/stats-out.json',
        silent: false,
        sort: true,
        subdirectories: false,
        unconditionalLoc: true,
        webpackStatsFile: './example/webpack-stats-example.json',
        webpackStatsOutputFilename: './out/webpack-stats-out.json'
      }
    };
    
    module.exports = config;
    

    framework1 (Required), framework2 (Required)

    Key Required Type Default Description
    name yes string none Name of the framework
    src yes string none Object that holds framework src keys
    test no string none Object that holds framework src keys

    src (Required), test (Optional)

    Key Required Type Default Description
    exclude no regex none Regex that excludes matching files or folders
    filetypes no array includes all files An array of filetypes to include [".js",".handlebars",".json"]. Although this is not required, it is better to include file types so that .DS_Store and other hidden files are not included.
    includeOnly no regex none Includes only files and folders matching this regex. Useful for complex folder structures.
    path yes string none Path to the src or test directory. NOTE Paths are relative to cwd, unless absolute paths are provided

    options (Optional)

    Key Required Type Default Description
    modules no array Analyzes all modules present in webpackStatsFile It will analyze any module that contains the substrings present in this array. For example ['some'] will include all modules with some in their name i.e. some-module will be included. If not present in config, all modules will be included.
    outputFilename no string none Path and name of output file. If key is not present, it will NOT output a stats JSON file. If directory is not present it will create one for you.
    silent no boolean false Don't output to stdout
    subdirectories no boolean false Flag to include subdirectories in output JSON file/stdout, NOTE For accuracy and completeness, this option will not prevent the traversal of the subdirectories. It will only exclude the subdirectories from the final output JSON/stdout. Defaults to false
    sort no boolean false Sorts the output of webpack-stats by number of includes if true
    unconditionalLoc no boolean false This option is useful when you have code written in an unrecognized language or if you have a lot of schema files. You will get a warning about skipped files if there is an unrecognized language. Use this option to add those files as pure source code i.e. ignoring comments and other language constructs. If you're confused, it's best to set this to true.
    webpackStatsFile no string none Path and name of webpack stats input JSON file. If not present, it will skip webpack analysis
    webpackStatsOutputFilename no string none Path and name of webpack stats output JSON file. If key is not present, it will NOTE output a webpack stats JSON file.If directory is not present it will create one for you.

    NOTE All paths are relative to cwd, unless absolute paths are provided.

    Generating webpack-stats.json

    You will need to generate your project's webpack stats file. This can be done using the webpack cli or through your webpack config.

    You can use the following command to generate your file

    webpack --progress --json > webpack-stats.json

    NOTE: If for some reason your file is empty or if you're watching files in webpack, make sure your environment is set to production. Use this to set your environment to production for the json output

    NODE_ENV=production webpack --progress --json > webpack-stats.json

    webpack stats config: https://webpack.js.org/configuration/stats/

    Empty file: http://stackoverflow.com/questions/41520410/webpack-stats-json-file-is-empty

    Output JSON

    This is what standard output json file looks like

    Migration Stats

    {
      "timestamp": "2017-04-10T17:02:25.590Z",
      "framework1": {
        "name": "Backbone",
        "srcPath": "./example/javascripts/",
        "testPath": "./example/tests/",
        "filetypes": [
          ".js",
          ".handlebars",
          ".json"
        ],
        "files": 6,
        "tests": 3,
        "percentage": 53,
        "srcSubdirectories": [
          {
            "Path": "./example/javascripts/",
            "length": 2
          },
          {
            "Path": "example/javascripts/modules/traffic",
            "length": 1
          },
          {
            "Path": "example/javascripts/modules/traffic/lib",
            "length": 1
          }
        ],
        "testsSubdirectories": [
          {
            "Path": "./example/tests/",
            "length": 1
          },
          {
            "Path": "example/tests/modules",
            "length": 1
          }
        ],
        "filesLoc": {
          "total": 465,
          "source": 403,
          "comment": 14,
          "single": 14,
          "block": 0,
          "mixed": 1,
          "empty": 40,
          "todo": 0,
          "unrecognized": 9
        },
        "testsLoc": {
          "total": 240,
          "source": 201,
          "comment": 9,
          "single": 9,
          "block": 0,
          "mixed": 0,
          "empty": 30,
          "todo": 0
        },
        "percentageLoc": 63
      },
      "framework2": {
        "name": "React",
        "srcPath": "./example/react/src/",
        "testPath": "./example/react/test/",
        "filetypes": [
          ".js",
          ".json"
        ],
        "files": 3,
        "tests": 5,
        "percentage": 47,
        "srcSubdirectories": [
          {
            "path": "./example/react/src/",
            "length": 2
          },
          {
            "path": "example/react/src/containers",
            "length": 1
          },
          {
            "path": "example/react/src/components",
            "length": 1
          }
        ],
        "testsSubdirectories": [
          {
            "path": "./example/react/test/",
            "length": 1
          },
          {
            "path": "example/react/test/selectors",
            "length": 1
          }
        ],
        "filesLoc": {
          "total": 72,
          "source": 53,
          "comment": 7,
          "single": 4,
          "block": 3,
          "mixed": 0,
          "empty": 12,
          "todo": 1
        },
        "testsLoc": {
          "total": 341,
          "source": 306,
          "comment": 0,
          "single": 0,
          "block": 0,
          "mixed": 0,
          "empty": 35,
          "todo": 0
        },
        "percentageLoc": 37
      }
    }
    

    Output keys

    Key Description
    timestamp Timestamp when the script was run
    name Name of the framework
    path Path to src directory of framework
    testPath Path to test directory of framework
    filetypes An array of filetypes to include [".js",".handlebars",".json"]
    files Number of files found in framework source directory
    tests Number of files found in framework source directory
    percentage Percentage of total codebase by number of files
    srcSubdirectories Array of source subdirectories and the number of subdirectories they include i.e. length
    testsSubdirectories Array of test subdirectories and the number of subdirectories they include i.e. length
    filesLoc The number of lines of code in the source directory. See Lines of code break down for details
    percentageLoc Percentage of total codebase by lines of code

    Lines of code breakdown

    • total - total lines of code
    • source - source lines of code
    • comment - comment lines of code
    • single - single line comments
    • block - block comments
    • mixed - mixed comments
    • empty - empty lines
    • todo - todos found in code
    • unrecognized - unconditionally added lines i.e. unrecognized lines

    Module Stats

    {
      "timestamp": "2017-04-07T16:42:28.531Z",
      "webpackStats": [
        {
          "module": "some-component",
          "entry": "../~/some-component/lib/index.js",
          "exports": [
            "some-sub-component",
            "some-other-sub-component"
          ],
          "count": 3,
          "issuers": [
          "../react/src/issuer1.js",
          "../react/src/issuer2.js",
          "../react/src/issuer3.js"
          ]
        }
      ]
    }
    

    Output keys

    Key Description
    timestamp Timestamp when the script was run
    module Name of the module
    entry Entry point of module
    exports An array of module exports
    count Number of times the module was included
    issuers An array of paths where the module was included

    Contributing and Development

    To get started run:

    git clone git@github.com:cloudflare/ui-migration-stats.git

    or for https

    git clone https://github.com/cloudflare/ui-migration-stats.git
    cd ui-migration-stats
    yarn install
    yarn build
    yarn demo

    The demo task runs the tool on the example app found in example. Example code is from various random open source libraries.

    Development tasks

    yarn build # Build the lib folder 
    yarn dev # Watch for changes in src and rebuild 
    yarn dev-test # Watch for changes in src,test and rebuild 
    yarn run clean # Delete node_modules and coverage folders 
    yarn lint # Run the eslint 
    yarn test # Run the tests 

    Tests :)

    yarn test
    

    Linting

    yarn lint
    

    You can also format your code using

    yarn format
    

    Install

    npm i ui-migration-stats

    DownloadsWeekly Downloads

    21

    Version

    2.0.0

    License

    BSD-3-Clause

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar