intent-record 1.0.0

data/lib/intent_record/cli.rb

@@ -0,0 +1,69 @@
+require "json"
+require_relative "cli/streams"
+require_relative "cli/argv_parser"
+require_relative "cli/dispatch"
+
+module IntentRecord
+  # Entry point for the `intent-record` executable. JSON in, JSON out, exit 0 on success.
+  class CLI
+    CONFIG_DIR_FLAG = "--config-dir".freeze
+
+    def self.run(argv)
+      exit new(argv, config: Config.default, streams: Streams.default).run
+    end
+
+    def initialize(argv, config:, streams:)
+      @argv = argv.dup
+      @config = config
+      @streams = streams
+    end
+
+    def run
+      take_config_dir!
+      dispatch(@argv.shift)
+    rescue Error => e
+      emit_error(e.message)
+    end
+
+    private
+
+    # Lifted before the command is taken, so it may be written on either side of
+    # it. A misspelling is left in argv, where it becomes an unknown command or an
+    # unexpected argument: an option this CLI does not recognise is an error,
+    # which an environment variable nobody set can never be.
+    def take_config_dir!
+      parser = ArgvParser.new(@argv)
+      dir = parser.take_flag(CONFIG_DIR_FLAG)
+      @argv = parser.remaining
+      @config = Config.new(config_dir: dir) if dir
+    end
+
+    def dispatch(command)
+      return usage if command.nil? || (@argv + [command]).intersect?(%w[--help -h])
+      return version if %w[--version version].include?(command)
+
+      connect!
+      Dispatch.new(@argv, streams: @streams, config: @config).call(command)
+    end
+
+    def connect!
+      @config.load!
+      Database.connect!(@config.db_path)
+    end
+
+    def usage
+      @streams.stderr.puts USAGE
+      0
+    end
+
+    def version
+      @streams.stdout.puts VERSION
+      0
+    end
+
+    def emit_error(message)
+      @streams.stdout.puts JSON.generate({ "error" => message })
+      1
+    end
+  end
+end

data/lib/intent_record/commands/attach.rb

@@ -0,0 +1,39 @@
+require_relative "../formatter"
+require_relative "../models/intent_record"
+require_relative "../linkers/asset_version_linker"
+require_relative "../linkers/stakeholder_linker"
+require_relative "../linkers/intent_linker"
+
+module IntentRecord
+  module Commands
+    # Links more commits, stakeholder sources or related intents to an existing intent record.
+    class Attach
+      LINK_KEYS = %w[commits asset_versions stakeholder_references related_intent_ids].freeze
+
+      def initialize(intent_id:)
+        @intent_id = intent_id
+      end
+
+      def call(input)
+        record = Models::IntentRecord.find_by(global_id: @intent_id)
+        raise NotFoundError, "Intent record not found: #{@intent_id}" unless record
+        raise ValidationError, "Nothing to attach: provide one of #{LINK_KEYS.join(", ")}" if nothing_to_attach?(input)
+
+        ActiveRecord::Base.transaction { link_all(record, input) }
+        Formatter.full(record.reload)
+      end
+
+      private
+
+      def nothing_to_attach?(input)
+        LINK_KEYS.none? { |key| !input[key].nil? && input[key] != [] }
+      end
+
+      def link_all(record, input)
+        Linkers::AssetVersionLinker.call(record, input)
+        Linkers::StakeholderLinker.call(record, input)
+        Linkers::IntentLinker.call(record, input)
+      end
+    end
+  end
+end

data/lib/intent_record/commands/by_source.rb

