rolfedh-doc-utils 0.1.12__tar.gz → 0.1.14__tar.gz

{rolfedh_doc_utils-0.1.12/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.12
+Version: 0.1.14
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/doc_utils/extract_link_attributes.py

@@ -85,10 +85,14 @@ def load_existing_attributes(file_path: str) -> Dict[str, str]:
     return attributes
 
 
-def find_link_macros(file_path: str) -> List[Tuple[str, str, str, int]]:
+def find_link_macros(file_path: str, macro_type: str = 'both') -> List[Tuple[str, str, str, int]]:
     """
     Find all link: and xref: macros containing attributes in their URLs.
 
+    Args:
+        file_path: Path to the file to scan
+        macro_type: Type of macros to find - 'link', 'xref', or 'both' (default: 'both')
+
     Returns list of tuples: (full_macro, url, link_text, line_number)
     """
     macros = []
@@ -97,10 +101,13 @@ def find_link_macros(file_path: str) -> List[Tuple[str, str, str, int]]:
         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:([^[\]]*\{[^}]+\}[^[\]]*)\[([^\]]*)\])'
-            ]
+            patterns = []
+
+            if macro_type in ('link', 'both'):
+                patterns.append(r'(link:([^[\]]*\{[^}]+\}[^[\]]*)\[([^\]]*)\])')
+
+            if macro_type in ('xref', 'both'):
+                patterns.append(r'(xref:([^[\]]*\{[^}]+\}[^[\]]*)\[([^\]]*)\])')
 
             for pattern in patterns:
                 for match in re.finditer(pattern, line, re.IGNORECASE):
