asciidoc-pubkit 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e6439ccb97f49f7e31290cb8d60b1f361cf444889ac0631cdd1f9e28f8a0d9c
-  data.tar.gz: 484ff3e7ac4475ea693ff7d5751bc34e1537b66dda90bb7d425bb55acb467322
+  metadata.gz: 3dd09ef810a52e64bd286b34f4f59cda2cf357214abd94a1255ee44d77a96e27
+  data.tar.gz: fec7d11ca4f985b41aa1d2e5d37c8b126d56a1dc1ee86874330d2239634207c1
 SHA512:
-  metadata.gz: 9ccf0130e06770e7b12774385daab670fffde6a128e83af1d67300ada91ea6c15fc281645cfae6da6b7b009cca36d01429287ee36461c11f2d43c439d8307fe5
-  data.tar.gz: f70b717d0633729647ac733670604e3d6ace15354efc31167f8af8994b62531ddba1c74f6456c293ccf16bbee4833ddbd2efb655c520151edee6b6559d94ca0c
+  metadata.gz: e56e14f6abd189a621a3f4b918d9e24697749bc1a777816b2cdfa9a02bfc662f1b53e831e291af99b5254ac976a6fa72a2703c224d98ce979e0d9d7eac5be6d5
+  data.tar.gz: 19361ba968e9738a736f4452eb6590b90cbc1ca998e128d0cdd952f1da527c66d97817f6913f9957092c8dfbae55b5019e90909e1709337671bb57384031da06

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.8.2 — 2026-10-02
+
+- Report replacement rule errors with the original YAML filename and one-based
+  line number on the first line and the existing reason on the following line.
+  Track imported rules, pattern arrays, specs, and runtime replacement references
+  without changing exit codes or applying invalid plans.
+
+## 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

data/README.md

@@ -7,13 +7,34 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.8.0 provides shared Japanese technical writing criteria, an authoring
+Version 0.8.2 provides shared Japanese technical writing criteria, an authoring
 prompt, separate prose and heading review prompts, manuscript scoring, and
 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.2.
+
+| 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`.
@@ -86,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.8.0'
+gem 'asciidoc-pubkit', '~> 0.8.2'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -108,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.8.0.gem
+gem install ./asciidoc-pubkit-0.8.2.gem
 asciidoc-pubkit --version
 ```
 
@@ -132,12 +153,205 @@ 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.8.0.
+review or writing criteria are shipped in 0.8.2.
 
 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`.
+
+Starting with version 0.8.2, invalid rule files report their original YAML file
+and one-based line number on the first error line, followed by the existing
+reason on the next line. Imported files and entries in pattern arrays retain
+their own source locations. For example:
+
+```text
+Error: /path/to/prh.yml:162
+Unsupported regex flags; only optional i is supported (all matches are collected).
+```
+
+Rules are validated before any manuscript is replaced. All replacement commands
+stop with exit code 2 on invalid rules, including errors found in imported files.
+
+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: '®'
+  - 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: '®'
+```
+
+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
@@ -753,107 +967,6 @@ Regex patterns are not interpreted in glossary or allow-list entries. Unknown
 configuration keys are rejected. A bare `mecab_command` is resolved through PATH;
 use an absolute path for an explicit executable override.
 
