refcheck 0.3.0__tar.gz → 0.4.2__tar.gz

refcheck-0.4.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: refcheck
+Version: 0.4.2
+Summary: Tool for finding broken references and links in Markdown files.
+License-File: LICENSE
+Keywords: markdown,links,references,validator,cli
+Author: Sebastian Flum
+Author-email: sebastian.flum.dev@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Project-URL: Repository, https://github.com/flumi3/markdown-refcheck
+Description-Content-Type: text/markdown
+
+# RefCheck
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/refcheck?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/refcheck)
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-silver.svg)](https://opensource.org/licenses/MIT)
+[![CI/CD](https://github.com/flumi3/markdown-refcheck/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/flumi3/markdown-refcheck/actions/workflows/ci-cd.yml)
+
+RefCheck is a simple tool for finding broken references and links in Markdown files.
+
+```text
+usage: refcheck [OPTIONS] [PATH ...]
+
+positional arguments:
+  PATH                  Markdown files or directories to check
+
+options:
+  -h, --help            show this help message and exit
+  -e, --exclude [ ...]  Files or directories to exclude
+  -cm, --check-remote   Check remote references (HTTP/HTTPS links)
+  -nc, --no-color        Turn off colored output
+  -v, --verbose         Enable verbose output
+  --allow-absolute      Allow absolute path references like [ref](/path/to/file.md)
+```
+
+<!-- [![codecov](https://codecov.io/gh/flumi3/markdown-refcheck/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/flumi3/markdown-refcheck) -->
+
+## Features
+
+- 🔍 **Comprehensive Reference Detection** - Find and validate various reference patterns in Markdown files
+- ❌ **Broken Link Highlighting** - Quickly identify broken references with clear error messages
+- 📁 **File Path Validation** - Support for both absolute and relative file paths to any file type
+- 🌐 **Remote URL Checking** - Validate external HTTP/HTTPS links (optional with `--check-remote`)
+- 🎯 **Header Reference Validation** - Verify links to specific sections within Markdown files
+- 🛠️ **User-Friendly CLI** - Simple and intuitive command-line interface
+- ⚙️ **CI/CD Ready** - Perfect for automated quality checks in your documentation workflows
+- 🎨 **Colored Output** - Clear, color-coded results for easy scanning (disable with `--no-color`)
+- 📊 **Detailed Reporting** - Summary statistics and line-by-line reference validation
+- 🚀 **Pre-commit Integration** - Available as a pre-commit hook for automated validation
+
+## Installation
+
+RefCheck is available on PyPI:
+
+```bash
+pip install refcheck
+
+# or using pipx
+pipx install refcheck
+```
+
+## Examples
+
+```text
+$ refcheck README.md
+
+[+] 1 Markdown files to check.
+- README.md
+
+[+] FILE: README.md...
+README.md:3: #introduction - OK
+README.md:5: #installation - OK
+README.md:6: #getting-started - OK
+
+Reference check complete.
+
+============================| Summary |=============================
+🎉 No broken references!
+====================================================================
+```
+
+```text
+$ refcheck . --check-remote
+
+[+] Searching for markdown files in C:\Users\flumi3\github\refcheck ...
+
+[+] 2 Markdown files to check.
+- tests\sample_markdown.md
+- docs\Understanding-Markdown-References.md
+
+[+] FILE: tests\sample_markdown.md...
+tests\sample_markdown.md:39: /img/image.png - BROKEN
+tests\sample_markdown.md:52: https://www.openai.com/logo.png - BROKEN
+
+[+] FILE: docs\Understanding-Markdown-References.md...
+docs\Understanding-Markdown-References.md:42: #local-file-references - OK
+
+Reference check complete.
+
+============================| Summary |=============================
+[!] 2 broken references found:
+tests\sample_markdown.md:39: /img/image.png
+tests\sample_markdown.md:52: https://www.openai.com/logo.png
+====================================================================
+```
+
+## Pre-commit Hook
+
+RefCheck is also available as pre-commit hook!
+
+```yaml
+- repo: https://github.com/flumi3/refcheck
+  rev: v0.4.2
+  hooks:
+    - id: refcheck
+      args: ["docs/", "-e", "docs/filetoexclude.md"] # e.g. scan the docs/ folder and exclude a file
+```
+
+For more advanced configuration options, see the [Integration Guide](docs/Integration-Guide.md).
+
+## Contributing
+
+Contributions are welcome!
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup instructions
+- Commit message conventions
+- Code quality standards
+- Testing requirements
+- Pull request guidelines
+
+## Documentation
+
+For more detailed information, check out the documentation:
+
+- [CLI Reference](docs/CLI-Reference.md) - Complete command-line options and usage
+- [Integration Guide](docs/Integration-Guide.md) - CI/CD and workflow integration
+- [Examples](docs/Examples.md) - Real-world usage examples
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

refcheck-0.4.2/README.md

@@ -0,0 +1,132 @@
+# RefCheck
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/refcheck?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/refcheck)
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-silver.svg)](https://opensource.org/licenses/MIT)
+[![CI/CD](https://github.com/flumi3/markdown-refcheck/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/flumi3/markdown-refcheck/actions/workflows/ci-cd.yml)
+
+RefCheck is a simple tool for finding broken references and links in Markdown files.
+
+```text
+usage: refcheck [OPTIONS] [PATH ...]
+
+positional arguments:
+  PATH                  Markdown files or directories to check
+
+options:
+  -h, --help            show this help message and exit
+  -e, --exclude [ ...]  Files or directories to exclude
+  -cm, --check-remote   Check remote references (HTTP/HTTPS links)
+  -nc, --no-color        Turn off colored output
+  -v, --verbose         Enable verbose output
+  --allow-absolute      Allow absolute path references like [ref](/path/to/file.md)
+```
+
+<!-- [![codecov](https://codecov.io/gh/flumi3/markdown-refcheck/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/flumi3/markdown-refcheck) -->
+
+## Features
+
+- 🔍 **Comprehensive Reference Detection** - Find and validate various reference patterns in Markdown files
+- ❌ **Broken Link Highlighting** - Quickly identify broken references with clear error messages
+- 📁 **File Path Validation** - Support for both absolute and relative file paths to any file type
+- 🌐 **Remote URL Checking** - Validate external HTTP/HTTPS links (optional with `--check-remote`)
+- 🎯 **Header Reference Validation** - Verify links to specific sections within Markdown files
+- 🛠️ **User-Friendly CLI** - Simple and intuitive command-line interface
+- ⚙️ **CI/CD Ready** - Perfect for automated quality checks in your documentation workflows
+- 🎨 **Colored Output** - Clear, color-coded results for easy scanning (disable with `--no-color`)
+- 📊 **Detailed Reporting** - Summary statistics and line-by-line reference validation
+- 🚀 **Pre-commit Integration** - Available as a pre-commit hook for automated validation
+
+## Installation
+
+RefCheck is available on PyPI:
+
+```bash
+pip install refcheck
+
+# or using pipx
+pipx install refcheck
+```
+
+## Examples
+
+```text
+$ refcheck README.md
+
+[+] 1 Markdown files to check.
+- README.md
+
+[+] FILE: README.md...
+README.md:3: #introduction - OK
+README.md:5: #installation - OK
+README.md:6: #getting-started - OK
+
+Reference check complete.
+
+============================| Summary |=============================
+🎉 No broken references!
+====================================================================
+```
+
+```text
+$ refcheck . --check-remote
+
+[+] Searching for markdown files in C:\Users\flumi3\github\refcheck ...
+
+[+] 2 Markdown files to check.
+- tests\sample_markdown.md
+- docs\Understanding-Markdown-References.md
+
+[+] FILE: tests\sample_markdown.md...
+tests\sample_markdown.md:39: /img/image.png - BROKEN
+tests\sample_markdown.md:52: https://www.openai.com/logo.png - BROKEN
+
+[+] FILE: docs\Understanding-Markdown-References.md...
+docs\Understanding-Markdown-References.md:42: #local-file-references - OK
+
+Reference check complete.
+
+============================| Summary |=============================
+[!] 2 broken references found:
+tests\sample_markdown.md:39: /img/image.png
+tests\sample_markdown.md:52: https://www.openai.com/logo.png
+====================================================================
+```
+
+## Pre-commit Hook
+
+RefCheck is also available as pre-commit hook!
+
+```yaml
+- repo: https://github.com/flumi3/refcheck
+  rev: v0.4.2
+  hooks:
+    - id: refcheck
+      args: ["docs/", "-e", "docs/filetoexclude.md"] # e.g. scan the docs/ folder and exclude a file
+```
+
+For more advanced configuration options, see the [Integration Guide](docs/Integration-Guide.md).
+
+## Contributing
+
+Contributions are welcome!
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup instructions
+- Commit message conventions
+- Code quality standards
+- Testing requirements
+- Pull request guidelines
+
+## Documentation
+
+For more detailed information, check out the documentation:
+
+- [CLI Reference](docs/CLI-Reference.md) - Complete command-line options and usage
+- [Integration Guide](docs/Integration-Guide.md) - CI/CD and workflow integration
+- [Examples](docs/Examples.md) - Real-world usage examples
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

refcheck-0.4.2/pyproject.toml

@@ -0,0 +1,112 @@
+[tool.poetry]
+name = "refcheck"
+version = "0.4.2"
+description = "Tool for finding broken references and links in Markdown files."
+authors = ["Sebastian Flum <sebastian.flum.dev@gmail.com>"]
+readme = "README.md"
+repository = "https://github.com/flumi3/markdown-refcheck"
+keywords = ["markdown", "links", "references", "validator", "cli"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = "^2.32.3"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+commitizen = "^4.2.2"
+python-semantic-release = ">=9.20,<11.0"
+ruff = ">=0.9.7,<0.12.0"
+mypy = "^1.13.0"
+types-requests = "^2.32.0"
+vulture = "^2.13"
+deptry = "^0.22.0"
+pre-commit = "^4.0.0"
+
+[tool.poetry.scripts]
+refcheck = "refcheck.main:main"
+
+[tool.ruff]
+line-length = 100
+
+[tool.semantic_release]
+commit_parser = "angular"
+branch = "main"
+major_on_zero = true
+build_command = "pip install poetry && python -m poetry build"
+version_toml = ["pyproject.toml:tool.poetry.version"]
+version_variables = [
+    "pyproject.toml:tool.poetry.version",
+    "README.md:rev:tf",
+    "docs/CLI-Reference.md:rev:tf",
+    "docs/Development-Guide.md:rev:tf",
+    "docs/Examples.md:rev:tf",
+    "docs/Integration-Guide.md:rev:tf",
+    "CONTRIBUTING.md:rev:tf",
+]
+tag_format = "v{version}"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.3.0"
+tag_format = "v$version"
+update_changelog_on_bump = true
+version_files = [
+    "pyproject.toml:tool.poetry.version",
+    "pyproject.toml:tool.commitizen.version"
+]
+
+[tool.vulture]
+min_confidence = 80
+exclude = ["*/__pycache__/*"]
+ignore_names = [
+    "_format_action_invocation",
+    "RAW_LINK_PATTERN",
+    "HTML_LINK_PATTERN",
+    "HTML_IMAGE_PATTERN",
+    "_process_inline_links",
+    "print_green_background",
+    "print_red_background",
+    "is_valid_remote_reference"
+]
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["mypy", "vulture", "deptry"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.coverage.run]
+source = ["refcheck"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/test_*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+fail_under = 80
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

refcheck-0.4.2/refcheck/cli.py

@@ -0,0 +1,75 @@
+import argparse
+import sys
+from argparse import Namespace
+
+
+class CustomFormatter(argparse.HelpFormatter):
+    def _format_action_invocation(self, action):
+        if not action.option_strings:
+            (metavar,) = self._metavar_formatter(action, action.dest)(1)
+            return metavar
+        else:
+            parts = []
+            # if the Optional doesn't take a value, format is:
+            #    -s, --long
+            if action.nargs == 0:
+                parts.extend(action.option_strings)
+
+            # if the Optional takes a value, format is:
+            #    -s ARGS, --long ARGS
+            # change to
+            #    -s, --long ARGS
+            else:
+                default = action.dest.upper()
+                args_string = self._format_args(action, default)
+                for option_string in action.option_strings:
+                    # parts.append('%s %s' % (option_string, args_string))
+                    parts.append("%s" % option_string)
+                parts[-1] += " %s" % args_string
+            return ", ".join(parts)
+
+
+def get_command_line_arguments() -> Namespace:
+    """Setup command line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="refcheck",
+        usage="refcheck [OPTIONS] [PATH ...]",
+        formatter_class=CustomFormatter,
+    )  # type: ignore
+    parser.add_argument(
+        "paths",
+        metavar="PATH",
+        type=str,
+        nargs="*",
+        help="Markdown files or directories to check",
+    )
+    parser.add_argument(
+        "-e",
+        "--exclude",
+        metavar="",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Files or directories to exclude",
+    )  # type: ignore
+    parser.add_argument(
+        "-cm",
+        "--check-remote",
+        action="store_true",
+        help="Check remote references (HTTP/HTTPS links)",
+    )  # type: ignore
+    parser.add_argument("-nc", "--no-color", action="store_true", help="Turn off colored output")  # type: ignore
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")  # type: ignore
+    parser.add_argument(
+        "--allow-absolute",
+        action="store_true",
+        help="Allow absolute path references like [ref](/path/to/file.md)",
+    )  # type: ignore
+
+    # Check if the user has provided any files or directories
+    args = parser.parse_args()
+    if not args.paths:
+        parser.print_help()
+        sys.exit(0)
+
+    return args

{refcheck-0.3.0 → refcheck-0.4.2}/refcheck/log_conf.py

@@ -18,7 +18,7 @@ def setup_logging(verbose=False):
         console_handler.setLevel(logging.INFO)
         console_formatter = logging.Formatter("[%(levelname)s]  %(message)s")
     else:
-        console_handler.setLevel(logging.CRITICAL)
+        console_handler.setLevel(logging.WARNING)
         console_formatter = logging.Formatter("%(asctime)s - %(message)s")
 
     console_handler.setFormatter(console_formatter)

{refcheck-0.3.0 → refcheck-0.4.2}/refcheck/main.py

@@ -32,7 +32,7 @@ class ReferenceChecker:
             logger.info(ref)
 
             if ref.is_remote and not settings.check_remote:
-                logger.warning("Skipping remote reference check.")
+                logger.info("Skipping remote reference check.")
                 status = print_yellow("SKIPPED")
             elif ref.is_remote and settings.check_remote:
                 # Check if remote reference is reachable
@@ -41,9 +41,13 @@ class ReferenceChecker:
                     if response.status_code < 400:
                         status = print_green("OK")
                     else:
-                        logger.info(f"Status code: {response.status_code}, Reason: {response.reason}")
+                        logger.info(
+                            f"Status code: {response.status_code}, Reason: {response.reason}"
+                        )
                         status = print_red("BROKEN")
-                        self.broken_references.append(BrokenReference(**ref.__dict__, status=status))
+                        self.broken_references.append(
+                            BrokenReference(**ref.__dict__, status=status)
+                        )
                 except requests.exceptions.RequestException as e:
                     logger.error(f"Error: Could not reach remote reference '{ref.link}': {e}")
                     status = print_red("BROKEN")
@@ -54,13 +58,17 @@ class ReferenceChecker:
                         status = print_green("OK")
                     else:
                         status = print_red("BROKEN")
-                        self.broken_references.append(BrokenReference(**ref.__dict__, status=status))
+                        self.broken_references.append(
+                            BrokenReference(**ref.__dict__, status=status)
+                        )
                 else:
                     if file_exists(ref.file_path, ref.link):
                         status = print_green("OK")
                     else:
                         status = print_red("BROKEN")
-                        self.broken_references.append(BrokenReference(**ref.__dict__, status=status))
+                        self.broken_references.append(
+                            BrokenReference(**ref.__dict__, status=status)
+                        )
             print(f"{ref.file_path}:{ref.line_number}: {ref.syntax} - {status}")
 
     def print_summary(self):
@@ -69,7 +77,9 @@ class ReferenceChecker:
 
         if self.broken_references:
             print(print_red(f"[!] {len(self.broken_references)} broken references found:"))
-            self.broken_references = sorted(self.broken_references, key=lambda ref: (ref.file_path, ref.line_number))
+            self.broken_references = sorted(
+                self.broken_references, key=lambda ref: (ref.file_path, ref.line_number)
+            )
 
             for broken_ref in self.broken_references:
                 print(f"{broken_ref.file_path}:{broken_ref.line_number}: {broken_ref.syntax}")
@@ -77,12 +87,12 @@ class ReferenceChecker:
             if settings.no_color:
                 print("No broken references!")
             else:
-                print(print_green("\U0001F389 No broken references!"))
+                print(print_green("\U0001f389 No broken references!"))
 
         print("====================================================================")
 
 
-def main() -> bool:
+def main() -> None:
     # Check if settings configuration is valid
     if not settings.is_valid():
         sys.exit(1)
@@ -92,13 +102,17 @@ def main() -> bool:
 
     check_remote: bool = settings.check_remote
     if not check_remote:
-        print(print_yellow("[!] WARNING: Skipping remote reference check. Enable with arg --check-remote."))
+        print(
+            print_yellow(
+                "[!] WARNING: Skipping remote reference check. Enable with arg --check-remote."
+            )
+        )
 
     # Retrieve all markdown files specified by the user
     markdown_files = get_markdown_files_from_args(settings.paths, settings.exclude)
     if not markdown_files:
         print(print_red("[!] No Markdown files specified or found."))
-        return False
+        sys.exit(1)
 
     print(f"\n[+] {len(markdown_files)} Markdown files to check.")
     for file in markdown_files:
@@ -119,20 +133,19 @@ def main() -> bool:
         logging.info(f"Checking {len(image_refs)} image references ...")
         checker.check_references(image_refs)
 
-        if len(basic_refs) == 0 and len(image_refs) == 0:
-            print("No references found.")
+        inline_links = references["inline_links"]
+        logging.info(f"Checking {len(inline_links)} inline links ...")
+        checker.check_references(inline_links)
 
-        # TODO: activate when pre-processing is implemented in parsers
-        # inline_links = references["inline_links"]
-        # logging.info(f"Checking {len(inline_links)} inline links ...")
-        # checker.check_references(inline_links, check_remote)
+        if len(basic_refs) == 0 and len(image_refs) == 0 and len(inline_links) == 0:
+            print("No references found.")
 
     checker.print_summary()
-    return not bool(checker.broken_references)
+    if checker.broken_references:
+        sys.exit(1)  # Exit with failure if broken references found
+    else:
+        sys.exit(0)  # Exit with success if no broken references
 
 
 if __name__ == "__main__":
-    if main():
-        sys.exit(0)
-    else:
-        sys.exit(1)
+    main()