@bfra.me/doc-sync 0.1.0

package/src/parsers/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @bfra.me/doc-sync/parsers - Unified export of all parser modules
+ */
+
+// Export analyzer exports
+export {
+  analyzePublicAPI,
+  findExportedSymbols,
+  getExportedSymbolInfo,
+  getExportsByKind,
+  isSymbolExported,
+} from './export-analyzer'
+export type {ExportAnalyzerOptions, PublicAPIAnalysis, ResolvedExport} from './export-analyzer'
+
+// Type guards and validation exports
+export {
+  assertPackageAPI,
+  assertPackageInfo,
+  assertParseError,
+  isDocConfigSource,
+  isExportedFunction,
+  isExportedType,
+  isJSDocInfo,
+  isJSDocParam,
+  isJSDocTag,
+  isMDXFrontmatter,
+  isPackageAPI,
+  isPackageInfo,
+  isParseError,
+  isReadmeContent,
+  isReadmeSection,
+  isReExport,
+  isSafeContent,
+  isSafeFilePath,
+  isSyncError,
+  isValidHeadingLevel,
+  isValidPackageName,
+  isValidSemver,
+} from './guards'
+
+// JSDoc extractor exports
+export {extractJSDocInfo, hasJSDoc, parseJSDoc} from './jsdoc-extractor'
+export type {JSDocableDeclaration} from './jsdoc-extractor'
+
+// Package info exports
+export {
+  buildDocSlug,
+  extractDocsConfig,
+  findEntryPoint,
+  findReadmePath,
+  getPackageScope,
+  getUnscopedName,
+  parsePackageComplete,
+  parsePackageJson,
+  parsePackageJsonContent,
+} from './package-info'
+export type {PackageInfoOptions, PackageJsonSchema} from './package-info'
+
+// README parser exports
+export {
+  findSection,
+  flattenSections,
+  getSectionsByLevel,
+  getTableOfContents,
+  parseReadme,
+  parseReadmeFile,
+} from './readme-parser'
+export type {ReadmeParserOptions} from './readme-parser'
+
+// TypeScript parser exports
+export {
+  analyzeTypeScriptContent,
+  analyzeTypeScriptFile,
+  createProject,
+  extractExportedFunctions,
+  extractExportedTypes,
+  extractPackageAPI,
+  extractReExports,
+  parseSourceContent,
+  parseSourceFile,
+} from './typescript-parser'
+export type {TypeScriptParserOptions} from './typescript-parser'

package/src/parsers/jsdoc-extractor.ts

@@ -0,0 +1,313 @@
+/**
+ * @bfra.me/doc-sync/parsers/jsdoc-extractor - JSDoc annotation extraction from TypeScript AST nodes
+ */
+
+import type {
+  ClassDeclaration,
+  EnumDeclaration,
+  FunctionDeclaration,
+  InterfaceDeclaration,
+  JSDoc,
+  JSDocableNode,
+  Node,
+  TypeAliasDeclaration,
+} from 'ts-morph'
+
+import type {JSDocInfo, JSDocParam, JSDocTag} from '../types'
+
+/**
+ * Supported node types for JSDoc extraction
+ */
+export type JSDocableDeclaration =
+  | ClassDeclaration
+  | EnumDeclaration
+  | FunctionDeclaration
+  | InterfaceDeclaration
+  | TypeAliasDeclaration
+
+/**
+ * Type guard to check if a node has JSDoc
+ */
+export function hasJSDoc(node: Node): node is Node & JSDocableNode {
+  return 'getJsDocs' in node && typeof node.getJsDocs === 'function'
+}
+
+/**
+ * Extracts JSDoc information from an AST node
+ */
+export function extractJSDocInfo(node: JSDocableDeclaration): JSDocInfo | undefined {
+  if (!hasJSDoc(node)) {
+    return undefined
+  }
+
+  const jsDocs = node.getJsDocs()
+  if (jsDocs.length === 0) {
+    return undefined
+  }
+
+  const jsDoc = jsDocs[0]
+  if (jsDoc === undefined) {
+    return undefined
+  }
+
+  return parseJSDoc(jsDoc)
+}
+
+/**
+ * Parses a JSDoc node into structured information
+ */
+export function parseJSDoc(jsDoc: JSDoc): JSDocInfo {
+  const description = jsDoc.getDescription().trim() || undefined
+  const tags = jsDoc.getTags()
+
+  const params = extractParams(tags)
+  const returns = extractReturns(tags)
+  const examples = extractExamples(tags)
+  const deprecated = extractDeprecated(tags)
+  const since = extractSince(tags)
+  const see = extractSee(tags)
+  const customTags = extractCustomTags(tags)
+
+  return {
+    ...(description !== undefined && {description}),
+    ...(params.length > 0 && {params}),
+    ...(returns !== undefined && {returns}),
+    ...(examples.length > 0 && {examples}),
+    ...(deprecated !== undefined && {deprecated}),
+    ...(since !== undefined && {since}),
+    ...(see.length > 0 && {see}),
+    ...(customTags.length > 0 && {customTags}),
+  }
+}
+
+function extractParams(tags: ReturnType<JSDoc['getTags']>): readonly JSDocParam[] {
+  const params: JSDocParam[] = []
+
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'param') continue
+
+    const text = getTagText(tag)
+    if (text === undefined) continue
+
+    const parsed = parseParamText(text)
+    if (parsed !== undefined) {
+      params.push(parsed)
+    }
+  }
+
+  return params
+}
+
+/**
+ * Handles multiple @param text formats:
+ * - name - description
+ * - {type} name - description
+ * - name description
+ */
+function parseParamText(text: string): JSDocParam | undefined {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) {
+    return undefined
+  }
+
+  let type: string | undefined
+  let remaining = trimmed
+
+  // Extract type if present: {type} ...
+  if (remaining.startsWith('{')) {
+    const typeEnd = remaining.indexOf('}')
+    if (typeEnd > 0) {
+      type = remaining.slice(1, typeEnd)
+      remaining = remaining.slice(typeEnd + 1).trim()
+    }
+  }
+
+  // Split name from description
+  const dashIndex = remaining.indexOf(' - ')
+  const spaceIndex = remaining.indexOf(' ')
+
+  let name: string
+  let description: string | undefined
+
+  if (dashIndex > 0) {
+    name = remaining.slice(0, dashIndex).trim()
+    description = remaining.slice(dashIndex + 3).trim() || undefined
+  } else if (spaceIndex > 0) {
+    name = remaining.slice(0, spaceIndex).trim()
+    description = remaining.slice(spaceIndex + 1).trim() || undefined
+  } else {
+    name = remaining
+  }
+
+  // Handle optional parameters [name]
+  let optional = false
+  if (name.startsWith('[') && name.endsWith(']')) {
+    optional = true
+    name = name.slice(1, -1)
+  }
+
+  // Handle default values [name=value]
+  let defaultValue: string | undefined
+  const defaultIndex = name.indexOf('=')
+  if (defaultIndex > 0) {
+    defaultValue = name.slice(defaultIndex + 1)
+    name = name.slice(0, defaultIndex)
+    optional = true
+  }
+
+  return {
+    name,
+    ...(type !== undefined && {type}),
+    ...(description !== undefined && {description}),
+    ...(optional && {optional}),
+    ...(defaultValue !== undefined && {defaultValue}),
+  }
+}
+
+function extractReturns(tags: ReturnType<JSDoc['getTags']>): string | undefined {
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'returns' && tagName !== 'return') continue
+
+    const text = getTagText(tag)
+    if (text !== undefined && text.trim().length > 0) {
+      // Strip leading type annotation if present
+      let result = text.trim()
+      if (result.startsWith('{')) {
+        const typeEnd = result.indexOf('}')
+        if (typeEnd > 0) {
+          result = result.slice(typeEnd + 1).trim()
+        }
+      }
+      return result.length > 0 ? result : undefined
+    }
+  }
+
+  return undefined
+}
+
+function extractExamples(tags: ReturnType<JSDoc['getTags']>): readonly string[] {
+  const examples: string[] = []
+
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'example') continue
+
+    const text = getTagText(tag)
+    if (text !== undefined && text.trim().length > 0) {
+      examples.push(text.trim())
+    }
+  }
+
+  return examples
+}
+
+function extractDeprecated(tags: ReturnType<JSDoc['getTags']>): string | undefined {
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'deprecated') continue
+
+    const text = getTagText(tag)
+    return text?.trim() ?? ''
+  }
+
+  return undefined
+}
+
+function extractSince(tags: ReturnType<JSDoc['getTags']>): string | undefined {
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'since') continue
+
+    const text = getTagText(tag)
+    if (text !== undefined && text.trim().length > 0) {
+      return text.trim()
+    }
+  }
+
+  return undefined
+}
+
+function extractSee(tags: ReturnType<JSDoc['getTags']>): readonly string[] {
+  const see: string[] = []
+
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (tagName !== 'see') continue
+
+    const text = getTagText(tag)
+    if (text !== undefined && text.trim().length > 0) {
+      see.push(text.trim())
+    }
+  }
+
+  return see
+}
+
+const STANDARD_TAGS = new Set([
+  'param',
+  'returns',
+  'return',
+  'example',
+  'deprecated',
+  'since',
+  'see',
+  'type',
+  'typedef',
+  'callback',
+  'template',
+  'throws',
+  'async',
+  'generator',
+  'override',
+  'readonly',
+  'private',
+  'protected',
+  'public',
+  'module',
+  'exports',
+  'interface',
+  'enum',
+  'class',
+  'constructor',
+  'function',
+  'method',
+  'property',
+  'member',
+  'implements',
+  'extends',
+  'augments',
+])
+
+function extractCustomTags(tags: ReturnType<JSDoc['getTags']>): readonly JSDocTag[] {
+  const customTags: JSDocTag[] = []
+
+  for (const tag of tags) {
+    const tagName = tag.getTagName()
+    if (STANDARD_TAGS.has(tagName)) continue
+
+    const text = getTagText(tag)
+    const value = text !== undefined && text.trim().length > 0 ? text.trim() : undefined
+
+    customTags.push({
+      name: tagName,
+      ...(value !== undefined && {value}),
+    })
+  }
+
+  return customTags
+}
+
+function getTagText(tag: ReturnType<JSDoc['getTags']>[number]): string | undefined {
+  const fullText = tag.getText()
+  const tagName = tag.getTagName()
+  const prefix = `@${tagName}`
+
+  if (fullText.startsWith(prefix)) {
+    const text = fullText.slice(prefix.length).trim()
+    return text.length > 0 ? text : undefined
+  }
+
+  return undefined
+}