-## 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: '®'
-  - expected: '($1)'
-    pattern: '/（([^（）\r\n]+)）/'
-    specs:
-      - from: '設定（任意）'
-        to: '設定(任意)'
-  - expected: '/'
-    patterns:
-      - '／'
-```
-
-The root contains exactly `version: 1` and `rules`. Each rule requires a string
-`expected` (empty strings permit deletion) and exactly one of `pattern` (a
-nonempty string) or `patterns` (a nonempty array of nonempty strings). 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 with no
-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 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 `imports`,
-`options`, and `regexpMustEmpty`, and omitted patterns are rejected rather than
-ignored. Regex flags and prh's automatic pattern generation are not supported.
-
-### 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.
-
 ## Rules and coverage
 
 | Rule | Severity | Purpose |
@@ -944,12 +1057,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.8.0 (session schema 2). Keep the original baseline for
+Sessions from earlier tool versions are not compatible with 0.8.2 (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.8.0
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.2
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship

data/lib/asciidoc_pubkit/replacement.rb

@@ -5,55 +5,166 @@ require 'tempfile'
 require 'open3'
 
 module AsciidocPubkit
+  class ReplacementRuleError < Error
+    def initialize(path, node, message, line: nil)
+      super("#{path}:#{line || (node ? node.start_line + 1 : 1)}\n#{message}")
+    end
+  end
+
   class ReplacementRules
+    def self.field(node, name)
+      return unless node.is_a?(Psych::Nodes::Mapping)
+      pair = node.children.each_slice(2).find { |key, _| key.respond_to?(:value) && key.value == name }
+      pair && pair.last
+    end
+
+    def self.item(node, index)
+      node.is_a?(Psych::Nodes::Sequence) ? node.children[index] : node
+    end
+
     def self.load(path)
-      data = YAML.safe_load(AsciidocPubkit.read_text(path), permitted_classes: [], aliases: false)
-      RuleSet.mapping(data, %w[version rules], 'Replacement rules')
-      raise Error, 'Replacement version must be integer 1.' unless data['version'].is_a?(Integer) && data['version'] == 1
-      raise Error, 'rules must be an array.' unless data['rules'].is_a?(Array)
-      data['rules'].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']
-        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)
-            raise Error, 'Regex flags are unsupported; omit flags (all matches are collected).' unless match && match[2].empty?
-            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?(/\\[^\\\/.*+?()\[\]{}^$|nrtdDsSwW-]/) || body.match?(/\(\?(?![:=!]|<[=!])/) || body.include?('&&')
-              raise Error, 'Unsupported regex syntax in replacement rule.'
-            end
-            Regexp.new(body.gsub('\\/', '/'), timeout: 0.1)
+      collect(path, [], {}).each_with_index.map { |source, index| compile(source, index) }
+    end
+
+    def self.compile(source, index)
+      rule = source[:value]
+      location = source[:node]
+      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
+      pattern_node = field(source[:node], rule.key?('pattern') ? 'pattern' : 'patterns')
+      location = pattern_node
+      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.each_with_index.map do |pattern, pattern_index|
+        location = item(pattern_node, pattern_index)
+        regex = 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
+        raise Error, 'Zero-length replacement matches are unsupported.' if regex.match('')
+        regex
+      end
+      location = field(source[:node], 'specs') || source[:node]
+      specs = rule.fetch('specs', [])
+      raise Error, 'specs must be an array.' unless specs.is_a?(Array)
+      specs.each_with_index do |spec, spec_index|
+        location = item(field(source[:node], 'specs'), spec_index)
+        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'],
+        path: source[:path], node: source[:node], pattern_node: pattern_node }
+    rescue RegexpError, Regexp::TimeoutError => e
+      raise ReplacementRuleError.new(source[:path], location, "Invalid replacement regex: #{e.message}")
+    rescue Error => e
+      raise ReplacementRuleError.new(source[:path], location, 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
-            Regexp.new(Regexp.escape(pattern), timeout: 0.1)
+            result << char << following
           end
+          index += 2
+          next
         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('')
+        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.expand_path(path)
+      location = nil
+      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
+      text = AsciidocPubkit.read_text(path)
+      tree = Psych.parse_stream(text, filename: path)
+      root = tree.children.first&.root
+      location = root
+      data = YAML.safe_load(text, 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
+      location = field(root, 'version')
+      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', [])
+      location = field(root, 'rules')
+      raise Error, "rules in #{path} must be an array." unless rules.is_a?(Array)
+      location = field(root, 'imports')
+      raise Error, "imports in #{path} must be an array." unless imports.is_a?(Array)
+      imported = imports.each_with_index.flat_map do |entry, index|
+        location = item(field(root, 'imports'), index)
+        if entry.is_a?(Hash)
+          RuleSet.mapping(entry, ['path'], "Replacement import in #{path}")
+          entry = entry['path']
         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']
+        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
-        { id: "rule-#{index + 1}", patterns: compiled, expected: rule['expected'] }
+        collect(File.expand_path(entry, File.dirname(path)), active + [path], visited)
       end
-    rescue RegexpError, Regexp::TimeoutError => e
-      raise Error, "Invalid replacement regex: #{e.message}"
+      visited[path] = true
+      imported + rules.each_with_index.map { |rule, index| { value: rule, path: path, node: item(field(root, 'rules'), index) } }
+    rescue ReplacementRuleError
+      raise
+    rescue Psych::Exception => e
+      raise ReplacementRuleError.new(path, location, "Invalid replacement YAML in #{path}: #{e.message}",
+                                     line: e.respond_to?(:line) ? e.line : nil)
+    rescue Error, SystemCallError => e
+      raise ReplacementRuleError.new(path, location, e.message)
     end
 
     def self.expand(template, match)
@@ -68,16 +179,23 @@ module AsciidocPubkit
       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) }
+    def self.matches(text, patterns, expected, source: nil)
+      patterns.each_with_index.flat_map do |regex, index|
+        begin
+          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
+        rescue Error, Regexp::TimeoutError => e
+          message = e.is_a?(Regexp::TimeoutError) ? 'Replacement regex timed out.' : e.message
+          if source
+            location = message.start_with?('Unsupported replacement reference:') ? field(source[:node], 'expected') : item(source[:pattern_node], index)
+            raise ReplacementRuleError.new(source[:path], location, message)
+          end
+          raise Error, message
         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)
@@ -111,7 +229,7 @@ module AsciidocPubkit
         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|
+          ReplacementRules.matches(text, rule[:patterns], rule[:expected], source: rule).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]/)

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.8.0'
+  VERSION = '0.8.2'
   class Error < StandardError; end
 
   def self.hash_text(text)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoc-pubkit
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - CyberGarage