Skip to content

Commit 793ad8f

Browse files
tonyredondotonyredondo
committed
chore(ducktyping): checkpoint NativeAOT implementation progress
1 parent 8b4147e commit 793ad8f

File tree

81 files changed

+11169
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

81 files changed

+11169
-0
lines changed

‎docs/development/DuckTyping.Bible.md‎

Lines changed: 2696 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/development/for-ai/DuckTyping-NativeAOT-Plan.md‎

Lines changed: 275 additions & 0 deletions
Large diffs are not rendered by default.

‎findings.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Findings & Decisions
2+
3+
## Requirements
4+
- Analyze DuckTyping deeply in code and docs.
5+
- Treat docs as potentially outdated but still important.
6+
- Prepare a high-confidence technical baseline for a follow-up implementation discussion.
7+
- Deliver a very large, very detailed markdown "bible" documenting DuckTyping internals and all supported features with examples.
8+
9+
## Research Findings
10+
- `docs/development/DuckTyping.md` is the only dedicated DuckTyping document under `docs/`.
11+
- Core implementation lives in `tracer/src/Datadog.Trace/DuckTyping/` and is split by concern (`Methods`, `Properties`, `Fields`, `Statics`, `Utilities`).
12+
- There is a large dedicated test project: `tracer/test/Datadog.Trace.DuckTyping.Tests/`.
13+
- Duck typing is heavily used across integrations (e.g., testing, MongoDB, logging, gRPC, Activity/OTEL compatibility layers).
14+
- Core runtime flow is: API entry (`DuckType` / `DuckTypeExtensions`) -> cache lookup (`DuckTypeCache`, `CreateCache<T>`) -> dry-run validation -> dynamic type emit -> activator delegate invoke.
15+
- Reverse duck typing uses `CreateReverse`/`DuckImplement` with `[DuckReverseMethod]` and enforces strict constraints (cannot derive from struct; implementor cannot be interface/abstract).
16+
- Visibility/access strategy uses dynamic assemblies + `IgnoresAccessChecksToAttribute` via `EnsureTypeVisibility`, not only direct `DynamicMethod` tricks.
17+
- Dedicated tests encode many behavioral guarantees and also known gaps (some skipped mismatch-detection tests).
18+
- Usage across `tracer/src/Datadog.Trace` appears in roughly 500 files, concentrated in `ClrProfiler/AutoInstrumentation`, `DiagnosticListeners`, `Activity`, `AppSec`, `Iast`.
19+
- Common production conventions: prefer `TryDuckCast` for version variance, use `[DuckField(Name=\"_...\")]` for private fields, use comma-separated name fallback aliases, and use string type names for runtime-only dependency signatures.
20+
- Docs drift highlights:
21+
- reverse docs reference `[DuckImplement]` attribute but code uses `[DuckReverseMethod]`;
22+
- docs omit `DuckPropertyOrField` and explicit-interface mapping support;
23+
- docs mention `HasValue`/`IsNull` APIs that are not implemented;
24+
- docs miss behavior around `DuckInclude`/`DuckIgnore`, reverse custom-attribute copy rules, and known detection gaps.
25+
- Additional implementation detail captured for final doc authoring:
26+
- `CreateTypeResult` stores either activator delegate or captured exception and rethrows lazily.
27+
- Dynamic module strategy has 3 branches: visible shared-by-assembly, non-visible dedicated module, and generic cross-assembly dedicated module.
28+
- `EnsureTypeVisibility` recursively processes nested/generic types and applies `IgnoresAccessChecksToAttribute` per module/assembly.
29+
- Method resolution supports explicit interface binding and wildcard explicit interface matching (`ExplicitInterfaceTypeName = "*"`) plus fallback parameter matching heuristics.
30+
- Conversion logic is centralized in `WriteTypeConversion` / `CheckTypeConversion` with strict value-type handling and runtime-cast paths for object/interface boundaries.
31+
- Deliverable produced:
32+
- `docs/development/DuckTyping.Bible.md` created as exhaustive reference (feature catalog, internals, caches, visibility, helpers, exceptions, analyzer guidance, and test-inspired examples).
33+
- Follow-up expansion completed:
34+
- Added `Feature-by-feature test-adapted excerpts` section with concrete snippets mapped to feature IDs and linked to representative test files.
35+
- Additional follow-up expansion completed:
36+
- Added a large `IL emission atlas (opcode-level)` section including forward/reverse IL paths, static/instance behavior, public/internal/private combination tables, chaining/ref-out patterns, and dynamic-method fallback mechanics.
37+
- Additional IL companion expansion completed:
38+
- Added `IL companion for Detailed examples (1-20)` section that pairs each C# detailed sample with a representative emitted IL form and branch notes.
39+
40+
## Technical Decisions
41+
| Decision | Rationale |
42+
|----------|-----------|
43+
| Analyze internals first, then usages | Prevents misinterpretation of usage patterns |
44+
| Use dedicated tests as behavior oracle | Tests often encode edge-case and compatibility intent better than docs |
45+
| Explicitly reconcile doc-vs-code differences | User already flagged docs as outdated |
46+
47+
## Issues Encountered
48+
| Issue | Resolution |
49+
|-------|------------|
50+
| Broad grep produced very large output | Switched to targeted file-level reads and scoped searches |
51+
52+
## Resources
53+
- `docs/development/DuckTyping.md`
54+
- `tracer/src/Datadog.Trace/DuckTyping/`
55+
- `tracer/test/Datadog.Trace.DuckTyping.Tests/`
56+
- `tracer/src/Datadog.Trace.Tools.Analyzers/DuckTypeAnalyzer/`
57+
- `tracer/src/Datadog.Trace/ClrProfiler/CallTarget/Handlers/IntegrationMapper.cs`
58+
- `tracer/src/Datadog.Trace/DiagnosticListeners/AspNetCoreDiagnosticObserver.cs`
59+
- `tracer/src/Datadog.Trace/Activity/ActivityListenerDelegatesBuilder.cs`
60+
61+
## Visual/Browser Findings
62+
- No visual/browser sources used yet.
63+
64+
---
65+
*Update this file after every 2 view/browser/search operations*

