broken-link-checker-cli 0.1.0__py3-none-any.whl

broken_link_checker.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Check links in Markdown and HTML docs.
+
+Usage:
+    python3 src/broken_link_checker.py docs/
+    python3 src/broken_link_checker.py README.md docs/guide.md
+    python3 src/broken_link_checker.py --local-only docs/
+    python3 src/broken_link_checker.py --format json docs/
+
+For every link it reports one of OK, BROKEN, or SKIPPED, and it
+distinguishes the two broken kinds: a page that does not exist
+(page) versus a page that exists but has no such anchor (anchor).
+A link is never reported OK unless the check for it actually ran.
+
+Python standard library only. Nothing is uploaded anywhere; remote
+checks are plain HEAD/GET requests to the linked URL itself.
+"""
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+LINK_RE = re.compile(r"!?\[([^\]]*)\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+AUTOLINK_RE = re.compile(r"<(https?://[^>\s]+)>")
+HTML_LINK_RE = re.compile(
+    r"""(?:href|src)\s*=\s*["']([^"']+)["']""", re.IGNORECASE
+)
+FENCE_RE = re.compile(r"^\s*(```|~~~)")
+HEADING_RE = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$")
+SKIP_SCHEMES = {"mailto", "tel", "data", "javascript"}
+CHECKABLE_SUFFIXES = {".md", ".markdown", ".html", ".htm"}
+
+
+def slugify(text):
+    """GitHub-style heading anchor: lowercase, punctuation stripped."""
+    text = re.sub(r"<[^>]+>", "", text).strip().lower()
+    text = re.sub(r"[^a-z0-9 _-]", "", text)
+    return re.sub(r"\s+", "-", text).strip("-")
+
+
+def strip_code(text):
+    """Remove fenced code blocks and inline code spans before scanning."""
+    out = []
+    in_fence = False
+    fence = ""
+    for line in text.splitlines():
+        match = FENCE_RE.match(line)
+        if match:
+            marker = match.group(1)
+            if not in_fence:
+                in_fence, fence = True, marker
+            elif marker == fence:
+                in_fence = False
+            # Keep the line count identical so reported line numbers match
+            # the original document.
+            out.append("")
+            continue
+        if in_fence:
+            out.append("")
+        else:
+            out.append(re.sub(r"`[^`]*`", "", line))
+    return "\n".join(out)
+
+
+def extract_links(text, is_html=False):
+    """Return [(line_number, target)] in document order."""
+    found = []
+    if is_html:
+        for lineno, line in enumerate(text.splitlines(), 1):
+            for match in HTML_LINK_RE.finditer(line):
+                found.append((lineno, match.group(1)))
+        return found
+    clean = strip_code(text)
+    for lineno, line in enumerate(clean.splitlines(), 1):
+        for match in LINK_RE.finditer(line):
+            found.append((lineno, match.group(2)))
+        for match in AUTOLINK_RE.finditer(line):
+            found.append((lineno, match.group(1)))
+    return found
+
+
+def headings_of_markdown(text):
+    anchors = set()
+    for line in text.splitlines():
+        match = HEADING_RE.match(line)
+        if match:
+            anchors.add(slugify(match.group(1)))
+    return anchors
+
+
+def anchors_of_html(text):
+    ids = set(re.findall(r"""id\s*=\s*["']([^"']+)["']""", text, re.IGNORECASE))
+    ids |= set(re.findall(r"""name\s*=\s*["']([^"']+)["']""", text, re.IGNORECASE))
+    return ids
+
+
+def fetch(url, timeout, method="HEAD"):
+    request = urllib.request.Request(url, method=method)
+    request.add_header("User-Agent", "broken-link-checker-cli/1.0")
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        return response.status, response.read()
+
+
+def check_remote(url, fragment, timeout):
+    try:
+        status, _ = fetch(url, timeout, "HEAD")
+    except urllib.error.HTTPError as exc:
+        if exc.code in (400, 401, 403, 404, 405, 410, 501):
+            # Some servers refuse HEAD; a GET is the real verdict.
+            try:
+                status, body = fetch(url, timeout, "GET")
+            except urllib.error.HTTPError as err:
+                return "BROKEN", "page", f"HTTP {err.code}"
+            except Exception as err:  # network failure, not a page verdict
+                return "BROKEN", "page", str(err)
+        else:
+            return "BROKEN", "page", f"HTTP {exc.code}"
+    except Exception as err:
+        return "BROKEN", "page", str(err)
+    if status >= 400:
+        return "BROKEN", "page", f"HTTP {status}"
+    if not fragment:
+        return "OK", "", ""
+    try:
+        _, body = fetch(url, timeout, "GET")
+    except Exception as err:
+        return "BROKEN", "page", str(err)
+    text = body.decode("utf-8", "ignore")
+    if fragment in anchors_of_html(text):
+        return "OK", "", ""
+    return "BROKEN", "anchor", f"no id or name '{fragment}' on page"
+
+
+def check_local(source_file, target, fragment, timeout):
+    base = source_file.parent
+    path = (base / urllib.parse.unquote(target)).resolve()
+    if not path.exists():
+        return "BROKEN", "page", "file does not exist"
+    if not fragment:
+        return "OK", "", ""
+    if path.suffix.lower() not in CHECKABLE_SUFFIXES:
+        return "SKIPPED", "", "anchor cannot be checked in this file type"
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    anchors = (
+        headings_of_markdown(text)
+        if path.suffix.lower() in (".md", ".markdown")
+        else anchors_of_html(text)
+    )
+    if fragment in anchors:
+        return "OK", "", ""
+    return "BROKEN", "anchor", f"no heading or id '{fragment}' in file"
+
+
+def check_link(source_file, target, timeout, local_only=False):
+    """Return (status, kind, detail) for one link target."""
+    parsed = urllib.parse.urlparse(target)
+    if parsed.scheme in SKIP_SCHEMES:
+        return "SKIPPED", "", f"{parsed.scheme} link, not checked"
+    if not parsed.scheme and not parsed.path and parsed.fragment:
+        # Same-page anchor: check it against the source file itself.
+        return check_local(source_file, source_file.name, parsed.fragment, timeout)
+    if parsed.scheme in ("http", "https"):
+        if local_only:
+            return "SKIPPED", "", "remote check skipped with --local-only"
+        url = urllib.parse.urlunparse(parsed._replace(fragment=""))
+        return check_remote(url, parsed.fragment, timeout)
+    if parsed.scheme:
+        return "SKIPPED", "", f"unsupported scheme '{parsed.scheme}'"
+    return check_local(source_file, parsed.path, parsed.fragment, timeout)
+
+
+def collect_files(paths):
+    files = []
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            files.extend(
+                sorted(
+                    p
+                    for p in path.rglob("*")
+                    if p.is_file()
+                    and p.suffix.lower() in CHECKABLE_SUFFIXES
+                )
+            )
+        elif path.is_file():
+            files.append(path)
+        else:
+            raise FileNotFoundError(f"no such file or directory: {raw}")
+    return files
+
+
+def check_files(files, timeout=10, local_only=False, exclude=()):
+    results = []
+    for source in files:
+        text = source.read_text(encoding="utf-8", errors="ignore")
+        is_html = source.suffix.lower() in (".html", ".htm")
+        for lineno, target in extract_links(text, is_html=is_html):
+            if any(re.search(pattern, target) for pattern in exclude):
+                results.append(
+                    {
+                        "file": str(source),
+                        "line": lineno,
+                        "url": target,
+                        "status": "SKIPPED",
+                        "kind": "",
+                        "detail": "excluded",
+                    }
+                )
+                continue
+            status, kind, detail = check_link(
+                source, target, timeout, local_only=local_only
+            )
+            results.append(
+                {
+                    "file": str(source),
+                    "line": lineno,
+                    "url": target,
+                    "status": status,
+                    "kind": kind,
+                    "detail": detail,
+                }
+            )
+    return results
+
+
+def summarize(results):
+    counts = {"OK": 0, "BROKEN": 0, "SKIPPED": 0}
+    for item in results:
+        counts[item["status"]] += 1
+    return counts
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Check links in Markdown and HTML docs."
+    )
+    parser.add_argument("paths", nargs="+", help="files or directories to check")
+    parser.add_argument("--timeout", type=float, default=10)
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument(
+        "--local-only", action="store_true", help="skip http(s) links"
+    )
+    parser.add_argument(
+        "--exclude", action="append", default=[], help="regex: skip matching URLs"
+    )
+    args = parser.parse_args(argv)
+    try:
+        files = collect_files(args.paths)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    results = check_files(
+        files,
+        timeout=args.timeout,
+        local_only=args.local_only,
+        exclude=args.exclude,
+    )
+    counts = summarize(results)
+    if args.format == "json":
+        print(json.dumps({"counts": counts, "results": results}, indent=2))
+    else:
+        for item in results:
+            line = f"{item['file']}:{item['line']}: {item['url']} -> {item['status']}"
+            if item["kind"]:
+                line += f" ({item['kind']})"
+            if item["detail"]:
+                line += f" ({item['detail']})"
+            print(line)
+        print(
+            f"{counts['OK']} ok, {counts['BROKEN']} broken, "
+            f"{counts['SKIPPED']} skipped"
+        )
+    return 1 if counts["BROKEN"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

broken_link_checker_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: broken-link-checker-cli
+Version: 0.1.0
+Summary: Check links in Markdown and HTML docs against real pages — and tell page failures apart from anchor failures.
+Author: Haider Ali
+License: MIT
+Project-URL: Homepage, https://github.com/haiderstudio/broken-link-checker-cli
+Project-URL: Repository, https://github.com/haiderstudio/broken-link-checker-cli
+Project-URL: Issues, https://github.com/haiderstudio/broken-link-checker-cli/issues
+Keywords: links,markdown,html,docs,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# broken-link-checker-cli
+
+Check links in Markdown and HTML docs against real pages — and tell page failures apart from anchor failures.
+
+[![CI](https://github.com/haiderstudio/broken-link-checker-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/haiderstudio/broken-link-checker-cli/actions/workflows/ci.yml) [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-yellow.svg)](LICENSE)
+
+## What it does
+
+`broken-link-checker` scans `.md`, `.markdown`, and `.html` files for links and checks each one for real:
+
+- Local links: the target file must exist. If the link has an anchor, the target Markdown heading (GitHub-style slug) or HTML `id`/`name` must exist too.
+- Remote links: the URL must answer (HEAD, falling back to GET where a server refuses HEAD). If the link has an anchor, the fetched page must carry that `id` or `name`.
+- Every result is one of three statuses, with the broken kind named: `BROKEN (page)` for a missing page, `BROKEN (anchor)` for a page that exists without that anchor. A link is never reported OK unless its check actually ran.
+- Links inside fenced code blocks and inline code spans are ignored, so code samples never produce false failures.
+- Exit code 0 means no broken links, 1 means at least one broken link, 2 means a usage error such as a missing path.
+
+## What it does NOT do
+
+- It does not guess. If an anchor cannot be checked (for example, an anchor on a PDF), the link is reported `SKIPPED` with the reason, never OK.
+- It does not check `mailto:`, `tel:`, or other non-web schemes — those are reported `SKIPPED`, not broken.
+- It does not follow JavaScript-rendered pages, log in to sites, or rewrite any file. It only reads and reports.
+- It does not send your docs anywhere. Remote checks are plain requests to the linked URL itself; everything else runs locally.
+
+## Who it is for
+
+Anyone who maintains docs, a README collection, or a static site and wants a broken link caught before a reader finds it — in CI, or as a one-off check before publishing.
+
+## Install
+
+Python standard library only — no packages to download. Clone the repo and run it in place:
+
+```sh
+git clone https://github.com/haiderstudio/broken-link-checker-cli.git
+cd broken-link-checker-cli
+```
+
+## Usage
+
+Check a directory (scanned recursively) or individual files:
+
+```sh
+python3 src/broken_link_checker.py docs/
+python3 src/broken_link_checker.py README.md docs/guide.md
+```
+
+Real output from the bundled examples (one link is deliberately broken):
+
+```text
+examples/sample-docs.md:3: other-page.md -> OK
+examples/sample-docs.md:5: #sample-docs -> OK
+examples/sample-docs.md:8: missing-page.md -> BROKEN (page) (file does not exist)
+2 ok, 1 broken, 0 skipped
+```
+
+Useful flags:
+
+```sh
+# Skip remote checks entirely (local files only)
+python3 src/broken_link_checker.py --local-only docs/
+
+# Machine-readable output
+python3 src/broken_link_checker.py --format json docs/
+
+# Skip URLs matching a pattern (repeatable)
+python3 src/broken_link_checker.py --exclude 'example\.com' docs/
+```
+
+## Examples
+
+Check only local links in a docs folder, so the run works offline:
+
+```sh
+python3 src/broken_link_checker.py --local-only docs/
+```
+
+Check one file and get JSON for a CI step:
+
+```sh
+python3 src/broken_link_checker.py --format json README.md
+```
+
+Run the bundled example (expect 2 ok, 1 broken, exit code 1):
+
+```sh
+sh examples/run-example.sh
+```
+
+## How it is tested
+
+```sh
+python3 tests/test_broken_link_checker.py
+```
+
+The tests use only the standard library's `unittest`. Remote checks are exercised against a real HTTP server started by the tests on localhost — never against the public internet — covering a good page, a 404 page, a good anchor, and a missing anchor, plus local files, same-page anchors, skipped schemes, CLI exit codes, and JSON counts.
+
+## Contributing
+
+Small, focused improvements are welcome. Open an issue first for anything larger than a typo, keep the standard-library-only rule, and run the tests before opening a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). This is original work, built fresh for this repo.

broken_link_checker_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+broken_link_checker.py,sha256=QVI3f1OnbGo8yhS5S__xRu_8DPTSJONiwMp9j73Zq5Q,9784
+broken_link_checker_cli-0.1.0.dist-info/licenses/LICENSE,sha256=mTjYlQM7htiV7thgBkBwT0woURqRpTJG1eWK1Logfl8,1067
+broken_link_checker_cli-0.1.0.dist-info/METADATA,sha256=kCNGNdt95QB07dTlGuYXoX5XezXcKfjBSsJU9s5NHGo,5087
+broken_link_checker_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+broken_link_checker_cli-0.1.0.dist-info/entry_points.txt,sha256=CpDyS_KVAhLiA0dX8ixq917d6MkQ8VR6QmisCxamYo4,65
+broken_link_checker_cli-0.1.0.dist-info/top_level.txt,sha256=Oh9VmlsyItxmwuSnVYR63BAFKMXrABn9RxtEWLXUaug,20
+broken_link_checker_cli-0.1.0.dist-info/RECORD,,

broken_link_checker_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

broken_link_checker_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+broken-link-checker = broken_link_checker:main

broken_link_checker_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haider Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

broken_link_checker_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+broken_link_checker