[TFgen] Implement tracking-field decoder + duplicate artifact name detection

[j10czar]

Changes

Decodes the x-datadog-tf-generator vendor extension into typed metadata on
model.Operation.Tracking during LoadSpec, and enforces global uniqueness of the resulting
artifact_name. Both run inside a single LoadSpec call, which now returns a fully-populated
*model.Spec or an actionable error.

• parser.DecodeTracking(op, path, method, extensionName) (*model.TrackingFieldMetadata, error) — parses the extension into a typed *model.TrackingFieldMetadata (artifact_kind,
  artifact_name, group, id_strategy, sensitive, skip) for downstream codegen,
  applying the id_strategy default (data.id). Before populating the struct it validates the
  raw value at runtime against the committed JSON Schema
  (internal/contracts/tracking-field.schema.json, embedded via a new contracts package), so
  callers only ever get well-formed metadata back. Returns (nil, nil) when the operation is
  out of scope (no extension, or skip: true), and a typed *TrackingError naming the OpenAPI
  location (method + path + operationId) when the extension is malformed (unknown
  artifact_kind, missing required field, unknown property, bad name pattern, …).
• parser.CheckDuplicateArtifactNames(spec) — walks every Operation.Tracking and fails
  with a single aggregated *DuplicateArtifactNameError listing each artifact_name collision
  and all of its source locations, sorted by name then (path, method) for deterministic
  output.
• Pipeline wiring — decode happens per-operation in the enumeration loop (storing the
  metadata on Operation.Tracking, fail-fast on a malformed extension); the duplicate check
  runs after the deterministic sort.
• --tracking-field seam — adds a WithTrackingFieldName LoadSpec option and threads
  flags.trackingField through the generate command, mirroring the existing --max-depth
  wiring.
• New dependency — github.com/santhosh-tekuri/jsonschema/v6 (a JSON-Schema validator,
  not a second OAS parser).

Note: the model carries json: tags, so once the value is validated DecodeTracking
bridges YAML→JSON (json.Marshal/Unmarshal) to fill the typed struct, rather than decoding
the yaml.Node directly.

Test Plan

New coverage — decode (asserts the returned metadata): valid resource / valid data source
(kind, name, group, id_strategy populated), absent extension, skip:true, missing required
fields, unknown artifact_kind, unknown property (additionalProperties:false), bad
artifact_name pattern, applied id_strategy default, error-carries-OpenAPI-path, custom
extension name. Duplicates: none / single collision / all-sources-listed /
multiple-collisions-sorted / ignores-untracked / deterministic-across-input-order. LoadSpec
wiring fixtures: tracking populated (resource + data source + unflagged op), duplicate →
typed error naming both ops, malformed → typed error carrying the real OpenAPI path.

❯ make tfgen-test
cd .generator-v2 && go test ./internal/... ./cmd/tfgen/...
ok    generator/internal/cli        0.505s
?     generator/internal/contracts  [no test files]
ok    generator/internal/model      0.495s
ok    generator/internal/parser     0.561s
      generator/cmd/tfgen           [no test files]
tfgen tests passed

Follow-ups / action items

• Remove the parser-side default extension name once the global CLI flags are wired into
  the cobra root (APIR-2923). DefaultTrackingFieldName and the empty-name fallback are a
  temporary stopgap so LoadSpec is usable standalone — the real default
  (x-datadog-tf-generator) already lives on the --tracking-field flag in root.go. Once the
  wiring guarantees the name is always supplied, delete:

  • the DefaultTrackingFieldName const — internal/parser/tracking.go
  • the if name != "" fallback in WithTrackingFieldName and the trackingFieldName: DefaultTrackingFieldName seed in LoadSpec — internal/parser/parser.go

  …so the extension name has a single source of truth (the CLI flag), instead of a default
  defined in two places.

• Update OAS extension contract

⚠️ Note: artifact-name uniqueness is enforced per artifact_kind, not globally — a
resource and a data_source may share a name (matches Terraform's separate namespaces).
This intentionally refines the literal AC; the schema is updated to match, but the ticket AC +
APIR-2492 discovery doc still say "globally unique" and need an owner's confirmation.

[j10czar]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [TFgen] Implement tracking-field decoder + duplicate artifact name detection #3853 👈 (View in Graphite)
• [TFgen] Adding a new terraform generator #3840 : 6 other dependent PRs (#3842 , #3849 , #3850 and 3 others)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[j10czar]

Need to add coverage to ignore collisions when both the resource and datasource have the same artifact name. Right now the CheckDuplicateArtifactNames function flags it. There are many instances where something that is a datasource and something that is a resource has the same artifact name ex. dashboard, monitors, slos etc.). Are we are adding some kind of uniqueness to artifact name in the future @Supam ?

[j10czar]

@Supam is this a valid statement? Should the OAS extension contract be updated?

[fpighi]

This is correct.

[Supam]

There technically is already some differentiation for both datasources and resources, it is just not obvious at the OAS level.

In the OAS we will be asking for the artefact name, this name will be used in both datasources and resources.
Once we run the generator we will create datasources as datasource_<artefact-name> and resources as resource_<artefact-name>. This is how we differentiate between both.