AsciiDoc 源文档包含可被作者直接观察的结构表面。标题创建 section 作用域。block metadata 附着到 section、listing、table 或其它 block。xref 和 anchor 在正文中创建可定位的出现点。显式 ID、inline anchor、listing ID 和 table ID 进入本地 target catalog。

下游程序需要这些事实，但不能直接依赖 Asciidoctor 内部对象形状。Asciidoctor official AST 提供结构解释；源文本提供 raw surface 和回源坐标。解析器把这两类事实放入同一个 TypeScript 数据模型。

本对象包含三个公共表面：

Pretty tree 和 JSON 必须来自同一个 AbundantDocument。序列化器不得重新解析 AsciiDoc，也不得从文本输出反推模型。

下游投影器是 AbundantDocument 的消费者。它读取 section、xref、target、listing 和 source coordinate，但它不属于解析器对象。

文档 lint 是相邻对象。解析器提供 target catalog、xref occurrence 和 diagnostics，但它不判断引用风格、业务语义或 schema 合法性。

站点生成器是相邻对象。解析器不生成 HTML、PDF、图片资源、导航页或部署产物。

完整 inline CST 恢复器是相邻对象。解析器保留本对象需要的 inline occurrence，不恢复所有 inline formatting 结构。

CLI 使用者读取 pretty tree 以观察文档结构。该动作需要稳定缩进、节点类型、关键字段和错误出口。

CLI 使用者读取 JSON 以交给其它程序。该动作需要 JSON 与 TypeScript 模型保持同一对象层级，并且不输出 undefined 字段。

TypeScript 调用者直接调用 parseAbundantTree 并读取 AbundantDocument。该动作需要稳定类型、稳定字段名和可区分的 source layer 与 official layer。

调用者遍历 section tree，读取 target catalog，检查 xref occurrence，定位 anchor occurrence，并根据 source span 回到源文件行列范围。

下游投影器消费 AbundantDocument，构造自己的公共图、索引或报告。投影器不得重新解析 AsciiDoc 源结构；它应使用解析器提供的 section、target、xref、anchor、block 和 source coordinate。

解析器不替下游投影器决定图形状。解析器只提供事实材料。

文档作者和修改执行者通过 source span 回到源文件。该动作要求 line number、column number 和 raw surface 与源文件一致。

解析器输出不能把派生表面伪装成源文件表面。source layer 字段必须能支持阅读、判断和修改循环。

测试者和审核者读取 diagnostics、source span、official binding 和序列化输出，以判断解析器是否满足本书契约。

完成声明必须提供行为证据。仅能运行、仅能输出文本、仅能通过局部快照都不能证明解析器对象已经成立。

library API 输入：

CLI 输入：

sourcePath 按当前进程工作目录解析。文件内容按 UTF-8 文本读取。行号使用 1-based line number。列号使用 1-based Unicode code point column。

single-file mode 只读取输入文件。该模式不展开 include directive，不打开跨文档 xref 指向的 .adoc 文件，也不构造 workspace graph。

跨文档 xref 作为 source occurrence 出现。解析器保存 raw target 和 official href，但不验证目标文档是否存在。

single-file mode 使用 @asciidoctor/core 解析输入文件。加载配置为：

safe: "secure" 支持 single-file 边界。include directive 在该模式下不会展开为外部文件内容。sourcemap: true 提供 official source location。to_file: false 避免输出文件副作用。

Asciidoctor source location 不独立定义完整 source span。解析器必须用源文本 line table 恢复 metadata、raw、content span 和 column span。

official block 的 source location 若指向输入文件之外的路径，single-file mode 不把该 block 投影成当前文件结构。

该情况进入 toolDiagnostics。解析器不得用当前文件 line table 强行解释外部 block。

AbundantDocument 表示一次解析结果。

sourcePath 是解析入口路径。mode 标记输入构造身份。parser 标记 official parser 名称和版本。children 保存文档结构树。targets 保存本地 target catalog。xrefOccurrences 和 anchorOccurrences 保存源文档中的 inline occurrence。toolDiagnostics 保存解析器诊断。

