Configuration System

/**
 * Container for all TypeDoc configuration options with type-safe access
 */
class Options extends EventDispatcher<OptionsEvents, EventsWithArgument> {
  /**
   * Add a new option declaration
   * @param declaration - Option declaration to add
   */
  addDeclaration(declaration: DeclarationOption): void;
  
  /**
   * Get the value of a configuration option
   * @param name - Option name
   * @returns Current option value
   */
  getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptions[K];
  
  /**
   * Set the value of a configuration option
   * @param name - Option name  
   * @param value - New option value
   */
  setValue<K extends keyof TypeDocOptions>(name: K, value: TypeDocOptions[K]): void;
  
  /**
   * Check if an option has been explicitly set
   * @param name - Option name
   * @returns True if option was set by user
   */
  isSet(name: keyof TypeDocOptions): boolean;
  
  /**
   * Read configuration from all registered readers
   * @param logger - Logger for error reporting
   */
  read(logger: Logger): void;
  
  /**
   * Get all option declarations
   * @returns Array of all registered option declarations
   */
  getDeclarations(): DeclarationOption[];
  
  /**
   * Get declaration for specific option
   * @param name - Option name
   * @returns Option declaration or undefined
   */
  getDeclaration(name: string): DeclarationOption | undefined;
  
  /**
   * Add an option reader
   * @param reader - Reader to add
   */
  addReader(reader: OptionsReader): void;
  
  /**
   * Remove an option reader
   * @param reader - Reader to remove
   */
  removeReader(reader: OptionsReader): void;
  
  /**
   * Freeze the options container (prevent further changes)
   */
  freeze(): void;
}

import { Application, Options, ParameterType } from "typedoc";

const app = await Application.bootstrap();
const options = app.options;

// Get option values
const entryPoints = options.getValue("entryPoints");
const outputDir = options.getValue("out");
const theme = options.getValue("theme");

// Set option values
options.setValue("out", "dist/docs");
options.setValue("theme", "default");
options.setValue("excludeExternals", true);

// Check if option was set
if (options.isSet("json")) {
  console.log("JSON output was explicitly configured");
}

// Add custom option declaration
options.addDeclaration({
  name: "customPlugin",
  help: "Enable custom plugin functionality",
  type: ParameterType.Boolean,
  defaultValue: false,
});

// Read all configuration sources
options.read(app.logger);

/**
 * Base interface for option readers
 */
interface OptionsReader {
  /** Reader priority (higher numbers read later) */
  readonly priority: number;
  /** Whether reader should process unknown options */
  readonly unknownOptionNames?: string[];
  
  /**
   * Read options from source
   * @param container - Options container to populate
   * @param logger - Logger for error reporting
   * @param cwd - Current working directory
   */
  read(container: Options, logger: Logger, cwd: string): void;
}

/**
 * Reads options from command line arguments
 */
class ArgumentsReader implements OptionsReader {
  readonly priority: number;
  
  /**
   * Create arguments reader
   * @param priority - Reader priority
   */
  constructor(priority: number);
  
  /**
   * Ignore errors during reading (for secondary passes)
   * @returns New reader that ignores errors
   */
  ignoreErrors(): ArgumentsReader;
  
  read(container: Options, logger: Logger, cwd: string): void;
}

/**
 * Reads options from TypeDoc configuration files
 */
class TypeDocReader implements OptionsReader {
  readonly priority: number;
  
  read(container: Options, logger: Logger, cwd: string): void;
}

/**
 * Reads options from package.json typedocOptions field
 */
class PackageJsonReader implements OptionsReader {
  readonly priority: number;
  
  read(container: Options, logger: Logger, cwd: string): void;
}

/**
 * Reads options from tsconfig.json typedocOptions field
 */
class TSConfigReader implements OptionsReader {
  readonly priority: number;
  
  read(container: Options, logger: Logger, cwd: string): void;
}

import { 
  Application, 
  ArgumentsReader, 
  TypeDocReader, 
  TSConfigReader, 
  PackageJsonReader 
} from "typedoc";

