knodin 0.5.0

package/dist/src/graph-query-health.js

@@ -0,0 +1,115 @@
+function hasNonReconciliableDamage(graph) {
+    if (Object.values(graph.orphaned).some((count) => count > 0))
+        return true;
+    const lifecycleIssues = new Set(graph.lifecycle?.issues ?? []);
+    const reconcilablePrefixes = [
+        "indexed file no longer exists: ",
+        "indexed file is no longer eligible: ",
+        "indexed snapshot differs from disk: ",
+    ];
+    return graph.missing.records.some((record) => !lifecycleIssues.has(record) &&
+        !reconcilablePrefixes.some((prefix) => record.startsWith(prefix)));
+}
+function unavailableState(graph) {
+    if (graph.freshness?.state === "queued")
+        return "queued";
+    if (graph.freshness?.state === "indexing")
+        return "indexing";
+    if (graph.status === "indexing")
+        return "indexing";
+    if (graph.schemaVersion === 0)
+        return graph.coverage.sourceFiles === 0 ? "empty-repository" : "not-initialized";
+    if (graph.coverage.sourceFiles === 0)
+        return "empty-repository";
+    if (graph.coverage.indexedFiles === 0)
+        return "empty-index";
+    if (graph.status === "repair-needed" && hasNonReconciliableDamage(graph))
+        return "repair-needed";
+    return null;
+}
+export async function inspectGraphQueryHealth(repo, status) {
+    try {
+        const graph = await status(repo);
+        const state = unavailableState(graph);
+        if (!state)
+            return {
+                available: true,
+                state: graph.lifecycle && graph.lifecycle.status !== "healthy"
+                    ? "lifecycle-degraded"
+                    : "healthy",
+                graph,
+            };
+        return {
+            available: false,
+            status: "unavailable",
+            state,
+            graph,
+            remediation: graph.repairSteps,
+        };
+    }
+    catch (error) {
+        return {
+            available: false,
+            status: "unavailable",
+            state: "unknown",
+            remediation: ["Run `knodin doctor` and `knodin status --deep`."],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function hasNoMatches(value) {
+    if (Array.isArray(value.results))
+        return value.results.length === 0;
+    if (typeof value.count === "number")
+        return value.count === 0;
+    if (typeof value.changedFileCount === "number")
+        return value.changedFileCount === 0;
+    if (typeof value.summary === "string" && /\bnot found\b/i.test(value.summary))
+        return true;
+    if (typeof value.refused === "string" &&
+        /\b(?:not found|no edit sites|no matches)\b/i.test(value.refused))
+        return true;
+    return false;
+}
+/** Add an explicit healthy/no-match outcome without replacing operation data. */
+export function decorateGraphQueryResult(value, graphState = "healthy", freshness) {
+    if (value === null || value === undefined) {
+        return {
+            status: "no-match",
+            result: value ?? null,
+            ...(freshness ? { freshness } : {}),
+            availability: { state: "no-match", graphState, outcome: "no-match" },
+        };
+    }
+    if (Array.isArray(value)) {
+        return {
+            status: value.length === 0 ? "no-match" : "ok",
+            results: value,
+            ...(freshness ? { freshness } : {}),
+            availability: {
+                state: value.length === 0 ? "no-match" : graphState,
+                graphState,
+                outcome: value.length === 0 ? "no-match" : "matches",
+            },
+        };
+    }
+    if (typeof value !== "object") {
+        return {
+            result: value,
+            ...(freshness ? { freshness } : {}),
+            availability: { state: graphState, outcome: "complete" },
+        };
+    }
+    const root = value;
+    const noMatch = hasNoMatches(root) && root.ambiguity === undefined;
+    return {
+        ...root,
+        ...(freshness ? { freshness } : {}),
+        ...(noMatch && root.status === undefined ? { status: "no-match" } : {}),
+        availability: {
+            state: noMatch ? "no-match" : graphState,
+            graphState,
+            outcome: noMatch ? "no-match" : "matches",
+        },
+    };
+}

package/dist/src/index-activity.js

@@ -0,0 +1,125 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+function activityPath(repo) {
+    return path.join(path.resolve(repo), ".reckon", "index-activity.json");
+}
+const ACTIVITY_CLOCK_SKEW_MS = 2_000;
+const MAX_ACTIVITY_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+const INDEX_PHASES = new Set([
+    "starting",
+    "collecting-files",
+    "indexing-files",
+    "embedding-model",
+    "embedding-symbols",
+    "finalizing",
+    "verifying",
+    "completed",
+]);
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function processStartedAt(pid) {
+    if (pid === process.pid)
+        return Date.now() - process.uptime() * 1_000;
+    if (process.platform === "win32")
+        return null;
+    try {
+        const output = child_process.execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const startedAt = Date.parse(output.trim());
+        return Number.isFinite(startedAt) ? startedAt : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Cross-process, source-safe status for a currently running index operation. */
+export function createIndexActivityReporter(repo) {
+    const target = activityPath(repo);
+    const startedAt = new Date().toISOString();
+    const write = (activity) => {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        const temporary = `${target}.${process.pid}.tmp`;
+        try {
+            fs.writeFileSync(temporary, `${JSON.stringify(activity)}\n`, "utf8");
+            fs.renameSync(temporary, target);
+        }
+        finally {
+            fs.rmSync(temporary, { force: true });
+        }
+    };
+    return {
+        start() {
+            write({
+                pid: process.pid,
+                startedAt,
+                updatedAt: startedAt,
+                phase: "starting",
+                phaseCompleted: 0,
+                message: "Opening local graph database",
+            });
+        },
+        update(event) {
+            write({
+                pid: process.pid,
+                startedAt,
+                updatedAt: new Date().toISOString(),
+                phase: event.phase,
+                phaseCompleted: event.phaseCompleted,
+                ...(event.phaseTotal === undefined ? {} : { phaseTotal: event.phaseTotal }),
+                message: event.message,
+            });
+        },
+        stop() {
+            try {
+                const current = JSON.parse(fs.readFileSync(target, "utf8"));
+                if (current.pid === process.pid)
+                    fs.unlinkSync(target);
+            }
+            catch { }
+        },
+    };
+}
+/** Return only a live operation; crash-left activity files never claim freshness. */
+export function readIndexActivity(repo) {
+    try {
+        const activity = JSON.parse(fs.readFileSync(activityPath(repo), "utf8"));
+        if (!Number.isInteger(activity.pid) || activity.pid <= 0 || !processIsAlive(activity.pid))
+            return null;
+        const now = Date.now();
+        const startedAt = Date.parse(activity.startedAt);
+        const updatedAt = Date.parse(activity.updatedAt);
+        if (!Number.isFinite(startedAt) ||
+            !Number.isFinite(updatedAt) ||
+            startedAt > now + ACTIVITY_CLOCK_SKEW_MS ||
+            updatedAt < startedAt ||
+            updatedAt > now + ACTIVITY_CLOCK_SKEW_MS ||
+            now - startedAt > MAX_ACTIVITY_AGE_MS ||
+            !INDEX_PHASES.has(activity.phase) ||
+            !Number.isFinite(activity.phaseCompleted) ||
+            activity.phaseCompleted < 0 ||
+            (activity.phaseTotal !== undefined &&
+                (!Number.isFinite(activity.phaseTotal) ||
+                    activity.phaseTotal < 0 ||
+                    activity.phaseCompleted > activity.phaseTotal)) ||
+            typeof activity.message !== "string") {
+            return null;
+        }
+        const processStart = processStartedAt(activity.pid);
+        if (processStart !== null && processStart > startedAt + ACTIVITY_CLOCK_SKEW_MS)
+            return null;
+        return activity;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/init-progress-worker.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { clearLine as clearTerminalLine, moveCursor as moveTerminalCursor, cursorTo as moveTerminalCursorTo, } from "node:readline";
+import ora from "ora";
+import { formatProgress, normalizeTerminalDimension, } from "./init-progress.js";
+const terminalEnabled = process.stderr.isTTY === true || process.env.RECKON_FORCE_PROGRESS_TTY === "1";
+// Ora divides rendered text width by `stream.columns`. Some pseudo-terminals
+// report zero columns, which turns its clear loop into an infinite loop. Keep
+// the real terminal methods while guaranteeing finite viewport dimensions.
+const progressStream = {
+    isTTY: terminalEnabled,
+    columns: normalizeTerminalDimension(process.stderr.columns, 80),
+    rows: normalizeTerminalDimension(process.stderr.rows, 24),
+    write: process.stderr.write.bind(process.stderr),
+    cursorTo: (x, y, callback) => moveTerminalCursorTo(process.stderr, x, y, callback),
+    moveCursor: (dx, dy, callback) => moveTerminalCursor(process.stderr, dx, dy, callback),
+    clearLine: (direction, callback) => clearTerminalLine(process.stderr, direction, callback),
+    once: process.stderr.once.bind(process.stderr),
+    removeListener: process.stderr.removeListener.bind(process.stderr),
+};
+const spinner = ora({
+    text: "[init:starting] Opening local graph database (0s elapsed)",
+    stream: progressStream,
+    isEnabled: terminalEnabled,
+    discardStdin: false,
+});
+let buffer = "";
+let stopped = false;
+let exiting = false;
+let startedAt = 0;
+let operation = "init";
+let current = "[init:starting] Opening local graph database";
+let clock;
+function refreshText() {
+    const elapsed = Math.max(0, Math.floor((Date.now() - startedAt) / 1_000));
+    spinner.text = `${current} (${elapsed}s elapsed)`;
+}
+function start(nextOperation = operation) {
+    if (spinner.isSpinning)
+        return;
+    operation = nextOperation;
+    current = `[${operation}:starting] Opening local graph database`;
+    startedAt = Date.now();
+    refreshText();
+    spinner.start();
+    clock = setInterval(refreshText, 250);
+}
+function stop(exitAfter = false) {
+    if (!stopped) {
+        stopped = true;
+        if (clock)
+            clearInterval(clock);
+        spinner.stop();
+    }
+    if (exitAfter && !exiting) {
+        exiting = true;
+        const exitTimer = setTimeout(() => process.exit(0), 100);
+        process.stderr.write("\r\x1b[2K", () => {
+            clearTimeout(exitTimer);
+            process.exit(0);
+        });
+    }
+}
+function handle(line) {
+    if (!line)
+        return;
+    const message = JSON.parse(line);
+    if (message.type === "start")
+        start(message.operation);
+    else if (message.type === "progress") {
+        if (!spinner.isSpinning)
+            start();
+        current = formatProgress(message.event, undefined, operation);
+        refreshText();
+    }
+    else
+        stop(true);
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    for (;;) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0)
+            break;
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        try {
+            handle(line);
+        }
+        catch {
+            // Progress transport is observational; malformed input cannot affect init.
+        }
+    }
+});
+process.stdin.on("end", () => {
+    if (buffer) {
+        try {
+            handle(buffer);
+        }
+        catch { }
+    }
+    stop(true);
+});
+process.on("SIGTERM", () => {
+    stop();
+    process.exit(0);
+});

package/dist/src/init-progress.js

@@ -0,0 +1,155 @@
+const HEARTBEAT_MS = 15_000;
+const TTY_THROTTLE_MS = 100;
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CLEAR_TTY_LINE = "\r\x1b[2K";
+export function normalizeTerminalDimension(value, fallback) {
+    return Number.isFinite(value) && (value ?? 0) > 0 ? Math.floor(value) : fallback;
+}
+function formatCount(value) {
+    return value.toLocaleString();
+}
+function formatBytes(value) {
+    if (value < 1024 * 1024)
+        return `${Math.round(value / 1024)} KB`;
+    return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatDuration(seconds) {
+    if (seconds < 1)
+        return "<1s";
+    if (seconds < 60)
+        return `${Math.ceil(seconds)}s`;
+    return `${Math.floor(seconds / 60)}m ${Math.ceil(seconds % 60)}s`;
+}
+export function formatProgress(event, ratePerSecond, operation = "init") {
+    const model = event.modelFile ? ` (${event.modelFile})` : "";
+    const total = event.phaseTotal;
+    if (total === undefined)
+        return `[${operation}:${event.phase}] ${event.message}${model}`;
+    const counter = event.phase === "embedding-model"
+        ? `${formatBytes(event.phaseCompleted)} / ${formatBytes(total)}`
+        : `${formatCount(event.phaseCompleted)} / ${formatCount(total)}`;
+    const percent = total > 0 ? ` (${Math.floor((event.phaseCompleted / total) * 100)}%)` : "";
+    const eta = ratePerSecond && total > event.phaseCompleted
+        ? ` • ~${formatDuration((total - event.phaseCompleted) / ratePerSecond)} remaining`
+        : "";
+    const rate = ratePerSecond && event.phase !== "embedding-model"
+        ? ` • ${ratePerSecond.toFixed(ratePerSecond >= 10 ? 0 : 1)}/s`
+        : "";
+    return `[${operation}:${event.phase}] ${counter}${percent} ${event.message}${model}${rate}${eta}`;
+}
+/**
+ * Human-only init feedback. It writes to stderr, leaving stdout stable for the
+ * final result, redraws a TTY at most 10 times/sec, and heartbeats a quiet phase.
+ */
+export function createInitProgressRenderer(options) {
+    const operation = options.operation ?? "init";
+    const now = options.now ?? Date.now;
+    const schedule = options.setTimeout ??
+        ((callback, intervalMs) => setTimeout(callback, intervalMs));
+    const unschedule = options.clearTimeout ?? ((handle) => clearTimeout(handle));
+    const tty = options.stderr.isTTY === true;
+    let started = false;
+    let stopped = false;
+    let hasTtyLine = false;
+    let startedAt = 0;
+    let heartbeat;
+    let spinner;
+    let spinnerFrame = 0;
+    let displayLine = `[${operation}:starting] Opening local graph database`;
+    let lastWriteAt = Number.NEGATIVE_INFINITY;
+    let lastPhase = "starting";
+    let lastPercentBucket = -1;
+    let phaseStartedElapsedMs = 0;
+    let phaseStartedCompleted = 0;
+    const scheduleHeartbeat = () => {
+        if (heartbeat !== undefined || stopped)
+            return;
+        heartbeat = schedule(() => {
+            heartbeat = undefined;
+            if (stopped)
+                return;
+            write(`${displayLine} (still working; ${Math.floor((now() - startedAt) / 1000)}s elapsed)`, false);
+            scheduleHeartbeat();
+        }, HEARTBEAT_MS);
+        if (typeof heartbeat === "object" && heartbeat !== null && "unref" in heartbeat) {
+            heartbeat.unref();
+        }
+    };
+    const scheduleSpinner = () => {
+        if (!tty || spinner !== undefined || stopped)
+            return;
+        spinner = schedule(() => {
+            spinner = undefined;
+            if (stopped)
+                return;
+            spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
+            options.stderr.write(`${CLEAR_TTY_LINE}${SPINNER_FRAMES[spinnerFrame]} ${displayLine} (${Math.floor((now() - startedAt) / 1000)}s elapsed)`);
+            hasTtyLine = true;
+            scheduleSpinner();
+        }, TTY_THROTTLE_MS);
+        if (typeof spinner === "object" && spinner !== null && "unref" in spinner) {
+            spinner.unref();
+        }
+    };
+    const write = (line, updateDisplay = true) => {
+        if (updateDisplay)
+            displayLine = line;
+        if (tty) {
+            options.stderr.write(`${CLEAR_TTY_LINE}${SPINNER_FRAMES[spinnerFrame]} ${line} (${Math.floor((now() - startedAt) / 1000)}s elapsed)`);
+            hasTtyLine = true;
+        }
+        else {
+            options.stderr.write(`${line}\n`);
+        }
+        lastWriteAt = now();
+        scheduleHeartbeat();
+    };
+    return {
+        start() {
+            if (started || stopped)
+                return;
+            started = true;
+            startedAt = now();
+            scheduleSpinner();
+            write(displayLine);
+        },
+        onProgress(event) {
+            if (stopped)
+                return;
+            if (!started)
+                this.start();
+            const percentage = event.phaseTotal && event.phaseTotal > 0
+                ? Math.floor((event.phaseCompleted / event.phaseTotal) * 100)
+                : undefined;
+            const bucket = percentage === undefined ? -1 : Math.floor(percentage / 5);
+            const phaseChanged = event.phase !== lastPhase;
+            if (phaseChanged) {
+                phaseStartedElapsedMs = event.elapsedMs;
+                phaseStartedCompleted = event.phaseCompleted;
+            }
+            const phaseElapsedSeconds = Math.max(0, event.elapsedMs - phaseStartedElapsedMs) / 1_000;
+            const ratePerSecond = phaseElapsedSeconds > 0 && event.phaseCompleted > phaseStartedCompleted
+                ? (event.phaseCompleted - phaseStartedCompleted) / phaseElapsedSeconds
+                : undefined;
+            const completed = event.phaseTotal !== undefined && event.phaseCompleted >= event.phaseTotal;
+            if (tty && !phaseChanged && !completed && now() - lastWriteAt < TTY_THROTTLE_MS)
+                return;
+            if (!tty && !phaseChanged && bucket <= lastPercentBucket && !completed)
+                return;
+            write(formatProgress(event, ratePerSecond, operation));
+            lastPhase = event.phase;
+            lastPercentBucket = Math.max(lastPercentBucket, bucket);
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (heartbeat !== undefined)
+                unschedule(heartbeat);
+            if (spinner !== undefined)
+                unschedule(spinner);
+            if (tty && hasTtyLine)
+                options.stderr.write(`${CLEAR_TTY_LINE}\n`);
+        },
+    };
+}