@lapis-notes/graph 0.1.0

package/dist/graph-controls-overlay.svelte.d.ts

@@ -0,0 +1,30 @@
+import { type App } from "@lapis-notes/api";
+import { type SearchFilterSyntax } from "@lapismd/design-core/filter";
+import type { GraphNodePreview } from "./graph-renderer";
+import type { GraphSettings, GraphSettingsPatch } from "./graph-types";
+type $$ComponentProps = {
+    app: App;
+    isLocal: boolean;
+    settings: GraphSettings;
+    statsText: string;
+    statusText: string;
+    statusKind: "loading" | "error" | null;
+    groupDiagnostics: Readonly<Record<string, string>>;
+    filterDiagnostic: string | null;
+    filterSyntax: SearchFilterSyntax;
+    preview: GraphNodePreview | null;
+    isAnimating: boolean;
+    onFocusActiveFile: () => void;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onResetView: () => void;
+    onRefreshGraph: () => void;
+    onResetDefaults: () => void;
+    onToggleAnimation: () => void;
+    onSettingsPatch: (patch: GraphSettingsPatch) => void;
+    onOpenPreviewFile: (preview: GraphNodePreview, event: MouseEvent) => void;
+    onDismissPreview: () => void;
+};
+declare const GraphControlsOverlay: import("svelte").Component<$$ComponentProps, {}, "">;
+type GraphControlsOverlay = ReturnType<typeof GraphControlsOverlay>;
+export default GraphControlsOverlay;

package/dist/graph-data-coordinator.d.ts

@@ -0,0 +1,41 @@
+import type { App } from "@lapis-notes/api";
+import { type GraphBuildProgress } from "./graph-data";
+import type { GraphData } from "./graph-types";
+export type GraphCoordinatorStatus = "idle" | "loading" | "updating" | "ready" | "error";
+export type GraphSnapshotOutcome = "none" | "hit" | "stale" | "corrupt";
+export interface GraphCoordinatorState {
+    version: number;
+    graph: GraphData | null;
+    status: GraphCoordinatorStatus;
+    progress: GraphBuildProgress | null;
+    error: string | null;
+    snapshotOutcome: GraphSnapshotOutcome;
+    completedAt: number | null;
+}
+type GraphCoordinatorApp = Pick<App, "appDatabase" | "metadataCache" | "telemetry" | "vault" | "workspace">;
+export declare function cloneGraphData(graph: GraphData): GraphData;
+export declare class GraphDataCoordinator {
+    private readonly app;
+    private readonly listeners;
+    private state;
+    private startPromise;
+    private runPromise;
+    private pending;
+    private pendingForce;
+    private disposed;
+    private abortController;
+    private currentFingerprint;
+    constructor(app: GraphCoordinatorApp);
+    subscribe(listener: (state: GraphCoordinatorState) => void): () => void;
+    getState(): GraphCoordinatorState;
+    start(): Promise<void>;
+    requestRefresh(_reason?: string, force?: boolean): Promise<void>;
+    dispose(): void;
+    private performStart;
+    private runQueue;
+    private buildOnce;
+    private handleFailure;
+    private updateState;
+}
+export declare const GRAPH_CANONICAL_SNAPSHOT_KEY = "graph.canonical-snapshot.v1";
+export {};

package/dist/graph-data-coordinator.js

