@typed/virtual-modules 1.0.0-beta.1

package/dist/internal/VirtualRecordStore.js

@@ -0,0 +1,199 @@
+import { createVirtualFileName, createVirtualKey, createWatchDescriptorKey } from "./path.js";
+export function toResolvedModule(tsMod, fileName) {
+    return {
+        resolvedFileName: fileName,
+        extension: tsMod.Extension.Ts,
+        isExternalLibraryImport: false,
+    };
+}
+export function createVirtualRecordStore(options) {
+    const recordsByKey = new Map();
+    const recordsByVirtualFile = new Map();
+    const descriptorToVirtualKeys = new Map();
+    const watcherByDescriptor = new Map();
+    let debounceTimer;
+    const pendingStaleKeys = new Set();
+    const { debounceMs, watchHost, shouldEvictRecord, onFlushStale, onMarkStale, onBeforeResolve, onAfterResolve, onRecordResolved, onEvictRecord, } = options;
+    const evictRecord = (record) => {
+        onEvictRecord?.(record);
+        recordsByKey.delete(record.key);
+        recordsByVirtualFile.delete(record.virtualFileName);
+        for (const descriptor of record.dependencies) {
+            const descriptorKey = createWatchDescriptorKey(descriptor);
+            const dependents = descriptorToVirtualKeys.get(descriptorKey);
+            if (dependents) {
+                dependents.delete(record.key);
+                if (dependents.size === 0) {
+                    descriptorToVirtualKeys.delete(descriptorKey);
+                    const watcher = watcherByDescriptor.get(descriptorKey);
+                    if (watcher) {
+                        watcher.close();
+                        watcherByDescriptor.delete(descriptorKey);
+                    }
+                }
+            }
+        }
+    };
+    const evictStaleImporters = () => {
+        const toEvict = [];
+        for (const record of recordsByKey.values()) {
+            if (shouldEvictRecord(record)) {
+                toEvict.push(record);
+            }
+        }
+        for (const record of toEvict) {
+            evictRecord(record);
+        }
+    };
+    const registerWatchers = (record) => {
+        for (const descriptor of record.dependencies) {
+            const descriptorKey = createWatchDescriptorKey(descriptor);
+            const dependents = descriptorToVirtualKeys.get(descriptorKey) ?? new Set();
+            dependents.add(record.key);
+            descriptorToVirtualKeys.set(descriptorKey, dependents);
+            if (watcherByDescriptor.has(descriptorKey)) {
+                continue;
+            }
+            if (descriptor.type === "file" && watchHost?.watchFile) {
+                const watcher = watchHost.watchFile(descriptor.path, () => {
+                    markStale(descriptorKey);
+                });
+                watcherByDescriptor.set(descriptorKey, watcher);
+            }
+            else if (descriptor.type === "glob" && watchHost?.watchDirectory) {
+                const watcher = watchHost.watchDirectory(descriptor.baseDir, () => {
+                    markStale(descriptorKey);
+                }, descriptor.recursive);
+                watcherByDescriptor.set(descriptorKey, watcher);
+            }
+        }
+    };
+    const flushPendingStale = () => {
+        if (pendingStaleKeys.size === 0) {
+            return;
+        }
+        onFlushStale?.();
+        for (const descriptorKey of pendingStaleKeys) {
+            const keys = descriptorToVirtualKeys.get(descriptorKey);
+            if (!keys || keys.size === 0) {
+                continue;
+            }
+            for (const key of keys) {
+                const record = recordsByKey.get(key);
+                if (record) {
+                    record.stale = true;
+                    onMarkStale?.(record);
+                }
+            }
+        }
+        pendingStaleKeys.clear();
+        debounceTimer = undefined;
+    };
+    const markStale = (descriptorKey) => {
+        if (debounceMs !== undefined && debounceMs > 0) {
+            pendingStaleKeys.add(descriptorKey);
+            if (debounceTimer === undefined) {
+                debounceTimer = setTimeout(() => {
+                    flushPendingStale();
+                }, debounceMs);
+            }
+            return;
+        }
+        const keys = descriptorToVirtualKeys.get(descriptorKey);
+        if (!keys || keys.size === 0) {
+            return;
+        }
+        for (const key of keys) {
+            const record = recordsByKey.get(key);
+            if (record) {
+                record.stale = true;
+                onMarkStale?.(record);
+            }
+        }
+    };
+    const resolveRecord = (id, importer, previous) => {
+        onBeforeResolve?.();
+        try {
+            const resolveOptions = {
+                id,
+                importer,
+                createTypeInfoApiSession: options.createTypeInfoApiSession,
+            };
+            const resolution = options.resolver.resolveModule(resolveOptions);
+            if (resolution.status === "unresolved") {
+                return { status: "unresolved" };
+            }
+            if (resolution.status === "error") {
+                return {
+                    status: "error",
+                    diagnostic: resolution.diagnostic,
+                };
+            }
+            const key = createVirtualKey(id, importer);
+            const virtualFileName = createVirtualFileName(resolution.pluginName, key, { id, importer }, { projectRoot: options.projectRoot });
+            const record = {
+                key,
+                id,
+                importer,
+                pluginName: resolution.pluginName,
+                virtualFileName,
+                sourceText: resolution.sourceText,
+                dependencies: resolution.dependencies,
+                ...(resolution.warnings?.length ? { warnings: resolution.warnings } : {}),
+                version: previous ? previous.version + 1 : 1,
+                stale: false,
+            };
+            recordsByKey.set(key, record);
+            recordsByVirtualFile.set(virtualFileName, record);
+            registerWatchers(record);
+            onRecordResolved?.(record);
+            return {
+                status: "resolved",
+                record,
+            };
+        }
+        finally {
+            onAfterResolve?.();
+        }
+    };
+    const getOrBuildRecord = (id, importer) => {
+        evictStaleImporters();
+        const key = createVirtualKey(id, importer);
+        const existing = recordsByKey.get(key);
+        if (existing && !existing.stale) {
+            return {
+                status: "resolved",
+                record: existing,
+            };
+        }
+        return resolveRecord(id, importer, existing);
+    };
+    const dispose = () => {
+        if (debounceTimer !== undefined) {
+            clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        }
+        pendingStaleKeys.clear();
+        for (const watcher of watcherByDescriptor.values()) {
+            watcher.close();
+        }
+        watcherByDescriptor.clear();
+        descriptorToVirtualKeys.clear();
+        recordsByKey.clear();
+        recordsByVirtualFile.clear();
+    };
+    return {
+        recordsByKey,
+        recordsByVirtualFile,
+        descriptorToVirtualKeys,
+        watcherByDescriptor,
+        evictRecord,
+        evictStaleImporters,
+        registerWatchers,
+        markStale,
+        flushPendingStale,
+        resolveRecord,
+        getOrBuildRecord,
+        dispose,
+    };
+}

