@orkestrel/probe 0.0.5 → 0.0.8

package/dist/src/server/index.d.cts

@@ -202,6 +202,29 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Carries the bound a caller holds over one stage inspection.
+ *
+ * @remarks
+ * `LintStageInterface.inspect` is the only inspection in this package that reads the signal. Its
+ * wait is a foreign language server's silence, and abandoning that wait would leave the client
+ * holding a pending diagnostics request. The type and runtime stages accept no options and honor no
+ * cancellation: a coordinator abandons an overrunning one and replaces it, which is what `Probe`
+ * does when its own deadline expires.
+ *
+ * Supply the signal a coordinator already armed rather than minting a second bound here. A bound
+ * minted beside the coordinator's races it, and which one answers then depends on scheduling.
+ *
+ * @example
+ * ```ts
+ * const options: InspectionOptions = { signal: AbortSignal.timeout(30_000) }
+ * ```
+ */
+export declare interface InspectionOptions {
+    /** Aborts the inspection's wait for the resident tool's answer. */
+    readonly signal: AbortSignal;
+}
+
 /**
  * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
  *
@@ -243,13 +266,22 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * Inspects virtual documents through one resident Oxlint language server.
  *
  * @remarks
- * Construction starts the target workspace's Oxlint binary with its Language Server Protocol
- * mode. Each inspection opens the supplied text by URI, waits for published diagnostics, and
- * closes the document without writing it to disk.
+ * Construction starts the target workspace's Oxlint binary with its Language Server Protocol mode
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioTransport` owns the child process and
+ * its bytes, and `createLSPClient` owns the framing, the request correlation, the capabilities this
+ * stage advertises, and the choice between pulled and pushed diagnostics. This stage owns the
+ * workspace, the candidate identity, and the projection from a diagnostic to an `Issue`.
+ *
+ * Each inspection opens the supplied text by URI, waits for the client's diagnostics, and closes the
+ * document without writing it to disk. The caller's own signal is what bounds that wait, so a server
+ * that admits a document and publishes nothing refuses the inspection when the caller's bound
+ * expires rather than holding it for the life of the process. This stage mints no bound of its own
+ * for the wait: a second one would race the caller's, and the answer would depend on scheduling.
  *
  * Teardown is bounded at both ends. Warming waits for the server's `initialize` response and the
- * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so
- * `destroy` bounds each exchange and takes the ending back with a signal when the bound passes.
+ * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so the
+ * client's deadline bounds each exchange and the transport's cooperative window takes the ending
+ * back with a signal when that window passes.
  *
  * The URI is the path the candidate declared, so the candidate receives exactly the rule set the
  * workspace's own lint gate applies to that path, including an override anchored to one directory,
@@ -262,11 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * @example
  * ```ts
  * const stage = new LintStage('/srv/checkout')
- * const check = await stage.inspect(subject)
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
  * await stage.destroy()
  * ```
  */
