import { createReadStream } from 'node:fs' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' import { isUniversalRow, type UniversalRow } from '@sf/contracts' import { parseWxrStream, type WxrItem } from '../src/parse/wxr-stream.js' import { DEFAULT_TYPE_ROUTES, mapItem, META_KEYS, STATUS_MAP, UNKNOWN_STATUS, type MapConfig, type MappedResult, } from '../src/map/item-to-row.js' // mini.xml(Plan 1 夹具):5 item(post 101 / product 111 / page 121 / attachment 201,202) // + 2 term;product 的图库 203/204 有意悬空(夹具中不存在对应 attachment item)。 const FIXTURE = fileURLToPath(new URL('../../../tests/fixtures/wxr/mini.xml', import.meta.url)) const CONFIG: MapConfig = { locale: 'zh-CN' } /** 经 parseWxrStream 喂 mini.xml 取真实 item 事件(端到端:解析产物即映射输入) */ async function miniItems(): Promise { const out: WxrItem[] = [] for await (const ev of parseWxrStream(createReadStream(FIXTURE))) { if (ev.kind === 'item') out.push(ev.item) } return out } function byPostId(items: WxrItem[], postId: number): WxrItem { const found = items.find((it) => it.postId === postId) if (found === undefined) throw new Error(`mini.xml 中找不到 post ${postId}`) return found } /** 手构等值 WxrItem(任务说明允许:wxr-stream 完整字段形状,缺省为最平凡合法值) */ function makeItem(overrides: Partial = {}): WxrItem { return { rawLocation: 'wxr://item/handmade', postId: 1, postType: 'post', status: 'publish', postName: 'handmade', link: 'https://example.com/handmade.html', title: 'Handmade', contentEncoded: '

handmade body

', excerptEncoded: '', postDate: '2026-01-01 00:00:00', postModified: '2026-01-02 00:00:00', attachmentUrl: '', creator: 'admin', metas: [], categories: [], ...overrides, } } /** 断言结果为 row 并取出( narrowing 辅助;非 row 即失败) */ function rowOf(result: MappedResult): { row: UniversalRow; issues: string[] } { if (result.kind !== 'row') throw new Error(`期望 kind:'row',实际 ${result.kind}`) return { row: result.row, issues: result.issues } } /** Plan 1 移交 property 断言:产出 row 的通用不变量(守卫 + 非空 + refs 形状) */ function expectRowInvariants(row: UniversalRow): void { expect(isUniversalRow(row)).toBe(true) expect(row.sourceType).not.toBe('') expect(row.sourceId).not.toBe('') expect(row.rawLocation).not.toBe('') for (const ref of row.taxonomyRefs) { expect(ref.taxonomy).not.toBe('') expect(ref.sourceTermId).not.toBe('') } for (const ref of row.attachmentRefs) { expect(ref.role).not.toBe('') // 本映射器产出的 ref 一律以 sourceId 锚定(不产 sourceUrl 型 ref) expect(typeof ref.sourceId === 'string' && ref.sourceId !== '').toBe(true) } } /** extras 为 null 原型字典(原型污染防御,审查 Fix 4):展开为普通对象再作整体等值比较 */ function plain(extras: Record): Record { return { ...extras } } describe('mapItem:mini.xml 端到端(parseWxrStream → mapItem)', () => { it('post(101):全字段映射(路由/status/locale/slug/seo/taxonomyRefs/featured/knownFields/bodyHtml 原文)', async () => { const { row, issues } = rowOf(mapItem(byPostId(await miniItems(), 101), CONFIG)) expect(issues).toStrictEqual([]) expect(row).toMatchObject({ sourceType: 'wp:post', sourceId: '101', status: 'publish', locale: 'zh-CN', sourceUrl: 'https://fixture.example/news/fixture-news-a.html', slug: 'fixture-news-a', // 原文透传(清洗是 Task 5 的职责) bodyHtml: '

Body with link and

', rawLocation: 'wxr://item/1', }) // 设计决定(JSDoc 钉死):sourceTermId 暂以 category @nicename 为锚 // (= 真实 WP 的 term slug;mini.xml 中 term 31 的 slug 恰为 'company',Task 8 实数据核对后冻结) expect(row.taxonomyRefs).toStrictEqual([{ taxonomy: 'category', sourceTermId: 'company' }]) expect(row.attachmentRefs).toStrictEqual([{ role: 'featured', sourceId: '201' }]) expect(row.seo).toStrictEqual({ title: 'Fixture SEO Title A', description: 'Fixture SEO description A.', }) // 阶段 3 提升纪律:title/日期暂留 knownFields(键名冻结为 title/postDate/postModified) expect(row.knownFields).toStrictEqual({ title: 'Fixture News A', postDate: '2026-10-05 09:00:00', postModified: '2026-10-06 10:00:00', excerpt: 'Fixture excerpt A', creator: 'editor', }) // 101 的 3 条 meta 全部被分流(thumbnail/yoast×2)——extras 无未识别残余 expect(plain(row.extras)).toStrictEqual({}) expectRowInvariants(row) }) it('product(111):featured 202 + 悬空 gallery 203/204 原样保留(歧义不猜);extras.wppop_sections 为解析产物', async () => { const { row, issues } = rowOf(mapItem(byPostId(await miniItems(), 111), CONFIG)) expect(issues).toStrictEqual([]) expect(row.sourceType).toBe('wp:product') expect(row.sourceId).toBe('111') // 悬空 203/204 原样保留:是否存在对应媒体是入库阶段以全量数据才能裁决的事 expect(row.attachmentRefs).toStrictEqual([ { role: 'featured', sourceId: '202' }, { role: 'gallery', sourceId: '203' }, { role: 'gallery', sourceId: '204' }, ]) // Map 陷阱防线:必须是 phpValueToJson 后的普通对象(可 JSON.stringify,非 Map) expect(row.extras.wppop_sections).not.toBeInstanceOf(Map) expect(row.extras.wppop_sections).toStrictEqual([{ title: 'SpecsTab', content: '

Tab

' }]) expect(JSON.stringify(row.extras.wppop_sections)).toBe('[{"title":"SpecsTab","content":"

Tab

"}]') expectRowInvariants(row) }) it('page(121):sourceType wp:page,seo/refs 为空', async () => { const { row } = rowOf(mapItem(byPostId(await miniItems(), 121), CONFIG)) expect(row.sourceType).toBe('wp:page') expect(row.sourceId).toBe('121') expect(row.taxonomyRefs).toStrictEqual([]) expect(row.attachmentRefs).toStrictEqual([]) expect(row.seo).toStrictEqual({}) expectRowInvariants(row) }) it('attachment(201):sourceType wp:attachment、status inherit 原样、knownFields.attachmentUrl', async () => { const { row, issues } = rowOf(mapItem(byPostId(await miniItems(), 201), CONFIG)) expect(issues).toStrictEqual([]) expect(row.sourceType).toBe('wp:attachment') expect(row.sourceId).toBe('201') expect(row.status).toBe('inherit') expect(row.knownFields.attachmentUrl).toBe( 'https://fixture.example/wp-content/uploads/2026/10/fixture-a.png', ) expectRowInvariants(row) }) it('property 断言(Plan 1 移交):mini.xml 全部 5 item 均产合法 row(含 attachment 202)', async () => { const items = await miniItems() expect(items).toHaveLength(5) for (const item of items) { const { row } = rowOf(mapItem(item, CONFIG)) expectRowInvariants(row) } }) }) describe('mapItem:unsupported 分流(不产 row)', () => { it.each(['nav_menu_item', 'wpcf7_contact_form', 'elementor_library', 'wp_navigation'])( 'post_type %s → {kind:unsupported, sourceType:wp:%s},不产 row', (postType) => { const result = mapItem(makeItem({ postType }), CONFIG) expect(result).toStrictEqual({ kind: 'unsupported', sourceType: `wp:${postType}`, reason: 'post_type 未配置映射', rawLocation: 'wxr://item/handmade', }) expect('row' in result).toBe(false) }, ) it('typeRoutes 自定义:整体替换语义(post 走自定义路由;product 无路由 → unsupported)', () => { const custom: MapConfig = { locale: 'zh-CN', typeRoutes: { post: 'site:article' } } const post = rowOf(mapItem(makeItem({ postType: 'post' }), custom)) expect(post.row.sourceType).toBe('site:article') expect(mapItem(makeItem({ postType: 'product' }), custom).kind).toBe('unsupported') }) }) describe('mapItem:status 值域映射(Plan 1 移交,表驱动)', () => { it.each(['publish', 'draft', 'future', 'pending', 'private', 'trash', 'inherit'])( '已知 status %s → 原样', (status) => { const { row, issues } = rowOf(mapItem(makeItem({ status }), CONFIG)) expect(row.status).toBe(status) expect(issues).toStrictEqual([]) }, ) it("未知 status('weird'/空串)→ 'unknown' + issue(不猜不丢)", () => { const weird = rowOf(mapItem(makeItem({ status: 'weird' }), CONFIG)) expect(weird.row.status).toBe('unknown') expect(weird.issues).toStrictEqual([`status 值未识别:"weird",已映射为 'unknown'`]) const empty = rowOf(mapItem(makeItem({ status: '' }), CONFIG)) expect(empty.row.status).toBe('unknown') expect(empty.issues).toHaveLength(1) }) it('STATUS_MAP/DEFAULT_TYPE_ROUTES/META_KEYS 冻结且值域钉死', () => { expect(Object.isFrozen(STATUS_MAP)).toBe(true) expect(Object.isFrozen(DEFAULT_TYPE_ROUTES)).toBe(true) expect(Object.isFrozen(META_KEYS)).toBe(true) expect(STATUS_MAP).toStrictEqual({ publish: 'publish', draft: 'draft', future: 'future', pending: 'pending', private: 'private', trash: 'trash', inherit: 'inherit', }) expect(UNKNOWN_STATUS).toBe('unknown') expect(DEFAULT_TYPE_ROUTES).toStrictEqual({ post: 'wp:post', page: 'wp:page', product: 'wp:product', attachment: 'wp:attachment', }) expect(META_KEYS).toStrictEqual({ thumbnail: '_thumbnail_id', gallery: '_product_image_gallery', seoTitle: '_yoast_wpseo_title', seoDescription: '_yoast_wpseo_metadesc', wppopSections: 'wppop_sections', }) }) }) describe('mapItem:postId 异常策略(Task 3 审查移交)', () => { it('postId null → {kind:error}(不产 row 不猜)', () => { expect(mapItem(makeItem({ postId: null }), CONFIG)).toStrictEqual({ kind: 'error', issue: 'post_id 缺失或非法', rawLocation: 'wxr://item/handmade', }) }) it("postId -7(wxr-stream 严格解析 '-7' 的产物)→ sourceId '-7' 原样", () => { const { row } = rowOf(mapItem(makeItem({ postId: -7 }), CONFIG)) expect(row.sourceId).toBe('-7') }) it("postId -0 / 0 → sourceId '0'(-0 归一,String(-0)==='0')", () => { const item = makeItem({ postId: -0 }) expect(Object.is(item.postId, -0)).toBe(true) // 确证喂入的确实是 -0(未被字面量归一) expect(rowOf(mapItem(item, CONFIG)).row.sourceId).toBe('0') expect(rowOf(mapItem(makeItem({ postId: 0 }), CONFIG)).row.sourceId).toBe('0') }) it('post_id 缺失的 unsupported 类型:data 有效性先行于路由(error 而非 unsupported)', () => { const result = mapItem(makeItem({ postId: null, postType: 'nav_menu_item' }), CONFIG) expect(result.kind).toBe('error') }) }) describe('mapItem:meta 分流表', () => { it('未识别 meta → extras 原样(字符串键值;同 key 后者覆盖前者)', () => { const { row, issues } = rowOf( mapItem( makeItem({ metas: [ { key: 'custom_a', value: 'va' }, { key: '_thumbnail_id', value: '301' }, { key: 'custom_a', value: 'va-2' }, { key: 'custom_b', value: 'vb' }, ], }), CONFIG, ), ) expect(issues).toStrictEqual([]) expect(plain(row.extras)).toStrictEqual({ custom_a: 'va-2', custom_b: 'vb' }) expect(row.attachmentRefs).toStrictEqual([{ role: 'featured', sourceId: '301' }]) }) it('thumbnail/gallery 容忍空白(trim);空 gallery 值不产 ref;空 thumbnail 记 issue', () => { const ok = rowOf( mapItem( makeItem({ metas: [ { key: '_thumbnail_id', value: ' 401 ' }, { key: '_product_image_gallery', value: '402 , 403' }, ], }), CONFIG, ), ) expect(ok.row.attachmentRefs).toStrictEqual([ { role: 'featured', sourceId: '401' }, { role: 'gallery', sourceId: '402' }, { role: 'gallery', sourceId: '403' }, ]) // WooCommerce 语义:空 _product_image_gallery = 无图库(不报 issue);空 _thumbnail_id 为畸形(记 issue) const emptyGallery = rowOf( mapItem(makeItem({ metas: [{ key: '_product_image_gallery', value: '' }] }), CONFIG), ) expect(emptyGallery.row.attachmentRefs).toStrictEqual([]) expect(emptyGallery.issues).toStrictEqual([]) const emptyThumb = rowOf( mapItem(makeItem({ metas: [{ key: '_thumbnail_id', value: ' ' }] }), CONFIG), ) expect(emptyThumb.row.attachmentRefs).toStrictEqual([]) expect(emptyThumb.issues).toStrictEqual(['meta _thumbnail_id 值为空,featured 引用已跳过']) }) it('wppop 解析失败路径:extras.phpRaw 存原串 + issue(不崩不丢,row 照常产出)', () => { const raw = 'a:1:{i:0;s:5:"ab' // 截断串 → PhpParseError const { row, issues } = rowOf( mapItem(makeItem({ metas: [{ key: 'wppop_sections', value: raw }] }), CONFIG), ) expect(row.extras.phpRaw).toBe(raw) expect(row.extras.wppop_sections).toBeUndefined() expect(issues).toHaveLength(1) expect(issues[0]).toContain('wppop_sections') expect(issues[0]).toContain('phpRaw') expectRowInvariants(row) }) }) describe('mapItem:category 引用形状防线', () => { it('category 缺 domain 或 nicename → 跳过该 ref 并记 issue(不产空锚点)', () => { const { row, issues } = rowOf( mapItem( makeItem({ categories: [ { domain: 'category', nicename: '', value: 'X' }, { domain: '', nicename: 'slug', value: 'Y' }, { domain: 'post_tag', nicename: 'tag-a', value: 'TagA' }, ], }), CONFIG, ), ) expect(row.taxonomyRefs).toStrictEqual([{ taxonomy: 'post_tag', sourceTermId: 'tag-a' }]) expect(issues).toHaveLength(2) expectRowInvariants(row) }) }) describe('mapItem:原型键防御(审查 Fix 1——裸索引会命中继承属性)', () => { it("postType 'constructor'(继承键,值为函数非路由)→ unsupported,不被当合法路由命中", () => { const result = mapItem(makeItem({ postType: 'constructor' }), CONFIG) expect(result).toStrictEqual({ kind: 'unsupported', sourceType: 'wp:constructor', reason: 'post_type 未配置映射', rawLocation: 'wxr://item/handmade', }) }) it("status 'valueOf'(继承键,值为函数非字符串)→ 'unknown' + issue", () => { const { row, issues } = rowOf(mapItem(makeItem({ status: 'valueOf' }), CONFIG)) expect(row.status).toBe('unknown') expect(issues).toStrictEqual([`status 值未识别:"valueOf",已映射为 'unknown'`]) }) it("typeRoutes 自定义表同样守卫:'toString' 键未被显式配置 → unsupported", () => { const custom: MapConfig = { locale: 'zh-CN', typeRoutes: { post: 'wp:post' } } expect(mapItem(makeItem({ postType: 'toString' }), custom).kind).toBe('unsupported') }) }) describe('mapItem:meta 冲突策略三方统一(审查 Fix 3)', () => { it('单值键重复(thumbnail/seoTitle/seoDescription)→ 先者胜出 + issue(WP 单值语义)', () => { const { row, issues } = rowOf( mapItem( makeItem({ metas: [ { key: '_thumbnail_id', value: '501' }, { key: '_thumbnail_id', value: '502' }, { key: '_yoast_wpseo_title', value: 'T1' }, { key: '_yoast_wpseo_title', value: 'T2' }, { key: '_yoast_wpseo_metadesc', value: 'D1' }, { key: '_yoast_wpseo_metadesc', value: 'D2' }, ], }), CONFIG, ), ) expect(row.attachmentRefs).toStrictEqual([{ role: 'featured', sourceId: '501' }]) expect(row.seo).toStrictEqual({ title: 'T1', description: 'D1' }) expect(issues).toStrictEqual([ 'meta _thumbnail_id 重复,取先者', 'meta _yoast_wpseo_title 重复,取先者', 'meta _yoast_wpseo_metadesc 重复,取先者', ]) }) it('首个单值键即便值非法也占位:后续同键值不顶替(重复即异常,显式报告不猜)', () => { const { row, issues } = rowOf( mapItem( makeItem({ metas: [ { key: '_thumbnail_id', value: '' }, { key: '_thumbnail_id', value: '503' }, ], }), CONFIG, ), ) expect(row.attachmentRefs).toStrictEqual([]) expect(issues).toStrictEqual([ 'meta _thumbnail_id 值为空,featured 引用已跳过', 'meta _thumbnail_id 重复,取先者', ]) }) it('wppop 先败后成:extras.phpRaw 被清除、终态为成功产物(issues 留痕不回滚)', () => { const { row, issues } = rowOf( mapItem( makeItem({ metas: [ { key: 'wppop_sections', value: 'a:1:{i:0;s:5:"ab' }, // 截断 → 失败 { key: 'wppop_sections', value: 'a:1:{i:0;s:3:"foo";}' }, // 成功 ], }), CONFIG, ), ) expect(Object.hasOwn(row.extras, 'phpRaw')).toBe(false) expect(row.extras.wppop_sections).toStrictEqual(['foo']) expect(issues).toHaveLength(1) // 首次失败仍在 issue 日志中 }) it('wppop 先成后败:对称清理——终态 phpRaw、无 wppop_sections 残留', () => { const bad = 'a:1:{i:0;s:5:"ab' const { row } = rowOf( mapItem( makeItem({ metas: [ { key: 'wppop_sections', value: 'a:1:{i:0;s:3:"foo";}' }, { key: 'wppop_sections', value: bad }, ], }), CONFIG, ), ) expect(Object.hasOwn(row.extras, 'wppop_sections')).toBe(false) expect(row.extras.phpRaw).toBe(bad) }) it('gallery 累积语义:两段 gallery meta 的引用按文档序并入(不属单值冲突策略)', () => { const { row, issues } = rowOf( mapItem( makeItem({ metas: [ { key: '_product_image_gallery', value: '601' }, { key: '_product_image_gallery', value: '602,603' }, ], }), CONFIG, ), ) expect(row.attachmentRefs).toStrictEqual([ { role: 'gallery', sourceId: '601' }, { role: 'gallery', sourceId: '602' }, { role: 'gallery', sourceId: '603' }, ]) expect(issues).toStrictEqual([]) }) }) describe('mapItem:原型污染防御(审查 Fix 4)', () => { it("meta key '__proto__' 不静默丢失:extras 保留为自有可枚举键(null 原型字典)", () => { const { row, issues } = rowOf( mapItem(makeItem({ metas: [{ key: '__proto__', value: 'proto-v' }] }), CONFIG), ) expect(issues).toStrictEqual([]) expect(Object.hasOwn(row.extras, '__proto__')).toBe(true) expect(row.extras['__proto__']).toBe('proto-v') expect(JSON.stringify(row.extras)).toContain('"__proto__":"proto-v"') expectRowInvariants(row) // 守卫(含 seo/knownFields/extras 对象形状检查)仍通过 }) }) describe('mapItem:config 校验(审查 Fix 5)', () => { it('typeRoutes 含空字符串路由值 → TypeError(程序员错误,fail fast)', () => { expect(() => mapItem(makeItem(), { locale: 'zh-CN', typeRoutes: { post: '' } })).toThrow(TypeError) expect(() => mapItem(makeItem(), { locale: 'zh-CN', typeRoutes: { post: 'wp:post', page: '' } }), ).toThrow(/typeRoutes/) }) it('非空路由值不误伤:合法自定义表正常产出', () => { expect(() => rowOf(mapItem(makeItem(), { locale: 'zh-CN', typeRoutes: { post: 'wp:post' } })), ).not.toThrow() }) })