asciidoc-pubkit 0.8.7 → 1.0.0

data/docs/writing.md

@@ -0,0 +1,24 @@
+# Writing commands
+
+`writing criteria` prints the packaged common criteria. `writing prompt` adds
+task instructions around those same criteria. Neither command needs an AsciiDoc
+file, a review session, MeCab, or network access. Both accept `--lang ja` and
+`--output FILE`; output defaults to stdout, and an existing output file is never
+overwritten. The prompt asks the agent to read project instructions and evidence;
+it does not supply source facts or authorize edits. Book-specific voice and
+format still come from the book. The OSS-only prose style profile remains with
+the book workflow, not the shared default.
+
+```sh
+asciidoc-pubkit writing criteria --lang ja
+asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
+```
+
+For example, `--lang en` exits with an unsupported-language error. No English
+review or writing criteria are shipped in 1.0.0.
+
+For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
+paragraphs deliberately contain review candidates; its code block must remain
+unchanged.
+
+[Back to README](../README.md)

data/lib/asciidoc_pubkit/cli.rb

@@ -6,6 +6,10 @@ module AsciidocPubkit
       Usage: asciidoc-pubkit <group> <command> [options] [input]
 
       Commands:
+        document toc FILE      Print the parsed section outline
+        document info FILE     Extract book metadata
+        document check-xrefs FILE  Report unresolved local cross-references
+        document index DIRECTORY  Generate an English-title AsciiDoc index
         writing criteria      Print the shared Japanese prose criteria
         writing prompt        Generate a Japanese technical writing prompt
         review scan FILE       Collect Japanese prose, headings, or list text and review candidates
@@ -32,11 +36,14 @@ module AsciidocPubkit
         out.puts VERSION
         return 0
       end
-      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing replace].any? { |group| args == [group, '--help'] }
+      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing replace document].any? { |group| args == [group, '--help'] }
         out.puts HELP
         return 0
       end
       group, command = args.shift(2)
+      if group == 'document' && %w[toc info check-xrefs index].include?(command)
+        return DocumentCommands.run(command, args, out: out, err: err)
+      end
       valid = (group == 'review' && %w[scan score prompt verify].include?(command)) ||
               (group == 'writing' && %w[criteria prompt].include?(command)) ||
               (group == 'replace' && %w[check diff apply].include?(command))

data/lib/asciidoc_pubkit/document_commands.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module AsciidocPubkit
+  # Read-only document utilities, independent of Japanese review settings.
+  class DocumentCommands
+    METADATA = %w[subtitle description keywords lang uuid author producer creator].freeze
+
+    def self.run(command, args, out:, err:)
+      options = { attributes: {} }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: asciidoc-pubkit document #{command} [options] #{command == 'index' ? 'DIRECTORY' : 'FILE'}"
+        opts.on('-o', '--output FILE', 'New output file (default: standard output)') { |v| options[:output] = v }
+        opts.on('--base-dir DIR', 'Local include boundary (default: input directory)') { |v| options[:base_dir] = v }
+        opts.on('-a', '--attribute NAME=VALUE', 'Set an Asciidoctor attribute; repeat as needed') do |v|
+          key, value = v.split('=', 2)
+          raise Error, 'Attribute name cannot be empty.' if key.empty?
+          raise Error, 'Remote includes are not supported.' if key == 'allow-uri-read'
+          options[:attributes][key] = value || ''
+        end
+        if command == 'toc'
+          opts.on('--depth N', 'Maximum section level (positive integer)') do |v|
+            raise Error, 'Depth must be a positive integer.' unless v.match?(/\A[1-9][0-9]*\z/)
+            options[:depth] = v.to_i
+          end
+          opts.on('-n', '--numbered', 'Output outline numbers such as 1-2') { options[:numbered] = true }
+        elsif command == 'index'
+          opts.on('-t', '--title TITLE', 'Prepend an AsciiDoc index title') { |v| options[:title] = v }
+        else
+          opts.on('--json', 'Output JSON') { options[:json] = true }
+        end
+        opts.on('-h', '--help', 'Show command help') { options[:help] = true }
+      end
+      parser.parse!(args)
+      if options[:help]
+        out.puts parser
+        return 0
+      end
+      raise Error, 'Exactly one input is required. Use --help.' unless args.length == 1
+      if options[:output] && (File.exist?(options[:output]) || File.symlink?(options[:output]))
+        raise Error, "Output already exists: #{options[:output]}"
+      end
+      tool = new(options, err)
+      code = 0
+      if command == 'index'
+        content = tool.index(args.first)
+      else
+        doc = tool.load(args.first)
+        case command
+        when 'toc'
+          content = tool.toc(doc)
+        when 'info'
+          metadata = { 'doctitle' => doc.doctitle(sanitize: true).to_s.strip }
+          METADATA.each { |key| metadata[key] = doc.attr(key).to_s.strip }
+          content = options[:json] ? JSON.pretty_generate(metadata) + "\n" : metadata.map { |k, v| "#{k}: #{v}\n" }.join
+        when 'check-xrefs'
+          missing = tool.check_xrefs(doc)
+          code = missing.empty? ? 0 : 1
+          content = options[:json] ? JSON.pretty_generate(missing) + "\n" : missing.map { |item| "#{item['file']}:#{item['line'] || '?'}\t#{item['refid']}\n" }.join
+        end
+      end
+      CLI.output(content, options[:output], out)
+      code
+    end
+
+    def initialize(options, err)
+      @options, @err = options, err
+    end
+
+    def load(file, default_root: nil)
+      entry = File.realpath(file)
+      root = File.realpath(@options[:base_dir] || default_root || File.dirname(entry))
+      raise Error, "Base directory is not a directory: #{root}" unless File.directory?(root)
+      check_source(entry, root)
+      logger = Asciidoctor::MemoryLogger.new
+      previous = Asciidoctor::LoggerManager.logger
+      begin
+        Asciidoctor::LoggerManager.logger = logger
+        doc = Asciidoctor.load_file(entry, safe: :safe, sourcemap: true, parse: false,
+                                   base_dir: root, attributes: @options[:attributes])
+        owner = self
+        # Reject targets before Asciidoctor can clamp an outside path into its
+        # safe-mode jail, and before reading any remote or symlinked source.
+        doc.reader.define_singleton_method(:resolve_include_path) do |target, attrlist, attributes|
+          raise Error, 'Remote includes are not supported.' if Asciidoctor::Helpers.uriish?(target)
+          candidate = File.expand_path(target, dir)
+          unless candidate.start_with?(root.end_with?('/') ? root : root + '/')
+            raise Error, "Include is outside the base directory: #{target}"
+          end
+          owner.check_source(candidate, root) if File.file?(candidate)
+          super(target, attrlist, attributes)
+        end
+        doc.reader.define_singleton_method(:push_include) do |*args|
+          owner.check_source(args[1], root) if args[1] && File.file?(args[1])
+          super(*args)
+        end
+        doc.parse
+      ensure
+        Asciidoctor::LoggerManager.logger = previous
+      end
+      messages = logger.messages
+      messages.each { |m| @err.puts "#{m[:severity]}: #{m[:message]}" }
+      raise Error, "Failed to parse document: #{entry}" if messages.any? { |m| %i[ERROR FATAL].include?(m[:severity]) }
+      doc
+    end
+
+    def check_source(file, root)
+      path = File.realpath(file)
+      raise Error, "Source is outside the base directory: #{path}" unless path.start_with?(root.end_with?('/') ? root : root + '/')
+      AsciidocPubkit.read_text(path)
+    end
+
+    def toc(doc)
+      lines = []
+      walk = lambda do |sections, prefix, nesting|
+        sections.each_with_index do |section, index|
+          number = prefix + [index + 1]
+          if !@options[:depth] || section.level <= @options[:depth]
+            title = section.title
+            lines << (@options[:numbered] ? "#{number.join('-')}. #{title}" : "#{'  ' * nesting}#{title}")
+            walk.call(section.sections, number, nesting + 1)
+          end
+        end
+      end
+      walk.call(doc.sections, [], 0)
+      lines.empty? ? '' : lines.join("\n") + "\n"
+    end
+
+    def index(directory)
+      root = File.realpath(directory)
+      raise Error, "Input is not a directory: #{directory}" unless File.directory?(root)
+      entries = []
+      Find.find(root) do |path|
+        if File.directory?(path)
+          Find.prune if path != root && File.basename(path).start_with?('.')
+          next
+        end
+        next unless File.extname(path) == '.adoc'
+        next if @options[:output] && File.expand_path(path) == File.expand_path(@options[:output])
+        doc = load(path, default_root: root)
+        next if doc.id.to_s.empty?
+        title = doc.doctitle(sanitize: true).to_s.gsub(/\s*\([^)]*\)/, '').split(/[：:]/, 2).first.to_s.gsub(/\s+/, ' ').strip
+        next unless title.ascii_only? && title.match?(/[A-Za-z]/)
+        entries << { id: doc.id, title: title, path: Pathname.new(path).relative_path_from(Pathname.new(root)).to_s }
+      end
+      selected = entries.sort_by { |e| [e[:path].count('/'), e[:path]] }.each_with_object({}) { |e, memo| memo[e[:title].downcase] ||= e }
+      lines = []
+      if @options[:title]
+        raise Error, 'Index title must be a nonempty single line.' if @options[:title].strip.empty? || @options[:title].match?(/[\r\n]/)
+        lines.concat(['[#book-index]', "= #{@options[:title]}"])
+      end
+      selected.values.sort_by { |e| [e[:title].downcase, e[:path]] }.group_by { |e| e[:title][/[A-Za-z]/].upcase }.each do |letter, group|
+        lines << '' unless lines.empty?
+        lines.concat(['[discrete]', "=== #{letter}"])
+        group.each { |e| lines << "* <<#{e[:id]},#{e[:title]}>>" }
+      end
+      lines.empty? ? '' : lines.join("\n") + "\n"
+    end
+
+    # Scan raw AST fields only where macro substitutions are active. Converted
+    # text would hide xref targets; source-wide matching would include comments/code.
+    def check_xrefs(doc)
+      missing = []
+      nodes = doc.find_by.dup
+      nodes.select { |node| node.context == :table }.each do |table|
+        [table.rows.head, table.rows.body, table.rows.foot].flatten.each do |cell|
+          nodes << cell
+          nodes.concat(cell.inner_document.find_by) if cell.inner_document
+        end
+      end
+      nodes.each do |node|
+        cursor = node.source_location
+        if node.respond_to?(:subs) && node.subs.include?(:macros)
+          if node.respond_to?(:lines)
+            node.lines.each_with_index { |line, i| scan_refs(line, node, cursor, i, doc, missing) }
+          elsif node.instance_variable_defined?(:@text)
+            scan_refs(node.instance_variable_get(:@text), node, cursor, 0, doc, missing)
+          end
+        end
+        title = node.instance_variable_get(:@title)
+        scan_refs(title, node, cursor, 0, doc, missing) if title
+      end
+      missing.uniq { |m| m.values_at('file', 'line', 'refid') }.sort_by { |m| [m['file'], m['line'] || 0, m['refid']] }
+    end
+
+    def scan_refs(text, node, cursor, offset, doc, missing)
+      text = node.apply_subs(text, [:attributes])
+      targets = text.scan(/(?<!\\)xref:([^\[]+)\[(?:\\.|[^\]\\])*\]/).map { |m| [m.first, :macro] }
+      targets.concat(text.scan(/(?<!\\)<<(.+?)>>/).map { |m| [m.first.split(',', 2).first, :short] })
+      targets.each do |target, kind|
+        target = target.strip
+        if target.include?('#')
+          path, id = target.split('#', 2)
+          next unless path.empty? || local_path?(path, doc, cursor)
+        else
+          next if kind == :macro && !File.extname(target).empty?
+          id = target
+        end
+        next if id.to_s.empty? || doc.catalog[:refs].key?(id) || doc.resolve_id(id)
+        missing << { 'refid' => id, 'file' => cursor&.file || doc.attr('docfile'), 'line' => cursor && cursor.lineno + offset }
+      end
+    end
+
+    def local_path?(path, doc, cursor)
+      return false if path.match?(/\A[a-z][a-z0-9+.-]*:/i)
+      normalized = path.sub(/\.(?:adoc|asciidoc|asc|ad)\z/, '')
+      files = [doc.attr('docfile')] + doc.catalog[:includes].keys
+      files.any? do |file|
+        candidate = File.expand_path(file, doc.base_dir).sub(/\.(?:adoc|asciidoc|asc|ad)\z/, '')
+        [doc.base_dir, cursor&.file && File.dirname(cursor.file)].compact.any? { |base| candidate == File.expand_path(normalized, base) }
+      end
+    end
+  end
+end

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.8.7'
+  VERSION = '1.0.0'
   class Error < StandardError; end
 
   def self.hash_text(text)