package/dist/internal/materializeVirtualFile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rewrite relative import specifiers in sourceText so they resolve correctly when
+ * the file is placed in previewDir instead of importerDir.
+ */
+export declare function rewriteSourceForPreviewLocation(sourceText: string, importer: string, virtualFilePath: string): string;
+/**
+ * Materialize virtual module content to disk at virtualFilePath. Rewrites relative
+ * imports so they resolve from the virtual file's location. Used so go-to-definition
+ * can open the file (path must exist on disk).
+ */
+export declare function materializeVirtualFile(virtualFilePath: string, importer: string, sourceText: string): void;
+//# sourceMappingURL=materializeVirtualFile.d.ts.map

package/dist/internal/materializeVirtualFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializeVirtualFile.d.ts","sourceRoot":"","sources":["../../src/internal/materializeVirtualFile.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,IAAI,CAIN"}

package/dist/internal/materializeVirtualFile.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { toPosixPath } from "./path.js";
+/**
+ * Rewrite relative import specifiers in sourceText so they resolve correctly when
+ * the file is placed in previewDir instead of importerDir.
+ */
+export function rewriteSourceForPreviewLocation(sourceText, importer, virtualFilePath) {
+    const importerDir = dirname(resolve(importer));
+    const previewDir = dirname(resolve(virtualFilePath));
+    return sourceText.replace(/from\s+['"](\.\.?\/[^'"]+)['"]/g, (match, spec) => {
+        const absoluteTarget = resolve(importerDir, spec);
+        const newRel = toPosixPath(relative(previewDir, absoluteTarget));
+        const newSpec = newRel.startsWith(".") ? newRel : `./${newRel}`;
+        const quote = match.includes('"') ? '"' : "'";
+        return `from ${quote}${newSpec}${quote}`;
+    });
+}
+/**
+ * Materialize virtual module content to disk at virtualFilePath. Rewrites relative
+ * imports so they resolve from the virtual file's location. Used so go-to-definition
+ * can open the file (path must exist on disk).
+ */
+export function materializeVirtualFile(virtualFilePath, importer, sourceText) {
+    const rewritten = rewriteSourceForPreviewLocation(sourceText, importer, virtualFilePath);
+    mkdirSync(dirname(resolve(virtualFilePath)), { recursive: true });
+    writeFileSync(virtualFilePath, rewritten, "utf8");
+}

