jekyll-client-search 0.3.4 → 0.3.5

data/README.developer.md

@@ -8,13 +8,12 @@ See [README.md](README.md) for user-facing configuration and usage docs.
 ## Quick start
 
 ```bash
-rbenv install 3.4.10       # if not already installed
-rbenv local 3.4.10
+rbenv install            # reads .ruby-version
 bundle install
 npm ci
-bundle exec rspec                          # Ruby tests (248 examples; 7 Ollama pending)
+bundle exec rspec                          # Ruby tests
 OLLAMA_INTEGRATION=1 bundle exec rspec     # all tests including Ollama integration
-npm test                                   # JavaScript tests (134 tests)
+npm test                                   # JavaScript tests
 ```
 
 Both test suites pass with only the committed Wikipedia fixtures and the
@@ -29,16 +28,22 @@ The project uses a focused quality stack: RuboCop (style), bundler-audit
 maintenance burden of additional code-smell tools on a small focused gem.
 
 External automated code review services:
+
 - [CodeQL](https://codeql.github.com) — GitHub native security scanning
   (Ruby + JavaScript), runs on every push.
 - [Semgrep](https://semgrep.dev) — CI security scan using the Semgrep Pro
-  engine with the organization's full policy (2,900+ rules). Runs as a CI
+  engine with the organization's full policy ruleset. Runs as a CI
   job (`semgrep ci`) and in the pre-commit hook (custom rules only). See
   `.semgrep.yml` for local configuration and usage instructions.
 - [CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search) —
   automated code review (RuboCop, Brakeman, bundler-audit, duplication).
 - [Dependabot](https://docs.github.com/en/code-security/dependabot) — weekly
   GitHub Actions version updates (SHA-pinned actions updated automatically).
+- [Codecov](https://codecov.io/gh/gundestrup/jekyll-client-search) — coverage
+  reporting. CI uploads Cobertura XML generated by `simplecov-cobertura` from
+  the Ruby 3.4 / Node 24 matrix job; status check thresholds live in
+  `codecov.yml`. Uploads authenticate via OIDC (`id-token: write`), with the
+  `CODECOV_TOKEN` secret as a fallback.
 
 ### Semgrep usage
 
@@ -85,8 +90,9 @@ comments. Dependabot updates the SHAs and version comments automatically.
 
 ### Git hooks
 
-Git hooks are not committed to the repository. Install them locally after
-cloning:
+Hooks are tracked in `bin/hooks/`; `bin/install-hooks.sh` points git at
+them via `core.hooksPath` (no copying — tracked hooks can't drift from
+installed ones). Run once after cloning:
 
 ```bash
 bin/install-hooks.sh
@@ -106,11 +112,11 @@ CI. Skip either with `git commit --no-verify` or `git push --no-verify`.
 ### CI checks
 
 The [CI workflow](.github/workflows/ci.yml) runs on every push and pull
-request across Ruby 3.2/3.3/3.4 and Node 22/24:
+request across Ruby 3.3/3.4 and Node 22/24:
 
 - `bundle exec rake ci` (rspec, rubocop, syntax checks, npm test, gem build)
 - `bundle exec bundle-audit check --update` (Ruby dependency security)
-- `npm audit --audit-level=high` (JavaScript dependency security)
+- `npm run audit` (JavaScript dependency security gate — see `scripts/npm-audit.mjs`)
 - `npm outdated` (non-blocking — warns about outdated npm packages)
 - `semgrep ci` (security scan with custom rules from `.semgrep.yml`)
 
@@ -163,7 +169,7 @@ test files are `spec/related_analyzer_spec.rb`, `spec/related_tag_spec.rb`,
 ## What is committed
 
 | Artifact | Committed? | Why |
-|---|---|---|
+| --- | --- | --- |
 | Wikipedia fixture posts (40) | Yes | CC BY-SA 3.0 allows redistribution with attribution |
 | arXiv fixture posts (40) | **No** | Mixed/restrictive licenses — see below |
 | Baseline search-index JSON | Yes | Generated test artifact (indexed data, not raw text) |
@@ -193,6 +199,7 @@ ruby spec/fixtures/download_arxiv.rb
 ```
 
 This script:
+
 - Fetches 40 recent arXiv papers from 5 CS/AI subfields
 - Downloads each PDF and extracts text with `pdftotext`
 - Records the actual per-paper license in each post's frontmatter
@@ -244,6 +251,7 @@ To run the full integration tests that call a real Ollama server:
    ```
 
 These tests:
+
 - Build the full 80-post index with real Ollama embeddings
 - Verify embedding dimensions and validity
 - Test semantic search quality with concept queries
@@ -272,7 +280,7 @@ ruby spec/fixtures/generate_semantic_gold.rb
 ## Test categories
 
 | Tag | Description | Requires arXiv? | Requires Ollama? |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `:unit` | Ruby unit tests | No | No |
 | `:system` | Ruby system tests (build fixture site) | Partially | No |
 | `:integration` | Ruby integration tests | No | No |
@@ -298,7 +306,9 @@ always return an asset).
 
 The coverage report is generated at `coverage/index.html` after each RSpec
 run. Raw data is in `coverage/.resultset.json` (SimpleCov 1.0+ format with
-`lines` and `branches` keys per file).
+`lines` and `branches` keys per file). In CI (`ENV["CI"]`), SimpleCov emits
+Cobertura XML at `coverage/coverage.xml` instead, which is uploaded to
+Codecov by the `codecov/codecov-action` step in `ci.yml`.
 
 To check remaining uncovered lines and branches after a run:
 
@@ -492,7 +502,7 @@ The [`release.yml`](.github/workflows/release.yml) workflow, triggered by
 pushing a `v*` tag:
 
 1. Checks out the repository at the release tag (`persist-credentials: false`).
-2. Sets up Ruby 3.4.10.
+2. Sets up Ruby from `.ruby-version`.
 3. Verifies the tag name matches `v<gem version>` (fails on mismatch).
 4. Verifies `CHANGELOG.md` has a `## X.Y.Z` entry for the version
    (`rake version:check_changelog` — fails if missing).

data/README.md

@@ -1,16 +1,21 @@
 # jekyll-client-search
 
+[![codecov](https://codecov.io/gh/gundestrup/jekyll-client-search/branch/main/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-client-search)
+
+
 ![jekyll-client-search logo](docs/assets/icon-256.png)
 
 [![CI](https://github.com/gundestrup/jekyll-client-search/actions/workflows/ci.yml/badge.svg)](https://github.com/gundestrup/jekyll-client-search/actions/workflows/ci.yml)
-[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.2-red.svg)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-client-search)](https://rubygems.org/gems/jekyll-client-search)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.3-red.svg)](https://www.ruby-lang.org/)
 [![Jekyll](https://img.shields.io/badge/jekyll-4.x-blue.svg)](https://jekyllrb.com/)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
-[![DeepWiki](https://img.shields.io/badge/DeepWiki-docs-7B68EE.svg)](https://deepwiki.com/gundestrup/jekyll-client-search)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gundestrup/jekyll-client-search)
 [![Coverage](https://img.shields.io/badge/coverage-100%25%20branches-brightgreen.svg)](#testing-strategy)
 [![Semgrep](https://img.shields.io/badge/semgrep-scanning-brightgreen.svg)](https://semgrep.dev)
 [![CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search/badge)](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search)
 [![SonarQube](https://sonarcloud.io/api/project_badges/measure?project=gundestrup_jekyll-client-search&metric=alert_status)](https://sonarcloud.io/project/overview?id=gundestrup_jekyll-client-search)
+[![codecov](https://codecov.io/gh/gundestrup/jekyll-client-search/branch/main/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-client-search)
 
 A Jekyll plugin that generates a JSON document index for client-side search.
 Supports lexical search ([MiniSearch](https://lucaong.github.io/minisearch/),
@@ -603,14 +608,19 @@ Jekyll build time using a local [Ollama](https://ollama.ai/) server and the
 ### Setup
 
 1. Install [Ollama](https://ollama.ai/) and pull an embedding model:
+
    ```bash
    ollama pull embeddinggemma:300m
    ```
+
 2. Add `ollama-ruby` to your site's Gemfile (optional dependency):
+
    ```ruby
    gem "ollama-ruby", "~> 1.23"
    ```
+
 3. Enable embeddings in `_config.yml`:
+
    ```yaml
    client_search:
      engine: semantic
@@ -1012,18 +1022,18 @@ Recommended policy:
 
 ## License
 
+Copyright (C) 2026 Svend Gundestrup.
+
 This project is licensed under the GNU Affero General Public License v3.0 or
 later (`AGPL-3.0-or-later`). See [LICENSE](LICENSE).
 
 ## Development
 
-Development uses Ruby 3.4.10 through rbenv, while the gem supports Ruby 3.2
-and newer. The development version is stored in `.ruby-version`, and CI tests
-Ruby 3.2, 3.3, and 3.4.
+Development uses the Ruby version pinned in `.ruby-version` (via rbenv),
+while the gem supports Ruby 3.3 and newer. CI tests Ruby 3.3 and 3.4.
 
 ```bash
-rbenv install 3.4.10       # if not already installed
-rbenv local 3.4.10
+rbenv install            # reads .ruby-version
 bundle install
 npm ci
 bundle exec rake ci
@@ -1153,7 +1163,7 @@ Additional automated code quality and security services:
 - [CodeQL](https://codeql.github.com) — GitHub native code scanning for
   security vulnerabilities (Ruby + JavaScript).
 - [Semgrep](https://semgrep.dev) — CI security scan using the Semgrep Pro
-  engine with the organization's full policy (2,900+ rules). Custom ReDoS
+  engine with the organization's full policy ruleset. Custom ReDoS
   detection rules are defined in `.semgrep.yml`. Findings are triaged on the
   [Semgrep AppSec Platform](https://semgrep.dev) dashboard. False positives
   and acceptable risks are annotated inline with `# nosemgrep: rule.id`.

data/assets/includes/related-articles.html

@@ -15,8 +15,10 @@
 #   scripts: true (default) to load runtime scripts, false to skip
 ---
 
-{% assign related_sort = include.sort | default: "relevance" %}
-{% assign include_scripts = include.scripts | default: true %}
+{% comment %}Bracket access: bare include.sort falls back to Hash#sort on
+non-empty param hashes, so the default would silently stop applying.{% endcomment %}
+{% assign related_sort = include["sort"] | default: "relevance" %}
+{% assign include_scripts = include["scripts"] | default: true %}
 {% if include_scripts == false or include_scripts == "false" %}
   {% assign include_scripts = false %}
 {% endif %}

data/lib/jekyll/client_search/dropdown_tag.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "cgi"
-
 module Jekyll
   module ClientSearch
     # Liquid tag that renders a compact live-search dropdown suitable for
@@ -15,27 +13,22 @@ module Jekyll
     #
     # When client_search is disabled the tag renders nothing.
     class DropdownTag < Liquid::Tag
+      include ScriptTags
+
       SYNTAX = /\A(max:(\d+))?\s*(scripts_only|no_scripts)?\z/
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
-        unless (match = @markup.match(SYNTAX))
-          raise Liquid::SyntaxError,
-                "search_dropdown: invalid syntax. Use {% search_dropdown %}, " \
-                "{% search_dropdown max:10 %}, {% search_dropdown scripts_only %}, " \
-                "or {% search_dropdown no_scripts %}"
-        end
-
-        @max_items = match[2].to_i if match[2]
-        raise Liquid::SyntaxError, "search_dropdown: max must be greater than zero" if @max_items && @max_items < 1
-
-        @mode = match[3] || "full"
         @input_id = "cs-dropdown-input-#{object_id}"
         @results_id = "cs-dropdown-results-#{object_id}"
       end
 
       def render(context)
+        validate_markup!
         site = context.registers[:site]
         return "" unless enabled?(site)
 
@@ -47,6 +40,23 @@ module Jekyll
 
       private
 
+      def validate_markup!
+        return if @validated
+
+        @validated = true
+        unless (match = @markup.match(SYNTAX))
+          raise Liquid::SyntaxError,
+                "search_dropdown: invalid syntax. Use {% search_dropdown %}, " \
+                "{% search_dropdown max:10 %}, {% search_dropdown scripts_only %}, " \
+                "or {% search_dropdown no_scripts %}"
+        end
+
+        @max_items = match[2].to_i if match[2]
+        raise Liquid::SyntaxError, "search_dropdown: max must be greater than zero" if @max_items && @max_items < 1
+
+        @mode = match[3] || "full"
+      end
+
       def enabled?(site)
         return false if site.nil?
 
@@ -62,7 +72,7 @@ module Jekyll
         form_html = build_form(max)
         return form_html if @mode == "no_scripts"
 
-        scripts = build_scripts(configuration, prefix)
+        scripts = script_tags(configuration, prefix, "client-search-dropdown.js")
         return scripts if @mode == "scripts_only"
 
         "#{form_html}\n#{scripts}"
@@ -87,33 +97,6 @@ module Jekyll
           </div>
         HTML
       end
-
-      def build_scripts(configuration, prefix)
-        scripts = []
-        engine = engine_script(configuration)
-        scripts << engine if engine
-        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-dropdown.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
-        scripts.map { |script| "  #{script}" }.join("\n")
-      end
-
-      def engine_script(configuration)
-        url = configuration.engine_url
-        return nil unless url
-
-        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
-        if configuration.engine_crossorigin
-          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
-          attrs << "crossorigin=\"#{crossorigin}\""
-        end
-        if configuration.engine_sri
-          integrity = CGI.escapeHTML(configuration.engine_sri)
-          attrs << "integrity=\"#{integrity}\""
-        end
-        "<script #{attrs.join(' ')}></script>"
-      end
     end
   end
 end

data/lib/jekyll/client_search/related_tag.rb

@@ -18,11 +18,34 @@ module Jekyll
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
+      end
+
+      def render(context)
         parse_tokens(@markup)
+        site = context.registers[:site]
+        return "" if site.nil?
+
+        config = site.config.fetch("client_search", {})
+        return "" if config == false
+        return "" unless related_enabled?(config)
+
+        asset_prefix = asset_prefix(site)
+        sort_attr = @sort ? " data-related-sort=\"#{@sort}\"" : ""
+        max_attr = resolve_max_attr(config)
+        scripts = build_scripts(asset_prefix)
+        build_html(sort_attr, max_attr, scripts)
       end
 
+      private
+
       def parse_tokens(markup)
+        return if @parsed
+
+        @parsed = true
         @sort = nil
         @max_items = nil
         @include_scripts = true
@@ -49,23 +72,6 @@ module Jekyll
           "or {% related_articles no_scripts %}"
       end
 
-      def render(context)
-        site = context.registers[:site]
-        return "" if site.nil?
-
-        config = site.config.fetch("client_search", {})
-        return "" if config == false
-        return "" unless related_enabled?(config)
-
-        asset_prefix = asset_prefix(site)
-        sort_attr = @sort ? " data-related-sort=\"#{@sort}\"" : ""
-        max_attr = resolve_max_attr(config)
-        scripts = build_scripts(asset_prefix)
-        build_html(sort_attr, max_attr, scripts)
-      end
-
-      private
-
       def related_enabled?(config)
         related = config.fetch("related", {})
         related["enabled"] == true

data/lib/jekyll/client_search/script_tags.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Jekyll
+  module ClientSearch
+    # Shared <script> tag assembly for the client-search Liquid tags so each
+    # tag only declares its own asset file.
+    module ScriptTags
+      private
+
+      def script_tags(configuration, prefix, tag_asset, extra: [])
+        scripts = []
+        engine = engine_script(configuration)
+        scripts << engine if engine
+        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
+        scripts.concat(extra)
+        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/#{tag_asset}\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
+        scripts.map { |script| "  #{script}" }.join("\n")
+      end
+
+      def engine_script(configuration)
+        url = configuration.engine_url
+        return nil unless url
+
+        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
+        if configuration.engine_crossorigin
+          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
+          attrs << "crossorigin=\"#{crossorigin}\""
+        end
+        if configuration.engine_sri
+          integrity = CGI.escapeHTML(configuration.engine_sri)
+          attrs << "integrity=\"#{integrity}\""
+        end
+        "<script #{attrs.join(' ')}></script>"
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/search_tag.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "cgi"
-
 module Jekyll
   module ClientSearch
     # Liquid tag that renders the search form, status/results containers,
@@ -14,21 +12,20 @@ module Jekyll
     #
     # When client_search is disabled the tag renders nothing.
     class SearchTag < Liquid::Tag
+      include ScriptTags
+
       SYNTAX = /\A(scripts_only|no_scripts)?\z/
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
-        unless (match = @markup.match(SYNTAX))
-          raise Liquid::SyntaxError,
-                "search_form: invalid syntax. Use {% search_form %}, " \
-                "{% search_form scripts_only %}, or {% search_form no_scripts %}"
-        end
-
-        @mode = match[1] || "full"
       end
 
       def render(context)
+        validate_markup!
         site = context.registers[:site]
         return "" if site.nil?
 
@@ -51,6 +48,18 @@ module Jekyll
 
       private
 
+      def validate_markup!
+        return if @mode
+
+        unless (match = @markup.match(SYNTAX))
+          raise Liquid::SyntaxError,
+                "search_form: invalid syntax. Use {% search_form %}, " \
+                "{% search_form scripts_only %}, or {% search_form no_scripts %}"
+        end
+
+        @mode = match[1] || "full"
+      end
+
       def build_form
         <<~HTML
           <form id="search-form" role="search">
@@ -64,31 +73,8 @@ module Jekyll
       end
 
       def build_scripts(configuration, prefix)
-        scripts = []
-        engine = engine_script(configuration)
-        scripts << engine if engine
-        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
-        scripts.concat(embedder_scripts(configuration, prefix))
-        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-base.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
-        scripts.map { |script| "  #{script}" }.join("\n")
-      end
-
-      def engine_script(configuration)
-        url = configuration.engine_url
-        return nil unless url
-
-        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
-        if configuration.engine_crossorigin
-          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
-          attrs << "crossorigin=\"#{crossorigin}\""
-        end
-        if configuration.engine_sri
-          integrity = CGI.escapeHTML(configuration.engine_sri)
-          attrs << "integrity=\"#{integrity}\""
-        end
-        "<script #{attrs.join(' ')}></script>"
+        script_tags(configuration, prefix, "client-search-base.js",
+                    extra: embedder_scripts(configuration, prefix))
       end
 
       def embedder_scripts(configuration, prefix)

data/lib/jekyll/client_search/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module ClientSearch
-    VERSION = "0.3.4"
+    VERSION = "0.3.5"
   end
 end

data/lib/jekyll/client_search.rb

@@ -23,5 +23,6 @@ require_relative "client_search/index_cache"
 require_relative "client_search/ollama_embedding_adapter"
 require_relative "client_search/generator"
 require_relative "client_search/related_tag"
+require_relative "client_search/script_tags"
 require_relative "client_search/dropdown_tag"
 require_relative "client_search/search_tag"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-client-search
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Svend Gundestrup
@@ -75,6 +75,7 @@ files:
 - lib/jekyll/client_search/related_page.rb
 - lib/jekyll/client_search/related_tag.rb
 - lib/jekyll/client_search/runtime_config_page.rb
+- lib/jekyll/client_search/script_tags.rb
 - lib/jekyll/client_search/search_index_page.rb
 - lib/jekyll/client_search/search_tag.rb
 - lib/jekyll/client_search/tasks.rb
@@ -95,7 +96,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="