node package manager

panop

panop

npm build commitizen

panop processes the packages in your Lerna-style monorepo through a set of filters, to produce a single consolidated monorepo information file describing key aspects of each package.

Use cases

The consolidated file produced by panop can be used to build things related to your monorepo project. Examples include:

  • A package listing website, such as the AtlasKit Registry
  • A file describing key stats about each of your monorepo package versions

Example output

If you have a monorepo with the standard structure:

my-repo/
  package.json
  packages/
    package-one/
      ...
    package-two/
      ...

Then panop will produce a JSON file with the following structure. Note that the jsStats and npmInfo sections are generated by plugins and you create your own plugins!

{
  "generated": 1478227106942,
  "repository": "username/repo",
  "components": [
    {
      "name": "package-one",
      "isPublished": true,
      "latestPublishedVersion": {
        "name": "package-one",
        "version": "0.0.1",
        "jsStats": { "...": "..." },
        "npmInfo": {
          "isPublished": true,
          "publishTime": "2016-11-03T11:57:39.622Z"
        }
      },
      "versions": [ "...", "..." ]
    },
    {
      "name": "package-two",
      "isPublished": true,
      "latestPublishedVersion": {
        "name": "package-two",
        "version": "0.0.2",
        "jsStats": { "...": "..." },
        "npmInfo": {
          "isPublished": true,
          "publishTime": "2016-11-02T11:57:39.622Z"
        }
      },
      "versions": [ "...", "..." ]
    }
  ]
}

To see a full example of output data, see the "API data" section linked at the bottom of the AtlasKit Registry.

Plugins

Every package version in your monorepo is passed through a set of plugins. Each plugin is published as a separate panop-plugin-* npm module.

The available plugins are:

  • panop-plugin-pkg-json-info (always enabled)
  • panop-plugin-npm-info
  • panop-plugin-js-stats
  • panop-plugin-css-stats

See below for how to specify plugins via the command line.

Support for repository hosts

Currently panop only supports repositories which are hosted on Bitbucket Cloud.

Repositories hosted on other services could be supported in the future, pull requests are welcomed!

Installation and usage

npm install -g panop
panop --repo=bitbucket_username/bitbucket_repo --json=registry.json --requestsPerSecond=2 --plugins=pkg-json-info,npm-info
 
# your registry.json file will be saved

Available arguments:

  • repo: the Bitbucket repository you want to inspect (required, format is username/repo)
  • json: path where your consolidated file will be saved to (required)
  • plugins: comma-separated list of plugins (optional, default is pkg-json-info)
  • requestsPerSecond: the maximum number of Bitbucket API requests which will be made per second (optional, default 20)
  • mergeData: path to a previously-exported panop JSON file, for faster incremental builds. NOTE: make sure you specify the same plugins both times.
  • pkgScope: name of a single package to process. Useful for debugging.

If your repo argument is a private repository, make sure you set your BITBUCKET_USER and BITBUCKET_PASS environment variables before running panop.

Development

npm install -g yarn # if you don't have yarn already
 
git clone git@bitbucket.org:atlassian/panop.git
cd panop
yarn install
 
# install commitizen
npm install -g commitizen

Then instead of using git commit, do git cz.

Tests

To run the tests locally, simply use npm run test. If you are developing and want to run tests on each file change, use npm run test/watch.

Each commit to the central panop repo on Bitbucket triggers the standard test suite as well as an end-to-end integration test. You can view the status of a branch's tests by the Branches page.

The docker image used for Bitbucket Pipelines can be rebuild and republished using docker build -t "atlassianlabs/panop:latest" . && docker push "atlassianlabs/panop:latest"

Contributors

Pull requests, issues and comments welcome. For pull requests:

  • Add tests for new features and bug fixes
  • Follow the existing style
  • Separate unrelated changes into multiple pull requests

See the existing issues for things to start contributing.

For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.

Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).

Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.

License

Copyright (c) 2016 Atlassian and others. Apache 2.0 licensed, see LICENSE.txt file.