rolfedh-doc-utils 0.1.3__tar.gz → 0.1.5__tar.gz

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/PKG-INFO

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

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/archive_unused_files.py

@@ -1,7 +1,8 @@
 """
 Archive Unused AsciiDoc Files
 
-Scans './modules' and './assemblies' for AsciiDoc files not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them.
+Automatically discovers and scans 'modules' and 'assemblies' directories for AsciiDoc files 
+not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them.
 
 For full documentation and usage examples, see archive_unused_files.md in this directory.
 """
@@ -11,14 +12,19 @@ from doc_utils.unused_adoc import find_unused_adoc
 from doc_utils.file_utils import parse_exclude_list_file
 
 def main():
-    parser = argparse.ArgumentParser(description='Archive unused AsciiDoc files.')
+    parser = argparse.ArgumentParser(
+        description='Archive unused AsciiDoc files.',
+        epilog='By default, automatically discovers all modules and assemblies directories in the repository.'
+    )
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
+    parser.add_argument('--scan-dir', action='append', default=[], help='Specific directory to scan (can be used multiple times). If not specified, auto-discovers directories.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
     parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
     parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
     args = parser.parse_args()
 
-    scan_dirs = ['./modules', './modules/rn', './assemblies']
+    # Use provided scan directories or None for auto-discovery
+    scan_dirs = args.scan_dir if args.scan_dir else None
     archive_dir = './archive'
 
     exclude_dirs = list(args.exclude_dir)

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/doc_utils/topic_map_parser.py

@@ -22,8 +22,16 @@ def detect_repo_type(base_path='.'):
         if yml_files:
             return 'topic_map'
     
-    # Check for master.adoc files
-    master_files = glob.glob(os.path.join(base_path, '**/master.adoc'), recursive=True)
+    # Check for master.adoc files using os.walk to avoid symlink issues
+    master_files = []
+    for root, dirs, files in os.walk(base_path):
+        # Skip symbolic link directories to prevent infinite recursion
+        dirs[:] = [d for d in dirs if not os.path.islink(os.path.join(root, d))]
+        
+        # Check for master.adoc in this directory
+        if 'master.adoc' in files:
+            master_files.append(os.path.join(root, 'master.adoc'))
+            
     if master_files:
         return 'master_adoc'
     

rolfedh_doc_utils-0.1.5/doc_utils/unused_adoc.py

@@ -0,0 +1,120 @@
+# doc_utils/unused_adoc.py
+
+import os
+import re
+from .file_utils import collect_files, write_manifest_and_archive
+from .topic_map_parser import detect_repo_type, get_all_topic_map_references
+
+def find_scan_directories(base_path='.', exclude_dirs=None):
+    """
+    Automatically find all 'modules' and 'assemblies' directories in the repository.
+    
+    Returns a list of paths to scan.
+    """
+    scan_dirs = []
+    exclude_dirs = exclude_dirs or []
+    
+    for root, dirs, files in os.walk(base_path):
+        # Skip symbolic links to prevent issues
+        dirs[:] = [d for d in dirs if not os.path.islink(os.path.join(root, d))]
+        
+        # Skip excluded directories
+        for exclude_dir in exclude_dirs:
+            abs_exclude = os.path.abspath(exclude_dir)
+            if os.path.abspath(root).startswith(abs_exclude):
+                dirs[:] = []  # Don't descend into excluded directories
+                break
+        
+        # Skip hidden directories and common non-content directories
+        dirs[:] = [d for d in dirs if not d.startswith('.') and d not in ['node_modules', 'build', 'dist', 'target']]
+        
+        # Look for modules and assemblies directories
+        for d in dirs:
+            if d in ['modules', 'assemblies']:
+                dir_path = os.path.join(root, d)
+                # Check if this directory or any subdirectory contains .adoc files
+                has_adoc = False
+                for subroot, subdirs, subfiles in os.walk(dir_path):
+                    # Skip symbolic links
+                    subdirs[:] = [sd for sd in subdirs if not os.path.islink(os.path.join(subroot, sd))]
+                    if any(f.endswith('.adoc') for f in subfiles):
+                        has_adoc = True
+                        break
+                if has_adoc:
+                    scan_dirs.append(dir_path)
+    
+    # Also check for modules/rn pattern if modules exists
+    modules_dirs = [d for d in scan_dirs if os.path.basename(d) == 'modules']
+    for modules_dir in modules_dirs:
+        rn_dir = os.path.join(modules_dir, 'rn')
+        if os.path.isdir(rn_dir):
+            # Check if rn directory or subdirectories contain .adoc files
+            has_adoc = False
+            for subroot, subdirs, subfiles in os.walk(rn_dir):
+                subdirs[:] = [sd for sd in subdirs if not os.path.islink(os.path.join(subroot, sd))]
+                if any(f.endswith('.adoc') for f in subfiles):
+                    has_adoc = True
+                    break
+            if has_adoc:
+                scan_dirs.append(rn_dir)
+    
+    return scan_dirs
+
+def find_unused_adoc(scan_dirs=None, archive_dir='./archive', archive=False, exclude_dirs=None, exclude_files=None):
+    # Print safety warning
+    print("\n⚠️  SAFETY: Work in a git branch! Run without --archive first to preview.\n")
+    
+    # If no scan_dirs provided, auto-discover them
+    if not scan_dirs:
+        scan_dirs = find_scan_directories(exclude_dirs=exclude_dirs)
+        if scan_dirs:
+            print(f"Auto-discovered directories to scan:")
+            for dir_path in sorted(scan_dirs):
+                print(f"  - {dir_path}")
+        else:
+            print("No 'modules' or 'assemblies' directories found containing .adoc files.")
+            print("Please run this tool from your documentation repository root.")
+            return
+    
+    # Detect repository type
+    repo_type = detect_repo_type()
+    print(f"Detected repository type: {repo_type}")
+    
+    # Collect all .adoc files in scan directories
+    asciidoc_files = collect_files(scan_dirs, {'.adoc'}, exclude_dirs, exclude_files)
+    
+    # Track which files are referenced
+    referenced_files = set()
+    
+    if repo_type == 'topic_map':
+        # For OpenShift-docs style repos, get references from topic maps
+        topic_references = get_all_topic_map_references()
+        # Convert to basenames for comparison
+        referenced_files.update(os.path.basename(ref) for ref in topic_references)
+    
+    # Always scan for include:: directives in all .adoc files
+    include_pattern = re.compile(r'include::(.+?)\[')
+    adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
+    
+    for file_path in adoc_files:
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+                includes = include_pattern.findall(content)
+                # Extract just the filename from the include path
+                for include in includes:
+                    # Handle both relative and absolute includes
+                    include_basename = os.path.basename(include)
+                    referenced_files.add(include_basename)
+        except Exception as e:
+            print(f"Warning: could not read {file_path}: {e}")
+    
+    # Find unused files by comparing basenames
+    unused_files = [f for f in asciidoc_files if os.path.basename(f) not in referenced_files]
+    unused_files = list(dict.fromkeys(unused_files))  # Remove duplicates
+    
+    print(f"Found {len(unused_files)} unused files out of {len(asciidoc_files)} total files in scan directories")
+    
+    return write_manifest_and_archive(
+        unused_files, archive_dir, 'to-archive', 'to-archive', archive=archive
+    )

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/doc_utils/unused_images.py

@@ -7,6 +7,9 @@ from .file_utils import collect_files, write_manifest_and_archive
 IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.svg'}
 
 def find_unused_images(scan_dirs, archive_dir, archive=False, exclude_dirs=None, exclude_files=None):
+    # Print safety warning
+    print("\n⚠️  SAFETY: Work in a git branch! Run without --archive first to preview.\n")
+    
     image_files = collect_files(scan_dirs, IMAGE_EXTENSIONS, exclude_dirs, exclude_files)
     adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
     referenced_images = set()

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/pyproject.toml

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

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/rolfedh_doc_utils.egg-info/PKG-INFO

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

{rolfedh_doc_utils-0.1.3 → rolfedh_doc_utils-0.1.5}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ archive_unused_images.py
 check_scannability.py
 find_unused_attributes.py
 pyproject.toml
+setup.py
 doc_utils/__init__.py
 doc_utils/file_utils.py
 doc_utils/scannability.py
@@ -20,6 +21,7 @@ rolfedh_doc_utils.egg-info/requires.txt
 rolfedh_doc_utils.egg-info/top_level.txt
 tests/test_archive_unused_files.py
 tests/test_archive_unused_images.py
+tests/test_auto_discovery.py
 tests/test_check_scannability.py
 tests/test_cli_entry_points.py
 tests/test_file_utils.py
@@ -27,5 +29,6 @@ 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_symlink_handling.py
 tests/test_topic_map_parser.py
 tests/test_unused_attributes.py

rolfedh_doc_utils-0.1.5/setup.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+Setup script for doc-utils package.
+This file is only needed if we want to customize the installation process.
+"""
+
+from setuptools import setup
+from setuptools.command.install import install
+from setuptools.command.develop import develop
+from setuptools.command.egg_info import egg_info
+
+def custom_post_install():
+    """Display safety message after installation."""
+    print("\n" + "="*60)
+    print("✅ doc-utils installed successfully!")
+    print("\n⚠️  IMPORTANT: Safety First")
+    print("   • Work in a git branch (never main/master)")
+    print("   • Run without --archive first to preview") 
+    print("   • Review changes with git diff")
+    print("="*60 + "\n")
+
+class CustomInstallCommand(install):
+    """Customized setuptools install command."""
+    def run(self):
+        install.run(self)
+        custom_post_install()
+
+class CustomDevelopCommand(develop):
+    """Customized setuptools develop command."""
+    def run(self):
+        develop.run(self)
+        custom_post_install()
+
+class CustomEggInfoCommand(egg_info):
+    """Customized setuptools egg_info command."""
+    def run(self):
+        egg_info.run(self)
+
+setup(
+    cmdclass={
+        'install': CustomInstallCommand,
+        'develop': CustomDevelopCommand,
+        'egg_info': CustomEggInfoCommand,
+    },
+)

rolfedh_doc_utils-0.1.5/tests/test_auto_discovery.py

@@ -0,0 +1,146 @@
+"""Test automatic directory discovery for archive-unused-files."""
+
+import os
+import tempfile
+import pytest
+from doc_utils.unused_adoc import find_scan_directories
+
+
+def test_find_scan_directories_standard_structure(tmp_path):
+    """Test discovery with standard directory structure."""
+    
+    # Create standard structure
+    (tmp_path / "modules").mkdir()
+    (tmp_path / "modules" / "test.adoc").write_text("= Test\n")
+    
+    (tmp_path / "assemblies").mkdir()
+    (tmp_path / "assemblies" / "assembly.adoc").write_text("= Assembly\n")
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should find both directories
+    assert len(dirs) == 2
+    assert any("modules" in d for d in dirs)
+    assert any("assemblies" in d for d in dirs)
+
+
+def test_find_scan_directories_nested_structure(tmp_path):
+    """Test discovery with nested directory structure."""
+    
+    # Create nested structure like red-hat-insights-documentation
+    downstream = tmp_path / "downstream"
+    downstream.mkdir()
+    
+    (downstream / "modules").mkdir()
+    (downstream / "modules" / "test.adoc").write_text("= Test\n")
+    
+    (downstream / "assemblies").mkdir()
+    (downstream / "assemblies" / "assembly.adoc").write_text("= Assembly\n")
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should find both nested directories
+    assert len(dirs) == 2
+    assert any("downstream/modules" in d or "downstream\\modules" in d for d in dirs)
+    assert any("downstream/assemblies" in d or "downstream\\assemblies" in d for d in dirs)
+
+
+def test_find_scan_directories_with_rn(tmp_path):
+    """Test discovery includes modules/rn directory when it contains .adoc files."""
+    
+    # Create modules with rn subdirectory
+    modules = tmp_path / "modules"
+    modules.mkdir()
+    (modules / "test.adoc").write_text("= Test\n")
+    
+    rn_dir = modules / "rn"
+    rn_dir.mkdir()
+    (rn_dir / "release-notes.adoc").write_text("= Release Notes\n")
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should find modules and modules/rn
+    assert len(dirs) == 2
+    assert any("modules/rn" in d or "modules\\rn" in d for d in dirs)
+
+
+def test_find_scan_directories_empty_dirs(tmp_path):
+    """Test that empty directories without .adoc files are not included."""
+    
+    # Create directories without .adoc files
+    (tmp_path / "modules").mkdir()
+    (tmp_path / "assemblies").mkdir()
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should find no directories since they don't contain .adoc files
+    assert len(dirs) == 0
+
+
+def test_find_scan_directories_with_exclusions(tmp_path):
+    """Test directory discovery with exclusions."""
+    
+    # Create multiple module directories
+    (tmp_path / "modules").mkdir()
+    (tmp_path / "modules" / "test.adoc").write_text("= Test\n")
+    
+    archived = tmp_path / "archived"
+    archived.mkdir()
+    (archived / "modules").mkdir()
+    (archived / "modules" / "old.adoc").write_text("= Old\n")
+    
+    # Find directories excluding archived
+    dirs = find_scan_directories(str(tmp_path), exclude_dirs=[str(archived)])
+    
+    # Should only find the non-excluded modules
+    assert len(dirs) == 1
+    assert "archived" not in dirs[0]
+
+
+def test_find_scan_directories_skips_hidden(tmp_path):
+    """Test that hidden directories are skipped."""
+    
+    # Create visible modules
+    (tmp_path / "modules").mkdir()
+    (tmp_path / "modules" / "test.adoc").write_text("= Test\n")
+    
+    # Create hidden directory
+    hidden = tmp_path / ".archive"
+    hidden.mkdir()
+    (hidden / "modules").mkdir()
+    (hidden / "modules" / "archived.adoc").write_text("= Archived\n")
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should only find visible modules
+    assert len(dirs) == 1
+    assert ".archive" not in dirs[0]
+
+
+def test_find_scan_directories_multiple_locations(tmp_path):
+    """Test discovery with modules/assemblies in multiple locations."""
+    
+    # Create modules in multiple places
+    (tmp_path / "modules").mkdir()
+    (tmp_path / "modules" / "root.adoc").write_text("= Root\n")
+    
+    content1 = tmp_path / "content1"
+    content1.mkdir()
+    (content1 / "modules").mkdir()
+    (content1 / "modules" / "content1.adoc").write_text("= Content1\n")
+    
+    content2 = tmp_path / "content2" 
+    content2.mkdir()
+    (content2 / "assemblies").mkdir()
+    (content2 / "assemblies" / "assembly2.adoc").write_text("= Assembly2\n")
+    
+    # Find directories
+    dirs = find_scan_directories(str(tmp_path))
+    
+    # Should find all three directories
+    assert len(dirs) == 3

rolfedh_doc_utils-0.1.5/tests/test_symlink_handling.py

@@ -0,0 +1,91 @@
+"""Test that topic_map_parser handles symbolic links correctly without freezing."""
+
+import os
+import tempfile
+import pytest
+from doc_utils.topic_map_parser import detect_repo_type
+
+
+def test_detect_repo_type_with_circular_symlinks(tmp_path):
+    """Test that detect_repo_type doesn't freeze with circular symbolic links."""
+    
+    # Create a directory structure with circular symlinks
+    modules_dir = tmp_path / "modules"
+    modules_dir.mkdir()
+    
+    # Create a master.adoc file in modules
+    (modules_dir / "master.adoc").write_text("= Test Doc\n")
+    
+    # Create a circular symlink: modules/modules -> ../modules
+    circular_link = modules_dir / "modules"
+    try:
+        os.symlink("../../modules", str(circular_link))
+    except OSError:
+        pytest.skip("Cannot create symbolic links on this system")
+    
+    # This should not freeze - it should skip the symlink
+    repo_type = detect_repo_type(str(tmp_path))
+    assert repo_type == "master_adoc"
+
+
+def test_detect_repo_type_with_nested_circular_symlinks(tmp_path):
+    """Test detection with nested directories containing circular symlinks."""
+    
+    # Create nested structure
+    (tmp_path / "assemblies").mkdir()
+    modules_dir = tmp_path / "modules"
+    modules_dir.mkdir()
+    
+    # Create master.adoc
+    (tmp_path / "master.adoc").write_text("= Main Doc\n")
+    
+    # Create archive directory with circular symlinks (similar to real case)
+    archive_dir = tmp_path / ".archive" / "archived-content" / "modules"
+    archive_dir.mkdir(parents=True)
+    
+    try:
+        # Create circular symlink in archive
+        os.symlink("../../modules", str(archive_dir / "modules"))
+    except OSError:
+        pytest.skip("Cannot create symbolic links on this system")
+    
+    # Should detect master_adoc without freezing
+    repo_type = detect_repo_type(str(tmp_path))
+    assert repo_type == "master_adoc"
+
+
+def test_detect_repo_type_skips_symlink_directories(tmp_path):
+    """Test that symlinked directories are skipped during traversal."""
+    
+    # Create main directories
+    real_dir = tmp_path / "real_modules"
+    real_dir.mkdir()
+    (real_dir / "master.adoc").write_text("= Real Master\n")
+    
+    # Create a symlink to real_dir
+    linked_dir = tmp_path / "linked_modules"
+    try:
+        os.symlink(str(real_dir), str(linked_dir))
+    except OSError:
+        pytest.skip("Cannot create symbolic links on this system")
+    
+    # The function should find the master.adoc in real_dir but not traverse linked_dir
+    repo_type = detect_repo_type(str(tmp_path))
+    assert repo_type == "master_adoc"
+    
+    # Test that symlinked directories are not traversed
+    only_symlink_path = tmp_path / "only_symlink_test"
+    only_symlink_path.mkdir()
+    
+    # Create a directory outside that contains master.adoc
+    external_dir = tmp_path / "external"
+    external_dir.mkdir()
+    (external_dir / "master.adoc").write_text("= External Master\n")
+    
+    # Create only a symlink to it inside our test directory
+    symlinked_dir = only_symlink_path / "linked_dir"
+    os.symlink(str(external_dir), str(symlinked_dir))
+    
+    # Should not find master.adoc since it's only accessible via symlink
+    repo_type = detect_repo_type(str(only_symlink_path))
+    assert repo_type == "unknown"

rolfedh_doc_utils-0.1.3/doc_utils/unused_adoc.py

@@ -1,50 +0,0 @@
-# doc_utils/unused_adoc.py
-
-import os
-import re
-from .file_utils import collect_files, write_manifest_and_archive
-from .topic_map_parser import detect_repo_type, get_all_topic_map_references
-
-def find_unused_adoc(scan_dirs, archive_dir, archive=False, exclude_dirs=None, exclude_files=None):
-    # Detect repository type
-    repo_type = detect_repo_type()
-    print(f"Detected repository type: {repo_type}")
-    
-    # Collect all .adoc files in scan directories
-    asciidoc_files = collect_files(scan_dirs, {'.adoc'}, exclude_dirs, exclude_files)
-    
-    # Track which files are referenced
-    referenced_files = set()
-    
-    if repo_type == 'topic_map':
-        # For OpenShift-docs style repos, get references from topic maps
-        topic_references = get_all_topic_map_references()
-        # Convert to basenames for comparison
-        referenced_files.update(os.path.basename(ref) for ref in topic_references)
-    
-    # Always scan for include:: directives in all .adoc files
-    include_pattern = re.compile(r'include::(.+?)\[')
-    adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
-    
-    for file_path in adoc_files:
-        try:
-            with open(file_path, 'r', encoding='utf-8') as f:
-                content = f.read()
-                includes = include_pattern.findall(content)
-                # Extract just the filename from the include path
-                for include in includes:
-                    # Handle both relative and absolute includes
-                    include_basename = os.path.basename(include)
-                    referenced_files.add(include_basename)
-        except Exception as e:
-            print(f"Warning: could not read {file_path}: {e}")
-    
-    # Find unused files by comparing basenames
-    unused_files = [f for f in asciidoc_files if os.path.basename(f) not in referenced_files]
-    unused_files = list(dict.fromkeys(unused_files))  # Remove duplicates
-    
-    print(f"Found {len(unused_files)} unused files out of {len(asciidoc_files)} total files in scan directories")
-    
-    return write_manifest_and_archive(
-        unused_files, archive_dir, 'to-archive', 'to-archive', archive=archive
-    )