agentilda 1.0.3

data/lib/agentilda/keyboard.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Agentilda
+  # Listens for single keypresses while a run is in flight, and turns them
+  # into {Control} broadcasts.
+  #
+  # The listener is a thread reading STDIN in raw mode, which only makes
+  # sense when STDIN is a terminal: piped input must never be eaten one byte
+  # at a time, and a run under cron has nobody at the keys. {.listen} returns
+  # nil in both cases and every caller treats nil as "no keyboard".
+  #
+  # Raw mode swallows Ctrl-C along with everything else, so ETX is forwarded
+  # to the main thread as the Interrupt it would have been — the listener
+  # must never make a run harder to kill than it was without one.
+  class Keyboard
+    # Key → what it does, rendered by {#help} and dispatched by {#handle}.
+    BINDINGS = [
+      ["h  ?", "this help"],
+      ["w", "ask every running agent to wrap up as fast as possible"],
+      ["n", "ask agents to write out what they have and stop; the loop continues"],
+      ["q", "write out, stop everything, and quit after a #{Control::GRACE}s grace"],
+      ["ctrl-c", "interrupt the run, as ever"]
+    ].freeze
+
+    # @return [Agentilda::Keyboard, nil] a running listener, or nil when
+    #   STDIN is not a terminal
+    def self.listen(input: $stdin)
+      return nil unless input.tty?
+
+      new(input:).start
+    end
+
+    # @param input [IO]
+    def initialize(input: $stdin)
+      @input = input
+    end
+
+    # @return [self]
+    def start
+      @thread = Thread.new do
+        Thread.current.report_on_exception = false
+        loop { handle(@input.getch) }
+      rescue IOError, Errno::EIO
+        # STDIN went away; a keyboard with no keys just stops listening.
+      end
+      self
+    end
+
+    # @return [void]
+    def stop
+      @thread&.kill
+      @thread = nil
+    end
+
+    # @param key [String, nil]
+    # @return [void]
+    def handle(key)
+      case key
+      when "h", "?" then UI.popup("Keys", help)
+      when "w" then acted("w — agents asked to wrap up") { Control.wrap_up! }
+      when "n" then acted("n — agents asked to write out and stop") { Control.stop! }
+      when "q" then acted("q — quitting; #{Control::GRACE}s grace to write out") { Control.quit! }
+      when "\u0003" then Thread.main.raise(Interrupt)
+      end
+    end
+
+    # @return [String] the bindings, one per line, widest key first
+    def help
+      width = BINDINGS.map { |key, _| key.length }.max
+      BINDINGS.map { |key, does| "#{key.ljust(width)}   #{does}" }.join("\n")
+    end
+
+    private
+
+    # A keypress with no acknowledgement looks like a keypress that did
+    # nothing, so each one says what it just asked for.
+    #
+    # @param note [String]
+    # @return [void]
+    def acted(note)
+      yield
+      UI.log(note)
+      UI.line(note)
+    end
+  end
+end

