hecks 5.0.0 → 6.0.0

data/lib/hecks/grammar.rb

@@ -4,61 +4,65 @@ require "json"
 # requires this file back, so the require is acyclic.
 require_relative "../hecks"
 require_relative "grammar/operators"
+require_relative "grammar/dialects"
+require_relative "grammar/translation_ledger"
 
 module Hecks
   # The sublanguage grammar domains (grammar/*.bluebook) and the one boot path
   # for reading them as data, replayed through the expression admission ledger.
   #
   # Booted on call, never at require: the Prism adapter normalises predicates
-  # while a bluebook loads, so the expression machinery cannot boot its own chapter.
+  # while a bluebook loads, so the expression machinery cannot boot its own bluebook.
   module Grammar
     DIR    = File.expand_path("grammar", __dir__)
     LEDGER = File.join(DIR, "expression_operators.json")
 
-    # The ports and adapters a chapter needs loaded before its own bluebook, relative to the
+    # The ports and adapters a bluebook needs loaded before its own bluebook, relative to the
     # repository root.
-    CHAPTER_PREREQUISITES = %w[lib/hecks/ports/persistence.port lib/hecks/ports/extraction.port
-                               lib/hecks/adapters/driven/memory.adapter
-                               lib/hecks/adapters/driven/prism.adapter].freeze
+    BLUEBOOK_PREREQUISITES = %w[lib/hecks/ports/persistence.port lib/hecks/ports/extraction.port
+                                lib/hecks/adapters/driven/memory.adapter
+                                lib/hecks/adapters/driven/prism.adapter].freeze
 
     extend Operators
+    extend Dialects
+    extend TranslationLedger
 
     module_function
 
-    # Boots the expression chapter and replays the admission ledger through
+    # Boots the expression bluebook and replays the admission ledger through
     # its real commands; a refused step raises.
     #
     # @return [Runtime::Dispatcher] the dispatcher bound to the booted, replayed
-    #   expression chapter
-    # @raise [Runtime::WiringError] if a ledger step is refused by the chapter's
+    #   expression bluebook
+    # @raise [Runtime::WiringError] if a ledger step is refused by the bluebook's
     #   own domain rules
     def expression
       registry = Runtime::Registry.new
-      load_chapter(registry, File.join(DIR, "expression.bluebook"))
+      load_bluebook(registry, File.join(DIR, "expression.bluebook"))
       dispatcher = Runtime::Dispatcher.new(registry)
       JSON.parse(File.read(LEDGER)).fetch("steps").each { |step| replay_step(dispatcher, step) }
       dispatcher
     end
 
-    # Loads a chapter's bluebook into a registry, after the ports and adapters it needs.
+    # Loads a bluebook's bluebook into a registry, after the ports and adapters it needs.
     #
-    # @param registry [Runtime::Registry] the registry the chapter loads into
-    # @param chapter [String] the path of the chapter's `.bluebook`
+    # @param registry [Runtime::Registry] the registry the bluebook loads into
+    # @param bluebook [String] the path of the bluebook's `.bluebook`
     # @return [void]
-    def load_chapter(registry, chapter)
+    def load_bluebook(registry, declaration)
       root = File.expand_path("../..", __dir__)
       Hecks.with_registry(registry) do
-        CHAPTER_PREREQUISITES.each { |file| Kernel.load(File.join(root, file)) }
-        Kernel.load(chapter)
+        BLUEBOOK_PREREQUISITES.each { |file| Kernel.load(File.join(root, file)) }
+        Kernel.load(declaration)
       end
     end
 
     # Dispatches one admission-ledger step.
     #
-    # @param dispatcher [Runtime::Dispatcher] the dispatcher bound to the expression chapter
+    # @param dispatcher [Runtime::Dispatcher] the dispatcher bound to the expression bluebook
     # @param step [Hash] a ledger step, with `"verb"` and `"args"`
     # @return [void]
