Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
/**
* 知识库文档预览 Markdown 排版回归测试。
*
* 为什么这样断言:仓库里的测试在 `tsx --test`(Node,无 DOM)下运行,依赖里
* 没有 jsdom/Playwright,也不适合为一个排版断言引入浏览器。这里:
* 1. 用 `@vue/compiler-sfc` 的 `parse` + `compileStyle({ scoped, preprocessLang: 'less' })`
* 编译组件的真实 `<style scoped lang="less">`(与 Vite 构建同一套实现,
* 包括 `@import` 进来的 markdown.less 和 `:deep()` 的 scoped 展开);
* 2. 用真实的 marked 渲染管线生成正文 HTML,套进组件模板里真实的容器
* (`.doc-markdown-root > .md-content` / `.document-preview > .markdown-body`);
* 3. 用 `@vue/compiler-dom` 解析出 DOM 树,按 CSS 级联算出 `font-size` /
* `padding-left` / `margin-bottom` 等属性的生效值,断言关键属性。
*
* 这样断言的是「编译后的样式 + 真实渲染出的标签结构」,能同时抓住选择器
* 不命中(类名/作用域写错)和样式本身太弱(标题同级、列表无缩进)两类问题。
*/
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import test from 'node:test'
import { fileURLToPath } from 'node:url'
import { parse as parseSfc, compileStyle } from '@vue/compiler-sfc'
import {
buildDomTree,
parseCssRules,
winningDeclaration,
type DomNode,
} from '../test-utils/cssRuleMatcher.ts'
import { renderDocumentPreviewMarkdown } from '../utils/documentPreviewMarkdown.ts'
const SCOPE_ID = 'data-v-previewtest'
const FRONTEND_ROOT = new URL('../../', import.meta.url)
const DOC_CONTENT_SFC = new URL('src/components/doc-content.vue', FRONTEND_ROOT)
const DOCUMENT_PREVIEW_SFC = new URL('src/components/document-preview.vue', FRONTEND_ROOT)
const THEME_CSS = new URL('src/assets/theme/theme.css', FRONTEND_ROOT)
type StyleLang = 'less' | 'sass' | 'scss' | 'styl' | 'stylus'
const SAMPLE = `# 一线标题
正文段落用于确认段落间距。
## 二级标题
- 项目协同(团队版中)
- 项目分享(团队版中)
### 三级标题
> 引用块
#### 四级标题
| 能力 | 说明 |
| --- | --- |
| 列表 | 支持 |
行内 \`code\` 与代码块:
\`\`\`ts
const a = 1
\`\`\`
`
/** 编译 SFC 里所有 scoped style 块(包含 less `@import` 与 `:deep()`)。 */
function compileScopedStyle(file: URL): string {
const filename = fileURLToPath(file)
const { descriptor, errors } = parseSfc(readFileSync(filename, 'utf8'), { filename })
assert.equal(errors.length, 0, `SFC parse errors in ${filename}`)
const scoped = descriptor.styles.filter(style => style.scoped)
assert.ok(scoped.length > 0, `expected a scoped style block in ${filename}`)
return scoped
.map(style =>
compileStyle({
source: style.content,
filename,
id: SCOPE_ID,
scoped: true,
preprocessLang: style.lang as StyleLang | undefined,
}),
)
.map(result => {
assert.equal(result.errors.length, 0, `style compile errors in ${filename}`)
return result.code
})
.join('\n')
}
/** 读取 theme.css 里的 `--app-text-*` / `--app-space-*` 令牌。 */
function readThemeTokens(): Map<string, string> {
const css = readFileSync(fileURLToPath(THEME_CSS), 'utf8')
const tokens = new Map<string, string>()
for (const match of css.matchAll(/--(app-(?:text|space)-[\w-]+)\s*:\s*([\d.]+px)/g)) {
tokens.set(`--${match[1]}`, match[2])
}
return tokens
}
const TOKENS = readThemeTokens()
function resolvePx(value: string | undefined | null): number | null {
if (!value) return null
const trimmed = value.trim()
const varMatch = trimmed.match(/^var\(\s*(--[\w-]+)\s*\)$/)
if (varMatch) {
const token = TOKENS.get(varMatch[1])
return token ? Number.parseFloat(token) : null
}
const pxMatch = trimmed.match(/^(-?[\d.]+)px$/)
return pxMatch ? Number.parseFloat(pxMatch[1]) : null
}
function findByTag(root: DomNode, tag: string): DomNode | null {
for (const child of root.children) {
if (child.tag === tag) return child
const nested = findByTag(child, tag)
if (nested) return nested
}
return null
}
function findByClass(root: DomNode, className: string): DomNode | null {
for (const child of root.children) {
if (child.classes.includes(className)) return child
const nested = findByClass(child, className)
if (nested) return nested
}
return null
}
function requiredDeclared(rules: ReturnType<typeof parseCssRules>, node: DomNode, property: string): string {
const declaration = winningDeclaration(rules, node, property)
assert.ok(
declaration,
`no rule declares ${property} for <${node.tag}> under .${node.classes.join('.')}`,
)
return declaration.value
}
function numberFor(rules: ReturnType<typeof parseCssRules>, node: DomNode, property: string): number {
const value = requiredDeclared(rules, node, property)
const px = resolvePx(value)
assert.ok(px !== null, `cannot resolve ${property}: ${value}`)
return px
}
function markdownBody(): string {
// 两个界面用的是同一套 marked + marked-katex 结构;这里用预览管线生成
// 真实标签(h1/h2/ul/li/p/table/blockquote/pre/code),再分别套上各自的
// 容器与编译后的 scoped CSS。
return renderDocumentPreviewMarkdown(SAMPLE, value => value)
}
function mergedPreviewTree(): DomNode {
// 与 doc-content.vue 模板一致:.doc_content 下的正文根节点带 scoped 属性,
// v-html 容器是 .md-content。
const html = `<div class="doc_content" ${SCOPE_ID}><div class="doc-markdown-root doc-drawer-body" ${SCOPE_ID}><div class="md-content doc-merged-content" ${SCOPE_ID}>${markdownBody()}</div></div></div>`
return buildDomTree(html)
}
function documentPreviewTree(): DomNode {
// 与 document-preview.vue 模板一致:根 .document-preview 带 scoped 属性,
// Markdown 渲染进 .markdown-body。
const html = `<div class="document-preview" ${SCOPE_ID}><div class="preview-markdown"><div class="markdown-body" ${SCOPE_ID}>${markdownBody()}</div></div></div>`
return buildDomTree(html)
}
function assertTypography(surface: string, tree: DomNode, rules: ReturnType<typeof parseCssRules>) {
const headings = ['h1', 'h2', 'h3', 'h4'].map(tag => {
const node = findByTag(tree, tag)
assert.ok(node, `${surface}: rendered markup is missing <${tag}>`)
return numberFor(rules, node, 'font-size')
})
for (let index = 1; index < headings.length; index += 1) {
assert.ok(
headings[index] < headings[index - 1],
`${surface}: heading scale is flat (h${index}=${headings[index - 1]}px, h${index + 1}=${headings[index]}px)`,
)
}
assert.notEqual(headings[0], headings[1], `${surface}: h1 and h2 must not share a font-size`)
const ul = findByTag(tree, 'ul')
assert.ok(ul, `${surface}: rendered markup is missing <ul>`)
const ulIndent = numberFor(rules, ul, 'padding-left')
assert.ok(ulIndent >= 16, `${surface}: list indent too small (${ulIndent}px)`)
const li = findByTag(ul, 'li')
assert.ok(li, `${surface}: rendered markup is missing <li>`)
const liLineHeight = Number.parseFloat(requiredDeclared(rules, li, 'line-height'))
assert.ok(liLineHeight >= 1.5, `${surface}: list line-height too tight (${liLineHeight})`)
const paragraph = findByTag(tree, 'p')
assert.ok(paragraph, `${surface}: rendered markup is missing <p>`)
const paragraphGap = numberFor(rules, paragraph, 'margin-bottom')
assert.ok(paragraphGap > 0, `${surface}: paragraphs have no bottom spacing`)
const blockquote = findByTag(tree, 'blockquote')
assert.ok(blockquote, `${surface}: rendered markup is missing <blockquote>`)
const quoteBorder = numberFor(rules, blockquote, 'border-left-width')
assert.ok(quoteBorder > 0, `${surface}: blockquote has no left border`)
const table = findByTag(tree, 'table')
assert.ok(table, `${surface}: rendered markup is missing <table>`)
assert.equal(
requiredDeclared(rules, table, 'border-collapse').trim(),
'collapse',
`${surface}: table borders must collapse`,
)
const pre = findByTag(tree, 'pre')
assert.ok(pre, `${surface}: rendered markup is missing <pre>`)
const preBackground = winningDeclaration(rules, pre, 'background')
assert.ok(preBackground, `${surface}: code block has no background`)
const inlineCode = findByTag(paragraph, 'code') ?? findByTag(tree, 'code')
assert.ok(inlineCode, `${surface}: rendered markup is missing <code>`)
assert.ok(
winningDeclaration(rules, inlineCode, 'padding') ?? winningDeclaration(rules, inlineCode, 'padding-left'),
`${surface}: inline code has no padding`,
)
// 正文窄栏:容器有可读的行宽上限(不是无限拉满整屏)。
const contentRoot = findByClass(tree, 'md-content') ?? findByClass(tree, 'markdown-body')
assert.ok(contentRoot, `${surface}: rendered markup is missing the content root`)
const maxWidth = numberFor(rules, contentRoot, 'max-width')
assert.ok(maxWidth >= 480 && maxWidth <= 800, `${surface}: reading column is ${maxWidth}px wide`)
}
test('merged/chunk view (.md-content) gets real Markdown typography', () => {
const rules = parseCssRules(compileScopedStyle(DOC_CONTENT_SFC))
assertTypography('.md-content', mergedPreviewTree(), rules)
})
test('preview view (.markdown-body) gets real Markdown typography', () => {
const rules = parseCssRules(compileScopedStyle(DOCUMENT_PREVIEW_SFC))
assertTypography('.markdown-body', documentPreviewTree(), rules)
})
test('scoped Markdown rules need the real container class in the DOM', () => {
const rules = parseCssRules(compileScopedStyle(DOC_CONTENT_SFC))
const treeWithoutClass = buildDomTree(
`<div class="doc_content" ${SCOPE_ID}><div class="doc-markdown-root" ${SCOPE_ID}><div class="doc_content-body">${markdownBody()}</div></div></div>`,
)
const h1 = findByTag(treeWithoutClass, 'h1')
assert.ok(h1)
// 没有 .md-content 容器时,这些排版规则不应命中(正是本次要修的「选择器
// 不命中」故障形态)。若这里开始能命中,说明规则被写成了全局标签选择器。
assert.equal(winningDeclaration(rules, h1, 'font-size'), null)
})
test('Markdown rules no longer depend on .doc_content being the render container', () => {
const rules = parseCssRules(compileScopedStyle(DOC_CONTENT_SFC))
const tree = mergedPreviewTree()
const h1 = findByTag(tree, 'h1')
assert.ok(h1)
const winner = winningDeclaration(rules, h1, 'font-size')
assert.ok(winner)
// 命中的选择器必须落在真实容器 .md-content 上,而不是抽屉外壳 .doc_content。
assert.match(winner.selector, /\.md-content/)
assert.doesNotMatch(winner.selector, /\.doc_content(?![\w-])/)
})