@jamesaphoenix/tx-core 0.4.1

package/dist/services/file-watcher-service.js

@@ -0,0 +1,278 @@
+import { Context, Effect, Layer, Queue } from "effect";
+import { FileWatcherError, WatcherAlreadyRunningError, WatcherNotRunningError } from "../errors.js";
+/**
+ * FileWatcherService watches file system paths and emits events when files are
+ * added, changed, or deleted. Events are delivered via an Effect Queue for
+ * decoupled, backpressure-aware processing.
+ *
+ * Used by the telemetry daemon to watch Claude Code transcript files
+ * (~/.claude/projects/** /*.jsonl) and trigger the learning extraction pipeline.
+ *
+ * See DD-015 for the full architecture.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const watcher = yield* FileWatcherService
+ *   const eventQueue = yield* watcher.getEventQueue()
+ *
+ *   // Start watching
+ *   yield* watcher.start({
+ *     patterns: ["~/.claude/projects/** /*.jsonl"],
+ *     debounceMs: 2000
+ *   })
+ *
+ *   // Process events
+ *   while (true) {
+ *     const event = yield* Queue.take(eventQueue)
+ *     yield* Effect.log(`File ${event.type}: ${event.path}`)
+ *   }
+ * })
+ * ```
+ */
+export class FileWatcherService extends Context.Tag("FileWatcherService")() {
+}
+/**
+ * No-op implementation for testing or when file watching is disabled.
+ * All operations succeed but no actual watching occurs.
+ */
+export const FileWatcherServiceNoop = Layer.scoped(FileWatcherService, Effect.gen(function* () {
+    // Create a dummy queue that will never receive events
+    const eventQueue = yield* Queue.unbounded();
+    return {
+        start: () => Effect.void,
+        stop: () => Effect.void,
+        isRunning: () => Effect.succeed(false),
+        getWatchedPaths: () => Effect.succeed([]),
+        getEventQueue: () => Effect.succeed(eventQueue),
+        status: () => Effect.succeed({
+            running: false,
+            watchedPaths: [],
+            startedAt: null,
+            eventsProcessed: 0
+        })
+    };
+}));
+/**
+ * Expand tilde (~) to the user's home directory.
+ */
+const expandTilde = (path) => {
+    const { homedir } = require("node:os");
+    return path.startsWith("~") ? path.replace(/^~/, homedir()) : path;
+};
+/**
+ * Extract the base directory from a glob pattern.
+ * For "~/.claude/projects/** /*.jsonl", returns the expanded "~/.claude/projects".
+ * For paths without globs, returns the path as-is.
+ */
+const extractBaseDir = (pattern) => {
+    const expanded = expandTilde(pattern);
+    const firstGlobIndex = expanded.search(/[*?[\]{}]/);
+    if (firstGlobIndex === -1) {
+        return expanded;
+    }
+    // Find the last path separator before the first glob character
+    const beforeGlob = expanded.slice(0, firstGlobIndex);
+    const lastSep = Math.max(beforeGlob.lastIndexOf("/"), beforeGlob.lastIndexOf("\\"));
+    return lastSep > 0 ? expanded.slice(0, lastSep) : expanded;
+};
+/**
+ * Check if a file path matches a glob-like pattern.
+ * Simple implementation supporting:
+ * - ** for any directory depth
+ * - * for any characters in a filename
+ */
+const matchesPattern = (filePath, pattern) => {
+    const expanded = expandTilde(pattern);
+    // If no glob characters, just check if the path starts with the pattern
+    if (!/[*?[\]{}]/.test(expanded)) {
+        return filePath.startsWith(expanded);
+    }
+    // Convert glob pattern to regex
+    // Escape special regex chars except * and ?
+    let regexStr = expanded
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "<<<GLOBSTAR>>>")
+        .replace(/\*/g, "[^/\\\\]*")
+        .replace(/<<<GLOBSTAR>>>/g, ".*")
+        .replace(/\?/g, ".");
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(filePath);
+};
+/**
+ * Live implementation of FileWatcherService using chokidar.
+ *
+ * Features:
+ * - Uses chokidar for cross-platform file watching
+ * - awaitWriteFinish with 2000ms debounce for chunked writes
+ * - persistent mode to keep process running
+ * - ignoreInitial: false to emit events for existing files
+ * - Effect Queue for backpressure-aware event buffering
+ * - Supports glob patterns (expands ~ and extracts base directories)
+ */
+export const FileWatcherServiceLive = Layer.scoped(FileWatcherService, Effect.gen(function* () {
+    const chokidar = yield* Effect.tryPromise({
+        try: () => import("chokidar"),
+        catch: (error) => new FileWatcherError({
+            reason: "Failed to import chokidar",
+            cause: error
+        })
+    });
+    // Create the event queue for delivering file events
+    const eventQueue = yield* Queue.unbounded();
+    // Mutable state using Effect Ref
+    const stateRef = yield* Effect.sync(() => ({
+        current: {
+            running: false,
+            watcher: null,
+            watchedPaths: [],
+            startedAt: null,
+            eventsProcessed: 0
+        }
+    }));
+    const getState = () => stateRef.current;
+    const setState = (updater) => {
+        stateRef.current = updater(stateRef.current);
+    };
+    // Cleanup on scope finalization
+    yield* Effect.addFinalizer(() => Effect.gen(function* () {
+        const state = getState();
+        if (state.watcher) {
+            yield* Effect.tryPromise({
+                try: () => state.watcher.close(),
+                catch: () => new Error("cleanup") // Error will be ignored
+            }).pipe(Effect.ignore);
+        }
+    }));
+    const start = (config) => Effect.gen(function* () {
+        const state = getState();
+        if (state.running) {
+            return yield* Effect.fail(new WatcherAlreadyRunningError({
+                path: state.watchedPaths.join(", ")
+            }));
+        }
+        // Extract base directories from glob patterns
+        const expandedPaths = config.patterns.map((p) => expandTilde(p));
+        const baseDirs = [...new Set(config.patterns.map(extractBaseDir))];
+        // Store original patterns for filtering
+        const originalPatterns = config.patterns;
+        // Configure chokidar options
+        const debounceMs = config.debounceMs ?? 2000;
+        const watcherOptions = {
+            persistent: true,
+            ignoreInitial: config.ignoreInitial ?? false,
+            awaitWriteFinish: {
+                stabilityThreshold: debounceMs,
+                pollInterval: Math.min(100, debounceMs / 10)
+            },
+            // Use polling interval if specified
+            ...(config.pollInterval && {
+                usePolling: true,
+                interval: config.pollInterval
+            })
+        };
+        // Create the watcher
+        const watcher = yield* Effect.try({
+            try: () => chokidar.watch(baseDirs, watcherOptions),
+            catch: (error) => new FileWatcherError({
+                reason: "Failed to create chokidar watcher",
+                cause: error
+            })
+        });
+        // Set up event handlers
+        const handleEvent = (type, path) => {
+            // Check if the path matches any of our patterns
+            const matches = originalPatterns.some((pattern) => matchesPattern(path, pattern));
+            if (!matches)
+                return;
+            const event = {
+                type,
+                path,
+                timestamp: new Date()
+            };
+            // Offer event to queue (non-blocking)
+            Effect.runFork(Queue.offer(eventQueue, event).pipe(Effect.tap(() => Effect.sync(() => {
+                setState((s) => ({ ...s, eventsProcessed: s.eventsProcessed + 1 }));
+            }))));
+        };
+        watcher.on("add", (path) => handleEvent("add", path));
+        watcher.on("change", (path) => handleEvent("change", path));
+        watcher.on("unlink", (path) => handleEvent("delete", path));
+        watcher.on("error", (error) => {
+            // Log errors but don't crash - fire and forget error reporting
+            Effect.runFork(Effect.logWarning(`File watcher error: ${error}`));
+        });
+        // Wait for the ready event
+        yield* Effect.async((resume) => {
+            const timeout = setTimeout(() => {
+                resume(Effect.fail(new FileWatcherError({
+                    reason: "Watcher did not become ready within timeout"
+                })));
+            }, 30000); // 30 second timeout
+            watcher.once("ready", () => {
+                clearTimeout(timeout);
+                resume(Effect.void);
+            });
+            watcher.once("error", (error) => {
+                clearTimeout(timeout);
+                resume(Effect.fail(new FileWatcherError({
+                    reason: "Watcher failed during initialization",
+                    cause: error
+                })));
+            });
+        });
+        // Update state
+        setState(() => ({
+            running: true,
+            watcher,
+            watchedPaths: expandedPaths,
+            startedAt: new Date(),
+            eventsProcessed: 0
+        }));
+    });
+    const stop = () => Effect.gen(function* () {
+        const state = getState();
+        if (!state.running || !state.watcher) {
+            return yield* Effect.fail(new WatcherNotRunningError({
+                path: "no active watcher"
+            }));
+        }
+        // Close the watcher
+        yield* Effect.tryPromise({
+            try: () => state.watcher.close(),
+            catch: (error) => new FileWatcherError({
+                reason: "Failed to close chokidar watcher",
+                cause: error
+            })
+        });
+        // Update state
+        setState(() => ({
+            running: false,
+            watcher: null,
+            watchedPaths: [],
+            startedAt: null,
+            eventsProcessed: 0
+        }));
+    });
+    const isRunning = () => Effect.sync(() => getState().running);
+    const getWatchedPaths = () => Effect.sync(() => getState().watchedPaths);
+    const getEventQueue = () => Effect.succeed(eventQueue);
+    const status = () => Effect.sync(() => {
+        const state = getState();
+        return {
+            running: state.running,
+            watchedPaths: state.watchedPaths,
+            startedAt: state.startedAt,
+            eventsProcessed: state.eventsProcessed
+        };
+    });
+    return {
+        start,
+        stop,
+        isRunning,
+        getWatchedPaths,
+        getEventQueue,
+        status
+    };
+}));
+//# sourceMappingURL=file-watcher-service.js.map

