@pyreon/mcp 0.13.1 → 0.15.0

package/src/tests/patterns-content.test.ts

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { API_REFERENCE } from '../api-reference'
+import { loadPatternRegistry } from '../patterns'
+
+// Content-quality test for the patterns corpus. Catches drift that
+// `loadPatternRegistry` and the seeAlso consistency test don't see:
+//
+//  (a) Structural shape — every pattern must follow the standardised
+//      # Title / ## Anti-pattern / ## Related skeleton so the MCP
+//      response has predictable content sections. A file missing any
+//      of these is incomplete doc content; failing the build beats
+//      shipping a half-written pattern.
+//  (b) Detector references — every `Detector: \`<code>\`` mention in
+//      prose must match a real `PyreonDiagnosticCode`. A rename in
+//      the detector without updating the pattern writes a footer
+//      that points at a ghost code.
+//  (c) get_api references — every `get_api({ package: "X", symbol:
+//      "Y" })` prose call with a CONCRETE symbol must resolve in
+//      API_REFERENCE. A rename or deletion of an API entry without
+//      updating the pattern leaves an AI agent chasing a 404.
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// tests/ → src/ → mcp/ → tools/ → packages/ → repo root (5 ups)
+const REPO_ROOT = resolve(HERE, '../../../../../')
+
+// Must stay in sync with `PyreonDiagnosticCode` in
+// `packages/core/compiler/src/pyreon-intercept.ts`. Consistency with
+// that source is enforced by `detector-tag-consistency.test.ts` in
+// the compiler package — we hardcode it here to avoid a cross-package
+// runtime import that would complicate bundling.
+const KNOWN_DETECTOR_CODES = new Set([
+  'for-missing-by',
+  'for-with-key',
+  'props-destructured',
+  'process-dev-gate',
+  'empty-theme',
+  'raw-add-event-listener',
+  'raw-remove-event-listener',
+  'date-math-random-id',
+  'on-click-undefined',
+])
+
+describe('patterns content — structural shape', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it.each(registry.patterns.map((p) => [p.name, p.path]))(
+    '%s has exactly one top-level # heading',
+    (_name, path) => {
+      const body = readFileSync(path, 'utf8')
+      const h1Count = body.split('\n').filter((l) => /^# /.test(l)).length
+      expect(h1Count).toBe(1)
+    },
+  )
+
+  it.each(registry.patterns.map((p) => [p.name, p.path]))(
+    '%s has a ## Anti-pattern section',
+    (_name, path) => {
+      const body = readFileSync(path, 'utf8')
+      // Match the heading at column 0, so "## Anti-pattern" and
+      // "## Anti-pattern (something)" both pass but "### Anti-pattern"
+      // (nested) does not.
+      const hasAnti = /^## Anti-pattern/m.test(body)
+      expect(hasAnti).toBe(true)
+    },
+  )
+
+  it.each(registry.patterns.map((p) => [p.name, p.path]))(
+    '%s has a ## Related section',
+    (_name, path) => {
+      const body = readFileSync(path, 'utf8')
+      const hasRelated = /^## Related/m.test(body)
+      expect(hasRelated).toBe(true)
+    },
+  )
+})
+
+describe('patterns content — detector code references are real', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('every `Detector: \\`<code>\\`` reference names a known PyreonDiagnosticCode', () => {
+    const unknown: Array<{ pattern: string; code: string }> = []
+    for (const p of registry.patterns) {
+      const body = readFileSync(p.path, 'utf8')
+      // Matches lines like "- Detector: `for-missing-by`" or
+      // "- Detector: `raw-add-event-listener` / `raw-remove-event-listener`"
+      const rx = /Detector: `([a-z0-9-]+)`/g
+      for (const m of body.matchAll(rx)) {
+        const code = m[1]!
+        if (!KNOWN_DETECTOR_CODES.has(code)) {
+          unknown.push({ pattern: p.name, code })
+        }
+      }
+    }
+    // If this fails, either (a) the detector code was renamed and
+    // the pattern still cites the old name — fix the pattern —
+    // or (b) a new detector code was added and `KNOWN_DETECTOR_CODES`
+    // in this test is stale — add the new code here AND in
+    // `pyreon-intercept.ts`.
+    expect(unknown).toEqual([])
+  })
+})
+
+describe('patterns content — get_api references resolve', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('every concrete `get_api({ package, symbol })` reference exists in API_REFERENCE', () => {
+    const dangling: Array<{ pattern: string; key: string }> = []
+    for (const p of registry.patterns) {
+      const body = readFileSync(p.path, 'utf8')
+      // Matches: get_api({ package: "hooks", symbol: "useEventListener" })
+      // Skips placeholder symbol values like "..." via the character class.
+      const rx = /get_api\(\{\s*package:\s*"([a-z-]+)"\s*,\s*symbol:\s*"([a-zA-Z]+)"\s*\}\)/g
+      for (const m of body.matchAll(rx)) {
+        const key = `${m[1]}/${m[2]}`
+        if (!API_REFERENCE[key]) {
+          dangling.push({ pattern: p.name, key })
+        }
+      }
+    }
+    // If this fails, the API entry was renamed or removed but the
+    // pattern still cites the old key. Either update the pattern or
+    // restore the API entry.
+    expect(dangling).toEqual([])
+  })
+
+  it('every documented package slug matches a real @pyreon/<pkg>', () => {
+    // Any `get_api({ package: "X" })` whose X is not a valid scope
+    // would pass the key check only if the symbol happens not to
+    // exist (null match). This assertion checks packages regardless
+    // of whether a concrete symbol was provided.
+    const knownPackages = new Set(Object.keys(API_REFERENCE).map((k) => k.split('/')[0]))
+    const unknown: Array<{ pattern: string; pkg: string }> = []
+    for (const p of registry.patterns) {
+      const body = readFileSync(p.path, 'utf8')
+      const rx = /get_api\(\{\s*package:\s*"([a-z-]+)"/g
+      for (const m of body.matchAll(rx)) {
+        const pkg = m[1]!
+        if (!knownPackages.has(pkg)) {
+          unknown.push({ pattern: p.name, pkg })
+        }
+      }
+    }
+    expect(unknown).toEqual([])
+  })
+})

package/src/tests/patterns-server.test.ts

@@ -0,0 +1,160 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { createServer } from '../index'
+
+// Real MCP server <-> client round-trip for the T2.5.3 (`get_pattern`)
+// and T2.5.4 (`get_anti_patterns`) tools. Same setup as the validate
+// integration test — linked in-memory transports + the SDK's Client —
+// so we exercise tool registration, JSON-RPC framing, and the formatter
+// response shape in one pass.
+
+async function newClient(): Promise<{ client: Client; close: () => Promise<void> }> {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+  const server = createServer()
+  await server.connect(serverTransport)
+  const client = new Client({ name: 'test', version: '0.0.0' })
+  await client.connect(clientTransport)
+  return {
+    client,
+    close: async () => {
+      await client.close()
+      await server.close()
+    },
+  }
+}
+
+async function callTool(
+  client: Client,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<string> {
+  const result = (await client.callTool({ name, arguments: args })) as {
+    content: Array<{ type: string; text: string }>
+  }
+  expect(result.content[0]!.type).toBe('text')
+  return result.content[0]!.text
+}
+
+describe('MCP server — get_pattern tool', () => {
+  it('lists available patterns when called with no arg', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_pattern', {})
+      expect(text).toMatch(/^# Pyreon Patterns \(\d+\)/)
+      expect(text).toContain('**dev-warnings**')
+      expect(text).toContain('**controllable-state**')
+      expect(text).toContain('**form-fields**')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns the full body when called with a valid slug', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_pattern', { name: 'dev-warnings' })
+      expect(text).toContain('# Dev-mode warnings')
+      expect(text).toContain('import.meta.env?.DEV')
+      expect(text).toContain('typeof process')
+      // Seealso footer is rendered.
+      expect(text).toContain('**See also:**')
+      expect(text).toContain('ssr-safe-hooks')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns suggestions when called with a misspelled name', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_pattern', { name: 'dev-warn' })
+      expect(text).toContain('not found')
+      expect(text).toContain('Did you mean')
+      expect(text).toContain('dev-warnings')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns a helpful miss message when no match exists at all', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_pattern', { name: 'totally-unrelated-xxx' })
+      expect(text).toContain('not found')
+      expect(text).toContain('get_pattern()')
+    } finally {
+      await close()
+    }
+  })
+})
+
+describe('MCP server — get_anti_patterns tool', () => {
+  it('returns all categories when called with no arg', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_anti_patterns', {})
+      expect(text).toMatch(/^# Pyreon Anti-Patterns \(\d+ total, \d+ categor(y|ies)\)/)
+      // Multiple categories rendered.
+      expect(text).toContain('## Reactivity Mistakes')
+      expect(text).toContain('## JSX Mistakes')
+      expect(text).toContain('## Architecture Mistakes')
+    } finally {
+      await close()
+    }
+  })
+
+  it('filters to a single category', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_anti_patterns', { category: 'reactivity' })
+      expect(text).toMatch(/^# Pyreon Anti-Patterns — reactivity \(\d+\)/)
+      expect(text).toContain('## Reactivity Mistakes')
+      // Other categories must NOT be present.
+      expect(text).not.toContain('## JSX Mistakes')
+      expect(text).not.toContain('## Architecture Mistakes')
+    } finally {
+      await close()
+    }
+  })
+
+  it('surfaces detector tags inline on tagged entries', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_anti_patterns', { category: 'jsx' })
+      expect(text).toContain('[detector: for-missing-by]')
+      expect(text).toContain('[detector: for-with-key]')
+    } finally {
+      await close()
+    }
+  })
+
+  it('accepts "all" explicitly (same output as no arg)', async () => {
+    const { client, close } = await newClient()
+    try {
+      const withArg = await callTool(client, 'get_anti_patterns', { category: 'all' })
+      const noArg = await callTool(client, 'get_anti_patterns', {})
+      expect(withArg).toBe(noArg)
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns an error response for an unknown category (zod validation)', async () => {
+    const { client, close } = await newClient()
+    try {
+      // The SDK returns { isError: true, content: [...] } for zod
+      // validation failures rather than rejecting the promise —
+      // a structured error response surfaces the same detail to
+      // consumers without the throw unwinding their request loop.
+      const result = (await client.callTool({
+        name: 'get_anti_patterns',
+        arguments: { category: 'bogus' },
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      expect(result.isError).toBe(true)
+      expect(result.content[0]!.text).toMatch(/Invalid (option|arguments)/i)
+      expect(result.content[0]!.text).toContain('reactivity')
+    } finally {
+      await close()
+    }
+  })
+})

package/src/tests/patterns.test.ts

@@ -0,0 +1,236 @@
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  findPattern,
+  formatPatternBody,
+  formatPatternIndex,
+  loadPatternRegistry,
+  suggestPatterns,
+} from '../patterns'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// tests/ → src/ → mcp/ → tools/ → packages/ → repo root (5 ups)
+const REPO_ROOT = resolve(HERE, '../../../../../')
+
+describe('loadPatternRegistry — real repo docs/patterns', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('finds the docs/patterns directory', () => {
+    expect(registry.root).toBeTruthy()
+    expect(registry.root).toContain('docs/patterns')
+  })
+
+  it('loads all 14 seeded patterns', () => {
+    const names = registry.patterns.map((p) => p.name).sort()
+    expect(names).toEqual([
+      'controllable-state',
+      'data-fetching',
+      'dev-warnings',
+      'dynamic-fields',
+      'event-listeners',
+      'form-fields',
+      'imperative-toasts',
+      'keyed-lists',
+      'reactive-context',
+      'routing-setup',
+      'signal-writes',
+      'ssr-safe-hooks',
+      'state-management',
+      'styler-theming',
+    ])
+  })
+
+  it('every pattern has a resolvable seeAlso (no dangling references)', () => {
+    // Drift guard: if pattern A says seeAlso: [b] and file b.md is
+    // renamed or removed, this test fails loudly. Otherwise the
+    // footer link in the MCP response would point at a ghost.
+    const valid = new Set(registry.patterns.map((p) => p.name))
+    const dangling: Array<{ from: string; to: string }> = []
+    for (const p of registry.patterns) {
+      for (const ref of p.seeAlso) {
+        if (!valid.has(ref)) dangling.push({ from: p.name, to: ref })
+      }
+    }
+    expect(dangling).toEqual([])
+  })
+
+  it('parses frontmatter on every seeded pattern', () => {
+    for (const p of registry.patterns) {
+      expect(p.title.length).toBeGreaterThan(0)
+      expect(p.summary).not.toBeNull()
+      expect(p.summary!.length).toBeGreaterThan(10)
+    }
+  })
+
+  it('parses the seeAlso array-style frontmatter', () => {
+    const devWarnings = registry.patterns.find((p) => p.name === 'dev-warnings')
+    expect(devWarnings).toBeDefined()
+    expect(devWarnings!.seeAlso).toEqual(['ssr-safe-hooks'])
+  })
+})
+
+describe('loadPatternRegistry — synthetic tmp dir', () => {
+  let tmp: string
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'pyreon-mcp-patterns-'))
+    mkdirSync(join(tmp, 'docs', 'patterns'), { recursive: true })
+  })
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true })
+  })
+
+  it('returns root=null when no docs/patterns exists', () => {
+    // Point to a sibling dir without patterns
+    const empty = mkdtempSync(join(tmpdir(), 'pyreon-mcp-empty-'))
+    try {
+      const r = loadPatternRegistry(empty)
+      expect(r.root).toBeNull()
+      expect(r.patterns).toEqual([])
+    } finally {
+      rmSync(empty, { recursive: true, force: true })
+    }
+  })
+
+  it('falls back to the first heading as title when frontmatter lacks one', () => {
+    writeFileSync(
+      join(tmp, 'docs/patterns/no-title.md'),
+      `---
+summary: Has summary but no title
+---
+
+# The Heading
+
+Body text.`,
+    )
+    const r = loadPatternRegistry(tmp)
+    const p = r.patterns.find((x) => x.name === 'no-title')!
+    expect(p.title).toBe('The Heading')
+  })
+
+  it('falls back to the slug when neither frontmatter nor heading has a title', () => {
+    writeFileSync(
+      join(tmp, 'docs/patterns/slug-only.md'),
+      'Body with no title.',
+    )
+    const r = loadPatternRegistry(tmp)
+    const p = r.patterns.find((x) => x.name === 'slug-only')!
+    expect(p.title).toBe('slug-only')
+  })
+
+  it('parses inline-array seeAlso: [a, b, c]', () => {
+    writeFileSync(
+      join(tmp, 'docs/patterns/inline.md'),
+      `---
+title: Inline
+seeAlso: [one, two, three]
+---
+
+Body.`,
+    )
+    const r = loadPatternRegistry(tmp)
+    expect(r.patterns[0]!.seeAlso).toEqual(['one', 'two', 'three'])
+  })
+
+  it('parses block-style seeAlso with YAML bullets', () => {
+    writeFileSync(
+      join(tmp, 'docs/patterns/block.md'),
+      `---
+title: Block
+seeAlso:
+  - one
+  - two
+---
+
+Body.`,
+    )
+    const r = loadPatternRegistry(tmp)
+    expect(r.patterns[0]!.seeAlso).toEqual(['one', 'two'])
+  })
+
+  it('skips README.md and index.md (reserved doc filenames)', () => {
+    writeFileSync(join(tmp, 'docs/patterns/README.md'), '# Should be skipped')
+    writeFileSync(join(tmp, 'docs/patterns/index.md'), '# Also skipped')
+    writeFileSync(join(tmp, 'docs/patterns/real.md'), '# Real pattern')
+    const r = loadPatternRegistry(tmp)
+    expect(r.patterns.map((p) => p.name)).toEqual(['real'])
+  })
+})
+
+describe('findPattern + suggestPatterns', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('findPattern returns an exact match', () => {
+    const p = findPattern(registry, 'dev-warnings')
+    expect(p).toBeDefined()
+    expect(p!.name).toBe('dev-warnings')
+  })
+
+  it('findPattern returns null for an unknown name', () => {
+    const p = findPattern(registry, 'nonexistent-pattern')
+    expect(p).toBeNull()
+  })
+
+  it('suggestPatterns returns slug substring matches', () => {
+    const s = suggestPatterns(registry, 'warn')
+    expect(s).toContain('dev-warnings')
+  })
+
+  it('suggestPatterns returns title substring matches', () => {
+    const s = suggestPatterns(registry, 'controlled')
+    expect(s).toContain('controllable-state')
+  })
+
+  it('suggestPatterns caps at 5 results', () => {
+    const s = suggestPatterns(registry, 's') // matches many
+    expect(s.length).toBeLessThanOrEqual(5)
+  })
+})
+
+describe('formatPatternIndex', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('renders a header with the pattern count', () => {
+    const out = formatPatternIndex(registry)
+    expect(out).toMatch(/^# Pyreon Patterns \(\d+\)/)
+  })
+
+  it('lists every pattern as a bullet', () => {
+    const out = formatPatternIndex(registry)
+    for (const p of registry.patterns) {
+      expect(out).toContain(`**${p.name}**`)
+    }
+  })
+
+  it('returns a helpful miss message when no patterns exist', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'pyreon-mcp-empty-idx-'))
+    try {
+      const r = loadPatternRegistry(empty)
+      const out = formatPatternIndex(r)
+      expect(out).toContain('No patterns found')
+      expect(out).toContain('docs/patterns')
+    } finally {
+      rmSync(empty, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('formatPatternBody', () => {
+  const registry = loadPatternRegistry(REPO_ROOT)
+
+  it('returns the pattern body', () => {
+    const devWarnings = findPattern(registry, 'dev-warnings')!
+    const out = formatPatternBody(devWarnings)
+    expect(out).toContain('# Dev-mode warnings')
+    expect(out).toContain('import.meta.env')
+  })
+
+  it('appends a See also footer when seeAlso is populated', () => {
+    const devWarnings = findPattern(registry, 'dev-warnings')!
+    const out = formatPatternBody(devWarnings)
+    expect(out).toContain('**See also:**')
+    expect(out).toContain('get_pattern({ name: "ssr-safe-hooks" })')
+  })
+})

package/src/tests/server-integration.test.ts

@@ -0,0 +1,155 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { createServer } from '../index'
+
+// Real MCP server <-> client round-trip via InMemoryTransport. The
+// tool-call payload goes through the full JSON-RPC framing, the tool
+// dispatcher resolves `validate`, and the handler runs with the exact
+// same code path production stdio uses. This locks down the bits the
+// detector unit test cannot: handler registration, merge contract, and
+// the serialised response shape a consumer actually sees.
+
+async function newConnectedClient(): Promise<{ client: Client; close: () => Promise<void> }> {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+
+  const server = createServer()
+  await server.connect(serverTransport)
+
+  const client = new Client({ name: 'test', version: '0.0.0' })
+  await client.connect(clientTransport)
+
+  return {
+    client,
+    close: async () => {
+      await client.close()
+      await server.close()
+    },
+  }
+}
+
+async function callValidate(client: Client, code: string): Promise<string> {
+  const result = (await client.callTool({
+    name: 'validate',
+    arguments: { code },
+  })) as { content: Array<{ type: string; text: string }> }
+
+  // Response is { content: [{ type: 'text', text: '...' }] }
+  expect(result.content).toHaveLength(1)
+  expect(result.content[0]!.type).toBe('text')
+  return result.content[0]!.text
+}
+
+describe('MCP server — validate tool over real JSON-RPC transport', () => {
+  it('invokes the merged detector pipeline on a mixed React + Pyreon snippet', async () => {
+    const { client, close } = await newConnectedClient()
+    try {
+      const code = `
+        import { useState } from 'react'
+
+        const Counter = ({ count }: { count: number }) => {
+          const [local, setLocal] = useState(count)
+          return <For each={items}>{(i) => <li className="x" />}</For>
+        }
+      `
+      const text = await callValidate(client, code)
+
+      // Merged output MUST contain codes from BOTH detectors.
+      // React detector:
+      expect(text).toContain('use-state')
+      expect(text).toContain('react-import')
+      expect(text).toContain('class-name-prop')
+      // Pyreon detector:
+      expect(text).toContain('props-destructured')
+      expect(text).toContain('for-missing-by')
+
+      // Header format "Found N issues" survived serialisation.
+      expect(text).toMatch(/^Found \d+ issues?:/)
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns the no-issues fast path unchanged for idiomatic Pyreon code', async () => {
+    const { client, close } = await newConnectedClient()
+    try {
+      const code = `
+        import { signal } from '@pyreon/reactivity'
+        import { For } from '@pyreon/core'
+
+        const List = (props: { items: Array<{ id: string; name: string }> }) => {
+          const q = signal('')
+          return (
+            <For each={props.items} by={(i) => i.id}>
+              {(i) => <li>{i.name}: {q()}</li>}
+            </For>
+          )
+        }
+      `
+      const text = await callValidate(client, code)
+      expect(text).toBe('✓ No issues found. The code follows Pyreon patterns correctly.')
+    } finally {
+      await close()
+    }
+  })
+
+  it('surfaces the on-click-undefined Pyreon-only diagnostic via the handler', async () => {
+    // Covers the "Pyreon-only, no React match" path — the React detector
+    // returns [], the Pyreon detector returns 1, and the MCP handler
+    // must still emit the "Found N issues" header and the diagnostic.
+    const { client, close } = await newConnectedClient()
+    try {
+      const text = await callValidate(client, `<button onClick={undefined}>x</button>`)
+      expect(text).toContain('on-click-undefined')
+      expect(text).toContain('omit')
+      expect(text).toMatch(/^Found 1 issue:/)
+    } finally {
+      await close()
+    }
+  })
+
+  it('locks the MCP response format (toMatchInlineSnapshot)', async () => {
+    // The textual format consumers render in their UI. An unannounced
+    // format change would drift consumer UIs silently. Update the
+    // snapshot deliberately via `bun run test -- -u` when the format
+    // is genuinely supposed to change.
+    const { client, close } = await newConnectedClient()
+    try {
+      // Single diagnostic so the snapshot stays readable.
+      const text = await callValidate(client, `<button onClick={undefined}>x</button>`)
+      expect(text).toMatchInlineSnapshot(`
+        "Found 1 issue:
+
+        1. **on-click-undefined** (line 1)
+           \`onClick={undefined}\` explicitly passes undefined as a listener. Pyreon's runtime guards against this, but the cleanest pattern is to omit the attribute entirely or use a conditional: \`onClick={condition ? handler : undefined}\`.
+           Current: \`onClick={undefined}\`
+           Fix: \`/* omit onClick when the handler is not defined */\`
+           Auto-fixable: no"
+      `)
+    } finally {
+      await close()
+    }
+  })
+
+  it('sorts the merged diagnostics by line number in the response', async () => {
+    // The handler merges React + Pyreon diagnostics and sorts by
+    // (line, column). Verify the sort survived the round trip.
+    const { client, close } = await newConnectedClient()
+    try {
+      const code = `
+        import { useState } from 'react'
+        // eslint-disable-next-line
+        const X = () => <For each={items}>{(i) => <li className="y" />}</For>
+      `
+      const text = await callValidate(client, code)
+
+      // Extract "(line N)" tokens and assert monotonically non-decreasing.
+      const lines = [...text.matchAll(/\(line (\d+)\)/g)].map((m) => Number(m[1]))
+      expect(lines.length).toBeGreaterThan(1)
+      for (let i = 1; i < lines.length; i++) {
+        expect(lines[i]).toBeGreaterThanOrEqual(lines[i - 1]!)
+      }
+    } finally {
+      await close()
+    }
+  })
+})