AsciiDoc Parser - Component Specification

include::path/to/file.adoc[]
include::{includedir}/file.adoc[]
include::chapter.adoc[leveloffset=+1]
include::code.py[lines=5..10]

:includedir: chapters
:lang: en

include::{includedir}/{lang}/intro.adoc[]
// Resolves to: chapters/en/intro.adoc

@dataclass
class SourceLocation:
    """Position in source document."""
    file: Path              # Original file (not resolved include file)
    line: int               # 1-based line number in this file
    resolved_from: Path | None  # If included via include directive

Scenario: Circular includes are detected
  Given File A contains "include::B.adoc[]"
  And File B contains "include::A.adoc[]"
  When the parser processes File A
  Then a CircularIncludeError is thrown
  And the include chain is specified in the error

// Set attribute
:author: John Doe
:revdate: 2024-01-15
:imagesdir: ./images

// Unset attribute
:!draft:

// Attribute reference
The author is {author}.

:jbake-title: My Document
:jbake-type: page_toc
:jbake-status: published
:jbake-menu: main
:jbake-order: 5

[source,python]
.Optional Title

[plantuml, diagram-name, svg]
----
@startuml
Alice -> Bob: Hello
@enduml
----

.Table Title
[cols="1,2,3"]
|===
| Header 1 | Header 2 | Header 3

| Cell 1   | Cell 2   | Cell 3
|===

// Block image
image::path/to/image.png[Alt Text, 400, 300]

// With title
.Image Title
image::diagram.svg[Architecture Diagram]

NOTE: This is a note.

WARNING: This is a warning.

[TIP]
====
This is a multi-line tip.
With multiple paragraphs.
====

// Internal reference
<<section-anchor>>
<<section-anchor,Custom Text>>

// External reference (xref)
xref:other-file.adoc#anchor[Link Text]
xref:other-file.adoc[]

@dataclass
class CrossReference:
    """A captured cross-reference."""
    type: Literal["internal", "external"]
    target: str                 # Anchor or file#anchor
    text: str | None           # Optional link text
    source_location: SourceLocation

@dataclass
class AsciidocDocument:
    """Represents a parsed AsciiDoc document."""
    file_path: Path
    title: str
    attributes: dict[str, str]
    sections: list[AsciidocSection]
    elements: list[AsciidocElement]
    cross_references: list[CrossReference]
    includes: list[IncludeInfo]         # All resolved includes

@dataclass
class AsciidocSection:
    """A section in the document."""
    title: str
    level: int                          # 0-5 (0 = document title)
    anchor: str | None                  # [[anchor]] if present
    source_location: SourceLocation
    path: str                           # Hierarchical path
    children: list[AsciidocSection]

@dataclass
class AsciidocElement:
    """An extractable element."""
    type: Literal["code", "plantuml", "mermaid", "ditaa", "table", "image", "admonition", "list"]
    source_location: SourceLocation
    attributes: dict[str, Any]          # Type-specific attributes
    parent_section: str                 # Path of containing section

@dataclass
class IncludeInfo:
    """Information about a resolved include."""
    source_location: SourceLocation     # Where the include is located
    target_path: Path                   # Resolved target path
    options: dict[str, str]             # leveloffset, lines, etc.

Scenario: Sections are correctly extracted
  Given an AsciiDoc file with the following content:
    """
    = Main Title

    == Chapter 1

    Text...

    == Chapter 2

    === Subchapter
    """
  When the parser processes the file
  Then 4 sections are extracted
  And the hierarchy is:
    | path                        | level |
    | /main-title                 | 0     |
    | /main-title/chapter-1       | 1     |
    | /main-title/chapter-2       | 1     |
    | /main-title/chapter-2/subchapter | 2 |

Scenario: Attributes are correctly resolved
  Given an AsciiDoc file with the following content:
    """
    :author: John Doe
    :project: MCP Server

    = {project} Documentation

    Author: {author}
    """
  When the parser processes the file
  Then the document title is "MCP Server Documentation"
  And attributes["author"] is "John Doe"

Scenario: Includes are recursively resolved
  Given a main file "main.adoc":
    """
    = Main Document

    \include::chapter.adoc[leveloffset=+1]
    """
  And an include file "chapter.adoc":
    """
    = Chapter

    Chapter content.
    """
  When the parser processes "main.adoc"
  Then the document contains 2 sections
  And the section "Chapter" has level 1 (due to leveloffset)
  And the source_location of "Chapter" points to "chapter.adoc"

Scenario: Circular includes are detected
  Given a file "a.adoc" with "include::b.adoc[]"
  And a file "b.adoc" with "include::a.adoc[]"
  When the parser processes "a.adoc"
  Then a CircularIncludeError is thrown
  And the error message contains "a.adoc -> b.adoc -> a.adoc"

