rolfedh-doc-utils 0.1.9__tar.gz → 0.1.10__tar.gz

{rolfedh_doc_utils-0.1.9/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.9
+Version: 0.1.10
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -79,7 +79,8 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`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/` |
 | **`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.9 → rolfedh_doc_utils-0.1.10}/README.md

@@ -46,7 +46,8 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`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/` |
 | **`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.10/doc_utils/extract_link_attributes.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""
+Extract link and xref macros containing attributes into attribute definitions.
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Set, Tuple, Optional
+from collections import defaultdict
+import unicodedata
+
+
+def find_attribute_files(base_path: str = '.') -> List[str]:
+    """Find potential attribute files in the repository."""
+    common_patterns = [
+        '**/common-attributes.adoc',
+        '**/attributes.adoc',
+        '**/*-attributes.adoc',
+        '**/attributes-*.adoc',
+        '**/common_attributes.adoc',
+        '**/_common-attributes.adoc'
+    ]
+
+    attribute_files = []
+    base = Path(base_path)
+
+    for pattern in common_patterns:
+        for file_path in base.glob(pattern):
+            if file_path.is_file():
+                rel_path = file_path.relative_to(base)
+                attribute_files.append(str(rel_path))
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_files = []
+    for f in attribute_files:
+        if f not in seen:
+            seen.add(f)
+            unique_files.append(f)
+
+    return sorted(unique_files)
+
+
+def select_attribute_file(attribute_files: List[str]) -> str:
+    """Let user interactively select an attribute file."""
+    if not attribute_files:
+        return None
+
+    print("\nMultiple attribute files found. Please select one:")
+    for i, file_path in enumerate(attribute_files, 1):
+        print(f"  {i}. {file_path}")
+
+    while True:
+        try:
+            choice = input(f"\nEnter your choice (1-{len(attribute_files)}): ").strip()
+            index = int(choice) - 1
+            if 0 <= index < len(attribute_files):
+                return attribute_files[index]
+            else:
+                print(f"Please enter a number between 1 and {len(attribute_files)}")
+        except (ValueError, EOFError, KeyboardInterrupt):
+            print("\nOperation cancelled.")
+            return None
+
+
+def load_existing_attributes(file_path: str) -> Dict[str, str]:
+    """Load existing attributes from file."""
+    attributes = {}
+    if not os.path.exists(file_path):
+        return attributes
+
+    with open(file_path, '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 find_link_macros(file_path: str) -> List[Tuple[str, str, str, int]]:
+    """
+    Find all link: and xref: macros containing attributes in their URLs.
+
+    Returns list of tuples: (full_macro, url, link_text, line_number)
+    """
+    macros = []
+
+    with open(file_path, 'r', encoding='utf-8') as f:
+        for line_num, line in enumerate(f, 1):
+            # Pattern to match link: and xref: macros
+            # Matches: (link|xref):url[text] where url contains {attribute}
+            patterns = [
+                r'(link:([^[\]]*\{[^}]+\}[^[\]]*)\[([^\]]*)\])',
+                r'(xref:([^[\]]*\{[^}]+\}[^[\]]*)\[([^\]]*)\])'
+            ]
+
+            for pattern in patterns:
+                for match in re.finditer(pattern, line, re.IGNORECASE):
+                    full_macro = match.group(1)
+                    url = match.group(2)
+                    link_text = match.group(3)
+                    macros.append((full_macro, url, link_text, line_num))
+
+    return macros
+
+
+def generate_attribute_name(url: str, existing_attrs: Set[str], counter: int) -> str:
+    """Generate a unique attribute name from URL."""
+    # Start with a base name from the URL
+    base_name = url
+
+    # Extract domain or path components
+    if '://' in url:
+        # Remove protocol
+        base_name = re.sub(r'^[^:]+://', '', url)
+
+    # Remove attributes from the name generation
+    base_name = re.sub(r'\{[^}]+\}', '', base_name)
+
+    # Extract meaningful parts
+    if '/' in base_name:
+        parts = base_name.split('/')
+        # Use domain and last path component
+        if len(parts) > 1:
+            domain_part = parts[0].replace('.', '-')
+            path_part = parts[-1].split('.')[0] if parts[-1] else ''
+            if path_part:
+                base_name = f"{domain_part}-{path_part}"
+            else:
+                base_name = domain_part
+
+    # Clean up the name
+    base_name = re.sub(r'[^a-zA-Z0-9-]', '-', base_name)
+    base_name = re.sub(r'-+', '-', base_name)
+    base_name = base_name.strip('-').lower()
+
+    # Limit length
+    if len(base_name) > 30:
+        base_name = base_name[:30]
+
+    # Make it unique
+    attr_name = f"link-{base_name}"
+    original_name = attr_name
+    suffix = 1
+
+    while attr_name in existing_attrs:
+        attr_name = f"{original_name}-{suffix}"
+        suffix += 1
+
+    return attr_name
+
+
+def group_macros_by_url(macros: List[Tuple[str, str, str, str, int]]) -> Dict[str, List[Tuple[str, str, str, int]]]:
+    """
+    Group macros by URL, collecting all link text variations.
+
+    Returns: Dict[url, List[(file_path, link_text, full_macro, line_number)]]
+    """
+    url_groups = defaultdict(list)
+
+    for file_path, full_macro, url, link_text, line_num in macros:
+        url_groups[url].append((file_path, link_text, full_macro, line_num))
+
+    return url_groups
+
+
+def select_link_text(url: str, variations: List[Tuple[str, str, str, int]], interactive: bool = True) -> str:
+    """
+    Select link text for a URL with multiple variations.
+
+    variations: List[(file_path, link_text, full_macro, line_number)]
+    """
+    # Extract unique link texts
+    unique_texts = {}
+    for file_path, link_text, _, line_num in variations:
+        if link_text not in unique_texts:
+            unique_texts[link_text] = []
+        unique_texts[link_text].append(f"{file_path}:{line_num}")
+
+    if len(unique_texts) == 1:
+        # Only one variation, use it
+        return list(unique_texts.keys())[0]
+
+    if not interactive:
+        # Use most common (appears in most locations)
+        most_common = max(unique_texts.items(), key=lambda x: len(x[1]))
+        return most_common[0]
+
+    # Interactive selection
+    print(f"\nMultiple link text variations found for URL: {url}")
+    print("Please select the preferred text:")
+
+    text_list = list(unique_texts.items())
+    for i, (text, locations) in enumerate(text_list, 1):
+        print(f"\n  {i}. \"{text}\"")
+        print(f"     Used in: {', '.join(locations[:3])}")
+        if len(locations) > 3:
+            print(f"     ... and {len(locations) - 3} more locations")
+
+    print(f"\n  {len(text_list) + 1}. Enter custom text")
+
+    while True:
+        try:
+            choice = input(f"\nEnter your choice (1-{len(text_list) + 1}): ").strip()
+            index = int(choice) - 1
+
+            if 0 <= index < len(text_list):
+                return text_list[index][0]
+            elif index == len(text_list):
+                custom_text = input("Enter custom link text: ").strip()
+                if custom_text:
+                    return custom_text
+                else:
+                    print("Text cannot be empty. Please try again.")
+            else:
+                print(f"Please enter a number between 1 and {len(text_list) + 1}")
+        except (ValueError, EOFError, KeyboardInterrupt):
+            print("\nUsing most common text variation.")
+            most_common = max(unique_texts.items(), key=lambda x: len(x[1]))
+            return most_common[0]
+
+
+def collect_all_macros(scan_dirs: List[str] = None) -> List[Tuple[str, str, str, str, int]]:
+    """
+    Collect all link/xref macros with attributes from all .adoc files.
+
+    Returns: List[(file_path, full_macro, url, link_text, line_number)]
+    """
+    if scan_dirs is None:
+        scan_dirs = ['.']
+
+    all_macros = []
+
+    for scan_dir in scan_dirs:
+        for root, _, files in os.walk(scan_dir):
+            # Skip hidden directories and .archive
+            if '/.archive' in root or '/.' in root:
+                continue
+
+            for file in files:
+                if file.endswith('.adoc'):
+                    file_path = os.path.join(root, file)
+                    macros = find_link_macros(file_path)
+                    for full_macro, url, link_text, line_num in macros:
+                        all_macros.append((file_path, full_macro, url, link_text, line_num))
+
+    return all_macros
+
+
+def create_attributes(url_groups: Dict[str, List[Tuple[str, str, str, int]]],
+                     existing_attrs: Dict[str, str],
+                     interactive: bool = True) -> Dict[str, str]:
+    """
+    Create new attributes for each unique URL.
+
+    Returns: Dict[attribute_name, attribute_value]
+    """
+    new_attributes = {}
+    existing_attr_names = set(existing_attrs.keys())
+    counter = 1
+
+    for url, variations in url_groups.items():
+        # Check if this URL already has an attribute
+        existing_attr = None
+        for attr_name, attr_value in existing_attrs.items():
+            if url in attr_value:
+                existing_attr = attr_name
+                break
+
+        if existing_attr:
+            print(f"URL already has attribute {{{existing_attr}}}: {url}")
+            continue
+
+        # Select link text
+        link_text = select_link_text(url, variations, interactive)
+
+        # Generate attribute name
+        attr_name = generate_attribute_name(url, existing_attr_names | set(new_attributes.keys()), counter)
+        counter += 1
+
+        # Determine macro type (link or xref)
+        first_macro = variations[0][2]  # full_macro from first variation
+        macro_type = 'xref' if first_macro.startswith('xref:') else 'link'
+
+        # Create attribute value
+        attr_value = f"{macro_type}:{url}[{link_text}]"
+        new_attributes[attr_name] = attr_value
+
+        print(f"Created attribute: :{attr_name}: {attr_value}")
+
+    return new_attributes
+
+
+def update_attribute_file(file_path: str, new_attributes: Dict[str, str], dry_run: bool = False):
+    """Add new attributes to the attribute file."""
+    if not new_attributes:
+        print("No new attributes to add.")
+        return
+
+    if dry_run:
+        print(f"\n[DRY RUN] Would add {len(new_attributes)} attributes to {file_path}:")
+        for attr_name, attr_value in new_attributes.items():
+            print(f"  :{attr_name}: {attr_value}")
+        return
+
+    # Ensure directory exists
+    os.makedirs(os.path.dirname(file_path) if os.path.dirname(file_path) else '.', exist_ok=True)
+
+    # Append new attributes
+    with open(file_path, 'a', encoding='utf-8') as f:
+        if os.path.getsize(file_path) > 0:
+            f.write('\n')  # Add newline if file not empty
+        f.write('// Extracted link attributes\n')
+        for attr_name, attr_value in sorted(new_attributes.items()):
+            f.write(f":{attr_name}: {attr_value}\n")
+
+    print(f"Added {len(new_attributes)} attributes to {file_path}")
+
+
+def replace_macros_with_attributes(file_updates: Dict[str, List[Tuple[str, str]]], dry_run: bool = False):
+    """
+    Replace link/xref macros with their attribute references.
+
+    file_updates: Dict[file_path, List[(old_macro, attribute_ref)]]
+    """
+    for file_path, replacements in file_updates.items():
+        if dry_run:
+            print(f"\n[DRY RUN] Would update {file_path}:")
+            for old_macro, attr_ref in replacements[:3]:
+                print(f"  Replace: {old_macro}")
+                print(f"     With: {attr_ref}")
+            if len(replacements) > 3:
+                print(f"  ... and {len(replacements) - 3} more replacements")
+            continue
+
+        # Read file
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        # Apply replacements
+        for old_macro, attr_ref in replacements:
+            content = content.replace(old_macro, attr_ref)
+
+        # Write file
+        with open(file_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        print(f"Updated {file_path}: {len(replacements)} replacements")
+
+
+def prepare_file_updates(url_groups: Dict[str, List[Tuple[str, str, str, int]]],
+                        attribute_mapping: Dict[str, str]) -> Dict[str, List[Tuple[str, str]]]:
+    """
+    Prepare file updates mapping macros to attribute references.
+
+    Returns: Dict[file_path, List[(old_macro, attribute_ref)]]
+    """
+    file_updates = defaultdict(list)
+
+    # Create reverse mapping from URL to attribute name
+    url_to_attr = {}
+    for attr_name, attr_value in attribute_mapping.items():
+        # Extract URL from attribute value
+        match = re.match(r'(?:link|xref):([^\[]+)\[', attr_value)
+        if match:
+            url = match.group(1)
+            url_to_attr[url] = attr_name
+
+    # Map each macro occurrence to its attribute
+    for url, variations in url_groups.items():
+        if url in url_to_attr:
+            attr_name = url_to_attr[url]
+            for file_path, _, full_macro, _ in variations:
+                file_updates[file_path].append((full_macro, f"{{{attr_name}}}"))
+
+    return dict(file_updates)
+
+
+def extract_link_attributes(attributes_file: str = None,
+                           scan_dirs: List[str] = None,
+                           interactive: bool = True,
+                           dry_run: bool = False) -> bool:
+    """
+    Main function to extract link attributes.
+
+    Returns: True if successful, False otherwise
+    """
+    # Find or confirm attributes file
+    if not attributes_file:
+        found_files = find_attribute_files()
+
+        if not found_files:
+            print("No attribute files found.")
+            response = input("Create common-attributes.adoc? (y/n): ").strip().lower()
+            if response == 'y':
+                attributes_file = 'common-attributes.adoc'
+            else:
+                print("Please specify an attribute file with --attributes-file")
+                return False
+        elif len(found_files) == 1:
+            attributes_file = found_files[0]
+            print(f"Using attribute file: {attributes_file}")
+        else:
+            attributes_file = select_attribute_file(found_files)
+            if not attributes_file:
+                return False
+
+    # Load existing attributes
+    existing_attrs = load_existing_attributes(attributes_file)
+    print(f"Loaded {len(existing_attrs)} existing attributes")
+
+    # Collect all macros
+    print("\nScanning for link and xref macros with attributes...")
+    all_macros = collect_all_macros(scan_dirs)
+
+    if not all_macros:
+        print("No link or xref macros with attributes found.")
+        return True
+
+    print(f"Found {len(all_macros)} link/xref macros with attributes")
+
+    # Group by URL
+    url_groups = group_macros_by_url(all_macros)
+    print(f"Grouped into {len(url_groups)} unique URLs")
+
+    # Create new attributes
+    new_attributes = create_attributes(url_groups, existing_attrs, interactive)
+
+    if not new_attributes:
+        print("No new attributes to create.")
+        return True
+
+    # Update attribute file
+    update_attribute_file(attributes_file, new_attributes, dry_run)
+
+    # Prepare file updates
+    all_attributes = {**existing_attrs, **new_attributes}
+    file_updates = prepare_file_updates(url_groups, all_attributes)
+
+    # Replace macros
+    replace_macros_with_attributes(file_updates, dry_run)
+
+    if dry_run:
+        print("\n[DRY RUN] No files were modified. Run without --dry-run to apply changes.")
+    else:
+        print(f"\nSuccessfully extracted {len(new_attributes)} link attributes")
+
+    return True

rolfedh_doc_utils-0.1.10/extract_link_attributes.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Extract link and xref macros containing attributes into attribute definitions.
+
+This tool finds all link: and xref: macros whose URLs contain attributes,
+creates attribute definitions for them, and replaces the macros with
+attribute references.
+"""
+
+import argparse
+import sys
+from doc_utils.extract_link_attributes import extract_link_attributes
+
+
+def main():
+    """Main entry point for the extract-link-attributes CLI tool."""
+    parser = argparse.ArgumentParser(
+        description='Extract link and xref macros containing attributes into attribute definitions',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive mode with auto-discovery
+  extract-link-attributes
+
+  # Specify attribute file
+  extract-link-attributes --attributes-file common-attributes.adoc
+
+  # Non-interactive mode (uses most common link text)
+  extract-link-attributes --non-interactive
+
+  # Dry run to preview changes
+  extract-link-attributes --dry-run
+
+  # Scan specific directories
+  extract-link-attributes --scan-dir modules --scan-dir assemblies
+        """
+    )
+
+    parser.add_argument(
+        '--attributes-file',
+        help='Path to the attributes file to update (auto-discovered if not specified)'
+    )
+
+    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(
+        '--non-interactive',
+        action='store_true',
+        help='Non-interactive mode: automatically use most common link text for variations'
+    )
+
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview changes without modifying files'
+    )
+
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Enable verbose output'
+    )
+
+    args = parser.parse_args()
+
+    try:
+        success = extract_link_attributes(
+            attributes_file=args.attributes_file,
+            scan_dirs=args.scan_dir,
+            interactive=not args.non_interactive,
+            dry_run=args.dry_run
+        )
+
+        if not success:
+            sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\nOperation 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()