package/src/parsers/package-info.ts

@@ -0,0 +1,267 @@
+/**
+ * @bfra.me/doc-sync/parsers/package-info - Package.json metadata extraction
+ */
+
+import type {DocConfigSource, PackageInfo, ParseError, ParseResult} from '../types'
+
+import path from 'node:path'
+
+import {err, ok} from '@bfra.me/es/result'
+
+/**
+ * Schema for validating package.json structure (runtime validation)
+ */
+export interface PackageJsonSchema {
+  readonly name: string
+  readonly version: string
+  readonly description?: string
+  readonly keywords?: readonly string[]
+  readonly main?: string
+  readonly module?: string
+  readonly types?: string
+  readonly exports?: Record<string, unknown>
+  readonly repository?:
+    | string
+    | {
+        readonly type?: string
+        readonly url?: string
+        readonly directory?: string
+      }
+  readonly docs?: DocConfigSource
+}
+
+/**
+ * Options for parsing package.json files
+ */
+export interface PackageInfoOptions {
+  readonly validateSchema?: boolean
+  readonly extractDocsConfig?: boolean
+}
+
+/**
+ * Parses a package.json file and extracts relevant metadata
+ */
+export async function parsePackageJson(
+  packagePath: string,
+  options?: PackageInfoOptions,
+): Promise<ParseResult<PackageInfo>> {
+  const packageJsonPath = packagePath.endsWith('package.json')
+    ? packagePath
+    : path.join(packagePath, 'package.json')
+
+  try {
+    const fs = await import('node:fs/promises')
+    const content = await fs.readFile(packageJsonPath, 'utf-8')
+    return parsePackageJsonContent(content, packageJsonPath, options)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return err({
+        code: 'FILE_NOT_FOUND',
+        message: `package.json not found: ${packageJsonPath}`,
+        filePath: packageJsonPath,
+        cause: error,
+      } satisfies ParseError)
+    }
+
+    return err({
+      code: 'READ_ERROR',
+      message: `Failed to read package.json: ${packageJsonPath}`,
+      filePath: packageJsonPath,
+      cause: error,
+    } satisfies ParseError)
+  }
+}
+
+/**
+ * Parses package.json content from a string
+ */
+export function parsePackageJsonContent(
+  content: string,
+  filePath: string,
+  options?: PackageInfoOptions,
+): ParseResult<PackageInfo> {
+  let parsed: unknown
+
+  try {
+    parsed = JSON.parse(content)
+  } catch (error) {
+    return err({
+      code: 'MALFORMED_JSON',
+      message: `Invalid JSON in package.json: ${filePath}`,
+      filePath,
+      cause: error,
+    } satisfies ParseError)
+  }
+
+  if (!isPackageJson(parsed)) {
+    return err({
+      code: 'INVALID_SYNTAX',
+      message: 'package.json is missing required fields (name, version)',
+      filePath,
+    } satisfies ParseError)
+  }
+
+  const packageDir = path.dirname(filePath)
+
+  return ok({
+    name: parsed.name,
+    version: parsed.version,
+    ...(parsed.description !== undefined && {description: parsed.description}),
+    ...(parsed.keywords !== undefined && {keywords: parsed.keywords}),
+    packagePath: packageDir,
+    srcPath: path.join(packageDir, 'src'),
+    ...(options?.extractDocsConfig !== false &&
+      parsed.docs !== undefined && {docsConfig: parsed.docs}),
+  })
+}
+
+function isPackageJson(value: unknown): value is PackageJsonSchema {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    return false
+  }
+
+  if (typeof obj.version !== 'string' || obj.version.length === 0) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Extracts documentation configuration from package.json
+ */
+export function extractDocsConfig(pkg: PackageInfo): DocConfigSource | undefined {
+  return pkg.docsConfig
+}
+
+/**
+ * Checks if a README file exists for a package
+ */
+export async function findReadmePath(packagePath: string): Promise<string | undefined> {
+  const fs = await import('node:fs/promises')
+  const candidates = ['README.md', 'readme.md', 'Readme.md', 'README.MD', 'README']
+
+  for (const candidate of candidates) {
+    const readmePath = path.join(packagePath, candidate)
+    try {
+      await fs.access(readmePath)
+      return readmePath
+    } catch {
+      // Continue to next candidate
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Extracts the source entry point from package.json
+ */
+export function findEntryPoint(pkg: PackageInfo, content: string): string {
+  try {
+    const parsed = JSON.parse(content) as PackageJsonSchema
+
+    // Check exports field first
+    if (parsed.exports !== undefined) {
+      const mainExport = parsed.exports['.']
+      if (mainExport !== undefined && typeof mainExport === 'object') {
+        const exportObj = mainExport as Record<string, unknown>
+        if (typeof exportObj.source === 'string') {
+          return path.join(pkg.packagePath, exportObj.source)
+        }
+        if (typeof exportObj.import === 'string') {
+          // Convert lib/ to src/ for source analysis
+          const importPath = exportObj.import
+          if (importPath.includes('/lib/')) {
+            return path.join(
+              pkg.packagePath,
+              importPath.replace('/lib/', '/src/').replace('.js', '.ts'),
+            )
+          }
+          return path.join(pkg.packagePath, importPath)
+        }
+      }
+      if (typeof mainExport === 'string') {
+        return path.join(pkg.packagePath, mainExport)
+      }
+    }
+
+    // Fall back to types or main field
+    if (typeof parsed.types === 'string') {
+      const typesPath = parsed.types.replace('/lib/', '/src/').replace('.d.ts', '.ts')
+      return path.join(pkg.packagePath, typesPath)
+    }
+
+    if (typeof parsed.main === 'string') {
+      const mainPath = parsed.main.replace('/lib/', '/src/').replace('.js', '.ts')
+      return path.join(pkg.packagePath, mainPath)
+    }
+  } catch {
+    // Ignore parsing errors
+  }
+
+  // Default to src/index.ts
+  return path.join(pkg.srcPath, 'index.ts')
+}
+
+/**
+ * Parses a complete package including README detection
+ */
+export async function parsePackageComplete(
+  packagePath: string,
+  options?: PackageInfoOptions,
+): Promise<ParseResult<PackageInfo>> {
+  const packageInfoResult = await parsePackageJson(packagePath, options)
+
+  if (!packageInfoResult.success) {
+    return packageInfoResult
+  }
+
+  const readmePath = await findReadmePath(packageInfoResult.data.packagePath)
+
+  return ok({
+    ...packageInfoResult.data,
+    ...(readmePath !== undefined && {readmePath}),
+  })
+}
+
+/**
+ * Gets the package scope from a scoped package name
+ */
+export function getPackageScope(packageName: string): string | undefined {
+  if (packageName.startsWith('@')) {
+    const slashIndex = packageName.indexOf('/')
+    if (slashIndex > 0) {
+      return packageName.slice(0, slashIndex)
+    }
+  }
+  return undefined
+}
+
+/**
+ * Gets the unscoped package name
+ */
+export function getUnscopedName(packageName: string): string {
+  if (packageName.startsWith('@')) {
+    const slashIndex = packageName.indexOf('/')
+    if (slashIndex > 0) {
+      return packageName.slice(slashIndex + 1)
+    }
+  }
+  return packageName
+}
+
+/**
+ * Builds a documentation slug from a package name
+ */
+export function buildDocSlug(packageName: string): string {
+  return getUnscopedName(packageName)
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9-]/g, '-')
+}