@@ -35,4 +35,5 @@ require_relative 'asciidoc_pubkit/session'
 require_relative 'asciidoc_pubkit/local_evaluator'
 require_relative 'asciidoc_pubkit/score'
 require_relative 'asciidoc_pubkit/replacement'
+require_relative 'asciidoc_pubkit/document_commands'
 require_relative 'asciidoc_pubkit/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoc-pubkit
 version: !ruby/object:Gem::Version
-  version: 0.8.7
+  version: 1.0.0
 platform: ruby
 authors:
 - CyberGarage
@@ -37,9 +37,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Generate Japanese technical writing prompts, review AsciiDoc prose, section
-  headings, and list text separately, verify protected manuscript content, and explicitly
-  apply prose-only mechanical replacements.
+description: Inspect AsciiDoc outlines, book metadata, and local cross-references,
+  generate English document-title indexes, and generate Japanese technical writing
+  prompts, review AsciiDoc prose, section headings, and list text separately, verify
+  protected manuscript content, and explicitly apply prose-only mechanical replacements.
 executables:
 - asciidoc-pubkit
 extensions: []
@@ -52,12 +53,27 @@ files:
 - data/review-rules.ja.yml
 - data/writing/ja/criteria.md
 - data/writing/ja/headings.md
+- docs/architecture.md
+- docs/configuration.md
+- docs/custom-rules.md
+- docs/development.md
+- docs/document-commands.md
+- docs/english-review-research.md
+- docs/installation.md
+- docs/list-review.md
+- docs/references.md
+- docs/replacements.md
+- docs/review-workflow.md
+- docs/rules-and-coverage.md
+- docs/scoring.md
+- docs/writing.md
 - examples/book.adoc
 - examples/replacements.yml
 - exe/asciidoc-pubkit
 - lib/asciidoc_pubkit.rb
 - lib/asciidoc_pubkit/cli.rb
 - lib/asciidoc_pubkit/document.rb
+- lib/asciidoc_pubkit/document_commands.rb
 - lib/asciidoc_pubkit/heading_rules.rb
 - lib/asciidoc_pubkit/language.rb
 - lib/asciidoc_pubkit/local_evaluator.rb
@@ -91,5 +107,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: Japanese writing and review tools for AsciiDoc books
+summary: Document inspection, replacement, and Japanese review tools for AsciiDoc
+  books
 test_files: []