refactor(filesystem): serve both kinds of watching through one interface

[EhabY]

What it does

Follow-up to #17875, restructuring what it added. Last of the stack (#17943, then #17875, then this); it shows their commits until they merge, so review only the last commit, with copy detection on so the file split does not read as an unrelated add and delete:

git diff -C --find-copies-harder HEAD~1...HEAD

The raw +1384/−980 overstates the diff: with copy detection it is ~1000 effective lines. parcel-watcher.ts pairs with the old parcel-filesystem-service.ts at ~307 shown lines, that file's remaining 592 deletions are the move's mirror image, and about half of the ~525 lines of new structure are logic extracted from the watcher rather than written new.

The service told the two watchers apart by hand: an instanceof to release a request, a client id on one path and a watcher id on the other, key prefixes to share one map, parallel create and key methods. Now both watchers implement FileSystemWatcher, a WatcherProvider per kind owns its key, factory and sharing map, and picking one by recursive is all the service knows about the difference.

The service moves out of parcel-filesystem-service.ts, which becomes a deprecated re-export so published names keep resolving until the next major. Platform and file system calls live in WatcherHost, request routing in WatchRequestRouter; neither touches the event machine, and tests drive the real watcher with the host substituted.

Defects found while auditing the feature against VS Code, fixed here:

• a queued task that threw left the change queue rejected with no handler, ending the watcher process, and swallowed the task behind it
• a change naming a file the initial snapshot had struck out reported an update and never recorded the name, so a later deletion announced a file that had never appeared
• excludes applied to the path a client explicitly asked to watch, so watching a single file under a files.watcherExclude directory was silently deaf
• the recovery diff ran against the adjusted snapshot rather than what was on disk
• clearing a delete timer that had already fired cancelled nothing
• the watched directory's own name was compared case-sensitively, and two separately resolved paths with ===, both wrong on case-insensitive file systems
• a handle error during a start was declined by a boolean guard, leaving a dead handle for good; a start attempt is a cancellation token now
• the dropped-FS-events log printed the fs.promises module instead of the watched path (pre-existing)

Honest cost: the provider abstraction is two implementations selected by a boolean. It pays by deleting the key prefixes, the instanceof and the parallel create and key pairs, but a third kind may never appear.

How to test

npx lerna run test --scope @theia/filesystem. The specs assert only on what clients were told, so they survive the restructuring; routing and sharing get their own seam via createProviders().

Follow-ups

Delete parcel-filesystem-service.ts and rename ParcelFileSystemWatcherServerOptions (only parcelOptions is parcel-specific) at the next major. Parcel failure handling: #17922.

Breaking changes

• This PR introduces breaking changes and requires careful review. If yes, the breaking changes section in the changelog has been updated.

[filesystem]: FileSystemWatcherServiceImpl moved to filesystem-watcher-service-impl.ts and delegates to providers, dropping its watchers/watcherHandles maps and createWatcher/getWatcherKey/registerWatcher/getLiveWatcher methods, along with the unreleased WatcherInstance and WatcherHandle types; ParcelWatcher moved to parcel-watcher/parcel-watcher.ts, deprecating initialClientId and renaming ParcelWatcherOptions to ParcelWatcherExcludes with a deprecated alias.

Attribution

Review checklist

• As an author, I have thoroughly tested my changes and carefully followed the review guidelines
• User-facing text is internationalized using the nls service (for details, please see the Internationalization/Localization section in the Coding Guidelines)

Reminder for reviewers

• As a reviewer, I agree to behave in accordance with the review guidelines