Minor generation script improvements (#136)

Author: Shinigami92

scripts/generate-rule-files/index.ts

@@ -7,12 +7,11 @@ import dedent from 'ts-dedent';
 import type { Plugin } from './contracts';
 import { format } from './src/format';
 import { JsDocBuilder } from './src/js-doc-builder';
-import { pluginsMap } from './src/plugins-map';
+import { PLUGIN_REGISTRY } from './src/plugins-map';
 import { RuleFile } from './src/rule-file';
 
 /**
- * Generate the index.d.ts file for the plugin's rules that will re-export all
- * rules.
+ * Generate the `index.d.ts` file for the plugin's rules that will re-export all rules.
  */
 function generateRuleIndexFile(
   pluginDirectory: string,
@@ -24,14 +23,14 @@ function generateRuleIndexFile(
   );
 
   /**
-   * Build all the import statements for the rules
+   * Build all the import statements for the rules.
    */
   const rulesImports: string = generatedRules
     .map((name) => `import type { ${pascalCase(name)}Rule } from './${name}';`)
     .join('\n');
 
   /**
-   * Build the exported type that is an intersection of all the rules
+   * Build the exported type that is an intersection of all the rules.
    */
   const rulesFinalIntersection: string = generatedRules
     .map((name) => `${pascalCase(name)}Rule`)
@@ -43,7 +42,7 @@ function generateRuleIndexFile(
   `);
 
   /**
-   * Write the final index.d.ts file
+   * Write the final `index.d.ts` file.
    */
   const fileContent: string = dedent(`
     ${rulesImports}
@@ -56,7 +55,7 @@ function generateRuleIndexFile(
 }
 
 /**
- * Print a report after having generated rules files for a plugin
+ * Print a report after having generated rules files for a plugin.
  */
 function printGenerationReport(
   rules: [string, Rule.RuleModule][],
@@ -75,7 +74,7 @@ function printGenerationReport(
 }
 
 /**
- * Generate a .d.ts file for each rule in the given plugin
+ * Generate a `.d.ts` file for each rule in the given plugin.
  */
 async function generateRulesFiles(
   plugin: Plugin,
@@ -106,8 +105,7 @@ async function generateRulesFiles(
   return { failedRules };
 }
 /**
- * If it doesn't exist, create the directory that will contain the plugin's
- * rule files.
+ * If it doesn't exist, create the directory that will contain the plugin's rule files.
  */
 function createPluginDirectory(
   pluginName: string,
@@ -124,27 +122,28 @@ function createPluginDirectory(
   }
 
   mkdirSync(pluginDirectory, { mode: 0o755, recursive: true });
+
   return pluginDirectory;
 }
 
-export async function run(
-  options: {
-    plugins?: string[];
-    targetDirectory?: string;
-  } = {},
-): Promise<void> {
+export interface RunOptions {
+  plugins?: string[];
+  targetDirectory?: string;
+}
+
+export async function run(options: RunOptions = {}): Promise<void> {
   const { plugins, targetDirectory } = options;
 
-  const wantedPlugins: string[] = plugins ?? Object.keys(pluginsMap);
+  const wantedPlugins: string[] = plugins ?? Object.keys(PLUGIN_REGISTRY);
 
   for (const pluginName of wantedPlugins) {
-    const plugin: Plugin = pluginsMap[pluginName]!;
+    const plugin: Plugin = PLUGIN_REGISTRY[pluginName]!;
 
     if (!plugin) {
-      throw new Error(`Plugin ${pluginName} doesn't exist`);
+      throw new Error(`Plugin ${pluginName} doesn't exist.`);
     }
 
-    logger.info(`Generating ${plugin.name} rules`);
+    logger.info(`Generating ${plugin.name} rules.`);
 
     const pluginDir: string = createPluginDirectory(
       pluginName,

scripts/generate-rule-files/src/format.ts

@@ -2,7 +2,7 @@ import type { Options } from 'prettier';
 import { format as prettierFormat } from 'prettier';
 
 /**
- * Our custom prettier configuration
+ * Our custom prettier configuration.
  */
 const PRETTIER_OPTIONS: Options = {
   plugins: [require.resolve('prettier-plugin-organize-imports')],

scripts/generate-rule-files/src/js-doc-builder.ts

@@ -1,10 +1,10 @@
 /**
- * Simple class helper to build a JSDoc comment
+ * Simple class helper to build a JSDoc comment.
  */
 export class JsDocBuilder {
   private readonly content: string[] = [];
 
-  static build(): JsDocBuilder {
+  public static build(): JsDocBuilder {
     return new JsDocBuilder();
   }
 

scripts/generate-rule-files/src/json-schema-to-ts.ts

@@ -2,10 +2,9 @@ import type { JSONSchema4 } from 'json-schema';
 import { compile } from 'json-schema-to-typescript';
 
 /**
- * Remove some comments that are generated by json-schema-to-typescript
- * and that we don't need
+ * Remove unnecessary comments that are generated by `json-schema-to-typescript`.
  */
-function removeGarbageFromJsDocs(content: string): string {
+function cleanJsDoc(content: string): string {
   const patterns: RegExp[] = [
     /\* This interface was referenced by .+ JSON-Schema definition/,
     /\* via the `.+` "/,
@@ -18,7 +17,7 @@ function removeGarbageFromJsDocs(content: string): string {
 }
 
 /**
- * Generate a type from the given JSON schema
+ * Generate a type from the given JSON schema.
  */
 export async function generateTypeFromSchema(
   schema: JSONSchema4,
@@ -27,9 +26,12 @@ export async function generateTypeFromSchema(
   const result: string = await compile(schema, typeName, {
     format: false,
     bannerComment: '',
-    style: { singleQuote: true, trailingComma: 'all' },
+    style: {
+      singleQuote: true,
+      trailingComma: 'all',
+    },
     unknownAny: false,
   });
 
-  return removeGarbageFromJsDocs(result);
+  return cleanJsDoc(result);
 }

scripts/generate-rule-files/src/plugins-map.ts

@@ -25,7 +25,7 @@ import type { Plugin } from '../contracts';
 /**
  * Map of plugins for which the script will generate rule files.
  */
-export const pluginsMap: Record<string, Plugin> = {
+export const PLUGIN_REGISTRY: Readonly<Record<string, Plugin>> = {
   eslint: {
     name: 'Eslint',
     rules: Object.fromEntries(new eslint.Linter().getRules().entries()),
@@ -77,4 +77,4 @@ export const pluginsMap: Record<string, Plugin> = {
     name: 'VuePug',
     rules: (eslintPluginVuePug as Plugin).rules,
   },
-};
+} as const;

scripts/generate-rule-files/src/rule-file.ts

@@ -11,6 +11,7 @@ import { generateTypeFromSchema } from './json-schema-to-ts';
 
 export class RuleFile {
   private content: string = '';
+
   private readonly rulePath: string;
   private readonly ruleNamePascalCase: string;
 
@@ -19,7 +20,7 @@ export class RuleFile {
   private sideSchema?: JSONSchema4;
   private thirdSchema?: JSONSchema4;
 
-  constructor(
+  public constructor(
     private readonly plugin: Plugin,
     pluginDirectory: string,
     private readonly ruleName: string,
@@ -43,17 +44,18 @@ export class RuleFile {
   }
 
   /**
-   * Append the `import type { RuleConfig } at the top of the file
+   * Append the `import type { RuleConfig } from '../rule-config'` at the top of the file.
    */
   public appendRuleConfigImport(): void {
     const nestedDepth: number = this.ruleName.split('/').length;
-    const ruleConfigImportPath: string =
-      '../'.repeat(nestedDepth) + 'rule-config';
+    const ruleConfigImportPath: string = `${'../'.repeat(
+      nestedDepth,
+    )}rule-config`;
     this.content += `import type { RuleConfig } from '${ruleConfigImportPath}'\n\n`;
   }
 
   /**
-   * Build the rule description to append to the JSDoc
+   * Build the rule description to append to the JSDoc.
    */
   public buildDescription(): string {
     let description: string = upperCaseFirst(
@@ -68,7 +70,7 @@ export class RuleFile {
   }
 
   /**
-   * Build the `@see` url to the rule documentation to append to the JSDoc
+   * Build the `@see` url to the rule documentation to append to the JSDoc.
    */
   public buildSeeDocLink(): string {
     const { meta } = this.rule;
@@ -80,7 +82,7 @@ export class RuleFile {
   }
 
   /**
-   * Generate a JSDoc with the rule description and `@see` url
+   * Generate a JSDoc with the rule description and `@see` url.
    */
   public generateTypeJsDoc(): string {
     return JsDocBuilder.build()
@@ -93,7 +95,7 @@ export class RuleFile {
   }
 
   /**
-   * Generate a type from a JSON schema and append it to the file content
+   * Generate a type from a JSON schema and append it to the file content.
    */
   private async appendJsonSchemaType(
     schema: JSONSchema4,
@@ -110,7 +112,7 @@ export class RuleFile {
   }
 
   /**
-   * Generate and append types for the rule schemas
+   * Generate and append types for the rule schemas.
    */
   private async appendRuleSchemaTypes(): Promise<void> {
     if (this.thirdSchema) {
@@ -127,7 +129,7 @@ export class RuleFile {
   }
 
   /**
-   * Append the rule type options to the file content
+   * Append the rule type options to the file content.
    */
   private appendRuleOptions(): void {
     const ruleName: string = this.ruleNamePascalCase;
@@ -148,7 +150,7 @@ export class RuleFile {
   }
 
   /**
-   * Append the rule config type to the file content
+   * Append the rule config type to the file content.
    */
   private appendRuleConfig(): void {
     const ruleName: string = this.ruleNamePascalCase;
@@ -161,7 +163,7 @@ export class RuleFile {
   }
 
   /**
-   * Append the final rule interface to the file content
+   * Append the final rule interface to the file content.
    */
   private appendRule(): void {
     const ruleName: string = this.ruleNamePascalCase;
@@ -180,7 +182,7 @@ export class RuleFile {
   }
 
   /**
-   * Create the directory of the rule file if it doesn't exist
+   * Create the directory of the rule file if it doesn't exist.
    */
   private createRuleDirectory(): void {
     const subPath: string = dirname(this.rulePath.toLowerCase());
@@ -190,7 +192,7 @@ export class RuleFile {
   }
 
   /**
-   * Generate a file with the rule typings
+   * Generate a file with the rule typings.
    */
   public async generate(): Promise<string> {
     this.appendRuleConfigImport();
@@ -209,10 +211,11 @@ export class RuleFile {
   }
 
   /**
-   * Must be called after `generate()` to write the file
+   * Must be called after `generate()` to write the file.
    */
   public writeGeneratedContent(): void {
     this.createRuleDirectory();
+
     writeFileSync(this.rulePath, this.content);
   }
 }

tests/__snapshots__/generate-rule-files.test.ts.snap

@@ -74,14 +74,9 @@ export interface MyRuleRule {
 "
 `;
 
-exports[`Rule File > Three schemas 1`] = `
+exports[`Rule File > Side schemas 1`] = `
 "import type { RuleConfig } from '../rule-config';
 
-/**
- * Setting.
- */
-export type MyRuleSetting = boolean;
-
 /**
  * Config.
  */
@@ -95,7 +90,7 @@ export type MyRuleOption = number;
 /**
  * Options.
  */
-export type MyRuleOptions = [MyRuleOption?, MyRuleConfig?, MyRuleSetting?];
+export type MyRuleOptions = [MyRuleOption?, MyRuleConfig?];
 
 /**
  * My rule description.
@@ -120,9 +115,14 @@ export interface MyRuleRule {
 "
 `;
 
-exports[`Rule File > Two schemas 1`] = `
+exports[`Rule File > Third schemas 1`] = `
 "import type { RuleConfig } from '../rule-config';
 
+/**
+ * Setting.
+ */
+export type MyRuleSetting = boolean;
+
 /**
  * Config.
  */
@@ -136,7 +136,7 @@ export type MyRuleOption = number;
 /**
  * Options.
  */
-export type MyRuleOptions = [MyRuleOption?, MyRuleConfig?];
+export type MyRuleOptions = [MyRuleOption?, MyRuleConfig?, MyRuleSetting?];
 
 /**
  * My rule description.