Skip to content

fix: keep the line offsets of inline tokens when rules call getLines again (DEV-3364) - #26

Open
galaxian85 wants to merge 2 commits into
masterfrom
fix/dev-3364-getlines-offsets
Open

galaxian85 wants to merge 2 commits into
masterfrom
fix/dev-3364-getlines-offsets

Conversation

@galaxian85

Copy link
Copy Markdown

DEV-3364

摘要

StateBlock#getLines 每次呼叫都會覆寫 [begin, end) 的 lineOffsets/linePads。inline 解析在整份文件的 block 解析結束後才跑,所以如果某個 rule 在 inline token 建立之後,又對同樣的行呼叫 getLines(例如往回探查),這個 token 的子 token 位置就會錯。這個 PR 在覆寫前把該 token 的值存起來,core inline rule 解析它之前再寫回去。

這是 14.2.1 批次的一部分,merge 後先不要發版。

輸出的 HTML 不變。沒有這種 plugin 的文件,所有位置都不變。hackmd-production 不用改 code。

問題和重現

一個 block rule 在每一行往回讀前 3 行,然後放棄:

md.block.ruler.before('table', 'look_back', (state, startLine, endLine, silent) => {
  if (!silent && startLine > 0) state.getLines(Math.max(0, startLine - 3), startLine, 0, false)
  return false
})
原始碼 text 子 token 修正前(對到的原始碼) 修正後
> a\n> b *c*\n\nnext b 、c 4(> )、7( ) 6、9
- a\n b *c*\n\nnext b 、c 4( )、7 6、9
> > a\n> > b\n> > *c*\n\nnext b、c 6(>)、9 正確

沒有容器(例如 a\n b *c*)的段落不受影響,因為那時每行被拿掉的字元數本來就和探查的結果一樣。

調查結果:只有自訂 plugin 會踩到

  • 內建 rule 不會觸發。 paragraph、lheading、code、fence、html_block 都是決定建立 token 之後,才對自己的行呼叫 getLines。用 instrumented 的 getLines 跑過所有 fixture 和 benchmark 樣本(3284 份),沒有任何一次覆寫到已建立的 inline token 的行。
  • hackmd-production 的 plugin 也不會觸發。 用 production 真正的 frontend renderer(extra.js,透過 loadFrontendRenderer)和 server 的 getParser() 解析 55 份樣本:spoiler、extraTag、mention、smartypants、deflist、svg、alert 放在 blockquote/list/巢狀容器/lazy continuation 的多行段落裡。覆寫次數是 0。
    • @hackmd/markdown-it-deflist 2.2.2 是先 push 空的 inline token,再對 term 那一行呼叫 getLines,讀的是自己的行。
    • svg.ts 是決定建立 svg_block 之後,才對自己的行呼叫。
  • 結論:這是 plugin API 的陷阱,目前沒有實際發生。修正後,之後的 plugin 也不會踩到。

修法

不是在 push inline token 時就存快照,而是等到真的要被覆寫時才存:

  1. getLines 開始時,先看自上次呼叫以來新 push 的 token,更新「已 push 的 inline token 最遠到哪一行」(_inlineLineEnd)。
  2. begin 在這一行之後就直接返回(內建 rule 都是這種情況)。
  3. 否則從最後一個 token 往回找 map 和 [begin, end) 重疊的 inline token,把它 map 範圍內的 lineOffsets/linePads 存進 block state 上的 _inlineSaved(Map,key 是 token)。
  4. core inline rule 解析每個 inline token 前,如果它有存值,就寫回 block state 的陣列。

和 Linear 建議的做法(push 時存快照)不同,理由:

  • lheading 是 push inline token 之後才呼叫 trimmedContentStart 重新起算 lineOffsets;deflist 也是先 push、再用 getLines 設 content。push 時存的快照會是錯的。延到下一次 getLines 開始時,這些都已經完成了。
  • 沒有探查的文件不用複製任何陣列,也不用配置記憶體。
  • 最後一個 token 如果是 content 為空的 inline token(deflist 的 term),要等到下一次呼叫才納入,因為它的 content 可能就來自這一次呼叫。

快照放在 block state 的 _inlineScanned/_inlineLineEnd/_inlineSaved 上,不在 token 上,也不會被序列化。lineOffsets/linePads 的名稱、索引方式(絕對行號),以及「inline 解析時陣列裡是當下 inline token 的偏移」這個語意都沒變,所以直接讀 state.env.state_block.lineOffsets 的 production plugin(githubAlertsPositionPlugin.js、extraTagPlugin.js)和透過 getLineOffset 讀的 plugin 都不用改。

沒有涵蓋的部分(已寫進註解和 CHANGELOG)

  • token push 之前寫入的值。 不靠 getLines 建立 inline token 的 rule(例如表格)會直接讀陣列裡現有的值。如果在那之前有 rule 探查過這些行,位置還是會錯,例如 blockquote 裡的表格配上往前探查的 plugin。這一點加了一個記錄現況的測試。建議探查改用 getLine/bMarks/eMarks。
  • 寫回發生在 core inline rule 裡。 在 block 和 inline 之間執行的 core rule 讀到的還是被覆寫的值。production 的 githubAlertsPositionPlugin.js 就是在這個時間點讀陣列,但 production 沒有會覆寫的 plugin,所以不受影響。

效能

repo 的 benchmark/benchmark.mjs 需要先全域安裝舊版 marked/commonmark(benchmark-deps),所以改用同一套 Benchmark.js 和 benchmark/samples,只比較 master 和這個 branch(Node 24,html/linkify/typographer 開啟),28 個樣本取幾何平均:

比較 幾何平均
master 對 master(雜訊基準) ±1.7–1.9%
master 先跑、branch 後跑 branch 慢 0.2%
branch 先跑、master 後跑 branch 慢 1.6%

差異落在雜訊範圍內。第一版每一行都記錄 owner,小文件會慢 4–6%(block-fences 慢 20%),所以改成上面的快速路徑。

測試

test/annotation.js 新增 6 個測試(Annotation with rules calling getLines again)。修正前,其中 5 個會失敗:

  • 往回探查的 rule:blockquote、list、巢狀容器、tab、setext heading 等 11 份原始碼,位置要和沒有 plugin 時一樣,text 子 token 要對到原始碼。另外鎖住 DEV-3364 第一個例子的確切值。
  • 在 push 自己的 token 之後,又用不同的 begin 和 indent 讀自己行的 rule(包住 paragraph)。
  • 仿 deflist 的 rule(先 push inline token,再用 getLines 設 content),配上前後探查。這個測試會抓到「把還在建立的 token 也納入」的錯誤實作(拿掉那個判斷時,這個測試會失敗)。
  • inline 解析時,直接讀 state.env.state_block.lineOffsets 和 getLineOffset/getLinePad 得到的值,要和沒有探查時一樣(production plugin 的讀法)。
  • 所有 fixture 檔案(每個範例,加上放進 blockquote/list 的版本,共 3000 份以上),搭配三種探查 plugin:所有 token 的位置和輸出的 HTML 都要和沒有 plugin 時完全相同。
  • 記錄現況:往前探查之後,blockquote 裡的表格 cell 位置還是會錯(上面「沒有涵蓋的部分」)。

既有的測試都沒改。npm test(Node 24):1626 passing、1 pending,lint 通過。

和 #25(DEV-3359)一起測:在臨時 worktree 把 #25 merge 進來(只有 CHANGELOG 衝突),npm test 1630 passing。paragraph_close.position 是在 push 時就算好的,有探查的 plugin 時結果也一樣(例如 > a\n> b 是 7)。

hackmd-production 驗證

在 #6100 的 branch(fix/dev-3358-code-source-map-real-line-starts,14.2.0)用 symlink 換成這個 branch build 出來的 fork,用 bin/agent/test 跑和 markdown 相關的 spec:

14.2.0(npm,基準) 這個 branch
node 8 個檔案、135 個測試全過 8 個檔案、135 個測試全過
browser 15 個檔案、163 個測試全過 15 個檔案、163 個測試全過

另外用臨時 spec(沒有 commit)比較 npm 14.2.0 和 fork 的 token:用 frontend renderer 和 server parser 解析 55 份樣本(spoiler、extraTag、mention、smartypants、deflist、svg、alert,放在各種容器裡的多行段落),所有 token 和子 token 的 position/size/map、mention 的 data-position,以及輸出的 HTML 完全相同。production 沒有會觸發這個問題的 plugin,所以沒有「原本錯、現在修正」的差異。

🤖 Generated with Claude Code

galaxian85 and others added 2 commits November 19, 2026 15:48
…again (DEV-3364)

StateBlock#getLines overwrites lineOffsets and linePads for its lines, and
inline parsing runs after the whole block parse, so a rule that read the
lines of an inline token pushed earlier (e.g. a plugin probing earlier
lines) changed how that token's children were mapped to the source.

Before a getLines call overwrites lines of an inline token pushed earlier,
save that token's values on the block state; the core inline rule writes
them back before parsing the token. Rules that only read lines after the
tokens pushed so far (all built-in rules) take a fast path, so documents
without such probes pay almost nothing and their positions are unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@galaxian85
galaxian85 requested a review from Yukaii November 19, 2026 07:50
@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 44482659639

Warning

No base build found for commit 3b368fe on master.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 98.937%

Details

  • Patch coverage: 30 uncovered changes across 1 file (76 of 106 lines covered, 71.7%).

Uncovered Changes

File Changed Covered %
lib/rules_block/state_block.mjs 95 65 68.42%
Total (3 files) 106 76 71.7%

Coverage Regressions

Requires a base build to compare against. How to fix this →


Coverage Stats

Coverage Status
Relevant Lines: 6775
Covered Lines: 6712
Line Coverage: 99.07%
Relevant Branches: 1785
Covered Branches: 1757
Branch Coverage: 98.43%
Branches in Coverage %: Yes
Coverage Strength: 385061.65 hits per line

💛 - Coveralls

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants