header: rename MatchTemplate to Matcher (#5)

Author: joshuasing

README.md

@@ -24,7 +24,7 @@ A fast, easy-to-use, license header linter for Go.
 | Git support                 | ✅                               | Limited¹                                                  | ❌                                                         | ❌                                                            |
 | Exclude patterns            | ✅ (regexp & doublestar)         | ❌                                                         | ✅                                                         | ❓                                                            |
 | Uses Go `text/template`     | ✅                               | ❌                                                         | ✅                                                         | ❌                                                            |
-| Customise existing matcher  | ✅                               | ❌                                                         | ❌                                                         | ❌                                                            |
+| Customise header matcher    | ✅                               | ❌                                                         | ❌                                                         | ❌                                                            |
 | Supports non-Go files       | Planned                         | ❌                                                         | ✅                                                         | ❌                                                            |
 | Supported by golangci-lint  | Planned                         | ✅                                                         | ❌                                                         | ❌                                                            |
 
@@ -196,12 +196,15 @@ golicenser supports configuring the comment type used for the license headers. T
 golicenser allows changing the regexp matchers used to detect existing license headers, and to tell when they should be
 replaced.
 
-#### Match template
+#### Matcher
 
-The "match template" is a regexp expression used to match the license headers used by the project. Headers matched by
-this matcher will be updated or replaced.
+The matcher is a regexp expression used to match the license headers generated by golicenser (or otherwise used by the
+project). Matched headers are updated or replaced by golicenser.
 
-By default, the license header template will be used.
+By default, the regexp-escaped value of license header template will be used.
+
+In some cases it may be easier to provide the plain license header here, as such it is possible to set `MatcherEscape` (
+or `-matcher-escape`) to always regexp-escape the matcher value.
 
 ##### Variables
 
@@ -212,13 +215,14 @@ year changes).
 - `filename` - `.+`
 - `year` - `(\d{4})|(\d{4})-(\d{4])|(\d{4})(?:, (\d{4}))+` - Matches a single year, year range or listed years.
 
-#### Match header
+#### Copyright header matcher
 
-The "match header" is used to detect **any** copyright header. By default, `(?i)copyright` is used, however this can be
-customised in order to prevent false-positives.
+The copyright header matcher is used to detect **any** copyright header. By default, `(?i)copyright` is used, however 
+this can be customised in order to prevent false-positives.
 
