chore: update dependencies and improve code documentation

Author: johnnyjoygh

.github/workflows/backend-tests.yml

@@ -26,9 +26,9 @@ jobs:
           go mod tidy -go=1.21
           git diff --exit-code
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v6
+        uses: golangci/golangci-lint-action@v8
         with:
-          version: v1.56.1
+          version: v2.4.0
           args: --verbose --timeout=3m
           skip-cache: true
 

.golangci.yaml

@@ -1,9 +1,11 @@
+version: "2"
+
 run:
   timeout: 10m
+
 linters:
   enable:
     - errcheck
-    - goimports
     - revive
     - govet
     - staticcheck
@@ -16,69 +18,73 @@ linters:
     - forbidigo
     - mirror
     - bodyclose
+  settings:
+    revive:
+      # Run entire rule set and selectively disable the ones that are too strict for now.
+      enable-all-rules: true
+      rules:
+        - name: file-header
+          disabled: true
+        - name: line-length-limit
+          disabled: true
+        - name: function-length
+          disabled: true
+        - name: max-public-structs
+          disabled: true
+        - name: function-result-limit
+          disabled: true
+        - name: banned-characters
+          disabled: true
+        - name: argument-limit
+          disabled: true
+        - name: cognitive-complexity
+          disabled: true
+        - name: cyclomatic
+          disabled: true
+        - name: confusing-results
+          disabled: true
+        - name: add-constant
+          disabled: true
+        - name: flag-parameter
+          disabled: true
+        - name: nested-structs
+          disabled: true
+        - name: import-shadowing
+          disabled: true
+        - name: early-return
+          disabled: true
+        - name: use-any
+          disabled: true
+        - name: exported
+          disabled: true
+        - name: unhandled-error
+          disabled: true
+        - name: if-return
+          disabled: true
+        - name: max-control-nesting
+          disabled: true
+    gocritic:
+      disabled-checks:
+        - ifElseChain
+    govet:
+      enable-all: true
+      disable:
+        - fieldalignment
+        - shadow
+      settings:
+        printf:
+          funcs:
+            - common.Errorf
+    forbidigo:
+      forbid:
+        - pattern: 'fmt\\.Errorf(# Please use errors\\.Wrap\\|Wrapf\\|Errorf instead)?'
+        - pattern: 'ioutil\\.ReadDir(# Please use os\\.ReadDir)?'
 
-linters-settings:
-  goimports:
-    # Put imports beginning with prefix after 3rd-party packages.
-    local-prefixes: github.com/usememos/memos
-  revive:
-    # Default to run all linters so that new rules in the future could automatically be added to the static check.
-    enable-all-rules: true
-    rules:
-      # The following rules are too strict and make coding harder. We do not enable them for now.
-      - name: file-header
-        disabled: true
-      - name: line-length-limit
-        disabled: true
-      - name: function-length
-        disabled: true
-      - name: max-public-structs
-        disabled: true
-      - name: function-result-limit
-        disabled: true
-      - name: banned-characters
-        disabled: true
-      - name: argument-limit
-        disabled: true
-      - name: cognitive-complexity
-        disabled: true
-      - name: cyclomatic
-        disabled: true
-      - name: confusing-results
-        disabled: true
-      - name: add-constant
-        disabled: true
-      - name: flag-parameter
-        disabled: true
-      - name: nested-structs
-        disabled: true
-      - name: import-shadowing
-        disabled: true
-      - name: early-return
-        disabled: true
-      - name: use-any
-        disabled: true
-      - name: exported
-        disabled: true
-      - name: unhandled-error
-        disabled: true
-      - name: if-return
-        disabled: true
-      - name: max-control-nesting
-        disabled: true
-  gocritic:
-    disabled-checks:
-      - ifElseChain
-  govet:
-    settings:
-      printf: # The name of the analyzer, run `go tool vet help` to see the list of all analyzers
-        funcs: # Run `go tool vet help printf` to see the full configuration of `printf`.
-          - common.Errorf
-    enable-all: true
-    disable:
-      - fieldalignment
-      - shadow
-  forbidigo:
-    forbid:
-      - 'fmt\.Errorf(# Please use errors\.Wrap\|Wrapf\|Errorf instead)?'
-      - 'ioutil\.ReadDir(# Please use os\.ReadDir)?'
+formatters:
+  enable:
+    - goimports
+  settings:
+    goimports:
+      # Keep local modules grouped after 3rd-party imports.
+      local-prefixes:
+        - github.com/usememos/memos

ast/ast.go

@@ -1,3 +1,4 @@
+// Package ast defines the abstract syntax tree nodes used by gomark.
 package ast
 
 type NodeType string

ast/document.go

@@ -27,9 +27,9 @@ func (d *Document) CloneMetadata() map[string]any {
 	if len(d.Metadata) == 0 {
 		return nil
 	}
-	copy := make(map[string]any, len(d.Metadata))
+	metadataCopy := make(map[string]any, len(d.Metadata))
 	for k, v := range d.Metadata {
-		copy[k] = v
+		metadataCopy[k] = v
 	}
-	return copy
+	return metadataCopy
 }

config/config.go

@@ -1,3 +1,4 @@
+// Package config provides configuration structures for the gomark parser.
 package config
 
 // ParserConfig holds configuration options for the parser.
@@ -188,6 +189,8 @@ func (c *ParserConfig) WithExtension(name string, enabled bool) *ParserConfig {
 		config.EnableExtensions.ReferencedContent = enabled
 	case "tags":
 		config.EnableExtensions.Tags = enabled
+	default:
+		return config
 	}
 	return config
 }
@@ -225,4 +228,4 @@ func (c *ParserConfig) WithMaxFileSize(size int64) *ParserConfig {
 	config := c.Clone()
 	config.MaxFileSize = size
 	return config
-}
+}

gomark.go

