rolfedh-doc-utils 0.1.8__py3-none-any.whl → 0.1.9__py3-none-any.whl

doc_utils/format_asciidoc_spacing.py

@@ -0,0 +1,222 @@
+"""
+Format AsciiDoc spacing - ensures blank lines after headings and around include directives.
+
+Core logic for formatting AsciiDoc files with proper spacing.
+"""
+
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+
+def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> Tuple[bool, List[str]]:
+    """
+    Process a single AsciiDoc file to fix spacing issues.
+
+    Args:
+        file_path: Path to the file to process
+        dry_run: If True, show what would be changed without modifying
+        verbose: If True, show detailed output
+
+    Returns:
+        Tuple of (changes_made, messages) where messages is a list of verbose output
+    """
+    messages = []
+
+    if verbose:
+        messages.append(f"Processing: {file_path}")
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+    except (IOError, UnicodeDecodeError) as e:
+        raise IOError(f"Error reading {file_path}: {e}")
+
+    # Remove trailing newlines from lines for processing
+    lines = [line.rstrip('\n\r') for line in lines]
+
+    new_lines = []
+    changes_made = False
+    in_block = False  # Track if we're inside a block (admonition, listing, etc.)
+    in_conditional = False  # Track if we're inside a conditional block
+
+    for i, current_line in enumerate(lines):
+        prev_line = lines[i-1] if i > 0 else ""
+        next_line = lines[i+1] if i + 1 < len(lines) else ""
+
+        # Check for conditional start (ifdef:: or ifndef::)
+        if re.match(r'^(ifdef::|ifndef::)', current_line):
+            in_conditional = True
+            # Add blank line before conditional if needed
+            if (prev_line and
+                not re.match(r'^\s*$', prev_line) and
+                not re.match(r'^(ifdef::|ifndef::|endif::)', prev_line)):
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    messages.append("  Added blank line before conditional block")
+            new_lines.append(current_line)
+
+        # Check for conditional end (endif::)
+        elif re.match(r'^endif::', current_line):
+            new_lines.append(current_line)
+            in_conditional = False
+            # Add blank line after conditional if needed
+            if (next_line and
+                not re.match(r'^\s*$', next_line) and
+                not re.match(r'^(ifdef::|ifndef::|endif::)', next_line)):
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    messages.append("  Added blank line after conditional block")
+
+        # Check for block delimiters (====, ----, ...., ____)
+        # These are used for admonitions, listing blocks, literal blocks, etc.
+        elif re.match(r'^(====+|----+|\.\.\.\.+|____+)$', current_line):
+            in_block = not in_block  # Toggle block state
+            new_lines.append(current_line)
+        # Check if current line is a heading (but not if we're in a block)
+        elif not in_block and re.match(r'^=+\s+', current_line):
+            new_lines.append(current_line)
+
+            # Check if next line is not empty and not another heading
+            if (next_line and
+                not re.match(r'^=+\s+', next_line) and
+                not re.match(r'^\s*$', next_line)):
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                    messages.append(f"  Added blank line after heading: {truncated}")
+
+        # Check if current line is a comment (AsciiDoc comments start with //)
+        elif re.match(r'^//', current_line):
+            # Skip special handling if we're inside a conditional block
+            if in_conditional:
+                new_lines.append(current_line)
+            else:
+                # Check if next line is an include directive
+                if next_line and re.match(r'^include::', next_line):
+                    # This comment belongs to the include, add blank line before comment if needed
+                    if (prev_line and
+                        not re.match(r'^\s*$', prev_line) and
+                        not re.match(r'^//', prev_line) and
+                        not re.match(r'^:', prev_line)):  # Don't add if previous is attribute
+                        new_lines.append("")
+                        changes_made = True
+                        if verbose:
+                            messages.append("  Added blank line before comment above include")
+                new_lines.append(current_line)
+
+        # Check if current line is an attribute (starts with :)
+        elif re.match(r'^:', current_line):
+            # Skip special handling if we're inside a conditional block
+            if in_conditional:
+                new_lines.append(current_line)
+            else:
+                # Check if next line is an include directive
+                if next_line and re.match(r'^include::', next_line):
+                    # This attribute belongs to the include, add blank line before attribute if needed
+                    if (prev_line and
+                        not re.match(r'^\s*$', prev_line) and
+                        not re.match(r'^//', prev_line) and
+                        not re.match(r'^:', prev_line)):  # Don't add if previous is comment or attribute
+                        new_lines.append("")
+                        changes_made = True
+                        if verbose:
+                            messages.append("  Added blank line before attribute above include")
+                new_lines.append(current_line)
+
+        # Check if current line is an include directive
+        elif re.match(r'^include::', current_line):
+            # Skip special handling if we're inside a conditional block
+            if in_conditional:
+                new_lines.append(current_line)
+            else:
+                # Check if this is an attribute include (contains "attribute" in the path)
+                is_attribute_include = 'attribute' in current_line.lower()
+
+                # Check if this appears near the top of the file (within first 10 lines after H1)
+                # Find the H1 heading position
+                h1_position = -1
+                for j in range(min(i, 10)):  # Look back up to 10 lines or to current position
+                    if re.match(r'^=\s+', lines[j]):  # H1 heading starts with single =
+                        h1_position = j
+                        break
+
+                # If this is an attribute include near the H1 heading, don't add surrounding blank lines
+                is_near_h1 = h1_position >= 0 and (i - h1_position) <= 2
+
+                # Check if previous line is a comment or attribute (which belongs to this include)
+                has_comment_above = prev_line and re.match(r'^//', prev_line)
+                has_attribute_above = prev_line and re.match(r'^:', prev_line)
+
+                # If it's an attribute include near H1, only the heading's blank line is needed
+                if not (is_attribute_include and is_near_h1):
+                    # Don't add blank line if there's a comment or attribute above (it was handled by the comment/attribute logic)
+                    if not has_comment_above and not has_attribute_above:
+                        # Add blank line before include if previous line is not empty and not an include
+                        if (prev_line and
+                            not re.match(r'^\s*$', prev_line) and
+                            not re.match(r'^include::', prev_line)):
+                            new_lines.append("")
+                            changes_made = True
+                            if verbose:
+                                truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                                messages.append(f"  Added blank line before include: {truncated}")
+
+                new_lines.append(current_line)
+
+                # If it's an attribute include near H1, don't add blank line after
+                if not (is_attribute_include and is_near_h1):
+                    # Add blank line after include if next line exists and is not empty and not an include
+                    if (next_line and
+                        not re.match(r'^\s*$', next_line) and
+                        not re.match(r'^include::', next_line)):
+                        new_lines.append("")
+                        changes_made = True
+                        if verbose:
+                            truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                            messages.append(f"  Added blank line after include: {truncated}")
+
+        else:
+            new_lines.append(current_line)
+
+    # Apply changes if any were made
+    if changes_made:
+        # Clean up any consecutive blank lines we may have added
+        cleaned_lines = []
+        for i, line in enumerate(new_lines):
+            # Check if this is a blank line we're about to add
+            if line == "":
+                # Check if the previous line is also a blank line
+                if i > 0 and cleaned_lines and cleaned_lines[-1] == "":
+                    # Skip this blank line as we already have one
+                    continue
+            cleaned_lines.append(line)
+
+        if not dry_run:
+            try:
+                with open(file_path, 'w', encoding='utf-8') as f:
+                    for line in cleaned_lines:
+                        f.write(line + '\n')
+            except IOError as e:
+                raise IOError(f"Error writing {file_path}: {e}")
+    else:
+        if verbose:
+            messages.append("  No changes needed")
+
+    return changes_made, messages
+
+
+def find_adoc_files(path: Path) -> List[Path]:
+    """Find all .adoc files in the given path"""
+    adoc_files = []
+
+    if path.is_file():
+        if path.suffix == '.adoc':
+            adoc_files.append(path)
+    elif path.is_dir():
+        adoc_files = list(path.rglob('*.adoc'))
+
+    return adoc_files

doc_utils/replace_link_attributes.py

@@ -0,0 +1,168 @@
+"""
+Replace AsciiDoc attributes within link URLs with their actual values.
+
+This module finds and replaces attribute references (like {attribute-name}) that appear
+in the URL portion of AsciiDoc link macros (link: and xref:) with their resolved values
+from attributes.adoc. Link text is preserved unchanged.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+
+def find_attributes_files(root_dir: Path) -> List[Path]:
+    """Find all attributes.adoc files in the repository."""
+    attributes_files = []
+
+    for path in root_dir.rglob('**/attributes.adoc'):
+        # Skip hidden directories and common build directories
+        parts = path.parts
+        if any(part.startswith('.') or part in ['target', 'build', 'node_modules'] for part in parts):
+            continue
+        attributes_files.append(path)
+
+    return attributes_files
+
+
+def load_attributes(attributes_file: Path) -> Dict[str, str]:
+    """Load attribute definitions from an attributes.adoc file."""
+    attributes = {}
+
+    with open(attributes_file, 'r', encoding='utf-8') as f:
+        for line in f:
+            # Match attribute definitions
+            # Format: :attribute-name: value
+            match = re.match(r'^:([a-zA-Z0-9_-]+):\s*(.*)$', line)
+            if match:
+                attr_name = match.group(1)
+                attr_value = match.group(2).strip()
+                attributes[attr_name] = attr_value
+
+    return attributes
+
+
+def resolve_nested_attributes(attributes: Dict[str, str], max_iterations: int = 10) -> Dict[str, str]:
+    """Resolve nested attribute references within attribute values."""
+    for _ in range(max_iterations):
+        changes_made = False
+
+        for attr_name, attr_value in attributes.items():
+            # Find all attribute references in the value
+            refs = re.findall(r'\{([a-zA-Z0-9_-]+)\}', attr_value)
+
+            for ref in refs:
+                if ref in attributes:
+                    new_value = attr_value.replace(f'{{{ref}}}', attributes[ref])
+                    if new_value != attr_value:
+                        attributes[attr_name] = new_value
+                        changes_made = True
+                        attr_value = new_value
+
+        if not changes_made:
+            break
+
+    return attributes
+
+
+def replace_link_attributes_in_file(file_path: Path, attributes: Dict[str, str], dry_run: bool = False) -> int:
+    """Replace attribute references within link macros in a single file."""
+    with open(file_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    original_content = content
+    replacement_count = 0
+
+    # Find all link macros containing attributes in the URL portion only
+    # Match link: and xref: macros, capturing URL and text separately
+    link_patterns = [
+        # link:url[text] - replace only in URL portion
+        (r'link:([^[\]]*)\[([^\]]*)\]', 'link'),
+        # xref:target[text] - replace only in target portion
+        (r'xref:([^[\]]*)\[([^\]]*)\]', 'xref'),
+        # link:url[] or xref:target[] - replace in URL/target portion
+        (r'(link|xref):([^[\]]*)\[\]', 'empty_text')
+    ]
+
+    for pattern, link_type in link_patterns:
+        matches = list(re.finditer(pattern, content))
+
+        # Process matches in reverse order to maintain string positions
+        for match in reversed(matches):
+            if link_type == 'empty_text':
+                # For links with empty text []
+                macro_type = match.group(1)  # 'link' or 'xref'
+                url_part = match.group(2)
+                text_part = ''
+
+                # Check if URL contains attributes
+                if re.search(r'\{[a-zA-Z0-9_-]+\}', url_part):
+                    modified_url = url_part
+
+                    # Replace attributes only in URL
+                    attr_matches = re.findall(r'\{([a-zA-Z0-9_-]+)\}', url_part)
+                    for attr_name in attr_matches:
+                        if attr_name in attributes:
+                            attr_pattern = re.escape(f'{{{attr_name}}}')
+                            modified_url = re.sub(attr_pattern, attributes[attr_name], modified_url)
+                            replacement_count += 1
+
+                    if modified_url != url_part:
+                        # Reconstruct the link with modified URL
+                        modified = f'{macro_type}:{modified_url}[]'
+                        start = match.start()
+                        end = match.end()
+                        content = content[:start] + modified + content[end:]
+            else:
+                # For links with text
+                url_part = match.group(1)
+                text_part = match.group(2)
+
+                # Check if URL contains attributes
+                if re.search(r'\{[a-zA-Z0-9_-]+\}', url_part):
+                    modified_url = url_part
+
+                    # Replace attributes only in URL
+                    attr_matches = re.findall(r'\{([a-zA-Z0-9_-]+)\}', url_part)
+                    for attr_name in attr_matches:
+                        if attr_name in attributes:
+                            attr_pattern = re.escape(f'{{{attr_name}}}')
+                            modified_url = re.sub(attr_pattern, attributes[attr_name], modified_url)
+                            replacement_count += 1
+
+                    if modified_url != url_part:
+                        # Reconstruct the link with modified URL but original text
+                        if link_type == 'link':
+                            modified = f'link:{modified_url}[{text_part}]'
+                        else:  # xref
+                            modified = f'xref:{modified_url}[{text_part}]'
+
+                        start = match.start()
+                        end = match.end()
+                        content = content[:start] + modified + content[end:]
+
+    # Write changes if not in dry-run mode
+    if content != original_content:
+        if not dry_run:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+
+        return replacement_count
+
+    return 0
+
+
+def find_adoc_files(root_dir: Path, exclude_dirs: Optional[set] = None) -> List[Path]:
+    """Find all *.adoc files in the repository."""
+    if exclude_dirs is None:
+        exclude_dirs = {'.git', 'target', 'build', 'node_modules'}
+
+    adoc_files = []
+
+    for path in root_dir.rglob('*.adoc'):
+        # Check if any part of the path is in exclude_dirs
+        parts = set(path.parts)
+        if not parts.intersection(exclude_dirs):
+            adoc_files.append(path)
+
+    return adoc_files

format_asciidoc_spacing.py

@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
+"""
+format-asciidoc-spacing - Format AsciiDoc spacing.
 
