feat(project): add alpha project simulate on the ported crossplane-diff engine

.github/workflows/ci.yml

@@ -111,6 +111,45 @@ jobs:
           file: result/coverage.txt
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  # The diff integration tests run the render engine's functions as Docker
+  # containers, so they cannot run in the Nix sandbox like the unit tests.
+  # The app runs outside the sandbox against the runner's Docker daemon.
+  integration-tests:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
+
+      - name: Setup Cachix
+        uses: cachix/cachix-action@38b082610b782e7e93e209c35fd730d399dee866 # v17
+        with:
+          name: crossplane
+          authToken: ${{ secrets.CACHIX_AUTH_TOKEN }}
+
+      - name: Cache Go modules and build cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-go-integration-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-integration-
+
+      - name: Run Integration Tests
+        run: nix run .#integration-test --option warn-dirty false
+
+      - name: Publish Integration Test Coverage
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7
+        with:
+          flags: integration
+          file: coverage-integration.txt
+          token: ${{ secrets.CODECOV_TOKEN }}
+
   # Build all artifacts
   build-artifacts:
     permissions:

.gitignore

@@ -13,8 +13,8 @@ Zone.Identifier
 build/
 
 # Nix build output symlinks
-result
-result-*
+/result
+/result-*
 
 # Exclude the ko data dir
 kodata/
@@ -45,3 +45,5 @@ AGENTS.md
 
 # Ignore local dev environment variables
 .env
+/coverage-integration.txt
+/coverage-merged.txt

.golangci.yml

@@ -6,6 +6,10 @@ run:
   # runs our unit tests. Lint them anyway, so they don't rot.
   build-tags:
     - compilegate
+    # The diff integration tests need Docker and envtest, so they sit behind
+    # the integration tag and run in their own target, not the unit tests.
+    # Lint them anyway.
+    - integration
 
 output:
   formats:

cmd/crossplane/common/exit.go

