import { Gender, Squad } from "@weekendgoals/weekendgoals-types/dist/classification"; /** * How a hit is ranked once the predicate has found it. * * The predicate (`search/tokens`) answers *whether* a row matches. It cannot * answer *which* of the matches the user meant, and on this data that is the * whole problem: "barc" reaches FC Barcelona, Barcelona SC and Kazincbarcikai * — and the FA WSL, the Premier League and the Premier League Asia Trophy, * each of which genuinely answers to a Barclays sponsor name. Every one of * those is a correct hit. Only one of them is the answer. * * Three things decide it: * * 1. **tier** — how the name matched: the whole of it, its start, a word * inside it, and whether that was the row's own name or an alias; * 2. **section** — men's senior before women's, senior before reserve and * youth (`SECTION_ORDER`); * 3. **prominence** — how big a thing it is, on one 0–1 scale for every * entity type. * * ## They are added, not compared in order * * The obvious design is lexicographic — tier first, ties broken by section, * ties broken by prominence — and it was measured against a production copy * and rejected. Three queries say why, and all three are the same shape: a * **weak entity matching the string slightly better than a hugely more * important one**. * * | query | lexicographic gives | because | * |---|---|---| * | "man" | *Isle Of Man*, over Manchester City | the country holds "Man" as an alternate name, so it is an exact hit and City is only a prefix | * | "real" | *Real* (Portugal, ranked 4,839th), over Real Madrid | a club is literally called that | * | "united" | *United* (India, 12,540th), over Manchester United | so is a club there | * * No tie-break can fix those, because they are not ties. Prominence has to be * able to outweigh a tier or two, which means one score: * * score = tier + (1 − prominence ÷ section decay) × PROMINENCE_WEIGHT * (lowest wins) * * `PROMINENCE_WEIGHT` is what a rung of the tier ladder is worth in * prominence, and it is a calibration rather than a measurement: high enough * that Manchester United outranks an Indian club named "United", low enough * that naming something exactly still finds it — "barcelona w" gives the * women's side, "barcelona b" the B team, over a club rated 96. Every one of * those is pinned in `test/unit/search-rank.spec.ts` against the row that * actually shipped the wrong answer. * * **Section is a term, not a gate**, for the same reason: demoting women's and * youth rows ahead of everything else would break the query that names one. * It discounts a cohort's prominence rather than penalising its rows, which is * both what the numbers mean (see `SECTION_DECAY`) and enough to order equally * good matches without ever hiding one — "barcelona w" gives the women's side, * "barcelona b" the B team. */ /** * How much of a name the term matched, and whether it was the name the row is * actually called. * * The ladder is the one `LeaguesMongoDao.searchTier` established, with its two * bottom rungs corrected: they were substring-anywhere (`includes`), which is * what let "man" match *O**man*** and "real" match *Villa**real***. A term is * a word being typed, so it matches at a word boundary or not at all. * * Own name before alias, at every rung, for the reason the city matcher has * the same rule: GeoNames lists "London" among the City of London's alternate * names, so both rows answer to it and only one is called it. */ export declare const MATCH_TIERS: { readonly ownExact: 0; readonly aliasExact: 1; readonly ownPrefix: 2; readonly aliasPrefix: 3; readonly ownWordPrefix: 4; readonly aliasWordPrefix: 5; /** Matched some other way — every query word prefixed *some* token, but not * in an order the name reads in ("mad real"), or the row was reached by its * country rather than its name. Still a hit; ranks last. */ readonly other: 6; }; /** * What a rung of the ladder is worth in prominence, and what a section step * is worth in rungs. * * 6 is not arbitrary: it is the smallest weight that lets Manchester United * (7th in the world, and only a *word* of its name typed) outrank the Indian * club literally called "United" (12,540th) — a four-rung gap, the widest any * of the measured cases needs bridged. Every case in the table above and * every counter-case (an exact name still winning) is pinned in * `test/unit/search-rank.spec.ts`. */ export declare const PROMINENCE_WEIGHT = 6; /** * How much of its prominence a row loses per section step. * * A section step cannot be a flat penalty added to the score, because * **prominence is measured inside a section and does not cross one**: * Barcelona W is 1st of 1,191 women's sides and Barcelona 5th of 11,917 * men's, so on the raw numbers the women's team looks the more prominent and * "barc" led with it. Dividing by the section instead keeps each rank meaning * what it measures and states the demotion where it belongs — in how much a * cohort's prominence is worth outside it. * * 0.35 is bounded on both sides by measured queries: high enough that a * women's #1 sits below a men's #5 for "barc", low enough that "liverpool w" * still gives Liverpool's women's side over the men's team two rungs better * matched. Both are pinned. */ export declare const SECTION_DECAY = 0.35; /** * How many rows may share an exact alias before it stops identifying anything. * * **34 teams hold the bare alias "United" and 25 hold "City"** — Leeds, West * Ham, Sheffield United and Rotherham are all called "United" by someone, and * each of those is a legitimate alternate name. But an exact hit on a name 34 * rows answer to is not an exact hit on an identity, and treating it as one * put Leeds, West Ham, Sheffield Utd, DC United, Peterborough and Rotherham * above Manchester United for the query "united" — which is the whole top of * the dropdown, and none of it what the user meant. * * So an alias-exact hit shared by more than a few candidates drops to the * word-prefix rung, where prominence decides between them. Nothing is hidden: * every one of those clubs is still a hit for "united", in the order a reader * would expect. This is inverse document frequency at its crudest, and it is * measured against the candidate set rather than precomputed because that is * where the question is asked. */ export declare const SHARED_ALIAS_LIMIT = 3; export interface NamedEntity { name?: string; alternateNames?: string[]; } /** * `folded` is the whole query folded — not its words. A multi-word query is * matched against the whole name, so "real mad" is a prefix of `real madrid` * and lands on `ownPrefix`. */ export declare function matchTier(entity: NamedEntity, folded: string): number; /** * **An unranked team is not a team ranked last.** 5,978 of 15,715 carry no * `globalRank`, and they are not the bottom of the table — they are the rows * Opta's club feed does not cover at all, which includes every national side. * Spain and Brazil sit here beside a village club, so scoring them 0 would put * "Spain" the team behind anything with a rating, while scoring them highly * would hand every unrated row the benefit. * * A rank of 12,540 is a measurement and lands near 0; absent is a silence and * lands here. The same distinction `LeaguesMongoDao.rankedLast` draws one * collection over. * * The national sides are the part of this that has a real answer: 414 of them * carry a `fifaRank`, Spain at 1. Round (a) deliberately did not read it — * folding it in moves Spain the *team* above Spain the *country*, and which of * those should lead could not be settled while the country's own prominence * was still a constant. Round (b) calibrates both together: `fifaProminence` * below, and `placeProminence` replacing `COUNTRY_PROMINENCE`. Measured * result — "spain" scores the country 0.41 (tier 0, prominence 0.932) against * the men's national team at 0.77 (tier 0, `fifaRank` 1 → prominence 0.872) — * country still leads, and both are pinned in `test/unit/search-rank.spec.ts`. * * `fifaRank` is exclusively a national-side signal — no club carries one — so * checking it first changes nothing for a club row. Only 22 of the 414 * `fifaRank` rows also carry a `globalRank`, and those are junk — Argentina * men's `globalRank` is 7577, a value the Opta CLUB feed assigned to the row, * not a measure of Argentina. There is no field that flags a row "national * side" for this function to key off; the presence of `fifaRank` on a row * that also holds a `globalRank` IS that signal, in this data, so `fifaRank` * is read first and the two are never blended. */ export declare const UNRANKED_TEAM_PROMINENCE = 0.3; export declare function teamProminence(team: { globalRank?: number; fifaRank?: number; }): number; /** Just past the worst FIFA rank in the collection (211). */ export declare const FIFA_RANK_FLOOR = 220; /** * A national side's prominence from its FIFA ranking, on the same log scale * `teamProminence` uses for `globalRank` — rank 1 near 1, rank 220 near 0. * Kept separate from `teamProminence` because `placeProminence` below needs * the same shape of function for a country's match count, and the two are * calibrated against each other (see `teamProminence`'s comment). */ export declare function fifaProminence(rank: number): number; export declare function leagueProminence(league: { rating?: number; rank?: number; }): number; /** * Just past England's 5,727 upcoming matches — the country with the most, on * a production copy measured 2026-08-27. */ export declare const COUNTRY_MATCH_FLOOR = 6000; /** * Just past London's 484 upcoming matches — the city with the most, same * measurement. */ export declare const CITY_MATCH_FLOOR = 500; /** * A place with at least one venue never scores below this, however few * upcoming matches it holds. * * Without it, prominence tracks the scraper: a stalled run drains every * country's `upcomingMatchCount` toward zero over a few weeks as fixtures * kick off and nothing replaces them, and search silently re-ranks the whole * world with no alarm on it. The floor bounds that decay. It does NOT apply * to a place with zero venues — Isle Of Man holds 0 venues and 0 upcoming * matches, and it has nothing to floor: it is meant to score 0, which is the * case this whole mechanism exists to fix (see `search-rank.spec.ts`, * `'man' leads with Manchester City`). */ export declare const VENUE_FLOOR_PROMINENCE = 0.1; /** * How much upcoming football a place hosts, log-scaled against a floor just * past the busiest place of its kind — the same shape `teamProminence` and * `fifaProminence` use, because both distributions are heavy-tailed (country * median 59 upcoming matches against a max of 5,727; city median 13 against * 484). * * `upcomingMatchCount` is written by `POST /ingest/places/recount` * (`CitiesDao.recountUpcomingMatches`) and read off the row already fetched * for the search — no extra query, and never computed live (see the module * comment). It undercounts systematically: **~30% of upcoming football has no * venue** (20,106 of 67,568 matches, mostly international fixtures before a * draw) and contributes to no place's count. Accepted rather than fixed — the * count is still the best signal available and the undercount is uniform * enough not to reorder the table, but a future reader should know the number * is a floor on the truth, not the truth. */ export declare function placeProminence(upcomingMatchCount: number | undefined, hasVenues: boolean | undefined, floor: number): number; export declare function cityProminence(city: { upcomingMatchCount?: number; hasVenues?: boolean; }): number; /** * "When a city and a club match the string about equally well, the club is * what was meant" — a flat term added to every city hit's score (lower wins, * so this demotes), applied once in `rankHit` rather than compared per query. * * Swept against six city-vs-club head-to-heads on a production copy * (`search-rank.spec.ts` pins all six): * * query club (rank) city (matches) flips club at * manchester Man City (3) 93 1.5 * barcelona Barcelona (5) 40 0 (never flips) * liverpool Liverpool (1) 30 0 (never flips) * valencia Valencia (63) 25 0 (never flips) * leicester Leicester (140) 15 0 (never flips) * hamburg Hamburger SV (250) 269 never (stays city) * * `manchester` is the hard one: the city matches EXACTLY (tier 0) and the * club only by prefix (tier 2) — a two-rung gap prominence alone cannot close * from either side, so only a flat penalty flips it. * * **Raised from 1.5 to 5 on 2026-08-27, on a product decision: a club comes * before a city, always.** At 1.5 two of the six stayed with the city — * `leicester`, because the data had drifted from the sweep above (the club is * 685th now, not 140th, and the city holds 57 upcoming matches, not 15), and * `hamburg`, which the sweep called "probably right" and which was overruled. * * 5 is what `hamburg` costs, and it is the whole reason the number is this * large: Hamburg hosts 269 upcoming matches — a prominence of 0.90, near the * top of the scale — while Hamburger SV is 250th in the world and matches the * string two rungs worse. Nothing smaller than 5 separates them, so at this * value the constant has stopped being a tie-break and become the rule it is * named for. Expect a city to rank below every club that answers the same * string, and read a smaller value as a decision to let prominence decide * again. * * A city still leads, and can still be the top hit, when no club answers the * string at all — "Мюнхен" and "Барселона" do exactly that, which is what * round (c) built. */ export declare const CITY_MATCH_PENALTY = 5; /** * What a country hit costs when the query did not actually NAME the country. * * A country is a big unambiguous thing: you either typed its name or you did * not. "united" is a prefix of *United States* and of *United Arab Emirates*, * but a person typing it into a football search box means a club — there are * dozens of them and they are what the word means in this domain. Giving * countries a real prominence (round (b)) made both of those outscore * Manchester United, because a prefix match is two rungs better than the word * match the club gets: * * united United States (528 matches) tier ownPrefix(2) 3.675 * Manchester United (rank 8) tier ownWordPrefix(4) 5.371 * * So the penalty applies only below `aliasExact` — a country that was named * outright keeps competing on prominence alone, which is what "spain", * "brazil", "england" and "germany" rely on. 2.5 is the smallest half-step * that clears the measured gap; every one of those queries is pinned in * `search-rank.spec.ts`. */ export declare const COUNTRY_PARTIAL_PENALTY = 2.5; /** * One ranked hit, whatever collection it came from. * * `type` is carried so the caller can group the ranked list back into * sections without ranking each section separately — the top hit is the head * of one list, and a section's position is decided by its best member. */ export interface RankedHit { type: "team" | "league" | "city" | "country"; entity: T; tier: number; section: number; prominence: number; score: number; /** The row's own folded name, for the last tie-break. */ sortName: string; } export declare function rankHit(type: RankedHit["type"], entity: T, folded: string, prominence: number, axes?: { gender?: Gender; squad?: Squad; }): RankedHit; /** * Order every hit, whatever collection it came from — the one entry point a * caller needs, and the only place the set-dependent correction above can be * applied, because it depends on what else matched. */ export declare function rankAll(hits: RankedHit[]): RankedHit[]; /** Lowest score first; name last, so equal rows are at least stable. */ export declare function compareHits(a: RankedHit, b: RankedHit): number; //# sourceMappingURL=rank.d.ts.map