-"""Format AsciiDoc spacing - ensures blank lines after headings and around include directives"""
+Ensures blank lines after headings and around include directives.
+"""
 
 import argparse
-import os
-import re
 import sys
 from pathlib import Path
-from typing import List, Tuple
+
+from doc_utils.format_asciidoc_spacing import process_file, find_adoc_files
 
 
 # Colors for output
@@ -23,224 +25,6 @@ def print_colored(message: str, color: str = Colors.NC) -> None:
     print(f"{color}{message}{Colors.NC}")
 
 
-def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> bool:
-    """
-    Process a single AsciiDoc file to fix spacing issues.
-    
-    Args:
-        file_path: Path to the file to process
-        dry_run: If True, show what would be changed without modifying
-        verbose: If True, show detailed output
-    
-    Returns:
-        True if changes were made (or would be made in dry-run), False otherwise
-    """
-    if verbose:
-        print(f"Processing: {file_path}")
-    
-    try:
-        with open(file_path, 'r', encoding='utf-8') as f:
-            lines = f.readlines()
-    except (IOError, UnicodeDecodeError) as e:
-        print_colored(f"Error reading {file_path}: {e}", Colors.RED)
-        return False
-    
-    # Remove trailing newlines from lines for processing
-    lines = [line.rstrip('\n\r') for line in lines]
-    
-    new_lines = []
-    changes_made = False
-    in_block = False  # Track if we're inside a block (admonition, listing, etc.)
-    in_conditional = False  # Track if we're inside a conditional block
-    
-    for i, current_line in enumerate(lines):
-        prev_line = lines[i-1] if i > 0 else ""
-        next_line = lines[i+1] if i + 1 < len(lines) else ""
-        
-        # Check for conditional start (ifdef:: or ifndef::)
-        if re.match(r'^(ifdef::|ifndef::)', current_line):
-            in_conditional = True
-            # Add blank line before conditional if needed
-            if (prev_line and 
-                not re.match(r'^\s*$', prev_line) and
-                not re.match(r'^(ifdef::|ifndef::|endif::)', prev_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    print(f"  Added blank line before conditional block")
-            new_lines.append(current_line)
-        
-        # Check for conditional end (endif::)
-        elif re.match(r'^endif::', current_line):
-            new_lines.append(current_line)
-            in_conditional = False
-            # Add blank line after conditional if needed
-            if (next_line and 
-                not re.match(r'^\s*$', next_line) and
-                not re.match(r'^(ifdef::|ifndef::|endif::)', next_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    print(f"  Added blank line after conditional block")
-        
-        # Check for block delimiters (====, ----, ...., ____)
-        # These are used for admonitions, listing blocks, literal blocks, etc.
-        elif re.match(r'^(====+|----+|\.\.\.\.+|____+)$', current_line):
-            in_block = not in_block  # Toggle block state
-            new_lines.append(current_line)
-        # Check if current line is a heading (but not if we're in a block)
-        elif not in_block and re.match(r'^=+\s+', current_line):
-            new_lines.append(current_line)
-            
-            # Check if next line is not empty and not another heading
-            if (next_line and 
-                not re.match(r'^=+\s+', next_line) and 
-                not re.match(r'^\s*$', next_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                    print(f"  Added blank line after heading: {truncated}")
-        
-        # Check if current line is a comment (AsciiDoc comments start with //)
-        elif re.match(r'^//', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if next line is an include directive
-                if next_line and re.match(r'^include::', next_line):
-                    # This comment belongs to the include, add blank line before comment if needed
-                    if (prev_line and 
-                        not re.match(r'^\s*$', prev_line) and 
-                        not re.match(r'^//', prev_line) and
-                        not re.match(r'^:', prev_line)):  # Don't add if previous is attribute
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            print(f"  Added blank line before comment above include")
-                new_lines.append(current_line)
-        
-        # Check if current line is an attribute (starts with :)
-        elif re.match(r'^:', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if next line is an include directive
-                if next_line and re.match(r'^include::', next_line):
-                    # This attribute belongs to the include, add blank line before attribute if needed
-                    if (prev_line and 
-                        not re.match(r'^\s*$', prev_line) and 
-                        not re.match(r'^//', prev_line) and
-                        not re.match(r'^:', prev_line)):  # Don't add if previous is comment or attribute
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            print(f"  Added blank line before attribute above include")
-                new_lines.append(current_line)
-        
-        # Check if current line is an include directive
-        elif re.match(r'^include::', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if this is an attribute include (contains "attribute" in the path)
-                is_attribute_include = 'attribute' in current_line.lower()
-                
-                # Check if this appears near the top of the file (within first 10 lines after H1)
-                # Find the H1 heading position
-                h1_position = -1
-                for j in range(min(i, 10)):  # Look back up to 10 lines or to current position
-                    if re.match(r'^=\s+', lines[j]):  # H1 heading starts with single =
-                        h1_position = j
-                        break
-                
-                # If this is an attribute include near the H1 heading, don't add surrounding blank lines
-                is_near_h1 = h1_position >= 0 and (i - h1_position) <= 2
-                
-                # Check if previous line is a comment or attribute (which belongs to this include)
-                has_comment_above = prev_line and re.match(r'^//', prev_line)
-                has_attribute_above = prev_line and re.match(r'^:', prev_line)
-                
-                # If it's an attribute include near H1, only the heading's blank line is needed
-                if not (is_attribute_include and is_near_h1):
-                    # Don't add blank line if there's a comment or attribute above (it was handled by the comment/attribute logic)
-                    if not has_comment_above and not has_attribute_above:
-                        # Add blank line before include if previous line is not empty and not an include
-                        if (prev_line and 
-                            not re.match(r'^\s*$', prev_line) and 
-                            not re.match(r'^include::', prev_line)):
-                            new_lines.append("")
-                            changes_made = True
-                            if verbose:
-                                truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                                print(f"  Added blank line before include: {truncated}")
-                
-                new_lines.append(current_line)
-                
-                # If it's an attribute include near H1, don't add blank line after
-                if not (is_attribute_include and is_near_h1):
-                    # Add blank line after include if next line exists and is not empty and not an include
-                    if (next_line and 
-                        not re.match(r'^\s*$', next_line) and 
-                        not re.match(r'^include::', next_line)):
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                            print(f"  Added blank line after include: {truncated}")
-        
-        else:
-            new_lines.append(current_line)
-    
-    # Apply changes if any were made
-    if changes_made:
-        # Clean up any consecutive blank lines we may have added
-        cleaned_lines = []
-        for i, line in enumerate(new_lines):
-            # Check if this is a blank line we're about to add
-            if line == "":
-                # Check if the previous line is also a blank line
-                if i > 0 and cleaned_lines and cleaned_lines[-1] == "":
-                    # Skip this blank line as we already have one
-                    continue
-            cleaned_lines.append(line)
-        
-        if dry_run:
-            print_colored(f"Would modify: {file_path}", Colors.YELLOW)
-        else:
-            try:
-                with open(file_path, 'w', encoding='utf-8') as f:
-                    for line in cleaned_lines:
-                        f.write(line + '\n')
-                print_colored(f"Modified: {file_path}", Colors.GREEN)
-            except IOError as e:
-                print_colored(f"Error writing {file_path}: {e}", Colors.RED)
-                return False
-    else:
-        if verbose:
-            print("  No changes needed")
-    
-    return changes_made
-
-
-def find_adoc_files(path: Path) -> List[Path]:
-    """Find all .adoc files in the given path"""
-    adoc_files = []
-    
-    if path.is_file():
-        if path.suffix == '.adoc':
-            adoc_files.append(path)
-        else:
-            print_colored(f"Warning: {path} is not an AsciiDoc file (.adoc)", Colors.YELLOW)
-    elif path.is_dir():
-        adoc_files = list(path.rglob('*.adoc'))
-    
-    return adoc_files
-
-
 def main():
     """Main entry point"""
     parser = argparse.ArgumentParser(
@@ -258,7 +42,7 @@ Examples:
   %(prog)s --dry-run modules/               # Preview changes without modifying
         """
     )
