feat: Add helper to write documentation files (#67)

Author: just-boris

package.json

@@ -15,6 +15,9 @@
     "*.js",
     "*.d.ts"
   ],
+  "exports": {
+    ".": "./index.js"
+  },
   "scripts": {
     "lint": "eslint --ignore-path .gitignore --ext js,ts,tsx .",
     "prebuild": "rimraf lib",

src/components/index.ts

@@ -1,5 +1,6 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import fs from 'node:fs';
 import { pascalCase } from 'change-case';
 import pathe from 'pathe';
 import { matcher } from 'micromatch';
@@ -21,46 +22,65 @@ export interface DocumenterOptions {
   extraExports?: Record<string, Array<string>>;
 }
 
+export interface WriteOptions {
+  outDir: string;
+}
+
+export function writeComponentsDocumentation({ outDir, ...options }: WriteOptions & DocumenterOptions): void {
+  const definitions = documentComponents(options);
+  fs.mkdirSync(outDir, { recursive: true });
+  for (const definition of definitions) {
+    fs.writeFileSync(
+      pathe.join(outDir, definition.dashCaseName + '.js'),
+      `module.exports = ${JSON.stringify(definition, null, 2)};`
+    );
+  }
+  const indexContent = `module.exports = {
+    ${definitions
+      .map(definition => `${JSON.stringify(definition.dashCaseName)}:require('./${definition.dashCaseName}')`)
+      .join(',\n')}
+  }`;
+  fs.writeFileSync(pathe.join(outDir, 'index.js'), indexContent);
+  fs.copyFileSync(require.resolve('./interfaces.d.ts'), pathe.join(outDir, 'interfaces.d.ts'));
+  fs.writeFileSync(
+    pathe.join(outDir, 'index.d.ts'),
+    `import { ComponentDefinition } from './interfaces';
+const definitions: Record<string, ComponentDefinition>;
+export default definitions;
+`
+  );
+}
+
 export function documentComponents(options: DocumenterOptions): Array<ComponentDefinition> {
   const program = bootstrapTypescriptProject(options.tsconfigPath);
   const checker = program.getTypeChecker();
 
   const isMatch = matcher(pathe.resolve(options.publicFilesGlob));
 
-  return program
-    .getSourceFiles()
-    .filter(file => isMatch(file.fileName))
-    .map(sourceFile => {
-      const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
-      const { name, dashCaseName } = componentNameFromPath(sourceFile.fileName);
+  const sourceFiles = program.getSourceFiles().filter(file => isMatch(file.fileName));
+
+  if (sourceFiles.length === 0) {
+    throw new Error(`No files found matching ${options.publicFilesGlob}`);
+  }
+
+  return sourceFiles.map(sourceFile => {
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const { name, dashCaseName } = componentNameFromPath(sourceFile.fileName);
 
-      // istanbul ignore next
-      if (!moduleSymbol) {
-        throw new Error(`Unable to resolve module: ${sourceFile.fileName}`);
-      }
-      const exportSymbols = checker.getExportsOfModule(moduleSymbol);
-      const { propsSymbol, componentSymbol } = extractExports(
-        name,
-        exportSymbols,
-        checker,
-        options?.extraExports ?? {}
-      );
-      const props = extractProps(propsSymbol, checker);
-      const functions = extractFunctions(propsSymbol, checker);
-      const defaultValues = extractDefaultValues(componentSymbol, checker);
-      const componentDescription = getDescription(
-        componentSymbol.getDocumentationComment(checker),
-        extractDeclaration(componentSymbol)
-      );
+    // istanbul ignore next
+    if (!moduleSymbol) {
+      throw new Error(`Unable to resolve module: ${sourceFile.fileName}`);
+    }
+    const exportSymbols = checker.getExportsOfModule(moduleSymbol);
+    const { propsSymbol, componentSymbol } = extractExports(name, exportSymbols, checker, options?.extraExports ?? {});
+    const props = extractProps(propsSymbol, checker);
+    const functions = extractFunctions(propsSymbol, checker);
+    const defaultValues = extractDefaultValues(componentSymbol, checker);
+    const componentDescription = getDescription(
+      componentSymbol.getDocumentationComment(checker),
+      extractDeclaration(componentSymbol)
+    );
 
-      return buildComponentDefinition(
-        name,
-        dashCaseName,
-        props,
-        functions,
-        defaultValues,
-        componentDescription,
-        checker
-      );
-    });
+    return buildComponentDefinition(name, dashCaseName, props, functions, defaultValues, componentDescription, checker);
+  });
 }

src/index.ts

@@ -1,5 +1,5 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 export * from './components/interfaces';
-export { documentComponents } from './components';
+export { documentComponents, writeComponentsDocumentation } from './components';
 export { documentTestUtils } from './test-utils';

test/components/errors.test.ts

@@ -7,6 +7,16 @@ test('should throw in case of configuration errors', () => {
   expect(() => buildProject('errors-config')).toThrow('Failed to parse tsconfig.json');
 });
 
+test('should throw if tsconfig is not found', () => {
+  expect(() => buildProject('fixture-does-not-exist')).toThrow('Failed to read tsconfig.json');
+});
+
+test('should throw if no components in the output', () => {
+  expect(() => buildProject('simple', { publicFilesGlob: 'does-not-exist' })).toThrow(
+    'No files found matching does-not-exist'
+  );
+});
+
 test('should throw in case of type errors', () => {
   expect(() => buildProject('errors-types')).toThrow('Compilation failed');
 });

test/components/test-helpers.ts

@@ -1,5 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import fs from 'node:fs';
+import os from 'node:os';
+import pathe from 'pathe';
 import ts from 'typescript';
 import { ProjectReflection } from 'typedoc';
 import { documentComponents, documentTestUtils } from '../../src';
@@ -9,12 +12,16 @@ import { DocumenterOptions } from '../../src/components';
 
 export function buildProject(name: string, options?: Partial<DocumenterOptions>) {
   return documentComponents({
-    tsconfigPath: require.resolve(`../../fixtures/components/${name}/tsconfig.json`),
+    tsconfigPath: pathe.resolve(`fixtures/components/${name}/tsconfig.json`),
     publicFilesGlob: `fixtures/components/${name}/*/index.tsx`,
     ...options,
   });
 }
 
+export function getTemporaryDir() {
+  return fs.mkdtempSync(pathe.join(os.tmpdir(), 'documenter-'));
+}
+
 export function buildTestUtilsProject(name: string, testGlob?: string): TestUtilsDoc[] {
   return documentTestUtils(
     {

test/components/writer.test.ts

@@ -0,0 +1,25 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { expect, test } from 'vitest';
+import fs from 'node:fs';
+import pathe from 'pathe';
+import { getTemporaryDir } from './test-helpers';
+// must use compiled artifacts, because the code relies on generated files
+import { writeComponentsDocumentation } from '../../lib';
+
+test('should write documentation files into the outDir', async () => {
+  const outDir = getTemporaryDir();
+  expect(fs.readdirSync(outDir)).toHaveLength(0);
+
+  writeComponentsDocumentation({
+    tsconfigPath: pathe.resolve('fixtures/components/simple/tsconfig.json'),
+    publicFilesGlob: 'fixtures/components/simple/*/index.tsx',
+    outDir,
+  });
+
+  expect(fs.readdirSync(outDir)).toEqual(['index.d.ts', 'index.js', 'interfaces.d.ts', 'simple.js']);
+  const { default: definitions } = await import(pathe.join(outDir, 'index.js'));
+  expect(definitions).toEqual({
+    simple: expect.objectContaining({ name: 'Simple', dashCaseName: 'simple' }),
+  });
+});

tsconfig.json

@@ -9,7 +9,9 @@
     "strict": true,
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true
+    "forceConsistentCasingInFileNames": true,
+    "sourceMap": true,
+    "inlineSources": true
   },
   "include": ["src"]
 }

vite.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
     coverage: {
       enabled: process.env.CI === 'true',
       provider: 'v8',
-      include: ['src/**'],
+      include: ['src/**', 'lib/**'],
     },
   },
 });