microsoft · dmcilvaney · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/docs/developer/reference/component-identity.md b/docs/developer/reference/component-identity.md
@@ -0,0 +1,56 @@
+# Component Identity & Change Detection
+
+The `component identity` and `component diff-identity` subcommands compute deterministic fingerprints of component build inputs. For example, CI can compute fingerprints for the base and head commits of a PR, then diff them to determine exactly which components have changed and need to be rebuilt/tested.
+
+```bash
+# Typical CI workflow
+git checkout $BASE_REF && azldev component identity -a -O json > base.json
+git checkout $HEAD_REF && azldev component identity -a -O json > head.json
+azldev component diff-identity base.json head.json -O json -c
+# → {"changed": ["curl"], "added": ["wget"], "removed": [], "unchanged": []}
+```
+
+## Fingerprint Inputs
+
+A component's fingerprint is a SHA256 combining:
+
+1. **Config hash** — `hashstructure.Hash()` of the resolved `ComponentConfig` (after all merging). Fields tagged `fingerprint:"-"` are excluded.
+2. **Source identity** — content hash for local specs (all files in the spec directory), commit hash for upstream.
+3. **Overlay file hashes** — SHA256 of each file referenced by overlay `Source` fields.
+4. **Distro name + version**
+5. **Affects commit count** — number of `Affects: <component>` commits in the project repo.
+
+Global change propagation works automatically: the fingerprint operates on the fully-merged config, so a change to a distro or group default changes the resolved config of every inheriting component.
+
+## `fingerprint:"-"` Tag System
+
+The `hashstructure` library uses `TagName: "fingerprint"`. Untagged fields are **included by default** (safe default: false positive > false negative).
+
+A guard test (`TestAllFingerprintedFieldsHaveDecision`) reflects over all fingerprinted structs and maintains a bi-directional allowlist of exclusions. It fails if a `fingerprint:"-"` tag is added without registering it, or if a registered exclusion's tag is removed.
+
+### Adding a New Config Field
+
+1. Add the field to the struct in `internal/projectconfig/`.
+2. **If NOT a build input**: add `fingerprint:"-"` to the struct tag and register it in `expectedExclusions` in `internal/projectconfig/fingerprint_test.go`.
+3. **If a build input**: do nothing — included by default.
+4. Run `mage unit`.
+
+### Adding a New Source Type
+
+1. Implement `SourceIdentityProvider` on your provider (see `ResolveLocalSourceIdentity` in `localidentity.go` for a simple example).
+2. Add a case to `sourceManager.ResolveSourceIdentity()` in `sourcemanager.go`.
+3. Add tests in `identityprovider_test.go`.
+
+## CLI
+
+### `azldev component identity`
+
+Compute fingerprints. Uses standard component filter flags (`-a`, `-p`, `-g`, `-s`). Exposed as an MCP tool.
+
+### `azldev component diff-identity`
+
+Compare two identity JSON files. The `--changed-only` / `-c` flag filters to only changed and added components (the build queue). Applies to both table and JSON output.
+
+## Known Limitations
+
+- It is difficult to determine WHY a diff occurred (e.g., which specific field changed) since the fingerprint is a single opaque hash. The JSON output includes an `inputs` breakdown (`configHash`, `sourceIdentity`, `overlayFileHashes`, etc.) that can help narrow it down by comparing the two identity files manually.
diff --git a/docs/user/reference/cli/azldev_component.md b/docs/user/reference/cli/azldev_component.md
diff --git a/docs/user/reference/cli/azldev_component_diff-identity.md b/docs/user/reference/cli/azldev_component_diff-identity.md
diff --git a/docs/user/reference/cli/azldev_component_identity.md b/docs/user/reference/cli/azldev_component_identity.md
diff --git a/go.mod b/go.mod
@@ -36,6 +36,7 @@ require (
 	github.com/magefile/mage v1.16.1
 	github.com/mark3labs/mcp-go v0.45.0
 	github.com/mattn/go-isatty v0.0.20
+	github.com/mitchellh/hashstructure/v2 v2.0.2
 	github.com/muesli/termenv v0.16.0
 	github.com/nxadm/tail v1.4.11
 	github.com/opencontainers/selinux v1.13.1

diff --git a/go.sum b/go.sum
@@ -229,6 +229,8 @@ github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh
 github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
 github.com/mattn/go-runewidth v0.0.21 h1:jJKAZiQH+2mIinzCJIaIG9Be1+0NR+5sz/lYEEjdM8w=
 github.com/mattn/go-runewidth v0.0.21/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4=
+github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=

diff --git a/internal/app/azldev/cmds/component/component.go b/internal/app/azldev/cmds/component/component.go
@@ -25,7 +25,9 @@ components defined in the project configuration.`,
 	app.AddTopLevelCommand(cmd)
 	addOnAppInit(app, cmd)
 	buildOnAppInit(app, cmd)
+	diffIdentityOnAppInit(app, cmd)
 	diffSourcesOnAppInit(app, cmd)
+	identityOnAppInit(app, cmd)
 	listOnAppInit(app, cmd)
 	prepareOnAppInit(app, cmd)
 	queryOnAppInit(app, cmd)