Markdown-Checker 0.2.5__tar.gz → 1.0.1__tar.gz

{markdown_checker-0.2.5/src/markdown_checker.egg-info → markdown_checker-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-checker
-Version: 0.2.5
+Version: 1.0.1
 Summary: A markdown link validation reporting tool.
 Author-email: John Aziz <johnaziz269@gmail.com>
 Maintainer-email: John Aziz <johnaziz269@gmail.com>
@@ -37,21 +37,20 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 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: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: click
-Requires-Dist: requests
+Requires-Dist: click==8.3.2
+Requires-Dist: httpx==0.28.1
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
-Requires-Dist: types-requests; extra == "dev"
 Provides-Extra: lint
 Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test
@@ -93,6 +92,8 @@ pip install markdown-checker
 
 For more customizations read the docs.
 
+> **Note:** When using list parameters (like `--skip-domains`, `--skip-files`, etc.), provide values as comma-separated without spaces: `--skip-domains=example.com,test.com`. Do not use square brackets or spaces after commas. See the [Advanced Usage](https://markdown-checker.readthedocs.io/en/latest/advanced/) documentation for detailed examples.
+
 ## Using `markdown-checker` in GitHub Actions
 
 You can run this tool within a GitHub workflow using the [action-check-markdown](https://github.com/marketplace/actions/check-markdown) GitHub action.

{markdown_checker-0.2.5 → markdown_checker-1.0.1}/README.md

@@ -27,6 +27,8 @@ pip install markdown-checker
 
 For more customizations read the docs.
 
+> **Note:** When using list parameters (like `--skip-domains`, `--skip-files`, etc.), provide values as comma-separated without spaces: `--skip-domains=example.com,test.com`. Do not use square brackets or spaces after commas. See the [Advanced Usage](https://markdown-checker.readthedocs.io/en/latest/advanced/) documentation for detailed examples.
+
 ## Using `markdown-checker` in GitHub Actions
 
 You can run this tool within a GitHub workflow using the [action-check-markdown](https://github.com/marketplace/actions/check-markdown) GitHub action.

{markdown_checker-0.2.5 → markdown_checker-1.0.1}/pyproject.toml

@@ -1,16 +1,16 @@
 [project]
 name = "markdown-checker"
 description= "A markdown link validation reporting tool."
-version = "0.2.5"
+version = "1.0.1"
 authors = [{ name = "John Aziz", email = "johnaziz269@gmail.com" }]
 maintainers = [{ name = "John Aziz", email = "johnaziz269@gmail.com" }]
 license = {file = "LICENSE"}
 readme = "README.md"
 
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
-    "click",
-    "requests",
+    "click==8.3.2",
+    "httpx==0.28.1",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -19,10 +19,10 @@ classifiers = [
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Software Development :: Quality Assurance",
 ]
@@ -41,7 +41,6 @@ Releases = "https://github.com/john0isaac/markdown-checker/releases"
 dev = [
     "pre-commit",
     "mypy",
-    "types-requests",
 ]
 lint = [
     "ruff"
@@ -60,18 +59,34 @@ docs = [
 [tool.ruff]
 lint.select = ["E", "F", "I", "UP"]
 line-length = 120
-target-version = "py39"
+target-version = "py310"
 src = ["src"]
 lint.isort.known-first-party = ["markdown_checker"]
 output-format = "full"
 
 [tool.mypy]
+strict_optional = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
 check_untyped_defs = true
-python_version = 3.9
-exclude = [".venv/*"]
+python_version = '3.10'
+exclude = [".venv/*", "tests/*", "smoke/*"]
+
+[tool.pytest.ini_options]
+markers = [
+    "smoke: end-to-end smoke tests that run the CLI against sample files",
+]
+addopts = "-ra"
+testpaths = ["tests"]
+pythonpath = ['src']
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.report]
+show_missing = true
 
 [project.scripts]
-markdown-checker = "markdown_checker:main_with_spinner"
+markdown-checker = "markdown_checker:main"
 
 [build-system]
 requires = ["setuptools", "wheel"]

markdown_checker-1.0.1/src/markdown_checker/__init__.py

@@ -0,0 +1,10 @@
+"""
+markdown-checker — a markdown link validation reporting tool.
+"""
+
+__version__ = "1.0.1"
+
+from markdown_checker.cli import main
+from markdown_checker.models import Config, MarkdownLinkBase, MarkdownPath, MarkdownURL
+
+__all__ = ["Config", "main", "MarkdownLinkBase", "MarkdownPath", "MarkdownURL", "__version__"]

markdown_checker-1.0.1/src/markdown_checker/checker.py

@@ -0,0 +1,82 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from markdown_checker.checks import REGISTRY
+from markdown_checker.models import Config, MarkdownLinkBase
+from markdown_checker.utils import get_links_from_md_file
+
+
+@dataclass
+class CheckResult:
+    """Result of running a check on one or more files."""
+
+    issues: list[tuple[Path, list[MarkdownLinkBase]]] = field(default_factory=list)
+    links_checked: int = 0
+
+
+def detect_issues(
+    func: str,
+    file_path: Path,
+    config: Config,
+) -> tuple[list[MarkdownLinkBase], int]:
+    """
+    Detect issues in a single markdown file using the named check.
+
+    Args:
+        func (str): Name of the check to run (must be a key in REGISTRY).
+        file_path (Path): Path to the markdown file to check.
+        config (Config): Runtime configuration for the check.
+
+    Returns:
+        A tuple of (detected_issues, links_checked_count).
+
+    Raises:
+        ValueError: If func is not a registered check name.
+    """
+    check = REGISTRY.get(func)
+    if check is None:
+        raise ValueError(f"Unknown check function: {func!r}. Available: {list(REGISTRY)}")
+
+    all_links = get_links_from_md_file(file_path)
+    if not all_links.paths and not all_links.urls:
+        return [], 0
+
+    detected_issues = check.run(links=all_links, config=config)
+
+    links_count = len(all_links.paths) if check.link_type == "paths" else len(all_links.urls)
+    return detected_issues, links_count
+
+
+def run_check_on_files(
+    func: str,
+    files_paths: list[Path],
+    config: Config,
+    progress_callback: Callable[[], None],
+) -> CheckResult:
+    """
+    Run a named check across multiple files.
+
+    Args:
+        func: Name of the check to run (must be a key in REGISTRY).
+        files_paths: List of markdown file paths to check.
+        config: Runtime configuration for the check.
+        progress_callback: Callback invoked after each file is checked.
+
+    Returns:
+        A CheckResult with per-file issues and total links checked.
+    """
+    check = REGISTRY.get(func)
+    if check is None:
+        raise ValueError(f"Unknown check function: {func!r}. Available: {list(REGISTRY)}")
+
+    result = CheckResult()
+
+    for file_path in files_paths:
+        detected_issues, links_count = detect_issues(func=func, file_path=file_path, config=config)
+        result.links_checked += links_count
+        if detected_issues:
+            result.issues.append((file_path, detected_issues))
+        progress_callback()
+
+    return result

markdown_checker-1.0.1/src/markdown_checker/checks/__init__.py

@@ -0,0 +1,16 @@
+from markdown_checker.checks.base import BaseCheck
+from markdown_checker.checks.broken_paths import BrokenPathsCheck
+from markdown_checker.checks.broken_urls import BrokenURLsCheck
+from markdown_checker.checks.locale import URLsLocaleCheck
+from markdown_checker.checks.tracking import PathsTrackingCheck, URLsTrackingCheck
+
+# Maps the CLI --func argument value to the corresponding check instance.
+REGISTRY: dict[str, BaseCheck] = {
+    BrokenPathsCheck.name: BrokenPathsCheck(),
+    BrokenURLsCheck.name: BrokenURLsCheck(),
+    URLsTrackingCheck.name: URLsTrackingCheck(),
+    PathsTrackingCheck.name: PathsTrackingCheck(),
+    URLsLocaleCheck.name: URLsLocaleCheck(),
+}
+
+__all__ = ["REGISTRY", "BaseCheck"]

markdown_checker-1.0.1/src/markdown_checker/checks/base.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import Literal
+
+from markdown_checker.models import Config, MarkdownLinkBase
+from markdown_checker.utils.extract_links import MarkdownLinks
+
+
+class BaseCheck(ABC):
+    """Abstract base class for all link checks."""
+
+    name: str
+    link_type: Literal["paths", "urls"]
+
+    @abstractmethod
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        """
+        Run the check against the extracted links.
+
+        Args:
+            links (MarkdownLinks): Extracted URLs and paths from a file.
+            config: Runtime configuration for the check run.
+
+        Returns:
+            List of links that failed the check, each with an .issue set.
+        """
+        raise NotImplementedError

markdown_checker-1.0.1/src/markdown_checker/checks/broken_paths.py

@@ -0,0 +1,22 @@
+from markdown_checker.checks.base import BaseCheck
+from markdown_checker.models import Config, MarkdownLinkBase
+from markdown_checker.utils.extract_links import MarkdownLinks
+
+
+class BrokenPathsCheck(BaseCheck):
+    """Check for relative paths in markdown files that do not exist on disk."""
+
+    name = "check_broken_paths"
+    link_type = "paths"
+
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        detected_issues: list[MarkdownLinkBase] = []
+        for path in links.paths:
+            if not path.exists():
+                path.issue = "is broken"
+                detected_issues.append(path)
+        return detected_issues

markdown_checker-1.0.1/src/markdown_checker/checks/broken_urls.py

@@ -0,0 +1,67 @@
+import concurrent.futures
+from functools import partial
+
+from markdown_checker.checks.base import BaseCheck
+from markdown_checker.models import Config, MarkdownLinkBase, MarkdownURL
+from markdown_checker.utils.extract_links import MarkdownLinks
+
+# Domains known to block automated requests (e.g. Cloudflare 403);
+# always skipped for URL checks.
+_BUILTIN_SKIP_DOMAINS: list[str] = [
+    "openai.com",
+]
+
+
+def _check_url(
+    url: MarkdownURL,
+    skip_domains: list[str],
+    skip_urls_containing: list[str],
+    timeout: int,
+    retries: int,
+) -> MarkdownURL | None:
+    """Thread worker: checks a single URL with its own httpx client."""
+    hostname = url.host_name().lower()
+    if any(domain.lower() in hostname for domain in skip_domains) or any(
+        substring in url.link for substring in skip_urls_containing
+    ):
+        return None
+    # Each worker creates its own client via is_alive(client=None).
+    if not url.is_alive(timeout=timeout, retries=retries):
+        url.issue = "is broken"
+        return url
+    return None
+
+
+class BrokenURLsCheck(BaseCheck):
+    """Check for URLs in markdown files that return non-2xx responses."""
+
+    name = "check_broken_urls"
+    link_type = "urls"
+
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        config = config or Config()
+        effective_skip = [*config.skip_domains, *_BUILTIN_SKIP_DOMAINS]
+        skip_urls_containing = config.skip_urls_containing
+
+        worker = partial(
+            _check_url,
+            skip_domains=effective_skip,
+            skip_urls_containing=skip_urls_containing,
+            timeout=config.timeout,
+            retries=config.retries,
+        )
+        # NOTE: httpx.Client is NOT thread-safe. Do not share a single client
+        # across ThreadPoolExecutor workers. Each worker creates its own
+        # client via is_alive(client=None) to avoid RuntimeError crashes.
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = {executor.submit(worker, url): url for url in links.urls}
+            results: list[MarkdownLinkBase] = []
+            for future in concurrent.futures.as_completed(futures):
+                result = future.result()
+                if result is not None:
+                    results.append(result)
+        return results

markdown_checker-1.0.1/src/markdown_checker/checks/locale.py

@@ -0,0 +1,36 @@
+from markdown_checker.checks.base import BaseCheck
+from markdown_checker.models import Config, MarkdownLinkBase
+from markdown_checker.utils.extract_links import MarkdownLinks
+
+# Domains where locale is required in the URL path; always skipped for locale checks.
+_BUILTIN_SKIP_DOMAINS: list[str] = [
+    "www.nvidia.com",
+]
+
+
+class URLsLocaleCheck(BaseCheck):
+    """Check that URLs do not contain a country/language locale segment."""
+
+    name = "check_urls_locale"
+    link_type = "urls"
+
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        config = config or Config()
+        effective_skip = [*config.skip_domains, *_BUILTIN_SKIP_DOMAINS]
+        skip_urls_containing = config.skip_urls_containing
+
+        detected_issues: list[MarkdownLinkBase] = []
+        for url in links.urls:
+            hostname = url.host_name().lower()
+            if any(domain.lower() in hostname for domain in effective_skip) or any(
+                substring in url.link for substring in skip_urls_containing
+            ):
+                continue
+            if url.has_locale():
+                url.issue = "has locale"
+                detected_issues.append(url)
+        return detected_issues

markdown_checker-1.0.1/src/markdown_checker/checks/tracking.py

@@ -0,0 +1,51 @@
+from markdown_checker.checks.base import BaseCheck
+from markdown_checker.models import Config, MarkdownLinkBase
+from markdown_checker.utils.extract_links import MarkdownLinks
+
+
+class URLsTrackingCheck(BaseCheck):
+    """Check that URLs on configured tracking domains include a tracking ID."""
+
+    name = "check_urls_tracking"
+    link_type = "urls"
+
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        config = config or Config()
+        skip_domains = config.skip_domains
+        skip_urls_containing = config.skip_urls_containing
+        tracking_domains = config.tracking_domains
+
+        detected_issues: list[MarkdownLinkBase] = []
+        for url in links.urls:
+            hostname = url.host_name().lower()
+            if any(domain.lower() in hostname for domain in skip_domains) or any(
+                substring in url.link for substring in skip_urls_containing
+            ):
+                continue
+            if any(domain.lower() in hostname for domain in tracking_domains) and not url.has_tracking():
+                url.issue = "is missing tracking id"
+                detected_issues.append(url)
+        return detected_issues
+
+
+class PathsTrackingCheck(BaseCheck):
+    """Check that relative paths include a tracking ID."""
+
+    name = "check_paths_tracking"
+    link_type = "paths"
+
+    def run(
+        self,
+        links: MarkdownLinks,
+        config: Config | None = None,
+    ) -> list[MarkdownLinkBase]:
+        detected_issues: list[MarkdownLinkBase] = []
+        for path in links.paths:
+            if not path.has_tracking():
+                path.issue = "is missing tracking id"
+                detected_issues.append(path)
+        return detected_issues

markdown_checker-1.0.1/src/markdown_checker/cli.py

@@ -0,0 +1,231 @@
+import os
+import platform
+from pathlib import Path
+
+import click
+
+from markdown_checker.checker import run_check_on_files
+from markdown_checker.models.config import Config
+from markdown_checker.reports.format_output import format_issues_table
+from markdown_checker.reports.markdown import MarkdownGenerator
+from markdown_checker.utils.list_files import get_files_paths_list
+
+
+class ListOfStrings(click.Option):
+    """
+    Helper class to parse a comma-separated list of strings from the command line.
+
+    Ref: https://stackoverflow.com/questions/47631914/how-to-pass-several-list-of-arguments-to-click-option
+    """
+
+    def type_cast_value(self, ctx, value) -> list[str]:  # type: ignore
+        try:
+            if isinstance(value, str):
+                return list(filter(None, value.split(",")))
+            elif isinstance(value, list):
+                return value
+            else:
+                raise Exception
+        except Exception:
+            raise click.BadParameter(str(value))
+
+
+@click.command()
+@click.argument(
+    "src",
+    nargs=-1,
+    type=click.Path(path_type=Path, exists=True, file_okay=True, dir_okay=True, readable=True),
+    metavar="SRC ...",
+    required=False,
+)
+@click.option(
+    "-d",
+    "--dir",
+    type=click.Path(path_type=Path, exists=True, file_okay=False, dir_okay=True, readable=True),
+    help="Path to the root directory to check.",
+    required=False,
+)
+@click.option(
+    "-f",
+    "--func",
+    type=click.Choice(
+        [
+            "check_broken_paths",
+            "check_broken_urls",
+            "check_paths_tracking",
+            "check_urls_tracking",
+            "check_urls_locale",
+        ]
+    ),
+    help="Function to be executed.",
+    required=True,
+)
+@click.option(
+    "-ext",
+    "--extensions",
+    cls=ListOfStrings,
+    type=list[str],
+    default=[".md", ".ipynb"],
+    help="File extensions to filter the files.",
+    required=False,
+)
+@click.option(
+    "-td",
+    "--tracking-domains",
+    cls=ListOfStrings,
+    type=list[str],
+    default=["github.com", "microsoft.com", "visualstudio.com", "aka.ms", "azure.com"],
+    help="List of tracking domains to check.",
+    required=False,
+)
+@click.option(
+    "-sf",
+    "--skip-files",
+    cls=ListOfStrings,
+    type=list[str],
+    default=[
+        "CODE_OF_CONDUCT.md",
+        "SECURITY.md",
+    ],
+    help="List of file names to skip check.",
+    required=False,
+)
+@click.option(
+    "-sd",
+    "--skip-domains",
+    cls=ListOfStrings,
+    type=list[str],
+    default=[],
+    help="List of domains to skip check.",
+    required=False,
+)
+@click.option(
+    "-suc",
+    "--skip-urls-containing",
+    cls=ListOfStrings,
+    type=list[str],
+    default=[],
+    help="List of urls to skip check.",
+    required=False,
+)
+@click.option(
+    "-gu",
+    "--guide-url",
+    type=str,
+    help="Full url of your contributing guide.",
+    required=False,
+)
+@click.option(
+    "-to",
+    "--timeout",
+    type=click.IntRange(0, 50),
+    default=20,
+    help="Timeout in seconds for the requests.",
+    required=False,
+)
+@click.option(
+    "-rt",
+    "--retries",
+    type=click.IntRange(0, 10),
+    default=3,
+    help="Number of retries for the requests.",
+    required=False,
+)
+@click.option(
+    "-o",
+    "--output-file-name",
+    type=str,
+    default="comment",
+    help="Name of the output file.",
+    required=False,
+)
+@click.version_option(
+    message=(f"%(prog)s, %(version)s\nPython ({platform.python_implementation()}) {platform.python_version()}"),
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    src: tuple[Path, ...],
+    dir: Path | None,
+    func: str,
+    guide_url: str | None,
+    extensions: list[str],
+    skip_files: list[str],
+    skip_domains: list[str],
+    skip_urls_containing: list[str],
+    tracking_domains: list[str],
+    timeout: int,
+    retries: int,
+    output_file_name: str,
+) -> None:
+    """A markdown link validation reporting tool."""
+    if src:
+        files_paths = []
+        for p in src:
+            if p.is_dir():
+                _, dir_files = get_files_paths_list(p, extensions)
+                files_paths.extend(dir_files)
+            elif p.suffix.lower() in extensions:
+                files_paths.append(p)
+    elif dir is not None:
+        _, files_paths = get_files_paths_list(dir, extensions)
+    else:
+        raise click.UsageError("Either SRC or --dir must be provided.")
+
+    # remove files from skip_files list
+    files_paths = [file_path for file_path in files_paths if file_path.name not in skip_files]
+
+    config = Config(
+        skip_domains=skip_domains,
+        skip_urls_containing=skip_urls_containing,
+        tracking_domains=tracking_domains,
+        timeout=timeout,
+        retries=retries,
+        output_mode="ci" if os.getenv("CI", "false") == "true" else "local",
+    )
+
+    with click.progressbar(length=len(files_paths), label="Checking", hidden=config.output_mode == "ci") as bar:
+        check_result = run_check_on_files(
+            func=func,
+            files_paths=files_paths,
+            config=config,
+            progress_callback=lambda: bar.update(1),
+        )
+
+    click.echo(
+        click.style(f"\n🔍 Checked {check_result.links_checked} links in {len(files_paths)} files.", fg="blue"),
+        err=False,
+    )
+
+    if check_result.issues:
+        formatted_output = format_issues_table(check_result.issues, config.output_mode)
+        generator = MarkdownGenerator(contributing_guide_url=guide_url, output_file_name=output_file_name)
+        generator.generate(func, formatted_output)
+
+        all_issues = [issue for _, issues in check_result.issues for issue in issues]
+        click.echo(click.style(f"😭 Found {len(all_issues)} issues in the following files:", fg="red"), err=True)
+        for markdown_path in all_issues:
+            if config.output_mode == "ci":
+                # Ref: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message
+                click.echo(
+                    click.style(
+                        f"::error file={markdown_path.file_path},line={markdown_path.line_number}::"
+                        f"File {markdown_path.file_path}, line {markdown_path.line_number}, "
+                        f"Link {markdown_path} {markdown_path.issue}.",
+                        fg="red",
+                    ),
+                    err=True,
+                )
+            else:
+                click.echo(
+                    click.style(
+                        f"\tFile '{markdown_path.file_path.resolve()}', line {markdown_path.line_number}"
+                        f"\n{markdown_path} {markdown_path.issue}.\n",
+                        fg="red",
+                    ),
+                    err=True,
+                )
+        ctx.exit(1)
+
+    click.echo(click.style("All files are compliant with the guidelines. 🎉", fg="green"), err=False)
+    ctx.exit(0)