Add cluster-free component preview for whole-component golden tests

[sourcehawk]

Summary

Closes #121.

Adds a public, cluster-free way to render a built Component's assembled desired-state resources, so consumers can snapshot-test the full resource set the controller actually builds (baseline + mutations + registration order) without a fake client or a reconcile.

• New capability interface concepts.Previewable { Preview() (client.Object, error) }, implemented by generic.BaseResource (wrapping the existing no-side-effect PreviewObject() engine).
• Component.Preview() ([]client.Object, error) renders managed reconcile resources in registration order, with no cluster IO. Read-only resources (fetched, not applied) and delete resources (removal markers) are excluded. Errors if a managed resource is not previewable, renders a nil object, or fails to render. Reconcile remains the only IO path.
• Component.Resource(identity string) (Resource, bool) looks up any registered resource by its Identity().
• pkg/testing/golden gains whole-component helpers CompareComponentYAML / AssertComponentYAML that serialize a component's preview into one multi-document (----separated) golden file.

Breaking changes (pre-1.0)

• Each primitive's typed PreviewObject() (*Concrete, error) is replaced by a single Preview() (client.Object, error). Callers needing the concrete type assert on the returned client.Object. The typed engine generic.BaseResource.PreviewObject() is retained for internal/custom-resource use.
• The golden single-resource API is now non-generic: Previewer, CompareYAML, AssertYAML use Preview() instead of the generic PreviewObject[T]. Existing golden.AssertYAML(t, path, res, ...) call sites are unchanged.

Docs updated in docs/component.md and docs/guidelines.md.

Test Plan

• make all (lint, format, unit tests) passes
• go test ./... — 42 packages, 0 failures
• make build-examples builds; example tests pass
• New tests cover: registration order, read-only/delete exclusion, not-previewable error, render-error wrapping, nil-object guard, BaseResource.Preview no-side-effect under a real mutation, golden multi-document match/mismatch/update/empty
• No e2e needed: pure in-memory desired-state rendering with no cluster IO

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a public cluster-free preview path so components and resource primitives can render desired-state Kubernetes objects for snapshot/golden testing without running reconciliation or using a client.

Changes:

• Adds concepts.Previewable, Component.Preview, and Component.Resource.
• Replaces primitive-level typed PreviewObject public methods with Preview() (client.Object, error).
• Adds whole-component golden YAML helpers and updates examples/docs/tests.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/component/component.go	Adds component preview and resource lookup APIs.
pkg/component/component_test.go	Tests component preview and lookup behavior.
pkg/component/concepts/previewable.go	Defines the preview capability interface.
pkg/component/concepts/previewable_test.go	Verifies previewable interface shape.
pkg/component/zz_mock_resource_test.go	Adds a previewable mock resource.
pkg/generic/resource_base.go	Adds polymorphic Preview wrapper around PreviewObject.
pkg/generic/resource_base_test.go	Tests generic preview behavior and no state mutation.
pkg/testing/golden/golden.go	Adds non-generic preview APIs and component YAML comparison.
pkg/testing/golden/golden_test.go	Tests component golden output behavior.
pkg/primitives/*/resource.go	Updates built-in primitives to expose Preview.
pkg/primitives/deployment/preview_test.go	Adds previewable conformance assertion.
examples/mutations-and-gating/features/*.go	Updates examples to use Preview with type assertions.
examples/custom-resource/resources/certificate_test.go	Updates custom-resource preview test.
docs/component.md	Documents component preview and resource lookup.
docs/guidelines.md	Documents whole-component golden snapshots.