package/dist/internal/path.d.ts

@@ -0,0 +1,40 @@
+import type { WatchDependencyDescriptor } from "../types.js";
+/** Base directory for virtual files under node_modules (enables go-to-definition to resolve correctly). */
+export declare const VIRTUAL_NODE_MODULES_RELATIVE = "node_modules/.typed/virtual";
+export declare const toPosixPath: (path: string) => string;
+export declare const resolveRelativePath: (baseDir: string, relativePath: string) => string;
+/**
+ * Resolves relativePath against baseDir and ensures the result stays under baseDir.
+ * Use for plugin/caller-controlled paths to prevent path traversal.
+ */
+export declare function resolvePathUnderBase(baseDir: string, relativePath: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: "path-escapes-base";
+};
+/** Returns true if absolutePath is under baseDir (or equal). Canonicalizes with realpath so symlinks (e.g. /tmp) match. */
+export declare function pathIsUnderBase(baseDir: string, absolutePath: string): boolean;
+export declare const stableHash: (input: string) => string;
+/** URI scheme for virtual module identifiers (e.g. `typed-virtual://0/...`). Single source of truth for all consumers. */
+export declare const VIRTUAL_MODULE_URI_SCHEME: "typed-virtual";
+export declare const createVirtualKey: (id: string, importer: string) => string;
+export interface CreateVirtualFileNameParams {
+    readonly id: string;
+    readonly importer: string;
+}
+export interface CreateVirtualFileNameOptions {
+    /** When provided, virtual files use projectRoot/node_modules/.typed/virtual/ so go-to-definition resolves correctly. */
+    readonly projectRoot?: string;
+}
+/**
+ * Virtual file name for the TS program. When projectRoot is provided, uses
+ * node_modules/.typed/virtual/ so the path exists on disk (after materialization)
+ * and go-to-definition works like node_modules packages. Falls back to
+ * importer-adjacent path or typed-virtual:// URI when projectRoot is not set.
+ */
+export declare const createVirtualFileName: (pluginName: string, virtualKey: string, params?: CreateVirtualFileNameParams, options?: CreateVirtualFileNameOptions) => string;
+export declare const createWatchDescriptorKey: (descriptor: WatchDependencyDescriptor) => string;
+export declare const dedupeSorted: (values: readonly string[]) => readonly string[];
+//# sourceMappingURL=path.d.ts.map

package/dist/internal/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/internal/path.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D,2GAA2G;AAC3G,eAAO,MAAM,6BAA6B,gCAAgC,CAAC;AAE3E,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAoC,CAAC;AAEhF,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,cAAc,MAAM,KAAG,MAC/B,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAQxE;AAED,2HAA2H;AAC3H,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAe9E;AAED,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MACkB,CAAC;AAI9D,0HAA0H;AAC1H,eAAO,MAAM,yBAAyB,EAAG,eAAwB,CAAC;AAElE,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,EAAE,UAAU,MAAM,KAAG,MAA8B,CAAC;AAE/F,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,wHAAwH;IACxH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,SAAS,2BAA2B,EACpC,UAAU,4BAA4B,KACrC,MAaF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,YAAY,yBAAyB,KAAG,MAOhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAC1B,CAAC"}

