linkrot

linkrot

すべての不正な応答をリンク切れとみなすのではなく、失敗の種類を分類するドキュメント用リンクチェッカーです。相対リンクとアンカーはファイルシステムに対して検証されます。外部リンクは、実際に起きたことに基づいて、正常、リンク切れ、移動、ボットによるブロック、エラーに分類されます。ボット対策ページによる403はリンク切れではなく、linkrotがそのように報告することはありません。

機能

• 対象ディレクトリ内のMarkdownファイルを走査します（node_modules、.git、distは除外）。または単一のMarkdownファイルをチェックします。
• インラインリンク（画像リンクを含む）、参照形式の定義、および定義に解決される参照の使用箇所を抽出します。フェンス付きコードブロック内のリンクは無視されます。本文中の単独URLや自動リンクは抽出されません。
• リンクを種類ごとにチェックします。
  • RELATIVE-FILE：パス部分をMarkdownファイルからの相対パスとして解決します。対象が存在しない場合、DEAD-RELATIVEの検出結果として報告されます（高）。
  • RELATIVE-ANCHOR：ファイルは存在しますが、アンカーのスラッグが対象ファイルの見出しスラッグに含まれていません。これはANCHOR-MISSINGの検出結果として報告されます（中）。スラッグは小文字に変換し、句読点を取り除き、スペースをハイフンに置き換えて生成されます。
  • SAME-FILE-ANCHOR：同じファイル内の#sectionのようなリンクを、そのファイルの見出しスラッグと照合します。ANCHOR-MISSINGのルールは同じです。
  • EXTERNAL：オフラインモードでは、httpおよびhttpsリンクは情報エントリーとしてUNCHECKEDと報告されます。件数には含まれますが、チェック結果が失敗になることはありません。
  • MAILTOおよびその他のスキームは、何も報告せずにスキップされ、スキップ件数に含まれます。

インストール

npx @reneturcios/linkrot check .

または、グローバルにインストールします。

npm install -g @reneturcios/linkrot

CLI

linkrot check [path] [--json]
linkrot mcp
linkrot --version

• checkは、パス（デフォルト：現在のディレクトリ）をオフラインでチェックします。判定結果がOKの場合は終了コード0、それ以外の場合は1を返します。機械可読なレポートを出力するには--jsonを使用します。
• mcpは、stdioでMCP サーバーを起動します。
• --versionはバージョンを表示します。

MCP

MCP サーバーは次のツールを1つ公開します。

• path引数を指定するcheck_links。linkrot check --jsonと同じJSONレポートを返します。

デフォルトはオフライン

オフラインモードがデフォルトであり、標準で提供されるモードです。コアは同期処理で、ネットワークリクエストは実行しません。

これは意図的な仕様です。linkrotの根底にある着想は、自動取得がボット対策ページ、ログインゲート、レート制限に頻繁に遭遇するというものです。すべての外部URLを取得し、2xx以外の応答をすべてリンク切れとみなすチェッカーは、サイトがボットをブロックするたびに正常なページを壊れたものとして報告します。オフラインモードでは、この問題を完全に回避できます。ローカルで確認できるもの（相対ファイルとアンカー）を検証し、外部リンクについては推測せず、正直にUNCHECKEDとして報告します。

リンクの種類とステータスの用語

今後、オンラインモードで外部URLをチェックする場合、各HTTPステータスは次のいずれか1つの種類に分類されます。

種類	意味
healthy	2xx、および恒久的な移転ではない3xxリダイレクト（例：302、304、307）
dead	404または410：ページは削除されています
moved	新しい場所へのリダイレクトです。恒久的なリダイレクト（301、308）には、個別のラベルmoved-permanentが付与されます。
bot-blocked	401、403、429：ボット対策ページ、認証ゲート、またはレート制限から応答がありました。人間にとっては問題のないページである可能性があります。
error	5xxおよびその他すべて：チェック自体で信頼できる回答を取得できませんでした

関数classifyStatus(status)はこの表を実装しており、ユニットテストの対象です。bot-blockedをdeadと区別することがこのツールの要点です。両者を混同すると、Cloudflareやログイン画面がすべて誤ったリンク切れとして報告されます。

判定ルール

• DEAD-RELATIVEおよびANCHOR-MISSINGの検出結果がない場合、判定はOKです。
• それ以外の場合、判定はFINDINGSです。
• オフラインモードでは、UNCHECKEDの外部エントリーは判定に影響しません。

レポートには、ファイル数、リンク数、dead、anchorsMissing、externalUncheckedと、種類別の件数（relativeFile、relativeAnchor、sameFileAnchor、external、skipped）が含まれます。

制限事項

• オフラインのコア機能では、相対リンクとアンカーのみをチェックします。
• オフラインでは外部リンクの有効性をチェックしません。外部リンクは「未チェック」として報告し、有効とも無効とも推測しません。将来のオンラインモードでは、上記の用語を使って分類します。
• 抽出対象はインラインリンクと参照定義です（完全参照と省略参照の使用箇所を解決します）。ショートカット参照リンク、裸の URL、自動リンクは抽出しません。
• アンカーのチェックは、リンク先が Markdown ファイルの場合に適用されます。Markdown 以外のファイル内を指すアンカーは検証しません。
• 見出しスラッグには、GitHub の簡易ルールを適用します。小文字に変換し、句読点を削除し、空白をハイフンに置き換えます。重複する見出しには -1、-2 のように接尾辞を付けます。

開発

npm install
npm run build
npm test