code-kraken

Code Kraken

A command line tool for code research using the GitHub API – it fetches info about users, commits, repositories, Docker images, and npm dependencies from GitHub. It can report the level of technical debt of repositories and how active or inactive they are.

Prerequisites

This tool runs with Node.js. Make sure you have an up-to-date version installed.

Preparation

You need to have a personal access token for the orgs and repositories on GitHub that you want to examine.

Getting a token – click here for a step by step guide

• Go to your GitHub token settings page:

• Click on “Generate new token (classic)”

• Enter any name you find suitable
• Tick the checkboxes for access to “repo” and “user”
• Confirm with “Generate token”
• Copy the personal access token to a safe place for later use

Refer to the instructions on GitHub for further information on this.

Installation

Install the code-kraken as a global command line tool using npm like so:

npm install -g code-kraken

Create a configuration file

Before you can use code-kraken, you have to set it up so that it knows yours the GitHub personal access token you've created (see chapter Preparation).

For this, you create a configuration file with in your home directory, like so:

echo CK_ACCESS_TOKEN=personal-access-token123 > $HOME/.code-kraken

GitHub Enterprise users

By default, code-kraken uses the API of the public GitHub, github.com. If your company is hosting its own GitHub Enterprise instance, like we do at Adevinta, add the CK_BASE_URL option to your .code-kraken config file, for example:

echo CK_BASE_URL=http://github.mpi-internal.com/api/v3 >> $HOME/.code-kraken

How to run

With the access token in place as described in the previous chapters, run the code-kraken on the command line like so:

code-kraken

(this will display a help message to get you on your way)

Getting the latest version

By default, once installed, code-kraken will always run the locally installed version. If you don't want to miss the latest features, run this every once in a while to get the latest version:

npm update -g code-kraken

Usage examples

Tech Debt

Shows a technical debt score for one or more GitHub repositories.

code-kraken tech-debt --org mobile-de --repo consumer-webapp

The repository parameter is optional:

• if a repository is provided, the output will show the score along with some improvement hints
• if the repository is omitted, the output will show a list of all the repos in the org, ranked according to their tech debt score

More info

Run --help for more info on the tech-debt command:

code-kraken help tech-debt

Guilds

Shows the guilds associated with repos – backend, frontend, data, qa, android, ios or devops.

code-kraken guild --org mobile-de --repo consumer-webapp

The repository parameter is optional:

• if repository is provided, the output will show the repo's associated guilds
• if the repository is omitted, the output will show a list of all guilds found in the org, along with the repos associated with them

Many commands, including the guild command, have a --guilds option that lets you specify guilds. The generated output will then only show data from repos associated with the specified guilds.

More info

Run --help for more info on the guild command:

code-kraken help guild

Inactive

Shows the level of inactivity of a GitHub repository. The inactivity score is a value from 0 to 100, 0 being a repo that currently gets updated every day, and 100 being a repo that has not been updated in a very long time.

code-kraken inactive --org mobile-de --repo consumer-webapp

The repository parameter is optional:

• if repository is provided, the output will show the repo's inactivity score along with additional info on how the score is composed
• if the repository is omitted, the output will show a list of all the repos in the org, ranked according to their level of inactivity

More info

Run --help for more info on the inactive command:

code-kraken help inactive

Docker images

Shows the Docker images used in the specified GitHub org and repository, found in a search of all the Dockerfiles in each repo.

code-kraken docker-images --org mobile-de --repo consumer-webapp

Repository is optional, if omitted, the whole org is searched.

Search expressions

You can pass a regular expression to match the images against. In the simplest usage example, the expression can just be a search term:

code-kraken docker-images --org mobile-de node

This will give you a list of repositories that use a Node.js image.

More advanced example:

code-kraken docker-images --org mobile-de "^.+/shared/node1[46].+$"

This will list all the repos that use dock.es.ecg.tools/shared/node14 or dock.es.ecg.tools/shared/node16, but not dock.es.ecg.tools/shared/node12.

• See also: Regular expressions

More info

Run --help for more info on the docker-images command:

code-kraken help docker-images

Npm packages

Shows the npm packages that repositories are dependent on according to their package.json files.

code-kraken npm-packages --org mobile-de --repo consumer-webapp

Repository is optional, if omitted, the whole org is searched.

Search expressions

You can pass one or two regular expressions to match the package names or versions against. In the simplest usage example, the expression can just be a search term:

code-kraken npm-packages --org mobile-de react

…gives you results for packages that have “react” in them (e.g. react, react-dom, react-router, etc.).

More advanced example:

code-kraken npm-packages --org mobile-de ^react$ "^[~^]*1[68]{1}"

…gives you results for precise package “react” with major versions 16 or 18.

• See also: Regular expressions

More info

Run --help for more info on the npm-packages command:

code-kraken help npm-packages

Repos

Shows info about the repositories a user contributed to in “pretty print” on the console:

code-kraken repos patrick-hund

You can use the --org option to constrain output to a specific GitHub org:

code-kraken repos --org mobile-de patrick-hund

You can specify multiple users:

code-kraken repos patrick-hund daniel-korger uwe-loydl

• Caveat: Data time range

More info

Run --help for more info on the repos command:

code-kraken help repos

Files

Shows info about what kinds of files the user modified (frontend or backend):

code-kraken files patrick-hund

As with the repos command, you can specify multiple users and a GitHub org. In addition, you can also constrain output to a specific repository:

code-kraken files --org mobile-de --repo consumer-webapp nina-maass

• Caveat: Data time range

More info

Run --help for more info on the files command:

code-kraken help files

CSS Colours

Since we should use only semantic tokens in our CSS files, this command helps to find the usage of wrong colours and tokens in the CSS files. It will detect the usage of explicit colours, deprecated tokens and primitive tokens and generate a report.

code-kraken css-colours --org mobile-de

The repository parameter gives the option to search in a specific repository. The output will show the usage of wrong colours and tokens in the CSS files and prints the line where the wrong colour or token is used.

code-kraken css-colours --org mobile-de --repo consumer-webapp

More info

Run --help for more info on the guild command:

code-kraken help css-colours

Options

CSV output

To facilitate importing the output into a Google Sheet, you can specify CSV format:

code-kraken repos --format csv patrick-hund

…or…

code-kraken files --format csv patrick-hund

This is particularly useful when using multiple users. You can pipe a list of usernames into code-kraken using xargs and store the output in a CSV file, like this:

cat users.txt | xargs code-kraken files --format csv > files.csv

You can then upload and import the CSV file into Google Sheets.

• See also: CSV date format

JSON output

You can also have code-kraken deliver its output in JSON format, for example:

code-kraken npm-packages --org mobile-de --format json

Verbose output

All commands support a flag for getting more verbose output:

-v or --verbose

The effect of using verbose mode is different depending on the command and the format type.

Caching

When executing a command, code-kraken does a lot of requests to the GitHub API, which can take a long time. Be patient when executing a command that you haven't used before!

For further command executions, code-kraken uses cached data from previous API calls to speed things up.

The time to live of the caching can be configured through the environment variable CK_FETCH_CACHE_TTL. You can set it in the .code-kraken config file in your home directory. In .code-kraken.defaults, this is set to 86,400,000 milliseconds, which is one day.

Additional notes and warnings

Data time range

For commands related to users (e.g. repos, files), code-kraken fetches commit data of the users.

We fetch data from GitHub as far back as it is allowed to by constraints of the GitHub API. This is usually data for around two weeks, depending on how active the user was (less activity – data ranges further back in time).

Regular expressions

Some hints on how to use regular expression with commands that support them (e.g. docker-images , npm-packages):

• Specify regular expressions without enclosing forward slashes
• Providing regular expression flags (g, i, u, etc.) is not supported
• The search is always case-insensitive
• Complex regular expressions need to be quoted, otherwise your shell will complain because it tries to evaluate the expression

CSV date format

For commands that create CSV data with times in them (e.g. repos, files), importing the CSV file in Google Sheets works best if you set the CK_LOCALE and CK_TIME_ZONE options in the .code-kraken file in your home directory to the locale and time zone your Google Sheets is set to. Then dates and times will be imported properly as dates you can calculate with rather than mere strings.

If your Google Workspace is in German, for example, you want to specify CK_LOCALE=de-DE. If you are located in Toronto, you want to specify CK_TIME_ZONE=EST.

Default locale is English / Great Britain (en-GB) and Barcelona / Berlin / Amsterdam time (CET).

Contributing

You are most welcome to fork this repository and create a pull request. The following will hopefully get you on your way.

How to install for development

• Check out the source code
• Use the correct Node.js version:

nvm use

• Install dependencies:

yarn install

• Create .code-kraken config file:

cp .code-kraken.example .code-kraken

• Uncomment the line with CK_ACCESS_TOKEN in the .code-kraken file, replace the value with your personal GitHub access token (instructions)

Running the script

You can run the script with:

yarn start

For your convenience, there is also a command that runs the program with debugging already enabled:

yarn dev

Configuration

To determine the tech debt score, the program analyses the Dockerfiles and package.json files of the repositories and assigns tech debt scores for dependencies that are outdated or banned. The algorithm uses a YAML config file to do this:

• config/tech-debt-evaluator.yaml

Tests

This package uses Jest for automated testing.

Running tests

To run unit test:

yarn test

Style considerations

Write unit tests mostly for low-level functions that have lots of different input, to make sure that they return the expected result. Use test and test.each instead of describe and it.

• Code example: getTechDebtScore.test.js

Type checking

Although this project is written entirely in JavaScript and runs directly in Node.js without any transpilation, we don't want to do without the “safety net” of type checking provided by TypeScript. We use JSDoc to achieve this. You can run the TypeScript compiler to check the code for type errors like this:

yarn check

Make sure you add JSDoc comments to every new function or class you implement!

Terminating with error

Whenever the program encounters a situation where it can't continue, e.g. network errors from API request attempts, it should terminate with an error code. Use the function die in these cases, supplying an error message:

import die from "./utils/die.js";

die("Failed to execute command");

Using the GitHub API

The codebase provides a package with utility functions for fetching data from the GitHub API.

Main API functions

The main functions for fetching data are:

• fetchResult – given a REST API path and an optional result page, fetches the result from that path
• fetchSearchResult – given a search query and an optional result page, fetches search results

Additional API utilities

This program includes many ways to reduce the number of requests to the GitHub API while making it resilient against connection problems and improving performance.

If you implement additional commands that fetch data from GitHub, you need to use these the same way the existing commands do:

• inBatches – executes fetch commands in batches rather than executing them all at once
• withPagination – fetches paged results one page after another
• withRetry – retries API requests if they fail
• fetchWithCache – caches fetch results using the local file system; note: this is already built-in into fetchData, so you'll only need this when implementing your own fetch function (see Caching)

Debugging

You can turn on a debug logger through the environment variable DEBUG, example:

DEBUG=* yarn start tech-debt

This will print log statements to the console that are created through the log function.

The asterisk argument in the above example means show all log statements; you can only show specific log statements by specifying a logger name.

The logger name is the relative path to the logging JavaScript module, prefixed with code-kraken:, with forward slashes replaced by colons and without the file extension.

For example, the logger name for module src/commands/dockerImages/run.js is code-kraken:commands:dockerImages:run, and you can show only log statements from this module with this command:

DEBUG=code-kraken:commands:dockerImages:run yarn start docker-images --org mobile-de

The command yarn dev already has debugging enabled with values DEBUG=code-kraken* and DEBUG_DEPTH=5. You can use the DEBUG and DEBUG_DEPTH variables to override these defaults:

DEBUG=*:run yarn dev tech-debt

This will show log output with depth 5 only from modules named run.mjs.

• See also: debug lib documentation on GitHub

Object logging depth

Objects are logged only up to a certain depth. You can increase this depth with the environment variable DEBUG_DEPTH.

Adding log statements in the code

You can add log statements to any module using debug like this:

import createLogFunction from "./utils/createLogFunction.js";

const log = createLogFunction();

log("I'm a happy camper");

The logger name will be set to “code-kraken” automatically. You can override this behaviour by providing a name as a string argument to createLogFunction (recommended!):

const log = createLogFunction("my:awesome:logger");

In this case, the logger name you provide is prefixed with code-kraken:, i.e. the resulting logger name will be code-kraken:my:awesome:logger.

If you intend to leave the log statements in the code, please use sensible names according to the conventions of the debug library. Recommended is the path to the logging JavaScript module, with slashes replaced by colons, without a file extension.

Example:

If your module's path is src/command/myCommand/doSomething.js, initialise a logger with this statement:

const log = createLogFunction("command:myCommand:doSomething");

Updating the documentation

This project uses JSDoc for creating HTML documentation in the docs directory.

To update the docs:

yarn docs

Please make sure the docs are up-to-date and run this frequently, at the very least before merging a pull request!

Publishing a new package version

Prerequisites

To be able to publish, you need to have the permission on npmjs.org. Ask one of the maintainers to grant you the access rights.

Versioning

This project uses semantic versioning, a.k.a. SemVer. If you're not familiar with the concept, please read up on it.

In a nutshell:

• If your new release contains only bugfixes, publish a patch version (e.g. old version 1.0.0 → new version 1.0.1)
• If your new release contains new features that are compatible with all existing features, publish a minor version (e.g. 1.0.0 → 1.1.0)
• If your new release contains new features that are not compatible with all existing features (also known as “breaking changes”), publish a major version (e.g. 1.0.0 → 1.0.0)

Beta versions are suffixed with -beta.x, where x is a number starting at zero that is incremented with every beta release.

Beta versions

Before you publish a final version of the package, make sure you test everything with a beta release.

1. Make sure tests pass: yarn test
2. Make sure there are no type errors: yarn check
3. Bump the version number in package.json – example: "version": "2.0.0-beta.0"
4. Bump the version number in src/codeKraken.mjs – example: .version("2.0.0-beta.0")
5. Build the bin file (in dist directory*)*: yarn build
6. Run the publish command: yarn npm publish --tag beta
7. Verify that it worked: npx code-kraken@beta --version

Final versions

When you are confident your new version is ready for the public at large, follow the same steps as above, but this time, without the beta parts:

1. Make sure tests pass: yarn test
2. Make sure there are no type errors: yarn check
3. Bump the version number in package.json – example: "version": "2.0.0"
4. Bump the version number in src/codeKraken.mjs – example: .version("2.0.0")
5. Build the bin file (in dist directory*)*: yarn build
6. Run the publish command: yarn npm publish
7. Verify that it worked: npx code-kraken@latest --version

License

MIT licence – copyright 2022-2024 mobile.de GmbH