@deepseek-ai/dsh-experimental-forge-github 0.2.2-alpha.3 → 0.2.2-rc.2

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.
Files changed (59) hide show
  1. package/README.i18n.yaml +6 -6
  2. package/README.md +27 -6
  3. package/README.zh.md +27 -6
  4. package/lib/index.js +1860 -112
  5. package/lib/types/commits.d.ts +24 -0
  6. package/lib/types/commits.d.ts.map +1 -0
  7. package/lib/types/commits.js.map +1 -0
  8. package/lib/types/compare.d.ts +23 -0
  9. package/lib/types/compare.d.ts.map +1 -0
  10. package/lib/types/compare.js.map +1 -0
  11. package/lib/types/gh.d.ts.map +1 -0
  12. package/lib/types/gh.js.map +1 -0
  13. package/lib/types/graphql.d.ts +66 -10
  14. package/lib/types/graphql.d.ts.map +1 -0
  15. package/lib/types/graphql.js.map +1 -0
  16. package/lib/types/index.d.ts +10 -1
  17. package/lib/types/index.d.ts.map +1 -0
  18. package/lib/types/index.js.map +1 -0
  19. package/lib/types/mutation.d.ts +40 -0
  20. package/lib/types/mutation.d.ts.map +1 -0
  21. package/lib/types/mutation.js.map +1 -0
  22. package/lib/types/overview.d.ts +51 -0
  23. package/lib/types/overview.d.ts.map +1 -0
  24. package/lib/types/overview.js.map +1 -0
  25. package/lib/types/provider.d.ts +71 -6
  26. package/lib/types/provider.d.ts.map +1 -0
  27. package/lib/types/provider.js.map +1 -0
  28. package/lib/types/pull-request-node.d.ts +15 -0
  29. package/lib/types/pull-request-node.d.ts.map +1 -0
  30. package/lib/types/pull-request-node.js.map +1 -0
  31. package/lib/types/review-writes.d.ts +44 -0
  32. package/lib/types/review-writes.d.ts.map +1 -0
  33. package/lib/types/review-writes.js.map +1 -0
  34. package/lib/types/review.d.ts.map +1 -0
  35. package/lib/types/review.js.map +1 -0
  36. package/lib/types/threads.d.ts +37 -0
  37. package/lib/types/threads.d.ts.map +1 -0
  38. package/lib/types/threads.js.map +1 -0
  39. package/lib/types/urls.d.ts +6 -0
  40. package/lib/types/urls.d.ts.map +1 -0
  41. package/lib/types/urls.js.map +1 -0
  42. package/lib/types/viewed.d.ts +37 -0
  43. package/lib/types/viewed.d.ts.map +1 -0
  44. package/lib/types/viewed.js.map +1 -0
  45. package/package.json +16 -12
  46. package/src/commits.ts +102 -0
  47. package/src/compare.ts +43 -0
  48. package/src/gh.ts +71 -0
  49. package/src/graphql.ts +685 -0
  50. package/src/index.ts +60 -0
  51. package/src/mutation.ts +86 -0
  52. package/src/overview.ts +197 -0
  53. package/src/provider.ts +534 -0
  54. package/src/pull-request-node.ts +42 -0
  55. package/src/review-writes.ts +192 -0
  56. package/src/review.ts +59 -0
  57. package/src/threads.ts +262 -0
  58. package/src/urls.ts +89 -0
  59. package/src/viewed.ts +132 -0
