Ensure Dart Sass file:// sources use relative paths

shared/tasks/assets.mjs

@@ -1,5 +1,5 @@
 import { mkdir, writeFile } from 'fs/promises'
-import { dirname } from 'path'
+import { dirname, relative } from 'path'
 
 /**
  * Write asset helper
@@ -14,15 +14,27 @@ export async function write (filePath, result) {
   const writeTasks = []
 
   // Files to write
+  /** @type {SourceMap | undefined} */
+  const map = result.map ? JSON.parse(result.map.toString()) : undefined
   const code = 'css' in result ? result.css : result.code
-  const map = result.map?.toString()
 
   // 1. Write code (example.js)
   writeTasks.push(writeFile(filePath, code))
 
   // 2. Write source map (example.js.map)
-  if (map) {
-    writeTasks.push(writeFile(`${filePath}.map`, map))
+  if (map && 'sources' in map) {
+    map.sources = map.sources
+
+      /**
+       * Make source file:// paths relative (e.g. for Dart Sass)
+       * {@link https://sass-lang.com/documentation/js-api/interfaces/CompileResult#sourceMap}
+       */
+      .map((path) => path.startsWith('file://')
+        ? relative(dirname(filePath), new URL(path).pathname)
+        : path
+      )
+
+    writeTasks.push(writeFile(`${filePath}.map`, JSON.stringify(map)))
   }
 
   await Promise.all(writeTasks)
@@ -70,3 +82,11 @@ export async function write (filePath, result) {
  *
  * @typedef {import('rollup').OutputChunk | import('terser').MinifyOutput | import('postcss').Result} AssetOutput
  */
+
+/**
+ * Asset source maps
+ *
+ * {@link https://github.com/source-map/source-map-spec}
+ *
+ * @typedef {import('@jridgewell/source-map').DecodedSourceMap | import('@jridgewell/source-map').EncodedSourceMap} SourceMap
+ */

shared/tasks/build/dist.test.mjs

@@ -46,6 +46,21 @@ describe('dist/', () => {
     })
   })
 
+  describe('govuk-frontend-[version].min.css.map', () => {
+    let filename
+    let sourcemap
+
+    beforeAll(async () => {
+      filename = `govuk-frontend-${pkg.version}.min.css.map`
+      sourcemap = JSON.parse(await readFile(join(paths.dist, filename), 'utf8'))
+    })
+
+    it('should contain relative paths to sources', () => {
+      expect(sourcemap.sources).toContain('../src/govuk/all.scss')
+      expect(sourcemap.sources).toContain('../src/govuk/core/_govuk-frontend-version.scss')
+    })
+  })
+
   describe('govuk-frontend-ie8-[version].min.css', () => {
     let filename
     let stylesheet
@@ -64,6 +79,21 @@ describe('dist/', () => {
     })
   })
 
+  describe('govuk-frontend-ie8-[version].min.css.map', () => {
+    let filename
+    let sourcemap
+
+    beforeAll(async () => {
+      filename = `govuk-frontend-ie8-${pkg.version}.min.css.map`
+      sourcemap = JSON.parse(await readFile(join(paths.dist, filename), 'utf8'))
+    })
+
+    it('should contain relative paths to sources', () => {
+      expect(sourcemap.sources).toContain('../src/govuk/all-ie8.scss')
+      expect(sourcemap.sources).toContain('../src/govuk/core/_govuk-frontend-version.scss')
+    })
+  })
+
   describe('govuk-frontend-[version].min.js', () => {
     let filename
     let javascript
@@ -86,6 +116,21 @@ describe('dist/', () => {
     })
   })
 
+  describe('govuk-frontend-[version].min.js.map', () => {
+    let filename
+    let sourcemap
+
+    beforeAll(async () => {
+      filename = `govuk-frontend-${pkg.version}.min.js.map`
+      sourcemap = JSON.parse(await readFile(join(paths.dist, filename), 'utf8'))
+    })
+
+    it('should contain relative paths to sources', () => {
+      expect(sourcemap.sources).toContain('../src/govuk/all.mjs')
+      expect(sourcemap.sources).toContain('../src/govuk/common/govuk-frontend-version.mjs')
+    })
+  })
+
   describe('VERSION.txt', () => {
     let filename
     let version

shared/tasks/build/package.test.mjs

@@ -70,6 +70,12 @@ describe('package/', () => {
         return output
       }))
 
+      // Add Autoprefixer prefixes to all source '*.scss' files
+      .flatMap(mapPathTo(['**/*.scss'], ({ dir: requirePath, name }) => [
+        join(requirePath, `${name}.scss`),
+        join(requirePath, `${name}.scss.map`) // with source map
+      ]))
+
       // Replaces source component '*.yaml' with:
       // - `fixtures.json` fixtures for tests
       // - `macro-options.json` component options

shared/tasks/styles.mjs

@@ -43,10 +43,25 @@ export async function compileStylesheet ([modulePath, { srcPath, destPath, fileP
   let css
   let map
 
-  // Configure PostCSS
+  /**
+   * Configure PostCSS
+   *
+   * @type {import('postcss').ProcessOptions}
+   */
   const options = {
     from: moduleSrcPath,
-    to: moduleDestPath
+    to: moduleDestPath,
+
+    /**
+     * Always generate source maps for either:
+     *
+     * 1. PostCSS on Sass compiler result
+     * 2. PostCSS on Sass sources (Autoprefixer only)
+     */
+    map: {
+      annotation: true,
+      inline: false
+    }
   }
 
   // Compile Sass to CSS
@@ -79,10 +94,8 @@ export async function compileStylesheet ([modulePath, { srcPath, destPath, fileP
     }))
 
     // Pass source maps to PostCSS
-    options.map = {
-      annotation: true,
-      inline: false,
-      prev: map
+    if (typeof options.map === 'object') {
+      options.map.prev = map
     }
   }