@orkestrel/probe 0.0.10 → 0.0.12

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

@@ -17,6 +17,26 @@ import type * as TypeScript from 'typescript';
 import { Verdict } from '@orkestrel/probe';
 import type * as VitestNode from 'vitest/node';
 
+/**
+ * Builds the fresh sibling path a revision's file is written at, preserving the test's resolution
+ * directory.
+ *
+ * @param workspace - The target workspace root
+ * @param path - The workspace-relative test path
+ * @param revision - The fresh revision identity
+ * @returns The absolute sibling path
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceFile(
+ * 	'/srv/checkout',
+ * 	buildRevisionPath('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
+ * )
+ * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
+ * ```
+ */
+export declare function buildRevisionPath(workspace: string, path: string, revision: string): string;
+
 /**
  * Records the listeners one emitter carries for a set of events.
  *
@@ -52,38 +72,45 @@ export declare function captureListeners(emitter: EventEmitter, events: readonly
 export declare function computeDigest(workspace: string, value: unknown): string;
 
 /**
- * Creates a fresh sibling identity while preserving a test's resolution directory.
+ * Normalizes a caught or foreign error into readable text.
  *
- * @param workspace - The target workspace root
- * @param path - The workspace-relative test path
- * @param revision - The fresh revision identity
- * @returns An absolute sibling file path
+ * @param value - The value to describe
+ * @returns Its message when present, or its string representation
  *
  * @example
  * ```ts
- * relativeWorkspaceFile(
- * 	'/srv/checkout',
- * 	createRevisionFile('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
- * )
- * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
+ * describeUnknown(new Error('The lint stage has been destroyed'))
+ * // 'The lint stage has been destroyed'
+ * describeUnknown(17) // '17'
  * ```
  */
-export declare function createRevisionFile(workspace: string, path: string, revision: string): string;
+export declare function describeUnknown(value: unknown): string;
 
 /**
- * Normalizes a caught or foreign error into readable text.
+ * Reports whether one path resolves outside the root it is read against.
  *
- * @param value - The value to describe
- * @returns Its message when present, or its string representation
+ * @remarks
+ * Containment decides which paths a claim may reach and which absolute paths a digest may rewrite,
+ * so one reading serves every site that asks the question. A target resolving to the root itself is
+ * contained, and each caller decides on its own what that empty relative path means for it.
+ *
+ * The test reads the relative path rather than a string prefix of the root, so a sibling directory
+ * whose name begins with the root's own text is outside rather than beneath it. An absolute
+ * relative path is the answer a host returns for two paths on different volumes, which no root
+ * contains.
+ *
+ * @param root - The root the target is read against
+ * @param target - The path to test, absolute or root-relative
+ * @returns True if the target resolves outside the root; false otherwise
  *
  * @example
  * ```ts
- * describeUnknown(new Error('The lint stage has been destroyed'))
- * // 'The lint stage has been destroyed'
- * describeUnknown(17) // '17'
+ * escapesRoot('/srv/checkout', 'src/core/greeting.ts') // false
+ * escapesRoot('/srv/checkout', '../secrets.env') // true
+ * escapesRoot('/srv/checkout', '/srv/checkout-backup/secrets.env') // true
  * ```
  */
-export declare function describeUnknown(value: unknown): string;
+export declare function escapesRoot(root: string, target: string): boolean;
 
 /**
  * Names every draft member of a claim-shaped value whose `path` this package's guard refuses.
@@ -196,9 +223,9 @@ export declare function inferTypeProject(path: string): string;
  * ```
  */
 export declare interface Inspection {
-    /** The candidate drafts and test one stage inspects. */
+    /** Holds the candidate drafts and test one stage inspects. */
     readonly subject: Case;
-    /** The claim the subject belongs to. */
+    /** Holds the claim the subject belongs to. */
     readonly claim: Claim;
 }
 
@@ -248,7 +275,7 @@ export declare interface InspectionOptions {
  *
  * @param file - The path whose creation failed
  * @param error - The fault the failed operation raised
- * @returns True when the fault means the host refuses this name; false otherwise
+ * @returns True if the fault means the host refuses this name; false otherwise
  *
  * @example
  * ```ts
@@ -267,10 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  *
  * @remarks
  * 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`.
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioClientTransport` 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
@@ -385,7 +413,7 @@ export declare function loadWorkspaceModule(workspace: string, specifier: 'vites
  * Reports whether a path is a workspace module Vitest can cache.
  *
  * @param path - The candidate file path
- * @returns True for script, TypeScript, Vue, and JSON modules; false otherwise
+ * @returns True if the path is a script, TypeScript, Vue, or JSON module; false otherwise
  *
  * @example
  * ```ts
@@ -543,9 +571,9 @@ export declare class Overlay implements OverlayInterface {
  * ```
  */
 export declare interface OverlayInterface {
-    /** Identity of the candidate set this overlay holds. */
+    /** Identifies the candidate set this overlay holds. */
     readonly revision: string;
-    /** Absolute path of every candidate this overlay holds. */
+    /** Names the absolute path of every candidate this overlay holds. */
     readonly paths: readonly string[];
     /**
      * Records one candidate's text against the absolute path it stands in for.
@@ -760,6 +788,31 @@ export declare interface ProbeServerInterface {
     destroy(): Promise<void>;
 }
 
+/**
+ * Reads the condition code a native fault carries.
+ *
+ * @remarks
+ * A caller catches `unknown`, so every reading of a caught value's own property calls into code
+ * this package does not own: a proxy whose `has` trap throws and a value whose `code` getter throws
+ * both arrive here. The read is guarded, so a fault that refuses inspection reports no code rather
+ * than raising a second fault over the first. A `code` the host reports as anything other than a
+ * string is no code this package compares against, so it reports none either.
+ *
+ * One reading serves every site that classifies a native fault, so a host condition is admitted the
+ * same way wherever it is read.
+ *
+ * @param error - The caught value to read
+ * @returns The fault's `code` when it carries a string one; `undefined` otherwise
+ *
+ * @example
+ * ```ts
+ * readFaultCode(Object.assign(new Error('no such file'), { code: 'ENOENT' })) // 'ENOENT'
+ * readFaultCode(new Error('the runtime stage was destroyed')) // undefined
+ * readFaultCode('ENOENT') // undefined
+ * ```
+ */
+export declare function readFaultCode(error: unknown): string | undefined;
+
 /**
  * Reads one installed package manifest from the target workspace.
  *
@@ -941,6 +994,11 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * 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.
+ * This stage mints its overlay with the default exact-match sensitivity, because it declares no
+ * file-name case sensitivity to Vite. A covered path whose spelling an importer wrote differs from
+ * the recorded candidate path is therefore served by whatever answers first, and `#misses` reports
+ * it as `The workspace configuration served this module before the runtime overlay` with origin
+ * `workspace` rather than leaving it answered silently.
  *
  * 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
@@ -1013,10 +1071,10 @@ export declare class RuntimeStage implements StageInterface {
  * ```
  */
 export declare interface StageInterface {
-    /** The inspection this resident stage performs. */
+    /** Names the inspection this resident stage performs. */
     readonly stage: Stage;
     /**
-     * Claimant-owned progress the coordinator compares with its inspection snapshot.
+     * Reports claimant-owned progress the coordinator compares with its inspection snapshot.
      *
      * @remarks
      * When claimant-owned work is admitted, raise `progress` before awaiting its result. When this
@@ -1165,9 +1223,9 @@ export declare interface TypeStageInterface extends StageInterface {
  * ```
  */
 export declare interface WorkspaceManifest {
-    /** Absolute path of the package manifest. */
+    /** Names the absolute path of the package manifest. */
     readonly path: string;
-    /** Parsed manifest record. */
+    /** Holds the parsed manifest record. */
     readonly contents: Readonly<Record<string, unknown>>;
 }
 

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

@@ -17,6 +17,26 @@ import type * as TypeScript from 'typescript';
 import { Verdict } from '@orkestrel/probe';
 import type * as VitestNode from 'vitest/node';
 
+/**
+ * Builds the fresh sibling path a revision's file is written at, preserving the test's resolution
+ * directory.
+ *
+ * @param workspace - The target workspace root
+ * @param path - The workspace-relative test path
+ * @param revision - The fresh revision identity
+ * @returns The absolute sibling path
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceFile(
+ * 	'/srv/checkout',
+ * 	buildRevisionPath('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
+ * )
+ * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
+ * ```
+ */
+export declare function buildRevisionPath(workspace: string, path: string, revision: string): string;
+
 /**
  * Records the listeners one emitter carries for a set of events.
  *
@@ -52,38 +72,45 @@ export declare function captureListeners(emitter: EventEmitter, events: readonly
 export declare function computeDigest(workspace: string, value: unknown): string;
 
 /**
- * Creates a fresh sibling identity while preserving a test's resolution directory.
+ * Normalizes a caught or foreign error into readable text.
  *
- * @param workspace - The target workspace root
- * @param path - The workspace-relative test path
- * @param revision - The fresh revision identity
- * @returns An absolute sibling file path
+ * @param value - The value to describe
+ * @returns Its message when present, or its string representation
  *
  * @example
  * ```ts
- * relativeWorkspaceFile(
- * 	'/srv/checkout',
- * 	createRevisionFile('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
- * )
- * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
+ * describeUnknown(new Error('The lint stage has been destroyed'))
+ * // 'The lint stage has been destroyed'
+ * describeUnknown(17) // '17'
  * ```
  */
-export declare function createRevisionFile(workspace: string, path: string, revision: string): string;
+export declare function describeUnknown(value: unknown): string;
 
 /**
- * Normalizes a caught or foreign error into readable text.
+ * Reports whether one path resolves outside the root it is read against.
  *
- * @param value - The value to describe
- * @returns Its message when present, or its string representation
+ * @remarks
+ * Containment decides which paths a claim may reach and which absolute paths a digest may rewrite,
+ * so one reading serves every site that asks the question. A target resolving to the root itself is
+ * contained, and each caller decides on its own what that empty relative path means for it.
+ *
+ * The test reads the relative path rather than a string prefix of the root, so a sibling directory
+ * whose name begins with the root's own text is outside rather than beneath it. An absolute
+ * relative path is the answer a host returns for two paths on different volumes, which no root
+ * contains.
+ *
+ * @param root - The root the target is read against
+ * @param target - The path to test, absolute or root-relative
+ * @returns True if the target resolves outside the root; false otherwise
  *
  * @example
  * ```ts
- * describeUnknown(new Error('The lint stage has been destroyed'))
- * // 'The lint stage has been destroyed'
- * describeUnknown(17) // '17'
+ * escapesRoot('/srv/checkout', 'src/core/greeting.ts') // false
+ * escapesRoot('/srv/checkout', '../secrets.env') // true
+ * escapesRoot('/srv/checkout', '/srv/checkout-backup/secrets.env') // true
  * ```
  */
-export declare function describeUnknown(value: unknown): string;
+export declare function escapesRoot(root: string, target: string): boolean;
 
 /**
  * Names every draft member of a claim-shaped value whose `path` this package's guard refuses.
@@ -196,9 +223,9 @@ export declare function inferTypeProject(path: string): string;
  * ```
  */
 export declare interface Inspection {
-    /** The candidate drafts and test one stage inspects. */
+    /** Holds the candidate drafts and test one stage inspects. */
     readonly subject: Case;
-    /** The claim the subject belongs to. */
+    /** Holds the claim the subject belongs to. */
     readonly claim: Claim;
 }
 
@@ -248,7 +275,7 @@ export declare interface InspectionOptions {
  *
  * @param file - The path whose creation failed
  * @param error - The fault the failed operation raised
- * @returns True when the fault means the host refuses this name; false otherwise
+ * @returns True if the fault means the host refuses this name; false otherwise
  *
  * @example
  * ```ts
@@ -267,10 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  *
  * @remarks
  * 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`.
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioClientTransport` 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
@@ -385,7 +413,7 @@ export declare function loadWorkspaceModule(workspace: string, specifier: 'vites
  * Reports whether a path is a workspace module Vitest can cache.
  *
  * @param path - The candidate file path
- * @returns True for script, TypeScript, Vue, and JSON modules; false otherwise
+ * @returns True if the path is a script, TypeScript, Vue, or JSON module; false otherwise
  *
  * @example
  * ```ts
@@ -543,9 +571,9 @@ export declare class Overlay implements OverlayInterface {
  * ```
  */
 export declare interface OverlayInterface {
-    /** Identity of the candidate set this overlay holds. */
+    /** Identifies the candidate set this overlay holds. */
     readonly revision: string;
-    /** Absolute path of every candidate this overlay holds. */
+    /** Names the absolute path of every candidate this overlay holds. */
     readonly paths: readonly string[];
     /**
      * Records one candidate's text against the absolute path it stands in for.
@@ -760,6 +788,31 @@ export declare interface ProbeServerInterface {
     destroy(): Promise<void>;
 }
 
+/**
+ * Reads the condition code a native fault carries.
+ *
+ * @remarks
+ * A caller catches `unknown`, so every reading of a caught value's own property calls into code
+ * this package does not own: a proxy whose `has` trap throws and a value whose `code` getter throws
+ * both arrive here. The read is guarded, so a fault that refuses inspection reports no code rather
+ * than raising a second fault over the first. A `code` the host reports as anything other than a
+ * string is no code this package compares against, so it reports none either.
+ *
+ * One reading serves every site that classifies a native fault, so a host condition is admitted the
+ * same way wherever it is read.
+ *
+ * @param error - The caught value to read
+ * @returns The fault's `code` when it carries a string one; `undefined` otherwise
+ *
+ * @example
+ * ```ts
+ * readFaultCode(Object.assign(new Error('no such file'), { code: 'ENOENT' })) // 'ENOENT'
+ * readFaultCode(new Error('the runtime stage was destroyed')) // undefined
+ * readFaultCode('ENOENT') // undefined
+ * ```
+ */
+export declare function readFaultCode(error: unknown): string | undefined;
+
 /**
  * Reads one installed package manifest from the target workspace.
  *
@@ -941,6 +994,11 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * 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.
+ * This stage mints its overlay with the default exact-match sensitivity, because it declares no
+ * file-name case sensitivity to Vite. A covered path whose spelling an importer wrote differs from
+ * the recorded candidate path is therefore served by whatever answers first, and `#misses` reports
+ * it as `The workspace configuration served this module before the runtime overlay` with origin
+ * `workspace` rather than leaving it answered silently.
  *
  * 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
@@ -1013,10 +1071,10 @@ export declare class RuntimeStage implements StageInterface {
  * ```
  */
 export declare interface StageInterface {
-    /** The inspection this resident stage performs. */
+    /** Names the inspection this resident stage performs. */
     readonly stage: Stage;
     /**
-     * Claimant-owned progress the coordinator compares with its inspection snapshot.
+     * Reports claimant-owned progress the coordinator compares with its inspection snapshot.
      *
      * @remarks
      * When claimant-owned work is admitted, raise `progress` before awaiting its result. When this
@@ -1165,9 +1223,9 @@ export declare interface TypeStageInterface extends StageInterface {
  * ```
  */
 export declare interface WorkspaceManifest {
-    /** Absolute path of the package manifest. */
+    /** Names the absolute path of the package manifest. */
     readonly path: string;
-    /** Parsed manifest record. */
+    /** Holds the parsed manifest record. */
     readonly contents: Readonly<Record<string, unknown>>;
 }