open_blog 0.1.0

data/lib/open_blog/doctor/javascript.rb

@@ -0,0 +1,57 @@
+module OpenBlog
+  class Doctor
+    module Javascript
+      private
+
+      def javascript
+        layout = layout_source
+        tag = layout.match(/javascript_(importmap_tags|include_tag)\s*(?:\(?\s*)(?:["']([^"']+)["'])?/)
+        return [ "error", "The blog layout has no recognizable JavaScript entry point." ] unless tag
+        if tag[2].nil? && layout[tag.end(0)..].match?(/\A[^%\s)]/)
+          return [ "warning", "Dynamic JavaScript entry point cannot be verified statically." ]
+        end
+        entry = tag[2] || "application"
+        maps = javascript_map_source(layout)
+        pins = maps.scan(/\bpin\s+["']([^"']+)["']\s*,\s*to:\s*["']([^"']+)["']/).to_h
+        source = javascript_tree(entry, pins: pins)
+        return [ "error", "JavaScript entry point #{entry} was not found." ] if source.empty?
+        importmap = tag[1] == "importmap_tags"
+        loaders = source.scan(/(?:eager|lazy)LoadControllersFrom\s*\(\s*["']([^"']+)["']/).flatten
+        missing = Dir[Engine.root.join("app/assets/javascripts/open_blog/controllers/*_controller.js")].filter_map do |path|
+          file = File.basename(path)
+          name = "open-blog--#{file.delete_suffix('_controller.js').tr('_', '-')}"
+          local = @root.join("app/javascript/controllers/open_blog/#{file}")
+          next name unless local.file?
+          explicit = source.match?(/\.register\s*\(\s*["']#{Regexp.escape(name)}["']/) && source.include?("open_blog/#{file.delete_suffix('.js')}")
+          automatic = importmap && loaders.any? do |prefix|
+            prefix == "controllers" && maps.match?(/pin_all_from[^\n]*controllers[^\n]*under:\s*["']controllers["']/)
+          end
+          name unless explicit || automatic
+        end
+        missing.any? ? [ "error", "Register controllers reachable from #{entry}: #{missing.join(', ')}." ] : [ "ok", "All blog controllers are reachable from #{entry}." ]
+      end
+
+      def javascript_map_source(layout)
+        custom = layout[/importmap:\s*([\w.]+)/, 1]
+        return read("config/importmap.rb") if custom.nil? || custom == "Rails.application.importmap"
+        name = custom.split(".").last.sub(/\Aimportmap_/, "")
+        read("config/importmap_#{name}.rb")
+      end
+
+      def javascript_tree(specifier, from: nil, seen: [], pins: {})
+        specifier = pins.fetch(specifier, specifier)
+        base = if specifier.start_with?(".") && from
+          from.dirname.join(specifier)
+        else
+          @root.join("app/javascript", specifier)
+        end
+        file = [ base, Pathname("#{base}.js"), base.join("index.js") ].find(&:file?)
+        return "" unless file && !seen.include?(file.cleanpath.to_s)
+        seen << file.cleanpath.to_s
+        source = file.read
+        imports = source.scan(/\bimport\s+(?:[^;\n]*?\s+from\s+)?["']([^"']+)["']/).flatten
+        source + imports.map { |name| javascript_tree(name, from: file, seen: seen, pins: pins) }.join("\n")
+      end
+    end
+  end
+end

data/lib/open_blog/doctor.rb

@@ -0,0 +1,177 @@
+require "net/http"
+require "securerandom"
+require "timeout"
+require_relative "doctor/files"
+require_relative "doctor/javascript"
+
+module OpenBlog
+  class Doctor
+    include Files
+    include Javascript
+
+    CHECKS = { "Configuration" => :configuration, "Migrations" => :migrations, "Route" => :route,
+      "Views" => :views, "Theme" => :theme, "JavaScript" => :javascript, "Authentication" => :authentication,
+      "Rate limit" => :rate_limit, "Jobs" => :jobs, "Storage" => :storage, "Policy pages" => :policy_pages,
+      "Records" => :records, "Declarations" => :declarations }.freeze
+    TABLES = %w[open_blog_authors open_blog_categories open_blog_series open_blog_images open_blog_posts
+      open_blog_api_tokens open_blog_pages open_blog_page_views open_blog_faqs open_blog_tags open_blog_taggings open_blog_redirects open_blog_revisions
+      open_blog_approvals open_blog_publications open_blog_baselines open_blog_connection_declarations
+      active_storage_blobs active_storage_attachments active_storage_variant_records action_text_rich_texts].freeze
+
+    def self.run(application: Rails.application, config: OpenBlog.config, http_get: nil)
+      new(application: application, config: config, http_get: http_get).run
+    end
+
+    def initialize(application:, config:, http_get:)
+      @application, @config, @http_get = application, config, http_get
+      @root = application.root
+    end
+
+    def run
+      CHECKS.map do |name, method|
+        status, message = send(method)
+        { name: name, status: status, message: message }
+      rescue StandardError => error
+        { name: name, status: "error", message: "Check unavailable: #{error.class}: #{error.message}" }
+      end
+    end
+
+    private
+
+    def configuration
+      @config.validate!
+      values = [ @config.site_name, @config.default_author&.dig(:name), @config.publisher&.dig(:name) ]
+      return [ "warning", "Replace installer placeholder names." ] if (values & [ "Example", "Ada Example" ]).any?
+      [ "ok", "Required configuration is present." ]
+    rescue ConfigurationError => error
+      [ "error", error.message ]
+    end
+
+    def missing_tables
+      @missing_tables ||= TABLES.reject { |name| ActiveRecord::Base.connection.data_source_exists?(name) }
+    end
+
+    def migrations
+      return [ "error", "Missing tables: #{missing_tables.join(', ')}. Run the installed migrations." ] if missing_tables.any?
+      pool = ActiveRecord::Base.connection_pool
+      paths = @application.paths["db/migrate"].existent
+      context = ActiveRecord::MigrationContext.new(paths, pool.schema_migration, pool.internal_metadata)
+      expected = Dir[Engine.root.join("db/migrate/*.rb")].map { |path| File.basename(path).sub(/\A\d+_/, "").delete_suffix(".rb").camelize }
+      installed = context.migrations.select { |migration| expected.include?(migration.name) }
+      absent = expected - installed.map(&:name)
+      pending = installed.reject { |migration| context.get_all_versions.include?(migration.version) }.map(&:name)
+      return [ "error", "Install and run migrations: #{(absent + pending).join(', ')}." ] if absent.any? || pending.any?
+      [ "ok", "Content, Active Storage and Action Text migrations are installed." ]
+    end
+
+    def route
+      routes = @application.routes.routes.to_a
+      index = routes.index { |candidate| candidate.app.respond_to?(:app) && candidate.app.app == Engine }
+      return [ "error", "Mount OpenBlog::Engine after host routes under its path." ] unless index
+      prefix = routes[index].path.spec.to_s.sub(/\(.*\z/, "").chomp("/")
+      shadowed = routes.drop(index + 1).filter_map do |candidate|
+        path = candidate.path.spec.to_s.sub(/\(.*\z/, "")
+        path if path == prefix || path.start_with?("#{prefix}/")
+      end
+      return [ "error", "Move the engine mount after these host routes: #{shadowed.join(', ')}." ] if shadowed.any?
+      [ "ok", "Engine mounted at #{prefix.presence || '/'} after matching host routes." ]
+    end
+
+    def authentication
+      return [ "ok", "Host authentication hook is configured." ] if @config.authenticate
+      if ActiveRecord::Base.connection.data_source_exists?("open_blog_api_tokens") && ApiToken.active.exists?
+        [ "ok", "An active API token is configured." ]
+      else
+        [ "warning", "No host authentication hook or active API token is configured." ]
+      end
+    end
+
+    def rate_limit
+      key = "open-blog-doctor-#{SecureRandom.hex(12)}"
+      store = @config.rate_limit_store
+      store.write(key, 0, raw: true, expires_in: 30.seconds)
+      value = store.increment(key, 1)
+      value == 1 ? [ "ok", "Rate limit store supports increment." ] : [ "warning", "Rate limit store cannot count; configure a store with atomic increment." ]
+    rescue NotImplementedError, StandardError
+      [ "warning", "Rate limit store cannot count; configure a store with atomic increment." ]
+    ensure
+      store&.delete(key)
+    end
+
+    def jobs
+      adapter = @application.config.active_job.queue_adapter.to_s
+      if %w[async inline test].include?(adapter)
+        [ "warning", "#{adapter} jobs do not survive restart; use a persistent adapter and arrange open_blog:publish_due for scheduled posts." ]
+      else
+        [ "ok", "Job adapter is #{adapter}." ]
+      end
+    end
+
+    def storage
+      service = @config.storage_service || @application.config.active_storage.service
+      return [ "error", "Configure an Active Storage service." ] unless service
+      ActiveStorage::Blob.services.fetch(service)
+      return [ "error", "Install image_processing for reader image variants." ] unless Gem.loaded_specs.key?("image_processing")
+      processor = @application.config.active_storage.variant_processor || :vips
+      if processor.to_sym == :vips
+        begin
+          require "vips"
+        rescue LoadError
+          return [ "error", "Install ruby-vips and libvips for the configured image processor." ]
+        end
+      elsif !ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |directory| %w[magick identify].any? { |name| File.executable?(File.join(directory, name)) } }
+        return [ "error", "Install ImageMagick for the configured image processor." ]
+      end
+      return [ "warning", "Image URL address protection is disabled (image_fetch_policy = :open)." ] if @config.image_fetch_policy == :open
+      [ "ok", "Active Storage and the configured image processor are available." ]
+    end
+
+    def policy_pages
+      problems = %i[responsible_party corrections editorial ai_use].filter_map do |key|
+        url = @config.policy_urls[key]
+        if url.blank?
+          next "#{key}: install the open_blog_pages table" unless ActiveRecord::Base.connection.data_source_exists?("open_blog_pages")
+          next OpenBlog.policy_url(key, config: @config).present? ? nil : "#{key}: no published page or URL configured"
+        end
+        begin
+          code = @http_get ? @http_get.call(url).to_i : policy_response(url)
+          "#{key}: HTTP #{code}" unless code == 200
+        rescue StandardError => error
+          "#{key}: unavailable (#{error.class})"
+        end
+      end
+      problems.any? ? [ "warning", problems.join("; ") ] : [ "ok", "All policies have a published page or a URL responding with HTTP 200." ]
+    end
+
+    def policy_response(url)
+      uri = URI.parse(url)
+      raise ArgumentError unless uri.is_a?(URI::HTTP) && uri.host && uri.userinfo.nil?
+      Timeout.timeout(3) do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 2, read_timeout: 2) do |http|
+          http.request(Net::HTTP::Get.new(uri)) { |response| return response.code.to_i }
+        end
+      end
+    end
+
+    def records
+      return [ "warning", "Records cannot be checked until all content tables are installed." ] if missing_tables.any?
+      problems = []
+      Post.where(status: "published").find_each do |post|
+        revision = post.public_revision
+        problems << "#{post.id}: content differs from public revision" unless revision && RevisionPayload.new(post).identifier == revision.identifier
+        published = post.publications.find_by(entry_type: "first")&.occurred_at || post.baseline&.first_published_at || post.baseline&.declared_first_published_at
+        modified = post.publications.where(entry_type: %w[substantive correction]).maximum(:occurred_at) || post.baseline&.last_modified_at || published
+        problems << "#{post.id}: modified_at differs from publication records" unless post.modified_at == modified
+      end
+      problems.any? ? [ "error", problems.join("; ") ] : [ "ok", "Public content and modification dates match their records." ]
+    end
+
+    def declarations
+      source = read("config/initializers/open_blog.rb")
+      absent = %i[primary_list_type sign_in_destinations].reject do |name|
+        !@config.public_send(name).nil? && source.match?(/\.#{name}\s*=/)
+      end
+      absent.any? ? [ "warning", "Declare #{absent.join(' and ')} in the blog initializer." ] : [ "ok", "List type and sign-in destinations are declared." ]
+    end
+  end
+end

data/lib/open_blog/engine.rb

@@ -0,0 +1,45 @@
+require "rails/engine"
+require "action_dispatch"
+
+module OpenBlog
+  class Engine < ::Rails::Engine
+    isolate_namespace OpenBlog
+    engine_name "open_blog"
+
+    initializer "open_blog.parameter_filters" do |application|
+      application.config.filter_parameters |= [ :authorization, :token, :token_string ]
+    end
+
+    initializer "open_blog.assets", before: "propshaft.assets_middleware" do |application|
+      if application.config.respond_to?(:assets)
+        application.config.assets.paths << root.join("app/assets/builds")
+        application.config.assets.paths << root.join("app/assets/javascripts")
+      end
+    end
+
+    initializer "open_blog.markdown_mime" do
+      Mime::Type.register "text/markdown", :md unless Mime[:md]
+    end
+
+    config.to_prepare do
+      ActionText::RichText.include(OpenBlog::RichTextGuard) if defined?(ActionText::RichText)
+      if defined?(ActiveStorage::Attachment)
+        ActiveStorage::Attachment.include(OpenBlog::ImmutableImageAttachment)
+      end
+    end
+
+    config.after_initialize do |application|
+      if Engine.first_install?(application)
+        OpenBlog.config.validate_structure!
+      else
+        OpenBlog.config.validate!
+      end
+    end
+
+    def self.first_install?(application)
+      defined?(Rails::Command::GenerateCommand) &&
+        ARGV.first == "open_blog:install" &&
+        !application.root.join("config/initializers/open_blog.rb").exist?
+    end
+  end
+end

data/lib/open_blog/errors.rb

@@ -0,0 +1,40 @@
+module OpenBlog
+  class Error < StandardError
+    attr_reader :code, :status, :details
+
+    def initialize(message = nil, details: [])
+      @code = self.class::CODE
+      @status = self.class::STATUS
+      @details = Array(details)
+      super(message || self.class::MESSAGE)
+    end
+
+    {
+      unauthenticated: [ 401, "An authenticated actor is required." ],
+      scope_required: [ 403, "The actor lacks the required scope." ],
+      not_found: [ 404, "The requested record was not found." ],
+      identity_conflict: [ 409, "The external ID and slug identify different posts." ],
+      slug_reserved: [ 409, "This slug belongs to a route or another post's redirect." ],
+      post_is_public: [ 409, "This post is public. Update it through Publish." ],
+      revision_mismatch: [ 409, "The revision identifier does not match the content being approved." ],
+      already_changed_in_gem: [ 409, "This post has changed since its adoption." ],
+      validation_failed: [ 422, "One or more fields are invalid." ],
+      unknown_field: [ 422, "The request contains unsupported fields." ],
+      change_type_required: [ 422, "This update changes the public revision. Send change: substantive, correction or maintenance." ],
+      correction_note_required: [ 422, "A correction needs a note describing what changed." ],
+      approval_required: [ 422, "This publication requires approval with facts checked." ],
+      approval_incomplete: [ 422, "Approval requires a reviewer name and a boolean facts_checked value." ],
+      refused_by_host: [ 422, "The host declined this publication." ],
+      body_format_not_permitted: [ 422, "This body format is not enabled." ],
+      slug_not_supported: [ 422, "The slug contains unsupported characters." ],
+      image_not_permitted: [ 422, "The image input is not supported." ],
+      rate_limited: [ 429, "The request limit has been reached. Try again later." ]
+    }.each do |code, (status, message)|
+      subclass = Class.new(self)
+      subclass.const_set(:CODE, code)
+      subclass.const_set(:STATUS, status)
+      subclass.const_set(:MESSAGE, message.freeze)
+      const_set(code.to_s.split("_").map(&:capitalize).join, subclass)
+    end
+  end
+end

data/lib/open_blog/faq_extraction.rb

@@ -0,0 +1,184 @@
+require "digest"
+require "commonmarker"
+
+module OpenBlog
+  class FaqExtraction
+    HEADING = /\A[ \t]*(\#{2,6})[ \t]+(.+?)(?:[ \t]+\#+)?[ \t]*\z/
+    FAQ_TITLE = /\bFAQ\b|\A(?:Frequently asked questions|Common questions|Q&A)/i
+    PLAIN_NODES = %i[document paragraph text softbreak].freeze
+
+    def self.call(body:, standalone_questions: [])
+      new(body, standalone_questions).call
+    end
+
+    def self.faq_heading?(text)
+      text.is_a?(String) && text.match?(FAQ_TITLE)
+    end
+
+    def self.contains_faq_heading?(body)
+      body.to_s.each_line.any? do |line|
+        match = HEADING.match(line.chomp)
+        match && [ 2, 3 ].include?(match[1].length) && faq_heading?(match[2])
+      end
+    end
+
+    def initialize(body, standalone_questions)
+      unless body.is_a?(String) && body.valid_encoding? && standalone_questions.is_a?(Array) && standalone_questions.all? { |question| question.is_a?(String) }
+        raise Error::ValidationFailed.new(details: [ "body", "standalone_questions" ])
+      end
+      @body, @standalone_questions = body, standalone_questions
+      @pairs, @leftover, @reasons, @cut = [], [], [], []
+      @lines = scan_lines
+    end
+
+    def call
+      headings = @lines.select { |line| [ 2, 3 ].include?(line[:level]) && self.class.faq_heading?(line[:heading]) }
+      @reasons << "faq_heading_in_code" if headings.any? { |line| line[:code] }
+      headings = headings.reject { |line| line[:code] }
+      @reasons << "multiple_faq_headings" if headings.length > 1
+      sections = []
+      sections << section(headings.first, standalone: false) if headings.first
+      @lines.each do |line|
+        next unless !line[:code] && line[:level] == 2 && @standalone_questions.include?(line[:heading])
+        next if sections.any? { |existing| line[:start] >= existing[:start] && line[:start] < existing[:end] }
+        sections << section(line, standalone: true)
+      end
+      sections.sort_by { |entry| entry[:start] }.each { |entry| extract_section(entry) }
+      questions = @pairs.map { |pair| pair[:question] }
+      @reasons << "duplicate_question" if questions.uniq.length != questions.length
+      @reasons << "leftover_text" if @leftover.any?
+      @reasons.uniq!
+      @cut = @cut.each_with_object([]) do |range, merged|
+        if merged.last && range[:start] <= merged.last[:end]
+          merged.last[:end] = [ merged.last[:end], range[:end] ].max
+        else
+          merged << range.dup
+        end
+      end
+      { pairs: @pairs, cut: @cut, body_after: cut_body, leftover: @leftover,
+        class: @reasons.any? ? "review" : (@cut.any? ? "clean" : "none"),
+        reasons: @reasons, source_body_sha256: Digest::SHA256.hexdigest(@body) }
+    end
+
+    private
+
+    def scan_lines
+      offset = 0
+      fence = nil
+      @body.each_line.map do |raw|
+        text = raw.chomp
+        was_fenced = !fence.nil?
+        if fence
+          fence = nil if text.match?(/\A {0,3}#{Regexp.escape(fence[0])}{#{fence.length},}[ \t]*\z/)
+        elsif (opening = text.match(/\A {0,3}(`{3,}|~{3,})/))
+          fence = opening[1]
+        end
+        match = HEADING.match(text)
+        line = { text: text, start: offset, end: offset + raw.bytesize,
+          level: match && match[1].length, heading: match && match[2],
+          code: was_fenced || !fence.nil? || text.match?(/\A(?: {4}|\t)/) }
+        offset += raw.bytesize
+        line
+      end
+    end
+
+    def section(heading, standalone:)
+      following = @lines.find { |line| line[:start] > heading[:start] && line[:level] == 2 && !line[:code] }
+      { start: heading[:start], end: following ? following[:start] : @body.bytesize,
+        heading: heading, standalone: standalone }
+    end
+
+    def extract_section(section)
+      @cut << section.slice(:start, :end)
+      heading = section[:heading]
+      if section[:standalone]
+        @reasons << "standalone_question"
+        add_pair(heading[:heading], bytes(heading[:end], section[:end]), bold: false)
+        return
+      end
+      lines = @lines.select { |line| line[:start] >= heading[:end] && line[:start] < section[:end] }
+      candidates = lines.reject { |line| line[:code] }
+      level = candidates.any? { |line| line[:level] == 4 } ? 4 : 3
+      questions = candidates.select { |line| line[:level] == level }
+      bold = questions.empty?
+      questions = candidates.select { |line| bold_question(line[:text]) } if bold
+      if questions.empty?
+        add_leftover(bytes(heading[:end], section[:end]))
+        @reasons << "questions_absent" if @leftover.empty?
+        return
+      end
+      add_leftover(bytes(heading[:end], questions.first[:start]))
+      questions.each_with_index do |line, index|
+        finish = questions[index + 1]&.fetch(:start) || section[:end]
+        answer = bytes(line[:end], finish)
+        if bold
+          match = bold_question(line[:text])
+          question = match[1]
+          answer = "#{match[2]}\n#{answer}" if match[2].present?
+        else
+          question = line[:heading]
+        end
+        add_pair(question, answer, bold: bold)
+      end
+    end
+
+    def bold_question(text)
+      text.match(/\A {0,3}\*\*(.+?)\*\*[ \t]*(.*)\z/)
+    end
+
+    def add_pair(question, answer, bold:)
+      question = question.strip
+      plain_question = PlainText.from_markdown(question)
+      if plain_question != question
+        @reasons << "markdown_in_question"
+        question = plain_question
+      end
+      answer = answer.gsub(/\r\n?/, "\n").strip
+      @reasons << "question_without_question_mark" unless question.end_with?("?")
+      @reasons << "answer_absent" if answer.empty?
+      @reasons << "multiline_bold_answer" if bold && answer.lines.length > 1
+      nodes = Commonmarker.parse(answer, options: { extension: { autolink: false } })
+      types = node_types(nodes)
+      @reasons << "heading_in_answer" if types.include?(:heading)
+      if (types - PLAIN_NODES).any? || plain_text(nodes).strip != answer
+        @reasons << "markdown_in_answer"
+        answer = PlainText.from_markdown(answer)
+      end
+      @pairs << { question: question, answer: answer }
+    end
+
+    def plain_text(node)
+      return node.literal if node.type == :text
+      return "\n" if node.type == :softbreak
+      node.each.map { |child| plain_text(child) }.join(node.type == :document ? "\n\n" : "")
+    end
+
+    def node_types(node)
+      [ node.type ] + node.each.flat_map { |child| node_types(child) }
+    end
+
+    def add_leftover(text)
+      @leftover << text.strip if text.present?
+    end
+
+    def bytes(start, finish)
+      @body.byteslice(start...finish)
+    end
+
+    def cut_body
+      result = @body.dup
+      @cut.reverse_each do |range|
+        before = result.byteslice(0...range[:start]).rstrip
+        after = result.byteslice(range[:end]..-1).to_s
+        result = if before.empty?
+          after
+        elsif after.empty?
+          "#{before}\n"
+        else
+          "#{before}\n\n#{after}"
+        end
+      end
+      result
+    end
+  end
+end

data/lib/open_blog/findings/body_checks.rb

@@ -0,0 +1,58 @@
+require "uri"
+
+module OpenBlog
+  module Findings
+    module BodyChecks
+      class << self
+        def build
+          [
+            Check.new(code: :heading_level_skipped, rule: "T9", message: "Use consecutive heading levels within the body.",
+              location: ->(_, _, index) { "body.headings[#{index}]" }) { |post, context| skipped_heading(post, context) },
+            Check.new(code: :heading_h1_in_body, rule: "T10", message: "Use a level-two heading or lower in the body; the title supplies level one.",
+              location: ->(_, _, index) { "body.headings[#{index}]" }) { |post, context| headings(post, context).index { |node| node.name == "h1" } },
+            Check.new(code: :image_alt_absent, rule: "T13", message: "Describe this image in alternative text.",
+              location: ->(_, _, location) { location }) { |post, context| absent_alt(post, context) },
+            Check.new(code: :image_external, rule: "E19", message: "Store this image in the blog to keep a stable copy of its bytes.",
+              location: ->(_, _, index) { "body.images[#{index}]" }) { |post, context| images(post, context).index { |node| external?(node["src"]) } }
+          ]
+        end
+
+        private
+
+        def document(post, context)
+          context[:body_document] ||= Renderer.document(post)
+        end
+
+        def headings(post, context)
+          document(post, context).css("h1, h2, h3, h4, h5, h6")
+        end
+
+        def images(post, context)
+          document(post, context).css("img")
+        end
+
+        def skipped_heading(post, context)
+          levels = headings(post, context).map { |node| node.name.delete_prefix("h").to_i }
+          pair = levels.each_cons(2).find_index { |previous, current| current > previous + 1 }
+          pair + 1 if pair
+        end
+
+        def absent_alt(post, context)
+          return "cover_alt" if post.cover_image && post.cover_alt.blank?
+          index = images(post, context).index { |node| node["alt"].blank? }
+          "body.images[#{index}].alt" if index
+        end
+
+        def external?(source)
+          return false if source.blank?
+          uri = URI.parse(source)
+          return false unless uri.host
+          base = URI.parse(OpenBlog.config.public_base_url.to_s)
+          uri.host.downcase != base.host&.downcase
+        rescue URI::InvalidURIError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/open_blog/findings/check.rb

@@ -0,0 +1,19 @@
+module OpenBlog
+  module Findings
+    class Check
+      attr_reader :code
+
+      def initialize(code:, rule:, message:, location: nil, &predicate)
+        @code, @rule, @message, @location, @predicate = code, rule, message, location, predicate
+      end
+
+      def call(post, context: {})
+        matched = @predicate.call(post, context)
+        return [] unless matched
+
+        location = @location.respond_to?(:call) ? @location.call(post, context, matched) : @location
+        [ { code: code, rule: @rule, message: @message, location: location } ]
+      end
+    end
+  end
+end

data/lib/open_blog/findings/link_check.rb

@@ -0,0 +1,78 @@
+require "uri"
+
+module OpenBlog
+  module Findings
+    class LinkCheck
+      def code
+        :link_same_site_broken
+      end
+
+      def call(post, context: {})
+        document = context[:body_document] ||= Renderer.document(post)
+        document.css("a[href]").map { |node| node["href"] }.uniq.filter_map do |href|
+          path = local_path(href, post)
+          next unless path && !resolves?(path)
+          { code: code, rule: "T14", message: "Point this link to an available page.", location: href }
+        end
+      end
+
+      private
+
+      def local_path(href, post)
+        return if href.blank? || href.start_with?("#", "?")
+        reference = URI.parse(href)
+        return if reference.scheme && !%w[http https].include?(reference.scheme.downcase)
+        configured = OpenBlog.config.public_base_url
+        return if (reference.host || reference.scheme) && configured.blank?
+        origin = URI.parse(configured.presence || "https://open-blog.invalid")
+        target = URI.join("#{origin.to_s.chomp('/')}#{post.path}", href)
+        return unless [ target.scheme, target.host&.downcase, target.port ] == [ origin.scheme, origin.host&.downcase, origin.port ]
+        mount = OpenBlog.mount_path.chomp("/")
+        path = target.path
+        return unless path == mount || path.start_with?("#{mount}/")
+        relative = path.delete_prefix(mount)
+        return if relative.match?(%r{\A/(?:api|mcp)(?:/|\z)})
+        path
+      rescue URI::InvalidURIError, URI::BadURIError
+        nil
+      end
+
+      def resolves?(path)
+        mount = OpenBlog.mount_path.chomp("/")
+        route = Engine.routes.recognize_path(path.delete_prefix(mount).presence || "/", method: :get)
+        format = route[:format].to_s
+        controller = route[:controller].delete_prefix("open_blog/")
+        case controller
+        when "posts"
+          return format.blank? || format == "html" if route[:action] == "index"
+          return false unless format.blank? || %w[html md].include?(format)
+          Post.listed.exists?(slug: route[:slug]) || Redirect.exists?(old_path: "#{mount}/#{route[:slug]}")
+        when "categories", "tags", "authors", "series"
+          return false unless format.blank? || format == "html"
+          model = { "categories" => Category, "tags" => Tag, "authors" => Author, "series" => Series }.fetch(controller)
+          model.exists?(slug: route[:slug])
+        when "feeds"
+          route[:slug].nil? || Category.exists?(slug: route[:slug])
+        when "search"
+          format.blank? || %w[html json].include?(format)
+        when "sitemaps"
+          OpenBlog.config.serve_sitemap
+        when "pages"
+          page = Page.published.find_by(slug: route[:slug])
+          page && OpenBlog.config.policy_urls[page.kind.to_sym].blank?
+        when "previews"
+          return false unless format.blank? || format == "html"
+          post = Post.find_by_preview_token(route[:token])
+          post && (post.previewable? || post.published?)
+        when "media"
+          image = Image.find_by(sha256: route[:sha256])
+          image && image.file.attached?
+        else
+          false
+        end
+      rescue ActionController::RoutingError
+        false
+      end
+    end
+  end
+end