@jmtrin/opencode-kevin 0.3.0 → 0.5.0

package/dist/plugin/Feedback.js

@@ -0,0 +1,137 @@
+import { uuidv7 } from "./uuid.js";
+const POSITIVE_VERDICTS = ["useful"];
+const NEGATIVE_VERDICTS = [
+    "wrong",
+    "outdated",
+    "ignore",
+];
+// v0.5.0 — pre-006 DBs lack `memory_feedback`; record() fails loudly with a
+// descriptive error instead of a bare "no such table" (the tool layer turns
+// it into a graceful message).
+const feedbackTableCache = new WeakMap();
+function hasFeedbackTable(store) {
+    const cached = feedbackTableCache.get(store);
+    if (cached !== undefined)
+        return cached;
+    try {
+        store.prepare("SELECT COUNT(*) FROM memory_feedback").get();
+        feedbackTableCache.set(store, true);
+        return true;
+    }
+    catch {
+        feedbackTableCache.set(store, false);
+        return false;
+    }
+}
+export class Feedback {
+    store;
+    metrics;
+    now;
+    constructor(store, metrics, now = () => new Date()) {
+        this.store = store;
+        this.metrics = metrics ?? null;
+        this.now = now;
+    }
+    /**
+     * Records one human verdict and folds it into the memory's counters.
+     * Counters are RECOMPUTED from the table (never incremented) so rows
+     * deleted in tests or by hand cannot drift them.
+     *
+     * The `ignore` verdict also stamps `memories.ignored = 1` (D5-07).
+     * Returns the feedback row id.
+     */
+    record(input) {
+        if (!hasFeedbackTable(this.store)) {
+            throw new Error("kevin_feedback requires migration 006_v05_glassbox.sql (missing table memory_feedback)");
+        }
+        const id = uuidv7();
+        this.store
+            .prepare(`INSERT INTO memory_feedback
+				   (id, memory_id, verdict, session_id, note)
+				 VALUES (?, ?, ?, ?, ?)`)
+            .run(id, input.memoryId, input.verdict, input.sessionId ?? null, input.note ?? null);
+        this.recomputeCounters(input.memoryId);
+        if (input.verdict === "ignore") {
+            this.store
+                .prepare("UPDATE memories SET ignored = 1 WHERE id = ?")
+                .run(input.memoryId);
+        }
+        // v0.5.0 (K5-023 / plan §5.3, D5-06) — lifecycle action of a
+        // negative verdict. `wrong` is an opinion and deserves a second
+        // opinion: it demotes only at feedback_negative >= 2. `outdated`
+        // is a self-verifying claim about the world and acts at once.
+        // `useful` confirms the memory and refreshes its verification.
+        if (input.verdict === "outdated") {
+            this.store
+                .prepare("UPDATE memories SET status = 'stale' WHERE id = ?")
+                .run(input.memoryId);
+        }
+        else if (input.verdict === "wrong") {
+            const counts = this.countsFor(input.memoryId);
+            if (counts.negative >= 2) {
+                this.store
+                    .prepare("UPDATE memories SET status = 'stale' WHERE id = ?")
+                    .run(input.memoryId);
+            }
+        }
+        else if (input.verdict === "useful") {
+            this.store
+                .prepare("UPDATE memories SET last_verified_at = datetime('now') WHERE id = ?")
+                .run(input.memoryId);
+        }
+        if (POSITIVE_VERDICTS.includes(input.verdict)) {
+            this.metrics?.incr("feedback_positive_total", 1);
+        }
+        else if (NEGATIVE_VERDICTS.includes(input.verdict)) {
+            this.metrics?.incr("feedback_negative_total", 1);
+        }
+        return id;
+    }
+    /** Human-judgement counters for one memory (from the row, not the table). */
+    countsFor(memoryId) {
+        const row = this.store
+            .prepare("SELECT feedback_positive, feedback_negative FROM memories WHERE id = ?")
+            .get(memoryId);
+        if (!row)
+            return { positive: 0, negative: 0 };
+        return { positive: row.feedback_positive, negative: row.feedback_negative };
+    }
+    /**
+     * Raw verdict history, newest first. Used by `kevin_feedback` (K5-011)
+     * and by the audit tool (K5-016).
+     */
+    list(memoryId, limit = 50) {
+        const rows = this.store
+            .prepare(`SELECT id, memory_id, verdict, session_id, note, created_at
+				   FROM memory_feedback
+				  ${memoryId ? "WHERE memory_id = ?" : ""}
+				  ORDER BY created_at DESC, rowid DESC
+				  LIMIT ?`)
+            .all(...(memoryId ? [memoryId, limit] : [limit]));
+        return rows.map((r) => ({
+            id: r.id,
+            memoryId: r.memory_id,
+            verdict: r.verdict,
+            sessionId: r.session_id,
+            note: r.note,
+            createdAt: r.created_at,
+        }));
+    }
+    /**
+     * Recompute a memory's positive/negative counters straight from the
+     * verdict table. Kept private — `record` is the only mutation path.
+     */
+    recomputeCounters(memoryId) {
+        this.store
+            .prepare(`UPDATE memories SET
+				   feedback_positive = (
+				     SELECT COUNT(*) FROM memory_feedback
+				      WHERE memory_id = ? AND verdict = 'useful'),
+				   feedback_negative = (
+				     SELECT COUNT(*) FROM memory_feedback
+				      WHERE memory_id = ? AND verdict IN ('wrong','outdated','ignore'))
+				 WHERE id = ?`)
+            .run(memoryId, memoryId, memoryId);
+    }
+}
+//# sourceMappingURL=Feedback.js.map

