Port lib/formatters to TypeScript (compiler-explorer#3741)

Author: junlarsen

docs/AddingAFormatter.md

@@ -5,10 +5,12 @@
   - Add a new formatter under the `formatters` key
   - The new formatter can have the following keys: name, exe, styles, type, explicitVersion (to override version
     parsing), version (argument to get version info), versionRe (regex to filter out the right version info)
-  - Add a `lib/formatters/<formatter>.js` file using the template below, replacing `Type` and `type` as appropriate
+  - Add a `lib/formatters/<formatter>.ts` file using the template below, replacing `Type` and `type` as appropriate
 
     ```js
-    import {BaseFormatter} from '../base-formatter';
+    import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
+    import {BaseFormatter} from './base';
+    import {FormatOptions} from './base.interfaces';
 
     export class TypeFormatter extends BaseFormatter {
       static get key() {
@@ -19,10 +21,11 @@
 
   - The value returned by `key` above corresponds to the `type` property you set in the compiler-explorer properties
     configuration file.
-  - Tweak `format(source, options)` and `isValidStyle(style)` as necessary. See the JSDoc for `format` and the
-    implementations for other formatters to get a further understanding of how to implement `format(source, options)`.
+  - Tweak `format(source: string, options: FormatOptions): Promise<UnprocessedExecResult>` and
+    `isValidStyle(style: string): boolean` as necessary. See the JSDoc for `format` and the implementations for other
+    formatters to get a further understanding of how to implement `format(source, options)`.
 
-- Add your `TypeFormatter` to `lib/formatters/_all.js` in alphabetical order
+- Add your `TypeFormatter` to `lib/formatters/_all.ts` in alphabetical order
 
 - You can check the output of http://localhost:10240/api/formats to be sure your formatter is there.
 

lib/formatters/_all.js renamed to lib/formatters/_all.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2022, Compiler Explorer Authors
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+//     * Redistributions of source code must retain the above copyright notice,
+//       this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above copyright
+//       notice, this list of conditions and the following disclaimer in the
+//       documentation and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.
+
+export interface FormatterInfo {
+    name: string;
+    exe: string;
+    styles: string[];
+    type: string;
+    explicitVersion?: string;
+    versionArgument?: string;
+    versionReExp?: string;
+}
+
+export type FormatOptions = {
+    useSpaces: boolean;
+    tabWidth: number;
+    baseStyle: string;
+};

lib/formatters/base.interfaces.ts

@@ -22,37 +22,33 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
+import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
 import * as exec from '../exec';
 
-export class BaseFormatter {
-    constructor(formatterInfo) {
+import {FormatOptions, FormatterInfo} from './base.interfaces';
+
+export abstract class BaseFormatter {
+    public formatterInfo: FormatterInfo;
+
+    public constructor(formatterInfo: FormatterInfo) {
         this.formatterInfo = formatterInfo;
     }
 
     /**
      * Format the provided source code using the formatting tool.
      *
-     * This function should construct the final arguments passed to the tool
-     * executable.
-     *
-     * Optionally accept a third argument to respect other formatting options.
-     * The possible options passed are as follows:
-     *
-     * interface AdditionalFormatOptions {
-     *     useSpaces: boolean;
-     *     tabWidth: number;
-     *     baseStyle: string;
-     * }
+     * This method should construct the command line arguments and call the formatter executable with the constructed
+     * arguments, returning the execution result
      */
-    async format(source, options) {
+    async format(source: string, options: FormatOptions): Promise<UnprocessedExecResult> {
         const args = [`--style=${options.baseStyle}`];
         return await exec.execute(this.formatterInfo.exe, args, {input: source});
     }
 
     /**
      * Test if a formatting base style is valid for this formatter
      */
-    isValidStyle(style) {
+    isValidStyle(style: string): boolean {
         return this.formatterInfo.styles.includes(style);
     }
 }

lib/formatters/base.js renamed to lib/formatters/base.ts

@@ -22,16 +22,18 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
+import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
 import * as exec from '../exec';
 
 import {BaseFormatter} from './base';
+import {FormatOptions} from './base.interfaces';
 
 export class ClangFormatFormatter extends BaseFormatter {
     static get key() {
         return 'clangformat';
     }
 
-    async format(source, options) {
+    override async format(source: string, options: FormatOptions): Promise<UnprocessedExecResult> {
         const tabText = options.useSpaces ? 'Never' : 'AlignWithSpaces';
         const arg = `{BasedOnStyle: ${options.baseStyle}, IndentWidth: ${options.tabWidth}, UseTab: ${tabText}}`;
         return await exec.execute(this.formatterInfo.exe, [`--style=${arg}`], {input: source});

lib/formatters/clang-format.js renamed to lib/formatters/clang-format.ts

@@ -22,20 +22,22 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
+import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
 import * as exec from '../exec';
 
 import {BaseFormatter} from './base';
+import {FormatOptions} from './base.interfaces';
 
 export class DartFormatFormatter extends BaseFormatter {
     static get key() {
         return 'dartformat';
     }
 
-    async format(source) {
+    override async format(source: string, options: FormatOptions): Promise<UnprocessedExecResult> {
         return await exec.execute(this.formatterInfo.exe, ['format'], {input: source});
     }
 
-    isValidStyle() {
+    override isValidStyle(style: string): boolean {
         // Dart supports only one style
         return true;
     }

lib/formatters/dartformat.js renamed to lib/formatters/dartformat.ts

@@ -22,9 +22,11 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
+import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
 import * as exec from '../exec';
 
 import {BaseFormatter} from './base';
+import {FormatOptions} from './base.interfaces';
 
 export class GoFmtFormatter extends BaseFormatter {
     static get key() {
@@ -37,14 +39,14 @@ export class GoFmtFormatter extends BaseFormatter {
      * This function does not use any options, because gofmt does not have any
      * options.
      */
-    async format(source) {
+    override async format(source: string, options: FormatOptions): Promise<UnprocessedExecResult> {
         return await exec.execute(this.formatterInfo.exe, [], {input: source});
     }
 
     /**
      * Gofmt has no styling options
      */
-    isValidStyle() {
+    override isValidStyle(style: string): boolean {
         return true;
     }
 }

lib/formatters/gofmt.js renamed to lib/formatters/gofmt.ts

@@ -22,16 +22,18 @@
 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 
+import {UnprocessedExecResult} from '../../types/execution/execution.interfaces';
 import * as exec from '../exec';
 
 import {BaseFormatter} from './base';
+import {FormatOptions} from './base.interfaces';
 
 export class RustFmtFormatter extends BaseFormatter {
     static get key() {
         return 'rustfmt';
     }
 
-    async format(source, options) {
+    override async format(source: string, options: FormatOptions): Promise<UnprocessedExecResult> {
         const args = [
             '--emit',
             'stdout',
@@ -46,7 +48,7 @@ export class RustFmtFormatter extends BaseFormatter {
     /**
      * Rust format only has one style.
      */
-    isValidStyle() {
+    override isValidStyle(style: string): boolean {
         return true;
     }
 }