Scenario: Source blocks are extracted
  Given an AsciiDoc file with a Python source block
  When the parser processes the file
  Then elements contains an entry of type "code"
  And its language equals "python"
  And source_location points to the correct file and line

Scenario: PlantUML blocks are extracted as their own type
  Given an AsciiDoc file with:
    """
    [plantuml, my-diagram, svg]
    ----
    @startuml
    A -> B
    @enduml
    ----
    """
  When the parser processes the file
  Then elements contains an entry of type "plantuml"
  And name equals "my-diagram"
  And format equals "svg"

Scenario: Admonitions are extracted
  Given an AsciiDoc file with "WARNING: Important notice"
  When the parser processes the file
  Then elements contains an entry of type "admonition"
  And admonition_type equals "WARNING"

Scenario: Cross-references are captured
  Given an AsciiDoc file with:
    """
    See <<section-a>> and xref:other.adoc#anchor[Link].
    """
  When the parser processes the file
  Then cross_references contains 2 entries
  And the first is type="internal", target="section-a"
  And the second is type="external", target="other.adoc#anchor"

Scenario: Attributes in include paths are resolved
  Given an AsciiDoc file with:
    """
    :chaptersdir: chapters

    \include::{chaptersdir}/intro.adoc[]
    """
  And a file "chapters/intro.adoc" exists
  When the parser processes the file
  Then "chapters/intro.adoc" is successfully included

class AsciidocParser:
    """Parser for AsciiDoc documents."""

    def __init__(self, base_path: Path, max_include_depth: int = 20):
        """
        Initializes the parser.

        Args:
            base_path: Base path for relative include resolution
            max_include_depth: Maximum include depth
        """
        ...

    def parse_file(self, file_path: Path) -> AsciidocDocument:
        """
        Parses an AsciiDoc file with include resolution.

        Raises:
            FileNotFoundError: File does not exist
            CircularIncludeError: Circular include detected
            IncludeNotFoundError: Include file not found
        """
        ...

    def get_section(self, doc: AsciidocDocument, path: str) -> AsciidocSection | None:
        """Finds a section by its hierarchical path."""
        ...

    def get_elements(
        self,
        doc: AsciidocDocument,
        element_type: str | None = None
    ) -> list[AsciidocElement]:
        """Returns all elements, optionally filtered by type."""
        ...

    def validate_cross_references(
        self,
        doc: AsciidocDocument
    ) -> list[ValidationError]:
        """Checks all cross-references for validity."""
        ...

# Section (Level 0-5)
SECTION_PATTERN = r'^(={1,6})\s+(.+?)(?:\s+=*)?$'

# Document attribute
ATTRIBUTE_PATTERN = r'^:([a-zA-Z0-9_-]+):\s*(.*)$'

# Unset attribute
ATTRIBUTE_UNSET_PATTERN = r'^:!([a-zA-Z0-9_-]+):$'

# Attribute reference
ATTRIBUTE_REF_PATTERN = r'\{([a-zA-Z0-9_-]+)\}'

# Include directive
INCLUDE_PATTERN = r'^include::(.+?)\[(.*?)\]$'

# Source block start
SOURCE_BLOCK_PATTERN = r'^\[source(?:,\s*(\w+))?\]$'

# PlantUML block start
PLANTUML_PATTERN = r'^\[plantuml(?:,\s*([^,\]]+))?(?:,\s*(\w+))?\]$'

# Mermaid block start (Issue #122)
MERMAID_PATTERN = r'^\[mermaid(?:,\s*([^,\]]+))?(?:,\s*(\w+))?\]$'

# Ditaa block start (Issue #122)
DITAA_PATTERN = r'^\[ditaa(?:,\s*([^,\]]+))?(?:,\s*(\w+))?\]$'

# Block delimiter
BLOCK_DELIMITER = r'^(-{4,}|={4,}|\*{4,}|_{4,})$'

# Block image
BLOCK_IMAGE_PATTERN = r'^image::(.+?)\[(.*)?]$'

# Admonition (short form)
ADMONITION_SHORT_PATTERN = r'^(NOTE|TIP|WARNING|CAUTION|IMPORTANT):\s*(.+)$'

# Cross-reference (internal)
XREF_INTERNAL_PATTERN = r'<<([^,>]+)(?:,([^>]+))?>>`

# Cross-reference (external)
XREF_EXTERNAL_PATTERN = r'xref:([^#\[]+)?(?:#([^\[]+))?\[([^\]]*)\]'

# Anchor
ANCHOR_PATTERN = r'^\[\[([^\]]+)\]\]$'

# Table start/end
TABLE_DELIMITER = r'^\|===$'