Repository navigation
Expand file tree
/
Copy path.lychee.toml
More file actions
154 lines (132 loc) · 6.6 KB
/
Copy path.lychee.toml
File metadata and controls
154 lines (132 loc) · 6.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
# 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. Dormant while
# `offline = true` — nothing is fetched, so nothing is cached, and CI
# carries no `.lycheecache` cache step. Both would come back together.
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",
# Declared shared-block sources (`check-shared-blocks.py`). A block's
# relative links (e.g. `[install.md](install.md#anchor)`) are written to
# resolve from the *host* skill directory the block is propagated into,
# not from `tools/dev/blocks/` itself — the same file is never read
# standalone. The propagated copies are checked normally at their real
# location; checking the source here would just re-report the same
# links as broken from the wrong directory.
"tools/dev/blocks",
]
# 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"