-    # @raise [Runtime::WiringError] if the chapter's own domain rules refuse the step
+    # @raise [Runtime::WiringError] if the bluebook's own domain rules refuse the step
     def replay_step(dispatcher, step)
       dispatcher.dispatch_flat(step.fetch("verb"), symbolize(step.fetch("args")))
     rescue *Runtime::DOMAIN_REFUSALS => e
@@ -66,10 +70,10 @@ module Hecks
             "the admission ledger refused at #{step["verb"]} #{step["args"]} — #{e.message}"
     end
 
-    # Reads every admitted operator from the ledger's replayed chapter.
+    # Reads every admitted operator from the ledger's replayed bluebook.
     #
     # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
-    #   expression chapter; defaults to booting and replaying a fresh one
+    #   expression bluebook; defaults to booting and replaying a fresh one
     # @return [Array<Hash>] one Hash per admitted operator, with `:symbol`,
     #   `:category`, `:precedence`, `:arity`, and `:renderings` (an Array of
     #   `{target:, form:}` Hashes)
@@ -86,10 +90,10 @@ module Hecks
     end
 
     # Reads every admitted normalisation rule from the ledger's replayed
-    # chapter, in position order.
+    # bluebook, in position order.
     #
     # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
-    #   expression chapter; defaults to booting and replaying a fresh one
+    #   expression bluebook; defaults to booting and replaying a fresh one
     # @return [Array<Hash>] one Hash per admitted rule, with `:strategy`,
     #   `:source_token`, `:replacement`, `:boundary`, and `:position`
     def admitted_normalisations(dispatcher = expression)
@@ -107,11 +111,11 @@ module Hecks
         position: rule[:position].value }
     end
 
-    # Reads every record of one aggregate from the expression chapter's own
+    # Reads every record of one aggregate from the expression bluebook's own
     # repository.
     #
     # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
-    #   expression chapter
+    #   expression bluebook
     # @param aggregate_name [String] the aggregate's declared name, such as
     #   `"Operator"`
     # @return [Array<Runtime::Instance>] every stored instance of the aggregate

data/lib/hecks/hecks/adapters/claude_agents.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/claude_agents"
+
+Hecks.adapter "ClaudeAgents" do
+  port "Agents"
+end

data/lib/hecks/hecks/adapters/claude_agents.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "shell"
+require "time"
+require_relative "console_capture"
+require_relative "claude_transcript"
+
+module Hecks
+  module Adapters
+    # The `Agents` port's adapter for `AgentRun`: finds the directory a session will work in, starts
+    # a background Claude session there with the `claude` command, and reports the state a started
+    # session says it is in.
+    #
+    # It decides nothing. Whether a brief is enough, whether an agent name is acceptable and which
+    # states mean a session has ended are the bluebook's; this only looks, starts and reads. The
+    # command is an argument list, never a string for a shell, and a `--` keeps a brief from being
+    # taken for a flag.
+    class ClaudeAgents
+      # The command that starts and lists sessions.
+      COMMAND = "claude"
+
+      # A background start prints `backgrounded · <id>` first, then how to attach to the session.
+      SESSION_ID = /\Abackgrounded\W+([0-9A-Za-z][0-9A-Za-z_-]{5,})/
+
+      # Keeps the command to run, so a spec can point it at a stand-in.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `command:` the program that starts sessions (default `claude`)
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @command = settings[:command] || COMMAND
+        @shell = Shell.new
+        @transcript = ClaudeTranscript.new(**settings.slice(:projects))
+      end
+
+      # Says the directory a session would work in is there.
+      #
+      # @param held [Hash] the `AgentRun` record: `repo`
+      # @return [Hash{Symbol => Hash}] `report:` that the directory is there
+      # @raise [ConsoleCapture::Failure] when it is not a directory
+      def locate(**held)
+        repo = plain(held[:repo])
+        raise ConsoleCapture::Failure, "#{repo} is not a directory" unless File.directory?(repo.to_s)
+
+        { report: { value: "#{repo} is a directory" } }
+      end
+
+      # Starts a background session in the directory, with the brief as its first prompt.
+      #
+      # @param held [Hash] the `AgentRun` record: `repo`, `brief`, and `agent` when one is named
+      # @return [Hash{Symbol => Hash}] `session:` the id the session is known by
+      # @raise [ConsoleCapture::Failure] when the command fails or names no session
+      def start(**held)
+        result = @shell.capture(*start_arguments(held), chdir: plain(held[:repo]))
+        raise ConsoleCapture::Failure, "#{@command} did not start a session: #{result.err.strip}" unless result.ok?
+
+        id = result.out[SESSION_ID, 1]
+        raise ConsoleCapture::Failure, "#{@command} named no session: #{result.out.strip}" unless id
+
+        { session: { value: id } }
+      end
+
+      # Reads the state a started session reports.
+      #
+      # @param held [Hash] the `AgentRun` record: `session`
+      # @return [Hash{Symbol => String}] `condition:` the state the session reports, as a bare
+      #   string
+      # @raise [ConsoleCapture::Failure] when the sessions cannot be listed or this one is not among
+      #   them
+      def examine(**held)
+        { condition: listed(plain(held[:session]))["state"].to_s }
+      end
+
+      # Says whether a person replied in a session after its brief.
+      #
+      # @param held [Hash] the `AgentRun` record: `session`
+      # @return [Hash{Symbol => Object}] `taken_over:` true when a person replied or the transcript
+      #   cannot be read, and `note:` that fact in words
+      # @raise [ConsoleCapture::Failure] when the sessions cannot be listed or this one is not among
+      #   them
+      def review(**held)
+        full = listed(plain(held[:session]))["sessionId"]
+        taken = @transcript.taken_over?(full)
+        { taken_over: taken, note: taken ? "a person replied, or the transcript cannot be read" : "nobody replied" }
+      end
+
+      # Removes a session with `claude rm`.
+      #
+      # @param held [Hash] the `AgentRun` record: `session`
+      # @return [Hash{Symbol => Object}] `removed_at:` when it was removed, as an ISO 8601 string
+      # @raise [ConsoleCapture::Failure] when the command refuses
+      def remove(**held)
+        id = plain(held[:session])
+        result = @shell.capture(@command, "rm", id)
+        raise ConsoleCapture::Failure, "#{@command} rm #{id} refused: #{result.err.strip}" unless result.ok?
+
+        { removed_at: { value: Time.now.utc.iso8601 } }
+      end
+
+      private
+
+      def listed(id)
+        listing = @shell.capture(@command, "agents", "--json", "--all")
+        raise ConsoleCapture::Failure, "#{@command} could not list sessions: #{listing.err.strip}" unless listing.ok?
+
+        found = JSON.parse(listing.out).find { |entry| [entry["id"], entry["sessionId"]].include?(id) }
+        found || raise(ConsoleCapture::Failure, "no session #{id} is listed")
+      end
+
+      def start_arguments(held)
+        agent = plain(held[:agent])
+        [@command, *(agent ? ["--agent", agent] : []), "--bg", "--", plain(held[:brief])]
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/claude_transcript.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    # Reads a background session's transcript file and says whether a person spoke in it after the
+    # brief.
+    #
+    # It reports a fact and judges nothing: `AgentRun` decides what a taken-over session means. When
+    # the transcript cannot be found or read the answer is "taken over", because the caller removes
+    # a session only on a clear "no".
+    class ClaudeTranscript
+      # The directory, under the home directory, the transcripts are kept in, one per project.
+      PROJECTS = File.join(".claude", "projects")
+
+      # Text a session writes into its own transcript as a user entry without a person typing it.
+      AUTOMATIC_TEXT = /\A\s*<(task-notification|system-reminder|command-(name|message)|local-command-|bash-)/
+
+      # @param projects [String] the directory holding the per-project transcript folders
+      def initialize(projects: File.join(Dir.home, PROJECTS))
+        @projects = projects
+      end
+
+      # @param session_id [String] the full session id, which names the transcript file
+      # @return [Boolean] true when a person replied after the brief, or when this cannot be told
+      def taken_over?(session_id)
+        path = Dir.glob(File.join(@projects, "*", "#{session_id}.jsonl")).first
+        return true unless path && !session_id.to_s.empty?
+
+        human_messages(path).length > 1
+      rescue SystemCallError, JSON::ParserError
+        true
+      end
+
+      private
+
+      # The first of these is the brief; any later one is a person.
+      def human_messages(path)
+        File.foreach(path).map { |line| JSON.parse(line) }.select { |entry| human?(entry) }
+      end
+
+      # A user entry is a person's unless something marks it automatic; an entry that cannot be
+      # classified counts as a person.
+      def human?(entry)
+        return false unless entry["type"] == "user"
+        return false if automatic_flag?(entry)
+
+        person_origin?(entry["origin"]) && person_content?(entry.dig("message", "content"))
+      end
+
+      def automatic_flag?(entry)
+        entry["isMeta"] == true || entry["isSidechain"] == true || entry.key?("toolUseResult")
+      end
+
+      # An entry with no origin is judged by its content; one with an origin is a person only if
+      # it says so.
+      def person_origin?(origin)
+        origin.nil? || (origin.is_a?(Hash) && origin["kind"] == "human")
+      end
+
+      def person_content?(content)
+        case content
+        when String then !content.match?(AUTOMATIC_TEXT)
+        when Array then content.none? { |part| part.is_a?(Hash) && part["type"] == "tool_result" }
+        else true
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/cache_clearing.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../../../cache_dir"
+require_relative "../../../adapters/driving/usage_cache"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # Empties the on-disk caches, which is how a cache is ruled out as the cause of a surprise.
+      #
+      # Only the user's cache directories go; the tables a packaged gem ships are not under
+      # `CacheDir` and are never touched.
+      module CacheClearing
+        # The `Hecks::CacheDir` subdirectories it empties.
+        DIRECTORIES = %w[hecks_syntax_boot_cache hecks_verdict_cache].freeze
+
+        module_function
+
+        # @return [String] which caches were emptied
+        def clear
+          cleared = DIRECTORIES.select do |name|
+            path = Hecks::CacheDir.path(name)
+            File.directory?(path) && FileUtils.rm_rf(path)
+          end
+          cleared << "usage" if Hecks::Adapters::Driving::UsageCache.clear
+          cleared.empty? ? "no cache to clear" : "cleared #{cleared.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/cargo_tests.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # Runs `cargo test` for the crates whose fuzzers take their seed counts from the
+      # environment, so a person gives a count as an argument and the fuzzer reads the variable
+      # it always has.
+      module CargoTests
+        # Where each crate's tests run, relative to the checkout's `rust/`, the `cargo test`
+        # words that select them, and the variables their fuzzers read for a seed count and a
+        # first seed.
+        TARGETS = {
+          "host"   => { dir: "host", words: [], seeds: "HOST_FUZZ_SEEDS", first: nil },
+          "parser" => { dir: "parser", words: [], seeds: "HECKS_PARSE_FUZZ_ITERATIONS", first: "HECKS_PARSE_FUZZ_SEED" },
+          "json"   => { dir: ".", words: %w[--test json_parse_fuzz], seeds: "JSON_FUZZ_SEEDS", first: nil }
+        }.freeze
+
+        module_function
+
+        # Runs `cargo test` for one crate with the seed counts named.
+        #
+        # @param args [Hash] `crate`, and `seeds` and `seed_start` when named
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the cargo child
+        # @return [String] what cargo printed
+        # @raise [ConsoleCapture::Failure] when a test fails or cargo is not installed
+        def run(args, tree, shell)
+          target = TARGETS.fetch(args[:crate])
+          env = fuzz_env(target, args)
+          result = shell.capture("cargo", "test", *target[:words], env: env, chdir: tree.path("rust/#{target[:dir]}"))
+          raise ConsoleCapture::Failure, printed(result) unless result.ok?
+
+          printed(result)
+        end
+
+        # @return [Hash{String => String}] only the fuzz variables the run named and the crate reads
+        def fuzz_env(target, args)
+          env = { target[:seeds] => args[:seeds]&.to_s }
+          env[target[:first]] = args[:seed_start]&.to_s if target[:first]
+          env.compact
+        end
+
+        def printed(result) = "#{result.out}#{result.err}".strip
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/composing.rb

@@ -25,7 +25,8 @@ module Hecks
         # Opens the editor.
         #
         # @param operation [String] `compose`
-        # @param held [Hash] the `CorpusRun` record's fields: `port`, `domains` (the directory)
+        # @param held [Hash] the `CorpusRun` record's fields: `port`, `domains` (the directory) and
+        #   `agent` (`claude`, or `fake` for a scripted assistant)
         # @param tree [Tree] the working tree, already known to be a hecks checkout
         # @param shell [#capture, nil] unused
         # @return [String] a note that the server stopped
@@ -37,7 +38,7 @@ module Hecks
           port = fields[:port] || DEFAULT_PORT
           warn "composer over #{workspace} on http://#{HOST}:#{port}/composer - no authentication, " \
                "no CSRF protection, no caller identity; do not expose beyond localhost"
-          app = Composer::Web.app(workspace: workspace)
+          app = Composer::Web.app(workspace: workspace, agents: Composer::Workbench.agents_named(fields[:agent]))
           (CorpusTasks.web_server || method(:serve)).call(app: app, port: port, host: HOST)
           "composed on port #{port}, now stopped"
         end

data/lib/hecks/hecks/adapters/codebase/conformance.rb

@@ -4,6 +4,7 @@ require_relative "tree"
 require_relative "ruby_child"
 require "hecks/engine_agreement"
 require "hecks/doc/reference"
