feat: add new LangVariant option LangAuto although it's unsupported (#107)

JounQin · autofix-ci[bot] · Copilot · web-flow · commit 3152cd3debf4 · 2025-04-08T00:26:34.000+08:00
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/.changeset/gentle-pets-prove.md b/.changeset/gentle-pets-prove.md
@@ -0,0 +1,5 @@
+---
+"sh-syntax": patch
+---
+
+feat: add new `LangVariant` option `LangAuto` although it's unsupported
diff --git a/eslint.config.js b/eslint.config.js
@@ -1,8 +1,17 @@
 import base from '@1stg/eslint-config'
+import stylisticJs from '@stylistic/eslint-plugin-js'
 
 export default [
   ...base,
   {
     ignores: ['vendors'],
   },
+  {
+    plugins: {
+      '@stylistic/js': stylisticJs,
+    },
+    rules: {
+      '@stylistic/js/multiline-comment-style': ['error', 'starred-block'],
+    },
+  },
 ]
diff --git a/package.json b/package.json
@@ -49,7 +49,7 @@
     "benchmark": "NO_COLOR=1 node benchmark > benchmark/benchmark.txt",
     "build": "run-p 'build:*'",
     "build:r": "r -f cjs -x '**/vendors/wasm_exec.cjs'",
-    "build:tsc": "tsc -b src",
+    "build:tsc": "tsc -p src --declaration false && tsc -p src --removeComments false --emitDeclarationOnly",
     "easyjson": "easyjson --all processor/structs.go",
     "format": "prettier --write .",
     "lint": "run-p 'lint:*'",
@@ -71,6 +71,7 @@
     "@commitlint/cli": "^19.8.0",
     "@mitata/counters": "^0.0.8",
     "@pkgr/rollup": "^6.0.2",
+    "@stylistic/eslint-plugin-js": "^4.2.0",
     "@types/golang-wasm-exec": "^1.15.2",
     "@types/mvdan-sh": "^0.10.9",
     "@types/node": "^22.14.0",
diff --git a/src/processor.ts b/src/processor.ts
@@ -91,6 +91,7 @@ export const getProcessor = (
       binaryNextLine = true,
       switchCaseIndent = true,
       spaceRedirects = true,
+      // eslint-disable-next-line sonarjs/deprecation
       keepPadding = false,
       minify = false,
       singleLine = false,
@@ -118,10 +119,11 @@ export const getProcessor = (
 
     const wasm = await WebAssembly.instantiate(wasmFile, go.importObject)
 
-    // Do not await this promise, because it only resolves once the go main()
-    // function has exited. But we need the main function to stay alive to be
-    // able to call the `parse` and `print` function.
-
+    /**
+     * Do not await this promise, because it only resolves once the go main()
+     * function has exited. But we need the main function to stay alive to be
+     * able to call the `parse` and `print` function.
+     */
     void go.run(wasm.instance)
 
     const { memory, wasmAlloc, wasmFree, process } = wasm.instance.exports as {
diff --git a/src/types.ts b/src/types.ts
@@ -1,29 +1,155 @@
 export type ValueOf<T> = T[keyof T]
 
 export const LangVariant = {
+  /**
+   * LangBash corresponds to the GNU Bash language, as described in its
+   * manual at https://www.gnu.org/software/bash/manual/bash.html.
+   *
+   * We currently follow Bash version 5.2.
+   *
+   * Its string representation is "bash".
+   */
   LangBash: 0,
+  /**
+   * LangPOSIX corresponds to the POSIX Shell language, as described at
+   * https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html.
+   *
+   * Its string representation is "posix" or "sh".
+   */
   LangPOSIX: 1,
+  /**
+   * LangMirBSDKorn corresponds to the MirBSD Korn Shell, also known as
+   * mksh, as described at https://www.mirbsd.org/htman/i386/man1/mksh.htm.
+   * Note that it shares some features with Bash, due to the shared
+   * ancestry that is ksh.
+   *
+   * We currently follow mksh version 59.
+   *
+   * Its string representation is "mksh".
+   */
   LangMirBSDKorn: 2,
+  /**
+   * LangBats corresponds to the Bash Automated Testing System language,
+   * as described at https://github.com/bats-core/bats-core. Note that
+   * it's just a small extension of the Bash language.
+   *
+   * Its string representation is "bats".
+   */
   LangBats: 3,
+  /**
+   * LangAuto corresponds to automatic language detection,
+   * commonly used by end-user applications like shfmt,
+   * which can guess a file's language variant given its filename or shebang.
+   *
+   * At this time, [Variant] does not support LangAuto.
+   */
+  LangAuto: 4,
 } as const
 
 export type LangVariant = ValueOf<typeof LangVariant>
 
 export interface ShParserOptions {
+  /**
+   * KeepComments makes the parser parse comments and attach them to
+   * nodes, as opposed to discarding them.
+   */
   keepComments?: boolean
+  /**
+   * LangVariant describes a shell language variant to use when tokenizing and
+   * parsing shell code. The zero value is [LangBash].
+   */
   variant?: LangVariant
+  /**
+   * StopAt configures the lexer to stop at an arbitrary word, treating it
+   * as if it were the end of the input. It can contain any characters
+   * except whitespace, and cannot be over four bytes in size.
+   *
+   * This can be useful to embed shell code within another language, as
+   * one can use a special word to mark the delimiters between the two.
+   *
+   * As a word, it will only apply when following whitespace or a
+   * separating token. For example, StopAt("$$") will act on the inputs
+   * "foo $$" and "foo;$$", but not on "foo '$$'".
+   *
+   * The match is done by prefix, so the example above will also act on
+   * "foo $$bar".
+   */
   stopAt?: string
+  /**
+   *  RecoverErrors allows the parser to skip up to a maximum number of
+   *  errors in the given input on a best-effort basis.
+   *  This can be useful to tab-complete an interactive shell prompt,
+   *  or when providing diagnostics on slightly incomplete shell source.
+   *
+   *  Currently, this only helps with mandatory tokens from the shell grammar
+   *  which are not present in the input. They result in position fields
+   *  or nodes whose position report [Pos.IsRecovered] as true.
+   *
+   *  For example, given the input
+   *
+   * 	(foo |
+   *
+   *  the result will contain two recovered positions; first, the pipe requires
+   *  a statement to follow, and as [Stmt.Pos] reports, the entire node is recovered.
+   *  Second, the subshell needs to be closed, so [Subshell.Rparen] is recovered.
+   */
   recoverErrors?: number
 }
 
 export interface ShPrinterOptions {
+  /**
+   * Indent sets the number of spaces used for indentation. If set to 0,
+   * tabs will be used instead.
+   */
   indent?: number
+  /**
+   * BinaryNextLine will make binary operators appear on the next line
+   * when a binary command, such as a pipe, spans multiple lines. A
+   * backslash will be used.
+   */
   binaryNextLine?: boolean
+  /**
+   * SwitchCaseIndent will make switch cases be indented. As such, switch
+   * case bodies will be two levels deeper than the switch itself.
+   */
   switchCaseIndent?: boolean
+  /**
+   * SpaceRedirects will put a space after most redirection operators. The
+   * exceptions are '>&', '<&', '>(', and '<('.
+   */
   spaceRedirects?: boolean
+  /**
+   * KeepPadding will keep most nodes and tokens in the same column that
+   * they were in the original source. This allows the user to decide how
+   * to align and pad their code with spaces.
+   *
+   * Note that this feature is best-effort and will only keep the
+   * alignment stable, so it may need some human help the first time it is
+   * run.
+   *
+   * @deprecated: this formatting option is flawed and buggy, and often does
+   * not result in what the user wants when the code gets complex enough.
+   *
+   * The next major version, v4, will remove this feature entirely.
+   * See: https://github.com/mvdan/sh/issues/658
+   */
   keepPadding?: boolean
+  /**
+   * Minify will print programs in a way to save the most bytes possible.
+   * For example, indentation and comments are skipped, and extra
+   * whitespace is avoided when possible.
+   */
   minify?: boolean
+  /**
+   * SingleLine will attempt to print programs in one line. For example, lists of
+   * commands or nested blocks do not use newlines in this mode. Note that some
+   * newlines must still appear, such as those following comments or around
+   * here-documents.
+   *
+   * Print's trailing newline when given a [*File] is not affected by this option.
+   */
   singleLine?: boolean
+  // FunctionNextLine will place a function's opening braces on the next line.
   functionNextLine?: boolean
 }
 
diff --git a/yarn.lock b/yarn.lock
@@ -3690,6 +3690,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@stylistic/eslint-plugin-js@npm:^4.2.0":
+  version: 4.2.0
+  resolution: "@stylistic/eslint-plugin-js@npm:4.2.0"
+  dependencies:
+    eslint-visitor-keys: "npm:^4.2.0"
+    espree: "npm:^10.3.0"
+  peerDependencies:
+    eslint: ">=9.0.0"
+  checksum: 10c0/5e5a21a60c818fc9f745b12fab252a1188e4d98d7008a81dbaf5a8e106558ac757c4c56e2a4b982bd97249132a31f577a991383f77b4912b8b26723d57654256
+  languageName: node
+  linkType: hard
+
 "@szmarczak/http-timer@npm:^4.0.5":
   version: 4.0.6
   resolution: "@szmarczak/http-timer@npm:4.0.6"
@@ -13156,6 +13168,7 @@ __metadata:
     "@commitlint/cli": "npm:^19.8.0"
     "@mitata/counters": "npm:^0.0.8"
     "@pkgr/rollup": "npm:^6.0.2"
+    "@stylistic/eslint-plugin-js": "npm:^4.2.0"
     "@types/golang-wasm-exec": "npm:^1.15.2"
     "@types/mvdan-sh": "npm:^0.10.9"
     "@types/node": "npm:^22.14.0"

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"sh-syntax": patch
 +---
++
 +feat: add new `LangVariant` option `LangAuto` although it's unsupported