本书定义的解析器输出使用 mode: "single-file"。书稿入口回源逻辑文档规约 定义的 book-entry 输入构造要求 AbundantDocument 接受 book-entry mode，并保持节点、target、occurrence 和 diagnostic 语义不变。

sourceText 是可选源文本缓存。该字段服务需要从文档标题或其它顶层对象恢复 raw slice 的消费者。字段缺失表示该文本未随模型携带，不表示源文档没有文本。

ParserInfo 描述 official parser。

version 保留实际运行时事实。解析器行为不得以该字段作为分支开关。

AbundantNode 是文档树节点的 union。节点集合包含 section、paragraph、description list、description list item、description term、description、listing、table、metadata、xref occurrence、anchor occurrence、target、title、text 和 unknown。

节点类型描述解析器恢复出的 source-aware structure facts。节点类型不表示下游图投影的资源类型。

可选字段缺失表示该事实不存在、official parser 没有提供该事实，或 source recovery 无法可靠恢复该事实。实现不得用空字符串、零行号或伪造 span 表示未知事实。

工具错误不写入 AbundantDocument。输入读取失败、parser load 失败和内部不变量失败必须通过错误出口表达。

公共节点基底：

source 保存原始文本表面事实。asciidoctor 保存 official interpretation。children 保存解析器恢复出的结构包含关系。

TitleNode 表示 document title。document title 不等同于普通 section。

Title 保存标题文本和可恢复的 source location。没有源标题行时，解析器保留 official title text，且不得伪造 raw source。

SectionNode 表示等号标题创建的标题作用域容器。

字段包括：

official section tree 决定 section identity 和父子结构。source layer 恢复 raw、metadata、line span 和 title span。

ParagraphNode 表示 official paragraph block。Paragraph 保存 text，并在内容行存在 inline occurrence 时包含 xref 或 anchor occurrence 子节点。

Paragraph 不恢复完整 inline formatting CST。strong、emphasis、literal inline formatting 等表面在本对象中作为文本保留。

ListingNode 表示 listing、source 或 literal-like 代码块。

Listing 保存 explicit ID、block title、style、language、metadata、content、metadataSpan、contentSpan 和 span。

Listing span 覆盖 metadata、delimiter、content 和 closing delimiter。contentSpan 只覆盖内容行。

TableNode 表示 official table block。

Table 保存 explicit ID、block title、metadata、rows 和 source span。cells 是公共模型保留字段；解析器投影以 official row group 提供的 rows 为表格内容表面。Table 内容结构来自 Asciidoctor official table model；解析器不手写 table grammar。

DescriptionListNode 表示 official description list block。

Description list 保存 explicit ID、block title、style、delimiter、metadata、metadataSpan、contentSpan、span 和 items。delimiter 记录该 list authored surface 中的 description delimiter；它是 source evidence，不定义列表层级。

DescriptionListItemNode 表示一个 official description list item。Item 保存 terms、可选 description 和 item source line span。Item span 覆盖 term、直接 description text 和 description 子树中可恢复的 block surface。

DescriptionTermNode 表示 description list item 的 term surface。Term 保存 display text、line、sourceSpan、source layer 和 term 文本区内的 inline occurrence 子节点。

DescriptionNode 表示 description list item 的 description surface。Description 保存直接 description text、line、sourceSpan、source layer 和 attached block 或 nested description list 子节点。Description text 和 children 可以同时存在。

MetadataNode 表示附着到 block 或 section 的源文本 metadata surface。

Metadata kind 包括 id、title、attrlist、anchor 和 unknown。

Metadata raw 是 source layer 事实。解析器不得丢弃 raw metadata 后只保留 official attributes。

XrefOccurrenceNode 表示源文档中的一个交叉引用出现点。

它保存 raw、syntax、target、label、attributes、sourceSpan、containingSectionId 和 official binding facts。

targetKind 是词法提示，不是目标存在性判断。跨文档 xref 不触发外部文件读取。

AnchorOccurrenceNode 表示源文档中的 inline 或 block anchor 出现点。

它保存 raw、syntax、ids、reftext、sourceSpan、containingSectionId 和 anchorScope。

Anchor occurrence 与 target catalog entry 是不同投影。anchor occurrence 产生 target fact，且 occurrence 仍然保留其源文本位置。

TargetNode 表示当前 source document 内可被引用的本地 target。

targetType 包括 section、listing、table、inline-anchor、block 和 unknown。

Target 保存 ID、target type、title、id origin 和 sourceSpan。Target catalog 为下游消费者提供寻址事实，不定义下游如何投影这些 target。

LineSpan 表示连续行范围。

行号使用 1-based line number。startLine 和 endLine 均包含在范围内。

SourceSpan 表示行列范围。

列号使用 1-based Unicode code point column。end.column 表示 token 结束后的列位置。

SourceLayer 保存源文本事实。

raw 是源文件切片。line 是事实的起始行或主行。span 是行范围。sourceSpan 是行列范围。

Source layer 字段只能来自源文本或 source span recovery。Official parser 的解释结果不能覆盖 raw source surface。

AsciidoctorLayer 保存 official interpretation。

Official layer 字段只能来自 Asciidoctor official result 或 official conversion fragment。Source scanner 不得伪造 official binding。

公开坐标必须使用 1-based line 和 1-based column。

Raw slice、line span 和 source span 必须来自同一 source surface。实现不得把 official line number、source scanner raw 和另一个文件的 line table 混合成一个 source layer。

字段缺失必须保持缺失。实现不得用 0、-1、空 raw 或空 span 表示未知坐标。

Asciidoctor official document 提供 section tree、block context、block parent-child relation、refs catalog 和 official xref conversion。

解析器通过 official-block-walker 遍历 official block tree。walker 只读取 official block 属性，不扫描源文件。

Source surface 是 official block 在源文本中的可恢复表面。它包含 block 起点、metadata、content span、full span、title span 和 diagnostics。

source-interval-resolver 以 official block source location 为锚点恢复 source interval。Delimiter 查找只能在 official context 已确认的 block 内局部执行。

源码扫描不得创建 official AST 中不存在的 section、listing、table、literal、pass 或 open block。

源码扫描补充 metadata、raw、line span、column span、局部 delimiter confirmation 和 fallback diagnostic。

Fallback 必须锚定 official block。没有 official block 锚点时，解析器不得用全文件正则制造结构。

Inline occurrence scanner 按 official block context 扫描。

Paragraph、带 macros substitutions 的 prose block 和可扫描 table prose 产生 xref 或 anchor occurrence。Listing、literal、pass-through 和 fenced code content 不产生 xref 或 anchor occurrence。

Open block 是容器。它自身不产生 prose occurrence；occurrence 来自其 paragraph descendants。

Section scope 由 official section surfaces 和 source intervals 建立。Table cell、listing、pass-through 或 literal content 中的 section-looking text 不得污染 section tree。

sectionByLine 只能来自 official section surfaces。该映射服务 containingSectionId 和下游 source scope 查询。

Metadata surface 附着到紧随其后的 section 或 block。可附着 surface 包括 explicit ID、block title、attribute list 和 block anchor。

紧邻性是 metadata attachment 的前提。远离 block 的普通行不得被解释为该 block 的 metadata。

Xref occurrence 来自源文本中的 xref syntax。

解析器保存 raw selector、display label、named attributes、sourceSpan 和 official binding facts。

Xref occurrence 不验证外部 target。Interdocument target 保持 raw target 和 official href。

Anchor occurrence 来自 inline 或 block anchor syntax。

解析器保存 raw anchor、ID、reftext、sourceSpan 和 containingSectionId。

Target catalog 保存当前 source document 内可寻址 target。

Target 来自 section、listing、table、inline anchor 或 block anchor。Target type 是解析器事实，不是下游资源类型。

下游消费者把 target ID 解释为 label、link endpoint、lint 对象或其它投影事实。解析器不决定该投影。

Source layer occurrence 与 official layer binding 必须保持可区分。

Raw xref target 不被 official href 覆盖。Official reftext 不替代 source label。Binding merge 只把两个来源的事实放在同一个 occurrence 上。

工具错误阻止 AbundantDocument 成立。

工具错误包括输入文件不存在、文件读取失败、Asciidoctor load 失败、内部不变量失败和 serializer 收到未知不可处理对象。

工具错误通过错误出口表达。CLI 使用非零 exit code。Library API 抛出错误。

ToolDiagnostic 保存解析器在恢复 source surface 时发现的可报告问题。

Tool diagnostic 不作为 document child。它不参与 section tree，不替代 source node，也不表示文档 lint 结论。

Source recovery diagnostic 描述 official block 与 source surface 之间的恢复缺口。

示例包括 missing official source location、external source location、delimiter not found 和 unknown official block context。

出现恢复缺口时，解析器不得输出伪造精确坐标。可恢复的结构事实保留；不可靠的 source layer 字段必须缺失或附带 diagnostic。

引用风格检查、业务 schema 错误、block 内容内部字段错误、跨文档 target 是否存在，都不是解析器诊断。

这些判断属于下游 lint、业务 validator 或投影消费者。

公共解析入口：

parseAbundantTree 返回 AbundantDocument。调用者不需要解析 pretty tree 或 JSON。

公共序列化入口：

Serializer 只读取 AbundantDocument。Serializer 不读取文件，不调用 Asciidoctor，不扫描 AsciiDoc。

公共命令：

默认输出是 pretty tree。--json 是 --format json 的快捷入口。rdf12 和 rdf12-json-ld 是下游投影格式；它们消费同一个 AbundantDocument，不改变解析器对象定义。

CLI 参数错误、输入文件不存在和内部工具错误返回非零 exit code。成功输出写入 stdout。错误消息写入 stderr。

包导出 rdf12(document, options) 作为下游投影函数。下游投影函数以 AbundantDocument 为输入，并要求调用者提供自己的投影选项。

下游投影函数不改变解析器公共模型。它们定义自己的输出表面和验收条件。

项目位于：

该目录是内部 Git 仓库。外层 micheng-ts 工作区和内层 asciidoc-abundant-tree 仓库有不同 Git 边界。提交和状态检查必须在正确仓库中执行。

package 名称：

CLI bin 名称：

运行时是 Node.js ESM。源码使用 TypeScript strict。包管理使用 pnpm。

src/model.ts 定义公共 TypeScript 数据模型。

src/asciidoctor-adapter.ts 承载 @asciidoctor/core 和 HTML fragment parser 的直接调用。

src/parser.ts 编排文件读取、official parse、source surface projection、official projection、target/xref merge 和 AbundantDocument 构造。

src/source-lines.ts 提供 line table、line text、line span 和 source span 工具。

src/official-block-walker.ts 遍历 official AST。

src/source-interval-resolver.ts 从 official block anchor 恢复 source interval。

src/source-surfaces.ts 合成 sections、inline occurrences、anchor occurrences 和 diagnostics。

src/official-projector.ts 从 official block 和 source evidence 构造 document tree。

src/serializers.ts 只负责 pretty tree 和 JSON 序列化。

src/cli.ts 只负责 CLI 参数、错误出口和调用 public API。

解析器运行依赖 @asciidoctor/core 和 HTML fragment parser。解析器不引入站点生成器、数据库、UI 框架或部署工具。

每个 parser 运行依赖都必须服务本对象。相邻工具需要的依赖不得进入 parser 运行依赖。

提交在内部 Git 仓库中执行。未跟踪文件必须先进入 Git index。

每次提交只包含当前任务文件。构建产物、无关格式化和其它项目修改不得混入解析器提交。

解析器完成必须满足：

核心样例必须覆盖：

CLI 必须覆盖：

项目验证命令：

质量检查命令：

文档书架变更时，书架命令也必须运行：

未运行的验证不能写成通过。不可用命令必须报告不可用原因。

出现以下任一情况，不得声明完成：