diff --git a/script/fetch-citations.rb b/script/fetch-citations.rb index cee529e..56a477c 100644 --- a/script/fetch-citations.rb +++ b/script/fetch-citations.rb @@ -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 @@ -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__ @@ -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 diff --git a/test/test_citations.rb b/test/test_citations.rb index 2281d2f..66bed42 100644 --- a/test/test_citations.rb +++ b/test/test_citations.rb @@ -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 diff --git a/test/test_fetch_citations.rb b/test/test_fetch_citations.rb index ec7beef..a8145fe 100644 --- a/test/test_fetch_citations.rb +++ b/test/test_fetch_citations.rb @@ -6,6 +6,8 @@ require "minitest/autorun" require "stringio" +require "tmpdir" +require_relative "../_plugins/citations" require_relative "../script/fetch-citations" class TestFetchCitations < Minitest::Test @@ -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 @@ -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