@self-review/core 2.0.4 → 2.1.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.
- package/README.md +441 -0
- package/dist/chunk-5SGPWHGH.cjs +106 -0
- package/dist/chunk-5SGPWHGH.cjs.map +1 -0
- package/dist/chunk-6OEFXBIZ.cjs +5212 -0
- package/dist/chunk-6OEFXBIZ.cjs.map +1 -0
- package/dist/chunk-6X3PJHP5.cjs +416 -0
- package/dist/chunk-6X3PJHP5.cjs.map +1 -0
- package/dist/chunk-CJQEOLI3.js +37 -0
- package/dist/chunk-CJQEOLI3.js.map +1 -0
- package/dist/chunk-IG2YF5LH.js +416 -0
- package/dist/chunk-IG2YF5LH.js.map +1 -0
- package/dist/chunk-IX226KG4.js +106 -0
- package/dist/chunk-IX226KG4.js.map +1 -0
- package/dist/chunk-LSLCQQBN.cjs +3684 -0
- package/dist/chunk-LSLCQQBN.cjs.map +1 -0
- package/dist/chunk-MOYO4RIX.js +3684 -0
- package/dist/chunk-MOYO4RIX.js.map +1 -0
- package/dist/chunk-TOUYY7I6.js +5212 -0
- package/dist/chunk-TOUYY7I6.js.map +1 -0
- package/dist/chunk-VOYTFLPH.cjs +37 -0
- package/dist/chunk-VOYTFLPH.cjs.map +1 -0
- package/dist/filesystem.cjs +56 -0
- package/dist/filesystem.cjs.map +1 -0
- package/dist/filesystem.d.cts +22 -0
- package/dist/filesystem.d.ts +22 -0
- package/dist/filesystem.js +56 -0
- package/dist/index.cjs +348 -6192
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +80 -1332
- package/dist/index.d.ts +80 -1332
- package/dist/index.js +234 -5172
- package/dist/index.js.map +1 -1
- package/dist/node-scan-fs-CaufzUZR.d.cts +5 -0
- package/dist/node-scan-fs-DcHI_BYB.d.ts +5 -0
- package/dist/operations-Bqhi9EBH.d.ts +765 -0
- package/dist/operations-UyiUD2Nx.d.cts +765 -0
- package/dist/operations.cjs +91 -0
- package/dist/operations.cjs.map +1 -0
- package/dist/operations.d.cts +6 -0
- package/dist/operations.d.ts +6 -0
- package/dist/operations.js +91 -0
- package/dist/resume-worker.cjs +152 -0
- package/dist/resume-worker.cjs.map +1 -0
- package/dist/resume-worker.d.cts +56 -0
- package/dist/resume-worker.d.ts +56 -0
- package/dist/resume-worker.js +152 -0
- package/dist/resume-worker.js.map +1 -0
- package/dist/review-request-validation-VJG7XZiE.d.cts +62 -0
- package/dist/review-request-validation-VJG7XZiE.d.ts +62 -0
- package/dist/review-xml-decoder-COgRtfkf.d.cts +33 -0
- package/dist/review-xml-decoder-COgRtfkf.d.ts +33 -0
- package/dist/source-identity-CQpAzugz.d.cts +959 -0
- package/dist/source-identity-CQpAzugz.d.ts +959 -0
- package/dist/validation.cjs +67 -0
- package/dist/validation.cjs.map +1 -0
- package/dist/validation.d.cts +30 -0
- package/dist/validation.d.ts +30 -0
- package/dist/validation.js +67 -0
- package/dist/validation.js.map +1 -0
- package/package.json +44 -3
- package/dist/chunk-4YO2MI6B.js +0 -269
- package/dist/chunk-4YO2MI6B.js.map +0 -1
- package/dist/chunk-QHS36X6T.js +0 -450
- package/dist/chunk-QHS36X6T.js.map +0 -1
- package/dist/diff-parser-B6S3KG5T.js +0 -9
- package/dist/git-N5HVNPKQ.js +0 -24
- /package/dist/{diff-parser-B6S3KG5T.js.map → filesystem.js.map} +0 -0
- /package/dist/{git-N5HVNPKQ.js.map → operations.js.map} +0 -0
|
@@ -0,0 +1,765 @@
|
|
|
1
|
+
import { ReviewComment, ReviewState, DiffFile, ReviewSourceIdentity, AppConfig, ImageLoadResult, DiffLoadPayload, PayloadStats, GuideLoadPayload, RemoteSessionInfo, RemoteForge } from '@self-review/types';
|
|
2
|
+
import { ai as ForgeCommandOptions, U as ForgeCommandRunner, T as TemporaryCloneStorage, Q as DiagnosticReporter, an as ForgeUrl, F as FsLayer, P as PublicationFileSystem, a6 as AttachmentOrigins, S as ScanFsLayer, O as SourceBudgets, as as LoadedReview, B as BoundedAsyncReadFsLayer, Y as ReviewSession, a9 as AttachmentReadResult, bv as ResolvedAttachmentLocation, R as GitExecutionOptions, n as SourceReadFsLayer, L as LocalSourcePaths, ak as ForgeName, V as ForgeProvider, X as ForgeThread } from './source-identity-CQpAzugz.cjs';
|
|
3
|
+
import { Stats } from 'node:fs';
|
|
4
|
+
import { P as ParsedReview } from './review-xml-decoder-COgRtfkf.cjs';
|
|
5
|
+
|
|
6
|
+
interface BufferedCommandResult {
|
|
7
|
+
stdout: Buffer;
|
|
8
|
+
stderr: Buffer;
|
|
9
|
+
exitCode: number;
|
|
10
|
+
}
|
|
11
|
+
/** Same completion, interruption and output-bound contract as ForgeCommandRunner, with raw bytes. */
|
|
12
|
+
type BufferedCommandRunner = (command: string, args: string[], options?: ForgeCommandOptions) => Promise<BufferedCommandResult>;
|
|
13
|
+
/** Text view for forge commands and diff metadata. The byte limit is applied before decoding. */
|
|
14
|
+
declare const defaultGitRunner: ForgeCommandRunner;
|
|
15
|
+
|
|
16
|
+
/** How the local git context was obtained. */
|
|
17
|
+
type MaterializeMode = 'existing-clone' | 'temp-clone';
|
|
18
|
+
/** Result of materializing a forge URL into a local git context. */
|
|
19
|
+
interface MaterializeResult {
|
|
20
|
+
/** Root of the git repository to run the diff pipeline in. */
|
|
21
|
+
repoPath: string;
|
|
22
|
+
/** Resolved SHA of the PR/MR base branch tip. */
|
|
23
|
+
baseSha: string;
|
|
24
|
+
/** Resolved SHA of the PR/MR head (the live remote head). */
|
|
25
|
+
headSha: string;
|
|
26
|
+
mode: MaterializeMode;
|
|
27
|
+
/**
|
|
28
|
+
* Refs this session created in a reused clone and deletes on cleanup; empty for a temp clone.
|
|
29
|
+
*/
|
|
30
|
+
ownedRefs: readonly string[];
|
|
31
|
+
/**
|
|
32
|
+
* Removes the temp clone (synchronously, before the first await, so an `exit`
|
|
33
|
+
* handler that cannot wait still gets that far) and deletes the session's refs
|
|
34
|
+
* from a reused clone. Idempotent, never rejects; a failed deletion goes to stderr.
|
|
35
|
+
* A caller that opts into cleanupAsync must await that disposal: while it is in flight,
|
|
36
|
+
* cleanup joins the same deletion rather than starting a competing synchronous removal.
|
|
37
|
+
*/
|
|
38
|
+
cleanup: () => Promise<void>;
|
|
39
|
+
/** Nonblocking normal disposal; concurrent calls share one attempt and failures can be retried. */
|
|
40
|
+
cleanupAsync?: () => Promise<void>;
|
|
41
|
+
}
|
|
42
|
+
/** A local clone whose fetch remote matches the requested forge repository. */
|
|
43
|
+
interface ExistingClone {
|
|
44
|
+
repoPath: string;
|
|
45
|
+
remoteName: string;
|
|
46
|
+
}
|
|
47
|
+
interface MaterializeOptions {
|
|
48
|
+
/** Authoritative owner of temporary clone creation and both removal modes. */
|
|
49
|
+
temporaryClones?: TemporaryCloneStorage;
|
|
50
|
+
/** Per-call progress and cleanup diagnostics. Defaults to stderr; must not throw. */
|
|
51
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
52
|
+
/**
|
|
53
|
+
* Aborting kills the command in flight and rejects with {@link CommandCancelledError}; the temp
|
|
54
|
+
* clone is removed first.
|
|
55
|
+
*/
|
|
56
|
+
signal?: AbortSignal;
|
|
57
|
+
/** Defaults to {@link DEFAULT_GIT_COMMAND_TIMEOUT_MS}. */
|
|
58
|
+
commandTimeoutMs?: number;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Generous because a blobless clone over a slow link is legitimately slow; tighter hosts abort via
|
|
62
|
+
* the signal.
|
|
63
|
+
*/
|
|
64
|
+
declare const DEFAULT_GIT_COMMAND_TIMEOUT_MS: number;
|
|
65
|
+
/**
|
|
66
|
+
* Detect an existing clone: when `cwd` is inside a git repository with a
|
|
67
|
+
* remote matching the forge URL, return `{ repoPath, remoteName }`.
|
|
68
|
+
*/
|
|
69
|
+
declare function detectExistingClone(url: ForgeUrl, cwd: string, runner?: ForgeCommandRunner, options?: MaterializeOptions): Promise<ExistingClone | null>;
|
|
70
|
+
/**
|
|
71
|
+
* Materialize a forge PR/MR into a local git context.
|
|
72
|
+
*
|
|
73
|
+
* When `cwd` is inside a git repository with a remote matching the forge
|
|
74
|
+
* URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
|
|
75
|
+
* branch and PR/MR head refs are fetched into that clone under
|
|
76
|
+
* `refs/self-review/<session>/` (read-only for the working tree; `cleanup()`
|
|
77
|
+
* deletes exactly those two refs). Otherwise a blobless clone is created in a
|
|
78
|
+
* unique directory under the OS temp root and `cleanup()` removes it. Callers
|
|
79
|
+
* that already detected a clone may pass it to skip the git probes.
|
|
80
|
+
*
|
|
81
|
+
* The returned `headSha` is the live remote head, so callers can compare it
|
|
82
|
+
* against a recorded `remote-head-sha` for drift detection.
|
|
83
|
+
*/
|
|
84
|
+
declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner, existingClone?: ExistingClone | null, options?: MaterializeOptions): Promise<MaterializeResult>;
|
|
85
|
+
/**
|
|
86
|
+
* Git-only fallback for the base branch when no forge CLI is available:
|
|
87
|
+
* resolves the remote's default branch from its HEAD symref via
|
|
88
|
+
* `git ls-remote --symref <remote> HEAD`. When an existing matching clone
|
|
89
|
+
* is supplied, the configured remote is used so its SSH/HTTPS transport
|
|
90
|
+
* and credentials are preserved. Otherwise the forge HTTPS URL is used.
|
|
91
|
+
* No forge API involved.
|
|
92
|
+
*/
|
|
93
|
+
declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner, existing?: ExistingClone | null, options?: MaterializeOptions): Promise<string>;
|
|
94
|
+
|
|
95
|
+
/** The bare name in `.self-review-assets/<name>`; null for any other shape. */
|
|
96
|
+
declare function parseAttachmentReference(reference: unknown): string | null;
|
|
97
|
+
/** The caller supplies a physically resolved directory from its own filesystem. No lookup occurs. */
|
|
98
|
+
declare function resolveAttachmentOriginsAtDirectory(comments: readonly ReviewComment[], directory: string): {
|
|
99
|
+
origins: Map<string, string>;
|
|
100
|
+
diagnostics: string[];
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/** A supplied validator is authoritative; throws mean unavailable infrastructure, not invalid XML. */
|
|
104
|
+
type ReviewSchemaValidator = (xml: string, schema: string) => {
|
|
105
|
+
valid: boolean;
|
|
106
|
+
errors?: readonly unknown[];
|
|
107
|
+
} | Promise<{
|
|
108
|
+
valid: boolean;
|
|
109
|
+
errors?: readonly unknown[];
|
|
110
|
+
}>;
|
|
111
|
+
|
|
112
|
+
/** Filesystem errors (ENOENT, EACCES, ...) throw. */
|
|
113
|
+
type BoundedReadResult = {
|
|
114
|
+
kind: 'ok';
|
|
115
|
+
content: Buffer;
|
|
116
|
+
} | {
|
|
117
|
+
kind: 'too-large';
|
|
118
|
+
size: number;
|
|
119
|
+
}
|
|
120
|
+
/** A directory, FIFO, socket or device: nothing was read. */
|
|
121
|
+
| {
|
|
122
|
+
kind: 'not-regular';
|
|
123
|
+
};
|
|
124
|
+
interface BoundedReadOptions {
|
|
125
|
+
/** Covers the leaf only; ancestors are the caller's job (`openContainedFile`). */
|
|
126
|
+
noFollow?: boolean;
|
|
127
|
+
}
|
|
128
|
+
interface AsyncBoundedReadOptions extends BoundedReadOptions {
|
|
129
|
+
signal?: AbortSignal;
|
|
130
|
+
}
|
|
131
|
+
declare function readFileWithinBudget(path: string, maxBytes: number, options?: AsyncBoundedReadOptions): Promise<BoundedReadResult>;
|
|
132
|
+
declare function readFileWithinBudgetSync(path: string, maxBytes: number, options?: BoundedReadOptions): BoundedReadResult;
|
|
133
|
+
|
|
134
|
+
interface ReviewXmlReader {
|
|
135
|
+
/** Must bound allocation and refuse non-regular inputs without blocking. Errors throw. */
|
|
136
|
+
read(path: string, maxBytes: number): BoundedReadResult;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
type ReviewPublishErrorCode =
|
|
140
|
+
/** `details` lists each XSD violation. */
|
|
141
|
+
'validation-failed' | 'xml-illegal-character' | 'output-is-directory' | 'permission-denied' | 'no-space'
|
|
142
|
+
/** A link where the publisher would write, or an inherited path resolving outside its base. */
|
|
143
|
+
| 'unsafe-link'
|
|
144
|
+
/** A hard-linked output, or a non-directory or foreign-owned asset directory. */
|
|
145
|
+
| 'unsupported-target'
|
|
146
|
+
/** A resumed attachment that must move cannot be read where its document put it. */
|
|
147
|
+
| 'attachment-unavailable' | 'io-error';
|
|
148
|
+
declare class ReviewPublishError extends Error {
|
|
149
|
+
readonly code: ReviewPublishErrorCode;
|
|
150
|
+
readonly path: string;
|
|
151
|
+
/** One rendered line per problem; empty when the message is all there is. */
|
|
152
|
+
readonly details: readonly string[];
|
|
153
|
+
readonly cause?: unknown;
|
|
154
|
+
constructor(code: ReviewPublishErrorCode, path: string, message: string, options?: {
|
|
155
|
+
details?: readonly string[];
|
|
156
|
+
cause?: unknown;
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
/** `inherited` paths come from something a repository can commit, so they must stay inside `baseDir`. */
|
|
160
|
+
type ReviewOutputOrigin = 'explicit' | 'inherited';
|
|
161
|
+
/** Resolved by `resolveOutputTarget` in `startup.ts`. */
|
|
162
|
+
type ReviewOutputTarget = {
|
|
163
|
+
path: string;
|
|
164
|
+
origin: 'explicit';
|
|
165
|
+
} | {
|
|
166
|
+
path: string;
|
|
167
|
+
origin: 'inherited';
|
|
168
|
+
baseDir: string;
|
|
169
|
+
};
|
|
170
|
+
interface PublishReviewCommonOptions {
|
|
171
|
+
/** Per-call diagnostics, including XML validation. Defaults to stderr. Must not throw. */
|
|
172
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
173
|
+
/** Optional authoritative schema effect, before staging any asset or XML. */
|
|
174
|
+
validateSchema?: ReviewSchemaValidator;
|
|
175
|
+
fs?: FsLayer;
|
|
176
|
+
/** Explicit asynchronous effects, authoritative over fs when both are supplied. */
|
|
177
|
+
publicationFs?: PublicationFileSystem;
|
|
178
|
+
randomName?: () => string;
|
|
179
|
+
/** Imported attachments whose origin is elsewhere are copied beside the output (`relocateAttachments`). */
|
|
180
|
+
attachmentOrigins?: AttachmentOrigins;
|
|
181
|
+
/** Checked during preparation, between bounded read/write chunks and immediately before rename.
|
|
182
|
+
* Legacy synchronous adapters cannot preempt a single syscall; without readSync their readFileSync
|
|
183
|
+
* allocation is guarded by pre/post size checks rather than a hard allocation bound. Cancellation throws
|
|
184
|
+
* ReviewPublishError (`io-error`, with the signal reason as cause). A completed
|
|
185
|
+
* rename is never rolled back. */
|
|
186
|
+
signal?: AbortSignal;
|
|
187
|
+
}
|
|
188
|
+
type PublishReviewOptions = PublishReviewCommonOptions & ({
|
|
189
|
+
outputOrigin: 'explicit';
|
|
190
|
+
} | {
|
|
191
|
+
outputOrigin: 'inherited';
|
|
192
|
+
baseDir: string;
|
|
193
|
+
});
|
|
194
|
+
interface PublishReviewResult {
|
|
195
|
+
outputPath: string;
|
|
196
|
+
/** The attachment files this publication created. */
|
|
197
|
+
assetPaths: string[];
|
|
198
|
+
}
|
|
199
|
+
/** @throws ReviewPublishError for every failure, document or filesystem. */
|
|
200
|
+
declare function publishReview(state: ReviewState, outputPath: string, options: PublishReviewOptions): Promise<PublishReviewResult>;
|
|
201
|
+
/** The error `publishReview` would throw for the path as it stands; advisory, since the disk can change. */
|
|
202
|
+
declare function inspectOutputPath(outputPath: string, options: PublishReviewOptions): ReviewPublishError | null;
|
|
203
|
+
/** Read-only location and permission effects. Every supplied method retains its receiver. */
|
|
204
|
+
interface OutputPathInspection {
|
|
205
|
+
realpath(target: string): Promise<string>;
|
|
206
|
+
lstat(target: string): Promise<Stats>;
|
|
207
|
+
/** Advisory permission check for the parent, without creating or opening an output file. */
|
|
208
|
+
isWritable(directory: string): Promise<boolean>;
|
|
209
|
+
}
|
|
210
|
+
type AsyncInspectOutputPathOptions = ({
|
|
211
|
+
outputOrigin: 'explicit';
|
|
212
|
+
} | {
|
|
213
|
+
outputOrigin: 'inherited';
|
|
214
|
+
baseDir: string;
|
|
215
|
+
}) & {
|
|
216
|
+
/** Authoritative for all probes. No native retry or missing-method fallback. */
|
|
217
|
+
inspection?: OutputPathInspection;
|
|
218
|
+
signal?: AbortSignal;
|
|
219
|
+
/** Legacy synchronous providers must keep using inspectOutputPath. */
|
|
220
|
+
fs?: never;
|
|
221
|
+
publicationFs?: never;
|
|
222
|
+
};
|
|
223
|
+
declare const nodeOutputPathInspection: OutputPathInspection;
|
|
224
|
+
/**
|
|
225
|
+
* Asynchronous advisory inspection with the same path policy as inspectOutputPath. Cancellation
|
|
226
|
+
* rejects with the signal reason only after an admitted probe settles. Provider errors are mapped
|
|
227
|
+
* like publication errors; an existing ReviewPublishError retains its identity. Final publication
|
|
228
|
+
* still rechecks the path. Legacy synchronous providers cannot supply this asynchronous role.
|
|
229
|
+
*/
|
|
230
|
+
declare function inspectOutputPathAsync(outputPath: string, options: AsyncInspectOutputPathOptions): Promise<ReviewPublishError | null>;
|
|
231
|
+
|
|
232
|
+
interface SourceScanOptions {
|
|
233
|
+
/** Read-only scan and descriptor capability; never falls back to the host filesystem. */
|
|
234
|
+
scanFs?: ScanFsLayer;
|
|
235
|
+
/** Defaults to stderr. Payload diagnostics are retained independently of presentation. */
|
|
236
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
237
|
+
budgets?: Partial<SourceBudgets>;
|
|
238
|
+
/** Rejects with CommandCancelledError, including ordinary Error abort reasons. */
|
|
239
|
+
signal?: AbortSignal;
|
|
240
|
+
}
|
|
241
|
+
interface SourceScanResult {
|
|
242
|
+
files: DiffFile[];
|
|
243
|
+
/** For `DiffLoadPayload.diagnostics`; empty for a clean scan. */
|
|
244
|
+
diagnostics: string[];
|
|
245
|
+
/** `files` is empty when this is true. */
|
|
246
|
+
entryLimitExceeded: boolean;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Recursively scans `directoryPath`; a directory matching `ignorePatterns` is pruned without being
|
|
250
|
+
* opened.
|
|
251
|
+
*/
|
|
252
|
+
declare function scanDirectory(directoryPath: string, ignorePatterns?: string[], options?: SourceScanOptions): Promise<SourceScanResult>;
|
|
253
|
+
/**
|
|
254
|
+
* The reviewer named this path explicitly, so a symlink is read through; the per-file budget still
|
|
255
|
+
* applies.
|
|
256
|
+
*/
|
|
257
|
+
declare function scanFile(filePath: string, options?: SourceScanOptions): Promise<SourceScanResult>;
|
|
258
|
+
|
|
259
|
+
interface ReviewedSnapshot {
|
|
260
|
+
/** Explicit load evidence. A logical identity copy alone has only legacy live semantics. */
|
|
261
|
+
loadedReview?: LoadedReview | null;
|
|
262
|
+
sourceIdentity: ReviewSourceIdentity | null;
|
|
263
|
+
reviewedPaths: ReadonlySet<string>;
|
|
264
|
+
}
|
|
265
|
+
type ReviewedPathRefusal = 'no-source' | 'not-reviewed'
|
|
266
|
+
/** Absolute, empty, or leaving the source root. */
|
|
267
|
+
| 'invalid-path';
|
|
268
|
+
type ReviewedPathAuthorization = {
|
|
269
|
+
ok: true;
|
|
270
|
+
/** Restated from `sourceRoot` through the identity's prefix, normalized. */
|
|
271
|
+
relativePath: string;
|
|
272
|
+
sourceRoot: string;
|
|
273
|
+
} | {
|
|
274
|
+
ok: false;
|
|
275
|
+
reason: ReviewedPathRefusal;
|
|
276
|
+
message: string;
|
|
277
|
+
};
|
|
278
|
+
/** The one path check every front end delegates to; what passes is exactly what the readers open. */
|
|
279
|
+
declare function authorizeReviewedPath(source: ReviewedSnapshot, filePath: string): ReviewedPathAuthorization;
|
|
280
|
+
type SnapshotReadFailure = ReviewedPathRefusal
|
|
281
|
+
/** The side has no content (`none`) or could not be identified (`unknown`). */
|
|
282
|
+
| 'side-unavailable' | 'not-found'
|
|
283
|
+
/** A directory, FIFO, socket or device. */
|
|
284
|
+
| 'not-regular' | 'unsafe-link' | 'too-large' | 'read-failed';
|
|
285
|
+
type SnapshotReadResult = {
|
|
286
|
+
ok: true;
|
|
287
|
+
content: Buffer;
|
|
288
|
+
} | {
|
|
289
|
+
ok: false;
|
|
290
|
+
reason: SnapshotReadFailure;
|
|
291
|
+
message: string;
|
|
292
|
+
};
|
|
293
|
+
interface SnapshotReadOptions {
|
|
294
|
+
/** Defaults to `MAX_SOURCE_FILE_BYTES`. */
|
|
295
|
+
maxBytes?: number;
|
|
296
|
+
/** Aborts git children; a physical read closes its bounded descriptor before rejecting. */
|
|
297
|
+
signal?: AbortSignal;
|
|
298
|
+
timeoutMs?: number;
|
|
299
|
+
runner?: BufferedCommandRunner;
|
|
300
|
+
/** Bounded reader for legacy identities. Captured reads require the load's own reader. */
|
|
301
|
+
readFs?: BoundedAsyncReadFsLayer;
|
|
302
|
+
}
|
|
303
|
+
/** A blob from the object store, or the file under the physical source root; authorized first. */
|
|
304
|
+
declare function readReviewedContent(source: ReviewedSnapshot, filePath: string, side: 'old' | 'new', options?: SnapshotReadOptions): Promise<SnapshotReadResult>;
|
|
305
|
+
/** Read through an original load capability; structural/serialized identities are not accepted. */
|
|
306
|
+
declare function readLoadedReviewContent(loadedReview: LoadedReview, filePath: string, side: 'old' | 'new', options?: SnapshotReadOptions): Promise<SnapshotReadResult>;
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* `project` config is repository data and is trusted less than the reviewer's own `user` config.
|
|
310
|
+
*/
|
|
311
|
+
type ConfigValueOrigin = 'default' | 'user' | 'project';
|
|
312
|
+
type ConfigProvenance = Readonly<Record<keyof AppConfig, ConfigValueOrigin>>;
|
|
313
|
+
interface ConfigSource {
|
|
314
|
+
origin: 'user' | 'project';
|
|
315
|
+
path: string;
|
|
316
|
+
}
|
|
317
|
+
interface LoadedConfig {
|
|
318
|
+
config: AppConfig;
|
|
319
|
+
provenance: ConfigProvenance;
|
|
320
|
+
sources: ConfigSource[];
|
|
321
|
+
}
|
|
322
|
+
/** Synchronous startup effects. A supplied implementation owns every read and location lookup. */
|
|
323
|
+
interface ConfigEffects {
|
|
324
|
+
exists(path: string): boolean;
|
|
325
|
+
read(path: string, maxBytes: number, options: BoundedReadOptions): BoundedReadResult;
|
|
326
|
+
homeDir(): string;
|
|
327
|
+
cwd(): string;
|
|
328
|
+
}
|
|
329
|
+
interface LoadConfigOptions {
|
|
330
|
+
effects?: ConfigEffects;
|
|
331
|
+
cwd?: string;
|
|
332
|
+
homeDir?: string;
|
|
333
|
+
/** Defaults to stderr; supply a callback to collect diagnostics without printing. */
|
|
334
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* Project overrides user overrides defaults; an invalid value is not attributed to its file.
|
|
338
|
+
* The deprecated `output-format` key is retained verbatim for compatibility. Publication always
|
|
339
|
+
* produces XML. Unsupported values warn without rejecting the configuration or changing provenance.
|
|
340
|
+
*/
|
|
341
|
+
declare function loadConfigWithProvenance(options?: LoadConfigOptions): LoadedConfig;
|
|
342
|
+
/** Load merged configuration; `output-format` is deprecated and publication always uses XML. */
|
|
343
|
+
declare function loadConfig(options?: LoadConfigOptions): AppConfig;
|
|
344
|
+
|
|
345
|
+
interface LoadImageOptions {
|
|
346
|
+
signal?: AbortSignal;
|
|
347
|
+
timeoutMs?: number;
|
|
348
|
+
/** Defaults to stderr. Reporter failures never change the read outcome. */
|
|
349
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Reads a reviewed, previewable path. First-party loads pin index blobs and verify physical
|
|
353
|
+
* source evidence; legacy injected identities retain live descriptor reads.
|
|
354
|
+
*/
|
|
355
|
+
declare function loadImage(session: Pick<ReviewSession, 'reviewedPaths' | 'diffData' | 'sourceIdentity' | 'loadedReview'>, filePath: string, options?: LoadImageOptions): Promise<ImageLoadResult>;
|
|
356
|
+
/**
|
|
357
|
+
* Records that resumed attachments live beside the resumed document, whatever the
|
|
358
|
+
* launch directory or save location. Returns one diagnostic per reference that is
|
|
359
|
+
* not `.self-review-assets/<name>` and so will never be read.
|
|
360
|
+
*/
|
|
361
|
+
declare function recordResumedAttachments(session: Pick<ReviewSession, 'attachmentOrigins'>, comments: readonly ReviewComment[], resumeDocumentPath: string, location: ResolvedAttachmentLocation): string[];
|
|
362
|
+
declare function recordResumedAttachments(session: Pick<ReviewSession, 'attachmentOrigins'>, comments: readonly ReviewComment[], resumeDocumentPath: string): string[];
|
|
363
|
+
/** Authorized asset reads only. Implementations enforce no-follow, regular-file and byte limits. */
|
|
364
|
+
interface AttachmentReader {
|
|
365
|
+
readAssetFile(assetPath: string, options: {
|
|
366
|
+
signal?: AbortSignal;
|
|
367
|
+
}): Promise<AttachmentReadResult>;
|
|
368
|
+
}
|
|
369
|
+
interface ReadAttachmentOptions {
|
|
370
|
+
signal?: AbortSignal;
|
|
371
|
+
/** Authoritative when supplied. Failures never retry through the native reader. */
|
|
372
|
+
attachmentReader?: AttachmentReader;
|
|
373
|
+
/** Defaults to stderr. Throwing or rejecting reporters cannot change the read outcome. */
|
|
374
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Read one attachment by its `.self-review-assets/<name>` reference, never a path:
|
|
378
|
+
* an imported one from its recorded origin, any other from the current output's asset
|
|
379
|
+
* directory. Anything else is `not-authorized` and touches nothing.
|
|
380
|
+
*/
|
|
381
|
+
declare function readAttachment(session: Pick<ReviewSession, 'outputPathInfo' | 'attachmentOrigins'>, reference: unknown, options?: ReadAttachmentOptions): Promise<AttachmentReadResult>;
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* What a review start produced: the payload built from the scanned path, the
|
|
385
|
+
* stats it was measured against (null when the session has no config, in which
|
|
386
|
+
* case no thresholds apply), and whether those stats exceeded a threshold.
|
|
387
|
+
*
|
|
388
|
+
* The payload is deliberately *not* stored on the session: the caller may still
|
|
389
|
+
* need to abandon it (a user declining a large review keeps the review they
|
|
390
|
+
* were already looking at), so committing it is the caller's decision.
|
|
391
|
+
*/
|
|
392
|
+
interface ReviewStartResult {
|
|
393
|
+
payload: DiffLoadPayload;
|
|
394
|
+
identity: ReviewSourceIdentity;
|
|
395
|
+
/** Host-local evidence to pass to commitLoadedReview. Never put this on a wire payload. */
|
|
396
|
+
loadedReview?: LoadedReview;
|
|
397
|
+
stats: PayloadStats | null;
|
|
398
|
+
exceedsThresholds: boolean;
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Scan a picked path and build the diff payload for a directory (or single
|
|
402
|
+
* file) review, measured against the session's large-payload thresholds.
|
|
403
|
+
* Nothing is stored on the session — see `ReviewStartResult`.
|
|
404
|
+
*/
|
|
405
|
+
declare function prepareDirectoryReview(session: Pick<ReviewSession, 'config'>, directoryPath: string, options?: SourceScanOptions): Promise<ReviewStartResult>;
|
|
406
|
+
/**
|
|
407
|
+
* Commit a prepared review payload to the session, once the caller has decided
|
|
408
|
+
* it should proceed. Returns the payload to hand to the transport.
|
|
409
|
+
*/
|
|
410
|
+
declare function commitReviewStart(session: Pick<ReviewSession, 'diffData' | 'reviewedPaths' | 'sourceIdentity' | 'loadedReview'>, payload: DiffLoadPayload, identity: ReviewSourceIdentity | null, loadedReview?: LoadedReview | undefined): DiffLoadPayload;
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* What a review starts from; `welcome` means nothing to review (desktop shows its picker, serve
|
|
414
|
+
* refuses).
|
|
415
|
+
*/
|
|
416
|
+
type StartupSource = {
|
|
417
|
+
mode: 'git';
|
|
418
|
+
} | {
|
|
419
|
+
mode: 'directory';
|
|
420
|
+
sourcePath: string;
|
|
421
|
+
} | {
|
|
422
|
+
mode: 'file';
|
|
423
|
+
sourcePath: string;
|
|
424
|
+
} | {
|
|
425
|
+
mode: 'welcome';
|
|
426
|
+
};
|
|
427
|
+
/**
|
|
428
|
+
* The candidate is the first *positional* by the shared classifier, so `-S src/x.ts` never selects
|
|
429
|
+
* a file.
|
|
430
|
+
*/
|
|
431
|
+
declare function resolveStartupSource(gitDiffArgs: readonly string[], cwd?: string): StartupSource;
|
|
432
|
+
/** The mode alone; see {@link resolveStartupSource} for the source path. */
|
|
433
|
+
declare function determineMode(gitDiffArgs: string[]): 'git' | 'directory' | 'file' | 'welcome';
|
|
434
|
+
/** Classification metadata only; content loading uses its own filesystem roles. */
|
|
435
|
+
interface StartupPathStats {
|
|
436
|
+
isFile(): boolean;
|
|
437
|
+
isDirectory(): boolean;
|
|
438
|
+
}
|
|
439
|
+
/** An authoritative path probe. A refusal or failure never retries against the native filesystem. */
|
|
440
|
+
interface StartupPathProbe {
|
|
441
|
+
stat(path: string): Promise<StartupPathStats | null>;
|
|
442
|
+
}
|
|
443
|
+
interface StartupSourceOptions extends GitExecutionOptions {
|
|
444
|
+
sourceProbe?: StartupPathProbe;
|
|
445
|
+
}
|
|
446
|
+
/**
|
|
447
|
+
* Nonblocking startup probes for hosts. Commands use the shared bounded runner and its
|
|
448
|
+
* explicit-repository environment, including a deliberately selected local alternate index.
|
|
449
|
+
* Abort and timeout reject with CommandCancelledError; ordinary probe failures keep the
|
|
450
|
+
* synchronous API's file/directory/welcome fallback. timeoutMs bounds each command.
|
|
451
|
+
* sourceProbe supplies classification metadata only and retains its receiver. Native stat and
|
|
452
|
+
* supplied probes are joined before cancellation propagates; neither can be forcibly preempted.
|
|
453
|
+
*/
|
|
454
|
+
declare function resolveStartupSourceAsync(gitDiffArgs: readonly string[], cwd?: string, options?: StartupSourceOptions): Promise<StartupSource>;
|
|
455
|
+
|
|
456
|
+
interface LoadGitDiffOptions extends GitExecutionOptions {
|
|
457
|
+
/** Supplied bounded source reads, including untracked additions. */
|
|
458
|
+
readFs?: SourceReadFsLayer;
|
|
459
|
+
sourcePaths?: LocalSourcePaths;
|
|
460
|
+
/**
|
|
461
|
+
* Include untracked working-tree files as synthetic additions. Defaults
|
|
462
|
+
* to true (local git mode). Remote mode passes false: a base...head diff
|
|
463
|
+
* of a PR/MR must never pick up unrelated local untracked files.
|
|
464
|
+
*/
|
|
465
|
+
includeUntracked?: boolean;
|
|
466
|
+
budgets?: Partial<SourceBudgets>;
|
|
467
|
+
/** Effective application ignore filter, in the same namespace as tracked diff paths. */
|
|
468
|
+
shouldKeep?: (path: string) => boolean;
|
|
469
|
+
}
|
|
470
|
+
interface LoadGitDiffResult {
|
|
471
|
+
files: DiffFile[];
|
|
472
|
+
repository: string;
|
|
473
|
+
/** What the diff compared; previews and line counts read this snapshot, not the working tree. */
|
|
474
|
+
identity: ReviewSourceIdentity;
|
|
475
|
+
/** What could not be shown faithfully; front ends show these instead of "no changes". */
|
|
476
|
+
diagnostics: string[];
|
|
477
|
+
}
|
|
478
|
+
/**
|
|
479
|
+
* Tracked wins on a path collision (after `git rm --cached f`, `f` is both a
|
|
480
|
+
* deletion and untracked); two entries would share React keys and comment state.
|
|
481
|
+
*/
|
|
482
|
+
declare function dedupeUntrackedByPath(tracked: DiffFile[], untracked: DiffFile[]): DiffFile[];
|
|
483
|
+
declare function loadGitDiffWithUntracked(gitDiffArgs: string[], cwd?: string, options?: LoadGitDiffOptions): Promise<LoadGitDiffResult>;
|
|
484
|
+
|
|
485
|
+
/** Source loading and later physical reads must belong to the same supplied filesystem. */
|
|
486
|
+
interface GitSnapshotDependencies {
|
|
487
|
+
readonly readFs: BoundedAsyncReadFsLayer;
|
|
488
|
+
/** Needed when the standard diff loader also reads untracked source/link content. */
|
|
489
|
+
readonly sourceFs?: SourceReadFsLayer;
|
|
490
|
+
loadDiff: typeof loadGitDiffWithUntracked;
|
|
491
|
+
}
|
|
492
|
+
/**
|
|
493
|
+
* Stronger loader for hosts; the original loadGitDiffWithUntracked call form stays live for legacy
|
|
494
|
+
* embedders. Mutable paths are inspected before diff execution, never first captured afterward.
|
|
495
|
+
*/
|
|
496
|
+
declare function loadGitReviewSnapshot(args: string[], cwd?: string, options?: LoadGitDiffOptions & {
|
|
497
|
+
snapshotRunner?: BufferedCommandRunner;
|
|
498
|
+
}, dependencies?: GitSnapshotDependencies): Promise<LoadGitDiffResult & {
|
|
499
|
+
loadedReview?: LoadedReview;
|
|
500
|
+
}>;
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* A CLI path or the reviewer's user-level `output-file` is explicit and may point anywhere.
|
|
504
|
+
* Project `output-file` or the default is inherited and contained under `cwd`, since a
|
|
505
|
+
* repository could otherwise redirect the save (audit A5).
|
|
506
|
+
*/
|
|
507
|
+
declare function resolveOutputTarget(explicitPath: string | null, loaded: LoadedConfig, cwd: string): ReviewOutputTarget;
|
|
508
|
+
declare function publishOptionsFor(target: ReviewOutputTarget, attachmentOrigins?: AttachmentOrigins): PublishReviewOptions;
|
|
509
|
+
/**
|
|
510
|
+
* Project `default-diff-args` would make git write a file or run a program; thrown before any git
|
|
511
|
+
* command.
|
|
512
|
+
*/
|
|
513
|
+
declare class ConfiguredDiffArgsError extends Error {
|
|
514
|
+
readonly options: readonly string[];
|
|
515
|
+
readonly configPath: string;
|
|
516
|
+
constructor(options: readonly string[], configPath: string);
|
|
517
|
+
}
|
|
518
|
+
interface ResolvedDiffArgs {
|
|
519
|
+
gitDiffArgs: string[];
|
|
520
|
+
origin: 'cli' | ConfigValueOrigin;
|
|
521
|
+
config: AppConfig;
|
|
522
|
+
}
|
|
523
|
+
/**
|
|
524
|
+
* The CLI's arguments, else `default-diff-args` split with shell quoting. Project-supplied
|
|
525
|
+
* ones are refused with {@link ConfiguredDiffArgsError} if write-capable; the
|
|
526
|
+
* reviewer's own are not.
|
|
527
|
+
*/
|
|
528
|
+
declare function resolveStartupDiffArgs(cliGitDiffArgs: readonly string[], loaded: LoadedConfig, cwd: string): ResolvedDiffArgs;
|
|
529
|
+
interface LoadedLocalReview {
|
|
530
|
+
payload: DiffLoadPayload;
|
|
531
|
+
identity: ReviewSourceIdentity | null;
|
|
532
|
+
/** Host-local capture; optional so original injected loaders remain source compatible. */
|
|
533
|
+
loadedReview?: LoadedReview | null;
|
|
534
|
+
}
|
|
535
|
+
/** Local source effects. A supplied scan owns paths, enumeration and bounded reads together. */
|
|
536
|
+
interface LocalReviewDependencies {
|
|
537
|
+
scanFs?: ScanFsLayer;
|
|
538
|
+
gitSnapshot?: GitSnapshotDependencies;
|
|
539
|
+
}
|
|
540
|
+
interface LocalReviewLoadOptions extends LoadGitDiffOptions {
|
|
541
|
+
/** Binary blob runner belonging to a supplied Git source. */
|
|
542
|
+
snapshotRunner?: BufferedCommandRunner;
|
|
543
|
+
}
|
|
544
|
+
/**
|
|
545
|
+
* Diagnostics ride on the payload and go to `log`, so a failed load never reads as empty. A welcome
|
|
546
|
+
* source yields no identity.
|
|
547
|
+
*/
|
|
548
|
+
declare function loadLocalReview(source: StartupSource, gitDiffArgs: readonly string[], config: Pick<AppConfig, 'ignore'>, cwd: string, log: (message: string) => void, options?: LocalReviewLoadOptions, dependencies?: LocalReviewDependencies): Promise<LoadedLocalReview>;
|
|
549
|
+
/**
|
|
550
|
+
* Throws `ReviewXmlError` for an unreadable document. Returns it for what the host still needs (the
|
|
551
|
+
* remote head, for drift).
|
|
552
|
+
*/
|
|
553
|
+
interface ResumeDocumentOptions extends ResolvedAttachmentLocation {
|
|
554
|
+
reader?: ReviewXmlReader;
|
|
555
|
+
signal?: AbortSignal;
|
|
556
|
+
}
|
|
557
|
+
declare function loadResumeDocument(session: ReviewSession, resumePath: string, options: ResumeDocumentOptions): ParsedReview;
|
|
558
|
+
declare function loadResumeDocument(session: ReviewSession, resumePath: string): ParsedReview;
|
|
559
|
+
/** Adopt an already parsed document, retaining the same attachment provenance as sync loading. */
|
|
560
|
+
declare function adoptResumeDocument(session: ReviewSession, parsed: ParsedReview, resumePath: string, options: ResolvedAttachmentLocation & {
|
|
561
|
+
signal?: AbortSignal;
|
|
562
|
+
}): ParsedReview;
|
|
563
|
+
declare function adoptResumeDocument(session: ReviewSession, parsed: ParsedReview, resumePath: string): ParsedReview;
|
|
564
|
+
|
|
565
|
+
/**
|
|
566
|
+
* Derive the guide sidecar path from the resolved output path: strip the
|
|
567
|
+
* last extension and append `.guide.xml` (`review.xml` →
|
|
568
|
+
* `review.guide.xml`). An output filename with no extension gets
|
|
569
|
+
* `.guide.xml` appended verbatim.
|
|
570
|
+
*/
|
|
571
|
+
declare function deriveGuidePath(outputPath: string): string;
|
|
572
|
+
/**
|
|
573
|
+
* Resolve where to look for the guide: the `guide-file` config override
|
|
574
|
+
* (resolved against cwd, like `output-file`) when set, otherwise the path
|
|
575
|
+
* derived from the resolved output path.
|
|
576
|
+
*/
|
|
577
|
+
declare function resolveGuidePath(outputPath: string, config: Pick<AppConfig, 'guideFile'>, cwd?: string): string;
|
|
578
|
+
/**
|
|
579
|
+
* Owns bounded guide reads, including regular-file checks, growth detection and handle cleanup.
|
|
580
|
+
* Must reject filesystem errors with Node-style errno codes and settle after cleanup on abort.
|
|
581
|
+
* Methods retain their receiver. A supplied reader is authoritative; native I/O is never retried.
|
|
582
|
+
*/
|
|
583
|
+
interface BoundedGuideReader {
|
|
584
|
+
read(path: string, maxBytes: number, options?: AsyncBoundedReadOptions): Promise<BoundedReadResult>;
|
|
585
|
+
}
|
|
586
|
+
interface LoadGuideOptions {
|
|
587
|
+
/** Defaults to the native bounded reader. The caller owns the reader; it owns opened handles. */
|
|
588
|
+
reader?: BoundedGuideReader;
|
|
589
|
+
/** Resolution directory for a relative guide-file. Defaults to process.cwd(). */
|
|
590
|
+
cwd?: string;
|
|
591
|
+
/** Defaults to stderr; missing guides are always silent. */
|
|
592
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
593
|
+
/** Cancels bounded reading and refuses obsolete validation; shared validation is not preempted. */
|
|
594
|
+
signal?: AbortSignal;
|
|
595
|
+
}
|
|
596
|
+
/**
|
|
597
|
+
* Discover, read, parse, validate, and reconcile the guide sidecar.
|
|
598
|
+
*
|
|
599
|
+
* Returns the display-ready payload, or null when there is no usable
|
|
600
|
+
* guide. Missing file: silent. Unreadable or invalid file: exactly one
|
|
601
|
+
* `reportDiagnostic()` line (guide path + reason class). An explicitly supplied
|
|
602
|
+
* startup signal propagates cancellation; ordinary guide failures never throw.
|
|
603
|
+
*/
|
|
604
|
+
declare function loadGuide(outputPath: string, config: Pick<AppConfig, 'guideFile'>, diffFilePaths: string[], options?: LoadGuideOptions): Promise<GuideLoadPayload | null>;
|
|
605
|
+
|
|
606
|
+
/**
|
|
607
|
+
* The git-mode inputs plus the forge threads, before any diff is loaded (so nothing to anchor
|
|
608
|
+
* suggestions to yet).
|
|
609
|
+
*/
|
|
610
|
+
interface MaterializedRemoteSession {
|
|
611
|
+
forgeUrl: ForgeUrl;
|
|
612
|
+
/** Root of the materialized clone; the pipeline's repo path. */
|
|
613
|
+
repoPath: string;
|
|
614
|
+
/** Arguments for the existing git-diff machinery: `[base...head]`. */
|
|
615
|
+
gitDiffArgs: string[];
|
|
616
|
+
mode: MaterializeMode;
|
|
617
|
+
/** Idempotent, never rejects; the receiver of the session must call it. */
|
|
618
|
+
cleanup: () => Promise<void>;
|
|
619
|
+
/** Legacy synchronous-first removal, for an exit handler that cannot await normal disposal. */
|
|
620
|
+
cleanupForExit?: () => Promise<void>;
|
|
621
|
+
/** Provenance + thread-sync status for payloads and the saved review. */
|
|
622
|
+
remote: RemoteSessionInfo;
|
|
623
|
+
/** Verbatim; empty when thread sync is unavailable. */
|
|
624
|
+
fetchedThreads: ForgeThread[];
|
|
625
|
+
}
|
|
626
|
+
/** A session whose diff is loaded and whose threads are mapped against it. */
|
|
627
|
+
interface RemoteSession extends MaterializedRemoteSession {
|
|
628
|
+
/** Review-level threads keep the sentinel `filePath: ''` (REVIEW_LEVEL_FILE_PATH). */
|
|
629
|
+
fetchedComments: ReviewComment[];
|
|
630
|
+
}
|
|
631
|
+
/** Injectable seams; defaults are the real core APIs. */
|
|
632
|
+
interface RemoteSessionDeps {
|
|
633
|
+
createProvider: (forge: ForgeName, runner: ForgeCommandRunner) => ForgeProvider;
|
|
634
|
+
materialize: (url: ForgeUrl, baseBranch: string, cwd: string, runner: ForgeCommandRunner, existingClone?: ExistingClone | null, options?: MaterializeOptions) => Promise<MaterializeResult>;
|
|
635
|
+
detectExistingClone: (url: ForgeUrl, cwd: string, runner: ForgeCommandRunner, options?: MaterializeOptions) => Promise<ExistingClone | null>;
|
|
636
|
+
resolveRemoteDefaultBranch: (url: ForgeUrl, runner: ForgeCommandRunner, existing?: ExistingClone | null, options?: MaterializeOptions) => Promise<string>;
|
|
637
|
+
runner: ForgeCommandRunner;
|
|
638
|
+
/** Untracked files are never included. A stand-in may omit `diagnostics` and `identity`. */
|
|
639
|
+
loadDiff: (gitDiffArgs: string[], cwd: string, options?: RemoteLifetimeOptions) => Promise<{
|
|
640
|
+
files: DiffFile[];
|
|
641
|
+
repository: string;
|
|
642
|
+
diagnostics?: string[];
|
|
643
|
+
identity?: ReviewSourceIdentity;
|
|
644
|
+
}>;
|
|
645
|
+
}
|
|
646
|
+
declare const defaultRemoteSessionDeps: RemoteSessionDeps;
|
|
647
|
+
interface RemoteLifetimeOptions {
|
|
648
|
+
/** Defaults to stderr, with the existing remote diagnostic text and call form. */
|
|
649
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
650
|
+
/** Passed unchanged to materialization; no host storage is used when supplied. */
|
|
651
|
+
temporaryClones?: MaterializeOptions['temporaryClones'];
|
|
652
|
+
/** Without one, the session is bounded only by the per-command timeout. */
|
|
653
|
+
signal?: AbortSignal;
|
|
654
|
+
}
|
|
655
|
+
interface StartRemoteSessionOptions extends RemoteLifetimeOptions {
|
|
656
|
+
includeResolved?: boolean;
|
|
657
|
+
/**
|
|
658
|
+
* `'optional'` (default, the app): a failed fetch degrades to no threads.
|
|
659
|
+
* `'required'` (`fetch-comments`): always attempted, and a failure is fatal.
|
|
660
|
+
*/
|
|
661
|
+
threads?: 'optional' | 'required';
|
|
662
|
+
}
|
|
663
|
+
/**
|
|
664
|
+
* Materialize a forge PR/MR URL into a local git context and fetch its
|
|
665
|
+
* discussion threads.
|
|
666
|
+
*
|
|
667
|
+
* Fatal failures (unrecognizable URL, materialization errors, base-branch
|
|
668
|
+
* lookup failures other than a missing CLI) throw — callers surface them
|
|
669
|
+
* like any other startup git error. Forge-CLI unavailability is never
|
|
670
|
+
* fatal for the base branch (git-only fallback); for threads see
|
|
671
|
+
* {@link StartRemoteSessionOptions.threads}.
|
|
672
|
+
*/
|
|
673
|
+
declare function startRemoteSession(url: string, cwd: string, deps?: Partial<RemoteSessionDeps>, options?: StartRemoteSessionOptions): Promise<MaterializedRemoteSession>;
|
|
674
|
+
interface RemoteReviewLoad {
|
|
675
|
+
/** After the ignore configuration. */
|
|
676
|
+
files: DiffFile[];
|
|
677
|
+
repository: string;
|
|
678
|
+
diagnostics: string[];
|
|
679
|
+
/** `session.fetchedThreads` mapped against `files` and the materialized head. */
|
|
680
|
+
comments: ReviewComment[];
|
|
681
|
+
identity?: ReviewSourceIdentity;
|
|
682
|
+
}
|
|
683
|
+
/**
|
|
684
|
+
* Load the diff, apply the ignore configuration and map the threads: the one place
|
|
685
|
+
* this happens, so the app and `fetch-comments` cannot drift. Mapping against the
|
|
686
|
+
* filtered files and the materialized head keeps a suggestion on an ignored path
|
|
687
|
+
* or another head plain text (R05). Does not release the session on failure. An
|
|
688
|
+
* abort during the load discards the result and throws.
|
|
689
|
+
*/
|
|
690
|
+
declare function loadRemoteReview(session: MaterializedRemoteSession, ignorePatterns: string[], loadDiff?: RemoteSessionDeps['loadDiff'], options?: RemoteLifetimeOptions): Promise<RemoteReviewLoad>;
|
|
691
|
+
/** A remote session plus the ready-to-send git-mode diff payload. */
|
|
692
|
+
interface RemoteBootstrapResult {
|
|
693
|
+
session: RemoteSession;
|
|
694
|
+
payload: DiffLoadPayload;
|
|
695
|
+
identity: ReviewSourceIdentity;
|
|
696
|
+
}
|
|
697
|
+
/**
|
|
698
|
+
* Full remote bootstrap for the app: materialize, {@link loadRemoteReview}, and shape
|
|
699
|
+
* the git-mode `DiffLoadPayload`. Thread sync degrades rather than failing.
|
|
700
|
+
*/
|
|
701
|
+
declare function bootstrapRemoteDiff(url: string, cwd: string, ignorePatterns: string[], deps?: Partial<RemoteSessionDeps>, options?: RemoteLifetimeOptions): Promise<RemoteBootstrapResult>;
|
|
702
|
+
|
|
703
|
+
/** Injectable seams: the app's remote-session seams plus this subcommand's output. */
|
|
704
|
+
interface FetchCommentsDeps extends RemoteSessionDeps {
|
|
705
|
+
publish: (state: ReviewState, outputPath: string, options: PublishReviewOptions) => Promise<PublishReviewResult>;
|
|
706
|
+
loadConfig: (options?: LoadConfigOptions) => LoadedConfig;
|
|
707
|
+
now: () => Date;
|
|
708
|
+
}
|
|
709
|
+
interface BuildRemoteReviewStateArgs {
|
|
710
|
+
remoteUrl: string;
|
|
711
|
+
forge: RemoteForge;
|
|
712
|
+
baseSha: string;
|
|
713
|
+
headSha: string;
|
|
714
|
+
diffFiles: DiffFile[];
|
|
715
|
+
comments: ReviewComment[];
|
|
716
|
+
timestamp: string;
|
|
717
|
+
}
|
|
718
|
+
/**
|
|
719
|
+
* Assemble the ReviewState for a fetched remote review. Pure and
|
|
720
|
+
* deterministic: same inputs, same state.
|
|
721
|
+
*
|
|
722
|
+
* Placement rules:
|
|
723
|
+
* - Every diff file gets a file entry in diff order; fetched threads land on
|
|
724
|
+
* their files, in thread order.
|
|
725
|
+
* - Comments whose path is not in the diff (e.g. outdated anchors on files
|
|
726
|
+
* no longer touched) get a synthetic entry with change-type "modified" —
|
|
727
|
+
* the schema requires the attribute and "modified" is the least-claiming
|
|
728
|
+
* value for a file we cannot classify.
|
|
729
|
+
* - Review-level threads (sentinel {@link REVIEW_LEVEL_FILE_PATH}) are
|
|
730
|
+
* folded into a single trailing file entry with the sentinel path: the v3
|
|
731
|
+
* schema requires every <comment> inside a <file path>, and the empty
|
|
732
|
+
* path can never collide with a real diff path, so consumers detect these
|
|
733
|
+
* by comparing against the constant. Omitted when there are none.
|
|
734
|
+
* - Every file is viewed="false": fetch-comments reviews nothing, and a
|
|
735
|
+
* viewed mark claims a human looked at the file. A subsequent
|
|
736
|
+
* --resume-from session therefore starts with the full file list pending.
|
|
737
|
+
* - `source` is `{ type: 'welcome' }`: the remote-* root attributes are the
|
|
738
|
+
* review's source shape, and the three shapes (git, directory, remote)
|
|
739
|
+
* are mutually exclusive by contract, so no local source attributes are
|
|
740
|
+
* serialized.
|
|
741
|
+
*/
|
|
742
|
+
declare function buildRemoteReviewState(args: BuildRemoteReviewStateArgs): ReviewState;
|
|
743
|
+
interface FetchCommentsOptions extends RemoteLifetimeOptions {
|
|
744
|
+
/** Include threads the forge marks resolved (GitLab). Default false. */
|
|
745
|
+
includeResolved?: boolean;
|
|
746
|
+
/** Working directory for clone detection and output resolution. */
|
|
747
|
+
cwd?: string;
|
|
748
|
+
/** Test seams; every omitted member falls back to the real default. */
|
|
749
|
+
deps?: Partial<FetchCommentsDeps>;
|
|
750
|
+
}
|
|
751
|
+
/**
|
|
752
|
+
* Run the headless fetch-comments flow end to end. Throws on any failure
|
|
753
|
+
* (the caller prints the message to stderr and exits 1); the temporary
|
|
754
|
+
* clone, when one was created, is removed on both success and failure, and
|
|
755
|
+
* the removal has completed by the time the promise settles.
|
|
756
|
+
*
|
|
757
|
+
* A supplied reportDiagnostic owns progress, configuration, loading and materialization diagnostics.
|
|
758
|
+
* Errors still reject for the host to present. Reporters must not throw.
|
|
759
|
+
*
|
|
760
|
+
* Fetching comments is the whole point, so threads run under the `'required'`
|
|
761
|
+
* policy: an unavailable forge CLI is an error, not a degraded review.
|
|
762
|
+
*/
|
|
763
|
+
declare function runFetchComments(url: string, options?: FetchCommentsOptions): Promise<void>;
|
|
764
|
+
|
|
765
|
+
export { buildRemoteReviewState as $, type ReviewOutputTarget as A, type BoundedReadOptions as B, type ConfigProvenance as C, DEFAULT_GIT_COMMAND_TIMEOUT_MS as D, type ExistingClone as E, type FetchCommentsDeps as F, type GitSnapshotDependencies as G, ReviewPublishError as H, type ReviewPublishErrorCode as I, type ReviewStartResult as J, type ReviewedPathAuthorization as K, type LoadConfigOptions as L, type MaterializeMode as M, type ReviewedPathRefusal as N, type ReviewedSnapshot as O, type PublishReviewOptions as P, type SnapshotReadOptions as Q, type ReviewSchemaValidator as R, type SnapshotReadFailure as S, type SnapshotReadResult as T, type SourceScanOptions as U, type SourceScanResult as V, type StartRemoteSessionOptions as W, type StartupSource as X, adoptResumeDocument as Y, authorizeReviewedPath as Z, bootstrapRemoteDiff as _, type ReviewXmlReader as a, commitReviewStart as a0, dedupeUntrackedByPath as a1, defaultGitRunner as a2, defaultRemoteSessionDeps as a3, deriveGuidePath as a4, detectExistingClone as a5, determineMode as a6, inspectOutputPath as a7, loadConfig as a8, loadConfigWithProvenance as a9, startRemoteSession as aA, type AsyncInspectOutputPathOptions as aB, type AttachmentReader as aC, type BoundedGuideReader as aD, type LoadImageOptions as aE, type OutputPathInspection as aF, type ReadAttachmentOptions as aG, type ResumeDocumentOptions as aH, type StartupPathProbe as aI, type StartupPathStats as aJ, type StartupSourceOptions as aK, inspectOutputPathAsync as aL, nodeOutputPathInspection as aM, resolveAttachmentOriginsAtDirectory as aN, loadGitDiffWithUntracked as aa, loadGitReviewSnapshot as ab, loadGuide as ac, loadImage as ad, loadLocalReview as ae, loadRemoteReview as af, loadResumeDocument as ag, materialize as ah, parseAttachmentReference as ai, prepareDirectoryReview as aj, publishOptionsFor as ak, publishReview as al, readAttachment as am, readFileWithinBudget as an, readFileWithinBudgetSync as ao, readLoadedReviewContent as ap, recordResumedAttachments as aq, resolveGuidePath as ar, resolveOutputTarget as as, resolveRemoteDefaultBranch as at, resolveStartupDiffArgs as au, resolveStartupSource as av, resolveStartupSourceAsync as aw, runFetchComments as ax, scanDirectory as ay, scanFile as az, type BoundedReadResult as b, type BuildRemoteReviewStateArgs as c, type ConfigSource as d, type ConfigValueOrigin as e, ConfiguredDiffArgsError as f, type FetchCommentsOptions as g, type LoadGitDiffOptions as h, type LoadGitDiffResult as i, type LoadGuideOptions as j, type LoadedConfig as k, type LoadedLocalReview as l, type LocalReviewDependencies as m, type LocalReviewLoadOptions as n, type MaterializeOptions as o, type MaterializeResult as p, type MaterializedRemoteSession as q, readReviewedContent as r, type PublishReviewResult as s, type RemoteBootstrapResult as t, type RemoteLifetimeOptions as u, type RemoteReviewLoad as v, type RemoteSession as w, type RemoteSessionDeps as x, type ResolvedDiffArgs as y, type ReviewOutputOrigin as z };
|