package/dist/services/file-watcher-service.js.map

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

package/dist/services/graph-expansion.d.ts

@@ -0,0 +1,155 @@
+import { Context, Effect, Layer } from "effect";
+import { EdgeService } from "./edge-service.js";
+import { LearningRepository } from "../repo/learning-repo.js";
+import { AnchorRepository } from "../repo/anchor-repo.js";
+import { DatabaseError, ValidationError } from "../errors.js";
+import type { Learning, EdgeType, LearningId } from "@jamesaphoenix/tx-types";
+/**
+ * Seed learning with an initial score for graph expansion.
+ * Typically the RRF score from hybrid search.
+ */
+export interface SeedLearning {
+    readonly learning: Learning;
+    readonly score: number;
+}
+/**
+ * Expanded learning with graph traversal metadata.
+ */
+export interface ExpandedLearning {
+    readonly learning: Learning;
+    /** Number of hops from the nearest seed (0 = direct seed) */
+    readonly hops: number;
+    /** Score after applying weight decay per hop */
+    readonly decayedScore: number;
+    /** Path of learning IDs from seed to this learning */
+    readonly path: readonly LearningId[];
+    /** Edge type that connected this learning (null for seeds) */
+    readonly sourceEdge: EdgeType | null;
+    /** The edge weight that led to this learning (null for seeds) */
+    readonly edgeWeight: number | null;
+}
+/**
+ * Filter configuration for edge types during graph traversal.
+ * Supports include/exclude lists and per-hop overrides.
+ */
+export interface EdgeTypeFilter {
+    /** Only traverse these edge types (mutually exclusive with exclude for same types) */
+    readonly include?: readonly EdgeType[];
+    /** Traverse all edge types except these (mutually exclusive with include for same types) */
+    readonly exclude?: readonly EdgeType[];
+    /** Depth-specific filter overrides (1-indexed, matching hop number) */
+    readonly perHop?: Readonly<Record<number, EdgeTypeFilter>>;
+}
+/**
+ * Options for graph expansion algorithm.
+ */
+export interface GraphExpansionOptions {
+    /** Maximum traversal depth (default: 2) */
+    readonly depth?: number;
+    /** Score decay factor per hop (default: 0.7) */
+    readonly decayFactor?: number;
+    /** Maximum nodes to return (default: 100) */
+    readonly maxNodes?: number;
+    /** Filter by specific edge types (default: all types).
+     * Accepts either a simple array for backwards compatibility or EdgeTypeFilter for advanced filtering. */
+    readonly edgeTypes?: EdgeTypeFilter | readonly EdgeType[];
+}
+/**
+ * Result of graph expansion operation.
+ */
+export interface GraphExpansionResult {
+    /** Seeds that were provided as input */
+    readonly seeds: readonly ExpandedLearning[];
+    /** Learnings discovered through graph expansion (excludes seeds) */
+    readonly expanded: readonly ExpandedLearning[];
+    /** Total learnings (seeds + expanded) */
+    readonly all: readonly ExpandedLearning[];
+    /** Statistics about the expansion */
+    readonly stats: {
+        readonly seedCount: number;
+        readonly expandedCount: number;
+        readonly maxDepthReached: number;
+        readonly nodesVisited: number;
+    };
+}
+/**
+ * Options for file-based graph expansion.
+ * Expands from files via IMPORTS and CO_CHANGES_WITH edges to find related learnings.
+ * See PRD-016 for specification.
+ */
+export interface FileExpansionOptions {
+    /** Maximum traversal depth for file relationships (default: 2) */
+    readonly depth?: number;
+    /** Score decay factor per hop (default: 0.7) */
+    readonly decayFactor?: number;
+    /** Maximum learnings to return (default: 100) */
+    readonly maxNodes?: number;
+}
+/**
+ * A learning discovered through file-based graph expansion.
+ * Contains metadata about how the learning was found via file relationships.
+ */
+export interface FileExpandedLearning {
+    readonly learning: Learning;
+    /** The source file path that led to this learning */
+    readonly sourceFile: string;
+    /** Number of hops from the source file (0 = directly anchored to input file) */
+    readonly hops: number;
+    /** Score after applying weight decay per hop */
+    readonly decayedScore: number;
+    /** Edge type that connected this learning (ANCHORED_TO for direct, IMPORTS or CO_CHANGES_WITH for expanded) */
+    readonly sourceEdge: EdgeType;
+    /** Edge weight (null for directly anchored learnings, weight value for IMPORTS/CO_CHANGES_WITH) */
+    readonly edgeWeight: number | null;
+}
+/**
+ * Result of file-based graph expansion operation.
+ */
+export interface FileExpansionResult {
+    /** Learnings directly anchored to the input files (hop 0) */
+    readonly anchored: readonly FileExpandedLearning[];
+    /** Learnings discovered through file expansion (hops > 0 via IMPORTS/CO_CHANGES_WITH) */
+    readonly expanded: readonly FileExpandedLearning[];
+    /** All learnings (anchored + expanded), sorted by decayedScore */
+    readonly all: readonly FileExpandedLearning[];
+    /** Statistics about the expansion */
+    readonly stats: {
+        readonly inputFileCount: number;
+        readonly anchoredCount: number;
+        readonly expandedCount: number;
+        readonly maxDepthReached: number;
+        readonly filesVisited: number;
+    };
+}
+declare const GraphExpansionService_base: Context.TagClass<GraphExpansionService, "GraphExpansionService", {
+    /**
+     * Expand from seed learnings through the knowledge graph.
+     * Uses BFS traversal with weight decay per hop.
+     * Bidirectional traversal (both incoming and outgoing edges).
+     *
+     * @param seeds - Learnings to start expansion from, with initial scores
+     * @param options - Expansion configuration (depth, decay, limits)
+     * @returns Seeds and expanded learnings with traversal metadata
+     */
+    readonly expand: (seeds: readonly SeedLearning[], options?: GraphExpansionOptions) => Effect.Effect<GraphExpansionResult, ValidationError | DatabaseError>;
+    /**
+     * Expand from file paths to find related learnings.
+     * First finds learnings ANCHORED_TO the input files, then expands via
+     * IMPORTS and CO_CHANGES_WITH edges to find learnings anchored to related files.
+     *
+     * @param files - File paths to expand from (e.g., ["src/auth.ts", "src/jwt.ts"])
+     * @param options - Expansion configuration (depth, decay, limits)
+     * @returns Anchored and expanded learnings with file relationship metadata
+     */
+    readonly expandFromFiles: (files: readonly string[], options?: FileExpansionOptions) => Effect.Effect<FileExpansionResult, ValidationError | DatabaseError>;
+}>;
+export declare class GraphExpansionService extends GraphExpansionService_base {
+}
+/**
+ * Noop implementation that returns seeds without expansion.
+ * Used when graph expansion is disabled or for testing.
+ */
+export declare const GraphExpansionServiceNoop: Layer.Layer<GraphExpansionService, never, never>;
+export declare const GraphExpansionServiceLive: Layer.Layer<GraphExpansionService, never, LearningRepository | AnchorRepository | EdgeService>;
+export {};
+//# sourceMappingURL=graph-expansion.d.ts.map

package/dist/services/graph-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-expansion.d.ts","sourceRoot":"","sources":["../../src/services/graph-expansion.ts"],"names":[],"mappings":"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"}