/**
 * Semantic documentation model for doc-weaver.
 *
 * This mirrors doc-forge's renderer-agnostic model: a project is a
 * collection of modules, each module contains named documentation objects,
 * and objects may contain nested members. Renderers (MkDocs, MCP) consume
 * this model so that output formats never depend on each other.
 */

/** The set of documentable symbol kinds recognized by doc-weaver. */
export type DocKind =
  | 'module'
  | 'namespace'
  | 'class'
  | 'interface'
  | 'enum'
  | 'enum-member'
  | 'type-alias'
  | 'variable'
  | 'function'
  | 'method'
  | 'accessor'
  | 'property'
  | 'constructor'
  | 'signature'
  | 'parameter'
  | 'component'
  | 'hook'
  | 'unknown';

/** A documentation object with an optional tree of members. */
export interface DocObject {
  name: string;
  kind: DocKind;
  path: string;
  signature: string;
  docstring: string;
  members?: Record<string, DocObject>;
}

/** A single module (typically one source file or package). */
export interface DocModule {
  path: string;
  docstring: string;
  objects: Record<string, DocObject>;
}

/** The root semantic model produced by the loader. */
export interface DocProject {
  name: string;
  modules: DocModule[];
}