git-jev-stage 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+import { Fetch } from '@typesafe-ai/sdk';
+
+interface ProviderErrorOptions extends ErrorOptions {
+    status?: number | undefined;
+    requestId?: string | undefined;
+    retryable?: boolean | undefined;
+}
+declare abstract class JevCoreError extends Error {
+    abstract readonly code: string;
+}
+declare class ProviderError extends JevCoreError {
+    readonly code = "provider";
+    readonly status: number | undefined;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+    constructor(message: string, options?: ProviderErrorOptions);
+}
+declare class RequestTooLargeError extends JevCoreError {
+    readonly code = "request-too-large";
+    readonly estimatedTokens: number;
+    readonly tokenCeiling: number;
+    constructor(estimatedTokens: number, tokenCeiling: number, options?: ErrorOptions);
+}
+declare class ProviderConfigError extends JevCoreError {
+    readonly code = "provider-config";
+    constructor(message: string, options?: ErrorOptions);
+}
+
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+interface ChoiceSpec<L extends string = string> {
+    instructions: string;
+    options: Record<L, string>;
+}
+interface ChoiceAnswer<L extends string = string> {
+    choice: L;
+    confidence: number;
+    probabilities: Record<L, number>;
+}
+type AnswerOutcome<L extends string = string> = {
+    kind: "answer";
+    answer: ChoiceAnswer<L>;
+} | {
+    kind: "missing";
+} | {
+    kind: "invalid";
+    reason: string;
+};
+interface ClassifyRequest<L extends string = string> {
+    state: JsonValue;
+    questions: Record<string, ChoiceSpec<L>>;
+}
+interface ClassifyResult<L extends string = string> {
+    outcomes: Record<string, AnswerOutcome<L>>;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    model: string;
+    requestId?: string;
+}
+interface JevProvider {
+    classify<L extends string>(request: ClassifyRequest<L>, options?: {
+        signal?: AbortSignal;
+    }): Promise<ClassifyResult<L>>;
+}
+interface WindowItem {
+    id: string;
+    text: string;
+    group: string;
+    ordinal: number;
+}
+interface Window {
+    askIds: string[];
+    contextIds: string[];
+    estimatedTokens: number;
+}
+interface WindowOptions {
+    tokenCeiling?: number;
+    sharedTokens: number;
+    perQuestionTokens?: number;
+    neighborContext?: boolean;
+}
+interface RunWindowsOptions {
+    concurrency?: number;
+    signal?: AbortSignal;
+}
+
+type ScriptedAnswer = ChoiceAnswer | {
+    raw: unknown;
+};
+interface FakeScript {
+    answers?: Record<string, ScriptedAnswer>;
+    defaultAnswer?: ChoiceAnswer;
+    error?: Error;
+    delayMs?: number;
+    onRequest?: (request: ClassifyRequest) => void;
+}
+declare class FakeProvider implements JevProvider {
+    #private;
+    readonly requests: ClassifyRequest[];
+    constructor(script?: FakeScript);
+    classify<L extends string>(request: ClassifyRequest<L>, options?: {
+        signal?: AbortSignal;
+    }): Promise<ClassifyResult<L>>;
+    static fromJsonFile(path: string): FakeProvider;
+}
+
+interface TypeSafeJevProviderOptions {
+    apiKey?: string | undefined;
+    baseURL?: string | undefined;
+    model?: string | undefined;
+    timeoutMs?: number | undefined;
+    maxRetries?: number | undefined;
+    fetch?: Fetch | undefined;
+}
+declare class TypeSafeJevProvider implements JevProvider {
+    #private;
+    readonly model: string;
+    constructor(options?: TypeSafeJevProviderOptions);
+    classify<L extends string>(request: ClassifyRequest<L>, options?: {
+        signal?: AbortSignal;
+    }): Promise<ClassifyResult<L>>;
+}
+declare function createProviderFromEnv(env?: Readonly<Record<string, string | undefined>>): TypeSafeJevProvider | undefined;
+declare function validateChoiceAnswer<L extends string = string>(raw: unknown, options: readonly L[]): AnswerOutcome<L>;
+
+declare const CHARS_PER_TOKEN = 4;
+declare const DEFAULT_TOKEN_CEILING = 25000;
+declare const DEFAULT_PER_QUESTION_TOKENS = 40;
+declare function estimateTokens(text: string): number;
+declare function estimateJsonTokens(value: JsonValue): number;
+
+declare const DEFAULT_CONCURRENCY = 4;
+declare function buildWindows(items: readonly WindowItem[], options: WindowOptions): Window[];
+declare function runWindows<T>(windows: readonly Window[], fn: (window: Window, index: number, signal: AbortSignal) => Promise<T>, options?: RunWindowsOptions): Promise<T[]>;
+
+type UnsupportedEntryKind = "symlink" | "submodule" | "binary";
+type StaleSnapshotWhich = "head" | "index" | "diff";
+declare abstract class JevStageError extends Error {
+    abstract readonly code: string;
+    readonly exitCode: number;
+}
+declare class UsageError extends JevStageError {
+    readonly code = "usage";
+    readonly exitCode = 2;
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class NotARepositoryError extends JevStageError {
+    readonly code = "not-a-repository";
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class UnbornRepositoryError extends JevStageError {
+    readonly code = "unborn-repository";
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class UnsupportedGitVersionError extends JevStageError {
+    readonly code = "unsupported-git-version";
+    readonly found: string;
+    readonly minimum: string;
+    constructor(found: string, minimum: string, options?: ErrorOptions);
+}
+declare class UnmergedEntriesError extends JevStageError {
+    readonly code = "unmerged-entries";
+    readonly paths: readonly string[];
+    constructor(paths: readonly string[], options?: ErrorOptions);
+}
+declare class UnsupportedEntryError extends JevStageError {
+    readonly code = "unsupported-entry";
+    readonly kind: UnsupportedEntryKind;
+    readonly paths: readonly string[];
+    constructor(kind: UnsupportedEntryKind, paths: readonly string[], options?: ErrorOptions);
+}
+declare class DiffParseError extends JevStageError {
+    readonly code = "diff-parse";
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class UnknownHunkError extends JevStageError {
+    readonly code = "unknown-hunk";
+    readonly ids: readonly string[];
+    constructor(ids: readonly string[], options?: ErrorOptions);
+}
+declare class PatchApplyError extends JevStageError {
+    readonly code = "patch-apply";
+    readonly stderr: string;
+    constructor(stderr: string, options?: ErrorOptions);
+}
+declare class StaleSnapshotError extends JevStageError {
+    readonly code = "stale-snapshot";
+    readonly exitCode = 3;
+    readonly which: StaleSnapshotWhich;
+    constructor(which: StaleSnapshotWhich, options?: ErrorOptions);
+}
+declare class IndexLockedError extends JevStageError {
+    readonly code = "index-locked";
+    readonly exitCode = 3;
+    readonly lockPath: string;
+    constructor(lockPath: string, options?: ErrorOptions);
+}
+declare class MissingApiKeyError extends JevStageError {
+    readonly code = "missing-api-key";
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class GitCommandError extends JevStageError {
+    readonly code = "git-command";
+    readonly argv: readonly string[];
+    readonly gitExitCode: number;
+    readonly stderr: string;
+    constructor(argv: readonly string[], exitCode: number, stderr: string, options?: ErrorOptions);
+}
+
+type Decision = "include" | "exclude" | "mixed";
+type DecisionSource = "model" | "low-confidence" | "missing" | "invalid" | "too-large" | "provider-error" | "manual" | "no-provider";
+type FileKind = "modified" | "added" | "deleted" | "mode-only";
+interface Hunk {
+    id: string;
+    path: string;
+    ordinal: number;
+    header: string;
+    bytes: Buffer;
+    text: string;
+    added: number;
+    removed: number;
+}
+interface DiffFile {
+    path: string;
+    kind: FileKind;
+    headerBytes: Buffer;
+    hunks: Hunk[];
+}
+interface Snapshot {
+    workTree: string;
+    gitDir: string;
+    indexPath: string;
+    gitEnv: Record<string, string>;
+    headOid: string;
+    indexHash: string;
+    diffHash: string;
+    diffBytes: Buffer;
+    files: DiffFile[];
+    skipped: Array<{
+        path: string;
+        reason: "mode-only" | "empty-file";
+    }>;
+}
+interface HunkDecision {
+    hunkId: string;
+    decision: Decision;
+    source: DecisionSource;
+    confidence?: number;
+    probabilities?: Record<Decision, number>;
+}
+interface Plan {
+    intent: string;
+    exclude?: string;
+    threshold: number;
+    snapshot: Snapshot;
+    decisions: Map<string, HunkDecision>;
+    usage: {
+        requests: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface StageResult {
+    stagedHunkIds: string[];
+    skippedMixedIds: string[];
+    patchBytes: Buffer;
+}
+
+interface GitRunOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: Buffer;
+    maxBuffer?: number;
+}
+interface GitRunResult {
+    stdout: Buffer;
+    stderr: string;
+    exitCode: number;
+}
+interface GitRunner {
+    run(args: string[], options?: GitRunOptions): Promise<GitRunResult>;
+}
+declare function createGitRunner(gitBinary?: string): GitRunner;
+
+interface ApplyPatchToIndexOptions {
+    snapshot: Snapshot;
+    patch: Buffer;
+    git: GitRunner;
+}
+declare function applyPatchToIndex({ snapshot, patch, git, }: ApplyPatchToIndexOptions): Promise<void>;
+declare function stageHunks(snapshot: Snapshot, selectedIds: ReadonlySet<string>, git: GitRunner): Promise<Buffer>;
+declare function cleanupOwnedPaths(): void;
+
+interface SelectionFileSummary {
+    path: string;
+    hunks: number;
+    added: number;
+    removed: number;
+}
+interface SelectionSummary {
+    files: number;
+    hunks: number;
+    added: number;
+    removed: number;
+    perFile: SelectionFileSummary[];
+}
+declare function composePatch(files: readonly DiffFile[], selectedIds: ReadonlySet<string>): Buffer;
+declare function summarizeSelection(files: readonly DiffFile[], selectedIds: ReadonlySet<string>): SelectionSummary;
+
+declare function parseUnifiedDiff(diff: Buffer): DiffFile[];
+
+declare const DIFF_ARGS: readonly string[];
+interface CaptureSnapshotOptions {
+    cwd: string;
+    git: GitRunner;
+}
+declare function captureSnapshot({ cwd, git }: CaptureSnapshotOptions): Promise<Snapshot>;
+
+interface PlanSelectionOptions {
+    cwd: string;
+    intent: string;
+    exclude?: string | undefined;
+    threshold?: number | undefined;
+    provider?: JevProvider | undefined;
+    git?: GitRunner | undefined;
+}
+interface ApplySelectionOptions {
+    includeIds: readonly string[];
+    git?: GitRunner | undefined;
+}
+declare function planSelection(options: PlanSelectionOptions): Promise<Plan>;
+declare function applySelection(plan: Plan, options: ApplySelectionOptions): Promise<StageResult>;
+
+interface ClassifyUsage {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface ClassifyHunksOptions {
+    snapshot: Snapshot;
+    intent: string;
+    exclude?: string | undefined;
+    threshold: number;
+    provider: JevProvider;
+    tokenCeiling?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+interface ClassifyHunksResult {
+    decisions: Map<string, HunkDecision>;
+    usage: ClassifyUsage;
+}
+declare function classifyHunks(options: ClassifyHunksOptions): Promise<ClassifyHunksResult>;
+
+declare const DEFAULT_THRESHOLD = 0.6;
+type PolicyDecision = Omit<HunkDecision, "hunkId">;
+declare function decide(outcome: AnswerOutcome<Decision>, threshold: number): PolicyDecision;
+
+export { type AnswerOutcome, type ApplyPatchToIndexOptions, type ApplySelectionOptions, CHARS_PER_TOKEN, type ChoiceAnswer, type ChoiceSpec, type ClassifyHunksOptions, type ClassifyHunksResult, type ClassifyRequest, type ClassifyResult, type ClassifyUsage, DEFAULT_CONCURRENCY, DEFAULT_PER_QUESTION_TOKENS, DEFAULT_THRESHOLD, DEFAULT_TOKEN_CEILING, DIFF_ARGS, type Decision, type DecisionSource, type DiffFile, DiffParseError, FakeProvider, type FakeScript, type FileKind, GitCommandError, type GitRunner, type Hunk, type HunkDecision, IndexLockedError, JevCoreError, type JevProvider, JevStageError, type JsonValue, MissingApiKeyError, NotARepositoryError, PatchApplyError, type Plan, type PlanSelectionOptions, type PolicyDecision, ProviderConfigError, ProviderError, type ProviderErrorOptions, RequestTooLargeError, type RunWindowsOptions, type ScriptedAnswer, type SelectionFileSummary, type SelectionSummary, type Snapshot, type StageResult, StaleSnapshotError, type StaleSnapshotWhich, TypeSafeJevProvider, type TypeSafeJevProviderOptions, UnbornRepositoryError, UnknownHunkError, UnmergedEntriesError, UnsupportedEntryError, type UnsupportedEntryKind, UnsupportedGitVersionError, UsageError, type Window, type WindowItem, type WindowOptions, applyPatchToIndex, applySelection, buildWindows, captureSnapshot, classifyHunks, cleanupOwnedPaths, composePatch, createGitRunner, createProviderFromEnv, decide, estimateJsonTokens, estimateTokens, parseUnifiedDiff, planSelection, runWindows, stageHunks, summarizeSelection, validateChoiceAnswer };