@bfra.me/doc-sync 0.1.0

package/src/parsers/export-analyzer.ts

@@ -0,0 +1,335 @@
+/**
+ * @bfra.me/doc-sync/parsers/export-analyzer - Public API surface analyzer for package exports
+ */
+
+import type {Project, SourceFile} from 'ts-morph'
+
+import type {PackageAPI, ParseResult, ReExport} from '../types'
+
+import {ok} from '@bfra.me/es/result'
+
+import {createProject, extractPackageAPI, parseSourceFile} from './typescript-parser'
+
+/**
+ * Options for analyzing package exports
+ */
+export interface ExportAnalyzerOptions {
+  readonly tsConfigPath?: string
+  readonly followReExports?: boolean
+  readonly maxDepth?: number
+}
+
+/**
+ * Resolved export information including the original source
+ */
+export interface ResolvedExport {
+  readonly name: string
+  readonly kind: 'function' | 'type' | 'interface' | 'enum' | 'class' | 're-export'
+  readonly source: string
+  readonly isDefault: boolean
+}
+
+/**
+ * Complete analysis of a package's public API
+ */
+export interface PublicAPIAnalysis {
+  readonly packagePath: string
+  readonly entryPoint: string
+  readonly api: PackageAPI
+  readonly resolvedExports: readonly ResolvedExport[]
+}
+
+/**
+ * Analyzes the public API surface of a package from its entry point
+ */
+export function analyzePublicAPI(
+  entryPointPath: string,
+  options?: ExportAnalyzerOptions,
+): ParseResult<PublicAPIAnalysis> {
+  const project = createProject({tsConfigPath: options?.tsConfigPath})
+  const sourceFileResult = parseSourceFile(project, entryPointPath)
+
+  if (!sourceFileResult.success) {
+    return sourceFileResult
+  }
+
+  const sourceFile = sourceFileResult.data
+  const api = extractPackageAPI(sourceFile)
+  const resolvedExports = resolveAllExports(sourceFile, api, project, options)
+
+  return ok({
+    packagePath: sourceFile.getDirectoryPath(),
+    entryPoint: entryPointPath,
+    api,
+    resolvedExports,
+  })
+}
+
+function resolveAllExports(
+  sourceFile: SourceFile,
+  api: PackageAPI,
+  project: Project,
+  options?: ExportAnalyzerOptions,
+): readonly ResolvedExport[] {
+  const exports: ResolvedExport[] = []
+  const filePath = sourceFile.getFilePath()
+
+  // Add direct function exports
+  for (const func of api.functions) {
+    exports.push({
+      name: func.name,
+      kind: 'function',
+      source: filePath,
+      isDefault: func.isDefault,
+    })
+  }
+
+  // Add direct type exports
+  for (const type of api.types) {
+    exports.push({
+      name: type.name,
+      kind: type.kind,
+      source: filePath,
+      isDefault: type.isDefault,
+    })
+  }
+
+  // Handle re-exports if enabled
+  if (options?.followReExports !== false) {
+    const maxDepth = options?.maxDepth ?? 5
+    const reExportedItems = resolveReExports(
+      sourceFile,
+      api.reExports,
+      project,
+      maxDepth,
+      new Set(),
+    )
+    exports.push(...reExportedItems)
+  }
+
+  return exports
+}
+
+function resolveReExports(
+  sourceFile: SourceFile,
+  reExports: readonly ReExport[],
+  project: Project,
+  remainingDepth: number,
+  visited: Set<string>,
+): readonly ResolvedExport[] {
+  if (remainingDepth <= 0 || reExports.length === 0) {
+    return []
+  }
+
+  const exports: ResolvedExport[] = []
+
+  for (const reExport of reExports) {
+    const resolvedPath = resolveModulePath(sourceFile, reExport.from)
+    if (resolvedPath === undefined || visited.has(resolvedPath)) {
+      // Add as unresolved re-export
+      if (reExport.exports === '*') {
+        exports.push({
+          name: reExport.alias ?? '*',
+          kind: 're-export',
+          source: reExport.from,
+          isDefault: false,
+        })
+      } else {
+        for (const name of reExport.exports) {
+          exports.push({
+            name,
+            kind: 're-export',
+            source: reExport.from,
+            isDefault: false,
+          })
+        }
+      }
+      continue
+    }
+
+    visited.add(resolvedPath)
+
+    try {
+      const reExportedFile = getOrAddSourceFile(project, resolvedPath)
+      if (reExportedFile === undefined) continue
+
+      const reExportedAPI = extractPackageAPI(reExportedFile)
+
+      if (reExport.exports === '*') {
+        // Namespace export - include all exports from the module
+        for (const func of reExportedAPI.functions) {
+          exports.push({
+            name: func.name,
+            kind: 'function',
+            source: resolvedPath,
+            isDefault: func.isDefault,
+          })
+        }
+
+        for (const type of reExportedAPI.types) {
+          exports.push({
+            name: type.name,
+            kind: type.kind,
+            source: resolvedPath,
+            isDefault: type.isDefault,
+          })
+        }
+
+        // Recurse into nested re-exports
+        const nestedExports = resolveReExports(
+          reExportedFile,
+          reExportedAPI.reExports,
+          project,
+          remainingDepth - 1,
+          visited,
+        )
+        exports.push(...nestedExports)
+      } else {
+        // Named exports - only include specified exports
+        for (const exportName of reExport.exports) {
+          // Parse potential alias: "original as alias"
+          const [originalName, alias] = parseExportName(exportName)
+
+          // Check if this is a function export
+          const func = reExportedAPI.functions.find(f => f.name === originalName)
+          if (func !== undefined) {
+            exports.push({
+              name: alias ?? originalName,
+              kind: 'function',
+              source: resolvedPath,
+              isDefault: func.isDefault,
+            })
+            continue
+          }
+
+          // Check if this is a type export
+          const type = reExportedAPI.types.find(t => t.name === originalName)
+          if (type !== undefined) {
+            exports.push({
+              name: alias ?? originalName,
+              kind: type.kind,
+              source: resolvedPath,
+              isDefault: type.isDefault,
+            })
+          }
+        }
+      }
+    } catch {
+      // Failed to resolve re-export, skip
+    }
+  }
+
+  return exports
+}
+
+function parseExportName(exportName: string): [string, string | undefined] {
+  const asIndex = exportName.indexOf(' as ')
+  if (asIndex > 0) {
+    return [exportName.slice(0, asIndex), exportName.slice(asIndex + 4)]
+  }
+  return [exportName, undefined]
+}
+
+function resolveModulePath(sourceFile: SourceFile, modulePath: string): string | undefined {
+  if (!modulePath.startsWith('.')) {
+    // External module, cannot resolve
+    return undefined
+  }
+
+  try {
+    const directory = sourceFile.getDirectory()
+    const extensions = ['.ts', '.tsx', '/index.ts', '/index.tsx', '.js', '.jsx']
+
+    for (const ext of extensions) {
+      const candidate = directory.getSourceFile(modulePath + ext)
+      if (candidate !== undefined) {
+        return candidate.getFilePath()
+      }
+    }
+
+    // Try without extension
+    const direct = directory.getSourceFile(modulePath)
+    return direct?.getFilePath()
+  } catch {
+    return undefined
+  }
+}
+
+function getOrAddSourceFile(project: Project, filePath: string): SourceFile | undefined {
+  try {
+    return project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Finds all exported symbols from a package entry point
+ */
+export function findExportedSymbols(
+  entryPointPath: string,
+  options?: ExportAnalyzerOptions,
+): ParseResult<readonly string[]> {
+  const analysisResult = analyzePublicAPI(entryPointPath, options)
+
+  if (!analysisResult.success) {
+    return analysisResult
+  }
+
+  const symbols = analysisResult.data.resolvedExports.map(exp => exp.name)
+  return ok([...new Set(symbols)])
+}
+
+/**
+ * Checks if a symbol is exported from a package
+ */
+export function isSymbolExported(
+  entryPointPath: string,
+  symbolName: string,
+  options?: ExportAnalyzerOptions,
+): ParseResult<boolean> {
+  const analysisResult = analyzePublicAPI(entryPointPath, options)
+
+  if (!analysisResult.success) {
+    return analysisResult
+  }
+
+  const isExported = analysisResult.data.resolvedExports.some(exp => exp.name === symbolName)
+  return ok(isExported)
+}
+
+/**
+ * Gets detailed information about a specific exported symbol
+ */
+export function getExportedSymbolInfo(
+  entryPointPath: string,
+  symbolName: string,
+  options?: ExportAnalyzerOptions,
+): ParseResult<ResolvedExport | undefined> {
+  const analysisResult = analyzePublicAPI(entryPointPath, options)
+
+  if (!analysisResult.success) {
+    return analysisResult
+  }
+
+  const exported = analysisResult.data.resolvedExports.find(exp => exp.name === symbolName)
+  return ok(exported)
+}
+
+/**
+ * Filters exports by kind
+ */
+export function getExportsByKind(
+  entryPointPath: string,
+  kind: ResolvedExport['kind'],
+  options?: ExportAnalyzerOptions,
+): ParseResult<readonly ResolvedExport[]> {
+  const analysisResult = analyzePublicAPI(entryPointPath, options)
+
+  if (!analysisResult.success) {
+    return analysisResult
+  }
+
+  const filtered = analysisResult.data.resolvedExports.filter(exp => exp.kind === kind)
+  return ok(filtered)
+}

package/src/parsers/guards.ts

@@ -0,0 +1,350 @@
+/**
+ * @bfra.me/doc-sync/parsers/guards - Type guards and validation for parser types
+ */
+
+import type {
+  DocConfigSource,
+  ExportedFunction,
+  ExportedType,
+  JSDocInfo,
+  JSDocParam,
+  JSDocTag,
+  MDXFrontmatter,
+  PackageAPI,
+  PackageInfo,
+  ParseError,
+  ReadmeContent,
+  ReadmeSection,
+  ReExport,
+  SyncError,
+} from '../types'
+
+export function isParseError(value: unknown): value is ParseError {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.code === 'string' &&
+    typeof obj.message === 'string' &&
+    [
+      'INVALID_SYNTAX',
+      'FILE_NOT_FOUND',
+      'READ_ERROR',
+      'MALFORMED_JSON',
+      'UNSUPPORTED_FORMAT',
+    ].includes(obj.code)
+  )
+}
+
+/**
+ * Type guard for SyncError
+ */
+export function isSyncError(value: unknown): value is SyncError {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.code === 'string' &&
+    typeof obj.message === 'string' &&
+    [
+      'WRITE_ERROR',
+      'VALIDATION_ERROR',
+      'GENERATION_ERROR',
+      'PACKAGE_NOT_FOUND',
+      'CONFIG_ERROR',
+    ].includes(obj.code)
+  )
+}
+
+export function isJSDocParam(value: unknown): value is JSDocParam {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.name === 'string' &&
+    (obj.type === undefined || typeof obj.type === 'string') &&
+    (obj.description === undefined || typeof obj.description === 'string') &&
+    (obj.optional === undefined || typeof obj.optional === 'boolean') &&
+    (obj.defaultValue === undefined || typeof obj.defaultValue === 'string')
+  )
+}
+
+export function isJSDocTag(value: unknown): value is JSDocTag {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return typeof obj.name === 'string' && (obj.value === undefined || typeof obj.value === 'string')
+}
+
+export function isJSDocInfo(value: unknown): value is JSDocInfo {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    (obj.description === undefined || typeof obj.description === 'string') &&
+    (obj.params === undefined || (Array.isArray(obj.params) && obj.params.every(isJSDocParam))) &&
+    (obj.returns === undefined || typeof obj.returns === 'string') &&
+    (obj.examples === undefined ||
+      (Array.isArray(obj.examples) && obj.examples.every(e => typeof e === 'string'))) &&
+    (obj.deprecated === undefined || typeof obj.deprecated === 'string') &&
+    (obj.since === undefined || typeof obj.since === 'string') &&
+    (obj.see === undefined ||
+      (Array.isArray(obj.see) && obj.see.every(s => typeof s === 'string'))) &&
+    (obj.customTags === undefined ||
+      (Array.isArray(obj.customTags) && obj.customTags.every(isJSDocTag)))
+  )
+}
+
+export function isExportedFunction(value: unknown): value is ExportedFunction {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.name === 'string' &&
+    typeof obj.signature === 'string' &&
+    typeof obj.isAsync === 'boolean' &&
+    typeof obj.isGenerator === 'boolean' &&
+    Array.isArray(obj.parameters) &&
+    typeof obj.returnType === 'string' &&
+    typeof obj.isDefault === 'boolean'
+  )
+}
+
+export function isExportedType(value: unknown): value is ExportedType {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.name === 'string' &&
+    typeof obj.definition === 'string' &&
+    typeof obj.kind === 'string' &&
+    ['interface', 'type', 'enum', 'class'].includes(obj.kind) &&
+    typeof obj.isDefault === 'boolean'
+  )
+}
+
+export function isReExport(value: unknown): value is ReExport {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.from === 'string' &&
+    (obj.exports === '*' ||
+      (Array.isArray(obj.exports) && obj.exports.every(e => typeof e === 'string')))
+  )
+}
+
+export function isPackageAPI(value: unknown): value is PackageAPI {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    Array.isArray(obj.functions) &&
+    obj.functions.every(isExportedFunction) &&
+    Array.isArray(obj.types) &&
+    obj.types.every(isExportedType) &&
+    Array.isArray(obj.reExports) &&
+    obj.reExports.every(isReExport)
+  )
+}
+
+export function isDocConfigSource(value: unknown): value is DocConfigSource {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    (obj.title === undefined || typeof obj.title === 'string') &&
+    (obj.description === undefined || typeof obj.description === 'string') &&
+    (obj.sidebar === undefined || typeof obj.sidebar === 'object') &&
+    (obj.excludeSections === undefined ||
+      (Array.isArray(obj.excludeSections) &&
+        obj.excludeSections.every(s => typeof s === 'string'))) &&
+    (obj.frontmatter === undefined || typeof obj.frontmatter === 'object')
+  )
+}
+
+export function isPackageInfo(value: unknown): value is PackageInfo {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.name === 'string' &&
+    typeof obj.version === 'string' &&
+    typeof obj.packagePath === 'string' &&
+    typeof obj.srcPath === 'string' &&
+    (obj.description === undefined || typeof obj.description === 'string') &&
+    (obj.keywords === undefined ||
+      (Array.isArray(obj.keywords) && obj.keywords.every(k => typeof k === 'string'))) &&
+    (obj.readmePath === undefined || typeof obj.readmePath === 'string') &&
+    (obj.docsConfig === undefined || isDocConfigSource(obj.docsConfig))
+  )
+}
+
+export function isReadmeSection(value: unknown): value is ReadmeSection {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.heading === 'string' &&
+    typeof obj.level === 'number' &&
+    obj.level >= 1 &&
+    obj.level <= 6 &&
+    typeof obj.content === 'string' &&
+    Array.isArray(obj.children) &&
+    obj.children.every(isReadmeSection)
+  )
+}
+
+export function isReadmeContent(value: unknown): value is ReadmeContent {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    (obj.title === undefined || typeof obj.title === 'string') &&
+    (obj.preamble === undefined || typeof obj.preamble === 'string') &&
+    Array.isArray(obj.sections) &&
+    obj.sections.every(isReadmeSection) &&
+    typeof obj.raw === 'string'
+  )
+}
+
+export function isMDXFrontmatter(value: unknown): value is MDXFrontmatter {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  return (
+    typeof obj.title === 'string' &&
+    (obj.description === undefined || typeof obj.description === 'string') &&
+    (obj.sidebar === undefined || typeof obj.sidebar === 'object') &&
+    (obj.tableOfContents === undefined ||
+      typeof obj.tableOfContents === 'boolean' ||
+      typeof obj.tableOfContents === 'object') &&
+    (obj.template === undefined || obj.template === 'doc' || obj.template === 'splash')
+  )
+}
+
+export function isValidPackageName(name: string): boolean {
+  // Package names must not be empty
+  if (name.length === 0) {
+    return false
+  }
+
+  // Package names must not start with a dot or underscore
+  if (name.startsWith('.') || name.startsWith('_')) {
+    return false
+  }
+
+  // Scoped package names
+  if (name.startsWith('@')) {
+    const slashIndex = name.indexOf('/')
+    if (slashIndex <= 1 || slashIndex === name.length - 1) {
+      return false
+    }
+
+    const scope = name.slice(1, slashIndex)
+    const pkg = name.slice(slashIndex + 1)
+
+    return isValidUnscopedPackageName(scope) && isValidUnscopedPackageName(pkg)
+  }
+
+  return isValidUnscopedPackageName(name)
+}
+
+function isValidUnscopedPackageName(name: string): boolean {
+  return /^\w[\w.-]*$/.test(name)
+}
+
+export function isValidSemver(version: string): boolean {
+  return /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(version)
+}
+
+export function isValidHeadingLevel(level: number): level is 1 | 2 | 3 | 4 | 5 | 6 {
+  return Number.isInteger(level) && level >= 1 && level <= 6
+}
+
+/** Checks for potential XSS patterns to prevent injection attacks */
+export function isSafeContent(content: string): boolean {
+  const dangerousPatterns = [/<script\b/i, /javascript:/i, /on\w+\s*=/i, /data:/i, /vbscript:/i]
+
+  return !dangerousPatterns.some(pattern => pattern.test(content))
+}
+
+/** Prevents directory traversal attacks in file paths */
+export function isSafeFilePath(filePath: string): boolean {
+  const normalizedPath = filePath
+    .replaceAll('\\', '/')
+    .replaceAll(/\/+/g, '/')
+    .replaceAll('/./', '/')
+
+  // Check for directory traversal
+  if (normalizedPath.includes('../') || normalizedPath.includes('..\\')) {
+    return false
+  }
+
+  // Check for absolute paths on Unix
+  if (normalizedPath.startsWith('/') && !filePath.startsWith('/')) {
+    return false
+  }
+
+  return true
+}
+
+export function assertParseError(value: unknown): asserts value is ParseError {
+  if (!isParseError(value)) {
+    throw new TypeError('Expected ParseError')
+  }
+}
+
+export function assertPackageInfo(value: unknown): asserts value is PackageInfo {
+  if (!isPackageInfo(value)) {
+    throw new TypeError('Expected PackageInfo')
+  }
+}
+
+export function assertPackageAPI(value: unknown): asserts value is PackageAPI {
+  if (!isPackageAPI(value)) {
+    throw new TypeError('Expected PackageAPI')
+  }
+}