npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

code-clerk

v1.1.1

Published

Pulls project metadata from GitHub repositories.

Downloads

6

Readme

Code Clerk

Harvests project metadata from GitHub repositories. The harvested metadata is formatted to make it easy to produce a code.json file for Code.gov.

Installation

Locally:

npm install code-clerk

System-wide:

npm install -g code-clerk

Usage

CLI Usage

First, check out the built-in usage information:

codeclerk --help

Example 1

Assuming:

  • Your GitHub access token is in an environment variable named GITHUB_ACCESS_TOKEN (the default)
  • Your agency's acronym is ABC
  • Your agency has two GitHub organizations, named AgencyABC and AgencyXYZ

You could get your code.json output by running this command (prints the JSON to your console):

codeclerk ABC AgencyABC AgencyXYZ

Example 2

Assuming:

  • Your GitHub access token is in an environment variable named GITHUB_TOKEN
  • Your agency's acronym is XYZ
  • Your agency has one GitHub organization, named XYZ

You could get your code.json output by running this command (saves the JSON to a file named code.json):

codeclerk -t GITHUB_TOKEN -o code.json XYZ XYZ

Basic API Usage

You can easily integrate Code Clerk into your project. Just instantiate a client and run the inventory on your GitHub organization(s). The data returned by the inventory follows the code.json format.

import { GitHubClient, Inventory } from "code-clerk"

const client = new GitHubClient(YOUR_GITHUB_ACCESS_TOKEN)
const inventory = new Inventory(client, "ABC") // ABC is your agency acronym
const orgs = ["ABC", "AgencyZ"] // List of GitHub organization names

inventory.build(orgs).then((data) => {
  console.log(JSON.stringify(data)) // Here's your code.json
})

Advanced API Usage

If you want to customize the way Code Clerk builds your code.json file, you can do so via transforms and overrides.

Transforms

A transform is simply a JSONata expression that takes a GitHub GraphQL API response and turns it into a format compatible with the Code.gov schema.

You can see the included transforms in src/transforms.js of this package's source code. There are two: defaultGitHubTransform and minimumGitHubTransform. The default transform tries to make as much use of GitHub metadata as possible when building your code.json. The minimum transform only takes the necessary GitHub metadata to build a code.json that meets the bare minimum specified by the Code.gov schema.

You can write your own transform if the included transforms don't meet your needs. Refer to the JSONata documentation for guidance on how to write JSONata transforms.

To use your custom transform:

const myCustomTransform = `{
  (your custom JSONata transform goes here)
}`
const inventory = new Inventory(client, "ABC", { transform: myCustomTransform })

Overrides

An override lets you manually specify a value to use in your repositories' metadata instead of what Code Clerk automatically pulls from the GitHub GraphQL API.

An example of an override is to use a specific contact email for all repositories in your organization instead of the email address listed on the GitHub organization:

const myOverrides = {
  contact: {
    email: "[email protected]"
  }
}
const inventory = new Inventory(client, "ABC", { localOverrides: myOverrides })

Callback

While Code Clerk is building an inventory of your organization's repositories, it can report back some status information on what it is currently processing.

An example would be to print which repository Code Clerk is currently processing:

function myCallback(releaseMetadata, org) {
  console.log(`Currently processing repository ${releaseMetadata.name} in the GitHub organization ${org}`)
}
const inventory = new Inventory(client, "ABC", { callback: myCallback })