.lychee.toml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

# Lychee link checker config for apache/magpie.
#
# Runs in OFFLINE mode (see `offline` below): validates only *local*
# references in markdown / rst / .md.j2 files:
#   * cross-file file existence — `[text](other.md)`
#   * cross-file fragments     — `[text](other.md#anchor)`
#   * same-file fragments      — `[text](#anchor)`
# External `http(s)://` URLs are intentionally NOT fetched — see the
# `offline` note below for why. Remote-link liveness is not checked
# anywhere; the link check exists to keep in-repo references intact.
#
# Run via prek (locally and in CI) as the `lychee` hook in
# `.pre-commit-config.yaml` — prek installs lychee itself, so no local
# lychee install is needed:
#   prek run lychee --all-files
#
# (Or directly, if you have lychee >= 0.24 installed:
#   lychee --config .lychee.toml .)

# Check anchor fragments, not just file paths — `#section` checks
# the GitHub-style slug exists in the linked file. The enum-string
# form (`"anchor-only"`) is the lychee v0.24+ schema; the link check
# now runs as the `lychee` prek hook (see `.pre-commit-config.yaml`)
# against a directly-installed lychee >= 0.24, not the old pinned
# `lychee-action`. The v0.23.x boolean form (`true`) no longer parses.
include_fragments = "anchor-only"

# Offline mode — check only local file/anchor references, never fetch
# remote URLs. Two reasons:
#   1. Scope: this hook's job is in-repo reference integrity, not
#      external-link liveness (which is flaky and rate-limited — note
#      the long `exclude` list of ASF infra hosts below that existed
#      purely to tame online checking).
#   2. Sandbox compatibility: the cargo/brew lychee links macOS
#      SecureTransport (`native-tls`), whose TLS handshake fails
#      through the secure-agent sandbox's CONNECT proxy on macOS 26
#      (`OSStatus -26276`) even though certs are valid. Offline mode
#      makes no network calls, so the hook passes cleanly in-sandbox.
# The network-related settings below (timeout / retry / accept /
# exclude / cache) are dormant while offline = true, kept for
# reference / a future opt-in online check.
offline = true

# Concurrency cap — kept moderate to avoid being rate-limited by GitHub.
max_concurrency = 14

# Per-request timeout. ASF infra and GitHub raw-content endpoints
# occasionally take 10+ seconds during peak.
timeout = 30

# Retry transient errors a few times before failing the run.
retry_wait_time = 2
max_retries = 3

# Cache successful results for 7 days. Mirrors the framework-wide
# 7-day `[tool.uv] exclude-newer` cooldown convention. CI restores
# this cache between runs to keep the link check fast.
cache = true
max_cache_age = "7d"

# Treat 4xx and 5xx as failures (default), but accept the redirects.
accept = [200, 206, 301, 302, 304, 308, 401, 403]

# 401/403 accepted because some authenticated endpoints (private ASF
# trackers, GitHub API rate-limited responses) return them deterministically
# on unauthenticated CI but are still valid URLs.

# Skip-list — endpoints that are private to ASF infra, rate-limited
# more aggressively than CI tolerates, or known to require headers
# the checker cannot supply.
exclude = [
  # ASF mailing-list archives — rate-limit on burst, not stable in CI.
  '^https://lists\.apache\.org/.*',

  # ASF Vulnogram CVE tool — auth-gated, returns 200 only when logged in.
  '^https://cveprocess\.apache\.org/.*',

  # cve.org record pages 404 until the record is published; many of the
  # links in skill examples reference future / hypothetical CVE IDs.
  '^https://cve\.org/CVERecord\?id=CVE-.*',
  '^https://www\.cve\.org/CVERecord\?id=CVE-.*',
  '^https://cveawg\.mitre\.org/api/cve/CVE-.*',

  # cve.mitre.org legacy (often slow + unreliable).
  '^https://cve\.mitre\.org/.*',

  # Ponymail thread IDs in canned-response examples — they reference
  # synthetic or future thread URLs that do not exist yet.
  '^https://lists\.apache\.org/thread/.*',

  # Placeholder paths used by the framework convention. `<project-config>`,
  # `<tracker>`, `<upstream>` etc. are literal placeholder tokens that
  # are substituted at runtime by the adopting project; URL-encoded
  # they appear as `%3C...%3E`. Lychee tries to resolve them as real
  # file paths and fails. See AGENTS.md#placeholder-convention-used-in-skill-files.
  '%3C[A-Za-z0-9_-]+%3E',

  # ALL_CAPS substitution tokens (e.g., FRAMEWORK_README_URL,
  # SOURCE_TAB_URL, JSON_ANCHOR_URL) used in the release-manager
  # comment templates. Each is replaced at runtime by the rendering
  # skill with the actual URL.
  '/[A-Z][A-Z0-9_]+_URL(?:#|$)',
  '/[A-Z][A-Z0-9_]+_URL/',
  '/[A-Z][A-Z0-9_]+_URL$',

]

# File patterns to skip entirely — the agent-isolation pinned-versions
# manifest has bare URLs that are intentionally pinned to specific tags
# the checker should not chase.
exclude_path = [
  "tools/agent-isolation/pinned-versions.toml",
  "uv.lock",
  "tools/*/uv.lock",
  ".git",

  # Eval fixture files contain intentionally fake URLs (placeholder GitHub
  # repos, private IPs, synthetic issue numbers) and are not documentation.
  # Link-checking them produces noise with no signal.
  "tools/skill-evals/evals",
]

# Treat unresolvable hostnames the same as failures, no silent passes.
no_progress = true

# Report-style output — one line per failing link makes CI logs grep-friendly.
format = "compact"