@ttsc/metro 0.30.4 → 0.31.0

package/lib/core/remapAstLocations.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Move every source location in an upstream transformer's AST from the ttsc
+ * transformed text back to the text the module's author wrote
+ * (samchon/ttsc#1392).
+ *
+ * Metro's Babel transformer contract returns an AST, never a map, and Metro
+ * builds the module's source map from that AST's `loc` positions against the
+ * file it read. The upstream transformer parsed the ttsc transformed text, so
+ * without this pass every position after the first change points at the
+ * reprinted lines: breakpoints, stack traces, and the error overlay would all
+ * be off. Each node's `loc` start and end are looked up in `map` with the usual
+ * greatest-lower-bound rule. A node whose start has no mapping into `file`,
+ * such as generated code, loses its `loc`, which Babel treats as a synthesized
+ * node, so it takes the mapping of the code around it.
+ *
+ * Babel locations have one-based lines and zero-based UTF-16 columns; source
+ * map segments have zero-based lines and columns. The map points from generated
+ * text to the authored file. Missing or reversed mapped ends clamp to the
+ * mapped start. Traversal tracks visited objects and mutates only AST
+ * locations. Absolute sources are compared by filesystem identity within this
+ * call, so links and actual directory case capabilities determine the owning
+ * source.
+ *
+ * @param ast The upstream transformer's AST, rewritten in place.
+ * @param map The adapter's map from the transformed text to `file`, with
+ *   absolute `sources`.
+ * @param file Absolute path of the module.
+ * @evidence contracts/common.md#principled-implementation
+ *   The adapter consumes its own source-map VLQ segments using
+ *   greatest-lower-bound lookup, then updates the upstream-owned AST through
+ *   Metro's returned-AST extension boundary. Iterative traversal tracks
+ *   visited objects to handle shared/cyclic AST references. Unmapped starts
+ *   lose loc and invalid ends clamp to the mapped start rather than
+ *   manufacturing authored positions.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Mapping decoding, position lookup and object traversal remain distinct
+ *   steps; the traversal owns AST mutation and the local lookup owns coordinate
+ *   conversion without adding a second Babel parser.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Mapping decoding is linear in encoded bytes. A visited Set walks each
+ *   AST object once; each endpoint uses binary search on its generated line's
+ *   segments. Temporary storage follows decoded segments and reachable AST
+ *   objects, and the iterative stack avoids call-depth dependence on the AST.
+ *   Source identity resolution is shared within this call; missing sources can
+ *   additionally require ancestor and directory-capability observations.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This call mutates one returned AST using that delivery's map; it owns no
+ *   shared cache and repeated calls would remap already moved coordinates.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The caller owns the AST. Local decoded lines and traversal state end with
+ *   the call; no handle or cross-delivery state is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No Babel methods or compiler internals are patched.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The shared filesystem-identity context compares absolute map sources with
+ *   the delivered file using physical spelling and actual directory case
+ *   capabilities. Source coordinates remain line/column values independent
+ *   of native newline spelling; OS names do not fold distinct filenames.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains map direction, in-place mutation, coordinate
+ *   indexing and generated/unmapped locations. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ */
+export declare function remapAstLocations(ast: unknown, map: {
+    mappings: string;
+    sources: readonly string[];
+}, file: string): void;

package/lib/core/remapAstLocations.js

@@ -0,0 +1,205 @@
+'use strict';
+
+var pathIdentity = require('ttsc/path-identity');
+
+/**
+ * Move every source location in an upstream transformer's AST from the ttsc
+ * transformed text back to the text the module's author wrote
+ * (samchon/ttsc#1392).
+ *
+ * Metro's Babel transformer contract returns an AST, never a map, and Metro
+ * builds the module's source map from that AST's `loc` positions against the
+ * file it read. The upstream transformer parsed the ttsc transformed text, so
+ * without this pass every position after the first change points at the
+ * reprinted lines: breakpoints, stack traces, and the error overlay would all
+ * be off. Each node's `loc` start and end are looked up in `map` with the usual
+ * greatest-lower-bound rule. A node whose start has no mapping into `file`,
+ * such as generated code, loses its `loc`, which Babel treats as a synthesized
+ * node, so it takes the mapping of the code around it.
+ *
+ * Babel locations have one-based lines and zero-based UTF-16 columns; source
+ * map segments have zero-based lines and columns. The map points from generated
+ * text to the authored file. Missing or reversed mapped ends clamp to the
+ * mapped start. Traversal tracks visited objects and mutates only AST
+ * locations. Absolute sources are compared by filesystem identity within this
+ * call, so links and actual directory case capabilities determine the owning
+ * source.
+ *
+ * @param ast The upstream transformer's AST, rewritten in place.
+ * @param map The adapter's map from the transformed text to `file`, with
+ *   absolute `sources`.
+ * @param file Absolute path of the module.
+ * @evidence contracts/common.md#principled-implementation
+ *   The adapter consumes its own source-map VLQ segments using
+ *   greatest-lower-bound lookup, then updates the upstream-owned AST through
+ *   Metro's returned-AST extension boundary. Iterative traversal tracks
+ *   visited objects to handle shared/cyclic AST references. Unmapped starts
+ *   lose loc and invalid ends clamp to the mapped start rather than
+ *   manufacturing authored positions.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Mapping decoding, position lookup and object traversal remain distinct
+ *   steps; the traversal owns AST mutation and the local lookup owns coordinate
+ *   conversion without adding a second Babel parser.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Mapping decoding is linear in encoded bytes. A visited Set walks each
+ *   AST object once; each endpoint uses binary search on its generated line's
+ *   segments. Temporary storage follows decoded segments and reachable AST
+ *   objects, and the iterative stack avoids call-depth dependence on the AST.
+ *   Source identity resolution is shared within this call; missing sources can
+ *   additionally require ancestor and directory-capability observations.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This call mutates one returned AST using that delivery's map; it owns no
+ *   shared cache and repeated calls would remap already moved coordinates.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The caller owns the AST. Local decoded lines and traversal state end with
+ *   the call; no handle or cross-delivery state is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No Babel methods or compiler internals are patched.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The shared filesystem-identity context compares absolute map sources with
+ *   the delivered file using physical spelling and actual directory case
+ *   capabilities. Source coordinates remain line/column values independent
+ *   of native newline spelling; OS names do not fold distinct filenames.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains map direction, in-place mutation, coordinate
+ *   indexing and generated/unmapped locations. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ */
+function remapAstLocations(ast, map, file) {
+    const identities = pathIdentity.createFilesystemPathIdentityContext({
+        throwOnRealpathError: false,
+    });
+    const fileKey = identities.resolve(file).key;
+    const own = map.sources.findIndex((source) => identities.resolve(source).key === fileKey);
+    if (own < 0) {
+        return;
+    }
+    const lines = decodeSegments(map.mappings);
+    const locate = (position) => {
+        if (typeof position !== "object" || position === null)
+            return undefined;
+        const { column, line } = position;
+        if (typeof line !== "number" || typeof column !== "number") {
+            return undefined;
+        }
+        const segments = lines[line - 1];
+        if (segments === undefined)
+            return undefined;
+        let low = 0;
+        let high = segments.length - 1;
+        let found;
+        while (low <= high) {
+            const middle = (low + high) >> 1;
+            const segment = segments[middle];
+            if (segment.generatedColumn <= column) {
+                found = segment;
+                low = middle + 1;
+            }
+            else {
+                high = middle - 1;
+            }
+        }
+        return found === undefined || found.source !== own
+            ? undefined
+            : { column: found.column, line: found.line + 1 };
+    };
+    const visited = new Set();
+    const pending = [ast];
+    while (pending.length !== 0) {
+        const value = pending.pop();
+        if (typeof value !== "object" || value === null || visited.has(value)) {
+            continue;
+        }
+        visited.add(value);
+        if (Array.isArray(value)) {
+            for (const entryToAppend of value)
+                pending.push(entryToAppend);
+            continue;
+        }
+        const node = value;
+        for (const [key, child] of Object.entries(node)) {
+            if (key !== "loc")
+                pending.push(child);
+        }
+        const loc = node.loc;
+        if (typeof loc !== "object" || loc === null)
+            continue;
+        const { end, start } = loc;
+        const mappedStart = locate(start);
+        if (mappedStart === undefined) {
+            node.loc = null;
+            continue;
+        }
+        const mappedEnd = locate(end);
+        node.loc = {
+            ...loc,
+            end: mappedEnd === undefined ||
+                mappedEnd.line < mappedStart.line ||
+                (mappedEnd.line === mappedStart.line &&
+                    mappedEnd.column < mappedStart.column)
+                ? mappedStart
+                : mappedEnd,
+            start: mappedStart,
+        };
+    }
+}
+/**
+ * Decode `mappings` into its segments per generated line, in column order.
+ * Segments of every source are kept, and a segment with no source position is
+ * kept with source `-1`, so a lookup that lands on either reports no position
+ * instead of reaching past it to an earlier mapping.
+ */
+function decodeSegments(mappings) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    const lines = [];
+    let source = 0;
+    let line = 0;
+    let column = 0;
+    for (const text of mappings.split(";")) {
+        const segments = [];
+        let generatedColumn = 0;
+        for (const encoded of text.split(",")) {
+            if (encoded === "")
+                continue;
+            const fields = [];
+            let value = 0;
+            let shift = 0;
+            for (const char of encoded) {
+                const digit = alphabet.indexOf(char);
+                if (digit < 0)
+                    return lines;
+                value += (digit & 31) << shift;
+                if ((digit & 32) !== 0) {
+                    shift += 5;
+                    continue;
+                }
+                fields.push((value & 1) !== 0 ? -(value >>> 1) : value >>> 1);
+                value = 0;
+                shift = 0;
+            }
+            generatedColumn += fields[0] ?? 0;
+            if (fields.length < 4) {
+                segments.push({ column: 0, generatedColumn, line: 0, source: -1 });
+                continue;
+            }
+            source += fields[1];
+            line += fields[2];
+            column += fields[3];
+            segments.push({ column, generatedColumn, line, source });
+        }
+        lines.push(segments);
+    }
+    return lines;
+}
+
+exports.remapAstLocations = remapAstLocations;
+//# sourceMappingURL=remapAstLocations.js.map

