richardlitt / jabbar

Find out who is interested in your GitHub Code

Jabbar

Find out who is interested in your GitHub code!

This is a tool to find out some more information about the people who watch or star your GitHub repository. GitHub's native UI is good for this, but it doesn't present the information in aggregate or show which orgs people are a member of. This tool does.

Table of Contents

• Background
• Install
• Usage
  • Authentication
  • Programmatic
  • CLI
  • Testing
• API
  • getWatchers(owner, repo)
  • getStargazers(owner, repo)
• Contribute
• License

Background

If a package maintainer uploads an open source package to a package manager, and no one sees it, does it make a sound?

Successful open source projects depend on their community for funding, interest, and long-term growth. Maintainers generally have to do a lot of leg-work themselves to make the package interesting, to attract more users, and to fund their own work. On GitHub, one way of tracking interest is to look at the contributors who have contributed code; or those who have opened issues; or those who have watched a repo; or, last, those who have starred a repository. There is some amount of information on GitHub in user profiles about interested users are and where they came from. Knowing that someone who starred your repo works for a company that may be able to sponsor continued work can be helpful for the maintainer.

This tool started as a simple idea: rather than manually looking through the people who star and watch repositories on GitHub, could we automatically get their affiliations?

What's with the weird name?

Jabbar comes from al jabbar, meaning 'the giant' the medieval Arabic word for the constellation Orion. Look to the stars, eh? Any chance relation to the Gom Jabbar is purely not coincidental. (If you can think of a better name, open an issue.)

Install

This package is on npm:

npm install --global jabbar

Usage

Quickstart

1. Get a GitHub Token. Click on 'read:org' in the Scopes page.
2. npm install --global jabbar
3. GITHUB_TOKEN=asdsafs jabbar RichardLitt/jabbar

Authentication

This module looks for an auth token in the environmental variable GITHUB_TOKEN. It needs to have the read:org scope in order to function properly. Make sure this var is set to a valid GitHub OAuth token. To create one see this article.

CLI

$ jabbar --help

  Usage
    $ jabbar <input> [--watchers|--stargazers]

  Options
    -r, --repo    - Repository to search. Format: RichardLitt/jabbar
                    This flag is used as the default input.
    --all         - The default: get all watchers, stargazers, and forkers
    -w, --watchers    - Get watchers for a repository
    -s, --stargazers  - Get stargazers for a repository
    -f, --forkers     - Get forkers for a repository
    --ignored     - Ignore a user. Defaults to include owner of repository.
                    Use csv for multiple users.
    -h, --help        - Show this printout
    --output <file>   - Print the results to a file as JSON

  Authentication
    This script looks for an auth token in the env var GITHUB_TOKEN. It needs
    to have the read:org scope in order to function properly. Make sure this
    var is set to a valid GitHub OAuth token.

  Examples
    $ jabbar RichardLitt/jabbar
    $ jabbar --repo RichardLitt/jabbar --watchers
    $ jabbar RichardLitt/jabbar -w --output=results.json

    # To pass an authentication token
    $ GITHUB_TOKEN=sd2991s jabbar -r RichardLitt/jabbar -w

Programmatic

You can also install Jabbar locally.

const j = require('jabbar')

// The main functions return a Promise, so wrap it in an async function
(async () => {
  let response = await j.getWatchers('RichardLitt', 'jabbar')
})()

Don't forget to set the GITHUB_TOKEN somewhere in your env.

Testing

This module uses Mocha. To run the tests, run: npm run test.

API

getAllUsers(owner, repo)

Get the aggregate users who have watched, forked, or stargazed at your repo.

getWatchers(owner, repo)

Get all of the watchers for a repository.

getStargazers(owner, repo)

Get all of the stargazers for a repository.

getForkers(owner, repo)

Get all users who have forked the repository.

getForkInformation(owner, repo)

Get information about the repository's forks.

Contribute

Please do! This is an open source project. Check out the Contributing Guide, which probably is a short read at the moment. open issues, submit PRs, or send get well soon cards.

Abide by the Code of Conduct.

License

MIT © 2019 Burnt Fen Creative LLC

jabbar's Issues

Test on an actual repository

Nock?

Disable automatic fork information

It seems to ping an abuse detection mechanism in large cases, by pinging user or orgs over and over again.

Write background in README file

Print data to the CLI

Figure out pagination

Create an al-Jabbar service

Right now, the data is only provided as a JSON file. In order to do more interesting things, we're going to need a separate service to be running. Here are things which would be useful to have if we had another service:

• Dates for when someone has watched your repository. This isn't currently accessible through the GitHub API;
• Information on which organizations have previously donated to various other projects

Aggregate orgs with multiple users

Address todos in cli.js file

Needed options:

    -c, --config  - Operate from config file. In this mode only token, verbose, and
                    debug flags apply.
    --csv         - Output data in CSV format
    --wipe-cache  - Wipe local cache before starting query.
    -v, --verbose - Enable verbose logging
    --debug       - Enable extremely verbose logging
    --dry-run     - Check the cost of the query without executing it.

Possible requires used by Thomas:

const done = require('./graphql').done
const cache = require('./graphql').cache

Test basic CLI call with curl

Enable passing the repo as an input without the repo flag

Get information for an entire organization

Superficially, this could mean looping over all repositories. Ideally, this would mean not getting data for people we already know about, which would involve getting a list of watchers, and then making a dictionary with the repos they watch, and then getting data for them all. Also, implement timeouts for the API to be nice.

Add ignore option

Print companies if a user has no orgs

Print results to a JSON file

Show forkers

Plan API call

Aggregate watchers and stargazers into one result

Add graphql file

Publish blogpost

TODO: When?

Pretty print results to the CLI

Right now, the CLI will just print the entire dumb JSON object. Instead, if should print the users in a list, with their orgs also listed - some sort of smart viewer. Ideally, this would really be in a webpage, but having a CLI command would be good, too.

Display fork information for `--forks` option

There's a lot of information we get from the forks which could be shown. For instance, any fork which has more than one watcher or star is non-trivial, and should be displayed to the user. Right now, this information is just deleted.

Show when someone has interacted with your repository

Make a dashboard to display data

Enable CI for tests

Output broken

TypeError: Converting circular structure to JSON

Request cost of request from GitHub

GitHub might send back a header for the cost of a request. This would enable us to work with API limits better.

Get information on contributors

Add tests

Print GitHub URLs

Add organizations embedded in Company strings to output

Right now, any organization included in a company profile isn't really used as effectively as GitHub organizations. This could be changed. There's a TODO in the mostPopularOrgs argument where this could be attended to immediately, as part of a larger PR.

Write out features in README

Provide example config file