‎progress.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Progress Log
2+
3+
## Session: 2026-02-26
4+
5+
### Phase 1: Scope & Inventory
6+
- **Status:** complete
7+
- **Started:** 2026-02-26
8+
- Actions taken:
9+
- Enumerated DuckTyping-related source files and docs.
10+
- Loaded planning skill instructions and initialized tracking files.
11+
- Captured initial findings and approach.
12+
- Files created/modified:
13+
- `task_plan.md` (created)
14+
- `findings.md` (created)
15+
- `progress.md` (created)
16+
17+
### Phase 2: Core Engine Analysis
18+
- **Status:** complete
19+
- Actions taken:
20+
- Reviewed main `DuckType.cs` orchestration and creation paths.
21+
- Collected full architecture/runtime-flow details from focused explorer analysis of `tracer/src/Datadog.Trace/DuckTyping/*`.
22+
- Files created/modified:
23+
- `task_plan.md` (updated)
24+
- `findings.md` (updated)
25+
- `progress.md` (updated)
26+
27+
### Phase 3: Usage & Tests Analysis
28+
- **Status:** complete
29+
- Actions taken:
30+
- Collected a dedicated behavior map from `tracer/test/Datadog.Trace.DuckTyping.Tests`, including supported/unsupported patterns and regression constraints.
31+
- Collected repository usage patterns and conventions across integrations and diagnostic layers.
32+
- Files created/modified:
33+
- `task_plan.md` (updated)
34+
- `findings.md` (updated)
35+
- `progress.md` (updated)
36+
37+
### Phase 4: Documentation Reconciliation
38+
- **Status:** complete
39+
- Actions taken:
40+
- Reconciled `docs/development/DuckTyping.md` against current implementation and tests.
41+
- Identified accurate sections, stale/outdated sections, and critical undocumented behaviors.
42+
- Files created/modified:
43+
- `task_plan.md` (updated)
44+
- `findings.md` (updated)
45+
- `progress.md` (updated)
46+
47+
### Phase 5: Delivery
48+
- **Status:** complete
49+
- Actions taken:
50+
- Consolidated findings into a structured brief for user discussion.
51+
- Files created/modified:
52+
- `task_plan.md` (updated)
53+
- `findings.md` (updated)
54+
- `progress.md` (updated)
55+
56+
### Phase 6: Author Bible Documentation
57+
- **Status:** complete
58+
- Actions taken:
59+
- Gathered additional low-level implementation details from `DuckType.Statics.cs`, `DuckType.Utilities.cs`, `DuckType.Methods.cs`, `DuckType.Properties.cs`, `DuckType.Fields.cs`, `ILHelpersExtensions.cs`, attribute/contract files, and analyzer files.
60+
- Authored new comprehensive doc: `docs/development/DuckTyping.Bible.md`.
61+
- Expanded with feature catalog, internals, cache/visibility/model details, examples, and test evidence index.
62+
- Performed quick consistency checks and TOC alignment.
63+
- Files created/modified:
64+
- `docs/development/DuckTyping.Bible.md` (created)
65+
- `task_plan.md` (updated)
66+
- `findings.md` (updated)
67+
- `progress.md` (updated)
68+
69+
### Phase 7: Deliver And Review
70+
- **Status:** complete
71+
- Actions taken:
72+
- Shared the first draft with user.
73+
- Implemented requested second pass adding feature-by-feature test-adapted excerpts.
74+
- Updated table of contents and added a large excerpt catalog section tied to concrete test files.
75+
- Implemented additional requested IL-depth expansion with opcode-level atlas and exhaustive combination matrices.
76+
- Implemented additional requested IL companion blocks for all 20 C# detailed samples, including representative emitted IL paths.
77+
- Files created/modified:
78+
- `docs/development/DuckTyping.Bible.md` (updated)
79+
- `task_plan.md` (updated)
80+
- `findings.md` (updated)
81+
- `progress.md` (updated)
82+
83+
## Test Results
84+
| Test | Input | Expected | Actual | Status |
85+
|------|-------|----------|--------|--------|
86+
| N/A | N/A | N/A | N/A | N/A |
87+
88+
## Error Log
89+
| Timestamp | Error | Attempt | Resolution |
90+
|-----------|-------|---------|------------|
91+
| 2026-02-26 | `ls task_plan.md findings.md progress.md` exited with code 2 | 1 | Created planning files |
92+
93+
## 5-Question Reboot Check
94+
| Question | Answer |
95+
|----------|--------|
96+
| Where am I? | Completed requested second-pass documentation expansion |
97+
| Where am I going? | Await user review and any further expansions |
98+
| What's the goal? | Build analysis and deliver exhaustive DuckTyping documentation |
99+
| What have I learned? | Full architecture, behaviors, internals, doc drift, test evidence, and feature-level snippets are mapped |
100+
| What have I done? | Produced and expanded a full 1,600+ line DuckTyping bible with test-adapted excerpt catalog |
101+
102+
---
103+
*Update after completing each phase or encountering errors*