+require "hecks/shape_ledger"
 
 module Hecks
   module Adapters
@@ -17,7 +18,7 @@ module Hecks
       # script only reports, and with it the script rewrites the committed matrix and its fixtures.
       module Conformance
         # Every operation this family carries out.
-        OPERATIONS = %w[check_engine_agreement measure_doc_coverage argument_gate_matrix].freeze
+        OPERATIONS = %w[check_engine_agreement measure_doc_coverage check_shape_ledger argument_gate_matrix].freeze
 
         module_function
 
@@ -32,6 +33,7 @@ module Hecks
           case operation
           when "check_engine_agreement" then engine_agreement(tree)
           when "measure_doc_coverage" then doc_coverage(tree)
+          when "check_shape_ledger" then shape_ledger(held, tree)
           else gate_matrix(held, tree)
           end
         end
@@ -56,6 +58,20 @@ module Hecks
           report
         end
 
+        # @param held [Hash] the record's fields; `confirm` rewrites the ledger, and `additive`
+        #   with it writes the empty edge for a shape that moved with none
+        # @param tree [Tree] the checkout
+        # @return [String] the clean verdict, or what was written
+        # @raise [ConsoleCapture::Failure] with each bluebook whose shape moved without an edge
+        def shape_ledger(held, tree)
+          ShapeLedger.check(tree.path("lib/hecks/hecks"), confirm: on?(held[:confirm]), additive: on?(held[:additive]))
+        rescue ShapeLedger::Failure => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @return [Boolean] whether a switch field is true, whether given bare or as `{ value: }`
+        def on?(field) = (field.is_a?(Hash) ? field[:value] : field) == true
+
         # @param held [Hash] the record's fields; `confirm` makes the script write
         # @param tree [Tree] the checkout
         # @return [String] what the script printed: the rows kept and dropped, and what it wrote

data/lib/hecks/hecks/adapters/codebase/corpus_tasks.rb

@@ -209,7 +209,7 @@ module Hecks
 
         # @param list [String, nil] a comma-separated list
         # @return [Array<String>] its items
-        def words(list) = list.to_s.split(",").map(&:strip).reject(&:empty?)
+        def words(list) = Text.comma_list(list)
       end
     end
   end

data/lib/hecks/hecks/adapters/codebase/declarations.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "search"
+require "hecks/composer/outline"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What `Reading` knows about where things are declared: the `kind "Name"` lines of every
+      # declaring file with the extent of each block, kept per checkout and rebuilt only when a
+      # declaring file's size or modification time moves.
+      #
+      # The scan reads the text alone, as the Composer outline does, so it works on a file that
+      # does not parse. It also reads the definitions of a Ruby file and the headings of a
+      # Markdown file, for `Outline`, which are scanned on demand and never kept.
+      module Declarations
+        # What a bluebook-family file declares: the constructs the Composer outline jumps to, and
+        # the ones it leaves out.
+        KINDS = (Composer::Outline::KINDS + %w[read_model lifecycle port adapter]).freeze
+
+        # The files whose declarations are indexed.
+        DECLARING = "**/*.{bluebook,hecksagon,behaviors,world,adapter,port}"
+
+        # A declaration line: the keyword, then its name between quotes.
+        DECLARATION = /\A(?<indent>\s*)(?<kind>#{KINDS.join("|")})\s+"(?<name>[^"]+)"/
+
+        # A Ruby definition line.
+        DEFINITION = %r{\A(?<indent>\s*)(?<kind>class|module|def)\s+(?<name>[\w:.?!=<>\[\]+*/-]+)}
+
+        # A heading of a Markdown file.
+        HEADING = /\A(?<hashes>\#{1,6})\s+(?<name>.+)/
+
+        # A line that opens a block closed by a later `end`.
+        OPENING = /\bdo\b(\s*\|[^|]*\|)?\s*\z|\A\s*(class|module|def)\s(?!.*\bend\b\s*\z)/
+
+        # A Ruby method written on one line: `def name(args) = body`.
+        ENDLESS = /\A\s*def\s+[^\s(]+(\(.*\))?\s=\s/
+
+        # One declaration of the index.
+        Entry = Struct.new(:file, :from, :to, :kind, :name, keyword_init: true) do
+          def range = "#{file}:#{from}-#{to}"
+          def label = KINDS.include?(kind) ? "#{kind} #{name.inspect}" : "#{kind} #{name}"
+        end
+
+        @kept = {}
+
+        class << self
+          # @return [Hash{String => Hash}] per checkout root, the scan and the stamp it was built
+          #   from
+          attr_reader :kept
+        end
+
+        module_function
+
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param paths [String, nil] files or directories, comma separated; all when nil
+        # @return [Array<Entry>] every declaration of those paths, from the kept scan
+        def entries(tree, paths = nil)
+          all = scanned(tree)
+          paths ? within(all, paths) : all
+        end
+
+        # @return [Array<Entry>] every declaration of the checkout, rescanned only when a declaring
+        #   file's size or modification time differs from the kept scan's
+        def scanned(tree)
+          files = declaring_files(tree)
+          stamp = stamped(tree, files)
+          held = Declarations.kept[tree.root]
+          return held[:all] if held && held[:stamp] == stamp
+
+          Declarations.kept[tree.root] = { stamp: stamp, all: build(tree, files) }
+          Declarations.kept[tree.root][:all]
+        end
+
+        # @return [Array<String>] the declaring files below the root, sorted
+        def declaring_files(tree)
+          Dir.glob(DECLARING, base: tree.root).select { |file| Search.walkable?(file) }.sort
+        end
+
+        # @return [Array<Array>] each file with the modification time and size it has now
+        def stamped(tree, files) = files.map { |file| [file, *stat(tree, file)] }
+
+        # @param file [String] the file's path, which says what kind of text it holds
+        # @param lines [Array<String>] the file's lines
+        # @return [Array<Entry>] its declarations, definitions or headings
+        def outline(file, lines)
+          return headings(file, lines) if file.end_with?(".md")
+
+          scan(file, lines, file.end_with?(".rb") ? DEFINITION : DECLARATION)
+        end
+
+        # @return [Array<Entry>] the matches of `pattern` in one file's lines
+        def scan(file, lines, pattern = DECLARATION)
+          lines.each_with_index.filter_map do |text, index|
+            found = text.match(pattern) or next
+            Entry.new(file: file, from: index + 1, to: block_end(lines, index, found[:indent].length),
+                      kind: found[:kind], name: found[:name])
+          end
+        end
+
+        # @return [Integer] the line the block opened at `index` closes on: the next `end` at its
+        #   own indent, or the line itself when it opens no block
+        def block_end(lines, index, indent)
+          return index + 1 if !lines[index].match?(OPENING) || lines[index].match?(ENDLESS)
+
+          close = lines[(index + 1)..].to_a.index { |text| text.match?(/\A {#{indent}}end\b/) }
+          close ? index + close + 2 : lines.length
+        end
+
+        # @return [Array<Entry>] the headings of a Markdown file, each ending where the next of its
+        #   level or higher begins
+        def headings(file, lines)
+          found = lines.each_with_index.filter_map { |text, at| heading(text, at) }
+          found.each_with_index.map do |(at, level, name), position|
+            stop = found[(position + 1)..].find { |_, other, _| other <= level }
+            Entry.new(file: file, from: at + 1, to: stop ? stop[0] : lines.length, kind: "#" * level, name: name)
+          end
+        end
+
+        # @return [Array, nil] the line index, level and title when `text` is a heading
+        def heading(text, index)
+          match = text.match(HEADING) or return
+          [index, match[:hashes].length, match[:name]]
+        end
+
+        # @return [Array<Entry>] the entries whose file is one of `paths`, or below one
+        def within(all, paths)
+          prefixes = paths.split(",").map { |path| path.delete_prefix("./").chomp("/") }
+          all.select { |entry| prefixes.any? { |prefix| entry.file == prefix || entry.file.start_with?("#{prefix}/") } }
+        end
+
+        def build(tree, files)
+          files.flat_map { |file| scan(file, File.readlines(tree.path(file), chomp: true).map(&:scrub)) }
+        end
+
+        def stat(tree, file)
+          info = File.stat(tree.path(file))
+          [info.mtime.to_i, info.size]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/inspection.rb

@@ -61,10 +61,10 @@ module Hecks
         # @return [String] its output
         # @raise [ConsoleCapture::Failure] when it ended in a status that is not a report
         def report(operation, result)
-          return result.out if REPORTING.fetch(operation, [0]).include?(result.status.exitstatus)
+          code = result.exit_code
+          return result.out if REPORTING.fetch(operation, [0]).include?(code)
 
-          raise ConsoleCapture::Failure,
-                "#{operation} ended with status #{result.status.exitstatus}: #{result.err}#{result.out}".strip
+          raise ConsoleCapture::Failure, "#{operation} ended with status #{code}: #{result.err}#{result.out}".strip
         end
 
         # @param text [String] a report
@@ -81,7 +81,8 @@ module Hecks
         # @return [Array<String>] the files, relative to the root and sorted
         def ruby_files(tree, paths)
           excluded = exclusions(tree)
-          paths.split(",").flat_map { |path| listing(tree, path) }.uniq.sort.reject do |file|
+          listed = paths.split(",").flat_map { |path| listing(tree, path) }.uniq
+          listed.sort.reject do |file|
             excluded.any? { |glob| File.fnmatch?(glob, file, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
           end
         end

data/lib/hecks/hecks/adapters/codebase/language.rb

@@ -25,6 +25,7 @@ module Hecks
           "project_rust_vocabulary"   => :rust_vocabulary,
           "project_reserved_names"    => :reserved_names,
           "project_parser_table"      => :parser_table,
+          "project_phrase_table"      => :phrase_table,
           "project_bootstrap_table"   => :bootstrap_table,
           "project_field_hints"       => :field_hints,
           "project_expression_tables" => :expression_tables,