data/lib/agentilda/linear/api.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Agentilda
+  module Linear
+    # Linear's GraphQL API, wrapped as thinly as {Agentilda::GitHub} wraps
+    # `gh`, and for the same reason: it is a seam. Every example in the suite
+    # injects a transport here, so nothing in the tests reaches Linear.
+    #
+    # Only the dozen operations an import needs are here. This is not a client
+    # library, and it should not grow into one — anything Linear can do that
+    # `.plans` cannot express does not belong in a tool whose whole premise is
+    # that the folder is the source of truth.
+    class API
+      ENDPOINT = "https://api.linear.app/graphql"
+
+      # The environment variable holding a personal API key.
+      TOKEN_VARIABLE = "LINEAR_API_KEY"
+
+      # @return [String, nil] the token, from the environment
+      def self.token_from_env = ENV[TOKEN_VARIABLE].to_s.strip.then { |t| t.empty? ? nil : t }
+
+      # @param token [String] a Linear personal API key
+      # @param transport [#call, nil] `(query, variables) -> Hash`, for tests
+      # @param endpoint [String]
+      def initialize(token: nil, transport: nil, endpoint: ENDPOINT)
+        @token = token
+        @transport = transport
+        @endpoint = endpoint
+        return if transport || (token && !token.empty?)
+
+        raise Error, "no Linear token. Set #{TOKEN_VARIABLE}, or use the MCP transport:\n  " \
+                     "agentilda linear import <TEAM> -p <PROJECT> --format json"
+      end
+
+      # The team, its workflow states and its labels, in one round trip.
+      #
+      # @param key [String] the team key, e.g. "TAX"
+      # @return [Hash] `{id:, name:, key:, states: [...], labels: [...]}`
+      # @raise [Agentilda::Error] when no team wears that key
+      def team(key)
+        node = query(TEAM, key: key.to_s.upcase).dig("teams", "nodes")&.first
+        raise Error, "no Linear team has the key #{key.to_s.upcase}" unless node
+
+        {id: node["id"], name: node["name"], key: node["key"],
+         states: node.dig("states", "nodes").to_a, labels: node.dig("labels", "nodes").to_a}
+      end
+
+      # @param team_id [String]
+      # @return [Array<Hash>] `{id:, name:, url:}`
+      def projects(team_id) = query(PROJECTS, teamId: team_id).dig("team", "projects", "nodes").to_a
+
+      # @param input [Hash] `{name:, teamIds:, content:, icon:}`
+      # @return [Hash] `{id:, name:, url:}`
+      def create_project(input) = unwrap(query(PROJECT_CREATE, input:), "projectCreate", "project")
+
+      # @param id [String]
+      # @param input [Hash]
+      # @return [Hash]
+      def update_project(id, input) = unwrap(query(PROJECT_UPDATE, id:, input:), "projectUpdate", "project")
+
+      # @param input [Hash] `{teamId:, projectId:, title:, description:, stateId:, labelIds:}`
+      # @return [Hash] `{id:, identifier:, url:}`
+      def create_issue(input) = unwrap(query(ISSUE_CREATE, input:), "issueCreate", "issue")
+
+      # @param id [String] a UUID or an identifier such as "TAX-41"
+      # @param input [Hash]
+      # @return [Hash]
+      def update_issue(id, input) = unwrap(query(ISSUE_UPDATE, id:, input:), "issueUpdate", "issue")
+
+      # @param name [String]
+      # @param team_id [String]
+      # @return [Hash] `{id:, name:}`
+      def create_label(name, team_id)
+        unwrap(query(LABEL_CREATE, input: {name:, teamId: team_id}), "issueLabelCreate", "issueLabel")
+      end
+
+      # @param issue_id [String]
+      # @param url [String]
+      # @param title [String]
+      # @return [void]
+      def link(issue_id:, url:, title:)
+        query(ATTACHMENT_CREATE, input: {issueId: issue_id, url:, title:})
+      end
+
+      # @param query [String] a GraphQL document
+      # @param variables [Hash]
+      # @return [Hash] the `data` object
+      # @raise [Agentilda::Error] on a transport or GraphQL error
+      def query(query, **variables)
+        body = transport.call(query, variables)
+        errors = body["errors"]
+        raise Error, "Linear rejected the request: #{describe(errors)}" if errors&.any?
+
+        body.fetch("data") { raise Error, "Linear returned no data" }
+      end
+
+      private
+
+      # @return [String, nil]
+      attr_reader :token
+
+      # @return [String]
+      attr_reader :endpoint
+
+      # @return [#call]
+      def transport = @transport ||= method(:post)
+
+      # Linear reports a failed mutation as `success: false` rather than as an
+      # error, so the envelope has to be checked as well as the errors array.
+      #
+      # @param data [Hash]
+      # @param mutation [String]
+      # @param field [String]
+      # @return [Hash]
+      def unwrap(data, mutation, field)
+        payload = data[mutation] or raise Error, "Linear returned no #{mutation} payload"
+        raise Error, "Linear declined the #{mutation}" unless payload["success"]
+
+        payload.fetch(field)
+      end
+
+      # @param errors [Array<Hash>]
+      # @return [String]
+      def describe(errors)
+        Array(errors).map { |e| e["message"] || e.to_s }.join("; ")
+      end
+
+      # @param document [String]
+      # @param variables [Hash]
+      # @return [Hash] the parsed response body
+      def post(document, variables)
+        uri = URI(endpoint)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = token
+        request.body = JSON.generate(query: document, variables:)
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https",
+          open_timeout: 10, read_timeout: 30) { |http| http.request(request) }
+
+        parse(response)
+      rescue JSON::ParserError, IOError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise Error, "could not reach Linear at #{endpoint}: #{e.message}"
+      end
+
+      # @param response [Net::HTTPResponse]
+      # @return [Hash]
+      def parse(response)
+        return JSON.parse(response.body.to_s) if response.is_a?(Net::HTTPSuccess)
+
+        hint = if ["400", "401"].include?(response.code)
+          "\n\nCheck #{TOKEN_VARIABLE}. A personal API key is sent verbatim, without a `Bearer` prefix."
+        end
+        raise Error, "Linear returned HTTP #{response.code}#{hint}"
+      end
+
+      TEAM = <<~GRAPHQL
+        query Team($key: String!) {
+          teams(filter: { key: { eq: $key } }, first: 1) {
+            nodes {
+              id name key
+              states(first: 100) { nodes { id name type position } }
+              labels(first: 250) { nodes { id name } }
+            }
+          }
+        }
+      GRAPHQL
+
+      PROJECTS = <<~GRAPHQL
+        query Projects($teamId: String!) {
+          team(id: $teamId) {
+            projects(first: 250) {
+              nodes { id name url description content status { name type } }
+            }
+          }
+        }
+      GRAPHQL
+
+      PROJECT_CREATE = <<~GRAPHQL
+        mutation CreateProject($input: ProjectCreateInput!) {
+          projectCreate(input: $input) { success project { id name url } }
+        }
+      GRAPHQL
+
+      PROJECT_UPDATE = <<~GRAPHQL
+        mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
+          projectUpdate(id: $id, input: $input) { success project { id name url } }
+        }
+      GRAPHQL
+
+      ISSUE_CREATE = <<~GRAPHQL
+        mutation CreateIssue($input: IssueCreateInput!) {
+          issueCreate(input: $input) { success issue { id identifier url } }
+        }
+      GRAPHQL
+
+      ISSUE_UPDATE = <<~GRAPHQL
+        mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
+          issueUpdate(id: $id, input: $input) { success issue { id identifier url } }
+        }
+      GRAPHQL
+
+      LABEL_CREATE = <<~GRAPHQL
+        mutation CreateLabel($input: IssueLabelCreateInput!) {
+          issueLabelCreate(input: $input) { success issueLabel { id name } }
+        }
+      GRAPHQL
+
+      ATTACHMENT_CREATE = <<~GRAPHQL
+        mutation CreateAttachment($input: AttachmentCreateInput!) {
+          attachmentCreate(input: $input) { success attachment { id } }
+        }
+      GRAPHQL
+    end
+  end
+end

