notion_publish 0.1.0

data/lib/notion_publish/resolver.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "client"
+require_relative "errors"
+require_relative "reference"
+require_relative "sharing"
+require_relative "target"
+
+module NotionPublish
+  # Turns --parent and --database into a Target.
+  class Resolver
+    class Unreachable < Error; end
+    class Ambiguous < Error; end
+    class NotNamed < Error; end
+    class WrongKind < Error; end
+
+    def initialize(client)
+      @client = client
+    end
+
+    # --parent takes an ID, a URL, or a database name. Nothing else has to be
+    # said: an ID and a URL are recognisable by shape, and anything else is a
+    # name. A user cannot tell a page ID from a database ID by looking at it --
+    # both are /p/<hex> -- so making them declare the type would be asking for
+    # a guess.
+    def resolve(input)
+      if Reference.reference?(input)
+        resolve_reference(input)
+      else
+        resolve_database_name(input)
+      end
+    end
+
+    # Identify first, fetch second. A page is also a block, so /v1/blocks says
+    # what an ID names in one call and hands back the title with it. That beats
+    # probing typed endpoints in turn, which took up to three calls and had to
+    # treat /v1/databases' 400 ("is a page, not a database") as a miss.
+    def resolve_reference(input)
+      ref = Reference.parse(input)
+      target = identify(ref.uuid)
+      return target if target
+
+      raise Unreachable, Sharing.unreachable(
+        id: ref.uuid,
+        title: ref.slug_title,
+        connection_name: @client.connection_name
+      )
+    end
+
+    # Notion's search is fuzzy and relevance-ranked, so a single hit does not
+    # mean an exact match: querying "a" returns three of thirteen data sources.
+    # Publishing into a database the user did not name is silent and annoying to
+    # undo, so only an exact title match is accepted.
+    def resolve_database_name(name)
+      candidates = search_data_sources(name)
+      exact = candidates.select { |c| c[:title].casecmp?(name.strip) }
+
+      case exact.length
+      when 1 then to_data_source_target(exact.first)
+      when 0 then raise NotNamed, no_exact_match_message(name, candidates)
+      else raise Ambiguous, ambiguous_message(name, exact)
+      end
+    end
+
+    private
+
+    def identify(uuid)
+      block = fetch_block(uuid)
+
+      case block && block["type"]
+      when "child_page"
+        Target.new(kind: :page, id: uuid, title: block.dig("child_page", "title"),
+                   database_id: nil, inline: false)
+      when "child_database"
+        database_target(uuid)
+      when nil
+        # Data sources are not blocks, so a 404 here means either a data source
+        # or something we cannot reach. Only the typed call tells them apart.
+        data_source_target(uuid)
+      else
+        raise WrongKind, "#{uuid} is a #{block['type'].tr('_', ' ')} block, not a page or database."
+      end
+    end
+
+    def fetch_block(uuid)
+      @client.get("/v1/blocks/#{uuid}")
+    rescue ApiError => e
+      raise unless e.not_found?
+
+      nil
+    end
+
+    # A database is a container; the schema and the rows live on its data
+    # sources. One source resolves cleanly. Two or more is genuinely ambiguous
+    # and Notion itself rejects a bare database parent in that case, so we stop
+    # and make the user choose rather than guessing.
+    def database_target(uuid)
+      body = @client.get("/v1/databases/#{uuid}")
+      sources = body["data_sources"] || []
+      db_title = plain_title(body["title"])
+
+      case sources.length
+      when 1
+        Target.new(
+          kind: :data_source,
+          id: sources.first["id"],
+          title: sources.first["name"].to_s.empty? ? db_title : sources.first["name"],
+          database_id: body["id"],
+          inline: body["is_inline"] == true
+        )
+      when 0
+        raise Unreachable, "Database #{db_title.inspect} (#{uuid}) has no data sources."
+      else
+        raise Ambiguous, multi_source_message(db_title, uuid, sources)
+      end
+    end
+
+    def data_source_target(uuid)
+      body = @client.get("/v1/data_sources/#{uuid}")
+      Target.new(
+        kind: :data_source,
+        id: body["id"],
+        title: plain_title(body["title"]),
+        database_id: body.dig("parent", "database_id"),
+        # Only the database object carries is_inline. A data source whose
+        # parent is a block_id is not necessarily inline: a full-page database
+        # can have a block_id parent and is_inline false.
+        inline: nil
+      )
+    rescue ApiError => e
+      raise unless e.not_found?
+
+      nil
+    end
+
+    # Every data source the search returns, across pages. Search ranks by
+    # relevance, so an exact match is not guaranteed to be on the first page.
+    def search_data_sources(name)
+      search_results(name.to_s.strip).map do |result|
+        {
+          id: result["id"],
+          title: plain_title(result["title"]).to_s,
+          database_id: result.dig("parent", "database_id"),
+          inline: nil
+        }
+      end
+    end
+
+    def search_results(query)
+      results = []
+      cursor = nil
+      loop do
+        body = @client.post("/v1/search", {
+          "query" => query, "page_size" => Client::PAGE_SIZE, "start_cursor" => cursor,
+          "filter" => { "property" => "object", "value" => "data_source" }
+        }.compact)
+        results.concat(body["results"] || [])
+        cursor = body["next_cursor"]
+        break unless body["has_more"] && cursor
+      end
+      results
+    end
+
+    def to_data_source_target(hit)
+      Target.new(
+        kind: :data_source,
+        id: hit[:id],
+        title: hit[:title],
+        database_id: hit[:database_id],
+        inline: hit[:inline]
+      )
+    end
+
+    def plain_title(rich_text)
+      return nil unless rich_text.is_a?(Array)
+
+      rich_text.map { |chunk| chunk["plain_text"] }.join
+    end
+
+    def no_exact_match_message(name, candidates)
+      lines = ["No database is named #{name.inspect}.", ""]
+      if candidates.empty?
+        lines << "Nothing similar is shared with the #{@client.connection_name.inspect} connection."
+        lines << Sharing.instructions(nil)
+      else
+        lines << "Similar names that are shared with this connection:"
+        candidates.first(10).each do |c|
+          shown = c[:title].empty? ? "(untitled)" : c[:title]
+          lines << "  #{shown}  --parent #{c[:id]}"
+        end
+        lines << ""
+        lines << "Names must match exactly. Use --parent with an ID to be unambiguous."
+      end
+      lines.join("\n")
+    end
+
+    def ambiguous_message(name, matches)
+      lines = ["More than one database is named #{name.inspect}:", ""]
+      matches.each { |m| lines << "  --parent #{m[:id]}" }
+      lines << ""
+      lines << "Use --parent with the ID you want."
+      lines.join("\n")
+    end
+
+    def multi_source_message(db_title, uuid, sources)
+      lines = ["Database #{db_title.inspect} (#{uuid}) has #{sources.length} data sources:", ""]
+      sources.each do |s|
+        name = s["name"].to_s.empty? ? "(untitled)" : s["name"]
+        lines << "  #{name}  --parent #{s['id']}"
+      end
+      lines << ""
+      lines << "Point --parent at one of them."
+      lines.join("\n")
+    end
+  end
+end

data/lib/notion_publish/schema.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+require_relative "errors"
+require_relative "reference"
+
+module NotionPublish
+  # The property definitions of a publishing target, and the rules for turning
+  # command-line strings into Notion property values.
+  #
+  # Because the schema is fetched anyway, the CLI syntax carries no type or
+  # arity information: --property 'Due Date=2026-09-15' is a date because the
+  # schema says so, and repeating --property is a list only where the property
+  # can hold one.
+  class Schema
+    # Notion computes these. Writing them is an error, so say so plainly rather
+    # than letting the API reject the whole request.
+    COMPUTED = %w[created_time created_by last_edited_time last_edited_by formula rollup unique_id].freeze
+
+    # Everything else holds exactly one value.
+    MULTI_VALUED = %w[multi_select people relation].freeze
+
+    OPTION_TYPES = %w[select status multi_select].freeze
+
+    attr_reader :properties
+
+    def self.for(client, target)
+      return new({}, page: true) if target.page?
+
+      body = client.get("/v1/data_sources/#{target.id}")
+      new(body["properties"] || {})
+    end
+
+    def initialize(properties, page: false)
+      @properties = properties
+      @page = page
+    end
+
+    def page? = @page
+
+    def title_key
+      return "title" if page?
+
+      key, = properties.find { |_, definition| definition["type"] == "title" }
+      key or raise Error, "This data source has no title property."
+    end
+
+    def names = properties.keys
+
+    # Property names are matched case-insensitively, because nobody remembers
+    # whether it is "Due Date" or "Due date".
+    def lookup(name)
+      wanted = name.to_s.strip
+      properties.find { |key, _| key.casecmp?(wanted) }
+    end
+
+    def type_of(name)
+      _, definition = lookup(name)
+      definition && definition["type"]
+    end
+
+    def multi_valued?(name) = MULTI_VALUED.include?(type_of(name))
+
+    # Returns [notion_key, value_payload] ready to drop into a page's
+    # properties. +values+ is always an array; arity is checked here.
+    def build(name, values, users: nil)
+      if page?
+        raise Error, page_parent_message(name) unless name.casecmp?("title")
+
+        return ["title", text_payload("title", values.first.to_s)]
+      end
+
+      key, definition = lookup(name)
+      raise Error, unknown_property_message(name) unless key
+
+      type = definition["type"]
+      raise Error, computed_message(key, type) if COMPUTED.include?(type)
+
+      return [key, empty_payload(type)] if cleared?(values)
+      raise Error, arity_message(key, type, values) if values.length > 1 && !MULTI_VALUED.include?(type)
+
+      [key, payload(key, definition, type, values, users)]
+    end
+
+    private
+
+    def cleared?(values) = values.length == 1 && values.first.to_s.empty?
+
+    # One branch per property type Notion defines; splitting it would only scatter the table.
+    def payload(key, definition, type, values, users) # rubocop:disable Metrics/CyclomaticComplexity
+      case type
+      when "title", "rich_text" then text_payload(type, values.first.to_s)
+      when "select", "status" then { type => { "name" => option!(key, definition, type, values.first) } }
+      when "multi_select"
+        { "multi_select" => values.map { |v| { "name" => option!(key, definition, type, v) } } }
+      when "people" then { "people" => values.map { |v| { "object" => "user", "id" => user!(v, users) } } }
+      when "relation" then { "relation" => values.map { |v| { "id" => Reference.parse(v).uuid } } }
+      when "date" then { "date" => date_payload(key, values.first) }
+      when "checkbox" then { "checkbox" => checkbox!(key, values.first) }
+      when "number" then { "number" => number!(key, values.first) }
+      when "url", "email", "phone_number" then { type => values.first.to_s }
+      when "files"
+        raise Error, "#{key} is a files property. notion-publish cannot set file properties yet."
+      else
+        raise Error, "#{key} is a #{type} property, which notion-publish cannot set."
+      end
+    end
+
+    def text_payload(type, string)
+      { type => [{ "type" => "text", "text" => { "content" => string } }] }
+    end
+
+    def empty_payload(type)
+      case type
+      when "title", "rich_text" then { type => [] }
+      when "multi_select" then { "multi_select" => [] }
+      when "people" then { "people" => [] }
+      when "relation" then { "relation" => [] }
+      when "checkbox" then { "checkbox" => false }
+      else { type => nil }
+      end
+    end
+
+    # Notion *creates* an unrecognised select option instead of rejecting it, so
+    # a typo would silently grow the schema. Match against the existing options
+    # and return their canonical spelling.
+    def option!(key, definition, type, value)
+      wanted = value.to_s.strip
+      options = definition.dig(type, "options") || []
+      match = options.find { |o| o["name"].casecmp?(wanted) }
+      return match["name"] if match
+
+      raise Error, unknown_option_message(key, wanted, options.map { |o| o["name"] })
+    end
+
+    # A people value may be a user ID or a name, which needs the workspace's
+    # user list to resolve. That list is fetched lazily, only when needed.
+    def user!(value, users)
+      candidate = value.to_s.strip
+      return candidate if candidate.match?(Reference::BARE_ID)
+      raise Error, "Cannot resolve #{candidate.inspect} to a user." unless users
+
+      users.resolve(candidate)
+    end
+
+    def date_payload(key, value)
+      start, finish = value.to_s.split("..", 2).map(&:strip)
+      raise Error, "#{key} needs a date, got an empty value." if start.to_s.empty?
+
+      payload = { "start" => start }
+      payload["end"] = finish if finish && !finish.empty?
+      payload
+    end
+
+    def checkbox!(key, value)
+      case value.to_s.strip.downcase
+      when "true", "yes", "y", "1", "checked" then true
+      when "false", "no", "n", "0", "unchecked" then false
+      else raise Error, "#{key} is a checkbox. Use true or false, not #{value.to_s.inspect}."
+      end
+    end
+
+    def number!(key, value)
+      string = value.to_s.strip
+      return Integer(string) if string.match?(/\A-?\d+\z/)
+
+      Float(string)
+    rescue ArgumentError, TypeError
+      raise Error, "#{key} is a number. #{value.to_s.inspect} is not one."
+    end
+
+    def unknown_property_message(name)
+      close = DidYouMean::SpellChecker.new(dictionary: names).correct(name.to_s)
+      lines = ["There is no property named #{name.to_s.inspect}."]
+      lines << "" << "Did you mean: #{close.join(', ')}" unless close.empty?
+      lines << "" << "Run `notion-publish properties` to see the schema."
+      lines.join("\n")
+    end
+
+    def unknown_option_message(key, value, options)
+      <<~MSG.strip
+        #{key} has no option named #{value.inspect}.
+
+        Options are: #{options.join(' | ')}
+
+        Notion would create a new option rather than reject this, so
+        notion-publish refuses it. Add the option in Notion first.
+      MSG
+    end
+
+    def computed_message(key, type)
+      "#{key} is a #{type} property. Notion computes it and it cannot be set."
+    end
+
+    def arity_message(key, type, values)
+      "#{key} is a #{type} property and takes one value; you gave #{values.length}: " \
+        "#{values.map(&:inspect).join(', ')}"
+    end
+
+    def page_parent_message(name)
+      "A page parent accepts only a title, so #{name.to_s.inspect} cannot be set. " \
+        "Publish into a database to set properties."
+    end
+  end
+end

