openings 0.1.36 → 0.1.37

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "Find evidence-grounded jobs, including relevant roles you may not have searched for, without accounts or API keys.",
   "author": { "name": "Openings contributors" },
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "A free, candidate-safe job-search substrate for AI agents",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/abhay-avagama/hiring-agent.git" },

package/src/catalog.ts

@@ -2,7 +2,7 @@ import { CASCADE_MINIMUM, CASCADE_WINDOWS, type Company, type Job, type JobAge,
 import { decodeEntities, providerSpec, type JsonGet } from "./providers.ts";
 import { crawlSite, sitePostingsToJobs } from "./jobposting-site.ts";
 import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
-import { statedExperience } from "./experience.ts";
+import { experienceMatches, normalizeJobExperience } from "./experience.ts";
 
 type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
 
@@ -102,7 +102,7 @@ export function createCatalog(options: CatalogOptions): Catalog {
       let job = (await fetchJobs(company)).find((candidate) => candidate.id === id) ?? null;
       if (job && !job.description.trim()) job = { ...job, description: await fetchJobDescription(company, job, fetcher) };
       if (job && !job.description.trim()) throw new Error(`Full description unavailable for job: ${id}`);
-      return job;
+      return job ? normalizeJobExperience(job) : null;
     },
   };
 }
