@orkestrel/probe 0.0.3 → 0.0.5

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

@@ -117,6 +117,21 @@ export declare function describeUnknown(value: unknown): string;
  */
 export declare function findRefusedPaths(value: unknown): readonly string[];
 
+/**
+ * Guards one resident-stage operation with the stage failure contract.
+ *
+ * @param stage - The resident stage serving the operation
+ * @param operation - The operation to settle
+ * @returns The operation's fulfilled value
+ * @throws The original `ProbeError`, or an instrument-owned malformed failure retaining the cause
+ *
+ * @example
+ * ```ts
+ * await guardStage('type', stage.inspect(subject))
+ * ```
+ */
+export declare function guardStage<T>(stage: Stage, operation: Promise<T>): Promise<T>;
+
 /**
  * Selects the Language Server Protocol language identifier for a source path.
  *
@@ -482,6 +497,40 @@ export declare interface OverlayInterface {
     clear(): void;
 }
 
+/**
+ * Overwrites a file that already exists, through a descriptor that refuses a symbolic link at the
+ * final component.
+ *
+ * @remarks
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * @param file - The absolute path to overwrite
+ * @param text - The text to write
+ * @returns Nothing
+ * @throws The host's own fault when the final component is a symbolic link, when the file is
+ * absent, or when the host refuses the descriptor
+ *
+ * @example
+ * ```ts
+ * const file = resolveWorkspaceFile('/srv/checkout', 'tmp/probe/arm-type.ts', true)
+ * writeFileSync(file, 'export type Signal = string\n', { encoding: 'utf8', flag: 'wx' })
+ * overwriteFile(file, 'export type Signal = number\n')
+ * readFileSync(file, 'utf8') // 'export type Signal = number\n'
+ * ```
+ */
+export declare function overwriteFile(file: string, text: string): void;
+
 /**
  * Reads a JSON-RPC frame's declared byte length.
  *
@@ -649,6 +698,49 @@ export declare function readWorkspaceManifest(workspace: string, name: string):
  */
 export declare function relativeWorkspaceFile(workspace: string, file: string): string;
 
+/**
+ * Projects the paths one tool named in a message into the forms this package's issues expose.
+ *
+ * @remarks
+ * An issue's `path` is workspace-relative, and its message is prose a tool wrote about the same
+ * tree. Left alone that prose names a file by the host's own layout, so one issue reports a path two
+ * ways and a reader on another checkout is sent to a directory that is not theirs. Each spelling of
+ * the root is removed: the absolute path, the backslash spelling a Windows tool writes, and the
+ * `file:` URL a runtime names a module by. A root the host itself names ends in a separator, and the
+ * paths beneath it continue straight from it rather than from one more separator. A path outside the
+ * workspace stands as it is, because a relative spelling of it would name a file the tree does not
+ * hold.
+ *
+ * A spelling of the root counts only where a path begins: at the start of the message, or after a
+ * character no path carries. A directory whose own name ends in this root's text holds a different
+ * tree, so the root inside a longer path names a file this workspace does not hold and that path
+ * survives whole.
+ *
+ * Only the root is removed. A name is otherwise the tool's, including a `.probe-` name that reads
+ * like a specification this package generates: the stage that wrote one knows the exact name it
+ * wrote and renames that name itself, which is the only reading that separates its own file from a
+ * file the target tree owns.
+ *
+ * Everything else the tool wrote survives verbatim, separators included. A message carries text
+ * that is not a path — a runtime escapes a newline as a backslash when it prints a string inline,
+ * and a compiler quotes a string literal with its escapes intact — so rewriting every separator
+ * would corrupt the evidence the message exists to carry. The cost is that the path left behind
+ * keeps the separator the tool chose, which on Windows is not the one `Issue.path` uses.
+ *
+ * @param workspace - The target workspace root
+ * @param message - The message a tool reported
+ * @returns The message with the host's own layout removed from every path that begins with it
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceMessage('/srv/checkout', 'Cannot read /srv/checkout/tsconfig.json')
+ * // 'Cannot read tsconfig.json'
+ * relativeWorkspaceMessage('/srv/checkout', 'Cannot read /mirror/srv/checkout/tsconfig.json')
+ * // 'Cannot read /mirror/srv/checkout/tsconfig.json'
+ * ```
+ */
+export declare function relativeWorkspaceMessage(workspace: string, message: string): string;
+
 /**
  * Removes every listener one emitter gained for the captured events since its capture.
  *
@@ -749,6 +841,13 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * workspace module whose disk content or candidate revision changed, runs that specification,
  * evicts its result, and deletes the file. Clearing the overlay makes the next snapshot differ from
  * the candidate revision, so the next inspection invalidates that module and reads disk again.
+ * After the run, the stage checks each covered module reachable from the generated specification
+ * against the overlay paths its loader served. A target-config loader that served first produces a
+ * workspace issue; a module id probe's loader received but failed to match produces an instrument
+ * issue.
+ * The runtime overlay leaves bare specifier resolution to Vite: it replaces a bare import only
+ * after Vite resolves that import to a covered file. The type stage overlays the declared test
+ * path, while this stage executes a generated sibling and overlays only the candidate files.
  *
  * Vite retains one unresolved URL for every specification path, so the stage replaces its whole
  * Vitest service after 64 specifications rather than deleting from each map that service owns. Any
@@ -772,9 +871,12 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * test path the host refuses to create is a claimant failure with `code: 'refused'`. Each is thrown
  * rather than reported, because a test that never ran is no evidence about the candidate.
  *
- * The write path's physical-containment guarantee covers the claim inputs and the target tree as
- * inspected. A concurrent process that mutates a path component between the final inspection and
- * the write is outside that guarantee.
+ * Physical containment covers the claim inputs, the target tree as the walk inspected it, and the
+ * final component at the moment this stage writes or unlinks it: a specification is created with the
+ * `wx` flag, which fails rather than following a symbolic link that appeared after the walk, and an
+ * unlink names the final component itself rather than what it points at. A directory component
+ * swapped for a symbolic link between the walk and the write stays open, because Node exposes no
+ * descriptor-relative call to pin the walk and the write to one set of descriptors.
  *
  * @example
  * ```ts

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

@@ -117,6 +117,21 @@ export declare function describeUnknown(value: unknown): string;
  */
 export declare function findRefusedPaths(value: unknown): readonly string[];
 
+/**
+ * Guards one resident-stage operation with the stage failure contract.
+ *
+ * @param stage - The resident stage serving the operation
+ * @param operation - The operation to settle
+ * @returns The operation's fulfilled value
+ * @throws The original `ProbeError`, or an instrument-owned malformed failure retaining the cause
+ *
+ * @example
+ * ```ts
+ * await guardStage('type', stage.inspect(subject))
+ * ```
+ */
+export declare function guardStage<T>(stage: Stage, operation: Promise<T>): Promise<T>;
+
 /**
  * Selects the Language Server Protocol language identifier for a source path.
  *
@@ -482,6 +497,40 @@ export declare interface OverlayInterface {
     clear(): void;
 }
 
+/**
+ * Overwrites a file that already exists, through a descriptor that refuses a symbolic link at the
+ * final component.
+ *
+ * @remarks
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * @param file - The absolute path to overwrite
+ * @param text - The text to write
+ * @returns Nothing
+ * @throws The host's own fault when the final component is a symbolic link, when the file is
+ * absent, or when the host refuses the descriptor
+ *
+ * @example
+ * ```ts
+ * const file = resolveWorkspaceFile('/srv/checkout', 'tmp/probe/arm-type.ts', true)
+ * writeFileSync(file, 'export type Signal = string\n', { encoding: 'utf8', flag: 'wx' })
+ * overwriteFile(file, 'export type Signal = number\n')
+ * readFileSync(file, 'utf8') // 'export type Signal = number\n'
+ * ```
+ */
+export declare function overwriteFile(file: string, text: string): void;
+
 /**
  * Reads a JSON-RPC frame's declared byte length.
  *
@@ -649,6 +698,49 @@ export declare function readWorkspaceManifest(workspace: string, name: string):
  */
 export declare function relativeWorkspaceFile(workspace: string, file: string): string;
 
+/**
+ * Projects the paths one tool named in a message into the forms this package's issues expose.
+ *
+ * @remarks
+ * An issue's `path` is workspace-relative, and its message is prose a tool wrote about the same
+ * tree. Left alone that prose names a file by the host's own layout, so one issue reports a path two
+ * ways and a reader on another checkout is sent to a directory that is not theirs. Each spelling of
+ * the root is removed: the absolute path, the backslash spelling a Windows tool writes, and the
+ * `file:` URL a runtime names a module by. A root the host itself names ends in a separator, and the
+ * paths beneath it continue straight from it rather than from one more separator. A path outside the
+ * workspace stands as it is, because a relative spelling of it would name a file the tree does not
+ * hold.
+ *
+ * A spelling of the root counts only where a path begins: at the start of the message, or after a
+ * character no path carries. A directory whose own name ends in this root's text holds a different
+ * tree, so the root inside a longer path names a file this workspace does not hold and that path
+ * survives whole.
+ *
+ * Only the root is removed. A name is otherwise the tool's, including a `.probe-` name that reads
+ * like a specification this package generates: the stage that wrote one knows the exact name it
+ * wrote and renames that name itself, which is the only reading that separates its own file from a
+ * file the target tree owns.
+ *
+ * Everything else the tool wrote survives verbatim, separators included. A message carries text
+ * that is not a path — a runtime escapes a newline as a backslash when it prints a string inline,
+ * and a compiler quotes a string literal with its escapes intact — so rewriting every separator
+ * would corrupt the evidence the message exists to carry. The cost is that the path left behind
+ * keeps the separator the tool chose, which on Windows is not the one `Issue.path` uses.
+ *
+ * @param workspace - The target workspace root
+ * @param message - The message a tool reported
+ * @returns The message with the host's own layout removed from every path that begins with it
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceMessage('/srv/checkout', 'Cannot read /srv/checkout/tsconfig.json')
+ * // 'Cannot read tsconfig.json'
+ * relativeWorkspaceMessage('/srv/checkout', 'Cannot read /mirror/srv/checkout/tsconfig.json')
+ * // 'Cannot read /mirror/srv/checkout/tsconfig.json'
+ * ```
+ */
+export declare function relativeWorkspaceMessage(workspace: string, message: string): string;
+
 /**
  * Removes every listener one emitter gained for the captured events since its capture.
  *
@@ -749,6 +841,13 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * workspace module whose disk content or candidate revision changed, runs that specification,
  * evicts its result, and deletes the file. Clearing the overlay makes the next snapshot differ from
  * the candidate revision, so the next inspection invalidates that module and reads disk again.
+ * After the run, the stage checks each covered module reachable from the generated specification
+ * against the overlay paths its loader served. A target-config loader that served first produces a
+ * workspace issue; a module id probe's loader received but failed to match produces an instrument
+ * issue.
+ * The runtime overlay leaves bare specifier resolution to Vite: it replaces a bare import only
+ * after Vite resolves that import to a covered file. The type stage overlays the declared test
+ * path, while this stage executes a generated sibling and overlays only the candidate files.
  *
  * Vite retains one unresolved URL for every specification path, so the stage replaces its whole
  * Vitest service after 64 specifications rather than deleting from each map that service owns. Any
@@ -772,9 +871,12 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * test path the host refuses to create is a claimant failure with `code: 'refused'`. Each is thrown
  * rather than reported, because a test that never ran is no evidence about the candidate.
  *
- * The write path's physical-containment guarantee covers the claim inputs and the target tree as
- * inspected. A concurrent process that mutates a path component between the final inspection and
- * the write is outside that guarantee.
+ * Physical containment covers the claim inputs, the target tree as the walk inspected it, and the
+ * final component at the moment this stage writes or unlinks it: a specification is created with the
+ * `wx` flag, which fails rather than following a symbolic link that appeared after the walk, and an
+ * unlink names the final component itself rather than what it points at. A directory component
+ * swapped for a symbolic link between the walk and the write stays open, because Node exposes no
+ * descriptor-relative call to pin the walk and the write to one set of descriptors.
  *
  * @example
  * ```ts