@karmaniverous/jeeves-watcher 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -15,6 +15,7 @@ declare const watchConfigSchema: z.ZodObject<{
     usePolling: z.ZodOptional<z.ZodBoolean>;
     debounceMs: z.ZodOptional<z.ZodNumber>;
     stabilityThresholdMs: z.ZodOptional<z.ZodNumber>;
+    respectGitignore: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Watch configuration for file system monitoring paths, ignore patterns, and debounce/stability settings. */
 type WatchConfig = z.infer<typeof watchConfigSchema>;
@@ -91,6 +92,7 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         usePolling: z.ZodOptional<z.ZodBoolean>;
         debounceMs: z.ZodOptional<z.ZodNumber>;
         stabilityThresholdMs: z.ZodOptional<z.ZodNumber>;
+        respectGitignore: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     configWatch: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -128,6 +130,8 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         file: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    maxBackoffMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /** Top-level jeeves-watcher configuration: watch paths, embedding, vector store, rules, maps, API, and logging. */
 type JeevesWatcherConfig = z.infer<typeof jeevesWatcherConfigSchema>;
@@ -541,6 +545,114 @@ declare function createApiServer(options: ApiServerOptions): FastifyInstance;
  */
 declare function createLogger(config?: LoggingConfig): pino.Logger;
 
+/**
+ * @module gitignore
+ * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
+ */
+/**
+ * Processor-level gitignore filter. Checks file paths against the nearest
+ * `.gitignore` chain in git repositories.
+ */
+declare class GitignoreFilter {
+    private repos;
+    /**
+     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
+     *
+     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
+     */
+    constructor(watchPaths: string[]);
+    /**
+     * Scan paths for git repos and their `.gitignore` files.
+     */
+    private scan;
+    /**
+     * Check whether a file path is ignored by any applicable `.gitignore`.
+     *
+     * @param filePath - Absolute file path to check.
+     * @returns `true` if the file should be ignored.
+     */
+    isIgnored(filePath: string): boolean;
+    /**
+     * Invalidate and re-parse a specific `.gitignore` file.
+     * Call when a `.gitignore` file is added, changed, or removed.
+     *
+     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
+     */
+    invalidate(gitignorePath: string): void;
+}
+
+/**
+ * @module health
+ * Tracks consecutive system-level failures and applies exponential backoff.
+ * Triggers fatal error callback when maxRetries is exceeded.
+ */
+
+/**
+ * Options for {@link SystemHealth}.
+ */
+interface SystemHealthOptions {
+    /** Maximum consecutive failures before fatal. Default: Infinity. */
+    maxRetries?: number;
+    /** Maximum backoff delay in milliseconds. Default: 60000. */
+    maxBackoffMs?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 1000. */
+    baseDelayMs?: number;
+    /** Called when maxRetries is exceeded. If not set, throws. */
+    onFatalError?: (error: unknown) => void;
+    /** Logger instance. */
+    logger: pino.Logger;
+}
+/**
+ * Tracks system health via consecutive failure count and exponential backoff.
+ */
+declare class SystemHealth {
+    private consecutiveFailures;
+    private readonly maxRetries;
+    private readonly maxBackoffMs;
+    private readonly baseDelayMs;
+    private readonly onFatalError?;
+    private readonly logger;
+    constructor(options: SystemHealthOptions);
+    /**
+     * Record a successful system operation. Resets the failure counter.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a system-level failure. If maxRetries is exceeded, triggers fatal error.
+     *
+     * @param error - The error that occurred.
+     * @returns Whether the watcher should continue (false = fatal).
+     */
+    recordFailure(error: unknown): boolean;
+    /**
+     * Compute the current backoff delay based on consecutive failures.
+     *
+     * @returns Delay in milliseconds.
+     */
+    get currentBackoffMs(): number;
+    /**
+     * Sleep for the current backoff duration.
+     *
+     * @param signal - Optional abort signal.
+     */
+    backoff(signal?: AbortSignal): Promise<void>;
+    /** Current consecutive failure count. */
+    get failures(): number;
+}
+
+/**
+ * Options for {@link FileSystemWatcher} beyond basic config.
+ */
+interface FileSystemWatcherOptions {
+    /** Maximum consecutive system-level failures before fatal error. */
+    maxRetries?: number;
+    /** Maximum backoff delay in milliseconds for system errors. */
+    maxBackoffMs?: number;
+    /** Callback invoked on unrecoverable system error. If not set, throws. */
+    onFatalError?: (error: unknown) => void;
+    /** Optional gitignore filter for processor-level filtering. */
+    gitignoreFilter?: GitignoreFilter;
+}
 /**
  * Filesystem watcher that maps chokidar events to the processing queue.
  */
@@ -549,6 +661,8 @@ declare class FileSystemWatcher {
     private readonly queue;
     private readonly processor;
     private readonly logger;
+    private readonly health;
+    private readonly gitignoreFilter?;
     private watcher;
     /**
      * Create a new FileSystemWatcher.
@@ -557,8 +671,9 @@ declare class FileSystemWatcher {
      * @param queue - The event queue.
      * @param processor - The document processor.
      * @param logger - The logger instance.
+     * @param options - Optional health/fatal error options.
      */
-    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger);
+    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger, options?: FileSystemWatcherOptions);
     /**
      * Start watching the filesystem and processing events.
      */