package/dist/plugin/Feedback.js.map

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

package/dist/plugin/InjectionLedger.d.ts

@@ -0,0 +1,92 @@
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * v0.4.0 InjectionLedger (K4-006/K4-007, plan §5.2, D4-04).
+ *
+ * The measurement half of the closed feedback loop: every lesson injected
+ * into a prompt is recorded in `kevin_injections`, and at `session.idle` the
+ * ledger settles each unmeasured row — if the same fingerprint failed again
+ * after the injection, the lesson is `ineffective`; otherwise `effective`.
+ * `precision_rate = effective / total` is the honest, measured value of the
+ * injection system (replacing Kevin_Token_Impact-style estimates).
+ *
+ * Schema (migration 005_v04_signal.sql):
+ *   kevin_injections(id PK, memory_id, fingerprint, session_id, hook,
+ *                    tokens, injected_at, outcome)
+ *
+ * BUG-015 — a ledger row is only meaningful when its fingerprint can be
+ * matched against failing tool_calls (`COALESCE(error_fingerprint,
+ * fingerprint)`). Memories WITHOUT a fingerprint (agent-saved notes) can
+ * never match, so they are NOT recorded: settle() would otherwise mark
+ * them `effective` forever and inflate `precision_rate`. The caller
+ * (ContextInjector.recordInjections) skips them.
+ */
+export type InjectionHook = "pre_prompt" | "compacting";
+export type InjectionOutcome = "unmeasured" | "effective" | "ineffective" | "inconclusive";
+export interface InjectionRecordInput {
+    memoryId: string;
+    fingerprint: string;
+    sessionId: string;
+    hook: InjectionHook;
+    tokens: number;
+}
+interface InjectionRow {
+    id: string;
+    memory_id: string;
+    fingerprint: string;
+    session_id: string;
+    hook: InjectionHook;
+    tokens: number;
+    injected_at: string;
+    outcome: InjectionOutcome;
+}
+export declare class InjectionLedger {
+    private readonly store;
+    private readonly metrics;
+    constructor(store: Store, metrics?: Metrics | null);
+    /**
+     * Records one injected memory. Idempotent at the row level (UUID PK);
+     * duplicates are expected only via the caller's per-session seen-set.
+     */
+    record(input: InjectionRecordInput): void;
+    /**
+     * Settles every unmeasured injection of the session: a fingerprint that
+     * failed again (as a failing tool_call) after the injection is
+     * `ineffective`, otherwise `effective`. Idempotent — only
+     * `outcome = 'unmeasured'` rows are flipped, and the recurrence charge
+     * is `MAX(recurrence_count, n)` where n = all failing calls of the
+     * fingerprint after `injected_at` (a later idle re-computes n and
+     * catches up — plan §5.1 rule 4: 3 recurrences → stale).
+     *
+     * An ineffective injection also bumps the target memory's
+     * `recurrence_count` (negative evidence, plan §5.3) and stamps
+     * `last_injected_at` (monotonically — an older row can never
+     * regress a newer injection's timestamp; the column means "most
+     * recent injection").
+     */
+    settle(sessionId: string): void;
+    /**
+     * Per-fingerprint failing tool-call counts for the session. Feeds
+     * QualityGate.canInject and the HITL suggestion block.
+     */
+    recurrencesFor(sessionId: string): Map<string, number>;
+    /**
+     * v0.4.0 (K4-017) — recurrence counts for the QualityGate at
+     * injection time: only failing calls that happened AFTER the
+     * fingerprint was already injected this session count. The failure
+     * that *created* a lesson is not a recurrence — it precedes any
+     * injection (plan §5.1 rule 4, same `ts >= injected_at` semantics
+     * `settle` uses).
+     */
+    postInjectionRecurrencesFor(sessionId: string): Map<string, number>;
+    /** Number of rows for the session not yet settled (drives tests and settle). */
+    unsettledForSession(sessionId: string): number;
+    /** Latest ledger rows for a session, newest first (used by tests/tools). */
+    rowsForSession(sessionId: string): InjectionRow[];
+    /**
+     * v0.5.0 (K5-005 / plan §8.4) — one grouped rollup over the whole
+     * ledger, zero-filled for every outcome. Consumed by `kevin_audit`.
+     */
+    outcomeCounts(): Record<InjectionOutcome, number>;
+}
+export {};

