principles 0.0.1

data/lib/principles/models/evidence_lines_since.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "evidence_item"
+require_relative "member_lines"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The lines one evidence item of a prior finding names at the commit the audit that kept the finding was based on,
+    # and now, either nil where they cannot be found: what the next full audit's request says of the item (#858). A
+    # removed pointer needs finding again and a reworded one judging again, so whether it is found now is said apart
+    # from whether it changed (#877).
+    class EvidenceLinesSince
+      # The lines item names in project at since and now, either nil where it cannot be found or read, so one moved or
+      # removed pointer never refuses the request.
+      #: (EvidenceItem, since: String, project: Project) -> EvidenceLinesSince
+      def self.of(item, since:, project:)
+        new(at_base: unless_refused { item.lines_at(project.history, since) },
+            now: unless_refused { item.lines_now(project) })
+      end
+
+      # What the block reads, or nil when it is refused.
+      #: () { () -> Array[String]? } -> Array[String]?
+      def self.unless_refused(&)
+        yield
+      rescue Error
+        nil
+      end
+      private_class_method :unless_refused
+
+      #: (at_base: Array[String]?, now: Array[String]?) -> void
+      def initialize(at_base:, now:)
+        @at_base = at_base
+        @now = now
+        freeze
+      end
+
+      # Whether its text reads otherwise now than at the base commit, true too when it cannot be found then or now, and
+      # whether it is found now.
+      #: () -> Hash[String, bool]
+      def facts = { "changed_since_last_audit" => changed?, "found_now" => !@now.nil? }
+
+      private
+
+      #: () -> bool
+      def changed?
+        at_base = @at_base
+        now = @now
+        return true unless at_base && now
+
+        MemberLines.new(at_baseline: at_base, now: now).changed?
+      end
+    end
+  end
+end

data/lib/principles/models/evidence_replacements.rb

@@ -0,0 +1,99 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "locator"
+require_relative "answer_fields"
+require_relative "answer_place"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The new places a still_holds decision gives a kept finding's evidence items that are no longer found, each
+    # problem_evidence entry naming by replaces the position of the item it replaces (D70). An item still found stays
+    # as the audit raised it, so a decision never rewrites what an audit found (D64); git keeps the old pointer.
+    class EvidenceReplacements
+      # The field an entry names the kept item it replaces by, which the record does not keep.
+      REPLACES = "replaces"
+
+      # kept is the finding's evidence as its record keeps it, in order; entries are the decision's problem_evidence.
+      #: (Array[Hash[String, untyped]], Array[Hash[String, untyped]]) -> void
+      def initialize(kept, entries)
+        @kept = kept
+        @entries = entries
+        freeze
+      end
+
+      # Refuses, through refuse with a reason and a repair, an entry that names no kept item by replaces, names one
+      # twice, or names one locate still finds, and has locate find each new pointer, at place.
+      #: (^(Locator) -> void, String, AnswerPlace, refuse: ^(String, String?) -> void) -> void
+      def check(locate, id, place, refuse:)
+        positions(id, refuse)
+        @entries.each do |entry|
+          index = entry.fetch(REPLACES)
+          next unless found?(locate, @kept.fetch(index))
+
+          refuse.call("evidence item #{index} is still found, so a decision may not replace it",
+                      "Drop that entry from #{id}'s problem_evidence, or raise it again as a new finding to " \
+                      "restate its evidence.")
+        end
+        AnswerFields.new(locate).evidence(pointers, place)
+      end
+
+      # The evidence the record keeps: each kept item, with each one an entry names swapped for its new pointer.
+      #: () -> Array[Hash[String, untyped]]
+      def evidence
+        by_index = @entries.to_h { |entry| [entry.fetch(REPLACES), entry.except(REPLACES)] }
+        @kept.each_with_index.map { |item, index| by_index.fetch(index, item) }
+      end
+
+      # Each swap, as the completed result names it for finding id: the pointer replaced and its new one.
+      #: (String) -> Array[Hash[String, untyped]]
+      def swaps(id)
+        @entries.map do |entry|
+          { "finding_id" => id, "replaced" => @kept.fetch(entry.fetch(REPLACES)), "with" => entry.except(REPLACES) }
+        end
+      end
+
+      private
+
+      # The new pointers, as their record keeps them.
+      #: () -> Array[Hash[String, untyped]]
+      def pointers = @entries.map { |entry| entry.except(REPLACES) }
+
+      # Refuses an entry without replaces, one naming no kept item, and two naming the same one.
+      #: (String, ^(String, String?) -> void) -> void
+      def positions(id, refuse)
+        named = @entries.map { |entry| entry[REPLACES] }
+        unnamed(id, refuse) if named.any?(nil)
+        stray = named.grep_v(0...@kept.size).first
+        if stray
+          refuse.call("replaces #{stray} names no item of its evidence",
+                      "Name by replaces a position in #{id}'s evidence, from 0 to #{@kept.size - 1}.")
+        end
+        twice = named.find { |index| named.count(index) > 1 } or return
+        refuse.call("replaces names evidence item #{twice} twice",
+                    "Give each item of #{id}'s evidence at most one entry in its problem_evidence.")
+      end
+
+      # Refuses entries that do not say which kept item each replaces, since the record keeps the evidence it was
+      # raised with.
+      #: (String, ^(String, String?) -> void) -> void
+      def unnamed(id, refuse)
+        refuse.call("its record keeps the evidence it was raised with, so each problem_evidence entry must name by " \
+                    "replaces the item no longer found that it replaces",
+                    "Give each entry replaces, the position in #{id}'s evidence of an item no longer found, " \
+                    "counting from 0, or drop problem_evidence.")
+      end
+
+      # Whether locate finds item now.
+      #: (^(Locator) -> void, Hash[String, untyped]) -> bool
+      def found?(locate, item)
+        locate.call(Locator.new(item))
+        true
+      rescue Error
+        false
+      end
+    end
+  end
+end

