npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

oss-signal

v0.9.8

Published

Maintainer-readiness CLI and GitHub Action for OSS triage, CI evidence, inventory reports, SARIF, issue-ready cleanup, workflow trials, adoption packs, transparent rule catalogs, and JSON schemas.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

nzamonodanzamonoda

Keywords

open-sourcemaintainermaintainer-toolsauditrepositoryrepository-healthgithub-actionsarifcli

Readme

OSS Maintainer Signal (oss-signal)

CI Repository health Evidence verification OpenSSF Scorecard GitHub release GitHub Marketplace npm version npm downloads Self audit Maintainer evidence License: MIT

oss-signal is a dependency-light maintainer-readiness CLI and GitHub Action for OSS projects that need repeatable triage, CI evidence, SARIF, inventory reports, issue-ready cleanup notes, adoption packs, a transparent rule catalog, and no-fail workflow trials.

It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, maintainer ownership, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown, JSON, SARIF, inventory, GitHub Issue-ready Markdown, PR-sized maintainer plan, no-fail workflow, adoption-pack, or rule-catalog formats.

oss-signal example output

30-Second Quick Start

Run a maintainer-readiness report against any public GitHub repository:

npx oss-signal owner/repo --format markdown --output oss-signal-report.md

Generate an editable issue body before posting a cleanup suggestion:

npx oss-signal owner/repo --format issue --output maintainer-follow-up.md

Generate a no-fail GitHub Actions trial workflow:

npx oss-signal owner/repo --format workflow --output .github/workflows/oss-signal-trial.yml

Generate a copyable maintainer adoption pack:

npx oss-signal owner/repo --format adoption --output adoption-pack.md

Inspect the rule weights before posting feedback:

npx oss-signal --list-rules

For the full first-run path, see docs/quickstart.md.

Who It Helps

  • Maintainers who want a quick view of missing workflow signals before a release.
  • Contributors who want to open small, reviewable documentation or automation PRs.
  • Teams that need a repeatable CI artifact for repository health and maintainer-readiness.
  • Foundations or working groups that need inventory reports across multiple repositories.

Maintainer Evidence Snapshot

The shortest reviewer path is REVIEWER_PACKET.md. Public evidence for the maintainer workflow is also collected in docs/index.md, docs/quickstart.md, docs/evidence-ledger.md, docs/trust-center.md, docs/reviewer-evidence.md, docs/adoption-evidence.md, docs/codex-for-oss-fit-gap.md, docs/selection-update-2026-06-08.md, docs/adoption-kit.md, docs/maintainer-trial.md, docs/maintainer-feedback.md, docs/social-launch.md, docs/architecture.md, docs/security-model.md, docs/json-output.md, docs/plan-output.md, docs/sarif-code-scanning.md, docs/roadmap.md, docs/post-submission-update.md, and docs/brand.md.

Why

Open-source projects often fail quietly because the maintainer workflow is undocumented. oss-signal gives maintainers a repeatable checklist they can run locally, in CI, or before asking contributors to help.

Use Cases

  • Maintainers can run it before publishing a new project.
  • Contributors can attach a report to a cleanup issue or pull request.
  • Teams can gate release readiness with --fail-under.
  • Foundations and working groups can compare repository hygiene across many projects.
  • CI maintainers can add it as a GitHub Action, show the score in the workflow summary, and publish the report as an artifact.

See docs/maintainer-playbook.md for a concrete maintainer workflow from audit to issue, PR, CI gate, and Code Scanning evidence.

Install

npm install --global oss-signal

Try it without installing:

npx oss-signal SalmonPlays/oss-signal

Use it from GitHub Marketplace: https://github.com/marketplace/actions/oss-signal

For local development:

git clone https://github.com/SalmonPlays/oss-signal.git
cd oss-signal
npm install
npm test

Usage

Audit the current directory:

oss-signal

Show a one-screen maintainer triage summary:

oss-signal SalmonPlays/oss-signal --format summary

Show the rule catalog and scoring weights:

oss-signal --list-rules
oss-signal --list-rules --format json --output rules-catalog.json

Audit a public GitHub repository without cloning it:

oss-signal https://github.com/SalmonPlays/oss-signal
oss-signal platformatic/massimo --format json

Write a Markdown report:

