amenbo 0.3.0 → 0.4.1

package/dist/extract/markdown.d.ts

@@ -25,6 +25,7 @@ export interface ExtractResult {
 interface TableCandidate {
     tagName: string;
     outerHTML: string;
+    innerHTML: string;
     textContent: string;
     parentElement: TableCandidate | null;
     closest(selector: string): TableCandidate | null;
@@ -37,15 +38,36 @@ interface TableQueryHost {
 export interface DroppedTable {
     /** turndownへ渡す正規化済みHTML(colspan/rowspan展開・多段ヘッダ結合後)。 */
     html: string;
-    /** 元の表テキスト先頭。Readability出力に既にある表かの重複判定に使う(正規化前基準)。 */
-    signature: string;
+    /**
+     * 表内セル(th/td)から作った照合プローブ群。Readability出力に既にある表かの重複判定に使う。
+     * 単一signatureではなく複数プローブの多数決にするのは、Readabilityが表を保持しつつ一部セルの
+     * 隠し要素を刈る(Langエラーspan・隠し座標span等)ため、先頭固定のsignatureだと保持済みの表でも
+     * 照合が外れて丸ごと再挿入されるのを防ぐため。contentHtml側と同じnormalizeForSignature
+     * (タグ→空白)で両辺を揃える(空白非対称による重複挿入対策)。
+     */
+    probes: string[];
     /** 表の直前の見出し(優先)または近傍段落の正規化テキスト。位置復元のアンカー。無ければ空。 */
     anchor: string;
+    /**
+     * anchorの由来。heading由来は見出し要素の完全一致で照合し(「人口」等の短く非一意な見出しが
+     * 段落の部分文字列へ吸着して表が無関係な節へ誤挿入されるのを防ぐ)、paragraph由来は包含判定する。
+     */
+    anchorKind: "heading" | "paragraph" | "";
 }
 /**
  * turndownのGFMテーブル変換はcolspan/rowspan・多段ヘッダを扱えず列ズレや空セルを生む。
- * グリッドを再構築してspanを実セルへ展開し、先頭の連続ヘッダ行は1行へ結合してから
- * 全行同一列数の単純表を返す。救出経路の表のみに適用する(影響を局所化)。
+ * グリッドを再構築してspanを「位置の占有」として展開し(内容の複製はしない)、先頭の連続ヘッダ行は
+ * 1行へ結合してから全行同一列数の単純表を返す。救出経路(collectDataTables)とReadability/アダプタ等が
+ * 本文に保持した複雑表(normalizeRetainedTables)の双方から呼ばれる。
+ * spanの無い単純表・既に正規化済みの表に対しては構造を変えず冪等に振る舞う。
+ * captionは再構築で失われないよう先頭へ復元する。
+ *
+ * 内容配置は行の役割で分岐する:
+ * - 列ヘッダ行(all-th ∧ 起点セル2つ以上): 占有読み。colspanグループラベルは配下の各列へ複製される
+ *   (多段ヘッダ結合「グループ 列名」の意味を保つための唯一の複製)
+ * - データ行: 起点位置にのみ内容、span継続位置は空セル(複製しない)
+ * - 全幅単一th行: 列ヘッダではなく表題/節ラベル。先頭の連続分はcaptionへ畳み(turndown-gfmが
+ *   ヘッダ行を見失って複雑表フォールバックへ落ちるのを防ぐ)、表中間の区切り行はデータ行として出力
  */
 export declare function normalizeTableHtml(tableHtml: string): string;
 /**
@@ -58,11 +80,127 @@ export declare function collectDataTables(body: TableQueryHost): DroppedTable[];
 /**
  * Readability出力に含まれない表だけを、可能なら元の位置(アンカー直後)へ、無理なら末尾へ再結合する。
  * アンカー(表の直前見出し/段落)がReadability出力に残っていれば、その要素の直後に挿入して
- * 「表が本来属していた節」へ戻す(記事構造=意味の保持)。残っていなければ末尾フォールバック。
+ * 「表が本来属していた節」へ戻す(記事構造=意味の保持)。残っていなければ末尾フォールバック
+ * (誤配置より末尾が安全)。
  */
 export declare function reinsertDroppedTables(contentHtml: string, tables: DroppedTable[]): {
     html: string;
     appended: number;
 };
+/** 救出対象の見出し。位置復元のため直後段落テキストをアンカーとして持つ。 */
+export interface DroppedHeading {
+    /** 見出しレベル(2-6)。h1はReadabilityがtitleへ昇格させるため対象外。 */
+    level: number;
+    /** normalizeForSignatureで正規化した見出しのプレーンテキスト。outlineに要る階層とテキストのみ持つ。 */
+    text: string;
+    /**
+     * 節スコープ内の十分長いコンテンツ要素(段落/表/リスト等)を文書順に並べた位置復元アンカー候補。
+     * 最初の段落まで(段落を含む)を最大HEADING_ANCHOR_CANDIDATE_MAX件持ち、照合は先頭から試して
+     * 最初に一致した要素の直前へ挿入する。単一アンカーにしないのは、節先頭のブロックが
+     * Readabilityに落とされるノイズ(廃止グラフ注意書き等)だった場合に、後続の実在要素
+     * (データ表や本文段落)へ吸着させるため。段落優先にせず文書順なのは、節の先頭が表のとき
+     * 見出しを表の前に立てるため(段落優先だと見出しが表の後ろへ入り、表が前の節へ帰属してしまう)。
+     * 空配列=節本文なし(復元しない)。
+     */
+    anchors: HeadingAnchorCandidate[];
+}
+export interface HeadingAnchorCandidate {
+    text: string;
+    /**
+     * block(表/リスト)由来はnormalizeTableHtml再構築で空白が消えるため全空白除去で照合し、
+     * paragraph由来は空白正規化ベースの包含で照合する(全空白除去を段落由来へ広げると欧文で偽陽性が増える)。
+     */
+    kind: "paragraph" | "block";
+}
+/** collectHeadingsが走査するDOM要素の最小インターフェース。 */
+interface HeadingCandidate {
+    tagName: string;
+    textContent: string;
+    parentElement: HeadingCandidate | null;
+    closest(selector: string): HeadingCandidate | null;
+}
+interface HeadingQueryHost {
+    querySelectorAll(selector: string): ArrayLike<HeadingCandidate>;
+}
+/**
+ * Readabilityは見出しがラッパー要素(編集リンク付きdiv等)に包まれていると本文整形時にh2-h6を
+ * 丸ごと落とし、outline/section機能が依存する節構造を全消失させる。parse前のdocumentからh2-h6を
+ * 採取し、節スコープ内の段落/ブロックをアンカーにして位置復元に備える。
+ * parseは渡したdocumentを破壊的に変更するため、必ずparse前に呼ぶこと。
+ * h1はReadabilityがtitleへ昇格させるため対象外(復元するとtitleと二重化する)。
+ * 見出し内リンク等のmarkupは持たない(outlineに要るのはテキストと階層のみ)。
+ */
+export declare function collectHeadings(body: HeadingQueryHost): DroppedHeading[];
+/**
+ * Readabilityが落とした見出しを、アンカー(直後段落)がReadability出力に残っている場合のみ、
+ * その段落の直前(beforebegin)へ`<hN>text</hN>`として戻す。
+ *
+ * 表救出(reinsertDroppedTables)との最重要差分は「アンカー不在の見出しは復元しない・末尾
+ * フォールバックもしない」こと。表=データそのもの(失うと情報欠落)だが、見出し=節のラベルであり、
+ * 節本文がReadability出力に残っていない見出しを戻してもノイズにしかならない。アンカーの生存確認が
+ * 「その節が本文として残っているか」の判定を兼ね、nav/フッター等Readabilityが正しく落とした節の
+ * 見出しを自然に除外する(サイト固有知識なしでnavbox見出しを拾わない)。
+ * 同一テキストの見出しは最初の1件のみ扱う(同名節の複数復元はアンカー取り違えリスクの方が大きい)。
+ * 挿入は「同テキストの見出しが本文に無い」場合のみのため、再適用しても増えない(冪等)。
+ */
+export declare function reinsertDroppedHeadings(contentHtml: string, headings: DroppedHeading[]): {
+    html: string;
+    restored: number;
+};
+/**
+ * 本文HTMLに保持された複雑表(colspan/rowspan・多段ヘッダ)をその場で正規化し、あわせて全表の
+ * セル内ブロック要素をインライン化する。
+ * 救出経路(reinsertDroppedTables)は「Readabilityが落とした表」しか正規化しないため、
+ * Readability/アダプタ/ジオメトリ/selector等が本文に保持した複雑表は未正規化のまま
+ * turndownへ渡ると列ズレ・空セルになる。turndown直前の全経路共通パスでこれを補う。
+ * (アダプタ経路(例: zenn等)はReadabilityを経由しないため、readability経路限定ではなく
+ *  全経路に適用する必要がある。)
+ * 正規化はspan/多段ヘッダを持つ最外データ表だけを対象にし、レイアウト表・単純表・
+ * 既に正規化済みの表(救出で挿入済みを含む)は触らないため冪等。
+ * インライン化はブロック要素を持つ全ての表が対象(セル内ul等によるturndown-gfmのouterHTML
+ * ダンプを防ぐため)。入れ子表もgfmからは単体の表として変換される(外表スキップ時に内表だけが
+ * GFM表になる)ので、最外表に限定せず各表を個別にインライン化する。正規化より先に全表を
+ * インライン化するのは、外表の正規化(remove+再挿入)後では旧サブツリー内の入れ子表への
+ * 変更が出力へ反映されないため。
+ */
+export declare function normalizeRetainedTables(contentHtml: string): string;
+/** removeStyleLeakElementsが除去対象を検索・除去できる最小限のDOM互換インターフェース。 */
+interface StyleLeakElement {
+    closest(selector: string): unknown;
+    remove(): void;
+}
+export interface StyleLeakHostDocument {
+    querySelectorAll(selector: string): ArrayLike<StyleLeakElement>;
+}
+/**
+ * turndownにはstyle/scriptの内容を除外するルールが無く、DOM上に残っていると
+ * 地の文への吸収(defaultReplacementが子孫テキストをそのまま連結する)か、gfmプラグインの
+ * 複雑表フォールバック(node.outerHTMLをそのままダンプする)経由でMarkdownへ混入する。
+ * Readability自身は_prepDocumentで<style>を除去するが、それはparse()呼び出し時点の
+ * ドキュメントにしか効かない: 救出表(collectDataTables)はparse前のouterHTMLを採取するため
+ * 道連れにしてしまい、アダプタ/selector経路はReadabilityを経由すらしない。抽出方式に関わらず
+ * 確実に除去するため、全ての抽出処理より前にドキュメント全体から取り除く
+ * (removeConsentBannersより前: バナー判定のテキスト長ヒューリスティックが埋め込みCSSで
+ * 水増しされるのも防げる)。pre/code内は著者が意図的に置いたコード例とみなし対象外にする。
+ *
+ * noscriptは対象に含めない: Readability.parse()は内部の_unwrapNoscriptImages()で、遅延読み込み
+ * プレースホルダimgをnoscript内の実画像へ差し替えてからnoscriptを除去する(style/scriptには
+ * 無い復元ロジック)。ここで先回りして除去すると差し替え元のnoscriptが消え、劣化した
+ * プレースホルダ画像しか残らなくなる。noscript自体の除去はremoveResidualNoscriptElements
+ * (turndown直前の全経路共通パス、Readability実行後)に委ねる。
+ */
+export declare function removeStyleLeakElements(document: StyleLeakHostDocument): void;
+/**
+ * <noscript>の除去は、Readability.parse()内の_unwrapNoscriptImages()(遅延読み込み
+ * プレースホルダimgをnoscript内の実画像へ差し替える処理)より後に行う必要がある
+ * (removeStyleLeakElementsのコメント参照)。readability/geometry/body-fallback経路は
+ * Readability.parse()が常に呼ばれる(結果を使わない場合も含め、渡したdocumentへ破壊的に
+ * 適用される)ため、この時点で画像差し替え・noscript除去は既に完了しており本関数は素通りする。
+ * 一方adapter/selector経路はReadabilityを経由しないため<noscript>が残ったままで、
+ * 地の文へ混入する。turndown直前の全経路共通パスに置くことで、経由済みの経路には影響を
+ * 与えず(冪等)、未経由の経路だけを確実にカバーする。pre/code内は著者が意図的に置いた
+ * コード例とみなし対象外にする。
+ */
+export declare function removeResidualNoscriptElements(html: string): string;
 export declare function extractMarkdown(html: string, options?: ExtractOptions): ExtractResult;
 export {};