Documentation Models

/**
 * Base class for all reflections representing documented elements
 */
abstract class Reflection {
  /** Unique identifier for this reflection */
  readonly id: ReflectionId;
  /** The name of this reflection */
  readonly name: string;
  /** The kind of reflection */
  readonly kind: ReflectionKind;
  /** Flags describing reflection properties */
  readonly flags: ReflectionFlag;
  /** Associated comment documentation */
  comment?: Comment;
  /** Parent reflection in the hierarchy */
  readonly parent?: Reflection;
  /** Original TypeScript symbol */
  readonly symbol?: ts.Symbol;
  /** Source file location */
  sources?: SourceReference[];
  /** Reflection groups for organization */
  groups?: ReflectionGroup[];
  /** Reflection categories for organization */
  categories?: ReflectionCategory[];

  /** Get full name including parent hierarchy */
  getFullName(separator?: string): string;
  /** Get URL for this reflection */
  getUrl(): string;
  /** Check if reflection has specific flag */
  hasFlag(flag: ReflectionFlag): boolean;
  /** Set comment for this reflection */
  setComment(comment: Comment): void;
}

/**
 * Reflection that can contain child reflections
 */
abstract class ContainerReflection extends Reflection {
  /** Child reflections */
  children?: DeclarationReflection[];
  /** Groups organizing child reflections */
  groups?: ReflectionGroup[];
  /** Categories for organizing reflections */  
  categories?: ReflectionCategory[];

  /** Get child reflection by name */
  getChildByName(name: string): Reflection | undefined;
  /** Get all children matching predicate */
  getChildren(predicate?: (child: Reflection) => boolean): Reflection[];
  /** Add child reflection */
  addChild(child: DeclarationReflection): void;
  /** Remove child reflection */
  removeChild(child: DeclarationReflection): void;
}

/**
 * Root reflection representing the entire project
 */
class ProjectReflection extends ContainerReflection {
  /** Package version from package.json */
  readonly packageVersion?: string;
  /** README content */
  readonly readme?: string;
  /** Changelog content */
  readonly changelog?: string;
  /** Entry points for this project */
  readonly entryPoints: readonly DocumentationEntryPoint[];
  /** File registry tracking all source files */
  readonly files: FileRegistry;

  /** Get reflection by ID */
  getReflectionById(id: ReflectionId): Reflection | undefined;
}

/**
 * Reflection for TypeScript declarations (classes, functions, variables, etc.)
 */
class DeclarationReflection extends ContainerReflection {
  /** Type of this declaration */
  type?: Type;
  /** Default value as string */
  defaultValue?: string;
  /** Reference to overwritten declaration */
  overwrites?: ReferenceType;
  /** Reference to inherited declaration */
  inheritedFrom?: ReferenceType;
  /** Reference to implemented interface member */
  implementationOf?: ReferenceType;
  /** Types this declaration extends */
  extendedTypes?: Type[];
  /** Types that extend this declaration */
  extendedBy?: ReferenceType[];
  /** Types this declaration implements */
  implementedTypes?: Type[];
  /** Types that implement this declaration */
  implementedBy?: ReferenceType[];
  /** Type parameters for generic declarations */
  typeParameters?: TypeParameterReflection[];
  /** Signatures for callable declarations */
  signatures?: SignatureReflection[];
  /** Index signature if present */
  indexSignature?: SignatureReflection;
  /** Get signature for accessors */
  getSignature?: SignatureReflection;
  /** Set signature for accessors */
  setSignature?: SignatureReflection;
  /** Variant information */
  variant?: ReflectionVariant;

  /** Check if declaration is exported */
  isExported(): boolean;
  /** Get all signatures including inherited ones */
  getAllSignatures(): SignatureReflection[];
}

import { ProjectReflection, DeclarationReflection, ReflectionKind } from "typedoc";

// Access project information
const project: ProjectReflection = app.convert();
console.log(`Project: ${project.name} v${project.packageVersion}`);
console.log(`Entry points: ${project.entryPoints.length}`);

// Find specific declarations
const classes = project.getChildren().filter(child => 
  child.kind === ReflectionKind.Class
);

const exports = project.getChildren().filter(child => 
  child instanceof DeclarationReflection && child.isExported()
);

// Navigate reflection hierarchy
for (const child of project.children || []) {
  console.log(`${child.name} (${ReflectionKind[child.kind]})`);
  if (child instanceof DeclarationReflection && child.signatures) {
    child.signatures.forEach(sig => {
      console.log(`  Signature: ${sig.name}(${sig.parameters?.map(p => p.name).join(', ')})`);
    });
  }
}

/**
 * Reflection for function/method signatures
 */
class SignatureReflection extends Reflection {
  /** Parameters for this signature */
  parameters?: ParameterReflection[];
  /** Return type */
  type?: Type;
  /** Type parameters for generic signatures */
  typeParameters?: TypeParameterReflection[];
  /** Overwrites information */
  overwrites?: ReferenceType;
  /** Inherited from information */
  inheritedFrom?: ReferenceType;
  /** Implementation information */
  implementationOf?: ReferenceType;

  /** Get signature string representation */
  toString(): string;
  /** Check if signature has parameters */
  hasParameters(): boolean;
}

/**
 * Reflection for function/method parameters
 */
class ParameterReflection extends Reflection {
  /** Parameter type */
  type?: Type;
  /** Default value */
  defaultValue?: string;
  /** Rest parameter flag */
  rest: boolean;
  /** Optional parameter flag */
  optional: boolean;

  /** Check if parameter is optional */
  isOptional(): boolean;
  /** Check if parameter is rest parameter */
  isRest(): boolean;
}

/**
 * Reflection for generic type parameters
 */
class TypeParameterReflection extends Reflection {
  /** Constraint type */
  type?: Type;
  /** Default type */
  default?: Type;
  /** Constraint type for extends clause */
  constraint?: Type;

  /** Get type parameter bound */
  getBound(): Type | undefined;
}

/**
 * Base class for all type representations
 */
abstract class Type {
  /** Type discriminator */
  abstract readonly type: keyof TypeKindMap;
  
  /** String representation of type */
  toString(): string;
  /** Visit type with visitor pattern */
  visit<T>(visitor: TypeVisitor<T>): T;
  /** Check if type needs parentheses in context */
  needsParenthesis(context: TypeContext): boolean;
  /** Serialize type to JSON */
  toObject(serializer: Serializer): JSONOutput.SomeType;
}

/**
 * Reference to another type or reflection
 */
class ReferenceType extends Type {
  readonly type = "reference";
  /** Name of referenced type */
  name: string;
  /** Type arguments for generic references */
  typeArguments?: Type[];
  /** Referenced reflection if resolved */
  reflection?: Reflection;
  /** Symbol ID for external references */
  symbolId?: ReflectionSymbolId;
  /** Package name for external references */
  package?: string;

  /** Check if reference is resolved */
  isResolved(): boolean;
}

/**
 * Array type representation
 */
class ArrayType extends Type {
  readonly type = "array";
  /** Element type */
  elementType: Type;
}

/**
 * Union type representation  
 */
class UnionType extends Type {
  readonly type = "union";
  /** Union member types */
  types: Type[];
}

/**
 * Intersection type representation
 */
class IntersectionType extends Type {
  readonly type = "intersection"; 
  /** Intersection member types */
  types: Type[];
}

/**
 * Literal type representation
 */
class LiteralType extends Type {
  readonly type = "literal";
  /** Literal value */
  value: string | number | boolean | bigint | null;
}

/**
 * Intrinsic type representation (string, number, boolean, etc.)
 */
class IntrinsicType extends Type {
  readonly type = "intrinsic";
  /** Intrinsic type name */
  name: string;
}

/**
 * Conditional type representation (T extends U ? X : Y)
 */
class ConditionalType extends Type {
  readonly type = "conditional";
  /** Check type (T) */
  checkType: Type;
  /** Extends type (U) */
  extendsType: Type;
  /** True type (X) */
  trueType: Type;
  /** False type (Y) */
  falseType: Type;
}

/**
 * Mapped type representation
 */
class MappedType extends Type {
  readonly type = "mapped";
  /** Parameter name */
  parameter: string;
  /** Parameter type */
  parameterType: Type;
  /** Template type */
  templateType: Type;
  /** Readonly modifier */
  readonlyModifier?: "+" | "-";
  /** Optional modifier */
  optionalModifier?: "+" | "-";
  /** Name type for computed property names */
  nameType?: Type;
}

/**
 * Template literal type representation
 */
class TemplateStringType extends Type {
  readonly type = "templateString";
  /** Template head */
  head: string;
  /** Template spans */
  tail: [Type, string][];
}

/**
 * Parsed comment documentation
 */
class Comment {
  /** Summary section */
  summary: CommentDisplayPart[];
  /** Block tags (@param, @returns, etc.) */
  blockTags: CommentTag[];
  /** Modifier tags (@public, @internal, etc.) */
  modifierTags: Set<`@${string}`>;

