@remix-run/assets 0.2.0 → 0.4.0

package/src/lib/injected-packages.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { getFilePathDirectory, normalizeFilePath } from './paths.ts'
+
+type ResolvedInjectedPackage = {
+  packageJsonPath: string
+  packageRoot: string
+}
+
+const injectedPackageNames = ['@oxc-project/runtime'] as const
+const injectedPackagesBasePath = '/__@remix/injected'
+
+const resolvedInjectedPackages = new Map<string, ResolvedInjectedPackage>()
+
+export function isInjectedPackageFilePath(filePath: string): boolean {
+  let normalizedFilePath = normalizeFilePath(filePath)
+
+  for (let packageName of injectedPackageNames) {
+    let packageRoot = getResolvedInjectedPackage(packageName).packageRoot
+    if (normalizedFilePath === packageRoot || normalizedFilePath.startsWith(`${packageRoot}/`)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+export function getInjectedPackageRouteConfigs(): {
+  fileMap: Record<string, string>
+  rootDir: string
+}[] {
+  return injectedPackageNames.map((packageName) => {
+    let { packageRoot } = getResolvedInjectedPackage(packageName)
+
+    return {
+      fileMap: {
+        [getInjectedPackageRoutePattern(packageName)]: `${packageName}/*path`,
+      },
+      rootDir: getInjectedPackageRouteRoot(packageRoot, packageName),
+    }
+  })
+}
+
+export function getInjectedPackageNameForSpecifier(specifier: string): string | null {
+  for (let packageName of injectedPackageNames) {
+    if (specifier === packageName || specifier.startsWith(`${packageName}/`)) {
+      return packageName
+    }
+  }
+
+  return null
+}
+
+export function mayContainInjectedPackageSpecifier(sourceText: string): boolean {
+  return injectedPackageNames.some((packageName) => sourceText.includes(packageName))
+}
+
+export function maskAuthoredInjectedPackageSpecifier(specifier: string): string | null {
+  let packageName = getInjectedPackageNameForSpecifier(specifier)
+  if (!packageName) return null
+
+  let maskedPackageName = getMaskedInjectedPackageName(packageName)
+  return `${maskedPackageName}${specifier.slice(packageName.length)}`
+}
+
+export function restoreAuthoredInjectedPackageSpecifier(specifier: string): string | null {
+  for (let packageName of injectedPackageNames) {
+    let maskedPackageName = getMaskedInjectedPackageName(packageName)
+    if (specifier === maskedPackageName) {
+      return packageName
+    }
+    if (specifier.startsWith(`${maskedPackageName}/`)) {
+      return `${packageName}${specifier.slice(maskedPackageName.length)}`
+    }
+  }
+
+  return null
+}
+
+function getMaskedInjectedPackageName(packageName: string): string {
+  return `~${packageName.slice(1)}`
+}
+
+export function getInjectedPackageImporterPath(): string {
+  return normalizeFilePath(fileURLToPath(import.meta.url))
+}
+
+function getResolvedInjectedPackage(packageName: string): ResolvedInjectedPackage {
+  let existing = resolvedInjectedPackages.get(packageName)
+  if (existing) return existing
+
+  let packageJsonUrl = import.meta.resolve(`${packageName}/package.json`)
+  let packageJsonPath = normalizeFilePath(fs.realpathSync(fileURLToPath(packageJsonUrl)))
+
+  let resolvedInjectedPackage = {
+    packageJsonPath,
+    packageRoot: normalizeFilePath(fs.realpathSync(getFilePathDirectory(packageJsonPath))),
+  }
+
+  resolvedInjectedPackages.set(packageName, resolvedInjectedPackage)
+  return resolvedInjectedPackage
+}
+
+function getInjectedPackageRoutePattern(packageName: string): string {
+  return `${injectedPackagesBasePath}/${packageName}/*path`
+}
+
+function getInjectedPackageRouteRoot(packageRoot: string, packageName: string): string {
+  let routeRoot = packageRoot
+
+  for (let _segment of packageName.split('/')) {
+    routeRoot = getFilePathDirectory(routeRoot)
+  }
+
+  return routeRoot
+}

package/src/lib/paths.ts

@@ -57,6 +57,34 @@ export function getFilePathDirectory(filePath: string): string {
   return path.posix.dirname(normalizeWindowsPath(filePath))
 }
 
+export function getRelativeFilePath(fromPath: string, toPath: string): string {
+  let normalizedFromPath = normalizeFilePath(fromPath)
+  let normalizedToPath = normalizeFilePath(toPath)
+
+  if (normalizedFromPath.startsWith('//') || normalizedToPath.startsWith('//')) {
+    return normalizeWindowsPath(
+      path.win32.relative(
+        normalizedFromPath.replace(/\//g, '\\'),
+        normalizedToPath.replace(/\//g, '\\'),
+      ),
+    )
+  }
+
+  if (
+    windowsDriveLetterRE.test(normalizedFromPath) ||
+    windowsDriveLetterRE.test(normalizedToPath)
+  ) {
+    return normalizeWindowsPath(
+      path.win32.relative(
+        normalizedFromPath.replace(/\//g, '\\'),
+        normalizedToPath.replace(/\//g, '\\'),
+      ),
+    )
+  }
+
+  return path.posix.relative(normalizedFromPath, normalizedToPath)
+}
+
 export function getFilePathBaseName(filePath: string): string {
   return path.posix.basename(normalizeWindowsPath(filePath))
 }

package/src/lib/routes.ts

@@ -1,22 +1,31 @@
-import * as path from 'node:path'
 import { RoutePattern } from '@remix-run/route-pattern'
+import { createHref } from '@remix-run/route-pattern/href'
+import { createMatcher, type Matcher } from '@remix-run/route-pattern/match'
 
 import {
+  getRelativeFilePath,
   isAbsoluteFilePath,
   normalizeFilePath,
   normalizePathname,
   resolveFilePath,
 } from './paths.ts'
 
-export interface AssetRouteDefinition {
+interface AssetRouteDefinition {
   urlPattern: string
   filePattern: string
 }
 
+interface RouteConfig {
+  fileMap: Readonly<Record<string, string>>
+  rootDir: string
+}
+
 interface CompiledRoute {
   rootDir: string
   urlPattern: RoutePattern
+  urlMatcher: Matcher
   filePattern: RoutePattern
+  fileMatcher: Matcher
 }
 
 export interface CompiledRoutes {
@@ -34,21 +43,26 @@ function normalizeFilePattern(pattern: string): string {
   return normalizePathname(pattern)
 }
 
-export function compileRoutes(options: {
-  fileMap: Readonly<Record<string, string>>
-  rootDir: string
-}): CompiledRoutes {
-  if (Object.keys(options.fileMap).length === 0) {
+export function compileRoutes(
+  basePath: string,
+  routeConfigs: readonly RouteConfig[],
+): CompiledRoutes {
+  if (routeConfigs.every((routeConfig) => Object.keys(routeConfig.fileMap).length === 0)) {
     throw new Error('createAssetServer() requires at least one configured fileMap entry.')
   }
 
-  let compiledRoutes = Object.entries(options.fileMap).map(([urlPattern, filePattern]) =>
-    compileRoute(
-      {
-        urlPattern,
-        filePattern,
-      },
-      { rootDir: options.rootDir },
+  let compiledRoutes = routeConfigs.flatMap((routeConfig) =>
+    Object.entries(routeConfig.fileMap).map(([urlPattern, filePattern]) =>
+      compileRoute(
+        {
+          filePattern,
+          urlPattern,
+        },
+        {
+          basePath,
+          rootDir: routeConfig.rootDir,
+        },
+      ),
     ),
   )
 
@@ -57,9 +71,9 @@ export function compileRoutes(options: {
       let normalizedPathname = normalizePathname(pathname)
 
       for (let route of compiledRoutes) {
-        let match = route.urlPattern.match(`http://remix.run${normalizedPathname}`)
+        let match = route.urlMatcher.match(`http://remix.run${normalizedPathname}`)
         if (!match) continue
-        let relativeFilePath = route.filePattern.href(match.params).replace(/^\/+/, '')
+        let relativeFilePath = createHref(route.filePattern, match.params).replace(/^\/+/, '')
         return resolveFilePath(route.rootDir, relativeFilePath)
       }
 
@@ -69,11 +83,10 @@ export function compileRoutes(options: {
       let normalizedFilePath = normalizeFilePath(filePath)
 
       for (let route of compiledRoutes) {
-        let relativeFilePath = getRelativeFilePath(normalizedFilePath, route.rootDir)
-        if (relativeFilePath === null) continue
-        let match = route.filePattern.ast.pathname.match(relativeFilePath)
+        let relativeFilePath = getRelativeFilePath(route.rootDir, normalizedFilePath)
+        let match = route.fileMatcher.match(`http://remix.run/${relativeFilePath}`)
         if (!match) continue
-        return normalizePathname(route.urlPattern.href(getPathnameParams(route.filePattern, match)))
+        return normalizePathname(createHref(route.urlPattern, match.params))
       }
 
       return null
@@ -84,14 +97,19 @@ export function compileRoutes(options: {
 function compileRoute(
   route: AssetRouteDefinition,
   options: {
+    basePath: string
     rootDir: string
   },
 ): CompiledRoute {
-  let urlPatternSource = normalizePathname(route.urlPattern)
+  let basePath = normalizePathname(options.basePath).replace(/\/+$/, '') || '/'
+  let relativeUrlPattern = normalizePathname(route.urlPattern)
+  let urlPatternSource = normalizePathname(
+    `${basePath.replace(/\/+$/, '')}/${relativeUrlPattern.replace(/^\/+/, '')}`,
+  )
   let filePatternSource = normalizeFilePattern(route.filePattern)
 
-  let urlPattern = new RoutePattern(urlPatternSource)
-  let filePattern = new RoutePattern(filePatternSource)
+  let urlPattern = RoutePattern.parse(urlPatternSource)
+  let filePattern = RoutePattern.parse(filePatternSource)
 
   validateNoUnnamedWildcards(urlPattern, 'URL')
   validateNoUnnamedWildcards(filePattern, 'File')
@@ -100,42 +118,30 @@ function compileRoute(
   return {
     rootDir: normalizeFilePath(options.rootDir).replace(/\/+$/, ''),
     urlPattern,
+    urlMatcher: createMatcher(urlPattern),
     filePattern,
+    fileMatcher: createMatcher(stripDotSegments(filePatternSource)),
   }
 }
 
-function getRelativeFilePath(filePath: string, rootDir: string): string | null {
-  if (filePath[1] === ':' && rootDir[1] === ':' && filePath[0] !== rootDir[0]) return null
-  return path.posix.relative(rootDir, filePath)
-}
-
-function getPathnameParams(
-  pattern: RoutePattern,
-  match: Array<{ name: string; type: ':' | '*'; value: string }>,
-): Record<string, string | undefined> {
-  let params: Record<string, string | undefined> = {}
-
-  for (let param of pattern.ast.pathname.params) {
-    if (param.name === '*') continue
-    params[param.name] = undefined
-  }
+function stripDotSegments(pattern: string): string {
+  let segments: string[] = []
 
-  for (let param of match) {
-    if (param.name === '*') continue
-    params[param.name] = param.value
+  for (let segment of pattern.split('/')) {
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') {
+      segments.pop()
+      continue
+    }
+    segments.push(segment)
   }
 
-  return params
+  return segments.join('/')
 }
 
 function validateRoutePatterns(urlPattern: RoutePattern, filePattern: RoutePattern): void {
-  let urlParams = urlPattern.ast.pathname.params.map(
-    (param: { name: string; type: ':' | '*' }) => `${param.type}:${param.name}`,
-  )
-  let fileParams = filePattern.ast.pathname.params.map(
-    (param: { name: string; type: ':' | '*' }) => `${param.type}:${param.name}`,
-  )
-
+  let urlParams = getPathnameParams(urlPattern)
+  let fileParams = getPathnameParams(filePattern)
   if (urlParams.length !== fileParams.length) {
     throw new Error(
       `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
@@ -143,7 +149,9 @@ function validateRoutePatterns(urlPattern: RoutePattern, filePattern: RoutePatte
   }
 
   for (let i = 0; i < urlParams.length; i++) {
-    if (urlParams[i] !== fileParams[i]) {
+    let urlParam = urlParams[i]
+    let fileParam = fileParams[i]
+    if (urlParam.type !== fileParam.type || urlParam.name !== fileParam.name) {
       throw new Error(
         `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
       )
@@ -152,13 +160,17 @@ function validateRoutePatterns(urlPattern: RoutePattern, filePattern: RoutePatte
 }
 
 function validateNoUnnamedWildcards(pattern: RoutePattern, label: string): void {
-  if (
-    pattern.ast.pathname.params.some(
-      (param: { name: string; type: ':' | '*' }) => param.type === '*' && param.name === '*',
-    )
-  ) {
+  if (pattern.pathname.tokens.some((token) => token.type === '*' && token.name === '*')) {
     throw new Error(
       `${label} route patterns must use named wildcards for reversible mapping.\nPattern: ${pattern}`,
     )
   }
 }
+
+type PathnameParam = Extract<RoutePattern['pathname']['tokens'][number], { type: ':' | '*' }>
+
+function getPathnameParams(pattern: RoutePattern): Array<PathnameParam> {
+  return pattern.pathname.tokens.filter(
+    (token): token is PathnameParam => token.type === ':' || token.type === '*',
+  )
+}

package/src/lib/scripts/compiler.ts

@@ -66,6 +66,7 @@ type ScriptCompilerOptions = {
   external: string[]
   fingerprintAssets: boolean
   isAllowed(absolutePath: string): boolean
+  isDenied(absolutePath: string): boolean
   minify: boolean
   onWatchDirectoriesChange?: (delta: { add: string[]; remove: string[] }) => void
   rootDir: string
@@ -117,8 +118,14 @@ export function createScriptCompiler(options: ScriptCompilerOptions): ScriptComp
     extensionAlias: resolverExtensionAlias,
     extensions: resolverExtensions,
     mainFields: ['browser', 'module', 'main'],
+    symlinks: false,
     tsconfig: 'auto',
   })
+  let resolveModulePathOptions = {
+    isAllowed: resolvedOptions.isAllowed,
+    isDenied: resolvedOptions.isDenied,
+    routes: resolvedOptions.routes,
+  }
   let resolveInFlightByCacheKey = new Map<string, Promise<ResolvedModule>>()
   let emitInFlightByCacheKey = new Map<string, Promise<EmittedModule>>()
 
@@ -138,7 +145,9 @@ export function createScriptCompiler(options: ScriptCompilerOptions): ScriptComp
   let resolveArgs: ResolveArgs = {
     isAllowed: resolvedOptions.isAllowed,
     isWatchIgnored,
-    resolveModulePath,
+    resolveModulePath(absolutePath) {
+      return resolveModulePath(absolutePath, resolveModulePathOptions)
+    },
     resolverFactory,
     routes: resolvedOptions.routes,
   }
@@ -253,7 +262,7 @@ export function createScriptCompiler(options: ScriptCompilerOptions): ScriptComp
   }
 
   function resolveServedScriptOrThrow(absolutePath: string): ResolveModuleResult {
-    let resolvedModule = resolveModulePath(absolutePath)
+    let resolvedModule = resolveModulePath(absolutePath, resolveModulePathOptions)
     if (!resolvedModule) {
       throw createAssetServerCompilationError(`File not found: ${absolutePath}`, {
         code: 'FILE_NOT_FOUND',
@@ -548,11 +557,19 @@ function shouldClearResolverCacheForFileEvent(filePath: string, event: ModuleWat
   return event !== 'change' || isPackageJsonPath(filePath) || isTsconfigPath(filePath)
 }
 
-function resolveModulePath(absolutePath: string): ResolveModuleResult | null {
+function resolveModulePath(
+  absolutePath: string,
+  options: {
+    isAllowed(absolutePath: string): boolean
+    isDenied(absolutePath: string): boolean
+    routes: CompiledRoutes
+  },
+): ResolveModuleResult | null {
+  let candidateIdentityPath = normalizeFilePath(absolutePath)
   let resolvedPath: string
 
   try {
-    resolvedPath = normalizeFilePath(fs.realpathSync(normalizeFilePath(absolutePath)))
+    resolvedPath = normalizeFilePath(fs.realpathSync(candidateIdentityPath))
   } catch (error) {
     if (isNoEntityError(error)) return null
     throw error
@@ -563,11 +580,32 @@ function resolveModulePath(absolutePath: string): ResolveModuleResult | null {
   }
 
   return {
-    identityPath: resolvedPath,
+    identityPath: getModuleIdentityPath(candidateIdentityPath, resolvedPath, options),
     resolvedPath,
   }
 }
 
+function getModuleIdentityPath(
+  candidateIdentityPath: string,
+  resolvedPath: string,
+  options: {
+    isAllowed(absolutePath: string): boolean
+    isDenied(absolutePath: string): boolean
+    routes: CompiledRoutes
+  },
+): string {
+  if (candidateIdentityPath === resolvedPath) return resolvedPath
+  if (!containsNodeModulesPathSegment(candidateIdentityPath)) return resolvedPath
+  if (!options.routes.toUrlPathname(candidateIdentityPath)) return resolvedPath
+  if (!options.isAllowed(candidateIdentityPath)) return resolvedPath
+  if (options.isDenied(resolvedPath)) return resolvedPath
+  return candidateIdentityPath
+}
+
+function containsNodeModulesPathSegment(filePath: string): boolean {
+  return filePath.split('/').includes('node_modules')
+}
+
 function resolveActualPath(identityPath: string): string | null {
   try {
     return normalizeFilePath(fs.realpathSync(identityPath))

package/src/lib/scripts/resolve.ts

@@ -7,6 +7,11 @@ import {
   isAssetServerCompilationError,
 } from '../compilation-error.ts'
 import type { AssetServerCompilationError } from '../compilation-error.ts'
+import {
+  getInjectedPackageNameForSpecifier,
+  getInjectedPackageImporterPath,
+  restoreAuthoredInjectedPackageSpecifier,
+} from '../injected-packages.ts'
 import type { ModuleRecord, ModuleTracking } from '../module-store.ts'
 import { normalizeFilePath } from '../paths.ts'
 import type { CompiledRoutes } from '../routes.ts'
@@ -81,6 +86,11 @@ type ResolvedSpec = {
   specifier: string
 }
 
+type NormalizedSpecifierResolution = {
+  importerPath: string
+  specifier: string
+}
+
 export async function resolveModule(
   record: ScriptRecord,
   transformed: TransformedModule,
@@ -95,7 +105,7 @@ export async function resolveModule(
       transformed.unresolvedImports.length > 0
         ? await batchResolveSpecifiers(
             getUniqueSpecifiers(transformed.unresolvedImports),
-            transformed.resolvedPath,
+            transformed.identityPath,
             args.resolverFactory,
           )
         : new Map<string, ResolvedSpec>()
@@ -109,9 +119,10 @@ export async function resolveModule(
   let deps = new Set<string>()
 
   for (let unresolved of transformed.unresolvedImports) {
+    let displaySpecifier = getDisplayImportSpecifier(unresolved.specifier)
     let trackedResolution = getTrackedRelativeImportResolution(
       transformed.importerDir,
-      unresolved.specifier,
+      displaySpecifier,
       args.isWatchIgnored,
     )
 
@@ -119,7 +130,7 @@ export async function resolveModule(
     if (!resolvedSpec?.absolutePath) {
       return failResolve(
         createAssetServerCompilationError(
-          `Failed to resolve import "${unresolved.specifier}" in ${transformed.resolvedPath}. ` +
+          `Failed to resolve import "${displaySpecifier}" in ${transformed.resolvedPath}. ` +
             `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
           {
             code: 'IMPORT_RESOLUTION_FAILED',
@@ -136,7 +147,7 @@ export async function resolveModule(
     if (!resolvedImport) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedSpec.absolutePath}", is not a supported script file. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedSpec.absolutePath}", is not a supported script file. ` +
             `Supported extensions are ${supportedScriptExtensions.join(', ')}.`,
           {
             code: 'IMPORT_NOT_SUPPORTED',
@@ -152,7 +163,7 @@ export async function resolveModule(
     if (!args.isAllowed(resolvedImport.identityPath)) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is not allowed by the asset server allow/deny configuration. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is not allowed by the asset server allow/deny configuration. ` +
             `Add a matching allow rule for this file path, remove a conflicting deny rule for this file path, or mark this import as external.`,
           {
             code: 'IMPORT_NOT_ALLOWED',
@@ -169,7 +180,7 @@ export async function resolveModule(
     if (!stableUrlPathname) {
       return failResolve(
         createAssetServerCompilationError(
-          `Import "${unresolved.specifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is outside all configured fileMap entries. ` +
+          `Import "${displaySpecifier}" in ${transformed.resolvedPath}, resolved to "${resolvedImport.identityPath}", is outside all configured fileMap entries. ` +
             `Add a matching fileMap entry for this file path, or mark this import as external.`,
           {
             code: 'IMPORT_OUTSIDE_FILE_MAP',
@@ -185,8 +196,10 @@ export async function resolveModule(
     deps.add(resolvedImport.identityPath)
 
     if (transformed.packageSpecifiers.includes(unresolved.specifier)) {
-      let packageJsonPath =
-        resolvedSpec.packageJsonPath ?? findNearestPackageJsonPath(resolvedImport.resolvedPath)
+      let packageJsonPath = resolvePackageJsonPath(
+        resolvedSpec.packageJsonPath,
+        resolvedImport.resolvedPath,
+      )
       if (packageJsonPath && !args.isWatchIgnored(packageJsonPath)) {
         trackedFiles.add(packageJsonPath)
       }
@@ -224,6 +237,25 @@ export async function resolveModule(
   }
 }
 
+function resolvePackageJsonPath(
+  packageJsonPath: string | null,
+  resolvedPath: string,
+): string | null {
+  return (
+    (packageJsonPath ? resolveExistingPath(packageJsonPath) : null) ??
+    findNearestPackageJsonPath(resolvedPath)
+  )
+}
+
+function resolveExistingPath(filePath: string): string | null {
+  try {
+    return normalizeFilePath(fs.realpathSync(filePath))
+  } catch (error) {
+    if (isNoEntityError(error)) return null
+    throw error
+  }
+}
+
 function findNearestPackageJsonPath(filePath: string): string | null {
   let directory = path.dirname(filePath)
 
@@ -239,6 +271,17 @@ function findNearestPackageJsonPath(filePath: string): string | null {
   }
 }
 
+function isNoEntityError(
+  error: unknown,
+): error is NodeJS.ErrnoException & { code: 'ENOENT' | 'ENOTDIR' } {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    ((error as NodeJS.ErrnoException).code === 'ENOENT' ||
+      (error as NodeJS.ErrnoException).code === 'ENOTDIR')
+  )
+}
+
 function isRelativeImportSpecifier(specifier: string): boolean {
   return specifier.startsWith('./') || specifier.startsWith('../')
 }
@@ -323,11 +366,17 @@ async function batchResolveSpecifiers(
 
   try {
     for (let specifier of specifiers) {
-      let resolutionResult = await resolverFactory.resolveFileAsync(importerPath, specifier)
+      let normalizedResolution = normalizeSpecifierResolution(specifier, importerPath)
+      let resolutionResult = await resolverFactory.resolveFileAsync(
+        normalizedResolution.importerPath,
+        normalizedResolution.specifier,
+      )
       if (resolutionResult.error) {
         throw createAssetServerCompilationError(
-          `Failed to resolve import "${specifier}" in ${importerPath}. ` +
-            `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
+          normalizedResolution.importerPath === getInjectedPackageImporterPath()
+            ? `Failed to resolve injected import "${specifier}" from asset server.`
+            : `Failed to resolve import "${normalizedResolution.specifier}" in ${normalizedResolution.importerPath}. ` +
+                `Ensure it resolves to a file within the configured asset server fileMap, or mark it as external.`,
           {
             code: 'IMPORT_RESOLUTION_FAILED',
           },
@@ -370,6 +419,35 @@ function formatUnknownError(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+function normalizeSpecifierResolution(
+  specifier: string,
+  importerPath: string,
+): NormalizedSpecifierResolution {
+  let authoredInjectedPackageSpecifier = restoreAuthoredInjectedPackageSpecifier(specifier)
+  if (authoredInjectedPackageSpecifier) {
+    return {
+      importerPath,
+      specifier: authoredInjectedPackageSpecifier,
+    }
+  }
+
+  if (getInjectedPackageNameForSpecifier(specifier)) {
+    return {
+      importerPath: getInjectedPackageImporterPath(),
+      specifier,
+    }
+  }
+
+  return {
+    importerPath,
+    specifier,
+  }
+}
+
+function getDisplayImportSpecifier(specifier: string): string {
+  return restoreAuthoredInjectedPackageSpecifier(specifier) ?? specifier
+}
+
 function failResolve(
   error: unknown,
   trackedFiles: ReadonlySet<string>,