jd-intel 0.8.3 → 0.10.0

package/src/adapters/workday.js

@@ -1,9 +1,17 @@
-import { normalize, stripHtml } from '../normalizer.js';
+import { normalize } from '../normalizer.js';
 import { atsErrorFromStatus } from '../errors.js';
+import { makeLocationMatcher } from '../filters.js';
+import { atsFetch } from '../http.js';
+import { orgHost } from '../boards.js';
 
 const MAX_DETAIL_FETCHES = 100;
 const LIST_PAGE_SIZE = 20;
-const LIST_PAGE_HARD_CAP = 100; // <= 2000 list items scanned per request
+// Upper bound on list pages per call: 100 pages of 20 = at most 2000
+// postings scanned. Paging usually stops sooner, on a short page or when
+// offset reaches the first page's total (see the loop below).
+const LIST_PAGE_HARD_CAP = 100;
+// A multi-location posting's list row reads "2 Locations", "14 Locations".
+const MULTI_LOCATION = /^\s*\d+\s+locations?\s*$/;
 
 /**
  * Fetch jobs from a Workday tenant via the public "CXS" JSON API.
@@ -25,7 +33,9 @@ const LIST_PAGE_HARD_CAP = 100; // <= 2000 list items scanned per request
  * detail set.
  *
  * @param {string} slug - normalized company slug (registry routing key)
- * @param {object} [ctx] - { config:{tenant,env,site}, companyName, filterContext }
+ * @param {object} [ctx] - { config:{tenant,env,site}, companyName, filterContext, report };
+ *   report is called once, after hydration, with
+ *   { ats, listed, prefiltered, hydrated, capped, org_name, org_url } when given
  * @returns {Promise<Array>} Normalized job objects
  */
 export async function fetchWorkday(slug, ctx = {}) {
@@ -40,27 +50,46 @@ export async function fetchWorkday(slug, ctx = {}) {
   const postings = [];
   let offset = 0;
   let pages = 0;
-  while (pages < LIST_PAGE_HARD_CAP) {
-    const resp = await fetch(`${base}/jobs`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ appliedFacets: {}, limit: LIST_PAGE_SIZE, offset, searchText: '' }),
-    });
+  let firstTotal = 0;
+  let listCapped = false;
+  while (true) {
+    if (pages >= LIST_PAGE_HARD_CAP) {
+      listCapped = true;
+      break;
+    }
+    let resp;
+    try {
+      resp = await atsFetch(`${base}/jobs`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ appliedFacets: {}, limit: LIST_PAGE_SIZE, offset, searchText: '' }),
+      });
+    } catch (err) {
+      // A 429 or 5xx that outlasted the retries, or a network failure.
+      // After the first page, keep the postings already read.
+      if (offset === 0) throw err;
+      break;
+    }
 
     if (!resp.ok) {
-      if (resp.status === 404) return []; // wrong site / no such board
       if (offset === 0) {
+        if (resp.status === 404) return []; // wrong site / no such board
         throw atsErrorFromStatus(resp.status, `Workday API error for ${slug} (${tenant}/${env}/${site}): ${resp.status}`);
       }
-      break; // mid-paging failure: keep what we have
+      break; // mid-paging failure (any status): keep what we have
     }
 
     const data = await resp.json();
     const page = data.jobPostings || [];
+    // Some tenants report the real `total` only at offset 0 and send
+    // `total: 0` on every later page, so only the first page's figure
+    // is trusted. A short page is the other stop signal.
+    if (pages === 0) firstTotal = data.total || 0;
     postings.push(...page);
     pages += 1;
     offset += LIST_PAGE_SIZE;
-    if (page.length === 0 || offset >= (data.total || 0)) break;
+    if (page.length < LIST_PAGE_SIZE) break;
+    if (firstTotal > 0 && offset >= firstTotal) break;
   }
 
   // 2. Filter-aware candidate selection BEFORE the N+1 detail cost.
@@ -72,18 +101,23 @@ export async function fetchWorkday(slug, ctx = {}) {
     const re = new RegExp(fc.titleFilter, 'i');
     candidates = candidates.filter(p => re.test(p.title || ''));
   }
