fix(links): honor HTML base URLs and repair six blog posts

Author: Coding-Dev-Tools

.hermes/linkcheck.py

@@ -24,17 +24,36 @@ def __init__(self):
         super().__init__(convert_charrefs=True)
         self.links = []
         self.anchors = set()
+        self.base_href = None
 
     def handle_starttag(self, tag, attrs):
         for name, value in attrs:
+            if tag == "base" and name == "href" and self.base_href is None:
+                # The first base with href wins, including an empty href.
+                self.base_href = value or ""
             if value is None:
                 continue
-            if name in {"href", "src"}:
+            # A base URL is a resolution directive, not a fetched resource.
+            if tag != "base" and name in {"href", "src"}:
                 self.links.append(value)
             if name == "id" or (tag == "a" and name == "name"):
                 self.anchors.add(value)
 
 
+def document_base_url(parser: PageLinks, document_url: str) -> str:
+    """Resolve the first HTML base href against the document's own URL."""
+    if parser.base_href is None:
+        return document_url
+    try:
+        base_url = urljoin(document_url, parser.base_href.strip(" \t\n\r\f"))
+        if urlsplit(base_url).scheme.lower() in {"data", "javascript"}:
+            return document_url
+        return base_url
+    except ValueError:
+        # Invalid bases fall back to the document URL, as in browsers.
+        return document_url
+
+
 def collect_html_files(root_dir: str) -> set[str]:
     """Walk root_dir and return set of all .html file paths."""
     files = set()
@@ -102,8 +121,9 @@ def check_links(root_dir: str, verbose: bool = False) -> int:
 
     site = urlsplit(SITE_URL)
     for source_rel, parser in sorted(pages.items()):
+        base_url = document_base_url(parser, SITE_URL + source_rel)
         for link in parser.links:
-            target = urlsplit(urljoin(SITE_URL + source_rel, link))
+            target = urlsplit(urljoin(base_url, link))
             # Other projects on the same host are external to this artifact.
             if target.scheme not in {"http", "https"} or target.netloc != site.netloc:
                 continue

blog/apicontractguardian-git-branch-openapi-diff-pr-review.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
- <base href="/devforge/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>API Contract Guardian: Git-Branch-Aware OpenAPI Diffing for Every PR | DevForge</title>
  <meta name="description" content="Stop manually reviewing OpenAPI spec changes. API Contract Guardian diffs specs between git branches — detect breaking changes, generate migration guides, and gate PRs automatically. Works with feature branches, release tags, and monorepo paths.">

blog/click-to-mcp-three-distribution-channels.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
- <base href="/devforge/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Three Ways to Distribute Your CLI to AI Agents: MCP, Claude Code Plugins, and Agent Skills | DevForge</title>
  <meta name="description" content="click-to-mcp now reaches AI agents through three distribution channels — MCP servers, Claude Code plugins, and Agent Skills. Learn how to package your CLI for every agent platform with zero code changes.">

blog/deadcode-remove-dead-code-nextjs-app-router.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <base href="/devforge/">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Find and Remove Dead Code in Next.js App Router Projects | DevForge</title>
   <meta name="description" content="Dead code accumulates fast in Next.js App Router projects. Learn how DeadCode CLI finds unused exports, dead routes, orphaned CSS, and unreferenced components — and removes them safely.">

blog/json2sql-cicd-automated-database-seeding.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
- <base href="/devforge/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>json2sql in CI/CD: Automate Database Seeding from JSON Fixtures | DevForge</title>
  <meta name="description" content="Stop committing .sql seed files. Use json2sql in GitHub Actions to generate INSERT statements from JSON fixtures on every CI run — deterministic test databases, zero manual SQL, and pipe-friendly workflows for PostgreSQL, MySQL, and SQLite.">

blog/saas-churn-predictor-launch.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
- <base href="/devforge/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>SaaS Churn Predictor v1.0: Stripe-Native Churn Scoring for Founders | DevForge</title>
  <meta name="description" content="SaaS Churn Predictor connects to Stripe in 60 seconds and scores every customer 0-100 on churn risk. Not a CS platform — a prediction engine that tells you who to save this week. 597 tests, 135 suites, free tier available.">

