refcheck 0.4.2__tar.gz → 0.4.4__tar.gz

{refcheck-0.4.2 → refcheck-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refcheck
-Version: 0.4.2
+Version: 0.4.4
 Summary: Tool for finding broken references and links in Markdown files.
 License-File: LICENSE
 Keywords: markdown,links,references,validator,cli
@@ -17,14 +17,15 @@ Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Repository, https://github.com/flumi3/markdown-refcheck
 Description-Content-Type: text/markdown
 
-# RefCheck
+# 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.
+Markdown RefCheck is a simple tool that checks Markdown references to find any broken links.  
+It helps keeping your documentation free from broken section refs, missing images and files, and unavailable websites links.
 
 ```text
 usage: refcheck [OPTIONS] [PATH ...]
@@ -45,15 +46,12 @@ options:
 
 ## Features
 
-- 🔍 **Comprehensive Reference Detection** - Find and validate various reference patterns in Markdown files
+- 🔍 **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
+- ⚙️ **CI/CD Ready** - Perfect for automated quality checks in your documentation workflows
 - 🚀 **Pre-commit Integration** - Available as a pre-commit hook for automated validation
 
 ## Installation
@@ -67,6 +65,18 @@ pip install refcheck
 pipx install refcheck
 ```
 
+## Pre-commit Integration
+
+Add this to your `pre-commit-config.yml`:
+
+```yaml
+- repo: https://github.com/flumi3/refcheck
+  rev: v0.4.4
+  hooks:
+    - id: refcheck
+      args: ["docs/", "--exclude", "docs/filetoexclude.md"]
+```
+
 ## Examples
 
 ```text
@@ -112,31 +122,12 @@ 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
+Contributions are welcome!  
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) before opening pull requests.
 
 ## Documentation
 
@@ -146,7 +137,3 @@ For more detailed information, check out the documentation:
 - [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 → refcheck-0.4.4}/README.md

@@ -1,11 +1,12 @@
-# RefCheck
+# 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.
+Markdown RefCheck is a simple tool that checks Markdown references to find any broken links.  
+It helps keeping your documentation free from broken section refs, missing images and files, and unavailable websites links.
 
 ```text
 usage: refcheck [OPTIONS] [PATH ...]
@@ -26,15 +27,12 @@ options:
 
 ## Features
 
-- 🔍 **Comprehensive Reference Detection** - Find and validate various reference patterns in Markdown files
+- 🔍 **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
+- ⚙️ **CI/CD Ready** - Perfect for automated quality checks in your documentation workflows
 - 🚀 **Pre-commit Integration** - Available as a pre-commit hook for automated validation
 
 ## Installation
@@ -48,6 +46,18 @@ pip install refcheck
 pipx install refcheck
 ```
 
+## Pre-commit Integration
+
+Add this to your `pre-commit-config.yml`:
+
+```yaml
+- repo: https://github.com/flumi3/refcheck
+  rev: v0.4.4
+  hooks:
+    - id: refcheck
+      args: ["docs/", "--exclude", "docs/filetoexclude.md"]
+```
+
 ## Examples
 
 ```text
@@ -93,31 +103,12 @@ 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
+Contributions are welcome!  
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) before opening pull requests.
 
 ## Documentation
 
@@ -126,7 +117,3 @@ 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 → refcheck-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "refcheck"
-version = "0.4.2"
+version = "0.4.4"
 description = "Tool for finding broken references and links in Markdown files."
 authors = ["Sebastian Flum <sebastian.flum.dev@gmail.com>"]
 readme = "README.md"

{refcheck-0.4.2 → refcheck-0.4.4}/refcheck/parsers.py

@@ -7,6 +7,7 @@ logger = logging.getLogger()
 
 CODE_BLOCK_PATTERN = re.compile(r"```(?P<content>[\s\S]*?)```")
 INLINE_CODE_PATTERN = re.compile(r"`(?P<content>[^`\n]+)`")
+HTML_COMMENT_PATTERN = re.compile(r"<!--(?P<content>[\s\S]*?)-->")
 
 # Basic Markdown references
 BASIC_REFERENCE_PATTERN = re.compile(r"!*\[(?P<text>[^\]]+)\]\((?P<link>[^)]+)\)")  # []() and ![]()
@@ -98,8 +99,13 @@ class MarkdownParser:
         inline_code = self._find_matches_with_line_numbers(INLINE_CODE_PATTERN, content)
         logger.info(f"Found {len(inline_code)} inline code spans.")
 
-        # Combine code blocks and inline code for filtering
-        all_code = code_blocks + inline_code
+        # Get all HTML comments, such as <!-- ... -->
+        logger.info("Extracting HTML comments ...")
+        html_comments = self._find_matches_with_line_numbers(HTML_COMMENT_PATTERN, content)
+        logger.info(f"Found {len(html_comments)} HTML comments.")
+
+        # Combine code blocks, inline code, and HTML comments for filtering
+        all_code = code_blocks + inline_code + html_comments
 
         # Get all references that look like this: [text](reference)
         logger.info("Extracting basic references ...")
