diff --git a/README.md b/README.md index ff28d30..e9a6f41 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ When published, consume it as a development-only analyzer dependency: + IncludeAssets="analyzers; buildtransitive" /> ``` For local evaluation from this checkout, reference the analyzer project directly from a consumer project: @@ -40,8 +40,8 @@ The package-level generated catalog is in [`docs/Qyl.OpenTelemetry.SemanticConve | [`QYL0014`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0014) | Warning | Yes | Hard-coded value matches a semantic-convention value constant marked `[Obsolete]` | | [`QYL0021`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0021) | Warning | No | Library directly references incubating semantic-convention members | | [`QYL0030`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0030) | Error | Exact replacements only | Supplemental catalog exact replacement in production telemetry emission | -| [`QYL0031`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0031) | Warning | Exact replacements only | Supplemental catalog context-sensitive, manual-review, removed/no-replacement, or ambiguous payload migration | -| [`QYL0032`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0032) | Info | Exact replacements only | Supplemental catalog item appears in test, fixture, compatibility, generated, translator, or catalog context | +| [`QYL0031`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0031) | Warning | No | Supplemental catalog context-sensitive, manual-review, removed/no-replacement, or ambiguous payload migration | +| [`QYL0032`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0032) | Info | No | Supplemental catalog item appears in test, fixture, compatibility, generated, translator, or catalog context | ## Examples @@ -64,7 +64,7 @@ activity.SetTag("error.message", message); // QYL0031; replacem - **Multi-hop rename resolution.** `SemconvMigrationCatalog.ResolveTerminalReplacement` chases `ExactRename` chains (e.g. `http.host` → `net.host.name` → `server.address`) so code-fixes land consumers on the terminal symbol, not on a still-deprecated mid-state. Cycles and chains over 8 hops bail at the last safe step. - **Structured changelog provenance.** Every `SemconvMigrationCatalogEntry` may carry an optional `SemconvChangelogEvidence` (commit / version / url / quote) pinning the migration claim to an exact upstream commit, so the catalog is auditable without re-parsing CHANGELOG.md. - **Catalog seeding from upstream.** `scripts/seed-catalog.sh ` clones a shallow upstream `open-telemetry/semantic-conventions` checkout, slices CHANGELOG.md between two version tags, and emits C# (or `--format json`) skeleton entries with provenance pre-filled. Curate the `Kind`/`Domain`/`Signal`/`MigrationKind` fields by hand before merging. -- **Generated docs and audit.** Regenerate the package catalog with `scripts/generate-docs.sh generate`; validate with `scripts/generate-docs.sh validate`; print the current 156-entry coverage audit with `scripts/generate-docs.sh audit`. Every `QYL*` rule has a stable `#qyl0010` anchor in the generated docs that every `DiagnosticDescriptor.HelpLinkUri` resolves to. +- **Generated docs and audit.** Regenerate the package catalog with `scripts/generate-docs.sh generate`; validate with `scripts/generate-docs.sh validate`; print the current coverage audit with `scripts/generate-docs.sh audit`. Every `QYL*` rule has a stable `#qyl0010` anchor in the generated docs that every `DiagnosticDescriptor.HelpLinkUri` resolves to. - **netstandard2.0** only — required by Roslyn analyzer host. Microsoft.CodeAnalysis.* dependencies only. - **Multi-version friendly.** A consumer on SemConv 1.39.0 gets live metadata diagnostics scoped to the 1.39.0 surface; upgrading expands those diagnostics automatically. The supplemental catalog is a conservative v1.41.0 migration aid. @@ -135,7 +135,7 @@ tests/WeaverRoundTrip/generate.sh # 4. Confirm the analyzer fires QYL0010 against the regenerated file: dotnet build Qyl.OpenTelemetry.SemanticConventions.Analyzers.slnx \ -c Release -warnaserror:QYL0010 -dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \ +dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \ --filter 'FullyQualifiedName~WeaverRoundTrip' ``` @@ -147,7 +147,7 @@ Run the repository gates before changing diagnostics, catalog data, or generated ```bash dotnet build Qyl.OpenTelemetry.SemanticConventions.Analyzers.slnx -c Release -dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj +dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj scripts/generate-docs.sh validate scripts/generate-docs.sh audit git diff --check @@ -155,7 +155,7 @@ git diff --check ## Incubation -This repository is the incubation home for what may eventually be proposed as an official `OpenTelemetry.SemanticConventions.Analyzers` companion to `opentelemetry-dotnet-contrib`. While here, it ships under the `ANcpLua.*` package ID and Apache-2.0 license. +This repository is the incubation home for what may eventually be proposed as an official `OpenTelemetry.SemanticConventions.Analyzers` companion to `opentelemetry-dotnet-contrib`. While here, it ships under the `Qyl.*` package ID and Apache-2.0 license. ## License diff --git a/docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md b/docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md index 0fd0b20..d9b0978 100644 --- a/docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md +++ b/docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md @@ -1,6 +1,6 @@ # Qyl.OpenTelemetry.SemanticConventions.Analyzers - + This package analyzes OpenTelemetry semantic-convention usage in C# consumers. The consumer's referenced `OpenTelemetry.SemanticConventions` assembly remains the primary source of truth: rules that read `[Obsolete]` metadata report what that package actually generated. The curated inventory below separates live-metadata coverage from supplemental diagnostics for changelog/model entries that are not reliably visible through live metadata. @@ -17,8 +17,8 @@ This package analyzes OpenTelemetry semantic-convention usage in C# consumers. T | QYL0014 | Warning | Deprecated semantic-convention value | Yes | A constant string used as the value of a known semantic-convention telemetry attribute matches a value member that is marked [Obsolete] in the consumer's referenced *Values enum class. | | QYL0021 | Warning | Incubating semantic-convention member used in a library | No | Members under any *.SemanticConventions.Incubating namespace may rename or change values across minor package releases. Library projects (non-exe, non-test) baking direct references push that volatility onto every downstream consumer. | | QYL0030 | Error | Obsolete semantic convention has an exact replacement | Exact replacements only | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog and has a one-to-one replacement. This supplements, but does not replace, [Obsolete] metadata from OpenTelemetry.SemanticConventions. | -| QYL0031 | Warning | Semantic convention migration needs review | Exact replacements only | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement. | -| QYL0032 | Info | Legacy semantic convention appears in compatibility or test code | Exact replacements only | A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled. | +| QYL0031 | Warning | Semantic convention migration needs review | No | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement. | +| QYL0032 | Info | Legacy semantic convention appears in compatibility or test code | No | A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled. | ## Rule Reference @@ -102,7 +102,7 @@ Code fix: Exact replacements only. A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement. -Code fix: Exact replacements only. +Code fix: No. ### QYL0032 @@ -110,7 +110,7 @@ Code fix: Exact replacements only. A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled. -Code fix: Exact replacements only. +Code fix: No. ## Precedence and Suppression @@ -458,8 +458,8 @@ These value rows are intentionally separate from the 156-entry name/key/event/me Regenerate with: ```bash -dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check +dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator +dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check ``` The `--check` mode fails if the generated markdown differs from the checked-in file.