statifier 0.0.1 → 0.1.0

data/lib/statifier/validator/error.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # Why a chart does not validate: a reason symbol, the detail that reason
+    # carries (a frozen Hash), a message for a person, and the span reported.
+    # The shape of {Lowering::Error}. An error gates compilation: a chart
+    # with one is not compiled.
+    #
+    # The reasons and their detail, each the reference's:
+    #
+    # - ids: `:duplicate_id` (`id`), `:empty_id`;
+    # - targets: `:unresolved_target` (`id`), `:unresolved_initial` (`id`),
+    #   `:initial_not_descendant` (`id`, `parent_id`),
+    #   `:initial_on_atomic_state` (`id`);
+    # - default transitions: `:initial_attribute_and_element` (`id`),
+    #   `:transition_count` (`owner`, `count`), `:transition_missing_target`
+    #   (`owner`), `:transition_forbidden_attribute` (`owner`, `attribute`,
+    #   `:event` or `:cond`); an `owner` is a frozen Hash, `kind` (`:initial`
+    #   or `:history`) and `id`, the owning state's id;
+    # - history and final: `:history_bad_parent` (`id`, `parent_kind`),
+    #   `:history_bad_type` (`raw`), `:final_has_states` (`id`),
+    #   `:final_has_transitions` (`id`), `:final_parent_missing_id`
+    #   (`final_id`), `:default_entry_not_enterable` (`id`, `child_kind`);
+    # - enumerated values, read as written: `:transition_bad_type`,
+    #   `:scxml_bad_binding`, `:scxml_bad_datamodel`,
+    #   `:invoke_bad_autoforward` (each `raw`);
+    # - the root: `:bad_namespace` (`uri`), `:bad_version` (`version`);
+    # - data: `:donedata_not_on_final` (`id`), `:donedata_content_and_params`
+    #   (`id`), `:content_expr_and_text` (`expr`), `:param_expr_and_location`
+    #   (`name`), `:param_no_value` (`name`), `:data_expr_and_src` (`id`),
+    #   `:data_value_and_children` (`id`), `:data_reserved_id` (`id`),
+    #   `:datamodel_bad_parent` (`kind`);
+    # - executable content: `:assign_expr_and_text` (`expr`),
+    #   `:if_elseif_after_else`, `:if_duplicate_else`,
+    #   `:script_no_src_or_text`, `:invoke_type_and_typeexpr`,
+    #   `:invoke_src_and_srcexpr`, `:invoke_src_and_content`,
+    #   `:invoke_id_and_idlocation`, `:invoke_namelist_and_param`,
+    #   `:send_event_and_eventexpr`, `:send_target_and_targetexpr`,
+    #   `:send_type_and_typeexpr`, `:send_id_and_idlocation`,
+    #   `:send_delay_and_delayexpr`, `:send_delay_and_internal_target`,
+    #   `:send_namelist_and_content`, `:send_param_and_content`,
+    #   `:cancel_sendid_and_sendidexpr`, `:cancel_no_sendid`;
+    # - the markup: `:duplicate_attribute` (`element`, `attribute`).
+    #
+    # A reason listed without detail carries an empty Hash.
+    #
+    # @api private
+    Error = ::Data.define(:reason, :detail, :message, :location)
+
+    # A finding that does not gate compilation: the chart is compiled either
+    # way, and the engine has a behavior for it. The shape of {Error}. The
+    # one reason is `:finalize_forbidden_content` (`element`, `"raise"` or
+    # `"send"`): an element the specification forbids inside `<finalize>`.
+    #
+    # @api private
+    Warning = ::Data.define(:reason, :detail, :message, :location)
+
+    # The constructors of {Error} and {Warning}, with the reference's
+    # messages.
+    #
+    # @api private
+    module Findings
+      SCXML = Lowering::SCXML_NAMESPACE
+
+      module_function
+
+      # @return [Error] the error `reason` with `detail`, at `location`;
+      #   `wording` reaches the message and is not kept in the detail
+      def error(reason, location, wording: nil, **detail)
+        make(Error, Messages::ERROR, [reason, location, wording], detail)
+      end
+
+      # @return [Warning] the warning `reason` with `detail`, at `location`
+      def warning(reason, location, **detail) = make(Warning, Messages::WARNING, [reason, location, nil], detail)
+
+      # A finding with its detail and message frozen.
+      def make(type, messages, (reason, location, wording), detail)
+        frozen = detail.transform_values { _1.is_a?(Hash) ? _1.dup.freeze : _1 }.freeze
+        message = messages.fetch(reason).call(wording.nil? ? frozen : frozen.merge(wording:))
+        type.new(reason:, detail: frozen, message: message.freeze, location:)
+      end
+
+      # A value as the reference inspects it: a string quoted, nil as `nil`.
+      def inspect_value(value) = value.nil? ? "nil" : Lowering::Errors.quote(value)
+    end
+  end
+end
+
+require_relative "messages"

data/lib/statifier/validator/executable.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The checks of executable content and of `<invoke>`.
+    #
+    # Each reaches the nodes the reference's own check reaches. Every check
+    # reads a state's `<onentry>` and `<onexit>` blocks, its transitions and
+    # its `<initial>` element's, descending into `<if>` branches and
+    # `<foreach>` bodies; the `<send>` and `<cancel>` checks also read every
+    # `<invoke>`'s `<finalize>`, and the `<script>` check the root's
+    # scripts. A `<send>`'s `<content>` is not read by the `<content>` check.
+    #
+    # @api private
+    module Executable
+      # Whether both attributes were written.
+      BOTH = ->(node, name, partner) { !node.public_send(name).nil? && !node.public_send(partner).nil? }
+
+      # The rules of an `<invoke>`, in the reference's order.
+      INVOKE_RULES = {
+        invoke_type_and_typeexpr: ->(node) { BOTH.call(node, :type, :typeexpr) },
+        invoke_src_and_srcexpr: ->(node) { BOTH.call(node, :src, :srcexpr) },
+        invoke_src_and_content: ->(node) { !node.content.nil? && !(node.src || node.srcexpr).nil? },
+        invoke_id_and_idlocation: ->(node) { BOTH.call(node, :id, :idlocation) },
+        invoke_namelist_and_param: ->(node) { !node.namelist.empty? && !node.params.empty? }
+      }.freeze
+
+      # The targets a delay may not be written beside.
+      INTERNAL = %w[_internal #_internal].freeze
+
+      # The rules of a `<send>`, in the reference's order. A delay beside an
+      # internal target is refused only when the target is written literally:
+      # with `targetexpr` it is not known before the send executes.
+      SEND_RULES = {
+        send_event_and_eventexpr: ->(node) { BOTH.call(node, :event, :eventexpr) },
+        send_target_and_targetexpr: ->(node) { BOTH.call(node, :target, :targetexpr) },
+        send_type_and_typeexpr: ->(node) { BOTH.call(node, :type, :typeexpr) },
+        send_id_and_idlocation: ->(node) { BOTH.call(node, :id, :idlocation) },
+        send_delay_and_delayexpr: ->(node) { BOTH.call(node, :delay, :delayexpr) },
+        send_delay_and_internal_target: lambda do |node|
+          INTERNAL.include?(node.target) && !(node.delay || node.delayexpr).nil?
+        end,
+        send_namelist_and_content: ->(node) { !node.namelist.empty? && !node.content.nil? },
+        send_param_and_content: ->(node) { !node.params.empty? && !node.content.nil? }
+      }.freeze
+
+      # The element a `<finalize>` may not hold, by node class.
+      FORBIDDEN_IN_FINALIZE = { Document::Raise => "raise", Document::Send => "send" }.freeze
+
+      module_function
+
+      # Every node of a state's blocks and transitions, in document order, a
+      # composite before what it holds.
+      def state_nodes(state)
+        initial = state.initial_element&.transitions || Lowering::Reading::EMPTY
+        content = [*state.onentry, *state.onexit, *state.transitions, *initial].flat_map(&:content)
+        content.flat_map { descend(_1) }
+      end
+
+      # The nodes of every `<finalize>` of a state's `<invoke>` children.
+      def finalize_nodes(state) = state.invoke.filter_map(&:finalize).flat_map(&:content).flat_map { descend(_1) }
+
+      # `node` and every node an `<if>` or `<foreach>` holds below it.
+      def descend(node)
+        inner = case node
+                when Document::If then node.branches.flat_map(&:content)
+                when Document::Foreach then node.content
+                else Lowering::Reading::EMPTY
+                end
+        [node, *inner.flat_map { descend(_1) }]
+      end
+
+      # Every `<send>`, its `<finalize>` ones included.
+      def sends(context)
+        context.states.flat_map { state_nodes(_1) + finalize_nodes(_1) }.grep(Document::Send)
+      end
+
+      # An `<assign>` does not carry both `expr` and child content, markup or
+      # text that is not blank; at the element's span.
+      def assigns(_document, context)
+        context.states.flat_map { state_nodes(_1) }.grep(Document::Assign).filter_map do |assign|
+          next if assign.expr.nil? || (assign.markup.nil? && Lowering::Reading.blank?(assign.text))
+
+          Findings.error(:assign_expr_and_text, assign.node_location, expr: assign.expr)
+        end
+      end
+
+      # Every branch after an `<if>`'s first `<else>` is out of order: another
+      # `<else>` is a duplicate, an `<elseif>` follows it.
+      def ifs(_document, context)
+        context.states.flat_map { state_nodes(_1) }.grep(Document::If).flat_map do |node|
+          after_else = node.branches.drop_while { !_1.cond.nil? }.drop(1)
+          after_else.map do |branch|
+            Findings.error(branch.cond.nil? ? :if_duplicate_else : :if_elseif_after_else, branch.location)
+          end
+        end
+      end
+
+      # A `<script>` has a program: text that is not blank.
+      def scripts(document, context)
+        all = context.states.flat_map { state_nodes(_1) }.grep(Document::Script) + document.scripts
+        all.select { Lowering::Reading.blank?(_1.text) }.map { Findings.error(:script_no_src_or_text, _1.location) }
+      end
+
+      # An `<invoke>`'s exclusive pairs, each at its span.
+      def invokes(_document, context) = broken(context.states.flat_map(&:invoke), INVOKE_RULES)
+
+      # A `<send>`'s exclusive pairs, each at its span.
+      def sends_check(_document, context) = broken(sends(context), SEND_RULES)
+
+      # A `<cancel>` carries exactly one of `sendid` and `sendidexpr`.
+      def cancels(_document, context)
+        all = context.states.flat_map { state_nodes(_1) + finalize_nodes(_1) }.grep(Document::Cancel)
+        all.filter_map do |cancel|
+          written = [cancel.sendid, cancel.sendidexpr].compact.size
+          next if written == 1
+
+          Findings.error(written.zero? ? :cancel_no_sendid : :cancel_sendid_and_sendidexpr, cancel.location)
+        end
+      end
+
+      # The error of each rule each node breaks, at the node's span.
+      def broken(nodes, rules)
+        nodes.flat_map do |node|
+          rules.select { |_, rule| rule.call(node) }.keys.map { Findings.error(_1, node.location) }
+        end
+      end
+
+      # The warning: a `<raise>` or `<send>` inside a `<finalize>`, at its own
+      # span.
+      def finalize_warnings(_document, context)
+        context.states.flat_map { finalize_nodes(_1) }.filter_map do |node|
+          element = FORBIDDEN_IN_FINALIZE[node.class]
+          Findings.warning(:finalize_forbidden_content, node.location, element:) if element
+        end
+      end
+    end
+  end
+end

data/lib/statifier/validator/history.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The checks of history states, final states and default entry.
+    #
+    # @api private
+    module History
+      HISTORY_TYPES = %w[shallow deep].freeze
+
+      module_function
+
+      # A history state: its parent is a compound `<state>` or `<parallel>`,
+      # it has one default transition, that transition's resolved targets
+      # lie inside the parent, and its `type` as written is in range.
+      def histories(_document, context)
+        context.states.select { _1.kind == :history }.flat_map do |state|
+          parent = context.parents.fetch(state)
+          compound = Index.compound?(parent)
+          bad_parent(state, parent, compound) +
+            default_transition(state) + outside_parent(state, parent, compound, context) +
+            Enums.out_of_range(state, :type, HISTORY_TYPES, context, :history_bad_type)
+        end
+      end
+
+      # A history's own transitions, as its one default transition.
+      def default_transition(state)
+        States.default_transition({ kind: :history, id: state.id }, state.transitions, state.location)
+      end
+
+      # The resolved default targets outside a compound parent; a parent
+      # that is not compound is reported once, as such, and not tested.
+      def outside_parent(state, parent, compound, context)
+        compound ? state.transitions.flat_map { States.outside_targets(_1, parent, context) } : []
+      end
+
+      # The `:history_bad_parent` error of a history whose parent is not
+      # compound; the root's kind is `:scxml`.
+      def bad_parent(state, parent, compound)
+        return [] if compound
+
+        parent_kind = parent.is_a?(Document::State) ? parent.kind : :scxml
+        [Findings.error(:history_bad_parent, state.location, id: state.id, parent_kind:)]
+      end
+
+      # A `<final>` holds no state and no transition: each is reported at its
+      # own span.
+      def finals(_document, context)
+        context.states.select { _1.kind == :final }.flat_map do |state|
+          state.states.map { Findings.error(:final_has_states, _1.location, id: _1.id) } +
+            state.transitions.map { Findings.error(:final_has_transitions, _1.location, id: state.id) }
+        end
+      end
+
+      # A state with a `<final>` child has an id, since the completion event
+      # is named after it. Reported once per parent, at its span, naming its
+      # first `<final>`.
+      def final_parents(_document, context)
+        context.states.filter_map do |state|
+          first = state.states.find { _1.kind == :final }
+          next if !state.id.nil? || first.nil?
+
+          Findings.error(:final_parent_missing_id, state.location, final_id: first.id)
+        end
+      end
+
+      # A `<state>` entered by default enters its first child, and a history
+      # cannot be entered that way. A `<parallel>` enters every child, so it
+      # is not read here.
+      def default_entries(_document, context)
+        context.states.filter_map do |state|
+          first = state.states.first
+          next unless state.kind == :state && state.initial.empty? && state.initial_element.nil?
+          next unless first&.kind == :history
+
+          Findings.error(:default_entry_not_enterable, first.location, id: state.id, child_kind: :history)
+        end
+      end
+    end
+  end
+end

data/lib/statifier/validator/messages.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The message of each reason, made from its detail: the reference's
+    # wording, with its quoting of values.
+    #
+    # @api private
+    module Messages
+      q = Findings.method(:inspect_value)
+      owner = lambda do |detail|
+        kind, id = detail[:owner].values_at(:kind, :id)
+        element = "<#{kind}>"
+        next element if id.nil?
+
+        kind == :initial ? "#{element} on #{q.call(id)}" : "#{element} #{q.call(id)}"
+      end
+
+      # The messages of the state, target and default-transition reasons.
+      STATES = {
+        duplicate_id: ->(d) { "duplicate state id #{q.call(d[:id])}" },
+        empty_id: ->(_) { "state id must not be empty - an absent id is legal, an empty one is not" },
+        unresolved_target: ->(d) { "transition target #{q.call(d[:id])} does not resolve to a state in the document" },
+        unresolved_initial: ->(d) { "initial state #{q.call(d[:id])} does not resolve to a state in the document" },
+        initial_not_descendant: lambda do |d|
+          parent = d[:parent_id].nil? ? "its parent state, which has no id" : q.call(d[:parent_id])
+          "initial state #{q.call(d[:id])} is not a descendant of #{parent}"
+        end,
+        initial_on_atomic_state: lambda do |d|
+          "#{d[:id].nil? ? "a state with no id" : "state #{q.call(d[:id])}"} has no child states to default into"
+        end,
+        initial_attribute_and_element: lambda do |d|
+          "state #{q.call(d[:id])} has both an initial attribute and an <initial> element - at most one is legal"
+        end,
+        transition_count: ->(d) { "#{owner.call(d)} must have exactly one transition, found #{d[:count]}" },
+        transition_missing_target: ->(d) { "#{owner.call(d)} transition must specify a target" },
+        transition_forbidden_attribute: ->(d) { "#{owner.call(d)} transition must not specify #{d[:attribute]}" },
+        history_bad_parent: lambda do |d|
+          "history #{q.call(d[:id])} must be a child of a compound <state> or <parallel>, not #{d[:parent_kind]}"
+        end,
+        history_bad_type: ->(d) { "history type #{q.call(d[:raw])} must be \"shallow\" or \"deep\"" },
+        final_has_states: lambda do |d|
+          "state #{q.call(d[:id])} must not be a child of <final> - only onentry, onexit, and donedata are legal there"
+        end,
+        final_has_transitions: lambda do |d|
+          "state #{q.call(d[:id])} is a <final> and must not carry a <transition> - " \
+            "only onentry, onexit, and donedata are legal there"
+        end,
+        final_parent_missing_id: lambda do |_|
+          "a state containing a <final> child must have an id - its completion event is named done.state.<id>"
+        end,
+        default_entry_not_enterable: lambda do |d|
+          "state #{q.call(d[:id])} has no initial attribute or <initial> element, and its first child is a " \
+            "#{d[:child_kind]} pseudo-state, which cannot be entered by default"
+        end
+      }.freeze
+
+      # The messages of the root, enumerated-value and data reasons.
+      DATA = {
+        transition_bad_type: ->(d) { "transition type #{q.call(d[:raw])} must be \"internal\" or \"external\"" },
+        scxml_bad_binding: ->(d) { "binding #{q.call(d[:raw])} must be \"early\" or \"late\"" },
+        scxml_bad_datamodel: lambda do |d|
+          "datamodel #{q.call(d[:raw])} must be one of \"predicator\", \"elixir\", \"null\", \"ecmascript\", " \
+            "or \"xpath\""
+        end,
+        invoke_bad_autoforward: ->(d) { "invoke autoforward #{q.call(d[:raw])} must be \"true\" or \"false\"" },
+        bad_namespace: lambda do |d|
+          next "the root element declares no namespace - expected xmlns=#{q.call(Findings::SCXML)}" if d[:uri].nil?
+
+          "the root element's namespace #{q.call(d[:uri])} is not the SCXML namespace #{q.call(Findings::SCXML)}"
+        end,
+        bad_version: lambda do |d|
+          next "the root element has no version attribute, expected \"1.0\"" if d[:version].nil?
+
+          "the root element's version #{q.call(d[:version])} must be \"1.0\""
+        end,
+        donedata_not_on_final: ->(d) { "state #{q.call(d[:id])} carries <donedata>, which is only legal on <final>" },
+        donedata_content_and_params: lambda do |d|
+          "<donedata> on #{q.call(d[:id])} must not specify both a <content> child and one or more <param> children"
+        end,
+        content_expr_and_text: lambda do |d|
+          "<content> must not specify both an expr attribute (#{q.call(d[:expr])}) and inline #{d[:wording]}"
+        end,
+        param_expr_and_location: lambda do |d|
+          "<param> #{q.call(d[:name])} must not specify both an expr attribute and a location attribute"
+        end,
+        param_no_value: lambda do |d|
+          "<param> #{q.call(d[:name])} must specify either an expr attribute or a location attribute"
+        end,
+        data_expr_and_src: ->(d) { "<data> #{q.call(d[:id])} must not specify both expr and src" },
+        data_value_and_children: lambda do |d|
+          "<data> #{q.call(d[:id])} must not specify expr or src together with child content"
+        end,
+        data_reserved_id: ->(d) { "<data> id #{q.call(d[:id])} must not begin with \"_\" - that prefix is reserved" },
+        datamodel_bad_parent: ->(d) { "<datamodel> must not be a child of a #{d[:kind]} state" }
+      }.freeze
+    end
+
+    # The messages, continued.
+    #
+    # @api private
+    module Messages
+      q = Findings.method(:inspect_value)
+
+      # The messages of the executable-content and markup reasons.
+      EXECUTABLE = {
+        assign_expr_and_text: lambda do |d|
+          "<assign> must not specify both an expr attribute (#{q.call(d[:expr])}) and child content"
+        end,
+        if_elseif_after_else: ->(_) { "<elseif> must not follow <else> - <else> must occur after all <elseif> tags" },
+        if_duplicate_else: ->(_) { "<if> must not carry more than one <else> branch" },
+        script_no_src_or_text: ->(_) { "<script> must specify either the src attribute or child content" },
+        invoke_type_and_typeexpr: ->(_) { "<invoke> must not specify both type and typeexpr" },
+        invoke_src_and_srcexpr: ->(_) { "<invoke> must not specify both src and srcexpr" },
+        invoke_src_and_content: ->(_) { "<invoke> must not specify src or srcexpr together with a <content> child" },
+        invoke_id_and_idlocation: ->(_) { "<invoke> must not specify both id and idlocation" },
+        invoke_namelist_and_param: ->(_) { "<invoke> must not specify namelist together with a <param> child" },
+        send_event_and_eventexpr: ->(_) { "<send> must not specify both event and eventexpr" },
+        send_target_and_targetexpr: ->(_) { "<send> must not specify both target and targetexpr" },
+        send_type_and_typeexpr: ->(_) { "<send> must not specify both type and typeexpr" },
+        send_id_and_idlocation: ->(_) { "<send> must not specify both id and idlocation" },
+        send_delay_and_delayexpr: ->(_) { "<send> must not specify both delay and delayexpr" },
+        send_delay_and_internal_target: lambda do |_|
+          "<send> must not specify delay or delayexpr when target is \"_internal\""
+        end,
+        send_namelist_and_content: ->(_) { "<send> must not specify namelist together with a <content> child" },
+        send_param_and_content: ->(_) { "<send> must not specify a <param> child together with a <content> child" },
+        cancel_sendid_and_sendidexpr: ->(_) { "<cancel> must not specify both sendid and sendidexpr" },
+        cancel_no_sendid: ->(_) { "<cancel> must specify exactly one of sendid or sendidexpr" },
+        duplicate_attribute: ->(d) { "duplicate attribute #{q.call(d[:attribute])} on <#{d[:element]}>" }
+      }.freeze
+
+      # Every error reason's message.
+      ERROR = STATES.merge(DATA, EXECUTABLE).freeze
+
+      # Every warning reason's message.
+      WARNING = {
+        finalize_forbidden_content: ->(d) { "<#{d[:element]}> must not occur inside <finalize>" }
+      }.freeze
+    end
+  end
+end

data/lib/statifier/validator/states.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The checks of ids, targets and initial references. Each check takes
+    # the chart and the {Context} and answers its errors.
+    #
+    # @api private
+    module States
+      module_function
+
+      # Every id-typed attribute, a state's and a `<data>`'s, shares one
+      # uniqueness set. An empty id is `:empty_id` and joins no set; the
+      # first occurrence of an id in document order is canonical and each
+      # later one is `:duplicate_id`, at its own span.
+      def ids(document, _context)
+        entries = in_order(data_ids(document.datamodel_element) + state_ids(document.states))
+        empty, named = entries.reject { _1.first.nil? }.partition { _1.first == "" }
+        empty.map { Findings.error(:empty_id, _1.last) } + duplicates(named)
+      end
+
+      # Each later entry of an id, the first being canonical.
+      def duplicates(entries)
+        entries.group_by(&:first).flat_map do |id, (_first, *later)|
+          later.map { Findings.error(:duplicate_id, _1.last, id:) }
+        end
+      end
+
+      # Id entries sorted by where their span starts, found order kept.
+      def in_order(entries)
+        entries.each_with_index.sort_by { |(_, location), index| [location.start_offset, index] }.map(&:first)
+      end
+
+      # The id entries of states, their datamodels' `<data>` included, in
+      # tree order.
+      def state_ids(states)
+        states.flat_map do |state|
+          [[state.id, span(state, :id)], *data_ids(state.datamodel_element), *state_ids(state.states)]
+        end
+      end
+
+      # The id entries of a `<datamodel>`'s `<data>`.
+      def data_ids(datamodel) = datamodel.nil? ? [] : datamodel.data.map { [_1.id, span(_1, :id)] }
+
+      # Every transition's targets resolve. This check owns existence: the
+      # checks after it skip an unresolved id rather than report it again.
+      def targets(_document, context)
+        context.transitions.flat_map do |transition, _owner|
+          location = span(transition, :target)
+          transition.target.reject { context.by_id.key?(_1) }.map do |id|
+            Findings.error(:unresolved_target, location, id:)
+          end
+        end
+      end
+
+      # Every `initial` reference resolves and lands inside the state it
+      # initializes; a state with nothing to default into is reported once
+      # and nothing else is checked on it. The chart's own `initial` need
+      # only resolve.
+      def initial_targets(document, context)
+        location = span(document, :initial)
+        root = document.initial.reject { context.by_id.key?(_1) }.map do |id|
+          Findings.error(:unresolved_initial, location, id:)
+        end
+        context.states.flat_map { initial_state(_1, context) } + root
+      end
+
+      # The initial-target errors of one state.
+      def initial_state(state, context)
+        return [] if state.initial.empty? && state.initial_element.nil?
+
+        return [atomic(state)] if state.states.empty? || %i[parallel final history].include?(state.kind)
+
+        initial_attribute(state, context) + initial_element_targets(state, context)
+      end
+
+      # The `:initial_on_atomic_state` error of a state with nothing to
+      # default into: at its `initial`, else at its `<initial>`.
+      def atomic(state)
+        location = state.initial.empty? ? state.initial_element.location : span(state, :initial)
+        Findings.error(:initial_on_atomic_state, location, id: state.id)
+      end
+
+      # The ids of a state's `initial` attribute.
+      def initial_attribute(state, context)
+        location = span(state, :initial)
+        state.initial.filter_map do |id|
+          if !context.by_id.key?(id)
+            Findings.error(:unresolved_initial, location, id:)
+          elsif outside?(id, state, context)
+            Findings.error(:initial_not_descendant, location, id:, parent_id: state.id)
+          end
+        end
+      end
+
+      # The resolved targets of a state's `<initial>` that lie outside it.
+      def initial_element_targets(state, context)
+        transitions = state.initial_element&.transitions || Lowering::Reading::EMPTY
+        transitions.flat_map { outside_targets(_1, state, context) }
+      end
+
+      # The `:initial_not_descendant` errors of a transition's resolved
+      # targets outside `parent`.
+      def outside_targets(transition, parent, context)
+        location = span(transition, :target)
+        transition.target.select { context.by_id.key?(_1) && outside?(_1, parent, context) }.map do |id|
+          Findings.error(:initial_not_descendant, location, id:, parent_id: parent.id)
+        end
+      end
+
+      # Whether the state `id` names lies outside `state`, by the tree.
+      def outside?(id, state, context) = !context.inside?(context.by_id.fetch(id), state)
+
+      # A state's `<initial>` element: not beside an `initial` attribute,
+      # and one default transition.
+      def initial_elements(_document, context)
+        context.states.reject { _1.initial_element.nil? }.flat_map do |state|
+          element = state.initial_element
+          owner = { kind: :initial, id: state.id }
+          both_forms(state) + default_transition(owner, element.transitions, element.location)
+        end
+      end
+
+      # The `:initial_attribute_and_element` error of a state with both.
+      def both_forms(state)
+        return [] if state.initial.empty?
+
+        [Findings.error(:initial_attribute_and_element, state.initial_element.location, id: state.id)]
+      end
+
+      # The content model an `<initial>` and a history share: exactly one
+      # transition, with a target, and neither `event` nor `cond`. A wrong
+      # count is reported at the owner.
+      def default_transition(owner, transitions, owner_location)
+        count = transitions.size == 1 ? [] : [transitions.size]
+        count.map { Findings.error(:transition_count, owner_location, owner:, count: _1) } +
+          transitions.flat_map { missing_target(owner, _1) + forbidden(owner, _1) }
+      end
+
+      # The `:transition_missing_target` error of a default transition with
+      # no target.
+      def missing_target(owner, transition)
+        return [] unless transition.target.empty?
+
+        [Findings.error(:transition_missing_target, transition.location, owner:)]
+      end
+
+      # A default transition's written `event` and `cond`: an empty `event`
+      # lowers to an empty list, so only its span says it was written.
+      def forbidden(owner, transition)
+        written = { event: transition.attribute_locations.key?(:event), cond: !transition.cond.nil? }
+        written.select { |_, yes| yes }.keys.map do |attribute|
+          Findings.error(:transition_forbidden_attribute, span(transition, attribute), owner:, attribute:)
+        end
+      end
+
+      # The value span of an attribute when it was written, else the node's.
+      def span(node, key) = node.attribute_locations.fetch(key, node.location)
+    end
+  end
+end