intent-record 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 871b5d799ddc9505ac23dbbd3bf468d243ae3c48a4c04574e9fd0fc596a579ae
-  data.tar.gz: f6370c0f8003d35971d1b717c1ca7d24632b38b9568496c22e7605838397f9d6
+  metadata.gz: b2abf7a93c2bbefd6b31f0ff8ee7f08def82e721b1166885b8701f1f003162e7
+  data.tar.gz: f5754926ff4e9b0ff7d339423196487610e816bdd164f3fc96344fb9423ef83c
 SHA512:
-  metadata.gz: 7d0ef27f3db2d4bf6616ea46f225462e778dad93c6433738d90f03e7c68fac5c2ee196681f1445a15673915d5ac449f0737d12974d01af97cdb618a4530f2759
-  data.tar.gz: 5dc2d7077843e89318b6d8d5ef7238663eb531e8ab01633a63f7a40c96f025577751e2a757f27fa64e8e1c31a81eef4ca9c8829d818fdd0f4bffbb1faa61867a
+  metadata.gz: 844a434054ae004e8bc75bb84b20e6d9a301842e860f66f715add6ac14926fa9c378d83a79d8fccabcdc97e9ff28a4b0c8fbed28194fc90b3f558ff687d6c5f5
+  data.tar.gz: 38a447b34c8fb3a2f4543c2d1c1e8d5cbb4d71669804cdd499b88ec6dfd1e48439fc26670f9e4e5bba838fa8bc4857a535a0abe6d9a8f59a2ed6008478904708

data/CHANGELOG.md

@@ -6,6 +6,16 @@ Notable changes, one section per released version. The format follows
 
 ## Unreleased
 
+## 1.1.0 - 2026-09-19
+
+### Added
+
+- `backfill`, which recovers intent records from a repository's commit history. Commits go in on stdin as JSON, `--pattern` says what a ticket reference looks like and `--uri-prefix` turns each match into a stakeholder source. Afterwards `lookup` and `by-source` answer for commits made before the tool was adopted.
+- A backfilled record says in its body that the reasoning was never recorded, so an agent can tell where the real reasoning still needs attaching.
+- Commits for one ticket are chained oldest to newest. `--order` says which end of the input is the old end and defaults to newest-first, the order `git log` prints.
+- A later pass with a different pattern adds its references to the records an earlier pass created and reports them as `linked`. A pass that finds nothing new writes nothing.
+- `--dry-run` writes nothing and reports the sources it would create and the commit subjects nothing matched.
+
 ## 1.0.0 - 2026-09-18
 
 First release.

data/README.md

@@ -1,5 +1,6 @@
 # intent-record
 
