@octocodeai/octocode-tools-core 16.5.1 → 16.6.0

package/dist/oql/adapters/compile.d.ts

@@ -0,0 +1,25 @@
+import type { DiagnosticCode, Predicate } from '../types.js';
+export interface CompiledMatch {
+    keywords?: string;
+    fixedString?: boolean;
+    perlRegex?: boolean;
+    caseInsensitive?: boolean;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+    multiline?: boolean;
+    multilineDotall?: boolean;
+    mode?: 'structural';
+    pattern?: string;
+    rule?: unknown;
+    langType?: string;
+}
+export interface CompileResult {
+    match?: CompiledMatch;
+    negate?: boolean;
+    unsupported?: {
+        code: DiagnosticCode;
+        message: string;
+        predicateId?: string;
+    };
+}
+export declare function compileWhere(where: Predicate): CompileResult;

package/dist/oql/adapters/github.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from './local.js';
+import type { OqlQuery } from '../types.js';
+export declare function executeGithub(query: OqlQuery): Promise<AdapterResult>;

package/dist/oql/adapters/local.d.ts

@@ -0,0 +1,7 @@
+import { type MappedResult } from './resultMap.js';
+import type { OqlDiagnostic, OqlProvenance, OqlQuery } from '../types.js';
+export interface AdapterResult extends MappedResult {
+    diagnostics: OqlDiagnostic[];
+    provenance: OqlProvenance[];
+}
+export declare function executeLocal(query: OqlQuery): Promise<AdapterResult>;

package/dist/oql/adapters/materialize.d.ts

@@ -0,0 +1,11 @@
+import { type AdapterResult } from './local.js';
+import type { OqlQuery } from '../types.js';
+export declare function executeMaterialize(query: OqlQuery): Promise<AdapterResult>;
+/**
+ * `target:"materialize"` — addressable materialization. Clone/cache a bounded
+ * corpus once and return a stable local checkpoint row (localPath, repoRoot,
+ * source, ref, cache, complete) that downstream queries can root at via the
+ * `next.search` / `next.structure` / `next.fetch` continuations (attached in
+ * run.ts). This makes materialization a first-class step, not a search side-effect.
+ */
+export declare function executeMaterializeCheckpoint(query: OqlQuery): Promise<AdapterResult>;

package/dist/oql/adapters/pagination.d.ts

@@ -0,0 +1,21 @@
+import type { Pagination } from '../types.js';
+export interface ToolPaginationPayload {
+    currentPage?: number;
+    totalPages?: number;
+    nextPage?: number;
+    hasMore?: boolean;
+    itemsPerPage?: number;
+    entriesPerPage?: number;
+    filesPerPage?: number;
+    perPage?: number;
+    totalItems?: number;
+    totalEntries?: number;
+    totalFiles?: number;
+    totalMatches?: number;
+    reportedTotalMatches?: number;
+    reachableTotalMatches?: number;
+    totalMatchesKind?: string;
+    totalMatchesCapped?: boolean;
+    uniqueFileCount?: number;
+}
+export declare function toOqlPagination(pagination: ToolPaginationPayload | undefined, fallbackHasMore?: boolean): Pagination | undefined;

package/dist/oql/adapters/researchTargets.d.ts