blog/schemaforge-convert-prisma-to-drizzle-migration-guide.html

@@ -2,7 +2,6 @@
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <base href="/devforge/">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Migrate from Prisma to Drizzle ORM: Step-by-Step with SchemaForge | DevForge</title>
   <meta name="description" content="Migrating from Prisma to Drizzle ORM? SchemaForge converts your schema automatically — models, relations, enums, indexes — in one command. No manual rewriting.">

tests/test_linkcheck_fragments.py

@@ -7,7 +7,7 @@
 import pytest
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / ".hermes"))
-from linkcheck import check_links
+from linkcheck import PageLinks, SITE_URL, check_links, document_base_url
 
 
 @pytest.mark.parametrize("link", ["#missing", "target.html#missing", "target.html?q=1#missing"])
@@ -63,3 +63,61 @@ def test_github_compatibility_wrapper_reports_broken_links(tmp_path):
     result = subprocess.run([sys.executable, str(wrapper), str(tmp_path), "--exit-code"], capture_output=True)
     assert result.returncode == 1
     assert b"missing fragment" in result.stdout
+
+
+def test_root_base_changes_nested_stylesheet_resolution(tmp_path):
+    blog = tmp_path / "blog"
+    blog.mkdir()
+    (blog / "post.html").write_text('<base href="/devforge/"><link href="blog.css" rel="stylesheet">')
+    (blog / "blog.css").write_text("body {}")
+    # A browser requests /devforge/blog.css, not /devforge/blog/blog.css.
+    assert check_links(str(tmp_path)) == 1
+    (tmp_path / "blog.css").write_text("body {}")
+    assert check_links(str(tmp_path)) == 0
+
+
+def test_first_base_href_wins_and_is_not_a_resource_link(tmp_path):
+    (tmp_path / "blog").mkdir()
+    (tmp_path / "assets").mkdir()
+    (tmp_path / "blog/post.html").write_text(
+        '<base target="_blank"><base href="../assets/">'
+        '<base href="/devforge/missing/"><a href="target.html#ok">target</a>'
+    )
+    (tmp_path / "assets/target.html").write_text('<h1 id="ok">Heading</h1>')
+    # There is no assets/index.html. The base href itself does not fetch one.
+    assert check_links(str(tmp_path)) == 0
+
+
+def test_fragment_uses_base_target_instead_of_source_page(tmp_path):
+    (tmp_path / "blog").mkdir()
+    (tmp_path / "blog/post.html").write_text(
+        '<base href="../target.html"><h1 id="section">Source</h1><a href="#section">target</a>'
+    )
+    (tmp_path / "target.html").write_text("No target anchor")
+    assert check_links(str(tmp_path)) == 1
+    (tmp_path / "target.html").write_text('<h1 id="section">Target</h1>')
+    assert check_links(str(tmp_path)) == 0
+
+
+def test_external_base_makes_relative_urls_external(tmp_path):
+    (tmp_path / "index.html").write_text(
+        '<base href="https://example.com/assets/"><a href="missing.html">external</a>'
+        '<a href="https://coding-dev-tools.github.io/devforge/target.html#ok">local</a>'
+    )
+    (tmp_path / "target.html").write_text('<h1 id="ok">Target</h1>')
+    assert check_links(str(tmp_path)) == 0
+
+
+@pytest.mark.parametrize("href", ["", "data:text/html,example", "javascript:alert(1)", "http://[invalid"])
+def test_empty_or_disallowed_first_base_falls_back_without_using_second_base(href):
+    parser = PageLinks()
+    parser.feed(f'<base href="{href}"><base href="/devforge/ignored/">')
+    document_url = SITE_URL + "blog/post.html"
+    assert document_base_url(parser, document_url) == document_url
+
+
+def test_escaped_base_example_does_not_change_document_base():
+    parser = PageLinks()
+    parser.feed('<code>&lt;base href="/devforge/"&gt;</code>')
+    document_url = SITE_URL + "blog/post.html"
+    assert document_base_url(parser, document_url) == document_url