rolfedh-doc-utils 0.1.4__py3-none-any.whl → 0.1.41__py3-none-any.whl

doc_utils/version_check.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Version checking utility for doc-utils.
+
+Checks PyPI for the latest version and notifies users if an update is available.
+Includes caching to avoid excessive PyPI requests.
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from importlib.metadata import version as get_installed_version
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def get_cache_dir() -> Path:
+    """Get the cache directory for version check data."""
+    # Use XDG_CACHE_HOME if set, otherwise ~/.cache
+    cache_home = os.environ.get('XDG_CACHE_HOME')
+    if cache_home:
+        cache_dir = Path(cache_home) / 'doc-utils'
+    else:
+        cache_dir = Path.home() / '.cache' / 'doc-utils'
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_cache_file() -> Path:
+    """Get the cache file path."""
+    return get_cache_dir() / 'version_check.json'
+
+
+def read_cache() -> Optional[dict]:
+    """Read version check cache."""
+    cache_file = get_cache_file()
+    if not cache_file.exists():
+        return None
+
+    try:
+        with open(cache_file, 'r') as f:
+            data = json.load(f)
+            # Check if cache is still valid (24 hours)
+            last_check = datetime.fromisoformat(data['last_check'])
+            if datetime.now() - last_check < timedelta(hours=24):
+                return data
+    except (json.JSONDecodeError, KeyError, ValueError):
+        pass
+
+    return None
+
+
+def write_cache(latest_version: str, current_version: str):
+    """Write version check cache."""
+    cache_file = get_cache_file()
+    data = {
+        'last_check': datetime.now().isoformat(),
+        'latest_version': latest_version,
+        'current_version': current_version,
+    }
+
+    try:
+        with open(cache_file, 'w') as f:
+            json.dump(data, f)
+    except Exception:
+        # Silently fail if we can't write cache
+        pass
+
+
+def fetch_latest_version() -> Optional[str]:
+    """Fetch the latest version from PyPI."""
+    try:
+        # Use PyPI JSON API
+        url = 'https://pypi.org/pypi/rolfedh-doc-utils/json'
+        with urllib.request.urlopen(url, timeout=2) as response:
+            data = json.loads(response.read())
+            return data['info']['version']
+    except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
+        # Silently fail if we can't reach PyPI
+        return None
+
+
+def parse_version(version_str: str) -> Tuple[int, ...]:
+    """Parse version string into tuple of integers for comparison."""
+    try:
+        # Remove any pre-release or dev suffixes
+        version_str = version_str.split('+')[0].split('-')[0]
+        return tuple(int(x) for x in version_str.split('.'))
+    except (ValueError, AttributeError):
+        return (0,)
+
+
+def check_for_update(force_check: bool = False) -> Optional[str]:
+    """
+    Check if a newer version is available.
+
+    Args:
+        force_check: If True, bypass cache and always check PyPI
+
+    Returns:
+        The latest version string if an update is available, None otherwise
+    """
+    try:
+        current_version = get_installed_version('rolfedh-doc-utils')
+    except Exception:
+        # Can't determine installed version
+        return None
+
+    # Check cache first (unless forced)
+    if not force_check:
+        cache_data = read_cache()
+        if cache_data:
+            latest_version = cache_data['latest_version']
+            # Only notify if there's a newer version
+            if parse_version(latest_version) > parse_version(current_version):
+                return latest_version
+            return None
+
+    # Fetch from PyPI
+    latest_version = fetch_latest_version()
+    if not latest_version:
+        return None
+
+    # Cache the result
+    write_cache(latest_version, current_version)
+
+    # Check if update is available
+    if parse_version(latest_version) > parse_version(current_version):
+        return latest_version
+
+    return None
+
+
+def detect_install_method() -> str:
+    """
+    Detect how the package was installed.
+
+    Returns:
+        'pipx' or 'pip'
+
+    Note: Defaults to 'pipx' as the recommended installation method.
+    """
+    # Check if running from pipx venv (standard pipx install)
+    if 'pipx' in sys.prefix.lower():
+        return 'pipx'
+
+    # Check PIPX_HOME environment variable
+    pipx_home = os.environ.get('PIPX_HOME') or os.path.join(Path.home(), '.local', 'pipx')
+    if pipx_home and str(Path(sys.prefix)).startswith(str(Path(pipx_home))):
+        return 'pipx'
+
+    # Check if executable is in typical pipx bin location
+    try:
+        exe_path = Path(sys.executable)
+        if '.local/pipx' in str(exe_path):
+            return 'pipx'
+    except Exception:
+        pass
+
+    # Default to pipx as the recommended method (per CLAUDE.md guidelines)
+    # This ensures users see the recommended upgrade command even for editable installs
+    return 'pipx'
+
+
+def show_update_notification(latest_version: str, current_version: str = None):
+    """Show update notification to user."""
+    if not current_version:
+        try:
+            current_version = get_installed_version('rolfedh-doc-utils')
+        except Exception:
+            current_version = 'unknown'
+
+    # Detect installation method and recommend appropriate upgrade command
+    install_method = detect_install_method()
+
+    # Use stderr to avoid interfering with tool output
+    print(f"\n📦 Update available: {current_version} → {latest_version}", file=sys.stderr)
+
+    if install_method == 'pipx':
+        print(f"   Run: pipx upgrade rolfedh-doc-utils", file=sys.stderr)
+    else:
+        print(f"   Run: pip install --upgrade rolfedh-doc-utils", file=sys.stderr)
+
+    print("", file=sys.stderr)
+
+
+def check_version_on_startup():
+    """
+    Check for updates on tool startup.
+
+    This should be called early in the main() function of each CLI tool.
+    It runs asynchronously and won't block the tool execution.
+    """
+    # Skip version check in certain conditions
+    if any([
+        os.environ.get('DOC_UTILS_NO_VERSION_CHECK'),  # User opt-out
+        os.environ.get('CI'),  # Running in CI
+        not sys.stderr.isatty(),  # Not running in terminal
+    ]):
+        return
+
+    try:
+        latest_version = check_for_update()
+        if latest_version:
+            show_update_notification(latest_version)
+    except Exception:
+        # Never let version checking break the tool
+        pass
+
+
+def disable_version_check():
+    """
+    Instructions for disabling version check.
+
+    Users can disable by setting DOC_UTILS_NO_VERSION_CHECK environment variable.
+    """
+    print("To disable version checking, set the environment variable:")
+    print("  export DOC_UTILS_NO_VERSION_CHECK=1")
+    print("\nOr add it to your shell configuration file.")
+
+
+if __name__ == "__main__":
+    # For testing/debugging
+    import argparse
+    parser = argparse.ArgumentParser(description="Check for doc-utils updates")
+    parser.add_argument('--force', action='store_true', help='Force check (bypass cache)')
+    parser.add_argument('--disable-instructions', action='store_true',
+                       help='Show instructions for disabling version check')
+    args = parser.parse_args()
+
+    if args.disable_instructions:
+        disable_version_check()
+    else:
+        latest = check_for_update(force_check=args.force)
+        if latest:
+            show_update_notification(latest)
+        else:
+            print("You are running the latest version!")

