Allow classes to be ignored via JSON file, Closes #40

Author: rubensworks

README.md

@@ -103,16 +103,31 @@ Generates component file for a package
 Usage:
   componentsjs-generator
   Options:
-       -p path/to/package   The directory of the package to look in, defaults to working directory
-       -s lib               Relative path to directory containing source files, defaults to 'lib'
-       -c components        Relative path to directory that will contain components files, defaults to 'components'
-       -e jsonld            Extension for components files (without .), defaults to 'jsonld'
-       --help               Show information about this command
+       -p path/to/package      The directory of the package to look in, defaults to working directory
+       -s lib                  Relative path to directory containing source files, defaults to 'lib'
+       -c components           Relative path to directory that will contain components files, defaults to 'components'
+       -e jsonld               Extension for components files (without .), defaults to 'jsonld'
+       -i ignore-classes.json  Relative path to an optional file with class names to ignore
+       --help                  Show information about this command
 ```
 
 **Note:** This generator will read `.d.ts` files,
 so it is important that you invoke the TypeScript compiler (`tsc`) _before_ using this tool.
 
+### Ignoring classes
+
+If you don't want components to be generated for certain classes,
+then you can pass a JSON file to the `-i` option containing an array of class names to skip.
+
+For example, invoking `componentsjs-generator -i ignore-classes.json` will skip `BadClass` if the contents of `ignore-classes.json` are:
+```json
+[
+  "BadClass"
+]
+```
+
+If you are looking for a way to ignore parameters, see the `@ignored` argument tag below.
+
 ## How it works
 
 For each exported TypeScript class,

bin/componentsjs-generator.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import * as fs from 'fs';
 import * as minimist from 'minimist';
 import { Generator } from '../lib/generate/Generator';
 import { ResolutionContext } from '../lib/resolution/ResolutionContext';
@@ -8,11 +9,12 @@ function showHelp(): void {
 Usage:
   componentsjs-generator
   Options:
-       -p path/to/package   The directory of the package to look in, defaults to working directory
-       -s lib               Relative path to directory containing source files, defaults to 'lib'
-       -c components        Relative path to directory that will contain components files, defaults to 'components'
-       -e jsonld            Extension for components files (without .), defaults to 'jsonld'
-       --help               Show information about this command
+       -p path/to/package      The directory of the package to look in, defaults to working directory
+       -s lib                  Relative path to directory containing source files, defaults to 'lib'
+       -c components           Relative path to directory that will contain components files, defaults to 'components'
+       -e jsonld               Extension for components files (without .), defaults to 'jsonld'
+       -i ignore-classes.json  Relative path to an optional file with class names to ignore
+       --help                  Show information about this command
 `);
   process.exit(1);
 }
@@ -30,6 +32,13 @@ if (args.help) {
     },
     fileExtension: args.e || 'jsonld',
     level: args.l || 'info',
+    ignoreClasses: args.i ?
+      // eslint-disable-next-line no-sync
+      JSON.parse(fs.readFileSync(args.i, 'utf8')).reduce((acc: Record<string, boolean>, entry: string) => {
+        acc[entry] = true;
+        return acc;
+      }, {}) :
+      [],
   });
   generator
     .generateComponents()

lib/generate/Generator.ts

@@ -18,11 +18,13 @@ export class Generator {
   private readonly resolutionContext: ResolutionContext;
   private readonly pathDestination: PathDestinationDefinition;
   private readonly fileExtension: string;
+  private readonly ignoreClasses: Record<string, boolean>;
 
   public constructor(args: GeneratorArgs) {
     this.resolutionContext = args.resolutionContext;
     this.pathDestination = args.pathDestination;
     this.fileExtension = args.fileExtension;
+    this.ignoreClasses = args.ignoreClasses;
   }
 
   public async generateComponents(): Promise<void> {
@@ -32,7 +34,7 @@ export class Generator {
 
     const classLoader = new ClassLoader({ resolutionContext: this.resolutionContext });
     const classFinder = new ClassFinder({ classLoader });
-    const classIndexer = new ClassIndexer({ classLoader, classFinder });
+    const classIndexer = new ClassIndexer({ classLoader, classFinder, ignoreClasses: this.ignoreClasses });
 
     // Find all relevant classes
     const packageExports = await classFinder.getPackageExports(packageMetadata.typesPath);
@@ -77,4 +79,5 @@ export interface GeneratorArgs {
   pathDestination: PathDestinationDefinition;
   fileExtension: string;
   level: string;
+  ignoreClasses: Record<string, boolean>;
 }

lib/parse/ClassIndexer.ts

@@ -6,19 +6,14 @@ import type { ClassIndex, ClassLoaded, ClassReference } from './ClassIndex';
 import type { ClassLoader } from './ClassLoader';
 
 export class ClassIndexer {
-  /**
-   * Errors that do not require an import, and are assumed to be known globally.
-   */
-  private static readonly SUPERCLASS_BLACKLIST: Record<string, boolean> = {
-    Error: true,
-  };
-
   private readonly classLoader: ClassLoader;
   private readonly classFinder: ClassFinder;
+  private readonly ignoreClasses: Record<string, boolean>;
 
   public constructor(args: ClassIndexerArgs) {
     this.classLoader = args.classLoader;
     this.classFinder = args.classFinder;
+    this.ignoreClasses = args.ignoreClasses;
   }
 
   /**
@@ -29,7 +24,9 @@ export class ClassIndexer {
     const classIndex: ClassIndex<ClassLoaded> = {};
 
     for (const [ className, classReference ] of Object.entries(classReferences)) {
-      classIndex[className] = await this.loadClassChain(classReference);
+      if (!(className in this.ignoreClasses)) {
+        classIndex[className] = await this.loadClassChain(classReference);
+      }
     }
 
     return classIndex;
@@ -47,11 +44,15 @@ export class ClassIndexer {
     // If the class has a super class, load it recursively
     const superClassName = this.classLoader.getSuperClassName(classReferenceLoaded.declaration,
       classReferenceLoaded.fileName);
-    if (superClassName && !(superClassName in ClassIndexer.SUPERCLASS_BLACKLIST)) {
-      classReferenceLoaded.superClass = await this.loadClassChain({
-        localName: superClassName,
-        fileName: classReferenceLoaded.fileName,
-      });
+    if (superClassName && !(superClassName in this.ignoreClasses)) {
+      try {
+        classReferenceLoaded.superClass = await this.loadClassChain({
+          localName: superClassName,
+          fileName: classReferenceLoaded.fileName,
+        });
+      } catch (error: unknown) {
+        throw new Error(`Failed to load super class ${superClassName} of ${classReference.localName} in ${classReference.fileName}:\n${(<Error> error).message}`);
+      }
     }
 
     return classReferenceLoaded;
@@ -61,4 +62,5 @@ export class ClassIndexer {
 export interface ClassIndexerArgs {
   classLoader: ClassLoader;
   classFinder: ClassFinder;
+  ignoreClasses: Record<string, boolean>;
 }

lib/parse/ClassLoader.ts

@@ -65,7 +65,14 @@ export class ClassLoader {
    */
   public async loadClassDeclaration<CI extends boolean>(classReference: ClassReference, considerInterfaces: CI):
   Promise<CI extends true ? (ClassLoaded | InterfaceLoaded) : ClassLoaded> {
-    const ast = await this.resolutionContext.parseTypescriptFile(classReference.fileName);
+    // Load the class as an AST
+    let ast;
+    try {
+      ast = await this.resolutionContext.parseTypescriptFile(classReference.fileName);
+    } catch (error: unknown) {
+      throw new Error(`Could not load ${considerInterfaces ? 'class or interface' : 'class'} ${classReference.localName} from ${classReference.fileName}:\n${(<Error> error).message}`);
+    }
+
     const {
       exportedClasses,
       exportedInterfaces,
@@ -188,6 +195,16 @@ export class ClassLoader {
     return this.getClassElements(fileName, ast);
   }
 
+  /**
+   * Convert the given import path to an absolute file path.
+   * @param currentFilePath Absolute path to a file in which the import path occurs.
+   * @param importPath Possibly relative path that is being imported.
+   */
+  public importTargetToAbsolutePath(currentFilePath: string, importPath: string): string {
+    // TODO: Add support for imports from other packages (#39)
+    return Path.join(Path.dirname(currentFilePath), importPath);
+  }
+
   /**
    * Get all class elements in a file.
    * @param fileName A file path.
@@ -223,7 +240,7 @@ export class ClassLoader {
           for (const specifier of statement.specifiers) {
             exportedImportedElements[specifier.exported.name] = {
               localName: specifier.local.name,
-              fileName: Path.join(Path.dirname(fileName), statement.source.value),
+              fileName: this.importTargetToAbsolutePath(fileName, statement.source.value),
             };
           }
         } else {
@@ -237,7 +254,7 @@ export class ClassLoader {
         if (statement.source &&
           statement.source.type === AST_NODE_TYPES.Literal &&
           typeof statement.source.value === 'string') {
-          exportedImportedAll.push(Path.join(Path.dirname(fileName), statement.source.value));
+          exportedImportedAll.push(this.importTargetToAbsolutePath(fileName, statement.source.value));
         }
       } else if (statement.type === AST_NODE_TYPES.ClassDeclaration && statement.id) {
         // Form: `declare class A {}`
@@ -253,7 +270,7 @@ export class ClassLoader {
           if (specifier.type === AST_NODE_TYPES.ImportSpecifier) {
             importedElements[specifier.local.name] = {
               localName: specifier.imported.name,
-              fileName: Path.join(Path.dirname(fileName), statement.source.value),
+              fileName: this.importTargetToAbsolutePath(fileName, statement.source.value),
             };
           }
         }

test/parse/ClassIndexer.test.ts

@@ -5,14 +5,16 @@ import { ResolutionContextMocked } from '../ResolutionContextMocked';
 
 describe('ClassIndexer', () => {
   const resolutionContext = new ResolutionContextMocked({});
+  let ignoreClasses: Record<string, boolean>;
   let classLoader: ClassLoader;
   let classFinder: ClassFinder;
   let indexer: ClassIndexer;
 
   beforeEach(() => {
+    ignoreClasses = {};
     classLoader = new ClassLoader({ resolutionContext });
     classFinder = new ClassFinder({ classLoader });
-    indexer = new ClassIndexer({ classLoader, classFinder });
+    indexer = new ClassIndexer({ classLoader, classFinder, ignoreClasses });
   });
 
   describe('createIndex', () => {
@@ -42,6 +44,26 @@ describe('ClassIndexer', () => {
       });
     });
 
+    it('should throw on a direct class reference to an unknown file', async() => {
+      await expect(indexer.createIndex({
+        Unknown: {
+          localName: 'Unknown',
+          fileName: 'unknown',
+        },
+      })).rejects.toThrow(new Error(`Could not load class Unknown from unknown:
+Could not find mocked path for unknown.d.ts`));
+    });
+
+    it('should not throw on a direct class reference to an unknown file when it is ignored', async() => {
+      ignoreClasses.Unknown = true;
+      expect(await indexer.createIndex({
+        Unknown: {
+          localName: 'Unknown',
+          fileName: 'unknown',
+        },
+      })).toMatchObject({});
+    });
+
     it('should load an indirect class reference', async() => {
       resolutionContext.contentsOverrides = {
         'x.d.ts': `export * from './y'`,
@@ -285,10 +307,22 @@ export * from './Z'
         });
     });
 
-    it('for an exported class extending Error should ignore the link', async() => {
+    it('for an exported class extending an unknown class should error', async() => {
+      resolutionContext.contentsOverrides = {
+        'file.d.ts': `
+export class A extends Unknown{}
+`,
+      };
+      await expect(indexer.loadClassChain({ localName: 'A', fileName: 'file' }))
+        .rejects.toThrow(new Error(`Failed to load super class Unknown of A in file:
+Could not load class Unknown from file`));
+    });
+
+    it('for an exported class extending an unknown class should not error if it is ignored', async() => {
+      ignoreClasses.Unknown = true;
       resolutionContext.contentsOverrides = {
         'file.d.ts': `
-export class A extends Error{}
+export class A extends Unknown{}
 `,
       };
       expect(await indexer.loadClassChain({ localName: 'A', fileName: 'file' }))

test/parse/ConstructorLoader.test.ts

@@ -15,6 +15,7 @@ describe('ConstructorLoader', () => {
     classIndexer = new ClassIndexer({
       classLoader,
       classFinder: new ClassFinder({ classLoader }),
+      ignoreClasses: {},
     });
   });