@bendyline/docblocks 2.0.0 → 2.1.0

package/src/filesystem/memory-provider.ts

@@ -1,180 +0,0 @@
-/**
- * In-memory filesystem used by transient loose-file and DBK workspaces.
- *
- * MemoryFileSystemProviderV2 is authoritative. This class is the temporary
- * text-oriented v1 facade retained while callers migrate to the byte contract.
- */
-
-import { FsError, type FsOperation } from './fs-error.js';
-import {
-  MemoryFileSystemProviderV2,
-  type MemoryFileSystemV2ReplacementFile,
-} from './memory-provider-v2.js';
-import type { FileCommitResult, FileSystemEntry, FileSystemProvider, FileMeta } from './types.js';
-import { parseWorkspacePath, type WorkspacePath } from './workspace-path.js';
-
-export type MemoryFileSystemSnapshotFile =
-  | {
-      readonly kind: 'text';
-      readonly path: string;
-      readonly content: string;
-    }
-  | {
-      readonly kind: 'binary';
-      readonly path: string;
-      readonly data: ArrayBuffer | Uint8Array;
-    };
-
-/** Complete provider-relative state for a transient memory workspace. */
-export interface MemoryFileSystemSnapshot {
-  readonly files: readonly MemoryFileSystemSnapshotFile[];
-  readonly directories?: readonly string[];
-}
-
-function canonicalPath(path: string): WorkspacePath {
-  return parseWorkspacePath(path);
-}
-
-function entryPath(path: string, operation: FsOperation): WorkspacePath {
-  const canonical = canonicalPath(path);
-  if (!canonical) {
-    throw new FsError('invalid-path', 'The workspace root is not a file entry.', {
-      operation,
-      path,
-    });
-  }
-  return canonical;
-}
-
-function decode(data: ArrayBuffer): string {
-  return new TextDecoder().decode(data);
-}
-
-/**
- * Legacy facade over the correctness-first memory provider.
- *
- * Synchronous seed/snapshot replacement methods remain because DBK import
- * fully stages external bytes before publishing one atomic in-memory swap.
- */
-export class MemoryFileSystemProvider implements FileSystemProvider {
-  public readonly id: string;
-  public readonly label: string;
-  public readonly v2: MemoryFileSystemProviderV2;
-
-  public constructor(id: string, label: string) {
-    this.id = id;
-    this.label = label;
-    this.v2 = new MemoryFileSystemProviderV2(id, label);
-  }
-
-  /** Monotonic version of the complete in-memory tree. */
-  public get treeVersion(): number {
-    return this.v2.mutationRevision;
-  }
-
-  /** Capture an owned deterministic copy of the complete transient tree. */
-  public captureContents(): MemoryFileSystemSnapshot {
-    const state = this.v2.captureState();
-    return {
-      files: state.files.map((file) =>
-        file.payloadKind === 'text'
-          ? { kind: 'text' as const, path: file.path, content: decode(file.data) }
-          : { kind: 'binary' as const, path: file.path, data: file.data.slice(0) },
-      ),
-      directories: [...state.directories],
-    };
-  }
-
-  /** Atomically replace the complete tree after validating and owning all input. */
-  public replaceContents(snapshot: MemoryFileSystemSnapshot, expectedTreeVersion?: number): void {
-    const files: MemoryFileSystemV2ReplacementFile[] = snapshot.files.map((file) => ({
-      path: entryPath(file.path, 'write'),
-      payloadKind: file.kind,
-      data: file.kind === 'text' ? new TextEncoder().encode(file.content) : file.data,
-    }));
-    const directories = (snapshot.directories ?? []).map((path) =>
-      entryPath(path, 'create-directory'),
-    );
-    this.v2.replaceState({ files, directories }, expectedTreeVersion);
-  }
-
-  /** Seed synchronously before publishing a transient provider to consumers. */
-  public seedText(path: string, content: string): void {
-    this.v2.seedText(entryPath(path, 'write'), content);
-  }
-
-  public async readFile(path: string): Promise<string | null> {
-    const file = await this.v2.readFile(entryPath(path, 'read'));
-    return file ? decode(file.data) : null;
-  }
-
-  public async writeFile(path: string, content: string): Promise<void> {
-    await this.v2.writeText(entryPath(path, 'write'), content, { createParents: true });
-  }
-
-  public commitFile(
-    path: string,
-    content: string,
-    expectedContent: string | null,
-  ): Promise<FileCommitResult> {
-    return this.v2.commitText(entryPath(path, 'write'), content, expectedContent);
-  }
-
-  public async delete(path: string): Promise<void> {
-    await this.v2.remove(entryPath(path, 'remove'), { recursive: true, missing: 'ignore' });
-  }
-
-  public async rename(oldPath: string, newPath: string): Promise<void> {
-    await this.v2.move(entryPath(oldPath, 'move'), entryPath(newPath, 'move'), {
-      createParents: true,
-    });
-  }
-
-  public async readDirectory(path: string): Promise<FileSystemEntry[]> {
-    const canonical = canonicalPath(path);
-    try {
-      const entries = await this.v2.readDirectory(canonical);
-      return entries.map((entry) => ({
-        kind: entry.kind,
-        name: entry.name,
-        path: entry.path,
-      }));
-    } catch (error: unknown) {
-      // Preserve the v1 missing-directory behavior only on the compatibility facade.
-      if (error instanceof FsError && error.code === 'not-found') return [];
-      throw error;
-    }
-  }
-
-  public async exists(path: string): Promise<boolean> {
-    return (await this.v2.stat(canonicalPath(path))) !== null;
-  }
-
-  public async createDirectory(path: string): Promise<void> {
-    await this.v2.createDirectory(canonicalPath(path), { createParents: true });
-  }
-
-  public async stat(path: string): Promise<FileMeta | null> {
-    const canonical = canonicalPath(path);
-    if (!canonical) return null;
-    const entry = await this.v2.stat(canonical);
-    if (!entry || entry.kind !== 'file') return null;
-    return {
-      name: entry.name,
-      path: entry.path,
-      size: entry.size,
-      lastModified: entry.lastModified,
-    };
-  }
-
-  public async readBinary(path: string): Promise<ArrayBuffer | null> {
-    const canonical = entryPath(path, 'read');
-    const file = this.v2.readCompatibilityFile(canonical);
-    if (!file || file.payloadKind !== 'binary') return null;
-    return file.data;
-  }
-
-  public async writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    await this.v2.writeBinary(entryPath(path, 'write'), data, { createParents: true });
-  }
-}

package/src/filesystem/memory.ts

@@ -1,15 +0,0 @@
-/** Transient in-memory filesystem provider entry point. */
-export {
-  MemoryFileSystemProvider,
-  type MemoryFileSystemSnapshot,
-  type MemoryFileSystemSnapshotFile,
-} from './memory-provider.js';
-export {
-  MemoryFileSystemProviderV2,
-  type MemoryFilePayloadKind,
-  type MemoryFileSystemV2CompatibilityFile,
-  type MemoryFileSystemV2Replacement,
-  type MemoryFileSystemV2ReplacementFile,
-  type MemoryFileSystemV2State,
-  type MemoryFileSystemV2StateFile,
-} from './memory-provider-v2.js';

package/src/filesystem/move-entry.ts

@@ -1,142 +0,0 @@
-import { getFileSystemProviderV2, type FileSystemProvider } from './types.js';
-import {
-  describeEntryMove,
-  describePartialMove,
-  FileSystemMoveRecoveryError,
-  FileSystemPartialMoveError,
-} from './move-error.js';
-import { parseWorkspacePath } from './workspace-path.js';
-
-function normalisePath(path: string): string {
-  return parseWorkspacePath(path);
-}
-
-function dirname(path: string): string {
-  const slash = path.lastIndexOf('/');
-  return slash < 0 ? '' : path.slice(0, slash);
-}
-
-function basename(path: string): string {
-  const slash = path.lastIndexOf('/');
-  return slash < 0 ? path : path.slice(slash + 1);
-}
-
-/** Return the hidden companion directory used for a document's media and versions. */
-export function documentCompanionPath(documentPath: string): string {
-  const rooted = documentPath.replace(/\\/g, '/').startsWith('/');
-  const clean = parseWorkspacePath(documentPath);
-  if (!clean) throw new Error('The workspace root has no document companion path.');
-  const parent = dirname(clean);
-  const name = basename(clean).replace(/\.[^.]+$/, '');
-  if (parent) return `${parent}/${name}_files`;
-  return rooted ? `/${name}_files` : `${name}_files`;
-}
-
-function isMarkdownPath(path: string): boolean {
-  return /\.md$/i.test(basename(path));
-}
-
-/**
- * Move an explorer entry without overwriting an existing entry. Markdown files
- * carry their hidden `<basename>_files` companion directory with them.
- */
-export async function moveFileSystemEntry(
-  provider: FileSystemProvider,
-  oldPath: string,
-  newPath: string,
-  kind: 'file' | 'directory',
-): Promise<void> {
-  const providerV2 = getFileSystemProviderV2(provider);
-  const exists = (candidate: string): Promise<boolean> =>
-    providerV2
-      ? providerV2.stat(parseWorkspacePath(candidate)).then((entry) => entry !== null)
-      : provider.exists(candidate);
-  const move = (source: string, destination: string): Promise<void> =>
-    providerV2
-      ? providerV2
-          .move(parseWorkspacePath(source), parseWorkspacePath(destination), {
-            createParents: true,
-          })
-          .then(() => undefined)
-      : provider.rename(source, destination);
-
-  const oldNormalised = normalisePath(oldPath);
-  const newNormalised = normalisePath(newPath);
-  if (oldNormalised === newNormalised) return;
-
-  if (kind === 'directory' && newNormalised.startsWith(`${oldNormalised}/`)) {
-    throw new Error('A folder cannot be moved into itself.');
-  }
-  if (await exists(newPath)) {
-    throw new Error(`An entry named "${basename(newPath)}" already exists there.`);
-  }
-
-  let oldCompanion: string | null = null;
-  let newCompanion: string | null = null;
-  if (kind === 'file' && isMarkdownPath(oldPath)) {
-    const candidate = documentCompanionPath(oldPath);
-    if (await exists(candidate)) {
-      oldCompanion = candidate;
-      newCompanion = documentCompanionPath(newPath);
-      if (
-        normalisePath(oldCompanion) !== normalisePath(newCompanion) &&
-        (await exists(newCompanion))
-      ) {
-        throw new Error(`The companion folder "${basename(newCompanion)}" already exists there.`);
-      }
-    }
-  }
-
-  try {
-    await move(oldPath, newPath);
-  } catch (error: unknown) {
-    const state = await describeEntryMove(provider, oldPath, newPath);
-    if (state.source === 'present' && state.destination === 'missing') throw error;
-    throw new FileSystemMoveRecoveryError(oldPath, newPath, state, error);
-  }
-  if (!oldCompanion || !newCompanion) return;
-
-  try {
-    await move(oldCompanion, newCompanion);
-  } catch (error: unknown) {
-    // Keep the document and its assets together when the second half fails.
-    try {
-      await move(newPath, oldPath);
-    } catch (rollbackError: unknown) {
-      const state = await describePartialMove(
-        provider,
-        oldPath,
-        newPath,
-        oldCompanion,
-        newCompanion,
-      );
-      throw new FileSystemPartialMoveError(
-        oldPath,
-        newPath,
-        oldCompanion,
-        newCompanion,
-        state,
-        error,
-        rollbackError,
-      );
-    }
-    const state = await describePartialMove(provider, oldPath, newPath, oldCompanion, newCompanion);
-    const restoredSourceOnly =
-      state.source === 'present' &&
-      state.destination === 'missing' &&
-      state.companionSource === 'present' &&
-      state.companionDestination === 'missing';
-    if (!restoredSourceOnly) {
-      throw new FileSystemPartialMoveError(
-        oldPath,
-        newPath,
-        oldCompanion,
-        newCompanion,
-        state,
-        error,
-        null,
-      );
-    }
-    throw error;
-  }
-}

