ttsc 0.30.3 → 0.31.0

package/lib/launcher/internal/watch/FseventsStreams.d.ts

@@ -0,0 +1,87 @@
+import { EventEmitter } from "node:events";
+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 declare class FseventsStreams {
+    private readonly binding;
+    private readonly descendants;
+    private readonly streams;
+    /** Use the binding supplied by the host for every stream in this registry. */
+    constructor(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.
+     */
+    static load(): FseventsStreams | 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.
+     */
+    open(location: string, recursive: boolean, listener: Watch["listener"]): DirectoryWatcher;
+    /** Find an ancestor stream, or start one and transfer its descendants. */
+    private streamFor;
+    private close;
+    private registerStream;
+    private unregisterStream;
+}
+/** 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>>;
+};
+export {};

package/lib/launcher/internal/watch/FseventsStreams.js

@@ -0,0 +1,266 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FseventsStreams = void 0;
+const node_events_1 = require("node:events");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 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.
+ */
+class FseventsStreams {
+    binding;
+    descendants = new Map();
+    streams = new Map();
+    /** Use the binding supplied by the host for every stream in this registry. */
+    constructor(binding) {
+        this.binding = binding;
+    }
+    /**
+     * 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.
+     */
+    static load() {
+        try {
+            const loaded = 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);
+        }
+        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.
+     */
+    open(location, recursive, listener) {
+        const directory = node_path_1.default.resolve(location);
+        const stream = this.streamFor(directory);
+        const watch = {
+            active: true,
+            directory,
+            emitter: new node_events_1.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. */
+    streamFor(directory) {
+        for (let ancestor = directory;; ancestor = node_path_1.default.dirname(ancestor)) {
+            const found = this.streams.get(ancestor);
+            if (found !== undefined)
+                return found;
+            if (node_path_1.default.dirname(ancestor) === ancestor)
+                break;
+        }
+        const displaced = [...(this.descendants.get(directory) ?? [])];
+        const 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();
+        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;
+    }
+    close(watch) {
+        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);
+    }
+    registerStream(stream) {
+        this.streams.set(stream.root, stream);
+        for (const ancestor of strictAncestors(stream.root)) {
+            const descendants = this.descendants.get(ancestor) ?? new Set();
+            descendants.add(stream);
+            this.descendants.set(ancestor, descendants);
+        }
+    }
+    unregisterStream(stream) {
+        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);
+        }
+    }
+}
+exports.FseventsStreams = FseventsStreams;
+/** 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, watch) {
+    const watches = stream.watches.get(watch.directory) ?? new Set();
+    watches.add(watch);
+    watch.stream = stream;
+    stream.watches.set(watch.directory, watches);
+}
+function stopStream(stream) {
+    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, file, flags) {
+    if (!stream.active)
+        return;
+    if ((flags & GAP) !== 0) {
+        deliverGap(stream);
+        return;
+    }
+    const target = node_path_1.default.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 = [];
+    let directory = node_path_1.default.dirname(target);
+    let depth = 0;
+    while (isWithin(stream.root, directory)) {
+        const watches = stream.watches.get(directory);
+        if (watches !== undefined) {
+            const name = node_path_1.default.relative(directory, target);
+            for (const watch of watches) {
+                if (depth === 0 || watch.recursive) {
+                    deliveries.push({ name, watch });
+                }
+            }
+        }
+        const parent = node_path_1.default.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) {
+    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) {
+    let ancestor = node_path_1.default.dirname(location);
+    while (ancestor !== location) {
+        yield ancestor;
+        const parent = node_path_1.default.dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+}
+function isWithin(parent, child) {
+    const relative = node_path_1.default.relative(parent, child);
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${node_path_1.default.sep}`) &&
+            !node_path_1.default.isAbsolute(relative)));
+}
+//# sourceMappingURL=FseventsStreams.js.map

package/lib/launcher/internal/watch/FseventsStreams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FseventsStreams.js","sourceRoot":"","sources":["../../../../src/launcher/internal/watch/FseventsStreams.ts"],"names":[],"mappings":"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"}

package/lib/launcher/internal/watch/ProjectInputWatchRules.d.ts

@@ -0,0 +1,92 @@
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+/**
+ * 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 declare 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.
+     */
+    function isCompilerEmittableSourceExtension(extension: string): boolean;
+    /**
+     * 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.
+     */
+    function projectInputRecursiveWatchRoot(target: string, projectRoot: string, identities?: import("../../../internal/projectInputPathIdentity").FilesystemPathIdentityContext): string | 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.
+     */
+    function projectInputAnchorsDeclaration(snapshot: ITtscProjectInputSnapshot, directory: string, identities: ProjectInputPathIdentityContext): boolean;
+    /**
+     * 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.
+     */
+    function projectInputPathMayAffectProgram(location: string): boolean;
+}

package/lib/launcher/internal/watch/ProjectInputWatchRules.js

@@ -0,0 +1,163 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectInputWatchRules = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const createProjectInputPathIdentityContext_1 = require("../../../internal/pathIdentity/createProjectInputPathIdentityContext");
+const WatchPaths_1 = require("./WatchPaths");
+const literalGlobRoot_1 = require("./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.
+ */
+var ProjectInputWatchRules;
+(function (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.
+     */
+    function isCompilerEmittableSourceExtension(extension) {
+        return [
+            ".cjs",
+            ".cts",
+            ".js",
+            ".jsx",
+            ".mjs",
+            ".mts",
+            ".ts",
+            ".tsx",
+        ].includes(extension);
+    }
+    ProjectInputWatchRules.isCompilerEmittableSourceExtension = isCompilerEmittableSourceExtension;
+    /**
+     * 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.
+     */
+    function projectInputRecursiveWatchRoot(target, projectRoot, identities = (0, createProjectInputPathIdentityContext_1.createProjectInputPathIdentityContext)()) {
+        const resolvedTarget = node_path_1.default.resolve(target);
+        const resolvedProjectRoot = node_path_1.default.resolve(projectRoot);
+        if (identities.isWithin(resolvedProjectRoot, resolvedTarget)) {
+            return WatchPaths_1.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_1.WatchPaths.nearestExistingDirectory(node_path_1.default.dirname(resolvedTarget)),
+            WatchPaths_1.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;
+    }
+    ProjectInputWatchRules.projectInputRecursiveWatchRoot = projectInputRecursiveWatchRoot;
+    /**
+     * 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.
+     */
+    function projectInputAnchorsDeclaration(snapshot, directory, identities) {
+        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, (0, literalGlobRoot_1.literalGlobRoot)(glob))));
+    }
+    ProjectInputWatchRules.projectInputAnchorsDeclaration = projectInputAnchorsDeclaration;
+    /**
+     * 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.
+     */
+    function projectInputPathMayAffectProgram(location) {
+        const extension = node_path_1.default.extname(location).toLowerCase();
+        return (extension === ".json" || isCompilerEmittableSourceExtension(extension));
+    }
+    ProjectInputWatchRules.projectInputPathMayAffectProgram = projectInputPathMayAffectProgram;
+})(ProjectInputWatchRules || (exports.ProjectInputWatchRules = ProjectInputWatchRules = {}));
+//# sourceMappingURL=ProjectInputWatchRules.js.map