data/lib/notion_publish/settings.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "errors"
+
+module NotionPublish
+  # Hand-written configuration. The tool reads it and never writes it, so
+  # comments and formatting survive -- Ruby's YAML discards comments on read and
+  # cannot put them back, which is why anything the tool rewrites lives in
+  # Manifest instead.
+  #
+  # Every .notion-publish.yml from the repository root down to the document's
+  # own directory is merged, closest winning, the way .rubocop.yml and
+  # .editorconfig behave.
+  class Settings
+    FILENAME = ".notion-publish.yml"
+    KEYS = %w[parent database icon cover].freeze
+
+    attr_reader :data, :files
+
+    def self.for(dir)
+      dirs = ancestors(File.expand_path(dir))
+      files = dirs.map { |d| File.join(d, FILENAME) }.select { |f| File.file?(f) }
+      new(files)
+    end
+
+    # Outermost first, so nearer files overwrite farther ones on merge. Stops at
+    # a git repository root when there is one.
+    def self.ancestors(dir)
+      chain = []
+      loop do
+        chain << dir
+        break if File.directory?(File.join(dir, ".git"))
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+      chain.reverse
+    end
+
+    def initialize(files)
+      @files = files
+      @data = files.reduce({}) { |merged, file| merged.merge(load_file(file)) }
+    end
+
+    KEYS.each { |key| define_method(key) { data[key] } }
+
+    def empty? = data.empty?
+
+    private
+
+    def load_file(path)
+      loaded = YAML.safe_load_file(path, permitted_classes: [], aliases: false) || {}
+      raise ConfigError, "#{path} must contain a YAML mapping" unless loaded.is_a?(Hash)
+
+      check_keys!(path, loaded.keys)
+      loaded.slice(*KEYS)
+    rescue Psych::Exception => e
+      raise ConfigError, "Could not parse #{path}: #{e.message}"
+    end
+
+    def check_keys!(path, keys)
+      unknown = keys - KEYS
+      return if unknown.empty?
+
+      raise ConfigError, "#{path}: unknown setting#{'s' if unknown.length > 1} " \
+                         "#{unknown.map(&:inspect).join(', ')}. Known settings: #{KEYS.join(', ')}."
+    end
+  end
+end

