Add function references module

Author: roxblnfk

.vitepress/config.mts

@@ -6,8 +6,10 @@ import { isBlogPath } from './locales'
 import { faqPlugin } from './faq'
 import { infoBlockPlugin } from './info-block'
 import { funcBlockPlugin } from './func-block'
+import { preScanSignatures } from './func-registry'
 
 const baseUrl = 'https://php-testo.github.io'
+const srcDir = fileURLToPath(new URL('..', import.meta.url))
 
 export default defineConfig({
   title: 'Testo',
@@ -18,6 +20,7 @@ export default defineConfig({
 
   markdown: {
     config: (md) => {
+      preScanSignatures(srcDir)
       md.use(faqPlugin)
       md.use(infoBlockPlugin)
       md.use(funcBlockPlugin)

.vitepress/func-block.ts

@@ -18,6 +18,7 @@
  */
 import type MarkdownIt from 'markdown-it'
 import { getLocaleByPath, type LocaleConfig } from './locales'
+import { getEntry } from './func-registry'
 
 interface Param {
   name: string
@@ -59,12 +60,68 @@ export function funcBlockPlugin(md: MarkdownIt) {
     return true
   })
 
-  md.renderer.rules['func_block'] = (tokens, idx) => {
-    return renderFuncBlock(md, tokens[idx].content, tokens[idx].meta?.locale)
+  md.renderer.rules['func_block'] = (tokens, idx, options, env) => {
+    return renderFuncBlock(md, tokens[idx].content, tokens[idx].meta?.locale, env)
+  }
+
+  // Inline rule: parse <func>..FQN..</func> references
+  md.inline.ruler.before('html_inline', 'func_ref', (state, silent) => {
+    if (state.src.slice(state.pos, state.pos + 6) !== '<func>') return false
+
+    const closeIdx = state.src.indexOf('</func>', state.pos + 6)
+    if (closeIdx === -1) return false
+
+    if (silent) return true
+
+    const token = state.push('func_ref', '', 0)
+    token.content = state.src.slice(state.pos + 6, closeIdx).trim()
+
+    const relativePath = state.env?.relativePath || ''
+    token.meta = { locale: getLocaleByPath('/' + relativePath) }
+
+    state.pos = closeIdx + 7
+    return true
+  })
+
+  // Renderer for <func> inline references
+  md.renderer.rules['func_ref'] = (tokens, idx) => {
+    const token = tokens[idx]
+    const rawFqn = token.content
+    const locale = token.meta?.locale
+
+    // Build display name: strip namespace, keep ()
+    const displayFqn = stripNamespace(rawFqn).display
+
+    // Look up in registry
+    const entry = getEntry(locale?.code ?? 'en', rawFqn)
+
+    if (entry) {
+      const sigHtml = highlightSignature(md, entry.signature)
+      // Highlight inline display using the full signature, then extract the short portion
+      const displayHtml = highlightFuncRef(md, displayFqn, entry.signature)
+      const shortHtml = entry.short ? md.renderInline(entry.short) : ''
+
+      const tooltip = `<span class="func-ref-tooltip">`
+        + `<code class="func-ref-tooltip-sig vp-code">${sigHtml}</code>`
+        + (shortHtml ? `<span class="func-ref-tooltip-short">${shortHtml}</span>` : '')
+        + `</span>`
+
+      // Link only if signature has a navigable anchor (h > 0)
+      if (entry.hasAnchor) {
+        const href = entry.pagePath + '#' + entry.slug
+        return `<a href="${href}" class="func-ref vp-code">${displayHtml}${tooltip}</a>`
+      }
+
+      // Tooltip without link
+      return `<span class="func-ref vp-code">${displayHtml}${tooltip}</span>`
+    }
+
+    // No match in registry — render as plain inline code
+    return `<code>${escapeHtml(displayFqn)}</code>`
   }
 }
 
-function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig): string {
+function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig, env?: any): string {
   // Parse name attribute (the full signature)
   const nameMatch = raw.match(/<signature\s+[^>]*name="([^"]*)"/)
   if (!nameMatch) return ''
@@ -122,12 +179,12 @@ function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig): st
 
   // Build HTML output
   const sigHtml = highlightSignature(md, display)
-  const descHtml = description ? md.render(description) : ''
+  const descHtml = description ? md.render(description, env) : ''
 
   // Compact mode: everything inline, no section headers
   if (compact) {
     const shortHtml = short ? md.renderInline(short) : ''
-    const compactDescHtml = description ? md.render(description) : ''
+    const compactDescHtml = description ? md.render(description, env) : ''
 
     let html = '<div class="func-compact">'
 
@@ -146,7 +203,7 @@ function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig): st
     }
 
     for (const ex of examples) {
-      html += `<div class="func-compact-example">${md.render(ex)}</div>`
+      html += `<div class="func-compact-example">${md.render(ex, env)}</div>`
     }
 
     html += '</div>\n'
@@ -189,7 +246,7 @@ function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig): st
     html += '  <div class="func-section">\n'
     html += `    <p class="func-section-title">${escapeHtml(examplesLabel)}</p>\n`
     for (const ex of examples) {
-      html += `    <div class="func-example">${md.render(ex)}</div>\n`
+      html += `    <div class="func-example">${md.render(ex, env)}</div>\n`
     }
     html += '  </div>\n'
   }
@@ -243,6 +300,15 @@ function extractShortName(display: string): string {
   return funcMatch ? funcMatch[1] : display
 }
 
+/**
+ * Highlights a short func reference (e.g. `Assert::blank()`) by wrapping it
+ * as a PHP static call expression so Shiki can tokenize it properly.
+ */
+function highlightFuncRef(md: MarkdownIt, displayFqn: string, _fullSignature: string): string {
+  // displayFqn is e.g. "Assert::blank()" — valid PHP as a static method call
+  return highlightSignature(md, displayFqn) || escapeHtml(displayFqn)
+}
+
 /**
  * Highlights a PHP signature string using Shiki via markdown-it's highlight option.
  */

.vitepress/func-registry.ts

@@ -0,0 +1,145 @@
+/**
+ * Signature registry for cross-referencing `<func>` inline tags.
+ *
+ * Pre-scans all .md files to collect `<signature>` blocks with FQN names and h > 0,
+ * then provides lookup for inline `<func>` references to generate links and tooltips.
+ */
+import { readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { getLocaleByPath } from './locales'
+
+export interface RegistryEntry {
+  fqn: string         // Normalized: \Testo\Assert::blank
+  slug: string        // Anchor: testo-assert--blank
+  pagePath: string    // URL path: /docs/plugins/assert or /ru/docs/plugins/assert
+  signature: string   // Display: Assert::blank(mixed $actual, string $message = ''): void
+  short: string       // One-liner description (raw markdown)
+  hasAnchor: boolean  // true if h > 0 — linkable heading exists
+}
+
+// locale code -> normalized FQN -> entry
+const registry = new Map<string, Map<string, RegistryEntry>>()
+
+/**
+ * Normalize FQN by stripping arguments and return type.
+ * `\Testo\Assert::blank(mixed $actual): void` → `\Testo\Assert::blank`
+ * `\Testo\Assert::blank()` → `\Testo\Assert::blank`
+ */
+export function normalizeFqn(raw: string): string {
+  const parenIdx = raw.indexOf('(')
+  let base = parenIdx !== -1 ? raw.slice(0, parenIdx) : raw
+  base = base.trim()
+  if (!base.startsWith('\\')) base = '\\' + base
+  return base
+}
+
+/**
+ * Build slug from FQN signature (same logic as func-block.ts buildSlug).
+ */
+function buildSlugFromFqn(signature: string): string {
+  const fqnMatch = signature.match(/^\\?(.+?)\(/)
+  if (fqnMatch) {
+    return fqnMatch[1]
+      .replace(/\\/g, '-')
+      .replace(/::/g, '--')
+      .replace(/->/g, '--')
+      .toLowerCase()
+  }
+  const methodMatch = signature.match(/^([A-Za-z_]\w*)/)
+  return methodMatch ? methodMatch[1].toLowerCase() : 'unknown'
+}
+
+/**
+ * Strip namespace prefix from signature for display.
+ */
+function stripNamespaceForDisplay(signature: string): string {
+  const match = signature.match(/^\\?(?:[A-Za-z_]\w*\\)+(.*)$/)
+  return match ? match[1] : signature
+}
+
+/**
+ * Pre-scan all .md files in srcDir to populate the signature registry.
+ * Call once before markdown-it processes any pages.
+ */
+export function preScanSignatures(srcDir: string): void {
+  registry.clear()
+  const mdFiles = collectMdFiles(srcDir)
+
+  // Match all <signature> blocks with a name attribute
+  const sigRe = /<signature\s+([^>]*)>([\s\S]*?)<\/signature>/g
+
+  for (const filePath of mdFiles) {
+    const content = readFileSync(filePath, 'utf-8')
+    const relPath = relative(srcDir, filePath).replace(/\\/g, '/')
+    const locale = getLocaleByPath('/' + relPath)
+    const pagePath = '/' + relPath.replace(/\.md$/, '').replace(/\/index$/, '/')
+
+    if (!registry.has(locale.code)) {
+      registry.set(locale.code, new Map())
+    }
+    const localeMap = registry.get(locale.code)!
+
+    sigRe.lastIndex = 0
+    let match: RegExpExecArray | null
+    while ((match = sigRe.exec(content)) !== null) {
+      const attrs = match[1]
+      const body = match[2]
+
+      // Extract name attribute (required)
+      const nameMatch = attrs.match(/\bname="([^"]*)"/)
+      if (!nameMatch) continue
+      const signature = nameMatch[1]
+
+      // Only collect FQN signatures (starting with \)
+      if (!signature.startsWith('\\')) continue
+
+      const fqn = normalizeFqn(signature)
+
+      // Skip if already registered (first wins)
+      if (localeMap.has(fqn)) continue
+
+      // Check if heading level > 0 (has a navigable anchor)
+      const hMatch = attrs.match(/\bh="([1-6])"/)
+      const hasAnchor = !!hMatch
+
+      const shortMatch = body.match(/<short>([\s\S]*?)<\/short>/)
+      const short = shortMatch ? shortMatch[1].trim() : ''
+
+      localeMap.set(fqn, {
+        fqn,
+        slug: buildSlugFromFqn(signature),
+        pagePath,
+        signature: stripNamespaceForDisplay(signature),
+        short,
+        hasAnchor,
+      })
+    }
+  }
+}
+
+/**
+ * Look up a signature entry by FQN and locale.
+ */
+export function getEntry(localeCode: string, rawFqn: string): RegistryEntry | undefined {
+  const fqn = normalizeFqn(rawFqn)
+  return registry.get(localeCode)?.get(fqn)
+}
+
+/**
+ * Recursively collect all .md files in a directory.
+ */
+function collectMdFiles(dir: string): string[] {
+  const results: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry)
+    const stat = statSync(fullPath)
+    if (stat.isDirectory()) {
+      // Skip node_modules, .vitepress, etc.
+      if (entry.startsWith('.') || entry === 'node_modules') continue
+      results.push(...collectMdFiles(fullPath))
+    } else if (entry.endsWith('.md') && entry !== 'CLAUDE.md' && entry !== 'README.md') {
+      results.push(fullPath)
+    }
+  }
+  return results
+}

.vitepress/theme/index.ts

@@ -12,6 +12,57 @@ import BlogPostHeader from './BlogPostHeader.vue'
 import { isBlogPath, getBlogBackLink, localNavBackKey } from '../locales'
 import './style.css'
 
+function setupFuncRefTooltips() {
+  document.addEventListener('mouseenter', (e) => {
+    const ref = (e.target as Element).closest?.('.func-ref')
+    if (!ref) return
+
+    const tip = ref.querySelector('.func-ref-tooltip') as HTMLElement
+    if (!tip) return
+
+    const rect = ref.getBoundingClientRect()
+    const gap = 8
+
+    // Reset and show with default max-width for measuring
+    tip.style.left = '0'
+    tip.style.top = '0'
+    tip.style.maxWidth = ''
+    tip.classList.add('is-visible')
+
+    // If signature overflows at 480px, expand to fit it
+    const sig = tip.querySelector('.func-ref-tooltip-sig') as HTMLElement
+    if (sig && sig.scrollWidth > sig.clientWidth) {
+      const needed = sig.scrollWidth + 28  // 14px padding * 2
+      tip.style.maxWidth = Math.min(needed, window.innerWidth - 16) + 'px'
+    }
+
+    // Measure tooltip after adjustment
+    const tipRect = tip.getBoundingClientRect()
+
+    // Vertical: above if fits, below otherwise
+    let top = rect.top - tipRect.height - gap
+    if (top < 0) top = rect.bottom + gap
+    tip.style.top = top + 'px'
+
+    // Horizontal: center on the func element, clamp to viewport
+    const refCenter = rect.left + rect.width / 2
+    let left = refCenter - tipRect.width / 2
+    if (left + tipRect.width > window.innerWidth - 8) {
+      left = window.innerWidth - tipRect.width - 8
+    }
+    if (left < 8) left = 8
+    tip.style.left = left + 'px'
+  }, true)
+
+  document.addEventListener('mouseleave', (e) => {
+    const ref = (e.target as Element).closest?.('.func-ref')
+    if (!ref) return
+
+    const tip = ref.querySelector('.func-ref-tooltip') as HTMLElement
+    if (tip) tip.classList.remove('is-visible')
+  }, true)
+}
+
 export default {
   extends: DefaultTheme,
   Layout: defineComponent({
@@ -29,10 +80,14 @@ export default {
       })
     },
   }),
-  enhanceApp({ app }) {
+  enhanceApp({ app, router }) {
     app.component('CodeTabs', CodeTabs)
     app.component('JetBrainsPluginButton', JetBrainsPluginButton)
     app.component('JetBrainsPlugin', JetBrainsPlugin)
     app.component('BlogPosts', BlogPosts)
+
+    if (typeof window !== 'undefined') {
+      setupFuncRefTooltips()
+    }
   },
 } satisfies Theme