doc_utils/warnings_report.py

@@ -0,0 +1,237 @@
+"""
+Generate AsciiDoc warnings report for callout conversion issues.
+"""
+
+from datetime import datetime
+from typing import List, Dict, Set
+from pathlib import Path
+
+
+class WarningInfo:
+    """Information about a specific warning."""
+
+    def __init__(self, warning_type: str, file_name: str, line_info: str,
+                 code_nums: List[int] = None, explanation_nums: List[int] = None):
+        self.warning_type = warning_type  # 'mismatch' or 'missing'
+        self.file_name = file_name
+        self.line_info = line_info  # e.g., "211" or "55-72"
+        self.code_nums = code_nums or []
+        self.explanation_nums = explanation_nums or []
+
+
+def parse_warning_message(warning_msg: str) -> WarningInfo:
+    """
+    Parse a warning message to extract structured information.
+
+    Examples:
+    - "WARNING: file.adoc lines 55-72: Callout mismatch: code has [1, 2], explanations have [1, 3]"
+    - "WARNING: file.adoc line 211: Code block has callouts [1, 2, 3, 4] but no explanations found..."
+    """
+    import re
+
+    # Extract file name and line info
+    match = re.match(r'WARNING: (.+?) lines? ([\d-]+):', warning_msg)
+    if not match:
+        return None
+
+    file_name = match.group(1)
+    line_info = match.group(2)
+
+    # Determine warning type and extract callout numbers
+    if 'Callout mismatch' in warning_msg:
+        # Parse: "code has [1, 2], explanations have [1, 3]"
+        code_match = re.search(r'code has \[([^\]]+)\]', warning_msg)
+        exp_match = re.search(r'explanations have \[([^\]]+)\]', warning_msg)
+
+        code_nums = []
+        exp_nums = []
+
+        if code_match:
+            code_nums = [int(n.strip()) for n in code_match.group(1).split(',')]
+        if exp_match:
+            exp_nums = [int(n.strip()) for n in exp_match.group(1).split(',')]
+
+        return WarningInfo('mismatch', file_name, line_info, code_nums, exp_nums)
+
+    elif 'but no explanations found' in warning_msg:
+        # Parse: "Code block has callouts [1, 2, 3, 4] but no explanations found"
+        callouts_match = re.search(r'has callouts \[([^\]]+)\]', warning_msg)
+
+        code_nums = []
+        if callouts_match:
+            code_nums = [int(n.strip()) for n in callouts_match.group(1).split(',')]
+
+        return WarningInfo('missing', file_name, line_info, code_nums, [])
+
+    return None
+
+
+def analyze_mismatch(code_nums: List[int], exp_nums: List[int]) -> List[str]:
+    """
+    Analyze what's wrong with a callout mismatch.
+
+    Returns a list of issue descriptions.
+    """
+    issues = []
+    code_set = set(code_nums)
+    exp_set = set(exp_nums)
+
+    # Check for duplicates in explanations
+    exp_counts = {}
+    for num in exp_nums:
+        exp_counts[num] = exp_counts.get(num, 0) + 1
+
+    duplicates = [num for num, count in exp_counts.items() if count > 1]
+    if duplicates:
+        for dup in duplicates:
+            count = exp_counts[dup]
+            issues.append(f"Duplicate callout: {dup} (appears {count} times in explanations)")
+
+    # Check for missing callouts (in code but not in explanations)
+    missing_in_exp = code_set - exp_set
+    if missing_in_exp:
+        for num in sorted(missing_in_exp):
+            issues.append(f"Missing callout: {num} (in code but not in explanations)")
+
+    # Check for extra callouts (in explanations but not in code)
+    extra_in_exp = exp_set - code_set
+    if extra_in_exp:
+        for num in sorted(extra_in_exp):
+            issues.append(f"Extra callout: {num} (in explanations but not in code)")
+
+    # Check for off-by-one errors
+    if code_nums and exp_nums:
+        code_start = min(code_nums)
+        exp_start = min(exp_nums)
+        if code_start != exp_start and not (missing_in_exp or extra_in_exp or duplicates):
+            issues.append(f"Off-by-one error (code starts at {code_start}, explanations start at {exp_start})")
+
+    return issues
+
+
+def generate_warnings_report(warnings: List[str], output_path: Path = None) -> str:
+    """
+    Generate an AsciiDoc warnings report from warning messages.
+
+    Args:
+        warnings: List of warning message strings
+        output_path: Path to write report file (if None, returns content only)
+
+    Returns:
+        The report content as a string
+    """
+    if not warnings:
+        return ""
+
+    # Parse all warnings
+    parsed_warnings = []
+    for warning in warnings:
+        parsed = parse_warning_message(warning)
+        if parsed:
+            parsed_warnings.append(parsed)
+
+    if not parsed_warnings:
+        return ""
+
+    # Group warnings by type
+    mismatch_warnings = [w for w in parsed_warnings if w.warning_type == 'mismatch']
+    missing_warnings = [w for w in parsed_warnings if w.warning_type == 'missing']
+
+    # Generate report content
+    lines = []
+    lines.append("= Callout Conversion Warnings Report")
+    lines.append(":toc:")
+    lines.append("")
+    lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    lines.append("")
+
+    # Summary
+    lines.append("== Summary")
+    lines.append("")
+    lines.append(f"Total warnings: {len(parsed_warnings)}")
+    if mismatch_warnings:
+        lines.append(f"- Callout mismatches: {len(mismatch_warnings)}")
+    if missing_warnings:
+        lines.append(f"- Missing explanations: {len(missing_warnings)}")
+    lines.append("")
+    lines.append("== Recommended Actions")
+    lines.append("")
+    lines.append("1. Review each warning below and fix callout issues where appropriate")
+    lines.append("2. For callout mismatches: Ensure code callouts match explanation numbers")
+    lines.append("3. For missing explanations: Check if explanations are shared with another block or missing")
+    lines.append("4. After fixing issues, rerun the conversion command")
+    lines.append("")
+    lines.append("== Force Mode Option")
+    lines.append("")
+    lines.append("CAUTION: Use this option sparingly and only after reviewing all warnings.")
+    lines.append("")
+    lines.append("If you've reviewed all warnings and confirmed that remaining issues are acceptable,")
+    lines.append("you can use the `--force` option to strip callouts from code blocks despite warnings:")
+    lines.append("")
+    lines.append("[source,bash]")
+    lines.append("----")
+    lines.append("convert-callouts-to-deflist --force modules/")
+    lines.append("----")
+    lines.append("")
+    lines.append("Force mode will:")
+    lines.append("")
+    lines.append("- Strip callouts from blocks with missing explanations (without creating explanation lists)")
+    lines.append("- Convert blocks with callout mismatches using available explanations")
+    lines.append("- Require confirmation before proceeding (unless in dry-run mode)")
+    lines.append("")
+    lines.append("IMPORTANT: Always work in a git branch and review changes with `git diff` before committing.")
+    lines.append("")
+
+    # Callout Mismatch section
+    if mismatch_warnings:
+        lines.append("== Callout Mismatch Warnings")
+        lines.append("")
+        lines.append("Callout numbers in code don't match explanation numbers.")
+        lines.append("")
+
+        for warning in mismatch_warnings:
+            lines.append(f"=== {warning.file_name}")
+            lines.append("")
+            lines.append(f"*Lines {warning.line_info}*")
+            lines.append("")
+            lines.append(f"Code has:: {warning.code_nums}")
+            lines.append(f"Explanations have:: {warning.explanation_nums}")
+            lines.append("")
+
+            issues = analyze_mismatch(warning.code_nums, warning.explanation_nums)
+            if issues:
+                lines.append("Issues detected::")
+                for issue in issues:
+                    lines.append(f"- {issue}")
+                lines.append("")
+
+    # Missing Explanations section
+    if missing_warnings:
+        lines.append("== Missing Explanations Warnings")
+        lines.append("")
+        lines.append("Code blocks with callouts but no explanations found after them.")
+        lines.append("")
+
+        for warning in missing_warnings:
+            lines.append(f"=== {warning.file_name}")
+            lines.append("")
+            lines.append(f"*Line {warning.line_info}*")
+            lines.append("")
+            lines.append(f"Callouts in code:: {warning.code_nums}")
+            lines.append("")
+            lines.append("Possible causes::")
+            lines.append("- Explanations shared with another code block (e.g., in conditional sections)")
+            lines.append("- Explanations in unexpected location")
+            lines.append("- Documentation error (missing explanations)")
+            lines.append("")
+            lines.append("Action:: Review this block manually")
+            lines.append("")
+
+    content = '\n'.join(lines)
+
+    # Write to file if path provided
+    if output_path:
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+    return content

