@tsdoctor/registry 0.1.0

package/index.js

@@ -0,0 +1,11 @@
+import { RegistryEvent, RegistryObserver } from "./RegistryEvent.js";
+import { FetchError, PackageFetcher, PackageManifest, PackageNotFoundError, VersionNotFoundError } from "./PackageFetcher.js";
+import { PackageSpec } from "./PackageSpec.js";
+import { TsEnvironment, TsEnvironmentError } from "./TsEnvironment.js";
+import { TypeCache, TypeCacheError, TypeCacheMetadata } from "./TypeCache.js";
+import { ResolvedModule, TypeResolver } from "./TypeResolver.js";
+import { mergeVfs, prefixVfs } from "./Vfs.js";
+import { BatchLoadError, TypeRegistry } from "./TypeRegistry.js";
+import { VirtualPackage } from "./VirtualPackage.js";
+
+export { BatchLoadError, FetchError, PackageFetcher, PackageManifest, PackageNotFoundError, PackageSpec, RegistryEvent, RegistryObserver, ResolvedModule, TsEnvironment, TsEnvironmentError, TypeCache, TypeCacheError, TypeCacheMetadata, TypeRegistry, TypeResolver, VersionNotFoundError, VirtualPackage, mergeVfs, prefixVfs };

package/internal/jsdelivr.js

@@ -0,0 +1,62 @@
+import { isSafeRelativePath } from "./resolution.js";
+import { Schema } from "effect";
+
+//#region src/internal/jsdelivr.ts
+/** Base URL for the jsDelivr data/metadata API. */
+const DATA_API = "https://data.jsdelivr.com/v1";
+/** Base URL for the jsDelivr file-serving CDN. */
+const CDN = "https://cdn.jsdelivr.net";
+/**
+* Matches TypeScript declaration file names: the standard `.d.ts`, `.d.mts`
+* and `.d.cts` suffixes, plus the arbitrary-extension form `.d.<ext>.ts`
+* (TS 5 `allowArbitraryExtensions`, e.g. `styles.d.css.ts`). The middle
+* segment is only valid before a plain `.ts` — `.d.<ext>.mts`/`.cts` are not
+* declaration forms — and cannot span path separators, so a directory named
+* `assets.d.css` does not make `assets.d.css/index.ts` a declaration file.
+*/
+const TYPE_FILE_PATTERN = /(\.d\.[cm]?ts|\.d\.[^./\\]+\.ts)$/i;
+/** The package metadata endpoint: versions and dist-tags. */
+const versionsUrl = (name) => `${DATA_API}/package/npm/${name}`;
+/** The flat file-tree endpoint for a pinned package version. */
+const fileTreeUrl = (pkg) => `${DATA_API}/package/npm/${pkg.name}@${pkg.version}/flat`;
+/**
+* The CDN URL for one file of a pinned package version. Each path segment is
+* percent-encoded so a file name containing `?`, `#` or `%` cannot rewrite
+* the URL's query, fragment or escaping, and a path that escapes the pinned
+* package (`..` segments, absolute forms) throws before a URL exists —
+* `encodeURIComponent` leaves dots active, so encoding alone cannot stop
+* URL normalization from resolving a `..` outside the package. Service
+* callers wrap the throw into a typed failure.
+*/
+const fileUrl = (pkg, filePath) => {
+	const relative = filePath.replace(/^\/+/, "");
+	if (!isSafeRelativePath(relative)) throw new Error(`file path escapes the pinned package: ${filePath}`);
+	const encoded = relative.split("/").filter((segment) => segment !== "" && segment !== ".").map(encodeURIComponent).join("/");
+	return `${CDN}/npm/${pkg.name}@${pkg.version}/${encoded}`;
+};
+/** The CDN URL for a pinned package version's `package.json`. */
+const packageJsonUrl = (pkg) => fileUrl(pkg, "package.json");
+/**
+* The `/package/npm/:name` response: published versions plus dist-tags.
+* Lenient — only the two fields the resolver reads.
+*/
+const VersionsResponse = Schema.Struct({
+	versions: Schema.Array(Schema.String),
+	tags: Schema.Record(Schema.String, Schema.String)
+});
+/**
+* The `/package/npm/:pkg@:version/flat` response. `default` is metadata only
+* (`null` for packages that declare none, e.g. `ink`); the loader consumes
+* `files`, never `default`. `size` (bytes) is used to pre-check the
+* type-file download budget before any request is made.
+*/
+const FileTreeResponse = Schema.Struct({
+	default: Schema.NullOr(Schema.String),
+	files: Schema.Array(Schema.Struct({
+		name: Schema.String,
+		size: Schema.optionalKey(Schema.Number)
+	}))
+});
+
+//#endregion
+export { CDN, DATA_API, FileTreeResponse, TYPE_FILE_PATTERN, VersionsResponse, fileTreeUrl, fileUrl, packageJsonUrl, versionsUrl };

package/internal/limits.js

