@riebeckite/plugin-diagnostics 0.0.12 → 0.0.14

package/README.md

@@ -1,132 +1,159 @@
-# @riebeckite/plugin-diagnostics
-
-Content diagnostics for Obsidian vaults / Riebeckite content: broken links,
-frontmatter issues, orphan notes, unused assets, and more. Usable as a build
-plugin, a programmatic API, and a CLI.
-
-[日本語](./README_ja.md)
-
-## Overview
-
-`diagnostics()` analyzes the content directory and reports problems as
-diagnostics during the build. The same checks are available through
-`runDiagnostics()` and the `riebeckite-diagnostics` CLI.
-
-## Usage (plugin)
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-import { diagnostics } from "@riebeckite/plugin-diagnostics";
-
-export default defineConfig({
-  // ...
-  plugins: [
-    diagnostics({
-      reportUnusedAssets: true,
-      reportOrphans: true,
-      requiredFrontmatter: ["title"],
-    }),
-  ],
-});
-```
-
-- `addDiagnostics` — runs the analysis at build time; results go to
-  `manifest.diagnostics`
-- `onBuildEnd` — with `failOnError: true`, throws `DiagnosticsFailure` when
-  error-level diagnostics exist
-
-## Checks
-
-| Code | Default severity | What it detects |
-| ---- | ---------------- | --------------- |
-| `broken-wikilink` | `error` | Wikilink target or fragment does not resolve |
-| `broken-image` | `error` | Embedded image or image link does not exist |
-| `broken-link` | `error` | Markdown link points to a missing or excluded note/file |
-| `unused-asset` | `warning` | Image never referenced by any note (`reportUnusedAssets`) |
-| `orphan-note` | `info` | Published note has no incoming links (`reportOrphans`) |
-| `missing-frontmatter` | `warning` | No frontmatter, or required fields missing |
-| `publish-conflict` | `warning` | `publish: true` combined with `draft: true` / `private: true` |
-| `duplicate-title` | `warning` | Multiple published notes share a title |
-| `slug-collision` | `error` | Slugs collide case-insensitively |
-| `duplicate-content-id` | `error` | Published notes share a stable content ID (`id`/`uid`) |
-| `invalid-content-id` | `error` | `id`/`uid` frontmatter violates the stable content ID contract |
-| `excluded-public` | `warning` | Excluded note is marked `publish: true` |
-| `publish-boundary` | `warning` | Published content links to or embeds non-published content |
-| `analytics-untracked` | `info` | Published note has no stable `id` and the analytics plugin will not track it (enabled with `reportAnalyticsCoverage`, or automatically when the config enables the analytics plugin) |
-| `internal-error` | `error` | Content analysis failed |
-
-## Options
-
-| Option | Type | Default | Description |
-| ------ | ---- | ------- | ----------- |
-| `failOnError` | `boolean` | `false` | Fail the build on error-level diagnostics |
-| `reportUnusedAssets` | `boolean` | `false` | Report unreferenced images |
-| `reportOrphans` | `boolean` | `false` | Report published notes without incoming links |
-| `reportAnalyticsCoverage` | `boolean` | `false` | Report published notes the analytics plugin will not track (auto-enabled when the resolved config enables the analytics plugin) |
-| `requiredFrontmatter` | `string[]` | `[]` | Required frontmatter fields |
-| `severity` | `Partial<Record<DiagnosticCode, DiagnosticSeverity>>` | table above | Override severity per code |
-| `exclude` | `string[]` | `[]` | Extra exclude globs |
-| `publishStrategy` | `"explicit" \| "selective"` | from config | Publication filter strategy |
-
-## CLI
-
-```bash
-riebeckite-diagnostics --config riebeckite.config.ts
-riebeckite-diagnostics --content ./content --report-orphans
-```
-
-| Option | Description |
-| ------ | ----------- |
-| `--config <path>` | Path to `riebeckite.config.ts` (loaded under tsx) |
-| `--content <dir>` | Content directory to analyze (default: `.`) |
-| `--exclude <glob>` | Extra exclude glob (repeatable) |
-| `--publish-strategy <mode>` | `explicit` \| `selective` (default: `selective`) |
-| `--report-unused-assets` | Report images never referenced by any note |
-| `--report-orphans` | Report published notes with no incoming links |
-| `--report-analytics-coverage` | Report published notes without a stable content ID (auto-enabled for `--config` when the config enables the analytics plugin) |
-| `--required-frontmatter <f>` | Comma-separated required frontmatter fields |
-| `--fail-on-error` | Exit with code 1 when errors are found (default) |
-| `--exit-on <severity>` | Exit with code 1 at/above severity (`info` \| `warning` \| `error`) |
-| `--format <text\|json>` | Output format (default: `text`) |
-| `--no-color` | Disable ANSI colors |
-| `-h`, `--help` | Show help |
-
-Exit codes: `0` no errors, `1` errors reported (or `--exit-on` threshold met),
-`2` invalid arguments.
-
-With `--config`, options from the config's `diagnostics` plugin are used as
-defaults; explicit CLI flags override them, and `exclude` lists are merged.
-
-## Programmatic API
-
-```ts
-import {
-  assertNoErrors,
-  formatDiagnostics,
-  runDiagnostics,
-} from "@riebeckite/plugin-diagnostics";
-
-const report = await runDiagnostics("./content", { reportOrphans: true });
-console.log(formatDiagnostics(report));
-assertNoErrors(report);
-```
-
-`runDiagnostics(config | path, options?)` returns a `DiagnosticsReport` with
-`diagnostics`, `errors`, `warnings`, `infos`, `hasErrors`, `hasWarnings`,
-`summary`, and `byCode`.
-
-## Exports
-
-- `diagnostics(options?)` / `diagnosticsPlugin` — plugin factory
-- `runDiagnostics(target, options?)` — run the analysis directly
-- `analyzeContent(config, options?)` — raw analysis returning `Diagnostic[]`
-- `hasEnabledAnalyticsPlugin(config?)` — whether the resolved config enables the analytics plugin
-- Report helpers: `buildReport`, `formatDiagnostics`, `groupByCode`,
-  `summarize`, `assertNoErrors`, `DiagnosticsFailure`
-- Types: `DiagnosticsOptions`, `DiagnosticsReport`, `DiagnosticsSummary`,
-  `AnalyzerContentConfig`
-- CLI: `riebeckite-diagnostics`
-
-## See also
-
-- [Plugin guide](../../../docs/en/plugin-system.md)
+# @riebeckite/plugin-diagnostics
+
+Content diagnostics for Obsidian vaults / Riebeckite content: site-wide
+reference integrity, frontmatter issues, orphan notes, unused assets, and more.
+Usable as a build plugin, a programmatic API, and a CLI.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+`diagnostics()` analyzes the content directory and reports problems as
+diagnostics during the build. The same checks are available through
+`runDiagnostics()` and the `riebeckite-diagnostics` CLI.
+
+## Usage (plugin)
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { diagnostics } from "@riebeckite/plugin-diagnostics";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    diagnostics({
+      reportUnusedAssets: true,
+      reportOrphans: true,
+      requiredFrontmatter: ["title"],
+    }),
+  ],
+});
+```
+
+- `addDiagnostics` — runs the analysis at build time; results go to
+  `manifest.diagnostics`
+- `onBuildEnd` — with `failOnError: true`, throws `DiagnosticsFailure` when
+  error-level diagnostics exist
+
+## Checks
+
+| Code | Default severity | What it detects |
+| ---- | ---------------- | --------------- |
+| `broken-wikilink` | `error` | Wikilink target or fragment does not resolve |
+| `broken-image` | `error` | Embedded image or image link does not exist |
+| `broken-link` | `error` | Markdown link points to a missing or excluded note/file |
+| `unused-asset` | `warning` | Image never referenced by any note (`reportUnusedAssets`) |
+| `orphan-note` | `info` | Published note has no incoming links (`reportOrphans`) |
+| `missing-frontmatter` | `warning` | No frontmatter, or required fields missing |
+| `publish-conflict` | `warning` | `publish: true` combined with `draft: true` / `private: true` |
+| `duplicate-title` | `warning` | Multiple published notes share a title |
+| `slug-collision` | `error` | Slugs collide case-insensitively |
+| `duplicate-content-id` | `error` | Published notes share a stable content ID (`id`/`uid`) |
+| `invalid-content-id` | `error` | `id`/`uid` frontmatter violates the stable content ID contract |
+| `excluded-public` | `warning` | Excluded note is marked `publish: true` |
+| `publish-boundary` | `warning` | Published content links to or embeds non-published content |
+| `analytics-untracked` | `info` | Published note has no stable `id` and the analytics plugin will not track it (enabled with `reportAnalyticsCoverage`, or automatically when the config enables the analytics plugin) |
+| `content-integrity:broken-link` | `warning` | A published page links to a site-local route that is not published or registered |
+| `content-integrity:unresolved-wikilink` | `warning` | A published entry contains a WikiLink that the configured WikiLink/content index resolution did not resolve |
+| `content-integrity:broken-asset` | `warning` | A published page references a local asset that is not in resolved content assets, plugin assets, generated outputs, or public routes |
+| `content-integrity:duplicate-public-location` | `error` | Two published entries or generated routes claim the same final public path |
+| `content-integrity:redirect-target-missing` | `warning` | A public redirect points at content whose public target is unavailable |
+| `content-integrity:redirect-cycle` | `error` | Public redirects form a cycle |
+| `content-integrity:redirect-public-location-conflict` | `error` | A redirect path conflicts with another public route |
+| `internal-error` | `error` | Content analysis failed |
+
+## Site-wide content integrity
+
+When used as a Riebeckite plugin, diagnostics runs site-wide integrity checks
+from the resolved manifest instead of rescanning content for link rules. It uses
+`publicEntries`, resolved `ContentLink` metadata, `ContentPublicLocation`,
+`publicRedirects`, plugin page paths, plugin assets, and generated outputs.
+This keeps permalink, alias, rename redirect, l10n, publish/exclude, and Page
+System behavior aligned with the build pipeline.
+
+It does not check external HTTP reachability, SEO, spelling, Lighthouse, or
+automatic repairs. External URLs (`http:`, `https:`, `mailto:`, `tel:`, `data:`),
+protocol-relative URLs, and fragment-only links are ignored. Query strings and
+fragments are stripped before route existence checks. Plugin authors should
+register generated routes through Page Types and generated files/assets through
+the existing plugin output/asset contracts so integrity checks can treat them as
+valid public targets.
+
+`runDiagnostics()` and the standalone CLI still use the filesystem/content-source
+analyzer because no full manifest is available in that mode.
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `failOnError` | `boolean` | `false` | Fail the build on error-level diagnostics |
+| `reportUnusedAssets` | `boolean` | `false` | Report unreferenced images |
+| `reportOrphans` | `boolean` | `false` | Report published notes without incoming links |
+| `reportAnalyticsCoverage` | `boolean` | `false` | Report published notes the analytics plugin will not track (auto-enabled when the resolved config enables the analytics plugin) |
+| `requiredFrontmatter` | `string[]` | `[]` | Required frontmatter fields |
+| `severity` | `Partial<Record<DiagnosticCode, DiagnosticSeverity>>` | table above | Override severity per code |
+| `exclude` | `string[]` | `[]` | Extra exclude globs |
+| `publishStrategy` | `"explicit" \| "selective"` | from config | Publication filter strategy |
+
+## CLI
+
+```bash
+riebeckite-diagnostics --config riebeckite.config.ts
+riebeckite-diagnostics --content ./content --report-orphans
+```
+
+| Option | Description |
+| ------ | ----------- |
+| `--config <path>` | Path to `riebeckite.config.ts` (loaded under tsx) |
+| `--content <dir>` | Content directory to analyze (default: `.`) |
+| `--exclude <glob>` | Extra exclude glob (repeatable) |
+| `--publish-strategy <mode>` | `explicit` \| `selective` (default: `selective`) |
+| `--report-unused-assets` | Report images never referenced by any note |
+| `--report-orphans` | Report published notes with no incoming links |
+| `--report-analytics-coverage` | Report published notes without a stable content ID (auto-enabled for `--config` when the config enables the analytics plugin) |
+| `--required-frontmatter <f>` | Comma-separated required frontmatter fields |
+| `--fail-on-error` | Exit with code 1 when errors are found (default) |
+| `--exit-on <severity>` | Exit with code 1 at/above severity (`info` \| `warning` \| `error`) |
+| `--format <text\|json>` | Output format (default: `text`) |
+| `--no-color` | Disable ANSI colors |
+| `-h`, `--help` | Show help |
+
+Exit codes: `0` no errors, `1` errors reported (or `--exit-on` threshold met),
+`2` invalid arguments.
+
+With `--config`, options from the config's `diagnostics` plugin are used as
+defaults; explicit CLI flags override them, and `exclude` lists are merged.
+
+## Programmatic API
+
+```ts
+import {
+  assertNoErrors,
+  formatDiagnostics,
+  runDiagnostics,
+} from "@riebeckite/plugin-diagnostics";
+
+const report = await runDiagnostics("./content", { reportOrphans: true });
+console.log(formatDiagnostics(report));
+assertNoErrors(report);
+```
+
+`runDiagnostics(config | path, options?)` returns a `DiagnosticsReport` with
+`diagnostics`, `errors`, `warnings`, `infos`, `hasErrors`, `hasWarnings`,
+`summary`, and `byCode`.
+
+## Exports
+
+- `diagnostics(options?)` / `diagnosticsPlugin` — plugin factory
+- `runDiagnostics(target, options?)` — run the analysis directly
+- `analyzeContent(config, options?)` — raw analysis returning `Diagnostic[]`
+- `hasEnabledAnalyticsPlugin(config?)` — whether the resolved config enables the analytics plugin
+- Report helpers: `buildReport`, `formatDiagnostics`, `groupByCode`,
+  `summarize`, `assertNoErrors`, `DiagnosticsFailure`
+- Types: `DiagnosticsOptions`, `DiagnosticsReport`, `DiagnosticsSummary`,
+  `AnalyzerContentConfig`
+- CLI: `riebeckite-diagnostics`
+
+## See also
+
+- [Plugin guide](../../../docs/en/reference/plugin-api.md)

