@mailwoman/kind-classifier 9.0.0 → 9.2.0

package/out/types.js

@@ -3,5 +3,5 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
-export {};
+export { QueryIntentCode } from "@mailwoman/core/pipeline";
 //# sourceMappingURL=types.js.map

package/out/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mailwoman/kind-classifier",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "Stage 2.5 of the runtime pipeline — categorize inputs by query shape (postcode_only / locality_only / structured_address / intersection / po_box / landmark / vague). Rule-based for v1.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
     "type": "git",
     "url": "https://github.com/sister-software/mailwoman.git",
-    "directory": "kind-classifier"
+    "directory": "packages/kind-classifier"
   },
   "files": [
     "out/**/*.js",
@@ -20,7 +20,8 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "!test/**"
   ],
   "type": "module",
   "exports": {
@@ -28,6 +29,26 @@
     ".": {
       "types": "./out/index.d.ts",
       "default": "./out/index.js"
+    },
+    "./classify": {
+      "types": "./out/classify.d.ts",
+      "default": "./out/classify.js"
+    },
+    "./types": {
+      "types": "./out/types.d.ts",
+      "default": "./out/types.js"
+    },
+    "./intent-rules": {
+      "types": "./out/intent-rules.d.ts",
+      "default": "./out/intent-rules.js"
+    },
+    "./rules": {
+      "types": "./out/rules.d.ts",
+      "default": "./out/rules.js"
+    },
+    "./poi": {
+      "types": "./out/poi.d.ts",
+      "default": "./out/poi.js"
     }
   },
   "publishConfig": {
@@ -37,10 +58,33 @@
       ".": {
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
+      },
+      "./classify": {
+        "types": "./out/classify.d.ts",
+        "default": "./out/classify.js"
+      },
+      "./types": {
+        "types": "./out/types.d.ts",
+        "default": "./out/types.js"
+      },
+      "./intent-rules": {
+        "types": "./out/intent-rules.d.ts",
+        "default": "./out/intent-rules.js"
+      },
+      "./rules": {
+        "types": "./out/rules.d.ts",
+        "default": "./out/rules.js"
+      },
+      "./poi": {
+        "types": "./out/poi.d.ts",
+        "default": "./out/poi.js"
       }
     }
   },
   "dependencies": {
-    "@mailwoman/core": "9.0.0"
+    "@mailwoman/core": "9.2.0"
+  },
+  "devDependencies": {
+    "@mailwoman/query-shape": "9.2.0"
   }
 }

package/poi.ts