‎task_plan.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Task Plan: DuckTyping Deep Analysis And Bible Documentation
2+
3+
## Goal
4+
Build a comprehensive, code-backed analysis of DuckTyping in `Datadog.Trace`, then produce a very detailed markdown "DuckTyping Bible" documenting every supported feature, internals, cache/codegen behavior, and test-inspired examples.
5+
6+
## Current Phase
7+
Phase 7
8+
9+
## Phases
10+
11+
### Phase 1: Scope & Inventory
12+
- [x] Understand user intent
13+
- [x] Identify relevant code and docs
14+
- [x] Initialize tracking files
15+
- **Status:** complete
16+
17+
### Phase 2: Core Engine Analysis
18+
- [x] Analyze `Datadog.Trace/DuckTyping` internals end-to-end
19+
- [x] Map key APIs, caches, and dynamic codegen flow
20+
- [x] Document behavioral constraints and edge cases
21+
- **Status:** complete
22+
23+
### Phase 3: Usage & Tests Analysis
24+
- [x] Analyze how integrations consume duck typing
25+
- [x] Review dedicated duck-typing tests for guarantees and failure modes
26+
- [x] Summarize analyzers/tooling around duck typing usage
27+
- **Status:** complete
28+
29+
### Phase 4: Documentation Reconciliation
30+
- [x] Deep-read `docs/development/DuckTyping.md`
31+
- [x] Compare docs to current implementation and tests
32+
- [x] List accurate parts, outdated parts, and missing guidance
33+
- **Status:** complete
34+
35+
### Phase 5: Deliver Analysis
36+
- [x] Produce a structured summary for discussion
37+
- [x] Include concrete file references and key questions
38+
- [x] Note follow-up areas for implementation planning
39+
- **Status:** complete
40+
41+
### Phase 6: Author Bible Documentation
42+
- [x] Define full documentation structure and coverage checklist
43+
- [x] Write detailed markdown with feature-by-feature explanations and examples
44+
- [x] Validate references and consistency with implementation/tests
45+
- **Status:** complete
46+
47+
### Phase 7: Deliver And Review
48+
- [x] Share document path and summary with user
49+
- [x] Capture any requested expansions or corrections
50+
- **Status:** complete
51+
52+
## Key Questions
53+
1. What exactly happens at runtime from `DuckCast`/`Create` to usable proxy instances?
54+
2. Which duck-typing patterns are canonical in this repo (interface, struct copy, reverse proxy, etc.)?
55+
3. What are the highest-risk constraints/failure modes contributors need to know?
56+
4. Where does documentation diverge from current code behavior?
57+
5. What structure and depth best satisfy a "DuckTyping bible" reference document?
58+
59+
## Decisions Made
60+
| Decision | Rationale |
61+
|----------|-----------|
62+
| Track analysis in planning files | Task is broad and will exceed normal context window |
63+
| Prioritize core engine and tests before broad usage grep | Gives a reliable behavioral model before surveying consumers |
64+
| Use parallel explorer agents for independent slices (core/tests/docs/usage) | Speeds up research while keeping results scoped and reference-backed |
65+
| Create a new file `docs/development/DuckTyping.Bible.md` | Preserves current doc while delivering exhaustive reference |
66+
67+
## Errors Encountered
68+
| Error | Attempt | Resolution |
69+
|-------|---------|------------|
70+
| `ls task_plan.md findings.md progress.md` exited with code 2 | 1 | Confirmed files did not exist; created fresh planning files |
71+
72+
## Notes
73+
- Keep focus on `tracer/src/Datadog.Trace/DuckTyping`, `tracer/test/Datadog.Trace.DuckTyping.Tests`, and `docs/development/DuckTyping.md`.
74+
- Expand to other folders only to explain real usage patterns and conventions.
75+
- Static analysis only in this pass; no test execution was run yet.

‎tracer/src/Datadog.Trace.Tools.Runner/DuckTypeAot/DuckTypeAotArtifactPaths.cs‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// <copyright file="DuckTypeAotArtifactPaths.cs" company="Datadog">
2+
// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
3+
// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
4+
// </copyright>
5+
6+
#nullable enable
7+
8+
using System.IO;
9+
10+
namespace Datadog.Trace.Tools.Runner.DuckTypeAot
11+
{
12+
internal sealed class DuckTypeAotArtifactPaths
13+
{
14+
public DuckTypeAotArtifactPaths(
15+
string outputAssemblyPath,
16+
string manifestPath,
17+
string compatibilityMatrixPath,
18+
string compatibilityReportPath,
19+
string trimmerDescriptorPath,
20+
string propsPath)
21+
{
22+
OutputAssemblyPath = outputAssemblyPath;
23+
ManifestPath = manifestPath;
24+
CompatibilityMatrixPath = compatibilityMatrixPath;
25+
CompatibilityReportPath = compatibilityReportPath;
26+
TrimmerDescriptorPath = trimmerDescriptorPath;
27+
PropsPath = propsPath;
28+
}
29+
30+
public string OutputAssemblyPath { get; }
31+
32+
public string ManifestPath { get; }
33+
34+
public string CompatibilityMatrixPath { get; }
35+
36+
public string CompatibilityReportPath { get; }
37+
38+
public string TrimmerDescriptorPath { get; }
39+
40+
public string PropsPath { get; }
41+
42+
public static DuckTypeAotArtifactPaths Create(DuckTypeAotGenerateOptions options)
43+
{
44+
var outputAssemblyPath = Path.GetFullPath(options.OutputPath);
45+
var manifestPath = outputAssemblyPath + ".manifest.json";
46+
var compatibilityMatrixPath = outputAssemblyPath + ".compat.json";
47+
var compatibilityReportPath = outputAssemblyPath + ".compat.md";
48+
var trimmerDescriptorPath = Path.GetFullPath(options.TrimmerDescriptorPath);
49+
var propsPath = Path.GetFullPath(options.PropsPath);
50+
51+
return new DuckTypeAotArtifactPaths(
52+
outputAssemblyPath,
53+
manifestPath,
54+
compatibilityMatrixPath,
55+
compatibilityReportPath,
56+
trimmerDescriptorPath,
57+
propsPath);
58+
}
59+
}
60+
}

0 commit comments

Comments
 (0)