Doc-parser

Functions

`parseDocumentedElements`

function parseDocumentedElements(docsDir: string): DocumentedElement[]

TypeScript

Use parseDocumentedElements to load and parse all previously generated documentation from a directory into structured objects you can query, transform, or render programmatically.

Reach for this when you've already run skrypt generate and want to work with the output in code — for example, to build a custom search index, validate coverage, or feed docs into another pipeline without re-running the generator.

It recursively finds every Markdown file under docsDir and extracts the documented API elements from each one, returning them as a flat array. The directory you pass should be the same -o output path you used with skrypt generate.

Parameters

Name	Type	Required	Description
`docsDir`	`string`	Yes	Path to the directory where `skrypt generate` wrote its output. Relative paths are resolved from the current working directory.

Returns

Returns a flat DocumentedElement[] array — one entry per documented API element found across all Markdown files in the directory. Each element carries the name, description, parameters, return type, and source metadata extracted during generation. Pass the array to your own rendering logic, filter it by element type, or diff it against a previous snapshot to detect undocumented additions.

Heads up

This reads from already-generated Markdown files — it does not re-scan your source code. If your source has changed since the last skrypt generate run, the results will be stale.
Returns an empty array (not an error) if docsDir exists but contains no Markdown files, so check result.length if you expect output.

Example:

import { readFileSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'fs'
import { join, extname } from 'path'
import { tmpdir } from 'os'

// Inline types — not imported from autodocs
interface DocumentedElement {
  name: string
  description: string
  filePath: string
  params: { name: string; type: string }[]
  returnType: string
}

// Self-contained implementation matching autodocs behavior
function findMarkdownFiles(dir: string): string[] {
  const results: string[] = []
  for (const entry of readdirSync(dir)) {
    const full = join(dir, entry)
    if (statSync(full).isDirectory()) {
      results.push(...findMarkdownFiles(full))
    } else if (extname(entry) === '.md' || extname(entry) === '.mdx') {
      results.push(full)
    }
  }
  return results
}

function parseDocumentedElements(docsDir: string): DocumentedElement[] {
  const files = findMarkdownFiles(docsDir)
  const elements: DocumentedElement[] = []

  for (const filePath of files) {
    const content = readFileSync(filePath, 'utf-8')
    // Extract name from first H2 heading
    const nameMatch = content.match(/^## (.+)$/m)
    // Extract description from first paragraph after heading
    const descMatch = content.match(/^## .+\n\n(.+)$/m)
    if (nameMatch) {
      elements.push({
        name: nameMatch[1].trim(),
        description: descMatch ? descMatch[1].trim() : '',
        filePath,
        params: [],
        returnType: 'unknown',
      })
    }
  }

  return elements
}

// Set up a temporary docs directory simulating `skrypt generate` output
const docsDir = join(tmpdir(), 'skrypt-docs-example')
mkdirSync(join(docsDir, 'auth'), { recursive: true })
mkdirSync(join(docsDir, 'payments'), { recursive: true })

writeFileSync(join(docsDir, 'auth', 'createUser.md'), `## createUser\n\nCreate a new user and return their session token.\n`)
writeFileSync(join(docsDir, 'auth', 'revokeToken.md'), `## revokeToken\n\nInvalidate an existing session token immediately.\n`)
writeFileSync(join(docsDir, 'payments', 'chargeCard.md'), `## chargeCard\n\nCharge a saved payment method and return a transaction ID.\n`)

try {
  const elements = parseDocumentedElements(docsDir)

  console.log(`Found ${elements.length} documented elements:\n`)
  for (const el of elements) {
    console.log(`  ${el.name}: ${el.description}`)
  }
  // Expected output:
  // Found 3 documented elements:
  //   createUser: Create a new user and return their session token.
  //   revokeToken: Invalidate an existing session token immediately.
  //   chargeCard: Charge a saved payment method and return a transaction ID.
} catch (err) {
  console.error('Failed to parse docs directory:', err)
}

TypeScript

audit — parser

Doc-parser

Functions

parseDocumentedElements

`parseDocumentedElements`