Publish usable source maps for production documentation bundles

[reakaleek]

Problem

Lighthouse reports missing or unreachable source maps for large first-party JavaScript bundles, including:

• docs/_static/main.js → main.js.map returns 404
• NavigationSearchComponent.*.js maps return 404
• VersionDropdown, FullPageSearch, Diagnostics, AskAi, and other generated chunk maps return 404

Parcel emits source map references, but src/Elastic.Documentation.Site/Elastic.Documentation.Site.csproj embeds *.js.map and *.css.map only when $(Configuration) == Debug. Release JavaScript therefore advertises maps that are not deployed.

This does not directly reduce runtime work, but it prevents Lighthouse and production debugging tooling from attributing large tasks and forced reflows to source modules.

Relevant code

• src/Elastic.Documentation.Site/Elastic.Documentation.Site.csproj (EmbedGeneratedAssets)
• src/tooling/docs-builder/Http/StaticWebHost.cs (already maps .map to application/json)
• Parcel production build configuration under src/Elastic.Documentation.Site/

Proposed implementation

Choose and implement one consistent production policy:

1. Preferred: publish generated .js.map/.css.map resources in Release output and verify hashed maps are copied with their bundles; or
2. If public source maps are intentionally prohibited, configure the Release build to omit sourceMappingURL references so bundles do not advertise guaranteed 404s, and document the loss of production attribution.

Before publishing maps, confirm the maps contain no embedded secrets or generated private content. Source code disclosure should be an explicit accepted trade-off, not accidental.

Acceptance criteria

• Release bundles no longer reference source maps that return 404.
• If maps are published, every generated map is deployed with the corresponding hashed asset and served as JSON with appropriate caching.
• Old hashed map cleanup remains aligned with old hashed JS/CSS cleanup.
• A Release build test or artifact assertion covers the selected policy.
• Lighthouse no longer reports missing maps for docs-builder-owned bundles.
• The external https://www.elastic.co/elastic-nav.js map remains explicitly out of scope.