Add cDAC usage graph analyzer and documentation gates by max-charlamb · Pull Request #131281 · dotnet/runtime

max-charlamb · 2026-07-23T18:14:25Z

Summary

Adds a Roslyn-based cDAC usage graph analyzer, generated contract usage documentation, and repository gates that keep the documentation synchronized with contract implementations.

Generated `IData` metadata

The IData source generator now emits dependency metadata for generated members, allowing the analyzer to identify descriptor reads without relying on implementation details:

GetSize(Target) helpers are generated for descriptor types and marked with [UsesDataDescriptorTypeSize].
Generated Get<X>Offset(Target) helpers are annotated with [DataDescriptorDependency] when they resolve a descriptor field dynamically.
Generated lazy [Field], [FieldAddress], write, and static-reference helpers carry [DataDescriptorDependency]; instance-data-start helpers carry [UsesDataDescriptorTypeSize].

Generated documentation and validation

The analyzer tracks cDAC contract, descriptor, global, callback, and contract-dependency usage. It generates marked usage sections in contract docs, supports version deltas and narrowly scoped documentation overrides, and adds gates that verify generated sections are current, every contract version is documented, and no placeholder meanings remain.

When a contract change makes a generated usage section stale, the test reports the affected document and repair command, for example:

Generated cDAC usage documentation is stale: StressLog.md.
To update it, run from the repository root:
  pwsh .\src\native\managed\cdac\tools\CdacUsageGraph\generate-docs.ps1
Review and commit the generated changes. If the generated dependencies are incorrect,
fix the usage-graph analysis or add a narrowly scoped entry to
docs\design\datacontracts\data-descriptor-overrides.json.

Testing

dotnet test .\src\native\managed\cdac\tests\UsageTests\Microsoft.Diagnostics.DataContractReader.Usage.Tests.csproj --no-restore -m:1
dotnet build .\src\native\managed\cdac\tests\UnitTests\Microsoft.Diagnostics.DataContractReader.Tests.csproj --no-restore -m:1
pwsh .\src\native\managed\cdac\tools\CdacUsageGraph\generate-docs.ps1 -Check
build.cmd -s tools.cdac+tools.cdactests -c Debug -test

Note

