rsyntaxtree 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 231de78b2e34e37f4a5bbccd641839e8cf5ae1babc2d8d4362d86dcf782d28b4
-  data.tar.gz: a4d04e71e6587592540400aa9a7e23d9dadae0d19912078d5d6cc5ebd65c117d
+  metadata.gz: fe4cd7a8b28ffa968f99ff228e3a182a64d420e0405cd27e120b5f4ff02fe48e
+  data.tar.gz: 23a64934f448707de2b55cad4c206d65fab18aa7d6c1cd3aab0b1871efd9be1e
 SHA512:
-  metadata.gz: f97797690b6d8e0ad8404c00a10c061c89d2213e582915a33fc9d739305d5fb10cdd0afde6bffe0b16f504b5d5854d7dcb0249f50a22b10599638fb22180aed3
-  data.tar.gz: 7f5814cc9bf0875b21982cf6c143397d467fb900a7973c8f6213934387ba4f80e0605ddccec63f02bc7bacc6d182a9da1bda3237f909414ba4c64f63a1da1d12
+  metadata.gz: 2dfd53e10a62187649fb3d7285fa38189ef25cf56d6af7ceea27fba3cc7358b1f7d528db6466607061120fab61a2ff7bd9b84fa0b989e4313faaac306af42235
+  data.tar.gz: 7399787ea179bdd17910fa9695cc292a18cb5b8e9b3948e943bf32fd52fd05f89e6ec0e2792138197d56c839b9960bab678489a976590667eca9b4dd80679029

data/.dockerignore

@@ -0,0 +1,5 @@
+# The image needs the working tree, not the repository: without this, ADD .
+# copies .git into every image — hundreds of megabytes of history, including
+# refs that exist only on the build machine.
+.git
+pkg

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [2.2.0] - 2026-09-01
+
+### Changed
+- Validation reports every error of a stage, not just the first one found.
+  An input with three bad labels lists all three in the `errors` array of
+  the JSON diagnosis, so one round of fixes covers them. The stages are
+  ordered — options, bracket structure, labels, whole-tree checks — and a
+  mistake stops the later stages, with a `note` saying that fixing what is
+  listed may reveal more; nothing is reported whose appearance is an
+  artifact of an earlier mistake. Duplicate failures collapse to one entry
+  and the list stops at twenty. The schema is unchanged
+  (`rsyntaxtree.error/1`): the same array, more of it.
+
+### Added
+- `RSGenerator.diagnose(text, options)` returns the full diagnosis as a
+  hash — what `--validate` prints — for programmatic callers.
+  `check_data` keeps its contract of raising the first error.
+
 ## [2.1.0] - 2026-08-29
 
 ### Changed

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at <yohasebe@gmail.com>. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

