fix: stop reading private aws-cdk-lib Function.environment field

[ava-silver]

What does this PR do?

Removes all reads of aws-cdk-lib's private Function.environment field from the library. Every read is replaced with a WeakMap-backed tracker that records the library's own addEnvironment calls. Adds a public DatadogLambda.setEnvironment() method so users can seed env vars the construct will respect.

Motivation

Closes #620

aws-cdk-lib changed Function.environment's internal shape in a semver-minor (2.252 → 2.253), breaking cdk synth for all users of sourceCodeIntegration (#596). The v4.0.0 fix re-pointed the access at the new internal shape and raised the peer floor -- it kept the private coupling, so the library remained one CDK refactor away from breaking again.

Three call sites read across the private boundary:

• env.ts -- setGitEnvironmentVariables reads DD_TAGS to append git metadata
• env.ts -- applyEnvVariables checks each key before writing a default
• datadog-lambda.ts -- overrideGitMetadata reads DD_TAGS to rewrite git components

Changes

src/env-tracker.ts (new)

• Module-level WeakMap<LambdaFunction, Map<string, string>> (ddEnvTracker) and three helpers -- setTrackedEnv, getTrackedEnv, hasTrackedEnv -- that record every env write the library makes. Internal, not re-exported from index.ts.

src/env.ts

• All addEnvironment calls in setGitEnvironmentVariables, applyEnvVariables, and setDDEnvVariables go through setTrackedEnv.
• Private field reads replaced with WeakMap lookups.
• setGitEnvironmentVariables parameter type tightened from any[] to LambdaFunction[].

src/datadog-lambda.ts

• overrideGitMetadata reads DD_TAGS from getTrackedEnv instead of lambdaFunction.environment.map.get(DD_TAGS), removing the any cast. Tag rewriting extracted to an upsertTag helper.
• Adds public setEnvironment(lambdaFunction, key, value), which writes through setTrackedEnv so the construct treats the value as one it manages.

README.md

• Documents the env var ordering: configure DD_* vars via DatadogLambdaProps; call func.addEnvironment() after addLambdaFunctions() to override; or call setEnvironment() before to seed a value the construct will respect.

Behavior change

Previously the library read the private field to detect whether the user had already set a DD_* var on a function before addLambdaFunctions(), skipping its default if so -- and to append git metadata onto a user-set DD_TAGS. Without a public CDK read API (which does not exist), arbitrary pre-set env vars are no longer visible to the construct. The new contract:

• Configure via props (recommended): use DatadogLambdaProps fields (enableDatadogTracing, logLevel, tags, etc.)
• Seed a construct-respected value: call datadogLambda.setEnvironment(func, key, value) before addLambdaFunctions(). The construct will not override it, and when source code integration is enabled it appends git metadata (git.commit.sha, git.repository_url) onto a seeded DD_TAGS rather than overriding it. This preserves the prior per-function DD_TAGS + git-metadata workflow.
• Override after: call func.addEnvironment("DD_*", value) after addLambdaFunctions() -- CDK's last-write-wins semantics handle this naturally.
• Other vars set before addLambdaFunctions() (not via setEnvironment): will be overridden by the library's defaults.

Testing Guidelines

The existing suite covers the tracker migration; two tests were updated to reflect the behavior change (comments explain the new contract), and the overrideGitMetadata tests now assert via Template.fromStack() instead of reading the CDK private field. New tests cover setEnvironment: git metadata appending onto a seeded DD_TAGS, and the construct not overriding a seeded value.

Run locally with yarn test.

Types of Changes

• Bug fix
• New feature
• Breaking change

Check all that apply

• This PR's description is comprehensive
• This PR contains breaking changes that are documented in the description
• This PR introduces new APIs or parameters that are documented and unlikely to change in the foreseeable future
• This PR impacts documentation, and it has been updated (or a ticket has been logged)
• This PR's changes are covered by the automated tests

[ava-silver]

• fix: stop reading private aws-cdk-lib Function.environment field #621 👈 (View in Graphite)
• main

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

[janine-c]

Just some optional writing suggestions 🙂

[janine-c]

Suggested change

	**Configuring `DD_*` environment variables:** Set Datadog environment variables through `DatadogLambdaProps` (e.g. `enableDatadogTracing`, `logLevel`, `tags`). If you need to set a `DD_*` variable directly on a function, call `func.addEnvironment()` **after** `addLambdaFunctions()` -- values set before will be overridden by the construct.
	To configure `DD_*` environment variables, set Datadog environment variables through `DatadogLambdaProps` (for example, `enableDatadogTracing`, `logLevel`, or `tags`). If you need to set a `DD_*` variable directly on a function, call `func.addEnvironment()` **after** `addLambdaFunctions()`. This construct overwrites any values that had been set before.