data/lib/principles/models/finding_write_ups.rb

@@ -0,0 +1,108 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "missing_files"
+require_relative "open_finding"
+require_relative "project"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Some open findings, each with its write-up opening where its recorded_at points, as the project's file stands
+    # now (#300).
+    class FindingWriteUps
+      # What to do about a recorded_at that no longer resolves, worded for a write-up rather than a member.
+      REPAIR = "Fix the write-up, or point recorded_at at it again with start-audit --write-ups, without a full audit."
+      # What the repair adds when git detects a rename for the write-up's missing file.
+      RENAMED = " git_detected_rename is git's match for its file, to #{MissingFiles::RENAME_MATCH}".freeze #: String
+
+      # The findings records keep open for the next audit, in project.
+      #: (Project, Array[AuditRecord]) -> FindingWriteUps
+      def self.of(project, records) = new(project, records.flat_map(&:left_open))
+
+      #: (Project, Array[OpenFinding]) -> void
+      def initialize(project, findings)
+        @project = project
+        @findings = findings
+        freeze
+      end
+
+      # Each finding with its write_up_opening, as list-open-findings prints them.
+      #: () -> Array[Hash[String, untyped]]
+      def listed
+        @findings.map { |finding| finding.listed.merge(opening_fields(finding.recorded_at)) }
+      end
+
+      # The findings that are written up somewhere, each with the write-up opening list-open-findings will print for
+      # it, so a pointer that lands on a generic line is seen before the answer is submitted (#411).
+      #: () -> Array[Hash[String, untyped]]
+      def written_up
+        fields = %w[finding_id write_up_opening write_up_opening_reason write_up_opening_error]
+        listed.select { |finding| finding["recorded_at"] }.map { |finding| finding.slice(*fields) }
+      end
+
+      # The findings whose write-up can no longer be found where recorded_at points, each by its principle and
+      # finding_id, which list-open-findings --short names so a session-start hook shows the broken pointer (#694).
+      # It asks git for no rename, which only the full list prints.
+      #: () -> Array[Hash[String, untyped]]
+      def not_found
+        @findings.select { |finding| unresolved?(finding.recorded_at) }
+                 .map { |finding| { "principle" => finding.principle_id, "finding_id" => finding.id } }
+      end
+
+      private
+
+      # pointer's write_up_opening, or null with the reason: not_recorded, empty_region, or unavailable with the
+      # refusal, so one pointer that no longer resolves never refuses the whole list.
+      #: (WriteUpPointer?) -> Hash[String, untyped]
+      def opening_fields(pointer) = pointer ? opening_found(pointer) : none("not_recorded")
+
+      # The write_up_opening pointer leads to, or null with why: empty_region, or unavailable with the refusal.
+      #: (WriteUpPointer) -> Hash[String, untyped]
+      def opening_found(pointer)
+        opening = pointer.opening_in(@project)
+        opening ? { "write_up_opening" => opening } : none("empty_region")
+      rescue Error => e
+        none("unavailable").merge("write_up_opening_error" => unavailable(e.payload, pointer))
+      end
+
+      # Whether a recorded pointer no longer resolves in the project's file now.
+      #: (WriteUpPointer?) -> bool
+      def unresolved?(pointer)
+        return false unless pointer
+
+        pointer.opening_in(@project)
+        false
+      rescue Error
+        true
+      end
+
+      # The refusal that left a write-up unavailable, with any rename git detects for its file when that file is
+      # missing. The agent checks the match before pointing recorded_at there: this tool does not decide the match
+      # is the write-up, as for a member's missing file (#276, #694).
+      #: (Hash[String, untyped], WriteUpPointer) -> Hash[String, untyped]
+      def unavailable(payload, pointer)
+        refused = payload.slice("code", "message")
+        rename = @project.history.rename_of(pointer.path) if refused["code"] == "unreadable_file"
+        return refused.merge("repair" => REPAIR) unless rename
+
+        refused.merge("git_detected_rename" => rename.merge(starting_at_found(pointer.in_file(rename.fetch("to")))),
+                      "repair" => REPAIR + RENAMED)
+      end
+
+      # Whether moved, the pointer with its starting_at in the file git matched, still resolves there: its
+      # starting_at occurs exactly once there, within its heading's section when it names one, as a member's passage
+      # must. A deterministic check of git's match, which the agent then reads as one fact; nothing for a pointer
+      # with no starting_at (#722).
+      #: (WriteUpPointer) -> Hash[String, bool]
+      def starting_at_found(moved)
+        moved.starting_at? ? { "starting_at_found_in_rename" => !unresolved?(moved) } : {}
+      end
+
+      #: (String) -> Hash[String, untyped]
+      def none(reason)
+        { "write_up_opening" => nil, "write_up_opening_reason" => reason }
+      end
+    end
+  end
+end

