pi-ghost-autocomplete 0.3.1 → 0.3.2

package/dist/eval-dataset.js

@@ -0,0 +1,127 @@
+/**
+ * Offline-eval dataset — capture + load. PRD §M5c.
+ *
+ * One JSONL example per committed prompt sample. The shape captures
+ * everything a replay run needs to reproduce the original ghost call:
+ * `(context, prefix, expected continuation, provider fingerprint)`.
+ *
+ * Privacy: examples DO contain raw prompt text. Capture is gated on the
+ * `PI_GHOST_EVAL_CAPTURE=1` env (not a default behavior — opt-in only).
+ * Sanitization still applies through `containsSensitive` so messages
+ * with API keys are dropped at capture time. Downstream tooling (CLI
+ * replay) ships a `--redact` flag that emits aggregate metrics without
+ * raw examples for publication.
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { containsSensitive } from "./trie-sanitize.js";
+export const EVAL_REL = ".pi/ghost-autocomplete/eval.jsonl";
+/** Char positions at which to sample prefixes from a committed line. */
+export const PREFIX_SAMPLE_POSITIONS = [3, 5, 8, 12, 20];
+/** Beyond `LONG_LINE_START`, sample every `LONG_LINE_STEP` chars. */
+export const LONG_LINE_START = 20;
+export const LONG_LINE_STEP = 10;
+/**
+ * Generate sample (prefix, expected) splits from a committed line. PRD
+ * §M5c: positions `[3, 5, 8, 12, 20]` plus every 10 chars beyond 20.
+ * Returns empty when the committed text is too short for any sample.
+ */
+export function samplePrefixes(committed) {
+    if (!committed)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const len = committed.length;
+    for (const pos of PREFIX_SAMPLE_POSITIONS) {
+        if (pos >= len)
+            break;
+        seen.add(pos);
+        out.push({ prefixLen: pos, prefix: committed.slice(0, pos), expected: committed.slice(pos) });
+    }
+    for (let pos = LONG_LINE_START + LONG_LINE_STEP; pos < len; pos += LONG_LINE_STEP) {
+        if (seen.has(pos))
+            continue;
+        out.push({ prefixLen: pos, prefix: committed.slice(0, pos), expected: committed.slice(pos) });
+    }
+    return out;
+}
+/**
+ * Build eval examples for a single commit. Drops sensitive messages
+ * entirely. `context` should already be rendered by the caller (the
+ * provider's recent-messages block joined into a single string) — keeps
+ * this module decoupled from provider context shape.
+ */
+export function buildExamplesFromCommit(committed, meta, ts = Date.now()) {
+    if (!committed)
+        return [];
+    // Skip multi-line commits — sampling assumes a single source line.
+    // First-line-only would distort expected continuations across newlines.
+    if (committed.includes("\n"))
+        return [];
+    if (containsSensitive(committed))
+        return [];
+    if (containsSensitive(meta.context))
+        return [];
+    return samplePrefixes(committed).map((s) => ({
+        ts,
+        committed,
+        prefixLen: s.prefixLen,
+        prefix: s.prefix,
+        expected: s.expected,
+        ...meta,
+    }));
+}
+export async function appendExamples(cwd, examples) {
+    if (examples.length === 0)
+        return;
+    const path = join(cwd, EVAL_REL);
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const body = examples.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        await appendFile(path, body, "utf8");
+    }
+    catch {
+        // best-effort, never break completions
+    }
+}
+export async function loadExamples(cwd) {
+    const path = join(cwd, EVAL_REL);
+    let body;
+    try {
+        body = await readFile(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    return parseExamples(body);
+}
+export function parseExamples(body) {
+    const out = [];
+    for (const line of body.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (typeof e.ts === "number" &&
+                typeof e.committed === "string" &&
+                typeof e.prefixLen === "number" &&
+                typeof e.prefix === "string" &&
+                typeof e.expected === "string" &&
+                typeof e.context === "string" &&
+                typeof e.providerFingerprint === "string" &&
+                typeof e.versionFingerprint === "string" &&
+                typeof e.providerName === "string") {
+                out.push(e);
+            }
+        }
+        catch {
+            // partial trailing write — ignore
+        }
+    }
+    return out;
+}
+/** Parse `PI_GHOST_EVAL_CAPTURE`. Returns true only when set to "1". */
+export function parseEvalCaptureEnv(raw) {
+    return raw === "1";
+}
+//# sourceMappingURL=eval-dataset.js.map

package/dist/eval-dataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-dataset.js","sourceRoot":"","sources":["../src/eval-dataset.ts"],"names":[],"mappings":"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"}

package/dist/fast-path-engine.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Fast-path engine: owns the three sync ghost sources (session trie,
+ * completion cache, speculative-warm ring) and exposes a single lookup
+ * that returns the winning hit or null. PRD §M1 + §M2.
+ *
+ * Also exposes `decideDeterministic` — a pure function that resolves
+ * the path-prefix / fuzzy-filename decision used by the editor's
+ * deterministic ghost path (PRD §M4 deterministic matchers).
+ *
+ * Refactor #57 slices 1 + 2. Extracted from `ghost-editor.ts` to reduce
+ * the editor's responsibility surface. The engine is state-only — it
+ * does not touch the editor's render or metric pipeline; callers feed
+ * it fingerprints and read the result.
+ *
+ * Mutation methods (set/delete/insertFromAccept/penalize/...) are left
+ * on the inner instances (`engine.cache`, `engine.trie`,
+ * `engine.lastGhosts`) and accessed by the editor directly. Migrating
+ * those into named methods is a follow-up slice; the win here is
+ * consolidating the lookup ordering in one place so it can be unit
+ * tested without spinning up the editor.
+ *
+ * Remaining #57 slices: extract `applyDeterministic` mutation,
+ * ProvisionalManager, CycleManager, MetricsBuilder. ghost-editor.ts
+ * target: <800 LOC.
+ */
+import { CompletionCache, type CacheValue } from "./cache.js";
+import { SessionTrie } from "./session-trie.js";
+import { LastGhostsRing, type LastGhost } from "./speculative.js";
+import type { CompletionMode } from "./metrics.js";
+import { type PathIndex } from "./path-index.js";
+import { type FuzzyBand } from "./fuzzy-matcher.js";
+import { EditHistoryRing, PreEditTextCache } from "./edit-history-ring.js";
+import { type ProvisionalPick, type ReconcileResult } from "./provisional-manager.js";
+import type { ProfileStore } from "./profile-store.js";
+/**
+ * Result of a successful fast-path lookup. Shape intentionally mirrors
+ * the legacy inline-construction in `GhostEditor.handleTextChange` so
+ * the editor's `applyServedGhost` call site is unchanged.
+ *
+ * `cacheKey` is `undefined` for trie hits (the trie keys on raw prefix,
+ * not on the cache key) and a hex digest for cache/speculative hits.
+ */
+export interface FastPathHit {
+    ghost: string;
+    mode: CompletionMode;
+    providerName: string;
+    cacheKey: string | undefined;
+}
+export interface FastPathLookupContext {
+    contextFingerprint: string;
+    providerFingerprint: string;
+    versionFingerprint: string;
+    /** Engine config fingerprint folded into the cache key + warm-path
+     *  match. Optional — when omitted, the engine substitutes its own
+     *  `getConfigFingerprint()` so callers get knob-change invalidation
+     *  by default. */
+    configFingerprint?: string;
+    cooldownActive: boolean;
+    /** Optional `Date.now()` override for deterministic tests. */
+    now?: number;
+}
+/**
+ * Bundled view of every `PI_GHOST_*` env knob that affects lookup,
+ * provisional, rerank, or context selection. Captured once at engine
+ * construction so downstream consumers can migrate off per-call
+ * `process.env` reads incrementally.
+ *
+ * Phase 2 contract: this is **additive**. Existing call sites that still
+ * read `process.env.PI_GHOST_*` continue to work — the values here are
+ * the same strings the env exposed at construction time. Tests that
+ * mutate `process.env` between cases keep working against those call
+ * sites; once a consumer is migrated to read from `engine.config`, that
+ * test must construct a fresh engine.
+ *
+ * `editHistory` lives here too, surfaced from the same single env read
+ * the ring already does. Other modules (config.ts provider envs,
+ * metrics.ts logging envs, eval-dataset capture env) are out of scope —
+ * they don't influence lookup ordering.
+ */
+export interface FastPathEngineConfig {
+    /** Raw `PI_GHOST_RERANK_WEIGHTS` (PRD §M3c). Parser in `reranker.ts`. */
+    rerankWeightsRaw: string | undefined;
+    /** Raw `PI_GHOST_MIN_CONFIDENCE` (PRD §M3c.1). Parser in `reranker.ts`. */
+    minConfidenceRaw: string | undefined;
+    /** Raw `PI_GHOST_PROVISIONAL` (PRD §M3.5b). Parser in `provisional.ts`. */
+    provisionalRaw: string | undefined;
+    /** Raw `PI_GHOST_PROVISIONAL_PREFER` (#6 swap-margin override). */
+    provisionalPreferRaw: string | undefined;
+    /** Raw `PI_GHOST_CONTEXT_BM25_WEIGHT` (PRD §M6b). */
+    contextBm25WeightRaw: string | undefined;
+    /** Raw `PI_GHOST_CONTEXT_EDIT_LOCALITY_WEIGHT` (#1 opt-in). */
+    contextEditLocalityWeightRaw: string | undefined;
+    /** Raw `PI_GHOST_CONTEXT_TOOL_MAX` (PRD §M6c). */
+    contextToolMaxRaw: string | undefined;
+    /** Raw `PI_GHOST_SHORT_HOVER_MS` (#3 short-hover-dismiss threshold). */
+    shortHoverMsRaw: string | undefined;
+    /** Raw `PI_GHOST_REGRET_WINDOW_MS` (PRD §M5a regret window). */
+    regretWindowMsRaw: string | undefined;
+    /** Raw `PI_GHOST_EVAL_CAPTURE` (PRD §M5c eval capture opt-in). */
+    evalCaptureRaw: string | undefined;
+    /** Edit-history (#1) — pre-parsed because the engine itself owns the ring. */
+    editHistory: {
+        enabled: boolean;
+        capacity: number;
+        maxAgeMs: number;
+        halfLifeMs: number;
+    };
+}
+/**
+ * Optional env source. Defaults to `process.env`. Tests can pass a fixed
+ * `Record<string, string | undefined>` to construct an engine with a
+ * specific knob state, no global mutation required.
+ */
+export type EngineEnvSource = Record<string, string | undefined>;
+/**
+ * Build the bundled config snapshot. Reads each knob once. Exported so
+ * tests + diag can compute the same fingerprint deterministically.
+ */
+export declare function buildFastPathEngineConfig(env?: EngineEnvSource): FastPathEngineConfig;
+/**
+ * Stable fingerprint over the bundled config. Suitable for folding into
+ * cache keys so a knob change (e.g. swapping rerank weights mid-session)
+ * invalidates affected entries. Field ordering is the JSON ordering
+ * above; do not reorder without bumping the fingerprint version.
+ */
+export declare function fingerprintFastPathEngineConfig(cfg: FastPathEngineConfig): string;
+export declare class FastPathEngine {
+    readonly cache: CompletionCache;
+    readonly trie: SessionTrie;
+    readonly lastGhosts: LastGhostsRing;
+    /**
+     * Enhancement #1 — edit-history ring + pre-edit text cache. Capacity /
+     * decay parameters read once at construction from
+     * `PI_GHOST_EDIT_HISTORY*` env. The `enabled` flag is the master
+     * switch: when false the editor skips `record()` (zero overhead) and
+     * skips injecting an `editProximityScorer` into the reranker.
+     */
+    readonly editHistory: EditHistoryRing;
+    readonly preEditCache: PreEditTextCache;
+    readonly editHistoryEnabled: boolean;
+    /**
+     * PRD §M4 — workspace path index used by the deterministic matchers
+     * (`decideDeterministic`). `null` until the editor's async indexer
+     * resolves; the deterministic step is skipped in that window.
+     */
+    private pathIndex;
+    /** Phase 2 — bundled env snapshot. Consumers migrate to read from here
+     *  instead of `process.env` over time. Immutable for an engine's lifetime. */
+    readonly config: FastPathEngineConfig;
+    private readonly configFingerprintCached;
+    /**
+     * PRD §M3.5b — provisional ghost manager. Owned by the engine so the
+     *  `picker` closure can be built from the engine's own trie + lastGhosts
+     *  without the editor having to reach in. The editor still supplies the
+     *  `canRender` predicate (editor-state) and `onShow` callback (UI mutator).
+     */
+    private readonly provisional;
+    constructor(env?: EngineEnvSource);
+    /**
+     * Stable fingerprint over the bundled env config. Suitable for folding
+     * into cache keys so a knob change invalidates affected entries. See
+     * `fingerprintFastPathEngineConfig` for the field-ordering contract.
+     */
+    getConfigFingerprint(): string;
+    /**
+     * Install or replace the workspace path index. Called once at editor
+     * startup after the async indexer resolves; may be re-called with
+     * `null` to disable deterministic matching (test / shutdown path).
+     */
+    setPathIndex(pi: PathIndex | null): void;
+    getPathIndex(): PathIndex | null;
+    /** PRD §M2 — seed (prefix, ghost) into the session trie after an accept. */
+    recordAccept(prefix: string, ghost: string, weight: number): void;
+    /** PRD §M2 / #5 — apply a negative-signal penalty to a (prefix, ghost) pair. */
+    penalize(prefix: string, ghost: string, magnitude: number): void;
+    /** PRD §M1a — write a completed ghost into the cache keyed on `cacheKey`. */
+    setCacheEntry(cacheKey: string, value: CacheValue): void;
+    /** PRD §M1a — evict a single cache entry on a non-accept outcome. */
+    deleteCacheEntry(cacheKey: string): void;
+    /** PRD §M1b — record a shown ghost into the speculative-warm ring. */
+    recordRecentGhost(entry: LastGhost): void;
+    /**
+     * PRD §M3.5b — arm a provisional ghost. Engine reads
+     * `PI_GHOST_PROVISIONAL` from the bundled config; no-op when disabled.
+     * The engine builds the `picker` from its own `trie` + `lastGhosts` +
+     * caller's profile. Editor supplies the `canRender` predicate
+     * (editor-state) and `onShow` callback (UI mutator).
+     */
+    armProvisional(input: {
+        prefix: string;
+        debounceMs: number;
+        profile: ProfileStore | null;
+        canRender: () => boolean;
+        onShow: (pick: ProvisionalPick) => void;
+    }): void;
+    /**
+     * PRD §M3.5b — reconcile an LLM result against any displayed
+     * provisional. Engine reads `PI_GHOST_PROVISIONAL_PREFER` from the
+     * bundled config.
+     */
+    reconcileProvisional(input: {
+        llm: {
+            text: string;
+            score: number;
+        } | null;
+        now: number;
+    }): ReconcileResult;
+    /** True iff a provisional pick is currently displayed. */
+    isProvisionalShown(): boolean;
+    /** Cancel a pending provisional timer without touching the displayed pick. */
+    cancelProvisionalTimer(): void;
+    /** Reset provisional state (timer + displayed pick). */
+    clearProvisional(): void;
+    /**
+     * Try, in order: session trie → completion cache → speculative warm.
+     * Returns null when nothing matches. Lookup is sync and allocation-light;
+     * fits inside a keystroke handler.
+     *
+     * `prefix` is the full pre-cursor text (multiline). The trie consults
+     * only the last line (committed messages + accepts are seeded against
+     * single-line prefixes). The cache/warm path consults the full prefix.
+     */
+    lookup(prefix: string, ctx: FastPathLookupContext): FastPathHit | null;
+    /**
+     * Deterministic-aware lookup. Runs `decideDeterministic` first (when
+     * a `deterministic` input is supplied) and falls back to the standard
+     * trie/cache/warm lookup. Returns a discriminated union so the caller
+     * can route deterministic decisions through its `applyDeterministic`
+     * mutator (different metrics path) while still using a single entry
+     * point. Pass `deterministic: null` to skip the path-prefix/fuzzy
+     * matchers (e.g., when an autocomplete popup is open).
+     *
+     * No editor state inside the engine — `deterministic` is supplied as a
+     * fully-formed `DeterministicInput`, and the editor owns the eventual
+     * mutation (`applyServedGhost` / `applyDeterministic`).
+     */
+    lookupWithDeterministic(prefix: string, ctx: FastPathLookupContext, deterministic: DeterministicInput | null): {
+        kind: "deterministic";
+        decision: DeterministicDecision;
+    } | {
+        kind: "fast-path";
+        hit: FastPathHit;
+    } | null;
+}
+/**
+ * Result of a successful deterministic-matcher decision. The editor
+ * applies this via `applyDeterministic()`. Pure — caller owns timing
+ * (`startedAt`) and editor-state mutation.
+ *
+ * `replaceFrom` is non-null for fuzzy matches that replace a typed token
+ * (e.g. `pkg.j` → `package.json`); null for path-prefix completions that
+ * append to the cursor.
+ */
+export interface DeterministicDecision {
+    ghost: string;
+    replaceFrom: {
+        line: number;
+        col: number;
+    } | null;
+    providerName: string;
+    matchedPath: string;
+}
+export interface DeterministicInput {
+    pathIndex: PathIndex;
+    lineText: string;
+    cursorLine: number;
+    cursorCol: number;
+    recentPaths: Set<string>;
+    /** PRD §M4 — bounded boost from profile path-frequency. Null when no profile. */
+    profileBoost: ((path: string) => number) | null;
+}
+/**
+ * Resolve a deterministic ghost candidate from the active path index.
+ * Tries path-prefix first (e.g. `src/co|` → `src/config.ts`), then
+ * fuzzy-filename (e.g. `cfg|` → `config.ts` with replace).
+ *
+ * Pure function — does not consult `this`, autocomplete state, or
+ * cursor mutation. The editor's `tryDeterministic` wraps this with the
+ * `isShowingAutocomplete()` guard and the `applyDeterministic` mutation.
+ *
+ * Returns null when no candidate clears the score gates (≥70 fuzzy
+ * baseline; ≥85 for non-action-trigger contexts).
+ */
+export declare function decideDeterministic(input: DeterministicInput): DeterministicDecision | null;
+export declare function bandToProvider(band: FuzzyBand): string;
+//# sourceMappingURL=fast-path-engine.d.ts.map

package/dist/fast-path-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-path-engine.d.ts","sourceRoot":"","sources":["../src/fast-path-engine.ts"],"names":[],"mappings":"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"}