package/src/filesystem/move-error.ts

@@ -1,159 +0,0 @@
-import { getFileSystemProviderV2, type FileSystemProvider } from './types.js';
-import { parseWorkspacePath } from './workspace-path.js';
-
-export type FileSystemPathPresence = 'present' | 'missing' | 'unknown';
-
-export interface FileSystemPartialMoveState {
-  readonly source: FileSystemPathPresence;
-  readonly destination: FileSystemPathPresence;
-  readonly companionSource: FileSystemPathPresence;
-  readonly companionDestination: FileSystemPathPresence;
-}
-
-export type FileSystemMoveLocation = 'source' | 'destination' | 'both' | 'neither' | 'unknown';
-
-export interface FileSystemEntryMoveState {
-  readonly source: FileSystemPathPresence;
-  readonly destination: FileSystemPathPresence;
-}
-
-function locationFromPresence(
-  source: FileSystemPathPresence,
-  destination: FileSystemPathPresence,
-): FileSystemMoveLocation {
-  if (source === 'unknown' || destination === 'unknown') return 'unknown';
-  if (source === 'present' && destination === 'present') return 'both';
-  if (source === 'present') return 'source';
-  if (destination === 'present') return 'destination';
-  return 'neither';
-}
-
-/**
- * One provider move failed without restoring a provable source-only state.
- * This is backend-neutral: callers must use `location`, never infer from the
- * original exception or a provider's advertised move atomicity.
- */
-export class FileSystemMoveRecoveryError extends Error {
-  public readonly code = 'partial-move' as const;
-
-  public constructor(
-    public readonly sourcePath: string,
-    public readonly destinationPath: string,
-    public readonly state: FileSystemEntryMoveState,
-    public readonly moveError: unknown,
-  ) {
-    super(
-      `The move did not restore one authoritative path. Entry location: ${locationFromPresence(
-        state.source,
-        state.destination,
-      )}.`,
-    );
-    this.name = 'FileSystemMoveRecoveryError';
-  }
-
-  public get location(): FileSystemMoveLocation {
-    return locationFromPresence(this.state.source, this.state.destination);
-  }
-
-  /** Alias used by DocumentSession's document-retarget recovery protocol. */
-  public get documentLocation(): FileSystemMoveLocation {
-    return this.location;
-  }
-}
-
-/**
- * A compound document/companion move failed and the document rollback also
- * failed. Callers must use the recorded post-state instead of assuming the
- * original path is still authoritative.
- */
-export class FileSystemPartialMoveError extends Error {
-  readonly code = 'partial-move' as const;
-
-  constructor(
-    readonly sourcePath: string,
-    readonly destinationPath: string,
-    readonly companionSourcePath: string,
-    readonly companionDestinationPath: string,
-    readonly state: FileSystemPartialMoveState,
-    readonly moveError: unknown,
-    readonly rollbackError: unknown,
-  ) {
-    super(
-      `The document move could not be rolled back. Document location: ${locationFromPresence(
-        state.source,
-        state.destination,
-      )}; companion location: ${locationFromPresence(
-        state.companionSource,
-        state.companionDestination,
-      )}.`,
-    );
-    this.name = 'FileSystemPartialMoveError';
-  }
-
-  get documentLocation(): FileSystemMoveLocation {
-    return locationFromPresence(this.state.source, this.state.destination);
-  }
-
-  get companionLocation(): FileSystemMoveLocation {
-    return locationFromPresence(this.state.companionSource, this.state.companionDestination);
-  }
-}
-
-export function isFileSystemPartialMoveError(error: unknown): error is FileSystemPartialMoveError {
-  return error instanceof FileSystemPartialMoveError;
-}
-
-export function isFileSystemMoveRecoveryError(
-  error: unknown,
-): error is FileSystemMoveRecoveryError {
-  return error instanceof FileSystemMoveRecoveryError;
-}
-
-export function isFileSystemMoveStateError(
-  error: unknown,
-): error is FileSystemMoveRecoveryError | FileSystemPartialMoveError {
-  return isFileSystemMoveRecoveryError(error) || isFileSystemPartialMoveError(error);
-}
-
-async function probePath(
-  provider: FileSystemProvider,
-  path: string,
-): Promise<FileSystemPathPresence> {
-  try {
-    const providerV2 = getFileSystemProviderV2(provider);
-    const present = providerV2
-      ? (await providerV2.stat(parseWorkspacePath(path))) !== null
-      : await provider.exists(path);
-    return present ? 'present' : 'missing';
-  } catch {
-    return 'unknown';
-  }
-}
-
-export async function describePartialMove(
-  provider: FileSystemProvider,
-  sourcePath: string,
-  destinationPath: string,
-  companionSourcePath: string,
-  companionDestinationPath: string,
-): Promise<FileSystemPartialMoveState> {
-  const [source, destination, companionSource, companionDestination] = await Promise.all([
-    probePath(provider, sourcePath),
-    probePath(provider, destinationPath),
-    probePath(provider, companionSourcePath),
-    probePath(provider, companionDestinationPath),
-  ]);
-  return { source, destination, companionSource, companionDestination };
-}
-
-export async function describeEntryMove(
-  provider: FileSystemProvider,
-  sourcePath: string,
-  destinationPath: string,
-): Promise<FileSystemEntryMoveState> {
-  const [source, destination] = await Promise.all([
-    probePath(provider, sourcePath),
-    probePath(provider, destinationPath),
-  ]);
-  return { source, destination };
-}