asciidoc-pubkit 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8340a490160e7c0c2ca089657884c882eca5861dd27206dc9a3513ab1b5cfa2d
-  data.tar.gz: b4c2428c0408f2301563ee3e4586e9422c7b4875f927779146d9ebacec678568
+  metadata.gz: 3dd09ef810a52e64bd286b34f4f59cda2cf357214abd94a1255ee44d77a96e27
+  data.tar.gz: fec7d11ca4f985b41aa1d2e5d37c8b126d56a1dc1ee86874330d2239634207c1
 SHA512:
-  metadata.gz: b919c53366fb83912221bf4a642b23db13725535c82449e54f6859d6a6bc76a04582c7b859eb4fb4f9cde814637dd535625eea31ffd62af48f02a6a71642c4f5
-  data.tar.gz: 18d123157532330403229b1365b97e2dcba308de2ed5d07aa16583c973d801bfa1e6aac001f299be7ab445beaf7a1600f204ff058362f1cd84dc7362f7466aca
+  metadata.gz: e56e14f6abd189a621a3f4b918d9e24697749bc1a777816b2cdfa9a02bfc662f1b53e831e291af99b5254ac976a6fa72a2703c224d98ce979e0d9d7eac5be6d5
+  data.tar.gz: 19361ba968e9738a736f4452eb6590b90cbc1ca998e128d0cdd952f1da527c66d97817f6913f9957092c8dfbae55b5019e90909e1709337671bb57384031da06

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

data/README.md

@@ -7,7 +7,7 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.8.1 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.
@@ -16,7 +16,7 @@ Japanese text is retained in manuscript excerpts, rule dictionaries, and fixture
 
 ## Available features
 
-The following commands are available in version 0.8.1.
+The following commands are available in version 0.8.2.
 
 | Feature | Commands | Behavior |
 | --- | --- | --- |
@@ -107,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.1'
+gem 'asciidoc-pubkit', '~> 0.8.2'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -129,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.1.gem
+gem install ./asciidoc-pubkit-0.8.2.gem
 asciidoc-pubkit --version
 ```
 
@@ -153,7 +153,7 @@ 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.1.
+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
@@ -180,6 +180,19 @@ 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;
@@ -1044,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.1 (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.1
+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,56 +5,82 @@ 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)
-      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'] }
+      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 Error, "Invalid replacement regex: #{e.message}"
+      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/_;
@@ -92,25 +118,35 @@ module AsciidocPubkit
     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
-      data = YAML.safe_load(AsciidocPubkit.read_text(path), permitted_classes: [], aliases: false)
+      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.flat_map do |entry|
+      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']
@@ -121,9 +157,14 @@ module AsciidocPubkit
         collect(File.expand_path(entry, File.dirname(path)), active + [path], visited)
       end
       visited[path] = true
-      imported + rules
+      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 Error, "Invalid replacement YAML in #{path}: #{e.message}"
+      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)
@@ -138,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)
@@ -181,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.1'
+  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.1
+  version: 0.8.2
 platform: ruby
 authors:
 - CyberGarage