[JEWEL-1058] Improve DefaultImageSourceResolver

AlexVanGogen · AlexVanGogen · commit b7d189be125e · 2025-11-11T18:07:23.000+01:00
- Support absolute and relative paths
- Abstract different approaches
 to resolve a given string
- Provide an option to not log resolve failures --
 we don't want to pollute logs in editor+preview mode
 when resolve works on each source file edit
- Make `ImageSourceResolver.resolve` return null
if a given string cannot be resolved.
Making Coil try to render something by an obscure string
can lead to unexpected behavior (exceptions at least)
diff --git a/platform/jewel/markdown/core/api-dump-experimental.txt b/platform/jewel/markdown/core/api-dump-experimental.txt
@@ -355,7 +355,33 @@ f:org.jetbrains.jewel.markdown.processing.ProcessingUtilKt
 - render(org.jetbrains.jewel.markdown.MarkdownBlock,Z,kotlin.jvm.functions.Function1,kotlin.jvm.functions.Function0,androidx.compose.ui.Modifier,androidx.compose.runtime.Composer,I):V
 - renderThematicBreak(org.jetbrains.jewel.markdown.rendering.MarkdownStyling$ThematicBreak,Z,androidx.compose.ui.Modifier,androidx.compose.runtime.Composer,I):V
 *:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver
+- *sf:Companion:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$Companion
 - a:resolve(java.lang.String):java.lang.String
+*f:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$Companion
+- f:create(java.nio.file.Path,Z):org.jetbrains.jewel.markdown.rendering.ImageSourceResolver
+- f:create(java.util.List,Z):org.jetbrains.jewel.markdown.rendering.ImageSourceResolver
+- bs:create$default(org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$Companion,java.util.List,Z,I,java.lang.Object):org.jetbrains.jewel.markdown.rendering.ImageSourceResolver
+*:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability
+- a:getDebugName():java.lang.String
+- a:resolve(java.lang.String):java.lang.String
+*f:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability$PlainUri
+- org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability
+- sf:$stable:I
+- sf:INSTANCE:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability$PlainUri
+- getDebugName():java.lang.String
+- resolve(java.lang.String):java.lang.String
+*f:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability$RelativePath
+- org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability
+- sf:$stable:I
+- <init>(java.nio.file.Path):V
+- getDebugName():java.lang.String
+- resolve(java.lang.String):java.lang.String
+*f:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability$RelativePathInResources
+- org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability
+- sf:$stable:I
+- sf:INSTANCE:org.jetbrains.jewel.markdown.rendering.ImageSourceResolver$ResolveCapability$RelativePathInResources
+- getDebugName():java.lang.String
+- resolve(java.lang.String):java.lang.String
 f:org.jetbrains.jewel.markdown.rendering.ImageSourceResolverKt
 - *sf:getLocalMarkdownImageSourceResolver():androidx.compose.runtime.ProvidableCompositionLocal
 *:org.jetbrains.jewel.markdown.rendering.InlineMarkdownRenderer
diff --git a/platform/jewel/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/rendering/ImageSourceResolver.kt b/platform/jewel/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/rendering/ImageSourceResolver.kt
@@ -4,7 +4,9 @@ package org.jetbrains.jewel.markdown.rendering
 import androidx.compose.runtime.ProvidableCompositionLocal
 import androidx.compose.runtime.staticCompositionLocalOf
 import java.net.URI
+import java.nio.file.Path
 import org.jetbrains.annotations.ApiStatus
+import org.jetbrains.annotations.VisibleForTesting
 import org.jetbrains.jewel.foundation.ExperimentalJewelApi
 import org.jetbrains.jewel.foundation.util.myLogger
 
@@ -27,35 +29,134 @@ public interface ImageSourceResolver {
      *
      * @param rawDestination The raw destination string from the Markdown, e.g., "my-image.png" or
      *   "https://example.com/image.png".
-     * @return A fully-qualified, loadable path to the image, which can be consumed by an image loader.
+     * @return A fully-qualified, loadable path to the image, which can be consumed by an image loader, or `null` if the
+     *   image could not be resolved.
      */
-    public fun resolve(rawDestination: String): String
+    public fun resolve(rawDestination: String): String?
+
+    public companion object {
+        @VisibleForTesting
+        internal val defaultCapabilities =
+            setOf(
+                ResolveCapability.PlainUri,
+                ResolveCapability.RelativePathInResources(),
+                ResolveCapability.AbsolutePath,
+            )
+
+        /**
+         * Creates [ImageSourceResolver] that can resolve image links in Markdown files if they are either:
+         * - plain URIs, e.g., `https://example.com/image.png` or `file:///image.png`
+         * - absolute paths, e.g., `/image.png`
+         * - relative paths in the current classloader's resources, e.g., `/images/my-image.png`
+         * - relative paths relative to a given root directory [rootDir], e.g., `../images/my-image.png`
+         *
+         * If [logResolveFailure] is true, logs any failures to resolve image sources.
+         */
+        public fun create(rootDir: Path, logResolveFailure: Boolean): ImageSourceResolver =
+            create(
+                buildSet {
+                    addAll(defaultCapabilities)
+                    add(ResolveCapability.RelativePath(rootDir))
+                },
+                logResolveFailure,
+            )
+
+        /**
+         * Creates [ImageSourceResolver] that can resolve image links in Markdown files according to provided
+         * [resolveCapabilities].
+         *
+         * If [logResolveFailure] is true, logs any failures to resolve image sources.
+         */
+        public fun create(
+            resolveCapabilities: Set<ResolveCapability> = defaultCapabilities,
+            logResolveFailure: Boolean = true,
+        ): ImageSourceResolver = DefaultImageSourceResolver(resolveCapabilities, logResolveFailure)
+    }
+
+    /** Provides a list of capabilities that the default [ImageSourceResolver] implementation supports. */
+    @ApiStatus.Experimental
+    @ExperimentalJewelApi
+    public sealed interface ResolveCapability {
+        /** Resolves a raw image destination string from a Markdown file into a fully-qualified, loadable path. */
+        public fun resolve(rawDestination: String): String?
+
+        /** Represents the ability to resolve plain URIs as-is. */
+        @ApiStatus.Experimental
+        @ExperimentalJewelApi
+        public object PlainUri : ResolveCapability {
+            override fun toString(): String = "PlainUri"
+
+            override fun resolve(rawDestination: String): String? {
+                val uri = runCatching { URI.create(rawDestination) }.getOrNull() ?: return null
+                return if (uri.isAbsolute) rawDestination else null
+            }
+        }
+
+        /**
+         * Represents the ability to resolve relative paths in the [resourceClass] classloader's resources, or in the
+         * current classloader's resources if [resourceClass] is `null`.
+         */
+        @ApiStatus.Experimental
+        @ExperimentalJewelApi
+        public class RelativePathInResources(val resourceClass: Class<*>? = null) : ResolveCapability {
+            override fun toString(): String = "RelativePathInResources"
+
+            override fun resolve(rawDestination: String): String? =
+                (resourceClass ?: javaClass).classLoader.getResource(rawDestination.removePrefix("/"))?.toExternalForm()
+        }
+
+        /** Represents the ability to resolve absolute paths as-is. */
+        public object AbsolutePath : ResolveCapability {
+            override fun resolve(rawDestination: String): String? {
+                val rawPath = Path.of(rawDestination)
+                if (rawPath.isAbsolute) return rawDestination
+                return null
+            }
+        }
+
+        /** Represents the ability to resolve relative paths relative to a given root directory [rootDir]. */
+        @ApiStatus.Experimental
+        @ExperimentalJewelApi
+        public class RelativePath(private val rootDir: Path) : ResolveCapability {
+            override fun resolve(rawDestination: String): String? {
+                val rawPath = Path.of(rawDestination)
+                // don't resolve absolute paths, it's not this resolver's capability
+                if (rawPath.isAbsolute) return null
+
+                val normalizedRoot = runCatching { rootDir.toAbsolutePath().normalize() }.getOrNull() ?: return null
+
+                val resolved = runCatching { normalizedRoot.resolve(rawPath).normalize() }.getOrNull() ?: return null
+
+                return resolved.toString()
+            }
+
+            override fun toString(): String = "RelativePath(rootDir=$rootDir)"
+        }
+    }
 }
 
 /**
- * The default implementation of [ImageSourceResolver].
- *
- * Resolves full URIs as-is and attempts to find relative paths in the current classloader's resources.
+ * The default implementation of [ImageSourceResolver] that can resolve image links in Markdown files according to
+ * provided [resolveCapabilities].
  *
+ * @param resolveCapabilities A list of [ImageSourceResolver.ResolveCapability]s that this resolver can support.
+ * @param logResolveFailure Whether to log any failures to resolve image sources.
  * @see ImageSourceResolver
  */