doc_utils_cli.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+doc-utils - CLI tools for AsciiDoc documentation projects
+
+Main entry point that provides a hub for all doc-utils tools.
+"""
+
+import argparse
+import sys
+from doc_utils.version import __version__
+from doc_utils.version_check import check_version_on_startup
+
+
+# Tool definitions with descriptions
+TOOLS = [
+    {
+        'name': 'validate-links',
+        'description': 'Validates all links in documentation with URL transposition',
+        'example': 'validate-links --transpose "https://prod--https://preview"'
+    },
+    {
+        'name': 'extract-link-attributes',
+        'description': 'Extracts link/xref macros with attributes into reusable definitions',
+        'example': 'extract-link-attributes --dry-run'
+    },
+    {
+        'name': 'replace-link-attributes',
+        'description': 'Resolves Vale LinkAttribute issues by replacing attributes in link URLs',
+        'example': 'replace-link-attributes --dry-run'
+    },
+    {
+        'name': 'format-asciidoc-spacing',
+        'description': 'Standardizes spacing after headings and around includes',
+        'example': 'format-asciidoc-spacing --dry-run modules/'
+    },
+    {
+        'name': 'check-scannability',
+        'description': 'Analyzes document readability by checking sentence/paragraph length',
+        'example': 'check-scannability --max-sentence-length 5'
+    },
+    {
+        'name': 'archive-unused-files',
+        'description': 'Finds and optionally archives unreferenced AsciiDoc files',
+        'example': 'archive-unused-files  # preview\narchive-unused-files --archive  # execute'
+    },
+    {
+        'name': 'archive-unused-images',
+        'description': 'Finds and optionally archives unreferenced image files',
+        'example': 'archive-unused-images  # preview\narchive-unused-images --archive  # execute'
+    },
+    {
+        'name': 'find-unused-attributes',
+        'description': 'Identifies unused attribute definitions in AsciiDoc files',
+        'example': 'find-unused-attributes  # auto-discovers attributes files'
+    },
+    {
+        'name': 'convert-callouts-to-deflist',
+        'description': 'Converts callouts to definition lists (batch mode)',
+        'example': 'convert-callouts-to-deflist --dry-run modules/'
+    },
+    {
+        'name': 'convert-callouts-interactive',
+        'description': 'Interactively converts callouts with per-block format selection',
+        'example': 'convert-callouts-interactive modules/'
+    },
+]
+
+
+def print_tools_list():
+    """Print a formatted list of all available tools."""
+    print("\n🛠️  Available Tools:\n")
+
+    for tool in TOOLS:
+        # Print tool name and description
+        experimental = " [EXPERIMENTAL]" if "[EXPERIMENTAL]" in tool['description'] else ""
+        desc = tool['description'].replace(" [EXPERIMENTAL]", "")
+        print(f"  {tool['name']}{experimental}")
+        print(f"    {desc}")
+        print()
+
+
+def print_help():
+    """Print comprehensive help information."""
+    print(f"doc-utils v{__version__}")
+    print("\nCLI tools for maintaining clean, consistent AsciiDoc documentation repositories.")
+
+    print_tools_list()
+
+    print("📚 Usage:")
+    print("  doc-utils --version          Show version information")
+    print("  doc-utils --list             List all available tools")
+    print("  doc-utils --help             Show this help message")
+    print("  <tool-name> --help           Show help for a specific tool")
+    print()
+    print("📖 Documentation:")
+    print("  https://rolfedh.github.io/doc-utils/")
+    print()
+    print("💡 Examples:")
+    print("  find-unused-attributes")
+    print("  check-scannability --max-sentence-length 5")
+    print("  format-asciidoc-spacing --dry-run modules/")
+    print()
+    print("⚠️  Safety First:")
+    print("  Always work in a git branch and review changes with 'git diff'")
+    print()
+
+
+def main():
+    """Main entry point for doc-utils command."""
+    # Check for updates (non-blocking)
+    check_version_on_startup()
+
+    parser = argparse.ArgumentParser(
+        description='doc-utils - CLI tools for AsciiDoc documentation projects',
+        add_help=False  # We'll handle help ourselves
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'doc-utils {__version__}'
+    )
+
+    parser.add_argument(
+        '--list',
+        action='store_true',
+        help='List all available tools'
+    )
+
+    parser.add_argument(
+        '--help', '-h',
+        action='store_true',
+        help='Show this help message'
+    )
+
+    # Parse known args to allow for future expansion
+    args, remaining = parser.parse_known_args()
+
+    # Handle flags
+    if args.list:
+        print_tools_list()
+        return 0
+
+    if args.help or len(sys.argv) == 1:
+        print_help()
+        return 0
+
+    # If we get here with remaining args, show help
+    if remaining:
+        print(f"doc-utils: unknown command or option: {' '.join(remaining)}")
+        print("\nRun 'doc-utils --help' for usage information.")
+        return 1
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())