feat: Add the file-based override source

[kinyoklion]

Summary

This PR is based on the events branch because it completes the feature that the earlier branches build up, and it should merge after them.

This change adds the file-based override source described by the OVERRIDE specification to the Node.js server SDK. It is configured as { type: 'file', paths: [...] } in the overrides property of the data system options, alongside the source object and factory forms that the earlier change added.

The source reads one or more JSON or YAML files in the file data source document format, with optional flags, flagValues, and segments members, and combines their entries in the configured order. Duplicate keys across files fail the reload by default, or keep the first file's entry with the ignore handling. Change detection is one of two modes. Polling, the default, examines the files once per second, with a one second minimum, and works on every filesystem. Watching reacts to change notifications for the directories that contain the files. Change detection is in place before the initial load, so a change made between the two is not missed.

A configured file that does not exist contributes no overrides, so a file can be created later and deleting a file removes its overrides. A file that exists but cannot be read or parsed fails that whole reload: the last good overrides stay in effect, the failure is logged once, and the source retries after one second. Every applied change is logged at Info level with the overrides in effect and what each file supplied, and an unchanged reload logs nothing. The initial load is part of starting the client: the promise that waitForInitialization returns settles after it, and an evaluation made before that reads the layer as it is at that moment.

An invalid configuration fails client construction, the way an invalid file initializer does: no file paths, an unrecognized change detection mode, or a platform without filesystem support. An unrecognized duplicate keys handling is logged and replaced by its default. A polling interval below the minimum is logged and raised to one second, and one that is not a finite number or exceeds 2147483 seconds is logged and replaced by the default.

The specification requires YAML support without extra configuration. The Node.js SDK package gains a dependency on the yaml package (2.9.1, already present in the lockfile as a transitive dependency of other workspaces) and supplies its parser to the shared code as a platform default. A configured yamlParser takes precedence. The shared server package has no new dependency.

The existing file data sources keep their current behavior. The override source has its own document handling (format detection by file extension, validation of the document shape, entries keyed by their map key with a key field inside an entry set to that map key, so a definition pasted under a new key overrides that key, value expansion to a flag that is on and serves the value by fallthrough, missing-file handling, retry) and none of it applies to the FDv1 FileDataSource or the FDv2 file data initializer.

The tests mirror the Go file source tests over a mock filesystem: initial load, YAML, ordered merge, duplicate handling, missing files that appear and disappear, the Info log on each change, quiet watching of an absent file, reloads in both modes, retention across a malformed edit with recovery through the retry, and close. A server-node test drives the source through the client on real files, including the built-in YAML parser.

SDK-3247

---

Note

Overview
Adds an experimental file-based flag override source configurable via dataSystem.overrides: { type: 'file', paths: [...] }. It loads JSON/YAML documents (same shape as file data sources: flags, flagValues, segments), merges multiple files in order, and hot-reloads via polling (default, 1s) or directory watching. Missing files contribute nothing; parse/duplicate-key failures keep the last good snapshot, log errors, and retry.

Shared server code introduces FileOverrideSource, override-specific document validation (parseOverrideDocument / fileOverrideSourcePolicy), and expanded createOverrideSource validation (paths required, change-detection modes, poll interval bounds). Node server SDK adds the yaml package and registers a default yamlParser on LDClientNode; apps can override with yamlParser in override options.

Evaluation behavior is unchanged except overrides sit on the read path: overrideAffected reasons, waitForInitialization waits for the initial override load, and evaluations can use overrides before LD init when present in the layer.

^{Reviewed by Cursor Bugbot for commit 0329a1f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 27281 bytes
Compressed size limit: 29000
Uncompressed size: 132642 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 32691 bytes
Compressed size limit: 34000
Uncompressed size: 117095 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25437 bytes
Compressed size limit: 44000
Uncompressed size: 165420 bytes

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a386f44. Configure here.}