fix: add file-context to generator parse errors

src/generators/ast/__tests__/generate.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { describe, it, mock } from 'node:test';
+
+// Mock dependencies
+const mockReadFile = mock.fn();
+mock.module('node:fs/promises', {
+  namedExports: { readFile: mockReadFile },
+});
+
+// Mock other internal modules as needed
+// From src/generators/ast/__tests__/ to src/utils/configuration/index.mjs is ../../../utils/configuration/index.mjs
+mock.module('../../../utils/configuration/index.mjs', {
+  defaultExport: () => ({ ast: { input: 'docs/*.md' } }),
+});
+
+const { processChunk } = await import('../generate.mjs');
+
+describe('ast/generate.mjs error handling', () => {
+  it('should wrap readFile errors with filename, original message, and cause', async () => {
+    const error = new Error('FS_ERROR');
+    mockReadFile.mock.mockImplementation(async () => {
+      throw error;
+    });
+
+    const inputSlice = ['test.md'];
+    const itemIndices = [0];
+
+    await assert.rejects(
+      async () => await processChunk(inputSlice, itemIndices),
+      {
+        name: 'Error',
+        message: 'Failed to process test.md: FS_ERROR',
+        cause: error,
+      }
+    );
+  });
+});

src/generators/ast/generate.mjs

@@ -25,19 +25,24 @@ export async function processChunk(inputSlice, itemIndices) {
   const results = [];
 
   for (const path of filePaths) {
-    const content = await readFile(path, 'utf-8');
-    const vfile = new VFile({
-      path,
-      value: content.replace(
-        QUERIES.stabilityIndexPrefix,
-        match => `[${match}](${STABILITY_INDEX_URL})`
-      ),
-    });
-
-    results.push({
-      tree: remarkProcessor.parse(vfile),
-      file: { stem: vfile.stem, basename: vfile.basename },
-    });
+    try {
+      const content = await readFile(path, 'utf-8');
+      const vfile = new VFile({
+        path,
+        value: content.replace(
+          QUERIES.stabilityIndexPrefix,
+          match => `[${match}](${STABILITY_INDEX_URL})`
+        ),
+      });
+
+      results.push({
+        tree: remarkProcessor.parse(vfile),
+        file: { stem: vfile.stem, basename: vfile.basename, path },
+      });
+    } catch (err) {
+      const message = `Failed to process ${path}: ${err.message ?? err}`;
+      throw new Error(message, { cause: err });
+    }
   }
 
   return results;

src/generators/metadata/__tests__/generate.test.mjs

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { describe, it, mock } from 'node:test';
+
+// Mock dependencies
+const mockParseApiDoc = mock.fn();
+mock.module('../utils/parse.mjs', {
+  namedExports: { parseApiDoc: mockParseApiDoc },
+});
+
+// Mock configuration and URL utils
+// From src/generators/metadata/__tests__/ to src/utils/ is ../../../utils/
+mock.module('../../../utils/configuration/index.mjs', {
+  defaultExport: () => ({ metadata: { typeMap: 'typeMap.json' } }),
+});
+mock.module('../../../utils/url.mjs', {
+  namedExports: { importFromURL: async () => ({}) },
+});
+
+const { processChunk } = await import('../generate.mjs');
+
+describe('metadata/generate.mjs error handling', () => {
+  it('should wrap parsing errors with filename, original message, and cause', async () => {
+    const error = new Error('PARSE_ERROR');
+    mockParseApiDoc.mock.mockImplementation(() => {
+      throw error;
+    });
+
+    const fullInput = [{ file: { path: 'docs/api/fs.md', basename: 'fs.md' } }];
+    const itemIndices = [0];
+
+    await assert.rejects(
+      async () => await processChunk(fullInput, itemIndices, {}),
+      {
+        name: 'Error',
+        message: 'Failed to parse metadata for docs/api/fs.md: PARSE_ERROR',
+        cause: error,
+      }
+    );
+  });
+
+  it('should fallback to basename or unknown if path is missing', async () => {
+    const error = new Error('PARSE_ERROR');
+    mockParseApiDoc.mock.mockImplementation(() => {
+      throw error;
+    });
+
+    const fullInput = [{ file: { basename: 'fs.md' } }];
+
+    await assert.rejects(async () => await processChunk(fullInput, [0], {}), {
+      name: 'Error',
+      message: 'Failed to parse metadata for fs.md: PARSE_ERROR',
+      cause: error,
+    });
+  });
+});

src/generators/metadata/generate.mjs

@@ -14,7 +14,15 @@ export async function processChunk(fullInput, itemIndices, typeMap) {
   const results = [];
 
   for (const idx of itemIndices) {
-    results.push(...parseApiDoc(fullInput[idx], typeMap));
+    const input = fullInput[idx];
+    try {
+      results.push(...parseApiDoc(input, typeMap));
+    } catch (err) {
+      const path =
+        input?.file?.path ?? input?.file?.basename ?? '<unknown file>';
+      const message = `Failed to parse metadata for ${path}: ${err.message ?? err}`;
+      throw new Error(message, { cause: err });
+    }
   }
 
   return results;