@octocodeai/octocode-tools-core 16.6.2 → 17.0.1

package/dist/tools/github_search_repos/execution/pagination.d.ts

@@ -0,0 +1,39 @@
+import type { RepoSearchVariantExecution, RepoSearchVariantLabel, SuccessfulRepoSearchVariant } from './queryVariants.js';
+export declare function buildResultPagination(pagination: {
+    currentPage: number;
+    totalPages: number;
+    hasMore: boolean;
+    entriesPerPage?: number;
+    totalMatches?: number;
+    reportedTotalMatches?: number;
+    reachableTotalMatches?: number;
+    totalMatchesKind?: 'exact' | 'reported' | 'lowerBound';
+    totalMatchesCapped?: boolean;
+}): {
+    nextPage?: number;
+    hasMore: boolean;
+    totalMatchesCapped?: boolean;
+    totalMatchesKind?: "exact" | "reported" | "lowerBound";
+    reachableTotalMatches?: number;
+    reportedTotalMatches?: number;
+    totalMatches?: number;
+    currentPage: number;
+    totalPages: number;
+    perPage: number;
+};
+export type EffectivePagination = {
+    currentPage: number;
+    totalPages: number;
+    hasMore: boolean;
+    entriesPerPage?: number;
+    totalMatches?: number;
+    reportedTotalMatches?: number;
+    reachableTotalMatches?: number;
+    totalMatchesKind?: 'exact' | 'reported' | 'lowerBound';
+    totalMatchesCapped?: boolean;
+};
+export declare function buildPartialFailureWarnings(failedVariants: readonly {
+    label: RepoSearchVariantLabel;
+}[]): string[] | undefined;
+export declare function buildMergedPagination(variants: SuccessfulRepoSearchVariant[], dedupedCount: number): EffectivePagination | undefined;
+export declare function sumVariantRawResponseChars(variants: RepoSearchVariantExecution[]): number;

package/dist/tools/github_search_repos/execution/queryVariants.d.ts

@@ -0,0 +1,38 @@
+import type { z } from 'zod';
+import type { GitHubReposSearchSingleQuerySchema } from '@octocodeai/octocode-core/schemas';
+import type { RepoSearchResult as ProviderRepoSearchResult } from '../../../providers/types.js';
+import type { ProviderOperationResult } from '../../providerExecution.js';
+import type { WithOptionalMeta } from '../../../types/execution.js';
+type GitHubReposSearchSingleQuery = z.infer<typeof GitHubReposSearchSingleQuerySchema>;
+export type RepositorySearchExtraFields = {
+    archived?: boolean;
+    visibility?: 'public' | 'private';
+    forks?: string;
+    license?: string;
+    goodFirstIssues?: string;
+};
+export type PartialReposSearchQuery = WithOptionalMeta<GitHubReposSearchSingleQuery> & RepositorySearchExtraFields;
+export type RepoSearchVariantLabel = 'combined' | 'topics' | 'keywords';
+export interface RepoSearchVariant {
+    label: RepoSearchVariantLabel;
+    query: PartialReposSearchQuery;
+}
+export interface RepoSearchVariantExecution {
+    label: RepoSearchVariantLabel;
+    query: PartialReposSearchQuery;
+    response: ProviderOperationResult<RepoSearchVariant, ProviderRepoSearchResult>['response'];
+}
+export type SuccessfulRepoSearchVariant = RepoSearchVariantExecution & {
+    response: Extract<ProviderOperationResult<RepoSearchVariant, ProviderRepoSearchResult>, {
+        response: {
+            data: ProviderRepoSearchResult;
+        };
+    }>['response'] & {
+        data: ProviderRepoSearchResult;
+    };
+};
+export declare function hasValidTopics(query: PartialReposSearchQuery): boolean;
+export declare function hasValidKeywords(query: PartialReposSearchQuery): boolean;
+export declare function hasValidRepositorySearchParams(query: PartialReposSearchQuery): boolean;
+export declare function createSearchVariants(query: PartialReposSearchQuery): RepoSearchVariant[];
+export {};

package/dist/tools/github_search_repos/execution/ranking.d.ts

@@ -0,0 +1,4 @@
+import type { GitHubRepositoryOutput } from '@octocodeai/octocode-core/extra-types';
+import type { PartialReposSearchQuery } from './queryVariants.js';
+export declare function deduplicateRepositories(repositories: GitHubRepositoryOutput[]): GitHubRepositoryOutput[];
+export declare function rankRepositoriesByRelevance(repositories: readonly GitHubRepositoryOutput[], query: PartialReposSearchQuery): GitHubRepositoryOutput[];

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

@@ -1,17 +1,7 @@
 import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import type { z } from 'zod';
-import type { GitHubReposSearchSingleQuerySchema } from '@octocodeai/octocode-core/schemas';
 import type { GitHubRepositoryOutput } from '@octocodeai/octocode-core/extra-types';
-type GitHubReposSearchSingleQuery = z.infer<typeof GitHubReposSearchSingleQuerySchema>;
-import type { ToolExecutionArgs, WithOptionalMeta } from '../../types/execution.js';
-type RepositorySearchExtraFields = {
-    archived?: boolean;
-    visibility?: 'public' | 'private';
-    forks?: string;
-    license?: string;
-    goodFirstIssues?: string;
-};
-type PartialReposSearchQuery = WithOptionalMeta<GitHubReposSearchSingleQuery> & RepositorySearchExtraFields;
+import type { ToolExecutionArgs } from '../../types/execution.js';
+import { type PartialReposSearchQuery } from './execution/queryVariants.js';
+export { buildMergedPagination, buildPartialFailureWarnings, buildResultPagination, } from './execution/pagination.js';
 export declare function formatRepoLine(repo: GitHubRepositoryOutput): string;
 export declare function searchMultipleGitHubRepos(args: ToolExecutionArgs<PartialReposSearchQuery>): Promise<CallToolResult>;
-export {};

package/dist/tools/github_search_repos/scheme.d.ts

@@ -68,21 +68,26 @@ export declare const GitHubSearchRepositoriesOutputLocalSchema: z.ZodObject<{
                 currentPage: z.ZodNumber;
                 totalPages: z.ZodNumber;
                 hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
                 perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
                 totalMatches: z.ZodOptional<z.ZodNumber>;
                 reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
                 reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
                 totalMatchesKind: z.ZodOptional<z.ZodEnum<{
                     exact: "exact";
                     reported: "reported";
                     lowerBound: "lowerBound";
                 }>>;
                 totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
-                nextPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$loose>>;
     }, z.core.$loose>>>;
-    hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     base: z.ZodOptional<z.ZodString>;
     shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     responsePagination: z.ZodOptional<z.ZodObject<{

package/dist/tools/github_view_repo_structure/scheme.d.ts

@@ -70,7 +70,6 @@ export declare const GitHubViewRepoStructureOutputLocalSchema: import("zod").Zod
         kind: import("zod").ZodString;
     }, import("zod/v4/core").$loose>]>>>;
     error: import("zod").ZodOptional<import("zod").ZodString>;
-    hints: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
     base: import("zod").ZodOptional<import("zod").ZodString>;
     shared: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodNumber, import("zod").ZodBoolean]>>>;
     responsePagination: import("zod").ZodOptional<import("zod").ZodObject<{

package/dist/tools/github_view_repo_structure/types.d.ts

@@ -15,6 +15,8 @@ export interface GitHubRepositoryStructureResult {
         truncated: boolean;
         filtered: boolean;
         originalCount: number;
+        /** True when Git Trees reported truncation — listing may be incomplete. */
+        incompleteTree?: boolean;
     };
     structure: Record<string, GitHubRepoStructureDirectoryEntry>;
     fileSizeMap?: Record<string, Record<string, number>>;

package/dist/tools/local_fetch_content/fetchContent/extraction.d.ts

@@ -0,0 +1,15 @@
+import type { LocalGetFileContentToolResult } from '@octocodeai/octocode-core/extra-types';
+import type { FetchContentQuery } from '../scheme.js';
+export interface ExtractionState {
+    resultContent?: string;
+    isPartial: boolean;
+    actualStartLine?: number;
+    actualEndLine?: number;
+    matchRanges?: Array<{
+        start: number;
+        end: number;
+    }>;
+    warnings?: string[];
+    earlyResult?: LocalGetFileContentToolResult;
+}
+export declare function buildExtractionState(query: FetchContentQuery, content: string, _defaultOutputCharLength: number): ExtractionState;

package/dist/tools/local_fetch_content/fetchContent/pagination.d.ts

@@ -0,0 +1,38 @@
+import { applyPagination } from '../../../utils/pagination/core.js';
+import type { LocalGetFileContentToolResult } from '@octocodeai/octocode-core/extra-types';
+import type { FetchContentQuery } from '../scheme.js';
+import { type FileStats } from './validation.js';
+import type { ExtractionState } from './extraction.js';
+export type ContentView = 'none' | 'standard' | 'symbols';
+export interface ContentWindow {
+    /** The windowed (paginated) slice of the input content. */
+    windowedContent: string;
+    pagination: ReturnType<typeof applyPagination>;
+    /** Requested/auto page size (undefined when no windowing applies). */
+    effectiveCharLength: number | undefined;
+    /** Explicit charOffset requested by the caller (0 when absent). */
+    explicitCharOffset: number;
+    autoPaginated: boolean;
+    /** Warning emitted when the content was auto-paginated (else undefined). */
+    autoPaginateWarning?: string;
+    chunkMode: 'semantic' | 'char-limit';
+    nextBlockChar?: number;
+    /** Ready continuation query for the next char page (undefined when !hasMore). */
+    next?: {
+        continueChars: {
+            tool: 'localGetFileContent';
+            query: {
+                path: string;
+                charOffset: number;
+                charLength: number;
+                minify: FetchContentQuery['minify'];
+            };
+        };
+    };
+    /** Whether pagination fields should be emitted on the result. */
+    showPagination: boolean;
+}
+export declare function paginateContentWindow(content: string, query: FetchContentQuery, defaultOutputCharLength: number): Promise<ContentWindow>;
+export declare function buildSuccessResult(query: FetchContentQuery, extraction: ExtractionState, fileStats: FileStats, totalLines: number, defaultOutputCharLength: number, shouldMinify?: boolean, contentView?: ContentView): Promise<LocalGetFileContentToolResult>;
+export declare function buildSymbolsSkeletonResult(query: FetchContentQuery, skeleton: string, totalLines: number, sourceChars: number, sourceBytes: number, secretWarning: string | undefined, defaultOutputCharLength: number): Promise<LocalGetFileContentToolResult>;
+export declare function withContentView(result: LocalGetFileContentToolResult, contentView: ContentView): LocalGetFileContentToolResult;

package/dist/tools/local_fetch_content/fetchContent/validation.d.ts

@@ -0,0 +1,26 @@
+import { stat } from 'fs/promises';
+import type { LocalGetFileContentToolResult } from '@octocodeai/octocode-core/extra-types';
+import type { FetchContentQuery } from '../scheme.js';
+export type FileStats = NonNullable<Awaited<ReturnType<typeof stat>>>;
+export declare function sourceSizeFields(sourceChars: number, sourceBytes: number): {
+    sourceChars: number;
+    sourceBytes: number;
+} | {
+    sourceChars: number;
+    sourceBytes?: undefined;
+};
+export declare function withSourceSize(result: LocalGetFileContentToolResult, sourceChars: number, sourceBytes: number): LocalGetFileContentToolResult;
+export declare function validateExtractionOptions(query: FetchContentQuery): LocalGetFileContentToolResult | null;
+export declare function getFileStatsOrError(query: FetchContentQuery, absolutePath: string): Promise<{
+    fileStats?: FileStats;
+    errorResult?: LocalGetFileContentToolResult;
+}>;
+export declare function shouldFailForLargeFile(query: FetchContentQuery, fileSizeKB: number): boolean;
+export declare function createLargeFileErrorResult(query: FetchContentQuery, absolutePath: string, fileSizeKB: number): LocalGetFileContentToolResult;
+export declare function createBinaryFileErrorResult(query: FetchContentQuery, absolutePath: string): LocalGetFileContentToolResult;
+export declare function isLikelyBinaryFile(filePath: string): Promise<boolean>;
+export declare function readFileContentOrError(query: FetchContentQuery, absolutePath: string): Promise<{
+    content?: string;
+    errorResult?: LocalGetFileContentToolResult;
+}>;
+export declare function createNoMatchesResult(_query: FetchContentQuery, totalLines: number): LocalGetFileContentToolResult;

package/dist/tools/local_fetch_content/fetchContent.d.ts

@@ -1,4 +1,6 @@
 import type { LocalGetFileContentToolResult } from '@octocodeai/octocode-core/extra-types';
 import type { FetchContentQuery } from './scheme.js';
+import { type ContentView } from './fetchContent/pagination.js';
+export type { ContentView };
 export declare function fetchContent(query: FetchContentQuery): Promise<LocalGetFileContentToolResult>;
 export declare function finalizeFetchContentResult(result: LocalGetFileContentToolResult, _query: FetchContentQuery, _totalLines: number): LocalGetFileContentToolResult;

package/dist/tools/local_fetch_content/scheme.d.ts

@@ -29,3 +29,93 @@ export declare const LocalFetchContentBulkQuerySchema: z.ZodObject<{
     responseCharLength: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
     queries: z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 }, z.core.$strip>;
+export declare const LocalGetFileContentOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            empty: "empty";
+            error: "error";
+        }>>;
+        data: z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            content: z.ZodOptional<z.ZodString>;
+            contentView: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                standard: "standard";
+                symbols: "symbols";
+            }>>;
+            totalLines: z.ZodOptional<z.ZodNumber>;
+            sourceChars: z.ZodOptional<z.ZodNumber>;
+            sourceBytes: z.ZodOptional<z.ZodNumber>;
+            startLine: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+            isPartial: z.ZodOptional<z.ZodBoolean>;
+            matchRanges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strip>>>;
+            pagination: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                charOffset: z.ZodNumber;
+                charLength: z.ZodNumber;
+                totalChars: z.ZodNumber;
+                hasMore: z.ZodBoolean;
+                nextCharOffset: z.ZodOptional<z.ZodNumber>;
+                currentPage: z.ZodOptional<z.ZodNumber>;
+                totalPages: z.ZodOptional<z.ZodNumber>;
+                chunkMode: z.ZodOptional<z.ZodEnum<{
+                    semantic: "semantic";
+                    "char-limit": "char-limit";
+                }>>;
+                nextBlockChar: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                currentPage: z.ZodNumber;
+                totalPages: z.ZodNumber;
+                hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>]>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            modified: z.ZodOptional<z.ZodString>;
+            lastModified: z.ZodOptional<z.ZodString>;
+            lastModifiedBy: z.ZodOptional<z.ZodString>;
+            warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            matchNotFound: z.ZodOptional<z.ZodBoolean>;
+            searchedFor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    base: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    responsePagination: z.ZodOptional<z.ZodObject<{
+        currentPage: z.ZodNumber;
+        totalPages: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        charOffset: z.ZodNumber;
+        charLength: z.ZodNumber;
+        totalChars: z.ZodNumber;
+        nextCharOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalGetFileContentOutput = z.infer<typeof LocalGetFileContentOutputSchema>;

package/dist/tools/local_find_files/scheme.d.ts

@@ -7,3 +7,84 @@ export declare const LocalFindFilesBulkQuerySchema: z.ZodObject<{
     responseCharLength: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
     queries: z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 }, z.core.$strip>;
+export declare const LocalFindFilesOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            empty: "empty";
+            error: "error";
+        }>>;
+        data: z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                path: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodEnum<{
+                    file: "file";
+                    link: "link";
+                    directory: "directory";
+                    dir: "dir";
+                    symlink: "symlink";
+                }>>;
+                size: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                sizeFormatted: z.ZodOptional<z.ZodString>;
+                modified: z.ZodOptional<z.ZodString>;
+                accessed: z.ZodOptional<z.ZodString>;
+                created: z.ZodOptional<z.ZodString>;
+                permissions: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            summary: z.ZodOptional<z.ZodString>;
+            pagination: z.ZodOptional<z.ZodObject<{
+                currentPage: z.ZodNumber;
+                totalPages: z.ZodNumber;
+                hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
+                filesPerPage: z.ZodOptional<z.ZodNumber>;
+                entriesPerPage: z.ZodOptional<z.ZodNumber>;
+                matchesPerPage: z.ZodOptional<z.ZodNumber>;
+                totalFiles: z.ZodOptional<z.ZodNumber>;
+                totalEntries: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                totalFilesFound: z.ZodOptional<z.ZodNumber>;
+                nextMatchPage: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    base: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    responsePagination: z.ZodOptional<z.ZodObject<{
+        currentPage: z.ZodNumber;
+        totalPages: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        charOffset: z.ZodNumber;
+        charLength: z.ZodNumber;
+        totalChars: z.ZodNumber;
+        nextCharOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalFindFilesOutput = z.infer<typeof LocalFindFilesOutputSchema>;

package/dist/tools/local_ripgrep/rankingProfile/rankingProfiles.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ranking profile data/config — language profile tables, path-role
+ * classification, and the tunable weight policy. See
+ * `.octocode/RANKING-ARCHITECTURE.md` and the module doc in
+ * `../rankingProfile.ts` (the public barrel) for the full contract.
+ *
+ * This module owns *what* a profile is and *where* a path lives (its role);
+ * `rankingScoring.ts` owns *how much* each signal is worth in a score.
+ */
+export type RankingProfileId = 'typescript' | 'javascript' | 'rust' | 'python' | 'go' | 'java' | 'scala' | 'markdown' | 'json' | 'yaml' | 'generic';
+/** TS-level result orderings. `relevance` is the language-aware scorer. */
+export type RankSort = 'relevance' | 'matchCount' | 'path' | 'created' | 'modified' | 'accessed';
+export declare const RANKING_PROFILE_IDS: readonly ["typescript", "javascript", "rust", "python", "go", "java", "scala", "markdown", "json", "yaml", "generic"];
+export type PathRole = 'source' | 'test' | 'docs' | 'config' | 'generated' | 'fixture' | 'unknown';
+/**
+ * All ranking weights in one place. Tuning happens here and in the golden
+ * fixtures, never scattered across the scorer. Values are deliberately
+ * integer-ish and additive so a score can be read back from its reasons.
+ */
+export declare const RANK_WEIGHTS: {
+    readonly exactWholeWord: 6;
+    readonly exactCaseInsensitive: 3;
+    readonly substring: 1;
+    readonly declarationLine: 8;
+    readonly exportLine: 4;
+    readonly importLine: 3;
+    readonly configKeyLine: 4;
+    readonly headingLine: 4;
+    readonly commentOrStringPenalty: -2;
+    readonly pathUnderQuery: 4;
+    readonly pathSegmentToken: 3;
+    readonly extMatchesLangType: 2;
+    readonly sourceDir: 1.5;
+    readonly lowSignalPathPenalty: -5;
+    readonly rareQueryTokenScale: 2;
+    readonly rareQueryTokenCap: 3;
+    readonly matchCountScale: 1.5;
+    readonly matchCountCap: 6;
+};
+/**
+ * Bound on how many files get full scoring before pagination. The engine text
+ * path returns the entire result set unbounded (no global file/match cap), so
+ * for broad terms in a large monorepo we must not score O(total files). When
+ * the cap bites we deterministically prefilter (matchCount desc, path asc)
+ * before scoring, and the builder surfaces a `truncated`-style note.
+ */
+export declare const RANK_CANDIDATE_CAP = 2000;
+export interface RankingProfile {
+    id: RankingProfileId;
+    extensions: readonly string[];
+    /** Lines that declare/define a symbol named like the query — highest signal. */
+    declaration: readonly RegExp[];
+    /** Exported/public surface. */
+    export: readonly RegExp[];
+    /** Import/use lines. */
+    import: readonly RegExp[];
+}
+export declare const COMMENT_LINE: RegExp;
+export declare const HEADING_LINE: RegExp;
+export declare const LOW_SIGNAL_PATH: RegExp;
+export declare const EXT_RE: RegExp;
+export declare function fileExtension(path: string): string;
+/** Deterministic profile selection from query langType then file extension. */
+export declare function selectProfile(path: string, langType?: string, override?: RankingProfileId | 'auto'): RankingProfile;
+export declare function classifyPathRole(path: string): PathRole;
+/** True when the query path explicitly targets a low-signal area, so the
+ * scorer should not penalize generated/test/docs/fixture roles. Uses anchored
+ * path-segment matching (not substring) so `latest/`, `contest/`, `manifest/`
+ * do NOT count as low-signal. */
+export declare function isLowSignalQueryPath(path: string | undefined): boolean;

package/dist/tools/local_ripgrep/rankingProfile/rankingResults.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Ranking results — the top-level `rankFiles` entry point plus the small
+ * lexical helpers (comment/string detection, token indexing) that classify a
+ * matched line before the scorer in `rankingScoring.ts` weighs it.
+ *
+ * `rankFiles` composes the scoring engine (`scoreFileWithRarity`,
+ * `buildCandidateTermRarity`) over the whole candidate set: it applies the
+ * candidate cap, builds candidate-local term rarity once, scores every file,
+ * and produces a total, deterministic order. See the module doc in
+ * `../rankingProfile.ts` for the full contract.
+ */
+import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
+import type { RankingProfileId, RankSort } from './rankingProfiles.js';
+import type { FileScore, RankContext } from './rankingScoring.js';
+export interface RankResult {
+    files: LocalSearchCodeFile[];
+    /** Per-path debug info, only populated when debug is requested. */
+    debug?: Map<string, FileScore>;
+    /** Number of files dropped by the candidate cap before scoring (0 if none). */
+    cappedCandidates: number;
+}
+/**
+ * Rank files by the requested sort mode. `relevance` is the language-aware
+ * scorer (default); `matchCount` and `path` are deterministic escape hatches;
+ * filesystem sorts (created/modified/accessed) preserve the engine's order.
+ */
+export declare function rankFiles(files: LocalSearchCodeFile[], sort: RankSort, ctx: RankContext, opts?: {
+    debug?: boolean;
+    candidateCap?: number;
+}): RankResult;
+export declare function matchesAny(patterns: readonly RegExp[], line: string): boolean;
+export declare function escapeRegex(s: string): string;
+/** A search whose keyword is a single bare identifier — the only case where
+ * whole-word/substring line-exactness is meaningful (regex/multi-term patterns
+ * make the extracted token an arbitrary fragment). */
+export declare function isPlainIdentifierKeyword(keyword?: string): boolean;
+/** Pick the line within a (possibly multi-line context) snippet that actually
+ * contains the query token; fall back to the first non-empty line. */
+export declare function matchedLineOf(snippet: string, token: string | undefined, caseSensitive?: boolean): string;
+type LexicalCategory = 'comment' | 'string' | 'code';
+/** Best-effort lexical category of the token's occurrence on a single line.
+ * Deterministic and conservative — used only in the regex fallback path when
+ * the engine's grammar-accurate AST kind is unavailable. */
+export declare function lexicalCategoryOf(line: string, token: string | undefined, profileId: RankingProfileId, caseSensitive?: boolean): LexicalCategory;
+/** Whether byte index `idx` falls inside a quoted region of the line. */
+export declare function isIndexInsideString(line: string, idx: number): boolean;
+export {};

package/dist/tools/local_ripgrep/rankingProfile/rankingScoring.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ranking scoring engine — turns a candidate file's matches, path, and the
+ * query context into an additive, explainable `FileScore`. Every function
+ * here appends to a shared `reasons: string[]` accumulator; call order is
+ * significant because scores are additive and reasons are appended in the
+ * order they are computed. Do not reorder the calls inside
+ * `scoreFileWithRarity` or `bestLineScore`.
+ *
+ * See the module doc in `../rankingProfile.ts` for the full contract.
+ */
+import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
+import { type PathRole, type RankingProfileId } from './rankingProfiles.js';
+export interface RankContext {
+    /** Validated, sanitized search base path (query.path). */
+    queryPath?: string;
+    /** The literal keyword/pattern, used for whole-word / token / path checks. */
+    keyword?: string;
+    langType?: string;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+    /** Profile override from query.rankingProfile. */
+    profileOverride?: RankingProfileId | 'auto';
+    /** True when the user explicitly searched into a low-signal/test/docs area. */
+    explicitLowSignal?: boolean;
+}
+export interface FileScore {
+    score: number;
+    profile: RankingProfileId;
+    pathRole: PathRole;
+    reasons: string[];
+}
+type CandidateTermRarity = {
+    candidateCount: number;
+    fileTokens: ReadonlyMap<string, readonly string[]>;
+    documentFrequency: ReadonlyMap<string, number>;
+};
+export declare function buildCandidateTermRarity(files: LocalSearchCodeFile[], ctx: RankContext): CandidateTermRarity | undefined;
+export declare function scoreFileWithRarity(file: LocalSearchCodeFile, ctx: RankContext, rarity?: CandidateTermRarity): FileScore;
+/** Score one file. Pure and deterministic. */
+export declare function scoreFile(file: LocalSearchCodeFile, ctx: RankContext): FileScore;
+export {};