data/lib/agentilda/linear/attribution.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Linear
+    # Which plan a pull request belongs to, when its title does not say.
+    #
+    # `resync prs` puts an `[NNN.MM]` on every title it can resolve, and most
+    # of them resolve. What is left is the tail: work that shipped before the
+    # convention existed, or from a branch named after nothing in particular.
+    # Those pull requests are real work with no home, and dropping them means
+    # the issues that stand for a plan are missing pieces of it.
+    #
+    # The rule is word overlap between the pull request's title and the
+    # folder's name. It works here, where it did not work for matching plans
+    # to projects, because the candidates are different: a folder slug is
+    # `ledger-carryforward-vintages`, three specific words about one thing,
+    # and there are twenty of them to choose between. A project is called
+    # "US Tax Law: Self Contained Ruby Gem" and there are four.
+    #
+    # It is still a guess, and it says so. A tie is refused rather than broken,
+    # because two folders matching equally well is evidence that neither is
+    # right rather than a reason to pick the first.
+    class Attribution
+      # One pull request, placed.
+      #
+      # @!attribute [r] pull
+      #   @return [Agentilda::PullRequest]
+      # @!attribute [r] subject
+      #   @return [Agentilda::Subject, nil] nil when nothing matched
+      # @!attribute [r] score
+      #   @return [Integer] words the title and the folder name shared
+      # @!attribute [r] rivals
+      #   @return [Array<String>] folders that matched equally well
+      Placed = Data.define(:pull, :subject, :score, :rivals, :widened) do
+        # @return [Boolean]
+        def placed? = !subject.nil?
+
+        # @return [String]
+        def percent = "#{(score * 100).round}%"
+
+        # @return [String] where the matching words came from
+        def source = widened ? "title and description" : "title"
+
+        # @return [String]
+        def why
+          return "matched no folder at all" if subject.nil? && score.zero?
+          return "#{percent} of a folder name is not enough" if subject.nil? && rivals.empty?
+          # `rivals` already holds every tied folder — there is no winner to
+          # add back in, and `+ 1` here once reported a two-way tie as three.
+          return "#{rivals.size} folders matched equally well (#{percent})" if subject.nil?
+
+          "#{source}: covers #{percent} of the folder name"
+        end
+      end
+
+      # Words too common in this domain to carry a match on their own. Every
+      # plan in a tax engine says "tax"; a pull request that says it too has
+      # told you nothing.
+      # How much of a folder's name a title must cover to claim it.
+      FLOOR = 0.5
+
+      # And how much a description must cover, which is more.
+      #
+      # A title is written to say what the change is. A description is written
+      # to get the change reviewed, and it opens with whatever this repository
+      # puts at the top of every one of them — a stacking note, a diff
+      # summary, a checklist. Read at the same bar as a title it produced two
+      # placements here and both were wrong, one of them on the word
+      # "documents" inside "diff includes nineteen documents".
+      WIDER_FLOOR = 0.75
+
+      # Words, not just a fraction. Half of a two-word folder name is one
+      # word, which is the case that was already established as too thin —
+      # "core" alone claiming `deterministic-core-and-as-of`.
+      MINIMUM_WORDS = 3
+
+      NOISE = %w[the and for with from into that this add adds added fix fixes
+        update updates use uses spec plan pull request pr tax app web api].freeze
+
+      # @param tree [Agentilda::Tree]
+      def initialize(tree:)
+        @tree = tree
+      end
+
+      # How much of a pull request's description to read when its title was
+      # not enough. The opening sentence or two of a description says what the
+      # change is for; further down it turns into checklists, test plans and
+      # generated tables, which are the same words on every pull request in
+      # the repository and match everything equally.
+      OPENING_WORDS = 20
+
+      # @param pulls [Array<Agentilda::PullRequest>] the ones with no number
+      # @param bodies [Hash{String => String}] descriptions, by pull request number
+      # @return [Array<Agentilda::Linear::Attribution::Placed>]
+      def call(pulls, bodies: {})
+        pulls.map do |pull|
+          found = place(pull, words(pull.title))
+          next found if found.placed?
+
+          # Second pass. A title is a headline and sometimes says nothing
+          # useful — "Add the Drake reference-return worklist" names a vendor
+          # rather than the work. The description usually opens by saying what
+          # the change is actually about.
+          opening = opening_words(bodies[pull.number.to_s])
+          next found if opening.empty?
+
+          wider = place(pull, words(pull.title) | opening, floor: WIDER_FLOOR)
+          wider.placed? ? wider.with(widened: true) : found
+        end
+      end
+
+      # @param body [String, nil]
+      # @return [Array<String>]
+      def opening_words(body)
+        text = body.to_s
+          .gsub(/<!--.*?-->/m, "")
+          .gsub(/```.*?```/m, "")
+          .gsub(/^\s*[-*|#>]+/, " ")
+        words(text.split(/\s+/).first(OPENING_WORDS * 3).join(" ")).first(OPENING_WORDS)
+      end
+
+      private
+
+      # @return [Agentilda::Tree]
+      attr_reader :tree
+
+      # @param pull [Agentilda::PullRequest]
+      # @param wanted [Array<String>] the words to match on
+      # @param floor [Float] how much of a folder name is enough
+      # @return [Agentilda::Linear::Attribution::Placed]
+      def place(pull, wanted, floor: FLOOR)
+        return Placed.new(pull:, subject: nil, score: 0.0, rivals: [], widened: false) if wanted.empty?
+
+        ranked = tree.subjects.filter_map { |s|
+          overlap = shared(folder_words(s), wanted)
+          [s, overlap] if overlap.positive?
+        }.sort_by { |_, overlap| -overlap }
+
+        best, score = ranked.first
+
+        # One word in common is not evidence. "Add year-keyed tax rules" shares
+        # "rules" with `rules-retirement-and-engine-convergence` and has
+        # nothing to do with it.
+        enough = best && score >= floor && (score * folder_words(best).size).round >= MINIMUM_WORDS
+        return Placed.new(pull:, subject: nil, score: score.to_f, rivals: [], widened: false) unless enough
+
+        tied = ranked.select { |_, overlap| overlap == score }
+        return Placed.new(pull:, subject: best, score:, rivals: [], widened: false) if tied.one?
+
+        Placed.new(pull:, subject: nil, score:, rivals: tied.map { |s, _| s.feature.dirname }, widened: false)
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @return [Array<String>]
+      def folder_words(subject)
+        (@folder_words ||= {})[subject.feature.path] ||=
+          words(subject.feature.slug.tr("-", " ")) | words(subject.feature.title)
+      end
+
+      # @param text [String]
+      # @return [Array<String>]
+      def words(text)
+        text.to_s.downcase.gsub(/[^a-z0-9]+/, " ").split
+          .reject { |w| w.length < 4 || NOISE.include?(w) }.uniq
+      end
+
+      # How much of a folder's name a pull request title actually said.
+      #
+      # A pull request said `signed_off` where its folder says `sign-off`, and
+      # `vintages` where the folder says `vintage`. Compared literally those
+      # are strangers, and the first cost a placement a human makes instantly
+      # — one a later, numbered pull request went on to prove correct.
+      #
+      # Matching on a shared prefix rather than by stripping suffixes, because
+      # stripping is destructive and gets it wrong in both directions:
+      # `corpus` is not a plural, and turning it into `corpu` reads as a typo
+      # in every diagnostic that prints it.
+      #
+      # @param folder [Array<String>]
+      # @param title [Array<String>]
+      # @return [Float] 0.0 to 1.0
+      def shared(folder, title) = Fuzzy.coverage(folder, title)
+    end
+  end
+end

data/lib/agentilda/linear/fuzzy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fuzzystringmatch"
+
+module Agentilda
+  module Linear
+    # How alike two short strings are, on a scale rather than a yes or no.
+    #
+    # Counting shared words gives whole numbers, and whole numbers tie. Three
+    # folders scoring 2 against the same pull request is not three good
+    # answers — it is no answer — but a tie has to be *detected* to be
+    # refused, and with a coarse enough score everything ties.
+    #
+    # Jaro-Winkler grades instead, and it is the right measure for these
+    # inputs: it is built for short strings, and its prefix bonus is exactly
+    # the shape of the errors here — a word and its inflection agree from the
+    # front and diverge at the end.
+    module Fuzzy
+      module_function
+
+      # Two words count as the same word above this.
+      #
+      # Calibrated rather than chosen. The prefix bonus that makes
+      # `rounding`/`round` (0.938) work also lifts `plaid`/`plain` (0.920) and
+      # `state`/`statement` (0.926), which are different words that would
+      # wrongly file a pull request. 0.93 is the gap between those two groups.
+      # It costs `corpus`/`corpora` (0.848), which is rarer than either.
+      AKIN = 0.93
+
+      # Deliberately the pure-Ruby implementation. The native one needs a C
+      # extension that does not build everywhere — it fails on this machine
+      # over a jemalloc header — and asking for it prints a compile warning to
+      # STDERR on every single load, which would land in the middle of every
+      # command's output. An import compares a few hundred short strings; that
+      # is nowhere near enough work to be worth a build step.
+      #
+      # @return [FuzzyStringMatch::JaroWinklerPure]
+      def matcher = @matcher ||= FuzzyStringMatch::JaroWinkler.create(:pure)
+
+      # @param one [String]
+      # @param other [String]
+      # @return [Float] 0.0 to 1.0
+      def similarity(one, other) = matcher.getDistance(one.to_s.downcase, other.to_s.downcase)
+
+      # @param one [String]
+      # @param other [String]
+      # @return [Boolean] whether these are the same word, inflections aside
+      def akin?(one, other) = similarity(one, other) >= AKIN
+
+      # What fraction of `wanted` has a counterpart in `found`.
+      #
+      # Asymmetric on purpose. A folder is named for what it is about, in two
+      # or three words; a pull request title is a sentence. Asking how much of
+      # the sentence the folder covers would punish every long title, so the
+      # question is the other way round: how much of this folder's name did
+      # the title actually say?
+      #
+      # @param wanted [Array<String>] the folder's words
+      # @param found [Array<String>] the title's words
+      # @return [Float] 0.0 to 1.0
+      def coverage(wanted, found)
+        return 0.0 if wanted.empty?
+
+        wanted.count { |word| found.any? { |other| akin?(word, other) } }.fdiv(wanted.size)
+      end
+    end
+  end
+end