@bendyline/docblocks 2.6.1 → 2.7.0

package/dist/workspace-index/index.d.ts

@@ -0,0 +1,240 @@
+import { n as FileSystemProviderV2, m as FileSystemProviderCapabilities } from '../v2-BVnZZyd4.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+import { d as CatalogDocumentFormat, f as CatalogOutlineEntry } from '../catalog-BQK05tne.js';
+import '@bendyline/squisq/markdown';
+import '../settings-HrrCikVX.js';
+
+/**
+ * What the index reads from. Only read methods are reachable, so the index
+ * cannot write to a workspace by construction.
+ */
+type WorkspaceIndexSource = Pick<FileSystemProviderV2, 'stat' | 'readFile' | 'readDirectory'> & {
+    readonly capabilities?: Pick<FileSystemProviderCapabilities, 'watch'>;
+    readonly watch?: FileSystemProviderV2['watch'];
+};
+interface WorkspaceIndexLimits {
+    /** Files and folders listed in total. */
+    readonly maxEntries: number;
+    readonly maxDirectories: number;
+    readonly maxDepth: number;
+    /** Documents whose text is analyzed; the rest are searchable by name only. */
+    readonly maxDocuments: number;
+    /** Larger documents are indexed by name only, without being read. */
+    readonly maxDocumentBytes: number;
+    /** Larger documents are searched line by line instead of being parsed. */
+    readonly maxParseBytes: number;
+    /** Total searchable text kept in memory, in UTF-16 code units. */
+    readonly maxTextCharacters: number;
+}
+declare const WORKSPACE_INDEX_LIMITS: Readonly<WorkspaceIndexLimits>;
+interface WorkspaceIndexOptions {
+    readonly workspaceId: string;
+    readonly source: WorkspaceIndexSource;
+    /** Read and parse document text (default). `false` indexes names only. */
+    readonly analyze?: boolean;
+    readonly limits?: Partial<WorkspaceIndexLimits>;
+    /** Hands control back to the host between slices of work. */
+    readonly yieldControl?: () => Promise<void>;
+    /** Monotonic clock in milliseconds, for slicing and refresh pacing. */
+    readonly now?: () => number;
+    /** Minimum gap between unforced refreshes; default 15 s. */
+    readonly minRefreshIntervalMs?: number;
+    /** Window that coalesces bursts of change notifications; default 50 ms. */
+    readonly changeCoalesceMs?: number;
+}
+type WorkspaceIndexPhase = 'idle' | 'listing' | 'analyzing' | 'ready' | 'error' | 'disposed';
+type WorkspaceIndexTruncation = 'entries' | 'directories' | 'depth' | 'documents' | 'text';
+interface WorkspaceIndexStatus {
+    readonly phase: WorkspaceIndexPhase;
+    readonly fileCount: number;
+    readonly documentCount: number;
+    readonly analyzedCount: number;
+    readonly pendingCount: number;
+    /** True while provider change events keep the index current. */
+    readonly watching: boolean;
+    /** True once the whole workspace has been listed at least once. */
+    readonly listed: boolean;
+    readonly truncated: {
+        readonly reason: WorkspaceIndexTruncation;
+        readonly limit: number;
+    } | null;
+    /** Folders or documents that could not be read; never reported as absent. */
+    readonly issues: number;
+    /** Why the workspace root could not be listed. */
+    readonly error: string | null;
+    /** Advances whenever the published files, documents, or status change. */
+    readonly generation: number;
+}
+type WorkspaceIndexFileKind = 'markdown' | 'outside-in' | 'other';
+interface WorkspaceIndexFile {
+    readonly path: WorkspacePath;
+    readonly name: string;
+    readonly size: number;
+    readonly lastModified: string;
+    readonly kind: WorkspaceIndexFileKind;
+}
+type IndexedDocumentContent = 'full' | 'lines' | 'name-only';
+type IndexedDocumentIssue = 'pending' | 'too-large' | 'parse-limit' | 'not-utf8' | 'read-error' | 'no-companion' | 'over-budget';
+interface IndexedDocument {
+    /** Navigation identity: the rendered file for outside-in documents. */
+    readonly path: WorkspacePath;
+    /** The Markdown actually read (the companion for outside-in documents). */
+    readonly sourcePath: WorkspacePath | null;
+    readonly format: CatalogDocumentFormat;
+    readonly lastModified: string;
+    readonly title: string;
+    readonly outline: readonly CatalogOutlineEntry[];
+    readonly wordCount: number;
+    readonly excerpt?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    /** `full` = parsed text, `lines` = raw source lines, `name-only` = not searchable by content. */
+    readonly content: IndexedDocumentContent;
+    readonly issue?: IndexedDocumentIssue;
+}
+interface WorkspaceSearchQuery {
+    readonly text: string;
+    readonly matchCase?: boolean;
+    readonly wholeWord?: boolean;
+}
+interface WorkspaceSearchLimits {
+    readonly maxQueryCharacters: number;
+    readonly maxDocuments: number;
+    readonly maxLinesPerDocument: number;
+    readonly maxMatchesPerDocument: number;
+    readonly maxTotalMatches: number;
+}
+declare const WORKSPACE_SEARCH_LIMITS: Readonly<WorkspaceSearchLimits>;
+type WorkspaceSearchRange = readonly [start: number, end: number];
+type WorkspaceSearchLineKind = 'text' | 'heading' | 'code' | 'frontmatter';
+interface WorkspaceSearchLineMatch {
+    /** 1-based source line. */
+    readonly line: number;
+    readonly kind: WorkspaceSearchLineKind;
+    readonly snippet: string;
+    /** Match ranges within `snippet`. */
+    readonly ranges: readonly WorkspaceSearchRange[];
+    /** 0-based index, in document order, of this line's first match. */
+    readonly occurrence: number;
+}
+interface WorkspaceSearchDocument {
+    readonly path: WorkspacePath;
+    readonly title: string;
+    readonly format: CatalogDocumentFormat;
+    readonly titleMatch: boolean;
+    readonly titleRanges: readonly WorkspaceSearchRange[];
+    readonly matchCount: number;
+    readonly matches: readonly WorkspaceSearchLineMatch[];
+    /** More matching lines exist than `matches` lists. */
+    readonly moreMatches: boolean;
+    readonly lastModified: string;
+    /** Not analyzed yet; only its name could be matched. */
+    readonly pending: boolean;
+}
+interface WorkspaceSearchResult {
+    readonly documents: readonly WorkspaceSearchDocument[];
+    readonly totalDocuments: number;
+    readonly totalMatches: number;
+    /** Result caps were reached; more matches exist than were counted or shown. */
+    readonly truncated: boolean;
+    /** Documents not analyzed yet, so their content was not searched. */
+    readonly pendingDocuments: number;
+    /** Documents that will never be content-searched (too large, unreadable, over budget). */
+    readonly skippedDocuments: number;
+}
+interface WorkspaceIndex {
+    readonly workspaceId: string;
+    getStatus(): WorkspaceIndexStatus;
+    /** Called after every published change; read state through the getters. */
+    subscribe(listener: () => void): () => void;
+    /** Begin listing and analysis. Idempotent. */
+    start(): void;
+    /** Every discoverable file, sorted by path; the same array within a generation. */
+    getFiles(): readonly WorkspaceIndexFile[];
+    /** Every document (Markdown and outside-in), sorted by path. */
+    getDocuments(): readonly IndexedDocument[];
+    getDocument(path: string): IndexedDocument | null;
+    /** `unknown` while unlisted, beneath an unreadable folder, or outside coverage. */
+    has(path: string): 'present' | 'absent' | 'unknown';
+    /** Resolves `true` once fully listed, or `false` on timeout. */
+    whenListed(options?: {
+        readonly signal?: AbortSignal;
+        readonly timeoutMs?: number;
+    }): Promise<boolean>;
+    search(query: WorkspaceSearchQuery, options?: {
+        readonly signal?: AbortSignal;
+        readonly limits?: Partial<WorkspaceSearchLimits>;
+    }): Promise<WorkspaceSearchResult>;
+    /** Re-walk the workspace, re-reading only changed documents. Coalesced. */
+    refresh(options?: {
+        readonly force?: boolean;
+    }): void;
+    /** Re-check one path (or subtree) that is known to have changed. */
+    invalidate(path: string): void;
+    /** Analyze these documents before others. */
+    prioritize(paths: readonly string[]): void;
+    /** Stop issuing provider calls until resumed (e.g. while the page is hidden). */
+    setPaused(paused: boolean): void;
+    /** Stop all work and release the watch subscription. Never disposes the source. */
+    dispose(): void;
+}
+
+/**
+ * In-memory workspace index: one shared listing of the files people can open,
+ * plus each document's title, outline, and searchable text.
+ *
+ * Every feature that used to walk the workspace on its own (link picker,
+ * quick-open, search) reads from here instead, so the workspace is walked once
+ * and kept current from provider change events (or explicit refreshes where
+ * the provider cannot watch).
+ *
+ * All provider calls go through one serial work loop, so at most one is ever
+ * outstanding: on desktop every read queues behind the same per-workspace
+ * lock as the user's saves, and parallel reads would only make saves wait.
+ */
+
+/** Create an index over one workspace. Call `start()` to begin. */
+declare function createWorkspaceIndex(options: WorkspaceIndexOptions): WorkspaceIndex;
+
+/**
+ * Literal workspace search over indexed text: exact matches, optional case
+ * and whole-word constraints, line snippets with highlight ranges.
+ */
+
+/**
+ * Compile a query, or null when it cannot match anything (empty or too long).
+ * Whole word only constrains the query's ends that are themselves word
+ * characters, so `c++` still matches before a space.
+ */
+declare function buildLiteralMatcher(query: WorkspaceSearchQuery, maxQueryCharacters?: number): RegExp | null;
+/** A display line around its matches, with the ranges shifted to fit. */
+declare function buildSnippet(line: string, ranges: readonly WorkspaceSearchRange[]): {
+    readonly snippet: string;
+    readonly ranges: readonly WorkspaceSearchRange[];
+};
+
+/**
+ * Fuzzy subsequence scoring for quick-open: every query character must
+ * appear in order. Matches at word starts and in consecutive runs score
+ * higher; skipped characters cost a little. Returns highlight ranges.
+ */
+
+interface FuzzyMatch {
+    readonly score: number;
+    readonly ranges: readonly WorkspaceSearchRange[];
+}
+/**
+ * Score one query token against a target, or null when it does not match.
+ * Finds the earliest-ending match, then walks back to the tightest window
+ * that still contains it, so `ab` in `a…xab` highlights the `ab` run.
+ */
+declare function fuzzyMatch(query: string, target: string): FuzzyMatch | null;
+/**
+ * Every whitespace-separated token must match. Scores add up; ranges merge.
+ * Returns null when any token misses.
+ */
+declare function fuzzyMatchTokens(tokens: readonly string[], target: string): FuzzyMatch | null;
+/** Split a quick-open query into tokens. */
+declare function fuzzyTokens(query: string): string[];
+
+export { type FuzzyMatch, type IndexedDocument, type IndexedDocumentContent, type IndexedDocumentIssue, WORKSPACE_INDEX_LIMITS, WORKSPACE_SEARCH_LIMITS, type WorkspaceIndex, type WorkspaceIndexFile, type WorkspaceIndexFileKind, type WorkspaceIndexLimits, type WorkspaceIndexOptions, type WorkspaceIndexPhase, type WorkspaceIndexSource, type WorkspaceIndexStatus, type WorkspaceIndexTruncation, type WorkspaceSearchDocument, type WorkspaceSearchLimits, type WorkspaceSearchLineKind, type WorkspaceSearchLineMatch, type WorkspaceSearchQuery, type WorkspaceSearchRange, type WorkspaceSearchResult, buildLiteralMatcher, buildSnippet, createWorkspaceIndex, fuzzyMatch, fuzzyMatchTokens, fuzzyTokens };