data/lib/notion_publish/sharing.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NotionPublish
+  # Notion returns object_not_found both for objects that do not exist and for
+  # objects that exist but are not shared with the calling connection. The API
+  # gives us no way to tell those apart, so these messages must not claim to.
+  module Sharing
+    module_function
+
+    def unreachable(id:, title:, connection_name:, kind: nil)
+      name = title && !title.empty? ? "#{title.inspect} (#{id})" : id.to_s
+      <<~MSG.strip
+        Cannot reach #{[kind, name].compact.join(' ')}.
+
+        Either it does not exist, or it is not shared with the
+        #{connection_name.inspect} connection. Notion returns the same error for
+        both, so there is no way to tell which from here.
+
+        #{instructions(kind)}
+      MSG
+    end
+
+    def instructions(kind)
+      case kind
+      when "inline database"
+        <<~MSG.strip
+          An inline database has no connection menu of its own. Share the page it
+          lives on:
+            1. Open that page in Notion
+            2. ••• menu (top right) -> Connections
+            3. Add the connection
+        MSG
+      else
+        <<~MSG.strip
+          To share it:
+            1. Open it in Notion
+            2. ••• menu (top right) -> Connections
+            3. Add the connection
+
+          Anything nested underneath is shared automatically.
+
+          An inline database has no menu of its own: share the page it sits on.
+        MSG
+      end
+    end
+  end
+end

