API

OctoGuide provides an octoguide package on npm. This package is the same as the standalone CLI and its code is directly used by the GitHub Action.

npm

npm install octoguide

pnpm

pnpm install octoguide

yarn

yarn install octoguide

runOctoGuideRules

Runs OctoGuide’s rules to generate a list of reports for a GitHub entity. The entity will be fetched from its URL.

Takes in a single parameter of type RunOctoGuideRulesOptions. Returns a RunOctoGuideRulesResult.

import { runOctoGuideRules } from "octoguide";

const { reports } = await runOctoGuideRules({
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

console.log("Received reports:", reports);

RunOctoGuideRulesOptions

Settings for running runOctoGuideRules. Only entity is required.

• auth: string: GitHub authentication token.
  • If not provided, retrieved with get-github-auth-token.
• config: "recommended" | "strict": Preset configuration to run rules from.
  • If not provided, defaults to "recommended".
• entity: string: URL of the entity to run rules on.

import { runOctoGuideRules } from "octoguide";

await runOctoGuideRules({
  auth: "ghp_...",
  config: "strict",
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

RunOctoGuideRulesResult

Returned data from running runOctoGuideRules.

• entity: Entity: The entity that was scanned.
• reports: RuleReport[]: Any reports generated by the rules.

const { entity, reports } = await runOctoGuideRules({
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

console.log("Entity URL:", entity.data.html_url);
console.log("Received reports:", reports);

Reporters

The functions that OctoGuide itself uses to display rule reports:

• cliReporter: Used by the standalone CLI
• markdownReporter: Used by the GitHub Actions Workflow

These reporters both take in a reports: RuleReport[] as returned by runOctoGuideRules’s RunOctoGuideRulesResult.

cliReporter

Formats a rule report as used by standalone CLI.

If reports is empty, it will log a happy Found 0 reports. Great! ✅ message. Otherwise it will pretty-print the reports, grouped by rule.

import { cliReporter, runOctoGuideRules } from "octoguide";

const { reports } = await runOctoGuideRules({
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

console.log(cliReporter(reports));

markdownReporter

Formats a rule report as used by the GitHub Actions Workflow.

If reports is empty, it will log a happy All reports are resolved now. Thanks! ✅ message. Otherwise it will pretty-print the reports, grouped by rule.

import { markdownReporter, runOctoGuideRules } from "octoguide";

const { entity, reports } = await runOctoGuideRules({
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

console.log(markdownReporter(entity, reports));