@zipbul/gildash 0.6.0 → 0.8.0

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/errors.d.ts

@@ -3,13 +3,14 @@
  */
 export type GildashErrorType = 'watcher' | 'parse' | 'extract' | 'index' | 'store' | 'search' | 'closed' | 'validation' | 'close' | 'semantic';
 /**
- * Plain-object error value used throughout Gildash's Result-based error handling.
- * Produced by {@link gildashError} and carried as the `data` field of an `Err<GildashError>`.
+ * Error class used throughout Gildash.
+ * Extends `Error` so that `instanceof Error` checks work and stack traces are captured.
  */
-export interface GildashError {
-    type: GildashErrorType;
-    message: string;
-    cause?: unknown;
+export declare class GildashError extends Error {
+    readonly type: GildashErrorType;
+    constructor(type: GildashErrorType, message: string, options?: {
+        cause?: unknown;
+    });
 }
 /**
  * Factory function that creates a {@link GildashError} value.
@@ -18,5 +19,6 @@ export interface GildashError {
  * @param message - Human-readable description of the error.
  * @param cause   - Optional root cause (any value). When `undefined`, the `cause`
  *                  property is omitted from the returned object entirely.
+ * @deprecated Use `new GildashError(type, message, { cause })` instead.
  */
 export declare function gildashError(type: GildashErrorType, message: string, cause?: unknown): GildashError;

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/extract-api.d.ts

@@ -1,9 +1,7 @@
-import { type Result } from '@zipbul/result';
 import type { ParsedFile } from '../parser/types';
 import type { ExtractedSymbol, CodeRelation } from '../extractor/types';
-import type { GildashError } from '../errors';
 import type { GildashContext } from './context';
 /** Extract all symbol declarations from a previously parsed file. */
-export declare function extractSymbols(ctx: GildashContext, parsed: ParsedFile): Result<ExtractedSymbol[], GildashError>;
+export declare function extractSymbols(ctx: GildashContext, parsed: ParsedFile): ExtractedSymbol[];
 /** Extract inter-file relationships from a previously parsed file. */
-export declare function extractRelations(ctx: GildashContext, parsed: ParsedFile): Result<CodeRelation[], GildashError>;
+export declare function extractRelations(ctx: GildashContext, parsed: ParsedFile): CodeRelation[];

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

@@ -1,30 +1,31 @@
-import { type Result } from '@zipbul/result';
-import type { GildashError } from '../errors';
 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. */
-export declare function getDependencies(ctx: GildashContext, filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
+export declare function getDependencies(ctx: GildashContext, filePath: string, project?: string, limit?: number): string[];
 /** List the files that directly import a given file. */
-export declare function getDependents(ctx: GildashContext, filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
+export declare function getDependents(ctx: GildashContext, filePath: string, project?: string, limit?: number): string[];
 /** Compute the full set of files transitively affected by changes. */
-export declare function getAffected(ctx: GildashContext, changedFiles: string[], project?: string): Promise<Result<string[], GildashError>>;
+export declare function getAffected(ctx: GildashContext, changedFiles: string[], project?: string): Promise<string[]>;
 /** Check whether the import graph contains a circular dependency. */
-export declare function hasCycle(ctx: GildashContext, project?: string): Promise<Result<boolean, GildashError>>;
+export declare function hasCycle(ctx: GildashContext, project?: string): Promise<boolean>;
 /** Return the full import graph as an adjacency list. */
-export declare function getImportGraph(ctx: GildashContext, project?: string): Promise<Result<Map<string, string[]>, GildashError>>;
+export declare function getImportGraph(ctx: GildashContext, project?: string): Promise<Map<string, string[]>>;
 /** Return all files that `filePath` transitively imports (forward BFS). */
-export declare function getTransitiveDependencies(ctx: GildashContext, filePath: string, project?: string): Promise<Result<string[], GildashError>>;
+export declare function getTransitiveDependencies(ctx: GildashContext, filePath: string, project?: string): Promise<string[]>;
 /** Return all cycle paths in the import graph. */
 export declare function getCyclePaths(ctx: GildashContext, project?: string, options?: {
     maxCycles?: number;
-}): Promise<Result<string[][], GildashError>>;
+}): Promise<string[][]>;
 /** Compute import-graph fan metrics (fan-in / fan-out) for a single file. */
-export declare function getFanMetrics(ctx: GildashContext, filePath: string, project?: string): Promise<Result<FanMetrics, GildashError>>;
+export declare function getFanMetrics(ctx: GildashContext, filePath: string, project?: string): Promise<FanMetrics>;