Fix: fixed the problems of display definition in web and support displaying WorkflowStep and Policy (#4234)

* Fix: fixed the problems of display definition in web

Some ComponentDefinitions, TraitDefinitions, WorkflowDefinitions
failed to show the usage in web browser

Signed-off-by: Zheng Xi Zhou <zhengxi.zzx@alibaba-inc.com>

* set printable type for {}

Signed-off-by: Zheng Xi Zhou <zhengxi.zzx@alibaba-inc.com>

* support WorkflowSteps and Policies

Signed-off-by: Zheng Xi Zhou <zhengxi.zzx@alibaba-inc.com>

Co-authored-by: Zheng Xi Zhou <zhengxi.zzx@alibaba-inc.com>

charts/vela-core/templates/defwithtemplate/affinity.yaml

@@ -4,7 +4,7 @@ apiVersion: core.oam.dev/v1beta1
 kind: TraitDefinition
 metadata:
   annotations:
-    definition.oam.dev/description: affinity specify affinity and tolerationon K8s pod for your workload which follows the pod spec in path 'spec.template'.
+    definition.oam.dev/description: Affinity specifies affinity and toleration K8s pod for your workload which follows the pod spec in path 'spec.template'.
   labels:
     custom.definition.oam.dev/ui-hidden: "true"
   name: affinity

charts/vela-minimal/templates/defwithtemplate/affinity.yaml

@@ -4,7 +4,7 @@ apiVersion: core.oam.dev/v1beta1
 kind: TraitDefinition
 metadata:
   annotations:
-    definition.oam.dev/description: affinity specify affinity and tolerationon K8s pod for your workload which follows the pod spec in path 'spec.template'.
+    definition.oam.dev/description: Affinity specifies affinity and toleration K8s pod for your workload which follows the pod spec in path 'spec.template'.
   labels:
     custom.definition.oam.dev/ui-hidden: "true"
   name: affinity

references/cli/show.go

@@ -100,12 +100,6 @@ func startReferenceDocsSite(ctx context.Context, ns string, c common.Args, ioStr
 	}
 	referenceHome := filepath.Join(home, "reference")
 
-	definitionPath := filepath.Join(referenceHome, "capabilities")
-	if _, err := os.Stat(definitionPath); err != nil && os.IsNotExist(err) {
-		if err := os.MkdirAll(definitionPath, 0750); err != nil {
-			return err
-		}
-	}
 	docsPath := filepath.Join(referenceHome, "docs")
 	if _, err := os.Stat(docsPath); err != nil && os.IsNotExist(err) {
 		if err := os.MkdirAll(docsPath, 0750); err != nil {
@@ -171,22 +165,12 @@ func startReferenceDocsSite(ctx context.Context, ns string, c common.Args, ioStr
 		return err
 	}
 
-	var capabilityPath string
-	switch capabilityType {
-	case types.TypeWorkload:
-		capabilityPath = plugins.WorkloadTypePath
-	case types.TypeTrait:
-		capabilityPath = plugins.TraitPath
-	case types.TypeScope:
-	case types.TypeComponentDefinition:
-		capabilityPath = plugins.ComponentDefinitionTypePath
-	case types.TypeWorkflowStep:
-		capabilityPath = plugins.WorkflowStepPath
-	default:
+	if capabilityType != types.TypeWorkload && capabilityType != types.TypeTrait && capabilityType != types.TypeScope &&
+		capabilityType != types.TypeComponentDefinition && capabilityType != types.TypeWorkflowStep {
 		return fmt.Errorf("unsupported type: %v", capabilityType)
 	}
 
-	url := fmt.Sprintf("http://127.0.0.1%s/#/%s/%s", Port, capabilityPath, capabilityName)
+	url := fmt.Sprintf("http://127.0.0.1%s/#/%s/%s", Port, capabilityType, capabilityName)
 	server := &http.Server{
 		Addr:         Port,
 		Handler:      http.FileServer(http.Dir(docsPath)),
@@ -227,7 +211,7 @@ func launch(server *http.Server, errChan chan<- error) {
 
 func generateSideBar(capabilities []types.Capability, docsPath string) error {
 	sideBar := filepath.Join(docsPath, SideBar)
-	components, traits, workflowsteps := getDefinitions(capabilities)
+	components, traits, workflowSteps, policies := getDefinitions(capabilities)
 	f, err := os.Create(sideBar)
 	if err != nil {
 		return err
@@ -235,8 +219,9 @@ func generateSideBar(capabilities []types.Capability, docsPath string) error {
 	if _, err := f.WriteString("- Components Types\n"); err != nil {
 		return err
 	}
+
 	for _, c := range components {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", c, plugins.ComponentDefinitionTypePath, c)); err != nil {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", c, types.TypeComponentDefinition, c)); err != nil {
 			return err
 		}
 	}
@@ -244,15 +229,24 @@ func generateSideBar(capabilities []types.Capability, docsPath string) error {
 		return err
 	}
 	for _, t := range traits {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, plugins.TraitPath, t)); err != nil {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypeTrait, t)); err != nil {
 			return err
 		}
 	}
 	if _, err := f.WriteString("- Workflow Steps\n"); err != nil {
 		return err
 	}
-	for _, t := range workflowsteps {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, plugins.WorkflowStepPath, t)); err != nil {
+	for _, t := range workflowSteps {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypeWorkflowStep, t)); err != nil {
+			return err
+		}
+	}
+
+	if _, err := f.WriteString("- Policies\n"); err != nil {
+		return err
+	}
+	for _, t := range policies {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypePolicy, t)); err != nil {
 			return err
 		}
 	}
