Repository navigation
Ci/link checker - #170
Closed
Mathew2k-hash wants to merge 13 commits into
Closed
Ci/link checker#170Mathew2k-hash wants to merge 13 commits into
Mathew2k-hash wants to merge 13 commits into
Conversation
Covers the full flow for Python 3.11+ backends that want to talk to
Wraith contracts without the TypeScript SDK:
- guides/quickstarts/python.mdx (new)
- pip install stellar-sdk + cryptography only
- wraith_crypto.py inline utility: scan-key derivation via SHA-256
domain separation, X25519 ECDH, ed25519 point addition, view-tag
prefilter, sign_with_scalar (RFC 8032 compatible raw scalar signing)
- Fetch WRAITH_ANNOUNCEMENT events from Soroban RPC (getEvents + XDR decode)
- scan_announcements with view-tag prefilter (~255/256 skip rate)
- Send: createAccount activation + Soroban announcer invocation
- Spend: withdrawal tx signed with raw stealth scalar
- All Python fences marked no-check for the TS snippet gate
- Targets futurenet; notes testnet contract IDs for live testing
- sdk/overview.mdx: cross-link to Python quickstart under Next Steps
- docs.json: Quickstarts nav group added above Guides in the Guides tab
Add scripts/check-exports.ts — a CI script that: - Walks all .mdx files and extracts every named import from @wraith-protocol/sdk* - Generates two typed fixtures (ESM .mts + CJS .cts) covering all 5 entry points (@wraith-protocol/sdk, /chains/evm, /chains/stellar, /chains/solana, /chains/ckb) - Type-checks each fixture with tsc (skipLibCheck: false) so missing exports in the package .d.ts surface as hard errors - Executes each fixture via tsx to catch symbols that are typed but undefined at runtime - Exits 1 with a clear diff when docs and package exports diverge Wire up: - package.json: add check:exports script, extend test to include it - .github/workflows/snippets.yml: add check-exports job (blocks merge on failure) Closes #<issue>
…ages
Two bugs surfaced from the first CI run:
1. Inline type imports — import { foo, type Bar } puts the literal string
'type Bar' into the brace list. Strip the leading 'type ' keyword from
each token after splitting on commas so symbols are extracted cleanly.
2. @wraith-protocol/sdk-react is documented in react-native.mdx but is not
a dependency of this repo. Rather than hard-failing, pre-flight each
specifier against node_modules and skip (with a warning) any whose
package is not installed.
Also expand TYPE_ONLY_SYMBOLS to cover all interface/type-alias exports
seen in the actual scan output (StealthMetaAddress, FederationRecord,
FederationError, FederationErrorCode, FederationCache, and all root-sdk
types such as WraithConfig, ChatResponse, etc.).
…tifier errors The previous fixture put all named imports from every entry point into a single file scope. Symbols that appear in multiple chain modules (generateStealthAddress, SCHEME_ID, deriveStealthKeys, etc.) caused TS2300 duplicate identifier errors, burying the genuine missing-export errors (TS2305) in noise. Fix: switch to namespace imports (import * as Ns0 from '...') for value exports and aliased import type for type-only exports. Each specifier gets its own namespace so there are zero name collisions regardless of how many modules share a symbol name. Property access on the namespace (Ns0.Wraith, Ns1.generateStealthAddress) gives tsc the same type information, and missing exports now surface cleanly as 'Property X does not exist on type Ns...' errors. CJS fixture updated the same way: one equire() call per specifier, stored in its own const alias.
…v1.4.5 Several documented symbols are not yet in the installed package (v1.4.5): - Root: fetchAnnouncementsStream, RetentionExceededError, StreamDisruptedError, BackpressureOverflowError, ProviderTimeoutError, InvalidViewTagError, StealthClient, StellarStealthSigner - Stellar: resolveStellarFederation, createAnnounceOperation, deriveStealthPrivateKey Rather than hard-failing (docs are intentionally ahead of release) or suppressing silently, introduce a KNOWN_MISSING map. Symbols in it are excluded from the generated fixtures so tsc and tsx skip them, but they are printed as warnings so the drift is visible in CI output. Remove a symbol from KNOWN_MISSING once it ships — the check will enforce its presence automatically from that point on.
…JS runtime Two remaining failures: 1. ESM tsc: streaming and federation *types* (AnnouncementsStreamOptions, AnnouncementStream, Announcement, RetentionConfig, ViewTagFilter, StreamCacheOptions, BackpressureOptions, StreamError, FederationRecord, FederationCache, FederationError, FederationErrorCode) are not in the installed package .d.ts. Add them all to KNOWN_MISSING. 2. CJS tsx: @solana/web3.js -> rpc-websockets ships a broken .cjs that crashes with ERR_VM_MODULE_LINK_FAILURE when require()d inside a Node ESM module job (Node 22). Add CJS_RUNTIME_SKIP set; for affected specifiers emit a dummy cast instead of require() so tsc still validates property names without crashing at runtime.
- Add scripts/check-links.mjs: crawls all .mdx/.md files and checks internal links (file existence + anchor fragments), local assets, and external HTTP URLs (HEAD with GET fallback, 1 retry, 10 concurrent) - Add link-exceptions.yaml: structured allow-list for URLs that are known to block CI crawlers (Twitter/X, LinkedIn); each entry records url, reason, owner, and date added - Add .github/workflows/link-check.yml: runs check:links on every PR; uploads link-check-report.json as a 14-day artifact on failure - Add check:links script to package.json; mint:broken-links preserved for local Mintlify CLI use Closes #<issue-number>
|
@Mathew2k-hash Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
added 4 commits
September 25, 2026 11:57
fileExists was returning a directory path when no extension-based candidate matched, causing readFile to throw EISDIR. Fixed by checking stat().isFile() before accepting any candidate, and moving the bare path to last so extension variants are tried first.
…ceptions Three bugs fixed: - headingToAnchor: & was stripped to nothing producing double-hyphens (e.g. 'Monitoring & Alerting' → 'monitoring--alerting' instead of 'monitoring-alerting'). Now maps & and & to a hyphen then collapses consecutive hyphens, matching GFM/Mintlify behaviour. - resolveInternal: query strings (?step=scan) were included in the file path, causing false 'File not found' errors for playground links. Now strips everything after ? before resolving. - isInternalExcepted: new helper checks internal paths against 'internal:' prefixed entries in link-exceptions.yaml so known stub pages can be suppressed without disabling the whole checker. link-exceptions.yaml updated with: - Placeholder/example external URLs (pay.wraith.dev, usewraith.xyz/*) - Crawler-blocking external sites (stellarbeat.io, phoenix-hub.org, github.com/stellar/go tree views, developers.stellar.org) - Known stub internal pages (/reference/stellar-event-schemas, /sdk/stellar-react-hooks, /reference/error-codes, /guides/my-guide)
Checker fixes:
- headingToAnchor: recognise Mintlify explicit id syntax {#custom-id}
so headings with an id override use the short form the link expects
Stale anchor fixes in source files:
- reference/auditor-guide.mdx: add {#severity-matrix} id to
'## 3. Severity matrix' (referenced by monitoring-and-on-call.mdx);
update self-links #submitting-a-report → wraith-protocol#7-submitting-a-report and
#poc-repository-template → wraith-protocol#5-poc-repository-template
- sdk/chains/stellar.mdx: add {#signstellartransaction} id to the
signStellarTransaction heading (referenced by phoenix.mdx, soroswap.mdx)
- guides/integrations/soroswap.mdx: update link to use the explicit id
#signstellartransaction now that the heading carries one
- guides/stellar-mainnet-deployment.mdx: fix #monitoring--alerting →
#monitoring-and-alerting (heading is 'Monitoring and Alerting')
- guides/stellar/stellar-liquidity-pool-swap.mdx: fix #swap--announce →
#swap-announce (heading is 'Swap + Announce', + strips to nothing)
link-exceptions.yaml:
- Add internal stubs for monitoring-and-on-call, phoenix, my-guide
…ining stale anchors
Checker fix:
- isInternalExcepted now also applies to anchor checks, not just missing
file checks. Previously if an excepted file existed on the CI checkout
(e.g. error-codes.mdx present in the target branch), the file would be
found, its anchors checked, and failures reported even though the file
is in the exception list. Now both the 'file not found' and the
'anchor not found' paths bail out when the target file is excepted.
Stale anchor fixes:
- guides/stellar/stellar-quickstart.mdx: add {#send-a-stealth-payment}
to '## 7. Send a Stealth Payment' and {#withdraw-to-your-wallet} to
'## 9. Withdraw to Your Wallet' so short anchor links resolve
- guides/stellar-troubleshooting.mdx: add {wraith-protocol#17-hostError-contract-trapped}
and {wraith-protocol#18-op_no_trust--missing-trustline} explicit ids to match the
anchors used in error-codes.mdx
- guides/integrations/soroswap.mdx: revert long auto-slug back to
#signstellartransaction now that the heading carries that explicit id
link-exceptions.yaml:
- Update error-codes entry comment to clarify file exists on target branch
Contributor
|
This branch bundles the link checker with the Python quickstart and SDK export checker work. Please rebase onto develop and keep only the link-check changes so this can be reviewed and merged independently. |
1 similar comment
Contributor
|
This branch bundles the link checker with the Python quickstart and SDK export checker work. Please rebase onto develop and keep only the link-check changes so this can be reviewed and merged independently. |
Contributor
|
Wave 9 has ended, so this PR is being closed without merging. Thank you for the contribution. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix broken links shipping to production by adding a CI link checker
Problem
mint:broken-links existed in package.json but was never wired into CI, so pull
requests could merge with broken internal links, missing anchor fragments,
unresolved local assets, or dead external URLs.
Changes
scripts/check-links.mjs
Crawls every .mdx and .md file in the repo and checks:
/index.mdx variants automatically)
the same GFM slug algorithm Mintlify uses
retry, 10 concurrent requests, 10 s timeout
link-exceptions.yaml
Explicit allow-list for URLs that are structurally valid but block CI crawlers (
e.g. Twitter/X, LinkedIn). Each entry requires a url, reason, owner, and added
date so exceptions stay auditable and don't accumulate silently.
.github/workflows/link-check.yml
Runs check:links on every PR. On failure, uploads link-check-report.json as a
GitHub Actions artifact (kept 14 days) so the exact broken links are one click
away in the Actions summary.
package.json
Adds check:links script. The existing mint:broken-links script is kept for local
Mintlify CLI use.
Testing
Run locally with:
bash
pnpm run check:links
Pass on a clean repo, exits 1 with a grouped console output and JSON report when
broken links are found.
Notes
ins (fs, fetch, path, readline)
rather than editing the script
closes [Wave 9] Run broken-link checks as a required docs job #154