architecture/doc-link-target · ドキュメントリンクのリンク先

コメントに書かれたドキュメントリンクは、実在する何かを指し続けている必要があります。

重大度: info · カテゴリ: architecture

チェック内容

コンポーネントのコメント内にある Markdown リンクのうち、リンク先がもう存在しないものを検出します。ただしそのリンクの URL が、プロジェクトのルートを表すと宣言したプレフィックスの配下にある場合に限ります。

このルールは設定するまで無効です。インターネット上のどの URL がリポジトリ内のパスに対応するかは、推測できないためです。

なぜ重要か

コメントに書かれたリンクには、それを解決する仕組みがありません。どの型もそれを参照せず、どのモジュールもそれを import せず、どのテストもそれをレンダリングしないため、リンク先を移動するリネームがあっても静かに壊れたまま残ります――クリックして初めて気づく形で。多くのユニットをリネームする再編成では、こうしたリンクがまとめて壊れることもあります。

修正方法

リンク先を、今実在するユニットに向けるか、リンク自体を削除します。

設定

オプション	型	デフォルト
`urlRoots`	`string-list`	`[]`

各エントリは、このプロジェクトのルートを表す URL プレフィックスです。URL がいずれかで始まるリンクは、そのプレフィックスを取り除かれ、残りの部分が src/ 配下のファイルの中から探されます。

export default {
  rules: {
    'architecture/doc-link-target': {
      options: { urlRoots: ['https://example.test/components/packages/ui/'] }
    }
  }
};

プレフィックスは、公開される URL がたまたま含んでいるワークスペースディレクトリも含めて、丸ごと宣言してください。この部分は公開の仕組み次第で変わるため、解析している場所からは導出できません。

最も長くマッチしたエントリが優先されるため、広いプレフィックスと狭いプレフィックスは共存できます。エントリはリストを置き換えるのではなく追加されるため、第2のホスト（ステージング環境など）で到達可能なプロジェクトは、両方を宣言できます。

報告されないもの

宣言したプレフィックスの配下にない URL――外部サイトへのリンク、ドキュメントのスラッグ、mailto: など。何かを参照として扱うのは宣言そのものであり、リンク先の見た目からは判断しません。
src/ で始まらない残りの部分――たとえばプロジェクトルートの CONTRIBUTING.md や static/logo.svg など。ファイルの一覧は src/ 配下しかカバーしていないため、その外については何も判断できません。そこで「見つからない」を「存在しない」として報告すると、実際には「索引の対象外」でしかないものを誤って報告することになります。
コメントの外にあるリンク。レンダリングされるマークアップは参照ではなくコンテンツです。
相対リンク、または .md ファイル内のリンク。このルールが読むのはコンポーネントのコメントだけです。
// [label](url)。ただし、行内で最初のものであり、かつその行が <script> ブロック内(または .svelte.ts /.svelte.js の runes モジュールでファイル全体がスクリプトである)場合は対象になります。マークアップや <style> ブロック内の同じ文字列はコメントではなくコンテンツであり、行の途中にある // がコメントを開始することもありません――この仕組みのおかげで https:// 内の // をスキャンに巻き込みません。
スクリプト内の /* … */ ブロックコメントや /** … */ の JSDoc コメントの中にあるリンク。スキャン対象はマークアップ形式（）と、行頭の // だけです。

export default {
  rules: {
    'architecture/doc-link-target': 'off'
  }
};

architecture/doc-link-target · ドキュメントリンクのリンク先

チェック内容

なぜ重要か

修正方法

設定

報告されないもの

制限事項

モードによる違い

無効化