oss-pulse

oss-pulse turns local repository maintenance signals into a small health report that works in a terminal, CI job, or GitHub step summary.

The first release is intentionally narrow: it checks whether a repository has the surfaces that help outside contributors succeed.

Install

npm install
npm run build
node dist/cli.js scan . --format markdown

After the package is published:

npx --yes [email protected] scan . --format markdown

CLI

oss-pulse scan [path] --format markdown
oss-pulse scan [path] --format json
oss-pulse scan [path] --format release-notes
oss-pulse scan [path] --format action-summary
oss-pulse scan [path] --format contributor-onboarding
oss-pulse scan [path] --format triage-suggestions
oss-pulse scan [path] --format sarif
oss-pulse scan [path] --format github-annotations
oss-pulse scan [path] --format markdown --output pulse.md
oss-pulse scan [path] --format markdown --fail-under 80
oss-pulse scan [path] --format markdown --summary-only

Choose the output format by audience:

| Format | Use it when you need | | --- | --- | | markdown | A readable maintainer report for terminals, PR summaries, or GITHUB_STEP_SUMMARY. | | json | Stable machine-readable output for dashboards, scripts, or repository automation. | | release-notes | A first draft of release notes from current readiness signals. | | action-summary | Compact Markdown for GitHub step summaries with score, status, and the top three actions. | | contributor-onboarding | A contributor-facing checklist for setup and first contribution paths. | | triage-suggestions | Maintainer prompts for turning missing surfaces into issues or review tasks. | | sarif | GitHub code scanning or security dashboard ingestion. | | github-annotations | CI annotations that surface high/medium/low remediation actions directly in checks. |

The report includes:

• maintainer readiness score
• README, license, contribution guide, issue templates, good first issue template, security policy, CI, release workflow, changelog, funding, and activity checks
• ranked next actions
• JSON output for automation
• JSON Schema for automation consumers at docs/report.schema.json
• Markdown output for GitHub summaries
• release notes draft output for maintainer updates
• Action-focused summary output for compact GitHub step summaries
• contributor onboarding output for first-time contributors
• triage suggestions for issue queues and pull request review
• SARIF output for GitHub code scanning and security dashboards
• GitHub workflow annotations for visible CI warnings and errors
• optional CI failure when score is below --fail-under
• compact Markdown output with --summary-only

Examples

Local pre-release audit:

npm run build
node dist/cli.js scan . --format markdown --fail-under 80

Pull request summary gate:

npx --yes [email protected] scan . --format markdown --summary-only --fail-under 80 >> "$GITHUB_STEP_SUMMARY"

Release notes draft:

npx --yes [email protected] scan . --format release-notes

Action-focused summary:

npx --yes [email protected] scan . --format action-summary

Contributor onboarding report:

npx --yes [email protected] scan . --format contributor-onboarding

Issue and pull request triage:

npx --yes [email protected] scan . --format triage-suggestions

SARIF for code scanning:

npx --yes [email protected] scan . --format sarif --output oss-pulse.sarif

GitHub workflow annotations:

npx --yes [email protected] scan . --format github-annotations

GitHub Actions

name: OSS Pulse

on:
  pull_request:
  workflow_dispatch:

jobs:
  pulse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - run: npx --yes [email protected] scan . --format markdown --summary-only --fail-under 80 >> "$GITHUB_STEP_SUMMARY"

Repository Action usage with a pinned release tag:

- uses: 2Eungk/[email protected]
  with:
    path: "."
    format: markdown
    fail-under: "80"
    summary-only: "true"

Action inputs:

| Input | Default | Description | | --- | --- | --- | | path | . | Repository path to scan. | | format | markdown | One of markdown, json, release-notes, action-summary, contributor-onboarding, triage-suggestions, sarif, or github-annotations. | | fail-under | 0 | Exit 1 when the score is below this threshold. | | summary-only | false | Emit compact Markdown with score and next actions. |

Prefer a pinned release tag for the repository Action instead of a branch name.

When format is github-annotations, the Action prints workflow commands to stdout so GitHub can render annotations in the checks UI.

Why

Most maintainer tools wait until a project is already busy. oss-pulse starts earlier: it makes missing contribution paths visible before a community arrives.

This project is built for maintainers who want a practical route toward a healthier open source project and measurable public contribution history.

Roadmap

See ROADMAP.md for the product path and CONTRIBUTOR_BACKLOG.md for issues designed for first-time contributors.

For automation consumers, see REPORT_SCHEMA.md. For real repository examples, see docs/examples.

Contributing

See CONTRIBUTING.md.

Release

See RELEASE.md for the npm and GitHub release path.