@self-review/core 2.0.3 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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/README.md ADDED
@@ -0,0 +1,441 @@
1
+ # @self-review/core
2
+
3
+ Node-only review operations shared by the desktop and HTTP hosts. Importing the package does not
4
+ start a review, install signal handlers or print diagnostics. Shared data types come from the
5
+ runtime-free `@self-review/types` package.
6
+
7
+ ## Supported entry points
8
+
9
+ - `@self-review/core/operations` provides configuration, startup, review-session, publication,
10
+ scanning and remote-fetch operations for hosts. It excludes concrete filesystem adapters and
11
+ low-level replacement policy. A host can load a source, commit it into a session, then publish the
12
+ submitted review through `publishReview`.
13
+ - `@self-review/core/filesystem` provides advanced read and write adapter contracts, no-follow
14
+ operations, and legacy synchronous adapter compatibility for hosts implementing a filesystem.
15
+ - `@self-review/core` retains every existing export and call form. Existing imports need no
16
+ migration. More specialized operations, parsers, providers and infrastructure remain supported
17
+ there; the smaller entry points help new consumers choose only their role's contracts.
18
+
19
+ All entry points ship ESM, CommonJS, and declarations for both module systems. These are additive
20
+ exports with no version, dependency or minimum-version change.
21
+
22
+ ```ts
23
+ import { loadConfigWithProvenance, runFetchComments } from '@self-review/core/operations';
24
+
25
+ const reportDiagnostic = (message: string) => diagnostics.push(message);
26
+ const diagnostics: string[] = [];
27
+ const controller = new AbortController();
28
+ const loaded = loadConfigWithProvenance({ cwd: '/project', reportDiagnostic });
29
+ await runFetchComments('https://github.com/owner/repo/pull/7', {
30
+ cwd: '/project',
31
+ reportDiagnostic,
32
+ signal: controller.signal,
33
+ });
34
+ ```
35
+
36
+ `runFetchComments` sends its progress, configuration warnings, remote loading and materialization
37
+ messages to the supplied per-call `reportDiagnostic`. With no reporter, the existing text goes to
38
+ stderr and stdout stays unused. Failure still rejects for the host to present. Cleanup finishes
39
+ before the operation settles. Reporters must not throw. Cleanup diagnostics cannot interrupt
40
+ resource release even if a reporter throws. Injected dependencies must honor the reporter passed in
41
+ their options; an independently printing injected dependency is outside this guarantee.
42
+
43
+ `scanDirectory` and `scanFile` accept the same optional reporter and retain their returned payload
44
+ diagnostics. `loadLocalReview` routes scanner messages through its existing `log` callback as well
45
+ as reporting payload diagnostics. Hosts calling scanners directly can pass their own reporter. Each
46
+ operation owns its reporter; there is no mutable global reporting setting.
47
+
48
+ Git root/diff diagnostics, untracked-list fallback diagnostics, config warnings, local-load messages
49
+ and submitted-state summaries isolate reporter throws and rejected promises. Their original messages
50
+ and callback arities remain unchanged. Reporter failure cannot replace a git error, discard valid
51
+ configuration or stop a valid submitted state from being stored.
52
+
53
+ `loadGuide(outputPath, config, diffPaths, options)` accepts `reader?: BoundedGuideReader` and
54
+ `reportDiagnostic`. The reader's `read(path, maxBytes, options?)` uses the existing
55
+ `BoundedReadResult` and bounded-read options. It receives `MAX_GUIDE_BYTES` and the operation's
56
+ signal, retains its receiver, and owns its opened handles through success, failure and cancellation.
57
+ A supplied reader owns every guide read. Missing or refused virtual input never triggers a native
58
+ retry. It must check regular-file metadata before reading, avoid blocking on FIFOs, bound allocation
59
+ and detect growth while reading. Core independently refuses an oversized returned buffer before
60
+ decoding or validation; it cannot undo allocation inside an adapter that violates the contract. The
61
+ default remains the native descriptor reader with regular-file checks, bounded growth detection and
62
+ cleanup. Missing guides stay silent, other read or validation failures return null with one warning,
63
+ and an aborted supplied signal propagates after the reader settles. XML/schema validation and
64
+ reconciliation apply equally to native and supplied bytes. Validation and individual adapter calls
65
+ in flight cannot be preempted.
66
+
67
+ `loadImage(session, path, options)` accepts a per-operation `reportDiagnostic`. Snapshot refusals
68
+ retain their existing error results and diagnostic text. Reporter throws and rejected promises are
69
+ ignored without replacing the read result. Membership, image-size and replaced-session refusals
70
+ retain their existing silent behavior; cancellation rejects without a diagnostic. The option does
71
+ not change captured versus legacy live read semantics. Neither option installs a global reporter.
72
+ Both operations and their option types are available from `@self-review/core/operations`, and the
73
+ original root functions remain supported. Hosts must pass their own reporter into each operation to
74
+ route these messages; callers that omit it retain stderr output.
75
+
76
+ ## Startup path classification
77
+
78
+ `resolveStartupSourceAsync(argv, cwd, options)` accepts an optional `sourceProbe: StartupPathProbe`
79
+ alongside its existing git execution options. The probe's `stat(path)` returns metadata with
80
+ `isFile()` and `isDirectory()`, or null for an unavailable path. It receives the resolved first
81
+ positional path and retains its receiver. A supplied refusal or ordinary probe error uses the
82
+ existing git/directory/file/welcome classification rules without retrying native stat. Tracked files
83
+ still use git, untracked files use file mode, and a repository in cwd takes precedence over
84
+ directory mode. Option values never select a source.
85
+
86
+ The probe supplies classification only. Virtual content loading separately requires the filesystem
87
+ roles accepted by `loadLocalReview`. Omitting the probe retains native stat, and the original
88
+ synchronous APIs and call forms remain supported. Probe and git cancellation propagate instead of
89
+ becoming welcome mode. An aborted signal is checked before probing and after success or failure;
90
+ in-flight native or supplied work is joined before rejection. `timeoutMs` bounds git commands, not
91
+ stat or an arbitrary supplied probe. A promise or timer cannot preempt a native syscall.
92
+
93
+ `StartupSourceOptions`, `StartupPathProbe` and `StartupPathStats` are available through
94
+ `@self-review/core/operations`. Existing root imports remain supported.
95
+
96
+ ## Comment ownership validation
97
+
98
+ Every comment's `filePath` must exactly match its containing file's `path`. The shared runtime and
99
+ serialization validator refuses inconsistent ownership with `ReviewXmlError` code `invalid-state`;
100
+ publication reports `validation-failed` before attachment preparation or staging. Diagnostics name
101
+ the field without echoing supplied path values. The empty review-level path, Unicode paths, renamed
102
+ and deleted files follow the same exact comparison. Paths are never rewritten to repair a mismatch.
103
+ Valid DTOs retain their reference aliases and extension metadata. Historical nullable omissions and
104
+ serialization's optional transient comment IDs keep their existing handling.
105
+
106
+ ## Payload threshold validation
107
+
108
+ `max-files` and `max-total-lines` accept finite numeric values from zero through
109
+ `Number.MAX_SAFE_INTEGER`. Zero disables that dimension. Finite fractions retain their existing
110
+ comparison semantics because the configuration contract does not require integer thresholds.
111
+ Nonfinite, negative, unsafe and nonnumeric YAML values produce a warning and leave the inherited
112
+ user value or default in place. Rejected values do not acquire project provenance. Other config keys
113
+ and project-over-user-over-default precedence are unchanged.
114
+
115
+ ## Read capabilities and compatibility
116
+
117
+ `AsyncReadHandle` requires only `stat`, `read` and `close`. `AsyncReadFsLayer` requires only `open`,
118
+ `lstat` and `realpath`. `readContainedFileAsync` accepts this read-only role. The
119
+ `openContainedFileAsync` overload preserves the exact supplied handle type, so existing
120
+ `AsyncFsLayer` callers still receive `AsyncFileHandle` with every write and ownership method.
121
+ Default callers also retain that full handle type and own its close.
122
+
123
+ `readContainedFileBounded` requires `BoundedAsyncReadFsLayer`, which explicitly promises that each
124
+ read copies at most the requested chunk without allocating the entire file. The native
125
+ `nodeReadFsLayer` provides it. Reads check descriptor size, allocate within the byte budget plus one
126
+ sentinel byte, copy chunks of at most 64 KiB, detect growth and close on all outcomes. Both read
127
+ entry points share the same containment, no-follow and descriptor identity policy.
128
+
129
+ `boundedReadFsFromSync` accepts a read-only `SyncReadFsLayer` with required descriptor `readSync`.
130
+ It uses only the supplied filesystem, including virtual descriptors. It yields before each chunk and
131
+ checks cancellation, but a synchronous call in progress cannot be preempted. The bounded allocation
132
+ promise does not imply an interruptible syscall.
133
+
134
+ `asyncFsFromSync` remains available at its original source-module export and the new filesystem
135
+ entry point. It preserves all `FsLayer` and `AsyncFsLayer` methods, including virtual descriptors.
136
+ It is a legacy compatibility adapter, not a bounded-read capability. Without `readSync`, its
137
+ `readFileSync` fallback allocates the whole file once. Size checks before and after that call cannot
138
+ bound allocation or interrupt the call. Existing adapters remain supported; no new refusal or
139
+ error/outcome-union member is introduced. A supplied `asyncFs` implementation retains precedence.
140
+
141
+ `readAssetFile`, `relocateAttachments` and `readContainedFile` accept an optional `readFs`
142
+ capability with the bounded read contract. Read-only adapters need no write, permission, ownership
143
+ or replacement methods. The original `fs?: FsLayer` option remains supported, including its optional
144
+ `asyncFs` and whole-file fallback. When both options are supplied, `readFs` takes precedence for
145
+ reads and relocation root resolution. Asset authorization, 10 MiB per-asset and 64 MiB aggregate
146
+ relocation limits are unchanged. Cancellation is checked across reads and close; no partial
147
+ attachment data is returned after cancellation.
148
+
149
+ `scanDirectory` and `scanFile` accept `scanFs?: ScanFsLayer`. This extends the bounded reader with
150
+ `stat`, `readlink` and `opendir`; directory handles provide async iteration and `close`.
151
+ `SourceReadFsLayer` is the smaller source-reader role, adding only `readlink` to the bounded reader.
152
+ The async synthetic diff and file loaders accept it as `readFs`. These contracts and the default
153
+ `nodeScanFsLayer` are exported from the root and filesystem entries. All root resolution,
154
+ enumeration, ancestor/link inspection, descriptor identity checks and content reads use the supplied
155
+ filesystem. Virtual paths never fall back to host filesystem reads. Adapters must supply Node-style
156
+ metadata, errno codes and canonical paths, and bounded descriptor reads over that same filesystem.
157
+
158
+ Ignored directories are pruned before opening. Scans retain deterministic file ordering, entry
159
+ budgets, no-follow containment and cleanup after early return, failure and cancellation. Directory
160
+ scans skip links; explicitly selected files still follow their leaf link, and synthetic git
161
+ additions retain link target text. The existing async scan signatures and synchronous synthetic APIs
162
+ remain. Native I/O calls in flight cannot be preempted, and portable name/identity checks cannot
163
+ eliminate all path replacement races. Callers own adapters; each operation owns and closes its
164
+ opened handles.
165
+
166
+ ## Patch parsing and local additions
167
+
168
+ `parseDiff(rawDiff)` and `parseDiffWithDiagnostics(rawDiff)` remain synchronous. They use the same
169
+ parsing state machine as `parseDiffWithDiagnosticsAsync(rawDiff, { signal })`. The async entry
170
+ returns the same `{ files, diagnostics }` result and rejects cancellation with
171
+ `CommandCancelledError` instead of returning partial files. `loadGitDiffWithUntracked` awaits that
172
+ parser with its operation signal, so its desktop, serve and remote callers share the cooperative
173
+ path.
174
+
175
+ The async parser scans at most 64 Ki UTF-16 code units per chunk and yields after at most 256
176
+ complete lines or each chunk. Scanning yields even within a single long line. It avoids a complete
177
+ split-lines array, but retains the captured patch and resulting AST. Assembling and parsing one
178
+ complete line, regex matching, string decoding, allocation and garbage collection remain
179
+ synchronous. These checkpoints allow scheduled work and cancellation to progress; they provide no
180
+ hard CPU deadline or preemption of an individual string operation. The git capture budget still
181
+ applies before parsing.
182
+
183
+ `loadSyntheticFiles` and `loadSyntheticFilesAsync` construct additions directly from bounded source
184
+ reads. They share decoding, source classification, aggregate accounting and omission policy with
185
+ `generateSyntheticDiffs` and `generateSyntheticDiffsAsync`, which still return the textual patch
186
+ format. Structured loading avoids constructing a complete patch, splitting that patch and parsing
187
+ its headers back into files. It retains per-file UTF-8 decoding and source line allocation. Async
188
+ source reads yield between bounded reads and files. One pure generator selects the patch or
189
+ structured emitter, then formats diagnostics separately. Both synchronous and asynchronous forms
190
+ retain their output, omission wording and ordering, and cancellation checkpoints. The asynchronous
191
+ consumer yields while counting each 64 KiB of source bytes, before decoding or line allocation, and
192
+ after emitting each 256 lines within one file. UTF-8 decoding, a single line slice, patch joining,
193
+ allocation and garbage collection still run synchronously. Synchronous entry points retain
194
+ synchronous execution.
195
+
196
+ The loaders preserve literal path ordering, no-follow reads, symlink target text, binary sniffing,
197
+ CR characters, BOMs, UTF-8 replacement, empty hunks and omission diagnostics. The existing text
198
+ format can report a blank separator after an empty file as a hunk-count diagnostic when another file
199
+ follows. Direct loading retains that diagnostic for compatibility. Ignore filtering and entry limits
200
+ stay with the calling scanner or git loader. Review publication and explicit Apply remain separate
201
+ operations.
202
+
203
+ Representation safety limits apply before line arrays, hunk objects and file objects grow, including
204
+ when payload thresholds are zero. The defaults are 100,000 line objects per file, 250,000 total line
205
+ objects, 10,000 file-header attempts or synthetic paths, and 50,000 total hunks. A context line is
206
+ one object; an addition and deletion are two. Empty hunks and metadata-only files consume their own
207
+ budgets. Patch diagnostic output retains at most 1,000 individual messages plus one stop summary,
208
+ and refuses individual patch diagnostics longer than 8,192 characters. These limits complement the
209
+ existing file, aggregate-read and git-output byte budgets.
210
+
211
+ `SourceBudgets` keeps its four original required fields. New `maxFileLines`, `maxTotalLines`,
212
+ `maxDiffFiles`, `maxDiffHunks` and `maxDiagnostics` fields are optional. `resolveSourceBudgets`
213
+ fills absent values with defaults. Limits must be nonnegative safe integers; zero refuses that kind
214
+ of representation. They are optional embedding/test controls, not YAML settings or CLI flags. All
215
+ three parsers accept an optional `{ budgets }` argument; the asynchronous parser also retains
216
+ `signal`. Existing calls and result shapes are unchanged. The legacy `parseDiff` result cannot carry
217
+ an aggregate diagnostic, so representation refusals throw `RangeError` instead of returning an
218
+ incomplete list. Ordinary malformed-input diagnostics remain discarded by that legacy API; use
219
+ `parseDiffWithDiagnostics` to inspect omitted content and aggregate stops without throwing. The
220
+ browser-safe source entry also exports `parseDiffWithDiagnostics` and the parser option/result
221
+ types.
222
+
223
+ A per-file refusal discards that file's entire hunk list and sets `omittedReason`, retaining its
224
+ path, change type and binary status. It never returns a truncated hunk as complete. The parser
225
+ reports the refusal and continues with the next file; aggregate exhaustion stops parsing and reports
226
+ that remaining input was not loaded. Synthetic projection lists omitted files without reading
227
+ further content after aggregate exhaustion, stopping with a diagnostic at the file limit. Unsafe
228
+ hunk coordinates and coordinate sums outside the safe integer range are refused explicitly.
229
+ Malformed headers and repeated empty hunks cannot bypass file, hunk or diagnostic accounting. Small
230
+ patches, source encodings and textual/direct projection semantics stay unchanged.
231
+
232
+ Tracked git and untracked additions share the retained file, hunk and line limits. Lazy delivery
233
+ returns the stored, already bounded hunks. Context expansion refuses an already omitted file, parses
234
+ cooperatively within the remaining review budget, and rechecks aggregate replacement after
235
+ concurrent reads. Refused expansion returns `null`, reports the reason and preserves existing hunks.
236
+ Source membership, snapshot selection and Apply authorization remain unchanged.
237
+
238
+ `readAttachment` forwards its existing optional signal through the bounded, authorized asset reader.
239
+ Aborting stops further chunks and closes the acquired handle, then rejects with the existing
240
+ `CommandCancelledError` contract. Origin and no-follow checks and read failure results are
241
+ unchanged.
242
+
243
+ These limits bound representation counts, not a universal memory or latency ceiling. Captured git
244
+ text, one decoded source buffer, path/header strings, patch output, retained ASTs and temporary
245
+ replacement representations still consume memory. Pure parser callers already own their input
246
+ string. Native I/O, regular expressions, string operations and GC cannot be preempted. Legacy
247
+ filesystem adapters retain the weaker guarantees documented above.
248
+
249
+ ## Package entry point verification
250
+
251
+ After `npm run build --workspace @self-review/core`, run both built API tests from the repository
252
+ root:
253
+
254
+ ```sh
255
+ node --test scripts/test/core-entry-points.test.mjs scripts/test/core-loaded-review.test.mjs
256
+ ```
257
+
258
+ These checks cover ESM/CommonJS root and operations aliases, typed error identity, explicit capture
259
+ and the legacy bridge. Generated shared chunks ship alongside each entry point in `dist`.
260
+
261
+ ## Host-owned resume workers
262
+
263
+ `@self-review/core/resume-worker` shares one-shot ownership and reply validation between hosts. It
264
+ has no runtime Core, parser or filesystem dependencies. The host constructs the worker, supplies an
265
+ owned request ID and input path, and injects failure reconstruction using its own Core error
266
+ constructors. Parser byte and attachment budgets remain in the parser. Parsed metadata is retained.
267
+ Legacy failures need only a message, with optional code and details; name, stack and native read
268
+ cause diagnostics are additive. Unknown failure codes remain strings on this internal wire and do
269
+ not extend the installed peer's public error-code union.
270
+
271
+ Ownership includes admission, delivery and termination. Results settle only after termination; abort
272
+ listeners and the deadline stay active during termination, and freshness is checked again before
273
+ returning. Hosts must abort replaced operations and check ownership before adopting into session
274
+ state. Omitted or zero timeout uses 30,000 ms, positive fractions round up, and values above
275
+ 2,147,483,647 clamp to that limit. Negative and nonfinite values reject after worker cleanup.
276
+
277
+ Cancellation retains the original abort reason, including falsy values. If termination rejects,
278
+ release is unconfirmed: a successful parse rejects with that termination error; an owned failure or
279
+ cancellation rejects with `ResumeWorkerTerminationError`, carrying the original reason as `cause`
280
+ and the cleanup rejection as `terminationError`. Listeners and timers are still removed. This does
281
+ not report cancellation as successfully releasing a potentially running worker. Native syscalls may
282
+ delay termination.
283
+
284
+ Hosts supporting older installed Core versions must bundle this subpath from their build input,
285
+ while retaining the runtime Core root as external. Serve does this with its `noExternal` binding, so
286
+ Core 2.0.4 needs no new export and its error classes keep their identity.
287
+
288
+ ## Explicit loaded review capabilities
289
+
290
+ New local hosts carry `LoadedLocalReview.loadedReview` separately from the logical
291
+ `ReviewSourceIdentity`. `loadLocalReview`, `loadGitReviewSnapshot` and `prepareDirectoryReview`
292
+ issue this opaque `LoadedReview` capability after observing the source. Use
293
+ `commitLoadedReview(session, payload, loadedReview)` to retain it in a session, or
294
+ `readLoadedReviewContent(loadedReview, path, side, options)` for a direct captured read.
295
+ `loadedReviewIdentity` returns the original mutable identity alias; `loadedReviewPaths` returns a
296
+ membership copy. Copying that set cannot authorize additional reads. The original payload, identity,
297
+ fields and nested maps remain mutable. Changing identity after load makes captured reads refuse
298
+ until reload. Physical source drift also refuses; index reads use the captured blob OID even after
299
+ restaging. Expansion verifies both compared sides and index replacement before and after re-diff. No
300
+ source bytes, temporary source snapshots, Git objects, index entries or refs are written to capture
301
+ a local review. The handle owns no open descriptors and requires no disposal.
302
+
303
+ This capability is host-local. Do not put it in XML, IPC, HTTP, saved state or other transport data.
304
+ Spreading or serializing a handle does not create another usable capability. Keep the original
305
+ handle when copying logical metadata. Session previews and expansion consume it explicitly, and a
306
+ copied logical identity cannot replace the identity associated with a retained handle.
307
+
308
+ The original three-argument `commitDiffData`, synchronous identity functions, six-argument
309
+ `loadLocalReview` and live structural `readReviewedContent` calls remain supported. For
310
+ compatibility with captured callers predating this API, first-party loaders also attach
311
+ non-enumerable evidence to the exact original identity object. The old commit/read route retains its
312
+ captured guarantee only while that original object survives. A spread, clone or serialized logical
313
+ identity has no capture guarantee and retains legacy live descriptor reads. Supplying such an
314
+ identity to the old API does not assert capture. Use the explicit capability route whenever capture
315
+ is required. Hosts running actual published Core 2.0.4 must feature-detect `commitLoadedReview` and
316
+ retain their original commit/read, Apply, publication and resume paths. That peer has no explicit
317
+ capture capability and provides only its original live descriptor semantics. No new peer subpath is
318
+ needed.
319
+
320
+ `loadLocalReview` accepts an optional seventh `LocalReviewDependencies` argument. Its `scanFs` role
321
+ owns path canonicalization, enumeration, metadata and bounded bytes for directory/file loads.
322
+ `resolveLocalSourceIdentityAsync(options, paths, signal)` uses the supplied path role; the original
323
+ synchronous resolver keeps native behavior. Every provider method retains its receiver. Failed
324
+ canonicalization keeps lexical paths for the scanner's diagnostics and never calls native realpath
325
+ as a fallback. Source budgets and cancellation stay in the sixth options argument. Native defaults
326
+ use the existing scanners and filesystem roles.
327
+
328
+ Git hosts can supply `gitSnapshot` dependencies. Its bounded `readFs` supplies capture inspection;
329
+ `sourceFs`, or the loader's `readFs` option, supplies untracked content and link reads. The standard
330
+ loader refuses an untracked read if only a path role was supplied, rather than reading the host
331
+ filesystem. Injected loaders retain their own source effects. Captured context expansion also uses
332
+ the load's Git runner with the current operation's signal. A supplied text Git runner also needs
333
+ `snapshotRunner` for binary-safe blob reads; otherwise a captured blob read refuses. Selected
334
+ comparison paths bound index evidence; unrelated tracked entries never consume untracked entry
335
+ budgets.
336
+
337
+ ## Session Apply and attachment effects
338
+
339
+ Suggestion admission and current Apply reject unpaired UTF-16 surrogates in proposed code, which
340
+ UTF-8 encoding would otherwise replace silently. Direct Apply uses the existing write-failed refusal
341
+ and leaves the file unchanged. Valid surrogate pairs, explicit U+FFFD, literal source-code escapes
342
+ and other supported code units retain their original bytes.
343
+
344
+ Synchronous `applySuggestionForSession(session, request, options?)` and asynchronous
345
+ `applySuggestionForSessionAsync` share destination and final authorization checks. A selected
346
+ destination redirected into a disposable clone is refused. Replacing the review, changing its
347
+ identity or destination, or removing membership before the commit also refuses. The synchronous
348
+ operation additionally accepts `fs?: FsLayer` through its optional effects argument. That layer owns
349
+ all inspection, reads, staging and replacement, including legacy virtual descriptors without
350
+ `readSync`; native methods never supplement it. A supplied `destinationInspection` retains its
351
+ receiver. The async operation keeps its existing filesystem and inspection arguments and
352
+ cancellation behavior. Neither operation changes the original session identity or payload aliases.
353
+
354
+ These checks do not make portable rename a filesystem transaction. Another actor can still change
355
+ names after the final check. If a parent directory moves after staging, path-based cleanup cannot
356
+ rediscover the staged file in the moved directory. Ordinary failures remove staging, and a refusal
357
+ never claims a committed replacement. Legacy synchronous reads can allocate a whole file and block
358
+ until their adapter returns. Timers and promise races cannot interrupt that work.
359
+
360
+ `readAttachment(session, reference, options?)` accepts an optional `attachmentReader` with one
361
+ `readAssetFile(authorizedPath, { signal })` method, plus `reportDiagnostic`. The method retains its
362
+ receiver and returns the existing `AttachmentReadResult`. Authorization against recorded origins or
363
+ the current output asset directory always precedes provider access. Rejected references touch no
364
+ provider. A supplied reader is authoritative; errors and refusals never cause a native retry. It
365
+ must enforce no-follow ancestry and leaf opens, regular files and `MAX_IMAGE_BYTES` before
366
+ allocation, preserve passive bytes, close acquired resources and honor cancellation. Core checks
367
+ cancellation before invocation and after settlement. Calls already in progress cannot be preempted.
368
+ Reporter throws and rejected promises cannot replace results. Omitted options retain native reads,
369
+ stderr messages and typed results. Refusal diagnostics describe non-string inputs without traversing
370
+ objects or calling `toJSON`; string labels are limited to 512 input characters before escaping.
371
+
372
+ The attachment operation and its types are available from the focused operations entry point. Hosts
373
+ must pass effects explicitly. Actual published Core 2.0.4 predates these options and ignores them;
374
+ its native attachment, synchronous Apply, startup, resume and publication routes remain supported.
375
+ Passing options alone cannot supply a virtual reader to that historical peer. Hosts must select a
376
+ supported operation explicitly when requiring injected I/O; bundling effectful Core internals as a
377
+ supposed pure helper would duplicate acquisition and error ownership. Keep the installed Core root
378
+ and its error classes external. No minimum-version change is required for existing native hosts.
379
+
380
+ `runFetchComments` forwards `temporaryClones` to real materialization, with receiver binding and
381
+ cleanup ownership intact on success, failure and cancellation. `remote-mode` retains direct aliases
382
+ for `mergeRemoteThreads`, `applyRemoteProvenance` and `computeRemoteDrift`; their implementation is
383
+ pure policy in `remote-feedback`, independent of clone acquisition and disposal.
384
+
385
+ ## Review schema validation effects
386
+
387
+ `serializeReview` and `publishReview` accept an optional `validateSchema(xml, schema)` effect in
388
+ their existing options. `ReviewSchemaValidator` is available from `@self-review/core/operations`.
389
+ The effect returns `{ valid, errors? }`, synchronously or asynchronously. It receives the emitted
390
+ review document and the unchanged v3 schema. A supplied effect owns validation; Core never retries
391
+ it through xmllint. Omitting it retains xmllint validation.
392
+
393
+ A returned `valid: false` throws the original `ReviewXmlError` with `schema-invalid` and rendered
394
+ errors. Publication maps that to `validation-failed` before staging assets or replacing XML. A
395
+ thrown or rejected effect means validation infrastructure is unavailable. The historical warning and
396
+ unvalidated document fallback remain. Diagnostic throws and rejected promises cannot replace either
397
+ outcome. The guide parser keeps its separate fail-closed policy. Serialization performs no file I/O;
398
+ the validator is its only supplied or default external effect.
399
+
400
+ ## Output inspection and resumed attachment locations
401
+
402
+ `inspectOutputPathAsync(path, options)` from `@self-review/core/operations` is an awaited, read-only
403
+ advisory probe for interactive hosts. It uses the same physical containment and output replacement
404
+ policy as `inspectOutputPath`, with asynchronous native probes by default. Options carry
405
+ `outputOrigin` and, for an inherited output, `baseDir`. An optional `inspection` provides
406
+ `realpath`, `lstat` and `isWritable(directory)` promises over one filesystem. Its methods retain
407
+ their receiver and own every probe. Errors never retry through native I/O. Legacy `fs` and
408
+ `publicationFs` bags are refused by this API; keep using the original synchronous inspector for
409
+ those providers, or supply the asynchronous read-only role explicitly.
410
+
411
+ Ordinary failures return the existing `ReviewPublishError`, and an injected instance retains its
412
+ identity. Cancellation rejects with the signal reason after any admitted probe settles. It cannot
413
+ interrupt a provider that blocks or never settles. Native missing-path diagnostics can name a
414
+ different underlying syscall than the synchronous implementation. Neither inspection writes files or
415
+ replaces the final checks in `publishReview`.
416
+
417
+ Resume hosts can pass a physically resolved `documentDirectory` to the additive overloads of
418
+ `resolveAttachmentOrigins`, `recordResumedAttachments`, `adoptResumeDocument` and
419
+ `loadResumeDocument`. With this option, origin recording performs path manipulation only and makes
420
+ no native location lookup. The directory must be absolute. `loadResumeDocument` also accepts an
421
+ authoritative `reader` and a signal in that option; read failures retain the parser's existing typed
422
+ error contract. Cancellation is checked before loading and before adoption, without claiming to
423
+ preempt synchronous reading or parsing. Parsed comments, viewed files and attachment provenance are
424
+ adopted together only after location planning succeeds. Original call forms keep native directory
425
+ resolution, reflected parameter lists, runtime arities and session aliases.
426
+
427
+ For example, an asynchronous host first awaits its own filesystem's
428
+ `realpath(dirname(resolve(resumePath)))`, checks cancellation and ownership, then calls
429
+ `adoptResumeDocument(session, parsed, resumePath, { documentDirectory, signal })`. The host retains
430
+ that filesystem method's receiver and propagates its failures before adopting anything. The pure
431
+ `resolveAttachmentOriginsAtDirectory(comments, documentDirectory)` helper is also available from
432
+ operations and its source module `attachment-origin-plan`. It returns the same origin map and
433
+ reference diagnostics without parsing, reading, writing or importing runtime Core error classes. A
434
+ host that supports older installed Core may bundle this pure policy while keeping acquisition,
435
+ adoption and the installed Core root external.
436
+
437
+ Actual published Core 2.0.4 predates these additive call forms and asynchronous inspection. Passing
438
+ extra options to an old peer does not give it virtual filesystem support. Hosts must select an
439
+ available capability explicitly. Existing native inspection, Apply, resume, startup and publication
440
+ paths remain supported without a minimum-version change. The legacy optional `fs` attachment-read
441
+ option remains supported; bounded read-only `readFs` remains preferred when both are supplied.
@@ -0,0 +1,106 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true});// ../config/src/index.ts
2
+ var categoryTemplate = Object.freeze(
3
+ [
4
+ {
5
+ name: "question",
6
+ description: "Clarification needed \u2014 not necessarily a problem",
7
+ color: "#805ad5"
8
+ },
9
+ {
10
+ name: "bug",
11
+ description: "Likely defect or incorrect behavior",
12
+ color: "#e53e3e"
13
+ },
14
+ {
15
+ name: "security",
16
+ description: "Security vulnerability or concern",
17
+ color: "#dd6b20"
18
+ },
19
+ {
20
+ name: "style",
21
+ description: "Code style, naming, or formatting issue",
22
+ color: "#3182ce"
23
+ },
24
+ {
25
+ name: "task",
26
+ description: "Action item or follow-up task",
27
+ color: "#38a169"
28
+ },
29
+ {
30
+ name: "nit",
31
+ description: "Minor nitpick, low priority",
32
+ color: "#718096"
33
+ }
34
+ ].map((category) => Object.freeze(category))
35
+ );
36
+ var ignoreTemplate = Object.freeze([
37
+ ".git",
38
+ "node_modules",
39
+ "vendor",
40
+ ".vendor",
41
+ "__pycache__",
42
+ ".venv",
43
+ "venv",
44
+ ".env",
45
+ "dist",
46
+ "build",
47
+ ".next",
48
+ ".nuxt",
49
+ ".svelte-kit",
50
+ "target",
51
+ "*.min.js",
52
+ "*.min.css",
53
+ "package-lock.json",
54
+ "yarn.lock",
55
+ "pnpm-lock.yaml",
56
+ "composer.lock",
57
+ "Gemfile.lock",
58
+ "Cargo.lock",
59
+ "poetry.lock",
60
+ "go.sum"
61
+ ]);
62
+ var DEFAULT_FONT_SIZE = 14;
63
+ var DEFAULT_MAX_FILES = 500;
64
+ var DEFAULT_MAX_TOTAL_LINES = 1e5;
65
+ var configTemplate = Object.freeze({
66
+ theme: "system",
67
+ diffView: "split",
68
+ fontSize: DEFAULT_FONT_SIZE,
69
+ outputFormat: "xml",
70
+ outputFile: "./review.xml",
71
+ ignore: ignoreTemplate,
72
+ categories: categoryTemplate,
73
+ defaultDiffArgs: "",
74
+ showUntracked: true,
75
+ showUntrackedExplicit: false,
76
+ wordWrap: true,
77
+ maxFiles: DEFAULT_MAX_FILES,
78
+ maxTotalLines: DEFAULT_MAX_TOTAL_LINES
79
+ });
80
+ function createDefaultConfig() {
81
+ return {
82
+ ...configTemplate,
83
+ ignore: [...configTemplate.ignore],
84
+ categories: configTemplate.categories.map((category) => ({ ...category }))
85
+ };
86
+ }
87
+ var DEFAULT_CATEGORIES = categoryTemplate.map((category) => ({
88
+ ...category
89
+ }));
90
+ var DEFAULT_IGNORE_PATTERNS = [...ignoreTemplate];
91
+ var DEFAULT_CONFIG = createDefaultConfig();
92
+
93
+ // src/config-font-size.ts
94
+ function normalizeConfigFontSize(config, fallback = createDefaultConfig().fontSize) {
95
+ if (Number.isFinite(config.fontSize)) return { config };
96
+ return {
97
+ config: { ...config, fontSize: fallback },
98
+ diagnostic: `Warning: Invalid font-size value "${String(config.fontSize)}", expected a finite number; using a finite fallback`
99
+ };
100
+ }
101
+
102
+
103
+
104
+
105
+ exports.createDefaultConfig = createDefaultConfig; exports.normalizeConfigFontSize = normalizeConfigFontSize;
106
+ //# sourceMappingURL=chunk-5SGPWHGH.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["/home/runner/work/self-review/self-review/packages/core/dist/chunk-5SGPWHGH.cjs","../../config/src/index.ts","../src/config-font-size.ts"],"names":[],"mappings":"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","file":"/home/runner/work/self-review/self-review/packages/core/dist/chunk-5SGPWHGH.cjs","sourcesContent":[null,"import type { AppConfig, CategoryDef } from '@self-review/types';\n\nconst categoryTemplate: readonly Readonly<CategoryDef>[] = Object.freeze(\n [\n {\n name: 'question',\n description: 'Clarification needed — not necessarily a problem',\n color: '#805ad5',\n },\n {\n name: 'bug',\n description: 'Likely defect or incorrect behavior',\n color: '#e53e3e',\n },\n {\n name: 'security',\n description: 'Security vulnerability or concern',\n color: '#dd6b20',\n },\n {\n name: 'style',\n description: 'Code style, naming, or formatting issue',\n color: '#3182ce',\n },\n {\n name: 'task',\n description: 'Action item or follow-up task',\n color: '#38a169',\n },\n {\n name: 'nit',\n description: 'Minor nitpick, low priority',\n color: '#718096',\n },\n ].map(category => Object.freeze(category))\n);\n\n/** Only core's directory scanner reads these; the renderer carries them so the defaults stay one. */\nconst ignoreTemplate: readonly string[] = Object.freeze([\n '.git',\n 'node_modules',\n 'vendor',\n '.vendor',\n '__pycache__',\n '.venv',\n 'venv',\n '.env',\n 'dist',\n 'build',\n '.next',\n '.nuxt',\n '.svelte-kit',\n 'target',\n '*.min.js',\n '*.min.css',\n 'package-lock.json',\n 'yarn.lock',\n 'pnpm-lock.yaml',\n 'composer.lock',\n 'Gemfile.lock',\n 'Cargo.lock',\n 'poetry.lock',\n 'go.sum',\n]);\n\nexport const DEFAULT_FONT_SIZE = 14;\n\nexport const DEFAULT_MAX_FILES = 500;\nexport const DEFAULT_MAX_TOTAL_LINES = 100000;\n\n/** `guideFile` is absent on purpose: the loader derives it from the output path. */\nconst configTemplate = Object.freeze({\n theme: 'system',\n diffView: 'split',\n fontSize: DEFAULT_FONT_SIZE,\n outputFormat: 'xml',\n outputFile: './review.xml',\n ignore: ignoreTemplate,\n categories: categoryTemplate,\n defaultDiffArgs: '',\n showUntracked: true,\n showUntrackedExplicit: false,\n wordWrap: true,\n maxFiles: DEFAULT_MAX_FILES,\n maxTotalLines: DEFAULT_MAX_TOTAL_LINES,\n} satisfies Omit<AppConfig, 'ignore' | 'categories'> & {\n ignore: readonly string[];\n categories: readonly Readonly<CategoryDef>[];\n});\n\n/** Return mutable defaults with independently owned arrays and category objects. */\nexport function createDefaultConfig(): AppConfig {\n return {\n ...configTemplate,\n ignore: [...configTemplate.ignore],\n categories: configTemplate.categories.map(category => ({ ...category })),\n };\n}\n\n/** Copy caller-owned nested configuration before retaining it. */\nexport function cloneConfig(config: AppConfig): AppConfig {\n return {\n ...config,\n // Partial configuration can explicitly replace a default with undefined.\n ignore: config.ignore && [...config.ignore],\n categories: config.categories && config.categories.map(category => ({ ...category })),\n };\n}\n\n// Compatibility snapshots remain mutable at runtime. Internal factories never read them.\nexport const DEFAULT_CATEGORIES: readonly CategoryDef[] = categoryTemplate.map(category => ({\n ...category,\n}));\nexport const DEFAULT_IGNORE_PATTERNS: readonly string[] = [...ignoreTemplate];\nexport const DEFAULT_CONFIG: Readonly<AppConfig> = createDefaultConfig();\n","// Pure policy shared by the YAML loader and hosts adapting older Core configuration.\nimport { createDefaultConfig } from '../../config/src/index';\n\nexport function normalizeConfigFontSize<T extends { fontSize: number }>(\n config: T,\n fallback: number = createDefaultConfig().fontSize\n): { config: T; diagnostic?: string } {\n if (Number.isFinite(config.fontSize)) return { config };\n return {\n config: { ...config, fontSize: fallback },\n diagnostic: `Warning: Invalid font-size value \"${String(config.fontSize)}\", expected a finite number; using a finite fallback`,\n };\n}\n"]}