docs(graphs): verify mermaid syntax
This commit is contained in:
Tianyi Cui committed
1 parent
665c10ff19
commit
8caf923196
9 files changed
+1328
-64
No files matched your search
@@ -49,10 +49,10 @@ jobs:
|
||||
|
||||
# Doc-sync gates (doc-sync-enforcement RFC). doc-typecheck compiles the
|
||||
# fenced ts blocks against the root project-reference graph. The cordis
|
||||
# catalog freshness check, type-equiv check, and markdown wrap/link checks
|
||||
# only read source. Same `doc-sync` script the pre-push hook runs
|
||||
# catalog freshness check, type-equiv check, Mermaid syntax check, and
|
||||
# markdown wrap/link checks only read source. Same `doc-sync` script the pre-push hook runs
|
||||
# (quality-gates RFC: one source of truth).
|
||||
- name: Doc-sync gates (doc code blocks + cordis catalog + type-equiv + markdown wrap/links)
|
||||
- name: Doc-sync gates (doc code blocks + catalogs + mermaid + markdown)
|
||||
run: pnpm run doc-sync
|
||||
|
||||
# Module-graph freshness: regenerate docs/module-graph.md from the
|
||||
|
||||
@@ -99,6 +99,7 @@ pnpm run verify-cordis-catalog # fail if the cordis events/services catalog is
|
||||
pnpm run gen-doc-graphs # regenerate docs/graphs/*.md from source and curated graph definitions
|
||||
pnpm run verify-doc-graphs # fail if docs/graphs/*.md is stale
|
||||
pnpm run verify-md-wrap # fail on hard-wrapped prose paragraphs in docs/README markdown
|
||||
pnpm run verify-mermaid # fail if a ```mermaid diagram has invalid Mermaid syntax
|
||||
pnpm run verify-type-equiv # fail if a ```ts type-equiv doc block drifts from its source type
|
||||
pnpm run doc-sync # doc-typecheck, generated doc freshness, markdown wrap/link, and type-equiv verification
|
||||
pnpm run gen-module-graph # regenerate docs/module-graph.md from package peerDeps
|
||||
|
||||
@@ -11,31 +11,31 @@ This sequence is the visual companion to [architecture.md](../architecture.md#lo
|
||||
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.
|
||||
@@ -10,21 +10,21 @@ This graph shows where policy, hooks, sandboxing, and future filesystem guards f
|
||||
```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.
|
||||
@@ -53,6 +53,7 @@ The hybrid pages must fail loud when their manifests are stale:
|
||||
- The capability seam graph imports the Cordis service collector and asserts every discovered harness `ctx.<key>` is classified in `SERVICE_ROLES`, and every classified key still exists.
|
||||
- The tool affordance graph boot-harvests the shipped tool catalog and asserts every tool package has `TOOL_PACKAGE_META`.
|
||||
- The event producer/consumer matrix labels itself hybrid because subagent lifecycle events deliberately use `ctx.events.dispatch` for per-listener containment; those dynamic edges are explicit overrides rather than invisible omissions.
|
||||
- `verify-mermaid` parses every repo-authored ` ```mermaid ` fence with Mermaid's own parser, so syntax errors fail `doc-sync` locally and in CI instead of showing up as broken GitHub-rendered diagrams.
|
||||
|
||||
## Format choices
|
||||
|
||||
@@ -62,5 +63,5 @@ Use Mermaid for committed diagrams because GitHub renders it in Markdown and it
|
||||
|
||||
- Maintainers get visual entry points for topology, seams, event flow, lifecycle, session replay, and snapshot behavior.
|
||||
- SDK users get a path from use case to package composition instead of only bottom-up package references.
|
||||
- `doc-sync` now includes `verify-doc-graphs`, so graph drift is caught with the other doc freshness gates.
|
||||
- `doc-sync` now includes `verify-doc-graphs` and `verify-mermaid`, so graph drift and Mermaid syntax errors are caught with the other doc freshness gates.
|
||||
- Future fs and hooks work has a concrete place to land new complexity: fs should expand the capability and tool graphs, while hooks should expand the event matrix and tool execution pipeline.
|
||||
+5
-1
@@ -29,6 +29,7 @@
|
||||
"verify-md-links": "tsx scripts/verify-md-links.ts",
|
||||
"verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
|
||||
"verify-package-paths": "tsx scripts/verify-package-paths.ts",
|
||||
"verify-mermaid": "tsx scripts/verify-mermaid.ts",
|
||||
"verify-rfc-classification": "tsx scripts/verify-rfc-classification.ts",
|
||||
"verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
|
||||
"verify-node-next-types": "tsx scripts/verify-node-next-types.ts",
|
||||
@@ -41,7 +42,7 @@
|
||||
"gen-module-graph": "tsx scripts/gen-module-graph.ts",
|
||||
"verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
|
||||
"constraints": "tsx scripts/check-workspace-constraints.ts",
|
||||
"doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-rfc-classification && pnpm run verify-type-equiv",
|
||||
"doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-type-equiv",
|
||||
"hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
|
||||
"demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
|
||||
"demo:coding": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
|
||||
@@ -51,15 +52,18 @@
|
||||
"devDependencies": {
|
||||
"@agentclientprotocol/sdk": "0.25.1",
|
||||
"@stylistic/eslint-plugin": "^5.10.0",
|
||||
"@types/jsdom": "^28.0.3",
|
||||
"@types/mdast": "^4.0.4",
|
||||
"@types/node": "^25.3.5",
|
||||
"@vitest/coverage-v8": "^4.1.8",
|
||||
"eslint": "^10.4.1",
|
||||
"fast-check": "^4.8.0",
|
||||
"jsdom": "29.1.1",
|
||||
"knip": "^6.16.1",
|
||||
"lefthook": "^2.1.9",
|
||||
"mdast-util-from-markdown": "^2.0.3",
|
||||
"mdast-util-gfm": "^3.1.0",
|
||||
"mermaid": "11.16.0",
|
||||
"micromark-extension-gfm": "^3.0.0",
|
||||
"publint": "^0.3.21",
|
||||
"tsdown": "^0.22.2",
|
||||
|
||||
Generated
+1154
-3
File diff suppressed because it is too large.
Load diff
+28
-28
@@ -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.',
|
||||
|
||||
@@ -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)
|
||||
Reference in new issue
Block a user