Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 48 additions & 37 deletions script/fetch-citations.rb
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ module CitationFetch

class KeyRefused < StandardError; end

# The seams test/test_fetch_citations.rb replaces.
# The seams test/test_fetch_citations.rb replaces. `Citations` comes from
# _plugins/citations.rb, which Jekyll loads (and the tests require).
class << self
attr_writer :http, :pause, :clock

Expand Down Expand Up @@ -83,14 +84,51 @@ def self.published(url)
rescue StandardError
nil
end
end

# A warning or error: an annotation in CI, and an error also in the run's
# summary, where a scheduled run's shows without opening the log.
def note(message, level = "warning")
warn(ENV["GITHUB_ACTIONS"] ? "::#{level} title=Citation counts::#{message}" : "fetch-citations: #{message}")
summary = ENV["GITHUB_STEP_SUMMARY"]
File.write(summary, "**Citation counts:** #{message}\n", mode: "a") if level == "error" && summary && !summary.empty?
# Fetches the counts for `ids` and writes them to `out`, or, failing that,
# the counts `published_url` holds. Calls `note.(message, level)` for each
# warning or error. Returns what it wrote, or nil.
def self.run(ids, out:, published_url:, key: "", note: method(:note), now: Time.now)
stop = clock.call + DEADLINE # one deadline for both tries below
begin
answer = fetch(ids, key: key, stop: stop)
rescue KeyRefused => e
note.("Semantic Scholar refused SEMANTIC_SCHOLAR_API_KEY (#{e.message}); renew the secret. Asking without it", "error")
answer = fetch(ids, stop: stop)
end
papers = nil
if answer
begin
papers = Citations.entries(ids, JSON.parse(answer))
rescue JSON::ParserError, ArgumentError => e
note.("unusable answer from Semantic Scholar (#{e.message.lines.first.strip})", "warning")
end
end

if papers
data = { "fetched_at" => now.utc.iso8601, "papers" => papers.sort.to_h }
puts "fetch-citations: #{papers.size} of #{ids.size} papers counted"
missing = ids - papers.keys
note.("no count for #{missing.join(", ")} (not found, or 0: see _data/citation_ids.yml)", "warning") unless missing.empty?
elsif (data = published(published_url))
age = now - (Time.iso8601(data["fetched_at"]) rescue Time.at(0))
note.("no usable answer from Semantic Scholar; kept the published counts of #{data["fetched_at"]}",
age > STALE ? "error" : "warning")
else
note.("no usable answer from Semantic Scholar and no published counts; #{File.basename(out)} is not updated", "warning")
return nil
end
File.write(out, JSON.pretty_generate(data) + "\n")
data
end

# A warning or error: an annotation in CI, and an error also in the run's
# summary, where a scheduled run's shows without opening the log.
def self.note(message, level = "warning")
warn(ENV["GITHUB_ACTIONS"] ? "::#{level} title=Citation counts::#{message}" : "fetch-citations: #{message}")
summary = ENV["GITHUB_STEP_SUMMARY"]
File.write(summary, "**Citation counts:** #{message}\n", mode: "a") if level == "error" && summary && !summary.empty?
end
end

if $PROGRAM_NAME == __FILE__
Expand All @@ -107,33 +145,6 @@ def note(message, level = "warning")
ids = site.posts.docs.filter_map { |post| post.data["citation_id"] }.uniq
abort "fetch-citations: no post has a citation_id; is _plugins/citations.rb loaded?" if ids.empty?

papers = nil
stop = CitationFetch.clock.call + CitationFetch::DEADLINE # one deadline for both tries below
begin
answer = CitationFetch.fetch(ids, key: ENV["SEMANTIC_SCHOLAR_API_KEY"].to_s, stop: stop)
rescue CitationFetch::KeyRefused => e
note("Semantic Scholar refused SEMANTIC_SCHOLAR_API_KEY (#{e.message}); renew the secret. Asking without it", "error")
answer = CitationFetch.fetch(ids, stop: stop)
end
if answer
begin
papers = Citations.entries(ids, JSON.parse(answer))
rescue JSON::ParserError, ArgumentError => e
note("unusable answer from Semantic Scholar (#{e.message.lines.first.strip})")
end
end

if papers
File.write(out, JSON.pretty_generate("fetched_at" => Time.now.utc.iso8601, "papers" => papers.sort.to_h) + "\n")
puts "fetch-citations: #{papers.size} of #{ids.size} papers counted"
missing = ids - papers.keys
note("no count for #{missing.join(", ")} (not found, or 0: see _data/citation_ids.yml)") unless missing.empty?
elsif (last = CitationFetch.published("#{site.config["url"]}#{ENV.fetch("BASE_PATH", site.baseurl)}/citations.json"))
File.write(out, JSON.pretty_generate(last) + "\n")
age = Time.now - (Time.iso8601(last["fetched_at"]) rescue Time.at(0))
note("no usable answer from Semantic Scholar; kept the published counts of #{last["fetched_at"]}",
age > CitationFetch::STALE ? "error" : "warning")
else
note("no usable answer from Semantic Scholar and no published counts; _data/citations.json is not updated")
end
url = "#{site.config["url"]}#{ENV.fetch("BASE_PATH", site.baseurl)}/citations.json"
CitationFetch.run(ids, out: out, published_url: url, key: ENV["SEMANTIC_SCHOLAR_API_KEY"].to_s)
end
16 changes: 16 additions & 0 deletions test/test_citations.rb
Original file line number Diff line number Diff line change
Expand Up @@ -90,4 +90,20 @@ def test_annotate_without_fetched_counts_sets_only_the_id
assert_nil post.data["citation"]
end
end

