Add gotmpl tool (#280)

* Add gotmpl tool

* Apply suggestions from code review

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

* Update package comment

* Add TestComplex

---------

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

.chloggen/gotmpl.yaml

@@ -0,0 +1,16 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the component, or a single word describing the area of concern, (e.g. crosslink)
+component: gotmpl
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add gotmpl tool to allow using text/template via CLI.
+
+# One or more tracking issues related to the change
+issues: [276]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.gitignore

@@ -13,5 +13,6 @@ chloggen/chloggen
 crosslink/crosslink
 dbotconf/dbotconf
 issuegenerator/issuegenerator
+gotmpl/gotmpl
 multimod/multimod
 semconvgen/semconvgen

.markdownlint.yaml

@@ -0,0 +1,7 @@
+# Default state for all rules
+default: true
+
+# Configure long lines for tables and code blocks
+MD013:
+  code_blocks: false
+  tables: false

gotmpl/README.md

@@ -0,0 +1,32 @@
+# gotmpl
+
+`gotmpl` is a tool
+to generate files
+from [templates](https://pkg.go.dev/text/template) and JSON data.
+
+## Usage
+
+```sh
+Usage of gotmpl:
+  -b, --body string   Template body filepath.
+  -d, --data string   Data in JSON format.
+  -o, --out string    Output filepath.
+```
+
+## Background
+
+`gotmpl` has been created as one of the solutions
+to avoid depending on internal packages of different modules.
+Such dependencies could transitively lead to build failure
+when an internal package API introduces a non-backward compatible change.
+
+`gotmpl` can be used for sharing non-exported
+common code across multiple Go modules.
+It is advised to keep the shared code in a separate internal Go module
+(e.g. under `internal/shared`).
+The shared code should be consumed across modules using `go generate`,
+for example:
+
+```go
+//go:generate gotmpl --body=../internal/shared/env.go.tmpl "--data={ \"pkg\": \"jaeger\" }" --out=env.go
+```

gotmpl/go.mod

@@ -0,0 +1,14 @@
+module go.opentelemetry.io/build-tools/gotmpl
+
+go 1.19
+
+require (
+	github.com/spf13/pflag v1.0.5
+	github.com/stretchr/testify v1.8.2
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

gotmpl/go.sum

@@ -0,0 +1,19 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
+github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

gotmpl/gotmpl.go

@@ -0,0 +1,60 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"text/template"
+)
+
+// gotmpl uses [text/template] package to generate a file using
+// bodyPath as template body filepath,
+// jsonData as data in JSON format,
+// outPath as output filepath.
+func gotmpl(bodyPath, jsonData, outPath string) error {
+	if bodyPath == "" {
+		return errors.New("gotmpl: template body filepath must be set")
+	}
+	if outPath == "" {
+		return errors.New("gotmpl: output filepath must be set")
+	}
+
+	tmpl, err := template.ParseFiles(bodyPath)
+	if err != nil {
+		return fmt.Errorf("gotmpl: cannot parse template body file: %w", err)
+	}
+
+	var data any
+	if err = json.Unmarshal(([]byte)(jsonData), &data); err != nil {
+		return fmt.Errorf("gotmpl: data must be in JSON format: %w", err)
+	}
+
+	outFile, err := os.Create(outPath) //nolint:gosec // This is a file generation tool that takes filepath as output.
+	if err != nil {
+		return fmt.Errorf("gotmpl: cannot create output file: %w", err)
+	}
+	defer outFile.Close()
+
+	if err := tmpl.Option("missingkey=error").Execute(outFile, data); err != nil {
+		return fmt.Errorf("gotmpl: execution failed: %w", err)
+	}
+	if err := outFile.Close(); err != nil {
+		return fmt.Errorf("gotmpl: cannot close output file: %w", err)
+	}
+	return nil
+}

gotmpl/gotmpl_test.go

@@ -0,0 +1,105 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	bodyPath = "testdata/in.go.tmpl"
+	jsonData = `{ "pkg": "myname" }`
+)
+
+func Test(t *testing.T) {
+	want, err := os.ReadFile("testdata/want.go")
+	require.NoError(t, err)
+	wantText := string(want)
+
+	destPath := filepath.Join(t.TempDir(), "out.go")
+
+	err = gotmpl(bodyPath, jsonData, destPath)
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(destPath) //nolint:gosec // It is a safe test temp filepath.
+	require.NoError(t, err)
+	gotText := string(got)
+
+	assert.Equal(t, wantText, gotText)
+}
+
+func TestEmptyOut(t *testing.T) {
+	err := gotmpl(bodyPath, jsonData, "")
+
+	assert.ErrorContains(t, err, "gotmpl: output filepath must be set")
+}
+
+func TestMissingData(t *testing.T) {
+	destPath := filepath.Join(t.TempDir(), "out.go")
+
+	err := gotmpl(bodyPath, `{ "badkey": "val" }`, destPath)
+
+	assert.ErrorContains(t, err, "gotmpl: execution failed")
+}
+
+func TestDataIsNotJSON(t *testing.T) {
+	destPath := filepath.Join(t.TempDir(), "out.go")
+
+	err := gotmpl(bodyPath, "{ bad[]", destPath)
+
+	assert.ErrorContains(t, err, "gotmpl: data must be in JSON format")
+}
+
+func TestEmptyBodyPath(t *testing.T) {
+	destPath := filepath.Join(t.TempDir(), "out.go")
+
+	err := gotmpl("", jsonData, destPath)
+
+	assert.ErrorContains(t, err, "gotmpl: template body filepath must be set")
+}
+
+func TestNotExistingBody(t *testing.T) {
+	destPath := filepath.Join(t.TempDir(), "out.go")
+
+	err := gotmpl("testdata/non-exiting.go", jsonData, destPath)
+
+	assert.ErrorContains(t, err, "gotmpl: cannot parse template body file")
+	assert.ErrorIs(t, err, os.ErrNotExist)
+}
+
+func TestComplex(t *testing.T) {
+	wantText := `myapp v2.1.0`
+	destPath := filepath.Join(t.TempDir(), "complex.txt")
+
+	bodyPath := filepath.Join(t.TempDir(), "complex.txt.tmpl")
+	body := `{{.app.name}} v{{.app.version.major}}.{{.app.version.minor}}.{{.app.version.patch}}`
+	jsonData := `{"app":{"name": "myapp", "version": {"major": 2, "minor": 1, "patch": 0}}}`
+	err := os.WriteFile(bodyPath, ([]byte)(body), 0o600)
+	require.NoError(t, err)
+
+	err = gotmpl(bodyPath, jsonData, destPath)
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(destPath) //nolint:gosec // It is a safe test temp filepath.
+	require.NoError(t, err)
+	gotText := string(got)
+
+	assert.Equal(t, wantText, gotText)
+}

gotmpl/main.go

@@ -0,0 +1,39 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// gotmpl is a tool to generate files from [text/template] and JSON data.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	flag "github.com/spf13/pflag"
+)
+
+var (
+	body = flag.StringP("body", "b", "", "Template body filepath.")
+	data = flag.StringP("data", "d", "", "Data in JSON format.")
+	out  = flag.StringP("out", "o", "", "Output filepath.")
+)
+
+func main() {
+	flag.Parse()
+
+	if err := gotmpl(*body, *data, *out); err != nil {
+		fmt.Println(err)
+		flag.PrintDefaults()
+		os.Exit(1)
+	}
+}

gotmpl/testdata/in.go.tmpl

@@ -0,0 +1,18 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package {{.pkg}}
+
+func foo() {
+}

gotmpl/testdata/want.go

@@ -0,0 +1,18 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package myname
+
+func foo() {
+}