zangief 0.1.1 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import * as llmist from 'llmist';
+import { LLMist, AgentBuilder } from 'llmist';
+
+/**
+ * SourcegraphExplorer agent factory.
+ */
+
+/**
+ * Creates a pre-configured agent for exploring code via Sourcegraph.
+ *
+ * The agent comes with all Sourcegraph gadgets and an optimized system
+ * prompt that explains query syntax and best practices.
+ *
+ * @param client - LLMist client instance
+ * @returns Configured AgentBuilder ready for use
+ *
+ * @example
+ * ```typescript
+ * import { LLMist } from 'llmist';
+ * import { createSourcegraphExplorer } from 'sourcegraph-search-gadget';
+ *
+ * const client = new LLMist();
+ * const result = await createSourcegraphExplorer(client)
+ *   .withModel('sonnet')
+ *   .askAndCollect('Find how React implements useState');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Streaming usage
+ * const agent = createSourcegraphExplorer(client)
+ *   .withModel('sonnet')
+ *   .ask('Explore the TypeScript compiler architecture');
+ *
+ * for await (const event of agent.run()) {
+ *   if (event.type === 'text') {
+ *     process.stdout.write(event.content);
+ *   }
+ * }
+ * ```
+ */
+declare function createSourcegraphExplorer(client: LLMist): AgentBuilder;
+
+/**
+ * System prompt for the SourcegraphExplorer agent.
+ */
+declare const SOURCEGRAPH_SYSTEM_PROMPT = "You are a code exploration assistant with access to Sourcegraph, a powerful code search engine that indexes millions of public repositories on GitHub.\n\n## Available Tools\n\nYou have 4 tools for exploring code:\n\n1. **SourcegraphSearch** - Search code across repositories\n   - Use for finding code patterns, functions, implementations\n   - Supports filters: repo:, lang:, file:, type:, case:\n\n2. **SourcegraphGetFile** - Read full file contents\n   - Use after finding interesting files via search\n   - Requires repo path and file path\n\n3. **SourcegraphListRepos** - List/search repositories\n   - Use to discover repositories before searching\n   - Filter by name patterns\n\n4. **SourcegraphCommitSearch** - Search commits and diffs\n   - Use type:commit for commit messages\n   - Use type:diff for code changes\n\n## Sourcegraph Query Syntax\n\n**Repository filters:**\n- `repo:github.com/org/repo` - Exact repo\n- `repo:^github.com/org/` - Regex (all repos in org)\n- `-repo:test` - Exclude repos matching pattern\n\n**Language and file filters:**\n- `lang:typescript` - Filter by language\n- `file:*.ts` - Filter by file pattern\n- `file:^src/` - Files in src directory\n\n**Search modifiers:**\n- `case:yes` - Case sensitive\n- `count:100` - Return up to 100 results\n- `type:symbol` - Search symbols only\n- `type:commit` - Search commit messages\n- `type:diff` - Search diffs\n\n**Boolean operators:**\n- `AND` or space - Both terms required\n- `OR` - Either term\n- `NOT` or `-` - Exclude term\n\n## Best Practices\n\n1. **Start broad, then narrow** - Begin with a general search, then add filters\n2. **Use language filters** - `lang:typescript` dramatically improves results\n3. **Specify repos when possible** - `repo:github.com/facebook/react` for targeted searches\n4. **Read files after finding them** - Use SourcegraphGetFile to see full context\n5. **Search commits for history** - Use type:commit to understand changes over time\n\n## Example Workflow\n\n1. List repos in an organization:\n   `SourcegraphListRepos({ query: \"github.com/facebook/\" })`\n\n2. Search for specific code:\n   `SourcegraphSearch({ query: \"useState lang:typescript repo:github.com/facebook/react\" })`\n\n3. Read interesting files:\n   `SourcegraphGetFile({ repo: \"github.com/facebook/react\", path: \"packages/react/src/ReactHooks.js\" })`\n\n4. Check commit history:\n   `SourcegraphCommitSearch({ query: \"type:commit useState repo:github.com/facebook/react\" })`\n";
+
+/**
+ * SourcegraphSearch gadget - Search code across public GitHub repos.
+ */
+declare const sourcegraphSearch: llmist.AbstractGadget;
+
+/**
+ * SourcegraphGetFile gadget - Fetch file contents from a repository.
+ */
+declare const sourcegraphGetFile: llmist.AbstractGadget;
+
+/**
+ * SourcegraphListRepos gadget - List and search repositories.
+ */
+declare const sourcegraphListRepos: llmist.AbstractGadget;
+
+/**
+ * SourcegraphCommitSearch gadget - Search commits and diffs.
+ */
+declare const sourcegraphCommitSearch: llmist.AbstractGadget;
+
+/**
+ * Array of all Sourcegraph gadgets for easy registration.
+ *
+ * @example
+ * ```typescript
+ * import { sourcegraphGadgets } from 'sourcegraph-search-gadget';
+ *
+ * const agent = LLMist.createAgent()
+ *   .withGadgets(...sourcegraphGadgets)
+ *   .ask('Search for React hooks');
+ * ```
+ */
+declare const sourcegraphGadgets: readonly [llmist.AbstractGadget, llmist.AbstractGadget, llmist.AbstractGadget, llmist.AbstractGadget];
+
+/**
+ * TypeScript interfaces for Sourcegraph GraphQL API responses.
+ */
+interface SearchResult {
+    search: {
+        results: {
+            matchCount: number;
+            limitHit: boolean;
+            cloning: Array<{
+                name: string;
+            }>;
+            missing: Array<{
+                name: string;
+            }>;
+            timedout: Array<{
+                name: string;
+            }>;
+            results: Array<FileMatch | CommitMatch | RepoMatch>;
+        };
+    };
+}
+interface FileMatch {
+    __typename: "FileMatch";
+    repository: {
+        name: string;
+        url: string;
+    };
+    file: {
+        path: string;
+        url: string;
+    };
+    lineMatches: Array<{
+        lineNumber: number;
+        preview: string;
+        offsetAndLengths: Array<[number, number]>;
+    }>;
+    chunkMatches?: Array<{
+        content: string;
+        contentStart: {
+            line: number;
+        };
+        ranges: Array<{
+            start: {
+                line: number;
+            };
+            end: {
+                line: number;
+            };
+        }>;
+    }>;
+}
+interface CommitMatch {
+    __typename: "CommitSearchResult";
+    commit: {
+        oid: string;
+        abbreviatedOID: string;
+        message: string;
+        subject: string;
+        body: string | null;
+        author: {
+            person: {
+                displayName: string;
+                email: string;
+            };
+            date: string;
+        };
+        url: string;
+        repository: {
+            name: string;
+            url: string;
+        };
+    };
+    matches?: Array<{
+        body: {
+            text: string;
+        };
+    }>;
+}
+interface RepoMatch {
+    __typename: "Repository";
+    name: string;
+    url: string;
+    description: string;
+}
+interface FileContentResult {
+    repository: {
+        commit: {
+            file: {
+                content: string;
+                byteSize: number;
+                richHTML?: string;
+            } | null;
+        } | null;
+    } | null;
+}
+interface RepositoryListResult {
+    repositories: {
+        nodes: Array<{
+            name: string;
+            description: string;
+            url: string;
+            externalURLs: Array<{
+                url: string;
+                serviceKind: string;
+            }>;
+            defaultBranch: {
+                name: string;
+            } | null;
+        }>;
+        totalCount: number;
+        pageInfo: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+        };
+    };
+}
+
+declare class SourcegraphClientError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly graphqlErrors?: Array<{
+        message: string;
+    }> | undefined;
+    constructor(message: string, statusCode?: number | undefined, graphqlErrors?: Array<{
+        message: string;
+    }> | undefined);
+}
+declare function sourcegraphQuery<T>(query: string, variables?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+
+export { type CommitMatch, type FileContentResult, type FileMatch, type RepoMatch, type RepositoryListResult, SOURCEGRAPH_SYSTEM_PROMPT, type SearchResult, SourcegraphClientError, createSourcegraphExplorer, sourcegraphCommitSearch, sourcegraphGadgets, sourcegraphGetFile, sourcegraphListRepos, sourcegraphQuery, sourcegraphSearch };