@whiteslove/parsing-lexicon 0.2.0 → 0.2.2

package/package.json

@@ -1,75 +1,77 @@
-{
-  "name": "@whiteslove/parsing-lexicon",
-  "version": "0.2.0",
-  "description": "Shared deterministic multilingual parsing lexicon for Whiteslove housing and hiring services",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AmoneMisa/parsing-lexicon.git"
-  },
-  "type": "module",
-  "main": "./src/index.js",
-  "types": "./index.d.ts",
-  "exports": {
-    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
-    "./lexicon-core": "./src/lexicon-core.js",
-    "./normalization": "./src/normalization.js",
-    "./countries": "./src/countries.js",
-    "./country-context": { "types": "./src/country-context.d.ts", "import": "./src/country-context.js" },
-    "./geo": "./src/geo.js",
-    "./geography": "./src/geography.js",
-    "./geography-display": { "types": "./src/geography-display.d.ts", "import": "./src/geography-display.js" },
-    "./geography-detection": { "types": "./src/geography-detection.d.ts", "import": "./src/geography-detection.js" },
-    "./central-asia": "./src/central-asia.js",
-    "./ukraine": "./src/ukraine.js",
-    "./location-merge": "./src/location-merge.js",
-    "./locations": "./src/locations.js",
-    "./kz-location-extensions": "./src/kz-location-extensions.js",
-    "./uz-location-extensions": "./src/uz-location-extensions.js",
-    "./central-asia-locations": "./src/central-asia-locations.js",
-    "./ua-location-extensions-major": "./src/ua-location-extensions-major.js",
-    "./ua-location-extensions-regional": "./src/ua-location-extensions-regional.js",
-    "./ua-location-extensions-metro": "./src/ua-location-extensions-metro.js",
-    "./landmarks": "./src/landmarks.js",
-    "./tashkent-colloquial": "./src/tashkent-colloquial.js",
-    "./tashkent-residential-complexes": "./src/tashkent-residential-complexes.js",
-    "./tashkent-pois": "./src/tashkent-pois.js",
-    "./tashkent-housing-geography": { "types": "./src/tashkent-housing-geography.d.ts", "import": "./src/tashkent-housing-geography.js" },
-    "./odesa-metropolitan": "./src/odesa-metropolitan.js",
-    "./housing": "./src/housing.js",
-    "./housing-intent": { "types": "./src/housing-intent.d.ts", "import": "./src/housing-intent.js" },
-    "./housing-context": { "types": "./src/housing-context.d.ts", "import": "./src/housing-context.js" },
-    "./housing-address": { "types": "./src/housing-address.d.ts", "import": "./src/housing-address.js" },
-    "./housing-structured": { "types": "./src/housing-structured.d.ts", "import": "./src/housing-structured.js" },
-    "./housing-source-aliases": { "types": "./src/housing-source-aliases.d.ts", "import": "./src/housing-source-aliases.js" },
-    "./hiring": "./src/hiring.js",
-    "./hiring-languages": "./src/hiring-languages.js",
-    "./hiring-language-extensions": { "types": "./src/hiring-language-extensions.d.ts", "import": "./src/hiring-language-extensions.js" },
-    "./hiring-context": { "types": "./src/hiring-context.d.ts", "import": "./src/hiring-context.js" },
-    "./hiring-source-aliases": { "types": "./src/hiring-source-aliases.d.ts", "import": "./src/hiring-source-aliases.js" },
-    "./hiring-source-semantics": { "types": "./src/hiring-source-semantics.d.ts", "import": "./src/hiring-source-semantics.js" },
-    "./hiring-requirements": { "types": "./src/hiring-requirements.d.ts", "import": "./src/hiring-requirements.js" },
-    "./hiring-semantics": { "types": "./src/hiring-semantics.d.ts", "import": "./src/hiring-semantics.js" },
-    "./hiring-work-semantics": { "types": "./src/hiring-work-semantics.d.ts", "import": "./src/hiring-work-semantics.js" },
-    "./hiring-candidate-fields": { "types": "./src/hiring-candidate-fields.d.ts", "import": "./src/hiring-candidate-fields.js" },
-    "./hiring-temporal": { "types": "./src/hiring-temporal.d.ts", "import": "./src/hiring-temporal.js" },
-    "./hiring-vacancy-fields": { "types": "./src/hiring-vacancy-fields.d.ts", "import": "./src/hiring-vacancy-fields.js" },
-    "./hiring-location-fields": { "types": "./src/hiring-location-fields.d.ts", "import": "./src/hiring-location-fields.js" },
-    "./hiring-salary-context": { "types": "./src/hiring-salary-context.d.ts", "import": "./src/hiring-salary-context.js" },
-    "./money": "./src/money.js",
-    "./currency": { "types": "./src/currency.d.ts", "import": "./src/currency.js" },
-    "./contact": { "types": "./src/contact.d.ts", "import": "./src/contact.js" },
-    "./housing-money": { "types": "./src/housing-money.d.ts", "import": "./src/housing-money.js" },
-    "./hiring-professions": "./src/hiring-professions.js",
-    "./hiring-skills": { "types": "./src/hiring-skills.d.ts", "import": "./src/hiring-skills.js" },
-    "./hiring-advanced": "./src/hiring-advanced.js"
-  },
-  "files": ["src", "index.d.ts", "README.md"],
-  "sideEffects": false,
-  "engines": { "node": ">=20" },
-  "scripts": { "test": "node --test" },
-  "dependencies": {
-    "libphonenumber-js": "^1.11.20"
-  },
-  "keywords": ["parsing", "lexicon", "uzbek", "kazakh", "ukrainian", "romanian", "russian", "housing", "hiring", "salary", "professions", "geography"],
-  "license": "MIT"
-}
+{
+  "name": "@whiteslove/parsing-lexicon",
+  "version": "0.2.2",
+  "description": "Shared deterministic multilingual parsing lexicon for Whiteslove housing and hiring services",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmoneMisa/parsing-lexicon.git"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
+    "./lexicon-core": "./src/lexicon-core.js",
+    "./normalization": "./src/normalization.js",
+    "./countries": "./src/countries.js",
+    "./country-context": { "types": "./src/country-context.d.ts", "import": "./src/country-context.js" },
+    "./geo": "./src/geo.js",
+    "./geography": "./src/geography.js",
+    "./geography-display": { "types": "./src/geography-display.d.ts", "import": "./src/geography-display.js" },
+    "./geography-detection": { "types": "./src/geography-detection.d.ts", "import": "./src/geography-detection.js" },
+    "./central-asia": "./src/central-asia.js",
+    "./ukraine": "./src/ukraine.js",
+    "./location-merge": "./src/location-merge.js",
+    "./locations": "./src/locations.js",
+    "./kz-location-extensions": "./src/kz-location-extensions.js",
+    "./uz-location-extensions": "./src/uz-location-extensions.js",
+    "./central-asia-locations": "./src/central-asia-locations.js",
+    "./ua-location-extensions-major": "./src/ua-location-extensions-major.js",
+    "./ua-location-extensions-regional": "./src/ua-location-extensions-regional.js",
+    "./ua-location-extensions-metro": "./src/ua-location-extensions-metro.js",
+    "./landmarks": "./src/landmarks.js",
+    "./tashkent-colloquial": "./src/tashkent-colloquial.js",
+    "./tashkent-residential-complexes": "./src/tashkent-residential-complexes.js",
+    "./tashkent-pois": "./src/tashkent-pois.js",
+    "./tashkent-housing-geography": { "types": "./src/tashkent-housing-geography.d.ts", "import": "./src/tashkent-housing-geography.js" },
+    "./odesa-metropolitan": "./src/odesa-metropolitan.js",
+    "./housing": "./src/housing.js",
+    "./housing-intent": { "types": "./src/housing-intent.d.ts", "import": "./src/housing-intent.js" },
+    "./housing-commercial": { "types": "./src/housing-commercial.d.ts", "import": "./src/housing-commercial.js" },
+    "./housing-context": { "types": "./src/housing-context.d.ts", "import": "./src/housing-context.js" },
+    "./housing-address": { "types": "./src/housing-address.d.ts", "import": "./src/housing-address.js" },
+    "./housing-structured": { "types": "./src/housing-structured.d.ts", "import": "./src/housing-structured.js" },
+    "./housing-source-aliases": { "types": "./src/housing-source-aliases.d.ts", "import": "./src/housing-source-aliases.js" },
+    "./hiring": "./src/hiring.js",
+    "./hiring-languages": "./src/hiring-languages.js",
+    "./hiring-language-extensions": { "types": "./src/hiring-language-extensions.d.ts", "import": "./src/hiring-language-extensions.js" },
+    "./hiring-context": { "types": "./src/hiring-context.d.ts", "import": "./src/hiring-context.js" },
+    "./hiring-source-aliases": { "types": "./src/hiring-source-aliases.d.ts", "import": "./src/hiring-source-aliases.js" },
+    "./hiring-source-semantics": { "types": "./src/hiring-source-semantics.d.ts", "import": "./src/hiring-source-semantics.js" },
+    "./hiring-requirements": { "types": "./src/hiring-requirements.d.ts", "import": "./src/hiring-requirements.js" },
+    "./hiring-semantics": { "types": "./src/hiring-semantics.d.ts", "import": "./src/hiring-semantics.js" },
+    "./hiring-work-semantics": { "types": "./src/hiring-work-semantics.d.ts", "import": "./src/hiring-work-semantics.js" },
+    "./hiring-candidate-fields": { "types": "./src/hiring-candidate-fields.d.ts", "import": "./src/hiring-candidate-fields.js" },
+    "./hiring-temporal": { "types": "./src/hiring-temporal.d.ts", "import": "./src/hiring-temporal.js" },
+    "./hiring-vacancy-fields": { "types": "./src/hiring-vacancy-fields.d.ts", "import": "./src/hiring-vacancy-fields.js" },
+    "./hiring-location-fields": { "types": "./src/hiring-location-fields.d.ts", "import": "./src/hiring-location-fields.js" },
+    "./hiring-salary-context": { "types": "./src/hiring-salary-context.d.ts", "import": "./src/hiring-salary-context.js" },
+    "./money": "./src/money.js",
+    "./currency": { "types": "./src/currency.d.ts", "import": "./src/currency.js" },
+    "./contact": { "types": "./src/contact.d.ts", "import": "./src/contact.js" },
+    "./housing-money": { "types": "./src/housing-money.d.ts", "import": "./src/housing-money.js" },
+    "./hiring-professions": "./src/hiring-professions.js",
+    "./hiring-skills": { "types": "./src/hiring-skills.d.ts", "import": "./src/hiring-skills.js" },
+    "./hiring-advanced": "./src/hiring-advanced.js"
+  },
+  "files": ["src", "index.d.ts", "README.md"],
+  "sideEffects": false,
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "libphonenumber-js": "^1.11.20"
+  },
+  "keywords": ["parsing", "lexicon", "uzbek", "kazakh", "ukrainian", "romanian", "russian", "housing", "hiring", "salary", "professions", "geography"],
+  "license": "MIT"
+}

