An AI-powered search engine with a generative UI
TypeScript generative-aigenerative-uinextjsollamareactsearxngshadcn-uitailwindcsstavilytypescriptupstashvercel-ai-sdk
import { describe, expect, it } from 'vitest'
import type { SearchResultItem } from '@/lib/types'
import type { UIMessage } from '@/lib/types/ai'
import {
extractCitationMaps,
extractCitationMapsFromMessages,
isCitationLabel,
isDerivedLabel,
nextCitationLabelNumber,
processCitations
} from '../citation'
function labelledAssistantMessage({
id,
toolCallId,
labels,
urls
}: {
id: string
toolCallId: string
labels: string[]
urls: string[]
}): UIMessage {
return {
id,
role: 'assistant',
parts: [
{
type: 'tool-search',
state: 'output-available',
toolCallId,
input: { query: id },
output: {
query: id,
images: [],
results: labels.map((label, index) => ({
label,
title: `${id} source ${index + 1}`,
url: urls[index],
content: `${id} evidence ${index + 1}`
}))
}
},
{ type: 'text', text: labels.map(label => `[1](#${label})`).join(' ') }
]
} as unknown as UIMessage
}
function labelledFetchMessage({
id,
label,
url
}: {
id: string
label: string
url: string
}): UIMessage {
return {
id,
role: 'assistant',
parts: [
{
type: 'tool-fetch',
state: 'output-available',
toolCallId: `fetch-${id}`,
input: { url },
output: {
query: '',
images: [],
results: [{ label, title: id, url, content: `${id} evidence` }]
}
}
]
} as unknown as UIMessage
}
describe('processCitations', () => {
const mockCitationMaps = {
toolCall1: {
1: {
title: 'Google',
url: 'https://www.google.com',
content: 'Search engine'
},
2: {
title: 'GitHub',
url: 'https://docs.github.com',
content: 'Developer platform'
},
3: {
title: 'Stack Overflow',
url: 'https://stackoverflow.com/questions/123',
content: 'Q&A for developers'
}
} as Record<number, SearchResultItem>
}
const labelledCitationMaps = {
S37: {
1: {
title: 'Malformed close source',
url: 'https://example.com/malformed',
content: 'Malformed close evidence'
}
} as Record<number, SearchResultItem>,
S5: {
1: {
title: 'Later source',
url: 'https://example.com/later',
content: 'Later evidence'
}
} as Record<number, SearchResultItem>
}
it('converts numbered citations to domain names', () => {
const content = 'Check out [1](#toolCall1) and [2](#toolCall1)'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe(
'Check out [google](https://www.google.com) and [github](https://docs.github.com)'
)
})
it('does not consume text or a later citation after a malformed close', () => {
const content =
'Alpha is true. [1](#S37] Beta is a whole sentence that should survive. Gamma cites correctly. [1](#S5)'
expect(processCitations(content, labelledCitationMaps)).toBe(
'Alpha is true. [example](https://example.com/malformed) Beta is a whole sentence that should survive. Gamma cites correctly. [example](https://example.com/later)'
)
})
it('does not let a malformed close swallow the next citation opener', () => {
const content = 'Alpha. [1](#missing[1](#S5) tail.'
expect(processCitations(content, labelledCitationMaps)).toBe(
'Alpha. [1](#missing[example](https://example.com/later) tail.'
)
})
it('resolves a malformed close to the same source as a normal close', () => {
expect(processCitations('[1](#S37]', labelledCitationMaps)).toBe(
processCitations('[1](#S37)', labelledCitationMaps)
)
})
it('keeps well-formed citation resolution unchanged', () => {
expect(processCitations('[1](#toolCall1)', mockCitationMaps)).toBe(
'[google](https://www.google.com)'
)
})
it('drops an unresolvable id without consuming neighbouring text', () => {
const content =
'Before [1](#missing] middle survives. After [1](#toolCall1)'
expect(processCitations(content, mockCitationMaps)).toBe(
'Before middle survives. After [google](https://www.google.com)'
)
})
it('handles citations with spaces', () => {
const content = 'See [ 1 ](#toolCall1) for details'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe('See [google](https://www.google.com) for details')
})
it('handles multiple citations from same domain', () => {
const citationMaps = {
toolCall1: {
1: {
title: 'Google Search',
url: 'https://www.google.com/search',
content: 'Search'
},
2: {
title: 'Google Maps',
url: 'https://www.google.com/maps',
content: 'Maps'
}
} as Record<number, SearchResultItem>
}
const content = 'Try [1](#toolCall1) or [2](#toolCall1)'
const result = processCitations(content, citationMaps)
expect(result).toBe(
'Try [google](https://www.google.com/search) or [google](https://www.google.com/maps)'
)
})
it('converts citations with dotted display labels', () => {
const citationMaps = {
toolCall1: {
1: {
title: 'Global News',
url: 'https://topics.global.example.com/portal/news/page.html',
content: 'News article'
},
2: {
title: 'World Report',
url: 'https://articles.world.example.net/articles/-/123',
content: 'News article'
}
} as Record<number, SearchResultItem>
}
const content = 'Sources [1](#toolCall1) [2](#toolCall1)'
const result = processCitations(content, citationMaps)
expect(result).toBe(
'Sources [global.example](https://topics.global.example.com/portal/news/page.html) [world.example](https://articles.world.example.net/articles/-/123)'
)
})
it('returns empty string for invalid citation numbers', () => {
const content = 'Invalid [999](#toolCall1) citation'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe('Invalid citation')
})
it('returns empty string for missing toolCallId', () => {
const content = 'Missing [1](#nonExistentTool) tool'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe('Missing tool')
})
it('returns empty string for invalid URLs', () => {
const citationMaps = {
toolCall1: {
1: {
title: 'Invalid',
url: 'not-a-valid-url',
content: 'Invalid URL'
}
} as Record<number, SearchResultItem>
}
const content = 'Check [1](#toolCall1) here'
const result = processCitations(content, citationMaps)
expect(result).toBe('Check here')
})
it('resolves citations where the model prepended a toolu_ prefix', () => {
// Models sometimes cite [1](#toolu_<id>) even though the search tool's
// call id has no prefix. The cited id should still resolve to the result.
const content = 'See [1](#toolu_toolCall1) and [2](#toolu_toolCall1)'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe(
'See [google](https://www.google.com) and [github](https://docs.github.com)'
)
})
it.each(['toolu_', 'call_', 'search-'])(
'normalizes the %s prefix for legacy citations',
prefix => {
const result = processCitations(
`[1](#${prefix}toolCall1)`,
mockCitationMaps
)
expect(result).toBe('[google](https://www.google.com)')
}
)
it('still prefers an exact toolCallId match over a normalized one', () => {
const content = 'See [1](#toolCall1)'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe('See [google](https://www.google.com)')
})
it('handles content with no citations', () => {
const content = 'This is plain text without citations'
const result = processCitations(content, mockCitationMaps)
expect(result).toBe('This is plain text without citations')
})
it('returns empty string for null/undefined content', () => {
expect(processCitations('', mockCitationMaps)).toBe('')
expect(processCitations(null as any, mockCitationMaps)).toBe('')
})
it('handles empty citation maps', () => {
const content = 'Text with [1](#toolCall1) citation'
const result = processCitations(content, {})
// When citation maps are empty, content is returned unchanged
expect(result).toBe('Text with [1](#toolCall1) citation')
})
it('encodes URLs to prevent injection', () => {
const citationMaps = {
toolCall1: {
1: {
title: 'Test',
url: 'https://example.com/page?param=value&other=test',
content: 'Test'
}
} as Record<number, SearchResultItem>
}
const content = 'See [1](#toolCall1)'
const result = processCitations(content, citationMaps)
expect(result).toContain('example')
expect(result).toContain('https://example.com/page?param=value&other=test')
})
it('handles complex real-world scenarios', () => {
const content = `According to [1](#toolCall1), the answer is 42.
However, [2](#toolCall1) suggests otherwise.
For more information, see [3](#toolCall1).`
const result = processCitations(content, mockCitationMaps)
expect(result).toContain('[google](https://www.google.com)')
expect(result).toContain('[github](https://docs.github.com)')
expect(result).toContain(
'[stackoverflow](https://stackoverflow.com/questions/123)'
)
})
it('handles citation numbers at edge cases', () => {
const content =
'Edge cases: [0](#toolCall1) [101](#toolCall1) [-1](#toolCall1)'
const result = processCitations(content, mockCitationMaps)
// 0 and 101 are out of bounds (1-100), so they're replaced with empty string
// -1 doesn't match the regex pattern \d+, so it remains unchanged
expect(result).toBe('Edge cases: [-1](#toolCall1)')
})
describe('extractCitationMaps', () => {
const results = [
{ title: 'Google', url: 'https://www.google.com', content: 'a' },
{ title: 'GitHub', url: 'https://docs.github.com', content: 'b' }
]
function messageWithSearchPart(output: unknown): UIMessage {
return {
id: 'm1',
role: 'assistant',
parts: [
{
type: 'tool-search',
state: 'output-available',
toolCallId: 'toolCall1',
output
}
]
} as unknown as UIMessage
}
it('derives the citation map from results when citationMap is absent', () => {
const maps = extractCitationMaps(
messageWithSearchPart({ results, images: [], query: 'q' })
)
expect(maps.toolCall1[1]).toEqual(results[0])
expect(maps.toolCall1[2]).toEqual(results[1])
})
it('prefers an existing citationMap (older persisted messages)', () => {
const legacy = {
1: { title: 'Legacy', url: 'https://legacy.example.com', content: 'c' }
}
const maps = extractCitationMaps(
messageWithSearchPart({ results, citationMap: legacy })
)
expect(maps.toolCall1).toBe(legacy)
})
it('omits tool calls with no results and no citationMap', () => {
const maps = extractCitationMaps(
messageWithSearchPart({ results: [], images: [], query: 'q' })
)
expect(maps).toEqual({})
})
it('produces a map that processCitations can resolve', () => {
const maps = extractCitationMaps(
messageWithSearchPart({ results, images: [], query: 'q' })
)
const result = processCitations('See [1](#toolCall1)', maps)
expect(result).toBe('See [google](https://www.google.com)')
})
it('adds one-result maps for valid persisted labels', () => {
const labelledResults = [
{ ...results[0], label: 'S3' },
{ ...results[1], label: 'invalid' }
]
const maps = extractCitationMaps(
messageWithSearchPart({ results: labelledResults })
)
expect(maps.S3).toEqual({ 1: labelledResults[0] })
expect(maps).not.toHaveProperty('invalid')
expect(maps.toolCall1[2]).toEqual(labelledResults[1])
})
it('maps fetch labels without adding a tool-call map', () => {
const message = labelledFetchMessage({
id: 'fetched',
label: 'S3',
url: 'https://fetched.test/source'
})
const maps = extractCitationMaps(message)
expect(maps).not.toHaveProperty('fetch-fetched')
expect(processCitations('[1](#S3)', maps)).toBe(
'[fetched](https://fetched.test/source)'
)
})
})
describe('derived citation labels', () => {
it('resolves each labelled turn through the combined conversation map', () => {
const turnOne = labelledAssistantMessage({
id: 'turn-one',
toolCallId: 'call_one',
labels: ['S1', 'S2'],
urls: ['https://turn-one.test/1', 'https://turn-one.test/2']
})
const turnTwo = labelledAssistantMessage({
id: 'turn-two',
toolCallId: 'call_two',
labels: ['S3', 'S4'],
urls: ['https://turn-two.test/1', 'https://turn-two.test/2']
})
const maps = extractCitationMapsFromMessages([turnOne, turnTwo])
expect(processCitations('[1](#S1) [1](#S2)', maps)).toBe(
'[turn-one](https://turn-one.test/1) [turn-one](https://turn-one.test/2)'
)
expect(processCitations('[1](#S3) [1](#S4)', maps)).toBe(
'[turn-two](https://turn-two.test/1) [turn-two](https://turn-two.test/2)'
)
expect(processCitations('[2](#S1)', maps)).toBe(
'[turn-one](https://turn-one.test/1)'
)
})
it('keeps the first turn addressable when the next seed follows history', () => {
const turnOne = labelledAssistantMessage({
id: 'turn-one',
toolCallId: 'call_one',
labels: ['S1', 'S2'],
urls: ['https://first.test/source', 'https://first.test/other']
})
const secondSeed = nextCitationLabelNumber([turnOne])
const turnTwo = labelledAssistantMessage({
id: 'turn-two',
toolCallId: 'call_two',
labels: [`S${secondSeed}`],
urls: ['https://second.test/source']
})
const maps = extractCitationMapsFromMessages([turnOne, turnTwo])
expect(secondSeed).toBe(3)
expect(processCitations('[1](#S1)', maps)).toBe(
'[first](https://first.test/source)'
)
})
it('starts at one without labels and advances past the largest valid label', () => {
expect(nextCitationLabelNumber([])).toBe(1)
const legacyMessage = labelledAssistantMessage({
id: 'legacy-shaped',
toolCallId: 'call_legacy',
labels: ['not-a-derived-label'],
urls: ['https://example.test/legacy']
})
expect(nextCitationLabelNumber([legacyMessage])).toBe(1)
const message = labelledAssistantMessage({
id: 'history',
toolCallId: 'call_history',
labels: ['S2', 'bad', 'S12', 'S3x'],
urls: [
'https://example.test/2',
'https://example.test/bad',
'https://example.test/12',
'https://example.test/3x'
]
})
expect(nextCitationLabelNumber([message])).toBe(13)
})
it('advances past labels from fetch outputs', () => {
const message = labelledFetchMessage({
id: 'fetch-history',
label: 'S8',
url: 'https://fetched.test/history'
})
expect(nextCitationLabelNumber([message])).toBe(9)
})
it('resolves fetch labels through the combined conversation map', () => {
const message = labelledFetchMessage({
id: 'fetch-turn',
label: 'S3',
url: 'https://fetched.test/combined'
})
const maps = extractCitationMapsFromMessages([message])
expect(processCitations('[1](#S3)', maps)).toBe(
'[fetched](https://fetched.test/combined)'
)
})
it('treats a label shared by search and fetch turns as ambiguous', () => {
const search = labelledAssistantMessage({
id: 'search-turn',
toolCallId: 'search-call',
labels: ['S3'],
urls: ['https://search.test/source']
})
const fetch = labelledFetchMessage({
id: 'fetch-turn',
label: 'S3',
url: 'https://fetch.test/source'
})
const maps = extractCitationMapsFromMessages([search, fetch])
expect(maps).not.toHaveProperty('S3')
expect(processCitations('[1](#S3)', maps)).toBe('')
})
it('refuses to resolve a label two turns both claim', () => {
const first = labelledAssistantMessage({
id: 'concurrent-one',
toolCallId: 'call_one',
labels: ['S1', 'S2'],
urls: ['https://one.test/a', 'https://one.test/b']
})
const second = labelledAssistantMessage({
id: 'concurrent-two',
toolCallId: 'call_two',
labels: ['S2'],
urls: ['https://two.test/a']
})
const maps = extractCitationMapsFromMessages([first, second])
expect(maps).not.toHaveProperty('S2')
expect(processCitations('[1](#S2)', maps)).toBe('')
// The unambiguous label in the same conversation still resolves.
expect(processCitations('[1](#S1)', maps)).toBe(
'[one](https://one.test/a)'
)
})
it('resolves legacy and labelled turns together', () => {
const legacy = {
id: 'legacy',
role: 'assistant',
parts: [
{
type: 'tool-search',
state: 'output-available',
toolCallId: 'call_legacy',
input: { query: 'legacy' },
output: {
results: [
{
title: 'Legacy',
url: 'https://legacy.test/source',
content: 'Legacy evidence'
}
]
}
},
{ type: 'text', text: '[1](#toolu_legacy)' }
]
} as unknown as UIMessage
const labelled = labelledAssistantMessage({
id: 'labelled',
toolCallId: 'search-new',
labels: ['S1'],
urls: ['https://labelled.test/source']
})
const maps = extractCitationMapsFromMessages([legacy, labelled])
expect(processCitations('[1](#toolu_legacy) [1](#S1)', maps)).toBe(
'[legacy](https://legacy.test/source) [labelled](https://labelled.test/source)'
)
})
it('recognizes only derived source labels', () => {
expect(isDerivedLabel('S1')).toBe(true)
expect(isDerivedLabel('S12')).toBe(true)
expect(isDerivedLabel('s1')).toBe(false)
expect(isDerivedLabel('S')).toBe(false)
expect(isDerivedLabel('S1x')).toBe(false)
})
})
describe('isCitationLabel', () => {
it('accepts numeric, simple domain, and dotted domain labels', () => {
expect(isCitationLabel('1')).toBe(true)
expect(isCitationLabel('youtube')).toBe(true)
expect(isCitationLabel('global.example')).toBe(true)
expect(isCitationLabel('world.example')).toBe(true)
})
it('rejects punctuation and whitespace outside the label', () => {
expect(isCitationLabel('')).toBe(false)
expect(isCitationLabel('global.example.')).toBe(false)
expect(isCitationLabel('.global.example')).toBe(false)
expect(isCitationLabel('global example')).toBe(false)
})
})
})