TypeScript Conversion

/**
 * The Converter manages the conversion process from TypeScript to TypeDoc reflections.
 * It coordinates symbol analysis, comment parsing, and reflection creation.
 */
class Converter extends AbstractComponent<Application, ConverterEvents> {
  /** Owner application */
  readonly owner: Application;
  
  /**
   * Convert entry points to a project reflection
   * @param entryPoints - Documentation entry points to convert
   * @returns Project reflection or undefined if conversion fails
   */
  convert(entryPoints: readonly DocumentationEntryPoint[]): ProjectReflection | undefined;
  
  /**
   * Convert a TypeScript symbol to a reflection
   * @param context - Current conversion context
   * @param symbol - TypeScript symbol to convert
   * @param exportSymbol - Export symbol if different from main symbol
   * @returns Created reflection or undefined
   */
  convertSymbol(
    context: Context,
    symbol: ts.Symbol,
    exportSymbol?: ts.Symbol
  ): Reflection | undefined;
  
  /**
   * Convert a TypeScript type to TypeDoc type representation
   * @param context - Current conversion context
   * @param type - TypeScript type to convert
   * @param node - Optional AST node for context
   * @returns TypeDoc type representation
   */
  convertType(context: Context, type: ts.Type, node?: ts.Node): Type;
}

import { Application, Context } from "typedoc";

const app = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
});

// Access the converter
const converter = app.converter;

// Convert the project
const project = converter.convert([
  { displayName: "My Project", entryPoints: ["src/index.ts"] }
]);

if (project) {
  console.log(`Converted project: ${project.name}`);
  console.log(`Found ${project.children?.length} top-level declarations`);
}

/**
 * Context maintains state during conversion and provides utilities for reflection creation
 */
class Context {
  /** Current TypeScript program */
  readonly program: ts.Program;
  /** Project being built */
  readonly project: ProjectReflection;
  /** Current conversion scope */
  readonly scope: Reflection;
  /** Current logger */
  readonly logger: Logger;
  /** Type checker instance */
  readonly checker: ts.TypeChecker;
  /** Converter instance */
  readonly converter: Converter;
  
  /**
   * Create a new declaration reflection
   * @param kind - Reflection kind
   * @param symbol - TypeScript symbol
   * @param exportSymbol - Export symbol if different
   * @param name - Override name
   * @returns Created declaration reflection
   */
  createDeclarationReflection(
    kind: ReflectionKind,
    symbol?: ts.Symbol,
    exportSymbol?: ts.Symbol,
    name?: string
  ): DeclarationReflection;
  
  /**
   * Finalize a declaration reflection after all processing
   * @param reflection - Reflection to finalize
   */
  finalizeDeclarationReflection(reflection: DeclarationReflection): void;
  
  /**
   * Create a signature reflection
   * @param kind - Signature kind
   * @param signature - TypeScript signature
   * @param parent - Parent reflection
   * @returns Created signature reflection
   */
  createSignatureReflection(
    kind: ReflectionKind,
    signature: ts.Signature,
    parent?: Reflection
  ): SignatureReflection;
  
  /**
   * Create a parameter reflection
   * @param parameter - TypeScript parameter symbol
   * @param signature - Parent signature
   * @returns Created parameter reflection
   */
  createParameterReflection(
    parameter: ts.Symbol,
    signature: SignatureReflection
  ): ParameterReflection;
  
  /**
   * Create a type parameter reflection
   * @param typeParameter - TypeScript type parameter
   * @param parent - Parent reflection
   * @returns Created type parameter reflection
   */
  createTypeParameterReflection(
    typeParameter: ts.TypeParameterDeclaration,
    parent: Reflection
  ): TypeParameterReflection;
  
  /**
   * Register reflection in the project
   * @param reflection - Reflection to register
   * @param symbol - Associated TypeScript symbol
   */
  registerReflection(reflection: Reflection, symbol?: ts.Symbol): void;
  
  /**
   * Get or create a reflection for a symbol
   * @param symbol - TypeScript symbol
   * @param kind - Expected reflection kind
   * @returns Existing or newly created reflection
   */
  expectReflection(symbol: ts.Symbol, kind?: ReflectionKind): Reflection;
  
  /**
   * Create child context for nested conversion
   * @param reflection - New scope reflection
   * @returns Child context
   */
  withScope(reflection: Reflection): Context;
}

import { Context, ReflectionKind } from "typedoc";

// In converter plugin or custom processing
function processSymbol(context: Context, symbol: ts.Symbol) {
  // Create reflection for the symbol
  const reflection = context.createDeclarationReflection(
    ReflectionKind.Function,
    symbol
  );
  
  // Process signatures if it's a callable
  const signatures = context.checker.getSignaturesOfType(
    context.checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration!),
    ts.SignatureKind.Call
  );
  
  for (const signature of signatures) {
    const sigReflection = context.createSignatureReflection(
      ReflectionKind.CallSignature,
      signature,
      reflection
    );
    
    // Process parameters
    for (const parameter of signature.parameters) {
      const paramReflection = context.createParameterReflection(
        parameter,
        sigReflection
      );
    }
  }
  
  // Finalize the reflection
  context.finalizeDeclarationReflection(reflection);
  
  return reflection;
}

/**
 * Convert default value expression to string representation
 * @param context - Conversion context
 * @param node - TypeScript node with default value
 * @returns String representation of default value
 */
function convertDefaultValue(context: Context, node: ts.Node): string | undefined;

