@microsoft/rayfin-docs 1.27.0

package/dist/discovery.js

@@ -0,0 +1,402 @@
+/**
+ * Per-package docs discovery - Phase 2 of `docs-package-architecture`.
+ *
+ * Walks a project's `node_modules` to find packages declaring the
+ * `rayfinDocs` field in their `package.json`. Returns a list of
+ * discovered package roots so {@link DocsService} can load each tree's
+ * markdown alongside any explicit `assetsRoot`.
+ *
+ * **Trust model.** Discovery is conservative by default: only
+ * `@microsoft/rayfin-*` scoped packages are auto-trusted. Anything else
+ * requires the caller to pass an explicit `trust` predicate. This
+ * matches the spec-review resolution that broad walking is too trusting
+ * (see `openspec/changes/docs-package-architecture/spec-review-findings.md`,
+ * finding B3).
+ *
+ * Discovery is intentionally explicit: callers choose either a fixed
+ * candidate list, workspace package roots, or all-installed node_modules
+ * walking via `scanInstalledPackages: true`.
+ */
+import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+/** Default trust predicate. Auto-trusts the Microsoft Rayfin namespace. */
+export const defaultTrust = (packageName) => packageName.startsWith('@microsoft/rayfin-');
+/**
+ * Returns whether callers already selected a discovery source.
+ * Wrappers use this to decide whether to inject their own bounded defaults.
+ */
+export function hasExplicitDiscoverySource(options) {
+    return countDiscoverySources(options) > 0;
+}
+export function discoverRayfinDocsPackages(options) {
+    const trust = options.trust ?? defaultTrust;
+    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 = [];
+    const untrustedSkipped = [];
+    const invalidManifest = [];
+    const sourceCount = countDiscoverySources(options);
+    if (sourceCount === 0) {
+        throw new Error('discoverRayfinDocsPackages requires an explicit source: pass `candidates`, `packageRoots`, or `scanInstalledPackages: true`.');
+    }
+    if (sourceCount > 1) {
+        throw new Error('discoverRayfinDocsPackages requires exactly one explicit source: pass only one of `candidates`, `packageRoots`, or `scanInstalledPackages: true`.');
+    }
+    let packagesToRead;
+    if (options.packageRoots !== undefined) {
+        packagesToRead = resolvePackageRootJsons(options.packageRoots);
+    }
+    else if (options.candidates !== undefined) {
+        packagesToRead = resolveCandidatePackageJsons(options.candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust);
+    }
+    else if (options.scanInstalledPackages) {
+        packagesToRead = discoverInstalledPackageJsons(nodeModulesChain);
+    }
+    else {
+        throw new Error('Invariant violation: explicit discovery source count did not match selected source.');
+    }
+    for (const { packageName: candidate, pkgJsonPath } of packagesToRead) {
+        let pkgJson;
+        try {
+            pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+        }
+        catch (err) {
+            invalidManifest.push({
+                packageName: candidate,
+                reason: `unreadable package.json: ${err.message}`,
+            });
+            continue;
+        }
+        const parsedName = pkgJson?.name;
+        const packageName = typeof parsedName === 'string' ? parsedName : candidate;
+        const hasRayfinDocs = typeof pkgJson === 'object' &&
+            pkgJson !== null &&
+            'rayfinDocs' in pkgJson;
+        if (!hasRayfinDocs) {
+            continue;
+        }
+        const parsedVersion = pkgJson?.version;
+        if (typeof parsedVersion !== 'string' || parsedVersion.length === 0) {
+            invalidManifest.push({
+                packageName,
+                reason: 'package.json must declare a non-empty string version when rayfinDocs is present',
+            });
+            continue;
+        }
+        if (!trust(packageName)) {
+            untrustedSkipped.push(packageName);
+            continue;
+        }
+        const validation = validateRayfinDocsManifest(pkgJson, candidate);
+        if (!validation.ok) {
+            if (validation.kind === 'missing') {
+                // Package is installed but doesn't declare rayfinDocs. This is
+                // not an error - it's the common case for any package that
+                // hasn't migrated yet. Don't surface as invalid.
+                continue;
+            }
+            invalidManifest.push({
+                packageName: candidate,
+                reason: validation.reason,
+            });
+            continue;
+        }
+        const packageRoot = dirname(pkgJsonPath);
+        discovered.push({
+            packageName,
+            packageVersion: parsedVersion,
+            packageRoot,
+            manifest: validation.manifest,
+        });
+    }
+    return { discovered, notInstalled, untrustedSkipped, invalidManifest };
+}
+function countDiscoverySources(options) {
+    return [
+        options.packageRoots !== undefined,
+        options.candidates !== undefined,
+        options.scanInstalledPackages === true,
+    ].filter(Boolean).length;
+}
+function resolvePackageRootJsons(packageRoots) {
+    return packageRoots.map((packageRoot) => ({
+        packageName: packageRoot,
+        pkgJsonPath: join(resolveExistingDir(packageRoot), 'package.json'),
+    }));
+}
+function resolveCandidatePackageJsons(candidates, requireFromBase, nodeModulesChain, notInstalled, untrustedSkipped, trust) {
+    const resolved = [];
+    for (const candidate of candidates) {
+        if (!trust(candidate)) {
+            untrustedSkipped.push(candidate);
+            continue;
+        }
+        const pkgJsonPath = resolvePackageJson(requireFromBase, candidate, nodeModulesChain);
+        if (!pkgJsonPath) {
+            notInstalled.push(candidate);
+            continue;
+        }
+        resolved.push({ packageName: candidate, pkgJsonPath });
+    }
+    return resolved;
+}
+function discoverInstalledPackageJsons(nodeModulesChain) {
+    const discovered = [];
+    const seen = new Set();
+    for (const dir of nodeModulesChain) {
+        const nodeModules = join(dir, 'node_modules');
+        if (!existsSync(nodeModules) || !statSync(nodeModules).isDirectory()) {
+            continue;
+        }
+        for (const entry of readdirSync(nodeModules, { withFileTypes: true })) {
+            if ((!entry.isDirectory() && !entry.isSymbolicLink()) ||
+                entry.name.startsWith('.')) {
+                continue;
+            }
+            if (entry.name.startsWith('@')) {
+                const scopeRoot = join(nodeModules, entry.name);
+                for (const scoped of readdirSync(scopeRoot, { withFileTypes: true })) {
+                    if (!scoped.isDirectory() && !scoped.isSymbolicLink())
+                        continue;
+                    const packageName = `${entry.name}/${scoped.name}`;
+                    const pkgJsonPath = join(scopeRoot, scoped.name, 'package.json');
+                    if (!seen.has(packageName) && existsSync(pkgJsonPath)) {
+                        seen.add(packageName);
+                        discovered.push({ packageName, pkgJsonPath });
+                    }
+                }
+            }
+            else {
+                const packageName = entry.name;
+                const pkgJsonPath = join(nodeModules, entry.name, 'package.json');
+                if (!seen.has(packageName) && existsSync(pkgJsonPath)) {
+                    seen.add(packageName);
+                    discovered.push({ packageName, pkgJsonPath });
+                }
+            }
+        }
+    }
+    return discovered;
+}
+/**
+ * Validate the `rayfinDocs` field on a parsed `package.json`. Returns
+ * a discriminated result so callers can distinguish "no manifest"
+ * (silently skip) from "broken manifest" (surface as warning).
+ *
+ * Path validation rejects absolute paths and parent-directory
+ * traversal in `dir` - discovered packages must keep their docs
+ * inside their own root.
+ */
+export function validateRayfinDocsManifest(pkgJson, packageName) {
+    if (!pkgJson || typeof pkgJson !== 'object') {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: 'package.json is not an object',
+        };
+    }
+    const rec = pkgJson;
+    const raw = rec['rayfinDocs'];
+    if (raw === undefined) {
+        return { ok: false, kind: 'missing' };
+    }
+    if (!raw || typeof raw !== 'object') {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs` field is not an object',
+        };
+    }
+    const m = raw;
+    if (m['version'] !== 1) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: `unsupported rayfinDocs.version (got ${JSON.stringify(m['version'])}, expected 1); skipping ${packageName}`,
+        };
+    }
+    if (m['dir'] !== undefined && typeof m['dir'] !== 'string') {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs.dir` must be a non-empty string',
+        };
+    }
+    if (m['dir'] === '') {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs.dir` must be a non-empty string',
+        };
+    }
+    const dir = m['dir'] ?? 'assets/docs';
+    if (isAbsolute(dir)) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs.dir` must be a relative path inside the package root',
+        };
+    }
+    // Reject `..` segments anywhere in the relative path. Segment-based
+    // check uniformly handles `..`, `./..`, `docs/..`, `a/../b`, and
+    // mixed separators.
+    const normalized = dir.replace(/\\/g, '/');
+    if (normalized.split('/').some((segment) => segment === '..')) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs.dir` must not traverse outside the package root (no `..` segments)',
+        };
+    }
+    if (typeof m['module'] !== 'string' || m['module'].length === 0) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: '`rayfinDocs.module` must be a non-empty string',
+        };
+    }
+    if (m['kind'] !== 'guide' &&
+        m['kind'] !== 'host' &&
+        m['kind'] !== 'api-reference') {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: `\`rayfinDocs.kind\` must be one of "guide" | "host" | "api-reference" (got ${JSON.stringify(m['kind'])}). ` +
+                `If you need a new kind, request it in the rayfin-docs repo: ` +
+                `https://github.com/microsoft/project-rayfin/issues/new`,
+        };
+    }
+    return {
+        ok: true,
+        manifest: {
+            version: 1,
+            dir,
+            module: m['module'],
+            kind: m['kind'],
+        },
+    };
+}
+/**
+ * Map a `DocKind` to the legacy `DocModule` value used throughout the
+ * existing CLI/MCP surfaces. Phase 2 keeps the `DocModule` union for
+ * back-compat; `--module ts-sdk` continues to mean "all api-reference
+ * docs" for end users.
+ */
+export function docKindToModule(kind) {
+    switch (kind) {
+        case 'guide':
+            return 'guide';
+        case 'host':
+            return 'host';
+        case 'api-reference':
+            return 'ts-sdk';
+    }
+}
+/**
+ * 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
+ * once per candidate (`9 candidates × 16 walks = 144 stat calls` in
+ * the original implementation; this caches the chain to 16 stats).
+ */
+function buildNodeModulesChain(fromDir) {
+    const chain = [];
+    let dir = fromDir;
+    for (let i = 0; i < 16; i += 1) {
+        chain.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    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).
+ *
+ * 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.
+ *
+ * Returns the absolute path to `package.json`, or `undefined` when the
+ * package isn't installed at all.
+ */
+function resolvePackageJson(req, packageName, nodeModulesChain) {
+    // Fast path: works when the package omits `exports` or explicitly
+    // includes `./package.json` in it.
+    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.
+    }
+    // Second fall-back: resolve the main entry, then walk up directories
+    // searching for a package.json whose name matches.
+    try {
+        const entry = req.resolve(packageName);
+        let dir = dirname(entry);
+        for (let i = 0; i < 16; i += 1) {
+            const candidate = join(dir, 'package.json');
+            if (existsSync(candidate)) {
+                try {
+                    const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+                    if (parsed.name === packageName) {
+                        return candidate;
+                    }
+                }
+                catch {
+                    // keep walking
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // ESM-only package or similar: fall through to the node_modules walk.
+    }
+    // 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.
+    for (const dir of nodeModulesChain) {
+        const candidate = join(dir, 'node_modules', packageName, 'package.json');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/** Internal: ensure `from` exists for `createRequire` when given a dir. */
+function resolveExistingDir(from) {
+    const absolute = resolve(from);
+    if (!existsSync(absolute)) {
+        throw new Error(`discoverRayfinDocsPackages: \`from\` path does not exist: ${absolute}`);
+    }
+    const st = statSync(absolute);
+    if (!st.isDirectory()) {
+        throw new Error(`discoverRayfinDocsPackages: \`from\` must be a directory: ${absolute}`);
+    }
+    return absolute;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { type DiscoveryResult, type DiscoveryOptions } from './discovery.js';
+import type { DocEntry, DocListItem, DocModule, DocSearchScope, DocSearchResult, DocSectionRef } from './types.js';
+export interface DocsIndexCacheOptions {
+    /**
+     * Directory used for on-disk index cache files. Defaults to
+     * `~/.rayfin/cache` with a temp-directory fallback for write failures.
+     */
+    dir?: string;
+    /**
+     * Whether to read an existing cache file. Set `false` for CLI/MCP
+     * `--no-cache` behavior while still updating the cache after rebuild.
+     */
+    read?: boolean;
+    /** Whether to write a rebuilt cache file. Defaults to `true`. */
+    write?: boolean;
+}
+/**
+ * Skip reading existing on-disk cache files while still writing a fresh index
+ * after rebuild. Used by CLI/MCP `--no-cache` flags.
+ */
+export declare const DOCS_CACHE_SKIP_READ: DocsIndexCacheOptions;
+export declare const DOCS_NO_CACHE_OPTION_DESCRIPTION = "Bypass any existing on-disk docs index cache and rebuild from installed package docs.";
+/**
+ * Default loaded module set when no `modules` option is provided. Mirrors
+ * the MCP `start` default and the CLI's builder default. Host docs are
+ * .NET reference content (DocFX-generated, ~70% of corpus) and are
+ * loaded only when explicitly requested via `--module host` (CLI) or
+ * `--host-docs` (MCP).
+ *
+ * Exported so the CLI command group, the MCP `start` command, and the
+ * build-time prebuilt-index emitter all read the same constant - changing
+ * the default loaded set requires editing one site.
+ */
+export declare const DOCS_DEFAULT_MODULES: readonly DocModule[];
+export declare function getKnownRayfinDocsPackages(): readonly string[];
+export type { DocEntry, DocListItem, DocModule, DocSearchResult, DocSearchScope, DocSection, DocSectionRef, DocSource, DocKind, RayfinDocsManifest, } from './types.js';
+export { type DiscoveredPackage, type DiscoveryResult, type DiscoveryOptions, type TrustPredicate, defaultTrust, discoverRayfinDocsPackages, validateRayfinDocsManifest, docKindToModule, } from './discovery.js';
+export { type Catalog, type CatalogPackage, type CatalogPackageKind, type DiscoverItem, type DiscoverScore, getCatalog, discoverPackages, mapDiscoverResult, deriveInstallCommand, deriveUpdateCommand, _resetCatalogForTesting, } from './catalog.js';
+export declare class DocsService {
+    private entries;
+    private entriesById;
+    private symbolToSections;
+    private searchIndex;
+    private discoveryReport?;
+    private hydrateFromPrebuilt;
+    constructor(options: {
+        /**
+         * Directory containing the legacy bundled corpus layout
+         * `docs/<module>/...` plus an optional `docs.search.json` prebuilt
+         * index. At least one of `assetsRoot` and `discover` must be set.
+         */
+        assetsRoot?: string;
+        /**
+         * Phase 2+ source: discover packages declaring the `rayfinDocs` field
+         * and load each declaring package's docs. If `candidates` is omitted,
+         * DocsService probes only Rayfin's known docs package list instead of
+         * walking the entire `node_modules` tree. The `from` argument is passed
+         * to {@link discoverRayfinDocsPackages} and used as the `createRequire`
+         * base.
+         */
+        discover?: DiscoveryOptions;
+        /**
+         * Optional filter applied to both legacy `assetsRoot` docs and
+         * discovered package docs.
+         */
+        modules?: readonly DocModule[];
+        /**
+         * Optional on-disk cache for indexes built from discovered installed
+         * packages. Enabled by default for discover-only mode so CLI/MCP cold
+         * starts stay fast while docs remain version-locked to installed package
+         * versions. Pass `false` or `{ read: false }` for `--no-cache` behavior.
+         */
+        cache?: boolean | DocsIndexCacheOptions;
+    });
+    /**
+     * Returns a frozen snapshot of the discovery report from
+     * construction, if `discover` was passed. `undefined` when no
+     * discovery ran (bundled-only mode). Useful for surfacing "package X
+     * is in your trust list but not installed" or "manifest invalid;
+     * skipped" diagnostics. The returned object is deep-frozen so
+     * consumers cannot mutate the service's internal state.
+     */
+    getDiscoveryReport(): DiscoveryResult | undefined;
+    listDocs(module?: DocModule): DocListItem[];
+    getDocById(id: string): DocEntry | undefined;
+    getDocsByPath(path: string, module?: DocModule): DocEntry[];
+    getDocByPath(path: string, module?: DocModule): DocEntry | undefined;
+    searchDocs(query: string, module?: DocModule, limit?: number, scope?: DocSearchScope): DocSearchResult[];
+    getSymbolDocs(symbol: string, module?: DocModule): DocSectionRef[];
+}
+//# sourceMappingURL=index.d.ts.map