@bendyline/docblocks 2.6.1 → 2.7.0

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

@@ -0,0 +1,301 @@
+import { R as ResolvedCatalogOutputs, W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-HrrCikVX.js';
+export { b as CATALOG_JSON_CONTENT_MODES, c as CATALOG_SORT_ORDERS, d as CatalogJsonContent, e as CatalogOutputKind, C as CatalogSortOrder, D as DEFAULT_CATALOG_HTML_PATH, f as DEFAULT_CATALOG_JSON_PATH, g as DEFAULT_CATALOG_TITLE, E as EMPTY_WORKSPACE_SETTINGS, U as UnsupportedWorkspaceSettingsVersionError, h as WORKSPACE_SETTINGS_DIRECTORY, i as WORKSPACE_SETTINGS_LIMITS, j as WORKSPACE_SETTINGS_PATH, k as WORKSPACE_SETTINGS_VERSION, l as WORKSPACE_THEME_ID_PATTERN, m as WorkspaceCatalogHtmlSettings, n as WorkspaceCatalogJsonSettings, o as WorkspaceCatalogSettings, p as WorkspaceDocumentSettings, q as WorkspaceSettingsParseResult, r as WorkspaceVersionHistorySettings, s as applyWorkspaceSettingsPatch, t as checkCatalogOutputPath, u as diffWorkspaceSettings, v as isDefaultWorkspaceSettings, w as isEmptyWorkspaceSettingsPatch, x as parseWorkspaceSettings, y as parseWorkspaceSettingsPatch, z as parseWorkspaceSettingsText, A as resolveCatalogOutputs, B as resolveFallbackThemeId, F as resolveWorkspaceDefaultThemeId, G as resolveWorkspaceVersioningEnabled, H as serializeWorkspaceSettings, I as tryApplyWorkspaceSettingsPatch, J as validateCatalogOutputPath } from '../settings-HrrCikVX.js';
+import { C as CatalogEntry, W as WorkspaceCatalog } from '../catalog-BQK05tne.js';
+export { a as CATALOG_FORMAT_VERSION, b as CATALOG_GENERATOR, c as CATALOG_LIMITS, d as CatalogDocumentFormat, e as CatalogEntryHints, f as CatalogOutlineEntry, g as CatalogSource, O as OUTSIDE_IN_FORMAT_IDS, h as OutsideInFormatId, i as OutsideInLayout, j as buildCatalogMarkdownDocument, k as catalogEntryForUnreadable, l as catalogEntryFromDocument, m as catalogEntryFromMarkdown, n as chooseOutsideInMarkdownPath, o as createWorkspaceCatalog, p as isGeneratedCatalogHtml, q as isGeneratedCatalogJson, r as readCatalogHtmlDigest, s as relativeCatalogLink, t as relocateOutsideInLayout, u as resolveOutsideInLayout, v as serializeCatalogJson, w as sortCatalogEntries, x as stampCatalogHtml } from '../catalog-BQK05tne.js';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { u as FileSystemVersion, n as FileSystemProviderV2 } from '../v2-BVnZZyd4.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+
+/**
+ * JSON Schema (draft-07) for `.docblocks/workspace.json`, used for editor
+ * validation and completion (VS Code `contributes.jsonValidation`). The
+ * runtime parser in `settings.ts` remains the authority; tests keep the two
+ * aligned.
+ */
+declare const WORKSPACE_SETTINGS_JSON_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "DocBlocks workspace settings";
+    readonly description: "Settings shared by everyone who opens this folder in DocBlocks. Every section is optional.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly maxLength: 2048;
+        };
+        readonly version: {
+            readonly const: 1;
+            readonly description: "Settings format version.";
+        };
+        readonly documents: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly defaultTheme: {
+                    readonly description: "Theme for documents whose frontmatter does not name one. A document’s own theme always wins.";
+                    readonly type: "string";
+                    readonly pattern: string;
+                };
+            };
+        };
+        readonly versionHistory: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly enabled: {
+                    readonly type: "boolean";
+                    readonly description: "Keep prior revisions for documents in this folder. Omit to use the app default.";
+                };
+                readonly keep: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 1000;
+                    readonly description: "Revisions kept per document.";
+                };
+            };
+        };
+        readonly catalog: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 256;
+                    readonly description: "Catalog heading. Defaults to \"Documents\".";
+                };
+                readonly sort: {
+                    readonly enum: readonly ["title", "path", "date"];
+                    readonly description: "Catalog order. Defaults to \"title\".";
+                };
+                readonly exclude: {
+                    readonly type: "array";
+                    readonly maxItems: 64;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 1024;
+                    };
+                    readonly description: "Workspace-relative folders or files left out of the catalog.";
+                };
+                readonly html: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly enabled: {
+                            readonly type: "boolean";
+                            readonly description: "Regenerate the catalog page on every save.";
+                        };
+                        readonly path: {
+                            readonly pattern: "\\.html?$";
+                            readonly description: "Catalog page path. Defaults to \"index.html\".";
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 1024;
+                        };
+                        readonly theme: {
+                            readonly description: "Theme for the catalog page only.";
+                            readonly type: "string";
+                            readonly pattern: string;
+                        };
+                    };
+                };
+                readonly json: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly enabled: {
+                            readonly type: "boolean";
+                            readonly description: "Regenerate the catalog data on every save.";
+                        };
+                        readonly path: {
+                            readonly pattern: "\\.json$";
+                            readonly description: "Catalog data path. Defaults to \"catalog.json\".";
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 1024;
+                        };
+                        readonly content: {
+                            readonly enum: readonly ["metadata", "markdown"];
+                            readonly description: "\"metadata\" (default) or \"markdown\" to include each document’s source.";
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+
+/**
+ * Regenerate a workspace's catalog outputs (catalog JSON and catalog HTML).
+ *
+ * One filesystem-agnostic implementation serves every surface: the shell
+ * passes its v2 provider, the VS Code extension host and the CLI pass small
+ * adapters over `vscode.workspace.fs` and `node:fs`. The HTML renderer is
+ * injected so core never depends on `@bendyline/squisq-formats`.
+ *
+ * Safety rules, all enforced here rather than by callers:
+ * - Outputs are written only when enabled in settings.
+ * - An existing file is replaced only when it carries the DocBlocks catalog
+ *   marker; a hand-written `index.html` is never clobbered.
+ * - Writes are skipped when bytes (or the HTML inputs digest) are unchanged,
+ *   so watchers, git, and sync clients see no churn.
+ * - The walk is budgeted; over budget nothing is written rather than a
+ *   truncated catalog.
+ */
+
+type WorkspaceOutputsIO = Pick<FileSystemProviderV2, 'stat' | 'readFile' | 'readDirectory' | 'writeFile'>;
+interface WorkspaceOutputsRenderer {
+    /** Render the catalog AST as a complete, themed, script-free HTML page. */
+    renderCatalogHtml(document: MarkdownDocument, options: {
+        readonly title: string;
+        readonly themeId: string | undefined;
+    }): string | Promise<string>;
+    /** Parse rendered HTML that has no Markdown companion yet. Optional. */
+    importHtml?(html: string): MarkdownDocument | Promise<MarkdownDocument>;
+}
+declare const WORKSPACE_OUTPUT_LIMITS: {
+    readonly maxDocuments: 5000;
+    readonly maxDirectories: 20000;
+    readonly maxDepth: 32;
+    readonly maxDocumentBytes: number;
+    readonly maxTotalBytes: number;
+    readonly maxOutputBytes: number;
+};
+type WorkspaceOutputLimits = {
+    readonly [K in keyof typeof WORKSPACE_OUTPUT_LIMITS]: number;
+};
+/** The walk exceeded a budget; nothing was written. */
+declare class WorkspaceOutputsLimitError extends Error {
+    constructor(message: string);
+}
+interface CachedEntry {
+    readonly readPath: string;
+    readonly version: FileSystemVersion;
+    readonly includeMarkdown: boolean;
+    /** null records a file that is deliberately not listed (a generated catalog page). */
+    readonly entry: CatalogEntry | null;
+}
+/** Per-document extraction cache keyed by path + provider version. Reuse it across runs. */
+type WorkspaceCatalogCache = Map<string, CachedEntry>;
+declare function createWorkspaceCatalogCache(): WorkspaceCatalogCache;
+interface RefreshWorkspaceOutputsOptions {
+    readonly cache?: WorkspaceCatalogCache;
+    readonly signal?: AbortSignal;
+    /** Rewrite the HTML page even when its inputs digest is unchanged. */
+    readonly force?: boolean;
+    /** Compute everything, write nothing. */
+    readonly dryRun?: boolean;
+    readonly limits?: Partial<WorkspaceOutputLimits>;
+}
+type WorkspaceOutputStatus = 'written' | 'unchanged' | 'blocked' | 'would-write';
+interface WorkspaceOutputResult {
+    readonly kind: 'html' | 'json';
+    readonly path: WorkspacePath;
+    readonly status: WorkspaceOutputStatus;
+    readonly message?: string;
+    /** True when this run created the file (it did not exist before). */
+    readonly created?: true;
+}
+interface WorkspaceOutputsResult {
+    readonly documentCount: number;
+    readonly outputs: readonly WorkspaceOutputResult[];
+}
+/**
+ * Whether a changed path can affect the catalog. Used by schedulers to ignore
+ * their own output writes, version snapshots, and other hidden bookkeeping.
+ * `.docblocks/` changes are settings changes, handled by the caller.
+ */
+declare function isCatalogRelevantPath(path: string, settings: WorkspaceSettings | null | undefined): boolean;
+/** True for the workspace settings directory or anything inside it. */
+declare function isWorkspaceSettingsPath(path: string): boolean;
+/** Walk the workspace and build its catalog without writing anything. */
+declare function collectWorkspaceCatalog(io: WorkspaceOutputsIO, resolved: ResolvedCatalogOutputs, renderer: Pick<WorkspaceOutputsRenderer, 'importHtml'>, options?: Omit<RefreshWorkspaceOutputsOptions, 'force' | 'dryRun'>): Promise<WorkspaceCatalog>;
+/**
+ * Regenerate every enabled catalog output for one workspace. Throws
+ * {@link WorkspaceOutputsLimitError} when over budget, `FsError('aborted')`
+ * when cancelled, and propagates storage errors (including `conflict` when a
+ * concurrent writer won, which callers should answer with one re-run).
+ */
+declare function refreshWorkspaceOutputs(io: WorkspaceOutputsIO, settings: WorkspaceSettings | null | undefined, renderer: WorkspaceOutputsRenderer, options?: RefreshWorkspaceOutputsOptions): Promise<WorkspaceOutputsResult>;
+
+/**
+ * Read and write `.docblocks/workspace.json` through a workspace's v2
+ * provider (or any adapter with the same read/write contract). Every surface
+ * shares these conflict and merge rules.
+ */
+
+/** The two operations settings persistence needs. */
+type WorkspaceSettingsIO = Pick<FileSystemProviderV2, 'readFile' | 'writeFile'>;
+type WorkspaceSettingsStatus = 'unavailable' | 'loading' | 'missing' | 'ready' | 'invalid' | 'unsupported-version' | 'error';
+interface WorkspaceSettingsState {
+    readonly status: WorkspaceSettingsStatus;
+    /** Settings in effect; null unless the file is missing (defaults) or valid. */
+    readonly settings: WorkspaceSettings | null;
+    /** Version of the file that `settings` came from; null when it does not exist. */
+    readonly version: FileSystemVersion | null;
+    /** Why the file cannot be used or changed, for display. */
+    readonly message: string | null;
+}
+declare const UNAVAILABLE_WORKSPACE_SETTINGS: WorkspaceSettingsState;
+declare const LOADING_WORKSPACE_SETTINGS: WorkspaceSettingsState;
+/** Only a missing file or a valid current-version file may be written. */
+declare function isWorkspaceSettingsWritable(state: WorkspaceSettingsState): boolean;
+declare function readWorkspaceSettings(provider: WorkspaceSettingsIO): Promise<WorkspaceSettingsState>;
+/**
+ * Apply a field-level patch on top of the file version the caller last
+ * observed. When another window or a git pull changed the file meanwhile,
+ * re-read it and apply the same patch once more so neither edit is lost.
+ * A file that turned invalid or newer is never overwritten, and a missing file
+ * is not created when the result would only hold defaults.
+ */
+declare function saveWorkspaceSettingsPatch(provider: WorkspaceSettingsIO, observed: WorkspaceSettingsState, patch: WorkspaceSettingsPatch): Promise<WorkspaceSettingsState>;
+
+/**
+ * Keeps a workspace's catalog outputs (`index.html`, `catalog.json`) current.
+ *
+ * One scheduler serves one workspace. Document commits and file-tree changes
+ * call `notify(path)`; the scheduler debounces them (with a maximum wait so a
+ * long typing session still refreshes), runs one refresh at a time, and
+ * re-runs once when changes arrived mid-run. Its own output writes, version
+ * snapshots, and other hidden bookkeeping never trigger a run. Disposing it
+ * (workspace switch) cancels any in-flight walk.
+ */
+
+interface WorkspaceOutputsStatus {
+    readonly state: 'idle' | 'pending' | 'running' | 'done' | 'error';
+    readonly result: WorkspaceOutputsResult | null;
+    /** A run failure, or the first blocked output's explanation. */
+    readonly message: string | null;
+}
+declare const IDLE_WORKSPACE_OUTPUTS_STATUS: WorkspaceOutputsStatus;
+interface WorkspaceOutputsScheduler {
+    readonly workspaceId: string;
+    /** A document or folder changed. Paths that cannot affect the catalog are ignored. */
+    notify(path?: string): void;
+    /** Run now if a refresh is pending. */
+    flush(): void;
+    /** Run now regardless of pending changes. */
+    regenerate(options?: {
+        readonly force?: boolean;
+    }): Promise<WorkspaceOutputsStatus>;
+    updateSettings(settings: WorkspaceSettings | null): void;
+    getStatus(): WorkspaceOutputsStatus;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+interface WorkspaceOutputsSchedulerOptions {
+    readonly workspaceId: string;
+    readonly provider: WorkspaceOutputsIO;
+    readonly settings: WorkspaceSettings | null;
+    /** The renderer, or a loader so rendering code loads only once a catalog is enabled. */
+    readonly renderer: WorkspaceOutputsRenderer | (() => Promise<WorkspaceOutputsRenderer>);
+    readonly debounceMs?: number;
+    readonly maxWaitMs?: number;
+}
+declare const WORKSPACE_OUTPUTS_DEBOUNCE_MS = 2500;
+declare const WORKSPACE_OUTPUTS_MAX_WAIT_MS = 20000;
+declare function createWorkspaceOutputsScheduler(options: WorkspaceOutputsSchedulerOptions): WorkspaceOutputsScheduler;
+
+export { CatalogEntry, IDLE_WORKSPACE_OUTPUTS_STATUS, LOADING_WORKSPACE_SETTINGS, type RefreshWorkspaceOutputsOptions, ResolvedCatalogOutputs, UNAVAILABLE_WORKSPACE_SETTINGS, WORKSPACE_OUTPUTS_DEBOUNCE_MS, WORKSPACE_OUTPUTS_MAX_WAIT_MS, WORKSPACE_OUTPUT_LIMITS, WORKSPACE_SETTINGS_JSON_SCHEMA, WorkspaceCatalog, type WorkspaceCatalogCache, type WorkspaceOutputLimits, type WorkspaceOutputResult, type WorkspaceOutputStatus, type WorkspaceOutputsIO, WorkspaceOutputsLimitError, type WorkspaceOutputsRenderer, type WorkspaceOutputsResult, type WorkspaceOutputsScheduler, type WorkspaceOutputsSchedulerOptions, type WorkspaceOutputsStatus, WorkspaceSettings, type WorkspaceSettingsIO, WorkspaceSettingsPatch, type WorkspaceSettingsState, type WorkspaceSettingsStatus, collectWorkspaceCatalog, createWorkspaceCatalogCache, createWorkspaceOutputsScheduler, isCatalogRelevantPath, isWorkspaceSettingsPath, isWorkspaceSettingsWritable, readWorkspaceSettings, refreshWorkspaceOutputs, saveWorkspaceSettingsPatch };