[linter] Improve do_not_use_environment lint error message and documentation

[samuelkchris]

Summary

Improves the do_not_use_environment lint rule error message and documentation to be more helpful and actionable.

Problem

The current error message is confusing and unhelpful:

• Before: "Invalid use of an environment declaration."
• Users don't understand WHY they shouldn't use environment constructors
• No guidance on what to use instead
• The term "environment declaration" is unclear

Solution

After: "Avoid using environment values like 'bool.hasEnvironment' which create hidden global state."

Key Improvements:

1. Specific Method Names: Error message now includes the exact method being used (e.g., "bool.hasEnvironment", "String.fromEnvironment")

2. Clear Explanation: Explains that environment constructors create "hidden global state" which makes code hard to understand and maintain

3. Actionable Guidance: Suggests using Platform.environment for runtime access instead

4. Comprehensive Documentation:

   • Explains compile-time vs runtime behavior
   • Shows both BAD and GOOD examples
   • Provides concrete alternatives

5. Better Test Coverage: Added tests for all variants and edge cases

Examples

Before

Invalid use of an environment declaration.
Try removing the environment declaration usage.

After

Avoid using environment values like 'bool.hasEnvironment' which create hidden global state.
Try using 'Platform.environment' for runtime access or remove environment-dependent code.

Documentation Improvements

Added clear examples in the lint documentation:

BAD:

const bool usingAppEngine = bool.hasEnvironment('APPENGINE_RUNTIME');
const loggingLevel = String.fromEnvironment('LOGGING_LEVEL');

GOOD:

import 'dart:io';

// Runtime access to environment variables
final bool usingAppEngine = Platform.environment.containsKey('APPENGINE_RUNTIME');
final String loggingLevel = Platform.environment['LOGGING_LEVEL'] ?? 'info';

Files Changed

• pkg/linter/messages.yaml - Updated message and documentation
• pkg/linter/lib/src/rules/do_not_use_environment.dart - Pass method name to error
• pkg/linter/lib/src/lint_codes.g.dart - Generated code update
• pkg/linter/test/rules/do_not_use_environment_test.dart - Enhanced test coverage

Test Plan

• ✅ All existing tests pass
• ✅ Added comprehensive test coverage for message formatting
• ✅ Tested with the original issue example (bool.hasEnvironment('APPENGINE_RUNTIME'))
• ✅ Verified error messages include specific method names

Fixes #59203

[copybara-service]

Thank you for your contribution! This project uses Gerrit for code reviews. Your pull request has automatically been converted into a code review at:

https://dart-review.googlesource.com/c/sdk/+/435744

Please wait for a developer to review your code review at the above link; you can speed up the review if you sign into Gerrit and manually add a reviewer that has recently worked on the relevant code. See CONTRIBUTING.md to learn how to upload changes to Gerrit directly.

Additional commits pushed to this PR will update both the PR and the corresponding Gerrit CL. After the review is complete on the CL, your reviewer will merge the CL (automatically closing this PR).

[copybara-service]

https://dart-review.googlesource.com/c/sdk/+/435744 has been updated with the latest commits from this pull request.

[copybara-service]

https://dart-review.googlesource.com/c/sdk/+/435744 has been updated with the latest commits from this pull request.