feat: add new options recoverErrors and singleLine support (#104)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: JounQin <admin@1stg.me>

Author: JounQin

.changeset/ninety-rings-guess.md

@@ -0,0 +1,5 @@
+---
+"sh-syntax": patch
+---
+
+feat: add new options `recoverErrors` and `singleLine` support

main.go

@@ -50,6 +50,12 @@ func Print(originalText string, filepath string, syntaxOptions processor.SyntaxO
 	return processor.Print(originalText, filepath, syntaxOptions)
 }
 
+// `process` processes the input file path and text by performing either formatting (printing) or parsing based on the print flag.
+//
+// It converts the input byte slices to strings and configures parser options—including comment retention, language variant, stop marker, and error recovery settings. When printing is enabled, it applies printer options (indentation, binary next line, switch case indentation, space redirects, padding, minification, single-line formatting, and function next line) to format the text via the Print function. Otherwise, it parses the text with Parse and maps the resulting AST into a file representation.
+//
+// The function then encapsulates the file, the processed text, and any parsing error information into a result structure, marshals it to JSON, appends a null terminator, and returns a pointer to the first byte of the JSON output.
+//
 //export process
 func process(
 	filepathBytes []byte,
@@ -59,8 +65,9 @@ func process(
 
 	// parser
 	keepComments bool,
-	stopAt []byte,
 	variant int,
+	stopAt []byte,
+	recoverErrors int,
 
 	// printer
 	indent int,
@@ -69,15 +76,17 @@ func process(
 	spaceRedirects,
 	keepPadding,
 	minify,
+	singleLine bool,
 	functionNextLine bool,
 ) *byte {
 	filepath := string(filepathBytes)
 	text := string(textBytes)
 
 	parserOptions := processor.ParserOptions{
-		KeepComments: keepComments,
-		StopAt:       string(stopAt),
-		Variant:      syntax.LangVariant(variant),
+		KeepComments:  keepComments,
+		Variant:       syntax.LangVariant(variant),
+		StopAt:        string(stopAt),
+		RecoverErrors: recoverErrors,
 	}
 
 	var file processor.File
@@ -91,6 +100,7 @@ func process(
 			SpaceRedirects:   spaceRedirects,
 			KeepPadding:      keepPadding,
 			Minify:           minify,
+			SingleLine:       singleLine,
 			FunctionNextLine: functionNextLine,
 		}
 

main.wasm

@@ -13,9 +13,10 @@ var (
 )
 
 type ParserOptions struct {
-	KeepComments bool
-	StopAt       string
-	Variant      syntax.LangVariant
+	KeepComments  bool
+	Variant       syntax.LangVariant
+	StopAt        string
+	RecoverErrors int
 }
 
 type PrinterOptions struct {
@@ -25,6 +26,7 @@ type PrinterOptions struct {
 	SpaceRedirects   bool
 	KeepPadding      bool
 	Minify           bool
+	SingleLine       bool
 	FunctionNextLine bool
 }
 
@@ -33,6 +35,11 @@ type SyntaxOptions struct {
 	PrinterOptions
 }
 
+// `Parse` converts shell script text into a structured syntax tree.
+// It assembles parser options based on the provided configuration—such as whether to keep comments,
+// the shell syntax variant to use, an optional stopping point, and the desired error recovery level.
+// The supplied file path is used for contextual error reporting.
+// It returns a syntax.File representing the parsed script, or an error if parsing fails.
 func Parse(text string, filepath string, parserOptions ParserOptions) (*syntax.File, error) {
 	var options []syntax.ParserOption
 
@@ -42,11 +49,20 @@ func Parse(text string, filepath string, parserOptions ParserOptions) (*syntax.F
 		options = append(options, syntax.StopAt(parserOptions.StopAt))
 	}
 
+	if parserOptions.RecoverErrors != 0 {
+		options = append(options, syntax.RecoverErrors(parserOptions.RecoverErrors))
+	}
+
 	parser = syntax.NewParser(options...)
 
 	return parser.Parse(bytes.NewReader([]byte(text)), filepath)
 }
 
+// `Print` returns the formatted shell script defined in originalText.
+// It first parses the input using the parser options in syntaxOptions and then prints the resulting
+// syntax tree using printer options—including indentation, single-line formatting, and others.
+// The filepath parameter is used for context in error messages. On success, Print returns the formatted
+// script as a string, or an error if parsing or printing fails.
 func Print(originalText string, filepath string, syntaxOptions SyntaxOptions) (string, error) {
 	file, err := Parse(originalText, filepath, syntaxOptions.ParserOptions)
 
@@ -61,6 +77,7 @@ func Print(originalText string, filepath string, syntaxOptions SyntaxOptions) (s
 		syntax.SpaceRedirects(syntaxOptions.SpaceRedirects),
 		syntax.KeepPadding(syntaxOptions.KeepPadding),
 		syntax.Minify(syntaxOptions.Minify),
+		syntax.SingleLine(syntaxOptions.SingleLine),
 		syntax.FunctionNextLine(syntaxOptions.FunctionNextLine),
 	)
 

processor/main.go

@@ -115,10 +115,11 @@ func mapNode(node syntax.Node) *Node {
 	}
 }
 
+// `mapComments` transforms a slice of syntax.Comment into a slice of Comment by converting each comment's hash, text, start, and end positions using mapPos. It preserves the order of the comments and returns an empty slice if the input is nil or empty.
 func mapComments(comments []syntax.Comment) []Comment {
 	commentsSize := len(comments)
 	commentList := make([]Comment, commentsSize)
-	for i := 0; i < commentsSize; i++ {
+	for i := range commentsSize {
 		curr := comments[i]
 		commentList[i] = Comment{
 			Hash: mapPos(curr.Hash),
@@ -130,6 +131,8 @@ func mapComments(comments []syntax.Comment) []Comment {
 	return commentList
 }
 
+// `mapWord` converts a *syntax.Word into a custom *Word structure. It maps each part of the syntax.Word using mapNode,
+// extracts the literal via Lit(), and maps the start and end positions using mapPos. If the input word is nil, it returns nil.
 func mapWord(word *syntax.Word) *Word {
 	if word == nil {
 		return nil
@@ -138,7 +141,7 @@ func mapWord(word *syntax.Word) *Word {
 	size := len(word.Parts)
 	parts := make([]Node, size)
 
-	for i := 0; i < size; i++ {
+	for i := range size {
 		parts[i] = *mapNode(word.Parts[i])
 	}
 
@@ -150,10 +153,13 @@ func mapWord(word *syntax.Word) *Word {
 	}
 }
 
+// `mapRedirects` converts a slice of syntax.Redirect pointers into a slice of custom Redirect structures.
+// It maps each redirect’s operator position, associated literal (if present), word, heredoc, and overall positional data using helper functions.
+// If the literal component (N) is non-nil, it is transformed into a Lit structure that encapsulates both its value and positional information.
 func mapRedirects(redirects []*syntax.Redirect) []Redirect {
 	redirsSize := len(redirects)
 	redirs := make([]Redirect, redirsSize)
-	for i := 0; i < redirsSize; i++ {
+	for i := range redirsSize {
 		curr := redirects[i]
 		var N *Lit
 		if curr.N != nil {
@@ -180,10 +186,11 @@ func mapRedirects(redirects []*syntax.Redirect) []Redirect {
 	return redirs
 }
 
+// `mapStmts` converts a slice of *syntax.Stmt into a slice of Stmt by mapping each statement's components—including comments, command node, positional information, semicolon, redirections, and execution flags (negated, background, coprocess).
 func mapStmts(stmts []*syntax.Stmt) []Stmt {
 	stmtsSize := len(stmts)
 	stmtList := make([]Stmt, stmtsSize)
-	for i := 0; i < stmtsSize; i++ {
+	for i := range stmtsSize {
 		curr := stmts[i]
 		stmtList[i] = Stmt{
 			Comments:   mapComments(curr.Comments),

processor/structs.go

@@ -45,6 +45,34 @@ export const getProcessor = (
     },
   ): Promise<string>
 
+  /**
+   * Processes a shell script input using a WebAssembly module.
+   *
+   * This asynchronous function accepts shell script input either as a string or as an AST File, along with a set of options
+   * that control formatting, error recovery, and output. It ensures that the WebAssembly module is loaded and instantiated,
+   * allocates memory for the file path and text content, and then calls the module's processing function with the provided options.
+   * Depending on the `print` flag, it returns either the processed text or a File representing the parsed AST.
+   *
+   * @param textOrAst - The shell script input as a string or as an AST File. When providing a non-string input and `print` is false,
+   *                    the `originalText` option must be supplied.
+   * @param options - An object containing processing options:
+   *   - filepath: The file path associated with the input, used primarily for error reporting.
+   *   - print: If true, the function returns the processed text; otherwise, it returns the processed AST as a File.
+   *   - originalText: The original text of the shell script, required when `textOrAst` is not a string.
+   *   - keepComments: Determines whether comments should be preserved in the output.
+   *   - variant: Specifies the shell scripting variant (e.g., {@link LangVariant.LangBash}).
+   *   - stopAt: A token indicating where to halt further processing.
+   *   - recoverErrors: Sets the level of error recovery during processing (default is 0).
+   *   - useTabs, tabWidth, indent: Options to control indentation formatting.
+   *   - binaryNextLine, switchCaseIndent, spaceRedirects, keepPadding, minify, singleLine, functionNextLine:
+   *     Additional flags that influence formatting details and output structure.
+   *
+   * @returns A promise that resolves to either the processed text (if `print` is true) or a File (if `print` is false).
+   *
+   * @throws {TypeError} If the original text is required but not provided.
+   * @throws {ParseError} If the processed output is not valid JSON or indicates a parsing error.
+   * @throws {SyntaxError} If a syntax error is detected without an associated parse error object.
+   */
   async function processor(
     textOrAst: File | string,
     {
@@ -53,8 +81,9 @@ export const getProcessor = (
       originalText,
 
       keepComments = true,
-      stopAt = '',
       variant = LangVariant.LangBash,
+      stopAt = '',
+      recoverErrors = 0,
 
       useTabs = false,
       tabWidth = 2,
@@ -64,6 +93,7 @@ export const getProcessor = (
       spaceRedirects = true,
       keepPadding = false,
       minify = false,
+      singleLine = false,
       functionNextLine = false,
     }: ShOptions & { print?: boolean; originalText?: string } = {},
   ) {
@@ -110,17 +140,19 @@ export const getProcessor = (
         isAst: boolean,
 
         keepComments: boolean,
+        variant: LangVariant,
         stopAtPointer: number,
         stopAt0: number,
         stopAt1: number,
-        variant: LangVariant,
+        recoverErrors: number,
 
         indent: number,
         binaryNextLine: boolean,
         switchCaseIndent: boolean,
         spaceRedirects: boolean,
         keepPadding: boolean,
         minify: boolean,
+        singleLine: boolean,
         functionNextLine: boolean,
       ) => number
     }
@@ -150,17 +182,19 @@ export const getProcessor = (
       print,
 
       keepComments,
+      variant,
       stopAtPointer,
       uStopAt.byteLength,
       uStopAt.byteLength,
-      variant,
+      recoverErrors,
 
       indent,
       binaryNextLine,
       switchCaseIndent,
       spaceRedirects,
       keepPadding,
       minify,
+      singleLine,
       functionNextLine,
     )
 

src/processor.ts

@@ -11,8 +11,9 @@ export type LangVariant = ValueOf<typeof LangVariant>
 
 export interface ShParserOptions {
   keepComments?: boolean
-  stopAt?: string
   variant?: LangVariant
+  stopAt?: string
+  recoverErrors?: number
 }
 
 export interface ShPrinterOptions {
@@ -22,6 +23,7 @@ export interface ShPrinterOptions {
   spaceRedirects?: boolean
   keepPadding?: boolean
   minify?: boolean
+  singleLine?: boolean
   functionNextLine?: boolean
 }