package/README_ja.md

@@ -1,103 +1,118 @@
-# @riebeckite/plugin-diagnostics
-
-コンテンツのリンク切れ、公開設定の矛盾、frontmatter の不足などを検出するプラグインです。ビルド時の診断だけでなく、CLI とプログラムからの実行にも対応します。
-
-[English](./README.md)
-
-## まずはビルドに診断を加える
-
-通常は `diagnostics()` を設定に登録します。診断結果は manifest に入り、`failOnError` を有効にするとエラーがあったビルドを失敗させられます。
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-import { diagnostics } from "@riebeckite/plugin-diagnostics";
-
-export default defineConfig({
-  // ...
-  plugins: [
-    diagnostics({
-      reportUnusedAssets: true,
-      reportOrphans: true,
-      requiredFrontmatter: ["title"],
-    }),
-  ],
-});
-```
-
-## 検出する問題
-
-| コード | 既定の重要度 | 内容 |
-| --- | --- | --- |
-| `broken-wikilink` | error | Wikiリンクの参照先またはフラグメントを解決できない |
-| `broken-image` | error | 埋め込み画像または画像リンクの参照先がない |
-| `broken-link` | error | Markdown リンクが存在しない、または除外されたノートを指す |
-| `unused-asset` | warning | どのノートからも参照されない画像 |
-| `orphan-note` | info | 公開ノートのうち、他のノートからリンクされていないもの |
-| `missing-frontmatter` | warning | frontmatter がない、または必須フィールドが欠けている |
-| `publish-conflict` | warning | `publish: true` と `draft: true` または `private: true` が同居している |
-| `duplicate-title` | warning | 公開ノート同士でタイトルが重複している |
-| `slug-collision` | error | 大文字・小文字を区別しない slug が衝突している |
-| `duplicate-content-id` | error | 公開ノート同士で安定コンテンツ ID（`id`/`uid`）が重複している |
-| `invalid-content-id` | error | `id`/`uid` の frontmatter が安定コンテンツ ID の契約を満たしていない |
-| `excluded-public` | warning | 除外されたノートに `publish: true` が指定されている |
-| `publish-boundary` | warning | 公開コンテンツから非公開コンテンツへリンク・埋め込みしている |
-| `analytics-untracked` | info | 安定 `id` のない公開ノートは analytics プラグインで計測されない（`reportAnalyticsCoverage` で有効化。設定で analytics プラグインが有効な場合は自動で有効化） |
-| `internal-error` | error | コンテンツ解析中に処理できないエラーが発生した |
-
-未使用アセットと孤立ノートは、明示的に有効化した場合だけ確認します。意図的に孤立させるトップページなどがあるなら、`reportOrphans` の結果を公開方針と照らして判断してください。
-
-## 設定項目
-
-| 項目 | 既定値 | 説明 |
-| --- | --- | --- |
-| `failOnError` | `false` | error レベルの診断があればビルドを失敗させる |
-| `reportUnusedAssets` | `false` | 未参照画像を報告する |
-| `reportOrphans` | `false` | 孤立した公開ノートを報告する |
-| `reportAnalyticsCoverage` | `false` | analytics プラグインで計測されない公開ノートを報告する（解決済み設定で analytics プラグインが有効なら自動で有効化） |
-| `requiredFrontmatter` | `[]` | 必須にする frontmatter フィールド |
-| `severity` | コードごとの既定値 | 診断コード別の重要度を上書きする |
-| `exclude` | `[]` | 解析対象から追加で除外する glob |
-| `publishStrategy` | 設定ファイルの値 | 公開ノートの判定方法 |
-
-## CI や編集時には CLI を使う
-
-設定を読み込んで実行する場合は、次のようにします。
-
-```bash
-riebeckite-diagnostics --config riebeckite.config.ts
-riebeckite-diagnostics --content ./content --report-orphans
-```
-
-`--format json` は機械処理用、`--exit-on warning` は警告以上を CI の失敗条件にしたい場合に使います。終了コードは、問題なしが `0`、指定したしきい値以上の診断があれば `1`、引数の誤りは `2` です。`--config` 使用時は設定内のオプションを既定値にし、CLI で明示した値を優先します。
-
-## アプリケーションから実行する
-
-エディタ連携や独自のレポートには `runDiagnostics()` を使えます。
-
-```ts
-import {
-  assertNoErrors,
-  formatDiagnostics,
-  runDiagnostics,
-} from "@riebeckite/plugin-diagnostics";
-
-const report = await runDiagnostics("./content", { reportOrphans: true });
-console.log(formatDiagnostics(report));
-assertNoErrors(report);
-```
-
-`DiagnosticsReport` には診断の一覧に加え、エラー・警告・情報の件数、コード別の集計、`hasErrors` と `hasWarnings` が入ります。
-
-## 主なエクスポート
-
-- `diagnostics(options?)` / `diagnosticsPlugin`: プラグインを作成する
-- `runDiagnostics(target, options?)`: 診断と集計を実行する
-- `analyzeContent(config, options?)`: 生の `Diagnostic[]` を取得する
-- `hasEnabledAnalyticsPlugin(config?)`: 解決済み設定で analytics プラグインが有効かを判定する
-- `formatDiagnostics`、`summarize`、`groupByCode`、`assertNoErrors`: レポート処理用の補助関数
-- `DiagnosticsFailure`: `failOnError` または `assertNoErrors` が送出するエラー
-- `riebeckite-diagnostics`: CLI
-
-## 関連資料
-
-- [プラグインシステム](../../../docs/ja/plugin-system.md)
+# @riebeckite/plugin-diagnostics
+
+サイト全体の参照整合性、公開設定の矛盾、frontmatter の不足などを検出するプラグインです。ビルド時の診断だけでなく、CLI とプログラムからの実行にも対応します。
+
+[English](./README.md)
+
+## まずはビルドに診断を加える
+
+通常は `diagnostics()` を設定に登録します。診断結果は manifest に入り、`failOnError` を有効にするとエラーがあったビルドを失敗させられます。
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { diagnostics } from "@riebeckite/plugin-diagnostics";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    diagnostics({
+      reportUnusedAssets: true,
+      reportOrphans: true,
+      requiredFrontmatter: ["title"],
+    }),
+  ],
+});
+```
+
+## 検出する問題
+
+| コード | 既定の重要度 | 内容 |
+| --- | --- | --- |
+| `broken-wikilink` | error | Wikiリンクの参照先またはフラグメントを解決できない |
+| `broken-image` | error | 埋め込み画像または画像リンクの参照先がない |
+| `broken-link` | error | Markdown リンクが存在しない、または除外されたノートを指す |
+| `unused-asset` | warning | どのノートからも参照されない画像 |
+| `orphan-note` | info | 公開ノートのうち、他のノートからリンクされていないもの |
+| `missing-frontmatter` | warning | frontmatter がない、または必須フィールドが欠けている |
+| `publish-conflict` | warning | `publish: true` と `draft: true` または `private: true` が同居している |
+| `duplicate-title` | warning | 公開ノート同士でタイトルが重複している |
+| `slug-collision` | error | 大文字・小文字を区別しない slug が衝突している |
+| `duplicate-content-id` | error | 公開ノート同士で安定コンテンツ ID（`id`/`uid`）が重複している |
+| `invalid-content-id` | error | `id`/`uid` の frontmatter が安定コンテンツ ID の契約を満たしていない |
+| `excluded-public` | warning | 除外されたノートに `publish: true` が指定されている |
+| `publish-boundary` | warning | 公開コンテンツから非公開コンテンツへリンク・埋め込みしている |
+| `analytics-untracked` | info | 安定 `id` のない公開ノートは analytics プラグインで計測されない（`reportAnalyticsCoverage` で有効化。設定で analytics プラグインが有効な場合は自動で有効化） |
+| `content-integrity:broken-link` | warning | 公開ページが、公開または登録されていないサイト内経路へリンクしている |
+| `content-integrity:unresolved-wikilink` | warning | 公開ページ内の Wikiリンクを、設定済みの解決規則で解決できない |
+| `content-integrity:broken-asset` | warning | 公開ページが、解決済みアセット・プラグインアセット・生成出力・公開経路のいずれにもないローカルアセットを参照している |
+| `content-integrity:duplicate-public-location` | error | 複数の公開コンテンツまたは生成経路が、同じ最終公開パスを所有している |
+| `content-integrity:redirect-target-missing` | warning | 公開リダイレクトの転送先コンテンツが公開されない |
+| `content-integrity:redirect-cycle` | error | 公開リダイレクトが循環している |
+| `content-integrity:redirect-public-location-conflict` | error | リダイレクト元のパスが別の公開経路と衝突している |
+| `internal-error` | error | コンテンツ解析中に処理できないエラーが発生した |
+
+未使用アセットと孤立ノートは、明示的に有効化した場合だけ確認します。意図的に孤立させるトップページなどがあるなら、`reportOrphans` の結果を公開方針と照らして判断してください。
+
+## サイト全体の参照整合性
+
+Riebeckite のプラグインとして使う場合、リンク関係の検査はコンテンツを再走査せず、解決済み manifest から行います。`publicEntries`、解決済み `ContentLink`、`ContentPublicLocation`、`publicRedirects`、プラグインページのパス、プラグインアセット、生成出力を参照します。これにより permalink、alias、rename によるリダイレクト、l10n、公開・除外設定、Page System の扱いがビルド処理と揃います。
+
+外部 URL の疎通確認、SEO、スペルチェック、Lighthouse、自動修復は行いません。`http:`、`https:`、`mailto:`、`tel:`、`data:`、プロトコル相対 URL、ページ内フラグメントだけのリンクは対象外です。経路の存在確認では、クエリ文字列とフラグメントを除いて判定します。生成ページや生成アセットを提供するプラグインは、Page Type、生成出力、アセット登録の既存契約を使ってください。登録されていれば、整合性検査でも有効な公開先として扱われます。
+
+`runDiagnostics()` と単体 CLI は、完全な manifest を持たないため、従来の content source 解析を使います。
+
+## 設定項目
+
+| 項目 | 既定値 | 説明 |
+| --- | --- | --- |
+| `failOnError` | `false` | error レベルの診断があればビルドを失敗させる |
+| `reportUnusedAssets` | `false` | 未参照画像を報告する |
+| `reportOrphans` | `false` | 孤立した公開ノートを報告する |
+| `reportAnalyticsCoverage` | `false` | analytics プラグインで計測されない公開ノートを報告する（解決済み設定で analytics プラグインが有効なら自動で有効化） |
+| `requiredFrontmatter` | `[]` | 必須にする frontmatter フィールド |
+| `severity` | コードごとの既定値 | 診断コード別の重要度を上書きする |
+| `exclude` | `[]` | 解析対象から追加で除外する glob |
+| `publishStrategy` | 設定ファイルの値 | 公開ノートの判定方法 |
+
+## CI や編集時には CLI を使う
+
+設定を読み込んで実行する場合は、次のようにします。
+
+```bash
+riebeckite-diagnostics --config riebeckite.config.ts
+riebeckite-diagnostics --content ./content --report-orphans
+```
+
+`--format json` は機械処理用、`--exit-on warning` は警告以上を CI の失敗条件にしたい場合に使います。終了コードは、問題なしが `0`、指定したしきい値以上の診断があれば `1`、引数の誤りは `2` です。`--config` 使用時は設定内のオプションを既定値にし、CLI で明示した値を優先します。
+
+## アプリケーションから実行する
+
+エディタ連携や独自のレポートには `runDiagnostics()` を使えます。
+
+```ts
+import {
+  assertNoErrors,
+  formatDiagnostics,
+  runDiagnostics,
+} from "@riebeckite/plugin-diagnostics";
+
+const report = await runDiagnostics("./content", { reportOrphans: true });
+console.log(formatDiagnostics(report));
+assertNoErrors(report);
+```
+
+`DiagnosticsReport` には診断の一覧に加え、エラー・警告・情報の件数、コード別の集計、`hasErrors` と `hasWarnings` が入ります。
+
+## 主なエクスポート
+
+- `diagnostics(options?)` / `diagnosticsPlugin`: プラグインを作成する
+- `runDiagnostics(target, options?)`: 診断と集計を実行する
+- `analyzeContent(config, options?)`: 生の `Diagnostic[]` を取得する
+- `hasEnabledAnalyticsPlugin(config?)`: 解決済み設定で analytics プラグインが有効かを判定する
+- `formatDiagnostics`、`summarize`、`groupByCode`、`assertNoErrors`: レポート処理用の補助関数
+- `DiagnosticsFailure`: `failOnError` または `assertNoErrors` が送出するエラー
+- `riebeckite-diagnostics`: CLI
+
+## 関連資料
+
+- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)

package/dist/bin.js

@@ -818,14 +818,16 @@ async function analyzeContent(config, options = {}) {
   const state = createAnalysisState();
   const diagnostics = [];
   for (const note of source.includedNotes) {
-    checkWikilinks(note, source, state, normalizedOptions, diagnostics);
-    checkMarkdownReferences(
-      note,
-      source,
-      state,
-      normalizedOptions,
-      diagnostics
-    );
+    if (!options.skipReferenceIntegrity) {
+      checkWikilinks(note, source, state, normalizedOptions, diagnostics);
+      checkMarkdownReferences(
+        note,
+        source,
+        state,
+        normalizedOptions,
+        diagnostics
+      );
+    }
     checkFrontmatter(note, source, state, normalizedOptions, diagnostics);
   }
   checkSlugCollisions(source, normalizedOptions, diagnostics);
@@ -834,7 +836,8 @@ async function analyzeContent(config, options = {}) {
   checkOrphans(source, state, normalizedOptions, diagnostics);
   checkUnusedAssets(source, state, normalizedOptions, diagnostics);
   checkExcludedPublic(source, normalizedOptions, diagnostics);
-  checkPublishBoundary(source, normalizedOptions, diagnostics);
+  if (!options.skipReferenceIntegrity)
+    checkPublishBoundary(source, normalizedOptions, diagnostics);
   checkAnalyticsCoverage(source, normalizedOptions, diagnostics);
   return diagnostics;
 }

package/dist/index.js

@@ -814,14 +814,16 @@ async function analyzeContent(config, options = {}) {
   const state = createAnalysisState();
   const diagnostics2 = [];
   for (const note of source.includedNotes) {
-    checkWikilinks(note, source, state, normalizedOptions, diagnostics2);
-    checkMarkdownReferences(
-      note,
-      source,
-      state,
-      normalizedOptions,
-      diagnostics2
-    );
+    if (!options.skipReferenceIntegrity) {
+      checkWikilinks(note, source, state, normalizedOptions, diagnostics2);
+      checkMarkdownReferences(
+        note,
+        source,
+        state,
+        normalizedOptions,
+        diagnostics2
+      );
+    }
     checkFrontmatter(note, source, state, normalizedOptions, diagnostics2);
   }
   checkSlugCollisions(source, normalizedOptions, diagnostics2);
@@ -830,7 +832,8 @@ async function analyzeContent(config, options = {}) {
   checkOrphans(source, state, normalizedOptions, diagnostics2);
   checkUnusedAssets(source, state, normalizedOptions, diagnostics2);
   checkExcludedPublic(source, normalizedOptions, diagnostics2);
-  checkPublishBoundary(source, normalizedOptions, diagnostics2);
+  if (!options.skipReferenceIntegrity)
+    checkPublishBoundary(source, normalizedOptions, diagnostics2);
   checkAnalyticsCoverage(source, normalizedOptions, diagnostics2);
   return diagnostics2;
 }
@@ -855,16 +858,16 @@ function buildReport(diagnostics2) {
   const errors = [];
   const warnings = [];
   const infos = [];
-  for (const diagnostic of diagnostics2) {
-    switch (diagnostic.severity) {
+  for (const diagnostic2 of diagnostics2) {
+    switch (diagnostic2.severity) {
       case "error":
-        errors.push(diagnostic);
+        errors.push(diagnostic2);
         break;
       case "warning":
-        warnings.push(diagnostic);
+        warnings.push(diagnostic2);
         break;
       default:
-        infos.push(diagnostic);
+        infos.push(diagnostic2);
         break;
     }
   }
@@ -883,8 +886,8 @@ function summarize(diagnostics2) {
   let error = 0;
   let warning = 0;
   let info = 0;
-  for (const diagnostic of diagnostics2) {
-    switch (diagnostic.severity) {
+  for (const diagnostic2 of diagnostics2) {
+    switch (diagnostic2.severity) {
       case "error":
         error++;
         break;
@@ -900,10 +903,10 @@ function summarize(diagnostics2) {
 }
 function groupByCode(diagnostics2) {
   const byCode = /* @__PURE__ */ new Map();
-  for (const diagnostic of diagnostics2) {
-    const group = byCode.get(diagnostic.code) ?? [];
-    group.push(diagnostic);
-    byCode.set(diagnostic.code, group);
+  for (const diagnostic2 of diagnostics2) {
+    const group = byCode.get(diagnostic2.code) ?? [];
+    group.push(diagnostic2);
+    byCode.set(diagnostic2.code, group);
   }
   return byCode;
 }
@@ -922,23 +925,23 @@ function formatDiagnostics(input, options = {}) {
   );
   lines.push("");
   const ordered = [...report.diagnostics].sort(compareDiagnostics);
-  for (const diagnostic of ordered) {
+  for (const diagnostic2 of ordered) {
     const icon = {
       error: `${color.error}✖`,
       warning: `${color.yellow}⚠`,
       info: `${color.cyan}ℹ`
-    }[diagnostic.severity];
+    }[diagnostic2.severity];
     const location = [
-      diagnostic.filePath ?? "",
-      diagnostic.line != null ? `:${diagnostic.line}${diagnostic.column != null ? `:${diagnostic.column}` : ""}` : ""
+      diagnostic2.filePath ?? "",
+      diagnostic2.line != null ? `:${diagnostic2.line}${diagnostic2.column != null ? `:${diagnostic2.column}` : ""}` : ""
     ].join("");
-    lines.push(`${icon} ${color.reset}[${diagnostic.code}] ${location}`);
-    lines.push(`    ${diagnostic.message}`);
-    if (diagnostic.target) {
-      lines.push(`    ${color.dim}target: ${diagnostic.target}${color.reset}`);
+    lines.push(`${icon} ${color.reset}[${diagnostic2.code}] ${location}`);
+    lines.push(`    ${diagnostic2.message}`);
+    if (diagnostic2.target) {
+      lines.push(`    ${color.dim}target: ${diagnostic2.target}${color.reset}`);
     }
-    if (diagnostic.suggestion) {
-      lines.push(`    ${color.cyan}→ ${diagnostic.suggestion}${color.reset}`);
+    if (diagnostic2.suggestion) {
+      lines.push(`    ${color.cyan}→ ${diagnostic2.suggestion}${color.reset}`);
     }
   }
   return lines.join("\n");
@@ -973,8 +976,303 @@ var noColors = {
   cyan: ""
 };
 
-// index.ts
+// src/site_integrity.ts
 var PLUGIN_NAME2 = "diagnostics";
+var DEFAULT_SEVERITY2 = {
+  "content-integrity:broken-link": "warning",
+  "content-integrity:unresolved-wikilink": "warning",
+  "content-integrity:broken-asset": "warning",
+  "content-integrity:duplicate-public-location": "error",
+  "content-integrity:redirect-target-missing": "warning",
+  "content-integrity:redirect-cycle": "error",
+  "content-integrity:redirect-public-location-conflict": "error"
+};
+function checkSiteIntegrity(manifest, options = {}) {
+  const diagnostics2 = [];
+  const publicSlugs = new Set(
+    manifest.publicEntries.map((entry) => entry.slug)
+  );
+  const routeOwners = buildRouteOwners(manifest, diagnostics2, options);
+  const publicRoutes = new Set(routeOwners.keys());
+  const assetPaths = buildAssetPaths(manifest);
+  for (const entry of manifest.publicEntries) {
+    checkResolvedLinks(entry, publicSlugs, assetPaths, diagnostics2, options);
+    checkHtmlReferences(entry, publicRoutes, assetPaths, diagnostics2, options);
+  }
+  checkRedirectTargets(manifest, publicRoutes, diagnostics2, options);
+  checkRedirectCycles(manifest, diagnostics2, options);
+  return diagnostics2;
+}
+function buildRouteOwners(manifest, diagnostics2, options) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const entry of manifest.publicEntries) {
+    reserveRoute(owners, diagnostics2, options, {
+      path: normalizeRoutePath(entry.publicLocation.permalink),
+      slug: entry.slug,
+      kind: "content"
+    });
+  }
+  for (const [path, redirect] of manifest.publicRedirects) {
+    reserveRoute(owners, diagnostics2, options, {
+      path: normalizeRoutePath(path),
+      slug: redirect.slug,
+      kind: "redirect"
+    });
+  }
+  const pagePaths = manifest.pagePaths ?? [];
+  for (const path of pagePaths) {
+    reserveRoute(owners, diagnostics2, options, {
+      path: normalizeRoutePath(path),
+      slug: "(plugin-page)",
+      kind: "page"
+    });
+  }
+  for (const output of manifest.generatedOutputs ?? []) {
+    reserveRoute(owners, diagnostics2, options, {
+      path: normalizeRoutePath(output.path),
+      slug: "(generated-output)",
+      kind: "output"
+    });
+  }
+  return owners;
+}
+function reserveRoute(owners, diagnostics2, options, next) {
+  const previous = owners.get(next.path);
+  if (!previous) {
+    owners.set(next.path, next);
+    return;
+  }
+  if (previous.slug === next.slug && previous.kind === next.kind) return;
+  const code = previous.kind === "redirect" || next.kind === "redirect" ? "content-integrity:redirect-public-location-conflict" : "content-integrity:duplicate-public-location";
+  diagnostics2.push(
+    diagnostic(options, {
+      code,
+      slug: next.slug.startsWith("(") ? void 0 : next.slug,
+      target: next.path,
+      message: `Public path "${next.path}" is claimed by both ${describeOwner(previous)} and ${describeOwner(next)}.`,
+      suggestion: "Change one permalink, alias, redirect, page path, or generated output path.",
+      meta: { previous, next }
+    })
+  );
+}
+function checkResolvedLinks(entry, publicSlugs, assetPaths, diagnostics2, options) {
+  for (const link of entry.links) {
+    if (link.kind === "unresolved") {
+      diagnostics2.push(
+        diagnostic(options, {
+          code: "content-integrity:unresolved-wikilink",
+          slug: entry.slug,
+          filePath: `${entry.slug}.md`,
+          target: link.raw,
+          message: `WikiLink target "${link.raw}" could not be resolved.`,
+          suggestion: "Create the target note/asset or update the WikiLink target.",
+          meta: { raw: link.raw, embed: link.embed }
+        })
+      );
+      continue;
+    }
+    if (link.kind === "note" && link.slug && !publicSlugs.has(link.slug)) {
+      diagnostics2.push(
+        diagnostic(options, {
+          code: "content-integrity:broken-link",
+          slug: entry.slug,
+          filePath: `${entry.slug}.md`,
+          target: link.slug,
+          message: `Content link "${link.raw}" resolves to unpublished content "${link.slug}".`,
+          suggestion: "Publish the target content or remove the reference from published content.",
+          meta: {
+            raw: link.raw,
+            resolvedSlug: link.slug,
+            reason: "unpublished-target"
+          }
+        })
+      );
+    }
+    if ((link.kind === "image" || link.kind === "attachment") && link.slug && !assetPaths.has(link.slug)) {
+      diagnostics2.push(
+        diagnostic(options, {
+          code: "content-integrity:broken-asset",
+          slug: entry.slug,
+          filePath: `${entry.slug}.md`,
+          target: link.slug,
+          message: `Asset reference "${link.raw}" resolves to "${link.slug}", but no asset is published for that path.`,
+          suggestion: "Add the asset, fix the reference, or register the generated asset from a plugin.",
+          meta: { raw: link.raw, resolvedPath: link.slug }
+        })
+      );
+    }
+  }
+}
+function checkHtmlReferences(entry, publicRoutes, assetPaths, diagnostics2, options) {
+  for (const href of extractAttributes(entry.html, "href")) {
+    if (!isSiteLocalReference(href)) continue;
+    const path = normalizeReferencePath(href, entry.publicLocation.permalink);
+    if (!path || publicRoutes.has(path)) continue;
+    diagnostics2.push(
+      diagnostic(options, {
+        code: "content-integrity:broken-link",
+        slug: entry.slug,
+        filePath: entry.publicLocation.permalink,
+        target: href,
+        message: `Internal link target "${href}" does not match a public route.`,
+        suggestion: "Update the link, create the target content, or register the generated route from a plugin.",
+        meta: { normalizedTarget: path }
+      })
+    );
+  }
+  for (const src of extractAttributes(entry.html, "src")) {
+    if (!isSiteLocalReference(src)) continue;
+    const path = normalizeReferencePath(src, entry.publicLocation.permalink);
+    const assetPath = path?.replace(/^\/+/, "");
+    if (!path || publicRoutes.has(path) || assetPath && assetPaths.has(assetPath))
+      continue;
+    diagnostics2.push(
+      diagnostic(options, {
+        code: "content-integrity:broken-asset",
+        slug: entry.slug,
+        filePath: entry.publicLocation.permalink,
+        target: src,
+        message: `Local asset target "${src}" does not match a published asset or route.`,
+        suggestion: "Add the asset, fix the reference, or register the generated asset from a plugin.",
+        meta: { normalizedTarget: path }
+      })
+    );
+  }
+}
+function checkRedirectTargets(manifest, publicRoutes, diagnostics2, options) {
+  for (const [path, redirect] of manifest.publicRedirects) {
+    const owner = manifest.bySlug.get(redirect.slug);
+    const target = owner ? normalizeRoutePath(owner.publicLocation.permalink) : null;
+    if (target && publicRoutes.has(target)) continue;
+    diagnostics2.push(
+      diagnostic(options, {
+        code: "content-integrity:redirect-target-missing",
+        slug: redirect.slug,
+        target: path,
+        message: `Redirect "${path}" points to content "${redirect.slug}", but its public target is not available.`,
+        suggestion: "Publish the target content or remove the redirect.",
+        meta: { redirect: path, targetSlug: redirect.slug, target }
+      })
+    );
+  }
+}
+function checkRedirectCycles(manifest, diagnostics2, options) {
+  const redirectTargets = /* @__PURE__ */ new Map();
+  const reportedCycles = /* @__PURE__ */ new Set();
+  for (const [path, redirect] of manifest.publicRedirects) {
+    const owner = manifest.bySlug.get(redirect.slug);
+    if (owner)
+      redirectTargets.set(
+        normalizeRoutePath(path),
+        normalizeRoutePath(owner.publicLocation.permalink)
+      );
+  }
+  for (const start of redirectTargets.keys()) {
+    const seen = /* @__PURE__ */ new Map();
+    const chain = [];
+    let current = start;
+    while (current) {
+      const previousIndex = seen.get(current);
+      if (previousIndex !== void 0) {
+        const cycle = [...chain.slice(previousIndex), current];
+        const key = canonicalCycleKey(cycle);
+        if (reportedCycles.has(key)) break;
+        reportedCycles.add(key);
+        diagnostics2.push(
+          diagnostic(options, {
+            code: "content-integrity:redirect-cycle",
+            target: cycle.join(" -> "),
+            message: `Redirect cycle detected: ${cycle.join(" -> ")}.`,
+            suggestion: "Remove or retarget one redirect in the cycle.",
+            meta: { cycle }
+          })
+        );
+        break;
+      }
+      seen.set(current, chain.length);
+      chain.push(current);
+      current = redirectTargets.get(current);
+    }
+  }
+}
+function buildAssetPaths(manifest) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const entry of manifest.entries) {
+    for (const asset of entry.assets) paths.add(asset.path);
+  }
+  for (const asset of manifest.assets ?? [])
+    paths.add(asset.path.replace(/^\/+/, ""));
+  for (const output of manifest.generatedOutputs ?? [])
+    paths.add(output.path.replace(/^\/+/, ""));
+  return paths;
+}
+function extractAttributes(html, attribute) {
+  const pattern = new RegExp(
+    `${attribute}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`,
+    "gi"
+  );
+  const values = [];
+  for (let match = pattern.exec(html); match; match = pattern.exec(html)) {
+    const value = match[1] ?? match[2] ?? match[3];
+    if (value) values.push(value);
+  }
+  return values;
+}
+function isSiteLocalReference(value) {
+  if (!value || value.startsWith("#") || value.startsWith("//")) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) return false;
+  return true;
+}
+function normalizeReferencePath(value, basePath) {
+  const path = value.split(/[?#]/)[0] ?? "";
+  if (!path || path === "/") return path || null;
+  try {
+    return normalizeRoutePath(resolveReferencePath(decodeURI(path), basePath));
+  } catch {
+    return null;
+  }
+}
+function resolveReferencePath(path, basePath) {
+  if (path.startsWith("/")) return path;
+  const baseSegments = basePath.split("/").filter(Boolean);
+  if (!basePath.endsWith("/")) baseSegments.pop();
+  const segments = [...baseSegments, ...path.split("/")];
+  const normalized = [];
+  for (const segment of segments) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      normalized.pop();
+      continue;
+    }
+    normalized.push(segment);
+  }
+  return `/${normalized.join("/")}`;
+}
+function normalizeRoutePath(value) {
+  const path = `/${value.split(/[?#]/)[0]?.split("/").filter(Boolean).join("/") ?? ""}`;
+  return path === "/" ? path : path.replace(/\/$/, "");
+}
+function describeOwner(owner) {
+  return `${owner.kind} "${owner.slug}"`;
+}
+function canonicalCycleKey(cycle) {
+  const closed = cycle.at(0) === cycle.at(-1) ? cycle.slice(0, -1) : [...cycle];
+  const rotations = closed.map((_, index) => [
+    ...closed.slice(index),
+    ...closed.slice(0, index)
+  ]);
+  return rotations.map((rotation) => rotation.join("\0")).sort()[0] ?? "";
+}
+function diagnostic(options, input) {
+  return {
+    pluginName: PLUGIN_NAME2,
+    severity: options.severity?.[input.code] ?? input.severity ?? DEFAULT_SEVERITY2[input.code] ?? "warning",
+    ...input
+  };
+}
+
+// index.ts
+var PLUGIN_NAME3 = "diagnostics";
 async function runDiagnostics(target, options = {}) {
   const config = toAnalyzerConfig(target, options);
   try {
@@ -985,24 +1283,27 @@ async function runDiagnostics(target, options = {}) {
 }
 function diagnostics(options = {}) {
   return definePlugin({
-    name: PLUGIN_NAME2,
+    name: PLUGIN_NAME3,
     options,
     addDiagnostics: async (context) => {
       const config = context.config;
       if (!config) return [];
       try {
-        return await analyzeContent(
-          toAnalyzerConfig(config, options),
-          analyticsCoverageOptions(config, options)
-        );
+        return await analyzeContent(toAnalyzerConfig(config, options), {
+          ...analyticsCoverageOptions(config, options),
+          skipReferenceIntegrity: true
+        });
       } catch (error) {
         return [createInternalError(error)];
       }
     },
+    onManifestCreated: ({ manifest, diagnostics: diagnostics2 }) => {
+      diagnostics2.push(...checkSiteIntegrity(manifest, options));
+    },
     onBuildEnd: ({ manifest }) => {
       if (!options.failOnError) return void 0;
       const errors = manifest.diagnostics.filter(
-        (diagnostic) => diagnostic.pluginName === PLUGIN_NAME2 && diagnostic.severity === "error"
+        (diagnostic2) => diagnostic2.pluginName === PLUGIN_NAME3 && diagnostic2.severity === "error"
       );
       if (errors.length > 0) {
         throw new DiagnosticsFailure(buildReport(errors));
@@ -1027,7 +1328,7 @@ function analyticsCoverageOptions(config, options) {
 function createInternalError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return {
-    pluginName: PLUGIN_NAME2,
+    pluginName: PLUGIN_NAME3,
     code: "internal-error",
     severity: "error",
     message: `content analysis failed: ${message}`

package/dist/src/site_integrity.d.ts

@@ -0,0 +1,5 @@
+import type { ContentManifest, Diagnostic, DiagnosticCode, DiagnosticSeverity } from "@riebeckite/core";
+export type SiteIntegrityOptions = {
+    readonly severity?: Partial<Record<DiagnosticCode, DiagnosticSeverity>>;
+};
+export declare function checkSiteIntegrity(manifest: ContentManifest, options?: SiteIntegrityOptions): Diagnostic[];

package/dist/src/types.d.ts

@@ -8,6 +8,7 @@ export type DiagnosticsOptions = {
     severity?: Partial<Record<DiagnosticCode, DiagnosticSeverity>>;
     exclude?: string[];
     publishStrategy?: "explicit" | "selective";
+    skipReferenceIntegrity?: boolean;
 };
 export type DiagnosticsSummary = {
     total: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-diagnostics",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     "remark-parse": "^11.0.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "@riebeckite/core": "0.0.12"
+    "@riebeckite/core": "0.0.14"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",