  /** Get block tag by name */
  getTag(name: `@${string}`): CommentTag | undefined;
  /** Check if comment has modifier tag */
  hasModifier(name: `@${string}`): boolean;
  /** Remove block tag */
  removeTag(name: `@${string}`): void;
  /** Clone comment */
  clone(): Comment;
}

/**
 * Comment display part (text, code, links, etc.)
 */
interface CommentDisplayPart {
  /** Part kind */
  kind: string;
  /** Text content */
  text: string;
  /** Target for links */
  target?: Reflection | string;
}

/**
 * Block comment tag (@param, @returns, etc.)
 */
class CommentTag {
  /** Tag name including @ */
  tag: `@${string}`;
  /** Tag content */
  content: CommentDisplayPart[];
  /** Parameter name for @param tags */
  name?: string;
}

/**
 * Reference to source code location
 */
class SourceReference {
  /** Source file name */
  fileName: string;
  /** Line number (1-based) */
  line: number;
  /** Character position */
  character: number;
  /** URL to source file */
  url?: string;

  /** Get relative path */
  getRelativePath(base: string): string;
}

/**
 * Registry tracking all source files
 */
class FileRegistry {
  /** Add source file */
  addFile(file: string): void;
  /** Check if file is registered */
  hasFile(file: string): boolean;
  /** Get all registered files */
  getFiles(): string[];
  /** Clear registry */
  clear(): void;
}

/**
 * Group of related reflections
 */
class ReflectionGroup {
  /** Group title */
  title: string;
  /** Child reflections in group */
  children: Reflection[];
  /** Categories within group */
  categories?: ReflectionCategory[];

  /** Get all children recursively */
  getAllChildrenByKind(kind: ReflectionKind): Reflection[];
}

/**
 * Category for organizing reflections
 */
class ReflectionCategory {
  /** Category title */
  title: string;  
  /** Child reflections in category */
  children: Reflection[];

  /** Get children by kind */
  getChildrenByKind(kind: ReflectionKind): Reflection[];
}

/**
 * Symbol ID for tracking external references
 */
class ReflectionSymbolId {
  /** File name */
  fileName: string;
  /** Qualified name */
  qualifiedName: string;
  /** Position in file */
  pos: number;

  /** Get stable string representation */
  getStableKey(): string;
}

enum ReflectionKind {
  Project = 0x1,
  Module = 0x2,
  Namespace = 0x4,
  Enum = 0x8,
  EnumMember = 0x10,
  Variable = 0x20,
  Function = 0x40,
  Class = 0x80,
  Interface = 0x100,
  Constructor = 0x200,
  Property = 0x400,
  Method = 0x800,
  CallSignature = 0x1000,
  IndexSignature = 0x2000,
  ConstructorSignature = 0x4000,
  Parameter = 0x8000,
  TypeLiteral = 0x10000,
  TypeParameter = 0x20000,
  Accessor = 0x40000,
  GetSignature = 0x80000,
  SetSignature = 0x100000,
  ObjectLiteral = 0x200000,
  TypeAlias = 0x400000,
  Reference = 0x800000,
  Document = 0x1000000,
}

enum ReflectionFlag {
  None = 0,
  Private = 1,
  Protected = 2,
  Public = 4,
  Static = 8,
  External = 16,
  Optional = 32,
  Rest = 64,
  Abstract = 128,
  Const = 256,
  Readonly = 512,
  Inherited = 1024,
}

enum TypeContext {
  none,
  templateLiteralElement,
  mappedTypeParameter,
  conditionalCheckType,
  conditionalExtendsType,
  conditionalTrueType,
  conditionalFalseType,
  indexedAccessObjectType,
  indexedAccessIndexType,
  inferredConstraint,
}

interface TypeKindMap {
  array: ArrayType;
  conditional: ConditionalType;
  indexedAccess: IndexedAccessType;
  inferred: InferredType;
  intersection: IntersectionType;
  intrinsic: IntrinsicType;
  literal: LiteralType;
  mapped: MappedType;
  namedTupleMember: NamedTupleMemberType;
  optional: OptionalType;
  predicate: PredicateType;
  query: QueryType;
  reference: ReferenceType;
  reflection: ReflectionType;
  rest: RestType;
  templateString: TemplateStringType;
  tuple: TupleType;
  typeOperator: TypeOperatorType;
  union: UnionType;
  unknown: UnknownType;
}

/**
 * Reset the global reflection ID counter (for testing)
 */
function resetReflectionID(): void;

/**
 * Remove reflection from its parent container
 */
function removeReflectionFromParent(reflection: Reflection): void;

/**
 * Split unquoted string for comment parsing
 */
function splitUnquotedString(input: string, delimiter: string): string[];