lychee.toml

# lychee ruleset — repo-agnostic link-checking config.
# The offline CI lane runs with --offline (external URLs skipped); the online
# advisory lane reuses this file with the network enabled.
# Ref: https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml

# Verify #fragment/anchor targets resolve, not just the file path ("full"
# checks both anchor and text fragments).
include_fragments = "full"

# A 429 is the SERVER rate-limiting the checker, never evidence the link is
# dead — and it lands on whichever host the shared CI runner IP happens to be
# throttled against that run, so it names a different healthy URL each time. The
# range restates lychee's own documented default (`--accept` help:
# `[default: 100..=103,200..=299]`, read from the pinned binary rather than
# recalled) so adding 429 widens the accepted set instead of silently narrowing
# it — `accept` REPLACES the default, it does not extend it.
#
# Deliberately NOT an exclude entry per rate-limited host: excluding a live URL
# to silence a transient throttle stops checking a link that is fine, and the
# next run just throttles a different one.
accept = ["100..=103", "200..=299", "429"]

# Build/dependency trees — not authored content. Values are regex (single-quoted
# TOML literals, so backslashes are not double-escaped).
exclude_path = [
  'node_modules',
  '\.venv',
  '(^|/)bin/',
  '(^|/)obj/',
]

# URL excludes for the online lane (the offline lane skips URLs entirely):
# exact bot-blocked URLs, auth-walled private repos, loopback, placeholders, and
# hosts the checker cannot complete a TLS handshake against. Every entry is a
# CHECKER-side limitation on a link verified to be alive — never a dead link
# silenced. Each one below records the verification that earned it, so a future
# reader can re-test rather than trust the list.
exclude = [
  # ACM blocks automated clients outright: both URLs answer 403 even with a full
  # browser User-Agent (verified 2026-07-30), so no header tuning reaches them.
  # A DOI link is also the most stable citation form there is — the failure is
  # entirely the checker being refused at the door.
  '^https?://dl\.acm\.org/doi/10\.1145/3611643\.3613871/?([?#].*)?$',
  '^https?://queue\.acm\.org/detail\.cfm\?id=3454124$',
  # ISO blocks automated clients outright: 403 to the checker (verified
  # 2026-08-11), so the failure is entirely the checker being refused at the
  # door — the cited standard page is the stable canonical link.
  '^https?://www\.iso\.org/standard/78907\.html/?([?#].*)?$',
  # 403 to the checker, 200 with a browser User-Agent (verified 2026-07-30) —
  # the documented bot-block case this list already exists for.
  '^https?://docs\.genius\.com/?([?#].*)?$',
  # Reported by the checker as "SSL certificate not trusted". The chain verifies
  # locally — `openssl s_client` returns `Verify return code: 0 (ok)` against a
  # Cloudflare TLS Issuing ECC CA intermediate, and curl fetches it 200 under
  # strict verification (both 2026-07-30) — so this is the runner or checker
  # trust store failing to complete an ECC chain, not an untrustworthy host.
  # Re-test before removing; a genuinely bad chain would fail locally too.
  '^https?://www\.ntia\.gov/files/ntia/publications/sbom_minimum_elements_report\.pdf$',
  '^https?://(www\.)?x\.com/',
  '^https?://twitter\.com/',
  '^https?://(www\.)?linkedin\.com/',
  '^https?://bsky\.app/',
  '^https?://(www\.)?medium\.com/@ziobrando/the-rise-and-fall-of-the-dungeon-master-c2d511eed12f/?([?#].*)?$',
  '^https?://(www\.)?medium\.com/fortmatic/postmortem-service-disruption-from-expired-ssl-certificate-a993a59272a0/?([?#].*)?$',
  '^https?://dev\.mysql\.com/doc/refman/8\.4/en/innodb-transaction-isolation-levels\.html/?([?#].*)?$',
  '^https?://help\.miro\.com/hc/en-us/articles/31624028247058/?([?#].*)?$',
  '^https?://isdown\.app/status/anthropic/?([?#].*)?$',
  '^https?://(www\.)?npmjs\.com/package/(firecrawl-cli|@mirohq/miro-api)/?([?#].*)?$',
  '^https?://www\.w3\.org/International/wiki/WorkingWithTimeZones/?([?#].*)?$',
  '^https?://localhost',
  '^https?://127\.0\.0\.1',
  '^https?://example\.(com|org)',
  # PRIVATE GitHub repos: valid links for authenticated collaborators, but the
  # online lane's credential is the calling repo's GITHUB_TOKEN (or nothing
  # locally), which cannot read any other private repo, so GitHub answers 404.
  # Listed per repo, not per owner, so links to public siblings stay checked.
  # Keep in sync with actual visibility: add newly created private repos here;
  # drop an entry when its repo goes public. The optional \.git arm covers
  # HTTPS clone URLs: the dot after the repo name would otherwise miss the
  # [/#?] boundary.
  '^https?://github\.com/melodic-software/(dotfiles|github-iac|itinerary-planner|knowledge-corpus|medley-archive|medley|melodic-main-archive|provisioning|songwriting)(\.git)?([/#?]|$)',
  '^https?://raw\.githubusercontent\.com/melodic-software/(dotfiles|github-iac|itinerary-planner|knowledge-corpus|medley-archive|medley|melodic-main-archive|provisioning|songwriting)/',
]