fix(activity): viewer-form GraphQL + token-scope guidance

[bit-incarnas]

Summary

• Switch contributionsCollection queries from user(login: ...) to viewer { ... }. The user form is treated as a third-party query and silently drops granular private-repo data even with the public-profile toggle on; viewer returns the authenticated user's complete contribution graph.
• Document and surface in-app the token-scope requirement that the viewer-form fix exposes: viewer.contributionsCollection only returns contributions to repos the token can see, so a fine-grained PAT scoped to "Only select repositories" silently drops every commit / PR / issue / review on unscoped repos and produces 0 day files. README Setup now splits fine-grained vs classic guidance, and the settings tab shows a callout above the Activity window control.

Test plan

• Existing unit tests pass (npm test); GraphQL + activity-writer tests updated for the new shape.
• npm run typecheck clean.
• Manually verified: classic PAT with read:user + repo produces non-zero day files for the activity sync (Cap, 2026-04-30).
• Optional: re-test with a fine-grained PAT scoped to "All repositories" to confirm that path also works end-to-end.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a038f3e2-43a4-49e5-9d04-5c1e9ed0a755

📥 Commits

Reviewing files that changed from the base of the PR and between 54092fa and 7d89c75.

📒 Files selected for processing (3)

• README.md
• src/github/graphql.ts
• src/settings/settings-tab.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/github/graphql.ts
• README.md

📜 Recent review details

🔇 Additional comments (1)

src/settings/settings-tab.ts (1)

113-119: Clear and actionable token-scope callout.

Nice addition—this explains the silent-omission behavior and gives concrete PAT configuration guidance right where users set activity sync.

---

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated setup instructions with clearer Personal Access Token scope requirements for both fine-grained and classic tokens
  • Added in-app clarification about how token scope affects contribution visibility

• Bug Fixes

  • Enhanced error handling to display descriptive messages instead of silently returning incomplete results during data retrieval

Walkthrough

Documentation and error handling improvements clarifying GitHub token scope requirements and their effects on contribution visibility. The code now throws descriptive errors when viewer data is missing during GraphQL pagination instead of silently breaking. UI and setup documentation updated to explain token scope limitations.

Changes

Cohort / File(s)	Summary
Documentation README.md	Updated Setup section with explicit fine-grained and classic PAT scope requirements, including guidance on repository access filtering and visibility of viewer.contributionsCollection.
GraphQL Pagination src/github/graphql.ts	Modified pull request, issue, and review paginators to throw descriptive errors when data.viewer is missing instead of silently breaking and returning partial results.
Settings UI src/settings/settings-tab.ts	Added Activity settings note documenting how token scope affects repository contribution filtering and clarifying that restricted fine-grained PATs may silently omit activity.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• [github-data] fix: switch contributions queries from user(login) to viewer form #24: Directly modifies the same pagination cursor logic in src/github/graphql.ts for handling data.viewer in contributions fetching.
• feat(sync): activity aggregator -- daily rollup from contributionsCol… #18: Adds the contributions-fetching and pagination helpers that interact with the viewer-handling logic being modified here.

Poem

🐰 A hop through token scopes so fine,
Where viewer data starts to shine,
No silent breaks, just errors clear,
The docs now guide us, never fear!
Contributions visible, no more mystery—
This PAT update writes a victory! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: fixing the activity feature by switching to viewer-form GraphQL and adding token-scope guidance.
Description check	✅ Passed	The description is directly related to the changeset, explaining the switch from user(login:...) to viewer queries and documenting token-scope requirements across README, settings UI, and GraphQL changes.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 fix/activity-viewer-form

---

_{Review rate limit: 2/5 reviews remaining, refill in 24 minutes and 56 seconds.}

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 43-53: Update the README section titled "Pick a token type" to
stop calling activity scope "allowlist-based" and instead clarify that "Sync
activity" returns contributions only from repositories visible to the token;
specifically, revise the phrasing in the "Fine-grained PAT (recommended for
repo-scoped syncs)" and "Classic PAT (simplest path for `Sync activity`)"
bullets to say "all repos visible to the token" vs "narrower token scope" (and
remove language implying the plugin is filtered by a separate allowlist), ensure
the sentence “Repository access matters for `Sync activity`” explicitly explains
that setting Repository access to "Only select repositories" limits
contributions to repos the token can see, and update any mention of "allowlisted
repos" to "repos visible to the token" to avoid implying a separate allowlist
filters syncs.

In `@src/github/graphql.ts`:
- Around line 449-455: The paginated fetch code in fetchContributionsCollection
uses "if (!data.viewer) break" which silently truncates results; instead, detect
a null viewer from the client.graphql call and surface the failure the same way
the main query branch does (e.g., log an error and throw or return an explicit
error) so partial results aren't returned silently; update the blocks around the
client.graphql<PaginatePullRequestsResponse>(...) call (and the analogous blocks
for the other paginated queries) to check for data.viewer and handle it by
emitting a consistent error (or throwing) rather than breaking out of the loop.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fdfd152e-f996-4fdb-ae8c-bda76bc55e8a

📥 Commits

Reviewing files that changed from the base of the PR and between 47b3cc0 and c573dc6.

📒 Files selected for processing (9)

• README.md
• manifest.json
• package.json
• src/github/graphql.test.ts
• src/github/graphql.ts
• src/settings/settings-tab.ts
• src/sync/activity-writer.test.ts
• src/sync/activity-writer.ts
• versions.json

📜 Review details

🔇 Additional comments (4)

src/github/graphql.test.ts (4)

35-66: mainResponse fixture is correctly aligned to the new GraphQL shape.

Switching the mock root to viewer.contributionsCollection is consistent with the production query contract and keeps downstream test data coherent.

---

112-132: Variable and query-shape assertions are solid here.

This test now correctly locks in both migration guarantees: no login variable and viewer-based query text.

---

134-143: Failure-path expectation update looks correct.

The new rejection assertion matches the updated behavior when viewer contributions are missing.

---

210-218: Pagination mocks were updated consistently across all connection branches.

Using viewer in all paginated mock payloads avoids shape drift and keeps pagination tests representative of runtime responses.

Also applies to: 248-256, 260-268, 272-280, 328-336

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 43-54: The settings UI copy in src/settings/settings-tab.ts
currently instructs users to create only fine-grained PATs; update the
token-field help text (the string/constant used by the SettingsTab component or
the function renderTokenHelp / tokenHelpText) to match the README: explain that
both fine-grained and classic PATs are supported, include both links
(github.com/settings/personal-access-tokens and github.com/settings/tokens),
list the recommended read-only scopes for fine-grained PATs (Contents: read,
Issues: read, Pull requests: read, Metadata: read, Dependabot alerts: read,
Actions: read) and note that classic PATs should include read:user (and repo
only if private contributions need counting). Ensure the copy also preserves the
Repository access note about "Only select repositories" vs "All repositories"
for Sync activity.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5d5a61ac-f43e-473a-966f-e11c780e1ef8

📥 Commits

Reviewing files that changed from the base of the PR and between c573dc6 and 54092fa.

📒 Files selected for processing (2)

• README.md
• src/github/graphql.ts

📜 Review details

🔇 Additional comments (1)

src/github/graphql.ts (1)

369-375: Good hardening on null-viewer handling in both main and paginated paths.

The new throw behavior prevents silent partial activity results and aligns failure surfacing across all contribution fetch branches.

Also applies to: 453-458, 487-493, 521-528