/**
 * Convert TypeScript expression to TypeDoc representation
 * @param context - Conversion context  
 * @param node - Expression node to convert
 * @returns Converted expression representation
 */
function convertExpression(context: Context, node: ts.Expression): string;

/**
 * Configuration for comment parsing behavior
 */
interface CommentParserConfig {
  /** Block comment parsing settings */
  blockTags: Set<`@${string}`>;
  /** Inline tag parsing settings */
  inlineTags: Set<`@${string}`>;
  /** Modifier tag recognition */
  modifierTags: Set<`@${string}`>;
  /** Tag name validation */
  supportForTags: Set<`@${string}`>;
  /** JSDoc compatibility mode */
  jsDocCompatibility: JsDocCompatibility;
}

/**
 * JSDoc compatibility settings
 */
interface JsDocCompatibility {
  /** Default tag handling */
  defaultTag: boolean;
  /** Ignore unescaped braces */
  ignoreUnescapedBraces: boolean;
}

/**
 * Interface for resolving external symbols not in the current project
 */
interface ExternalSymbolResolver {
  /**
   * Resolve an external symbol reference
   * @param declaration - Declaration reference to resolve
   * @param referencingModule - Module making the reference
   * @param symbolId - Symbol identifier
   * @returns Resolution result or undefined if not resolvable
   */
  resolveSymbol(
    declaration: DeclarationReference,
    referencingModule: Reflection,
    symbolId?: ReflectionSymbolId
  ): ExternalResolveResult | undefined;
}

/**
 * Result of external symbol resolution
 */
interface ExternalResolveResult {
  /** Target reflection if resolved internally */
  target?: Reflection;
  /** External package name */
  package?: string;
  /** URL to external documentation */
  url?: string;
}

/**
 * Events dispatched during conversion process
 */
interface ConverterEvents {
  /** Begin conversion process */
  BEGIN: [Context];
  /** End conversion process */
  END: [Context];
  /** Begin converting a source file */
  FILE_BEGIN: [Context, Reflection, ts.SourceFile];
  /** Create a declaration reflection */
  CREATE_DECLARATION: [Context, DeclarationReflection, ts.Declaration | undefined];
  /** Create a signature reflection */
  CREATE_SIGNATURE: [Context, SignatureReflection, ts.Signature | ts.JSDocSignature, ts.Node | undefined];
  /** Create a parameter reflection */
  CREATE_PARAMETER: [Context, ParameterReflection, ts.Symbol, ts.Node | undefined];
  /** Create a type parameter reflection */
  CREATE_TYPE_PARAMETER: [Context, TypeParameterReflection, ts.TypeParameterDeclaration];
  /** Resolve external symbol */
  RESOLVE_EXTERNAL_SYMBOL: [Context, DeclarationReference, ReflectionSymbolId];
}

import { Application, ConverterEvents } from "typedoc";

const app = await Application.bootstrap();

// Listen for conversion events
app.converter.on("BEGIN", (context) => {
  console.log("Starting conversion");
});

app.converter.on("CREATE_DECLARATION", (context, reflection, declaration) => {
  console.log(`Created ${reflection.kind} reflection: ${reflection.name}`);
  
  // Custom processing for specific declaration types
  if (reflection.kind === ReflectionKind.Class) {
    // Add custom metadata or processing for classes
    reflection.comment = reflection.comment || new Comment();
  }
});

app.converter.on("END", (context) => {
  console.log("Conversion completed");
  console.log(`Total reflections: ${context.project.children?.length}`);
});

/**
 * Base class for converter components/plugins
 */
abstract class ConverterComponent extends AbstractComponent<Application, ConverterEvents> {
  /** Converter instance */
  readonly converter: Converter;
  
  /**
   * Initialize the component
   */
  initialize(): void;
  
  /**
   * Called when component is removed
   */
  remove(): void;
}

import { ConverterComponent, ReflectionKind } from "typedoc";

class CustomConverterPlugin extends ConverterComponent {
  initialize() {
    // Listen for declaration creation
    this.listenTo(this.owner, "CREATE_DECLARATION", this.onCreateDeclaration);
  }
  
  private onCreateDeclaration = (context: Context, reflection: DeclarationReflection) => {
    // Add custom processing for functions
    if (reflection.kind === ReflectionKind.Function) {
      // Extract custom metadata from JSDoc tags
      const customTag = reflection.comment?.getTag("@custom");
      if (customTag) {
        // Process custom tag content
        console.log(`Custom tag found on ${reflection.name}`);
      }
    }
  };
}

// Register the plugin
app.converter.addComponent("custom-plugin", CustomConverterPlugin);

/**
 * Utility functions for TypeScript node analysis
 */
namespace NodeUtils {
  /** Check if node is exported */
  function isExported(node: ts.Node): boolean;
  
  /** Check if node is namespace export */
  function isNamespaceExport(node: ts.Node): boolean;
  
  /** Get name from various node types */
  function getName(node: ts.Node): string | undefined;
  
  /** Check if node has specific modifier */
  function hasModifier(node: ts.Node, modifier: ts.SyntaxKind): boolean;
}

/**
 * Utility functions for TypeScript symbol analysis
 */
namespace SymbolUtils {
  /** Get qualified symbol name */
  function getQualifiedName(symbol: ts.Symbol, checker: ts.TypeChecker): string;
  
  /** Check if symbol is alias */
  function isAlias(symbol: ts.Symbol): boolean;
  
  /** Resolve alias to target symbol */
  function resolveAlias(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol;
}