yak(link-validator-never-sees-compiled-html-internal-link-validation-is-vacuous-ddd1): Link validator never sees compiled HTML — internal-link validation is vacuous

2026-10-28 22:08:45 +00:00
parent 4e7798c906
commit c04d8c856c
8 changed files with 175 additions and 19 deletions
@@ -1,6 +1,12 @@
 defmodule Blogex.LinkValidator do
  @moduledoc """
-  Validates internal blog link semantics in markdown post bodies.
+  Validates internal blog link semantics in compiled post bodies.
+
+  Post bodies reach this module as HTML: `Blogex.Blog` validates them in
+  `@before_compile`, after NimblePublisher has rendered the markdown. Markdown
+  link syntax is still understood so bodies and snippets can be validated
+  before rendering, but the HTML `<a href="…">` anchors are the ones that
+  matter in the real pipeline.

  Checks that internal links follow the pattern `/blog/{blog_id}/{slug}`
  where `blog_id` is a valid blog identifier and `slug` matches the
@@ -50,21 +56,25 @@ defmodule Blogex.LinkValidator do
  @slug_regex ~r/^[a-z0-9]+(-[a-z0-9]+)*$/

  @doc """
-  Extracts internal blog links from a markdown body.
+  Extracts internal blog links from a post body.

-  Returns a list of link paths (strings) that match the pattern
-  `/blog/{engineering|releases}/{slug}`. External links and non-blog
-  internal links are ignored.
+  Returns a list of link paths (strings) that look like `/blog/…` links.
+  External links and non-blog internal links are ignored. Blog IDs and slugs
+  are *not* judged here — `validate_link/1` classifies those.

-  Handles both markdown link syntax `[text](url)` and HTML `<a href="url">`.
-  (Post bodies are HTML, rendered by NimblePublisher at compile time.)
+  HTML anchors are read with Floki, so attribute order, quoting and extra
+  attributes do not matter. Markdown link syntax `[text](url)` is extracted
+  too (raw markdown bodies and snippets), and the two scans are merged.

  ## Examples

      iex> extract_links("[link](/blog/engineering/post)")
      ["/blog/engineering/post"]

-      iex> extract_links("<p><a href=\"/blog/engineering/post\">link</a></p>")
+      iex> extract_links("<p><a href=\\"/blog/engineering/post\\">link</a></p>")
+      ["/blog/engineering/post"]
+
+      iex> extract_links("<p><a class=\\"x\\" href='/blog/engineering/post'>link</a></p>")
      ["/blog/engineering/post"]

      iex> extract_links("See [GitHub](https://github.com)")
@@ -72,21 +82,24 @@ defmodule Blogex.LinkValidator do
  """
  @spec extract_links(String.t()) :: [String.t()]
  def extract_links(body) when is_binary(body) do
-    markdown_links =
-      ~r/\[([^\]]+)\]\(([^)]+)\)/
-      |> Regex.scan(body)
-      |> Enum.map(fn [_, _, path] -> path end)
-
-    html_links =
-      ~r/<a\s+href=["']([^"']*)["']/i
-      |> Regex.scan(body)
-      |> Enum.map(fn [_, path] -> path end)
-
-    (markdown_links ++ html_links)
+    (markdown_links(body) ++ html_links(body))
    |> Enum.uniq()
    |> Enum.filter(&internal_blog_link?/1)
  end

+  defp markdown_links(body) do
+    ~r/\[([^\]]+)\]\(([^)]+)\)/
+    |> Regex.scan(body)
+    |> Enum.map(fn [_, _, path] -> path end)
+  end
+
+  defp html_links(body) do
+    body
+    |> Floki.parse_document!()
+    |> Floki.find("a[href]")
+    |> Enum.flat_map(&Floki.attribute(&1, "href"))
+  end
+
  defp internal_blog_link?(path) do
    case parse_blog_link(path) do
      {_, _} -> true
@@ -38,6 +38,7 @@ defmodule Blogex.MixProject do
  defp deps do
    [
      {:nimble_publisher, "~> 2.0"},
+      {:floki, "~> 0.38"},
      {:makeup_elixir, ">= 0.0.0"},
      {:makeup_erlang, ">= 0.0.0"},
      {:phoenix, "~> 1.7"},
@@ -4,6 +4,7 @@
  "earmark_parser": {:hex, :earmark_parser, "1.4.44", "f20830dd6b5c77afe2b063777ddbbff09f9759396500cdbe7523efd58d7a339c", [:mix], [], "hexpm", "4778ac752b4701a5599215f7030989c989ffdc4f6df457c5f36938cc2d2a2750"},
  "ex_crap": {:hex, :ex_crap, "0.1.1", "c1770e7ce1843f304a27f5d32bfa867a340140e337684ee1929c770b2499f884", [:mix], [{:boundary, "~> 0.10", [hex: :boundary, repo: "hexpm", optional: false]}], "hexpm", "ada5d59bce442c1a8a987cb5328cbf4469fb56eb8d04641886f2199569a75b12"},
  "ex_doc": {:hex, :ex_doc, "0.40.1", "67542e4b6dde74811cfd580e2c0149b78010fd13001fda7cfeb2b2c2ffb1344d", [:mix], [{:earmark_parser, "~> 1.4.44", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "bcef0e2d360d93ac19f01a85d58f91752d930c0a30e2681145feea6bd3516e00"},
+  "floki": {:hex, :floki, "0.38.4", "10f98971e892aed2c2f1b3a0f928e488e3797e1c6dd3dfd98db40b14e9a78bcf", [:mix], [], "hexpm", "bdb34645eee8e79845c7edaca2d4099a52804ee4d4a3ecc683a69451f0244973"},
  "jason": {:hex, :jason, "1.4.5", "2e3a008590b0b8d7388c20293e9dcc9cf3e5d642fd2a114e4cbbb52e595d940a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0 or ~> 3.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "b0c823996102bcd0239b3c2444eb00409b72f6a140c1950bc8b457d836b30684"},
  "makeup": {:hex, :makeup, "1.2.2", "882d46dc0905e9ff7abf2aab61a7e6b3dcc555533977d8a23b06019e6c89ac94", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "9a1a24e5b343b8ae16abea0822c10a6f75da27af7fa802ada5251f7579bfccfa"},
  "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
@@ -0,0 +1,7 @@
+%{
+  title: "Internal Link Post",
+  author: "Test Author",
+  description: "A post that links to another post"
+}
+---
+This post links to [hello world](/blog/engineering/hello-world) in its body.
@@ -93,4 +93,38 @@ defmodule Blogex.BlogIntegrationTest do
      File.rm!(tmp_file)
    end
  end
+
+  describe "validation sees compiled post bodies" do
+    # `_validate_links/2` runs on `post.body` *after* NimblePublisher rendered
+    # the markdown, so validation only works if extraction reads the compiled
+    # HTML. This pins that contract against a real compiled body: if
+    # extraction ever goes back to scanning markdown syntax only, it fails.
+    test "extract_links finds internal links in a compiled post body" do
+      tmp_file = Path.join(System.tmp_dir!(), "test_blog_compiled_body.ex")
+
+      File.write!(tmp_file, """
+      defmodule TestBlogCompiledBody do
+        use Blogex.Blog,
+          blog_id: :test,
+          app: :blogex,
+          from: "priv/blog/test/2026/01-03-internal-link-post.md",
+          title: "Test Blog",
+          base_path: "/blog/test"
+      end
+      """)
+
+      [{TestBlogCompiledBody, _bytecode}] = Code.compile_file(tmp_file, __ENV__.file)
+
+      # `apply/3`: the module is compiled at runtime, so a static call would
+      # warn ("module is not available") on every test compile.
+      [post] = apply(TestBlogCompiledBody, :all_posts, [])
+
+      # The markdown source is `[hello world](/blog/engineering/hello-world)`.
+      assert post.body =~ "/blog/engineering/hello-world"
+
+      assert "/blog/engineering/hello-world" in Blogex.LinkValidator.extract_links(post.body)
+
+      File.rm!(tmp_file)
+    end
+  end
 end
@@ -29,6 +29,21 @@ defmodule Blogex.LinkValidatorTest do
      assert LinkValidator.extract_links(body) == ["/blog/engineering/tag/pi.dev"]
    end

+    # HTML anchors are not "the href right after <a (" - they are whatever the
+    # renderer emits. Pinned with the shapes a hand-rolled scan misses.
+    test "extracts internal blog links whatever the anchor's attributes look like" do
+      body =
+        ~s(<p><a class="post-link" href="/blog/engineering/first">first</a>) <>
+          ~s( <a href=/blog/releases/second>second</a>) <>
+          ~s( <a data-x="1" aria-label="third" href='/blog/engineering/third'>third</a></p>)
+
+      assert LinkValidator.extract_links(body) == [
+               "/blog/engineering/first",
+               "/blog/releases/second",
+               "/blog/engineering/third"
+             ]
+    end
+
    test "ignores external links" do
      body = "See [GitHub](https://github.com) and [internal](/blog/engineering/post)."

@@ -157,6 +172,12 @@ defmodule Blogex.LinkValidatorTest do
      assert LinkValidator.validate_link("/blog/engineering/tag/pi.dev#top") == :ok
    end

+    # Tags are user-defined: the documented rule restricts *slugs*, not tags.
+    test "accepts tag links with dots and capitals" do
+      assert LinkValidator.validate_link("/blog/engineering/tag/pi.dev") == :ok
+      assert LinkValidator.validate_link("/blog/engineering/tag/Pi.dev") == :ok
+    end
+
    test "rejects tag page link with empty tag" do
      assert LinkValidator.validate_link("/blog/engineering/tag/") ==
               {:error, "empty tag in tag link"}
@@ -267,5 +288,40 @@ defmodule Blogex.LinkValidatorTest do
               ]
             }
    end
+
+    # `_validate_links/2` hands this module `post.body`, which NimblePublisher
+    # already rendered to HTML, so failure reporting has to work on HTML bodies.
+    # These are the two reports the compile-time integration tests depend on.
+    test "reports an unknown blog ID in an HTML body" do
+      body = ~s(<p><a href="/blog/unknown/broken">bad</a></p>)
+
+      assert LinkValidator.validate_body(body, :engineering, post_id: "html-post") == {
+               :error,
+               [
+                 {
+                   1,
+                   "/blog/unknown/broken",
+                   "unknown blog ID: unknown",
+                   post_id: "html-post"
+                 }
+               ]
+             }
+    end
+
+    test "reports an invalid slug in an HTML body" do
+      body = ~s(<p><a href="/blog/engineering/My-Post">bad</a></p>)
+
+      assert LinkValidator.validate_body(body, :engineering, post_id: "html-post") == {
+               :error,
+               [
+                 {
+                   1,
+                   "/blog/engineering/My-Post",
+                   "slug must be lowercase alphanumeric with hyphens: My-Post",
+                   post_id: "html-post"
+                 }
+               ]
+             }
+    end
  end
 end