@@ -327,14 +321,14 @@ func generateREADME(capabilities []types.Capability, docsPath string) error {
 		return err
 	}
 
-	workloads, traits, workflowsteps := getDefinitions(capabilities)
+	workloads, traits, workflowSteps, policies := getDefinitions(capabilities)
 
 	if _, err := f.WriteString("## Component Types\n"); err != nil {
 		return err
 	}
 
 	for _, w := range workloads {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", w, plugins.ComponentDefinitionTypePath, w)); err != nil {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", w, types.TypeComponentDefinition, w)); err != nil {
 			return err
 		}
 	}
@@ -343,7 +337,7 @@ func generateREADME(capabilities []types.Capability, docsPath string) error {
 	}
 
 	for _, t := range traits {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, plugins.TraitPath, t)); err != nil {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypeTrait, t)); err != nil {
 			return err
 		}
 	}
@@ -351,16 +345,26 @@ func generateREADME(capabilities []types.Capability, docsPath string) error {
 	if _, err := f.WriteString("## Workflow Steps\n"); err != nil {
 		return err
 	}
-	for _, t := range workflowsteps {
-		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, plugins.WorkflowStepPath, t)); err != nil {
+	for _, t := range workflowSteps {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypeWorkflowStep, t)); err != nil {
 			return err
 		}
 	}
