@statoscope/cli

Statoscope CLI

This package supplies Statoscope as CLI tool

Installation

npm i @statoscope/cli -g

Usage

statoscope [command] [...args]

Features

validate (experimental)

Validate one or more webpack stats.

This is an experimental feature. Please provide some feedback

validate validator input [...args]

• --validator (-v) - path to validator-script (see validator API below)
• --input (-i) - path to one or more webpack stats
• --warn-as-error (-w) - treat warnings as errors

Validator API

As jora-query:

Validator-script may provide plain jora-query.

A query must return TestEntry[]:

type TestEntry = {
  type?: 'error' | 'warn' | 'info'; // 'error' by default
  assert?: boolean; // false by default
  messsage: string;
  filename?: string;
};

Example:

rules.jora:

[
  {
    assert: compilations.nodeModules.[name="lodash"].size() = 0,
    message: 'Lodash usage detected. Please do not use lodash in this project',
    filename: name
  },
  {
    message: 'Just info message',
    filename: name
  }
]

statoscope validate rules.jora stats.json

Output:

stats.json
  info: Just info message
  error: Lodash usage detected. Please do not use lodash in this project

Info: 1
Errors: 1

In this example validation will fail if bundle uses lodash library.

You can inspect stats-file structure and test your rules at statoscope-sandbox by clicking to Make report button.

You may also validate multiple stats (e.g. in CI):

rules.jora:

$master: .[name="master.json"];
$branch: .[name="branch.json"];

$branchRXJS: $branch.compilations.nodeModules.[name="rxjs"].instances.reasons.data.resolvedModule;
$masterRXJS: $master.compilations.nodeModules.[name="rxjs"].instances.reasons.data.resolvedModule;

[
  {
    assert: $branch.compilations.nodeModules.[name="lodash"].size() = 0,
    message: 'Lodash usage detected. Please do not use lodash in this project',
    filename: $branch.name
  },
  {
    type: 'warn',
    assert: $branchRXJS.size() <= $masterRXJS.size(),
    message: 'More rxjs usage detected. Try not to increase rxjs-usage',
    filename: $branch.name
  }
]

statoscope validate rules.jora --input master.json --input branch.json

Output:

branch.json
  error: Lodash usage detected. Please do not use lodash in this project
  warn: More rxjs usage detected. Try not to increase rxjs-usage

Errors: 1
Warnings: 1

Also, there are a lot of jora-helpers that you can use in your rules:

• common helpers
• webpack-model helpers

For example:

rules.jora:

$master: .[name="astexp-1.json"];
$branch: .[name="astexp-2.json"];

$masterInitialSize: $master.compilations.chunks.[initial].reduce(=> size + $$, 0);
$branchInitialSize: $branch.compilations.chunks.[initial].reduce(=> size + $$, 0);
$initialSizeDiff: $branchInitialSize - $masterInitialSize;
$initialSizeDiffPercent: $branchInitialSize.percentFrom($masterInitialSize, 2);

[
  {
    assert: $initialSizeDiff <= 0,
    message: `Initial assets size increased by ${$initialSizeDiff.formatSize()} (${$initialSizeDiffPercent}%)`,
    filename: $branch.name
  }
]

statoscope validate rules.jora --input master.json --input branch.json

Output:

branch.json
  error: Initial assets size increased at 249.57 kb (9.16%)"

Errors: 1

As function:

Validator-script may export ValidatorFn that will be called to validate stats from input.

type Data = {
  files: Object[];
  compilations: Object[];
  query: (query: string, data?: any) => any; // query-parameter is jora-syntax query
};

type API = {
  error(message: string, filename?: string): void;
  warn(message: string, filename?: string): void;
  info(message: string, filename?: string): void;
};
type ValidatorFn = (data: Data, api: API) => Promise<string | void>;

Example:

module.exports = (data, api) => {
  const lodash = data.query('compilations.nodeModules.[name="lodash"]');

  if (lodash.length) {
    api.error(
      'Lodash usage detected. Please do not use lodash in this project',
      data.files[0].name
    );
  }
};

statoscope validate rules.js stats.json

Output:

stats.json
  error: Lodash usage detected. Please do not use lodash in this project

Errors: 1

serve

Start HTTP-server and serve JSON-stats as HTML report

serve input [...args]

• --input (-i) - path to one or more webpack stats
• --host (-h) - server host
• --port (-p) - server port
• --open (-o) - open browser after server start

Example:

statoscope serve path/to/stats.json -o

Start server and open browser.

generate

Generate HTML report from JSON-stats.

generate input output [...args]

• --input (-i) - path to one or more webpack stats
• --output (-t) - path to generated HTML
• --open (-o) - open browser after generate

Example:

statoscope generate path/to/stats.json path/to/report.html -o

Create statoscope report, save it to path/to/report.html and open

Support

If you are an engineer or a company that is interested in Statoscope improvements, you may support Statoscope by financial contribution at OpenCollective.

Changelog

5.5.0 (08 July 2021)

Features

• [webpack-plugin] add new property saveOnlyStats
• [webpack-plugin] add new property saveReportTo (as a replacement for saveTo)

Refactor

• [webpack-plugin] refactoring to make code more flexible
• [report-writer] refactor work with the streams