@octocodeai/octocode-tools-core 16.3.0 → 16.6.0

package/dist/oql/normalize.d.ts

@@ -0,0 +1,5 @@
+import { type OqlCanonicalInput, type OqlInputQuery, type OqlQuery, type OqlSearchInput } from './types.js';
+declare function asArray<T>(v: T | T[] | undefined): T[] | undefined;
+export declare function normalizeInput(input: OqlSearchInput): OqlCanonicalInput;
+export declare function normalizeQuery(input: OqlInputQuery): OqlQuery;
+export { asArray };

package/dist/oql/planner.d.ts

@@ -0,0 +1,7 @@
+import type { OqlExplainPlan, OqlQuery } from './types.js';
+export interface PlanQueryResult {
+    plan: OqlExplainPlan;
+    /** True when no node is UNSUPPORTED and no blocking diagnostic exists. */
+    executable: boolean;
+}
+export declare function planQuery(query: OqlQuery, rawInput: unknown): PlanQueryResult;

package/dist/oql/research/analyze.d.ts

@@ -0,0 +1,134 @@
+export type ResearchIntent = 'general' | 'reachability' | 'dependencies' | 'symbols';
+export type ResearchMode = 'plan' | 'analyze' | 'prove';
+export type ResearchFlowStep = {
+    readonly id: string;
+    readonly purpose: string;
+    readonly tools: readonly string[];
+    readonly produces: readonly string[];
+    readonly evidence: 'heuristic' | 'proof';
+};
+export type ResearchSymbolVerdict = 'reachable' | 'candidate-unused-export' | 'transitive-dead' | 'unused-export' | 'unknown';
+export type ResearchSymbolRow = {
+    readonly symbol: string;
+    readonly kind: string;
+    readonly file: string;
+    readonly line: number;
+    readonly evidenceSource: 'ast' | 'regex';
+    readonly directRefs: number;
+    readonly externalRefs: number;
+    readonly retainedBy: readonly string[];
+    readonly verdict: ResearchSymbolVerdict;
+};
+export type ResearchGraphFactFile = {
+    readonly file: string;
+    readonly source: 'native-ast';
+    readonly language: string;
+    readonly declarations: readonly {
+        readonly name: string;
+        readonly kind: string;
+        readonly line: number;
+        readonly exported: boolean;
+        readonly parent?: string;
+    }[];
+    readonly imports: readonly {
+        readonly specifier: string;
+        readonly line: number;
+        readonly importKind: string;
+        readonly localName?: string;
+        readonly importedName?: string;
+    }[];
+    readonly exports: readonly {
+        readonly name: string;
+        readonly line: number;
+        readonly exportKind: string;
+        readonly localName?: string;
+        readonly source?: string;
+    }[];
+    readonly calls: readonly {
+        readonly caller: string;
+        readonly callee: string;
+        readonly line: number;
+        readonly kind: string;
+    }[];
+    readonly edges: readonly {
+        readonly from: string;
+        readonly to: string;
+        readonly relation: string;
+        readonly source: string;
+        readonly line: number;
+    }[];
+    readonly diagnostics: readonly string[];
+};
+export type ResearchFileIssue = {
+    readonly kind: 'unusedFile';
+    readonly file: string;
+    readonly retainedBy: readonly string[];
+    readonly verdict: 'unused-file';
+};
+export type ResearchDependencyIssue = {
+    readonly kind: 'unlistedDependency' | 'unusedDependency' | 'duplicateDependency';
+    readonly packageName: string;
+    readonly manifest: string;
+    readonly usedBy: readonly string[];
+    readonly declaredIn: readonly string[];
+    readonly verdict: string;
+};
+export type ResearchManifestSummary = {
+    readonly manifest: string;
+    readonly name?: string;
+    readonly entrypoints: readonly string[];
+    readonly dependencyCount: number;
+};
+export type ResearchGraphCapabilitySummary = {
+    readonly graphFactExtensions: readonly string[];
+    readonly capabilityCount: number;
+    readonly factFamilies: readonly string[];
+    readonly sourceFilesByLanguage: Readonly<Record<string, number>>;
+    readonly graphFilesByLanguage: Readonly<Record<string, number>>;
+    readonly missingGraphFacts: readonly {
+        readonly extension: string;
+        readonly files: number;
+        readonly reason: string;
+    }[];
+};
+export type ResearchAnalysisResult = {
+    readonly kind: 'researchFlow';
+    readonly goal: string;
+    readonly intent: ResearchIntent;
+    readonly facets: readonly string[];
+    readonly mode: ResearchMode;
+    readonly root: string;
+    readonly flow: readonly ResearchFlowStep[];
+    readonly summary: {
+        readonly manifests: number;
+        readonly sourceFiles: number;
+        readonly entrypoints: number;
+        readonly reachableFiles: number;
+        readonly unusedFiles: number;
+        readonly unlistedDependencies: number;
+        readonly unusedDependencies: number;
+        readonly duplicateDependencies: number;
+        readonly exportedSymbols: number;
+        readonly candidateUnusedExports: number;
+        readonly transitiveDeadExports: number;
+        readonly nativeGraphFiles: number;
+        readonly nativeGraphDeclarations: number;
+        readonly nativeGraphCalls: number;
+    };
+    readonly manifests: readonly ResearchManifestSummary[];
+    readonly files: readonly ResearchFileIssue[];
+    readonly dependencies: readonly ResearchDependencyIssue[];
+    readonly symbols: readonly ResearchSymbolRow[];
+    readonly graphFacts: readonly ResearchGraphFactFile[];
+    readonly graphCapabilities: ResearchGraphCapabilitySummary;
+    readonly caveats: readonly string[];
+};
+export type AnalyzeResearchOptions = {
+    readonly root: string;
+    readonly goal?: string;
+    readonly intent?: string;
+    readonly facets?: readonly string[];
+    readonly mode?: ResearchMode;
+    readonly maxFiles?: number;
+};
+export declare function analyzeResearchFlow(options: AnalyzeResearchOptions): Promise<ResearchAnalysisResult>;

package/dist/oql/research/packets.d.ts

@@ -0,0 +1,80 @@
+import type { OqlContinuation } from '../types.js';
+import type { ResearchAnalysisResult } from './analyze.js';
+export type EvidenceSource = 'ripgrep' | 'regex' | 'ast' | 'symbols' | 'lsp' | 'manifest' | 'graph' | 'exactRead';
+export type EvidenceConfidence = 'exact' | 'heuristic' | 'partial';
+export interface EvidenceLocation {
+    uri: string;
+    range?: {
+        start: {
+            line: number;
+            character?: number;
+        };
+        end?: {
+            line: number;
+            character?: number;
+        };
+    };
+}
+export interface EvidenceSubject extends EvidenceLocation {
+    id: string;
+    kind: 'file' | 'symbol' | 'function' | 'class' | 'method' | 'interface' | 'type' | 'dependency' | 'package' | 'entrypoint';
+    name?: string;
+    symbolKind?: number | string;
+    language?: string;
+}
+export type EvidenceClaim = 'defines' | 'declares' | 'exports' | 'imports' | 'references' | 'calls' | 'extends' | 'implements' | 'typeUses' | 'entrypoint' | 'unresolved' | 'textMatch' | 'structuralMatch';
+export type EvidenceFlag = 'same-file' | 'external' | 'type-only' | 'test-only' | 'dynamic' | 'string-only' | 'unreachable' | 'generated' | 'declaration';
+export interface EvidenceFact {
+    id: string;
+    subject: EvidenceSubject;
+    claim: EvidenceClaim;
+    source: EvidenceSource;
+    confidence: EvidenceConfidence;
+    flags?: EvidenceFlag[];
+    value?: unknown;
+}
+export type EvidenceRelation = 'contains' | 'defines' | 'exports' | 'imports' | 'references' | 'calls' | 'constructs' | 'extends' | 'implements' | 'typeUses' | 'retains' | 'reachableFrom' | 'declaresDependency' | 'usesDependency';
+export interface EvidenceEdge {
+    id: string;
+    from: EvidenceSubject;
+    to: EvidenceSubject;
+    relation: EvidenceRelation;
+    source: EvidenceSource;
+    confidence: EvidenceConfidence;
+    flags?: EvidenceFlag[];
+    via?: EvidenceLocation;
+}
+export type PacketVerdict = 'reachable' | 'candidate-dead' | 'transitive-dead' | 'candidate-unused-file' | 'candidate-unused-dependency' | 'unknown';
+export type PacketProofStatus = 'candidate' | 'confirmed-by-lsp' | 'confirmed-by-ast-and-lsp' | 'needs-framework-graph' | 'conflicting-evidence';
+export type MissingProofKind = 'lsp-unavailable' | 'dynamic-import-unresolved' | 'framework-entrypoint-unknown' | 'tsconfig-paths-unresolved' | 'manifest-rule-missing' | 'parser-failed' | 'pagination-open';
+export interface MissingProof {
+    kind: MissingProofKind;
+    severity: 'low' | 'medium' | 'high';
+    location?: EvidenceLocation;
+}
+export interface ResearchEvidencePacket {
+    subject: EvidenceSubject;
+    verdict: PacketVerdict;
+    proofStatus: PacketProofStatus;
+    why: EvidenceFact[];
+    retainedBy: EvidenceEdge[];
+    retains?: EvidenceEdge[];
+    missingProof: MissingProof[];
+    proof?: Record<string, unknown>;
+    risk: {
+        deleteRisk: 'low' | 'medium' | 'high' | 'unknown';
+        reason: string;
+    };
+    next: Record<string, OqlContinuation>;
+}
+export interface ResearchGraphSummary {
+    subjects: number;
+    facts: number;
+    edges: number;
+    byVerdict: Record<PacketVerdict, number>;
+}
+export interface ResearchPacketBundle {
+    packets: ResearchEvidencePacket[];
+    graphSummary: ResearchGraphSummary;
+}
+export declare function buildResearchPackets(analysis: ResearchAnalysisResult): ResearchPacketBundle;

package/dist/oql/run.d.ts

@@ -0,0 +1,32 @@
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { type OqlContinuation, type OqlQuery, type OqlResultRow, type OqlRunResult, type OqlSearchInput } from './types.js';
+export interface RunOptions {
+    authInfo?: AuthInfo;
+    /** Plan only; do not execute. Maps to `octocode search --dry-run`. */
+    dryRun?: boolean;
+}
+export declare function runOqlSearch(input: OqlSearchInput, options?: RunOptions): Promise<OqlRunResult>;
+/**
+ * Emit executable `next.*` continuations (contract Gate 10). Every continuation
+ * is a full canonical OQL query runnable as-is.
+ *
+ * Envelope-level:
+ *  - next.page      — more result pages remain
+ *  - next.matchPage — per-file matches were capped
+ *
+ * Per-row continuations are produced by a registry keyed by row kind (and, for
+ * record rows, recordType) so adding a new row's continuations is one entry,
+ * never another `else if`:
+ *  - code        → next.fetch (read exact content) [+ next.semantic on local]
+ *  - content     → next.charRange (page the body)
+ *  - artifact    → next.structure / next.files rooted at the extracted path
+ *  - materialized→ next.structure / next.files rooted at the checkpoint path
+ *  - semantics   → next.fetch (read the code at a symbol location)
+ *  - graph       → next.graph (bounded LSP proof for candidate graph pages)
+ */
+export interface ContinuationCtx {
+    query: OqlQuery;
+    /** code rows: rebuild an absolute `from` from a relativized row path. */
+    fileFrom?: (rowPath: string) => OqlQuery['from'];
+}
+export declare function buildArtifactContinuations(row: OqlResultRow, ctx: ContinuationCtx): Record<string, OqlContinuation> | undefined;