ligarb 0.7.0 → 0.8.0

data/lib/ligarb/config.rb

@@ -10,7 +10,8 @@ module Ligarb
     # 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].freeze
+                          repository ai_generated footer bibliography
+                          github_review].freeze
 
     # Represents a structural entry in the book
     StructEntry = Struct.new(:type, :path, :children, keyword_init: true)
@@ -25,7 +26,7 @@ module Ligarb
     attr_reader :title, :author, :language, :output_dir, :base_dir,
                 :chapter_numbers, :structure, :style, :repository,
                 :ai_generated, :footer, :bibliography, :sources,
-                :translations
+                :translations, :github_review
 
     def initialize(path, parent_data: nil)
       @base_dir = File.dirname(File.expand_path(path))
@@ -68,6 +69,7 @@ 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    = []
@@ -95,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
@@ -254,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/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)
 
@@ -37,12 +38,13 @@ module Ligarb
       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:)
+    def render_multilang(langs:, assets:, hub_data:, github_review: nil)
       css = File.read(@css_path)
       template = File.read(@template_path)
 
@@ -90,12 +92,41 @@ module Ligarb
       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.7.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"

data/templates/book.html.erb

@@ -16,6 +16,11 @@
 <%= custom_css %>
 </style>
 <%- end -%>
+<%- if feedback -%>
+<style>
+<%= feedback[:css] %>
+</style>
+<%- end -%>
 <%- if assets.need?(:highlight) -%>
 <link rel="stylesheet" href="css/highlight.css">
 <%- end -%>
@@ -247,6 +252,11 @@
 <main class="content" id="content">
 <%- if multilang -%>
   <%- langs.each do |ld| -%>
+  <%- ld[:chapters].select(&:cover?).each do |chapter| -%>
+  <section class="chapter cover-page" id="chapter-<%= chapter.slug %>" data-lang="<%= ld[:lang] %>" style="display: none;">
+    <%= chapter.html %>
+  </section>
+  <%- end -%>
   <section class="chapter toc-page" id="chapter-<%= ld[:lang] %>--__toc__" data-lang="<%= ld[:lang] %>" style="display: none;">
     <h1><%= ld[:language] == 'ja' ? '目次' : 'Contents' %></h1>
     <nav class="toc-full">
@@ -297,8 +307,8 @@
     <%- end -%>
     </nav>
   </section>
-  <%- ld[:chapters].each_with_index do |chapter, idx| -%>
-  <section class="<%= chapter.cover? ? 'chapter cover-page' : 'chapter' %>" id="chapter-<%= chapter.slug %>" data-lang="<%= ld[:lang] %>" style="display: none;">
+  <%- ld[:chapters].reject(&:cover?).each_with_index do |chapter, idx| -%>
+  <section class="chapter" id="chapter-<%= chapter.slug %>" data-lang="<%= ld[:lang] %>"<%= src_attrs(chapter, feedback) %> style="display: none;">
     <%= chapter.html %>
     <%- if ld[:repository] && !chapter.part_title? && !chapter.cover? -%>
     <div class="edit-link">
@@ -358,6 +368,11 @@
   <%- end -%>
   <%- end -%>
 <%- else -%>
+  <%- chapters.select(&:cover?).each do |chapter| -%>
+  <section class="chapter cover-page" id="chapter-<%= chapter.slug %>" style="display: none;">
+    <%= chapter.html %>
+  </section>
+  <%- end -%>
   <section class="chapter toc-page" id="chapter-__toc__" style="display: none;">
     <h1><%= language == 'ja' ? '目次' : 'Contents' %></h1>
     <nav class="toc-full">
@@ -408,8 +423,8 @@
     <%- end -%>
     </nav>
   </section>
-  <%- chapters.each_with_index do |chapter, idx| -%>
-  <section class="<%= chapter.cover? ? 'chapter cover-page' : 'chapter' %>" id="chapter-<%= chapter.slug %>" style="display: none;">
+  <%- chapters.reject(&:cover?).each_with_index do |chapter, idx| -%>
+  <section class="chapter" id="chapter-<%= chapter.slug %>"<%= src_attrs(chapter, feedback) %> style="display: none;">
     <%= chapter.html %>
     <%- if repository && !chapter.part_title? && !chapter.cover? -%>
     <div class="edit-link">
@@ -475,7 +490,8 @@
 <%- if multilang -%>
   var langChapters = {
   <%- langs.each do |ld| -%>
-    "<%= ld[:lang] %>": ["<%= ld[:lang] %>--__toc__", <%= ld[:chapters].map { |c| "\"#{c.slug}\"" }.join(", ") %><%= ", \"#{ld[:lang]}--__bibliography__\"" unless ld[:bibliography].empty? %><%= ", \"#{ld[:lang]}--__index__\"" unless ld[:index_tree].empty? %>],
+    <%- ld_cover = ld[:chapters].find(&:cover?) -%>
+    "<%= ld[:lang] %>": [<%= "\"#{ld_cover.slug}\", " if ld_cover %>"<%= ld[:lang] %>--__toc__", <%= ld[:chapters].reject(&:cover?).map { |c| "\"#{c.slug}\"" }.join(", ") %><%= ", \"#{ld[:lang]}--__bibliography__\"" unless ld[:bibliography].empty? %><%= ", \"#{ld[:lang]}--__index__\"" unless ld[:index_tree].empty? %>],
   <%- end -%>
   };
   var allLangs = [<%= langs.map { |ld| "\"#{ld[:lang]}\"" }.join(", ") %>];
@@ -483,7 +499,8 @@
   if (allLangs.indexOf(currentLang) === -1) currentLang = allLangs[0];
   var chapters = langChapters[currentLang];
 <%- else -%>
-  var chapters = ["__toc__", <%= chapters.map { |c| "\"#{c.slug}\"" }.join(", ") %><%= ', "__bibliography__"' unless bibliography.empty? %><%= ', "__index__"' unless index_tree.empty? %>];
+  <%- cover_ch = chapters.find(&:cover?) -%>
+  var chapters = [<%= "\"#{cover_ch.slug}\", " if cover_ch %>"__toc__", <%= chapters.reject(&:cover?).map { |c| "\"#{c.slug}\"" }.join(", ") %><%= ', "__bibliography__"' unless bibliography.empty? %><%= ', "__index__"' unless index_tree.empty? %>];
 <%- end -%>
   var currentChapter = null;
 
@@ -1111,5 +1128,11 @@ renderSpecialBlocks();
 <script src="js/function-plot.min.js"></script>
 <script>renderSpecialBlocks();</script>
 <%- end -%>
+<%- if feedback -%>
+<script>window._ligarbReview = <%= feedback[:config_json] %>;</script>
+<script>
+<%= feedback[:js] %>
+</script>
+<%- end -%>
 </body>
 </html>

data/templates/github_review/.github/ISSUE_TEMPLATE/book-feedback.yml

@@ -0,0 +1,43 @@
+name: 本へのフィードバック
+description: 本文の誤り・わかりにくい点・疑問を報告する
+title: "[feedback] "
+labels: ["feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        本を読んで気づいた点を報告してください。
+        （ligarb の公開ページから「Report as issue」で来た場合、いくつかの項目は自動入力されています。）
+  - type: input
+    id: location
+    attributes:
+      label: 対象箇所
+      description: 章・節、ソースの Markdown ファイル名、公開サイトの該当 URL など
+      placeholder: "例: 第3章 2節 / 03-advanced.md / https://__OWNER__.github.io/__REPO__/#ch3-2"
+    validations:
+      required: true
+  - type: textarea
+    id: quote
+    attributes:
+      label: 引用テキスト
+      description: 問題の箇所を本文から引用してください
+      render: markdown
+    validations:
+      required: true
+  - type: dropdown
+    id: type
+    attributes:
+      label: 種類
+      options:
+        - 誤り（事実誤認・誤字・壊れたコード例など）
+        - わかりにくい（説明・構成・例の改善提案）
+        - 疑問（直す必要はないが確認したい）
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: 詳細
+      description: 何が問題か、どう直すとよいか、または何を確認したいか
+    validations:
+      required: true

data/templates/github_review/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 一般的な質問・議論
+    url: https://github.com/__OWNER__/__REPO__/discussions
+    about: 本の内容と関係ない質問や雑談はこちら（Discussions を有効にしている場合）

data/templates/github_review/.github/workflows/build-check.yml

@@ -0,0 +1,25 @@
+name: Build check
+
+# PR で ligarb build が通るかを検証する。Claude は関与しない。
+# このチェックを Settings > Branches の必須チェックに指定すると、
+# ビルドが落ちる PR を merge できなくできる。
+
+on:
+  pull_request:
+    branches: [master]   # main を使う場合はここを main に変更する
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+      - name: Install ligarb
+        run: gem install ligarb
+      - name: Build book
+        run: ligarb build   # 失敗すればチェックが落ちる