@@ -0,0 +1,265 @@
+import { buildCanonicalGraph, } from "./graph-data";
+const GRAPH_SNAPSHOT_KEY = "graph.canonical-snapshot.v1";
+const GRAPH_SNAPSHOT_VERSION = 1;
+function cloneNode(node) {
+    return {
+        ...node,
+        tags: [...node.tags],
+        groupIds: [...node.groupIds],
+    };
+}
+function cloneLink(link) {
+    return { ...link };
+}
+export function cloneGraphData(graph) {
+    return {
+        nodes: graph.nodes.map(cloneNode),
+        links: graph.links.map(cloneLink),
+        centerNodeId: graph.centerNodeId ?? null,
+    };
+}
+function isGraphData(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (Array.isArray(candidate.nodes) &&
+        candidate.nodes.every((node) => node &&
+            typeof node === "object" &&
+            typeof node.id === "string" &&
+            typeof node.label === "string" &&
+            Array.isArray(node.tags) &&
+            Array.isArray(node.groupIds)) &&
+        Array.isArray(candidate.links) &&
+        candidate.links.every((link) => link &&
+            typeof link === "object" &&
+            typeof link.id === "string" &&
+            typeof link.source === "string" &&
+            typeof link.target === "string"));
+}
+function parseSnapshot(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const candidate = value;
+    if (candidate.version !== GRAPH_SNAPSHOT_VERSION ||
+        typeof candidate.completedAt !== "number" ||
+        typeof candidate.metadataFingerprint !== "string" ||
+        !isGraphData(candidate.graph)) {
+        return null;
+    }
+    return {
+        version: GRAPH_SNAPSHOT_VERSION,
+        completedAt: candidate.completedAt,
+        metadataFingerprint: candidate.metadataFingerprint,
+        graph: cloneGraphData(candidate.graph),
+    };
+}
+function isCancellation(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+export class GraphDataCoordinator {
+    app;
+    listeners = new Set();
+    state = {
+        version: 0,
+        graph: null,
+        status: "idle",
+        progress: null,
+        error: null,
+        snapshotOutcome: "none",
+        completedAt: null,
+    };
+    startPromise = null;
+    runPromise = null;
+    pending = false;
+    pendingForce = false;
+    disposed = false;
+    abortController = null;
+    currentFingerprint = null;
+    constructor(app) {
+        this.app = app;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.getState());
+        return () => this.listeners.delete(listener);
+    }
+    getState() {
+        return {
+            ...this.state,
+            graph: this.state.graph ? cloneGraphData(this.state.graph) : null,
+            progress: this.state.progress ? { ...this.state.progress } : null,
+        };
+    }
+    start() {
+        this.startPromise ??= this.performStart();
+        return this.startPromise;
+    }
+    requestRefresh(_reason = "refresh", force = false) {
+        if (this.disposed)
+            return Promise.resolve();
+        this.pending = true;
+        this.pendingForce ||= force;
+        this.runPromise ??= this.runQueue().finally(() => {
+            this.runPromise = null;
+        });
+        return this.runPromise;
+    }
+    dispose() {
+        this.disposed = true;
+        this.pending = false;
+        this.pendingForce = false;
+        this.abortController?.abort();
+        this.abortController = null;
+        this.listeners.clear();
+    }
+    async performStart() {
+        try {
+            await this.app.appDatabase.open();
+            if (this.disposed)
+                return;
+            const stored = await this.app.appDatabase.getMeta(GRAPH_SNAPSHOT_KEY);
+            const snapshot = parseSnapshot(stored);
+            const fingerprint = this.app.metadataCache.getReconciliationFingerprint();
+            if (snapshot) {
+                const matching = snapshot.metadataFingerprint === fingerprint;
+                this.currentFingerprint = snapshot.metadataFingerprint;
+                this.updateState({
+                    graph: snapshot.graph,
+                    status: matching ? "ready" : "updating",
+                    progress: null,
+                    error: null,
+                    snapshotOutcome: matching ? "hit" : "stale",
+                    completedAt: snapshot.completedAt,
+                });
+                this.app.telemetry.recordEvent("graph.snapshot", {
+                    outcome: matching ? "hit" : "stale",
+                    "graph.node.count": snapshot.graph.nodes.length,
+                    "graph.link.count": snapshot.graph.links.length,
+                });
+                if (matching)
+                    return;
+            }
+            else {
+                const outcome = stored === undefined ? "none" : "corrupt";
+                this.updateState({
+                    status: "loading",
+                    snapshotOutcome: outcome,
+                    error: null,
+                });
+                this.app.telemetry.recordEvent("graph.snapshot", { outcome });
+            }
+            void this.app.metadataCache.load().then(() => {
+                if (!this.disposed)
+                    void this.requestRefresh("startup");
+            }, (error) => {
+                if (!this.disposed)
+                    this.handleFailure(error);
+            });
+        }
+        catch (error) {
+            this.handleFailure(error);
+        }
+    }
+    async runQueue() {
+        await this.start();
+        await this.app.metadataCache.load();
+        while (this.pending && !this.disposed) {
+            const force = this.pendingForce;
+            this.pending = false;
+            this.pendingForce = false;
+            await this.buildOnce(force);
+        }
+    }
+    async buildOnce(force) {
+        const fingerprint = this.app.metadataCache.getReconciliationFingerprint();
+        if (!force && this.state.graph && this.currentFingerprint === fingerprint) {
+            this.updateState({ status: "ready", progress: null, error: null });
+            return;
+        }
+        this.updateState({
+            status: this.state.graph ? "updating" : "loading",
+            progress: { processed: 0, total: 0, pages: 0 },
+            error: null,
+        });
+        this.abortController = new AbortController();
+        const startedAt = performance.now();
+        let lastProgress = {
+            processed: 0,
+            total: 0,
+            pages: 0,
+        };
+        try {
+            const graph = await this.app.telemetry.measureAsync("graph.build", async (span) => {
+                const result = await buildCanonicalGraph(this.app, {
+                    signal: this.abortController?.signal,
+                    onProgress: (progress) => {
+                        lastProgress = progress;
+                        span.setAttribute("graph.files.processed", progress.processed);
+                        span.setAttribute("graph.files.total", progress.total);
+                        span.setAttribute("graph.page.count", progress.pages);
+                        this.updateState({ progress });
+                    },
+                });
+                span.setAttribute("graph.node.count", result.nodes.length);
+                span.setAttribute("graph.link.count", result.links.length);
+                return result;
+            });
+            if (this.disposed)
+                return;
+            const completedFingerprint = this.app.metadataCache.getReconciliationFingerprint();
+            const completedAt = Date.now();
+            this.currentFingerprint =
+                fingerprint === completedFingerprint ? completedFingerprint : null;
+            this.updateState({
+                graph,
+                status: fingerprint === completedFingerprint ? "ready" : "updating",
+                progress: null,
+                error: null,
+                completedAt,
+            });
+            if (fingerprint === completedFingerprint) {
+                await this.app.appDatabase.setMeta(GRAPH_SNAPSHOT_KEY, {
+                    version: GRAPH_SNAPSHOT_VERSION,
+                    completedAt,
+                    metadataFingerprint: completedFingerprint,
+                    graph,
+                });
+            }
+            else {
+                this.pending = true;
+            }
+            this.app.telemetry.recordEvent("graph.build.complete", {
+                "graph.node.count": graph.nodes.length,
+                "graph.link.count": graph.links.length,
+                "graph.page.count": lastProgress.pages,
+                "graph.duration.ms": Math.round(performance.now() - startedAt),
+                stable: fingerprint === completedFingerprint,
+            });
+        }
+        catch (error) {
+            if (!isCancellation(error))
+                this.handleFailure(error);
+        }
+        finally {
+            this.abortController = null;
+        }
+    }
+    handleFailure(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.updateState({ status: "error", progress: null, error: message });
+        this.app.telemetry.recordEvent("graph.build.failed", {
+            cached: Boolean(this.state.graph),
+        });
+    }
+    updateState(patch) {
+        this.state = {
+            ...this.state,
+            ...patch,
+            version: "graph" in patch ? this.state.version + 1 : this.state.version,
+        };
+        const snapshot = this.getState();
+        for (const listener of this.listeners)
+            listener(snapshot);
+    }
+}
+export const GRAPH_CANONICAL_SNAPSHOT_KEY = GRAPH_SNAPSHOT_KEY;

