octocode-cli 1.1.1 → 1.2.0

package/skills/octocode-implement/references/tool-reference.md

@@ -0,0 +1,403 @@
+# Tool Reference - Implementation Agent
+
+Complete parameter reference for implementation-focused tool usage.
+
+**Required Fields (ALL queries)**: `mainResearchGoal`, `researchGoal`, `reasoning`
+
+---
+
+## Local Tools (PRIMARY - Always Prefer)
+
+### localViewStructure
+
+Map codebase architecture before diving in.
+
+```typescript
+{
+  path: string;                    // Directory path (required)
+  depth?: number;                  // 1-5 (default 1)
+  entriesPerPage?: number;         // ≤20
+  entryPageNumber?: number;        // Pagination
+  details?: boolean;               // Show file sizes
+  hidden?: boolean;                // Include dotfiles
+  extensions?: string[];           // Filter by extension
+  pattern?: string;                // Filter by name pattern
+  filesOnly?: boolean;
+  directoriesOnly?: boolean;
+  sortBy?: "name" | "size" | "time" | "extension";
+}
+```
+
+**Implementation Tips:**
+- Start `depth: 1` at root to understand project structure
+- Use `depth: 2` on `src/` to see feature organization
+- Check for monorepo patterns: `packages/`, `apps/`, `libs/`
+- Note test directory structure for later
+
+---
+
+### localSearchCode
+
+Find implementations, usages, and patterns.
+
+```typescript
+{
+  pattern: string;                 // Search pattern (required)
+  path: string;                    // Search root (required)
+  filesOnly?: boolean;             // Discovery mode - list files only
+  type?: string;                   // "ts", "py", "js" etc
+  include?: string[];              // Glob patterns to include
+  exclude?: string[];              // Glob patterns to exclude
+  excludeDir?: string[];           // Directories to skip
+  noIgnore?: boolean;              // Search inside node_modules
+  matchesPerPage?: number;         // 1-100
+  filesPerPage?: number;           // ≤20
+  filePageNumber?: number;         // Pagination
+  contextLines?: number;           // Lines around match
+  caseSensitive?: boolean;
+  wholeWord?: boolean;
+  multiline?: boolean;
+}
+```
+
+**Implementation Tips:**
+- `filesOnly: true` first for discovery (fast, token-efficient)
+- Search for similar features: `export.*function.*CreateUser`
+- Find tests: `describe.*"UserService"`
+- Find types: `interface.*User|type.*User`
+- Use `contextLines: 3` to see surrounding code
+
+**Pattern Search Examples:**
+```typescript
+// Find feature implementations
+{ pattern: "export class.*Service", path: "src", type: "ts", filesOnly: true }
+
+// Find tests for a feature
+{ pattern: "describe.*UserService", path: "tests", type: "ts" }
+
+// Find error handling patterns
+{ pattern: "catch.*Error|throw new", path: "src", type: "ts" }
+
+// Find API endpoints
+{ pattern: "@(Get|Post|Put|Delete)\\(", path: "src", type: "ts" }
+
+// Find React components
+{ pattern: "export.*function.*Component|export const.*:.*FC", path: "src", type: "tsx" }
+```
+
+---
+
+### localGetFileContent
+
+Read implementation details with precision.
+
+```typescript
+{
+  path: string;                    // File path (required)
+  // Choose ONE strategy:
+  matchString?: string;            // Pattern to find
+  matchStringContextLines?: number; // 1-50 lines of context
+  matchStringIsRegex?: boolean;
+  matchStringCaseSensitive?: boolean;
+  charOffset?: number;             // BYTE offset for pagination
+  charLength?: number;             // BYTES to read (2000-4000 recommended)
+  startLine?: number;              // Line range
+  endLine?: number;
+  fullContent?: boolean;           // Small files only (<100 lines)
+}
+```
+
+**Implementation Tips:**
+- Use `matchString` + `matchStringContextLines: 20` for functions
+- Use `startLine`/`endLine` when you know the location
+- `fullContent: true` only for small config files
+- For large files, use multiple `matchString` calls
+
+**Reading Examples:**
+```typescript
+// Read a specific function
+{ path: "src/service.ts", matchString: "async function processData", matchStringContextLines: 30 }
+
+// Read a class definition
+{ path: "src/models/User.ts", matchString: "export class User", matchStringContextLines: 50 }
+
+// Read test structure
+{ path: "tests/service.test.ts", matchString: "describe.*Service", matchStringContextLines: 40 }
+
+// Read config file entirely
+{ path: "tsconfig.json", fullContent: true }
+```
+
+---
+
+### localFindFiles
+
+Find files by metadata for targeted investigation.
+
+```typescript
+{
+  path: string;                    // Search root (required)
+  name?: string;                   // "*.ts" pattern
+  iname?: string;                  // Case-insensitive name
+  names?: string[];                // Multiple patterns
+  type?: "f" | "d" | "l";          // file/directory/link
+  modifiedWithin?: string;         // "7d", "2h", "30m"
+  modifiedBefore?: string;
+  sizeGreater?: string;            // "10M", "1K"
+  sizeLess?: string;
+  excludeDir?: string[];
+  maxDepth?: number;               // 1-10
+  filesPerPage?: number;           // ≤20
+  filePageNumber?: number;
+}
+```
+
+**Implementation Tips:**
+- Find recently changed files: `modifiedWithin: "1d"`
+- Find config files: `names: ["*.config.*", "*.json"]`
+- Find large files that might need breaking up: `sizeGreater: "200K"`
+
+---
+
+## LSP Tools (Semantic Code Intelligence)
+
+### lspGotoDefinition
+
+Navigate to symbol definitions - essential for tracing imports.
+
+```typescript
+{
+  uri: string;                     // File path (required)
+  symbolName: string;              // EXACT symbol name (required)
+  lineHint: number;                // 1-indexed line number (required)
+  orderHint?: number;              // 0-indexed if multiple on same line
+  contextLines?: number;           // Lines around definition (0-20)
+}
+```
+
+**Implementation Tips:**
+- Use when you see `import { X } from './module'` → trace X's definition
+- `lineHint` must be within ±2 lines of actual location
+- `symbolName` must be EXACT text, not partial
+
+**Example:**
+```typescript
+// Trace an import
+{ uri: "src/service.ts", symbolName: "UserRepository", lineHint: 3, contextLines: 10 }
+
+// Find type definition
+{ uri: "src/handlers/user.ts", symbolName: "UserDTO", lineHint: 5 }
+```
+
+---
+
+### lspFindReferences
+
+Find all usages of a symbol - critical for impact analysis.
+
+```typescript
+{
+  uri: string;                     // File path (required)
+  symbolName: string;              // EXACT symbol name (required)
+  lineHint: number;                // 1-indexed line (required)
+  includeDeclaration?: boolean;    // Include definition (default true)
+  orderHint?: number;
+  contextLines?: number;           // 0-10
+  referencesPerPage?: number;      // 1-50
+  page?: number;
+}
+```
+
+**Implementation Tips:**
+- **ALWAYS run before modifying public APIs**
+- Use `includeDeclaration: false` to see only usages
+- Check all pages if many references
+
+**Example:**
+```typescript
+// Find all usages of a function before changing it
+{ uri: "src/utils.ts", symbolName: "formatDate", lineHint: 15, includeDeclaration: false }
+
+// Find all callers of an API
+{ uri: "src/api/users.ts", symbolName: "getUser", lineHint: 42, contextLines: 3 }
+```
+
+---
+
+### lspCallHierarchy
+
+Trace function call relationships - understand data flow.
+
+```typescript
+{
+  uri: string;                     // File path (required)
+  symbolName: string;              // Function name (required)
+  lineHint: number;                // 1-indexed (required)
+  direction: "incoming" | "outgoing"; // (required)
+  depth?: number;                  // 1-3 (default 1)
+  orderHint?: number;
+  contextLines?: number;           // 0-10
+  callsPerPage?: number;           // 1-30
+  page?: number;
+}
+```
+
+**Implementation Tips:**
+- `direction: "incoming"` → "Who calls this function?"
+- `direction: "outgoing"` → "What does this function call?"
+- Use `depth: 2` to see transitive calls
+- Limit depth to avoid timeout on hot paths
+
+**Example:**
+```typescript
+// Who calls this function?
+{ uri: "src/auth/validate.ts", symbolName: "validateToken", lineHint: 20, direction: "incoming" }
+
+// What does this function depend on?
+{ uri: "src/handlers/order.ts", symbolName: "processOrder", lineHint: 50, direction: "outgoing", depth: 2 }
+```
+
+---
+
+## GitHub Tools (When Patterns Not Found Locally)
+
+### packageSearch
+
+Find package repo locations for upstream research.
+
+```typescript
+{
+  name: string;                    // Package name (required)
+  ecosystem: "npm" | "python";     // Registry (required)
+  searchLimit?: number;            // 1-10
+  npmFetchMetadata?: boolean;
+  pythonFetchMetadata?: boolean;
+}
+```
+
+**Use When:**
+- Need to understand how a dependency works internally
+- Looking for canonical implementation patterns
+- Debugging library behavior
+
+---
+
+### githubSearchCode
+
+Find patterns in external repositories.
+
+```typescript
+{
+  keywordsToSearch: string[];      // Search terms (required)
+  match: "file" | "path";          // Content vs paths (required)
+  owner?: string;                  // Org filter
+  repo?: string;                   // Repo filter
+  path?: string;                   // Directory filter
+  extension?: string;              // File type
+  filename?: string;
+  limit?: number;                  // 1-100
+}
+```
+
+**Use When:**
+- Can't find pattern in local codebase
+- Need reference implementation from upstream
+- Researching library usage patterns
+
+---
+
+### githubGetFileContent
+
+Read file content from GitHub repositories.
+
+```typescript
+{
+  owner: string;                   // (required)
+  repo: string;                    // (required)
+  path: string;                    // (required)
+  branch?: string;
+  matchString?: string;
+  matchStringContextLines?: number;
+  fullContent?: boolean;           // Small files only
+}
+```
+
+**Use When:**
+- Need to read upstream source code
+- Comparing local node_modules with canonical
+- Finding reference implementations
+
+---
+
+## Implementation-Specific Patterns
+
+### Before Modifying Any Code
+
+```typescript
+// 1. Find all references
+{ uri: "src/target.ts", symbolName: "functionToModify", lineHint: N, includeDeclaration: false }
+
+// 2. Understand incoming calls
+{ uri: "src/target.ts", symbolName: "functionToModify", lineHint: N, direction: "incoming" }
+
+// 3. Understand outgoing dependencies
+{ uri: "src/target.ts", symbolName: "functionToModify", lineHint: N, direction: "outgoing" }
+```
+
+### Finding Similar Implementations
+
+```typescript
+// 1. Search for similar features
+{ pattern: "export.*function.*Similar", path: "src", filesOnly: true }
+
+// 2. Read the implementation
+{ path: "src/found/file.ts", matchString: "export function similar", matchStringContextLines: 40 }
+
+// 3. Find its tests
+{ pattern: "describe.*Similar|test.*similar", path: "tests", filesOnly: true }
+```
+
+### Understanding Test Patterns
+
+```typescript
+// 1. Find test file
+{ pattern: "describe.*TargetFeature", path: "tests", type: "ts", filesOnly: true }
+
+// 2. Read test structure
+{ path: "tests/target.test.ts", matchString: "describe", matchStringContextLines: 50 }
+
+// 3. Find mock patterns
+{ pattern: "mock|jest\\.fn|vi\\.fn|spy", path: "tests/target.test.ts" }
+```
+
+---
+
+## Query Batching
+
+- Local tools: Max 5 queries per call
+- GitHub tools: Max 3 queries per call
+- LSP tools: Max 5 queries per call
+
+**Parallel Research Example:**
+```typescript
+{
+  "queries": [
+    { "pattern": "AuthService", "path": "src", "filesOnly": true },
+    { "pattern": "UserService", "path": "src", "filesOnly": true },
+    { "pattern": "describe.*Auth|describe.*User", "path": "tests", "filesOnly": true }
+  ]
+}
+```
+
+---
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Empty results | Try semantic variants, broaden path |
+| Too many results | Add filters (type, path, extension) |
+| File too large | Use `matchString` or `charLength` |
+| Symbol not found (LSP) | Verify exact name, check lineHint |
+| Definition in node_modules | Use `packageSearch` → GitHub tools |
+