@zipbul/gildash 0.2.0 → 0.3.0

package/dist/src/gildash.d.ts

@@ -8,6 +8,7 @@ import { extractRelations as defaultExtractRelations } from './extractor/relatio
 import type { CodeRelation } from './extractor/types';
 import { DbConnection } from './store/connection';
 import { FileRepository } from './store/repositories/file.repository';
+import type { FileRecord } from './store/repositories/file.repository';
 import { SymbolRepository } from './store/repositories/symbol.repository';
 import { RelationRepository } from './store/repositories/relation.repository';
 import { ProjectWatcher } from './watcher/project-watcher';
@@ -75,7 +76,7 @@ interface GildashInternalOptions {
         handleWatcherEvent?(event: FileChangeEvent): void;
     };
     repositoryFactory?: () => {
-        fileRepo: Pick<FileRepository, 'upsertFile' | 'getAllFiles' | 'getFilesMap' | 'deleteFile'>;
+        fileRepo: Pick<FileRepository, 'upsertFile' | 'getAllFiles' | 'getFilesMap' | 'deleteFile' | 'getFile'>;
         symbolRepo: SymbolRepository;
         relationRepo: RelationRepository;
         parseCache: Pick<ParseCache, 'set' | 'get' | 'invalidate'>;
@@ -130,6 +131,7 @@ export declare class Gildash {
     private readonly db;
     private readonly symbolRepo;
     private readonly relationRepo;
+    private readonly fileRepo;
     private readonly parseCache;
     private coordinator;
     private watcher;
@@ -420,5 +422,36 @@ export declare class Gildash {
      * ```
      */
     hasCycle(project?: string): Promise<Result<boolean, GildashError>>;
+    /**
+     * Retrieve a previously-parsed AST from the internal LRU cache.
+     *
+     * Returns `undefined` if the file has not been parsed or was evicted from the cache.
+     * The returned object is shared with the internal cache — treat it as **read-only**.
+     *
+     * @param filePath - Absolute path of the file.
+     * @returns The cached {@link ParsedFile}, or `undefined` if not available.
+     */
+    getParsedAst(filePath: string): ParsedFile | undefined;
+    /**
+     * Retrieve metadata for an indexed file.
+     *
+     * Returns the stored {@link FileRecord} including content hash, mtime, and size.
+     * Returns `null` if the file has not been indexed yet.
+     *
+     * @param filePath - Relative path from project root (as stored in the index).
+     * @param project - Project name. Defaults to the primary project.
+     * @returns The {@link FileRecord}, or `null` if not found.
+     */
+    getFileInfo(filePath: string, project?: string): Result<FileRecord | null, GildashError>;
+    /**
+     * List all symbols declared in a specific file.
+     *
+     * Convenience wrapper around {@link searchSymbols} with a `filePath` filter.
+     *
+     * @param filePath - File path to query.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>`.
+     */
+    getSymbolsByFile(filePath: string, project?: string): Result<SymbolSearchResult[], GildashError>;
 }
 export {};

package/dist/src/index.d.ts

@@ -12,3 +12,5 @@ export type { ProjectBoundary } from "./common/project-discovery";
 export type { CodeRelation, SymbolKind } from "./extractor/types";
 export type { SymbolStats } from "./store/repositories/symbol.repository";
 export type { WatcherRole } from "./watcher/types";
+export type { ParsedFile } from "./parser/types";
+export type { FileRecord } from "./store/repositories/file.repository";

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

@@ -7,10 +7,28 @@ export interface SourceSpan {
     start: SourcePosition;
     end: SourcePosition;
 }
+/**
+ * The result of parsing a TypeScript source file with oxc-parser.
+ *
+ * Returned by {@link Gildash.parseSource} and retrievable from the internal LRU
+ * cache via {@link Gildash.getParsedAst}.
+ *
+ * @remarks
+ * The `program` field is an oxc-parser `Program` node.
+ * Consumers must add `oxc-parser` as a peer dependency to access the `Program` type.
+ *
+ * **The returned object is shared with the internal cache — treat it as read-only.**
+ * Mutating the AST may cause undefined behaviour in subsequent extraction operations.
+ */
 export interface ParsedFile {
+    /** Absolute path of the parsed file. */
     filePath: string;
+    /** Root AST node produced by oxc-parser. */
     program: Program;
+    /** Parse errors reported by oxc-parser (non-fatal). */
     errors: readonly OxcError[];
+    /** Top-level comments found in the source. */
     comments: readonly Comment[];
+    /** Raw source text that was parsed. */
     sourceText: string;
 }

package/dist/src/search/symbol-search.d.ts

@@ -8,6 +8,8 @@ import type { SymbolRecord } from '../store/repositories/symbol.repository';
 export interface SymbolSearchQuery {
     /** Full-text search on symbol names (prefix matching). */
     text?: string;
+    /** Exact symbol name match. When `true`, `text` is treated as an exact name (not FTS prefix). */
+    exact?: boolean;
     /** Restrict to a specific {@link SymbolKind}. */
     kind?: SymbolKind;
     /** Restrict to symbols declared in this file path. */
@@ -54,6 +56,7 @@ export interface SymbolSearchResult {
 export interface ISymbolRepo {
     searchByQuery(opts: {
         ftsQuery?: string;
+        exactName?: string;
         kind?: string;
         filePath?: string;
         isExported?: boolean;

package/dist/src/store/repositories/file.repository.d.ts

@@ -1,10 +1,22 @@
 import type { DbConnection } from '../connection';
+/**
+ * Metadata record for an indexed source file.
+ *
+ * Stored and retrieved by {@link FileRepository}.
+ * Exposed via {@link Gildash.getFileInfo}.
+ */
 export interface FileRecord {
+    /** Project name this file belongs to. */
     project: string;
+    /** File path relative to the project root. */
     filePath: string;
+    /** Last-modified timestamp in milliseconds since epoch. */
     mtimeMs: number;
+    /** File size in bytes at the time of indexing. */
     size: number;
+    /** SHA-256 content hash of the file at the time of indexing. */
     contentHash: string;
+    /** ISO 8601 timestamp of the last index update. */
     updatedAt: string;
 }
 export declare class FileRepository {

package/dist/src/store/repositories/symbol.repository.d.ts

@@ -42,6 +42,7 @@ export declare class SymbolRepository {
     deleteFileSymbols(project: string, filePath: string): void;
     searchByQuery(opts: {
         ftsQuery?: string;
+        exactName?: string;
         kind?: string;
         filePath?: string;
         isExported?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zipbul/gildash",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript code indexing and dependency graph engine for Bun",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,8 @@
     "test:coverage": "bun test --coverage",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "changeset publish"
+    "release": "changeset publish",
+    "prepare": "husky"
   },
   "dependencies": {
     "@parcel/watcher": "^2.5.6",
@@ -56,6 +57,7 @@
     "husky": "^9.1.7"
   },
   "peerDependencies": {
-    "@zipbul/result": "^0.0.3"
+    "@zipbul/result": "^0.0.3",
+    "oxc-parser": ">=0.114.0"
   }
-}
+}