dmitri.shuralyov.com/go/generated/...

create parser for generated comment proposed specification

This new package contains an initial attempt at implementing a parser
for the currently proposed specification for generated disclaimer
comment in golang.org/issue/13560.
dmitshur committed 5 years ago commit 1fe745ad0baf2ebe14f78bc10ed6ffdc131cdce0
LICENSE
@@ -0,0 +1,27 @@
Copyright (c) 2017 The Go Authors. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
   * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
generated.go
@@ -0,0 +1,81 @@
// Package generated provides a function that parses a Go file and reports
// whether it contains a "// Code generated … DO NOT EDIT." line comment.
//
// It's intended to stay up to date with the specification proposal in
// https://golang.org/issues/13560.
//
// The first priority is correctness (no false negatives, no false positives).
// It must return accurate results even if the input Go source code is not gofmted.
// The second priority is performance. The current version is implemented
// via go/parser, but it may be possible to improve performance via an
// alternative implementation. That can be explored later.
//
// The exact API is undecided and can change. The current API style is somewhat
// based on go/parser, but that may not be the best approach.
package generated

import (
	"go/parser"
	"go/token"
	"strings"
)

// ParseFile parses the source code of a single Go source file
// specified by filename, and reports whether the file contains
// a "// Code generated ... DO NOT EDIT." line comment
// matching the specification proposal in
// https://golang.org/issues/13560#issuecomment-277804473:
//
// 	The text must appear as the first line of a properly formatted Go // comment,
// 	and that comment must appear before but not be attached to the package clause
// 	and before any /* */ comment. This is similar to the rules for build tags.
//
// 	The comment line must match the case-sensitive regular expression (in Go syntax):
//
// 		^// Code generated .* DO NOT EDIT\.$
//
// 	The .* means the tool can put whatever folderol it wants in there,
// 	but the comment must be a single line and must start with Code generated
// 	and end with DO NOT EDIT., with a period.
//
// If the source couldn't be read, the error indicates the specific
// failure. If the source was read but syntax errors were found,
// the result is estimated on a best effort basis from a partial AST.
//
// TODO: Decide on best policy of what to do in case of syntax errors
// being encountered during parsing.
func ParseFile(filename string) (hasGeneratedComment bool, err error) {
	fset := token.NewFileSet()
	f, err := parser.ParseFile(fset, filename, nil, parser.PackageClauseOnly|parser.ParseComments)
	if f == nil { // Can only happen when err != nil.
		return false, err
	}
Outer:
	for _, cg := range f.Comments {
		if cg == f.Doc {
			// If we've reached the package comment, don't look any further,
			// because the generated comment must be before that.
			break
		}
		// Check if this comment group is a match.
		// The text must appear as the first line of a properly formatted line comment (//-style).
		if len(cg.List[0].Text) >= smallestMatchingComment &&
			strings.HasPrefix(cg.List[0].Text, "// Code generated ") &&
			strings.HasSuffix(cg.List[0].Text, " DO NOT EDIT.") &&
			fset.Position(cg.List[0].Pos()).Column == 1 {

			return true, nil
		}
		// Ensure none of the comments in this comment group are general comments (/*-style).
		for _, c := range cg.List {
			if strings.HasPrefix(c.Text, "/*") {
				// If we've reached a general comment (/*-style), don't look any further,
				// because the generated comment must be before that.
				break Outer
			}
		}
	}
	return false, nil
}

const smallestMatchingComment = len("// Code generated  DO NOT EDIT.")
generated_test.go
@@ -0,0 +1,45 @@
package generated_test

import (
	"path/filepath"
	"testing"

	"dmitri.shuralyov.com/go/generated"
)