@@ -0,0 +1,52 @@
+require_relative "../formatter"
+require_relative "../like_pattern"
+require_relative "../stakeholder_normalizer"
+require_relative "../models/stakeholder_source"
+
+module IntentRecord
+  module Commands
+    # Answers "what did we build for this ticket, and why": every intent linked to a
+    # stakeholder source (by exact uri or substring) plus the distinct commits across them.
+    class BySource
+      def initialize(uri:, contains: false)
+        @uri = uri.strip
+        @contains = contains
+      end
+
+      def call
+        sources = matching_sources.includes(:stakeholder_system).to_a
+        intents = intents_for(sources)
+        {
+          "sources" => sources.map { |s| Formatter.source(s) },
+          "asset_versions" => intents.flat_map { |i| i["asset_versions"] }.uniq,
+          "intents" => intents
+        }
+      end
+
+      private
+
+      def matching_sources
+        return sources.where(uri: StakeholderNormalizer.uri(@uri)) unless @contains
+
+        sources.where(LikePattern.contains("uri"), LikePattern.contains_bind(@uri))
+      end
+
+      # In the order the sources were first recorded. An unordered query is
+      # answered in whatever order the plan produces, and that is a list a person
+      # reads.
+      def sources
+        Models::StakeholderSource.order(:id)
+      end
+
+      def intents_for(sources)
+        Formatter.preloaded(matching_intents(sources)).map { |r| Formatter.full(r) }
+      end
+
+      def matching_intents(sources)
+        Models::IntentRecord.joins(:stakeholder_references)
+                            .where(stakeholder_references: { stakeholder_source_id: sources.map(&:id) })
+                            .distinct.order(:created_at)
+      end
+    end
+  end
+end

data/lib/intent_record/commands/lookup.rb

@@ -0,0 +1,22 @@
+require_relative "../asset_version_resolver"
+require_relative "../formatter"
+
+module IntentRecord
+  module Commands
+    # Everything recorded against one commit (or other asset version).
+    class Lookup
+      def initialize(external_id:, vcs: nil)
+        @external_id = external_id
+        @vcs = vcs
+      end
+
+      def call
+        version = AssetVersionResolver.new(external_id: @external_id, vcs: @vcs).call
+        {
+          "asset_version" => Formatter.asset_version(version),
+          "intents" => Formatter.preloaded(version.intent_records.order(:created_at)).map { |r| Formatter.full(r) }
+        }
+      end
+    end
+  end
+end

data/lib/intent_record/commands/recent.rb

@@ -0,0 +1,21 @@
+require_relative "../formatter"
+require_relative "../models/intent_record"
+
+module IntentRecord
+  module Commands
+    class Recent
+      DEFAULT_LIMIT = 20
+
+      def initialize(limit: DEFAULT_LIMIT)
+        @limit = limit
+      end
+
+      def call
+        raise ValidationError, "--limit must be at least 1" if @limit < 1
+
+        records = Formatter.preloaded(Models::IntentRecord.order(created_at: :desc, id: :desc).limit(@limit))
+        { "intents" => records.map { |r| Formatter.full(r) } }
+      end
+    end
+  end
+end

data/lib/intent_record/commands/record.rb

@@ -0,0 +1,52 @@
+require_relative "../input_validator"
+require_relative "../formatter"
+require_relative "../global_id"
+require_relative "../models/intent_record"
+require_relative "../linkers/asset_version_linker"
+require_relative "../linkers/stakeholder_linker"
+require_relative "../linkers/intent_linker"
+
+module IntentRecord
+  module Commands
+    # Creates an intent record and links it to commits, stakeholder sources and related intents.
+    class Record
+      def call(input)
+        attributes = validated(input)
+
+        ActiveRecord::Base.transaction do
+          record = create!(attributes)
+          link_all(record, input)
+          Formatter.full(record)
+        end
+      end
+
+      private
+
+      # Nothing here reaches the database, so bad input is refused before the
+      # store is asked anything, and these rules can be exercised without one.
+      def validated(input)
+        { summary: summary(input),
+          body: InputValidator.required_string!(input, "body"),
+          author: InputValidator.optional_string!(input, "author"),
+          created_at: Time.now.utc }
+      end
+
+      # Minting the id asks the store whether it is taken, which is why it waits
+      # until the input has been accepted.
+      def create!(attributes)
+        Models::IntentRecord.create!(attributes.merge(global_id: GlobalId.unique_for(Models::IntentRecord)))
+      end
+
+      def summary(input)
+        InputValidator.required_string!(input, "summary", max_length: Models::IntentRecord::SUMMARY_MAX_LENGTH)
+                      .gsub(/\s+/, " ")
+      end
+
+      def link_all(record, input)
+        Linkers::AssetVersionLinker.call(record, input)
+        Linkers::StakeholderLinker.call(record, input)
+        Linkers::IntentLinker.call(record, input)
+      end
+    end
+  end
+end

data/lib/intent_record/commands/search.rb

