ligarb 0.6.0 → 0.8.0

data/lib/ligarb/config.rb

@@ -6,20 +6,57 @@ module Ligarb
   class Config
     REQUIRED_KEYS = %w[title chapters].freeze
 
+    # Keys that can be inherited from a parent (translations hub) config.
+    # output_dir is intentionally excluded — it always comes from the
+    # config file that was directly passed to `ligarb build`.
+    INHERITABLE_KEYS = %w[author language chapter_numbers style
+                          repository ai_generated footer bibliography
+                          github_review].freeze
+
     # Represents a structural entry in the book
     StructEntry = Struct.new(:type, :path, :children, keyword_init: true)
     # type: :chapter, :part, or :appendix_group
     # path: markdown file path (for :chapter and :part), nil for :appendix_group
     # children: array of StructEntry (for :part and :appendix_group)
 
+    # Represents a translation entry
+    # output_path: absolute path to the translation's build directory (for link generation)
+    TranslationEntry = Struct.new(:lang, :config_path, :title, :language, :output_path, keyword_init: true)
+
     attr_reader :title, :author, :language, :output_dir, :base_dir,
                 :chapter_numbers, :structure, :style, :repository,
-                :ai_generated, :footer, :bibliography, :sources
+                :ai_generated, :footer, :bibliography, :sources,
+                :translations, :github_review
 
-    def initialize(path)
+    def initialize(path, parent_data: nil)
       @base_dir = File.dirname(File.expand_path(path))
       data = YAML.safe_load_file(path)
 
+      # If this is a translations hub (has translations but no chapters), skip normal validation
+      if data.is_a?(Hash) && data.key?("translations") && !data.key?("chapters")
+        @translations_hub = true
+        @translations_data = data
+        load_translations_hub(data)
+        return
+      end
+
+      # Load inherit file if specified (for standalone builds of child configs)
+      if !parent_data && data.is_a?(Hash) && data.key?("inherit")
+        inherit_path = File.expand_path(data["inherit"], @base_dir)
+        if File.exist?(inherit_path)
+          parent_data = YAML.safe_load_file(inherit_path)
+        else
+          abort "Error: inherit config not found: #{inherit_path}"
+        end
+      end
+
+      # Merge parent (inheritable) keys as defaults
+      if parent_data
+        INHERITABLE_KEYS.each do |key|
+          data[key] = parent_data[key] if parent_data.key?(key) && !data.key?(key)
+        end
+      end
+
       validate!(data)
 
       @title           = data["title"]
@@ -32,8 +69,16 @@ module Ligarb
       @ai_generated    = data.fetch("ai_generated", false)
       @footer          = data.fetch("footer", nil)
       @bibliography    = data.fetch("bibliography", nil)
+      @github_review   = data.fetch("github_review", nil)
       @sources         = parse_sources(data.fetch("sources", []))
       @structure       = parse_structure(data["chapters"])
+      @translations    = []
+
+      load_translations(data, path) if data.key?("translations")
+    end
+
+    def translations_hub?
+      @translations_hub == true
     end
 
     def output_path
@@ -52,6 +97,23 @@ module Ligarb
       @language == "ja" ? "付録" : "Appendix"
     end
 
+    # Whether the reader's "Report as issue" feedback UI is requested in book.yml.
+    # This reflects intent only; actual injection also requires `repository`
+    # (the issues/new base) — the builder warns and skips when it is missing.
+    def github_review_enabled?
+      @github_review.is_a?(Hash) && @github_review.fetch("enabled", false) == true
+    end
+
+    def github_review_issue_template
+      tmpl = @github_review.is_a?(Hash) ? @github_review["issue_template"] : nil
+      tmpl && !tmpl.to_s.empty? ? tmpl.to_s : "book-feedback.yml"
+    end
+
+    def github_review_labels
+      labels = @github_review.is_a?(Hash) ? @github_review["labels"] : nil
+      Array(labels || ["feedback"]).map(&:to_s)
+    end
+
     def effective_footer
       return @footer if @footer
       return nil unless @ai_generated
@@ -137,6 +199,66 @@ module Ligarb
       collect_chapter_paths(entries)
     end
 
+    def load_translations(data, config_path)
+      trans = data["translations"]
+      return unless trans.is_a?(Hash)
+
+      trans.each do |lang, rel_path|
+        abs_path = File.expand_path(rel_path, @base_dir)
+        unless File.exist?(abs_path)
+          abort "Error: translation config not found: #{abs_path}"
+        end
+        child_data = YAML.safe_load_file(abs_path)
+        # Merge parent keys for output_dir resolution
+        INHERITABLE_KEYS.each do |key|
+          child_data[key] = data[key] if data.key?(key) && !child_data.key?(key)
+        end
+        child_title = child_data["title"] || @title
+        child_lang = child_data.fetch("language", lang)
+        child_base = File.dirname(abs_path)
+        child_output = File.join(child_base, child_data.fetch("output_dir", "build"))
+        @translations << TranslationEntry.new(
+          lang: lang,
+          config_path: abs_path,
+          title: child_title,
+          language: child_lang,
+          output_path: child_output
+        )
+      end
+    end
+
+    def load_translations_hub(data)
+      @title = data.fetch("title", "")
+      @translations = []
+
+      trans = data["translations"]
+      return unless trans.is_a?(Hash)
+
+      trans.each do |lang, rel_path|
+        abs_path = File.expand_path(rel_path, @base_dir)
+        unless File.exist?(abs_path)
+          abort "Error: translation config not found: #{abs_path}"
+        end
+        child_data = YAML.safe_load_file(abs_path)
+        # Merge inheritable keys from hub as defaults
+        merged = child_data.dup
+        INHERITABLE_KEYS.each do |key|
+          merged[key] = data[key] if data.key?(key) && !merged.key?(key)
+        end
+        child_title = merged["title"] || @title
+        child_lang = merged.fetch("language", lang)
+        child_base = File.dirname(abs_path)
+        child_output = File.join(child_base, merged.fetch("output_dir", "build"))
+        @translations << TranslationEntry.new(
+          lang: lang,
+          config_path: abs_path,
+          title: child_title,
+          language: child_lang,
+          output_path: child_output
+        )
+      end
+    end
+
     def validate!(data)
       unless data.is_a?(Hash)
         abort "Error: book.yml must be a YAML mapping"
@@ -151,6 +273,10 @@ module Ligarb
       unless data["chapters"].is_a?(Array) && !data["chapters"].empty?
         abort "Error: 'chapters' must be a non-empty array"
       end
+
+      if data.key?("github_review") && !data["github_review"].is_a?(Hash)
+        abort "Error: 'github_review' must be a mapping (e.g. { enabled: true })"
+      end
     end
   end
 end

data/lib/ligarb/github_review.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Ligarb
+  # Sets up the GitHub-based review scaffolding (.github/ + SETUP.md) in a
+  # project — the `ligarb setup-github-review` command. This is pure file
+  # copying: ligarb never calls Claude or GitHub at runtime. The templates are
+  # classified into layers so a future option could split them apart:
+  #   - generic layer  : works without Claude (Pages deploy, build check, forms)
+  #   - claude layer    : opt-in Claude integration (issue/PR handlers, SETUP.md)
+  #
+  # Re-running OVERWRITES the generated files so a project can follow upstream
+  # template changes (e.g. after a ligarb upgrade). The user's own book.yml is
+  # never overwritten. Since projects are git repos, `git diff` is the safety
+  # net for reviewing/reverting changes after a re-sync.
+  class GithubReview
+    TEMPLATE_DIR = File.expand_path("../../templates/github_review", __dir__)
+
+    # Generic layer: no Claude dependency.
+    GENERIC_FILES = %w[
+      .github/workflows/deploy-book.yml
+      .github/workflows/build-check.yml
+      .github/ISSUE_TEMPLATE/book-feedback.yml
+      .github/ISSUE_TEMPLATE/config.yml
+    ].freeze
+
+    # Claude integration layer: opt-in.
+    CLAUDE_FILES = %w[
+      .github/workflows/claude-feedback.yml
+      .github/workflows/claude-pr-mention.yml
+      SETUP.md
+      SETUP.sh
+    ].freeze
+
+    TEMPLATE_FILES = (GENERIC_FILES + CLAUDE_FILES).freeze
+
+    Result = Struct.new(:created, :updated, :unchanged, keyword_init: true)
+
+    # `ligarb setup-github-review [DIR]` entry point. Sets up the scaffolding in
+    # an existing ligarb project (book.yml must exist), enables the reader
+    # feedback UI in book.yml, and prints the remaining manual-setup steps.
+    # Safe to re-run to pull in updated templates (generated files are
+    # overwritten; book.yml is not).
+    def self.run(directory = nil)
+      target = File.expand_path(directory || ".")
+      unless File.exist?(File.join(target, "book.yml"))
+        $stderr.puts "Error: book.yml not found in #{target}"
+        $stderr.puts "Run 'ligarb init' or 'ligarb write' first, then set up the GitHub review scaffolding."
+        exit 1
+      end
+
+      reviewer = new(target)
+      # book.yml edits must run BEFORE generate so the templates (SETUP.sh,
+      # issue forms, README) are substituted with the resolved repository.
+      repository = reviewer.ensure_repository_in_book_yml
+      enabled = reviewer.enable_in_book_yml
+      readme = reviewer.create_readme_if_absent
+      result = reviewer.generate
+      reviewer.print_notice(result, repository: repository, enabled: enabled, readme: readme)
+    end
+
+    def initialize(target)
+      @target = File.expand_path(target)
+    end
+
+    # Writes all template files into the project, substituting __OWNER__ /
+    # __REPO__ from book.yml's `repository:`. Existing files are OVERWRITTEN so a
+    # project can follow upstream template changes; only files whose content is
+    # already identical are left untouched. Returns a Result listing
+    # created/updated/unchanged files.
+    def generate
+      owner, repo = extract_owner_repo
+      created = []
+      updated = []
+      unchanged = []
+
+      TEMPLATE_FILES.each do |rel|
+        dest = File.join(@target, rel)
+        content = render(rel, File.read(File.join(TEMPLATE_DIR, rel)), owner, repo)
+
+        if !File.exist?(dest)
+          write_file(dest, content)
+          created << rel
+        elsif File.read(dest) == content
+          unchanged << rel
+        else
+          write_file(dest, content)
+          updated << rel
+        end
+      end
+
+      Result.new(created: created, updated: updated, unchanged: unchanged)
+    end
+
+    # Ensures `github_review.enabled: true` is present in book.yml so the reader
+    # feedback UI activates (once `repository` is also set). Appends the key only
+    # when absent, preserving existing formatting/comments. Returns :added,
+    # :present, or :unsupported (translations hub / unparsable).
+    def enable_in_book_yml
+      book_yml = File.join(@target, "book.yml")
+      data = YAML.safe_load_file(book_yml)
+      return :unsupported unless data.is_a?(Hash)
+      return :present if data.key?("github_review")
+
+      content = File.read(book_yml).rstrip
+      File.write(book_yml, "#{content}\n\ngithub_review:\n  enabled: true\n")
+      :added
+    end
+
+    # Seeds a default `repository:` in book.yml when it has none, guessing
+    # https://github.com/<os-user>/<dir-name>. This drives __OWNER__/__REPO__
+    # substitution and the GH Pages link; the user edits it if the guess is
+    # wrong. Returns :added, :present, or :unsupported. (@default_repository is
+    # set to the guessed URL when :added, for the notice.)
+    def ensure_repository_in_book_yml
+      book_yml = File.join(@target, "book.yml")
+      data = YAML.safe_load_file(book_yml)
+      return :unsupported unless data.is_a?(Hash)
+      return :present if data.key?("repository")
+
+      user = ENV["USER"] || ENV["USERNAME"] || "your-github-account"
+      @default_repository = "https://github.com/#{user}/#{File.basename(@target)}"
+      content = File.read(book_yml).rstrip
+      File.write(book_yml, %(#{content}\n\nrepository: "#{@default_repository}"\n))
+      :added
+    end
+
+    # Creates a project README.md that links to the published GitHub Pages site,
+    # but only when one does not already exist (the reader's own README is never
+    # overwritten). Returns :created or :present.
+    def create_readme_if_absent
+      readme = File.join(@target, "README.md")
+      return :present if File.exist?(readme)
+
+      owner, repo = extract_owner_repo
+      pages  = owner && repo ? "https://#{owner}.github.io/#{repo}/" : "https://__OWNER__.github.io/__REPO__/"
+      issues = owner && repo ? "https://github.com/#{owner}/#{repo}/issues/new?template=book-feedback.yml" \
+                             : "https://github.com/__OWNER__/__REPO__/issues/new?template=book-feedback.yml"
+      title = book_title.to_s.empty? ? "Book" : book_title
+
+      File.write(readme, <<~MD)
+        # #{title}
+
+        📖 **公開版（GitHub Pages）**: #{pages}
+
+        この本は [ligarb](https://github.com/ko1/ligarb) で生成しています。
+
+        ## フィードバック
+
+        本文の誤り・わかりにくい点・疑問は [Issue](#{issues}) からどうぞ。
+        公開ページでは本文を選択して「Report as issue」からも送れます。
+
+        ## ローカルでビルド
+
+        ```bash
+        ligarb build   # build/index.html を生成
+        ligarb serve   # ローカルプレビュー
+        ```
+
+        セットアップ手順は [SETUP.md](SETUP.md) を参照してください。
+      MD
+      :created
+    end
+
+    def print_notice(result, repository:, enabled:, readme:)
+      puts "Set up GitHub review scaffolding in #{@target}:"
+      result.created.each { |path| puts "  created    #{path}" }
+      result.updated.each { |path| puts "  updated    #{path}" }
+      puts "  created    README.md (with the GitHub Pages link)" if readme == :created
+      case repository
+      when :added then puts "  updated    book.yml (repository: #{@default_repository})"
+      end
+      case enabled
+      when :added   then puts "  updated    book.yml (github_review.enabled: true)"
+      when :present then puts "  kept       book.yml github_review setting"
+      end
+      unless result.unchanged.empty?
+        puts "  unchanged  #{result.unchanged.size} file(s) already up to date"
+      end
+      if result.updated.any?
+        puts
+        puts "Note: existing scaffolding files were overwritten with the latest"
+        puts "templates. Review with 'git diff' and revert any local edits you"
+        puts "want to keep."
+      end
+      puts
+      puts "Next: edit 'repository:' in book.yml if the guess is wrong, then run"
+      puts "the gh CLI quickstart:"
+      puts "  bash SETUP.sh    # repo create + secret + Pages + permissions + labels"
+      puts
+      puts "It still needs a token (see SETUP.md): generate one with"
+      puts "'claude setup-token' before running SETUP.sh (it prompts for it)."
+    end
+
+    private
+
+    def write_file(dest, content)
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, content)
+      File.chmod(0o755, dest) if dest.end_with?(".sh")
+    end
+
+    def book_title
+      data = YAML.safe_load_file(File.join(@target, "book.yml"))
+      data.is_a?(Hash) ? data["title"] : nil
+    rescue StandardError
+      nil
+    end
+
+    # Substitute __OWNER__ / __REPO__ placeholders. When repository is unset we
+    # leave the placeholders as-is, except config.yml's Discussions link which
+    # we comment out so the issue chooser does not show a broken URL.
+    def render(rel, content, owner, repo)
+      if owner && repo
+        content.gsub("__OWNER__", owner).gsub("__REPO__", repo)
+      elsif rel == ".github/ISSUE_TEMPLATE/config.yml"
+        comment_out_contact_links(content)
+      else
+        content
+      end
+    end
+
+    def comment_out_contact_links(content)
+      content.lines.map { |line|
+        line.start_with?("contact_links:") || line.start_with?("  ") ? "# #{line}" : line
+      }.join
+    end
+
+    # Reads book.yml's `repository:` and extracts [owner, repo].
+    # Returns [nil, nil] when book.yml or repository is missing/unparsable.
+    def extract_owner_repo
+      book_yml = File.join(@target, "book.yml")
+      return [nil, nil] unless File.exist?(book_yml)
+
+      data = YAML.safe_load_file(book_yml)
+      url = data.is_a?(Hash) ? data["repository"] : nil
+      return [nil, nil] unless url.is_a?(String)
+
+      m = url.chomp("/").match(%r{github\.com[/:]([^/]+)/([^/]+?)(?:\.git)?\z})
+      m ? [m[1], m[2]] : [nil, nil]
+    end
+  end
+end

data/lib/ligarb/review_store.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 require "securerandom"
 require "fileutils"
 

data/lib/ligarb/template.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "erb"
+require "json"
 
 module Ligarb
   class Template
@@ -12,7 +13,7 @@ module Ligarb
       @css_path      = File.join(ASSETS_DIR, "style.css")
     end
 
-    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [])
+    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [], github_review: nil)
       css = File.read(@css_path)
       template = File.read(@template_path)
 
@@ -35,12 +36,97 @@ module Ligarb
       b.local_variable_set(:footer, config.effective_footer)
       b.local_variable_set(:index_tree, build_index_tree(index_entries, chapters))
       b.local_variable_set(:bibliography, bibliography)
+      b.local_variable_set(:multilang, false)
+      b.local_variable_set(:langs, [])
+      b.local_variable_set(:feedback, load_feedback(github_review))
+
+      ERB.new(template, trim_mode: "-").result(b)
+    end
+
+    # Render a single HTML with all languages, switchable via JS
+    def render_multilang(langs:, assets:, hub_data:, github_review: nil)
+      css = File.read(@css_path)
+      template = File.read(@template_path)
+
+      first = langs.first
+      first_config = first[:config]
+
+      custom_css = if first_config.style_path && File.exist?(first_config.style_path)
+                     File.read(first_config.style_path)
+                   end
+
+      # Build per-language template data
+      lang_data = langs.map do |ld|
+        cfg = ld[:config]
+        {
+          lang: ld[:lang],
+          title: cfg.title,
+          author: cfg.author,
+          language: cfg.language,
+          chapters: ld[:chapters],
+          structure: ld[:structure],
+          repository: cfg.repository,
+          appendix_label: cfg.appendix_label,
+          ai_generated: cfg.ai_generated,
+          footer: cfg.effective_footer,
+          index_tree: build_index_tree(ld[:index_entries], ld[:chapters]),
+          bibliography: ld[:bibliography],
+        }
+      end
+
+      b = binding
+      # Use first language's values as defaults for shared template vars
+      b.local_variable_set(:title, first_config.title)
+      b.local_variable_set(:author, first_config.author)
+      b.local_variable_set(:language, first_config.language)
+      b.local_variable_set(:chapters, first[:chapters])
+      b.local_variable_set(:structure, first[:structure])
+      b.local_variable_set(:css, css)
+      b.local_variable_set(:custom_css, custom_css)
+      b.local_variable_set(:assets, assets)
+      b.local_variable_set(:repository, first_config.repository)
+      b.local_variable_set(:appendix_label, first_config.appendix_label)
+      b.local_variable_set(:ai_generated, first_config.ai_generated)
+      b.local_variable_set(:footer, first_config.effective_footer)
+      b.local_variable_set(:index_tree, build_index_tree(first[:index_entries], first[:chapters]))
+      b.local_variable_set(:bibliography, first[:bibliography])
+      b.local_variable_set(:multilang, true)
+      b.local_variable_set(:langs, lang_data)
+      b.local_variable_set(:feedback, load_feedback(github_review))
 
       ERB.new(template, trim_mode: "-").result(b)
     end
 
     private
 
+    # When github_review (a hash with :base/:issue_template/:labels) is given,
+    # returns the inlined feedback assets + a JSON config blob for the template
+    # to embed; otherwise nil (the UI is not injected). Inlining keeps the build
+    # output self-contained, like the main style.css.
+    def load_feedback(github_review)
+      return nil unless github_review
+
+      config_json = JSON.generate(
+        base: github_review[:base],
+        issueTemplate: github_review[:issue_template],
+        labels: github_review[:labels]
+      ).gsub("</", '<\/')
+
+      {
+        css: File.read(File.join(ASSETS_DIR, "feedback.css")),
+        js: File.read(File.join(ASSETS_DIR, "feedback.js")),
+        config_json: config_json,
+      }
+    end
+
+    # data-src-* attributes for a chapter <section>, used by the feedback UI to
+    # locate the source Markdown. Empty unless the UI is active and the chapter
+    # has a resolved source path (set when `repository` is configured).
+    def src_attrs(chapter, feedback)
+      return "" unless feedback && chapter.relative_path
+      %( data-src-file="#{h(chapter.relative_path)}" data-src-title="#{h(chapter.display_title)}")
+    end
+
     # HTML-escape helper for ERB templates (available via binding)
     def h(s)
       ERB::Util.html_escape(s.to_s)

data/lib/ligarb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ligarb
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/ligarb/writer.rb

@@ -185,8 +185,8 @@ module Ligarb
       lines << "Create book.yml first, then each chapter .md file."
       lines << "Include a cover page for books with 4+ chapters."
       lines << "Each chapter: substantive content with multiple ## sections."
-      lines << "Use code blocks, admonitions, mermaid diagrams where appropriate."
-      lines << "Chapter filenames: 01-topic.md, 02-topic.md, etc."
+      lines << "Use code blocks, admonitions, and other ligarb features from the spec where appropriate."
+      lines << "Chapter filenames: topic-name.md (e.g. introduction.md, getting-started.md). Do NOT use number prefixes."
       lines << ""
       lines << "Create references.bib with real bibliography entries in BibTeX format."
       lines << "In book.yml, set: bibliography: references.bib"