fix(domxref): build Web/API index to resolve API names by caugner · Pull Request #672 · mdn/rari

caugner · 2026-05-11T11:34:56Z

Description

Updates the domxref macro to resolve API names via an Web/API index (rather than just composing Web/API/{arg}):

Web/API/Window/foo can be referenced via {{domxref("Window/foo")}} or {{domxref("foo")}}
Web/API/BackgroundFetchManager/fetch can be referenced via {{domxref("BackgroundFetchManager/fetch")}}
Web/API/Background_Synchronization_API/Reference/SyncEvent can be referenced via {{domxref("SyncEvent")}}

Note: The argument of the domxref macro continues to be normalized:

Space is replaced by underline (" " → "_")
Parentheses are trimmed ("()" → "")
Prototype infix is removed (".prototype." → ".")
Dots are replaced by slashes ("." → "/")

Motivation

Support shortcuts like {{domxref("structuredClone")}} avoiding templ-redirected-link issues.

Additional details

Build comparison yielded:

Source	main	branch	Δ
`domxref` + `templ-redirected-link`	6,531	5,697	−834
`domxref` + `templ-broken-link`	3,645	3,634	−11
Other sources	~12,856	~12,861	±5
Total	~23,035	~22,192	−843

~13% of domxref redirected/broken issues cleared; other templates unchanged.

Related issues and pull requests

Part of #683.

Build a lazy en-US index of all `Web/API/*` page slugs keyed by both full sub-slug (e.g. `Window/structuredClone`) and leaf segment (e.g. `structuredClone`). `domxref` now resolves inputs against this map, using the canonical slug on hit and falling back to the previous capitalize-first-char URL construction on miss. Ambiguous lookups emit a `templ-ambiguous-arg` warning and pick the first candidate.

github-actions · 2026-05-11T11:39:07Z

45c0148 was deployed to: https://rari-pr672.review.mdn.allizom.net/

The test fixture previously duplicated the per-slug indexing body of `build_index`. Adding a new alias rule in `build_index` would silently diverge from the fixture and tests would still pass. Pull the per-slug work into `index_one` and have both `build_index` and the test fixture call it.

When `Response/json` and `Response/json_static` collide under the shared `response/json` key, both have equal sort keys, so `min_by_key` falls back to insertion order. Document that this relies on the ascending slug order produced by `SubPagesSorter::Slug` in `build_index`.

The `_static` suffix strip is applied unconditionally to any slug matching the suffix. Document the implicit assumption that the suffix always denotes a static member, so future readers know the alias is not a structural guarantee.

Surface the `Window/*` leaf shortcut and the full-path requirement for other interfaces' members on the `domxref` template itself, so authors discover the behavior without reading the index implementation.

The pre-existing fallback used `api.char_indices().next()` to grab the byte offset of the first char (always 0) and then sliced `api[0..0]` to uppercase — i.e. uppercased the empty string, then appended the full input verbatim. The intended behavior never ran. Build the URL from the normalized input directly.

A failed index build silently degrades every subsequent `domxref` call to the legacy URL-construction fallback. Escalate from `warn!` to `error!` so the failure surfaces in `--deny-warnings` builds and is harder to miss in logs.

The function returns `&'static str` because it borrows from the `API_NAME_INDEX` `LazyLock`, which is never dropped. Spell that out so future readers don't wonder where the lifetime comes from.

The fixture now lists slugs in the same ascending order that `build_index` consumes them from `get_sub_pages`, matching the tie-break-correctness invariant documented in `resolve_from_map`.

caugner · 2026-05-11T19:17:44Z

Took: 15.622264285s - 0 changes in 0 of 14390 files (0.0%)

✅

LeoMcA

Overall looks good, but I've got a few questions about the details:

LeoMcA · 2026-05-14T17:05:10Z

+    let indexable = sub_slug
+        .split_once("/Reference/")
+        .map(|(_, after)| after)
+        .unwrap_or(sub_slug);


