Lint API .d.ts files

Similar to xtermjs#4668, this brings linting to the API files with a cut down set of rules. One of the bigger ones is comment length is restricted to 80, this was done as opposed to 100 for regular code to reduce the chance of wrapping or API going off screen regardless of resolution or window/browser size
Tyriar · Aug 12, 2023 · 1f4fe0a · 1f4fe0a
1 parent 530f758
commit 1f4fe0a
Show file tree

Hide file tree

Showing 5 changed files with 292 additions and 150 deletions.
diff --git a/.eslintrc.json.typings b/.eslintrc.json.typings
@@ -0,0 +1,104 @@
+{
+  "env": {
+    "browser": true,
+    "es6": true,
+    "node": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint",
+    "jsdoc"
+  ],
+  "rules": {
+    "no-extra-semi": "error",
+    "@typescript-eslint/array-type": [
+      "warn",
+      {
+        "default": "array",
+        "readonly": "generic"
+      }
+    ],
+    "@typescript-eslint/explicit-function-return-type": [
+      "warn",
+      {
+        "allowExpressions": true
+      }
+    ],
+    "@typescript-eslint/indent": [
+      "warn",
+      2
+    ],
+    "@typescript-eslint/member-delimiter-style": [
+      "warn",
+      {
+        "multiline": {
+          "delimiter": "semi",
+          "requireLast": true
+        },
+        "singleline": {
+          "delimiter": "comma",
+          "requireLast": false
+        }
+      }
+    ],
+    "@typescript-eslint/naming-convention": [
+      "warn",
+      { "selector": "typeLike", "format": ["PascalCase"] },
+      { "selector": "interface", "format": ["PascalCase"], "prefix": ["I"] }
+    ],
+    "@typescript-eslint/prefer-namespace-keyword": "warn",
+    "@typescript-eslint/type-annotation-spacing": "warn",
+    "@typescript-eslint/quotes": [
+      "warn",
+      "single",
+      { "allowTemplateLiterals": true }
+    ],
+    "@typescript-eslint/semi": [
+      "warn",
+      "always"
+    ],
+    "comma-dangle": [
+      "warn",
+      {
+        "objects": "never",
+        "arrays": "never",
+        "functions": "never"
+      }
+    ],
+    "curly": [
+      "warn",
+      "multi-line"
+    ],
+    "eol-last": "warn",
+    "eqeqeq": [
+      "warn",
+      "always"
+    ],
+    "jsdoc/check-alignment": 1,
+    "jsdoc/check-param-names": 1,
+    "keyword-spacing": "warn",
+    "max-len": [
+      "warn",
+      {
+        "code": 1000, // Don't enforce for code
+        "comments": 80,
+        "ignoreUrls": true,
+        "ignorePattern": "^ *(?<ps_description>\\* Ps=)"
+      }
+    ],
+    "no-irregular-whitespace": "warn",
+    "no-trailing-spaces": "warn",
+    "object-curly-spacing": [
+      "warn",
+      "always"
+    ],
+    "spaced-comment": [
+      "warn",
+      "always",
+      {
+        "markers": ["/"],
+        "exceptions": ["-"]
+      }
+    ]
+  }
+}
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -33,7 +33,9 @@ jobs:
       exit $EXIT_CODE
     displayName: 'Unit tests'
   - script: yarn lint
-    displayName: 'Lint'
+    displayName: 'Lint code'
+  - script: yarn lint-api
+    displayName: 'Lint API'
   - task: PublishCodeCoverageResults@1
     inputs:
       codeCoverageTool: Cobertura
@@ -58,7 +60,9 @@ jobs:
   - script: yarn test-unit --forbid-only
     displayName: 'Unit tests'
   - script: yarn lint
-    displayName: 'Lint'
+    displayName: 'Lint code'
+  - script: yarn lint-api
+    displayName: 'Lint API'
 
 - job: Windows
   pool:
@@ -78,7 +82,9 @@ jobs:
   - script: yarn test-unit --forbid-only
     displayName: 'Unit tests'
   - script: yarn lint
-    displayName: 'Lint'
+    displayName: 'Lint code'
+  - script: yarn lint-api
+    displayName: 'Lint API'
 
 - job: Linux_IntegrationTests
   pool:

diff --git a/package.json b/package.json
@@ -30,6 +30,7 @@
     "start": "node demo/start",
     "start-debug": "node --inspect-brk demo/start",
     "lint": "eslint -c .eslintrc.json --max-warnings 0 --ext .ts src/ addons/",
+    "lint-api": "eslint --no-eslintrc -c .eslintrc.json.typings --max-warnings 0 --no-ignore --ext .d.ts typings/",
     "test": "npm run test-unit",
     "posttest": "npm run lint",
     "test-api": "npm run test-api-chromium",

diff --git a/typings/xterm-headless.d.ts b/typings/xterm-headless.d.ts
@@ -19,7 +19,8 @@ declare module 'xterm-headless' {
   export interface ITerminalOptions {
     /**
      * Whether to allow the use of proposed API. When false, any usage of APIs
-     * marked as experimental/proposed will throw an error. The default is false.
+     * marked as experimental/proposed will throw an error. The default is
+     * false.
      */
     allowProposedApi?: boolean;
 
@@ -63,13 +64,13 @@ declare module 'xterm-headless' {
     cursorWidth?: number;
 
     /**
-     * Whether to draw custom glyphs for block element and box drawing characters instead of using
-     * the font. This should typically result in better rendering with continuous lines, even when
-     * line height and letter spacing is used. Note that this doesn't work with the DOM renderer
-     * which renders all characters using the font. The default is true.
+     * Whether to draw custom glyphs for block element and box drawing
+     * characters instead of using the font. This should typically result in
+     * better rendering with continuous lines, even when line height and letter
+     * spacing is used. Note that this doesn't work with the DOM renderer which
+     * renders all characters using the font. The default is true.
      */
     customGlyphs?: boolean;
-
     /**
      * Whether input should be disabled.
      */
@@ -217,9 +218,9 @@ declare module 'xterm-headless' {
     windowsPty?: IWindowsPty;
 
     /**
-     * A string containing all characters that are considered word separated by the
-     * double click to select work logic.
-    */
+     * A string containing all characters that are considered word separated by
+     * the double click to select work logic.
+     */
     wordSeparator?: string;
 
     /**
@@ -314,23 +315,23 @@ declare module 'xterm-headless' {
    */
   export interface ILogger {
     /**
-     * Log a debug message, this will only be called if {@link ITerminalOptions.logLevel} is set to
-     * debug.
+     * Log a debug message, this will only be called if
+     * {@link ITerminalOptions.logLevel} is set to debug.
      */
     debug(message: string, ...args: any[]): void;
     /**
-     * Log a debug message, this will only be called if {@link ITerminalOptions.logLevel} is set to
-     * info or below.
+     * Log a debug message, this will only be called if
+     * {@link ITerminalOptions.logLevel} is set to info or below.
      */
     info(message: string, ...args: any[]): void;
     /**
-     * Log a debug message, this will only be called if {@link ITerminalOptions.logLevel} is set to
-     * warn or below.
+     * Log a debug message, this will only be called if
+     * {@link ITerminalOptions.logLevel} is set to warn or below.
      */
     warn(message: string, ...args: any[]): void;
     /**
-     * Log a debug message, this will only be called if {@link ITerminalOptions.logLevel} is set to
-     * error or below.
+     * Log a debug message, this will only be called if
+     * {@link ITerminalOptions.logLevel} is set to error or below.
      */
     error(message: string | Error, ...args: any[]): void;
   }
@@ -361,23 +362,26 @@ declare module 'xterm-headless' {
      */
     readonly id: number;
 
-    /**
-     * Whether this marker is disposed.
-     */
-    readonly isDisposed: boolean;
-
     /**
      * The actual line index in the buffer at this point in time. This is set to
      * -1 if the marker has been disposed.
      */
     readonly line: number;
+  }
 
+  /**
+   * Represents a disposable that tracks is disposed state.
+   */
+  export interface IDisposableWithEvent extends IDisposable {
     /**
-     * Event listener to get notified when the marker gets disposed. Automatic disposal
-     * might happen for a marker, that got invalidated by scrolling out or removal of
-     * a line from the buffer.
+     * Event listener to get notified when this gets disposed.
      */
     onDispose: IEvent<void>;
+
+    /**
+     * Whether this is disposed.
+     */
+    readonly isDisposed: boolean;
   }
 
   /**
@@ -397,7 +401,8 @@ declare module 'xterm-headless' {
   }
 
   /**
-   * Enable various window manipulation and report features (CSI Ps ; Ps ; Ps t).
+   * Enable various window manipulation and report features
+   * (`CSI Ps ; Ps ; Ps t`).
    *
    * Most settings have no default implementation, as they heavily rely on
    * the embedding environment.
@@ -417,10 +422,10 @@ declare module 'xterm-headless' {
    *
    * Note on security:
    * Most features are meant to deal with some information of the host machine
-   * where the terminal runs on. This is seen as a security risk possibly leaking
-   * sensitive data of the host to the program in the terminal. Therefore all options
-   * (even those without a default implementation) are guarded by the boolean flag
-   * and disabled by default.
+   * where the terminal runs on. This is seen as a security risk possibly
+   * leaking sensitive data of the host to the program in the terminal.
+   * Therefore all options (even those without a default implementation) are
+   * guarded by the boolean flag and disabled by default.
    */
   export interface IWindowOptions {
     /**
@@ -601,23 +606,36 @@ declare module 'xterm-headless' {
     readonly modes: IModes;
 
     /**
-     * Gets or sets the terminal options. This supports setting multiple options.
+     * Gets or sets the terminal options. This supports setting multiple
+     * options.
      *
      * @example Get a single option
-     * ```typescript
+     * ```ts
      * console.log(terminal.options.fontSize);
      * ```
      *
-     * @example Set a single option
-     * ```typescript
+     * @example Set a single option:
+     * ```ts
      * terminal.options.fontSize = 12;
      * ```
+     * Note that for options that are object, a new object must be used in order
+     * to take effect as a reference comparison will be done:
+     * ```ts
+     * const newValue = terminal.options.theme;
+     * newValue.background = '#000000';
+     *
+     * // This won't work
+     * terminal.options.theme = newValue;
+     *
+     * // This will work
+     * terminal.options.theme = { ...newValue };
+     * ```
      *
      * @example Set multiple options
-     * ```typescript
+     * ```ts
      * terminal.options = {
      *   fontSize: 12,
-     *   fontFamily: 'Courier New',
+     *   fontFamily: 'Courier New'
      * };
      * ```
      */
@@ -1282,6 +1300,6 @@ declare module 'xterm-headless' {
     /**
      * Auto-Wrap Mode (DECAWM): `CSI ? 7 h`
      */
-    readonly wraparoundMode: boolean
+    readonly wraparoundMode: boolean;
   }
 }