data/lib/principles/models/findings_left_open.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "open_finding"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Every finding the records leave open, deferred or accepted, as one fact the session-start line states: how
+    # many wait, and which has waited longest (D47).
+    class FindingsLeftOpen
+      # The findings each record leaves open for the next full audit.
+      #: (Array[AuditRecord]) -> FindingsLeftOpen
+      def self.of(records) = new(records.flat_map(&:left_open))
+
+      #: (Array[OpenFinding]) -> void
+      def initialize(findings)
+        @findings = findings
+        freeze
+      end
+
+      # How many are open, how many of them record no waits_on (#736), and the one first raised earliest as it
+      # has waited until now, or nil when none is open. How long it waited runs from first_raised_at, never from when
+      # its waits_on was asked, which a later audit may have given it (D52).
+      #: (Time) -> Hash[String, untyped]?
+      def waiting_at(now)
+        oldest = @findings.min_by(&:first_raised_time) or return nil
+
+        { "count" => @findings.length, "without_waits_on" => @findings.count(&:without_waits_on?),
+          **oldest.waited_at(now) }
+      end
+    end
+  end
+end

data/lib/principles/models/first_raised_claim.rb

@@ -0,0 +1,128 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+require_relative "../error"
+require_relative "audit_records"
+require_relative "open_finding"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A still_holds decision's claim that its finding was first raised earlier than the record says, citing in
+    # raised_in the commit whose audit record left it open then (D53). Whether that record's finding is the same
+    # finding is the agent's judgement. This tool checks only the facts the claim cites, at that one commit: the
+    # record there leaves a finding with the same id deferred or accepted, its audit was made at the claimed time,
+    # and that time is earlier than the one stored. It walks no history.
+    class FirstRaisedClaim
+      FIELDS = %w[first_raised_at raised_in].freeze
+
+      # decision is the agent's decision on finding, the prior finding as its record left it open.
+      #: (Hash[String, untyped], OpenFinding) -> void
+      def initialize(decision, finding)
+        @decision = decision
+        @id = finding.id #: String
+        @stored = finding.first_raised_at #: String?
+        freeze
+      end
+
+      # Refuses the claim unless it is whole, on a still_holds decision, and the record of principle_id that records
+      # reads at its commit bears it out; a decision that claims nothing passes, and needs no records.
+      #: (AuditRecords?, String) -> void
+      def check(records, principle_id)
+        return if @decision.slice(*FIELDS).empty?
+
+        whole
+        records or raise ArgumentError, "a claim on #{@id} is checked only against the audit records"
+        borne_out(*read(records, principle_id))
+        raise not_earlier unless earlier?
+      end
+
+      private
+
+      # Refuses unless version, the record read from path, leaves this finding open from an audit at the claimed time.
+      #: (String, AuditRecord) -> void
+      def borne_out(path, version)
+        open = version.open_findings.find { |finding| finding.fetch("finding_id") == @id } or raise lacking(path)
+        audited_at = open.fetch("audited_at")
+        raise time_differs(path, audited_at) unless audited_at == claimed
+      end
+
+      #: () -> String
+      def claimed = @decision.fetch("first_raised_at")
+
+      #: () -> String
+      def commit = @decision.fetch("raised_in")
+
+      #: () -> void
+      def whole
+        unless @decision["decision"] == "still_holds"
+          invalid("only still_holds may give first_raised_at and raised_in",
+                  "Drop first_raised_at and raised_in from #{@id}'s decision, or decide it still_holds.")
+        end
+        return if FIELDS.all? { |field| @decision.key?(field) }
+
+        invalid("first_raised_at and raised_in go together",
+                "Give both: first_raised_at, the audited_at of the record that first left #{@id} open, and " \
+                "raised_in, the full sha of the commit holding that record; or give neither.")
+      end
+
+      # The record's path and the record as the claimed commit held it, refused when it holds none or cannot be read.
+      #: (AuditRecords, String) -> [String, AuditRecord]
+      def read(records, principle_id)
+        records.at(principle_id, commit) or raise not_found(records, principle_id)
+      rescue Error => e
+        raise unless %w[invalid_audit_record unparseable_audit].include?(e.payload.fetch("code"))
+
+        raise Error.new("raised_in_unreadable", "Prior finding #{@id}: the record at raised_in #{commit} cannot be " \
+                                                "read: #{e.payload.fetch("message")}",
+                        "Cite another commit whose record holds #{@id}, or drop first_raised_at and raised_in.",
+                        fields: e.payload["fields"])
+      end
+
+      #: () -> bool
+      def earlier?
+        Time.iso8601(claimed) < Time.iso8601(@stored.to_s)
+      rescue ArgumentError
+        false
+      end
+
+      #: (AuditRecords, String) -> Error
+      def not_found(records, principle_id)
+        paths = "#{records.file(principle_id)} or #{records.earlier_file(principle_id)}"
+        Error.new("raised_in_not_found", "Prior finding #{@id}: commit #{commit} holds no audit record at #{paths}",
+                  "Set raised_in to the full sha of a commit holding #{paths} that left #{@id} open, as " \
+                  "git log --follow on the record finds it; outside git, drop first_raised_at and raised_in.")
+      end
+
+      #: (String) -> Error
+      def lacking(path)
+        Error.new("raised_in_lacks_finding",
+                  "Prior finding #{@id}: #{path} at #{commit} leaves no finding #{@id} deferred or accepted",
+                  "Set raised_in to a commit whose record leaves #{@id} deferred or accepted, or drop " \
+                  "first_raised_at and raised_in.")
+      end
+
+      #: (String, String) -> Error
+      def time_differs(path, audited_at)
+        Error.new("raised_in_time_differs",
+                  "Prior finding #{@id}: #{path} at #{commit} was audited at #{audited_at}, not #{claimed}",
+                  "Set first_raised_at to #{audited_at}, that record's audited_at, or cite the commit of the record " \
+                  "audited at #{claimed}.")
+      end
+
+      #: () -> Error
+      def not_earlier
+        Error.new("first_raised_not_earlier",
+                  "Prior finding #{@id}: #{claimed} is not earlier than its first_raised_at, #{@stored}",
+                  "Drop first_raised_at and raised_in from #{@id}'s decision; the record keeps #{@stored}, and only " \
+                  "an earlier record replaces it.")
+      end
+
+      #: (String, String) -> bot
+      def invalid(why, repair)
+        raise Error.new("invalid_decision", "Prior finding #{@id}: #{why}", repair)
+      end
+    end
+  end
+end