package/src/central-asia-locations.js

@@ -1,211 +1,211 @@
-import { LOCATION_DICTIONARIES } from './locations.js';
-import { LOCATION_LIST_KEYS, mergeLocationCountries } from './location-merge.js';
-import { aliasesOf, aliasesToRegex, normalizeForMatch } from './normalization.js';
-import {
-  KZ_CITY_CATALOG,
-  UZ_CITY_CATALOG,
-  canonicalKazakhstanCity,
-  canonicalUzbekistanCity,
-} from './central-asia.js';
-import { KZ_AMBIGUOUS_LOCAL_NAMES, KZ_LOCATION_EXTENSIONS, KZ_SEARCH_CLUSTERS } from './kz-location-extensions.js';
-import { UZ_AMBIGUOUS_LOCAL_NAMES, UZ_LOCATION_EXTENSIONS } from './uz-location-extensions.js';
-
-export const KZ_EXPANDED_LOCATION_DICTIONARIES = mergeLocationCountries(
-  LOCATION_DICTIONARIES.KZ || {},
-  KZ_LOCATION_EXTENSIONS,
-);
-
-export const UZ_EXPANDED_LOCATION_DICTIONARIES = mergeLocationCountries(
-  LOCATION_DICTIONARIES.UZ || {},
-  UZ_LOCATION_EXTENSIONS,
-);
-
-export const CENTRAL_ASIA_LOCATION_DICTIONARIES = Object.freeze({
-  KZ: KZ_EXPANDED_LOCATION_DICTIONARIES,
-  UZ: UZ_EXPANDED_LOCATION_DICTIONARIES,
-});
-
-const TYPE_BY_KEY = Object.freeze({
-  districts: 'district',
-  microdistricts: 'microdistrict',
-  mahallas: 'mahalla',
-  localAreas: 'local_area',
-  suburbs: 'suburb',
-  settlements: 'settlement',
-  metro: 'metro',
-  residentialComplexes: 'residential_complex',
-  streets: 'street',
-  landmarks: 'poi',
-  pois: 'poi',
-  searchClusters: 'search_cluster',
-});
-
-const GENERIC_AMBIGUOUS = new Set([
-  'center', 'old city', 'new city', 'airport', 'railway station area', 'university area',
-  'central park', 'embankment', 'bazaar', 'market', 'north', 'east', 'south west',
-]);
-
-const KZ_AMBIGUOUS = new Set(KZ_AMBIGUOUS_LOCAL_NAMES.map(normalizeForMatch));
-const UZ_AMBIGUOUS = new Set(UZ_AMBIGUOUS_LOCAL_NAMES.map(normalizeForMatch));
-
-function cityCatalog(countryCode) {
-  return countryCode === 'KZ' ? KZ_CITY_CATALOG : countryCode === 'UZ' ? UZ_CITY_CATALOG : [];
-}
-
-function dictionaries(countryCode) {
-  return CENTRAL_ASIA_LOCATION_DICTIONARIES[countryCode] || {};
-}
-
-function canonicalCity(value, countryCode) {
-  return countryCode === 'KZ'
-    ? canonicalKazakhstanCity(value)
-    : countryCode === 'UZ'
-      ? canonicalUzbekistanCity(value)
-      : null;
-}
-
-const cityRegexCache = new Map();
-function cityRegex(item) {
-  const key = `${item.country}:${item.canonical}`;
-  if (!cityRegexCache.has(key)) {
-    cityRegexCache.set(key, aliasesToRegex([item.canonical, ...aliasesOf(item)]));
-  }
-  return cityRegexCache.get(key);
-}
-
-function explicitCityFromText(text, countryCode) {
-  const value = String(text || '');
-  const matches = [];
-  for (const item of cityCatalog(countryCode)) {
-    const match = value.match(cityRegex(item));
-    if (!match) continue;
-    if (item.contextRequired) {
-      const start = match.index || 0;
-      const before = value.slice(Math.max(0, start - 40), start);
-      const after = value.slice(start + match[0].length, start + match[0].length + 48);
-      if (!/(?:shahri|город|viloyati|область|andijon|андижан)/iu.test(`${before} ${after}`)) continue;
-    }
-    matches.push({ item, length: normalizeForMatch(match[0]).length });
-  }
-  matches.sort((a, b) => b.length - a.length);
-  return matches[0]?.item?.canonical || null;
-}
-
-function isExplicitMetroContext(value, match) {
-  const start = match.index ?? 0;
-  const end = start + match[0].length;
-  const before = value.slice(Math.max(0, start - 36), start);
-  const after = value.slice(end, end + 36);
-  return /(?:метро|metro|станц(?:ия|ии)?|station|ст\.?\s*м\.?|м\.)\s*[:\-–—]?\s*$/iu.test(before)
-    || /^\s*(?:метро|metro|station|станц(?:ия|ии)?)(?=$|[^\p{L}\p{N}_])/iu.test(after);
-}
-
-function metroOverlapsArea(item, data) {
-  const itemKeys = new Set([item.name, ...(item.aliases || [])].map(normalizeForMatch).filter(Boolean));
-  return ['microdistricts', 'localAreas'].some((key) => (data?.[key] || []).some((area) =>
-    [area.name, ...(area.aliases || [])].map(normalizeForMatch).some((value) => itemKeys.has(value)),
-  ));
-}
-
-function findEntryMatches(text, cityName, data) {
-  const value = String(text || '');
-  const matches = [];
-  for (const key of LOCATION_LIST_KEYS) {
-    for (const item of data?.[key] || []) {
-      const match = value.match(item?.re);
-      if (!match) continue;
-      if (key === 'metro' && metroOverlapsArea(item, data) && !isExplicitMetroContext(value, match)) continue;
-      matches.push(Object.freeze({
-        country: item.country || null,
-        city: cityName,
-        type: item.entityType || TYPE_BY_KEY[key] || key,
-        key,
-        name: item.name,
-        aliases: item.aliases || [],
-        district: item.district || null,
-        parent: item.parent || item.district || null,
-        confidence: item.confidence || null,
-        language: item.language || null,
-      }));
-    }
-  }
-  return matches;
-}
-
-function isAmbiguousMatch(match, countryCode) {
-  const keys = [match.name, ...(match.aliases || [])].map(normalizeForMatch).filter(Boolean);
-  if (keys.some((key) => GENERIC_AMBIGUOUS.has(key))) return true;
-  if (countryCode === 'KZ' && keys.some((key) => KZ_AMBIGUOUS.has(key))) return true;
-  if (countryCode === 'UZ' && keys.some((key) => UZ_AMBIGUOUS.has(key))) return true;
-  return false;
-}
-
-function clusterMatches(matches, countryCode) {
-  if (countryCode !== 'KZ') return [];
-  const names = new Set(matches.map((item) => normalizeForMatch(item.name)));
-  return KZ_SEARCH_CLUSTERS.filter((cluster) => cluster.members.some((member) => names.has(normalizeForMatch(member))));
-}
-
-export function centralAsiaLocationCities(countryCode) {
-  return dictionaries(countryCode);
-}
-
-export function centralAsiaLocationCity(countryCode, city) {
-  const canonical = canonicalCity(city, countryCode) || city;
-  return dictionaries(countryCode)[canonical] || null;
-}
-
-export function matchCentralAsiaLocationEntities(text, countryCode, preferredCity = null) {
-  if (!text || !['KZ', 'UZ'].includes(countryCode)) {
-    return Object.freeze({ city: null, matches: Object.freeze([]), searchClusters: Object.freeze([]), candidates: Object.freeze([]) });
-  }
-
-  const country = dictionaries(countryCode);
-  const preferred = canonicalCity(preferredCity, countryCode) || preferredCity;
-  const explicit = explicitCityFromText(text, countryCode);
-  const scopedCity = preferred && country[preferred] ? preferred : explicit && country[explicit] ? explicit : null;
-
-  if (scopedCity) {
-    const matches = findEntryMatches(text, scopedCity, country[scopedCity]);
-    const clusters = clusterMatches(matches, countryCode);
-    return Object.freeze({ city: scopedCity, matches: Object.freeze(matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
-  }
-
-  const byCity = [];
-  for (const [cityName, data] of Object.entries(country)) {
-    const matches = findEntryMatches(text, cityName, data);
-    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([]) });
-  }
-
-  // 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
-  // that no other city matched.
-  const strong = byCity.filter((candidate) => candidate.matches.some((match) => !isAmbiguousMatch(match, countryCode)));
-  const selected = strong.length === 1
-    ? strong[0]
-    : byCity.length === 1 && byCity[0].matches.some((match) => !isAmbiguousMatch(match, countryCode))
-      ? byCity[0]
-      : null;
-
-  if (!selected) {
-    return Object.freeze({
-      city: null,
-      matches: Object.freeze([]),
-      searchClusters: Object.freeze([]),
-      candidates: Object.freeze(byCity.map((candidate) => Object.freeze({ city: candidate.city, matches: Object.freeze(candidate.matches) }))),
-    });
-  }
-
-  const clusters = clusterMatches(selected.matches, countryCode);
-  return Object.freeze({ city: selected.city, matches: Object.freeze(selected.matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
-}
-
-export function matchCentralAsiaLocationEntity(text, countryCode, preferredCity = null, type = null) {
-  const result = matchCentralAsiaLocationEntities(text, countryCode, preferredCity);
-  return result.matches.find((item) => !type || item.type === type || item.key === type) || null;
-}
+import { LOCATION_DICTIONARIES } from './locations.js';
+import { LOCATION_LIST_KEYS, mergeLocationCountries } from './location-merge.js';
+import { aliasesOf, aliasesToRegex, normalizeForMatch } from './normalization.js';
+import {
+  KZ_CITY_CATALOG,
+  UZ_CITY_CATALOG,
+  canonicalKazakhstanCity,
+  canonicalUzbekistanCity,
+} from './central-asia.js';
+import { KZ_AMBIGUOUS_LOCAL_NAMES, KZ_LOCATION_EXTENSIONS, KZ_SEARCH_CLUSTERS } from './kz-location-extensions.js';
+import { UZ_AMBIGUOUS_LOCAL_NAMES, UZ_LOCATION_EXTENSIONS } from './uz-location-extensions.js';
+
+export const KZ_EXPANDED_LOCATION_DICTIONARIES = mergeLocationCountries(
+  LOCATION_DICTIONARIES.KZ || {},
+  KZ_LOCATION_EXTENSIONS,
+);
+
+export const UZ_EXPANDED_LOCATION_DICTIONARIES = mergeLocationCountries(
+  LOCATION_DICTIONARIES.UZ || {},
+  UZ_LOCATION_EXTENSIONS,
+);
+
+export const CENTRAL_ASIA_LOCATION_DICTIONARIES = Object.freeze({
+  KZ: KZ_EXPANDED_LOCATION_DICTIONARIES,
+  UZ: UZ_EXPANDED_LOCATION_DICTIONARIES,
+});
+
+const TYPE_BY_KEY = Object.freeze({
+  districts: 'district',
+  microdistricts: 'microdistrict',
+  mahallas: 'mahalla',
+  localAreas: 'local_area',
+  suburbs: 'suburb',
+  settlements: 'settlement',
+  metro: 'metro',
+  residentialComplexes: 'residential_complex',
+  streets: 'street',
+  landmarks: 'poi',
+  pois: 'poi',
+  searchClusters: 'search_cluster',
+});
+
+const GENERIC_AMBIGUOUS = new Set([
+  'center', 'old city', 'new city', 'airport', 'railway station area', 'university area',
+  'central park', 'embankment', 'bazaar', 'market', 'north', 'east', 'south west',
+]);
+
+const KZ_AMBIGUOUS = new Set(KZ_AMBIGUOUS_LOCAL_NAMES.map(normalizeForMatch));
+const UZ_AMBIGUOUS = new Set(UZ_AMBIGUOUS_LOCAL_NAMES.map(normalizeForMatch));
+
+function cityCatalog(countryCode) {
+  return countryCode === 'KZ' ? KZ_CITY_CATALOG : countryCode === 'UZ' ? UZ_CITY_CATALOG : [];
+}
+
+function dictionaries(countryCode) {
+  return CENTRAL_ASIA_LOCATION_DICTIONARIES[countryCode] || {};
+}
+
+function canonicalCity(value, countryCode) {
+  return countryCode === 'KZ'
+    ? canonicalKazakhstanCity(value)
+    : countryCode === 'UZ'
+      ? canonicalUzbekistanCity(value)
+      : null;
+}
+
+const cityRegexCache = new Map();
+function cityRegex(item) {
+  const key = `${item.country}:${item.canonical}`;
+  if (!cityRegexCache.has(key)) {
+    cityRegexCache.set(key, aliasesToRegex([item.canonical, ...aliasesOf(item)]));
+  }
+  return cityRegexCache.get(key);
+}
+
+function explicitCityFromText(text, countryCode) {
+  const value = String(text || '');
+  const matches = [];
+  for (const item of cityCatalog(countryCode)) {
+    const match = value.match(cityRegex(item));
+    if (!match) continue;
+    if (item.contextRequired) {
+      const start = match.index || 0;
+      const before = value.slice(Math.max(0, start - 40), start);
+      const after = value.slice(start + match[0].length, start + match[0].length + 48);
+      if (!/(?:shahri|город|viloyati|область|andijon|андижан)/iu.test(`${before} ${after}`)) continue;
+    }
+    matches.push({ item, length: normalizeForMatch(match[0]).length });
+  }
+  matches.sort((a, b) => b.length - a.length);
+  return matches[0]?.item?.canonical || null;
+}
+
+function isExplicitMetroContext(value, match) {
+  const start = match.index ?? 0;
+  const end = start + match[0].length;
+  const before = value.slice(Math.max(0, start - 36), start);
+  const after = value.slice(end, end + 36);
+  return /(?:метро|metro|станц(?:ия|ии)?|station|ст\.?\s*м\.?|м\.)\s*[:\-–—]?\s*$/iu.test(before)
+    || /^\s*(?:метро|metro|station|станц(?:ия|ии)?)(?=$|[^\p{L}\p{N}_])/iu.test(after);
+}
+
+function metroOverlapsArea(item, data) {
+  const itemKeys = new Set([item.name, ...(item.aliases || [])].map(normalizeForMatch).filter(Boolean));
+  return ['microdistricts', 'localAreas'].some((key) => (data?.[key] || []).some((area) =>
+    [area.name, ...(area.aliases || [])].map(normalizeForMatch).some((value) => itemKeys.has(value)),
+  ));
+}
+
+function findEntryMatches(text, cityName, data) {
+  const value = String(text || '');
+  const matches = [];
+  for (const key of LOCATION_LIST_KEYS) {
+    for (const item of data?.[key] || []) {
+      const match = value.match(item?.re);
+      if (!match) continue;
+      if (key === 'metro' && metroOverlapsArea(item, data) && !isExplicitMetroContext(value, match)) continue;
+      matches.push(Object.freeze({
+        country: item.country || null,
+        city: cityName,
+        type: item.entityType || TYPE_BY_KEY[key] || key,
+        key,
+        name: item.name,
+        aliases: item.aliases || [],
+        district: item.district || null,
+        parent: item.parent || item.district || null,
+        confidence: item.confidence || null,
+        language: item.language || null,
+      }));
+    }
+  }
+  return matches;
+}
+
+function isAmbiguousMatch(match, countryCode) {
+  const keys = [match.name, ...(match.aliases || [])].map(normalizeForMatch).filter(Boolean);
+  if (keys.some((key) => GENERIC_AMBIGUOUS.has(key))) return true;
+  if (countryCode === 'KZ' && keys.some((key) => KZ_AMBIGUOUS.has(key))) return true;
+  if (countryCode === 'UZ' && keys.some((key) => UZ_AMBIGUOUS.has(key))) return true;
+  return false;
+}
+
+function clusterMatches(matches, countryCode) {
+  if (countryCode !== 'KZ') return [];
+  const names = new Set(matches.map((item) => normalizeForMatch(item.name)));
+  return KZ_SEARCH_CLUSTERS.filter((cluster) => cluster.members.some((member) => names.has(normalizeForMatch(member))));
+}
+
+export function centralAsiaLocationCities(countryCode) {
+  return dictionaries(countryCode);
+}
+
+export function centralAsiaLocationCity(countryCode, city) {
+  const canonical = canonicalCity(city, countryCode) || city;
+  return dictionaries(countryCode)[canonical] || null;
+}
+
+export function matchCentralAsiaLocationEntities(text, countryCode, preferredCity = null) {
+  if (!text || !['KZ', 'UZ'].includes(countryCode)) {
+    return Object.freeze({ city: null, matches: Object.freeze([]), searchClusters: Object.freeze([]), candidates: Object.freeze([]) });
+  }
+
+  const country = dictionaries(countryCode);
+  const preferred = canonicalCity(preferredCity, countryCode) || preferredCity;
+  const explicit = explicitCityFromText(text, countryCode);
+  const scopedCity = preferred && country[preferred] ? preferred : explicit && country[explicit] ? explicit : null;
+
+  if (scopedCity) {
+    const matches = findEntryMatches(text, scopedCity, country[scopedCity]);
+    const clusters = clusterMatches(matches, countryCode);
+    return Object.freeze({ city: scopedCity, matches: Object.freeze(matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
+  }
+
+  const byCity = [];
+  for (const [cityName, data] of Object.entries(country)) {
+    const matches = findEntryMatches(text, cityName, data);
+    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([]) });
+  }
+
+  // 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
+  // that no other city matched.
+  const strong = byCity.filter((candidate) => candidate.matches.some((match) => !isAmbiguousMatch(match, countryCode)));
+  const selected = strong.length === 1
+    ? strong[0]
+    : byCity.length === 1 && byCity[0].matches.some((match) => !isAmbiguousMatch(match, countryCode))
+      ? byCity[0]
+      : null;
+
+  if (!selected) {
+    return Object.freeze({
+      city: null,
+      matches: Object.freeze([]),
+      searchClusters: Object.freeze([]),
+      candidates: Object.freeze(byCity.map((candidate) => Object.freeze({ city: candidate.city, matches: Object.freeze(candidate.matches) }))),
+    });
+  }
+
+  const clusters = clusterMatches(selected.matches, countryCode);
+  return Object.freeze({ city: selected.city, matches: Object.freeze(selected.matches), searchClusters: Object.freeze(clusters), candidates: Object.freeze([]) });
+}
+
+export function matchCentralAsiaLocationEntity(text, countryCode, preferredCity = null, type = null) {
+  const result = matchCentralAsiaLocationEntities(text, countryCode, preferredCity);
+  return result.matches.find((item) => !type || item.type === type || item.key === type) || null;
+}