doc-detective 4.27.0 → 4.28.0

package/dist/runtime/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/runtime/lock.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;IAC9D,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,sFAAsF;IACtF,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;CAC5D;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,OAAO,IAAI,IAAI,CAAC;CACjB;AA+BD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAqJ5B;AAoBD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,OAAO,EAAE,kBAAkB,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC,CAQ5C"}

package/dist/runtime/lock.js

@@ -0,0 +1,218 @@
+// Cross-process advisory lock (mkdir-as-lock) for single-writer critical
+// sections in the runtime cache — first consumer: the WebDriverAgent prebuild
+// in `install ios` (docs/design/ios-wda-prebuild.md), where a legitimate
+// xcodebuild can hold the lock for ~20 minutes.
+//
+// Staleness is a HEARTBEAT LEASE, not age-since-acquire: the holder refreshes
+// the metadata timestamp on a short interval, and a contender may take over
+// only when that heartbeat has gone stale (many missed refreshes) or, on the
+// same host, the recorded pid is dead. Lock age alone never permits takeover —
+// a TTL long enough to cover a slow build would make a crashed holder block
+// the next build for that whole window, and a shorter one would steal live
+// builds.
+//
+// All effects (fs, clock, sleep, pid liveness, the heartbeat timer) are
+// injectable so the lock is hermetically unit-testable.
+import fsDefault from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // Dead ONLY on ESRCH (no such process). Any other error — EPERM
+        // (exists, different user) or something unexpected — reads as alive:
+        // this check licenses stealing a lock and deleting a live xcodebuild's
+        // output, so uncertainty must never count as dead. Matches the
+        // repo's other liveness probes (src/core/tests.ts).
+        return err?.code !== "ESRCH";
+    }
+}
+function defaultStartInterval(fn, ms) {
+    const timer = setInterval(fn, ms);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+const OWNER_FILE = "owner.json";
+/**
+ * Acquire the advisory lock at `dir`, waiting up to `waitMs`. Returns a
+ * handle whose `release()` frees the lock, or `null` when the wait elapsed
+ * with the lock still held by a live owner.
+ */
+export async function acquireLock(options) {
+    const { dir, waitMs = 10 * 60_000, pollMs = 1_000, heartbeatMs = 30_000, staleMs = 5 * 60_000, deps = {}, } = options;
+    const fs = deps.fs ?? fsDefault;
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ??
+        ((ms) => new Promise((r) => {
+            const timer = setTimeout(r, ms);
+            timer.unref?.();
+        }));
+    const pid = deps.pid ?? process.pid;
+    const hostname = deps.hostname ?? os.hostname();
+    const isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;
+    const startInterval = deps.startInterval ?? defaultStartInterval;
+    const ownerPath = `${dir}/${OWNER_FILE}`;
+    const deadline = now() + waitMs;
+    // The parent provably exists after this; the loop body only runs the
+    // exclusive-mkdir arbiter plus the staleness read.
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    // Missing/corrupt owner metadata gets one poll-cycle of grace before it is
+    // treated as stealable: a healthy acquirer writes owner.json microseconds
+    // after its mkdir wins, so metadata that is STILL absent a poll later marks
+    // a crash in that window, not a race with a live acquirer.
+    let metaMissingSince = null;
+    for (;;) {
+        // Attempt the exclusive mkdir that IS the lock. EEXIST means contention;
+        // anything else propagates.
+        try {
+            fs.mkdirSync(dir);
+            return takeOwnership();
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+        }
+        // Held by someone. Decide whether the holder is recoverable. Metadata
+        // that parses but has the wrong shape (non-numeric heartbeatAt would make
+        // the staleness comparison NaN — permanently false) is treated exactly
+        // like missing metadata: grace, then stealable.
+        const meta = readOwnerMeta(fs, ownerPath);
+        let stealable = false;
+        if (meta) {
+            metaMissingSince = null;
+            const heartbeatStale = now() - meta.heartbeatAt > staleMs;
+            const deadOnThisHost = meta.hostname === hostname && !isPidAlive(meta.pid);
+            stealable = heartbeatStale || deadOnThisHost;
+        }
+        else {
+            metaMissingSince ??= now();
+            stealable = now() - metaMissingSince >= pollMs;
+        }
+        if (stealable) {
+            // Takeover is arbitrated by RENAME, not rm: exactly one of N
+            // simultaneous stealers wins the rename of the dead holder's dir to a
+            // unique trash name, so a loser can never delete a lock a winner just
+            // re-acquired (the classic rm-based double-steal race). The loser's
+            // rename throws (ENOENT) and it loops back to find the winner's fresh
+            // lock. Trash dirs are cleaned best-effort here and are also
+            // markerless siblings to the WDA prune pass.
+            const trash = `${dir}.stale-${pid}-${now()}`;
+            try {
+                fs.renameSync(dir, trash);
+                try {
+                    fs.rmSync(trash, { recursive: true, force: true });
+                }
+                catch {
+                    /* best-effort trash cleanup */
+                }
+                // Won the takeover — retry the mkdir immediately (guaranteed
+                // progress, no busy-spin risk: the dir is gone).
+                continue;
+            }
+            catch {
+                // Lost the takeover race, or the dir is un-removable (EACCES from a
+                // different-user run). Fall through to the deadline check and sleep
+                // so an un-stealable stale lock still times out instead of spinning.
+            }
+        }
+        if (now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+    function takeOwnership() {
+        const acquiredAt = now();
+        const writeMeta = () => {
+            // acquiredAt is fixed at acquisition; only the heartbeat refreshes.
+            const meta = {
+                pid,
+                hostname,
+                acquiredAt,
+                heartbeatAt: now(),
+            };
+            fs.writeFileSync(ownerPath, JSON.stringify(meta));
+        };
+        // Still-ours check: after a lease takeover (this process was suspended
+        // past staleMs and a contender legitimately stole the lock), the old
+        // holder must neither overwrite the new owner's metadata nor remove the
+        // new owner's lock dir on release.
+        const isStillOwner = () => {
+            const meta = readOwnerMeta(fs, ownerPath);
+            return meta !== null && meta.pid === pid && meta.hostname === hostname;
+        };
+        writeMeta();
+        let lost = false;
+        const stopHeartbeat = startInterval(() => {
+            // Refresh the lease — but never resurrect a stolen lock. Never throw
+            // from a timer: if the dir vanished (external cleanup), the refresh
+            // just fails and release() stays safe.
+            try {
+                if (!isStillOwner()) {
+                    lost = true;
+                    stopHeartbeat();
+                    return;
+                }
+                writeMeta();
+            }
+            catch {
+                /* best-effort */
+            }
+        }, heartbeatMs);
+        let released = false;
+        return {
+            release() {
+                if (released)
+                    return;
+                released = true;
+                stopHeartbeat();
+                if (lost)
+                    return;
+                try {
+                    // Same guard on the release path: only remove the dir while the
+                    // metadata is still ours.
+                    if (!isStillOwner())
+                        return;
+                    fs.rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    /* already gone */
+                }
+            },
+        };
+    }
+}
+/** Parse and shape-validate owner metadata; null for missing/corrupt/wrong-shape. */
+function readOwnerMeta(fs, ownerPath) {
+    try {
+        const parsed = JSON.parse(String(fs.readFileSync(ownerPath)));
+        if (typeof parsed?.pid !== "number" ||
+            typeof parsed?.hostname !== "string" ||
+            typeof parsed?.acquiredAt !== "number" ||
+            typeof parsed?.heartbeatAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `fn` while holding the lock, releasing on both success and throw.
+ * Returns `null` without running `fn` when the lock could not be acquired
+ * within the wait bound.
+ */
+export async function withLock(options, fn) {
+    const handle = await acquireLock(options);
+    if (!handle)
+        return { acquired: false };
+    try {
+        return { acquired: true, result: await fn() };
+    }
+    finally {
+        handle.release();
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/runtime/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/runtime/lock.ts"],"names":[],"mappings":"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"}

package/dist/runtime/wdaProducts.d.ts

@@ -0,0 +1,147 @@
+import { type CacheDirContext } from "./cacheDir.js";
+export interface XcodeVersion {
+    /** e.g. "16.4" */
+    version: string;
+    /** e.g. "16F6" — distinguishes two images shipping the same marketing version. */
+    build: string;
+}
+/**
+ * Minimum Xcode major for the WDA prebuild. Below this the
+ * `build-for-testing` invocation against the generic iOS Simulator
+ * destination (and the appium-xcuitest-driver versions we install) are not
+ * supported — skip with upgrade guidance instead of attempting a doomed
+ * build. Floor per the design doc's "likely 14+"; revisit against the live
+ * macOS leg if it ever disagrees.
+ */
+export declare const MIN_XCODE_MAJOR = 14;
+/**
+ * Parse `xcodebuild -version` output:
+ *
+ *   Xcode 16.4
+ *   Build version 16F6
+ *
+ * Returns null when the output doesn't look like full Xcode (e.g. the
+ * Command Line Tools error text) — only full Xcode can build WDA.
+ */
+export declare function parseXcodebuildVersion(output: unknown): XcodeVersion | null;
+export declare function xcodeMajor(xcode: XcodeVersion): number;
+/** The managed WDA root: <cacheDir>/ios/wda. */
+export declare function getWdaRoot(ctx?: CacheDirContext): string;
+export interface WdaFs {
+    existsSync(p: string): boolean;
+    readFileSync(p: string): string | Buffer;
+    writeFileSync(p: string, data: string): void;
+    mkdirSync(p: string, opts?: {
+        recursive?: boolean;
+    }): unknown;
+    renameSync(from: string, to: string): void;
+    rmSync(p: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    readdirSync(p: string): string[];
+    statSync(p: string): {
+        mtimeMs: number;
+    };
+}
+/**
+ * The cache key a WDA build is valid for: Xcode marketing version + build id
+ * (two runner images can ship the same marketing version) + the exact
+ * appium-xcuitest-driver version whose bundled WDA source was compiled.
+ */
+export declare function computeWdaKey(xcode: XcodeVersion, driverVersion: string): string;
+/** Where xcodebuild's products land inside a key dir. */
+export declare const RUNNER_APP_RELATIVE: string;
+export declare const PRODUCTS_MARKER = "products.json";
+export declare const LAST_USED_STAMP = "last-used";
+/** The writer's advisory-lock dir name under the WDA root — one name shared
+ * by the acquire call and the prune pass's skip check so they can't drift. */
+export declare const WDA_LOCK_DIRNAME = ".lock";
+export interface WdaProductsMarker {
+    key: string;
+    driverVersion: string;
+    /** Diagnostic metadata — validated shape only, never consumed by readers. */
+    xcode?: XcodeVersion;
+    runnerApp?: string;
+    builtAt?: string;
+}
+/**
+ * Read and validate a key dir's completeness marker. Null on any miss:
+ * absent/corrupt marker (a crashed half-built dir never wrote one — that is
+ * the lock-free correctness story for readers) or a key dir whose Runner app
+ * is gone. The Runner check uses the layout-relative path, NOT the absolute
+ * path recorded in the marker, so a relocated cache root (moved home dir,
+ * container bind-mount, CI cache restored under a different path) keeps its
+ * valid products instead of misreading them all as stale.
+ */
+export declare function readProductsMarker(keyDir: string, fs: WdaFs): WdaProductsMarker | null;
+/**
+ * Touch a key dir's last-used stamp — the prune-freshness signal shared by
+ * the installer (writes it at build time, stats it when pruning) and the
+ * session locator (touches it on every valid hit). Best-effort: a failed
+ * stamp only risks an early prune much later.
+ */
+export declare function touchLastUsed(keyDir: string, fs: WdaFs, now: () => number): void;
+/**
+ * Minimum appium-xcuitest-driver MAJOR whose prebuilt-WDA consumption
+ * (`appium:usePrebuiltWDA` + `appium:derivedDataPath`) this locator has been
+ * validated against (the live macOS fixture legs run the 10.x line that
+ * doc-detective's declared range installs). Prebuilt handling is
+ * driver-version-sensitive across older majors (`prebuiltWDAPath` /
+ * `useXctestrunFile` variants, differing .xctestrun handling), so anything
+ * below the floor gets a plain fallback — today's build-in-session behavior —
+ * never a guess.
+ */
+export declare const MIN_PREBUILT_WDA_DRIVER_MAJOR = 10;
+export interface LocateManagedWdaOptions {
+    ctx?: CacheDirContext;
+    fs?: WdaFs;
+    platform?: NodeJS.Platform;
+    probeXcode?: () => XcodeVersion | null;
+    resolveDriverVersion?: (name: string, ctx: CacheDirContext) => string | null;
+    /** Test override for the managed WDA root (default: <cacheDir>/ios/wda). */
+    wdaRootDir?: string;
+    now?: () => number;
+}
+export interface ManagedWdaHit {
+    key: string;
+    /** Value for appium:derivedDataPath — the keyed DerivedData dir. */
+    derivedDataPath: string;
+}
+/**
+ * Pure managed-products locator for iOS session capability builders: find
+ * the prebuilt WDA products matching the CURRENT toolchain (installed
+ * driver version × host Xcode). On a valid hit, touch the last-used stamp
+ * (the prune signal) and return the derivedDataPath to consume read-only
+ * with `appium:usePrebuiltWDA`. Any miss — wrong platform, unresolvable
+ * driver, driver below the supported floor, no full Xcode, absent/stale
+ * marker — returns null and the session builds WDA itself, exactly today's
+ * behavior. Never throws.
+ */
+export declare function locateManagedWda(options?: LocateManagedWdaOptions): ManagedWdaHit | null;
+/**
+ * Apply the WDA derived-data capabilities for an iOS XCUITest session — the
+ * ONE place the env-override-vs-managed-products precedence and the exact
+ * capability pair live, shared by the app-surface and mobile-web builders so
+ * the two cannot drift (the pair is driver-version-sensitive; see
+ * MIN_PREBUILT_WDA_DRIVER_MAJOR).
+ *
+ * Precedence: DOC_DETECTIVE_IOS_WDA_DERIVED_DATA_PATH set → exactly the
+ * historical behavior (`derivedDataPath` only, caller owns semantics; the
+ * managed locator is not consulted). Otherwise a managed-products hit sets
+ * both `appium:derivedDataPath` (the keyed DerivedData) and
+ * `appium:usePrebuiltWDA` (read-only consumption — the concurrency answer).
+ * No locator or a miss → no capabilities change (today's behavior: the
+ * session builds WDA itself in a throwaway per-session temp dir).
+ */
+export declare function applyManagedWdaCapabilities(capabilities: Record<string, any>, locateWda?: () => ManagedWdaHit | null): void;
+/**
+ * Locate the WebDriverAgent source bundled with the installed
+ * appium-xcuitest-driver: walk up from the driver's resolved entry looking
+ * for a `node_modules/appium-webdriveragent` that actually contains the
+ * Xcode project. The walk (rather than a hardcoded relative path) is what
+ * absorbs npm's hoisting variability — nested under the driver on some
+ * installs, hoisted to the runtime root on others.
+ */
+export declare function findWdaSource(driverEntryPath: string, fs: Pick<WdaFs, "existsSync">): string | null;
+//# sourceMappingURL=wdaProducts.d.ts.map

package/dist/runtime/wdaProducts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wdaProducts.d.ts","sourceRoot":"","sources":["../../src/runtime/wdaProducts.ts"],"names":[],"mappings":"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"}

package/dist/runtime/wdaProducts.js

@@ -0,0 +1,234 @@
+// Managed WebDriverAgent build products: the shared key/probe/marker
+// vocabulary between the `install ios` prebuild (writer) and the session-time
+// locator (reader). See docs/design/ios-wda-prebuild.md.
+//
+// Layout under the cache dir:
+//   <cacheDir>/ios/wda/<key>/DerivedData/    xcodebuild -derivedDataPath target
+//   <cacheDir>/ios/wda/<key>/products.json   completeness marker, written LAST
+//   <cacheDir>/ios/wda/<key>/last-used       sidecar stamp touched by readers
+//   <cacheDir>/ios/wda/.lock/                writer's advisory lock
+import { spawnSync } from "node:child_process";
+import fsDefault from "node:fs";
+import path from "node:path";
+import { getCacheDir } from "./cacheDir.js";
+import { resolveHeavyDepVersion } from "./loader.js";
+/**
+ * Minimum Xcode major for the WDA prebuild. Below this the
+ * `build-for-testing` invocation against the generic iOS Simulator
+ * destination (and the appium-xcuitest-driver versions we install) are not
+ * supported — skip with upgrade guidance instead of attempting a doomed
+ * build. Floor per the design doc's "likely 14+"; revisit against the live
+ * macOS leg if it ever disagrees.
+ */
+export const MIN_XCODE_MAJOR = 14;
+/**
+ * Parse `xcodebuild -version` output:
+ *
+ *   Xcode 16.4
+ *   Build version 16F6
+ *
+ * Returns null when the output doesn't look like full Xcode (e.g. the
+ * Command Line Tools error text) — only full Xcode can build WDA.
+ */
+export function parseXcodebuildVersion(output) {
+    const text = String(output ?? "");
+    const version = /^\s*Xcode\s+(\S+)/m.exec(text)?.[1];
+    const build = /^\s*Build version\s+(\S+)/m.exec(text)?.[1];
+    if (!version || !build)
+        return null;
+    return { version, build };
+}
+export function xcodeMajor(xcode) {
+    const major = Number.parseInt(xcode.version, 10);
+    return Number.isFinite(major) ? major : 0;
+}
+/** The managed WDA root: <cacheDir>/ios/wda. */
+export function getWdaRoot(ctx = {}) {
+    return path.join(getCacheDir(ctx), "ios", "wda");
+}
+// actions/cache-style conservative charset: collapse anything outside
+// [A-Za-z0-9._-] to a single "-" so versions with build metadata or spaces
+// can't produce hostile directory names.
+function sanitizeKeySegment(value) {
+    return ((value || "unknown").trim().replace(/[^A-Za-z0-9._-]+/g, "-") || "unknown");
+}
+/**
+ * The cache key a WDA build is valid for: Xcode marketing version + build id
+ * (two runner images can ship the same marketing version) + the exact
+ * appium-xcuitest-driver version whose bundled WDA source was compiled.
+ */
+export function computeWdaKey(xcode, driverVersion) {
+    return `xcode-${sanitizeKeySegment(xcode.version)}-${sanitizeKeySegment(xcode.build)}-driver-${sanitizeKeySegment(driverVersion)}`;
+}
+/** Where xcodebuild's products land inside a key dir. */
+export const RUNNER_APP_RELATIVE = path.join("DerivedData", "Build", "Products", "Debug-iphonesimulator", "WebDriverAgentRunner-Runner.app");
+export const PRODUCTS_MARKER = "products.json";
+export const LAST_USED_STAMP = "last-used";
+/** The writer's advisory-lock dir name under the WDA root — one name shared
+ * by the acquire call and the prune pass's skip check so they can't drift. */
+export const WDA_LOCK_DIRNAME = ".lock";
+/**
+ * Read and validate a key dir's completeness marker. Null on any miss:
+ * absent/corrupt marker (a crashed half-built dir never wrote one — that is
+ * the lock-free correctness story for readers) or a key dir whose Runner app
+ * is gone. The Runner check uses the layout-relative path, NOT the absolute
+ * path recorded in the marker, so a relocated cache root (moved home dir,
+ * container bind-mount, CI cache restored under a different path) keeps its
+ * valid products instead of misreading them all as stale.
+ */
+export function readProductsMarker(keyDir, fs) {
+    try {
+        const parsed = JSON.parse(String(fs.readFileSync(path.join(keyDir, PRODUCTS_MARKER))));
+        if (typeof parsed?.key !== "string" ||
+            typeof parsed?.driverVersion !== "string") {
+            return null;
+        }
+        if (!fs.existsSync(path.join(keyDir, RUNNER_APP_RELATIVE)))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Touch a key dir's last-used stamp — the prune-freshness signal shared by
+ * the installer (writes it at build time, stats it when pruning) and the
+ * session locator (touches it on every valid hit). Best-effort: a failed
+ * stamp only risks an early prune much later.
+ */
+export function touchLastUsed(keyDir, fs, now) {
+    try {
+        fs.writeFileSync(path.join(keyDir, LAST_USED_STAMP), String(now()));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// --- session-time locator (design phase 3) ---
+/**
+ * Minimum appium-xcuitest-driver MAJOR whose prebuilt-WDA consumption
+ * (`appium:usePrebuiltWDA` + `appium:derivedDataPath`) this locator has been
+ * validated against (the live macOS fixture legs run the 10.x line that
+ * doc-detective's declared range installs). Prebuilt handling is
+ * driver-version-sensitive across older majors (`prebuiltWDAPath` /
+ * `useXctestrunFile` variants, differing .xctestrun handling), so anything
+ * below the floor gets a plain fallback — today's build-in-session behavior —
+ * never a guess.
+ */
+export const MIN_PREBUILT_WDA_DRIVER_MAJOR = 10;
+// One `xcodebuild -version` spawn max per process: sessions can be created
+// many times per run, and the Xcode version cannot change mid-run.
+let cachedXcodeProbe;
+/* c8 ignore start — real spawn; unit tests inject probeXcode. */
+function probeXcodeVersionCached() {
+    if (cachedXcodeProbe === undefined) {
+        try {
+            const result = spawnSync("xcodebuild", ["-version"], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 15000,
+            });
+            cachedXcodeProbe =
+                result.status === 0 ? parseXcodebuildVersion(result.stdout) : null;
+        }
+        catch {
+            cachedXcodeProbe = null;
+        }
+    }
+    return cachedXcodeProbe;
+}
+/**
+ * Pure managed-products locator for iOS session capability builders: find
+ * the prebuilt WDA products matching the CURRENT toolchain (installed
+ * driver version × host Xcode). On a valid hit, touch the last-used stamp
+ * (the prune signal) and return the derivedDataPath to consume read-only
+ * with `appium:usePrebuiltWDA`. Any miss — wrong platform, unresolvable
+ * driver, driver below the supported floor, no full Xcode, absent/stale
+ * marker — returns null and the session builds WDA itself, exactly today's
+ * behavior. Never throws.
+ */
+export function locateManagedWda(options = {}) {
+    const { ctx = {}, fs = fsDefault, platform = process.platform, probeXcode = probeXcodeVersionCached, resolveDriverVersion = resolveHeavyDepVersion, now = Date.now, } = options;
+    try {
+        if (platform !== "darwin")
+            return null;
+        const driverVersion = resolveDriverVersion("appium-xcuitest-driver", ctx);
+        if (!driverVersion)
+            return null;
+        const driverMajor = Number.parseInt(driverVersion, 10);
+        if (!Number.isFinite(driverMajor) ||
+            driverMajor < MIN_PREBUILT_WDA_DRIVER_MAJOR) {
+            return null;
+        }
+        const xcode = probeXcode();
+        if (!xcode)
+            return null;
+        const wdaRoot = path.normalize(options.wdaRootDir ?? getWdaRoot(ctx));
+        const key = computeWdaKey(xcode, driverVersion);
+        const keyDir = path.join(wdaRoot, key);
+        const marker = readProductsMarker(keyDir, fs);
+        // The key is the single identity: it already encodes the driver version,
+        // so `marker.key === key` is the whole match.
+        if (!marker || marker.key !== key)
+            return null;
+        // Readers are read-only consumers of the DerivedData — the stamp is the
+        // one exception (it's the prune-freshness signal).
+        touchLastUsed(keyDir, fs, now);
+        return { key, derivedDataPath: path.join(keyDir, "DerivedData") };
+    }
+    catch {
+        // ADR 01049 degradation semantics: an unusable cache is a plain miss.
+        return null;
+    }
+}
+/**
+ * Apply the WDA derived-data capabilities for an iOS XCUITest session — the
+ * ONE place the env-override-vs-managed-products precedence and the exact
+ * capability pair live, shared by the app-surface and mobile-web builders so
+ * the two cannot drift (the pair is driver-version-sensitive; see
+ * MIN_PREBUILT_WDA_DRIVER_MAJOR).
+ *
+ * Precedence: DOC_DETECTIVE_IOS_WDA_DERIVED_DATA_PATH set → exactly the
+ * historical behavior (`derivedDataPath` only, caller owns semantics; the
+ * managed locator is not consulted). Otherwise a managed-products hit sets
+ * both `appium:derivedDataPath` (the keyed DerivedData) and
+ * `appium:usePrebuiltWDA` (read-only consumption — the concurrency answer).
+ * No locator or a miss → no capabilities change (today's behavior: the
+ * session builds WDA itself in a throwaway per-session temp dir).
+ */
+export function applyManagedWdaCapabilities(capabilities, locateWda) {
+    const derivedDataPath = process.env.DOC_DETECTIVE_IOS_WDA_DERIVED_DATA_PATH;
+    if (derivedDataPath && derivedDataPath.trim()) {
+        capabilities["appium:derivedDataPath"] = derivedDataPath.trim();
+        return;
+    }
+    const managed = locateWda?.();
+    if (managed) {
+        capabilities["appium:derivedDataPath"] = managed.derivedDataPath;
+        capabilities["appium:usePrebuiltWDA"] = true;
+    }
+}
+/**
+ * Locate the WebDriverAgent source bundled with the installed
+ * appium-xcuitest-driver: walk up from the driver's resolved entry looking
+ * for a `node_modules/appium-webdriveragent` that actually contains the
+ * Xcode project. The walk (rather than a hardcoded relative path) is what
+ * absorbs npm's hoisting variability — nested under the driver on some
+ * installs, hoisted to the runtime root on others.
+ */
+export function findWdaSource(driverEntryPath, fs) {
+    let dir = path.dirname(driverEntryPath);
+    for (let i = 0; i < 20; i++) {
+        const candidate = path.join(dir, "node_modules", "appium-webdriveragent");
+        if (fs.existsSync(path.join(candidate, "WebDriverAgent.xcodeproj"))) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+//# sourceMappingURL=wdaProducts.js.map

package/dist/runtime/wdaProducts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wdaProducts.js","sourceRoot":"","sources":["../../src/runtime/wdaProducts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-detective",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
   "bin": {
     "doc-detective": "bin/doc-detective.js",