data/lib/principles/models/frontmatter_fields.rb

@@ -0,0 +1,128 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "json_path_query"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The YAML frontmatter at the head of a Markdown file, read as lines and never parsed as YAML, since a
+    # YAML parser over untrusted bytes is attack surface. A field is a top-level `key:` line and the indented,
+    # list or blank lines after it; its member is those lines exactly. This tool never interprets a value, so it
+    # refuses only what would make a field's lines differ from what the harness reads: an anchor, an alias or
+    # a tag, or a line it cannot place in a field.
+    class FrontmatterFields
+      # A top-level field's opening line, and its name.
+      FIELD = /\A([A-Za-z0-9_-]+):(?:\s|\z)/ #: Regexp
+
+      # A node that starts with an anchor, an alias or a tag, after a key or a list dash.
+      INDIRECT = /\A\s*(?:-\s+|[^\s:#][^:#]*:\s+)[&*!]/ #: Regexp
+
+      # A value that is a flow collection, after a key or a list dash, such as [a, b] or {a: b}.
+      FLOW = /\A\s*(?:-\s+|[^\s:#][^:#]*:\s+)([\[{].*)/ #: Regexp
+
+      # A quoted scalar, whose text is never a node of its own.
+      QUOTED = /"(?:[^"\\]|\\.)*"|'(?:[^']|'')*'/ #: Regexp
+
+      # A node inside a flow collection that starts with an anchor, an alias or a tag.
+      FLOW_INDIRECT = /[\[{,:]\s*[&*!]/ #: Regexp
+
+      #: (path: String, lines: Array[String]) -> void
+      def initialize(path:, lines:)
+        @path = path
+        @lines = lines
+        freeze
+      end
+
+      # The line range of the field query names: from its key line through its last non-blank line.
+      #: (String) -> [Integer, Integer]
+      def field(query)
+        name = JsonPathQuery.new(query).top_level_name or refuse_query(query)
+        found = fields.select { |field_name, _| field_name == name }
+        if found.empty?
+          raise Error.new("field_not_found", "#{@path} has no frontmatter field #{name.inspect}",
+                          "Name a top-level field its frontmatter has, such as $.description.", @path)
+        end
+        refuse_duplicate(name) if found.length > 1
+
+        found.fetch(0).last
+      end
+
+      # The lines of the field query names, as written, or nil when the frontmatter has no such field; every
+      # other refusal still refuses.
+      #: (String) -> Array[String]?
+      def field_lines(query)
+        first, last = field(query)
+        (first...last).map { |index| @lines.fetch(index) }
+      rescue Error => e
+        raise unless e.payload.fetch("code") == "field_not_found"
+      end
+
+      private
+
+      # Each top-level field's name and line range, in order; refused on a line this tool would misread.
+      #: () -> Array[[String, [Integer, Integer]]]
+      def fields
+        closing = closing_line or return []
+        starts = (1...closing).select { |i| opens_field?(i) }
+        starts.each_with_index.map do |start, n|
+          [@lines.fetch(start)[FIELD, 1].to_s, [start, last_filled(start, (starts[n + 1] || closing) - 1) + 1]]
+        end
+      end
+
+      # The index of the --- that closes the frontmatter, or nil when the text opens with none.
+      #: () -> Integer?
+      def closing_line
+        return nil unless @lines.first&.chomp == "---"
+
+        (1...@lines.length).find { |i| @lines.fetch(i).chomp == "---" }
+      end
+
+      # The last line from start to last that is not blank, so trailing blank lines stay out of a field.
+      #: (Integer, Integer) -> Integer
+      def last_filled(start, last)
+        last -= 1 while last > start && @lines.fetch(last).strip.empty?
+        last
+      end
+
+      # Whether line i opens a field, after refusing what this tool cannot read as lines.
+      #: (Integer) -> bool
+      def opens_field?(index)
+        line = @lines.fetch(index)
+        refuse_line(index, "an anchor, alias or tag") if line.match?(INDIRECT) || indirect_in_flow?(line)
+        return true if line.match?(FIELD)
+        return false if line.strip.empty? || line.start_with?(" ", "\t", "-", "#")
+
+        refuse_line(index, "a line that is not a top-level field")
+      end
+
+      # Whether line's value is a flow collection holding an anchor, alias or tag outside its quoted text.
+      #: (String) -> bool
+      def indirect_in_flow?(line)
+        flow = line[FLOW, 1] or return false
+        flow.gsub(QUOTED, "\"\"").match?(FLOW_INDIRECT)
+      end
+
+      #: (Integer, String) -> bot
+      def refuse_line(index, what)
+        raise Error.new("unsupported_frontmatter", "#{@path} line #{index + 1} holds #{what}",
+                        "Frontmatter is read as plain fields. Write the value out in full, or map the " \
+                        "file with --starting-at TEXT instead.", @path).including("line" => index + 1)
+      end
+
+      #: (String) -> bot
+      def refuse_query(query)
+        raise Error.new("unsupported_query", "#{query.inspect} is not a supported frontmatter query",
+                        "Name one top-level field, such as $.description, or $['allowed-tools'] for a name " \
+                        "with a hyphen.", @path)
+      end
+
+      #: (String) -> bot
+      def refuse_duplicate(name)
+        raise Error.new("duplicate_frontmatter_key", "#{@path} names #{name.inspect} more than once",
+                        "Keep one #{name} field; the harness may read either.", @path)
+      end
+    end
+  end
+end

data/lib/principles/models/hook_commands.rb

@@ -0,0 +1,100 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/project_files"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The command hooks a project's settings files declare, and which of them name a file. A command names a file
+    # when its command or one of its args gives the file's path from the project root, bare or after the project
+    # placeholder, with nothing else joined to either end. That is a fact about the string: this tool does not run
+    # the command, and says nothing of whether its output reaches the agent's context. It reads only command
+    # handlers, not prompt or agent ones, as the hooks documentation shapes them: event, matcher group, handler.
+    class HookCommands
+      # The project placeholder before a path, bare, braced or quoted, which stands for the project root.
+      PROJECT_DIR = %r{"?\$\{?CLAUDE_PROJECT_DIR\}?"?/} #: Regexp
+
+      # The project settings files whose hooks Claude Code runs in this checkout: the committed one and the local.
+      SETTINGS = %w[.claude/settings.json .claude/settings.local.json].freeze #: Array[String]
+
+      # The command hooks in each project settings file present, or the code each unreadable one was refused with.
+      #: (Data::ProjectFiles) -> HookCommands
+      def self.read(files)
+        new(SETTINGS.select { |path| files.file?(path) }.to_h do |path|
+          [path, files.parse_json(files.read_text(path), path)]
+        rescue Error => e
+          [path, e.payload.fetch("code")]
+        end)
+      end
+
+      # settings maps each settings file's path to its parsed JSON, or to the code this tool refused it with.
+      #: (Hash[String, untyped]) -> void
+      def initialize(settings)
+        @settings = settings
+        freeze
+      end
+
+      # Each command handler that names the file at path, with the settings file and event it is in, and its
+      # matcher, command and args as written.
+      #: (String) -> Array[Hash[String, untyped]]
+      def naming(path)
+        named = %r{(?:\A|[\s"'=])(?:\./)?#{Regexp.escape(path)}(?=\z|[\s"';|&)])}
+        handlers.select do |entry|
+          [entry["command"], *entry["args"]].any? { |text| text.to_s.gsub(PROJECT_DIR, "").match?(named) }
+        end
+      end
+
+      # Each settings file this tool could not read, or whose hooks are not the documented shape, with why.
+      #: () -> Array[Hash[String, String]]
+      def not_read
+        @settings.filter_map do |path, parsed|
+          code = parsed.is_a?(String) ? parsed : ("unexpected_hooks_shape" unless events(parsed))
+          { "path" => path, "code" => code } if code
+        end
+      end
+
+      private
+
+      # Every command handler in every readable settings file, in file and declaration order.
+      #: () -> Array[Hash[String, untyped]]
+      def handlers
+        @settings.flat_map do |path, parsed|
+          (events(parsed) || []).flat_map do |event, groups|
+            groups.flat_map { |group| commands(group).map { |hook| entry(path, event, group, hook) } }
+          end
+        end
+      end
+
+      #: (String, String, Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def entry(path, event, group, hook)
+        { "settings" => path, "event" => event, "matcher" => group["matcher"], "command" => hook["command"],
+          "args" => hook["args"] }.compact
+      end
+
+      # The settings' hooks by event, or nil when they are not the documented shape; none when there are none.
+      #: (untyped) -> Hash[String, Array[Hash[String, untyped]]]?
+      def events(parsed)
+        return nil unless parsed.is_a?(Hash)
+
+        hooks = parsed.fetch("hooks", {})
+        return nil unless hooks.is_a?(Hash) && hooks.values.all? { |groups| groups?(groups) }
+
+        hooks
+      end
+
+      #: (untyped) -> bool
+      def groups?(groups)
+        return false unless groups.is_a?(Array)
+
+        groups.all? { |group| group.is_a?(Hash) && group.fetch("hooks", []).is_a?(Array) }
+      end
+
+      #: (Hash[String, untyped]) -> Array[Hash[String, untyped]]
+      def commands(group)
+        group.fetch("hooks", []).select { |hook| hook.is_a?(Hash) && hook["type"] == "command" }
+      end
+    end
+  end
+end