@@ -0,0 +1,50 @@
+require_relative "../formatter"
+require_relative "../like_pattern"
+require_relative "../models/intent_record"
+
+module IntentRecord
+  module Commands
+    # Case-insensitive substring search over summary, body, and linked stakeholder uris and titles,
+    # so a ticket key such as ACME-42 finds the intents built for it.
+    class Search
+      LIMIT = 200
+      FIELDS = %w[intent_records.summary intent_records.body stakeholder_sources.uri stakeholder_sources.title].freeze
+
+      def initialize(terms:, match: "any")
+        @terms = terms.map(&:strip).reject(&:empty?)
+        @match = match
+      end
+
+      def call
+        raise ValidationError, "At least one search term is required" if @terms.empty?
+        raise ValidationError, "--match must be any or all" unless %w[any all].include?(@match)
+
+        { "intents" => matching_records.map { |r| Formatter.full(r) } }
+      end
+
+      private
+
+      def matching_records
+        Formatter.preloaded(
+          Models::IntentRecord.left_joins(:stakeholder_sources)
+                              .group("intent_records.id")
+                              .having(having_sql, *having_binds)
+                              .order(created_at: :desc).limit(LIMIT)
+        )
+      end
+
+      def having_sql
+        joiner = @match == "all" ? " AND " : " OR "
+        @terms.map { "SUM(CASE WHEN #{term_clause} THEN 1 ELSE 0 END) > 0" }.join(joiner)
+      end
+
+      def term_clause
+        FIELDS.map { |f| LikePattern.contains(f) }.join(" OR ")
+      end
+
+      def having_binds
+        @terms.flat_map { |t| [LikePattern.contains_bind(t)] * FIELDS.size }
+      end
+    end
+  end
+end

data/lib/intent_record/commands/show.rb

@@ -0,0 +1,19 @@
+require_relative "../formatter"
+require_relative "../models/intent_record"
+
+module IntentRecord
+  module Commands
+    class Show
+      def initialize(intent_id:)
+        @intent_id = intent_id
+      end
+
+      def call
+        record = Formatter.preloaded(Models::IntentRecord).find_by(global_id: @intent_id)
+        raise NotFoundError, "Intent record not found: #{@intent_id}" unless record
+
+        Formatter.full(record)
+      end
+    end
+  end
+end

data/lib/intent_record/commands/systems.rb

@@ -0,0 +1,16 @@
+require_relative "../models/vcs_system"
+require_relative "../models/stakeholder_system"
+
+module IntentRecord
+  module Commands
+    # Vocabulary discovery: which vcs and stakeholder system names are known.
+    class Systems
+      def call
+        {
+          "vcs_systems" => Models::VcsSystem.order(:name).pluck(:name),
+          "stakeholder_systems" => Models::StakeholderSystem.order(:name).pluck(:name)
+        }
+      end
+    end
+  end
+end

data/lib/intent_record/config.rb

@@ -0,0 +1,51 @@
+require "yaml"
+require "fileutils"
+
+module IntentRecord
+  # Locates the config directory and the SQLite database path.
+  # Bootstraps ~/.intent-record/config.yml on first use.
+  class Config
+    DEFAULT_CONFIG_DIR = File.expand_path("~/.intent-record")
+    DB_FILENAME = "intent-record.db".freeze
+
+    attr_reader :config_dir, :db_path
+
+    # The one caller that means "wherever this person keeps their records" says so
+    # by name. Everywhere else has to name a directory, so no caller can arrive at
+    # somebody's own store by losing an argument.
+    def self.default
+      new(config_dir: ENV.fetch("INTENT_RECORD_CONFIG_DIR", DEFAULT_CONFIG_DIR))
+    end
+
+    def initialize(config_dir:)
+      raise ArgumentError, "config_dir is required; use Config.default for this user's own store" if config_dir.nil?
+
+      @config_dir = config_dir
+    end
+
+    def load!
+      bootstrap! unless File.exist?(config_file_path)
+      read_config!
+      self
+    end
+
+    private
+
+    def bootstrap!
+      FileUtils.mkdir_p(@config_dir)
+      File.write(config_file_path, YAML.dump("db_path" => File.join(@config_dir, DB_FILENAME)))
+    end
+
+    def config_file_path
+      File.join(@config_dir, "config.yml")
+    end
+
+    def read_config!
+      data = YAML.load_file(config_file_path)
+      valid = data.is_a?(Hash) && !data["db_path"].to_s.strip.empty?
+      raise ConfigError, "db_path is not configured in #{config_file_path}" unless valid
+
+      @db_path = data["db_path"]
+    end
+  end
+end