package/lib/core/remapAstLocations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remapAstLocations.js","sources":["../../src/core/remapAstLocations.ts"],"sourcesContent":[null],"names":["createFilesystemPathIdentityContext"],"mappings":"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"}

package/lib/core/remapAstLocations.mjs

@@ -0,0 +1,203 @@
+import { createFilesystemPathIdentityContext } from 'ttsc/path-identity';
+
+/**
+ * Move every source location in an upstream transformer's AST from the ttsc
+ * transformed text back to the text the module's author wrote
+ * (samchon/ttsc#1392).
+ *
+ * Metro's Babel transformer contract returns an AST, never a map, and Metro
+ * builds the module's source map from that AST's `loc` positions against the
+ * file it read. The upstream transformer parsed the ttsc transformed text, so
+ * without this pass every position after the first change points at the
+ * reprinted lines: breakpoints, stack traces, and the error overlay would all
+ * be off. Each node's `loc` start and end are looked up in `map` with the usual
+ * greatest-lower-bound rule. A node whose start has no mapping into `file`,
+ * such as generated code, loses its `loc`, which Babel treats as a synthesized
+ * node, so it takes the mapping of the code around it.
+ *
+ * Babel locations have one-based lines and zero-based UTF-16 columns; source
+ * map segments have zero-based lines and columns. The map points from generated
+ * text to the authored file. Missing or reversed mapped ends clamp to the
+ * mapped start. Traversal tracks visited objects and mutates only AST
+ * locations. Absolute sources are compared by filesystem identity within this
+ * call, so links and actual directory case capabilities determine the owning
+ * source.
+ *
+ * @param ast The upstream transformer's AST, rewritten in place.
+ * @param map The adapter's map from the transformed text to `file`, with
+ *   absolute `sources`.
+ * @param file Absolute path of the module.
+ * @evidence contracts/common.md#principled-implementation
+ *   The adapter consumes its own source-map VLQ segments using
+ *   greatest-lower-bound lookup, then updates the upstream-owned AST through
+ *   Metro's returned-AST extension boundary. Iterative traversal tracks
+ *   visited objects to handle shared/cyclic AST references. Unmapped starts
+ *   lose loc and invalid ends clamp to the mapped start rather than
+ *   manufacturing authored positions.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Mapping decoding, position lookup and object traversal remain distinct
+ *   steps; the traversal owns AST mutation and the local lookup owns coordinate
+ *   conversion without adding a second Babel parser.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Mapping decoding is linear in encoded bytes. A visited Set walks each
+ *   AST object once; each endpoint uses binary search on its generated line's
+ *   segments. Temporary storage follows decoded segments and reachable AST
+ *   objects, and the iterative stack avoids call-depth dependence on the AST.
+ *   Source identity resolution is shared within this call; missing sources can
+ *   additionally require ancestor and directory-capability observations.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This call mutates one returned AST using that delivery's map; it owns no
+ *   shared cache and repeated calls would remap already moved coordinates.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The caller owns the AST. Local decoded lines and traversal state end with
+ *   the call; no handle or cross-delivery state is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No Babel methods or compiler internals are patched.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The shared filesystem-identity context compares absolute map sources with
+ *   the delivered file using physical spelling and actual directory case
+ *   capabilities. Source coordinates remain line/column values independent
+ *   of native newline spelling; OS names do not fold distinct filenames.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains map direction, in-place mutation, coordinate
+ *   indexing and generated/unmapped locations. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ */
+function remapAstLocations(ast, map, file) {
+    const identities = createFilesystemPathIdentityContext({
+        throwOnRealpathError: false,
+    });
+    const fileKey = identities.resolve(file).key;
+    const own = map.sources.findIndex((source) => identities.resolve(source).key === fileKey);
+    if (own < 0) {
+        return;
+    }
+    const lines = decodeSegments(map.mappings);
+    const locate = (position) => {
+        if (typeof position !== "object" || position === null)
+            return undefined;
+        const { column, line } = position;
+        if (typeof line !== "number" || typeof column !== "number") {
+            return undefined;
+        }
+        const segments = lines[line - 1];
+        if (segments === undefined)
+            return undefined;
+        let low = 0;
+        let high = segments.length - 1;
+        let found;
+        while (low <= high) {
+            const middle = (low + high) >> 1;
+            const segment = segments[middle];
+            if (segment.generatedColumn <= column) {
+                found = segment;
+                low = middle + 1;
+            }
+            else {
+                high = middle - 1;
+            }
+        }
+        return found === undefined || found.source !== own
+            ? undefined
+            : { column: found.column, line: found.line + 1 };
+    };
+    const visited = new Set();
+    const pending = [ast];
+    while (pending.length !== 0) {
+        const value = pending.pop();
+        if (typeof value !== "object" || value === null || visited.has(value)) {
+            continue;
+        }
+        visited.add(value);
+        if (Array.isArray(value)) {
+            for (const entryToAppend of value)
+                pending.push(entryToAppend);
+            continue;
+        }
+        const node = value;
+        for (const [key, child] of Object.entries(node)) {
+            if (key !== "loc")
+                pending.push(child);
+        }
+        const loc = node.loc;
+        if (typeof loc !== "object" || loc === null)
+            continue;
+        const { end, start } = loc;
+        const mappedStart = locate(start);
+        if (mappedStart === undefined) {
+            node.loc = null;
+            continue;
+        }
+        const mappedEnd = locate(end);
+        node.loc = {
+            ...loc,
+            end: mappedEnd === undefined ||
+                mappedEnd.line < mappedStart.line ||
+                (mappedEnd.line === mappedStart.line &&
+                    mappedEnd.column < mappedStart.column)
+                ? mappedStart
+                : mappedEnd,
+            start: mappedStart,
+        };
+    }
+}
+/**
+ * Decode `mappings` into its segments per generated line, in column order.
+ * Segments of every source are kept, and a segment with no source position is
+ * kept with source `-1`, so a lookup that lands on either reports no position
+ * instead of reaching past it to an earlier mapping.
+ */
+function decodeSegments(mappings) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    const lines = [];
+    let source = 0;
+    let line = 0;
+    let column = 0;
+    for (const text of mappings.split(";")) {
+        const segments = [];
+        let generatedColumn = 0;
+        for (const encoded of text.split(",")) {
+            if (encoded === "")
+                continue;
+            const fields = [];
+            let value = 0;
+            let shift = 0;
+            for (const char of encoded) {
+                const digit = alphabet.indexOf(char);
+                if (digit < 0)
+                    return lines;
+                value += (digit & 31) << shift;
+                if ((digit & 32) !== 0) {
+                    shift += 5;
+                    continue;
+                }
+                fields.push((value & 1) !== 0 ? -(value >>> 1) : value >>> 1);
+                value = 0;
+                shift = 0;
+            }
+            generatedColumn += fields[0] ?? 0;
+            if (fields.length < 4) {
+                segments.push({ column: 0, generatedColumn, line: 0, source: -1 });
+                continue;
+            }
+            source += fields[1];
+            line += fields[2];
+            column += fields[3];
+            segments.push({ column, generatedColumn, line, source });
+        }
+        lines.push(segments);
+    }
+    return lines;
+}
+
+export { remapAstLocations };
+//# sourceMappingURL=remapAstLocations.mjs.map

