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.

日本語

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)

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
• buildEnd — with failOnError: true, throws DiagnosticsFailure when error-level diagnostics exist

Checks

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. As a result, orphan-note and unused-asset are reported only by runDiagnostics() and the standalone CLI; during a build they are omitted because link relationships come from the manifest.

Options

CLI

riebeckite-diagnostics --config riebeckite.config.ts
riebeckite-diagnostics --content ./content --report-orphans

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

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