@@ -139,35 +145,35 @@ class MarkdownParser:
     def _drop_code_references(
         self, references: list[ReferenceMatch], code_sections: list[ReferenceMatch]
     ) -> list[ReferenceMatch]:
-        """Drop references that are part of code blocks or inline code."""
-        logger.info("Dropping references that are part of code blocks or inline code ...")
+        """Drop references that are part of code blocks, inline code, or HTML comments."""
+        logger.info(
+            "Dropping references that are part of code blocks, inline code, or HTML comments ..."
+        )
 
-        # Filter out references that are inside code blocks or inline code
+        # Filter out references whose source span is contained within a code/comment section span.
+        # Position-based comparison prevents incorrectly dropping references that share the same
+        # text as a commented-out or code-block reference but appear at a different location.
         filtered_references = []
         dropped_counter = 0
 
         for ref in references:
-            is_in_code = False
-            for code_section in code_sections:
-                logger.debug(ref.match.group(0))
-
-                # Check if reference is within the code section content
-                if code_section.match.lastindex and code_section.match.lastindex >= 1:
-                    content = code_section.match.group(1)
-                    logger.debug(f"Code content: {content}")
-                    if ref.match.group(0) in content:
-                        logger.info(f"Dropping reference: {ref.match.group(0)}")
-                        is_in_code = True
-                        dropped_counter += 1
-                        break
-
-            if not is_in_code:
+            is_in_filtered_section = False
+            for section in code_sections:
+                if section.match.start(0) <= ref.match.start(0) and ref.match.end(
+                    0
+                ) <= section.match.end(0):
+                    logger.info(f"Dropping reference: {ref.match.group(0)}")
+                    is_in_filtered_section = True
+                    dropped_counter += 1
+                    break
+
+            if not is_in_filtered_section:
                 filtered_references.append(ref)
 
         if dropped_counter > 0:
             logger.info(f"Dropped {dropped_counter} references.")
         else:
-            logger.info("No code references found.")
+            logger.info("No filtered references found.")
 
         return filtered_references
 

{refcheck-0.4.2 → refcheck-0.4.4}/refcheck/utils.py

@@ -8,21 +8,21 @@ logger = logging.getLogger()
 IGNORE_FILE = ".refcheckignore"
 
 CHECK_IGNORE_DEFAULTS = [
-    ".git",
-    ".vscode",
-    ".idea",
-    "__pycache__",
-    "node_modules",
-    "venv",
-    ".venv",
-    ".pytest_cache",
+    ".git/",
+    ".vscode/",
+    ".idea/",
+    "__pycache__/",
+    "node_modules/",
+    "venv/",
+    ".venv/",
+    ".pytest_cache/",
 ]
 
 
 def load_exclusion_patterns() -> list[str]:
     """Read exclusions from the .refcheckignore file."""
     if not os.path.isfile(IGNORE_FILE):
-        logger.warning(f"Could not find {IGNORE_FILE}. Using default exclusions.")
+        logger.info(f"Could not find {IGNORE_FILE}. Using default exclusions.")
         exclusions = CHECK_IGNORE_DEFAULTS
     else:
         logger.info(f"Reading exclusions from {IGNORE_FILE}...")
@@ -33,6 +33,21 @@ def load_exclusion_patterns() -> list[str]:
     return exclusions
 
 
+def _is_path_excluded(path: str, exclude_set: set[str]) -> bool:
+    """Check if a path should be excluded based on the exclude set.
+
+    Handles both bare names (e.g. 'node_modules') that may appear anywhere in the
+    path tree, and explicit relative/absolute paths (e.g. '../some/dir').
+    """
+    for ex in exclude_set:
+        if path == ex or path.startswith(ex + os.sep):
+            return True
+        # Bare name with no separator: match against individual path components
+        if os.sep not in ex and ex in path.split(os.sep):
+            return True
+    return False
+
+
 def get_markdown_files_from_dir(root_dir: str, exclude: list[str] | None = None) -> list[str]:
     """Traverse the directory to get all markdown files."""
     if exclude is None:
@@ -44,7 +59,7 @@ def get_markdown_files_from_dir(root_dir: str, exclude: list[str] | None = None)
     # Walk through the directory to get all markdown files
     for subdir, _, files in os.walk(root_dir):
         subdir_norm = os.path.normpath(subdir)
-        if any(subdir_norm.startswith(exclude_item) for exclude_item in exclude_set):
+        if _is_path_excluded(subdir_norm, exclude_set):
             continue  # Skip excluded directories
 
         for file in files:
@@ -76,7 +91,7 @@ def get_markdown_files_from_args(paths: list[str], exclude: list[str] | None = N
             if norm_path.endswith(".md"):
                 markdown_files.add(norm_path)
         else:
-            print(f"[!] Warning: {path} is not a valid file or directory.")
+            print(print_yellow(f"[!] Warning: {path} is not a valid file or directory."))
 
     return list(markdown_files)