forked from WikiDeck/wikideck
[duel-cards] profile.ts: build the frozen CardProfile from enrichment + wbgetentities (pure, no fetch)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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<string, string> {
|
||||
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<string, string> {
|
||||
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<string, readonly {
|
||||
rank?: string;
|
||||
mainsnak?: { snaktype?: string; datavalue?: { type?: string; value?: unknown } };
|
||||
}[]>;
|
||||
}
|
||||
|
||||
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<PageEnrichment, 'description' | 'wikidataId' | 'categories' | 'revisionId'>;
|
||||
/** 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<Record<string, string>>;
|
||||
/** 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<string, unknown>)[k])]))
|
||||
: v;
|
||||
return JSON.stringify(sortKeys(profile));
|
||||
}
|
||||
@@ -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'));
|
||||
});
|
||||
Reference in New Issue
Block a user