-    
+
     parser.add_argument(
         'path',
         nargs='?',
@@ -275,42 +59,68 @@ Examples:
         action='store_true',
         help='Show detailed output'
     )
-    
+
     args = parser.parse_args()
-    
+
     # Convert path to Path object
     target_path = Path(args.path)
-    
+
     # Check if path exists
     if not target_path.exists():
         print_colored(f"Error: Path does not exist: {target_path}", Colors.RED)
         sys.exit(1)
-    
+
     # Display dry-run mode message
     if args.dry_run:
         print_colored("DRY RUN MODE - No files will be modified", Colors.YELLOW)
-    
+
     # Find all AsciiDoc files
     adoc_files = find_adoc_files(target_path)
-    
+
     if not adoc_files:
+        if target_path.is_file():
+            print_colored(f"Warning: {target_path} is not an AsciiDoc file (.adoc)", Colors.YELLOW)
         print(f"Processed 0 AsciiDoc file(s)")
         print("AsciiDoc spacing formatting complete!")
         return
-    
+
     # Process each file
     files_processed = 0
+    files_modified = 0
+
     for file_path in adoc_files:
         try:
-            process_file(file_path, args.dry_run, args.verbose)
+            changes_made, messages = process_file(file_path, args.dry_run, args.verbose)
+
+            # Print verbose messages
+            if args.verbose:
+                for msg in messages:
+                    print(msg)
+
+            if changes_made:
+                files_modified += 1
+                if args.dry_run:
+                    print_colored(f"Would modify: {file_path}", Colors.YELLOW)
+                else:
+                    print_colored(f"Modified: {file_path}", Colors.GREEN)
+            elif args.verbose:
+                print(f"  No changes needed for: {file_path}")
+
             files_processed += 1
