rolfedh-doc-utils 0.1.10__py3-none-any.whl → 0.1.11__py3-none-any.whl

doc_utils/unused_attributes.py

@@ -6,19 +6,36 @@ Functions:
 - find_adoc_files: Recursively find all .adoc files in a directory (ignoring symlinks).
 - scan_for_attribute_usage: Find which attributes are used in a set of .adoc files.
 - find_unused_attributes: Main function to return unused attributes.
+- find_attributes_files: Find all potential attributes files in the repository.
 """
 
 import os
 import re
-from typing import Set, List
+from pathlib import Path
+from typing import Set, List, Optional
 
 def parse_attributes_file(attr_file: str) -> Set[str]:
     attributes = set()
-    with open(attr_file, 'r', encoding='utf-8') as f:
-        for line in f:
-            match = re.match(r'^:([\w-]+):', line.strip())
-            if match:
-                attributes.add(match.group(1))
+
+    # Check if file exists
+    if not os.path.exists(attr_file):
+        raise FileNotFoundError(f"Attributes file not found: {attr_file}")
+
+    # Check if it's a file (not a directory)
+    if not os.path.isfile(attr_file):
+        raise ValueError(f"Path is not a file: {attr_file}")
+
+    try:
+        with open(attr_file, 'r', encoding='utf-8') as f:
+            for line in f:
+                match = re.match(r'^:([\w-]+):', line.strip())
+                if match:
+                    attributes.add(match.group(1))
+    except PermissionError:
+        raise PermissionError(f"Permission denied reading file: {attr_file}")
+    except UnicodeDecodeError as e:
+        raise ValueError(f"Unable to read file (encoding issue): {attr_file}\n{str(e)}")
+
     return attributes
 
 def find_adoc_files(root_dir: str) -> List[str]:
@@ -42,6 +59,77 @@ def scan_for_attribute_usage(adoc_files: List[str], attributes: Set[str]) -> Set
                         used.add(match)
     return used
 
+def find_attributes_files(root_dir: str = '.') -> List[str]:
+    """Find all attributes.adoc files in the repository."""
+    attributes_files = []
+    root_path = Path(root_dir)
+
+    # Common attribute file patterns
+    patterns = ['**/attributes.adoc', '**/attributes*.adoc', '**/*attributes.adoc', '**/*-attributes.adoc']
+
+    for pattern in patterns:
+        for path in root_path.glob(pattern):
+            # Skip hidden directories and common build directories
+            parts = path.parts
+            if any(part.startswith('.') or part in ['target', 'build', 'node_modules', '.archive'] for part in parts):
+                continue
+            # Convert to string and avoid duplicates
+            str_path = str(path)
+            if str_path not in attributes_files:
+                attributes_files.append(str_path)
+
+    # Sort for consistent ordering
+    attributes_files.sort()
+    return attributes_files
+
+
+def select_attributes_file(attributes_files: List[str]) -> Optional[str]:
+    """Interactive selection of attributes file from a list."""
+    if not attributes_files:
+        return None
+
+    if len(attributes_files) == 1:
+        print(f"Found attributes file: {attributes_files[0]}")
+        response = input("Use this file? (y/n): ").strip().lower()
+        if response == 'y':
+            return attributes_files[0]
+        else:
+            response = input("Enter the path to your attributes file: ").strip()
+            if os.path.exists(response) and os.path.isfile(response):
+                return response
+            else:
+                print(f"Error: File not found: {response}")
+                return None
+
+    # Multiple files found
+    print("\nFound multiple attributes 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 file: ").strip()
+                if os.path.exists(response) and os.path.isfile(response):
+                    return response
+                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.")
+
+    return None
+
+
 def find_unused_attributes(attr_file: str, adoc_root: str = '.') -> List[str]:
     attributes = parse_attributes_file(attr_file)
     adoc_files = find_adoc_files(adoc_root)

doc_utils/validate_links.py

@@ -0,0 +1,576 @@
+#!/usr/bin/env python3
+"""
+Validate links in AsciiDoc documentation, checking for broken URLs and missing references.
+"""
+
+import os
+import re
+import time
+import json
+import hashlib
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional, Set
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from urllib.parse import urlparse, urljoin
+import urllib.request
+import urllib.error
+import socket
+from datetime import datetime, timedelta
+
+
+class LinkValidator:
+    """Validates links in AsciiDoc documentation."""
+
+    def __init__(self,
+                 timeout: int = 10,
+                 retry: int = 3,
+                 parallel: int = 10,
+                 cache_duration: int = 3600,
+                 transpositions: List[Tuple[str, str]] = None):
+        """
+        Initialize the link validator.
+
+        Args:
+            timeout: Timeout in seconds for each URL check
+            retry: Number of retries for failed URLs
+            parallel: Number of parallel URL checks
+            cache_duration: Cache duration in seconds
+            transpositions: List of (from_url, to_url) tuples for URL replacement
+        """
+        self.timeout = timeout
+        self.retry = retry
+        self.parallel = parallel
+        self.cache_duration = cache_duration
+        self.transpositions = transpositions or []
+        self.cache = {}
+        self.cache_file = Path.home() / '.cache' / 'doc-utils' / 'link-validation.json'
+        self._load_cache()
+
+    def _load_cache(self):
+        """Load cached validation results."""
+        if self.cache_file.exists():
+            try:
+                with open(self.cache_file, 'r') as f:
+                    cached_data = json.load(f)
+                    # Check cache expiry
+                    now = datetime.now().timestamp()
+                    self.cache = {
+                        url: result for url, result in cached_data.items()
+                        if now - result.get('timestamp', 0) < self.cache_duration
+                    }
+            except (json.JSONDecodeError, IOError):
+                self.cache = {}
+
+    def _save_cache(self):
+        """Save validation results to cache."""
+        self.cache_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.cache_file, 'w') as f:
+            json.dump(self.cache, f, indent=2)
+
+    def transpose_url(self, url: str) -> str:
+        """
+        Apply transposition rules to URL.
+
+        Args:
+            url: Original URL
+
+        Returns:
+            Transposed URL if rules match, otherwise original URL
+        """
+        for from_pattern, to_pattern in self.transpositions:
+            if url.startswith(from_pattern):
+                return url.replace(from_pattern, to_pattern, 1)
+        return url
+
+    def extract_links(self, file_path: str, attributes: Dict[str, str] = None) -> List[Dict]:
+        """
+        Extract all links from an AsciiDoc file.
+
+        Args:
+            file_path: Path to the AsciiDoc file
+            attributes: Dictionary of attribute definitions
+
+        Returns:
+            List of link dictionaries with url, text, type, line_number
+        """
+        links = []
+        attributes = attributes or {}
+
+        with open(file_path, 'r', encoding='utf-8') as f:
+            for line_num, line in enumerate(f, 1):
+                # Find link: macros
+                link_matches = re.finditer(r'link:([^[\]]+)\[([^\]]*)\]', line)
+                for match in link_matches:
+                    url = match.group(1)
+                    text = match.group(2)
+                    # Resolve attributes in URL
+                    resolved_url = self._resolve_attributes(url, attributes)
+                    links.append({
+                        'url': resolved_url,
+                        'original_url': url,
+                        'text': text,
+                        'type': 'external',
+                        'file': file_path,
+                        'line': line_num
+                    })
+
+                # Find xref: macros
+                xref_matches = re.finditer(r'xref:([^[\]]+)\[([^\]]*)\]', line)
+                for match in xref_matches:
+                    target = match.group(1)
+                    text = match.group(2)
+                    # Resolve attributes in target
+                    resolved_target = self._resolve_attributes(target, attributes)
+                    links.append({
+                        'url': resolved_target,
+                        'original_url': target,
+                        'text': text,
+                        'type': 'internal',
+                        'file': file_path,
+                        'line': line_num
+                    })
+
+                # Find image:: directives
+                image_matches = re.finditer(r'image::([^[\]]+)\[', line)
+                for match in image_matches:
+                    path = match.group(1)
+                    resolved_path = self._resolve_attributes(path, attributes)
+                    links.append({
+                        'url': resolved_path,
+                        'original_url': path,
+                        'text': 'image',
+                        'type': 'image',
+                        'file': file_path,
+                        'line': line_num
+                    })
+
+        return links
+
+    def _resolve_attributes(self, text: str, attributes: Dict[str, str]) -> str:
+        """Resolve attributes in text."""
+        resolved = text
+        max_iterations = 10
+
+        for _ in range(max_iterations):
+            # Find all attribute references
+            refs = re.findall(r'\{([^}]+)\}', resolved)
+            if not refs:
+                break
+
+            changes_made = False
+            for ref in refs:
+                if ref in attributes:
+                    resolved = resolved.replace(f'{{{ref}}}', attributes[ref])
+                    changes_made = True
+
+            if not changes_made:
+                break
+
+        return resolved
+
+    def validate_url(self, url: str, original_url: str = None, use_cache: bool = True) -> Dict:
+        """
+        Validate a single URL.
+
+        Args:
+            url: URL to validate
+            original_url: Original URL before transposition
+            use_cache: Whether to use cached results
+
+        Returns:
+            Dictionary with validation results
+        """
+        # Check cache first
+        cache_key = f"{url}:{original_url}" if original_url else url
+        if use_cache and cache_key in self.cache:
+            cached = self.cache[cache_key]
+            if datetime.now().timestamp() - cached['timestamp'] < self.cache_duration:
+                return cached
+
+        result = {
+            'url': url,
+            'original_url': original_url or url,
+            'status': None,
+            'error': None,
+            'redirect': None,
+            'timestamp': datetime.now().timestamp()
+        }
+
+        # Apply transposition if needed
+        check_url = self.transpose_url(url)
+        if check_url != url:
+            result['transposed_url'] = check_url
+
+        # Validate the URL
+        for attempt in range(self.retry):
+            try:
+                req = urllib.request.Request(
+                    check_url,
+                    headers={
+                        'User-Agent': 'Mozilla/5.0 (doc-utils link validator)',
+                        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'
+                    }
+                )
+
+                with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                    result['status'] = response.status
+                    # Check for redirect
+                    if response.url != check_url:
+                        result['redirect'] = response.url
+                    break
+
+            except urllib.error.HTTPError as e:
+                result['status'] = e.code
+                result['error'] = str(e)
+                if e.code not in [500, 502, 503, 504]:  # Don't retry client errors
+                    break
+
+            except urllib.error.URLError as e:
+                result['error'] = str(e.reason)
+
+            except socket.timeout:
+                result['error'] = 'Timeout'
+
+            except Exception as e:
+                result['error'] = str(e)
+
+            # Wait before retry
+            if attempt < self.retry - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+
+        # Cache the result
+        self.cache[cache_key] = result
+
+        return result
+
+    def validate_internal_reference(self, ref: str, base_dir: str) -> Dict:
+        """
+        Validate an internal reference (xref).
+
+        Args:
+            ref: Reference path
+            base_dir: Base directory for relative paths
+
+        Returns:
+            Dictionary with validation results
+        """
+        result = {
+            'url': ref,
+            'type': 'internal',
+            'status': None,
+            'error': None
+        }
+
+        # Handle anchor references
+        if ref.startswith('#'):
+            # TODO: Check if anchor exists in current file
+            result['status'] = 'anchor'
+            return result
+
+        # Parse file and anchor
+        parts = ref.split('#', 1)
+        file_ref = parts[0]
+        anchor = parts[1] if len(parts) > 1 else None
+
+        # Resolve file path
+        if os.path.isabs(file_ref):
+            file_path = file_ref
+        else:
+            file_path = os.path.normpath(os.path.join(base_dir, file_ref))
+
+        # Check if file exists
+        if os.path.exists(file_path):
+            result['status'] = 'ok'
+            # TODO: If anchor provided, check if it exists in the file
+        else:
+            result['status'] = 'missing'
+            result['error'] = f"File not found: {file_path}"
+
+        return result
+
+    def validate_image(self, path: str, base_dir: str) -> Dict:
+        """
+        Validate an image path.
+
+        Args:
+            path: Image path
+            base_dir: Base directory for relative paths
+
+        Returns:
+            Dictionary with validation results
+        """
+        result = {
+            'url': path,
+            'type': 'image',
+            'status': None,
+            'error': None
+        }
+
+        # Check if it's a URL
+        if path.startswith(('http://', 'https://')):
+            return self.validate_url(path)
+
+        # Resolve file path
+        if os.path.isabs(path):
+            file_path = path
+        else:
+            file_path = os.path.normpath(os.path.join(base_dir, path))
+
+        # Check if file exists
+        if os.path.exists(file_path):
+            result['status'] = 'ok'
+        else:
+            result['status'] = 'missing'
+            result['error'] = f"Image not found: {file_path}"
+
+        return result
+
+    def validate_links_in_file(self, file_path: str, attributes: Dict[str, str] = None) -> List[Dict]:
+        """
+        Validate all links in a single file.
+
+        Args:
+            file_path: Path to the AsciiDoc file
+            attributes: Dictionary of attribute definitions
+
+        Returns:
+            List of validation results
+        """
+        links = self.extract_links(file_path, attributes)
+        results = []
+        base_dir = os.path.dirname(file_path)
+
+        # Group links by type for efficient processing
+        external_links = [l for l in links if l['type'] == 'external']
+        internal_links = [l for l in links if l['type'] == 'internal']
+        image_links = [l for l in links if l['type'] == 'image']
+
+        # Validate external links in parallel
+        if external_links:
+            with ThreadPoolExecutor(max_workers=self.parallel) as executor:
+                futures = {
+                    executor.submit(self.validate_url, link['url'], link['original_url']): link
+                    for link in external_links
+                }
+
+                for future in as_completed(futures):
+                    link = futures[future]
+                    try:
+                        result = future.result()
+                        result.update(link)
+                        results.append(result)
+                    except Exception as e:
+                        result = link.copy()
+                        result['error'] = str(e)
+                        results.append(result)
+
+        # Validate internal references
+        for link in internal_links:
+            result = self.validate_internal_reference(link['url'], base_dir)
+            result.update(link)
+            results.append(result)
+
+        # Validate image paths
+        for link in image_links:
+            result = self.validate_image(link['url'], base_dir)
+            result.update(link)
+            results.append(result)
+
+        return results
+
+    def validate_all(self, scan_dirs: List[str] = None,
+                    attributes_file: str = None,
+                    exclude_domains: List[str] = None) -> Dict:
+        """
+        Validate all links in documentation.
+
+        Args:
+            scan_dirs: Directories to scan
+            attributes_file: Path to attributes file
+            exclude_domains: Domains to skip
+
+        Returns:
+            Dictionary with all validation results
+        """
+        if scan_dirs is None:
+            scan_dirs = ['.']
+
+        exclude_domains = exclude_domains or []
+
+        # Load attributes
+        attributes = {}
+        if attributes_file and os.path.exists(attributes_file):
+            attributes = self._load_attributes(attributes_file)
+
+        # Collect all .adoc files
+        adoc_files = []
+        for scan_dir in scan_dirs:
+            for root, _, files in os.walk(scan_dir):
+                # Skip hidden directories
+                if '/.' in root:
+                    continue
+                for file in files:
+                    if file.endswith('.adoc'):
+                        adoc_files.append(os.path.join(root, file))
+
+        # Validate links in all files
+        all_results = {
+            'files': {},
+            'summary': {
+                'total': 0,
+                'valid': 0,
+                'broken': 0,
+                'warnings': 0,
+                'skipped': 0
+            },
+            'broken_links': [],
+            'warnings': [],
+            'transpositions': [
+                {'from': t[0], 'to': t[1]} for t in self.transpositions
+            ]
+        }
+
+        for file_path in adoc_files:
+            results = self.validate_links_in_file(file_path, attributes)
+
+            # Filter out excluded domains
+            filtered_results = []
+            for result in results:
+                url = result.get('url', '')
+                parsed = urlparse(url)
+                if parsed.netloc in exclude_domains:
+                    result['status'] = 'skipped'
+                    result['reason'] = 'Domain excluded'
+                filtered_results.append(result)
+
+            all_results['files'][file_path] = filtered_results
+
+            # Update summary
+            for result in filtered_results:
+                all_results['summary']['total'] += 1
+
+                if result.get('status') == 'skipped':
+                    all_results['summary']['skipped'] += 1
+                elif result.get('status') in ['ok', 200, 'anchor']:
+                    all_results['summary']['valid'] += 1
+                elif result.get('status') in [301, 302, 303, 307, 308]:
+                    all_results['summary']['warnings'] += 1
+                    all_results['warnings'].append(result)
+                elif result.get('error') or result.get('status') in ['missing', 404]:
+                    all_results['summary']['broken'] += 1
+                    all_results['broken_links'].append(result)
+                else:
+                    # Treat other status codes as broken
+                    all_results['summary']['broken'] += 1
+                    all_results['broken_links'].append(result)
+
+        # Save cache
+        self._save_cache()
+
+        return all_results
+
+    def _load_attributes(self, attributes_file: str) -> Dict[str, str]:
+        """Load attributes from file."""
+        attributes = {}
+
+        with open(attributes_file, 'r', encoding='utf-8') as f:
+            for line in f:
+                # Match attribute definitions
+                match = re.match(r'^:([^:]+):\s*(.*)$', line)
+                if match:
+                    attr_name = match.group(1).strip()
+                    attr_value = match.group(2).strip()
+                    attributes[attr_name] = attr_value
+
+        return attributes
+
+
+def parse_transpositions(transpose_args: List[str]) -> List[Tuple[str, str]]:
+    """
+    Parse transposition arguments.
+
+    Args:
+        transpose_args: List of transposition strings in format "from--to"
+
+    Returns:
+        List of (from_url, to_url) tuples
+    """
+    transpositions = []
+
+    for arg in transpose_args or []:
+        parts = arg.split('--')
+        if len(parts) == 2:
+            from_url = parts[0].strip()
+            to_url = parts[1].strip()
+            transpositions.append((from_url, to_url))
+        else:
+            print(f"Warning: Invalid transposition format: {arg}")
+            print("Expected format: from_url--to_url")
+
+    return transpositions
+
+
+def format_results(results: Dict, verbose: bool = False) -> str:
+    """
+    Format validation results for display.
+
+    Args:
+        results: Validation results dictionary
+        verbose: Whether to show verbose output
+
+    Returns:
+        Formatted string for display
+    """
+    output = []
+
+    # Show transpositions if any
+    if results.get('transpositions'):
+        output.append("URL Transposition Rules:")
+        for trans in results['transpositions']:
+            output.append(f"  {trans['from']} → {trans['to']}")
+        output.append("")
+
+    # Summary
+    summary = results['summary']
+    output.append("SUMMARY:")
+    output.append(f"✓ Valid: {summary['valid']} links")
+    if summary['broken'] > 0:
+        output.append(f"✗ Broken: {summary['broken']} links")
+    if summary['warnings'] > 0:
+        output.append(f"⚠ Warnings: {summary['warnings']} redirects")
+    if summary['skipped'] > 0:
+        output.append(f"⊘ Skipped: {summary['skipped']} links (excluded domains)")
+    output.append("")
+
+    # Broken links
+    if results['broken_links']:
+        output.append("BROKEN LINKS:")
+        for i, link in enumerate(results['broken_links'], 1):
+            output.append(f"\n{i}. {link['file']}:{link['line']}")
+            if link.get('original_url') and link.get('original_url') != link.get('url'):
+                output.append(f"   Original: {link['original_url']}")
+                output.append(f"   Resolved: {link['url']}")
+            else:
+                output.append(f"   URL: {link['url']}")
+
+            if link.get('transposed_url'):
+                output.append(f"   Checked: {link['transposed_url']}")
+
+            if link.get('status'):
+                output.append(f"   Status: {link['status']}")
+            if link.get('error'):
+                output.append(f"   Error: {link['error']}")
+        output.append("")
+
+    # Warnings (redirects)
+    if results['warnings'] and verbose:
+        output.append("WARNINGS (Redirects):")
+        for i, link in enumerate(results['warnings'], 1):
+            output.append(f"\n{i}. {link['file']}:{link['line']}")
+            output.append(f"   URL: {link['url']}")
+            if link.get('redirect'):
+                output.append(f"   Redirects to: {link['redirect']}")
+        output.append("")
+
+    return '\n'.join(output)

find_unused_attributes.py

@@ -1,23 +1,61 @@
 """
 Find Unused AsciiDoc Attributes
 