package/lib/core/remapAstLocations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remapAstLocations.mjs","sources":["../../src/core/remapAstLocations.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/core/upstream.d.ts

@@ -1,23 +1,4 @@
-/**
- * The subset of the Metro Babel-transformer contract this adapter relies on.
- *
- * Metro loads the module named by `transformer.babelTransformerPath` and calls
- * its `transform` once per file, expecting a Babel AST back. `getCacheKey` is
- * an optional export Metro folds into its transform-cache key; Metro invokes it
- * with arguments (e.g. `{ projectRoot, enableBabelRCLookup }`), so it is typed
- * variadic.
- */
-export interface UpstreamTransformer {
-    transform(params: {
-        src: string;
-        filename: string;
-        options: Record<string, unknown>;
-        [key: string]: unknown;
-    }): Promise<{
-        ast: object;
-    }>;
-    getCacheKey?: (...args: unknown[]) => string;
-}
+import type { UpstreamTransformer } from "./UpstreamTransformer";
 /**
  * Upstream transformer module specifiers tried (in order) when no explicit
  * `upstreamTransformer` is configured: Expo first, then modern bare React
@@ -32,13 +13,102 @@ export declare const UPSTREAM_CANDIDATES: readonly ["@expo/metro-config/babel-tr
  * 1. An explicit `customPath` (the `upstreamTransformer` option);
  * 2. Each of {@link UPSTREAM_CANDIDATES} in turn.
  *
- * These are declared as optional peers and resolved at runtime against the
- * consumer project, so the adapter carries no Metro/Expo dependency itself.
- * Resolution is not memoised: Node's own module cache already makes the
- * repeated `require` a cheap lookup, and keeping no module-level state lets a
- * changed `upstreamTransformer` always take effect.
+ * `withTtsc` resolves an explicit specifier and the automatic candidates from
+ * the consuming project in the Metro config process, and publishes the absolute
+ * path it found (see {@link locateProjectUpstreamTransformer}). This worker-side
+ * lookup, rooted in the adapter's own location, is what remains for a specifier
+ * the project could not resolve, so the adapter carries no Metro/Expo
+ * dependency itself. Resolution is not memoised: Node's own module cache
+ * already makes the repeated `require` a cheap lookup, and keeping no
+ * module-level state lets a changed `upstreamTransformer` always take effect.
+ *
+ * `load` is the explicit module-loading boundary. Its default uses Node's real
+ * `require`; an injected loader must preserve absence versus failure
+ * semantics.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node createRequire loads the configured module or documented
+ *   Expo/React-Native candidates. Resolution is separated from execution: only
+ *   known entry-absence codes permit another automatic candidate;
+ *   installed-module initialization failures preserve their cause.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Explicit selection and ordered detection share the loading boundary.
+ *   tryRequire owns absence classification, leaving this function to choose
+ *   the transformer and attach contextual errors.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The loader argument is an explicit dependency-injection boundary, not a
+ *   test-only runtime branch or a patched require.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node resolution accepts project-resolved absolute paths on Windows and
+ *   POSIX. createRequire is rooted at this module via import.meta.url; no
+ *   path is turned into a shell command. Runtime errors propagate through the
+ *   same policy on every OS.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains candidate order, project versus worker
+ *   resolution and absence versus initialization failures. Checked against
+ *   the documentation skill: separate paragraphs state the contract and why
+ *   its nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Keeps no state between calls; loaded modules belong to Node's module cache.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   At most three candidate probes per call, each a require.resolve followed by one require.
  *
- * `load` is injectable purely so the resolution order and the not-found path
- * can be tested deterministically; production always uses the real `require`.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Deliberately unmemoised: Node's module cache makes a repeated require cheap and a changed option must take effect.
  */
 export declare function resolveUpstreamTransformer(customPath?: string, load?: (modulePath: string) => UpstreamTransformer | undefined): UpstreamTransformer;
