feat: add config validation workflow and editor schema hints (#286)

* feat(devx): add config validation workflow

* feat(config): add YAML schema hints for editors

* fix(devx): pin prettier and harden config validation

* fix(ci): skip schema-only changed config fetch tests

* docs: update readme

* Fix RuboCop CI warnings

Author: gildesmarais

.github/workflows/ruby.yml

@@ -11,14 +11,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: "20"
 
       - name: Install dependencies
-        run: |
-          sudo apt-get install -yqq yamllint
+        run: sudo apt-get install -yqq yamllint
+
+      - name: Install Node dependencies
+        run: npm ci --ignore-scripts --no-fund --no-audit
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -29,6 +31,9 @@ jobs:
       - name: Run linters
         run: make lint
 
+      - name: Validate configs
+        run: make validate
+
   test:
     strategy:
       fail-fast: false
@@ -38,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -53,7 +58,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

.gitignore

@@ -7,6 +7,7 @@
 /spec/reports/
 /tmp/
 /node_modules/
+/schema/
 
 # rspec failure tracking
 .rspec_status

.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-rspec
   - rubocop-performance
 

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "redhat.vscode-yaml"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/html2rss/html2rss/refs/heads/master/schema/html2rss-config.schema.json": "lib/html2rss/configs/**/*.yml"
+  }
+}

Makefile

@@ -1,9 +1,16 @@
-default: lint test
+default: lint validate test
 
 lint:
 	yamllint lib/html2rss/configs/ .github/
 	bundle exec rubocop -P -f quiet
-	npx prettier --check lib/**/*.yml .github/**/*.yml  README.md
+	./node_modules/.bin/prettier --check lib/**/*.yml .github/**/*.yml README.md
+
+validate:
+	bundle exec ruby bin/validate_configs
+
+schema:
+	mkdir -p schema
+	bundle exec html2rss schema --write schema/html2rss-config.schema.json
 
 test:
 	bundle exec rspec
@@ -46,4 +53,4 @@ restore-tests:
 
 lintfix:
 	bundle exec rubocop -a
-	npx prettier --write lib/**/*.yml .github/**/*.yml README.md
+	./node_modules/.bin/prettier --write lib/**/*.yml .github/**/*.yml README.md

README.md

@@ -22,7 +22,7 @@ This repository contains `html2rss` feed configurations for many websites.
 
 ## Dynamic Parameters
 
-Configs must include a `parameters` section to define default values for dynamic parameters:
+Parameterized configs should include a `parameters` section with default values:
 
 ```yaml
 parameters:
@@ -38,7 +38,30 @@ channel:
   # ... rest of config
 ```
 
-The `type` field specifies the parameter type (currently only `string` is supported), and `default` provides the default value when no parameter is explicitly provided.
+The `type` field specifies the parameter type (currently only `string` is supported), and `default` provides the default value used by this repository's validation and fetch tests.
+
+Notes:
+
+- Only configs that use `%<param>s` placeholders need a `parameters` section.
+- Callers can still override those defaults at runtime with `html2rss feed ... --params ...`.
+- Dynamic substitution applies to `channel` and `headers`; selectors are not parameterized by this feature.
+
+## Validation
+
+Use both schema-aware editing and runtime validation before committing:
+
+```bash
+# Validate all configs with the runtime validator
+make validate
+
+# Validate a single config directly
+bundle exec html2rss validate lib/html2rss/configs/github.com/releases.yml
+
+# Export the current JSON Schema locally for editor use
+make schema
+```
+
+The JSON Schema is useful for editor autocompletion and basic structural checks. Runtime validation remains authoritative for merged defaults and cross-field rules.
 
 ## Testing
 
