From f58603ea2ca7ba7baf3c2ce7365521c662206692 Mon Sep 17 00:00:00 2001
From: "Brian M. Carr" <brian.carr@engine.com>
Date: Thu, 8 Oct 2026 11:49:59 -0500
Subject: [PATCH 1/2] Keep Markdown intact when cleaning plain // comments

Edge detection treated any leading non-alphanumeric run as frame chrome, so
ordinary // comments lost a leading code span backtick or reference-link
bracket, shared list markers were stripped from every line, and lines with no
alphanumerics (code fences, table rules) were blanked.

Comments with no border lines and no column-zero fence are now treated as
plain: only their common leading whitespace is removed and every line in the
content range is kept. Framed, Holub, and JavaDoc comments keep the existing
behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../protoc/util/comment/CommentParser.kt      |  55 ++++++++
 src/test/kotlin/CommentTests.kt               | 130 ++++++++++++++++++
 2 files changed, 185 insertions(+)

diff --git a/src/main/kotlin/com/engine/protoc/util/comment/CommentParser.kt b/src/main/kotlin/com/engine/protoc/util/comment/CommentParser.kt
index 465b34e..afd0ee3 100644
--- a/src/main/kotlin/com/engine/protoc/util/comment/CommentParser.kt
+++ b/src/main/kotlin/com/engine/protoc/util/comment/CommentParser.kt
@@ -69,6 +69,10 @@ public abstract class CommentParser<S : Style> {
             // A single content line can't reveal a non-whitespace frame edge — frames need multiple lines
             // to corroborate. Trailing punctuation like "]." or "." on one line is content, not a frame.
             private val rightSingleLineEdgePattern = Regex(""".*?(\s+)$""")
+
+            // A top or bottom border line of a framed comment, e.g. "*****", "====\", or "//////".
+            // Backticks and tildes are deliberately excluded so a closing Markdown code fence is content.
+            private val frameBorderPattern = Regex("""[*=/\\|#+_-]+""")
             public fun of(rawComment: String): ParseContext = ParseContext(rawComment)
         }
 
