@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/vfs/index.d.ts

@@ -1,6 +1,360 @@
-export * from './factory';
-export * from './fs-tree';
-export * from './commit';
-export * from './diff';
-export * from './types';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Write mode for file operations.
+ */
+declare const Mode: Readonly<{
+    /** Overwrite existing files */
+    readonly Overwrite: "overwrite";
+    /** Fail if file exists */
+    readonly ExclusiveCreate: "exclusive";
+    /** Skip if file exists */
+    readonly SkipIfExists: "skip";
+}>;
+/**
+ * Write mode type extracted from Mode object.
+ */
+type ModeType = (typeof Mode)[keyof typeof Mode];
+/**
+ * A single file change in the tree.
+ */
+interface FileChange {
+    /** Relative path from tree root */
+    path: string;
+    /** Type of change */
+    type: 'CREATE' | 'UPDATE' | 'DELETE';
+    /** File content (undefined for DELETE) */
+    content?: Buffer;
+    /** Original content for UPDATE (enables diff) */
+    originalContent?: Buffer;
+    /** File mode/permissions */
+    mode?: number;
+}
+/**
+ * Options for write operations.
+ */
+interface WriteOptions {
+    /** Write mode */
+    mode?: ModeType;
+    /** File permissions (e.g., 0o755) */
+    permissions?: number;
+}
+/**
+ * Options for creating a tree.
+ */
+interface CreateTreeOptions {
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /**
+     * Whether to follow symlinks when reading/writing files.
+     * When false, operations on symlinks will throw an error.
+     *
+     * @default true
+     */
+    followSymlinks?: boolean;
+}
+/**
+ * Options for committing changes.
+ */
+interface CommitOptions {
+    /** Dry run - don't actually write to disk */
+    dryRun?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Result of committing changes.
+ */
+interface CommitResult {
+    /** Number of files created */
+    created: number;
+    /** Number of files updated */
+    updated: number;
+    /** Number of files deleted */
+    deleted: number;
+    /** List of all changes applied */
+    changes: FileChange[];
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+/**
+ * Virtual file system tree interface.
+ * Transactional in-memory tree of pending file operations.
+ */
+interface Tree {
+    /** Workspace root path */
+    readonly root: string;
+    /**
+     * Read file contents.
+     *
+     * @returns Buffer if no encoding specified, string otherwise
+     */
+    read(filePath: string): Buffer | null;
+    /** Read file contents with encoding, returning string. */
+    read(filePath: string, encoding: BufferEncoding): string | null;
+    /**
+     * Write file contents.
+     * Creates parent directories if they don't exist.
+     */
+    write(filePath: string, content: Buffer | string, options?: WriteOptions): void;
+    /**
+     * Check if a file exists.
+     * Considers pending changes in the tree.
+     */
+    exists(filePath: string): boolean;
+    /**
+     * Delete a file or directory.
+     */
+    delete(filePath: string): void;
+    /**
+     * Rename/move a file or directory.
+     */
+    rename(from: string, to: string): void;
+    /**
+     * Check if path is a file (not directory).
+     */
+    isFile(filePath: string): boolean;
+    /**
+     * Check if path is a directory.
+     */
+    isDirectory(filePath: string): boolean;
+    /**
+     * Check if path is a symbolic link.
+     *
+     * @param filePath - Path to check
+     * @returns True if path is a symlink
+     */
+    isSymlink(filePath: string): boolean;
+    /**
+     * List children of a directory.
+     *
+     * @returns Array of child names (not full paths)
+     */
+    children(dirPath: string): string[];
+    /**
+     * Get list of pending changes.
+     */
+    listChanges(): FileChange[];
+    /**
+     * Clear all pending changes without committing.
+     * Discards all buffered modifications.
+     */
+    clearChanges(): void;
+    /**
+     * Change file permissions.
+     */
+    changePermissions(filePath: string, mode: number): void;
+    /**
+     * Transform file contents using a callback.
+     * Reads the file, applies transformation, and writes back.
+     *
+     * @param filePath - Path to file
+     * @param transform - Transformation function
+     * @throws {Error} If file doesn't exist
+     */
+    changeFile(filePath: string, transform: (content: Buffer) => Buffer): void;
+}
+/**
+ * A single line in a diff.
+ */
+interface DiffLine {
+    /** Type of line change */
+    type: 'add' | 'remove' | 'context';
+    /** Line number (in original for remove/context, in new for add) */
+    line: number;
+    /** Line content */
+    content: string;
+}
+/**
+ * Diff for a single file.
+ */
+interface FileDiff {
+    /** File path */
+    path: string;
+    /** Diff lines */
+    lines: DiffLine[];
+    /** Number of added lines */
+    additions: number;
+    /** Number of deleted lines */
+    deletions: number;
+}
+
+/**
+ * Options for diff generation.
+ */
+interface DiffOptions {
+    /**
+     * Number of context lines around changes.
+     *
+     * @default 3
+     */
+    contextLines?: number;
+}
+/**
+ * Generate a diff for a single file change.
+ *
+ * @example Generating a diff for a file change
+ * ```typescript
+ * const change: FileChange = {
+ *   path: 'src/app.ts',
+ *   type: 'UPDATE',
+ *   originalContent: Buffer.from('const x = 1;\n'),
+ *   content: Buffer.from('const x = 2;\n'),
+ * }
+ * const diff = generateDiff(change)
+ * // { path: 'src/app.ts', additions: 1, deletions: 1, lines: [...] }
+ * ```
+ *
+ * @param change - File change to diff
+ * @param options - Configuration for diff generation including context lines
+ * @returns FileDiff object
+ */
+declare function generateDiff(change: FileChange, options?: DiffOptions): FileDiff;
+/**
+ * Format a FileDiff as a unified diff string.
+ *
+ * @example Formatting a unified diff
+ * ```typescript
+ * const formatted = formatUnifiedDiff(diff)
+ * console.log(formatted)
+ * // --- a/src/app.ts
+ * // +++ b/src/app.ts
+ * // @@ -1,3 +1,3 @@
+ * //  const x = 1;
+ * // -const y = 2;
+ * // +const y = 3;
+ * //  const z = 4;
+ * ```
+ *
+ * @param diff - FileDiff to format
+ * @returns Unified diff string
+ */
+declare function formatUnifiedDiff(diff: FileDiff): string;
+/**
+ * Generate diffs for all changes in a tree.
+ *
+ * @example Generating diffs for all changes
+ * ```typescript
+ * const tree = createTree('/workspace')
+ * tree.write('new.txt', 'hello')
+ * tree.delete('old.txt')
+ *
+ * const diffs = generateAllDiffs(tree)
+ * for (const diff of diffs) {
+ *   console.log(formatUnifiedDiff(diff))
+ * }
+ * ```
+ *
+ * @param tree - Tree to generate diffs for
+ * @param options - Diff options
+ * @returns Array of FileDiff objects
+ */
+declare function generateAllDiffs(tree: Tree, options?: DiffOptions): FileDiff[];
+
+/**
+ * Commit buffered changes to disk.
+ *
+ * @param tree - Virtual file system tree with pending modifications
+ * @param options - Configuration for dry-run and verbosity
+ * @returns Result of the commit operation
+ *
+ * @example Committing changes to disk
+ * ```typescript
+ * import { createTree, commitChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('./my-project')
+ * tree.write('src/new-file.ts', 'export const hello = "world"')
+ *
+ * // Preview changes without writing
+ * const preview = commitChanges(tree, { dryRun: true })
+ * console.log('Would create:', preview.created, 'files')
+ *
+ * // Actually commit changes
+ * const result = commitChanges(tree)
+ * console.log('Created:', result.created, 'Updated:', result.updated)
+ * ```
+ */
+declare function commitChanges(tree: Tree, options?: CommitOptions): CommitResult;
+/**
+ * Discard all pending changes.
+ *
+ * @param tree - Virtual file system tree
+ *
+ * @example Rolling back pending changes
+ * ```typescript
+ * import { createTree, rollbackChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('/workspace')
+ * tree.write('new-file.ts', 'content')
+ * // Decide to abort - discard all pending changes
+ * rollbackChanges(tree)
+ * ```
+ */
+declare function rollbackChanges(tree: Tree): void;
+
+/**
+ * Create a virtual file system tree.
+ *
+ * @param root - Root directory path
+ * @param options - Tree creation options
+ * @returns A new Tree instance
+ * @throws {Error} If root doesn't exist or isn't a directory
+ *
+ * @example Creating a virtual tree
+ * ```typescript
+ * import { createTree } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('./my-project')
+ *
+ * // Read files from tree
+ * const content = tree.read('src/index.ts', 'utf-8')
+ *
+ * // Make changes (buffered in memory)
+ * tree.write('src/new-file.ts', 'export const x = 1')
+ *
+ * // List pending changes
+ * console.log(tree.listChanges())
+ * ```
+ */
+declare function createTree(root: string, options?: CreateTreeOptions): Tree;
+/**
+ * Create a tree from disk.
+ *
+ * Convenience alias for createTree.
+ *
+ * @param root - Root directory path
+ * @param options - Tree creation options
+ * @returns A new Tree instance backed by disk
+ *
+ * @example Creating a tree from disk
+ * ```typescript
+ * import { createTreeFromDisk } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTreeFromDisk('/path/to/project', { verbose: true })
+ * const files = tree.children('/src')
+ * ```
+ */
+declare function createTreeFromDisk(root: string, options?: CreateTreeOptions): Tree;
+
+/**
+ * Create a file system-backed tree implementation.
+ *
+ * Supports transactional modifications - all changes are buffered
+ * in memory and can be committed atomically or rolled back.
+ *
+ * @param root - Absolute path to the workspace root directory
+ * @param options - Configuration for verbose logging
+ * @returns A Tree instance
+ *
+ * @example Creating and using a file system tree
+ * ```typescript
+ * import { createFsTree, commitChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createFsTree('/workspace')
+ * tree.write('src/new-file.ts', 'export const value = 42')
+ * tree.delete('old-file.ts')
+ * commitChanges(tree) // Atomically apply all changes to disk
+ * ```
+ */
+declare function createFsTree(root: string, options?: CreateTreeOptions): Tree;
+
+export { Mode, commitChanges, createFsTree, createTree, createTreeFromDisk, formatUnifiedDiff, generateAllDiffs, generateDiff, rollbackChanges };
+export type { CommitOptions, CommitResult, CreateTreeOptions, DiffLine, DiffOptions, FileChange, FileDiff, ModeType, Tree, WriteOptions };

package/vfs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/project-scope/src/vfs/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/project-scope/src/vfs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACzC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3I,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA"}