package/dist/internal/path.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+/** Base directory for virtual files under node_modules (enables go-to-definition to resolve correctly). */
+export const VIRTUAL_NODE_MODULES_RELATIVE = "node_modules/.typed/virtual";
+export const toPosixPath = (path) => path.replaceAll("\\", "/");
+export const resolveRelativePath = (baseDir, relativePath) => toPosixPath(resolve(baseDir, relativePath));
+/**
+ * Resolves relativePath against baseDir and ensures the result stays under baseDir.
+ * Use for plugin/caller-controlled paths to prevent path traversal.
+ */
+export function resolvePathUnderBase(baseDir, relativePath) {
+    const baseAbs = resolve(baseDir);
+    const resolved = resolve(baseDir, relativePath);
+    const rel = relative(baseAbs, resolved);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        return { ok: false, error: "path-escapes-base" };
+    }
+    return { ok: true, path: toPosixPath(resolved) };
+}
+/** Returns true if absolutePath is under baseDir (or equal). Canonicalizes with realpath so symlinks (e.g. /tmp) match. */
+export function pathIsUnderBase(baseDir, absolutePath) {
+    let baseAbs;
+    let resolvedAbs;
+    try {
+        baseAbs = realpathSync(resolve(baseDir));
+        resolvedAbs = realpathSync(resolve(absolutePath));
+    }
+    catch {
+        baseAbs = resolve(baseDir);
+        resolvedAbs = resolve(absolutePath);
+    }
+    const rel = relative(baseAbs, resolvedAbs);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        return false;
+    }
+    return true;
+}
+export const stableHash = (input) => createHash("sha1").update(input).digest("hex").slice(0, 16);
+const sanitizeSegment = (value) => value.replaceAll(/[^a-zA-Z0-9._-]/g, "-");
+/** URI scheme for virtual module identifiers (e.g. `typed-virtual://0/...`). Single source of truth for all consumers. */
+export const VIRTUAL_MODULE_URI_SCHEME = "typed-virtual";
+export const createVirtualKey = (id, importer) => `${importer}::${id}`;
+/**
+ * Virtual file name for the TS program. When projectRoot is provided, uses
+ * node_modules/.typed/virtual/ so the path exists on disk (after materialization)
+ * and go-to-definition works like node_modules packages. Falls back to
+ * importer-adjacent path or typed-virtual:// URI when projectRoot is not set.
+ */
+export const createVirtualFileName = (pluginName, virtualKey, params, options) => {
+    const safePluginName = sanitizeSegment(pluginName);
+    const hash = stableHash(virtualKey);
+    const basename = `__virtual_${safePluginName}_${hash}.ts`;
+    if (params) {
+        const projectRoot = options?.projectRoot;
+        if (typeof projectRoot === "string" && projectRoot.trim().length > 0) {
+            return toPosixPath(join(resolve(projectRoot), VIRTUAL_NODE_MODULES_RELATIVE, basename));
+        }
+        const importerDir = dirname(toPosixPath(params.importer));
+        return `${importerDir}/${basename}`;
+    }
+    return `${VIRTUAL_MODULE_URI_SCHEME}://0/${safePluginName}/${hash}.ts`;
+};
+export const createWatchDescriptorKey = (descriptor) => {
+    if (descriptor.type === "file") {
+        return `file:${toPosixPath(descriptor.path)}`;
+    }
+    const globs = [...descriptor.relativeGlobs].sort().join("|");
+    return `glob:${toPosixPath(descriptor.baseDir)}:${descriptor.recursive ? "r" : "nr"}:${globs}`;
+};
+export const dedupeSorted = (values) => [...new Set(values.map(toPosixPath))].sort();