data/lib/notion_publish/status.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "notion_digest"
+require_relative "errors"
+require_relative "manifest"
+require_relative "pool"
+
+module NotionPublish
+  # What would happen if you published everything.
+  #
+  # Answers the question the manifest exists to make answerable: which
+  # documents are in sync, which have changed locally, which changed in Notion,
+  # and which entries no longer have a source file.
+  class Status
+    STATES = {
+      unchanged: "in sync",
+      modified: "changed locally",
+      drifted: "changed in Notion",
+      diverged: "changed in both",
+      missing: "page is gone from Notion",
+      trashed: "page is in Notion's trash",
+      orphaned: "no source file",
+      unpublished: "never published"
+    }.freeze
+
+    # States that mean something needs doing to a document the manifest tracks.
+    ACTIONABLE = %i[modified drifted diverged missing trashed orphaned].freeze
+
+    SKIP_DIRS = %w[.git node_modules vendor tmp .bundle].freeze
+
+    Row = Data.define(:source, :state, :url) do
+      def actionable? = ACTIONABLE.include?(state)
+      def label = STATES[state]
+    end
+
+    # Whether a page object is in Notion's trash. Older API versions called
+    # this "archived".
+    def self.trashed?(page) = page["in_trash"] == true || page["archived"] == true
+
+    def initialize(map, client: nil)
+      @map = map
+      @client = client
+    end
+
+    # Pages are checked a few at a time. +started+ is called with each key as
+    # it is picked up and +finished+ with the count done so far, both on the
+    # calling thread, so a caller can show progress.
+    def rows(dir: nil, check_notion: true, started: nil, finished: nil, jobs: Pool::SIZE)
+      @client&.me if check_notion
+      tracked = Pool.run(@map.pages.to_a, size: jobs,
+                                          work: lambda { |(key, raw)|
+                                            tracked_row(key, Manifest::Entry.from(raw), check_notion)
+                                          },
+                                          started: started && ->((key, _)) { started.call(key) }, finished: finished)
+      tracked.sort_by { |r| [ACTIONABLE.index(r.state) || 99, r.source] } + untracked(dir)
+    end
+
+    private
+
+    def tracked_row(key, entry, check_notion)
+      path = File.expand_path(key, @map.dir)
+      return Row.new(source: key, state: :orphaned, url: entry.url) unless File.file?(path)
+
+      local = entry.source_sha256 && entry.source_sha256 != Digest::SHA256.hexdigest(File.binread(path))
+      remote = check_notion ? remote_state(entry) : nil
+      return Row.new(source: key, state: remote, url: entry.url) if %i[missing trashed].include?(remote)
+
+      Row.new(source: key, state: state_for(local, remote == :drifted), url: entry.url)
+    end
+
+    def state_for(local, remote)
+      return :diverged if local && remote
+      return :modified if local
+      return :drifted if remote
+
+      :unchanged
+    end
+
+    # :missing, :trashed, :drifted, or nil when the page is as published.
+    #
+    # Deleting a page in Notion moves it to the trash, and the API still
+    # returns a trashed page, Markdown and all. Only the page object says so,
+    # which is why it is read for every page, not only for those whose
+    # content changed: a page trashed without being edited still matches.
+    def remote_state(entry)
+      return nil unless @client
+      return :trashed if Status.trashed?(@client.get("/v1/pages/#{entry.id}"))
+      return :drifted if drifted?(entry)
+
+      nil
+    rescue ApiError => e
+      raise unless e.not_found?
+
+      :missing
+    end
+
+    # Notion's own output on both sides: a round trip is not byte-stable, so the
+    # sent form would never match a later read.
+    def drifted?(entry)
+      return false unless entry.notion_sha256
+
+      markdown = @client.get("/v1/pages/#{entry.id}/markdown")["markdown"].to_s
+      NotionDigest.of(markdown) != entry.notion_sha256
+    end
+
+    # Markdown files under the manifest that have never been published. Reported for
+    # information; they are not counted as needing action, because plenty of
+    # files are deliberately not mirrored.
+    def untracked(dir)
+      root = dir ? File.expand_path(dir) : @map.dir
+      return [] unless File.directory?(root)
+
+      known = @map.pages.keys.map { |k| File.expand_path(k, @map.dir) }
+      markdown_under(root).reject { |p| known.include?(p) }
+                          .sort
+                          .map { |p| Row.new(source: @map.key_for(p), state: :unpublished, url: nil) }
+    end
+
+    def markdown_under(root)
+      Dir.glob("**/*.md", base: root)
+         .reject { |rel| rel.split(File::SEPARATOR).any? { |part| SKIP_DIRS.include?(part) || part.start_with?(".") } }
+         .map { |rel| File.join(root, rel) }
+    end
+  end
+end