@@ -119,10 +119,10 @@ export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: num
 
 /** Keyword search newest first. Without maxAgeDays it walks 7, 14, 30, then everything until CASCADE_MINIMUM results appear; the window used rides on the result. */
 export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): SearchResult {
-  const matched = jobs.filter((job) => matches(job, query)).filter((job) => {
+  const matched = jobs.filter((job) => matches(job, query)).map(normalizeJobExperience).filter((job) => {
     if (query.experienceYears === undefined) return true;
-    const experience = job.experience === undefined ? statedExperience(job.description) : job.experience;
-    return experience ? query.experienceYears >= experience.min && (experience.max === undefined || query.experienceYears <= experience.max) : query.includeUnknownExperience === true;
+    const experience = job.experience;
+    return experience ? experienceMatches(experience, query.experienceYears) : query.includeUnknownExperience === true;
   });
   const run = (days: number) => matched.filter((job) => withinWindow(job, days, now)).sort((left, right) => postedTime(right) - postedTime(left) || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
   const steps: SearchWindow["steps"] = [];
@@ -133,7 +133,7 @@ export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.n
     if (found.length >= CASCADE_MINIMUM) break;
   }
   const offset = query.offset ?? 0, limit = query.limit ?? 50;
-  const result = found.slice(offset, offset + limit).map((job) => toSummary(query.experienceYears !== undefined && job.experience === undefined ? { ...job, experience: statedExperience(job.description) } : job, now)) as SearchResult;
+  const result = found.slice(offset, offset + limit).map((job) => toSummary(job, now)) as SearchResult;
   Object.defineProperty(result, "pagination", { value: { offset, limit, total: found.length, nextOffset: offset + limit < found.length ? offset + limit : null }, enumerable: false });
   Object.defineProperty(result, "window", { value: { daysUsed: steps[steps.length - 1]!.days, widened: steps.length > 1, steps } satisfies SearchWindow, enumerable: false });
   return result;

package/src/crawler.ts

@@ -1,5 +1,5 @@
 import type { FetchJobsObserver } from "./catalog.ts";
-import { statedExperience } from "./experience.ts";
+import { EXPERIENCE_VERSION, normalizeJobExperience } from "./experience.ts";
 import { partitionFor, type Company, type CrawlFailure, type CrawlReport, type CrawlSourceResult, type Job, type JobPartition, type JobSnapshot } from "./types.ts";
 
 export interface SnapshotStore {
@@ -49,23 +49,22 @@ export function createCrawler(options: CrawlerOptions): Crawler {
 
   /** Required experience for every job: from its description, the last crawl's reading, or a paced detail fetch for recent roles in describeCountries. */
   async function withExperience(source: Company, jobs: Job[], previous: Job[] | undefined): Promise<Job[]> {
-    const known = new Map((previous ?? []).filter((job) => job.experience !== undefined).map((job) => [job.id, job.experience]));
+    const known = new Map((previous ?? []).map(normalizeJobExperience).filter((job) => job.experienceVersion === EXPERIENCE_VERSION && job.experience !== undefined).map((job) => [job.id, job]));
     const since = now().getTime() - 30 * 86_400_000;
     const deadline = Date.now() + DESCRIBE_BUDGET_MS;
     let budget = DESCRIBE_LIMIT;
     const out: Job[] = [];
     for (const job of jobs) {
-      if (job.experience !== undefined) out.push(job);
-      else if (job.description.trim()) out.push({ ...job, experience: statedExperience(job.description) });
-      else if (known.has(job.id)) out.push({ ...job, experience: known.get(job.id) });
+      if (job.description.trim() || job.experienceVersion === EXPERIENCE_VERSION) out.push(normalizeJobExperience(job));
+      else if (known.has(job.id)) out.push({ ...job, description: known.get(job.id)!.description, experience: known.get(job.id)!.experience, experienceVersion: EXPERIENCE_VERSION });
       else if (options.describe && budget > 0 && Date.now() < deadline && job.eligibleCountries.some((code) => describeCountries.has(code)) && Date.parse(job.updatedAt ?? "") >= since) {
         budget -= 1;
         try {
           if (options.workdayPageDelayMs) await pacingSleep(options.workdayPageDelayMs);
           const description = await options.describe(source, job);
-          out.push(description.trim() ? { ...job, experience: statedExperience(description) } : job);
-        } catch { out.push(job); } // unread; the next crawl tries again
-      } else out.push(job);
+          out.push(normalizeJobExperience({ ...job, description }));
+        } catch { out.push(normalizeJobExperience(job)); } // unread; the next crawl tries again
+      } else out.push(normalizeJobExperience(job));
     }
     return out;
   }

package/src/experience.ts

@@ -1,7 +1,8 @@
-import { decodeEntities } from "./providers.ts";
+import { plainText } from "./providers.ts";
 
 /** Years of experience a posting asks for, read from its own text. */
-export interface Experience { min: number; max?: number }
+export interface Experience { min: number; max?: number; maxOpen?: boolean }
+export const EXPERIENCE_VERSION = 2;
 
 const WORDS: Record<string, number> = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10, twelve: 12, fifteen: 15 };
 const NUM = String.raw`(\d{1,2}(?:\.\d)?|${Object.keys(WORDS).join("|")})`;
@@ -11,6 +12,7 @@ const YEARS_THEN_EXPERIENCE = new RegExp(String.raw`${RANGE}(?:\s+of)?(?:\s+[\w/
 const EXPERIENCE_THEN_YEARS = new RegExp(String.raw`\b(?:experiences?|exp)\b[^.\n\d]{0,30}?${RANGE}`, "gi");
 // "minimum 15+ years" with no word "experience" after it.
 const MINIMUM_YEARS = new RegExp(String.raw`\b(?:minimum|min\.?|at least|atleast)\s*(?:of\s*)?${RANGE}`, "gi");
+const STANDALONE_YEARS = new RegExp(String.raw`^[ \t]*(?:[•·-][ \t]*)?${RANGE}[ \t]*[.!]?[ \t]*$`, "gmi");
 // Company history reads the same way ("our 135 years of experience"); skip matches that talk about the employer.
 const ABOUT_EMPLOYER = /\b(?:our (?:company|firm|group|organi[sz]ation|brands?|history|legacy)|(?:company|firm|group) (?:has|with)|founded|established|history|legacy|heritage)\b[^.\n?!:;•·-]*$/i;
 const MIN_PREFIX = /\b(?:minimum|min\.?|at least|atleast)\s*(?:of\s*)?$/i;
@@ -20,11 +22,15 @@ function value(text: string | undefined): number | undefined {
   return WORDS[text.toLowerCase()] ?? Number(text);
 }
 
-/** The first experience requirement the text states, or null when it states none. */
+/** Prefer overall/total experience and standalone role ranges to skill-specific requirements. */
 export function statedExperience(description: string): Experience | null {
-  const text = decodeEntities(description);
-  const found: Array<{ index: number; experience: Experience }> = [];
-  for (const pattern of [YEARS_THEN_EXPERIENCE, EXPERIENCE_THEN_YEARS, MINIMUM_YEARS]) {
+  return readExperience(description)?.experience ?? null;
+}
+
+export function readExperience(description: string): { index: number; quote: string; priority: number; experience: Experience } | null {
+  const text = plainText(description);
+  const found: Array<{ index: number; quote: string; priority: number; experience: Experience }> = [];
+  for (const pattern of [YEARS_THEN_EXPERIENCE, EXPERIENCE_THEN_YEARS, MINIMUM_YEARS, STANDALONE_YEARS]) {
     for (const match of text.matchAll(pattern)) {
       const [low, high] = [value(match[1]), value(match[2])];
       if (low === undefined || !Number.isFinite(low)) continue;
@@ -32,11 +38,15 @@ export function statedExperience(description: string): Experience | null {
       if (low > 20 || (high !== undefined && (high < low || high > 40))) continue;
       const before = text.slice(Math.max(0, match.index - 60), match.index);
       if (pattern !== MINIMUM_YEARS && ABOUT_EMPLOYER.test(before) && !MIN_PREFIX.test(before)) continue;
-      found.push({ index: match.index, experience: high !== undefined && high !== low ? { min: low, max: high } : { min: low } });
+      const lineStart = Math.max(text.lastIndexOf("\n", match.index - 1), text.lastIndexOf(".", match.index - 1)) + 1;
+      const context = text.slice(lineStart, match.index) + match[0];
+      const priority = /\b(?:overall|total)\b/i.test(context) ? 3 : pattern === STANDALONE_YEARS ? 2 : 1;
+      const maxOpen = high !== undefined && /(?:\+\s*(?:years?|yrs?)|(?:years?|yrs?)\s*\+)/i.test(match[0]);
+      found.push({ index: match.index, quote: match[0], priority, experience: high !== undefined && high !== low ? { min: low, max: high, ...(maxOpen ? { maxOpen: true } : {}) } : { min: low } });
     }
   }
-  found.sort((left, right) => left.index - right.index);
-  return found[0]?.experience ?? null;
+  found.sort((left, right) => right.priority - left.priority || right.experience.min - left.experience.min || left.index - right.index);
+  return found[0] ?? null;
 }
 
 /** Entry-level titles (intern, trainee, fresher, graduate) as a rough 0–1 year estimate when the posting states nothing. */
@@ -46,5 +56,17 @@ export function titleExperience(title: string): Experience | undefined {
 
 /** "2–5 yrs", "5+ yrs". */
 export function experienceLabel(experience: Experience): string {
-  return experience.max === undefined ? `${experience.min}+ yrs` : `${experience.min}–${experience.max} yrs`;
+  return experience.max === undefined ? `${experience.min}+ yrs` : `${experience.min}–${experience.max}${experience.maxOpen ? "+" : ""} yrs`;
+}
+
+export function experienceMatches(experience: Experience, years: number): boolean {
+  return years >= experience.min && (experience.max === undefined || experience.maxOpen === true || years <= experience.max);
+}
+
+/** Old cached readings without their source text cannot be safely corrected: make them unknown. */
+export function normalizeJobExperience<T extends { description: string; experience?: Experience | null; experienceVersion?: number }>(job: T): Omit<T, "experience" | "experienceVersion"> & { experience?: Experience | null; experienceVersion?: number } {
+  if (job.description.trim()) return { ...job, experience: statedExperience(job.description), experienceVersion: EXPERIENCE_VERSION };
+  if (job.experienceVersion === EXPERIENCE_VERSION) return job;
+  const { experience: _experience, experienceVersion: _version, ...rest } = job;
+  return rest;
 }

package/src/index.ts

@@ -17,7 +17,7 @@ export const companies: Company[] = Object.entries(companyData).map(([slug, valu
 
 export const catalog = createCatalog({ companies });
 export { createCatalog } from "./catalog.ts";
-export { experienceLabel, statedExperience, titleExperience, type Experience } from "./experience.ts";
+export { EXPERIENCE_VERSION, experienceLabel, experienceMatches, normalizeJobExperience, statedExperience, titleExperience, type Experience } from "./experience.ts";
 export type { Catalog } from "./catalog.ts";
 export type { Ats, Company, CrawlReport, Job, JobPartition, JobSnapshot, JobSummary, SearchQuery } from "./types.ts";
 export { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";

package/src/job-matching.ts

@@ -1,4 +1,4 @@
-import { experienceLabel } from "./experience.ts";
+import { experienceLabel, normalizeJobExperience } from "./experience.ts";
 import { validateCandidateProfileEvidence, type CandidateProfile } from "./candidate-profile.ts";
 import { isEligibleForCountry, normalizeLocation } from "./locations.ts";
 import { detectRequirementTerms, findTransferability, matchesExactSkillEvidence, requiresExactSkillEvidence, type TransferabilityKind } from "./requirement-vocabulary.ts";
@@ -71,7 +71,8 @@ export function matchJobs(profile: CandidateProfile, intent: CandidateIntent, jo
   const roleFamilies = deriveRoleFamilies(profile, intent);
   const filteredOut: FilteredJob[] = [];
   const ranked: Array<JobMatch & { score: number; index: number }> = [];
-  for (const [index, job] of jobs.entries()) {
+  for (const [index, rawJob] of jobs.entries()) {
+    const job = normalizeJobExperience(rawJob);
     const rejectionReasons = hardFilterReasons(job, intent);
     if (rejectionReasons.length) {
       filteredOut.push({ jobId: job.id, reasons: rejectionReasons });
@@ -263,7 +264,7 @@ function seniorityAlignment(profile: CandidateProfile, intent: CandidateIntent,
   if (job.experience && typeof resumeYears === "number" && !intent.seniority?.length) {
     // The posting's own range is better evidence than a seniority word in the title. A year short or a few over still fits.
     const asked = experienceLabel(job.experience);
-    const fits = resumeYears >= job.experience.min - 1 && (job.experience.max === undefined || resumeYears <= job.experience.max + 3);
+    const fits = resumeYears >= job.experience.min - 1 && (job.experience.max === undefined || job.experience.maxOpen === true || resumeYears <= job.experience.max + 3);
     return { score: fits ? 3 : -3, reason: `posting asks for ${asked}; resume shows about ${resumeYears} years` };
   }
   const jobSeniority = seniorityTerms.find((term) => includesPhrase(job.title, term));

package/src/runtime.ts

@@ -5,6 +5,7 @@ import { fetchJobDescription, fetchSourceJobs } from "./catalog.ts";
 import { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
 import { createUsageReporter, type UsageReporter } from "./usage.ts";
 import { VERSION } from "./version.ts";
+import { normalizeJobExperience } from "./experience.ts";
 import { catalog as liveCatalog, companies } from "./index.ts";
 import { createLocalJobs } from "./local-jobs.ts";
 import { createJobRecommender } from "./job-recommendations.ts";
@@ -82,7 +83,7 @@ export function createHostedRuntime(options: { sources: Company[]; store: Snapsh
     if (!company) return job;
     try {
       const description = await fetchJobDescription(company, job, globalThis.fetch);
-      return description.trim() ? { ...job, description } : job;
+      return description.trim() ? normalizeJobExperience({ ...job, description }) : job;
     } catch { return job; } // the employer's board is unreachable; the summary is still useful
   }
   const snapshotJob = async (id: string) => (await local.get(id, { offline: true, staleDays: 3650 })).job;

package/src/screening-requirements.ts

@@ -1,5 +1,7 @@
 import type { CandidateProfile } from "./candidate-profile.ts";
 import type { Job } from "./types.ts";
+import { readExperience } from "./experience.ts";
+import { plainText } from "./providers.ts";
 
 export interface ScreeningRequirement {
   kind: "experience" | "education";
@@ -14,6 +16,12 @@ export function evaluateScreeningRequirements(profile: CandidateProfile, job: Jo
     ...experienceRequirements(profile, description),
     ...educationRequirements(profile, description),
   ];
+  const text = plainText(job.description);
+  const reading = readExperience(text);
+  if (reading && (isMandatory(text, reading.index, reading.quote) || (reading.priority === 2 && lastSectionKind(text.slice(0, reading.index)) !== "optional")) && !requirements.some((item) => item.kind === "experience" && Number(item.requirement.match(/\d+/)?.[0]) === reading.experience.min)) {
+    const inference = profile.inferences.find((value) => value.kind === "approximate_experience_years");
+    requirements.push({ kind: "experience", requirement: clean(reading.quote), status: !inference ? "unsupported" : inference.value >= reading.experience.min ? "supported" : "partial", factIds: inference?.derivedFromFactIds ?? [] });
+  }
   return [...new Map(requirements.map((item) => [`${item.kind}:${item.requirement.toLocaleLowerCase()}`, item])).values()];
 }
 

package/src/selected-job-lookup.ts

@@ -1,4 +1,5 @@
 import type { Job } from "./types.ts";
+import { normalizeJobExperience } from "./experience.ts";
 
 export interface SelectedJobLookupOptions {
   getSnapshotJob(id: string): Promise<Job | null>;
@@ -8,7 +9,8 @@ export interface SelectedJobLookupOptions {
 export function createSelectedJobLookup(options: SelectedJobLookupOptions) {
   return async (id: string): Promise<Job | null> => {
     const snapshot = await options.getSnapshotJob(id);
-    if (snapshot?.description.trim()) return snapshot;
-    return options.getDetailedJob(id);
+    if (snapshot?.description.trim()) return normalizeJobExperience(snapshot);
+    const detailed = await options.getDetailedJob(id);
+    return detailed ? normalizeJobExperience(detailed) : null;
   };
 }

package/src/snapshot-catalog.ts

@@ -1,5 +1,6 @@
 import { searchJobs, type Catalog } from "./catalog.ts";
 import type { SnapshotStore } from "./crawler.ts";
+import { normalizeJobExperience } from "./experience.ts";
 
 export function createSnapshotCatalog(store: SnapshotStore): Catalog {
   return {
@@ -13,7 +14,7 @@ export function createSnapshotCatalog(store: SnapshotStore): Catalog {
       if (!snapshot) return null;
       for (const partition of Object.values(snapshot.partitions)) {
         const job = partition.jobs.find((candidate) => candidate.id === id);
-        if (job) return job;
+        if (job) return normalizeJobExperience(job);
       }
       return null;
     },

package/src/types.ts

@@ -87,6 +87,7 @@ export interface JobSummary {
   updatedAt?: string;
   /** Years of experience the posting states, read from its description. null: the description states none. Absent: not read yet. */
   experience?: Experience | null;
+  experienceVersion?: number;
   /** Days since the posting date at the time of the search; absent when the board gave no date. */
   postedDaysAgo?: number;
   /** new = 7 days or less, older = 8 to 30, stale = beyond 30, undated = no posting date. Present it as such; a stale listing may still be open. */

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.36";
+export const VERSION = "0.1.37";