feat(): add default-export-loader util

Author: Karnaukhov-kh

packages/angular-mcp-server/src/lib/tools/ds/component/utils/deprecated-css-helpers.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import { resolveCrossPlatformPath } from '../../shared/utils/cross-platform-path.js';
+import { loadDefaultExport } from '@push-based/utils';
 
 export interface DeprecatedCssComponent {
   componentName: string;
@@ -31,9 +32,8 @@ export async function getDeprecatedCssClasses(
     throw new Error(`File not found at deprecatedCssClassesPath: ${absPath}`);
   }
 
-  const module = await import(absPath);
-
-  const dsComponents = module.default;
+  const dsComponents =
+    await loadDefaultExport<DeprecatedCssComponent[]>(absPath);
 
   if (!Array.isArray(dsComponents)) {
     throw new Error('Invalid export: expected dsComponents to be an array');

packages/angular-mcp-server/src/lib/validation/ds-components-file-loader.validation.ts

@@ -1,11 +1,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import {
   DsComponentsArraySchema,
   DsComponentSchema,
 } from './ds-components.schema.js';
 import { z } from 'zod';
+import { loadDefaultExport } from '@push-based/utils';
 
 export type DsComponent = z.infer<typeof DsComponentSchema>;
 export type DsComponentsArray = z.infer<typeof DsComponentsArraySchema>;
@@ -65,10 +65,7 @@ export async function loadAndValidateDsComponentsFile(
   }
 
   try {
-    const fileUrl = pathToFileURL(absPath).toString();
-    const module = await import(fileUrl);
-
-    const rawData = module.default;
+    const rawData = await loadDefaultExport(absPath);
 
     return validateDsComponentsArray(rawData);
   } catch (ctx) {

packages/angular-mcp-server/src/lib/validation/ds-components-file.validation.ts

@@ -1,7 +1,7 @@
 import * as path from 'path';
-import { pathToFileURL } from 'url';
 import { AngularMcpServerOptions } from './angular-mcp-server-options.schema.js';
 import { DsComponentsArraySchema } from './ds-components.schema.js';
+import { loadDefaultExport } from '@push-based/utils';
 
 export async function validateDeprecatedCssClassesFile(
   config: AngularMcpServerOptions,
@@ -11,22 +11,7 @@ export async function validateDeprecatedCssClassesFile(
     config.ds.deprecatedCssClassesPath,
   );
 
-  let dsComponents;
-  try {
-    const fileUrl = pathToFileURL(deprecatedCssClassesAbsPath).toString();
-    const module = await import(fileUrl);
-
-    dsComponents = module.default;
-  } catch (ctx) {
-    throw new Error(
-      `Failed to load deprecated CSS classes configuration file: ${deprecatedCssClassesAbsPath}\n\n` +
-        `Possible causes:\n` +
-        `- File does not exist\n` +
-        `- Invalid JavaScript syntax\n` +
-        `- File permission issues\n\n` +
-        `Original error: ${ctx}`,
-    );
-  }
+  const dsComponents = await loadDefaultExport(deprecatedCssClassesAbsPath);
 
   const validation = DsComponentsArraySchema.safeParse(dsComponents);
   if (!validation.success) {

packages/shared/utils/src/index.ts

@@ -3,3 +3,4 @@ export * from './lib/execute-process.js';
 export * from './lib/logging.js';
 export * from './lib/file/find-in-file.js';
 export * from './lib/file/file.resolver.js';
+export * from './lib/file/default-export-loader.js';

packages/shared/utils/src/lib/file/default-export-loader.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadDefaultExport } from './default-export-loader.js';
+
+describe('loadDefaultExport', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(
+      tmpdir(),
+      `test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  const createFile = (name: string, content: string) => {
+    const path = join(testDir, name);
+    writeFileSync(path, content, 'utf-8');
+    return path;
+  };
+
+  describe('Success Cases', () => {
+    it.each([
+      {
+        type: 'array',
+        content: '[{name: "test"}]',
+        expected: [{ name: 'test' }],
+      },
+      {
+        type: 'object',
+        content: '{version: "1.0"}',
+        expected: { version: '1.0' },
+      },
+      { type: 'string', content: '"test"', expected: 'test' },
+      { type: 'null', content: 'null', expected: null },
+      { type: 'boolean', content: 'false', expected: false },
+      { type: 'undefined', content: 'undefined', expected: undefined },
+    ])('should load $type default export', async ({ content, expected }) => {
+      const path = createFile('test.mjs', `export default ${content};`);
+      expect(await loadDefaultExport(path)).toEqual(expected);
+    });
+  });
+
+  describe('Error Cases - No Default Export', () => {
+    it.each([
+      {
+        desc: 'named exports only',
+        content: 'export const a = 1; export const b = 2;',
+        exports: 'a, b',
+      },
+      { desc: 'empty module', content: '', exports: 'none' },
+      { desc: 'comments only', content: '// comment', exports: 'none' },
+      {
+        desc: 'function exports',
+        content: 'export function fn() {}',
+        exports: 'fn',
+      },
+    ])('should throw error for $desc', async ({ content, exports }) => {
+      const path = createFile('test.mjs', content);
+      await expect(loadDefaultExport(path)).rejects.toThrow(
+        `No default export found in module. Expected ES Module format:\nexport default [...]\n\nAvailable exports: ${exports}`,
+      );
+    });
+  });
+
+  describe('Error Cases - File System', () => {
+    it('should throw error when file does not exist', async () => {
+      const path = join(testDir, 'missing.mjs');
+      await expect(loadDefaultExport(path)).rejects.toThrow(
+        `Failed to load module from ${path}`,
+      );
+    });
+
+    it('should throw error when file has syntax errors', async () => {
+      const path = createFile(
+        'syntax.mjs',
+        'export default { invalid: syntax }',
+      );
+      await expect(loadDefaultExport(path)).rejects.toThrow(
+        `Failed to load module from ${path}`,
+      );
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should work with TypeScript generics', async () => {
+      interface Config {
+        name: string;
+      }
+      const path = createFile('typed.mjs', 'export default [{name: "test"}];');
+      const result = await loadDefaultExport<Config[]>(path);
+      expect(result).toEqual([{ name: 'test' }]);
+    });
+
+    it('should handle mixed exports (prefers default)', async () => {
+      const path = createFile(
+        'mixed.mjs',
+        'export const named = "n"; export default "d";',
+      );
+      expect(await loadDefaultExport<string>(path)).toBe('d');
+    });
+
+    it('should handle complex nested structures', async () => {
+      const path = createFile(
+        'complex.mjs',
+        `
+        export default {
+          data: [{ name: 'test', meta: { date: new Date('2024-01-01') } }],
+          version: '1.0'
+        };
+      `,
+      );
+      const result = await loadDefaultExport(path);
+      expect(result).toMatchObject({
+        data: [{ name: 'test', meta: { date: expect.any(Date) } }],
+        version: '1.0',
+      });
+    });
+  });
+});

packages/shared/utils/src/lib/file/default-export-loader.ts

@@ -0,0 +1,42 @@
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Dynamically imports an ES Module and extracts the default export.
+ *
+ * @param filePath - Absolute path to the ES module file to import
+ * @returns The default export from the module
+ * @throws Error if the module cannot be loaded or has no default export
+ *
+ * @example
+ * ```typescript
+ * const data = await loadDefaultExport('/path/to/config.js');
+ * ```
+ */
+export async function loadDefaultExport<T = unknown>(
+  filePath: string,
+): Promise<T> {
+  try {
+    const fileUrl = pathToFileURL(filePath).toString();
+    const module = await import(fileUrl);
+
+    if (!('default' in module)) {
+      throw new Error(
+        `No default export found in module. Expected ES Module format:\n` +
+          `export default [...]\n\n` +
+          `Available exports: ${Object.keys(module).join(', ') || 'none'}`,
+      );
+    }
+
+    return module.default;
+  } catch (ctx) {
+    if (
+      ctx instanceof Error &&
+      ctx.message.includes('No default export found')
+    ) {
+      throw ctx;
+    }
+    throw new Error(
+      `Failed to load module from ${filePath}: ${ctx instanceof Error ? ctx.message : String(ctx)}`,
+    );
+  }
+}