+  // Location rows go through the applyFilters matcher, so the pre-filter
+  // keeps exactly the rows the pass after hydration would (issue #61).
+  // "2 Locations" says nothing about where: the row stays a candidate
+  // through both filters and that later pass decides on the detail's
+  // location list.
   if (Array.isArray(fc.locationIncludes) && fc.locationIncludes.length > 0) {
-    const inc = fc.locationIncludes.map(s => String(s).toLowerCase());
+    const inc = fc.locationIncludes.map(makeLocationMatcher);
     candidates = candidates.filter(p => {
       const loc = (p.locationsText || '').toLowerCase();
-      return inc.some(s => loc.includes(s));
+      return MULTI_LOCATION.test(loc) || inc.some(m => m(loc));
     });
   }
   if (Array.isArray(fc.locationExcludes) && fc.locationExcludes.length > 0) {
-    const exc = fc.locationExcludes.map(s => String(s).toLowerCase());
+    const exc = fc.locationExcludes.map(makeLocationMatcher);
     candidates = candidates.filter(p => {
       const loc = (p.locationsText || '').toLowerCase();
-      return !exc.some(s => loc.includes(s));
+      return MULTI_LOCATION.test(loc) || !exc.some(m => m(loc));
     });
   }
   if (typeof fc.postedWithinDays === 'number') {
@@ -91,33 +125,44 @@ export async function fetchWorkday(slug, ctx = {}) {
   }
 
   // 3. Bound the detail-fetch set.
-  //    NOTE: huge-tenant coverage is intentionally capped for v1
-  //    (Salesforce ~1398 postings). A description `filter` is applied
-  //    by the library AFTER this returns, so for that case we keep the
-  //    full backstop instead of truncating tightly to `limit` (which
-  //    could hydrate jobs that all fail the regex while better matches
-  //    go unscanned). Proper fix (smart pagination / rate-limited
-  //    concurrency / surfaced truncation) is tracked in #26, to be
-  //    designed alongside retry/rate-limit work (#7).
+  //    NOTE: huge-tenant coverage is intentionally capped for v1. Two
+  //    caps apply: the list scan above stops at LIST_PAGE_HARD_CAP pages
+  //    (2000 postings, enough for Salesforce's ~1398), and the detail set
+  //    is cut to MAX_DETAIL_FETCHES here. A description `filter` is
+  //    applied by the library AFTER this returns, so for that case we
+  //    keep the full backstop instead of truncating tightly to `limit`
+  //    (which could hydrate jobs that all fail the regex while better
+  //    matches go unscanned). The library pages with `offset` after this
+  //    returns, so the budget covers the page plus what precedes it.
+  //    Proper fix (smart pagination / rate-limited concurrency / surfaced
+  //    truncation) is tracked in #26, to be designed alongside
+  //    retry/rate-limit work (#7).
   const limit = typeof fc.limit === 'number' && fc.limit > 0 ? fc.limit : 100;
-  const cap = fc.filter ? MAX_DETAIL_FETCHES : Math.min(limit, MAX_DETAIL_FETCHES);
-  candidates = candidates.slice(0, cap);
+  const skip = typeof fc.offset === 'number' && fc.offset > 0 ? fc.offset : 0;
+  const cap = fc.filter ? MAX_DETAIL_FETCHES : Math.min(skip + limit, MAX_DETAIL_FETCHES);
+  const hydrate = candidates.slice(0, cap);
 
-  // 4. Hydrate descriptions via the per-posting detail endpoint.
-  const jobs = await Promise.all(candidates.map(async (p) => {
+  // 4. Hydrate descriptions via the per-posting detail endpoint. The detail
+  //    also carries `hiringOrganization: { name, url }` next to
+  //    jobPostingInfo; the list does not. Kept per posting in list order so
+  //    the one reported is the first hydrated posting's, not whichever
+  //    detail answered first (a tenant can post under several entities).
+  const orgs = [];
+  const jobs = await Promise.all(hydrate.map(async (p, i) => {
     const externalPath = p.externalPath || ''; // already begins with '/job/...'
     let info = {};
     try {
       // externalPath already carries the '/job/...' segment, so it is
       // concatenated directly onto the CXS base. Inserting another
       // '/job' here yields '/job/job/...' which Workday rejects (422).
-      const dResp = await fetch(`${base}${externalPath}`);
+      const dResp = await atsFetch(`${base}${externalPath}`);
       if (dResp.ok) {
         const detail = await dResp.json();
         info = detail.jobPostingInfo || {};
+        orgs[i] = detail.hiringOrganization || null;
       }
     } catch {
-      // detail failed: fall back to list fields, empty description
+      // detail failed, retries included: fall back to list fields, empty description
     }
 
     return normalize({
@@ -126,7 +171,9 @@ export async function fetchWorkday(slug, ctx = {}) {
       title: p.title || info.title || '',
       department: '',
       location: info.location || p.locationsText || '',
-      description: stripHtml(info.jobDescription || ''),
+      locations: info.additionalLocations || [],
+      workplace: parseWorkdayRemoteType(info.remoteType),
+      description: info.jobDescription || '',
       url: `https://${tenant}.${env}.myworkdayjobs.com/${site}${externalPath}`,
       postedAt: parseWorkdayDate(info.startDate) || normalizePostedOn(p.postedOn),
       salary: null, // normalizer extracts from description text
@@ -139,9 +186,38 @@ export async function fetchWorkday(slug, ctx = {}) {
     }, 'workday');
   }));
 
+  // Nothing hydrated (a filter miss, an empty site) means no detail was
+  // read, so the org is unknown rather than absent: null, null.
+  if (typeof ctx.report === 'function') {
+    const org = orgs.find(Boolean) || {};
+    ctx.report({
+      ats: 'workday',
+      listed: postings.length,
+      prefiltered: candidates.length,
+      hydrated: hydrate.length,
+      capped: listCapped || hydrate.length < candidates.length,
+      org_name: org.name || null,
+      org_url: orgHost(org.url),
+    });
+  }
+
   return jobs;
 }
 
+/**
+ * Detail `remoteType` is free text set per tenant: "Remote", "Hybrid",
+ * "Office - Flexible", "On-site". A flexible office arrangement counts as
+ * hybrid, so that check runs before the office one. Some tenants send no
+ * value at all; the location string decides then.
+ */
+function parseWorkdayRemoteType(remoteType) {
+  const s = String(remoteType || '').toLowerCase();
+  if (/remote/.test(s)) return 'remote';
+  if (/hybrid|flexible/.test(s)) return 'hybrid';
+  if (/office|on-?site/.test(s)) return 'onsite';
+  return null;
+}
+
 /**
  * Workday list `postedOn` is a relative string ("Posted Today",
  * "Posted 5 Days Ago", "Posted 30+ Days Ago"). Decide membership in

package/src/boards.js

@@ -0,0 +1,80 @@
+/**
+ * The boards[] entry of a fetchJobsDetailed result (issues #58, #60, #87).
+ *
+ * A board is one (ats, slug) the library fetched, with what came back. The
+ * fields fall in three groups: what the registry or the caller said about
+ * it (`name`, `site`), what the fetch found (`jobs_found`, `matched`,
+ * `scan`), and what the board says about itself (`org_name`, `org_url`).
+ * Only the adapters can read the third group, and they hand it over through
+ * ctx.report. Both fields are null where the platform exposes nothing, and
+ * they are never filled from the slug or the registry name: a slug is an
+ * address, not a confirmed identity.
+ */
+
+const BOARD_URLS = {
+  greenhouse: (slug) => `https://boards.greenhouse.io/${slug}`,
+  lever: (slug) => `https://jobs.lever.co/${slug}`,
+  ashby: (slug) => `https://jobs.ashbyhq.com/${slug}`,
+  smartrecruiters: (slug) => `https://careers.smartrecruiters.com/${slug}`,
+  teamtailor: (slug) => `https://${slug}.teamtailor.com`,
+  recruitee: (slug) => `https://${slug}.recruitee.com`,
+  workday: (slug, config) => (config ? `https://${config.tenant}.${config.env}.myworkdayjobs.com/${config.site}` : null),
+};
+
+// Domains the platforms own. A link there (boards.greenhouse.io,
+// jobs.lever.co, testco.recruitee.com, cisco.wd5.myworkdayjobs.com) says
+// which ATS hosts the board, nothing about whose board it is.
+const ATS_DOMAINS = ['greenhouse.io', 'lever.co', 'ashbyhq.com', 'smartrecruiters.com', 'teamtailor.com', 'recruitee.com', 'myworkdayjobs.com'];
+
+/**
+ * The page a person opens to see the board, or null when the ATS is unknown
+ * or, for Workday, no {tenant, env, site} is at hand.
+ */
+export function boardUrl(ats, slug, config) {
+  const build = BOARD_URLS[ats];
+  return build ? build(slug, config) : null;
+}
+
+/**
+ * The bare hostname a board's link points at ("jobs.example.com"), for
+ * org_url. Null when the link is missing or malformed, and null when the
+ * host belongs to an ATS, since that carries no signal about the company.
+ */
+export function orgHost(link) {
+  let host;
+  try {
+    host = new URL(link).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  if (!host || ATS_DOMAINS.some(d => host === d || host.endsWith(`.${d}`))) return null;
+  return host;
+}
+
+/**
+ * @param {object} board
+ * @param {string} board.ats
+ * @param {string} board.slug - The slug the adapter was called with (canonical casing on a registry hit)
+ * @param {string|null} board.name - Registry row name; null for a probe or an override
+ * @param {object} [board.config] - Workday {tenant, env, site}, when one was used
+ * @param {string|null} board.org_name - The organization name the ATS response states, else null
+ * @param {string|null} board.org_url - The careers or company host the board links to (see orgHost), else null
+ * @param {number} board.jobs_found - Rows the board listed before any filter: the list count an adapter reported through ctx.report when it filters before hydrating, else the rows it returned
+ * @param {number} board.matched - Rows left after filters, before offset and limit
+ * @param {object|null} board.scan - The { listed, prefiltered, hydrated, capped } counts the adapter reported through ctx.report, else null
+ */
+export function describeBoard({ ats, slug, name = null, config, org_name = null, org_url = null, jobs_found, matched = 0, scan = null }) {
+  return {
+    ats,
+    slug,
+    name,
+    site: ats === 'workday' && config ? config.site : null,
+    board_url: boardUrl(ats, slug, config),
+    org_name,
+    org_url,
+    jobs_found,
+    matched,
+    selected: true,
+    scan,
+  };
+}

package/src/cli.js

@@ -9,8 +9,10 @@
  *   jd-intel registry search <query>
  */
 
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { fetchJobs } from './index.js';
-import { detectAts, searchRegistry } from './registry.js';
+import { detectAtsDetailed, searchRegistry } from './registry.js';
 
 const [,, command, ...args] = process.argv;
 
@@ -85,7 +87,7 @@ async function main() {
       console.log(`Found ${jobs.length} jobs\n`);
 
       for (const job of jobs.slice(0, 20)) {
-        const salary = job.salary ? ` | $${job.salary.min?.toLocaleString()}-$${job.salary.max?.toLocaleString()}` : '';
+        const salary = job.salary ? ` | ${formatSalary(job.salary)}` : '';
         const loc = job.location ? ` | ${job.location}` : '';
         const dept = job.department ? ` [${job.department}]` : '';
         console.log(`  ${job.title}${dept}${loc}${salary}`);
@@ -111,13 +113,17 @@ async function main() {
       const company = args[0];
       if (!company) { console.error('Usage: jd-intel detect <company>'); process.exit(1); }
       console.log(`Detecting ATS for ${company}...`);
-      const results = await detectAts(company);
-      if (results.length === 0) {
-        console.log('No ATS board found for this company.');
-      } else {
-        for (const r of results) {
-          console.log(`  Found: ${r.ats} (slug: ${r.slug})`);
-        }
+      const { boards, failed } = await detectAtsDetailed(company);
+      for (const b of boards) {
+        console.log(`  Found: ${b.ats} (slug: ${b.slug}, ${b.source === 'registry' ? 'in the registry' : 'live probe'})`);
+      }
+      for (const f of failed) {
+        console.log(`  Could not check ${f.ats}: ${f.message}`);
+      }
+      if (boards.length === 0) {
+        console.log(failed.length > 0
+          ? 'No ATS board confirmed. At least one check failed, so this is not a definite miss. Retry in a moment.'
+          : 'No ATS board found for this company.');
       }
       break;
     }
@@ -162,8 +168,8 @@ Fetch options:
   --title-filter pattern          Regex matched against TITLE only (role identity)
   --filter pattern                Regex matched across title, department, description (topic/scope)
   --posted-within-days N          Only jobs posted in the last N days
-  --location-include "A,B,C"      Keep jobs whose location contains any of these
-  --location-exclude "A,B,C"      Drop jobs whose location contains any of these
+  --location-include "A,B,C"      Keep jobs where any listed location contains one of these
+  --location-exclude "A,B,C"      Drop jobs only when every listed location contains one of these
   --limit N                       Cap results (default 100)
   --json                          Output full JSON
 
@@ -184,7 +190,32 @@ Examples:
   }
 }
 
-main().catch(err => {
-  console.error('Error:', err.message);
-  process.exit(1);
-});
+export function formatSalary({ min, max, currency, period }) {
+  const hasMin = min != null;
+  const hasMax = max != null;
+  let range;
+  if (hasMin && hasMax) range = `${min.toLocaleString()}-${max.toLocaleString()}`;
+  else if (hasMin) range = `from ${min.toLocaleString()}`;
+  else range = `up to ${max.toLocaleString()}`;
+  const unit = period === 'hour' ? '/hr' : period === 'month' ? '/mo' : '';
+  return `${range} ${currency}${unit}`;
+}
+
+// Boot only when this file is the script Node was started with, so a test
+// can import formatSalary without running a command. argv[1] is resolved
+// through realpath because npm installs the bin as a symlink into .bin/,
+// while import.meta.url already points at the real file.
+function isEntrypoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  main().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}

package/src/errors.js

@@ -34,6 +34,20 @@ export class AtsError extends Error {
   }
 }
 
+/**
+ * Thrown when a call cannot proceed because of its arguments: a missing
+ * company, an unknown ATS name, a regex that does not compile. Carries
+ * `code: 'invalid_args'` so callers tell a bad request from a failed fetch
+ * (AtsError) without reading the message.
+ */
+export class ArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ArgumentError';
+    this.code = ERROR_CODES.INVALID_ARGS;
+  }
+}
+
 /**
  * Helper for adapters: build an AtsError from an HTTP status (429 => rate
  * limited, anything else => unreachable) with the given message.

package/src/filters.js

@@ -1,33 +1,56 @@
+import { ArgumentError } from './errors.js';
+
 /**
  * Apply filters to a list of normalized jobs.
  *
  * Facts go here (deterministic field matches). Interpretations stay with the
  * caller — this module does substring matching on structured fields, nothing
  * semantic.
+ *
+ * Returns the page as an array. applyFiltersDetailed returns the same page
+ * plus total_matched, the match count before offset and limit.
  */
 export function applyFilters(jobs, options = {}) {
-  const {
-    titleFilter,
-    filter,
-    postedWithinDays,
-    locationIncludes,
-    locationExcludes,
-    limit = 100,
-  } = options;
+  return applyFiltersDetailed(jobs, options).jobs;
+}
+
+/**
+ * Filter, sort, then page.
+ *
+ * Order is applied after the filters and before offset and limit, so a cut
+ * drops the oldest matches first. 'newest' sorts by postedAt descending with
+ * undated jobs last and ties broken by id, which keeps pages deterministic.
+ * 'board' keeps the order the adapter returned.
+ *
+ * @returns {{ jobs: Array, total_matched: number }}
+ */
+export function applyFiltersDetailed(jobs, options = {}) {
+  const { order = 'newest', offset = 0, limit = 100 } = options;
+  const matched = filterJobs(jobs, options);
+  return { jobs: pageJobs(matched, { order, offset, limit }), total_matched: matched.length };
+}
+
+/**
+ * The filter step on its own: every job that passes titleFilter, filter,
+ * postedWithinDays and the location filters, in the order given. No sort
+ * and no paging, so fetchJobsDetailed can count the matches per board
+ * before the page cut removes them.
+ */
+export function filterJobs(jobs, options = {}) {
+  const { titleFilter, filter, postedWithinDays, locationIncludes, locationExcludes } = options;
+  const { title, topic } = compileFilterPatterns({ titleFilter, filter });
 
   let result = jobs;
 
-  if (titleFilter) {
-    const pattern = new RegExp(titleFilter, 'i');
-    result = result.filter(j => pattern.test(j.title || ''));
+  if (title) {
+    result = result.filter(j => title.test(j.title || ''));
   }
 
-  if (filter) {
-    const pattern = new RegExp(filter, 'i');
+  if (topic) {
     result = result.filter(j =>
-      pattern.test(j.title || '') ||
-      pattern.test(j.department || '') ||
-      pattern.test(j.description || '')
+      topic.test(j.title || '') ||
+      topic.test(j.department || '') ||
+      topic.test(j.description || '')
     );
   }
 
@@ -42,36 +65,106 @@ export function applyFilters(jobs, options = {}) {
 
   if (Array.isArray(locationIncludes) && locationIncludes.length > 0) {
     const matchers = locationIncludes.map(makeLocationMatcher);
-    result = result.filter(j => {
-      const loc = (j.location || '').toLowerCase();
-      return matchers.some(m => m(loc));
-    });
+    result = result.filter(j => jobLocations(j).some(loc => matchers.some(m => m(loc))));
   }
 
   if (Array.isArray(locationExcludes) && locationExcludes.length > 0) {
     const matchers = locationExcludes.map(makeLocationMatcher);
-    result = result.filter(j => {
-      const loc = (j.location || '').toLowerCase();
-      return !matchers.some(m => m(loc));
-    });
+    result = result.filter(j => !jobLocations(j).every(loc => matchers.some(m => m(loc))));
   }
 
-  if (typeof limit === 'number' && result.length > limit) {
-    result = result.slice(0, limit);
+  return result;
+}
+
+/**
+ * Sort, then cut the page (see applyFiltersDetailed for the order rules).
+ */
+export function pageJobs(jobs, { order = 'newest', offset = 0, limit = 100 } = {}) {
+  let result = jobs;
+
+  if (order !== 'board') {
+    result = [...result].sort(byNewest);
+  }
+
+  const start = typeof offset === 'number' && offset > 0 ? offset : 0;
+  const end = typeof limit === 'number' ? start + limit : undefined;
+  if (start > 0 || (end !== undefined && result.length > end)) {
+    result = result.slice(start, end);
   }
 
   return result;
 }
 
 /**
- * Build a matcher for a single location keyword.
+ * Compile the two regex arguments, or throw ArgumentError naming the one
+ * that does not compile. Both are case-insensitive. fetchJobsDetailed calls
+ * this before its first request, so a bad pattern is reported as a bad
+ * argument and costs no upstream traffic.
+ *
+ * @returns {{ title: RegExp|null, topic: RegExp|null }}
+ */
+export function compileFilterPatterns({ titleFilter, filter } = {}) {
+  return {
+    title: titleFilter ? compilePattern(titleFilter, 'titleFilter') : null,
+    topic: filter ? compilePattern(filter, 'filter') : null,
+  };
+}
+
+function compilePattern(source, name) {
+  try {
+    return new RegExp(source, 'i');
+  } catch (err) {
+    throw new ArgumentError(`${name}: ${err.message}`);
+  }
+}
+
+/**
+ * Every location a job is open in, lowercased. A job passes an include when
+ * any of them matches and is dropped by an exclude only when all of them
+ * match: a role open in Berlin and New York is still open in Berlin for
+ * someone excluding the US (issue #68). Jobs from before `locations`
+ * existed fall back to the single `location` string.
+ */
+function jobLocations(job) {
+  const list = Array.isArray(job.locations) && job.locations.length > 0
+    ? job.locations
+    : [job.location || ''];
+  return list.map(loc => String(loc).toLowerCase());
+}
+
+function postedTime(job) {
+  if (!job.postedAt) return null;
+  const t = new Date(job.postedAt).getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+function byNewest(a, b) {
+  const ta = postedTime(a);
+  const tb = postedTime(b);
+  if (ta !== tb) {
+    if (ta === null) return 1;
+    if (tb === null) return -1;
+    return tb - ta;
+  }
+  const ia = a.id || '';
+  const ib = b.id || '';
+  return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+
+/**
+ * Build a matcher for a single location keyword. The matcher takes a
+ * lowercased location string.
  *
  * Short tokens (≤4 chars) use word-boundary matching to prevent substring
  * collisions like "US" matching "Australia", "Brussels", "Belarus", or "UK"
- * matching "Auckland". Longer tokens use substring matching so phrases like
+ * matching "Ukraine". Longer tokens use substring matching so phrases like
  * "United States" can match "United States of America".
+ *
+ * Exported for the Workday list pre-filter, so one rule (trim, empty
+ * keywords never match, word boundaries for short tokens) applies before
+ * and after detail hydration (issue #61).
  */
-function makeLocationMatcher(needle) {
+export function makeLocationMatcher(needle) {
   const lower = (needle || '').toLowerCase().trim();
   if (!lower) return () => false;
   if (lower.length <= 4) {