oss-signal /path/to/repo --format markdown --output oss-signal-report.md

Use JSON in automation:

oss-signal . --format json --fail-under 80

Print a compact shell-friendly score summary (jq optional):

oss-signal . --format json | jq -r '"score=\(.score) grade=\(.grade) source=\(.source)"'

See docs/json-output.md for the JSON schema and fixture.

Document intentional exceptions with a local config:

oss-signal . --config .oss-signal.json --format markdown

See docs/configuration.md for not-applicable rules and scoring behavior.

Audit multiple repositories from one newline-delimited inventory file:

oss-signal --inventory docs/examples/inventory-targets.txt --format markdown --output inventory-report.md

See docs/examples/inventory-report.md for a generated inventory report.

Write SARIF for GitHub Code Scanning or other dashboards:

oss-signal . --format sarif --output oss-signal.sarif

See docs/sarif-code-scanning.md for the Code Scanning upload workflow and expected output.

Generate a report that can be attached to an issue:

oss-signal . --format markdown --output docs/maintainer-readiness.md

Generate a maintainer-friendly issue body:

oss-signal platformatic/massimo --format issue --output maintainer-follow-up.md

Generate a PR-sized maintainer plan:

oss-signal platformatic/massimo --format plan --output maintainer-plan.md

See docs/plan-output.md and docs/examples/github-plan.md for an example.

Generate a maintainer adoption pack:

oss-signal platformatic/massimo --format adoption --output adoption-pack.md

The adoption pack combines a local trial command, no-fail workflow YAML, suggested maintainer message, decision checklist, current findings, verification links, and boundaries against overstating adoption.

Generate a no-fail GitHub Actions trial workflow:

oss-signal owner/repo --format workflow --output .github/workflows/oss-signal-trial.yml

See docs/maintainer-trial.md and docs/examples/maintainer-trial-workflow.yml for the generated workflow.

Checks

oss-signal currently checks:

  • Community files: README, license, contributing guide, security policy, code of conduct, changelog, support policy, maintainer ownership
  • Automation: CI workflows, tests, issue templates, pull request template, Dependabot, CodeQL or similar security workflow
  • Package hygiene: package metadata and lockfile presence

See docs/rules.md for rule details and scoring weights.

SARIF output reports failed maintainer-readiness checks as warning-level results. This lets teams upload the audit to code scanning dashboards while keeping the Markdown report available for maintainers. Issue output turns the same findings into a human-reviewed checklist that can be edited before posting. Plan output turns the findings into a PR-sized sequence with suggested files and acceptance criteria.

For GitHub URL audits, oss-signal reads the repository file tree through the GitHub API and also uses GitHub's community profile signal when available. This lets it detect organization-level files such as a shared code of conduct.

Real Output

This repository audits itself at 100/100 (A) and dogfoods the public GitHub Action:

Score: 100/100 (A)

Summary:
- Passed: 16
- Failed: 0
- Total checks: 16

See docs/self-audit.md for the full local self-audit report, docs/examples/github-url-report.md for the GitHub URL audit output, docs/examples/github-summary.txt for compact summary output, docs/examples/github-issue-body.md for issue output, docs/examples/github-plan.md for plan output, docs/examples/maintainer-trial-workflow.yml for workflow output, docs/examples/adoption-pack.md for adoption-pack output, docs/examples/self-audit.sarif for SARIF output, and docs/examples/rules-catalog.json for the machine-readable rule catalog.

The Repository health workflow runs SalmonPlays/[email protected], uploads the Markdown report and adoption pack as artifacts, includes a SHA256 checksum manifest, and uploads SARIF to GitHub Code Scanning on non-PR runs. The Repository inventory workflow runs the inventory mode from CI and uploads a multi-repository report artifact.

Field Audits

oss-signal has been run against public repositories to produce maintainer-readiness reports, respectful issue drafts, and focused follow-up PRs:

See docs/outreach for the reports and draft issue text. Drafts are not posted automatically; maintainers should only receive specific, useful, and respectful suggestions.

Historical audit reports for Grovanni/oss-signal and noctemlabs/signal-oss remain in the repository as examples, but their public issue or PR links were not verifiable on 2026-06-08 and are not counted as current public evidence.