# The build prints the field and js/citations.js rewrites it, each with its
# own copy of the wording: they must say the same.
def test_the_layout_and_the_script_word_the_count_alike
root = File.expand_path("..", __dir__)
layout = File.read(File.join(root, "_layouts/post.html"))
script = File.read(File.join(root, "js/citations.js"))
assert_includes layout, %({% if cited.count == 1 %}citation{% else %}citations{% endif %} on Semantic Scholar")
assert_includes script, %(+ (entry.count === 1 ? ' citation' : ' citations') + ' on Semantic Scholar')
assert_includes layout, 'title="Semantic Scholar"'
assert_includes script, "link.title = 'Semantic Scholar'"
assert_includes layout, 'href="https://www.semanticscholar.org/paper/{{ cited.paper_id | escape }}"'
assert_includes script, "'https://www.semanticscholar.org/paper/' + encodeURIComponent(entry.paperId)"
# delimited() and toLocaleString('en-US') group by thousands with commas.
assert_includes script, "entry.count.toLocaleString('en-US')"
end
end
62 changes: 62 additions & 0 deletions test/test_fetch_citations.rb
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

require "minitest/autorun"
require "stringio"
require "tmpdir"
require_relative "../_plugins/citations"
require_relative "../script/fetch-citations"

class TestFetchCitations < Minitest::Test
Expand All @@ -16,10 +18,12 @@ def setup
CitationFetch.pause = ->(s) { @now += s }
CitationFetch.http = ->(*) { raise "no network in tests" }
@stderr, $stderr = $stderr, StringIO.new # the retry log
@stdout, $stdout = $stdout, StringIO.new
end

def teardown
$stderr = @stderr
$stdout = @stdout
CitationFetch.http = CitationFetch.pause = CitationFetch.clock = nil
end

Expand Down Expand Up @@ -119,4 +123,62 @@ def test_published_counts_are_taken_only_in_the_shape_written
answering(SocketError.new("x"))
assert_nil CitationFetch.published("https://example.org/citations.json")
end

S2 = "f1c0aad419cd942d5a135b47fcce58d101dbb3bd"
NOW = Time.utc(2026, 11, 17, 12)
LIVE = "https://example.org/citations.json"

# run() in a scratch dir; returns [what it returned, the file, the notes].
def run_with(*answers, key: "")
Dir.mktmpdir do |dir|
out = File.join(dir, "citations.json")
notes = []
answering(*answers)
data = CitationFetch.run(%w[arXiv:1 arXiv:2], out: out, published_url: LIVE, key: key,
note: ->(m, l) { notes << [l, m] }, now: NOW)
[data, File.file?(out) ? JSON.parse(File.read(out)) : nil, notes]
end
end

def published(at)
response(200, JSON.generate("fetched_at" => at, "papers" => { "arXiv:1" => { "count" => 3, "paper_id" => S2 } }))
end

def test_run_writes_the_fetched_counts_and_names_the_missing
data, file, notes = run_with(response(200, JSON.generate([{ "paperId" => S2, "citationCount" => 9 }, nil])))
assert_equal({ "fetched_at" => "2026-11-17T12:00:00Z", "papers" => { "arXiv:1" => { "count" => 9, "paper_id" => S2 } } }, file)
assert_equal file, data
assert_equal [["warning", "no count for arXiv:2 (not found, or 0: see _data/citation_ids.yml)"]], notes
end

def test_a_refused_key_is_an_error_and_is_asked_again_without_it
_, file, notes = run_with(response(403), response(200, JSON.generate([nil, nil])), key: "k")
assert_equal %w[k] + [nil], @asked.map { |r| r["x-api-key"] }
assert_equal "error", notes.first[0]
assert_equal({}, file["papers"])
end

def test_without_an_answer_the_published_counts_are_kept
_, file, notes = run_with(*Array.new(5) { response(429) }, published("2026-11-16T20:41:00Z"))
assert_equal "2026-11-16T20:41:00Z", file["fetched_at"]
assert_equal [["warning", "no usable answer from Semantic Scholar; kept the published counts of 2026-11-16T20:41:00Z"]], notes
end

def test_published_counts_a_week_old_are_an_error
_, _, notes = run_with(*Array.new(5) { response(429) }, published("2026-11-09T00:00:00Z"))
assert_equal "error", notes.last[0]
end

def test_an_unusable_answer_falls_back_too
_, file, notes = run_with(response(200, "[]"), published("2026-11-16T20:41:00Z"))
assert_equal 3, file.dig("papers", "arXiv:1", "count")
assert_match(/unusable answer/, notes.first[1])
end

def test_with_nothing_to_write_the_file_is_left_alone
data, file, notes = run_with(*Array.new(5) { response(429) }, response(404))
assert_nil data
assert_nil file
assert_match(/not updated/, notes.last[1])
end
end
Loading