github-issue-form-doctor

github-issue-form-doctor is a local CLI for maintainers and automation that validates GitHub YAML issue forms and previews the Markdown issue body they generate.

npx github-issue-form-doctor check

Expected output:

OK: checked 3 file(s), 0 error(s), 0 warning(s)

Overview

github-issue-form-doctor reads .github/ISSUE_TEMPLATE/*.yml, .github/ISSUE_TEMPLATE/*.yaml, and .github/ISSUE_TEMPLATE/config.yml. It validates common GitHub issue form and template chooser rules, renders local Markdown previews of submitted issue bodies, never contacts GitHub, and writes no files.

Why this exists

Broken issue forms are often discovered only after opening the GitHub UI or after contributors report that a template is unusable. That feedback loop is remote, manual, and awkward to automate.

YAML linting only proves that a file parses. It does not know about issue form required keys, duplicate field IDs, dropdown default indexes, checkbox option shapes, template chooser contact links, or the Markdown body that GitHub will generate. This tool is intentionally narrower than GitHub itself and focuses on deterministic local checks for those common mistakes.

Who should use this

• Open-source maintainers who use GitHub issue forms.
• Contributors changing files under .github/ISSUE_TEMPLATE.
• CI jobs and pre-commit hooks that gate issue template changes.
• AI coding agents that need a local pass/fail check before pushing generated templates.

Highlights

• Validates issue form YAML and config.yml.
• Reports stable text and JSON diagnostics.
• Supports strict mode for treating warnings as errors.
• Renders deterministic Markdown previews with optional JSON answers.
• Runs offline and writes nothing.

Demo

Fixture tree:

.github/
  ISSUE_TEMPLATE/
    bug.yml
    config.yml

Run a machine-readable check:

issue-form-doctor check --format json

Example output:

{
  "ok": true,
  "filesChecked": 2,
  "errorCount": 0,
  "warningCount": 0,
  "diagnostics": []
}

Render a preview:

issue-form-doctor preview .github/ISSUE_TEMPLATE/bug.yml

Generated Markdown:

### What happened?

example

Installation

Install as a development dependency:

npm install --save-dev github-issue-form-doctor

Or run through npx:

npx github-issue-form-doctor check

Quickstart

npx github-issue-form-doctor check
npx github-issue-form-doctor preview .github/ISSUE_TEMPLATE/bug.yml

Exit codes:

• 0: success.
• 1: validation or answer errors.
• 2: usage, file, or unsupported format errors.

Usage

issue-form-doctor check [target] [--format text|json] [--strict]
issue-form-doctor preview <form-file> [--answers <answers-json>] [--format markdown|json]
issue-form-doctor --help
issue-form-doctor --version

check defaults to the current working directory. When the target is a directory, it validates .github/ISSUE_TEMPLATE under that directory and ignores Markdown issue templates. When the target is a file, it validates that one .yml or .yaml issue form, or config.yml.

preview validates the issue form before rendering it. If --answers is omitted, deterministic placeholder answers are used. If --answers is provided, it must point to a JSON object keyed by issue form field IDs.

The CLI reads only the target files. It does not write, overwrite, or create files, and it does not call the GitHub API or any network service. --format json is intended for CI and agents.

Configuration

There is no separate config file. The only configuration is the CLI flags and the GitHub issue template files being checked.

For AI agents and CI

Use strict JSON output for deterministic automation:

issue-form-doctor check --format json --strict

Agents should parse stdout as JSON and treat any non-zero exit code as failure. Use preview --format json to capture rendered Markdown without submitting an issue.

Pre-commit or CI example:

npx github-issue-form-doctor check --strict

Development

npm install
npm test

Tests use node:test, generate temporary fixtures under the OS temp directory, and do not touch the network.

Testing

Acceptance command:

npm test

Package dry run:

npm pack --dry-run

Troubleshooting

Symptom	Cause	Fix
Exit code 2 for a directory	No .github/ISSUE_TEMPLATE directory found	Run from the repo root or pass the repo path
Warnings fail CI	--strict is enabled	Remove unknown keys or run without --strict
Preview fails	The form is invalid or answers JSON has the wrong shape	Run check first and validate the answers file

Contributing

Keep the CLI contract deterministic, avoid network-dependent behavior in tests, add tests for every new diagnostic, and run npm test plus npm pack --dry-run before submitting changes.

License

MIT licensed. See LICENSE.