@hominhtuan/repodoctor

v0.1.2

Published

11 days ago

Zero-config Repository Health, Security & CI Linter for modern open-source projects

0High
0Medium
0Low

hominhtuan

linter repository-health github-actions security-scanner ci-cd open-source sarif code-quality

🩺 RepoDoctor

Zero-config Repository Health, Security & CI Linter for modern open-source projects.

Problem Statement

As open-source repositories grow, they accumulate hygiene decay, security vulnerabilities, and workflow misconfigurations:

GitHub Actions run unpinned floating tags (susceptible to supply-chain attacks).
Workflows lack timeout bounds or concurrency cancellation, burning CI credits.
Sensitive environment variables and keys lack .gitignore coverage.
Missing OSS governance (LICENSE, SECURITY.md, issue templates, PR checklists) slows down contributions.
Conflicting lockfiles or open version ranges break builds unpredictably.

Existing linters are fragmented: ESLint only checks JavaScript ASTs, Flake8 only checks Python, and heavy commercial security scanners require SaaS signups, cloud tokens, or complex setups.

RepoDoctor provides a single, zero-config CLI tool that diagnoses 29 built-in cross-ecosystem repository health rules, computes a deterministic 0-100 Repository Health Score (Grades A+ to F), auto-fixes common violations, and generates standard SARIF 2.1.0 reports for GitHub Code Scanning.

Key Features

⚡ Deterministic & Local-first: Evaluates repositories locally with in-memory parsing caches without requiring network access.
🔒 Security & Supply-Chain Hardened: Detects unpinned GitHub Actions, dangerous pull_request_target usage, plaintext tokens, missing .gitignore secret rules, and curl | sh pipes.
📜 OSS Standards Compliance: Verifies LICENSE integrity, README completeness, CONTRIBUTING guides, CODE_OF_CONDUCT, and SECURITY.md policies.
🚦 CI/CD Best Practices: Validates workflow timeout-minutes, PR concurrency cancellation groups, and multi-OS matrix configurations.
📦 Package & Lockfile Hygiene: Checks for missing lockfiles (npm, yarn, pnpm, cargo, poetry, uv, go), conflicting lockfiles, and unconstrained wildcard * dependencies.
🛠️ One-Command Remediation (repodoctor fix): Safely generates missing .gitattributes, .gitignore secret patterns, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, issue templates, and PR templates.
📊 Multi-Format Reporting: Supports Terminal ANSI tables, JSON, Markdown, GitHub workflow annotations (::error::), and OASIS SARIF v2.1.0 for GitHub Security tab integration.
🎛️ Extensible & Configurable: Zero-config by default, with optional .repodoctor.yml for custom rules, severity overrides, and score thresholds.

Installation & Setup

Local Development / Repository Clone

Clone the repository and install dependencies:

git clone https://github.com/knmt1219/repodoctor.git
cd repodoctor
npm install
npm run build

Run RepoDoctor locally:

# Run health diagnostics
node ./bin/repodoctor.js check .

# Run auto-remediation fixers
node ./bin/repodoctor.js fix .

When Published to npm

Once published to the npm registry, RepoDoctor can be executed directly:

# Run instantly with npx
npx repodoctor check

# Global installation
npm install -g repodoctor

# Project development dependency
npm install --save-dev repodoctor

Quick Start

Run a full health check on your current repository:

node ./bin/repodoctor.js check .

Sample output:

RepoDoctor v0.1.0 — Repository Health & Security Diagnostics
──────────────────────────────────────────────────────────────────────

  WARN  [sec-002] Workflow ".github/workflows/ci.yml" does not declare top-level or job-level 'permissions:' block at .github/workflows/ci.yml:1:1
   └─ Fix: Add `permissions: read-all` or specific granular permissions at the top of the workflow

  WARN  [git-001] Missing .gitattributes file for cross-platform line ending normalization
   └─ Fix: Create a `.gitattributes` file containing `* text=auto eol=lf`.

──────────────────────────────────────────────────────────────────────
 Health Score: 92/100 (Grade: A)
 Category Breakdown: security: 90%  |  oss: 100%  |  ci: 100%  |  package: 100%  |  git: 90%  |  docker: 100%

 Summary: 2 warnings, 1 auto-fixable (29 rules evaluated)

Auto-fix eligible issues immediately:

node ./bin/repodoctor.js fix .

CLI Usage & Commands

repodoctor [command] [options] [target-directory]

Commands

Flags & Options (`check` command)

Rule Catalog

RepoDoctor includes 29 built-in production rules categorized across 6 core domains:

1. 🔒 Security & Supply Chain (`security`)