+
+	if _, err := f.WriteString("## Policies\n"); err != nil {
+		return err
+	}
+	for _, t := range policies {
+		if _, err := f.WriteString(fmt.Sprintf("  - [%s](%s/%s.md)\n", t, types.TypePolicy, t)); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 
-func getDefinitions(capabilities []types.Capability) ([]string, []string, []string) {
-	var components, traits, workflowSteps []string
+func getDefinitions(capabilities []types.Capability) ([]string, []string, []string, []string) {
+	var components, traits, workflowSteps, policies []string
 	for _, c := range capabilities {
 		switch c.Type {
 		case types.TypeComponentDefinition:
@@ -369,12 +373,14 @@ func getDefinitions(capabilities []types.Capability) ([]string, []string, []stri
 			traits = append(traits, c.Name)
 		case types.TypeWorkflowStep:
 			workflowSteps = append(workflowSteps, c.Name)
+		case types.TypePolicy:
+			policies = append(policies, c.Name)
 		case types.TypeScope:
 		case types.TypeWorkload:
 		default:
 		}
 	}
-	return components, traits, workflowSteps
+	return components, traits, workflowSteps, policies
 }
 
 // ShowReferenceConsole will show capability reference in console

references/cli/show_test.go

@@ -27,7 +27,6 @@ import (
 	"github.com/stretchr/testify/assert"
 
 	"github.com/oam-dev/kubevela/apis/types"
-	"github.com/oam-dev/kubevela/references/plugins"
 )
 
 const BaseDir = "testdata"
@@ -134,9 +133,9 @@ func TestGenerateREADME(t *testing.T) {
 			for _, c := range tc.capabilities {
 				switch c.Type {
 				case types.TypeComponentDefinition:
-					assert.Contains(t, string(data), fmt.Sprintf("  - [%s](%s/%s.md)\n", c.Name, plugins.ComponentDefinitionTypePath, c.Name))
+					assert.Contains(t, string(data), fmt.Sprintf("  - [%s](%s/%s.md)\n", c.Name, types.TypeComponentDefinition, c.Name))
 				case types.TypeTrait:
-					assert.Contains(t, string(data), fmt.Sprintf("  - [%s](%s/%s.md)\n", c.Name, plugins.TraitPath, c.Name))
+					assert.Contains(t, string(data), fmt.Sprintf("  - [%s](%s/%s.md)\n", c.Name, types.TypeTrait, c.Name))
 				}
 			}
 		})
@@ -147,10 +146,15 @@ func TestGetWorkloadAndTraits(t *testing.T) {
 	type want struct {
 		workloads []string
 		traits    []string
+		policies  []string
 	}
-	workloadName := "component1"
-	traitName := "trait1"
-	scopeName := "scope1"
+
+	var (
+		workloadName = "component1"
+		traitName    = "trait1"
+		scopeName    = "scope1"
+		policyName   = "policy1"
+	)
 
 	cases := map[string]struct {
 		reason       string
@@ -187,11 +191,22 @@ func TestGetWorkloadAndTraits(t *testing.T) {
 				traits:    nil,
 			},
 		},
+		"PolicyTypeCapability": {
+			capabilities: []types.Capability{
+				{
+					Name: policyName,
+					Type: types.TypePolicy,
+				},
+			},
+			want: want{
+				policies: []string{policyName},
+			},
+		},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
-			gotWorkloads, gotTraits, _ := getDefinitions(tc.capabilities)
-			assert.Equal(t, tc.want, want{workloads: gotWorkloads, traits: gotTraits})
+			gotWorkloads, gotTraits, _, gotPolicies := getDefinitions(tc.capabilities)
+			assert.Equal(t, tc.want, want{workloads: gotWorkloads, traits: gotTraits, policies: gotPolicies})
 		})
 	}
 }

references/plugins/cluster.go

@@ -73,20 +73,38 @@ func GetNamespacedCapabilitiesFromCluster(ctx context.Context, namespace string,
 		capabilities = append(capabilities, traits...)
 	}
 
