@zipbul/gildash 0.7.0 → 0.8.1

package/dist/migrations/0005_instance_id_covering_index.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `watcher_owner` ADD COLUMN `instance_id` text;--> statement-breakpoint
+CREATE INDEX `idx_relations_project_type_src` ON `relations` (`project`,`type`,`src_file_path`);

package/dist/migrations/meta/0005_snapshot.json

@@ -0,0 +1,445 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "prevId": "4792483b-0af0-4775-a2df-c04b8066770e",
+  "tables": {
+    "files": {
+      "name": "files",
+      "columns": {
+        "project": {
+          "name": "project",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "file_path": {
+          "name": "file_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mtime_ms": {
+          "name": "mtime_ms",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content_hash": {
+          "name": "content_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "line_count": {
+          "name": "line_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "files_project_file_path_pk": {
+          "columns": [
+            "project",
+            "file_path"
+          ],
+          "name": "files_project_file_path_pk"
+        }
+      },
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "relations": {
+      "name": "relations",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "project": {
+          "name": "project",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "src_file_path": {
+          "name": "src_file_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "src_symbol_name": {
+          "name": "src_symbol_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "dst_project": {
+          "name": "dst_project",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "dst_file_path": {
+          "name": "dst_file_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "dst_symbol_name": {
+          "name": "dst_symbol_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "meta_json": {
+          "name": "meta_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_relations_src": {
+          "name": "idx_relations_src",
+          "columns": [
+            "project",
+            "src_file_path"
+          ],
+          "isUnique": false
+        },
+        "idx_relations_dst": {
+          "name": "idx_relations_dst",
+          "columns": [
+            "dst_project",
+            "dst_file_path"
+          ],
+          "isUnique": false
+        },
+        "idx_relations_type": {
+          "name": "idx_relations_type",
+          "columns": [
+            "project",
+            "type"
+          ],
+          "isUnique": false
+        },
+        "idx_relations_project_type_src": {
+          "name": "idx_relations_project_type_src",
+          "columns": [
+            "project",
+            "type",
+            "src_file_path"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "relations_project_src_file_path_files_project_file_path_fk": {
+          "name": "relations_project_src_file_path_files_project_file_path_fk",
+          "tableFrom": "relations",
+          "tableTo": "files",
+          "columnsFrom": [
+            "project",
+            "src_file_path"
+          ],
+          "columnsTo": [
+            "project",
+            "file_path"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "relations_dst_project_dst_file_path_files_project_file_path_fk": {
+          "name": "relations_dst_project_dst_file_path_files_project_file_path_fk",
+          "tableFrom": "relations",
+          "tableTo": "files",
+          "columnsFrom": [
+            "dst_project",
+            "dst_file_path"
+          ],
+          "columnsTo": [
+            "project",
+            "file_path"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "symbols": {
+      "name": "symbols",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "project": {
+          "name": "project",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "file_path": {
+          "name": "file_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "start_line": {
+          "name": "start_line",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "start_column": {
+          "name": "start_column",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "end_line": {
+          "name": "end_line",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "end_column": {
+          "name": "end_column",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "is_exported": {
+          "name": "is_exported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "signature": {
+          "name": "signature",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail_json": {
+          "name": "detail_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content_hash": {
+          "name": "content_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "indexed_at": {
+          "name": "indexed_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "resolved_type": {
+          "name": "resolved_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_symbols_project_file": {
+          "name": "idx_symbols_project_file",
+          "columns": [
+            "project",
+            "file_path"
+          ],
+          "isUnique": false
+        },
+        "idx_symbols_project_kind": {
+          "name": "idx_symbols_project_kind",
+          "columns": [
+            "project",
+            "kind"
+          ],
+          "isUnique": false
+        },
+        "idx_symbols_project_name": {
+          "name": "idx_symbols_project_name",
+          "columns": [
+            "project",
+            "name"
+          ],
+          "isUnique": false
+        },
+        "idx_symbols_fingerprint": {
+          "name": "idx_symbols_fingerprint",
+          "columns": [
+            "project",
+            "fingerprint"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "symbols_project_file_path_files_project_file_path_fk": {
+          "name": "symbols_project_file_path_files_project_file_path_fk",
+          "tableFrom": "symbols",
+          "tableTo": "files",
+          "columnsFrom": [
+            "project",
+            "file_path"
+          ],
+          "columnsTo": [
+            "project",
+            "file_path"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "watcher_owner": {
+      "name": "watcher_owner",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "pid": {
+          "name": "pid",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "heartbeat_at": {
+          "name": "heartbeat_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "instance_id": {
+          "name": "instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {
+        "watcher_owner_singleton": {
+          "name": "watcher_owner_singleton",
+          "value": "\"watcher_owner\".\"id\" = 1"
+        }
+      }
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/dist/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1772043335425,
       "tag": "0004_cool_firestar",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1772150400000,
+      "tag": "0005_instance_id_covering_index",
+      "breakpoints": true
     }
   ]
 }

package/dist/src/gildash/context.d.ts

@@ -77,6 +77,7 @@ export interface GildashContext {
     readonly updateHeartbeatFn: UpdateHeartbeatFn;
     readonly watcherFactory?: () => WatcherLike;
     readonly coordinatorFactory?: () => CoordinatorLike;
+    readonly instanceId: string;
     closed: boolean;
     coordinator: CoordinatorLike | null;
     watcher: WatcherLike | null;
@@ -85,7 +86,11 @@ export interface GildashContext {
     tsconfigPaths: TsconfigPaths | null;
     boundaries: ProjectBoundary[];
     onIndexedCallbacks: Set<(result: IndexResult) => void>;
+    onFileChangedCallbacks: Set<(event: FileChangeEvent) => void>;
+    onErrorCallbacks: Set<(error: GildashError) => void>;
+    onRoleChangedCallbacks: Set<(newRole: 'owner' | 'reader') => void>;
     graphCache: DependencyGraph | null;
     graphCacheKey: string | null;
+    graphCacheBuiltAt: number | null;
     semanticLayer: SemanticLayerLike | null;
 }

package/dist/src/gildash/graph-api.d.ts

@@ -1,11 +1,14 @@
 import { DependencyGraph } from '../search/dependency-graph';
 import type { GildashContext } from './context';
 import type { FanMetrics } from './types';
+/** Graph cache TTL — matches healthcheck interval so readers stay fresh. */
+export declare const GRAPH_CACHE_TTL_MS = 15000;
 /** Invalidate the cached DependencyGraph (called after every index run). */
 export declare function invalidateGraphCache(ctx: GildashContext): void;
 /**
  * Return a cached or freshly-built DependencyGraph for the given project.
  * Builds once per key; subsequent calls with the same key return the cached instance.
+ * TTL-based expiry ensures readers don't hold stale graphs indefinitely.
  */
 export declare function getOrBuildGraph(ctx: GildashContext, project?: string): DependencyGraph;
 /** List the files that a given file directly imports. */

package/dist/src/gildash/index.d.ts

@@ -10,9 +10,11 @@ import type { FileRecord } from '../store/repositories/file.repository';
 import type { PatternMatch } from '../search/pattern-search';
 import type { ResolvedType, SemanticReference, Implementation, SemanticModuleInterface } from '../semantic/types';
 import type { GildashContext } from './context';
-import type { GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol } from './types';
+import type { FileChangeEvent } from '../watcher/types';
+import { GildashError } from '../errors';
+import type { GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol, BatchParseResult } from './types';
 import type { GildashInternalOptions } from './lifecycle';
-export type { Logger, GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol, } from './types';
+export type { Logger, GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol, BatchParseResult, } from './types';
 export type { GildashInternalOptions } from './lifecycle';
 /**
  * Main entry point for gildash.
@@ -47,7 +49,7 @@ export declare class Gildash {
         cleanup?: boolean;
     }): Promise<void>;
     parseSource(filePath: string, sourceText: string, options?: ParserOptions): ParsedFile;
-    batchParse(filePaths: string[], options?: ParserOptions): Promise<Map<string, ParsedFile>>;
+    batchParse(filePaths: string[], options?: ParserOptions): Promise<BatchParseResult>;
     getParsedAst(filePath: string): ParsedFile | undefined;
     extractSymbols(parsed: ParsedFile): ExtractedSymbol[];
     extractRelations(parsed: ParsedFile): CodeRelation[];
@@ -88,4 +90,7 @@ export declare class Gildash {
         project?: string;
     }): Promise<PatternMatch[]>;
     getHeritageChain(symbolName: string, filePath: string, project?: string): Promise<HeritageNode>;
+    onFileChanged(callback: (event: FileChangeEvent) => void): () => void;
+    onError(callback: (error: GildashError) => void): () => void;
+    onRoleChanged(callback: (newRole: 'owner' | 'reader') => void): () => void;
 }

package/dist/src/gildash/lifecycle.d.ts

@@ -15,7 +15,7 @@ import { SemanticLayer } from '../semantic/index';
 import type { GildashContext, CoordinatorLike, WatcherLike, DbStore } from './context';
 import type { GildashOptions } from './types';
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
-export declare const HEALTHCHECK_INTERVAL_MS = 60000;
+export declare const HEALTHCHECK_INTERVAL_MS = 15000;
 export declare const MAX_HEALTHCHECK_RETRIES = 10;
 export interface GildashInternalOptions {
     existsSyncFn?: (p: string) => boolean;

package/dist/src/gildash/misc-api.d.ts

@@ -1,6 +1,8 @@
 import type { SymbolSearchResult } from '../search/symbol-search';
 import type { IndexResult } from '../indexer/index-coordinator';
+import type { FileChangeEvent } from '../watcher/types';
 import type { PatternMatch } from '../search/pattern-search';
+import { GildashError } from '../errors';
 import type { GildashContext } from './context';
 import type { SymbolDiff, ResolvedSymbol, HeritageNode } from './types';
 /** Compare two snapshots of symbol search results and return a structured diff. */
@@ -11,6 +13,12 @@ export declare function onIndexed(ctx: GildashContext, callback: (result: IndexR
 export declare function reindex(ctx: GildashContext): Promise<IndexResult>;
 /** Resolve the original definition location of a symbol by following its re-export chain. */
 export declare function resolveSymbol(ctx: GildashContext, symbolName: string, filePath: string, project?: string): ResolvedSymbol;
+/** Register a callback that fires whenever a watched file changes. */
+export declare function onFileChanged(ctx: GildashContext, callback: (event: FileChangeEvent) => void): () => void;
+/** Register a callback that fires on internal errors (e.g. healthcheck failures). */
+export declare function onError(ctx: GildashContext, callback: (error: GildashError) => void): () => void;
+/** Register a callback that fires when the watcher role changes (reader → owner). */
+export declare function onRoleChanged(ctx: GildashContext, callback: (newRole: 'owner' | 'reader') => void): () => void;
 /** Search for an AST structural pattern across indexed TypeScript files. */
 export declare function findPattern(ctx: GildashContext, pattern: string, opts?: {
     filePaths?: string[];

package/dist/src/gildash/parse-api.d.ts

@@ -1,9 +1,10 @@
 import type { ParsedFile } from '../parser/types';
 import type { ParserOptions } from 'oxc-parser';
 import type { GildashContext } from './context';
+import type { BatchParseResult } from './types';
 /** Parse a TypeScript source string into an AST and cache the result. */
 export declare function parseSource(ctx: GildashContext, filePath: string, sourceText: string, options?: ParserOptions): ParsedFile;
-/** Parse multiple files concurrently and return a map of results. */
-export declare function batchParse(ctx: GildashContext, filePaths: string[], options?: ParserOptions): Promise<Map<string, ParsedFile>>;
+/** Parse multiple files concurrently and return results with failure details. */
+export declare function batchParse(ctx: GildashContext, filePaths: string[], options?: ParserOptions): Promise<BatchParseResult>;
 /** Retrieve a previously-parsed AST from the internal LRU cache. */
 export declare function getParsedAst(ctx: GildashContext, filePath: string): ParsedFile | undefined;

package/dist/src/gildash/types.d.ts

@@ -1,3 +1,4 @@
+import type { ParsedFile } from '../parser/types';
 import type { SymbolSearchResult } from '../search/symbol-search';
 import type { SymbolKind } from '../extractor/types';
 import type { ResolvedType } from '../semantic/types';
@@ -126,6 +127,19 @@ export interface ResolvedSymbol {
     /** Whether a circular re-export chain was detected. */
     circular: boolean;
 }
+/**
+ * Result of a batch parse operation.
+ * Contains both successful parses and failure details.
+ */
+export interface BatchParseResult {
+    /** Successfully parsed files. */
+    parsed: Map<string, ParsedFile>;
+    /** Files that failed to parse, with error details. */
+    failures: Array<{
+        filePath: string;
+        error: Error;
+    }>;
+}
 /**
  * Options for creating a {@link Gildash} instance via {@link Gildash.open}.
  */

package/dist/src/indexer/index-coordinator.d.ts

@@ -9,6 +9,7 @@ import type { SymbolRecord } from '../store/repositories/symbol.repository';
 import type { RelationRecord } from '../store/repositories/relation.repository';
 import type { Logger } from '../gildash';
 export declare const WATCHER_DEBOUNCE_MS = 100;
+export declare const FILE_READ_BATCH_SIZE = 50;
 /**
  * Summary returned after an indexing run completes.
  *

package/dist/src/search/dependency-graph.d.ts

@@ -32,6 +32,19 @@ export declare class DependencyGraph {
      * Must be called before any query method.
      */
     build(): void;
+    /**
+     * Incrementally patch the graph after a set of files changed or were deleted.
+     *
+     * For small change-sets this is much cheaper than a full {@link build}.
+     *
+     * @param changedFiles  - Files whose edges may have changed.
+     * @param deletedFiles  - Files that were removed from the project.
+     * @param getRelationsForFile - Callback to query current relations for a file.
+     */
+    patchFiles(changedFiles: string[], deletedFiles: string[], getRelationsForFile: (filePath: string) => Array<{
+        srcFilePath: string;
+        dstFilePath: string;
+    }>): void;
     /**
      * Return the files that `filePath` directly imports.
      *

package/dist/src/store/connection.d.ts

@@ -21,9 +21,10 @@ export declare class DbConnection {
     selectOwner(): {
         pid: number;
         heartbeat_at: string;
+        instance_id: string | null;
     } | undefined;
-    insertOwner(pid: number): void;
-    replaceOwner(pid: number): void;
+    insertOwner(pid: number, instanceId?: string): void;
+    replaceOwner(pid: number, instanceId?: string): void;
     touchOwner(pid: number): void;
     deleteOwner(pid: number): void;
     private requireClient;

package/dist/src/store/schema.d.ts

@@ -683,6 +683,25 @@ export declare const watcherOwner: import("drizzle-orm/sqlite-core").SQLiteTable
         }, {}, {
             length: number | undefined;
         }>;
+        instanceId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "instance_id";
+            tableName: "watcher_owner";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;