asciidoc-pubkit 0.8.6 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1fb57dff066c28a30d6205ad30ff8c5cd1a89fc27c35ec8379e9c80354843ae
-  data.tar.gz: 9431768603df5a8191ba93b0bc5773ad188050e06304e6f0f35272bbe132ef51
+  metadata.gz: 75fa596bc050de3a0b084f4072fa830156ea1b82e923aaf8d2e429c0d7735465
+  data.tar.gz: 3b510d7c39d8c2d418fd05b31feaf724fed8d246a61a7bc6adb316e9d3cea32b
 SHA512:
-  metadata.gz: 901984c71c8178ba62738e21ec67cb5585ebe72719ef06c03b38585c5ad7d0961a9fe4da78c47d1612e9c339d6170bee9a060ea4cf2cf68e9301ae4b80bb96ac
-  data.tar.gz: 70570e253745de217ba1d4eb2c5447a7a1dba2f72e3d1f5f1abb40787d54c996fa9dca3072bb190071a459346146200e5744e9eb5fa72f4410c9dd314af71333
+  metadata.gz: 7c1906759470ebd93a70f1960c575893ec68e9ecb8ded59786ea4871e4c790ad70acf5f38db7dcd11f6291f01338ba000aec1f4357848409b75f0ca15fc08a1f
+  data.tar.gz: 4d26fe3ad162a62e326729cd76f269d2b0d42a0c1329a0526f65cd99ef5ab6bcfb23b19b9b8fb25fedd2415ebdaf0ef1d97074732a4a2abcc0dcae3b96a20c0f

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.9.0 — 2026-10-03
+
+- Add read-only `document toc`, `document info`, `document check-xrefs`, and
+  `document index` commands without MeCab, review settings, or AI invocation.
+  Parse local includes and conditions within an explicit source boundary;
+  reject remote includes, parse errors, and existing output files. Support book
+  parts, strict depth selection, metadata JSON, local cross-reference diagnostics,
+  and deterministic English document-title indexes.
+
+- Introduce document inspection before prose replacements and review in the README.
+
+- Explain when optional list review is needed, why its scope is separate from
+  running prose, and how to preserve phase baselines in a complete review.
+
+## 0.8.7 — 2026-10-02
+
+- Make exact saved old-ID anchor permissions standard for eligible heading
+  scans. Remove `--preserve-heading-ids`; continue protecting existing anchors,
+  section IDs, structure, and body content. Existing session permissions and
+  baselines remain unchanged.
+- Tell prose reviewers in scan output and generated prompts to review list text
+  in a separate `--scope lists` session without replacing the prose baseline.
+
 ## 0.8.6 — 2026-10-02
 
 - Add separate `review scan --scope lists` sessions for source-mapped single-line

data/README.md

@@ -7,20 +7,24 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.8.6 provides shared Japanese technical writing criteria, an authoring
-prompt, separate prose, heading, and list review prompts, manuscript scoring, and
-baseline verification for edited manuscripts, plus explicit prose-only mechanical
-replacements using a limited prh-format rule set.
+Version 0.9.0 provides AsciiDoc document inspection, explicit prose-only
+mechanical replacements, and Japanese manuscript review. Start by inspecting the
+outline, book metadata, and local cross-references; preview and apply your
+replacement rules; then review and verify the edited manuscript against a saved
+baseline. Document commands also generate English document-title indexes.
 The CLI, diagnostics, documentation, and generated instructions are in English.
 Japanese text is retained in manuscript excerpts, rule dictionaries, and fixtures.
 
 ## Available features
 
-The following commands are available in version 0.8.6.
+The following commands are available in version 0.9.0.
 
 | Feature | Commands | Behavior |
 | --- | --- | --- |
-| [Writing criteria and prompts](#writing-commands) | `writing criteria`, `writing prompt` | Print Japanese prose criteria or generate a writing prompt without a manuscript or MeCab |
+| [Document outline](#document-commands) | `document toc` | Print parsed section titles, including book parts and chapters, with optional depth and outline numbering |
+| [Book metadata](#document-commands) | `document info` | Extract book attributes as text or JSON |
+| [Cross-reference checks](#document-commands) | `document check-xrefs` | Report unresolved local cross-references with source locations |
+| [Document-title index](#document-commands) | `document index` | Generate an alphabetical AsciiDoc index from English document titles and IDs |
 | [Replacement preview](#prose-replacements) | `replace check`, `replace diff` | Report mechanical replacement candidates or preview a diff for mapped running prose; preserve source files |
 | [Replacement application](#prose-replacements) | `replace apply` | Apply author-supplied rules after checking protected content and document structure; no MeCab or AI required |
 | [Prose review](#review-workflow) | `review scan` | Collect mapped Japanese running prose and contextual review candidates with MeCab/IPADIC by default |
@@ -29,42 +33,29 @@ The following commands are available in version 0.8.6.
 | [Review prompts](#prompt) | `review prompt` | Generate one Markdown prompt from a saved session for review and editing by an external reviewer |
 | [Baseline verification](#verify) | `review verify` | Check edited sources against a saved baseline for mechanical preservation; meaning is not verified |
 | [Manuscript scoring](#score-an-asciidoc-manuscript) | `review score` | Report a prose candidate-density score; explicit `--agent codex` or `--agent claude` optionally invokes a local AI CLI for readability ratings |
-
-Version 0.8.1 additionally supports nested replacement-rule imports,
-omitted/null `rules`, arrays in `pattern`, `/i`, and limited ECMAScript word
-boundaries. See [Prose replacements](#prose-replacements) for supported syntax
-and preservation limits. Only `replace apply` edits manuscripts directly;
-review prompts supply instructions for an external reviewer.
+| [Writing criteria and prompts](#writing-commands) | `writing criteria`, `writing prompt` | Print Japanese prose criteria or generate a writing prompt without a manuscript or MeCab |
 
 ## Status
 
-Version 0.6.3 adds separate heading review with `review scan --scope headings`.
-See [Heading review](#heading-review).
-
-Version 0.8.0 adds explicit prose replacements with `replace apply`;
-see [Prose replacements](#prose-replacements). Review and scoring do not edit
-manuscripts. The CLI does not publish books. EPUB, image,
-and book scaffolding commands are planned extensions, not available features.
-
 Ruby 3.2 or later is required. Asciidoctor is installed as a gem dependency.
-Starting with version 0.1.1, the default review backend requires the external MeCab
-command and a UTF-8 IPADIC dictionary. Node.js and textlint are not required.
-Explicit `--tokenizer literal` mode provides limited phrase matching without MeCab.
-
-Version 0.6.2 also provides `review score FILE` for a manuscript score.
-It uses local candidate analysis by default; `--agent codex` or `--agent claude`
-explicitly asks an installed CLI to evaluate readability and may connect to its
-configured model provider. No scoring mode edits manuscripts.
-
-Version 0.1.1 added morphological analysis. Version 0.1.0 used literal matching.
-
-The CLI has `writing`, `review`, and `replace` command groups. All default to `--lang ja`.
-Language-specific criteria live under `data/writing/<language>/`; review rules
-use `data/review-rules.<language>.yml`. Writing and review have separate lists
-of supported languages, so a future writing language need not imply review
-support. Other languages are reserved for future implementations and now
-return an explicit error. A review session saves its language and the criteria
-used to generate its prompt.
+Document inspection and prose replacement require neither MeCab nor an AI CLI.
+Japanese review uses the external MeCab command and a UTF-8 IPADIC dictionary by
+default; explicit `--tokenizer literal` provides limited phrase matching.
+Node.js and textlint are not required.
+
+Only `replace apply` edits manuscripts directly. Review prompts supply
+instructions for an external reviewer; review and scoring do not edit
+manuscripts. Only `review score --agent codex` or `--agent claude` invokes an
+installed AI CLI, which may connect to its configured model provider.
+The CLI does not publish books. EPUB, image, and book scaffolding commands are
+planned extensions, not available features.
+
+The CLI has `document`, `replace`, `review`, and `writing` command groups.
+Document commands accept documents in any language and do not load review
+configuration. Writing, replacement, and review default to `--lang ja` and reject
+unsupported languages. Language-specific criteria live under
+`data/writing/<language>/`; review rules use `data/review-rules.<language>.yml`.
+A review session saves its language and the criteria used to generate its prompt.
 
 ## Install from RubyGems
 
@@ -80,16 +71,17 @@ Ruby 3.2 or later is required. RubyGems installs the required Ruby dependencies;
 no repository clone or Node.js installation is needed. MeCab and IPADIC must be
 installed separately when using version 0.1.1 or later in the default mode.
 
-Generate a writing prompt without an existing manuscript:
-
-```sh
-asciidoc-pubkit writing criteria --lang ja
-asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
-```
-
-Run the review workflow from your manuscript directory:
+Inspect the document, apply explicit replacement rules, and start the review
+workflow from your manuscript directory:
 
 ```sh
+asciidoc-pubkit document toc book.adoc --depth 2 --numbered
+asciidoc-pubkit document info book.adoc --json
+asciidoc-pubkit document check-xrefs book.adoc
+asciidoc-pubkit replace check book.adoc --rules replacements.yml
+asciidoc-pubkit replace diff book.adoc --rules replacements.yml
+asciidoc-pubkit replace apply book.adoc --rules replacements.yml
+# Start a new review baseline after completing mechanical replacements.
 asciidoc-pubkit review scan book.adoc --output .pubkit/review
 asciidoc-pubkit review prompt .pubkit/review --output review-prompt.md
 # Ask your agent to review the prompt and edit the referenced manuscript.
@@ -108,13 +100,16 @@ Add the gem to your project's `Gemfile` to manage its version with Bundler:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'asciidoc-pubkit', '~> 0.8.6'
+gem 'asciidoc-pubkit', '~> 0.9.0'
 ```
 
 Then install dependencies and run the CLI through Bundler:
 
 ```sh
 bundle install
+bundle exec asciidoc-pubkit document toc book.adoc
+bundle exec asciidoc-pubkit replace diff book.adoc --rules replacements.yml
+bundle exec asciidoc-pubkit replace apply book.adoc --rules replacements.yml
 bundle exec asciidoc-pubkit review scan book.adoc --output .pubkit/review
 bundle exec asciidoc-pubkit review prompt .pubkit/review --output review-prompt.md
 bundle exec asciidoc-pubkit review verify .pubkit/review --output verification.json
@@ -130,35 +125,79 @@ git clone https://github.com/cybergarage/asciidoc-pubkit.git
 cd asciidoc-pubkit
 bundle install
 gem build asciidoc-pubkit.gemspec
-gem install ./asciidoc-pubkit-0.8.6.gem
+gem install ./asciidoc-pubkit-0.9.0.gem
 asciidoc-pubkit --version
 ```
 
 The gem name and CLI name are `asciidoc-pubkit`; the Ruby require path is
 `asciidoc_pubkit`, and the namespace is `AsciidocPubkit`.
 
-## Writing commands
+## Document 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.
+Version 0.9.0 provides four read-only document commands. They require neither
+MeCab nor an AI CLI, accept documents in any language, and do not create review
+sessions or change manuscripts.
 
 ```sh
-asciidoc-pubkit writing criteria --lang ja
-asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
+asciidoc-pubkit document toc book.adoc --depth 2 --numbered
+asciidoc-pubkit document info book.adoc --json
+asciidoc-pubkit document check-xrefs book.adoc --json
+asciidoc-pubkit document index . --output index.adoc --title "Index"
 ```
 
-For example, `--lang en` exits with an unsupported-language error. No English
-review or writing criteria are shipped in 0.8.6.
-
-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.
+All four require exactly one input. Use `--help` for command-specific options.
+Output defaults to stdout. `--output FILE` creates a new file and rejects existing
+files and symlinks. Diagnostics go to stderr. These commands do not discover
+`.asciidoc-pubkit.yml` or load review rules. Use repeatable `-a NAME=VALUE` options
+for Asciidoctor attributes and `--base-dir DIR` for the local include boundary.
+The default boundary is the input file's directory, or the scanned directory for
+`index`. Local includes and conditional directives are parsed normally; source
+files and symlink targets must remain within that boundary. Remote includes are
+rejected. `/shared/` has no special mapping or automatic exclusion: migrate such
+references to local includes within the configured boundary.
+
+`toc` prints parsed section titles in document order, with two spaces per nesting
+level. It includes book parts and their child chapters, but excludes the document
+title and apparent headings inside code blocks. `--numbered` uses outline
+positions (`1.`, `1-1.`, etc.), independently of Asciidoctor's publication
+numbering. `--depth` must be a positive integer and limits the Asciidoctor section
+level: chapters are level 1 and book parts are level 0. It does not generate or
+rewrite heading text.
+
+`info` prints `key: value` lines or a JSON object with `--json`. Its fields are
+`doctitle`, `subtitle`, `description`, `keywords`, `lang`, `uuid`, `author`,
+`producer`, and `creator`. Missing attributes become empty strings. Metadata is
+extracted from the parsed document, including active local includes.
+
+`check-xrefs` reports unresolved local `xref:ID[]` and `<<ID,label>>` references,
+including fragments targeting the entry document or an included file. It
+recognizes explicit and generated IDs and attribute-expanded targets. It scans
+macro-enabled block text, list items, table cells, and titles; comments and
+ordinary code blocks are excluded. References to separate documents and remote
+URLs are outside its scope. This is a limited syntax scan, not complete rendered
+link validation: complex inline passthroughs and custom macros are not analyzed.
+Text output has `file:line`, a tab, and the missing ID; JSON output is an array of
+`refid`, `file`, and `line` objects. Locations use Asciidoctor source cursors;
+table cells, list continuations, and multiline titles may identify the enclosing node's start
+rather than the exact token line. Duplicate occurrences of one ID on the same
+source line are reported once.
+
+`index` recursively scans lowercase `.adoc` files, skips hidden subdirectories
+and its output path, and uses each document's ID and title. It produces an
+AsciiDoc alphabetical cross-reference list for English names: parenthesized
+text and subtitles after `:` or `：` are removed; remaining titles must be ASCII
+and contain a letter. Documents without IDs are omitted. Titles are deduplicated
+case-insensitively, preferring the shallowest relative path and then lexical path
+order. `--title` adds a document title with `[#book-index]`; alphabetical groups
+use discrete level-2 headings (`=== A`). This indexes document titles, not all
+section headings. The generated references are useful when those documents are
+included in the consuming book; the command does not verify that membership.
+
+Success returns 0. `check-xrefs` returns 1 when local references are unresolved.
+Invalid inputs/options, include or parse errors, and output failures return 2;
+no output file is created on a parse error. Warnings remain visible on stderr.
+Unlike the original directory index script, an input parse error fails the whole
+index instead of silently omitting the file.
 
 ## Prose replacements
 
@@ -461,7 +500,21 @@ asciidoc-pubkit review verify .pubkit/review --output verification.json
 All three commands leave manuscript files unchanged. Only the agent edits them.
 `prompt` and `verify` output files must not already exist.
 Without `--output`, `prompt` writes Markdown and `verify` writes JSON to stdout.
-`scan` defaults to `.pubkit/review` and prints a short summary.
+`scan` defaults to `.pubkit/review` and prints a short summary. Prose scan output
+and prompts explicitly direct reviewers to a separate `--scope lists` session
+for list text; the prose baseline must remain intact.
+
+List review is optional when the assignment covers running prose only or there
+are no list descriptions to review. It is needed when the assignment includes
+list wording: the default prose scan does not review it. See [List review](#list-review)
+for examples, supported items, and coverage limits.
+
+For a review covering all three scopes, finish and verify headings first, then
+scan and review the current prose, then scan and review the current list text.
+Create each session after the preceding phase's edits and verification. Preserve
+all earlier baselines and phase-end results; later edits in another scope may
+legitimately make an earlier session's verification fail. On re-review, choose
+unused session paths rather than replacing the previous evidence.
 
 ### Scan
 
@@ -566,9 +619,9 @@ and converted inline titles and physical title lines reused by multiple includes
 Unresolved section titles receive coverage notices. Verification permits only selected title text changes while
 protecting the body, title markers, hierarchy, order, section IDs, references,
 attributes, includes and other protected content. A title-derived section ID
-change fails verification. To permit limited ID preservation, scan with
-`--scope headings --preserve-heading-ids`. Eligible generated headings then save
-an exact `permitted_id_anchor` in their metadata. A reviewer may insert only that
+change fails verification. Starting with version 0.8.7, heading scans preserve
+generated IDs by default. Eligible generated headings save an exact `permitted_id_anchor` in
+their metadata. A reviewer may insert only that
 anchor immediately before its selected heading, for example:
 
 ```adoc
@@ -578,13 +631,15 @@ anchor immediately before its selected heading, for example:
 
 Verification allows this exact addition while requiring the same section ID,
 hierarchy, order, and protected body. Existing explicit anchors remain protected;
-other anchors and reference migrations are outside this permission. Without the
-flag, only title text is editable. Scan and prompt never insert anchors or rewrite
+other anchors and reference migrations are outside this permission. No additional
+ID-preservation option is required. Previously saved permissions remain unchanged;
+start a separate new session to obtain the default permissions, keeping the old
+baseline intact. Scan and prompt never insert anchors or rewrite
 manuscripts. Numeric title changes
 are manual-review notices, and remaining candidates do not fail verification.
 `meaning_verified` remains `false`.
 
-Version 0.8.6 uses session schema 3. Earlier sessions must be recreated; preserve or
+Version 0.8.7 uses session schema 3. Earlier sessions must be recreated; preserve or
 finish an ongoing review with its original tool before establishing a new baseline.
 `review score` continues to support prose only and rejects `--scope`.
 
@@ -1139,13 +1194,13 @@ reports analyzer changes instead of treating results from different dictionaries
 as directly comparable. Prompt generation uses saved evidence and does not need
 MeCab. Changed rules or dictionary settings require a new scan.
 
-Version 0.8.6 uses session schema 3; version 0.8.5 uses schema 2.
+Version 0.8.7 uses session schema 3; version 0.8.5 uses schema 2.
 Sessions with a different schema or tool version cannot be loaded. Keep the original baseline for
 an ongoing review and finish it with the original version, or start a new review
 pass in a different directory:
 
 ```sh
-asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.6
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.7
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship
@@ -1165,11 +1220,33 @@ An empty findings array does not establish full coverage or good prose.
 
 ## List review
 
-Use a separate session to review list descriptions, including reference-list text:
+List review checks wording in unordered and ordered list items, including
+reference-list descriptions. For example, the description following this link
+is list text and is excluded from the default running-prose review:
+
+```adoc
+* link:https://example.com/cli[CLI documentation]: printとJSON/RPCの入口を説明しています。
+```
+
+AsciiDoc parses list items separately from ordinary paragraphs. The tool keeps
+these review scopes separate to map editable text and verify preservation of
+list markers, nesting, links, and inline syntax. This is a scope and preservation
+choice, not a claim that list descriptions are outside the book's body or an
+exclusion made to improve processing speed.
+
+Use this optional phase when list descriptions are part of the requested review,
+including a whole-book editorial pass. Omit it for an explicitly prose-only or
+heading-only assignment, or when there is no eligible list text. Report omitted
+and unsupported list content as unreviewed; successful prose verification does
+not establish that lists were reviewed. A zero-item list scan still requires
+inspection of coverage notices.
+
+Use a separate session:
 
 ```sh
 asciidoc-pubkit review scan book.adoc --scope lists --output .pubkit/lists
 asciidoc-pubkit review prompt .pubkit/lists --output lists-review.md
+# Ask the reviewer to read the prompt and edit only selected list text.
 asciidoc-pubkit review verify .pubkit/lists
 ```
 
@@ -1190,6 +1267,29 @@ Default prose scanning, scoring, and mechanical replacement keep their existing
 prose scope. Heading body evidence continues to omit lists. A successful verify
 checks preservation and does not establish editorial completion.
 
+## 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 0.9.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.
+
 ## Development
 
 ```sh

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))
@@ -55,7 +62,6 @@ module AsciidocPubkit
         elsif group == 'review' && %w[scan score].include?(command)
           if command == 'scan'
             opts.on('--scope SCOPE', 'prose (default), headings, or lists; separate review sessions') { |v| options[:scope] = v }
-            opts.on('--preserve-heading-ids', 'Allow exact old-ID anchors before eligible headings') { options[:preserve_heading_ids] = true }
             opts.on('--heading-rules FILE', 'Replace default heading rules with a YAML rule set') { |v| options[:heading_rules] = v }
             opts.on('-y', '--yes', 'Answer yes to replacement confirmation') { options[:yes] = true }
             opts.on('--no-input', 'Never prompt; fail on existing output unless --yes') { options[:no_input] = true }
@@ -133,6 +139,7 @@ module AsciidocPubkit
           out.puts "Scanned #{result['paragraphs']} list items; found #{result['findings']} review candidates."
         else
           out.puts "Scanned #{result['paragraphs']} paragraphs; found #{result['findings']} review candidates."
+          out.puts "List text is excluded. Review it in a separate session with --scope lists."
         end
         out.puts "Tokenizer: #{result['tokenizer']}#{result['tokenizer'] == 'literal' ? ' (limited phrase matching; no morphological analysis)' : ' (UTF-8 IPADIC)'}"
         out.puts "Coverage notices: #{result['coverage_notices']}. See document.json for limitations."

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/session.rb

@@ -215,6 +215,7 @@ module AsciidocPubkit
 
         Only source-mapped running-prose paragraphs are reviewed. Inline macros and literal spans are masked by a conservative heuristic.
         Headings, lists, tables, quotations, code, and passthrough blocks are not prose-reviewed in this release.
+        #{list_scope ? "" : "List text requires a separate review scan with --scope lists. Preserve this baseline and use a different session directory; do not count excluded lists as reviewed."}
         This is a local correction task, not a chapter-restructuring task.
         Coverage notices: #{@document['coverage'].length}
 

data/lib/asciidoc_pubkit/settings.rb

@@ -35,9 +35,6 @@ module AsciidocPubkit
       if scope == 'headings' && (options[:rules] || options[:style])
         raise Error, 'Heading scans use --heading-rules, not prose --rules or --style.'
       end
-      if scope != 'headings' && options[:preserve_heading_ids]
-        raise Error, '--preserve-heading-ids requires --scope headings.'
-      end
       if scope != 'headings' && options[:heading_rules]
         raise Error, '--heading-rules requires --scope headings.'
       end
@@ -45,7 +42,7 @@ module AsciidocPubkit
       rules_path = options[:replacement] ? RuleSet.default_path(language) : options[:rules] ? File.expand_path(options[:rules]) : (review['rules'] ? File.expand_path(review['rules'], base) : RuleSet.default_path(language))
       @data = {
         'scope' => scope,
-        'preserve_heading_ids' => !!options[:preserve_heading_ids],
+        'preserve_heading_ids' => scope == 'headings',
         'heading_rules' => scope == 'headings' ? HeadingRuleSet.load(heading_rules_path) : nil,
         'heading_rules_path' => heading_rules_path,
         'rules' => scope != 'headings' ? RuleSet.load(rules_path) : nil,

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.8.6'
+  VERSION = '0.9.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.6
+  version: 0.9.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: []
@@ -58,6 +59,7 @@ files:
 - 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 +93,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: []