-If a copyright header exists and does not match the [match template](#match-template), then a license header will not be
-created.
+If a copyright header exists and does not match the [header matcher](#matcher), then a license header will not be
+created. If a file starts with a comment that does not match the copyright header matcher, then a new license header
+will be generated.
 
 ## Contributing
 

analysis.go

@@ -36,9 +36,10 @@ import (
 const (
 	analyzerName = "golicenser"
 
-	// DefaultMatchHeaderRegexp is the default regexp used to detect license
-	// headers. This will match any header containing "copyright".
-	DefaultMatchHeaderRegexp = "(?i)copyright"
+	// DefaultCopyrightHeaderMatcher is the default regexp used to detect the
+	// existence of any copyright header  This will match any header containing
+	// "copyright".
+	DefaultCopyrightHeaderMatcher = "(?i)copyright"
 )
 
 var (
@@ -56,9 +57,9 @@ var (
 type Config struct {
 	Header HeaderOpts
 
-	Exclude           []string
-	MaxConcurrent     int
-	MatchHeaderRegexp string
+	Exclude                []string
+	MaxConcurrent          int
+	CopyrightHeaderMatcher string
 }
 
 // NewAnalyzer creates a golicenser analyzer.
@@ -92,8 +93,8 @@ func newAnalyzer(cfg Config) (*analyzer, error) {
 	if cfg.MaxConcurrent < 1 {
 		cfg.MaxConcurrent = DefaultMaxConcurrent
 	}
-	if cfg.MatchHeaderRegexp == "" {
-		cfg.MatchHeaderRegexp = DefaultMatchHeaderRegexp
+	if cfg.CopyrightHeaderMatcher == "" {
+		cfg.CopyrightHeaderMatcher = DefaultCopyrightHeaderMatcher
 	}
 	if cfg.Exclude == nil {
 		cfg.Exclude = DefaultExcludes
@@ -102,7 +103,7 @@ func newAnalyzer(cfg Config) (*analyzer, error) {
 	a := &analyzer{cfg: cfg}
 
 	var err error
-	a.headerMatcher, err = regexp.Compile(a.cfg.MatchHeaderRegexp)
+	a.headerMatcher, err = regexp.Compile(a.cfg.CopyrightHeaderMatcher)
 	if err != nil {
 		return nil, fmt.Errorf("compile match header regexp: %w", err)
 	}

analysis_test.go

@@ -78,4 +78,51 @@ func TestAnalyzer(t *testing.T) {
 			_ = analysistest.RunWithSuggestedFixes(t, packageDir, a)
 		})
 	})
+
+	t.Run("with matcher", func(t *testing.T) {
+		cfg := Config{
+			Header: HeaderOpts{
+				Template: "Copyright (c) {{.year}} {{.author}}",
+				Author:   "Test",
+				Matcher:  "Copyright \\(c\\) {{.year}} Joshua",
+				YearMode: YearModeThisYear,
+			},
+			Exclude: []string{},
+		}
+		a, err := NewAnalyzer(cfg)
+		if err != nil {
+			t.Fatalf("NewAnalyzer() err = %v", err)
+		}
+
+		// differentmatcher contains a header that will be matched by Matcher
+		// but is different from the Template.
+		t.Run("differentmatcher", func(t *testing.T) {
+			packageDir := filepath.Join(analysistest.TestData(), "src/differentmatcher/")
+			_ = analysistest.Run(t, packageDir, a)
+		})
+	})
+
+	t.Run("with escaped matcher", func(t *testing.T) {
+		cfg := Config{
+			Header: HeaderOpts{
+				Template:      "Copyright (c) {{.year}} {{.author}}",
+				Author:        "Test",
+				Matcher:       "Copyright (c) {{.year}} Joshua",
+				MatcherEscape: true,
+				YearMode:      YearModeThisYear,
+			},
+			Exclude: []string{},
+		}
+		a, err := NewAnalyzer(cfg)
+		if err != nil {
+			t.Fatalf("NewAnalyzer() err = %v", err)
+		}
+
+		// differentmatcher contains a header that will be matched with the
+		// escaped Matcher but is different from the Template.
+		t.Run("differentmatcher", func(t *testing.T) {
+			packageDir := filepath.Join(analysistest.TestData(), "src/differentmatcher/")
+			_ = analysistest.Run(t, packageDir, a)
+		})
+	})
 }

cmd/golicenser/golicenser.go

@@ -36,31 +36,31 @@ import (
 var flagSet flag.FlagSet
 
 var (
-	template            string
-	templateFile        string
-	matchTemplate       string
-	matchTemplateFile   string
-	matchTemplateEscape bool
-	author              string
-	authorRegexp        string
-	variables           string
-	yearModeStr         string
-	commentStyleStr     string
-	exclude             string
-	maxConcurrent       int
-	matchHeaderRegexp   string
+	template               string
+	templateFile           string
+	matcher                string
+	matcherFile            string
+	matcherEscape          bool
+	author                 string
+	authorRegexp           string
+	variables              string
+	yearModeStr            string
+	commentStyleStr        string
+	exclude                string
+	maxConcurrent          int
+	copyrightHeaderMatcher string
 )
 
 func init() {
 	flagSet.StringVar(&template, "tmpl", "", "License header template")
 	flagSet.StringVar(&templateFile, "tmpl-file", "license_header.txt",
 		"License header template file")
-	flagSet.StringVar(&matchTemplate, "match-tmpl", "",
-		"Match license header template")
-	flagSet.StringVar(&matchTemplateFile, "match-tmpl-file", "",
-		"Match license header template file (used to detect existing license headers which may be updated)")
-	flagSet.BoolVar(&matchTemplateEscape, "match-tmpl-escape", false,
-		"Whether to regexp-escape the match-tmpl")
+	flagSet.StringVar(&matcher, "matcher", "",
+		"License header matcher (This is template, when executed it must become valid regexp)")
+	flagSet.StringVar(&matcherFile, "matcher-file", "",
+		"License header matcher file)")
+	flagSet.BoolVar(&matcherEscape, "matcher-escape", false,
+		"Whether to regexp-escape the matcher")
 	flagSet.StringVar(&author, "author", "", "Copyright author")
 	flagSet.StringVar(&authorRegexp, "author-regexp", "",
 		"Regexp to match copyright author (default: match author)")
@@ -73,8 +73,8 @@ func init() {
 		"Paths to exclude (doublestar or r!-prefixed regexp, comma-separated)")
 	flagSet.IntVar(&maxConcurrent, "max-concurrent", golicenser.DefaultMaxConcurrent,
 		"Maximum concurrent processes to use when processing files")
-	flagSet.StringVar(&matchHeaderRegexp, "match-header-regexp", golicenser.DefaultMatchHeaderRegexp,
-		"Match header regexp (used to detect any copyright headers)")
+	flagSet.StringVar(&copyrightHeaderMatcher, "copyright-header-matcher", golicenser.DefaultCopyrightHeaderMatcher,
+		"Copyright header matcher regexp (used to detect existence of any copyright header)")
 }
 
 // TODO(joshuasing): There has to be a better way of doing this...
@@ -97,16 +97,16 @@ var analyzer = &analysis.Analyzer{
 				template = tm
 			}
 		}
-		if matchTemplate == "" && matchTemplateFile != "" {
+		if matcher == "" && matcherFile != "" {
 			//nolint:gosec // Reading user-defined file.
-			b, err := os.ReadFile(matchTemplateFile)
+			b, err := os.ReadFile(matcherFile)
 			if err != nil {
 				log.Fatal("read match template file: ", err)
 			}
-			matchTemplate = string(b)
+			matcher = string(b)
 		} else {
-			if tm, ok := golicenser.TemplateBySPDX(matchTemplate); ok {
-				matchTemplate = tm
+			if tm, ok := golicenser.TemplateBySPDX(matcher); ok {
+				matcher = tm
 			}
 		}
 
@@ -136,18 +136,18 @@ var analyzer = &analysis.Analyzer{
 
 		a, err := golicenser.NewAnalyzer(golicenser.Config{
 			Header: golicenser.HeaderOpts{
-				Template:            template,
-				MatchTemplate:       matchTemplate,
-				MatchTemplateEscape: matchTemplateEscape,
-				Author:              author,
-				AuthorRegexp:        authorRegexp,
-				Variables:           vars,
-				YearMode:            yearMode,
-				CommentStyle:        commentStyle,
+				Template:      template,
+				Matcher:       matcher,
+				MatcherEscape: matcherEscape,
+				Author:        author,
+				AuthorRegexp:  authorRegexp,
+				Variables:     vars,
+				YearMode:      yearMode,
+				CommentStyle:  commentStyle,
 			},
-			Exclude:           strings.Split(exclude, ","),
-			MaxConcurrent:     maxConcurrent,
-			MatchHeaderRegexp: matchHeaderRegexp,
+			Exclude:                strings.Split(exclude, ","),
+			MaxConcurrent:          maxConcurrent,
+			CopyrightHeaderMatcher: copyrightHeaderMatcher,
 		})
 		if err != nil {
 			log.Fatal(err)

header.go

@@ -232,14 +232,14 @@ var tmplFuncMap = template.FuncMap{
 
 // HeaderOpts are the options for creating a license header.
 type HeaderOpts struct {
-	Template            string
-	MatchTemplate       string
-	MatchTemplateEscape bool
-	Author              string
-	AuthorRegexp        string
-	Variables           map[string]any
-	YearMode            YearMode
-	CommentStyle        CommentStyle
+	Template      string
+	Matcher       string
+	MatcherEscape bool
+	Author        string
+	AuthorRegexp  string
+	Variables     map[string]any
+	YearMode      YearMode
+	CommentStyle  CommentStyle
 }
 
 // NewHeader creates a new header with the given options.
@@ -280,13 +280,13 @@ func NewHeader(opts HeaderOpts) (*Header, error) {
 	}
 
 	var matcher *regexp.Regexp
-	if opts.MatchTemplate != "" {
+	if opts.Matcher != "" {
 		mt, err := template.New("").Funcs(tmplFuncMap).
-			Option("missingkey=error").Parse(opts.MatchTemplate)
+			Option("missingkey=error").Parse(opts.Matcher)
 		if err != nil {
 			return nil, fmt.Errorf("new match template: %w", err)
 		}
-		matcher, err = headerMatcher(mt, opts.MatchTemplateEscape, authorRegexp, opts.Variables)
+		matcher, err = headerMatcher(mt, opts.MatcherEscape, authorRegexp, opts.Variables)
 		if err != nil {
 			return nil, fmt.Errorf("create header matcher (with match template): %w", err)
 		}

header_test.go

@@ -281,10 +281,10 @@ func TestHeaderUpdate(t *testing.T) {
 		{
 			name: "change MIT to OpenBSD",
 			header: HeaderOpts{
-				Template:            LicenseOpenBSD,
-				MatchTemplate:       LicenseMIT,
-				MatchTemplateEscape: true,
-				Author:              "Joshua Sing",
+				Template:      LicenseOpenBSD,
+				Matcher:       LicenseMIT,
+				MatcherEscape: true,
+				Author:        "Joshua Sing",
 			},
 			wantModified: true,
 			existing: `// Copyright (c) 2025 Joshua Sing

testdata/src/differentmatcher/main.go

@@ -0,0 +1,5 @@
+// Copyright (c) 2025 Joshua // want "invalid license header"
+// This header is different, but should be matched by the header matcher and
+// be replaced.
+
+package differentmatcher

testdata/src/differentmatcher/main.go.golden

@@ -0,0 +1,3 @@
+// Copyright (c) 2025 Test
+
+package differentmatcher