Kindsys: Include generated-code links to Kinds report (#61910)

* Kindsys: Include generated-code links to Kinds report

* Apply feedback suggestions

pkg/kindsys/report.go

@@ -10,6 +10,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"path"
+	"reflect"
 	"sort"
 	"strings"
 
@@ -18,9 +20,26 @@ import (
 	"github.com/grafana/grafana/pkg/plugins/pfs/corelist"
 	"github.com/grafana/grafana/pkg/plugins/plugindef"
 	"github.com/grafana/grafana/pkg/registry/corekind"
+	"github.com/grafana/thema"
 )
 
-const reportFileName = "report.json"
+const (
+	// Program's output
+	reportFileName = "report.json"
+
+	// External references
+	repoBaseURL = "https://github.com/grafana/grafana/tree/main"
+	docsBaseURL = "https://grafana.com/docs/grafana/next/developers/kinds"
+
+	// Local references
+	coreTSPath  = "packages/grafana-schema/src/raw/%s/%s/%s_types.gen.ts"
+	coreGoPath  = "pkg/kinds/%s"
+	coreCUEPath = "kinds/%s/%s_kind.cue"
+
+	composableTSPath  = "public/app/plugins/%s/%s/%s.gen.ts"
+	composableGoPath  = "pkg/tsdb/%s/kinds/%s/types_%s_gen.go"
+	composableCUEPath = "public/app/plugins/%s/%s/%s.cue"
+)
 
 func main() {
 	report := buildKindStateReport()
@@ -54,17 +73,58 @@ var plannedCoreKinds = []string{
 	"QueryHistory",
 }
 
+type KindLinks struct {
+	Schema string
+	Go     string
+	Ts     string
+	Docs   string
+}
+
+type Kind struct {
+	kindsys.SomeKindProperties
+	Category string
+	Links    KindLinks
+}
+
+// MarshalJSON is overwritten to marshal
+// kindsys.SomeKindProperties at root level.
+func (k Kind) MarshalJSON() ([]byte, error) {
+	b, err := json.Marshal(k.SomeKindProperties)
+	if err != nil {
+		return nil, err
+	}
+
+	var m map[string]interface{}
+	if err = json.Unmarshal(b, &m); err != nil {
+		return nil, err
+	}
+
+	m["category"] = k.Category
+
+	m["links"] = map[string]string{}
+	for _, ref := range []string{"Schema", "Go", "Ts", "Docs"} {
+		refVal := reflect.ValueOf(k.Links).FieldByName(ref).String()
+		if len(refVal) > 0 {
+			m["links"].(map[string]string)[toCamelCase(ref)] = refVal
+		} else {
+			m["links"].(map[string]string)[toCamelCase(ref)] = "n/a"
+		}
+	}
+
+	return json.Marshal(m)
+}
+
 type KindStateReport struct {
-	Kinds      map[string]kindsys.SomeKindProperties `json:"kinds"`
+	Kinds      map[string]Kind      `json:"kinds"`
 	Dimensions map[string]Dimension `json:"dimensions"`
 }
 
-func (r *KindStateReport) add(k kindsys.SomeKindProperties, category string) {
+func (r *KindStateReport) add(k Kind) {
 	kName := k.Common().MachineName
 
 	r.Kinds[kName] = k
 	r.Dimensions["maturity"][k.Common().Maturity.String()].add(kName)
-	r.Dimensions["category"][category].add(kName)
+	r.Dimensions["category"][k.Category].add(kName)
 }
 
 type Dimension map[string]*DimensionValue
@@ -85,7 +145,7 @@ func (dv *DimensionValue) add(s string) {
 // the final report.
 func emptyKindStateReport() *KindStateReport {
 	return &KindStateReport{
-		Kinds: make(map[string]kindsys.SomeKindProperties),
+		Kinds: make(map[string]Kind),
 		Dimensions: map[string]Dimension{
 			"maturity": {
 				"planned":      emptyDimensionValue("planned"),
@@ -117,9 +177,14 @@ func buildKindStateReport() *KindStateReport {
 	seen := make(map[string]bool)
 	for _, k := range b.All() {
 		seen[k.Props().Common().Name] = true
+		k.Lineage()
 		switch k.Props().(type) {
 		case kindsys.CoreProperties:
-			r.add(k.Props(), "core")
+			r.add(Kind{
+				SomeKindProperties: k.Props(),
+				Category:           "core",
+				Links:              buildCoreLinks(k.Lineage(), k.Decl().Properties),
+			})
 		}
 	}
 
@@ -128,7 +193,8 @@ func buildKindStateReport() *KindStateReport {
 			continue
 		}
 
-		r.add(kindsys.CoreProperties{
+		r.add(Kind{
+			SomeKindProperties: kindsys.CoreProperties{
 				CommonProperties: kindsys.CommonProperties{
 					Name:              kn,
 					PluralName:        kn + "s",
@@ -136,17 +202,23 @@ func buildKindStateReport() *KindStateReport {
 					PluralMachineName: machinize(kn) + "s",
 					Maturity:          "planned",
 				},
-		}, "core")
+			},
+			Category: "core",
+		})
 	}
 
 	all := kindsys.SchemaInterfaces(nil)
 	for _, pp := range corelist.New(nil) {
 		for _, si := range all {
 			if ck, has := pp.ComposableKinds[si.Name()]; has {
-				r.add(ck.Props(), "composable")
+				r.add(Kind{
+					SomeKindProperties: ck.Props(),
+					Category:           "composable",
+					Links:              buildComposableLinks(pp.Properties, ck.Decl().Properties),
+				})
 			} else if may := si.Should(string(pp.Properties.Type)); may {
 				n := plugindef.DerivePascalName(pp.Properties) + si.Name()
-				props := kindsys.ComposableProperties{
+				ck := kindsys.ComposableProperties{
 					SchemaInterface: si.Name(),
 					CommonProperties: kindsys.CommonProperties{
 						Name:              n,
@@ -157,7 +229,10 @@ func buildKindStateReport() *KindStateReport {
 						Maturity:          "planned",
 					},
 				}
-				r.add(props, "composable")
+				r.add(Kind{
+					SomeKindProperties: ck,
+					Category:           "composable",
+				})
 			}
 		}
 	}
@@ -171,6 +246,66 @@ func buildKindStateReport() *KindStateReport {
 	return r
 }
 
+func buildDocsRef(category string, props kindsys.CommonProperties) string {
+	return path.Join(docsBaseURL, category, props.MachineName, "schema-reference")
+}
+
+func buildCoreLinks(lin thema.Lineage, cp kindsys.CoreProperties) KindLinks {
+	const category = "core"
+	vpath := fmt.Sprintf("v%v", lin.Latest().Version()[0])
+	if cp.Maturity.Less(kindsys.MaturityStable) {
+		vpath = "x"
+	}
+
+	return KindLinks{
+		Schema: path.Join(repoBaseURL, fmt.Sprintf(coreCUEPath, cp.MachineName, cp.MachineName)),
+		Go:     path.Join(repoBaseURL, fmt.Sprintf(coreGoPath, cp.MachineName)),
+		Ts:     path.Join(repoBaseURL, fmt.Sprintf(coreTSPath, cp.MachineName, vpath, cp.MachineName)),
+		Docs:   path.Join(docsBaseURL, category, cp.MachineName, "schema-reference"),
+	}
+}
+
+// used to map names for those plugins that aren't following
+// naming conventions, like 'annonlist' which comes from "Annotations list".
+var irregularPluginNames = map[string]string{
+	// Panel
+	"alertgroups":     "alertGroups",
+	"annotationslist": "annolist",
+	"dashboardlist":   "dashlist",
+	"nodegraph":       "nodeGraph",
+	"statetimeline":   "state-timeline",
+	"statushistory":   "status-history",
+	"tableold":        "table-old",
+	// Datasource
+	"googlecloudmonitoring": "cloud-monitoring",
+	"azuremonitor":          "grafana-azure-monitor-datasource",
+	"microsoftsqlserver":    "mssql",
+	"postgresql":            "postgres",
+	"testdatadb":            "testdata",
+}
+
+func buildComposableLinks(pp plugindef.PluginDef, cp kindsys.ComposableProperties) KindLinks {
+	const category = "composable"
+	schemaInterface := strings.ToLower(cp.SchemaInterface)
+
+	pName := strings.Replace(cp.MachineName, schemaInterface, "", 1)
+	if irr, ok := irregularPluginNames[pName]; ok {
+		pName = irr
+	}
+
+	var goLink string
+	if pp.Backend != nil && *pp.Backend {
+		goLink = path.Join(repoBaseURL, fmt.Sprintf(composableGoPath, pName, schemaInterface, schemaInterface))
+	}
+
+	return KindLinks{
+		Schema: path.Join(repoBaseURL, fmt.Sprintf(composableCUEPath, string(pp.Type), pName, schemaInterface)),
+		Go:     goLink,
+		Ts:     path.Join(repoBaseURL, fmt.Sprintf(composableTSPath, string(pp.Type), pName, schemaInterface)),
+		Docs:   path.Join(docsBaseURL, category, cp.MachineName, "schema-reference"),
+	}
+}
+
 func machinize(s string) string {
 	return strings.Map(func(r rune) rune {
 		switch {
@@ -190,6 +325,10 @@ func machinize(s string) string {
 	}, s)
 }
 
+func toCamelCase(s string) string {
+	return strings.ToLower(string(s[0])) + s[1:]
+}
+
 type reportJenny struct{}
 
 func (reportJenny) JennyName() string {