Add attributes signatures support; update docs about Inline plugin

Author: roxblnfk

.vitepress/config.mts

@@ -89,14 +89,14 @@ gtag('config', 'G-VYGDN3X0PR');`],
               text: 'Plugins',
               link: '/docs/plugins.md',
               items: [
-                { text: 'Test Attribute', link: '/docs/plugins/test.md' },
                 { text: 'Assert & Expect', link: '/docs/plugins/assert.md' },
-                { text: 'Naming Conventions', link: '/docs/plugins/convention.md' },
                 { text: 'Inline Tests', link: '/docs/plugins/inline.md' },
                 { text: 'Data Providers', link: '/docs/plugins/data.md' },
-                { text: 'Lifecycle', link: '/docs/plugins/lifecycle.md' },
                 { text: 'Retry', link: '/docs/plugins/retry.md' },
-                { text: 'Benchmarks', link: '/docs/plugins/bench.md' },
+                { text: 'Bench', link: '/docs/plugins/bench.md' },
+                { text: '\#[Test]', link: '/docs/plugins/test.md' },
+                { text: 'Lifecycle', link: '/docs/plugins/lifecycle.md' },
+                { text: 'Convention', link: '/docs/plugins/convention.md' },
               ],
             },
             {

.vitepress/func-block.ts

@@ -1,17 +1,18 @@
 /**
- * Function signature block plugin for markdown-it.
+ * Function/attribute signature block plugin for markdown-it.
  *
  * Tags:
- *   <signature> — API reference card with Shiki-highlighted PHP signature
- *   <func>      — inline/block cross-reference to a <signature> block (tooltip + link)
+ *   <signature> — API reference card with Shiki-highlighted PHP signature (functions and attributes)
+ *   <func>      — inline/block cross-reference to a function <signature> (tooltip + link)
+ *   <attr>      — inline/block cross-reference to an attribute <signature> (tooltip + link)
  *   <class>     — inline/block tag rendering short class name with FQN tooltip
  *   <plugin>    — inline/block link to a plugin page by name (from plugin-block registry)
  */
 import type MarkdownIt from 'markdown-it'
 import type StateInline from 'markdown-it/lib/rules_inline/state_inline.mjs'
 import type StateBlock from 'markdown-it/lib/rules_block/state_block.mjs'
 import { getLocaleByPath, type LocaleConfig } from './locales'
-import { getEntry } from './func-registry'
+import { getEntry, getAttrEntry } from './func-registry'
 import { getPluginEntry } from './plugin-block'
 
 interface Param {
@@ -84,9 +85,17 @@ function highlightSignature(md: MarkdownIt, signature: string): string {
 
 // ─── Inline tag renderers (return HTML string) ──────────
 
-function renderFuncRefHtml(md: MarkdownIt, rawFqn: string, locale?: LocaleConfig): string {
-  const displayFqn = stripNamespace(rawFqn).display
-  const entry = getEntry(locale?.code ?? 'en', rawFqn)
+function renderRefHtml(
+  md: MarkdownIt,
+  rawFqn: string,
+  locale: LocaleConfig | undefined,
+  lookupEntry: typeof getEntry,
+  wrapDisplay?: (display: string) => string,
+  extraClass?: string,
+): string {
+  const baseDisplay = stripNamespace(rawFqn).display
+  const displayFqn = wrapDisplay ? wrapDisplay(baseDisplay) : baseDisplay
+  const entry = lookupEntry(locale?.code ?? 'en', rawFqn)
 
   if (entry) {
     const sigHtml = highlightSignature(md, entry.signature)
@@ -98,17 +107,27 @@ function renderFuncRefHtml(md: MarkdownIt, rawFqn: string, locale?: LocaleConfig
       + (shortHtml ? `<span class="func-ref-tooltip-short">${shortHtml}</span>` : '')
       + `</span>`
 
+    const cls = extraClass ? `func-ref ${extraClass} vp-code` : 'func-ref vp-code'
+
     if (entry.hasAnchor) {
       const href = entry.pagePath + '#' + entry.slug
-      return `<a href="${href}" class="func-ref vp-code">${displayHtml}${tooltip}</a>`
+      return `<a href="${href}" class="${cls}">${displayHtml}${tooltip}</a>`
     }
 
-    return `<span class="func-ref vp-code">${displayHtml}${tooltip}</span>`
+    return `<span class="${cls}">${displayHtml}${tooltip}</span>`
   }
 
   return `<code>${escapeHtml(displayFqn)}</code>`
 }
 
+function renderFuncRefHtml(md: MarkdownIt, rawFqn: string, locale?: LocaleConfig): string {
+  return renderRefHtml(md, rawFqn, locale, getEntry)
+}
+
+function renderAttrRefHtml(md: MarkdownIt, rawFqn: string, locale?: LocaleConfig): string {
+  return renderRefHtml(md, rawFqn, locale, getAttrEntry, (d) => '#[' + d + ']', 'attr-ref')
+}
+
 function renderKlassRefHtml(fqn: string): string {
   const short = escapeHtml(stripNamespaceShort(fqn))
   const tooltip = `<span class="func-ref-tooltip"><code class="func-ref-tooltip-sig vp-code">${escapeHtml(fqn)}</code></span>`
@@ -231,6 +250,12 @@ export function funcBlockPlugin(md: MarkdownIt) {
     return renderPluginRefHtml(name, locale)
   })
 
+  registerBlockParagraphTag(md, 'attr_line', 'attr', (rawFqn, state) => {
+    const relativePath = state.env?.relativePath || ''
+    const locale = getLocaleByPath('/' + relativePath)
+    return renderAttrRefHtml(md, rawFqn, locale)
+  })
+
   // ── <signature> block rule (multi-line) ──
 
   md.block.ruler.before('html_block', 'func_block', (state, startLine, endLine, silent) => {
@@ -274,6 +299,7 @@ export function funcBlockPlugin(md: MarkdownIt) {
   registerInlineTag(md, 'func', 'func_ref', { before: 'html_inline' }, { withLocale: true })
   registerInlineTag(md, 'class', 'class_ref', { after: 'func_ref' })
   registerInlineTag(md, 'plugin', 'plugin_ref', { after: 'class_ref' }, { withLocale: true })
+  registerInlineTag(md, 'attr', 'attr_ref', { after: 'plugin_ref' }, { withLocale: true })
 
   // ── Inline renderers ──
 
@@ -290,6 +316,11 @@ export function funcBlockPlugin(md: MarkdownIt) {
     const { content, meta } = tokens[idx]
     return renderPluginRefHtml(content, meta?.locale)
   }
+
+  md.renderer.rules['attr_ref'] = (tokens, idx) => {
+    const { content, meta } = tokens[idx]
+    return renderAttrRefHtml(md, content, meta?.locale)
+  }
 }
 
 // ─── <signature> block renderer ─────────────────────────
@@ -329,11 +360,15 @@ function renderFuncBlock(md: MarkdownIt, raw: string, locale?: LocaleConfig, env
     examples.push(em[1].trim())
   }
 
-  const { display } = stripNamespace(signature)
-  const shortName = extractShortName(display)
+  const isAttr = signature.startsWith('#[')
+  const innerSig = isAttr ? signature.slice(2, -1) : signature
+  const { display: innerDisplay } = stripNamespace(innerSig)
+  const display = isAttr ? '#[' + innerDisplay + ']' : innerDisplay
+  const rawShortName = extractShortName(innerDisplay)
+  const shortName = isAttr ? '#[' + rawShortName + ']' : rawShortName
   const paramsLabel = locale?.signatureParamsLabel ?? 'Parameters:'
   const examplesLabel = locale?.signatureExamplesLabel ?? 'Examples:'
-  const slug = buildSlug(signature)
+  const slug = buildSlug(innerSig)
   const sigHtml = highlightSignature(md, display)
 
   if (compact) {

.vitepress/func-registry.ts

@@ -1,8 +1,10 @@
 /**
- * Signature registry for cross-referencing `<func>` inline tags.
+ * Signature registry for cross-referencing `<func>` and `<attr>` 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.
+ * Pre-scans all .md files to collect `<signature>` blocks with FQN names,
+ * then provides lookup for inline references to generate links and tooltips.
+ * Function signatures (e.g. `\Testo\Assert::same(...)`) and attribute signatures
+ * (e.g. `#[\Testo\MyAttr(...)]`) are stored in separate registries.
  */
 import { readFileSync, readdirSync, statSync } from 'fs'
 import { join, relative } from 'path'
@@ -19,6 +21,7 @@ export interface RegistryEntry {
 
 // locale code -> normalized FQN -> entry
 const registry = new Map<string, Map<string, RegistryEntry>>()
+const attrRegistry = new Map<string, Map<string, RegistryEntry>>()
 
 /**
  * Normalize FQN by stripping arguments and return type.
@@ -63,6 +66,7 @@ function stripNamespaceForDisplay(signature: string): string {
  */
 export function preScanSignatures(srcDir: string): void {
   registry.clear()
+  attrRegistry.clear()
   const mdFiles = collectMdFiles(srcDir)
 
   // Match all <signature> blocks with a name attribute
@@ -74,11 +78,6 @@ export function preScanSignatures(srcDir: string): void {
     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) {
@@ -90,10 +89,20 @@ export function preScanSignatures(srcDir: string): void {
       if (!nameMatch) continue
       const signature = nameMatch[1]
 
+      // Detect attribute signatures: #[\Namespace\Attr(...)]
+      const isAttr = signature.startsWith('#[')
+      const innerSig = isAttr ? signature.slice(2, -1) : signature
+
       // Only collect FQN signatures (starting with \)
-      if (!signature.startsWith('\\')) continue
+      if (!innerSig.startsWith('\\')) continue
 
-      const fqn = normalizeFqn(signature)
+      const fqn = normalizeFqn(innerSig)
+      const targetRegistry = isAttr ? attrRegistry : registry
+
+      if (!targetRegistry.has(locale.code)) {
+        targetRegistry.set(locale.code, new Map())
+      }
+      const localeMap = targetRegistry.get(locale.code)!
 
       // Skip if already registered (first wins)
       if (localeMap.has(fqn)) continue
@@ -105,11 +114,13 @@ export function preScanSignatures(srcDir: string): void {
       const shortMatch = body.match(/<short>([\s\S]*?)<\/short>/)
       const short = shortMatch ? shortMatch[1].trim() : ''
 
+      const displaySig = stripNamespaceForDisplay(innerSig)
+
       localeMap.set(fqn, {
         fqn,
-        slug: buildSlugFromFqn(signature),
+        slug: buildSlugFromFqn(innerSig),
         pagePath,
-        signature: stripNamespaceForDisplay(signature),
+        signature: isAttr ? '#[' + displaySig + ']' : displaySig,
         short,
         hasAnchor,
       })
@@ -118,13 +129,21 @@ export function preScanSignatures(srcDir: string): void {
 }
 
 /**
- * Look up a signature entry by FQN and locale.
+ * Look up a function 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)
 }
 
+/**
+ * Look up an attribute signature entry by FQN and locale.
+ */
+export function getAttrEntry(localeCode: string, rawFqn: string): RegistryEntry | undefined {
+  const fqn = normalizeFqn(rawFqn)
+  return attrRegistry.get(localeCode)?.get(fqn)
+}
+
 /**
  * Recursively collect all .md files in a directory.
  */

blog/collider.md

@@ -29,7 +29,7 @@ Here's my reasoning:
 
 > The array solution should be slower than the `for` loop, since extra resources go into computing hashes for the hash table when creating the array, and more memory is needed for intermediate values.
 
-Let's verify this: we'll write the functions and add the `#[Bench]` attribute to one of them.
+Let's verify this: we'll write the functions and add the <attr>\Testo\Bench</attr> attribute to one of them.
 
 ```php
 #[Bench(
@@ -56,7 +56,7 @@ public static function sumInArray(int $a, int $b): int
 }
 ```
 
-With the `#[Bench]` attribute, we're telling Testo that:
+With the <attr>\Testo\Bench</attr> attribute, we're telling Testo that:
 - we want to compare the performance of the current function (`sumInCycle`) with another function (`sumInArray`);
 - both functions will receive the same arguments: `1` and `5_000`;
 - to measure execution time, each function will be called 100 times in a row (`calls: 100`).
@@ -94,7 +94,7 @@ Statistics comes to the rescue with the [coefficient of variation](https://en.wi
 The smaller this coefficient, the more stable the results.
 
 All we need to do is collect more data spread over time — that is, rerun the benchmarks multiple times.
-The `#[Bench]` attribute has an `iterations` parameter responsible for the number of benchmark reruns.
+The <attr>\Testo\Bench</attr> attribute has an `iterations` parameter responsible for the number of benchmark reruns.
 
 Let's set `iterations: 10` and rerun:
 

docs/cli-reference.md

@@ -156,7 +156,7 @@ Filter tests by type. If specified, only tests of the matching type are run.
 
 **Possible values:**
 - `test` — regular tests (methods in classes)
-- `inline` — [inline tests](plugins/inline.md) (tests via `#[TestInline]`)
+- `inline` — [inline tests](plugins/inline.md) (tests via <attr>\Testo\Inline\TestInline</attr>)
 - `bench` — [benchmarks](plugins/bench.md)
 
 **Examples:**

docs/getting-started.md

@@ -55,7 +55,7 @@ To learn more about configuration, visit the [Configuration](configuration.md) s
 
 ## Writing Your First Test
 
-Create a test class in the configured directory (e.g., `tests/Unit/MyFirstTest.php`) and add a method with the `#[Test]` attribute:
+Create a test class in the configured directory (e.g., `tests/Unit/MyFirstTest.php`) and add a method with the <attr>\Testo\Test</attr> attribute:
 
 ```php
 final class MyFirstTest
@@ -71,7 +71,7 @@ final class MyFirstTest
 }
 ```
 
-The `#[Test]` attribute marks the method as a test, and the <class>\Testo\Assert</class> facade checks assertions. More about test approaches, attributes, and conventions — in [Writing Tests](writing-tests.md).
+The <attr>\Testo\Test</attr> attribute marks the method as a test, and the <class>\Testo\Assert</class> facade checks assertions. More about test approaches, attributes, and conventions — in [Writing Tests](writing-tests.md).
 
 ## Running Tests
 

docs/plugins/assert.md

@@ -305,12 +305,12 @@ You can determine the type of the JSON value at the start, after which type-spec
 <short>Checks that the JSON object contains the given keys.</short>
 </signature>
 
-<signature h="4" name="\Testo\Assert\Api\Json\JsonStructure::assertPath(string $path, callable $callback): static">
+<signature compact h="4" name="\Testo\Assert\Api\Json\JsonStructure::assertPath(string $path, callable $callback): static">
 <short>Checks a nested value at the given path.</short>
 <description>The callback receives a `JsonAbstract` for the value at the specified path, allowing you to build nested assertion chains.</description>
 </signature>
 
-<signature h="4" name="\Testo\Assert\Api\Json\JsonCommon::matchesType(string $type): static">
+<signature compact h="4" name="\Testo\Assert\Api\Json\JsonCommon::matchesType(string $type): static">
 <short>Validates the JSON structure against a Psalm type.</short>
 <description>Accepts an extended Psalm type annotation — for example, `'array{foo: bool, bar?: non-empty-string}'` or `'list<array{id: positive-int}>'`.</description>
 </signature>