@whiteslove/parsing-lexicon 0.9.9 → 0.10.0

package/index.d.ts

@@ -372,6 +372,8 @@ export function parseExperience(value: unknown): ExperienceParseResult | null;
 
 export * from './src/housing-context.js';
 export * from './src/housing-address.js';
+// Keep the address grammar as the root owner; the V2 extractor remains on its subpath.
+export { extractHousingAddressCandidates } from './src/housing-address.js';
 export * from './src/parser-core.js';
 export * from './src/temporal.js';
 export * from './src/hiring-context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whiteslove/parsing-lexicon",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "description": "Shared deterministic multilingual parsing lexicon for WhitesLove housing and hiring services",
   "repository": {
     "type": "git",
@@ -17,6 +17,38 @@
     "./lexicon-core": "./src/lexicon-core.js",
     "./normalization": "./src/normalization.js",
     "./alias-prefilter": "./src/alias-prefilter.js",
+    "./provenance": {
+      "types": "./src/provenance.d.ts",
+      "import": "./src/provenance.js"
+    },
+    "./vacancy-requirements": {
+      "types": "./src/vacancy-requirements.d.ts",
+      "import": "./src/vacancy-requirements.js"
+    },
+    "./vacancy-blocks": {
+      "types": "./src/vacancy-blocks.d.ts",
+      "import": "./src/vacancy-blocks.js"
+    },
+    "./cv-skill-experience": {
+      "types": "./src/cv-skill-experience.d.ts",
+      "import": "./src/cv-skill-experience.js"
+    },
+    "./cv-employment": {
+      "types": "./src/cv-employment.d.ts",
+      "import": "./src/cv-employment.js"
+    },
+    "./cv-sections": {
+      "types": "./src/cv-sections.d.ts",
+      "import": "./src/cv-sections.js"
+    },
+    "./resolver-v2": {
+      "types": "./src/resolver-v2.d.ts",
+      "import": "./src/resolver-v2.js"
+    },
+    "./evidence-ledger": {
+      "types": "./src/evidence-ledger.d.ts",
+      "import": "./src/evidence-ledger.js"
+    },
     "./parser-core": {
       "types": "./src/parser-core.d.ts",
       "import": "./src/parser-core.js"
@@ -223,6 +255,19 @@
     "./hiring-safety": {
       "types": "./src/hiring-safety.d.ts",
       "import": "./src/hiring-safety.js"
+    },
+    "./parse-document": {
+      "types": "./src/parse-document.d.ts",
+      "import": "./src/parse-document.js"
+    },
+    "./city-hypotheses": {
+      "import": "./src/city-hypotheses.js"
+    },
+    "./micro-grammars": {
+      "import": "./src/micro-grammars.js"
+    },
+    "./resolver-weights": {
+      "import": "./src/resolver-weights.js"
     }
   },
   "files": [
@@ -237,7 +282,9 @@
   "scripts": {
     "test": "node --test",
     "sync:geo-map-data": "node ./scripts/sync-geo-map-data-lexicon.js",
-    "audit:geo-map-data": "node ./scripts/audit-geo-map-data-lexicon.js"
+    "audit:geo-map-data": "node ./scripts/audit-geo-map-data-lexicon.js",
+    "benchmark:parser": "node benchmarks/parser-baseline.js",
+    "calibrate:resolver": "node ./scripts/calibrate-resolver-weights.js"
   },
   "publishConfig": {
     "access": "public"

package/src/alias-prefilter.js

@@ -9,20 +9,31 @@
 // Almost all of that work is provably wasted. aliasPattern() only relaxes
 // *separators* between alias words; the letters and digits of an alias are
 // matched literally (modulo the Karakalpak Latin equivalence classes and
-// case). So the longest run of letters/digits inside an alias must appear as a
-// contiguous substring of the text for that alias to match at all. Indexing
-// entries by the first few characters of that run lets a text's own character
-// n-grams select the handful of entries worth testing.
+// case). So every maximal run of letters/digits inside an alias must appear as
+// a contiguous substring of the text for that alias to match at all. That is
+// the invariant the whole index rests on.
 //
 // The index is a filter, never a verdict: every surviving candidate is still
 // matched with its real `re`, in the list's original order, so results are
 // identical to a full scan. Folding is deliberately more aggressive than the
 // pattern's own equivalences (Cyrillic ё/ў/қ/ғ… are collapsed): over-merging
 // can only admit extra candidates, never discard a real match.
+//
+// Indexing is per alias, not per entry. An entry whose aliases include one
+// short string used to fall out of the index entirely and be tested against
+// every text; now each alias is indexed on its own terms, so a single short
+// alias costs only that alias, never the whole entry. Bucket keys are chosen
+// by rarity: of the grams an alias could be filed under, the one appearing in
+// the fewest aliases wins, which keeps buckets small where the vocabulary is
+// dense. Surviving candidates are then verified by exact substring containment
+// of every run, which is cheap and admits almost nothing spurious.
 
 import { normalizeUnicode } from './normalization.js';
 
 const GRAM = 4;
+/** Runs shorter than GRAM are looked up against every text substring of the
+ * same length, so this bounds how many such sets a query builds. */
+const MAX_SHORT = GRAM - 1;
 
 const PREFILTER_FOLD = Object.freeze({
   // Karakalpak Latin equivalences aliasPattern() encodes as character classes.
@@ -42,58 +53,59 @@ function fold(value) {
   return out;
 }
 
-/** The first GRAM characters of an alias's longest literal run, or null. */
-function aliasGram(alias) {
-  let longest = '';
-  for (const run of fold(alias).split(NON_ALNUM_RE)) {
-    if (run.length > longest.length) longest = run;
-  }
-  return longest.length >= GRAM ? longest.slice(0, GRAM) : null;
+/** Maximal literal runs of an alias, folded. Each must appear verbatim in the
+ * text for the alias to match, which is what makes them safe filter keys. */
+function aliasRuns(alias) {
+  return fold(alias).split(NON_ALNUM_RE).filter(Boolean);
+}
+
+function* windows(run) {
+  for (let i = 0; i + GRAM <= run.length; i += 1) yield run.slice(i, i + GRAM);
 }
 
-/** Every GRAM-length window of the folded text. */
-function textGrams(text) {
+/** Every GRAM-length window of the folded text, plus the shorter substrings a
+ * short alias needs. Both are needed because an alias run of two characters
+ * cannot be found in a set of four-character windows. */
+function textIndex(text) {
   const folded = fold(text);
   const grams = new Set();
-  for (let i = 0; i + GRAM <= folded.length; i += 1) {
-    grams.add(folded.slice(i, i + GRAM));
+  for (let i = 0; i + GRAM <= folded.length; i += 1) grams.add(folded.slice(i, i + GRAM));
+  const shorts = new Set();
+  for (let size = 1; size <= MAX_SHORT; size += 1) {
+    for (let i = 0; i + size <= folded.length; i += 1) shorts.add(folded.slice(i, i + size));
   }
-  return grams;
+  return { folded, grams, shorts };
 }
 
 function buildIndex(entries) {
-  const byGram = new Map();
-  // Entries whose every alias is shorter than GRAM cannot be indexed, so they
-  // are always tested. In practice this is a tiny tail.
-  const always = [];
-
+  // Pass one counts how many aliases could be filed under each gram, so pass
+  // two can file every alias under its rarest option.
+  const frequency = new Map();
+  const prepared = [];
   for (let i = 0; i < entries.length; i += 1) {
     const entry = entries[i];
     const aliases = entry?.aliases?.length ? entry.aliases : [entry?.name].filter(Boolean);
-    const grams = [];
-    let indexable = aliases.length > 0;
-
     for (const alias of aliases) {
-      const gram = aliasGram(alias);
-      if (!gram) {
-        indexable = false;
-        break;
-      }
-      grams.push(gram);
-    }
-
-    if (!indexable) {
-      always.push(i);
-      continue;
-    }
-    for (const gram of new Set(grams)) {
-      const bucket = byGram.get(gram);
-      if (bucket) bucket.push(i);
-      else byGram.set(gram, [i]);
+      const runs = aliasRuns(alias);
+      if (!runs.length) { prepared.push({ index: i, runs: null }); continue; }
+      const longest = runs.reduce((best, run) => (run.length > best.length ? run : best), '');
+      const options = longest.length >= GRAM ? [...windows(longest)] : [longest];
+      for (const option of options) frequency.set(option, (frequency.get(option) ?? 0) + 1);
+      prepared.push({ index: i, runs, options, short: longest.length < GRAM });
     }
   }
 
-  return { byGram, always };
+  const byGram = new Map(); const byShort = new Map(); const always = new Set();
+  for (const alias of prepared) {
+    if (!alias.runs) { always.add(alias.index); continue; }
+    let key = alias.options[0];
+    for (const option of alias.options) if (frequency.get(option) < frequency.get(key)) key = option;
+    const target = alias.short ? byShort : byGram;
+    const bucket = target.get(key);
+    const ref = { index: alias.index, runs: alias.runs };
+    if (bucket) bucket.push(ref); else target.set(key, [ref]);
+  }
+  return { byGram, byShort, always: [...always].sort((a, b) => a - b) };
 }
 
 const INDEX_CACHE = new WeakMap();
@@ -107,6 +119,59 @@ function indexFor(entries) {
   return index;
 }
 
+/**
+ * Text-side index for `text`, precomputed once for reuse across lists. The
+ * returned value is opaque: pass it straight back to `candidateEntries`.
+ */
+export function computeTextGrams(text) {
+  return textIndex(String(text || ''));
+}
+
+/** Accepts an opaque index or, for older callers, a bare Set of grams. */
+function resolveTextIndex(value, text) {
+  if (value && value.grams instanceof Set) return value;
+  if (value instanceof Set) return { ...textIndex(text), grams: value };
+  return textIndex(text);
+}
+
+function candidateIndices(entries, value, provided) {
+  const { byGram, byShort, always } = indexFor(entries);
+  const { folded, grams, shorts } = resolveTextIndex(provided, value);
+  const candidates = new Set(always);
+  const consider = (refs) => {
+    if (!refs) return;
+    for (const ref of refs) {
+      if (candidates.has(ref.index)) continue;
+      // Exact containment of every run. The bucket only proposed this alias;
+      // this is what makes the proposal almost always correct.
+      let ok = true;
+      for (const run of ref.runs) if (!folded.includes(run)) { ok = false; break; }
+      if (ok) candidates.add(ref.index);
+    }
+  };
+  for (const gram of grams) consider(byGram.get(gram));
+  if (byShort.size) for (const short of shorts) consider(byShort.get(short));
+  return [...candidates].sort((a, b) => a - b);
+}
+
+/**
+ * Every entry in `entries` (original list order) the text could plausibly
+ * contain, per the index — a filter, not a verdict. Callers still run their
+ * own verification (regex, exact-token match, ...) on what comes back; see the
+ * module doc for why this is safe even for non-regex verifiers.
+ *
+ * `grams`, from `computeTextGrams()`, lets a caller scanning the same text
+ * against many lists compute the O(text length) text pass once instead of
+ * once per list.
+ */
+export function candidateEntries(entries, text, grams) {
+  if (!Array.isArray(entries) || !entries.length) return [];
+  const value = String(text || '');
+  if (!value) return [];
+
+  return candidateIndices(entries, value, grams).map((i) => entries[i]);
+}
+
 /**
  * First entry in `entries` whose alias regex matches `text`.
  *
@@ -124,16 +189,7 @@ export function matchFirstEntry(entries, text, accept) {
   const value = String(text || '');
   if (!value) return undefined;
 
-  const { byGram, always } = indexFor(entries);
-  const candidates = new Set(always);
-  for (const gram of textGrams(value)) {
-    const bucket = byGram.get(gram);
-    if (!bucket) continue;
-    for (const i of bucket) candidates.add(i);
-  }
-  if (!candidates.size) return undefined;
-
-  for (const i of [...candidates].sort((a, b) => a - b)) {
+  for (const i of candidateIndices(entries, value)) {
     const entry = entries[i];
     // `re` carries no /g flag, so exec() is stateless and safe to reuse here.
     const match = entry?.re?.exec(value);

package/src/central-asia-locations.js

@@ -2,6 +2,8 @@ import { LOCATION_DICTIONARIES } from './locations-runtime.js';
 import { isMapDataEntry, LOCATION_LIST_KEYS } from './location-merge.js';
 import { CITIES_BY_COUNTRY, canonicalCity } from './geography.js';
 import { aliasesOf, aliasesToRegex, normalizeForMatch } from './normalization.js';
+import { candidateEntries, computeTextGrams } from './alias-prefilter.js';
+import { scoreCityHypotheses } from './city-hypotheses.js';
 import { KZ_AMBIGUOUS_LOCAL_NAMES, KZ_SEARCH_CLUSTERS } from './kz-location-extensions.js';
 import { UZ_AMBIGUOUS_LOCAL_NAMES } from './uz-location-extensions.js';
 
@@ -237,12 +239,13 @@ function mapDataMatch(value, normalizedValue, item) {
   return null;
 }
 
-function findEntryMatches(text, cityName, data, { includeMapData = false } = {}) {
+function findEntryMatches(text, cityName, data, { includeMapData = false, grams = null } = {}) {
   const value = String(text || '');
   const normalizedValue = normalizeForMatch(value);
+  const textGrams = grams || computeTextGrams(value);
   const raw = [];
   for (const key of LOCATION_LIST_KEYS) {
-    for (const item of data?.[key] || []) {
+    for (const item of candidateEntries(data?.[key] || [], value, textGrams)) {
       if (isMapDataEntry(item) && !includeMapData) continue;
       const match = (isMapDataEntry(item) ? mapDataMatch(value, normalizedValue, item) : value.match(item?.re))
         || (key === 'residentialComplexes' ? markedResidentialMatch(value, item) : null);
@@ -329,23 +332,37 @@ export function matchCentralAsiaLocationEntities(text, countryCode, preferredCit
   const preferred = canonicalCity(preferredCity, countryCode) || preferredCity;
   const explicit = explicitCityFromText(text, countryCode);
   const scopedCity = preferred && country[preferred] ? preferred : explicit && country[explicit] ? explicit : null;
+  const grams = computeTextGrams(text);
 
   if (scopedCity) {
-    const matches = findEntryMatches(text, scopedCity, country[scopedCity], { includeMapData: true });
+    const matches = findEntryMatches(text, scopedCity, country[scopedCity], { includeMapData: true, grams });
     const clusters = clusterMatches(matches, countryCode);
-    return Object.freeze({ city: scopedCity, matches: Object.freeze(matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
+    // The city is already decided here; the hypothesis is reported so callers
+    // get one shape either way, and can see the evidence behind the scope.
+    const scoped = scoreCityHypotheses([{ city: scopedCity, matches }], {
+      explicitCity: explicit, preferredCity: preferred, cityNames: Object.keys(country),
+      isAmbiguous: (match) => isAmbiguousMatch(match, countryCode),
+    });
+    return Object.freeze({ city: scopedCity, matches: Object.freeze(matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]), hypotheses: scoped.hypotheses });
   }
 
   const byCity = [];
   for (const [cityName, data] of Object.entries(country)) {
-    const matches = findEntryMatches(text, cityName, data);
+    const matches = findEntryMatches(text, cityName, data, { grams });
     if (matches.length) byCity.push({ city: cityName, matches });
   }
 
   if (!byCity.length) {
-    return Object.freeze({ city: null, matches: Object.freeze([]), searchClusters: Object.freeze([]), candidates: Object.freeze([]) });
+    return Object.freeze({ city: null, matches: Object.freeze([]), searchClusters: Object.freeze([]), candidates: Object.freeze([]), hypotheses: Object.freeze([]) });
   }
 
+  // Scored view of the same per-city matches. Additive: the selection rules
+  // below are unchanged, so every existing caller sees what it always saw.
+  const scored = scoreCityHypotheses(byCity, {
+    explicitCity: explicit, preferredCity: preferred, cityNames: Object.keys(country),
+    isAmbiguous: (match) => isAmbiguousMatch(match, countryCode),
+  });
+
   // Numeric microdistricts and common names such as Samal/Center occur in many
   // cities. Without an explicit/structured city we must not silently assign a
   // parent. Prefer a city only when it owns at least one non-ambiguous match
@@ -363,11 +380,13 @@ export function matchCentralAsiaLocationEntities(text, countryCode, preferredCit
       matches: Object.freeze([]),
       searchClusters: Object.freeze([]),
       candidates: Object.freeze(byCity.map((candidate) => Object.freeze({ city: candidate.city, matches: Object.freeze(candidate.matches) }))),
+      hypotheses: scored.hypotheses,
+      unresolvedReasons: scored.unresolvedReasons,
     });
   }
 
   const clusters = clusterMatches(selected.matches, countryCode);
-  return Object.freeze({ city: selected.city, matches: Object.freeze(selected.matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
+  return Object.freeze({ city: selected.city, matches: Object.freeze(selected.matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]), hypotheses: scored.hypotheses });
 }
 
 export function matchCentralAsiaLocationEntity(text, countryCode, preferredCity = null, type = null) {

package/src/cv-employment.d.ts

@@ -0,0 +1,48 @@
+import type { CvSection } from './cv-sections.js';
+
+/** Precision records what the text said. A bare "2019" is year precision; the
+ * month is absent rather than guessed. */
+export type ParsedDate = Readonly<{ year: number; month?: number; precision: 'year' | 'month' }>;
+
+export type EmploymentRange = Readonly<{
+  start: ParsedDate;
+  end: ParsedDate;
+  ongoing: boolean;
+  startIndex: number;
+  endIndex: number;
+  durationMonths: number;
+  raw: string;
+  range: Readonly<{ start: number; end: number }>;
+}>;
+
+export type EmploymentPeriod = Readonly<{
+  company?: string;
+  role?: string;
+  /** The CV section this entry was read from; undefined when the document had
+   * no headings and the whole text was scanned. */
+  section?: CvSection;
+  start: ParsedDate;
+  end: ParsedDate;
+  ongoing: boolean;
+  durationMonths: number;
+  sectionRange: Readonly<{ start: number; end: number }>;
+  skills: readonly string[];
+  startIndex: number;
+  endIndex: number;
+}>;
+
+export type MergedEmploymentPeriod = Readonly<{
+  startIndex: number;
+  endIndex: number;
+  ongoing: boolean;
+  durationMonths: number;
+  companies: readonly string[];
+}>;
+
+export type EmploymentOptions = { referenceDate?: Date; sections?: readonly CvSection[] };
+
+export function parseEmploymentDate(value: unknown): ParsedDate | null;
+export function findEmploymentRanges(value: unknown, options?: EmploymentOptions): readonly EmploymentRange[];
+export function parseCvEmploymentPeriods(value: unknown, options?: EmploymentOptions): readonly EmploymentPeriod[];
+export function mergeEmploymentPeriods(periods: readonly EmploymentPeriod[]): readonly MergedEmploymentPeriod[];
+export function totalEmploymentMonths(periods: readonly EmploymentPeriod[]): number;

package/src/cv-employment.js

@@ -0,0 +1,153 @@
+import { HIRING_MONTHS } from './hiring-temporal.js';
+import { detectCvSections } from './cv-sections.js';
+import { extractSkillNames } from './hiring-skills.js';
+import { matchProfession } from './hiring-professions.js';
+import { escapeRegex } from './normalization.js';
+
+/** Structured employment chronology for CVs. This is not another date parser:
+ * month vocabulary comes from `hiring-temporal`, section spans from
+ * `cv-sections`, skills from `hiring-skills` and roles from
+ * `hiring-professions`. What is new here is pairing two dates into a period,
+ * attaching the employer and role that introduced it, and keeping the source
+ * range so a caller can point back at the text. */
+
+const MONTH_SRC = Object.keys(HIRING_MONTHS).sort((a, b) => b.length - a.length).map(escapeRegex).join('|');
+const YEAR_SRC = '(?:19|20)\\d{2}';
+// Longest alternative first, and the trailing digit guard on DATE_SRC below:
+// without both, "2021-12" matches as "2021-1" and silently loses 11 months.
+const MONTH_NUMBER_SRC = '(?:1[0-2]|0?[1-9])';
+const PRESENT_SRC = '(?:present|current|now|to date|ongoing|по\\s+настоящее\\s+время|настоящее\\s+время|наст\\.?\\s*время|н\\.\\s*в\\.|по\\s+сей\\s+день|сейчас|теперь|донині|до\\s+тепер|дотепер|теперішній\\s+час|зараз|hozirgi\\s+kunga\\s+qadar|hozirgacha|hozir|ҳозирги\\s+кунгача|ҳозиргача|ҳозир|қазірге\\s+дейін|қазір|осы\\s+күнге\\s+дейін|în\\s+prezent|in\\s+prezent|prezent|pân[ăa]\\s+în\\s+prezent)';
+/** Written longest-first so "March 2019" is never truncated to "2019". */
+const DATE_SRC = `(?:(?:${MONTH_SRC})\\.?\\s+${YEAR_SRC}|${YEAR_SRC}\\s*[-/.]\\s*${MONTH_NUMBER_SRC}|${MONTH_NUMBER_SRC}\\s*[/.]\\s*${YEAR_SRC}|${YEAR_SRC})(?!\\d)`;
+const SEPARATOR_SRC = '(?:\\s*(?:[-–—]|\\.{2,})\\s*|\\s+(?:to|till|until|по|до|gacha|pân[ăa]|pana)\\s+)';
+
+const RANGE_RE = new RegExp(`(${DATE_SRC})${SEPARATOR_SRC}(${DATE_SRC}|${PRESENT_SRC})`, 'giu');
+const MONTH_YEAR_RE = new RegExp(`^(${MONTH_SRC})\\.?\\s+(${YEAR_SRC})$`, 'iu');
+const YEAR_MONTH_RE = new RegExp(`^(${YEAR_SRC})\\s*[-/.]\\s*(${MONTH_NUMBER_SRC})$`, 'iu');
+const MONTH_SLASH_YEAR_RE = new RegExp(`^(${MONTH_NUMBER_SRC})\\s*[/.]\\s*(${YEAR_SRC})$`, 'iu');
+const YEAR_ONLY_RE = new RegExp(`^(${YEAR_SRC})$`, 'iu');
+const PRESENT_RE = new RegExp(`^${PRESENT_SRC}$`, 'iu');
+/** Employer and role sit on the same line as the dates, separated by commas,
+ * pipes, bullets or a spaced dash. "at"/"в" join a role to its employer. */
+const ENTRY_SPLIT_RE = /\s*(?:[,|•·;]|\s[—–-]\s|\s+(?:at|@|in|в|у|da)\s+)\s*/iu;
+const COMPANY_MARKER_RE = /\b(?:llc|ltd|inc|gmbh|corp|corporation|company|co|plc|ag|sa|srl|bv|oy|ab|as|llp|studio|labs?|group|holding|bank|university|ооо|зао|оао|пао|ип|тоо|ао|мчж|mchj|xk|аж|жшс)\b\.?|["«»“”]/iu;
+
+const monthIndex = (year, month) => year * 12 + Math.max(1, Math.min(12, month)) - 1;
+const parsedDate = (year, month, precision) => Object.freeze(month === undefined ? { year, precision } : { year, month, precision });
+
+/** A ParsedDate records what the text actually said. "2019" is year precision;
+ * inventing a month for it would fabricate detail the CV never gave. */
+export function parseEmploymentDate(value) {
+  const text = String(value ?? '').trim();
+  if (!text) return null;
+  let match = MONTH_YEAR_RE.exec(text);
+  if (match) return parsedDate(Number(match[2]), HIRING_MONTHS[match[1].toLowerCase()] + 1, 'month');
+  match = YEAR_MONTH_RE.exec(text);
+  if (match) return parsedDate(Number(match[1]), Number(match[2]), 'month');
+  match = MONTH_SLASH_YEAR_RE.exec(text);
+  if (match) return parsedDate(Number(match[2]), Number(match[1]), 'month');
+  match = YEAR_ONLY_RE.exec(text);
+  if (match) return parsedDate(Number(match[1]), undefined, 'year');
+  return null;
+}
+
+const startIndexOf = date => monthIndex(date.year, date.month ?? 1);
+const endIndexOf = date => monthIndex(date.year, date.month ?? 12);
+
+/** Date ranges with their offsets in `text`. Shared by the period builder and
+ * by the legacy total-years helper, so both read the same chronology. */
+export function findEmploymentRanges(value, options = {}) {
+  const text = String(value ?? '');
+  const reference = options.referenceDate ?? new Date();
+  const ranges = [];
+  RANGE_RE.lastIndex = 0;
+  for (const match of text.matchAll(RANGE_RE)) {
+    const start = parseEmploymentDate(match[1]);
+    if (!start) continue;
+    const ongoing = PRESENT_RE.test(match[2].trim());
+    const end = ongoing ? parsedDate(reference.getUTCFullYear(), reference.getUTCMonth() + 1, 'month') : parseEmploymentDate(match[2]);
+    if (!end) continue;
+    const startIndex = startIndexOf(start);
+    const endIndex = ongoing ? monthIndex(end.year, end.month) : endIndexOf(end);
+    if (endIndex < startIndex || endIndex - startIndex > 12 * 50) continue;
+    ranges.push(Object.freeze({ start, end, ongoing, startIndex, endIndex, durationMonths: endIndex - startIndex + 1, raw: match[0], range: Object.freeze({ start: match.index, end: match.index + match[0].length }) }));
+  }
+  return Object.freeze(ranges);
+}
+
+function labelsFrom(line, rangeText) {
+  const remainder = line.replace(rangeText, ' ');
+  const segments = remainder.split(ENTRY_SPLIT_RE).map(part => part.replace(/^[\s\-–—:|()]+|[\s\-–—:|()]+$/gu, '')).filter(part => part.length > 1);
+  let role, company;
+  for (const segment of segments) {
+    const isRole = Boolean(matchProfession(segment));
+    if (isRole && role === undefined) { role = segment; continue; }
+    if (!isRole && company === undefined && COMPANY_MARKER_RE.test(segment)) { company = segment; continue; }
+  }
+  for (const segment of segments) {
+    if (segment === role || segment === company) continue;
+    if (company === undefined) company = segment;
+    else if (role === undefined) role = segment;
+  }
+  return { role, company };
+}
+
+/** One period per employment entry: the line carrying the dates plus the lines
+ * under it, which is where that entry's skills live. */
+export function parseCvEmploymentPeriods(value, options = {}) {
+  const text = String(value ?? '');
+  const wanted = options.sections ?? ['experience', 'projects'];
+  const spans = detectCvSections(text).filter(span => wanted.includes(span.section));
+  const scopes = spans.length ? spans.map(span => ({ start: span.contentStart, end: span.end, section: span.section })) : [{ start: 0, end: text.length, section: undefined }];
+  const periods = [];
+  for (const scope of scopes) {
+    const body = text.slice(scope.start, scope.end);
+    const found = findEmploymentRanges(body, options);
+    if (!found.length) continue;
+    const lines = [];
+    let offset = 0;
+    for (const raw of body.split('\n')) { lines.push({ start: offset, end: offset + raw.replace(/\r$/, '').length, text: raw.trim() }); offset += raw.length + 1; }
+    const headers = found.map(range => ({ range, line: lines.find(line => range.range.start >= line.start && range.range.start <= line.end) ?? lines[0] }));
+    headers.forEach((header, index) => {
+      const next = headers.slice(index + 1).find(other => other.line.start > header.line.start);
+      const entryEnd = next ? next.line.start : scope.end - scope.start;
+      const { role, company } = labelsFrom(header.line.text, header.range.raw);
+      periods.push(Object.freeze({
+        company, role, section: scope.section,
+        start: header.range.start, end: header.range.end, ongoing: header.range.ongoing,
+        durationMonths: header.range.durationMonths,
+        sectionRange: Object.freeze({ start: scope.start + header.line.start, end: scope.start + entryEnd }),
+        skills: Object.freeze([...new Set(extractSkillNames(body.slice(header.line.start, entryEnd)))]),
+        startIndex: header.range.startIndex, endIndex: header.range.endIndex,
+      }));
+    });
+  }
+  return Object.freeze(periods);
+}
+
+/** Overlapping or adjacent periods collapse into one interval. Concurrent jobs
+ * must not be counted twice, so this merges across employers and keeps every
+ * contributing company name. */
+export function mergeEmploymentPeriods(periods) {
+  const ordered = [...periods].sort((a, b) => a.startIndex - b.startIndex || a.endIndex - b.endIndex);
+  const merged = [];
+  for (const period of ordered) {
+    const last = merged[merged.length - 1];
+    if (last && period.startIndex <= last.endIndex + 1) {
+      last.endIndex = Math.max(last.endIndex, period.endIndex);
+      last.ongoing ||= period.ongoing;
+      if (period.company) last.companies.add(period.company);
+      continue;
+    }
+    merged.push({ startIndex: period.startIndex, endIndex: period.endIndex, ongoing: period.ongoing, companies: new Set(period.company ? [period.company] : []) });
+  }
+  return Object.freeze(merged.map(entry => Object.freeze({
+    startIndex: entry.startIndex, endIndex: entry.endIndex, ongoing: entry.ongoing,
+    durationMonths: entry.endIndex - entry.startIndex + 1,
+    companies: Object.freeze([...entry.companies]),
+  })));
+}
+
+export function totalEmploymentMonths(periods) {
+  return mergeEmploymentPeriods(periods).reduce((sum, entry) => sum + entry.durationMonths, 0);
+}

package/src/cv-sections.d.ts

@@ -0,0 +1,15 @@
+export type CvSection = 'profile' | 'experience' | 'projects' | 'skills' | 'education' | 'languages' | 'certifications' | 'contact' | 'additional';
+export const CV_SECTIONS: readonly CvSection[];
+
+export type CvSectionSpan = Readonly<{
+  section: CvSection | 'preamble';
+  heading: string | null;
+  headingRange: Readonly<{ start: number; end: number }> | null;
+  start: number;
+  contentStart: number;
+  end: number;
+}>;
+
+export function classifyCvSectionHeading(value: unknown): CvSection | null;
+export function detectCvSections(value: unknown): readonly CvSectionSpan[];
+export function extractCvSectionText(value: unknown, wanted: CvSection): string;