@self-review/core 1.42.0 → 1.43.1
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/dist/index.cjs +740 -18
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +235 -2
- package/dist/index.d.ts +235 -2
- package/dist/index.js +731 -19
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { DiffFile, ReviewState, ReviewComment, DiffSource, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats } from '@self-review/types';
|
|
1
|
+
import { DiffFile, ReviewState, ReviewComment, DiffSource, RemoteForge, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats } from '@self-review/types';
|
|
2
2
|
export { AppConfig, Attachment, CategoryDef, ChangeType, CommentConfidence, CommentSeverity, DiffFile, DiffHunk, DiffLine, DiffLineType, DiffLoadPayload, DiffSource, ExpandContextRequest, ExpandContextResponse, FileReviewState, FindInPageRequest, FindInPageResult, GuideFileEntry, GuideGroup, ImageLoadResult, LineRange, OutputPathInfo, PayloadStats, ResolvedGuideFile, ResolvedGuideGroup, ResumeLoadPayload, ReviewComment, ReviewGuide, ReviewState, Suggestion, VersionUpdateInfo } from '@self-review/types';
|
|
3
3
|
|
|
4
4
|
declare function parseDiff(rawDiff: string): DiffFile[];
|
|
@@ -11,6 +11,10 @@ interface ParsedReview {
|
|
|
11
11
|
viewedFiles: string[];
|
|
12
12
|
gitDiffArgs: string;
|
|
13
13
|
source: DiffSource;
|
|
14
|
+
remoteUrl?: string;
|
|
15
|
+
remoteBaseSha?: string;
|
|
16
|
+
remoteHeadSha?: string;
|
|
17
|
+
remoteForge?: RemoteForge;
|
|
14
18
|
}
|
|
15
19
|
declare function parseReviewXml(xmlPath: string): ParsedReview;
|
|
16
20
|
declare function parseReviewXmlString(xmlContent: string): ParsedReview;
|
|
@@ -78,6 +82,129 @@ declare function getUntrackedFilesAsync(cwd?: string): Promise<string[]>;
|
|
|
78
82
|
*/
|
|
79
83
|
declare function generateUntrackedDiffs(paths: string[], repoRoot: string): string;
|
|
80
84
|
|
|
85
|
+
/** Forges the app knows how to talk to. */
|
|
86
|
+
type ForgeName = 'github' | 'gitlab';
|
|
87
|
+
/**
|
|
88
|
+
* A parsed pull-request / merge-request web URL.
|
|
89
|
+
*
|
|
90
|
+
* Detection is by URL path shape only (`/pull/N` → GitHub,
|
|
91
|
+
* `/-/merge_requests/N` → GitLab) on any host, so self-hosted instances such
|
|
92
|
+
* as git.drupalcode.org work with zero configuration.
|
|
93
|
+
*/
|
|
94
|
+
interface ForgeUrl {
|
|
95
|
+
forge: ForgeName;
|
|
96
|
+
/** Host as it appears in the URL, including a port when present. */
|
|
97
|
+
host: string;
|
|
98
|
+
/**
|
|
99
|
+
* Repository owner. For GitLab this is the full namespace path and may
|
|
100
|
+
* contain slashes (subgroups, e.g. `group/subgroup`); for GitHub it is a
|
|
101
|
+
* single segment.
|
|
102
|
+
*/
|
|
103
|
+
owner: string;
|
|
104
|
+
/** Repository name (final path segment before the PR/MR marker). */
|
|
105
|
+
repo: string;
|
|
106
|
+
/** Pull-request number / merge-request IID. */
|
|
107
|
+
number: number;
|
|
108
|
+
}
|
|
109
|
+
/** Which side of the diff a thread anchor points at. */
|
|
110
|
+
type ForgeAnchorSide = 'old' | 'new';
|
|
111
|
+
/**
|
|
112
|
+
* Forge-neutral anchor of a discussion thread onto the diff.
|
|
113
|
+
*
|
|
114
|
+
* The mapper consumes this shape without forge-conditional logic:
|
|
115
|
+
* - `startLine`/`endLine` are equal for single-line anchors.
|
|
116
|
+
* - `startLine`/`endLine` are `null` when the forge supplies a file path but
|
|
117
|
+
* no usable line information (the mapper degrades to a file-level comment;
|
|
118
|
+
* `side` is meaningless in that case and providers should set `'new'`).
|
|
119
|
+
* - `outdated: true` means the forge reports the anchor no longer applies to
|
|
120
|
+
* the current head (e.g. GitHub outdated review comments); the line fields
|
|
121
|
+
* then hold the historic anchor and the mapper degrades to file-level.
|
|
122
|
+
*/
|
|
123
|
+
interface ForgeThreadAnchor {
|
|
124
|
+
filePath: string;
|
|
125
|
+
side: ForgeAnchorSide;
|
|
126
|
+
startLine: number | null;
|
|
127
|
+
endLine: number | null;
|
|
128
|
+
outdated: boolean;
|
|
129
|
+
}
|
|
130
|
+
/** One turn (root comment or reply) in a forge discussion thread. */
|
|
131
|
+
interface ForgeThreadTurn {
|
|
132
|
+
/** Forge-assigned comment/note ID, kept as a string verbatim. */
|
|
133
|
+
remoteId: string;
|
|
134
|
+
/** Forge username of the turn's author. */
|
|
135
|
+
author: string;
|
|
136
|
+
/** Markdown body, passed through verbatim. */
|
|
137
|
+
body: string;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* A normalized discussion thread: an ordered root + flat replies.
|
|
141
|
+
*
|
|
142
|
+
* The root turn owns the anchor. `anchor` is `null` for threads with no file
|
|
143
|
+
* association at all (e.g. GitLab non-diff discussions); the mapper turns
|
|
144
|
+
* those into its review-level representation. `replies` preserve the forge's
|
|
145
|
+
* document order — nothing else sorts them.
|
|
146
|
+
*/
|
|
147
|
+
interface ForgeThread {
|
|
148
|
+
root: ForgeThreadTurn;
|
|
149
|
+
replies: ForgeThreadTurn[];
|
|
150
|
+
anchor: ForgeThreadAnchor | null;
|
|
151
|
+
}
|
|
152
|
+
/** Options for {@link ForgeProvider.fetchThreads}. */
|
|
153
|
+
interface FetchThreadsOptions {
|
|
154
|
+
/**
|
|
155
|
+
* Include threads the forge marks resolved. Defaults to false where the
|
|
156
|
+
* forge tracks resolution (GitLab); providers without a comparable concept
|
|
157
|
+
* on the fetch path (GitHub REST review comments) may ignore it.
|
|
158
|
+
*/
|
|
159
|
+
includeResolved?: boolean;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Result of running a forge CLI command through {@link ForgeCommandRunner}.
|
|
163
|
+
*/
|
|
164
|
+
interface ForgeCommandResult {
|
|
165
|
+
stdout: string;
|
|
166
|
+
stderr: string;
|
|
167
|
+
exitCode: number;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Injectable command runner used by provider implementations, mirroring how
|
|
171
|
+
* `git.ts` keeps child-process execution testable. Resolves with the exit
|
|
172
|
+
* code on any completed run (including non-zero); rejects only when the
|
|
173
|
+
* binary cannot be spawned at all (e.g. ENOENT when the CLI is absent).
|
|
174
|
+
*/
|
|
175
|
+
type ForgeCommandRunner = (command: string, args: string[]) => Promise<ForgeCommandResult>;
|
|
176
|
+
/**
|
|
177
|
+
* The conversation plane of a forge. Exactly two capabilities: base-branch
|
|
178
|
+
* lookup and discussion-thread fetching. No diff fetching, no blob fetching,
|
|
179
|
+
* no posting — those concerns live elsewhere.
|
|
180
|
+
*
|
|
181
|
+
* Implementations throw {@link ForgeCliUnavailableError} when their CLI is
|
|
182
|
+
* absent or unauthenticated so callers can degrade cleanly.
|
|
183
|
+
*/
|
|
184
|
+
interface ForgeProvider {
|
|
185
|
+
readonly forge: ForgeName;
|
|
186
|
+
/** Resolve the PR/MR base (target) branch name. */
|
|
187
|
+
fetchBaseBranch(url: ForgeUrl): Promise<string>;
|
|
188
|
+
/** Fetch the PR/MR discussion threads in normalized form. */
|
|
189
|
+
fetchThreads(url: ForgeUrl, options?: FetchThreadsOptions): Promise<ForgeThread[]>;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Thrown by providers when their CLI is missing (spawn ENOENT) or exits
|
|
193
|
+
* non-zero due to authentication/API failure. Callers catch this to degrade
|
|
194
|
+
* (print to stderr, continue without threads) instead of crashing.
|
|
195
|
+
*/
|
|
196
|
+
declare class ForgeCliUnavailableError extends Error {
|
|
197
|
+
readonly forge: ForgeName;
|
|
198
|
+
readonly cli: string;
|
|
199
|
+
constructor(forge: ForgeName, cli: string, message: string);
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* Parse a forge web URL into a {@link ForgeUrl}, or return `null` for
|
|
203
|
+
* anything that is not a PR/MR URL. Detection is by path shape only, on any
|
|
204
|
+
* http(s) host. Query strings and fragments are ignored.
|
|
205
|
+
*/
|
|
206
|
+
declare function parseForgeUrl(url: string): ForgeUrl | null;
|
|
207
|
+
|
|
81
208
|
/**
|
|
82
209
|
* Generate synthetic unified diffs for a list of file paths so they can be
|
|
83
210
|
* parsed by the existing diff parser. Each file is treated as a new addition.
|
|
@@ -157,4 +284,110 @@ declare function getRenderedTextMode(filePath: string): RenderedTextMode | null;
|
|
|
157
284
|
declare function isPreviewableRenderedText(filePath: string): boolean;
|
|
158
285
|
declare function getLanguageFromPath(filePath: string): string;
|
|
159
286
|
|
|
160
|
-
|
|
287
|
+
/**
|
|
288
|
+
* Create the GitHub {@link ForgeProvider} backed by an injected command
|
|
289
|
+
* runner, mirroring how `git.ts` keeps child-process execution testable.
|
|
290
|
+
*/
|
|
291
|
+
declare function createGitHubProvider(runCommand: ForgeCommandRunner): ForgeProvider;
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Sentinel `filePath` for review-level threads (threads with no file
|
|
295
|
+
* association at all, e.g. GitLab non-diff discussions).
|
|
296
|
+
*
|
|
297
|
+
* The v3 schema has no review-level comment element — every `<comment>`
|
|
298
|
+
* lives inside a `<file path>` — so the mapper degrades these threads to
|
|
299
|
+
* file-level comments on this sentinel path, the closest legal shape.
|
|
300
|
+
* The empty string can never collide with a repository-relative diff path,
|
|
301
|
+
* so consumers (the fetch-comments orchestrator, the app's remote mode)
|
|
302
|
+
* detect review-level comments by comparing against this constant and
|
|
303
|
+
* decide their placement (e.g. a synthetic review-level file entry).
|
|
304
|
+
*/
|
|
305
|
+
declare const REVIEW_LEVEL_FILE_PATH = "";
|
|
306
|
+
/**
|
|
307
|
+
* Convert normalized forge threads into v3 `ReviewComment` threads.
|
|
308
|
+
*
|
|
309
|
+
* - The root turn becomes the root comment and owns the anchor; subsequent
|
|
310
|
+
* turns become flat replies in document order (nothing sorts them).
|
|
311
|
+
* - Forge usernames land in `author`, forge thread/comment ids in
|
|
312
|
+
* `remoteId`, markdown bodies pass through verbatim.
|
|
313
|
+
* - Outdated or line-less anchors degrade to file-level comments
|
|
314
|
+
* (`lineRange: null`); anchor-less threads degrade to file-level
|
|
315
|
+
* comments on {@link REVIEW_LEVEL_FILE_PATH}. The degradation is
|
|
316
|
+
* structural, never textual.
|
|
317
|
+
* - Mapped comments carry no category, severity or confidence: forge
|
|
318
|
+
* threads have none, and absent means below every threshold. The empty
|
|
319
|
+
* `category` matches how the XML parser represents a missing category.
|
|
320
|
+
*
|
|
321
|
+
* Output order is input order. The input is never mutated.
|
|
322
|
+
*/
|
|
323
|
+
declare function mapThreadsToReviewComments(threads: ForgeThread[]): ReviewComment[];
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Create the GitLab {@link ForgeProvider} backed by the `glab` CLI.
|
|
327
|
+
*
|
|
328
|
+
* The URL's host is forwarded via `--hostname`, so self-hosted instances
|
|
329
|
+
* (e.g. git.drupalcode.org) work with zero configuration beyond `glab auth`.
|
|
330
|
+
* Resolved discussions are excluded unless `includeResolved` is set.
|
|
331
|
+
*/
|
|
332
|
+
declare function createGitLabProvider(runCommand: ForgeCommandRunner): ForgeProvider;
|
|
333
|
+
|
|
334
|
+
/** How the local git context was obtained. */
|
|
335
|
+
type MaterializeMode = 'existing-clone' | 'temp-clone';
|
|
336
|
+
/** Result of materializing a forge URL into a local git context. */
|
|
337
|
+
interface MaterializeResult {
|
|
338
|
+
/** Root of the git repository to run the diff pipeline in. */
|
|
339
|
+
repoPath: string;
|
|
340
|
+
/** Resolved SHA of the PR/MR base branch tip. */
|
|
341
|
+
baseSha: string;
|
|
342
|
+
/** Resolved SHA of the PR/MR head (the live remote head). */
|
|
343
|
+
headSha: string;
|
|
344
|
+
mode: MaterializeMode;
|
|
345
|
+
/**
|
|
346
|
+
* Removes the temp clone directory when one was created this run; a no-op
|
|
347
|
+
* for the existing-clone mode. Safe to call more than once. Only ever
|
|
348
|
+
* deletes a directory this materializer created.
|
|
349
|
+
*/
|
|
350
|
+
cleanup: () => void;
|
|
351
|
+
}
|
|
352
|
+
/** A local clone whose fetch remote matches the requested forge repository. */
|
|
353
|
+
interface ExistingClone {
|
|
354
|
+
repoPath: string;
|
|
355
|
+
remoteName: string;
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* Default runner: spawns real git. Resolves with the exit code on any
|
|
359
|
+
* completed run (including non-zero); rejects only when git cannot be
|
|
360
|
+
* spawned at all (e.g. ENOENT).
|
|
361
|
+
*/
|
|
362
|
+
declare const defaultGitRunner: ForgeCommandRunner;
|
|
363
|
+
/**
|
|
364
|
+
* Detect an existing clone: when `cwd` is inside a git repository with a
|
|
365
|
+
* remote matching the forge URL, return `{ repoPath, remoteName }`.
|
|
366
|
+
*/
|
|
367
|
+
declare function detectExistingClone(url: ForgeUrl, cwd: string, runner?: ForgeCommandRunner): Promise<ExistingClone | null>;
|
|
368
|
+
/**
|
|
369
|
+
* Materialize a forge PR/MR into a local git context.
|
|
370
|
+
*
|
|
371
|
+
* When `cwd` is inside a git repository with a remote matching the forge
|
|
372
|
+
* URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
|
|
373
|
+
* branch and PR/MR head refs are fetched into that clone under
|
|
374
|
+
* `refs/self-review/*` — read-only for the working tree. Otherwise a
|
|
375
|
+
* blobless clone is created in a unique directory under the OS temp root
|
|
376
|
+
* and `cleanup()` removes exactly that directory. Callers that already
|
|
377
|
+
* detected a clone may pass it to avoid repeating the git probes.
|
|
378
|
+
*
|
|
379
|
+
* The returned `headSha` is the live remote head, so callers can compare it
|
|
380
|
+
* against a recorded `remote-head-sha` for drift detection.
|
|
381
|
+
*/
|
|
382
|
+
declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner, existingClone?: ExistingClone | null): Promise<MaterializeResult>;
|
|
383
|
+
/**
|
|
384
|
+
* Git-only fallback for the base branch when no forge CLI is available:
|
|
385
|
+
* resolves the remote's default branch from its HEAD symref via
|
|
386
|
+
* `git ls-remote --symref <remote> HEAD`. When an existing matching clone
|
|
387
|
+
* is supplied, the configured remote is used so its SSH/HTTPS transport
|
|
388
|
+
* and credentials are preserved. Otherwise the forge HTTPS URL is used.
|
|
389
|
+
* No forge API involved.
|
|
390
|
+
*/
|
|
391
|
+
declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner, existing?: ExistingClone | null): Promise<string>;
|
|
392
|
+
|
|
393
|
+
export { type ExistingClone, type FetchThreadsOptions, type ForgeAnchorSide, ForgeCliUnavailableError, type ForgeCommandResult, type ForgeCommandRunner, type ForgeName, type ForgeProvider, type ForgeThread, type ForgeThreadAnchor, type ForgeThreadTurn, type ForgeUrl, GUIDE_XSD_SCHEMA, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type MaterializeMode, type MaterializeResult, REVIEW_LEVEL_FILE_PATH, type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createGitHubProvider, createGitLabProvider, createIgnoreFilter, defaultGitRunner, detectExistingClone, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, mapThreadsToReviewComments, materialize, parseDiff, parseForgeUrl, parseGuideXml, parseReviewXml, parseReviewXmlString, reconcileGuide, resolveRemoteDefaultBranch, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { DiffFile, ReviewState, ReviewComment, DiffSource, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats } from '@self-review/types';
|
|
1
|
+
import { DiffFile, ReviewState, ReviewComment, DiffSource, RemoteForge, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats } from '@self-review/types';
|
|
2
2
|
export { AppConfig, Attachment, CategoryDef, ChangeType, CommentConfidence, CommentSeverity, DiffFile, DiffHunk, DiffLine, DiffLineType, DiffLoadPayload, DiffSource, ExpandContextRequest, ExpandContextResponse, FileReviewState, FindInPageRequest, FindInPageResult, GuideFileEntry, GuideGroup, ImageLoadResult, LineRange, OutputPathInfo, PayloadStats, ResolvedGuideFile, ResolvedGuideGroup, ResumeLoadPayload, ReviewComment, ReviewGuide, ReviewState, Suggestion, VersionUpdateInfo } from '@self-review/types';
|
|
3
3
|
|
|
4
4
|
declare function parseDiff(rawDiff: string): DiffFile[];
|
|
@@ -11,6 +11,10 @@ interface ParsedReview {
|
|
|
11
11
|
viewedFiles: string[];
|
|
12
12
|
gitDiffArgs: string;
|
|
13
13
|
source: DiffSource;
|
|
14
|
+
remoteUrl?: string;
|
|
15
|
+
remoteBaseSha?: string;
|
|
16
|
+
remoteHeadSha?: string;
|
|
17
|
+
remoteForge?: RemoteForge;
|
|
14
18
|
}
|
|
15
19
|
declare function parseReviewXml(xmlPath: string): ParsedReview;
|
|
16
20
|
declare function parseReviewXmlString(xmlContent: string): ParsedReview;
|
|
@@ -78,6 +82,129 @@ declare function getUntrackedFilesAsync(cwd?: string): Promise<string[]>;
|
|
|
78
82
|
*/
|
|
79
83
|
declare function generateUntrackedDiffs(paths: string[], repoRoot: string): string;
|
|
80
84
|
|
|
85
|
+
/** Forges the app knows how to talk to. */
|
|
86
|
+
type ForgeName = 'github' | 'gitlab';
|
|
87
|
+
/**
|
|
88
|
+
* A parsed pull-request / merge-request web URL.
|
|
89
|
+
*
|
|
90
|
+
* Detection is by URL path shape only (`/pull/N` → GitHub,
|
|
91
|
+
* `/-/merge_requests/N` → GitLab) on any host, so self-hosted instances such
|
|
92
|
+
* as git.drupalcode.org work with zero configuration.
|
|
93
|
+
*/
|
|
94
|
+
interface ForgeUrl {
|
|
95
|
+
forge: ForgeName;
|
|
96
|
+
/** Host as it appears in the URL, including a port when present. */
|
|
97
|
+
host: string;
|
|
98
|
+
/**
|
|
99
|
+
* Repository owner. For GitLab this is the full namespace path and may
|
|
100
|
+
* contain slashes (subgroups, e.g. `group/subgroup`); for GitHub it is a
|
|
101
|
+
* single segment.
|
|
102
|
+
*/
|
|
103
|
+
owner: string;
|
|
104
|
+
/** Repository name (final path segment before the PR/MR marker). */
|
|
105
|
+
repo: string;
|
|
106
|
+
/** Pull-request number / merge-request IID. */
|
|
107
|
+
number: number;
|
|
108
|
+
}
|
|
109
|
+
/** Which side of the diff a thread anchor points at. */
|
|
110
|
+
type ForgeAnchorSide = 'old' | 'new';
|
|
111
|
+
/**
|
|
112
|
+
* Forge-neutral anchor of a discussion thread onto the diff.
|
|
113
|
+
*
|
|
114
|
+
* The mapper consumes this shape without forge-conditional logic:
|
|
115
|
+
* - `startLine`/`endLine` are equal for single-line anchors.
|
|
116
|
+
* - `startLine`/`endLine` are `null` when the forge supplies a file path but
|
|
117
|
+
* no usable line information (the mapper degrades to a file-level comment;
|
|
118
|
+
* `side` is meaningless in that case and providers should set `'new'`).
|
|
119
|
+
* - `outdated: true` means the forge reports the anchor no longer applies to
|
|
120
|
+
* the current head (e.g. GitHub outdated review comments); the line fields
|
|
121
|
+
* then hold the historic anchor and the mapper degrades to file-level.
|
|
122
|
+
*/
|
|
123
|
+
interface ForgeThreadAnchor {
|
|
124
|
+
filePath: string;
|
|
125
|
+
side: ForgeAnchorSide;
|
|
126
|
+
startLine: number | null;
|
|
127
|
+
endLine: number | null;
|
|
128
|
+
outdated: boolean;
|
|
129
|
+
}
|
|
130
|
+
/** One turn (root comment or reply) in a forge discussion thread. */
|
|
131
|
+
interface ForgeThreadTurn {
|
|
132
|
+
/** Forge-assigned comment/note ID, kept as a string verbatim. */
|
|
133
|
+
remoteId: string;
|
|
134
|
+
/** Forge username of the turn's author. */
|
|
135
|
+
author: string;
|
|
136
|
+
/** Markdown body, passed through verbatim. */
|
|
137
|
+
body: string;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* A normalized discussion thread: an ordered root + flat replies.
|
|
141
|
+
*
|
|
142
|
+
* The root turn owns the anchor. `anchor` is `null` for threads with no file
|
|
143
|
+
* association at all (e.g. GitLab non-diff discussions); the mapper turns
|
|
144
|
+
* those into its review-level representation. `replies` preserve the forge's
|
|
145
|
+
* document order — nothing else sorts them.
|
|
146
|
+
*/
|
|
147
|
+
interface ForgeThread {
|
|
148
|
+
root: ForgeThreadTurn;
|
|
149
|
+
replies: ForgeThreadTurn[];
|
|
150
|
+
anchor: ForgeThreadAnchor | null;
|
|
151
|
+
}
|
|
152
|
+
/** Options for {@link ForgeProvider.fetchThreads}. */
|
|
153
|
+
interface FetchThreadsOptions {
|
|
154
|
+
/**
|
|
155
|
+
* Include threads the forge marks resolved. Defaults to false where the
|
|
156
|
+
* forge tracks resolution (GitLab); providers without a comparable concept
|
|
157
|
+
* on the fetch path (GitHub REST review comments) may ignore it.
|
|
158
|
+
*/
|
|
159
|
+
includeResolved?: boolean;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Result of running a forge CLI command through {@link ForgeCommandRunner}.
|
|
163
|
+
*/
|
|
164
|
+
interface ForgeCommandResult {
|
|
165
|
+
stdout: string;
|
|
166
|
+
stderr: string;
|
|
167
|
+
exitCode: number;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Injectable command runner used by provider implementations, mirroring how
|
|
171
|
+
* `git.ts` keeps child-process execution testable. Resolves with the exit
|
|
172
|
+
* code on any completed run (including non-zero); rejects only when the
|
|
173
|
+
* binary cannot be spawned at all (e.g. ENOENT when the CLI is absent).
|
|
174
|
+
*/
|
|
175
|
+
type ForgeCommandRunner = (command: string, args: string[]) => Promise<ForgeCommandResult>;
|
|
176
|
+
/**
|
|
177
|
+
* The conversation plane of a forge. Exactly two capabilities: base-branch
|
|
178
|
+
* lookup and discussion-thread fetching. No diff fetching, no blob fetching,
|
|
179
|
+
* no posting — those concerns live elsewhere.
|
|
180
|
+
*
|
|
181
|
+
* Implementations throw {@link ForgeCliUnavailableError} when their CLI is
|
|
182
|
+
* absent or unauthenticated so callers can degrade cleanly.
|
|
183
|
+
*/
|
|
184
|
+
interface ForgeProvider {
|
|
185
|
+
readonly forge: ForgeName;
|
|
186
|
+
/** Resolve the PR/MR base (target) branch name. */
|
|
187
|
+
fetchBaseBranch(url: ForgeUrl): Promise<string>;
|
|
188
|
+
/** Fetch the PR/MR discussion threads in normalized form. */
|
|
189
|
+
fetchThreads(url: ForgeUrl, options?: FetchThreadsOptions): Promise<ForgeThread[]>;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Thrown by providers when their CLI is missing (spawn ENOENT) or exits
|
|
193
|
+
* non-zero due to authentication/API failure. Callers catch this to degrade
|
|
194
|
+
* (print to stderr, continue without threads) instead of crashing.
|
|
195
|
+
*/
|
|
196
|
+
declare class ForgeCliUnavailableError extends Error {
|
|
197
|
+
readonly forge: ForgeName;
|
|
198
|
+
readonly cli: string;
|
|
199
|
+
constructor(forge: ForgeName, cli: string, message: string);
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* Parse a forge web URL into a {@link ForgeUrl}, or return `null` for
|
|
203
|
+
* anything that is not a PR/MR URL. Detection is by path shape only, on any
|
|
204
|
+
* http(s) host. Query strings and fragments are ignored.
|
|
205
|
+
*/
|
|
206
|
+
declare function parseForgeUrl(url: string): ForgeUrl | null;
|
|
207
|
+
|
|
81
208
|
/**
|
|
82
209
|
* Generate synthetic unified diffs for a list of file paths so they can be
|
|
83
210
|
* parsed by the existing diff parser. Each file is treated as a new addition.
|
|
@@ -157,4 +284,110 @@ declare function getRenderedTextMode(filePath: string): RenderedTextMode | null;
|
|
|
157
284
|
declare function isPreviewableRenderedText(filePath: string): boolean;
|
|
158
285
|
declare function getLanguageFromPath(filePath: string): string;
|
|
159
286
|
|
|
160
|
-
|
|
287
|
+
/**
|
|
288
|
+
* Create the GitHub {@link ForgeProvider} backed by an injected command
|
|
289
|
+
* runner, mirroring how `git.ts` keeps child-process execution testable.
|
|
290
|
+
*/
|
|
291
|
+
declare function createGitHubProvider(runCommand: ForgeCommandRunner): ForgeProvider;
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Sentinel `filePath` for review-level threads (threads with no file
|
|
295
|
+
* association at all, e.g. GitLab non-diff discussions).
|
|
296
|
+
*
|
|
297
|
+
* The v3 schema has no review-level comment element — every `<comment>`
|
|
298
|
+
* lives inside a `<file path>` — so the mapper degrades these threads to
|
|
299
|
+
* file-level comments on this sentinel path, the closest legal shape.
|
|
300
|
+
* The empty string can never collide with a repository-relative diff path,
|
|
301
|
+
* so consumers (the fetch-comments orchestrator, the app's remote mode)
|
|
302
|
+
* detect review-level comments by comparing against this constant and
|
|
303
|
+
* decide their placement (e.g. a synthetic review-level file entry).
|
|
304
|
+
*/
|
|
305
|
+
declare const REVIEW_LEVEL_FILE_PATH = "";
|
|
306
|
+
/**
|
|
307
|
+
* Convert normalized forge threads into v3 `ReviewComment` threads.
|
|
308
|
+
*
|
|
309
|
+
* - The root turn becomes the root comment and owns the anchor; subsequent
|
|
310
|
+
* turns become flat replies in document order (nothing sorts them).
|
|
311
|
+
* - Forge usernames land in `author`, forge thread/comment ids in
|
|
312
|
+
* `remoteId`, markdown bodies pass through verbatim.
|
|
313
|
+
* - Outdated or line-less anchors degrade to file-level comments
|
|
314
|
+
* (`lineRange: null`); anchor-less threads degrade to file-level
|
|
315
|
+
* comments on {@link REVIEW_LEVEL_FILE_PATH}. The degradation is
|
|
316
|
+
* structural, never textual.
|
|
317
|
+
* - Mapped comments carry no category, severity or confidence: forge
|
|
318
|
+
* threads have none, and absent means below every threshold. The empty
|
|
319
|
+
* `category` matches how the XML parser represents a missing category.
|
|
320
|
+
*
|
|
321
|
+
* Output order is input order. The input is never mutated.
|
|
322
|
+
*/
|
|
323
|
+
declare function mapThreadsToReviewComments(threads: ForgeThread[]): ReviewComment[];
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Create the GitLab {@link ForgeProvider} backed by the `glab` CLI.
|
|
327
|
+
*
|
|
328
|
+
* The URL's host is forwarded via `--hostname`, so self-hosted instances
|
|
329
|
+
* (e.g. git.drupalcode.org) work with zero configuration beyond `glab auth`.
|
|
330
|
+
* Resolved discussions are excluded unless `includeResolved` is set.
|
|
331
|
+
*/
|
|
332
|
+
declare function createGitLabProvider(runCommand: ForgeCommandRunner): ForgeProvider;
|
|
333
|
+
|
|
334
|
+
/** How the local git context was obtained. */
|
|
335
|
+
type MaterializeMode = 'existing-clone' | 'temp-clone';
|
|
336
|
+
/** Result of materializing a forge URL into a local git context. */
|
|
337
|
+
interface MaterializeResult {
|
|
338
|
+
/** Root of the git repository to run the diff pipeline in. */
|
|
339
|
+
repoPath: string;
|
|
340
|
+
/** Resolved SHA of the PR/MR base branch tip. */
|
|
341
|
+
baseSha: string;
|
|
342
|
+
/** Resolved SHA of the PR/MR head (the live remote head). */
|
|
343
|
+
headSha: string;
|
|
344
|
+
mode: MaterializeMode;
|
|
345
|
+
/**
|
|
346
|
+
* Removes the temp clone directory when one was created this run; a no-op
|
|
347
|
+
* for the existing-clone mode. Safe to call more than once. Only ever
|
|
348
|
+
* deletes a directory this materializer created.
|
|
349
|
+
*/
|
|
350
|
+
cleanup: () => void;
|
|
351
|
+
}
|
|
352
|
+
/** A local clone whose fetch remote matches the requested forge repository. */
|
|
353
|
+
interface ExistingClone {
|
|
354
|
+
repoPath: string;
|
|
355
|
+
remoteName: string;
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* Default runner: spawns real git. Resolves with the exit code on any
|
|
359
|
+
* completed run (including non-zero); rejects only when git cannot be
|
|
360
|
+
* spawned at all (e.g. ENOENT).
|
|
361
|
+
*/
|
|
362
|
+
declare const defaultGitRunner: ForgeCommandRunner;
|
|
363
|
+
/**
|
|
364
|
+
* Detect an existing clone: when `cwd` is inside a git repository with a
|
|
365
|
+
* remote matching the forge URL, return `{ repoPath, remoteName }`.
|
|
366
|
+
*/
|
|
367
|
+
declare function detectExistingClone(url: ForgeUrl, cwd: string, runner?: ForgeCommandRunner): Promise<ExistingClone | null>;
|
|
368
|
+
/**
|
|
369
|
+
* Materialize a forge PR/MR into a local git context.
|
|
370
|
+
*
|
|
371
|
+
* When `cwd` is inside a git repository with a remote matching the forge
|
|
372
|
+
* URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
|
|
373
|
+
* branch and PR/MR head refs are fetched into that clone under
|
|
374
|
+
* `refs/self-review/*` — read-only for the working tree. Otherwise a
|
|
375
|
+
* blobless clone is created in a unique directory under the OS temp root
|
|
376
|
+
* and `cleanup()` removes exactly that directory. Callers that already
|
|
377
|
+
* detected a clone may pass it to avoid repeating the git probes.
|
|
378
|
+
*
|
|
379
|
+
* The returned `headSha` is the live remote head, so callers can compare it
|
|
380
|
+
* against a recorded `remote-head-sha` for drift detection.
|
|
381
|
+
*/
|
|
382
|
+
declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner, existingClone?: ExistingClone | null): Promise<MaterializeResult>;
|
|
383
|
+
/**
|
|
384
|
+
* Git-only fallback for the base branch when no forge CLI is available:
|
|
385
|
+
* resolves the remote's default branch from its HEAD symref via
|
|
386
|
+
* `git ls-remote --symref <remote> HEAD`. When an existing matching clone
|
|
387
|
+
* is supplied, the configured remote is used so its SSH/HTTPS transport
|
|
388
|
+
* and credentials are preserved. Otherwise the forge HTTPS URL is used.
|
|
389
|
+
* No forge API involved.
|
|
390
|
+
*/
|
|
391
|
+
declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner, existing?: ExistingClone | null): Promise<string>;
|
|
392
|
+
|
|
393
|
+
export { type ExistingClone, type FetchThreadsOptions, type ForgeAnchorSide, ForgeCliUnavailableError, type ForgeCommandResult, type ForgeCommandRunner, type ForgeName, type ForgeProvider, type ForgeThread, type ForgeThreadAnchor, type ForgeThreadTurn, type ForgeUrl, GUIDE_XSD_SCHEMA, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type MaterializeMode, type MaterializeResult, REVIEW_LEVEL_FILE_PATH, type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createGitHubProvider, createGitLabProvider, createIgnoreFilter, defaultGitRunner, detectExistingClone, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, mapThreadsToReviewComments, materialize, parseDiff, parseForgeUrl, parseGuideXml, parseReviewXml, parseReviewXmlString, reconcileGuide, resolveRemoteDefaultBranch, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
|