@octocodeai/octocode-tools-core 16.6.3 → 17.0.2

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

@@ -0,0 +1,46 @@
+/**
+ * OQL planner — the explain-plan shapes describing how a query's predicates
+ * were routed to backends (pushdown/residual/route/unsupported), the backend
+ * calls made, and transformer traces, surfaced when `explain:true`.
+ */
+import type { PredicateId, QuerySource } from './predicates.js';
+import type { MaterializePolicy, OqlCanonicalInput, QueryControls } from './query.js';
+import type { OqlDiagnostic } from './diagnostics.js';
+import type { OqlContinuation } from './envelope.js';
+export type PlanRoute = 'PUSHDOWN' | 'RESIDUAL' | 'ROUTE' | 'UNSUPPORTED';
+export interface OqlPlanNode {
+    predicateId: PredicateId;
+    path: string;
+    route: PlanRoute;
+    backend?: string;
+    reason: string;
+}
+export interface OqlBackendCall {
+    backend: string;
+    source?: QuerySource;
+    operation: string;
+    exact: boolean;
+}
+export interface OqlTransformerTrace {
+    id: string;
+    status: string;
+    sourceKinds: readonly string[];
+    target: string;
+    backends: readonly Pick<OqlBackendCall, 'backend' | 'operation' | 'exact'>[];
+}
+export interface OqlExplainPlan {
+    input: unknown;
+    normalized: OqlCanonicalInput;
+    defaults: Record<string, unknown>;
+    nodes: OqlPlanNode[];
+    backendCalls: OqlBackendCall[];
+    transformers?: readonly OqlTransformerTrace[];
+    materialization?: MaterializePolicy & {
+        required: boolean;
+        reason: string;
+    };
+    budgets: QueryControls['budget'];
+    truncated?: boolean;
+    diagnostics: OqlDiagnostic[];
+    next?: Record<string, OqlContinuation>;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * OQL predicates — the boolean/leaf conditions a query's `where` clause is
+ * built from (text/regex/structural/field matches plus all/any/not
+ * composition), and the query source/scope shapes they operate over.
+ */
+export type PredicateId = string;
+export type QuerySource = {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'github';
+    repo?: string;
+    owner?: string;
+    ref?: string;
+} | {
+    kind: 'materialized';
+    localPath: string;
+    source?: QuerySource;
+} | {
+    kind: 'npm';
+};
+export interface QueryScope {
+    path?: string | string[];
+    language?: string | string[];
+    include?: string[];
+    exclude?: string[];
+    excludeDir?: string[];
+    hidden?: boolean;
+    noIgnore?: boolean;
+    minDepth?: number;
+    maxDepth?: number;
+}
+export interface TextPredicate {
+    id?: PredicateId;
+    kind: 'text';
+    value: string;
+    case?: 'smart' | 'sensitive' | 'insensitive';
+    wholeWord?: boolean;
+}
+export interface RegexPredicate {
+    id?: PredicateId;
+    kind: 'regex';
+    value: string;
+    dialect?: 'rust' | 'pcre2' | 'provider';
+    case?: 'smart' | 'sensitive' | 'insensitive';
+    wholeWord?: boolean;
+    multiline?: boolean;
+    dotAll?: boolean;
+}
+export interface StructuralRule {
+    pattern?: string;
+    kind?: string;
+    inside?: StructuralRule;
+    has?: StructuralRule;
+    not?: StructuralRule;
+    all?: StructuralRule[];
+    any?: StructuralRule[];
+    stopBy?: 'end';
+}
+export type StructuralRuleInput = StructuralRule | string;
+export interface StructuralPredicate {
+    id?: PredicateId;
+    kind: 'structural';
+    lang: string;
+    pattern?: string;
+    rule?: StructuralRuleInput;
+}
+export type FieldName = 'path' | 'basename' | 'extension' | 'size' | 'modified' | 'accessed' | 'empty' | 'permissions' | 'executable' | 'readable' | 'writable' | 'entryType';
+export type FieldOp = '=' | '!=' | 'in' | 'exists' | 'glob' | 'regex' | '>' | '>=' | '<' | '<=' | 'within' | 'before';
+export interface FieldPredicate {
+    id?: PredicateId;
+    kind: 'field';
+    field: FieldName;
+    op: FieldOp;
+    value?: unknown;
+}
+export interface AllPredicate {
+    kind: 'all';
+    id?: PredicateId;
+    of: Predicate[];
+}
+export interface AnyPredicate {
+    kind: 'any';
+    id?: PredicateId;
+    of: Predicate[];
+}
+export interface NotPredicate {
+    kind: 'not';
+    id?: PredicateId;
+    predicate: Predicate;
+}
+export type LeafPredicate = TextPredicate | RegexPredicate | StructuralPredicate | FieldPredicate;
+export type Predicate = AllPredicate | AnyPredicate | NotPredicate | LeafPredicate;

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

@@ -0,0 +1,143 @@
+/**
+ * OQL query/batch input shapes — the canonical `OqlQuery`/`OqlBatch` a query
+ * compiles to, plus the looser `OqlInputQuery`/`OqlInputBatch` edge shapes
+ * that accept sugar (repo/owner/ref/text/regex/... shorthand) before
+ * normalization.
+ */
+import type { OqlActiveTarget, OqlTarget } from './targets.js';
+import type { Predicate, QueryScope, QuerySource, StructuralRule } from './predicates.js';
+export interface MaterializePolicy {
+    mode: 'never' | 'auto' | 'required';
+    strategy?: 'file' | 'tree' | 'subtree' | 'repo';
+    allowFullRepo?: boolean;
+    forceRefresh?: boolean;
+}
+export interface FetchInstructions {
+    content?: {
+        range?: {
+            startLine?: number;
+            endLine?: number;
+            contextLines?: number;
+        };
+        match?: {
+            text: string;
+            regex?: boolean;
+            caseSensitive?: boolean;
+        };
+        contentView?: 'none' | 'standard' | 'symbols';
+        charOffset?: number;
+        charLength?: number;
+        fullContent?: boolean;
+    };
+    tree?: {
+        maxDepth?: number;
+        pattern?: string;
+        includeSizes?: boolean;
+        extensions?: string[];
+        filesOnly?: boolean;
+        directoriesOnly?: boolean;
+        sortBy?: 'name' | 'size' | 'time' | 'extension';
+        reverse?: boolean;
+    };
+}
+export interface QueryControls {
+    search?: {
+        countLinesPerFile?: boolean;
+        countMatchesPerFile?: boolean;
+        onlyMatching?: boolean;
+        unique?: boolean;
+        countUnique?: boolean;
+        contextLines?: number;
+        invertMatch?: boolean;
+        matchWindow?: number;
+        matchContentLength?: number;
+        maxMatchesPerFile?: number;
+        matchPage?: number;
+        sort?: 'relevance' | 'matchCount' | 'path' | 'modified' | 'accessed' | 'created' | 'size' | 'name';
+        sortReverse?: boolean;
+        rankingProfile?: string;
+        debugRanking?: boolean;
+    };
+    budget?: {
+        maxFiles?: number;
+        maxCandidates?: number;
+        maxBytes?: number;
+        maxMaterializedBytes?: number;
+        maxPlanNodes?: number;
+        maxBooleanExpansion?: number;
+        timeoutMs?: number;
+    };
+}
+export type SelectField = string;
+export type QueryView = 'discovery' | 'paginated' | 'detailed';
+export interface OqlQuery {
+    schema: 'oql';
+    id?: string;
+    target: OqlActiveTarget;
+    from?: QuerySource;
+    scope?: QueryScope;
+    where?: Predicate;
+    materialize?: MaterializePolicy;
+    fetch?: FetchInstructions;
+    select?: SelectField[];
+    view?: QueryView;
+    controls?: QueryControls;
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    /**
+     * Target-specific parameter bag. The backing tool's schema remains the
+     * exhaustive validator; OQL validates the documented common fields early.
+     */
+    params?: Record<string, unknown>;
+    explain?: boolean;
+}
+export interface OqlBatch {
+    schema: 'oql';
+    id?: string;
+    queries: OqlQuery[];
+    combine?: 'independent' | 'merge';
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    explain?: boolean;
+}
+export type OqlCanonicalInput = OqlQuery | OqlBatch;
+export interface OqlInputQuery {
+    schema?: 'oql';
+    id?: string;
+    target: OqlTarget;
+    from?: QuerySource;
+    scope?: QueryScope;
+    where?: Predicate;
+    materialize?: MaterializePolicy | 'never' | 'auto' | 'required';
+    fetch?: FetchInstructions;
+    select?: SelectField[];
+    view?: QueryView;
+    controls?: QueryControls;
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    explain?: boolean;
+    repo?: string;
+    owner?: string;
+    ref?: string;
+    path?: string | string[];
+    text?: string;
+    regex?: string;
+    pattern?: string;
+    rule?: StructuralRule;
+    lang?: string;
+    [key: string]: unknown;
+}
+export interface OqlInputBatch {
+    schema?: 'oql';
+    id?: string;
+    queries: OqlInputQuery[];
+    combine?: 'independent' | 'merge';
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    explain?: boolean;
+}
+export type OqlSearchInput = OqlInputQuery | OqlInputBatch;

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

@@ -0,0 +1,127 @@
+/**
+ * OQL record `data` contracts — the documented payload shapes per
+ * `recordType` (repository, package, PR, commit, diff, semantics,
+ * materialized, research, graph). The backing tool owns the exhaustive
+ * payload; these name the fields agents rely on to cite + continue. All
+ * optional (backend-dependent); never fabricated.
+ */
+import type { Pagination } from './envelope.js';
+export interface OqlRepositoryData {
+    fullName?: string;
+    owner?: string;
+    repo?: string;
+    description?: string;
+    stars?: number;
+    forks?: number;
+    language?: string;
+    topics?: string[];
+    pushedAt?: string;
+    url?: string;
+    [k: string]: unknown;
+}
+export interface OqlPackageData {
+    name?: string;
+    version?: string;
+    description?: string;
+    downloads?: number;
+    repository?: string;
+    repositoryId?: string;
+    [k: string]: unknown;
+}
+export interface OqlPullRequestData {
+    number?: number;
+    title?: string;
+    state?: string;
+    author?: string;
+    createdAt?: string;
+    mergedAt?: string;
+    changedFiles?: number;
+    url?: string;
+    [k: string]: unknown;
+}
+export interface OqlCommitData {
+    sha?: string;
+    oid?: string;
+    message?: string;
+    title?: string;
+    author?: string;
+    date?: string;
+    [k: string]: unknown;
+}
+export interface OqlDiffData {
+    path?: string;
+    baseRef?: string;
+    headRef?: string;
+    additions?: number;
+    deletions?: number;
+    unchanged?: number;
+    patch?: string;
+    [k: string]: unknown;
+}
+export interface OqlSemanticsData {
+    uri?: string;
+    line?: number;
+    startLine?: number;
+    symbol?: string;
+    kind?: string;
+    [k: string]: unknown;
+}
+export interface OqlMaterializedData {
+    localPath: string;
+    repoRoot?: string;
+    ref?: string;
+    cache?: 'hit' | 'miss';
+    complete?: boolean;
+    [k: string]: unknown;
+}
+export interface OqlResearchData {
+    kind?: 'researchFlow';
+    goal?: string;
+    intent?: string;
+    facets?: readonly string[];
+    mode?: 'plan' | 'analyze' | 'prove';
+    summary?: Record<string, unknown>;
+    flow?: readonly unknown[];
+    nativeGraphSummary?: Record<string, unknown>;
+    graphSummary?: Record<string, unknown>;
+    packetPage?: Pagination;
+    packets?: unknown[];
+    /** Present only in detailed view — a windowed slice (see `manifestsPage`). */
+    manifests?: unknown[];
+    manifestsPage?: Pagination;
+    /** Present only in detailed view — a windowed slice (see `filesPage`). */
+    files?: unknown[];
+    filesPage?: Pagination;
+    /** Present only in detailed view — a windowed slice (see `dependenciesPage`). */
+    dependencies?: unknown[];
+    dependenciesPage?: Pagination;
+    /** Present only in detailed view — a windowed slice (see `symbolsPage`). */
+    symbols?: unknown[];
+    symbolsPage?: Pagination;
+    /** Present only in detailed view — a windowed slice (see `graphFactsPage`). */
+    graphFacts?: unknown[];
+    graphFactsPage?: Pagination;
+    caveats?: string[];
+    [k: string]: unknown;
+}
+export interface OqlGraphData {
+    kind?: 'relationshipGraph';
+    goal?: string;
+    intent?: string;
+    facets?: readonly string[];
+    mode?: 'plan' | 'analyze' | 'prove';
+    root?: string;
+    filters?: Record<string, unknown>;
+    summary?: Record<string, unknown>;
+    flow?: readonly unknown[];
+    nativeGraphSummary?: Record<string, unknown>;
+    graphSummary?: unknown;
+    packetPage?: Pagination;
+    nodes?: unknown[];
+    edges?: unknown[];
+    facts?: unknown[];
+    packets?: unknown[];
+    missingProof?: unknown[];
+    caveats?: string[];
+    [k: string]: unknown;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * OQL typed record-row aliases — a record row narrowed to a specific
+ * `recordType` + matching `data` shape, plus the overall `OqlResultRow` union
+ * and its proof-graded variant.
+ */
+import type { OqlCodeResultRow, OqlContentResultRow, OqlFileResultRow, OqlProofGrade, OqlRecordResultRow, OqlTreeResultRow } from './results.js';
+import type { OqlCommitData, OqlDiffData, OqlGraphData, OqlMaterializedData, OqlPackageData, OqlPullRequestData, OqlRepositoryData, OqlResearchData, OqlSemanticsData } from './recordData.js';
+/** Typed row aliases — a record row whose `data` matches its `recordType`. */
+export type OqlRepositoryRow = OqlRecordResultRow & {
+    recordType: 'repository';
+    data: OqlRepositoryData;
+};
+export type OqlPackageRow = OqlRecordResultRow & {
+    recordType: 'package';
+    data: OqlPackageData;
+};
+export type OqlPullRequestRow = OqlRecordResultRow & {
+    recordType: 'pullRequest';
+    data: OqlPullRequestData;
+};
+export type OqlCommitRow = OqlRecordResultRow & {
+    recordType: 'commit';
+    data: OqlCommitData;
+};
+export type OqlDiffRow = OqlRecordResultRow & {
+    recordType: 'diff';
+    data: OqlDiffData;
+};
+export type OqlSemanticsRow = OqlRecordResultRow & {
+    recordType: 'semantics';
+    data: OqlSemanticsData;
+};
+export type OqlMaterializedRow = OqlRecordResultRow & {
+    recordType: 'materialized';
+    data: OqlMaterializedData;
+};
+export type OqlResearchRow = OqlRecordResultRow & {
+    recordType: 'research';
+    data: OqlResearchData;
+};
+export type OqlGraphRow = OqlRecordResultRow & {
+    recordType: 'graph';
+    data: OqlGraphData;
+};
+export type OqlResultRow = OqlCodeResultRow | OqlFileResultRow | OqlTreeResultRow | OqlContentResultRow | OqlRecordResultRow;
+export type OqlProofGradedResultRow = OqlResultRow & {
+    proofGrade: OqlProofGrade;
+};

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

@@ -0,0 +1,118 @@
+/**
+ * OQL result rows — the per-kind row shapes a result envelope's `results[]`
+ * can hold (code/file/tree/content matches, and the generic `record` row
+ * used by typed research objects; see record-data.ts / record-rows.ts for
+ * the `recordType`-specific `data` payloads and aliases).
+ */
+import type { QuerySource } from './predicates.js';
+import type { OqlContinuation } from './envelope.js';
+export type OqlProofGrade = 'candidate' | 'text' | 'structural' | 'semantic' | 'graph' | 'missing';
+interface OqlProofGradedRow {
+    /**
+     * Mandatory on rows emitted by `runOqlSearch`; adapters may omit it while the
+     * runner computes the final proof grade from query semantics and row shape.
+     */
+    proofGrade?: OqlProofGrade;
+}
+export interface OqlCodeResultRow extends OqlProofGradedRow {
+    kind: 'code';
+    source?: QuerySource;
+    path: string;
+    /**
+     * 1-based match line. Optional because some providers (GitHub code search)
+     * return path-level matches with no line — never fabricate one.
+     */
+    line?: number;
+    endLine?: number;
+    column?: number;
+    snippet?: string;
+    /** File-level count payloads from local search count modes. */
+    totalMatchedLines?: number;
+    totalOccurrences?: number;
+    /** Provider snippet offsets when available, e.g. GitHub code search indices. */
+    matchIndices?: Array<{
+        start: number;
+        end: number;
+        lineOffset?: number;
+    }>;
+    /** Row-level provider/context metadata that is useful but not identity. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Structural (AST) metavariable captures. `$X` → single-element list; `$$$X`
+     * → node list. Keyed by bare metavar name. Present only for structural
+     * matches that captured; never fabricated.
+     */
+    metavars?: Record<string, string[]>;
+    /** Per-capture source ranges (uri+line ready for lspGetSemantics handoff). */
+    metavarRanges?: Record<string, {
+        text: string;
+        line: number;
+        column: number;
+        endLine: number;
+        endColumn: number;
+    }[]>;
+    /**
+     * Deterministic AST match-kind label from the engine classifier
+     * (declaration|import|export|callsite|identifier|comment|string|…).
+     * Lexical coverage signal — not semantic identity.
+     */
+    matchKind?: string;
+    /** Fixed table derived from matchKind (0.0..1.0); not relevance ranking. */
+    scoreHint?: number;
+    /**
+     * Executable follow-up continuations. Keys are dotted *domain names*
+     * (`next.<domain>`, e.g. `next.fetch`, `next.semantic`, `next.charRange`),
+     * NOT nested object paths — the registry in run.ts owns the key set.
+     */
+    next?: Record<string, OqlContinuation>;
+}
+export interface OqlFileResultRow extends OqlProofGradedRow {
+    kind: 'file';
+    source?: QuerySource;
+    path: string;
+    entryType: 'file' | 'directory';
+    size?: number;
+    modified?: string;
+    next?: Record<string, OqlContinuation>;
+}
+export interface OqlTreeResultRow extends OqlProofGradedRow {
+    kind: 'tree';
+    source?: QuerySource;
+    path: string;
+    entryType: 'file' | 'directory';
+    depth: number;
+    size?: number;
+    children?: OqlTreeResultRow[];
+    next?: Record<string, OqlContinuation>;
+}
+export interface OqlContentResultRow extends OqlProofGradedRow {
+    kind: 'content';
+    source?: QuerySource;
+    path: string;
+    content: string;
+    range?: {
+        startLine?: number;
+        endLine?: number;
+        charOffset?: number;
+        charLength?: number;
+    };
+    contentView: 'none' | 'standard' | 'symbols';
+    next?: Record<string, OqlContinuation>;
+}
+/**
+ * Generic record row for targets whose payload is a typed research object
+ * (repository, package, PR, commit, symbol/location, diff, packet).
+ * `recordType` names the family; `data` is the row payload.
+ */
+export interface OqlRecordResultRow extends OqlProofGradedRow {
+    kind: 'record';
+    recordType: 'semantics' | 'repository' | 'package' | 'pullRequest' | 'commit' | 'diff' | 'research' | 'graph' | 'materialized';
+    /** Stable, citeable identity (repo, name@version, #PR, SHA, path, uri). */
+    id?: string;
+    source?: QuerySource;
+    /** Parent/query metadata preserved from the backing tool payload. */
+    metadata?: Record<string, unknown>;
+    data: Record<string, unknown>;
+    next?: Record<string, OqlContinuation>;
+}
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * OQL targets — the addressable "shapes" a query can search
+ * (code/content/structure/files/... ) plus reserved (not-yet-active) targets
+ * and the sort values each lane can execute.
+ */
+export type OqlActiveTarget = 'code' | 'content' | 'structure' | 'files' | 'semantics' | 'repositories' | 'packages' | 'pullRequests' | 'commits' | 'diff' | 'research' | 'graph' | 'materialize';
+export type OqlReservedTarget = 'fixes' | 'dataflow';
+export type OqlTarget = OqlActiveTarget | OqlReservedTarget;
+export declare const ACTIVE_TARGETS: readonly OqlActiveTarget[];
+export declare const RESERVED_TARGETS: readonly OqlReservedTarget[];
+/** Targets that do not need a code corpus (provider/registry discovery). */
+export declare const CORPUS_OPTIONAL_TARGETS: readonly OqlActiveTarget[];
+/**
+ * Which `controls.search.sort` values each lane can actually execute
+ * (files: localFindFiles sortBy; code: code-search ranking sorts). Single
+ * source for shorthand lowering and the planner's inapplicable-sort warning —
+ * a value outside the target's set is IGNORED by the backend, never an error.
+ */
+export declare const SEARCH_SORTS_BY_TARGET: {
+    readonly code: readonly ["relevance", "matchCount", "path", "modified", "accessed", "created"];
+    readonly files: readonly ["size", "name", "path", "modified"];
+};