diff --git a/shared/duel/profile.ts b/shared/duel/profile.ts new file mode 100644 index 0000000..6b24c0f --- /dev/null +++ b/shared/duel/profile.ts @@ -0,0 +1,114 @@ +/** + * Building the frozen CardProfile (data review §3) from data the host already has or fetches once + * through the polite Wikimedia client. Pure: this file never fetches. The host: + * 1. takes the cached PageEnrichment (description, wikidataId, categories), + * 2. fetches the item once with wikidataEntityParams([qid, …]) (≤ 50 ids per request), + * 3. fetches the labels of the P31/P279 classes it doesn't know with wikidataLabelParams(ids), + * 4. optionally adds outlinks (prop=links, ns0) as pageIds, + * 5. calls profileFromSources() and stores the result per tokenId forever. + * Owner: duel-cards. + */ +import type { PageEnrichment } from '../enrichment.ts'; +import type { CardProfile, WikidataClass } from './classify.ts'; + +export const PROFILE_PROPERTIES = { + instanceOf: 'P31', subclassOf: 'P279', country: 'P17', citizenship: 'P27', + birth: 'P569', death: 'P570', inception: 'P571', start: 'P580', pointInTime: 'P585', +} as const; + +/** Properties whose item values count as "cited" for the Linked tier (DUEL_DESIGN §6). */ +export const CITE_PROPERTIES = ['P17', 'P27', 'P131', 'P361', 'P527', 'P463', 'P102', 'P108', 'P69', 'P19', 'P20', 'P710', 'P1344', 'P276'] as const; + +/** Action API parameters for wbgetentities (claims only, so the payload stays small). */ +export function wikidataEntityParams(qids: readonly string[]): Record { + if (qids.length < 1 || qids.length > 50) throw new RangeError('wbgetentities takes 1 to 50 ids'); + return { action: 'wbgetentities', ids: [...qids].sort().join('|'), props: 'claims', format: 'json', formatversion: '2' }; +} + +/** Action API parameters for class labels (English). */ +export function wikidataLabelParams(qids: readonly string[]): Record { + if (qids.length < 1 || qids.length > 50) throw new RangeError('wbgetentities takes 1 to 50 ids'); + return { action: 'wbgetentities', ids: [...qids].sort().join('|'), props: 'labels', languages: 'en', format: 'json', formatversion: '2' }; +} + +/** The slice of a wbgetentities entity this module reads. Unknown shapes are ignored, never thrown on. */ +export interface WikidataEntity { + id?: string; + claims?: Record; +} + +function claimValues(entity: WikidataEntity | null | undefined, property: string): unknown[] { + const statements = entity?.claims?.[property]; + if (!Array.isArray(statements)) return []; + return statements + .filter(s => s?.rank !== 'deprecated' && s?.mainsnak?.snaktype === 'value') + .map(s => s.mainsnak?.datavalue?.value) + .filter(v => v !== undefined); +} + +function itemIds(entity: WikidataEntity | null | undefined, property: string): string[] { + return claimValues(entity, property) + .map(v => (v && typeof v === 'object' && 'id' in v && typeof (v as { id: unknown }).id === 'string') ? (v as { id: string }).id : null) + .filter((id): id is string => id !== null && /^Q\d+$/.test(id)); +} + +/** Years from Wikidata time values ("+1909-04-29T00:00:00Z", "-0044-03-15T…"). */ +function years(entity: WikidataEntity | null | undefined, property: string): number[] { + return claimValues(entity, property) + .map(v => (v && typeof v === 'object' && 'time' in v) ? String((v as { time: unknown }).time) : '') + .map(t => /^([+-])0*(\d{1,6})-/.exec(t)) + .filter((m): m is RegExpExecArray => m !== null) + .map(m => (m[1] === '-' ? -1 : 1) * Number(m[2])) + .filter(y => y !== 0); +} + +/** Q-ids whose labels the host must look up to classify this entity. */ +export function classIdsOf(entity: WikidataEntity | null | undefined): string[] { + return [...new Set([...itemIds(entity, 'P31'), ...itemIds(entity, 'P279')])].sort(); +} + +export interface ProfileSources { + enrichment: Pick; + /** The card's own wbgetentities entity, or null when it has no item or the fetch is pending. */ + entity?: WikidataEntity | null; + /** English labels for class Q-ids; missing labels are kept as the bare Q-id. */ + labels?: Readonly>; + /** Superclass chain for the P31 classes (P279, up to 4 hops), nearest first, if the host resolved it. */ + superclasses?: readonly WikidataClass[]; + /** ns0 outlinks resolved to pageIds. */ + links?: readonly number[]; +} + +export function profileFromSources(src: ProfileSources): CardProfile { + const { enrichment, entity, labels = {} } = src; + const label = (id: string): WikidataClass => ({ id, label: labels[id] ?? id }); + const countries = [...new Set([...itemIds(entity, 'P17'), ...itemIds(entity, 'P27')])].sort(); + const yrs = [...new Set(['P569', 'P570', 'P571', 'P580', 'P585'].flatMap(p => years(entity, p)))].sort((a, b) => a - b); + const cites = [...new Set(CITE_PROPERTIES.flatMap(p => itemIds(entity, p)))].sort(); + const subclassOf = [...itemIds(entity, 'P279').map(label), ...(src.superclasses ?? [])]; + const profile: CardProfile = { + wikidataId: enrichment.wikidataId, + description: enrichment.description, + categories: [...enrichment.categories], + instanceOf: itemIds(entity, 'P31').map(label), + fetchedRevisionId: enrichment.revisionId, + }; + if (subclassOf.length) profile.subclassOf = subclassOf; + if (countries.length) profile.countries = countries; + if (yrs.length) profile.years = yrs; + if (claimValues(entity, 'P570').length) profile.died = true; + if (cites.length) profile.cites = cites; + if (src.links?.length) profile.links = [...new Set(src.links)].sort((a, b) => a - b); + return profile; +} + +/** A canonical JSON string of a profile, for storing, hashing and logging in the match record. */ +export function canonicalProfile(profile: CardProfile): string { + const sortKeys = (v: unknown): unknown => Array.isArray(v) ? v.map(sortKeys) + : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map(k => [k, sortKeys((v as Record)[k])])) + : v; + return JSON.stringify(sortKeys(profile)); +} diff --git a/tests/duel-cards-profile.test.ts b/tests/duel-cards-profile.test.ts new file mode 100644 index 0000000..9fc274e --- /dev/null +++ b/tests/duel-cards-profile.test.ts @@ -0,0 +1,71 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + canonicalProfile, classIdsOf, profileFromSources, wikidataEntityParams, wikidataLabelParams, type WikidataEntity, +} from '../shared/duel/profile.ts'; +import { classify } from '../shared/duel/classify.ts'; +import { derive } from '../shared/duel/derive.ts'; + +const item = (id: string) => ({ rank: 'normal', mainsnak: { snaktype: 'value', datavalue: { type: 'wikibase-entityid', value: { id } } } }); +const time = (t: string) => ({ rank: 'normal', mainsnak: { snaktype: 'value', datavalue: { type: 'time', value: { time: t } } } }); + +const EWELL: WikidataEntity = { + id: 'Q1351340', + claims: { + P31: [item('Q5')], + P27: [item('Q30')], + P569: [time('+1909-04-29T00:00:00Z')], + P570: [time('+1994-09-12T00:00:00Z')], + P19: [item('Q1018580')], + P106: [item('Q33999')], + P17: [{ rank: 'deprecated', mainsnak: { snaktype: 'value', datavalue: { value: { id: 'Q999' } } } }], + }, +}; +const ENRICH = { description: 'American actor (1909–1994)', wikidataId: 'Q1351340', categories: ['1994 deaths', 'American male actors'], revisionId: 42 }; + +test('profileFromSources reads P31, countries, years, death and cited items; ignores deprecated claims', () => { + const p = profileFromSources({ enrichment: ENRICH, entity: EWELL, labels: { Q5: 'human' }, links: [9, 3, 9] }); + assert.deepEqual(p, { + wikidataId: 'Q1351340', description: 'American actor (1909–1994)', categories: ['1994 deaths', 'American male actors'], + instanceOf: [{ id: 'Q5', label: 'human' }], fetchedRevisionId: 42, + countries: ['Q30'], years: [1909, 1994], died: true, cites: ['Q1018580', 'Q30'], links: [3, 9], + }); + assert.equal(classify(p).type, 'Figure'); +}); + +test('BCE years are negative; malformed and novalue claims are skipped without throwing', () => { + const entity: WikidataEntity = { claims: { + P571: [time('-0753-04-21T00:00:00Z'), { mainsnak: { snaktype: 'novalue' } }, { mainsnak: { snaktype: 'value', datavalue: { value: 'junk' } } }], + P31: [item('not-a-qid'), item('Q515')], + } }; + const p = profileFromSources({ enrichment: { ...ENRICH, categories: [] }, entity }); + assert.deepEqual(p.years, [-753]); + assert.deepEqual(p.instanceOf, [{ id: 'Q515', label: 'Q515' }]); + assert.equal(classify(p).type, 'Location', 'Q-id anchors classify even without labels'); + assert.equal(profileFromSources({ enrichment: ENRICH, entity: null }).instanceOf.length, 0); +}); + +test('without a Wikidata item the profile still classifies from categories and description', () => { + const p = profileFromSources({ enrichment: { description: 'Village in Poland', wikidataId: null, categories: ['Villages in Gmina X'], revisionId: 1 } }); + assert.equal(classify(p).type, 'Location'); +}); + +test('request parameters: claims-only entities, English labels, ≤ 50 sorted ids', () => { + assert.deepEqual(wikidataEntityParams(['Q5', 'Q1']), { action: 'wbgetentities', ids: 'Q1|Q5', props: 'claims', format: 'json', formatversion: '2' }); + assert.equal(wikidataLabelParams(['Q5']).props, 'labels'); + assert.throws(() => wikidataEntityParams([]), RangeError); + assert.throws(() => wikidataLabelParams(Array.from({ length: 51 }, (_, i) => `Q${i + 1}`)), RangeError); + assert.deepEqual(classIdsOf({ claims: { P31: [item('Q5')], P279: [item('Q2'), item('Q5')] } }), ['Q2', 'Q5']); +}); + +test('canonicalProfile is key-order independent, and the frozen profile derives the same card twice', () => { + const p = profileFromSources({ enrichment: ENRICH, entity: EWELL, labels: { Q5: 'human' } }); + const shuffled = Object.fromEntries(Object.entries(p).reverse()) as typeof p; + assert.equal(canonicalProfile(shuffled), canonicalProfile(p)); + const chain = { tokenId: 'ab'.repeat(32), article: { pageId: 1, title: 'Tom Ewell', extract: 'Tom Ewell was an American actor. More.', revisionId: 42 }, + statsSnapshot: { pageBytes: 9000, languageCount: 30, stats: { attention: 60, depth: 70, reach: 50 } } }; + const thawed = JSON.parse(canonicalProfile(p)); + assert.deepEqual(derive(chain, thawed), derive(chain, p)); + assert.equal(derive(chain, p).flavor, 'Tom Ewell was an American actor.'); + assert.ok(derive(chain, p).keywords.includes('Legacy')); +});