wiki sync code notation strip - Liplus-Project/liplus-language GitHub Wiki

wiki sync のリンク抽出はコード記法を除去してから行う

Question

wiki sync の cross-reference / sidebar 整合性アサーションが ](<x>) を抽出するとき、コードスパンやフェンス内の記法をどう扱うか。

Current resolution

抽出の前にコード記法を除去する。除去は 5 形式（HTML コメント / HTML 要素 / フェンスドコードブロック / インデントコードブロック / インラインコードスパン）を対象とし、この順序で、各パスを本文全体に適用してから次のパスへ進む。区切りはバッククォート N 個の run として突き合わせ、長さを固定値で書かない。フェンスは 3 個以上のバッククォートまたはチルダの run のみからなる行で開き、同じ文字の同じ長さ以上の run で閉じる。

sidebar 側は当時 _Sidebar.md に記法が無く偽陽性は出ていなかったが、同じ抽出方式であるため予防的に同じ除去を適用する。

Edges

depends on: wiki sync 時の _Sidebar.md 整合性 assertion — 除去対象となる抽出方式そのものを導入した判断。本 entry はその抽出の入力側を条件付ける

背景

アサーションの仕様文自身が ](<x>) 記法をインラインコードスパン内で使ってパターンを説明している。したがって仕様どおりに実行すると必ず自己一致する。2026-07-26 の v1.19.11（tag build-2026-07-26.3）で実測したところ、docs/4.-Operations.md（wiki ミラー）の 2 箇所と wiki entry wiki-sync-sidebar-integrity-check.md の 1 箇所、計 3 件が「未解決リンク」として報告された。仕様は 1 件でも STOP と定めているため、以後すべてのリリースの wiki sync が恒久的に停止する状態だった。コード記法を除去して再抽出すると実リンク 66 件はすべて解決し、真の未解決リンクはゼロ。よって wiki の整合性問題ではなくアサーションの抽出ロジックの欠陥。

初版の修正はインラインコードスパンのみを対象にしていた。PR #1551 の brake 1（N=3）が 4 点を指摘して現在の形になった:

除去順序が未指定だと、インラインスパンのパスがフェンスより先に走ったときフェンス自身のバッククォート run が区切りと誤認され、無関係なテキストを飲み込む
カバレッジがトリプルバッククォートのフェンスとシングルバッククォートのスパンだけを名指ししており、チルダフェンス / インデントブロック / HTML の code 要素が同じリスクを持つのに漏れていた
区切り長がハードコードで、run として突き合わせていなかった
sidebar 側 rationale の末尾一文（「まだ偽陽性を出していない」）は、その上の除去ステップが無条件である以上 push surplus。3 体中 2 体が指摘し削除

制約

アサーションの停止側の挙動（STOP & escalate、自動修正なし）は変更しない。変えたのは抽出の入力のみ
仕様は skills/operations-on-wiki-sync/SKILL.md と docs/4.-Operations.md の双方にあるため同一 PR で整合させる

結論

採用 = 抽出前の多段除去 + 順序の明示 + run 長の突き合わせ。

却下 = インラインスパンのみの単純除去（フェンス内の記法で同じ偽陽性が再発する）。却下 = アサーション自身の仕様文をコード記法以外の書き方に変える（記法の説明としての可読性を失い、他の文書での再発も防げない）。

観測として残す点

このアサーションが追加されてから #1547 までのリリースでも同じ 3 件は存在していたはずである。にもかかわらず sync が停止した記録が無い。つまりアサーションが仕様どおりには実行されていなかった可能性が高い。手順が recall 依存であることの実例として、rules/model/subtractive-structural-beauty.md の procedure-vs-structure 二分に照らして観測する価値がある（過去 run の実行実態は未調査）。