data/lib/intent_record/database.rb

@@ -0,0 +1,74 @@
+require "active_record"
+require "fileutils"
+require "sqlite3"
+require_relative "seeds"
+require_relative "sqlite_connection_setup"
+
+module IntentRecord
+  module Database
+    MIGRATIONS_PATH = File.expand_path("../../db/migrate", __dir__)
+
+    # mkdir_p raises an Errno when the parent cannot be created, but once the
+    # directory exists sqlite reports an unwritable file or directory through
+    # ActiveRecord instead, so both families have to become the same DatabaseError.
+    UNWRITABLE_CAUSES = [SQLite3::CantOpenException, SQLite3::ReadOnlyException].freeze
+
+    def self.connect!(db_path)
+      translating_unwritable(db_path) do
+        FileUtils.mkdir_p(File.dirname(db_path))
+        establish!(db_path)
+        while_setting_up(db_path) { migrate_and_seed! }
+      end
+    end
+
+    def self.translating_unwritable(db_path)
+      yield
+    rescue Errno::EACCES, Errno::EPERM, Errno::EROFS => e
+      raise DatabaseError, unwritable(db_path, e)
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless UNWRITABLE_CAUSES.any? { |klass| e.cause.is_a?(klass) }
+
+      raise DatabaseError, unwritable(db_path, e.cause)
+    end
+
+    def self.establish!(db_path)
+      ActiveRecord::Base.logger = nil
+      # The pragma sets sqlite's own busy timeout, which is not the same thing as
+      # the adapter's: without :timeout ActiveRecord installs no busy handler and
+      # a write that meets a concurrent one fails rather than waiting.
+      ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: db_path,
+                                              timeout: SqliteConnectionSetup::BUSY_TIMEOUT_MS)
+    end
+
+    def self.migrate_and_seed!
+      run_migrations!
+      Seeds.apply!
+    end
+
+    def self.unwritable(db_path, error)
+      "Database path is not writable: #{db_path} (#{error.message})"
+    end
+
+    def self.disconnect!
+      ActiveRecord::Base.remove_connection
+    rescue StandardError
+      nil
+    end
+
+    # Migrating and seeding both read and then write, so two processes reaching a
+    # new store together each find the tables missing and each create them. Their
+    # individual statements succeed, so sqlite's locking has nothing to object to
+    # until one of them hits "table already exists". Serialise the whole setup.
+    def self.while_setting_up(db_path)
+      File.open("#{db_path}.setup", File::RDWR | File::CREAT) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    def self.run_migrations!
+      ActiveRecord::Migration.verbose = false
+      ActiveRecord::MigrationContext.new(MIGRATIONS_PATH).migrate
+    end
+  end
+end

data/lib/intent_record/formatter.rb

@@ -0,0 +1,59 @@
+module IntentRecord
+  # Turns models into the JSON shapes the CLI emits. Internal ids never leak.
+  #
+  # `full` reads four associations per record and does not load them itself, so a
+  # caller formatting more than one record hands it a scope through `preloaded`.
+  # Loading them here instead would query once per record however the caller
+  # asked, which is most of the work in a list of two hundred.
+  module Formatter
+    PRELOADS = [{ asset_versions: :vcs_system },
+                { stakeholder_sources: :stakeholder_system },
+                { outgoing_links: :target },
+                { incoming_links: :source }].freeze
+
+    module_function
+
+    def preloaded(scope)
+      scope.preload(*PRELOADS)
+    end
+
+    def summary(record)
+      {
+        "intent_id" => record.global_id,
+        "summary" => record.summary,
+        "author" => record.author,
+        "created_at" => record.created_at.utc.iso8601
+      }
+    end
+
+    def full(record)
+      summary(record).merge("body" => record.body).merge(external_links(record)).merge(intent_links(record))
+    end
+
+    def external_links(record)
+      {
+        "asset_versions" => record.asset_versions.map { |v| asset_version(v) },
+        "stakeholder_references" => record.stakeholder_sources.map { |s| source(s) }
+      }
+    end
+
+    def intent_links(record)
+      {
+        "related_intents" => record.outgoing_links.map { |l| summary(l.target) },
+        "related_by_intents" => record.incoming_links.map { |l| summary(l.source) }
+      }
+    end
+
+    def asset_version(version)
+      { "vcs" => version.vcs_system.name, "external_id" => version.external_id }
+    end
+
+    def source(source)
+      { "system" => source.stakeholder_system.name, "uri" => source.uri, "title" => source.title }
+    end
+
+    # Steps of `full`. Only `full`, `preloaded`, `asset_version` and `source` are
+    # asked for from outside.
+    private_class_method :summary, :external_links, :intent_links
+  end
+end

data/lib/intent_record/global_id.rb

@@ -0,0 +1,22 @@
+module IntentRecord
+  module GlobalId
+    BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".freeze
+    PATTERN = /\A[1-9A-HJ-NP-Za-km-z]{7}\z/
+    LENGTH = 7
+
+    def self.generate
+      Array.new(LENGTH) { BASE58_ALPHABET[rand(58)] }.join
+    end
+
+    def self.valid?(id)
+      id.is_a?(String) && PATTERN.match?(id)
+    end
+
+    def self.unique_for(model)
+      loop do
+        candidate = generate
+        return candidate unless model.exists?(global_id: candidate)
+      end
+    end
+  end
+end

data/lib/intent_record/input_validator.rb

@@ -0,0 +1,69 @@
+module IntentRecord
+  # Shape checks for the JSON an agent sends on stdin. Raises ValidationError with a field-named message.
+  module InputValidator
+    module_function
+
+    def required_string!(input, key, max_length: nil)
+      value = non_blank_string!(input, key)
+      max_length ? within_length!(value, key, max_length) : value
+    end
+
+    def optional_string!(input, key)
+      value = input[key]
+      return nil if value.nil?
+      raise ValidationError, "#{key} must be a string" unless value.is_a?(String)
+
+      value = value.strip
+      value.empty? ? nil : value
+    end
+
+    def array!(input, key)
+      value = input[key]
+      return [] if value.nil?
+      raise ValidationError, "#{key} must be an array" unless value.is_a?(Array)
+
+      value
+    end
+
+    # Judged by its stripped form, so returned stripped too. Returning the padded
+    # value would hand a caller something this module has already treated as the
+    # same as a shorter string, and a caller that looks an id up verbatim would
+    # then miss a record that exists.
+    def non_blank_strings!(values, label)
+      values.map do |v|
+        raise ValidationError, "#{label} must be a non-empty string" unless v.is_a?(String) && !v.strip.empty?
+
+        v.strip
+      end
+    end
+
+    def hashes_with!(values, label, *keys)
+      values.each do |v|
+        raise ValidationError, "#{label} entries must be objects" unless v.is_a?(Hash)
+
+        keys.each { |k| required_string!(v, k) }
+      end
+      values
+    end
+
+    def non_blank_string!(input, key)
+      value = input[key]
+      raise ValidationError, "#{key} is required" if value.nil?
+      raise ValidationError, "#{key} must be a string" unless value.is_a?(String)
+
+      value = value.strip
+      raise ValidationError, "#{key} cannot be blank" if value.empty?
+
+      value
+    end
+
+    def within_length!(value, key, max_length)
+      raise ValidationError, "#{key} must be #{max_length} characters or fewer" if value.length > max_length
+
+      value
+    end
+
+    # Steps of required_string!, not part of what this module offers callers.
+    private_class_method :non_blank_string!, :within_length!
+  end
+end

data/lib/intent_record/like_pattern.rb

@@ -0,0 +1,34 @@
+require "active_record"
+
+module IntentRecord
+  # Builds case-insensitive, literal-safe LIKE fragments. SQLite only honours the escape
+  # character when an ESCAPE clause is present, so every LIKE goes through here.
+  module LikePattern
+    ESCAPE = "ESCAPE '\\'".freeze
+
+    module_function
+
+    def contains(column)
+      "ULOWER(#{column}) LIKE ? #{ESCAPE}"
+    end
+
+    def contains_bind(term)
+      "%#{escape(term.downcase)}%"
+    end
+
+    def prefix(column)
+      "#{column} LIKE ? #{ESCAPE}"
+    end
+
+    def prefix_bind(term)
+      "#{escape(term)}%"
+    end
+
+    def escape(term)
+      ActiveRecord::Base.sanitize_sql_like(term)
+    end
+
+    # A step of the two binds, not part of what this module offers callers.
+    private_class_method :escape
+  end
+end