-Scans a user-specified attributes file (e.g., attributes.adoc) for attribute definitions (e.g., :version: 1.1), then recursively scans all .adoc files in the current directory (ignoring symlinks) for usages of those attributes (e.g., {version}).
+Scans an attributes file for attribute definitions (e.g., :version: 1.1), then recursively scans all .adoc files in the current directory (ignoring symlinks) for usages of those attributes (e.g., {version}).
+
+If no attributes file is specified, the tool will auto-discover attributes files in the repository and let you choose one interactively.
 
 Any attribute defined but not used in any .adoc file is reported as NOT USED in both the command line output and a timestamped output file.
 """
 
 import argparse
 import os
+import sys
 from datetime import datetime
-from doc_utils.unused_attributes import find_unused_attributes
+from doc_utils.unused_attributes import find_unused_attributes, find_attributes_files, select_attributes_file
 
 def main():
     parser = argparse.ArgumentParser(description='Find unused AsciiDoc attributes.')
-    parser.add_argument('attributes_file', help='Path to the attributes.adoc file to scan for attribute definitions.')
+    parser.add_argument(
+        'attributes_file',
+        nargs='?',  # Make it optional
+        help='Path to the attributes file. If not specified, auto-discovers attributes files.'
+    )
     parser.add_argument('-o', '--output', action='store_true', help='Write results to a timestamped txt file in your home directory.')
     args = parser.parse_args()
 
-    unused = find_unused_attributes(args.attributes_file, '.')
+    # Determine which attributes file to use
+    if args.attributes_file:
+        # User specified a file
+        attr_file = args.attributes_file
+    else:
+        # Auto-discover attributes files
+        print("Searching for attributes files...")
+        attributes_files = find_attributes_files('.')
+
+        if not attributes_files:
+            print("No attributes files found in the repository.")
+            print("You can specify a file directly: find-unused-attributes <path-to-attributes-file>")
+            return 1
+
+        attr_file = select_attributes_file(attributes_files)
+        if not attr_file:
+            print("No attributes file selected.")
+            return 1
+
+    try:
+        unused = find_unused_attributes(attr_file, '.')
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        print(f"\nPlease ensure the file '{attr_file}' exists.")
+        print("Usage: find-unused-attributes [<path-to-attributes-file>]")
+        return 1
+    except (ValueError, PermissionError) as e:
+        print(f"Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return 1
 
     lines = [f":{attr}:  NOT USED" for attr in unused]
     output = '\n'.join(lines)
@@ -33,9 +71,12 @@ def main():
         home_dir = os.path.expanduser('~')
         filename = os.path.join(home_dir, f'unused_attributes_{timestamp}.txt')
         with open(filename, 'w', encoding='utf-8') as f:
-            f.write('Unused attributes in ' + args.attributes_file + '\n')
+            f.write('Unused attributes in ' + attr_file + '\n')
             f.write(output + '\n')
         print(f'Results written to: {filename}')
 
+    return 0
+
 if __name__ == '__main__':
-    main()
+    import sys
+    sys.exit(main())

{rolfedh_doc_utils-0.1.10.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.10
+Version: 0.1.11
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -79,9 +79,10 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
+| **`validate-links`** [EXPERIMENTAL] | Validates all links in documentation, with URL transposition for preview environments | `validate-links --transpose "https://prod--https://preview"` |
 | **`extract-link-attributes`** | Extracts link/xref macros with attributes into reusable definitions | `extract-link-attributes --dry-run` |
 | **`replace-link-attributes`** | Resolves Vale LinkAttribute issues 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/` |
+| **`format-asciidoc-spacing`** [EXPERIMENTAL] | 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) |
 | **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images` (preview)<br>`archive-unused-images --archive` (execute) |

{rolfedh_doc_utils-0.1.10.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/RECORD

@@ -2,9 +2,10 @@ archive_unused_files.py,sha256=KMC5a1WL3rZ5owoVnncvfpT1YeMKbVXq9giHvadDgbM,1936
 archive_unused_images.py,sha256=PG2o3haovYckgfhoPhl6KRG_a9czyZuqlLkzkupKTCY,1526
 check_scannability.py,sha256=gcM-vFXKHGP_yFBz7-V5xbXWhIMmtMzBYIGwP9CFbzI,5140
 extract_link_attributes.py,sha256=utDM1FE-VEr649HhIH5BreXvxDNLnnAJO9dB5rs5f9Q,2535
-find_unused_attributes.py,sha256=fk-K32eoCVHxoj7RiBNgSmX1arBLuwYfdSAOMc-wIx0,1677
+find_unused_attributes.py,sha256=V8qI7O0u18ExbSho-hLfyBeRVqowLKGrFugY55JxZN0,3023
 format_asciidoc_spacing.py,sha256=ROp-cdMs2_hk8H4z5ljT0iDgGtsiECZ8TVjjcN_oOWE,3874
 replace_link_attributes.py,sha256=vg_aufw7dKXvh_epCKRNq_hEBMU_9crZ_JyJPpxSMNk,6454
+validate_links.py,sha256=DoSB0h3mmjzTY2f0oN6ybTP6jCNkzN7T3qM6oXc2AwE,5585
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/extract_link_attributes.py,sha256=qBpJuTXNrhy15klpqC0iELZzcSLztEzMSmhEnKyQZT0,15574
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
@@ -13,11 +14,12 @@ doc_utils/replace_link_attributes.py,sha256=kBiePbxjQn3O2rzqmYY8Mqy_mJgZ6yw048vS
 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_attributes.py,sha256=EjTtWIKW_aXsR1JOgw5RSDVAqitJ_NfRMVOXVGaiWTY,5282
 doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-rolfedh_doc_utils-0.1.10.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.10.dist-info/METADATA,sha256=Kk1Ur-SbE2XIP55NJ7Y5oVB-KNScnlADwmZyFSthTXo,7180
-rolfedh_doc_utils-0.1.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.10.dist-info/entry_points.txt,sha256=aQtQRDwcdDN-VLBCnQBfmoozzQiaCUZ9dqcLLv8fCkM,381
-rolfedh_doc_utils-0.1.10.dist-info/top_level.txt,sha256=ILTc2mA4sHdDp0GvKC8JXO1I_DBP7vvF5hn-PFkMcL8,167
-rolfedh_doc_utils-0.1.10.dist-info/RECORD,,
+doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
+rolfedh_doc_utils-0.1.11.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.11.dist-info/METADATA,sha256=22seO4nEGTjlibUZ8tPRxTFyYpmLRsfY7sZssteQl1g,7386
+rolfedh_doc_utils-0.1.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.11.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
+rolfedh_doc_utils-0.1.11.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
+rolfedh_doc_utils-0.1.11.dist-info/RECORD,,

{rolfedh_doc_utils-0.1.10.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/entry_points.txt

@@ -6,3 +6,4 @@ extract-link-attributes = extract_link_attributes:main
 find-unused-attributes = find_unused_attributes:main
 format-asciidoc-spacing = format_asciidoc_spacing:main
 replace-link-attributes = replace_link_attributes:main
+validate-links = validate_links:main

{rolfedh_doc_utils-0.1.10.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/top_level.txt

@@ -6,3 +6,4 @@ extract_link_attributes
 find_unused_attributes
 format_asciidoc_spacing
 replace_link_attributes
+validate_links

validate_links.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Validate links in AsciiDoc documentation.
+
+This tool checks all links in AsciiDoc files for validity, including:
+- External HTTP/HTTPS links
+- Internal cross-references (xref)
+- Image paths
+"""
+
+import argparse
+import sys
+import json
+from doc_utils.validate_links import LinkValidator, parse_transpositions, format_results
+
+
+def main():
+    """Main entry point for the validate-links CLI tool."""
+    parser = argparse.ArgumentParser(
+        description='Validate links in AsciiDoc documentation',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Basic validation
+  validate-links
+
+  # Validate against preview environment
+  validate-links --transpose "https://docs.redhat.com--https://preview.docs.redhat.com"
+
+  # Multiple transpositions
+  validate-links \\
+    --transpose "https://docs.redhat.com--https://preview.docs.redhat.com" \\
+    --transpose "https://access.redhat.com--https://stage.access.redhat.com"
+
+  # With specific options
+  validate-links \\
+    --transpose "https://docs.example.com--https://preview.example.com" \\
+    --attributes-file common-attributes.adoc \\
+    --timeout 15 \\
+    --retry 3 \\
+    --parallel 20 \\
+    --exclude-domain localhost \\
+    --exclude-domain example.com
+
+  # Export results to JSON
+  validate-links --output report.json --format json
+        """
+    )
+
+    parser.add_argument(
+        '--transpose',
+        action='append',
+        help='Transpose URLs from production to preview/staging (format: from_url--to_url)'
+    )
+
+    parser.add_argument(
+        '--attributes-file',
+        help='Path to the AsciiDoc attributes file'
+    )
+
+    parser.add_argument(
+        '--scan-dir',
+        action='append',
+        help='Directory to scan for .adoc files (can be used multiple times, default: current directory)'
+    )
+
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        default=10,
+        help='Timeout in seconds for each URL check (default: 10)'
+    )
+
+    parser.add_argument(
+        '--retry',
+        type=int,
+        default=3,
+        help='Number of retries for failed URLs (default: 3)'
+    )
+
+    parser.add_argument(
+        '--parallel',
+        type=int,
+        default=10,
+        help='Number of parallel URL checks (default: 10)'
+    )
+
+    parser.add_argument(
+        '--cache-duration',
+        type=int,
+        default=3600,
+        help='Cache duration in seconds (default: 3600)'
+    )
+
+    parser.add_argument(
+        '--exclude-domain',
+        action='append',
+        dest='exclude_domains',
+        help='Domain to exclude from validation (can be used multiple times)'
+    )
+
+    parser.add_argument(
+        '--no-cache',
+        action='store_true',
+        help='Disable caching of validation results'
+    )
+
+    parser.add_argument(
+        '--output',
+        help='Output file for results'
+    )
+
+    parser.add_argument(
+        '--format',
+        choices=['text', 'json', 'junit'],
+        default='text',
+        help='Output format (default: text)'
+    )
+
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Show verbose output including warnings'
+    )
+
+    parser.add_argument(
+        '--fail-on-broken',
+        action='store_true',
+        help='Exit with error code if broken links are found'
+    )
+
+    args = parser.parse_args()
+
+    # Parse transpositions
+    transpositions = parse_transpositions(args.transpose)
+
+    # Show configuration
+    print("Validating links in documentation...")
+    if args.attributes_file:
+        print(f"Loading attributes from {args.attributes_file}")
+    if transpositions:
+        print("\nURL Transposition Rules:")
+        for from_url, to_url in transpositions:
+            print(f"  {from_url} → {to_url}")
+        print()
+
+    # Create validator
+    validator = LinkValidator(
+        timeout=args.timeout,
+        retry=args.retry,
+        parallel=args.parallel,
+        cache_duration=args.cache_duration if not args.no_cache else 0,
+        transpositions=transpositions
+    )
+
+    try:
+        # Run validation
+        results = validator.validate_all(
+            scan_dirs=args.scan_dir,
+            attributes_file=args.attributes_file,
+            exclude_domains=args.exclude_domains
+        )
+
+        # Format output
+        if args.format == 'json':
+            output = json.dumps(results, indent=2)
+        elif args.format == 'junit':
+            # TODO: Implement JUnit XML format
+            output = format_results(results, verbose=args.verbose)
+        else:
+            output = format_results(results, verbose=args.verbose)
+
+        # Save or print output
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(output)
+            print(f"Results saved to {args.output}")
+            # Still print summary to console
+            if args.format != 'text':
+                summary = results['summary']
+                print(f"\nSummary: {summary['valid']} valid, {summary['broken']} broken, "
+                      f"{summary['warnings']} warnings")
+        else:
+            print(output)
+
+        # Exit code
+        if args.fail_on_broken and results['summary']['broken'] > 0:
+            sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\nValidation cancelled.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()