feat: correctly resolve link definitions

Author: iamgio

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/link/ResolvedImagePathProperty.kt renamed to quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/link/ResolvedLinkUrlProperty.kt

@@ -1,43 +1,43 @@
 package com.quarkdown.core.ast.attributes.link
 
-import com.quarkdown.core.ast.base.inline.Image
+import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.context.Context
 import com.quarkdown.core.context.MutableContext
 import com.quarkdown.core.property.Property
 
 /**
- * [Property] that is assigned to each image that points to a local relative path that is different from the original.
+ * [Property], assigned to each image link, that points to a local relative URL (path) that is different from the original.
  * For instance, an image may have a link to `images/picture.png`,
  * but if it's loaded from an included document with a different base path, it may be resolved to, for example, `../images/picture.png`.
  * @see com.quarkdown.core.ast.base.inline.Link
- * @see com.quarkdown.core.context.hooks.location.Imag for the storing stage
+ * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook for the storing stage
  */
-data class ResolvedImagePathProperty(
+data class ResolvedLinkUrlProperty(
     override val value: String,
 ) : Property<String> {
     companion object : Property.Key<String>
 
-    override val key = ResolvedImagePathProperty
+    override val key = ResolvedLinkUrlProperty
 }
 
 /**
  * @param context context where resolution data is stored
  * @return the resolved URL of this node within the document handled by [context],
  * or the regular URL if a resolved one is not registered
  */
-fun Image.getResolvedUrl(context: Context): String =
-    context.attributes.of(this)[ResolvedImagePathProperty]
-        ?: this.link.url
+fun LinkNode.getResolvedUrl(context: Context): String =
+    context.attributes.of(this)[ResolvedLinkUrlProperty]
+        ?: this.url
 
 /**
  * Registers the resolved path of this node within the document handled by [context].
  * @param context context where resolution data is stored
  * @param resolvedUrl resolved URL to set
- * @see com.quarkdown.core.context.hooks.ImagePathResolverHook
+ * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook
  */
-fun Image.setResolvedUrl(
+fun LinkNode.setResolvedUrl(
     context: MutableContext,
     resolvedUrl: String,
 ) {
-    context.attributes.of(this) += ResolvedImagePathProperty(resolvedUrl)
+    context.attributes.of(this) += ResolvedLinkUrlProperty(resolvedUrl)
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/LinkNode.kt

@@ -2,6 +2,7 @@ package com.quarkdown.core.ast.base
 
 import com.quarkdown.core.ast.InlineContent
 import com.quarkdown.core.ast.Node
+import com.quarkdown.core.context.file.FileSystem
 
 /**
  * A general link node.
@@ -23,4 +24,10 @@ interface LinkNode : Node {
      * Optional title.
      */
     val title: String?
+
+    /**
+     * Optional file system where this link is defined, used for resolving relative paths.
+     * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook
+     */
+    val fileSystem: FileSystem?
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/block/LinkDefinition.kt

@@ -3,18 +3,21 @@ package com.quarkdown.core.ast.base.block
 import com.quarkdown.core.ast.InlineContent
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.TextNode
+import com.quarkdown.core.context.file.FileSystem
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
  * Creation of a referenceable link definition.
  * @param label inline content of the displayed label
  * @param url URL this link points to
  * @param title optional title
+ * @param fileSystem optional file system this link is relative to
  */
 class LinkDefinition(
     override val label: InlineContent,
     override val url: String,
     override val title: String?,
+    override val fileSystem: FileSystem? = null,
 ) : LinkNode,
     TextNode {
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/inline/Link.kt

@@ -19,7 +19,7 @@ class Link(
     override val label: InlineContent,
     override val url: String,
     override val title: String?,
-    val fileSystem: FileSystem? = null,
+    override val fileSystem: FileSystem? = null,
 ) : LinkNode,
     TextNode {
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/BaseContext.kt

@@ -1,6 +1,7 @@
 package com.quarkdown.core.context
 
 import com.quarkdown.core.ast.attributes.AstAttributes
+import com.quarkdown.core.ast.attributes.link.getResolvedUrl
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.inline.Link
 import com.quarkdown.core.ast.base.inline.ReferenceLink
@@ -74,7 +75,7 @@ open class BaseContext(
     override fun resolve(reference: ReferenceLink): LinkNode? =
         attributes.linkDefinitions
             .firstOrNull { it.label.toPlainText() == reference.reference.toPlainText() }
-            ?.let { Link(reference.label, it.url, it.title) }
+            ?.let { Link(reference.label, it.getResolvedUrl(this), it.title, it.fileSystem) }
             ?.also { link ->
                 reference.onResolve.forEach { action -> action(link) }
             }

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/ImagePathResolverHook.kt

@@ -0,0 +1,56 @@
+package com.quarkdown.core.context.hooks
+
+import com.quarkdown.core.ast.attributes.link.setResolvedUrl
+import com.quarkdown.core.ast.base.LinkNode
+import com.quarkdown.core.ast.base.block.LinkDefinition
+import com.quarkdown.core.ast.base.inline.Image
+import com.quarkdown.core.ast.iterator.AstIteratorHook
+import com.quarkdown.core.ast.iterator.ObservableAstIterator
+import com.quarkdown.core.context.MutableContext
+import com.quarkdown.core.util.isURL
+import java.nio.file.Path
+import kotlin.io.path.Path
+
+/**
+ * Hook that resolves relative link paths based on their file system.
+ *
+ * If a link uses a relative path and its file system
+ * is different from the [context]'s file system,
+ * the path is resolved relative to the context's file system.
+ *
+ * This is mainly applied to images.
+ *
+ * @param context root context to use for resolution
+ * @see com.quarkdown.core.ast.attributes.link.ResolvedImagePathProperty
+ */
+class LinkUrlResolverHook(
+    private val context: MutableContext,
+) : AstIteratorHook {
+    /**
+     * Resolves the URL of a [link] if it's a relative path
+     * and its file system is different from the [context]'s file system.
+     *
+     * @param link link node to resolve
+     */
+    private fun resolve(link: LinkNode) {
+        val fileSystem = link.fileSystem
+        if (fileSystem == null || fileSystem.isRoot) return // No need to resolve paths.
+
+        if (link.url.isURL || Path(link.url).isAbsolute) return // Not a relative path.
+
+        val resolved: Path? =
+            context.fileSystem
+                .relativePathTo(fileSystem)
+                ?.resolve(link.url)
+                ?.normalize()
+
+        resolved?.let {
+            link.setResolvedUrl(context, it.toString())
+        }
+    }
+
+    override fun attach(iterator: ObservableAstIterator) {
+        iterator.on<Image> { resolve(it.link) }
+        iterator.on<LinkDefinition> { resolve(it) }
+    }
+}

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/LinkUrlResolverHook.kt

@@ -1,6 +1,6 @@
 package com.quarkdown.core.context.hooks
 
-import com.quarkdown.core.ast.attributes.MutableAstAttributes
+import com.quarkdown.core.ast.attributes.link.getResolvedUrl
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.inline.Image
 import com.quarkdown.core.ast.base.inline.ReferenceImage
@@ -9,38 +9,33 @@ import com.quarkdown.core.ast.iterator.ObservableAstIterator
 import com.quarkdown.core.ast.media.StoredMediaProperty
 import com.quarkdown.core.context.MutableContext
 import com.quarkdown.core.log.Log
-import com.quarkdown.core.media.storage.MutableMediaStorage
 import com.quarkdown.core.media.storage.StoredMedia
-import java.io.File
 
 /**
  * Hook that, when a node containing information about media is found,
  * registers it in the media [storage].
  * A media storage is a temporary lookup table that maps media to their paths, so that they can be resolved later.
- * @param storage media storage
- * @param workingDirectory directory from which media are resolved, in case they use relative paths
+ * @param storage media storage where media are registered
  */
 class MediaStorerHook(
-    private val storage: MutableMediaStorage,
-    private val attributes: MutableAstAttributes,
-    private val workingDirectory: File?,
+    private val context: MutableContext,
 ) : AstIteratorHook {
-    constructor(context: MutableContext) : this(
-        context.mediaStorage,
-        context.attributes,
-        context.fileSystem.workingDirectory,
-    )
-
     /**
      * Registers a media contained within a link into the media storage
      * and attaches the new media to the node's extra attributes.
+     *
+     * [getResolvedUrl] is used rather than [LinkNode.url] in case a different URL was set by [LinkUrlResolverHook].
+     *
      * @param link the link node containing the media to register.
      * It is also the node to attach the [StoredMediaProperty] to, into [com.quarkdown.core.ast.attributes.AstAttributes.properties]
      */
     private fun register(link: LinkNode) {
         val media: StoredMedia? =
             try {
-                storage.register(link.url, workingDirectory)
+                context.mediaStorage.register(
+                    link.getResolvedUrl(context),
+                    context.fileSystem.workingDirectory,
+                )
             } catch (_: IllegalArgumentException) {
                 // If the media cannot be resolved, it is ignored and not stored.
                 Log.warn("Media cannot be resolved: ${link.url}")
@@ -52,7 +47,7 @@ class MediaStorerHook(
             ?.let(::StoredMediaProperty)
             ?.also { Log.debug("Registered media: ${link.url} -> ${it.value}") }
             ?.let {
-                attributes.of(link) += it
+                context.attributes.of(link) += it
             }
     }
 

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/MediaStorerHook.kt

@@ -2,8 +2,8 @@ package com.quarkdown.core.flavor.base
 
 import com.quarkdown.core.ast.iterator.ObservableAstIterator
 import com.quarkdown.core.context.MutableContext
-import com.quarkdown.core.context.hooks.ImagePathResolverHook
 import com.quarkdown.core.context.hooks.LinkDefinitionRegistrationHook
+import com.quarkdown.core.context.hooks.LinkUrlResolverHook
 import com.quarkdown.core.context.hooks.SubdocumentRegistrationHook
 import com.quarkdown.core.context.hooks.presence.CodePresenceHook
 import com.quarkdown.core.context.hooks.presence.MathPresenceHook
@@ -22,7 +22,7 @@ class BaseMarkdownTreeIteratorFactory : TreeIteratorFactory {
             // Registers subdocuments.
             .attach(SubdocumentRegistrationHook(context))
             // Resolves local URLs/paths for links and images loaded from different base paths.
-            .attach(ImagePathResolverHook(context))
+            .attach(LinkUrlResolverHook(context))
             // Resolves footnotes.
             .attach(FootnoteResolverHook(context))
             // Allows loading code libraries (e.g. highlight.js syntax highlighting)

quarkdown-core/src/main/kotlin/com/quarkdown/core/flavor/base/BaseMarkdownTreeIteratorFactory.kt

@@ -178,6 +178,7 @@ class BlockTokenParser(
             url = groups.next().trim(),
             // Remove first and last character
             title = groups.nextOrNull()?.trimDelimiters()?.trim(),
+            fileSystem = context.fileSystem,
         )
     }