Skip to content

Standardize enable option handling across all plugins#324

Draft
watson wants to merge 1 commit into
masterfrom
watson/DEBUG-5291/fix-enable
Draft

Standardize enable option handling across all plugins#324
watson wants to merge 1 commit into
masterfrom
watson/DEBUG-5291/fix-enable

Conversation

@watson
Copy link
Copy Markdown
Contributor

@watson watson commented Apr 19, 2026

What and why?

The six user-facing plugins (apps, error-tracking, live-debugger, metrics, output, rum) each had a divergent implementation for resolving their enable config boolean:

  • Two code patterns: apps and live-debugger used explicit ?? nullish coalescing, while the other four used a spread-override trick (enable: !!config[KEY], ...config[KEY]) that relies on property ordering.
  • Inconsistent validation: Only live-debugger rejected non-boolean values; the rest silently coerced.
  • Incomplete docs: output and metrics documented default: true (misleading — it's false when the config block is absent), error-tracking had no enable section at all, and rum had no README (lost in the sourcemaps extraction refactor of 804f917).

This PR standardizes all three axes so future plugins have a single pattern to follow.

How?

Shared helper (@dd/core/helpers/options):

  • resolveEnable(options, configKey, log) — single source of truth for resolving enable. Emits a deprecation warning (once per key) when a non-boolean value is passed, but still coerces it with !! to avoid breaking existing users. Strict rejection is deferred to the next major.
  • validateEnableStrict(pluginConfig, errors) — pushes a hard validation error for non-booleans. Used only by live-debugger, preserving its existing contract.

Plugin refactors:

  • All six validators now call resolveEnable() instead of ad-hoc logic. apps and output gained a log parameter (call sites updated). For the spread-override plugins, enable is now set after the spread so it can never be silently overwritten.

Documentation:

  • Every plugin's README now has a consistent ### <key>.enable section with the correct default wording: "true when a <key> config block is present, false otherwise."
  • error-tracking gained its missing enable section and TOC entry.
  • A full rum README was authored covering enable, sdk.*, privacy.*, and sourceCodeContext.*.

Tests:

  • 15 new tests for the shared helper (coercion, warn-once, strict validation).
  • Each plugin's validate tests extended with non-boolean enable cases asserting the deprecation warning.

@watson watson mentioned this pull request Apr 19, 2026
Copy link
Copy Markdown
Contributor Author

watson commented Apr 19, 2026

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

Base automatically changed from watson/DEBUG-5291/add-live-debugger-plugin to master April 20, 2026 13:42
@watson watson force-pushed the watson/DEBUG-5291/fix-enable branch from 430542d to dd508cf Compare April 20, 2026 14:58
Introduce a shared `resolveEnable` helper in @dd/core that all six
user-facing plugins now use to resolve their `enable` config flag.
This replaces the two divergent patterns (explicit `??` vs spread-
override) with a single greppable call site per plugin.

Non-boolean values continue to be coerced for backwards compatibility
but now emit a deprecation warning so strict validation can land in
the next major. live-debugger retains its existing hard rejection via
the companion `validateEnableStrict` helper.

Also fixes the misleading `default: true` wording in the output and
metrics READMEs, adds the missing `errorTracking.enable` docs section,
and authors a full README for the rum plugin (lost in the sourcemaps
extraction refactor of 804f917).
@watson watson force-pushed the watson/DEBUG-5291/fix-enable branch from dd508cf to 00679a8 Compare May 12, 2026 05:31
Copy link
Copy Markdown
Member

@yoannmoinet yoannmoinet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks mostly good.

I wonder if we could handle one level higher than just resolveEnable and have something like a global validateOptions, that would, for now, validate enable.

It would be called from each plugin, but would be implemented, tested and documented just once.
Since this is a standard, this can be documented just at the root, once, and not for each individual plugin.

Or alternatively, handle this at the factory level directly, where we also have an validateOptions too.

for (const [name, getPlugins] of pluginsToAdd) {
context.plugins.push(
...wrapGetPlugins(
context,
getPlugins,
name,
)({
bundler,
context,
options,
data,
stores,
}),
);
}

This way, plugins themselves don't even have to handle it.
The standard is applied by design.

I think I prefer the factory approach after all.

WDYT?

Comment on lines +9 to +16
const mockLogger: Logger = {
getLogger: jest.fn(() => mockLogger),
time: jest.fn() as unknown as Logger['time'],
error: jest.fn(),
warn: jest.fn(),
info: jest.fn(),
debug: jest.fn(),
};
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This already exists.

export const mockLogFn = jest.fn((text: any, level: LogLevel) => {});
export const getMockLogger = (overrides: Partial<Logger> = {}): Logger => ({
getLogger: jest.fn(),
time: jest.fn(() => getMockTimeLogger()),
error: (text: any) => {
mockLogFn(text, 'error');
},
warn: (text: any) => {
mockLogFn(text, 'warn');
},
info: (text: any) => {
mockLogFn(text, 'info');
},
debug: (text: any) => {
mockLogFn(text, 'debug');
},
...overrides,
});
export const mockLogger: Logger = getMockLogger();

Same thing in the other test files.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should live in its own PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants