A URL is a public API that almost nobody writes down. A filter panel adds ?tag=a&tag=b, an analytics link bolts on utmsource, someone bookmarks ?page=007, a mail client re-encodes a query, and every one of these paths through the application has a different idea of what the link means. The failures are quiet: a repeated key silently resolves to the last value, an unknown key is dropped on the next navigation, a truncated percent escape turns into U+FFFD and gets stored as a search term.
This walkthrough uses the tool's public README and checked-in example files. Run the command from a repository checkout with Node.js 22+.
Run the checked-in example
node bin/url-state-contract-checker.mjs --contract examples/contract.json --urls examples/urls.clean.jsonRead the result
stdout carries the JSON report and nothing else, so it pipes straight into a parser. The human summary and every usage diagnostic go to stderr.
Scope
Determinism, the full rule catalog, the declared limits and the reasons URLSearchParams is not used are documented in docs/url-state-contract.md.