Additional prepared outreach candidates are tracked in docs/outreach/peer-shortlist-2026-06.md. The shortlist explicitly separates respectful, defensible candidates from low-signal mass outreach.

Additional focused external contribution evidence: icoretech/codex-action PR #24 was merged by an outside maintainer and updates Codex Action README examples to route generated output through environment variables before printing it from shell steps. oss-signal PR #14 was opened by an outside contributor and merged into this repository with a compact JSON score example.

For a compact maintainer/adoption summary, see docs/adoption-evidence.md. For a reviewer-oriented verification path, see docs/reviewer-evidence.md.

Separate public workflow evidence: SalmonPlays/oss-signal-adoption-demo runs SalmonPlays/[email protected] and produced a successful workflow run with Markdown, SARIF, Issue-ready, and no-fail workflow artifacts.

Example Recommendation Output

Score: 86/100 (B)

Recommended next steps:
- Static security analysis: Add a CodeQL or equivalent security scanning workflow.
- Support policy: Add SUPPORT.md describing where to ask questions.

See docs/examples/minimal-repo-report.md for a small repository example with missing maintainer files.

Exit Codes

By default, oss-signal exits with 0 after writing a report.

When --fail-under <score> is provided, it exits with 1 if the score is below the threshold:

oss-signal . --fail-under 80

GitHub Action

Add oss-signal directly to a GitHub Actions workflow:

- uses: SalmonPlays/[email protected]
  id: oss-signal
  with:
    fail-under: "80"
    output: oss-signal-report.md
    summary: "true"
- run: echo "score ${{ steps.oss-signal.outputs.score }} (${{ steps.oss-signal.outputs.grade }})"

The Action writes a concise GitHub Actions step summary by default, so reviewers can see the score and recommended next steps without downloading an artifact. Set summary: "false" to disable it.

oss-signal GitHub Actions summary

Run an inventory from CI:

- uses: SalmonPlays/[email protected]
  env:
    GITHUB_TOKEN: ${{ github.token }}
  with:
    inventory: docs/examples/inventory-targets.txt
    output: inventory-report.md
    summary: "true"

Generate an editable Issue body from CI:

- uses: SalmonPlays/[email protected]
  with:
    format: issue
    output: maintainer-follow-up.md
    summary: "true"

Full workflow example:

name: Repository health

on:
  pull_request:
  push:
    branches: [main]

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  oss-signal:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: SalmonPlays/[email protected]
        id: oss-signal
        with:
          fail-under: "80"
          output: oss-signal-report.md
          summary: "true"
      - uses: actions/upload-artifact@v5
        with:
          name: oss-signal-report
          path: oss-signal-report.md

See docs/examples/github-action-workflow.yml for a copyable workflow, docs/examples/github-inventory-workflow.yml for an inventory workflow, and docs/examples/github-code-scanning-workflow.yml for a workflow that uploads SARIF to GitHub Code Scanning.

Upload SARIF to GitHub Code Scanning:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v5
  - uses: SalmonPlays/[email protected]
    with:
      format: sarif
      output: oss-signal.sarif
      summary: "true"
  - uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: oss-signal.sarif

This repository dogfoods the public Action tag in Repository health, which runs SalmonPlays/[email protected] against the repository, uploads Markdown and adoption-pack artifacts with a SHA256 manifest, and publishes SARIF to Code Scanning on non-PR runs.

You can also run the CLI directly in CI:

- run: npx oss-signal . --format markdown --output oss-signal-report.md --fail-under 80

Current Limitations

  • It checks deterministic maintenance signals, not code quality or project importance.
  • GitHub URL mode uses unauthenticated API requests unless GITHUB_TOKEN is set, so very heavy usage may hit GitHub rate limits.
  • A high score does not prove a project is important. It proves the maintainer workflow is documented and automatable.

Roadmap

  • Ecosystem-specific profiles for Python, Rust, Go, and JavaScript packages
  • Release automation and provenance metadata checks
  • Maintainer score trends over time
  • Organization-level repository inventory dashboards

Release Process

Releases use the checklist in docs/release-process.md. The repository also includes a tag-triggered release workflow that verifies the package, creates a GitHub Release, and publishes to npm with Trusted Publishing provenance.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Security

Please report security issues privately. See SECURITY.md.

License

MIT