package-adoption

Find out where a ts/js package is used across a GitHub organization, version and position of the package for each repository.

Usage for pkgName will be analyzed across org, excluding repositories that did not receive any commit in the last daysUntilStale days. A GitHub personal access token with scope repo is required, to access the org private repositories through GitHub APIs. It can be omitted to search across public repositories. Archived repositories are filtered out.

⚠️ GitHub API are rate limited, and search API in particular has the additional secondary rate limit. package-adoption implements the best practices guidelines to deal with it, but you should know that limitations could happen in any case.

⚠️ GitHub search API are not 100% reliable and sometimes return deleted / outdated files or multiple versions of the same file. The library version in the output could be inaccurate for this reason. There is a known issue with package names with a scope containing hyphen character, e.g. @typescript-eslint/parser. A slower version of the main scan function will be automatically used to handle this case.

Install

npm install package-adoption

Usage

import { getFilteredReposWithPackageForOrg } from 'package-adoption';

const result = getFilteredReposWithPackageForOrg({
  org: 'my-org',
  daysUntilStale: 90,
  ghAuthToken: 'my-gh-auth-token',
  pkgName: 'my-pkg',
});
/* => [
  {
    name: 'repo-1',
    installationPath: 'root',
    libVersion: '55.0.0-beta.13',
  },
  {
    name: 'repo-2',
    installationPath: 'packages/package-name1',
    libVersion: '65.2.0',
    "isPeerDep": true,
    "isDevDep": true
  },
  {
    name: 'repo-2',
    installationPath: 'packages/package-name2',
    libVersion: '65.2.1',
    "isDevDep": true
  }
]; */

Run CLI

npx package-adoption

package-adoption --config /path/to/config.js --output /path/to/output.json

If output file path omitted, package-adoption ouputs to stdout. When config option omitted, default for config file will be local config.js. The file must export an object like this:

module.exports = {
  org: 'myOrg',
  daysUntilStale: 90, // If omitted, 365 will be used as default
  ghAuthToken: 'my-GH-auth-token',
  pkgName: 'myPkg',
};

With inline arguments

package-adoption --org=myOrg --token=my-GH-auth-token --pkg=myPkg --output /path/to/output.json