broken-link-checker-cli 0.1.0__tar.gz

broken_link_checker_cli-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "broken-link-checker-cli"
+version = "0.1.0"
+description = "Check links in Markdown and HTML docs against real pages — and tell page failures apart from anchor failures."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Haider Ali" }]
+keywords = ["links", "markdown", "html", "docs", "cli", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Quality Assurance",
+]
+urls = { Homepage = "https://github.com/haiderstudio/broken-link-checker-cli", Repository = "https://github.com/haiderstudio/broken-link-checker-cli", Issues = "https://github.com/haiderstudio/broken-link-checker-cli/issues" }
+
+[project.scripts]
+broken-link-checker = "broken_link_checker:main"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools]
+py-modules = ["broken_link_checker"]

broken_link_checker_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

broken_link_checker_cli-0.1.0/src/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/src/broken_link_checker_cli.egg-info/PKG-INFO

@@ -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/src/broken_link_checker_cli.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/broken_link_checker.py
+src/broken_link_checker_cli.egg-info/PKG-INFO
+src/broken_link_checker_cli.egg-info/SOURCES.txt
+src/broken_link_checker_cli.egg-info/dependency_links.txt
+src/broken_link_checker_cli.egg-info/entry_points.txt
+src/broken_link_checker_cli.egg-info/top_level.txt
+tests/test_broken_link_checker.py

broken_link_checker_cli-0.1.0/src/broken_link_checker_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

broken_link_checker_cli-0.1.0/src/broken_link_checker_cli.egg-info/entry_points.txt

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

broken_link_checker_cli-0.1.0/src/broken_link_checker_cli.egg-info/top_level.txt

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

broken_link_checker_cli-0.1.0/tests/test_broken_link_checker.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Tests for broken_link_checker. Run: python3 tests/test_broken_link_checker.py
+
+No third-party dependencies. Remote checks run against a real local
+HTTP server started by the tests, never against the public internet.
+"""
+
+import json
+import subprocess
+import sys
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+from broken_link_checker import (  # noqa: E402
+    check_files,
+    check_link,
+    extract_links,
+    main,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+CLI = ROOT / "src" / "broken_link_checker.py"
+
+
+class FixtureHandler(BaseHTTPRequestHandler):
+    def _send(self, code, body=b""):
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(body)
+
+    def do_HEAD(self):
+        self._send(200 if self.path.split("#")[0] in ("/ok", "/page") else 404)
+
+    def do_GET(self):
+        if self.path == "/ok":
+            self._send(200, b"ok")
+        elif self.path == "/page":
+            self._send(200, b'<h2 id="intro">Intro</h2>')
+        else:
+            self._send(404, b"missing")
+
+    def log_message(self, *args):
+        pass
+
+
+class ServerMixin(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FixtureHandler)
+        cls.port = cls.server.server_address[1]
+        cls.thread = threading.Thread(
+            target=cls.server.serve_forever, daemon=True
+        )
+        cls.thread.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def base(self):
+        return f"http://127.0.0.1:{self.port}"
+
+
+class TestExtract(unittest.TestCase):
+    def test_code_blocks_and_inline_code_are_ignored(self):
+        text = (
+            "```\n[hidden](gone.md)\n```\n"
+            "Real [link](here.md) and `code [fake](gone.md)`\n"
+        )
+        self.assertEqual(extract_links(text), [(4, "here.md")])
+
+    def test_autolink_found(self):
+        self.assertEqual(
+            extract_links("see <https://example.com/x> now"),
+            [(1, "https://example.com/x")],
+        )
+
+
+class TestLocal(ServerMixin):
+    def test_good_file_good_anchor_missing_file_missing_anchor(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "target.md").write_text("# Getting Started\n\nBody.\n")
+            (root / "doc.md").write_text(
+                "[ok](target.md) [anchor](target.md#getting-started) "
+                "[gone](nope.md) [bad anchor](target.md#nope)\n"
+            )
+            results = check_files([root / "doc.md"])
+            by_url = {r["url"]: r for r in results}
+            self.assertEqual(by_url["target.md"]["status"], "OK")
+            self.assertEqual(
+                by_url["target.md#getting-started"]["status"], "OK"
+            )
+            self.assertEqual(by_url["nope.md"]["status"], "BROKEN")
+            self.assertEqual(by_url["nope.md"]["kind"], "page")
+            self.assertEqual(by_url["target.md#nope"]["status"], "BROKEN")
+            self.assertEqual(by_url["target.md#nope"]["kind"], "anchor")
+
+    def test_same_page_anchor_and_mailto_skipped(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            source = root / "doc.md"
+            source.write_text("# Top\n\n[here](#top) [mail](mailto:a@b.c)\n")
+            results = check_files([source])
+            by_url = {r["url"]: r for r in results}
+            self.assertEqual(by_url["#top"]["status"], "OK")
+            self.assertEqual(by_url["mailto:a@b.c"]["status"], "SKIPPED")
+
+
+class TestRemote(ServerMixin):
+    def test_page_ok_page_broken_anchor_ok_anchor_broken(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            source = Path(tmp) / "doc.md"
+            source.write_text("x\n")
+            base = self.base()
+            self.assertEqual(
+                check_link(source, f"{base}/ok", 5)[0], "OK"
+            )
+            status, kind, _ = check_link(source, f"{base}/missing", 5)
+            self.assertEqual((status, kind), ("BROKEN", "page"))
+            self.assertEqual(
+                check_link(source, f"{base}/page#intro", 5)[0], "OK"
+            )
+            status, kind, _ = check_link(source, f"{base}/page#gone", 5)
+            self.assertEqual((status, kind), ("BROKEN", "anchor"))
+
+    def test_local_only_skips_remote(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            source = Path(tmp) / "doc.md"
+            source.write_text("x\n")
+            status, _, _ = check_link(
+                source, f"{self.base()}/missing", 5, local_only=True
+            )
+            self.assertEqual(status, "SKIPPED")
+
+
+class TestCli(unittest.TestCase):
+    def test_exit_zero_when_clean_exit_one_when_broken_json_counts(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "good.md").write_text("[ok](good.md)\n")
+            (root / "bad.md").write_text("[gone](nope.md)\n")
+            clean = subprocess.run(
+                [sys.executable, str(CLI), str(root / "good.md")],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(clean.returncode, 0)
+            self.assertIn("1 ok, 0 broken", clean.stdout)
+            broken = subprocess.run(
+                [
+                    sys.executable,
+                    str(CLI),
+                    "--format",
+                    "json",
+                    str(root / "bad.md"),
+                ],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(broken.returncode, 1)
+            data = json.loads(broken.stdout)
+            self.assertEqual(data["counts"], {"OK": 0, "BROKEN": 1, "SKIPPED": 0})
+            missing = subprocess.run(
+                [sys.executable, str(CLI), str(root / "absent")],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(missing.returncode, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()