feat(scan): add optional always_allow tier to location_filter

`location_filter` currently checks `block` first and absolutely, so a
multi-location posting like "Remote, Belgium or France" is rejected the
moment `france` is in `block` — even though Belgium is an acceptable
location in the same string.

Add an optional `always_allow` list, checked before `block`. A location
matching it passes regardless of `block`. Fully backward-compatible: a
config with no `always_allow:` key behaves exactly as before (the new
const resolves to [] and the guard short-circuits).

Refs #650

Author: jrojomartinez

scan.mjs

@@ -136,21 +136,25 @@ function buildTitleFilter(titleFilter) {
 
 // ── Location filter ─────────────────────────────────────────────────
 // Optional. If `location_filter` is absent from portals.yml, all locations pass.
-// Semantics:
+// Semantics (case-insensitive substring, in this order):
 //   - Empty location string → pass (don't penalize missing data)
-//   - `block` matches → reject (takes precedence over allow)
+//   - `always_allow` matches → pass (takes precedence over `block` — lets a
+//     multi-location string like "Remote, Belgium or France" through because
+//     the home region is an option, even though "france" is blocked)
+//   - `block` matches → reject
 //   - `allow` empty → pass (already cleared block)
 //   - `allow` non-empty → must match at least one keyword
-// All matches are case-insensitive substring.
 
 function buildLocationFilter(locationFilter) {
   if (!locationFilter) return () => true;
+  const alwaysAllow = (locationFilter.always_allow || []).map(k => k.toLowerCase());
   const allow = (locationFilter.allow || []).map(k => k.toLowerCase());
   const block = (locationFilter.block || []).map(k => k.toLowerCase());
 
   return (location) => {
     if (!location) return true;
     const lower = location.toLowerCase();
+    if (alwaysAllow.length > 0 && alwaysAllow.some(k => lower.includes(k))) return true;
     if (block.length > 0 && block.some(k => lower.includes(k))) return false;
     if (allow.length === 0) return true;
     return allow.some(k => lower.includes(k));

templates/portals.example.yml

@@ -24,17 +24,25 @@
 # Filter scanned jobs by location. Applied AFTER title filter, BEFORE dedup.
 # If this entire block is absent, all locations pass (current default behavior).
 #
-# Semantics:
+# Semantics (case-insensitive substring, in this order):
 #   - Empty location string on a job → pass (don't penalize missing data)
-#   - Any `block` keyword present → reject (takes precedence over allow)
+#   - Any `always_allow` keyword present → pass (takes precedence over `block`)
+#   - Any `block` keyword present → reject
 #   - `allow` empty → pass (already cleared block)
 #   - `allow` non-empty → must match at least one keyword
-# All matches are case-insensitive substring.
+#
+# `always_allow` is optional. It rescues multi-location postings that name your
+# home region: with always_allow ["Belgium"] and block ["France"], a job listed
+# "Remote, Belgium or France" passes (Belgium wins), while "Remote, France" is
+# still rejected. Omit always_allow entirely and the filter behaves as before.
 #
 # Example below targets US-based remote + a couple of US metros, blocking
 # common foreign hubs. Customize to your geography.
 
 # location_filter:
+#   always_allow:
+#     - "Belgium"
+#     - "Brussels"
 #   allow:
 #     - "Remote"
 #     - "United States"