remark 模块契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 在独立的 @astryxdesign/core/Markdown/remark 入口点中,createMarkdownRemarkTransform(plugin, ...settings) 返回一个用于 createMarkdownPlugin() 的 Markdown 变换。它既接受常规的 Unified/Remark 插件类型,也接受 Astryx 编写的类型。 |
| 行为 | 每次调用都会在一个全新、可变的规范树副本上运行一个仅同步变换的 Remark 插件,并附带一个隔离的受约束文件,然后接受无损往返或拒绝它。 |
| 对最终用户的影响 | 读者看到的要么是插件支持的变换结果,要么是最后一个有效可读文档;不受支持的行为绝不会静默丢弃、近似或伪造文档内容。 |
| 对构建者的影响 | 不导入任何内容的构建者不受影响。选择加入的构建者会导入此适配器,证明某个插件与 fixtures 兼容,并在插件偏离 profile 时读取一条诊断信息。 |
| 兼容性/就绪状态 | 增量且可选加入;除非被导入,否则不包含在 Markdown 的入口点以及仅 parser 或服务端 bundle 中。兼容性依据每个插件的证据,而非包身份。 |
| 审查检查 | 拒绝静默近似、字段丢失、恢复或重建的来源信息、作者编写或偏移的位置、编辑过的 Astryx 自有节点、原始标记通道、异步或处理器状态插件、插件编写的诊断文本、插件可能捕获并继续往后的拒绝、未处理的 rejection,以及 Markdown 或 parser 内的适配器导入。 |
| 治理规则 | spec:AST-036 FR18–FR20, FR24;component:Markdown FR12–FR16;architecture:public-component-api。 |
此表是审查投影;以下正文为权威内容。
意图¶
拥有现有 Remark 变换的团队应该能够在 Astryx Markdown 中复用兼容的变换,而无需采用 Unified 作为 Core 运行时、修改规范树,或削弱 Core 拥有的语义。此模块拥有这条狭窄的兼容边界:profile 接受什么、拒绝什么,以及拒绝如何保持可读。
profile 之外的一切都按关闭即失败(fail closed)处理。“Remark 兼容”是插件通过此模块测试中的 fixtures 赢得的声明,绝不由包名决定。
兼容性与迁移¶
- 已发布默认行为保持不变:
yes - 兼容性类别:增量、可选加入、单独导入;当适配器未被导入时,已发布的 Markdown、parser、Outline 或 bundle 行为不发生任何变化。
- 迁移决策:
spec:AST-036/DEC-3
面向使用方的迁移说明属于使用方文档和发布说明。
所有权边界¶
拥有
- 适配器的公共工厂、其可变的 Remark 树类型,以及其受约束的文件类型。
- 受支持子集的无损往返,以及下文中的确切拒绝条件。
- 每次调用时隔离的副本、文件数据和诊断信息。
- 它自己的、证明一个真实插件兼容的证据。
不拥有 / 非目标
- 插件准入、变换排序、验证和失败恢复——由
component:Markdown和spec:AST-036拥有。 - Unified 处理器、parser 或 compiler 注册、micromark 扩展、异步流水线,以及受约束文件之外的
VFile行为。 - 标题身份、导航、资源策略、列表、表格和文档语义——由 Core 拥有。
公共 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
createMarkdownRemarkTransform |
(plugin, ...settings) => MarkdownTransform |
适配一个采用 attacher 形式的 Remark 插件;attacher 运行一次,其 transformer 在每次运行时执行一次。 | 无 | module:Markdown/remark |
稳定 |
| 适配树 | 受支持的 MDAST 子集外加 Astryx 流程图像、引文和扩展 | 插件可以修改或替换的全新可变副本。 | 每次运行全新 | module:Markdown/remark |
稳定 |
| 受约束文件 | value、data、messages、message()、fail()、toString() |
只读源、每次运行的类 JSON 数据以及诊断信息。 | 空 data |
module:Markdown/remark |
稳定 |
| 受支持的插件类型 | MarkdownRemarkPlugin 或 MarkdownRemarkCompatiblePlugin |
新插件可以针对类型化的 Astryx 树编写;结构上接受传统的 Unified/Remark 插件类型,包括声明为异步或回调式的转换器,但运行时随后会将其拒绝。 | 结构性 | module:Markdown/remark |
稳定 |
| 拒绝 | 一条诊断信息加上最后有效的文档 | 对配置范围之外的任何内容,采用故障关闭(fail-closed)的结果。 | 不适用 | module:Markdown/remark |
稳定 |
行为契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 适配器只接受这样的插件:其附加函数(attacher)同步返回一个至多接受两个参数的转换器。解析器、编译器、异步、回调式或仅注册型插件都会被拒绝。 | spec:AST-036 FR18 |
| FR2 | 每次调用都会收到规范树的全新可变副本和一个新的受约束文件。任何规范节点、数组、数据值或位置都不可变,且运行之间不保留任何状态。 | spec:AST-036 FR10, FR18 |
| FR3 | 受约束文件仅公开 value、data、messages、message()、fail() 和 toString()。任何其他键——path、cwd、history 或其他任何键——在读取、写入、定义和删除时都会故障关闭(fail-closed),而不是返回 undefined;in 运算符和键枚举会如实回答,以便插件进行特性检测。处理器访问同样故障关闭。 |
spec:AST-036 FR18 |
| FR4 | 只有当每个节点和元数据字段都能通过受支持的子集无损往返(round-trip)时,返回或修改后的树才会被接受——包括围栏代码的 meta;否则保留最后有效的文档。 |
spec:AST-036 FR19 |
| FR5 | 存活的源支撑节点必须精确保持 Core 的来源信息:两个位置点上的每一行、列和偏移都必须原样返回。重建、重设类型、复制或移位的存活节点都会被拒绝,绝不会被静默恢复。源支撑节点(包括标题)可以移除或重新排序;存活的源标题保持其原有层级深度。 | spec:AST-036 FR11, FR19, FR26 |
| FR6 | Astryx 拥有的引文和插件扩展节点仅在每个自有字段——包括 data 和创作的 source——完全相等时才原样通过。通过适配器创作或编辑其中一个会被拒绝。 |
spec:AST-036 FR11, FR15 |
| FR7 | 一次失败的运行只报告一条诊断信息,且该诊断仅由适配器自身的词汇构成,并且只能从适配器拥有的状态中读取,绝不来自抛出的值或插件可重写的任何对象。插件创作的文本——抛出的错误、fail() 原因、message() 诊断——永远不会成为诊断信息,因为插件读取过文档,可能会引用其中的内容。插件捕获后继续绕过的任何拒绝仍会使运行失败,且报告的是第一条记录的原因。后续插件和渲染会继续基于最后一个有效文档进行。 |
spec:AST-036 FR12 |
| FR8 | 未更改的文档返回相同的规范根节点,因此经过适配的空操作不会产生树分配,也不会导致下游失效。 | spec:AST-036 FR13, FR21 |
| FR9 | 适配器是一个独立的入口点,Markdown、解析器和插件协议都不会导入它,因此仅解析器 bundle 和服务端 bundle 会将其排除,除非调用方导入它。它已在导出生成器中注册,因此已发布的子路径不会与源代码发生漂移。 | spec:AST-036 FR24 |
| FR10 | 常规的 Unified/Remark 插件在调用点即可通过类型检查,无需重写,包括声明了 Unified 回调参数或异步返回联合类型的转换器。运行时仍会拒绝实际的 promise 和回调风格的转换器。 | spec:AST-036 FR18 |
| FR11 | 来自 attacher 或 transformer 的、被适配器拒绝的 promise,会在应用任何其他判定之前挂上拒绝处理程序;因此,一个既因其他原因被拒收又被拒绝的结果,不会以未处理拒绝的形式浮出水面。这在服务端最为重要,因为未处理的拒绝默认会终止进程,并打印出从文档中提取的、由插件编写的原因。then 只被读取一次,因为读取它本身就可能抛出异常或触发守卫。 |
spec:AST-036 FR12, FR18 |
| FR12 | 粘性拒绝会在验证后的输出变为可观察之前立即重新检查,因此一个触发较晚的守卫——在恶意 then 访问器内部,或在结果被验证时读取的 getter 中——仍然会拒绝,而不是让插件的输出通过。 |
spec:AST-036 FR12 |
支持的往返¶
| 输入 | 往返行为 |
|---|---|
root, paragraph, heading, blockquote, thematicBreak |
结构和子节点;标题深度仍由 Core 所有。 |
text、strong、emphasis、delete、inlineCode、break |
值及有序的短语子节点。 |
link、image |
url 由导航与资源所有者重新验证;alt 必填;title 为 null。 |
list、listItem |
ordered、start、spread、Astryx delimiter 和 checked。 |
code |
lang 和 meta,缺省时均为 null,外加 value。作者编写的 info 字符串在两次转换后仍存活,发布的语言投影也得以保留。 |
math、inlineMath |
仅当调用方启用数学支持时才存在。 |
table、tableRow、tableCell |
规范化的 align 与单元格子节点。 |
Astryx 流式图片、citation、extension |
作为受管节点保留;插件可读,但不可写。 |
position、data |
由 Core 生成的 position 和有限的 JSON 类数据。 |
拒绝矩阵¶
| 被拒绝的输入 | 结果 |
|---|---|
| 异步、回调风格、仅注册或处理器状态的插件 | 最后一个有效文档加一条诊断;FR1、FR3 |
html 或支持子集之外的任何节点(定义、引用、脚注、frontmatter、指令、MDX) |
最后一个有效文档加一条诊断;FR4 |
不支持的字段、hName、hProperties、hChildren,或非 JSON 节点/文件数据 |
最后一个有效文档加一条诊断;FR3、FR4 |
非字符串的围栏 meta、链接或图片的 title、松散的列表项,或参差不齐的转换后表格 |
最后一个有效文档加一条诊断;FR4 |
读取、写入、定义或删除不支持的文件键——path、cwd、history 或任何其他键 |
最后一个有效文档加一条诊断;FR3 |
| 在存活的源支持节点上编写、移动或移除 position;重建、重输入或复制的源节点;或重新调整级别的源标题 | 最后一个有效文档加一条诊断;FR5 |
| 在原本未变的偏移上移动行号或列号 | 最后一个有效文档加一条诊断;FR5 |
| 从复制的 position 重建的溯源信息,或从另一个文档夹带进来的溯源信息 | 最后一个有效文档加一条诊断;FR5 |
编写或编辑 Astryx citation 或 extension 节点,包括 data 和 source |
最后一个有效文档加一条诊断;FR6 |
| 被拒绝的链接或图片 URL、无效的内置结构、嵌套链接,或内联入口点产生的块级输出 | 最后一个有效文档加一条诊断;FR4 |
抛出异常的 transformer,或插件捕获后继续绕过的任何拒绝,包括 fail() |
最后一个有效文档加一条诊断;FR7 |
| 来自 attacher 或 transformer 的被拒绝 promise,无论是单独出现还是叠加在已捕获的拒绝之上 | 最后一个有效文档,一条诊断,无未处理的拒绝;FR11 |
在验证期间,于 then 访问器或 getter 读取中触发过晚的守卫 |
最后一个有效文档加一条诊断;FR12 |
转换与优先级顺序¶
- ORD1 — 一次运行。 规范树 → 新的可变副本 → 插件的单个同步 transformer → 经过验证的往返转换 → 供后续插件和渲染观察的文档。Core 会再次验证结果;适配器绝不替代 Core 自身的验证。
- ORD2 — 一条诊断,由适配器撰写。 成功运行保持静默;Core 唯一的诊断通道只报告插件失败,因此没有可如实说明的内容。失败运行恰好报告一行,使用本模块自身的语汇构建。插件记录的消息保留在其自己的文件上,只有该插件能看到。
- ORD3 — 先解除风险,再判断,后接受。 在应用任何判定之前,先检查并解除返回值的风险,因此运行被拒绝的原因永远不会决定 promise 是否被遗留为悬空状态。在接受输出之前会立即再次检查粘性拒绝,因为守卫可能在适配器接触插件控制的值的任何时刻触发。
性能与资源¶
- PR1 — 每次调用一份副本。 每次运行的工作量与文档大小成正比; 未更改的文档会返回规范根节点本身。
- PR2 — 无运行时依赖。 适配器不添加 Unified、Remark、mdast
或
VFile依赖,也不进行解析工作;它在现有转换阶段内运行, 不会触发重新解析。
无障碍契约¶
- AR1 — 必要语义得以保留。 图片必须保留其文本替代内容, 且源标题必须保留其层级;因此宁可拒绝,也不允许出现 无障碍名称或文档大纲的回归。
- AR2 — 无标记通道。 原始 HTML 和 hast 属性通道均被拒绝, 因此适配后的插件无法注入无标签或非语义的输出。
设计关系¶
该兼容适配器不拥有任何视觉表示;适配后的输出通过 Markdown 的现有部分渲染。
父级与系统关系¶
component:Markdown拥有聚合插件应用、验证、回退和标题身份。spec:AST-036拥有协议、规范 MDAST 兼容矩阵, 以及本记录所实现的受限 Remark 配置。family:navigation-destinations保持对所有适配后链接目标和图片资源的所有权。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | remark.test.tsx 的挂载、隔离与受限文件测试夹具 |
异步、回调式、处理器状态、仅注册型插件;重复调用;每个不支持的键,读取与写入;被捕获的守卫拒绝 | 若接受其中任一情况、在运行之间泄漏文件数据,或让已捕获的拒绝清除判定结果,则测试夹具失败。 |
| FR4–FR6 | remark.test.tsx 的往返与拒绝矩阵,包括解析围栏身份测试夹具 |
每种受支持的节点类型;带和不带信息字符串的围栏;上述每个被拒绝的输入;归属的引用与扩展节点 | 若静默丢弃某个字段(包括 meta)、接受一个不受支持的节点,或编辑归属节点,则封闭式测试夹具失败。 |
| FR7 | remark.test.tsx 的诊断信息以及拒绝后的 Markdown 渲染 |
抛出的转换器、被吞掉的 fail()、使用适配器自身类构造的伪造拒绝、被重写的 message、手动标记的致命消息、同一列表中的后续插件 |
若出现缺失、重复或插件生成的诊断,被吞掉的失败仍成功,或兄弟插件丢失,则测试失败。 |
| FR8 | remark.test.tsx 覆盖完整受支持文档的身份测试夹具 |
带有位置、数学、引用和扩展节点的未改动文档 | 若返回副本而非规范根节点,则身份测试失败。 |
| FR9 | remark.test.tsx 导入与清单测试夹具;sync:exports:check |
Markdown、解析器和插件模块;已发布的入口点 | 若在 Core 的 Markdown 路径中出现适配器导入,或存在未注册子路径,则测试失败。 |
| FR10 | remark.test.tsx 针对 Unified 形状声明的编译测试夹具 |
绑定到处理器的 attacher;回调参数与 async-union 转换器;内联 Astryx 插件 | 若收窄接受类型导致常规插件无法编译,则测试夹具失败。 |
| FR11 | remark.test.tsx 观察 process 未处理拒绝的拒绝测试夹具,包括服务端渲染 |
被拒绝的 attacher 结果;被拒绝的转换器结果;在已捕获守卫或已捕获的 fail() 之上被拒绝的结果;then 抛错的 thenable 对象 |
若在解除风险前应用判定,或在不附加处理器的情况下拒绝,则测试夹具失败。 |
| FR12 | remark.test.tsx 延迟守卫测试夹具 |
恶意的 then 访问器;在结果验证期间触发守卫的 getter |
若移除最终的粘性复核,则会让已捕获守卫的输出通过,并导致测试夹具失败。 |
决策日志¶
DEC-1 — 无损往返或可读的拒绝¶
参考: module:Markdown/remark/DEC-1
决策者: cixzhang,2026-09-15
该适配器从不会近似处理。链接标题、松散列表项、原始标记、
不支持的节点以及 Astryx 无法表示的元数据——包括
非字符串围栏 meta——对 Astryx 而言没有意义,因此接受它们将
静默改变或丢弃读者所见的内容。作者编写的围栏信息字符串
在此处确实有意义,并能原样往返;仅当它不是字符串时才会被拒绝。
拒绝其余内容可让最后一个有效文档保持可读,并通过一条诊断
让构建者看到差距,而不是让读者面对缺失的内容。
DEC-2 — 出处是携带的,绝不由推断而来¶
参考: module:Markdown/remark/DEC-2
决策者: cixzhang, 2026-09-15
一个被转换的节点只有携带着适配器放在副本上的标记时,才归属于某个源节点;仅凭一个看起来正确的位置进行匹配,会让重建的节点继承它从未有过的出处。相等性在每一行、每一列、每个偏移量上都是精确的,因为在已变更的位置之上恢复 Core 的位置,正是该配置存在所要拒绝的静默近似。
DEC-3 — 诊断中只有适配器发言¶
参考: module:Markdown/remark/DEC-3
决策者: cixzhang, 2026-09-15
插件自己的文本是从文档传到它那里的,并且可能引用文档中的任何内容;因此转发这些文本会把开发者警告变成私有内容泄露的渠道。相反,唯一报告的那一行由本模块的词汇拼装而成;插件的消息仍留在交给它的那个文件上。
插件能触及的一切,它也能改写:message 在任何 Error 上都是可写的,而捕获一次 rejection 会把该 rejection 本身交到它手中。因此,报告的原因是从适配器拥有的、以被抛出的对象为键的状态中读取的;每一次拒绝——被禁止的文件键、对 processor 的访问、插件自己的 fail()——都被记录在适配器拥有的运行状态中,而不是记录在插件持有的任何东西上。插件捕获后继续执行的拒绝仍会使本次运行失败,而最先记录的原因就是最终报告的原因。
DEC-4 — 归属节点仍归 Core 所有¶
参考: module:Markdown/remark/DEC-4
决策者: cixzhang, 2026-09-15
经过适配的插件可以读取 Astryx 引文节点或扩展节点,但不能创建或编辑这类节点,也不能更改源标题。归属节点正是 Markdown、Outline 与回退就同一份文档达成一致的方式;兼容性垫片不是让它们发生漂移的合适位置。
DEC-5 — 接受 Remark 已有的插件类型¶
参考: module:Markdown/remark/DEC-5
决策者: cixzhang, 2026-09-15
该配置的全部意义在于复用现有插件,因此针对 Unified 编写类型的插件必须能原样在此编译——Unified 声明了一个 transformer 类型,同时携带回调参数和异步返回值;如果在类型层面拒绝它,就会拒绝所有真实插件。适配器在结构上接受该形状,并在运行时拒绝不支持的行为;此时它可以带着一份可读的文档失败关闭(fail closed)。针对 Astryx 编写新插件的作者,用 MarkdownRemarkPlugin 对其进行注解,并保持一棵完全类型化的树。
开放问题¶
无。
内容边界¶
本记录不重复消费者签名或示例、权威插件协议、Markdown 的聚合应用与回退规则、AST 兼容性矩阵,也不重复 Remark 自己的文档。它链接到它们各自的属主。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx