From 364e182e01dcf820ee6094fcb6c16fbbd8087e17 Mon Sep 17 00:00:00 2001 From: midenotch <125803339+midenotch@users.noreply.github.com> Date: Thu, 22 Oct 2026 11:13:51 +0100 Subject: [PATCH 1/2] feat: enforce Rust quickstart guide/crate extraction check --- .github/workflows/snippets.yml | 11 +- docs/CONTRIBUTING.md | 64 ++- guides/quickstarts/rust.mdx | 137 ++++-- package.json | 115 ++--- scripts/check-rust-quickstart.ts | 566 ++++++++++++++++++++++++ scripts/check-snippets-extended.ts | 21 +- snippets/rust-quickstart/src/keypair.rs | 3 + snippets/rust-quickstart/src/main.rs | 41 +- snippets/rust-quickstart/src/stealth.rs | 2 + 9 files changed, 806 insertions(+), 154 deletions(-) create mode 100644 scripts/check-rust-quickstart.ts diff --git a/.github/workflows/snippets.yml b/.github/workflows/snippets.yml index cc7e8c1..ff6d8ed 100644 --- a/.github/workflows/snippets.yml +++ b/.github/workflows/snippets.yml @@ -135,19 +135,26 @@ jobs: python3 --version bash --version | head -1 + # Runs both the extended fence checks and the Rust quickstart + # guide/crate extraction check (check:snippets-extended chains both). - name: Check extended snippets (Rust / Python / shell / JSON / TOML / YAML) run: pnpm run check:snippets-extended # ----------------------------------------------------------------------- # Compile the Rust quickstart crate — this is the ground-truth check # that all documented crypto code actually compiles and its tests pass. - # The "network" feature (reqwest / tokio / soroban-client) is intentionally - # excluded here; it is only needed for live RPC calls, not for type-checking. + # The second pass enables the "network" feature so the scan / send + # modules (reqwest / tokio) are type-checked too; it is compile-only, + # no RPC calls are made. # ----------------------------------------------------------------------- - name: Compile Rust quickstart crate working-directory: snippets/rust-quickstart run: cargo build --features testnet 2>&1 + - name: Type-check Rust quickstart network modules + working-directory: snippets/rust-quickstart + run: cargo check --features testnet,network 2>&1 + - name: Check Rust quickstart formatting working-directory: snippets/rust-quickstart run: cargo fmt --check diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5c61ef3..f70d4c2 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -44,28 +44,56 @@ request must hit a route documented on the page, and each fixture is compiled wi When an example calls an endpoint, add one fixture per request it makes. `no-check` is not allowed on that page. -### Python quickstart +### Rust quickstart crate -`guides/quickstarts/python.mdx` runs end to end in CI, offline, as part of -`check:snippets-extended`: +`guides/quickstarts/rust.mdx` is backed by a real crate, +`snippets/rust-quickstart`, that CI builds with `cargo build` / `cargo test` / +`cargo fmt --check`. Fences in that guide that belong to the crate are tagged: -```bash -npm run check:python-quickstart +````mdx +```rust crate +// src/stealth.rs +... ``` +```` -`scripts/python-quickstart/run_quickstart.py` builds `wraith_crypto.py` from the -fence that starts with `# wraith_crypto.py` (plus any `# Add to wraith_crypto.py` -fences), then runs every other Python fence in page order in one session. The -Soroban RPC, Horizon, and Soroban transaction calls go to local fakes that serve -recorded announcer events and verify each transaction's signatures. Results are -compared with `scripts/python-quickstart/vectors.json`, which -`npm run generate:python-quickstart-vectors` computes from the pinned SDK. - -Dependencies are pinned in `scripts/python-quickstart/requirements.txt`. The -`--bootstrap` flag creates a virtualenv with those pins under -`node_modules/.cache`. Every Python fence in the guide must run. A fence that -cannot run needs both words after the language, `python Pseudocode no-check`, so -readers see it is pseudocode. +- `crate` fences are **not** compiled standalone by + `check:snippets-extended` (they reference crate-internal modules). Instead, + `scripts/check-rust-quickstart.ts` extracts every `// src/` fence, + concatenates continuation fences, and byte-compares the result against + `snippets/rust-quickstart/src/.rs` (after stripping crate-only + regions). If the crate and the guide drift apart, CI fails. +- The first fence for a file keeps its `// src/` marker line. Later + fences start with `// src/ (continued)`; that line is dropped when the + fences are concatenated. +- Code that exists only in the crate (unit tests, test fixtures) is wrapped in + markers and hidden from the guide: + + ```rust + // crate-only-begin: reason, not shown in the guide + #[cfg(test)] + mod tests { /* ... */ } + // crate-only-end + ``` + +- Fences that intentionally diverge from the crate (aspirational APIs, + self-contained `main` variants) use `no-check` plus a marker line and must be + listed with a reason in the `EXEMPT` map of + `scripts/check-rust-quickstart.ts`. The script also fails on stale exemptions + and on crate sources that no fence covers, so every `src/*.rs` file is + either shown in the guide or explicitly exempted. +- `Cargo.toml` is compared structurally: feature names, default features, and + dependency names (including optional flags) must match. Version strings may + differ so the guide can pin looser ranges. + +After editing either side, regenerate or fix until both pass: + +```bash +npm run check:rust-quickstart +# print the crate source (crate-only regions stripped) for a file: +npx tsx scripts/check-rust-quickstart.ts --emit stealth.rs +cd snippets/rust-quickstart && cargo build --features testnet && cargo test && cargo fmt --check +``` ## Navigation coverage diff --git a/guides/quickstarts/rust.mdx b/guides/quickstarts/rust.mdx index 132ff77..1db1ac0 100644 --- a/guides/quickstarts/rust.mdx +++ b/guides/quickstarts/rust.mdx @@ -21,6 +21,8 @@ A Rust quickstart for developers building backends, indexers, relayers, or CLIs There is no first-class `@wraith-protocol/sdk` Rust crate yet. This guide **reimplements the stealth spec directly** using audited crates (`ed25519-dalek`, `x25519-dalek`, `curve25519-dalek`, `stellar-strkey`, `stellar-xdr`, `soroban-client`). See [Where the Rust story is thinner](#where-the-rust-story-is-thinner) for what is planned. +Every `src/` file below is compiled in CI as part of the `snippets/rust-quickstart` crate — the code you copy is the code that is built and tested on each PR. + ## Prerequisites - Rust toolchain (stable) @@ -32,7 +34,7 @@ There is no first-class `@wraith-protocol/sdk` Rust crate yet. This guide **reim Feature flags select the network at compile time. `testnet` is the default and is where the Wraith contracts are live. `futurenet` and `mainnet` flip the RPC URL, passphrase, and Friendbot availability — the example compiles and runs on all three. -```toml no-check +```toml # Cargo.toml [package] name = "wraith-rust-quickstart" @@ -67,7 +69,7 @@ tokio = { version = "1", features = ["full"], optional = true } opt-level = 3 ``` -```rust +```rust crate // src/network.rs // Compile-time network selection. Flip with --features futurenet / --features mainnet. @@ -108,10 +110,10 @@ pub const STEALTH_SIGNING_MESSAGE: &str = Decode the `S...` secret seed with `stellar-strkey`, then build an `ed25519-dalek` signing key. Keep the seed in memory only — never log it. -```rust +```rust crate // src/keypair.rs use anyhow::Result; -use ed25519_dalek::{Signer, SigningKey}; +use ed25519_dalek::SigningKey; pub struct Account { pub seed: [u8; 32], @@ -120,32 +122,69 @@ pub struct Account { } pub fn load_keypair(secret: &str) -> Result { - // `S...` -> 32-byte ed25519 seed via stellar-strkey + // `S...` -> 32-byte ed25519 seed via stellar-strkey ed25519::PrivateKey let private = stellar_strkey::ed25519::PrivateKey::from_string(secret) .map_err(|e| anyhow::anyhow!("invalid stellar secret: {e:?}"))?; let seed: [u8; 32] = private.0; let signing_key = SigningKey::from_bytes(&seed); let address = stellar_strkey::ed25519::PublicKey(signing_key.verifying_key().to_bytes()).to_string(); - Ok(Account { seed, signing_key, address }) + Ok(Account { + seed, + signing_key, + address, + }) } +``` + +The binary entry point loads the key from `STELLAR_SECRET`, signs the domain-separated message, and prints the derived stealth keys. With `--features network` the same binary becomes a scanner instead (see Step 3). + +```rust crate +// src/main.rs +// +// Entry point for `cargo run`. When the "network" feature is active the binary +// scans the Soroban testnet for stealth payments addressed to the keypair +// supplied via STELLAR_SECRET. Without "network" it just derives keys and +// prints them — useful for local testing without an RPC call. + +pub mod keypair; +pub mod network; +pub mod scan; +pub mod send; +pub mod stealth; + +#[cfg(not(feature = "network"))] +fn main() -> anyhow::Result<()> { + use ed25519_dalek::Signer; + use network::STEALTH_SIGNING_MESSAGE; -#[tokio::main] -async fn main() -> Result<()> { let secret = std::env::var("STELLAR_SECRET")?; - let account = load_keypair(&secret)?; - println!("loaded account {}", account.address); + let account = keypair::load_keypair(&secret)?; + println!("loaded account: {}", account.address); // The 64-byte signature drives stealth key derivation. - let sig: [u8; 64] = account.signing_key.sign(STEALTH_SIGNING_MESSAGE.as_bytes()).to_bytes(); - println!("derivation signature (hex): {}", hex::encode(sig)); + let sig: [u8; 64] = account + .signing_key + .sign(STEALTH_SIGNING_MESSAGE.as_bytes()) + .to_bytes(); + let keys = stealth::derive_stealth_keys(&sig); + println!("spending pub : {}", hex::encode(keys.spending_pub)); + println!("viewing pub : {}", hex::encode(keys.viewing_pub)); Ok(()) } + +#[cfg(feature = "network")] +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let secret = std::env::var("STELLAR_SECRET")?; + scan::run_scan(&secret).await +} ``` Run it: ```bash +export STELLAR_SECRET=S... # your funded testnet account cargo run --features testnet # or: cargo run --features futurenet ``` @@ -154,18 +193,24 @@ cargo run --features testnet This is the core of the Rust path: a self-contained reimplementation of the Wraith Stellar stealth spec (ed25519 + X25519, domain-separated SHA-256). It mirrors `deriveStealthKeys` / `generateStealthAddress` / `scanAnnouncements` from `@wraith-protocol/sdk/chains/stellar`. -```rust +```rust crate // src/stealth.rs -use anyhow::Result; +// +// Self-contained reimplementation of the Wraith Stellar stealth spec. +// Mirrors deriveStealthKeys / generateStealthAddress / scanAnnouncements +// from @wraith-protocol/sdk/chains/stellar. +// +// Cryptographic primitives: ed25519 + X25519, domain-separated SHA-256. + use curve25519_dalek::{ - constants::ED25519_BASEPOINT_POINT, - edwards::CompressedEdwardsY, - EdwardsPoint, Scalar, + constants::ED25519_BASEPOINT_POINT, edwards::CompressedEdwardsY, EdwardsPoint, Scalar, }; use ed25519_dalek::SigningKey; use sha2::{Digest, Sha256, Sha512}; use x25519_dalek::{PublicKey as X25519PublicKey, StaticSecret}; +// ── Public types ────────────────────────────────────────────────────────────── + pub struct StealthKeys { pub spending_seed: [u8; 32], pub viewing_seed: [u8; 32], @@ -187,9 +232,9 @@ pub struct MatchedStealth { } ``` -```rust +```rust crate // src/stealth.rs (continued) -// --- domain-separated derivation (mirrors the TS spec) --- +// ── Domain-separated derivation (mirrors the TS spec) ──────────────────────── fn derive_seed(tag: &str, sig: &[u8; 64]) -> [u8; 32] { let mut h = Sha256::new(); @@ -201,7 +246,7 @@ fn derive_seed(tag: &str, sig: &[u8; 64]) -> [u8; 32] { b } -// ed25519 private scalar: SHA-512(seed)[0..32], clamped. +/// ed25519 private scalar: SHA-512(seed)[0..32], clamped (RFC 8032 §5.1.5). fn seed_to_scalar(seed: &[u8; 32]) -> Scalar { let h = Sha512::digest(seed); let mut a = [0u8; 32]; @@ -230,18 +275,20 @@ pub fn derive_stealth_keys(sig: &[u8; 64]) -> StealthKeys { } ``` -```rust +```rust crate // src/stealth.rs (continued) -// --- X25519 ECDH between ed25519 keys (Montgomery form) --- +// ── X25519 ECDH between ed25519 keys (Montgomery form) ─────────────────────── fn edwards_pub_to_mont_pub(pub_bytes: &[u8; 32]) -> [u8; 32] { - let compressed = CompressedEdwardsY::from_slice(pub_bytes); + let compressed = CompressedEdwardsY::from_slice(pub_bytes) + .expect("32-byte slice always fits CompressedEdwardsY"); let point = compressed.decompress().expect("valid ed25519 public key"); point.to_montgomery().to_bytes() } fn x25519_shared(priv_seed: &[u8; 32], peer_pub: &[u8; 32]) -> [u8; 32] { - let a = seed_to_scalar(priv_seed).to_bytes(); // clamped scalar == x25519 private + // The clamped ed25519 scalar bytes are a valid x25519 private key. + let a = seed_to_scalar(priv_seed).to_bytes(); let secret = StaticSecret::from(a); let peer = X25519PublicKey::from(edwards_pub_to_mont_pub(peer_pub)); secret.diffie_hellman(&peer).to_bytes() @@ -262,26 +309,32 @@ pub fn compute_view_tag(shared: &[u8; 32]) -> u8 { } ``` -```rust +```rust crate // src/stealth.rs (continued) -// --- generate a one-time stealth address for a recipient --- +// ── Generate a one-time stealth address for a recipient ─────────────────────── +// +// Callers supply the recipient's viewing *seed* (not just the public key) +// because ECDH requires the private scalar. After calling derive_stealth_keys +// the viewing_seed is available directly on StealthKeys. pub fn generate_stealth_address( spending_pub: &[u8; 32], - viewing_seed: &[u8; 32], // the recipient's viewing seed (not just the public key) + viewing_seed: &[u8; 32], ephemeral_seed: &[u8; 32], ) -> GeneratedStealth { - let eph_pub = SigningKey::from_bytes(ephemeral_seed).verifying_key().to_bytes(); + let eph_pub = SigningKey::from_bytes(ephemeral_seed) + .verifying_key() + .to_bytes(); // shared = X25519(viewing_priv, ephemeral_pub) let shared = x25519_shared(viewing_seed, &eph_pub); let view_tag = compute_view_tag(&shared); let h_scalar = hash_to_scalar("wraith:scalar:", &shared); let spend_point = CompressedEdwardsY::from_slice(spending_pub) + .expect("32-byte slice always fits CompressedEdwardsY") .decompress() .expect("valid spending pub"); - let stealth_point: EdwardsPoint = - spend_point + h_scalar * ED25519_BASEPOINT_POINT; + let stealth_point: EdwardsPoint = spend_point + h_scalar * ED25519_BASEPOINT_POINT; let stealth_pub = stealth_point.compress().to_bytes(); let stealth_address = stellar_strkey::ed25519::PublicKey(stealth_pub).to_string(); @@ -293,11 +346,9 @@ pub fn generate_stealth_address( } ``` -After calling `derive_stealth_keys`, the `viewing_seed` is available directly on the returned `StealthKeys` struct. Pass it here: `generate_stealth_address(&keys.spending_pub, &keys.viewing_seed, &ephemeral_seed)`. - -```rust +```rust crate // src/stealth.rs (continued) -// --- scan announcements and recover the stealth private scalar --- +// ── Scan announcements and recover the stealth private scalar ───────────────── pub fn scan_announcements( announcements: &[(String, [u8; 32], u8)], // (stealth_address, ephemeral_pub, view_tag) @@ -306,6 +357,7 @@ pub fn scan_announcements( spending_scalar: Scalar, ) -> Vec { let spend_point = CompressedEdwardsY::from_slice(spending_pub) + .expect("32-byte slice always fits CompressedEdwardsY") .decompress() .expect("valid spending pub"); let mut matched = Vec::new(); @@ -330,8 +382,10 @@ pub fn scan_announcements( matched } -// Sign a message with a raw stealth scalar (ed25519 scalar signing, RFC 8032 style). +// ── Sign with a raw stealth scalar (ed25519 / RFC 8032) ─────────────────────── +// // Needed to spend funds received at a stealth address. + pub fn sign_with_scalar(scalar_le: &[u8; 32], message: &[u8], pubkey: &[u8; 32]) -> [u8; 64] { let a = Scalar::from_bytes_mod_order(*scalar_le); let mut h = Sha512::new(); @@ -357,13 +411,18 @@ pub fn sign_with_scalar(scalar_le: &[u8; 32], message: &[u8], pubkey: &[u8; 32]) Announcements are Soroban contract events, not a subgraph. Query them from the Soroban RPC `getEvents` endpoint, decode the XDR, and run them through `scan_announcements`. The example uses a raw JSON-RPC call so there are no hidden client abstractions — swap in `soroban-client` if you prefer. + + This fence is shown as a self-contained `main` so you can run it on its own. The crate compiles the same logic as `run_scan`, gated behind `--features network` so the crypto-only build never pulls in `reqwest` or `tokio`. + + ```rust no-check // src/scan.rs use anyhow::Result; +use ed25519_dalek::Signer; use serde_json::Value; +use crate::network::{ANNOUNCER, RPC_URL, STEALTH_SIGNING_MESSAGE}; use crate::stealth::scan_announcements; -use crate::{ANNOUNCER, RPC_URL}; pub async fn fetch_announcements(start_ledger: u32) -> Result> { let client = reqwest::Client::new(); @@ -388,7 +447,7 @@ pub async fn fetch_announcements(start_ledger: u32) -> Result=1) carry: caller, scheme_id, stealth_address(Address), + // Topics (index >= 1) carry: caller, scheme_id, stealth_address(Address), // ephemeral_pub_key(Bytes), metadata(Bytes, first byte == view tag). // Extract (stealth_address, ephemeral_pub[32], metadata[0]) and push below. let stealth_address = e["topics"][3].as_str().unwrap().to_string(); @@ -431,8 +490,8 @@ use anyhow::Result; use rand::rngs::OsRng; use rand::RngCore; +use crate::network::{ANNOUNCER, RPC_URL, SCHEME_ID}; use crate::stealth::generate_stealth_address; -use crate::{ANNOUNCER, RPC_URL, SCHEME_ID}; pub async fn send_stealth_payment( sender_seed: &[u8; 32], @@ -453,7 +512,7 @@ pub async fn send_stealth_payment( // Shape is stable across soroban-client 0.9–0.11; adapt builder methods to your version. // Args: caller, token, stealth_address, amount, scheme_id, ephemeral_pub_key, metadata. // `metadata` is a single byte (the view tag) or more; keep it >= 1 byte. - let client = soroban_client::Client::new(RPC_URL, crate::NETWORK_PASSPHRASE).await?; + let client = soroban_client::Client::new(RPC_URL, crate::network::NETWORK_PASSPHRASE).await?; let account = client.account(sender_address).await?; let tx = client .tx_builder(&account) diff --git a/package.json b/package.json index f9b40e0..c3d6cd6 100644 --- a/package.json +++ b/package.json @@ -1,59 +1,60 @@ { - "name": "@wraith-protocol/docs", - "private": true, - "type": "module", - "scripts": { - "check:placeholders": "tsx scripts/check-placeholders.ts", - "check:snippets": "tsx scripts/check-snippets.ts && tsx scripts/check-api-examples.ts", - "check:api-examples": "tsx scripts/check-api-examples.ts", - "check:integration-guides": "tsx scripts/check-integration-guides.ts", - "check:snippets-extended": "tsx scripts/check-snippets-extended.ts && npm run check:python-quickstart", - "check:python-quickstart": "tsx scripts/python-quickstart/generate-vectors.ts --check && python3 scripts/python-quickstart/run_quickstart.py --bootstrap", - "generate:python-quickstart-vectors": "tsx scripts/python-quickstart/generate-vectors.ts", - "check:nav-coverage": "node scripts/check-nav-coverage.mjs", - "check:contract-registry": "node --test scripts/check-contract-registry.test.mjs && node scripts/check-contract-registry.mjs", - "check:compatibility-matrix": "node scripts/check-compatibility-matrix.mjs", - "check:redirects-and-anchors": "node scripts/check-redirects-and-anchors.mjs", - "test:redirects-and-anchors": "node --test scripts/check-redirects-and-anchors.test.mjs", - "test:contract-registry": "node --test scripts/check-contract-registry.test.mjs", - "test:preview-redirect": "node --test scripts/check-preview-redirect.test.mjs", - "check:stellar-testnet": "tsx scripts/check-stellar-testnet-snippets.ts", - "test:stellar-testnet": "node --test scripts/check-stellar-testnet-snippets.test.mjs", - "generate:stellar-reference": "tsx scripts/generate-stellar-reference.ts", - "check:stellar-reference": "tsx scripts/generate-stellar-reference.ts --check", - "generate:playground-fixtures": "node scripts/playground/generate-fixtures.mjs", - "check:playground-fixtures": "node scripts/playground/generate-fixtures.mjs --check", - "test:playground": "playwright test --config scripts/playground/tests/playwright.config.ts", - "mint:validate": "mint validate", - "mint:broken-links": "mint broken-links", - "test": "npm run check:snippets && npm run check:integration-guides && npm run check:nav-coverage && npm run check:contract-registry && npm run check:compatibility-matrix && npm run test:redirects-and-anchors" - }, - "dependencies": { - "@solana/web3.js": "^1.99.0", - "@stellar/stellar-sdk": "^13.3.0", - "@wraith-protocol/sdk": "1.4.5" - }, - "devDependencies": { - "@playwright/test": "^1.49.1", - "@types/js-yaml": "4.0.9", - "@types/node": "^22.10.2", - "js-yaml": "4.3.2", - "tsx": "^4.19.2", - "typescript": "^5.7.2" - }, - "pnpm": { - "overrides": { - "axios@<1.20.0": ">=1.20.0", - "follow-redirects@<1.16.1": ">=1.16.1", - "toml@<4.2.0": "^4.2.0", - "uuid@<11.1.1": "^11.1.1" - }, - "auditConfig": { - "ignoreGhsas": [ - "GHSA-528h-pc64-c93x", - "GHSA-hqr4-qq8f-hg3x", - "GHSA-mjw6-4jj6-33hc" - ] - } - } + "name": "@wraith-protocol/docs", + "private": true, + "type": "module", + "scripts": { + "check:placeholders": "tsx scripts/check-placeholders.ts", + "check:snippets": "tsx scripts/check-snippets.ts \u0026\u0026 tsx scripts/check-api-examples.ts", + "check:api-examples": "tsx scripts/check-api-examples.ts", + "check:integration-guides": "tsx scripts/check-integration-guides.ts", + "check:python-quickstart": "tsx scripts/python-quickstart/generate-vectors.ts --check \u0026\u0026 python3 scripts/python-quickstart/run_quickstart.py --bootstrap", + "generate:python-quickstart-vectors": "tsx scripts/python-quickstart/generate-vectors.ts", + "check:nav-coverage": "node scripts/check-nav-coverage.mjs", + "check:contract-registry": "node --test scripts/check-contract-registry.test.mjs \u0026\u0026 node scripts/check-contract-registry.mjs", + "check:compatibility-matrix": "node scripts/check-compatibility-matrix.mjs", + "check:redirects-and-anchors": "node scripts/check-redirects-and-anchors.mjs", + "test:redirects-and-anchors": "node --test scripts/check-redirects-and-anchors.test.mjs", + "test:contract-registry": "node --test scripts/check-contract-registry.test.mjs", + "test:preview-redirect": "node --test scripts/check-preview-redirect.test.mjs", + "check:stellar-testnet": "tsx scripts/check-stellar-testnet-snippets.ts", + "test:stellar-testnet": "node --test scripts/check-stellar-testnet-snippets.test.mjs", + "generate:stellar-reference": "tsx scripts/generate-stellar-reference.ts", + "check:stellar-reference": "tsx scripts/generate-stellar-reference.ts --check", + "generate:playground-fixtures": "node scripts/playground/generate-fixtures.mjs", + "check:playground-fixtures": "node scripts/playground/generate-fixtures.mjs --check", + "test:playground": "playwright test --config scripts/playground/tests/playwright.config.ts", + "mint:validate": "mint validate", + "mint:broken-links": "mint broken-links", + "test": "npm run check:snippets \u0026\u0026 npm run check:integration-guides \u0026\u0026 npm run check:nav-coverage \u0026\u0026 npm run check:contract-registry \u0026\u0026 npm run check:compatibility-matrix \u0026\u0026 npm run test:redirects-and-anchors", + "check:rust-quickstart": "tsx scripts/check-rust-quickstart.ts", + "check:snippets-extended": "tsx scripts/check-snippets-extended.ts \u0026\u0026 npm run check:python-quickstart \u0026\u0026 npm run check:rust-quickstart" + }, + "dependencies": { + "@solana/web3.js": "^1.99.0", + "@stellar/stellar-sdk": "^13.3.0", + "@wraith-protocol/sdk": "1.4.5" + }, + "devDependencies": { + "@playwright/test": "^1.49.1", + "@types/js-yaml": "4.0.9", + "@types/node": "^22.10.2", + "js-yaml": "4.3.2", + "tsx": "^4.19.2", + "typescript": "^5.7.2" + }, + "pnpm": { + "overrides": { + "axios@\u003c1.20.0": "\u003e=1.20.0", + "follow-redirects@\u003c1.16.1": "\u003e=1.16.1", + "toml@\u003c4.2.0": "^4.2.0", + "uuid@\u003c11.1.1": "^11.1.1" + }, + "auditConfig": { + "ignoreGhsas": [ + "GHSA-528h-pc64-c93x", + "GHSA-hqr4-qq8f-hg3x", + "GHSA-mjw6-4jj6-33hc" + ] + } + } } diff --git a/scripts/check-rust-quickstart.ts b/scripts/check-rust-quickstart.ts new file mode 100644 index 0000000..ff3385c --- /dev/null +++ b/scripts/check-rust-quickstart.ts @@ -0,0 +1,566 @@ +/** + * check-rust-quickstart.ts + * + * Deterministic extraction check between the Rust quickstart guide and the + * crate that compiles it. + * + * guides/quickstarts/rust.mdx — what readers copy (source of truth) + * snippets/rust-quickstart/ — the crate CI builds with cargo + * + * Every ```rust fence in the guide whose first line is a `// src/` + * marker belongs to the crate and must be classified: + * + * ```rust crate → extracted and byte-compared against src/.rs + * ```rust no-check → exempt, but only with an entry in EXEMPT below + * (no marker, no attr)→ compiled standalone by check-snippets-extended.ts + * + * The first fence for a file keeps its `// src/` marker line. Later + * fences start with `// src/ (continued)`; that line is dropped when the + * fences are concatenated, so the crate file reads as one normal source file. + * + * A crate source may contain regions that are not shown in the guide (unit + * tests, fixtures). They are delimited by: + * + * // crate-only-begin: + * ... + * // crate-only-end + * + * and are stripped before comparison. Blank lines touching the markers belong + * to the region. + * + * Cargo.toml is compared structurally: feature names, default features, and + * dependency names (including which are optional) must match. Version strings + * may differ so the guide can pin looser ranges than the crate lockfile. + * + * Usage: + * tsx scripts/check-rust-quickstart.ts # check + * tsx scripts/check-rust-quickstart.ts --emit stealth.rs # print the + * crate-only-free source for a file, ready to paste into the guide + */ + +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; +import process from "node:process"; + +const GUIDE = "guides/quickstarts/rust.mdx"; +const CRATE = "snippets/rust-quickstart"; +const CARGO_TOML = path.join(CRATE, "Cargo.toml"); +const SRC_DIR = path.join(CRATE, "src"); + +/** + * Guide fences that intentionally diverge from the crate. Keyed by the file + * named in the fence's `// src/` marker, with the reason it is exempt. + */ +const EXEMPT: Record = { + "scan.rs": + "the guide shows a self-contained example with its own main; the crate " + + "keeps a feature-gated variant behind `--features network`", + "send.rs": + "illustrative soroban-client builder call — that API is not stable " + + "enough to compile against yet", +}; + +const FENCE_PATTERN = /^```([A-Za-z0-9_-]+)([^\n]*)\n([\s\S]*?)^```/gm; +const MARKER_PATTERN = /^\/\/ src\/([A-Za-z0-9_.-]+\.rs)( \(continued\))?$/; +const CRATE_ONLY_BEGIN = /^\/\/ crate-only-begin\b/; +const CRATE_ONLY_END = /^\/\/ crate-only-end\b/; + +type Fence = { + attrs: string; + code: string; + line: number; +}; + +type Group = { + file: string; + fences: Fence[]; + exempt: boolean; +}; + +type Report = { + problems: string[]; + summary: string[]; +}; + +// --------------------------------------------------------------------------- +// Entry point +// --------------------------------------------------------------------------- + +async function main() { + const emitTarget = readEmitTarget(); + + if (emitTarget) { + // Print the crate file with crate-only regions stripped: exactly what + // the guide's fences must concatenate to. + const cratePath = path.join(SRC_DIR, emitTarget); + const source = await readFile(cratePath, "utf8").catch(() => null); + if (!source) { + fail([`crate file src/${emitTarget} not found`]); + } + const problems: string[] = []; + process.stdout.write(stripCrateOnly(source, problems, cratePath)); + return; + } + + const report = await check(); + + if (report.problems.length > 0) { + console.error( + `${report.summary.join("\n")}\n\n` + + `${"=".repeat(60)}\nFAILURES\n${"=".repeat(60)}\n\n` + + report.problems.join("\n\n"), + ); + process.exit(1); + } + + console.log(report.summary.join("\n")); +} + +async function check(): Promise { + const problems: string[] = []; + const guide = await readFile(GUIDE, "utf8"); + const fences = collectFences(guide); + const { groups, standalone, errors } = classify(fences); + problems.push(...errors); + + // Every exemption must still be used, and every crate source must be + // covered — extracted, exempt, or absent from the guide altogether. + const covered = new Set(); + for (const group of groups.values()) { + covered.add(group.file); + if (group.exempt && !EXEMPT[group.file]) { + problems.push( + `${GUIDE}:${group.fences[0].line} — src/${group.file} is \`no-check\` ` + + `but has no exemption reason. Add it to EXEMPT in ` + + `scripts/check-rust-quickstart.ts or mark the fence \`crate\`.`, + ); + } + } + for (const file of Object.keys(EXEMPT)) { + const used = [...groups.values()].some((g) => g.file === file && g.exempt); + if (!used) { + problems.push( + `stale exemption: src/${file} has no \`no-check\` fence in ${GUIDE}`, + ); + } + } + + const crateFiles = (await readdir(SRC_DIR)) + .filter((name) => name.endsWith(".rs")) + .sort(); + for (const file of crateFiles) { + if (!covered.has(file)) { + problems.push( + `src/${file} is neither extracted from ${GUIDE} nor listed in ` + + `EXEMPT — the crate can drift without CI noticing.`, + ); + } + } + + // Byte comparison: guide fences vs crate sources. + for (const group of groups.values()) { + if (group.exempt) continue; + const cratePath = path.join(SRC_DIR, group.file); + let crateSource: string; + try { + crateSource = await readFile(cratePath, "utf8"); + } catch { + problems.push( + `${GUIDE}:${group.fences[0].line} — fence targets src/${group.file}, ` + + `which does not exist. Create it or fix the \`// src/\` marker.`, + ); + continue; + } + + const expected = expectedSource(group); + const actual = stripCrateOnly(crateSource, problems, cratePath); + if (expected !== actual) { + problems.push( + `src/${group.file} has drifted from ${GUIDE}:\n` + + describeDiff(expected, actual, group.fences[0].line, cratePath), + ); + } + } + + problems.push(...(await checkCargoToml(guide))); + + const extracted = [...groups.values()].filter((g) => !g.exempt); + const exempted = [...groups.values()].filter((g) => g.exempt); + const summary = [ + "Rust quickstart extraction check", + ` guide fences : ${fences.length}`, + ` extracted (crate) : ${extracted.length} (${extracted.map((g) => g.file).join(", ") || "-"})`, + ` exempt (no-check) : ${exempted.length} (${exempted.map((g) => g.file).join(", ") || "-"})`, + ` standalone rustc : ${standalone.length}`, + ` crate sources : ${crateFiles.length}`, + ` failures : ${problems.length}`, + ]; + + if (problems.length === 0) { + summary.push("", `All crate sources match ${GUIDE}.`); + } + + return { problems, summary }; +} + +// --------------------------------------------------------------------------- +// Fence collection and classification +// --------------------------------------------------------------------------- + +function collectFences(markdown: string): Fence[] { + const fences: Fence[] = []; + let match: RegExpExecArray | null; + + while ((match = FENCE_PATTERN.exec(markdown)) !== null) { + if (match[1].toLowerCase() !== "rust") continue; + fences.push({ + attrs: match[2] ?? "", + code: (match[3] ?? "").replace(/\r\n/g, "\n"), + line: markdown.slice(0, match.index).split("\n").length, + }); + } + + return fences; +} + +function classify(fences: Fence[]): { + groups: Map; + standalone: Fence[]; + errors: string[]; +} { + const groups = new Map(); + const standalone: Fence[] = []; + const errors: string[] = []; + + for (const fence of fences) { + const wantsCrate = /\bcrate\b/.test(fence.attrs); + const wantsSkip = /\bno-check\b/.test(fence.attrs); + const marker = MARKER_PATTERN.exec(firstLine(fence)); + + if (wantsCrate && wantsSkip) { + errors.push( + `${GUIDE}:${fence.line} — a fence cannot be both \`crate\` and \`no-check\`.`, + ); + continue; + } + + if (!marker) { + if (wantsCrate) { + errors.push( + `${GUIDE}:${fence.line} — \`crate\` fence has no \`// src/\` ` + + `marker line, so it cannot be extracted.`, + ); + } else if (wantsSkip) { + errors.push( + `${GUIDE}:${fence.line} — \`no-check\` fence has no \`// src/\` ` + + `marker line, so nothing ties it to the crate. Give it a marker ` + + `and an EXEMPT reason, or make it checkable.`, + ); + } else { + standalone.push(fence); + } + continue; + } + + const file = marker[1]; + const continued = marker[2] !== undefined; + + if (!wantsCrate && !wantsSkip) { + errors.push( + `${GUIDE}:${fence.line} — src/${file} has a \`// src/\` marker but is ` + + `neither \`crate\` (extracted) nor \`no-check\` (exempt).`, + ); + } + + const group = groups.get(file); + + if (!group) { + if (continued) { + errors.push( + `${GUIDE}:${fence.line} — src/${file} starts with a ` + + `\`(continued)\` marker but has no opening fence.`, + ); + continue; + } + groups.set(file, { file, fences: [fence], exempt: wantsSkip }); + } else { + if (!continued) { + errors.push( + `${GUIDE}:${fence.line} — src/${file} has a second opening fence; ` + + `use \`// src/${file} (continued)\`.`, + ); + } + if (group.exempt !== wantsSkip) { + errors.push( + `${GUIDE}:${fence.line} — all fences for src/${file} must share ` + + `the same attributes (\`crate\` or \`no-check\`).`, + ); + } + group.fences.push(fence); + } + } + + return { groups, standalone, errors }; +} + +function firstLine(fence: Fence): string { + return fence.code.split("\n")[0] ?? ""; +} + +// --------------------------------------------------------------------------- +// Extraction +// --------------------------------------------------------------------------- + +/** + * Concatenate a file's fences into the source the crate must contain. + * The opening fence keeps its `// src/` marker line (a normal file + * header comment); `(continued)` marker lines are dropped. Fences are joined + * with a blank line, so a crate file always has exactly one blank line at a + * fence boundary. + */ +function expectedSource(group: Group): string { + const chunks = group.fences.map((fence, index) => { + const fenceLines = logicalLines(fence.code); + if (index > 0) fenceLines.shift(); // drop the `(continued)` marker + return fenceLines.join("\n"); + }); + + return `${chunks.join("\n\n")}\n`; +} + +/** Split into lines, dropping the trailing newline artifact. */ +function logicalLines(text: string): string[] { + const lines = text.replace(/\r\n/g, "\n").split("\n"); + if (lines.at(-1) === "") lines.pop(); + return lines; +} + +/** + * Remove `// crate-only-begin` … `// crate-only-end` regions from a crate + * source, together with any blank lines touching the markers. + */ +function stripCrateOnly( + source: string, + problems: string[], + location: string, +): string { + const lines = logicalLines(source); + const kept: string[] = []; + let inRegion = false; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + + if (CRATE_ONLY_BEGIN.test(line)) { + if (inRegion) { + problems.push(`${location}:${i + 1} — nested crate-only region.`); + return lines.join("\n"); + } + inRegion = true; + + // Blank lines touching the markers belong to the region. + while (kept.length > 0 && kept[kept.length - 1].trim() === "") { + kept.pop(); + } + continue; + } + + if (CRATE_ONLY_END.test(line)) { + if (!inRegion) { + problems.push( + `${location}:${i + 1} — crate-only-end without a matching begin.`, + ); + return lines.join("\n"); + } + inRegion = false; + + while (i + 1 < lines.length && lines[i + 1].trim() === "") { + i += 1; + } + continue; + } + + if (!inRegion) kept.push(line); + } + + if (inRegion) { + problems.push(`${location} — crate-only region is never closed.`); + return lines.join("\n"); + } + + return `${kept.join("\n")}\n`; +} + +// --------------------------------------------------------------------------- +// Diff reporting +// --------------------------------------------------------------------------- + +function describeDiff( + expected: string, + actual: string, + guideLine: number, + cratePath: string, +): string { + const want = logicalLines(expected); + const got = logicalLines(actual); + + let prefix = 0; + while (prefix < want.length && prefix < got.length && want[prefix] === got[prefix]) { + prefix += 1; + } + + let suffix = 0; + while ( + suffix < want.length - prefix && + suffix < got.length - prefix && + want[want.length - 1 - suffix] === got[got.length - 1 - suffix] + ) { + suffix += 1; + } + + const wantMiddle = want.slice(prefix, want.length - suffix); + const gotMiddle = got.slice(prefix, got.length - suffix); + const window = 8; + + const format = (label: string, lines: string[], sign: string) => { + const shown = lines.slice(0, window); + const head = + shown.length === 0 + ? ` ${label}: ` + : shown + .map((l, i) => ` ${sign} ${label} line ${prefix + i + 1}: ${l}`) + .join("\n"); + const more = + lines.length > shown.length ? `\n … ${lines.length - window} more` : ""; + return head + more; + }; + + return [ + ` first difference at guide line ${guideLine + prefix} / ` + + `${cratePath}:${prefix + 1}:`, + format("guide", wantMiddle, "+"), + format("crate", gotMiddle, "-"), + ].join("\n"); +} + +// --------------------------------------------------------------------------- +// Cargo.toml structural comparison +// --------------------------------------------------------------------------- + +async function checkCargoToml(guide: string): Promise { + const fence = firstTomlFence(guide); + if (!fence) { + return [`${GUIDE} has no TOML fence for Cargo.toml.`]; + } + + const doc = parseToml(fence.code); + const crateToml = parseToml(await readFile(CARGO_TOML, "utf8")); + const problems: string[] = []; + + const compareKeys = (label: string, a: string[], b: string[]) => { + const missing = a.filter((k) => !b.includes(k)); + const extra = b.filter((k) => !a.includes(k)); + if (missing.length > 0) { + problems.push(`Cargo.toml ${label} missing from the crate: ${missing.join(", ")}`); + } + if (extra.length > 0) { + problems.push(`Cargo.toml ${label} missing from the guide: ${extra.join(", ")}`); + } + }; + + compareKeys("features", Object.keys(doc.features), Object.keys(crateToml.features)); + compareKeys( + "dependencies", + Object.keys(doc.dependencies), + Object.keys(crateToml.dependencies), + ); + + for (const name of Object.keys(doc.features)) { + if (!crateToml.features[name]) continue; + const a = [...doc.features[name]].sort().join(","); + const b = [...crateToml.features[name]].sort().join(","); + if (a !== b) { + problems.push( + `Cargo.toml feature \`${name}\` differs: guide [${a}] vs crate [${b}]`, + ); + } + } + + for (const name of Object.keys(doc.dependencies)) { + const inCrate = crateToml.dependencies[name]; + if (!inCrate) continue; + if (doc.dependencies[name].optional !== inCrate.optional) { + problems.push( + `Cargo.toml dependency \`${name}\`: optional=${String(doc.dependencies[name].optional)} ` + + `in the guide, optional=${String(inCrate.optional)} in the crate`, + ); + } + } + + return problems; +} + +function firstTomlFence(guide: string): Fence | null { + const pattern = /^```toml([^\n]*)\n([\s\S]*?)^```/gm; + const match = pattern.exec(guide); + return match ? { attrs: match[1] ?? "", code: match[2] ?? "", line: 0 } : null; +} + +function parseToml(source: string): { + features: Record; + dependencies: Record; +} { + const features: Record = {}; + const dependencies: Record = {}; + let section = ""; + + for (const raw of source.split("\n")) { + const line = raw.replace(/#.*$/, "").trim(); + if (line === "") continue; + + const header = /^\[+([^\]]+)\]+/.exec(line); + if (header) { + section = header[1].trim(); + continue; + } + + const kv = /^([^=]+?)\s*=\s*(.+)$/.exec(line); + if (!kv) continue; + const key = kv[1].trim().replace(/^["']|["']$/g, ""); + const value = kv[2].trim(); + + if (section === "features") { + features[key] = (value.match(/"[^"]*"/g) ?? []).map((s) => s.slice(1, -1)); + } else if (section === "dependencies") { + dependencies[key] = { optional: /optional\s*=\s*true/.test(value) }; + } + } + + return { features, dependencies }; +} + +// --------------------------------------------------------------------------- +// Utilities +// --------------------------------------------------------------------------- + +function readEmitTarget(): string | null { + const arg = process.argv[2]; + if (!arg) return null; + if (arg !== "--emit" || !process.argv[3]) { + fail([ + `unknown argument: ${arg}\n` + + `usage: tsx scripts/check-rust-quickstart.ts [--emit ]`, + ]); + } + return path.basename(process.argv[3]); +} + +function fail(problems: string[]): never { + console.error(problems.join("\n\n")); + process.exit(1); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/scripts/check-snippets-extended.ts b/scripts/check-snippets-extended.ts index dd32073..9f3b499 100644 --- a/scripts/check-snippets-extended.ts +++ b/scripts/check-snippets-extended.ts @@ -17,6 +17,17 @@ * ```python no-check * ```bash no-check * + * Fence attribute: add `crate` to a rust fence whose first line is a + * `// src/` marker, e.g. + * ```rust crate + * // src/stealth.rs + * ... + * ``` + * Those fences belong to a compiling crate (`snippets/rust-quickstart`) and + * are NOT compiled standalone here — they reference crate-internal modules. + * Their extraction and drift check lives in check-rust-quickstart.ts, which + * fails if a `crate` fence is not extracted into a compiled crate file. + * * Every failure is reported as: * [rust] guides/quickstarts/rust.mdx:67 * ---------------------------------------- @@ -83,7 +94,12 @@ async function main() { const allSnippets = await collectSnippets(files); const skipped = allSnippets.filter((s) => /\bno-check\b/.test(s.attrs)); - const checkable = allSnippets.filter((s) => !/\bno-check\b/.test(s.attrs)); + const crateSet = allSnippets.filter((s) => s.lang === "rust" && /\bcrate\b/.test(s.attrs)); + const crateFenced = crateSet.filter((s) => !/\bno-check\b/.test(s.attrs)); + const crateFencedKeys = new Set(crateFenced.map((s) => `${s.file}:${s.index}`)); + const checkable = allSnippets.filter( + (s) => !/\bno-check\b/.test(s.attrs) && !crateFencedKeys.has(`${s.file}:${s.index}`), + ); const byLang = groupBy(checkable, (s) => s.lang); @@ -108,6 +124,7 @@ async function main() { `MDX files scanned : ${files.length}`, `Snippets found : ${allSnippets.length}`, ` rust : ${counts["rust"] ?? 0}`, + ` rust (crate) : ${crateFenced.length}`, ` python : ${counts["python"] ?? 0}`, ` shell : ${counts["shell"] ?? 0}`, ` json : ${counts["json"] ?? 0}`, @@ -337,7 +354,7 @@ function checkToml(snippets: Snippet[]): Promise { * header, not a key-value pair, not a value continuation). */ function lintToml(src: string): string | null { - const lines = src.split("\n"); + const lines = src.replace(/\r\n/g, "\n").split("\n"); for (let i = 0; i < lines.length; i++) { const raw = lines[i]; const line = raw.replace(/#.*$/, "").trim(); // strip inline comments diff --git a/snippets/rust-quickstart/src/keypair.rs b/snippets/rust-quickstart/src/keypair.rs index 589abf7..91db351 100644 --- a/snippets/rust-quickstart/src/keypair.rs +++ b/snippets/rust-quickstart/src/keypair.rs @@ -23,6 +23,8 @@ pub fn load_keypair(secret: &str) -> Result { }) } +// crate-only-begin: fixture secret + unit tests, not shown in the guide + /// Fixture keypair used in tests and CI verification. /// /// This is a well-known test vector: the all-zeros 32-byte seed encoded as a @@ -58,3 +60,4 @@ mod tests { assert_eq!(acct.seed.len(), 32); } } +// crate-only-end diff --git a/snippets/rust-quickstart/src/main.rs b/snippets/rust-quickstart/src/main.rs index 9bd0126..91b770b 100644 --- a/snippets/rust-quickstart/src/main.rs +++ b/snippets/rust-quickstart/src/main.rs @@ -11,31 +11,16 @@ pub mod scan; pub mod send; pub mod stealth; -use network::STEALTH_SIGNING_MESSAGE; - #[cfg(not(feature = "network"))] fn main() -> anyhow::Result<()> { use ed25519_dalek::Signer; - use keypair::load_keypair; - - let secret = std::env::var("STELLAR_SECRET").unwrap_or_else(|_| { - keypair::fixture_keypair() - .signing_key - .to_bytes() - .iter() - .fold(String::new(), |acc, _| acc) - }); // unreachable branch; just satisfies the type - let secret = if secret.is_empty() { - // No env var — use the fixture keypair for a smoke-run. - println!("STELLAR_SECRET not set; using built-in fixture keypair."); - return run_with_fixture(); - } else { - secret - }; + use network::STEALTH_SIGNING_MESSAGE; - let account = load_keypair(&secret)?; - println!("Loaded account: {}", account.address); + let secret = std::env::var("STELLAR_SECRET")?; + let account = keypair::load_keypair(&secret)?; + println!("loaded account: {}", account.address); + // The 64-byte signature drives stealth key derivation. let sig: [u8; 64] = account .signing_key .sign(STEALTH_SIGNING_MESSAGE.as_bytes()) @@ -46,22 +31,6 @@ fn main() -> anyhow::Result<()> { Ok(()) } -#[cfg(not(feature = "network"))] -fn run_with_fixture() -> anyhow::Result<()> { - use ed25519_dalek::Signer; - - let acct = keypair::fixture_keypair(); - println!("Fixture account: {}", acct.address); - let sig: [u8; 64] = acct - .signing_key - .sign(STEALTH_SIGNING_MESSAGE.as_bytes()) - .to_bytes(); - let keys = stealth::derive_stealth_keys(&sig); - println!("spending pub : {}", hex::encode(keys.spending_pub)); - println!("viewing pub : {}", hex::encode(keys.viewing_pub)); - Ok(()) -} - #[cfg(feature = "network")] #[tokio::main] async fn main() -> anyhow::Result<()> { diff --git a/snippets/rust-quickstart/src/stealth.rs b/snippets/rust-quickstart/src/stealth.rs index b4ceee3..3870467 100644 --- a/snippets/rust-quickstart/src/stealth.rs +++ b/snippets/rust-quickstart/src/stealth.rs @@ -198,6 +198,7 @@ pub fn sign_with_scalar(scalar_le: &[u8; 32], message: &[u8], pubkey: &[u8; 32]) sig } +// crate-only-begin: unit tests, not shown in the guide // ── Tests ───────────────────────────────────────────────────────────────────── #[cfg(test)] @@ -287,3 +288,4 @@ mod tests { assert_eq!(found.len(), 0, "corrupted view tag must be filtered"); } } +// crate-only-end From fb1f71bc7f352dd28715edd1651d754223b22ae5 Mon Sep 17 00:00:00 2001 From: midenotch <125803339+midenotch@users.noreply.github.com> Date: Thu, 22 Oct 2026 13:08:10 +0100 Subject: [PATCH 2/2] chore(ci): restore UTF-8 encoding in snippets workflow --- .github/workflows/snippets.yml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/snippets.yml b/.github/workflows/snippets.yml index ff6d8ed..bed0b57 100644 --- a/.github/workflows/snippets.yml +++ b/.github/workflows/snippets.yml @@ -1,4 +1,4 @@ -name: Snippet checks +name: Snippet checks on: pull_request: @@ -98,7 +98,7 @@ jobs: uses: actions/checkout@v4 # ----------------------------------------------------------------------- - # Rust — pinned stable toolchain for reproducibility. + # Rust — pinned stable toolchain for reproducibility. # ----------------------------------------------------------------------- - name: Setup Rust uses: dtolnay/rust-toolchain@stable @@ -107,7 +107,7 @@ jobs: components: rustfmt # ----------------------------------------------------------------------- - # Python — pinned minor version; patch resolved by setup-python. + # Python — pinned minor version; patch resolved by setup-python. # ----------------------------------------------------------------------- - name: Setup Python uses: actions/setup-python@v5 @@ -141,7 +141,7 @@ jobs: run: pnpm run check:snippets-extended # ----------------------------------------------------------------------- - # Compile the Rust quickstart crate — this is the ground-truth check + # Compile the Rust quickstart crate — this is the ground-truth check # that all documented crypto code actually compiles and its tests pass. # The second pass enables the "network" feature so the scan / send # modules (reqwest / tokio) are type-checked too; it is compile-only, @@ -166,7 +166,7 @@ jobs: stellar-testnet-snippets: name: Stellar snippet testnet validation runs-on: ubuntu-latest - # No top-level continue-on-error — individual steps control leniency. + # No top-level continue-on-error — individual steps control leniency. needs: extract-sdk-version steps: - name: Checkout @@ -215,9 +215,9 @@ jobs: # the next step a reliable signal to branch on. # # Exit codes (defined in check-stellar-testnet-snippets.ts): - # 0 – all checks passed - # 1 – content regression → hard failure, blocks merge - # 2 – provider outage → warning annotation only, does NOT block + # 0 – all checks passed + # 1 – content regression → hard failure, blocks merge + # 2 – provider outage → warning annotation only, does NOT block - name: Validate Stellar testnet provider availability (non-blocking) id: provider-check continue-on-error: true @@ -231,9 +231,9 @@ jobs: echo "exit-status=$STATUS" >> "$GITHUB_OUTPUT" exit $STATUS - # Exit 1 → content regression from a reachable provider; hard-fail. - # Exit 2 → provider outage; emit a warning annotation and continue. - # Exit 0 → all good; nothing to do. + # Exit 1 → content regression from a reachable provider; hard-fail. + # Exit 2 → provider outage; emit a warning annotation and continue. + # Exit 0 → all good; nothing to do. - name: Classify provider-check exit status if: always() env: