feat(scan): add optional always_allow tier to location_filter

Adds an optional always_allow list checked BEFORE block. A location
matching always_allow passes regardless of block. Fully backward
compatible: a config without always_allow: behaves exactly as today.

Motivation: the current filter checks block first and absolutely, so
a multi-location posting like "Remote, Belgium or France" is dropped
the moment "france" is in block — even though Belgium is an
acceptable location in the same string. always_allow is the
home-region escape hatch.

Worked example with always_allow: ["belgium"], block: ["france"]:
  - "Remote, Belgium"           pass (unchanged)
  - "Remote, Belgium or France" PASS  (was REJECT)
  - "Remote, France"            reject (unchanged)

Also:
- Adds `export` to buildLocationFilter + gates main() behind an
  import.meta.url check so the function is importable from tests
  without running scan.mjs as a script.
- Adds test-all.mjs §11 covering the 6 boundary cases (home-region
  match, always_allow beats block, block still rejects when no
  always_allow hit, empty location, case-insensitivity, backward
  compatibility when always_allow is omitted).
- templates/portals.example.yml documents the commented
  always_allow: example with an ordering note.

Refs #650

Author: jrojomartinez

scan.mjs

@@ -117,21 +117,34 @@ 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) {
+// Normalize a keyword list from portals.yml: tolerates a bare string
+// (wrapped to a 1-item array), null/undefined (→ []), and non-string
+// entries (filtered out). All survivors are lowercased.
+function normalizeKeywordList(value) {
+  if (value == null) return [];
+  const arr = Array.isArray(value) ? value : [value];
+  return arr.filter(k => typeof k === 'string').map(k => k.toLowerCase());
+}
+
+export function buildLocationFilter(locationFilter) {
   if (!locationFilter) return () => true;
-  const allow = (locationFilter.allow || []).map(k => k.toLowerCase());
-  const block = (locationFilter.block || []).map(k => k.toLowerCase());
+  const alwaysAllow = normalizeKeywordList(locationFilter.always_allow);
+  const allow = normalizeKeywordList(locationFilter.allow);
+  const block = normalizeKeywordList(locationFilter.block);
 
   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));
@@ -394,7 +407,11 @@ async function main() {
   console.log('→ Share results and get help: https://discord.gg/8pRpHETxa4');
 }
 
-main().catch(err => {
-  console.error('Fatal:', err.message);
-  process.exit(1);
-});
+// Only run main() when invoked directly (`node scan.mjs`), not when imported by tests.
+// `|| ''` guards the case where Node is invoked without a script arg (e.g. `node -e`).
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main().catch(err => {
+    console.error('Fatal:', err.message);
+    process.exit(1);
+  });
+}

templates/portals.example.yml

@@ -24,17 +24,26 @@
 # 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 is checked BEFORE block — keep this list to your home region only
+#   always_allow:
+#     - "Belgium"   # (replace with your home region)
+#     - "Brussels"
 #   allow:
 #     - "Remote"
 #     - "United States"

test-all.mjs

@@ -314,6 +314,86 @@ if (fileExists('VERSION')) {
   fail('VERSION file missing');
 }
 
+// ── 11. LOCATION FILTER — always_allow tier ───────────────────────
+
+console.log('\n11. Location filter — always_allow tier');
+
+try {
+  const { buildLocationFilter } = await import(pathToFileURL(join(ROOT, 'scan.mjs')).href);
+
+  const filter = buildLocationFilter({
+    always_allow: ['belgium', 'brussels'],
+    allow: ['europe', 'emea', 'remote'],
+    block: ['france', 'germany', 'united states'],
+  });
+
+  // Case 1: home-region passes regardless of other text
+  if (filter('Brussels, Belgium') === true) pass('Brussels, Belgium passes (always_allow hit)');
+  else fail('Brussels, Belgium should pass');
+
+  // Case 2: always_allow wins over block (THE motivating case for this tier)
+  if (filter('Remote, Belgium or France') === true) pass('Remote, Belgium or France passes (always_allow beats block)');
+  else fail('Remote, Belgium or France should pass — always_allow must win over block');
+
+  // Case 3: no always_allow hit, block still rejects
+  if (filter('Paris, France') === false) pass('Paris, France is rejected (block still applies)');
+  else fail('Paris, France should be rejected');
+
+  // Case 4: empty location → pass (existing semantics, unchanged)
+  if (filter('') === true) pass('empty location passes (unchanged semantics)');
+  else fail('empty location should pass');
+
+  // Case 5: case-insensitivity
+  if (filter('BRUSSELS, BELGIUM') === true) pass('case-insensitive match works');
+  else fail('case-insensitive match failed');
+
+  // Case 6: backward compatibility — no always_allow key behaves like stock allow/block
+  const stockFilter = buildLocationFilter({
+    allow: ['europe', 'remote'],
+    block: ['france'],
+  });
+  if (stockFilter('Remote, Belgium or France') === false) pass('without always_allow, block still wins (backward compatible)');
+  else fail('without always_allow, behaviour must match stock allow/block (block wins)');
+
+  // Case 7: null/missing locationFilter → pass-all filter (early-return path)
+  const nullFilter = buildLocationFilter(null);
+  if (nullFilter('Anywhere on Earth') === true && nullFilter('') === true) {
+    pass('null locationFilter returns a pass-all filter (early-return path)');
+  } else {
+    fail('null locationFilter should return a pass-all filter');
+  }
+
+  // Case 8: string-instead-of-array → wrapped to a 1-item list
+  const stringFilter = buildLocationFilter({ always_allow: 'belgium', block: ['france'] });
+  if (stringFilter('Remote, Belgium or France') === true) {
+    pass('always_allow as a bare string is wrapped to a single-item list');
+  } else {
+    fail('always_allow as a bare string should still work');
+  }
+
+  // Case 9: null/non-string items are filtered out (no crash, no false matches)
+  const messyFilter = buildLocationFilter({
+    always_allow: [null, 'belgium', 42, undefined],
+    block: ['france', null, 7],
+  });
+  if (messyFilter('Brussels, Belgium') === true && messyFilter('Paris, France') === false) {
+    pass('non-string entries (null, numbers, undefined) are filtered out without crashing');
+  } else {
+    fail('mixed-type keyword lists should not crash and should still match string entries');
+  }
+
+  // Case 10: all-null/non-string list → empty after normalization (no false rejects)
+  const allBadFilter = buildLocationFilter({ block: [null, 42, undefined], allow: ['remote'] });
+  if (allBadFilter('Remote') === true) {
+    pass('a block list with only non-string entries normalizes to [] (no false rejects)');
+  } else {
+    fail('non-string-only block list should not cause rejection');
+  }
+
+} catch (e) {
+  fail(`always_allow tests crashed: ${e.message}`);
+}
+
 // ── SUMMARY ─────────────────────────────────────────────────────
 
 console.log('\n' + '='.repeat(50));