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:
@@ -107,6 +111,11 @@ linters:
     # Deprecated and replaced by a new version, but still on by default.
     - gomodguard
   settings:
+    exhaustive:
+      # Only check switches marked //exhaustive:enforce, and don't let a
+      # default case satisfy them.
+      explicit-exhaustive-switch: true
+      default-signifies-exhaustive: false
     depguard:
       rules:
         no_third_party_test_libraries:

cmd/crossplane/common/exit.go

@@ -0,0 +1,26 @@
+/*
+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
+
+// ExitStatus is the exit status of a command that returns no error. main
+// binds a pointer to one, so a command's Run can take it as a parameter and
+// set a non-zero status for a result that is not an error, such as changes
+// found. An error the command returns takes precedence over the status.
+type ExitStatus struct {
+	// Code is the status to exit with. Zero unless the command sets it.
+	Code int
+}

cmd/crossplane/common/load/loader.go

@@ -259,6 +259,16 @@ 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)
+}
+
+// NewExactCompositeLoader is NewCompositeLoader, except each source is exactly
+// one path or "-": commas are part of the path, not separators.
+func NewExactCompositeLoader(sources []string) (Loader, error) {
+	return newCompositeLoader(sources, newLoader)
+}
+
+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 +290,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)
 		}

cmd/crossplane/main.go

@@ -37,6 +37,7 @@ import (
 	runtimexpkg "github.com/crossplane/crossplane-runtime/v2/pkg/xpkg"
 
 	"github.com/crossplane/cli/v2/cmd/crossplane/cluster"
+	"github.com/crossplane/cli/v2/cmd/crossplane/common"
 	"github.com/crossplane/cli/v2/cmd/crossplane/completion"
 	"github.com/crossplane/cli/v2/cmd/crossplane/composition"
 	configcmd "github.com/crossplane/cli/v2/cmd/crossplane/config"
@@ -131,6 +132,7 @@ func main() {
 		os.Exit(1)
 	}
 
+	status := &common.ExitStatus{}
 	parser := kong.Must(&cli{},
 		kong.Name("crossplane"),
 		// Binding a variable to kong context makes it available to all commands
@@ -139,6 +141,8 @@ func main() {
 		kong.BindTo(configcmd.ConfigPath(cfgPath), (*configcmd.ConfigPath)(nil)),
 		// Bind the loaded config so commands can read feature flags at runtime.
 		kong.Bind(cfg),
+		// Commands set the exit status of a run that returns no error.
+		kong.Bind(status),
 		kongVars,
 		kong.Help(helpPrinter),
 		kong.UsageOnError())
@@ -185,7 +189,12 @@ func main() {
 		}
 		os.Exit(130)
 	}
+	// An error is printed and exits 1, or with its ExitCoder's code;
+	// otherwise the run exits with the status its command set.
 	ctx.FatalIfErrorf(err)
+	if status.Code != 0 {
+		os.Exit(status.Code)
+	}
 }
 
 // exitOnSignal waits for SIGINT or SIGTERM, then exits with status 130

cmd/crossplane/project/help/simulate.md

@@ -0,0 +1,201 @@
+The `project simulate` command previews how applying a project's Compositions,
+or changed Composition or composite resource files, would change the composite
+resources in a cluster. It renders each affected composite resource and shows
+the difference from what's in the cluster. It doesn't change the cluster.
+
+The `-f` flag picks what to simulate. Repeat it to pass more than one file or
+directory, or pass `-` to read from standard input:
+
+- A project file, the default, simulates the project. The command builds the
+  project's embedded functions and loads them into the local Docker daemon,
+  resolves its function dependencies, and collects the Compositions under its
+  APIs path. It renders each composite resource that uses one of those
+  Compositions with the project's version of the Composition, using the
+  project's functions in place of the cluster's functions of the same name.
+- Composition files simulate those Compositions without a project. The command
+  renders each composite resource in the cluster that uses one of them, with
+  the functions installed in the cluster.
+- Composite resource or claim files simulate those resources. The command
+  renders each one with the Composition the cluster selects for it and the
+  functions installed in the cluster.
+
+A project file must be the only `-f` input, and one run can't mix Compositions
+with composite resources. Any other resource, such as package metadata, a
+Provider or a ConfigMap, is rejected: each one must be a kind an XRD in the
+cluster defines as a composite resource or claim.
+
+The command connects to the cluster in your current Kubernetes context, or the
+one `--context` names.
+
+The command needs Docker, to build and run functions, and read access to the
+cluster's Crossplane resources. It verifies the rendered resources with
+server-side dry-run requests, so it also needs the `create` and `patch` verbs on
+them. Use `--as`, `--as-group`, and `--as-uid` to simulate as another user.
+
+By default, `simulate` skips composite resources with a `Manual` composition
+update policy, because they don't adopt a new Composition revision on their
+own. A pinned composite whose revision calls a function the project changes is
+still simulated, rendered against the revision it's pinned to. Pass
+`--include-pinned` to render every pinned composite against the new Composition
+instead.
+
+Some flags apply only to some inputs. `--namespace`, `--name`,
+`--include-pinned`, `--analyze-on`, and `--minimize-composition` choose which
+composite resources a Composition change reaches, so composite resource files
+don't take them. `--max-concurrency` configures the project's function builds,
+so only a project file takes it. `--cache-dir` caches function builds and
+provider packages, so Composition and composite resource files take it unless
+`--skip-plan` is set.
+
+The `-o` flag picks the output format:
+
+- `plan`, the default, prints each change as a field-level plan, grouped under
+  the composite resource it belongs to. A changed Composition prints first,
+  with whether applying it creates a new Composition revision.
+- `json` and `yaml` print the same plan as a structured result, for CI and
+  other tools. Each plan carries the objects it compares, as `before` (the
+  live object, absent for a create) and `after` (the rendered object, absent
+  for a delete), with ignored paths, status and server-managed metadata
+  removed and Secret values redacted. A provider-planned resource's `after`
+  is the manifest sent to the provider, not the provider's view.
+- `diff` prints the line diff `crossplane-diff` prints.
+
+For example, a changed Composition run with `--skip-plan` prints a plan like this:
+
+```
+[~] Composition.apiextensions.crossplane.io xnetworks.example.org (update)
+    Applying this creates a new CompositionRevision, which 1 composite would adopt.
+    spec:
+      pipeline[0]:
+        input:
+          ~ region: "us-west-1" -> "us-east-1"
+
+XR: XNetwork.example.org team-a/prod-network
+  [~] VPC.ec2.aws.upbound.io prod-network (update)
+      spec:
+        forProvider:
+          ~ region: "us-west-1" -> "us-east-1"
+
+Plan: 0 to add, 2 to change, 0 to destroy.
+
+Note: Cloud-layer plan skipped (--skip-plan).
+```
+
+The `--timeout` flag, 2m by default, bounds the time to simulate one composite
+resource: its render and its resources' provider plans. Function and provider
+image pulls don't count, but the render image pull counts against the first
+composite resource's budget.
+
+By default `simulate` also runs provider plans: it asks each provider's diff
+server to plan the managed resources, so the plan shows changes the cluster
+can't see. The diff servers come from `--providers` when set, otherwise from
+the project's provider dependencies in project mode, otherwise from the
+providers installed on the cluster that own the rendered resources, started on
+demand. A resource no diff server serves keeps its cluster-layer diff. In `json`
+and `yaml` output, `approximate: true` on a plan means it was computed
+client-side, without a provider diff, because the provider couldn't diff that
+resource. The result's `notes` say when provider plans were skipped or no diff
+server served the resources.
+
+Provider plans are controlled by these flags:
+
+- `--skip-plan` doesn't run provider diff servers and shows only the
+  cluster-layer diff. It can't be combined with the three flags below.
+- `--providers` takes a YAML file or directory of Provider manifests to run as
+  diff servers, instead of discovering providers from the cluster.
+- `--image-configs` takes a YAML file of ImageConfig manifests that rewrite
+  provider image paths for local pulls. It defaults to the project's
+  imageConfigs when `-f` names a project file; in Composition and XR modes it
+  falls back, best effort, to the project file in the current directory.
+- `--session-id` sets the `simulate.crossplane.io/session` label on diff server
+  containers. It defaults to a random per-process ID.
+
+The command accepts the same diff-tuning flags as `crossplane-diff`:
+
+- `--ignore-paths` leaves paths out of the diff.
+- `--function-credentials` and `--function-registry-override` configure the
+  functions the render runs.
+- `--max-nested-depth` limits nested composite resource recursion.
+- `--dry-run-on` picks which resources the server-side dry run verifies:
+  `existing` or `all`, the default.
+- `--analyze-on` sets the smallest Composition change that triggers impact
+  analysis: `spec-change`, `any-change`, or `always`.
+- `--minimize-composition` collapses each changed Composition to one line in
+  `-o diff` output.
+- `--eventual-state` shows the state after all reconciliation cycles complete.
+- `--max-recv-message-size` raises the function gRPC message limit, in MB.
+- `--no-color` and `--compact` change how `-o diff` prints.
+
+The command exits with one of these statuses, so a CI pipeline can gate on
+the result:
+
+- 0: the simulation succeeded and found no changes.
+- 1: the simulation failed, including when the -f inputs can't be read or
+  can't be simulated together. If a provider plan fails, so does its whole
+  composite resource, which then reports an error entry and none of its
+  resources' plans.
+- 2: only schema validation failed.
+- 3: the simulation succeeded and found changes, including drift a provider
+  plan found that the cluster diff didn't.
+- 80: the flags were invalid, so nothing was simulated.
+- 130: the simulation was interrupted.
+
+When more than one applies, the lowest of 1, 2 and 3 wins.
+
+## Examples
+
+Simulate the project in the current directory against the current context:
+
+```shell
+crossplane project simulate
+```
+
+Simulate against another context, only for composite resources in one
+namespace:
+
+```shell
+crossplane project simulate --context=staging -n team-a
+```
+
+Simulate a single namespaced composite resource:
+
+```shell
+crossplane project simulate -n team-a --name=my-database
+```
+
+`--name` takes `[namespace/]name` and is repeatable or comma-separated. Simulate
+two composite resources in different namespaces:
+
+```shell
+crossplane project simulate --name=team-a/my-database --name=team-b/my-database
+```
+
+Print the plan as JSON:
+
+```shell
+crossplane project simulate -o json
+```
+
+Print the line diff `crossplane-diff` prints:
+
+```shell
+crossplane project simulate -o diff
+```
+
+Simulate a changed Composition without a project:
+
+```shell
+crossplane project simulate -f composition.yaml
+```
+
+Simulate changed composite resources:
+
+```shell
+crossplane project simulate -f xr.yaml -f claim.yaml
+```
+
+Simulate composite resources read from standard input:
+
+```shell
+cat xr.yaml | crossplane project simulate -f -
+```

cmd/crossplane/project/project.go

@@ -19,9 +19,10 @@ package project
 
 // Cmd contains project subcommands.
 type Cmd struct {
-	Init  initCmd  `cmd:"" help:"Initialize a new project."`
-	Build buildCmd `cmd:"" help:"Build a project into Crossplane packages."`
-	Push  pushCmd  `cmd:"" help:"Push a built project to an OCI registry."`
-	Run   runCmd   `cmd:"" help:"Build and run a project in a local dev control plane." novale:"Google.WordList[\"admin\"]"`
-	Stop  stopCmd  `cmd:"" help:"Tear down a local dev control plane."`
+	Init     initCmd     `cmd:"" help:"Initialize a new project."`
+	Build    buildCmd    `cmd:"" help:"Build a project into Crossplane packages."`
+	Push     pushCmd     `cmd:"" help:"Push a built project to an OCI registry."`
+	Run      runCmd      `cmd:"" help:"Build and run a project in a local dev control plane."                              novale:"Google.WordList[\"admin\"]"`
+	Simulate simulateCmd `cmd:"" help:"Preview how a project's Compositions would change a cluster's composite resources." maturity:"alpha"`
+	Stop     stopCmd     `cmd:"" help:"Tear down a local dev control plane."`
 }