package/dist/internal/sanitize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sanitizes error messages for structured diagnostics: strips stack traces and
+ * redacts absolute paths to avoid leaking filesystem layout.
+ */
+export declare function sanitizeErrorMessage(message: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/internal/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/internal/sanitize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW5D"}

package/dist/internal/sanitize.js

@@ -0,0 +1,15 @@
+/**
+ * Sanitizes error messages for structured diagnostics: strips stack traces and
+ * redacts absolute paths to avoid leaking filesystem layout.
+ */
+export function sanitizeErrorMessage(message) {
+    const withoutStack = message
+        .split(/\r?\n/)
+        .filter((line) => !/^\s*at\s+/.test(line.trim()))
+        .join("\n")
+        .trim();
+    const unixPath = /\/[\w./-]+\/[\w./-]+(?:\/[\w./-]*)*/g;
+    const winPath = /[A-Za-z]:[\\/][\w.-]+(?:[\\/][\w.-]+)*/g;
+    let out = withoutStack.replace(unixPath, "[path]").replace(winPath, "[path]");
+    return out.replace(/\s{2,}/g, " ").trim();
+}

package/dist/internal/tsInternal.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal TypeScript API access.
+ *
+ * The TypeScript Compiler API does not expose all capabilities we need for
+ * type-target resolution, assignability fallbacks, and serialization. This
+ * module centralizes use of non-public APIs (via type casts) so that:
+ * - All such use is in one place and documented.
+ * - Callers can guard with try/catch and optional chaining.
+ * - Upgrades to new TS versions can be handled here.
+ *
+ * These APIs are not part of the public TypeScript contract and may change
+ * across versions. Tested with TypeScript 5.x.
+ */
+import type * as ts from "typescript";
+/** Index signature entry shape from internal getIndexInfosOfType (not in public .d.ts). */
+export interface IndexInfo {
+    readonly keyType: ts.Type;
+    readonly type: ts.Type;
+    readonly isReadonly?: boolean;
+}
+/**
+ * Get index signature key/value types for an object type when available.
+ * Uses internal TypeChecker.getIndexInfosOfType; may change in future TS versions.
+ * Returns undefined when the API is missing or throws.
+ */
+export declare function getIndexInfosOfType(type: ts.Type, checker: ts.TypeChecker): readonly IndexInfo[] | undefined;
+/**
+ * Resolve an alias symbol to the symbol it refers to (re-exports, import-then-export).
+ * Only call when symbol.flags includes SymbolFlags.Alias.
+ * Uses internal TypeChecker.getAliasedSymbol; may change in future TS versions.
+ * Returns the original symbol when the API is missing or throws.
+ */
+export declare function getAliasedSymbol(symbol: ts.Symbol, checker: ts.TypeChecker, tsMod: typeof import("typescript")): ts.Symbol;
+/**
+ * Get the base (generic declaration) type from a TypeReference.
+ * Uses internal (type as TypeReference).target; may change in future TS versions.
+ * Returns undefined when not a TypeReference with target or when access throws.
+ */
+export declare function getTypeReferenceTarget(type: ts.Type, checker: ts.TypeChecker): (ts.Type & {
+    symbol?: ts.Symbol;
+}) | undefined;
+/**
+ * Get the symbol attached to a type when available (e.g. interface, class, type alias).
+ * Uses internal (type as Type).symbol; may change in future TS versions.
+ */
+export declare function getTypeSymbol(type: ts.Type): ts.Symbol | undefined;
+/**
+ * Get namespace/merged declaration exports from a symbol when available.
+ * Uses internal (symbol as Symbol).exports; may change in future TS versions.
+ * Prefer checker.getExportsOfModule(moduleSymbol) for module symbols when applicable.
+ */
+export declare function getSymbolExports(symbol: ts.Symbol): Map<unknown, ts.Symbol> | undefined;
+/**
+ * Get base types of an interface/class for inheritance checks.
+ * Uses internal TypeChecker.getBaseTypes; may change in future TS versions.
+ * Returns undefined when the API is missing or throws (e.g. type is not interface or class).
+ */
+export declare function getBaseTypes(type: ts.InterfaceType, checker: ts.TypeChecker): ts.Type[] | undefined;
+/**
+ * ObjectFlags.Mapped value when the public ts.ObjectFlags is missing (e.g. older or different TS build).
+ * Used only as a fallback for mapped-type detection in serialization.
+ * Value 32 corresponds to ObjectFlags.Mapped in TypeScript 5.x; may need adjustment for other versions.
+ */
+export declare const FALLBACK_OBJECT_FLAGS_MAPPED = 32;
+//# sourceMappingURL=tsInternal.d.ts.map

package/dist/internal/tsInternal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsInternal.d.ts","sourceRoot":"","sources":["../../src/internal/tsInternal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEtC,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,SAAS,SAAS,EAAE,GAAG,SAAS,CAQlC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,EAAE,CAAC,MAAM,EACjB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,KAAK,EAAE,cAAc,YAAY,CAAC,GACjC,EAAE,CAAC,MAAM,CAUX;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,CAAC,EAAE,CAAC,IAAI,GAAG;IAAE,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAWhD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,MAAM,GAAG,SAAS,CAElE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,EAAE,CAAC,MAAM,GAChB,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,SAAS,CAErC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,EAAE,CAAC,aAAa,EACtB,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,EAAE,CAAC,IAAI,EAAE,GAAG,SAAS,CAQvB;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC"}

package/dist/internal/tsInternal.js

@@ -0,0 +1,99 @@
+/**
+ * Internal TypeScript API access.
+ *
+ * The TypeScript Compiler API does not expose all capabilities we need for
+ * type-target resolution, assignability fallbacks, and serialization. This
+ * module centralizes use of non-public APIs (via type casts) so that:
+ * - All such use is in one place and documented.
+ * - Callers can guard with try/catch and optional chaining.
+ * - Upgrades to new TS versions can be handled here.
+ *
+ * These APIs are not part of the public TypeScript contract and may change
+ * across versions. Tested with TypeScript 5.x.
+ */
+/**
+ * Get index signature key/value types for an object type when available.
+ * Uses internal TypeChecker.getIndexInfosOfType; may change in future TS versions.
+ * Returns undefined when the API is missing or throws.
+ */
+export function getIndexInfosOfType(type, checker) {
+    try {
+        const fn = checker
+            .getIndexInfosOfType;
+        return fn?.(type);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve an alias symbol to the symbol it refers to (re-exports, import-then-export).
+ * Only call when symbol.flags includes SymbolFlags.Alias.
+ * Uses internal TypeChecker.getAliasedSymbol; may change in future TS versions.
+ * Returns the original symbol when the API is missing or throws.
+ */
+export function getAliasedSymbol(symbol, checker, tsMod) {
+    if ((symbol.flags & tsMod.SymbolFlags.Alias) === 0)
+        return symbol;
+    try {
+        const aliased = checker.getAliasedSymbol(symbol);
+        return aliased ?? symbol;
+    }
+    catch {
+        return symbol;
+    }
+}
+/**
+ * Get the base (generic declaration) type from a TypeReference.
+ * Uses internal (type as TypeReference).target; may change in future TS versions.
+ * Returns undefined when not a TypeReference with target or when access throws.
+ */
+export function getTypeReferenceTarget(type, checker) {
+    try {
+        const args = checker.getTypeArguments(type);
+        if (args.length > 0) {
+            const target = type.target;
+            return target;
+        }
+    }
+    catch {
+        /* getTypeArguments can throw for some type shapes */
+    }
+    return undefined;
+}
+/**
+ * Get the symbol attached to a type when available (e.g. interface, class, type alias).
+ * Uses internal (type as Type).symbol; may change in future TS versions.
+ */
+export function getTypeSymbol(type) {
+    return type.symbol;
+}
+/**
+ * Get namespace/merged declaration exports from a symbol when available.
+ * Uses internal (symbol as Symbol).exports; may change in future TS versions.
+ * Prefer checker.getExportsOfModule(moduleSymbol) for module symbols when applicable.
+ */
+export function getSymbolExports(symbol) {
+    return symbol.exports;
+}
+/**
+ * Get base types of an interface/class for inheritance checks.
+ * Uses internal TypeChecker.getBaseTypes; may change in future TS versions.
+ * Returns undefined when the API is missing or throws (e.g. type is not interface or class).
+ */
+export function getBaseTypes(type, checker) {
+    try {
+        const fn = checker
+            .getBaseTypes;
+        return fn?.(type);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * ObjectFlags.Mapped value when the public ts.ObjectFlags is missing (e.g. older or different TS build).
+ * Used only as a fallback for mapped-type detection in serialization.
+ * Value 32 corresponds to ObjectFlags.Mapped in TypeScript 5.x; may need adjustment for other versions.
+ */
+export const FALLBACK_OBJECT_FLAGS_MAPPED = 32;

package/dist/internal/validation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure validators for plugin and TypeInfoApi boundaries. No I/O.
+ */
+export type ValidationOk<T> = {
+    ok: true;
+    value: T;
+};
+export type ValidationFail = {
+    ok: false;
+    reason: string;
+};
+export type ValidationResult<T> = ValidationOk<T> | ValidationFail;
+/**
+ * Validates a non-empty string (trimmed). Rejects null bytes.
+ */
+export declare function validateNonEmptyString(value: unknown, name: string, maxLength?: number): ValidationResult<string>;
+/**
+ * Validates a path-like segment: string, non-empty, no null byte, optional max length.
+ * Does not trim so path semantics are preserved.
+ */
+export declare function validatePathSegment(value: unknown, name: string, maxLength?: number): ValidationResult<string>;
+/**
+ * Validates relativeGlobs: array or single string; each element non-empty, no null byte,
+ * no parent-segment (..) or absolute paths, optional max length.
+ * Rejects patterns that could escape the intended base directory.
+ */
+export declare function validateRelativeGlobs(value: unknown, name: string, maxLength?: number): ValidationResult<string[]>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/internal/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/internal/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;AAEnE;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAA2B,GACrC,gBAAgB,CAAC,MAAM,CAAC,CAe1B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAA2B,GACrC,gBAAgB,CAAC,MAAM,CAAC,CAc1B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAA2B,GACrC,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAiB5B"}

package/dist/internal/validation.js

@@ -0,0 +1,66 @@
+/**
+ * Pure validators for plugin and TypeInfoApi boundaries. No I/O.
+ */
+const DEFAULT_MAX_LENGTH = 4096;
+/**
+ * Validates a non-empty string (trimmed). Rejects null bytes.
+ */
+export function validateNonEmptyString(value, name, maxLength = DEFAULT_MAX_LENGTH) {
+    if (typeof value !== "string") {
+        return { ok: false, reason: `${name} must be a string` };
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return { ok: false, reason: `${name} must be non-empty` };
+    }
+    if (value.includes("\0")) {
+        return { ok: false, reason: `${name} must not contain null bytes` };
+    }
+    if (value.length > maxLength) {
+        return { ok: false, reason: `${name} exceeds max length ${maxLength}` };
+    }
+    return { ok: true, value: trimmed };
+}
+/**
+ * Validates a path-like segment: string, non-empty, no null byte, optional max length.
+ * Does not trim so path semantics are preserved.
+ */
+export function validatePathSegment(value, name, maxLength = DEFAULT_MAX_LENGTH) {
+    if (typeof value !== "string") {
+        return { ok: false, reason: `${name} must be a string` };
+    }
+    if (value.length === 0 || value.trim() === "") {
+        return { ok: false, reason: `${name} must be non-empty` };
+    }
+    if (value.includes("\0")) {
+        return { ok: false, reason: `${name} must not contain null bytes` };
+    }
+    if (value.length > maxLength) {
+        return { ok: false, reason: `${name} exceeds max length ${maxLength}` };
+    }
+    return { ok: true, value };
+}
+/**
+ * Validates relativeGlobs: array or single string; each element non-empty, no null byte,
+ * no parent-segment (..) or absolute paths, optional max length.
+ * Rejects patterns that could escape the intended base directory.
+ */
+export function validateRelativeGlobs(value, name, maxLength = DEFAULT_MAX_LENGTH) {
+    const arr = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+    const result = [];
+    for (let i = 0; i < arr.length; i++) {
+        const v = arr[i];
+        const r = validatePathSegment(v, `${name}[${i}]`, maxLength);
+        if (!r.ok)
+            return r;
+        const normalized = r.value.replaceAll("\\", "/");
+        if (normalized.includes("..")) {
+            return { ok: false, reason: `${name}[${i}] must not contain parent path segments (..)` };
+        }
+        if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
+            return { ok: false, reason: `${name}[${i}] must be a relative glob, not absolute` };
+        }
+        result.push(r.value);
+    }
+    return { ok: true, value: result };
+}