infodocs 0.3.0

data/lib/infodocs/code_theme.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Syntax colour palettes. Rouge token classes map to a few roles; each role
+  # is a CSS variable, so a theme is just a set of colours for light and dark.
+  module CodeTheme
+    ROLES = %i[fg bg comment keyword string number function type variable builtin operator punctuation tag attribute escape regex symbol].freeze
+
+    PALETTES = {
+      github: {
+        light: { fg: "#24292f", bg: "#f6f8fa", comment: "#6e7781", keyword: "#cf222e", string: "#0a3069", number: "#0550ae", function: "#8250df",
+                 type: "#953800", variable: "#953800", builtin: "#0550ae", operator: "#cf222e", punctuation: "#24292f", tag: "#116329",
+                 attribute: "#0550ae", escape: "#0550ae", regex: "#0a3069", symbol: "#0550ae" },
+        dark: { fg: "#e6edf3", bg: "#161b22", comment: "#8b949e", keyword: "#ff7b72", string: "#a5d6ff", number: "#79c0ff", function: "#d2a8ff",
+                type: "#ffa657", variable: "#ffa657", builtin: "#79c0ff", operator: "#ff7b72", punctuation: "#e6edf3", tag: "#7ee787",
+                attribute: "#79c0ff", escape: "#79c0ff", regex: "#a5d6ff", symbol: "#79c0ff" }
+      },
+      one: {
+        light: { fg: "#383a42", bg: "#fafafa", comment: "#a0a1a7", keyword: "#a626a4", string: "#50a14f", number: "#986801", function: "#4078f2",
+                 type: "#c18401", variable: "#e45649", builtin: "#c18401", operator: "#0184bc", punctuation: "#383a42", tag: "#e45649",
+                 attribute: "#986801", escape: "#0184bc", regex: "#0184bc", symbol: "#0184bc" },
+        dark: { fg: "#abb2bf", bg: "#282c34", comment: "#5c6370", keyword: "#c678dd", string: "#98c379", number: "#d19a66", function: "#61afef",
+                type: "#e5c07b", variable: "#e06c75", builtin: "#e5c07b", operator: "#56b6c2", punctuation: "#abb2bf", tag: "#e06c75",
+                attribute: "#d19a66", escape: "#56b6c2", regex: "#56b6c2", symbol: "#56b6c2" }
+      },
+      vscode: {
+        light: { fg: "#1f1f1f", bg: "#f8f8f8", comment: "#008000", keyword: "#0000ff", string: "#a31515", number: "#098658", function: "#795e26",
+                 type: "#267f99", variable: "#001080", builtin: "#267f99", operator: "#1f1f1f", punctuation: "#1f1f1f", tag: "#800000",
+                 attribute: "#e50000", escape: "#ee0000", regex: "#811f3f", symbol: "#0070c1" },
+        dark: { fg: "#d4d4d4", bg: "#1e1e1e", comment: "#6a9955", keyword: "#569cd6", string: "#ce9178", number: "#b5cea8", function: "#dcdcaa",
+                type: "#4ec9b0", variable: "#9cdcfe", builtin: "#4ec9b0", operator: "#d4d4d4", punctuation: "#d4d4d4", tag: "#569cd6",
+                attribute: "#9cdcfe", escape: "#d7ba7d", regex: "#d16969", symbol: "#4fc1ff" }
+      },
+      catppuccin: {
+        light: { fg: "#4c4f69", bg: "#eff1f5", comment: "#9ca0b0", keyword: "#8839ef", string: "#40a02b", number: "#fe640b", function: "#1e66f5",
+                 type: "#df8e1d", variable: "#e64553", builtin: "#d20f39", operator: "#04a5e5", punctuation: "#7c7f93", tag: "#1e66f5",
+                 attribute: "#df8e1d", escape: "#ea76cb", regex: "#ea76cb", symbol: "#dd7878" },
+        dark: { fg: "#cdd6f4", bg: "#1e1e2e", comment: "#6c7086", keyword: "#cba6f7", string: "#a6e3a1", number: "#fab387", function: "#89b4fa",
+                type: "#f9e2af", variable: "#f38ba8", builtin: "#f38ba8", operator: "#89dceb", punctuation: "#9399b2", tag: "#89b4fa",
+                attribute: "#f9e2af", escape: "#f5c2e7", regex: "#f5c2e7", symbol: "#f2cdcd" }
+      }
+    }.freeze
+
+    DEFAULT = :one
+
+    # Rouge short token classes -> role.
+    TOKENS = {
+      comment: %w[c cm c1 cs cd],
+      keyword: %w[k kd kn kp kr kc],
+      string: %w[s sb sc sd s2 sh si sx s1 dl],
+      symbol: %w[ss],
+      regex: %w[sr],
+      escape: %w[se],
+      number: %w[m mf mh mi mo mb il],
+      function: %w[nf fm],
+      type: %w[nc nn kt no nd],
+      variable: %w[nv vc vg vi vm],
+      builtin: %w[nb bp],
+      attribute: %w[na py],
+      tag: %w[nt],
+      operator: %w[o ow],
+      punctuation: %w[p]
+    }.freeze
+
+    module_function
+
+    # Accepts a palette name or a custom hash:
+    #   { base: :one, light: { keyword: "#..." }, dark: { ... } }
+    def resolve(theme)
+      case theme
+      when Hash
+        options = theme.transform_keys(&:to_sym)
+        base = PALETTES.fetch((options[:base] || DEFAULT).to_sym) { raise Error, "unknown base code theme #{options[:base].inspect}" }
+        { light: base[:light].merge(symbolize(options[:light])), dark: base[:dark].merge(symbolize(options[:dark])) }
+      else
+        PALETTES.fetch((theme || DEFAULT).to_sym) { raise Error, "unknown code theme #{theme.inspect}; choose one of #{PALETTES.keys.inspect}" }
+      end
+    end
+
+    def css(theme)
+      palette = resolve(theme)
+      light = variables(palette[:light])
+      dark = variables(palette[:dark])
+      <<~CSS
+        .infodocs-code{#{light}}
+        @media (prefers-color-scheme: dark){.infodocs-code{#{dark}}}
+        .dark .infodocs-code{#{dark}}
+        .infodocs-code{margin:1.25em 0;border:1px solid color-mix(in srgb,var(--hl-fg) 16%,transparent);border-radius:.5rem;overflow:hidden;background:var(--hl-bg);color:var(--hl-fg)}
+        @media print{body>header,#infodocs-sidebar,[data-infodocs-toc],article nav[aria-label=Pagination],.infodocs-code-copy{display:none!important}.infodocs-code pre{white-space:pre-wrap}}
+        .infodocs-numbers{counter-reset:line}
+        .infodocs-numbers .line::before{counter-increment:line;content:counter(line);display:inline-block;width:2.25rem;margin-right:1rem;text-align:right;color:color-mix(in srgb,var(--hl-fg) 35%,transparent);user-select:none}
+        .highlight .line-hl{display:inline-block;width:100%;background:color-mix(in srgb,var(--hl-fg) 10%,transparent)}
+        .infodocs-anchor{margin-left:.4em;font-weight:400;text-decoration:none;opacity:0;color:inherit}
+        h1:hover>.infodocs-anchor,h2:hover>.infodocs-anchor,h3:hover>.infodocs-anchor,h4:hover>.infodocs-anchor,.infodocs-anchor:focus{opacity:.4}
+        .infodocs-anchor:hover{opacity:.8!important}
+        .footnotes{margin-top:2.5rem;padding-top:1rem;border-top:1px solid color-mix(in srgb,currentColor 18%,transparent);font-size:.875em}
+        .infodocs-alert{margin:1.25rem 0;padding:.75rem 1rem;border-left:4px solid var(--alert,#3b82f6);border-radius:.375rem;background:color-mix(in srgb,var(--alert,#3b82f6) 10%,transparent)}
+        .infodocs-alert>p{margin:.25rem 0}
+        .infodocs-alert-title{font-weight:600;color:var(--alert,#3b82f6)}
+        .infodocs-alert-tip{--alert:#16a34a}.infodocs-alert-important{--alert:#9333ea}.infodocs-alert-warning{--alert:#d97706}.infodocs-alert-caution{--alert:#dc2626}
+        .infodocs-code-bar{display:flex;align-items:center;gap:.75rem;min-height:2.25rem;padding:0 .5rem 0 .875rem;font:500 .75rem/1 ui-sans-serif,system-ui,sans-serif;color:color-mix(in srgb,var(--hl-fg) 65%,transparent);background:color-mix(in srgb,var(--hl-fg) 6%,transparent);border-bottom:1px solid color-mix(in srgb,var(--hl-fg) 12%,transparent)}
+        .infodocs-code-file{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--hl-fg)}
+        .infodocs-code-copy{margin-left:auto;min-height:1.75rem;padding:0 .625rem;border-radius:.375rem;border:0;background:transparent;color:inherit;font:inherit;cursor:pointer}
+        .infodocs-code-copy:hover{background:color-mix(in srgb,var(--hl-fg) 12%,transparent)}
+        .infodocs-code pre.highlight{margin:0;border:0;border-radius:0;background:transparent;color:var(--hl-fg);padding:1rem;overflow-x:auto;font:.875rem/1.65 ui-monospace,SFMono-Regular,"JetBrains Mono",Menlo,monospace;tab-size:2}
+        .infodocs-code pre.highlight code{background:none;padding:0;color:inherit;font:inherit}
+        .infodocs-code pre.highlight code::before,.infodocs-code pre.highlight code::after{content:none}
+        #{token_rules}
+      CSS
+    end
+
+    def variables(colors)
+      colors.map { |role, value| "--hl-#{role}:#{value}" }.join(";")
+    end
+
+    def token_rules
+      rules = TOKENS.map do |role, classes|
+        selector = classes.map { |name| ".infodocs-code .#{name}" }.join(",")
+        "#{selector}{color:var(--hl-#{role})}"
+      end
+      rules << ".infodocs-code .c,.infodocs-code .cm,.infodocs-code .c1,.infodocs-code .cs{font-style:italic}"
+      rules << ".infodocs-code .gd{color:var(--hl-keyword)}.infodocs-code .gi{color:var(--hl-string)}.infodocs-code .ge{font-style:italic}.infodocs-code .gs,.infodocs-code .gh,.infodocs-code .gu{font-weight:600}"
+      rules.join("\n")
+    end
+
+    def symbolize(hash)
+      (hash || {}).to_h.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/infodocs/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Infodocs
+  class Configuration
+    AUTH_MODES = %i[none basic devise].freeze
+
+    attr_reader :paths
+    attr_accessor :title, :auth, :basic_auth, :devise, :editable, :index_path, :stylesheets, :code_theme, :repo_url, :repo_branch, :page_authorize, :logo, :favicon, :head_html, :header_links, :mermaid_url
+
+    def initialize
+      @paths = []
+      @title = "Docs"
+      @auth = :none
+      @basic_auth = {}
+      @devise = {}
+      @editable = false
+      @code_theme = CodeTheme::DEFAULT
+      @page_authorize = nil
+      @mermaid_url = nil
+      @logo = nil
+      @favicon = nil
+      @head_html = nil
+      @header_links = []
+      @repo_url = nil
+      @repo_branch = "main"
+      @stylesheets = %w[tailwind]
+      @index_path = defined?(Rails) ? Rails.root.join("tmp/infodocs/index.sqlite3") : "tmp/infodocs/index.sqlite3"
+    end
+
+    def paths=(value)
+      sources = (value.is_a?(Array) ? value : [value]).compact.map { |entry| Source.wrap(entry) }
+      duplicate = sources.map(&:key).tally.find { |_key, count| count > 1 }&.first
+      raise Error, "Infodocs sources share the name #{duplicate.inspect}; give them different slugs" if duplicate && sources.size > 1
+
+      @paths = sources
+    end
+
+    def validate!
+      CodeTheme.resolve(code_theme)
+      unless header_links.is_a?(Array) && header_links.all? { |link| link.respond_to?(:to_hash) && link.to_hash.transform_keys(&:to_sym).values_at(:label, :url).none?(&:nil?) }
+        raise Error, "Infodocs header_links must be an array of { label:, url: } hashes"
+      end
+      raise Error, "Infodocs page_authorize must respond to #call" if page_authorize && !page_authorize.respond_to?(:call)
+
+      return if auth.respond_to?(:call) || AUTH_MODES.include?(auth)
+
+      raise Error, "Infodocs auth must be one of #{AUTH_MODES.inspect} or a callable, got #{auth.inspect}"
+    end
+  end
+end

data/lib/infodocs/engine.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Infodocs
+  class Engine < ::Rails::Engine
+    isolate_namespace Infodocs
+
+    initializer "infodocs.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    initializer "infodocs.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/javascript")
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+      end
+    end
+
+    initializer "infodocs.url_helpers" do
+      ActiveSupport.on_load(:action_view) { include Infodocs::UrlHelper }
+      ActiveSupport.on_load(:action_controller) { include Infodocs::UrlHelper }
+    end
+
+    config.after_initialize do
+      Infodocs.config.validate!
+    end
+
+    # Pick up edited .md files without restarting the server.
+    initializer "infodocs.reload" do |app|
+      next unless Rails.env.development?
+
+      app.config.to_prepare { Infodocs.reload! }
+    end
+  end
+end

data/lib/infodocs/link_checker.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Finds relative links to pages, anchors and files that do not exist.
+  class LinkChecker
+    Problem = Struct.new(:page, :target, :reason, keyword_init: true)
+
+    def initialize(tree)
+      @tree = tree
+      @headings = {}
+    end
+
+    def call
+      @tree.pages.sum([]) { |page| check(page) } + hidden_pages.sum([]) { |page| check(page) }
+    end
+
+    private
+
+    def hidden_pages
+      @tree.all_pages - @tree.pages
+    end
+
+    def check(page)
+      result = Renderer.new(page).call
+      problems = result.links.filter_map do |slug, anchor|
+        if @tree.find(slug).nil? && !@tree.node(slug)&.folder?
+          Problem.new(page: page, target: slug, reason: "page not found")
+        elsif anchor && !headings_of(slug).include?(anchor)
+          Problem.new(page: page, target: "#{slug}##{anchor}", reason: "anchor not found")
+        end
+      end
+      problems += result.embeds_missing.map { |path| Problem.new(page: page, target: path, reason: "embedded file not found") }
+      problems + result.assets.reject { |path| @tree.asset(path) }.map { |path| Problem.new(page: page, target: path, reason: "file not found") }
+    end
+
+    def headings_of(slug)
+      @headings[slug] ||= begin
+        page = @tree.find(slug)
+        page ? Renderer.new(page).call.headings : []
+      end
+    end
+  end
+end

data/lib/infodocs/linter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Infodocs
+  # Content checks beyond broken links (see LinkChecker): missing titles,
+  # unknown frontmatter keys, unreachable hidden pages and useless redirects.
+  class Linter
+    KNOWN_KEYS = %w[title description tags draft redirect_from].freeze
+    Problem = Struct.new(:page, :rule, :message, keyword_init: true)
+
+    def initialize(tree)
+      @tree = tree
+    end
+
+    def call
+      pages = @tree.all_pages
+      linked = pages.flat_map { |page| Renderer.new(page).call.links.map(&:first) }.to_set
+      visible = @tree.pages.to_set
+      redirects = Hash.new { |hash, key| hash[key] = [] }
+
+      problems = pages.flat_map do |page|
+        page.redirect_from.each { |old| redirects[old] << page }
+        check(page, linked, visible)
+      end
+
+      redirects.each do |old, owners|
+        owners.each { |page| problems << Problem.new(page: page, rule: "redirect", message: "redirect_from #{old.inspect} is shadowed by an existing page") } if @tree.find(old)
+        owners.drop(1).each { |page| problems << Problem.new(page: page, rule: "redirect", message: "redirect_from #{old.inspect} is also claimed by #{owners.first.relative_path}") }
+      end
+      problems
+    end
+
+    private
+
+    def check(page, linked, visible)
+      problems = []
+      unless page.frontmatter["title"] || page.body.match?(/^#\s+\S/)
+        problems << Problem.new(page: page, rule: "title", message: "no title: add a `# Heading` or a `title:` in the frontmatter")
+      end
+      (page.frontmatter.keys - KNOWN_KEYS).each do |key|
+        problems << Problem.new(page: page, rule: "frontmatter", message: "unknown frontmatter key #{key.inspect}")
+      end
+      if !visible.include?(page) && !page.draft? && !linked.include?(page.slug)
+        problems << Problem.new(page: page, rule: "orphan", message: "hidden page that no other page links to")
+      end
+      problems
+    end
+  end
+end

data/lib/infodocs/page.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Infodocs
+  # A single .md file. `slug` is the URL path without extension, relative to
+  # its source root and prefixed with the root's index when several roots exist.
+  class Page
+    FRONTMATTER = /\A---\s*\n(.*?)\n---\s*\n/m
+
+    attr_reader :file, :slug, :root, :manifest_tags
+
+    def self.normalize_tags(value)
+      list = value.is_a?(String) ? value.split(",") : Array(value)
+      list.map { |tag| tag.to_s.strip.downcase.gsub(/\s+/, "-") }.reject(&:empty?).uniq
+    end
+
+    def initialize(file:, slug:, root:, raw: nil, manifest_tags: [])
+      @raw = raw
+      @manifest_tags = self.class.normalize_tags(manifest_tags)
+      @file = Pathname(file)
+      @slug = slug
+      @root = Pathname(root)
+    end
+
+    def raw
+      @raw ||= file.read
+    end
+
+    # Atomic overwrite of the source file; the page object is not reused after.
+    def write(content)
+      temp = file.sub_ext(".md.tmp-#{Process.pid}")
+      temp.write(content.to_s.gsub("\r\n", "\n"))
+      File.rename(temp, file)
+    ensure
+      temp&.delete if temp&.exist?
+    end
+
+    def frontmatter
+      @frontmatter ||= begin
+        match = raw.match(FRONTMATTER)
+        data = match ? YAML.safe_load(match[1], permitted_classes: [Date, Time]) : nil
+        data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+      end
+    end
+
+    # Old URLs (slugs) of this page, from the `redirect_from:` frontmatter key.
+    def redirect_from
+      Array(frontmatter["redirect_from"]).map { |path| path.to_s.strip.delete_prefix("/").delete_suffix("/").delete_suffix(".md") }.reject(&:empty?)
+    end
+
+    # Adds a `redirect_from` entry to the file's frontmatter (creating the block if needed).
+    def add_redirect_from(old_slug)
+      return if old_slug.blank? || old_slug == slug || redirect_from.include?(old_slug)
+
+      data = frontmatter.dup
+      data["redirect_from"] = redirect_from + [old_slug]
+      block = data.to_yaml
+      content = raw.match?(FRONTMATTER) ? raw.sub(FRONTMATTER) { "#{block}---\n" } : "#{block}---\n\n#{raw}"
+      write(content)
+    end
+
+    # `draft: true` pages are only shown in development.
+    def draft?
+      frontmatter["draft"] == true
+    end
+
+    # Tags from the `tags:` frontmatter key plus those saved in the folder's `_tree.yml`.
+    def tags
+      (self.class.normalize_tags(frontmatter["tags"]) + manifest_tags).uniq
+    end
+
+    def body
+      @body ||= raw.sub(FRONTMATTER, "")
+    end
+
+    def title
+      frontmatter["title"] || body[/^#\s+(.+)$/, 1]&.strip || File.basename(slug).tr("-_", "  ").capitalize
+    end
+
+    # Frontmatter `description`, else the first plain paragraph.
+    def description
+      text = frontmatter["description"] ||
+             body.split(/\n{2,}/).map(&:strip).find { |block| !block.empty? && !block.start_with?("#", "```", "|", ">", "-", "*", "<", "!") }
+      text.to_s.gsub(/\s+/, " ").gsub(/\[([^\]]*)\]\([^)]*\)/, '\\1').delete("*`_").strip.truncate(200)
+    end
+
+    # Directory the file lives in, as a slug; relative links resolve against it.
+    def directory_slug
+      landing? ? slug : File.dirname(slug).sub(/\A\.\z/, "")
+    end
+
+    def landing?
+      %w[index readme].include?(file.basename(".md").to_s.downcase)
+    end
+
+    # Last commit touching the file; file mtime when git has no answer.
+    def updated_at
+      out = IO.popen(["git", "log", "-1", "--format=%cI", "--", file.to_s], chdir: file.dirname.to_s, err: File::NULL, &:read).to_s.strip
+      out.empty? ? mtime : Time.iso8601(out)
+    rescue SystemCallError, ArgumentError
+      mtime
+    end
+
+    # Browser URL of the file in the repository (config.repo_url), or nil.
+    def repo_edit_url(repo_url, branch, base)
+      return if repo_url.blank?
+
+      relative = file.expand_path.relative_path_from(Pathname(base).expand_path).to_s
+      return if relative.start_with?("..")
+
+      "#{repo_url.to_s.chomp('/')}/edit/#{branch}/#{relative}"
+    end
+
+    def mtime
+      file.mtime
+    end
+
+    def relative_path
+      file.relative_path_from(root).to_s
+    end
+  end
+end

data/lib/infodocs/rails_lexer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rouge"
+
+module Infodocs
+  # Ruby plus the Rails DSL (associations, callbacks, routes, migrations…)
+  # highlighted as builtins. Use ```rails (or ```ruby: it is the same lexer).
+  class RailsLexer < Rouge::Lexers::Ruby
+    title "Rails"
+    desc "Ruby on Rails (Ruby with Rails DSL keywords)"
+    tag "rails"
+    aliases "rb-rails", "rails-ruby"
+    filenames "Rakefile", "*.rake", "*.rb", "*.ru", "Gemfile", "*.gemspec", "*.jbuilder"
+
+    DSL = %w[
+      belongs_to has_one has_many has_and_belongs_to_many has_one_attached has_many_attached has_rich_text
+      validates validates_presence_of validates_uniqueness_of validate validates_with
+      before_validation after_validation before_save around_save after_save
+      before_create around_create after_create before_update around_update after_update
+      before_destroy around_destroy after_destroy
+      after_commit after_rollback after_create_commit after_update_commit after_destroy_commit after_save_commit
+      after_initialize after_find after_touch
+      before_action after_action around_action skip_before_action prepend_before_action
+      scope default_scope enum delegate attribute store_accessor serialize normalizes accepts_nested_attributes_for
+      has_secure_password has_secure_token broadcasts_to
+      resources resource namespace scope member collection concern concerns mount root get post put patch delete match
+      draw devise_for
+      create_table drop_table change_table add_column remove_column rename_column change_column add_index remove_index
+      add_reference remove_reference add_foreign_key remove_foreign_key create_join_table
+      render redirect_to respond_to head redirect_back
+      permit require expect params
+      class_attribute included extended prepend_view_path helper_method layout rescue_from
+    ].freeze
+
+    prepend :root do
+      rule %r/(?<![.:@$\w])(?:#{DSL.join('|')})\b(?!:)/, Name::Builtin, :expr_start
+    end
+  end
+end