Do we want to include the sub_slug in the map? Perhaps that should be inserted more explicitly, and we should wrap the insert_unique below with if let Some(...?

LeoMcA · 2026-05-14T17:09:16Z

+        Ok(pages) => pages,
+        Err(e) => {
+            error!("failed to build domxref API name index: {e}");
+            return HashMap::new();


Should this panic instead? Feels like this is a pretty catastrophic error which is worthy of killing the build

LeoMcA · 2026-05-14T17:21:20Z

+    if !entry.iter().any(|v| v == &value) {
+        entry.push(value);
+    }


Could we replace the Vec here with an IndexSet or a BTreeSet (if we don't care about preserving insertion order), to avoid having to manually dedup?

LeoMcA · 2026-05-14T17:22:28Z

+    // in iteration order. Correctness then relies on `build_index` iterating
+    // pages in ascending slug order (`SubPagesSorter::Slug`) so the canonical
+    // entry is inserted before its `_static`-suffixed sibling.


Can we avoid this by sorting by length, or explicitly check for strings ending with static?

An empty index silently degrades to the pre-index fallback, producing a flood of spurious `templ-redirected-link` issues without any clear signal of root cause. Failing loudly makes the problem immediately visible.

…index_one` The previous `split_once(...).unwrap_or(sub_slug)` idiom obscured the distinction between reorg pages (indexed by the post-`/Reference/` leaf) and normal pages (indexed by the full sub-slug). An explicit `if let Some` branch makes each case and its intent visible in the code structure.

…t<String>` `indexmap` is already a workspace dependency of `rari-doc`. `IndexSet` preserves insertion order (required for the resolution tie-break) and deduplicates automatically on `insert`, so the `insert_unique` helper can be replaced by a direct `.insert()` call.

…` check Replace the `v.to_lowercase() != key` secondary sort key with `v.ends_with(\"_static\")`, which is self-documenting: non-`_static` slugs are preferred over their `_static`-aliased counterparts. The previous formulation also carried a misleading comment claiming correctness depended on insertion order, which was not actually the case.

…ookup Covers the converse of `window_member_resolves_by_leaf`: non-Window members have no leaf-only shortcut and must be referenced by their full sub-path (e.g. `WorkerGlobalScope/structuredClone`).

caugner temporarily deployed to review May 11, 2026 11:38 — with GitHub Actions Inactive

fix(domxref): resolve window/Window to Web/API/Window

9761a78

caugner temporarily deployed to review May 11, 2026 11:55 — with GitHub Actions Inactive

fix(domxref): restrict leaf-key shortcut to Window/*

155eb5b

caugner temporarily deployed to review May 11, 2026 12:07 — with GitHub Actions Inactive

fix(domxref): support Web API reorg structure

edbdbf5

caugner temporarily deployed to review May 11, 2026 12:12 — with GitHub Actions Inactive

This comment was marked as outdated.

Sign in to view

caugner added 2 commits May 11, 2026 14:35

chore(domxref): remove templ-ambiguous-arg handling

75e0888

fix(domxref): handle static members

2d3ce4a

caugner changed the title ~~fix(domxref): resolve API names via Web/API index~~ fix(domxref): build Web/API index to resolve API names May 11, 2026

caugner temporarily deployed to review May 11, 2026 12:44 — with GitHub Actions Inactive

caugner marked this pull request as ready for review May 11, 2026 12:49

caugner requested a review from a team as a code owner May 11, 2026 12:49

caugner requested a review from LeoMcA May 11, 2026 12:49

caugner added 8 commits May 11, 2026 14:57

docs(domxref): describe name-resolution shortcuts in the macro doc

e147f9d

Surface the `Window/*` leaf shortcut and the full-path requirement for other interfaces' members on the `domxref` template itself, so authors discover the behavior without reading the index implementation.

fix(domxref): log index-build failure at error! level

51105fa

A failed index build silently degrades every subsequent `domxref` call to the legacy URL-construction fallback. Escalate from `warn!` to `error!` so the failure surfaces in `--deny-warnings` builds and is harder to miss in logs.

docs(domxref): note 'static borrow origin on resolve_api_name

3096ceb

The function returns `&'static str` because it borrows from the `API_NAME_INDEX` `LazyLock`, which is never dropped. Spell that out so future readers don't wonder where the lifetime comes from.

test(domxref): sort fixture slugs to match SubPagesSorter::Slug

579b433

The fixture now lists slugs in the same ascending order that `build_index` consumes them from `get_sub_pages`, matching the tie-break-correctness invariant documented in `resolve_from_map`.

caugner temporarily deployed to review May 11, 2026 13:06 — with GitHub Actions Inactive

caugner mentioned this pull request May 11, 2026

Remove {{DOMxRef("External"}} mdn/content#44074

Merged

Merge branch 'main' into domxref-with-index

4c33ec0

caugner temporarily deployed to review May 11, 2026 17:33 — with GitHub Actions Inactive

caugner mentioned this pull request May 11, 2026

fix(cssxref): build Web/CSS index to resolve CSS features #682

Open

LeoMcA reviewed May 14, 2026

View reviewed changes

caugner added 4 commits May 20, 2026 19:12

Merge branch 'main' into domxref-with-index

14e2683

fix(domxref): panic on API name index build failure

6624f05

An empty index silently degrades to the pre-index fallback, producing a flood of spurious `templ-redirected-link` issues without any clear signal of root cause. Failing loudly makes the problem immediately visible.

caugner temporarily deployed to review May 20, 2026 17:18 — with GitHub Actions Inactive

caugner added 2 commits May 20, 2026 19:18

test(domxref): assert WorkerGlobalScope member requires full-path l…

72bd6da

…ookup Covers the converse of `window_member_resolves_by_leaf`: non-Window members have no leaf-only shortcut and must be referenced by their full sub-path (e.g. `WorkerGlobalScope/structuredClone`).

caugner deployed to review May 20, 2026 17:42 — with GitHub Actions View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(domxref): build Web/API index to resolve API names#672

fix(domxref): build Web/API index to resolve API names#672
caugner wants to merge 21 commits into
mainfrom
domxref-with-index

caugner commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

caugner commented May 11, 2026

Uh oh!

LeoMcA left a comment

Uh oh!

LeoMcA May 14, 2026

Uh oh!

LeoMcA May 14, 2026

Uh oh!

LeoMcA May 14, 2026

Uh oh!

LeoMcA May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

caugner commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

caugner commented May 11, 2026

Uh oh!

LeoMcA left a comment

Choose a reason for hiding this comment

Uh oh!

LeoMcA May 14, 2026

Choose a reason for hiding this comment

Uh oh!

LeoMcA May 14, 2026

Choose a reason for hiding this comment

Uh oh!

LeoMcA May 14, 2026

Choose a reason for hiding this comment

Uh oh!

LeoMcA May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

caugner commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading