ttsc 0.30.4 → 0.31.0

package/src/launcher/internal/watch/FseventsStreams.ts

@@ -0,0 +1,303 @@
+import { EventEmitter } from "node:events";
+import path from "node:path";
+
+import type { DirectoryWatcher } from "./DirectoryWatcher";
+
+/**
+ * The FSEventStreams serving this process's macOS directory watches.
+ *
+ * A stream covers its root recursively. Watches below an open stream join it;
+ * opening an ancestor starts its stream before retiring the descendant streams.
+ * Still-active transferred watches receive a deferred gap notification; their
+ * owners decide the content recheck. Retired streams reject later callbacks
+ * through their inactive guard. Stream roots and their descendants are indexed,
+ * so registration, close, and named event delivery depend on path depth and
+ * affected watches rather than every stream in the process.
+ *
+ * @evidence contracts/common.md#principled-implementation Ancestor streams cover descendant subscriptions; promotion starts replacement observation before retiring old streams and then reports the handoff gap.
+ * @evidence contracts/common.md#clear-and-simple-design Stream ownership and descendant indexes are distinct from each watch's listener and close state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The registry uses the binding's supported watch/stop boundary and explicit gaps instead of patching libuv or assuming queued callbacks survive stop.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain ancestor reuse, transfer ordering, gaps and index-driven delivery following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation This macOS binding boundary interprets FSEvents flags explicitly and exposes the same DirectoryWatcher contract as Node's other native backends.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The class representation groups indexes; open and event helpers own processing strategies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration operations establish stream sharing rather than the state representation itself.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Registry methods own active native streams and ancestor/subscription indexes, growing with roots, depth, text and watches without a quota. Last-subscription close removes logical indexes and attempts native stop, whose failures are suppressed. Returned watcher closures/listeners can remain caller-reachable after close; callers must discard retired objects to permit reclamation.
+ */
+export class FseventsStreams {
+  private readonly descendants = new Map<string, Set<Stream>>();
+  private readonly streams = new Map<string, Stream>();
+
+  /** Use the binding supplied by the host for every stream in this registry. */
+  public constructor(private readonly binding: FseventsBinding) {}
+
+  /**
+   * Load the optional binding, or warn and return `null` without it. The
+   * selecting watchDirectory owner calls this once for the process.
+   *
+   * @evidence contracts/common.md#principled-implementation A binding must expose the required watch function before the registry can use it; unavailable optional support is surfaced by a warning.
+   * @evidence contracts/common.md#clear-and-simple-design One shape check constructs the registry or returns explicit unavailability.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The real Node watcher fallback serves missing optional production support, not a fake successful binding or fixture branch.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes per-call warning from the selecting owner's once-per-process scheduling following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation The optional macOS binding is loaded at its explicit native boundary and its absence retains supported Node observation with a stated limitation.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms require delegates module resolution/loading and possible native binding initialization, then a fixed interface check constructs two empty registry maps or formats/emits a warning. Module/path/initialization work is not bounded by the shape check; this method traverses no watch population.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The selecting owner caches availability; calling this constructor directly does not coordinate caller reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned registry owns no stream until open acquires one; module loading has no independently released watcher here.
+   */
+  public static load(): FseventsStreams | null {
+    try {
+      const loaded: unknown = require("fsevents");
+      if (
+        typeof loaded !== "object" ||
+        loaded === null ||
+        !("watch" in loaded) ||
+        typeof loaded.watch !== "function"
+      ) {
+        throw new TypeError("fsevents does not expose watch()");
+      }
+      return new FseventsStreams(loaded as FseventsBinding);
+    } catch {
+      process.emitWarning(
+        "the optional `fsevents` package could not be loaded, so `ttsc --watch` watches through `fs.watch`, which on macOS can lose events without notice. Reinstall ttsc without omitting optional dependencies.",
+        { code: "TTSC_WATCH_FSEVENTS_UNAVAILABLE" },
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Open one directory watch, joining an ancestor stream where one exists.
+   *
+   * @param location The physical directory to watch.
+   * @param recursive Whether to receive events below immediate children.
+   * @param listener Receives the event and its relative name, or `null` with a
+   *   gap flag when every affected input needs a content recheck.
+   * @returns A watcher whose close is idempotent.
+   * @evidence contracts/common.md#principled-implementation A watch joins a covering ancestor stream; promotion transfers existing subscriptions before retiring displaced streams and schedules one gap recheck.
+   * @evidence contracts/common.md#clear-and-simple-design Stream selection is separate from subscription state; returned close/on callbacks operate on one captured watch.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Transfer gaps are reported explicitly rather than hidden by repeated registration or assumptions about stopped native callbacks.
+   * @evidence contracts/common.md#meaningful-documentation Native parameters explain physical roots, recursion, absent names and idempotent returned ownership following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Physical path.resolve/dirname ancestry qualifies the macOS native stream; callers retain the backend-independent DirectoryWatcher interface.
+   * @evidence contracts/performance.md#efficient-algorithms D path ancestors locate a covering stream; indexed descendants visit displaced roots and W subscriptions, with ancestor-index removal/insertion per displaced root and local displaced/transferred collections. Native watch/stop, path/key text, deferred gap listeners and event delivery contribute delegated costs. Named delivery follows ancestry and eligible watches, while gaps visit the affected stream population. Depth/text/watch populations are uncapped.
+   * @evidence contracts/performance.md#reuse-equivalent-work Recursive native observation is shared by watches under one live ancestor; promotion preserves each listener/recursion contract while replacing the underlying stream identity.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The registry owns active stream handles and O(SD+W) index/subscription references for S roots and W watches, plus associated path/listener text without a quota. Last-subscription closure unregisters and attempts stop; suppressed stop failures cannot prove native reclamation. Retired returned watcher objects still capture their watch/registry/listeners until callers discard them.
+   */
+  public open(
+    location: string,
+    recursive: boolean,
+    listener: Watch["listener"],
+  ): DirectoryWatcher {
+    const directory = path.resolve(location);
+    const stream = this.streamFor(directory);
+    const watch: Watch = {
+      active: true,
+      directory,
+      emitter: new EventEmitter(),
+      listener,
+      recursive,
+      stream,
+    };
+    addWatch(stream, watch);
+    return {
+      close: () => this.close(watch),
+      on: (event, handler) => watch.emitter.on(event, handler),
+    };
+  }
+
+  /** Find an ancestor stream, or start one and transfer its descendants. */
+  private streamFor(directory: string): Stream {
+    for (let ancestor = directory; ; ancestor = path.dirname(ancestor)) {
+      const found = this.streams.get(ancestor);
+      if (found !== undefined) return found;
+      if (path.dirname(ancestor) === ancestor) break;
+    }
+
+    const displaced = [...(this.descendants.get(directory) ?? [])];
+    const stream: Stream = {
+      active: true,
+      root: directory,
+      stop: () => undefined,
+      watches: new Map(),
+    };
+    // The old streams still serve their watches if opening this one fails.
+    stream.stop = this.binding.watch(directory, (file, flags) =>
+      deliver(stream, file, flags),
+    );
+    const transferred = new Set<Watch>();
+    for (const old of displaced) {
+      for (const watches of old.watches.values()) {
+        for (const watch of watches) {
+          addWatch(stream, watch);
+          transferred.add(watch);
+        }
+      }
+      old.watches.clear();
+      old.active = false;
+      this.unregisterStream(old);
+    }
+    this.registerStream(stream);
+    for (const old of displaced) stopStream(old);
+
+    if (transferred.size !== 0) {
+      queueMicrotask(() => {
+        // Retired streams reject later callbacks through their inactive guard.
+        // The new stream receives later events; a gap notice lets the owner
+        // recheck the handoff.
+        for (const watch of transferred) {
+          if (watch.active && watch.stream === stream) {
+            watch.listener("rename", null, true);
+          }
+        }
+      });
+    }
+    return stream;
+  }
+
+  private close(watch: Watch): void {
+    if (!watch.active) return;
+    watch.active = false;
+    const stream = watch.stream;
+    const watches = stream.watches.get(watch.directory);
+    watches?.delete(watch);
+    if (watches?.size === 0) stream.watches.delete(watch.directory);
+    if (stream.watches.size !== 0) return;
+    stream.active = false;
+    this.unregisterStream(stream);
+    stopStream(stream);
+  }
+
+  private registerStream(stream: Stream): void {
+    this.streams.set(stream.root, stream);
+    for (const ancestor of strictAncestors(stream.root)) {
+      const descendants = this.descendants.get(ancestor) ?? new Set<Stream>();
+      descendants.add(stream);
+      this.descendants.set(ancestor, descendants);
+    }
+  }
+
+  private unregisterStream(stream: Stream): void {
+    this.streams.delete(stream.root);
+    for (const ancestor of strictAncestors(stream.root)) {
+      const descendants = this.descendants.get(ancestor);
+      descendants?.delete(stream);
+      if (descendants?.size === 0) this.descendants.delete(ancestor);
+    }
+  }
+}
+
+/** The part of the `fsevents` binding used for directory observation. */
+type FseventsBinding = {
+  watch(
+    root: string,
+    handler: (file: string, flags: number) => void,
+  ): () => unknown;
+};
+
+type Watch = {
+  active: boolean;
+  directory: string;
+  emitter: EventEmitter;
+  listener: (
+    event: "change" | "rename",
+    filename: string | null,
+    gap?: boolean,
+  ) => void;
+  recursive: boolean;
+  stream: Stream;
+};
+
+type Stream = {
+  active: boolean;
+  root: string;
+  stop: () => unknown;
+  watches: Map<string, Set<Watch>>;
+};
+
+/** FSEvents flags that say the stream may have lost events. */
+const GAP = 0x1 | 0x2 | 0x4 | 0x8 | 0x20 | 0x40 | 0x80;
+const MODIFIED = 0x400 | 0x1000 | 0x2000 | 0x4000 | 0x8000;
+const RENAMED = 0x100 | 0x200 | 0x800;
+
+function addWatch(stream: Stream, watch: Watch): void {
+  const watches = stream.watches.get(watch.directory) ?? new Set<Watch>();
+  watches.add(watch);
+  watch.stream = stream;
+  stream.watches.set(watch.directory, watches);
+}
+
+function stopStream(stream: Stream): void {
+  try {
+    Promise.resolve(stream.stop()).catch(() => undefined);
+  } catch {
+    // A failed stop cannot be repaired after the stream lost its subscribers.
+  }
+}
+
+/** Deliver one event to its parent watch and recursive ancestor watches. */
+function deliver(stream: Stream, file: string, flags: number): void {
+  if (!stream.active) return;
+  if ((flags & GAP) !== 0) {
+    deliverGap(stream);
+    return;
+  }
+  const target = path.resolve(file);
+  if (!isWithin(stream.root, target)) {
+    // The stream reported a path it cannot place, so its observations may be
+    // incomplete. The unplugin broker treats the same case as a gap.
+    deliverGap(stream);
+    return;
+  }
+  const event =
+    (flags & MODIFIED) !== 0 && (flags & RENAMED) === 0 ? "change" : "rename";
+  const deliveries: Array<{ name: string; watch: Watch }> = [];
+  let directory = path.dirname(target);
+  let depth = 0;
+  while (isWithin(stream.root, directory)) {
+    const watches = stream.watches.get(directory);
+    if (watches !== undefined) {
+      const name = path.relative(directory, target);
+      for (const watch of watches) {
+        if (depth === 0 || watch.recursive) {
+          deliveries.push({ name, watch });
+        }
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+    depth += 1;
+  }
+  for (const { name, watch } of deliveries) {
+    if (watch.active && watch.stream === stream) watch.listener(event, name);
+  }
+}
+
+function deliverGap(stream: Stream): void {
+  const watches = [...stream.watches.values()].flatMap((set) => [...set]);
+  for (const watch of watches) {
+    if (watch.active && watch.stream === stream) {
+      watch.listener("rename", null, true);
+    }
+  }
+}
+
+function* strictAncestors(location: string): Iterable<string> {
+  let ancestor = path.dirname(location);
+  while (ancestor !== location) {
+    yield ancestor;
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) break;
+    ancestor = parent;
+  }
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}

package/src/launcher/internal/watch/ProjectInputWatchRules.ts

@@ -0,0 +1,179 @@
+import path from "node:path";
+
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import { WatchPaths } from "./WatchPaths";
+import { literalGlobRoot } from "./literalGlobRoot";
+
+/**
+ * Rules for watching the inputs project rules declare beyond the TypeScript
+ * Program (documents, schemas, generated sources).
+ *
+ * They decide which directory a declared input is observed through, whether a
+ * directory still anchors any declaration after a change, and whether a changed
+ * path can affect the compiler's Program rather than only a rule.
+ *
+ * @evidence contracts/common.md#principled-implementation Declaration ancestry, safe observation roots and compiler-capable extensions remain distinct inputs to watch decisions.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace groups project-input classification helpers without owning handles or notification scheduling.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Root rules follow supplied declarations and physical identity instead of fixture directories or guessed plugin behavior.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify root ownership, retained declarations and Program effects following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Boundary helpers use actual filesystem identity transactions and native ancestry; source-extension policy is separate from native case capability.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Member operations choose their algorithms; namespace representation performs no computation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace contains no independent reuse coordinator.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace acquires no watcher or resident state.
+ */
+export namespace ProjectInputWatchRules {
+  /**
+   * Whether a file extension is one TypeScript-Go compiles or emits.
+   *
+   * @evidence contracts/common.md#principled-implementation The fixed supported source-extension set identifies compiler-capable inputs without asserting that every such file belongs to the current Program.
+   * @evidence contracts/common.md#clear-and-simple-design One bounded membership predicate is shared by topology and population invalidation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Extensions are compiler contract discriminants rather than consumer or fixture special cases.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states compiler/emit capability following the documentation skill.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Extension membership owns no native path or filesystem identity operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The fixed eight-item semantic set has no workload-dependent collection strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Classification owns no repeated-work coordinator.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No state or native resource survives the predicate.
+   */
+  export function isCompilerEmittableSourceExtension(
+    extension: string,
+  ): boolean {
+    return [
+      ".cjs",
+      ".cts",
+      ".js",
+      ".jsx",
+      ".mjs",
+      ".mts",
+      ".ts",
+      ".tsx",
+    ].includes(extension);
+  }
+
+  /**
+   * The directory a recursive watcher for `target` should be installed on.
+   *
+   * A target inside the project selects the nearest existing directory at or
+   * above the project root. For an external target, candidates are the nearest
+   * existing directories of its declared parent and its own tree, in that
+   * order. A candidate strictly containing the project is refused; one with the
+   * project's own identity is allowed. If neither candidate is admitted, the
+   * result is undefined. This selects a root under current native observations;
+   * it starts no watcher and does not prove future event delivery.
+   *
+   * @evidence contracts/common.md#principled-implementation Internal declarations select existing ancestry of the project root; external candidates cannot strictly contain the project and displace its distinct root selection, while equal physical identity is admitted.
+   * @evidence contracts/common.md#clear-and-simple-design Internal and external ownership branches share one physical identity policy and nearest-existing-directory helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An unsafe external owner remains undefined instead of adding a broad ancestor watch to disguise lost observation.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain missing trees, parent preference and the containment ceiling with their reasons, following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native resolve/dirname supply ancestry; the supplied transaction compares physical roots and actual case semantics, including symlink aliases.
+   * @evidence contracts/performance.md#efficient-algorithms Construction of a default identity context precedes selection. The internal branch makes one native ancestor-stat search; the external branch eagerly makes both parent and target searches before candidate admission. Identity resolution/containment adds path-text, ancestor and possible case-query work through the shared context; no descendant corpus is enumerated and depth/text/query populations are not capped here.
+   * @evidence contracts/performance.md#reuse-equivalent-work The transaction shares equivalent native identity resolutions across root and ceiling comparisons for this selection; later selections can use fresh state.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection returns an optional path without acquiring a watcher or retaining history. A supplied identity context remains caller-owned; a default context and its observation maps are invocation-local and become reclaimable after their references are discarded.
+   */
+  export function projectInputRecursiveWatchRoot(
+    target: string,
+    projectRoot: string,
+    identities = createProjectInputPathIdentityContext(),
+  ): string | undefined {
+    const resolvedTarget = path.resolve(target);
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    if (identities.isWithin(resolvedProjectRoot, resolvedTarget)) {
+      return WatchPaths.nearestExistingDirectory(resolvedProjectRoot);
+    }
+    // An external anchor prefers the declared parent so missing trees and
+    // sibling declarations can select the same observation root. Installation
+    // and actual delivery remain with the topology owner. The root
+    // may not rise strictly past the project: a containing root can displace
+    // its distinct root selection when roots are merged. Declining avoids that
+    // broader selection; it does not establish what a shared ancestor watcher
+    // would deliver. Prefer the declared parent, fall back to the target's own
+    // tree, and allow equality with the project root.
+    for (const candidate of [
+      WatchPaths.nearestExistingDirectory(path.dirname(resolvedTarget)),
+      WatchPaths.nearestExistingDirectory(resolvedTarget),
+    ]) {
+      if (candidate === undefined) continue;
+      // The project root cannot outrank itself in the merge, so it is the one
+      // container that is never a swallow — it is the owner the internal branch
+      // would have chosen when it exists. An in-project directory symlink can
+      // produce the same physical root here; that alias must remain eligible.
+      if (
+        identities.resolve(candidate).key !==
+          identities.resolve(resolvedProjectRoot).key &&
+        identities.isWithin(candidate, resolvedProjectRoot)
+      ) {
+        continue;
+      }
+      return candidate;
+    }
+    return undefined;
+  }
+
+  /**
+   * Whether `directory` contains any declaration of the snapshot: a declared
+   * file, a reload file, a reload directory strictly below it, or the literal
+   * root of a declared glob. This predicate classifies declaration ancestry;
+   * watcher retirement and native delivery remain the topology owner's
+   * decisions.
+   *
+   * @evidence contracts/common.md#principled-implementation Files and glob roots anchor containing coverage; reload-directory membership alone requires a strict containing directory. Other declaration categories can independently anchor the same path.
+   * @evidence contracts/common.md#clear-and-simple-design Four short-circuited declaration categories remain visible under one anchor predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No project directory is treated as an anchor without an actual declaration, and reload membership is not widened to its whole subtree.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states each category and the strict reload-directory relation following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation All ancestry and equal-root distinctions use the supplied actual filesystem identity transaction.
+   * @evidence contracts/performance.md#efficient-algorithms At most F files, R reload declarations and G globs are visited with short-circuiting. Each containment/equality query can resolve native identities and inspect key text; globs additionally compute their literal root. Costs include declaration spelling, ancestor/entry/case observations and native queries, not just F+R+G. No declared corpus contents are enumerated.
+   * @evidence contracts/performance.md#reuse-equivalent-work The caller's shared transaction caches repeated identity lookups across anchor and root-selection questions for one native state.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows declarations and the transaction; it opens no watcher and retains no history.
+   */
+  export function projectInputAnchorsDeclaration(
+    snapshot: ITtscProjectInputSnapshot,
+    directory: string,
+    identities: ProjectInputPathIdentityContext,
+  ): boolean {
+    return (
+      snapshot.files.some((file) => identities.isWithin(directory, file)) ||
+      (snapshot.reloadFiles ?? []).some((file) =>
+        identities.isWithin(directory, file),
+      ) ||
+      (snapshot.reloadDirectories ?? []).some(
+        (entry) =>
+          // This category anchors a strict containing directory, not the reload
+          // directory itself. Its immediate membership does not by itself
+          // declare a descendant corpus; other file/glob declarations above or
+          // below this branch can still anchor that same directory.
+          identities.isWithin(directory, entry) &&
+          identities.resolve(directory).key !== identities.resolve(entry).key,
+      ) ||
+      snapshot.globs.some((glob) =>
+        identities.isWithin(directory, literalGlobRoot(glob)),
+      )
+    );
+  }
+
+  /**
+   * Whether a changed project input could change the TypeScript Program: a
+   * source or emittable extension, or JSON, which `resolveJsonModule` imports
+   * and tsconfig files are written in.
+   *
+   * @evidence contracts/common.md#principled-implementation JSON and recognized source extensions can alter compiler inputs even when also selected as project-rule data.
+   * @evidence contracts/common.md#clear-and-simple-design One normalized native extension delegates the compiler-source set to its owning predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The capability set follows compiler semantics rather than named project fixtures.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains JSON's dual data/config role following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native extname extracts the extension without separator assumptions; extension case normalization is language policy, not filesystem identity folding.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms Native extname scans supplied path text, then lowercasing allocates normalized extension text before JSON or fixed eight-item membership. No directory population is visited; input path/extension lengths remain uncapped here.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Classification coordinates no equivalent computation requests.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No retained state or resource is acquired.
+   */
+  export function projectInputPathMayAffectProgram(location: string): boolean {
+    const extension = path.extname(location).toLowerCase();
+    return (
+      extension === ".json" || isCompilerEmittableSourceExtension(extension)
+    );
+  }
+}

package/src/launcher/internal/watch/WatchInputChange.ts

@@ -0,0 +1,31 @@
+/**
+ * One classified filesystem event from the watch topology, before it is
+ * coalesced into a cycle by {@link PendingResidentCheckWatchChanges}.
+ *
+ * @evidence contracts/common.md#principled-implementation The discriminant distinguishes compiler data, project-rule data and execution-selection inputs; invalidation separately requests a cold Program without replacing the process.
+ * @evidence contracts/common.md#clear-and-simple-design One tagged event carries optional localization and an independent resident-invalidation qualification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The event does not invent a changed path for an unnamed native notification.
+ * @evidence contracts/common.md#meaningful-documentation Member paragraphs explain reload categories, invalidation and absent localization following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Optional path preserves the backend's inability to name a changed input instead of assuming every native notification carries a filename.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type WatchInputChange = {
+  /** Keep the resident process but cold-load its compiler Program. */
+  invalidate?: boolean;
+
+  /**
+   * Which population the path belongs to. `config` and `plugin` changes force a
+   * full reload; `compiler` belongs to the compiler input topology, including
+   * non-TypeScript files the compiler reports; `project` is a file a project
+   * rule declared as its own input.
+   */
+  kind: "compiler" | "config" | "plugin" | "project";
+
+  /**
+   * The changed path, when the backend named it. An unnamed `compiler` event
+   * cannot be localized and is treated as a reload.
+   */
+  path?: string;
+};