@microsoft/rayfin-docs 1.35.0 → 1.35.1

package/dist/discovery.d.ts

@@ -120,12 +120,23 @@ export interface InstalledPackageVersionResolution {
 /** Optional policy applied to installed manifest versions. */
 export interface InstalledPackageVersionResolutionOptions {
     isVersionAllowed?: (version: string) => boolean;
+    /**
+     * Also resolve packages that are installed but reachable only as an *indirect*
+     * dependency — one a strict/isolated install links inside its dependent's
+     * scope rather than anywhere `from` can see (see
+     * {@link resolvePackageJsonTransitively}).
+     *
+     * Off by default
+     */
+    includeIndirect?: boolean;
 }
 /**
  * Resolve actual installed versions for a bounded candidate set.
  *
  * Candidates are deduplicated and sorted. Missing, malformed, or mismatched
  * manifests are omitted so telemetry collection remains best-effort.
+ *
+ * Resolves only what `from` can reach unless `includeIndirect` is set.
  */
 export declare function resolveInstalledPackageVersions(packageNames: readonly string[], from: string, options?: InstalledPackageVersionResolutionOptions): InstalledPackageVersionResolution;
 //# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -17,7 +17,7 @@
  * candidate list, workspace package roots, or all-installed node_modules
  * walking via `scanInstalledPackages: true`.
  */
-import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { readFileSync, existsSync, realpathSync, statSync, readdirSync, } from 'fs';
 import { createRequire } from 'module';
 import { dirname, isAbsolute, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -35,7 +35,6 @@ export function discoverRayfinDocsPackages(options) {
     const fromDir = options.from.startsWith('file:') || options.from.includes('://')
         ? dirname(fileURLToPath(options.from))
         : resolveExistingDir(options.from);
-    const requireFromBase = createRequire(join(fromDir, 'noop.js'));
     const nodeModulesChain = buildNodeModulesChain(fromDir);
     const discovered = [];
     const notInstalled = [];
@@ -53,7 +52,7 @@ export function discoverRayfinDocsPackages(options) {
         packagesToRead = resolvePackageRootJsons(options.packageRoots);
     }
     else if (options.candidates !== undefined) {
-        packagesToRead = resolveCandidatePackageJsons(options.candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust);
+        packagesToRead = resolveCandidatePackageJsons(options.candidates, fromDir, notInstalled, untrustedSkipped, trust);
     }
     else if (options.scanInstalledPackages) {
         packagesToRead = discoverInstalledPackageJsons(nodeModulesChain);
@@ -130,14 +129,19 @@ function resolvePackageRootJsons(packageRoots) {
         pkgJsonPath: join(resolveExistingDir(packageRoot), 'package.json'),
     }));
 }
-function resolveCandidatePackageJsons(candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust) {
+/**
+ * Resolve explicitly named candidates. Direct-only by construction: docs
+ * discovery reports packages the caller named and trusts, so it must not reach
+ * through the dependency graph into packages nobody asked about.
+ */
+function resolveCandidatePackageJsons(candidates, fromDir, notInstalled, untrustedSkipped, trust) {
     const resolved = [];
     for (const candidate of candidates) {
         if (!trust(candidate)) {
             untrustedSkipped.push(candidate);
             continue;
         }
-        const pkgJsonPath = resolvePackageJson(requireFromBase, candidate, nodeModulesChain);
+        const pkgJsonPath = resolvePackageJsonFrom(fromDir, candidate);
         if (!pkgJsonPath) {
             notInstalled.push(candidate);
             continue;
@@ -300,8 +304,8 @@ export function docKindToModule(kind) {
 }
 /**
  * Compute the chain of `node_modules` ancestor directories from
- * `fromDir` upward, capped at 16 levels. Used by the tier-3 fallback
- * in {@link resolvePackageJson} to avoid re-walking the same ancestors
+ * `fromDir` upward, capped at 16 levels. Used by the ancestor tier in
+ * {@link resolvePackageJsonFrom} to avoid re-walking the same ancestors
  * once per candidate (`9 candidates × 16 walks = 144 stat calls` in
  * the original implementation; this caches the chain to 16 stats).
  */
@@ -317,18 +321,37 @@ function buildNodeModulesChain(fromDir) {
     }
     return chain;
 }
+/**
+ * Dependency fields that describe packages actually present in an install.
+ *
+ * `devDependencies` is deliberately excluded: it is not installed for a
+ * transitive dependency, so following it would walk edges that do not exist in
+ * the consuming project's tree.
+ */
+const INSTALLED_DEPENDENCY_FIELDS = [
+    'dependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
+/**
+ * Bounds on the dependency-graph search. The walk only runs for a package the
+ * direct tiers already failed to find, so these cap a rare path rather than the
+ * common one.
+ */
+const MAX_TRANSITIVE_DEPTH = 4;
+const MAX_TRANSITIVE_VISITS = 256;
 /**
  * Resolve actual installed versions for a bounded candidate set.
  *
  * Candidates are deduplicated and sorted. Missing, malformed, or mismatched
  * manifests are omitted so telemetry collection remains best-effort.
+ *
+ * Resolves only what `from` can reach unless `includeIndirect` is set.
  */
 export function resolveInstalledPackageVersions(packageNames, from, options = {}) {
     const fromDir = from.startsWith('file:') || from.includes('://')
         ? dirname(fileURLToPath(from))
         : resolveExistingDir(from);
-    const requireFromBase = createRequire(join(fromDir, 'noop.js'));
-    const nodeModulesChain = buildNodeModulesChain(fromDir);
     const packages = [];
     const unresolvedPackageNames = [];
     for (const packageName of [...new Set(packageNames)].sort()) {
@@ -336,7 +359,10 @@ export function resolveInstalledPackageVersions(packageNames, from, options = {}
             unresolvedPackageNames.push(packageName);
             continue;
         }
-        const packageJsonPath = resolvePackageJson(requireFromBase, packageName, nodeModulesChain);
+        const packageJsonPath = resolvePackageJsonFrom(fromDir, packageName) ??
+            (options.includeIndirect
+                ? resolvePackageJsonTransitively(fromDir, packageName)
+                : undefined);
         if (!packageJsonPath) {
             unresolvedPackageNames.push(packageName);
             continue;
@@ -364,15 +390,21 @@ function isValidPackageName(packageName) {
         /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(packageName));
 }
 /**
- * Find a package's `package.json` even when exports hide it, the package is
- * ESM-only, or the install is hoisted above the resolution root.
+ * Find a package's `package.json` **as resolved from `fromDir`**, even when
+ * exports hide it, the package is ESM-only, or the install is hoisted above the
+ * resolution root.
  *
  * Packages with restricted exports often omit `./package.json`, causing direct
  * subpath resolution to fail. ESM-only packages may also hide their main entry
- * from CommonJS resolution, so the final tier searches the cached ancestor
+ * from CommonJS resolution, so the final tier searches the ancestor
  * `node_modules` chain used by npm, pnpm, and Yarn-style installs.
+ *
+ * Scoped to one directory so the dependency-graph walk can reuse it verbatim:
+ * "resolve X from package Y's location" is the same question as "resolve X from
+ * the project root", just asked somewhere else in the tree.
  */
-function resolvePackageJson(req, packageName, nodeModulesChain) {
+function resolvePackageJsonFrom(fromDir, packageName) {
+    const req = createRequire(join(fromDir, 'noop.js'));
     // Tier 1: direct manifest resolution when exports allow the subpath.
     try {
         return req.resolve(`${packageName}/package.json`);
@@ -407,14 +439,126 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
     catch {
         // ESM-only package or similar: fall through to node_modules lookup.
     }
-    // Tier 3: search cached ancestor node_modules roots, independent of exports.
-    for (const dir of nodeModulesChain) {
+    // Tier 3: search ancestor node_modules roots, independent of exports.
+    for (const dir of buildNodeModulesChain(fromDir)) {
         const candidate = join(dir, 'node_modules', packageName, 'package.json');
         if (existsSync(candidate))
             return candidate;
     }
     return undefined;
 }
+/**
+ * Find a package that is installed but *not reachable from `fromDir`* by
+ * searching outward through the dependency graph.
+ *
+ * A strict/isolated install (pnpm's default, and Yarn's `nmMode: hardlinks`)
+ * links a purely transitive package only inside the dependency scope of the
+ * package that asked for it — never the consumer's own `node_modules` chain.
+ * Resolution from `fromDir` therefore fails for it, correctly: nothing at the
+ * project root may import it. It is still the version that ships, because the
+ * bundler reaches it through the dependent that does.
+ *
+ * So the search moves to where the answer is: walk the installed dependency
+ * graph breadth-first and re-ask {@link resolvePackageJsonFrom} at each package's
+ * own real location. Node's resolver supplies all the layout knowledge —
+ * following the symlink out of pnpm's virtual store and then finding the target
+ * as its sibling — instead of this code hard-coding store paths, and it costs
+ * nothing on the common path because it only runs after a direct miss.
+ *
+ * Known limitation: Yarn Plug'n'Play has no `node_modules` tree at all, so
+ * neither this nor the direct tiers can see it without the `.pnp.cjs` API.
+ */
+function resolvePackageJsonTransitively(fromDir, packageName) {
+    const visited = new Set();
+    let frontier = readInstalledDependencyNames(join(fromDir, 'package.json'));
+    // Not seeded from the manifest alone: a project whose own manifest is
+    // unreadable can still have an installed tree worth searching.
+    if (frontier.length === 0) {
+        frontier = readAncestorNodeModulesEntries(fromDir);
+    }
+    for (let depth = 0; depth < MAX_TRANSITIVE_DEPTH; depth += 1) {
+        const next = [];
+        for (const dependentName of frontier) {
+            if (visited.size >= MAX_TRANSITIVE_VISITS)
+                return undefined;
+            if (dependentName === packageName)
+                continue;
+            if (visited.has(dependentName))
+                continue;
+            visited.add(dependentName);
+            if (!isValidPackageName(dependentName))
+                continue;
+            const dependentManifest = resolvePackageJsonFrom(fromDir, dependentName);
+            if (!dependentManifest)
+                continue;
+            // The real location matters: resolving through the virtual-store symlink
+            // is what puts the target in scope as a sibling.
+            let dependentDir;
+            try {
+                dependentDir = realpathSync(dirname(dependentManifest));
+            }
+            catch {
+                continue;
+            }
+            const found = resolvePackageJsonFrom(dependentDir, packageName);
+            if (found)
+                return found;
+            next.push(...readInstalledDependencyNames(join(dependentDir, 'package.json')));
+        }
+        if (next.length === 0)
+            return undefined;
+        frontier = next;
+    }
+    return undefined;
+}
+/** Names declared in the dependency fields that describe an installed tree. */
+function readInstalledDependencyNames(manifestPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const names = [];
+        for (const field of INSTALLED_DEPENDENCY_FIELDS) {
+            const value = parsed[field];
+            if (value && typeof value === 'object') {
+                names.push(...Object.keys(value));
+            }
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Top-level package names installed in the nearest ancestor `node_modules`,
+ * used to seed the graph walk when no readable manifest declares anything.
+ */
+function readAncestorNodeModulesEntries(fromDir) {
+    for (const dir of buildNodeModulesChain(fromDir)) {
+        const nodeModules = join(dir, 'node_modules');
+        if (!existsSync(nodeModules))
+            continue;
+        try {
+            const names = [];
+            for (const entry of readdirSync(nodeModules, { withFileTypes: true })) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                if (entry.name.startsWith('@')) {
+                    const scopeDir = join(nodeModules, entry.name);
+                    for (const scoped of readdirSync(scopeDir)) {
+                        names.push(`${entry.name}/${scoped}`);
+                    }
+                    continue;
+                }
+                names.push(entry.name);
+            }
+            return names;
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
 /** Internal: ensure `from` exists for `createRequire` when given a dir. */
 function resolveExistingDir(from) {
     const absolute = resolve(from);

package/dist/site-cjs/discovery.js

@@ -44,7 +44,6 @@ function discoverRayfinDocsPackages(options) {
     const fromDir = options.from.startsWith('file:') || options.from.includes('://')
         ? (0, path_1.dirname)((0, url_1.fileURLToPath)(options.from))
         : resolveExistingDir(options.from);
-    const requireFromBase = (0, module_1.createRequire)((0, path_1.join)(fromDir, 'noop.js'));
     const nodeModulesChain = buildNodeModulesChain(fromDir);
     const discovered = [];
     const notInstalled = [];
@@ -62,7 +61,7 @@ function discoverRayfinDocsPackages(options) {
         packagesToRead = resolvePackageRootJsons(options.packageRoots);
     }
     else if (options.candidates !== undefined) {
-        packagesToRead = resolveCandidatePackageJsons(options.candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust);
+        packagesToRead = resolveCandidatePackageJsons(options.candidates, fromDir, notInstalled, untrustedSkipped, trust);
     }
     else if (options.scanInstalledPackages) {
         packagesToRead = discoverInstalledPackageJsons(nodeModulesChain);
@@ -139,14 +138,19 @@ function resolvePackageRootJsons(packageRoots) {
         pkgJsonPath: (0, path_1.join)(resolveExistingDir(packageRoot), 'package.json'),
     }));
 }
-function resolveCandidatePackageJsons(candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust) {
+/**
+ * Resolve explicitly named candidates. Direct-only by construction: docs
+ * discovery reports packages the caller named and trusts, so it must not reach
+ * through the dependency graph into packages nobody asked about.
+ */
+function resolveCandidatePackageJsons(candidates, fromDir, notInstalled, untrustedSkipped, trust) {
     const resolved = [];
     for (const candidate of candidates) {
         if (!trust(candidate)) {
             untrustedSkipped.push(candidate);
             continue;
         }
-        const pkgJsonPath = resolvePackageJson(requireFromBase, candidate, nodeModulesChain);
+        const pkgJsonPath = resolvePackageJsonFrom(fromDir, candidate);
         if (!pkgJsonPath) {
             notInstalled.push(candidate);
             continue;
@@ -309,8 +313,8 @@ function docKindToModule(kind) {
 }
 /**
  * Compute the chain of `node_modules` ancestor directories from
- * `fromDir` upward, capped at 16 levels. Used by the tier-3 fallback
- * in {@link resolvePackageJson} to avoid re-walking the same ancestors
+ * `fromDir` upward, capped at 16 levels. Used by the ancestor tier in
+ * {@link resolvePackageJsonFrom} to avoid re-walking the same ancestors
  * once per candidate (`9 candidates × 16 walks = 144 stat calls` in
  * the original implementation; this caches the chain to 16 stats).
  */
@@ -326,18 +330,37 @@ function buildNodeModulesChain(fromDir) {
     }
     return chain;
 }
+/**
+ * Dependency fields that describe packages actually present in an install.
+ *
+ * `devDependencies` is deliberately excluded: it is not installed for a
+ * transitive dependency, so following it would walk edges that do not exist in
+ * the consuming project's tree.
+ */
+const INSTALLED_DEPENDENCY_FIELDS = [
+    'dependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
+/**
+ * Bounds on the dependency-graph search. The walk only runs for a package the
+ * direct tiers already failed to find, so these cap a rare path rather than the
+ * common one.
+ */
+const MAX_TRANSITIVE_DEPTH = 4;
+const MAX_TRANSITIVE_VISITS = 256;
 /**
  * Resolve actual installed versions for a bounded candidate set.
  *
  * Candidates are deduplicated and sorted. Missing, malformed, or mismatched
  * manifests are omitted so telemetry collection remains best-effort.
+ *
+ * Resolves only what `from` can reach unless `includeIndirect` is set.
  */
 function resolveInstalledPackageVersions(packageNames, from, options = {}) {
     const fromDir = from.startsWith('file:') || from.includes('://')
         ? (0, path_1.dirname)((0, url_1.fileURLToPath)(from))
         : resolveExistingDir(from);
-    const requireFromBase = (0, module_1.createRequire)((0, path_1.join)(fromDir, 'noop.js'));
-    const nodeModulesChain = buildNodeModulesChain(fromDir);
     const packages = [];
     const unresolvedPackageNames = [];
     for (const packageName of [...new Set(packageNames)].sort()) {
@@ -345,7 +368,10 @@ function resolveInstalledPackageVersions(packageNames, from, options = {}) {
             unresolvedPackageNames.push(packageName);
             continue;
         }
-        const packageJsonPath = resolvePackageJson(requireFromBase, packageName, nodeModulesChain);
+        const packageJsonPath = resolvePackageJsonFrom(fromDir, packageName) ??
+            (options.includeIndirect
+                ? resolvePackageJsonTransitively(fromDir, packageName)
+                : undefined);
         if (!packageJsonPath) {
             unresolvedPackageNames.push(packageName);
             continue;
@@ -373,15 +399,21 @@ function isValidPackageName(packageName) {
         /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(packageName));
 }
 /**
- * Find a package's `package.json` even when exports hide it, the package is
- * ESM-only, or the install is hoisted above the resolution root.
+ * Find a package's `package.json` **as resolved from `fromDir`**, even when
+ * exports hide it, the package is ESM-only, or the install is hoisted above the
+ * resolution root.
  *
  * Packages with restricted exports often omit `./package.json`, causing direct
  * subpath resolution to fail. ESM-only packages may also hide their main entry
- * from CommonJS resolution, so the final tier searches the cached ancestor
+ * from CommonJS resolution, so the final tier searches the ancestor
  * `node_modules` chain used by npm, pnpm, and Yarn-style installs.
+ *
+ * Scoped to one directory so the dependency-graph walk can reuse it verbatim:
+ * "resolve X from package Y's location" is the same question as "resolve X from
+ * the project root", just asked somewhere else in the tree.
  */
-function resolvePackageJson(req, packageName, nodeModulesChain) {
+function resolvePackageJsonFrom(fromDir, packageName) {
+    const req = (0, module_1.createRequire)((0, path_1.join)(fromDir, 'noop.js'));
     // Tier 1: direct manifest resolution when exports allow the subpath.
     try {
         return req.resolve(`${packageName}/package.json`);
@@ -416,14 +448,126 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
     catch {
         // ESM-only package or similar: fall through to node_modules lookup.
     }
-    // Tier 3: search cached ancestor node_modules roots, independent of exports.
-    for (const dir of nodeModulesChain) {
+    // Tier 3: search ancestor node_modules roots, independent of exports.
+    for (const dir of buildNodeModulesChain(fromDir)) {
         const candidate = (0, path_1.join)(dir, 'node_modules', packageName, 'package.json');
         if ((0, fs_1.existsSync)(candidate))
             return candidate;
     }
     return undefined;
 }
+/**
+ * Find a package that is installed but *not reachable from `fromDir`* by
+ * searching outward through the dependency graph.
+ *
+ * A strict/isolated install (pnpm's default, and Yarn's `nmMode: hardlinks`)
+ * links a purely transitive package only inside the dependency scope of the
+ * package that asked for it — never the consumer's own `node_modules` chain.
+ * Resolution from `fromDir` therefore fails for it, correctly: nothing at the
+ * project root may import it. It is still the version that ships, because the
+ * bundler reaches it through the dependent that does.
+ *
+ * So the search moves to where the answer is: walk the installed dependency
+ * graph breadth-first and re-ask {@link resolvePackageJsonFrom} at each package's
+ * own real location. Node's resolver supplies all the layout knowledge —
+ * following the symlink out of pnpm's virtual store and then finding the target
+ * as its sibling — instead of this code hard-coding store paths, and it costs
+ * nothing on the common path because it only runs after a direct miss.
+ *
+ * Known limitation: Yarn Plug'n'Play has no `node_modules` tree at all, so
+ * neither this nor the direct tiers can see it without the `.pnp.cjs` API.
+ */
+function resolvePackageJsonTransitively(fromDir, packageName) {
+    const visited = new Set();
+    let frontier = readInstalledDependencyNames((0, path_1.join)(fromDir, 'package.json'));
+    // Not seeded from the manifest alone: a project whose own manifest is
+    // unreadable can still have an installed tree worth searching.
+    if (frontier.length === 0) {
+        frontier = readAncestorNodeModulesEntries(fromDir);
+    }
+    for (let depth = 0; depth < MAX_TRANSITIVE_DEPTH; depth += 1) {
+        const next = [];
+        for (const dependentName of frontier) {
+            if (visited.size >= MAX_TRANSITIVE_VISITS)
+                return undefined;
+            if (dependentName === packageName)
+                continue;
+            if (visited.has(dependentName))
+                continue;
+            visited.add(dependentName);
+            if (!isValidPackageName(dependentName))
+                continue;
+            const dependentManifest = resolvePackageJsonFrom(fromDir, dependentName);
+            if (!dependentManifest)
+                continue;
+            // The real location matters: resolving through the virtual-store symlink
+            // is what puts the target in scope as a sibling.
+            let dependentDir;
+            try {
+                dependentDir = (0, fs_1.realpathSync)((0, path_1.dirname)(dependentManifest));
+            }
+            catch {
+                continue;
+            }
+            const found = resolvePackageJsonFrom(dependentDir, packageName);
+            if (found)
+                return found;
+            next.push(...readInstalledDependencyNames((0, path_1.join)(dependentDir, 'package.json')));
+        }
+        if (next.length === 0)
+            return undefined;
+        frontier = next;
+    }
+    return undefined;
+}
+/** Names declared in the dependency fields that describe an installed tree. */
+function readInstalledDependencyNames(manifestPath) {
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(manifestPath, 'utf8'));
+        const names = [];
+        for (const field of INSTALLED_DEPENDENCY_FIELDS) {
+            const value = parsed[field];
+            if (value && typeof value === 'object') {
+                names.push(...Object.keys(value));
+            }
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Top-level package names installed in the nearest ancestor `node_modules`,
+ * used to seed the graph walk when no readable manifest declares anything.
+ */
+function readAncestorNodeModulesEntries(fromDir) {
+    for (const dir of buildNodeModulesChain(fromDir)) {
+        const nodeModules = (0, path_1.join)(dir, 'node_modules');
+        if (!(0, fs_1.existsSync)(nodeModules))
+            continue;
+        try {
+            const names = [];
+            for (const entry of (0, fs_1.readdirSync)(nodeModules, { withFileTypes: true })) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                if (entry.name.startsWith('@')) {
+                    const scopeDir = (0, path_1.join)(nodeModules, entry.name);
+                    for (const scoped of (0, fs_1.readdirSync)(scopeDir)) {
+                        names.push(`${entry.name}/${scoped}`);
+                    }
+                    continue;
+                }
+                names.push(entry.name);
+            }
+            return names;
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
 /** Internal: ensure `from` exists for `createRequire` when given a dir. */
 function resolveExistingDir(from) {
     const absolute = (0, path_1.resolve)(from);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-docs",
-  "version": "1.35.0",
+  "version": "1.35.1",
   "description": "Rayfin docs indexing and search library — used by the MCP server, CLI, and other doc-facing surfaces",
   "type": "module",
   "main": "dist/index.js",