# code-clerk

> Pulls project metadata from GitHub repositories.

Latest version **1.1.1** (published 2024-06-24) · CC0-1.0 license · 0 weekly downloads

## Install

```sh
npm install code-clerk
pnpm add code-clerk
yarn add code-clerk
bun add code-clerk
```

Provides the command `codeclerk`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2024-06-24 |
| First published | 2018-06-13 |
| Weekly downloads | 0 |
| License | CC0-1.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 4 |
| Unpacked size | 45.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Jeff Fredrickson |

## Links

- npm: https://www.npmjs.com/package/code-clerk
- Repository: https://github.com/GSA/code-clerk
- Homepage: https://github.com/GSA/code-clerk#readme
- Issues: https://github.com/GSA/code-clerk/issues
- npm.io page: https://npm.io/package/code-clerk

## Dependencies (4)

- [dotenv](https://npm.io/package/dotenv.md) ^16.4.5
- [jsonata](https://npm.io/package/jsonata.md) ^2.0.5
- [argparse](https://npm.io/package/argparse.md) ^2.0.1
- [graphql-request](https://npm.io/package/graphql-request.md) ^7.1.0

## Recent versions

- 1.1.1 (latest) — 2024-06-24
- 1.1.0 — 2024-05-16
- 1.0.0 — 2024-05-15
- 0.3.4 — 2020-06-04
- 0.3.3 — 2020-06-04
- 0.3.0 — 2020-05-18
- 0.2.1 — 2019-08-21
- 0.2.0 — 2018-06-18
- 0.1.1 — 2018-06-13
- 0.1.0 — 2018-06-13

## 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:

```sh
npm install code-clerk
```

System-wide:

```sh
npm install -g code-clerk
```

## Usage

### CLI Usage

First, check out the built-in usage information:

```sh
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):

```sh
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`):

```sh
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.

```javascript
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](https://jsonata.org/) 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](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](http://docs.jsonata.org/overview.html) for guidance on how to write JSONata transforms.

To use your custom transform:

```javascript
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:

```javascript
const myOverrides = {
  contact: {
    email: "opensource@example.gov"
  }
}
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:

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

---
_Source: https://npm.io/package/code-clerk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._