+[![Gem Version](https://badge.fury.io/rb/intent-record.svg)](https://badge.fury.io/rb/intent-record)
 [![CI](https://github.com/beatmadsen/intent-record/actions/workflows/ci.yml/badge.svg)](https://github.com/beatmadsen/intent-record/actions/workflows/ci.yml)
 
 Local records storage for the intent behind individual code changes.
@@ -63,6 +64,7 @@ JSON in on stdin where input is needed, JSON out on stdout, exit code 0 on succe
 | `by-source <uri> [--contains]` | Intents linked to a stakeholder source, plus the distinct commits across them. `--contains` matches a substring such as a ticket key |
 | `recent [--limit N]` | Newest intents first |
 | `systems` | Known VCS and stakeholder system names |
+| `backfill` | Recover intent records from a history of commit messages (JSON via stdin) |
 | `serve [--port N]` | Start the web GUI on 127.0.0.1 (default port 4791) |
 
 ### Input shape for `record` and `attach`
@@ -87,6 +89,86 @@ Options take either `--name value` or `--name=value`. Unknown options and stray
 
 An intent can be recorded before the commit exists and linked with `attach` afterwards. This also covers rebases and squashes, where the same intent ends up on a new hash. One commit can carry several intents and one intent can span several commits.
 
+## Backfilling an existing repo
+
+A repo that adopts intent-record already has years of history, and `lookup` and `by-source` answer nothing for any of it. That history is usually exactly what someone needs when they open unfamiliar code. The ticket keys are already in the commit messages, so `backfill` reads them and writes the rows `record` would have written at the time.
+
+It recovers the graph, not the reasoning. A commit message says what changed, and only the person who made the change knew why. Every backfilled record says so in its body, so an agent that later touches that code knows the real reasoning is still to be attached.
+
+Commits go in on stdin as JSON, so the tool never shells out to git and the same command works for Perforce or Mercurial:
+
+```bash
+git log --format='%H%x00%an%x00%B%x01' | ruby -rjson -e '
+  commits = $stdin.read.split("\x01").map(&:strip).reject(&:empty?).map do |entry|
+    hash, author, message = entry.split("\x00", 3)
+    { "commit" => hash, "author" => author, "message" => message.to_s.strip }
+  end
+  puts JSON.generate({ "commits" => commits })
+' > history.json
+
+intent-record backfill --system jira \
+  --pattern 'ACME-\d+' \
+  --uri-prefix https://acme.atlassian.net/browse/ \
+  --dry-run < history.json
+```
+
+Start with `--dry-run`. It writes nothing, and it reports the sources it would create and the first twenty commit subjects nothing matched, which is how you find the second convention your team used before anything is written:
+
+```json
+{"created": 128, "linked": 0, "skipped": 41, "failed": 0, "dry_run": true,
+ "sources": ["https://acme.atlassian.net/browse/ACME-42"],
+ "unmatched": ["Fix a typo in the README", "Bump version to 0.4.1"]}
+```
+
+Drop `--dry-run` to write. Each commit that names a ticket gets one record, linked to that commit and to every ticket its message names. A commit naming no ticket is not stored at all.
+
+A history may use more than one convention. Run it once per convention, each with its own system:
+
+```bash
+intent-record backfill --system github-issues \
+  --pattern '(?<![A-Za-z])#(\d+)' \
+  --uri-prefix https://github.com/acme/api/issues/ < history.json
+```
+
+A commit the first pass already recorded keeps that record and gains the references this pass finds, so a commit naming both a Jira key and a GitHub issue ends up linked to both. The report counts those as `linked` rather than `created`.
+
+Reruns stay cheap. A pass that finds nothing new to link reports the commit as skipped and writes nothing.
+
+### Options
+
+- `--system <name>` names the stakeholder system the references belong to. Required.
+- `--pattern <regex>` says what a reference looks like in a message. Required.
+- `--uri-prefix <url>` is prepended to the key to give the source uri. Without it, the whole match is the uri.
+- `--dry-run` reports what it would write and writes nothing.
+- `--order <newest-first|oldest-first>` says which end of the history the list starts at. Defaults to `newest-first`, which is what `git log` gives you.
+
+A capture group narrows what gets appended to the prefix. `ACME-\d+` with prefix `https://acme.atlassian.net/browse/` appends `ACME-42`; `ENG-(\d+)` with prefix `https://linear.app/acme/issue/ENG-` appends `7`. The source is titled with the matched text either way, so `search ENG-7` finds it.
+
+A pattern matches anywhere in the message, including inside another key. `#(\d+)` finds the `77` in an Azure `AB#77` and links it to GitHub issue 77, which is a different thing entirely. Where a history mixes conventions, anchor the loose one: `(?<![A-Za-z])#(\d+)` matches `closes #123` and `fix (#42)` while leaving `AB#77` alone.
+
+Patterns are case-sensitive, and so are the uris they build. A history that writes `ACME-42` in some commits and `acme-42` in others gives you two sources. `(?i)acme-\d+` matches both, but each uri is still built from what the commit wrote, so the two are not merged.
+
+There is no default pattern per system, because Jira and Linear keys look alike and only you know which one `ABC-123` means.
+
+### What it does with the history
+
+Each entry takes a `commit` and an optional `message`, `author` and `ref`. A commit with no message matches nothing and is skipped rather than failing the run. The ref is the branch name, scanned alongside the message for teams that put the key in the branch and never in the commit.
+
+Commits for the same ticket are chained. Each record links to the most recent earlier record for that ticket, so `show` on any one of them walks back through the others, and the chain continues across separate runs.
+
+The chain is always written oldest to newest, so the later commit builds on the earlier one. That needs to know which end of your list is the old end, which is what `--order` says. `git log` prints newest first and that is the default, so a reversed list (`git log --reverse`) needs `--order oldest-first` or every link points backwards.
+
+Each commit is written in its own transaction. One malformed hash in a history of thousands costs that commit and not the run, and the report names it:
+
+```json
+{"created": 3, "linked": 0, "skipped": 1, "failed": 1,
+ "failures": [{"commit": "bad-hash", "error": "git commit must be 40 or 64 hex characters, got \"bad-hash\""}]}
+```
+
+Those failures come back on every rerun, since a hash that is not a hash can never be written.
+
+Rewriting history changes hashes, and a rerun after a rebase links the new hashes to new records. The old ones stay, pointing at commits that no longer exist.
+
 ## Data model
 
 Commit hashes are treated as globally unique, so the store does not track which repository a commit belongs to. VCS and stakeholder system names are lowercased on the way in, and the common ones are seeded on first connect; `intent-record systems` lists them. Unknown names are added on first use.
@@ -112,7 +194,7 @@ Related-intent links may form cycles; the store records what it is told and leav
 
 ## Agent integration
 
-Any agent that can run a process and read stdout can use it. Record after each commit, `lookup` before touching unfamiliar code, `by-source` when picking up a ticket that has history.
+Any agent that can run a process and read stdout can use it. Record after each commit, `lookup` before touching unfamiliar code, `by-source` when picking up a ticket that has history, and `backfill` once when adopting the tool on a repository that already has history.
 
 For Claude Code there is a skill that says when to do each of those and what a usable `body` contains: [intent-record](https://github.com/beatmadsen/claude-skills/tree/main/skills/intent-record), in the [beatmadsen/claude-skills](https://github.com/beatmadsen/claude-skills) collection. Install it for every project you work on:
 

data/lib/intent_record/backfill/backfilled_intent.rb

@@ -0,0 +1,54 @@
+require_relative "../models/intent_record"
+
+module IntentRecord
+  module Backfill
+    # The text a backfilled record carries.
+    #
+    # A commit message says what changed, not why, and backfill cannot invent
+    # the why. So the body says plainly that the reasoning was never recorded,
+    # and the commit message follows it. The marker is a fixed string, which is
+    # what lets an agent find these records later and attach the real reasoning,
+    # and what a migration would search for if this ever becomes a column.
+    #
+    # The message is copied rather than pointed at: the store keeps no
+    # repository identity, so "see the commit" names no git anyone could open,
+    # and search, by-source and the GUI all read the store alone.
+    class BackfilledIntent
+      MARKER = "Backfilled from the commit message; the reasoning behind this change was not recorded.".freeze
+      SUMMARY_LIMIT = Models::IntentRecord::SUMMARY_MAX_LENGTH
+      BLANK_SUMMARY = "Backfilled commit with no message".freeze
+      ELLIPSIS = "...".freeze
+
+      def initialize(message:, author:)
+        @message = message.to_s
+        @author = author
+      end
+
+      def to_h
+        { "summary" => summary, "body" => body, "author" => @author }
+      end
+
+      private
+
+      # A truncated summary loses nothing: the body below keeps the subject
+      # whole.
+      def summary
+        subject.empty? ? BLANK_SUMMARY : truncated(subject)
+      end
+
+      def body
+        [MARKER, @message.strip].reject(&:empty?).join("\n\n")
+      end
+
+      def subject
+        @message.strip.lines.first.to_s.strip.gsub(/\s+/, " ")
+      end
+
+      def truncated(text)
+        return text if text.length <= SUMMARY_LIMIT
+
+        "#{text[0, SUMMARY_LIMIT - ELLIPSIS.length]}#{ELLIPSIS}"
+      end
+    end
+  end
+end

data/lib/intent_record/backfill/commit_specs.rb

@@ -0,0 +1,39 @@
+require_relative "../input_validator"
+
+module IntentRecord
+  module Backfill
+    # Reads what a backfill payload says about each commit. Every entry is
+    # checked before any is returned, so a payload with a bad entry late in the
+    # list never reaches the database. Nothing here needs one.
+    module CommitSpecs
+      module_function
+
+      def from(input)
+        entries(input).map { |entry| spec(entry) }
+      end
+
+      def entries(input)
+        InputValidator.array!(input, "commits")
+      end
+
+      def spec(entry)
+        raise ValidationError, "commits entries must be objects" unless entry.is_a?(Hash)
+
+        { commit: InputValidator.required_string!(entry, "commit"),
+          message: message(entry),
+          author: InputValidator.optional_string!(entry, "author"),
+          ref: InputValidator.optional_string!(entry, "ref") }
+      end
+
+      # An empty commit message is rare and real, and it names no ticket, so it
+      # is the same as any commit matching nothing. Refusing it would abort a
+      # whole history over one commit nobody wrote a message for. A message that
+      # is not a string is still a malformed payload rather than an absent one.
+      def message(entry)
+        InputValidator.optional_string!(entry, "message").to_s
+      end
+
+      private_class_method :entries, :spec, :message
+    end
+  end
+end

data/lib/intent_record/backfill/inspection.rb

@@ -0,0 +1,46 @@
+module IntentRecord
+  module Backfill
+    # What one dry run saw: the sources it would create and the commit subjects
+    # that matched nothing. A write run collects neither, because it is not an
+    # inspection, and reports neither.
+    class Inspection
+      # A real history has thousands of unmatched commits and nobody reads
+      # thousands of lines. Enough to recognise a convention, not enough to bury
+      # the counts.
+      UNMATCHED_SHOWN = 20
+
+      def initialize(collecting)
+        @collecting = collecting
+        @sources = []
+        @unmatched = []
+      end
+
+      def missed(subject)
+        @unmatched << subject if listable?(subject)
+        :skipped
+      end
+
+      def noted(references)
+        @sources.concat(references.map { |r| r["uri"] }) if @collecting
+      end
+
+      def to_h
+        return {} unless @collecting
+
+        { "dry_run" => true, "sources" => @sources.uniq, "unmatched" => @unmatched }
+      end
+
+      private
+
+      # A commit with no message has no subject to show, and a column of blank
+      # lines says nothing about what the pattern missed.
+      def listable?(subject)
+        @collecting && room_left? && !subject.empty?
+      end
+
+      def room_left?
+        @unmatched.size < UNMATCHED_SHOWN
+      end
+    end
+  end
+end

data/lib/intent_record/backfill/predecessor_finder.rb

@@ -0,0 +1,49 @@
+require_relative "../models/intent_record"
+require_relative "../models/stakeholder_source"
+require_relative "../stakeholder_normalizer"
+
+module IntentRecord
+  module Backfill
+    # The intent a new record for these references builds on: the most recent
+    # earlier record against the same stakeholder source.
+    #
+    # The most recent one only, because linking to every earlier commit for a
+    # ticket would say each builds on all of them, which the history does not
+    # support. Asked of the store rather than remembered within a run, so a
+    # second run continues the chain the first one left.
+    module PredecessorFinder
+      module_function
+
+      # A commit naming two tickets with the same predecessor asks for that
+      # link once, which IntentLinker's find-or-create already settles, so the
+      # duplicate is left for it rather than removed twice.
+      def for(references)
+        references.filter_map { |reference| latest_intent_for(reference) }
+      end
+
+      def latest_intent_for(reference)
+        newest(intents_against(source_id(reference)))
+      end
+
+      def intents_against(source_id)
+        Models::IntentRecord.joins(:stakeholder_sources).where(stakeholder_sources: { id: source_id })
+      end
+
+      def newest(intents)
+        intents.order(created_at: :desc, id: :desc).first&.global_id
+      end
+
+      def source_id(reference)
+        Models::StakeholderSource.joins(:stakeholder_system)
+                                 .find_by(stakeholder_systems: { name: system_name(reference) },
+                                          uri: StakeholderNormalizer.uri(reference["uri"]))&.id
+      end
+
+      def system_name(reference)
+        StakeholderNormalizer.system_name(reference["system"])
+      end
+
+      private_class_method :latest_intent_for, :intents_against, :newest, :source_id, :system_name
+    end
+  end
+end

data/lib/intent_record/backfill/reference_scanner.rb

@@ -0,0 +1,70 @@
+module IntentRecord
+  module Backfill
+    # Reads the stakeholder references a commit message names, as the
+    # `stakeholder_references` entries `record` already accepts. Nothing here
+    # reaches the database.
+    class ReferenceScanner
+      # A pattern that backtracks catastrophically would otherwise hang the
+      # command with no output. Ruby's engine memoises its way out of every
+      # such pattern this suite could construct, so the budget rarely decides
+      # anything; it is what stands between a report and a hang on an engine
+      # that gives up.
+      MATCH_TIMEOUT_SECONDS = 2.0
+
+      def initialize(system:, pattern:, uri_prefix:)
+        @system = system
+        @pattern = compiled(pattern)
+        @uri_prefix = uri_prefix.to_s
+      end
+
+      def call(message)
+        distinct(matches(message)).map { |match| reference(match) }
+      rescue Regexp::TimeoutError
+        raise ValidationError, timeout_message
+      end
+
+      private
+
+      def compiled(pattern)
+        Regexp.new(pattern, timeout: MATCH_TIMEOUT_SECONDS)
+      rescue RegexpError => e
+        raise ValidationError, "--pattern is not a valid regular expression: #{e.message}"
+      end
+
+      # Scanned as MatchData rather than with String#scan, because scan throws
+      # away the matched text as soon as the pattern has a group, and the title
+      # needs it.
+      def matches(message)
+        message.to_s.to_enum(:scan, @pattern).map { Regexp.last_match }
+               .map { |m| { uri: uri_for(key_of(m)), title: m[0] } }
+      end
+
+      # A message naming the same ticket twice, as merge commits do, asks for
+      # one source and not two. Keyed on the uri, because that is what makes a
+      # source the same source downstream.
+      def distinct(found)
+        found.uniq { |match| match[:uri] }
+      end
+
+      def reference(match)
+        { "system" => @system, "uri" => match[:uri], "title" => match[:title] }
+      end
+
+      def uri_for(key)
+        "#{@uri_prefix}#{key}"
+      end
+
+      # A pattern with a group says the uri is narrower than the text that found
+      # it: `ENG-(\d+)` finds `ENG-7` and means `7`, so the prefix can carry the
+      # project. With no group the whole match is the key.
+      def key_of(match)
+        match.size > 1 ? match[1] : match[0]
+      end
+
+      def timeout_message
+        "--pattern took longer than #{MATCH_TIMEOUT_SECONDS}s on one commit message; " \
+          "it probably backtracks catastrophically"
+      end
+    end
+  end
+end

data/lib/intent_record/backfill.rb

@@ -0,0 +1,5 @@
+require_relative "backfill/backfilled_intent"
+require_relative "backfill/commit_specs"
+require_relative "backfill/inspection"
+require_relative "backfill/predecessor_finder"
+require_relative "backfill/reference_scanner"

data/lib/intent_record/cli/dispatch.rb

@@ -10,6 +10,7 @@ require_relative "../commands/by_source"
 require_relative "../commands/recent"
 require_relative "../commands/attach"
 require_relative "../commands/systems"
+require_relative "../commands/backfill"
 
 module IntentRecord
   class CLI
@@ -67,6 +68,13 @@ module IntentRecord
         @parser.take_required_positional(label)
       end
 
+      def required_flag(name)
+        value = @parser.take_flag(name)
+        raise ValidationError, "#{name} is required" if value.nil? || value.strip.empty?
+
+        value
+      end
+
       def run_record
         finish! { Commands::Record.new.call(stdin_json) }
       end
@@ -104,6 +112,16 @@ module IntentRecord
         finish! { command.call(stdin_json) }
       end
 
+      def run_backfill
+        command = Commands::Backfill.scanning(system: required_flag("--system"),
+                                              pattern: required_flag("--pattern"),
+                                              uri_prefix: @parser.take_flag("--uri-prefix"),
+                                              dry_run: @parser.take_switch?("--dry-run"),
+                                              order: @parser.take_flag("--order") ||
+                                           Commands::Backfill::DEFAULT_ORDER)
+        finish! { command.call(stdin_json) }
+      end
+
       def run_systems
         finish! { Commands::Systems.new.call }
       end

data/lib/intent_record/cli/usage.rb

@@ -12,6 +12,7 @@ module IntentRecord
         by-source <uri> [--contains]    Intents linked to a stakeholder uri (Jira ticket, Confluence page, ...)
         recent [--limit N]              Newest intents first
         systems                         Known vcs and stakeholder system names
+        backfill [options]              Recover intents from commit messages (JSON via stdin, see below)
         serve [--port N]                Start the local web GUI
 
       Options:
@@ -19,6 +20,18 @@ module IntentRecord
         --help, -h                      Show this help
         --version                       Show version
 
+      Options for backfill:
+        --system <name>                 Stakeholder system the found references belong to (required)
+        --pattern <regex>               What a reference looks like in a message (required).
+                                        A capture group narrows what is appended to the prefix
+        --uri-prefix <url>              Prefix + key = source uri. Without it the whole match is the uri
+        --order <which-first>           newest-first (default, as git log prints) or oldest-first
+        --dry-run                       Report what it would write, write nothing
+
+      Input shape for backfill:
+        {"commits": [{"commit": "<hash>", "message": "<commit message>",
+                      "author": "...", "ref": "<branch name>"}]}
+
       Input shape for record/attach (all keys optional except summary and body on record):
         {"summary": "...", "body": "...", "author": "...",
          "commits": ["<git hash>"], "asset_versions": [{"vcs": "perforce", "external_id": "123"}],

data/lib/intent_record/commands/backfill.rb

@@ -0,0 +1,160 @@
+require_relative "record"
+require_relative "../backfill/backfilled_intent"
+require_relative "../backfill/commit_specs"
+require_relative "../backfill/inspection"
+require_relative "../backfill/predecessor_finder"
+require_relative "../backfill/reference_scanner"
+require_relative "../linkers/stakeholder_linker"
+require_relative "../stakeholder_normalizer"
+require_relative "../models/asset_version"
+require_relative "../asset_version_normalizer"
+
+module IntentRecord
+  module Commands
+    # Recovers intent records from a history of commit messages.
+    #
+    # One record per commit that names a reference, because `lookup <hash>` is
+    # meaningless if a record's summary describes forty other commits. A ticket
+    # spanning commits is what `by-source` already assembles from these.
+    #
+    # Each commit is its own transaction, so one malformed hash in a history of
+    # thousands costs that commit rather than the run. A commit that already has
+    # an intent is passed over, which is what makes a second run cheap: finding
+    # the convention you missed is the normal way to use this.
+    class Backfill
+      # `git log` prints newest first, which is what a person pipes in without
+      # thinking about it, so that is the default. The chain is written oldest
+      # to newest either way; this only says which end of the list is which.
+      ORDERS = %w[newest-first oldest-first].freeze
+      DEFAULT_ORDER = "newest-first".freeze
+
+      def self.scanning(system:, pattern:, uri_prefix: nil, **)
+        new(scanner: IntentRecord::Backfill::ReferenceScanner.new(system: system, pattern: pattern,
+                                                                  uri_prefix: uri_prefix),
+            **)
+      end
+
+      def initialize(scanner:, dry_run: false, order: DEFAULT_ORDER)
+        @scanner = scanner
+        @dry_run = dry_run
+        @order = validated_order(order)
+      end
+
+      def call(input)
+        specs = chronological(IntentRecord::Backfill::CommitSpecs.from(input))
+        seen = IntentRecord::Backfill::Inspection.new(@dry_run)
+        report(specs.map { |spec| process(spec, seen) }, seen)
+      end
+
+      private
+
+      def validated_order(order)
+        value = order.to_s.strip.downcase
+        return value if ORDERS.include?(value)
+
+        raise ValidationError, "--order must be one of #{ORDERS.join(", ")}, got #{order.inspect}"
+      end
+
+      # Each record links to the one before it, so the commits are written in
+      # the order they were made whichever end of the history the caller gave.
+      def chronological(specs)
+        @order == DEFAULT_ORDER ? specs.reverse : specs
+      end
+
+      # A commit already recorded keeps its record and gains whatever this pass
+      # found, because a second pass exists to link the convention the first
+      # pattern did not match. Skipping the commit whole would silently drop
+      # every reference in it.
+      def process(spec, seen)
+        references = @scanner.call(searchable(spec))
+        return seen.missed(subject(spec)) if references.empty?
+
+        write(spec, references, seen)
+      rescue Error => e
+        { commit: spec[:commit], error: e.message }
+      end
+
+      # Nothing this pass found is new, which is what a repeated pass looks
+      # like: neither created nor linked, and its sources are not offered as
+      # ones a dry run would add.
+      def write(spec, references, seen)
+        existing = recorded_intents(spec[:commit])
+        return :skipped if nothing_new?(existing, references)
+
+        seen.noted(references)
+        existing.empty? ? create(spec, references) : attach(existing, references)
+      end
+
+      def nothing_new?(existing, references)
+        existing.any? && already_linked?(existing, references)
+      end
+
+      def attach(existing, references)
+        return :linked if @dry_run
+
+        ActiveRecord::Base.transaction do
+          existing.each { |record| Linkers::StakeholderLinker.call(record, "stakeholder_references" => references) }
+        end
+        :linked
+      end
+
+      def already_linked?(existing, references)
+        wanted = references.map { |r| StakeholderNormalizer.uri(r["uri"]) }
+        existing.all? { |record| (wanted - record.stakeholder_sources.map(&:uri)).empty? }
+      end
+
+      def create(spec, references)
+        @dry_run ? :created : write!(spec, references)
+      end
+
+      def subject(spec)
+        spec[:message].strip.lines.first.to_s.strip
+      end
+
+      # The key is as often in the branch name as in the message, and a team
+      # that puts it there never puts it in both.
+      def searchable(spec)
+        [spec[:message], spec[:ref]].compact.join("\n")
+      end
+
+      def write!(spec, references)
+        ActiveRecord::Base.transaction { Commands::Record.new.call(payload(spec, references)) }
+        :created
+      end
+
+      def payload(spec, references)
+        intent = IntentRecord::Backfill::BackfilledIntent.new(message: spec[:message], author: spec[:author])
+        intent.to_h.merge("commits" => [spec[:commit]],
+                          "stakeholder_references" => references,
+                          "related_intent_ids" => IntentRecord::Backfill::PredecessorFinder.for(references))
+      end
+
+      # Asked of the store rather than remembered, so a commit recorded by an
+      # earlier run or by hand is treated the same.
+      def recorded_intents(commit)
+        version = Models::AssetVersion.joins(:vcs_system)
+                                      .find_by(vcs_systems: { name: "git" }, external_id: lookup_id(commit))
+        version ? version.intent_records.to_a : []
+      end
+
+      # A hash that is not a hash cannot match anything stored, and judging its
+      # shape here would refuse it before the per-commit rescue can report it.
+      def lookup_id(commit)
+        AssetVersionNormalizer.lookup_id("git", commit)
+      end
+
+      def report(outcomes, seen)
+        counts(outcomes).merge(seen.to_h)
+      end
+
+      def counts(outcomes)
+        failures = outcomes.grep(Hash)
+        { "created" => outcomes.count(:created),
+          "linked" => outcomes.count(:linked),
+          "skipped" => outcomes.count(:skipped),
+          "failed" => failures.size,
+          "failures" => failures.map { |f| { "commit" => f[:commit], "error" => f[:error] } } }
+      end
+    end
+  end
+end

data/lib/intent_record/version.rb

@@ -1,3 +1,3 @@
 module IntentRecord
-  VERSION = "1.0.0".freeze
+  VERSION = "1.1.0".freeze
 end

data/lib/intent_record.rb

@@ -25,4 +25,5 @@ require "intent_record/models/stakeholder_system"
 require "intent_record/models/stakeholder_source"
 require "intent_record/models/stakeholder_reference"
 require "intent_record/models/intent_record_link"
+require "intent_record/backfill"
 require "intent_record/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intent-record
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Erik T. Madsen
@@ -112,6 +112,12 @@ files:
 - lib/intent_record/application_record.rb
 - lib/intent_record/asset_version_normalizer.rb
 - lib/intent_record/asset_version_resolver.rb
+- lib/intent_record/backfill.rb
+- lib/intent_record/backfill/backfilled_intent.rb
+- lib/intent_record/backfill/commit_specs.rb
+- lib/intent_record/backfill/inspection.rb
+- lib/intent_record/backfill/predecessor_finder.rb
+- lib/intent_record/backfill/reference_scanner.rb
 - lib/intent_record/cli.rb
 - lib/intent_record/cli/argv_parser.rb
 - lib/intent_record/cli/dispatch.rb
@@ -119,6 +125,7 @@ files:
 - lib/intent_record/cli/streams.rb
 - lib/intent_record/cli/usage.rb
 - lib/intent_record/commands/attach.rb
+- lib/intent_record/commands/backfill.rb
 - lib/intent_record/commands/by_source.rb
 - lib/intent_record/commands/lookup.rb
 - lib/intent_record/commands/recent.rb