lychee.toml

# lychee.toml
# Declarative config consumed by .github/workflows/lychee.yml.
# Lychee scans docs/**/*.md (source markdown) for external URL liveness.
# Internal /progress-platform/* paths are VitePress build artifacts, validated
# at build time; lychee can't resolve them filesystem-side without running into
# --root-dir / --base interaction bugs, so they're excluded here.

# Exclude localhost variants so README dev-stack samples don't fail CI.
# Also exclude self-referential progresslabit.github.io paths — VitePress validates
# its own internal links at build time; lychee gets confused by the auto-generated
# absolute-path chunks/assets in dist/ HTML.
exclude = [
  "^https?://(?:localhost|127\\.0\\.0\\.1|progress\\.localhost)",
  "^https?://progresslabit\\.github\\.io/",
  # Root-relative VitePress URL-contract paths — VitePress's own build validates
  # these (it fails on dead internal links). Lychee can't reliably resolve
  # `/api/` → `docs/api/index.md` because directory-to-index inference depends on
  # serving conventions, not filesystem lookup.
  "^/(?:|api|events|cli|users|admins)(?:/|$)",
  # When lychee resolves root-relative links against the source tree it produces
  # file:// URLs without the .md suffix (cleanUrls mode). VitePress validates
  # these at build time; lychee should not.
  "^file://.*/docs/(api|events|cli|users|admins)(/|$)",
  # Cross-workstream ADR references (sparkplug-demo decisions). These live on
  # GSD until the sparkplug-demo workstream ships its decisions/ to DEV. Once
  # that lands, remove this exclusion.
  "^https?://github\\.com/ProgressLabIT/progress-platform/blob/DEV/\\.planning/workstreams/sparkplug-demo/decisions/",
  # VitePress public assets (served from docs/public/) — root-relative links
  # to /openapi.json, /sitemap.xml, /robots.txt, etc. resolve at runtime via
  # the public/ directory; lychee sees them as docs/openapi.json (missing).
  "^/(?:openapi\\.json|sitemap\\.xml|robots\\.txt)$",
  "^file://.*/docs/(?:openapi\\.json|sitemap\\.xml|robots\\.txt)$",
]

# Note: docs/.vitepress/templates is excluded via --exclude-path in
# .github/workflows/lychee.yml (lychee.toml has no exclude_path key).
# Templates carry literal {placeholder} link targets and aren't user-facing
# pages (excluded from VitePress build via srcExclude in config.ts).

# Accept 403 from sites that bot-block lychee's UA (gitlab.com is the prime offender —
# the repo URL works fine in a browser but returns 403 to scripted user-agents).
accept = ["200..=299", "403"]

# Tolerate private-network references (RFC 1918 etc.) without failing CI.
exclude_all_private = true

# Cache to reduce upstream load on rerun.
cache = true
max_cache_age = "2d"

# Retry tuning per init context — soak transient 5xx/rate-limits without false-failing.
max_retries = 2
retry_wait_time = 2