feat: implement MD053 link-image-reference-definitions rule (#28)

Add comprehensive MD053 rule to detect unused and duplicate link/image reference definitions.

Features:
- Detects unused reference definitions
- Identifies duplicate definitions (first definition wins per CommonMark)
- Supports all reference formats: full [text][label], collapsed [label][], shortcut [label]
- CommonMark compliant label normalization (case-insensitive, whitespace collapse)
- Configurable ignored definitions with sensible defaults (["//"] for comments)
- Performance optimized with pre-compiled regex patterns and HashMap lookups

Implementation:
- Document-wide rule type for comprehensive analysis
- 13 comprehensive unit tests covering all scenarios and edge cases
- Proper integration with configuration system and CLI
- Complete documentation and test sample files
- Code formatting improvements across multiple files

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: ekropotin

.claude/commands/review.md

@@ -1,2 +1 @@
-Tidy up the code by deleting old, unused code and fixing compiler hints/warnings. Suppress false positive ones, if needed.
-When do general code review, check adherence to the best coding practices on Rust. Also, pay a special attention on potential performance/resource overuse issues.
+Review the code changes in the current branch, ensuring they adhere to the coding standards outlined in CLAUDE.md.

CLAUDE.md

@@ -121,99 +121,6 @@ quickmark/
 - Each rule implements `RuleLinter` trait with `feed` method
 - Rules are dynamically instantiated based on configuration
 
-### Rules Implementation Checklist
-
-This section tracks the progress of porting all markdownlint rules to QuickMark. Rules are categorized by their implementation requirements:
-
-#### Line-Based Rules (5 rules)
-
-*Work primarily with raw text lines - high performance, direct text analysis*
-
-- [ ] **MD009** (`no-trailing-spaces`): Trailing spaces at end of lines
-- [ ] **MD010** (`no-hard-tabs`): Hard tabs should not be used
-- [ ] **MD012** (`no-multiple-blanks`): Multiple consecutive blank lines
-- [x] **MD013** (`line-length`): Line length limits with configurable exceptions ✅
-- [ ] **MD047** (`single-trailing-newline`): Files should end with a single newline
-
-#### Token-Based Rules (32 rules)
-
-*Work with specific AST node types - cached node filtering for efficiency*
-
-**Heading Rules (8 rules):**
-
-- [x] **MD001** (`heading-increment`): Heading levels increment by one ✅
-- [x] **MD003** (`heading-style`): Consistent heading styles ✅
-- [ ] **MD018** (`no-missing-space-atx`): Space after hash in ATX headings
-- [ ] **MD019** (`no-multiple-space-atx`): Multiple spaces after hash in ATX headings
-- [ ] **MD020** (`no-missing-space-closed-atx`): Space inside closed ATX headings
-- [ ] **MD021** (`no-multiple-space-closed-atx`): Multiple spaces in closed ATX headings
-- [ ] **MD023** (`heading-start-left`): Headings start at beginning of line
-- [ ] **MD026** (`no-trailing-punctuation`): Trailing punctuation in headings
-
-**List Rules (6 rules):**
-
-- [ ] **MD004** (`ul-style`): Unordered list style consistency
-- [ ] **MD005** (`list-indent`): List item indentation at same level
-- [ ] **MD006** (`ul-start-left`): Bulleted lists start at beginning of line
-- [ ] **MD007** (`ul-indent`): Unordered list indentation consistency
-- [ ] **MD029** (`ol-prefix`): Ordered list item prefix consistency
-- [ ] **MD030** (`list-marker-space`): Spaces after list markers
-
-**Link Rules (3 rules):**
-
-- [ ] **MD011** (`no-reversed-links`): Reversed link syntax
-- [ ] **MD034** (`no-bare-urls`): Bare URLs without proper formatting
-- [ ] **MD042** (`no-empty-links`): Empty links
-
-**Code Rules (4 rules):**
-
-- [ ] **MD014** (`commands-show-output`): Dollar signs before shell commands
-- [ ] **MD040** (`fenced-code-language`): Language specified for fenced code blocks
-- [ ] **MD046** (`code-block-style`): Code block style consistency
-- [ ] **MD048** (`code-fence-style`): Code fence style consistency
-
-**Formatting Rules (11 rules):**
-
-- [ ] **MD027** (`no-multiple-space-blockquote`): Multiple spaces after blockquote
-- [ ] **MD028** (`no-blanks-blockquote`): Blank lines inside blockquotes
-- [ ] **MD033** (`no-inline-html`): Inline HTML usage
-- [ ] **MD035** (`hr-style`): Horizontal rule style consistency
-- [ ] **MD036** (`no-emphasis-as-heading`): Emphasis used instead of heading
-- [ ] **MD037** (`no-space-in-emphasis`): Spaces inside emphasis markers
-- [ ] **MD038** (`no-space-in-code`): Spaces inside code span elements
-- [ ] **MD039** (`no-space-in-links`): Spaces inside link text
-- [ ] **MD045** (`no-alt-text`): Images should have alternate text
-- [ ] **MD049** (`emphasis-style`): Emphasis style consistency
-- [ ] **MD050** (`strong-style`): Strong style consistency
-
-#### Document-Wide Rules (7 rules)
-
-*Require full document analysis - global state tracking*
-
-- [ ] **MD024** (`no-duplicate-heading`): Multiple headings with same content
-- [ ] **MD025** (`single-title`): Multiple top-level headings
-- [ ] **MD041** (`first-line-heading`): First line should be top-level heading
-- [ ] **MD043** (`required-headings`): Required heading structure
-- [x] **MD051** (`link-fragments`): Link fragments should be valid
-- [x] **MD052** (`reference-links-images`): Reference links should be defined ✅
-- [ ] **MD053** (`link-image-reference-definitions`): Reference definitions should be needed
-
-#### Hybrid Rules (3 rules)
-
-*Need both AST analysis and line context - structural elements with spacing*
-
-- [ ] **MD022** (`blanks-around-headings`): Headings surrounded by blank lines
-- [ ] **MD031** (`blanks-around-fences`): Fenced code blocks surrounded by blank lines
-- [ ] **MD032** (`blanks-around-lists`): Lists surrounded by blank lines
-
-#### Special Rules (1 rule)
-
-*Unique implementation requirements*
-
-- [ ] **MD044** (`proper-names`): Proper names with correct capitalization (requires external dictionaries)
-
-**Implementation Progress: 4/48 rules completed (8.33%)**
-
 ### Linting Architecture Evolution
 
 **Performance-Optimized Single-Pass Design**:
@@ -314,3 +221,57 @@ This architecture allows rules like MD013 to work efficiently with raw text whil
 1. Create conversion functions in `quickmark_config`
 2. Add new public functions following the pattern of `parse_toml_config`
 3. Both CLI and server applications can immediately use the new format
+
+## Code Guidelines
+
+### General principles
+
+1. **Follow idiomatic Rust**: Use the latest Rust best practices and conventions. Code should feel natural to an experienced Rust developer.
+2. **No unsafe unless required**: Do not use unsafe blocks unless absolutely necessary for performance or interoperability. If used, justify with a comment and encapsulate safely.
+3. **Zero compiler warnings**:
+   - Code must compile with `#![deny(warnings)]`.
+   - Suppress only known false positives with clearly scoped `#[allow(...)]` attributes and documented reasons.
+4. **Speed over memory**:
+   - Optimize for CPU performance, even at the cost of increased memory usage.
+   - Avoid unnecessary allocations, but favor speed in algorithms and data access patterns.
+5. **Cloning is expensive**: Avoid cloning (`.clone()`) unless it is proven to be more efficient than passing a reference or performing in-place mutation.
+6. **Use modern language features**:
+   - Prefer `let else`, `if let`, match ergonomics, Iterator combinators, `?` operator, and Result-based error handling.
+   - Consider `Cow` or `Arc` where applicable to avoid unnecessary clones.
+
+### Optimization practices
+
+1. **Prefer move semantics** when data is no longer needed.
+2. **Use references wisely**: Use `&T` or `&mut T` rather than `T` or `T.clone()` when ownership is not required.
+3. **Inline strategically**: Inline functions where beneficial using `#[inline]` (but measure if in doubt).
+4. **Use zero-cost abstractions**: From the standard library or crates like `itertools`, `smallvec`, `rayon` (for parallelism), etc.
+5. **Choose fast data structures**: For hot paths, prefer faster data structures, even if more memory is consumed (e.g., `HashMap` over `BTreeMap` when ordering is unnecessary).
+
+### Safety and correctness
+
+1. **Use strong typing**: Use the type system to enforce invariants.
+2. **Avoid panics**: In library code (`unwrap()`, `expect()`) unless in clearly unreachable branches.
+3. **Mark important results**: Use `#[must_use]` to mark important results when appropriate.
+4. **Document assumptions**: Document all `TODO`, `FIXME`, and assumptions in code.
+
+### Linting & Tooling
+
+**Code must pass**:
+
+1. `cargo check`
+2. `cargo clippy --all-targets --all-features -- -D warnings`
+3. `cargo fmt --check`
+4. `cargo test --all`
+
+**Additional practices**:
+
+1. **Use Clippy lints**: That enforce performance best practices (e.g., `clippy::redundant_clone`, `clippy::needless_collect`, `clippy::manual_memcpy`, etc.)
+2. **Use performance attributes**: `#[inline(always)]`, `#[cold]`, or `#[no_mangle]` where profiling/FFI suggests it makes sense — but only after benchmarking.
+
+### Testing & Validation
+
+**Tests must**:
+
+1. **Cover edge cases**: And performance regressions.
+2. **Use `#[should_panic]`**: Where panics are expected.
+3. **Prefer property-based testing**: Use `proptest` or fuzzing where inputs are highly variable.

README.md

@@ -52,6 +52,7 @@ heading-style = 'err'
 line-length = 'err'
 link-fragments = 'warn'
 reference-links-images = 'err'
+link-image-reference-definitions = 'err'
 
 # see a specific rule's doc for details of configuration
 [linters.settings.heading-style]
@@ -72,11 +73,14 @@ ignored_pattern = ""
 [linters.settings.reference-links-images]
 shortcut_syntax = false
 ignored_labels = ["x"]
+
+[linters.settings.link-image-reference-definitions]
+ignored_definitions = ["//"]
 ```
 
 ## Rules
 
-**Implementation Progress: 5/48 rules completed (10.4%)**
+**Implementation Progress: 6/48 rules completed (12.5%)**
 
 - [x] **[MD001](docs/rules/md001.md)** *heading-increment* - Heading levels should only increment by one level at a time
 - [x] **[MD003](docs/rules/md003.md)** *heading-style* - Consistent heading styles
@@ -125,4 +129,4 @@ ignored_labels = ["x"]
 - [ ] **MD050** *strong-style* - Strong style consistency
 - [x] **[MD051](docs/rules/md051.md)** *link-fragments* - Link fragments should be valid
 - [x] **[MD052](docs/rules/md052.md)** *reference-links-images* - Reference links should be defined
-- [ ] **MD053** *link-image-reference-definitions* - Reference definitions should be needed
+- [x] **[MD053](docs/rules/md053.md)** *link-image-reference-definitions* - Reference definitions should be needed

crates/quickmark/src/main.rs

@@ -1,8 +1,8 @@
 use anyhow::Context;
 use clap::Parser;
 use quickmark_config::config_in_path_or_default;
-use quickmark_linter::linter::{MultiRuleLinter, RuleViolation};
 use quickmark_linter::config::{QuickmarkConfig, RuleSeverity};
+use quickmark_linter::linter::{MultiRuleLinter, RuleViolation};
 use std::cmp::min;
 use std::env;
 use std::{fs, path::PathBuf, process::exit};
@@ -73,11 +73,11 @@ fn main() -> anyhow::Result<()> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::path::PathBuf;
     use quickmark_linter::config::{HeadingStyle, LintersSettingsTable, MD003HeadingStyleTable};
     use quickmark_linter::linter::{CharPosition, Range};
     use quickmark_linter::rules::{md001::MD001, md003::MD003};
     use quickmark_linter::test_utils::test_helpers::test_config_with_settings;
+    use std::path::PathBuf;
 
     #[test]
     fn test_print_cli_errors() {
@@ -94,14 +94,35 @@ mod tests {
             },
         );
         let range = Range {
-            start: CharPosition { line: 1, character: 1 },
-            end: CharPosition { line: 1, character: 5 },
+            start: CharPosition {
+                line: 1,
+                character: 1,
+            },
+            end: CharPosition {
+                line: 1,
+                character: 5,
+            },
         };
         let file = PathBuf::default();
         let results = vec![
-            RuleViolation::new(&MD001, "all is bad".to_string(), file.clone(), range.clone()),
-            RuleViolation::new(&MD003, "all is even worse".to_string(), file.clone(), range.clone()),
-            RuleViolation::new(&MD003, "all is even worse2".to_string(), file.clone(), range),
+            RuleViolation::new(
+                &MD001,
+                "all is bad".to_string(),
+                file.clone(),
+                range.clone(),
+            ),
+            RuleViolation::new(
+                &MD003,
+                "all is even worse".to_string(),
+                file.clone(),
+                range.clone(),
+            ),
+            RuleViolation::new(
+                &MD003,
+                "all is even worse2".to_string(),
+                file.clone(),
+                range,
+            ),
         ];
 
         let (errs, warns) = print_cli_errors(&results, &config);

crates/quickmark/tests/cli_integration_tests.rs

@@ -7,8 +7,7 @@ use std::path::PathBuf;
 /// Helper function to get the path to test sample files
 fn test_sample_path(filename: &str) -> String {
     // Use the CARGO_MANIFEST_DIR environment variable to find the project root
-    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR")
-        .expect("CARGO_MANIFEST_DIR not set");
+    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set");
 
     PathBuf::from(manifest_dir)
         .parent() // Go up from crates/quickmark
@@ -105,7 +104,8 @@ fn test_cli_error_format() {
 
     // Check that error format includes expected components:
     // ERR: file_path:line:column MD001/heading-increment message
-    let error_lines: Vec<&str> = stderr.lines()
+    let error_lines: Vec<&str> = stderr
+        .lines()
         .filter(|line| line.starts_with("ERR:") || line.starts_with("WARN:"))
         .collect();
 
@@ -162,7 +162,8 @@ fn test_cli_line_numbers_are_one_based() {
     let stderr = String::from_utf8_lossy(&output.stderr);
 
     // Find error lines and check line numbers
-    let error_lines: Vec<&str> = stderr.lines()
+    let error_lines: Vec<&str> = stderr
+        .lines()
         .filter(|line| line.starts_with("ERR:") || line.starts_with("WARN:"))
         .collect();
 
@@ -174,7 +175,10 @@ fn test_cli_line_numbers_are_one_based() {
                 let line_num_str = &after_file[..second_colon];
                 if let Ok(line_num) = line_num_str.parse::<u32>() {
                     // Line numbers should be 1-based, not 0-based
-                    assert!(line_num >= 1, "Line number should be 1-based, got: {line_num}");
+                    assert!(
+                        line_num >= 1,
+                        "Line number should be 1-based, got: {line_num}"
+                    );
                 }
             }
         }