// src/services/metadata/types.ts
// Obsidian-compatible metadata type definitions.
// Most types match Obsidian's documented public TypeScript API exactly.
// Some types (FootnoteCache, FootnoteRefCache) include Reams-specific extensions
// for enhanced footnote display functionality.

/**
 * A location within a document (line, column, character offset).
 * Matches Obsidian's Loc type.
 */
export interface Loc {
  /** 0-indexed line number */
  line: number
  /** 0-indexed column number */
  col: number
  /** 0-indexed character offset from start of document */
  offset: number
}

/**
 * A position span with start and end locations.
 * Matches Obsidian's Pos type.
 */
export interface Pos {
  start: Loc
  end: Loc
}

/**
 * Base interface for all cache items.
 * Matches Obsidian's CacheItem type.
 * @public
 */
export interface CacheItem {
  /** Position of this item in the note. */
  position: Pos
}

/**
 * Base interface for items that point to a different location.
 * Matches Obsidian's Reference type.
 * @public
 */
export interface Reference {
  /**
   * Link destination.
   * @public
   */
  link: string
  /**
   * Contains the text as it's written in the document. Not available on Publish.
   * @public
   */
  original: string
  /**
   * Available if title is different from link text, in the case of `[[page name|display name]]` this will return `display name`
   * @public
   */
  displayText?: string
}

/**
 * A reference with position information.
 * Matches Obsidian's ReferenceCache type.
 * @public
 */
export interface ReferenceCache extends Reference, CacheItem {}

/**
 * A cached block reference (^block-id).
 * Matches Obsidian's BlockCache type.
 * @public
 */
export interface BlockCache extends CacheItem {
  /** The block identifier (without the ^ prefix) */
  id: string
}

/**
 * A cached wikilink reference.
 * Matches Obsidian's LinkCache type.
 * @public
 */
export interface LinkCache extends ReferenceCache {}

/**
 * A cached embed reference.
 * Matches Obsidian's EmbedCache type.
 * @public
 */
export interface EmbedCache extends ReferenceCache {}

/**
 * A cached tag reference.
 * Matches Obsidian's TagCache type.
 * @public
 */
export interface TagCache extends CacheItem {
  /** Tag including # prefix (e.g. "#todo", "#nested/tag") */
  tag: string
}

/**
 * A cached heading reference.
 * Matches Obsidian's HeadingCache type.
 * @public
 */
export interface HeadingCache extends CacheItem {
  /** Heading text (without # prefix) */
  heading: string
  /** Heading level (1-6) */
  level: number
}

/**
 * A cached list item reference.
 * Matches Obsidian's ListItemCache type.
 * @public
 */
export interface ListItemCache extends CacheItem {
  /**
   * The block ID of this list item, if defined.
   * @public
   */
  id?: string | undefined
  /**
   * A single character indicating the checked status of a task.
   * The space character `' '` is interpreted as an incomplete task.
   * Any other character is interpreted as completed task.
   * `undefined` if this item isn't a task.
   * @public
   */
  task?: string | undefined
  /**
   * Line number of the parent list item (position.start.line).
   * If this item has no parent (e.g. it's a root level list),
   * then this value is the negative of the line number of the first list item (start of the list).
   *
   * Can be used to deduce which list items belongs to the same group (item1.parent === item2.parent).
   * Can be used to reconstruct hierarchy information (parentItem.position.start.line === childItem.parent).
   * @public
   */
  parent: number
}

/**
 * A cached section reference.
 * Sections are root level markdown blocks, which can be used to divide the document up.
 * Matches Obsidian's SectionCache type.
 * @public
 */
export interface SectionCache extends CacheItem {
  /**
   * The block ID of this section, if defined.
   * @public
   */
  id?: string | undefined
  /**
   * The type string generated by the parser.
   * Typing is non-exhaustive, more types can be available than are documented here.
   * @public
   */
  type: 'blockquote' | 'callout' | 'code' | 'element' | 'footnoteDefinition' | 'heading' | 'html' | 'list' | 'paragraph' | 'table' | 'text' | 'thematicBreak' | 'yaml' | string
}

