@karmaniverous/jeeves-watcher 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -159,6 +159,11 @@ interface EmbeddingProvider {
  */
 declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger): EmbeddingProvider;
 
+/**
+ * @module rules/attributes
+ * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
+ */
+
 /**
  * Attributes derived from a watched file for rule matching.
  */
@@ -183,15 +188,6 @@ interface FileAttributes {
     /** Parsed JSON content, if any. */
     json?: Record<string, unknown>;
 }
-/**
- * A compiled inference rule ready for evaluation.
- */
-interface CompiledRule {
-    /** The original rule definition. */
-    rule: InferenceRule;
-    /** The compiled ajv validate function. */
-    validate: (data: unknown) => boolean;
-}
 /**
  * Build {@link FileAttributes} from a file path and stat info.
  *
@@ -202,6 +198,21 @@ interface CompiledRule {
  * @returns The constructed file attributes.
  */
 declare function buildAttributes(filePath: string, stats: Stats, extractedFrontmatter?: Record<string, unknown>, extractedJson?: Record<string, unknown>): FileAttributes;
+
+/**
+ * @module rules/compile
+ * Compiles inference rule definitions into executable AJV validators for efficient rule evaluation.
+ */
+
+/**
+ * A compiled inference rule ready for evaluation.
+ */
+interface CompiledRule {
+    /** The original rule definition. */
+    rule: InferenceRule;
+    /** The compiled AJV validate function. */
+    validate: (data: unknown) => boolean;
+}
 /**
  * Compile an array of inference rules into executable validators.
  *
@@ -209,6 +220,19 @@ declare function buildAttributes(filePath: string, stats: Stats, extractedFrontm
  * @returns An array of compiled rules.
  */
 declare function compileRules(rules: InferenceRule[]): CompiledRule[];
+
+/**
+ * @module rules/apply
+ * Applies compiled inference rules to file attributes, producing merged metadata via template resolution and JsonMap transforms.
+ */
+
+/**
+ * A minimal logger interface for rule application warnings.
+ */
+interface RuleLogger {
+    /** Log a warning message during rule application. */
+    warn(msg: string): void;
+}
 /**
  * Apply compiled inference rules to file attributes, returning merged metadata.
  *
@@ -219,10 +243,10 @@ declare function compileRules(rules: InferenceRule[]): CompiledRule[];
  * @param compiledRules - The compiled rules to evaluate.
  * @param attributes - The file attributes to match against.
  * @param namedMaps - Optional record of named JsonMap definitions.
- * @param logger - Optional pino logger for warnings (falls back to console.warn).
+ * @param logger - Optional logger for warnings (falls back to console.warn).
  * @returns The merged metadata from all matching rules.
  */
-declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: pino.Logger): Promise<Record<string, unknown>>;
+declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger): Promise<Record<string, unknown>>;
 
 /**
  * A point to upsert into the vector store.
@@ -262,7 +286,7 @@ declare class VectorStoreClient {
     private readonly client;
     private readonly collectionName;
     private readonly dims;
-    private readonly logger?;
+    private readonly log;
     /**
      * Create a new VectorStoreClient.
      *
@@ -504,26 +528,91 @@ interface ApiServerOptions {
  */
 declare function createApiServer(options: ApiServerOptions): FastifyInstance;
 
+/**
+ * @module logger
+ * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
+ */
+
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logging configuration.
+ * @returns A configured pino logger.
+ */
+declare function createLogger(config?: LoggingConfig): pino.Logger;
+
+/**
+ * Filesystem watcher that maps chokidar events to the processing queue.
+ */
+declare class FileSystemWatcher {
+    private readonly config;
+    private readonly queue;
+    private readonly processor;
+    private readonly logger;
+    private watcher;
+    /**
+     * Create a new FileSystemWatcher.
+     *
+     * @param config - Watch configuration.
+     * @param queue - The event queue.
+     * @param processor - The document processor.
+     * @param logger - The logger instance.
+     */
+    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger);
+    /**
+     * Start watching the filesystem and processing events.
+     */
+    start(): void;
+    /**
+     * Stop the filesystem watcher.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Component factories for {@link JeevesWatcher}. Override in tests to inject mocks.
+ */
+interface JeevesWatcherFactories {
+    /** Load and validate a {@link JeevesWatcherConfig} from disk. */
+    loadConfig: (configPath?: string) => Promise<JeevesWatcherConfig>;
+    /** Create a pino logger instance. */
+    createLogger: typeof createLogger;
+    /** Create an embedding provider from config. */
+    createEmbeddingProvider: typeof createEmbeddingProvider;
+    /** Create a vector-store client for similarity search and upsert. */
+    createVectorStoreClient: (config: JeevesWatcherConfig['vectorStore'], dimensions: number, logger: pino.Logger) => VectorStoreClient;
+    /** Compile inference rules from config. */
+    compileRules: typeof compileRules;
+    /** Create a document processor for file ingestion. */
+    createDocumentProcessor: (config: ConstructorParameters<typeof DocumentProcessor>[0], embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: ConstructorParameters<typeof DocumentProcessor>[3], logger: pino.Logger) => DocumentProcessor;
+    /** 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;
+    /** Create the HTTP API server. */
+    createApiServer: typeof createApiServer;
+}
 /**
  * Main application class that wires together all components.
  */
 declare class JeevesWatcher {
     private config;
     private readonly configPath?;
+    private readonly factories;
     private logger;
     private watcher;
     private queue;
     private server;
     private processor;
     private configWatcher;
-    private configDebounce;
     /**
      * Create a new JeevesWatcher instance.
      *
      * @param config - The application configuration.
      * @param configPath - Optional config file path to watch for changes.
+     * @param factories - Optional component factories (for dependency injection).
      */
-    constructor(config: JeevesWatcherConfig, configPath?: string);
+    constructor(config: JeevesWatcherConfig, configPath?: string, factories?: Partial<JeevesWatcherFactories>);
     /**
      * Start the watcher, API server, and all components.
      */
@@ -586,19 +675,6 @@ declare function extractText(filePath: string, extension: string): Promise<Extra
  */
 declare function contentHash(text: string): string;
 
-/**
- * @module logger
- * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
- */
-
-/**
- * Create a pino logger instance.
- *
- * @param config - Optional logging configuration.
- * @returns A configured pino logger.
- */
-declare function createLogger(config?: LoggingConfig): pino.Logger;
-
 /**
  * Derive a deterministic `.meta.json` path for a given file.
  *
@@ -640,33 +716,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-/**
- * Filesystem watcher that maps chokidar events to the processing queue.
- */
-declare class FileSystemWatcher {
-    private readonly config;
-    private readonly queue;
-    private readonly processor;
-    private readonly logger;
-    private watcher;
-    /**
-     * Create a new FileSystemWatcher.
-     *
-     * @param config - Watch configuration.
-     * @param queue - The event queue.
-     * @param processor - The document processor.
-     * @param logger - The logger instance.
-     */
-    constructor(config: WatchConfig, queue: EventQueue, processor: DocumentProcessor, logger: pino.Logger);
-    /**
-     * Start watching the filesystem and processing events.
-     */
-    start(): void;
-    /**
-     * Stop the filesystem watcher.
-     */
-    stop(): Promise<void>;
-}
-
 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, LoggingConfig, ProcessFn, ProcessorConfig, ScrolledPoint, SearchResult, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };
+export type { ApiConfig, ApiServerOptions, CompiledRule, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, LoggingConfig, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };