contribcheck 0.1.0__tar.gz

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.
@@ -0,0 +1,16 @@
1
+ .DS_Store
2
+ .env
3
+ .idea/
4
+ .mypy_cache/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .uv-cache/
8
+ .venv/
9
+ __pycache__/
10
+ *.egg-info/
11
+ *.py[cod]
12
+ .coverage
13
+ coverage.xml
14
+ htmlcov/
15
+ dist/
16
+ build/
@@ -0,0 +1,36 @@
1
+ # Contributing
2
+
3
+ Thank you for helping improve ContribCheck.
4
+
5
+ ## Before Starting
6
+
7
+ 1. Search existing issues and pull requests for overlapping work.
8
+ 2. Comment on the issue with a short implementation plan.
9
+ 3. Wait for confirmation when the issue is assigned or changes a public contract.
10
+
11
+ ## Development Setup
12
+
13
+ ```bash
14
+ git clone https://github.com/gokul-debugger/contribcheck.git
15
+ cd contribcheck
16
+ uv sync --all-extras --dev
17
+ ```
18
+
19
+ Run the complete local check set:
20
+
21
+ ```bash
22
+ uv run ruff check .
23
+ uv run ruff format --check .
24
+ uv run mypy src tests
25
+ uv run pytest --cov=contribcheck --cov-report=term-missing
26
+ ```
27
+
28
+ ## Design Rules
29
+
30
+ - Base verdicts on deterministic, linkable evidence.
31
+ - Report unavailable evidence as `unknown`; do not quietly treat it as a pass.
32
+ - Keep GitHub access read-only.
33
+ - Add a focused test for every new signal or failure mode.
34
+ - Avoid heuristics that cannot explain why they fired.
35
+
36
+ Pull requests should be narrowly scoped and describe the behavior being changed, its motivation, and the checks that were run.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gokul Krishna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,300 @@
1
+ Metadata-Version: 2.5
2
+ Name: contribcheck
3
+ Version: 0.1.0
4
+ Summary: Check whether a GitHub issue is genuinely ready for open-source contribution
5
+ Project-URL: Homepage, https://github.com/gokul-debugger/contribcheck
6
+ Project-URL: Documentation, https://github.com/gokul-debugger/contribcheck#readme
7
+ Project-URL: Issues, https://github.com/gokul-debugger/contribcheck/issues
8
+ Project-URL: Releases, https://github.com/gokul-debugger/contribcheck/releases
9
+ Project-URL: Source, https://github.com/gokul-debugger/contribcheck
10
+ Author: Gokul Krishna
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: cli,contributors,developer-tools,fastapi,github,github-api,issue-tracker,open-source,open-source-contributions
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Software Development :: Version Control :: Git
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: httpx<1,>=0.28.1
25
+ Requires-Dist: pydantic<3,>=2.11
26
+ Requires-Dist: rich<15,>=14
27
+ Requires-Dist: typer<1,>=0.16
28
+ Provides-Extra: server
29
+ Requires-Dist: fastapi<1,>=0.116; extra == 'server'
30
+ Requires-Dist: uvicorn[standard]<1,>=0.35; extra == 'server'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # ContribCheck: GitHub Issue Readiness Checker
34
+
35
+ An evidence-based CLI and API that checks whether a GitHub issue is genuinely ready for an open-source contribution.
36
+
37
+ [![CI](https://github.com/gokul-debugger/contribcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/gokul-debugger/contribcheck/actions/workflows/ci.yml)
38
+ [![PyPI](https://img.shields.io/pypi/v/contribcheck?logo=pypi&logoColor=white)](https://pypi.org/project/contribcheck/)
39
+ [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
40
+ [![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
41
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/gokul-debugger/contribcheck/blob/main/LICENSE)
42
+
43
+ ContribCheck identifies blockers that issue-discovery lists often miss: dependency issues, missing base branches, existing assignments, comment claims, competing pull requests, unhealthy default-branch CI, and missing contribution guidance.
44
+
45
+ It does not predict whether a maintainer will merge a pull request. Every result is linked to observable GitHub state, and signals that cannot be verified are reported as `unknown` instead of silently passing.
46
+
47
+ ## Real-World Example
48
+
49
+ Two open issues from the same repository can look equally available while having very different readiness states.
50
+
51
+ ### Blocked by a prerequisite
52
+
53
+ ```bash
54
+ contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/986 \
55
+ --actor gokul-debugger
56
+ ```
57
+
58
+ ```text
59
+ Lyrics models
60
+ https://github.com/sigma67/ytmusicapi/issues/986
61
+ Verdict: BLOCKED
62
+
63
+ FAILURE Dependencies Blocked by 1 open issue(s).
64
+ FAILURE Base branch Required branch `ytmusicapi-2` does not exist.
65
+ PASS Assignment Assigned to the requested contributor.
66
+ PASS Competing PRs No open pull request referencing this issue was found.
67
+
68
+ Next actions
69
+ - Wait for the listed dependency issues to close.
70
+ - Ask the maintainer to create or clarify the required base branch.
71
+ - Read the repository contribution guide before creating a branch.
72
+ ```
73
+
74
+ ContribCheck prevents work from starting too early: the contributor is assigned, but the required dependency and base branch are not ready.
75
+
76
+ ### Ready for contribution
77
+
78
+ ```bash
79
+ contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/941
80
+ ```
81
+
82
+ ```text
83
+ get_song() can return stale likeStatus right after rate_song()
84
+ https://github.com/sigma67/ytmusicapi/issues/941
85
+ Verdict: READY
86
+
87
+ PASS Dependencies No open blockers reported.
88
+ PASS Assignment The issue is unassigned.
89
+ PASS Comment claims No other contributor appears to have claimed it.
90
+ PASS Competing PRs No open pull request referencing this issue was found.
91
+ PASS Default branch CI Latest runs for 4 workflow(s) are green.
92
+ PASS Maintainer response A maintainer first replied after approximately 8 hours.
93
+
94
+ Next actions
95
+ - Read the repository contribution guide before creating a branch.
96
+ - Comment with a concise implementation plan before starting work.
97
+ ```
98
+
99
+ Here the evidence supports beginning the contribution workflow, while still recommending coordination with the maintainer.
100
+
101
+ ## Why It Exists
102
+
103
+ Labels such as `good first issue` and `help wanted` are useful discovery signals, but they do not guarantee that an issue is actionable. A contribution can still be blocked by another issue, depend on a branch that has not been created, overlap an existing pull request, or wait in a repository whose default CI is already failing.
104
+
105
+ ContribCheck performs that second-stage verification before a contributor invests hours in setup and implementation.
106
+
107
+ ## Checks
108
+
109
+ | Check | Evidence | Effect |
110
+ |---|---|---|
111
+ | Issue state | GitHub issue state | Closed issues block work |
112
+ | Dependencies | GitHub issue dependency API | Open dependencies block work |
113
+ | Base branch | Explicit branch named in the issue body | A missing required branch blocks work |
114
+ | Assignment | Current assignees | Another assignee blocks uncoordinated work |
115
+ | Comment claims | Explicit work-claim phrases | Produces a caution |
116
+ | Competing PRs | Timeline cross-references and PR search | Produces a caution |
117
+ | Scope | Issue body and acceptance-language markers | Warns when clarification may be needed |
118
+ | Contribution guide | Repository tree | Warns when standard guidance is absent |
119
+ | Repository health | Archive status and recent push activity | Blocks archived repositories, warns on inactivity |
120
+ | Default CI | Latest completed workflow run per workflow | Warns about pre-existing failures |
121
+ | Maintainer response | Comment author association and timestamps | Reports issue-level responsiveness |
122
+
123
+ The overall result is one of:
124
+
125
+ - `ready`: no blocking, warning, or unknown signals were found
126
+ - `caution`: manual review is needed
127
+ - `blocked`: a hard prerequisite is not satisfied
128
+
129
+ ## Installation
130
+
131
+ ContribCheck requires Python 3.11 or newer.
132
+
133
+ ```bash
134
+ pipx install contribcheck
135
+ ```
136
+
137
+ Alternatively, install it into an existing Python environment with `pip install contribcheck`. The optional web service is available with `pip install "contribcheck[server]"`.
138
+
139
+ Public GitHub requests work without authentication, but GitHub applies a much smaller anonymous rate limit. Set a token for regular use:
140
+
141
+ ```bash
142
+ export GITHUB_TOKEN="your-fine-grained-token"
143
+ ```
144
+
145
+ Read-only access to public metadata is sufficient. Do not grant write permissions.
146
+
147
+ ## CLI
148
+
149
+ Inspect by URL:
150
+
151
+ ```bash
152
+ contribcheck inspect https://github.com/owner/repository/issues/123
153
+ ```
154
+
155
+ Inspect by shorthand and emit JSON:
156
+
157
+ ```bash
158
+ contribcheck inspect owner/repository#123 --actor your-username --json
159
+ ```
160
+
161
+ Use the result in CI or a script:
162
+
163
+ ```bash
164
+ contribcheck inspect owner/repository#123 --fail-on caution
165
+ ```
166
+
167
+ Exit codes are `0` for a completed inspection, `1` for an operational error, and `2` when the configured readiness threshold is reached.
168
+
169
+ Render a portable GitHub-flavored Markdown report:
170
+
171
+ ```bash
172
+ contribcheck inspect owner/repository#123 --markdown
173
+ contribcheck inspect owner/repository#123 --markdown --output report.md
174
+ ```
175
+
176
+ Markdown reports include the issue title and URL, verdict, check summaries, linked evidence, and next actions. `--markdown` and `--json` cannot be used together. Existing terminal output remains the default.
177
+
178
+ Inspect several candidates from a text file while preserving input order:
179
+
180
+ ```text
181
+ # candidates.txt
182
+ sigma67/ytmusicapi#986
183
+ https://github.com/plotly/plotly.js/issues/7750
184
+ ```
185
+
186
+ ```bash
187
+ contribcheck batch candidates.txt --actor your-username
188
+ contribcheck batch candidates.txt --json --fail-on caution
189
+ ```
190
+
191
+ Batch JSON uses a stable top-level object with `schema_version`, ordered `results`, and a `summary` containing total, success, failure, and verdict counts. Each failed item is reported independently instead of discarding successful inspections. Batch concurrency defaults to four and can be changed with `--concurrency`.
192
+
193
+ Batch exit codes are `0` when processing completes without reaching the configured threshold, `1` when input or processing fails for at least one item, and `2` when a successful report reaches the configured `--fail-on` threshold.
194
+
195
+ ### GitHub Enterprise Server
196
+
197
+ Set the API endpoint with `GITHUB_API_URL`, or override it for one command with `--base-url`:
198
+
199
+ ```bash
200
+ export GITHUB_API_URL="https://github.example.com/api/v3"
201
+ contribcheck inspect https://github.example.com/team/project/issues/123
202
+ contribcheck inspect team/project#123 --base-url https://github.example.com/api/v3
203
+ ```
204
+
205
+ The precedence is CLI option, `GITHUB_API_URL`, then `https://api.github.com`. The endpoint must be HTTP or HTTPS and cannot contain credentials, query parameters, or fragments. Tokens are sent only to the configured API endpoint.
206
+
207
+ ## Python SDK
208
+
209
+ ```python
210
+ import asyncio
211
+
212
+ from contribcheck import GitHubClient, IssueAnalyzer
213
+
214
+
215
+ async def main() -> None:
216
+ async with GitHubClient() as client:
217
+ report = await IssueAnalyzer(client).inspect(
218
+ "https://github.com/sigma67/ytmusicapi/issues/986",
219
+ actor="gokul-debugger",
220
+ )
221
+ print(report.status)
222
+ print(report.check("dependencies").summary)
223
+
224
+
225
+ asyncio.run(main())
226
+ ```
227
+
228
+ ## HTTP API
229
+
230
+ Install server dependencies and start FastAPI:
231
+
232
+ ```bash
233
+ pip install -e '.[server]'
234
+ contribcheck serve
235
+ ```
236
+
237
+ Open `http://127.0.0.1:8000/` for the browser interface or `http://127.0.0.1:8000/docs` for the interactive API documentation. The browser interface sends only the issue reference and optional actor to the local API. It does not accept, store, or log GitHub tokens.
238
+
239
+ ![ContribCheck web interface](https://raw.githubusercontent.com/gokul-debugger/contribcheck/main/docs/contribcheck-ui.png)
240
+
241
+ Call the API directly:
242
+
243
+ ```bash
244
+ curl -X POST http://127.0.0.1:8000/v1/inspect \
245
+ -H 'Content-Type: application/json' \
246
+ -d '{
247
+ "url": "https://github.com/sigma67/ytmusicapi/issues/986",
248
+ "actor": "gokul-debugger"
249
+ }'
250
+ ```
251
+
252
+ The service accepts an optional `Authorization: Bearer ...` header. It never stores the token.
253
+
254
+ ## Docker
255
+
256
+ ```bash
257
+ docker build -t contribcheck .
258
+ docker run --rm -p 8000:8000 -e GITHUB_TOKEN contribcheck
259
+ ```
260
+
261
+ ## Development
262
+
263
+ This repository uses `uv` for reproducible development environments:
264
+
265
+ ```bash
266
+ uv sync --all-extras --dev
267
+ uv run ruff check .
268
+ uv run ruff format --check .
269
+ uv run mypy src tests
270
+ uv run pytest --cov=contribcheck --cov-report=term-missing
271
+ ```
272
+
273
+ Tests use a mocked GitHub transport and do not consume API quota.
274
+
275
+ ## Contributing
276
+
277
+ Contributions are welcome. Start with the [good first issues](https://github.com/gokul-debugger/contribcheck/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) or browse tasks marked [help wanted](https://github.com/gokul-debugger/contribcheck/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22).
278
+
279
+ Read [CONTRIBUTING.md](https://github.com/gokul-debugger/contribcheck/blob/main/CONTRIBUTING.md), comment with a short implementation plan, and wait for confirmation before starting work that changes a public contract.
280
+
281
+ ## Current Limitations
282
+
283
+ - Comment-claim detection is conservative text matching, not proof of ownership.
284
+ - Competing PR detection can miss work that never references the issue.
285
+ - Maintainer responsiveness is measured only on the inspected issue in this release.
286
+ - Explicit base-branch detection depends on recognizable wording in the issue body.
287
+ - Private repositories require a token with appropriate read access.
288
+ - GitHub remains the source of truth; always review linked evidence before acting.
289
+
290
+ ## Roadmap
291
+
292
+ - Repository-wide maintainer response statistics
293
+ - Local clone and development-environment readiness checks
294
+ - GitHub App checks embedded directly in issue conversations
295
+ - Browser extension for one-click inspection
296
+ - Configurable organization policies and output formats
297
+
298
+ ## License
299
+
300
+ MIT
@@ -0,0 +1,268 @@
1
+ # ContribCheck: GitHub Issue Readiness Checker
2
+
3
+ An evidence-based CLI and API that checks whether a GitHub issue is genuinely ready for an open-source contribution.
4
+
5
+ [![CI](https://github.com/gokul-debugger/contribcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/gokul-debugger/contribcheck/actions/workflows/ci.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/contribcheck?logo=pypi&logoColor=white)](https://pypi.org/project/contribcheck/)
7
+ [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
8
+ [![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/gokul-debugger/contribcheck/blob/main/LICENSE)
10
+
11
+ ContribCheck identifies blockers that issue-discovery lists often miss: dependency issues, missing base branches, existing assignments, comment claims, competing pull requests, unhealthy default-branch CI, and missing contribution guidance.
12
+
13
+ It does not predict whether a maintainer will merge a pull request. Every result is linked to observable GitHub state, and signals that cannot be verified are reported as `unknown` instead of silently passing.
14
+
15
+ ## Real-World Example
16
+
17
+ Two open issues from the same repository can look equally available while having very different readiness states.
18
+
19
+ ### Blocked by a prerequisite
20
+
21
+ ```bash
22
+ contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/986 \
23
+ --actor gokul-debugger
24
+ ```
25
+
26
+ ```text
27
+ Lyrics models
28
+ https://github.com/sigma67/ytmusicapi/issues/986
29
+ Verdict: BLOCKED
30
+
31
+ FAILURE Dependencies Blocked by 1 open issue(s).
32
+ FAILURE Base branch Required branch `ytmusicapi-2` does not exist.
33
+ PASS Assignment Assigned to the requested contributor.
34
+ PASS Competing PRs No open pull request referencing this issue was found.
35
+
36
+ Next actions
37
+ - Wait for the listed dependency issues to close.
38
+ - Ask the maintainer to create or clarify the required base branch.
39
+ - Read the repository contribution guide before creating a branch.
40
+ ```
41
+
42
+ ContribCheck prevents work from starting too early: the contributor is assigned, but the required dependency and base branch are not ready.
43
+
44
+ ### Ready for contribution
45
+
46
+ ```bash
47
+ contribcheck inspect https://github.com/sigma67/ytmusicapi/issues/941
48
+ ```
49
+
50
+ ```text
51
+ get_song() can return stale likeStatus right after rate_song()
52
+ https://github.com/sigma67/ytmusicapi/issues/941
53
+ Verdict: READY
54
+
55
+ PASS Dependencies No open blockers reported.
56
+ PASS Assignment The issue is unassigned.
57
+ PASS Comment claims No other contributor appears to have claimed it.
58
+ PASS Competing PRs No open pull request referencing this issue was found.
59
+ PASS Default branch CI Latest runs for 4 workflow(s) are green.
60
+ PASS Maintainer response A maintainer first replied after approximately 8 hours.
61
+
62
+ Next actions
63
+ - Read the repository contribution guide before creating a branch.
64
+ - Comment with a concise implementation plan before starting work.
65
+ ```
66
+
67
+ Here the evidence supports beginning the contribution workflow, while still recommending coordination with the maintainer.
68
+
69
+ ## Why It Exists
70
+
71
+ Labels such as `good first issue` and `help wanted` are useful discovery signals, but they do not guarantee that an issue is actionable. A contribution can still be blocked by another issue, depend on a branch that has not been created, overlap an existing pull request, or wait in a repository whose default CI is already failing.
72
+
73
+ ContribCheck performs that second-stage verification before a contributor invests hours in setup and implementation.
74
+
75
+ ## Checks
76
+
77
+ | Check | Evidence | Effect |
78
+ |---|---|---|
79
+ | Issue state | GitHub issue state | Closed issues block work |
80
+ | Dependencies | GitHub issue dependency API | Open dependencies block work |
81
+ | Base branch | Explicit branch named in the issue body | A missing required branch blocks work |
82
+ | Assignment | Current assignees | Another assignee blocks uncoordinated work |
83
+ | Comment claims | Explicit work-claim phrases | Produces a caution |
84
+ | Competing PRs | Timeline cross-references and PR search | Produces a caution |
85
+ | Scope | Issue body and acceptance-language markers | Warns when clarification may be needed |
86
+ | Contribution guide | Repository tree | Warns when standard guidance is absent |
87
+ | Repository health | Archive status and recent push activity | Blocks archived repositories, warns on inactivity |
88
+ | Default CI | Latest completed workflow run per workflow | Warns about pre-existing failures |
89
+ | Maintainer response | Comment author association and timestamps | Reports issue-level responsiveness |
90
+
91
+ The overall result is one of:
92
+
93
+ - `ready`: no blocking, warning, or unknown signals were found
94
+ - `caution`: manual review is needed
95
+ - `blocked`: a hard prerequisite is not satisfied
96
+
97
+ ## Installation
98
+
99
+ ContribCheck requires Python 3.11 or newer.
100
+
101
+ ```bash
102
+ pipx install contribcheck
103
+ ```
104
+
105
+ Alternatively, install it into an existing Python environment with `pip install contribcheck`. The optional web service is available with `pip install "contribcheck[server]"`.
106
+
107
+ Public GitHub requests work without authentication, but GitHub applies a much smaller anonymous rate limit. Set a token for regular use:
108
+
109
+ ```bash
110
+ export GITHUB_TOKEN="your-fine-grained-token"
111
+ ```
112
+
113
+ Read-only access to public metadata is sufficient. Do not grant write permissions.
114
+
115
+ ## CLI
116
+
117
+ Inspect by URL:
118
+
119
+ ```bash
120
+ contribcheck inspect https://github.com/owner/repository/issues/123
121
+ ```
122
+
123
+ Inspect by shorthand and emit JSON:
124
+
125
+ ```bash
126
+ contribcheck inspect owner/repository#123 --actor your-username --json
127
+ ```
128
+
129
+ Use the result in CI or a script:
130
+
131
+ ```bash
132
+ contribcheck inspect owner/repository#123 --fail-on caution
133
+ ```
134
+
135
+ Exit codes are `0` for a completed inspection, `1` for an operational error, and `2` when the configured readiness threshold is reached.
136
+
137
+ Render a portable GitHub-flavored Markdown report:
138
+
139
+ ```bash
140
+ contribcheck inspect owner/repository#123 --markdown
141
+ contribcheck inspect owner/repository#123 --markdown --output report.md
142
+ ```
143
+
144
+ Markdown reports include the issue title and URL, verdict, check summaries, linked evidence, and next actions. `--markdown` and `--json` cannot be used together. Existing terminal output remains the default.
145
+
146
+ Inspect several candidates from a text file while preserving input order:
147
+
148
+ ```text
149
+ # candidates.txt
150
+ sigma67/ytmusicapi#986
151
+ https://github.com/plotly/plotly.js/issues/7750
152
+ ```
153
+
154
+ ```bash
155
+ contribcheck batch candidates.txt --actor your-username
156
+ contribcheck batch candidates.txt --json --fail-on caution
157
+ ```
158
+
159
+ Batch JSON uses a stable top-level object with `schema_version`, ordered `results`, and a `summary` containing total, success, failure, and verdict counts. Each failed item is reported independently instead of discarding successful inspections. Batch concurrency defaults to four and can be changed with `--concurrency`.
160
+
161
+ Batch exit codes are `0` when processing completes without reaching the configured threshold, `1` when input or processing fails for at least one item, and `2` when a successful report reaches the configured `--fail-on` threshold.
162
+
163
+ ### GitHub Enterprise Server
164
+
165
+ Set the API endpoint with `GITHUB_API_URL`, or override it for one command with `--base-url`:
166
+
167
+ ```bash
168
+ export GITHUB_API_URL="https://github.example.com/api/v3"
169
+ contribcheck inspect https://github.example.com/team/project/issues/123
170
+ contribcheck inspect team/project#123 --base-url https://github.example.com/api/v3
171
+ ```
172
+
173
+ The precedence is CLI option, `GITHUB_API_URL`, then `https://api.github.com`. The endpoint must be HTTP or HTTPS and cannot contain credentials, query parameters, or fragments. Tokens are sent only to the configured API endpoint.
174
+
175
+ ## Python SDK
176
+
177
+ ```python
178
+ import asyncio
179
+
180
+ from contribcheck import GitHubClient, IssueAnalyzer
181
+
182
+
183
+ async def main() -> None:
184
+ async with GitHubClient() as client:
185
+ report = await IssueAnalyzer(client).inspect(
186
+ "https://github.com/sigma67/ytmusicapi/issues/986",
187
+ actor="gokul-debugger",
188
+ )
189
+ print(report.status)
190
+ print(report.check("dependencies").summary)
191
+
192
+
193
+ asyncio.run(main())
194
+ ```
195
+
196
+ ## HTTP API
197
+
198
+ Install server dependencies and start FastAPI:
199
+
200
+ ```bash
201
+ pip install -e '.[server]'
202
+ contribcheck serve
203
+ ```
204
+
205
+ Open `http://127.0.0.1:8000/` for the browser interface or `http://127.0.0.1:8000/docs` for the interactive API documentation. The browser interface sends only the issue reference and optional actor to the local API. It does not accept, store, or log GitHub tokens.
206
+
207
+ ![ContribCheck web interface](https://raw.githubusercontent.com/gokul-debugger/contribcheck/main/docs/contribcheck-ui.png)
208
+
209
+ Call the API directly:
210
+
211
+ ```bash
212
+ curl -X POST http://127.0.0.1:8000/v1/inspect \
213
+ -H 'Content-Type: application/json' \
214
+ -d '{
215
+ "url": "https://github.com/sigma67/ytmusicapi/issues/986",
216
+ "actor": "gokul-debugger"
217
+ }'
218
+ ```
219
+
220
+ The service accepts an optional `Authorization: Bearer ...` header. It never stores the token.
221
+
222
+ ## Docker
223
+
224
+ ```bash
225
+ docker build -t contribcheck .
226
+ docker run --rm -p 8000:8000 -e GITHUB_TOKEN contribcheck
227
+ ```
228
+
229
+ ## Development
230
+
231
+ This repository uses `uv` for reproducible development environments:
232
+
233
+ ```bash
234
+ uv sync --all-extras --dev
235
+ uv run ruff check .
236
+ uv run ruff format --check .
237
+ uv run mypy src tests
238
+ uv run pytest --cov=contribcheck --cov-report=term-missing
239
+ ```
240
+
241
+ Tests use a mocked GitHub transport and do not consume API quota.
242
+
243
+ ## Contributing
244
+
245
+ Contributions are welcome. Start with the [good first issues](https://github.com/gokul-debugger/contribcheck/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) or browse tasks marked [help wanted](https://github.com/gokul-debugger/contribcheck/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22).
246
+
247
+ Read [CONTRIBUTING.md](https://github.com/gokul-debugger/contribcheck/blob/main/CONTRIBUTING.md), comment with a short implementation plan, and wait for confirmation before starting work that changes a public contract.
248
+
249
+ ## Current Limitations
250
+
251
+ - Comment-claim detection is conservative text matching, not proof of ownership.
252
+ - Competing PR detection can miss work that never references the issue.
253
+ - Maintainer responsiveness is measured only on the inspected issue in this release.
254
+ - Explicit base-branch detection depends on recognizable wording in the issue body.
255
+ - Private repositories require a token with appropriate read access.
256
+ - GitHub remains the source of truth; always review linked evidence before acting.
257
+
258
+ ## Roadmap
259
+
260
+ - Repository-wide maintainer response statistics
261
+ - Local clone and development-environment readiness checks
262
+ - GitHub App checks embedded directly in issue conversations
263
+ - Browser extension for one-click inspection
264
+ - Configurable organization policies and output formats
265
+
266
+ ## License
267
+
268
+ MIT
@@ -0,0 +1,31 @@
1
+ # Release Process
2
+
3
+ ContribCheck publishes signed distributions to PyPI through GitHub Trusted Publishing. No PyPI password or long-lived API token is stored in the repository.
4
+
5
+ ## One-time PyPI configuration
6
+
7
+ Create a pending Trusted Publisher on PyPI with these exact values:
8
+
9
+ | Field | Value |
10
+ |---|---|
11
+ | PyPI project name | `contribcheck` |
12
+ | GitHub owner | `gokul-debugger` |
13
+ | Repository | `contribcheck` |
14
+ | Workflow | `publish.yml` |
15
+ | Environment | `pypi` |
16
+
17
+ Create a GitHub environment named `pypi`. Add required-reviewer protection before publishing if the repository plan supports it.
18
+
19
+ ## Release checklist
20
+
21
+ 1. Confirm `main` is clean and CI is passing.
22
+ 2. Set the same release version in `pyproject.toml` and `src/contribcheck/__init__.py`.
23
+ 3. Update `uv.lock` when the project version or dependencies change.
24
+ 4. Run the full local quality suite.
25
+ 5. Build both distributions and inspect their contents.
26
+ 6. Create an annotated `vX.Y.Z` tag from the intended commit.
27
+ 7. Publish a GitHub release for that tag.
28
+ 8. Wait for the `Publish to PyPI` workflow to finish.
29
+ 9. Verify installation in a clean environment with `pipx install contribcheck`.
30
+
31
+ The workflow refuses to publish when the release tag and package metadata versions differ. PyPI does not permit replacing an uploaded version, so publish only from a reviewed commit.