@pyreon/mcp 0.5.0

package/src/project-scanner.ts

@@ -0,0 +1,215 @@
+/**
+ * Project scanner — extracts route, component, and island information from source files.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+export interface RouteInfo {
+  path: string
+  name?: string | undefined
+  component?: string | undefined
+  hasLoader: boolean
+  hasGuard: boolean
+  params: string[]
+}
+
+export interface ComponentInfo {
+  name: string
+  file: string
+  hasSignals: boolean
+  signalNames: string[]
+  props: string[]
+}
+
+export interface IslandInfo {
+  name: string
+  file: string
+  hydrate: string
+}
+
+export interface ProjectContext {
+  framework: "pyreon"
+  version: string
+  generatedAt: string
+  routes: RouteInfo[]
+  components: ComponentInfo[]
+  islands: IslandInfo[]
+}
+
+export function generateContext(cwd: string): ProjectContext {
+  const files = collectSourceFiles(cwd)
+  const version = readVersion(cwd)
+
+  return {
+    framework: "pyreon",
+    version,
+    generatedAt: new Date().toISOString(),
+    routes: extractRoutes(files, cwd),
+    components: extractComponents(files, cwd),
+    islands: extractIslands(files, cwd),
+  }
+}
+
+function collectSourceFiles(cwd: string): string[] {
+  const results: string[] = []
+  const extensions = new Set([".tsx", ".jsx", ".ts", ".js"])
+  const ignoreDirs = new Set(["node_modules", "dist", "lib", ".pyreon", ".git", "build"])
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: simple recursive walker
+  function walk(dir: string): void {
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") && entry.isDirectory()) continue
+      if (ignoreDirs.has(entry.name) && entry.isDirectory()) continue
+      const fullPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      } else if (entry.isFile() && extensions.has(path.extname(entry.name))) {
+        results.push(fullPath)
+      }
+    }
+  }
+
+  walk(cwd)
+  return results
+}
+
+function extractRoutes(files: string[], _cwd: string): RouteInfo[] {
+  const routes: RouteInfo[] = []
+
+  for (const file of files) {
+    let code: string
+    try {
+      code = fs.readFileSync(file, "utf-8")
+    } catch {
+      continue
+    }
+
+    const routeArrayRe =
+      /(?:createRouter\s*\(\s*\[|(?:const|let)\s+routes\s*(?::\s*RouteRecord\[\])?\s*=\s*\[)([\s\S]*?)\]/g
+    let match: RegExpExecArray | null
+    for (match = routeArrayRe.exec(code); match; match = routeArrayRe.exec(code)) {
+      const block = match[1] ?? ""
+      const routeObjRe = /path\s*:\s*["']([^"']+)["']/g
+      let routeMatch: RegExpExecArray | null
+      for (routeMatch = routeObjRe.exec(block); routeMatch; routeMatch = routeObjRe.exec(block)) {
+        const routePath = routeMatch[1] ?? ""
+        const surroundingStart = Math.max(0, routeMatch.index - 50)
+        const surroundingEnd = Math.min(block.length, routeMatch.index + 200)
+        const surrounding = block.slice(surroundingStart, surroundingEnd)
+
+        routes.push({
+          path: routePath,
+          name: surrounding.match(/name\s*:\s*["']([^"']+)["']/)?.[1],
+          hasLoader: /loader\s*:/.test(surrounding),
+          hasGuard: /beforeEnter\s*:|beforeLeave\s*:/.test(surrounding),
+          params: extractParams(routePath),
+        })
+      }
+    }
+  }
+
+  return routes
+}
+
+function extractComponents(files: string[], cwd: string): ComponentInfo[] {
+  const components: ComponentInfo[] = []
+
+  for (const file of files) {
+    let code: string
+    try {
+      code = fs.readFileSync(file, "utf-8")
+    } catch {
+      continue
+    }
+
+    const componentRe =
+      /(?:export\s+)?(?:const|function)\s+([A-Z]\w*)\s*(?::\s*ComponentFn<[^>]+>\s*)?=?\s*\(?(?:\s*\{?\s*([^)]*?)\s*\}?\s*)?\)?\s*(?:=>|{)/g
+    let match: RegExpExecArray | null
+
+    for (match = componentRe.exec(code); match; match = componentRe.exec(code)) {
+      const name = match[1] ?? "Unknown"
+      const propsStr = match[2] ?? ""
+      const props = propsStr
+        .split(/[,;]/)
+        .map((p) => p.trim().replace(/[{}]/g, "").trim().split(":")[0]?.split("=")[0]?.trim() ?? "")
+        .filter((p) => p && p !== "props")
+
+      const bodyStart = match.index + match[0].length
+      const body = code.slice(bodyStart, Math.min(code.length, bodyStart + 2000))
+      const signalNames: string[] = []
+      const signalRe = /(?:const|let)\s+(\w+)\s*=\s*signal\s*[<(]/g
+      let sigMatch: RegExpExecArray | null
+      for (sigMatch = signalRe.exec(body); sigMatch; sigMatch = signalRe.exec(body)) {
+        if (sigMatch[1]) signalNames.push(sigMatch[1])
+      }
+
+      components.push({
+        name,
+        file: path.relative(cwd, file),
+        hasSignals: signalNames.length > 0,
+        signalNames,
+        props,
+      })
+    }
+  }
+
+  return components
+}
+
+function extractIslands(files: string[], cwd: string): IslandInfo[] {
+  const islands: IslandInfo[] = []
+
+  for (const file of files) {
+    let code: string
+    try {
+      code = fs.readFileSync(file, "utf-8")
+    } catch {
+      continue
+    }
+
+    const islandRe =
+      /island\s*\(\s*\(\)\s*=>\s*import\(.+?\)\s*,\s*\{[^}]*name\s*:\s*["']([^"']+)["'][^}]*?(?:hydrate\s*:\s*["']([^"']+)["'])?[^}]*\}/g
+    let match: RegExpExecArray | null
+    for (match = islandRe.exec(code); match; match = islandRe.exec(code)) {
+      if (match[1]) {
+        islands.push({
+          name: match[1],
+          file: path.relative(cwd, file),
+          hydrate: match[2] ?? "load",
+        })
+      }
+    }
+  }
+
+  return islands
+}
+
+function extractParams(routePath: string): string[] {
+  const params: string[] = []
+  const paramRe = /:(\w+)\??/g
+  let match: RegExpExecArray | null
+  for (match = paramRe.exec(routePath); match; match = paramRe.exec(routePath)) {
+    if (match[1]) params.push(match[1])
+  }
+  return params
+}
+
+function readVersion(cwd: string): string {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"))
+    const deps: Record<string, unknown> = { ...pkg.dependencies, ...pkg.devDependencies }
+    for (const [name, ver] of Object.entries(deps)) {
+      if (name.startsWith("@pyreon/") && typeof ver === "string") return ver.replace(/^[\^~]/, "")
+    }
+    return (pkg.version as string) || "unknown"
+  } catch {
+    return "unknown"
+  }
+}

package/src/tests/api-reference.test.ts

@@ -0,0 +1,14 @@
+import { API_REFERENCE } from "../api-reference"
+
+describe("api-reference", () => {
+  it("has entries", () => {
+    expect(Object.keys(API_REFERENCE).length).toBeGreaterThan(0)
+  })
+
+  it("entries have required fields", () => {
+    for (const [key, entry] of Object.entries(API_REFERENCE)) {
+      expect(entry.signature, `${key} missing signature`).toBeTruthy()
+      expect(entry.example, `${key} missing example`).toBeTruthy()
+    }
+  })
+})

package/src/tests/project-scanner.test.ts

@@ -0,0 +1,294 @@
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import { generateContext } from "../project-scanner"
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pyreon-scanner-"))
+}
+
+function writeFile(dir: string, relPath: string, content: string): void {
+  const full = path.join(dir, relPath)
+  fs.mkdirSync(path.dirname(full), { recursive: true })
+  fs.writeFileSync(full, content, "utf-8")
+}
+
+describe("generateContext", () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it("returns correct framework and version from @pyreon dependency", () => {
+    writeFile(
+      tmpDir,
+      "package.json",
+      JSON.stringify({ dependencies: { "@pyreon/core": "^1.2.3" } }),
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.framework).toBe("pyreon")
+    expect(ctx.version).toBe("1.2.3")
+    expect(ctx.generatedAt).toBeTruthy()
+  })
+
+  it("falls back to package version when no @pyreon dep", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "0.5.0" }))
+    const ctx = generateContext(tmpDir)
+    expect(ctx.version).toBe("0.5.0")
+  })
+
+  it("returns unknown version when no package.json", () => {
+    const ctx = generateContext(tmpDir)
+    expect(ctx.version).toBe("unknown")
+  })
+
+  it("extracts routes from createRouter calls", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+import { createRouter } from "@pyreon/router"
+const router = createRouter([
+  { path: "/", component: Home },
+  { path: "/about", component: About },
+])
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes).toHaveLength(2)
+    expect(ctx.routes[0]?.path).toBe("/")
+    expect(ctx.routes[1]?.path).toBe("/about")
+  })
+
+  it("extracts routes from routes variable", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/routes.ts",
+      `
+const routes = [
+  { path: "/home", component: Home },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes).toHaveLength(1)
+    expect(ctx.routes[0]?.path).toBe("/home")
+  })
+
+  it("extracts route params", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+const routes = [
+  { path: "/users/:id/posts/:postId" },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes[0]?.params).toEqual(["id", "postId"])
+  })
+
+  it("extracts optional route params", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+const routes = [
+  { path: "/search/:query?" },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes[0]?.params).toEqual(["query"])
+  })
+
+  it("detects loaders and guards", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+const routes = [
+  { path: "/dash", loader: fetchData, beforeEnter: authGuard },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes[0]?.hasLoader).toBe(true)
+    expect(ctx.routes[0]?.hasGuard).toBe(true)
+  })
+
+  it("detects beforeLeave guard", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+const routes = [
+  { path: "/form", beforeLeave: confirmLeave },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes[0]?.hasGuard).toBe(true)
+  })
+
+  it("extracts route names", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/router.ts",
+      `
+const routes = [
+  { path: "/profile", name: "profile", component: Profile },
+]
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes[0]?.name).toBe("profile")
+  })
+
+  it("extracts component names with props", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/Button.tsx",
+      `
+export function Button(props: { label: string; disabled: boolean }) {
+  return <button>{props.label}</button>
+}
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.components).toHaveLength(1)
+    expect(ctx.components[0]?.name).toBe("Button")
+    expect(ctx.components[0]?.file).toBe("src/Button.tsx")
+  })
+
+  it("detects signals in components", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/Counter.tsx",
+      `
+function Counter() {
+  const count = signal<number>(0)
+  const name = signal<string>("hello")
+  return <div>{count()}</div>
+}
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.components[0]?.hasSignals).toBe(true)
+    expect(ctx.components[0]?.signalNames).toEqual(["count", "name"])
+  })
+
+  it("reports no signals when none present", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/Static.tsx",
+      `
+function Static() {
+  return <div>hello</div>
+}
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.components[0]?.hasSignals).toBe(false)
+    expect(ctx.components[0]?.signalNames).toEqual([])
+  })
+
+  it("extracts island declarations with hydrate strategy", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/islands.ts",
+      `
+const Counter = island(() => import("./Counter"), { name: "Counter", hydrate: "visible" })
+const Nav = island(() => import("./Nav"), { name: "Nav", hydrate: "idle" })
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.islands).toHaveLength(2)
+    expect(ctx.islands[0]?.name).toBe("Counter")
+    expect(ctx.islands[1]?.name).toBe("Nav")
+  })
+
+  it("defaults hydrate to load when not specified", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/islands.ts",
+      `
+const Widget = island(() => import("./Widget"), { name: "Widget" })
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.islands[0]?.hydrate).toBe("load")
+  })
+
+  it("returns empty arrays for empty project", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    const ctx = generateContext(tmpDir)
+    expect(ctx.routes).toEqual([])
+    expect(ctx.components).toEqual([])
+    expect(ctx.islands).toEqual([])
+  })
+
+  it("skips node_modules and dist directories", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "node_modules/@pyreon/core/src/index.ts",
+      `function Internal() { return null }`,
+    )
+    writeFile(tmpDir, "dist/bundle.ts", `function Bundled() { return null }`)
+    writeFile(tmpDir, "src/App.tsx", `function App() { return <div /> }`)
+    const ctx = generateContext(tmpDir)
+    expect(ctx.components).toHaveLength(1)
+    expect(ctx.components[0]?.name).toBe("App")
+  })
+
+  it("handles unreadable directories gracefully", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(tmpDir, "src/App.tsx", `function App() { return <div /> }`)
+    const badDir = path.join(tmpDir, "restricted")
+    fs.mkdirSync(badDir)
+    fs.chmodSync(badDir, 0o000)
+
+    try {
+      const ctx = generateContext(tmpDir)
+      expect(ctx.components).toHaveLength(1)
+      expect(ctx.components[0]?.name).toBe("App")
+    } finally {
+      fs.chmodSync(badDir, 0o755)
+    }
+  })
+
+  it("extracts const arrow function components", () => {
+    writeFile(tmpDir, "package.json", JSON.stringify({ version: "1.0.0" }))
+    writeFile(
+      tmpDir,
+      "src/Card.tsx",
+      `
+export const Card = (props: CardProps) => {
+  return <div>{props.title}</div>
+}
+`,
+    )
+    const ctx = generateContext(tmpDir)
+    expect(ctx.components).toHaveLength(1)
+    expect(ctx.components[0]?.name).toBe("Card")
+  })
+})