[jcogilvie]

Description of your changes

Adds an alpha crossplane project simulate (#367) built on the crossplane diff engine, ported from crossplane-diff into internal/diff. It previews how a project's changed Compositions and embedded functions affect the XRs on a live cluster.

Builds on #429 (resource simulate, merged).

Work in progress toward #367. Done so far:

• Engine port (internal/diff/**): renderer, types, ref, dockerrun, the core/kubernetes/crossplane clients and the diffprocessor, ported verbatim from crossplane-diff (import rewrites and gci grouping only), plus a client bundle client.New.

• Integration tests (internal/diff/integration): every case from crossplane-diff's TestDiffIntegration and TestCompDiffIntegration at 6a140b6, run against envtest with the real Docker render engine. The case tables are verbatim. One runSimulate function translates each case's crossplane-diff arguments and runs the real project simulate command through kong.

  • 142 cases: 139 pass. One skips with gap: simulate has no repeated --resource scoping, and two carry upstream's own skips. grep -rn 'gap:' lists what is left to enable.

• Project glue: project.LoadFunctions (lifted from render xr), project.LoadCompositions, an overlay FunctionProvider that serves project functions by name and falls back to the cluster's, and kube.RESTConfig (now shared with resource simulate).

• project simulate command (alpha). -f/--input is repeatable and picks the mode from what it's given:

  • Project file (the default): Compositions from the project, with the project's functions overlaid on the cluster's.
  • Composition files: crossplane-diff's comp. XRs are found on the cluster, and the cluster's functions run.
  • XR or claim files: crossplane-diff's xr. Compositions and functions come from the cluster.
  • Rejected: a project file mixed with other inputs, and Compositions mixed with other resources.
  • Per-mode flags: a flag that doesn't apply to the chosen mode is rejected, as crossplane-diff's comp and xr do.
  • Other flags: -c/--context, impersonation, -n, --name, --include-pinned, --max-iterations, --timeout, --max-concurrency, -o diff|json|yaml, --output-version, the render-backend version flags, and crossplane-diff's other common flags (--ignore-paths, --function-credentials, --dry-run-on, --analyze-on, ...).

• Engine boundary (tracking upstream): ported from crossplane-diff#591, #593, #594 and #595:

  • Object comparison lives in internal/diff/compare.
  • Processors return reports (XRReport, CompDiffOutput), and the command renders them.
  • The output model lives in internal/diff/result.
  • Filtered and pinned XRs are always recorded.

  The CLI keeps its own error printing: errors print once, via kong, not inline.

• Mapper: internal/simulate.FromXRReport and FromCompReport turn engine reports into plan.Result, with Secrets redacted and claims kept. It is not wired into the command yet.

• plan.Result: carries composite grouping, typed errors with validation failures, warnings, revision impact for each Composition, dry-run verification and a deferred count. The text renderer groups plans under their XR. resource simulate's output is unchanged, and its JSON formatVersion is now 0.2.

• internal/simulate: resource simulate's per-resource planning moves into a reusable Planner (Plan, PlanWithLive) and RelevantProviderImages, so project simulate can plan composed MRs through the provider diff servers.

• Render: a typed render.ErrStaleRenderBackend, so the engine can tell a stale render backend apart from other errors.

• Nix and CI: pinned Crossplane v2.4.1 CRDs and envtest v1.30.3 assets for the tests. The integration tests need Docker for the render engine, and the Nix sandbox has none. So they sit behind an integration build tag, the same way the existing compilegate tests do, and lint still covers them. They run through their own nix run .#integration-test app and integration-tests CI job, outside the sandbox. Unit tests and flake check are unchanged. The integration job writes a -coverpkg=./... profile and uploads it to codecov under the integration flag. Codecov merges it with the unittests upload for the same commit. A later e2e suite fits in as a third tag, app and job.

Still to do for #367:

• -o plan as the default, with json|yaml emitting plan.Result through one mapper. Then drop --output-version and crossplane-diff's v1/v2 schemas, and rewrite the structured IT assertions
• Plan each composed MR through the provider diff servers, with inline # forces replacement and (known after apply) in -o diff
• Claims, and the exception for pinned XRs when an embedded function changes
• CODEOWNERS for the ported packages

Decisions to review (hard to reverse, even under alpha):

• Output: -o plan is the default. -o json|yaml emit plan.Result (formatVersion 0.2), and -o diff is crossplane-diff's diff. --output-version is hidden and temporary: it selects crossplane-diff's schema while the integration tests move over, and is then removed.
• Field path grammar in plan.Result: path is one string. Plain keys join with ., list indexes are [N], and any other key is quoted terraform-style as ["key"], e.g. metadata.annotations["crossplane.io/composite"]. This lets annotation and label keys round-trip, but json/yaml consumers must parse the grammar to split a path. An additive segments list is an option if that's a burden. Paths from upjet's diff servers don't quote dotted TF map keys (e.g. a tags key a.b), which needs an upjet change.
• Exit codes: 0 (no changes), 1 (error), 2 (schema validation only), 3 (changes found) or 130 (interrupted), with crossplane-diff's precedence 1 > 2 > 3, so changes exit 3 by default as in crossplane-diff. Changes found are a result, not an error: simulate sets a kong-bound common.ExitStatus that main exits with after a run that returns no error. Errors still exit through kong's FatalIfErrorf.
• Flag names: -f/--input (its long form was --project-file), --name, --include-pinned, -c/--context.
• -f classification: a single file that isn't a project file and holds no Compositions is treated as XRs. Each one is checked against the cluster's XRDs, as a claim and then as an XR, and anything else (a Configuration, a Provider, a ConfigMap) is rejected with its kind, name and what -f accepts.
• Errors print once: the ported renderers no longer write each error to stderr inline as ERROR: Kind/name: .... kong prints the returned error once, as crossplane: error: ..., and that error names each failing resource. This deviates from crossplane-diff, which printed both. Structured output's errors[] is unchanged.
• Target cluster: the user's kubeconfig context, not the dev control plane.
• Cluster-wide listing: diff comp lists Functions, Compositions and XRDs cluster-wide on startup. That conflicts with the issue's "no cluster-wide work beyond the scoped discovery"; it is flagged here, not fixed yet.

Also worth a look:

• fix(project): project build with spec.paths.apis: "/" no longer packages XRDs and Compositions from examples, functions and operations. It's a separate commit, easy to cherry-pick on its own.
• Dependency bumps forced by the port: go.yaml.in/yaml/v3 v3.0.5, golang.org/x/sys v0.48.0. The port's semver use moved to Masterminds v3.
• Exit code 80: a render version below the v2.3.4 floor exits 80 (kong's parse-error code), not 1.
• Timeout: --timeout covers the whole run, not each XR.
• No manual end-to-end run: the command hasn't been run by hand against a real cluster; the integration tests run it against envtest. Stdin input (-f -) hasn't been tested end to end.

I have:

• Read and followed Crossplane's contribution process.
• Run ./nix.sh flake check to ensure this PR is ready for review.
• Added or updated unit tests.
• Linked a PR or a docs tracking issue to document this change.
• Added backport release-x.y labels to auto-backport this PR.

🤖 Generated with Claude Code