chore: extract comment shortener into dedicated package

Author: ldez

shorten/.gitattributes

@@ -1,2 +1,3 @@
 /testdata/** text eol=lf
 /internal/graph/testdata/** text eol=lf
+/internal/comments/testdata/** text eol=lf

shorten/annotations.go

@@ -3,7 +3,9 @@ package shorten
 import (
 	"strings"
 
+	"github.com/golangci/golines/shorten/internal"
 	"github.com/golangci/golines/shorten/internal/annotation"
+	"github.com/golangci/golines/shorten/internal/comments"
 )
 
 // annotateLongLines adds specially formatted comments to all eligible lines that
@@ -17,7 +19,7 @@ func (s *Shortener) annotateLongLines(lines []string) ([]string, int) {
 	prevLen := -1
 
 	for _, line := range lines {
-		length := s.lineLen(line)
+		length := internal.LineLength(line, s.config.TabLen)
 
 		if prevLen > -1 {
 			if length <= s.config.MaxLen {
@@ -28,7 +30,7 @@ func (s *Shortener) annotateLongLines(lines []string) ([]string, int) {
 				annotatedLines[len(annotatedLines)-1] = annotation.Create(length)
 				linesToShorten++
 			}
-		} else if !isComment(line) && length > s.config.MaxLen {
+		} else if !comments.Is(line) && length > s.config.MaxLen {
 			annotatedLines = append(
 				annotatedLines,
 				annotation.Create(length),

shorten/comments.go renamed to shorten/internal/comments/comments.go

@@ -1,33 +1,48 @@
-package shorten
+package comments
 
 import (
 	"fmt"
 	"regexp"
 	"strings"
 
+	"github.com/golangci/golines/shorten/internal"
 	"github.com/golangci/golines/shorten/internal/annotation"
 )
 
+// Shortener is a struct that can be used to shorten long comments.
+//
+// As noted in the repo README,
+// this functionality has some quirks and is disabled by default.
+type Shortener struct {
+	MaxLen int
+	TabLen int
+}
+
 // Go directive (should be ignored).
 // https://go.dev/doc/comment#syntax
 var directivePattern = regexp.MustCompile(`\s*//(line |extern |export |[a-z0-9]+:[a-z0-9])`)
 
-// shortenCommentsFunc attempts to shorten long comments in the provided source.
+// Process attempts to shorten long comments in the provided source.
 //
 // As noted in the repo README,
 // this functionality has some quirks and is disabled by default.
-func (s *Shortener) shortenCommentsFunc(content []byte) []byte {
+func (s *Shortener) Process(content []byte) []byte {
+	if len(content) == 0 {
+		return content
+	}
+
 	var cleanedLines []string
 
-	var words []string // all words in a contiguous sequence of long comments
+	// all words in a contiguous sequence of long comments
+	var words []string
 
 	prefix := ""
 
 	lines := strings.SplitSeq(string(content), "\n")
 	for line := range lines {
-		if isComment(line) && !annotation.Is(line) &&
+		if Is(line) && !annotation.Is(line) &&
 			!isDirective(line) &&
-			s.lineLen(line) > s.config.MaxLen {
+			internal.LineLength(line, s.TabLen) > s.MaxLen {
 			start := strings.Index(line, "//")
 			prefix = line[0:(start + 2)]
 			trimmedLine := strings.Trim(line[(start+2):], " ")
@@ -39,7 +54,7 @@ func (s *Shortener) shortenCommentsFunc(content []byte) []byte {
 
 			var currLineWords []string
 
-			maxCommentLen := s.config.MaxLen - s.lineLen(prefix)
+			maxCommentLen := s.MaxLen - internal.LineLength(prefix, s.TabLen)
 			for _, word := range words {
 				if currLineLen > 0 && currLineLen+1+len(word) > maxCommentLen {
 					cleanedLines = append(
@@ -78,12 +93,12 @@ func (s *Shortener) shortenCommentsFunc(content []byte) []byte {
 	return []byte(strings.Join(cleanedLines, "\n"))
 }
 
+// Is determines whether the provided line is a non-block comment.
+func Is(line string) bool {
+	return strings.HasPrefix(strings.Trim(line, " \t"), "//")
+}
+
 // isDirective determines whether the provided line is a directive, e.g., for `go:generate`.
 func isDirective(line string) bool {
 	return directivePattern.MatchString(line)
 }
-
-// isComment determines whether the provided line is a non-block comment.
-func isComment(line string) bool {
-	return strings.HasPrefix(strings.Trim(line, " \t"), "//")
-}

shorten/internal/comments/comments_test.go

@@ -0,0 +1,23 @@
+package comments
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestShortener_Process(t *testing.T) {
+	cs := &Shortener{MaxLen: 100, TabLen: 4}
+
+	src, err := os.ReadFile("testdata/comments.go")
+	require.NoError(t, err)
+
+	result := cs.Process(src)
+
+	expectedContent, err := os.ReadFile("testdata/comments.go.golden")
+	require.NoError(t, err)
+
+	assert.Equal(t, string(expectedContent), string(result))
+}

shorten/internal/comments/testdata/comments.go

@@ -0,0 +1,38 @@
+package testdata
+
+import "fmt"
+
+// Short prefix
+// This is a really, really long comment on a single line. We should try to break it up if possible because it's longer than 100 chars. In fact, it's so long that it should probably be on three lines instead of two. Wow, so long!!
+// Short suffix
+//
+
+// This comment contains multiple contiguous lines which are greater than the target maximum line length.
+// The expected result is a sequence of shortened (reflown) lines without preserving the position of line breaks.
+
+// Another comment
+
+/*
+	A block comment. Really long lines in here aren't currently processed because they're a bit harder to handle.
+
+	func(aReallyLongArgument string, anotherReallyLongArgument string, aThirdReallyLongArgument string) (string, error) {
+		return "", nil
+	}
+*/
+//go:generate this is a really long go generate line. We don't want to shorten this because that could cause problems running go generate.
+func _() {
+	for i := 0; i < 10; i++ {
+		if i > 5 {
+			// This is a another really, really long comment on a single line. We should try to break it up if possible because it's longer than 100 chars.
+			fmt.Print("hello")
+
+			// These are comments like the ones in https://github.com/segmentio/golines/issues/9
+			//
+			// Documentation: https://swagger.io/docs/specification/authentication/bearer-authentication/more/more/more/more/more
+			//
+			// More documentation:
+			// https://swagger.io/docs/specification/authentication/bearer-authentication/more/more/more/more/more
+			fmt.Println("Hello again")
+		}
+	}
+}

shorten/internal/comments/testdata/comments.go.golden

@@ -0,0 +1,43 @@
+package testdata
+
+import "fmt"
+
+// Short prefix
+// This is a really, really long comment on a single line. We should try to break it up if possible
+// because it's longer than 100 chars. In fact, it's so long that it should probably be on three
+// lines instead of two. Wow, so long!!
+// Short suffix
+//
+
+// This comment contains multiple contiguous lines which are greater than the target maximum line
+// length. The expected result is a sequence of shortened (reflown) lines without preserving the
+// position of line breaks.
+
+// Another comment
+
+/*
+	A block comment. Really long lines in here aren't currently processed because they're a bit harder to handle.
+
+	func(aReallyLongArgument string, anotherReallyLongArgument string, aThirdReallyLongArgument string) (string, error) {
+		return "", nil
+	}
+*/
+//go:generate this is a really long go generate line. We don't want to shorten this because that could cause problems running go generate.
+func _() {
+	for i := 0; i < 10; i++ {
+		if i > 5 {
+			// This is a another really, really long comment on a single line. We should try to
+			// break it up if possible because it's longer than 100 chars.
+			fmt.Print("hello")
+
+			// These are comments like the ones in https://github.com/segmentio/golines/issues/9
+			//
+			// Documentation:
+			// https://swagger.io/docs/specification/authentication/bearer-authentication/more/more/more/more/more
+			//
+			// More documentation:
+			// https://swagger.io/docs/specification/authentication/bearer-authentication/more/more/more/more/more
+			fmt.Println("Hello again")
+		}
+	}
+}

shorten/internal/line.go

@@ -0,0 +1,16 @@
+package internal
+
+// LineLength gets the width of the provided line after tab expansion.
+func LineLength(line string, tabLen int) int {
+	length := 0
+
+	for _, char := range line {
+		if char == '\t' {
+			length += tabLen
+		} else {
+			length++
+		}
+	}
+
+	return length
+}

shorten/shortener.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/dave/dst"
 	"github.com/dave/dst/decorator"
+	"github.com/golangci/golines/shorten/internal/comments"
 	"github.com/golangci/golines/shorten/internal/graph"
 	"github.com/golangci/golines/shorten/internal/tags"
 )
@@ -72,6 +73,8 @@ func WithLogger(logger Logger) Options {
 type Shortener struct {
 	config *Config
 
+	cs *comments.Shortener
+
 	logger Logger
 }
 
@@ -86,6 +89,13 @@ func NewShortener(config *Config, opts ...Options) *Shortener {
 		logger: &noopLogger{},
 	}
 
+	if config.ShortenComments {
+		s.cs = &comments.Shortener{
+			MaxLen: config.MaxLen,
+			TabLen: config.TabLen,
+		}
+	}
+
 	for _, opt := range opts {
 		opt(s)
 	}
@@ -173,8 +183,8 @@ func (s *Shortener) Process(content []byte) ([]byte, error) {
 		content = removeAnnotations(content)
 	}
 
-	if s.config.ShortenComments {
-		content = s.shortenCommentsFunc(content)
+	if s.cs != nil {
+		content = s.cs.Process(content)
 	}
 
 	// Do the final round of non-line-length-aware formatting after we've fixed up the comments
@@ -186,21 +196,6 @@ func (s *Shortener) Process(content []byte) ([]byte, error) {
 	return content, nil
 }
 
-// lineLen gets the width of the provided line after tab expansion.
-func (s *Shortener) lineLen(line string) int {
-	length := 0
-
-	for _, char := range line {
-		if char == '\t' {
-			length += s.config.TabLen
-		} else {
-			length++
-		}
-	}
-
-	return length
-}
-
 func (s *Shortener) createDot(result dst.Node) error {
 	dotFile, err := os.Create(s.config.DotFile)
 	if err != nil {