yuno-proofreader 0.1.0

data/lib/yuno/proofreader/store/google_gateway.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "google/apis/sheets_v4"
+require "googleauth"
+
+module Yuno
+  module Proofreader
+    module Store
+      # Talks to the Google Sheets API. It knows nothing about pages or suggestions, only about tabs, rows and cells.
+      # Rate limits and server hiccups are retried. Everything else becomes a StoreError that says what to do.
+      class GoogleGateway
+        Api = ::Google::Apis::SheetsV4
+        SCOPE = "https://www.googleapis.com/auth/spreadsheets"
+        RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+        DATETIME_PATTERN = "yyyy-mm-dd hh:mm"
+        REAL_SLEEP = ->(seconds) { sleep(seconds) }
+
+        def initialize(spreadsheet_id:, service: nil, sleeper: REAL_SLEEP, attempts: 4)
+          @id = spreadsheet_id
+          @service = service || default_service
+          @sleeper = sleeper
+          @attempts = attempts
+        end
+
+        # { "Pages" => 123, ... }: the tab titles with their ids.
+        def tabs
+          sheet = with_retries { @service.get_spreadsheet(@id, fields: "sheets.properties(sheetId,title)") }
+          sheet.sheets.to_a.to_h { |tab| [tab.properties.title, tab.properties.sheet_id] }
+        end
+
+        def add_tab(title, rows:, columns:)
+          grid = Api::GridProperties.new(row_count: rows, column_count: columns)
+          properties = Api::SheetProperties.new(title:, grid_properties: grid)
+          reply = batch([Api::Request.new(add_sheet: Api::AddSheetRequest.new(properties:))]).replies.first
+          reply.add_sheet.properties.sheet_id
+        end
+
+        def delete_tab(sheet_id)
+          batch([Api::Request.new(delete_sheet: Api::DeleteSheetRequest.new(sheet_id:))])
+        end
+
+        # All values of a tab as rows of strings. Empty trailing cells and rows are missing, as in the API.
+        def read(title)
+          values = with_retries { @service.get_spreadsheet_values(@id, quote(title)) }.values
+          values.to_a.map { |row| row.map(&:to_s) }
+        end
+
+        # Adds rows below the last row that has data, writing into the cells that are already formatted.
+        def append(title, rows)
+          body = Api::ValueRange.new(values: rows)
+          with_retries do
+            @service.append_spreadsheet_value(@id, "#{quote(title)}!A1", body,
+                                              value_input_option: "RAW", insert_data_option: "OVERWRITE")
+          end
+        end
+
+        # cells: [[row, column, value], ...] with row and column starting at 1. One request for all of them.
+        def update_cells(title, cells)
+          return if cells.empty?
+
+          data = cells.map do |row, column, value|
+            Api::ValueRange.new(range: "#{quote(title)}!#{Cells.a1(row, column)}", values: [[value]])
+          end
+          body = Api::BatchUpdateValuesRequest.new(data:, value_input_option: "RAW")
+          with_retries { @service.batch_update_values(@id, body) }
+        end
+
+        # Frozen bold header, column widths, wrapping, date and number formats and the dropdowns, in one request.
+        def format_tab(sheet_id, schema)
+          requests = [freeze_request(sheet_id), header_request(sheet_id, schema.columns.size)]
+          schema.columns.each_with_index do |column, index|
+            requests << width_request(sheet_id, index, column.width)
+            requests << body_format_request(sheet_id, index, column)
+          end
+          schema.dropdowns.each do |name, values|
+            requests << dropdown_request(sheet_id, schema.names.index(name), values)
+          end
+          batch(requests)
+        end
+
+        private
+
+        def default_service
+          service = Api::SheetsService.new
+          service.authorization = ::Google::Auth.get_application_default([SCOPE])
+          service
+        rescue StandardError => e
+          raise StoreError, "Could not load Google credentials (#{e.message}). " \
+                            "Check GOOGLE_APPLICATION_CREDENTIALS, or run scripts/check_google.rb."
+        end
+
+        def batch(requests)
+          body = Api::BatchUpdateSpreadsheetRequest.new(requests:)
+          with_retries { @service.batch_update_spreadsheet(@id, body) }
+        end
+
+        def quote(title) = "'#{title.gsub("'", "''")}'"
+
+        def with_retries
+          attempt = 0
+          begin
+            attempt += 1
+            yield
+          rescue ::Google::Apis::Error => e
+            raise explain(e) unless retryable?(e) && attempt < @attempts
+
+            @sleeper.call(2**attempt)
+            retry
+          rescue ::Signet::AuthorizationError => e
+            raise StoreError,
+                  "Google rejected the credentials (#{e.message}). Log in again, see scripts/check_google.rb."
+          end
+        end
+
+        def status_of(error) = error.respond_to?(:status_code) ? error.status_code : nil
+
+        # Network trouble has no status. Rate limits and server errors are worth another try.
+        def retryable?(error)
+          status = status_of(error)
+          status.nil? || RETRY_STATUSES.include?(status)
+        end
+
+        def explain(error)
+          StoreError.new("Google Sheets: #{reason(status_of(error), error)}")
+        end
+
+        def reason(status, error)
+          case status
+          when 403
+            "no access to the spreadsheet. Share it as Editor with the account you use, " \
+            "and check that the Sheets API is enabled."
+          when 404 then "spreadsheet not found. Check SPREADSHEET_ID."
+          when 400 then bad_request(error)
+          else error.message
+          end
+        end
+
+        def bad_request(error)
+          return error.message unless error.message.include?("Unable to parse range")
+
+          "tab not found. Run: yuno-proofreader prepare"
+        end
+
+        def grid(sheet_id, **bounds) = Api::GridRange.new(sheet_id:, **bounds)
+
+        def freeze_request(sheet_id)
+          properties = Api::SheetProperties.new(sheet_id:,
+                                                grid_properties: Api::GridProperties.new(frozen_row_count: 1))
+          Api::Request.new(update_sheet_properties: Api::UpdateSheetPropertiesRequest.new(
+            properties:, fields: "gridProperties.frozenRowCount"
+          ))
+        end
+
+        def header_request(sheet_id, columns)
+          bold = Api::CellFormat.new(text_format: Api::TextFormat.new(bold: true))
+          range = grid(sheet_id, start_row_index: 0, end_row_index: 1, start_column_index: 0, end_column_index: columns)
+          Api::Request.new(repeat_cell: Api::RepeatCellRequest.new(
+            range:, cell: Api::CellData.new(user_entered_format: bold), fields: "userEnteredFormat.textFormat.bold"
+          ))
+        end
+
+        def width_request(sheet_id, index, pixels)
+          Api::Request.new(update_dimension_properties: Api::UpdateDimensionPropertiesRequest.new(
+            range: Api::DimensionRange.new(sheet_id:, dimension: "COLUMNS", start_index: index, end_index: index + 1),
+            properties: Api::DimensionProperties.new(pixel_size: pixels), fields: "pixelSize"
+          ))
+        end
+
+        def body_format_request(sheet_id, index, column)
+          format = Api::CellFormat.new(vertical_alignment: "TOP")
+          format.wrap_strategy = "WRAP" if column.wrap
+          format.number_format = number_format(column.type)
+          Api::Request.new(repeat_cell: Api::RepeatCellRequest.new(
+            range: grid(sheet_id, start_row_index: 1, start_column_index: index, end_column_index: index + 1),
+            cell: Api::CellData.new(user_entered_format: format),
+            fields: "userEnteredFormat(verticalAlignment,wrapStrategy,numberFormat)"
+          ))
+        end
+
+        def number_format(type)
+          case type
+          when :datetime then Api::NumberFormat.new(type: "DATE_TIME", pattern: DATETIME_PATTERN)
+          when :integer then Api::NumberFormat.new(type: "NUMBER", pattern: "0")
+          end
+        end
+
+        def dropdown_request(sheet_id, index, values)
+          choices = values.map { |value| Api::ConditionValue.new(user_entered_value: value) }
+          rule = Api::DataValidationRule.new(condition: Api::BooleanCondition.new(type: "ONE_OF_LIST", values: choices),
+                                             strict: true, show_custom_ui: true)
+          Api::Request.new(set_data_validation: Api::SetDataValidationRequest.new(
+            range: grid(sheet_id, start_row_index: 1, start_column_index: index, end_column_index: index + 1), rule:
+          ))
+        end
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/store/memory.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Store
+      # Keeps the pages, suggestions and analysis in memory, with the same behavior as the Google Sheet store.
+      # Used in tests, and handy for dry runs.
+      class Memory
+        IMPORTANCE_FIELDS = %i[importance tier importance_notes analyzed_at].freeze
+
+        def initialize(site)
+          @languages = site.languages
+          @pages = []
+          @suggestions = []
+          @analysis = []
+        end
+
+        def prepare = ["The in-memory store needs no preparation."]
+
+        def pages = @pages.dup
+
+        def add_pages(pages)
+          pages.each do |page|
+            urls = page.urls.slice(*@languages).reject { |_code, url| url.to_s.empty? }
+            @pages << PageRecord.new(row: next_row(@pages), name: page.name, urls:, last_audited: nil,
+                                     fingerprint: "", note: page.notes.join("; "), sitemap_lastmod: page.lastmod)
+          end
+          pages.size
+        end
+
+        def record_audit(record, fingerprint:, at:)
+          change(@pages, record.row) { |page| page.with(last_audited: at, fingerprint:) }
+        end
+
+        # Keeps importance and tier, the fields a page record has. Notes and the time are accepted and left out.
+        def record_importance(updates)
+          updates.each do |row, changes|
+            fields = changes.transform_keys(&:to_sym)
+            unknown = fields.keys - IMPORTANCE_FIELDS
+            raise StoreError, "Unknown field(s): #{unknown.join(', ')}" unless unknown.empty?
+
+            change(@pages, row) { |page| page.with(**fields.slice(:importance, :tier)) }
+          end
+        end
+
+        def suggestions(page_name = nil)
+          page_name ? @suggestions.select { |record| record.page == page_name } : @suggestions.dup
+        end
+
+        def add_suggestions(records)
+          records.each { |record| @suggestions << record.with(row: next_row(@suggestions)) }
+          records.size
+        end
+
+        # updates: { row => { field => value } }
+        def update_suggestions(updates)
+          updates.each do |row, changes|
+            fields = validated(changes)
+            change(@suggestions, row) { |record| record.with(**fields) }
+          end
+        end
+
+        def analysis_rows = @analysis.each_with_index.map { |values, index| { row: index + 2, **values } }
+
+        def replace_analysis(rows)
+          @analysis = rows.map { |values| values.transform_keys(&:to_sym) }
+        end
+
+        private
+
+        def next_row(list) = list.size + 2
+
+        def change(list, row)
+          index = row.to_i - 2
+          raise StoreError, "There is no row #{row}" unless index >= 0 && list[index]
+
+          list[index] = yield(list[index])
+        end
+
+        def validated(changes)
+          fields = changes.transform_keys(&:to_sym)
+          unknown = fields.keys - (SuggestionRecord.members - [:row])
+          raise StoreError, "Unknown field(s): #{unknown.join(', ')}" unless unknown.empty?
+
+          fields
+        end
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/store/records.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Store
+      # A row of the Pages tab. urls holds the address per language the page exists in. importance and tier are
+      # written by the analysis, and boost is what a person typed in.
+      PageRecord = Data.define(:row, :name, :urls, :last_audited, :fingerprint, :note, :sitemap_lastmod, :importance,
+                               :tier, :boost) do
+        def initialize(importance: nil, tier: nil, boost: nil, **fields) = super
+
+        # The address that identifies the page: its default-language address, or the first one it has.
+        def key(default_language) = urls[default_language] || urls.values.first
+      end
+
+      SUGGESTION_DEFAULTS = {
+        row: nil, timestamp: nil, page: "", language: "", category: "", effort: "", approximate_place: "",
+        original: "", suggested: "", reason: "", verified: "", status: "open", found_by: "",
+        last_seen: nil, amount_seen: 1
+      }.freeze
+
+      # A row of the Suggestions tab. Use build to leave out the fields you do not need.
+      SuggestionRecord = Data.define(*SUGGESTION_DEFAULTS.keys) do
+        def self.build(**fields) = new(**SUGGESTION_DEFAULTS, **fields)
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/store/schema.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Store
+      STATUSES = ["open", "on staging", "done", "rejected"].freeze
+
+      # One column of a tab. type is :text, :datetime (a sheet date, stored as a serial number), :integer or
+      # :number (a decimal number).
+      Column = Data.define(:name, :type, :width, :wrap) do
+        def initialize(name:, type: :text, width: 120, wrap: false) = super
+      end
+
+      # What a tab looks like: its columns, the ones that must exist, the dropdown columns and the grid size.
+      TabSchema = Data.define(:title, :columns, :required, :dropdowns, :rows) do
+        def names = columns.map(&:name)
+
+        def column(name) = columns.find { |column| column.name == name }
+
+        # The columns of the schema that a header row lacks, required or not.
+        def absent(header) = names - normalized(header)
+
+        def check!(header)
+          missing = required - normalized(header)
+          return if missing.empty?
+
+          raise StoreError, "Tab #{title} is missing the column(s) #{missing.join(', ')}. Add them to the header row " \
+                            "with exactly these names, or delete the tab and run prepare again."
+        end
+
+        def normalized(header) = header.map { |name| name.to_s.strip.downcase }
+      end
+
+      # The tabs the tool works with.
+      module Schema
+        SUGGESTION_COLUMNS = [
+          Column.new(name: "timestamp", type: :datetime, width: 150),
+          Column.new(name: "page", width: 180),
+          Column.new(name: "language", width: 80),
+          Column.new(name: "category", width: 100),
+          Column.new(name: "effort", width: 80),
+          Column.new(name: "approximate_place", width: 220, wrap: true),
+          Column.new(name: "original", width: 300, wrap: true),
+          Column.new(name: "suggested", width: 300, wrap: true),
+          Column.new(name: "reason", width: 300, wrap: true),
+          Column.new(name: "verified", width: 80),
+          Column.new(name: "status", width: 100),
+          Column.new(name: "found_by", width: 110),
+          Column.new(name: "last_seen", type: :datetime, width: 150),
+          Column.new(name: "amount_seen", type: :integer, width: 90)
+        ].freeze
+        SUGGESTION_REQUIRED = %w[page language category effort original suggested reason verified status].freeze
+
+        # Written by the analysis, except boost, which a person fills in.
+        IMPORTANCE_COLUMNS = [
+          Column.new(name: "importance", type: :integer, width: 100),
+          Column.new(name: "tier", type: :integer, width: 60),
+          Column.new(name: "importance_notes", width: 320, wrap: true),
+          Column.new(name: "analyzed_at", type: :datetime, width: 150),
+          Column.new(name: "boost", type: :number, width: 70)
+        ].freeze
+
+        ANALYSIS_COLUMNS = [
+          Column.new(name: "page_name", width: 220),
+          Column.new(name: "address", width: 300),
+          Column.new(name: "importance", type: :integer, width: 100),
+          Column.new(name: "tier", type: :integer, width: 60),
+          Column.new(name: "reach", type: :number, width: 80),
+          Column.new(name: "presence", type: :number, width: 80),
+          Column.new(name: "mentions", type: :number, width: 80),
+          Column.new(name: "freshness", type: :number, width: 80),
+          Column.new(name: "changed", width: 100),
+          Column.new(name: "route", width: 260, wrap: true),
+          Column.new(name: "ai_value", type: :integer, width: 80),
+          Column.new(name: "ai_kind", width: 100),
+          Column.new(name: "ai_place", width: 180),
+          Column.new(name: "ai_certainty", width: 90),
+          Column.new(name: "ai_reason", width: 320, wrap: true),
+          Column.new(name: "ai_spread", type: :integer, width: 80),
+          Column.new(name: "analyzed_at", type: :datetime, width: 150)
+        ].freeze
+
+        module_function
+
+        def pages(languages)
+          urls = languages.map { |code| Column.new(name: "#{code}_url", width: 320) }
+          columns = [Column.new(name: "page_name", width: 220), *urls,
+                     Column.new(name: "last_audited", type: :datetime, width: 150),
+                     Column.new(name: "fingerprint", width: 130),
+                     Column.new(name: "note", width: 200),
+                     Column.new(name: "sitemap_lastmod", width: 130),
+                     *IMPORTANCE_COLUMNS]
+          required = ["page_name", *urls.map(&:name), "last_audited"]
+          TabSchema.new(title: "Pages", columns:, required:, dropdowns: {}, rows: 1_000)
+        end
+
+        def suggestions
+          TabSchema.new(title: "Suggestions", columns: SUGGESTION_COLUMNS, required: SUGGESTION_REQUIRED,
+                        dropdowns: { "status" => STATUSES }, rows: 5_000)
+        end
+
+        def analysis
+          TabSchema.new(title: "Analysis", columns: ANALYSIS_COLUMNS, required: %w[page_name address], dropdowns: {},
+                        rows: 1_000)
+        end
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/store/sheets.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Store
+      # Keeps the pages, the suggestions and the analysis in a Google Sheet. Columns are found by their header
+      # names, so the order of the columns does not matter and extra columns are left alone. All access goes through
+      # a gateway.
+      class Sheets
+        Table = Data.define(:index, :rows, :width)
+        IMPORTANCE = %w[importance tier importance_notes analyzed_at].freeze
+
+        def self.connect(config, site)
+          require_relative "google_gateway"
+          new(GoogleGateway.new(spreadsheet_id: config.spreadsheet_id), site)
+        end
+
+        def initialize(gateway, site)
+          @gateway = gateway
+          @languages = site.languages
+          @pages_schema = Schema.pages(@languages)
+          @suggestions_schema = Schema.suggestions
+          @analysis_schema = Schema.analysis
+        end
+
+        # Creates the tabs that are missing and returns a line for each thing it did or found.
+        def prepare = TabSetup.new(@gateway, [@pages_schema, @suggestions_schema, @analysis_schema]).call
+
+        def pages
+          table = read_table(@pages_schema)
+          data_rows(table).map { |cells, row| page_record(table, cells, row) }
+        end
+
+        # pages: Sitemap::Page objects. Returns how many were added.
+        def add_pages(pages)
+          return 0 if pages.empty?
+
+          table = read_table(@pages_schema)
+          @gateway.append(@pages_schema.title, pages.map { |page| build_row(table, @pages_schema, page_values(page)) })
+          pages.size
+        end
+
+        def record_audit(record, fingerprint:, at:)
+          table = read_table(@pages_schema)
+          change_rows(table, @pages_schema, { record.row => { last_audited: at, fingerprint: } })
+        end
+
+        # updates: { row => { importance:, tier:, importance_notes:, analyzed_at: } }, sent in one request. The Pages
+        # tab must have those columns.
+        def record_importance(updates)
+          return if updates.empty?
+
+          table = read_table(@pages_schema)
+          missing = IMPORTANCE - table.index.keys
+          unless missing.empty?
+            raise StoreError, "Tab Pages lacks the column(s) #{missing.join(', ')}. Type them at the end of its " \
+                              "header row, with exactly these names. Run prepare to see every column it lacks."
+          end
+
+          change_rows(table, @pages_schema, updates)
+        end
+
+        def suggestions(page_name = nil)
+          table = read_table(@suggestions_schema)
+          records = data_rows(table).map { |cells, row| suggestion_record(table, cells, row) }
+          page_name ? records.select { |record| record.page == page_name } : records
+        end
+
+        def add_suggestions(records)
+          return 0 if records.empty?
+
+          table = read_table(@suggestions_schema)
+          rows = records.map { |record| build_row(table, @suggestions_schema, record.to_h.except(:row)) }
+          @gateway.append(@suggestions_schema.title, rows)
+          records.size
+        end
+
+        # updates: { row => { field => value } }. All changes are sent in one request.
+        def update_suggestions(updates)
+          return if updates.empty?
+
+          change_rows(read_table(@suggestions_schema), @suggestions_schema, updates)
+        end
+
+        # The rows of the Analysis tab as hashes by column name, each with its row number.
+        def analysis_rows
+          table = read_table(@analysis_schema)
+          data_rows(table).map { |cells, row| { row:, **attributes(table, @analysis_schema, cells) } }
+        end
+
+        # rows: hashes by column name. The rows the tab already has are overwritten in place, the rest are appended,
+        # and rows left over from a longer earlier run are emptied.
+        def replace_analysis(rows)
+          table = read_table(@analysis_schema)
+          built = rows.map { |values| build_row(table, @analysis_schema, values) }
+          height = table.rows.size
+          blank = Array.new(table.width, "")
+          kept = (0...height).map { |index| built[index] || blank }
+          @gateway.update_cells(@analysis_schema.title,
+                                kept.each_with_index.flat_map { |values, index| row_cells(index + 2, values) })
+          @gateway.append(@analysis_schema.title, built.drop(height)) if built.size > height
+        end
+
+        private
+
+        # ---- reading ----
+
+        def read_table(schema)
+          values = @gateway.read(schema.title)
+          header = values.first.to_a.map { |name| name.to_s.strip.downcase }
+          schema.check!(header)
+          Table.new(index: header.each_with_index.to_h, rows: values.drop(1), width: header.size)
+        end
+
+        # The data rows with their row numbers in the sheet. Rows with nothing in them are skipped.
+        def data_rows(table)
+          table.rows.each_with_index.filter_map do |cells, index|
+            [cells, index + 2] unless cells.all? { |cell| cell.to_s.strip.empty? }
+          end
+        end
+
+        def attributes(table, schema, cells)
+          schema.columns.to_h do |column|
+            position = table.index[column.name]
+            [column.name.to_sym, Cells.from_cell(position ? cells[position] : "", column.type)]
+          end
+        end
+
+        def page_record(table, cells, row)
+          attrs = attributes(table, @pages_schema, cells)
+          urls = @languages.to_h { |code| [code, attrs[:"#{code}_url"].strip] }.reject { |_code, url| url.empty? }
+          PageRecord.new(row:, name: attrs[:page_name], urls:, last_audited: attrs[:last_audited],
+                         fingerprint: attrs[:fingerprint], note: attrs[:note], sitemap_lastmod: attrs[:sitemap_lastmod],
+                         importance: attrs[:importance], tier: attrs[:tier], boost: attrs[:boost])
+        end
+
+        def suggestion_record(table, cells, row)
+          SuggestionRecord.build(row:, **attributes(table, @suggestions_schema, cells))
+        end
+
+        # ---- writing ----
+
+        def page_values(page)
+          values = { "page_name" => page.name, "note" => page.notes.join("; "), "sitemap_lastmod" => page.lastmod }
+          @languages.each { |code| values["#{code}_url"] = page.urls[code] }
+          values
+        end
+
+        # A row as wide as the header, with each value in the column of its name. Columns the sheet lacks are skipped.
+        def build_row(table, schema, values)
+          cells = Array.new(table.width, "")
+          values.each do |name, value|
+            position = table.index[name.to_s]
+            cells[position] = Cells.to_cell(value, schema.column(name.to_s).type) if position
+          end
+          cells
+        end
+
+        def change_rows(table, schema, changes)
+          last_row = table.rows.size + 1
+          cells = changes.flat_map do |row, values|
+            raise StoreError, "There is no row #{row} in #{schema.title}" unless row.to_i.between?(2, last_row)
+
+            changed_cells(table, schema, row, values)
+          end
+          @gateway.update_cells(schema.title, cells)
+        end
+
+        def changed_cells(table, schema, row, values)
+          values.filter_map do |name, value|
+            column = schema.column(name.to_s)
+            raise StoreError, "Unknown field #{name} for #{schema.title}" unless column
+
+            position = table.index[column.name]
+            [row, position + 1, Cells.to_cell(value, column.type)] if position
+          end
+        end
+
+        def row_cells(row, values) = values.each_with_index.map { |value, index| [row, index + 1, value] }
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/store/tab_setup.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    module Store
+      # Sets up the tabs of the sheet: creates the ones that are missing, sets up empty ones, checks the others and
+      # names the columns they lack, and removes an empty default tab. Returns a line for each thing it did or found.
+      class TabSetup
+        DEFAULT_TABS = %w[Sheet1 Tabellenblatt1].freeze
+
+        def initialize(gateway, schemas)
+          @gateway = gateway
+          @schemas = schemas
+        end
+
+        def call
+          tabs = @gateway.tabs
+          @schemas.flat_map { |schema| prepare_tab(schema, tabs) } + remove_default_tab
+        end
+
+        private
+
+        def prepare_tab(schema, tabs)
+          title = schema.title
+          return create_tab(schema) unless tabs.key?(title)
+
+          header = @gateway.read(title).first.to_a
+          return fill_tab(schema, tabs[title]) if header.empty?
+
+          schema.check!(header)
+          existing(schema, header)
+        end
+
+        # A tab that exists keeps its columns as they are. Columns a newer version of the tool added are named, so
+        # they can be typed at the end of the header row.
+        def existing(schema, header)
+          absent = schema.absent(header)
+          return ["Tab #{schema.title} already exists."] if absent.empty?
+
+          ["Tab #{schema.title} already exists, but lacks the column(s) #{absent.join(', ')}. Type them at the end " \
+           "of its header row, with exactly these names."]
+        end
+
+        def create_tab(schema)
+          sheet_id = @gateway.add_tab(schema.title, rows: schema.rows, columns: schema.columns.size)
+          write_header(schema)
+          @gateway.format_tab(sheet_id, schema)
+          ["Created tab #{schema.title}."]
+        end
+
+        def fill_tab(schema, sheet_id)
+          write_header(schema)
+          @gateway.format_tab(sheet_id, schema)
+          ["Set up the empty tab #{schema.title}."]
+        end
+
+        def write_header(schema)
+          cells = schema.names.each_with_index.map { |name, index| [1, index + 1, name] }
+          @gateway.update_cells(schema.title, cells)
+        end
+
+        def remove_default_tab
+          ours = @schemas.map(&:title)
+          @gateway.tabs.filter_map do |title, sheet_id|
+            next unless DEFAULT_TABS.include?(title) && !ours.include?(title) && @gateway.read(title).empty?
+
+            @gateway.delete_tab(sheet_id)
+            "Removed the empty tab #{title}."
+          end
+        end
+      end
+    end
+  end
+end