package/dist/graph-data.d.ts

@@ -0,0 +1,23 @@
+import type { App, TFile } from "@lapis-notes/api";
+import type { GraphData, GraphSettings } from "./graph-types";
+type GraphApp = Pick<App, "vault" | "metadataCache" | "workspace">;
+export interface GraphBuildProgress {
+    processed: number;
+    total: number;
+    pages: number;
+}
+export interface GraphBuildOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: GraphBuildProgress) => void;
+}
+export declare function normalizeGraphTag(tag: string): string;
+export declare function filterGraphBySettings(graph: GraphData, settings: GraphSettings, matches?: {
+    filterPaths?: ReadonlySet<string>;
+    groupPaths?: ReadonlyMap<string, ReadonlySet<string>>;
+}): GraphData;
+export declare function buildCanonicalGraph(app: GraphApp, options?: GraphBuildOptions): Promise<GraphData>;
+export declare function buildGlobalGraph(app: GraphApp, settings: GraphSettings): Promise<GraphData>;
+export declare function buildLocalGraph(app: GraphApp, settings: GraphSettings, activeFile: TFile | null): Promise<GraphData>;
+export declare function buildCanonicalLocalGraph(app: GraphApp, settings: GraphSettings, activeFile: TFile | null): Promise<GraphData>;
+export declare function graphNodeIdForFile(path: string): string;
+export {};