+
         except KeyboardInterrupt:
             print_colored("\nOperation cancelled by user", Colors.YELLOW)
             sys.exit(1)
+        except IOError as e:
+            print_colored(f"{e}", Colors.RED)
         except Exception as e:
             print_colored(f"Unexpected error processing {file_path}: {e}", Colors.RED)
-    
+
     print(f"Processed {files_processed} AsciiDoc file(s)")
+    if args.dry_run and files_modified > 0:
+        print(f"Would modify {files_modified} file(s)")
+    elif files_modified > 0:
+        print(f"Modified {files_modified} file(s)")
     print("AsciiDoc spacing formatting complete!")
 
 

replace_link_attributes.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+replace-link-attributes - Replace AsciiDoc attributes within link URLs with their actual values.
+
+This script finds and replaces attribute references (like {attribute-name}) that appear
+in the URL portion of AsciiDoc link macros (link: and xref:) with their resolved values
+from attributes.adoc. Link text is preserved unchanged.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from doc_utils.replace_link_attributes import (
+    find_attributes_files,
+    load_attributes,
+    resolve_nested_attributes,
+    replace_link_attributes_in_file,
+    find_adoc_files
+)
+
+
+def prompt_for_attributes_file(attributes_files: list[Path]) -> Optional[Path]:
+    """Prompt user to select or specify attributes file."""
+    if not attributes_files:
+        print("No attributes.adoc files found in the repository.")
+        response = input("Enter the path to your attributes.adoc file (or 'q' to quit): ").strip()
+        if response.lower() == 'q':
+            return None
+        path = Path(response)
+        if path.exists() and path.is_file():
+            return path
+        else:
+            print(f"Error: File not found: {response}")
+            return None
+
+    if len(attributes_files) == 1:
+        file_path = attributes_files[0]
+        response = input(f"Found attributes file: {file_path}\nUse this file? (y/n/q): ").strip().lower()
+        if response == 'y':
+            return file_path
+        elif response == 'q':
+            return None
+        else:
+            response = input("Enter the path to your attributes.adoc file (or 'q' to quit): ").strip()
+            if response.lower() == 'q':
+                return None
+            path = Path(response)
+            if path.exists() and path.is_file():
+                return path
+            else:
+                print(f"Error: File not found: {response}")
+                return None
+
+    # Multiple files found
+    print("\nFound multiple attributes.adoc files:")
+    for i, file_path in enumerate(attributes_files, 1):
+        print(f"  {i}. {file_path}")
+    print(f"  {len(attributes_files) + 1}. Enter custom path")
+
+    while True:
+        response = input(f"\nSelect option (1-{len(attributes_files) + 1}) or 'q' to quit: ").strip()
+        if response.lower() == 'q':
+            return None
+
+        try:
+            choice = int(response)
+            if 1 <= choice <= len(attributes_files):
+                return attributes_files[choice - 1]
+            elif choice == len(attributes_files) + 1:
+                response = input("Enter the path to your attributes.adoc file: ").strip()
+                path = Path(response)
+                if path.exists() and path.is_file():
+                    return path
+                else:
+                    print(f"Error: File not found: {response}")
+            else:
+                print(f"Invalid choice. Please enter a number between 1 and {len(attributes_files) + 1}")
+        except ValueError:
+            print("Invalid input. Please enter a number.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Replace AsciiDoc attributes within link macros with their actual values.'
+    )
+    parser.add_argument(
+        '--dry-run', '-n',
+        action='store_true',
+        help='Show what would be changed without making actual modifications'
+    )
+    parser.add_argument(
+        '--path', '-p',
+        type=str,
+        default='.',
+        help='Repository path to search (default: current directory)'
+    )
+    parser.add_argument(
+        '--attributes-file', '-a',
+        type=str,
+        help='Path to attributes.adoc file (skips interactive selection)'
+    )
+
+    args = parser.parse_args()
+
+    # Determine repository root
+    repo_root = Path(args.path).resolve()
+
+    if not repo_root.exists() or not repo_root.is_dir():
+        print(f"Error: Directory not found: {repo_root}")
+        sys.exit(1)
+
+    print(f"{'DRY RUN MODE - ' if args.dry_run else ''}Searching in: {repo_root}")
+
+    # Find or get attributes file
+    if args.attributes_file:
+        attributes_file = Path(args.attributes_file)
+        if not attributes_file.exists():
+            print(f"Error: Specified attributes file not found: {attributes_file}")
+            sys.exit(1)
+    else:
+        print("\nSearching for attributes.adoc files...")
+        attributes_files = find_attributes_files(repo_root)
+        attributes_file = prompt_for_attributes_file(attributes_files)
+
+        if not attributes_file:
+            print("Operation cancelled.")
+            sys.exit(0)
+
+    print(f"\nLoading attributes from: {attributes_file}")
+    attributes = load_attributes(attributes_file)
+
+    if not attributes:
+        print("No attributes found in the file.")
+        sys.exit(1)
+
+    print(f"Found {len(attributes)} attributes")
+
+    # Resolve nested references
+    print("Resolving nested attribute references...")
+    attributes = resolve_nested_attributes(attributes)
+
+    # Find all AsciiDoc files
+    print(f"\nSearching for *.adoc files in {repo_root}")
+    adoc_files = find_adoc_files(repo_root)
+
+    # Exclude the attributes file itself
+    adoc_files = [f for f in adoc_files if f != attributes_file]
+
+    print(f"Found {len(adoc_files)} AsciiDoc files to process")
+
+    if args.dry_run:
+        print("\n*** DRY RUN MODE - No files will be modified ***\n")
+
+    # Process each file
+    total_replacements = 0
+    files_modified = 0
+
+    for file_path in adoc_files:
+        replacements = replace_link_attributes_in_file(file_path, attributes, args.dry_run)
+        if replacements > 0:
+            rel_path = file_path.relative_to(repo_root)
+            prefix = "[DRY RUN] " if args.dry_run else ""
+            print(f"  {prefix}Modified {rel_path}: {replacements} replacements")
+            total_replacements += replacements
+            files_modified += 1
+
+    # Summary
+    print(f"\nSummary:")
+    if args.dry_run:
+        print(f"  Would modify {files_modified} files")
+        print(f"  Would make {total_replacements} replacements")
+        print("\nRun without --dry-run to apply changes.")
+    else:
+        print(f"  Total files modified: {files_modified}")
+        print(f"  Total replacements: {total_replacements}")
+
+        if total_replacements == 0:
+            print("\nNo attribute references found within link macros.")
+        else:
+            print("\nReplacement complete!")
+
+
+if __name__ == '__main__':
+    main()

