@mailwoman/variant-aliases 7.2.0 → 7.2.1

package/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/variant-aliases` — regional variant alias table for amenity/brand queries.
+ *
+ *   The data file (`data/aliases.json`) catalogs ~35 hand-curated regional terms: "servo" → fuel
+ *   (en-AU), "マクド" → McDonald's (ja-JP), "PFK" → KFC (fr-CA), etc.
+ *
+ *   See:
+ *
+ *   - `docs/articles/understanding/exotic-poi/regional-variant-queries.md` for the linguistic
+ *       background and the source tables this data is derived from.
+ *   - Issue #166 for the v0.6.0+ runtime integration plan (kind classifier consumes this table to emit
+ *       `kind=amenity` / `kind=brand` proposals, gated by locale-gate output).
+ */
+
+export { VARIANT_ALIAS_VERSION, getAllAliases, lookupVariantAliases } from "./lookup.ts"
+export type {
+	AliasLookupResult,
+	AmenityAlias,
+	BrandAlias,
+	VariantAlias,
+	VariantAliasTable,
+	VariantKind,
+} from "./types.ts"

package/lookup.ts

@@ -0,0 +1,105 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Regional variant alias lookup. Given a token (or short phrase) and a detected locale, return the
+ *   canonical amenity category or brand it refers to.
+ *
+ *   This is the data-side foundation for #166 (variant alias table + locale-gated category matching).
+ *   The runtime integration into the kind classifier is v0.6.0+ work.
+ */
+
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+import type { AliasLookupResult, VariantAlias, VariantAliasTable } from "./types.ts"
+
+const moduleDir = import.meta.dirname
+
+function loadTable(): VariantAliasTable {
+	const candidates = [
+		resolve(moduleDir, "data/aliases.json"),
+		resolve(moduleDir, "../data/aliases.json"),
+		resolve(moduleDir, "../../variant-aliases/data/aliases.json"),
+	]
+
+	for (const path of candidates) {
+		try {
+			return JSON.parse(readFileSync(path, "utf8")) as VariantAliasTable
+		} catch {
+			// try next
+		}
+	}
+	throw new Error("variant-aliases: could not find data/aliases.json")
+}
+
+const TABLE = loadTable()
+
+/**
+ * Indexed by lowercased variant string for O(1) lookup. Multiple entries can share the same variant key (e.g. ambiguous
+ * "takeaway" only matches GB but not AU if both list it differently), so each entry is an array of all aliases that
+ * share the key.
+ */
+const INDEX: ReadonlyMap<string, ReadonlyArray<VariantAlias>> = (() => {
+	const map = new Map<string, VariantAlias[]>()
+
+	for (const a of TABLE.aliases) {
+		const key = a.variant.toLowerCase()
+		const existing = map.get(key) ?? []
+		existing.push(a)
+		map.set(key, existing)
+	}
+
+	return map
+})()
+
+/**
+ * Match a query token against the variant alias table, gated by detected locale.
+ *
+ * Confidence:
+ *
+ * - `1.0` when the detected locale (e.g. `en-AU`) is in the alias's `locales` list.
+ * - `0.5` when only the language part matches (e.g. detected `en-IE`, alias supports `en-AU`). This is intentionally
+ *   weaker because regional variants are by definition regional.
+ * - No match when neither holds.
+ *
+ * Returns ALL matches sorted by confidence descending. Multi-locale variants (like "petrol station" →
+ * en-GB/en-AU/en-NZ/en-ZA) return one entry per locale list — the caller picks.
+ */
+export function lookupVariantAliases(text: string, locale: string): AliasLookupResult[] {
+	const norm = text.trim().toLowerCase()
+
+	if (!norm) return []
+
+	const candidates = INDEX.get(norm)
+
+	if (!candidates || candidates.length === 0) return []
+
+	const language = locale.split(/[-_]/)[0]
+	const results: AliasLookupResult[] = []
+
+	for (const alias of candidates) {
+		if (alias.locales.includes(locale)) {
+			results.push({ alias, confidence: 1.0 })
+			continue
+		}
+		// Relaxed match: any locale in `locales` that shares the same language part.
+		const langMatch = alias.locales.some((l) => l.split(/[-_]/)[0] === language)
+
+		if (langMatch) {
+			results.push({ alias, confidence: 0.5 })
+		}
+	}
+
+	results.sort((a, b) => b.confidence - a.confidence)
+
+	return results
+}
+
+/** Pure-data accessor for callers that want to enumerate the table (e.g. corpus synthesis). */
+export function getAllAliases(): ReadonlyArray<VariantAlias> {
+	return TABLE.aliases
+}
+
+export const VARIANT_ALIAS_VERSION = TABLE.version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/variant-aliases",
-  "version": "7.2.0",
+  "version": "7.2.1",
   "description": "Regional variant alias table — local terms for amenities/brands gated by locale. 'servo' → fuel (en-AU), 'マクド' → McDonald's (ja-JP), 'PFK' → KFC (fr-CA).",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -13,18 +13,32 @@
     "out/**/*.js.map",
     "out/**/*.d.ts",
     "out/**/*.d.ts.map",
-    "data/**/*.json"
+    "data/**/*.json",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    }
   }
 }

package/types.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Types for the regional variant alias table.
+ */
+
+/**
+ * The semantic kind of a variant — either a generic amenity category or a specific brand.
+ *
+ * - `amenity` aliases resolve to a category (`fuel`, `pharmacy`, `convenience`, ...). Several variants can map to the
+ *   same category ("servo" and "petrol station" both → `fuel`).
+ * - `brand` aliases resolve to a canonical brand name. Multiple regional variants of the same brand ("Macca's", "McDo",
+ *   "Mickey D's", "マクド") all map to `McDonald's`.
+ */
+export type VariantKind = "amenity" | "brand"
+
+export interface VariantAliasBase {
+	/** The user-typed variant. Always lowercase for the lookup key (CJK preserved as-is). */
+	variant: string
+	/**
+	 * BCP-47 locale tags where this variant is in active use. Used to gate lookups: only consider an alias when the
+	 * detected locale matches one of these. A query in `en-US` won't match Australian "servo" because `en-AU` is not in
+	 * `["en-US"]`.
+	 */
+	locales: ReadonlyArray<string>
+	/**
+	 * Free-form regional refinement within the locale (e.g. "NYC", "Kansai", "Quebec"). Not used for matching today;
+	 * informational. A future enhancement could combine this with a coarse geolocation signal to further disambiguate.
+	 */
+	regionHint?: string
+}
+
+export interface AmenityAlias extends VariantAliasBase {
+	kind: "amenity"
+	/** Canonical amenity category (e.g. `fuel`, `pharmacy`, `convenience`, `alcohol`). */
+	category: string
+}
+
+export interface BrandAlias extends VariantAliasBase {
+	kind: "brand"
+	/** Canonical brand display name (e.g. `McDonald's`, `7-Eleven`). */
+	brand: string
+}
+
+export type VariantAlias = AmenityAlias | BrandAlias
+
+export interface VariantAliasTable {
+	version: string
+	description: string
+	aliases: ReadonlyArray<VariantAlias>
+}
+
+export interface AliasLookupResult {
+	alias: VariantAlias
+	/** Confidence in the match. 1.0 = exact locale match. 0.5 = relaxed (locale fallback to language). */
+	confidence: number
+}