-	// get components from default namespace
-	if workloads, _, err := GetComponentsFromClusterWithValidateOption(ctx, types.DefaultKubeVelaNS, c, selector, false); err == nil {
-		capabilities = append(capabilities, workloads...)
+	if workflowSteps, _, err := GetWorkflowSteps(ctx, namespace, c); err == nil {
+		capabilities = append(capabilities, workflowSteps...)
 	}
 
-	// get traits from default namespace
-	if traits, _, err := GetTraitsFromClusterWithValidateOption(ctx, types.DefaultKubeVelaNS, c, selector, false); err == nil {
-		capabilities = append(capabilities, traits...)
+	if policies, _, err := GetPolicies(ctx, namespace, c); err == nil {
+		capabilities = append(capabilities, policies...)
+	}
+
+	if namespace != types.DefaultKubeVelaNS {
+		// get components from default namespace
+		if workloads, _, err := GetComponentsFromClusterWithValidateOption(ctx, types.DefaultKubeVelaNS, c, selector, false); err == nil {
+			capabilities = append(capabilities, workloads...)
+		}
+
+		// get traits from default namespace
+		if traits, _, err := GetTraitsFromClusterWithValidateOption(ctx, types.DefaultKubeVelaNS, c, selector, false); err == nil {
+			capabilities = append(capabilities, traits...)
+		}
+
+		if workflowSteps, _, err := GetWorkflowSteps(ctx, types.DefaultKubeVelaNS, c); err == nil {
+			capabilities = append(capabilities, workflowSteps...)
+		}
+
+		if policies, _, err := GetPolicies(ctx, types.DefaultKubeVelaNS, c); err == nil {
+			capabilities = append(capabilities, policies...)
+		}
 	}
 
 	if len(capabilities) > 0 {
 		return capabilities, nil
 	}
-	return nil, fmt.Errorf("could not find any components or traits from namespace %s and %s", namespace, types.DefaultKubeVelaNS)
+	return nil, fmt.Errorf("could not find any components, traits or workflowSteps from namespace %s and %s", namespace, types.DefaultKubeVelaNS)
 }
 
 // GetComponentsFromCluster will get capability from K8s cluster
@@ -184,6 +202,58 @@ func GetTraitsFromClusterWithValidateOption(ctx context.Context, namespace strin
 	return templates, templateErrors, nil
 }
 
+// GetWorkflowSteps will get WorkflowStepDefinition list
+func GetWorkflowSteps(ctx context.Context, namespace string, c common.Args) ([]types.Capability, []error, error) {
+	newClient, err := c.GetClient()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	var templates []types.Capability
+	var workflowStepDefs v1beta1.WorkflowStepDefinitionList
+	err = newClient.List(ctx, &workflowStepDefs, &client.ListOptions{Namespace: namespace})
+	if err != nil {
+		return nil, nil, fmt.Errorf("list WorkflowStepDefinition err: %w", err)
+	}
+
+	var templateErrors []error
+	for _, def := range workflowStepDefs.Items {
+		tmp, err := GetCapabilityByWorkflowStepDefinitionObject(def, nil)
+		if err != nil {
+			templateErrors = append(templateErrors, err)
+			continue
+		}
+		templates = append(templates, *tmp)
+	}
+	return templates, templateErrors, nil
+}
+
+// GetPolicies will get Policy from K8s cluster
+func GetPolicies(ctx context.Context, namespace string, c common.Args) ([]types.Capability, []error, error) {
+	newClient, err := c.GetClient()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	var templates []types.Capability
+	var defs v1beta1.PolicyDefinitionList
+	err = newClient.List(ctx, &defs, &client.ListOptions{Namespace: namespace})
+	if err != nil {
+		return nil, nil, fmt.Errorf("list PolicyDefinition err: %w", err)
+	}
+
+	var templateErrors []error
+	for _, def := range defs.Items {
+		tmp, err := GetCapabilityByPolicyDefinitionObject(def, nil)
+		if err != nil {
+			templateErrors = append(templateErrors, err)
+			continue
+		}
+		templates = append(templates, *tmp)
+	}
+	return templates, templateErrors, nil
+}
+
 // validateCapabilities validates whether helm charts are successful installed, GVK are successfully retrieved.
 func validateCapabilities(tmp *types.Capability, dm discoverymapper.DiscoveryMapper, definitionName string, reference commontypes.DefinitionReference) error {
 	var err error
@@ -411,11 +481,7 @@ func GetCapabilityByTraitDefinitionObject(traitDef v1beta1.TraitDefinition) (*ty
 
 // GetCapabilityByWorkflowStepDefinitionObject gets capability by WorkflowStepDefinition object
 func GetCapabilityByWorkflowStepDefinitionObject(wfStepDef v1beta1.WorkflowStepDefinition, pd *packages.PackageDiscover) (*types.Capability, error) {
-	var (
-		capability types.Capability
-		err        error
-	)
-	capability, err = HandleDefinition(wfStepDef.Name, wfStepDef.Spec.Reference.Name, wfStepDef.Annotations, wfStepDef.Labels,
+	capability, err := HandleDefinition(wfStepDef.Name, wfStepDef.Spec.Reference.Name, wfStepDef.Annotations, wfStepDef.Labels,
 		nil, types.TypeWorkflowStep, nil, wfStepDef.Spec.Schematic, pd)
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to handle WorkflowStepDefinition")
@@ -423,3 +489,14 @@ func GetCapabilityByWorkflowStepDefinitionObject(wfStepDef v1beta1.WorkflowStepD
 	capability.Namespace = wfStepDef.Namespace
 	return &capability, nil
 }
+
+// GetCapabilityByPolicyDefinitionObject gets capability by PolicyDefinition object
+func GetCapabilityByPolicyDefinitionObject(def v1beta1.PolicyDefinition, pd *packages.PackageDiscover) (*types.Capability, error) {
+	capability, err := HandleDefinition(def.Name, def.Spec.Reference.Name, def.Annotations, def.Labels,
+		nil, types.TypePolicy, nil, def.Spec.Schematic, pd)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to handle PolicyDefinition")
+	}
+	capability.Namespace = def.Namespace
+	return &capability, nil
+}

references/plugins/references.go

@@ -55,14 +55,6 @@ const (
 	KubeVelaIOTerraformPathZh = "../kubevela.io/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform"
 	// ReferenceSourcePath is the location for source reference
 	ReferenceSourcePath = "hack/references"
-	// ComponentDefinitionTypePath is the URL path for component typed capability
-	ComponentDefinitionTypePath = "components"
-	// WorkloadTypePath is the URL path for workload typed capability
-	WorkloadTypePath = "workload-types"
-	// TraitPath is the URL path for trait typed capability
-	TraitPath = "traits"
-	// WorkflowStepPath is the URL path for workflow step typed capability
-	WorkflowStepPath = "workflowsteps"
 )
 
 // Int64Type is int64 type
@@ -656,18 +648,20 @@ func (ref *MarkdownReference) CreateMarkdown(ctx context.Context, caps []types.C
 			sample        string
 			specification string
 		)
-		if c.Type != types.TypeWorkload && c.Type != types.TypeComponentDefinition && c.Type != types.TypeTrait {
+		if c.Type != types.TypeWorkload && c.Type != types.TypeComponentDefinition && c.Type != types.TypeTrait &&
+			c.Type != types.TypeWorkflowStep && c.Type != types.TypePolicy {
 			return fmt.Errorf("the type of the capability is not right")
 		}
 
-		fileName := fmt.Sprintf("%s.md", c.Name)
-		if _, err := os.Stat(baseRefPath); err != nil && os.IsNotExist(err) {
-			if err := os.MkdirAll(baseRefPath, 0750); err != nil {
+		refPath := filepath.Join(baseRefPath, string(c.Type))
+		if _, err := os.Stat(refPath); err != nil && os.IsNotExist(err) {
+			if err := os.MkdirAll(refPath, 0750); err != nil {
 				return err
 			}
 		}
 
-		markdownFile := filepath.Join(baseRefPath, fileName)
+		fileName := fmt.Sprintf("%s.md", c.Name)
+		markdownFile := filepath.Join(refPath, fileName)
 		f, err := os.OpenFile(filepath.Clean(markdownFile), os.O_WRONLY|os.O_CREATE, 0600)
 		if err != nil {
 			return fmt.Errorf("failed to open file %s: %w", markdownFile, err)
@@ -869,11 +863,13 @@ func (ref *ParseReference) parseParameters(paraValue cue.Value, paramKey string,
 		}
 		if arguments.Len() == 0 {
 			var param ReferenceParameter
-			param.Name = "-"
+			param.Name = "\\-"
 			param.Required = true
 			tl := paraValue.Template()
 			if tl != nil { // is map type
 				param.PrintableType = fmt.Sprintf("map[string]%s", tl("").IncompleteKind().String())
+			} else {
+				param.PrintableType = "{}"
 			}
 			params = append(params, param)
 		}

vela-templates/definitions/internal/trait/affinity.cue

@@ -4,7 +4,7 @@
 	labels: {
 		"ui-hidden": "true"
 	}
-	description: "affinity specify affinity and tolerationon K8s pod for your workload which follows the pod spec in path 'spec.template'."
+	description: "Affinity specifies affinity and toleration K8s pod for your workload which follows the pod spec in path 'spec.template'."
 	attributes: {
 		appliesToWorkloads: ["*"]
 		podDisruptive: true