func TestParseFile(t *testing.T) {
	tests := []struct {
		name string
		want bool
	}{
		// Positive matches.
		{"positive.0.src", true},
		{"positive.1.src", true},
		{"positive.2.src", true},
		{"positive.3.src", true},
		{"positive.4.src", true},

		// Negative matches.
		{"negative.0.src", false},
		{"negative.1.src", false},
		{"negative.2.src", false},
		{"negative.3.src", false},
		{"negative.4.src", false},
		{"negative.5.src", false},
		{"negative.6.src", false},
		{"negative.7.src", false},
		{"negative.8.src", false},
	}
	for _, tc := range tests {
		tc := tc
		t.Run(tc.name, func(t *testing.T) {
			hasGeneratedComment, err := generated.ParseFile(filepath.Join("testdata", tc.name))
			if err != nil {
				t.Fatal(err)
			}
			if got, want := hasGeneratedComment, tc.want; got != want {
				t.Errorf("got hasGeneratedComment %v, want %v", got, want)
			}
		})
	}
}
testdata/negative.0.src
@@ -0,0 +1,7 @@
// Code generated by tool; do NOT edit!!!

// +build !dev

package p

// Doesn't match because the string isn't an exact match.
testdata/negative.1.src
@@ -0,0 +1,10 @@
// stuff

// not really
// Code generated by tool; DO NOT EDIT.

// +build !dev

package p

// Doesn't match because it's not the first line of a // comment.
testdata/negative.2.src
@@ -0,0 +1,17 @@
// stuff

/*
definitely
not
after
this
*/

// Code generated by tool; DO NOT EDIT.

// +build !dev

// Package comment.
package p

// Doesn't match because it comes after general comment (/*-style).
testdata/negative.3.src
@@ -0,0 +1,4 @@
// Code generated by tool; DO NOT EDIT.
package p

// Doesn't match because it's a part of the package comment.
testdata/negative.4.src
@@ -0,0 +1,7 @@
    // Code generated by tool; DO NOT EDIT.

// +build !dev

package p

// Doesn't match because it's not a properly formatted // comment (doesn't begin on column 1).
testdata/negative.5.src
@@ -0,0 +1,12 @@
// stuff
/* not after this */
// stuff

// Code generated by tool; DO NOT EDIT.

// +build !dev

// Package comment.
package p

// Doesn't match because it comes after general comment (/*-style).
testdata/negative.6.src
@@ -0,0 +1,12 @@
   		  // stuff
   		  /* not after this */
   		  // stuff

// Code generated by tool; DO NOT EDIT.

    // +build !dev

     // Package comment.
package p

// Doesn't match because it comes after general comment (/*-style).
testdata/negative.7.src
@@ -0,0 +1,12 @@
/* start of a general comment

// Code generated by tool; DO NOT EDIT.

end of a general comment */

// +build !dev

// Package comment.
package p

// Doesn't match because it's inside general comment (/*-style).
testdata/negative.8.src
@@ -0,0 +1,5 @@
// Code generated DO NOT EDIT.

package p

// Doesn't match because the string isn't an exact match (too short).
testdata/positive.0.src
@@ -0,0 +1,5 @@
// Code generated by tool; DO NOT EDIT.

// +build !dev

package p
testdata/positive.1.src
@@ -0,0 +1,16 @@
// stuff

// Code generated by tool; DO NOT EDIT.
// yes really
/*
still so
even
after
this
*/
// stuff

// +build !dev

// Package comment.
package p
testdata/positive.2.src
@@ -0,0 +1,16 @@
// stuff

// Code generated by tool; DO NOT EDIT.
   // yes really
 /*
  still so
   even
    after
     this
    */
      // stuff

// +build !dev

// Package comment.
package p
testdata/positive.3.src
@@ -0,0 +1,10 @@
   		  // stuff
   		  // /* even after this */
   		  // stuff

// Code generated by tool; DO NOT EDIT.

    // +build !dev

     // Package comment.
package p
testdata/positive.4.src
@@ -0,0 +1,5 @@
// Code generated  DO NOT EDIT.

package p

// Shortest possible match.