oss-signal 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/README.md +61 -9
- package/action.yml +5 -1
- package/docs/adoption-evidence.md +24 -13
- package/docs/assets/github-step-summary.svg +24 -0
- package/docs/codex-for-oss-application.md +84 -0
- package/docs/examples/github-action-workflow.yml +2 -1
- package/docs/examples/github-code-scanning-workflow.yml +38 -0
- package/docs/examples/github-url-report.md +1 -1
- package/docs/examples/self-audit.sarif +407 -0
- package/docs/maintainer-playbook.md +103 -0
- package/docs/outreach/README.md +5 -5
- package/docs/release-notes/v0.4.0.md +26 -0
- package/docs/release-process.md +82 -0
- package/docs/self-audit.md +1 -1
- package/package.json +1 -1
- package/src/action.js +66 -5
- package/src/cli.js +15 -5
- package/src/index.js +104 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
- Added a maintainer playbook for audit-to-issue, PR, CI gate, and SARIF workflows.
|
|
6
|
+
- Added a documented release process and tag-triggered release workflow with npm dry-run verification.
|
|
7
|
+
|
|
8
|
+
## 0.4.0
|
|
9
|
+
|
|
10
|
+
- Added SARIF output for GitHub Code Scanning and other security dashboards.
|
|
11
|
+
- Added Action support for `format: sarif`.
|
|
12
|
+
|
|
13
|
+
## 0.3.0
|
|
14
|
+
|
|
15
|
+
- Added GitHub Actions step summary output for readable workflow reports.
|
|
16
|
+
- Added a `summary` Action input for turning step summary output on or off.
|
|
17
|
+
|
|
3
18
|
## 0.2.0
|
|
4
19
|
|
|
5
20
|
- Added direct GitHub repository audits for public repositories.
|
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
# oss-signal
|
|
2
2
|
|
|
3
3
|
[](https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml)
|
|
5
|
+
[](https://github.com/SalmonPlays/oss-signal/releases/latest)
|
|
4
6
|
[](https://www.npmjs.com/package/oss-signal)
|
|
5
7
|
[](https://www.npmjs.com/package/oss-signal)
|
|
6
8
|
[](LICENSE)
|
|
7
9
|
|
|
8
10
|
`oss-signal` is a dependency-light CLI for auditing open-source repository maintenance readiness.
|
|
9
11
|
|
|
10
|
-
It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown or
|
|
12
|
+
It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown, JSON, or SARIF.
|
|
11
13
|
|
|
12
14
|

|
|
13
15
|
|
|
@@ -21,7 +23,9 @@ Open-source projects often fail quietly because the maintainer workflow is undoc
|
|
|
21
23
|
- Contributors can attach a report to a cleanup issue or pull request.
|
|
22
24
|
- Teams can gate release readiness with `--fail-under`.
|
|
23
25
|
- Foundations and working groups can compare repository hygiene across many projects.
|
|
24
|
-
- CI maintainers can add it as a GitHub Action and publish the report as an artifact.
|
|
26
|
+
- CI maintainers can add it as a GitHub Action, show the score in the workflow summary, and publish the report as an artifact.
|
|
27
|
+
|
|
28
|
+
See [docs/maintainer-playbook.md](docs/maintainer-playbook.md) for a concrete maintainer workflow from audit to issue, PR, CI gate, and Code Scanning evidence.
|
|
25
29
|
|
|
26
30
|
## Install
|
|
27
31
|
|
|
@@ -29,6 +33,12 @@ Open-source projects often fail quietly because the maintainer workflow is undoc
|
|
|
29
33
|
npm install --global oss-signal
|
|
30
34
|
```
|
|
31
35
|
|
|
36
|
+
Try it without installing:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx oss-signal SalmonPlays/oss-signal
|
|
40
|
+
```
|
|
41
|
+
|
|
32
42
|
For local development:
|
|
33
43
|
|
|
34
44
|
```bash
|
|
@@ -65,6 +75,12 @@ Use JSON in automation:
|
|
|
65
75
|
oss-signal . --format json --fail-under 80
|
|
66
76
|
```
|
|
67
77
|
|
|
78
|
+
Write SARIF for GitHub Code Scanning or other dashboards:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
oss-signal . --format sarif --output oss-signal.sarif
|
|
82
|
+
```
|
|
83
|
+
|
|
68
84
|
Generate a report that can be attached to an issue:
|
|
69
85
|
|
|
70
86
|
```bash
|
|
@@ -81,11 +97,13 @@ oss-signal . --format markdown --output docs/maintainer-readiness.md
|
|
|
81
97
|
|
|
82
98
|
See [docs/rules.md](docs/rules.md) for rule details and scoring weights.
|
|
83
99
|
|
|
100
|
+
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.
|
|
101
|
+
|
|
84
102
|
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.
|
|
85
103
|
|
|
86
104
|
## Real Output
|
|
87
105
|
|
|
88
|
-
This repository audits itself at **100/100 (A)
|
|
106
|
+
This repository audits itself at **100/100 (A)** and dogfoods the public GitHub Action:
|
|
89
107
|
|
|
90
108
|
```text
|
|
91
109
|
Score: 100/100 (A)
|
|
@@ -96,7 +114,9 @@ Summary:
|
|
|
96
114
|
- Total checks: 15
|
|
97
115
|
```
|
|
98
116
|
|
|
99
|
-
See [docs/self-audit.md](docs/self-audit.md) for the full local self-audit report
|
|
117
|
+
See [docs/self-audit.md](docs/self-audit.md) for the full local self-audit report, [docs/examples/github-url-report.md](docs/examples/github-url-report.md) for the GitHub URL audit output, and [docs/examples/self-audit.sarif](docs/examples/self-audit.sarif) for SARIF output.
|
|
118
|
+
|
|
119
|
+
The [Repository health workflow](.github/workflows/repository-health.yml) runs `SalmonPlays/oss-signal@v0.4.0`, uploads the Markdown report as an artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
|
|
100
120
|
|
|
101
121
|
## Field Audits
|
|
102
122
|
|
|
@@ -137,14 +157,19 @@ oss-signal . --fail-under 80
|
|
|
137
157
|
Add `oss-signal` directly to a GitHub Actions workflow:
|
|
138
158
|
|
|
139
159
|
```yaml
|
|
140
|
-
- uses: SalmonPlays/oss-signal@v0.
|
|
160
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
141
161
|
id: oss-signal
|
|
142
162
|
with:
|
|
143
163
|
fail-under: "80"
|
|
144
164
|
output: oss-signal-report.md
|
|
165
|
+
summary: "true"
|
|
145
166
|
- run: echo "score ${{ steps.oss-signal.outputs.score }} (${{ steps.oss-signal.outputs.grade }})"
|
|
146
167
|
```
|
|
147
168
|
|
|
169
|
+
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.
|
|
170
|
+
|
|
171
|
+

|
|
172
|
+
|
|
148
173
|
Full workflow example:
|
|
149
174
|
|
|
150
175
|
```yaml
|
|
@@ -160,18 +185,40 @@ jobs:
|
|
|
160
185
|
runs-on: ubuntu-latest
|
|
161
186
|
steps:
|
|
162
187
|
- uses: actions/checkout@v4
|
|
163
|
-
- uses: SalmonPlays/oss-signal@v0.
|
|
188
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
164
189
|
id: oss-signal
|
|
165
190
|
with:
|
|
166
191
|
fail-under: "80"
|
|
167
192
|
output: oss-signal-report.md
|
|
193
|
+
summary: "true"
|
|
168
194
|
- uses: actions/upload-artifact@v4
|
|
169
195
|
with:
|
|
170
196
|
name: oss-signal-report
|
|
171
197
|
path: oss-signal-report.md
|
|
172
198
|
```
|
|
173
199
|
|
|
174
|
-
See [docs/examples/github-action-workflow.yml](docs/examples/github-action-workflow.yml) for a copyable workflow.
|
|
200
|
+
See [docs/examples/github-action-workflow.yml](docs/examples/github-action-workflow.yml) for a copyable workflow and [docs/examples/github-code-scanning-workflow.yml](docs/examples/github-code-scanning-workflow.yml) for a workflow that uploads SARIF to GitHub Code Scanning.
|
|
201
|
+
|
|
202
|
+
Upload SARIF to GitHub Code Scanning:
|
|
203
|
+
|
|
204
|
+
```yaml
|
|
205
|
+
permissions:
|
|
206
|
+
contents: read
|
|
207
|
+
security-events: write
|
|
208
|
+
|
|
209
|
+
steps:
|
|
210
|
+
- uses: actions/checkout@v4
|
|
211
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
212
|
+
with:
|
|
213
|
+
format: sarif
|
|
214
|
+
output: oss-signal.sarif
|
|
215
|
+
summary: "true"
|
|
216
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
217
|
+
with:
|
|
218
|
+
sarif_file: oss-signal.sarif
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
This repository dogfoods the public Action tag in [Repository health](.github/workflows/repository-health.yml), which runs `SalmonPlays/oss-signal@v0.4.0` against the repository, uploads the Markdown report artifact, and publishes SARIF to Code Scanning on non-PR runs.
|
|
175
222
|
|
|
176
223
|
You can also run the CLI directly in CI:
|
|
177
224
|
|
|
@@ -188,8 +235,13 @@ You can also run the CLI directly in CI:
|
|
|
188
235
|
## Roadmap
|
|
189
236
|
|
|
190
237
|
- Ecosystem-specific profiles for Python, Rust, Go, and JavaScript packages
|
|
191
|
-
-
|
|
192
|
-
-
|
|
238
|
+
- Release automation and provenance metadata checks
|
|
239
|
+
- Maintainer score trends over time
|
|
240
|
+
- Organization-level repository inventory reports
|
|
241
|
+
|
|
242
|
+
## Release Process
|
|
243
|
+
|
|
244
|
+
Releases use the checklist in [docs/release-process.md](docs/release-process.md). The repository also includes a tag-triggered [release workflow](.github/workflows/release.yml) that verifies the package, runs `npm publish --dry-run`, and can publish to npm with provenance when `NPM_TOKEN` is configured.
|
|
193
245
|
|
|
194
246
|
## Contributing
|
|
195
247
|
|
package/action.yml
CHANGED
|
@@ -10,13 +10,17 @@ inputs:
|
|
|
10
10
|
required: false
|
|
11
11
|
default: "."
|
|
12
12
|
format:
|
|
13
|
-
description: Output format, either markdown or
|
|
13
|
+
description: Output format, either markdown, json, or sarif.
|
|
14
14
|
required: false
|
|
15
15
|
default: markdown
|
|
16
16
|
output:
|
|
17
17
|
description: Report file path.
|
|
18
18
|
required: false
|
|
19
19
|
default: oss-signal-report.md
|
|
20
|
+
summary:
|
|
21
|
+
description: Write a concise report to the GitHub Actions step summary.
|
|
22
|
+
required: false
|
|
23
|
+
default: "true"
|
|
20
24
|
fail-under:
|
|
21
25
|
description: Fail the action when the score is below this number.
|
|
22
26
|
required: false
|
|
@@ -5,12 +5,18 @@ This page collects the public evidence that `oss-signal` is built for real open-
|
|
|
5
5
|
## Project Links
|
|
6
6
|
|
|
7
7
|
- Repository: https://github.com/SalmonPlays/oss-signal
|
|
8
|
-
- npm package: https://www.npmjs.com/package/oss-signal
|
|
9
|
-
- GitHub
|
|
8
|
+
- npm package: https://www.npmjs.com/package/oss-signal (`0.3.0` latest)
|
|
9
|
+
- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.4.0
|
|
10
|
+
- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.4.0
|
|
10
11
|
- GitHub Action metadata: [action.yml](../action.yml)
|
|
12
|
+
- Public dogfood workflow: [.github/workflows/repository-health.yml](../.github/workflows/repository-health.yml)
|
|
11
13
|
- Self-audit report: [docs/self-audit.md](self-audit.md)
|
|
14
|
+
- SARIF self-audit output: [docs/examples/self-audit.sarif](examples/self-audit.sarif)
|
|
12
15
|
- GitHub URL audit report: [docs/examples/github-url-report.md](examples/github-url-report.md)
|
|
13
16
|
- GitHub Action workflow example: [docs/examples/github-action-workflow.yml](examples/github-action-workflow.yml)
|
|
17
|
+
- Maintainer playbook: [docs/maintainer-playbook.md](maintainer-playbook.md)
|
|
18
|
+
- Release process: [docs/release-process.md](release-process.md)
|
|
19
|
+
- Codex for Open Source application brief: [docs/codex-for-oss-application.md](codex-for-oss-application.md)
|
|
14
20
|
- Rule reference: [docs/rules.md](rules.md)
|
|
15
21
|
|
|
16
22
|
## Maintainer Use Case
|
|
@@ -22,19 +28,21 @@ The CLI supports two practical modes:
|
|
|
22
28
|
- Local repository audit for maintainers working in a clone.
|
|
23
29
|
- Public GitHub repository audit for quick triage without cloning.
|
|
24
30
|
|
|
25
|
-
It also ships as a GitHub Action, so maintainers can gate repository hygiene in CI
|
|
31
|
+
It also ships as a GitHub Action, so maintainers can gate repository hygiene in CI, show the result in the GitHub Actions step summary, upload a Markdown report as a workflow artifact, and upload failed maintainer-readiness checks as SARIF for GitHub Code Scanning. This repository dogfoods the public Action tag through the Repository health workflow.
|
|
26
32
|
|
|
27
|
-
|
|
33
|
+
The [maintainer playbook](maintainer-playbook.md) documents the end-to-end workflow from audit to issue, pull request, CI gate, and Code Scanning evidence. The [release process](release-process.md) documents pre-release verification, tag consistency, npm publish checks, and post-release smoke tests.
|
|
34
|
+
|
|
35
|
+
## Public Field Audits And PRs
|
|
28
36
|
|
|
29
37
|
The tool has been used to generate maintainer-readiness reports for public repositories and convert them into respectful cleanup issues:
|
|
30
38
|
|
|
31
|
-
| Repository | Report | Posted issue |
|
|
32
|
-
| --- | --- | --- |
|
|
33
|
-
| `platformatic/massimo` | [report](outreach/platformatic-massimo-report.md) | https://github.com/platformatic/massimo/issues/159 |
|
|
34
|
-
| `supermarkt/checkjebon` | [report](outreach/supermarkt-checkjebon-report.md) | https://github.com/supermarkt/checkjebon/issues/22 |
|
|
35
|
-
| `sammorrisdesign/interactive-feed` | [report](outreach/sammorrisdesign-interactive-feed-report.md) | https://github.com/sammorrisdesign/interactive-feed/issues/14 |
|
|
39
|
+
| Repository | Report | Posted issue | Follow-up PR |
|
|
40
|
+
| --- | --- | --- | --- |
|
|
41
|
+
| `platformatic/massimo` | [report](outreach/platformatic-massimo-report.md) | https://github.com/platformatic/massimo/issues/159 | https://github.com/platformatic/massimo/pull/160 |
|
|
42
|
+
| `supermarkt/checkjebon` | [report](outreach/supermarkt-checkjebon-report.md) | https://github.com/supermarkt/checkjebon/issues/22 | https://github.com/supermarkt/checkjebon/pull/23 |
|
|
43
|
+
| `sammorrisdesign/interactive-feed` | [report](outreach/sammorrisdesign-interactive-feed-report.md) | https://github.com/sammorrisdesign/interactive-feed/issues/14 | https://github.com/sammorrisdesign/interactive-feed/pull/15 |
|
|
36
44
|
|
|
37
|
-
These issues are evidence of the intended maintainer workflow: run a deterministic audit, explain the missing signals, and give maintainers a small set of actionable improvements.
|
|
45
|
+
These issues and pull requests are evidence of the intended maintainer workflow: run a deterministic audit, explain the missing signals, and give maintainers a small set of actionable improvements. Each PR is intentionally limited to documentation or GitHub templates.
|
|
38
46
|
|
|
39
47
|
## Verification Commands
|
|
40
48
|
|
|
@@ -43,15 +51,18 @@ From this repository:
|
|
|
43
51
|
```bash
|
|
44
52
|
npm run check
|
|
45
53
|
npm run audit:github
|
|
54
|
+
node src/cli.js . --format sarif --output docs/examples/self-audit.sarif
|
|
46
55
|
node src/cli.js platformatic/massimo --format json
|
|
56
|
+
npx --yes oss-signal@0.3.0 SalmonPlays/oss-signal --format json
|
|
47
57
|
```
|
|
48
58
|
|
|
49
|
-
The current repository self-audit score is 100/100, the GitHub community profile health score is 100, and CI verifies the local GitHub Action wrapper.
|
|
59
|
+
The current repository self-audit score is 100/100, the GitHub community profile health score is 100, and CI verifies the local GitHub Action wrapper. The public `v0.4.0` Action tag is used by the repository health workflow for Markdown and SARIF output. The published npm `0.3.0` package has also been executed from a clean temporary directory against the public GitHub repository.
|
|
50
60
|
|
|
51
61
|
Public CI evidence:
|
|
52
62
|
|
|
53
|
-
-
|
|
54
|
-
-
|
|
63
|
+
- CI workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml
|
|
64
|
+
- Repository health workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml
|
|
65
|
+
- CodeQL workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/codeql.yml
|
|
55
66
|
|
|
56
67
|
## Boundaries
|
|
57
68
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="920" height="470" viewBox="0 0 920 470" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">oss-signal GitHub Actions step summary</title>
|
|
3
|
+
<desc id="desc">Example GitHub Actions step summary showing an oss-signal score of 100 out of 100.</desc>
|
|
4
|
+
<rect width="920" height="470" rx="18" fill="#ffffff"/>
|
|
5
|
+
<rect x="1" y="1" width="918" height="468" rx="18" fill="none" stroke="#d0d7de" stroke-width="2"/>
|
|
6
|
+
<rect x="0" y="0" width="920" height="58" rx="18" fill="#f6f8fa"/>
|
|
7
|
+
<text x="32" y="37" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="18" font-weight="700">GitHub Actions step summary</text>
|
|
8
|
+
<text x="32" y="106" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="30" font-weight="700">oss-signal</text>
|
|
9
|
+
<text x="32" y="154" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="20">Score: </text>
|
|
10
|
+
<text x="94" y="154" fill="#1a7f37" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="20" font-weight="700">100/100 (A)</text>
|
|
11
|
+
<rect x="32" y="190" width="520" height="152" rx="8" fill="#ffffff" stroke="#d0d7de"/>
|
|
12
|
+
<line x1="32" y1="238" x2="552" y2="238" stroke="#d0d7de"/>
|
|
13
|
+
<line x1="32" y1="286" x2="552" y2="286" stroke="#d0d7de"/>
|
|
14
|
+
<line x1="32" y1="342" x2="552" y2="342" stroke="#d0d7de"/>
|
|
15
|
+
<line x1="388" y1="190" x2="388" y2="342" stroke="#d0d7de"/>
|
|
16
|
+
<text x="54" y="222" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16" font-weight="700">Result</text>
|
|
17
|
+
<text x="444" y="222" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16" font-weight="700">Count</text>
|
|
18
|
+
<text x="54" y="270" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16">Passed</text>
|
|
19
|
+
<text x="478" y="270" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16">15</text>
|
|
20
|
+
<text x="54" y="318" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16">Failed</text>
|
|
21
|
+
<text x="486" y="318" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="16">0</text>
|
|
22
|
+
<text x="32" y="390" fill="#24292f" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="21" font-weight="700">Recommended next steps</text>
|
|
23
|
+
<text x="32" y="428" fill="#57606a" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="17">No missing maintainer-readiness checks found.</text>
|
|
24
|
+
</svg>
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Codex for Open Source Application Brief
|
|
2
|
+
|
|
3
|
+
Snapshot: 2026-06-03T03:06:42Z
|
|
4
|
+
|
|
5
|
+
This document summarizes why `oss-signal` is a fit for OpenAI's Codex for Open Source program. The official program page says open-source maintainers can apply, with emphasis on core maintainers, widely used public projects, and projects that play an important ecosystem role: https://developers.openai.com/community/codex-for-oss
|
|
6
|
+
|
|
7
|
+
## Project
|
|
8
|
+
|
|
9
|
+
- Repository: https://github.com/SalmonPlays/oss-signal
|
|
10
|
+
- npm package: https://www.npmjs.com/package/oss-signal
|
|
11
|
+
- GitHub Release: https://github.com/SalmonPlays/oss-signal/releases/tag/v0.4.0
|
|
12
|
+
- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.4.0
|
|
13
|
+
- CI workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/ci.yml
|
|
14
|
+
- Repository health workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/repository-health.yml
|
|
15
|
+
- CodeQL workflow: https://github.com/SalmonPlays/oss-signal/actions/workflows/codeql.yml
|
|
16
|
+
- Maintainer evidence: [adoption-evidence.md](adoption-evidence.md)
|
|
17
|
+
- Maintainer playbook: [maintainer-playbook.md](maintainer-playbook.md)
|
|
18
|
+
- Release process: [release-process.md](release-process.md)
|
|
19
|
+
|
|
20
|
+
## What `oss-signal` Does
|
|
21
|
+
|
|
22
|
+
`oss-signal` is a dependency-light CLI and GitHub Action for OSS maintainers. It audits maintainer-readiness signals that lower recurring maintainer load:
|
|
23
|
+
|
|
24
|
+
- README, license, contribution, support, security, code of conduct, and changelog files.
|
|
25
|
+
- CI, tests, issue templates, pull request templates, Dependabot, and CodeQL-style security workflow.
|
|
26
|
+
- Package metadata and lockfile hygiene.
|
|
27
|
+
|
|
28
|
+
The output is a deterministic score plus actionable next steps in Markdown, JSON, or SARIF. The GitHub Action also writes a workflow step summary so maintainers and reviewers can see the result without downloading an artifact.
|
|
29
|
+
|
|
30
|
+
## Why Codex Helps
|
|
31
|
+
|
|
32
|
+
This project is designed around repeatable maintainer workflows where Codex is useful:
|
|
33
|
+
|
|
34
|
+
- Run audits against public repositories without cloning.
|
|
35
|
+
- Convert findings into focused cleanup issues or pull requests.
|
|
36
|
+
- Keep repository hygiene visible in CI.
|
|
37
|
+
- Upload failed maintainer-readiness checks to GitHub Code Scanning through SARIF.
|
|
38
|
+
- Generate small contributor-facing files that maintainers can review quickly.
|
|
39
|
+
- Use Codex to turn audit findings into scoped documentation and workflow improvements.
|
|
40
|
+
|
|
41
|
+
## Public Evidence
|
|
42
|
+
|
|
43
|
+
The repository currently has:
|
|
44
|
+
|
|
45
|
+
- A published npm package with `0.3.0` as the latest release.
|
|
46
|
+
- A published GitHub Release for v0.4.0 with SARIF release notes and CI usage guidance.
|
|
47
|
+
- A reusable GitHub Action with `score`, `grade`, `failed`, and `report-path` outputs.
|
|
48
|
+
- SARIF output for GitHub Code Scanning integration.
|
|
49
|
+
- A v0.4.0 GitHub Action tag with step summary and SARIF support.
|
|
50
|
+
- A public dogfood workflow that runs `SalmonPlays/oss-signal@v0.4.0` against the repository, uploads the Markdown report artifact, and uploads SARIF to GitHub Code Scanning on non-PR runs.
|
|
51
|
+
- A maintainer playbook that documents audit, triage, issue, PR, CI, and SARIF workflows.
|
|
52
|
+
- A release process and tag-triggered release workflow that verify package contents and support npm provenance publishing when repository secrets are configured.
|
|
53
|
+
- CI and CodeQL workflows passing on `main`.
|
|
54
|
+
- A local self-audit score of 100/100.
|
|
55
|
+
- A clean-directory smoke test of `npx --yes oss-signal@0.3.0 SalmonPlays/oss-signal --format json`, returning 100/100 (A).
|
|
56
|
+
- Public reports, issues, and PRs created from real repository audits.
|
|
57
|
+
|
|
58
|
+
## Field Audits And Follow-Up PRs
|
|
59
|
+
|
|
60
|
+
| Repository | Report | Issue | PR | Status |
|
|
61
|
+
| --- | --- | --- | --- | --- |
|
|
62
|
+
| `platformatic/massimo` | [report](outreach/platformatic-massimo-report.md) | https://github.com/platformatic/massimo/issues/159 | https://github.com/platformatic/massimo/pull/160 | open, mergeable |
|
|
63
|
+
| `supermarkt/checkjebon` | [report](outreach/supermarkt-checkjebon-report.md) | https://github.com/supermarkt/checkjebon/issues/22 | https://github.com/supermarkt/checkjebon/pull/23 | open, mergeable |
|
|
64
|
+
| `sammorrisdesign/interactive-feed` | [report](outreach/sammorrisdesign-interactive-feed-report.md) | https://github.com/sammorrisdesign/interactive-feed/issues/14 | https://github.com/sammorrisdesign/interactive-feed/pull/15 | open, mergeable |
|
|
65
|
+
|
|
66
|
+
These PRs are intentionally small and maintainer-friendly. They add documentation or GitHub templates rather than changing product code.
|
|
67
|
+
|
|
68
|
+
## Application Positioning
|
|
69
|
+
|
|
70
|
+
Recommended application angle:
|
|
71
|
+
|
|
72
|
+
`oss-signal` is not yet a widely adopted project, but it is a public OSS maintainer tool built specifically for repeatable Codex-assisted maintenance. The project already has a working CLI, npm distribution, GitHub Action, passing CI/CodeQL, self-audit evidence, and three public field-audit PRs. Codex support would be used to continue auditing repositories, prepare focused maintainer PRs, improve Action automation, and document repeatable OSS maintenance workflows.
|
|
73
|
+
|
|
74
|
+
## Current Gaps
|
|
75
|
+
|
|
76
|
+
- External PRs are open but not yet merged.
|
|
77
|
+
- npm download metrics are still early because the package is newly published.
|
|
78
|
+
- The project needs more real maintainers using the Action in their own repositories.
|
|
79
|
+
|
|
80
|
+
## Next Evidence To Collect
|
|
81
|
+
|
|
82
|
+
- One or more merged external PRs.
|
|
83
|
+
- A public workflow run in another repository using `SalmonPlays/oss-signal@v0.4.0`, ideally with SARIF upload enabled.
|
|
84
|
+
- npm download data once the registry starts reporting weekly/monthly counts.
|
|
@@ -10,11 +10,12 @@ jobs:
|
|
|
10
10
|
runs-on: ubuntu-latest
|
|
11
11
|
steps:
|
|
12
12
|
- uses: actions/checkout@v4
|
|
13
|
-
- uses: SalmonPlays/oss-signal@v0.
|
|
13
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
14
14
|
id: oss-signal
|
|
15
15
|
with:
|
|
16
16
|
fail-under: "80"
|
|
17
17
|
output: oss-signal-report.md
|
|
18
|
+
summary: "true"
|
|
18
19
|
- uses: actions/upload-artifact@v4
|
|
19
20
|
with:
|
|
20
21
|
name: oss-signal-report
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
name: Repository health
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
push:
|
|
6
|
+
branches: [main]
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
security-events: write
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
oss-signal:
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
19
|
+
id: oss-signal
|
|
20
|
+
with:
|
|
21
|
+
fail-under: "80"
|
|
22
|
+
output: oss-signal-report.md
|
|
23
|
+
summary: "true"
|
|
24
|
+
- uses: SalmonPlays/oss-signal@v0.4.0
|
|
25
|
+
with:
|
|
26
|
+
format: sarif
|
|
27
|
+
output: oss-signal.sarif
|
|
28
|
+
summary: "false"
|
|
29
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
30
|
+
if: github.event_name != 'pull_request'
|
|
31
|
+
with:
|
|
32
|
+
sarif_file: oss-signal.sarif
|
|
33
|
+
- uses: actions/upload-artifact@v4
|
|
34
|
+
with:
|
|
35
|
+
name: oss-signal-report
|
|
36
|
+
path: |
|
|
37
|
+
oss-signal-report.md
|
|
38
|
+
oss-signal.sarif
|