@zipbul/gildash 0.3.0 → 0.4.0

package/dist/migrations/0001_add_line_count.sql

@@ -0,0 +1 @@
+ALTER TABLE `files` ADD COLUMN `line_count` integer;

package/dist/migrations/meta/_journal.json

@@ -8,6 +8,13 @@
       "when": 1771705270251,
       "tag": "0000_soft_revanche",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1771815700000,
+      "tag": "0001_add_line_count",
+      "breakpoints": true
     }
   ]
 }

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

@@ -141,13 +141,15 @@ export interface ImportReference {
  * A relationship between two symbols/files extracted from source code.
  *
  * - `'imports'` — file A imports from file B
+ * - `'type-references'` — file A type-only imports from file B (`import type`)
+ * - `'re-exports'` — file A re-exports from file B (`export { ... } from`)
  * - `'calls'` — symbol in file A calls a symbol in file B
  * - `'extends'` — class/interface in file A extends one in file B
  * - `'implements'` — class in file A implements an interface in file B
  */
 export interface CodeRelation {
     /** The kind of relationship. */
-    type: 'imports' | 'calls' | 'extends' | 'implements';
+    type: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
     /** File path where the relationship originates. */
     srcFilePath: string;
     /** Source symbol name, or `null` for module-level relationships. */
@@ -158,5 +160,7 @@ export interface CodeRelation {
     dstSymbolName: string | null;
     /** Optional JSON-encoded metadata about the relation. */
     metaJson?: string;
+    /** Parsed metadata object derived from `metaJson`. */
+    meta?: Record<string, unknown>;
 }
 export type { SourcePosition, SourceSpan };

package/dist/src/gildash.d.ts

@@ -2,10 +2,9 @@ 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';
-import type { ExtractedSymbol } from './extractor/types';
+import type { ExtractedSymbol, SymbolKind, CodeRelation } from './extractor/types';
 import { extractSymbols as defaultExtractSymbols } from './extractor/symbol-extractor';
 import { extractRelations as defaultExtractRelations } from './extractor/relation-extractor';
-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';
@@ -26,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 { PatternMatch } from './search/pattern-search';
 import { type GildashError } from './errors';
 /**
  * Minimal logger interface accepted by {@link Gildash}.
@@ -36,6 +36,117 @@ export interface Logger {
     /** Log one or more error-level messages. */
     error(...args: unknown[]): void;
 }
+/**
+ * Result of a {@link Gildash.diffSymbols} call.
+ */
+export interface SymbolDiff {
+    /** Symbols present in `after` but not in `before`. */
+    added: SymbolSearchResult[];
+    /** Symbols present in `before` but not in `after`. */
+    removed: SymbolSearchResult[];
+    /** Symbols present in both but with a different `fingerprint`. */
+    modified: Array<{
+        before: SymbolSearchResult;
+        after: SymbolSearchResult;
+    }>;
+}
+/**
+ * Public interface of a module — its exported symbols with key metadata.
+ * Returned by {@link Gildash.getModuleInterface}.
+ */
+export interface ModuleInterface {
+    filePath: string;
+    exports: Array<{
+        name: string;
+        kind: SymbolKind;
+        parameters?: string;
+        returnType?: string;
+        jsDoc?: string;
+    }>;
+}
+/**
+ * A node in the heritage chain tree returned by {@link Gildash.getHeritageChain}.
+ */
+export interface HeritageNode {
+    symbolName: string;
+    filePath: string;
+    /** Relationship kind (`extends` or `implements`). Undefined for the root query node. */
+    kind?: 'extends' | 'implements';
+    children: HeritageNode[];
+}
+/**
+ * Full symbol detail including members, documentation, and type information.
+ * Returned by {@link Gildash.getFullSymbol}.
+ */
+export interface FullSymbol extends SymbolSearchResult {
+    members?: Array<{
+        name: string;
+        kind: string;
+        type?: string;
+        visibility?: string;
+        isStatic?: boolean;
+        isReadonly?: boolean;
+    }>;
+    /** JSDoc comment attached to the symbol. */
+    jsDoc?: string;
+    /** Stringified parameter list (functions/methods). */
+    parameters?: string;
+    /** Stringified return type (functions/methods). */
+    returnType?: string;
+    /** Superclass/interface names (classes/interfaces with heritage). */
+    heritage?: string[];
+    /** Decorators applied to the symbol. */
+    decorators?: Array<{
+        name: string;
+        arguments?: string;
+    }>;
+    /** Stringified type parameters (generic symbols). */
+    typeParameters?: string;
+}
+/**
+ * File-level statistics for an indexed file.
+ * Returned by {@link Gildash.getFileStats}.
+ */
+export interface FileStats {
+    /** Absolute file path. */
+    filePath: string;
+    /** Number of lines in the file at the time of last indexing. */
+    lineCount: number;
+    /** Number of symbols indexed in the file. */
+    symbolCount: number;
+    /** Number of outgoing relations (imports, calls, etc.) from the file. */
+    relationCount: number;
+    /** File size in bytes at the time of last indexing. */
+    size: number;
+    /** Number of exported symbols in the file. */
+    exportedSymbolCount: number;
+}
+/**
+ * Import-graph fan metrics for a single file.
+ * Returned by {@link Gildash.getFanMetrics}.
+ */
+export interface FanMetrics {
+    /** Absolute file path queried. */
+    filePath: string;
+    /** Number of files that import this file (fan-in). */
+    fanIn: number;
+    /** Number of files this file imports (fan-out). */
+    fanOut: number;
+}
+/**
+ * Result of following a re-export chain to the original symbol definition.
+ */
+export interface ResolvedSymbol {
+    /** The name of the symbol at the end of the re-export chain (may differ from the queried name due to aliasing). */
+    originalName: string;
+    /** Absolute path of the file that originally defines the symbol. */
+    originalFilePath: string;
+    /** Ordered list of re-export hops between the queried file and the original definition. */
+    reExportChain: Array<{
+        filePath: string;
+        exportedAs: string;
+    }>;
+}
 /**
  * Options for creating a {@link Gildash} instance via {@link Gildash.open}.
  *
@@ -66,6 +177,17 @@ export interface GildashOptions {
     parseCacheCapacity?: number;
     /** Logger for error output. Defaults to `console`. */
     logger?: Logger;
+    /**
+     * When `false`, disables the file watcher and runs in scan-only mode:
+     * ownership contention is skipped, heartbeat and signal handlers are not
+     * registered, and only the initial `fullIndex()` is performed.
+     *
+     * Set `cleanup: true` in {@link Gildash.close} to remove the database files
+     * after a one-shot scan.
+     *
+     * @default true
+     */
+    watchMode?: boolean;
 }
 interface GildashInternalOptions {
     existsSyncFn?: (p: string) => boolean;
@@ -90,7 +212,16 @@ interface GildashInternalOptions {
     extractRelationsFn?: typeof defaultExtractRelations;
     symbolSearchFn?: typeof defaultSymbolSearch;
     relationSearchFn?: typeof defaultRelationSearch;
+    patternSearchFn?: (opts: {
+        pattern: string;
+        filePaths: string[];
+    }) => Promise<PatternMatch[]>;
     loadTsconfigPathsFn?: typeof loadTsconfigPaths;
+    readFileFn?: (filePath: string) => Promise<string>;
+    unlinkFn?: (filePath: string) => Promise<void>;
+    makeExternalCoordinatorFn?: (packageDir: string, project: string) => {
+        fullIndex(): Promise<IndexResult>;
+    };
 }
 /**
  * Main entry point for gildash.
@@ -141,6 +272,11 @@ export declare class Gildash {
     private readonly extractRelationsFn;
     private readonly symbolSearchFn;
     private readonly relationSearchFn;
+    private readonly patternSearchFn;
+    private readonly readFileFn;
+    private readonly unlinkFn;
+    private readonly existsSyncFn;
+    private readonly makeExternalCoordinatorFn?;
     private readonly logger;
     private readonly defaultProject;
     /** Current watcher role: `'owner'` (can reindex) or `'reader'` (read-only). */
@@ -151,6 +287,10 @@ export declare class Gildash {
     private tsconfigPaths;
     private boundaries;
     private readonly onIndexedCallbacks;
+    /** Cached DependencyGraph — invalidated on each index run. */
+    private graphCache;
+    /** Project key of the cached graph (`project ?? '__cross__'`). */
+    private graphCacheKey;
     private constructor();
     /**
      * Create and initialise a new `Gildash` instance.
@@ -193,7 +333,9 @@ export declare class Gildash {
      * }
      * ```
      */
-    close(): Promise<Result<void, GildashError>>;
+    close(opts?: {
+        cleanup?: boolean;
+    }): Promise<Result<void, GildashError>>;
     /**
      * Register a callback that fires after each indexing run completes.
      *
@@ -272,6 +414,15 @@ export declare class Gildash {
      * ```
      */
     extractRelations(parsed: ParsedFile): Result<CodeRelation[], GildashError>;
+    /** Invalidate the cached DependencyGraph (called after every index run). */
+    private invalidateGraphCache;
+    /**
+     * Return a cached or freshly-built {@link DependencyGraph} for the given project.
+     *
+     * Builds once per `project ?? '__cross__'` key; subsequent calls with the same key
+     * return the cached instance. Cache is invalidated by {@link invalidateGraphCache}.
+     */
+    private getOrBuildGraph;
     /**
      * Trigger a full re-index of all tracked files.
      *
@@ -348,6 +499,60 @@ export declare class Gildash {
      * ```
      */
     searchRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+    /**
+     * Search symbols across all projects (no project filter).
+     *
+     * @param query - Search filters (see {@link SymbolSearchQuery}). The `project` field is ignored.
+     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the query fails.
+     */
+    searchAllSymbols(query: Omit<SymbolSearchQuery, 'project'> & {
+        project?: string;
+    }): Result<SymbolSearchResult[], GildashError>;
+    /**
+     * Search relations across all projects (no project filter).
+     *
+     * @param query - Search filters (see {@link RelationSearchQuery}). The `project` field is ignored.
+     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the query fails.
+     */
+    searchAllRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+    /**
+     * List all files indexed for a given project.
+     *
+     * @param project - Project name. Defaults to the primary project.
+     * @returns An array of {@link FileRecord} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='store'` if the repository query fails.
+     */
+    listIndexedFiles(project?: string): Result<FileRecord[], GildashError>;
+    /**
+     * Get all intra-file relations for a given file (relations where both source and destination
+     * are within the same file).
+     *
+     * @param filePath - Path of the file to query.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the query fails.
+     */
+    getInternalRelations(filePath: string, project?: string): Result<CodeRelation[], GildashError>;
+    /**
+     * Compare two snapshots of symbol search results and return a structured diff.
+     *
+     * Symbols are keyed by `name::filePath`. A symbol is:
+     * - **added** if it appears only in `after`
+     * - **removed** if it appears only in `before`
+     * - **modified** if it appears in both but with a different `fingerprint`
+     * - **unchanged** otherwise
+     *
+     * @param before - Snapshot of symbols before the change.
+     * @param after - Snapshot of symbols after the change.
+     * @returns A {@link SymbolDiff} object.
+     */
+    diffSymbols(before: SymbolSearchResult[], after: SymbolSearchResult[]): SymbolDiff;
     /**
      * List the files that a given file directly imports.
      *
@@ -422,6 +627,177 @@ export declare class Gildash {
      * ```
      */
     hasCycle(project?: string): Promise<Result<boolean, GildashError>>;
+    /**
+     * Return the full import graph for a project as an adjacency list.
+     *
+     * Builds a {@link DependencyGraph} and exposes its internal adjacency list.
+     * Each file appears as a key; its value lists the files it directly imports.
+     * Files that are imported but do not themselves import appear as keys with empty arrays.
+     *
+     * @param project - Project name. Defaults to the primary project.
+     * @returns A `Map<filePath, importedFilePaths[]>`, or `Err<GildashError>` with
+     *   `type='closed'` / `type='search'`.
+     */
+    getImportGraph(project?: string): Promise<Result<Map<string, string[]>, GildashError>>;
+    /**
+     * Return all files that `filePath` transitively imports (forward BFS).
+     *
+     * @param filePath - Absolute path of the starting file.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns An array of file paths that `filePath` directly or indirectly imports,
+     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
+     */
+    getTransitiveDependencies(filePath: string, project?: string): Promise<Result<string[], GildashError>>;
+    /**
+     * Return all cycle paths in the import graph.
+     *
+     * Uses DFS with canonical form deduplication.
+     *
+     * @param project - Project name. Defaults to the primary project.
+     * @returns An array of cycle paths (`string[][]`), each starting at the lexicographically
+     *   smallest node in the cycle. Returns `[]` if no cycles exist.
+     *   Returns `Err<GildashError>` with `type='closed'` / `type='search'`.
+     */
+    getCyclePaths(project?: string): Promise<Result<string[][], GildashError>>;
+    /**
+     * Find exported symbols that are never imported anywhere in the project.
+     *
+     * A symbol is considered "dead" if no `imports` or `re-exports` relation in the
+     * project references it by name (matching both `dstFilePath` and `dstSymbolName`).
+     * Exports from entry-point files are excluded by default.
+     *
+     * @param project - Project name. Defaults to the primary project.
+     * @param opts.entryPoints - File paths whose exports are excluded from dead-export detection.
+     *   Defaults to files named `index.ts`, `index.mts`, or `main.ts` anywhere in the project.
+     *   Pass `[]` to disable all entry-point filtering.
+     * @returns An array of `{ symbolName, filePath }` for dead exports,
+     *   or `Err<GildashError>` with `type='closed'` / `type='store'`.
+     */
+    getDeadExports(project?: string, opts?: {
+        entryPoints?: string[];
+    }): Result<Array<{
+        symbolName: string;
+        filePath: string;
+    }>, GildashError>;
+    /**
+     * Retrieve full details for a named symbol in a specific file,
+     * including members, documentation, and type information.
+     *
+     * @param symbolName - Exact symbol name to look up.
+     * @param filePath   - Absolute path of the file containing the symbol.
+     * @param project    - Project scope override (defaults to `defaultProject`).
+     * @returns A {@link FullSymbol} on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the symbol is not found or the query fails.
+     */
+    getFullSymbol(symbolName: string, filePath: string, project?: string): Result<FullSymbol, GildashError>;
+    /**
+     * Retrieve statistics for an indexed file (line count, symbol count, etc.).
+     *
+     * @param filePath - Absolute path of the file to query.
+     * @param project  - Project scope override (defaults to `defaultProject`).
+     * @returns A {@link FileStats} on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the file is not in the index,
+     *   `type='store'` if the query throws.
+     */
+    getFileStats(filePath: string, project?: string): Result<FileStats, GildashError>;
+    /**
+     * Compute import-graph fan metrics (fan-in / fan-out) for a single file.
+     *
+     * Builds a full {@link DependencyGraph} each call (O(relations)).
+     * For repeated calls, consider caching the graph externally.
+     *
+     * @param filePath - Absolute path of the file to query.
+     * @param project  - Project scope override (defaults to `defaultProject`).
+     * @returns A {@link FanMetrics} on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the graph build fails.
+     */
+    getFanMetrics(filePath: string, project?: string): Promise<Result<FanMetrics, GildashError>>;
+    /**
+     * Resolve the original definition location of a symbol by following its re-export chain.
+     *
+     * Traverses `re-exports` relations iteratively until no further hop is found or a
+     * circular chain is detected.
+     *
+     * @param symbolName - The exported name to resolve.
+     * @param filePath   - The file from which the symbol is exported.
+     * @param project    - Project scope override (defaults to `defaultProject`).
+     * @returns A {@link ResolvedSymbol} on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if a circular re-export chain is detected.
+     */
+    resolveSymbol(symbolName: string, filePath: string, project?: string): Result<ResolvedSymbol, GildashError>;
+    /**
+     * Search for an AST structural pattern across indexed TypeScript files.
+     *
+     * Uses ast-grep's `findInFiles` under the hood. Provide `opts.filePaths` to
+     * limit search scope; otherwise all files tracked by the project index are searched.
+     *
+     * @param pattern   - ast-grep structural pattern (e.g. `'console.log($$$)'`).
+     * @param opts      - Optional scope: file paths and/or project override.
+     * @returns An array of {@link PatternMatch} on success, or `Err<GildashError>` with
+     *   `type='closed'` if the instance is closed,
+     *   `type='search'` if the underlying search fails.
+     */
+    findPattern(pattern: string, opts?: {
+        filePaths?: string[];
+        project?: string;
+    }): Promise<Result<PatternMatch[], GildashError>>;
+    /**
+     * Index the TypeScript type declarations (`.d.ts` files) of one or more
+     * `node_modules` packages.
+     *
+     * Each package is indexed under a dedicated `@external/<packageName>` project
+     * so it does not pollute the main project index. Subsequent calls re-index
+     * (incremental diff) the same package.
+     *
+     * @param packages - Package names as they appear in `node_modules/`
+     *   (e.g. `['react', 'typescript']`).
+     * @param opts     - Optional overrides (unused currently, reserved for future use).
+     * @returns An array of {@link IndexResult} — one per package — on success,
+     *   or `Err<GildashError>` with:
+     *   - `type='closed'` if the instance is closed or in reader mode,
+     *   - `type='validation'` if a requested package is not found in `node_modules/`,
+     *   - `type='store'` if indexing fails at runtime.
+     */
+    indexExternalPackages(packages: string[], opts?: {
+        project?: string;
+    }): Promise<Result<IndexResult[], GildashError>>;
+    /**
+     * Parse multiple files concurrently and return a map of results.
+     *
+     * Files that fail to read or parse are silently excluded from the result map.
+     * The operation does not fail even if every file fails — it returns an empty `Map`.
+     *
+     * @param filePaths - Absolute paths of files to parse.
+     * @returns A `Map<filePath, ParsedFile>` for every successfully-parsed file,
+     *   or `Err<GildashError>` with `type='closed'` if the instance is closed.
+     */
+    batchParse(filePaths: string[]): Promise<Result<Map<string, ParsedFile>, GildashError>>;
+    /**
+     * Return the public interface of a module: all exported symbols with key metadata.
+     *
+     * @param filePath - Absolute path of the file.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns A {@link ModuleInterface} object, or `Err<GildashError>` with
+     *   `type='closed'` / `type='search'`.
+     */
+    getModuleInterface(filePath: string, project?: string): Result<ModuleInterface, GildashError>;
+    /**
+     * Recursively traverse `extends`/`implements` relations to build a heritage tree.
+     *
+     * The root node represents `symbolName`/`filePath`. Its `children` are the symbols
+     * it extends or implements, and so on transitively. A visited set prevents cycles.
+     *
+     * @param symbolName - Name of the starting symbol.
+     * @param filePath - Absolute path of the file containing the symbol.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns A {@link HeritageNode} tree, or `Err<GildashError>` with
+     *   `type='closed'` / `type='search'`.
+     */
+    getHeritageChain(symbolName: string, filePath: string, project?: string): Promise<Result<HeritageNode, GildashError>>;
     /**
      * Retrieve a previously-parsed AST from the internal LRU cache.
      *

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { Gildash } from "./gildash";
-export type { GildashOptions, Logger } from "./gildash";
+export type { GildashOptions, Logger, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol } from "./gildash";
 export { gildashError } from "./errors";
 export type { GildashError, GildashErrorType } from "./errors";
 export { symbolSearch } from "./search/symbol-search";
@@ -7,6 +7,8 @@ export type { SymbolSearchQuery, SymbolSearchResult } from "./search/symbol-sear
 export { relationSearch } from "./search/relation-search";
 export type { RelationSearchQuery } from "./search/relation-search";
 export { DependencyGraph } from "./search/dependency-graph";
+export { patternSearch } from "./search/pattern-search";
+export type { PatternMatch, PatternSearchOptions } from "./search/pattern-search";
 export type { IndexResult } from "./indexer/index-coordinator";
 export type { ProjectBoundary } from "./common/project-discovery";
 export type { CodeRelation, SymbolKind } from "./extractor/types";

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

@@ -31,6 +31,27 @@ export interface IndexResult {
     deletedFiles: string[];
     /** Absolute paths of files that failed to index. */
     failedFiles: string[];
+    /**
+     * Symbol-level diff compared to the previous index state.
+     * On the very first full index (empty DB), all symbols appear in `added`.
+     */
+    changedSymbols: {
+        added: Array<{
+            name: string;
+            filePath: string;
+            kind: string;
+        }>;
+        modified: Array<{
+            name: string;
+            filePath: string;
+            kind: string;
+        }>;
+        removed: Array<{
+            name: string;
+            filePath: string;
+            kind: string;
+        }>;
+    };
 }
 export interface IndexCoordinatorOptions {
     projectRoot: string;

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

@@ -68,4 +68,32 @@ export declare class DependencyGraph {
      * @returns Paths of all transitively-dependent files.
      */
     getAffectedByChange(changedFiles: string[]): string[];
+    /**
+     * Return the full import graph as an adjacency list.
+     *
+     * Each key is a file path (both source and destination files are included as keys).
+     * The associated value lists the files it directly imports.
+     *
+     * @returns A new `Map<filePath, importedFilePaths[]>`.
+     */
+    getAdjacencyList(): Map<string, string[]>;
+    /**
+     * Return all files that `filePath` transitively imports
+     * (breadth-first forward walk).
+     *
+     * @param filePath - Absolute file path.
+     * @returns Paths of all transitively-imported files. Does not include `filePath` itself
+     *   unless a cycle exists.
+     */
+    getTransitiveDependencies(filePath: string): string[];
+    /**
+     * Return the distinct cycle paths in the import graph.
+     *
+     * Each cycle is represented as a list of file paths in canonical form
+     * (rotated so the lexicographically smallest node comes first).
+     * Duplicate cycles are deduplicated.
+     *
+     * @returns An array of cycles, where each cycle is a `string[]` of file paths.
+     */
+    getCyclePaths(): string[][];
 }

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

@@ -4,3 +4,5 @@ export { relationSearch } from './relation-search';
 export type { RelationSearchQuery, IRelationRepo } from './relation-search';
 export { DependencyGraph } from './dependency-graph';
 export type { IDependencyGraphRepo } from './dependency-graph';
+export { patternSearch } from './pattern-search';
+export type { PatternMatch, PatternSearchOptions } from './pattern-search';

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

@@ -0,0 +1,30 @@
+/**
+ * A single structural-pattern match found in a source file.
+ */
+export interface PatternMatch {
+    /** Absolute path of the file containing the match. */
+    filePath: string;
+    /** 1-based start line number of the matched node. */
+    startLine: number;
+    /** 1-based end line number of the matched node. */
+    endLine: number;
+    /** Source text of the matched node. */
+    matchedText: string;
+}
+/**
+ * Options for {@link patternSearch}.
+ */
+export interface PatternSearchOptions {
+    /** An ast-grep structural pattern string (e.g. `'console.log($$$)'`). */
+    pattern: string;
+    /** Absolute file paths (or directories) to search within. */
+    filePaths: string[];
+}
+/**
+ * Search for a structural AST pattern across a set of TypeScript/TSX files
+ * using ast-grep's `findInFiles` API.
+ *
+ * @param opts - Pattern and file paths to search.
+ * @returns An array of {@link PatternMatch} entries for all matching nodes.
+ */
+export declare function patternSearch(opts: PatternSearchOptions): Promise<PatternMatch[]>;

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

@@ -20,6 +20,16 @@ export interface SymbolSearchQuery {
     project?: string;
     /** Maximum number of results. Defaults to `100`. */
     limit?: number;
+    /**
+     * Filter by decorator name (LEG-1).
+     * Restricts results to symbols annotated with this decorator (matched against `detailJson.decorators[].name`).
+     */
+    decorator?: string;
+    /**
+     * Filter by regex pattern applied to the symbol name (FR-19).
+     * Requires the `REGEXP` SQL function to be registered in the DB connection.
+     */
+    regex?: string;
 }
 /**
  * A single result returned by {@link symbolSearch}.
@@ -62,6 +72,8 @@ export interface ISymbolRepo {
         isExported?: boolean;
         project?: string;
         limit: number;
+        decorator?: string;
+        regex?: string;
     }): (SymbolRecord & {
         id: number;
     })[];

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

@@ -18,6 +18,8 @@ export interface FileRecord {
     contentHash: string;
     /** ISO 8601 timestamp of the last index update. */
     updatedAt: string;
+    /** Number of lines in the file at the time of indexing. */
+    lineCount?: number | null;
 }
 export declare class FileRepository {
     private readonly db;

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

@@ -48,6 +48,8 @@ export declare class SymbolRepository {
         isExported?: boolean;
         project?: string;
         limit: number;
+        decorator?: string;
+        regex?: string;
     }): (SymbolRecord & {
         id: number;
     })[];