-internal object DefaultImageSourceResolver : ImageSourceResolver {
-    override fun resolve(rawDestination: String): String {
-        val uri = URI.create(rawDestination)
-        if (uri.scheme != null) return rawDestination
-
-        val resourceUrl = javaClass.classLoader.getResource(rawDestination.removePrefix("/"))
-
-        if (resourceUrl == null) {
+internal class DefaultImageSourceResolver(
+    private val resolveCapabilities: Set<ImageSourceResolver.ResolveCapability> =
+        ImageSourceResolver.defaultCapabilities,
+    private val logResolveFailure: Boolean = true,
+) : ImageSourceResolver {
+    override fun resolve(rawDestination: String): String? {
+        val result = resolveCapabilities.firstNotNullOfOrNull { it.resolve(rawDestination) }
+        if (result == null && logResolveFailure) {
             myLogger()
                 .warn(
-                    "Markdown image '$rawDestination' expected at classpath '$rawDestination' but not found. " +
-                        "Please ensure it's in your 'src/main/resources/' folder."
+                    "Failed to resolve image source: $rawDestination. Supported capabilities: ${resolveCapabilities.joinToString()}"
                 )
-            return rawDestination // This will cause Coil to fail and not render anything.
         }
-
-        return resourceUrl.toExternalForm()
+        return result
     }
 }
 
@@ -84,5 +185,5 @@ internal object DefaultImageSourceResolver : ImageSourceResolver {
 @ExperimentalJewelApi
 public val LocalMarkdownImageSourceResolver: ProvidableCompositionLocal<ImageSourceResolver> =
     staticCompositionLocalOf {
-        DefaultImageSourceResolver
+        ImageSourceResolver.create()
     }
diff --git a/platform/jewel/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/TestUtils.kt b/platform/jewel/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/TestUtils.kt
@@ -1,5 +1,7 @@
 package org.jetbrains.jewel.markdown
 
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.contract
 import org.jetbrains.jewel.foundation.code.MimeType
 import org.jetbrains.jewel.markdown.MarkdownBlock.BlockQuote
 import org.jetbrains.jewel.markdown.MarkdownBlock.CodeBlock
@@ -15,6 +17,12 @@ import org.jetbrains.jewel.markdown.MarkdownBlock.Paragraph
 import org.jetbrains.jewel.markdown.MarkdownBlock.ThematicBreak
 import org.junit.Assert.assertTrue
 
+@OptIn(ExperimentalContracts::class)
+public fun <T> T?.assertNotNull() {
+    contract { returns() implies (this@assertNotNull != null) }
+    assertTrue("Expected non-null value, but got null", this != null)
+}
+
 public fun List<MarkdownBlock>.assertEquals(vararg expected: MarkdownBlock) {
     val differences = findDifferences(expected.toList(), indentSize = 0)
     assertTrue(
diff --git a/platform/jewel/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/rendering/DefaultImageSourceResolverTest.kt b/platform/jewel/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/rendering/DefaultImageSourceResolverTest.kt
@@ -2,24 +2,36 @@
 package org.jetbrains.jewel.markdown.rendering
 
 import junit.framework.TestCase
+import junit.framework.TestCase.assertNull
+import org.jetbrains.jewel.markdown.assertNotNull
 import org.junit.Test
 
 public class DefaultImageSourceResolverTest {
     @Test
-    public fun `resolveImageSource returns raw destination for full URI`() {
+    public fun `resolves full URI as raw destination`() {
         val fullUri = "https://example.com/image.png"
 
-        val result = DefaultImageSourceResolver.resolve(fullUri)
+        val result = DefaultImageSourceResolver().resolve(fullUri)
 
         TestCase.assertEquals(fullUri, result)
     }
 
     @Test
-    public fun `resolveImageSource resolves existing classpath resource`() {
+    public fun `resolves full file URI as raw destination`() {
+        val fullUri = "file:///image.png"
+
+        val result = DefaultImageSourceResolver().resolve(fullUri)
+
+        TestCase.assertEquals(fullUri, result)
+    }
+
+    @Test
+    public fun `resolves existing classpath resource`() {
         // This test requires a file named `test-image.svg` to exist in `src/test/resources/`.
         val resourceName = "test-image.svg"
 
-        val result = DefaultImageSourceResolver.resolve(resourceName)
+        val result = DefaultImageSourceResolver().resolve(resourceName)
+        result.assertNotNull()
 
         assert(result.startsWith("file:/") || result.startsWith("jar:file:/")) {
             "Expected result to start with 'file:/' or 'jar:file:/', but got '$result'"
@@ -28,11 +40,12 @@ public class DefaultImageSourceResolverTest {
     }
 
     @Test
-    public fun `resolveImageSource with slash prefix resolves existing classpath resource`() {
+    public fun `resolves existing classpath resource with slash prefix`() {
         // This test requires a file named `test-image.svg` to exist in `src/test/resources/`.
         val resourceName = "/test-image.svg"
 
-        val result = DefaultImageSourceResolver.resolve(resourceName)
+        val result = DefaultImageSourceResolver().resolve(resourceName)
+        result.assertNotNull()
 
         assert(result.startsWith("file:/") || result.startsWith("jar:file:/")) {
             "Expected result to start with 'file:/' or 'jar:file:/', but got '$result'"
@@ -41,12 +54,41 @@ public class DefaultImageSourceResolverTest {
     }
 
     @Test
-    public fun `resolveImageSource returns raw destination for non-existent resource`() {
+    public fun `resolves absolute paths`() {
+        val absolutePath = "/absolute/path/to/image.png"
+
+        val result = DefaultImageSourceResolver().resolve(absolutePath)
+
+        TestCase.assertEquals(absolutePath, result)
+    }
+
+    @Test
+    public fun `doesn't resolve non-existent resource`() {
         val nonExistentResource = "this_file_does_not_exist.jpg"
 
-        val result = DefaultImageSourceResolver.resolve(nonExistentResource)
+        val result = DefaultImageSourceResolver().resolve(nonExistentResource)
+        assertNull(result)
+    }
+
+    @Test
+    public fun `doesn't resolve URIs without capability`() {
+        val fullUri = "https://example.com/image.png"
+
+        val result =
+            DefaultImageSourceResolver(
+                    resolveCapabilities = setOf(ImageSourceResolver.ResolveCapability.RelativePathInResources())
+                )
+                .resolve(fullUri)
+        assertNull(result)
+    }
+
+    @Test
+    public fun `doesn't resolve existing classpath resource without capability`() {
+        val resourceName = "/test-image.svg"
 
-        // It should return the original string, which will later cause Coil to fail.
-        TestCase.assertEquals(nonExistentResource, result)
+        val result =
+            DefaultImageSourceResolver(resolveCapabilities = setOf(ImageSourceResolver.ResolveCapability.PlainUri))
+                .resolve(resourceName)
+        assertNull(result)
     }
 }
