@bfra.me/doc-sync 0.1.0

package/src/parsers/readme-parser.ts

@@ -0,0 +1,334 @@
+/**
+ * @bfra.me/doc-sync/parsers/readme-parser - README Markdown parser with section extraction
+ */
+
+import type {Root, RootContent} from 'mdast'
+
+import type {ParseError, ParseResult, ReadmeContent, ReadmeSection} from '../types'
+
+import {err, ok} from '@bfra.me/es/result'
+import remarkParse from 'remark-parse'
+import {unified} from 'unified'
+
+/**
+ * Options for parsing README files
+ */
+export interface ReadmeParserOptions {
+  readonly extractSections?: boolean
+  readonly preserveRaw?: boolean
+}
+
+/**
+ * Parses a README markdown string into structured content
+ */
+export function parseReadme(
+  content: string,
+  options?: ReadmeParserOptions,
+): ParseResult<ReadmeContent> {
+  try {
+    const processor = unified().use(remarkParse)
+    const tree = processor.parse(content)
+
+    const title = extractTitle(tree)
+    const preamble = extractPreamble(tree)
+    const sections =
+      options?.extractSections === false ? ([] as readonly ReadmeSection[]) : extractSections(tree)
+
+    return ok({
+      ...(title !== undefined && {title}),
+      ...(preamble !== undefined && {preamble}),
+      sections,
+      raw: options?.preserveRaw === false ? '' : content,
+    })
+  } catch (error) {
+    return err({
+      code: 'INVALID_SYNTAX',
+      message: 'Failed to parse README content',
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+/**
+ * Parses a README file from the file system
+ */
+export async function parseReadmeFile(
+  filePath: string,
+  options?: ReadmeParserOptions,
+): Promise<ParseResult<ReadmeContent>> {
+  try {
+    const fs = await import('node:fs/promises')
+    const content = await fs.readFile(filePath, 'utf-8')
+    return parseReadme(content, options)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return err({
+        code: 'FILE_NOT_FOUND',
+        message: `README file not found: ${filePath}`,
+        filePath,
+        cause: error,
+      } satisfies ParseError)
+    }
+
+    return err({
+      code: 'READ_ERROR',
+      message: `Failed to read README file: ${filePath}`,
+      filePath,
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+function extractTitle(tree: Root): string | undefined {
+  for (const node of tree.children) {
+    if (node.type === 'heading' && node.depth === 1) {
+      return extractTextFromNode(node)
+    }
+  }
+  return undefined
+}
+
+function extractPreamble(tree: Root): string | undefined {
+  const preambleNodes: RootContent[] = []
+
+  for (const node of tree.children) {
+    if (node.type === 'heading') {
+      break
+    }
+    preambleNodes.push(node)
+  }
+
+  if (preambleNodes.length === 0) {
+    return undefined
+  }
+
+  const text = preambleNodes.map(extractTextFromNode).join('\n\n').trim()
+  return text.length > 0 ? text : undefined
+}
+
+function extractSections(tree: Root): readonly ReadmeSection[] {
+  const sections: ReadmeSection[] = []
+  const stack: {level: number; section: ReadmeSection & {children: ReadmeSection[]}}[] = []
+
+  for (let i = 0; i < tree.children.length; i++) {
+    const node = tree.children[i]
+
+    if (node !== undefined && node.type === 'heading') {
+      const heading = extractTextFromNode(node)
+      const level = node.depth
+      const content = extractSectionContent(tree, i + 1)
+
+      const newSection: ReadmeSection & {children: ReadmeSection[]} = {
+        heading,
+        level,
+        content,
+        children: [],
+      }
+
+      // Pop sections from stack that are at same or higher level
+      while (stack.length > 0 && (stack.at(-1)?.level ?? 0) >= level) {
+        stack.pop()
+      }
+
+      if (stack.length === 0) {
+        // Top-level section
+        sections.push(newSection)
+      } else {
+        // Nested section
+        const parent = stack.at(-1)
+        parent?.section.children.push(newSection)
+      }
+
+      stack.push({level, section: newSection})
+    }
+  }
+
+  return freezeSections(sections)
+}
+
+function freezeSections(sections: ReadmeSection[]): readonly ReadmeSection[] {
+  return sections.map(s => ({
+    heading: s.heading,
+    level: s.level,
+    content: s.content,
+    children: freezeSections([...s.children]),
+  }))
+}
+
+function extractSectionContent(tree: Root, startIndex: number): string {
+  const contentNodes: RootContent[] = []
+
+  for (let i = startIndex; i < tree.children.length; i++) {
+    const node = tree.children[i]
+    if (node === undefined || node.type === 'heading') {
+      break
+    }
+    contentNodes.push(node)
+  }
+
+  return contentNodes.map(serializeNode).join('\n\n').trim()
+}
+
+function extractTextFromNode(node: RootContent): string {
+  if ('value' in node && typeof node.value === 'string') {
+    return node.value
+  }
+
+  if ('children' in node && Array.isArray(node.children)) {
+    return (node.children as RootContent[]).map(extractTextFromNode).join('')
+  }
+
+  return ''
+}
+
+function serializeNode(node: RootContent): string {
+  if (node.type === 'paragraph') {
+    return extractTextFromNode(node)
+  }
+
+  if (node.type === 'heading') {
+    const prefix = '#'.repeat(node.depth)
+    return `${prefix} ${extractTextFromNode(node)}`
+  }
+
+  if (node.type === 'code') {
+    return `\`\`\`${node.lang ?? ''}\n${node.value}\n\`\`\``
+  }
+
+  if (node.type === 'blockquote') {
+    return (node.children as RootContent[]).map(c => `> ${serializeNode(c)}`).join('\n')
+  }
+
+  if (node.type === 'list') {
+    const items = node.children
+      .map((item, index) => {
+        if (item.type !== 'listItem') return ''
+        const prefix = node.ordered === true ? `${index + 1}. ` : '- '
+        const content = (item.children as RootContent[]).map(serializeNode).join('\n')
+        return `${prefix}${content}`
+      })
+      .filter(s => s.length > 0)
+    return items.join('\n')
+  }
+
+  if (node.type === 'thematicBreak') {
+    return '---'
+  }
+
+  if (node.type === 'html') {
+    return node.value
+  }
+
+  if (node.type === 'table') {
+    return serializeTable(node)
+  }
+
+  // For all other node types, extract text content
+  return extractTextFromNode(node)
+}
+
+function serializeTable(node: RootContent): string {
+  if (node.type !== 'table' || !('children' in node)) {
+    return ''
+  }
+
+  const rows = node.children
+    .filter((row): row is (typeof node.children)[number] => row.type === 'tableRow')
+    .map(row => {
+      const cells = (row.children as RootContent[])
+        .filter((cell): cell is RootContent => cell.type === 'tableCell')
+        .map(cell => extractTextFromNode(cell))
+      return `| ${cells.join(' | ')} |`
+    })
+
+  if (rows.length === 0) {
+    return ''
+  }
+
+  // Insert separator after header row
+  const headerRow = rows[0]
+  if (headerRow !== undefined) {
+    const columnCount = (headerRow.match(/\|/g)?.length ?? 2) - 1
+    const separator = `|${' --- |'.repeat(columnCount)}`
+    rows.splice(1, 0, separator)
+  }
+
+  return rows.join('\n')
+}
+
+/**
+ * Finds a section by heading text (case-insensitive)
+ */
+export function findSection(
+  content: ReadmeContent,
+  headingText: string,
+): ReadmeSection | undefined {
+  const normalizedSearch = headingText.toLowerCase()
+
+  function searchInSections(sections: readonly ReadmeSection[]): ReadmeSection | undefined {
+    for (const section of sections) {
+      if (section.heading.toLowerCase() === normalizedSearch) {
+        return section
+      }
+
+      const found = searchInSections(section.children)
+      if (found !== undefined) {
+        return found
+      }
+    }
+    return undefined
+  }
+
+  return searchInSections(content.sections)
+}
+
+/**
+ * Gets all sections at a specific heading level
+ */
+export function getSectionsByLevel(
+  content: ReadmeContent,
+  level: number,
+): readonly ReadmeSection[] {
+  const result: ReadmeSection[] = []
+
+  function collectAtLevel(sections: readonly ReadmeSection[]): void {
+    for (const section of sections) {
+      if (section.level === level) {
+        result.push(section)
+      }
+      collectAtLevel(section.children)
+    }
+  }
+
+  collectAtLevel(content.sections)
+  return result
+}
+
+/**
+ * Flattens all sections into a single array
+ */
+export function flattenSections(content: ReadmeContent): readonly ReadmeSection[] {
+  const result: ReadmeSection[] = []
+
+  function collect(sections: readonly ReadmeSection[]): void {
+    for (const section of sections) {
+      result.push(section)
+      collect(section.children)
+    }
+  }
+
+  collect(content.sections)
+  return result
+}
+
+/**
+ * Gets the table of contents as a flat list
+ */
+export function getTableOfContents(
+  content: ReadmeContent,
+): readonly {readonly heading: string; readonly level: number}[] {
+  return flattenSections(content).map(s => ({
+    heading: s.heading,
+    level: s.level,
+  }))
+}

package/src/parsers/typescript-parser.ts

@@ -0,0 +1,299 @@
+/**
+ * @bfra.me/doc-sync/parsers/typescript-parser - TypeScript source file parser using ts-morph
+ */
+
+import type {
+  ExportedFunction,
+  ExportedType,
+  FunctionParameter,
+  PackageAPI,
+  ParseError,
+  ParseResult,
+  ReExport,
+} from '../types'
+
+import {err, ok} from '@bfra.me/es/result'
+import {Project, type SourceFile} from 'ts-morph'
+
+import {extractJSDocInfo} from './jsdoc-extractor'
+
+/**
+ * Options for parsing TypeScript source files
+ */
+export interface TypeScriptParserOptions {
+  readonly tsConfigPath?: string
+  readonly compilerOptions?: Record<string, unknown>
+}
+
+/**
+ * Creates a ts-morph project instance for analyzing source files
+ */
+export function createProject(options?: TypeScriptParserOptions): Project {
+  return new Project({
+    tsConfigFilePath: options?.tsConfigPath,
+    compilerOptions: {
+      declaration: true,
+      ...(options?.compilerOptions as object),
+    },
+    skipAddingFilesFromTsConfig: true,
+  })
+}
+
+/**
+ * Parses a TypeScript source file and extracts its structure
+ */
+export function parseSourceFile(project: Project, filePath: string): ParseResult<SourceFile> {
+  try {
+    const sourceFile = project.addSourceFileAtPath(filePath)
+    return ok(sourceFile)
+  } catch (error) {
+    return err({
+      code: 'FILE_NOT_FOUND',
+      message: `Failed to parse source file: ${filePath}`,
+      filePath,
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+/**
+ * Parses TypeScript source content from a string
+ */
+export function parseSourceContent(
+  project: Project,
+  content: string,
+  virtualPath = 'virtual.ts',
+): ParseResult<SourceFile> {
+  try {
+    const sourceFile = project.createSourceFile(virtualPath, content, {
+      overwrite: true,
+    })
+    return ok(sourceFile)
+  } catch (error) {
+    return err({
+      code: 'INVALID_SYNTAX',
+      message: 'Failed to parse TypeScript content',
+      filePath: virtualPath,
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+/**
+ * Extracts exported functions from a source file
+ */
+export function extractExportedFunctions(sourceFile: SourceFile): readonly ExportedFunction[] {
+  const functions: ExportedFunction[] = []
+
+  for (const func of sourceFile.getFunctions()) {
+    if (!func.isExported()) continue
+
+    const name = func.getName() ?? 'default'
+    const parameters = extractFunctionParameters(func)
+    const returnType = func.getReturnType().getText()
+    const jsdoc = extractJSDocInfo(func)
+
+    functions.push({
+      name,
+      jsdoc,
+      signature: func.getSignature()?.getDeclaration().getText() ?? func.getText(),
+      isAsync: func.isAsync(),
+      isGenerator: func.isGenerator(),
+      parameters,
+      returnType,
+      isDefault: func.isDefaultExport(),
+    })
+  }
+
+  return functions
+}
+
+function extractFunctionParameters(
+  func: ReturnType<SourceFile['getFunctions']>[number],
+): readonly FunctionParameter[] {
+  return func.getParameters().map(param => ({
+    name: param.getName(),
+    type: param.getType().getText(),
+    optional: param.isOptional(),
+    defaultValue: param.getInitializer()?.getText(),
+  }))
+}
+
+/**
+ * Extracts exported types and interfaces from a source file
+ */
+export function extractExportedTypes(sourceFile: SourceFile): readonly ExportedType[] {
+  const types: ExportedType[] = []
+
+  // Extract interfaces
+  for (const iface of sourceFile.getInterfaces()) {
+    if (!iface.isExported()) continue
+
+    const jsdoc = extractJSDocInfo(iface)
+    const typeParams = iface.getTypeParameters().map(tp => tp.getText())
+
+    types.push({
+      name: iface.getName(),
+      jsdoc,
+      definition: iface.getText(),
+      kind: 'interface',
+      isDefault: iface.isDefaultExport(),
+      typeParameters: typeParams.length > 0 ? typeParams : undefined,
+    })
+  }
+
+  // Extract type aliases
+  for (const typeAlias of sourceFile.getTypeAliases()) {
+    if (!typeAlias.isExported()) continue
+
+    const jsdoc = extractJSDocInfo(typeAlias)
+    const typeParams = typeAlias.getTypeParameters().map(tp => tp.getText())
+
+    types.push({
+      name: typeAlias.getName(),
+      jsdoc,
+      definition: typeAlias.getText(),
+      kind: 'type',
+      isDefault: typeAlias.isDefaultExport(),
+      typeParameters: typeParams.length > 0 ? typeParams : undefined,
+    })
+  }
+
+  // Extract enums
+  for (const enumDecl of sourceFile.getEnums()) {
+    if (!enumDecl.isExported()) continue
+
+    const jsdoc = extractJSDocInfo(enumDecl)
+
+    types.push({
+      name: enumDecl.getName(),
+      jsdoc,
+      definition: enumDecl.getText(),
+      kind: 'enum',
+      isDefault: enumDecl.isDefaultExport(),
+    })
+  }
+
+  // Extract classes
+  for (const classDecl of sourceFile.getClasses()) {
+    if (!classDecl.isExported()) continue
+
+    const name = classDecl.getName()
+    if (name === undefined) continue
+
+    const jsdoc = extractJSDocInfo(classDecl)
+    const typeParams = classDecl.getTypeParameters().map(tp => tp.getText())
+
+    types.push({
+      name,
+      jsdoc,
+      definition: classDecl.getText(),
+      kind: 'class',
+      isDefault: classDecl.isDefaultExport(),
+      typeParameters: typeParams.length > 0 ? typeParams : undefined,
+    })
+  }
+
+  return types
+}
+
+/**
+ * Extracts re-export statements from a source file
+ */
+export function extractReExports(sourceFile: SourceFile): readonly ReExport[] {
+  const reExports: ReExport[] = []
+
+  for (const exportDecl of sourceFile.getExportDeclarations()) {
+    const moduleSpecifier = exportDecl.getModuleSpecifierValue()
+    if (moduleSpecifier === undefined || moduleSpecifier.length === 0) continue
+
+    if (exportDecl.isNamespaceExport()) {
+      const namespaceExport = exportDecl.getNamespaceExport()
+      reExports.push({
+        from: moduleSpecifier,
+        exports: '*',
+        alias: namespaceExport?.getName(),
+      })
+    } else {
+      const namedExports = exportDecl.getNamedExports().map(ne => {
+        const aliasNode = ne.getAliasNode()
+        const alias = aliasNode === undefined ? undefined : aliasNode.getText()
+        const name = ne.getName()
+        return alias === undefined ? name : `${name} as ${alias}`
+      })
+
+      if (namedExports.length > 0) {
+        reExports.push({
+          from: moduleSpecifier,
+          exports: namedExports,
+        })
+      }
+    }
+  }
+
+  return reExports
+}
+
+/**
+ * Extracts the complete API surface from a source file
+ */
+export function extractPackageAPI(sourceFile: SourceFile): PackageAPI {
+  return {
+    functions: extractExportedFunctions(sourceFile),
+    types: extractExportedTypes(sourceFile),
+    reExports: extractReExports(sourceFile),
+  }
+}
+
+/**
+ * Parses and analyzes a TypeScript file, returning the complete API
+ */
+export function analyzeTypeScriptFile(
+  filePath: string,
+  options?: TypeScriptParserOptions,
+): ParseResult<PackageAPI> {
+  const project = createProject(options)
+  const sourceFileResult = parseSourceFile(project, filePath)
+
+  if (!sourceFileResult.success) {
+    return sourceFileResult
+  }
+
+  try {
+    const api = extractPackageAPI(sourceFileResult.data)
+    return ok(api)
+  } catch (error) {
+    return err({
+      code: 'INVALID_SYNTAX',
+      message: `Failed to analyze TypeScript file: ${filePath}`,
+      filePath,
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+/**
+ * Analyzes TypeScript content from a string
+ */
+export function analyzeTypeScriptContent(
+  content: string,
+  options?: TypeScriptParserOptions,
+): ParseResult<PackageAPI> {
+  const project = createProject(options)
+  const sourceFileResult = parseSourceContent(project, content)
+
+  if (!sourceFileResult.success) {
+    return sourceFileResult
+  }
+
+  try {
+    const api = extractPackageAPI(sourceFileResult.data)
+    return ok(api)
+  } catch (error) {
+    return err({
+      code: 'INVALID_SYNTAX',
+      message: 'Failed to analyze TypeScript content',
+      cause: error,
+    } satisfies ParseError)
+  }
+}