日本語|English

remark 13移行:破壊点

VFMをremark 13へ移行すると必ず壊れる箇所(Phase 0-3, #279)。各項目に、該当コード、壊れる理由、remark 13での対応物、修正、担当Phase、検証方法を記す。最初の9件は#279の一覧で、残りはpackages/vfm インベントリとサブパッケージ調査を書く中で見つけたもの。上流の挙動は2026-10-17にpnpm storeのパッケージ(unified 11.0.5, remark-parse 11.0.0, mdast-util-to-hast 13.2.1, hastscript 9.0.1, hast-util-raw 9.1.0, refractor 5.0.0)で確認した。

Phaseは#275のsub-issueを指す: Phase 2 #281 (基盤ライブラリ)、Phase 3 #285 (構文プラグインのmicromark化)、Phase 4 #293 (検証とテスト)。

一覧

# 破壊点 種類 Phase
1 旧tokenizer拡張 無言で無効 3
2 to-hast handlerの署名 実行時エラー 2
3 unifiedのimport形式 コンパイル エラー 2
4 remark-parseのオプション 無言で無効 2
5 deep import 解決エラー 2
6 Image.alt の再パース 出力不正 3
7 旧Parser内部のテスト テスト失敗 4
8 @types/mdast 4の型名 コンパイル エラー 2
9 テストのMDAST期待値 テスト失敗 4
10 hastscript 9のchild / properties判定 出力不正 2
11 footnoteById が Map 実行時エラー 2
12 mdast-util-to-hast 13のendnote footer 出力不正 2
13 refractor 5が Root を返す 出力不正 2
14 hast-util-raw 9の署名 コンパイル エラー 2
15 inline footnoteノードの消滅 無言で無効 3
16 math.ts の findAndReplace フォールバック 出力不正 3
17 旧方式の外部プラグイン 無言で無効 3
18 サブパッケージのテスト ユーティリティ テスト失敗 4
19 1つのworkspaceに2世代が併存することによる型解決 コンパイル エラー 1 / 2

「無言で無効」の項目が危険。ビルドもプロセッサも動き、HTML出力を見るまで構文がパースされていないことに気付けない。

#279の項目

1.旧tokenizer拡張

  • 場所
    • packages/vfm/src/plugins/math.ts (mdast)
    • packages/remark-ruby/src/ruby.ts (mdast)
  • 理由
    • 両者ともtokenizerを this.Parser.prototype.inlineTokenizers / inlineMethods に付ける。remark-parse 10以降は this.parser (小文字)に mdast-util-from-markdown のラッパーを設定し、unified 11には Parser が無いため、this.Parser は undefined。両プラグインはこれをガードにしており(if (!this.Parser) return)、何もしない。$...$ と {base|ruby} の構文はプレーンテキストとして出る。
  • 対応物
    • this.data('micromarkExtensions') で登録するmicromark構文拡張
    • this.data('fromMarkdownExtensions') で登録する mdast-util-from-markdown 拡張
    • remark-parse 11は両リストを読む。
  • 修正
    • 両者をmicromark + from-markdown拡張として書き直す。
    • mathはremark-math 6が候補(#224)。ノード名(inlineMath / math)とフィールド(value)がVFM (inlineMath / displayMath, data.value)と異なるため、handlerを変えるかVFM拡張で旧形状を保つ。
    • rubyはベース テキストをmicromarkにトークン化させるインライン拡張が必要で、入れ子のインライン記法を維持する。
  • 検証
    • tests/math.test.ts
    • tests/math-mathml.test.ts
    • packages/remark-ruby/tests/ruby.test.ts
    • 構文が無言で未パースだと失敗するテストを足す(例: mathテストの出力にリテラルの $ が残らないことを確認する)。

2. to-hast handlerの署名

  • 場所
    • math.ts (handlerInlineMath, handlerDisplayMath)
    • math.ts (buildDisplayMath、ノードのみ受け取る)
    • code.ts (handler)
    • revive-rehype.ts (paragraph)
    • figure.ts (buildFigure)
    • remark-ruby (handler)
    • mdast-to-hast-table-cell (withTableCellTransform, TableCellHook)
    • remark-footnote-dpub / gcpm (各3 handler)
  • 理由
    • mdast-util-to-hast 13はhandlerを (state, node, parent) で呼ぶ。h(node, tagName, props, children) は無くなり、all と one はexportされない。
  • 対応物
    • state.all(node)
    • state.one(node, parent)
    • state.patch(node, element) (positionをコピー)
    • state.applyData(node, element) (hName / hProperties / hChildren を適用)
    • 要素はplain objectかhastscriptで組む。
  • 修正
    • 各handlerを変換する。{ h } を受け取る mdast-to-hast-table-cell の公開型 TableCellHook は { state } か絞った部分集合になる。
  • 検証
    • 全handlerテストのHTML期待値
    • editPlugins によるhandler置き換えは tests/edit-plugins.test.ts

3. unifiedのimport形式

  • 場所
    • packages/vfm/src/index.ts
    • packages/vfm/src/utils.ts
    • packages/vfm/src/revive-parse.ts
    • packages/vfm/src/revive-rehype.ts
    • packages/vfm/src/plugins/metadata.ts
    • packages/vfm/src/plugins/figure.ts
    • packages/vfm/src/plugins/footnotes.ts
    • packages/vfm/src/plugins/math.ts
    • remark-footnote-{dpub,gcpm,pandoc}
    • すべてのテスト ユーティリティ
  • 理由
    • unified 10以降は { unified } と名前付き型(Plugin, Pluggable, PluggableList, Processor, Transformer)をexportする。import unified from 'unified' と unified.Plugin はコンパイルできない。
  • 対応物
    • import { unified, type Plugin, type Pluggable } from 'unified'。Plugin はパラメーターとツリー型のジェネリック。
  • 修正
    • 機械的な置き換え。utils.ts の brand<T>()、mergePlugins、partial は名前付き型でそのままの形を保てる。metadata.ts の unified.PluggableList<unified.Settings> キャストは削除する。
  • 検証
    • workspace全体の tsc

4. remark-parseのオプション

  • 場所
    • packages/vfm/src/index.ts (VFM())
    • packages/vfm/src/plugins/metadata.ts (parseMarkdown)
    • すべてのサブパッケージ テスト ユーティリティ
    • いずれも [remarkParse, { gfm: true, commonmark: true }] を渡している。
  • 理由
    • remark-parse 11はオプションを mdast-util-from-markdown に転送するが、そこに gfm や commonmark は無い。モードはCommonMarkのみ。この呼び出しは旧型でしか型検査を通らず、実行時には何もしないため、remark-gfmを足すまでGFMのtable、取り消し線、autolinkリテラル、footnote参照はパースされない。
  • 対応物
    • GFMノードを読むプラグインより前のmdast slotとしての remark-gfm 4
  • 修正
    • オプションをslotリストの remarkGfm に置き換える。.data('settings', { position }) も fromMarkdown に転送されて無視される。positionは常に付く。
  • 検証
    • tests/table.test.ts
    • tests/footnotes.test.ts
    • GFM構文を含むテストのMDASTダンプ

5. deep import

  • 場所
    • packages/vfm/src/revive-rehype.ts
    • packages/mdast-to-hast-table-cell/tests/utils.ts
    • packages/mdast-to-hast-table-cell/tests/composition.test.ts
    • いずれも mdast-util-to-hast/lib/handlers/table.js をimportしている。
  • 理由
    • mdast-util-to-hast 13は "exports": "./index.js" を持ち、lib/ 配下のパスは解決できない。
  • 対応物
    • import { defaultHandlers } from 'mdast-util-to-hast' と defaultHandlers.table
  • 修正
    • importを置き換える。あわせてVFM自身のパッケージに exports を付けるか決める。READMEの @vivliostyle/vfm/lib/revive-parse deep importは exports が無いことに依存している。
  • 検証
    • ビルド
    • packages/mdast-to-hast-table-cell/tests

6. Image.alt の再パース

  • 場所
    • packages/vfm/src/plugins/figure.ts (parseImageAltAsInline): this.parse(image.alt)
  • 理由
    • remark-parse 8はaltテキストの生ソースを保持していたため、![**bold** caption](a.png) の alt にアスタリスクが残り、プラグインがそれを再パースできた。micromarkはプラグインが動く前に alt をプレーンテキスト(bold caption)にdecodeするので、再パースする対象が残らない。this.parse 自体はunifiedプロセッサに引き続き存在する。
  • 対応物
    • 生のキャプションはトークン化中にしか得られない。from-markdown拡張で画像ラベルのソース スライスを記録する(例: data.rawAlt)か、ラベルの子トークンを保持する。
  • 修正
    • 再パースを、画像ラベルのインライン子要素を保持するVFM拡張に置き換え、buildFigure がそれを読むようにする。非標準の Image.children の慣習は型付きフィールドにする。
  • 検証
    • tests/figure.test.ts、特に parseFigcaptionAsInline のケースとalt導出(deriveImgAltFromFigcaption)

7.旧Parser内部のテスト

  • 場所
    • packages/vfm/tests/defs.test.ts (6件)。検証対象:
      • vfm.Parser.prototype.inlineMethods
      • blockMethods
      • interruptParagraph
      • interruptList
      • interruptBlockquote
      • interruptFootnoteDefinition
  • 理由
    • remark-parse 11にはいずれも存在しない。
  • 対応物
    • freezeしたプロセッサの this.data('micromarkExtensions') と this.data('fromMarkdownExtensions') のリスト
  • 修正
    • 登録された拡張(件数または同一性)を検証するテストに置き換えるか、ファイルを削除して挙動テストに任せる。
  • 検証
    • 置き換えたテスト自体

8. @types/mdast 4の型名

  • 場所
    • packages/vfm/src/plugins/math.ts (StaticPhrasingContentMap)
    • packages/vfm/src/plugins/toc.ts (Content, BlockContentMap)
    • packages/vfm/src/plugins/code.ts (unist Data のaugmentation)
    • packages/vfm/types/remark.d.ts
    • packages/remark-ruby/src/ruby.ts (unist Data)
    • packages/remark-sectionize/src/section.ts (Content, HTML, BlockContentMap, unist Data)
    • packages/mdast-to-hast-table-cell/tests/rehype-format.d.ts
  • 理由
    • @types/mdast 4は StaticPhrasingContentMap を PhrasingContentMap に、Content を RootContent に、HTML を Html に改名し、Content unionを廃止した。@types/unist 3の Data は mdast-util-to-hast 13自身がaugmentationする(hName, hProperties, hChildren)ため、ローカルのaugmentationは重複になる。
  • 対応物
    • PhrasingContentMap
    • BlockContentMap (変更なし)
    • RootContent
    • Html
    • Data フィールドには import 'mdast-util-to-hast'
  • 修正
    • 改名し、重複した Data augmentationを削除する(code.ts の figcaptionTitle とrubyの rubyText は残す)。rehype-format 5が型を同梱したら rehype-format.d.ts を削除する。
  • 検証
    • tsc

9.テストのMDAST期待値

  • 場所
    • buildProcessorTestingCode (tests/utils.ts)を使うすべての packages/vfm/tests/*.test.ts。MDASTはpositionと data: 行を除いた unist-util-inspect のダンプとして比較される。
  • 理由
    • 新しい構文でノード形状が変わり、unist-util-inspect 8の書式も変わりうる。影響するノード:
      • remark-mathの inlineMath / math
      • remark-gfmのfootnoteノード
      • attr書き直しによる属性の運搬ノード
      • rubyとinline noteのノード
  • 修正
    • 各構文が揃うたびに期待ダンプを再生成し、差分を手で確認する。挙動の検証はHTML期待値に任せる。
  • 検証
    • テスト自体。変更が最も大きい見込みのファイル:
      • figure.test.ts
      • math.test.ts
      • footnotes.test.ts
      • code.test.ts

Phase 0-1 / 0-2で見つかった項目

10. hastscript 9のchild / properties判定

  • 場所
    • packages/vfm/src/plugins/document.ts: h('head', ...createHead()) (h('html', props, [u('text', '\n'), ...]) は問題なし)
    • packages/remark-footnote-dpub/src/index.ts: h('sup', u('text', '1'))
    • buildElement に渡されるユーザー定義の ElementFactory
  • 理由
    • hastscript 9は第2引数がpropertiesかどうかを isChild 判定で決める。オブジェクトがchildと見なされるのは、(文字列/数値の配列以外の)オブジェクト値のフィールドか children 配列を持つ場合のみ。textノード { type: 'text', value: '\n' } はどちらも持たないためpropertiesと扱われ、type="text" value="..." 属性として描画され、テキスト子要素が無くなる。
  • 対応物
    • childrenを1つの配列で渡すか、明示的なpropertiesオブジェクトの後に渡す: h('sup', {}, u('text', '1'))。
  • 修正
    • 第2引数がtextノードになりうる h() 呼び出しをすべて監査する。hastscript 7はこれを受け付けていた。
  • 検証
    • tests/index.test.ts (document wrapper、<head> の内容)
    • packages/remark-footnote-dpub/tests

11. footnoteById が Map

  • 場所
    • packages/remark-footnote-dpub/src/index.ts
    • packages/remark-footnote-gcpm/src/index.ts
    • アクセス箇所: identifier in ctx.footnoteById、ctx.footnoteById[id]、ctx.footnoteById[identifier] = ...
  • 理由
    • mdast-util-to-hast 13の state.footnoteById は String(identifier).toUpperCase() をキーとする Map<string, FootnoteDefinition>。in 判定とインデックス アクセスは false / undefined を返し、代入は state が決して読まないown propertyを追加する。
  • 対応物
    • state.footnoteById.has(id)、.get(id)、.set(id, def)
    • state.footnoteOrder と state.footnoteCounts が採番と重複を追跡する。
  • 修正
    • アクセスを変換する。パッケージ独自のカウンターの代わりに footnoteOrder / footnoteCounts を使うことを検討する。
  • 検証
    • packages/remark-footnote-{dpub,gcpm}/tests
    • tests/footnotes.test.ts
  • 場所
    • packages/remark-footnote-pandoc/src/index.ts のセレクター:
      • div.footnotes
      • li[id^="fn-"]
      • sup[id^="fnref-"]:has(a:only-child[href^="#fn-"].footnote-ref)
      • a.footnote-backref
  • 理由
    • 現在のセレクターはどれもv13のfooterに一致せず、transformerは既定footerを触らずに残す。v13のfooter:
      • Area: <section data-footnotes class="footnotes"> と <h2 id="footnote-label" class="sr-only">
      • Element: <li id="user-content-fn-id">
      • Call: <sup><a href="#user-content-fn-id" id="user-content-fnref-id" data-footnote-ref aria-describedby="footnote-label">
      • Backlink: <a href="#user-content-fnref-id" data-footnote-backref class="data-footnote-backref" aria-label="Back to reference N">
  • 対応物
    • remark-rehype 11のオプション: clobberPrefix、footnoteLabel、footnoteLabelTagName、footnoteLabelProperties、footnoteBackLabel、footnoteBackContent
    • カスタム footnoteReference / footnoteDefinition handlerと state.footnoteOrder から組むfooter
  • 修正
    • セレクターをv13 footerに合わせて書き直すか、handlerからPandoc構造を直接出力する(推奨。サブパッケージ調査を参照)。
  • 検証
    • packages/remark-footnote-pandoc/tests
    • tests/footnotes.test.ts

13. refractor 5が Root を返す

  • 場所
    • packages/vfm/src/plugins/code.ts (mdast): node.data.hChildren = refractor.highlight(value, lang)
  • 理由
    • refractor 3はhastノードの配列を返した。refractor 4以降は { type: 'root', children } を返す。rootを hChildren に代入すると <code> の中に root が入れ子になる。rehype-stringify は実際にはそのchildrenを描画するが、hChildren の型付けと、要素コンテンツを期待するhastコンシューマーは壊れる。
  • 対応物
    • refractor.highlight(value, lang).children
  • 修正
    • .children を取る。refractor 5はdefault exportも廃止して import { refractor } from 'refractor' になり、言語登録は refractor/<lang> パスに移る。
  • 検証
    • tests/code.test.ts のハイライト ケース

14. hast-util-raw 9の署名

  • 場所
    • packages/vfm/src/plugins/figure.ts (parseHtml): raw(u('root', [u('raw', value)]))
  • 理由
    • hast-util-raw 9は名前付きexportの raw(tree, options) で Nodes を返す。default exportは無くなり、raw ノード型は mdast-util-to-hast のaugmentationで宣言する必要がある。
  • 対応物
    • import { raw } from 'hast-util-raw'。raw(tree) は raw 子要素を持つrootを引き続き受け付ける。
  • 修正
    • importと戻り値の型キャストを更新する。
  • 検証
    • tests/figure.test.ts の画像段落内にHTMLコメントがあるケース

15. inline footnoteノードの消滅

  • 場所
    • packages/vfm/src/plugins/slug.ts (child.type !== 'footnote' のフィルター)
    • packages/vfm/src/plugins/metadata.ts (child.type !== 'footnote' のフィルター)
    • packages/vfm/src/plugins/footnotes.ts (inlineNotes: true)
    • remark-footnote-dpub / gcpm の footnote handler
    • tests/footnotes.test.ts
  • 理由
    • remark-footnotes 2は ^[text] に対して footnote ノードを生成した。remark-gfm 4にinline noteは無いため、このノード型は決して現れず、^[text] はリテラルのテキストとして描画される。フィルターとhandlerはエラー無しにdead codeになる。
  • 対応物
    • 上流には無い。VFMのmicromark拡張で構文とノードを定義する必要がある。
  • 修正
    • inline note拡張を最初に書く(slug、metadata、footnoteパッケージの共通依存)。ノード型名が変わるなら更新する。
  • 検証
    • tests/footnotes.test.ts のinlineケース
    • tests/metadata.test.ts のfootnote付きタイトル抽出

16. math.ts の findAndReplace フォールバック

  • 場所
    • packages/vfm/src/plugins/math.ts (mdast)、this.Parser が無いときに通る分岐
  • 理由
    • このフォールバックは「remark 13以降」向けに書かれたが、パース後に text ノード上で動く。$**x**$ はすでに text('$'), strong, text('$') になっているため正規表現は数式全体を見られず、tokenizerが除外していた(notInLink)コード スパンやリンク内の $ に一致してしまう。remark 13ではこの分岐が実行される(#1参照)ので、mathの出力は欠落ではなく不正になる。
  • 修正
    • tokenizerとともにフォールバックを削除し、micromark拡張へ移る。
  • 検証
    • tests/math.test.ts の数式内インライン記法のケースと、コード内の $ のケース

17.旧方式の外部プラグイン

  • 場所
    • remark-attr 0.11 (attr.ts, remark-sectionize テスト)
    • remark-shortcodes 0.3 (toc.ts)
    • remark-footnotes 2 (footnotes.ts, footnoteパッケージのテスト)
    • remark-breaks 1 (line-breaks.ts, remark-ruby テスト)
  • 理由
    • 4つとも this.Parser.prototype を書き換える。this.Parser がundefinedだと早期returnするため、属性、[[toc]]、footnote、hard breakがエラー無しに動かなくなる。code.ts には meta が空のときremark-attrがコード内容を属性としてパースする問題の回避策もあり、これはdead codeになる。
  • 対応物
    • remark-breaks 4 (transformer、置き換えのみ)
    • remark-gfm 4 (footnoteの参照と定義)
    • 属性とinline noteのVFM拡張
    • [[toc]] を残すなら remark-directive 4かblock拡張(#207)
  • 修正
    • プラグインごとにサブパッケージ調査を参照。code.ts のremark-attr回避策を削除する。
  • 検証
    • tests/attr.test.ts
    • tests/code.test.ts
    • tests/line-breaks.test.ts
    • tests/metadata.test.ts ([[toc]] 検出)
    • packages/remark-sectionize/tests ({hidden})

18.サブパッケージのテスト ユーティリティ

  • 場所
    • packages/remark-ruby/tests/ruby.test.ts
    • packages/remark-footnote-{dpub,gcpm,pandoc}/tests/*.test.ts
    • packages/remark-sectionize/tests/utils.ts
    • packages/mdast-to-hast-table-cell/tests/utils.ts
  • 理由
    • それぞれ import unified from 'unified'、remark-parse 8オプション、devDependencies の remark-footnotes / remark-attr / remark-breaks 1で独自のプロセッサを組んでいる。#1、#3、#4、#5、#17に同時に当たる。
  • 修正
    • 各ユーティリティをパッケージと一緒に移植する。使うもの:
      • { unified }
      • remark-gfm
      • remark-breaks 4
      • できあがり次第VFMのinline noteと属性拡張
      • defaultHandlers.table
  • 検証
    • パッケージごとの pnpm test

19. 1つのworkspaceに2世代が併存することによる型解決

  • 場所
    • pnpm-workspace.yaml (overrides, packageExtensions)
    • @types/unist: "*" を宣言している @types/mdast@3 / @types/mdast@4 / @types/hast@2 / @types/hast@3
    • .d.ts で unist、unified、vfile、hastscript を依存宣言なしにimportしているremark 8世代のパッケージ: remark-parse@8、remark-rehype@8、remark-frontmatter@2、remark-footnotes@2、rehype-raw@5、rehype-stringify@8、unified@9、unist-builder@2、unist-util-is@4、vfile-location@3、hast-util-to-html@7、hast-util-from-parse5@6、hast-util-has-property@2、mdast-util-definitions@4、hast-util-to-string@2、@types/refractor@3
    • vfile について同じ欠落があるremark 13世代のパッケージ: remark-parse@11、remark-stringify@11、rehype-stringify@10
  • 理由
    • Phase 2で判明。1つのpnpm workspaceにunist 2の packages/ とunist 3の packages-next/ が併存すると、@types/unist: "*" はすべて1つのバージョンに解決され、依存宣言の無い型importは node_modules/.pnpm/node_modules にあるpnpmのhoist済みコピー1つに解決される。負けた世代は別majorの型を読むことになり、Parents が never に潰れ、Plugin や Processor が別のunifiedのものになり、自身の package.json が正しくてもそのツリーのビルドが失敗する。
  • 対応物
    • 親セレクター付きのpnpm overrides ('@types/mdast@4>@types/unist': ^3.0.0)で、* の子を親のmajorごとに固定する。
    • pnpm packageExtensions で、公開パッケージに欠けている dependencies を補い、hoist済みコピーではなく自身のコピーを解決させる。
  • 修正
    • 両方の表は pnpm-workspace.yaml にコメント付きで置いてある。併存期間のための足場であり、Phase 5 (#296)で packages/ とともに削除する。
  • 検証
    • ルートで pnpm install --frozen-lockfile && pnpm build && pnpm test を実行する(両ツリーが対象)。
    • 世代固有の依存を新たに追加したときは、node_modules/.pnpm/<pkg>/node_modules/@types/unist/package.json で解決されたバージョンを確認する。

修正間の依存関係

  • #15 (inline noteノード)と#17 (属性拡張)は#1、#6、#9、#11、#12、#18の入力になる。handlerやテストを移植する前に、この2つのノード形状を定義する。
  • #2と#11はfootnoteパッケージごとに一緒に行う。
  • #4 (remark-gfm)はfootnoteやtableのテストが通る前に入れる必要がある。
  • #10、#13、#14は独立したライブラリ適応で、Phase 2の最初にできる。
  • #19はworkspaceの問題で、packages-next/ の依存を新majorに上げる前に入れておく必要があり、Phase 5で packages/ とともに消える。