SpecMap: Spec-Code-WPT Mapping

Spec URL or fragment: $0 Specific algorithm (optional): $1

Step 1: Identify the Spec Target and Read Spec Content

If you have a spec URL (from a bug report, code comment, etc.), query it directly:

webspec-index query 'https://html.spec.whatwg.org/#navigate' --format markdown
webspec-index refs 'https://html.spec.whatwg.org/#navigate'

If you only have a feature name, search for it:

webspec-index search "FEATURE_NAME" --limit 5
webspec-index search "FEATURE_NAME" --spec HTML --limit 5

If the exact fragment is unknown, find it by pattern or by listing sections:

webspec-index anchors '*navigate*' --spec HTML
webspec-index list HTML

For a long algorithm, get the step outline first, then the sub-algorithms it calls with their arguments. Each callee is a unit the implementation has to cover:

webspec-index query 'HTML#navigate' --depth 1 --format markdown
webspec-index state 'HTML#navigate' --calls --format markdown

For WebIDL definitions, query the member or interface:

webspec-index idl 'Window.navigation' --format markdown
webspec-index idl 'Window.open()' --format markdown

If the spec is not indexed by webspec-index, fall back to the webref IDL extract, using the spec shortname (visible in search results or derivable from the URL):

curl -s "https://w3c.github.io/webref/ed/idl/SHORTNAME.idl"

Step 2: Query Searchfox for References

Use searchfox-cli to find files referencing the spec section. Start with the exact lookup, passing the url field from the query response:

searchfox-cli --spec-refs 'https://html.spec.whatwg.org/#navigate'

Then widen by pattern, split by file type:

# Implementation code (excludes test and generated files)
searchfox-cli -q "DOMAIN.*#FRAGMENT" --only-normal -l 200
searchfox-cli -q "#FRAGMENT" --only-normal --path "dom\|html\|layout\|widget" -l 200
searchfox-cli --id InterfaceName --only-normal -l 100

# Test files only
searchfox-cli -q "DOMAIN.*#FRAGMENT" --only-tests -l 200
searchfox-cli -q "#FRAGMENT" --only-tests -l 200

If results are sparse, try alternative fragment spellings or the IDL interface/method name from webspec-index idl. If results are too broad, narrow with --path. Run --spec-refs for each callee from state --calls as well: a callee with no hits is often a missing piece of the implementation.

Step 3: Analyze Gaps

Cross-reference the algorithm steps and callees from Step 1 against the searchfox results from Step 2 to identify:

  • Spec steps with no corresponding implementation code

  • Spec steps with implementation but no test coverage in WPT

  • WPT tests that are currently failing or disabled

WPT is the preferred test location for web platform features. Do NOT flag the absence of Mozilla-specific tests (mochitest, browser-chrome, etc.) as a gap when there is adequate WPT coverage. Mozilla tests are only expected for Firefox-specific behavior that WPT cannot cover (e.g. chrome-privileged APIs, internal pref gating, process architecture).

To check WPT status, look for .ini expectation files using dedicated tools (avoid bash loops which trigger permission prompts):

  1. Use Glob to find .ini files: testing/web-platform/meta/PATH/*.ini

  2. For each .ini file found, use Grep with output_mode: "count" to count expected: and disabled: lines.

No .ini file means the test fully passes. An .ini with disabled: lines means skipped tests. Count expected: lines for the number of non-default expectations.

Step 4: Present the Map

Output a structured report:

## SpecMap: [Feature Name]
Spec: [full spec URL with fragment]

### Implementation Code
| File | Function/Class | Line | Notes |
|------|---------------|------|-------|
| dom/Foo.cpp | Foo::Bar() | 123 | Step 4 of algorithm |

### Web Platform Tests
| Test File | Status | Tests |
|-----------|--------|-------|
| .../feature.html | PASS (no .ini) | 12 subtests |
| .../feature-edge.html | PARTIAL (.ini has 3 expected fails) | 8 subtests |

### Mozilla Tests
| Test File | Type | Notes |
|-----------|------|-------|
| dom/tests/mochitest/test_feature.html | mochitest | ... |

### Coverage Summary
- Spec steps with implementation: N/M
- WPT files found: N (K passing, J partial, L failing)
- Gaps: [list spec steps or areas with no code or test coverage]

Split test results: files under testing/web-platform/ are WPT, other test files are Mozilla tests (mochitest, browser-chrome, xpcshell).

Step 5: Offer to Add Missing References

If implementation code lacks a spec URL comment or step annotations, offer to add them. Ask for confirmation before making edits. Before inserting any spec URL, verify the anchor exists:

webspec-index exists 'SHORTNAME#FRAGMENT' && echo "valid"
# e.g.:
webspec-index exists 'HTML#navigate' && echo "valid"

Examples of references to add:

  • // https://spec.example.org/#section at the top of an implementing function

  • // Step N. comments for algorithm implementations

  • Spec URL references in .webidl files next to interface/method definitions

Tips

  • WHATWG fragments follow patterns: #dom-interface-method, #the-element-name-element, #concept-name

  • Firefox code references specs as // https://html.spec.whatwg.org/#fragment or // Step N of https://...

  • When a spec URL is in a code comment, you can pass it directly to webspec-index query 'URL' to read the referenced section