blockwatch-cli 0.11.3__tar.gz → 0.12.0__tar.gz

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/CHANGELOG.md

@@ -12,6 +12,38 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.12.0] - 2026-10-15
+
+### Changed
+
+- A `blockwatch-suppress:` line with no address now fails the run with `invalid suppression address`. Before,
+  blockwatch ignored it.
+- Messages now show a non-ASCII key in a symbol path as written, such as `data.toml#/täble/key`. Before, they showed
+  `data.toml#/t%C3%A4ble/key`. An `affects` or `same-as` violation on such a key gets a new hash, so update any
+  `--suppress` address with four parts that points at it.
+
+### Fixed
+
+- `--suppress-from` no longer crashes on a line with a non-ASCII character, such as `❌` or `—`, near its start.
+  Before, such a line could make blockwatch exit with code 101, even when the code had no violations
+  ([#172](https://github.com/mennanov/blockwatch/issues/172)).
+- blockwatch no longer crashes on a file that holds a tag and one of these:
+  - in Scala, a `/*` comment that is never closed;
+  - in Markdown, a `[//]:` line with no title, such as `[//]: #`, or with a quote in its destination, such as
+    `[//]: it's (text)`.
+- In Markdown, a tag in a `[//]:` title that starts on the next line is now reported on that line. Before, it was
+  reported on the `[//]:` line.
+- A Lua error in a `check-lua` script now shows the script and the line, such as `check.lua:3:`. Before, it showed a
+  file of blockwatch's own source code: `src/validators/check_lua.rs:309:3:`.
+- `blockwatch list`, the JSON violations and the SARIF log now come out in the same order on every run. Files are
+  sorted by path, and the violations in a file by line, column and validator. Before, the order changed from run to
+  run.
+- A pattern with its `value` group in one branch, such as `^(?:none|(?P<value>\w+))$`, now skips a match of the other
+  branch, such as `none`. This applies to `keep-sorted-pattern`, `keep-unique`, `same-as-pattern`, `check-ai-pattern`
+  and `check-lua-pattern`. Before, such a match gave its whole text as a value, so `keep-unique` could report a false
+  duplicate ([#173](https://github.com/mennanov/blockwatch/issues/173)). A `target-pattern` match like that now stops
+  the run. Before, the block's content was the whole match.
+
 ## [0.11.3] - 2026-10-15
 
 ### Fixed

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/Cargo.lock

@@ -274,7 +274,7 @@ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "blockwatch"
-version = "0.11.3"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "assert-json-diff",

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.11.3"
+version = "0.12.0"
 edition = "2024"
 repository = "https://github.com/mennanov/blockwatch"
 description = "Language agnostic linter that keeps your code and documentation in sync and valid"

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.11.3
+Version: 0.12.0
 Summary: Language agnostic linter that keeps your code and documentation in sync and valid
 Keywords: linter,sync,drift,comments,agents
 Home-Page: https://github.com/mennanov/blockwatch

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/README.md

@@ -214,7 +214,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.11.3  # Use latest release
+  rev: v0.12.0  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/docs/ci.md

@@ -19,7 +19,7 @@ To use [pre-commit](https://pre-commit.com), add the hook to `.pre-commit-config
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.11.3  # Use latest release
+  rev: v0.12.0  # Use latest release
   hooks:
     - id: blockwatch
 ```
@@ -59,7 +59,7 @@ The `blockwatch` hook runs before the commit message exists, so it cannot see a
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.11.3  # Use latest release
+  rev: v0.12.0  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/docs/cli.md

@@ -394,6 +394,7 @@ same-as-pattern = 'os\.environ\["(?P<value>[A-Z_]+)"\]'
 - **A match can span lines with `(?s)`.** `(?s)^CREATE TABLE users \(.*?^\);` matches the whole statement. Write
   `.*?`, not `.*`. A `.*` runs to the last `);` in the file, and that still counts as one match.
 - **A `value` group picks the content**, as in the `*-pattern` attributes. Without one, the content is the whole match.
+  A match of a branch without the group stops the run, such as `MODEL = none` for `^MODEL = (?:none|"(?P<value>.+)")`.
 
 A virtual block is a block of the file it wraps:
 
@@ -554,15 +555,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.11.3",
-          "semanticVersion": "0.11.3",
+          "version": "0.12.0",
+          "semanticVersion": "0.12.0",
           "informationUri": "https://github.com/mennanov/blockwatch",
           "rules": [
             {
               "id": "keep-sorted",
               "name": "keep-sorted",
               "shortDescription": { "text": "Requires the lines of a block to stay in order." },
-              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.11.3/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.12.0/docs/validators/keep-sorted.md"
             }
           ]
         }

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/docs/validators/keep-sorted.md

@@ -93,7 +93,8 @@ A separator must sit between two digits — `_1`, `1_`, `1__0` and `1_.0` are ty
 ## Notes
 
 - Blank lines and lines the pattern does not match are ignored, not treated as out of order. A line whose match is empty
-  is ignored as well.
+  is ignored as well. So is a line that matches a branch without the `value` group: `^(?:none|(?P<value>\w+))$`
+  ignores the line `none`.
 - Comparison is on the trimmed line, so indentation does not affect ordering. A pattern is applied to the trimmed line
   too, so `^` and `$` anchor to the entry rather than to the indentation.
 - An unrecognized `keep-sorted` or `keep-sorted-format` value is a hard error, not a violation.

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/docs/validators/keep-unique.md

@@ -36,7 +36,8 @@ ids = [
 ```
 
 Without a `value` group the whole match is compared. Lines that do not match are skipped, as are
-lines whose match is empty.
+lines whose match is empty. So is a line that matches a branch without the `value` group: `^(?:none|(?P<value>\w+))$`
+skips the line `none`.
 
 ## Notes
 

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/docs/validators/same-as.md

@@ -56,8 +56,9 @@ Usually, though, the two places don't hold the same text. Then each block says *
 ## Pick values with `same-as-pattern`
 
 Each block has its own regex. Every match is a value: the `(?P<value>…)` group if there is one, otherwise the whole
-match. A line can hold several values. Lines without a match are skipped, and so are empty matches. This lets you
-compare blocks written in different formats:
+match. A line can hold several values. Lines without a match are skipped, and so are empty matches. So is a match of a
+branch without the `value` group: `^(?:none|(?P<value>\w+))$` skips the line `none`. This lets you compare blocks
+written in different formats:
 
 ```rust
 // <block same-as="README.md:supported-env-vars" same-as-pattern="BLOCKWATCH_AI_[A-Z_]+">

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/setup.py

@@ -6,7 +6,7 @@ setup(
     name='blockwatch-pre-commit-placeholder',
     version='0.0.0',
     # <block name="blockwatch-cli-version" same-as-pattern="blockwatch-cli==(?P<value>\d+\.\d+\.\d+)">
-    install_requires=['blockwatch-cli==0.11.3'],
+    install_requires=['blockwatch-cli==0.12.0'],
     # </block>
     # Without it, setuptools takes the directories under src/ for Python packages.
     packages=[],

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/block_parser.rs

@@ -206,6 +206,10 @@ impl<'source, I: Iterator<Item = Comment>> PartialBlocksIterator<'source, I> {
     fn take_adjacent_comment(&mut self, comment: &Comment) -> Option<Comment> {
         let contents = self.contents;
         self.comments.next_if(|next| {
+            #[expect(
+                clippy::string_slice,
+                reason = "parsers give comment ranges of whole characters"
+            )]
             contents[comment.source_range.end..next.source_range.start]
                 .trim()
                 .is_empty()
@@ -217,6 +221,10 @@ impl<'source, I: Iterator<Item = Comment>> PartialBlocksIterator<'source, I> {
 fn join_comments(comment: Comment, next: Comment, contents: &str) -> Comment {
     // The text between the comments is copied from the source, so an offset into the joined text
     // maps onto the source as it does for a single comment.
+    #[expect(
+        clippy::string_slice,
+        reason = "parsers give comment ranges of whole characters"
+    )]
     let between = &contents[comment.source_range.end..next.source_range.start];
     Comment {
         position_range: comment.position_range.start..next.position_range.end,
@@ -315,9 +323,14 @@ impl BlockStart {
     /// Columns count characters, so the offset is converted by counting the characters it skips
     /// rather than the bytes: the two differ on any line holding a multi-byte character.
     fn source_position_at(position_in_comment: usize, comment: &Comment) -> Position {
+        #[expect(
+            clippy::string_slice,
+            reason = "a tag starts at a `<` and ends after a `>`"
+        )]
         let text_before = &comment.comment_text[..position_in_comment];
         match text_before.rfind('\n') {
             // Past the comment's first line, so the column is measured from that line's start.
+            #[expect(clippy::string_slice, reason = "`line_break` is the index of a `\\n`")]
             Some(line_break) => Position::new(
                 comment.position_range.start.line + text_before.matches('\n').count(),
                 text_before[line_break + 1..].chars().count() + 1,

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/blocks.rs

@@ -166,6 +166,10 @@ impl Content {
     /// Returns the content's text. `source` must be the text of the block's file.
     pub(crate) fn text<'a>(&'a self, source: &'a str) -> &'a str {
         match &self.text {
+            #[expect(
+                clippy::string_slice,
+                reason = "a comment, a symbol or a match sets `range`"
+            )]
             ContentText::Source(range) => &source[range.clone()],
             ContentText::Decoded(text) => text,
         }
@@ -1002,6 +1006,7 @@ pub(crate) fn parser_for_file_path<'p>(
     let file_name = file_path.file_name()?.to_str()?;
 
     for (i, _) in file_name.match_indices('.').rev() {
+        #[expect(clippy::string_slice, reason = "`i` is the index of a `.`")]
         let extension = &file_name[i + 1..];
         let ext_os = OsString::from(extension);
 

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/cli.rs

@@ -16,7 +16,7 @@ use crate::violation_address::ViolationAddress;
 use crate::virtual_blocks::VirtualBlock;
 use anyhow::Context;
 use clap::Parser;
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
 use std::io::{IsTerminal, Read, Write};
 use std::path::PathBuf;
 use std::process::ExitCode;
@@ -147,7 +147,7 @@ fn run_validators(args: &flags::Args) -> anyhow::Result<ExitCode> {
 /// both leave one behind, and neither says anything about the code being checked.
 fn apply_suppressions(
     suppressed_addresses: &[ViolationAddress],
-    violations: &mut HashMap<RepoPath, Vec<Violation>>,
+    violations: &mut BTreeMap<RepoPath, Vec<Violation>>,
 ) {
     if suppressed_addresses.is_empty() {
         return;
@@ -329,7 +329,7 @@ fn read_diff_from_stdin(
 /// Writes the violations to stderr in the requested format. Returns true if any violation has error
 /// severity.
 fn process_violations(
-    violations: &HashMap<RepoPath, Vec<Violation>>,
+    violations: &BTreeMap<RepoPath, Vec<Violation>>,
     format: flags::OutputFormat,
 ) -> anyhow::Result<bool> {
     let has_error_severity = violations.values().flatten().any(|violation| {
@@ -348,9 +348,10 @@ fn process_violations(
     Ok(has_error_severity)
 }
 
-/// Writes the violations to stderr as one JSON object of diagnostics grouped by file.
-fn write_json_violations(violations: &HashMap<RepoPath, Vec<Violation>>) -> anyhow::Result<()> {
-    let diagnostics: HashMap<&RepoPath, Vec<_>> = violations
+/// Writes the violations to stderr as one JSON object of diagnostics grouped by file, with the
+/// files sorted by path.
+fn write_json_violations(violations: &BTreeMap<RepoPath, Vec<Violation>>) -> anyhow::Result<()> {
+    let diagnostics: BTreeMap<&RepoPath, Vec<_>> = violations
         .iter()
         .map(|(file_path, file_violations)| {
             let file_diagnostics = file_violations
@@ -364,7 +365,7 @@ fn write_json_violations(violations: &HashMap<RepoPath, Vec<Violation>>) -> anyh
 }
 
 /// Writes the violations to stderr as a SARIF log.
-fn write_sarif_violations(violations: &HashMap<RepoPath, Vec<Violation>>) -> anyhow::Result<()> {
+fn write_sarif_violations(violations: &BTreeMap<RepoPath, Vec<Violation>>) -> anyhow::Result<()> {
     write_json(std::io::stderr(), &sarif::SarifLog::new(violations))
 }
 

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/flags.rs

@@ -377,13 +377,15 @@ fn parse_suppressions(content: &str, path: &Path) -> anyhow::Result<Vec<Violatio
     let mut addresses = Vec::new();
     for (line_idx, line) in content.lines().enumerate() {
         let trimmed = line.trim();
-        if trimmed.len() <= SUPPRESS_TRAILER_PREFIX.len()
-            || !trimmed[..SUPPRESS_TRAILER_PREFIX.len()]
-                .eq_ignore_ascii_case(SUPPRESS_TRAILER_PREFIX)
+        // Bytes, because the prefix's length can fall inside a multi-byte character.
+        if trimmed.len() < SUPPRESS_TRAILER_PREFIX.len()
+            || !trimmed.as_bytes()[..SUPPRESS_TRAILER_PREFIX.len()]
+                .eq_ignore_ascii_case(SUPPRESS_TRAILER_PREFIX.as_bytes())
         {
             // Non-matching line.
             continue;
         }
+        #[expect(clippy::string_slice, reason = "the prefix just matched is ASCII")]
         let address_str = trimmed[SUPPRESS_TRAILER_PREFIX.len()..].trim();
         let address = ViolationAddress::parse(address_str).with_context(|| {
             format!(
@@ -600,6 +602,36 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn multibyte_character_across_prefix_length_is_ignored() -> anyhow::Result<()> {
+        // `é` is 2 bytes: 19 and 20. The trailer prefix is 20 bytes long.
+        let content = format!(
+            "{0}é\n\
+             {0}é and more text\n\
+             blockwatch-suppress: docs/cli.md:cli-docs:keep-sorted\n",
+            "a".repeat(19)
+        );
+
+        assert_eq!(
+            parse_suppressions(&content, Path::new("commit_msg.txt"))?
+                .iter()
+                .map(ToString::to_string)
+                .collect::<Vec<_>>(),
+            vec!["docs/cli.md:cli-docs:keep-sorted".to_string()]
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn trailer_without_address_fails() {
+        let error = parse_suppressions("blockwatch-suppress:\n", Path::new("commit_msg.txt"))
+            .expect_err("a trailer without an address must be rejected");
+        assert!(
+            error.to_string().contains("invalid suppression address"),
+            "unexpected error: {error}"
+        );
+    }
+
     #[test]
     fn suppress_from_with_nonexistent_file_fails_validation() -> anyhow::Result<()> {
         let args = parse(&["blockwatch", "--suppress-from", "nonexistent_file.txt"])?;

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/bash.rs

@@ -1,5 +1,6 @@
 use crate::language_parsers::{
     CommentsParser, LanguageParser, LanguageParserImpl, TreeSitterCommentsParser, comment_visitor,
+    node_text,
 };
 
 /// Returns a [`LanguageParser`] for Bash.
@@ -15,7 +16,7 @@ fn comments_parser() -> anyhow::Result<impl CommentsParser> {
             if node.kind() != "comment" {
                 return None;
             }
-            let comment = &source[node.byte_range()];
+            let comment = node_text(node, source);
             if comment.starts_with("#!") {
                 // Skip shebang.
                 None

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/cmake.rs

@@ -1,5 +1,6 @@
 use crate::language_parsers::{
     CommentsParser, LanguageParser, LanguageParserImpl, TreeSitterCommentsParser, comment_visitor,
+    node_text,
 };
 use tree_sitter::Node;
 
@@ -13,8 +14,8 @@ fn comments_parser() -> anyhow::Result<impl CommentsParser> {
     let parser = TreeSitterCommentsParser::new(
         &cmake_language,
         comment_visitor(|node, source_code| match node.kind() {
-            "line_comment" => Some(source_code[node.byte_range()].replacen('#', " ", 1)),
-            "bracket_comment" => Some(bracket_comment_text(node, &source_code[node.byte_range()])),
+            "line_comment" => Some(node_text(node, source_code).replacen('#', " ", 1)),
+            "bracket_comment" => Some(bracket_comment_text(node, node_text(node, source_code))),
             _ => None,
         }),
     );
@@ -31,6 +32,10 @@ fn bracket_comment_text(node: &Node, comment: &str) -> String {
         .map(|child| child.start_byte() - node.start_byte()..child.end_byte() - node.start_byte())
         .unwrap_or(0..0);
     let mut result = " ".repeat(content_range.start);
+    #[expect(
+        clippy::string_slice,
+        reason = "`content_range` is a tree-sitter node's range"
+    )]
     result.push_str(&comment[content_range.clone()]);
     result.push_str(&" ".repeat(comment.len() - content_range.end));
     result

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/css.rs

@@ -1,6 +1,6 @@
 use crate::language_parsers::{
     CommentsParser, LanguageParser, LanguageParserImpl, TreeSitterCommentsParser,
-    c_style_multiline_comment_processor, comment_visitor,
+    c_style_multiline_comment_processor, comment_visitor, node_text,
 };
 
 /// Returns a [`LanguageParser`] for CSS.
@@ -14,9 +14,10 @@ fn comments_parser() -> anyhow::Result<impl CommentsParser> {
         &css_language,
         comment_visitor(|node, source_code| {
             if node.kind() == "comment" {
-                Some(c_style_multiline_comment_processor(
-                    &source_code[node.byte_range()],
-                ))
+                Some(c_style_multiline_comment_processor(node_text(
+                    node,
+                    source_code,
+                )))
             } else {
                 None
             }

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/json.rs

@@ -1,4 +1,6 @@
-use crate::language_parsers::{LanguageParser, LanguageParserImpl, c_style_comments_parser};
+use crate::language_parsers::{
+    LanguageParser, LanguageParserImpl, c_style_comments_parser, node_text,
+};
 use crate::symbols::QuerySymbolsParser;
 use anyhow::Context;
 
@@ -16,7 +18,7 @@ pub(super) fn parser() -> anyhow::Result<impl LanguageParser> {
 /// # Errors
 /// Returns an error if a string literal is not valid JSON, e.g. because it holds a raw tab.
 fn decode_node(node: &tree_sitter::Node, source: &str) -> anyhow::Result<String> {
-    let raw = &source[node.byte_range()];
+    let raw = node_text(node, source);
     match node.kind() {
         "string" => serde_json::from_str::<String>(raw)
             .with_context(|| format!("failed to unescape JSON string: {raw}")),

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/lean.rs

@@ -55,7 +55,9 @@ impl CommentsParser for LeanCommentsParser {
         comments
             .into_iter()
             .map(move |((opening, closing), range)| {
+                #[expect(clippy::string_slice, reason = "the scanner reads whole characters")]
                 let text = &source_code[range.clone()];
+                #[expect(clippy::string_slice, reason = "comment markers are ASCII")]
                 Comment {
                     position_range: position_at(range.start)..position_at(range.end),
                     comment_text: format!(

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/lua.rs

@@ -1,5 +1,6 @@
 use crate::language_parsers::{
     CommentsParser, LanguageParser, LanguageParserImpl, TreeSitterCommentsParser, comment_visitor,
+    node_text,
 };
 use tree_sitter::Node;
 
@@ -16,7 +17,7 @@ fn comments_parser() -> anyhow::Result<impl CommentsParser> {
             if node.kind() != "comment" {
                 return None;
             }
-            Some(lua_comment_text(node, &source_code[node.byte_range()]))
+            Some(lua_comment_text(node, node_text(node, source_code)))
         }),
     );
     Ok(parser)
@@ -32,6 +33,10 @@ fn lua_comment_text(node: &Node, comment: &str) -> String {
         None => 0..0,
     };
     let mut result = " ".repeat(content_range.start);
+    #[expect(
+        clippy::string_slice,
+        reason = "`content_range` is a tree-sitter node's range"
+    )]
     result.push_str(&comment[content_range.clone()]);
     result.push_str(&" ".repeat(comment.len() - content_range.end));
     result

{blockwatch_cli-0.11.3 → blockwatch_cli-0.12.0}/src/language_parsers/markdown.rs

@@ -1,6 +1,6 @@
 use crate::language_parsers::{
     Comment, CommentsParser, LanguageParser, LanguageParserImpl, TreeSitterCommentsParser,
-    blank_preserving_line_breaks, xml_style_comments_parser,
+    blank_preserving_line_breaks, node_text, xml_style_comments_parser,
 };
 use tree_sitter::StreamingIterator;
 
@@ -73,12 +73,12 @@ impl MdCommentsParser {
                 .first()
                 .expect("Empty Tree-sitter region query match")
                 .node;
-            let region = &contents[node.byte_range()];
+            let region = node_text(&node, contents);
 
             // `[//]:` comments are direct nodes of the Markdown tree, so their positions are
             // already the source positions.
             if node.kind() == "link_reference_definition" {
-                if let Some(text) = link_reference_definition_comment_text(region) {
+                if let Some(text) = link_reference_definition_comment_text(&node, contents) {
                     comments.push(Comment::from_node(&node, contents, text));
                 }
                 continue;
@@ -151,40 +151,33 @@ impl CommentsParser for MdCommentsParser {
     }
 }
 
-/// Extracts the content of a Markdown `[//]:` comment (a link reference definition used as a
-/// comment), blanking the `[//]:` prefix and the title delimiters so the length is preserved.
-/// Returns `None` for a link reference definition that is not a `[//]:` comment.
-fn link_reference_definition_comment_text(comment: &str) -> Option<String> {
-    let prefix_idx = comment.find("[//]:")?;
-    let start_search = prefix_idx + 5;
-    let (open_offset, open_char) = comment[start_search..]
-        .char_indices()
-        .find(|&(_, c)| ['(', '"', '\''].contains(&c))
-        .expect("comment is expected to have a title delimiter");
-    let open_idx = open_offset + start_search;
-    // Of the three title delimiters only `(` closes on a different character; `"` and `'` close
-    // on themselves.
-    let close_char = if open_char == '(' { ')' } else { open_char };
-
-    let close_idx = comment
-        .rfind(close_char)
-        .expect("comment is expected to end with matching delimiter");
-
-    let mut result = String::with_capacity(comment.len());
-    result.push_str(&comment[..prefix_idx]);
-    // Replace "[//]:" with spaces.
-    result.push_str("     ");
-    // Replace everything before the open delimiter with spaces (including the delimiter).
-    result.push_str(" ".repeat(open_idx - (prefix_idx + 5) + 1).as_str());
-    // Copy the comment's content.
-    result.push_str(&comment[open_idx + 1..close_idx]);
-    // Replace the close delimiter with a space.
-    result.push(' ');
-    if close_idx + 1 < comment.len() {
-        // Copy the rest of the comment after the close delimiter.
-        result.push_str(&comment[close_idx + 1..]);
+/// Returns the text of `node`, a link reference definition in `contents`, with everything but its
+/// title blanked, so the length is preserved. Returns `None` when `node` is not a `[//]:` comment,
+/// or has no title.
+fn link_reference_definition_comment_text(
+    node: &tree_sitter::Node,
+    contents: &str,
+) -> Option<String> {
+    let mut cursor = node.walk();
+    let mut label = None;
+    let mut title = None;
+    for child in node.named_children(&mut cursor) {
+        match child.kind() {
+            "link_label" => label = Some(child),
+            "link_title" => title = Some(child),
+            _ => {}
+        }
+    }
+    if node_text(&label?, contents) != "[//]" {
+        return None;
     }
-    Some(result)
+    // A title is read from the tree, not found in the text, because its delimiters, such as `'`,
+    // can also appear in the destination.
+    let title = title?;
+    let mut text = contents.as_bytes()[node.byte_range()].to_vec();
+    blank_preserving_line_breaks(&mut text[..title.start_byte() - node.start_byte()]);
+    blank_preserving_line_breaks(&mut text[title.end_byte() - node.start_byte()..]);
+    Some(String::from_utf8(text).expect("only whole characters are blanked"))
 }
 
 #[cfg(test)]
@@ -279,6 +272,64 @@ Text
         Ok(())
     }
 
+    #[test]
+    fn link_reference_comment_with_quote_in_destination_reads_title() -> anyhow::Result<()> {
+        let mut parser = parser()?;
+        let content = r#"[//]: it's (<block name="a">)
+Text
+
+[//]: # (</block>)
+"#;
+        let blocks = parser
+            .parse_blocks(content)
+            .collect::<anyhow::Result<Vec<_>>>()?;
+
+        assert_eq!(blocks.len(), 1);
+        assert_eq!(blocks[0].attributes["name"], "a");
+        assert_eq!(blocks[0].content.text(content), "Text\n\n");
+        Ok(())
+    }
+
+    #[test]
+    fn link_reference_comment_with_title_on_next_line_reports_tag_line() -> anyhow::Result<()> {
+        let mut parser = parser()?;
+        let content = r#"[//]: #
+(<block name="a">)
+Text
+
+[//]: # (</block>)
+"#;
+        let blocks = parser
+            .parse_blocks(content)
+            .collect::<anyhow::Result<Vec<_>>>()?;
+
+        assert_eq!(
+            blocks[0].start_tag_position_range,
+            Position::new(2, 2)..Position::new(2, 18)
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn link_reference_without_title_or_with_another_label_is_ignored() -> anyhow::Result<()> {
+        let mut parser = parser()?;
+        let content = r#"<!-- <block name="a"> -->
+Text
+
+[//]: #
+[other]: /url (<block name="b">)
+
+<!-- </block> -->
+"#;
+        let blocks = parser
+            .parse_blocks(content)
+            .collect::<anyhow::Result<Vec<_>>>()?;
+
+        assert_eq!(blocks.len(), 1);
+        assert_eq!(blocks[0].attributes["name"], "a");
+        Ok(())
+    }
+
     #[test]
     fn inline_comment_after_a_code_span_holding_non_ascii_reports_a_character_column()
     -> anyhow::Result<()> {