package-probe
v3.1.0
Published
Scan a Github organization for usage of a package
Downloads
13
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
orGH_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 │
└──────────────────────────────────┴──────────────────────────────────┴─────────────────┘