@@ -1,3 +1,4 @@
+// Package gomark exposes high-level parsing and rendering helpers.
 package gomark
 
 import (
@@ -73,7 +74,7 @@ func (e *Engine) Parse(markdown string) (*ast.Document, error) {
 }
 
 // Restore renders the AST document to markdown.
-func (e *Engine) Restore(doc *ast.Document) string {
+func (*Engine) Restore(doc *ast.Document) string {
 	if doc == nil {
 		return ""
 	}

parser/errors.go

@@ -2,6 +2,7 @@ package parser
 
 import (
 	"fmt"
+
 	"github.com/usememos/gomark/parser/tokenizer"
 )
 
@@ -104,8 +105,8 @@ func NewIncompleteElementError(element string, position int) *ParseError {
 
 // ParseResult wraps parsing results with error information.
 type ParseResult struct {
-	Success bool
-	Errors  []*ParseError
+	Success  bool
+	Errors   []*ParseError
 	Warnings []*ParseError
 }
 
@@ -145,4 +146,4 @@ func NewParseResult() *ParseResult {
 		Errors:   []*ParseError{},
 		Warnings: []*ParseError{},
 	}
-}
+}

parser/internal/code_block.go

@@ -27,25 +27,22 @@ func (*CodeBlockParser) Match(tokens []*tokenizer.Token) (ast.Node, int) {
 		return nil, 0
 	}
 
-	// Check for new-style triple backtick token or legacy three separate tokens
-	if firstRow[0].Type == tokenizer.TripleBacktick {
-		// New tokenizer style
-	} else if len(firstRow) >= 3 && firstRow[0].Type == tokenizer.Backtick && firstRow[1].Type == tokenizer.Backtick && firstRow[2].Type == tokenizer.Backtick {
-		// Legacy tokenizer style
-	} else {
+	// Check for new-style triple backtick token or legacy three separate tokens.
+	isNewStyle := firstRow[0].Type == tokenizer.TripleBacktick
+	isLegacyStyle := len(firstRow) >= 3 && firstRow[0].Type == tokenizer.Backtick && firstRow[1].Type == tokenizer.Backtick && firstRow[2].Type == tokenizer.Backtick
+	if !isNewStyle && !isLegacyStyle {
 		return nil, 0
 	}
-	languageTokens := []*tokenizer.Token{}
-	if firstRow[0].Type == tokenizer.TripleBacktick {
-		// New tokenizer style - language tokens start at index 1
+
+	var languageTokens []*tokenizer.Token
+	if isNewStyle {
+		// New tokenizer style - language tokens start at index 1.
 		if len(firstRow) > 1 {
 			languageTokens = firstRow[1:]
 		}
-	} else {
-		// Legacy tokenizer style - language tokens start at index 3
-		if len(firstRow) > 3 {
-			languageTokens = firstRow[3:]
-		}
+	} else if len(firstRow) > 3 {
+		// Legacy tokenizer style - language tokens start at index 3.
+		languageTokens = firstRow[3:]
 	}
 
 	// Check if language is valid.

parser/internal/ordered_list_item.go

@@ -16,16 +16,18 @@ func (*OrderedListItemParser) Match(tokens []*tokenizer.Token) (ast.Node, int) {
 	indent := 0
 	consumedTokens := 0
 
-	// Handle both new-style consolidated spaces and legacy individual spaces
+	// Handle both new-style consolidated spaces and legacy individual spaces.
+spaceScan:
 	for i, token := range matchedTokens {
-		if token.Type == tokenizer.Space {
+		switch token.Type {
+		case tokenizer.Space:
 			indent++
 			consumedTokens = i + 1
-		} else if token.Type == tokenizer.MultipleSpaces {
-			indent = len(token.Value) // Count the actual spaces in the consolidated token
+		case tokenizer.MultipleSpaces:
+			indent = len(token.Value) // Count the actual spaces in the consolidated token.
 			consumedTokens = i + 1
-		} else {
-			break
+		default:
+			break spaceScan
 		}
 	}
 

parser/internal/parser.go

@@ -1,16 +1,17 @@
+// Package internal contains parser implementations used by gomark.
 package internal
 
 import (
 	"github.com/usememos/gomark/ast"
 	"github.com/usememos/gomark/parser/tokenizer"
 )
 
-// ParseInline parses inline tokens into AST nodes
+// ParseInline parses inline tokens into AST nodes.
 func ParseInline(tokens []*tokenizer.Token) ([]ast.Node, error) {
 	return ParseInlineWithParsers(tokens, getDefaultInlineParsers())
 }
 
-// ParseInlineWithParsers parses inline tokens using the provided parsers
+// ParseInlineWithParsers parses inline tokens using the provided parsers.
 func ParseInlineWithParsers(tokens []*tokenizer.Token, inlineParsers []InlineParser) ([]ast.Node, error) {
 	nodes := []ast.Node{}
 	for len(tokens) > 0 {
@@ -33,12 +34,12 @@ func ParseInlineWithParsers(tokens []*tokenizer.Token, inlineParsers []InlinePar
 	return mergeTextNodes(nodes), nil
 }
 
-// ParseBlock parses block tokens into AST nodes using default parsers
+// ParseBlock parses block tokens into AST nodes using default parsers.
 func ParseBlock(tokens []*tokenizer.Token) ([]ast.Node, error) {
 	return ParseBlockWithParsers(tokens, getDefaultBlockParsers())
 }
 
-// ParseBlockWithParsers parses block tokens using the provided parsers
+// ParseBlockWithParsers parses block tokens using the provided parsers.
 func ParseBlockWithParsers(tokens []*tokenizer.Token, blockParsers []BlockParser) ([]ast.Node, error) {
 	// Set lookahead parsers for any paragraph parsers
 	for _, parser := range blockParsers {
@@ -106,7 +107,7 @@ func ParseBlockWithParsers(tokens []*tokenizer.Token, blockParsers []BlockParser
 	return nodes, nil
 }
 
-// getDefaultInlineParsers returns the default set of inline parsers
+// getDefaultInlineParsers returns the default set of inline parsers.
 func getDefaultInlineParsers() []InlineParser {
 	return []InlineParser{
 		NewEscapingCharacterParser(),
@@ -131,7 +132,7 @@ func getDefaultInlineParsers() []InlineParser {
 	}
 }
 
-// getDefaultBlockParsers returns the default set of block parsers
+// getDefaultBlockParsers returns the default set of block parsers.
 func getDefaultBlockParsers() []BlockParser {
 	paragraph := NewParagraphParser()
 	parsers := []BlockParser{
@@ -151,7 +152,7 @@ func getDefaultBlockParsers() []BlockParser {
 	return parsers
 }
 
-// mergeTextNodes merges consecutive text nodes
+// mergeTextNodes merges consecutive text nodes.
 func mergeTextNodes(nodes []ast.Node) []ast.Node {
 	if len(nodes) == 0 {
 		return nodes
@@ -167,7 +168,7 @@ func mergeTextNodes(nodes []ast.Node) []ast.Node {
 	return result
 }
 
-// mergeListItemNodes merges list item nodes into list structures
+// mergeListItemNodes merges list item nodes into list structures.
 func mergeListItemNodes(nodes []ast.Node) []ast.Node {
 	var result []ast.Node
 	var stack []*ast.List
@@ -218,4 +219,4 @@ func mergeListItemNodes(nodes []ast.Node) []ast.Node {
 	}
 
 	return result
-}
+}