{rolfedh_doc_utils-0.1.8.dist-info → rolfedh_doc_utils-0.1.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.8
+Version: 0.1.9
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -79,6 +79,7 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
+| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
 | **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
 | **`check-scannability`** | Analyzes readability (sentence/paragraph length) | `check-scannability --max-words 25` |
 | **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files` (preview)<br>`archive-unused-files --archive` (execute) |

{rolfedh_doc_utils-0.1.8.dist-info → rolfedh_doc_utils-0.1.9.dist-info}/RECORD

@@ -2,17 +2,20 @@ archive_unused_files.py,sha256=KMC5a1WL3rZ5owoVnncvfpT1YeMKbVXq9giHvadDgbM,1936
 archive_unused_images.py,sha256=PG2o3haovYckgfhoPhl6KRG_a9czyZuqlLkzkupKTCY,1526
 check_scannability.py,sha256=gcM-vFXKHGP_yFBz7-V5xbXWhIMmtMzBYIGwP9CFbzI,5140
 find_unused_attributes.py,sha256=fk-K32eoCVHxoj7RiBNgSmX1arBLuwYfdSAOMc-wIx0,1677
-format_asciidoc_spacing.py,sha256=Jy_V8c03KGRPJxu4uPdDuMsFg-Q-4AGD9BdkGnApUu8,13241
+format_asciidoc_spacing.py,sha256=ROp-cdMs2_hk8H4z5ljT0iDgGtsiECZ8TVjjcN_oOWE,3874
+replace_link_attributes.py,sha256=vg_aufw7dKXvh_epCKRNq_hEBMU_9crZ_JyJPpxSMNk,6454
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
+doc_utils/format_asciidoc_spacing.py,sha256=XnVJekaj39aDzjV3xFKl58flM41AaJzejxNYJIIAMz0,10139
+doc_utils/replace_link_attributes.py,sha256=kBiePbxjQn3O2rzqmYY8Mqy_mJgZ6yw048vSZ5SSB5E,6587
 doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
 doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
 doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
 doc_utils/unused_attributes.py,sha256=HBgmHelqearfWl3TTC2bZGiJytjLADIgiGQUNKqXXPg,1847
 doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-rolfedh_doc_utils-0.1.8.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.8.dist-info/METADATA,sha256=KrjqTRhF_B26ZNt37SZXReMcV4-ztpy1aWHJepYxMDE,6891
-rolfedh_doc_utils-0.1.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.8.dist-info/entry_points.txt,sha256=dA-u4qlxKcewUAOFgaeW1NUIrkhsVknuwFuGTn1-84w,271
-rolfedh_doc_utils-0.1.8.dist-info/top_level.txt,sha256=WrYqTa4wbjRPMUl2hgJBfP734XsXLkhbnzUublx8S0s,119
-rolfedh_doc_utils-0.1.8.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.9.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.9.dist-info/METADATA,sha256=QmlwozZ8j3S2dnbZhsQpCr4JIDTyyjKpMCUYWnkCOTA,7041
+rolfedh_doc_utils-0.1.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.9.dist-info/entry_points.txt,sha256=w5FlyLk-L2rtzYsMuTo8OVxYPo4nm4zRiArBTYqVud0,326
+rolfedh_doc_utils-0.1.9.dist-info/top_level.txt,sha256=YrJAJFSkY9RKoHGDmrFCwsMVZS3Azw6ewzR2b081qCU,143
+rolfedh_doc_utils-0.1.9.dist-info/RECORD,,

{rolfedh_doc_utils-0.1.8.dist-info → rolfedh_doc_utils-0.1.9.dist-info}/entry_points.txt

@@ -4,3 +4,4 @@ archive-unused-images = archive_unused_images:main
 check-scannability = check_scannability:main
 find-unused-attributes = find_unused_attributes:main
 format-asciidoc-spacing = format_asciidoc_spacing:main
+replace-link-attributes = replace_link_attributes:main

{rolfedh_doc_utils-0.1.8.dist-info → rolfedh_doc_utils-0.1.9.dist-info}/top_level.txt

@@ -4,3 +4,4 @@ check_scannability
 doc_utils
 find_unused_attributes
 format_asciidoc_spacing
+replace_link_attributes