sec-001 (error): Action Commit SHA Pinning — Ensures GitHub Actions use immutable 40-character commit hashes rather than mutable floating tags (@v4).
sec-002 (warn): Explicit Workflow Permissions — Ensures workflows declare least-privilege permissions: blocks and avoids permissions: write-all.
sec-003 (error, fixable): Gitignore Secrets Coverage — Validates that .gitignore prevents staging .env, *.key, *.pem, and credential files.
sec-004 (error): No Remote Pipe-to-Shell — Flags dangerous curl | sh or wget | bash executions in CI workflows and package scripts.
sec-005 (error): Committed Secret Scanner — Scans tracked files for high-entropy API keys (OpenAI, AWS, Slack, GitHub tokens) and private key headers with automatic redaction.
sec-006 (warn): Safe pull_request_target Usage — Flags risky combinations of pull_request_target triggers checking out untrusted fork head code.

2. 📜 Open Source & Community Standards (`oss`)

oss-001 (error): Valid LICENSE File — Checks for an OSI-compliant, non-empty LICENSE file.
oss-002 (warn): Comprehensive README — Ensures README exists and provides structured documentation.
oss-003 (warn, fixable): CONTRIBUTING Guide — Checks for CONTRIBUTING.md in root or .github/.
oss-004 (info, fixable): Code of Conduct — Checks for CODE_OF_CONDUCT.md.
oss-005 (warn, fixable): SECURITY.md Policy — Verifies a vulnerability reporting policy exists.
oss-006 (info, fixable): Issue Templates — Checks for .github/ISSUE_TEMPLATE/ forms.
oss-007 (info, fixable): Pull Request Template — Checks for .github/pull_request_template.md.
oss-008 (warn): Package Metadata Completeness — Verifies description and repository fields in package manifests.

3. 🚦 CI/CD Best Practices (`ci`)

ci-001 (warn): Workflow Job Timeouts — Ensures all GitHub Actions jobs declare timeout-minutes to avoid runaway billing.
ci-002 (warn): PR Concurrency Cancellation — Ensures PR workflows set concurrency with cancel-in-progress: true and non-empty group to prevent runner backlog.
ci-003 (warn): CI Workflow Presence — Checks that at least one CI workflow is configured in .github/workflows/.
ci-004 (info): Matrix Fail-Fast Policy — Recommends explicit fail-fast configuration on large test matrices.

4. 📦 Package & Dependency Hygiene (`package`)

pkg-001 (error): Committed Lockfile — Ensures package manifests have matching lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.lock, poetry.lock, uv.lock, go.sum).
pkg-002 (error): No Conflicting Lockfiles — Detects accidental co-existence of multiple lockfiles (e.g. package-lock.json AND yarn.lock).
pkg-003 (warn): No Wildcard Dependencies — Flags dangerous * or latest unconstrained dependencies in package.json.
pkg-004 (warn): Standard Lifecycle Scripts — Ensures package.json#scripts defines required executable lifecycle scripts (defaults to ['test'], configurable via options.requiredScripts).

5. 📁 Git & File Structure Hygiene (`git`)

git-001 (warn, fixable): Cross-Platform .gitattributes — Ensures * text=auto eol=lf is configured to prevent CRLF corruption.
git-002 (error): No Merge Conflict Markers — Detects committed <<<<<<<, =======, >>>>>>> markers in files.
git-003 (warn): Large Binary Tracking — Warns on large binary files tracked without Git LFS (defaults to >1024 KB / 1 MB threshold, configurable via options.maxBinarySizeKb).
git-004 (error): No Nested .git Directories — Detects accidental embedded git repositories or unregistered submodules.
git-005 (error): No Broken Symbolic Links — Detects dead or repository-escaping symlinks.

6. 🐳 Docker & Container Hygiene (`docker`)

docker-001 (warn): Base Image Pinning — Warns on :latest or unpinned tags in Dockerfile.
docker-002 (warn, fixable): .dockerignore Presence — Ensures .dockerignore exists when Dockerfile is present.

Configuration

Initialize a configuration file with:

repodoctor init

This creates .repodoctor.yml in your repository root:

# Minimum acceptable health score (0 - 100)
scoreThreshold: 85

# Maximum allowed warnings before exiting with code 1 (-1 for unlimited)
maxWarnings: 0

# Enable or disable categories
categories:
  security: true
  oss: true
  ci: true
  package: true
  git: true
  docker: true

# Custom rule severity overrides ('error', 'warn', 'info', 'off')
rules:
  sec-001: error  # Action SHA pinning
  sec-002: warn   # Workflow permissions
  ci-001: error   # Enforce timeouts as strict errors
  oss-004: off    # Disable Code of Conduct check

# Global analyzer options
options:
  checkTrackedOnly: false       # Scan only git-tracked files when true
  requiredScripts: ['test']      # Lifecycle scripts required by pkg-004
  maxBinarySizeKb: 1024          # Binary size threshold in KB for git-003

# Files and directories to ignore
ignore:
  - '**/legacy/**'
  - '**/fixtures/**'

RepoDoctor also supports .repodoctor.json, .repodoctorrc, or a "repodoctor" section in package.json.

