mjswensen/shoulders

💛 Quickly view a list of your dependencies' open issues.

If I have seen a little further it is by standing on the shoulders of giants.

—Isaac Newton, John of Salisbury, and others before them

shoulders

Quickly view a list of open issues for the open-source packages that your project depends on.

Terminal theme: Rivet by themer

Usage

npx shoulders

shoulders will find dependencies in the node_modules folder, identify corresponding repositories on GitHub, and query GitHub's API for open issues.

If your project depends on many packages you will likely run into rate limiting errors from the GitHub API; you can increase the limit by using a personal access token (the only scope needed is public_repo) and passing it to shoulders via the $GITHUB_TOKEN environment variable:

GITHUB_TOKEN='<your token>' npx shoulders

Parameters

Name	Type	Short description
--labels	string	Filter issues by labels
--depth	number	Look for issues only n levels deep
--format	string	Format the output

Issue Filtering

In addition to listing all open issues, you can optionally include a comma-separated list of labels to use. For example, to see only issues with the bug label:

npx shoulders --labels bug

Or to include multiple labels, you can do:

npx shoulders --labels="bug,good first issue"

Controlling Depth

If you wish to look for issues only n levels deep, you can specify a depth parameter:

# Look for issues in your direct dependencies
npx shoulders --depth=0

Output Format

You can format the output by passing a format parameter:

npx shoulders --format html

If you'd like to create a new file you can pipe the output like this:

npx shoulders --format html > output.html

The available formats are currently console (default), html and md (markdown).

Why?

Modern software would not be possible without the mountains of previous work by others—much of it open source—as its foundation. In the spirit of Hacktoberfest 2019, this simple script makes it a little bit easier to find a way to support the projects that we depend on so heavily.

License

MIT © Matt Swensen

shoulders's Issues

Missing `g` flag in regex for labels option

This regex is missing a g (global) flag.
As it is now it will only replace the first occurrence it finds.

shoulders/index.js

Line 26 in fa665f7

labels = labels.replace(/\s*,\s*/, ',');

Introduced in #2

Feature Request/Implementation: output to HTML/MD file

Hey!

(full disclosure) I discovered your project through my college professor @humphd and think it's a wonderful idea! I'd like to contribute to it if possible.

I'd like to add the ability to specify --tofile at runtime which will dump the console results to an HTML/MD file for easier reading ability. I mean no offence by this feature and just wanted to try my hand at adding something that might be of value to your project!

I've actually already implemented a working demo and with your permission I'll submit a PR for your review.

Introduced in #8

Thanks and let me know 😄
-Chris

Filter out pull requests from output?

Since shoulders is meant to show the open issues for the packages we use, I find it a bit annoying that pull requests show up as well.

The github API treats them like issues, but we could filter them out by looking if the pull_request key is present as documented here.

What do you think? Should we filter out the PRs? If so should that be the default behavior or should it be behind a flag?

I would be interested in implementing this feature should you decide it's something you want to add.

Deal with package.json files that don't have a name field

I ran shoulders on a project, and it has a lot of modules that don't have names, for example:

$ npx shoulders
Detected 5780 packages.
Loading issues...

debug
No issues found.
https://github.com/visionmedia/debug/issues

async
No issues found.
https://github.com/caolan/async/issues

eventemitter2
No issues found.
https://github.com/hij1nx/EventEmitter2/issues

ms
No issues found.
https://github.com/zeit/ms/issues

safe-buffer
No issues found.
https://github.com/feross/safe-buffer/issues

ws
No issues found.
https://github.com/websockets/ws/issues

undefined
No issues found.

undefined
No issues found.

undefined
No issues found.

undefined
No issues found.

undefined
No issues found.

undefined
No issues found.

undefined
No issues found.
...

I did some digging, and this happens when you have package.json files like:

{
  "main": "./"
}

Looking at my deps, I can see a lot like this, for example:

find . -name 'package.json' \( -exec echo {} \; -exec jq '.name' {} \; \)
"co"
./tools/autodeployment/node_modules/pm2-axon/node_modules/debug/package.json
"debug"
./tools/autodeployment/node_modules/pm2-axon/package.json
"pm2-axon"
./tools/autodeployment/node_modules/pm2-axon/lib/configurable/package.json
"configurable"
./tools/autodeployment/node_modules/inherits/package.json
"inherits"
./tools/autodeployment/node_modules/date-fns/endOfWeek/package.json
null
./tools/autodeployment/node_modules/date-fns/startOfDecade/package.json
null
./tools/autodeployment/node_modules/date-fns/subMinutes/package.json
null
./tools/autodeployment/node_modules/date-fns/getISOWeek/package.json
null
./tools/autodeployment/node_modules/date-fns/differenceInMinutes/package.json
null
./tools/autodeployment/node_modules/date-fns/isThisQuarter/package.json
...

Instead of logging undefined for the project name, what if it used the path to the package.json file?