Merge pull request #4669 from Tyriar/api_lint

Lint API .d.ts files
xtermjs · Aug 12, 2023 · 5890029 · 5890029
2 parents 519f6a3 + 1f4fe0a
commit 5890029
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;
   }
 }