@@ -567,6 +682,24 @@ declare class FileSystemWatcher {
      * Stop the filesystem watcher.
      */
     stop(): Promise<void>;
+    /**
+     * Get the system health tracker.
+     */
+    get systemHealth(): SystemHealth;
+    /**
+     * Check if a path is gitignored and should be skipped.
+     */
+    private isGitignored;
+    /**
+     * If the changed file is a `.gitignore`, invalidate the filter cache.
+     */
+    private handleGitignoreChange;
+    /**
+     * Wrap a processing operation with health tracking.
+     * On success, resets the failure counter.
+     * On failure, records the failure and applies backoff.
+     */
+    private wrapProcessing;
 }
 
 /**
@@ -588,10 +721,20 @@ interface JeevesWatcherFactories {
     /** Create an event queue for batching file-system events. */
     createEventQueue: (options: ConstructorParameters<typeof EventQueue>[0]) => EventQueue;
     /** Create a file-system watcher for the configured watch paths. */
-    createFileSystemWatcher: (config: JeevesWatcherConfig['watch'], queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger) => FileSystemWatcher;
+    createFileSystemWatcher: (config: JeevesWatcherConfig['watch'], queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger, options?: FileSystemWatcherOptions) => FileSystemWatcher;
     /** Create the HTTP API server. */
     createApiServer: typeof createApiServer;
 }
+/**
+ * Main application class that wires together all components.
+ */
+/**
+ * Runtime options for {@link JeevesWatcher} that aren't serializable in config.
+ */
+interface JeevesWatcherRuntimeOptions {
+    /** Callback invoked on unrecoverable system error. If not set, throws. */
+    onFatalError?: (error: unknown) => void;
+}
 /**
  * Main application class that wires together all components.
  */
@@ -599,6 +742,7 @@ declare class JeevesWatcher {
     private config;
     private readonly configPath?;
     private readonly factories;
+    private readonly runtimeOptions;
     private logger;
     private watcher;
     private queue;
@@ -611,8 +755,9 @@ declare class JeevesWatcher {
      * @param config - The application configuration.
      * @param configPath - Optional config file path to watch for changes.
      * @param factories - Optional component factories (for dependency injection).
+     * @param runtimeOptions - Optional runtime-only options (e.g., onFatalError).
      */
-    constructor(config: JeevesWatcherConfig, configPath?: string, factories?: Partial<JeevesWatcherFactories>);
+    constructor(config: JeevesWatcherConfig, configPath?: string, factories?: Partial<JeevesWatcherFactories>, runtimeOptions?: JeevesWatcherRuntimeOptions);
     /**
      * Start the watcher, API server, and all components.
      */
@@ -716,5 +861,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, JeevesWatcher, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loggingConfigSchema, metadataPath, pointId, readMetadata, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
-export type { ApiConfig, ApiServerOptions, CompiledRule, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, LoggingConfig, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };
+export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loggingConfigSchema, metadataPath, pointId, readMetadata, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
+export type { ApiConfig, ApiServerOptions, CompiledRule, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, FileSystemWatcherOptions, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };