README

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

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

Usage no npm install needed!

README

ui-migration-stats

Example

Installation

Usage

Configuring ui-migration-stats

framework1 (Required), framework2 (Required)

src (Required), test (Optional)

options (Optional)

Generating webpack-stats.json

Output JSON

Migration Stats

Output keys

Lines of code breakdown

Module Stats

Output keys

Contributing and Development

Development tasks

Tests :)

Linting

`framework1` (Required), `framework2` (Required)

`src` (Required), `test` (Optional)

`options` (Optional)