kiln 0.1.0

data/lib/kiln/router.rb

@@ -0,0 +1,142 @@
+module Kiln
+  # Walks the app's GET routes and turns them into concrete pages, using the param sources and skips
+  # from Kiln.pages. Routes that need params but have no source are reported as uncovered.
+  class Router
+    # status is :built (count pages), :skipped (reason) or :uncovered.
+    Row = Data.define(:name, :path, :status, :count, :reason)
+
+    # Framework routes skipped by default, keyed by "controller#action" or a whole "controller".
+    DEFAULT_SKIPS = {
+      "rails/health#show" => "Rails health check",
+      "turbo/native/navigation" => "turbo-rails native navigation"
+    }.freeze
+
+    def initialize(routes, pages, report:)
+      @routes = routes
+      @dsl = pages
+      @report = report
+    end
+
+    def pages
+      analyze
+      @pages
+    end
+
+    def rows
+      analyze
+      @rows
+    end
+
+    # Text table for `kiln:routes`.
+    def table
+      lines = rows.map do |row|
+        status = case row.status
+        when :built then "built #{row.count}"
+        when :skipped then "skipped: #{row.reason}"
+        else "uncovered"
+        end
+        [ row.name || "-", row.path, status ]
+      end
+      widths = [ 0, 1 ].map { |i| lines.map { it[i].length }.max.to_i }
+      lines.map { |name, path, status| "#{name.ljust(widths[0])}  #{path.ljust(widths[1])}  #{status}".rstrip }.join("\n")
+    end
+
+    private
+      attr_reader :dsl, :report
+
+      def analyze
+        return if @rows
+
+        @pages = []
+        @rows = []
+        seen = Set.new
+        check_declared_names
+        get_routes.each do |route|
+          status, detail = classify(route)
+          count = 0
+          if status == :built
+            pages_for(route, detail).each do |page|
+              next unless seen.add?(page.path)
+              @pages << page
+              count += 1
+            end
+          end
+          @rows << Row.new(name: route.name, path: route.path.spec.to_s, status:, count:, reason: status == :skipped ? detail : nil)
+        end
+      end
+
+      def get_routes
+        @get_routes ||= @routes.routes.select { it.verb.empty? || it.verb.split("|").include?("GET") }
+      end
+
+      # Explicit declarations win over the defaults. For :built, detail is the param list source.
+      def classify(route)
+        name = route.name&.to_sym
+        if name && dsl.skips.key?(name)
+          [ :skipped, dsl.skips[name] || "skipped in config/kiln.rb" ]
+        elsif name && dsl.sources.key?(name)
+          [ :built, dsl.sources[name] ]
+        elsif route.internal || route.path.spec.to_s.start_with?("/rails/")
+          [ :skipped, "Rails internal route" ]
+        elsif (reason = default_skip(route))
+          [ :skipped, reason ]
+        elsif route.app.engine?
+          [ :skipped, "mounted engine" ]
+        elsif route.required_parts.empty?
+          [ :built, -> { [ {} ] } ]
+        else
+          report_uncovered(route)
+          [ :uncovered, nil ]
+        end
+      end
+
+      def default_skip(route)
+        controller, action = route.requirements.values_at(:controller, :action)
+        DEFAULT_SKIPS["#{controller}##{action}"] || DEFAULT_SKIPS[controller] if controller
+      end
+
+      def pages_for(route, source)
+        list = source.call
+        unless list.is_a?(Enumerable) && !list.is_a?(Hash)
+          return source_error(route, "must return a list of hashes, got #{list.class}")
+        end
+
+        list.flat_map do |params|
+          next source_error(route, "returned #{params.inspect}, expected a hash") unless params.is_a?(Hash)
+
+          params = params.symbolize_keys.compact
+          missing = route.required_parts - params.keys
+          next source_error(route, "returned #{params.inspect}, missing #{missing.map(&:inspect).join(", ")}") if missing.any?
+
+          [ Page.new(path: route.format(params.transform_values(&:to_param)), route_name: route.name, params:) ]
+        end
+      rescue StandardError => error
+        source_error(route, "raised #{error.class}: #{error.message}")
+      end
+
+      def source_error(route, message)
+        report.error(:other, "Param source for :#{route.name} #{message}")
+        []
+      end
+
+      def report_uncovered(route)
+        spec = route.path.spec.to_s
+        message =
+          if route.name
+            keys = route.required_parts.map { "#{it}: ..." }.join(", ")
+            "GET #{spec} (:#{route.name}) needs params. Add `params :#{route.name}, -> { [ { #{keys} } ] }` " \
+              "or `skip :#{route.name}, reason: \"...\"` to config/kiln.rb."
+          else
+            "GET #{spec} needs params but has no name. Add `as:` to the route in config/routes.rb, " \
+              "then declare its params or skip it in config/kiln.rb."
+          end
+        report.error(:uncovered_route, message)
+      end
+
+      def check_declared_names
+        (dsl.declared_names - get_routes.filter_map { it.name&.to_sym }).each do |name|
+          report.error(:other, "config/kiln.rb declares :#{name}, but there is no GET route with that name")
+        end
+      end
+  end
+end