-export declare class LintStage implements StageInterface {
+export declare class LintStage implements LintStageInterface {
     #private;
     /**
      * Starts warming the target workspace's Oxlint language server.
@@ -276,10 +308,42 @@ export declare class LintStage implements StageInterface {
     constructor(workspace?: string);
     get stage(): Stage_2;
     get progress(): number;
-    inspect(subject: Case_2): Promise<Check_2>;
+    inspect(subject: Case_2, options?: InspectionOptions): Promise<Check_2>;
     destroy(): Promise<void>;
 }
 
+/**
+ * Inspects one case under a bound the caller supplies.
+ *
+ * @remarks
+ * The lint stage carries a member the shared stage contract cannot. Its inspection waits for a
+ * foreign language server to publish, and only the caller knows how long that wait may run, so the
+ * bound belongs here rather than on `StageInterface`. The type and runtime stages read no signal
+ * and keep the shared one-argument `inspect`.
+ *
+ * `options` is optional because `StageInterface.inspect` accepts one argument and this contract
+ * extends it. An inspection that omits `options` is refused rather than served: a bound this stage
+ * minted for itself would race the coordinator's, and the client's own `timeout` covers the
+ * lifecycle exchanges alone.
+ *
+ * @example
+ * ```ts
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
+ * ```
+ */
+export declare interface LintStageInterface extends StageInterface {
+    /**
+     * Inspects one case, under the bound the caller supplies.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param options - The bound this inspection waits under
+     * @returns One outcome for this stage
+     * @throws When the caller supplies no bound, when the resident language server cannot start, or
+     * when the stage has already been destroyed
+     */
+    inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
+}
+
 /**
  * Holds the listeners one emitter carried for a set of events at the moment it was captured.
  *
@@ -505,12 +569,18 @@ export declare interface OverlayInterface {
  * A containment walk and the write that follows it are separate calls, so a process that swaps the
  * final component between them decides where the bytes land. `writeFileSync` opens with the default
  * `w` flag, which follows a symbolic link at that component and creates the file when it is absent,
- * so the walk's reading does not bind the write. Opening `O_WRONLY | O_TRUNC | O_NOFOLLOW` moves
- * that decision into the call that writes: a link at the final component refuses the open, and the
+ * so the walk's reading does not bind the write. Opening `O_WRONLY | O_NOFOLLOW` moves that
+ * decision into the call that writes: a link at the final component refuses the open, and the
  * omitted `O_CREAT` fails `ENOENT` for a target that has gone since the walk saw it. This is the
  * mutating counterpart of the `wx` flag every create in this package uses. Which code the refusal
  * carries is the host's; Linux with Node v22.22.2 reported `ELOOP` on 2026-08-24.
  *
+ * Truncation runs through the held descriptor rather than through an `O_TRUNC` flag, so it reaches
+ * the file the open bound. A Windows host refuses the numeric `O_TRUNC` without `O_CREAT` outright:
+ * measured on 2026-08-26 on Windows 11 with Node v24.19.0 over NTFS, `openSync` reported `EINVAL`
+ * for `O_WRONLY | O_TRUNC` and for `O_RDWR | O_TRUNC` while `O_WRONLY` alone opened, and adding
+ * `O_CREAT` would trade that refusal for the create this function must never perform.
+ *
  * A directory component stays open, because Node exposes no descriptor-relative call to walk and
  * write through one set of descriptors. Where a host's Node build defines no `O_NOFOLLOW`, that flag
  * contributes nothing to the flag set and the final component is open on that host too.
@@ -531,20 +601,6 @@ export declare interface OverlayInterface {
  */
 export declare function overwriteFile(file: string, text: string): void;
 
-/**
- * Reads a JSON-RPC frame's declared byte length.
- *
- * @param header - The frame header text without its terminating empty line
- * @returns The non-negative content length, or `undefined` for an invalid header
- *
- * @example
- * ```ts
- * parseContentLength('Content-Length: 128') // 128
- * parseContentLength('Content-Type: application/json') // undefined
- * ```
- */
-export declare function parseContentLength(header: string): number | undefined;
-
 /**
  * Answers claims through resident TypeScript, Oxlint, and Vitest stages.
  *

package/dist/src/server/index.d.ts

@@ -202,6 +202,29 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Carries the bound a caller holds over one stage inspection.
+ *
+ * @remarks
+ * `LintStageInterface.inspect` is the only inspection in this package that reads the signal. Its
+ * wait is a foreign language server's silence, and abandoning that wait would leave the client
+ * holding a pending diagnostics request. The type and runtime stages accept no options and honor no
+ * cancellation: a coordinator abandons an overrunning one and replaces it, which is what `Probe`
+ * does when its own deadline expires.
+ *
+ * Supply the signal a coordinator already armed rather than minting a second bound here. A bound
+ * minted beside the coordinator's races it, and which one answers then depends on scheduling.
+ *
+ * @example
+ * ```ts
+ * const options: InspectionOptions = { signal: AbortSignal.timeout(30_000) }
+ * ```
+ */
+export declare interface InspectionOptions {
+    /** Aborts the inspection's wait for the resident tool's answer. */
+    readonly signal: AbortSignal;
+}
+
 /**
  * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
  *
@@ -243,13 +266,22 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * Inspects virtual documents through one resident Oxlint language server.
  *
  * @remarks
- * Construction starts the target workspace's Oxlint binary with its Language Server Protocol
- * mode. Each inspection opens the supplied text by URI, waits for published diagnostics, and
- * closes the document without writing it to disk.
+ * Construction starts the target workspace's Oxlint binary with its Language Server Protocol mode
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioTransport` owns the child process and
+ * its bytes, and `createLSPClient` owns the framing, the request correlation, the capabilities this
+ * stage advertises, and the choice between pulled and pushed diagnostics. This stage owns the
+ * workspace, the candidate identity, and the projection from a diagnostic to an `Issue`.
+ *
+ * Each inspection opens the supplied text by URI, waits for the client's diagnostics, and closes the
+ * document without writing it to disk. The caller's own signal is what bounds that wait, so a server
+ * that admits a document and publishes nothing refuses the inspection when the caller's bound
+ * expires rather than holding it for the life of the process. This stage mints no bound of its own
+ * for the wait: a second one would race the caller's, and the answer would depend on scheduling.
  *
  * Teardown is bounded at both ends. Warming waits for the server's `initialize` response and the
- * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so
- * `destroy` bounds each exchange and takes the ending back with a signal when the bound passes.
+ * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so the
+ * client's deadline bounds each exchange and the transport's cooperative window takes the ending
+ * back with a signal when that window passes.
  *
  * The URI is the path the candidate declared, so the candidate receives exactly the rule set the
  * workspace's own lint gate applies to that path, including an override anchored to one directory,
@@ -262,11 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * @example
  * ```ts
  * const stage = new LintStage('/srv/checkout')
- * const check = await stage.inspect(subject)
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
  * await stage.destroy()
  * ```
  */
-export declare class LintStage implements StageInterface {
+export declare class LintStage implements LintStageInterface {
     #private;
     /**
      * Starts warming the target workspace's Oxlint language server.
@@ -276,10 +308,42 @@ export declare class LintStage implements StageInterface {
     constructor(workspace?: string);
     get stage(): Stage_2;
     get progress(): number;
-    inspect(subject: Case_2): Promise<Check_2>;
+    inspect(subject: Case_2, options?: InspectionOptions): Promise<Check_2>;
     destroy(): Promise<void>;
 }
 
+/**
+ * Inspects one case under a bound the caller supplies.
+ *
+ * @remarks
+ * The lint stage carries a member the shared stage contract cannot. Its inspection waits for a
+ * foreign language server to publish, and only the caller knows how long that wait may run, so the
+ * bound belongs here rather than on `StageInterface`. The type and runtime stages read no signal
+ * and keep the shared one-argument `inspect`.
+ *
+ * `options` is optional because `StageInterface.inspect` accepts one argument and this contract
+ * extends it. An inspection that omits `options` is refused rather than served: a bound this stage
+ * minted for itself would race the coordinator's, and the client's own `timeout` covers the
+ * lifecycle exchanges alone.
+ *
+ * @example
+ * ```ts
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
+ * ```
+ */
+export declare interface LintStageInterface extends StageInterface {
+    /**
+     * Inspects one case, under the bound the caller supplies.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param options - The bound this inspection waits under
+     * @returns One outcome for this stage
+     * @throws When the caller supplies no bound, when the resident language server cannot start, or
+     * when the stage has already been destroyed
+     */
+    inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
+}
+
 /**
  * Holds the listeners one emitter carried for a set of events at the moment it was captured.
  *
@@ -505,12 +569,18 @@ export declare interface OverlayInterface {
  * A containment walk and the write that follows it are separate calls, so a process that swaps the
  * final component between them decides where the bytes land. `writeFileSync` opens with the default
  * `w` flag, which follows a symbolic link at that component and creates the file when it is absent,
- * so the walk's reading does not bind the write. Opening `O_WRONLY | O_TRUNC | O_NOFOLLOW` moves
- * that decision into the call that writes: a link at the final component refuses the open, and the
+ * so the walk's reading does not bind the write. Opening `O_WRONLY | O_NOFOLLOW` moves that
+ * decision into the call that writes: a link at the final component refuses the open, and the
  * omitted `O_CREAT` fails `ENOENT` for a target that has gone since the walk saw it. This is the
  * mutating counterpart of the `wx` flag every create in this package uses. Which code the refusal
  * carries is the host's; Linux with Node v22.22.2 reported `ELOOP` on 2026-08-24.
  *
+ * Truncation runs through the held descriptor rather than through an `O_TRUNC` flag, so it reaches
+ * the file the open bound. A Windows host refuses the numeric `O_TRUNC` without `O_CREAT` outright:
+ * measured on 2026-08-26 on Windows 11 with Node v24.19.0 over NTFS, `openSync` reported `EINVAL`
+ * for `O_WRONLY | O_TRUNC` and for `O_RDWR | O_TRUNC` while `O_WRONLY` alone opened, and adding
+ * `O_CREAT` would trade that refusal for the create this function must never perform.
+ *
  * A directory component stays open, because Node exposes no descriptor-relative call to walk and
  * write through one set of descriptors. Where a host's Node build defines no `O_NOFOLLOW`, that flag
  * contributes nothing to the flag set and the final component is open on that host too.
@@ -531,20 +601,6 @@ export declare interface OverlayInterface {
  */
 export declare function overwriteFile(file: string, text: string): void;
 
-/**
- * Reads a JSON-RPC frame's declared byte length.
- *
- * @param header - The frame header text without its terminating empty line
- * @returns The non-negative content length, or `undefined` for an invalid header
- *
- * @example
- * ```ts
- * parseContentLength('Content-Length: 128') // 128
- * parseContentLength('Content-Type: application/json') // undefined
- * ```
- */
-export declare function parseContentLength(header: string): number | undefined;
-
 /**
  * Answers claims through resident TypeScript, Oxlint, and Vitest stages.
  *