@@ -22,18 +22,20 @@ const MAX_POI_SEGMENTS = 3
  */
 export interface POIPhraseMatch {
 	/**
-	 * The matched subject's identifier string. For `kind: "category"`, a `@mailwoman/poi-taxonomy` category id. For
-	 * `kind: "brand"`, the brand's canonical display name (NOT a taxonomy id) — `matchPOISubject` never reads this field
-	 * itself, so the caller (`mailwoman`'s `poi-intent.ts`) is the one that interprets it per `kind`.
+	 * The matched subject's identifier string. For `kind: "category"`, a `@mailwoman/poi-taxonomy` category id; for
+	 * `kind: "brand"` or `kind: "name"`, the canonical display name. `matchPOISubject` treats it opaquely; the caller
+	 * (`mailwoman`'s `poi-intent.ts`) interprets it per `kind`.
 	 */
 	categoryID: string
 	matchedPhrase: string
 	confidence: number
+	mechanism?: "exact" | "locale_normalized" | "typo"
+	inputPhrase?: string
 	/**
 	 * Absent = "category" (the pre-brand shape) — optional so pre-7.3 POIPhraseLookup implementors stay
 	 * source-compatible.
 	 */
-	kind?: "category" | "brand"
+	kind?: "category" | "brand" | "name"
 	/**
 	 * Wikidata QID, when known. `kind: "brand"` only — absent when a brand resolved by name alone (no QID match).
 	 */
@@ -45,6 +47,17 @@ export interface POIPhraseMatch {
  */
 export type POIPhraseLookup = (phrase: string, locale?: string) => ReadonlyArray<POIPhraseMatch>
 
+export type POISpatialRelation = "comma" | "near" | "in" | "at" | "around" | "to"
+
+export interface POIQuerySpan {
+	text: string
+	/**
+	 * Half-open character offsets into the normalized input.
+	 */
+	start: number
+	end: number
+}
+
 /**
  * Which lexicon this hit came from. Existing category lookups set `"category"` (backward-compatible default).
  */
@@ -54,15 +67,22 @@ export interface POISubjectMatch {
 	 * The matched subject text as it appeared in the query.
 	 */
 	subject: string
+	subjectSpan: POIQuerySpan
+	/**
+	 * The relation crossing from the subject span to the anchor span.
+	 */
+	relation?: POISpatialRelation
+	relationSpan?: POIQuerySpan
 	/**
 	 * The anchor remainder after the separator; `""` when the whole input matched.
 	 */
 	remainder: string
+	anchorSpan?: POIQuerySpan
 }
 
 /**
- * Anchor separator between subject and place: comma, or near/in/at/around — scanned left-to-right until a prefix hits
- * the lexicon.
+ * Anchor separator between subject and place: comma, or near/in/at/around/to — scanned left-to-right until a prefix
+ * hits the lexicon.
  *
  * Linear by construction (no polynomial ReDoS): neither alternative places an unbounded whitespace quantifier _before_
  * its required literal — the classic `\s*`/`\s+`-then-literal backtracking shape that CodeQL's `js/polynomial-redos`
@@ -78,16 +98,16 @@ export interface POISubjectMatch {
  * lastIndex) identical, preserving the exact subsequent-match sequence. Verified: 0 divergences across 22.7k inputs
  * (systematic + fuzzed adversarial whitespace + shared-whitespace anchor/comma chains).
  */
-const ANCHOR_SEPARATOR = /,\s*|\s(?:near|in|at|around)\s+/gi
+const ANCHOR_SEPARATOR = /,\s*|\s(near|in|at|around|to)\s+/gi
 
 /**
- * Longest subject we accept, in tokens. Lexicon phrases are short; 4 covers the table.
+ * Longest subject we accept, in tokens. Eight covers compound taxonomy phrases while bounding lexicon probes.
  */
-const MAX_SUBJECT_TOKENS = 4
+const MAX_SUBJECT_TOKENS = 8
 
 /**
  * Match a POI subject: the whole input, or the text before the FIRST anchor separator WHOSE PREFIX HITS THE LEXICON (≤
- * 4 tokens). Scans separator occurrences left-to-right — a lexicon phrase may itself contain a bare separator word
+ * 8 tokens). Scans separator occurrences left-to-right — a lexicon phrase may itself contain a bare separator word
  * (e.g. "walk in clinic"), so the first separator isn't necessarily the right split point. Returns null when the
  * lexicon never fires — including comma-ridden full addresses whose leading segment isn't a lexicon phrase.
  */
@@ -97,13 +117,19 @@ export function matchPOISubject(
 	lookup: POIPhraseLookup
 ): POISubjectMatch | null {
 	const trimmed = text.trim()
+	const inputStart = text.indexOf(trimmed)
 
 	if (!trimmed) return null
 
 	const whole = lookup(trimmed, locale)
 
 	if (whole.length) {
-		return { match: whole[0]!, subject: trimmed, remainder: "" }
+		return {
+			match: whole[0]!,
+			subject: trimmed,
+			subjectSpan: { text: trimmed, start: inputStart, end: inputStart + trimmed.length },
+			remainder: "",
+		}
 	}
 
 	for (const separator of trimmed.matchAll(ANCHOR_SEPARATOR)) {
@@ -120,7 +146,34 @@ export function matchPOISubject(
 
 		const remainder = trimmed.slice(separator.index + separator[0].length).trim()
 
-		return { match: hits[0]!, subject, remainder }
+		if (!remainder) continue
+
+		const subjectOffset = trimmed.slice(0, separator.index).indexOf(subject)
+		const anchorOffset = trimmed.indexOf(remainder, separator.index + separator[0].length)
+		const relationText = separator[1] ?? ","
+		const relationOffset = separator[1] ? separator.index + separator[0].indexOf(separator[1]) : separator.index
+
+		return {
+			match: hits[0]!,
+			subject,
+			subjectSpan: {
+				text: subject,
+				start: inputStart + subjectOffset,
+				end: inputStart + subjectOffset + subject.length,
+			},
+			relation: relationText === "," ? "comma" : (relationText.toLowerCase() as POISpatialRelation),
+			relationSpan: {
+				text: relationText,
+				start: inputStart + relationOffset,
+				end: inputStart + relationOffset + relationText.length,
+			},
+			remainder,
+			anchorSpan: {
+				text: remainder,
+				start: inputStart + anchorOffset,
+				end: inputStart + anchorOffset + remainder.length,
+			},
+		}
 	}
 
 	return null
@@ -153,3 +206,53 @@ export function createScorePOIQuery(
 		return 0.9 * matched.match.confidence
 	}
 }
+
+/**
+ * Confidence band for a bare category. One notch above `poi_query`'s whole-input band (0.92) so the anchorless subset
+ * takes the top slot from it, and only from it — every anchored POI query keeps scoring `poi_query` exactly as before.
+ * The coordinator's POI branch accepts both kinds, so the routing is identical either way; the split exists so the
+ * marker can say "you named a category and no place", which is a different thing to tell a caller.
+ */
+const POI_CATEGORY_CONFIDENCE = 0.93
+
+/**
+ * `poi_category` scorer (ROAD_TO_V9 §4.4) — a bare taxonomy category with nowhere to search: "tacos", "grocery store",
+ * "drinking fountain".
+ *
+ * Fires ONLY on a whole-input lexicon hit (`remainder === ""`) whose subject is a CATEGORY. A brand (`kind: "brand"`)
+ * is excluded: a bare "Starbucks" is a name lookup, not a category, and the taxonomy id a category marker promises to
+ * carry does not exist for it — `POIPhraseMatch.categoryID` holds the brand's display name in that case, which would
+ * make the marker's `categoryID` evidence a lie.
+ */
+export function createScorePOICategory(
+	lookup: POIPhraseLookup,
+	locale?: string
+): (input: NormalizedInputLite, shape: QueryShapeLike) => number {
+	return (input, _shape) => {
+		const matched = matchPOISubject(input.normalized, locale ?? input.appliedLocale, lookup)
+
+		if (!matched || matched.remainder !== "") return 0
+
+		if ((matched.match.kind ?? "category") !== "category") return 0
+
+		return POI_CATEGORY_CONFIDENCE * matched.match.confidence
+	}
+}
+
+/**
+ * The whole-input category hit behind a `poi_category` verdict, for the marker's evidence. `null` when the input is not
+ * a bare category — same gates as {@link createScorePOICategory}, so the two cannot disagree.
+ */
+export function matchPOICategory(
+	text: string,
+	locale: string | undefined,
+	lookup: POIPhraseLookup
+): POIPhraseMatch | null {
+	const matched = matchPOISubject(text, locale, lookup)
+
+	if (!matched || matched.remainder !== "") return null
+
+	if ((matched.match.kind ?? "category") !== "category") return null
+
+	return matched.match
+}

package/rules.ts

@@ -31,8 +31,12 @@ const MIN_POSTCODE_COVERAGE = 0.7
 
 /**
  * Longest input still plausible as a bare locality name, including a trailing region code.
+ *
+ * Exported so `intent-rules.ts`'s `bare_toponym` can share the exact same ceiling. Sharing it is what makes
+ * "bare_toponym is a strict refinement of locality_only" a structural property rather than two numbers that happen to
+ * agree today.
  */
-const MAX_LOCALITY_ONLY_LENGTH = 30
+export const MAX_LOCALITY_ONLY_LENGTH = 30
 
 /**
  * Word count of a short capitalized phrase — the shape of a venue name like `Empire State Building`. Wider than this
@@ -124,9 +128,10 @@ export function scoreLandmark(input: NormalizedInputLite, _shape: QueryShapeLike
 }
 
 /**
- * Street-suffix tokens that indicate an address, not a venue name.
+ * Street-suffix tokens that indicate an address, not a venue name. Shared with `intent-rules.ts` — the intent kinds
+ * disqualify on the same vocabulary, and a second copy would drift.
  */
-const STREET_SUFFIXES = new Set([
+export const STREET_SUFFIXES: ReadonlySet<string> = new Set([
 	"st",
 	"street",
 	"ave",
@@ -223,6 +228,10 @@ const POSTCODE_FORMATS: ReadonlySet<string> = new Set([
 	"ca_postcode",
 	"jp_postcode",
 	"nl_postcode",
+	"cz_postcode",
+	"sk_postcode",
+	"se_postcode",
+	"gr_postcode",
 ])
 
 /**

package/types.ts

@@ -7,7 +7,8 @@
 /**
  * Re-exports of the canonical types from `@mailwoman/core/pipeline`.
  */
-export type { LocaleHint, QueryKind, QueryKindResult } from "@mailwoman/core/pipeline"
+export type { LocaleHint, QueryIntentMarker, QueryKind, QueryKindResult } from "@mailwoman/core/pipeline"
+export { QueryIntentCode } from "@mailwoman/core/pipeline"
 
 /**
  * Minimal `NormalizedInput` shape consumed by `classifyKind`. Compatible with `@mailwoman/normalize`'s output.