@zipbul/gildash 0.0.2 → 0.1.2

package/dist/src/errors.d.ts

@@ -1,42 +1,22 @@
 /**
- * Base error class for all Gildash errors.
- * Every error thrown by this library is an instance of `GildashError`.
- *
- * @example
- * ```ts
- * try {
- *   await Gildash.open({ projectRoot: '/path' });
- * } catch (err) {
- *   if (err instanceof GildashError) {
- *     console.error('Gildash error:', err.message);
- *   }
- * }
- * ```
+ * Discriminated union type representing all possible error categories in Gildash.
  */
-export declare class GildashError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when the file watcher fails to start or stop. */
-export declare class WatcherError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when AST parsing of a TypeScript file fails. */
-export declare class ParseError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when symbol or relation extraction from a parsed AST fails. */
-export declare class ExtractError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when the indexing pipeline encounters an unrecoverable error. */
-export declare class IndexError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when a database (SQLite) operation fails. */
-export declare class StoreError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Thrown when a search query (symbol search, relation search) fails. */
-export declare class SearchError extends GildashError {
-    constructor(message: string, options?: ErrorOptions);
+export type GildashErrorType = 'watcher' | 'parse' | 'extract' | 'index' | 'store' | 'search' | 'closed' | 'validation' | 'close';
+/**
+ * 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>`.
+ */
+export interface GildashError {
+    type: GildashErrorType;
+    message: string;
+    cause?: unknown;
 }
+/**
+ * Factory function that creates a {@link GildashError} value.
+ *
+ * @param type    - One of the {@link GildashErrorType} variants.
+ * @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.
+ */
+export declare function gildashError(type: GildashErrorType, message: string, cause?: unknown): GildashError;

package/dist/src/gildash.d.ts

@@ -1,3 +1,4 @@
+import { type Result } from '@zipbul/result';
 import type { ParsedFile } from './parser/types';
 import { parseSource as defaultParseSource } from './parser/parse-source';
 import { ParseCache } from './parser/parse-cache';
@@ -24,6 +25,7 @@ import type { SymbolSearchQuery, SymbolSearchResult } from './search/symbol-sear
 import { relationSearch as defaultRelationSearch } from './search/relation-search';
 import type { RelationSearchQuery } from './search/relation-search';
 import type { SymbolStats } from './store/repositories/symbol.repository';
+import { type GildashError } from './errors';
 /**
  * Minimal logger interface accepted by {@link Gildash}.
  *
@@ -38,11 +40,18 @@ export interface Logger {
  *
  * @example
  * ```ts
- * const ledger = await Gildash.open({
+ * import { isErr } from '@zipbul/result';
+ *
+ * const result = await Gildash.open({
  *   projectRoot: '/absolute/path/to/project',
  *   extensions: ['.ts', '.tsx'],
  *   ignorePatterns: ['vendor'],
  * });
+ * if (isErr(result)) {
+ *   console.error(result.data.message);
+ *   process.exit(1);
+ * }
+ * const ledger = result;
  * ```
  */
 export interface GildashOptions {
@@ -88,15 +97,30 @@ interface GildashInternalOptions {
  * `Gildash` indexes TypeScript source code into a local SQLite database,
  * watches for file changes, and provides search / dependency-graph queries.
  *
+ * Every public method returns a `Result<T, GildashError>` — either the
+ * success value `T` directly, or an `Err<GildashError>` that can be checked
+ * with `isErr()` from `@zipbul/result`.
+ *
  * Create an instance with the static {@link Gildash.open} factory.
  * Always call {@link Gildash.close} when done to release resources.
  *
  * @example
  * ```ts
  * import { Gildash } from '@zipbul/gildash';
+ * import { isErr } from '@zipbul/result';
+ *
+ * const result = await Gildash.open({ projectRoot: '/my/project' });
+ * if (isErr(result)) {
+ *   console.error(result.data.message);
+ *   process.exit(1);
+ * }
+ * const ledger = result;
  *
- * const ledger = await Gildash.open({ projectRoot: '/my/project' });
  * const symbols = ledger.searchSymbols({ text: 'handle', kind: 'function' });
+ * if (!isErr(symbols)) {
+ *   symbols.forEach(s => console.log(s.name));
+ * }
+ *
  * await ledger.close();
  * ```
  */
@@ -133,18 +157,19 @@ export declare class Gildash {
      * and begins watching for file changes.
      *
      * @param options - Configuration for the instance.
-     * @returns A fully-initialised `Gildash` ready for queries.
-     * @throws {Error} If `projectRoot` is not absolute or does not exist.
+     * @returns A fully-initialised `Gildash` ready for queries, or an `Err<GildashError>` on failure.
      *
      * @example
      * ```ts
-     * const ledger = await Gildash.open({
+     * const result = await Gildash.open({
      *   projectRoot: '/home/user/my-app',
      *   extensions: ['.ts', '.tsx'],
      * });
+     * if (isErr(result)) { console.error(result.data.message); process.exit(1); }
+     * const ledger = result;
      * ```
      */
-    static open(options: GildashOptions & GildashInternalOptions): Promise<Gildash>;
+    static open(options: GildashOptions & GildashInternalOptions): Promise<Result<Gildash, GildashError>>;
     /**
      * Shut down the instance and release all resources.
      *
@@ -152,9 +177,20 @@ export declare class Gildash {
      * releases the watcher ownership role, and closes the database.
      * Calling `close()` more than once is safe (subsequent calls are no-ops).
      *
-     * @throws {AggregateError} If one or more sub-systems fail during shutdown.
+     * @returns `void` on success, or `Err<GildashError>` with `type='close'` if one or more
+     *   sub-systems failed during shutdown.  The `cause` field contains an array of
+     *   individual errors from each failed sub-system.
+     *
+     * @example
+     * ```ts
+     * const closeResult = await ledger.close();
+     * if (isErr(closeResult)) {
+     *   console.error('Close failed:', closeResult.data.message);
+     *   // closeResult.data.cause is unknown[] of per-subsystem errors
+     * }
+     * ```
      */
-    close(): Promise<void>;
+    close(): Promise<Result<void, GildashError>>;
     /**
      * Register a callback that fires after each indexing run completes.
      *
@@ -174,38 +210,86 @@ export declare class Gildash {
     /**
      * Parse a TypeScript source string into an AST and cache the result.
      *
+     * On success the result is automatically stored in the internal LRU parse cache
+     * so that subsequent calls to extraction methods can reuse it.
+     *
      * @param filePath - File path used as the cache key and for diagnostics.
      * @param sourceText - Raw TypeScript source code.
-     * @returns The parsed file representation.
-     * @throws {Error} If the instance is closed.
+     * @returns A {@link ParsedFile}, or `Err<GildashError>` with `type='closed'` if the instance
+     *   is closed, or `type='parse'` if the parser fails.
+     *
+     * @example
+     * ```ts
+     * const parsed = ledger.parseSource('/project/src/app.ts', sourceCode);
+     * if (isErr(parsed)) {
+     *   console.error(parsed.data.message); // e.g. "Failed to parse file: ..."
+     *   return;
+     * }
+     * // parsed is now a ParsedFile
+     * const symbols = ledger.extractSymbols(parsed);
+     * ```
      */
-    parseSource(filePath: string, sourceText: string): ParsedFile;
+    parseSource(filePath: string, sourceText: string): Result<ParsedFile, GildashError>;
     /**
      * Extract all symbol declarations from a previously parsed file.
      *
+     * Returns function, class, variable, type-alias, interface, and enum declarations
+     * found in the AST.
+     *
      * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
-     * @returns An array of {@link ExtractedSymbol} entries.
-     * @throws {Error} If the instance is closed.
+     * @returns An array of {@link ExtractedSymbol} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed.
+     *
+     * @example
+     * ```ts
+     * const symbols = ledger.extractSymbols(parsed);
+     * if (isErr(symbols)) return;
+     * for (const sym of symbols) {
+     *   console.log(`${sym.kind}: ${sym.name}`);
+     * }
+     * ```
      */
-    extractSymbols(parsed: ParsedFile): ExtractedSymbol[];
+    extractSymbols(parsed: ParsedFile): Result<ExtractedSymbol[], GildashError>;
     /**
      * Extract inter-file relationships (imports, calls, extends, implements)
      * from a previously parsed file.
      *
+     * If tsconfig path aliases were discovered during {@link Gildash.open},
+     * they are automatically applied when resolving import targets.
+     *
      * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
-     * @returns An array of {@link CodeRelation} entries.
-     * @throws {Error} If the instance is closed.
+     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed.
+     *
+     * @example
+     * ```ts
+     * const relations = ledger.extractRelations(parsed);
+     * if (isErr(relations)) return;
+     * const imports = relations.filter(r => r.type === 'imports');
+     * ```
      */
-    extractRelations(parsed: ParsedFile): CodeRelation[];
+    extractRelations(parsed: ParsedFile): Result<CodeRelation[], GildashError>;
     /**
      * Trigger a full re-index of all tracked files.
      *
      * Only available to the instance that holds the *owner* role.
+     * Reader instances receive `Err<GildashError>` with `type='closed'`.
      *
-     * @returns The indexing result summary.
-     * @throws {Error} If the instance is closed or is a reader.
+     * @returns An {@link IndexResult} summary on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed / reader,
+     *   `type='index'` if the indexing pipeline fails.
+     *
+     * @example
+     * ```ts
+     * const result = await ledger.reindex();
+     * if (isErr(result)) {
+     *   console.error(result.data.message);
+     *   return;
+     * }
+     * console.log(`Indexed ${result.indexedFiles} files in ${result.durationMs}ms`);
+     * ```
      */
-    reindex(): Promise<IndexResult>;
+    reindex(): Promise<Result<IndexResult, GildashError>>;
     /**
      * Discovered project boundaries within the project root.
      *
@@ -216,69 +300,124 @@ export declare class Gildash {
      * Return aggregate symbol statistics for the given project.
      *
      * @param project - Project name. Defaults to the auto-discovered primary project.
-     * @returns Counts grouped by symbol kind.
-     * @throws {Error} If the instance is closed.
+     * @returns A {@link SymbolStats} object with counts grouped by symbol kind,
+     *   or `Err<GildashError>` with `type='closed'` if the instance is closed,
+     *   `type='store'` if the database query fails.
+     *
+     * @example
+     * ```ts
+     * const stats = ledger.getStats();
+     * if (isErr(stats)) return;
+     * console.log(`Files: ${stats.fileCount}, Symbols: ${stats.symbolCount}`);
+     * ```
      */
-    getStats(project?: string): SymbolStats;
+    getStats(project?: string): Result<SymbolStats, GildashError>;
     /**
      * Search indexed symbols by name, kind, file path, or export status.
      *
-     * @param query - Search filters. All fields are optional; omitted fields match everything.
-     * @returns Matching {@link SymbolSearchResult} entries.
-     * @throws {Error} If the instance is closed.
+     * @param query - Search filters (see {@link SymbolSearchQuery}). All fields are optional;
+     *   omitted fields match everything.
+     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the query fails.
      *
      * @example
      * ```ts
      * const fns = ledger.searchSymbols({ kind: 'function', isExported: true });
+     * if (isErr(fns)) return;
+     * fns.forEach(fn => console.log(fn.name, fn.filePath));
      * ```
      */
-    searchSymbols(query: SymbolSearchQuery): SymbolSearchResult[];
+    searchSymbols(query: SymbolSearchQuery): Result<SymbolSearchResult[], GildashError>;
     /**
      * Search indexed code relationships (imports, calls, extends, implements).
      *
-     * @param query - Search filters. All fields are optional.
-     * @returns Matching {@link CodeRelation} entries.
-     * @throws {Error} If the instance is closed.
+     * @param query - Search filters (see {@link RelationSearchQuery}). All fields are optional.
+     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the query fails.
+     *
+     * @example
+     * ```ts
+     * const rels = ledger.searchRelations({ srcFilePath: 'src/app.ts', type: 'imports' });
+     * if (isErr(rels)) return;
+     * rels.forEach(r => console.log(`${r.srcFilePath} -> ${r.dstFilePath}`));
+     * ```
      */
-    searchRelations(query: RelationSearchQuery): CodeRelation[];
+    searchRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
     /**
      * List the files that a given file directly imports.
      *
      * @param filePath - Absolute path of the source file.
      * @param project - Project name. Defaults to the primary project.
      * @param limit - Maximum results. Defaults to `10_000`.
-     * @returns Absolute paths of imported files.
-     * @throws {Error} If the instance is closed.
+     * @returns An array of absolute paths that `filePath` imports,
+     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
+     *
+     * @example
+     * ```ts
+     * const deps = ledger.getDependencies('/project/src/app.ts');
+     * if (isErr(deps)) return;
+     * console.log('Imports:', deps.join(', '));
+     * ```
      */
-    getDependencies(filePath: string, project?: string, limit?: number): string[];
+    getDependencies(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
     /**
      * List the files that directly import a given file.
      *
      * @param filePath - Absolute path of the target file.
      * @param project - Project name. Defaults to the primary project.
      * @param limit - Maximum results. Defaults to `10_000`.
-     * @returns Absolute paths of files that import the target.
-     * @throws {Error} If the instance is closed.
+     * @returns An array of absolute paths of files that import `filePath`,
+     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
+     *
+     * @example
+     * ```ts
+     * const dependents = ledger.getDependents('/project/src/utils.ts');
+     * if (isErr(dependents)) return;
+     * console.log('Imported by:', dependents.join(', '));
+     * ```
      */
-    getDependents(filePath: string, project?: string, limit?: number): string[];
+    getDependents(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
     /**
      * Compute the full set of files transitively affected by changes.
      *
-     * Builds a dependency graph and walks all reverse edges from each changed file.
+     * Internally builds a full {@link DependencyGraph} and walks all reverse
+     * edges from each changed file to find every transitive dependent.
      *
      * @param changedFiles - Absolute paths of files that changed.
      * @param project - Project name. Defaults to the primary project.
-     * @returns Paths of all transitively-dependent files (excludes the changed files themselves).
-     * @throws {Error} If the instance is closed.
+     * @returns De-duplicated absolute paths of all transitively-dependent files
+     *   (excluding the changed files themselves), or `Err<GildashError>` with
+     *   `type='closed'` / `type='search'`.
+     *
+     * @example
+     * ```ts
+     * const affected = await ledger.getAffected(['/project/src/utils.ts']);
+     * if (isErr(affected)) return;
+     * console.log('Affected files:', affected.length);
+     * ```
      */
-    getAffected(changedFiles: string[], project?: string): Promise<string[]>;
+    getAffected(changedFiles: string[], project?: string): Promise<Result<string[], GildashError>>;
     /**
      * Check whether the import graph contains a circular dependency.
      *
+     * Internally builds a full {@link DependencyGraph} and runs iterative DFS
+     * cycle detection.
+     *
      * @param project - Project name. Defaults to the primary project.
-     * @returns `true` if at least one cycle exists.
-     * @throws {Error} If the instance is closed.
+     * @returns `true` if at least one cycle exists, `false` otherwise,
+     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
+     *
+     * @example
+     * ```ts
+     * const cycleResult = await ledger.hasCycle();
+     * if (isErr(cycleResult)) return;
+     * if (cycleResult) {
+     *   console.warn('Circular dependency detected!');
+     * }
+     * ```
      */
-    hasCycle(project?: string): Promise<boolean>;
+    hasCycle(project?: string): Promise<Result<boolean, GildashError>>;
 }
 export {};

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 export { Gildash } from "./gildash";
 export type { GildashOptions, Logger } from "./gildash";
-export { GildashError, WatcherError, ParseError, ExtractError, IndexError, StoreError, SearchError, } from "./errors";
+export { gildashError } from "./errors";
+export type { GildashError, GildashErrorType } from "./errors";
 export { symbolSearch } from "./search/symbol-search";
 export type { SymbolSearchQuery, SymbolSearchResult } from "./search/symbol-search";
 export { relationSearch } from "./search/relation-search";

package/dist/src/parser/jsdoc-parser.d.ts

@@ -1,2 +1,4 @@
+import { type Result } from '@zipbul/result';
 import type { JsDocBlock } from '../extractor/types';
-export declare function parseJsDoc(commentText: string): JsDocBlock;
+import { type GildashError } from '../errors';
+export declare function parseJsDoc(commentText: string): Result<JsDocBlock, GildashError>;

package/dist/src/parser/parse-source.d.ts

@@ -1,3 +1,5 @@
+import { type Result } from '@zipbul/result';
 import { parseSync as defaultParseSync } from 'oxc-parser';
 import type { ParsedFile } from './types';
-export declare function parseSource(filePath: string, sourceText: string, parseSyncFn?: typeof defaultParseSync): ParsedFile;
+import { type GildashError } from '../errors';
+export declare function parseSource(filePath: string, sourceText: string, parseSyncFn?: typeof defaultParseSync): Result<ParsedFile, GildashError>;

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

@@ -1,4 +1,6 @@
+import { type Result } from '@zipbul/result';
 import { type BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import { type GildashError } from '../errors';
 import * as schema from './schema';
 export interface DbConnectionOptions {
     projectRoot: string;
@@ -10,7 +12,7 @@ export declare class DbConnection {
     private txDepth;
     constructor(opts: DbConnectionOptions);
     get drizzleDb(): BunSQLiteDatabase<typeof schema>;
-    open(): void;
+    open(): Result<void, GildashError>;
     close(): void;
     transaction<T>(fn: (tx: DbConnection) => T): T;
     immediateTransaction<T>(fn: () => T): T;

package/dist/src/watcher/project-watcher.d.ts

@@ -1,13 +1,15 @@
+import { type Result } from '@zipbul/result';
 import type { AsyncSubscription, SubscribeCallback } from "@parcel/watcher";
 import { subscribe as parcelSubscribe } from "@parcel/watcher";
 type SubscribeOptions = NonNullable<Parameters<typeof parcelSubscribe>[2]>;
+import { type GildashError } from "../errors";
 import type { FileChangeEvent, WatcherOptions } from "./types";
 import type { Logger } from "../gildash";
 type SubscribeFn = (directoryPath: string, callback: SubscribeCallback, options?: SubscribeOptions) => Promise<AsyncSubscription>;
 export declare class ProjectWatcher {
     #private;
     constructor(options: WatcherOptions, subscribeFn?: SubscribeFn, logger?: Logger);
-    start(onChange: (event: FileChangeEvent) => void): Promise<void>;
-    close(): Promise<void>;
+    start(onChange: (event: FileChangeEvent) => void): Promise<Result<void, GildashError>>;
+    close(): Promise<Result<void, GildashError>>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zipbul/gildash",
-  "version": "0.0.2",
+  "version": "0.1.2",
   "description": "TypeScript code indexing and dependency graph engine for Bun",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "build": "bun build index.ts --outdir dist --target bun --format esm --packages external --sourcemap=linked --production && tsc -p tsconfig.build.json && cp -r src/store/migrations dist/migrations",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "coverage": "bun test --coverage",
+    "test:coverage": "bun test --coverage",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "changeset publish"
@@ -54,5 +54,8 @@
     "@types/bun": "latest",
     "drizzle-kit": "^0.31.9",
     "husky": "^9.1.7"
+  },
+  "peerDependencies": {
+    "@zipbul/result": "^0.0.3"
   }
-}
+}