@@ -55,12 +78,33 @@ make test-config CONFIG=github.com/releases.yml
 make test-domain DOMAIN=github.com
 ```
 
-**Adding new configs**: Just create the YAML file and run tests. No spec file needed.
+**Adding new configs**: Create the YAML file, run `make validate`, then run the generated tests. No dedicated spec file is needed.
 
 **Config folder convention**: Place configs under the registrable domain folder (e.g., `example.com/` or `bbc.co.uk/`). Legacy subdomain folders (e.g., `news.example.com/`) are allowed but not preferred.
 
+## Editor Setup (JSON Schema)
+
+Get inline validation and autocompletion when editing configs in your IDE.
+All config files already carry the schema modeline at the top:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/html2rss/html2rss/refs/heads/master/schema/html2rss-config.schema.json
+```
+
+Any editor with [yaml-language-server](https://github.com/redhat-developer/yaml-language-server)
+support (VS Code + [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml),
+Neovim, Helix, …) will automatically pick up the schema when opening a config file.
+
+The included `.vscode/settings.json` additionally associates the schema with all
+configs via a glob pattern, so new files get validation before the modeline is added.
+
+> `make schema` writes `schema/html2rss-config.schema.json` locally — useful for
+> offline editing or when you want to pin against the currently installed gem version.
+
 ## Documentation
 
-- [Main Documentation](https://html2rss.github.io/html2rss-configs/)
+- [Selectors Reference](https://html2rss.github.io/ruby-gem/reference/selectors/)
+- [Dynamic Parameters](https://html2rss.github.io/ruby-gem/how-to/dynamic-parameters/)
+- [CLI Reference](https://html2rss.github.io/ruby-gem/reference/cli-reference/)
 - [Contributing Guide](https://html2rss.github.io/get-involved/contributing)
 - [Sponsorship Page](https://html2rss.github.io/get-involved/sponsoring)

bin/rspec_changed_configs

@@ -1,18 +1,34 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-changed_files = `git diff --name-only origin/master | grep 'lib/html2rss/configs/.*/.*.yml'`.split("\n")
-
-if changed_files.any?
-  # Use dynamic test file with environment variable to filter changed configs
-  config_names = changed_files.map { |file| file.sub('lib/html2rss/configs/', '') }
-
-  # Test each changed config individually
-  config_names.each do |config_name|
-    puts "Testing changed config: #{config_name}"
-    system("bundle exec rspec --example '#{config_name}' --tag fetch spec/html2rss/configs_dynamic_spec.rb")
-  end
-else
-  puts 'No changed config files found'
+CONFIG_PATH = %r{\Alib/html2rss/configs/.+/.+\.yml\z}
+SCHEMA_MODELINE = /\A[+-]# yaml-language-server: \$schema=/
+
+def comment_only_change?(file)
+  diff_lines = `git diff --unified=0 origin/master -- #{file}`.lines
+  changed_lines = diff_lines.select { |line| line.start_with?('+', '-') }
+  content_lines = changed_lines.reject { |line| line.start_with?('+++', '---') }
+
+  content_lines.any? && content_lines.all? { |line| line.match?(SCHEMA_MODELINE) }
+end
+
+changed_files = `git diff --name-only origin/master`
+                .split("\n")
+                .grep(CONFIG_PATH)
+
+test_files = changed_files.reject { |file| comment_only_change?(file) }
+
+if test_files.empty?
+  puts 'No changed config files require fetch tests'
   exit 0
 end
+
+failed = false
+
+test_files.each do |file|
+  config_name = file.sub('lib/html2rss/configs/', '')
+  puts "Testing changed config: #{config_name}"
+  failed ||= !system("bundle exec rspec --example '#{config_name}' --tag fetch spec/html2rss/configs_dynamic_spec.rb")
+end
+
+exit 1 if failed

bin/setup

@@ -1,8 +1,33 @@
 #!/usr/bin/env bash
 set -euo pipefail
 IFS=$'\n\t'
-set -vx
 
+echo "==> Installing Ruby dependencies..."
 bundle install
 
-# Do any other automated setup that you need to do here
+echo
+echo "==> Installing Node dependencies (required for make lint)..."
+npm install --ignore-scripts --no-fund --no-audit
+
+echo
+echo "==> Checking system tools..."
+if command -v yamllint &>/dev/null; then
+  echo "    yamllint: ok ($(yamllint --version))"
+else
+  echo "    yamllint: not found"
+  echo "    Install with one of:"
+  echo "      brew install yamllint"
+  echo "      pip install yamllint"
+fi
+
+echo
+echo "==> Setup complete. Common commands:"
+echo
+echo "    make              # lint + validate + test"
+echo "    make lint         # yamllint, rubocop, prettier"
+echo "    make validate     # validate all configs against the html2rss schema"
+echo "    make test         # run rspec"
+echo
+echo "    make test-config CONFIG=github.com/releases.yml   # test a single config"
+echo "    make test-domain DOMAIN=github.com                # test all configs for a domain"
+echo "    make schema                                        # write schema locally (optional)"

bin/validate_configs

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'html2rss'
+require 'yaml'
+
+files = Dir['lib/html2rss/configs/**/*.yml']
+failed = []
+
+files.each do |file|
+  config = YAML.safe_load_file(file, symbolize_names: true)
+  result = Html2rss::Config.validate(config)
+
+  if result.success?
+    puts "ok   #{file}"
+  else
+    puts "FAIL #{file}"
+    result.errors.to_h.each do |key, messages|
+      Array(messages).each { |msg| warn "       #{key}: #{msg}" }
+    end
+    failed << file
+  end
+rescue Psych::Exception => error
+  puts "FAIL #{file}"
+  warn "       parse: #{error.message}"
+  failed << file
+rescue StandardError => error
+  puts "FAIL #{file}"
+  warn "       validation: #{error.class}: #{error.message}"
+  failed << file
+end
+
+puts
+if failed.empty?
+  puts "#{files.size} configs validated successfully."
+else
+  warn "#{failed.size}/#{files.size} configs failed validation."
+  exit 1
+end