@pyreon/mcp 0.13.1 → 0.14.0

package/src/patterns.ts

@@ -0,0 +1,243 @@
+/**
+ * Pattern registry for the `get_pattern` MCP tool (T2.5.3).
+ *
+ * Each pattern answers a "how do I do X the right way" question with a
+ * code example and rationale. The content is the body of the
+ * corresponding `docs/patterns/<name>.md` file, discovered at runtime
+ * by walking up from `process.cwd()` to the nearest repo that contains
+ * `docs/patterns/`.
+ *
+ * Why a filesystem lookup instead of bundled content: the patterns
+ * belong in the VitePress site (they're first-class docs), and having
+ * the MCP fetch them live means the AI sees the same text the human
+ * would. Bundling copies would drift.
+ *
+ * Fallback: if no `docs/patterns/` exists in the walk (e.g. the MCP is
+ * running in a consumer repo), the tool reports the miss and lists
+ * what patterns WOULD be available if running against the Pyreon
+ * monorepo. The list itself is seeded from the directory walk, so
+ * adding a new pattern file makes it discoverable without code changes.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+export interface PatternFile {
+  /** Slug (filename without extension) — the value consumers pass to get_pattern */
+  name: string
+  /** Absolute path to the source markdown file */
+  path: string
+  /** Raw markdown body */
+  body: string
+  /** Title from the frontmatter or first `# ` heading */
+  title: string
+  /** Optional one-line summary from the frontmatter */
+  summary: string | null
+  /** Cross-reference slugs from the frontmatter */
+  seeAlso: string[]
+}
+
+export interface PatternRegistry {
+  /** Root dir (the `docs/patterns/` directory that was found) */
+  root: string | null
+  /** All patterns, sorted by slug */
+  patterns: PatternFile[]
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Directory walk
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// Patterns live at `docs/docs/patterns/` — the VitePress content dir
+// so the same file serves both the MCP tool AND the docs website. We
+// also check the top-level `docs/patterns/` layout for forward
+// compatibility, in case a future migration moves them up.
+const PATTERN_PATH_CANDIDATES: ReadonlyArray<ReadonlyArray<string>> = [
+  ['docs', 'docs', 'patterns'],
+  ['docs', 'patterns'],
+]
+
+function findPatternsDir(startDir: string): string | null {
+  let dir = resolve(startDir)
+  for (let i = 0; i < 30; i++) {
+    for (const segments of PATTERN_PATH_CANDIDATES) {
+      const candidate = join(dir, ...segments)
+      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        return candidate
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+  return null
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Frontmatter parser (YAML-ish — no external dep)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Minimal frontmatter parser. Supports:
+ *   title: string (unquoted or quoted)
+ *   summary: string
+ *   seeAlso: [one, two, three]  OR  seeAlso:\n  - one\n  - two
+ *
+ * Anything else is ignored. Full YAML would be overkill here.
+ */
+function parseFrontmatter(source: string): {
+  meta: { title?: string; summary?: string; seeAlso?: string[] }
+  body: string
+} {
+  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(source)
+  if (!match) return { meta: {}, body: source }
+  const rawMeta = match[1]!
+  const body = match[2]!.trim()
+
+  const meta: { title?: string; summary?: string; seeAlso?: string[] } = {}
+
+  const lines = rawMeta.split('\n')
+  let seeAlsoActive = false
+  const seeAlsoItems: string[] = []
+
+  for (const line of lines) {
+    if (seeAlsoActive) {
+      const bullet = /^\s*-\s*(.+?)\s*$/.exec(line)
+      if (bullet) {
+        seeAlsoItems.push(bullet[1]!)
+        continue
+      }
+      seeAlsoActive = false
+    }
+
+    const kv = /^([a-zA-Z]+):\s*(.*)$/.exec(line)
+    if (!kv) continue
+    const key = kv[1]!
+    const value = kv[2]!.trim()
+
+    if (key === 'title') {
+      meta.title = value.replace(/^["']|["']$/g, '')
+    } else if (key === 'summary') {
+      meta.summary = value.replace(/^["']|["']$/g, '')
+    } else if (key === 'seeAlso') {
+      if (value.startsWith('[') && value.endsWith(']')) {
+        meta.seeAlso = value
+          .slice(1, -1)
+          .split(',')
+          .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+          .filter(Boolean)
+      } else if (value === '') {
+        seeAlsoActive = true
+      }
+    }
+  }
+
+  if (seeAlsoActive && seeAlsoItems.length > 0) {
+    meta.seeAlso = seeAlsoItems
+  }
+
+  return { meta, body }
+}
+
+function extractFirstHeading(body: string): string | null {
+  for (const line of body.split('\n')) {
+    const h = /^#\s+(.+)$/.exec(line)
+    if (h) return h[1]!
+  }
+  return null
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Public API
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export function loadPatternRegistry(startDir: string = process.cwd()): PatternRegistry {
+  const root = findPatternsDir(startDir)
+  if (!root) return { root: null, patterns: [] }
+
+  const patterns: PatternFile[] = []
+  const entries = readdirSync(root).sort()
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue
+    if (entry.startsWith('.') || entry === 'README.md' || entry === 'index.md') continue
+    const filePath = join(root, entry)
+    let source: string
+    try {
+      source = readFileSync(filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const { meta, body } = parseFrontmatter(source)
+    const name = entry.replace(/\.md$/, '')
+    const title = meta.title ?? extractFirstHeading(body) ?? name
+    patterns.push({
+      name,
+      path: filePath,
+      body: source,
+      title,
+      summary: meta.summary ?? null,
+      seeAlso: meta.seeAlso ?? [],
+    })
+  }
+
+  return { root, patterns }
+}
+
+/**
+ * Format the registry as a short index listing for the "no arg" case.
+ * Each entry: `  - slug — title (summary)`.
+ */
+export function formatPatternIndex(registry: PatternRegistry): string {
+  if (!registry.root || registry.patterns.length === 0) {
+    return (
+      'No patterns found. Patterns live at `docs/docs/patterns/<name>.md` ' +
+      '(the VitePress content directory) in the Pyreon monorepo. If you ' +
+      'are running the MCP in a consumer project, patterns are not ' +
+      'available locally — run the MCP in the Pyreon repo to browse them.'
+    )
+  }
+
+  const parts: string[] = [`# Pyreon Patterns (${registry.patterns.length})`, '']
+  parts.push(
+    'Call `get_pattern({ name: "<slug>" })` for the full body. Each pattern shows the canonical "do it this way" with code + rationale, plus the anti-pattern to avoid.',
+  )
+  parts.push('')
+  for (const p of registry.patterns) {
+    const summary = p.summary ? ` — ${p.summary}` : ''
+    parts.push(`- **${p.name}** — ${p.title}${summary}`)
+  }
+  return parts.join('\n')
+}
+
+/**
+ * Format a single pattern's full body for the MCP response. Prepends
+ * a breadcrumb and appends a cross-reference footer if `seeAlso` was
+ * populated.
+ */
+export function formatPatternBody(pattern: PatternFile): string {
+  const parts: string[] = [pattern.body.trimEnd()]
+  if (pattern.seeAlso.length > 0) {
+    parts.push('')
+    parts.push(
+      `---\n\n**See also:** ${pattern.seeAlso.map((s) => `\`get_pattern({ name: "${s}" })\``).join(', ')}`,
+    )
+  }
+  return parts.join('\n')
+}
+
+export function findPattern(registry: PatternRegistry, name: string): PatternFile | null {
+  for (const p of registry.patterns) {
+    if (p.name === name) return p
+  }
+  return null
+}
+
+export function suggestPatterns(registry: PatternRegistry, name: string): string[] {
+  const needle = name.toLowerCase()
+  const matches: string[] = []
+  for (const p of registry.patterns) {
+    if (p.name.toLowerCase().includes(needle) || p.title.toLowerCase().includes(needle)) {
+      matches.push(p.name)
+    }
+  }
+  return matches.slice(0, 5)
+}

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

@@ -0,0 +1,180 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  ANTI_PATTERN_CATEGORIES,
+  type AntiPatternCategory,
+  formatAntiPatterns,
+  parseAntiPatterns,
+} from '../anti-patterns'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// tests/ → src/ → mcp/ → tools/ → packages/ → repo root (5 ups)
+const REPO_ROOT = resolve(HERE, '../../../../../')
+const ANTI_PATTERNS_PATH = resolve(REPO_ROOT, '.claude/rules/anti-patterns.md')
+
+describe('parseAntiPatterns — real repo file', () => {
+  const doc = readFileSync(ANTI_PATTERNS_PATH, 'utf8')
+  const entries = parseAntiPatterns(doc)
+
+  it('returns at least one entry per documented category', () => {
+    const categoriesFound = new Set(entries.map((e) => e.category))
+    for (const cat of ANTI_PATTERN_CATEGORIES) {
+      expect(categoriesFound.has(cat)).toBe(true)
+    }
+  })
+
+  it('returns entries with non-empty name + description', () => {
+    for (const entry of entries) {
+      expect(entry.name.length).toBeGreaterThan(0)
+      expect(entry.description.length).toBeGreaterThan(10)
+    }
+  })
+
+  it('parses multi-code detector tags (e.g. "raw-add / raw-remove")', () => {
+    const withDual = entries.find((e) => e.detectorCodes.length > 1)
+    expect(withDual).toBeDefined()
+    // The raw-listener anti-pattern in `lifecycle` / `architecture` docs
+    // both codes on one bullet.
+    expect(withDual!.detectorCodes).toContain('raw-add-event-listener')
+  })
+
+  it('parses single-code detector tags on known entries', () => {
+    const forMissingBy = entries.find((e) =>
+      e.detectorCodes.includes('for-missing-by'),
+    )
+    expect(forMissingBy).toBeDefined()
+    expect(forMissingBy!.category).toBe('jsx')
+    expect(forMissingBy!.name).toContain('by')
+  })
+
+  it('includes doc-only entries (no detector tag)', () => {
+    const docOnly = entries.filter((e) => e.detectorCodes.length === 0)
+    expect(docOnly.length).toBeGreaterThan(10)
+  })
+
+  it('preserves file order within each category', () => {
+    // The first reactivity bullet is "Bare signal in JSX text"
+    const firstReactivity = entries.find((e) => e.category === 'reactivity')
+    expect(firstReactivity!.name).toBe('Bare signal in JSX text')
+  })
+})
+
+describe('parseAntiPatterns — synthetic inputs', () => {
+  it('ignores bullets outside a known category heading', () => {
+    const doc = `# Anti-Patterns
+
+Intro prose — never parsed as an anti-pattern.
+
+## Unknown Heading Not In Map
+
+- **Ignored** \`[detector: for-missing-by]\`: this should not land in output.
+
+## Reactivity Mistakes
+
+- **Real entry**: this one does land.
+`
+    const entries = parseAntiPatterns(doc)
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.name).toBe('Real entry')
+    expect(entries[0]!.category).toBe('reactivity')
+  })
+
+  it('strips trailing colon and leading whitespace from the description', () => {
+    const doc = `## JSX Mistakes
+
+- **X**   :   body text here`
+    const [only] = parseAntiPatterns(doc)
+    expect(only!.description).toBe('body text here')
+  })
+
+  it('accepts bullets with NO detector tag', () => {
+    const doc = `## JSX Mistakes
+
+- **Plain**: no tag here`
+    const [only] = parseAntiPatterns(doc)
+    expect(only!.detectorCodes).toEqual([])
+  })
+
+  it('survives backtick-wrapped detector tags', () => {
+    const doc = `## JSX Mistakes
+
+- **X** \`[detector: for-missing-by]\`: body`
+    const [only] = parseAntiPatterns(doc)
+    expect(only!.detectorCodes).toEqual(['for-missing-by'])
+  })
+
+  it('splits multi-continuation-line bullets correctly', () => {
+    const doc = `## Reactivity Mistakes
+
+- **Long one**: first line
+  continuation line
+  another continuation
+- **Second**: short`
+    const entries = parseAntiPatterns(doc)
+    expect(entries).toHaveLength(2)
+    expect(entries[0]!.name).toBe('Long one')
+    expect(entries[0]!.description).toContain('first line')
+    expect(entries[0]!.description).toContain('continuation line')
+    expect(entries[1]!.name).toBe('Second')
+  })
+})
+
+describe('formatAntiPatterns', () => {
+  const doc = readFileSync(ANTI_PATTERNS_PATH, 'utf8')
+  const entries = parseAntiPatterns(doc)
+
+  it('renders an "all" header with entry count + category count', () => {
+    const out = formatAntiPatterns(entries, 'all')
+    expect(out).toMatch(/^# Pyreon Anti-Patterns \(\d+ total, \d+ categor(y|ies)\)/)
+  })
+
+  it('renders a category-filtered header', () => {
+    const reactivity = entries.filter((e) => e.category === 'reactivity')
+    const out = formatAntiPatterns(reactivity, 'reactivity')
+    expect(out).toMatch(/^# Pyreon Anti-Patterns — reactivity \(\d+\)/)
+  })
+
+  it('includes detector tags inline on entries that have them', () => {
+    const reactivity = entries.filter((e) => e.category === 'reactivity')
+    const out = formatAntiPatterns(reactivity, 'reactivity')
+    // "Destructuring props" has `[detector: props-destructured]`
+    expect(out).toContain('`[detector: props-destructured]`')
+  })
+
+  it('returns a descriptive message when entries is empty', () => {
+    const out = formatAntiPatterns([], 'jsx' as AntiPatternCategory)
+    expect(out).toContain('No anti-patterns found in category')
+    expect(out).toContain('Valid categories')
+  })
+
+  it('mentions validate + anti-patterns.md in the header prose', () => {
+    const out = formatAntiPatterns(entries, 'all')
+    expect(out).toContain('anti-patterns.md')
+    expect(out).toContain('validate')
+  })
+})
+
+describe('coverage parity — every detector code has a bullet', () => {
+  // This test is complementary to the one in the compiler package —
+  // it verifies from the MCP side that the parser surfaces every
+  // detector code that downstream consumers expect.
+  const doc = readFileSync(ANTI_PATTERNS_PATH, 'utf8')
+  const entries = parseAntiPatterns(doc)
+  const knownCodes = [
+    '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',
+  ]
+
+  it.each(knownCodes)('%s appears on at least one parsed bullet', (code) => {
+    const match = entries.find((e) => e.detectorCodes.includes(code))
+    expect(match).toBeDefined()
+  })
+})

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

@@ -0,0 +1,176 @@
+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.8 get_changelog
+// tool. Same InMemoryTransport shape as the patterns-server test —
+// exercises 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_changelog tool', () => {
+  it('lists every package when called with no arg', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_changelog', {})
+      expect(text).toMatch(/^# Pyreon Changelogs \(\d+ packages\)/)
+      expect(text).toContain('**@pyreon/query**')
+      expect(text).toContain('**@pyreon/router**')
+      expect(text).toContain('**@pyreon/form**')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns recent versions for a package (fully-qualified name)', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_changelog', { package: '@pyreon/query' })
+      expect(text).toContain('@pyreon/query — changelog')
+      // At least one version heading.
+      expect(text).toMatch(/^## \d+\.\d+\.\d+/m)
+    } finally {
+      await close()
+    }
+  })
+
+  it('accepts the short slug (auto-prefixes @pyreon/)', async () => {
+    const { client, close } = await newClient()
+    try {
+      const short = await callTool(client, 'get_changelog', { package: 'query' })
+      const qualified = await callTool(client, 'get_changelog', { package: '@pyreon/query' })
+      expect(short).toBe(qualified)
+    } finally {
+      await close()
+    }
+  })
+
+  it('respects the limit parameter', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_changelog', { package: 'query', limit: 1 })
+      const versionHeadings = text.split('\n').filter((l) => /^## \d+\.\d+/.test(l))
+      expect(versionHeadings).toHaveLength(1)
+    } finally {
+      await close()
+    }
+  })
+
+  it('omits Updated-dependencies by default, includes when flag is true', async () => {
+    const { client, close } = await newClient()
+    try {
+      const withoutDeps = await callTool(client, 'get_changelog', {
+        package: 'query',
+        limit: 10,
+      })
+      const withDeps = await callTool(client, 'get_changelog', {
+        package: 'query',
+        limit: 10,
+        includeDependencyUpdates: true,
+      })
+      expect(withoutDeps).not.toContain('Updated dependencies')
+      expect(withDeps).toContain('Updated dependencies')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns suggestions for a misspelled name', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_changelog', { package: 'quer' })
+      expect(text).toContain('not found')
+      expect(text).toContain('Did you mean')
+      expect(text).toContain('@pyreon/query')
+    } 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_changelog', { package: 'totally-unrelated-xxx' })
+      expect(text).toContain('not found')
+      expect(text).toContain('get_changelog()')
+    } finally {
+      await close()
+    }
+  })
+
+  it('accepts a `since` floor and returns only newer versions', async () => {
+    const { client, close } = await newClient()
+    try {
+      // First get the full index to pick a real floor version.
+      const full = await callTool(client, 'get_changelog', { package: 'query', limit: 20 })
+      // Extract the 3rd-oldest version heading (needs at least 3 for the test to be meaningful).
+      const headings = [...full.matchAll(/^## (\S+)$/gm)].map((m) => m[1]!)
+      expect(headings.length).toBeGreaterThanOrEqual(3)
+      const floor = headings[headings.length - 2]! // everything newer than the second-oldest
+      const filtered = await callTool(client, 'get_changelog', {
+        package: 'query',
+        limit: 20,
+        since: floor,
+      })
+      expect(filtered).toContain(`since v${floor}`)
+      expect(filtered).not.toContain(`## ${floor}\n`) // floor itself excluded (strict)
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns the "no changes since" miss message when the floor is the latest', async () => {
+    const { client, close } = await newClient()
+    try {
+      // Find the real latest substantive version from the package.
+      const full = await callTool(client, 'get_changelog', { package: 'query', limit: 1 })
+      const latest = /^## (\S+)$/m.exec(full)![1]!
+      const result = await callTool(client, 'get_changelog', {
+        package: 'query',
+        since: latest,
+      })
+      expect(result).toContain(`no changes since v${latest}`)
+    } finally {
+      await close()
+    }
+  })
+
+  it('rejects a negative limit via zod', async () => {
+    const { client, close } = await newClient()
+    try {
+      const result = (await client.callTool({
+        name: 'get_changelog',
+        arguments: { package: 'query', limit: -5 },
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      expect(result.isError).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})