feat: add portals.yml schema validator

[luochen211]

Summary

• Add validate-portals.mjs to validate portals.yml shape before scanner runs.
• Validate title/location filter keyword lists, tracked company entries, URL schemes, explicit provider IDs, parser blocks, and duplicate enabled company names.
• Add npm run validate:portals, docs, and regression coverage in test-all.mjs.

Fixes #877

Tests

• npm run validate:portals -- --file templates/portals.example.yml
• node validate-portals.mjs --self-test
• node --check validate-portals.mjs && node --check test-all.mjs
• node test-all.mjs — 173 passed, 0 failed, 7 existing README.ua personal-data warnings

Summary by CodeRabbit

• New Features

  • Added an offline command to validate portal configuration files, checking YAML syntax, provider validity, URL formats, filter keywords, parser settings, and warning on duplicate enabled company names.

• Tests

  • Added validation tests for valid configs, unknown providers, empty keywords, and duplicate companies.

• Documentation

  • Documented the validator with usage examples, validation rules, and exit-code behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: bf7ddfb2-4f2e-4eac-a5ea-7f106ad89f7f

📥 Commits

Reviewing files that changed from the base of the PR and between b006f20 and 0b351d0.

📒 Files selected for processing (4)

• docs/SCRIPTS.md
• package.json
• test-all.mjs
• update-system.mjs

---

📝 Walkthrough

Walkthrough

This PR adds a new CLI validator validate-portals.mjs to validate portals.yml (schema, provider IDs, URL schemes, parser blocks), documents it in SCRIPTS.md, wires an npm script, adds tests exercising valid/invalid/warning cases, and updates the updater bootstrap lists.

Changes

Portals Configuration Validator

Layer / File(s)	Summary
Core portals validator implementation validate-portals.mjs	Implements validatePortalsConfig() plus CLI: provider discovery from providers/*.mjs, schema helpers, URL/provider/parser validation, file loader, self-test, formatted warnings/errors, and exit-code behavior.
npm script, docs, and updater bootstrap package.json, docs/SCRIPTS.md, update-system.mjs	Adds validate:portals npm script, documents validator usage and exit semantics in SCRIPTS.md, and includes validate-portals.mjs in SYSTEM_PATHS and BOOTSTRAP_PATHS for updater bootstrapping.
Test integration and fixtures test-all.mjs	Runs validate-portals.mjs against templates/portals.example.yml and adds a dedicated test section that writes temporary YAML fixtures to assert acceptance, rejection, and duplicate-name warnings.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant FileSystem
  participant ProviderLoader
  participant Validator
  participant Console
  CLI->>FileSystem: read portals.yml (--file)
  CLI->>ProviderLoader: load providers/*.mjs
  ProviderLoader->>Validator: provide providerIds set
  FileSystem->>Validator: provide parsed YAML config
  Validator->>Console: print warnings/errors (path: message)
  CLI->>Console: exit with code (0 success / 1 on errors)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• santifer/career-ops#921: Similar updater bootstrap changes to include new system scripts during upgrades.
• santifer/career-ops#602: Related provider/module work that affects provider IDs used by the validator.
• santifer/career-ops#725: Another PR that adds new top-level scripts and updates updater bootstrap/allowlists.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add portals.yml schema validator' clearly and concisely describes the main change—adding a new validator for portals.yml configuration.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #877: validate-portals.mjs script with schema validation, npm script, documentation, and test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #877 objectives—no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[santifer]

Merged — cryptic scanner failures from malformed portals.yml are a whole class of support issues, and this turns them into precise line-level errors. Registered it in SYSTEM_PATHS/BOOTSTRAP_PATHS while resolving the conflicts (the checklist that bit four releases). Six PRs resolved for you today — four in, with the criterion for the other five explained on #890. Quality week, @luochen211. 🚀