// Bootstrap with custom reader configuration
const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
}, [
  new ArgumentsReader(0),           // CLI args (highest priority)
  new TypeDocReader(),              // typedoc.json/js
  new PackageJsonReader(),          // package.json typedocOptions
  new TSConfigReader(),             // tsconfig.json typedocOptions
  new ArgumentsReader(300).ignoreErrors(), // CLI args again (for overrides)
]);

// Create custom reader
class CustomConfigReader implements OptionsReader {
  readonly priority = 200;
  
  read(container: Options, logger: Logger, cwd: string): void {
    // Read from custom configuration source
    const customConfig = loadCustomConfig(cwd);
    
    for (const [key, value] of Object.entries(customConfig)) {
      if (container.getDeclaration(key)) {
        container.setValue(key as any, value);
      }
    }
  }
}

// Add custom reader
app.options.addReader(new CustomConfigReader());

/**
 * Base option declaration
 */
interface DeclarationOptionBase {
  /** Option name */
  name: string;
  /** Help text describing the option */
  help: string;
  /** Option type */
  type: ParameterType;
  /** Default value */
  defaultValue?: unknown;
  /** Validation function */
  validate?: (value: unknown) => void;
  /** Configuration file key (if different from name) */
  configFileKey?: string;
}

/**
 * String option declaration
 */
interface StringDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.String;
  defaultValue?: string;
  /** Validation function for strings */
  validate?: (value: string) => void;
}

/**
 * Number option declaration
 */
interface NumberDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Number;
  defaultValue?: number;
  /** Validation function for numbers */
  validate?: (value: number) => void;
}

/**
 * Boolean option declaration
 */
interface BooleanDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Boolean;
  defaultValue?: boolean;
  /** Validation function for booleans */
  validate?: (value: boolean) => void;
}

/**
 * Array option declaration
 */
interface ArrayDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Array;
  defaultValue?: string[];
  /** Validation function for arrays */
  validate?: (value: string[]) => void;
}

/**
 * Path option declaration
 */
interface PathDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Path;
  defaultValue?: string;
  /** Whether this is an output shortcut */
  outputShortcut?: boolean;
  /** Validation function for paths */
  validate?: (value: string) => void;
}

/**
 * Map option declaration (key-value pairs)
 */
interface MapDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Map;
  defaultValue?: Record<string, string>;
  /** Map key validation */
  mapKeyValidation?: (key: string) => void;
  /** Map value validation */
  mapValueValidation?: (value: string) => void;
}

/**
 * Flags option declaration (bit flags)
 */
interface FlagsDeclarationOption<T extends Record<string, number>> extends DeclarationOptionBase {
  type: ParameterType.Flags;
  /** Available flag values */
  flags: T;
  defaultValue?: number;
  /** Validation function for flags */
  validate?: (value: number) => void;
}

/**
 * Mixed type option (union of multiple types)
 */
interface MixedDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Mixed;
  /** Validation function for mixed types */
  validate?: (value: unknown) => void;
}

/**
 * Object option declaration
 */
interface ObjectDeclarationOption extends DeclarationOptionBase {
  type: ParameterType.Object;
  defaultValue?: Record<string, unknown>;
  /** Validation function for objects */
  validate?: (value: Record<string, unknown>) => void;
}

/**
 * Complete TypeDoc options interface
 */
interface TypeDocOptions {
  // Input Options
  entryPoints: string[];
  entryPointStrategy: EntryPointStrategy;
  exclude: string[];
  externalPattern: string[];
  excludeExternals: boolean;
  excludeNotDocumented: boolean;
  excludeInternal: boolean;
  excludePrivate: boolean;
  excludeProtected: boolean;
  excludeReferences: boolean;
  
  // Output Options  
  out: string;
  json: string;
  pretty: boolean;
  emit: EmitStrategy;
  theme: string;
  router: string;
  lightHighlightTheme: string;
  darkHighlightTheme: string;
  highlightLanguages: string[];
  customCss: string;
  customJs: string;
  markdownItOptions: object;
  
  // Comments Options
  commentStyle: CommentStyle;
  blockTags: `@${string}`[];
  inlineTags: `@${string}`[];
  modifierTags: `@${string}`[];
  excludeTags: `@${string}`[];
  
  // Organization Options
  categorizeByGroup: boolean;
  defaultCategory: string;
  categoryOrder: string[];
  groupOrder: string[];
  sort: SortStrategy[];
  kindSortOrder: ReflectionKind[];
  
  // Validation Options
  treatWarningsAsErrors: boolean;
  intentionallyNotExported: string[];
  validation: ValidationOptions;
  
  // Other Options
  name: string;
  includeVersion: boolean;
  disableSources: boolean;
  sourceLinkTemplate: string;
  gitRevision: string;
  gitRemote: string;
  githubPages: boolean;
  basePath: string;
  media: string;
  includes: string;
  
  // Watch Options  
  watch: boolean;
  preserveWatchOutput: boolean;
  
  // Plugin Options
  plugin: string[];
  
  // Advanced Options
  skipErrorChecking: boolean;
  compilerOptions: object;
  tsconfig: string;
  options: string;
  showConfig: boolean;
  logLevel: LogLevel;
  listInvalidSymbolLinks: boolean;
  
  // Package Options (for monorepos)
  packageOptions: object;
  entryPointPackages: string[];
}

/**
 * Types of configuration parameters
 */
enum ParameterType {
  String = "string",
  Number = "number", 
  Boolean = "boolean",
  Map = "map",
  Mixed = "mixed",
  Array = "array",
  PathArray = "pathArray",
  ModuleArray = "moduleArray", 
  GlobArray = "globArray",
  Object = "object",
  Flags = "flags",
  Path = "path",
  Module = "module",
  Glob = "glob",
}

/**
 * Parameter display hints for help generation
 */
enum ParameterHint {
  File = "file",
  Directory = "directory",
}

/**
 * Comment parsing styles
 */
enum CommentStyle {
  JSDoc = "jsdoc",
  Block = "block",
  Line = "line", 
  All = "all",
}

/**
 * Documentation emission strategies
 */
enum EmitStrategy {
  both = "both",   // Emit both docs and JS
  docs = "docs",   // Emit docs only (default)
  none = "none",   // No emission, validation only
}

/**
 * Entry point resolution strategies
 */
enum EntryPointStrategy {
  Resolve = "resolve",   // Resolve entry points (default)
  Expand = "expand",     // Expand directories
  Packages = "packages", // Package-based (monorepos)
  Merge = "merge",       // Merge all into single module
}

/**
 * Default option values
 */
namespace OptionDefaults {
  /** Default entry point strategy */
  const entryPointStrategy: EntryPointStrategy;
  
  /** Default comment style */
  const commentStyle: CommentStyle;
  
  /** Default theme name */
  const theme: string;
  
  /** Default sort strategies */
  const sort: SortStrategy[];
  
  /** Default block tags */
  const blockTags: `@${string}`[];
  
  /** Default inline tags */
  const inlineTags: `@${string}`[];
  
  /** Default modifier tags */
  const modifierTags: `@${string}`[];
}

/**
 * Validation configuration options
 */
interface ValidationOptions {
  /** Validate that documented types are not missing exports */
  notExported: boolean;
  /** Validate internal consistency of documentation */
  invalidLink: boolean;
  /** Validate that documented symbols have comments */
  notDocumented: boolean;
}

/**
 * Manually validated option type for complex validations
 */
type ManuallyValidatedOption<T> = {
  /** The actual option value */
  value: T;
  /** Whether the value has been manually validated */
  validated: boolean;
};

import { Application, TypeDocReader } from "typedoc";

// Load from typedoc.json
const reader = new TypeDocReader();
const options = new Options();
reader.read(options, logger, process.cwd());

// Custom configuration loading
class CustomConfigLoader {
  static async loadConfig(configPath: string): Promise<Partial<TypeDocOptions>> {
    const configFile = await readFile(configPath, 'utf8');
    return JSON.parse(configFile);
  }
}

import { Options, ParameterType } from "typedoc";

const options = new Options();

// Add custom options at runtime
options.addDeclaration({
  name: "customOutputFormat",
  help: "Specify custom output format",
  type: ParameterType.String,
  defaultValue: "html",
  validate: (value: string) => {
    if (!["html", "json", "xml"].includes(value)) {
      throw new Error("Invalid output format");
    }
  }
});

// Listen for option changes
options.on("optionSet", (name, value) => {
  console.log(`Option ${name} set to:`, value);
});