refactor: rename Spec to the Intent (#601)

docs/design/appconfiguration_generator.md

@@ -1,7 +1,7 @@
 # AppConfiguration Generator Proposal
 
 ## Motivation
-Currently(v0.9.0), `AppConfigurationGenerator` is composed of a series of `GeneratorFunc`. Each `GeneratorFunc` creates a corresponding `Generator` for a subresource, and then the `Generate` method of each Generator is called to generate the resource and add it to the `spec`.
+Currently(v0.9.0), `AppConfigurationGenerator` is composed of a series of `GeneratorFunc`. Each `GeneratorFunc` creates a corresponding `Generator` for a subresource, and then the `Generate` method of each Generator is called to generate the resource and add it to the `intent`.
 
 ```
 AppConfigurationGenerator
@@ -32,7 +32,7 @@ Each `NewXXXGeneratorFunc` call chain is as follows:
             |  (generate)                                                          
             v                                                            
 +------------------------+                                                
-|         spec           |                                                
+|         Intent         |                                                
 |                        |                                                
 +------------------------+
 ```
@@ -108,22 +108,22 @@ func (g *databaseGenerator) injectSecret(secret *v1.Secret) error {
 
 We introduce a new `XXXPatcherFunc`. The current `XXXGeneratorFunc` is used only to generate new resources, while the `XXXPatcherFunc` is used only for additional patching of resources.
 ```go
-func (g *appConfigurationGenerator) Generate(spec *models.Spec) error {
+func (g *appConfigurationGenerator) Generate(intent *models.Intent) error {
 	// Generator logic only generates new resources
 	gfs := []appconfiguration.NewGeneratorFunc{
 		NewNamespaceGeneratorFunc(g.project.Name),
 		accessories.NewDatabaseGeneratorFunc(g.project, g.stack, g.appName, g.app.Workload, g.app.Database),
 		...
 	}
-	if err := appconfiguration.CallGenerators(spec, gfs...); err != nil {
+	if err := appconfiguration.CallGenerators(intent, gfs...); err != nil {
 		return err
 	}
 
 	// Patcher logic patches generated resources
 	pfs := []appconfiguration.NewPatcherFunc{
 		trait.NewPatcherFunc(g.project, g.stack, g.appName, g.app),
 	}
-	if err := appconfiguration.CallPatchers(spec.Resources.KubernetesKinds(), pfs...); err != nil {
+	if err := appconfiguration.CallPatchers(intent.Resources.KubernetesKinds(), pfs...); err != nil {
 		return err
 	}
 	return nil
@@ -134,7 +134,7 @@ func (g *appConfigurationGenerator) Generate(spec *models.Spec) error {
 ### Render Order
 Perform all `GeneratorFunc` tasks first, followed by all `PatcherFunc` tasks.
 ### Patcher Logic
-First, classify the resources in the spec by resource type (if it is a Kubernetes type), and perform patching on the specified resource types. For example, the opsRulePatcher needs to patch the MaxUnavailable field for resources of the deployment type.
+First, classify the resources in the intent by resource type (if it is a Kubernetes type), and perform patching on the specified resource types. For example, the opsRulePatcher needs to patch the MaxUnavailable field for resources of the deployment type.
 ```go
 // Patch implements Patcher interface.
 func (p *opsRulePatcher) Patch(resources map[string][]*models.Resource) error {

pkg/cmd/apply/options.go

@@ -77,8 +77,8 @@ func (o *Options) Run() error {
 		NoStyle:     o.NoStyle,
 	}
 
-	// Generate Spec
-	var sp *models.Spec
+	// Generate Intent
+	var sp *models.Intent
 	if o.SpecFile != "" {
 		sp, err = spec.GenerateSpecFromFile(o.SpecFile)
 	} else {
@@ -190,7 +190,7 @@ func (o *Options) Run() error {
 func Apply(
 	o *Options,
 	storage states.StateStorage,
-	planResources *models.Spec,
+	planResources *models.Intent,
 	changes *opsmodels.Changes,
 	out io.Writer,
 ) error {
@@ -333,7 +333,7 @@ func Apply(
 //	}
 func Watch(
 	o *Options,
-	planResources *models.Spec,
+	planResources *models.Intent,
 	changes *opsmodels.Changes,
 ) error {
 	if o.DryRun {
@@ -355,7 +355,7 @@ func Watch(
 		Request: opsmodels.Request{
 			Project: changes.Project(),
 			Stack:   changes.Stack(),
-			Spec:    &models.Spec{Resources: toBeWatched},
+			Spec:    &models.Intent{Resources: toBeWatched},
 		},
 	}); err != nil {
 		return err

pkg/cmd/apply/options_test.go

@@ -82,8 +82,8 @@ func mockeyPatchGenerateSpec() *mockey.Mocker {
 		o *generator.Options,
 		project *projectstack.Project,
 		stack *projectstack.Stack,
-	) (*models.Spec, error) {
-		return &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, nil
+	) (*models.Intent, error) {
+		return &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, nil
 	}).Build()
 }
 
@@ -130,7 +130,10 @@ func (f *fakerRuntime) Watch(ctx context.Context, request *runtime.WatchRequest)
 }
 
 func mockeyPatchOperationPreview() *mockey.Mocker {
-	return mockey.Mock((*operation.PreviewOperation).Preview).To(func(*operation.PreviewOperation, *operation.PreviewRequest) (rsp *operation.PreviewResponse, s status.Status) {
+	return mockey.Mock((*operation.PreviewOperation).Preview).To(func(
+		*operation.PreviewOperation,
+		*operation.PreviewRequest,
+	) (rsp *operation.PreviewResponse, s status.Status) {
 		return &operation.PreviewResponse{
 			Order: &opsmodels.ChangeOrder{
 				StepKeys: []string{sa1.ID, sa2.ID, sa3.ID},
@@ -186,7 +189,7 @@ func newSA(name string) models.Resource {
 func Test_apply(t *testing.T) {
 	stateStorage := &local.FileSystemState{Path: filepath.Join("", local.KusionState)}
 	mockey.PatchConvey("dry run", t, func() {
-		planResources := &models.Spec{Resources: []models.Resource{sa1}}
+		planResources := &models.Intent{Resources: []models.Resource{sa1}}
 		order := &opsmodels.ChangeOrder{
 			StepKeys: []string{sa1.ID},
 			ChangeSteps: map[string]*opsmodels.ChangeStep{
@@ -206,7 +209,7 @@ func Test_apply(t *testing.T) {
 	mockey.PatchConvey("apply success", t, func() {
 		mockOperationApply(opsmodels.Success)
 		o := NewApplyOptions()
-		planResources := &models.Spec{Resources: []models.Resource{sa1, sa2}}
+		planResources := &models.Intent{Resources: []models.Resource{sa1, sa2}}
 		order := &opsmodels.ChangeOrder{
 			StepKeys: []string{sa1.ID, sa2.ID},
 			ChangeSteps: map[string]*opsmodels.ChangeStep{
@@ -231,7 +234,7 @@ func Test_apply(t *testing.T) {
 		mockOperationApply(opsmodels.Failed)
 
 		o := NewApplyOptions()
-		planResources := &models.Spec{Resources: []models.Resource{sa1}}
+		planResources := &models.Intent{Resources: []models.Resource{sa1}}
 		order := &opsmodels.ChangeOrder{
 			StepKeys: []string{sa1.ID},
 			ChangeSteps: map[string]*opsmodels.ChangeStep{

pkg/cmd/compile/options_test.go

@@ -175,14 +175,18 @@ func mockGenerateSpec() *mockey.Mocker {
 		o *generator.Options,
 		project *projectstack.Project,
 		stack *projectstack.Stack,
-	) (*models.Spec, error) {
-		return &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, nil
+	) (*models.Intent, error) {
+		return &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, nil
 	}).Build()
 }
 
 func mockGenerateSpecFail() *mockey.Mocker {
-	return mockey.Mock(spec.GenerateSpecWithSpinner).To(func(o *generator.Options, project *projectstack.Project, stack *projectstack.Stack) (*models.Spec, error) {
-		return &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, errTest
+	return mockey.Mock(spec.GenerateSpecWithSpinner).To(func(
+		o *generator.Options,
+		project *projectstack.Project,
+		stack *projectstack.Stack,
+	) (*models.Intent, error) {
+		return &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, errTest
 	}).Build()
 }
 

pkg/cmd/destroy/options.go

@@ -79,7 +79,7 @@ func (o *Options) Run() error {
 	}
 
 	// Compute changes for preview
-	spec := &models.Spec{Resources: destroyResources}
+	spec := &models.Intent{Resources: destroyResources}
 	changes, err := o.preview(spec, project, stack, stateStorage)
 	if err != nil {
 		return err
@@ -125,7 +125,7 @@ func (o *Options) Run() error {
 }
 
 func (o *Options) preview(
-	planResources *models.Spec, project *projectstack.Project,
+	planResources *models.Intent, project *projectstack.Project,
 	stack *projectstack.Stack, stateStorage states.StateStorage,
 ) (*opsmodels.Changes, error) {
 	log.Info("Start compute preview changes ...")
@@ -157,7 +157,7 @@ func (o *Options) preview(
 	return opsmodels.NewChanges(project, stack, rsp.Order), nil
 }
 
-func (o *Options) destroy(planResources *models.Spec, changes *opsmodels.Changes, stateStorage states.StateStorage) error {
+func (o *Options) destroy(planResources *models.Intent, changes *opsmodels.Changes, stateStorage states.StateStorage) error {
 	do := &operation.DestroyOperation{
 		Operation: opsmodels.Operation{
 			Stack:        changes.Stack(),

pkg/cmd/destroy/options_test.go

@@ -100,7 +100,7 @@ func Test_preview(t *testing.T) {
 
 		o := NewDestroyOptions()
 		stateStorage := &local.FileSystemState{Path: filepath.Join(o.WorkDir, local.KusionState)}
-		_, err := o.preview(&models.Spec{Resources: []models.Resource{sa1}}, project, stack, stateStorage)
+		_, err := o.preview(&models.Intent{Resources: []models.Resource{sa1}}, project, stack, stateStorage)
 		assert.Nil(t, err)
 	})
 }
@@ -198,7 +198,7 @@ func Test_destroy(t *testing.T) {
 		mockOperationDestroy(opsmodels.Success)
 
 		o := NewDestroyOptions()
-		planResources := &models.Spec{Resources: []models.Resource{sa2}}
+		planResources := &models.Intent{Resources: []models.Resource{sa2}}
 		order := &opsmodels.ChangeOrder{
 			StepKeys: []string{sa1.ID, sa2.ID},
 			ChangeSteps: map[string]*opsmodels.ChangeStep{
@@ -226,7 +226,7 @@ func Test_destroy(t *testing.T) {
 		mockOperationDestroy(opsmodels.Failed)
 
 		o := NewDestroyOptions()
-		planResources := &models.Spec{Resources: []models.Resource{sa1}}
+		planResources := &models.Intent{Resources: []models.Resource{sa1}}
 		order := &opsmodels.ChangeOrder{
 			StepKeys: []string{sa1.ID},
 			ChangeSteps: map[string]*opsmodels.ChangeStep{

pkg/cmd/preview/options.go

@@ -133,8 +133,8 @@ func (o *Options) Run() error {
 		NoStyle:     o.NoStyle,
 	}
 
-	// Generate Spec
-	var sp *models.Spec
+	// Generate Intent
+	var sp *models.Intent
 	if o.SpecFile != "" {
 		sp, err = spec.GenerateSpecFromFile(o.SpecFile)
 	} else if o.Output == jsonOutput {
@@ -226,7 +226,7 @@ func (o *Options) Run() error {
 func Preview(
 	o *Options,
 	storage states.StateStorage,
-	planResources *models.Spec,
+	planResources *models.Intent,
 	project *projectstack.Project,
 	stack *projectstack.Stack,
 ) (*opsmodels.Changes, error) {

pkg/cmd/preview/options_test.go

@@ -53,7 +53,7 @@ func Test_preview(t *testing.T) {
 		defer m.UnPatch()
 
 		o := NewPreviewOptions()
-		_, err := Preview(o, stateStorage, &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, project, stack)
+		_, err := Preview(o, stateStorage, &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, project, stack)
 		assert.Nil(t, err)
 	})
 }
@@ -241,8 +241,8 @@ func mockGenerateSpec() *mockey.Mocker {
 		o *generator.Options,
 		project *projectstack.Project,
 		stack *projectstack.Stack,
-	) (*models.Spec, error) {
-		return &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, nil
+	) (*models.Intent, error) {
+		return &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, nil
 	}).Build()
 }
 
@@ -251,8 +251,8 @@ func mockPatchGenerateSpecWithSpinner() *mockey.Mocker {
 		o *generator.Options,
 		project *projectstack.Project,
 		stack *projectstack.Stack,
-	) (*models.Spec, error) {
-		return &models.Spec{Resources: []models.Resource{sa1, sa2, sa3}}, nil
+	) (*models.Intent, error) {
+		return &models.Intent{Resources: []models.Resource{sa1, sa2, sa3}}, nil
 	}).Build()
 }
 

pkg/cmd/spec/generator.go

@@ -22,13 +22,13 @@ import (
 	"kusionstack.io/kusion/pkg/util/pretty"
 )
 
-func GenerateSpecWithSpinner(o *generator.Options, project *projectstack.Project, stack *projectstack.Stack) (*models.Spec, error) {
+func GenerateSpecWithSpinner(o *generator.Options, project *projectstack.Project, stack *projectstack.Stack) (*models.Intent, error) {
 	var sp *pterm.SpinnerPrinter
 	if o.NoStyle {
-		fmt.Printf("Generating Spec in the Stack %s...\n", stack.Name)
+		fmt.Printf("Generating Intent in the Stack %s...\n", stack.Name)
 	} else {
 		sp = &pretty.SpinnerT
-		sp, _ = sp.Start(fmt.Sprintf("Generating Spec in the Stack %s...", stack.Name))
+		sp, _ = sp.Start(fmt.Sprintf("Generating Intent in the Stack %s...", stack.Name))
 	}
 
 	// style means color and prompt here. Currently, sp will be nil only when o.NoStyle is true
@@ -55,7 +55,7 @@ func GenerateSpecWithSpinner(o *generator.Options, project *projectstack.Project
 	return spec, nil
 }
 
-func GenerateSpec(o *generator.Options, project *projectstack.Project, stack *projectstack.Stack) (*models.Spec, error) {
+func GenerateSpec(o *generator.Options, project *projectstack.Project, stack *projectstack.Stack) (*models.Intent, error) {
 	// Choose the generator
 	var g generator.Generator
 	pg := project.Generator
@@ -114,7 +114,7 @@ func buildAppConfigs(o *generator.Options, stack *projectstack.Stack) (map[strin
 	return appConfigs, nil
 }
 
-func GenerateSpecFromFile(filePath string) (*models.Spec, error) {
+func GenerateSpecFromFile(filePath string) (*models.Intent, error) {
 	b, err := os.ReadFile(filePath)
 	if err != nil {
 		return nil, err
@@ -125,7 +125,7 @@ func GenerateSpecFromFile(filePath string) (*models.Spec, error) {
 	// The use of yaml.v2 and yaml.v3 should be unified in the future.
 	decoder := yamlv3.NewDecoder(bytes.NewBuffer(b))
 	decoder.KnownFields(true)
-	spec := &models.Spec{}
+	spec := &models.Intent{}
 	if err = decoder.Decode(spec); err != nil && err != io.EOF {
 		return nil, fmt.Errorf("failed to parse the spec file, please check if the file content is valid")
 	}

pkg/cmd/spec/generator_test.go

@@ -31,7 +31,7 @@ resources:
     spec: {}
     status: {}
 `
-	specModel1 = &models.Spec{
+	specModel1 = &models.Intent{
 		Resources: []models.Resource{
 			{
 				ID:   "v1:Namespace:default",
@@ -68,7 +68,7 @@ resources:
       name: kube-system
 `
 
-	specModel2 = &models.Spec{
+	specModel2 = &models.Intent{
 		Resources: []models.Resource{
 			{
 				ID:   "v1:Namespace:default",
@@ -95,7 +95,7 @@ resources:
 		},
 	}
 
-	specModel3 = &models.Spec{
+	specModel3 = &models.Intent{
 		Resources: []models.Resource{
 			{
 				ID:   "v1:Namespace:default",
@@ -123,7 +123,7 @@ func TestGenerateSpecFromFile(t *testing.T) {
 		name    string
 		path    string
 		content string
-		want    *models.Spec
+		want    *models.Intent
 		wantErr bool
 	}{
 		{
@@ -176,7 +176,7 @@ func TestGenerateSpec(t *testing.T) {
 	tests := []struct {
 		name    string
 		args    args
-		want    *models.Spec
+		want    *models.Intent
 		wantErr bool
 	}{
 		{

pkg/engine/kcl.go

@@ -11,7 +11,7 @@ import (
 
 const MaxLogLength = 3751
 
-func KCLResult2Spec(kclResults []kcl.KCLResult) (*models.Spec, error) {
+func KCLResult2Spec(kclResults []kcl.KCLResult) (*models.Intent, error) {
 	resources := make([]models.Resource, len(kclResults))
 
 	for i, result := range kclResults {
@@ -36,5 +36,5 @@ func KCLResult2Spec(kclResults []kcl.KCLResult) (*models.Spec, error) {
 		resources[i] = item
 	}
 
-	return &models.Spec{Resources: resources}, nil
+	return &models.Intent{Resources: resources}, nil
 }

pkg/engine/operation/apply.go

@@ -29,7 +29,7 @@ type ApplyResponse struct {
 	State *states.State
 }
 
-func NewApplyGraph(m *models.Spec, priorState *states.State) (*dag.AcyclicGraph, status.Status) {
+func NewApplyGraph(m *models.Intent, priorState *states.State) (*dag.AcyclicGraph, status.Status) {
 	specParser := parser.NewSpecParser(m)
 	g := &dag.AcyclicGraph{}
 	g.Add(&graph.RootNode{})
@@ -167,7 +167,7 @@ func validateRequest(request *opsmodels.Request) status.Status {
 	}
 	if request.Spec == nil {
 		return status.NewErrorStatusWithMsg(status.InvalidArgument,
-			"request.Spec is empty. If you want to delete all resources, please use command 'destroy'")
+			"request.Intent is empty. If you want to delete all resources, please use command 'destroy'")
 	}
 	resourceKeyMap := make(map[string]bool)