feat: add vale for docs linting

.github/workflows/on-pull-request.yml

@@ -3,6 +3,21 @@
   pull_request:
 
 jobs:
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**/*.mdx'
+
   enforce_title:
     name: Enforce PR Title Format
     runs-on: ubuntu-latest
@@ -21,8 +36,74 @@
         env:
           TITLE: ${{ github.event.pull_request.title }}
         run: echo "$TITLE" | yarn commitlint
+
+  lint_docs:
+    name: Lint Documentation
+    runs-on: ubuntu-latest
+    needs: changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
+    steps:
+      - name: "Checkout files"
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.ALCHEMY_BOT_PAT }}
+          fetch-depth: "0"
+          submodules: "recursive"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22'
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Install Vale
+        run: |
+          wget -O vale.tar.gz https://github.com/errata-ai/vale/releases/download/v3.12.0/vale_3.12.0_Linux_64-bit.tar.gz
+          tar -xzf vale.tar.gz
+          sudo mv vale /usr/local/bin/
+          vale --version
+
+      - name: Run documentation linting
+        run: yarn lint:docs
+
+  check_broken_links:
+    name: Check Broken Links
+    runs-on: ubuntu-latest
+    needs: changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
+    # TODO: Remove this after fixing all broken links
+    continue-on-error: true
+    steps:
+      - name: "Checkout files"
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.ALCHEMY_BOT_PAT }}
+          fetch-depth: "0"
+          submodules: "recursive"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22'
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Install Lychee
+        run: |
+          wget -O lychee.tar.gz https://github.com/lycheeverse/lychee/releases/download/lychee-v0.20.1/lychee-x86_64-unknown-linux-gnu.tar.gz
+          tar -xzf lychee.tar.gz
+          sudo mv lychee /usr/local/bin/
+          lychee --version
+
+      - name: Check for broken links
+        run: yarn docs:broken-links
 
   lint:
     name: Lint
     runs-on: ubuntu-latest
     permissions:

.gitignore

@@ -129,4 +129,6 @@ Pods
 
 vendor
 
-.claude/settings.local.json
+.claude/settings.local.json
+
+.lycheecache

.vale.ini

@@ -0,0 +1,29 @@
+# Vale configuration for Alchemy Smart Wallets documentation
+# Based on CONTRIBUTING.md guidelines
+
+StylesPath = .vale/styles
+
+# Custom vocabulary for technical terms
+Vocab = SmartWallets
+
+# Minimum alert level (suggestion, warning, error)
+MinAlertLevel = suggestion
+
+# Ignore certain scopes in Markdown/MDX (global settings)
+SkippedScopes = script, style, pre, code, tt, img, url, a, body.id
+IgnoredScopes = script, style, pre, code, tt, img, url, a, body.id
+
+# File patterns to include/exclude - MDX files only
+[*.mdx]
+# Base Vale styles to extend (Vale required for vocabulary system)
+BasedOnStyles = Vale, SmartWallets
+Vale.Repetition = NO
+# Comment delimiters for ignoring sections
+# <!-- vale off --> and <!-- vale on -->
+CommentDelimiters = <!--, -->
+
+# Specific settings for docs directory - MDX only
+[docs/**/*.mdx]
+BasedOnStyles = Vale, SmartWallets
+Vale.Repetition = NO
+CommentDelimiters = <!--, -->

.vale/README.md

@@ -0,0 +1,159 @@
+# Vale Configuration for Smart Wallets Documentation
+
+This directory contains Vale configuration and custom style rules for linting Alchemy Smart Wallets documentation according to the guidelines in `/docs/CONTRIBUTING.md`.
+
+## Setup
+
+### Prerequisites
+
+1. **Install Vale**:
+
+   ```bash
+   # macOS with Homebrew
+   brew install vale
+
+   # Other platforms: https://vale.sh/docs/vale-cli/installation/
+   ```
+
+2. **Verify installation**:
+   ```bash
+   vale --version
+   ```
+
+## Usage
+
+### Quick Start
+
+```bash
+# From project root, run Vale on specific MDX files
+vale docs/pages/some-page.mdx
+
+# Run on all MDX files in docs directory
+vale docs/**/*.mdx
+
+# Use yarn script
+yarn lint:docs
+```
+
+### Configuration Files
+
+- **`.vale.ini`** - Main Vale configuration file
+- **`styles/SmartWallets/`** - Custom style rules directory
+- **`styles/config/vocabularies/SmartWallets/`** - Vocabulary system
+  - `accept.txt` - Technical terms that are accepted (enforces exact casing)
+  - `reject.txt` - Prohibited terms that should be avoided
+
+### Custom Style Rules
+
+The SmartWallets style includes these rules based on `CONTRIBUTING.md`:
+
+#### 1. **Terminology.yml** (Error Level)
+
+- Enforces approved terms from CONTRIBUTING.md
+- Replaces prohibited terms with approved alternatives
+- Examples:
+  - ❌ "Account Abstraction" → ✅ "smart account functionality"
+  - ❌ "user operations" → ✅ "transactions"
+  - ❌ "bundler" → ✅ "transaction processing"
+
+#### 2. **Voice.yml** (Error Level)
+
+- Enforces second-person voice ("you" instead of "we")
+- Detects first-person usage patterns
+
+#### 3. **PassiveVoice.yml** (Warning Level)
+
+- Detects passive voice constructions
+- Encourages active voice per style guide
+
+#### 4. **DirectCommands.yml** (Warning Level)
+
+- Encourages direct commands over indirect suggestions
+- ❌ "You should install..." → ✅ "Install..."
+
+#### 5. **Qualifiers.yml** (Suggestion Level)
+
+- Detects unnecessary qualifiers that weaken tone
+- Examples: "perhaps", "might want to", "you may wish to"
+
+#### 6. **CodeFormatting.yml** (Suggestion Level)
+
+- Ensures technical terms are wrapped in backticks
+- Examples: `aa-sdk`, `getSigner`, `Provider`
+
+#### 7. **Capitalization.yml** (Error Level)
+
+- Enforces sentence case for headings only
+- Preserves proper nouns and acronyms
+
+### Ignoring Vale Rules
+
+To temporarily disable Vale checking in documentation:
+
+```markdown
+<!-- vale off -->
+
+This content will be ignored by Vale.
+You can use prohibited terms here for technical accuracy.
+
+<!-- vale on -->
+```
+
+To ignore specific rules:
+
+```markdown
+<!-- vale SmartWallets.Terminology = NO -->
+
+This allows using Account Abstraction terminology when needed.
+
+<!-- vale SmartWallets.Terminology = YES -->
+```
+
+## MDX Support
+
+**Current Status**: Vale is configured to lint MDX files only. If you encounter issues with MDX processing, you may need to install additional dependencies:
+
+```bash
+# If MDX processing fails, try installing mdx2vast
+npm install -g mdx2vast
+```
+
+**Note**: Vale will attempt to process MDX files directly. Most rules should work without additional setup.
+
+## Integration
+
+### VS Code Integration
+
+Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server) for real-time linting.
+
+## Customization
+
+### Adding New Rules
+
+1. Create a new `.yml` file in `styles/SmartWallets/`
+2. Follow Vale's rule format: https://vale.sh/docs/topics/styles/
+3. Test the rule: `vale --config=.vale.ini docs/test-file.md`
+
+### Modifying Existing Rules
+
+Edit the relevant `.yml` file in `styles/SmartWallets/` and test changes.
+
+### Vocabulary
+
+Add approved terms to `styles/SmartWallets/vocab.txt` to prevent spelling errors.
+
+### Testing Changes
+
+```bash
+# Test a specific rule
+vale --config=.vale.ini --filter='*.Terminology' docs/README.md
+
+# Test with different alert levels
+vale --minAlertLevel=error docs/README.md
+```
+
+## Resources
+
+- [Vale Documentation](https://vale.sh/docs/)
+- [Smart Wallets Contributing Guidelines](/docs/CONTRIBUTING.md)
+- [Google Developer Documentation Style Guide](https://developers.google.com/style)

.vale/styles/SmartWallets/Capitalization.yml

@@ -0,0 +1,11 @@
+# Capitalization rules for headings only
+# Enforces proper capitalization per CONTRIBUTING.md guidelines
+
+extends: capitalization
+message: "Use title case for headings: '%s'"
+level: suggestion
+scope: heading
+
+# Match patterns and their required capitalization
+match: $title
+style: title

.vale/styles/SmartWallets/CodeFormatting.yml

@@ -0,0 +1,16 @@
+# Code formatting rule
+# Ensures technical terms and function names are properly formatted with backticks
+
+extends: existence
+message: "Wrap '%s' in backticks for proper code formatting"
+level: suggestion
+ignorecase: false
+
+# Technical terms that should be in backticks when not already formatted
+tokens:
+  - "(?<!`)aa-sdk(?!`)"
+  - "(?<!`)getSigner(?!`)"
+  - "(?<!`)sendUserOperation(?!`)"
+  - "(?<!`)createAccount(?!`)"
+  - "(?<!`)bundlerClient(?!`)"
+  - "(?<!`)paymasterClient(?!`)"

.vale/styles/SmartWallets/DirectCommands.yml

@@ -0,0 +1,22 @@
+# Direct commands rule
+# Enforces direct, confident commands as required in CONTRIBUTING.md
+
+extends: existence
+message: "Use direct commands. Say '%s' instead"
+level: warning
+ignorecase: true
+
+# Indirect command patterns that should be direct
+tokens:
+  - 'you\s+need\s+to\s+install'
+  - 'you\s+should\s+install'
+  - 'you\s+need\s+to\s+create'
+  - 'you\s+should\s+create'
+  - 'you\s+need\s+to\s+configure'
+  - 'you\s+should\s+configure'
+  - 'you\s+need\s+to\s+set'
+  - 'you\s+should\s+set'
+  - 'you\s+may\s+want\s+to'
+  - 'you\s+might\s+want\s+to'
+  - 'you\s+can\s+optionally'
+  - 'it\s+is\s+recommended\s+to'

.vale/styles/SmartWallets/PassiveVoice.yml

@@ -0,0 +1,24 @@
+# Passive voice detection rule
+# Enforces active voice as required in CONTRIBUTING.md
+
+extends: existence
+message: "Use active voice instead of passive voice"
+level: warning
+ignorecase: true
+
+# Common passive voice patterns
+tokens:
+  - '\bis\s+created\s+by\b'
+  - '\bare\s+created\s+by\b'
+  - '\bwas\s+created\s+by\b'
+  - '\bwere\s+created\s+by\b'
+  - '\bis\s+provided\s+by\b'
+  - '\bare\s+provided\s+by\b'
+  - '\bis\s+supported\s+by\b'
+  - '\bare\s+supported\s+by\b'
+  - '\bshould\s+be\s+created\b'
+  - '\bshould\s+be\s+configured\b'
+  - '\bshould\s+be\s+installed\b'
+  - '\bcan\s+be\s+used\b'
+  - '\bmust\s+be\s+set\b'
+  - '\bwill\s+be\s+created\b'

.vale/styles/SmartWallets/Qualifiers.yml

@@ -0,0 +1,20 @@
+# Qualifiers rule
+# Detects unnecessary qualifiers that should be removed for confident tone
+
+extends: existence
+message: "Remove qualifier '%s' for more confident tone"
+level: suggestion
+ignorecase: true
+
+# Qualifiers to avoid per CONTRIBUTING.md
+tokens:
+  - '\bperhaps\b'
+  - '\bmight\s+want\s+to\b'
+  - '\byou\s+may\s+wish\s+to\b'
+  - '\bpossibly\b'
+  - '\bprobably\b'
+  - '\bseems\s+like\b'
+  - '\bappears\s+to\b'
+  - '\btends\s+to\b'
+  - '\bkind\s+of\b'
+  - '\bsort\s+of\b'