Focus review on the generated IData helpers and metadata, the generated contract documentation under docs/design/datacontracts, and the UsageTests CI gate. The implementation under src/native/managed/cdac/tools/** is supporting analyzer/tooling code and can be skipped unless you want to inspect its implementation details.

Note

This pull request description was generated with GitHub Copilot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

azure-pipelines · 2026-07-23T18:15:23Z

Azure Pipelines: Successfully started running 5 pipeline(s). 11 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

Adds a new cDAC “usage graph” analysis tool and wires it into unit tests to generate / validate contract usage documentation, while also enriching the cDAC source-generator output and contracts to make descriptor/type-size dependencies more explicit and mechanically discoverable.

Changes:

Introduces the CdacUsageGraph tool (Roslyn/MSBuild-backed) plus a dedicated test project and a generate-docs.ps1 wrapper to emit/check documentation artifacts.
Extends cDAC metadata/annotations (new attributes + generator output) so descriptor field usage and “uses type size” information can be captured for reporting and doc generation.
Updates many contracts + docs to rely on generated GetSize / offset helpers and to include generated “usage” blocks (with override/suppression sidecars) and new unit-test gates.

Reviewed changes

Copilot reviewed 155 out of 155 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/native/managed/cdac/tools/CdacUsageGraph/tests/CdacUsageGraph.Tests/CdacUsageGraph.Tests.csproj	New test project for the usage-graph tool.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/UsageGraphAnalyzer.cs	Public entry-point wrapper for building a usage graph.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Semantic/SymbolExtensions.cs	Roslyn helpers for symbol traversal and assignability checks.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Semantic/NativeTypeName.cs	Maps Roslyn types to “native type” strings for reporting.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Semantic/CdacSymbolMatcher.cs	Resolves/matches well-known cDAC types/methods in a compilation.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Reporting/MarkdownReportWriters.cs	Markdown writers for contract/data/field/global/contract edges.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Reporting/JsonReportWriter.cs	JSON writer for the full machine-readable usage graph.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Reporting/IReportWriter.cs	Report-writer interface for tool output stages.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Program.cs	Tool program entrypoint wiring `Commands` to args.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/UsageGraph.cs	Immutable usage-graph model types used by writers/docs.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/DataTypeIndex.cs	Index over discovered IData descriptor types for analysis.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/DataDescriptorType.cs	Model for a discovered descriptor type and its names.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/DataDescriptorDependency.cs	Models descriptor field dependencies and type-size dependencies.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/ContractVersion.cs	Model for (contract interface, version) labels.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/ContractRegistration.cs	Model for parsed contract registrations from Contracts compilation.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Model/ContractInterface.cs	Model wrapper for contract interface names + derived contract name.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Locator.cs	Locates cdac root, docs dir, and sidecar files.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Docs/DocDescriptorOverrides.cs	Loads per-contract/version descriptor supplement/suppress sidecars.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Docs/DocDescriptorMeanings.cs	Loads meaning text for descriptors/globals and provides placeholders.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Discovery/DataTypeDiscovery.cs	Discovers IData descriptor classes from the compilation.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Discovery/ContractRegistrationParser.cs	Parses CoreCLRContracts.Register<>() calls into registrations.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Compilation/CdacCompilationLoader.cs	MSBuildWorkspace-based loader for the real Contracts project.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Commands.cs	System.CommandLine surface including `docs --check` support.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/CdacUsageGraph.csproj	New tool project with Roslyn/MSBuild workspace dependencies.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/CdacSymbols.cs	Centralized stable symbol/name anchors for semantic matching.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/AnalysisPipeline.cs	Orchestrates compilation load → discovery → walk → report emission.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/AnalysisOptions.cs	Options model for CLI execution.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Analysis/StringEvaluator.cs	Static string-value evaluator over Roslyn IOperation trees.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Analysis/OperationInspector.cs	Operation shape helpers (e.g., unwrap implicit conversions).
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Analysis/ContractEntryPoints.cs	Discovers contract entry points and returned interface types.
src/native/managed/cdac/tools/CdacUsageGraph/src/CdacUsageGraph/Analysis/ConstructionEntryPoints.cs	Adds constructor + field/property entry points for analysis roots.
src/native/managed/cdac/tools/CdacUsageGraph/generate-docs.ps1	Wrapper script to run `CdacUsageGraph docs` / `--check`.
src/native/managed/cdac/tools/CdacUsageGraph/CdacUsageGraph.slnx	Solution definition for tool + tests.
src/native/managed/cdac/tools/CdacUsageGraph/.gitignore	Ignores tool output/build artifacts.
src/native/managed/cdac/tests/UnitTests/UsageGraph/UsageGraphFixture.cs	Shared fixture to build a usage graph for unit tests.
src/native/managed/cdac/tests/UnitTests/UsageGraph/ContractUsageGraphTests.cs	New tests asserting contract dependency cycles are allowlisted.
src/native/managed/cdac/tests/UnitTests/UsageGraph/ContractDocumentationTests.cs	New doc drift / missing marker / placeholder-meaning test gates.
src/native/managed/cdac/tests/UnitTests/Microsoft.Diagnostics.DataContractReader.Tests.csproj	References the tool for tests and adds an extra Roslyn package ref.
src/native/managed/cdac/tests/DataGenerator/TestTypes.cs	Adds test IData types for new generator/descriptor scenarios.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/RuntimeTypeSystemHelpers/MethodValidation.cs	Switches to generated size helper for MethodDescChunk math.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/RuntimeTypeSystemHelpers/MethodDescOptionalSlots.cs	Replaces TypeInfo size reads with generated GetSize helpers.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/UnwindInfo.cs	Adds explicit DataDescriptorDependency annotation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/TypeDesc.cs	Shares base-field read via cached TypeDesc processed data.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/TLSIndex.cs	Minor formatting/spacing adjustment.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/Thread.cs	Adds explicit DataDescriptorDependency annotations.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/TableSegment.cs	Adds explicit DataDescriptorDependency annotations for byte[] fields.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/SyncTableEntry.cs	Adds explicit DataDescriptorDependency annotations.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/SyncBlock.cs	Adds explicit DataDescriptorDependency annotations.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/StressMsg.cs	Adds StressMsgHeader descriptor type.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/StackTraceElement.cs	Converts to generator-backed partial IData with [Field] attributes.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/StackTraceArrayHeader.cs	Converts to generator-backed partial IData with [Field] attributes.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ReadyToRunInfo.cs	Adds explicit DataDescriptorDependency annotations for fields.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ReadyToRunCoreHeader.cs	Uses generated GetSize helpers for section walking.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/RCW.cs	Uses generated size helper; annotates InterfaceEntries dependency.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/RangeSectionFragment.cs	Adds explicit DataDescriptorDependency annotation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/PrecodeMachineDescriptor.cs	Adds extensive DataDescriptorDependency annotations for fields/arrays.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/MethodDesc.cs	Adds several descriptor type shells used for size/offset helpers.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/InterpreterRealCodeHeader.cs	Adds explicit DataDescriptorDependency annotation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/InstMethodHashTable.cs	Adds explicit DataDescriptorDependency annotations for hash layout.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/HandleTableMap.cs	Adds explicit DataDescriptorDependency annotation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/GCCoverageInfo.cs	Adds new descriptor type and field address accessor.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ExceptionClause.cs	Minor formatting/spacing adjustment.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/EETypeHashTable.cs	Adds explicit DataDescriptorDependency annotations for hash layout.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/DynamicStaticsInfo.cs	Adds explicit DataDescriptorDependency annotations.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ComWrappersVtablePtrs.cs	Uses generated size helper for pointer array sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ComInterfaceEntry.cs	Adds explicit DataDescriptorDependency annotation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/Bucket.cs	Adds explicit DataDescriptorDependency annotations.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Data/ArrayListBase.cs	Minor formatting/spacing adjustment.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Thread_1.cs	Uses generated offsets instead of cached TypeInfo.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/SyncBlock_1.cs	Uses generated GetSize helper for SyncTableEntry stride.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StressLog.cs	Uses generated GetSize helpers and correct global read patterns.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/StackWalk_1.cs	Uses generated GetSize helper for InlinedCallFrame math.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/GC/GcScanContext.cs	Switches to generated offset helpers for key object/array/string fields.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/X86FrameHandler.cs	Uses generated GetSize helpers for frame sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/RISCV64FrameHandler.cs	Uses generated GetSize helpers for HijackArgs sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/LoongArch64FrameHandler.cs	Uses generated GetSize helpers for HijackArgs sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/BaseFrameHandler.cs	Uses generated GetSize helper for TransitionBlock sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/ARMFrameHandler.cs	Uses generated GetSize helpers for HijackArgs sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/ARM64FrameHandler.cs	Uses generated GetSize helpers for HijackArgs sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/StackWalk/FrameHandling/AMD64FrameHandler.cs	Uses generated GetSize helpers for HijackArgs sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/PrecodeStubs_Common.cs	Refactors interpreter-precode behavior to a virtual override point.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/PrecodeStubs_3.cs	Implements interpreter-precode translation for contract version 3.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Object_1.cs	Uses generated offsets/sizes instead of TypeInfo reads.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ManagedTypeSource_1.cs	Uses generated Object.GetSize for layout math.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Loader_1.cs	Uses generated offsets; annotates dynamic hash table dependencies.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/GC/GC_1.cs	Uses generated sizes/offsets for multiple GC data structures.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/Helpers/RuntimeFunctionLookup.cs	Uses generated GetSize helper.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/Helpers/HashMapLookup.cs	Uses generated GetSize helper for buckets.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/ExecutionManagerCore.ReadyToRunJitManager.cs	Uses generated GetSize helper for exception table entries.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/ExecutionManagerCore.InterpreterJitManager.cs	Uses generated GetSize helper for EEExceptionClause.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/ExecutionManagerCore.EEJitManager.cs	Uses generated GetSize helper for EEExceptionClause.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ExecutionManager/ExecutionManagerCore.cs	Uses generated GetSize helper for clause-size selection.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Exception_1.cs	Uses generated sizes/offset helpers for stack trace decoding.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/DebugInfo/DebugInfo_1.cs	Uses generated GetSize helper for PatchpointInfo.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/Debugger/Debugger_1.cs	Uses generated GetSize helper for MemoryRange stride.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/ComWrappers_1.cs	Uses generated GetSize helpers for dispatch and entry strides.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/CodeVersions_1.cs	Uses generated offset helper for GCCoverageInfo.SavedCode.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/CodeNotifications_1.cs	Uses generated GetSize helper for JITNotification table entry sizing.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/BuiltInCOM_1.cs	Uses generated offsets/sizes for COM wrapper navigation.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/AuxiliarySymbols_1.cs	Uses generated GetSize helper for AuxiliarySymbolInfo stride.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/CdacAttributes.cs	Adds new public attributes to express descriptor/type-size dependencies.
src/native/managed/cdac/gen/Parser.cs	Captures descriptor native type information during generator parsing.
src/native/managed/cdac/gen/Model.cs	Extends generator model with descriptor-native-type metadata.
src/native/managed/cdac/gen/Emitter.cs	Emits GetSize/offset helpers + dependency attributes in generated code.
eng/Subsets.props	Adds CdacUsageGraph tests to `tools.cdactests` subset with source-only skip.
docs/design/datacontracts/WindowsErrorReporting.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/SyncBlock.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/Signature.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/SHash.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/RuntimeInfo.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/ReJIT.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/PlatformMetadata.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/ObjectiveCMarshal.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/Notifications.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/ManagedTypeSource.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/GCInfo.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/FeatureFlags.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/Exception.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/EcmaMetadata.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/DebugInfo.md	Inserts/updates generated usage sections (incl. diff-from) for docs.
docs/design/datacontracts/Debugger.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/data-descriptor-overrides.json	Adds version-aware suppressions for generated usage reporting.
docs/design/datacontracts/DacStreams.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/ConditionalWeakTable.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/ComWrappers.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/CodeVersions.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/CodeNotifications.md	Inserts/updates generated usage section for contract documentation.
docs/design/datacontracts/CallingConvention.md	Inserts generated usage section for contract documentation.
docs/design/datacontracts/AuxiliarySymbols.md	Inserts/updates generated usage section for contract documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Copilot

Pull request overview

Copilot reviewed 151 out of 151 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/CdacAttributes.cs:47

These new public attribute types are part of the packable cDAC Abstractions package (see project comment about downstream consumers). New public API surface in dotnet/runtime requires an approved API proposal / linked api-approved issue; the PR description currently doesn’t reference one. Please either link the approved API issue/proposal or adjust the visibility (if these APIs are intended to stay internal).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Copilot

Pull request overview

Copilot reviewed 151 out of 151 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/CdacAttributes.cs:82

This change introduces new public API surface (DataDescriptorDependencyAttribute and UsesDataDescriptorTypeSizeAttribute) in a packable/shipping assembly. Per repo policy, new public APIs require an approved API proposal/issue (api-approved) or should be kept internal until approval is in place.

azure-pipelines · 2026-07-23T21:01:44Z

Azure Pipelines: Successfully started running 5 pipeline(s). 11 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

dotnet-policy-service · 2026-07-23T21:25:27Z

Tagging subscribers to this area: @steveisok, @tommcdon, @dotnet/dotnet-diag
See info in area-owners.md if you want to be subscribed.

max-charlamb · 2026-07-24T02:06:40Z

/ba-g osx timeout

## Summary Adds a Roslyn-based cDAC usage graph analyzer, generated contract usage documentation, and repository gates that keep the documentation synchronized with contract implementations. ### Generated `IData` metadata The `IData` source generator now emits dependency metadata for generated members, allowing the analyzer to identify descriptor reads without relying on implementation details: - `GetSize(Target)` helpers are generated for descriptor types and marked with `[UsesDataDescriptorTypeSize]`. - Generated `Get<X>Offset(Target)` helpers are annotated with `[DataDescriptorDependency]` when they resolve a descriptor field dynamically. - Generated lazy `[Field]`, `[FieldAddress]`, write, and static-reference helpers carry `[DataDescriptorDependency]`; instance-data-start helpers carry `[UsesDataDescriptorTypeSize]`. ### Generated documentation and validation The analyzer tracks cDAC contract, descriptor, global, callback, and contract-dependency usage. It generates marked usage sections in contract docs, supports version deltas and narrowly scoped documentation overrides, and adds gates that verify generated sections are current, every contract version is documented, and no placeholder meanings remain. When a contract change makes a generated usage section stale, the test reports the affected document and repair command, for example: ```text Generated cDAC usage documentation is stale: StressLog.md. To update it, run from the repository root: pwsh .\src\native\managed\cdac\tools\CdacUsageGraph\generate-docs.ps1 Review and commit the generated changes. If the generated dependencies are incorrect, fix the usage-graph analysis or add a narrowly scoped entry to docs\design\datacontracts\data-descriptor-overrides.json. ``` ## Testing - `dotnet test .\src\native\managed\cdac\tests\UsageTests\Microsoft.Diagnostics.DataContractReader.Usage.Tests.csproj --no-restore -m:1` - `dotnet build .\src\native\managed\cdac\tests\UnitTests\Microsoft.Diagnostics.DataContractReader.Tests.csproj --no-restore -m:1` - `pwsh .\src\native\managed\cdac\tools\CdacUsageGraph\generate-docs.ps1 -Check` - `build.cmd -s tools.cdac+tools.cdactests -c Debug -test` > [!NOTE] >Focus review on the generated `IData` helpers and metadata, the generated contract documentation under `docs/design/datacontracts`, and the `UsageTests` CI gate. The implementation under `src/native/managed/cdac/tools/**` is supporting analyzer/tooling code and can be skipped unless you want to inspect its implementation details. > [!NOTE] > This pull request description was generated with GitHub Copilot. --------- Co-authored-by: Max Charlamb <maxcharlamb@microsoft.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Max Charlamb added 3 commits July 23, 2026 14:09

Add cDAC usage graph analyzer

78e5066

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Generate cDAC usage documentation

d68b12c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Test cDAC usage documentation

326061e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Copilot AI review requested due to automatic review settings July 23, 2026 18:14

github-actions Bot added the area-Diagnostics-coreclr label Jul 23, 2026

Copilot started reviewing on behalf of max-charlamb July 23, 2026 18:14 View session

dotnet-policy-service Bot assigned max-charlamb Jul 23, 2026

Copilot AI reviewed Jul 23, 2026

View reviewed changes

max-charlamb commented Jul 23, 2026

View reviewed changes

Refine cDAC usage graph tests

152c366

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Copilot AI review requested due to automatic review settings July 23, 2026 18:55

Copilot started reviewing on behalf of max-charlamb July 23, 2026 18:55 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Complete cDAC usage documentation coverage

03ef77c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d52ae8e-3385-4241-9a57-9e864fc4d1ef

Copilot AI review requested due to automatic review settings July 23, 2026 19:43

Copilot started reviewing on behalf of max-charlamb July 23, 2026 19:43 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread .../managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/PrecodeStubs_3.cs

noahfalk approved these changes Jul 23, 2026

View reviewed changes

max-charlamb marked this pull request as ready for review July 23, 2026 21:00

max-charlamb requested a review from rcj1 July 23, 2026 21:02

max-charlamb added area-Diagnostics-cdac and removed area-Diagnostics-coreclr labels Jul 23, 2026

max-charlamb enabled auto-merge (squash) July 23, 2026 21:35

This was referenced Jul 24, 2026

slow macOS - "##[error]The job running on agent Azure Pipelines 9 ran longer than the maximum time of 60 minutes." dotnet/dnceng#1883

Open

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

max-charlamb merged commit 1220ced into dotnet:main Jul 24, 2026
184 of 195 checks passed

max-charlamb deleted the cdac-usage-graph-simple branch July 24, 2026 02:07

dotnet-maestro Bot mentioned this pull request Jul 25, 2026

[main] Source code updates from dotnet/runtime dotnet/dotnet#7965

Merged

dotnet-milestone-bot Bot added this to the 11.0-rc1 milestone Jul 26, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add cDAC usage graph analyzer and documentation gates - #131281

Add cDAC usage graph analyzer and documentation gates#131281
max-charlamb merged 5 commits into
dotnet:mainfrom
max-charlamb:cdac-usage-graph-simple

max-charlamb commented Jul 23, 2026 •

edited

Loading

Uh oh!

azure-pipelines Bot commented Jul 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

azure-pipelines Bot commented Jul 23, 2026

Uh oh!

dotnet-policy-service Bot commented Jul 23, 2026

Uh oh!

max-charlamb commented Jul 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

max-charlamb commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Generated IData metadata

Generated documentation and validation

Testing

Uh oh!

azure-pipelines Bot commented Jul 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

azure-pipelines Bot commented Jul 23, 2026

Uh oh!

dotnet-policy-service Bot commented Jul 23, 2026

Uh oh!

max-charlamb commented Jul 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

max-charlamb commented Jul 23, 2026 •

edited

Loading

Generated `IData` metadata