/**
 * A cached footnote reference (`[^id]` inline).
 * Matches Obsidian's FootnoteRefCache type exactly (extends CacheItem with `id`).
 * @public
 * @since 1.8.7
 */
export interface FootnoteRefCache extends CacheItem {
  /** Footnote id (e.g. "1" from [^1] or "custom-name" from [^custom-name]) */
  id: string
}

/**
 * Reams-extended FootnoteRefCache with additional fields for footnote display.
 * Use this type internally; export FootnoteRefCache for Obsidian API compatibility.
 * @public
 */
export interface ReamsFootnoteRefCache extends FootnoteRefCache {
  /** Original raw text (e.g. "[^1]"). Reams extension. */
  original?: string
}

/**
 * A cached footnote definition (`[^id]: body` at line start, body may
 * span multiple indented continuation lines).
 * Matches Obsidian's FootnoteCache type exactly (extends CacheItem with `id`).
 * @public
 * @since 1.6.6
 */
export interface FootnoteCache extends CacheItem {
  /** Footnote id (matches a FootnoteRefCache.id when resolved) */
  id: string
}

/**
 * Reams-extended FootnoteCache with additional fields for footnote display.
 * Use this type internally; export FootnoteCache for Obsidian API compatibility.
 * @public
 */
export interface ReamsFootnoteCache extends FootnoteCache {
  /**
   * Body text (excludes the `[^id]:` prefix; continuation lines joined with \n).
   * Reams extension.
   */
  body?: string
  /**
   * Original raw text covering the full definition span (no trailing newline).
   * Reams extension.
   */
  original?: string
}

/**
 * A cached reference link definition (`[id]: url` at line start).
 * Matches Obsidian's ReferenceLinkCache type (extends CacheItem with `id` and `link`).
 * @public
 * @since 1.8.7
 */
export interface ReferenceLinkCache extends CacheItem {
  /** Reference link id (e.g. "wiki" from `[wiki]: https://example.com`) */
  id: string
  /** The link destination URL */
  link: string
}

/**
 * Parsed frontmatter as a key-value record.
 * Matches Obsidian's FrontMatterCache type exactly.
 * A simple index signature: arbitrary YAML keys are accessible.
 *
 * NOTE: In Obsidian, frontmatter position is stored in CachedMetadata.frontmatterPosition,
 * NOT as a property on FrontMatterCache itself. See CachedMetadata below.
 */
export interface FrontMatterCache {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any
}

/**
 * A link found in the frontmatter of a document.
 * Matches Obsidian's FrontmatterLinkCache type (extends Reference with `key`).
 * @public
 * @since 1.4.0
 */
export interface FrontmatterLinkCache extends Reference {
  /**
   * @public
   */
  key: string
}

/**
 * Complete cached metadata for a single file.
 * Matches Obsidian's CachedMetadata type.
 */
export interface CachedMetadata {
  /** Non-embed wikilinks */
  links?: LinkCache[]
  /** Embed links (![[...]]) */
  embeds?: EmbedCache[]
  /** Tags (inline body tags only — frontmatter tags are on the frontmatter object) */
  tags?: TagCache[]
  /** Headings */
  headings?: HeadingCache[]
  /** Sections are root level markdown blocks, which can be used to divide the document up. */
  sections?: SectionCache[]
  /** List items (ordered and unordered, including task items) */
  listItems?: ListItemCache[]
  /** Parsed frontmatter key-value pairs, or null if no frontmatter */
  frontmatter?: FrontMatterCache | null
  /** Position of the frontmatter block */
  frontmatterPosition?: Pos
  /** Links found in frontmatter (e.g. [[wikilinks]] in YAML values) */
  frontmatterLinks?: FrontmatterLinkCache[]
  /** Footnote definitions ([^id]: body, possibly multi-line). */
  footnotes?: FootnoteCache[]
  /** Footnote references ([^id]). */
  footnoteRefs?: FootnoteRefCache[]
  /** Reference link definitions ([id]: url). */
  referenceLinks?: ReferenceLinkCache[]
  /** Block references (^block-id) mapped by their ID */
  blocks?: Record<string, BlockCache>
}