{rolfedh_doc_utils-0.1.9 → rolfedh_doc_utils-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.9"
+version = "0.1.10"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -21,10 +21,11 @@ archive-unused-images = "archive_unused_images:main"
 find-unused-attributes = "find_unused_attributes:main"
 format-asciidoc-spacing = "format_asciidoc_spacing:main"
 replace-link-attributes = "replace_link_attributes:main"
+extract-link-attributes = "extract_link_attributes:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["doc_utils*"]
 
 [tool.setuptools]
-py-modules = ["find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes"]
+py-modules = ["find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes", "extract_link_attributes"]

{rolfedh_doc_utils-0.1.9 → rolfedh_doc_utils-0.1.10/rolfedh_doc_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.9
+Version: 0.1.10
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -79,7 +79,8 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`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/` |
 | **`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.9 → rolfedh_doc_utils-0.1.10}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -3,12 +3,14 @@ README.md
 archive_unused_files.py
 archive_unused_images.py
 check_scannability.py
+extract_link_attributes.py
 find_unused_attributes.py
 format_asciidoc_spacing.py
 pyproject.toml
 replace_link_attributes.py
 setup.py
 doc_utils/__init__.py
+doc_utils/extract_link_attributes.py
 doc_utils/file_utils.py
 doc_utils/format_asciidoc_spacing.py
 doc_utils/replace_link_attributes.py
@@ -28,6 +30,7 @@ tests/test_archive_unused_images.py
 tests/test_auto_discovery.py
 tests/test_check_scannability.py
 tests/test_cli_entry_points.py
+tests/test_extract_link_attributes.py
 tests/test_file_utils.py
 tests/test_fixture_archive_unused_files.py
 tests/test_fixture_archive_unused_images.py

{rolfedh_doc_utils-0.1.9 → rolfedh_doc_utils-0.1.10}/rolfedh_doc_utils.egg-info/entry_points.txt

@@ -2,6 +2,7 @@
 archive-unused-files = archive_unused_files:main
 archive-unused-images = archive_unused_images:main
 check-scannability = check_scannability:main
+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

{rolfedh_doc_utils-0.1.9 → rolfedh_doc_utils-0.1.10}/rolfedh_doc_utils.egg-info/top_level.txt

@@ -2,6 +2,7 @@ archive_unused_files
 archive_unused_images
 check_scannability
 doc_utils
+extract_link_attributes
 find_unused_attributes
 format_asciidoc_spacing
 replace_link_attributes

rolfedh_doc_utils-0.1.10/tests/test_extract_link_attributes.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""Tests for extract_link_attributes module."""
+
+import os
+import tempfile
+import shutil
+from pathlib import Path
+import pytest
+from doc_utils.extract_link_attributes import (
+    find_attribute_files,
+    find_link_macros,
+    generate_attribute_name,
+    group_macros_by_url,
+    select_link_text,
+    load_existing_attributes,
+    create_attributes,
+    prepare_file_updates,
+    extract_link_attributes
+)
+
+
+class TestFindAttributeFiles:
+    """Tests for find_attribute_files function."""
+
+    def test_find_common_attribute_files(self, tmp_path):
+        """Test finding common attribute file patterns."""
+        # Create test files
+        (tmp_path / "common-attributes.adoc").touch()
+        (tmp_path / "attributes.adoc").touch()
+        (tmp_path / "custom-attributes.adoc").touch()
+        subdir = tmp_path / "modules"
+        subdir.mkdir()
+        (subdir / "module-attributes.adoc").touch()
+
+        # Find files
+        files = find_attribute_files(str(tmp_path))
+
+        assert len(files) == 4
+        assert "common-attributes.adoc" in files
+        assert "attributes.adoc" in files
+        assert "custom-attributes.adoc" in files
+        assert "modules/module-attributes.adoc" in files
+
+    def test_no_attribute_files(self, tmp_path):
+        """Test when no attribute files exist."""
+        files = find_attribute_files(str(tmp_path))
+        assert files == []
+
+
+class TestFindLinkMacros:
+    """Tests for find_link_macros function."""
+
+    def test_find_link_with_attributes(self, tmp_path):
+        """Test finding link macros with attributes."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+See link:https://example.com/{product-version}/guide.html[User Guide] for details.
+
+Also check xref:{base-url}/intro.html[Introduction].
+
+Regular link without attributes: link:https://example.com/static.html[Static Link]
+""")
+
+        macros = find_link_macros(str(test_file))
+
+        assert len(macros) == 2
+        # First macro
+        assert macros[0][0] == "link:https://example.com/{product-version}/guide.html[User Guide]"
+        assert macros[0][1] == "https://example.com/{product-version}/guide.html"
+        assert macros[0][2] == "User Guide"
+        assert macros[0][3] == 4  # Line number (accounting for empty first line)
+
+        # Second macro
+        assert macros[1][0] == "xref:{base-url}/intro.html[Introduction]"
+        assert macros[1][1] == "{base-url}/intro.html"
+        assert macros[1][2] == "Introduction"
+        assert macros[1][3] == 6  # Line number
+
+    def test_no_macros_with_attributes(self, tmp_path):
+        """Test file with no macros containing attributes."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+Regular link: link:https://example.com/guide.html[Guide]
+""")
+
+        macros = find_link_macros(str(test_file))
+        assert len(macros) == 0
+
+
+class TestGenerateAttributeName:
+    """Tests for generate_attribute_name function."""
+
+    def test_generate_from_url_with_domain(self):
+        """Test attribute name generation from URL with domain."""
+        url = "https://docs.example.com/{version}/guide.html"
+        existing = set()
+
+        name = generate_attribute_name(url, existing, 1)
+
+        assert name.startswith("link-")
+        assert "docs-example" in name or "guide" in name
+
+    def test_generate_unique_names(self):
+        """Test generating unique names when conflicts exist."""
+        url = "https://example.com/guide.html"
+        existing = {"link-example-com-guide"}
+
+        name = generate_attribute_name(url, existing, 1)
+
+        assert name != "link-example-com-guide"
+        assert name.startswith("link-")
+
+    def test_clean_special_characters(self):
+        """Test that special characters are cleaned."""
+        url = "https://example.com/path with spaces/{attr}/file.html"
+        existing = set()
+
+        name = generate_attribute_name(url, existing, 1)
+
+        # Should not contain spaces or special chars
+        assert " " not in name
+        assert "/" not in name
+        assert "." not in name
+
+
+class TestGroupMacrosByUrl:
+    """Tests for group_macros_by_url function."""
+
+    def test_group_same_urls(self):
+        """Test grouping macros with the same URL."""
+        macros = [
+            ("file1.adoc", "link:url1[Text1]", "url1", "Text1", 1),
+            ("file2.adoc", "link:url1[Text2]", "url1", "Text2", 5),
+            ("file3.adoc", "link:url2[Text3]", "url2", "Text3", 10),
+        ]
+
+        groups = group_macros_by_url(macros)
+
+        assert len(groups) == 2
+        assert "url1" in groups
+        assert "url2" in groups
+        assert len(groups["url1"]) == 2
+        assert len(groups["url2"]) == 1
+
+
+class TestSelectLinkText:
+    """Tests for select_link_text function."""
+
+    def test_single_variation(self):
+        """Test when there's only one link text variation."""
+        variations = [
+            ("file1.adoc", "Same Text", "link:url[Same Text]", 1),
+            ("file2.adoc", "Same Text", "link:url[Same Text]", 2),
+        ]
+
+        result = select_link_text("url", variations, interactive=False)
+
+        assert result == "Same Text"
+
+    def test_non_interactive_most_common(self):
+        """Test non-interactive mode selects most common text."""
+        variations = [
+            ("file1.adoc", "Text A", "link:url[Text A]", 1),
+            ("file2.adoc", "Text B", "link:url[Text B]", 2),
+            ("file3.adoc", "Text A", "link:url[Text A]", 3),
+        ]
+
+        result = select_link_text("url", variations, interactive=False)
+
+        assert result == "Text A"  # Most common
+
+
+class TestLoadExistingAttributes:
+    """Tests for load_existing_attributes function."""
+
+    def test_load_attributes(self, tmp_path):
+        """Test loading existing attributes from file."""
+        attr_file = tmp_path / "attributes.adoc"
+        attr_file.write_text("""
+// Common attributes
+:product-name: My Product
+:version: 1.0
+:docs-url: https://docs.example.com
+:link-guide: link:https://example.com/guide.html[User Guide]
+""")
+
+        attrs = load_existing_attributes(str(attr_file))
+
+        assert len(attrs) == 4
+        assert attrs["product-name"] == "My Product"
+        assert attrs["version"] == "1.0"
+        assert attrs["docs-url"] == "https://docs.example.com"
+        assert attrs["link-guide"] == "link:https://example.com/guide.html[User Guide]"
+
+    def test_load_nonexistent_file(self, tmp_path):
+        """Test loading from non-existent file."""
+        attrs = load_existing_attributes(str(tmp_path / "missing.adoc"))
+        assert attrs == {}
+
+
+class TestCreateAttributes:
+    """Tests for create_attributes function."""
+
+    def test_create_new_attributes(self):
+        """Test creating new attributes for URLs."""
+        url_groups = {
+            "https://example.com/{version}/guide.html": [
+                ("file1.adoc", "Guide", "link:https://example.com/{version}/guide.html[Guide]", 1)
+            ],
+            "{base-url}/intro.html": [
+                ("file2.adoc", "Intro", "xref:{base-url}/intro.html[Intro]", 2)
+            ]
+        }
+        existing_attrs = {}
+
+        new_attrs = create_attributes(url_groups, existing_attrs, interactive=False)
+
+        assert len(new_attrs) == 2
+        # Check that attributes were created
+        attr_values = list(new_attrs.values())
+        assert any("link:https://example.com/{version}/guide.html[Guide]" in v for v in attr_values)
+        assert any("xref:{base-url}/intro.html[Intro]" in v for v in attr_values)
+
+    def test_skip_existing_urls(self, capsys):
+        """Test that URLs with existing attributes are skipped."""
+        url_groups = {
+            "https://example.com/guide.html": [
+                ("file1.adoc", "Guide", "link:https://example.com/guide.html[Guide]", 1)
+            ]
+        }
+        existing_attrs = {
+            "existing-link": "link:https://example.com/guide.html[Existing Guide]"
+        }
+
+        new_attrs = create_attributes(url_groups, existing_attrs, interactive=False)
+
+        assert len(new_attrs) == 0
+        captured = capsys.readouterr()
+        assert "already has attribute" in captured.out
+
+
+class TestPrepareFileUpdates:
+    """Tests for prepare_file_updates function."""
+
+    def test_prepare_updates(self):
+        """Test preparing file updates."""
+        url_groups = {
+            "url1": [
+                ("file1.adoc", "Text1", "link:url1[Text1]", 1),
+                ("file2.adoc", "Text1", "link:url1[Text1]", 2),
+            ],
+            "url2": [
+                ("file1.adoc", "Text2", "link:url2[Text2]", 3),
+            ]
+        }
+        attribute_mapping = {
+            "link-1": "link:url1[Text1]",
+            "link-2": "link:url2[Text2]"
+        }
+
+        updates = prepare_file_updates(url_groups, attribute_mapping)
+
+        assert len(updates) == 2
+        assert "file1.adoc" in updates
+        assert "file2.adoc" in updates
+        assert len(updates["file1.adoc"]) == 2  # Two replacements in file1
+        assert len(updates["file2.adoc"]) == 1  # One replacement in file2
+
+        # Check replacement pairs
+        file1_updates = updates["file1.adoc"]
+        assert ("link:url1[Text1]", "{link-1}") in file1_updates
+        assert ("link:url2[Text2]", "{link-2}") in file1_updates
+
+
+class TestExtractLinkAttributesIntegration:
+    """Integration tests for the main extract_link_attributes function."""
+
+    def test_full_extraction_dry_run(self, tmp_path, capsys):
+        """Test full extraction process in dry-run mode."""
+        # Create test structure
+        modules_dir = tmp_path / "modules"
+        modules_dir.mkdir()
+
+        # Create attribute file
+        attr_file = tmp_path / "common-attributes.adoc"
+        attr_file.write_text(":existing-attr: value\n")
+
+        # Create test .adoc file with links
+        test_file = modules_dir / "test.adoc"
+        test_file.write_text("""
+= Test Module
+
+See link:https://docs.example.com/{version}/guide.html[Installation Guide] for setup.
+
+Also check link:https://docs.example.com/{version}/guide.html[Setup Guide] for config.
+
+And xref:{base-url}/intro.html[Introduction] for overview.
+""")
+
+        # Run extraction in dry-run mode
+        os.chdir(tmp_path)
+        result = extract_link_attributes(
+            attributes_file=str(attr_file),
+            scan_dirs=[str(modules_dir)],
+            interactive=False,
+            dry_run=True
+        )
+
+        assert result is True
+
+        # Check output
+        captured = capsys.readouterr()
+        assert "Found 3 link/xref macros" in captured.out
+        assert "Grouped into 2 unique URLs" in captured.out
+        assert "[DRY RUN]" in captured.out
+
+        # Verify no files were modified
+        assert attr_file.read_text() == ":existing-attr: value\n"
+
+    def test_full_extraction_with_write(self, tmp_path):
+        """Test full extraction process with actual file updates."""
+        # Create test structure
+        modules_dir = tmp_path / "modules"
+        modules_dir.mkdir()
+
+        # Create attribute file
+        attr_file = tmp_path / "common-attributes.adoc"
+        attr_file.write_text(":existing-attr: value\n")
+
+        # Create test .adoc file
+        test_file = modules_dir / "test.adoc"
+        original_content = """
+= Test Module
+
+See link:https://example.com/{version}/guide.html[Guide] for info.
+"""
+        test_file.write_text(original_content)
+
+        # Run extraction
+        os.chdir(tmp_path)
+        result = extract_link_attributes(
+            attributes_file=str(attr_file),
+            scan_dirs=[str(modules_dir)],
+            interactive=False,
+            dry_run=False
+        )
+
+        assert result is True
+
+        # Check that attribute file was updated
+        attr_content = attr_file.read_text()
+        assert ":existing-attr: value" in attr_content
+        assert "// Extracted link attributes" in attr_content
+        assert "link:https://example.com/{version}/guide.html[Guide]" in attr_content
+
+        # Check that .adoc file was updated
+        updated_content = test_file.read_text()
+        assert "link:https://example.com/{version}/guide.html[Guide]" not in updated_content
+        assert "{link-" in updated_content  # Should have attribute reference