@tsdoctor/registry 0.1.0

package/TypeResolver.js

@@ -0,0 +1,183 @@
+import { compileWildcard, extractTypesFromExport, findMainTypePath, getExportValue, isSafeRelativePath, isTypeDefinition, normalizePath } from "./internal/resolution.js";
+import { PackageSpec } from "./PackageSpec.js";
+import { Option, Schema } from "effect";
+
+//#region src/TypeResolver.ts
+/**
+* A resolved module: the declaration file a specifier resolves to within a
+* package.
+*
+* @public
+*/
+var ResolvedModule = class extends Schema.Class("ResolvedModule")({
+	/** The file path relative to the package root (no `./` prefix). */
+	filePath: Schema.String,
+	/** Whether the path names a TypeScript declaration file. */
+	isTypeDefinition: Schema.Boolean,
+	/** The package the path belongs to. */
+	package: PackageSpec
+}) {};
+const DUNDER_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Build a `ResolvedModule` only when the manifest-supplied path stays inside
+* the package: resolved paths reach `PackageFetcher.downloadFile`'s URL and
+* the cache's join, so an absolute or `..`-bearing path from a hostile
+* manifest must not survive resolution.
+*/
+const safeResolved = (filePath, pkg) => {
+	const normalized = normalizePath(filePath.replace(/^\.\//, ""));
+	if (!isSafeRelativePath(normalized)) return Option.none();
+	return Option.some(ResolvedModule.make({
+		filePath: normalized,
+		isTypeDefinition: isTypeDefinition(normalized),
+		package: pkg
+	}));
+};
+/**
+* Pure `package.json` → declaration-file resolution.
+*
+* @remarks
+* Stateless pure functions — no service, no layer (v3's `Layer.succeed` over
+* stateless functions was ceremony), and no fictional error channel: v3
+* declared a `ResolutionError` its total implementation could never raise.
+* Here {@link TypeResolver.resolveImport} is honest in the other direction
+* too — it returns `Option.none()` where v3 fabricated a guessed fallback
+* path, leaving fallback policy to the caller.
+*
+* All map inputs are untrusted CDN data; the machinery underneath is depth-
+* guarded, wildcard-bounded and prototype-pollution-safe (see
+* `internal/resolution.ts`), and every resolved path is validated to stay
+* inside the package before a `ResolvedModule` is constructed.
+*
+* @public
+*/
+var TypeResolver = class TypeResolver {
+	constructor() {}
+	/**
+	* Resolve an import specifier (`"zod"`, `"zod/lib/types"`) against a
+	* manifest.
+	*
+	* @remarks
+	* Resolution order: the `exports` map (`types` condition, then
+	* `import`/`default`, fallback arrays in order), then `typesVersions["*"]`
+	* (exact, then bounded wildcards), then — for the root specifier only —
+	* the top-level `types`/`typings` fields. `Option.none()` when the
+	* manifest offers no evidence for the subpath, or when the evidence names
+	* a path outside the package (hostile manifest — fails closed).
+	*/
+	static resolveImport(specifier, manifest, pkg) {
+		let subpath;
+		if (specifier === pkg.name) subpath = ".";
+		else if (specifier.startsWith(`${pkg.name}/`)) subpath = `./${specifier.slice(pkg.name.length + 1)}`;
+		else {
+			const bare = specifier.replace(/^\/+/, "");
+			subpath = bare === "" || bare === "." ? "." : bare.startsWith("./") ? bare : `./${bare}`;
+		}
+		if (manifest.exports !== void 0) {
+			const exportValue = getExportValue(manifest.exports, subpath);
+			const typesPath = extractTypesFromExport(exportValue);
+			if (typesPath !== null) return safeResolved(typesPath, pkg);
+		}
+		if (manifest.typesVersions !== void 0 && Object.hasOwn(manifest.typesVersions, "*")) {
+			const versionMap = manifest.typesVersions["*"];
+			if (versionMap !== void 0) {
+				const lookupPath = subpath === "." ? "." : subpath.replace(/^\.\//, "");
+				if (!DUNDER_KEYS.has(lookupPath) && Object.hasOwn(versionMap, lookupPath)) {
+					const mapped = versionMap[lookupPath];
+					const first = Array.isArray(mapped) ? mapped[0] : mapped;
+					if (typeof first === "string") return safeResolved(first, pkg);
+				}
+				for (const pattern of Object.keys(versionMap)) {
+					if (DUNDER_KEYS.has(pattern) || !pattern.includes("*")) continue;
+					if (!Object.hasOwn(versionMap, pattern)) continue;
+					const regex = compileWildcard(pattern);
+					if (regex === null) continue;
+					const match = regex.exec(lookupPath);
+					if (match === null) continue;
+					const mapped = versionMap[pattern];
+					const first = Array.isArray(mapped) ? mapped[0] : mapped;
+					if (typeof first === "string") return safeResolved(first.replace(/\*/g, match[1] ?? ""), pkg);
+				}
+			}
+		}
+		if (subpath === ".") {
+			if (manifest.types !== void 0) return safeResolved(manifest.types, pkg);
+			if (manifest.typings !== void 0) return safeResolved(manifest.typings, pkg);
+		}
+		return Option.none();
+	}
+	/**
+	* Resolve the manifest's main type entry.
+	*
+	* @remarks
+	* Total by the documented `index.d.ts` convention floor: `types`/`typings`,
+	* then the root export's types condition, then a declaration-extension
+	* swap of `main`, then `index.d.ts`. A main path that escapes the package
+	* (hostile manifest) also falls to the floor rather than surviving.
+	*/
+	static resolveMainEntry(manifest, pkg) {
+		return Option.getOrElse(safeResolved(findMainTypePath(manifest), pkg), () => ResolvedModule.make({
+			filePath: "index.d.ts",
+			isTypeDefinition: true,
+			package: pkg
+		}));
+	}
+	/**
+	* Enumerate every entry point that exposes type definitions: the main
+	* entry plus each `exports` subpath with a types-bearing condition,
+	* deduplicated by file path.
+	*
+	* @remarks
+	* Wildcard export keys (`"./*"`) are skipped: enumeration has no captured
+	* segment to substitute, so a pattern entry would emit a literal
+	* `dist/*.d.ts`. Pattern subpaths resolve through
+	* {@link TypeResolver.resolveImport}, which has the concrete specifier.
+	* Entries whose paths escape the package are skipped.
+	*/
+	static resolveTypeEntries(manifest, pkg) {
+		const entries = [TypeResolver.resolveMainEntry(manifest, pkg)];
+		if (manifest.exports !== void 0 && typeof manifest.exports === "object" && !Array.isArray(manifest.exports)) for (const key of Object.keys(manifest.exports)) {
+			if (DUNDER_KEYS.has(key)) continue;
+			if (!key.startsWith(".")) continue;
+			if (key.includes("*")) continue;
+			if (!Object.hasOwn(manifest.exports, key)) continue;
+			const typesPath = extractTypesFromExport(manifest.exports[key]);
+			if (typesPath !== null) {
+				const entry = safeResolved(typesPath, pkg);
+				if (Option.isSome(entry)) entries.push(entry.value);
+			}
+		}
+		const seen = /* @__PURE__ */ new Set();
+		return entries.filter((entry) => {
+			if (!entry.isTypeDefinition) return false;
+			if (seen.has(entry.filePath)) return false;
+			seen.add(entry.filePath);
+			return true;
+		});
+	}
+	/**
+	* The conventional declaration-file path for a JavaScript file path
+	* (`lib/index.js` → `lib/index.d.ts`, `.mjs` → `.d.mts`, `.cjs` →
+	* `.d.cts`).
+	*
+	* @remarks
+	* The input is a tree path from the CDN — untrusted — so a path that is
+	* absolute or escapes the package yields `Option.none()` instead of a
+	* `ResolvedModule` that could reach a download URL.
+	*/
+	static findTypeDefinition(jsFilePath, pkg) {
+		let typePath;
+		if (jsFilePath.endsWith(".mjs")) typePath = jsFilePath.replace(/\.mjs$/, ".d.mts");
+		else if (jsFilePath.endsWith(".cjs")) typePath = jsFilePath.replace(/\.cjs$/, ".d.cts");
+		else if (jsFilePath.endsWith(".js")) typePath = jsFilePath.replace(/\.js$/, ".d.ts");
+		else typePath = `${jsFilePath.replace(/\.(m?js|cjs)$/, "")}.d.ts`;
+		return safeResolved(typePath, pkg);
+	}
+};
+
+//#endregion
+export { ResolvedModule, TypeResolver };

package/Vfs.js

@@ -0,0 +1,33 @@
+//#region src/Vfs.ts
+/**
+* Merge VFS maps left to right into a new map; later entries win on path
+* collisions.
+*
+* @example
+* ```ts
+* import { mergeVfs } from "@tsdoctor/registry";
+*
+* const combined = mergeVfs(vfsA, vfsB);
+* ```
+*
+* @public
+*/
+const mergeVfs = (...maps) => {
+	const out = /* @__PURE__ */ new Map();
+	for (const map of maps) for (const [path, content] of map) out.set(path, content);
+	return out;
+};
+/**
+* Prefix every path in `entries` with `node_modules/<name>/`, normalizing
+* away leading slashes.
+*
+* @public
+*/
+const prefixVfs = (name, entries) => {
+	const out = /* @__PURE__ */ new Map();
+	for (const [path, content] of entries) out.set(`node_modules/${name}/${path.replace(/^\/+/, "")}`, content);
+	return out;
+};
+
+//#endregion
+export { mergeVfs, prefixVfs };

package/VirtualPackage.js

@@ -0,0 +1,126 @@
+import { Effect, FileSystem, Schema } from "effect";
+
+//#region src/VirtualPackage.ts
+/**
+* A synthetic npm package built from locally supplied TypeScript declaration
+* content, for inclusion in a {@link Vfs} without fetching from the CDN.
+*
+* @remarks
+* Useful when you have locally generated `.d.ts` files — API Extractor
+* output, hand-written ambient declarations — and want them in the same VFS
+* `TypeRegistry` builds from remote packages. Instances are transient: they
+* are never persisted to the disk cache.
+*
+* The class is deliberately subclass-friendly (the rspress consumer extends
+* it): construct via `VirtualPackage.make(...)` or the statics, and extend
+* with `class Mine extends VirtualPackage { ... }`.
+*
+* @example
+* ```ts
+* import { VirtualPackage } from "@tsdoctor/registry";
+*
+* const pkg = VirtualPackage.create("@my-org/api-types", "1.0.0", "export interface User { id: string }");
+* const vfs = pkg.toVfs();
+* // node_modules/@my-org/api-types/package.json, node_modules/@my-org/api-types/index.d.ts
+* ```
+*
+* @public
+*/
+var VirtualPackage = class VirtualPackage extends Schema.Class("VirtualPackage")({
+	/** The package name (e.g. `"@my-org/api-types"`). */
+	name: Schema.String,
+	/** The package version. */
+	version: Schema.String,
+	/** Entry file names (e.g. `"index.d.ts"`) mapped to declaration source. */
+	entries: Schema.ReadonlyMap(Schema.String, Schema.String)
+}) {
+	/**
+	* Single-entry factory: a virtual package whose sole entry point is
+	* `index.d.ts`.
+	*/
+	static create(name, version, declarations) {
+		return VirtualPackage.make({
+			name,
+			version,
+			entries: /* @__PURE__ */ new Map([["index.d.ts", declarations]])
+		});
+	}
+	/**
+	* Multi-entry factory: one `.d.ts` per entry point, exposed through a
+	* synthetic `exports` map.
+	*
+	* @remarks
+	* An empty entries map is developer wiring, not input — it would produce a
+	* package whose `types` points at a file that does not exist — so it
+	* throws at construction (defect posture), as does an entry set whose
+	* names collide after extension normalization (see
+	* {@link VirtualPackage.toVfs}).
+	*/
+	static createMultiEntry(name, version, entries) {
+		if (entries.size === 0) throw new Error(`VirtualPackage.createMultiEntry: "${name}" needs at least one entry file`);
+		return VirtualPackage.make({
+			name,
+			version,
+			entries
+		});
+	}
+	/**
+	* Load a single `.d.ts` file from disk as a virtual package with one
+	* `index.d.ts` entry.
+	*
+	* @remarks
+	* Reads through the platform-agnostic `FileSystem` service; the
+	* `PlatformError` surfaces typed.
+	*/
+	static fromFile(name, version, filePath) {
+		return Effect.gen(function* () {
+			const content = yield* (yield* FileSystem.FileSystem).readFileString(filePath);
+			return VirtualPackage.create(name, version, content);
+		}).pipe(Effect.withSpan("VirtualPackage.fromFile"));
+	}
+	/**
+	* The package's {@link Vfs}: a synthetic `package.json` plus every entry
+	* file, each path prefixed `node_modules/<name>/`.
+	*
+	* @remarks
+	* The `package.json` uses `types` for a single entry and an `exports` map
+	* for multiple entries, so TypeScript module resolution works against the
+	* generated VFS.
+	*/
+	toVfs() {
+		const vfs = /* @__PURE__ */ new Map();
+		const prefix = `node_modules/${this.name}`;
+		vfs.set(`${prefix}/package.json`, this.toPackageJson());
+		for (const [fileName, content] of this.entries) {
+			if (fileName === "package.json") throw new Error(`VirtualPackage: "${this.name}" cannot define package.json as an entry`);
+			vfs.set(`${prefix}/${fileName}`, content);
+		}
+		return vfs;
+	}
+	toPackageJson() {
+		if (this.entries.size === 0) throw new Error(`VirtualPackage: "${this.name}" has no entry files — nothing to point types at`);
+		const manifest = {
+			name: this.name,
+			version: this.version
+		};
+		if (this.entries.size === 1) {
+			const [only] = this.entries.keys();
+			manifest.types = only ?? "index.d.ts";
+		} else {
+			manifest.exports = {};
+			const sources = /* @__PURE__ */ new Map();
+			for (const fileName of this.entries.keys()) {
+				const baseName = fileName.replace(/\.d\.(m|c)?ts$/, "");
+				const key = baseName === "index" ? "." : `./${baseName}`;
+				const previous = sources.get(key);
+				if (previous !== void 0) throw new Error(`VirtualPackage: "${this.name}" entries "${previous}" and "${fileName}" both normalize to the export key "${key}"`);
+				sources.set(key, fileName);
+				manifest.exports[key] = { types: `./${fileName}` };
+			}
+		}
+		return JSON.stringify(manifest, null, 2);
+	}
+};
+
+//#endregion
+export { VirtualPackage };