asciidoc-pubkit 0.6.3 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bce892bd925140f338afaba12cce7b039e5863d7b082ef6ddb7c18b3930a5b9f
-  data.tar.gz: 6490e4783d15787651083e083bd57687d01a446d47c69a5202638e8493b9d541
+  metadata.gz: 8340a490160e7c0c2ca089657884c882eca5861dd27206dc9a3513ab1b5cfa2d
+  data.tar.gz: b4c2428c0408f2301563ee3e4586e9422c7b4875f927779146d9ebacec678568
 SHA512:
-  metadata.gz: 3bf0e618fc48a4c45f67429e1b74f3996a3d6aa2d71029bc87e112091551d3f612f1b4b2c1b5ed8e78f314fd87be412175b8009c00c741f711f902d0c9ffe89e
-  data.tar.gz: 2827a75447bac7e95bf5161bac061a3d5a089f7d0390801bbfe22a51851cdf206b4a6e512d61074e4021481aac01c2d3fd63bf7caf8db3f46e8fd8628fd30b06
+  metadata.gz: b919c53366fb83912221bf4a642b23db13725535c82449e54f6859d6a6bc76a04582c7b859eb4fb4f9cde814637dd535625eea31ffd62af48f02a6a71642c4f5
+  data.tar.gz: 18d123157532330403229b1365b97e2dcba308de2ed5d07aa16583c973d801bfa1e6aac001f299be7ab445beaf7a1600f204ff058362f1cd84dc7362f7466aca

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.8.1 — 2026-10-01
+
+- Add an opening README feature table and describe prose replacements before
+  scoring and review.
+
+- Support replacement regex `/i` with Ruby case-insensitive matching and translate
+  `\b`/`\B` assertions to limited ECMAScript Unicode word boundaries. Preserve
+  capture numbering, source positions, protected spans, and backspace-in-class
+  semantics; retain Ruby behavior elsewhere and reject other flags.
+
+- Treat null replacement `rules`, including bare `rules:`, as an empty local
+  rule set while retaining imported rules and rejecting other non-array values.
+
+- Accept nonempty string arrays in replacement `pattern` as an alias for
+  `patterns`, retaining strict validation, specs, protection, and conflict checks.
+
+- Document omitted replacement `rules` as an empty set, including version-only
+  files, and verify CLI no-op behavior and application through import-only chains.
+
+- Support nested local `imports` in replacement rules, resolving paths relative
+  to each importing file and accepting import-only files and `path` mappings.
+  Deduplicate physical files, reject cycles and unsupported import options, and
+  preserve validation, conflict detection, and prose-only replacement scope.
+
+## 0.8.0 — 2026-10-01
+
+- Add explicit `replace check`, `replace diff`, and `replace apply` commands for
+  mapped running prose using a strict subset of prh-format YAML rules. Protect
+  blocks and recognized inline spans, reject overlapping edits, test rule specs,
+  and validate staged sources before applying replacements without MeCab or AI.
+
 ## 0.6.3 — 2026-10-01
 
 - Summarize review and scoring features at the start of the README architecture

data/README.md

@@ -7,18 +7,42 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.6.3 provides shared Japanese technical writing criteria, an authoring
+Version 0.8.1 provides shared Japanese technical writing criteria, an authoring
 prompt, separate prose and heading review prompts, manuscript scoring, and
-baseline verification for edited manuscripts.
+baseline verification for edited manuscripts, plus explicit prose-only mechanical
+replacements using a limited prh-format rule set.
 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.1.
+
+| 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 |
+| [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 |
+| [Heading review](#heading-review) | `review scan --scope headings` | Collect editable section titles separately, retaining the outline and read-only body evidence |
+| [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.
+
 ## Status
 
 Version 0.6.3 adds separate heading review with `review scan --scope headings`.
 See [Heading review](#heading-review).
 
-The CLI does not automatically rewrite manuscripts or publish books. EPUB, image,
+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.
@@ -33,7 +57,7 @@ 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` and `review` command groups. Both default to `--lang ja`.
+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
@@ -83,7 +107,7 @@ Add the gem to your project's `Gemfile` to manage its version with Bundler:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'asciidoc-pubkit', '~> 0.6.3'
+gem 'asciidoc-pubkit', '~> 0.8.1'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -105,7 +129,7 @@ git clone https://github.com/cybergarage/asciidoc-pubkit.git
 cd asciidoc-pubkit
 bundle install
 gem build asciidoc-pubkit.gemspec
-gem install ./asciidoc-pubkit-0.6.3.gem
+gem install ./asciidoc-pubkit-0.8.1.gem
 asciidoc-pubkit --version
 ```
 
@@ -129,12 +153,192 @@ 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.6.3.
+review or writing criteria are shipped in 0.8.1.
 
 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.
 
+## Prose replacements
+
+Available starting with version 0.8.0.
+It applies author-supplied mechanical replacement rules without MeCab or an AI
+CLI. Review candidates and glossary variants remain advisory and are never
+implicitly applied. Replacement rules are separate from review rules.
+
+```sh
+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
+```
+
+`check` reports original text, proposed text, rule IDs (`rule-1`, etc.), source
+paths, one-based Unicode lines/columns, and a coverage-notice count. Its exit code
+is 1 when replacements are available, 0 otherwise. `diff` previews unified diffs
+without editing; it requires the external `diff` command. `apply` explicitly
+authorizes source replacement without prompting. Successful diff/apply commands
+return 0; invalid rules, conflicts, unsafe edits, and input/output failures return
+2. Check/diff accept `--output` for a new file only; apply rejects `--output`.
+
+All three accept `--lang ja`, `--base-dir`, `--config`, and `--only` (an included
+source file). Normal configuration discovery and `review.base_dir`, `language`,
+`attributes`, and `exclude` control parsing and selection. `--rules` is required;
+`review.rules` and glossary entries do not supply replacement rules. There are
+no built-in replacement rules and no automatic search for `prh.yml`.
+
+### Limited prh-format rules
+
+The supported format is a strict subset of [prh](https://github.com/prh/prh):
+
+```yaml
+version: 1
+rules:
+  - expected: '®'
+    pattern: '&reg;'
+  - expected: '($1)'
+    pattern: '/（([^（）\r\n]+)）/'
+    specs:
+      - from: '設定（任意）'
+        to: '設定(任意)'
+  - expected: '/'
+    patterns:
+      - '／'
+```
+
+The root requires `version: 1` and accepts optional `rules` and `imports` arrays.
+Starting with version 0.8.1, omitted arrays default to empty. Version 0.8.0
+requires `rules` and rejects `imports`. Each rule requires a string
+`expected` (empty strings permit deletion) and exactly one of `pattern` (a
+nonempty string or, starting with version 0.8.1, a nonempty array of nonempty
+strings) or `patterns` (a nonempty array of nonempty strings). Array-valued
+`pattern` is equivalent to `patterns`; specifying both keys is rejected. Optional
+`specs` is an array of exact `from`/`to` string pairs, validated on load. Specs
+exercise the rule on plain text, not AsciiDoc selection or inline protection.
+
+Strings not beginning with `/` match literally. `/.../` denotes a regex; the
+version 0.8.1 also accepts `/.../i` for Ruby case-insensitive matching.
+Version 0.8.0 rejects all flags. All occurrences are collected. The implementation
+uses Ruby regexes with
+a timeout and accepts a limited common syntax: character classes, ordinary
+captures, noncapturing groups, lookarounds, alternatives, anchors, quantifiers,
+and the escapes `\n`, `\r`, `\t`, `\d`, `\D`, `\s`, `\S`, `\w`, `\W`
+and escaped punctuation. Ruby regex character-class behavior applies; this is
+not a JavaScript regex engine or a promise of full prh equivalence. Engine-specific
+groups/escapes and flags other than a single `i` are rejected. A leading literal slash must be expressed
+as an escaped regex, for example `/\//`. Zero-length matches are rejected.
+
+Replacement strings support `$1` through `$99` for existing capture groups and
+`$$` for a literal dollar sign. Unsupported dollar references are rejected when
+matched. Missing optional captures expand to empty strings. YAML single quotes
+are recommended to keep backslashes literal. Unknown fields, including
+`options` and `regexpMustEmpty`, and omitted patterns are rejected rather than
+ignored. prh's automatic pattern generation is not supported.
+
+For example, version 0.8.1 also accepts:
+
+```yaml
+version: 1
+rules:
+  - expected: 'ハードウェア'
+    pattern:
+      - 'ハードウエア'
+      - 'ハードウェアー'
+```
+
+Each array entry uses the same literal/regex syntax and validation as a single
+pattern. Arrays do not change supported flags or overlap handling.
+
+### Limited ECMAScript boundary compatibility
+
+Version 0.8.1 translates `\b` and `\B` outside character classes into Ruby
+lookarounds with ECMAScript word-character semantics, following prh's default
+Unicode mode. Word characters are ASCII letters, digits, and underscore; Japanese
+characters are non-word characters. Thus `/\bTips\b/` matches `Tips` in
+`前Tips後`, but not in `Tips2`, `_Tips`, or `ATips`.
+With `/i`, long s (`ſ`) and Kelvin sign (`K`) also count as word characters under
+ECMAScript Unicode case folding. The generated assertions add no capture groups
+and preserve original match offsets. Inside a character class, `\b` means a
+backspace character; `\B` there is rejected. Escaped literal backslashes are
+preserved.
+
+Only the boundary assertions emulate ECMAScript. `/i` uses Ruby's
+`Regexp::IGNORECASE`; Unicode case folding can differ from JavaScript (for
+example multi-character folds). Other constructs, including whitespace classes,
+retain Ruby semantics. This is limited prh compatibility, not full ECMAScript
+conformance. Flags `g`, `m`, `s`, `u`, `y`, `d`, and `v` and duplicate `i` are
+rejected; all occurrences are already collected independently of `g`.
+
+### Importing replacement rules
+
+Version 0.8.1 supports nested `imports`; version 0.8.0 does not. For example:
+
+```yaml
+version: 1
+imports:
+  - ../../rules/prh.yml
+  - path: ./terminology.yml
+rules:
+  - expected: '®'
+    pattern: '&reg;'
+```
+
+Each entry is a nonempty local file path string or a mapping containing exactly
+`path`. Relative paths resolve from the importing YAML file, including nested
+imports, independently of the working directory and manuscript base directory.
+Absolute local paths are also accepted; URL imports are rejected. An import-only
+file may omit `rules`. A file containing only `version: 1` is also valid and
+contributes no rules. With no imported or local rules, `check`, `diff`, and
+`apply` succeed without changing manuscript sources, and `diff` emits no patch.
+Starting with version 0.8.1, a bare `rules:`, `rules: null`, and `rules: ~`
+also contribute no local rules, just like omission or `rules: []`; imported rules
+are still loaded. Other non-array values remain invalid. This normalization
+applies only to `rules`, not to `imports` or individual rule fields.
+Every imported file must use version 1 and pass the same
+strict rule validation and specs as the entry file.
+
+Imports are loaded in listed order, recursively before each file's own rules.
+Each physical file is loaded once per plan, including repeated paths, symlink
+aliases, and shared dependencies. Rule IDs are assigned across the flattened
+set. Cycles (including symlink aliases), missing files, and import chains deeper
+than 100 files fail rather than silently omitting rules. Imported and local rules
+are combined, not overridden: overlapping replacement candidates remain errors
+and replacements are still calculated only against the original text.
+
+Import options such as `ignoreRules` and `disableImports` remain unsupported and
+are rejected. Source selection and protection are unchanged by imports.
+
+### Selection and preservation
+
+Only unambiguously source-mapped running prose in the existing default review
+scope is eligible. Headings, lists, tables, quotations, listing/source, literal,
+and passthrough blocks are excluded. Recognized inline code, quotations, URLs,
+macros, and attribute references are protected by the existing conservative
+inline heuristic, not a complete inline parser. A match overlapping any protected
+span is skipped; matching is performed on the original text, never on blanked
+placeholders. Backtick-to-bold and list-marker conversions are outside this scope.
+
+Candidates are calculated once against the original sources; replacement results
+are not searched again. Overlapping edits are conflicts, not resolved by rule
+order. Matches/results containing line breaks are rejected. Source files retain
+UTF-8 bytes, original line endings, and unrelated content; repeated include
+occurrences must not create overlapping edits.
+
+Before presenting a plan, the complete captured source set is copied to temporary
+staging and reparsed. Parsing diagnostics, structural changes, new/deleted protected
+inline tokens, and protected-content/source-membership changes reject the plan.
+Relative includes within the base directory are supported. Absolute includes and
+includes whose paths depend on the original filesystem may fail staged validation;
+they are not rewritten or silently accepted. Symlink entrypoints are rejected.
+
+Apply stages all changed files beside their destinations, checks all captured
+source bytes against the plan, and renames the prepared files into place while
+preserving permission bits. An ordinary installation error restores sources
+already installed. This is not a crash-atomic transaction across multiple files;
+keep manuscripts under version control and avoid concurrent edits during apply.
+No review session is created or replaced. Existing sessions retain their original
+baselines; applying replacements can make a session stale for prompt generation.
+Mechanical validation does not establish semantic correctness.
+
 ## Score an AsciiDoc manuscript
 
 Pass any AsciiDoc entry file directly; no review session or gold annotations are
@@ -840,12 +1044,12 @@ 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.
 
-Sessions from earlier tool versions are not compatible with 0.6.3 (session schema 2). Keep the original baseline for
+Sessions from earlier tool versions are not compatible with 0.8.1 (session schema 2). 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.6.3
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.1
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship

data/examples/replacements.yml

@@ -0,0 +1,17 @@
+version: 1
+
+rules:
+  - expected: '®'
+    pattern: '®'
+    specs:
+      - from: '製品®'
+        to: '製品®'
+  - expected: '($1)'
+    pattern: '/（([^（）\r\n]+)）/'
+    specs:
+      - from: '設定（任意）'
+        to: '設定(任意)'
+  - expected: ' '
+    pattern: '　'
+  - expected: '/'
+    pattern: '／'

data/lib/asciidoc_pubkit/cli.rb

@@ -12,6 +12,9 @@ module AsciidocPubkit
         review score FILE      Score Japanese prose; optionally use a local AI CLI
         review prompt SESSION  Generate an English review prompt with Japanese source excerpts
         review verify SESSION  Compare edited sources with the saved baseline
+        replace check FILE     Report prose-only replacement candidates
+        replace diff FILE      Preview prose replacements as a unified diff
+        replace apply FILE     Validate and apply explicit replacement rules
 
       Options:
         --help                 Show help (also supported for each command)
@@ -19,7 +22,7 @@ module AsciidocPubkit
 
       Use --lang ja with writing commands and review commands. Other review and
       writing languages are not supported yet and return an error.
-      No command edits manuscripts. review score --agent explicitly invokes a
+      Only replace apply edits manuscripts. review score --agent explicitly invokes a
       local Codex or Claude CLI, which may connect to its configured AI service.
     TEXT
 
@@ -29,21 +32,27 @@ module AsciidocPubkit
         out.puts VERSION
         return 0
       end
-      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing].any? { |group| args == [group, '--help'] }
+      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing replace].any? { |group| args == [group, '--help'] }
         out.puts HELP
         return 0
       end
       group, command = args.shift(2)
       valid = (group == 'review' && %w[scan score prompt verify].include?(command)) ||
-              (group == 'writing' && %w[criteria prompt].include?(command))
+              (group == 'writing' && %w[criteria prompt].include?(command)) ||
+              (group == 'replace' && %w[check diff apply].include?(command))
       raise Error, 'Unknown command. Use --help.' unless valid
       options = { attributes: {} }
       parser = OptionParser.new do |opts|
-        input_name = group == 'writing' ? '' : (%w[scan score].include?(command) ? ' FILE' : ' SESSION')
+        input_name = group == 'writing' ? '' : ((group == 'replace' || %w[scan score].include?(command)) ? ' FILE' : ' SESSION')
         opts.banner = "Usage: asciidoc-pubkit #{group} #{command} [options]#{input_name}"
         opts.on('-o', '--output PATH', group == 'review' && command == 'scan' ? 'New session directory (default: .pubkit/review for prose, .pubkit/headings for headings)' : 'New output file (default: standard output)') { |v| options[:output] = v }
         opts.on('--lang LANG', 'Language (ja only in this release)') { |v| options[:language] = v }
-        if group == 'review' && %w[scan score].include?(command)
+        if group == 'replace'
+          opts.on('--rules FILE', 'Required prh-format replacement rules (limited compatibility)') { |v| options[:rules] = v }
+          opts.on('--base-dir DIR', 'Set the Asciidoctor base directory') { |v| options[:base_dir] = v }
+          opts.on('--config FILE', 'Use review parsing configuration and exclusions') { |v| options[:config] = v }
+          opts.on('--only FILE', 'Select one included file') { |v| options[:only] = v }
+        elsif group == 'review' && %w[scan score].include?(command)
           if command == 'scan'
             opts.on('--scope SCOPE', 'prose (default) or headings; separate review sessions') { |v| options[:scope] = v }
             opts.on('--heading-rules FILE', 'Replace default heading rules with a YAML rule set') { |v| options[:heading_rules] = v }
@@ -85,6 +94,15 @@ module AsciidocPubkit
       end
       raise Error, 'Exactly one input is required. Use --help.' unless args.length == 1
       Language.validate!(options[:language], operation: 'review') if options[:language]
+      if group == 'replace'
+        raise Error, 'replace apply does not accept --output.' if command == 'apply' && options[:output]
+        replacement = Replacement.new(args.first, options)
+        content = command == 'diff' ? replacement.diff : replacement.report
+        replacement.apply if command == 'apply'
+        content += "Applied #{replacement.candidates.length} replacements.\n" if command == 'apply'
+        output(content, options[:output], out)
+        return command == 'check' && !replacement.candidates.empty? ? 1 : 0
+      end
       if command == 'score'
         if options[:output] && (File.exist?(options[:output]) || File.symlink?(options[:output]))
           raise Error, "Output already exists: #{options[:output]}"

data/lib/asciidoc_pubkit/replacement.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'tempfile'
+require 'open3'
+
+module AsciidocPubkit
+  class ReplacementRules
+    def self.load(path)
+      collect(path, [], {}).each_with_index.map do |rule, index|
+        unless rule.is_a?(Hash) && (rule.keys - %w[expected pattern patterns specs]).empty? &&
+               rule['expected'].is_a?(String) && (rule.key?('pattern') ^ rule.key?('patterns'))
+          raise Error, "Rule #{index + 1} requires expected and exactly one of pattern or patterns; unsupported keys are rejected."
+        end
+        patterns = rule.key?('pattern') ? rule['pattern'] : rule['patterns']
+        patterns = [patterns] if rule.key?('pattern') && patterns.is_a?(String)
+        unless patterns.is_a?(Array) && !patterns.empty? && patterns.all? { |p| p.is_a?(String) && !p.empty? }
+          raise Error, 'Replacement patterns must be nonempty strings.'
+        end
+        compiled = patterns.map do |pattern|
+          if pattern.start_with?('/')
+            match = pattern.match(%r{\A/(.*)/([a-z]*)\z}m)
+            unless match && ['', 'i'].include?(match[2])
+              raise Error, 'Unsupported regex flags; only optional i is supported (all matches are collected).'
+            end
+            body = match[1]
+            # Deliberately small common JavaScript/Ruby subset; Ruby-only escapes
+            # and engine-specific groups must not silently change JS semantics.
+            if body.match?(/\\[^\\\/.*+?()\[\]{}^$|nrtdDsSwWbB-]/) || body.match?(/\(\?(?![:=!]|<[=!])/) || body.include?('&&')
+              raise Error, 'Unsupported regex syntax in replacement rule.'
+            end
+            ignore_case = match[2] == 'i'
+            body = javascript_boundaries(body, ignore_case: ignore_case)
+            Regexp.new(body.gsub('\\/', '/'), ignore_case ? Regexp::IGNORECASE : 0, timeout: 0.1)
+          else
+            Regexp.new(Regexp.escape(pattern), timeout: 0.1)
+          end
+        end
+        compiled.each do |regex|
+          regex.match('') # Detect common empty matches; runtime checks cover contextual ones.
+          raise Error, 'Zero-length replacement matches are unsupported.' if regex.match('')
+        end
+        specs = rule.fetch('specs', [])
+        raise Error, 'specs must be an array.' unless specs.is_a?(Array)
+        specs.each do |spec|
+          RuleSet.mapping(spec, %w[from to], 'Replacement spec')
+          raise Error, 'Spec from/to must be strings.' unless spec.values.all? { |v| v.is_a?(String) }
+          result = spec['from'].dup
+          edits = matches(spec['from'], compiled, rule['expected'])
+          reject_overlaps!(edits)
+          edits.reverse_each { |edit| result[edit[:start]...edit[:finish]] = edit[:after] }
+          raise Error, "Replacement spec failed for rule #{index + 1}." unless result == spec['to']
+        end
+        { id: "rule-#{index + 1}", patterns: compiled, expected: rule['expected'] }
+      end
+    rescue RegexpError, Regexp::TimeoutError => e
+      raise Error, "Invalid replacement regex: #{e.message}"
+    end
+
+    # prh uses Unicode JS regexes: word characters are ASCII letters/digits/_;
+    # Unicode ignore-case additionally folds long s and Kelvin sign to ASCII.
+    # Scope out Ruby's ignore-case so these assertion classes stay exact.
+    def self.javascript_boundaries(body, ignore_case:)
+      word = ignore_case ? '(?-i:[A-Za-z0-9_ſK])' : '[A-Za-z0-9_]'
+      boundary = "(?:(?<=#{word})(?!#{word})|(?<!#{word})(?=#{word}))"
+      nonboundary = "(?:(?<=#{word})(?=#{word})|(?<!#{word})(?!#{word}))"
+      chars = body.chars
+      result = +''
+      in_class = false
+      index = 0
+      while index < chars.length
+        char = chars[index]
+        if char == '\\' && index + 1 < chars.length
+          following = chars[index + 1]
+          if following == 'b'
+            result << (in_class ? '\x08' : boundary)
+          elsif following == 'B'
+            raise Error, '\B inside a character class is unsupported.' if in_class
+            result << nonboundary
+          else
+            result << char << following
+          end
+          index += 2
+          next
+        end
+        in_class = true if char == '['
+        in_class = false if char == ']'
+        result << char
+        index += 1
+      end
+      result
+    end
+
+    def self.collect(path, active, visited)
+      path = File.realpath(path)
+      if active.include?(path)
+        raise Error, "Circular replacement imports: #{(active + [path]).join(' -> ')}"
+      end
+      return [] if visited[path]
+      raise Error, 'Replacement imports exceed the maximum depth of 100 files.' if active.length >= 100
+      data = YAML.safe_load(AsciidocPubkit.read_text(path), permitted_classes: [], aliases: false)
+      unless data.is_a?(Hash) && data.key?('version') && (data.keys - %w[version rules imports]).empty?
+        raise Error, "Replacement rules in #{path} require version and accept only rules and imports."
+      end
+      unless data['version'].is_a?(Integer) && data['version'] == 1
+        raise Error, "Replacement version in #{path} must be integer 1."
+      end
+      rules = data.fetch('rules', [])
+      rules = [] if rules.nil?
+      imports = data.fetch('imports', [])
+      raise Error, "rules in #{path} must be an array." unless rules.is_a?(Array)
+      raise Error, "imports in #{path} must be an array." unless imports.is_a?(Array)
+      imported = imports.flat_map do |entry|
+        if entry.is_a?(Hash)
+          RuleSet.mapping(entry, ['path'], "Replacement import in #{path}")
+          entry = entry['path']
+        end
+        unless entry.is_a?(String) && !entry.strip.empty? && !entry.match?(/\A[a-z][a-z0-9+.-]*:/i)
+          raise Error, "Replacement imports in #{path} must specify nonempty local file paths."
+        end
+        collect(File.expand_path(entry, File.dirname(path)), active + [path], visited)
+      end
+      visited[path] = true
+      imported + rules
+    rescue Psych::Exception => e
+      raise Error, "Invalid replacement YAML in #{path}: #{e.message}"
+    end
+
+    def self.expand(template, match)
+      template.gsub(/\$\$|\$[1-9][0-9]?|\$./) do |ref|
+        if ref == '$$'
+          '$'
+        elsif ref.match?(/\A\$[1-9][0-9]?\z/) && ref[1..].to_i < match.length
+          match[ref[1..].to_i] || ''
+        else
+          raise Error, "Unsupported replacement reference: #{ref}"
+        end
+      end
+    end
+
+    def self.matches(text, patterns, expected)
+      patterns.flat_map do |regex|
+        text.to_enum(:scan, regex).map do
+          match = Regexp.last_match
+          raise Error, 'Zero-length replacement matches are unsupported.' if match.begin(0) == match.end(0)
+          { start: match.begin(0), finish: match.end(0), before: match[0], after: expand(expected, match) }
+        end
+      end.reject { |edit| edit[:before] == edit[:after] }.uniq.sort_by { |edit| edit[:start] }
+    rescue Regexp::TimeoutError
+      raise Error, 'Replacement regex timed out.'
+    end
+
+    def self.reject_overlaps!(edits)
+      edits.sort_by { |edit| edit[:start] }.each_cons(2) do |left, right|
+        raise Error, 'Conflicting replacement candidates overlap; revise the rules.' if left[:finish] > right[:start]
+      end
+    end
+  end
+
+  class Replacement
+    attr_reader :candidates
+
+    def initialize(entry, options)
+      raise Error, 'Replacement commands require --rules FILE.' unless options[:rules]
+      raise Error, 'Replacement entry must not be a symlink.' if File.symlink?(entry)
+      @entry = File.realpath(entry)
+      @only = options[:only] && File.realpath(options[:only])
+      @settings = Settings.new(entry, options.merge(replacement: true)).data
+      @document = Document.new(entry, @settings, only: options[:only])
+      raise Error, 'Replacement input has parsing diagnostics.' unless @document.diagnostics.empty?
+      rules = ReplacementRules.load(options[:rules])
+      @candidates = []
+      @document.paragraphs.each do |paragraph|
+        text = paragraph['text']
+        protected_ranges = text.to_enum(:scan, Rules::INLINE).map do
+          match = Regexp.last_match
+          match.begin(0)...match.end(0)
+        end
+        raw = @document.sources.fetch(paragraph['file'])
+        lines = raw.lines
+        line_offsets = [0]
+        lines.each { |line| line_offsets << line_offsets.last + line.length }
+        rules.each do |rule|
+          ReplacementRules.matches(text, rule[:patterns], rule[:expected]).each do |edit|
+            next if protected_ranges.any? { |range| edit[:start] < range.end && edit[:finish] > range.begin }
+            # Keep physical line boundaries intact, including CRLF.
+            raise Error, 'Replacement matches and results must stay on one line.' if (edit[:before] + edit[:after]).match?(/[\r\n]/)
+            prefix = text[0...edit[:start]]
+            line = paragraph['line'] + prefix.count("\n")
+            column = (prefix.rindex("\n") ? prefix.length - prefix.rindex("\n") : prefix.length + 1)
+            start = line_offsets.fetch(line - 1) + column - 1
+            raise Error, 'Replacement source mapping is ambiguous.' unless raw[start, edit[:before].length] == edit[:before]
+            @candidates << edit.merge(start: start, finish: start + edit[:before].length,
+                                     file: paragraph['file'], line: line, column: column, rule: rule[:id])
+          end
+        end
+      end
+      @candidates.uniq!
+      @candidates.sort_by! { |edit| [edit[:file], edit[:start], edit[:rule]] }
+      @candidates.group_by { |edit| edit[:file] }.each_value { |edits| ReplacementRules.reject_overlaps!(edits) }
+      @updated = @document.sources.transform_values(&:dup)
+      @candidates.reverse_each { |edit| @updated[edit[:file]][edit[:start]...edit[:finish]] = edit[:after] }
+      validate unless @candidates.empty?
+    end
+
+    def report
+      candidates.map { |edit| "#{edit[:file]}:#{edit[:line]}:#{edit[:column]}: #{edit[:rule]} #{edit[:before].inspect} -> #{edit[:after].inspect}\n" }.join +
+        "#{candidates.length} replacements; #{@document.coverage.length} coverage notices. Only mapped running prose is eligible.\n"
+    end
+
+    def changed
+      @updated.select { |path, text| text != @document.sources[path] }
+    end
+
+    def diff
+      changed.map do |path, text|
+        Tempfile.create('pubkit-before') do |before|
+          Tempfile.create('pubkit-after') do |after|
+            before.binmode.write(@document.sources[path]); before.flush
+            after.binmode.write(text); after.flush
+            output, error, status = Open3.capture3('diff', '-u', '--label', "#{path} (before)", '--label', "#{path} (after)", before.path, after.path)
+            raise Error, "Cannot generate diff: #{error}" unless [0, 1].include?(status.exitstatus)
+            output
+          end
+        end
+      end.join
+    end
+
+    def validate
+      root = File.realpath(@settings['base_dir'])
+      Dir.mktmpdir('pubkit-replacement-') do |stage|
+        stage = File.realpath(stage)
+        @updated.each do |path, text|
+          destination = File.join(stage, Pathname.new(path).relative_path_from(Pathname.new(root)).to_s)
+          FileUtils.mkdir_p(File.dirname(destination))
+          File.binwrite(destination, text)
+        end
+        staged_entry = File.join(stage, Pathname.new(@entry).relative_path_from(Pathname.new(root)).to_s)
+        staged_only = @only && File.join(stage, Pathname.new(@only).relative_path_from(Pathname.new(root)).to_s)
+        staged = Document.new(staged_entry, @settings.merge('base_dir' => stage), only: staged_only)
+        raise Error, 'Replacement changes parsing or document structure.' unless staged.diagnostics.empty? && staged.structure == @document.structure
+        original = Session.protected_content(@document).transform_keys { |path| Pathname.new(path).relative_path_from(Pathname.new(root)).to_s }
+        result = Session.protected_content(staged).transform_keys { |path| Pathname.new(path).relative_path_from(Pathname.new(stage)).to_s }
+        # --only can leave otherwise eligible paragraphs protected in the original.
+        if original != result
+          raise Error, 'Replacement changes source membership or protected content.'
+        end
+      end
+    end
+
+    def apply
+      installed = []
+      prepared = []
+      begin
+        changed.each do |path, text|
+          file = Tempfile.new('.pubkit-replace-', File.dirname(path))
+          prepared << [path, file]
+          file.binmode.write(text)
+          file.flush
+          file.fsync
+          File.chmod(File.stat(path).mode & 0o777, file.path)
+        end
+        @document.sources.each do |path, raw|
+          unless !File.symlink?(path) && File.binread(path) == raw.b
+            raise Error, "Source changed before replacement: #{path}"
+          end
+        end
+        prepared.each do |path, file|
+          File.rename(file.path, path)
+          installed << path
+        end
+      rescue StandardError
+        installed.reverse_each { |path| File.binwrite(path, @document.sources.fetch(path)) }
+        raise
+      ensure
+        prepared.each { |_, file| file.close! }
+      end
+    end
+  end
+end

data/lib/asciidoc_pubkit/settings.rb

@@ -39,7 +39,7 @@ module AsciidocPubkit
         raise Error, '--heading-rules requires --scope headings.'
       end
       heading_rules_path = options[:heading_rules] ? File.expand_path(options[:heading_rules]) : (review['heading_rules'] ? File.expand_path(review['heading_rules'], base) : HeadingRuleSet.default_path(language))
-      rules_path = options[:rules] ? File.expand_path(options[:rules]) : (review['rules'] ? File.expand_path(review['rules'], base) : RuleSet.default_path(language))
+      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,
         'heading_rules' => scope == 'headings' ? HeadingRuleSet.load(heading_rules_path) : nil,

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.6.3'
+  VERSION = '0.8.1'
   class Error < StandardError; end
 
   def self.hash_text(text)
@@ -34,4 +34,5 @@ require_relative 'asciidoc_pubkit/rules'
 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/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoc-pubkit
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.8.1
 platform: ruby
 authors:
 - CyberGarage
@@ -38,7 +38,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 description: Generate Japanese technical writing prompts, review AsciiDoc prose and
-  section headings separately, and verify protected manuscript content.
+  section headings separately, verify protected manuscript content, and explicitly
+  apply prose-only mechanical replacements.
 executables:
 - asciidoc-pubkit
 extensions: []
@@ -52,6 +53,7 @@ files:
 - data/writing/ja/criteria.md
 - data/writing/ja/headings.md
 - examples/book.adoc
+- examples/replacements.yml
 - exe/asciidoc-pubkit
 - lib/asciidoc_pubkit.rb
 - lib/asciidoc_pubkit/cli.rb
@@ -60,6 +62,7 @@ files:
 - lib/asciidoc_pubkit/language.rb
 - lib/asciidoc_pubkit/local_evaluator.rb
 - lib/asciidoc_pubkit/morphology.rb
+- lib/asciidoc_pubkit/replacement.rb
 - lib/asciidoc_pubkit/rule_set.rb
 - lib/asciidoc_pubkit/rules.rb
 - lib/asciidoc_pubkit/score.rb