@@ -0,0 +1,16 @@
+//#region src/internal/limits.ts
+/**
+* Cap on declaration files materialized per package by `getTypeFiles`. A
+* pathological or hostile file tree naming more declaration files than this
+* fails typed rather than exhausting memory.
+*/
+const MAX_TYPE_FILES_PER_PACKAGE = 5e3;
+/**
+* Cap on total downloaded declaration bytes per package, checked as the
+* downloads accumulate. The yaml alias-budget lesson applied to downloads:
+* budget the materialization, not just the input's static size claims.
+*/
+const MAX_TYPE_BYTES_PER_PACKAGE = 67108864;
+
+//#endregion
+export { MAX_TYPE_BYTES_PER_PACKAGE, MAX_TYPE_FILES_PER_PACKAGE };

package/internal/resolution.js

@@ -0,0 +1,181 @@
+//#region src/internal/resolution.ts
+/**
+* Exports-map resolution machinery. Every input here — `exports` values,
+* `typesVersions` maps, wildcard patterns — is untrusted JSON fetched from a
+* CDN, so every recursive surface carries a depth guard, wildcard patterns
+* are bounded before regex compilation, and untrusted keys are only read
+* through `Object.hasOwn` (a JSON-parsed `{"__proto__": …}` key would
+* otherwise read or, worse, assign the prototype).
+*/
+/** Keys that are never data on a plain object. Skipped everywhere. */
+const DUNDER_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/** Whether a path names a TypeScript declaration file. */
+const isTypeDefinition = (filePath) => filePath.endsWith(".d.ts") || filePath.endsWith(".d.mts") || filePath.endsWith(".d.cts");
+/** Normalize backslashes to forward slashes. */
+const normalizePath = (path) => path.replace(/\\/g, "/");
+/**
+* Reject paths that are absolute or contain `..` segments. Shared by the
+* cache (paths from CDN file trees joined under the cache root) and the
+* resolver (paths from untrusted manifests that reach the CDN download URL).
+*/
+const isSafeRelativePath = (filePath) => {
+	if (filePath.length === 0) return false;
+	if (filePath.startsWith("/") || filePath.startsWith("\\")) return false;
+	if (/^[A-Za-z]:/.test(filePath)) return false;
+	return !filePath.split(/[/\\]+/).some((segment) => segment === "..");
+};
+const escapeRegex = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+/**
+* Compile an exports/typesVersions wildcard pattern to a regex, or `null`
+* when the pattern exceeds the wildcard bound. npm semantics use exactly one
+* `*`; a hostile pattern with many wildcards would compile to a
+* catastrophic-backtracking regex, so past the bound it simply does not
+* match.
+*/
+const compileWildcard = (pattern) => {
+	let stars = 0;
+	for (const char of pattern) if (char === "*") stars += 1;
+	if (stars === 0 || stars > 1) return null;
+	return new RegExp(`^${escapeRegex(pattern).replace(/\\?\*/g, "(.*)")}$`);
+};
+/**
+* Substitute a captured wildcard segment into an exports value.
+*
+* @remarks
+* This is where v3 had a live prototype-pollution defect: it copied untrusted
+* keys into a plain object literal, so an `exports` map containing a
+* `"__proto__"` key assigned the prototype of the result. Substituted maps
+* are built with `Object.create(null)` and dunder keys are skipped. Past the
+* depth guard nothing resolves (`null`).
+*/
+const substituteWildcard = (value, captured, depth = 0) => {
+	if (depth > 256) return null;
+	if (typeof value === "string") return value.replace(/\*/g, captured);
+	if (Array.isArray(value)) return value.map((entry) => substituteWildcard(entry, captured, depth + 1));
+	if (typeof value === "object" && value !== null) {
+		const result = Object.create(null);
+		for (const key of Object.keys(value)) {
+			if (DUNDER_KEYS.has(key)) continue;
+			if (!Object.hasOwn(value, key)) continue;
+			const entry = value[key];
+			result[key] = typeof entry === "string" || typeof entry === "object" && entry !== null ? substituteWildcard(entry, captured, depth + 1) : entry;
+		}
+		return result;
+	}
+	return value;
+};
+/**
+* Look up a subpath in an `exports` map: the root-conditions sugar form
+* first, then exact keys (with and without the `./` prefix), then bounded
+* wildcard patterns resolved by Node's specificity rules. Returns the export
+* value (wildcards substituted) or `null`.
+*/
+const getExportValue = (exports, subpath) => {
+	if (exports === void 0 || exports === null) return null;
+	if (typeof exports === "string") return subpath === "." ? exports : null;
+	if (Array.isArray(exports)) return subpath === "." ? exports : null;
+	if (typeof exports !== "object") return null;
+	const exportsObj = exports;
+	const keys = Object.keys(exportsObj);
+	if (!keys.some((key) => key.startsWith("."))) return subpath === "." ? exportsObj : null;
+	const withoutDot = subpath.replace(/^\.\//, "");
+	for (const key of [subpath, withoutDot]) if (!DUNDER_KEYS.has(key) && Object.hasOwn(exportsObj, key)) return exportsObj[key];
+	let best = null;
+	for (const pattern of keys) {
+		if (DUNDER_KEYS.has(pattern) || !pattern.includes("*")) continue;
+		if (!Object.hasOwn(exportsObj, pattern)) continue;
+		const regex = compileWildcard(pattern);
+		if (regex === null) continue;
+		const match = regex.exec(subpath) ?? regex.exec(withoutDot);
+		if (match === null) continue;
+		const base = pattern.indexOf("*");
+		if (best === null || base > best.base || base === best.base && pattern.length > best.pattern.length) best = {
+			pattern,
+			captured: match[1] ?? "",
+			base
+		};
+	}
+	if (best !== null) return substituteWildcard(exportsObj[best.pattern], best.captured);
+	return null;
+};
+/**
+* Extract a types-bearing path from an export value: `types` first, then
+* `import` / `default`, recursing into nested condition objects under the
+* depth guard. A fallback array (Node semantics) is walked in order and the
+* first entry yielding a types path wins.
+*/
+const extractTypesFromExport = (exportValue, depth = 0) => {
+	if (depth > 256) return null;
+	if (exportValue === void 0 || exportValue === null) return null;
+	if (typeof exportValue === "string") return exportValue;
+	if (Array.isArray(exportValue)) {
+		for (const entry of exportValue) {
+			const found = extractTypesFromExport(entry, depth + 1);
+			if (found !== null) return found;
+		}
+		return null;
+	}
+	if (typeof exportValue !== "object") return null;
+	const conditions = exportValue;
+	for (const condition of [
+		"types",
+		"import",
+		"default"
+	]) {
+		if (!Object.hasOwn(conditions, condition)) continue;
+		const value = conditions[condition];
+		if (typeof value === "string") return value;
+		if (typeof value === "object" && value !== null) {
+			const nested = extractTypesFromExport(value, depth + 1);
+			if (nested !== null) return nested;
+		}
+	}
+	return null;
+};
+/** The conventional lookup candidates for a bare subpath, most specific first. */
+const tryExtensions = (basePath) => [
+	basePath,
+	`${basePath}.d.ts`,
+	`${basePath}.d.mts`,
+	`${basePath}.d.cts`,
+	`${basePath}.ts`,
+	`${basePath}.mts`,
+	`${basePath}.cts`,
+	`${basePath}.js`,
+	`${basePath}.mjs`,
+	`${basePath}.cjs`,
+	`${basePath}/index.d.ts`,
+	`${basePath}/index.d.mts`,
+	`${basePath}/index.d.cts`,
+	`${basePath}/index.ts`,
+	`${basePath}/index.js`
+].map(normalizePath);
+/**
+* The main type entry for a manifest: `types`/`typings`, then the root
+* export's types condition, then a declaration-extension swap of `main`,
+* with the documented `index.d.ts` convention floor — which is what makes
+* `TypeResolver.resolveMainEntry` genuinely total.
+*/
+const findMainTypePath = (manifest) => {
+	if (manifest.types !== void 0) return manifest.types;
+	if (manifest.typings !== void 0) return manifest.typings;
+	if (manifest.exports !== void 0) {
+		const rootExport = getExportValue(manifest.exports, ".");
+		const typesPath = extractTypesFromExport(rootExport);
+		if (typesPath !== null) return typesPath;
+	}
+	if (manifest.main !== void 0) {
+		const mainWithoutExt = manifest.main.replace(/\.(m?[jt]s|cjs)$/, "");
+		const found = tryExtensions(mainWithoutExt).find(isTypeDefinition);
+		if (found !== void 0) return found;
+		return manifest.main;
+	}
+	return "index.d.ts";
+};
+
+//#endregion
+export { compileWildcard, extractTypesFromExport, findMainTypePath, getExportValue, isSafeRelativePath, isTypeDefinition, normalizePath, substituteWildcard, tryExtensions };

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "@tsdoctor/registry",
+	"version": "0.1.0",
+	"private": false,
+	"description": "TypeScript virtual file systems for Effect: fetch, cache and resolve type definitions from npm via the jsDelivr CDN, and build @typescript/vfs environments for Twoslash-style documentation tooling.",
+	"keywords": [
+		"typescript",
+		"vfs",
+		"twoslash",
+		"types",
+		"jsdelivr",
+		"cache",
+		"effect"
+	],
+	"homepage": "https://github.com/spencerbeggs/tsdoctor#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/tsdoctor/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/tsdoctor.git",
+		"directory": "packages/registry"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effect/platform-node": "4.0.0-rc.109",
+		"@effected/semver": "^0.5.0",
+		"@effected/store": "^0.4.0",
+		"@effected/tsconfig-json": "^0.6.0",
+		"@effected/xdg": "^0.3.0",
+		"@typescript/vfs": "^1.6.4",
+		"effect": "4.0.0-rc.109",
+		"typescript": "^6.0.3"
+	},
+	"peerDependenciesMeta": {
+		"@effected/tsconfig-json": {
+			"optional": true
+		},
+		"@effected/xdg": {
+			"optional": true
+		},
+		"@typescript/vfs": {
+			"optional": true
+		},
+		"typescript": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.0"
+    }
+  ]
+}