@octocodeai/octocode-tools-core 16.5.1 → 16.6.0

package/dist/tools/lsp/shared/semanticTypes.d.ts

@@ -1,6 +1,6 @@
 import type { ExactPosition, LSPRange } from '@octocodeai/octocode-engine/lsp/types';
-export declare const LSP_GET_SEMANTIC_CONTENT_TOOL_NAME = "lspGetSemantics";
-export declare const SEMANTIC_CONTENT_TYPES: readonly ["definition", "references", "callers", "callees", "callHierarchy", "hover", "documentSymbols", "typeDefinition", "implementation"];
+export { LSP_GET_SEMANTIC_CONTENT_TOOL_NAME } from '../../toolNames.js';
+export declare const SEMANTIC_CONTENT_TYPES: readonly ["definition", "references", "callers", "callees", "callHierarchy", "hover", "documentSymbols", "typeDefinition", "implementation", "workspaceSymbol", "supertypes", "subtypes", "diagnostic"];
 export type SemanticContentType = (typeof SEMANTIC_CONTENT_TYPES)[number];
 export type SemanticOutputFormat = 'structured' | 'compact';
 export type SemanticQueryBase = {
@@ -17,7 +17,7 @@ export type SemanticQueryBase = {
     reasoning?: string;
 };
 export type SymbolAnchoredSemanticQuery = SemanticQueryBase & {
-    type: Exclude<SemanticContentType, 'documentSymbols'>;
+    type: Exclude<SemanticContentType, 'documentSymbols' | 'workspaceSymbol' | 'diagnostic'>;
     symbolName: string;
     lineHint: number;
     orderHint?: number;
@@ -28,7 +28,16 @@ export type SymbolAnchoredSemanticQuery = SemanticQueryBase & {
 export type DocumentSymbolsSemanticQuery = SemanticQueryBase & {
     type: 'documentSymbols';
 };
-export type LspGetSemanticsQuery = SymbolAnchoredSemanticQuery | DocumentSymbolsSemanticQuery;
+/** `workspace/symbol`: project-wide fuzzy symbol search. `symbolName` is the query string. */
+export type WorkspaceSymbolSemanticQuery = SemanticQueryBase & {
+    type: 'workspaceSymbol';
+    symbolName: string;
+};
+/** `textDocument/diagnostic` (pull): errors/warnings for a file without a position anchor. */
+export type DiagnosticSemanticQuery = SemanticQueryBase & {
+    type: 'diagnostic';
+};
+export type LspGetSemanticsQuery = SymbolAnchoredSemanticQuery | DocumentSymbolsSemanticQuery | WorkspaceSymbolSemanticQuery | DiagnosticSemanticQuery;
 export type ResolvedSymbol = {
     name: string;
     uri: string;
@@ -65,7 +74,7 @@ export declare function compactLocation(snippet: {
     };
     isDefinition?: boolean;
 }): CompactLocation;
-export type SemanticEmptyCategory = 'serverUnavailable' | 'unsupportedOperation' | 'symbolNotFound' | 'anchorFailed' | 'noLocations' | 'noReferences' | 'noHover' | 'noCalls';
+export type SemanticEmptyCategory = 'serverUnavailable' | 'unsupportedOperation' | 'symbolNotFound' | 'anchorFailed' | 'noLocations' | 'noReferences' | 'noHover' | 'noCalls' | 'noWorkspaceSymbols' | 'noTypeHierarchy' | 'noDiagnostics';
 export type SemanticEmptyState = {
     category: SemanticEmptyCategory;
     reason: string;
@@ -124,6 +133,26 @@ export type LspSemanticEnvelope = {
         totalSymbols?: number;
         topLevelSymbols?: number;
         empty?: SemanticEmptyState;
+    } | {
+        kind: 'workspaceSymbol';
+        query: string;
+        symbols: unknown[];
+        totalSymbols: number;
+        empty?: SemanticEmptyState;
+    } | {
+        kind: 'typeHierarchy';
+        direction: 'supertypes' | 'subtypes';
+        root?: unknown;
+        items: unknown[];
+        totalItems: number;
+        empty?: SemanticEmptyState;
+    } | {
+        kind: 'diagnostic';
+        diagnostics: unknown[];
+        totalDiagnostics: number;
+        errorCount: number;
+        warningCount: number;
+        empty?: SemanticEmptyState;
     } | {
         kind: 'empty';
         category: SemanticEmptyCategory;

package/dist/tools/oql_search/execution.d.ts

@@ -0,0 +1,7 @@
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+type OqlSearchToolInput = Record<string, unknown> & {
+    authInfo?: AuthInfo;
+};
+export declare function executeOqlSearchTool(input: OqlSearchToolInput): Promise<CallToolResult>;
+export {};

package/dist/tools/package_search/execution.d.ts

@@ -3,5 +3,15 @@ import type { z } from 'zod';
 import type { NpmPackageQuerySchema } from '@octocodeai/octocode-core/schemas';
 type NpmSearchQuery = z.input<typeof NpmPackageQuerySchema>;
 import type { ToolExecutionArgs } from '../../types/execution.js';
+type PackagePagination = {
+    currentPage: number;
+    totalPages: number;
+    perPage: number;
+    totalFound: number;
+    returned: number;
+    hasMore: boolean;
+    nextPage?: number;
+};
+export declare function buildPackagePagination(query: NpmSearchQuery, totalFound: number, returned: number, isKeyword: boolean): PackagePagination;
 export declare function searchPackages(args: ToolExecutionArgs<NpmSearchQuery>): Promise<CallToolResult>;
 export {};

package/dist/tools/providerMappers.d.ts

@@ -42,7 +42,7 @@ export declare function mapCodeSearchToolQuery(query: WithOptionalMeta<GitHubCod
     filename: string;
     extension: string;
     language: string | undefined;
-    match: "path" | "file";
+    match: "file" | "path";
     limit: number | undefined;
     page: number;
     mainResearchGoal: string;
@@ -101,7 +101,7 @@ export declare function mapRepoSearchToolQuery(query: WithOptionalMeta<GitHubRep
     forks: string | undefined;
     license: string | undefined;
     goodFirstIssues: string | undefined;
-    match: ("name" | "description" | "readme")[];
+    match: ("description" | "name" | "readme")[];
     sort: "stars" | "forks" | "updated" | "created" | "best-match" | undefined;
     limit: number | undefined;
     page: number;
@@ -138,18 +138,18 @@ export declare function mapPullRequestToolQuery(query: PartialPRQuery): {
     reactions: string;
     interactions: string;
     draft: boolean;
-    match: ("comments" | "title" | "body")[];
+    match: ("title" | "comments" | "body")[];
     milestone: string;
     language: string;
-    checks: "pending" | "success" | "failure";
-    review: "none" | "required" | "approved" | "changes_requested";
+    checks: "success" | "failure" | "pending";
+    review: "none" | "approved" | "changes_requested" | "required";
     locked: boolean;
     visibility: "public" | "private";
     teamMentions: string;
     project: string;
     archived: boolean | undefined;
     content: unknown;
-    reviewMode: "summary" | "full";
+    reviewMode: "full" | "summary";
     filePage: number;
     commentPage: number;
     commitPage: number;
@@ -217,7 +217,7 @@ export declare function mapPullRequestProviderResultData(data: ProviderPullReque
             in_reply_to_id?: number;
         }[];
         url: string;
-        state: "closed" | "open" | "merged";
+        state: "open" | "closed" | "merged";
         draft: boolean;
         author: string;
         assignees: string[];

package/dist/tools/toolConfig.d.ts

@@ -38,4 +38,5 @@ export declare const LOCAL_FIND_FILES: ToolConfig;
 export declare const LOCAL_FETCH_CONTENT: ToolConfig;
 export declare const LSP_GET_SEMANTIC_CONTENT: ToolConfig;
 export declare const LOCAL_BINARY_INSPECT: ToolConfig;
+export declare const OQL_SEARCH: ToolConfig;
 export declare const ALL_TOOLS: ToolConfig[];

package/dist/tools/toolNames.d.ts

@@ -1,2 +1,4 @@
 export declare const STATIC_TOOL_NAMES: import("@octocodeai/octocode-core/types").ToolNames;
+export declare const LSP_GET_SEMANTIC_CONTENT_TOOL_NAME: "lspGetSemantics";
+export declare const OQL_SEARCH_TOOL_NAME = "oqlSearch";
 export declare function isLocalTool(toolName: string): boolean;

package/dist/types/server.d.ts

@@ -7,7 +7,6 @@ export interface ServerConfig {
     disableTools?: string[];
     timeout: number;
     maxRetries: number;
-    loggingEnabled: boolean;
     enableLocal: boolean;
     enableClone: boolean;
     outputFormat: 'yaml' | 'json';

package/dist/types/session.d.ts

@@ -1,22 +1,3 @@
-export interface SessionData {
-    sessionId: string;
-    intent: 'init' | 'error' | 'tool_call' | 'rate_limit';
-    data: ToolCallData | ErrorData | RateLimitData | Record<string, never>;
-    timestamp: string;
-    version: string;
-}
-export interface ToolCallData {
-    tool_name: string;
-    repos: string[];
-    provider?: string;
-    mainResearchGoal?: string;
-    researchGoal?: string;
-    reasoning?: string;
-}
-export interface ErrorData {
-    error: string;
-    provider?: string;
-}
 export interface RateLimitData {
     limit_type: 'primary' | 'secondary' | 'graphql' | 'precheck_blocked';
     retry_after_seconds?: number;

package/dist/utils/contextUtils.d.ts

@@ -1,5 +1,5 @@
 import type * as NativeContextUtils from '@octocodeai/octocode-engine';
-export type { BinaryInspectInfo, BinaryStrings, ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, MinifyResult, JsonInput, RipgrepParseOptions, RipgrepParseResult, RipgrepSearchOptions, SliceContentOptions, SliceContentResult, StructuralMatch, YamlConversionConfig, } from '@octocodeai/octocode-engine';
+export type { BinaryInspectInfo, BinaryStrings, ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, GraphFactCapability, GraphFactCall, GraphFactDeclaration, GraphFactEdge, GraphFactExport, GraphFactImport, GraphFacts, MinifyResult, JsonInput, RipgrepParseOptions, RipgrepParseResult, RipgrepSearchOptions, SliceContentOptions, SliceContentResult, StructuralMatch, YamlConversionConfig, } from '@octocodeai/octocode-engine';
 type NativeContextUtilsModule = typeof NativeContextUtils;
 type NativeLoader = () => NativeContextUtilsModule;
 export declare class ContextUtilsLoadError extends Error {
@@ -28,11 +28,25 @@ export declare const contextUtils: {
      * Same-file only, syntax-only — no type inference, no cross-file resolution.
      */
     findInFileReferences(content: string, filePath: string, line: number, character: number): string | null;
+    /**
+     * Native JS/TS graph facts as a JSON `GraphFacts` object. Syntax-level only:
+     * declarations/imports/exports, containment, and direct call expressions.
+     */
+    extractGraphFacts(content: string, filePath: string): string | null;
     /**
      * Canonical lowercase extensions (no leading dot) the native oxc JS/TS path
      * handles. Source of truth lives in the engine — gate native dispatch on this.
      */
     getSupportedJsTsExtensions(): string[];
+    /**
+     * Canonical lowercase extensions (no leading dot) that can emit native
+     * GraphFacts. JS/TS use OXC; other entries use tree-sitter syntax inventory.
+     */
+    getSupportedGraphFactExtensions(): string[];
+    /**
+     * Native graph-fact capability matrix as a JSON `GraphFactCapability[]`.
+     */
+    getGraphFactCapabilities(): string;
     structuralSearch(content: string, filePath: string, pattern?: string | null, rule?: string | null): NativeContextUtils.StructuralMatch[];
     structuralSearchFiles(options: NativeContextUtils.StructuralSearchFilesOptions): NativeContextUtils.StructuralSearchFilesResult;
     getSupportedStructuralExtensions(): string[];

package/dist/utils/core/types.d.ts

@@ -44,7 +44,8 @@ export interface PaginationInfo {
     totalMatchesCapped?: boolean;
 }
 export interface SearchStats {
-    matchCount?: number;
+    totalOccurrences?: number;
+    totalStructuralMatches?: number;
     matchedLines?: number;
     filesMatched?: number;
     filesSearched?: number;

package/dist/utils/markdownOutline.d.ts

@@ -0,0 +1,10 @@
+export type MarkdownHeading = {
+    line: number;
+    level: number;
+    text: string;
+    children: MarkdownHeading[];
+};
+export declare function isMarkdownFilePath(filePath: string): boolean;
+export declare function extractMarkdownHeadingOutline(content: string, filePath: string): MarkdownHeading[] | null;
+export declare function markdownHeadingOutlineToText(content: string, filePath: string): string | null;
+export declare function markdownHeadingOutlineToDocumentSymbols(content: string, filePath: string): unknown[] | null;

package/dist/utils/response/groupedFinalizer.d.ts

@@ -1,35 +1,12 @@
 import type { BulkFinalizerOutput } from '../../types/bulk.js';
 import type { FlatQueryResult } from '../../types/toolResults.js';
-export type CharPagination = {
-    currentPage: number;
-    totalPages: number;
-    hasMore: boolean;
-    charOffset: number;
-    charLength: number;
-    totalChars: number;
-};
 export type QueryWithPagination = {
     id?: unknown;
     charLength?: unknown;
     charOffset?: unknown;
 };
-type CharWindowConfig<TGroup, TItem> = {
-    groups: TGroup[];
-    getItems: (group: TGroup) => readonly TItem[];
-    setItems: (group: TGroup, items: TItem[]) => TGroup;
-    getItemText?: (item: TItem) => string | undefined;
-    setItemText?: (item: TItem, text: string) => TItem;
-    charOffset: number;
-    charLength: number;
-    maxItems?: number;
-};
-export declare function paginateGroupsCharWindow<TGroup, TItem>({ groups, getItems, setItems, getItemText, setItemText, charOffset, charLength, maxItems, }: CharWindowConfig<TGroup, TItem>): {
-    groups: TGroup[];
-    pagination: CharPagination;
-};
 export declare function collectFlatErrors(results: readonly FlatQueryResult[]): Array<{
     id: string;
     error: string;
 }>;
 export declare function formatFinalizedResponse<T extends Record<string, unknown>>(responseData: T, keysPriority: readonly string[], isError?: boolean): BulkFinalizerOutput<T>;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octocodeai/octocode-tools-core",
-  "version": "16.5.1",
+  "version": "16.6.0",
   "description": "Core tool implementations for Octocode: GitHub, local filesystem, LSP, and package search tools.",
   "author": "Guy Bary <bgauryy@octocodeai.com>",
   "license": "MIT",
@@ -16,6 +16,14 @@
       "types": "./dist/direct.d.ts",
       "import": "./dist/direct.js"
     },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./oql": {
+      "types": "./dist/oql/index.d.ts",
+      "import": "./dist/oql/index.js"
+    },
     "./zod": {
       "types": "./dist/zod.d.ts",
       "import": "./dist/zod.js"
@@ -72,8 +80,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@octocodeai/octocode-core": "^16.5.1",
-    "@octocodeai/octocode-engine": "^16.5.1",
+    "@octocodeai/octocode-core": "^16.5.3",
+    "@octocodeai/octocode-engine": "^16.6.0",
     "@octokit/oauth-methods": "^6.0.2",
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/request": "^10.0.10",

package/dist/commands/BaseCommandBuilder.d.ts

@@ -1,14 +0,0 @@
-export declare abstract class BaseCommandBuilder {
-    protected command: string;
-    protected args: string[];
-    constructor(command: string);
-    addFlag(flag: string): this;
-    protected addOption(option: string, value: string | number): this;
-    protected addArg(arg: string): this;
-    build(): {
-        command: string;
-        args: string[];
-    };
-    reset(): this;
-    getArgs(): string[];
-}

package/dist/commands/FindCommandBuilder.d.ts

@@ -1,23 +0,0 @@
-import { BaseCommandBuilder } from './BaseCommandBuilder.js';
-import type { FindFilesQuery } from '../tools/local_find_files/scheme.js';
-export declare class FindCommandBuilder extends BaseCommandBuilder {
-    private isMacOS;
-    private isLinux;
-    private isWindows;
-    constructor();
-    fromQuery(query: Partial<FindFilesQuery> & Pick<FindFilesQuery, 'path'>): this;
-    private buildExcludeDirPrune;
-    private addFilters;
-    simple(path: string, name: string): this;
-    entryType(entryType: 'f' | 'd' | 'l'): this;
-    name(pattern: string): this;
-    maxDepth(depth: number): this;
-    minDepth(depth: number): this;
-    size(size: string): this;
-    mtime(time: string): this;
-    path(path: string): this;
-    private normalizeRegexForFullPath;
-    private parseTimeString;
-    private parseTimeStringAccess;
-    private normalizeSizeForPlatform;
-}

package/dist/commands/LsCommandBuilder.d.ts

@@ -1,15 +0,0 @@
-import { BaseCommandBuilder } from './BaseCommandBuilder.js';
-import type { ViewStructureQuery } from '../tools/local_view_structure/scheme.js';
-export declare class LsCommandBuilder extends BaseCommandBuilder {
-    constructor();
-    fromQuery(query: Partial<ViewStructureQuery> & Pick<ViewStructureQuery, 'path'>): this;
-    simple(path: string): this;
-    detailed(): this;
-    all(): this;
-    humanReadable(): this;
-    recursive(): this;
-    sortBySize(): this;
-    sortByTime(): this;
-    reverse(): this;
-    path(path: string): this;
-}

package/dist/shared/logger/index.d.ts

@@ -1,2 +0,0 @@
-export { createLogger, setLogHandler, _getLogHandler } from './logger.js';
-export type { LogLevel, LogEntry } from './logger.js';

package/dist/shared/logger/logger.d.ts

@@ -1,17 +0,0 @@
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-export interface LogEntry {
-    level: LogLevel;
-    module: string;
-    message: string;
-    data?: Record<string, unknown>;
-}
-type LogHandler = (entry: LogEntry) => void;
-export declare function setLogHandler(handler: LogHandler | null): void;
-export declare function _getLogHandler(): LogHandler | null;
-export declare function createLogger(module: string): {
-    debug: (message: string, data?: Record<string, unknown>) => void;
-    info: (message: string, data?: Record<string, unknown>) => void;
-    warn: (message: string, data?: Record<string, unknown>) => void;
-    error: (message: string, data?: Record<string, unknown>) => void;
-};
-export {};

package/dist/utils/pagination/outputSizeLimit.d.ts

@@ -1,16 +0,0 @@
-import type { PaginationInfo } from '../../types/toolResults.js';
-interface OutputSizeLimitOptions {
-    charOffset?: number;
-    charLength?: number;
-    maxOutputChars?: number;
-    recommendedCharLength?: number;
-}
-interface OutputSizeLimitResult {
-    content: string;
-    wasLimited: boolean;
-    pagination?: PaginationInfo;
-    warnings: string[];
-    paginationHints: string[];
-}
-export declare function applyOutputSizeLimit(content: string, options: OutputSizeLimitOptions): OutputSizeLimitResult;
-export {};

package/dist/utils/ranking/evidenceRanker.d.ts

@@ -1,86 +0,0 @@
-/**
- * Tier 2 — cross-source evidence fusion for code-research results.
- *
- * Raw LSP, structural-search, and code-search scores are not comparable. This
- * layer normalizes hits into `EvidenceItem`s, merges them into `EvidenceBundle`s
- * (one per useful target), fuses incomparable per-source ranks with weighted
- * Reciprocal Rank Fusion, reranks by task intent, diversifies, budgets for
- * tokens, and explains every result. See `.octocode/RANKING-ARCHITECTURE.md`.
- *
- * Determinism: no clock, no randomness. Sort is total via explicit
- * tie-breakers. Weak evidence is penalized but never silently dropped.
- */
-export interface Range {
-    startLine: number;
-    endLine?: number;
-}
-export type EvidenceSource = 'lsp' | 'structural' | 'codeSearch' | 'fileGraph' | 'signature' | 'contentView' | 'recentEdit' | 'testSignal' | 'diagnostic';
-export type EvidenceStatus = 'ok' | 'partial' | 'fallback' | 'ambiguous' | 'unsupported' | 'parserFailed' | 'truncated' | 'stale';
-export type EvidenceIntent = 'definition' | 'reference' | 'callsite' | 'declaration' | 'implementation' | 'test' | 'config' | 'doc' | 'schema' | 'route' | 'error' | 'unknown';
-export type EvidenceConfidence = 'high' | 'medium' | 'low';
-/** A measurement that can be mapped to a source weight (e.g. LSP fallback kind). */
-export type EvidenceQuality = 'exact' | 'detailed' | 'nearLineFallback' | 'wholeFileFallback' | 'partialAst' | 'fallbackText' | 'comment' | 'broadRegex';
-export interface EvidenceItem {
-    id: string;
-    source: EvidenceSource;
-    /** 1-based rank within this item's own source list (for RRF). */
-    sourceRank: number;
-    sourceScore?: number;
-    status: EvidenceStatus;
-    confidence: EvidenceConfidence;
-    intent: EvidenceIntent;
-    quality?: EvidenceQuality;
-    path: string;
-    range?: Range;
-    symbol?: string;
-    languageId?: string;
-    textPreview?: string;
-    tokenCost?: number;
-    reasons: string[];
-}
-export interface EvidenceBundle {
-    id: string;
-    target: {
-        path: string;
-        range?: Range;
-        symbol?: string;
-        languageId?: string;
-    };
-    primaryIntent: EvidenceIntent;
-    contributors: EvidenceItem[];
-    fusedScore: number;
-    finalScore: number;
-    confidence: EvidenceConfidence;
-    status: EvidenceStatus;
-    tokenCost: number;
-    reasons: string[];
-    warnings: string[];
-}
-export interface RankedEvidenceGroups {
-    mustRead: EvidenceBundle[];
-    supporting: EvidenceBundle[];
-    maybe: EvidenceBundle[];
-    weakOrSkipped: EvidenceBundle[];
-}
-export type RankTask = 'definition' | 'references' | 'edit' | 'explain' | 'security' | 'test' | 'generic';
-export interface RankEvidenceOptions {
-    task: RankTask;
-    seed?: {
-        path?: string;
-        range?: Range;
-        symbol?: string;
-        query?: string;
-    };
-    tokenBudget?: number;
-    maxBundles?: number;
-    includeWeak?: boolean;
-}
-export interface RankEvidenceResult {
-    groups: RankedEvidenceGroups;
-    allBundles: EvidenceBundle[];
-    scorerVersion: string;
-}
-export declare const SCORER_VERSION = "tier2-rrf-1";
-export declare function bundleEvidence(items: EvidenceItem[]): EvidenceBundle[];
-/** Rank a flat list of normalized evidence items into explained groups. */
-export declare function rankEvidence(items: EvidenceItem[], options: RankEvidenceOptions): RankEvidenceResult;

package/dist/utils/response/structuredPagination.d.ts

@@ -1,9 +0,0 @@
-import type { BulkToolResponse } from '../../types/bulk.js';
-import type { FlatQueryResult } from '../../types/toolResults.js';
-interface PaginationRequest {
-    offset?: number;
-    length?: number;
-}
-export declare function applyQueryOutputPagination(queryResult: FlatQueryResult, originalQuery: Record<string, unknown>, toolName: string): FlatQueryResult;
-export declare function applyBulkResponsePagination(response: BulkToolResponse, request: PaginationRequest, toolName: string): BulkToolResponse;
-export {};