data/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to RSyntaxTree
+
+This page explains how to report a problem, propose a change, and get a
+development environment running.
+
+## Reporting bugs
+
+Open an issue at <https://github.com/yohasebe/rsyntaxtree/issues> with:
+
+- the input text (the bracket notation) and the options you used
+- what you expected and what you got — for drawing problems, attach the image
+- your platform and how you run RSyntaxTree (gem, Docker, or the
+  [web interface](https://yohasebe.com/rsyntaxtree))
+
+If the input fails to draw, include the output of:
+
+```bash
+rsyntaxtree --validate "your input here"
+```
+
+It reports the problem in a structured form that is usually enough to
+diagnose the issue.
+
+## Suggesting features
+
+Open an issue describing what you want to draw and, ideally, a hand-drawn or
+published example of the intended output. The
+[gallery](https://yohasebe.github.io/rsyntaxtree/examples) shows the range of
+figures the notation covers today; a suggestion that names the linguistic
+framework it serves is easier to evaluate than one described purely in terms
+of graphics.
+
+Not every good idea belongs in RSyntaxTree. The project deliberately keeps
+the notation small, so proposals are weighed against what they add for
+users who do not need them.
+
+## Setting up for development
+
+System libraries first (Pango for text measurement, librsvg for rasterizing):
+
+```bash
+# Debian/Ubuntu
+apt install libpango1.0-dev librsvg2-dev libgirepository1.0-dev gobject-introspection
+
+# macOS
+brew install pkg-config pango librsvg gobject-introspection
+```
+
+The tests measure text with the Noto fonts, so install them too — the
+[Fonts](https://yohasebe.github.io/rsyntaxtree/documentation#fonts) section
+of the manual lists the package names for each platform.
+
+Then:
+
+```bash
+git clone https://github.com/yohasebe/rsyntaxtree.git
+cd rsyntaxtree
+bundle install
+bundle exec rake test
+```
+
+The tests should pass before and after your change.
+
+## Making changes
+
+- Every behavioral change needs a test that fails without it.
+- The committed gallery figures are generated inside Docker
+  (`rake docker_build && rake docker_generate`) so that font differences
+  between machines do not rewrite them. Do not regenerate them with a local
+  `rake generate`; if your change intentionally alters figures, say so in
+  the pull request and the maintainer will regenerate them.
+- The manual lives in `docs/documentation.md` (English) and
+  `docs/documentation_ja.md` (Japanese). If your change affects the
+  notation or an option, update at least the English manual; the reference
+  the gem installs (`lib/rsyntaxtree/notation_core.md`) and the LLM payload
+  (`rake llm_payload`) must be regenerated when examples or the manual
+  change — the test suite tells you when they are stale.
+
+## Pull requests
+
+Fork, branch, and open a pull request against `master`. A good pull request
+explains the problem before the solution and stays small enough to review.
+CI runs the test suite on Linux and an installation check on macOS; both
+must pass.
+
+## Questions
+
+For anything that does not fit an issue, contact the maintainer:
+Yoichiro Hasebe <yohasebe@gmail.com>.

data/README.md

@@ -135,23 +135,17 @@ See [Fonts](https://yohasebe.github.io/rsyntaxtree/documentation#install-fonts-f
 gem install rsyntaxtree
 ```
 
-### macOS Installation Notice
-
-**Important for macOS users:** If you encounter build errors for native extensions (`gobject-introspection`, `cairo-gobject`, `gio2`), run the following commands before installing RSyntaxTree:
-
-```bash
-gem install gobject-introspection -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-gem install cairo-gobject -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-gem install gio2 -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-```
-
-Then install RSyntaxTree:
-
-```bash
-gem install rsyntaxtree
-```
-
-Alternatively, use the [Docker image](https://hub.docker.com/r/yohasebe/rsyntaxtree) or the [web interface](https://yohasebe.com/rsyntaxtree).
+### macOS
+
+With the libraries in place (`brew install pkg-config pango librsvg
+gobject-introspection`), a plain `gem install rsyntaxtree` builds the native
+extensions without further options — CI verifies this on every change. If an
+older setup still fails to build `gobject-introspection`, `cairo-gobject` or
+`gio2`, install those three first with
+`-- --with-ldflags="-Wl,-undefined,dynamic_lookup"` appended, then install
+RSyntaxTree; or skip the build entirely with the
+[Docker image](https://hub.docker.com/r/yohasebe/rsyntaxtree) or the
+[web interface](https://yohasebe.com/rsyntaxtree).
 
 ## Usage
 

data/bin/rsyntaxtree

@@ -214,12 +214,9 @@ data = RSyntaxTree::FormatConverter.to_bracket(data) if data
 # Validate without drawing or writing anything: the diagnosis goes to stdout
 # as JSON and the exit code carries the verdict.
 if opts[:validate]
-  diagnosis = begin
-    RSyntaxTree::RSGenerator.check_data(data, string_opts)
-    { "schema" => "rsyntaxtree.error/1", "ok" => true }
-  rescue RSTError => e
-    { "schema" => "rsyntaxtree.error/1" }.merge(e.to_h)
-  end
+  diagnosis = { "schema" => "rsyntaxtree.error/1" }.merge(
+    RSyntaxTree::RSGenerator.diagnose(data, string_opts)
+  )
   puts JSON.pretty_generate(diagnosis)
   exit(diagnosis["ok"] ? 0 : 1)
 end

data/lib/rsyntaxtree/notation_examples.md

@@ -1,4 +1,4 @@
-RSyntaxTree examples: 80 trees, every one verified to draw.
+RSyntaxTree examples: 81 trees, every one verified to draw.
 
 Each is the input behind a figure in the gallery at https://yohasebe.github.io/rsyntaxtree/examples.
 The settings line names the options the gallery records for that figure;
@@ -2586,30 +2586,56 @@ VAL\t#(SPR\t⟨<>⟩#)#)#)
   VAL\t#(SPR\t⟨<>*NP*<>⟩#)#)#) [barks]]]
 ```
 
-## 085 — A tree on a tilted plane
+## 085 — A tree on a tilted plane, with a movement path
 
 Category: General
 Settings: fontstyle=noto-serif shear=20 vheight=1.0
 
 ```
-[S
-  [NP
-    [D the]
-    [N man]
-  ]
-  [VP
-    [V put]
-    [NP
-      [D the]
-      [N book]
-    ]
-    [PP
-      [P on]
+[CP
+  [NP what+>1]
+  [C'
+    [C did]
+    [TP
       [NP
         [D the]
-        [N table]
+        [N man]
+      ]
+      [VP
+        [V'
+          [V put]
+          [NP *t*+1]
+        ]
+        [PP
+          [P on]
+          [NP
+            [D the]
+            [N table]
+          ]
+        ]
       ]
     ]
   ]
 ]
 ```
+
+## 086 — Feature structures on a tilted plane
+
+Category: General
+Settings: color=none fontstyle=noto-serif leafstyle=nothing shear=20 vheight=1.5
+
+```
+[#(*phrase*\
+---\
+SYN\t#(HEAD\t|1|#)#)
+  [#(*word*\
+  ---\
+  SYN\t#(HEAD\t#(*noun*\
+  ---\
+  AGR\t|2|#(NUM\t*pl*#)#)#)#) [dogs]]
+  [#(*word*\
+  ---\
+  SYN\t#(HEAD\t|1|#(*verb*\
+  ---\
+  AGR\t|2|#)#)#) [bark]]]
+```

data/lib/rsyntaxtree/string_parser.rb

@@ -15,9 +15,23 @@ require_relative 'utils'
 module RSyntaxTree
   class StringParser
     attr_accessor :data, :elist, :pos, :id, :level
+    attr_reader :collected_errors
 
-    def initialize(str, fontset, fontsize, global)
+    # In collect mode, reporting stops here but the walk does not: labels
+    # past this many failures are still checked (the tree must stay whole)
+    # without adding to the list.
+    COLLECTED_ERRORS_LIMIT = 20
+
+    # What stands in for a label that would not parse, when collecting.
+    # Any label that always parses will do; what matters is that it keeps
+    # the tree's shape.
+    PLACEHOLDER_LABEL = "x"
+
+    def initialize(str, fontset, fontsize, global, collect_errors: false)
       @global = global
+      @collect_errors = collect_errors
+      @collected_errors = []
+      @more_errors = false
       # Clean up the data a little to make processing easier
       # repeated newlines => a newline
       string = str.gsub(/[\n\r]+/m, "\n")
@@ -113,6 +127,41 @@ module RSyntaxTree
       restore_rule_names_without_a_rule
     end
 
+    def more_errors?
+      @more_errors
+    end
+
+    # One element, or its recorded failure. Outside collect mode this is
+    # exactly the Element.new it wraps. In collect mode an RSTError is
+    # recorded and a placeholder element stands in, so the walk continues
+    # and every bad label is seen. The placeholder keeps the tree's shape —
+    # parenthood, childlessness, level — which is all a later label's
+    # verdict can depend on; what it cannot keep (a path marker the broken
+    # label carried) only matters to the whole-tree checks, and those do
+    # not run while collected errors stand.
+    def element_or_recorded_failure(id, parent, level, names_a_rule = false)
+      yield
+    rescue RSTError => e
+      raise unless @collect_errors
+
+      record_failure(e)
+      Element.new(id, parent, PLACEHOLDER_LABEL, level, @fontset, @fontsize, @global, names_a_rule)
+    end
+
+    # The same mistake in two copies of a label is one thing to fix, so a
+    # failure is recorded once per (code, label, position). Past the limit
+    # the list stops growing and only the fact that there was more is kept.
+    def record_failure(error)
+      key = [error.code, error.label, error.position]
+      return if @collected_errors.any? { |c| [c.code, c.label, c.position] == key }
+
+      if @collected_errors.length >= COLLECTED_ERRORS_LIMIT
+        @more_errors = true
+      else
+        @collected_errors << error
+      end
+    end
+
     # A rule name names the step that produced a node from its daughters. A node
     # with no daughters is the product of no step, so what looked like a name is
     # a column of the label like any other, and it goes back.
@@ -128,8 +177,17 @@ module RSyntaxTree
         next unless e.children.empty?
         next if e.label_with_rule_name.nil?
 
-        restored = Element.new(e.id, e.parent, e.label_with_rule_name,
-                               e.level, @fontset, @fontsize, @global)
+        # In collect mode the failed restoration is recorded and the element
+        # kept as it is; the tree stays whole either way.
+        restored = begin
+          Element.new(e.id, e.parent, e.label_with_rule_name,
+                      e.level, @fontset, @fontsize, @global)
+        rescue RSTError => err
+          raise unless @collect_errors
+
+          record_failure(err)
+          next
+        end
         restored.children = e.children
         restored.type = e.type
         @elist.elements[i] = restored
@@ -226,7 +284,9 @@ module RSyntaxTree
           # Check for escaped square brackets
           if token =~ /\A\\\[/ || token =~ /\A\\\]/
             # Treat escaped brackets as regular text
-            element = Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            element = element_or_recorded_failure(@id, parent, @level) do
+              Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            end
             @id += 1
             @elist.add(element)
           else
@@ -241,7 +301,7 @@ module RSyntaxTree
               tl = token_r.length
               parts[1] = token_r[spaceat, tl - spaceat].join
 
-              element = begin
+              element = element_or_recorded_failure(@id, parent, @level, true) do
                 Element.new(@id, parent, parts[0], @level, @fontset, @fontsize, @global, true)
               rescue RSTError => e
                 # The first raw space splits a token into the node's label
@@ -277,11 +337,15 @@ module RSyntaxTree
               @elist.add(element)
               newparent = element.id
 
-              element = Element.new(@id, @id - 1, parts[1], @level + 1, @fontset, @fontsize, @global)
+              element = element_or_recorded_failure(@id, @id - 1, @level + 1) do
+                Element.new(@id, @id - 1, parts[1], @level + 1, @fontset, @fontsize, @global)
+              end
               @id += 1
             else
               joined = token_r.join
-              element = Element.new(@id, parent, joined, @level, @fontset, @fontsize, @global, true)
+              element = element_or_recorded_failure(@id, parent, @level, true) do
+                Element.new(@id, parent, joined, @level, @fontset, @fontsize, @global, true)
+              end
               @id += 1
               newparent = element.id
             end
@@ -291,7 +355,9 @@ module RSyntaxTree
           end
         else
           if token.strip != ""
-            element = Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            element = element_or_recorded_failure(@id, parent, @level) do
+              Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            end
             @id += 1
             @elist.add(element)
           end

data/lib/rsyntaxtree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSyntaxTree
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/lib/rsyntaxtree.rb

@@ -139,14 +139,20 @@ class RSTError < StandardError
   # the top, rather than repeated on every error.
   REFERENCE = "rsyntaxtree --notation, or https://yohasebe.github.io/rsyntaxtree/llms-full.txt"
 
+  # One error as the hash the JSON diagnosis carries; to_h wraps a single
+  # one and diagnose collects many.
+  def error_entry
+    { "code" => code.to_s,
+      "message" => message,
+      "label" => label,
+      "position" => position,
+      "hint" => hint,
+      "retryable" => retryable }.compact
+  end
+
   def to_h
     { "ok" => false,
-      "errors" => [{ "code" => code.to_s,
-                     "message" => message,
-                     "label" => label,
-                     "position" => position,
-                     "hint" => hint,
-                     "retryable" => retryable }.compact],
+      "errors" => [error_entry],
       "reference" => REFERENCE }
   end
 end
@@ -185,13 +191,13 @@ module RSyntaxTree
 
         if REMOVED_OPTIONS.key?(key)
           raise RSTError.new(+"Error: option '#{key}' was removed in RSyntaxTree 2.0",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "Use #{REMOVED_OPTIONS[key]} instead.",
                              retryable: false)
         end
         if OPTION_VALUES.key?(key) && !OPTION_VALUES[key].include?(value.to_s)
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' must be one of: #{OPTION_VALUES[key].join(', ')}.",
                              retryable: false)
         end
@@ -202,14 +208,14 @@ module RSyntaxTree
         if NUMERIC_RANGES.key?(key) && !value.is_a?(Numeric) &&
            value.to_s.strip !~ /\A-?(\d+(\.\d+)?|\.\d+)\z/
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' takes a number.",
                              retryable: false)
         end
         if NUMERIC_RANGES.key?(key) && !NUMERIC_RANGES[key].cover?(value.to_f)
           range = NUMERIC_RANGES[key]
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' must be in the range of #{range.begin}-#{range.end}.",
                              retryable: false)
         end
@@ -288,7 +294,7 @@ module RSyntaxTree
                               else
                                 unless COLOR_NAMES.include?(v.downcase) || v =~ /\A#(\h{3}|\h{6})\z/
                                   raise RSTError.new(+"Error: invalid value for option 'shear_plane': #{value.inspect}",
-                                                     code: :invalid_option,
+                                                     code: :invalid_option, label: "shear_plane",
                                                      hint: "'shear_plane' is on, off, a colour name, " \
                                                            "or a hex colour of 3 or 6 digits.",
                                                      retryable: false)
@@ -333,7 +339,7 @@ module RSyntaxTree
       # the combination is refused rather than approximated.
       if @params[:derivation] == true && @params[:direction] == "ltr"
         raise RSTError.new(+"Error: a derivation cannot be drawn left to right",
-                           code: :invalid_option,
+                           code: :invalid_option, label: "derivation",
                            hint: "A derivation runs down the page. Use direction ttb or btt, " \
                                  "or turn derivation off.",
                            retryable: false)
@@ -346,7 +352,7 @@ module RSyntaxTree
       # them. Refused for the same reason as left to right.
       if @params[:derivation] == true && @params[:hide_default_connectors] == true
         raise RSTError.new(+"Error: a derivation's rules cannot be hidden",
-                           code: :invalid_option,
+                           code: :invalid_option, label: "derivation",
                            hint: "The rules are what a derivation is drawn with, not a " \
                                  "connector added to it. Turn off hide default connectors, " \
                                  "or turn derivation off.",
@@ -448,6 +454,101 @@ module RSyntaxTree
       end
     end
 
+    # Every option error at once. The constructor is the only judge of an
+    # option, and its rules are not written out a second time here: it
+    # stops at its first complaint, so it is asked again with the option
+    # it complained about set aside, until it accepts what is left or
+    # names nothing to set aside. Each round removes one option, so the
+    # loop is as bounded as the option list.
+    def self.option_errors(params)
+      remaining = params.reject { |k, _| k.to_sym == :data }
+      errors = []
+      loop do
+        begin
+          new(remaining.merge(data: "[A a]"))
+          break
+        rescue RSTError => e
+          errors << e
+          key = e.label
+          break if key.nil? || remaining.keys.none? { |k| k.to_s == key }
+
+          remaining = remaining.reject { |k, _| k.to_s == key }
+        end
+      end
+      errors
+    end
+
+    # Parse in collect mode: every label that will not parse, and every
+    # rule name that turns out to have no rule behind it, recorded instead
+    # of raised. The walk is the real one — the same tokens, the same
+    # judgments — so what this reports and what drawing rejects cannot
+    # drift apart. Returns the errors and whether the list was cut short.
+    def collect_input_errors
+      sp = StringParser.new(@params[:data].gsub('&', '&amp;'), @params[:fontset],
+                            @params[:fontsize], @global, collect_errors: true)
+      sp.parse
+      [sp.collected_errors, sp.more_errors?]
+    end
+
+    NOTE_OPTIONS = "Not every option could be read, so the input itself has " \
+                   "not been checked yet; fixing the options may reveal more."
+    NOTE_STRUCTURE = "The bracket structure could not be read, so the labels " \
+                     "have not been checked yet; fixing it may reveal more."
+    NOTE_LABELS = "Whole-tree checks (paths, output limits) run only once " \
+                  "every label reads, so fixing these may reveal more."
+    NOTE_TRUNCATED = " Only the first #{StringParser::COLLECTED_ERRORS_LIMIT} " \
+                     "problems are listed."
+
+    # The whole diagnosis at once, as the hash the CLI prints: every error
+    # of the first stage that finds any, not just the first error found.
+    # Stages are ordered so that nothing is reported whose appearance is an
+    # artifact of an earlier mistake — a missing bracket shifts every token
+    # after it, an unreadable hyphen option changes what counts as markup —
+    # and when a stage stops the walk, the note says that fixing what is
+    # listed may reveal more. check_data keeps its contract (raise the
+    # first error) for callers that want a verdict rather than a list.
+    def self.diagnose(text, params = {})
+      errors = []
+      note = nil
+      if text.to_s == ""
+        errors << RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false)
+      else
+        begin
+          errors = option_errors(params)
+          if errors.any?
+            note = NOTE_OPTIONS
+          else
+            StringParser.valid?(text)
+            gen = new(params.merge(data: text))
+            collected, truncated = gen.collect_input_errors
+            if collected.any?
+              errors = collected
+              note = NOTE_LABELS
+              note += NOTE_TRUNCATED if truncated
+            else
+              gen.validate!
+            end
+          end
+        rescue RSTError => e
+          errors << e
+          note = NOTE_STRUCTURE if %i[empty_brackets unbalanced_brackets].include?(e.code)
+        rescue StandardError => e
+          # The same promise check_data makes: a defect anywhere in here —
+          # the option probing included — is still a verdict of "no", in
+          # the same shape, not a backtrace.
+          errors << RSTError.new(+"Error: input could not be processed (#{e.class})",
+                                 code: :internal_error, retryable: false)
+        end
+      end
+
+      return { "ok" => true } if errors.empty?
+
+      result = { "ok" => false, "errors" => errors.map(&:error_entry) }
+      result["note"] = note if note
+      result["reference"] = RSTError::REFERENCE
+      result
+    end
+
     # Generate, and throw the result away. Parsing alone leaves out the
     # checks that only happen once the tree is laid out — a movement path
     # with one end, a line with three — so validation that stopped at the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsyntaxtree
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Yoichiro Hasebe
@@ -115,8 +115,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".dockerignore"
 - CHANGELOG.md
 - CITATION.cff
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
 - README.md
 - bin/rsyntaxtree