@@ -95,6 +99,35 @@ public abstract class CommentParser<S : Style> {
          * This may be an empty range if no content exists for the content.
          */
         public val contentLineIndices: IntRange by lazy {
+            if (isPlain) {
+                val first = rawCommentLines.indexOfFirst { it.isNotBlank() }
+                if (first < 0) IntRange.EMPTY else first..rawCommentLines.indexOfLast { it.isNotBlank() }
+            } else {
+                framedContentLineIndices
+            }
+        }
+
+        /**
+         * True when the comment has a top or bottom border line made only of frame characters, as in a
+         * block comment frame or a JavaDoc opening `*`.
+         */
+        public val hasFrameChrome: Boolean by lazy {
+            val nonBlank = rawCommentLines.filter { it.isNotBlank() }
+            nonBlank.size > 1 && (frameBorderPattern.matches(nonBlank.first().trim()) || frameBorderPattern.matches(nonBlank.last().trim()))
+        }
+
+        /**
+         * True when the comment has no frame chrome and no column-zero fence (such as the Holub `*` edge),
+         * which is the case for ordinary `//` comments. Only common leading whitespace is removed from a
+         * plain comment, and lines without alphanumeric characters (code fences, table rules, list
+         * markers) are kept as content, so Markdown in the comment survives cleaning.
+         */
+        private val isPlain: Boolean by lazy {
+            !hasFrameChrome &&
+                (framedContentLines.size < 2 || framedCommonEdges.first.firstOrNull()?.isWhitespace() != false)
+        }
+
+        private val framedContentLineIndices: IntRange by lazy {
             var firstContentLineIndex: Int? = null
             var lastContentLineIndex: Int? = null
             rawCommentLines.indices.forEach { i ->
@@ -116,6 +149,10 @@ public abstract class CommentParser<S : Style> {
             rawCommentLines.slice(contentLineIndices)
         }
 
+        private val framedContentLines: List<String> by lazy {
+            rawCommentLines.slice(framedContentLineIndices)
+        }
+
         /**
          * The sanitized region of lines that include comment content.
          * May include internal blank lines.
@@ -129,6 +166,20 @@ public abstract class CommentParser<S : Style> {
          * This is useful for identification of fences, padding, and other comment chrome.
          */
         public val rawCommonEdges: Pair<String, String> by lazy {
+            if (isPlain) {
+                val leftEdge = rawContentLines
+                    .filter { it.isNotBlank() }
+                    .map { line -> line.takeWhile { it.isWhitespace() } }
+                    .reduceOrNull { acc, it -> acc.commonPrefixWith(it) }
+                    ?: ""
+                leftEdge to ""
+            } else {
+                framedCommonEdges
+            }
+        }
+
+        private val framedCommonEdges: Pair<String, String> by lazy {
+            val rawContentLines = framedContentLines
             when (rawContentLines.size) {
                 // it's empty
                 0 -> "" to ""
@@ -236,6 +287,10 @@ public abstract class CommentParser<S : Style> {
          */
         public fun cleanedLine(index: Int): String {
             return cleanedLineCache.computeIfAbsent(index) { i ->
+                if (isPlain) {
+                    return@computeIfAbsent rawCommentLines[i].removePrefix(rawCommonEdges.first).trimEnd()
+                }
+
                 /*
                  * special casing for first line and fencing messing up left edge detection
                  */
diff --git a/src/test/kotlin/CommentTests.kt b/src/test/kotlin/CommentTests.kt
index 6bea162..54d2c81 100644
--- a/src/test/kotlin/CommentTests.kt
+++ b/src/test/kotlin/CommentTests.kt
@@ -281,6 +281,136 @@ class CommentTests :
                 """.trimMargin(),
                 expectedCleanedResult = "The greeting will be randomly selected [MissingAnchor].",
             ),
+            TestCase(
+                description = "single-line comment starting with a code span",
+                source = """
+                |// `entity_type` was unspecified.
+                |
+                """.trimMargin(),
+                protoc = """
+                | `entity_type` was unspecified.
+                |
+                """.trimMargin(),
+                expectedCleanedResult = "`entity_type` was unspecified.",
+            ),
+            TestCase(
+                description = "single-line comment starting with a reference link",
+                source = """
+                |// [Widget] is returned on success.
+                |
+                """.trimMargin(),
+                protoc = """
+                | [Widget] is returned on success.
+                |
+                """.trimMargin(),
+                expectedCleanedResult = "[Widget] is returned on success.",
+            ),
+            TestCase(
+                description = "multiple single-line comments that all start with a reference link",
+                source = """
+                |// [Widget] for widgets.
+                |// [Gadget] for gadgets.
+                |
+                """.trimMargin(),
+                protoc = """
+                | [Widget] for widgets.
+                | [Gadget] for gadgets.
+                |
+                """.trimMargin(),
+                expectedCleanedResult = """
+                |[Widget] for widgets.
+                |[Gadget] for gadgets.
+                """.trimMargin(),
+            ),
+            TestCase(
+                description = "multiple single-line comments forming a bulleted list",
+                source = """
+                |// - first
+                |// - second
+                |// - third
+                |
+                """.trimMargin(),
+                protoc = """
+                | - first
+                | - second
+                | - third
+                |
+                """.trimMargin(),
+                expectedCleanedResult = """
+                |- first
+                |- second
+                |- third
+                """.trimMargin(),
+            ),
+            TestCase(
+                description = "single-line comments with a paragraph break and indented list",
+                source = """
+                |// Returns one of:
+                |//
+                |// * `A` when
+                |//   continued
+                |// * `B`
+                |
+                """.trimMargin(),
+                protoc = """
+                | Returns one of:
+                |
+                | * `A` when
+                |   continued
+                | * `B`
+                |
+                """.trimMargin(),
+                expectedCleanedResult = """
+                |Returns one of:
+                |
+                |* `A` when
+                |  continued
+                |* `B`
+                """.trimMargin(),
+            ),
+            TestCase(
+                description = "single-line comments containing a fenced code block",
+                source = """
+                |// Example:
+                |// ```json
+                |// {"a": 1}
+                |// ```
+                |
+                """.trimMargin(),
+                protoc = """
+                | Example:
+                | ```json
+                | {"a": 1}
+                | ```
+                |
+                """.trimMargin(),
+                expectedCleanedResult = """
+                |Example:
+                |```json
+                |{"a": 1}
+                |```
+                """.trimMargin(),
+            ),
+            TestCase(
+                description = "single-line comments containing a table",
+                source = """
+                |// | Code | Meaning |
+                |// |------|---------|
+                |// | 1    | One     |
+                |
+                """.trimMargin(),
+                protoc = """
+                | | Code | Meaning |
+                | |------|---------|
+                | | 1    | One     |
+                |
+                """.trimMargin(),
+                expectedCleanedResult = """
+                || Code | Meaning |
+                ||------|---------|
+                || 1    | One     |
+                """.trimMargin(),
+            ),
         )
 
         context("Comment parsing tests") {

From 2423f5d928338d12bb033abb1cbcf6f4efb537ce Mon Sep 17 00:00:00 2001
From: "Brian M. Carr" <brian.carr@engine.com>
Date: Thu, 8 Oct 2026 11:55:48 -0500
Subject: [PATCH 2/2] Add protoc-utils-markdown for shared doc-comment link
 handling

Reference-link resolution, failure reporting, and Markdown-to-plain-text
conversion were implemented separately in protoc-gen-markdown and
protoc-gen-openapi. This module extracts them so both plugins share one
implementation:

- ReferenceIndex indexes every proto element under every name a comment
  can use and resolves labels with protoc-gen-markdown's scope rules,
  mapping elements to a plugin-supplied target type.
- ReferenceLinkProcessor is a commonmark LinkProcessor with NONE / WARN /
  FAIL_ON_INVALID modes, referenceLink URL overrides, and collected
  failures with a CodeGeneratorResponse-ready summary.
- MarkdownText renders documents back to CommonMark and flattens them to
  plain text or a first sentence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |   5 +-
 README.md                                     |   3 +
 gradle/libs.versions.toml                     |   4 +
 gradle/license/allowed-licenses.json          |   4 +-
 markdown/README.md                            |  37 +++
 markdown/build.gradle.kts                     |  54 +++
 .../protoc/util/markdown/MarkdownText.kt      |  92 ++++++
 .../protoc/util/markdown/ReferenceElement.kt  |  50 +++
 .../protoc/util/markdown/ReferenceIndex.kt    | 308 ++++++++++++++++++
 .../util/markdown/ReferenceLinkFailure.kt     |  55 ++++
 .../protoc/util/markdown/ReferenceLinkMode.kt |  18 +
 .../util/markdown/ReferenceLinkProcessor.kt   | 186 +++++++++++
 .../src/test/kotlin/ReferenceLinkTests.kt     | 263 +++++++++++++++
 13 files changed, 1076 insertions(+), 3 deletions(-)
 create mode 100644 markdown/README.md
 create mode 100644 markdown/build.gradle.kts
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/MarkdownText.kt
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceElement.kt
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceIndex.kt
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkFailure.kt
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkMode.kt
 create mode 100644 markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkProcessor.kt
 create mode 100644 markdown/src/test/kotlin/ReferenceLinkTests.kt

diff --git a/CLAUDE.md b/CLAUDE.md
index 3a602fa..575bb56 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Build / test commands
 
-- `./gradlew build` — compiles, runs ktlint, and runs the test suite for both modules.
+- `./gradlew build` — compiles, runs ktlint, and runs the test suite for every module.
 - `./gradlew test` — runs tests only. The root `:test` task transitively triggers the recorder's GraalVM `nativeCompile` and a `publishToMavenLocal` (see *Test fixture wiring*), so a clean checkout's first run takes several minutes for the native image build.
 - `./gradlew test --tests "ServiceAndMethodWrapperTests"` — single test class. (`-i` for info logging.)
 - `./gradlew ktlintCheck` / `./gradlew ktlintFormat` — lint / autoformat. ktlint excludes everything under `build/` (workaround for the plugin not honoring generated-source exclusions). **Always run `ktlintFormat` after editing Kotlin source** so the next CI run isn't blocked on a trivial formatting failure.
@@ -17,10 +17,11 @@ The `pr.yaml` workflow just calls `build.yaml` (which runs `./gradlew build` aft
 
 ## Module layout
 
-The repo is a multi-project Gradle build with two modules:
+The repo is a multi-project Gradle build with three modules:
 
 - **Root project `:protoc-utils`** (`src/main/kotlin/com/engine/protoc/util/…`) — the published Kotlin library. Pure JVM, no native code.
 - **Subproject `:protoc-utils-recorder`** (`recorder/`) — a tiny GraalVM-native protoc plugin (single `Main.kt`) that copies stdin to a file named `code-generator-request.binpb`. It is shipped as multi-platform native binaries to Maven Central, **not** as a JVM jar.
+- **Subproject `:protoc-utils-markdown`** (`markdown/`) — a JVM library, depending on the root library and commonmark-java, that resolves proto reference links in doc comments and converts comment Markdown to plain text. Kept separate so the core library stays free of the commonmark dependency.
 
 `settings.gradle.kts` walks the tree and includes every directory containing a `build.gradle.kts` (skipping `build`, `buildSrc`, `tmp`, `scratch`, dotfile dirs, and dirs containing `.gradle_ignore`). Subproject names are derived as `:<root-name>-<relative-path>`, so the directory `recorder/` becomes `:protoc-utils-recorder`. To add a subproject, just create a directory with a `build.gradle.kts` — no manual `include(…)` needed.
 
diff --git a/README.md b/README.md
index 5504c35..d624b09 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,8 @@ dependencies {
 
 The companion `protoc-utils-recorder` plugin is published as multi-platform native binaries under the same group; see [`recorder/README.md`](recorder/README.md) for how to consume those.
 
+The companion `protoc-utils-markdown` library resolves proto reference links (`[Widget]`, `[Service.Rpc]`) in doc comments and converts comment Markdown to plain text; see [`markdown/README.md`](markdown/README.md).
+
 ---
 
 ## Why this exists
@@ -79,6 +81,7 @@ val comment: String? = nameElement?.location?.leadingComments?.cleaned
 | `cleaned` | The comment text with fencing characters (`//`, `/*`, `*`, etc.) stripped |
 
 The `cleaned` form is what you almost always want when generating documentation or OpenAPI descriptions.
+For ordinary `//` comments only the common leading whitespace is removed, so Markdown in the comment (a leading code span or reference link, list markers, code fences, tables) is preserved.
 
 ### Extension options
 
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 7fe799d..41bbcb5 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -2,6 +2,8 @@
 kotest = "6.1.4"
 kotlin = "2.4.20"
 protobuf = "4.34.1"
+commonmark = "0.28.0"
+slf4j = "2.0.17"
 
 # plugin versions
 google-osdetector-plugin = "1.7.3"
@@ -21,6 +23,8 @@ cyclonedx = { id = "org.cyclonedx.bom", version.ref = "cyclonedx" }
 license-report = { id = "com.github.jk1.dependency-license-report", version.ref = "jk1-dependency-license-report" }
 
 [libraries]
+commonmark = { group = "org.commonmark", name = "commonmark", version.ref = "commonmark" }
+slf4j-api = { group = "org.slf4j", name = "slf4j-api", version.ref = "slf4j" }
 protobuf-java = { group = "com.google.protobuf", name = "protobuf-java", version.ref = "protobuf" }
 
 # test dependencies
diff --git a/gradle/license/allowed-licenses.json b/gradle/license/allowed-licenses.json
index dcde8a7..9ca893c 100644
--- a/gradle/license/allowed-licenses.json
+++ b/gradle/license/allowed-licenses.json
@@ -2,6 +2,8 @@
   "allowedLicenses": [
     { "moduleLicense": "Apache License, Version 2.0" },
     { "moduleLicense": "MIT License" },
-    { "moduleLicense": "The 3-Clause BSD License" }
+    { "moduleLicense": "The 2-Clause BSD License" },
+    { "moduleLicense": "The 3-Clause BSD License" },
+    { "moduleName": "org.slf4j:slf4j-api" }
   ]
 }
diff --git a/markdown/README.md b/markdown/README.md
new file mode 100644
index 0000000..d5152fe
--- /dev/null
+++ b/markdown/README.md
@@ -0,0 +1,37 @@
+# protoc-utils-markdown
+
+CommonMark helpers shared by Engine's protoc plugins for handling proto doc comments.
+
+```kotlin
+implementation("com.engine:protoc-utils-markdown:VERSION")
+```
+
+## Reference links
+
+Doc comments refer to other proto elements with CommonMark reference-link syntax: `[Widget]`, `[acme.v1.Widget]`, `[Widget.name]`, `[Status.STATUS_ACTIVE]`, `[WidgetService.GetWidget]`, or the full form `[display text][Widget]`.
+
+- `ReferenceIndex<T>` indexes every message, field, enum, enum value, service, and RPC in a set of files.
+  A plugin-supplied function maps each `ReferenceElement` to a target `T` (an href, a rendering decision, …); returning `null` leaves the element unindexed.
+  Bare names resolve against the members of the comment's own descriptor before global short names, so a comment on `message Widget` can write `[name]`.
+- `ReferenceLinkProcessor<T>` is a commonmark-java `LinkProcessor` that rewrites resolved references as links (`ReferenceRendering.Link`) or code spans (`ReferenceRendering.Code`).
+  Inline links, images, code spans, and escaped brackets are left alone.
+  Labels in the `overrides` map (parsed from repeated `referenceLink=<label>=<URL>` parameters with `ReferenceLinkProcessor.parseOverrides`) link outside the compile scope, e.g. `google.rpc.Status`.
+- `ReferenceLinkMode` selects `NONE` (no resolution), `WARN` (log failures), or `FAIL_ON_INVALID` (log and collect failures).
+  Collected `ReferenceLinkFailure`s are formatted for `CodeGeneratorResponse.error` with `ReferenceLinkFailure.summary`.
+
+```kotlin
+val index = ReferenceIndex(request.protoFiles) { element -> ReferenceRendering.Link("#${element.fqn}") }
+val processor = ReferenceLinkProcessor(index, ReferenceLinkMode.FAIL_ON_INVALID) { it }
+val parser = Parser.builder().linkProcessor(processor).build()
+
+val document = processor.withScope("acme.v1.Widget") { parser.parse(comment.cleaned) }
+val description = MarkdownText.render(document)
+
+val failures = processor.drainFailures()
+if (failures.isNotEmpty()) response.addError("my-plugin failed:\n" + ReferenceLinkFailure.summary(failures))
+```
+
+## Plain text
+
+`MarkdownText.toPlainText` flattens a parsed comment to one line of plain text for fields that cannot hold Markdown (titles, summaries), and `MarkdownText.firstSentence` cuts it to the first sentence of the first paragraph.
+Parse with the same `ReferenceLinkProcessor` first so bad references in those fields are still reported.
diff --git a/markdown/build.gradle.kts b/markdown/build.gradle.kts
new file mode 100644
index 0000000..96edf42
--- /dev/null
+++ b/markdown/build.gradle.kts
@@ -0,0 +1,54 @@
+description = "CommonMark helpers for protoc plugins: proto reference-link resolution and plain-text scrubbing of doc comments."
+
+java {
+    withJavadocJar()
+    withSourcesJar()
+}
+
+dependencies {
+    api(rootProject)
+    api(libs.commonmark)
+    implementation(libs.slf4j.api)
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("maven") {
+            from(components["java"])
+            artifact(layout.buildDirectory.file("reports/cyclonedx-direct/bom.json")) {
+                classifier = "cyclonedx"
+                extension = "json"
+                builtBy(tasks.named("cyclonedxDirectBom"))
+            }
+            pom {
+                name.set(project.name)
+                inceptionYear.set("2026")
+                licenses {
+                    license {
+                        name.set("Apache-2.0")
+                        url.set("https://github.com/engine-public/protoc-utils/blob/${version}/LICENSE")
+                    }
+                }
+                developers {
+                    developer {
+                        organizationUrl.set("https://github.com/engine-public")
+                    }
+                }
+                scm {
+                    connection.set("scm:git:https://github.com/engine-public/protoc-utils.git")
+                    developerConnection.set("scm:git:https://github.com/engine-public/protoc-utils.git")
+                    url.set("https://github.com/engine-public/protoc-utils")
+                }
+            }
+        }
+    }
+}
+
+afterEvaluate {
+    publishing.publications.named<MavenPublication>("maven") {
+        pom {
+            description.set(project.description)
+            url.set("https://github.com/engine-public/protoc-utils/blob/${version}/markdown/README.md")
+        }
+    }
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/MarkdownText.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/MarkdownText.kt
new file mode 100644
index 0000000..3ef2916
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/MarkdownText.kt
@@ -0,0 +1,92 @@
+package com.engine.protoc.util.markdown
+
+import org.commonmark.node.AbstractVisitor
+import org.commonmark.node.Code
+import org.commonmark.node.Image
+import org.commonmark.node.Link
+import org.commonmark.node.Node
+import org.commonmark.node.Paragraph
+import org.commonmark.node.Text
+import org.commonmark.renderer.markdown.MarkdownRenderer
+import org.commonmark.renderer.text.TextContentRenderer
+import java.text.BreakIterator
+import java.util.Locale
+
+/**
+ * Conversions of parsed doc-comment Markdown into the strings a plugin emits.
+ */
+public object MarkdownText {
+    private val defaultMarkdownRenderer: MarkdownRenderer = MarkdownRenderer.builder().build()
+    private val textRenderer: TextContentRenderer = TextContentRenderer.builder().stripNewlines(true).build()
+
+    /**
+     * Render [node] back to CommonMark, with trailing whitespace removed from every line and from
+     * the end of the result.  A hard line break written as trailing spaces therefore renders as a
+     * soft break; cleaned doc comments have already lost trailing spaces, so this only normalizes.
+     */
+    public fun render(
+        node: Node,
+        renderer: MarkdownRenderer = defaultMarkdownRenderer,
+    ): String =
+        renderer.render(node)
+            .lines()
+            .joinToString("\n") { it.trimEnd() }
+            .trimEnd()
+
+    /**
+     * Flatten [node] to a single line of plain text for fields that cannot hold Markdown (titles,
+     * summaries).  Links and images become their visible text, code spans lose their backticks,
+     * emphasis markers are dropped, and line breaks become spaces.
+     *
+     * Mutates [node]; pass a freshly parsed document.
+     */
+    public fun toPlainText(node: Node): String {
+        val replacements = mutableListOf<Node>()
+        node.accept(
+            object : AbstractVisitor() {
+                override fun visit(link: Link) {
+                    replacements += link
+                    visitChildren(link)
+                }
+
+                override fun visit(image: Image) {
+                    replacements += image
+                    visitChildren(image)
+                }
+
+                override fun visit(code: Code) {
+                    replacements += code
+                }
+            },
+        )
+        for (n in replacements) {
+            if (n is Code) {
+                n.insertBefore(Text(n.literal))
+            } else {
+                while (true) {
+                    val child = n.firstChild ?: break
+                    n.insertBefore(child)
+                }
+            }
+            n.unlink()
+        }
+        return textRenderer.render(node).trim()
+    }
+
+    /**
+     * The plain text of [node]'s first paragraph, cut to its first sentence.  A document that does
+     * not open with a paragraph (a list, heading, or code block) is flattened whole.  Sentence
+     * boundaries come from [BreakIterator], so `e.g.`, decimals, and URLs don't end a sentence.
+     *
+     * Mutates [node]; pass a freshly parsed document.
+     */
+    public fun firstSentence(node: Node): String {
+        val first = node.firstChild
+        val plain = toPlainText(if (first is Paragraph) first else node)
+        if (plain.isEmpty()) return ""
+        val iterator = BreakIterator.getSentenceInstance(Locale.ROOT)
+        iterator.setText(plain)
+        val end = iterator.next()
+        return if (end == BreakIterator.DONE) plain else plain.substring(0, end).trim()
+    }
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceElement.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceElement.kt
new file mode 100644
index 0000000..350b3a7
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceElement.kt
@@ -0,0 +1,50 @@
+package com.engine.protoc.util.markdown
+
+import com.engine.protoc.util.GeneratedMessageWrapper
+import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+
+/**
+ * A proto element that a doc-comment reference link (`[Name]`) can point at.
+ *
+ * Instances are created by [ReferenceIndex] while it walks the compile scope and are handed to the
+ * plugin's target function, which decides where (or whether) the element is addressable in that
+ * plugin's output.
+ */
+public class ReferenceElement internal constructor(
+    /** What kind of proto element this is. */
+    public val kind: Kind,
+    /** The file that declares the element. */
+    public val file: FileDescriptorProtoWrapper,
+    /** The proto package of [file], without a leading dot; empty for the default package. */
+    public val packageName: String,
+    /**
+     * The dotted name of the element relative to its package, e.g. `Outer.Inner`,
+     * `Outer.Inner.field`, `Enum.VALUE`, or `Service.Method`.
+     */
+    public val localName: String,
+    /** The containing element: the message of a field or nested type, the enum of a value, the service of an RPC. */
+    public val parent: ReferenceElement?,
+    /** The descriptor wrapper for the element. */
+    public val descriptor: GeneratedMessageWrapper<*>,
+) {
+    /** The fully-qualified name of the element, without a leading dot. */
+    public val fqn: String = if (packageName.isEmpty()) localName else "$packageName.$localName"
+
+    /** The last segment of [localName]. */
+    public val simpleName: String get() = localName.substringAfterLast('.')
+
+    /** The kinds of element a reference link can resolve to. */
+    public enum class Kind(
+        /** The human-readable label used in log and failure messages. */
+        public val label: String,
+    ) {
+        MESSAGE("message"),
+        ENUM("enum"),
+        SERVICE("service"),
+        FIELD("field"),
+        ENUM_VALUE("enum value"),
+        RPC("rpc"),
+    }
+
+    override fun toString(): String = "${kind.label} $fqn"
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceIndex.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceIndex.kt
new file mode 100644
index 0000000..e2cb9e0
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceIndex.kt
@@ -0,0 +1,308 @@
+package com.engine.protoc.util.markdown
+
+import com.engine.protoc.util.enums.EnumDescriptorProtoWrapper
+import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+import com.engine.protoc.util.message.DescriptorProtoWrapper
+import org.slf4j.LoggerFactory
+
+private val log = LoggerFactory.getLogger(ReferenceIndex::class.java)
+
+/**
+ * An index of every message, field, enum, enum value, service, and RPC declared in [files], keyed
+ * by every name a doc-comment reference link may use for it.
+ *
+ * Each element is mapped to a plugin-specific target of type [T] by [targetFor] (for example an
+ * href, or a description of how to render the reference).  An element for which [targetFor]
+ * returns `null` is not indexed, so references to it resolve as [Outcome.Unresolved].  Two keys
+ * are ambiguous only when they map to targets that are not equal, so plugins decide what counts
+ * as "the same place" through [T]'s `equals`.
+ *
+ * Resolution order for a label under a comment's scope (see [resolve]):
+ *
+ *  1. A label containing a dot is looked up only in the qualified index, which holds every FQN,
+ *     every dotted name relative to the package (`Outer.Inner`), and every `Type.member` form.
+ *  2. Otherwise, the bare-scope candidates of the comment's descriptor: the fields and nested types
+ *     of a message, the values of an enum, the RPCs of a service, the sibling fields of a field
+ *     (plus the fields of the field's message type and that type itself), the sibling values of an
+ *     enum value, and the sibling RPCs of an RPC (plus the fields of its input and output types
+ *     and those types themselves).
+ *  3. The global short names of messages, enums, and services.
+ *  4. The global short names of enum values.
+ *
+ * The first resolved step wins; otherwise the first ambiguous step; otherwise unresolved.
+ */
+public class ReferenceIndex<T : Any>(
+    files: Iterable<FileDescriptorProtoWrapper>,
+    private val describe: (T) -> String = { it.toString() },
+    private val targetFor: (ReferenceElement) -> T?,
+) {
+    /** The result of resolving a reference label. */
+    public sealed interface Outcome<out T : Any> {
+        /** The label names exactly one target. */
+        public data class Resolved<T : Any>(val target: T) : Outcome<T>
+
+        /**
+         * The label names more than one distinct target.  [target] is the last one registered, and
+         * [candidates] describes each of them as `owner → target`.
+         */
+        public data class Ambiguous<T : Any>(val target: T, val candidates: List<String>) : Outcome<T>
+
+        /** The label names nothing in the index. */
+        public data object Unresolved : Outcome<Nothing>
+    }
+
+    private val qualified = AmbiguityAwareMap("qualified")
+    private val globalShortTypes = AmbiguityAwareMap("global short type")
+    private val globalShortEnumValues = AmbiguityAwareMap("global short enum value")
+
+    private val fieldsByMessage = mutableMapOf<String, MutableMap<String, T>>()
+    private val nestedTypesByMessage = mutableMapOf<String, MutableMap<String, T>>()
+    private val valuesByEnum = mutableMapOf<String, MutableMap<String, T>>()
+    private val rpcsByService = mutableMapOf<String, MutableMap<String, T>>()
+    private val parentMessageOfField = mutableMapOf<String, String>()
+    private val parentEnumOfValue = mutableMapOf<String, String>()
+    private val parentServiceOfRpc = mutableMapOf<String, String>()
+    private val fieldTypeOf = mutableMapOf<String, String>()
+    private val rpcInputOf = mutableMapOf<String, String>()
+    private val rpcOutputOf = mutableMapOf<String, String>()
+    private val fileByFqn = mutableMapOf<String, String>()
+    private val typeTargetByFqn = mutableMapOf<String, T>()
+
+    init {
+        for (file in files) indexFile(file)
+    }
+
+    /** The name of the proto file that declares the element [fqn], or `null` when it isn't indexed. */
+    public fun fileOf(fqn: String): String? = fileByFqn[fqn]
+
+    /**
+     * Resolve [label] for a comment attached to the descriptor [scopeFqn] (without a leading dot),
+     * or `""` when the comment has no descriptor scope.
+     */
+    public fun resolve(
+        label: String,
+        scopeFqn: String,
+    ): Outcome<T> {
+        if (label.isEmpty()) return Outcome.Unresolved
+        if ('.' in label) return qualified.lookup(label)
+        var ambiguous: Outcome.Ambiguous<T>? = null
+        for (outcome in sequenceOf(
+            { bareScopeOutcome(label, scopeFqn) },
+            { globalShortTypes.lookup(label) },
+            { globalShortEnumValues.lookup(label) },
+        )) {
+            when (val it = outcome()) {
+                is Outcome.Resolved -> return it
+                is Outcome.Ambiguous -> if (ambiguous == null) ambiguous = it
+                else -> Unit
+            }
+        }
+        return ambiguous ?: Outcome.Unresolved
+    }
+
+    private fun indexFile(file: FileDescriptorProtoWrapper) {
+        val pkg = file.`package`?.value.orEmpty()
+        val protoFile = file.name ?: "(unnamed)"
+        for (m in file.messageTypes) indexMessage(m, file, pkg, protoFile, null)
+        for (e in file.enumTypes) indexEnum(e, file, pkg, protoFile, null)
+        for (s in file.services) {
+            val sname = s.name?.value ?: continue
+            val service = ReferenceElement(ReferenceElement.Kind.SERVICE, file, pkg, sname, null, s)
+            val sFqn = service.fqn
+            fileByFqn[sFqn] = protoFile
+            targetFor(service)?.let { target ->
+                globalShortTypes.put(sname, target, service.toString())
+                qualified.put(sname, target, service.toString())
+                qualified.put(sFqn, target, service.toString())
+            }
+            val rpcMap = rpcsByService.getOrPut(sFqn) { mutableMapOf() }
+            for (method in s.methods) {
+                val mname = method.name?.value ?: continue
+                val rpc = ReferenceElement(ReferenceElement.Kind.RPC, file, pkg, "$sname.$mname", service, method)
+                val mFqn = rpc.fqn
+                fileByFqn[mFqn] = protoFile
+                parentServiceOfRpc[mFqn] = sFqn
+                method.inputType?.value?.removePrefix(".")?.let { rpcInputOf[mFqn] = it }
+                method.outputType?.value?.removePrefix(".")?.let { rpcOutputOf[mFqn] = it }
+                val target = targetFor(rpc) ?: continue
+                qualified.put("$sname.$mname", target, rpc.toString())
+                qualified.put(mFqn, target, rpc.toString())
+                rpcMap[mname] = target
+            }
+        }
+    }
+
+    private fun indexMessage(
+        msg: DescriptorProtoWrapper,
+        file: FileDescriptorProtoWrapper,
+        pkg: String,
+        protoFile: String,
+        parent: ReferenceElement?,
+    ) {
+        if (msg.options?.mapEntry?.value == true) return
+        val short = msg.name?.value ?: return
+        val dotted = parent?.let { "${it.localName}.$short" } ?: short
+        val message = ReferenceElement(ReferenceElement.Kind.MESSAGE, file, pkg, dotted, parent, msg)
+        val fqn = message.fqn
+        fileByFqn[fqn] = protoFile
+        targetFor(message)?.let { target ->
+            typeTargetByFqn[fqn] = target
+            globalShortTypes.put(short, target, message.toString())
+            qualified.put(dotted, target, message.toString())
+            qualified.put(fqn, target, message.toString())
+            if (parent != null) nestedTypesByMessage.getOrPut(parent.fqn) { mutableMapOf() }[short] = target
+        }
+
+        val fieldMap = fieldsByMessage.getOrPut(fqn) { mutableMapOf() }
+        for (f in msg.fields) {
+            val fname = f.name?.value ?: continue
+            val field = ReferenceElement(ReferenceElement.Kind.FIELD, file, pkg, "$dotted.$fname", message, f)
+            val fFqn = field.fqn
+            fileByFqn[fFqn] = protoFile
+            parentMessageOfField[fFqn] = fqn
+            f.typeName?.value?.removePrefix(".")?.takeIf { it.isNotEmpty() }?.let { fieldTypeOf[fFqn] = it }
+            val target = targetFor(field) ?: continue
+            qualified.put("$short.$fname", target, field.toString())
+            if (parent != null) qualified.put("$dotted.$fname", target, field.toString())
+            qualified.put(fFqn, target, field.toString())
+            fieldMap[fname] = target
+        }
+
+        for (n in msg.nestedTypes) indexMessage(n, file, pkg, protoFile, message)
+        for (e in msg.enumTypes) indexEnum(e, file, pkg, protoFile, message)
+    }
+
+    private fun indexEnum(
+        enum: EnumDescriptorProtoWrapper,
+        file: FileDescriptorProtoWrapper,
+        pkg: String,
+        protoFile: String,
+        parent: ReferenceElement?,
+    ) {
+        val short = enum.name?.value ?: return
+        val dotted = parent?.let { "${it.localName}.$short" } ?: short
+        val element = ReferenceElement(ReferenceElement.Kind.ENUM, file, pkg, dotted, parent, enum)
+        val fqn = element.fqn
+        fileByFqn[fqn] = protoFile
+        targetFor(element)?.let { target ->
+            typeTargetByFqn[fqn] = target
+            globalShortTypes.put(short, target, element.toString())
+            qualified.put(dotted, target, element.toString())
+            qualified.put(fqn, target, element.toString())
+            if (parent != null) nestedTypesByMessage.getOrPut(parent.fqn) { mutableMapOf() }[short] = target
+        }
+
+        val valueMap = valuesByEnum.getOrPut(fqn) { mutableMapOf() }
+        for (v in enum.values) {
+            val vname = v.name?.value ?: continue
+            val value = ReferenceElement(ReferenceElement.Kind.ENUM_VALUE, file, pkg, "$dotted.$vname", element, v)
+            val vFqn = value.fqn
+            fileByFqn[vFqn] = protoFile
+            parentEnumOfValue[vFqn] = fqn
+            val target = targetFor(value) ?: continue
+            qualified.put("$short.$vname", target, value.toString())
+            if (parent != null) qualified.put("$dotted.$vname", target, value.toString())
+            qualified.put(vFqn, target, value.toString())
+            valueMap[vname] = target
+            globalShortEnumValues.put(vname, target, value.toString())
+        }
+    }
+
+    private fun bareScopeOutcome(
+        label: String,
+        scopeFqn: String,
+    ): Outcome<T>? {
+        if (scopeFqn.isEmpty()) return null
+        val sources = bareScopeSources(scopeFqn) ?: return null
+        val hits = sources.mapNotNull { (sourceLabel, map) -> map[label]?.let { sourceLabel to it } }
+        return when {
+            hits.isEmpty() -> null
+            hits.distinctBy { it.second }.size == 1 -> Outcome.Resolved(hits[0].second)
+            else -> Outcome.Ambiguous(hits[0].second, hits.map { "${it.first} → ${describe(it.second)}" })
+        }
+    }
+
+    private fun bareScopeSources(scopeFqn: String): List<Pair<String, Map<String, T>>>? {
+        fieldsByMessage[scopeFqn]?.let { fields ->
+            return buildList {
+                add("field of $scopeFqn" to fields)
+                nestedTypesByMessage[scopeFqn]?.let { add("nested type of $scopeFqn" to it) }
+            }
+        }
+        valuesByEnum[scopeFqn]?.let { return listOf("value of $scopeFqn" to it) }
+        rpcsByService[scopeFqn]?.let { return listOf("rpc of $scopeFqn" to it) }
+        parentMessageOfField[scopeFqn]?.let { parentMessage ->
+            return buildList {
+                fieldsByMessage[parentMessage]?.let { add("sibling field in $parentMessage" to it) }
+                fieldTypeOf[scopeFqn]?.let { type ->
+                    fieldsByMessage[type]?.let { add("field of referenced type $type" to it) }
+                    typeSource("declared type of $scopeFqn", type)?.let(::add)
+                }
+            }
+        }
+        parentEnumOfValue[scopeFqn]?.let { parentEnum ->
+            valuesByEnum[parentEnum]?.let { return listOf("sibling value in $parentEnum" to it) }
+        }
+        parentServiceOfRpc[scopeFqn]?.let { parentService ->
+            return buildList {
+                rpcsByService[parentService]?.let { add("sibling rpc in $parentService" to it) }
+                rpcInputOf[scopeFqn]?.let { input ->
+                    fieldsByMessage[input]?.let { add("field of input $input" to it) }
+                    typeSource("input type of $scopeFqn", input)?.let(::add)
+                }
+                rpcOutputOf[scopeFqn]?.let { output ->
+                    fieldsByMessage[output]?.let { add("field of output $output" to it) }
+                    typeSource("output type of $scopeFqn", output)?.let(::add)
+                }
+            }
+        }
+        return null
+    }
+
+    /** A bare-scope source holding [typeFqn]'s target under its short name, or `null` when the type isn't indexed. */
+    private fun typeSource(
+        sourceLabel: String,
+        typeFqn: String,
+    ): Pair<String, Map<String, T>>? = typeTargetByFqn[typeFqn]?.let { sourceLabel to mapOf(typeFqn.substringAfterLast('.') to it) }
+
+    /**
+     * A `key → target` map that remembers every owner registering each key, so a key claimed by two
+     * distinct targets resolves as [Outcome.Ambiguous] instead of silently keeping one.
+     */
+    private inner class AmbiguityAwareMap(private val mapLabel: String) {
+        private val targetByKey = mutableMapOf<String, T>()
+        private val candidatesByKey = mutableMapOf<String, MutableList<Pair<String, T>>>()
+
+        fun put(
+            key: String,
+            target: T,
+            owner: String,
+        ) {
+            val candidates = candidatesByKey.getOrPut(key) { mutableListOf() }
+            if (candidates.any { it.first == owner && it.second == target }) return
+            candidates += owner to target
+            val prior = targetByKey[key]
+            if (prior != null && prior != target && log.isTraceEnabled) {
+                log.trace(
+                    "reference-link key '{}' in {} is ambiguous — '{}' collides with a prior entry resolving to '{}'; " +
+                        "keeping the latest.  Use a qualified form to disambiguate in comments.",
+                    key,
+                    mapLabel,
+                    owner,
+                    describe(prior),
+                )
+            }
+            targetByKey[key] = target
+        }
+
+        fun lookup(key: String): Outcome<T> {
+            val target = targetByKey[key] ?: return Outcome.Unresolved
+            val candidates = candidatesByKey[key].orEmpty()
+            return if (candidates.map { it.second }.distinct().size <= 1) {
+                Outcome.Resolved(target)
+            } else {
+                Outcome.Ambiguous(target, candidates.map { "${it.first} → ${describe(it.second)}" })
+            }
+        }
+    }
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkFailure.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkFailure.kt
new file mode 100644
index 0000000..574eb01
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkFailure.kt
@@ -0,0 +1,55 @@
+package com.engine.protoc.util.markdown
+
+/**
+ * A doc-comment reference link that did not resolve cleanly.
+ */
+public data class ReferenceLinkFailure(
+    /** The proto file declaring the descriptor whose comment holds the reference. */
+    val protoFile: String,
+    /** The FQN of the descriptor whose comment holds the reference, or `""` for no scope. */
+    val scopeFqn: String,
+    /** The bracketed lookup label. */
+    val label: String,
+    /** Why the reference failed. */
+    val reason: Reason,
+) {
+    /** Why a reference failed to resolve. */
+    public sealed interface Reason {
+        /** A human-readable description of the reason. */
+        public val description: String
+
+        /** Nothing in the compile scope matches the label. */
+        public data object Unresolved : Reason {
+            override val description: String = "no matching type, field, enum value, or RPC in compile scope"
+        }
+
+        /** More than one distinct target matches the label. */
+        public data class Ambiguous(val candidates: List<String>) : Reason {
+            override val description: String get() = "ambiguous; candidates: ${candidates.joinToString("; ")}"
+        }
+    }
+
+    public companion object {
+        /**
+         * A multi-line summary of [failures], suitable for `CodeGeneratorResponse.error`: a count
+         * line followed by one `  - file :: scope :: [label] — reason` bullet per failure.
+         */
+        public fun summary(failures: List<ReferenceLinkFailure>): String =
+            buildString {
+                append(failures.size)
+                append(if (failures.size == 1) " reference-link failure under " else " reference-link failures under ")
+                appendLine("resolveReferenceLinksMode=FAIL_ON_INVALID:")
+                for (f in failures) {
+                    append("  - ")
+                    append(f.protoFile)
+                    append(" :: ")
+                    append(f.scopeFqn.ifEmpty { "(file scope)" })
+                    append(" :: [")
+                    append(f.label)
+                    append("] — ")
+                    append(f.reason.description)
+                    appendLine()
+                }
+            }
+    }
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkMode.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkMode.kt
new file mode 100644
index 0000000..fe8eca4
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkMode.kt
@@ -0,0 +1,18 @@
+package com.engine.protoc.util.markdown
+
+/**
+ * How a plugin treats CommonMark reference links (`[Name]`, `[text][Name]`) in doc comments.
+ */
+public enum class ReferenceLinkMode {
+    /** References are not resolved; the comment text is left as written, brackets included. */
+    NONE,
+
+    /** References are resolved; each unresolved or ambiguous reference is logged at `warn`. */
+    WARN,
+
+    /**
+     * References are resolved; each unresolved or ambiguous reference is logged at `error` and
+     * collected as a [ReferenceLinkFailure] so the plugin can fail the protoc run.
+     */
+    FAIL_ON_INVALID,
+}
diff --git a/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkProcessor.kt b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkProcessor.kt
new file mode 100644
index 0000000..deae80a
--- /dev/null
+++ b/markdown/src/main/kotlin/com/engine/protoc/util/markdown/ReferenceLinkProcessor.kt
@@ -0,0 +1,186 @@
+package com.engine.protoc.util.markdown
+
+import org.commonmark.node.Code
+import org.commonmark.node.Link
+import org.commonmark.parser.InlineParserContext
+import org.commonmark.parser.beta.LinkInfo
+import org.commonmark.parser.beta.LinkProcessor
+import org.commonmark.parser.beta.LinkResult
+import org.commonmark.parser.beta.Scanner
+import org.slf4j.LoggerFactory
+
+private val log = LoggerFactory.getLogger(ReferenceLinkProcessor::class.java)
+
+/**
+ * How a resolved reference is written into the parsed document.
+ */
+public sealed interface ReferenceRendering {
+    /** Wrap the reference text in a link to [destination]. */
+    public data class Link(val destination: String) : ReferenceRendering
+
+    /** Replace the reference with an inline code span of its text, for elements with no addressable target. */
+    public data object Code : ReferenceRendering
+}
+
+/**
+ * How an unresolved reference is written into the parsed document.
+ */
+public enum class UnresolvedReferenceRendering {
+    /** Leave the brackets as literal text, so the failure is visible in the output. */
+    LITERAL,
+
+    /** Replace the reference with an inline code span of its text. */
+    CODE,
+}
+
+/**
+ * A CommonMark [LinkProcessor] that resolves proto reference links in doc comments against a
+ * [ReferenceIndex].
+ *
+ * Shortcut (`[label]`), collapsed (`[label][]`), and full (`[text][label]`) reference links are
+ * resolved; in the full form `label` is the lookup key and `text` stays as the visible text.
+ * Inline links (`[text](url)`), images, code spans, and escaped brackets are left to the core
+ * CommonMark parser.  Labels in [overrides] resolve to their URL before the index is consulted,
+ * which is how references to types outside the compile scope (e.g. `[google.rpc.Status]`) link
+ * to external documentation.
+ *
+ * Resolution is bound to the descriptor whose comment is being parsed: wrap each parse in
+ * [withScope].  Under [ReferenceLinkMode.NONE] the processor leaves every link to the core parser.
+ */
+public class ReferenceLinkProcessor<T : Any>(
+    private val index: ReferenceIndex<T>,
+    private val mode: ReferenceLinkMode,
+    private val overrides: Map<String, String> = emptyMap(),
+    private val unresolvedRendering: UnresolvedReferenceRendering = UnresolvedReferenceRendering.LITERAL,
+    private val render: (T) -> ReferenceRendering,
+) : LinkProcessor {
+    private var currentScope: String = ""
+    private val failures = mutableListOf<ReferenceLinkFailure>()
+
+    /** True when the processor rewrote at least one reference since the last [withScope] began. */
+    public var touched: Boolean = false
+        private set
+
+    /**
+     * Run [block] (typically a `parser.parse(...)` call) with references resolving relative to the
+     * descriptor [scopeFqn] (without a leading dot), or `""` for no scope.  Resets [touched].
+     */
+    public fun <R> withScope(
+        scopeFqn: String,
+        block: () -> R,
+    ): R {
+        currentScope = scopeFqn
+        touched = false
+        return try {
+            block()
+        } finally {
+            currentScope = ""
+        }
+    }
+
+    /** Return and clear the failures recorded under [ReferenceLinkMode.FAIL_ON_INVALID]. */
+    public fun drainFailures(): List<ReferenceLinkFailure> {
+        val out = failures.toList()
+        failures.clear()
+        return out
+    }
+
+    override fun process(
+        linkInfo: LinkInfo,
+        scanner: Scanner,
+        context: InlineParserContext,
+    ): LinkResult? {
+        if (mode == ReferenceLinkMode.NONE) return LinkResult.none()
+        if (linkInfo.destination() != null || linkInfo.marker() != null) return LinkResult.none()
+        val rawLabel = linkInfo.label()
+        val text = linkInfo.text()
+        // shortcut `[text]` → label null; collapsed `[text][]` → label "" — both use text as the key.
+        val key = if (rawLabel.isNullOrEmpty()) text else rawLabel
+        if (key.isEmpty()) return LinkResult.none()
+        val scopeFqn = currentScope
+
+        overrides[key]?.let { url ->
+            touched = true
+            return LinkResult.wrapTextIn(Link(url, null), scanner.position())
+        }
+
+        val outcome = index.resolve(key, scopeFqn)
+        if (log.isTraceEnabled) {
+            log.trace(
+                "reference-link [{}] identified in {} :: {} — {}",
+                key,
+                index.fileOf(scopeFqn) ?: "(unknown)",
+                scopeFqn.ifEmpty { "(file scope)" },
+                outcome,
+            )
+        }
+        return when (outcome) {
+            is ReferenceIndex.Outcome.Resolved -> rendered(render(outcome.target), text, scanner)
+
+            is ReferenceIndex.Outcome.Ambiguous -> {
+                reportFailure(scopeFqn, key, ReferenceLinkFailure.Reason.Ambiguous(outcome.candidates))
+                rendered(render(outcome.target), text, scanner)
+            }
+
+            ReferenceIndex.Outcome.Unresolved -> {
+                reportFailure(scopeFqn, key, ReferenceLinkFailure.Reason.Unresolved)
+                when (unresolvedRendering) {
+                    UnresolvedReferenceRendering.LITERAL -> LinkResult.none()
+                    UnresolvedReferenceRendering.CODE -> rendered(ReferenceRendering.Code, text, scanner)
+                }
+            }
+        }
+    }
+
+    private fun rendered(
+        rendering: ReferenceRendering,
+        text: String,
+        scanner: Scanner,
+    ): LinkResult {
+        touched = true
+        return when (rendering) {
+            is ReferenceRendering.Link -> LinkResult.wrapTextIn(Link(rendering.destination, null), scanner.position())
+            ReferenceRendering.Code -> LinkResult.replaceWith(Code(text), scanner.position())
+        }
+    }
+
+    private fun reportFailure(
+        scopeFqn: String,
+        label: String,
+        reason: ReferenceLinkFailure.Reason,
+    ) {
+        val protoFile = index.fileOf(scopeFqn) ?: "(unknown)"
+        val scopeDescription = scopeFqn.ifEmpty { "(file scope)" }
+        when (mode) {
+            ReferenceLinkMode.NONE -> Unit
+
+            ReferenceLinkMode.WARN ->
+                log.warn("reference-link [{}] in {} :: {} — {}", label, protoFile, scopeDescription, reason.description)
+
+            ReferenceLinkMode.FAIL_ON_INVALID -> {
+                log.error("reference-link [{}] in {} :: {} — {}", label, protoFile, scopeDescription, reason.description)
+                failures += ReferenceLinkFailure(protoFile, scopeFqn, label, reason)
+            }
+        }
+    }
+
+    public companion object {
+        /**
+         * Parse repeated `<label>=<URL>` plugin parameter entries into an ordered override map.
+         *
+         * @throws IllegalArgumentException when an entry has no `=`, an empty label, or an empty URL.
+         */
+        public fun parseOverrides(entries: List<String>?): Map<String, String> {
+            if (entries.isNullOrEmpty()) return emptyMap()
+            val map = LinkedHashMap<String, String>()
+            for (entry in entries) {
+                val idx = entry.indexOf('=')
+                require(idx > 0 && idx < entry.length - 1) {
+                    "referenceLink entry must be of the form <label>=<URL>, got `$entry`"
+                }
+                map[entry.substring(0, idx)] = entry.substring(idx + 1)
+            }
+            return map
+        }
+    }
+}
diff --git a/markdown/src/test/kotlin/ReferenceLinkTests.kt b/markdown/src/test/kotlin/ReferenceLinkTests.kt
new file mode 100644
index 0000000..f47bec4
--- /dev/null
+++ b/markdown/src/test/kotlin/ReferenceLinkTests.kt
@@ -0,0 +1,263 @@
+import com.engine.protoc.util.extensions.wrap
+import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+import com.engine.protoc.util.markdown.MarkdownText
+import com.engine.protoc.util.markdown.ReferenceElement
+import com.engine.protoc.util.markdown.ReferenceIndex
+import com.engine.protoc.util.markdown.ReferenceLinkFailure
+import com.engine.protoc.util.markdown.ReferenceLinkMode
+import com.engine.protoc.util.markdown.ReferenceLinkProcessor
+import com.engine.protoc.util.markdown.ReferenceRendering
+import com.engine.protoc.util.markdown.UnresolvedReferenceRendering
+import com.google.protobuf.DescriptorProtos.DescriptorProto
+import com.google.protobuf.DescriptorProtos.EnumDescriptorProto
+import com.google.protobuf.DescriptorProtos.EnumValueDescriptorProto
+import com.google.protobuf.DescriptorProtos.FieldDescriptorProto
+import com.google.protobuf.DescriptorProtos.FileDescriptorProto
+import com.google.protobuf.DescriptorProtos.MethodDescriptorProto
+import com.google.protobuf.DescriptorProtos.ServiceDescriptorProto
+import com.google.protobuf.compiler.PluginProtos
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.collections.shouldBeEmpty
+import io.kotest.matchers.collections.shouldHaveSize
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+import org.commonmark.parser.Parser
+
+private fun field(
+    name: String,
+    typeName: String? = null,
+): FieldDescriptorProto =
+    FieldDescriptorProto.newBuilder().setName(name).setNumber(1).apply {
+        if (typeName != null) {
+            setType(FieldDescriptorProto.Type.TYPE_MESSAGE)
+            setTypeName(typeName)
+        } else {
+            setType(FieldDescriptorProto.Type.TYPE_STRING)
+        }
+    }.build()
+
+private fun enum(
+    name: String,
+    vararg values: String,
+): EnumDescriptorProto =
+    EnumDescriptorProto.newBuilder().setName(name).apply {
+        values.forEachIndexed { i, v -> addValue(EnumValueDescriptorProto.newBuilder().setName(v).setNumber(i)) }
+    }.build()
+
+private val widgetFile: FileDescriptorProto =
+    FileDescriptorProto.newBuilder()
+        .setName("acme/widget.proto")
+        .setPackage("acme.v1")
+        .addMessageType(
+            DescriptorProto.newBuilder()
+                .setName("Widget")
+                .addField(field("name"))
+                .addField(field("gadget", ".acme.v1.Gadget"))
+                .addNestedType(DescriptorProto.newBuilder().setName("Part").addField(field("label")))
+                .addEnumType(enum("Color", "COLOR_UNKNOWN", "COLOR_RED")),
+        )
+        .addMessageType(DescriptorProto.newBuilder().setName("Gadget").addField(field("size")))
+        .addMessageType(DescriptorProto.newBuilder().setName("GetWidgetRequest").addField(field("widget_id")))
+        .addEnumType(enum("Status", "STATUS_UNKNOWN", "STATUS_ACTIVE"))
+        .addService(
+            ServiceDescriptorProto.newBuilder()
+                .setName("WidgetService")
+                .addMethod(
+                    MethodDescriptorProto.newBuilder()
+                        .setName("GetWidget")
+                        .setInputType(".acme.v1.GetWidgetRequest")
+                        .setOutputType(".acme.v1.Widget"),
+                ),
+        )
+        .build()
+
+// A second package that also declares a `Gadget`, to exercise ambiguity.
+private val otherFile: FileDescriptorProto =
+    FileDescriptorProto.newBuilder()
+        .setName("other/gadget.proto")
+        .setPackage("other.v1")
+        .addMessageType(DescriptorProto.newBuilder().setName("Gadget"))
+        .build()
+
+private fun files(vararg protos: FileDescriptorProto): List<FileDescriptorProtoWrapper> =
+    PluginProtos.CodeGeneratorRequest.newBuilder()
+        .addAllProtoFile(protos.toList())
+        .apply { protos.forEach { addFileToGenerate(it.name) } }
+        .build()
+        .wrap()
+        .protoFiles
+
+/** An index whose target is the element's own FQN, so every distinct element is a distinct target. */
+private fun fqnIndex(vararg protos: FileDescriptorProto): ReferenceIndex<String> = ReferenceIndex(files(*protos)) { it.fqn }
+
+private fun ReferenceIndex.Outcome<String>.target(): String? = (this as? ReferenceIndex.Outcome.Resolved)?.target
+
+class ReferenceIndexTests :
+    FunSpec({
+        val index = fqnIndex(widgetFile)
+
+        test("qualified labels resolve by FQN, package-relative name, and Type.member") {
+            index.resolve("acme.v1.Widget", "").target() shouldBe "acme.v1.Widget"
+            index.resolve("Widget.Part", "").target() shouldBe "acme.v1.Widget.Part"
+            index.resolve("Widget.name", "").target() shouldBe "acme.v1.Widget.name"
+            index.resolve("Part.label", "").target() shouldBe "acme.v1.Widget.Part.label"
+            index.resolve("Widget.Part.label", "").target() shouldBe "acme.v1.Widget.Part.label"
+            index.resolve("Status.STATUS_ACTIVE", "").target() shouldBe "acme.v1.Status.STATUS_ACTIVE"
+            index.resolve("WidgetService.GetWidget", "").target() shouldBe "acme.v1.WidgetService.GetWidget"
+        }
+
+        test("bare labels resolve to global short names of types and enum values") {
+            index.resolve("Widget", "").target() shouldBe "acme.v1.Widget"
+            index.resolve("WidgetService", "").target() shouldBe "acme.v1.WidgetService"
+            index.resolve("STATUS_ACTIVE", "").target() shouldBe "acme.v1.Status.STATUS_ACTIVE"
+        }
+
+        test("bare labels resolve to members of the comment's scope") {
+            index.resolve("name", "acme.v1.Widget").target() shouldBe "acme.v1.Widget.name"
+            index.resolve("Part", "acme.v1.Widget").target() shouldBe "acme.v1.Widget.Part"
+            index.resolve("gadget", "acme.v1.Widget.name").target() shouldBe "acme.v1.Widget.gadget"
+            index.resolve("size", "acme.v1.Widget.gadget").target() shouldBe "acme.v1.Gadget.size"
+            index.resolve("widget_id", "acme.v1.WidgetService.GetWidget").target() shouldBe "acme.v1.GetWidgetRequest.widget_id"
+            index.resolve("GetWidget", "acme.v1.WidgetService").target() shouldBe "acme.v1.WidgetService.GetWidget"
+            index.resolve("COLOR_RED", "acme.v1.Widget.Color.COLOR_UNKNOWN").target() shouldBe "acme.v1.Widget.Color.COLOR_RED"
+        }
+
+        test("bare member names don't resolve without a scope") {
+            index.resolve("name", "") shouldBe ReferenceIndex.Outcome.Unresolved
+            index.resolve("Nope", "") shouldBe ReferenceIndex.Outcome.Unresolved
+        }
+
+        test("a short name shared by two types is ambiguous unless the scope disambiguates it") {
+            val both = fqnIndex(widgetFile, otherFile)
+            val outcome = both.resolve("Gadget", "").shouldBeInstanceOf<ReferenceIndex.Outcome.Ambiguous<String>>()
+            outcome.candidates shouldBe listOf("message acme.v1.Gadget → acme.v1.Gadget", "message other.v1.Gadget → other.v1.Gadget")
+            both.resolve("Gadget", "acme.v1.Widget.gadget").target() shouldBe "acme.v1.Gadget"
+            both.resolve("other.v1.Gadget", "").target() shouldBe "other.v1.Gadget"
+        }
+
+        test("elements whose target is null are not indexed") {
+            val noFields = ReferenceIndex(files(widgetFile)) { it.takeIf { e -> e.kind != ReferenceElement.Kind.FIELD }?.fqn }
+            noFields.resolve("Widget.name", "") shouldBe ReferenceIndex.Outcome.Unresolved
+            noFields.resolve("Widget", "").target() shouldBe "acme.v1.Widget"
+        }
+
+        test("equal targets are not ambiguous") {
+            val byFile = ReferenceIndex(files(widgetFile, otherFile)) { "anchor" }
+            byFile.resolve("Gadget", "").target() shouldBe "anchor"
+        }
+
+        test("fileOf names the declaring file") {
+            index.fileOf("acme.v1.Widget.name") shouldBe "acme/widget.proto"
+        }
+    })
+
+class ReferenceLinkProcessorTests :
+    FunSpec({
+        val index = ReferenceIndex(files(widgetFile, otherFile)) { element ->
+            when (element.kind) {
+                ReferenceElement.Kind.ENUM_VALUE -> ReferenceRendering.Code
+                else -> ReferenceRendering.Link("#${element.fqn}")
+            }
+        }
+
+        fun processor(
+            mode: ReferenceLinkMode = ReferenceLinkMode.FAIL_ON_INVALID,
+            unresolved: UnresolvedReferenceRendering = UnresolvedReferenceRendering.CODE,
+        ) = ReferenceLinkProcessor(
+            index = index,
+            mode = mode,
+            overrides = mapOf("google.rpc.Status" to "https://example.com/status"),
+            unresolvedRendering = unresolved,
+        ) { it }
+
+        fun ReferenceLinkProcessor<ReferenceRendering>.render(
+            text: String,
+            scope: String = "",
+        ): String {
+            val parser = Parser.builder().linkProcessor(this).build()
+            return MarkdownText.render(withScope(scope) { parser.parse(text) })
+        }
+
+        test("resolved references become links and code spans") {
+            val p = processor()
+            p.render("See [Widget] and [the request][GetWidgetRequest].") shouldBe
+                "See [Widget](#acme.v1.Widget) and [the request](#acme.v1.GetWidgetRequest)."
+            p.render("Defaults to [STATUS_ACTIVE].") shouldBe "Defaults to `STATUS_ACTIVE`."
+            p.render("Bare [name] here.", "acme.v1.Widget") shouldBe "Bare [name](#acme.v1.Widget.name) here."
+            p.drainFailures().shouldBeEmpty()
+            p.touched shouldBe true
+        }
+
+        test("overrides win over the index and link outside the compile scope") {
+            processor().render("In [Status.details][google.rpc.Status].") shouldBe
+                "In [Status.details](https://example.com/status)."
+        }
+
+        test("inline links, code spans, and escaped brackets are untouched") {
+            val p = processor()
+            p.render("A [link](https://x.test), `[Widget]`, and \\[Widget\\].") shouldBe
+                "A [link](https://x.test), `[Widget]`, and \\[Widget\\]."
+            p.touched shouldBe false
+            p.drainFailures().shouldBeEmpty()
+        }
+
+        test("unresolved and ambiguous references are collected under FAIL_ON_INVALID") {
+            val p = processor()
+            p.render("See [Missing] and [Gadget].", "acme.v1.Widget.Part") shouldBe
+                "See `Missing` and [Gadget](#other.v1.Gadget)."
+            val failures = p.drainFailures()
+            failures shouldHaveSize 2
+            failures[0] shouldBe ReferenceLinkFailure("acme/widget.proto", "acme.v1.Widget.Part", "Missing", ReferenceLinkFailure.Reason.Unresolved)
+            failures[1].reason.shouldBeInstanceOf<ReferenceLinkFailure.Reason.Ambiguous>()
+            p.drainFailures().shouldBeEmpty()
+            ReferenceLinkFailure.summary(failures.take(1)) shouldBe
+                """
+                |1 reference-link failure under resolveReferenceLinksMode=FAIL_ON_INVALID:
+                |  - acme/widget.proto :: acme.v1.Widget.Part :: [Missing] — no matching type, field, enum value, or RPC in compile scope
+                |
+                """.trimMargin()
+        }
+
+        test("WARN resolves but collects nothing; LITERAL keeps unresolved brackets") {
+            val p = processor(ReferenceLinkMode.WARN, UnresolvedReferenceRendering.LITERAL)
+            // The renderer escapes the brackets it leaves as literal text.
+            p.render("See [Missing] and [Widget].") shouldBe "See \\[Missing\\] and [Widget](#acme.v1.Widget)."
+            p.drainFailures().shouldBeEmpty()
+        }
+
+        test("NONE leaves every reference as written") {
+            val p = processor(ReferenceLinkMode.NONE)
+            p.render("See [Missing] and [Widget].") shouldBe "See \\[Missing\\] and \\[Widget\\]."
+            p.touched shouldBe false
+        }
+
+        test("parseOverrides keeps order and rejects malformed entries") {
+            ReferenceLinkProcessor.parseOverrides(listOf("a=b", "c.d=https://x/y=z")) shouldBe mapOf("a" to "b", "c.d" to "https://x/y=z")
+            ReferenceLinkProcessor.parseOverrides(null) shouldBe emptyMap()
+            shouldThrow<IllegalArgumentException> { ReferenceLinkProcessor.parseOverrides(listOf("novalue=")) }
+            shouldThrow<IllegalArgumentException> { ReferenceLinkProcessor.parseOverrides(listOf("=nolabel")) }
+        }
+    })
+
+class MarkdownTextTests :
+    FunSpec({
+        val parser = Parser.builder().build()
+
+        test("toPlainText drops Markdown syntax") {
+            MarkdownText.toPlainText(
+                parser.parse("Returns a *new* [Widget](#w) for `widget_id`,\nor ![an icon](i.png) **never**."),
+            ) shouldBe "Returns a new Widget for widget_id, or an icon never."
+        }
+
+        test("firstSentence keeps only the first sentence of the first paragraph") {
+            MarkdownText.firstSentence(parser.parse("Gets a [Widget], e.g. v1.2 widgets. More text.\n\nSecond paragraph.")) shouldBe
+                "Gets a [Widget], e.g. v1.2 widgets."
+            MarkdownText.firstSentence(parser.parse("- a list\n- of items")) shouldBe "a list of items"
+            MarkdownText.firstSentence(parser.parse("")) shouldBe ""
+        }
+
+        test("render trims trailing whitespace") {
+            MarkdownText.render(parser.parse("*line one*   \n\n\n")) shouldBe "*line one*"
+        }
+    })