Adopt the canonical pm-ops docstring gate by unbraind · Pull Request #30 · unbraind/pm-github

unbraind · 2026-08-09T06:26:24Z

Summary

Adopts the canonical pm-ops docstring coverage analyzer as the single fleet-wide docstring gate, mirroring the pm-linear adoption (pm-linear#58). The analyzer is never vendored, copied, or reimplemented — this is adoption only (pm-ops devDependency + a thin launcher over analyzeDocstringCoverage).

Changes

pm-ops ^2026.8.8 added as a devDependency — the exact pin pm-linear uses.
scripts/docstring-gate.ts — a self-contained launcher over pm-ops/docstrings analyzeDocstringCoverage, exposing a pure runGate + thin main + isMainInvocation guard. It intentionally matches this repo's existing scripts/coverage-gate.ts style (no shared launcher helper module introduced), rather than copying pm-linear's script-launcher.ts abstraction.
test/docstring-gate.test.ts — behavioral coverage of the clean path, the violation path, main()'s stream/exit wiring, and the main-invocation guard.
package.json — "docstring": "node scripts/docstring-gate.ts", inserted into release:check immediately before the coverage step.
.github/workflows/ci.yml — a Verify complete docstring coverage step added after Build, before the coverage step. No existing CI job or step is renamed.
Real JSDoc written for every flagged declaration: 72 → 0 violations (62 in index.ts, 10 in projects.ts); 85 declarations documented across 4 files.

Verification

Full npm run release:check is green end to end:

typecheck ✓
build ✓
docstring → 4 file(s), 85 declaration(s) documented. (0 violations) ✓
coverage → thresholds met (88/79/89) ✓
audit:prod ✓
pack:dry-run ✓
changelog:check ✓

pm

pm-github-pbxd

FORBIDDEN compliance

No PR merged, no review-bot triggers posted, nothing pushed to unbraind/pm-cli, the analyzer is not vendored, and no AI attribution is present in the commit.

Summary by Sourcery

Adopt a shared docstring coverage gate and wire it into local scripts and CI while fully documenting the GitHub integration surfaces.

New Features:

Add a docstring gate script backed by the canonical pm-ops analyzer and expose it via an npm script used in the release check pipeline.

Enhancements:

Document existing GitHub integration types, helpers, and project-sync utilities with comprehensive JSDoc to reach complete docstring coverage.

CI:

Add a CI step that runs the docstring coverage gate after build and before the coverage gate.

Documentation:

Bring previously undocumented GitHub issue, import, locking, dependency-linking, export, search, validate, and project-sync APIs up to full JSDoc coverage.

Tests:

Add behavioral tests for the docstring gate launcher, covering success, violation handling, stream wiring, and main-invocation detection.

Chores:

Record the pm task history for this change in the pm workspace metadata.

Summary by cubic

Adopted the canonical pm-ops docstring coverage gate and wired it into CI to enforce real JSDoc across the repo. Fixed all violations (72 → 0) and hardened the launcher to fail closed on self-resolution errors.

New Features
- Added pm-ops ^2026.8.8 devDependency and a thin scripts/docstring-gate.ts launcher (runGate/main/isMainInvocation).
- Added test/docstring-gate.test.ts.
- Added npm script docstring; inserted into release:check and added a CI step “Verify complete docstring coverage” after Build.
- Wrote JSDoc for all flagged declarations; violations reduced 72 → 0 across 4 files.
- Adoption only; analyzer is not vendored or copied.
Bug Fixes
- Clarified GateResult docs (newline-free strings) and ensured main() writes newline-terminated stderr.
- isMainInvocation now throws when this module’s own path cannot be resolved, preventing the mandatory gate from skipping its scan and exiting zero; added regression tests.

^{Written for commit 7ec5dcd. Summary will update on new commits.}

Adopt pm-ops/docstrings (analyzeDocstringCoverage) as the single fleet-wide docstring policy behind a thin launcher, mirroring the pm-linear adoption (pm-linear#58). - Add pm-ops ^2026.8.8 as a devDependency (the exact pin pm-linear uses). - Add scripts/docstring-gate.ts: a self-contained launcher over analyzeDocstringCoverage (runGate / main / isMainInvocation), matching this repo's existing coverage-gate.ts style rather than introducing a shared launcher helper module. - Add test/docstring-gate.test.ts covering the clean path, the violation path, main()'s stream/exit wiring, and the main-invocation guard. - Wire `npm run docstring` into release:check (immediately before coverage) and add a "Verify complete docstring coverage" CI step after build, before the coverage step. No existing CI job or step is renamed. - Write real JSDoc for every flagged declaration: 72 violations (62 in index.ts, 10 in projects.ts) reduced to 0 — 85 declarations documented across 4 files. The analyzer is never vendored, copied, or reimplemented; this is adoption only. pm: pm-github-pbxd

sourcery-ai

Sorry @unbraind, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

coderabbitai · 2026-08-09T06:26:43Z

Warning

Review limit reached

@unbraind, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4736424a-050a-4ae3-b6e6-b1e105253813

📥 Commits

Reviewing files that changed from the base of the PR and between a6cf220 and 7ec5dcd.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (11)

.agents/pm/history/pm-github-pbxd.jsonl
.agents/pm/history/pm-github-wxob.jsonl
.agents/pm/issues/pm-github-wxob.toon
.agents/pm/tasks/pm-github-pbxd.toon
.github/workflows/ci.yml
CHANGELOG.md
index.ts
package.json
projects.ts
scripts/docstring-gate.ts
test/docstring-gate.test.ts

Summary by CodeRabbit

New Features
- Added support for identifying draft pull requests during issue filtering.
Documentation
- Expanded documentation for GitHub issue workflows, search, validation, and Projects.
Quality Improvements
- Added automated documentation coverage validation with complete coverage across checked declarations.
- Improved validation behavior when the gate cannot resolve its own module path.
Tests
- Added coverage for successful, failing, and edge-case documentation validation scenarios.
CI
- Integrated documentation coverage checks into continuous integration and release validation.

Walkthrough

The pull request adds a pm-ops docstring coverage gate, integrates it into CI and release checks, adds behavioral tests, and documents exported APIs across GitHub operations and Projects v2 workflows.

Changes

Docstring coverage gate

Layer / File(s)	Summary
Gate implementation and tests `scripts/docstring-gate.ts`, `test/docstring-gate.test.ts`	Adds coverage analysis, result handling, direct-execution detection, exit handling, and success or violation tests.
CI, release, changelog, and task integration `package.json`, `.github/workflows/ci.yml`, `CHANGELOG.md`, `.agents/pm/tasks/pm-github-pbxd.toon`, `.agents/pm/history/*`	Adds the validation script, `pm-ops` dependency, CI and release-check execution, changelog entries, and completed PM records.
Import and GitHub operation documentation `index.ts`	Documents issue data, import options, HTTP behavior, locks, comments, dependencies, exports, search, validation, and draft filtering.
Projects v2 and lifecycle documentation `index.ts`, `projects.ts`	Documents project references, status mapping, pagination, synchronization, push plans, lifecycle rendering, and command behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant main
  participant runGate
  participant analyzeDocstringCoverage
  CI->>main: run npm run docstring
  main->>runGate: analyze repository
  runGate->>analyzeDocstringCoverage: check docstring coverage
  analyzeDocstringCoverage-->>runGate: violations or documented count
  runGate-->>main: return GateResult
  main-->>CI: write output and set exit code

Possibly related PRs

unbraind/pm-github#28: Shares Projects v2 and draft-related APIs documented by this pull request.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adopting the canonical pm-ops docstring gate.
Description check	✅ Passed	The description directly explains the docstring gate adoption, implementation, tests, CI integration, and verification results.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docstring-gate-adoption

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

sourcery-ai · 2026-08-09T06:26:45Z

Reviewer's Guide

Adopts the canonical pm-ops docstring coverage analyzer as a fleet-wide docstring gate for this repo, wiring it into npm scripts and CI via a thin launcher script, adding behavioral tests for the gate, and bringing existing source files up to full JSDoc coverage so the gate passes cleanly.

Sequence diagram for the new docstring gate execution

sequenceDiagram
  actor Developer
  participant npm as npm_script
  participant DocGate as scripts_docstring_gate_ts
  participant Ops as pm_ops_docstrings

  Developer->>npm: npm run docstring
  npm->>DocGate: node scripts/docstring-gate.ts
  DocGate->>DocGate: isMainInvocation(process.argv, import.meta.url)
  DocGate->>DocGate: main(repoRoot)
  DocGate->>Ops: analyzeDocstringCoverage({ root })
  Ops-->>DocGate: report
  alt report.violations.length > 0
    DocGate->>DocGate: runGate(root) returns GateResult(exitCode=1, stderr)
    DocGate->>Developer: write stderr, set process.exitCode=1
  else no violations
    DocGate->>DocGate: runGate(root) returns GateResult(exitCode=0, stdout)
    DocGate->>Developer: write stdout, set process.exitCode=0
  end

File-Level Changes

Change	Details	Files
Introduce a self-contained docstring gate script that wraps pm-ops/docstrings and exposes a testable run/main interface.	Add scripts/docstring-gate.ts implementing runGate(main) over analyzeDocstringCoverage with a main-invocation guard. runGate computes success/violation output from the pm-ops report without touching process streams, returning exitCode/stdout/stderr. main writes newline-terminated stdout/stderr and sets process.exitCode instead of exiting directly. isMainInvocation compares realpath-resolved argv[1] to module URL to decide whether to run main on direct invocation.	`scripts/docstring-gate.ts`
Add behavioral tests to validate the docstring gate wiring and CLI behavior.	Test that runGate succeeds on the real repository and prints a summary line to stdout with no stderr. Test that runGate reports violations and non-zero exitCode for a synthetic undocumented source tree. Test that main writes violation output to stderr, leaves stdout empty, and sets process.exitCode=1 for failing roots. Test that isMainInvocation correctly distinguishes matching/non-matching argv scripts and missing argv[1]. Test that main on the real repository writes a success line to stdout (with newline) and exits with code 0.	`test/docstring-gate.test.ts`
Wire the docstring gate into npm scripts, devDependencies, and CI so it runs as part of release checks.	Add pm-ops ^2026.8.8 as a devDependency, matching the canonical pin. Introduce an npm script "docstring" that runs node scripts/docstring-gate.ts. Update release:check to run the docstring script between build and coverage. Add a "Verify complete docstring coverage" step to the CI workflow between Build and coverage. Update package-lock.json accordingly (dependency graph changes).	`package.json` `.github/workflows/ci.yml` `package-lock.json`
Add comprehensive JSDoc docstrings to existing TypeScript types and functions so the new gate reports zero violations.	Document GhIssue fields and semantics, including PR/draft handling and provenance-related usage. Document ImportOptions, AtomicImportOptions, RateLimitInfo, PmItem, and various helper functions (sameOrigin, computeBackoffMs, etc.) in index.ts. Add detailed JSDoc for locking, comment-sync, import/export, search, validate, and projects-related helpers within index.ts. Document ProjectRef, ProjectMeta, status mapping helpers, indexing helpers, and push plan types in projects.ts. Ensure all previously flagged declarations in index.ts and projects.ts have meaningful JSDoc so the analyzer passes (72→0 violations).	`index.ts` `projects.ts`
Record pm task/provenance metadata for the pm-github-pbxd task within the agents directory.	Add pm history JSONL entry for pm-github-pbxd under .agents/pm/history. Add corresponding pm task definition pm-github-pbxd.toon under .agents/pm/tasks.	`.agents/pm/history/pm-github-pbxd.jsonl` `.agents/pm/tasks/pm-github-pbxd.toon`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

greptile-apps · 2026-08-09T06:28:30Z

Greptile Summary

The PR adopts the canonical pm-ops docstring analyzer and documents the existing GitHub integration surfaces.

Adds a thin docstring-gate launcher with behavioral tests.
Runs the gate in CI and the release-check pipeline.
Adds JSDoc across the root GitHub and Projects implementation files.
Records the associated pm task, fix history, and changelog entries.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/docstring-gate.ts	Adds the `pm-ops` analyzer launcher, stream and exit-code wiring, and a fail-closed direct-invocation guard.
test/docstring-gate.test.ts	Covers successful and failing scans, CLI output wiring, invocation detection, and the self-resolution regression.
package.json	Adds the locked `pm-ops`-backed docstring command and inserts it into the release-check sequence.
.github/workflows/ci.yml	Runs the docstring gate after compilation and before the coverage gate.
index.ts	Adds JSDoc to existing GitHub issue integration declarations without changing executable behavior.
projects.ts	Adds JSDoc to existing Projects V2 declarations without changing executable behavior.

_{Reviews (5): Last reviewed commit: "fix(docstring-gate): fail closed when th..." | Re-trigger Greptile}

`runGate` returns newline-free strings on purpose, so a test can compare whole strings without a trailing newline getting in the way; `main` appends the newline as it writes each non-empty stream. The docstring said the opposite — that the struct holds "the exact stdout/stderr bytes the CLI emits" — which is the one detail a caller would get wrong. Raised by CodeRabbit on pm-jira#56. The same wording came from the shared reference implementation, so it is corrected here in every repository adopting the gate in this round rather than in one.

unbraind · 2026-08-09T06:49:39Z

@coderabbitai full review

@greptileai review

coderabbitai · 2026-08-09T06:49:47Z

@unbraind I will perform a complete review of PR #30.

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 36 minutes.

main appends the newline so the next release:check step starts on its own line rather than butting against this gate's output, but the failure-path test accepted output without it. Raised by CodeRabbit on pm-beads#63; applied across this round's repositories rather than one, since they share the test.

unbraind · 2026-08-09T06:59:48Z

@coderabbitai full review

@greptileai review

coderabbitai · 2026-08-09T06:59:58Z

@unbraind I will perform a complete review of PR #30.

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 26 minutes.

unbraind · 2026-08-09T07:42:26Z

@coderabbitai full review

coderabbitai · 2026-08-09T07:42:34Z

✅ Action performed

Full review finished.

unbraind · 2026-08-09T07:52:34Z

@coderabbitai full review

coderabbitai · 2026-08-09T07:52:44Z

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 49 minutes.

unbraind · 2026-08-09T07:54:34Z

@coderabbitai full review

coderabbitai · 2026-08-09T07:54:42Z

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 47 minutes.

unbraind · 2026-08-09T09:10:09Z

@coderabbitai full review

coderabbitai · 2026-08-09T09:10:14Z

✅ Action performed

Full review finished.

unbraind · 2026-08-09T10:36:34Z

@coderabbitai full review

coderabbitai · 2026-08-09T10:36:41Z

✅ Action performed

Full review finished.

unbraind · 2026-08-09T11:52:37Z

@coderabbitai full review

coderabbitai · 2026-08-09T11:52:44Z

✅ Action performed

Full review finished.

… path isMainInvocation resolved this module's own path inside a try block that swallowed every failure and returned false. Returning false leaves main() unreached and process.exitCode at zero, so a release could pass the mandatory docstring gate having scanned nothing - the silent no-op the docstring itself called worse than throwing. The two resolutions fail for opposite reasons and are now treated differently: an unresolvable argv[1] still answers false, because that is the ordinary imported-by-a-test case, while an unresolvable own module path throws. Adds a regression test for the throw, plus one for the unresolvable-argv[1] case, and asserts the newline-free GateResult contract that the violation test previously accepted a trailing newline against. The throw test was mutation-checked: reverting the split resolution makes it fail.

unbraind · 2026-08-09T13:39:01Z

@coderabbitai full review
@greptileai
/gemini review

coderabbitai · 2026-08-09T13:39:11Z

@unbraind I will perform a complete review of PR #30.

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 29 minutes.

sourcery-ai Bot reviewed Aug 9, 2026

View reviewed changes

unbraind merged commit a3a65ea into main Aug 9, 2026
7 checks passed

unbraind deleted the docstring-gate-adoption branch August 9, 2026 13:55

coderabbitai Bot mentioned this pull request Aug 10, 2026

Propagate the docstring gate entry guard fix so an unresolvable entry cannot pass the gate #32

Merged

Conversation

unbraind commented Aug 9, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Verification

pm

FORBIDDEN compliance

Summary by Sourcery

Summary by cubic

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Summary by CodeRabbit

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

sourcery-ai Bot commented Aug 9, 2026

Reviewer's Guide

Sequence diagram for the new docstring gate execution

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

greptile-apps Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unbraind commented Aug 9, 2026

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

unbraind commented Aug 9, 2026 •

edited by cubic-dev-ai Bot

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

greptile-apps Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading