@microsoft/rayfin-docs 1.35.0-alpha.1315 → 1.35.0-alpha.1331

package/dist/discovery.d.ts

@@ -107,4 +107,25 @@ export declare function validateRayfinDocsManifest(pkgJson: unknown, packageName
  * docs" for end users.
  */
 export declare function docKindToModule(kind: DocKind): 'guide' | 'host' | 'ts-sdk';
+/** One package and its actual installed manifest version. */
+export interface InstalledPackageVersion {
+    name: string;
+    version: string;
+}
+/** Installed package versions plus candidates that could not be resolved. */
+export interface InstalledPackageVersionResolution {
+    packages: InstalledPackageVersion[];
+    unresolvedPackageNames: string[];
+}
+/** Optional policy applied to installed manifest versions. */
+export interface InstalledPackageVersionResolutionOptions {
+    isVersionAllowed?: (version: string) => 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.
+ */
+export declare function resolveInstalledPackageVersions(packageNames: readonly string[], from: string, options?: InstalledPackageVersionResolutionOptions): InstalledPackageVersionResolution;
 //# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -318,38 +318,71 @@ function buildNodeModulesChain(fromDir) {
     return chain;
 }
 /**
- * Find a package's `package.json` path even when the package's
- * `exports` field doesn't expose it as a subpath OR when the package
- * is ESM-only (`exports."."` is `{ "import": ... }` without a CJS
- * `default`/`require` branch).
+ * Resolve actual installed versions for a bounded candidate set.
  *
- * SDK packages with restricted `exports` typically don't list
- * `./package.json` and so `require.resolve('<pkg>/package.json')`
- * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. ESM-only packages additionally
- * fail `require.resolve('<pkg>')` (CJS resolution can't see the
- * `import:` branch). We finally fall back to walking the node_modules
- * tree from the resolution base - this matches what every npm/pnpm
- * tool does internally.
+ * Candidates are deduplicated and sorted. Missing, malformed, or mismatched
+ * manifests are omitted so telemetry collection remains best-effort.
+ */
+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()) {
+        if (!isValidPackageName(packageName)) {
+            unresolvedPackageNames.push(packageName);
+            continue;
+        }
+        const packageJsonPath = resolvePackageJson(requireFromBase, packageName, nodeModulesChain);
+        if (!packageJsonPath) {
+            unresolvedPackageNames.push(packageName);
+            continue;
+        }
+        try {
+            const manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+            if (manifest.name === packageName &&
+                typeof manifest.version === 'string' &&
+                manifest.version.length > 0 &&
+                (options.isVersionAllowed?.(manifest.version) ?? true)) {
+                packages.push({ name: packageName, version: manifest.version });
+            }
+            else {
+                unresolvedPackageNames.push(packageName);
+            }
+        }
+        catch {
+            unresolvedPackageNames.push(packageName);
+        }
+    }
+    return { packages, unresolvedPackageNames };
+}
+function isValidPackageName(packageName) {
+    return (packageName.length <= 214 &&
+        /^(?:@[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.
  *
- * Returns the absolute path to `package.json`, or `undefined` when the
- * package isn't installed at all.
+ * 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
+ * `node_modules` chain used by npm, pnpm, and Yarn-style installs.
  */
 function resolvePackageJson(req, packageName, nodeModulesChain) {
-    // Fast path: works when the package omits `exports` or explicitly
-    // includes `./package.json` in it.
+    // Tier 1: direct manifest resolution when exports allow the subpath.
     try {
         return req.resolve(`${packageName}/package.json`);
     }
-    catch (err) {
-        const code = err?.code;
-        if (code === 'MODULE_NOT_FOUND') {
-            // Package isn't installed.
-            return undefined;
-        }
-        // ERR_PACKAGE_PATH_NOT_EXPORTED or similar: keep going.
+    catch {
+        // MODULE_NOT_FOUND means only this subpath failed to resolve, not that the
+        // package is absent. Restricted exports and alternate layouts require the
+        // remaining tiers.
     }
-    // Second fall-back: resolve the main entry, then walk up directories
-    // searching for a package.json whose name matches.
+    // Tier 2: resolve the package entry, then walk upward to its named manifest.
     try {
         const entry = req.resolve(packageName);
         let dir = dirname(entry);
@@ -358,12 +391,11 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
             if (existsSync(candidate)) {
                 try {
                     const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
-                    if (parsed.name === packageName) {
+                    if (parsed.name === packageName)
                         return candidate;
-                    }
                 }
                 catch {
-                    // keep walking
+                    // Keep walking toward the package root.
                 }
             }
             const parent = dirname(dir);
@@ -373,17 +405,13 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
         }
     }
     catch {
-        // ESM-only package or similar: fall through to the node_modules walk.
+        // ESM-only package or similar: fall through to node_modules lookup.
     }
-    // Third fall-back: walk the precomputed `node_modules` ancestor
-    // chain looking for `<ancestor>/node_modules/<packageName>/package.json`.
-    // This is what npm/pnpm/yarn tooling does internally and works
-    // regardless of how the package's `exports` are configured.
+    // Tier 3: search cached ancestor node_modules roots, independent of exports.
     for (const dir of nodeModulesChain) {
         const candidate = join(dir, 'node_modules', packageName, 'package.json');
-        if (existsSync(candidate)) {
+        if (existsSync(candidate))
             return candidate;
-        }
     }
     return undefined;
 }

package/dist/site-cjs/discovery.js

@@ -5,6 +5,7 @@ exports.hasExplicitDiscoverySource = hasExplicitDiscoverySource;
 exports.discoverRayfinDocsPackages = discoverRayfinDocsPackages;
 exports.validateRayfinDocsManifest = validateRayfinDocsManifest;
 exports.docKindToModule = docKindToModule;
+exports.resolveInstalledPackageVersions = resolveInstalledPackageVersions;
 /**
  * Per-package docs discovery - Phase 2 of `docs-package-architecture`.
  *
@@ -326,38 +327,71 @@ function buildNodeModulesChain(fromDir) {
     return chain;
 }
 /**
- * Find a package's `package.json` path even when the package's
- * `exports` field doesn't expose it as a subpath OR when the package
- * is ESM-only (`exports."."` is `{ "import": ... }` without a CJS
- * `default`/`require` branch).
+ * Resolve actual installed versions for a bounded candidate set.
  *
- * SDK packages with restricted `exports` typically don't list
- * `./package.json` and so `require.resolve('<pkg>/package.json')`
- * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. ESM-only packages additionally
- * fail `require.resolve('<pkg>')` (CJS resolution can't see the
- * `import:` branch). We finally fall back to walking the node_modules
- * tree from the resolution base - this matches what every npm/pnpm
- * tool does internally.
+ * Candidates are deduplicated and sorted. Missing, malformed, or mismatched
+ * manifests are omitted so telemetry collection remains best-effort.
+ */
+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()) {
+        if (!isValidPackageName(packageName)) {
+            unresolvedPackageNames.push(packageName);
+            continue;
+        }
+        const packageJsonPath = resolvePackageJson(requireFromBase, packageName, nodeModulesChain);
+        if (!packageJsonPath) {
+            unresolvedPackageNames.push(packageName);
+            continue;
+        }
+        try {
+            const manifest = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, 'utf8'));
+            if (manifest.name === packageName &&
+                typeof manifest.version === 'string' &&
+                manifest.version.length > 0 &&
+                (options.isVersionAllowed?.(manifest.version) ?? true)) {
+                packages.push({ name: packageName, version: manifest.version });
+            }
+            else {
+                unresolvedPackageNames.push(packageName);
+            }
+        }
+        catch {
+            unresolvedPackageNames.push(packageName);
+        }
+    }
+    return { packages, unresolvedPackageNames };
+}
+function isValidPackageName(packageName) {
+    return (packageName.length <= 214 &&
+        /^(?:@[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.
  *
- * Returns the absolute path to `package.json`, or `undefined` when the
- * package isn't installed at all.
+ * 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
+ * `node_modules` chain used by npm, pnpm, and Yarn-style installs.
  */
 function resolvePackageJson(req, packageName, nodeModulesChain) {
-    // Fast path: works when the package omits `exports` or explicitly
-    // includes `./package.json` in it.
+    // Tier 1: direct manifest resolution when exports allow the subpath.
     try {
         return req.resolve(`${packageName}/package.json`);
     }
-    catch (err) {
-        const code = err?.code;
-        if (code === 'MODULE_NOT_FOUND') {
-            // Package isn't installed.
-            return undefined;
-        }
-        // ERR_PACKAGE_PATH_NOT_EXPORTED or similar: keep going.
+    catch {
+        // MODULE_NOT_FOUND means only this subpath failed to resolve, not that the
+        // package is absent. Restricted exports and alternate layouts require the
+        // remaining tiers.
     }
-    // Second fall-back: resolve the main entry, then walk up directories
-    // searching for a package.json whose name matches.
+    // Tier 2: resolve the package entry, then walk upward to its named manifest.
     try {
         const entry = req.resolve(packageName);
         let dir = (0, path_1.dirname)(entry);
@@ -366,12 +400,11 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
             if ((0, fs_1.existsSync)(candidate)) {
                 try {
                     const parsed = JSON.parse((0, fs_1.readFileSync)(candidate, 'utf8'));
-                    if (parsed.name === packageName) {
+                    if (parsed.name === packageName)
                         return candidate;
-                    }
                 }
                 catch {
-                    // keep walking
+                    // Keep walking toward the package root.
                 }
             }
             const parent = (0, path_1.dirname)(dir);
@@ -381,17 +414,13 @@ function resolvePackageJson(req, packageName, nodeModulesChain) {
         }
     }
     catch {
-        // ESM-only package or similar: fall through to the node_modules walk.
+        // ESM-only package or similar: fall through to node_modules lookup.
     }
-    // Third fall-back: walk the precomputed `node_modules` ancestor
-    // chain looking for `<ancestor>/node_modules/<packageName>/package.json`.
-    // This is what npm/pnpm/yarn tooling does internally and works
-    // regardless of how the package's `exports` are configured.
+    // Tier 3: search cached ancestor node_modules roots, independent of exports.
     for (const dir of nodeModulesChain) {
         const candidate = (0, path_1.join)(dir, 'node_modules', packageName, 'package.json');
-        if ((0, fs_1.existsSync)(candidate)) {
+        if ((0, fs_1.existsSync)(candidate))
             return candidate;
-        }
     }
     return undefined;
 }

package/package.json

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