@self-review/core 2.0.3 → 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
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,19 @@
|
|
|
1
|
-
import { DiffFile, ReviewState,
|
|
1
|
+
import { DiffFile, ReviewState, LineRange, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats, ReviewComment, ExpandContextRequest, DiffHunk, RemoteSessionInfo, RemoteDriftInfo } from '@self-review/types';
|
|
2
2
|
export { AppConfig, ApplyDestinationOutcome, 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, ReviewSourceIdentity, ReviewSourceMode, ReviewSourceSide, ReviewState, Suggestion, SuggestionApplyOutcome, SuggestionApplyRequest, VersionUpdateInfo } from '@self-review/types';
|
|
3
|
-
import
|
|
4
|
-
|
|
3
|
+
import { O as SourceBudgets, Q as DiagnosticReporter, R as GitExecutionOptions, F as FsLayer, U as ForgeCommandRunner, V as ForgeProvider, X as ForgeThread, Y as ReviewSession } from './source-identity-CQpAzugz.cjs';
|
|
4
|
+
export { a as ApplyDestinationInspection, Z as ApplyRefusalReason, _ as ApplySuggestionApplied, $ as ApplySuggestionAsyncOptions, a0 as ApplySuggestionForSessionAsyncOptions, a1 as ApplySuggestionOptions, a2 as ApplySuggestionRefused, a3 as ApplySuggestionRequest, a4 as ApplySuggestionResult, b as AsyncFileHandle, A as AsyncFsLayer, c as AsyncReadFsLayer, d as AsyncReadHandle, a5 as AsyncSyntheticDiffOptions, e as AtomicReplaceAsyncOptions, f as AtomicReplaceOptions, g as AtomicReplaceResult, a6 as AttachmentOrigins, a7 as AttachmentReadFailureReason, a8 as AttachmentReadOptions, a9 as AttachmentReadResult, aa as AttachmentRelocationError, ab as BINARY_SNIFF_BYTES, B as BoundedAsyncReadFsLayer, ac as CommandCancelReason, ad as CommandCancelledError, ae as DEFAULT_SOURCE_BUDGETS, af as FetchThreadsOptions, h as FileIdentity, ag as ForgeAnchorSide, ah as ForgeCliUnavailableError, ai as ForgeCommandOptions, aj as ForgeCommandResult, ak as ForgeName, al as ForgeThreadAnchor, am as ForgeThreadTurn, an as ForgeUrl, ao as GitCommandError, ap as GitDiffSideSpec, aq as GitDiffSides, ar as GitSourceIdentityOptions, as as LoadedReview, at as LocalSourceIdentityOptions, L as LocalSourcePaths, au as MAX_DIFF_DIAGNOSTICS, av as MAX_DIFF_DIAGNOSTIC_CHARS, aw as MAX_DIFF_FILES, ax as MAX_DIFF_HUNKS, ay as MAX_GIT_DIFF_OUTPUT_BYTES, az as MAX_GUIDE_BYTES, aA as MAX_IMAGE_BYTES, aB as MAX_PUBLICATION_ASSET_BYTES, aC as MAX_RESUME_ATTACHMENTS, aD as MAX_RESUME_XML_BYTES, aE as MAX_REVIEW_ATTACHMENTS, aF as MAX_SOURCE_ENTRIES, aG as MAX_SOURCE_FILE_BYTES, aH as MAX_SOURCE_FILE_LINES, aI as MAX_SOURCE_TOTAL_BYTES, aJ as MAX_SOURCE_TOTAL_LINES, aK as PARSER_COMPATIBLE_DIFF_FLAGS, aL as PARSER_COMPATIBLE_GIT_CONFIG, P as PublicationFileSystem, i as PublicationInspection, j as SafeFsError, k as SafeFsErrorCode, l as ScanDirectoryHandle, m as ScanEntry, S as ScanFsLayer, n as SourceReadFsLayer, aM as SuggestionOperationOptions, o as SyncReadFsLayer, aN as SyntheticDiffOptions, aO as SyntheticDiffResult, T as TemporaryCloneStorage, W as WriteExclusiveOptions, aP as applySuggestion, aQ as applySuggestionAsync, aR as applySuggestionForSession, aS as applySuggestionForSessionAsync, p as assertNoSymlinkAncestors, q as atomicReplace, r as atomicReplaceAsync, aT as authorizeAttachmentReference, s as boundedReadFsFromSync, aU as canonicalSourcePath, t as classifyFsError, aV as commitDiffData, aW as commitLoadedReview, aX as createReviewSession, aY as describeGitDiffSides, aZ as formatBytes, a_ as generateSyntheticDiffs, a$ as generateSyntheticDiffsAsync, b0 as generateUntrackedDiffs, b1 as getConfigLoad, b2 as getDiffLoad, b3 as getFileHunks, b4 as getRepoRootAsync, b5 as getResumeLoad, b6 as getUntrackedFilesAsync, u as inspectReplaceTarget, b7 as isCommandCancelled, b8 as isRepositoryControlPath, b9 as loadSyntheticFiles, ba as loadSyntheticFilesAsync, bb as loadedReviewIdentity, bc as loadedReviewPaths, bd as locateReviewedFile, v as nodeApplyDestinationInspection, w as nodeAsyncFsLayer, x as nodeFsLayer, y as nodePublicationFileSystem, z as nodeReadFsLayer, C as nodeTemporaryCloneStorage, be as parseForgeUrl, bf as preparePayload, bg as readAssetFile, I as readContainedFileBounded, bh as relocateAttachments, bi as resolveApplyDestination, bj as resolveAttachmentOrigins, bk as resolveGitSourceIdentity, bl as resolveLocalSourceIdentity, bm as resolveLocalSourceIdentityAsync, bn as resolveReviewedPathPrefix, bo as resolveSourceBaseDir, bp as resolveSourceBudgets, bq as rootRelativeReviewedPath, br as runGitDiffAsync, J as sameFile, K as snapshotIdentity, bs as submitReviewState, bt as takeReviewState, bu as withParserCompatibleDiffArgs, M as writeExclusiveNoFollow } from './source-identity-CQpAzugz.cjs';
|
|
5
|
+
export { M as MAX_CONTEXT_LINES, a as RequestDecodeResult, R as ReviewXmlError, b as ReviewXmlErrorCode, X as XmlIllegalCharacterError, c as XmlIllegalCharacterLocation, d as decodeSuggestionApplyRequest, v as validateReviewState } from './review-request-validation-VJG7XZiE.cjs';
|
|
6
|
+
import { R as ReviewSchemaValidator, a as ReviewXmlReader, r as readReviewedContent } from './operations-UyiUD2Nx.cjs';
|
|
7
|
+
export { B as BoundedReadOptions, b as BoundedReadResult, c as BuildRemoteReviewStateArgs, C as ConfigProvenance, d as ConfigSource, e as ConfigValueOrigin, f as ConfiguredDiffArgsError, D as DEFAULT_GIT_COMMAND_TIMEOUT_MS, E as ExistingClone, F as FetchCommentsDeps, g as FetchCommentsOptions, G as GitSnapshotDependencies, L as LoadConfigOptions, h as LoadGitDiffOptions, i as LoadGitDiffResult, j as LoadGuideOptions, k as LoadedConfig, l as LoadedLocalReview, m as LocalReviewDependencies, n as LocalReviewLoadOptions, M as MaterializeMode, o as MaterializeOptions, p as MaterializeResult, q as MaterializedRemoteSession, P as PublishReviewOptions, s as PublishReviewResult, t as RemoteBootstrapResult, u as RemoteLifetimeOptions, v as RemoteReviewLoad, w as RemoteSession, x as RemoteSessionDeps, y as ResolvedDiffArgs, z as ReviewOutputOrigin, A as ReviewOutputTarget, H as ReviewPublishError, I as ReviewPublishErrorCode, J as ReviewStartResult, K as ReviewedPathAuthorization, N as ReviewedPathRefusal, O as ReviewedSnapshot, S as SnapshotReadFailure, Q as SnapshotReadOptions, T as SnapshotReadResult, U as SourceScanOptions, V as SourceScanResult, W as StartRemoteSessionOptions, X as StartupSource, Y as adoptResumeDocument, Z as authorizeReviewedPath, _ as bootstrapRemoteDiff, $ as buildRemoteReviewState, a0 as commitReviewStart, a1 as dedupeUntrackedByPath, a2 as defaultGitRunner, a3 as defaultRemoteSessionDeps, a4 as deriveGuidePath, a5 as detectExistingClone, a6 as determineMode, a7 as inspectOutputPath, a8 as loadConfig, a9 as loadConfigWithProvenance, aa as loadGitDiffWithUntracked, ab as loadGitReviewSnapshot, ac as loadGuide, ad as loadImage, ae as loadLocalReview, af as loadRemoteReview, ag as loadResumeDocument, ah as materialize, ai as parseAttachmentReference, aj as prepareDirectoryReview, ak as publishOptionsFor, al as publishReview, am as readAttachment, an as readFileWithinBudget, ao as readFileWithinBudgetSync, ap as readLoadedReviewContent, aq as recordResumedAttachments, ar as resolveGuidePath, as as resolveOutputTarget, at as resolveRemoteDefaultBranch, au as resolveStartupDiffArgs, av as resolveStartupSource, aw as resolveStartupSourceAsync, ax as runFetchComments, ay as scanDirectory, az as scanFile, aA as startRemoteSession } from './operations-UyiUD2Nx.cjs';
|
|
8
|
+
import { R as ReviewXmlDecoderOptions, P as ParsedReview } from './review-xml-decoder-COgRtfkf.cjs';
|
|
9
|
+
export { p as parseReviewXmlString } from './review-xml-decoder-COgRtfkf.cjs';
|
|
10
|
+
export { n as nodeScanFsLayer } from './node-scan-fs-CaufzUZR.cjs';
|
|
11
|
+
import 'node:fs';
|
|
12
|
+
import 'node:fs/promises';
|
|
13
|
+
|
|
14
|
+
interface DiffParseOptions {
|
|
15
|
+
budgets?: Partial<SourceBudgets>;
|
|
16
|
+
}
|
|
5
17
|
/**
|
|
6
18
|
* The files parsed, plus one diagnostic per piece of input that could not be represented
|
|
7
19
|
* faithfully.
|
|
@@ -10,16 +22,21 @@ interface DiffParseResult {
|
|
|
10
22
|
files: DiffFile[];
|
|
11
23
|
diagnostics: string[];
|
|
12
24
|
}
|
|
13
|
-
|
|
14
|
-
|
|
25
|
+
|
|
26
|
+
/** Parse a unified diff, discarding diagnostics; representation limits throw RangeError. Prefer {@link parseDiffWithDiagnostics}. */
|
|
27
|
+
declare function parseDiff(rawDiff: string, options?: DiffParseOptions): DiffFile[];
|
|
28
|
+
/** Parse the complete patch synchronously, retaining malformed-input diagnostics. */
|
|
29
|
+
declare function parseDiffWithDiagnostics(rawDiff: string, options?: DiffParseOptions): DiffParseResult;
|
|
30
|
+
|
|
15
31
|
/**
|
|
16
|
-
* Parse
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* (`diff --cc`) is reported and skipped.
|
|
32
|
+
* Parse captured patch output cooperatively. Rejects with CommandCancelledError on abort and
|
|
33
|
+
* never exposes partial files. Input and the resulting AST remain in memory. Individual string
|
|
34
|
+
* operations and one line's parsing cannot be preempted; checkpoints bound scanning and groups
|
|
35
|
+
* of lines, not the CPU time of a pathological header or a single very long line.
|
|
21
36
|
*/
|
|
22
|
-
declare function
|
|
37
|
+
declare function parseDiffWithDiagnosticsAsync(rawDiff: string, options?: DiffParseOptions & {
|
|
38
|
+
signal?: AbortSignal;
|
|
39
|
+
}): Promise<DiffParseResult>;
|
|
23
40
|
|
|
24
41
|
declare const ASSET_DIR_NAME = ".self-review-assets";
|
|
25
42
|
interface PlannedAsset {
|
|
@@ -33,283 +50,38 @@ interface PlannedAsset {
|
|
|
33
50
|
* names so a new document never overwrites an asset the previous one references.
|
|
34
51
|
*/
|
|
35
52
|
type AssetNamer = (idPrefix: string, index: number, ext: string) => string;
|
|
36
|
-
interface SerializeOptions {
|
|
37
|
-
assetName?: AssetNamer;
|
|
38
|
-
}
|
|
39
53
|
interface SerializedReview {
|
|
40
54
|
/** Validated, without a trailing newline. */
|
|
41
55
|
xml: string;
|
|
42
56
|
/** Blobs the document references that nothing has written yet. */
|
|
43
57
|
assets: PlannedAsset[];
|
|
44
58
|
}
|
|
59
|
+
|
|
60
|
+
interface SerializeOptions {
|
|
61
|
+
/** Defaults to stderr for validation diagnostics. */
|
|
62
|
+
reportDiagnostic?: DiagnosticReporter;
|
|
63
|
+
assetName?: AssetNamer;
|
|
64
|
+
/** Optional authoritative schema effect; omitted calls use xmllint. */
|
|
65
|
+
validateSchema?: ReviewSchemaValidator;
|
|
66
|
+
}
|
|
45
67
|
/**
|
|
46
68
|
* Pure: touches no disk (`publishReview` writes). Built before validation, so an
|
|
47
69
|
* unrepresentable value is refused first.
|
|
48
70
|
*
|
|
49
71
|
* @throws XmlIllegalCharacterError naming the comment/reply and field.
|
|
50
|
-
* @throws ReviewXmlError `
|
|
51
|
-
*
|
|
72
|
+
* @throws ReviewXmlError `input-too-large` before escaped output exceeds the resume byte
|
|
73
|
+
* budget (including publication’s final newline), or `schema-invalid`, one violation per
|
|
74
|
+
* `details` line. A validator that fails to load is deliberately not fatal: unvalidated XML
|
|
75
|
+
* after a stderr warning.
|
|
52
76
|
*/
|
|
53
77
|
declare function serializeReview(state: ReviewState, outputFilePath: string, options?: SerializeOptions): Promise<SerializedReview>;
|
|
54
78
|
|
|
55
|
-
interface
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
viewedFiles: string[];
|
|
59
|
-
gitDiffArgs: string;
|
|
60
|
-
source: DiffSource;
|
|
61
|
-
/**
|
|
62
|
-
* One line per comment downgraded to file-level feedback, with its suggestion text folded into
|
|
63
|
-
* the body.
|
|
64
|
-
*/
|
|
65
|
-
importDiagnostics: string[];
|
|
66
|
-
remoteUrl?: string;
|
|
67
|
-
remoteBaseSha?: string;
|
|
68
|
-
remoteHeadSha?: string;
|
|
69
|
-
remoteForge?: RemoteForge;
|
|
79
|
+
interface ParseReviewXmlOptions extends ReviewXmlDecoderOptions {
|
|
80
|
+
/** Authoritative when supplied; native filesystem reads are never used as a fallback. */
|
|
81
|
+
reader?: ReviewXmlReader;
|
|
70
82
|
}
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
-
*
|
|
74
|
-
* @throws ReviewXmlError `read-failed`, `input-too-large`, or what
|
|
75
|
-
* {@link parseReviewXmlString} throws.
|
|
76
|
-
*/
|
|
77
|
-
declare function parseReviewXml(xmlPath: string): ParsedReview;
|
|
78
|
-
/**
|
|
79
|
-
* Namespace-blind by design: v1, v2 and v3 documents read identically.
|
|
80
|
-
*
|
|
81
|
-
* @throws ReviewXmlError `parse-failed`, `missing-root`, or `input-too-large`
|
|
82
|
-
* (over `MAX_RESUME_ATTACHMENTS`).
|
|
83
|
-
*/
|
|
84
|
-
declare function parseReviewXmlString(xmlContent: string): ParsedReview;
|
|
85
|
-
|
|
86
|
-
type ReviewXmlErrorCode = 'read-failed'
|
|
87
|
-
/** Over a safety budget (input-budgets.ts): byte size or attachment count. */
|
|
88
|
-
| 'input-too-large' | 'parse-failed'
|
|
89
|
-
/** Well-formed, but with no `<review>` root element. */
|
|
90
|
-
| 'missing-root'
|
|
91
|
-
/** The generated document does not validate against the v3 XSD. */
|
|
92
|
-
| 'schema-invalid' | 'xml-illegal-character';
|
|
93
|
-
declare class ReviewXmlError extends Error {
|
|
94
|
-
readonly code: ReviewXmlErrorCode;
|
|
95
|
-
readonly cause?: unknown;
|
|
96
|
-
/** One rendered line per problem (e.g. a schema violation with its line number). */
|
|
97
|
-
readonly details: readonly string[];
|
|
98
|
-
constructor(code: ReviewXmlErrorCode, message: string, options?: {
|
|
99
|
-
cause?: unknown;
|
|
100
|
-
details?: readonly string[];
|
|
101
|
-
});
|
|
102
|
-
}
|
|
103
|
-
interface XmlIllegalCharacterLocation {
|
|
104
|
-
/** e.g. `body`, `original-code`, `path`, `author`. */
|
|
105
|
-
field: string;
|
|
106
|
-
filePath?: string;
|
|
107
|
-
commentId?: string;
|
|
108
|
-
replyId?: string;
|
|
109
|
-
}
|
|
110
|
-
/**
|
|
111
|
-
* Thrown before anything is written: no escaped form exists, and dropping the character would
|
|
112
|
-
* change the reviewer's text or a suggestion's code.
|
|
113
|
-
*/
|
|
114
|
-
declare class XmlIllegalCharacterError extends ReviewXmlError {
|
|
115
|
-
readonly codePoint: number;
|
|
116
|
-
readonly field: string;
|
|
117
|
-
readonly filePath?: string;
|
|
118
|
-
readonly commentId?: string;
|
|
119
|
-
readonly replyId?: string;
|
|
120
|
-
constructor(codePoint: number, location: XmlIllegalCharacterLocation);
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
type SafeFsErrorCode = 'output-is-directory'
|
|
124
|
-
/** EACCES, EPERM or EROFS. */
|
|
125
|
-
| 'permission-denied'
|
|
126
|
-
/** ENOSPC or EDQUOT. */
|
|
127
|
-
| 'no-space'
|
|
128
|
-
/** A symlink sits where this module would read, create or replace a file, or on the way to it. */
|
|
129
|
-
| 'unsafe-link'
|
|
130
|
-
/** Exists, but replacing it would change semantics: hard-linked, not a regular file, or foreign-owned. */
|
|
131
|
-
| 'unsupported-target'
|
|
132
|
-
/** The file at the target is not the one the caller checked. */
|
|
133
|
-
| 'identity-changed'
|
|
134
|
-
/** ENOENT or ENOTDIR. */
|
|
135
|
-
| 'not-found'
|
|
136
|
-
/** A FIFO, socket or device. */
|
|
137
|
-
| 'not-regular' | 'too-large' | 'io-error';
|
|
138
|
-
declare class SafeFsError extends Error {
|
|
139
|
-
readonly code: SafeFsErrorCode;
|
|
140
|
-
readonly path: string;
|
|
141
|
-
readonly cause?: unknown;
|
|
142
|
-
constructor(code: SafeFsErrorCode, path: string, message: string, cause?: unknown);
|
|
143
|
-
}
|
|
144
|
-
/** The subset of `fs` used here, synchronous so a test can inject a failure at an exact step. */
|
|
145
|
-
interface FsLayer {
|
|
146
|
-
openSync(path: string, flags: number, mode?: number): number;
|
|
147
|
-
/** May write fewer bytes than given, as the real one may. */
|
|
148
|
-
writeSync(fd: number, buffer: Uint8Array): number;
|
|
149
|
-
fsyncSync(fd: number): void;
|
|
150
|
-
fchmodSync(fd: number, mode: number): void;
|
|
151
|
-
fchownSync(fd: number, uid: number, gid: number): void;
|
|
152
|
-
closeSync(fd: number): void;
|
|
153
|
-
renameSync(from: string, to: string): void;
|
|
154
|
-
unlinkSync(path: string): void;
|
|
155
|
-
lstatSync(path: string): nodeFs.Stats;
|
|
156
|
-
fstatSync(fd: number): nodeFs.Stats;
|
|
157
|
-
readFileSync(fd: number): Buffer;
|
|
158
|
-
mkdirSync(path: string, mode: number): void;
|
|
159
|
-
realpathSync(path: string): string;
|
|
160
|
-
}
|
|
161
|
-
declare const nodeFsLayer: FsLayer;
|
|
162
|
-
interface FileIdentity {
|
|
163
|
-
dev: number;
|
|
164
|
-
ino: number;
|
|
165
|
-
/** Permission bits only (`mode & 0o7777`). */
|
|
166
|
-
mode: number;
|
|
167
|
-
nlink: number;
|
|
168
|
-
size: number;
|
|
169
|
-
mtimeMs: number;
|
|
170
|
-
uid: number;
|
|
171
|
-
gid: number;
|
|
172
|
-
}
|
|
173
|
-
declare function snapshotIdentity(stats: nodeFs.Stats): FileIdentity;
|
|
174
|
-
declare function sameFile(a: FileIdentity, b: FileIdentity): boolean;
|
|
175
|
-
/** The code a caller maps to its own reason; anything unknown is `io-error`. */
|
|
176
|
-
declare function classifyFsError(error: unknown): SafeFsErrorCode;
|
|
177
|
-
/**
|
|
178
|
-
* Refuse a `rel` whose directories under `root` include a symlink. The leaf is the caller's
|
|
179
|
-
* policy, and a missing component ends the walk: nothing can be linked where nothing is.
|
|
180
|
-
*/
|
|
181
|
-
declare function assertNoSymlinkAncestors(root: string, rel: string, fs?: FsLayer): void;
|
|
182
|
-
interface WriteExclusiveOptions {
|
|
183
|
-
/** Masked by the umask. Default 0o666. */
|
|
184
|
-
mode?: number;
|
|
185
|
-
/** Applied after creation, bypassing the umask. */
|
|
186
|
-
exactMode?: number;
|
|
187
|
-
/** Applied after creation; failing to is `unsupported-target` and removes the file. */
|
|
188
|
-
exactOwner?: {
|
|
189
|
-
uid: number;
|
|
190
|
-
gid: number;
|
|
191
|
-
};
|
|
192
|
-
fs?: FsLayer;
|
|
193
|
-
}
|
|
194
|
-
/**
|
|
195
|
-
* Create `filePath`, which must not exist, write every byte and sync. A symlink at the path,
|
|
196
|
-
* dangling or not, is `unsafe-link`. Any failure after creation removes the file again.
|
|
197
|
-
*/
|
|
198
|
-
declare function writeExclusiveNoFollow(filePath: string, bytes: Uint8Array, options?: WriteExclusiveOptions): FileIdentity;
|
|
199
|
-
interface AtomicReplaceOptions {
|
|
200
|
-
/** Give the replacement the replaced file's permission bits. */
|
|
201
|
-
preserveMode?: boolean;
|
|
202
|
-
/**
|
|
203
|
-
* Give the replacement the replaced file's owner (`rename` swaps the inode). An owner this
|
|
204
|
-
* process may not restore with `fchown` is refused as `unsupported-target` before any write.
|
|
205
|
-
*/
|
|
206
|
-
preserveOwner?: boolean;
|
|
207
|
-
/** Refused as `identity-changed` when the target is no longer this file (dev/ino). */
|
|
208
|
-
expectedIdentity?: FileIdentity;
|
|
209
|
-
/** With `expectedIdentity`: also refuse a same-inode rewrite (size or mtime moved). */
|
|
210
|
-
expectUnmodified?: boolean;
|
|
211
|
-
fs?: FsLayer;
|
|
212
|
-
randomName?: () => string;
|
|
213
|
-
}
|
|
214
|
-
interface AtomicReplaceResult {
|
|
215
|
-
identity: FileIdentity;
|
|
216
|
-
/** Whether a file existed at `target` before. */
|
|
217
|
-
replaced: boolean;
|
|
218
|
-
}
|
|
219
|
-
/**
|
|
220
|
-
* Replace or create `target` in one `rename` from a same-directory temp file. The `lstat`→`rename`
|
|
221
|
-
* window is accepted: `rename` never follows a link and nothing before it creates through one.
|
|
222
|
-
*/
|
|
223
|
-
declare function atomicReplace(target: string, bytes: Uint8Array, options?: AtomicReplaceOptions): AtomicReplaceResult;
|
|
224
|
-
/** `lstat` a replace target under the policy of {@link atomicReplace}; null when absent. */
|
|
225
|
-
declare function inspectReplaceTarget(target: string, fs?: FsLayer): FileIdentity | null;
|
|
226
|
-
|
|
227
|
-
/** Reference as the resumed document wrote it → absolute path beside that document. Session state only. */
|
|
228
|
-
type AttachmentOrigins = ReadonlyMap<string, string>;
|
|
229
|
-
type AttachmentReadFailureReason = 'not-authorized' | 'not-found' | 'not-regular' | 'unsafe-link' | 'too-large' | 'io-error';
|
|
230
|
-
type AttachmentReadResult = {
|
|
231
|
-
ok: true;
|
|
232
|
-
data: ArrayBuffer;
|
|
233
|
-
} | {
|
|
234
|
-
ok: false;
|
|
235
|
-
reason: AttachmentReadFailureReason;
|
|
236
|
-
message: string;
|
|
237
|
-
};
|
|
238
|
-
/** The bare name in `.self-review-assets/<name>`; null for any other shape. */
|
|
239
|
-
declare function parseAttachmentReference(reference: unknown): string | null;
|
|
240
|
-
/** Origins resolve against the resumed document's directory; an unrecorded reference is never read. */
|
|
241
|
-
declare function resolveAttachmentOrigins(comments: readonly ReviewComment[], resumeDocumentPath: string): {
|
|
242
|
-
origins: Map<string, string>;
|
|
243
|
-
diagnostics: string[];
|
|
244
|
-
};
|
|
245
|
-
/** Read one asset the caller authorized: the asset directory must not be a link, nor the leaf. */
|
|
246
|
-
declare function readAssetFile(assetPath: string): Promise<AttachmentReadResult>;
|
|
247
|
-
/** The recorded origin of an imported reference, else the same name in `currentAssetDir`. */
|
|
248
|
-
declare function authorizeAttachmentReference(reference: unknown, origins: AttachmentOrigins, currentAssetDir: string | null): string | null;
|
|
249
|
-
declare class AttachmentRelocationError extends Error {
|
|
250
|
-
readonly reference: string;
|
|
251
|
-
readonly origin: string;
|
|
252
|
-
readonly reason: AttachmentReadFailureReason;
|
|
253
|
-
constructor(reference: string, origin: string, reason: AttachmentReadFailureReason, detail: string);
|
|
254
|
-
}
|
|
255
|
-
/**
|
|
256
|
-
* Give every imported attachment whose origin is not beside `outputPath` its bytes, so the
|
|
257
|
-
* publisher stages a copy. Unreadable ones throw: the old reference would resolve to the wrong file.
|
|
258
|
-
*/
|
|
259
|
-
declare function relocateAttachments(state: ReviewState, origins: AttachmentOrigins, outputPath: string): Promise<ReviewState>;
|
|
260
|
-
|
|
261
|
-
type ReviewPublishErrorCode =
|
|
262
|
-
/** `details` lists each XSD violation. */
|
|
263
|
-
'validation-failed' | 'xml-illegal-character' | 'output-is-directory' | 'permission-denied' | 'no-space'
|
|
264
|
-
/** A link where the publisher would write, or an inherited path resolving outside its base. */
|
|
265
|
-
| 'unsafe-link'
|
|
266
|
-
/** A hard-linked output, or a non-directory or foreign-owned asset directory. */
|
|
267
|
-
| 'unsupported-target'
|
|
268
|
-
/** A resumed attachment that must move cannot be read where its document put it. */
|
|
269
|
-
| 'attachment-unavailable' | 'io-error';
|
|
270
|
-
declare class ReviewPublishError extends Error {
|
|
271
|
-
readonly code: ReviewPublishErrorCode;
|
|
272
|
-
readonly path: string;
|
|
273
|
-
/** One rendered line per problem; empty when the message is all there is. */
|
|
274
|
-
readonly details: readonly string[];
|
|
275
|
-
readonly cause?: unknown;
|
|
276
|
-
constructor(code: ReviewPublishErrorCode, path: string, message: string, options?: {
|
|
277
|
-
details?: readonly string[];
|
|
278
|
-
cause?: unknown;
|
|
279
|
-
});
|
|
280
|
-
}
|
|
281
|
-
/** `inherited` paths come from something a repository can commit, so they must stay inside `baseDir`. */
|
|
282
|
-
type ReviewOutputOrigin = 'explicit' | 'inherited';
|
|
283
|
-
/** Resolved by `resolveOutputTarget` in `startup.ts`. */
|
|
284
|
-
type ReviewOutputTarget = {
|
|
285
|
-
path: string;
|
|
286
|
-
origin: 'explicit';
|
|
287
|
-
} | {
|
|
288
|
-
path: string;
|
|
289
|
-
origin: 'inherited';
|
|
290
|
-
baseDir: string;
|
|
291
|
-
};
|
|
292
|
-
interface PublishReviewCommonOptions {
|
|
293
|
-
fs?: FsLayer;
|
|
294
|
-
randomName?: () => string;
|
|
295
|
-
/** Imported attachments whose origin is elsewhere are copied beside the output (`relocateAttachments`). */
|
|
296
|
-
attachmentOrigins?: AttachmentOrigins;
|
|
297
|
-
}
|
|
298
|
-
type PublishReviewOptions = PublishReviewCommonOptions & ({
|
|
299
|
-
outputOrigin: 'explicit';
|
|
300
|
-
} | {
|
|
301
|
-
outputOrigin: 'inherited';
|
|
302
|
-
baseDir: string;
|
|
303
|
-
});
|
|
304
|
-
interface PublishReviewResult {
|
|
305
|
-
outputPath: string;
|
|
306
|
-
/** The attachment files this publication created. */
|
|
307
|
-
assetPaths: string[];
|
|
308
|
-
}
|
|
309
|
-
/** @throws ReviewPublishError for every failure, document or filesystem. */
|
|
310
|
-
declare function publishReview(state: ReviewState, outputPath: string, options: PublishReviewOptions): Promise<PublishReviewResult>;
|
|
311
|
-
/** The error `publishReview` would throw for the path as it stands; advisory, since the disk can change. */
|
|
312
|
-
declare function inspectOutputPath(outputPath: string, options: PublishReviewOptions): ReviewPublishError | null;
|
|
83
|
+
/** Sized before reading; preserves the string decoder's typed errors and read-failed errors. */
|
|
84
|
+
declare function parseReviewXml(xmlPath: string, options?: ParseReviewXmlOptions): ParsedReview;
|
|
313
85
|
|
|
314
86
|
type AnchorSide = 'old' | 'new';
|
|
315
87
|
interface LineAnchor {
|
|
@@ -379,446 +151,36 @@ declare function parseGuideXml(xmlContent: string): Promise<GuideParseResult>;
|
|
|
379
151
|
declare function reconcileGuide(guide: ReviewGuide, diffFilePaths: string[]): ResolvedGuideGroup[];
|
|
380
152
|
|
|
381
153
|
/**
|
|
382
|
-
*
|
|
383
|
-
*
|
|
384
|
-
*/
|
|
385
|
-
declare const MAX_SOURCE_ENTRIES = 50000;
|
|
386
|
-
/** Prefix sampled for a NUL byte to decide a file is binary. */
|
|
387
|
-
declare const BINARY_SNIFF_BYTES: number;
|
|
388
|
-
/**
|
|
389
|
-
* Largest text file read into a synthetic diff; a larger one is listed without content and named in
|
|
390
|
-
* a diagnostic.
|
|
391
|
-
*/
|
|
392
|
-
declare const MAX_SOURCE_FILE_BYTES: number;
|
|
393
|
-
/** Total bytes one synthetic-diff build may read, binary sniffs included. */
|
|
394
|
-
declare const MAX_SOURCE_TOTAL_BYTES: number;
|
|
395
|
-
/** Most bytes of `git diff` output captured from one invocation (the child process `maxBuffer`). */
|
|
396
|
-
declare const MAX_GIT_DIFF_OUTPUT_BYTES: number;
|
|
397
|
-
/** Largest guide sidecar the loader will read. */
|
|
398
|
-
declare const MAX_GUIDE_BYTES: number;
|
|
399
|
-
/**
|
|
400
|
-
* Largest review document `--resume-from` will read (text and attachment references, never bytes).
|
|
401
|
-
*/
|
|
402
|
-
declare const MAX_RESUME_XML_BYTES: number;
|
|
403
|
-
/** Most attachment references one resumed document may carry; bounds the reads it can ask for. */
|
|
404
|
-
declare const MAX_RESUME_ATTACHMENTS = 1000;
|
|
405
|
-
/** Largest image read for a rendered preview or a comment attachment. */
|
|
406
|
-
declare const MAX_IMAGE_BYTES: number;
|
|
407
|
-
/**
|
|
408
|
-
* The source-loading budgets as one value; overrides are for tests and embedders, never user
|
|
409
|
-
* config.
|
|
410
|
-
*/
|
|
411
|
-
interface SourceBudgets {
|
|
412
|
-
maxEntries: number;
|
|
413
|
-
maxFileBytes: number;
|
|
414
|
-
maxTotalBytes: number;
|
|
415
|
-
maxGitDiffOutputBytes: number;
|
|
416
|
-
}
|
|
417
|
-
declare const DEFAULT_SOURCE_BUDGETS: Readonly<SourceBudgets>;
|
|
418
|
-
declare function resolveSourceBudgets(overrides?: Partial<SourceBudgets>): SourceBudgets;
|
|
419
|
-
/** `5 MiB`, `7.3 MiB`, `812 KiB`, `100 bytes`. */
|
|
420
|
-
declare function formatBytes(bytes: number): string;
|
|
421
|
-
|
|
422
|
-
interface SyntheticDiffOptions {
|
|
423
|
-
/**
|
|
424
|
-
* Only for a path the reviewer named explicitly (single-file review); enumerated paths never
|
|
425
|
-
* follow links.
|
|
426
|
-
*/
|
|
427
|
-
followSymlinks?: boolean;
|
|
428
|
-
budgets?: Partial<SourceBudgets>;
|
|
429
|
-
}
|
|
430
|
-
interface SyntheticDiffResult {
|
|
431
|
-
diff: string;
|
|
432
|
-
/**
|
|
433
|
-
* Files listed without content, by literal relative path, with the sentence the viewer shows
|
|
434
|
-
* instead.
|
|
435
|
-
*/
|
|
436
|
-
omitted: Map<string, string>;
|
|
437
|
-
diagnostics: string[];
|
|
438
|
-
}
|
|
439
|
-
/**
|
|
440
|
-
* Generate synthetic unified diffs for a list of file paths so they can be
|
|
441
|
-
* parsed by the existing diff parser. Each file is treated as a new addition.
|
|
442
|
-
*
|
|
443
|
-
* @param paths - Literal relative file paths (e.g. "src/foo.ts"), resolved
|
|
444
|
-
* against rootDir and never git-quoted on the way in
|
|
445
|
-
* @param rootDir - Absolute path to the root directory the paths are relative to
|
|
446
|
-
* @returns The diff text, the files listed without content, and diagnostics
|
|
447
|
-
*/
|
|
448
|
-
declare function generateSyntheticDiffs(paths: string[], rootDir: string, options?: SyntheticDiffOptions): SyntheticDiffResult;
|
|
449
|
-
/** Builds and parses in one step, setting `omittedReason` on files listed without content. */
|
|
450
|
-
declare function loadSyntheticFiles(paths: string[], rootDir: string, options?: SyntheticDiffOptions): {
|
|
451
|
-
files: DiffFile[];
|
|
452
|
-
diagnostics: string[];
|
|
453
|
-
};
|
|
454
|
-
|
|
455
|
-
/** Rejects when git is missing or `cwd` is not inside a repository. */
|
|
456
|
-
declare function getRepoRootAsync(cwd?: string): Promise<string>;
|
|
457
|
-
/**
|
|
458
|
-
* Config overrides, placed before `diff`, that keep output parseable whatever the user's config
|
|
459
|
-
* says.
|
|
460
|
-
*/
|
|
461
|
-
declare const PARSER_COMPATIBLE_GIT_CONFIG: readonly string[];
|
|
462
|
-
/** Appended after the user's options so a user `--color=always` or `--no-prefix` loses. */
|
|
463
|
-
declare const PARSER_COMPATIBLE_DIFF_FLAGS: readonly string[];
|
|
464
|
-
/** Inserts the flags after every user option and before `--`. */
|
|
465
|
-
declare function withParserCompatibleDiffArgs(args: readonly string[]): string[];
|
|
466
|
-
/**
|
|
467
|
-
* The one entry point for every `git diff` (load, expansion, remote), so the
|
|
468
|
-
* parser-compatible normalization applies uniformly. Output past `maxOutputBytes`
|
|
469
|
-
* rejects with an error {@link isOutputLimitError} recognizes.
|
|
470
|
-
*/
|
|
471
|
-
declare function runGitDiffAsync(args: string[], cwd?: string, maxOutputBytes?: number): Promise<string>;
|
|
472
|
-
/**
|
|
473
|
-
* Get list of untracked files (respects .gitignore).
|
|
474
|
-
*
|
|
475
|
-
* Pass the repository root. `git ls-files` reports paths relative to the
|
|
476
|
-
* directory it runs in and lists that subtree only, while `git diff` reports
|
|
477
|
-
* root-relative paths for the whole repository from anywhere inside it. Run
|
|
478
|
-
* anywhere else and the names match neither the diff nor the root the files
|
|
479
|
-
* are read from.
|
|
480
|
-
*
|
|
481
|
-
* `-z` keeps the names literal. NUL termination survives newlines in
|
|
482
|
-
* filenames, and it turns off the C-style quoting git otherwise applies to
|
|
483
|
-
* control characters and non-ASCII bytes.
|
|
484
|
-
*/
|
|
485
|
-
declare function getUntrackedFilesAsync(repoRoot?: string): Promise<string[]>;
|
|
486
|
-
/**
|
|
487
|
-
* Generate synthetic unified diffs for untracked files so they can be
|
|
488
|
-
* parsed by the existing diff parser. Untracked symlinks are described by
|
|
489
|
-
* their link text, never followed.
|
|
490
|
-
*/
|
|
491
|
-
declare function generateUntrackedDiffs(paths: string[], repoRoot: string, options?: SyntheticDiffOptions): SyntheticDiffResult;
|
|
492
|
-
|
|
493
|
-
/** Forges the app knows how to talk to. */
|
|
494
|
-
type ForgeName = 'github' | 'gitlab';
|
|
495
|
-
/**
|
|
496
|
-
* A parsed pull-request / merge-request web URL.
|
|
497
|
-
*
|
|
498
|
-
* Detection is by URL path shape only (`/pull/N` → GitHub,
|
|
499
|
-
* `/-/merge_requests/N` → GitLab) on any host, so self-hosted instances such
|
|
500
|
-
* as git.drupalcode.org work with zero configuration.
|
|
501
|
-
*/
|
|
502
|
-
interface ForgeUrl {
|
|
503
|
-
forge: ForgeName;
|
|
504
|
-
/** Host as it appears in the URL, including a port when present. */
|
|
505
|
-
host: string;
|
|
506
|
-
/**
|
|
507
|
-
* Repository owner. For GitLab this is the full namespace path and may
|
|
508
|
-
* contain slashes (subgroups, e.g. `group/subgroup`); for GitHub it is a
|
|
509
|
-
* single segment.
|
|
510
|
-
*/
|
|
511
|
-
owner: string;
|
|
512
|
-
/** Repository name (final path segment before the PR/MR marker). */
|
|
513
|
-
repo: string;
|
|
514
|
-
/** Pull-request number / merge-request IID. */
|
|
515
|
-
number: number;
|
|
516
|
-
}
|
|
517
|
-
/** Which side of the diff a thread anchor points at. */
|
|
518
|
-
type ForgeAnchorSide = 'old' | 'new';
|
|
519
|
-
/**
|
|
520
|
-
* Forge-neutral anchor of a discussion thread onto the diff.
|
|
521
|
-
*
|
|
522
|
-
* The mapper consumes this shape without forge-conditional logic:
|
|
523
|
-
* - `startLine`/`endLine` are equal for single-line anchors.
|
|
524
|
-
* - `startLine`/`endLine` are `null` when the forge supplies a file path but
|
|
525
|
-
* no usable line information (the mapper degrades to a file-level comment;
|
|
526
|
-
* `side` is meaningless in that case and providers should set `'new'`).
|
|
527
|
-
*
|
|
528
|
-
* Revision provenance (the mapper compares it with the reviewed head; providers
|
|
529
|
-
* report only what the forge told them):
|
|
530
|
-
* - `headSha`: head commit the line numbers were computed against, when the
|
|
531
|
-
* forge reports one per note (GitLab). A suggestion activates only on a match.
|
|
532
|
-
* - `outdated`: the forge's own per-note verdict (GitHub `line: null`). `true`
|
|
533
|
-
* degrades to file-level; `false` vouches for the anchor when no `headSha` exists.
|
|
534
|
-
*
|
|
535
|
-
* An anchor carrying neither is unverifiable: it never activates a suggestion.
|
|
536
|
-
*/
|
|
537
|
-
interface ForgeThreadAnchor {
|
|
538
|
-
filePath: string;
|
|
539
|
-
side: ForgeAnchorSide;
|
|
540
|
-
startLine: number | null;
|
|
541
|
-
endLine: number | null;
|
|
542
|
-
headSha?: string;
|
|
543
|
-
outdated?: boolean;
|
|
544
|
-
}
|
|
545
|
-
/** One turn (root comment or reply) in a forge discussion thread. */
|
|
546
|
-
interface ForgeThreadTurn {
|
|
547
|
-
/** Forge-assigned comment/note ID, kept as a string verbatim. */
|
|
548
|
-
remoteId: string;
|
|
549
|
-
/** Forge username of the turn's author. */
|
|
550
|
-
author: string;
|
|
551
|
-
/** Markdown body, passed through verbatim. */
|
|
552
|
-
body: string;
|
|
553
|
-
}
|
|
554
|
-
/**
|
|
555
|
-
* A normalized discussion thread: an ordered root + flat replies.
|
|
556
|
-
*
|
|
557
|
-
* The root turn owns the anchor. `anchor` is `null` for threads with no file
|
|
558
|
-
* association at all (e.g. GitLab non-diff discussions); the mapper turns
|
|
559
|
-
* those into its review-level representation. `replies` preserve the forge's
|
|
560
|
-
* document order — nothing else sorts them.
|
|
561
|
-
*/
|
|
562
|
-
interface ForgeThread {
|
|
563
|
-
root: ForgeThreadTurn;
|
|
564
|
-
replies: ForgeThreadTurn[];
|
|
565
|
-
anchor: ForgeThreadAnchor | null;
|
|
566
|
-
}
|
|
567
|
-
/** Options for {@link ForgeProvider.fetchThreads}. */
|
|
568
|
-
interface FetchThreadsOptions {
|
|
569
|
-
/**
|
|
570
|
-
* Include threads the forge marks resolved. Defaults to false where the
|
|
571
|
-
* forge tracks resolution (GitLab); providers without a comparable concept
|
|
572
|
-
* on the fetch path (GitHub REST review comments) may ignore it.
|
|
573
|
-
*/
|
|
574
|
-
includeResolved?: boolean;
|
|
575
|
-
}
|
|
576
|
-
/**
|
|
577
|
-
* Result of running a forge CLI command through {@link ForgeCommandRunner}.
|
|
578
|
-
*/
|
|
579
|
-
interface ForgeCommandResult {
|
|
580
|
-
stdout: string;
|
|
581
|
-
stderr: string;
|
|
582
|
-
exitCode: number;
|
|
583
|
-
}
|
|
584
|
-
/**
|
|
585
|
-
* Optional lifetime bounds; either one kills the child and rejects with {@link
|
|
586
|
-
* CommandCancelledError}.
|
|
587
|
-
*/
|
|
588
|
-
interface ForgeCommandOptions {
|
|
589
|
-
signal?: AbortSignal;
|
|
590
|
-
timeoutMs?: number;
|
|
591
|
-
}
|
|
592
|
-
/**
|
|
593
|
-
* Injectable command runner for providers and the materializer. Resolves with
|
|
594
|
-
* the exit code on any completed run; rejects when the binary cannot be spawned
|
|
595
|
-
* and, with a {@link CommandCancelledError}, when cut short by `options`.
|
|
596
|
-
*/
|
|
597
|
-
type ForgeCommandRunner = (command: string, args: string[], options?: ForgeCommandOptions) => Promise<ForgeCommandResult>;
|
|
598
|
-
/** Why a command run was cut short. */
|
|
599
|
-
type CommandCancelReason = 'aborted' | 'timeout';
|
|
600
|
-
/**
|
|
601
|
-
* A run ended by its caller's bounds (abort or timeout) after the child was
|
|
602
|
-
* killed. Providers must not fold it into {@link ForgeCliUnavailableError}: a
|
|
603
|
-
* session being torn down must not degrade into a review without threads.
|
|
604
|
-
*/
|
|
605
|
-
declare class CommandCancelledError extends Error {
|
|
606
|
-
readonly reason: CommandCancelReason;
|
|
607
|
-
readonly command: string;
|
|
608
|
-
readonly args: readonly string[];
|
|
609
|
-
constructor(reason: CommandCancelReason, command: string, args: readonly string[]);
|
|
610
|
-
}
|
|
611
|
-
/** Matches by name too, so it works across module instances. */
|
|
612
|
-
declare function isCommandCancelled(error: unknown): error is CommandCancelledError;
|
|
613
|
-
/**
|
|
614
|
-
* The conversation plane of a forge. Exactly two capabilities: base-branch
|
|
615
|
-
* lookup and discussion-thread fetching. No diff fetching, no blob fetching,
|
|
616
|
-
* no posting — those concerns live elsewhere.
|
|
617
|
-
*
|
|
618
|
-
* Implementations throw {@link ForgeCliUnavailableError} when their CLI is
|
|
619
|
-
* absent or unauthenticated so callers can degrade cleanly.
|
|
620
|
-
*/
|
|
621
|
-
interface ForgeProvider {
|
|
622
|
-
readonly forge: ForgeName;
|
|
623
|
-
/** Resolve the PR/MR base (target) branch name. */
|
|
624
|
-
fetchBaseBranch(url: ForgeUrl): Promise<string>;
|
|
625
|
-
/** Fetch the PR/MR discussion threads in normalized form. */
|
|
626
|
-
fetchThreads(url: ForgeUrl, options?: FetchThreadsOptions): Promise<ForgeThread[]>;
|
|
627
|
-
}
|
|
628
|
-
/**
|
|
629
|
-
* Thrown by providers when their CLI is missing (spawn ENOENT) or exits
|
|
630
|
-
* non-zero due to authentication/API failure. Callers catch this to degrade
|
|
631
|
-
* (print to stderr, continue without threads) instead of crashing.
|
|
632
|
-
*/
|
|
633
|
-
declare class ForgeCliUnavailableError extends Error {
|
|
634
|
-
readonly forge: ForgeName;
|
|
635
|
-
readonly cli: string;
|
|
636
|
-
constructor(forge: ForgeName, cli: string, message: string);
|
|
637
|
-
}
|
|
638
|
-
/**
|
|
639
|
-
* Parse a forge web URL into a {@link ForgeUrl}, or return `null` for
|
|
640
|
-
* anything that is not a PR/MR URL. Detection is by path shape only, on any
|
|
641
|
-
* http(s) host. Query strings and fragments are ignored.
|
|
642
|
-
*/
|
|
643
|
-
declare function parseForgeUrl(url: string): ForgeUrl | null;
|
|
644
|
-
|
|
645
|
-
interface SourceScanOptions {
|
|
646
|
-
budgets?: Partial<SourceBudgets>;
|
|
647
|
-
}
|
|
648
|
-
interface SourceScanResult {
|
|
649
|
-
files: DiffFile[];
|
|
650
|
-
/** For `DiffLoadPayload.diagnostics`; empty for a clean scan. */
|
|
651
|
-
diagnostics: string[];
|
|
652
|
-
/** `files` is empty when this is true. */
|
|
653
|
-
entryLimitExceeded: boolean;
|
|
654
|
-
}
|
|
655
|
-
/**
|
|
656
|
-
* Recursively scans `directoryPath`; a directory matching `ignorePatterns` is pruned without being
|
|
657
|
-
* opened.
|
|
658
|
-
*/
|
|
659
|
-
declare function scanDirectory(directoryPath: string, ignorePatterns?: string[], options?: SourceScanOptions): Promise<SourceScanResult>;
|
|
660
|
-
/**
|
|
661
|
-
* The reviewer named this path explicitly, so a symlink is read through; the per-file budget still
|
|
662
|
-
* applies.
|
|
663
|
-
*/
|
|
664
|
-
declare function scanFile(filePath: string, options?: SourceScanOptions): Promise<SourceScanResult>;
|
|
665
|
-
|
|
666
|
-
/** Filesystem errors (ENOENT, EACCES, ...) throw. */
|
|
667
|
-
type BoundedReadResult = {
|
|
668
|
-
kind: 'ok';
|
|
669
|
-
content: Buffer;
|
|
670
|
-
} | {
|
|
671
|
-
kind: 'too-large';
|
|
672
|
-
size: number;
|
|
673
|
-
}
|
|
674
|
-
/** A directory, FIFO, socket or device: nothing was read. */
|
|
675
|
-
| {
|
|
676
|
-
kind: 'not-regular';
|
|
677
|
-
};
|
|
678
|
-
interface BoundedReadOptions {
|
|
679
|
-
/** Covers the leaf only; ancestors are the caller's job (`openContainedFile`). */
|
|
680
|
-
noFollow?: boolean;
|
|
681
|
-
}
|
|
682
|
-
declare function readFileWithinBudget(path: string, maxBytes: number, options?: BoundedReadOptions): Promise<BoundedReadResult>;
|
|
683
|
-
declare function readFileWithinBudgetSync(path: string, maxBytes: number, options?: BoundedReadOptions): BoundedReadResult;
|
|
684
|
-
|
|
685
|
-
/** One side as the arguments describe it, before resolution; `implicit` is the HEAD git assumes. */
|
|
686
|
-
type GitDiffSideSpec = {
|
|
687
|
-
kind: 'working-tree';
|
|
688
|
-
} | {
|
|
689
|
-
kind: 'index';
|
|
690
|
-
} | {
|
|
691
|
-
kind: 'revision';
|
|
692
|
-
rev: string;
|
|
693
|
-
implicit: boolean;
|
|
694
|
-
} | {
|
|
695
|
-
kind: 'merge-base';
|
|
696
|
-
left: string;
|
|
697
|
-
right: string;
|
|
698
|
-
} | {
|
|
699
|
-
kind: 'unknown';
|
|
700
|
-
reason: string;
|
|
701
|
-
};
|
|
702
|
-
interface GitDiffSides {
|
|
703
|
-
oldSide: GitDiffSideSpec;
|
|
704
|
-
newSide: GitDiffSideSpec;
|
|
705
|
-
}
|
|
706
|
-
/**
|
|
707
|
-
* The two snapshots a `git diff` argv compares. Pure: runs no git and checks no revision.
|
|
708
|
-
* Uses the classifier's arity rules, so `-S --cached` is not a flag. `--no-index`, three
|
|
709
|
-
* or more revisions and `--cached` with a range are `unknown`.
|
|
710
|
-
*/
|
|
711
|
-
declare function describeGitDiffSides(argv: readonly string[]): GitDiffSides;
|
|
712
|
-
declare function canonicalSourcePath(target: string): string;
|
|
713
|
-
/**
|
|
714
|
-
* `ReviewSourceIdentity.pathPrefix`: empty for root-relative output, the
|
|
715
|
-
* `--relative=<dir>` directory without trailing slashes, or for bare `--relative`
|
|
716
|
-
* the launch directory under the root (empty when outside the work tree, as in git).
|
|
154
|
+
* Compute payload statistics and check against configured thresholds.
|
|
155
|
+
* A maxFiles or maxTotalLines value of 0 disables that guard.
|
|
717
156
|
*/
|
|
718
|
-
declare function
|
|
719
|
-
/** The one mapping every reader, Apply and re-diff uses, so they all name the same file. */
|
|
720
|
-
declare function rootRelativeReviewedPath(identity: Pick<ReviewSourceIdentity, 'pathPrefix'>, filePath: string): string;
|
|
721
|
-
interface GitSourceIdentityOptions {
|
|
722
|
-
repository: string;
|
|
723
|
-
gitDiffArgv: readonly string[];
|
|
724
|
-
/** Defaults to the process's working directory. */
|
|
725
|
-
invocationCwd?: string;
|
|
726
|
-
/** `'remote'` for a materialized PR/MR; the git-mode machinery is the same. */
|
|
727
|
-
mode?: 'git' | 'remote';
|
|
728
|
-
}
|
|
729
|
-
/** Resolves the compared sides to commit SHAs. Never throws; an unresolvable side is `unknown`. */
|
|
730
|
-
declare function resolveGitSourceIdentity(options: GitSourceIdentityOptions): Promise<ReviewSourceIdentity>;
|
|
731
|
-
interface LocalSourceIdentityOptions {
|
|
732
|
-
type: 'directory' | 'file';
|
|
733
|
-
sourcePath: string;
|
|
734
|
-
/** Defaults to the process's working directory. */
|
|
735
|
-
invocationCwd?: string;
|
|
736
|
-
}
|
|
157
|
+
declare function computePayloadStats(fileCount: number, totalLines: number, config: Pick<AppConfig, 'maxFiles' | 'maxTotalLines'>): PayloadStats;
|
|
737
158
|
/**
|
|
738
|
-
*
|
|
739
|
-
* symlink the user named, recording its target once; its root is the parent of the path as given.
|
|
159
|
+
* Count total diff lines across all files and hunks.
|
|
740
160
|
*/
|
|
741
|
-
declare function
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
reviewedPaths: ReadonlySet<string>;
|
|
161
|
+
declare function countTotalLines(files: DiffFile[]): number;
|
|
162
|
+
interface GitDiffStats {
|
|
163
|
+
fileCount: number;
|
|
164
|
+
totalLines: number;
|
|
746
165
|
}
|
|
747
|
-
type
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
type ReviewedPathAuthorization = {
|
|
751
|
-
ok: true;
|
|
752
|
-
/** Restated from `sourceRoot` through the identity's prefix, normalized. */
|
|
753
|
-
relativePath: string;
|
|
754
|
-
sourceRoot: string;
|
|
755
|
-
} | {
|
|
756
|
-
ok: false;
|
|
757
|
-
reason: ReviewedPathRefusal;
|
|
758
|
-
message: string;
|
|
759
|
-
};
|
|
760
|
-
/** The one path check every front end delegates to; what passes is exactly what the readers open. */
|
|
761
|
-
declare function authorizeReviewedPath(source: ReviewedSnapshot, filePath: string): ReviewedPathAuthorization;
|
|
762
|
-
type SnapshotReadFailure = ReviewedPathRefusal
|
|
763
|
-
/** The side has no content (`none`) or could not be identified (`unknown`). */
|
|
764
|
-
| 'side-unavailable' | 'not-found'
|
|
765
|
-
/** A directory, FIFO, socket or device. */
|
|
766
|
-
| 'not-regular' | 'unsafe-link' | 'too-large' | 'read-failed';
|
|
767
|
-
type SnapshotReadResult = {
|
|
768
|
-
ok: true;
|
|
769
|
-
content: Buffer;
|
|
166
|
+
type GitDiffStatsResult = {
|
|
167
|
+
available: true;
|
|
168
|
+
stats: GitDiffStats;
|
|
770
169
|
} | {
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
message: string;
|
|
170
|
+
available: false;
|
|
171
|
+
error: unknown;
|
|
774
172
|
};
|
|
775
|
-
interface SnapshotReadOptions {
|
|
776
|
-
/** Defaults to `MAX_SOURCE_FILE_BYTES`. */
|
|
777
|
-
maxBytes?: number;
|
|
778
|
-
}
|
|
779
|
-
/** A blob from the object store, or the file under the physical source root; authorized first. */
|
|
780
|
-
declare function readReviewedContent(source: ReviewedSnapshot, filePath: string, side: 'old' | 'new', options?: SnapshotReadOptions): Promise<SnapshotReadResult>;
|
|
781
|
-
|
|
782
|
-
/**
|
|
783
|
-
* `project` config is repository data and is trusted less than the reviewer's own `user` config.
|
|
784
|
-
*/
|
|
785
|
-
type ConfigValueOrigin = 'default' | 'user' | 'project';
|
|
786
|
-
type ConfigProvenance = Readonly<Record<keyof AppConfig, ConfigValueOrigin>>;
|
|
787
|
-
interface ConfigSource {
|
|
788
|
-
origin: 'user' | 'project';
|
|
789
|
-
path: string;
|
|
790
|
-
}
|
|
791
|
-
interface LoadedConfig {
|
|
792
|
-
config: AppConfig;
|
|
793
|
-
provenance: ConfigProvenance;
|
|
794
|
-
sources: ConfigSource[];
|
|
795
|
-
}
|
|
796
|
-
interface LoadConfigOptions {
|
|
797
|
-
cwd?: string;
|
|
798
|
-
homeDir?: string;
|
|
799
|
-
}
|
|
800
|
-
/** Project overrides user overrides defaults; an invalid value is not attributed to its file. */
|
|
801
|
-
declare function loadConfigWithProvenance(options?: LoadConfigOptions): LoadedConfig;
|
|
802
|
-
declare function loadConfig(options?: LoadConfigOptions): AppConfig;
|
|
803
|
-
|
|
804
173
|
/**
|
|
805
|
-
*
|
|
806
|
-
*
|
|
174
|
+
* Bounded --numstat lookup. Unavailable statistics are distinct from a genuinely empty diff.
|
|
175
|
+
* Abort and timeout reject with CommandCancelledError instead of becoming an empty result.
|
|
807
176
|
*/
|
|
808
|
-
declare function
|
|
177
|
+
declare function getGitDiffStatsResult(args: string[], repoRoot: string, options?: GitExecutionOptions): Promise<GitDiffStatsResult>;
|
|
809
178
|
/**
|
|
810
|
-
*
|
|
179
|
+
* Compatibility lookup: failures still warn and return zeros so existing guards do not block.
|
|
180
|
+
* Use getGitDiffStatsResult to distinguish failure from an empty diff. Cancellation requested
|
|
181
|
+
* through the additive execution options propagates; the historical default timeout falls back.
|
|
811
182
|
*/
|
|
812
|
-
declare function
|
|
813
|
-
/**
|
|
814
|
-
* Get git diff stats cheaply using --numstat (avoids full diff parsing).
|
|
815
|
-
* Each output line is "added\tremoved\tfilename".
|
|
816
|
-
* Returns file count and total changed lines (added + removed).
|
|
817
|
-
*/
|
|
818
|
-
declare function getGitDiffStats(args: string[], repoRoot: string): Promise<{
|
|
819
|
-
fileCount: number;
|
|
820
|
-
totalLines: number;
|
|
821
|
-
}>;
|
|
183
|
+
declare function getGitDiffStats(args: string[], repoRoot: string, options?: GitExecutionOptions): Promise<GitDiffStats>;
|
|
822
184
|
|
|
823
185
|
/**
|
|
824
186
|
* Create a filter function from gitignore-compatible patterns.
|
|
@@ -833,99 +195,7 @@ declare function createIgnoreFilter(patterns: string[]): (path: string) => boole
|
|
|
833
195
|
* Returns true if the directory exists and the process has write permission,
|
|
834
196
|
* false otherwise (including non-existent directories).
|
|
835
197
|
*/
|
|
836
|
-
declare function checkWritability(filePath: string): boolean;
|
|
837
|
-
|
|
838
|
-
/**
|
|
839
|
-
* Why an apply was refused. Every value is a structural fact about the
|
|
840
|
-
* request or the file — never a fragment of the file's contents, so a
|
|
841
|
-
* refusal is safe to surface in the UI and in logs.
|
|
842
|
-
*/
|
|
843
|
-
type ApplyRefusalReason =
|
|
844
|
-
/** The suggestion is file-level: there is nothing to replace. */
|
|
845
|
-
'no-anchor'
|
|
846
|
-
/**
|
|
847
|
-
* The anchor names deleted lines (`side: 'old'`). Those lines are not in
|
|
848
|
-
* the working file, and the app holds no old→new line mapping, so the
|
|
849
|
-
* target is undefined rather than merely missing.
|
|
850
|
-
*/
|
|
851
|
-
| 'old-side-anchor'
|
|
852
|
-
/** Unknown side, non-positive or non-integer bounds, or reversed; checked before any I/O. */
|
|
853
|
-
| 'invalid-anchor'
|
|
854
|
-
/** `destinationRoot` is relative; resolving it would consult the cwd. */
|
|
855
|
-
| 'destination-not-absolute' | 'destination-missing'
|
|
856
|
-
/** `filePath` resolves outside `destinationRoot`. */
|
|
857
|
-
| 'path-escapes-destination' | 'control-file'
|
|
858
|
-
/** A link on the way or at the leaf, a hard-linked or special file, or a swap during the open. */
|
|
859
|
-
| 'unsafe-target'
|
|
860
|
-
/** Replacing the file would change its owner, which this process cannot restore. */
|
|
861
|
-
| 'unsupported-target'
|
|
862
|
-
/** No file at the resolved path. */
|
|
863
|
-
| 'file-missing'
|
|
864
|
-
/** The path exists but could not be read (permissions, a directory, …). */
|
|
865
|
-
| 'file-unreadable'
|
|
866
|
-
/**
|
|
867
|
-
* The file is not valid UTF-8. Rewriting it would round-trip its bytes
|
|
868
|
-
* through a lossy decode and corrupt regions outside the anchor.
|
|
869
|
-
*/
|
|
870
|
-
| 'file-not-utf8'
|
|
871
|
-
/** The anchor falls outside the file's line count. */
|
|
872
|
-
| 'anchor-out-of-range'
|
|
873
|
-
/** The anchored lines no longer match `suggestion.originalCode`. */
|
|
874
|
-
| 'context-mismatch'
|
|
875
|
-
/** The file was replaced or rewritten between the read and the commit. */
|
|
876
|
-
| 'file-changed'
|
|
877
|
-
/** The context matched but the write itself failed. */
|
|
878
|
-
| 'write-failed';
|
|
879
|
-
interface ApplySuggestionRequest {
|
|
880
|
-
/**
|
|
881
|
-
* Absolute path of the directory the reviewed files live in. Always
|
|
882
|
-
* supplied by the caller: a git-mode working tree, a directory-mode root,
|
|
883
|
-
* a reused clone, or the destination the user picked for a temporary-clone
|
|
884
|
-
* review. Never derived here.
|
|
885
|
-
*/
|
|
886
|
-
destinationRoot: string;
|
|
887
|
-
/** Path of the file to modify, relative to `destinationRoot`. */
|
|
888
|
-
filePath: string;
|
|
889
|
-
/** The comment's anchor. `null` (file-level) is refused. */
|
|
890
|
-
lineRange: LineRange | null;
|
|
891
|
-
suggestion: Suggestion;
|
|
892
|
-
}
|
|
893
|
-
interface ApplySuggestionOptions {
|
|
894
|
-
fs?: FsLayer;
|
|
895
|
-
randomName?: () => string;
|
|
896
|
-
}
|
|
897
|
-
interface ApplySuggestionApplied {
|
|
898
|
-
status: 'applied';
|
|
899
|
-
/** Echoed from the request, so a batch caller can attribute the result. */
|
|
900
|
-
filePath: string;
|
|
901
|
-
absolutePath: string;
|
|
902
|
-
/** How many on-disk lines the proposal replaced. */
|
|
903
|
-
replacedLines: number;
|
|
904
|
-
}
|
|
905
|
-
interface ApplySuggestionRefused {
|
|
906
|
-
status: 'refused';
|
|
907
|
-
filePath: string;
|
|
908
|
-
reason: ApplyRefusalReason;
|
|
909
|
-
/** One sentence naming the refusal, safe to show to the reviewer. */
|
|
910
|
-
detail: string;
|
|
911
|
-
}
|
|
912
|
-
type ApplySuggestionResult = ApplySuggestionApplied | ApplySuggestionRefused;
|
|
913
|
-
/**
|
|
914
|
-
* A `.git` segment at any depth, directory or worktree file: git executes what is in there. `.gitmodules`
|
|
915
|
-
* and the like are reviewed content, gated by diff membership in the session handler instead.
|
|
916
|
-
*/
|
|
917
|
-
declare function isRepositoryControlPath(filePath: string): boolean;
|
|
918
|
-
/**
|
|
919
|
-
* Apply one anchored suggestion to one file under `destinationRoot`.
|
|
920
|
-
*
|
|
921
|
-
* On a byte-for-byte match between the anchored lines and
|
|
922
|
-
* `suggestion.originalCode`, the anchored lines are replaced with
|
|
923
|
-
* `suggestion.proposedCode` and the file is rewritten. Lines outside the
|
|
924
|
-
* anchor keep their exact bytes, including their line terminators, and the
|
|
925
|
-
* file's trailing-newline state is preserved either way. Any other outcome
|
|
926
|
-
* refuses with a reason and writes nothing.
|
|
927
|
-
*/
|
|
928
|
-
declare function applySuggestion(request: ApplySuggestionRequest, options?: ApplySuggestionOptions): ApplySuggestionResult;
|
|
198
|
+
declare function checkWritability(filePath: string, fs?: Pick<FsLayer, 'accessSync' | 'lstatSync'>): boolean;
|
|
929
199
|
|
|
930
200
|
/**
|
|
931
201
|
* File-type detection utilities.
|
|
@@ -999,233 +269,12 @@ declare function mapThreadsToReviewComments(threads: ForgeThread[], diffFiles?:
|
|
|
999
269
|
*/
|
|
1000
270
|
declare function createGitLabProvider(runCommand: ForgeCommandRunner): ForgeProvider;
|
|
1001
271
|
|
|
1002
|
-
/**
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
repoPath: string;
|
|
1008
|
-
/** Resolved SHA of the PR/MR base branch tip. */
|
|
1009
|
-
baseSha: string;
|
|
1010
|
-
/** Resolved SHA of the PR/MR head (the live remote head). */
|
|
1011
|
-
headSha: string;
|
|
1012
|
-
mode: MaterializeMode;
|
|
1013
|
-
/**
|
|
1014
|
-
* Refs this session created in a reused clone and deletes on cleanup; empty for a temp clone.
|
|
1015
|
-
*/
|
|
1016
|
-
ownedRefs: readonly string[];
|
|
1017
|
-
/**
|
|
1018
|
-
* Removes the temp clone (synchronously, before the first await, so an `exit`
|
|
1019
|
-
* handler that cannot wait still gets that far) and deletes the session's refs
|
|
1020
|
-
* from a reused clone. Idempotent, never rejects; a failed deletion goes to stderr.
|
|
1021
|
-
*/
|
|
1022
|
-
cleanup: () => Promise<void>;
|
|
1023
|
-
}
|
|
1024
|
-
/** A local clone whose fetch remote matches the requested forge repository. */
|
|
1025
|
-
interface ExistingClone {
|
|
1026
|
-
repoPath: string;
|
|
1027
|
-
remoteName: string;
|
|
272
|
+
/** The effects expansion needs; callers and tests can supply runners/readers without module mocks. */
|
|
273
|
+
interface ContextExpansionDependencies {
|
|
274
|
+
runDiff(args: string[], cwd: string, options?: GitExecutionOptions): Promise<string>;
|
|
275
|
+
readContent: typeof readReviewedContent;
|
|
276
|
+
report(message: string, error?: unknown): void;
|
|
1028
277
|
}
|
|
1029
|
-
interface MaterializeOptions {
|
|
1030
|
-
/**
|
|
1031
|
-
* Aborting kills the command in flight and rejects with {@link CommandCancelledError}; the temp
|
|
1032
|
-
* clone is removed first.
|
|
1033
|
-
*/
|
|
1034
|
-
signal?: AbortSignal;
|
|
1035
|
-
/** Defaults to {@link DEFAULT_GIT_COMMAND_TIMEOUT_MS}. */
|
|
1036
|
-
commandTimeoutMs?: number;
|
|
1037
|
-
}
|
|
1038
|
-
/**
|
|
1039
|
-
* Generous because a blobless clone over a slow link is legitimately slow; tighter hosts abort via
|
|
1040
|
-
* the signal.
|
|
1041
|
-
*/
|
|
1042
|
-
declare const DEFAULT_GIT_COMMAND_TIMEOUT_MS: number;
|
|
1043
|
-
/**
|
|
1044
|
-
* Default runner: spawns the real binary. Rejects on spawn failure, on output over
|
|
1045
|
-
* the buffer cap, and with {@link CommandCancelledError} on abort or timeout (SIGTERM,
|
|
1046
|
-
* then SIGKILL after {@link KILL_GRACE_MS}; settles once the child exited).
|
|
1047
|
-
*
|
|
1048
|
-
* Deliberately not in its own process group: that would detach the controlling
|
|
1049
|
-
* terminal and silently disable git's and ssh's credential prompts.
|
|
1050
|
-
*/
|
|
1051
|
-
declare const defaultGitRunner: ForgeCommandRunner;
|
|
1052
|
-
/**
|
|
1053
|
-
* Detect an existing clone: when `cwd` is inside a git repository with a
|
|
1054
|
-
* remote matching the forge URL, return `{ repoPath, remoteName }`.
|
|
1055
|
-
*/
|
|
1056
|
-
declare function detectExistingClone(url: ForgeUrl, cwd: string, runner?: ForgeCommandRunner, options?: MaterializeOptions): Promise<ExistingClone | null>;
|
|
1057
|
-
/**
|
|
1058
|
-
* Materialize a forge PR/MR into a local git context.
|
|
1059
|
-
*
|
|
1060
|
-
* When `cwd` is inside a git repository with a remote matching the forge
|
|
1061
|
-
* URL (SSH and HTTPS forms recognized, `.git` suffix tolerated), the base
|
|
1062
|
-
* branch and PR/MR head refs are fetched into that clone under
|
|
1063
|
-
* `refs/self-review/<session>/` (read-only for the working tree; `cleanup()`
|
|
1064
|
-
* deletes exactly those two refs). Otherwise a blobless clone is created in a
|
|
1065
|
-
* unique directory under the OS temp root and `cleanup()` removes it. Callers
|
|
1066
|
-
* that already detected a clone may pass it to skip the git probes.
|
|
1067
|
-
*
|
|
1068
|
-
* The returned `headSha` is the live remote head, so callers can compare it
|
|
1069
|
-
* against a recorded `remote-head-sha` for drift detection.
|
|
1070
|
-
*/
|
|
1071
|
-
declare function materialize(url: ForgeUrl, baseBranch: string, cwd: string, runner?: ForgeCommandRunner, existingClone?: ExistingClone | null, options?: MaterializeOptions): Promise<MaterializeResult>;
|
|
1072
|
-
/**
|
|
1073
|
-
* Git-only fallback for the base branch when no forge CLI is available:
|
|
1074
|
-
* resolves the remote's default branch from its HEAD symref via
|
|
1075
|
-
* `git ls-remote --symref <remote> HEAD`. When an existing matching clone
|
|
1076
|
-
* is supplied, the configured remote is used so its SSH/HTTPS transport
|
|
1077
|
-
* and credentials are preserved. Otherwise the forge HTTPS URL is used.
|
|
1078
|
-
* No forge API involved.
|
|
1079
|
-
*/
|
|
1080
|
-
declare function resolveRemoteDefaultBranch(url: ForgeUrl, runner?: ForgeCommandRunner, existing?: ExistingClone | null, options?: MaterializeOptions): Promise<string>;
|
|
1081
|
-
|
|
1082
|
-
/**
|
|
1083
|
-
* The state a single review session owns. One desktop application window is
|
|
1084
|
-
* one session; two sessions are independent and cannot observe each other.
|
|
1085
|
-
*/
|
|
1086
|
-
interface ReviewSession {
|
|
1087
|
-
reviewState: ReviewState | null;
|
|
1088
|
-
diffData: DiffLoadPayload | null;
|
|
1089
|
-
guideData: GuideLoadPayload | null;
|
|
1090
|
-
config: AppConfig | null;
|
|
1091
|
-
outputPathInfo: OutputPathInfo | null;
|
|
1092
|
-
resumeComments: ReviewComment[];
|
|
1093
|
-
resumeViewedFiles: string[];
|
|
1094
|
-
resumeRemoteDrift: RemoteDriftInfo | null;
|
|
1095
|
-
resumeImportDiagnostics: string[];
|
|
1096
|
-
/**
|
|
1097
|
-
* Destination directory the user named for this session's applies, or
|
|
1098
|
-
* null when none has been named. Only a temporary-clone remote review
|
|
1099
|
-
* needs one; see {@link resolveApplyDestination}.
|
|
1100
|
-
*/
|
|
1101
|
-
applyDestinationRoot: string | null;
|
|
1102
|
-
/**
|
|
1103
|
-
* Old and new path of every file in the committed diff, frozen by {@link commitDiffData}.
|
|
1104
|
-
* The authorization set for writes; resumed comments, submitted state and placeholder
|
|
1105
|
-
* entries can name other paths and never reach it.
|
|
1106
|
-
*/
|
|
1107
|
-
reviewedPaths: ReadonlySet<string>;
|
|
1108
|
-
/**
|
|
1109
|
-
* Recorded by {@link commitDiffData}; null until then (and for welcome), when every read of
|
|
1110
|
-
* reviewed content refuses.
|
|
1111
|
-
*/
|
|
1112
|
-
sourceIdentity: ReviewSourceIdentity | null;
|
|
1113
|
-
/**
|
|
1114
|
-
* Resumed reference to absolute path beside *the resumed document*; authorizes reads and tells
|
|
1115
|
-
* the publisher which bytes to carry. Never sent to the front end.
|
|
1116
|
-
*/
|
|
1117
|
-
attachmentOrigins: AttachmentOrigins;
|
|
1118
|
-
}
|
|
1119
|
-
/** Create an empty session. */
|
|
1120
|
-
declare function createReviewSession(): ReviewSession;
|
|
1121
|
-
/**
|
|
1122
|
-
* The one place a diff is committed to a session: captures `reviewedPaths` and
|
|
1123
|
-
* records `sourceIdentity`; later `diffData` edits (expanded hunks) leave both alone.
|
|
1124
|
-
* The identity comes from the loader, and is `null` only for a payload that
|
|
1125
|
-
* reviews nothing (welcome), so reads refuse rather than guess a root.
|
|
1126
|
-
*/
|
|
1127
|
-
declare function commitDiffData(session: ReviewSession, payload: DiffLoadPayload, identity: ReviewSourceIdentity | null): void;
|
|
1128
|
-
/**
|
|
1129
|
-
* The old side is where a deletion or a rename's old name lives. Null when the diff has no such
|
|
1130
|
-
* file.
|
|
1131
|
-
*/
|
|
1132
|
-
declare function locateReviewedFile(session: ReviewSession, filePath: string): {
|
|
1133
|
-
file: DiffFile;
|
|
1134
|
-
side: 'old' | 'new';
|
|
1135
|
-
} | null;
|
|
1136
|
-
/**
|
|
1137
|
-
* Prepare a DiffLoadPayload for IPC transmission.
|
|
1138
|
-
* In large-payload mode, strips hunks from files to reduce initial transfer size.
|
|
1139
|
-
* The full data stays in the session for on-demand loading via DIFF_LOAD_FILE.
|
|
1140
|
-
*/
|
|
1141
|
-
declare function preparePayload(payload: DiffLoadPayload): DiffLoadPayload;
|
|
1142
|
-
/**
|
|
1143
|
-
* Resolve what a diff request should deliver: the prepared diff payload and,
|
|
1144
|
-
* when one is loaded, the guide that rides with it. Returns null when the
|
|
1145
|
-
* session has no diff, so the caller sends nothing at all.
|
|
1146
|
-
*/
|
|
1147
|
-
declare function getDiffLoad(session: ReviewSession): {
|
|
1148
|
-
diff: DiffLoadPayload;
|
|
1149
|
-
guide: GuideLoadPayload | null;
|
|
1150
|
-
} | null;
|
|
1151
|
-
/** The read-only source root; {@link resolveApplyDestination} decides where applies write. */
|
|
1152
|
-
declare function resolveSourceBaseDir(session: ReviewSession): string | null;
|
|
1153
|
-
/**
|
|
1154
|
-
* Reads from the snapshot the review compared, never the current working tree; only reviewed,
|
|
1155
|
-
* previewable paths are read.
|
|
1156
|
-
*/
|
|
1157
|
-
declare function loadImage(session: ReviewSession, filePath: string): Promise<ImageLoadResult>;
|
|
1158
|
-
/**
|
|
1159
|
-
* Return a single file's hunks for lazy (large-payload) mode, or null when the
|
|
1160
|
-
* session has no diff or the diff has no such file.
|
|
1161
|
-
*/
|
|
1162
|
-
declare function getFileHunks(session: ReviewSession, filePath: string): DiffHunk[] | null;
|
|
1163
|
-
/**
|
|
1164
|
-
* Resolve the config and the output path info that travel with it. Returns null
|
|
1165
|
-
* when the session has no config, so the caller sends nothing at all: the
|
|
1166
|
-
* renderer distinguishes an absent message from an empty one.
|
|
1167
|
-
*/
|
|
1168
|
-
declare function getConfigLoad(session: ReviewSession): {
|
|
1169
|
-
config: AppConfig;
|
|
1170
|
-
outputPathInfo: OutputPathInfo | null;
|
|
1171
|
-
} | null;
|
|
1172
|
-
/**
|
|
1173
|
-
* Store a review state submitted by the front end on the session.
|
|
1174
|
-
*/
|
|
1175
|
-
declare function submitReviewState(session: ReviewSession, state: ReviewState): void;
|
|
1176
|
-
/**
|
|
1177
|
-
* Take the submitted review state off the session, clearing it so it is
|
|
1178
|
-
* consumed exactly once. Returns null when nothing has been submitted.
|
|
1179
|
-
*/
|
|
1180
|
-
declare function takeReviewState(session: ReviewSession): ReviewState | null;
|
|
1181
|
-
/**
|
|
1182
|
-
* The directory an apply may write into for this session, or null when the
|
|
1183
|
-
* session has none.
|
|
1184
|
-
*
|
|
1185
|
-
* For every review whose files sit in a place the user controls — a git
|
|
1186
|
-
* working tree, a scanned directory, a reused remote clone — that is the
|
|
1187
|
-
* root the reviewed paths are relative to, and no one is asked anything.
|
|
1188
|
-
*
|
|
1189
|
-
* A temporary-clone review is the one exception. Its files live in a
|
|
1190
|
-
* directory the app deletes on exit, so the clone is never a destination:
|
|
1191
|
-
* the answer is the directory the user named, and null until they name one.
|
|
1192
|
-
*/
|
|
1193
|
-
declare function resolveApplyDestination(session: ReviewSession): string | null;
|
|
1194
|
-
/**
|
|
1195
|
-
* Apply one suggestion to the reviewed working file, or refuse and write
|
|
1196
|
-
* nothing. The engine does the work; this handler names the destination, which
|
|
1197
|
-
* the engine never derives, and authorizes the target.
|
|
1198
|
-
*
|
|
1199
|
-
* Authorization is membership in {@link ReviewSession.reviewedPaths}
|
|
1200
|
-
* (`not-reviewed` otherwise), so a resumed document or a client reaching this
|
|
1201
|
-
* handler cannot name an unreviewed file. The request is not bound to a
|
|
1202
|
-
* comment (the session keeps no registry of live suggestions); the binding is
|
|
1203
|
-
* the anchor plus the engine's byte-exact `originalCode` match.
|
|
1204
|
-
*
|
|
1205
|
-
* The engine gets the path through the identity's prefix, so a `--relative`
|
|
1206
|
-
* review of `sub/` writes `sub/<path>`, never the root's same-named file.
|
|
1207
|
-
*
|
|
1208
|
-
* A refusal travels as a value, never a thrown error.
|
|
1209
|
-
*/
|
|
1210
|
-
declare function applySuggestionForSession(session: ReviewSession, request: SuggestionApplyRequest): SuggestionApplyOutcome;
|
|
1211
|
-
/**
|
|
1212
|
-
* Records that resumed attachments live beside the resumed document, whatever the
|
|
1213
|
-
* launch directory or save location. Returns one diagnostic per reference that is
|
|
1214
|
-
* not `.self-review-assets/<name>` and so will never be read.
|
|
1215
|
-
*/
|
|
1216
|
-
declare function recordResumedAttachments(session: ReviewSession, comments: readonly ReviewComment[], resumeDocumentPath: string): string[];
|
|
1217
|
-
/**
|
|
1218
|
-
* Read one attachment by its `.self-review-assets/<name>` reference, never a path:
|
|
1219
|
-
* an imported one from its recorded origin, any other from the current output's asset
|
|
1220
|
-
* directory. Anything else is `not-authorized` and touches nothing.
|
|
1221
|
-
*/
|
|
1222
|
-
declare function readAttachment(session: ReviewSession, reference: unknown): Promise<AttachmentReadResult>;
|
|
1223
|
-
/**
|
|
1224
|
-
* Resolve the resumed comments, viewed files and remote drift for a session.
|
|
1225
|
-
* Returns null when there is nothing to resume, so the caller sends nothing
|
|
1226
|
-
* at all.
|
|
1227
|
-
*/
|
|
1228
|
-
declare function getResumeLoad(session: ReviewSession): ResumeLoadPayload | null;
|
|
1229
278
|
/**
|
|
1230
279
|
* Re-run the review's own git diff over one file with more context, via
|
|
1231
280
|
* {@link singleFileRediffArgs}. Git runs at the source root; a `--relative` review is
|
|
@@ -1236,101 +285,12 @@ declare function getResumeLoad(session: ReviewSession): ResumeLoadPayload | null
|
|
|
1236
285
|
* Expanded hunks are written back to the session's diff data. Returns null when
|
|
1237
286
|
* there is no git diff or tracked file, git's output lacks the file, or git fails.
|
|
1238
287
|
*/
|
|
1239
|
-
declare function expandContext(session: ReviewSession, request: ExpandContextRequest
|
|
288
|
+
declare function expandContext(session: Pick<ReviewSession, 'diffData' | 'sourceIdentity' | 'reviewedPaths' | 'loadedReview'>, request: ExpandContextRequest, dependencies?: ContextExpansionDependencies, options?: GitExecutionOptions & {
|
|
289
|
+
budgets?: Partial<SourceBudgets>;
|
|
290
|
+
}): Promise<{
|
|
1240
291
|
hunks: DiffHunk[];
|
|
1241
292
|
totalLines: number;
|
|
1242
293
|
} | null>;
|
|
1243
|
-
/**
|
|
1244
|
-
* What a review start produced: the payload built from the scanned path, the
|
|
1245
|
-
* stats it was measured against (null when the session has no config, in which
|
|
1246
|
-
* case no thresholds apply), and whether those stats exceeded a threshold.
|
|
1247
|
-
*
|
|
1248
|
-
* The payload is deliberately *not* stored on the session: the caller may still
|
|
1249
|
-
* need to abandon it (a user declining a large review keeps the review they
|
|
1250
|
-
* were already looking at), so committing it is the caller's decision.
|
|
1251
|
-
*/
|
|
1252
|
-
interface ReviewStartResult {
|
|
1253
|
-
payload: DiffLoadPayload;
|
|
1254
|
-
identity: ReviewSourceIdentity;
|
|
1255
|
-
stats: PayloadStats | null;
|
|
1256
|
-
exceedsThresholds: boolean;
|
|
1257
|
-
}
|
|
1258
|
-
/**
|
|
1259
|
-
* Scan a picked path and build the diff payload for a directory (or single
|
|
1260
|
-
* file) review, measured against the session's large-payload thresholds.
|
|
1261
|
-
* Nothing is stored on the session — see `ReviewStartResult`.
|
|
1262
|
-
*/
|
|
1263
|
-
declare function prepareDirectoryReview(session: ReviewSession, directoryPath: string): Promise<ReviewStartResult>;
|
|
1264
|
-
/**
|
|
1265
|
-
* Commit a prepared review payload to the session, once the caller has decided
|
|
1266
|
-
* it should proceed. Returns the payload to hand to the transport.
|
|
1267
|
-
*/
|
|
1268
|
-
declare function commitReviewStart(session: ReviewSession, payload: DiffLoadPayload, identity: ReviewSourceIdentity | null): DiffLoadPayload;
|
|
1269
|
-
|
|
1270
|
-
/**
|
|
1271
|
-
* What a review starts from; `welcome` means nothing to review (desktop shows its picker, serve
|
|
1272
|
-
* refuses).
|
|
1273
|
-
*/
|
|
1274
|
-
type StartupSource = {
|
|
1275
|
-
mode: 'git';
|
|
1276
|
-
} | {
|
|
1277
|
-
mode: 'directory';
|
|
1278
|
-
sourcePath: string;
|
|
1279
|
-
} | {
|
|
1280
|
-
mode: 'file';
|
|
1281
|
-
sourcePath: string;
|
|
1282
|
-
} | {
|
|
1283
|
-
mode: 'welcome';
|
|
1284
|
-
};
|
|
1285
|
-
/**
|
|
1286
|
-
* The candidate is the first *positional* by the shared classifier, so `-S src/x.ts` never selects
|
|
1287
|
-
* a file.
|
|
1288
|
-
*/
|
|
1289
|
-
declare function resolveStartupSource(gitDiffArgs: readonly string[], cwd?: string): StartupSource;
|
|
1290
|
-
/** The mode alone; see {@link resolveStartupSource} for the source path. */
|
|
1291
|
-
declare function determineMode(gitDiffArgs: string[]): 'git' | 'directory' | 'file' | 'welcome';
|
|
1292
|
-
|
|
1293
|
-
/**
|
|
1294
|
-
* A CLI path or the reviewer's user-level `output-file` is explicit and may point anywhere.
|
|
1295
|
-
* Project `output-file` or the default is inherited and contained under `cwd`, since a
|
|
1296
|
-
* repository could otherwise redirect the save (audit A5).
|
|
1297
|
-
*/
|
|
1298
|
-
declare function resolveOutputTarget(explicitPath: string | null, loaded: LoadedConfig, cwd: string): ReviewOutputTarget;
|
|
1299
|
-
declare function publishOptionsFor(target: ReviewOutputTarget, attachmentOrigins?: AttachmentOrigins): PublishReviewOptions;
|
|
1300
|
-
/**
|
|
1301
|
-
* Project `default-diff-args` would make git write a file or run a program; thrown before any git
|
|
1302
|
-
* command.
|
|
1303
|
-
*/
|
|
1304
|
-
declare class ConfiguredDiffArgsError extends Error {
|
|
1305
|
-
readonly options: readonly string[];
|
|
1306
|
-
readonly configPath: string;
|
|
1307
|
-
constructor(options: readonly string[], configPath: string);
|
|
1308
|
-
}
|
|
1309
|
-
interface ResolvedDiffArgs {
|
|
1310
|
-
gitDiffArgs: string[];
|
|
1311
|
-
origin: 'cli' | ConfigValueOrigin;
|
|
1312
|
-
config: AppConfig;
|
|
1313
|
-
}
|
|
1314
|
-
/**
|
|
1315
|
-
* The CLI's arguments, else `default-diff-args` split with shell quoting. Project-supplied
|
|
1316
|
-
* ones are refused with {@link ConfiguredDiffArgsError} if write-capable; the
|
|
1317
|
-
* reviewer's own are not.
|
|
1318
|
-
*/
|
|
1319
|
-
declare function resolveStartupDiffArgs(cliGitDiffArgs: readonly string[], loaded: LoadedConfig, cwd: string): ResolvedDiffArgs;
|
|
1320
|
-
interface LoadedLocalReview {
|
|
1321
|
-
payload: DiffLoadPayload;
|
|
1322
|
-
identity: ReviewSourceIdentity | null;
|
|
1323
|
-
}
|
|
1324
|
-
/**
|
|
1325
|
-
* Diagnostics ride on the payload and go to `log`, so a failed load never reads as empty. A welcome
|
|
1326
|
-
* source yields no identity.
|
|
1327
|
-
*/
|
|
1328
|
-
declare function loadLocalReview(source: StartupSource, gitDiffArgs: readonly string[], config: AppConfig, cwd: string, log: (message: string) => void): Promise<LoadedLocalReview>;
|
|
1329
|
-
/**
|
|
1330
|
-
* Throws `ReviewXmlError` for an unreadable document. Returns it for what the host still needs (the
|
|
1331
|
-
* remote head, for drift).
|
|
1332
|
-
*/
|
|
1333
|
-
declare function loadResumeDocument(session: ReviewSession, resumePath: string): ParsedReview;
|
|
1334
294
|
|
|
1335
295
|
interface ApplicationOptionsSpec<V extends string, B extends string> {
|
|
1336
296
|
/** Spelling to field. Long flags take `--flag value` or `--flag=value`; short ones `-o value`. */
|
|
@@ -1354,52 +314,6 @@ declare class ApplicationOptionError extends Error {
|
|
|
1354
314
|
*/
|
|
1355
315
|
declare function extractApplicationOptions<V extends string, B extends string = never>(argv: readonly string[], spec: ApplicationOptionsSpec<V, B>): ExtractedApplicationOptions<V, B>;
|
|
1356
316
|
|
|
1357
|
-
/**
|
|
1358
|
-
* Derive the guide sidecar path from the resolved output path: strip the
|
|
1359
|
-
* last extension and append `.guide.xml` (`review.xml` →
|
|
1360
|
-
* `review.guide.xml`). An output filename with no extension gets
|
|
1361
|
-
* `.guide.xml` appended verbatim.
|
|
1362
|
-
*/
|
|
1363
|
-
declare function deriveGuidePath(outputPath: string): string;
|
|
1364
|
-
/**
|
|
1365
|
-
* Resolve where to look for the guide: the `guide-file` config override
|
|
1366
|
-
* (resolved against cwd, like `output-file`) when set, otherwise the path
|
|
1367
|
-
* derived from the resolved output path.
|
|
1368
|
-
*/
|
|
1369
|
-
declare function resolveGuidePath(outputPath: string, config: Pick<AppConfig, 'guideFile'>): string;
|
|
1370
|
-
/**
|
|
1371
|
-
* Discover, read, parse, validate, and reconcile the guide sidecar.
|
|
1372
|
-
*
|
|
1373
|
-
* Returns the display-ready payload, or null when there is no usable
|
|
1374
|
-
* guide. Missing file: silent. Unreadable or invalid file: exactly one
|
|
1375
|
-
* `console.error()` line (guide path + reason class). Never throws.
|
|
1376
|
-
*/
|
|
1377
|
-
declare function loadGuide(outputPath: string, config: Pick<AppConfig, 'guideFile'>, diffFilePaths: string[]): Promise<GuideLoadPayload | null>;
|
|
1378
|
-
|
|
1379
|
-
interface LoadGitDiffOptions {
|
|
1380
|
-
/**
|
|
1381
|
-
* Include untracked working-tree files as synthetic additions. Defaults
|
|
1382
|
-
* to true (local git mode). Remote mode passes false: a base...head diff
|
|
1383
|
-
* of a PR/MR must never pick up unrelated local untracked files.
|
|
1384
|
-
*/
|
|
1385
|
-
includeUntracked?: boolean;
|
|
1386
|
-
budgets?: Partial<SourceBudgets>;
|
|
1387
|
-
}
|
|
1388
|
-
interface LoadGitDiffResult {
|
|
1389
|
-
files: DiffFile[];
|
|
1390
|
-
repository: string;
|
|
1391
|
-
/** What the diff compared; previews and line counts read this snapshot, not the working tree. */
|
|
1392
|
-
identity: ReviewSourceIdentity;
|
|
1393
|
-
/** What could not be shown faithfully; front ends show these instead of "no changes". */
|
|
1394
|
-
diagnostics: string[];
|
|
1395
|
-
}
|
|
1396
|
-
/**
|
|
1397
|
-
* Tracked wins on a path collision (after `git rm --cached f`, `f` is both a
|
|
1398
|
-
* deletion and untracked); two entries would share React keys and comment state.
|
|
1399
|
-
*/
|
|
1400
|
-
declare function dedupeUntrackedByPath(tracked: DiffFile[], untracked: DiffFile[]): DiffFile[];
|
|
1401
|
-
declare function loadGitDiffWithUntracked(gitDiffArgs: string[], cwd?: string, options?: LoadGitDiffOptions): Promise<LoadGitDiffResult>;
|
|
1402
|
-
|
|
1403
317
|
/**
|
|
1404
318
|
* In staged-mode reviews (--staged / --cached), untracked files are not
|
|
1405
319
|
* part of the index and should be hidden by default. If the user has
|
|
@@ -1440,28 +354,8 @@ declare function classifyGitDiffArgs(args: string[]): {
|
|
|
1440
354
|
positionalIndices: number[];
|
|
1441
355
|
hasSeparator: boolean;
|
|
1442
356
|
};
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
* filesystem path. This makes the args unambiguous so downstream code
|
|
1446
|
-
* (expand-context) never confuses a path for a revision.
|
|
1447
|
-
*
|
|
1448
|
-
* Idempotent: an explicit `--` separator leaves the args unchanged.
|
|
1449
|
-
*/
|
|
1450
|
-
declare function normalizeGitDiffArgs(args: string[], cwd?: string): string[];
|
|
1451
|
-
/**
|
|
1452
|
-
* Split a configured argument string into argv the way a shell would, so a
|
|
1453
|
-
* quoted path or search string survives as one argument.
|
|
1454
|
-
*
|
|
1455
|
-
* Two callers rely on this: `default-diff-args` from YAML, which people write
|
|
1456
|
-
* with shell quoting, and the `git-diff-args` string carried on a git diff
|
|
1457
|
-
* source, which `formatGitDiffArgs` writes in the same syntax. Unquoted input
|
|
1458
|
-
* splits on whitespace exactly as a plain split did, so older config and older
|
|
1459
|
-
* review documents keep parsing identically.
|
|
1460
|
-
*
|
|
1461
|
-
* Malformed input never throws. An unterminated quote closes at end of input:
|
|
1462
|
-
* a broken config line degrades to a best-effort argument list instead of
|
|
1463
|
-
* taking startup down with it.
|
|
1464
|
-
*/
|
|
357
|
+
|
|
358
|
+
/** Legacy/persisted review strings keep their best-effort malformed-input behavior. */
|
|
1465
359
|
declare function tokenizeGitDiffArgs(value: string): string[];
|
|
1466
360
|
/**
|
|
1467
361
|
* Render argv as the single string a git diff source carries, such that
|
|
@@ -1473,96 +367,9 @@ declare function tokenizeGitDiffArgs(value: string): string[];
|
|
|
1473
367
|
*/
|
|
1474
368
|
declare function formatGitDiffArgs(args: string[]): string;
|
|
1475
369
|
|
|
1476
|
-
/**
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
*/
|
|
1480
|
-
interface MaterializedRemoteSession {
|
|
1481
|
-
forgeUrl: ForgeUrl;
|
|
1482
|
-
/** Root of the materialized clone; the pipeline's repo path. */
|
|
1483
|
-
repoPath: string;
|
|
1484
|
-
/** Arguments for the existing git-diff machinery: `[base...head]`. */
|
|
1485
|
-
gitDiffArgs: string[];
|
|
1486
|
-
mode: MaterializeMode;
|
|
1487
|
-
/** Idempotent, never rejects; the receiver of the session must call it. */
|
|
1488
|
-
cleanup: () => Promise<void>;
|
|
1489
|
-
/** Provenance + thread-sync status for payloads and the saved review. */
|
|
1490
|
-
remote: RemoteSessionInfo;
|
|
1491
|
-
/** Verbatim; empty when thread sync is unavailable. */
|
|
1492
|
-
fetchedThreads: ForgeThread[];
|
|
1493
|
-
}
|
|
1494
|
-
/** A session whose diff is loaded and whose threads are mapped against it. */
|
|
1495
|
-
interface RemoteSession extends MaterializedRemoteSession {
|
|
1496
|
-
/** Review-level threads keep the sentinel `filePath: ''` (REVIEW_LEVEL_FILE_PATH). */
|
|
1497
|
-
fetchedComments: ReviewComment[];
|
|
1498
|
-
}
|
|
1499
|
-
/** Injectable seams; defaults are the real core APIs. */
|
|
1500
|
-
interface RemoteSessionDeps {
|
|
1501
|
-
createProvider: (forge: ForgeName, runner: ForgeCommandRunner) => ForgeProvider;
|
|
1502
|
-
materialize: (url: ForgeUrl, baseBranch: string, cwd: string, runner: ForgeCommandRunner, existingClone?: ExistingClone | null, options?: MaterializeOptions) => Promise<MaterializeResult>;
|
|
1503
|
-
detectExistingClone: (url: ForgeUrl, cwd: string, runner: ForgeCommandRunner, options?: MaterializeOptions) => Promise<ExistingClone | null>;
|
|
1504
|
-
resolveRemoteDefaultBranch: (url: ForgeUrl, runner: ForgeCommandRunner, existing?: ExistingClone | null, options?: MaterializeOptions) => Promise<string>;
|
|
1505
|
-
runner: ForgeCommandRunner;
|
|
1506
|
-
/** Untracked files are never included. A stand-in may omit `diagnostics` and `identity`. */
|
|
1507
|
-
loadDiff: (gitDiffArgs: string[], cwd: string) => Promise<{
|
|
1508
|
-
files: DiffFile[];
|
|
1509
|
-
repository: string;
|
|
1510
|
-
diagnostics?: string[];
|
|
1511
|
-
identity?: ReviewSourceIdentity;
|
|
1512
|
-
}>;
|
|
1513
|
-
}
|
|
1514
|
-
declare const defaultRemoteSessionDeps: RemoteSessionDeps;
|
|
1515
|
-
interface RemoteLifetimeOptions {
|
|
1516
|
-
/** Without one, the session is bounded only by the per-command timeout. */
|
|
1517
|
-
signal?: AbortSignal;
|
|
1518
|
-
}
|
|
1519
|
-
interface StartRemoteSessionOptions extends RemoteLifetimeOptions {
|
|
1520
|
-
includeResolved?: boolean;
|
|
1521
|
-
/**
|
|
1522
|
-
* `'optional'` (default, the app): a failed fetch degrades to no threads.
|
|
1523
|
-
* `'required'` (`fetch-comments`): always attempted, and a failure is fatal.
|
|
1524
|
-
*/
|
|
1525
|
-
threads?: 'optional' | 'required';
|
|
1526
|
-
}
|
|
1527
|
-
/**
|
|
1528
|
-
* Materialize a forge PR/MR URL into a local git context and fetch its
|
|
1529
|
-
* discussion threads.
|
|
1530
|
-
*
|
|
1531
|
-
* Fatal failures (unrecognizable URL, materialization errors, base-branch
|
|
1532
|
-
* lookup failures other than a missing CLI) throw — callers surface them
|
|
1533
|
-
* like any other startup git error. Forge-CLI unavailability is never
|
|
1534
|
-
* fatal for the base branch (git-only fallback); for threads see
|
|
1535
|
-
* {@link StartRemoteSessionOptions.threads}.
|
|
1536
|
-
*/
|
|
1537
|
-
declare function startRemoteSession(url: string, cwd: string, deps?: Partial<RemoteSessionDeps>, options?: StartRemoteSessionOptions): Promise<MaterializedRemoteSession>;
|
|
1538
|
-
interface RemoteReviewLoad {
|
|
1539
|
-
/** After the ignore configuration. */
|
|
1540
|
-
files: DiffFile[];
|
|
1541
|
-
repository: string;
|
|
1542
|
-
diagnostics: string[];
|
|
1543
|
-
/** `session.fetchedThreads` mapped against `files` and the materialized head. */
|
|
1544
|
-
comments: ReviewComment[];
|
|
1545
|
-
identity?: ReviewSourceIdentity;
|
|
1546
|
-
}
|
|
1547
|
-
/**
|
|
1548
|
-
* Load the diff, apply the ignore configuration and map the threads: the one place
|
|
1549
|
-
* this happens, so the app and `fetch-comments` cannot drift. Mapping against the
|
|
1550
|
-
* filtered files and the materialized head keeps a suggestion on an ignored path
|
|
1551
|
-
* or another head plain text (R05). Does not release the session on failure. An
|
|
1552
|
-
* abort during the load discards the result and throws.
|
|
1553
|
-
*/
|
|
1554
|
-
declare function loadRemoteReview(session: MaterializedRemoteSession, ignorePatterns: string[], loadDiff?: RemoteSessionDeps['loadDiff'], options?: RemoteLifetimeOptions): Promise<RemoteReviewLoad>;
|
|
1555
|
-
/** A remote session plus the ready-to-send git-mode diff payload. */
|
|
1556
|
-
interface RemoteBootstrapResult {
|
|
1557
|
-
session: RemoteSession;
|
|
1558
|
-
payload: DiffLoadPayload;
|
|
1559
|
-
identity: ReviewSourceIdentity;
|
|
1560
|
-
}
|
|
1561
|
-
/**
|
|
1562
|
-
* Full remote bootstrap for the app: materialize, {@link loadRemoteReview}, and shape
|
|
1563
|
-
* the git-mode `DiffLoadPayload`. Thread sync degrades rather than failing.
|
|
1564
|
-
*/
|
|
1565
|
-
declare function bootstrapRemoteDiff(url: string, cwd: string, ignorePatterns: string[], deps?: Partial<RemoteSessionDeps>, options?: RemoteLifetimeOptions): Promise<RemoteBootstrapResult>;
|
|
370
|
+
/** Insert `--` before the first existing positional path, relative to cwd. */
|
|
371
|
+
declare function normalizeGitDiffArgs(args: string[], cwd?: string): string[];
|
|
372
|
+
|
|
1566
373
|
/**
|
|
1567
374
|
* Merge fetched forge threads into a resumed document's comments. The
|
|
1568
375
|
* resumed document wins: a fetched thread whose root `remoteId` already
|
|
@@ -1585,63 +392,4 @@ declare function applyRemoteProvenance(state: ReviewState, remote: RemoteSession
|
|
|
1585
392
|
*/
|
|
1586
393
|
declare function computeRemoteDrift(recordedHeadSha: string | undefined, liveHeadSha: string): RemoteDriftInfo | null;
|
|
1587
394
|
|
|
1588
|
-
|
|
1589
|
-
interface FetchCommentsDeps extends RemoteSessionDeps {
|
|
1590
|
-
publish: (state: ReviewState, outputPath: string, options: PublishReviewOptions) => Promise<PublishReviewResult>;
|
|
1591
|
-
loadConfig: () => LoadedConfig;
|
|
1592
|
-
now: () => Date;
|
|
1593
|
-
}
|
|
1594
|
-
interface BuildRemoteReviewStateArgs {
|
|
1595
|
-
remoteUrl: string;
|
|
1596
|
-
forge: RemoteForge;
|
|
1597
|
-
baseSha: string;
|
|
1598
|
-
headSha: string;
|
|
1599
|
-
diffFiles: DiffFile[];
|
|
1600
|
-
comments: ReviewComment[];
|
|
1601
|
-
timestamp: string;
|
|
1602
|
-
}
|
|
1603
|
-
/**
|
|
1604
|
-
* Assemble the ReviewState for a fetched remote review. Pure and
|
|
1605
|
-
* deterministic: same inputs, same state.
|
|
1606
|
-
*
|
|
1607
|
-
* Placement rules:
|
|
1608
|
-
* - Every diff file gets a file entry in diff order; fetched threads land on
|
|
1609
|
-
* their files, in thread order.
|
|
1610
|
-
* - Comments whose path is not in the diff (e.g. outdated anchors on files
|
|
1611
|
-
* no longer touched) get a synthetic entry with change-type "modified" —
|
|
1612
|
-
* the schema requires the attribute and "modified" is the least-claiming
|
|
1613
|
-
* value for a file we cannot classify.
|
|
1614
|
-
* - Review-level threads (sentinel {@link REVIEW_LEVEL_FILE_PATH}) are
|
|
1615
|
-
* folded into a single trailing file entry with the sentinel path: the v3
|
|
1616
|
-
* schema requires every <comment> inside a <file path>, and the empty
|
|
1617
|
-
* path can never collide with a real diff path, so consumers detect these
|
|
1618
|
-
* by comparing against the constant. Omitted when there are none.
|
|
1619
|
-
* - Every file is viewed="false": fetch-comments reviews nothing, and a
|
|
1620
|
-
* viewed mark claims a human looked at the file. A subsequent
|
|
1621
|
-
* --resume-from session therefore starts with the full file list pending.
|
|
1622
|
-
* - `source` is `{ type: 'welcome' }`: the remote-* root attributes are the
|
|
1623
|
-
* review's source shape, and the three shapes (git, directory, remote)
|
|
1624
|
-
* are mutually exclusive by contract, so no local source attributes are
|
|
1625
|
-
* serialized.
|
|
1626
|
-
*/
|
|
1627
|
-
declare function buildRemoteReviewState(args: BuildRemoteReviewStateArgs): ReviewState;
|
|
1628
|
-
interface FetchCommentsOptions extends RemoteLifetimeOptions {
|
|
1629
|
-
/** Include threads the forge marks resolved (GitLab). Default false. */
|
|
1630
|
-
includeResolved?: boolean;
|
|
1631
|
-
/** Working directory for clone detection and output resolution. */
|
|
1632
|
-
cwd?: string;
|
|
1633
|
-
/** Test seams; every omitted member falls back to the real default. */
|
|
1634
|
-
deps?: Partial<FetchCommentsDeps>;
|
|
1635
|
-
}
|
|
1636
|
-
/**
|
|
1637
|
-
* Run the headless fetch-comments flow end to end. Throws on any failure
|
|
1638
|
-
* (the caller prints the message to stderr and exits 1); the temporary
|
|
1639
|
-
* clone, when one was created, is removed on both success and failure, and
|
|
1640
|
-
* the removal has completed by the time the promise settles.
|
|
1641
|
-
*
|
|
1642
|
-
* Fetching comments is the whole point, so threads run under the `'required'`
|
|
1643
|
-
* policy: an unavailable forge CLI is an error, not a degraded review.
|
|
1644
|
-
*/
|
|
1645
|
-
declare function runFetchComments(url: string, options?: FetchCommentsOptions): Promise<void>;
|
|
1646
|
-
|
|
1647
|
-
export { ASSET_DIR_NAME, type AnchorCheck, type AnchorFields, type AnchorSide, ApplicationOptionError, type ApplicationOptionsSpec, type ApplyRefusalReason, type ApplySuggestionApplied, type ApplySuggestionOptions, type ApplySuggestionRefused, type ApplySuggestionRequest, type ApplySuggestionResult, type AssetNamer, type AtomicReplaceOptions, type AtomicReplaceResult, type AttachmentOrigins, type AttachmentReadFailureReason, type AttachmentReadResult, AttachmentRelocationError, BINARY_SNIFF_BYTES, type BoundedReadOptions, type BoundedReadResult, type BuildRemoteReviewStateArgs, type CommandCancelReason, CommandCancelledError, type ConfigProvenance, type ConfigSource, type ConfigValueOrigin, ConfiguredDiffArgsError, DEFAULT_GIT_COMMAND_TIMEOUT_MS, DEFAULT_SOURCE_BUDGETS, type DiffParseResult, type DiffPathRelativity, type ExistingClone, type ExtractedApplicationOptions, type FetchCommentsDeps, type FetchCommentsOptions, type FetchThreadsOptions, type FileIdentity, type ForgeAnchorSide, ForgeCliUnavailableError, type ForgeCommandOptions, type ForgeCommandResult, type ForgeCommandRunner, type ForgeName, type ForgeProvider, type ForgeThread, type ForgeThreadAnchor, type ForgeThreadTurn, type ForgeUrl, type FsLayer, GUIDE_XSD_SCHEMA, type GitDiffSideSpec, type GitDiffSides, type GitSourceIdentityOptions, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type LineAnchor, type LoadConfigOptions, type LoadGitDiffOptions, type LoadGitDiffResult, type LoadedConfig, type LoadedLocalReview, type LocalSourceIdentityOptions, MAX_GIT_DIFF_OUTPUT_BYTES, MAX_GUIDE_BYTES, MAX_IMAGE_BYTES, MAX_RESUME_ATTACHMENTS, MAX_RESUME_XML_BYTES, MAX_SOURCE_ENTRIES, MAX_SOURCE_FILE_BYTES, MAX_SOURCE_TOTAL_BYTES, type MaterializeMode, type MaterializeOptions, type MaterializeResult, type MaterializedRemoteSession, PARSER_COMPATIBLE_DIFF_FLAGS, PARSER_COMPATIBLE_GIT_CONFIG, type ParsedReview, type PlannedAsset, type PublishReviewOptions, type PublishReviewResult, REVIEW_LEVEL_FILE_PATH, type RemoteBootstrapResult, type RemoteLifetimeOptions, type RemoteReviewLoad, type RemoteSession, type RemoteSessionDeps, type RenderedTextMode, type ResolvedDiffArgs, type ReviewOutputOrigin, type ReviewOutputTarget, ReviewPublishError, type ReviewPublishErrorCode, type ReviewSession, type ReviewStartResult, ReviewXmlError, type ReviewXmlErrorCode, type ReviewedPathAuthorization, type ReviewedPathRefusal, type ReviewedSnapshot, SafeFsError, type SafeFsErrorCode, type SerializeOptions, type SerializedReview, type SnapshotReadFailure, type SnapshotReadOptions, type SnapshotReadResult, type SourceBudgets, type SourceScanOptions, type SourceScanResult, type StartRemoteSessionOptions, type StartupSource, type SyntheticDiffOptions, type SyntheticDiffResult, type WriteExclusiveOptions, XmlIllegalCharacterError, type XmlIllegalCharacterLocation, applyRemoteProvenance, applyStagedUntrackedDefault, applySuggestion, applySuggestionForSession, assertNoSymlinkAncestors, atomicReplace, authorizeAttachmentReference, authorizeReviewedPath, bootstrapRemoteDiff, buildRemoteReviewState, canonicalSourcePath, checkWritability, classifyFsError, classifyGitDiffArgs, commitDiffData, commitReviewStart, computePayloadStats, computeRemoteDrift, consumesNextArgument, countTotalLines, createGitHubProvider, createGitLabProvider, createIgnoreFilter, createReviewSession, dedupeUntrackedByPath, defaultGitRunner, defaultRemoteSessionDeps, deriveGuidePath, describeDiffPathRelativity, describeGitDiffSides, detectExistingClone, determineMode, expandContext, extractApplicationOptions, findUnsupportedGitDiffOptions, findWriteCapableGitDiffOptions, formatBytes, formatGitDiffArgs, generateSyntheticDiffs, generateUntrackedDiffs, getConfigLoad, getDiffLoad, getFileHunks, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRootAsync, getResumeLoad, getUntrackedFilesAsync, inspectOutputPath, inspectReplaceTarget, isCommandCancelled, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, isRepositoryControlPath, loadConfig, loadConfigWithProvenance, loadGitDiffWithUntracked, loadGuide, loadImage, loadLocalReview, loadRemoteReview, loadResumeDocument, loadSyntheticFiles, locateReviewedFile, mapThreadsToReviewComments, materialize, mergeRemoteThreads, nodeFsLayer, normalizeGitDiffArgs, parseAttachmentReference, parseDiff, parseDiffWithDiagnostics, parseForgeUrl, parseGuideXml, parseReviewXml, parseReviewXmlString, prepareDirectoryReview, preparePayload, publishOptionsFor, publishReview, readAssetFile, readAttachment, readFileWithinBudget, readFileWithinBudgetSync, readReviewedContent, reconcileGuide, recordResumedAttachments, relocateAttachments, resolveApplyDestination, resolveAttachmentOrigins, resolveGitSourceIdentity, resolveGuidePath, resolveLocalSourceIdentity, resolveOutputTarget, resolveRemoteDefaultBranch, resolveReviewedPathPrefix, resolveSourceBaseDir, resolveSourceBudgets, resolveStartupDiffArgs, resolveStartupSource, rootRelativeReviewedPath, runFetchComments, runGitDiffAsync, sameFile, scanDirectory, scanFile, serializeReview, snapshotIdentity, startRemoteSession, submitReviewState, takeReviewState, tokenizeGitDiffArgs, validateLineAnchor, validateLineRange, withParserCompatibleDiffArgs, writeExclusiveNoFollow };
|
|
395
|
+
export { ASSET_DIR_NAME, type AnchorCheck, type AnchorFields, type AnchorSide, ApplicationOptionError, type ApplicationOptionsSpec, type AssetNamer, type ContextExpansionDependencies, DiagnosticReporter, type DiffParseOptions, type DiffParseResult, type DiffPathRelativity, type ExtractedApplicationOptions, ForgeCommandRunner, ForgeProvider, ForgeThread, FsLayer, GUIDE_XSD_SCHEMA, type GitDiffStats, type GitDiffStatsResult, GitExecutionOptions, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type LineAnchor, ParsedReview, type PlannedAsset, REVIEW_LEVEL_FILE_PATH, type RenderedTextMode, ReviewSession, type SerializeOptions, type SerializedReview, SourceBudgets, applyRemoteProvenance, applyStagedUntrackedDefault, checkWritability, classifyGitDiffArgs, computePayloadStats, computeRemoteDrift, consumesNextArgument, countTotalLines, createGitHubProvider, createGitLabProvider, createIgnoreFilter, describeDiffPathRelativity, expandContext, extractApplicationOptions, findUnsupportedGitDiffOptions, findWriteCapableGitDiffOptions, formatGitDiffArgs, getGitDiffStats, getGitDiffStatsResult, getLanguageFromPath, getRenderedTextMode, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, mapThreadsToReviewComments, mergeRemoteThreads, normalizeGitDiffArgs, parseDiff, parseDiffWithDiagnostics, parseDiffWithDiagnosticsAsync, parseGuideXml, parseReviewXml, readReviewedContent, reconcileGuide, serializeReview, tokenizeGitDiffArgs, validateLineAnchor, validateLineRange };
|