@self-review/core 2.0.4 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +441 -0
  2. package/dist/chunk-5SGPWHGH.cjs +106 -0
  3. package/dist/chunk-5SGPWHGH.cjs.map +1 -0
  4. package/dist/chunk-6OEFXBIZ.cjs +5212 -0
  5. package/dist/chunk-6OEFXBIZ.cjs.map +1 -0
  6. package/dist/chunk-6X3PJHP5.cjs +416 -0
  7. package/dist/chunk-6X3PJHP5.cjs.map +1 -0
  8. package/dist/chunk-CJQEOLI3.js +37 -0
  9. package/dist/chunk-CJQEOLI3.js.map +1 -0
  10. package/dist/chunk-IG2YF5LH.js +416 -0
  11. package/dist/chunk-IG2YF5LH.js.map +1 -0
  12. package/dist/chunk-IX226KG4.js +106 -0
  13. package/dist/chunk-IX226KG4.js.map +1 -0
  14. package/dist/chunk-LSLCQQBN.cjs +3684 -0
  15. package/dist/chunk-LSLCQQBN.cjs.map +1 -0
  16. package/dist/chunk-MOYO4RIX.js +3684 -0
  17. package/dist/chunk-MOYO4RIX.js.map +1 -0
  18. package/dist/chunk-TOUYY7I6.js +5212 -0
  19. package/dist/chunk-TOUYY7I6.js.map +1 -0
  20. package/dist/chunk-VOYTFLPH.cjs +37 -0
  21. package/dist/chunk-VOYTFLPH.cjs.map +1 -0
  22. package/dist/filesystem.cjs +56 -0
  23. package/dist/filesystem.cjs.map +1 -0
  24. package/dist/filesystem.d.cts +22 -0
  25. package/dist/filesystem.d.ts +22 -0
  26. package/dist/filesystem.js +56 -0
  27. package/dist/index.cjs +348 -6192
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +80 -1332
  30. package/dist/index.d.ts +80 -1332
  31. package/dist/index.js +234 -5172
  32. package/dist/index.js.map +1 -1
  33. package/dist/node-scan-fs-CaufzUZR.d.cts +5 -0
  34. package/dist/node-scan-fs-DcHI_BYB.d.ts +5 -0
  35. package/dist/operations-Bqhi9EBH.d.ts +765 -0
  36. package/dist/operations-UyiUD2Nx.d.cts +765 -0
  37. package/dist/operations.cjs +91 -0
  38. package/dist/operations.cjs.map +1 -0
  39. package/dist/operations.d.cts +6 -0
  40. package/dist/operations.d.ts +6 -0
  41. package/dist/operations.js +91 -0
  42. package/dist/resume-worker.cjs +152 -0
  43. package/dist/resume-worker.cjs.map +1 -0
  44. package/dist/resume-worker.d.cts +56 -0
  45. package/dist/resume-worker.d.ts +56 -0
  46. package/dist/resume-worker.js +152 -0
  47. package/dist/resume-worker.js.map +1 -0
  48. package/dist/review-request-validation-VJG7XZiE.d.cts +62 -0
  49. package/dist/review-request-validation-VJG7XZiE.d.ts +62 -0
  50. package/dist/review-xml-decoder-COgRtfkf.d.cts +33 -0
  51. package/dist/review-xml-decoder-COgRtfkf.d.ts +33 -0
  52. package/dist/source-identity-CQpAzugz.d.cts +959 -0
  53. package/dist/source-identity-CQpAzugz.d.ts +959 -0
  54. package/dist/validation.cjs +67 -0
  55. package/dist/validation.cjs.map +1 -0
  56. package/dist/validation.d.cts +30 -0
  57. package/dist/validation.d.ts +30 -0
  58. package/dist/validation.js +67 -0
  59. package/dist/validation.js.map +1 -0
  60. package/package.json +44 -3
  61. package/dist/chunk-4YO2MI6B.js +0 -269
  62. package/dist/chunk-4YO2MI6B.js.map +0 -1
  63. package/dist/chunk-QHS36X6T.js +0 -450
  64. package/dist/chunk-QHS36X6T.js.map +0 -1
  65. package/dist/diff-parser-B6S3KG5T.js +0 -9
  66. package/dist/git-N5HVNPKQ.js +0 -24
  67. /package/dist/{diff-parser-B6S3KG5T.js.map → filesystem.js.map} +0 -0
  68. /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, ReviewComment, DiffSource, RemoteForge, LineRange, ReviewGuide, ResolvedGuideGroup, ReviewSourceIdentity, AppConfig, PayloadStats, Suggestion, DiffLoadPayload, GuideLoadPayload, OutputPathInfo, RemoteDriftInfo, SuggestionApplyRequest, SuggestionApplyOutcome, ExpandContextRequest, DiffHunk, ResumeLoadPayload, ImageLoadResult, RemoteSessionInfo } from '@self-review/types';
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 * as nodeFs from 'node:fs';
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
- /** Parse a unified diff, discarding diagnostics. Prefer {@link parseDiffWithDiagnostics}. */
14
- declare function parseDiff(rawDiff: string): DiffFile[];
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 `git diff` output (a/ b/ prefixes, no color). Every hunk is checked
17
- * against its `@@` counts; a line over them, a short hunk or an unprefixed line
18
- * is a diagnostic, never context. Empty lines in an open hunk are the one
19
- * leniency (`git apply` reads them as empty context). Combined output
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 parseDiffWithDiagnostics(rawDiff: string): DiffParseResult;
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 `schema-invalid`, one violation per `details` line. A validator
51
- * that fails to load is deliberately not fatal: unvalidated XML after a stderr warning.
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 ParsedReview {
56
- comments: ReviewComment[];
57
- /** Paths of files the previous review marked as done (`viewed="true"`). */
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
- * Sized before it is read, so an oversized document or a FIFO is refused unread.
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
- * Entries one directory walk (or untracked-file listing) may examine; ignored directories are
383
- * pruned first.
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 resolveReviewedPathPrefix(gitDiffArgv: readonly string[], sourceRoot: string, invocationCwd: string): string;
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
- * Everything is an addition, so the old side is `none`. A single-file review follows a
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 resolveLocalSourceIdentity(options: LocalSourceIdentityOptions): ReviewSourceIdentity;
742
-
743
- interface ReviewedSnapshot {
744
- sourceIdentity: ReviewSourceIdentity | null;
745
- reviewedPaths: ReadonlySet<string>;
161
+ declare function countTotalLines(files: DiffFile[]): number;
162
+ interface GitDiffStats {
163
+ fileCount: number;
164
+ totalLines: number;
746
165
  }
747
- type ReviewedPathRefusal = 'no-source' | 'not-reviewed'
748
- /** Absolute, empty, or leaving the source root. */
749
- | 'invalid-path';
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
- ok: false;
772
- reason: SnapshotReadFailure;
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
- * Compute payload statistics and check against configured thresholds.
806
- * A maxFiles or maxTotalLines value of 0 disables that guard.
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 computePayloadStats(fileCount: number, totalLines: number, config: AppConfig): PayloadStats;
177
+ declare function getGitDiffStatsResult(args: string[], repoRoot: string, options?: GitExecutionOptions): Promise<GitDiffStatsResult>;
809
178
  /**
810
- * Count total diff lines across all files and hunks.
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 countTotalLines(files: DiffFile[]): number;
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
- /** How the local git context was obtained. */
1003
- type MaterializeMode = 'existing-clone' | 'temp-clone';
1004
- /** Result of materializing a forge URL into a local git context. */
1005
- interface MaterializeResult {
1006
- /** Root of the git repository to run the diff pipeline in. */
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): Promise<{
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
- * Insert `--` before the first non-flag positional arg that exists as a
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
- * The git-mode inputs plus the forge threads, before any diff is loaded (so nothing to anchor
1478
- * suggestions to yet).
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
- /** Injectable seams: the app's remote-session seams plus this subcommand's output. */
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 };