pi-ghost-autocomplete 0.3.1 → 0.3.2

package/dist/cycle-manager.d.ts

@@ -0,0 +1,102 @@
+/**
+ * CycleManager — owns multi-candidate state and word-level partial-accept
+ * gestures for the GREAT Ghost autocomplete.
+ *
+ * PRD §M3e (Alt+]/Alt+[ cycling with clamp-at-edges, no wrap) +
+ * PRD §M3f (Ctrl+Right word-by-word acceptance in append mode).
+ *
+ * Design notes:
+ *
+ *  - Candidate list is stored read-only (frozen) so that future refactors
+ *    don't accidentally mutate ranked text. Per-candidate consumption from
+ *    word-level accepts is tracked separately in `consumed[idx]`.
+ *  - `current` returns `string | null` — `null` distinguishes "no candidates
+ *    installed" from "current candidate is empty after full consumption".
+ *  - `acceptPartialWordAppend()` is named to make the append-mode invariant
+ *    impossible to forget at call sites. Replace-mode ghosts (fuzzy/path)
+ *    accept atomically; word-by-word doesn't apply.
+ *  - No hidden auto-reset: caller is responsible for `reset()` after the
+ *    final-chunk accept so the lifecycle is explicit.
+ *
+ * Extracted as part of refactor #57 so `GhostEditor` stays thin.
+ */
+/**
+ * Pure helper: compute the next index for Alt+]/Alt[+ cycle.
+ * Returns null when the move would go past an edge (no wrap, per PRD).
+ */
+export declare function cycleCandidateIdx(currentIdx: number, len: number, dir: 1 | -1): number | null;
+/**
+ * Extract the next lexical "word" chunk from the start of a ghost string.
+ * Skips leading whitespace, then either consumes an identifier run (`\w+`)
+ * OR a single non-word non-space char so code like `foo("bar")` accepts as
+ * `foo`, `(`, `"`, `bar`, `"`, `)` rather than gulping the whole
+ * expression. Used by Ctrl+Right partial accept.
+ *
+ * Returns the empty string when the ghost is empty or contains only
+ * whitespace — caller treats that as a no-op.
+ */
+export declare function nextWordChunk(ghost: string): string;
+/**
+ * CycleManager — small mutable facade over CycleState.
+ * All mutation goes through the manager so editor code stays declarative.
+ */
+export declare class CycleManager {
+    private state;
+    reset(): void;
+    /**
+     * Install a fresh ranked candidate list for a newly shown ghost.
+     * Always resets indices, cycledCount, partialAccepts, and consumed
+     * offsets. The stored list is frozen — partial-accepts shrink the
+     * per-candidate `consumed` offset, never the underlying text.
+     */
+    setCandidates(texts: string[]): void;
+    /**
+     * Read-only view of the ranked candidate list as installed. Stable across
+     * partial accepts (consumption is tracked separately via `current`).
+     */
+    get candidates(): readonly string[];
+    /**
+     * Currently displayed ghost text — the un-consumed remainder of the
+     * candidate at `candidateIdx`. Returns `null` when no candidates are
+     * installed; returns `""` when the current candidate has been fully
+     * consumed by partial accepts (caller must then `reset()`).
+     */
+    get current(): string | null;
+    get cycledCount(): number;
+    get partialAccepts(): number;
+    get candidateIdx(): number;
+    /**
+     * Attempt a cycle in the given direction. Returns true if the ghost text
+     * actually changed (i.e., a legal non-edge move occurred). Each
+     * candidate retains its own `consumed` offset across cycles so the user
+     * can partial-accept on A, cycle to B, cycle back to A and resume.
+     */
+    cycle(dir: 1 | -1): boolean;
+    /**
+     * Perform a word-level partial accept on the currently displayed
+     * candidate. APPEND MODE ONLY — callers must check
+     * `!ghostReplaceFrom && cursorAtEnd()` before invoking. Naming
+     * deliberately includes `Append` so the invariant is impossible to
+     * forget at the call site.
+     *
+     * Returns the chunk that should be inserted now, plus the remaining
+     * ghost suffix (or `null` if this was the final chunk). When `remaining`
+     * is `null` the caller is responsible for finalizing and calling
+     * `reset()` — the manager does NOT auto-reset so lifecycle stays
+     * explicit.
+     */
+    acceptPartialWordAppend(): {
+        chunk: string;
+        remaining: string | null;
+    };
+    /**
+     * Snapshot for diagnostics / metrics (no raw candidate text leaked).
+     */
+    snapshot(): {
+        count: number;
+        idx: number;
+        cycled: number;
+        partials: number;
+    };
+}
+//# sourceMappingURL=cycle-manager.d.ts.map

