docs(platform): clarify FileSystem.watch recursive option behavior

[Hoishin]

Type

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Description

Update API docs and previous change log for how recursive option for FileSystem.watch is supported, and how it's handled.

Related

• Related PR feat(platform): add recursive option to FileSystem.watch #5174

It seems that it was AI slop that added "recursive option is only supported on macOS and Windows" to changelog and API docs. By the time recursive option was added, not only that Node.js v18 was already EOL, which meant all LTS at that time supported recursive watch for all OS, but also that platform-node was already using @parcel/watch by default which is always recursive.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d8e40f3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull request overview

This PR updates the documentation for the FileSystem.watch method to clarify how the recursive option behaves across different backend implementations. Previously, the documentation incorrectly stated that the recursive option was only supported on macOS and Windows, but this has been corrected to reflect the actual behavior.

Key Changes:

• Updated API documentation to explain backend-specific behavior of the recursive option
• Clarified that @parcel/watcher (the default) always watches recursively and ignores the option
• Noted that the Node.js fs.watch() fallback supports the recursive option on all platforms (Node.js v20+)

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/platform/src/FileSystem.ts	Updated JSDoc comment for the watch method to clarify recursive option behavior based on backend implementation
packages/platform-node/CHANGELOG.md	Updated changelog entry to match the corrected documentation about recursive option support

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.