data/lib/kiln/server.rb

@@ -0,0 +1,38 @@
+require "rack/mime"
+
+module Kiln
+  # Rack app that serves the built output the way a static host would.
+  class Server
+    def self.start(root, port:)
+      require "rackup"
+      Rackup::Handler.default.run(new(root), Host: "localhost", Port: port)
+    end
+
+    def initialize(root)
+      @root = Pathname(root)
+      @resolver = StaticResolver.new(@root)
+      @redirects = Redirects.load(@root.join(Redirects::FILENAME)).index_by(&:from)
+    end
+
+    def call(env)
+      path = env["PATH_INFO"].presence || "/"
+
+      if (redirect = @redirects[path])
+        [ redirect.status, { "location" => redirect.to }, [] ]
+      elsif (file = @resolver.resolve(path))
+        serve(200, file)
+      elsif (not_found = @resolver.resolve("/404.html"))
+        serve(404, not_found)
+      else
+        [ 404, { "content-type" => "text/plain" }, [ "Not found\n" ] ]
+      end
+    end
+
+    private
+      def serve(status, file)
+        body = file.binread
+        type = Rack::Mime.mime_type(file.extname, "application/octet-stream")
+        [ status, { "content-type" => type, "content-length" => body.bytesize.to_s }, [ body ] ]
+      end
+  end
+end

data/lib/kiln/sitemap.rb

@@ -0,0 +1,38 @@
+require "erb"
+
+module Kiln
+  # sitemap.xml with every indexable HTML page in the manifest.
+  class Sitemap
+    FILENAME = "sitemap.xml"
+
+    def self.noindex?(response, body)
+      return false unless response.html?
+      return true if response.headers["x-robots-tag"].to_s.downcase.include?("noindex")
+      return false unless body.match?(/noindex/i)
+
+      Nokogiri::HTML5(body).css("meta[name]").any? do |meta|
+        meta["name"].casecmp?("robots") && meta["content"].to_s.downcase.include?("noindex")
+      end
+    end
+
+    def initialize(manifest, url:)
+      @manifest = manifest
+      @url = url.chomp("/")
+    end
+
+    def write(output)
+      urls = @manifest.entries.filter_map do |path, entry|
+        next if entry[:noindex] || entry[:content_type] != "text/html"
+
+        "  <url><loc>#{ERB::Util.html_escape(@url + path)}</loc></url>\n"
+      end
+
+      File.write(Pathname(output).join(FILENAME), <<~XML)
+        <?xml version="1.0" encoding="UTF-8"?>
+        <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+        #{urls.join}</urlset>
+      XML
+      FILENAME
+    end
+  end
+end

data/lib/kiln/static_resolver.rb

@@ -0,0 +1,28 @@
+module Kiln
+  # Maps a URL path to a file the way Cloudflare Pages and GitHub Pages do: exact file, then x.html,
+  # then x/index.html. A trailing slash only matches x/index.html. Never returns a file outside root.
+  class StaticResolver
+    def initialize(root)
+      @root = Pathname(root).expand_path
+    end
+
+    def resolve(url_path)
+      path = Rack::Utils.unescape_path(url_path.to_s.split(/[?#]/, 2).first.to_s)
+      return if path.include?("\0")
+
+      segments = path.split("/").reject { it.empty? || it == "." }
+      return if segments.include?("..")
+
+      base = @root.join(*segments)
+      candidates = path.end_with?("/") || segments.empty? ? [ base.join("index.html") ] : [ base, Pathname("#{base}.html"), base.join("index.html") ]
+      candidates.find { it.file? && inside_root?(it) }
+    rescue ArgumentError, Encoding::CompatibilityError
+      nil
+    end
+
+    private
+      def inside_root?(file)
+        file.realpath.to_s.start_with?("#{@root.realpath}/")
+      end
+  end
+end

data/lib/kiln/test_helper.rb

@@ -0,0 +1,59 @@
+require "kiln"
+require "tmpdir"
+require "nokogiri"
+
+module Kiln
+  # Minitest assertions for apps built with Kiln.
+  #
+  #   require "kiln/test_helper"
+  #
+  #   class StaticSiteTest < ActiveSupport::TestCase
+  #     include Kiln::TestHelper
+  #
+  #     test("builds the same output twice") { assert_repeatable_build }
+  #     test("home page") { assert_page "/", selector: "h1", text: "Home" }
+  #   end
+  module TestHelper
+    # Builds into a temp dir, fails with the report on any error, and yields the output path.
+    # Returns the Build when no block is given (the temp dir is then left for the caller).
+    def kiln_build(app: Rails.application, config: Kiln.config)
+      dir = Dir.mktmpdir("kiln-build")
+      build = Build.new(app:, config:, output: dir)
+      assert build.run.success?, build.report.to_s
+      return build unless block_given?
+
+      begin
+        yield Pathname(dir)
+      ensure
+        FileUtils.rm_rf(dir)
+      end
+    end
+
+    # Builds twice and asserts both outputs are byte-identical.
+    def assert_repeatable_build(app: Rails.application, config: Kiln.config)
+      kiln_build(app:, config:) do |first|
+        kiln_build(app:, config:) do |second|
+          diff = TreeDiff.call(first, second)
+          assert diff.empty?, "Kiln output differs between two builds:\n#{diff}"
+        end
+      end
+    end
+
+    # Renders one path the way a build does (processors included) and asserts it succeeds.
+    # Optional `selector` must match, and contain `text` when given. Returns the processed body.
+    def assert_page(path, status: 200, selector: nil, text: nil, app: Rails.application, config: Kiln.config)
+      response = Kiln.building! { Renderer.new(app, host: config.host).get(path) }
+      assert_equal status, response.status, "Expected #{path} to respond with #{status}"
+
+      body = response.body
+      body = Processors.apply(body, Processors::Context.new(path:, config:, response:)) if response.html?
+
+      if selector
+        nodes = Nokogiri::HTML5(body).css(selector)
+        assert nodes.any?, "Expected #{path} to contain #{selector}"
+        assert nodes.any? { it.text.include?(text) }, "Expected #{selector} on #{path} to contain #{text.inspect}" if text
+      end
+      body
+    end
+  end
+end

data/lib/kiln/tree_diff.rb

@@ -0,0 +1,25 @@
+module Kiln
+  # Compares two directory trees byte for byte. Returns relative paths.
+  module TreeDiff
+    Result = Data.define(:added, :removed, :changed) do
+      def empty? = added.empty? && removed.empty? && changed.empty?
+
+      def to_s
+        [ added.map { "+ #{it}" }, removed.map { "- #{it}" }, changed.map { "~ #{it}" } ].flatten.join("\n")
+      end
+    end
+
+    def self.call(before, after)
+      old_files = files(before)
+      new_files = files(after)
+      changed = (old_files & new_files).reject { FileUtils.identical?(File.join(before, it), File.join(after, it)) }
+      Result.new(added: new_files - old_files, removed: old_files - new_files, changed:)
+    end
+
+    def self.files(root)
+      return [] unless File.directory?(root)
+
+      Dir.glob("**/*", File::FNM_DOTMATCH, base: root).reject { File.directory?(File.join(root, it)) }.sort
+    end
+  end
+end

data/lib/kiln/verifier.rb

@@ -0,0 +1,97 @@
+module Kiln
+  # Checks the built output: internal links, anchors and importmap modules.
+  class Verifier
+    LINK_ATTRIBUTES = %w[href src srcset].freeze
+
+    def initialize(output, config:)
+      @output = Pathname(output)
+      @host = config.host.downcase
+      @resolver = StaticResolver.new(@output)
+      @redirect_sources = Redirects.load(@output.join(Redirects::FILENAME)).map(&:from).to_set
+      @anchors = {}
+    end
+
+    def verify(report)
+      @errors = Set.new
+      Dir.glob("**/*.html", base: @output).sort.each { check_page(it) }
+      @errors.each { |kind, message, path| report.error(kind, message, path:) }
+      report
+    end
+
+    private
+      def check_page(file)
+        page = page_path(file)
+        doc = parse(@output.join(file))
+
+        doc.xpath("//*[@href or @src or @srcset]").each do |element|
+          urls_in(element).each { check_link(it, page) }
+        end
+        doc.css('script[type="importmap"]').each { check_importmap(it.text, page) }
+      end
+
+      def urls_in(element)
+        LINK_ATTRIBUTES.flat_map do |name|
+          value = element[name]
+          next [] if value.nil?
+
+          name == "srcset" ? value.split(",").filter_map { it.split.first } : [ value ]
+        end
+      end
+
+      def check_link(url, page)
+        uri = internal_uri(url, page) or return
+        target = @resolver.resolve(uri.path)
+
+        if target.nil?
+          error(:broken_link, url, page) unless @redirect_sources.include?(uri.path)
+        elsif uri.fragment.present? && uri.fragment != "top" && target.extname == ".html"
+          fragment = Rack::Utils.unescape_path(uri.fragment)
+          error(:missing_anchor, url, page) unless anchors(target).include?(fragment)
+        end
+      rescue URI::Error
+        error(:broken_link, url, page)
+      end
+
+      def check_importmap(json, page)
+        map = JSON.parse(json)
+        urls = map.fetch("imports", {}).values + map.fetch("scopes", {}).values.flat_map(&:values)
+        urls.each do |url|
+          uri = internal_uri(url, page)
+          error(:importmap, url, page) if uri && @resolver.resolve(uri.path).nil?
+        rescue URI::Error
+          error(:importmap, url, page)
+        end
+      rescue JSON::ParserError, NoMethodError, TypeError
+        error(:importmap, "invalid importmap JSON", page)
+      end
+
+      # The URL resolved against the page, or nil when it points somewhere Kiln doesn't serve.
+      def internal_uri(url, page)
+        url = url.strip
+        return if url.empty?
+
+        uri = URI.join("https://#{@host}#{page}", url)
+        uri if uri.is_a?(URI::HTTP) && uri.host.to_s.downcase == @host
+      end
+
+      def anchors(file)
+        @anchors[file] ||= parse(file).xpath("//*[@id]/@id | //a[@name]/@name").to_set(&:value)
+      end
+
+      def parse(file)
+        Nokogiri::HTML5(file.read)
+      end
+
+      # The URL a file is served at: index.html -> /, now/index.html -> /now/, components.html -> /components.
+      def page_path(file)
+        path = "/#{file}"
+        return path.delete_suffix("index.html") if File.basename(file) == "index.html"
+
+        path.delete_suffix(".html")
+      end
+
+      def error(kind, message, page)
+        @errors << [ kind, message, page ]
+      end
+  end
+end

data/lib/kiln/version.rb

@@ -0,0 +1,3 @@
+module Kiln
+  VERSION = "0.1.0"
+end

data/lib/kiln/writer.rb

@@ -0,0 +1,62 @@
+require "fileutils"
+
+module Kiln
+  # Maps request paths to files under the output directory and writes them.
+  class Writer
+    def initialize(output, mode:)
+      raise Kiln::Error, "Unknown paths mode #{mode.inspect} (expected :directory or :file)" unless %i[directory file].include?(mode)
+
+      @output = Pathname(output).expand_path
+      @mode = mode
+    end
+
+    # Relative file for a request path: "/now" -> "now/index.html" (or "now.html" in :file mode).
+    def file_for(path, content_type)
+      segments = segments_for(path)
+      content_type = content_type.to_s.split(";").first.to_s.strip.downcase
+      return "index.html" if segments.empty?
+
+      name = segments.last
+      if File.extname(name).empty?
+        if content_type == "text/html"
+          segments = @mode == :directory ? [ *segments, "index.html" ] : [ *segments[...-1], "#{name}.html" ]
+        elsif (extension = extension_for(content_type))
+          segments = [ *segments[...-1], "#{name}.#{extension}" ]
+        end
+      end
+      segments.join("/")
+    end
+
+    def write(path, content_type, body)
+      write_file(file_for(path, content_type), body)
+    end
+
+    # Writes a file at a path relative to the output directory.
+    def write_file(relative, body)
+      target = @output.join(relative).expand_path
+      unless target.to_s.start_with?("#{@output}/")
+        raise Kiln::Error, "Refusing to write #{relative} outside #{@output}"
+      end
+
+      FileUtils.mkdir_p(target.dirname)
+      File.binwrite(target, body)
+      relative.to_s
+    end
+
+    private
+      def extension_for(content_type)
+        symbol = Mime::Type.lookup(content_type).symbol if content_type.present?
+        symbol == :text ? "txt" : symbol
+      end
+
+      def segments_for(path)
+        segments = path.to_s.split("?").first.to_s.split("/").reject(&:empty?).map do
+          Rack::Utils.unescape_path(it).force_encoding(Encoding::UTF_8)
+        end
+        if segments.any? { it == ".." || it == "." || it.include?("/") || it.include?("\0") }
+          raise Kiln::Error, "Invalid path #{path.inspect}"
+        end
+        segments
+      end
+  end
+end

data/lib/kiln.rb

@@ -0,0 +1,62 @@
+require "zeitwerk"
+require "active_support"
+require "active_support/core_ext"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/tasks")
+loader.ignore("#{__dir__}/kiln/railtie.rb")
+# Optional parts, loaded with an explicit require so eager loading never pulls in their gems.
+loader.ignore("#{__dir__}/kiln/content.rb", "#{__dir__}/kiln/content")
+loader.ignore("#{__dir__}/kiln/test_helper.rb")
+loader.inflector.inflect("strip_csrf" => "StripCSRF")
+loader.setup
+
+module Kiln
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Kiln.pages { params :post, -> { ... }; skip :up }
+    def pages(&block)
+      @pages ||= Pages.new
+      @pages.instance_eval(&block) if block
+      @pages
+    end
+
+    # True while a build is rendering pages. Views use it to hide dev-only things.
+    def building?
+      @building == true
+    end
+
+    def building!
+      previous = @building
+      @building = true
+      build_cache.clear
+      yield
+    ensure
+      @building = previous
+      build_cache.clear
+    end
+
+    # Memoization store that lives for one build. Cleared before and after every build.
+    def build_cache
+      @build_cache ||= BuildCache.new
+    end
+
+    def reset!
+      @config = nil
+      @pages = nil
+      @building = nil
+      @build_cache = nil
+    end
+  end
+end
+
+require "kiln/railtie" if defined?(Rails::Railtie)

data/lib/tasks/kiln/build.rake

@@ -0,0 +1,33 @@
+namespace :kiln do
+  desc "Render every page into the output directory"
+  task build: :environment do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    build = Kiln::Build.new
+    # One log line per request buries the report. Warnings and errors still show; VERBOSE=1 shows all.
+    report = ENV["VERBOSE"] ? build.run : Rails.logger.silence(Logger::WARN) { build.run }
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+    puts report
+    if (changes = build.changes) && report.success?
+      summary = changes.map { |kind, paths| "#{paths.size} #{kind}" }.join(", ")
+      puts "Pages since last build: #{summary}"
+      changes.each { |kind, paths| paths.each { puts "  #{kind}: #{it}" } }
+    end
+    puts format("Output: %s (%.1fs)", build.output, elapsed)
+    exit 1 if report.failure?
+  end
+
+  desc "Fail if the committed output differs from a fresh build"
+  task check: :environment do
+    result = Kiln::Check.new.run
+    if result.report.failure?
+      puts result.report
+    elsif result.diff.empty?
+      puts "Kiln check: #{Kiln.config.output_path} is up to date."
+    else
+      puts "Kiln check: #{Kiln.config.output_path} is out of date. Run kiln:build and commit the result."
+      puts result.diff
+    end
+    exit 1 unless result.success?
+  end
+end

data/lib/tasks/kiln/routes.rake

@@ -0,0 +1,12 @@
+namespace :kiln do
+  desc "List every GET route and whether Kiln builds, skips, or misses it"
+  task routes: :environment do
+    report = Kiln::Report.new
+    router = Kiln::Router.new(Rails.application.routes, Kiln.pages, report:)
+    puts router.table
+    if report.failure?
+      puts "", report
+      exit 1
+    end
+  end
+end

data/lib/tasks/kiln/serve.rake

@@ -0,0 +1,11 @@
+namespace :kiln do
+  desc "Serve the built output like a static host (PORT, default 4000)"
+  task serve: :environment do
+    output = Kiln.config.output_path
+    abort "Kiln: #{output} does not exist. Run kiln:build first." unless output.directory?
+
+    port = Integer(ENV.fetch("PORT", 4000))
+    puts "Kiln: serving #{output} at http://localhost:#{port}"
+    Kiln::Server.start(output, port:)
+  end
+end

data/lib/tasks/kiln/verify.rake

@@ -0,0 +1,15 @@
+namespace :kiln do
+  desc "Check internal links, anchors and importmap modules in the built output"
+  task verify: :environment do
+    output = Kiln.config.output_path
+    abort "Kiln: #{output} does not exist. Run kiln:build first." unless output.directory?
+
+    report = Kiln::Verifier.new(output, config: Kiln.config).verify(Kiln::Report.new)
+    if report.success?
+      puts "Kiln verify: no problems found in #{output}."
+    else
+      puts report.to_s(title: "Kiln verify")
+      exit 1
+    end
+  end
+end