@self-review/core 1.41.0 → 1.43.0

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.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,96 @@ 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
- export { GUIDE_XSD_SCHEMA, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createIgnoreFilter, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, parseDiff, parseGuideXml, parseReviewXml, parseReviewXmlString, reconcileGuide, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
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
+ /**
353
+ * Default runner: spawns real git. Resolves with the exit code on any
354
+ * completed run (including non-zero); rejects only when git cannot be
355
+ * spawned at all (e.g. ENOENT).
356
+ */
357
+ declare const defaultGitRunner: ForgeCommandRunner;
358
+ /**
359
+ * Materialize a forge PR/MR into a local git context.
360
+ *
361
+ * When `cwd` is inside a git repository with a remote matching the forge
362
+ * URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
363
+ * branch and PR/MR head refs are fetched into that clone under
364
+ * `refs/self-review/*` — read-only for the working tree. Otherwise a
365
+ * blobless clone is created in a unique directory under the OS temp root
366
+ * and `cleanup()` removes exactly that directory.
367
+ *
368
+ * The returned `headSha` is the live remote head, so callers can compare it
369
+ * against a recorded `remote-head-sha` for drift detection.
370
+ */
371
+ declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner): Promise<MaterializeResult>;
372
+ /**
373
+ * Git-only fallback for the base branch when no forge CLI is available:
374
+ * resolves the remote's default branch from its HEAD symref via
375
+ * `git ls-remote --symref <url> HEAD`. No forge API involved.
376
+ */
377
+ declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner): Promise<string>;
378
+
379
+ export { 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, 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,96 @@ 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
- export { GUIDE_XSD_SCHEMA, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createIgnoreFilter, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, parseDiff, parseGuideXml, parseReviewXml, parseReviewXmlString, reconcileGuide, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
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
+ /**
353
+ * Default runner: spawns real git. Resolves with the exit code on any
354
+ * completed run (including non-zero); rejects only when git cannot be
355
+ * spawned at all (e.g. ENOENT).
356
+ */
357
+ declare const defaultGitRunner: ForgeCommandRunner;
358
+ /**
359
+ * Materialize a forge PR/MR into a local git context.
360
+ *
361
+ * When `cwd` is inside a git repository with a remote matching the forge
362
+ * URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
363
+ * branch and PR/MR head refs are fetched into that clone under
364
+ * `refs/self-review/*` — read-only for the working tree. Otherwise a
365
+ * blobless clone is created in a unique directory under the OS temp root
366
+ * and `cleanup()` removes exactly that directory.
367
+ *
368
+ * The returned `headSha` is the live remote head, so callers can compare it
369
+ * against a recorded `remote-head-sha` for drift detection.
370
+ */
371
+ declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner): Promise<MaterializeResult>;
372
+ /**
373
+ * Git-only fallback for the base branch when no forge CLI is available:
374
+ * resolves the remote's default branch from its HEAD symref via
375
+ * `git ls-remote --symref <url> HEAD`. No forge API involved.
376
+ */
377
+ declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner): Promise<string>;
378
+
379
+ export { 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, 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 };