Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(graphs): verify mermaid syntax

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-03 01:32:01 +08:00
parent 665c10ff19
commit 8caf923196
9 changed files with 1328 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
scripts/gen-doc-graphs.ts
View File

@@ -598,31 +598,31 @@ function renderLifecycle(): string {
'sequenceDiagram',
' participant User',
' participant Agent',
' participant Loop',
' participant Driver',
' participant Prompt as ctx.systemPrompt',
' participant LLM as ctx.llm',
' participant Tools as ctx.tools',
' participant Session',
' participant Persistence',
' User->>Agent: send(content)',
' Agent->>Loop: queued work wakes driver',
' Loop->>Session: turn/start + user/message',
' Loop-->>User: agent/turn-start',
' Loop->>Prompt: system-prompt/assemble waterfall',
' Loop-->>Loop: agent/pre-step serial checkpoint',
' Loop->>Session: step/start',
' Loop->>LLM: agent/request waterfall, then llm/stream waterfall',
' LLM-->>Loop: StreamChunk*',
' Loop->>Session: assistant/chunk*',
' Loop-->>User: agent/stream-chunk* (master live mirror)',
' Loop->>Session: assistant/message',
' Loop->>Tools: tools/execute waterfall for each tool-call',
' Agent->>Driver: queued work wakes driver',
' Driver->>Session: turn/start + user/message',
' Driver-->>User: agent/turn-start',
' Driver->>Prompt: system-prompt/assemble waterfall',
' Driver-->>Driver: agent/pre-step serial checkpoint',
' Driver->>Session: step/start',
' Driver->>LLM: agent/request waterfall, then llm/stream waterfall',
' LLM-->>Driver: StreamChunk*',
' Driver->>Session: assistant/chunk*',
' Driver-->>User: agent/stream-chunk* (master live mirror)',
' Driver->>Session: assistant/message',
' Driver->>Tools: tools/execute waterfall for each tool-call',
' Tools-->>Session: tool-owned events when applicable',
' Loop->>Session: tool/result',
' Loop-->>Loop: agent/turn-continuation waterfall',
' Loop->>Session: turn/end',
' Loop->>Persistence: session/flush parallel checkpoint',
' Loop-->>User: agent/status idle',
' Driver->>Session: tool/result',
' Driver-->>Driver: agent/turn-continuation waterfall',
' Driver->>Session: turn/end',
' Driver->>Persistence: session/flush parallel checkpoint',
' Driver-->>User: agent/status idle',
'```',
'',
'Future pressure from the hooks stack: PR #129 removes the live `agent/stream-chunk` mirror and leaves durable `assistant/chunk` on `session/event` as the authoritative token stream. Consumers that need replayable transcript data should already treat `session/event` as the load-bearing path.',
@@ -638,21 +638,21 @@ function renderToolPipeline(): string {
'```mermaid',
'flowchart TD',
' model["Assistant message contains tool-call block"]',
' call["Session event: tool/call"]',
' toolCall["Session event: tool/call"]',
' waterfall["ctx.tools.execute()<br/>tools/execute waterfall"]',
' policy["Policy / permission / hooks listener"]',
' body["Registered tool execute() body"]',
' toolBody["Registered tool execute() body"]',
' owned["Tool-owned session events<br/>todo/write, future fs policy facts"]',
' result["Session event: tool/result"]',
' toolResult["Session event: tool/result"]',
' ui["UI presentation<br/>presentCall / presentResult"]',
' model --> call --> waterfall',
' model --> toolCall --> waterfall',
' waterfall --> policy',
' policy -->|next()| body',
' policy -->|veto / throw| result',
' body --> owned',
' body --> result',
' call --> ui',
' result --> ui',
' policy -->|next| toolBody',
' policy -->|veto / throw| toolResult',
' toolBody --> owned',
' toolBody --> toolResult',
' toolCall --> ui',
' toolResult --> ui',
'```',
'',
'Future pressure from the fs stack: PR #128 snapshots a policy rejection card. The graph keeps the veto path explicit because filesystem read-before-edit checks, permission prompts, and hook bridges all belong on this path.',

107
scripts/verify-mermaid.ts Normal file
View File

@@ -0,0 +1,107 @@
/**
* Doc-sync gate: verify every fenced ```mermaid block parses with Mermaid's
* own parser. Markdown link/type/code gates can say a diagram block exists and
* is linked, but only Mermaid can catch syntax errors that GitHub would fail to
* render.
*
* Scope matches the Markdown link gate so any Mermaid diagram in repo-authored
* docs is checked: README.md, docs/** /*.md, packages/* /*.md,
* packages/* /* /*.md, examples/** /*.md, AGENTS.md, packages/AGENTS.md, and
* .agents/skills/** /*.md.
*
* Run: `tsx scripts/verify-mermaid.ts`.
*/
import { readFileSync, realpathSync } from 'node:fs'
import { resolve } from 'node:path'
import { glob } from 'node:fs/promises'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { gfmFromMarkdown } from 'mdast-util-gfm'
import { gfm } from 'micromark-extension-gfm'
import { JSDOM } from 'jsdom'
import type { Nodes } from 'mdast'
const root = resolve(import.meta.dirname, '..')
const PATTERNS = [
'README.md',
'docs/**/*.md',
'packages/*/*.md',
'packages/*/*/*.md',
'examples/**/*.md',
'AGENTS.md',
'packages/AGENTS.md',
'.agents/skills/**/*.md',
]
interface Block {
file: string
line: number
source: string
}
interface Violation {
file: string
line: number
message: string
}
function extractMermaidBlocks(file: string): Block[] {
const source = readFileSync(resolve(root, file), 'utf8')
const tree = fromMarkdown(source, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] })
const out: Block[] = []
const visit = (node: Nodes): void => {
if (node.type === 'code' && node.lang === 'mermaid') {
out.push({ file, line: node.position?.start.line ?? 0, source: node.value })
}
if ('children' in node) {
for (const child of node.children) visit(child)
}
}
visit(tree)
return out
}
function formatError(error: unknown): string {
if (error instanceof Error) return error.message.replace(/\s+/g, ' ').trim()
return String(error).replace(/\s+/g, ' ').trim()
}
const blocks: Block[] = []
const seen = new Set<string>()
let checkedFiles = 0
for (const pattern of PATTERNS) {
for await (const match of glob(pattern, { cwd: root })) {
const real = realpathSync(resolve(root, match))
if (seen.has(real)) continue
seen.add(real)
checkedFiles++
blocks.push(...extractMermaidBlocks(match))
}
}
const violations: Violation[] = []
const { window } = new JSDOM('')
Object.defineProperty(globalThis, 'window', { value: window })
Object.defineProperty(globalThis, 'document', { value: window.document })
Object.defineProperty(globalThis, 'navigator', { value: window.navigator })
const mermaid = (await import('mermaid')).default
mermaid.initialize({ startOnLoad: false })
for (const block of blocks) {
try {
await mermaid.parse(block.source, { suppressErrors: false })
} catch (error: unknown) {
violations.push({ file: block.file, line: block.line, message: formatError(error) })
}
}
if (violations.length === 0) {
console.log(`verify-mermaid: ${blocks.length} mermaid block(s) parsed across ${checkedFiles} file(s).`)
process.exit(0)
}
console.error('verify-mermaid: Mermaid syntax errors found:')
for (const violation of violations) {
console.error(` ${violation.file}:${violation.line} ${violation.message}`)
}
process.exit(1)