+/**
+ * Locate the automatic upstream transformer the consuming project installed,
+ * without executing it.
+ *
+ * The candidates belong to the app, not to this adapter: under pnpm or a linked
+ * workspace the adapter sits outside the app's `node_modules` ancestry, so a
+ * lookup rooted in the adapter cannot see a transformer only the app installed.
+ * `resolve` is rooted in the project; each candidate is tried in
+ * {@link UPSTREAM_CANDIDATES} order and an absent one is skipped, exactly as the
+ * worker's probe skips it. Only resolution runs here, so a broken installation
+ * still fails where the worker loads it, with its own error.
+ *
+ * @param resolve Resolves a module specifier from the project.
+ * @returns The absolute path of the first installed candidate, or `undefined`.
+ * @evidence contracts/common.md#principled-implementation
+ *   The supplied project resolver uses Node module resolution without
+ *   executing candidate code. Only recognized entry-absence errors continue
+ *   probing; other resolver failures propagate.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Project discovery resolves only the shared candidate list; execution is
+ *   deferred to the worker loader that owns initialization failures.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The documented optional-peer order is a product default, not a
+ *   fixture-specific answer. No module methods are replaced.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The injected resolver owns project filesystem resolution on the host OS.
+ *   This operation compares module specifiers and returns its absolute result
+ *   without inventing separators or quoting a command.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains project ownership, ordered probing,
+ *   nonexecution and the absent result. Checked against the documentation
+ *   skill: separate paragraphs state the contract and why its nonobvious
+ *   boundary matters; field comments retain their own useful facts.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Resolves paths without executing a candidate and retains nothing.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   At most three resolutions, stopping at the first one that succeeds.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Runs once per withTtsc call, in the config process only.
+ */
+export declare function locateProjectUpstreamTransformer(resolve: (specifier: string) => string): string | undefined;