Package Exports

package-probe

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (package-probe) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Package Probe 🛰

Scan a Github organization for usage of a package.

Package Probe can help you answer questions such as "Which repositories in my organization are using React?" or "Which version of internal dependency X are my organization's projects using?"

Installation

$ npm install -g package-probe

Set up (one time)

Package Probe uses the Github API to scan for a package. If you want to search in a private Github organization, you'll need to create a Github Personal Access Token that has access to your organization and set it as an environment variable when running package-probe.

If you are scanning public organizations/owners, you can skip this step.

Generate a Github Personal access token in your Github profile developer settings
Grant the repo scope to the token (Package Probe reads information and does not store any of your data)
Add it to your environment as GITHUB_TOKEN or GH_TOKEN. (e.g. export GITHUB_TOKEN=<your token>)

Command line usage

$ package-probe --help

  Usage: package-probe [options]

  Options:
    --json                        output results as json (default output is a table)
    --owner <owner>               Github owner/organization to scan (required)
    --partial-matches             return results for partial matches of the search term
    --search-term <searchTerm>    search term (required)
    -V, --version                 output the version number
    -h, --help                    output usage information

Package probe will automatically use a Github Personal Access Token defined in the GITHUB_TOKEN or GH_TOKEN environment variable.

Advanced usage

While the CLI provides quick use, you have more control through the advanced options available in the JavaScript interface.

JavaScript API

probe(options)

// options
{
  // Github Personal Access Token. Only necessary if scanning a private organization/owner.
  accessToken?: string,
  // Function that adds fields to return along with the repository name and matched version
  appendFieldsToOutput: AppendFieldsToOutputFunction
  // Don't return results that match ANY of the provided filter functions
  exclude?: RepoFilterFunction[]
  // Only return results that match ALL the provided filter functions
  include?: RepoFilterFunction[],
  // The Github owner or organization to search in
  owner: string,
  // **Required**. If true, will match packages that partially match the provided search term. Otherwise, only exact matches will be returned. This option can be used to search for multiple packages that follow a naming schema.
  partialMatches?: boolean,
  // **Required**. The package name to search for. Must be the full name of the package, including the owner, unless you use the `partialMatches` option.
  searchTerm: string
}

// See Github REST API documentation (https://developer.github.com/v3/repos/#get) for available fields
type RepoFilterFunction = (githubRepo: Octokit.ReposGetResponse) => boolean

// See Github REST API documentation (https://developer.github.com/v3/repos/#get) for available fields
type AppendFieldsToOutputFunction = (githubRepo: Octokit.ReposGetResponse) => { [fieldName: string]: any }

Recipes

Scan for an private package

import probe from 'package-probe'

const accessToken = process.env.GITHUB_TOKEN

const results = await probe({
  accessToken,
  owner: 'my-company',
  searchTerm: '@my-company/my-package',
})

console.log(results)

Exclude archived repositories

const isArchived = (githubRepo: Octokit.ReposGetResponse) => githubRepo.archived

const results = await probe({
  accessToken: '...',
  owner: 'my-company',
  searchTerm: '@my-company/my-package',
  exclude: [isArchived],
})

Add the last commit and description to the output

const appendFieldsToOutput = (githubRepo: Octokit.ReposGetResponse) => ({
  description: githubRepo.description,
  lastCommit: new Date(githubRepo.pushed_at).toLocaleDateString(),
})

const results = await probe({
  accessToken: '...',
  owner: 'my-company',
  searchTerm: '@my-company/my-package',
  appendFieldsToOutput,
})

Example CLI search results

Searching my Github repositories for usage of React.

$ package-probe --search-term react --owner ryanoglesby08
🛰️  Scanning...
✨ Found 15 matches!
┌──────────────────────────────────┬──────────────────────────────────┬─────────────────┐
│ Repository name                  │ Package/app name                 │ Version         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ the-eod-machine                  │ @the-eod-machine/ui              │ ^16.4.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ movie-night                      │ movie-night                      │ ^16.7.0-alpha.2 │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ email-autocomplete               │ email-autocomplete               │ ^16.5.2         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ exposing-css-hidden-complexities │ exposing-css-hidden-complexities │ ^16.1.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ splitit                          │ splitit                          │ ^15.3.2         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ react-dashboard                  │ react-bare-app                   │ ^15.5.4         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ react-quizzer                    │ react-quizzer                    │ ^15.1.0         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ ssr-media-queries                │ ssr-media-queries                │ ^16.2.0         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ javascript-workshop              │ react-workshop-webpack           │ ^15.4.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ react-bare-app                   │ react-bare-app                   │ ^15.5.4         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ javascript-workshop              │ react-workshop-real-server       │ ^15.4.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ javascript-workshop              │ react-workshop-real-server       │ ^15.4.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ the-eod-machine                  │ @the-eod-machine/emailer         │ ^16.4.2         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ javascript-workshop              │ react-workshop-real-server       │ ^15.4.1         │
├──────────────────────────────────┼──────────────────────────────────┼─────────────────┤
│ css-playground                   │ js-hide-instead-of-by-class      │ ^15.4.2         │
└──────────────────────────────────┴──────────────────────────────────┴─────────────────┘