@octocodeai/octocode-tools-core 16.3.0 → 16.6.0

package/dist/oql/schemeText.d.ts

@@ -0,0 +1,138 @@
+export declare const OQL_SCHEMA_DOC: {
+    readonly schema: "oql";
+    readonly description: "octocode search — typed read-only queries over code, files, symbols, repos, packages, history, artifacts, diffs, and graph evidence. Think source + answer type + filters + read/output options; use --explain for routing; follow next.* for pages, exact reads, materialization, or proof.";
+    readonly activeTargets: readonly import("./types.js").OqlActiveTarget[];
+    readonly reservedTargets: readonly import("./types.js").OqlReservedTarget[];
+    readonly sourceGuide: {
+        readonly local: "from:{kind:\"local\",path:\"./src\"}; shorthand: search \"term\" ./src, search ./src --tree, search file.ts --op documentSymbols. Best for local code/content/files/tree/LSP/artifacts/diff.";
+        readonly github: "from:{kind:\"github\",repo:\"owner/repo\",ref?}; shorthand: search \"term\" owner/repo, search owner/repo --tree, search owner/repo#123 --target pullRequests. GitHub code is indexed/default-branch scoped; materialize for AST/LSP/local proof.";
+        readonly npm: "from:{kind:\"npm\"} with target:\"packages\"; shorthand: search zod --target packages. Use to resolve package metadata and source repo, then continue with GitHub or local/materialized proof.";
+        readonly materialized: "from:{kind:\"materialized\",localPath:\"/abs/path\"} after target:\"materialize\", clone, or cache fetch. Use when a remote repo/subtree must behave like local code.";
+    };
+    readonly plainLanguage: {
+        readonly source: "`from` = where to look: local path, GitHub repo, npm, or a materialized checkout.";
+        readonly answerType: "`target` = what kind of answer you want: code matches, file content, tree, files, symbols, repos, packages, PRs, commits, artifacts, diffs, research packets, graph proof, or materialization.";
+        readonly filters: "`where` = match/filter conditions for code and file discovery only: text, regex, AST shape, file fields, and boolean combinations.";
+        readonly readOptions: "`fetch` = what to read once you know the file/tree: exact content, compact content, symbol outline, ranges, match slices, or tree depth.";
+        readonly targetOptions: "`params` = options that belong to one answer type, such as LSP operation, PR number, package name, artifact mode, research intent, or graph proof.";
+        readonly output: "`view`, `select`, and `controls` = response shape, projected fields, search tuning, and cost limits.";
+        readonly paging: "`page` + `itemsPerPage` page the target's primary result domain. For code search that may be matched files; per-file match paging uses `controls.search.matchPage` / `--match-page`.";
+    };
+    readonly targetDecisionTree: {
+        readonly 'find a string/pattern in code': "target:code (shorthand default for text/regex/--pattern/--rule; needs a where filter)";
+        readonly 'read or slice a known file': "target:content (file positional + --content-view, --start-line/--end-line, or --match-string)";
+        readonly 'see the file/dir layout': "target:structure (--tree)";
+        readonly 'find files by name/glob/ext/size/mtime': "target:files (--search path, --name/--ext/--size-greater/--modified-within)";
+        readonly 'symbol defs/refs/callers/hover': "target:semantics (--op …; local or materialized only)";
+        readonly 'search GitHub repos': "target:repositories (--stars/--lang/--topic)";
+        readonly 'resolve an npm package': "target:packages";
+        readonly 'PR list or deep-read': "target:pullRequests (owner/repo#N)";
+        readonly 'commit history': "target:commits (--since/--until)";
+        readonly 'a diff': "target:diff ({prNumber} for a PR patch, {baseRef,headRef,path} for two refs)";
+        readonly 'inspect a binary/archive': "target:artifacts (--inspect/--list/--strings/--extract)";
+        readonly 'dead-code / reachability sweep': "target:research, then upgrade with target:graph proof:\"lsp\"";
+        readonly 'make a remote repo behave like local (AST/LSP/negation)': "target:materialize (or clone / cache fetch)";
+    };
+    readonly agentBestPractices: readonly ["Start with cheap orientation: --tree, --search path, --view discovery, or --content-view symbols.", "Then narrow and read exact evidence: --match-string, --start-line/--end-line, --char-offset/--char-length, or --content-view exact.", "Use snippets as discovery only; make decisions from exact content, PR/commit metadata, or LSP/graph proof.", "For semantics, run documentSymbols first to get line anchors, then references/callers/hover with symbolName + lineHint.", "For GitHub zero rows / providerUnindexed, do NOT claim absence — follow evidenceSemantics.providerUnindexed (verify path with structure, then materialize a bounded path).", "Read evidence.answerReady, evidence.complete, diagnostics, pagination, and next.* before concluding."];
+    readonly quickStart: {
+        readonly 'text search (local)': "search \"functionName\" ./src";
+        readonly 'text search (GitHub)': "search \"functionName\" facebook/react";
+        readonly 'package lookup (npm)': "search zod --target packages";
+        readonly 'PR deep read (GitHub)': "search facebook/react#1 --target pullRequests --comments --patches";
+        readonly 'commit history (GitHub)': "search facebook/react/packages/react/src --target commits --since 2024-01-01T00:00:00Z";
+        readonly 'browse a tree (local dir or owner/repo)': "search ./src --tree   |   search facebook/react --tree";
+        readonly 'read a file (local or owner/repo/path)': "search ./src/index.ts   |   search facebook/react/packages/react/src/index.js";
+        readonly 'semantics (local/materialized)': "search ./src/index.ts --op documentSymbols   |   search ./src/index.ts --op references --symbol runCLI --line 42";
+        readonly 'artifact inspect/list': "search app.tgz --target artifacts --list   |   search dist/server.node --target artifacts --inspect";
+        readonly 'PR diff (GitHub)': "search facebook/react#123 --target diff   |   search facebook/react --target diff --pr 123";
+        readonly 'two-ref / two-file diff': "search src/a.ts src/b.ts --target diff   |   search owner/repo --target diff --base-ref <sha> --head-ref <sha> --path <file>";
+        readonly 'structural AST (local \u2014 needs full node shape)': "search --pattern \"function $NAME($$$ARGS) { $$$BODY }\" ./src --lang ts";
+        readonly 'structural AST (GitHub \u2014 clones bounded subtree)': "search --pattern \"function $NAME($$$ARGS) { $$$BODY }\" facebook/react/packages --lang js --materialize auto";
+        readonly 'GitHub index miss recovery': "search useState packages/react/src --repo facebook/react --materialize required   |   clone facebook/react/packages/react/src   |   cache fetch facebook/react packages/react/src --depth tree";
+        readonly 'dead-code triage (research)': "search --query '{\"schema\":\"oql\",\"target\":\"research\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"params\":{\"intent\":\"reachability\",\"facets\":[\"symbols\",\"files\"]},\"itemsPerPage\":1,\"page\":1}'";
+        readonly 'LSP-proven dead symbols (graph)': "search --query '{\"schema\":\"oql\",\"target\":\"graph\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"params\":{\"intent\":\"reachability\",\"facets\":[\"symbols\"],\"proof\":\"lsp\",\"proofLimit\":5,\"includePackets\":true},\"page\":1,\"itemsPerPage\":10}'";
+        readonly 'OQL full-schema reference': "search --scheme";
+        readonly 'routing explanation before running': "search --explain --query '{\"target\":\"code\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"where\":{\"kind\":\"text\",\"value\":\"term\"}}'";
+    };
+    readonly evidenceSemantics: {
+        readonly 'answerReady:true': "The envelope answers the query as asked. No required follow-up.";
+        readonly 'answerReady:false': "Normal, NOT a failure — the results above are valid; only answerReady:true means no follow-up is needed. Follow next.* for more pages, LSP proof, or content.";
+        readonly 'complete:false': "Pages/proof/slices may remain. Read diagnostics: non-blocking warnings can still leave usable rows, but deletion/absence claims need the requested scope plus the listed continuations.";
+        readonly 'kind:proof': "Backend evaluated the request exactly.";
+        readonly 'kind:partial': "Truncation, pagination, or residual checks remain.";
+        readonly 'kind:candidate': "Useful evidence, not proof. research/graph are always candidate — upgrade via next.semantic/search/fetch.";
+        readonly 'kind:unsupported': "OQL could not safely execute the requested semantics.";
+        readonly 'proofStatus:confirmed-by-lsp': "LSP refs=0 inside the bounded workspace. Inspect for deletion only after checking entrypoints, framework conventions, dynamic imports, package exports, and scripts.";
+        readonly 'proofStatus:conflicting-evidence': "LSP refs>0 — symbol IS retained; check retainedBy before acting.";
+        readonly 'proofStatus:needs-framework-graph': "Maybe an entrypoint (framework/export/dynamic import) — LSP alone can't prove reachability.";
+        readonly 'proofStatus:candidate': "Pre-proof state (no LSP run yet) — run the row's next.graph (proof:\"lsp\") to resolve it to confirmed-by-lsp / conflicting-evidence / needs-framework-graph.";
+        readonly partialParse: "Non-fatal structural-search warning. Some files were not parsed, often because a literal prefilter had no anchor; add a literal/rule or broaden proof before claiming absence.";
+        readonly providerUnindexed: "GitHub provider returned zero rows. This is NOT absence. Verify the path with structure, then use bounded local proof: search \"term\" path --repo owner/repo --materialize required, clone owner/repo[/path], or cache fetch owner/repo [path] --depth file|tree|clone.";
+    };
+    readonly query: {
+        readonly schema: "\"oql\" (inserted by normalization)";
+        readonly target: string;
+        readonly from: "{ kind:\"local\", path } | { kind:\"github\", repo?, owner?, ref? } | { kind:\"materialized\", localPath, source? } | { kind:\"npm\" } — local row.path is relative to from.path; the pre-filled next.fetch carries the resolved ABSOLUTE path, so follow it directly rather than re-joining paths yourself";
+        readonly scope: "{ path?, language?, include?, exclude?, excludeDir?, hidden?, noIgnore?, minDepth?, maxDepth? } — minDepth/maxDepth bound directory recursion depth (0-64)";
+        readonly where: "filters for code/files only: text | regex | structural | field | all | any | not. To read a matched file slice, use fetch.content.match. For PR/commit/artifact text narrowing, use that target params hint.";
+        readonly materialize: "{ mode:\"never\"|\"auto\"|\"required\", strategy?:\"file\"|\"tree\"|\"subtree\"|\"repo\", allowFullRepo?, forceRefresh? }";
+        readonly fetch: "{ content?: { contentView:\"exact\"|\"compact\"|\"symbols\", fullContent?, match?:{text|regex,case?}, range?:{startLine?,endLine?,contextLines?}, charOffset?, charLength? }, tree?:{ maxDepth?, pattern?, includeSizes?, extensions?, filesOnly?, directoriesOnly?, sortBy?:\"name\"|\"size\"|\"time\"|\"extension\", reverse? } } — read options for known files/trees; fetch.content.fullContent:true returns the WHOLE file in one shot (lossless, no char-window paging); to read the region around a string, anchor with fetch.content.match (NOT a top-level where, which is code/files only)";
+        readonly params: "target options (validated by OQL for common fields and by the backing tool exhaustively) — see params hints below";
+        readonly select: "string[] projection of result/continuation fields";
+        readonly view: "discovery | paginated | detailed";
+        readonly controls: "{ search?: { countLinesPerFile?, countMatchesPerFile?, onlyMatching?, unique?, countUnique?, contextLines?, invertMatch?, matchWindow?, matchContentLength?, maxMatchesPerFile?, matchPage?, sort?, sortReverse?, rankingProfile?, debugRanking? }, budget?: { maxFiles?, maxCandidates?, maxBytes?, maxMaterializedBytes?, maxPlanNodes?, maxBooleanExpansion?, timeoutMs? } } — output/cost controls";
+        readonly limit: "number — total result cap where supported. Prefer itemsPerPage for paged research/graph/file-history continuations.";
+        readonly page: "number — top-level page number for OQL windowing/continuations";
+        readonly itemsPerPage: "number — page size for the target primary result domain. For code search this may be matched files, not individual matches; per-file match paging uses controls.search.matchPage. Per-target params expose backing-tool sub-pages only (filePage/commentPage/commitPage, entryPageNumber, scanOffset, etc.).";
+        readonly explain: "boolean";
+    };
+    readonly params: {
+        readonly semantics: "{ type:\"definition\"|\"references\"|\"callers\"|\"callees\"|\"callHierarchy\"|\"hover\"|\"documentSymbols\"|\"typeDefinition\"|\"implementation\"|\"workspaceSymbol\"|\"supertypes\"|\"subtypes\"|\"diagnostic\", uri?, symbolName?, symbolKind?, lineHint?, orderHint?, depth?, contextLines?, includeDeclaration?, groupByFile?, workspaceRoot?, format? } — backing tool lspGetSemantics; contextLines adds call-flow snippets; symbolKind filters returned symbol rows after documentSymbols/workspaceSymbol";
+        readonly repositories: "{ keywords?: string[], topicsToSearch?: string[], language?, owner?, stars?, license?, sort?, archived?, limit?, page? } — backing tool ghSearchRepos; keywords/topicsToSearch are arrays even for one term";
+        readonly packages: "{ packageName?: string | keywords?: string[], mode?:\"lean\"|\"full\", page? } — backing tool npmSearch";
+        readonly pullRequests: "{ state?:\"open\"|\"closed\"|\"merged\", author?, label?, keywordsToSearch?, prNumber?, reviewMode?, filePage?, commentPage?, commitPage?, limit?, page?, matchString?, matchScope?:\"body\"|\"title\"|\"comments\"|\"reviews\"|\"all\", content? } — backing tool ghHistoryResearch; matchString filters fetched PR title/body/comments/reviews per matchScope (default body), not a search-index query — no match → zeroMatches";
+        readonly commits: "{ path?, branch?, since?, until?, includeDiff?, limit?, page?, filePage?, itemsPerPage?, matchString? } — backing tool ghHistoryResearch type:\"commits\"; matchString filters commit messages; repo/directory diffs page changed files per commit with filePage/itemsPerPage";
+        readonly artifacts: "{ mode:\"inspect\"|\"list\"|\"extract\"|\"decompress\"|\"strings\"|\"unpack\", minLength?, entryPageNumber?, scanOffset?, charOffset?, charLength?, matchString? } — localBinaryInspect. matchString filters text-producing modes (extract/decompress/strings) over the current fetched payload. For large strings dumps, follow next.search on data.localPath for lossless ripgrep paging; next.artifactContent (charOffset) = next inline text window; next.artifactStrings (scanOffset) = next binary scan window. extract/unpack/decompress → tree at data.localPath (next.structure/next.files).";
+        readonly diff: "{ prNumber, files? } (PR patch via ghHistoryResearch) | { baseRef, headRef, path } (direct two-ref file diff via ghGetFileContent + local line diff); neither shape -> invalidQuery repair";
+        readonly research: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(\"symbols\"|\"files\"|\"dependencies\"|\"relations\")[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles? } — TWO-PHASE: page:1+itemsPerPage:1 → data.summary (full-scope counts) and may include a bounded first packet page; page:2+ → data.packets[] continuation pages (candidates w/ retainedBy edges + per-packet next.*). Always evidence:\"candidate\"/answerReady:false (normal). Follow the row's pre-filled next.graph (proof:\"lsp\", proofLimit-bounded) to upgrade a page to LSP-proven proofStatus.";
+        readonly graph: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(…)[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles?, subject?, subjectKind?, relation?, verdict?, direction?:\"incoming\"|\"outgoing\"|\"both\", proof?:\"none\"|\"lsp\", proofLimit?, includePackets?, includeFacts?, includeEdges? } — UPGRADE PATH: run a research row's pre-filled next.graph directly. proof:\"lsp\" sets per-row proofStatus: \"confirmed-by-lsp\" (refs=0 in bounded workspace; still inspect entrypoints/exports before deletion), \"conflicting-evidence\" (refs>0 → retained, check retainedBy), \"needs-framework-graph\" (maybe an entrypoint). answerReady:false is normal — follow next.* for more pages/proof.";
+        readonly materialize: "(no params; no `where`) clone/cache a bounded corpus (from:{kind:\"github\",repo} + scope.path) and return a stable materialized checkpoint row (localPath/repoRoot/ref/cache/complete) with next.structure/next.files. Use after GitHub providerUnindexed; for CLI alternatives use clone owner/repo[/path] or cache fetch owner/repo [path] --depth file|tree|clone.";
+    };
+    readonly predicates: {
+        readonly text: "{ kind:\"text\", value, case?, wholeWord? }";
+        readonly regex: "{ kind:\"regex\", value, dialect?:\"rust\"|\"pcre2\"|\"provider\", case?, wholeWord?, multiline?, dotAll? }";
+        readonly structural: "{ kind:\"structural\", lang, pattern? | rule? } (exactly one; rule is a JSON object or grep-compatible YAML rule string) — pattern must match the COMPLETE node, so include the parts the real node has: a fn WITH a return type only matches if the pattern has one too (`function $N($$$A): $R { $$$B }`); omitting it returns 0. Shapes: `function $N($$$A) { $$$B }` (no-return-type fn), `($$$A) => $$$B` (arrow, block+expression), `$F($$$A)` (call), `$O.$M($$$A)` (method). For \"find symbol X\" the ROBUST form is a rule, not a pattern: `{ kind:\"function_declaration\", has:{ pattern:\"X\" } }`. 0 matches + no parse error = pattern shape ≠ real node (add `: $R`, or switch to a rule). Note: $$$-only patterns skip files with no literal anchor → low counts; add a literal name or use a regex where.";
+        readonly field: "{ kind:\"field\", field:\"path\"|\"basename\"|\"extension\"|\"size\"|\"modified\"|\"accessed\"|\"empty\"|\"permissions\"|\"executable\"|\"readable\"|\"writable\"|\"entryType\", op:\"=\"|\"!=\"|\"in\"|\"exists\"|\"glob\"|\"regex\"|\">\"|\">=\"|\"<\"|\"<=\"|\"within\"|\"before\", value? } (use symbolic ops like \"=\"; aliases such as \"eq\" are invalid; there is no \"contains\" op — use op:\"glob\", value:\"*term*\" or op:\"regex\"; \"within\"/\"before\" compare modified/accessed times; empty/executable/readable/writable are boolean file attributes paired with op:\"exists\" or op:\"=\")";
+        readonly boolean: "{ kind:\"all\"|\"any\", of: Predicate[] } | { kind:\"not\", predicate }";
+    };
+    readonly batch: {
+        readonly queries: "OqlQuery[] (1-5)";
+        readonly combine: "independent | merge";
+    };
+    readonly explainRoutes: {
+        readonly PUSHDOWN: "Backend evaluates this predicate exactly — good. No residual work.";
+        readonly RESIDUAL: "Backend narrows candidates but OQL must finish evaluation locally.";
+        readonly ROUTE: "OQL must use a different lane, often materialization.";
+        readonly UNSUPPORTED: "OQL cannot execute this predicate safely on the chosen source.";
+    };
+    readonly 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";
+    };
+};
+export declare function oqlSchemaText(): string;

package/dist/oql/shorthand.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Shorthand lowering for `octocode search`.
+ *
+ * The CLI reads argv and resolves a target string to a corpus (local path vs
+ * GitHub ref — the only step that needs the filesystem). Everything else —
+ * which predicate the flags select, dialect, lang requirements, and assembling
+ * the sugar object the normalizer accepts — lives here so it is owned once in
+ * tools-core (not re-implemented in the interface) and is unit-testable without
+ * argv or a terminal.
+ */
+import { type OqlInputBatch, type OqlInputQuery } from './types.js';
+/** Corpus already classified by the caller (local path vs GitHub ref). */
+export type ShorthandCorpus = {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'github';
+    repo: string;
+    path?: string;
+    ref?: string;
+} | {
+    kind: 'npm';
+};
+export interface SearchShorthand {
+    target?: string;
+    view?: string;
+    contentView?: string;
+    search?: string;
+    /** literal text term (used when no pattern/rule/regex flag is set) */
+    text?: string;
+    /** regex pattern (rust dialect unless pcre2) */
+    regex?: string;
+    pcre2?: boolean;
+    /** structural AST pattern (requires lang) */
+    pattern?: string;
+    /** structural rule, already parsed from JSON (requires lang) */
+    rule?: unknown;
+    lang?: string;
+    corpus: ShorthandCorpus;
+    materialize?: 'never' | 'auto' | 'required';
+    branch?: string;
+    forceRefresh?: boolean;
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    include?: string[];
+    exclude?: string[];
+    excludeDir?: string[];
+    extension?: string;
+    filename?: string;
+    pathPattern?: string;
+    hidden?: boolean;
+    noIgnore?: boolean;
+    minDepth?: number;
+    maxDepth?: number;
+    empty?: boolean;
+    modifiedWithin?: string;
+    modifiedBefore?: string;
+    accessedWithin?: string;
+    sizeGreater?: string;
+    sizeLess?: string;
+    permissions?: string;
+    executable?: boolean;
+    readable?: boolean;
+    writable?: boolean;
+    details?: boolean;
+    showModified?: boolean;
+    caseInsensitive?: boolean;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+    fixedString?: boolean;
+    multiline?: boolean;
+    multilineDotall?: boolean;
+    filesOnly?: boolean;
+    directoriesOnly?: boolean;
+    filesWithoutMatch?: boolean;
+    entryType?: 'file' | 'directory';
+    countLinesPerFile?: boolean;
+    countMatchesPerFile?: boolean;
+    onlyMatching?: boolean;
+    unique?: boolean;
+    countUnique?: boolean;
+    contextLines?: number;
+    invertMatch?: boolean;
+    matchWindow?: number;
+    matchContentLength?: number;
+    maxMatchesPerFile?: number;
+    matchPage?: number;
+    maxFiles?: number;
+    sort?: string;
+    sortReverse?: boolean;
+    rankingProfile?: string;
+    debugRanking?: boolean;
+    matchString?: string;
+    matchRegex?: boolean;
+    matchCaseSensitive?: boolean;
+    startLine?: number;
+    endLine?: number;
+    charOffset?: number;
+    charLength?: number;
+    fullContent?: boolean;
+    tree?: boolean;
+    includeSizes?: boolean;
+    op?: string;
+    symbol?: string;
+    symbolKind?: string;
+    uri?: string;
+    line?: number;
+    order?: number;
+    orderDirection?: string;
+    depth?: number;
+    workspaceRoot?: string;
+    format?: string;
+    owner?: string;
+    topic?: string[];
+    stars?: string;
+    forks?: string;
+    goodFirstIssues?: string;
+    license?: string;
+    created?: string;
+    updated?: string;
+    closed?: string;
+    mergedAt?: string;
+    size?: string;
+    match?: string[];
+    archived?: boolean;
+    visibility?: string;
+    concise?: boolean;
+    state?: string;
+    author?: string;
+    label?: string;
+    prNumber?: number;
+    base?: string;
+    head?: string;
+    draft?: boolean;
+    commentsContent?: boolean;
+    commitsContent?: boolean;
+    deep?: boolean;
+    patchFile?: string;
+    reviewMode?: string;
+    filePage?: number;
+    commentPage?: number;
+    commitPage?: number;
+    since?: string;
+    until?: string;
+    patches?: boolean;
+    baseRef?: string;
+    headRef?: string;
+    diffPath?: string;
+    artifactMode?: string;
+    detailed?: boolean;
+    verbose?: boolean;
+    maxEntries?: number;
+    minLength?: number;
+    entryPageNumber?: number;
+    scanOffset?: number;
+    includeOffsets?: boolean;
+    archiveFile?: string;
+    intent?: string;
+    facets?: string[];
+    proof?: string;
+    proofLimit?: number;
+    includePackets?: boolean;
+    includeFacts?: boolean;
+    includeEdges?: boolean;
+}
+export type ShorthandResult = {
+    input: OqlInputQuery | OqlInputBatch;
+} | {
+    error: string;
+};
+/**
+ * Lower shorthand parts into the OQL sugar object. Predicate precedence:
+ * pattern > rule > regex > text. Returns a typed error for invalid combos
+ * (e.g. structural without `lang`) instead of throwing.
+ */
+export declare function buildShorthandInput(parts: SearchShorthand): ShorthandResult;

package/dist/oql/targetParams.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed target-specific `params` schemas.
+ *
+ * Research targets (semantics/repositories/packages/pullRequests/commits/
+ * artifacts/diff/research/graph) carry a `params` bag that the backing tool validates
+ * exhaustively. These schemas type the documented common fields so a type
+ * mistake (e.g. `prNumber:"abc"`) is caught at the OQL layer with a clear
+ * `invalidQuery` instead of failing opaquely at the tool, while `.passthrough()`
+ * keeps the backing tool the source of truth for the rest.
+ */
+import { z } from 'zod';
+import type { OqlActiveTarget } from './types.js';
+/** Per-target params schema; targets without a `params` bag are absent. */
+export declare const TARGET_PARAM_SCHEMAS: Partial<Record<OqlActiveTarget, z.ZodTypeAny>>;
+/**
+ * Validate a target's `params` bag against its typed schema. Returns `null` when
+ * valid (or no schema applies), or a Zod-style error message string the caller
+ * raises as `invalidQuery`.
+ */
+export declare function validateTargetParams(target: OqlActiveTarget, params: unknown): string | null;

package/dist/oql/transformers/contract.d.ts

@@ -0,0 +1,19 @@
+import type { OqlActiveTarget, OqlRecordResultRow, QuerySource } from '../types.js';
+export type TransformerStatus = 'active' | 'planned';
+export type TransformerBackend = {
+    readonly backend: string;
+    readonly operation: string;
+    readonly exact: boolean;
+};
+export type TransformerRegistryEntry = {
+    readonly id: string;
+    readonly target: OqlActiveTarget;
+    readonly sourceKinds: readonly QuerySource['kind'][];
+    readonly status: TransformerStatus;
+    readonly backends: readonly TransformerBackend[];
+    readonly rowKind: 'code' | 'file' | 'tree' | 'content' | 'record';
+    readonly recordType?: OqlRecordResultRow['recordType'];
+    readonly adapterModule?: string;
+    readonly adapterFunctions: readonly string[];
+    readonly notes?: readonly string[];
+};

package/dist/oql/transformers/github/code.d.ts

@@ -0,0 +1,17 @@
+import type { OqlQuery, Predicate } from '../../types.js';
+import type { TransformResult } from '../types.js';
+export type GithubCodeSearchToolQuery = Record<string, unknown>;
+export type GithubCodeSearchTransformOptions = {
+    defaultMatch?: 'file' | 'path';
+    unsupportedMessage?: string;
+    unsupportedBackend?: string;
+};
+/**
+ * Path-like field predicates (`basename`/`extension`/`path` with op `=`) map
+ * directly onto GitHub code-search path qualifiers — the same provider route
+ * OQL target:"files" uses. Returns the ghSearchCode param
+ * fragment, or `null` if the predicate is not a provider-expressible path-field
+ * equality (those still require materialization, per the planner files lane).
+ */
+export declare function githubPathFieldParams(where: Predicate): GithubCodeSearchToolQuery | null;
+export declare function toGithubCodeSearchToolQuery(query: OqlQuery, options?: GithubCodeSearchTransformOptions): TransformResult<GithubCodeSearchToolQuery>;

package/dist/oql/transformers/github/common.d.ts

@@ -0,0 +1,8 @@
+import type { OqlQuery, QueryScope, QuerySource } from '../../types.js';
+export declare function splitGithubSource(source: QuerySource | undefined): {
+    owner?: string;
+    repo?: string;
+};
+export declare function firstScopePath(scope: QueryScope | undefined): string | undefined;
+export declare function firstScopeLanguage(scope: QueryScope | undefined): string | undefined;
+export declare function requestedRowLimit(query: OqlQuery): number | undefined;

package/dist/oql/transformers/language.d.ts

@@ -0,0 +1 @@
+export { classifyLanguageSelector, toGithubCodeLanguageParams, toGithubRepositoryLanguage, toLocalFileLanguageGlobs, toLocalSearchLanguageParams, } from '../../shared/languageSelectors.js';

package/dist/oql/transformers/registry.d.ts

@@ -0,0 +1,16 @@
+import type { OqlActiveTarget, OqlBackendCall, OqlTransformerTrace, QuerySource } from '../types.js';
+import type { TransformerRegistryEntry } from './contract.js';
+export declare function listTransformerEntries(): readonly TransformerRegistryEntry[];
+export declare function findTransformerEntry(args: {
+    sourceKind: QuerySource['kind'];
+    target: OqlActiveTarget;
+    variant?: string;
+}): TransformerRegistryEntry | undefined;
+export declare function findTransformerById(id: string): TransformerRegistryEntry | undefined;
+export declare function findTransformerForQuery(args: {
+    source?: QuerySource;
+    target: OqlActiveTarget;
+    params?: Record<string, unknown>;
+}): TransformerRegistryEntry | undefined;
+export declare function backendCallsForTransformer(entry: TransformerRegistryEntry, source?: QuerySource): OqlBackendCall[];
+export declare function transformerTrace(entry: TransformerRegistryEntry): OqlTransformerTrace;

package/dist/oql/transformers/types.d.ts

@@ -0,0 +1,11 @@
+import type { OqlDiagnostic } from '../types.js';
+export type TransformOk<TQuery extends Record<string, unknown>> = {
+    ok: true;
+    query: TQuery;
+    diagnostics: OqlDiagnostic[];
+};
+export type TransformBlocked = {
+    ok: false;
+    diagnostics: OqlDiagnostic[];
+};
+export type TransformResult<TQuery extends Record<string, unknown>> = TransformOk<TQuery> | TransformBlocked;