@@ -0,0 +1,82 @@
+/*
+Copyright 2026 The Crossplane 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 common
+
+import "errors"
+
+// Exit statuses the simulate commands share.
+const (
+	// ExitCodeSchemaValidation means only schema validation failed.
+	ExitCodeSchemaValidation = 2
+	// ExitCodeChanges means the simulation succeeded and found changes.
+	ExitCodeChanges = 3
+	// ExitCodeUsage is the status kong exits with for parse and Validate
+	// errors. Commands return it for invalid flags they can only detect in
+	// Run.
+	ExitCodeUsage = 80
+)
+
+// ExitError is an error that sets the command's exit status; it implements
+// kong.ExitCoder. With a nil Err it reports a result that is not an error,
+// such as changes found: main exits with Code without printing anything.
+// Return it by value and unwrapped: main exits silently only when the
+// returned error carries no message besides a silent ExitError, so one
+// wrapped with a message or joined with another error, or a pointer, is
+// printed as an error.
+type ExitError struct {
+	// Err is the error to print, or nil to exit silently.
+	Err error
+
+	// Code is the status to exit with.
+	Code int
+}
+
+// Error returns Err's message, or an empty string when Err is nil.
+func (e ExitError) Error() string {
+	if e.Err == nil {
+		return ""
+	}
+	return e.Err.Error()
+}
+
+// ExitCode implements kong.ExitCoder.
+func (e ExitError) ExitCode() int {
+	return e.Code
+}
+
+// Unwrap returns Err.
+func (e ExitError) Unwrap() error {
+	return e.Err
+}
+
+// Silent reports whether e exits without printing anything.
+func (e ExitError) Silent() bool {
+	return e.Err == nil
+}
+
+// SilentExit returns the code of a silent ExitError value in err's chain
+// when err has no message of its own, and false otherwise. kong's
+// Context.Run joins the command's error with its AfterRun hooks' errors, so
+// the check can't require err to be the ExitError itself; requiring an empty
+// message still keeps a wrapping or joined error from being swallowed.
+func SilentExit(err error) (int, bool) {
+	var e ExitError
+	if err == nil || err.Error() != "" || !errors.As(err, &e) || !e.Silent() {
+		return 0, false
+	}
+	return e.Code, true
+}

cmd/crossplane/common/exit_test.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2026 The Crossplane 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 common
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/crossplane/crossplane-runtime/v2/pkg/errors"
+)
+
+func TestSilentExit(t *testing.T) {
+	type want struct {
+		code   int
+		silent bool
+	}
+	cases := map[string]struct {
+		reason string
+		err    error
+		want   want
+	}{
+		"Nil":      {reason: "No error isn't a silent exit.", err: nil},
+		"Silent":   {reason: "A silent ExitError value exits silently with its code.", err: ExitError{Code: ExitCodeChanges}, want: want{code: ExitCodeChanges, silent: true}},
+		"WithErr":  {reason: "An ExitError with an error is printed.", err: ExitError{Code: 2, Err: errors.New("boom")}},
+		"Wrapped":  {reason: "A wrapped silent ExitError is printed, so the wrapper's message isn't lost.", err: errors.Wrap(ExitError{Code: ExitCodeChanges}, "boom")},
+		"KongJoin": {reason: "kong's Run joins a silent ExitError with nil hook errors, which still exits silently.", err: errors.Join(ExitError{Code: ExitCodeChanges}, nil), want: want{code: ExitCodeChanges, silent: true}},
+		"Joined":   {reason: "A silent ExitError joined with a real error is printed.", err: errors.Join(ExitError{Code: ExitCodeChanges}, errors.New("boom"))},
+		"Pointer":  {reason: "A pointer isn't matched; ExitError must be returned by value.", err: &ExitError{Code: ExitCodeChanges}},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			code, silent := SilentExit(tc.err)
+			if diff := cmp.Diff(tc.want, want{code: code, silent: silent}, cmp.AllowUnexported(want{})); diff != "" {
+				t.Errorf("\n%s\nSilentExit(...): -want, +got:\n%s", tc.reason, diff)
+			}
+		})
+	}
+}

cmd/crossplane/common/load/loader.go

@@ -63,8 +63,15 @@ func NewLoader(input string) (Loader, error) {
 }
 
 func newLoader(input string) (Loader, error) {
+	return newSourceLoader(input, false)
+}
+
+// newSourceLoader returns the Loader for one input. With skipPipelineInputs,
+// the loader doesn't return Composition pipeline step inputs as manifests of
+// their own.
+func newSourceLoader(input string, skipPipelineInputs bool) (Loader, error) {
 	if input == "-" {
-		return &StdinLoader{}, nil
+		return &StdinLoader{skipPipelineInputs: skipPipelineInputs}, nil
 	}
 
 	fi, err := os.Stat(input)
@@ -73,10 +80,10 @@ func newLoader(input string) (Loader, error) {
 	}
 
 	if fi.IsDir() {
-		return &FolderLoader{path: input}, nil
+		return &FolderLoader{path: input, skipPipelineInputs: skipPipelineInputs}, nil
 	}
 
-	return &FileLoader{path: input}, nil
+	return &FileLoader{path: input, skipPipelineInputs: skipPipelineInputs}, nil
 }
 
 // MultiLoader implements the Loader interface for reading from multiple other loaders.
@@ -101,7 +108,9 @@ func (m *MultiLoader) Load() ([]*unstructured.Unstructured, error) {
 }
 
 // StdinLoader implements the Loader interface for reading from stdin.
-type StdinLoader struct{}
+type StdinLoader struct {
+	skipPipelineInputs bool
+}
 
 // Load reads the contents from stdin.
 func (s *StdinLoader) Load() ([]*unstructured.Unstructured, error) {
@@ -110,12 +119,13 @@ func (s *StdinLoader) Load() ([]*unstructured.Unstructured, error) {
 		return nil, errors.Wrap(err, "cannot load YAML stream from stdin")
 	}
 
-	return streamToUnstructured(stream)
+	return streamToUnstructured(stream, s.skipPipelineInputs)
 }
 
 // FileLoader implements the Loader interface for reading from a file and converting input to unstructured objects.
 type FileLoader struct {
-	path string
+	path               string
+	skipPipelineInputs bool
 }
 
 // Load reads the contents from a file.
@@ -125,12 +135,13 @@ func (f *FileLoader) Load() ([]*unstructured.Unstructured, error) {
 		return nil, errors.Wrap(err, "cannot read file")
 	}
 
-	return streamToUnstructured(stream)
+	return streamToUnstructured(stream, f.skipPipelineInputs)
 }
 
 // FolderLoader implements the Loader interface for reading from a folder.
 type FolderLoader struct {
-	path string
+	path               string
+	skipPipelineInputs bool
 }
 
 // Load reads the contents from all files in a folder.
@@ -157,7 +168,7 @@ func (f *FolderLoader) Load() ([]*unstructured.Unstructured, error) {
 		return nil, errors.Wrap(err, "cannot read folder")
 	}
 
-	return streamToUnstructured(stream)
+	return streamToUnstructured(stream, f.skipPipelineInputs)
 }
 
 func isYamlFile(info os.FileInfo) bool {
@@ -200,7 +211,10 @@ func YamlStream(r io.Reader) ([][]byte, error) {
 	return stream, nil
 }
 
-func streamToUnstructured(stream [][]byte) ([]*unstructured.Unstructured, error) {
+// streamToUnstructured parses stream. Unless skipPipelineInputs is set, it also
+// returns each Composition pipeline step input as a manifest of its own, so
+// validate can check the inputs against their schemas.
+func streamToUnstructured(stream [][]byte, skipPipelineInputs bool) ([]*unstructured.Unstructured, error) {
 	manifests := make([]*unstructured.Unstructured, 0, len(stream))
 
 	for _, y := range stream {
@@ -215,7 +229,7 @@ func streamToUnstructured(stream [][]byte) ([]*unstructured.Unstructured, error)
 		}
 
 		// extract pipeline input resources
-		if u.GetObjectKind().GroupVersionKind() == v1.CompositionGroupVersionKind {
+		if !skipPipelineInputs && u.GetObjectKind().GroupVersionKind() == v1.CompositionGroupVersionKind {
 			// Convert the unstructured resource to a Composition
 			var comp v1.Composition
 
@@ -259,6 +273,35 @@ type CompositeLoader struct {
 // Sources can be files, directories, or "-" for stdin.
 // If sources is empty, stdin is used by default.
 func NewCompositeLoader(sources []string) (Loader, error) {
+	return newCompositeLoader(sources, NewLoader)
+}
+
+// ExactCompositeLoaderOption configures NewExactCompositeLoader.
+type ExactCompositeLoaderOption func(*exactCompositeLoaderOptions)
+
+type exactCompositeLoaderOptions struct {
+	skipPipelineInputs bool
+}
+
+// WithoutPipelineInputs stops the loader from returning each Composition
+// pipeline step input as a manifest of its own. By default it returns them.
+func WithoutPipelineInputs() ExactCompositeLoaderOption {
+	return func(o *exactCompositeLoaderOptions) { o.skipPipelineInputs = true }
+}
+
+// NewExactCompositeLoader is NewCompositeLoader, except each source is exactly
+// one path or "-": commas are part of the path, not separators.
+func NewExactCompositeLoader(sources []string, opts ...ExactCompositeLoaderOption) (Loader, error) {
+	o := &exactCompositeLoaderOptions{}
+	for _, fn := range opts {
+		fn(o)
+	}
+	return newCompositeLoader(sources, func(source string) (Loader, error) {
+		return newSourceLoader(source, o.skipPipelineInputs)
+	})
+}
+
+func newCompositeLoader(sources []string, newSource func(string) (Loader, error)) (Loader, error) {
 	if len(sources) == 0 {
 		// In unit tests, this will cause an error when Load() is called
 		// which is the expected behavior for NoSources test case
@@ -280,7 +323,7 @@ func NewCompositeLoader(sources []string) (Loader, error) {
 			stdinUsed = true
 		}
 
-		loader, err := NewLoader(source)
+		loader, err := newSource(source)
 		if err != nil {
 			return nil, errors.Wrapf(err, "cannot create loader for %q", source)
 		}