package/src/viewed.ts ADDED
@@ -0,0 +1,132 @@
1
+ /** The signed-in user's viewed marks on pull request files through GraphQL, pinned to one head commit. */
2
+
3
+ import type {
4
+ ChangeRequestRef, ForgeActionFailure, ForgeFailure, ForgeViewedFiles, ForgeViewedRequest, ForgeViewedState,
5
+ } from '@deepseek-ai/dsh-experimental-forge'
6
+ import { pullRequestNode } from './pull-request-node.ts'
7
+ import { z } from 'zod'
8
+ import type { GraphqlReader } from './commits.ts'
9
+ import type { GraphqlWriter } from './mutation.ts'
10
+ import { checkedRepository, isCommit } from './urls.ts'
11
+
12
+ /** Files GitHub returns per GraphQL page, its connection maximum. */
13
+ const PAGE = 100
14
+
15
+ /** One page of a pull request's files with the viewer's marks and its head; `cursor` continues after the previous page. */
16
+ export const VIEWED_QUERY = `query($owner: String!, $name: String!, $number: Int!, $first: Int!, $cursor: String) {
17
+ repository(owner: $owner, name: $name) {
18
+ pullRequest(number: $number) {
19
+ headRefOid
20
+ files(first: $first, after: $cursor) { totalCount pageInfo { hasNextPage endCursor } nodes { path viewerViewedState } }
21
+ }
22
+ }
23
+ }`
24
+
25
+ /** Mark one file viewed; variables `id` (pull request node id) and `path`, sent on standard input. */
26
+ export const MARK_VIEWED_MUTATION = `mutation($id: ID!, $path: String!) {
27
+ markFileAsViewed(input: { pullRequestId: $id, path: $path }) { clientMutationId }
28
+ }`
29
+
30
+ /** Clear one file's viewed mark; variables `id` (pull request node id) and `path`, sent on standard input. */
31
+ export const UNMARK_VIEWED_MUTATION = `mutation($id: ID!, $path: String!) {
32
+ unmarkFileAsViewed(input: { pullRequestId: $id, path: $path }) { clientMutationId }
33
+ }`
34
+
35
+ const STATES: ReadonlyMap<string, ForgeViewedState> = new Map([['VIEWED', 'viewed'], ['UNVIEWED', 'unviewed'], ['DISMISSED', 'dismissed']])
36
+
37
+ const pageSchema = z.object({
38
+ data: z.object({
39
+ repository: z.object({
40
+ pullRequest: z.object({
41
+ headRefOid: z.string(),
42
+ files: z.object({
43
+ totalCount: z.number().int().nonnegative(),
44
+ pageInfo: z.object({ hasNextPage: z.boolean(), endCursor: z.string().nullable() }),
45
+ nodes: z.array(z.object({ path: z.string(), viewerViewedState: z.string() })),
46
+ }).nullable(),
47
+ }).nullable(),
48
+ }).nullable(),
49
+ }),
50
+ })
51
+
52
+ /**
53
+ * Read the viewer's marks on a pull request's files, at most `limit`, reading pages until the limit or the last file.
54
+ * Every page must name `headSha` as the head, so the marks never mix two pushes, and a cursor no earlier page returned,
55
+ * so the listing ends. A state GitHub adds later reads as `unviewed`.
56
+ * @param read - runs one GraphQL request.
57
+ * @param ref - pull request address.
58
+ * @param headSha - head commit the marks must be read at.
59
+ * @param limit - most files listed.
60
+ * @param signal - cancellation of every page.
61
+ * @returns the marks at `headSha`, `stale` once the head is another commit, or why GitHub did not list them.
62
+ * @throws when `headSha` is not a full commit object name.
63
+ */
64
+ export async function readViewed(
65
+ read: GraphqlReader,
66
+ ref: ChangeRequestRef,
67
+ headSha: string,
68
+ limit: number,
69
+ signal: AbortSignal,
70
+ ): Promise<ForgeViewedFiles | ForgeFailure> {
71
+ const { host, owner, name } = checkedRepository(ref)
72
+ if (!isCommit(headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(headSha)}`)
73
+ // A map keeps a path such as `__proto__`, which assignment to a plain object drops.
74
+ const files = new Map<string, ForgeViewedState>()
75
+ let listed = 0
76
+ const cursors = new Set<string>()
77
+ let cursor: string | null = null
78
+ for (;;) {
79
+ const body = await read([
80
+ 'api', 'graphql', '--hostname', host, '-f', `query=${VIEWED_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`,
81
+ '-F', `number=${ref.number}`, '-F', `first=${Math.min(PAGE, limit - listed)}`, ...cursor === null ? [] : ['-f', `cursor=${cursor}`],
82
+ ], signal)
83
+ if (!body.ok) return body.failure
84
+ const parsed = pageSchema.safeParse(body.body)
85
+ if (!parsed.success) return { code: 'unavailable', message: 'unexpected GitHub response to the viewed file read' }
86
+ const pull = parsed.data.data.repository?.pullRequest
87
+ if (pull == null) return { code: 'not-found', message: `pull request ${ref.number} was not found` }
88
+ if (pull.headRefOid.toLowerCase() !== headSha.toLowerCase()) {
89
+ return { code: 'stale', message: `the pull request head moved from ${headSha} to ${pull.headRefOid}` }
90
+ }
91
+ // GitHub answers null for the files of a pull request whose diff it cannot list.
92
+ if (pull.files === null) return { code: 'unavailable', message: 'GitHub did not list the pull request files' }
93
+ const { totalCount, pageInfo: { hasNextPage, endCursor }, nodes } = pull.files
94
+ for (const node of nodes) files.set(node.path, STATES.get(node.viewerViewedState) ?? 'unviewed')
95
+ listed += nodes.length
96
+ // `fromEntries` defines each path as an own property, `__proto__` included.
97
+ if (!hasNextPage || listed >= limit) {
98
+ return { headSha: pull.headRefOid, files: Object.fromEntries(files), truncated: totalCount > listed }
99
+ }
100
+ if (endCursor === null || cursors.has(endCursor)) return { code: 'unavailable', message: 'GitHub file pagination did not advance' }
101
+ cursors.add(endCursor)
102
+ cursor = endCursor
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Set or clear the viewer's mark on one file. GitHub's mutations take no head commit, so the pull request head is read
108
+ * first and the write is refused once it is another commit; a push between that read and the write leaves the mark on
109
+ * the file as the new head has it.
110
+ * @param read - runs one GraphQL query.
111
+ * @param write - runs one GraphQL mutation.
112
+ * @param ref - pull request address.
113
+ * @param request - the file, its mark, and the head commit the user saw.
114
+ * @param signal - cancellation of both requests.
115
+ * @returns undefined once GitHub saved the mark, `stale` when the head moved, or why GitHub refused.
116
+ * @throws when `request.headSha` is not a full commit object name.
117
+ */
118
+ export async function writeViewed(
119
+ read: GraphqlReader,
120
+ write: GraphqlWriter,
121
+ ref: ChangeRequestRef,
122
+ request: ForgeViewedRequest,
123
+ signal: AbortSignal,
124
+ ): Promise<ForgeActionFailure | undefined> {
125
+ if (!isCommit(request.headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(request.headSha)}`)
126
+ const id = await pullRequestNode(read, ref, request.headSha, signal)
127
+ if (typeof id !== 'string') return id
128
+ const variables = { id, path: request.path }
129
+ return await write(ref.repository.host, request.viewed
130
+ ? { query: MARK_VIEWED_MUTATION, field: 'markFileAsViewed', variables }
131
+ : { query: UNMARK_VIEWED_MUTATION, field: 'unmarkFileAsViewed', variables }, signal)
132
+ }