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 can be provided as either a URL string (which will be fetched from the GitHub API) or pre-existing entity data.

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 | Entity: GitHub entity to run rules on. Can be either:
  • A string URL (e.g., "https://github.com/owner/repo/issues/123") - will fetch entity data via GitHub API
  • An Entity object with pre-fetched data - avoids additional API calls when data is already available

import { runOctoGuideRules } from "octoguide";

// Using a URL string - will fetch data from GitHub API
await runOctoGuideRules({
  auth: "ghp_...",
  config: "strict",
  entity: "https://github.com/JoshuaKGoldberg/OctoGuide/issues/19",
});

// Using pre-existing Entity data - avoids API calls
const existingEntity = {
  data: {
    /* GitHub API response data */
  },
  number: 19,
  type: "issue",
};

await runOctoGuideRules({
  auth: "ghp_...",
  config: "strict",
  entity: existingEntity,
});

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));