@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.4

package/src/check/acquire.ts

@@ -0,0 +1,212 @@
+import type * as TS from 'typescript';
+import { isBareSpecifier, splitPackageSpecifier } from '../resolve.js';
+import { dirname, join } from '../paths.js';
+import { parseLooseJson } from '../projectConfig.js';
+import type { VirtualFileSystem } from '../vfs.js';
+import { SHIMMED_TYPE_REFERENCES } from './shims.js';
+import {
+  CONFIG_MODULES_DIR,
+  dtsCandidates,
+  packageRequestUrl,
+  typesPackageName,
+  versioned,
+  type TypeSources,
+  type TypeStore,
+} from './typeStore.js';
+
+/** The part of a fetch `Response` acquisition reads; the real `fetch` satisfies it. */
+export interface FetchResponseLike {
+  ok: boolean;
+  /** The final URL after redirects. Relative references resolve against it. */
+  url: string;
+  headers: { get(name: string): string | null };
+  text(): Promise<string>;
+}
+
+export type FetchLike = (url: string) => Promise<FetchResponseLike>;
+
+export interface AcquireRequest {
+  /** Bare module specifiers imported by project files (`react`, `react/jsx-runtime`). */
+  specifiers: string[];
+  /** `types` entries and `/// <reference types>` names. */
+  typeReferences: string[];
+  /** Lib file names (`lib.es2020.full.d.ts`). */
+  libFiles: string[];
+  dependencies: Readonly<Record<string, string>>;
+}
+
+export interface AcquireOptions {
+  fetch: FetchLike;
+  sources: TypeSources;
+  /** Upper bound on fetched `.d.ts` files — one run-away graph must not stall a check. */
+  maxFiles: number;
+}
+
+const TYPES_HEADER = 'X-TypeScript-Types';
+
+/**
+ * Fetch every declaration file the request can reach into the store: package
+ * entry types (via the CDN's `X-TypeScript-Types` header), then everything those
+ * import or reference, transitively; lib files and their `/// <reference lib>`s.
+ *
+ * Fetches run concurrently. Each URL is fetched once and its references are
+ * scheduled rather than awaited inside the fetch, so reference cycles between
+ * declaration files cannot deadlock.
+ */
+export async function acquireTypes(ts: typeof TS, store: TypeStore, request: AcquireRequest, options: AcquireOptions): Promise<void> {
+  const { sources } = options;
+  const inflight = new Map<string, Promise<unknown>>();
+  const tasks: Promise<unknown>[] = [];
+  const schedule = (task: () => Promise<unknown>) => tasks.push(task().catch(() => undefined));
+  const once = <T>(key: string, task: () => Promise<T>): Promise<T> => {
+    if (!inflight.has(key)) inflight.set(key, task());
+    return inflight.get(key) as Promise<T>;
+  };
+  const get = (url: string) => options.fetch(url).then((res) => (res.ok ? res : undefined), () => undefined);
+
+  function walk(fromUrl: string, text: string): void {
+    const info = ts.preProcessFile(text, true, true);
+    for (const ref of info.referencedFiles) schedule(() => fetchFirst(dtsCandidates(ref.fileName, fromUrl)));
+    for (const ref of info.typeReferenceDirectives) schedule(() => ensureTypeReference(ref.fileName));
+    for (const ref of info.libReferenceDirectives) schedule(() => ensureLib(`lib.${ref.fileName.toLowerCase()}.d.ts`));
+    for (const ref of info.importedFiles) {
+      const spec = ref.fileName;
+      schedule(() => (isBareSpecifier(spec) ? ensurePackage(spec) : fetchFirst(dtsCandidates(spec, fromUrl))));
+    }
+  }
+
+  /** Fetch one declaration file; resolves to its final URL. */
+  function fetchDts(url: string): Promise<string | undefined> {
+    const known = store.redirects.get(url);
+    if (known !== undefined) return Promise.resolve(known || undefined);
+    if (store.files.has(url)) return Promise.resolve(url);
+    return once(`dts:${url}`, async () => {
+      if (store.files.size >= options.maxFiles) return undefined;
+      const res = await get(url);
+      if (!res) {
+        store.redirects.set(url, '');
+        return undefined;
+      }
+      const final = res.url || url;
+      store.redirects.set(url, final);
+      if (!store.files.has(final)) {
+        const text = await res.text();
+        store.files.set(final, text);
+        walk(final, text);
+      }
+      return final;
+    });
+  }
+
+  async function fetchFirst(candidates: string[]): Promise<string | undefined> {
+    for (const url of candidates) {
+      const final = await fetchDts(url);
+      if (final) return final;
+    }
+    return undefined;
+  }
+
+  /** A bare specifier's entry types, located by the CDN's header. */
+  function ensurePackage(specifier: string, dependencies: Readonly<Record<string, string>> = {}): Promise<string | undefined> {
+    const key = packageRequestUrl(sources.typesOrigin, specifier, dependencies);
+    if (store.packages.has(key)) return Promise.resolve(store.packages.get(key) ?? undefined);
+    return once(`pkg:${key}`, async () => {
+      const res = await get(key);
+      const header = res?.headers.get(TYPES_HEADER);
+      const final = header ? await fetchDts(new URL(header, res!.url || key).href) : undefined;
+      store.packages.set(key, final ?? null);
+      return final;
+    });
+  }
+
+  /** `/// <reference types="x" />` and `types: ["x"]`: the package's own types, else DefinitelyTyped. */
+  function ensureTypeReference(name: string, dependencies: Readonly<Record<string, string>> = {}): Promise<unknown> {
+    if (SHIMMED_TYPE_REFERENCES.has(name)) return Promise.resolve();
+    const key = `types:${name}`;
+    if (store.packages.has(key)) return Promise.resolve();
+    return once(key, async () => {
+      // `node` is DefinitelyTyped's, not the npm package called "node".
+      const own = name === 'node' ? undefined : await ensurePackage(name, dependencies);
+      const { name: pkg, subpath } = splitPackageSpecifier(name);
+      const typesPkg = typesPackageName(pkg);
+      const definitelyTyped = own
+        ? undefined
+        : await fetchDts(`${sources.typesOrigin}/${versioned(typesPkg, dependencies)}${subpath || '/index'}.d.ts`);
+      store.packages.set(key, own ?? definitelyTyped ?? null);
+    });
+  }
+
+  function ensureLib(file: string): Promise<unknown> {
+    if (store.libs.has(file)) return Promise.resolve();
+    return once(`lib:${file}`, async () => {
+      const res = await get(`${sources.libBaseUrl}/${file}`);
+      const text = res ? await res.text() : null;
+      store.libs.set(file, text);
+      if (text) {
+        for (const ref of ts.preProcessFile(text, true, false).libReferenceDirectives) {
+          schedule(() => ensureLib(`lib.${ref.fileName.toLowerCase()}.d.ts`));
+        }
+      }
+    });
+  }
+
+  for (const spec of request.specifiers) schedule(() => ensurePackage(spec, request.dependencies));
+  for (const name of request.typeReferences) schedule(() => ensureTypeReference(name, request.dependencies));
+  for (const file of request.libFiles) schedule(() => ensureLib(file));
+  while (tasks.length) await Promise.all(tasks.splice(0));
+}
+
+/**
+ * Fetch tsconfig files the project `extends` from packages (`@vue/tsconfig`,
+ * `@tsconfig/svelte`) into the store's virtual node_modules, following their own
+ * `extends` chains, so the config parser sees what a local install would hold.
+ */
+export async function acquireExtendedConfigs(
+  fs: VirtualFileSystem,
+  store: TypeStore,
+  dependencies: Readonly<Record<string, string>>,
+  options: Pick<AcquireOptions, 'fetch' | 'sources'>,
+): Promise<void> {
+  const tasks: Promise<void>[] = [];
+
+  function extendsOf(text: string): string[] {
+    try {
+      const value = (parseLooseJson(text) as { extends?: unknown }).extends;
+      return (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === 'string');
+    } catch {
+      return [];
+    }
+  }
+
+  function follow(fromPath: string, text: string): void {
+    for (const spec of extendsOf(text)) {
+      let path: string;
+      if (isBareSpecifier(spec)) {
+        const { name, subpath } = splitPackageSpecifier(spec);
+        path = `${CONFIG_MODULES_DIR}/${name}${subpath ? (subpath.endsWith('.json') ? subpath : `${subpath}.json`) : '/tsconfig.json'}`;
+      } else if (fromPath.startsWith(`${CONFIG_MODULES_DIR}/`)) {
+        path = join(dirname(fromPath), spec.endsWith('.json') ? spec : `${spec}.json`);
+      } else {
+        continue; // a project-local config: already in the VFS
+      }
+      if (store.configs.has(path)) continue;
+      store.configs.set(path, null);
+      tasks.push(fetchConfig(path));
+    }
+  }
+
+  async function fetchConfig(path: string): Promise<void> {
+    const rest = path.slice(CONFIG_MODULES_DIR.length + 1);
+    const { name, subpath } = splitPackageSpecifier(rest);
+    const res = await options.fetch(`${options.sources.npmBaseUrl}/${versioned(name, dependencies)}${subpath}`).catch(() => undefined);
+    if (!res?.ok) return;
+    const text = await res.text();
+    store.configs.set(path, text);
+    follow(path, text);
+  }
+
+  for (const path of fs.list()) {
+    if (/^\/tsconfig[^/]*\.json$/.test(path)) follow(path, fs.readText(path) ?? '');
+  }
+  while (tasks.length) await Promise.all(tasks.splice(0));
+}

package/src/check/compilerHost.ts

@@ -0,0 +1,138 @@
+import type * as TS from 'typescript';
+import type { VirtualFileSystem } from '../vfs.js';
+import type { PathAlias } from '../projectConfig.js';
+import { dirname, extname, join, normalizePath } from '../paths.js';
+import { isBareSpecifier } from '../resolve.js';
+import { AMBIENT_SHIM_PATH, EMPTY_TYPES_PATH, SHIMMED_TYPE_REFERENCES, SHIM_DIR } from './shims.js';
+import { dtsCandidates, LIB_DIR, packageRequestUrl, TYPES_DIR, type TypeStore } from './typeStore.js';
+
+/**
+ * A synchronous TypeScript CompilerHost over the project's VFS and a filled
+ * {@link TypeStore}. Module resolution is done here rather than by TypeScript's
+ * node resolver: project imports follow the runtime's own rules (resolve.ts
+ * probing, tsconfig aliases), bare imports go to the types the CDN named, and
+ * references inside fetched declaration files resolve as URLs.
+ */
+export interface VirtualHostOptions {
+  fs: VirtualFileSystem;
+  store: TypeStore;
+  typesOrigin: string;
+  dependencies: Readonly<Record<string, string>>;
+  aliases: readonly PathAlias[];
+  /** The ambient shim's text (see shims.ts). */
+  shim: string;
+}
+
+const TS_PROBE = ['.ts', '.tsx', '.d.ts', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+
+function extensionOf(ts: typeof TS, path: string): TS.Extension {
+  if (path.endsWith('.d.ts')) return ts.Extension.Dts;
+  if (path.endsWith('.d.mts')) return ts.Extension.Dmts;
+  if (path.endsWith('.d.cts')) return ts.Extension.Dcts;
+  const map: Record<string, TS.Extension> = {
+    '.ts': ts.Extension.Ts, '.tsx': ts.Extension.Tsx, '.mts': ts.Extension.Mts, '.cts': ts.Extension.Cts,
+    '.js': ts.Extension.Js, '.jsx': ts.Extension.Jsx, '.mjs': ts.Extension.Mjs, '.cjs': ts.Extension.Cjs, '.json': ts.Extension.Json,
+  };
+  return map[extname(path)] ?? ts.Extension.Ts;
+}
+
+/** TypeScript's probing for a project-relative path: extensions, `.js` → `.ts`, `index`. */
+function probeProject(fs: VirtualFileSystem, base: string): string | undefined {
+  const ext = extname(base);
+  if (fs.isFile(base) && TS_PROBE.includes(ext)) return base;
+  for (const candidate of TS_PROBE) if (fs.isFile(base + candidate)) return base + candidate;
+  if (ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') {
+    const stem = base.slice(0, -ext.length);
+    for (const alt of ['.ts', '.tsx', '.d.ts', '.mts', '.cts']) if (fs.isFile(stem + alt)) return stem + alt;
+  }
+  for (const candidate of TS_PROBE) if (fs.isFile(join(base, `index${candidate}`))) return join(base, `index${candidate}`);
+  return undefined;
+}
+
+export function createVirtualHost(ts: typeof TS, options: VirtualHostOptions): TS.CompilerHost {
+  const { fs, store } = options;
+
+  const readFile = (path: string): string | undefined => {
+    if (path === AMBIENT_SHIM_PATH) return options.shim;
+    if (path === EMPTY_TYPES_PATH) return 'export {};\n';
+    return fs.readText(path) ?? store.read(path);
+  };
+
+  function typesFor(url: string | undefined | null): string | undefined {
+    return url ? store.virtualPath(url) : undefined;
+  }
+
+  function resolveInTypes(specifier: string, containingUrl: string): string | undefined {
+    if (isBareSpecifier(specifier)) return typesFor(store.packages.get(packageRequestUrl(options.typesOrigin, specifier, {})));
+    for (const candidate of dtsCandidates(specifier, containingUrl)) {
+      const final = store.finalUrl(candidate);
+      if (final) return typesFor(final);
+    }
+    return undefined;
+  }
+
+  function resolveInProject(specifier: string, containingFile: string): string | undefined {
+    if (specifier.includes('?')) return undefined; // `?raw`/`?url`: the ambient shim declares them
+    if (!isBareSpecifier(specifier)) {
+      const base = specifier.startsWith('/') ? normalizePath(specifier) : join(dirname(containingFile), specifier);
+      return probeProject(fs, base);
+    }
+    for (const alias of options.aliases) {
+      const matches = alias.wildcard ? specifier.startsWith(alias.prefix) : specifier === alias.prefix;
+      if (!matches) continue;
+      const rest = alias.wildcard ? specifier.slice(alias.prefix.length) : '';
+      for (const target of alias.targets) {
+        const hit = probeProject(fs, normalizePath(target + rest));
+        if (hit) return hit;
+      }
+    }
+    return typesFor(store.packages.get(packageRequestUrl(options.typesOrigin, specifier, options.dependencies)));
+  }
+
+  function resolveModule(specifier: string, containingFile: string): TS.ResolvedModuleFull | undefined {
+    const containingUrl = store.urlOf(containingFile);
+    const resolved = containingUrl ? resolveInTypes(specifier, containingUrl) : resolveInProject(specifier, containingFile);
+    if (!resolved) return undefined;
+    return { resolvedFileName: resolved, extension: extensionOf(ts, resolved), isExternalLibraryImport: resolved.startsWith(`${TYPES_DIR}/`) };
+  }
+
+  /** `/// <reference types>` resolves the same from anywhere: acquisition keyed it by name. */
+  function resolveTypeReference(name: string): string | undefined {
+    if (SHIMMED_TYPE_REFERENCES.has(name)) return EMPTY_TYPES_PATH;
+    return typesFor(store.packages.get(`types:${name}`));
+  }
+
+  return {
+    getSourceFile(fileName, languageVersion) {
+      const shared = !fs.isFile(fileName);
+      const cached = shared ? store.sourceFiles.get(fileName) : undefined;
+      if (cached) return cached;
+      const text = readFile(fileName);
+      if (text === undefined) return undefined;
+      const file = ts.createSourceFile(fileName, text, languageVersion, true);
+      // Lib and package files never change for a URL: parse once per store.
+      if (shared && fileName !== AMBIENT_SHIM_PATH) store.sourceFiles.set(fileName, file);
+      return file;
+    },
+    getDefaultLibFileName: (compilerOptions) => `${LIB_DIR}/${ts.getDefaultLibFileName(compilerOptions)}`,
+    getDefaultLibLocation: () => LIB_DIR,
+    writeFile: () => undefined,
+    getCurrentDirectory: () => '/',
+    getCanonicalFileName: (fileName) => fileName,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+    fileExists: (fileName) => readFile(fileName) !== undefined,
+    readFile,
+    directoryExists: (dir) => fs.isDirectory(dir) || dir.startsWith(TYPES_DIR) || dir === LIB_DIR || dir === SHIM_DIR,
+    getDirectories: () => [],
+    resolveModuleNameLiterals: (literals, containingFile) =>
+      literals.map((literal) => ({ resolvedModule: resolveModule(literal.text, containingFile) })),
+    resolveTypeReferenceDirectiveReferences: (references) =>
+      references.map((reference) => {
+        const resolved = resolveTypeReference(typeof reference === 'string' ? reference : reference.fileName);
+        return {
+          resolvedTypeReferenceDirective: resolved ? { primary: true, resolvedFileName: resolved, isExternalLibraryImport: true } : undefined,
+        };
+      }),
+  };
+}

package/src/check/diagnostics.ts

@@ -0,0 +1,48 @@
+import type * as TS from 'typescript';
+
+export type DiagnosticCategory = 'error' | 'warning' | 'suggestion' | 'message';
+
+/**
+ * One problem, in a shape an editor (or an agent) can act on without the
+ * TypeScript API: positions are 1-based like an editor's gutter, and `file` is
+ * the project-relative path (`src/App.tsx`), the same key `FlatFiles` uses.
+ */
+export interface CheckDiagnostic {
+  /** Project-relative path; absent for global problems (compiler options, a missing lib). */
+  file?: string;
+  line: number;
+  column: number;
+  message: string;
+  /** TypeScript's code (2322 for TS2322). */
+  code: number;
+  category: DiagnosticCategory;
+}
+
+const CATEGORIES: Record<number, DiagnosticCategory> = { 0: 'warning', 1: 'error', 2: 'suggestion', 3: 'message' };
+
+export function toCheckDiagnostic(ts: typeof TS, diagnostic: TS.Diagnostic): CheckDiagnostic {
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+  const category = CATEGORIES[diagnostic.category] ?? 'error';
+  if (!diagnostic.file || diagnostic.start === undefined) return { line: 1, column: 1, message, code: diagnostic.code, category };
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+  return { file: diagnostic.file.fileName.replace(/^\//, ''), line: line + 1, column: character + 1, message, code: diagnostic.code, category };
+}
+
+/** `src/App.tsx(3,7): error TS2322: Type 'number' is not assignable to type 'string'.` — tsc's own format. */
+export function formatDiagnostic(diagnostic: CheckDiagnostic): string {
+  const where = diagnostic.file ? `${diagnostic.file}(${diagnostic.line},${diagnostic.column}): ` : '';
+  return `${where}${diagnostic.category} TS${diagnostic.code}: ${diagnostic.message}`;
+}
+
+/** Stable order (file, then position) and no duplicates — a file in two tsconfig projects reports once. */
+export function sortDiagnostics(diagnostics: CheckDiagnostic[]): CheckDiagnostic[] {
+  const seen = new Set<string>();
+  return diagnostics
+    .filter((d) => {
+      const key = `${d.file ?? ''}:${d.line}:${d.column}:${d.code}:${d.message}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => (a.file ?? '').localeCompare(b.file ?? '') || a.line - b.line || a.column - b.column);
+}

package/src/check/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@seanhogg/builderforce-webcontainers-core/check` — type-checking a project in
+ * memory. A separate entry point because it is typed against the `typescript`
+ * package (an optional peer dependency), which the rest of the core never needs.
+ */
+export { typecheckProject } from './typecheck.js';
+export type { TypecheckOptions, TypecheckResult } from './typecheck.js';
+export { toCheckDiagnostic, formatDiagnostic, sortDiagnostics } from './diagnostics.js';
+export type { CheckDiagnostic, DiagnosticCategory } from './diagnostics.js';
+export { acquireTypes, acquireExtendedConfigs } from './acquire.js';
+export type { FetchLike, FetchResponseLike, AcquireRequest, AcquireOptions } from './acquire.js';
+export { resolveCheckProjects, defaultCompilerOptions, createParseConfigHost } from './projects.js';
+export type { CheckProject } from './projects.js';
+export { createVirtualHost } from './compilerHost.js';
+export type { VirtualHostOptions } from './compilerHost.js';
+export { ambientShim, declaresModule, AMBIENT_SHIM_PATH, SHIMMED_TYPE_REFERENCES } from './shims.js';
+export {
+  TypeStore,
+  libBaseUrlFor,
+  typesPackageName,
+  dtsCandidates,
+  packageRequestUrl,
+  DEFAULT_TYPES_ORIGIN,
+  DEFAULT_NPM_BASE_URL,
+  TYPES_DIR,
+  LIB_DIR,
+} from './typeStore.js';
+export type { TypeSources } from './typeStore.js';

package/src/check/projects.ts

@@ -0,0 +1,149 @@
+import type * as TS from 'typescript';
+import type { VirtualFileSystem } from '../vfs.js';
+import { dirname, extname, join } from '../paths.js';
+import type { TypeStore } from './typeStore.js';
+
+/**
+ * Which programs to build, with which options, over which files — what `tsc -b`
+ * would derive from the project's tsconfig files.
+ *
+ * Vite's templates keep a root `tsconfig.json` holding only `references` (to
+ * `tsconfig.app.json` and `tsconfig.node.json`); each reference is its own
+ * program. With no tsconfig at all, the checker synthesises Vite's defaults for
+ * a React + TS app, so a generated project with no config still gets checked.
+ */
+export interface CheckProject {
+  /** The tsconfig this came from; undefined when synthesised. */
+  configPath?: string;
+  options: TS.CompilerOptions;
+  rootNames: string[];
+  /** Problems parsing the config itself. */
+  errors: readonly TS.Diagnostic[];
+}
+
+/** Tool configs (`vite.config.ts`…) describe the build, which runs elsewhere: not checked. */
+const TOOL_CONFIG = /(^|\/)(vite|vitest|svelte|tailwind|postcss|eslint|prettier|playwright)\.config\.[cm]?[jt]s$/;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+/** "No inputs were found in config file" — a reference covering only tool configs. */
+const NO_INPUTS = 18003;
+
+/** Vite's React + TS template, made strict-ish; what a project with no tsconfig gets. */
+export function defaultCompilerOptions(ts: typeof TS, jsxImportSource?: string): TS.CompilerOptions {
+  return {
+    target: ts.ScriptTarget.ES2020,
+    lib: ['lib.es2020.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    ...(jsxImportSource ? { jsxImportSource } : {}),
+    strict: true,
+    noFallthroughCasesInSwitch: true,
+    isolatedModules: true,
+    resolveJsonModule: true,
+    allowImportingTsExtensions: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    noEmit: true,
+  };
+}
+
+/** Options no in-browser check wants, whatever the config says: nothing is emitted. */
+function forCheck(options: TS.CompilerOptions): TS.CompilerOptions {
+  return {
+    ...options,
+    noEmit: true,
+    skipLibCheck: true,
+    composite: false,
+    incremental: false,
+    declaration: false,
+    declarationMap: false,
+    emitDeclarationOnly: false,
+    tsBuildInfoFile: undefined,
+  };
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let source = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (ch === '*' && pattern[i + 1] === '*' && pattern[i + 2] === '/') {
+      source += '(?:[^/]+/)*';
+      i += 2;
+    } else if (ch === '*') source += '[^/]*';
+    else if (ch === '?') source += '[^/]';
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** A tsconfig `include`/`exclude` spec as a matcher; a bare directory means everything under it. */
+function specMatcher(root: string, spec: string): RegExp {
+  let abs = join(root, spec);
+  const last = abs.slice(abs.lastIndexOf('/') + 1);
+  if (!/[*?]/.test(last) && !extname(last)) abs = `${abs === '/' ? '' : abs}/**/*`;
+  return globToRegExp(abs);
+}
+
+/** The ParseConfigHost the config parser reads through: the VFS plus fetched `extends` packages. */
+export function createParseConfigHost(fs: VirtualFileSystem, store: TypeStore): TS.ParseConfigHost {
+  return {
+    useCaseSensitiveFileNames: true,
+    fileExists: (path) => fs.isFile(path) || store.read(path) !== undefined,
+    readFile: (path) => fs.readText(path) ?? store.read(path),
+    readDirectory(rootDir, extensions, excludes, includes) {
+      const include = (includes ?? ['**/*']).map((spec) => specMatcher(rootDir, spec));
+      const exclude = (excludes ?? []).map((spec) => specMatcher(rootDir, spec));
+      return fs.list().filter((path) =>
+        extensions.some((ext) => path.endsWith(ext)) &&
+        !path.includes('/node_modules/') &&
+        include.some((re) => re.test(path)) &&
+        !exclude.some((re) => re.test(path)),
+      );
+    },
+  };
+}
+
+function parseConfig(ts: typeof TS, host: TS.ParseConfigHost, configPath: string): TS.ParsedCommandLine | { errors: TS.Diagnostic[] } {
+  const text = host.readFile(configPath) ?? '';
+  const json = ts.parseConfigFileTextToJson(configPath, text);
+  if (json.error) return { errors: [json.error] };
+  return ts.parseJsonConfigFileContent(json.config, host, dirname(configPath), undefined, configPath);
+}
+
+function referencedConfigs(ts: typeof TS, host: TS.ParseConfigHost, configPath: string): string[] {
+  const json = ts.parseConfigFileTextToJson(configPath, host.readFile(configPath) ?? '').config as { references?: Array<{ path?: unknown }>; files?: unknown[]; include?: unknown[] } | undefined;
+  const references = json?.references ?? [];
+  // A "solution" config — references and nothing of its own — is checked through its references.
+  const ownsFiles = (json?.files?.length ?? 0) > 0 || json?.include !== undefined;
+  if (!references.length || ownsFiles) return [];
+  return references
+    .map((ref) => (typeof ref.path === 'string' ? join(dirname(configPath), ref.path) : undefined))
+    .filter((path): path is string => !!path)
+    .map((path) => (path.endsWith('.json') ? path : join(path, 'tsconfig.json')))
+    .filter((path) => host.fileExists(path));
+}
+
+export function resolveCheckProjects(ts: typeof TS, fs: VirtualFileSystem, store: TypeStore, jsxImportSource?: string): CheckProject[] {
+  const host = createParseConfigHost(fs, store);
+  const root = ['/tsconfig.json', '/jsconfig.json'].find((path) => fs.isFile(path));
+
+  if (!root) {
+    const rootNames = fs.list().filter((path) => SOURCE_EXTENSIONS.some((ext) => path.endsWith(ext)) && !path.includes('/node_modules/') && !TOOL_CONFIG.test(path));
+    return rootNames.length ? [{ options: defaultCompilerOptions(ts, jsxImportSource), rootNames, errors: [] }] : [];
+  }
+
+  const configs = referencedConfigs(ts, host, root);
+  const projects: CheckProject[] = [];
+  for (const configPath of configs.length ? configs : [root]) {
+    const parsed = parseConfig(ts, host, configPath);
+    const errors = parsed.errors.filter((d) => d.code !== NO_INPUTS);
+    if (!('options' in parsed)) {
+      projects.push({ configPath, options: {}, rootNames: [], errors });
+      continue;
+    }
+    const rootNames = parsed.fileNames.filter((path) => !TOOL_CONFIG.test(path));
+    if (!rootNames.length && !errors.length) continue;
+    projects.push({ configPath, options: forCheck(parsed.options), rootNames, errors });
+  }
+  return projects;
+}

package/src/check/shims.ts

@@ -0,0 +1,88 @@
+/**
+ * Ambient declarations the checker adds, standing in for what a local install
+ * would provide:
+ *   • Vite's `vite/client` (`import.meta.env`, CSS/asset/`?raw` imports) and CRA's
+ *     `react-scripts` types. Shimmed rather than fetched: they are what every
+ *     generated app references, and a small local copy never fails to load;
+ *   • `.vue` / `.svelte` imports. Component internals are not type-checked yet;
+ *     importing one must not be an error;
+ *   • packages whose types could not be found, declared as `any` — a CDN miss is
+ *     not the user's type error.
+ *
+ * A pattern the project (or a fetched package) already declares is skipped: two
+ * declarations of `*.vue` with a default export each would be an error of ours.
+ */
+
+export const SHIM_DIR = '/__bfwc_shims__';
+export const AMBIENT_SHIM_PATH = `${SHIM_DIR}/ambient.d.ts`;
+/** What a shimmed type reference (`/// <reference types="vite/client" />`) resolves to. */
+export const EMPTY_TYPES_PATH = `${SHIM_DIR}/empty.d.ts`;
+export const SHIMMED_TYPE_REFERENCES: ReadonlySet<string> = new Set(['vite/client', 'react-scripts']);
+
+const STRING_DEFAULT = '{ const src: string; export default src; }';
+const ANY_DEFAULT = '{ const value: any; export default value; }';
+
+const MODULE_SHIMS: ReadonlyArray<[pattern: string, body: string]> = [
+  ['*.module.css', '{ const classes: { readonly [key: string]: string }; export default classes; }'],
+  ['*.module.scss', '{ const classes: { readonly [key: string]: string }; export default classes; }'],
+  ['*.css', '{}'],
+  ['*.scss', '{}'],
+  ['*.sass', '{}'],
+  ['*.less', '{}'],
+  ...['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico', 'bmp', 'woff', 'woff2', 'ttf', 'otf', 'eot', 'mp4', 'webm', 'mp3', 'wav', 'ogg', 'pdf', 'txt', 'md', 'wasm'].map(
+    (ext): [string, string] => [`*.${ext}`, STRING_DEFAULT],
+  ),
+  ['*?raw', STRING_DEFAULT],
+  ['*?url', STRING_DEFAULT],
+  ['*?inline', STRING_DEFAULT],
+  ['*.vue', ANY_DEFAULT],
+  ['*.svelte', ANY_DEFAULT],
+];
+
+const IMPORT_META = `interface ImportMetaEnv {
+  readonly [key: string]: any;
+  readonly MODE: string;
+  readonly BASE_URL: string;
+  readonly PROD: boolean;
+  readonly DEV: boolean;
+  readonly SSR: boolean;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+  readonly hot?: any;
+  readonly glob: any;
+}`;
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** True when any of `texts` declares `declare module '<pattern>'`. */
+export function declaresModule(texts: Iterable<string>, pattern: string): boolean {
+  const re = new RegExp(`declare\\s+module\\s+['"]${escapeRegExp(pattern)}['"]`);
+  for (const text of texts) if (re.test(text)) return true;
+  return false;
+}
+
+export interface AmbientShimOptions {
+  /** Declarations already loaded: the project's own `.d.ts` files and fetched package types. */
+  existing: string[];
+  /** Packages with no types found — declared as `any`. */
+  untyped: string[];
+}
+
+export function ambientShim(options: AmbientShimOptions): string {
+  const lines = [IMPORT_META];
+  // CRA reads `process.env.REACT_APP_*`; @types/node, when loaded, declares it properly.
+  if (!options.existing.some((text) => /declare\s+var\s+process\b/.test(text))) {
+    lines.push('declare var process: { env: { readonly [key: string]: string | undefined; readonly NODE_ENV: string } };');
+  }
+  for (const [pattern, body] of MODULE_SHIMS) {
+    if (!declaresModule(options.existing, pattern)) lines.push(`declare module ${JSON.stringify(pattern)} ${body}`);
+  }
+  for (const name of options.untyped) {
+    lines.push(`declare module ${JSON.stringify(name)};`);
+    lines.push(`declare module ${JSON.stringify(`${name}/*`)};`);
+  }
+  return lines.join('\n') + '\n';
+}