pdflinkcheck 1.1.73__py3-none-any.whl → 1.2.29__py3-none-any.whl

pdflinkcheck/validate.py

@@ -1,31 +1,35 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/validate.py
-
+from __future__ import annotations
 import sys
 from pathlib import Path
 from typing import Dict, Any
 
-from pdflinkcheck.report import run_report
-from pdflinkcheck.io import get_friendly_path, export_validation_json
+from pdflinkcheck.io import get_friendly_path
+from pdflinkcheck.helpers import PageRef  # Importing the established helper
 
 SEP_COUNT=28
 
+START_INDEX = 0  
+# Internal 0-based start
+# Define the offset. 
+# The PDF engines are 0-based.
+# We will add +1 only for the HUMAN REASON strings.
+
+
 def run_validation(
     report_results: Dict[str, Any],
     pdf_path: str,
-    pdf_library: str = "pypdf",
-    check_external: bool = False,
-    export_json: bool = True,
-    print_bool: bool = True
+    check_external: bool = False
 ) -> Dict[str, Any]:
     """
-    Validates links using the output from run_report().
+    Validates links during run_report_*() using a partial completion of the data dict.
 
     Args:
-        report_results: The dict returned by run_report()
+        report_results: The dict returned by run_report_and_call_exports()
         pdf_path: Path to the original PDF (needed for relative file checks and page count)
-        pdf_library: Engine used ("pypdf" or "pymupdf")
         check_external: Whether to validate HTTP URLs (requires network + requests)
-        print_bool: Whether to print results to console
 
     Returns:
         Validation summary stats with valid/broken counts and detailed issues
@@ -35,62 +39,77 @@ def run_validation(
 
     all_links = data.get("external_links", []) + data.get("internal_links", [])
     toc = data.get("toc", [])
+    total_pages = metadata.get("file_overview", {}).get("total_pages",None)
 
     if not all_links and not toc:
-        if print_bool:
-            print("No links or TOC to validate.")
+        print("No links or TOC to validate.")
         return {"summary-stats": {"valid": 0, "broken": 0}, "issues": []}
 
-    # Get total page count (critical for internal validation)
-    try:
-        if pdf_library == "pymupdf":
-            import fitz
-            doc = fitz.open(pdf_path)
-            total_pages = doc.page_count
-            doc.close()
-        else:
-            from pypdf import PdfReader
-            reader = PdfReader(pdf_path)
-            total_pages = len(reader.pages)
-    except Exception as e:
-        if print_bool:
-            print(f"Could not determine page count: {e}")
-        total_pages = None
 
     pdf_dir = Path(pdf_path).parent
 
     issues = []
-    valid_count = 0
+    valid_count = 0 # add more granulaity for types of valid links
+    file_found_count = 0
     broken_file_count = 0
     broken_page_count = 0
-    file_found_count = 0
+    no_destination_page_count = 0
     unknown_web_count = 0
     unknown_reasonableness_count = 0
     unknown_link_count = 0
 
     # Validate active links
-    for i, link in enumerate(all_links):
+    #print("DEBUG validate: entering loop with", len(all_links), "links")
+    for link in all_links:
         link_type = link.get("type")
         status = "valid"
         reason = None
+
         if link_type in ("Internal (GoTo/Dest)", "Internal (Resolved Action)"):
-            target_page = int(link.get("destination_page"))
-            if not isinstance(target_page, int):
-                status = "broken-page"
-                reason = f"Target page not a number: {target_page}"
-            elif (1 <= target_page) and total_pages is None:
-                status = "unknown-reasonableness"
-                reason = "Total page count unavailable, but the page number is reasonable"
-            elif (1 <= target_page <= total_pages):
-                status = "valid"
-                reason = f"Page {target_page} within range (1–{total_pages})"
-            elif target_page < 1:
-                status = "broken-page"
-                reason = f"TOC targets page negative {target_page}."
-            elif not (1 <= target_page <= total_pages):
-                status = "broken-page"
-                reason = f"Page {target_page} out of range (1–{total_pages})"
-            
+            dest_page_raw = link.get("destination_page")
+
+            if dest_page_raw is not None:
+
+                try:
+                    # Use PageRef to handle translation
+                    target_page_ref = PageRef.from_index(int(dest_page_raw))
+                    #target_page = int(dest_page_raw)
+                    
+                    # 1. Immediate Failure: Below 0
+                    if target_page_ref.machine < START_INDEX:
+                        status = "broken-page"
+                        # We use target_page + 1 to show the user what they "saw"
+                        reason = f"Target page {target_page_ref.human} is invalid (negative index)."
+
+                    # 2. Case: We don't know the max page count
+                    elif total_pages is None:
+                        # If it's 0 or higher, we assume it might be okay but can't be sure
+                        status = "unknown-reasonableness"
+                        reason = f"Page {target_page_ref.human} seems reasonable, but total page count is unavailable."
+
+                    # 3. Case: Out of Upper Bounds
+                    elif target_page_ref.machine >= total_pages:
+                        status = "broken-page"
+                        # User sees 1-based, e.g., "Page 101 out of range (1-100)"
+                        reason = f"Page {target_page_ref.human} out of range (1–{total_pages})"
+
+                    # 4. Case: Perfect Match
+                    else:
+                        status = "valid"
+                        reason = f"Page {target_page_ref.human} within range (1–{total_pages})"
+
+                except (ValueError, TypeError):
+                    status = "broken-page"
+                    reason = f"Invalid page value: {dest_page_raw}"
+
+                except (ValueError, TypeError):
+                    status = "broken-page"
+                    reason = f"Invalid page value: {dest_page_raw}"
+
+            elif dest_page_raw is None:
+                status = "no-destinstion-page"
+                reason = "No destination page resolved"
+
         elif link_type == "Remote (GoToR)":
             remote_file = link.get("remote_file")
             if not remote_file:
@@ -132,55 +151,79 @@ def run_validation(
             unknown_reasonableness_count += 1
         elif status == "unknown-link":
             unknown_link_count += 1
-        elif status == "broken-file":
+        elif status == "broken-page":
             broken_page_count += 1
             issues.append(link_with_val)
         elif status == "broken-file":
-            broken_page_count += 1
+            broken_file_count += 1
+            issues.append(link_with_val)
+        elif status == "no-destinstion-page":
+            no_destination_page_count += 1
             issues.append(link_with_val)
 
     # Validate TOC entries
     for entry in toc:
-        target_page = int(entry.get("target_page"))
-        if isinstance(target_page, int):
-            if (1 <= target_page) and total_pages is None:
-                reason = "Page count unknown"
+        try:
+            # Coerce to int; we expect 0-based index from the engine
+            # In the context of the ing Map, -1 acts as a "Sentinel Value." It represents a state that is strictly outside the "Machine" range
+            target_page_raw = int(entry.get("target_page", -1))
+            target_page_ref = PageRef.from_index(int(target_page_raw))
+
+            status = "valid"
+            reason = ""
+
+            # 1. Check for negative indices (anything below our START_INDEX)
+            if target_page_ref.machine < START_INDEX:
+                status = "broken-page"
+                broken_page_count += 1
+                # User sees Page 0 or lower as the problem
+                reason = f"TOC targets invalid page number: {target_page_ref.human}"
+
+            # 2. Case: total_pages is unknown
+            elif total_pages is None:
                 status = "unknown-reasonableness"
                 unknown_reasonableness_count += 1
-            elif target_page < 1:
+                reason = f"Page {target_page_ref.human} unknown (could not verify total pages)"
+
+            # 3. Case: Out of range (Upper Bound)
+            # Index 100 in a 100-page doc (total_pages=100) is out of bounds
+            elif target_page_ref.machine >= total_pages:
                 status = "broken-page"
-                broken_count += 1
-                reason = f"TOC targets negative page: {target_page}."
-            elif 1 <= target_page <= total_pages:
+                broken_page_count += 1
+                reason = f"TOC targets page {target_page_ref.human} (out of 1–{total_pages})"
+
+            # 4. Valid Case
+            else:
+                status = "valid"
                 valid_count += 1
+                # We skip issues.append for valid TOC entries to keep the issues list clean
                 continue
-            else:
-                status = "broken-page"
-                reason = f"TOC targets page {page} (out of 1–{total_pages})"
-                broken_count += 1
-        else:
+
+        except (ValueError, TypeError):
             status = "broken-page"
-            reason = f"Invalid page: {target_page}"
-            broken_count += 1
+            broken_page_count += 1
+            reason = f"Invalid page reference: {entry.get('target_page')}"
 
+        # Only reaches here if status is not "valid" (because of 'continue' above)
         issues.append({
             "type": "TOC Entry",
-            "title": entry["title"],
-            "level": entry["level"],
-            "target_page": target_page,
+            "title": entry.get("title", "Untitled"),
+            "level": entry.get("level", 0),
+            "target_page": target_page_ref.machine, # Stored as 0-indexed for data consistency
             "validation": {"status": status, "reason": reason}
         })
-
+    
+    total_checked = metadata.get("link_counts",{}).get("total_links_count",0) + metadata.get("link_counts",{}).get("toc_entry_count",0)
     summary_stats = {
-        "total_checked": len(all_links) + len(toc),
+        "total_checked": total_checked,
         "valid": valid_count,
         "file-found": file_found_count,
         "broken-page": broken_page_count,
         "broken-file": broken_file_count,
+        "no_destination_page_count": no_destination_page_count,
         "unknown-web": unknown_web_count,
         "unknown-reasonableness": unknown_reasonableness_count,
-        "unknown-link": unknown_link_count,
-        #"unknown": len(all_links) + len(toc) - valid_count - broken_count # nah this is not granuar enough 
+        "unknown-link": unknown_link_count 
     }
 
     
@@ -200,11 +243,13 @@ def run_validation(
         log(f"PDF Path = {get_friendly_path(pdf_path)}")
         log(f"Total items checked: {summary_stats['total_checked']}")
         log(f"✅ Valid: {summary_stats['valid']}")
-        log(f"🌐 Web Addresses (Not Checked): {summary_stats['unknown-web']}")
+        #log(f"✅ Valid: {summary_stats['valid']}")
+        #log(f"✅ Valid: {summary_stats['valid']}")
+        log(f"🌐 Web Addresses (Ping Each: OFF): {summary_stats['unknown-web']}")
         log(f"⚠️ Unknown Page Reasonableness (Due to Missing Total Page Count): {summary_stats['unknown-reasonableness']}")
         log(f"⚠️ Unsupported PDF Links: {summary_stats['unknown-link']}")
-        log(f"❌ Broken Page Reference: {summary_stats['broken-page']}")
-        log(f"❌ Broken File Reference: {summary_stats['broken-file']}")
+        log(f"❌ Broken Page Reference (Page number beyond scope of availability): {summary_stats['broken-page']}")
+        log(f"❌ Broken File Reference (File not available): {summary_stats['broken-file']}")
         log("=" * SEP_COUNT)
 
         if issues:
@@ -219,8 +264,16 @@ def run_validation(
                 log("{:<5} | {:<12} | {:<30} | {}".format(i, link_type, text, reason))
             if len(issues) > 25:
                 log(f"... and {len(issues) - 25} more issues")
+
+        elif summary_stats.get('total_checked', 0) == 0:
+            # Check if this was a total crash or just an empty PDF
+            if summary_stats.get('is_error_fallback'): 
+                 log("\nStatus: Validation could not be performed due to a processing error.")
+            else:
+                 log("\nStatus: No links or TOC entries were found to validate.")
+
         else:
-            log("No issues found — all links and TOC entries are valid!")
+            log("Success: No broken links or TOC issues!")
 
         # Final aggregation of the buffer into one string
         validation_buffer_str = "\n".join(validation_buffer)
@@ -228,8 +281,6 @@ def run_validation(
         return validation_buffer_str
     
     summary_txt = generate_validation_summary_txt_buffer(summary_stats, issues, pdf_path)
-    if print_bool:
-        print(summary_txt)
 
     validation_results = {
         "pdf_path" : pdf_path,
@@ -239,144 +290,4 @@ def run_validation(
         "total_pages": total_pages
     }
 
-    # Have export run interally so that the logic need not happen in an interface
-
-    export_validation_json(validation_results,  pdf_path, pdf_library)
     return validation_results
-
-
-def run_validation_more_readable_slop(pdf_path: str = None, pdf_library: str = "pypdf", check_external_links:bool = False) -> Dict[str, Any]:
-    """
-    Experimental. Ignore for now.
-
-    Extends the report logic by programmatically testing every extracted link.
-    Validates Internal Jumps (page bounds), External URIs (HTTP status), 
-    and Launch actions (file existence).
-    """
-    if check_external_links:
-        import requests
-
-    # 1. Setup Library Engine (Reuse your logic)
-    pdf_library = pdf_library.lower()
-    if pdf_library == "pypdf":
-        from pdflinkcheck.analyze_pypdf import extract_links_pypdf as extract_links
-    else:
-        from pdflinkcheck.analyze_pymupdf import extract_links_pymupdf as extract_links
-
-    if pdf_path is None:
-        pdf_path = get_first_pdf_in_cwd()
-    
-    if not pdf_path:
-        print("Error: No PDF found for validation.")
-        return {}
-
-    print(f"\nValidating links in {Path(pdf_path).name}...")
-
-    # 2. Extract links and initialize validation counters
-    links = extract_links(pdf_path)
-    total_links = len(links)
-    results = {"valid": [], "broken": [], "error": []}
-
-    # 3. Validation Loop
-    for i, link in enumerate(links, 1):
-        # Progress indicator for long manuals
-        sys.stdout.write(f"\rChecking link {i}/{total_links}...")
-        sys.stdout.flush()
-
-        link_type = link.get('type')
-        status = {"is_valid": False, "reason": "Unknown Type"}
-
-        # --- A. Validate Internal Jumps ---
-        if "Internal" in link_type:
-            target_page = link.get('destination_page')
-            if isinstance(target_page, int) and target_page > 0:
-                # In a real run, you'd compare against reader.pages_count
-                status = {"is_valid": True, "reason": "Resolves"}
-            else:
-                status = {"is_valid": False, "reason": f"Invalid Page: {target_page}"}
-
-        # --- B. Validate Web URIs ---
-        elif link_type == 'External (URI)':
-
-            url = link.get('url')
-            if url and url.startswith("http") and check_external_links:
-                try:
-                    # Use a short timeout and HEAD request to be polite/fast
-                    resp = requests.head(url, timeout=5, allow_redirects=True)
-                    if resp.status_code < 400:
-                        status = {"is_valid": True, "reason": f"HTTP {resp.status_code}"}
-                    else:
-                        status = {"is_valid": False, "reason": f"HTTP {resp.status_code}"}
-                except Exception as e:
-                    status = {"is_valid": False, "reason": "Connection Failed"}
-            else:
-                status = {"is_valid": False, "reason": "Malformed URL"}
-
-        # --- C. Validate Local File/Launch Links ---
-        elif link_type == 'Launch' or 'remote_file' in link:
-            file_path = link.get('remote_file') or link.get('url')
-            if file_path:
-                # Clean URI formatting
-                clean_path = file_path.replace("file://", "").replace("%20", " ")
-                # Check relative to the PDF's location
-                abs_path = Path(pdf_path).parent / clean_path
-                if abs_path.exists():
-                    status = {"is_valid": True, "reason": "File Exists"}
-                else:
-                    status = {"is_valid": False, "reason": "File Missing"}
-
-        # Append result
-        link['validation'] = status
-        if status['is_valid']:
-            results['valid'].append(link)
-        else:
-            results['broken'].append(link)
-
-    print("\n" + "=" * SEP_COUNT)
-    print(f"--- Validation Summary Stats for {Path(pdf_path).name} ---")
-    print(f"Total Checked: {total_links}")
-    print(f"✅ Valid:  {len(results['valid'])}")
-    print(f"❌ Broken: {len(results['broken'])}")
-    print("=" * SEP_COUNT)
-
-    # 4. Print Detail Report for Broken Links
-    if results['broken']:
-        print("\n## ❌ Broken Links Found:")
-        print("{:<5} | {:<5} | {:<30} | {}".format("Idx", "Page", "Reason", "Target"))
-        print("-" * SEP_COUNT)
-        for i, link in enumerate(results['broken'], 1):
-            target = link.get('url') or link.get('destination_page') or link.get('remote_file')
-            print("{:<5} | {:<5} | {:<30} | {}".format(
-                i, link['page'], link['validation']['reason'], str(target)[:30]
-            ))
-    
-    return results
-
-
-if __name__ == "__main__":
-
-    from pdflinkcheck.io import get_first_pdf_in_cwd
-    pdf_path = get_first_pdf_in_cwd()
-    # Run analysis first
-    report = run_report(
-        pdf_path=pdf_path,
-        max_links=0,
-        export_format="",
-        pdf_library="pypdf",
-        print_bool=False  # We handle printing in validation
-    )
-
-    if not report or not report.get("data"):
-        print("No data extracted — nothing to validate.")
-        sys.exit(1)
-
-    # Then validate
-    validation_results = run_validation(
-        report_results=report,
-        pdf_path=pdf_path,
-        pdf_library="pypdf",
-        export_json=True,
-        print_bool=True
-    )
-
-    export_validation_results()

pdflinkcheck/version_info.py

@@ -1,4 +1,7 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/version_info.py
+from __future__ import annotations
 import re
 from pathlib import Path
 import sys
@@ -11,7 +14,7 @@ This portion of the codebase is MIT licensed. It does not rely on any AGPL-licen
 
 MIT License
 
-Copyright (c) 2025 George Clayton Bennett <george.bennett@memphistn.gov>
+Copyright © 2025 George Clayton Bennett <george.bennett@memphistn.gov>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -52,7 +55,7 @@ def find_pyproject(start: Path) -> Path | None:
         if candidate.exists():
             return candidate
         
-    # 3. Handle Installed / Wheel / Shiv state (using your force-include path)
+    # 3. Handle Installed / Wheel / Shiv state (using force-include path)
     internal_path = Path(__file__).parent / "data" / "pyproject.toml"
     if internal_path.exists():
         return internal_path
@@ -80,4 +83,4 @@ def get_version_from_pyproject() -> str:
         match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', poetry_section.group(1))
         if match: return match.group(1)
 
-    return "0.0.0"
+    return "0.0.0"