Automated Remediation (Fixers)

Run:

node ./bin/repodoctor.js fix .

RepoDoctor will safely apply non-destructive, idempotent fixes:

git-001: Generates .gitattributes with * text=auto eol=lf.
sec-003: Appends .env, .env.*, *.key, *.pem, and credentials.json rules to .gitignore.
oss-003: Generates CONTRIBUTING.md template.
oss-004: Generates CODE_OF_CONDUCT.md template.
oss-005: Generates SECURITY.md vulnerability reporting policy template.
oss-006: Generates .github/ISSUE_TEMPLATE/ forms (bug_report.yml and feature_request.yml).
oss-007: Generates .github/pull_request_template.md.
docker-002: Generates .dockerignore ignoring node_modules, .git, .env, and build artifacts.

Output Formats & CI Integration

1. Terminal (Default)

repodoctor check

2. SARIF v2.1.0 (for GitHub Code Scanning)

Integrate RepoDoctor directly with GitHub's Security / Code Scanning tab:

# .github/workflows/repodoctor.yml
name: RepoDoctor Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: node ./bin/repodoctor.js check . --format sarif --output results.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@6bb034f26f1da0b37c6335a3983f3333bed7a2ff # v3.28.11
        with:
          sarif_file: results.sarif

3. Markdown Report

Generate rich Markdown tables for $GITHUB_STEP_SUMMARY or PR comments:

repodoctor check --format markdown >> $GITHUB_STEP_SUMMARY

4. JSON (Machine-Readable)

repodoctor check --format json --output report.json

5. GitHub Annotations

Directly annotate pull request diffs using GitHub Actions workflow commands:

repodoctor check --format github

Architecture Overview

                          ┌──────────────────────────┐
                          │   CLI / Entry Point      │
                          │ (Commander, Flags, Args) │
                          └─────────────┬────────────┘
                                        │
                                        ▼
                          ┌──────────────────────────┐
                          │   Config Loader          │
                          │ (.repodoctor.yml, JSON)  │
                          └─────────────┬────────────┘
                                        │
                                        ▼
                          ┌──────────────────────────┐
                          │   RepoDoctor Engine      │
                          │  - Rule Context Cache    │
                          │  - Parallel Rule Runner  │
                          └─────────────┬────────────┘
                                        │
            ┌───────────────────────────┴───────────────────────────┐
            ▼                                                       ▼
  ┌───────────────────────┐                               ┌───────────────────────┐
  │     Rule Catalog      │                               │    Score Calculator   │
  │  - Security (sec-*)   │                               │  - 0-100 Score        │
  │  - OSS (oss-*)        │                               │  - Grade A+ to F      │
  │  - CI (ci-*)          │                               │  - Category Breakdown │
  │  - Package (pkg-*)    │                               └───────────┬───────────┘
  │  - Git (git-*)        │                                           │
  │  - Docker (docker-*)  │                                           │
  └───────────┬───────────┘                                           │
              └─────────────────────────┬─────────────────────────────┘
                                        │
                                        ▼
                          ┌──────────────────────────┐
                          │   Reporters              │
                          │  - Terminal (ANSI)       │
                          │  - SARIF v2.1.0          │
                          │  - Markdown Summary      │
                          │  - JSON / GH Annotations │
                          └──────────────────────────┘

Security Model

Static Analysis: RepoDoctor treats analyzed files as data. The engine performs static inspection without dynamically evaluating or importing target repository executable scripts.
Offline-First Design: RepoDoctor is designed to operate locally on the filesystem without network access.
Path Boundary Protection: Safe file reading and writing utilities verify paths against the repository root boundary to prevent unintended file access outside the target repository.
Secret Redaction: Common API keys and tokens matching built-in patterns are masked before formatting in reports to help avoid accidental exposure in terminal output or CI logs.

Limitations

AST parsing is focused on configuration structures (YAML, JSON, TOML, Dockerfiles, and Git attributes). Deep semantic AST analysis of language-specific logic (e.g. complex TypeScript control flow) is best paired with specialized linters like ESLint.
Git historical scanning checks currently tracked files and .git config; full-history deep commit rewriting is recommended via tools like git-filter-repo.

Development & Testing

Run Tests

npm test

Run Coverage Report

npm run test:coverage

Type Checking & Linting

npm run typecheck
npm run lint

Self-Dogfooding

npm run doctor

Contributing

Contributions are warmly welcome! Please read our Contributing Guide and Code of Conduct before submitting a pull request.

Roadmap

[x] Initial release (v0.1.0) with 29 built-in production rules and SARIF 2.1.0 support
[ ] Pre-commit git hook integration (repodoctor hook install)
[ ] Custom community plugin architecture (repodoctor-plugin-*)
[ ] Monorepo package boundary and workspace dependency analyzer
[ ] Direct PR comment bot GitHub Action