@@ -228,10 +235,14 @@ def select_link_text(url: str, variations: List[Tuple[str, str, str, int]], inte
             return most_common[0]
 
 
-def collect_all_macros(scan_dirs: List[str] = None) -> List[Tuple[str, str, str, str, int]]:
+def collect_all_macros(scan_dirs: List[str] = None, macro_type: str = 'both') -> List[Tuple[str, str, str, str, int]]:
     """
     Collect all link/xref macros with attributes from all .adoc files.
 
+    Args:
+        scan_dirs: Directories to scan (default: current directory)
+        macro_type: Type of macros to find - 'link', 'xref', or 'both' (default: 'both')
+
     Returns: List[(file_path, full_macro, url, link_text, line_number)]
     """
     if scan_dirs is None:
@@ -248,7 +259,7 @@ def collect_all_macros(scan_dirs: List[str] = None) -> List[Tuple[str, str, str,
             for file in files:
                 if file.endswith('.adoc'):
                     file_path = os.path.join(root, file)
-                    macros = find_link_macros(file_path)
+                    macros = find_link_macros(file_path, macro_type)
                     for full_macro, url, link_text, line_num in macros:
                         all_macros.append((file_path, full_macro, url, link_text, line_num))
 
@@ -257,13 +268,14 @@ def collect_all_macros(scan_dirs: List[str] = None) -> List[Tuple[str, str, str,
 
 def create_attributes(url_groups: Dict[str, List[Tuple[str, str, str, int]]],
                      existing_attrs: Dict[str, str],
-                     interactive: bool = True) -> Dict[str, str]:
+                     interactive: bool = True) -> Tuple[Dict[str, str], Dict[str, str]]:
     """
-    Create new attributes for each unique URL.
+    Create new attributes for each unique URL and track existing ones.
 
-    Returns: Dict[attribute_name, attribute_value]
+    Returns: Tuple[new_attributes, existing_matching_attributes]
     """
     new_attributes = {}
+    existing_matching_attributes = {}
     existing_attr_names = set(existing_attrs.keys())
     counter = 1
 
@@ -273,6 +285,7 @@ def create_attributes(url_groups: Dict[str, List[Tuple[str, str, str, int]]],
         for attr_name, attr_value in existing_attrs.items():
             if url in attr_value:
                 existing_attr = attr_name
+                existing_matching_attributes[attr_name] = attr_value
                 break
 
         if existing_attr:
@@ -296,7 +309,7 @@ def create_attributes(url_groups: Dict[str, List[Tuple[str, str, str, int]]],
 
         print(f"Created attribute: :{attr_name}: {attr_value}")
 
-    return new_attributes
+    return new_attributes, existing_matching_attributes
 
 
 def update_attribute_file(file_path: str, new_attributes: Dict[str, str], dry_run: bool = False):
@@ -450,10 +463,20 @@ def extract_link_attributes(attributes_file: str = None,
                            interactive: bool = True,
                            dry_run: bool = False,
                            validate_links: bool = False,
-                           fail_on_broken: bool = False) -> bool:
+                           fail_on_broken: bool = False,
+                           macro_type: str = 'both') -> bool:
     """
     Main function to extract link attributes.
 
+    Args:
+        attributes_file: Path to attributes file
+        scan_dirs: Directories to scan
+        interactive: Enable interactive mode
+        dry_run: Preview changes without modifying files
+        validate_links: Validate URLs before extraction
+        fail_on_broken: Exit if broken links found
+        macro_type: Type of macros to process - 'link', 'xref', or 'both' (default: 'both')
+
     Returns: True if successful, False otherwise
     """
     # Find or confirm attributes file
@@ -488,16 +511,17 @@ def extract_link_attributes(attributes_file: str = None,
     spinner.stop(f"Loaded {len(existing_attrs)} existing attributes")
 
     # Collect all macros
-    spinner = Spinner("Scanning for link and xref macros with attributes")
+    macro_desc = {'link': 'link', 'xref': 'xref', 'both': 'link and xref'}[macro_type]
+    spinner = Spinner(f"Scanning for {macro_desc} macros with attributes")
     spinner.start()
-    all_macros = collect_all_macros(scan_dirs)
+    all_macros = collect_all_macros(scan_dirs, macro_type)
     spinner.stop()
 
     if not all_macros:
-        print("No link or xref macros with attributes found.")
+        print(f"No {macro_desc} macros with attributes found.")
         return True
 
-    print(f"Found {len(all_macros)} link/xref macros with attributes")
+    print(f"Found {len(all_macros)} {macro_desc} macros with attributes")
 
     # Group by URL
     spinner = Spinner("Grouping macros by URL")
@@ -505,15 +529,15 @@ def extract_link_attributes(attributes_file: str = None,
     url_groups = group_macros_by_url(all_macros)
     spinner.stop(f"Grouped into {len(url_groups)} unique URLs")
 
-    # Create new attributes
-    new_attributes = create_attributes(url_groups, existing_attrs, interactive)
+    # Create new attributes and track existing ones
+    new_attributes, existing_matching_attributes = create_attributes(url_groups, existing_attrs, interactive)
 
-    if not new_attributes:
-        print("No new attributes to create.")
+    if not new_attributes and not existing_matching_attributes:
+        print("No new attributes to create and no existing attributes match found URLs.")
         return True
 
     # Validate new attributes before writing if requested
-    if validate_links and not dry_run:
+    if validate_links and not dry_run and new_attributes:
         print("\nValidating new link attributes...")
         spinner = Spinner("Validating new URLs")
         spinner.start()
@@ -543,10 +567,11 @@ def extract_link_attributes(attributes_file: str = None,
                 print("\nStopping due to broken URLs in new attributes (--fail-on-broken)")
                 return False
 
-    # Update attribute file
-    update_attribute_file(attributes_file, new_attributes, dry_run)
+    # Update attribute file (only if there are new attributes)
+    if new_attributes:
+        update_attribute_file(attributes_file, new_attributes, dry_run)
 
-    # Prepare file updates
+    # Prepare file updates (include both new and existing matching attributes)
     all_attributes = {**existing_attrs, **new_attributes}
     file_updates = prepare_file_updates(url_groups, all_attributes)
 
@@ -560,6 +585,14 @@ def extract_link_attributes(attributes_file: str = None,
     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")
+        total_processed = len(new_attributes) + len(existing_matching_attributes)
+        if new_attributes and existing_matching_attributes:
+            print(f"\nSuccessfully processed {total_processed} link attributes:")
+            print(f"  - Created {len(new_attributes)} new attributes")
+            print(f"  - Replaced macros using {len(existing_matching_attributes)} existing attributes")
+        elif new_attributes:
+            print(f"\nSuccessfully extracted {len(new_attributes)} link attributes")
+        elif existing_matching_attributes:
+            print(f"\nSuccessfully replaced macros using {len(existing_matching_attributes)} existing link attributes")
 
     return True

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/doc_utils/replace_link_attributes.py

@@ -65,8 +65,18 @@ def resolve_nested_attributes(attributes: Dict[str, str], max_iterations: int =
     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."""
+def replace_link_attributes_in_file(file_path: Path, attributes: Dict[str, str], dry_run: bool = False, macro_type: str = 'both') -> int:
+    """
+    Replace attribute references within link macros in a single file.
+
+    Args:
+        file_path: Path to the file to process
+        attributes: Dictionary of attribute definitions
+        dry_run: Preview changes without modifying files
+        macro_type: Type of macros to process - 'link', 'xref', or 'both' (default: 'both')
+
+    Returns: Number of replacements made
+    """
     with open(file_path, 'r', encoding='utf-8') as f:
         content = f.read()
 
@@ -75,14 +85,23 @@ def replace_link_attributes_in_file(file_path: Path, attributes: Dict[str, str],
 
     # Find all link macros containing attributes in the URL portion only
     # Match link: and xref: macros, capturing URL and text separately
-    link_patterns = [
+    link_patterns = []
+
+    if macro_type in ('link', 'both'):
         # link:url[text] - replace only in URL portion
-        (r'link:([^[\]]*)\[([^\]]*)\]', 'link'),
+        link_patterns.append((r'link:([^[\]]*)\[([^\]]*)\]', 'link'))
+
+    if macro_type in ('xref', 'both'):
         # 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')
-    ]
+        link_patterns.append((r'xref:([^[\]]*)\[([^\]]*)\]', 'xref'))
+
+    # Handle empty text cases based on macro type
+    if macro_type == 'both':
+        link_patterns.append((r'(link|xref):([^[\]]*)\[\]', 'empty_text'))
+    elif macro_type == 'link':
+        link_patterns.append((r'(link):([^[\]]*)\[\]', 'empty_text'))
+    elif macro_type == 'xref':
+        link_patterns.append((r'(xref):([^[\]]*)\[\]', 'empty_text'))
 
     for pattern, link_type in link_patterns:
         matches = list(re.finditer(pattern, content))

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/extract_link_attributes.py

@@ -77,6 +77,13 @@ Examples:
         help='Exit extraction if broken links are found in attributes (requires --validate-links)'
     )
 
+    parser.add_argument(
+        '--macro-type',
+        choices=['link', 'xref', 'both'],
+        default='both',
+        help='Type of macros to process: link, xref, or both (default: both)'
+    )
+
     args = parser.parse_args()
 
     try:
@@ -86,7 +93,8 @@ Examples:
             interactive=not args.non_interactive,
             dry_run=args.dry_run,
             validate_links=args.validate_links,
-            fail_on_broken=args.fail_on_broken
+            fail_on_broken=args.fail_on_broken,
+            macro_type=args.macro_type
         )
 
         if not success:

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.12"
+version = "0.1.14"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/replace_link_attributes.py

@@ -102,6 +102,12 @@ def main():
         type=str,
         help='Path to attributes.adoc file (skips interactive selection)'
     )
+    parser.add_argument(
+        '--macro-type',
+        choices=['link', 'xref', 'both'],
+        default='both',
+        help='Type of macros to process: link, xref, or both (default: both)'
+    )
 
     args = parser.parse_args()
 
@@ -165,7 +171,7 @@ def main():
     spinner.start()
 
     for file_path in adoc_files:
-        replacements = replace_link_attributes_in_file(file_path, attributes, args.dry_run)
+        replacements = replace_link_attributes_in_file(file_path, attributes, args.dry_run, args.macro_type)
         if replacements > 0:
             rel_path = file_path.relative_to(repo_root)
             total_replacements += replacements

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14/rolfedh_doc_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.12
+Version: 0.1.14
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ tests/test_fixture_archive_unused_files.py
 tests/test_fixture_archive_unused_images.py
 tests/test_fixture_check_scannability.py
 tests/test_parse_exclude_list.py
+tests/test_replace_link_attributes.py
 tests/test_symlink_handling.py
 tests/test_topic_map_parser.py
 tests/test_unused_attributes.py

{rolfedh_doc_utils-0.1.12 → rolfedh_doc_utils-0.1.14}/tests/test_extract_link_attributes.py

@@ -90,6 +90,36 @@ Regular link: link:https://example.com/guide.html[Guide]
         macros = find_link_macros(str(test_file))
         assert len(macros) == 0
 
+    def test_find_only_link_macros(self, tmp_path):
+        """Test finding only link macros when macro_type='link'."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+See link:https://example.com/{version}/guide.html[Guide].
+Also check xref:{base-url}/intro.html[Intro].
+""")
+
+        macros = find_link_macros(str(test_file), macro_type='link')
+
+        assert len(macros) == 1
+        assert macros[0][0] == "link:https://example.com/{version}/guide.html[Guide]"
+
+    def test_find_only_xref_macros(self, tmp_path):
+        """Test finding only xref macros when macro_type='xref'."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+See link:https://example.com/{version}/guide.html[Guide].
+Also check xref:{base-url}/intro.html[Intro].
+""")
+
+        macros = find_link_macros(str(test_file), macro_type='xref')
+
+        assert len(macros) == 1
+        assert macros[0][0] == "xref:{base-url}/intro.html[Intro]"
+
 
 class TestGenerateAttributeName:
     """Tests for generate_attribute_name function."""
@@ -217,9 +247,10 @@ class TestCreateAttributes:
         }
         existing_attrs = {}
 
-        new_attrs = create_attributes(url_groups, existing_attrs, interactive=False)
+        new_attrs, existing_matched = create_attributes(url_groups, existing_attrs, interactive=False)
 
         assert len(new_attrs) == 2
+        assert len(existing_matched) == 0
         # 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)
@@ -236,9 +267,11 @@ class TestCreateAttributes:
             "existing-link": "link:https://example.com/guide.html[Existing Guide]"
         }
 
-        new_attrs = create_attributes(url_groups, existing_attrs, interactive=False)
+        new_attrs, existing_matched = create_attributes(url_groups, existing_attrs, interactive=False)
 
         assert len(new_attrs) == 0
+        assert len(existing_matched) == 1
+        assert "existing-link" in existing_matched
         captured = capsys.readouterr()
         assert "already has attribute" in captured.out
 
@@ -314,7 +347,7 @@ And xref:{base-url}/intro.html[Introduction] for overview.
 
         # Check output
         captured = capsys.readouterr()
-        assert "Found 3 link/xref macros" in captured.out
+        assert "Found 3 link and xref macros" in captured.out
         assert "Grouped into 2 unique URLs" in captured.out
         assert "[DRY RUN]" in captured.out
 

rolfedh_doc_utils-0.1.14/tests/test_replace_link_attributes.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Tests for replace_link_attributes module."""
+
+import tempfile
+from pathlib import Path
+import pytest
+from doc_utils.replace_link_attributes import (
+    load_attributes,
+    resolve_nested_attributes,
+    replace_link_attributes_in_file,
+)
+
+
+class TestLoadAttributes:
+    """Tests for load_attributes function."""
+
+    def test_load_basic_attributes(self, tmp_path):
+        """Test loading basic attribute definitions."""
+        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
+""")
+
+        attrs = load_attributes(attr_file)
+
+        assert len(attrs) == 3
+        assert attrs["product-name"] == "My Product"
+        assert attrs["version"] == "1.0"
+        assert attrs["docs-url"] == "https://docs.example.com"
+
+
+class TestResolveNestedAttributes:
+    """Tests for resolve_nested_attributes function."""
+
+    def test_resolve_simple_nesting(self):
+        """Test resolving simple nested attributes."""
+        attributes = {
+            "base-url": "https://example.com",
+            "docs-url": "{base-url}/docs",
+            "guide-url": "{docs-url}/guide.html"
+        }
+
+        resolved = resolve_nested_attributes(attributes)
+
+        assert resolved["base-url"] == "https://example.com"
+        assert resolved["docs-url"] == "https://example.com/docs"
+        assert resolved["guide-url"] == "https://example.com/docs/guide.html"
+
+    def test_no_nesting(self):
+        """Test attributes without nesting."""
+        attributes = {
+            "url1": "https://example.com",
+            "url2": "https://another.com"
+        }
+
+        resolved = resolve_nested_attributes(attributes)
+
+        assert resolved == attributes
+
+
+class TestReplaceLinkAttributesInFile:
+    """Tests for replace_link_attributes_in_file function."""
+
+    def test_replace_in_link_macro(self, tmp_path):
+        """Test replacing attributes in link: macros."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+See link:{docs-url}/guide.html[User Guide] for details.
+""")
+
+        attributes = {"docs-url": "https://docs.example.com"}
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False)
+
+        assert count == 1
+        content = test_file.read_text()
+        assert "link:https://docs.example.com/guide.html[User Guide]" in content
+        assert "{docs-url}" not in content
+
+    def test_replace_in_xref_macro(self, tmp_path):
+        """Test replacing attributes in xref: macros."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+Check xref:{base-path}/intro.adoc[Introduction].
+""")
+
+        attributes = {"base-path": "modules"}
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False)
+
+        assert count == 1
+        content = test_file.read_text()
+        assert "xref:modules/intro.adoc[Introduction]" in content
+
+    def test_preserve_link_text(self, tmp_path):
+        """Test that link text is preserved unchanged."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test
+
+link:{url}/page.html[Custom Link Text]
+""")
+
+        attributes = {"url": "https://example.com"}
+
+        replace_link_attributes_in_file(test_file, attributes, dry_run=False)
+
+        content = test_file.read_text()
+        assert "[Custom Link Text]" in content
+
+    def test_dry_run_no_changes(self, tmp_path):
+        """Test that dry-run mode doesn't modify files."""
+        test_file = tmp_path / "test.adoc"
+        original_content = """
+link:{url}/page.html[Link]
+"""
+        test_file.write_text(original_content)
+
+        attributes = {"url": "https://example.com"}
+
+        replace_link_attributes_in_file(test_file, attributes, dry_run=True)
+
+        # File should be unchanged
+        assert test_file.read_text() == original_content
+
+    def test_macro_type_link_only(self, tmp_path):
+        """Test processing only link: macros."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+link:{docs-url}/guide.html[Guide]
+xref:{base-path}/intro.adoc[Intro]
+""")
+
+        attributes = {
+            "docs-url": "https://docs.example.com",
+            "base-path": "modules"
+        }
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False, macro_type='link')
+
+        assert count == 1
+        content = test_file.read_text()
+        assert "link:https://docs.example.com/guide.html[Guide]" in content
+        assert "xref:{base-path}/intro.adoc[Intro]" in content  # xref unchanged
+
+    def test_macro_type_xref_only(self, tmp_path):
+        """Test processing only xref: macros."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+link:{docs-url}/guide.html[Guide]
+xref:{base-path}/intro.adoc[Intro]
+""")
+
+        attributes = {
+            "docs-url": "https://docs.example.com",
+            "base-path": "modules"
+        }
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False, macro_type='xref')
+
+        assert count == 1
+        content = test_file.read_text()
+        assert "link:{docs-url}/guide.html[Guide]" in content  # link unchanged
+        assert "xref:modules/intro.adoc[Intro]" in content
+
+    def test_macro_type_both(self, tmp_path):
+        """Test processing both link: and xref: macros."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+= Test Document
+
+link:{docs-url}/guide.html[Guide]
+xref:{base-path}/intro.adoc[Intro]
+""")
+
+        attributes = {
+            "docs-url": "https://docs.example.com",
+            "base-path": "modules"
+        }
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False, macro_type='both')
+
+        assert count == 2
+        content = test_file.read_text()
+        assert "link:https://docs.example.com/guide.html[Guide]" in content
+        assert "xref:modules/intro.adoc[Intro]" in content
+
+    def test_multiple_attributes_in_url(self, tmp_path):
+        """Test replacing multiple attributes in a single URL."""
+        test_file = tmp_path / "test.adoc"
+        test_file.write_text("""
+link:{base-url}/{version}/guide.html[Guide]
+""")
+
+        attributes = {
+            "base-url": "https://example.com",
+            "version": "v2.0"
+        }
+
+        count = replace_link_attributes_in_file(test_file, attributes, dry_run=False)
+
+        assert count == 2
+        content = test_file.read_text()
+        assert "link:https://example.com/v2.0/guide.html[Guide]" in content