fix(docs): find image sizes for query URLs, paths with spaces and read errors

Three gaps in the image sizes from #443, found in its review:

- A src with a query or fragment (`/a.png?v=2`) missed its size; the
  lookup now uses the path.
- The public directory came from `URL.pathname`, which keeps `%20` for a
  space, so a checkout path with a space found no images. It now comes
  from `import.meta.dirname`.
- Any error while reading the images was swallowed, so the build could
  emit images without sizes. Only a missing directory is skipped now.

Author: erkamyaman

apps/docs/image-sizes.spec.ts

@@ -1,4 +1,4 @@
-import {mkdirSync, mkdtempSync, writeFileSync} from 'node:fs';
+import {mkdirSync, mkdtempSync, symlinkSync, writeFileSync} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {imageSize, readImageSizes} from './image-sizes';
@@ -42,6 +42,22 @@ describe('imageSize', () => {
 });
 
 describe('readImageSizes', () => {
+  it('reads a directory whose path has a space', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'image sizes '));
+    writeFileSync(join(dir, 'a.png'), png(2, 1));
+    expect(readImageSizes(dir)).toEqual({'/a.png': [2, 1]});
+  });
+
+  it('returns nothing when there is no public directory', () => {
+    expect(readImageSizes(join(tmpdir(), 'image-sizes-missing-dir'))).toEqual({});
+  });
+
+  it('fails when an image cannot be read, instead of leaving it out', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'image-sizes-'));
+    symlinkSync(join(dir, 'gone.png'), join(dir, 'broken.png'));
+    expect(() => readImageSizes(dir)).toThrow(/ENOENT/);
+  });
+
   it('keys the sizes by URL path', () => {
     const dir = mkdtempSync(join(tmpdir(), 'image-sizes-'));
     mkdirSync(join(dir, 'images/panel'), {recursive: true});

apps/docs/image-sizes.ts

@@ -1,4 +1,4 @@
-import {readFileSync, readdirSync, statSync} from 'node:fs';
+import {existsSync, readFileSync, readdirSync, statSync} from 'node:fs';
 import {join, relative, sep} from 'node:path';
 
 /**
@@ -9,7 +9,11 @@ import {join, relative, sep} from 'node:path';
  */
 export type ImageSizes = Record<string, [number, number]>;
 
-/** The sizes of the PNG and JPEG files under `dir`, keyed by their URL path. */
+/**
+ * The sizes of the PNG and JPEG files under `dir`, keyed by their URL path.
+ * A missing `dir` gives none; a file that cannot be read fails the build
+ * rather than leaving its image without a size.
+ */
 export function readImageSizes(dir: string): ImageSizes {
   const sizes: ImageSizes = {};
   const walk = (current: string) => {
@@ -22,11 +26,7 @@ export function readImageSizes(dir: string): ImageSizes {
       }
     }
   };
-  try {
-    walk(dir);
-  } catch {
-    // no public/ directory
-  }
+  if (existsSync(dir)) walk(dir);
   return sizes;
 }
 

apps/docs/src/marked-extensions/index.ts

@@ -37,9 +37,7 @@ export async function getBuildExtensions(): Promise<MarkedExtension[]> {
   ]);
   return [
     // The pages are rendered here, so `<ngmd-image>` gets the sizes of the files in public/.
-    ...createNgmdRuntimeExtensions(
-      readImageSizes(new URL('../../public', import.meta.url).pathname),
-    ),
+    ...createNgmdRuntimeExtensions(readImageSizes(`${import.meta.dirname}/../../public`)),
     ngmdCodeImportExtension,
     ngmdCodeGroupExtension,
     ngmdCodeHighlightExtension,

apps/docs/src/marked-extensions/marked-extensions.spec.ts

@@ -25,6 +25,13 @@ describe('ngmd-image', () => {
     expect(html).toContain('<figcaption>Tom &amp; Jerry</figcaption>');
   });
 
+  it('finds the size of an image whose src has a query or fragment', () => {
+    const html = new Marked({
+      extensions: [createNgmdImageExtension({'/images/a.png': [1280, 800]})],
+    }).parse('<ngmd-image src="/images/a.png?v=2#x" alt="A"></ngmd-image>') as string;
+    expect(html).toContain('<img src="/images/a.png?v=2#x" alt="A" width="1280" height="800"');
+  });
+
   it('gives the image its width and height when its size is known', () => {
     const html = new Marked({
       extensions: [createNgmdImageExtension({'/images/a.png': [1280, 800]})],

apps/docs/src/marked-extensions/ngmd-image.ts

@@ -50,7 +50,8 @@ export function createNgmdImageExtension(sizes: NgmdImageSizes = {}) {
       const width = token.width?.trim() ?? '';
       const maxWidth = /^\d+(\.\d+)?$/.test(width) ? `${width}px` : width;
       const style = maxWidth ? ` style="max-width: ${escapeHtml(maxWidth)}"` : '';
-      const size = sizes[token.src];
+      // A query or fragment (`/a.png?v=2`) still names the file `/a.png`.
+      const size = sizes[token.src.split(/[?#]/)[0]];
       const dimensions = size ? ` width="${size[0]}" height="${size[1]}"` : '';
       const caption = token.caption ? `<figcaption>${escapeHtml(token.caption)}</figcaption>` : '';
       return `<figure class="ngmd-image"${style}><img src="${escapeHtml(token.src)}" alt="${escapeHtml(token.alt)}"${dimensions} loading="lazy" decoding="async">${caption}</figure>`;