package/dist/plugin/InjectionLedger.js

@@ -0,0 +1,243 @@
+import { uuidv7 } from "./uuid.js";
+export class InjectionLedger {
+    store;
+    metrics;
+    constructor(store, metrics) {
+        this.store = store;
+        this.metrics = metrics ?? null;
+    }
+    /**
+     * Records one injected memory. Idempotent at the row level (UUID PK);
+     * duplicates are expected only via the caller's per-session seen-set.
+     */
+    record(input) {
+        this.store
+            .prepare(`INSERT INTO kevin_injections
+				   (id, memory_id, fingerprint, session_id, hook, tokens, outcome)
+				 VALUES (?, ?, ?, ?, ?, ?, 'unmeasured')`)
+            .run(uuidv7(), input.memoryId, input.fingerprint, input.sessionId, input.hook, input.tokens);
+        this.metrics?.incr("injections_total", 1);
+    }
+    /**
+     * Settles every unmeasured injection of the session: a fingerprint that
+     * failed again (as a failing tool_call) after the injection is
+     * `ineffective`, otherwise `effective`. Idempotent — only
+     * `outcome = 'unmeasured'` rows are flipped, and the recurrence charge
+     * is `MAX(recurrence_count, n)` where n = all failing calls of the
+     * fingerprint after `injected_at` (a later idle re-computes n and
+     * catches up — plan §5.1 rule 4: 3 recurrences → stale).
+     *
+     * An ineffective injection also bumps the target memory's
+     * `recurrence_count` (negative evidence, plan §5.3) and stamps
+     * `last_injected_at` (monotonically — an older row can never
+     * regress a newer injection's timestamp; the column means "most
+     * recent injection").
+     */
+    settle(sessionId) {
+        const injections = this.store
+            .prepare(`SELECT id, memory_id, fingerprint, injected_at, outcome
+				   FROM kevin_injections
+				  WHERE session_id = ?
+				  ORDER BY injected_at ASC, id ASC`)
+            .all(sessionId);
+        for (const inj of injections) {
+            // Same identity dimension CausalChain uses: the failing call's
+            // `error_fingerprint` (stamped by Reflector) or the legacy
+            // `fingerprint` hash. `ts` and `injected_at` are both
+            // `datetime('now')` text → lexicographic comparison is valid.
+            // COUNT (not LIMIT 1): every failing call after the injection
+            // is a recurrence — the charge must reach 3 so D4-06 expels
+            // the lesson.
+            //
+            // BUG-003 — the exemption is now bounded to the lesson's OWN
+            // creating call (memories.metadata.origin_call_id, stamped by
+            // Reflector). The old code excluded the session's FIRST failing
+            // call of the fingerprint, which is only the creating call when
+            // the lesson was born in THIS session; a lesson created in an
+            // earlier session had its first in-session failure (a genuine
+            // post-injection recurrence) wrongly exempted, inflating
+            // precision. Memories without a tracked creating call (agent-
+            // saved, test fixtures) get no exemption: only the `ts >=
+            // injected_at` bound applies.
+            const originCallId = readOriginCallId(this.store, inj.memory_id);
+            const countRow = this.store
+                .prepare(`SELECT COUNT(*) AS n FROM tool_calls
+					  WHERE session_id = ?
+					    AND success = 0
+					    AND COALESCE(error_fingerprint, fingerprint) = ?
+					    AND ts >= ?
+					    AND (? IS NULL OR id != ?)
+					 LIMIT 1`)
+                .get(sessionId, inj.fingerprint, inj.injected_at, originCallId, originCallId);
+            const n = countRow.n;
+            // v0.5.0 (K5-005 / plan §5.1, D5-01) — three-way settlement:
+            //   recurrences >= 1 → ineffective  (existing side effects unchanged)
+            //   else fixes >= 1  → effective    (a linked fix was OBSERVED)
+            //   else             → inconclusive (new majority bucket; excluded
+            //                                    from the precision denominator)
+            if (n >= 1) {
+                if (inj.outcome === "unmeasured") {
+                    this.store
+                        .prepare(`UPDATE kevin_injections SET outcome = 'ineffective'
+							  WHERE id = ?`)
+                        .run(inj.id);
+                    this.metrics?.incr("injections_ineffective", 1);
+                }
+                this.store
+                    .prepare(`UPDATE memories
+						    SET recurrence_count = MAX(recurrence_count, ?),
+						        last_injected_at = CASE
+						          WHEN last_injected_at IS NULL
+						            OR ? > last_injected_at
+						            THEN ? ELSE last_injected_at END
+						  WHERE fingerprint = ? AND id = ?`)
+                    .run(countRow.n, inj.injected_at, inj.injected_at, inj.fingerprint, inj.memory_id);
+                // v0.4.0 (K4-025 / plan §5.1 rule 4, D4-06) — recurrence
+                // expels: a fingerprint at `recurrence_count >= 3` is
+                // demoted to `status='stale'` and never injected again
+                // (only a new causal pattern — from a linked fix —
+                // re-admits the lesson, not the stale error row).
+                this.store
+                    .prepare(`UPDATE memories SET status = 'stale'
+						  WHERE id = ? AND recurrence_count >= 3`)
+                    .run(inj.memory_id);
+            }
+            else if (inj.outcome === "unmeasured") {
+                // Mirror of the recurrence predicate with the success flag
+                // inverted and the fingerprint matched on
+                // `fix_for_fingerprint` (populated by CausalChain.onSuccess,
+                // indexed by idx_tool_calls_fix_fp since migration 004). The
+                // `ts >= injected_at` bound and `session_id = ?` filter are
+                // kept; there is no `origin_call_id` exemption for fixes —
+                // a fix is not the creating call.
+                const fixRow = this.store
+                    .prepare(`SELECT COUNT(*) AS m FROM tool_calls
+						  WHERE session_id = ?
+						    AND success = 1
+						    AND fix_for_fingerprint = ?
+						    AND ts >= ?
+						 LIMIT 1`)
+                    .get(sessionId, inj.fingerprint, inj.injected_at);
+                if (fixRow.m >= 1) {
+                    this.store
+                        .prepare(`UPDATE kevin_injections SET outcome = 'effective'
+							  WHERE id = ?`)
+                        .run(inj.id);
+                    this.metrics?.incr("injections_effective", 1);
+                }
+                else {
+                    this.store
+                        .prepare(`UPDATE kevin_injections SET outcome = 'inconclusive'
+							  WHERE id = ?`)
+                        .run(inj.id);
+                    this.metrics?.incr("injections_inconclusive", 1);
+                }
+            }
+        }
+    }
+    /**
+     * Per-fingerprint failing tool-call counts for the session. Feeds
+     * QualityGate.canInject and the HITL suggestion block.
+     */
+    recurrencesFor(sessionId) {
+        const rows = this.store
+            .prepare(`SELECT COALESCE(error_fingerprint, fingerprint) AS fp
+				   FROM tool_calls
+				  WHERE session_id = ? AND success = 0
+				    AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)`)
+            .all(sessionId);
+        const out = new Map();
+        for (const r of rows) {
+            if (!r.fp)
+                continue;
+            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
+        }
+        return out;
+    }
+    /**
+     * v0.4.0 (K4-017) — recurrence counts for the QualityGate at
+     * injection time: only failing calls that happened AFTER the
+     * fingerprint was already injected this session count. The failure
+     * that *created* a lesson is not a recurrence — it precedes any
+     * injection (plan §5.1 rule 4, same `ts >= injected_at` semantics
+     * `settle` uses).
+     */
+    postInjectionRecurrencesFor(sessionId) {
+        const rows = this.store
+            .prepare(`SELECT COALESCE(t.error_fingerprint, t.fingerprint) AS fp
+				   FROM tool_calls t
+				  WHERE t.session_id = ? AND t.success = 0
+				    AND (t.error_fingerprint IS NOT NULL OR t.fingerprint IS NOT NULL)
+				    AND t.ts >= COALESCE(
+				          (SELECT MAX(injected_at) FROM kevin_injections
+				            WHERE session_id = t.session_id
+				              AND fingerprint = COALESCE(t.error_fingerprint, t.fingerprint)),
+				          '9999-12-31')`)
+            .all(sessionId);
+        const out = new Map();
+        for (const r of rows) {
+            if (!r.fp)
+                continue;
+            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
+        }
+        return out;
+    }
+    /** Number of rows for the session not yet settled (drives tests and settle). */
+    unsettledForSession(sessionId) {
+        const row = this.store
+            .prepare(`SELECT COUNT(*) AS n FROM kevin_injections
+				  WHERE session_id = ? AND outcome = 'unmeasured'`)
+            .get(sessionId);
+        return row.n;
+    }
+    /** Latest ledger rows for a session, newest first (used by tests/tools). */
+    rowsForSession(sessionId) {
+        return this.store
+            .prepare(`SELECT id, memory_id, fingerprint, session_id, hook, tokens,
+				        injected_at, outcome
+				   FROM kevin_injections
+				  WHERE session_id = ?
+				  ORDER BY injected_at ASC, id ASC`)
+            .all(sessionId);
+    }
+    /**
+     * v0.5.0 (K5-005 / plan §8.4) — one grouped rollup over the whole
+     * ledger, zero-filled for every outcome. Consumed by `kevin_audit`.
+     */
+    outcomeCounts() {
+        const rows = this.store
+            .prepare("SELECT outcome, COUNT(*) AS n FROM kevin_injections GROUP BY outcome")
+            .all();
+        const out = {
+            unmeasured: 0,
+            effective: 0,
+            ineffective: 0,
+            inconclusive: 0,
+        };
+        for (const r of rows) {
+            out[r.outcome] = r.n;
+        }
+        return out;
+    }
+}
+/**
+ * BUG-003 — read `origin_call_id` (the failing tool_call that CREATED the
+ * memory) from memories.metadata, mirroring the feedback loop's
+ * `readOriginCallId` in MemoryService. Returns null when absent/malformed.
+ */
+function readOriginCallId(store, memoryId) {
+    const row = store
+        .prepare("SELECT metadata FROM memories WHERE id = ?")
+        .get(memoryId);
+    if (!row?.metadata)
+        return null;
+    try {
+        const parsed = JSON.parse(row.metadata);
+        const id = parsed?.origin_call_id;
+        return typeof id === "string" && id.length > 0 ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=InjectionLedger.js.map

package/dist/plugin/InjectionLedger.js.map

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

package/dist/plugin/LessonFixer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
+ *
+ * Zero-cost "Fixed by:" raw material from local data: when CausalChain
+ * links a success to a failing fingerprint, the linked tool_call's
+ * `args_summary` becomes a deterministic fix string stored in
+ * `memories.fix_args`. The default promotion path is pure local data —
+ * no LLM calls (principle 14).
+ */
+/** Max length of the `args_summary` embedded in a fix_args string. */
+export declare const FIX_ARGS_TRUNCATE = 120;
+export interface LinkedToolCall {
+    tool: string;
+    args_summary: string | null;
+}
+/**
+ * `"bash" with args "npm i -g rg"` style. Returns null when the linked
+ * call carries no args_summary (nothing to say).
+ */
+export declare function extractFixArgs(call: LinkedToolCall): string | null;
+export interface EnrichInput {
+    lesson: string;
+    fixArgs: string | null;
+    originalError: string | null;
+}
+/**
+ * Opt-in LLM phrasing hook (K4-015): receives the lesson, the
+ * deterministic fix_args and the original error; returns a one-line
+ * `Fix:` phrasing, or null to fall back to the deterministic text.
+ * May be async; never runs on the failure hot path.
+ */
+export type EnrichFn = (input: EnrichInput) => Promise<string | null>;
+export interface PatternLike {
+    content: string;
+    fixArgs: string | null;
+}
+/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
+export declare function deterministicFixLine(pattern: PatternLike): string;
+/**
+ * Promotion-time fix phrasing. Default path returns the deterministic
+ * `Fixed by: {fix_args}` line (or "" when there is none). When an
+ * `enrichFn` is supplied and returns a phrase, that phrase wins.
+ */
+export declare function enrichAtPromotion(pattern: PatternLike, enrichFn?: EnrichFn): Promise<string>;

package/dist/plugin/LessonFixer.js

@@ -0,0 +1,46 @@
+/**
+ * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
+ *
+ * Zero-cost "Fixed by:" raw material from local data: when CausalChain
+ * links a success to a failing fingerprint, the linked tool_call's
+ * `args_summary` becomes a deterministic fix string stored in
+ * `memories.fix_args`. The default promotion path is pure local data —
+ * no LLM calls (principle 14).
+ */
+/** Max length of the `args_summary` embedded in a fix_args string. */
+export const FIX_ARGS_TRUNCATE = 120;
+/**
+ * `"bash" with args "npm i -g rg"` style. Returns null when the linked
+ * call carries no args_summary (nothing to say).
+ */
+export function extractFixArgs(call) {
+    const raw = call.args_summary?.trim();
+    if (!raw)
+        return null;
+    const truncated = raw.length > FIX_ARGS_TRUNCATE
+        ? `${raw.slice(0, FIX_ARGS_TRUNCATE)}…`
+        : raw;
+    return `${call.tool} with args "${truncated}"`;
+}
+/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
+export function deterministicFixLine(pattern) {
+    return pattern.fixArgs ? `Fixed by: ${pattern.fixArgs}` : "";
+}
+/**
+ * Promotion-time fix phrasing. Default path returns the deterministic
+ * `Fixed by: {fix_args}` line (or "" when there is none). When an
+ * `enrichFn` is supplied and returns a phrase, that phrase wins.
+ */
+export async function enrichAtPromotion(pattern, enrichFn) {
+    if (enrichFn) {
+        const phrased = await enrichFn({
+            lesson: pattern.content,
+            fixArgs: pattern.fixArgs,
+            originalError: null,
+        });
+        if (phrased)
+            return phrased;
+    }
+    return deterministicFixLine(pattern);
+}
+//# sourceMappingURL=LessonFixer.js.map

package/dist/plugin/LessonFixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LessonFixer.js","sourceRoot":"","sources":["../../plugin/LessonFixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAOrC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAoB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,SAAS,GACd,GAAG,CAAC,MAAM,GAAG,iBAAiB;QAC7B,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG;QACvC,CAAC,CAAC,GAAG,CAAC;IACR,OAAO,GAAG,IAAI,CAAC,IAAI,eAAe,SAAS,GAAG,CAAC;AAChD,CAAC;AAqBD,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,OAAoB;IACxD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,OAAoB,EACpB,QAAmB;IAEnB,IAAI,QAAQ,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC;YAC9B,MAAM,EAAE,OAAO,CAAC,OAAO;YACvB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,aAAa,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAC7B,CAAC;IACD,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}