webspec-index 0.9.0

Query WHATWG/W3C/TC39 web specifications from the command line
Documentation

webspec-index

Query WHATWG, W3C, and TC39 web specifications from the command line.

Features

  • Full-text search across HTML, DOM, URL, CSS, ECMAScript, and 70+ other specifications
  • Cross-reference tracking — see incoming/outgoing references between spec sections
  • Graph traversal — build cross-reference graphs with JSON, Mermaid, or Graphviz DOT output
  • WHATWG PR previews — query spec sections as modified by an open PR, with section-level diffs
  • Auto URL indexing for whitelisted domains — query non-hardcoded specs by URL
  • Fast SQLite indexing with FTS5 for instant queries
  • Algorithm and IDL extraction with rendered markdown content
  • LSP server for inline spec hovers and step validation in your editor
  • LLM-friendly --help output — automatically detected when run inside Claude Code, Codex, Gemini CLI, or OpenCode

Installation

cargo binstall webspec-index

Or build from source:

cargo install webspec-index

Quick Start

# Look up a spec section (algorithm, definition, heading, IDL)
webspec-index query "HTML#navigate"
webspec-index query "https://html.spec.whatwg.org/#navigate"
webspec-index query "https://w3c.github.io/webappsec-permissions-policy/#permissions-policy-header"
webspec-index query "DOM#concept-tree" --format markdown

# Full-text search
webspec-index search "tree order" --spec DOM

# Check if an anchor exists (exit code 0 = found, 1 = not found)
webspec-index exists "HTML#navigate"

# Find anchors by glob pattern
webspec-index anchors "*-tree" --spec DOM

# List all headings in a spec
webspec-index list HTML

# Cross-references (exact or shorthand)
webspec-index refs "HTML#navigate" --direction incoming
webspec-index refs "Window.navigation" --limit 5

# Graph traversal
webspec-index graph "HTML#navigate" --max-depth 2 --graph-format mermaid
webspec-index graph "HTML#navigate" --graph-format dot
webspec-index graph "HTML#navigate" --same-spec-only
webspec-index graph "HTML#navigate" --include "*concept-*" --exclude "re:^URL#"

# Query dedicated WebIDL definitions
webspec-index idl "HTML#dom-window-navigation"
webspec-index idl "Window.navigation"
webspec-index idl "Window.open()" --spec HTML

# Update specs to latest versions
webspec-index update

WHATWG PR Previews

Query spec sections as they would look after a WHATWG PR is merged. Previews are lazily fetched from whatpr.org and cached locally.

# Query a section from a PR preview (falls back to merge base for unchanged sections)
webspec-index query "HTML#navigate" --pr 12345
webspec-index query "HTML#navigate" --pr 12345 --format markdown

# Diff: see what sections the PR adds or modifies vs the merge base
webspec-index query "HTML#navigate" --pr 12345 --diff --format markdown

# Force re-fetch (e.g. after the PR is updated)
webspec-index query "HTML#navigate" --pr 12345 --force-update

# Other commands also support --pr
webspec-index exists "HTML#navigate" --pr 12345
webspec-index list HTML --pr 12345
webspec-index refs "HTML#navigate" --pr 12345
webspec-index search "OpaqueRange" --spec HTML --pr 12345
webspec-index anchors "*opaquerange*" --spec HTML --pr 12345

# Manage cached PR data (each PR caches rendered pages + merge base)
webspec-index clear-pr                          # list cached PRs
webspec-index clear-pr --spec HTML --pr 12345   # remove one
webspec-index clear-pr --all                    # remove all

All commands support --format json (default) or --format markdown.

Spec data is fetched and cached locally on first query — no setup needed.

Spec refreshes are freshness-based: once checked, a spec is considered fresh for 24h. When refreshed, the CLI fetches live HTML and re-indexes only if content changed.

AI Agent Integration

Skill file

Drop SKILL.md into your repo to teach the agent how to use the CLI.

Editor Integration

The webspec-lens extension provides inline spec hovers, step validation, and coverage tracking. Available for VS Code and any LSP-compatible editor.

See editors/vscode/ and editors/zed/ for details.

How It Works

  1. Fetches spec HTML from WHATWG/W3C/TC39 spec URLs
  2. Parses sections, algorithms, IDL definitions, and cross-references
  3. Indexes in SQLite with FTS5 for fast full-text search
  4. Refreshes snapshots on a 24h cadence with content-hash change detection
  5. PR previews fetch rendered pages from whatpr.org and the merge base from commit-snapshots, storing both as separate snapshots for querying and diffing

Development

cargo test
cargo clippy        # lint
cargo fmt --check   # format check

License

MIT

Links