package/dist/cycle-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-manager.d.ts","sourceRoot":"","sources":["../src/cycle-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAK7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAInD;AAED;;;GAGG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,KAAK,CAA4B;IAEzC,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAWpC;;;OAGG;IACH,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAED;;;;;OAKG;IACH,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAI3B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO;IAc3B;;;;;;;;;;;;OAYG;IACH,uBAAuB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IAgBtE;;OAEG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;CAQ5E"}

package/dist/cycle-manager.js

@@ -0,0 +1,168 @@
+/**
+ * CycleManager — owns multi-candidate state and word-level partial-accept
+ * gestures for the GREAT Ghost autocomplete.
+ *
+ * PRD §M3e (Alt+]/Alt+[ cycling with clamp-at-edges, no wrap) +
+ * PRD §M3f (Ctrl+Right word-by-word acceptance in append mode).
+ *
+ * Design notes:
+ *
+ *  - Candidate list is stored read-only (frozen) so that future refactors
+ *    don't accidentally mutate ranked text. Per-candidate consumption from
+ *    word-level accepts is tracked separately in `consumed[idx]`.
+ *  - `current` returns `string | null` — `null` distinguishes "no candidates
+ *    installed" from "current candidate is empty after full consumption".
+ *  - `acceptPartialWordAppend()` is named to make the append-mode invariant
+ *    impossible to forget at call sites. Replace-mode ghosts (fuzzy/path)
+ *    accept atomically; word-by-word doesn't apply.
+ *  - No hidden auto-reset: caller is responsible for `reset()` after the
+ *    final-chunk accept so the lifecycle is explicit.
+ *
+ * Extracted as part of refactor #57 so `GhostEditor` stays thin.
+ */
+function emptyState() {
+    return {
+        originals: Object.freeze([]),
+        consumed: [],
+        candidateIdx: 0,
+        cycledCount: 0,
+        partialAccepts: 0,
+    };
+}
+/**
+ * Pure helper: compute the next index for Alt+]/Alt[+ cycle.
+ * Returns null when the move would go past an edge (no wrap, per PRD).
+ */
+export function cycleCandidateIdx(currentIdx, len, dir) {
+    if (len <= 1)
+        return null;
+    const next = currentIdx + dir;
+    if (next < 0 || next >= len)
+        return null;
+    return next;
+}
+/**
+ * Extract the next lexical "word" chunk from the start of a ghost string.
+ * Skips leading whitespace, then either consumes an identifier run (`\w+`)
+ * OR a single non-word non-space char so code like `foo("bar")` accepts as
+ * `foo`, `(`, `"`, `bar`, `"`, `)` rather than gulping the whole
+ * expression. Used by Ctrl+Right partial accept.
+ *
+ * Returns the empty string when the ghost is empty or contains only
+ * whitespace — caller treats that as a no-op.
+ */
+export function nextWordChunk(ghost) {
+    if (!ghost)
+        return "";
+    const m = /^\s*(\w+|[^\s\w])/.exec(ghost);
+    return m ? m[0] : "";
+}
+/**
+ * CycleManager — small mutable facade over CycleState.
+ * All mutation goes through the manager so editor code stays declarative.
+ */
+export class CycleManager {
+    state = emptyState();
+    reset() {
+        this.state = emptyState();
+    }
+    /**
+     * Install a fresh ranked candidate list for a newly shown ghost.
+     * Always resets indices, cycledCount, partialAccepts, and consumed
+     * offsets. The stored list is frozen — partial-accepts shrink the
+     * per-candidate `consumed` offset, never the underlying text.
+     */
+    setCandidates(texts) {
+        const originals = Object.freeze(texts.length > 0 ? [...texts] : []);
+        this.state = {
+            originals,
+            consumed: new Array(originals.length).fill(0),
+            candidateIdx: 0,
+            cycledCount: 0,
+            partialAccepts: 0,
+        };
+    }
+    /**
+     * Read-only view of the ranked candidate list as installed. Stable across
+     * partial accepts (consumption is tracked separately via `current`).
+     */
+    get candidates() {
+        return this.state.originals;
+    }
+    /**
+     * Currently displayed ghost text — the un-consumed remainder of the
+     * candidate at `candidateIdx`. Returns `null` when no candidates are
+     * installed; returns `""` when the current candidate has been fully
+     * consumed by partial accepts (caller must then `reset()`).
+     */
+    get current() {
+        const o = this.state.originals[this.state.candidateIdx];
+        if (o === undefined)
+            return null;
+        return o.slice(this.state.consumed[this.state.candidateIdx] ?? 0);
+    }
+    get cycledCount() {
+        return this.state.cycledCount;
+    }
+    get partialAccepts() {
+        return this.state.partialAccepts;
+    }
+    get candidateIdx() {
+        return this.state.candidateIdx;
+    }
+    /**
+     * Attempt a cycle in the given direction. Returns true if the ghost text
+     * actually changed (i.e., a legal non-edge move occurred). Each
+     * candidate retains its own `consumed` offset across cycles so the user
+     * can partial-accept on A, cycle to B, cycle back to A and resume.
+     */
+    cycle(dir) {
+        const nextIdx = cycleCandidateIdx(this.state.candidateIdx, this.state.originals.length, dir);
+        if (nextIdx === null) {
+            return false;
+        }
+        this.state.candidateIdx = nextIdx;
+        this.state.cycledCount++;
+        return true;
+    }
+    /**
+     * Perform a word-level partial accept on the currently displayed
+     * candidate. APPEND MODE ONLY — callers must check
+     * `!ghostReplaceFrom && cursorAtEnd()` before invoking. Naming
+     * deliberately includes `Append` so the invariant is impossible to
+     * forget at the call site.
+     *
+     * Returns the chunk that should be inserted now, plus the remaining
+     * ghost suffix (or `null` if this was the final chunk). When `remaining`
+     * is `null` the caller is responsible for finalizing and calling
+     * `reset()` — the manager does NOT auto-reset so lifecycle stays
+     * explicit.
+     */
+    acceptPartialWordAppend() {
+        const cur = this.current;
+        if (cur === null || cur.length === 0) {
+            return { chunk: "", remaining: null };
+        }
+        const chunk = nextWordChunk(cur);
+        if (!chunk) {
+            return { chunk: "", remaining: null };
+        }
+        const idx = this.state.candidateIdx;
+        this.state.consumed[idx] = (this.state.consumed[idx] ?? 0) + chunk.length;
+        this.state.partialAccepts++;
+        const tail = cur.slice(chunk.length);
+        return { chunk, remaining: tail.length === 0 ? null : tail };
+    }
+    /**
+     * Snapshot for diagnostics / metrics (no raw candidate text leaked).
+     */
+    snapshot() {
+        return {
+            count: this.state.originals.length,
+            idx: this.state.candidateIdx,
+            cycled: this.state.cycledCount,
+            partials: this.state.partialAccepts,
+        };
+    }
+}
+//# sourceMappingURL=cycle-manager.js.map

package/dist/cycle-manager.js.map

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

package/dist/edit-history-ring.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Edit-history ring + aggregated index. Enhancement #1
+ * (Next-Edit-Prediction motivated). See `docs/edit-history-signals-spec.md`.
+ *
+ * Records the most recent K edits (default 32) made in-session, then
+ * exposes:
+ *  - a `snapshot()` of newest-first events with age filtering, and
+ *  - an `index()` of decayed token frequencies + per-URI line proximity.
+ *
+ * The reranker reads `index()` to compute `editProximityBoost`; the M6
+ * context selector reads it (opt-in) for a token-overlap locality bit.
+ *
+ * Privacy: events are pre-sanitized at capture (`containsSensitive` on
+ * the raw added/removed text — caller is responsible for invoking it
+ * before calling `record`). Only tokens + scalars + URIs survive. No
+ * raw text is ever stored on the ring. The ring lives in-process only —
+ * no persistence in v0.5.
+ */
+export declare const TOKEN_CAP_PER_EVENT = 16;
+export declare const DEFAULT_CAPACITY = 32;
+export declare const DEFAULT_MAX_AGE_MS: number;
+export declare const DEFAULT_HALF_LIFE_MS: number;
+export interface EditEvent {
+    ts: number;
+    uri: string;
+    rangeStartLine: number;
+    addedTokens: string[];
+    removedTokens: string[];
+    netCharDelta: number;
+}
+export interface EditHistoryIndex {
+    addedFreq: Map<string, number>;
+    removedFreq: Map<string, number>;
+    recentUris: Set<string>;
+    lastEditLineByUri: Map<string, number>;
+    totalEvents: number;
+}
+export interface EditHistoryOpts {
+    capacity?: number;
+    maxAgeMs?: number;
+    halfLifeMs?: number;
+}
+/**
+ * Tokenize text using the same regex as `profile.ts` (`\b[\w][\w-]*\b`).
+ * Code identifiers are case-sensitive — we do NOT lowercase. Result is
+ * capped at `TOKEN_CAP_PER_EVENT` to bound memory per event.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Exponential time-decay weight: 1.0 at `ageMs=0`, halves every
+ * `halfLifeMs`. Pure helper for tests + index().
+ */
+export declare function timeDecayWeight(ageMs: number, halfLifeMs?: number): number;
+export declare class EditHistoryRing {
+    private readonly events;
+    readonly capacity: number;
+    readonly maxAgeMs: number;
+    readonly halfLifeMs: number;
+    constructor(opts?: EditHistoryOpts);
+    /**
+     * Append an event. `ts` defaults to `Date.now()`. Caller is responsible
+     * for sanitization — the ring does not re-validate. Overflow drops the
+     * oldest event.
+     */
+    record(ev: Omit<EditEvent, "ts"> & {
+        ts?: number;
+    }): void;
+    /**
+     * Newest-first list of events not older than `maxAgeMs`. Returns a
+     * copy — safe for the caller to retain.
+     *
+     * Scans without early-break: we cannot assume `record()` was called in
+     * ts-monotonic order (a backfill or test clock could insert older
+     * events after newer ones). At capacity=32 the scan cost is trivial.
+     */
+    snapshot(now?: number): EditEvent[];
+    /**
+     * Aggregated index of recent edit signals, with exponential time-decay
+     * applied to token frequencies. URIs touched within `maxAgeMs` are
+     * collected; the *most recent* edit line per URI is kept (used by the
+     * reranker for line-proximity scoring).
+     */
+    index(now?: number): EditHistoryIndex;
+    clear(): void;
+    get size(): number;
+}
+/** Default per-entry size cap. 1 MB — large enough for any realistic
+ *  source file, small enough that 16 × 1MB = 16MB worst-case is bounded. */
+export declare const DEFAULT_PRE_EDIT_MAX_BYTES: number;
+/**
+ * Per-document pre-edit text cache. Holds the most recent `capacity`
+ * document texts so we can derive the *removed* slice of an edit before
+ * the on-disk text mutates. LRU-bounded to avoid pinning every project
+ * file in RAM. v0.5 stores transiently in process only — never persisted.
+ *
+ * Per-entry size is capped at `maxBytesPerEntry` (default 1 MB). Texts
+ * exceeding the cap are stored as empty string — the next edit on that
+ * document will derive empty `removedTokens`, which is the same
+ * degradation as a fresh LRU miss. This bounds worst-case memory at
+ * `capacity * maxBytesPerEntry` regardless of project file sizes.
+ */
+export declare class PreEditTextCache {
+    private readonly map;
+    readonly capacity: number;
+    readonly maxBytesPerEntry: number;
+    constructor(capacity?: number, maxBytesPerEntry?: number);
+    /** Returns the snapshot for `uri` (or `""` if absent) without touching LRU order. */
+    peek(uri: string): string;
+    /**
+     * Update the snapshot. Move-to-front semantics; oldest is evicted when
+     * capacity is exceeded. Texts exceeding `maxBytesPerEntry` are stored
+     * as empty string (the next edit on this URI gets no `removedTokens`,
+     * matching the LRU-miss degradation path).
+     *
+     * Byte length uses UTF-16 code units (`text.length`), not UTF-8 bytes —
+     * the cap is approximate but stable across machines.
+     */
+    update(uri: string, text: string): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Spec §5.1 — compute the raw `editProximityScore` for a candidate. Pure
+ * function. Returns 0 when the ring is empty (zero events). Output is
+ * un-normalized: the reranker's min-max normalization re-maps the value
+ * across the candidate set so absolute scale doesn't matter — only the
+ * relative ordering does. The same un-normalized value is reported on
+ * the `MetricRecord` for observability.
+ *
+ * `currentUri` / `currentLine` describe the user's cursor at predict
+ * time. The prompt-buffer editor uses a static `"prompt"` URI sentinel
+ * and the current cursor line.
+ */
+export declare function editProximityScore(text: string, index: EditHistoryIndex, currentUri: string, currentLine: number): number;
+/**
+ * Pure character-diff helper. Returns the minimal `{ added, removed }`
+ * slice between two strings by stripping the common prefix + suffix.
+ * Caller is responsible for `containsSensitive` checks before tokenizing
+ * the result. Returns empty strings for both sides when texts are equal.
+ */
+export declare function diffStrings(prev: string, next: string): {
+    added: string;
+    removed: string;
+};
+export declare function readEditHistoryEnv(env?: Record<string, string | undefined>): Required<EditHistoryOpts> & {
+    enabled: boolean;
+};
+//# sourceMappingURL=edit-history-ring.d.ts.map

package/dist/edit-history-ring.d.ts.map

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