@@ -0,0 +1,50 @@
+import type { AdapterResult } from './local.js';
+import type { OqlQuery } from '../types.js';
+export declare function executeRepositories(query: OqlQuery): Promise<AdapterResult>;
+export declare function executePackages(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeHistory(query: OqlQuery): Promise<AdapterResult>;
+/**
+ * Keep only commit records whose message contains `needle` (case-insensitive
+ * substring), spotlight where it matched, and surface honest diagnostics — a
+ * `partialResult` when some were dropped, `zeroMatches` when none matched.
+ * Mirrors {@link filterPullRequestsByMatch}; commit text is the commit message.
+ */
+export declare function filterCommitsByMatch(result: AdapterResult, needle: string): AdapterResult;
+export interface PullRequestMatch {
+    needle: string;
+    scope: 'body' | 'title' | 'comments' | 'reviews' | 'all';
+}
+/**
+ * Keep only PR records whose scope text contains `matchString` (case-insensitive
+ * substring), spotlight where each matched, and surface honest diagnostics: a
+ * `partialResult` when some were dropped, `zeroMatches` when none matched.
+ */
+export declare function filterPullRequestsByMatch(result: AdapterResult, match: PullRequestMatch): AdapterResult;
+/**
+ * `target:"diff"` has two typed lanes, discriminated by params shape:
+ *   - PR patch:    { prNumber, files? }            -> ghHistoryResearch patches
+ *   - direct file: { baseRef, headRef, path }      -> two ghGetFileContent reads
+ *                                                     + a pure local line diff
+ * A request that fits neither returns a repair diagnostic rather than silently
+ * falling through to a PR-patch call.
+ */
+export declare function executeDiff(query: OqlQuery): Promise<AdapterResult>;
+export interface LineDiff {
+    additions: number;
+    deletions: number;
+    unchanged: number;
+    /** Unified-style patch text (`+`/`-`/` ` line prefixes). */
+    patch: string;
+}
+/**
+ * Minimal LCS-based line diff between two file bodies. Pure and dependency-free
+ * so it is unit-testable without any backend. Not a byte-perfect git patch —
+ * a line-granular additions/deletions view for direct two-ref comparison.
+ */
+export declare function computeLineDiff(baseText: string, headText: string): LineDiff;
+export declare function executeArtifacts(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeSemantics(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeResearch(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeGraph(query: OqlQuery): Promise<AdapterResult>;
+/** Dispatch map: target -> adapter. */
+export declare const RESEARCH_TARGET_ADAPTERS: Record<string, (q: OqlQuery) => Promise<AdapterResult>>;

package/dist/oql/adapters/resultMap.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Map typed tool results into OQL result rows + pagination. Pure functions —
+ * no I/O — so they are unit-testable without backends.
+ */
+import type { LocalFindFilesToolResult, LocalGetFileContentToolResult, LocalSearchCodeToolResult, LocalViewStructureToolResult } from '@octocodeai/octocode-core/extra-types';
+import type { OqlContentResultRow, OqlResultRow, Pagination, QuerySource } from '../types.js';
+export interface MappedResult {
+    results: OqlResultRow[];
+    pagination?: Pagination;
+}
+export declare function mapCodeResult(result: LocalSearchCodeToolResult, source: QuerySource): MappedResult;
+export declare function mapFilesResult(result: LocalFindFilesToolResult, source: QuerySource): MappedResult;
+export declare function mapStructureResult(result: LocalViewStructureToolResult, source: QuerySource): MappedResult;
+export declare function mapContentResult(result: LocalGetFileContentToolResult, source: QuerySource, path: string, 
+/**
+ * The view the OQL query *requested*. The backing tool does not reliably echo
+ * the minify mode back (e.g. a `symbols` read reports `standard`), so the row
+ * must report the requested view to satisfy "report the view used".
+ */
+requestedView?: OqlContentResultRow['contentView']): MappedResult;

package/dist/oql/adapters/ruleYaml.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serialize an OQL JSON `StructuralRule` into the engine's YAML rule string.
+ *
+ * The structural engine's `rule` field is a YAML string with a top-level
+ * `rule:` key (matching the `search --rule` surface). OQL accepts that YAML
+ * string directly, or this JSON object form for typed callers. Covers the
+ * currently supported rule fields: pattern, kind, inside, has, not, all, any,
+ * stopBy.
+ */
+import type { StructuralRule } from '../types.js';
+export declare function structuralRuleToYaml(rule: StructuralRule): string;

package/dist/oql/adapters/runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single entry for OQL adapters to invoke a backing tool.
+ *
+ * Routes through `executeDirectTool` — the SAME path the CLI's `tools <name>`
+ * uses — so OQL gets identical credential resolution (withSecurityValidation),
+ * provider initialization, input validation, and secret sanitization. Calling
+ * the bulk runners directly bypassed auth (the CLI runs `runOqlSearch` without
+ * an MCP `authInfo`), which silently failed GitHub/npm calls.
+ *
+ * GitHub/package tools require `mainResearchGoal`; we fill OQL defaults.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Run one backing tool with a single query, via the shared direct-tool path. */
+export declare function runDirect(name: string, query: Record<string, unknown>): Promise<CallToolResult>;

package/dist/oql/adapters/v2.d.ts

@@ -0,0 +1,32 @@
+import type { AdapterResult } from './local.js';
+import type { OqlQuery } from '../types.js';
+export declare function executeRepositories(query: OqlQuery): Promise<AdapterResult>;
+export declare function executePackages(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeHistory(query: OqlQuery): Promise<AdapterResult>;
+/**
+ * `target:"diff"` has two typed lanes, discriminated by params shape:
+ *   - PR patch:    { prNumber, files? }            -> ghHistoryResearch patches
+ *   - direct file: { baseRef, headRef, path }      -> two ghGetFileContent reads
+ *                                                     + a pure local line diff
+ * A request that fits neither returns a repair diagnostic rather than silently
+ * falling through to a PR-patch call (see OCTOCODE_SEARCH_PARITY_CHECKLIST.md gap log #8).
+ */
+export declare function executeDiff(query: OqlQuery): Promise<AdapterResult>;
+export interface LineDiff {
+    additions: number;
+    deletions: number;
+    unchanged: number;
+    /** Unified-style patch text (`+`/`-`/` ` line prefixes). */
+    patch: string;
+}
+/**
+ * Minimal LCS-based line diff between two file bodies. Pure and dependency-free
+ * so it is unit-testable without any backend. Not a byte-perfect git patch —
+ * a line-granular additions/deletions view for direct two-ref comparison.
+ */
+export declare function computeLineDiff(baseText: string, headText: string): LineDiff;
+export declare function executeArtifacts(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeSemantics(query: OqlQuery): Promise<AdapterResult>;
+export declare function executeResearch(query: OqlQuery): Promise<AdapterResult>;
+/** Dispatch map: V2 target -> adapter. */
+export declare const V2_ADAPTERS: Record<string, (q: OqlQuery) => Promise<AdapterResult>>;

package/dist/oql/capabilities.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OQL capability registry — makes backend limits explicit and testable.
+ *
+ * Given the source kind, target, materialization stance, and a single leaf
+ * predicate, decide how that predicate can be evaluated:
+ *   PUSHDOWN   backend evaluates it directly (exact or approximate)
+ *   RESIDUAL   fetch bounded candidates and filter locally
+ *   ROUTE      move to another lane (materialize -> local)
+ *   UNSUPPORTED cannot be evaluated; emit a diagnostic
+ *
+ * This is intentionally conservative: anything that cannot be proven exactly is
+ * flagged so the planner never reports `proof` it cannot back.
+ */
+import type { DiagnosticCode, LeafPredicate, MaterializePolicy, OqlActiveTarget, PlanRoute, QuerySource } from './types.js';
+export interface CapabilityContext {
+    sourceKind: QuerySource['kind'];
+    target: OqlActiveTarget;
+    materialize: MaterializePolicy | undefined;
+}
+export interface CapabilityDecision {
+    route: PlanRoute;
+    backend: string;
+    /** Whether the backend evaluates the predicate exactly (proof-grade). */
+    exact: boolean;
+    reason: string;
+    diagnostic?: {
+        code: DiagnosticCode;
+        message: string;
+    };
+}
+export declare function routeLeafPredicate(ctx: CapabilityContext, predicate: LeafPredicate, inNegation?: boolean): CapabilityDecision;

package/dist/oql/defaults.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OQL defaults (see OCTOCODE_QUERY_LANGUAGE.md §defaults). `--explain` must
+ * surface every applied default, so they live in one place.
+ */
+import type { OqlQuery } from './types.js';
+export declare const DEFAULTS: {
+    schema: "oql";
+    view: "paginated";
+    page: number;
+    itemsPerPage: number;
+    githubMaterializeMode: "never";
+    textCase: "smart";
+    regexDialectLocal: "rust";
+    regexCase: "smart";
+    contentView: "compact";
+    contentCharLength: number;
+    matchContentLength: number;
+    maxPlanNodes: number;
+    maxBooleanExpansion: number;
+    normalCodeContext: number;
+    detailedCodeContext: number;
+    localSearchSort: "relevance";
+    localRankingProfile: "auto";
+};
+/** The subset of defaults actually applied to (or relevant for) this query. */
+export declare function appliedDefaults(query: OqlQuery): Record<string, unknown>;

package/dist/oql/diagnostics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OQL diagnostic helpers. Diagnostics are first-class typed output, not prose
+ * hints. `blocksAnswer:true` marks diagnostics that prevent `proof`.
+ */
+import type { DiagnosticCode, OqlContinuation, OqlDiagnostic, OqlSearchInput } from './types.js';
+export interface DiagnosticOptions {
+    queryPath?: string;
+    predicateId?: string;
+    backend?: string;
+    blocksAnswer?: boolean;
+    severity?: OqlDiagnostic['severity'];
+    repair?: {
+        message: string;
+        suggestedQuery?: OqlSearchInput;
+    };
+    continuation?: OqlContinuation;
+}
+export declare function diagnostic(code: DiagnosticCode, message: string, options?: DiagnosticOptions): OqlDiagnostic;
+export declare function blocksAnswer(diagnostics: OqlDiagnostic[]): boolean;
+export declare function hasErrors(diagnostics: OqlDiagnostic[]): boolean;
+/** Error raised when validation/normalization cannot produce a canonical query. */
+export declare class OqlValidationError extends Error {
+    readonly diagnostics: OqlDiagnostic[];
+    constructor(diagnostics: OqlDiagnostic[]);
+}

package/dist/oql/diffLanes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for the `target:"diff"` lane discriminant.
+ *
+ * `target:"diff"` has two typed execution lanes plus an invalid shape:
+ *   - prPatch:    { prNumber, files? }        -> ghHistoryResearch (PR patches)
+ *   - directFile: { baseRef, headRef, path }  -> 2× ghGetFileContent + line diff
+ *   - neither:    repair diagnostic, no call
+ *
+ * Both the planner (to announce the right backend in `--explain --dry-run`) and
+ * the diff adapter (to dispatch execution) classify a query off this one
+ * helper, so the plan can never contradict execution. Pure: no imports beyond
+ * its own return types.
+ */
+export type DiffLane = {
+    kind: 'prPatch';
+    prNumber: number;
+    files?: string[];
+} | {
+    kind: 'directFile';
+    baseRef: string;
+    headRef: string;
+    path: string;
+} | {
+    kind: 'neither';
+};
+/** Unified lane discriminant for target:"diff". Single source of truth. */
+export declare function classifyDiffLane(params: Record<string, unknown> | undefined): DiffLane;
+/** Backend name the planner should announce for a lane (`''` = no call). */
+export declare function diffLaneBackend(lane: DiffLane): string;

package/dist/oql/envelope.d.ts

@@ -0,0 +1,19 @@
+import type { OqlBackendCall, OqlDiagnostic, OqlExplainPlan, OqlProofGradedResultRow, OqlProvenance, OqlResultEnvelope, Pagination } from './types.js';
+export interface BuildEnvelopeArgs {
+    queryId?: string;
+    queryIndex?: number;
+    results: OqlProofGradedResultRow[];
+    pagination?: Pagination;
+    next?: OqlResultEnvelope['next'];
+    diagnostics: OqlDiagnostic[];
+    provenance: OqlProvenance[];
+    /** Whether the plan was executable (no UNSUPPORTED nodes / blocking errors). */
+    executable: boolean;
+    /** Whether any backend call was approximate (exact:false). */
+    approximate?: boolean;
+    plan?: OqlExplainPlan;
+}
+export declare function buildEnvelope(args: BuildEnvelopeArgs): OqlResultEnvelope;
+export declare function backendsApproximate(calls: OqlBackendCall[]): boolean;
+/** Envelope for a query that failed validation/planning (no execution). */
+export declare function unsupportedEnvelope(diagnostics: OqlDiagnostic[], plan?: OqlExplainPlan, queryId?: string, queryIndex?: number, next?: OqlResultEnvelope['next']): OqlResultEnvelope;

package/dist/oql/features.d.ts

@@ -0,0 +1,7 @@
+import type { OqlDiagnostic, OqlQuery } from './types.js';
+/**
+ * Diagnose requested-but-unbackable output features. Pure; emits zero or more
+ * non-blocking diagnostics. Called by the planner so the limitation rides in the
+ * plan and the envelope alike.
+ */
+export declare function checkOutputFeatures(query: OqlQuery): OqlDiagnostic[];

package/dist/oql/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Octocode Query Language (OQL) public surface.
+ *
+ * `octocode search` (CLI) and the OQL MCP tool both consume this module:
+ *   - `runOqlSearch` executes a query/batch and returns a typed envelope.
+ *   - `normalizeInput` / `planQuery` expose the normalize + explain stages.
+ *   - `oqlSchemaText()` / `OQL_SCHEMA_JSON` back `octocode search --scheme`.
+ *
+ * Schemas/types co-locate here for now (tools-core). They may migrate to
+ * `@octocodeai/octocode-core/oql` once a second consumer needs OQL validation
+ * without the rest of tools-core.
+ */
+export * from './types.js';
+export { OqlQuerySchema, OqlBatchSchema, OqlCanonicalInputSchema, OqlInputQuerySchema, OqlInputBatchSchema, OqlSearchInputSchema, PredicateSchema, QuerySourceSchema, StructuralRuleSchema, } from './schema.js';
+export { normalizeInput, normalizeQuery } from './normalize.js';
+export { planQuery, type PlanQueryResult } from './planner.js';
+export { DEFAULTS, appliedDefaults } from './defaults.js';
+export { diagnostic, blocksAnswer, hasErrors, OqlValidationError, } from './diagnostics.js';
+export { buildEnvelope, unsupportedEnvelope, backendsApproximate, } from './envelope.js';
+export { runOqlSearch, type RunOptions } from './run.js';
+export { buildShorthandInput, type SearchShorthand, type ShorthandCorpus, type ShorthandResult, } from './shorthand.js';
+export { listTransformerEntries, findTransformerById, findTransformerEntry, backendCallsForTransformer, } from './transformers/registry.js';
+export type { TransformerRegistryEntry, TransformerStatus, } from './transformers/contract.js';
+export { oqlSchemaText, OQL_SCHEMA_DOC } from './schemeText.js';
+export { analyzeResearchFlow, type AnalyzeResearchOptions, type ResearchAnalysisResult, type ResearchDependencyIssue, type ResearchFileIssue, type ResearchFlowStep, type ResearchIntent, type ResearchManifestSummary, type ResearchMode, type ResearchSymbolRow, type ResearchSymbolVerdict, } from './research/analyze.js';
+export { buildResearchPackets, type EvidenceClaim, type EvidenceConfidence, type EvidenceEdge, type EvidenceFact, type EvidenceFlag, type EvidenceLocation, type EvidenceRelation, type EvidenceSource, type EvidenceSubject, type MissingProof, type MissingProofKind, type PacketProofStatus, type PacketVerdict, type ResearchEvidencePacket, type ResearchGraphSummary, type ResearchPacketBundle, } from './research/packets.js';