init

enriched-qwen3-coder-next/Common/DTS.Common.CPU/Properties.md

@@ -0,0 +1,115 @@
+---
+source_files:
+  - Common/DTS.Common.CPU/Properties/AssemblyInfo.cs
+  - Common/DTS.Common.CPU/Properties/Annotations.cs
+generated_at: "2026-04-16T03:29:08.777780+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "2ecad58ebc9f0db4"
+---
+
+# Properties
+
+## Documentation: `DTS.Common.CPU.Annotations` Namespace
+
+### 1. Purpose  
+This module provides a comprehensive set of JetBrains-style code annotation attributes for use in static analysis (e.g., by ReSharper or Rider) to improve nullability, contract, and usage intent expressiveness in C# code. It does not contain executable logic or business functionality; rather, it serves as a *metadata layer* to guide compiler/tooling behavior and human understanding of API contracts. The attributes are applied via attributes on types, methods, parameters, and properties to convey semantic constraints (e.g., nullability, immutability, usage patterns) that static analyzers interpret to generate warnings or suggestions.
+
+### 2. Public Interface  
+All types reside in the `DTS.Common.CPU.Annotations` namespace. All attributes are `sealed` and inherit from `Attribute`. Below are the key public types:
+
+#### Core Nullability Annotations  
+- **`CanBeNullAttribute`**  
+  Indicates the marked element *may* be `null`. Applies to methods, parameters, properties, fields, events, delegates, classes, interfaces, and generic parameters.  
+- **`NotNullAttribute`**  
+  Indicates the marked element *must never* be `null`. Applies to the same targets as `CanBeNullAttribute`.  
+- **`ItemCanBeNullAttribute`**  
+  For `IEnumerable<T>`, `Task<T>`, or `Lazy<T>`: indicates the *item/result/value* may be `null`.  
+- **`ItemNotNullAttribute`**  
+  For `IEnumerable<T>`, `Task<T>`, or `Lazy<T>`: indicates the *item/result/value* is guaranteed non-null.  
+- **`ImplicitNotNullAttribute`**  
+  Applies to types or assemblies: implicitly enforces `[NotNull]`/`[ItemNotNull]` on all members within scope.
+
+#### Contract & Behavior Annotations  
+- **`StringFormatMethodAttribute(string formatParameterName)`**  
+  Marks a method as building a string from a format string (like `string.Format`). `formatParameterName` specifies which parameter holds the format string.  
+- **`ValueProviderAttribute(string name)`**  
+  Indicates a parameter/property/field must be one of a limited set of values, defined by fields of the type specified by `name`.  
+- **`InvokerParameterNameAttribute`**  
+  For parameters expected to be string literals matching a caller’s parameter name (e.g., `ArgumentNullException` parameter).  
+- **`NotifyPropertyChangedInvocatorAttribute(string parameterName = null)`**  
+  Marks methods used to notify property changes (e.g., `INotifyPropertyChanged`). Supports `NotifyChanged(string)`, `NotifyChanged(params string[])`, expression-based overloads, and `SetProperty` patterns.  
+- **`ContractAnnotationAttribute(string contract, bool forceFullStates = false)`**  
+  Declares input-output dependencies (e.g., `"s:null => true"`, `"null => null; notnull => notnull"`). Supports multiple instances per method.  
+- **`MustUseReturnValueAttribute(string justification = null)`**  
+  Indicates the return value of a method *must* be used.  
+- **`PureAttribute`**  
+  Indicates the method has no observable side effects (like `System.Diagnostics.Contracts.PureAttribute`).  
+- **`InstantHandleAttribute`**  
+  For delegate/`IEnumerable` parameters: indicates the parameter is used *immediately* within the method (e.g., executed or enumerated synchronously).  
+- **`ProvidesContextAttribute`**  
+  Marks a member as the canonical source for a context value (e.g., a service instance).  
+- **`CollectionAccessAttribute(CollectionAccessType type)`**  
+  Describes how a method/constructor/property affects a collection’s content. `CollectionAccessType` values:  
+  - `None` (0)  
+  - `Read` (1)  
+  - `ModifyExistingContent` (2)  
+  - `UpdatedContent` (7 = `ModifyExistingContent | 4`)  
+- **`AssertionMethodAttribute`** + **`AssertionConditionAttribute(AssertionConditionType)`**  
+  Marks assertion methods (e.g., `Guard.NotNull`). `AssertionConditionType` values: `IS_TRUE`, `IS_FALSE`, `IS_NULL`, `IS_NOT_NULL`.  
+- **`LinqTunnelAttribute`**  
+  Marks pure LINQ methods to enable `InstantHandle` inference for delegate parameters in chains.  
+- **`NoEnumerationAttribute`**  
+  Indicates an `IEnumerable` parameter is *not* enumerated.  
+- **`LocalizationRequiredAttribute(bool required = true)`**  
+  Marks elements requiring localization.  
+- **`CannotApplyEqualityOperatorAttribute`**  
+  Indicates `==`/`!=` operators are invalid for the type (except `null` comparisons).  
+- **`UsedImplicitlyAttribute(ImplicitUseKindFlags, ImplicitUseTargetFlags)`** + **`MeansImplicitUseAttribute(...)`**  
+  Marks symbols used implicitly (e.g., via reflection) to suppress unused warnings. `ImplicitUseKindFlags`: `Access`, `Assign`, `InstantiatedWithFixedConstructorSignature`, `InstantiatedNoFixedConstructorSignature`. `ImplicitUseTargetFlags`: `Itself`, `Members`, `WithMembers`.  
+- **`PublicAPIAttribute(string comment = null)`**  
+  Marks publicly exposed API that must not be removed. Internally uses `[MeansImplicitUse(ImplicitUseTargetFlags.WithMembers)]`.  
+- **`SourceTemplateAttribute`** + **`MacroAttribute`**  
+  Marks extension methods as source templates for IDE expansion (e.g., `forEach` snippets).  
+- **`PathReferenceAttribute(string basePath = null)`**  
+  Indicates a parameter is a file/folder path in a web project.  
+
+#### ASP.NET MVC & Razor-Specific Annotations  
+- **`AspMvc*Attribute`** (e.g., `AspMvcActionAttribute`, `AspMvcAreaAttribute`, `AspMvcControllerAttribute`, `AspMvcViewAttribute`, `AspMvcSuppressViewErrorAttribute`, etc.)  
+  Marks parameters/methods for MVC/Razor view resolution (e.g., action names, areas, controllers, views). Many have optional `anonymousProperty` constructor.  
+- **`AspChildControlTypeAttribute(string tagName, Type controlType)`**  
+  Specifies child control types for ASP.NET server controls.  
+- **`AspDataFieldAttribute`**, **`AspDataFieldsAttribute`**, **`AspMethodPropertyAttribute`**, **`AspRequiredAttributeAttribute(string attribute)`**, **`AspTypePropertyAttribute(bool createConstructorReferences)`**  
+  ASP.NET-specific metadata for data binding and property resolution.  
+- **`Razor*Attribute`** (e.g., `RazorSectionAttribute`, `RazorImportNamespaceAttribute`, `RazorInjectionAttribute`, `RazorDirectiveAttribute`, `RazorWriteLiteralMethodAttribute`, `RazorWriteMethodAttribute`, `RazorHelperCommonAttribute`, `RazorLayoutAttribute`)  
+  Razor view engine metadata for section resolution, imports, and helper methods.  
+- **`XamlItemsControlAttribute`** + **`XamlItemBindingOfItemsControlAttribute`**  
+  XAML binding context resolution for `ItemsControl`-derived types.  
+
+#### Utility  
+- **`NoReorder`**  
+  Prevents IDE member reordering for the marked class.  
+
+### 3. Invariants  
+- **No runtime behavior**: All attributes are metadata-only. They have no effect at runtime unless consumed by tooling (e.g., ReSharper, analyzers).  
+- **Attribute targets**: Each attribute’s `AttributeUsage` is strictly defined (e.g., `CanBeNullAttribute` targets methods, parameters, properties, etc.). Applying to an unsupported target is a compile-time error.  
+- **Nullability semantics**: `[NotNull]` and `[CanBeNull]` are mutually exclusive for the same element. Tooling expects consistency; mixing them may cause conflicting warnings.  
+- **ContractAnnotation syntax**: The `contract` string must follow the specified FDT (Function Definition Table) syntax. Invalid syntax may cause analyzer errors or ignored annotations.  
+- **`StringFormatMethodAttribute`**: The `formatParameterName` must match an actual parameter name; otherwise, tooling may produce false warnings.  
+- **`AssertionConditionAttribute`**: Only valid on parameters of methods marked with `[AssertionMethod]`.  
+
+### 4. Dependencies  
+- **No external dependencies**: This module is self-contained. It uses only `System` and `System.Runtime.CompilerServices` (via attributes like `AttributeUsage`).  
+- **Consumers**: Any project referencing `DTS.Common.CPU` can use these annotations. They are intended for use in *other* modules within the `DTS.Common.*` family (e.g., `DTS.Common.CPU` itself likely consumes them, though not visible in the provided files).  
+- **Tooling dependency**: Full benefit requires ReSharper/Rider or compatible analyzers (e.g., JetBrains.Annotations NuGet package). Without tooling, attributes are inert.  
+
+### 5. Gotchas  
+- **`AssemblyInfo.cs` is metadata-only**: The assembly version (`1.0.0.0`) and GUID (`a68ef337-debf-4265-8dec-8acf01e76ee6`) are fixed and should not be changed without coordination.  
+- **`Annotations.cs` is a copy of JetBrains.Annotations**: This is a vendored copy of JetBrains’ annotation definitions (MIT-licensed). Do *not* modify it unless aligning with upstream changes.  
+- **`[Obsolete]` on `TerminatesProgramAttribute`**: The `TerminatesProgramAttribute` is deprecated in favor of `[ContractAnnotation("=> halt")]`. Using it will trigger an obsolete warning.  
+- **`AspMvc*` attributes are framework-specific**: These only make sense in ASP.NET MVC/Razor contexts. Using them in non-MVC projects may confuse tooling without benefit.  
+- **`SourceTemplate`/`Macro` require IDE support**: These attributes only function in IDEs that support template expansion (e.g., ReSharper). They are ignored in standard compilation.  
+- **`ImplicitUse*` flags are subtle**: Misusing `ImplicitUseKindFlags` (e.g., omitting `InstantiatedNoFixedConstructorSignature` when constructors are used reflectively) may cause false "unused constructor" warnings.  
+- **No runtime validation**: Attributes like `[NotNull]` do *not* enforce null checks at runtime. Developers must still write defensive code.  
+
+None identified beyond what is apparent from the source.